agentfootprint 9.1.0 → 9.2.0

package/dist/core/conversation.js

@@ -0,0 +1,139 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NoConversationError = exports.PendingQuestionError = exports.RunInFlightError = void 0;
+/**
+ * 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' })]);
+ * ```
+ */
+class RunInFlightError extends Error {
+    code = 'ERR_RUN_IN_FLIGHT';
+    /** The runner that is busy, by its configured id. */
+    agentId;
+    /** The run already in flight, so a log line can be joined to its trace. */
+    activeRunId;
+    constructor(door, agentId, activeRunId) {
+        super(`${door}: this agent is already running (run '${activeRunId}'). One instance answers one ` +
+            `turn at a time — its last executor, run context, answer and pause all live on the ` +
+            `instance, so two overlapping runs would each finish having overwritten the other's. ` +
+            `Both would return a plausible answer and checkpoint() would then hand back whichever ` +
+            `finished last, which is why this is refused rather than left to look like it worked. ` +
+            `Await the run in flight, build a second Agent for the second turn (charts are ` +
+            `built per instance and instances are cheap), or serve the agent through ` +
+            `standingAgent({ onConcurrentInvoke: 'enqueue' }) to queue turns behind each other.`);
+        this.name = 'RunInFlightError';
+        this.agentId = agentId;
+        this.activeRunId = activeRunId;
+    }
+}
+exports.RunInFlightError = RunInFlightError;
+/**
+ * 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.
+ */
+class PendingQuestionError extends Error {
+    code = 'ERR_PENDING_QUESTION';
+    /** The tool that asked, when the pause named one. */
+    toolName;
+    /** The id of the tool call that asked, for joining back to the trace. */
+    toolCallId;
+    constructor(door, pending) {
+        const asked = pending.toolName !== undefined
+            ? `'${pending.toolName}'${pending.toolCallId ? ` (call ${pending.toolCallId})` : ''}`
+            : 'a tool';
+        const quoted = pending.question !== undefined ? ` It asked: "${pending.question}"` : '';
+        super(`${door}: this agent's last run paused to ask a person something and is still waiting. ` +
+            `${asked} raised the question and nothing has answered it.${quoted} Answer it with ` +
+            `agent.resume(outcome.checkpoint, decision) — that continues the paused run from where ` +
+            `it stopped, with no earlier tool re-executed. If the question really is being dropped, ` +
+            `call agent.abandonPause() first and then run() again: a pending question that a later ` +
+            `message silently discards is a consent gate anyone can walk around.`);
+        this.name = 'PendingQuestionError';
+        if (pending.toolName !== undefined)
+            this.toolName = pending.toolName;
+        if (pending.toolCallId !== undefined)
+            this.toolCallId = pending.toolCallId;
+    }
+}
+exports.PendingQuestionError = PendingQuestionError;
+/**
+ * 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.
+ */
+class NoConversationError extends Error {
+    code = 'ERR_NO_CONVERSATION';
+    constructor(door, reason) {
+        super(reason === 'never-run'
+            ? `${door}: this agent has not completed a run, so there is no conversation to ` +
+                `continue. Start it with agent.run({ message }) — the first turn is a run; every ` +
+                `turn after it is a followUp(). To continue a conversation this PROCESS did not ` +
+                `have (a stored one, or one from another instance), pass it explicitly: ` +
+                `agent.run({ message, continueFrom: storedConversation }).`
+            : `${door}: this agent's last run did not finish with an answer, so there is no ` +
+                `conversation to continue yet. A failed run's conversation is carried by ` +
+                `RunCheckpointError.checkpoint — catch it and pass that to ` +
+                `run({ message, continueFrom }) or resumeOnError(checkpoint).`);
+        this.name = 'NoConversationError';
+    }
+}
+exports.NoConversationError = NoConversationError;
+//# sourceMappingURL=conversation.js.map

