@cuylabs/agent-core 4.9.0 → 4.10.0

package/dist/middleware/runner.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Middleware Runner
+ *
+ * Executes middleware hooks in the correct order with proper
+ * error handling and short-circuit semantics.
+ *
+ * This is the internal engine — consumers never see it.
+ * They interact with middleware through AgentConfig.middleware.
+ */
+import type { AgentMiddleware, BlockedModelCall, ChatLifecycleContext, ModelCallContext, ModelCallInput, ModelCallOutput, ToolCallDecision, ToolCallOutput } from "./types.js";
+import type { AgentEvent } from "../types/events.js";
+import type { PromptBuildContext, PromptSection } from "../prompt/types.js";
+import type { TokenUsage } from "../types/messages.js";
+import type { StreamChunk } from "../types/stream.js";
+import type { ToolContext } from "../types/tool.js";
+import type { Logger } from "../logger/types.js";
+import type { AgentContextFragmentBuildContext, AgentContextFragmentInput } from "../context/fragments/types.js";
+/**
+ * Middleware runner — holds an ordered list of middleware and
+ * exposes methods to run each hook type with correct semantics.
+ *
+ * Immutable after construction. Fork creates a new runner
+ * (with inherited + additional middleware).
+ */
+export declare class MiddlewareRunner {
+    private readonly stack;
+    private readonly log;
+    constructor(middleware?: AgentMiddleware[], logger?: Logger);
+    /** Number of registered middleware */
+    get count(): number;
+    /** Whether any middleware is registered */
+    get hasMiddleware(): boolean;
+    /** Get the middleware list (for fork inheritance) */
+    getMiddleware(): readonly AgentMiddleware[];
+    runModelInput(input: ModelCallInput, ctx: ModelCallContext): Promise<ModelCallInput | BlockedModelCall>;
+    runModelChunk(chunk: StreamChunk, ctx: ModelCallContext): Promise<StreamChunk | undefined>;
+    runModelOutput(output: ModelCallOutput, ctx: ModelCallContext): Promise<ModelCallOutput>;
+    /**
+     * Run all `beforeToolCall` hooks in order.
+     *
+     * Returns `{ action: "allow" }` if all middleware allow (or have no hook).
+     * Returns `{ action: "deny", reason }` on first denial — remaining
+     * middleware are skipped.
+     *
+     * When a middleware rewrites args via `decision.args`, subsequent
+     * middleware in the chain receive the rewritten args.
+     */
+    runBeforeToolCall(tool: string, args: unknown, ctx: ToolContext): Promise<ToolCallDecision>;
+    /**
+     * Run all `afterToolCall` hooks in reverse order.
+     *
+     * Each hook receives the result from the previous hook (or the
+     * original tool result for the first hook). Errors are caught
+     * and logged — the original result passes through.
+     *
+     * Middleware can add a `supplement` to inject extra text the model
+     * sees alongside the tool output. Supplements chain naturally —
+     * each middleware receives any supplement added by earlier hooks.
+     */
+    runAfterToolCall(tool: string, args: unknown, result: ToolCallOutput, ctx: ToolContext): Promise<ToolCallOutput>;
+    /**
+     * Collect prompt sections from all middleware.
+     *
+     * Returns a flat array of sections. Each middleware can return a single
+     * section, an array of sections, or undefined/empty.
+     */
+    collectPromptSections(ctx: PromptBuildContext): PromptSection[];
+    collectContextFragments(ctx: AgentContextFragmentBuildContext): Promise<AgentContextFragmentInput[]>;
+    /**
+     * Broadcast an event to all middleware observers.
+     *
+     * Non-blocking — errors are caught and logged. This never
+     * slows down the streaming pipeline.
+     */
+    emitEvent(event: AgentEvent): void;
+    /**
+     * Get the OTel context for a session from the telemetry middleware.
+     * Returns undefined if no telemetry middleware is registered.
+     */
+    getOtelContext(sessionId: string, ctx?: ChatLifecycleContext): unknown | undefined;
+    /**
+     * Run all `onChatStart` hooks in order.
+     *
+     * Errors are caught and logged — a broken logger should not
+     * prevent the chat from starting.
+     */
+    runChatStart(sessionId: string, message: string, ctx?: ChatLifecycleContext): Promise<void>;
+    /**
+     * Run all `onChatEnd` hooks in order.
+     *
+     * Always called, even when the stream errored. Errors in handlers
+     * are caught and logged.
+     */
+    runChatEnd(sessionId: string, result: {
+        usage?: TokenUsage;
+        error?: Error;
+        output?: string;
+    }, ctx?: ChatLifecycleContext): Promise<void>;
+}
+//# sourceMappingURL=runner.d.ts.map

