@dudousxd/nestjs-agent-core 0.25.0 → 0.26.0

package/dist/processors-Bf1fYLbY.d.cts

@@ -0,0 +1,160 @@
+import { M as ModelMessage, A as Actor, d as ToolCallRequest } from './tool-BXKG2xSm.cjs';
+
+/**
+ * The two seams that see a turn's traffic to and from the model: an {@link InputProcessor} rewrites
+ * the prompt on its way out, an {@link OutputProcessor} inspects the answer on its way back and may
+ * redact, replace or refuse it. Wire them as `AgentLoopDeps.inputProcessors` /
+ * `outputProcessors`, or via `AgentModule.forRoot({ inputProcessors, outputProcessors })`.
+ *
+ * WHAT THESE ARE NOT: a second way to decide what enters the context. `HistoryPolicy` owns
+ * SELECTION — which of the thread's messages ride into the turn, and what stands in for the rest.
+ * Processors run on whatever selection produced and own TRANSFORMATION — what those messages say.
+ * The distinction is load-bearing rather than stylistic: selection is contractually pure and is what
+ * the `load:thread` checkpoint records, so it bounds the journal as well as the prompt, while a
+ * processor is allowed to call a model, runs in a checkpoint of its own per step, and rewrites a
+ * DERIVED prompt that never becomes the thread's own memory of what was said. Splitting the same
+ * decision across both means neither can be reasoned about alone, and the cheap one stops being the
+ * whole answer to "why did this turn cost that much".
+ */
+
+/** Which turn, and which model step of it, a processor is looking at. */
+interface ProcessorContext {
+    threadId: string;
+    actor: Actor;
+    /** The agent running this turn. Undefined → the default agent. */
+    agentName?: string;
+    /** 0-based model step within the run — the same index the `llm:<step>` checkpoint carries. */
+    step: number;
+}
+/** Everything the model is about to be sent, as the previous processor in the chain left it. */
+interface ProcessedPrompt {
+    /** The composed system prompt (agent base + contributors + any injected retrieval block). */
+    system: string;
+    /** The turn's messages, oldest-first, already through the history ceiling. */
+    messages: ModelMessage[];
+}
+/**
+ * Rewrites the prompt before each model call of a turn — masking identifiers, stamping a policy
+ * preamble, collapsing an oversized tool result. Runs on EVERY step, not once per run, because the
+ * transcript grows between steps: a redactor that only saw the opening prompt would wave through
+ * whatever a tool result carried back.
+ *
+ * Runs inside the loop's `process:input:<step>` checkpoint and its result is journaled, so a
+ * processor may call a model or hit the network — a resumed run reads back the prompt the suspended
+ * attempt built rather than composing a different one.
+ */
+interface InputProcessor {
+    /** Identifies this processor in a failure. Keep it stable — it is user-visible on an error. */
+    readonly name: string;
+    process(prompt: ProcessedPrompt, ctx: ProcessorContext): ProcessedPrompt | Promise<ProcessedPrompt>;
+}
+/** One model step's answer, as the previous processor in the chain left it. */
+interface ModelAnswer {
+    /** The assembled assistant text for this step. */
+    text: string;
+    /** The tool calls the same step asked for. Read-only context — a processor cannot change them. */
+    toolCalls: readonly ToolCallRequest[];
+}
+/**
+ * What an {@link OutputProcessor} decided. `pass` hands the text to the next processor unchanged;
+ * `replace` hands it on rewritten (a redaction is a replacement); `reject` ends the chain AND the
+ * run — the text is never streamed, never persisted, and the caller gets an
+ * {@link OutputRejectedError} rather than an answer.
+ */
+type OutputVerdict = {
+    action: 'pass';
+} | {
+    action: 'replace';
+    text: string;
+} | {
+    action: 'reject';
+    reason: string;
+};
+/**
+ * Characters an incremental gate keeps holding at the end of the transformed answer, when a
+ * processor declares {@link IncrementalGating} without naming its own window. Wide enough for the
+ * patterns a redactor is usually written against — an SSN, an email address, a card number — and
+ * deliberately not wider: the window IS the answer's minimum latency tail, since those characters
+ * are only released once the whole-answer pass runs.
+ */
+declare const DEFAULT_INCREMENTAL_LOOKBACK_CHARS = 64;
+/**
+ * A processor's statement that its verdict on a PREFIX of an answer is worth acting on, which is
+ * what lets the loop release that prefix to the reader instead of holding the whole answer.
+ *
+ * Declaring it is a promise about every prefix `P` of the final answer, and the loop takes it at
+ * face value on the streaming path:
+ *
+ * 1. REJECTION IS PREFIX-DECIDABLE. The refusal this processor would return for the whole answer is
+ *    already returned for the first prefix that contains the reason. A refusal that only emerges
+ *    from the complete answer still fails the run, but by then the reader has seen a prefix — there
+ *    is no un-sending bytes, and that is the cost of opting in.
+ * 2. REPLACEMENT IS PREFIX-STABLE UP TO THE WINDOW. Once a character of `process(P)`'s output is
+ *    more than {@link lookbackChars} from the end of that output, it never changes as `P` grows.
+ *
+ * A broken second promise is caught, not tolerated: the whole-answer pass stays authoritative, and
+ * the loop raises a `ProcessorFailedError` when its result is not an extension of what the chain
+ * already released. So a window too short for a pattern fails loudly rather than streaming the text
+ * it was supposed to redact.
+ */
+interface IncrementalGating {
+    /**
+     * How many characters of this processor's own output stay held back. Undefined →
+     * {@link DEFAULT_INCREMENTAL_LOOKBACK_CHARS}. Set it to the length of the longest pattern the
+     * processor can act on — anything shorter is a run that fails on the pattern it was written for.
+     */
+    readonly lookbackChars?: number;
+}
+/**
+ * Inspects each model step's answer before anything downstream sees it — before it reaches the live
+ * stream, before it is persisted, before it becomes the next step's context.
+ *
+ * Gating an answer and streaming it as it is generated are mutually exclusive, so registering ANY
+ * output processor switches the turn's model call off the run's sink: nothing reaches the
+ * subscriber until this chain has ruled on it — see `AgentLoopDeps.outputProcessors`. How much of
+ * that costs the reader is what {@link incremental} decides.
+ *
+ * Runs inside the loop's `process:output:<step>` checkpoint (which also performs the release), so a
+ * processor may call a model — a moderation pass is the motivating case — and a replay reads the
+ * verdict back instead of re-deciding it.
+ */
+interface OutputProcessor {
+    /** Identifies this processor in a rejection or a failure. User-visible; keep it stable. */
+    readonly name: string;
+    /**
+     * Opt this processor into gating a PREFIX, so the turn keeps streaming — see
+     * {@link IncrementalGating} for what declaring it promises. Undefined means the whole answer,
+     * which is what a processor written against the complete text needs and therefore the only safe
+     * default; a chain is incremental only when EVERY member of it declares this, so a neighbour can
+     * never downgrade what another author was given.
+     */
+    readonly incremental?: IncrementalGating;
+    process(answer: ModelAnswer, ctx: ProcessorContext): OutputVerdict | Promise<OutputVerdict>;
+}
+/**
+ * The run ended because an output processor refused the answer — NOT because the model failed. The
+ * two must stay distinguishable: a model failure is worth retrying and worth paging someone about,
+ * a refusal is the control doing its job. Both runners map this to the `output_rejected` stream
+ * error code.
+ */
+declare class OutputRejectedError extends Error {
+    /** {@link OutputProcessor.name} of the processor that refused. */
+    readonly processor: string;
+    /** The reason it gave, verbatim. */
+    readonly reason: string;
+    constructor(processor: string, reason: string);
+}
+/**
+ * A processor threw. Wrapped so it can never be mistaken for the model call failing — the loop's
+ * only other source of failure at that point in the turn — and so the failure names the processor
+ * that produced it instead of surfacing a bare `TypeError` from someone else's code.
+ */
+declare class ProcessorFailedError extends Error {
+    /** Which seam it was on, so a reader knows whether the prompt or the answer was in flight. */
+    readonly phase: 'input' | 'output';
+    /** The processor's `name`. */
+    readonly processor: string;
+    constructor(phase: 'input' | 'output', processor: string, cause: unknown);
+}
+
+export { DEFAULT_INCREMENTAL_LOOKBACK_CHARS as D, type InputProcessor as I, type ModelAnswer as M, type OutputProcessor as O, type ProcessorContext as P, type ProcessedPrompt as a, type IncrementalGating as b, OutputRejectedError as c, type OutputVerdict as d, ProcessorFailedError as e };

