agentfootprint/dist/esm/core/conversation.d.ts

The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.

/**
 * conversation — the refusals that guard a runner's per-instance state.
 *
 * Pattern: teaching refusal at a boundary (the shape `runInput` uses for a
 *          caller's message, applied to a caller's TIMING).
 * Role:    core/ layer. An `Agent` keeps the last run's executor, run context,
 *          answer and pause on ITSELF — that is what makes `checkpoint()`,
 *          `getLastSnapshot()` and `followUp()` possible at all. Those fields
 *          have exactly one owner at a time, and until 9.2.0 nothing said so.
 * Emits:   N/A — these fire before a run starts.
 *
 * ## Why these are refusals and not warnings
 *
 * Both shapes below used to SUCCEED, which is the entire problem. Two `run()`
 * calls overlapping on one Agent both resolved with plausible answers, and the
 * per-instance state afterwards belonged to whichever finished last: the
 * conversation `checkpoint()` handed back was the other run's, the snapshot
 * `getLastSnapshot()` served was the other run's, and every event carried the
 * other run's meta. That is not concurrency, it is corruption — and nothing in
 * the recording said so, because each run's own trace looked perfect.
 *
 * A message sent while a person still owes the agent an answer used to start a
 * fresh run and silently abandon the pending question. A consent gate that can
 * be walked around by sending another message is not a consent gate.
 *
 * Neither refusal is new policy. `standingAgent` has refused both since it
 * existed (it serializes runs globally and calls that "a correctness
 * requirement rather than a tuning choice", and answers a message that arrives
 * mid-question with `AwaitingDecisionError`), and `recordedChat.send` refuses
 * an overlapping turn in the same words. 9.2.0 moves the guarantee from the
 * compositions down to the primitive, so it holds however you drive it.
 *
 * The names are deliberately NOT the hosting ones. `hosting/errors.ts` already
 * owns `ConcurrentRunError` and `AwaitingDecisionError`, both of which carry a
 * `sessionId` and speak about a session; core has no sessions, and two classes
 * sharing one name across two doors is the duplicate-type hazard this codebase
 * has fixed before.
 */
/**
 * Thrown when `run()` / `resume()` is called on a runner that is already
 * running.
 *
 * One instance answers one turn at a time. To run two turns at once, build two
 * agents — a chart is built once per instance and instances are cheap — or put
 * the turns behind `standingAgent({ onConcurrentInvoke: 'enqueue' })`, which
 * queues them.
 *
 * @example
 * ```ts
 * // Refused: both would write the same instance's last-run state.
 * await Promise.all([agent.run({ message: 'a' }), agent.run({ message: 'b' })]);
 *
 * // Fine: two instances, two sets of state.
 * await Promise.all([agentA.run({ message: 'a' }), agentB.run({ message: 'b' })]);
 * ```
 */
export declare class RunInFlightError extends Error {
    readonly code: "ERR_RUN_IN_FLIGHT";
    /** The runner that is busy, by its configured id. */
    readonly agentId: string;
    /** The run already in flight, so a log line can be joined to its trace. */
    readonly activeRunId: string;
    constructor(door: string, agentId: string, activeRunId: string);
}
/**
 * Thrown when a new message is sent to an agent whose last run PAUSED to ask a
 * person something, and that question has not been answered.
 *
 * The pause is not a failure and not a stale flag — it is unfinished work with
 * a person on the other end. Answer it with `resume(checkpoint, decision)`, or
 * say plainly that it is being dropped with `abandonPause()`; both are visible
 * in the record, and silently starting a fresh run was not.
 */