package/dist/core/conversation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation.js","sourceRoot":"","sources":["../../src/core/conversation.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;;;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAa,gBAAiB,SAAQ,KAAK;IAChC,IAAI,GAAG,mBAA4B,CAAC;IAC7C,qDAAqD;IAC5C,OAAO,CAAS;IACzB,2EAA2E;IAClE,WAAW,CAAS;IAE7B,YAAY,IAAY,EAAE,OAAe,EAAE,WAAmB;QAC5D,KAAK,CACH,GAAG,IAAI,yCAAyC,WAAW,+BAA+B;YACxF,oFAAoF;YACpF,sFAAsF;YACtF,uFAAuF;YACvF,uFAAuF;YACvF,gFAAgF;YAChF,0EAA0E;YAC1E,oFAAoF,CACvF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IACjC,CAAC;CACF;AAtBD,4CAsBC;AAED;;;;;;;;GAQG;AACH,MAAa,oBAAqB,SAAQ,KAAK;IACpC,IAAI,GAAG,sBAA+B,CAAC;IAChD,qDAAqD;IAC5C,QAAQ,CAAU;IAC3B,yEAAyE;IAChE,UAAU,CAAU;IAE7B,YACE,IAAY,EACZ,OAAsE;QAEtE,MAAM,KAAK,GACT,OAAO,CAAC,QAAQ,KAAK,SAAS;YAC5B,CAAC,CAAC,IAAI,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU,OAAO,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;YACrF,CAAC,CAAC,QAAQ,CAAC;QACf,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,eAAe,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QACxF,KAAK,CACH,GAAG,IAAI,iFAAiF;YACtF,GAAG,KAAK,oDAAoD,MAAM,kBAAkB;YACpF,wFAAwF;YACxF,yFAAyF;YACzF,wFAAwF;YACxF,qEAAqE,CACxE,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS;YAAE,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACrE,IAAI,OAAO,CAAC,UAAU,KAAK,SAAS;YAAE,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IAC7E,CAAC;CACF;AA5BD,oDA4BC;AAED;;;;;;GAMG;AACH,MAAa,mBAAoB,SAAQ,KAAK;IACnC,IAAI,GAAG,qBAA8B,CAAC;IAE/C,YAAY,IAAY,EAAE,MAA2C;QACnE,KAAK,CACH,MAAM,KAAK,WAAW;YACpB,CAAC,CAAC,GAAG,IAAI,uEAAuE;gBAC5E,kFAAkF;gBAClF,iFAAiF;gBACjF,yEAAyE;gBACzE,2DAA2D;YAC/D,CAAC,CAAC,GAAG,IAAI,wEAAwE;gBAC7E,0EAA0E;gBAC1E,4DAA4D;gBAC5D,8DAA8D,CACrE,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAlBD,kDAkBC"}

package/dist/core/runCheckpoint.js

@@ -55,7 +55,7 @@
  *          DFS stage).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.classifyFailurePhase = exports.validateCheckpoint = exports.buildCheckpoint = exports.RunCheckpointError = void 0;
