@cuylabs/agent-core 4.9.0 → 5.0.0

package/dist/middleware/runner.d.ts

@@ -0,0 +1,115 @@
+/**
+ * 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, ContextCompactionHookContext, 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[]>;
+    /**
+     * Run all `beforeContextCompactionCommit` hooks in order.
+     *
+     * Hooks are awaited because durability work, such as memory capture, must
+     * complete before old context is replaced. Errors are logged and do not abort
+     * compaction.
+     */
+    runBeforeContextCompactionCommit(ctx: ContextCompactionHookContext): Promise<void>;
+    /**
+     * Run all `afterContextCompactionCommit` hooks in reverse order.
+     *
+     * This mirrors `afterToolCall` / `model.output` ordering. Errors are logged
+     * and do not abort the turn.
+     */
+    runAfterContextCompactionCommit(ctx: ContextCompactionHookContext): Promise<void>;
+    /**
+     * 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":"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"}

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"}