package/dist/processors-CK1RWv0D.d.ts

@@ -0,0 +1,160 @@
+import { M as ModelMessage, A as Actor, d as ToolCallRequest } from './tool-BXKG2xSm.js';
+
+/**
+ * The two seams that see a turn's traffic to and from the model: an {@link InputProcessor} rewrites
+ * the prompt on its way out, an {@link OutputProcessor} inspects the answer on its way back and may
+ * redact, replace or refuse it. Wire them as `AgentLoopDeps.inputProcessors` /
+ * `outputProcessors`, or via `AgentModule.forRoot({ inputProcessors, outputProcessors })`.
+ *
+ * WHAT THESE ARE NOT: a second way to decide what enters the context. `HistoryPolicy` owns
+ * SELECTION — which of the thread's messages ride into the turn, and what stands in for the rest.
+ * Processors run on whatever selection produced and own TRANSFORMATION — what those messages say.
+ * The distinction is load-bearing rather than stylistic: selection is contractually pure and is what
+ * the `load:thread` checkpoint records, so it bounds the journal as well as the prompt, while a
+ * processor is allowed to call a model, runs in a checkpoint of its own per step, and rewrites a
+ * DERIVED prompt that never becomes the thread's own memory of what was said. Splitting the same
+ * decision across both means neither can be reasoned about alone, and the cheap one stops being the
+ * whole answer to "why did this turn cost that much".
+ */
+
+/** Which turn, and which model step of it, a processor is looking at. */
+interface ProcessorContext {
+    threadId: string;
+    actor: Actor;
+    /** The agent running this turn. Undefined → the default agent. */
+    agentName?: string;
+    /** 0-based model step within the run — the same index the `llm:<step>` checkpoint carries. */
+    step: number;
+}
+/** Everything the model is about to be sent, as the previous processor in the chain left it. */
+interface ProcessedPrompt {
+    /** The composed system prompt (agent base + contributors + any injected retrieval block). */
+    system: string;
+    /** The turn's messages, oldest-first, already through the history ceiling. */
+    messages: ModelMessage[];
+}
+/**
+ * Rewrites the prompt before each model call of a turn — masking identifiers, stamping a policy
+ * preamble, collapsing an oversized tool result. Runs on EVERY step, not once per run, because the
+ * transcript grows between steps: a redactor that only saw the opening prompt would wave through
+ * whatever a tool result carried back.
+ *
+ * Runs inside the loop's `process:input:<step>` checkpoint and its result is journaled, so a
+ * processor may call a model or hit the network — a resumed run reads back the prompt the suspended
+ * attempt built rather than composing a different one.
+ */
+interface InputProcessor {
+    /** Identifies this processor in a failure. Keep it stable — it is user-visible on an error. */
+    readonly name: string;
+    process(prompt: ProcessedPrompt, ctx: ProcessorContext): ProcessedPrompt | Promise<ProcessedPrompt>;
+}
+/** One model step's answer, as the previous processor in the chain left it. */
+interface ModelAnswer {
+    /** The assembled assistant text for this step. */
+    text: string;
+    /** The tool calls the same step asked for. Read-only context — a processor cannot change them. */
+    toolCalls: readonly ToolCallRequest[];
+}
+/**
+ * What an {@link OutputProcessor} decided. `pass` hands the text to the next processor unchanged;
+ * `replace` hands it on rewritten (a redaction is a replacement); `reject` ends the chain AND the
+ * run — the text is never streamed, never persisted, and the caller gets an
+ * {@link OutputRejectedError} rather than an answer.
+ */
+type OutputVerdict = {
+    action: 'pass';
+} | {
+    action: 'replace';
+    text: string;
+} | {
+    action: 'reject';
+    reason: string;
+};
+/**
+ * Characters an incremental gate keeps holding at the end of the transformed answer, when a
+ * processor declares {@link IncrementalGating} without naming its own window. Wide enough for the
+ * patterns a redactor is usually written against — an SSN, an email address, a card number — and
+ * deliberately not wider: the window IS the answer's minimum latency tail, since those characters
+ * are only released once the whole-answer pass runs.
+ */
+declare const DEFAULT_INCREMENTAL_LOOKBACK_CHARS = 64;
+/**
+ * A processor's statement that its verdict on a PREFIX of an answer is worth acting on, which is
+ * what lets the loop release that prefix to the reader instead of holding the whole answer.
+ *
+ * Declaring it is a promise about every prefix `P` of the final answer, and the loop takes it at
+ * face value on the streaming path:
+ *
+ * 1. REJECTION IS PREFIX-DECIDABLE. The refusal this processor would return for the whole answer is
+ *    already returned for the first prefix that contains the reason. A refusal that only emerges
+ *    from the complete answer still fails the run, but by then the reader has seen a prefix — there
+ *    is no un-sending bytes, and that is the cost of opting in.
+ * 2. REPLACEMENT IS PREFIX-STABLE UP TO THE WINDOW. Once a character of `process(P)`'s output is
+ *    more than {@link lookbackChars} from the end of that output, it never changes as `P` grows.
+ *
+ * A broken second promise is caught, not tolerated: the whole-answer pass stays authoritative, and
+ * the loop raises a `ProcessorFailedError` when its result is not an extension of what the chain
+ * already released. So a window too short for a pattern fails loudly rather than streaming the text
+ * it was supposed to redact.
+ */
+interface IncrementalGating {
+    /**
+     * How many characters of this processor's own output stay held back. Undefined →
+     * {@link DEFAULT_INCREMENTAL_LOOKBACK_CHARS}. Set it to the length of the longest pattern the
+     * processor can act on — anything shorter is a run that fails on the pattern it was written for.
+     */
+    readonly lookbackChars?: number;
+}
+/**
+ * Inspects each model step's answer before anything downstream sees it — before it reaches the live
+ * stream, before it is persisted, before it becomes the next step's context.
+ *
+ * Gating an answer and streaming it as it is generated are mutually exclusive, so registering ANY
+ * output processor switches the turn's model call off the run's sink: nothing reaches the
+ * subscriber until this chain has ruled on it — see `AgentLoopDeps.outputProcessors`. How much of
+ * that costs the reader is what {@link incremental} decides.
+ *
+ * Runs inside the loop's `process:output:<step>` checkpoint (which also performs the release), so a
+ * processor may call a model — a moderation pass is the motivating case — and a replay reads the
+ * verdict back instead of re-deciding it.
+ */
+interface OutputProcessor {
+    /** Identifies this processor in a rejection or a failure. User-visible; keep it stable. */
+    readonly name: string;
+    /**
+     * Opt this processor into gating a PREFIX, so the turn keeps streaming — see
+     * {@link IncrementalGating} for what declaring it promises. Undefined means the whole answer,
+     * which is what a processor written against the complete text needs and therefore the only safe
+     * default; a chain is incremental only when EVERY member of it declares this, so a neighbour can
+     * never downgrade what another author was given.
+     */
+    readonly incremental?: IncrementalGating;
+    process(answer: ModelAnswer, ctx: ProcessorContext): OutputVerdict | Promise<OutputVerdict>;
+}
+/**
+ * The run ended because an output processor refused the answer — NOT because the model failed. The
+ * two must stay distinguishable: a model failure is worth retrying and worth paging someone about,
+ * a refusal is the control doing its job. Both runners map this to the `output_rejected` stream
+ * error code.
+ */
+declare class OutputRejectedError extends Error {
+    /** {@link OutputProcessor.name} of the processor that refused. */
+    readonly processor: string;
+    /** The reason it gave, verbatim. */
+    readonly reason: string;
+    constructor(processor: string, reason: string);
+}
+/**
+ * A processor threw. Wrapped so it can never be mistaken for the model call failing — the loop's
+ * only other source of failure at that point in the turn — and so the failure names the processor
+ * that produced it instead of surfacing a bare `TypeError` from someone else's code.
+ */
+declare class ProcessorFailedError extends Error {
+    /** Which seam it was on, so a reader knows whether the prompt or the answer was in flight. */
+    readonly phase: 'input' | 'output';
+    /** The processor's `name`. */
+    readonly processor: string;
+    constructor(phase: 'input' | 'output', processor: string, cause: unknown);
+}
+
+export { DEFAULT_INCREMENTAL_LOOKBACK_CHARS as D, type InputProcessor as I, type ModelAnswer as M, type OutputProcessor as O, type ProcessorContext as P, type ProcessedPrompt as a, type IncrementalGating as b, OutputRejectedError as c, type OutputVerdict as d, ProcessorFailedError as e };