package/dist/middleware/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/middleware/runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,cAAc,EACf,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD,OAAO,KAAK,EACV,gCAAgC,EAChC,yBAAyB,EAC1B,MAAM,+BAA+B,CAAC;AAMvC;;;;;;GAMG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA6B;IACnD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;gBAEjB,UAAU,GAAE,eAAe,EAAO,EAAE,MAAM,CAAC,EAAE,MAAM;IAK/D,sCAAsC;IACtC,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,2CAA2C;IAC3C,IAAI,aAAa,IAAI,OAAO,CAE3B;IAED,qDAAqD;IACrD,aAAa,IAAI,SAAS,eAAe,EAAE;IAQrC,aAAa,CACjB,KAAK,EAAE,cAAc,EACrB,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,cAAc,GAAG,gBAAgB,CAAC;IA2BvC,aAAa,CACjB,KAAK,EAAE,WAAW,EAClB,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC;IA4B7B,cAAc,CAClB,MAAM,EAAE,eAAe,EACvB,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,eAAe,CAAC;IAyB3B;;;;;;;;;OASG;IACG,iBAAiB,CACrB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,EACb,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,gBAAgB,CAAC;IAiC5B;;;;;;;;;;OAUG;IACG,gBAAgB,CACpB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,cAAc,EACtB,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,cAAc,CAAC;IAsB1B;;;;;OAKG;IACH,qBAAqB,CAAC,GAAG,EAAE,kBAAkB,GAAG,aAAa,EAAE;IAyBzD,uBAAuB,CAC3B,GAAG,EAAE,gCAAgC,GACpC,OAAO,CAAC,yBAAyB,EAAE,CAAC;IA2BvC;;;;;OAKG;IACH,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAalC;;;OAGG;IACH,cAAc,CACZ,SAAS,EAAE,MAAM,EACjB,GAAG,CAAC,EAAE,oBAAoB,GACzB,OAAO,GAAG,SAAS;IActB;;;;;OAKG;IACG,YAAY,CAChB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,GAAG,CAAC,EAAE,oBAAoB,GACzB,OAAO,CAAC,IAAI,CAAC;IAiBhB;;;;;OAKG;IACG,UAAU,CACd,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE;QAAE,KAAK,CAAC,EAAE,UAAU,CAAC;QAAC,KAAK,CAAC,EAAE,KAAK,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,EAC9D,GAAG,CAAC,EAAE,oBAAoB,GACzB,OAAO,CAAC,IAAI,CAAC;CAYjB"}

