agentfootprint 9.0.0 → 9.2.0

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).