export declare class PendingQuestionError extends Error {
    readonly code: "ERR_PENDING_QUESTION";
    /** The tool that asked, when the pause named one. */
    readonly toolName?: string;
    /** The id of the tool call that asked, for joining back to the trace. */
    readonly toolCallId?: string;
    constructor(door: string, pending: {
        toolName?: string;
        toolCallId?: string;
        question?: string;
    });
}
/**
 * Thrown by `resume(checkpoint, input, options)` when the run would carry two
 * identities — refused before anything runs:
 *  - `options.identity` names an identity other than the one the run's memory
 *    namespace and credentials are restored with (`scope.runIdentity`, whatever
 *    its source) — including an OWNERLESS pause (the per-run default or the
 *    session rung) resumed by a named person;
 *  - the checkpoint's own fields disagree (a session-rung marker on an
 *    identity that carries a person).
 *
 * The ownerless case is the fail-closed reading of an open owner question; a
 * later release may relax it behind an explicit opt-in, never by default.
 *
 * One run never carries two identities. The resumed run keeps the paused run's
 * memory namespace and credential identity (`scope.runIdentity`, restored from
 * the checkpoint — a resume never re-seeds), so honouring a different caller
 * would give the run one person's memory and vault and another person's
 * `ctx.identity`, `EventMeta.principal` and stored ownership. Ownership is
 * derived from the run and never moved; the same law, and the same `code`, as
 * the hosting door's `SessionOwnershipConflictError`.
 *
 * Neither identity is named in the message: an error is read by whoever
 * provoked it. Nothing has run and no state has moved when it is thrown.
 */
export declare class ResumeIdentityConflictError extends Error {
    readonly code: "ERR_SESSION_OWNERSHIP_CONFLICT";
    constructor();
}
/** Why a resume could not carry its paused run's redaction — see `ResumeRedactionError`. */
export type ResumeRedactionReason = 'unreadable' | 'missing' | 'unknown-pattern';
/**
 * Thrown by `resume(checkpoint, input, options)` when the paused run's
 * redaction cannot be carried into the resumed leg — refused before anything
 * runs, so a leg its policy could not keep covered never starts:
 *  - `'unreadable'` — the checkpoint's `runRedaction` (the policy the paused
 *    run was covered by, as plain data) is not one this library wrote;
 *  - `'missing'` — the checkpoint says its run kept values out of its records
 *    (footprintjs's `redactionMarks`: the names it masked) but carries no
 *    policy. Every leg of a covered run writes its policy into its checkpoint,
 *    so this one was altered; a `redact` passed to the resume cannot stand in
 *    for the policy the run was covered by, so it is refused all the same;
 *  - `'unknown-pattern'` — the carried policy names a pattern this side does
 *    not hold. A pattern is never compiled from a checkpoint (one built to hang
 *    the matcher could come back from storage someone else controls): a
 *    carried pattern is a reference to one the agent declares, the library's
 *    vocabulary holds, or the resume names — pass the run's `redact` to
 *    `resume(checkpoint, input, { redact })` when the run was handed one.
 *
 * Every way, the resumed leg would write what the paused leg kept out into
 * every record of its own. No policy, pattern, name or value appears in the
 * message.
 */
export declare class ResumeRedactionError extends Error {
    readonly code: "ERR_RESUME_REDACTION";
    readonly reason: ResumeRedactionReason;
    constructor(reason: ResumeRedactionReason);
}
/**
 * Why `followUp()` found no conversation to continue.
 *
 * - `'never-run'` — no run on this agent got past input admission yet
 *   (before the first run, or when the first turn was refused).
 * - `'last-run-unfinished'` — the last run ended without an answer (it threw);
 *   its conversation rides `RunCheckpointError.checkpoint`.
 * - `'last-input-refused'` — input middleware refused the last run's message.
 *   A refusal raises `MessageDeniedError`, which carries no checkpoint: the
 *   refused attempt admitted no conversation, so the one to continue is the
 *   checkpoint taken after an earlier ACCEPTED run.
 */
export type NoConversationReason = 'never-run' | 'last-run-unfinished' | 'last-input-refused';
/**
 * Thrown by `followUp()` when there is no conversation to follow up on.
 *
 * `followUp()` continues THIS agent's own last completed run. Before the first
 * one there is nothing to continue, and a "follow-up" that quietly became a
 * first turn would be the very confusion the door exists to remove.
 * `reason` says which of those it was, so a caller can branch on it.
 */
export declare class NoConversationError extends Error {
    readonly code: "ERR_NO_CONVERSATION";
    readonly reason: NoConversationReason;
    constructor(door: string, reason: NoConversationReason);
}