+exports.classifyFailurePhase = exports.validateCheckpoint = exports.buildCheckpoint = exports.assertContinuable = exports.ConversationMismatchError = exports.RunCheckpointError = void 0;
 /**
  * Thrown by `agent.run()` when a fault occurs mid-run. Carries the
  * underlying error AND the last-known-good checkpoint. Catch this
@@ -101,6 +101,55 @@ class RunCheckpointError extends Error {
     }
 }
 exports.RunCheckpointError = RunCheckpointError;
+/**
+ * Thrown when a stored conversation is handed to an agent that is provably
+ * not the one that recorded it (9.2.0).
+ *
+ * Raised only when BOTH sides named themselves with an explicit
+ * `Agent.create({ id })` and the two names differ — see
+ * {@link AgentRunCheckpoint.agent} for why that is the whole of the rule.
+ * An agent that gained a tool, changed its prompt or moved to a new model
+ * since the conversation was stored is NOT this error; continuing across a
+ * deploy is the ordinary case and must keep working.
+ */
+class ConversationMismatchError extends Error {
+    code = 'ERR_CONVERSATION_MISMATCH';
+    /** The id stamped on the stored conversation. */
+    storedAgentId;
+    /** The id of the agent it was handed to. */
+    agentId;
+    constructor(door, storedAgentId, agentId) {
+        super(`${door}: this conversation was recorded by agent '${storedAgentId}' and was handed to ` +
+            `agent '${agentId}'. Both agents named themselves with Agent.create({ id }), and the ` +
+            `names differ — so this is one agent answering another one's conversation, not a ` +
+            `deploy that changed. Continue it on the agent whose id is '${storedAgentId}', or, if ` +
+            `handing conversations between these two really is intended, give them the same id. ` +
+            `(An agent that merely gained a tool, changed its prompt or moved model since the ` +
+            `conversation was stored keeps the same id and is never refused here.)`);
+        this.name = 'ConversationMismatchError';
+        this.storedAgentId = storedAgentId;
+        this.agentId = agentId;
+    }
+}
+exports.ConversationMismatchError = ConversationMismatchError;
+/**
+ * Refuse a stored conversation that provably belongs to a different agent.
+ *
+ * Both-sides-named-themselves, or nothing happens. `storedId` is absent on
+ * every conversation written before 9.2.0 and on every agent that never chose
+ * an id; `agentId` is undefined for the same reason on the reading side.
+ *
+ * @internal
+ */
+function assertContinuable(checkpoint, agentId, door) {
+    const storedId = checkpoint.agent?.id;
+    if (storedId === undefined || agentId === undefined)
+        return;
+    if (storedId === agentId)
+        return;
+    throw new ConversationMismatchError(door, storedId, agentId);
+}
+exports.assertContinuable = assertContinuable;
 /**
  * The human half of `failurePoint`, as one clause.
  *
@@ -135,7 +184,14 @@ function buildCheckpoint(tracker, failurePoint,
  * and a fold's span is committed state — and because the same reader then
  * serves both checkpoint carriers, so neither can lose what the other keeps.
  */
-folded) {
+folded, 
+/**
+ * Who the run was for and which agent ran it — the two fields that make a
+ * stored conversation continuable rather than merely readable (9.2.0).
+ * Both are absent unless the caller chose them explicitly; see
+ * {@link AgentRunCheckpoint.identity} and {@link AgentRunCheckpoint.agent}.
+ */
+owner) {
     return {
         version: 1,
         runId: tracker.runId,
@@ -145,6 +201,8 @@ folded) {
         checkpointedAt: Date.now(),
         ...(failurePoint && { failurePoint }),
         ...(folded !== undefined && folded.length > 0 && { folded }),
+        ...(owner?.identity !== undefined && { identity: owner.identity }),
+        ...(owner?.agentId !== undefined && { agent: { id: owner.agentId } }),
     };
 }
 exports.buildCheckpoint = buildCheckpoint;

package/dist/core/runCheckpoint.js.map