package/dist/{tool-fLRLs_f3.d.cts → tool-BXKG2xSm.d.cts}

@@ -1266,6 +1266,11 @@ interface LlmStepEnvelope {
     messages: ModelMessage[];
     /** The turn's actor — the handler re-derives tool definitions from it (definitionsFor). */
     actor: Actor;
+    /**
+     * The turn's thread — with {@link actor}, what a tool's per-turn `describe` is scoped on. Optional
+     * so an envelope from a loop that predates it still parses.
+     */
+    threadId?: string;
     /**
      * Hold this call's stream frames rather than writing them to the run's sink, and return them on
      * the result. Set by the loop when an output processor has to see the whole answer before the
@@ -1312,163 +1317,6 @@ interface ToolStepEnvelope {
     collectUi?: boolean;
 }
 
-/**
- * The two seams that see a turn's traffic to and from the model: an {@link InputProcessor} rewrites
- * the prompt on its way out, an {@link OutputProcessor} inspects the answer on its way back and may
- * redact, replace or refuse it. Wire them as `AgentLoopDeps.inputProcessors` /
- * `outputProcessors`, or via `AgentModule.forRoot({ inputProcessors, outputProcessors })`.
- *
- * WHAT THESE ARE NOT: a second way to decide what enters the context. `HistoryPolicy` owns
- * SELECTION — which of the thread's messages ride into the turn, and what stands in for the rest.
- * Processors run on whatever selection produced and own TRANSFORMATION — what those messages say.
- * The distinction is load-bearing rather than stylistic: selection is contractually pure and is what
- * the `load:thread` checkpoint records, so it bounds the journal as well as the prompt, while a
- * processor is allowed to call a model, runs in a checkpoint of its own per step, and rewrites a
- * DERIVED prompt that never becomes the thread's own memory of what was said. Splitting the same
- * decision across both means neither can be reasoned about alone, and the cheap one stops being the
- * whole answer to "why did this turn cost that much".
- */
-
-/** Which turn, and which model step of it, a processor is looking at. */
-interface ProcessorContext {
-    threadId: string;
-    actor: Actor;
-    /** The agent running this turn. Undefined → the default agent. */
-    agentName?: string;
-    /** 0-based model step within the run — the same index the `llm:<step>` checkpoint carries. */
-    step: number;
-}
-/** Everything the model is about to be sent, as the previous processor in the chain left it. */
-interface ProcessedPrompt {
-    /** The composed system prompt (agent base + contributors + any injected retrieval block). */
-    system: string;
-    /** The turn's messages, oldest-first, already through the history ceiling. */
-    messages: ModelMessage[];
-}
-/**
- * Rewrites the prompt before each model call of a turn — masking identifiers, stamping a policy
- * preamble, collapsing an oversized tool result. Runs on EVERY step, not once per run, because the
- * transcript grows between steps: a redactor that only saw the opening prompt would wave through
- * whatever a tool result carried back.
- *
- * Runs inside the loop's `process:input:<step>` checkpoint and its result is journaled, so a
- * processor may call a model or hit the network — a resumed run reads back the prompt the suspended
- * attempt built rather than composing a different one.
- */
-interface InputProcessor {
-    /** Identifies this processor in a failure. Keep it stable — it is user-visible on an error. */
-    readonly name: string;
-    process(prompt: ProcessedPrompt, ctx: ProcessorContext): ProcessedPrompt | Promise<ProcessedPrompt>;
-}
-/** One model step's answer, as the previous processor in the chain left it. */
-interface ModelAnswer {
-    /** The assembled assistant text for this step. */
-    text: string;
-    /** The tool calls the same step asked for. Read-only context — a processor cannot change them. */
-    toolCalls: readonly ToolCallRequest[];
-}
-/**
- * What an {@link OutputProcessor} decided. `pass` hands the text to the next processor unchanged;
- * `replace` hands it on rewritten (a redaction is a replacement); `reject` ends the chain AND the
- * run — the text is never streamed, never persisted, and the caller gets an
- * {@link OutputRejectedError} rather than an answer.
- */
-type OutputVerdict = {
-    action: 'pass';
-} | {
-    action: 'replace';
-    text: string;
-} | {
-    action: 'reject';
-    reason: string;
-};
-/**
- * Characters an incremental gate keeps holding at the end of the transformed answer, when a
- * processor declares {@link IncrementalGating} without naming its own window. Wide enough for the
- * patterns a redactor is usually written against — an SSN, an email address, a card number — and
- * deliberately not wider: the window IS the answer's minimum latency tail, since those characters
- * are only released once the whole-answer pass runs.
- */
-declare const DEFAULT_INCREMENTAL_LOOKBACK_CHARS = 64;
-/**
- * A processor's statement that its verdict on a PREFIX of an answer is worth acting on, which is
- * what lets the loop release that prefix to the reader instead of holding the whole answer.
- *
- * Declaring it is a promise about every prefix `P` of the final answer, and the loop takes it at
- * face value on the streaming path:
- *
- * 1. REJECTION IS PREFIX-DECIDABLE. The refusal this processor would return for the whole answer is
- *    already returned for the first prefix that contains the reason. A refusal that only emerges
- *    from the complete answer still fails the run, but by then the reader has seen a prefix — there
- *    is no un-sending bytes, and that is the cost of opting in.
- * 2. REPLACEMENT IS PREFIX-STABLE UP TO THE WINDOW. Once a character of `process(P)`'s output is
- *    more than {@link lookbackChars} from the end of that output, it never changes as `P` grows.
- *
- * A broken second promise is caught, not tolerated: the whole-answer pass stays authoritative, and
- * the loop raises a `ProcessorFailedError` when its result is not an extension of what the chain
- * already released. So a window too short for a pattern fails loudly rather than streaming the text
- * it was supposed to redact.
- */
-interface IncrementalGating {
-    /**
-     * How many characters of this processor's own output stay held back. Undefined →
-     * {@link DEFAULT_INCREMENTAL_LOOKBACK_CHARS}. Set it to the length of the longest pattern the
-     * processor can act on — anything shorter is a run that fails on the pattern it was written for.
-     */
-    readonly lookbackChars?: number;
-}
-/**
- * Inspects each model step's answer before anything downstream sees it — before it reaches the live
- * stream, before it is persisted, before it becomes the next step's context.
- *
- * Gating an answer and streaming it as it is generated are mutually exclusive, so registering ANY
- * output processor switches the turn's model call off the run's sink: nothing reaches the
- * subscriber until this chain has ruled on it — see `AgentLoopDeps.outputProcessors`. How much of
- * that costs the reader is what {@link incremental} decides.
- *
- * Runs inside the loop's `process:output:<step>` checkpoint (which also performs the release), so a
- * processor may call a model — a moderation pass is the motivating case — and a replay reads the
- * verdict back instead of re-deciding it.
- */
-interface OutputProcessor {
-    /** Identifies this processor in a rejection or a failure. User-visible; keep it stable. */
-    readonly name: string;
-    /**
-     * Opt this processor into gating a PREFIX, so the turn keeps streaming — see
-     * {@link IncrementalGating} for what declaring it promises. Undefined means the whole answer,
-     * which is what a processor written against the complete text needs and therefore the only safe
-     * default; a chain is incremental only when EVERY member of it declares this, so a neighbour can
-     * never downgrade what another author was given.
-     */
-    readonly incremental?: IncrementalGating;
-    process(answer: ModelAnswer, ctx: ProcessorContext): OutputVerdict | Promise<OutputVerdict>;
-}
-/**
- * The run ended because an output processor refused the answer — NOT because the model failed. The
- * two must stay distinguishable: a model failure is worth retrying and worth paging someone about,
- * a refusal is the control doing its job. Both runners map this to the `output_rejected` stream
- * error code.
- */
-declare class OutputRejectedError extends Error {
-    /** {@link OutputProcessor.name} of the processor that refused. */
-    readonly processor: string;
-    /** The reason it gave, verbatim. */
-    readonly reason: string;
-    constructor(processor: string, reason: string);
-}
-/**
- * A processor threw. Wrapped so it can never be mistaken for the model call failing — the loop's
- * only other source of failure at that point in the turn — and so the failure names the processor
- * that produced it instead of surfacing a bare `TypeError` from someone else's code.
- */
-declare class ProcessorFailedError extends Error {
-    /** Which seam it was on, so a reader knows whether the prompt or the answer was in flight. */
-    readonly phase: 'input' | 'output';
-    /** The processor's `name`. */
-    readonly processor: string;
-    constructor(phase: 'input' | 'output', processor: string, cause: unknown);
-}
-
 /**
  * Per-invocation context handed to a tool handler. Host-supplied bits are optional. Identity lives
  * on {@link AiToolCtx.actor} — read `ctx.actor.id` / `ctx.actor.tenantRef` (single source of truth;
@@ -1494,12 +1342,13 @@ interface AiToolCtx {
      * JSON; it is snapshotted when pushed.
      *
      * Replay-safe under the durable runner: the pushed components ride the tool step's journaled
-     * result, so a replay neither streams nor persists them again. Present whenever the agent loop
-     * runs the tool (inline, durable, dispatched); absent on surfaces with no conversation to push
-     * into (the MCP server), hence optional — call it as `ctx.emitUi?.(…)` in a tool that is also
-     * served there.
+     * result, so a replay neither streams nor persists them again.
+     *
+     * Always present. On a surface with no conversation to push into (the MCP server, a direct
+     * `registry.invoke` without one) it is a no-op that still resolves to an id, so a tool calls
+     * `ctx.emitUi(…)` unconditionally.
      */
-    emitUi?(component: string, props: Record<string, unknown>, options?: {
+    emitUi(component: string, props: Record<string, unknown>, options?: {
         id?: string;
         version?: number;
     }): Promise<{
@@ -1536,6 +1385,30 @@ interface ToolHandler<I = unknown> {
      * when the turn's tool list is built (a denied actor is never shown it) and again on invoke.
      */
     canUse?(actor: Actor): boolean | Promise<boolean>;
+    /**
+     * What the model is told about this tool for THIS turn — a description and/or input schema that
+     * depend on who is asking (a per-tenant component catalog, a per-plan list of options). Called
+     * when the turn's tool list is built, after every gate has passed; whatever it returns replaces
+     * the registered spec's `description` / `inputSchema` in the definition the model sees. Omit, or
+     * return `undefined`, to use the registered spec as is.
+     *
+     * It shapes what the model is SHOWN only: the registry still validates a call against the
+     * registered `inputSchema`, so a tool whose accepted input varies per turn registers a permissive
+     * schema and validates in `execute`.
+     */
+    describe?(scope: ToolDescribeScope): ToolDescription | undefined | Promise<ToolDescription | undefined>;
+}
+/** Who a turn's tool list is being built for — what {@link ToolHandler.describe} can vary on. */
+interface ToolDescribeScope {
+    actor: Actor;
+    /** Absent where the list is built outside a conversation (the MCP server's `tools/list`). */
+    threadId?: string;
+    agentName?: string;
+}
+/** A per-turn override of a tool's model-facing definition ({@link ToolHandler.describe}). */
+interface ToolDescription {
+    description?: string;
+    inputSchema?: StandardSchemaV1;
 }
 
-export { type ElicitationInput as $, type Actor as A, type Decision as B, type ToolStepEnvelope as C, type DetachedDelivery as D, type ElicitationRequest as E, ASK_TOOL_DESCRIPTION as F, ASK_TOOL_NAME as G, type HumanReply as H, type InputProcessor as I, type AgentApprovalRequest as J, type AgentApprovalSettlement as K, type LlmStepEnvelope as L, type ModelMessage as M, type AgentCatalogEntry as N, type OutputProcessor as O, type ProcessorContext as P, type QuotaState as Q, type AgentHistoryWindow as R, type StoredMessage as S, type ToolHandler as T, type UsagePurpose as U, type AskToolInput as V, DEFAULT_INCREMENTAL_LOOKBACK_CHARS as W, DEFAULT_INTAKE_PREAMBLE as X, DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS as Y, DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS as Z, ELICITATION_INPUT_TYPES as _, type ToolDefinition as a, type ElicitationInputType as a0, type ElicitationOption as a1, type ElicitationOutcome as a2, type ElicitationQuestion as a3, type ElicitationReply as a4, type ElicitationResult as a5, type HistoryPolicyContext as a6, type HistorySelection as a7, type HistorySummary as a8, type IncrementalGating as a9, normalizeElicitationReply as aA, questionOptions as aB, readElicitationInput as aC, readElicitationQuestions as aD, renderElicitationAnswers as aE, resolveElicitation as aF, resolveToolTransientRetryNumbers as aG, settleElicitation as aH, validateElicitationAnswer as aI, validateElicitationValue as aJ, type InvokeWithTransientRetryOptions as aa, MAX_ASK_QUESTIONS as ab, type MessageFeedbackValue as ac, type MessageRole as ad, OutputRejectedError as ae, type OutputVerdict as af, ProcessorFailedError as ag, type PromptContext as ah, type QuotaView as ai, type ToolCallApprovalStatus as aj, type ToolCatalogEntry as ak, type ToolConfirmation as al, type ToolPresentation as am, type ToolPresentationTone as an, type ToolResultField as ao, type ToolResultView as ap, type ToolStepCtx as aq, type ToolTransientRetryNumbers as ar, type ToolTransientRetryOptions as as, askInputSchema as at, askToolDefinition as au, decodeStreamEvent as av, encodeStreamEvent as aw, invokeWithTransientRetry as ax, isTransientToolError as ay, isTypedQuestion as az, type ToolCallRequest as b, type MessageUsage as c, type AgentUiComponent as d, type AiToolCtx as e, type AgentStreamEvent as f, type ThreadSummary as g, type ThreadDetail as h, type ToolResult as i, type MessageAttachment as j, type MessageFeedback as k, type ToolCallStatus as l, type ToolSpec as m, type AgentRunInput as n, type ToolKind as o, type ToolCallApproval as p, type HistoryPolicy as q, type ProcessedPrompt as r, type ModelAnswer as s, type PageContext as t, type AgentDefinition as u, type AgentDelegation as v, type PromptBuilder as w, type PromptContributor as x, type ToolTransientRetrySetting as y, type AgentIntake as z };
+export { type ElicitationQuestion as $, type Actor as A, type ToolStepEnvelope as B, ASK_TOOL_DESCRIPTION as C, type DetachedDelivery as D, type ElicitationRequest as E, ASK_TOOL_NAME as F, type AgentApprovalRequest as G, type HumanReply as H, type AgentApprovalSettlement as I, type AgentCatalogEntry as J, type AgentHistoryWindow as K, type LlmStepEnvelope as L, type ModelMessage as M, type AskToolInput as N, DEFAULT_INTAKE_PREAMBLE as O, type PageContext as P, type QuotaState as Q, DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS as R, type StoredMessage as S, type ToolSpec as T, type UsagePurpose as U, DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS as V, ELICITATION_INPUT_TYPES as W, type ElicitationInput as X, type ElicitationInputType as Y, type ElicitationOption as Z, type ElicitationOutcome as _, type ToolHandler as a, type ElicitationReply as a0, type ElicitationResult as a1, type HistoryPolicyContext as a2, type HistorySelection as a3, type HistorySummary as a4, type InvokeWithTransientRetryOptions as a5, MAX_ASK_QUESTIONS as a6, type MessageFeedbackValue as a7, type MessageRole as a8, type PromptContext as a9, validateElicitationAnswer as aA, validateElicitationValue as aB, type QuotaView as aa, type ToolCallApprovalStatus as ab, type ToolCatalogEntry as ac, type ToolConfirmation as ad, type ToolDescription as ae, type ToolPresentationTone as af, type ToolResultField as ag, type ToolResultView as ah, type ToolStepCtx as ai, type ToolTransientRetryNumbers as aj, type ToolTransientRetryOptions as ak, askInputSchema as al, askToolDefinition as am, decodeStreamEvent as an, encodeStreamEvent as ao, invokeWithTransientRetry as ap, isTransientToolError as aq, isTypedQuestion as ar, normalizeElicitationReply as as, questionOptions as at, readElicitationInput as au, readElicitationQuestions as av, renderElicitationAnswers as aw, resolveElicitation as ax, resolveToolTransientRetryNumbers as ay, settleElicitation as az, type ToolPresentation as b, type ToolDefinition as c, type ToolCallRequest as d, type MessageUsage as e, type AgentUiComponent as f, type AiToolCtx as g, type AgentStreamEvent as h, type ThreadSummary as i, type ThreadDetail as j, type ToolResult as k, type MessageAttachment as l, type MessageFeedback as m, type ToolCallStatus as n, type AgentRunInput as o, type ToolKind as p, type ToolCallApproval as q, type HistoryPolicy as r, type AgentDefinition as s, type AgentDelegation as t, type ToolDescribeScope as u, type PromptBuilder as v, type PromptContributor as w, type ToolTransientRetrySetting as x, type AgentIntake as y, type Decision as z };