@tanstack/ai

import { AgentLoopState, StreamChunk } from '../../../types.js'; import { InternalLogger } from '../../../logger/internal-logger.js'; import { AbortInfo, AfterToolCallInfo, BeforeToolCallDecision, ChatMiddleware, ChatMiddlewareConfig, ChatMiddlewareContext, ErrorInfo, FinishInfo, IterationInfo, SandboxFileHookEvent, StructuredOutputMiddlewareConfig, ToolCallHookContext, ToolPhaseCompleteInfo, UsageInfo } from './types.js'; /** * Internal middleware runner that manages composed execution of middleware hooks. * Created once per chat() invocation. */ export declare class MiddlewareRunner<TContext = unknown> { private readonly middlewares; private readonly logger; constructor(middlewares: ReadonlyArray<ChatMiddleware<TContext>>, logger: InternalLogger); get hasMiddleware(): boolean; /** * Pipe config through all middleware onConfig hooks in order. * Each middleware receives the merged config from previous middleware. * Partial returns are shallow-merged with the current config. */ runOnConfig(ctx: ChatMiddlewareContext<TContext>, config: ChatMiddlewareConfig): Promise<ChatMiddlewareConfig>; /** * Pipe config through all middleware onStructuredOutputConfig hooks in order. * Each middleware receives the merged config from previous middleware. * Partial returns are shallow-merged with the current config. * * Called once at the structured-output boundary, before runOnConfig at the * same boundary (which receives a ChatMiddlewareConfig view, no outputSchema). */ runOnStructuredOutputConfig(ctx: ChatMiddlewareContext<TContext>, config: StructuredOutputMiddlewareConfig): Promise<StructuredOutputMiddlewareConfig>; /** * Run all `setup` hooks in array order, then assert every declared `provides` * capability was actually provided. Wires the last-wins duplicate-provide * warning into the registry. Runs before init `onConfig`. * * Takes the full `ChatMiddlewareContext` — the same stable context the engine * threads through every other hook — because it both forwards `ctx` to each * `setup` hook and emits instrumentation events from it. */ runSetup(ctx: ChatMiddlewareContext<TContext>): Promise<void>; /** * Call onStart on all middleware in order. */ runOnStart(ctx: ChatMiddlewareContext<TContext>): Promise<void>; /** * Pipe a single chunk through all middleware onChunk hooks in order. * Returns the resulting chunks (0..N) to yield to the consumer. * * - void: pass through unchanged * - chunk: replace with this chunk * - chunk[]: expand to multiple chunks * - null: drop the chunk entirely */ runOnChunk(ctx: ChatMiddlewareContext<TContext>, chunk: StreamChunk): Promise<Array<StreamChunk>>; /** * Dispatch a sandbox file event to every middleware's `sandbox` hooks, in * array order: the catch-all `onFile` then the type-specific hook. Errors are * logged and swallowed so one bad hook can't break the run. */ runSandboxFile(ctx: ChatMiddlewareContext<TContext>, event: SandboxFileHookEvent): Promise<void>; /** * Run onBeforeToolCall through middleware in order. * Returns the first non-void decision, or undefined to continue normally. */ runOnBeforeToolCall(ctx: ChatMiddlewareContext<TContext>, hookCtx: ToolCallHookContext): Promise<BeforeToolCallDecision>; /** * Run onAfterToolCall on all middleware in order. */ runOnAfterToolCall(ctx: ChatMiddlewareContext<TContext>, info: AfterToolCallInfo): Promise<void>; /** * Run onUsage on all middleware in order. */ runOnUsage(ctx: ChatMiddlewareContext<TContext>, usage: UsageInfo): Promise<void>; /** * Await ONE terminal hook and RETURN its throw instead of letting it escape * the caller's loop, logging it on the `errors` channel first so the failure * is never invisible. `undefined` means the hook completed. * * Capturing (rather than swallowing at this level) is what lets isolation and * reporting coexist: every caller gives every middleware its turn, and then * each decides on its own whether the collected failures are worth telling the * caller about. See {@link runOnFinish} vs {@link runOnAbort} / * {@link runOnError}. */ private captureTerminalHook; /** * Run onFinish on all middleware in order. * * ISOLATED **and** REPORTED. `onFinish` is the only terminal fan-out on the * SUCCESS path, and it is where `withPersistence.onFinish` writes the * assistant turn through the store. So the two properties are needed together * and neither may be traded for the other: * * - ISOLATION: every middleware's hook runs even if an earlier one threw, so a * transient store error cannot skip a later middleware's own bookkeeping. * Each failure is captured by {@link captureTerminalHook}, not propagated * mid-loop. * - REPORTING: after the loop, the failures are rethrown. `chat()`'s catch * treats what we throw as a genuine error (it is not a * `MiddlewareAbortError`, and `structuralInterruptFailure` does not match * it) and rethrows it out of the generator. * * What that rethrow can and cannot achieve depends on the transport, because * this fan-out is awaited AFTER the adapter's `RUN_FINISHED` has already been * yielded (`chat()` yields terminal chunks while streaming, then awaits this * hook on its way out). The success terminal is therefore already gone; the * rethrow can only append to what the consumer saw, never retract it: * * - NON-DURABLE transport: the throw escapes the generator mid-response, and * the SSE / HTTP-stream encoder turns it into a TRAILING `RUN_ERROR` on the * wire carrying the store's own message and `code`. `ai-client` surfaces * that as an error status, so the user is not told the turn was saved when * it was not. * - DURABLE transport: the throw reaches the durability sink instead. The * terminal was already persisted AND forwarded, so the sink deliberately * does NOT append a second, contradictory terminal, and `terminalForwarded` * (see `stream-to-response.ts`) suppresses the rethrow to the live consumer. * The `RUN_FINISHED` stands and the failure is RECORDED SERVER-SIDE on the * sink's `errors` channel. That is the intended outcome, not a gap: the save * failed, not the run — the consumer did receive the complete stream, so * telling it the run errored would be the lie. What the rethrow buys here is * that the sink sees the failure at all; while this loop swallowed, the only * trace anywhere was {@link captureTerminalHook}'s log line. * * Either way, swallowing is the one option ruled out: a failed * `messages.append` would otherwise leave a `completed` run record with the * assistant turn missing from storage and nothing beyond a middleware log * line, and the client would go on to send a history the server has no record * of. * * A single failure is rethrown AS-IS so the store's own error — its message, * `cause`, `code` and `instanceof` identity — is what reaches the caller and * the wire; wrapping the common case would bury it. Two or more become an * `AggregateError` (never a `MiddlewareAbortError`, so it cannot be mistaken * for an abort) rather than picking a winner and dropping the rest. */ runOnFinish(ctx: ChatMiddlewareContext<TContext>, info: FinishInfo): Promise<void>; /** * Run onAbort on all middleware in order. * * ISOLATED and DELIBERATELY SWALLOWED. `onAbort` is a pure teardown fan-out * released from `chat()`'s `finally`, on a path where the outcome is already * decided: the run stopped, and the caller is being told why. A throw here has * nothing better to report than the abort reason it would DISPLACE — the * `finally` would surface a flaky store's error in place of "client * disconnected" — so failures are logged on the `errors` channel and go no * further. That is not a silent failure; it is refusing to let teardown * rewrite an outcome it did not produce. * * Isolation matters independently: these hooks release PER-MIDDLEWARE * resources (`withSandbox.onAbort` detaches or destroys the sandbox and stamps * `detachedSince`; `withPersistence.onAbort` records the run status through the * store), so an unguarded loop turns one transient store error into a * permanently leaked sandbox for every middleware ordered after it. */ runOnAbort(ctx: ChatMiddlewareContext<TContext>, info: AbortInfo): Promise<void>; /** * Run onError on all middleware in order. * * ISOLATED and DELIBERATELY SWALLOWED, for the same reason as * {@link runOnAbort} and NOT merely because it is teardown: the run has * already failed, `info.error` IS that failure, and `chat()` rethrows it to the * caller the moment this fan-out returns. A propagated hook throw could only * REPLACE the run's real error with a teardown artifact — strictly less * information for the caller, who is already learning the run failed. Reporting * would buy nothing and cost the diagnosis, so failures are logged on the * `errors` channel and stop there. * * Contrast {@link runOnFinish}, where nothing else is telling the caller * anything is wrong — which is why that one reports. */ runOnError(ctx: ChatMiddlewareContext<TContext>, info: ErrorInfo): Promise<void>; /** * Run onIteration on all middleware in order. * Called at the start of each agent loop iteration. */ runOnIteration(ctx: ChatMiddlewareContext<TContext>, info: IterationInfo): Promise<void>; /** * Run onShouldContinue through middleware in order (AND semantics). * Any explicit `false` stops further iterations; `true` / void / undefined pass. * Called after `agentLoopStrategy` has already approved continuation. */ runOnShouldContinue(ctx: ChatMiddlewareContext<TContext>, state: AgentLoopState): Promise<boolean>; /** * Run onToolPhaseComplete on all middleware in order. * Called after all tool calls in an iteration have been processed. */ runOnToolPhaseComplete(ctx: ChatMiddlewareContext<TContext>, info: ToolPhaseCompleteInfo): Promise<void>; }