@@ -1 +1 @@
-{"version":3,"file":"runCheckpoint.js","sourceRoot":"","sources":["../../src/core/runCheckpoint.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runCheckpoint.js","sourceRoot":"","sources":["../../src/core/runCheckpoint.ts"],"names":[],"mappings":"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"}

package/dist/esm/core/Agent.d.ts

@@ -20,6 +20,8 @@ import { type RunnerPauseOutcome } from './pause.js';
 import type { WindowStrategy } from './agent/window/strategy.js';
 import { type CheckInBuilderOptions } from './checkin.js';
 import type { MemoryDefinition } from '../memory/define.types.js';
+import type { MemoryIdentity } from '../memory/identity/types.js';
+import type { SelfExplainBinding } from '../lib/trace-toolpack/selfExplain.js';
 import type { Injection, InjectionContext } from '../lib/injection-engine/types.js';
 import type { CursorMove, EntryScoring } from '../lib/injection-engine/skillGraph.js';
 import { type ResolvedOutputFallback } from './outputFallback.js';
@@ -55,6 +57,19 @@ export interface AgentRunOptions extends RunOptions {
     correlationId?: string;
     /** OTEL-style trace id — forwarded onto every emitted event's `EventMeta.traceId`. Falls back to `options.env?.traceId` when unset. */
     traceId?: string;
+    /**
+     * Who this run is for — the same tuple as `run({ identity })`, reachable
+     * from the doors whose input is a stored conversation rather than a
+     * message bag: `resumeOnError(checkpoint, { identity })` and
+     * `followUp(message, { identity })` (9.2.0).
+     *
+     * Before this existed, `resumeOnError` could not carry an identity at all,
+     * so every continued turn silently re-namespaced its memory under a fresh
+     * runId. Omitted, the conversation's own stored `identity` is used; given,
+     * it wins. On `run()` this is a second spelling of `run({ identity })` and
+     * the one on the input wins, since that is where the caller looked first.
+     */
+    identity?: MemoryIdentity;
 }
 export declare class Agent extends RunnerBase<AgentInput, AgentOutput> {
     readonly name: string;
@@ -245,6 +260,28 @@ export declare class Agent extends RunnerBase<AgentInput, AgentOutput> {
      *  kept here rather than read back from the recording. Undefined after a run
      *  that failed or paused. */
     private lastRunAnswer?;
+    /** The id the CONSUMER chose, or undefined when they took the default.
+     *  `this.id` cannot answer that question — it is `'agent'` either way — and
+     *  the stored-conversation fingerprint refuses only on ids somebody picked
+     *  (see `AgentRunCheckpoint.agent`). */
+    private readonly explicitId?;
+    /** The identity the caller gave the last run, or undefined when they gave
+     *  none. Only an EXPLICIT identity is carried onto `checkpoint()`: the
+     *  default is derived from a runId, and storing that would pin a whole
+     *  conversation to the id of the one run that started it. */
+    private lastRunIdentity?;
+    /** The run in flight, by id — the whole of the one-turn-at-a-time guard.
+     *  Set before the executor is built and cleared in `finally`, so a run that
+     *  throws does not leave the agent permanently refusing. */
+    private inFlightRunId?;
+    /** The question a person still owes this agent an answer to. Set when a run
+     *  ends paused, cleared by `resume()`, `abandonPause()`, or a run that
+     *  completes. Read by the `run()` guard — see `PendingQuestionError`. */
+    private pendingQuestion?;
+    /** The `.selfExplain()` binding, when the builder mounted one. Held so
+     *  `canExplain()` can answer the same question the trace tools answer, from
+     *  the same fact. Undefined on every agent that never called `.selfExplain()`. */
+    private selfExplainBinding?;
     /**
      * Optional `ToolProvider` set via the builder's `.toolProvider()`.
      * When present, the Tools slot subflow consults it per iteration
@@ -309,9 +346,17 @@ export declare class Agent extends RunnerBase<AgentInput, AgentOutput> {
      * prop) so consumers can scrub the execution timeline post-run without
      * threading a recorder through the call site.
      *
-     * Returns `undefined` before the first run completes. Returns the
-     * snapshot of the most recent run on every call after — including
-     * across multiple turns of the same Agent instance.
+     * `undefined` until a run has STARTED. After that it is the most recent
+     * run's snapshot — including across multiple turns of the same instance.
+     *
+     * **It is LIVE during a run, not a completed-runs-only view.** The executor
+     * is assigned at run start, so calling this from an event listener, a tool,
+     * or any other mid-run vantage point returns the IN-FLIGHT run, partially
+     * filled. That is deliberate (Lens scrubs a running agent through it), and
+     * it is why `.selfExplain()` captures at the terminal flush instead of
+     * resolving through this: evidence that is supposed to describe a FINISHED
+     * turn cannot be read from a getter that also answers about an unfinished
+     * one.
      */
     getLastSnapshot(): RuntimeSnapshot | undefined;
     /**
@@ -383,7 +428,112 @@ export declare class Agent extends RunnerBase<AgentInput, AgentOutput> {
      * pauses (use `run()` directly when pauses are expected).
      */
     runTyped<T = unknown>(input: AgentInput | string, options?: AgentRunOptions): Promise<T>;
+    /**
+     * Answer one turn.
+     *
+     * **`run()` is ONE turn, and it starts a new conversation every time.** The
+     * chart seeds its history from this call's `message` alone, so a second
+     * `run()` on the same agent does not continue the first: the model is shown
+     * one user message and will honestly tell your user it has not spoken to
+     * them before. That is deliberate — a primitive that quietly accumulated
+     * state across calls could never be used for one-shot work, and a hidden
+     * transcript is the most expensive thing an agent can carry.
+     *
+     * To continue a conversation, name it:
+     *
+     *   - `agent.followUp(message)` — continue THIS agent's own last completed
+     *     run. The one-liner, and what most callers want.
+     *   - `run({ message, continueFrom })` — continue a conversation you are
+     *     holding: `agent.checkpoint()` from an earlier turn, persisted anywhere
+     *     and handed back. Works across a restart, a deploy, or a different
+     *     machine, and is what `standingAgent` uses per session.
+     *
+     * Passing the same `identity.conversationId` to two `run()` calls does NOT
+     * continue anything — see {@link AgentInput.identity}. What a registered
+     * memory adds is *recall* of prior turns into the system-prompt slot, which
+     * is a different thing from the conversation itself.
+     *
+     * Two refusals guard the per-instance state this agent keeps; both replace
+     * behavior that used to succeed while quietly being wrong (9.2.0):
+     * {@link RunInFlightError} when a run is already in flight, and
+     * {@link PendingQuestionError} when the last run paused to ask a person
+     * something that nobody has answered.
+     *
+     * @example  One turn, then a follow-up
+     * ```ts
+     * await agent.run({ message: 'Book me a table for two.' });
+     * await agent.followUp('Make it three.');       // remembers the table
+     * ```
+     */
     run(input: AgentInput | string, options?: AgentRunOptions): Promise<AgentOutput | RunnerPauseOutcome>;
+    /**
+     * Continue this agent's own last completed conversation.
+     *
+     * The one-liner for turn two and after. `run()` is one turn and starts a new
+     * conversation each time (see {@link Agent.run}); this reads the
+     * conversation off the last completed run, appends `message` as the next
+     * user turn, and runs from there — so the model sees what was actually said.
+     *
+     * Sugar over `run({ message, continueFrom: this.checkpoint() })` and nothing
+     * more: one restoration path, so the convenience cannot drift from the
+     * mechanism. Reach for `run({ continueFrom })` directly when the
+     * conversation comes from somewhere other than this instance's last run — a
+     * store, another process, a different machine.
+     *
+     * Refuses rather than guessing: {@link NoConversationError} when this agent
+     * has no completed run to continue (a "follow-up" that quietly became a
+     * first turn would be exactly the confusion this door exists to remove),
+     * and — through `run()` — {@link PendingQuestionError} when the last run
+     * paused to ask a person something, because a pause has its own door:
+     * `resume(checkpoint, decision)`.
+     *
+     * The conversation grows every turn and nothing here trims it; bounding what
+     * the model is shown is `.window()` / `.compaction()` / `.memory()`, not a
+     * silent cap on the way through.
+     *
+     * @example
+     * ```ts
+     * await agent.run({ message: 'Book me a table for two.' });
+     * await agent.followUp('Make it three.');
+     * await agent.followUp('And move it to 8pm.');
+     * ```
+     */
+    followUp(message: string, options?: AgentRunOptions): Promise<AgentOutput | RunnerPauseOutcome>;
+    /**
+     * Drop the question this agent's last run paused to ask, on the record.
+     *
+     * A paused run is waiting on a person. Sending a different message while one
+     * is outstanding is refused ({@link PendingQuestionError}) because silently
+     * discarding a pending question makes a consent gate something any later
+     * message can walk around. When the question really is being dropped —
+     * the user changed the subject, the session timed out, the approval is no
+     * longer wanted — say so with this, and the next `run()` proceeds.
+     *
+     * Returns what was dropped (`undefined` when nothing was pending), so a
+     * caller can log or audit the abandonment rather than perform it blind. It
+     * does not touch the paused run's checkpoint: if you still hold that, it
+     * remains resumable.
+     */
+    abandonPause(): {
+        readonly toolName?: string;
+        readonly toolCallId?: string;
+        readonly question?: string;
+    } | undefined;
+    /**
+     * Whether {@link Agent.selfExplain}'s why-questions have a run to answer
+     * from right now.
+     *
+     * `false` for two different reasons, both honest: this agent was not built
+     * with `.selfExplain()`, or it was and no turn has completed yet (evidence
+     * binds at the END of a run, never to the one in flight). Either way there
+     * is nothing to explain, which is what a caller routing a why-question needs
+     * to know before it routes.
+     *
+     * The model is told the same thing by the same fact — the trace tools answer
+     * "No completed run is available yet" and the skill body says to say so
+     * plainly. This is that answer, for the program.
+     */
+    canExplain(): boolean;
     /**
      * Resume an agent run from a checkpoint produced by a prior
      * `RunCheckpointError`. Unlike `agent.resume()` (which takes a
@@ -429,6 +579,13 @@ export declare class Agent extends RunnerBase<AgentInput, AgentOutput> {
      * ```
      */
     resumeOnError(checkpoint: AgentRunCheckpoint | unknown, options?: AgentRunOptions): Promise<AgentOutput | RunnerPauseOutcome>;
+    /**
+     * Which identity a continued turn runs under: the caller's if they named
+     * one, otherwise the conversation's own.
+     *
+     * @internal
+     */
+    private identityFor;
     /**
      * Install a per-run checkpoint tracker. Listens for the agent's
      * own iteration_end events on `this.dispatcher` and snapshots the
@@ -493,6 +650,64 @@ export declare class Agent extends RunnerBase<AgentInput, AgentOutput> {
      * @internal
      */
     private foldedSpansOf;
+    /**
+     * The two owner facts every conversation carrier stamps — who the run was
+     * for, and which agent ran it (9.2.0).
+     *
+     * One reader for `checkpoint()` and the crash checkpoint, the same rule
+     * `foldedSpansOf` follows: a fact kept on one carrier and lost on the other
+     * is worse than a fact kept on neither. Both are absent unless the caller
+     * chose them, which is what keeps the fingerprint refusal narrow and the
+     * default `conversationId` out of storage.
+     *
+     * @internal
+     */
+    private conversationOwner;
+    /**
+     * Restore a stored conversation onto the side channel `seed` reads.
+     *
+     * THE one restoration path — `run({ continueFrom })` and `resumeOnError()`
+     * both come through here, so the conversation door and the error door cannot
+     * disagree about what continuing means. It checks the agent fingerprint,
+     * restores history + folded spans, and adopts the conversation's identity so
+     * the continued turn writes its memory where the earlier turns are.
+     *
+     * `appendMessage` is the difference between the two callers, and it is the
+     * whole difference. Continuing a conversation ADDS this turn's user message
+     * to the stored history; resuming after an error does NOT, because there the
+     * message is already the last user turn in that history and appending it
+     * would ask the same question twice.
+     *
+     * @internal
+     */
+    private applyContinuation;
+    /** One turn at a time — see `RunInFlightError`. @internal */
+    private assertNotRunning;
+    /** A person's unanswered question outranks a new message — see
+     *  `PendingQuestionError`. @internal */
+    private assertNoPendingQuestion;
+    /**
+     * Remember (or forget) the question this run ended on.
+     *
+     * A paused outcome sets it; anything else clears it, because a run that
+     * reached an answer has no outstanding question by definition. Reads the
+     * same `pauseData` fields `standingAgent.describePause` reads — the tool
+     * name and question the dispatch loop stamped — and invents nothing.
+     *
+     * @internal
+     */
+    private recordPendingQuestion;
+    /**
+     * Hand the `.selfExplain()` binding to the agent that owns it.
+     *
+     * Called once by `AgentBuilder.build()`, immediately after `bindTo`. The
+     * binding stays the tool provider's to read; the Agent holds it only so
+     * `canExplain()` answers from the same fact the trace tools answer from,
+     * rather than from a second guess about whether a run has completed.
+     *
+     * @internal
+     */
+    bindSelfExplain(binding: SelfExplainBinding): void;
     /**
      * Refuse, at run start, any declared messages-slot role this provider
      * cannot carry inside its message list (7.21, D2).