package/dist/middleware/telemetry/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * OpenTelemetry middleware module.
+ *
+ * Split by responsibility:
+ * - `types` defines the public tracing contracts
+ * - `otel` owns span creation and middleware lifecycle hooks
+ * - `provider` owns optional SDK/provider bootstrap helpers
+ */
+export { otelMiddleware } from "./otel.js";
+export { createTelemetryConfig } from "./provider.js";
+export type { OtelMiddlewareConfig, TelemetryConfig, TelemetryConfigResult, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/middleware/telemetry/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/middleware/telemetry/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAE3C,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAEtD,YAAY,EACV,oBAAoB,EACpB,eAAe,EACf,qBAAqB,GACtB,MAAM,YAAY,CAAC"}

package/dist/middleware/telemetry/otel.d.ts

@@ -0,0 +1,4 @@
+import type { AgentMiddleware } from "../types.js";
+import type { OtelMiddlewareConfig } from "./types.js";
+export declare function otelMiddleware(config?: OtelMiddlewareConfig): AgentMiddleware;
+//# sourceMappingURL=otel.d.ts.map

package/dist/middleware/telemetry/otel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel.d.ts","sourceRoot":"","sources":["../../../src/middleware/telemetry/otel.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,eAAe,EAGhB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAiLvD,wBAAgB,cAAc,CAC5B,MAAM,GAAE,oBAAyB,GAChC,eAAe,CAyTjB"}

package/dist/middleware/telemetry/provider.d.ts

@@ -0,0 +1,3 @@
+import type { TelemetryConfig, TelemetryConfigResult } from "./types.js";
+export declare function createTelemetryConfig(config: TelemetryConfig): TelemetryConfigResult;
+//# sourceMappingURL=provider.d.ts.map

package/dist/middleware/telemetry/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../../src/middleware/telemetry/provider.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAezE,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,eAAe,GACtB,qBAAqB,CAyDvB"}

package/dist/middleware/telemetry/types.d.ts

@@ -0,0 +1,150 @@
+import type { TelemetryOptions } from "ai";
+import type { SpanProcessor } from "@opentelemetry/sdk-trace-node";
+import type { AgentMiddleware } from "../types.js";
+export type SpanAttributeValue = string | number | boolean | string[] | number[] | boolean[];
+/**
+ * Configuration for the OpenTelemetry middleware.
+ */
+export interface OtelMiddlewareConfig {
+    /**
+     * Whether to record tool call arguments as span attributes.
+     * Defaults to `true`.
+     */
+    recordInputs?: boolean;
+    /**
+     * Whether to record tool results as span attributes.
+     * Defaults to `true`.
+     */
+    recordOutputs?: boolean;
+    /**
+     * Agent name — used in the root span name and attributes.
+     * Falls back to `"agent"`.
+     */
+    agentName?: string;
+    /** Stable agent identifier — recorded as `gen_ai.agent.id` when provided. */
+    agentId?: string;
+    /** Agent description — recorded as `gen_ai.agent.description`. */
+    agentDescription?: string;
+    /** Agent version — recorded as `gen_ai.agent.version` when provided. */
+    agentVersion?: string;
+    /**
+     * Additional attributes applied to agent and tool spans.
+     *
+     * Use this for deployment, tenant, or vendor-specific dimensions that should
+     * flow on every span. Built-in semantic attributes take precedence.
+     */
+    spanAttributes?: Record<string, SpanAttributeValue>;
+    /**
+     * Whether to emit `execute_tool` spans for tool calls.
+     * Defaults to `true`.
+     */
+    emitToolSpans?: boolean;
+    /**
+     * TTL in milliseconds for orphaned spans.
+     * Defaults to 5 minutes.
+     */
+    spanTimeoutMs?: number;
+    /**
+     * Promise that resolves once the TracerProvider is registered.
+     * `ensureTracer()` waits on this before calling `trace.getTracer()`.
+     */
+    providerReady?: Promise<unknown>;
+}
+/**
+ * Configuration for `createTelemetryConfig()`.
+ */
+export interface TelemetryConfig {
+    /** Agent name — used in span names and `gen_ai.agent.name`. */
+    agentName: string;
+    /** Stable agent identifier — recorded as `gen_ai.agent.id` when provided. */
+    agentId?: string;
+    /** Agent description — recorded as `gen_ai.agent.description`. */
+    agentDescription?: string;
+    /** Agent version — recorded as `gen_ai.agent.version` when provided. */
+    agentVersion?: string;
+    /**
+     * Additional attributes applied to agent and tool spans.
+     *
+     * Built-in semantic attributes take precedence.
+     */
+    spanAttributes?: Record<string, SpanAttributeValue>;
+    /**
+     * Enable the AI SDK v7 GenAI OpenTelemetry integration.
+     *
+     * Defaults to `true`. Set to `false` to use only custom/global AI SDK
+     * telemetry integrations, or to disable AI SDK model spans entirely.
+     */
+    useGenAIOpenTelemetry?: boolean;
+    /**
+     * Additional AI SDK v7 telemetry integrations.
+     *
+     * These are passed to `streamText({ telemetry: { integrations } })` together
+     * with the default `GenAIOpenTelemetry` integration unless that default is
+     * disabled via `useGenAIOpenTelemetry: false`.
+     */
+    telemetryIntegrations?: TelemetryOptions["integrations"];
+    /**
+     * Use globally registered AI SDK telemetry integrations when no local
+     * integrations are configured.
+     *
+     * Defaults to `false` because `agent-core` installs a local GenAI integration
+     * by default.
+     */
+    useGlobalTelemetryIntegrations?: boolean;
+    /** Record tool arguments and LLM prompts in spans. Defaults to `true`. */
+    recordInputs?: boolean;
+    /** Record tool results and LLM responses in spans. Defaults to `true`. */
+    recordOutputs?: boolean;
+    /**
+     * Emit `execute_tool` spans from agent-core middleware.
+     *
+     * `createTelemetryConfig()` defaults this to `false` when local AI SDK GenAI
+     * OpenTelemetry is enabled, because AI SDK already emits tool spans for
+     * standard `streamText()` tool execution. `otelMiddleware()` used directly
+     * still defaults to `true`.
+     */
+    emitToolSpans?: boolean;
+    /** TTL in ms for orphaned spans. Defaults to 5 minutes. */
+    spanTimeoutMs?: number;
+    /**
+     * Additional telemetry middleware installed before the default
+     * agent-core OTel middleware.
+     *
+     * Integrations can use this to provide product-specific span lifecycles
+     * while still reusing the AI SDK telemetry settings from this config.
+     */
+    middleware?: AgentMiddleware | AgentMiddleware[];
+    /**
+     * Whether to install agent-core's built-in OTel lifecycle middleware.
+     *
+     * Defaults to `true`. Set to `false` when an integration supplies its own
+     * middleware that creates the agent/tool parent spans and OTel context.
+     */
+    useDefaultOtelMiddleware?: boolean;
+    /**
+     * An OTel `SpanProcessor` to auto-create and register a `NodeTracerProvider`.
+     */
+    spanProcessor?: SpanProcessor;
+    /**
+     * OTel service name for the `NodeTracerProvider` resource.
+     * Defaults to `agentName`.
+     */
+    serviceName?: string;
+}
+/**
+ * Result of `createTelemetryConfig()`.
+ */
+export interface TelemetryConfigResult {
+    /** Agent-core middleware. */
+    middleware: AgentMiddleware;
+    /** Ordered telemetry middleware stack. */
+    middlewares: AgentMiddleware[];
+    /** AI SDK telemetry settings. */
+    telemetry: TelemetryOptions;
+    /**
+     * Flush and shut down the auto-created tracer provider.
+     * No-op when no provider was auto-created.
+     */
+    shutdown: () => Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/middleware/telemetry/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/middleware/telemetry/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,IAAI,CAAC;AAC3C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,MAAM,MAAM,kBAAkB,GAC1B,MAAM,GACN,MAAM,GACN,OAAO,GACP,MAAM,EAAE,GACR,MAAM,EAAE,GACR,OAAO,EAAE,CAAC;AAEd;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IACpD;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,+DAA+D;IAC/D,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IACpD;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;;;;;OAMG;IACH,qBAAqB,CAAC,EAAE,gBAAgB,CAAC,cAAc,CAAC,CAAC;IACzD;;;;;;OAMG;IACH,8BAA8B,CAAC,EAAE,OAAO,CAAC;IACzC,0EAA0E;IAC1E,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,0EAA0E;IAC1E,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,2DAA2D;IAC3D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,eAAe,GAAG,eAAe,EAAE,CAAC;IACjD;;;;;OAKG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC;;OAEG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,6BAA6B;IAC7B,UAAU,EAAE,eAAe,CAAC;IAC5B,0CAA0C;IAC1C,WAAW,EAAE,eAAe,EAAE,CAAC;IAC/B,iCAAiC;IACjC,SAAS,EAAE,gBAAgB,CAAC;IAC5B;;;OAGG;IACH,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B"}

package/dist/middleware/types.d.ts

@@ -0,0 +1,371 @@
+/**
+ * Middleware Types
+ *
+ * Defines the composable middleware interface for agent lifecycle hooks.
+ *
+ * Middleware is just a plain object with optional hook methods — no
+ * base classes, no discovery, no installation. Pass it in code:
+ *
+ * ```typescript
+ * const agent = createAgent({
+ *   middleware: [myLoggerMiddleware, myApprovalMiddleware],
+ * });
+ * ```
+ *
+ * Hooks run in array order for "before" operations and reverse order
+ * for "after" operations (like middleware stacks everywhere).
+ */
+import type { LanguageModel, ModelMessage, SystemModelMessage, TelemetryOptions } from "ai";
+import type { ProviderOptions } from "@ai-sdk/provider-utils";
+import type { AgentEvent } from "../types/events.js";
+import type { PromptBuildContext, PromptSection } from "../prompt/types.js";
+import type { Message, TokenUsage } from "../types/messages.js";
+import type { RecentMessagesOptions as SessionRecentMessagesOptions } from "../storage/manager/types.js";
+import type { ScopeSnapshot } from "../execution/scope/types.js";
+import type { StreamChunk, StreamProvider } from "../types/stream.js";
+import type { ToolContext } from "../types/tool.js";
+import type { Tool } from "../tool/tool.js";
+import type { ReasoningLevel } from "../models/reasoning/index.js";
+import type { ApprovalCorrection } from "../safety/types.js";
+import type { AgentContextFragmentBuildContext, AgentContextFragmentInput } from "../context/fragments/types.js";
+/**
+ * Action returned by `beforeToolCall` — determines whether
+ * the tool call proceeds or is blocked.
+ */
+export interface ToolCallDecision {
+    /** Whether to allow or deny the tool call */
+    action: "allow" | "deny";
+    /** Reason for denial — returned to the model as the tool output */
+    reason?: string;
+    /**
+     * Structured correction metadata for denied tool calls.
+     *
+     * Hosts and runtimes can persist this even though the model still receives
+     * a string tool result.
+     */
+    correction?: ApprovalCorrection;
+    /**
+     * Rewritten tool arguments. When present, replaces the original
+     * args for the remainder of the execution pipeline (schema validation,
+     * baseline capture, and execution).
+     *
+     * Only meaningful when `action` is `"allow"`. Use this for path
+     * rewriting, sandbox prefixing, argument sanitization, or injecting
+     * default values — without the tool knowing about the transformation.
+     *
+     * @example
+     * ```typescript
+     * beforeToolCall: async (tool, args, ctx) => {
+     *   if (tool === "write_file") {
+     *     const a = args as { path: string };
+     *     return {
+     *       action: "allow",
+     *       args: { ...a, path: resolveSandboxPath(a.path) },
+     *     };
+     *   }
+     *   return { action: "allow" };
+     * },
+     * ```
+     */
+    args?: unknown;
+}
+/**
+ * Mutable model invocation payload presented to middleware before an LLM call.
+ */
+export interface ModelCallInput {
+    model: LanguageModel;
+    system: string[];
+    messages: ModelMessage[];
+    temperature?: number;
+    topP?: number;
+    maxOutputTokens?: number;
+    maxSteps?: number;
+    reasoningLevel?: ReasoningLevel;
+    telemetry?: TelemetryOptions;
+    customStreamProvider?: StreamProvider;
+    toolExecutionMode?: "auto" | "plan";
+    /**
+     * Provider-specific options passed through to `streamText()`.
+     *
+     * Middleware can set these to enable provider features like Anthropic
+     * prompt caching (`{ anthropic: { cacheControl: { type: "ephemeral" } } }`).
+     *
+     * When multiple sources set providerOptions (e.g. middleware + reasoning),
+     * they are shallow-merged before the LLM call.
+     */
+    providerOptions?: ProviderOptions;
+    /**
+     * System messages with provider-specific options.
+     *
+     * When set, these take precedence over the plain `system` strings.
+     * This allows middleware to attach per-message metadata such as
+     * Anthropic `cacheControl` breakpoints on system content.
+     *
+     * Leave undefined to use the plain `system` string array.
+     */
+    systemMessages?: SystemModelMessage[];
+}
+/**
+ * Context shared across model middleware hooks for a single step.
+ */
+export interface ModelCallContext {
+    sessionID: string;
+    turnID?: string;
+    step: number;
+    cwd: string;
+    abort: AbortSignal;
+    model: LanguageModel;
+    toolNames: string[];
+    mcpToolNames: string[];
+    scope?: ScopeSnapshot;
+}
+/**
+ * Return this from `model.input(...)` to stop an LLM call entirely.
+ */
+export interface BlockedModelCall {
+    block: true;
+    reason: string;
+}
+/** Type guard for `BlockedModelCall`. */
+export declare function isBlockedModelCall(value: ModelCallInput | BlockedModelCall): value is BlockedModelCall;
+/**
+ * Final step result exposed to model middleware after the stream is processed.
+ */
+export interface ModelCallOutput {
+    text: string;
+    usage?: TokenUsage;
+    finishReason?: string;
+}
+/**
+ * Context shared across chat lifecycle hooks for a single turn.
+ */
+export interface ChatLifecycleContext {
+    sessionId: string;
+    turnId?: string;
+    history?: HistoryAccessor;
+}
+/**
+ * Options for reading a bounded slice of recent visible chat messages.
+ */
+export type RecentMessagesOptions = Pick<SessionRecentMessagesOptions, "limit" | "roles">;
+/**
+ * Lazy chat-history accessor exposed to lifecycle middleware.
+ *
+ * The chat loop passes this accessor by reference; messages are only read and
+ * deserialized if middleware calls it.
+ */
+export interface HistoryAccessor {
+    getRecentMessages(options?: RecentMessagesOptions): Message[];
+}
+/**
+ * Extended tool result returned by `afterToolCall` middleware.
+ *
+ * Same shape as `Tool.ExecuteResult` with an optional `supplement` —
+ * extra text appended to the tool output for model visibility.
+ *
+ * Use this to inject warnings, guidance, lint results, or annotations
+ * that the model should see alongside the tool's own output, without
+ * modifying the tool's result directly.
+ *
+ * When multiple middleware add supplements, each one receives the
+ * previous supplement (if any) and can extend or replace it.
+ *
+ * @example
+ * ```typescript
+ * afterToolCall: async (tool, args, result) => {
+ *   if (tool === "write_file") {
+ *     const warnings = await lintFile(args.path);
+ *     return { ...result, supplement: warnings };
+ *   }
+ *   return result;
+ * },
+ * ```
+ */
+export interface ToolCallOutput extends Tool.ExecuteResult {
+    /**
+     * Supplementary text appended to the tool output for the model.
+     *
+     * Kept separate from `output` so the original tool result stays
+     * untouched. The executor merges this into the final output string
+     * before returning it to the model.
+     */
+    supplement?: string;
+}
+/**
+ * Optional model-specific hooks grouped under `middleware.model`.
+ */
+export interface AgentModelHooks {
+    /**
+     * Review or rewrite the model request before the LLM is invoked.
+     *
+     * Return:
+     * - `undefined` to keep the current request
+     * - a `ModelCallInput` object to replace the request
+     * - `{ block: true, reason }` to cancel the model call
+     *
+     * Hooks run in middleware array order. The first block stops the call.
+     */
+    input?(input: ModelCallInput, ctx: ModelCallContext): Promise<ModelCallInput | BlockedModelCall | void>;
+    /**
+     * Review or rewrite raw stream chunks as they arrive from the model.
+     *
+     * Return:
+     * - `undefined` to keep the current chunk
+     * - a `StreamChunk` to replace it
+     * - `null` to drop it from downstream processing
+     *
+     * Hooks run in middleware array order.
+     */
+    chunk?(chunk: StreamChunk, ctx: ModelCallContext): Promise<StreamChunk | null | void>;
+    /**
+     * Review or rewrite the fully processed model result for the current step.
+     *
+     * Hooks run in reverse middleware order so outer middleware sees the final
+     * shaped result, matching `afterToolCall(...)`.
+     */
+    output?(output: ModelCallOutput, ctx: ModelCallContext): Promise<ModelCallOutput | void>;
+}
+/**
+ * Agent middleware — composable lifecycle hooks.
+ *
+ * All methods are optional. Implement only what you need.
+ *
+ * Ordering:
+ * - `beforeToolCall`: runs in array order, first "deny" wins
+ * - `afterToolCall`: runs in reverse order (innermost first)
+ * - `model.input`: runs in array order, first block wins
+ * - `model.chunk`: runs in array order on raw stream chunks
+ * - `model.output`: runs in reverse order
+ * - `promptSections`: all run, sections merged
+ * - `onEvent`: all run synchronously, errors logged, never blocks the stream
+ * - `onChatStart` / `onChatEnd`: run in array order, awaited sequentially
+ *
+ * @example
+ * ```typescript
+ * // A simple logging middleware
+ * const logger: AgentMiddleware = {
+ *   name: "logger",
+ *   beforeToolCall: async (tool, args) => {
+ *     console.log(`→ ${tool}`, args);
+ *     return { action: "allow" };
+ *   },
+ *   afterToolCall: async (tool, args, result) => {
+ *     console.log(`← ${tool}`, result.title);
+ *     return result;
+ *   },
+ * };
+ * ```
+ */
+export interface AgentMiddleware {
+    /** Middleware name (for logging and debugging) */
+    name: string;
+    /**
+     * Optional hooks for shaping model requests, raw stream chunks,
+     * and final step outputs.
+     */
+    model?: AgentModelHooks;
+    /**
+     * Intercept a tool call before execution.
+     *
+     * Return `{ action: "allow" }` to proceed, or `{ action: "deny", reason }` to
+     * block the call. When denied, `reason` is returned to the model as the tool
+     * output so it can adjust its approach.
+     *
+     * Runs in array order. The first middleware that returns "deny" short-circuits
+     * the chain — remaining middleware and the tool itself are skipped.
+     *
+     * @param tool   - Tool name (e.g. "bash", "write_file")
+     * @param args   - Parsed tool arguments
+     * @param ctx    - Tool execution context (cwd, sessionID, host, etc.)
+     */
+    beforeToolCall?(tool: string, args: unknown, ctx: ToolContext): Promise<ToolCallDecision>;
+    /**
+     * Transform or observe a tool result after execution.
+     *
+     * Receives the result and must return a result (can be the same object
+     * or a modified copy). Runs in reverse array order so the outermost
+     * middleware sees the final transformed result.
+     *
+     * @param tool   - Tool name
+     * @param args   - Original tool arguments
+     * @param result - Tool execution result
+     * @param ctx    - Tool execution context
+     */
+    afterToolCall?(tool: string, args: unknown, result: ToolCallOutput, ctx: ToolContext): Promise<ToolCallOutput>;
+    /**
+     * Inject dynamic prompt sections at build time.
+     *
+     * Called during `PromptBuilder.build()` for each middleware. Return one
+     * or more sections to inject into the system prompt. Return `undefined`
+     * or an empty array to inject nothing.
+     *
+     * Sections follow the same priority system as static sections — use
+     * `priority` to control placement relative to base template (10),
+     * environment (20), instructions (30), custom (50), skills (70),
+     * and per-turn overrides (90).
+     *
+     * @param ctx - Build context with cwd, model, toolNames, sessionId
+     */
+    promptSections?(ctx: PromptBuildContext): PromptSection | PromptSection[] | undefined;
+    /**
+     * Inject typed model-visible context messages before each model step.
+     *
+     * Use this for runtime/session context that should be distinguishable from
+     * normal user conversation: environment snapshots, memory recall, workflow
+     * hints, or hook-added context. Returned context fragments are transient
+     * unless the caller also persists them through
+     * `SessionManager.addContextFragment(...)`.
+     */
+    contextFragments?(ctx: AgentContextFragmentBuildContext): AgentContextFragmentInput | AgentContextFragmentInput[] | undefined | Promise<AgentContextFragmentInput | AgentContextFragmentInput[] | undefined>;
+    /**
+     * Observe agent events (read-only, non-blocking).
+     *
+     * Fires for every event emitted during `chat()`. Errors thrown by
+     * handlers are caught and logged — they never interrupt the stream.
+     *
+     * This is intentionally synchronous (void return) to prevent
+     * event observers from blocking the streaming pipeline.
+     *
+     * @param event - The agent event
+     */
+    onEvent?(event: AgentEvent): void;
+    /**
+     * Called when `chat()` starts, before the LLM stream is created.
+     *
+     * Use this for setup: initializing loggers, recording start time,
+     * resetting per-turn state, etc. Runs in array order, awaited
+     * sequentially.
+     *
+     * @param sessionId - Session identifier
+     * @param message   - The user message being sent
+     */
+    onChatStart?(sessionId: string, message: string, ctx?: ChatLifecycleContext): Promise<void>;
+    /**
+     * Called when `chat()` completes (or errors), after all events
+     * have been yielded.
+     *
+     * Use this for teardown: flushing logs, recording metrics, etc.
+     * Runs in array order, awaited sequentially. Always called, even
+     * if the stream errored.
+     *
+     * Turn-scoped tool cleanup runs after `onChatEnd`, so middleware can still
+     * inspect the just-resolved turn tool objects during this hook.
+     *
+     * @param sessionId - Session identifier
+     * @param result    - Completion info (usage stats and optional error)
+     */
+    onChatEnd?(sessionId: string, result: {
+        usage?: TokenUsage;
+        error?: Error;
+        output?: string;
+    }, ctx?: ChatLifecycleContext): Promise<void>;
+    /**
+     * Get the active OTel context for a session.
+     *
+     * Used internally by the LLM layer to wrap `streamText()` so that
+     * AI SDK spans are nested under the middleware's parent span.
+     * Only implemented by the `otelMiddleware`.
+     */
+    getOtelContext?(sessionId: string, ctx?: ChatLifecycleContext): unknown;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/middleware/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/middleware/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EACjB,MAAM,IAAI,CAAC;AACZ,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,KAAK,EAAE,qBAAqB,IAAI,4BAA4B,EAAE,MAAM,6BAA6B,CAAC;AACzG,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACtE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,KAAK,EACV,gCAAgC,EAChC,yBAAyB,EAC1B,MAAM,+BAA+B,CAAC;AAMvC;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6CAA6C;IAC7C,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC;IACzB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,kBAAkB,CAAC;IAChC;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,aAAa,CAAC;IACrB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,oBAAoB,CAAC,EAAE,cAAc,CAAC;IACtC,iBAAiB,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACpC;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,kBAAkB,EAAE,CAAC;CACvC;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,WAAW,CAAC;IACnB,KAAK,EAAE,aAAa,CAAC;IACrB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,IAAI,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,yCAAyC;AACzC,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,cAAc,GAAG,gBAAgB,GACvC,KAAK,IAAI,gBAAgB,CAE3B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,eAAe,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,IAAI,CACtC,4BAA4B,EAC5B,OAAO,GAAG,OAAO,CAClB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,iBAAiB,CAAC,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,EAAE,CAAC;CAC/D;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,cAAe,SAAQ,IAAI,CAAC,aAAa;IACxD;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;;;OASG;IACH,KAAK,CAAC,CACJ,KAAK,EAAE,cAAc,EACrB,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,cAAc,GAAG,gBAAgB,GAAG,IAAI,CAAC,CAAC;IAErD;;;;;;;;;OASG;IACH,KAAK,CAAC,CACJ,KAAK,EAAE,WAAW,EAClB,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,WAAW,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC;IAEtC;;;;;OAKG;IACH,MAAM,CAAC,CACL,MAAM,EAAE,eAAe,EACvB,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,WAAW,eAAe;IAC9B,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,KAAK,CAAC,EAAE,eAAe,CAAC;IAExB;;;;;;;;;;;;;OAaG;IACH,cAAc,CAAC,CACb,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,EACb,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAE7B;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,CACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,cAAc,EACtB,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,cAAc,CAAC,CAAC;IAE3B;;;;;;;;;;;;;OAaG;IACH,cAAc,CAAC,CACb,GAAG,EAAE,kBAAkB,GACtB,aAAa,GAAG,aAAa,EAAE,GAAG,SAAS,CAAC;IAE/C;;;;;;;;OAQG;IACH,gBAAgB,CAAC,CACf,GAAG,EAAE,gCAAgC,GAEnC,yBAAyB,GACzB,yBAAyB,EAAE,GAC3B,SAAS,GACT,OAAO,CACL,yBAAyB,GAAG,yBAAyB,EAAE,GAAG,SAAS,CACpE,CAAC;IAEN;;;;;;;;;;OAUG;IACH,OAAO,CAAC,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IAElC;;;;;;;;;OASG;IACH,WAAW,CAAC,CACV,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,GAAG,CAAC,EAAE,oBAAoB,GACzB,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,CACR,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE;QAAE,KAAK,CAAC,EAAE,UAAU,CAAC;QAAC,KAAK,CAAC,EAAE,KAAK,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,EAC9D,GAAG,CAAC,EAAE,oBAAoB,GACzB,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;;;OAMG;IACH,cAAc,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC;CACzE"}