@cuylabs/agent-core 4.9.0 → 4.10.0

package/dist/memory/types.d.ts

@@ -0,0 +1,232 @@
+import type { Message, TokenUsage } from "../types/messages.js";
+import type { Tool } from "../tool/tool.js";
+import type { AgentContextCompactionPhase } from "../types/events.js";
+export type AgentMemoryScope = "session" | "project" | "user" | "global";
+export interface AgentMemoryRecord {
+    id: string;
+    content: string;
+    title?: string;
+    kind?: string;
+    scope?: AgentMemoryScope;
+    score?: number;
+    source?: string;
+    tags?: string[];
+    createdAt?: string;
+    updatedAt?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface AgentMemoryRecallInput {
+    sessionId: string;
+    turnId?: string;
+    step: number;
+    cwd: string;
+    query: string;
+    messages: readonly Message[];
+    limit: number;
+    toolNames: readonly string[];
+    mcpToolNames: readonly string[];
+    abort?: AbortSignal;
+}
+export interface AgentMemoryRecallResult {
+    records: AgentMemoryRecord[];
+    query?: string;
+    instructions?: string;
+    metadata?: Record<string, unknown>;
+}
+export type AgentMemoryRecallResponse = AgentMemoryRecallResult | AgentMemoryRecord[] | undefined;
+export type AgentMemoryRecallFrequency = "per-turn" | "per-step";
+export interface AgentMemorySearchInput {
+    sessionId: string;
+    turnId?: string;
+    cwd: string;
+    query: string;
+    limit: number;
+    scope?: AgentMemoryScope;
+    tags?: string[];
+    abort?: AbortSignal;
+}
+export interface AgentMemoryListInput {
+    sessionId: string;
+    turnId?: string;
+    cwd: string;
+    limit: number;
+    scope?: AgentMemoryScope;
+    tags?: string[];
+    abort?: AbortSignal;
+}
+export interface AgentMemorySearchResult {
+    records: AgentMemoryRecord[];
+    query?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface AgentMemoryRememberInput {
+    sessionId: string;
+    turnId?: string;
+    cwd: string;
+    content: string;
+    title?: string;
+    /** Provider-specific record kind, for example preference, fact, summary, or turn-extraction. */
+    kind?: string;
+    scope?: AgentMemoryScope;
+    /** Provider-specific write source, for example memory_remember, turn_end, or compaction. */
+    source?: string;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+    abort?: AbortSignal;
+}
+export interface AgentMemoryWriteResult {
+    record: AgentMemoryRecord;
+    created?: boolean;
+    updated?: boolean;
+    metadata?: Record<string, unknown>;
+}
+export interface AgentMemoryForgetInput {
+    sessionId: string;
+    turnId?: string;
+    cwd: string;
+    id: string;
+    scope?: AgentMemoryScope;
+    abort?: AbortSignal;
+}
+export interface AgentMemoryForgetResult {
+    id: string;
+    removed: boolean;
+    reason?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface AgentMemoryTurnEndInput {
+    sessionId: string;
+    turnId?: string;
+    cwd: string;
+    input: string;
+    output?: string;
+    error?: Error;
+    usage?: TokenUsage;
+    messages: readonly Message[];
+    abort?: AbortSignal;
+}
+export interface AgentMemoryTurnStartInput {
+    sessionId: string;
+    turnId?: string;
+    cwd: string;
+    input: string;
+    messages: readonly Message[];
+    abort?: AbortSignal;
+}
+export interface AgentMemoryCompactionInput {
+    sessionId: string;
+    turnId?: string;
+    cwd: string;
+    phase?: AgentContextCompactionPhase;
+    removedMessages: readonly Message[];
+    keptMessages: readonly Message[];
+    summary?: string;
+    abort?: AbortSignal;
+}
+export interface AgentMemoryCompactionResult {
+    notes?: AgentMemoryRecord[];
+    metadata?: Record<string, unknown>;
+}
+export interface AgentMemoryGetToolsInput {
+    deferred: boolean;
+}
+/**
+ * Pluggable durable-memory adapter used by agent-core.
+ *
+ * The provider owns storage, retrieval quality, write policy, and any external
+ * service calls. Agent-core owns when the provider is invoked: automatic
+ * recall for a user turn or model step, tools at agent setup, turn lifecycle
+ * hooks around chat, and the compaction preparation hook before old messages
+ * are removed from context.
+ */
+export interface AgentMemoryProvider {
+    /** Stable provider id used in middleware names, context-fragment metadata, and diagnostics. */
+    id: string;
+    /**
+     * Read-only automatic recall for the current user turn or model step.
+     *
+     * The `query` is the latest user message chosen by core. Providers also
+     * receive visible messages and can ignore or rewrite that query internally.
+     */
+    recall?(input: AgentMemoryRecallInput): Promise<AgentMemoryRecallResponse> | AgentMemoryRecallResponse;
+    /** Provider-backed deliberate lookup, usually exposed through a memory search tool. */
+    search?(input: AgentMemorySearchInput): Promise<AgentMemorySearchResult | AgentMemoryRecord[]> | AgentMemorySearchResult | AgentMemoryRecord[];
+    /** Provider-backed browsing/listing, usually exposed through a memory list tool. */
+    list?(input: AgentMemoryListInput): Promise<AgentMemorySearchResult | AgentMemoryRecord[]> | AgentMemorySearchResult | AgentMemoryRecord[];
+    /** Store durable knowledge. The provider decides dedupe, scopes, indexes, and consolidation. */
+    remember?(input: AgentMemoryRememberInput): Promise<AgentMemoryWriteResult> | AgentMemoryWriteResult;
+    /** Remove stale or incorrect durable knowledge. */
+    forget?(input: AgentMemoryForgetInput): Promise<AgentMemoryForgetResult> | AgentMemoryForgetResult;
+    /** Called at the start of a user turn when memory capture is enabled. */
+    onTurnStart?(input: AgentMemoryTurnStartInput): Promise<void> | void;
+    /** Called after a user turn completes when memory capture is enabled. */
+    onTurnEnd?(input: AgentMemoryTurnEndInput): Promise<void> | void;
+    /**
+     * Called before context compaction drops old messages.
+     *
+     * This is the right place to persist durable facts from messages that are
+     * about to leave the model-visible window. It does not replace or mutate the
+     * compaction algorithm.
+     */
+    prepareForCompaction?(input: AgentMemoryCompactionInput): Promise<AgentMemoryCompactionResult | void> | AgentMemoryCompactionResult | void;
+    /** Return provider-owned tools. Agent-core installs them when memory tools are enabled. */
+    getTools?(input: AgentMemoryGetToolsInput): Tool.AnyInfo[];
+    /** Dispose provider resources such as database handles, workers, or network clients. */
+    shutdown?(): Promise<void> | void;
+}
+export interface AgentMemoryRecallConfig {
+    /** Disable automatic pre-step recall without disabling memory tools or hooks. */
+    enabled?: boolean;
+    /**
+     * How often automatic recall runs.
+     *
+     * `per-turn` recalls once for the latest user turn and reuses that result
+     * across tool-loop model steps. `per-step` lets providers recompute recall
+     * before every model step.
+     *
+     * Default: `per-turn`
+     */
+    frequency?: AgentMemoryRecallFrequency;
+    /** Provider-facing desired recall count. Providers may treat this as a hint. */
+    limit?: number;
+    /** Hard cap on records injected into the current model step. */
+    maxRecords?: number;
+    /** Hard cap on each injected record's content. */
+    maxRecordChars?: number;
+}
+export interface AgentMemoryToolsConfig {
+    /** Disable provider-returned tools without disabling automatic recall or hooks. */
+    enabled?: boolean;
+    /** Ask provider tools to use deferred execution when they support it. */
+    deferred?: boolean;
+}
+export interface AgentMemoryTurnConfig {
+    /** Disable provider turn lifecycle hooks without disabling recall or tools. */
+    enabled?: boolean;
+    /**
+     * Number of additional recent visible messages passed to
+     * onTurnStart/onTurnEnd as surrounding context.
+     *
+     * The current turn input/output are passed as explicit fields and do not
+     * count toward this limit.
+     */
+    contextMessageLimit?: number;
+}
+export interface AgentMemoryConfig {
+    /** Provider instance. Use a provider factory for provider-specific configuration. */
+    provider: AgentMemoryProvider;
+    /** Core recall controls. Provider-specific recall strategy lives in the provider. */
+    recall?: boolean | AgentMemoryRecallConfig;
+    /** Core turn lifecycle controls. Provider-specific extraction policy lives in the provider. */
+    turns?: boolean | AgentMemoryTurnConfig;
+    /** Core tool registration controls. Provider-specific tool design lives in the provider. */
+    tools?: boolean | AgentMemoryToolsConfig;
+}
+export type AgentMemoryInput = AgentMemoryProvider | AgentMemoryConfig;
+export interface ResolvedAgentMemoryConfig {
+    provider: AgentMemoryProvider;
+    recall: Required<AgentMemoryRecallConfig>;
+    turns: Required<AgentMemoryTurnConfig>;
+    tools: Required<AgentMemoryToolsConfig>;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/memory/types.ts"],"names":[],"mappings":"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"}

package/dist/middleware/approval.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Approval Middleware
+ *
+ * Wraps the existing approval system as an AgentMiddleware.
+ * This is how approval finally gets wired into the tool execution
+ * pipeline — no more dead code.
+ *
+ * @example
+ * ```typescript
+ * import { createAgent, approvalMiddleware } from "@cuylabs/agent-core";
+ *
+ * const agent = createAgent({
+ *   model: anthropic("claude-sonnet-4-20250514"),
+ *   tools: [read, write, bash],
+ *   middleware: [
+ *     approvalMiddleware({
+ *       rules: [
+ *         { pattern: "src/*", tool: "read_file", action: "allow" },
+ *       ],
+ *       onRequest: async (req) => {
+ *         // Prompt user in your UI
+ *         return await askUser(req);
+ *       },
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+import type { AgentMiddleware } from "./types.js";
+import { type ApprovalHandler, type ApprovalConfig, type RiskLevel } from "../safety/index.js";
+/**
+ * Configuration for the approval middleware.
+ *
+ * Extends the existing ApprovalConfig with middleware-specific options.
+ */
+export interface ApprovalMiddlewareConfig extends ApprovalConfig {
+    /**
+     * Custom risk classification for tools.
+     *
+     * Overrides the built-in risk map. Tools not listed here
+     * fall back to the default classification.
+     *
+     * @example
+     * ```typescript
+     * customRisks: {
+     *   "my_deploy_tool": "dangerous",
+     *   "my_lint_tool": "safe",
+     * }
+     * ```
+     */
+    customRisks?: Record<string, RiskLevel>;
+}
+export interface ApprovalAgentMiddleware extends AgentMiddleware {
+    name: "approval";
+    readonly approvalHandler: ApprovalHandler;
+    readonly approvalCustomRisks?: Record<string, RiskLevel>;
+}
+export declare function isApprovalMiddleware(value: AgentMiddleware): value is ApprovalAgentMiddleware;
+/**
+ * Create an approval middleware from an ApprovalConfig.
+ *
+ * This bridges the existing `createApprovalHandler` into the middleware
+ * system. The `beforeToolCall` hook checks rules, classifies risk,
+ * and calls the approval handler when needed.
+ *
+ * @param config - Approval configuration (rules, handler, timeout, etc.)
+ * @returns An AgentMiddleware that gates tool execution
+ */
+export declare function approvalMiddleware(config?: ApprovalMiddlewareConfig): ApprovalAgentMiddleware;
+//# sourceMappingURL=approval.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"approval.d.ts","sourceRoot":"","sources":["../../src/middleware/approval.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAoB,MAAM,YAAY,CAAC;AACpE,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,SAAS,EAIf,MAAM,oBAAoB,CAAC;AAE5B;;;;GAIG;AACH,MAAM,WAAW,wBAAyB,SAAQ,cAAc;IAC9D;;;;;;;;;;;;;OAaG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,uBAAwB,SAAQ,eAAe;IAC9D,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;IAC1C,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;CAC1D;AAED,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,eAAe,GACrB,KAAK,IAAI,uBAAuB,CAOlC;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,GAAE,wBAA6B,GACpC,uBAAuB,CAuCzB"}

package/dist/middleware/index.d.ts

@@ -1,112 +1,26 @@
-import { b_ as OtelMiddlewareConfig, N as AgentMiddleware, ds as TelemetryConfig, dt as TelemetryConfigResult } from '../instance-Bg61WSyz.js';
-export { O as AgentModelHooks, ah as ApprovalAgentMiddleware, as as ApprovalMiddlewareConfig, az as BlockedModelCall, aB as ChatLifecycleContext, bh as HistoryAccessor, b as MiddlewareRunner, d as ModelCallContext, bT as ModelCallInput, bU as ModelCallOutput, dv as ToolCallDecision, dw as ToolCallOutput, dM as approvalMiddleware, dZ as isApprovalMiddleware, d_ as isBlockedModelCall } from '../instance-Bg61WSyz.js';
-import '../types-C_LCeYNg.js';
-import 'ai';
-import '../types-RSCv7nQ4.js';
-import 'zod';
-import '../types-CQaXbRsS.js';
-import '../types-DMjoFKKv.js';
-import '@modelcontextprotocol/sdk/client/auth.js';
-import '@modelcontextprotocol/sdk/types.js';
-import '@ai-sdk/provider-utils';
-import '../sandbox/index.js';
-import '../llm-error-D93FNNLY.js';
-
-declare function otelMiddleware(config?: OtelMiddlewareConfig): AgentMiddleware;
-
-declare function createTelemetryConfig(config: TelemetryConfig): TelemetryConfigResult;
-
 /**
- * Prompt Cache Middleware — Type definitions.
- *
- * The middleware auto-detects the model provider and applies the right
- * caching strategy. Currently supports Anthropic's `cache_control`
- * with ephemeral breakpoints. Other providers pass through unchanged
- * until their caching strategy is implemented.
- */
-/**
- * Supported cache TTL values.
- *
- * - `"5m"` — 5-minute cache (default, ~90% input cost reduction on Anthropic)
- * - `"1h"` — 1-hour cache (higher write cost, longer retention)
- */
-type CacheTTL = "5m" | "1h";
-/**
- * Configuration for the prompt cache middleware.
- *
- * @example
- * ```typescript
- * // Auto-detect provider, 5-minute TTL
- * promptCacheMiddleware()
- *
- * // Custom TTL
- * promptCacheMiddleware({ ttl: "1h" })
- *
- * // Custom breakpoint strategy (Anthropic)
- * promptCacheMiddleware({ messageBreakpoints: 2 })
- * ```
- */
-interface PromptCacheConfig {
-    /**
-     * Cache TTL. Defaults to `"5m"`.
-     *
-     * - `"5m"` — 5 minutes.
-     * - `"1h"` — 1 hour.
-     */
-    ttl?: CacheTTL;
-    /**
-     * Number of cache breakpoints to place on conversation messages.
-     *
-     * For Anthropic: max 4 breakpoints total (system always gets 1).
-     * This controls additional breakpoints on conversation messages.
-     *
-     * Defaults to `1` (system + 1 message boundary = 2 breakpoints).
-     * Set to `0` to only cache the system prompt.
-     */
-    messageBreakpoints?: number;
-}
-
-/**
- * Prompt Cache Middleware — provider-dispatched prompt caching.
- *
- * Auto-detects the model provider and applies the right caching strategy:
- *
- * - **Anthropic**: Sets `cache_control: { type: "ephemeral" }` breakpoints
- *   on system prompt and stable conversation messages. Up to 4 breakpoints.
- *
- * - **Other providers**: Pass through unchanged (strategies can be added).
- *
- * @example
- * ```typescript
- * import { promptCacheMiddleware } from "@cuylabs/agent-core/middleware";
- *
- * const agent = createAgent({
- *   model: anthropic("claude-sonnet-4-20250514"),
- *   middleware: [promptCacheMiddleware()],
- * });
- * ```
- */
-
-/**
- * Create a prompt cache middleware that auto-detects the model provider
- * and applies the right caching strategy.
- *
- * Currently supported:
- * - **Anthropic** — `cache_control` breakpoints on system + messages
- *
- * Unsupported providers pass through unchanged.
- *
- * @param config - Optional TTL and breakpoint settings
- *
- * @example
- * ```typescript
- * // Works with any supported provider — auto-detects
- * const agent = createAgent({
- *   model: anthropic("claude-sonnet-4-20250514"),
- *   middleware: [promptCacheMiddleware()],
- * });
- * ```
+ * Middleware Module
+ *
+ * Middleware customizes agent behavior around the main execution loop:
+ * - `model.input` can review, rewrite, or block model requests
+ * - `model.chunk` can transform or drop raw model stream chunks
+ * - `model.output` can shape the finalized step result
+ * - `beforeToolCall` can allow or deny tool invocations
+ * - `afterToolCall` can transform tool results
+ * - `promptSections` can inject dynamic prompt content
+ * - `onEvent`, `onChatStart`, and `onChatEnd` observe lifecycle activity
+ *
+ * Middleware changes behavior inside the current execution scope. The `scope`
+ * module carries ambient lineage and correlation for the active task, turn,
+ * step, or tool call.
+ *
+ * `MiddlewareRunner` owns hook ordering and execution. The built-in factories
+ * here cover approval flows, OpenTelemetry/tracing, and prompt caching.
  */
-declare function promptCacheMiddleware(config?: PromptCacheConfig): AgentMiddleware;
-
-export { AgentMiddleware, type CacheTTL, OtelMiddlewareConfig, type PromptCacheConfig, TelemetryConfig, TelemetryConfigResult, createTelemetryConfig, otelMiddleware, promptCacheMiddleware };
+export type { AgentMiddleware, ChatLifecycleContext, HistoryAccessor, AgentModelHooks, BlockedModelCall, ModelCallContext, ModelCallInput, ModelCallOutput, ToolCallDecision, ToolCallOutput, } from "./types.js";
+export { isBlockedModelCall } from "./types.js";
+export { MiddlewareRunner } from "./runner.js";
+export { approvalMiddleware, isApprovalMiddleware, type ApprovalAgentMiddleware, type ApprovalMiddlewareConfig, } from "./approval.js";
+export { otelMiddleware, type OtelMiddlewareConfig, createTelemetryConfig, type TelemetryConfig, type TelemetryConfigResult, } from "./telemetry/index.js";
+export { promptCacheMiddleware, type PromptCacheConfig, type CacheTTL, } from "./prompt-cache/index.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/middleware/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,YAAY,EACV,eAAe,EACf,oBAAoB,EACpB,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAGhD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG/C,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,GAC9B,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,cAAc,EACd,KAAK,oBAAoB,EACzB,qBAAqB,EACrB,KAAK,eAAe,EACpB,KAAK,qBAAqB,GAC3B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,qBAAqB,EACrB,KAAK,iBAAiB,EACtB,KAAK,QAAQ,GACd,MAAM,yBAAyB,CAAC"}

package/dist/middleware/index.js

@@ -5,10 +5,10 @@ import {
   isApprovalMiddleware,
   otelMiddleware,
   promptCacheMiddleware
-} from "../chunk-GEBFHREI.js";
+} from "../chunk-TU5KDFWI.js";
 import {
   isBlockedModelCall
-} from "../chunk-CJI7PVS2.js";
+} from "../chunk-W6LWIMIX.js";
 import "../chunk-I6PKJ7XQ.js";
 import "../chunk-T33MQXUP.js";
 import "../chunk-FII65CN7.js";

package/dist/middleware/prompt-cache/cache.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Prompt Cache Middleware — provider-dispatched prompt caching.
+ *
+ * Auto-detects the model provider and applies the right caching strategy:
+ *
+ * - **Anthropic**: Sets `cache_control: { type: "ephemeral" }` breakpoints
+ *   on system prompt and stable conversation messages. Up to 4 breakpoints.
+ *
+ * - **Other providers**: Pass through unchanged (strategies can be added).
+ *
+ * @example
+ * ```typescript
+ * import { promptCacheMiddleware } from "@cuylabs/agent-core/middleware";
+ *
+ * const agent = createAgent({
+ *   model: anthropic("claude-sonnet-4-20250514"),
+ *   middleware: [promptCacheMiddleware()],
+ * });
+ * ```
+ */
+import type { AgentMiddleware } from "../types.js";
+import type { PromptCacheConfig } from "./types.js";
+/**
+ * Create a prompt cache middleware that auto-detects the model provider
+ * and applies the right caching strategy.
+ *
+ * Currently supported:
+ * - **Anthropic** — `cache_control` breakpoints on system + messages
+ *
+ * Unsupported providers pass through unchanged.
+ *
+ * @param config - Optional TTL and breakpoint settings
+ *
+ * @example
+ * ```typescript
+ * // Works with any supported provider — auto-detects
+ * const agent = createAgent({
+ *   model: anthropic("claude-sonnet-4-20250514"),
+ *   middleware: [promptCacheMiddleware()],
+ * });
+ * ```
+ */
+export declare function promptCacheMiddleware(config?: PromptCacheConfig): AgentMiddleware;
+//# sourceMappingURL=cache.d.ts.map

package/dist/middleware/prompt-cache/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../../src/middleware/prompt-cache/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EACV,eAAe,EAGhB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAY,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAyI9D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,CAAC,EAAE,iBAAiB,GACzB,eAAe,CA+BjB"}

package/dist/middleware/prompt-cache/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Prompt Cache Middleware
+ *
+ * Auto-detects the model provider and applies the right caching strategy.
+ * Currently supports Anthropic cache_control breakpoints. Other providers
+ * pass through unchanged until their strategy is implemented.
+ *
+ * Split by responsibility:
+ * - `types` defines config contracts and TTL options
+ * - `cache` owns the middleware factory, provider dispatch, and strategies
+ */
+export { promptCacheMiddleware } from "./cache.js";
+export type { PromptCacheConfig, CacheTTL } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/middleware/prompt-cache/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/middleware/prompt-cache/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAEnD,YAAY,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC"}

package/dist/middleware/prompt-cache/types.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Prompt Cache Middleware — Type definitions.
+ *
+ * The middleware auto-detects the model provider and applies the right
+ * caching strategy. Currently supports Anthropic's `cache_control`
+ * with ephemeral breakpoints. Other providers pass through unchanged
+ * until their caching strategy is implemented.
+ */
+/**
+ * Supported cache TTL values.
+ *
+ * - `"5m"` — 5-minute cache (default, ~90% input cost reduction on Anthropic)
+ * - `"1h"` — 1-hour cache (higher write cost, longer retention)
+ */
+export type CacheTTL = "5m" | "1h";
+/**
+ * Configuration for the prompt cache middleware.
+ *
+ * @example
+ * ```typescript
+ * // Auto-detect provider, 5-minute TTL
+ * promptCacheMiddleware()
+ *
+ * // Custom TTL
+ * promptCacheMiddleware({ ttl: "1h" })
+ *
+ * // Custom breakpoint strategy (Anthropic)
+ * promptCacheMiddleware({ messageBreakpoints: 2 })
+ * ```
+ */
+export interface PromptCacheConfig {
+    /**
+     * Cache TTL. Defaults to `"5m"`.
+     *
+     * - `"5m"` — 5 minutes.
+     * - `"1h"` — 1 hour.
+     */
+    ttl?: CacheTTL;
+    /**
+     * Number of cache breakpoints to place on conversation messages.
+     *
+     * For Anthropic: max 4 breakpoints total (system always gets 1).
+     * This controls additional breakpoints on conversation messages.
+     *
+     * Defaults to `1` (system + 1 message boundary = 2 breakpoints).
+     * Set to `0` to only cache the system prompt.
+     */
+    messageBreakpoints?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/middleware/prompt-cache/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/middleware/prompt-cache/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,IAAI,GAAG,IAAI,CAAC;AAEnC;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,GAAG,CAAC,EAAE,QAAQ,CAAC;IAEf;;;;;;;;OAQG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B"}