@tanstack/ai 0.36.0 → 0.38.0

package/dist/esm/activities/chat/middleware/capabilities.d.ts

@@ -0,0 +1,93 @@
+/** Options accepted by a capability getter. */
+export interface CapabilityGetOptions {
+    /** When true, return undefined instead of throwing if the capability is absent. */
+    optional?: boolean;
+}
+/**
+ * The minimal context shape a capability accessor needs. The full
+ * `ChatMiddlewareContext` satisfies this (it has `capabilities`), so accessors
+ * accept any middleware context without referencing `any`.
+ */
+export interface CapabilityContext {
+    capabilities: CapabilityRegistry;
+}
+/** Reads a capability value off a context. Overloaded so the flag narrows the return. */
+export interface CapabilityGetter<TValue> {
+    (ctx: CapabilityContext): TValue;
+    (ctx: CapabilityContext, opts: {
+        optional: true;
+    }): TValue | undefined;
+}
+/** Writes a capability value onto a context. */
+export type CapabilityProvider<TValue> = (ctx: CapabilityContext, value: TValue) => void;
+/**
+ * A capability handle. It is BOTH a `[get, provide]` tuple (array-destructurable)
+ * AND the identity used in middleware `requires`/`provides` declarations.
+ *
+ * Runtime identity is this object's reference. The `capabilityName` literal is
+ * used for diagnostics and COMPILE-TIME tracking only — capability names MUST be
+ * unique across an app or the type-level coverage check conflates them.
+ */
+export type Capability<TValue = unknown, TName extends string = string> = readonly [
+    get: CapabilityGetter<TValue>,
+    provide: CapabilityProvider<TValue>
+] & {
+    readonly capabilityName: TName;
+    /** @internal Presence check for the post-setup assertion. */
+    has: (ctx: CapabilityContext) => boolean;
+};
+/**
+ * A capability handle with permissive value/name — for use as a constraint in
+ * `requires`/`provides` arrays. Concentrates `any` in one named alias (same
+ * convention as `AnyTextAdapter`/`AnyTool`); needed so `Capability<SpecificT>`
+ * is assignable to the handle-array element type.
+ */
+export type CapabilityHandle = Capability<any, string>;
+/**
+ * Per-request bookkeeping: which capabilities were provided, plus the
+ * duplicate-provide notification. Capability VALUES live in per-capability
+ * WeakMaps (see `createCapability`), not here — this only tracks presence.
+ */
+export declare class CapabilityRegistry {
+    private readonly provided;
+    private onDuplicate?;
+    /** Register a callback fired when a handle is provided more than once. */
+    setOnDuplicate(cb: (name: string) => void): void;
+    /** Record that `handle` was provided; fire the duplicate callback on repeats. */
+    markProvided(handle: CapabilityHandle): void;
+    has(handle: CapabilityHandle): boolean;
+}
+/**
+ * Create a capability. Returns a hybrid handle that destructures to
+ * `[get, provide]` and is itself the identity for `requires`/`provides`.
+ *
+ * Curried so the value type is supplied explicitly while the name literal is
+ * INFERRED from the argument: `createCapability<T>()('name')`. (A single call
+ * `createCapability<T>('name')` cannot work — supplying `T` explicitly stops
+ * TypeScript inferring the name, collapsing it to `string` and defeating the
+ * compile-time coverage check that keys on the literal name.)
+ *
+ * @example Provider + consumer middleware
+ * ```ts
+ * const counterCapability = createCapability<{ value: number }>()('counter')
+ * const [getCounter, provideCounter] = counterCapability
+ *
+ * const withCounter = defineChatMiddleware({
+ *   name: 'counter',
+ *   provides: [counterCapability],
+ *   setup(ctx) { provideCounter(ctx, { value: 0 }) },
+ * })
+ *
+ * const readsCounter = defineChatMiddleware({
+ *   name: 'reads-counter',
+ *   requires: [counterCapability],
+ *   onChunk(ctx) { getCounter(ctx).value++ },
+ * })
+ *
+ * chat({ adapter, messages, middleware: [withCounter, readsCounter] })
+ * ```
+ *
+ * @remarks Capability `name`s must be unique across your app: compile-time
+ * coverage tracking keys on the name literal (runtime keys on reference).
+ */
+export declare function createCapability<TValue = unknown>(): <const TName extends string>(name: TName) => Capability<TValue, TName>;

package/dist/esm/activities/chat/middleware/capabilities.js

@@ -0,0 +1,45 @@
+class CapabilityRegistry {
+  provided = /* @__PURE__ */ new Set();
+  onDuplicate;
+  /** Register a callback fired when a handle is provided more than once. */
+  setOnDuplicate(cb) {
+    this.onDuplicate = cb;
+  }
+  /** Record that `handle` was provided; fire the duplicate callback on repeats. */
+  markProvided(handle) {
+    if (this.provided.has(handle)) this.onDuplicate?.(handle.capabilityName);
+    this.provided.add(handle);
+  }
+  has(handle) {
+    return this.provided.has(handle);
+  }
+}
+function createCapability() {
+  return (name) => {
+    const values = /* @__PURE__ */ new WeakMap();
+    function get(ctx, opts) {
+      if (!values.has(ctx)) {
+        if (opts?.optional) return void 0;
+        throw new Error(
+          `Capability "${name}" was requested but never provided. Ensure a middleware provides it in setup(), ordered before this consumer.`
+        );
+      }
+      return values.get(ctx);
+    }
+    const provide = (ctx, value) => {
+      values.set(ctx, value);
+      ctx.capabilities.markProvided(handle);
+    };
+    const pair = [get, provide];
+    const handle = Object.assign(pair, {
+      capabilityName: name,
+      has: (ctx) => values.has(ctx)
+    });
+    return handle;
+  };
+}
+export {
+  CapabilityRegistry,
+  createCapability
+};
+//# sourceMappingURL=capabilities.js.map

package/dist/esm/activities/chat/middleware/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sources":["../../../../../src/activities/chat/middleware/capabilities.ts"],"sourcesContent":["/** Options accepted by a capability getter. */\nexport interface CapabilityGetOptions {\n  /** When true, return undefined instead of throwing if the capability is absent. */\n  optional?: boolean\n}\n\n/**\n * The minimal context shape a capability accessor needs. The full\n * `ChatMiddlewareContext` satisfies this (it has `capabilities`), so accessors\n * accept any middleware context without referencing `any`.\n */\nexport interface CapabilityContext {\n  capabilities: CapabilityRegistry\n}\n\n/** Reads a capability value off a context. Overloaded so the flag narrows the return. */\nexport interface CapabilityGetter<TValue> {\n  (ctx: CapabilityContext): TValue\n  (ctx: CapabilityContext, opts: { optional: true }): TValue | undefined\n}\n\n/** Writes a capability value onto a context. */\nexport type CapabilityProvider<TValue> = (\n  ctx: CapabilityContext,\n  value: TValue,\n) => void\n\n/**\n * A capability handle. It is BOTH a `[get, provide]` tuple (array-destructurable)\n * AND the identity used in middleware `requires`/`provides` declarations.\n *\n * Runtime identity is this object's reference. The `capabilityName` literal is\n * used for diagnostics and COMPILE-TIME tracking only — capability names MUST be\n * unique across an app or the type-level coverage check conflates them.\n */\nexport type Capability<\n  TValue = unknown,\n  TName extends string = string,\n> = readonly [\n  get: CapabilityGetter<TValue>,\n  provide: CapabilityProvider<TValue>,\n] & {\n  readonly capabilityName: TName\n  /** @internal Presence check for the post-setup assertion. */\n  has: (ctx: CapabilityContext) => boolean\n}\n\n/**\n * A capability handle with permissive value/name — for use as a constraint in\n * `requires`/`provides` arrays. Concentrates `any` in one named alias (same\n * convention as `AnyTextAdapter`/`AnyTool`); needed so `Capability<SpecificT>`\n * is assignable to the handle-array element type.\n */\nexport type CapabilityHandle = Capability<any, string>\n\n/**\n * Per-request bookkeeping: which capabilities were provided, plus the\n * duplicate-provide notification. Capability VALUES live in per-capability\n * WeakMaps (see `createCapability`), not here — this only tracks presence.\n */\nexport class CapabilityRegistry {\n  private readonly provided = new Set<CapabilityHandle>()\n  private onDuplicate?: (name: string) => void\n\n  /** Register a callback fired when a handle is provided more than once. */\n  setOnDuplicate(cb: (name: string) => void): void {\n    this.onDuplicate = cb\n  }\n\n  /** Record that `handle` was provided; fire the duplicate callback on repeats. */\n  markProvided(handle: CapabilityHandle): void {\n    if (this.provided.has(handle)) this.onDuplicate?.(handle.capabilityName)\n    this.provided.add(handle)\n  }\n\n  has(handle: CapabilityHandle): boolean {\n    return this.provided.has(handle)\n  }\n}\n\n/**\n * Create a capability. Returns a hybrid handle that destructures to\n * `[get, provide]` and is itself the identity for `requires`/`provides`.\n *\n * Curried so the value type is supplied explicitly while the name literal is\n * INFERRED from the argument: `createCapability<T>()('name')`. (A single call\n * `createCapability<T>('name')` cannot work — supplying `T` explicitly stops\n * TypeScript inferring the name, collapsing it to `string` and defeating the\n * compile-time coverage check that keys on the literal name.)\n *\n * @example Provider + consumer middleware\n * ```ts\n * const counterCapability = createCapability<{ value: number }>()('counter')\n * const [getCounter, provideCounter] = counterCapability\n *\n * const withCounter = defineChatMiddleware({\n *   name: 'counter',\n *   provides: [counterCapability],\n *   setup(ctx) { provideCounter(ctx, { value: 0 }) },\n * })\n *\n * const readsCounter = defineChatMiddleware({\n *   name: 'reads-counter',\n *   requires: [counterCapability],\n *   onChunk(ctx) { getCounter(ctx).value++ },\n * })\n *\n * chat({ adapter, messages, middleware: [withCounter, readsCounter] })\n * ```\n *\n * @remarks Capability `name`s must be unique across your app: compile-time\n * coverage tracking keys on the name literal (runtime keys on reference).\n */\nexport function createCapability<TValue = unknown>(): <\n  const TName extends string,\n>(\n  name: TName,\n) => Capability<TValue, TName> {\n  return <const TName extends string>(\n    name: TName,\n  ): Capability<TValue, TName> => {\n    // Each capability owns a typed WeakMap keyed by the context object. Because\n    // the value type is TValue, reads are typed with no assertion.\n    const values = new WeakMap<CapabilityContext, TValue>()\n\n    function get(ctx: CapabilityContext): TValue\n    function get(\n      ctx: CapabilityContext,\n      opts: { optional: true },\n    ): TValue | undefined\n    function get(\n      ctx: CapabilityContext,\n      opts?: CapabilityGetOptions,\n    ): TValue | undefined {\n      if (!values.has(ctx)) {\n        if (opts?.optional) return undefined\n        throw new Error(\n          `Capability \"${name}\" was requested but never provided. Ensure a ` +\n            `middleware provides it in setup(), ordered before this consumer.`,\n        )\n      }\n      return values.get(ctx)\n    }\n\n    const provide: CapabilityProvider<TValue> = (ctx, value) => {\n      values.set(ctx, value)\n      ctx.capabilities.markProvided(handle)\n    }\n\n    const pair: readonly [\n      CapabilityGetter<TValue>,\n      CapabilityProvider<TValue>,\n    ] = [get, provide]\n    // Object.assign's return type is the intersection of the tuple and the\n    // props, which IS Capability<TValue, TName> — no cast needed.\n    const handle = Object.assign(pair, {\n      capabilityName: name,\n      has: (ctx: CapabilityContext) => values.has(ctx),\n    })\n    return handle\n  }\n}\n"],"names":[],"mappings":"AA4DO,MAAM,mBAAmB;AAAA,EACb,+BAAe,IAAA;AAAA,EACxB;AAAA;AAAA,EAGR,eAAe,IAAkC;AAC/C,SAAK,cAAc;AAAA,EACrB;AAAA;AAAA,EAGA,aAAa,QAAgC;AAC3C,QAAI,KAAK,SAAS,IAAI,MAAM,EAAG,MAAK,cAAc,OAAO,cAAc;AACvE,SAAK,SAAS,IAAI,MAAM;AAAA,EAC1B;AAAA,EAEA,IAAI,QAAmC;AACrC,WAAO,KAAK,SAAS,IAAI,MAAM;AAAA,EACjC;AACF;AAmCO,SAAS,mBAIe;AAC7B,SAAO,CACL,SAC8B;AAG9B,UAAM,6BAAa,QAAA;AAOnB,aAAS,IACP,KACA,MACoB;AACpB,UAAI,CAAC,OAAO,IAAI,GAAG,GAAG;AACpB,YAAI,MAAM,SAAU,QAAO;AAC3B,cAAM,IAAI;AAAA,UACR,eAAe,IAAI;AAAA,QAAA;AAAA,MAGvB;AACA,aAAO,OAAO,IAAI,GAAG;AAAA,IACvB;AAEA,UAAM,UAAsC,CAAC,KAAK,UAAU;AAC1D,aAAO,IAAI,KAAK,KAAK;AACrB,UAAI,aAAa,aAAa,MAAM;AAAA,IACtC;AAEA,UAAM,OAGF,CAAC,KAAK,OAAO;AAGjB,UAAM,SAAS,OAAO,OAAO,MAAM;AAAA,MACjC,gBAAgB;AAAA,MAChB,KAAK,CAAC,QAA2B,OAAO,IAAI,GAAG;AAAA,IAAA,CAChD;AACD,WAAO;AAAA,EACT;AACF;"}

package/dist/esm/activities/chat/middleware/compose.d.ts

@@ -0,0 +1,87 @@
+import { StreamChunk } from '../../../types.js';
+import { InternalLogger } from '../../../logger/internal-logger.js';
+import { AbortInfo, AfterToolCallInfo, BeforeToolCallDecision, ChatMiddleware, ChatMiddlewareConfig, ChatMiddlewareContext, ErrorInfo, FinishInfo, IterationInfo, 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>>;
+    /**
+     * 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>;
+    /**
+     * Run onFinish on all middleware in order.
+     */
+    runOnFinish(ctx: ChatMiddlewareContext<TContext>, info: FinishInfo): Promise<void>;
+    /**
+     * Run onAbort on all middleware in order.
+     */
+    runOnAbort(ctx: ChatMiddlewareContext<TContext>, info: AbortInfo): Promise<void>;
+    /**
+     * Run onError on all middleware in order.
+     */
+    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 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>;
+}