@cognipeer/agent-sdk 0.9.7 → 0.10.0

package/dist/index.d.ts

@@ -107,6 +107,746 @@ declare function withTools(model: SmartModel, tools: any[], options?: {
 }): BaseChatModel;
 declare function fromLangchainModel(lcModel: any): BaseChatModel;
 
+/**
+ * Skill primitive — progressive capability disclosure for the smart agent.
+ *
+ * A Skill is a lazy, self-contained capability bundle. The model discovers a
+ * skill by its cheap one-line `header`, then calls `open_skill(key)` to load the
+ * skill's prompt and (for small skills) bind its tools, or
+ * `bind_skill_tools(key, names)` to bind a chosen subset of a fat skill. This
+ * keeps the number of bound tools per step small — the property small models
+ * need — and replaces an up-front tool-selector pass with on-demand disclosure.
+ *
+ * Discovery itself comes in two flavors, see `SkillPolicy.disclosure`: the
+ * headers can be listed in the system prompt, or looked up with `search_skills`.
+ */
+type SkillToolHeader = {
+    name: string;
+    description?: string;
+};
+type SkillModelTier = "small" | "large";
+/**
+ * How the model finds out which skills exist.
+ *
+ *  - `"catalog"` (default): every available skill's header is rendered into the
+ *    system prompt as `<available_skills>`. Cheapest possible discovery — the
+ *    model needs no tool call — but the prompt grows with the catalog, and the
+ *    whole catalog is paid for on every single turn of every conversation.
+ *  - `"search"`: nothing goes into the prompt. The model finds skills through
+ *    the `search_skills` tool, whose description is the only always-on cost.
+ *    Prompt cost is constant, so this is the mode for a catalog that is large,
+ *    workspace-supplied, or mostly irrelevant to any one conversation. The
+ *    trade-off is real: a model that never calls `search_skills` never learns
+ *    the skills exist, so keep the tool description explicit about when to call.
+ */
+type SkillDisclosure = "catalog" | "search";
+type Skill = {
+    /** Stable key, e.g. "mcp:atlassian" | "integration:google" | "builtin:drawio". */
+    key: string;
+    title: string;
+    /** One-line "what + when to use" the model always sees in the catalog. */
+    header: string;
+    /** Injected (as the open_skill result) only after the skill is opened. */
+    prompt: string | (() => Promise<string> | string);
+    /** When true, opening this skill should trigger sandbox bootstrap. */
+    needsSandbox?: boolean;
+    /** Gate: a "large"-only skill is hidden from a small-tier model. */
+    minModelTier?: SkillModelTier;
+    /** Whether the skill is usable in the current workspace (integration connected, etc.). */
+    isAvailable?: () => boolean | Promise<boolean>;
+    /** Cheap list of the skill's tool headers (names + one-liners). */
+    listToolIndex: () => Promise<SkillToolHeader[]> | SkillToolHeader[];
+    /** Bind concrete tools. With no names, bind the whole (small) skill. */
+    bindTools: (names?: string[]) => Promise<ToolInterface[]> | ToolInterface[];
+    /** Optional embedding/heuristic ranking of tool headers for a fat skill. */
+    rankToolHeaders?: (query: string, headers: SkillToolHeader[]) => Promise<SkillToolHeader[]> | SkillToolHeader[];
+    /** Deterministic floor: tools to bind when a weak model gives no usable query. */
+    defaultBindNames?: string[];
+};
+type SkillPolicy = {
+    /** Max distinct skills open at once (small tier should be 1). */
+    maxOpenSkills: number;
+    /** Max tools bound from a single skill in one bind call. */
+    maxBoundToolsPerSkill: number;
+    /** Overall cap on skill-bound tools across the whole run. */
+    maxBoundToolsTotal: number;
+    /** Current model tier; gates `minModelTier`. */
+    modelTier?: SkillModelTier;
+    /** How the model discovers skills. Defaults to `"catalog"`. */
+    disclosure?: SkillDisclosure;
+};
+declare const DEFAULT_SKILL_POLICY: SkillPolicy;
+declare const SMALL_TIER_SKILL_POLICY: SkillPolicy;
+/**
+ * Mutable per-invoke registry. The skill tools mutate this ref (append-only) and
+ * call `__onToolsChanged` so the runtime can rebuild its tool sets. Mirrors the
+ * stateRef pattern used by createAskUserQuestionTool.
+ */
+type SkillRegistryRef = {
+    /** Append-only: skills the model has opened this run. */
+    openedSkillKeys: string[];
+    /** Append-only, deduped by tool name: tools bound from opened skills. */
+    boundSkillTools: ToolInterface[];
+    /** Rebuild hook wired by createSmartAgent; rebuilds both recovery variants. */
+    __onToolsChanged?: () => void;
+};
+declare function createSkillRegistryRef(): SkillRegistryRef;
+
+/**
+ * A non-text part of a message, normalized across the two shapes this SDK
+ * accepts: the unified `{ type: "image" | "audio" | "file", source: … }` used by
+ * the native providers, and the legacy OpenAI-style `{ type: "image_url", … }`.
+ * A policy that had to know which of the two it was looking at would be wrong
+ * for half of its callers.
+ */
+type MediaAttachment = {
+    /** Position in the content array, so a policy can rewrite the right part. */
+    index: number;
+    kind: "image" | "audio" | "video" | "file" | "unknown";
+    mediaType?: string;
+    sourceType?: "url" | "base64";
+    url?: string;
+    /** Decoded size for a base64 payload. Unknown for a URL — nobody fetched it. */
+    approxBytes?: number;
+    fileName?: string;
+};
+declare function contentToString(content: string | ContentPart$1[] | any): string;
+declare function extractMessageText(message: any): string;
+/**
+ * The text a hook should reason about: the text parts only, joined.
+ *
+ * Deliberately not `contentToString`, which renders media as human-readable
+ * descriptors (`[image:…]`) for logs and token counting. A guardrail scoring
+ * that string would be scoring the SDK's own placeholder text, and a redactor
+ * rewriting it would bake the placeholder into the message.
+ */
+declare function textFromContent(content: string | ContentPart$1[] | unknown): string;
+/**
+ * Rewrite the text of a message's content, leaving every other part exactly as
+ * it was — same objects, same order.
+ *
+ * This is the write-back half of every text-oriented hook. Assigning a plain
+ * string over a multi-part `content` is the silent version of this operation:
+ * the run still answers, it just answers without the image the user attached.
+ */
+declare function mapTextParts(content: string | ContentPart$1[] | unknown, fn: (text: string) => string): string | ContentPart$1[] | unknown;
+/**
+ * Put a whole replacement text back into a multi-part content.
+ *
+ * A hook that took `text` saw the CONCATENATION of every text part, so there is
+ * no general way to split its answer back across them. With one text part (the
+ * ordinary case) this is exact. With several, the replacement lands in the first
+ * and the rest are dropped — media parts keep their positions either way. A
+ * plugin that needs exact multi-part fidelity should return `content` instead,
+ * which is why that field exists.
+ */
+declare function replaceTextContent(content: string | ContentPart$1[] | unknown, text: string): string | ContentPart$1[] | unknown;
+/** Every non-text part of a message, normalized for policy code. */
+declare function collectAttachments(content: string | ContentPart$1[] | unknown): MediaAttachment[];
+
+/**
+ * Plugin layer — type surface.
+ *
+ * This module is TYPE-ONLY on purpose. `src/types.ts` imports `AgentPlugin`
+ * from here while this file imports most of its payload types from there; a
+ * runtime export in either direction would create a real module cycle. Keeping
+ * everything here erasable (`import type` / `export type`) means the cycle
+ * disappears at compile time.
+ *
+ * Three kinds of extension live in a plugin:
+ *   - hooks         intercept   many run, chained, decisions merge
+ *   - contributions add         many run, results accumulate
+ *   - slots         replace     exactly one owner, conflict is a hard error
+ */
+
+type MaybePromise<T> = T | Promise<T>;
+/** How a plugin's failure is interpreted. `closed` turns an error into a deny. */
+type PluginFailureMode = "open" | "closed";
+/** Merged verdict of a gate hook. Escalation order: allow &lt; ask &lt; deny. */
+type HookDecision = "allow" | "deny" | "ask";
+type PluginLogger = {
+    debug(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+};
+/**
+ * Passed to every hook and slot call. Scoped per plugin: `store` is private to
+ * the plugin that received it and lives for exactly one run.
+ */
+type HookContext = {
+    /** Stable id for this invoke, always present. */
+    runId: string;
+    /**
+     * The run's trace id, for correlating a decision with its timeline.
+     *
+     * Undefined when tracing is off, and also for hooks that run BEFORE the first
+     * model call on a smart agent — the trace session is created inside the first
+     * base leg, while `sessionStart` and `userPromptSubmit` run ahead of it.
+     * `runId` is the identifier that is always available; treat this as an
+     * additional join key, not a replacement.
+     */
+    traceId?: string;
+    agentName?: string;
+    /** Name of the hook currently executing — handy for shared handlers. */
+    hookName: string;
+    /**
+     * Live agent state. Declared readonly because mutation must go through the
+     * hook's return value; an in-place write is invisible to the composition
+     * rules and makes execution order unobservable.
+     */
+    state: Readonly<SmartState>;
+    /** Per-plugin, per-run scratch space. Never serialized into a snapshot. */
+    store: Record<string, unknown>;
+    /** Emit an event to the host's `onEvent`. */
+    emit: (event: SmartAgentEvent) => void;
+    logger: PluginLogger;
+    /** The run's cancellation signal — forward it to outbound HTTP calls. */
+    signal?: AbortSignal;
+    /** Delegation depth. 0 is the root agent; children increment it. */
+    depth: number;
+};
+/** Passed to `setup`, `tools`, `systemPrompt` and `wrapModel`. */
+type PluginSetupContext = {
+    agentName?: string;
+    agentVersion?: string;
+    /** The agent's model, before any `wrapModel` in this plugin's own chain. */
+    model: unknown;
+    logger: PluginLogger;
+    /** Register a teardown callback instead of returning one from `setup`. */
+    onDispose: (fn: () => MaybePromise<void>) => void;
+};
+/**
+ * The single source of truth for hook payloads. Every `output` field is
+ * optional so that adding capability later is not a breaking change, and
+ * returning `undefined` always means "nothing changed".
+ */
+interface HookMap {
+    /** Run is starting. Fires once per `invoke()`, including on resume. */
+    sessionStart: {
+        input: {
+            messages: Message[];
+            /** True when this invoke continues a paused/snapshotted run. */
+            resumed: boolean;
+            config?: InvokeConfig;
+        };
+        output: {
+            /** Replace the starting transcript (e.g. hydrate from a conversation store). */
+            messages?: Message[];
+            /** Appended to the composed system prompt for this run. */
+            systemPromptAppend?: string;
+            metadata?: Record<string, unknown>;
+        };
+    };
+    /**
+     * A new user message is entering the transcript. Input-side guardrail point.
+     *
+     * A user turn is not always a string: it can carry images, audio, video or
+     * files alongside its text. `text` is the concatenation of the text parts,
+     * `content` is the whole thing, and `attachments` is the non-text half
+     * normalized for policy code.
+     */
+    userPromptSubmit: {
+        input: {
+            /** Concatenated text parts. Empty string for a media-only turn. */
+            text: string;
+            /** The full content, string or parts. Return `content` to rewrite it exactly. */
+            content: string | ContentPart$1[];
+            /** Every non-text part, normalized across the unified and legacy shapes. */
+            attachments: MediaAttachment[];
+            message: Message;
+        };
+        output: {
+            /**
+             * Rewritten text — masking, normalization, injection stripping. Written
+             * back into the text parts, never over the whole content: assigning a
+             * string over a multi-part message is how an attached image disappears.
+             * With several text parts the replacement lands in the first and the rest
+             * are dropped, because the hook only ever saw their concatenation —
+             * return `content` when that matters.
+             */
+            text?: string;
+            /** Full control over the parts: reorder, drop an attachment, rewrite per part. */
+            content?: string | ContentPart$1[];
+            /** Extra system-level context appended for this turn only. */
+            additionalContext?: string;
+            decision?: "allow" | "deny";
+            reason?: string;
+            metadata?: Record<string, unknown>;
+        };
+    };
+    /** Immediately before every model call, including retries and finalization. */
+    preModelCall: {
+        input: {
+            messages: Message[];
+            tools: ToolInterface[];
+            /** Provider invoke options: signal, response_format, reasoning, … */
+            params: Record<string, unknown>;
+            model: unknown;
+            /** 1-based loop iteration. */
+            iteration: number;
+        };
+        output: {
+            messages?: Message[];
+            /** Narrow the tool menu for this call only. */
+            tools?: ToolInterface[];
+            /** Shallow-merged into the provider options — never replaces them wholesale. */
+            params?: Record<string, unknown>;
+            /** Skip the provider entirely and use this as the assistant turn. */
+            shortCircuit?: AIMessage;
+            decision?: "allow" | "deny";
+            reason?: string;
+            metadata?: Record<string, unknown>;
+        };
+    };
+    /** The assistant turn came back, before the loop decides what to do with it. */
+    postModelCall: {
+        input: {
+            message: AIMessage;
+            usage?: Record<string, unknown>;
+            durationMs: number;
+            iteration: number;
+            /** True when the message was produced by a `preModelCall` short-circuit. */
+            shortCircuited: boolean;
+        };
+        output: {
+            message?: AIMessage;
+            decision?: "allow" | "deny";
+            reason?: string;
+            /** Re-run this model call. Bounded by `maxModelRetries`. */
+            retry?: boolean;
+            metadata?: Record<string, unknown>;
+        };
+    };
+    /** After argument validation, before the approval gate. */
+    preToolUse: {
+        input: {
+            toolName: string;
+            toolCallId: string;
+            args: unknown;
+            tool: ToolInterface;
+            /** Tool executions already recorded in this run. */
+            executionCount: number;
+        };
+        output: {
+            /** Corrected or constrained arguments. Re-validated against the schema. */
+            args?: unknown;
+            /** `ask` escalates to human approval; it can never be downgraded to `allow`. */
+            decision?: HookDecision;
+            /** Surfaced to the model as the tool result on `deny`. */
+            reason?: string;
+            /** Prompt text when this hook raised the approval. */
+            approvalPrompt?: string;
+            /** Skip execution and use this as the tool's output (cache, mock, stub). */
+            result?: unknown;
+            metadata?: Record<string, unknown>;
+        };
+    };
+    /** Raw tool output, before ContextPilot compression and the hard cap. */
+    postToolUse: {
+        input: {
+            toolName: string;
+            toolCallId: string;
+            args: unknown;
+            output: unknown;
+            error?: Error;
+            durationMs: number;
+            executionId: string;
+        };
+        output: {
+            /** Rewritten output — redaction, normalization, schema coercion. */
+            output?: unknown;
+            decision?: "allow" | "deny";
+            reason?: string;
+            metadata?: Record<string, unknown>;
+        };
+    };
+    /** Before the summarizer runs. */
+    preCompact: {
+        input: {
+            reason: "token_pressure" | "manual";
+            messages: Message[];
+            tokenCount: number;
+            threshold: number;
+        };
+        output: {
+            /** Replace the candidate set (e.g. pin messages that must survive). */
+            messages?: Message[];
+            /** Skip compaction for this pass. */
+            skip?: boolean;
+            metadata?: Record<string, unknown>;
+        };
+    };
+    /** After a summary was produced and applied. */
+    postCompact: {
+        input: {
+            summary: StructuredSummary;
+            tokensBefore: number;
+            tokensAfter: number;
+            /** Name of the strategy that produced it — `"builtin"` when no slot is filled. */
+            strategy: string;
+        };
+        output: void;
+    };
+    /** The run produced a final answer and is about to return it. */
+    preFinalAnswer: {
+        input: {
+            content: string;
+            output?: unknown;
+            message?: AIMessage;
+        };
+        output: {
+            content?: string;
+            decision?: "allow" | "deny";
+            reason?: string;
+            /** Keep looping with this instruction instead of returning. Bounded. */
+            continueWith?: string;
+            metadata?: Record<string, unknown>;
+        };
+    };
+    /** A sub-agent task is about to start. */
+    subagentStart: {
+        input: {
+            name: string;
+            task: string;
+            depth: number;
+        };
+        output: {
+            task?: string;
+            decision?: "allow" | "deny";
+            reason?: string;
+        };
+    };
+    /** A sub-agent finished and its result is returning to the parent. */
+    subagentStop: {
+        input: {
+            name: string;
+            result: unknown;
+            depth: number;
+            durationMs?: number;
+        };
+        output: void;
+    };
+    /** Something needs a human, or a limit was hit. Observation only. */
+    notification: {
+        input: {
+            kind: "approval" | "user_question" | "limit" | "error";
+            detail: unknown;
+        };
+        output: void;
+    };
+    /** The run ended, on every exit path. */
+    sessionEnd: {
+        input: {
+            status: "success" | "error" | "paused" | "cancelled";
+            result?: AgentInvokeResult;
+            error?: Error;
+            usage?: SmartState["usage"];
+            durationMs: number;
+        };
+        output: void;
+    };
+}
+type HookName = keyof HookMap;
+type HookHandler<K extends HookName> = (input: HookMap[K]["input"], ctx: HookContext) => MaybePromise<HookMap[K]["output"] | void>;
+/** Hooks declared inline on the agent, or inside a plugin. */
+type HookRegistrations = {
+    [K in HookName]?: HookHandler<K> | Array<HookHandler<K>>;
+};
+/** What a gate hook chain produced, after composition. */
+type GateResult<K extends HookName> = {
+    decision: HookDecision;
+    reason?: string;
+    /** Plugin that produced the blocking decision, when there is one. */
+    deniedBy?: string;
+    /** The payload after every handler's mutations were applied in order. */
+    input: HookMap[K]["input"];
+    /** First short-circuit value offered, if any. */
+    shortCircuit?: unknown;
+    /** Whether any handler mutated the payload. */
+    mutated: boolean;
+    /**
+     * Which plugins mutated it, in the order they ran.
+     *
+     * Plugin-level, not span-level: a handler returns a rewritten payload rather
+     * than an op list, so "which rule changed this span" is not recoverable —
+     * but "which plugin changed this" is, and that is the question an audit
+     * trail is usually asked. A plugin that needs finer provenance reports it
+     * through `metadata` (piiRedaction emits the entity types it matched).
+     */
+    mutatedBy: string[];
+    /** Accumulated non-payload output (systemPromptAppend, additionalContext, …). */
+    collected: Record<string, unknown[]>;
+    /** Boolean flags OR-ed across handlers (skip, retry, …). */
+    flags: Record<string, boolean>;
+    /** Merged `metadata` objects from every handler. */
+    metadata?: Record<string, unknown>;
+};
+type SummarizerInput = {
+    /**
+     * The messages the SDK selected as compressable. Selection is not negotiable:
+     * protected tool_call ids and the recency window are correctness-critical and
+     * stay on the SDK side.
+     */
+    messages: Message[];
+    /** Prior summary for incremental mode. */
+    previousSummary?: StructuredSummary;
+    /** Latest user request, so the summary can be query-focused. */
+    query: string;
+    budget: {
+        targetTokens: number;
+        maxTokens: number;
+    };
+    /** The agent's model. A strategy is free to use a cheaper one. */
+    model: unknown;
+    mode: SummarizationMode;
+};
+type SummarizerResult = {
+    summary: StructuredSummary;
+    /** Provider usage, so the SDK can bill the compaction call. */
+    usage?: unknown;
+    /** Recovery references for archived tool payloads. */
+    archived?: Array<{
+        executionId: string;
+        ref: string;
+    }>;
+};
+type SummarizerStrategy = {
+    name: string;
+    /** Returning `null` means "could not compress" — same contract as the built-in `{}`. */
+    compress(input: SummarizerInput, ctx: HookContext): MaybePromise<SummarizerResult | null>;
+};
+type ConversationStore = {
+    load(threadId: string): MaybePromise<Message[] | null | undefined>;
+    append(threadId: string, messages: Message[]): MaybePromise<void>;
+    clear?(threadId: string): MaybePromise<void>;
+};
+type CheckpointStore = {
+    save(id: string, snapshot: AgentSnapshot): MaybePromise<void>;
+    load(id: string): MaybePromise<AgentSnapshot | null | undefined>;
+    list?(prefix?: string): MaybePromise<string[]>;
+    remove?(id: string): MaybePromise<void>;
+};
+type ApprovalTransport = {
+    /**
+     * Deliver a pending approval to a human and wait for the answer. Returning
+     * `null` leaves the run paused for the host to resolve the usual way.
+     */
+    request(pending: PendingToolApproval, ctx: HookContext): MaybePromise<ToolApprovalResolution | null>;
+    /** Optional: same treatment for `ask_user_question`. */
+    requestUserInput?(pending: PendingUserQuestion, ctx: HookContext): MaybePromise<unknown | null>;
+};
+type SkillSource = {
+    name: string;
+    list(ctx: PluginSetupContext): MaybePromise<Skill[]>;
+};
+type PromptSource = {
+    name: string;
+    /** Resolve a named, versioned prompt. `null` falls through to the default. */
+    resolve(key: string, ctx: HookContext): MaybePromise<string | null | undefined>;
+};
+type ContextBuilder = {
+    name: string;
+    build(input: {
+        state: SmartState;
+        defaultMessages: Message[];
+    }, ctx: HookContext): MaybePromise<Message[]>;
+};
+type CostEstimator = (args: {
+    modelName?: string;
+    inputTokens: number;
+    outputTokens: number;
+    cachedInputTokens?: number;
+    reasoningTokens?: number;
+}) => number;
+/**
+ * Slots replace an SDK default. Exactly one plugin may fill each one; two
+ * claimants is a construction-time error, never a silent last-one-wins.
+ */
+type PluginProvides = {
+    summarizer?: SummarizerStrategy;
+    tokenCounter?: (text: string) => number;
+    costEstimator?: CostEstimator;
+    memoryStore?: MemoryStore;
+    conversationStore?: ConversationStore;
+    checkpointStore?: CheckpointStore;
+    approvalTransport?: ApprovalTransport;
+    skillSource?: SkillSource;
+    promptSource?: PromptSource;
+    contextBuilder?: ContextBuilder;
+};
+type SlotName = keyof PluginProvides;
+type AgentPlugin = {
+    /** Unique within one agent. A duplicate is a construction-time error. */
+    name: string;
+    version?: string;
+    description?: string;
+    /** Execution order; lower runs first. Default 100. */
+    priority?: number;
+    /** How this plugin's own errors and timeouts are interpreted. Default "open". */
+    failureMode?: PluginFailureMode;
+    /** Per-handler timeout in ms. Default 10_000. */
+    timeoutMs?: number;
+    /**
+     * Whether children (sub-agents, `asTool` delegates) inherit this plugin.
+     * Default true — a policy a delegation can shed is not a policy.
+     */
+    inheritToSubagents?: boolean;
+    /** One-time construction. May return a disposer. */
+    setup?: (ctx: PluginSetupContext) => MaybePromise<void | (() => MaybePromise<void>)>;
+    dispose?: () => MaybePromise<void>;
+    hooks?: HookRegistrations;
+    /**
+     * Whether this plugin's `preToolUse` handler can return `decision: "ask"`.
+     * Defaults to true for any plugin that registers `preToolUse`.
+     *
+     * It exists for scheduling, not for policy: a call that may pause for a human
+     * has to run in the sequential group, because the parallel fan-out has already
+     * started its siblings by the time a pause is raised. Declaring `false` on a
+     * pure redaction/audit hook keeps the tool batch parallel.
+     */
+    mayRequireApproval?: boolean;
+    tools?: ToolInterface[] | ((ctx: PluginSetupContext) => MaybePromise<ToolInterface[]>);
+    systemPrompt?: string | ((current: string, ctx: PluginSetupContext) => string);
+    toolDescriptions?: Record<string, string | ((defaultDescription: string) => string)>;
+    wrapModel?: (model: unknown, ctx: PluginSetupContext) => unknown;
+    provides?: PluginProvides;
+    /** Bridge for v1 guardrails carried inside a plugin. */
+    guardrails?: ConversationGuardrail[];
+    /** Set by the SDK on internally-generated bridge plugins. */
+    readonly __internal?: boolean;
+};
+/** Everything the plugin layer contributes, resolved once per agent. */
+type PluginContributions = {
+    tools: ToolInterface[];
+    toolDescriptions: Record<string, string | ((defaultDescription: string) => string)>;
+    guardrails: ConversationGuardrail[];
+    /** Applied in priority order, before any legacy `promptHooks.transformSystemPrompt`. */
+    applySystemPrompt: (base: string) => string;
+    /** Applied outermost-last, so the highest-priority plugin wraps first. */
+    applyModelWrappers: (model: unknown) => unknown;
+};
+/** Emitted so the hook layer itself is observable. */
+type PluginEvent = {
+    type: "plugin";
+    plugin: string;
+    hook: string;
+    phase: "success" | "error" | "timeout";
+    decision?: HookDecision;
+    mutated?: boolean;
+    shortCircuited?: boolean;
+    reason?: string;
+    durationMs?: number;
+    error?: {
+        message: string;
+    };
+};
+/**
+ * A hook outcome worth putting on the trace timeline. Only material outcomes
+ * are recorded — a decision that was not `allow`, a payload mutation, a
+ * short-circuit, or a failure. Per-handler noise stays on the `plugin` event
+ * stream, where it costs nothing.
+ */
+type PluginTraceRecord = {
+    plugin: string;
+    hook: HookName;
+    /** Plugins that had already rewritten this payload when the record was made. */
+    mutatedBy?: string[];
+    /**
+     * `skipped` for a policy deny and for a fail-open error: neither is a system
+     * failure, and `error` would flip the whole trace session's status for a run
+     * that behaved exactly as configured. `error` is reserved for a fail-closed
+     * failure, which does abort the run.
+     */
+    status: "success" | "error" | "skipped";
+    decision?: HookDecision;
+    mutated?: boolean;
+    shortCircuited?: boolean;
+    reason?: string;
+    durationMs?: number;
+    error?: {
+        message: string;
+    };
+};
+type PluginHostOptions = {
+    /** Emit a `plugin` event for every handler, not just the interesting ones. */
+    debug?: boolean;
+    logger?: PluginLogger;
+    /** Cap on `postModelCall.retry`. Default 2. */
+    maxModelRetries?: number;
+    /** Cap on `preFinalAnswer.continueWith`. Default 2. */
+    maxContinuations?: number;
+};
+
+/**
+ * Plugin layer — runtime.
+ *
+ * `createPluginHost` is agent-scoped: it validates the plugin set, resolves
+ * slots and contributions once, and owns setup/dispose. `beginRun` opens a
+ * run-scoped handle whose per-plugin stores live and die with one `invoke()`,
+ * which is what keeps concurrent invokes on the same agent instance isolated.
+ *
+ * Composition rules (see docs/guide/plugins.md):
+ *   R1 order        priority ascending, then registration order; stable
+ *   R2 mutation     chained — each handler sees the previous one's output
+ *   R3 decision     deny > ask > allow; the first deny short-circuits the chain
+ *   R4 short-circuit first value offered wins, the rest are reported and dropped
+ *   R5 errors       per-plugin failureMode: "open" continues, "closed" denies
+ *   R6 timeout      per-handler, treated as an error under R5
+ *   R7 observers    never block and never fail the run
+ *   R8 observable   every decision/mutation is emitted as a `plugin` event
+ */
+
+declare const HOOK_NAMES: HookName[];
+declare class HookTimeoutError extends Error {
+    constructor(label: string, ms: number);
+}
+type PluginRunHost = {
+    /** Cheap guard so call sites can skip building payloads when nothing listens. */
+    has(hook: HookName): boolean;
+    /** Cap on `postModelCall.retry` for this run. */
+    readonly maxModelRetries: number;
+    /** Cap on `preFinalAnswer.continueWith` for this run. */
+    readonly maxContinuations: number;
+    /**
+     * True when some registered `preToolUse` plugin may return `ask`. Call sites
+     * use it to keep such calls out of the parallel fan-out.
+     */
+    readonly mayPauseOnToolUse: boolean;
+    runGate<K extends HookName>(hook: K, input: HookMap[K]["input"]): Promise<GateResult<K>>;
+    runObservers<K extends HookName>(hook: K, input: HookMap[K]["input"]): Promise<void>;
+    /** Release per-run plugin stores. */
+    end(): void;
+};
+type PluginHost = {
+    readonly plugins: AgentPlugin[];
+    readonly slots: PluginProvides;
+    readonly contributions: PluginContributions;
+    readonly maxModelRetries: number;
+    readonly maxContinuations: number;
+    has(hook: HookName): boolean;
+    hasAny(): boolean;
+    /** True when some `preToolUse` plugin may escalate a call to human approval. */
+    mayPauseOnToolUse(): boolean;
+    /** Resolve contributions and run every `setup`. Idempotent; a failure sticks. */
+    setup(ctx: Omit<PluginSetupContext, "onDispose" | "logger"> & {
+        logger?: PluginLogger;
+    }): Promise<void>;
+    dispose(): Promise<void>;
+    beginRun(opts: {
+        runId: string;
+        agentName?: string;
+        getState: () => SmartState;
+        emit?: (event: SmartAgentEvent) => void;
+        /** Put a material hook outcome on the trace timeline. */
+        recordTrace?: (record: PluginTraceRecord) => void;
+        signal?: AbortSignal;
+        depth?: number;
+    }): PluginRunHost;
+    /** The subset a child agent inherits. */
+    childPlugins(): AgentPlugin[];
+};
+declare function createPluginHost(plugins?: AgentPlugin[], options?: PluginHostOptions): PluginHost;
+
 /**
  * Sub-agent primitive — dynamic problem-solving by delegating self-contained
  * subtasks to focused child agents.
@@ -237,91 +977,6 @@ type SubagentToolNames = {
 };
 declare const DEFAULT_SUBAGENT_TOOL_NAMES: SubagentToolNames;
 
-/**
- * Skill primitive — progressive capability disclosure for the smart agent.
- *
- * A Skill is a lazy, self-contained capability bundle. The model discovers a
- * skill by its cheap one-line `header`, then calls `open_skill(key)` to load the
- * skill's prompt and (for small skills) bind its tools, or
- * `bind_skill_tools(key, names)` to bind a chosen subset of a fat skill. This
- * keeps the number of bound tools per step small — the property small models
- * need — and replaces an up-front tool-selector pass with on-demand disclosure.
- *
- * Discovery itself comes in two flavors, see `SkillPolicy.disclosure`: the
- * headers can be listed in the system prompt, or looked up with `search_skills`.
- */
-type SkillToolHeader = {
-    name: string;
-    description?: string;
-};
-type SkillModelTier = "small" | "large";
-/**
- * How the model finds out which skills exist.
- *
- *  - `"catalog"` (default): every available skill's header is rendered into the
- *    system prompt as `<available_skills>`. Cheapest possible discovery — the
- *    model needs no tool call — but the prompt grows with the catalog, and the
- *    whole catalog is paid for on every single turn of every conversation.
- *  - `"search"`: nothing goes into the prompt. The model finds skills through
- *    the `search_skills` tool, whose description is the only always-on cost.
- *    Prompt cost is constant, so this is the mode for a catalog that is large,
- *    workspace-supplied, or mostly irrelevant to any one conversation. The
- *    trade-off is real: a model that never calls `search_skills` never learns
- *    the skills exist, so keep the tool description explicit about when to call.
- */
-type SkillDisclosure = "catalog" | "search";
-type Skill = {
-    /** Stable key, e.g. "mcp:atlassian" | "integration:google" | "builtin:drawio". */
-    key: string;
-    title: string;
-    /** One-line "what + when to use" the model always sees in the catalog. */
-    header: string;
-    /** Injected (as the open_skill result) only after the skill is opened. */
-    prompt: string | (() => Promise<string> | string);
-    /** When true, opening this skill should trigger sandbox bootstrap. */
-    needsSandbox?: boolean;
-    /** Gate: a "large"-only skill is hidden from a small-tier model. */
-    minModelTier?: SkillModelTier;
-    /** Whether the skill is usable in the current workspace (integration connected, etc.). */
-    isAvailable?: () => boolean | Promise<boolean>;
-    /** Cheap list of the skill's tool headers (names + one-liners). */
-    listToolIndex: () => Promise<SkillToolHeader[]> | SkillToolHeader[];
-    /** Bind concrete tools. With no names, bind the whole (small) skill. */
-    bindTools: (names?: string[]) => Promise<ToolInterface[]> | ToolInterface[];
-    /** Optional embedding/heuristic ranking of tool headers for a fat skill. */
-    rankToolHeaders?: (query: string, headers: SkillToolHeader[]) => Promise<SkillToolHeader[]> | SkillToolHeader[];
-    /** Deterministic floor: tools to bind when a weak model gives no usable query. */
-    defaultBindNames?: string[];
-};
-type SkillPolicy = {
-    /** Max distinct skills open at once (small tier should be 1). */
-    maxOpenSkills: number;
-    /** Max tools bound from a single skill in one bind call. */
-    maxBoundToolsPerSkill: number;
-    /** Overall cap on skill-bound tools across the whole run. */
-    maxBoundToolsTotal: number;
-    /** Current model tier; gates `minModelTier`. */
-    modelTier?: SkillModelTier;
-    /** How the model discovers skills. Defaults to `"catalog"`. */
-    disclosure?: SkillDisclosure;
-};
-declare const DEFAULT_SKILL_POLICY: SkillPolicy;
-declare const SMALL_TIER_SKILL_POLICY: SkillPolicy;
-/**
- * Mutable per-invoke registry. The skill tools mutate this ref (append-only) and
- * call `__onToolsChanged` so the runtime can rebuild its tool sets. Mirrors the
- * stateRef pattern used by createAskUserQuestionTool.
- */
-type SkillRegistryRef = {
-    /** Append-only: skills the model has opened this run. */
-    openedSkillKeys: string[];
-    /** Append-only, deduped by tool name: tools bound from opened skills. */
-    boundSkillTools: ToolInterface[];
-    /** Rebuild hook wired by createSmartAgent; rebuilds both recovery variants. */
-    __onToolsChanged?: () => void;
-};
-declare function createSkillRegistryRef(): SkillRegistryRef;
-
 type ContextPilotJsonCompressionConfig = {
     enabled?: boolean;
     /** Fraction (0-1) of array items to retain. Lower = more aggressive. */
@@ -545,6 +1200,17 @@ type ConversationGuardrail = {
     description?: string;
     appliesTo: GuardrailPhase[];
     rules: GuardrailRule[];
+    /**
+     * What a rule THROWING means. `"closed"` (the default, and the historical
+     * behaviour) turns the error into a block. `"open"` records a warning and
+     * lets the turn continue.
+     *
+     * The distinction matters because a rule that reaches a database or a policy
+     * service fails transiently, and under `"closed"` one blip hard-blocks every
+     * turn until it clears — a availability decision the guardrail author should
+     * be making deliberately rather than inheriting.
+     */
+    failureMode?: "open" | "closed";
     haltOnViolation?: boolean;
     onViolation?: (incident: GuardrailIncident, context: GuardrailContext) => Promise<GuardrailDisposition | void> | GuardrailDisposition | void;
     metadata?: Record<string, any>;
@@ -683,6 +1349,19 @@ type AgentOptions = {
      * passed explicitly.
      */
     contextPilot?: ContextPilotConfig;
+    /**
+     * Plugins: named bundles of hooks, contributions and strategy slots. See
+     * {@link AgentPlugin} and docs/guide/plugins.md.
+     */
+    plugins?: AgentPlugin[];
+    /**
+     * Inline hooks, for the cases where naming a plugin would be ceremony. They
+     * are wrapped into an anonymous plugin that runs at the default priority,
+     * after any explicitly lower-priority plugin.
+     */
+    hooks?: HookRegistrations;
+    /** Tuning for the plugin host (retry/continuation caps, debug events). */
+    pluginOptions?: PluginHostOptions;
 };
 type ReasoningLevel = "minimal" | "low" | "medium" | "high";
 type ReflectionCadence = "off" | "every_turn" | "after_tool" | "on_branch" | "initial_then_after_tool";
@@ -1059,6 +1738,12 @@ type SmartAgentOptions = {
      * catalog block. See {@link PromptHooks}.
      */
     promptHooks?: PromptHooks;
+    /** See AgentOptions.plugins. */
+    plugins?: AgentPlugin[];
+    /** See AgentOptions.hooks. */
+    hooks?: HookRegistrations;
+    /** See AgentOptions.pluginOptions. */
+    pluginOptions?: PluginHostOptions;
 };
 /**
  * Override points for the SDK's built-in (otherwise static) prompt surfaces.
@@ -1834,7 +2519,7 @@ type DelegationEventStamp = {
     /** Name of the `asTool` child agent this forwarded event came from. */
     delegatedTo?: string;
 };
-type SmartAgentEvent = (ToolCallEvent | ToolApprovalEvent | UserQuestionEvent | PlanEvent | SummarizationEvent | FinalAnswerEvent | MetadataEvent | HandoffEvent | GuardrailEvent | ProgressEvent | StreamEvent | CancelledEvent | SubagentEvent | ReflectionEvent) & DelegationEventStamp;
+type SmartAgentEvent = (ToolCallEvent | ToolApprovalEvent | UserQuestionEvent | PlanEvent | SummarizationEvent | FinalAnswerEvent | MetadataEvent | HandoffEvent | GuardrailEvent | ProgressEvent | StreamEvent | CancelledEvent | SubagentEvent | ReflectionEvent | PluginEvent) & DelegationEventStamp;
 type ReflectionEvent = {
     type: "reflection";
     id: string;
@@ -1889,6 +2574,23 @@ type InvokeConfig = RunnableConfig & {
      * unavailable keys are skipped. Ignored when the agent has no `skills`.
      */
     preopenedSkills?: string[];
+    /**
+     * @internal Session handle threaded from createSmartAgent's driver into each
+     * `base.invoke()` leg. It is what makes one logical turn one plugin session:
+     * whoever creates it owns sessionStart/sessionEnd/preFinalAnswer, and the
+     * legs that inherit it fire none of the three.
+     *
+     * Deliberately NOT carried on `state.ctx`. A handle on ctx rides out on
+     * `result.state` and comes back in on the next `invoke(previousState)`, which
+     * makes two concurrent continuations share one store and one run id.
+     */
+    __pluginSession?: {
+        host: PluginRunHost;
+        runId: string;
+        stateHolder: {
+            value: SmartState;
+        };
+    };
 };
 type SnapshotRuntimeHint = {
     name?: string;
@@ -1932,6 +2634,15 @@ type AgentInvokeResult<TOutput = unknown> = {
     state?: SmartState;
 };
 type AgentInstance<TOutput = unknown> = {
+    /**
+     * Release plugin-held resources (HTTP clients, MCP connections, batch
+     * buffers). Safe to skip for plugin-free agents; safe to call twice.
+     */
+    dispose?: () => Promise<void>;
+    /** Internal: the agent's plugin host, used to seed child agents. */
+    __plugins?: unknown;
+    /** Composed plugin systemPrompt contribution; run-scoped, never serialized. */
+    __applySystemPromptContribution?: unknown;
     invoke: (input: SmartState, config?: InvokeConfig) => Promise<AgentInvokeResult<TOutput>>;
     snapshot: (state: SmartState, options?: SnapshotOptions) => AgentSnapshot;
     resume: (snapshot: AgentSnapshot, config?: InvokeConfig, restoreOptions?: RestoreSnapshotOptions) => Promise<AgentInvokeResult<TOutput>>;
@@ -2003,6 +2714,13 @@ declare function createTool({ name, description, schema, func, needsApproval, ap
 
 declare function buildSystemPrompt(extra?: string, planning?: boolean | PlanningMode, name?: string, todoListPrompt?: string): string;
 
+/**
+ * Turn handoff descriptors into the tools that expose them to the model.
+ *
+ * Shared with createSmartAgent, which builds its own per-invoke tool set and
+ * would otherwise never see these — a typed, documented option doing nothing.
+ */
+declare function buildHandoffTools(handoffs: HandoffDescriptor[]): any[];
 declare function createAgent<TOutput = unknown>(opts: AgentOptions & {
     outputSchema?: ZodSchema<TOutput>;
 }): AgentInstance<TOutput>;
@@ -2562,12 +3280,12 @@ declare const guardianSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     allow: boolean;
     reason?: string | undefined;
-    disposition?: "block" | "warn" | "allow" | undefined;
+    disposition?: "allow" | "block" | "warn" | undefined;
     details?: Record<string, any> | undefined;
 }, {
     allow: boolean;
     reason?: string | undefined;
-    disposition?: "block" | "warn" | "allow" | undefined;
+    disposition?: "allow" | "block" | "warn" | undefined;
     details?: Record<string, any> | undefined;
 }>;
 type AgentRuleOptions = {
@@ -2623,400 +3341,301 @@ type CodeGuardrailOptions = GuardrailPresetBase & {
 declare function createCodeGuardrail(options?: CodeGuardrailOptions): ConversationGuardrail;
 
 /**
- * Centralized manager for structured output across both base Agent and SmartAgent.
+ * Wrap a plugin factory so config flows through with full inference:
  *
- * Responsibilities:
- * - Prepare tools or response_format depending on the resolved strategy
- * - Build system prompt hints tailored to the strategy
- * - Build nudge/correction prompts for retries
- * - Parse final output from tool result or assistant content
- * - Report structured errors (never silently swallow)
+ *   const myGuard = definePlugin<{ level: number }>((cfg) => ({ name: "my-guard", ... }));
+ *   myGuard({ level: 2 })
+ *
+ * The indirection buys nothing at runtime — it exists so the config type is
+ * inferred at the call site and the returned object is checked against
+ * `AgentPlugin` at the definition site, where the error message is useful.
  */
-declare class StructuredOutputManager<T> {
-    readonly strategy: StructuredOutputStrategy;
-    readonly schema: ZodSchema<T>;
-    readonly maxRetries: number;
-    constructor(schema: ZodSchema<T>, strategy: StructuredOutputStrategy, config?: StructuredOutputManagerConfig);
-    /**
-     * Get the `response` tool for tool-based strategy.
-     * Returns undefined for native strategy (no tool needed).
-     */
-    getResponseTool(): ToolInterface | undefined;
-    /**
-     * Get response_format config for native strategy.
-     * Returns undefined for tool-based strategy.
-     */
-    getResponseFormat(): Record<string, any> | undefined;
-    /**
-     * Build the system prompt hint that tells the model how to produce structured output.
-     */
-    buildSystemPromptHint(): string;
-    /**
-     * Build a nudge message for when the model didn't produce structured output.
-     * Used by the agent loop when it needs to retry.
-     * User role is intentional: OpenAI-compatible chat templates such as Qwen
-     * reject system messages anywhere except the beginning of the conversation.
-     */
-    buildNudgeMessage(isLastAttempt: boolean): {
-        role: string;
-        content: string;
-    };
-    /**
-     * Build a correction message when schema validation failed.
-     */
-    buildCorrectionMessage(error: StructuredOutputError, _previousAttempt?: unknown): {
-        role: string;
-        content: string;
-    };
-    /**
-     * Try to parse structured output from the tool-based finalization result.
-     * Called when __structuredOutputParsed is available in ctx.
-     */
-    parseFromToolResult(data: unknown): StructuredOutputResult<T>;
-    /**
-     * Try to parse structured output from assistant message content.
-     * For native strategy: content should be valid JSON.
-     * For tool-based strategy: last-resort fallback extraction from text.
-     */
-    parseFromContent(content: string): StructuredOutputResult<T>;
-    /**
-     * Create a "no output" error result.
-     */
-    noOutputResult(attempts: number, rawContent?: string): StructuredOutputResult<T>;
+declare function definePlugin<TConfig = void>(factory: (config: TConfig) => AgentPlugin): (config: TConfig) => AgentPlugin;
+/**
+ * A single hook, packaged as a plugin. For the common case where naming and a
+ * lifecycle would be ceremony:
+ *
+ *   defineHook("preToolUse", ({ toolName }) => toolName === "shell" ? { decision: "ask" } : undefined)
+ */
+declare function defineHook<K extends HookName>(hook: K, handler: HookHandler<K>, opts?: {
+    name?: string;
+    priority?: number;
+    failureMode?: PluginFailureMode;
+    timeoutMs?: number;
+    inheritToSubagents?: boolean;
     /**
-     * Create a "max retries" error result.
+     * Declare that this hook never returns `decision: "ask"`. Without it a
+     * `preToolUse` hook is assumed to be able to pause, and the whole tool
+     * batch is scheduled serially — silently costing an agent its parallel
+     * tool execution.
      */
-    maxRetriesResult(lastError: StructuredOutputError, attempts: number, rawContent?: string): StructuredOutputResult<T>;
-}
+    mayRequireApproval?: boolean;
+}): AgentPlugin;
 
 /**
- * Tool-based structured output strategy.
+ * What this build actually implements.
  *
- * Injects a hidden `response` tool that the model must call with the final JSON.
- * This is the universal fallback that works with all providers.
+ * A policy configured as `mode: "enforce"` whose hook is never called is worse
+ * than no policy: the console shows a control that does not exist. A host
+ * cannot infer that from the type surface, because a declared hook and a wired
+ * one look identical to TypeScript — so the runtime states it.
+ *
+ * This table is maintained BY HAND alongside the wiring. That is deliberate:
+ * deriving it from the registry would only prove that a handler was registered,
+ * not that any call site raises it, which is precisely the failure it exists to
+ * make visible.
  */
-declare class ToolBasedStrategy implements StructuredOutputStrategy {
-    readonly kind: "tool_based";
-    /**
-     * Create the `response` tool for a given Zod schema.
-     * The tool validates input against the schema and returns a sentinel object
-     * that the tools node picks up to finalize the structured output.
-     */
-    createResponseTool<T>(schema: ZodSchema<T>): ToolInterface;
-    /**
-     * Try to extract structured output from raw assistant text content.
-     * Used as a last resort when the model writes JSON directly instead of calling the tool.
-     */
-    extractFromText<T>(content: string, schema: ZodSchema<T>): {
-        data: T;
-    } | {
-        error: StructuredOutputError;
-    };
-    buildCorrectionPrompt(error: ZodError<any>, previousAttempt: unknown): string;
-}
 
 /**
- * Native JSON Schema strategy for providers that support `response_format`.
+ * Bumped when the hook contract changes shape in a way a host must notice —
+ * a hook gains or loses a call site, a payload field changes meaning, a slot
+ * starts or stops being consumed. Independent of the package version.
+ */
+declare const HOOK_CONTRACT_VERSION = 1;
+type CapabilityStatus = {
+    /** True when a call site in the runtime actually raises this. */
+    implemented: boolean;
+    /** Why not, or what the caveat is. */
+    notes?: string;
+};
+type SdkCapabilities = {
+    hookContractVersion: number;
+    hooks: Record<HookName, CapabilityStatus>;
+    slots: Record<SlotName, CapabilityStatus>;
+    features: Record<string, CapabilityStatus>;
+};
+/**
+ * Hook ids used by the Cognipeer Console's guardrail plane, mapped onto this
+ * SDK's hooks.
  *
- * Works with OpenAI (gpt-4o+), Google Gemini, and similar providers
- * that accept `response_format: { type: "json_schema", json_schema: {...} }`.
+ * The Console plane originally had one input stage, which collapsed two
+ * moments that behave differently: `userPromptSubmit` fires ONCE for a new
+ * user turn and can see attachments, while `preModelCall` fires before EVERY
+ * provider call — which is where the legacy `GuardrailPhase.Request` actually
+ * ran. A policy meant to vet what a person typed wants the first; one meant to
+ * vet every prompt reaching the model, including turns built from tool output,
+ * wants the second. Mapping both to one id silently changes how often the
+ * policy runs, and on a moderation-model guardrail that is a cost as well as a
+ * semantics bug.
  *
- * The model guarantees valid JSON output matching the schema — no tool needed.
+ * The Console added `prompt.pre` for the first and kept `input.pre` meaning
+ * the second, so every id below is single-valued.
  */
-declare class NativeJsonSchemaStrategy implements StructuredOutputStrategy {
-    readonly kind: "native";
-    private resolveJsonPointer;
-    private unwrapRootObjectSchema;
+declare const CONSOLE_HOOK_MAP: Readonly<Record<string, HookName | null>>;
+/** What this build implements. Safe to call at any time; allocates a fresh copy. */
+declare function pluginCapabilities(): SdkCapabilities;
+/** Convenience for a host that only wants to know whether it can enforce. */
+declare function isHookImplemented(hook: HookName): boolean;
+
+/**
+ * Guardrail transport + the plugin that drives it.
+ *
+ * Layered the way tracing sinks are layered — a transport seam, a generic HTTP
+ * implementation, an in-process escape hatch, and thin first-party presets on
+ * top (see `cognipeerGuardrail`, `portkeyGuardrail`). What is deliberately NOT
+ * copied from tracing is its retry policy: a trace post can afford four
+ * attempts at an 8s timeout because nothing waits on it, while a guardrail sits
+ * on the critical path of every turn and the same policy would stall an agent
+ * for half a minute.
+ */
+
+/**
+ * `tool` is the ARGUMENTS a model wants to run; `tool_result` is what came
+ * back. They are different surfaces with different risks — one is an action
+ * about to happen, the other is untrusted content entering the context — and a
+ * policy usually wants different rules for each.
+ */
+type GuardrailPhaseName = "input" | "output" | "tool" | "tool_result";
+type GuardrailRequest = {
+    phase: GuardrailPhaseName;
+    content: string;
+    /** Tool name for `tool` / `tool_result`, otherwise unset. */
+    subject?: string;
+    /** The SDK hook this check was raised from, so a preset can map it exactly. */
+    hook?: string;
+    /** Structured tool arguments, for a service that wants them un-stringified. */
+    toolArgs?: unknown;
+    /** The tool's return value, for `tool_result`. */
+    toolResult?: unknown;
     /**
-     * Convert a Zod schema to the JSON Schema object used in response_format.
+     * Non-text parts of the turn — images, audio, video, files. A text-only
+     * policy sees the caption and nothing else, so a service that moderates
+     * media needs these; one that does not simply ignores the field.
+     *
+     * Inline payloads are DESCRIBED (kind, media type, size) rather than
+     * inlined: shipping a base64 image on every check would multiply the cost of
+     * the guardrail by the size of the upload. A service that needs the bytes
+     * should take a URL, or the caller should override `buildRequest`.
      */
-    toJsonSchema(schema: ZodSchema<any>, name?: string): Record<string, any>;
+    attachments?: MediaAttachment[];
+    metadata?: Record<string, unknown>;
+};
+type GuardrailViolation = {
+    id?: string;
+    type?: string;
+    severity?: string;
+    detail?: string;
+};
+type GuardrailVerdict = {
+    action: "allow" | "block" | "mask";
+    message?: string;
+    /** Required when `action === "mask"`. */
+    maskedContent?: string;
+    violations?: GuardrailViolation[];
+    /** The untouched service response, for tracing and debugging. */
+    raw?: unknown;
+};
+type GuardrailCallContext = {
+    runId: string;
+    agentName?: string;
+    /** Correlates a guardrail decision with the trace session in the console UI. */
+    traceId?: string;
+    signal?: AbortSignal;
+};
+type GuardrailTransport = {
+    name: string;
+    /** Verdicts must come back in the same order as `requests`. */
+    evaluate(requests: GuardrailRequest[], ctx: GuardrailCallContext): MaybePromise<GuardrailVerdict[]>;
     /**
-     * Build response_format configuration for the model call.
-     * Returns the object that should be spread into model invocation options.
+     * Optional setup-time handshake. When a service can say which phases carry
+     * active rules, every other phase skips the network entirely — usually the
+     * single biggest latency win available here.
      */
-    buildResponseFormat(schema: ZodSchema<any>, name?: string): Record<string, any>;
+    describe?: () => MaybePromise<{
+        activePhases?: GuardrailPhaseName[];
+    } | null | undefined>;
+    close?: () => MaybePromise<void>;
+};
+type HttpGuardrailOptions = {
+    url: string;
+    /** Static headers, or a thunk so a rotating token is read per call. */
+    headers?: Record<string, string> | (() => Record<string, string>);
+    /** Hard ceiling per attempt. Default 3000ms — this is on the critical path. */
+    timeoutMs?: number;
+    /** Retries after the first attempt. Default 1. */
+    retries?: number;
+    /** Send all pending checks in one request. Default true. */
+    batch?: boolean;
+    /** Override the wire request. Default: `{ items, runId, traceId }`. */
+    buildRequest?: (requests: GuardrailRequest[], ctx: GuardrailCallContext) => unknown;
+    /** Override response mapping. Default: `normalizeVerdicts`, which is forgiving. */
+    mapVerdict?: (response: unknown, requests: GuardrailRequest[]) => GuardrailVerdict[];
     /**
-     * Parse and validate model response content.
-     * With native support, content is guaranteed JSON — but we still validate with Zod
-     * for type safety and field-level error reporting.
+     * Status codes that carry a VERDICT rather than an error. Some services
+     * signal the outcome in the status line (e.g. 446 for a block); treating
+     * those as transport failures would route a real decision through the
+     * failureMode path with the wrong reason attached.
      */
-    extractOutput<T>(content: string, schema: ZodSchema<T>): {
-        data: T;
-    } | {
-        error: StructuredOutputError;
+    verdictStatuses?: number[];
+    /** Optional GET endpoint for the setup-time handshake. */
+    describeUrl?: string;
+    name?: string;
+};
+/**
+ * Accepts the shapes a guardrail service is likely to return and normalizes
+ * them. Being forgiving here is the point: the exact contract can change on the
+ * service side without a client release, and a stricter parser would turn a
+ * cosmetic field rename into an outage.
+ */
+declare function normalizeVerdicts(response: unknown, requests: GuardrailRequest[]): GuardrailVerdict[];
+declare function httpGuardrail(options: HttpGuardrailOptions): GuardrailTransport;
+/** In-process evaluation — regex policies, a local model, Presidio, tests. */
+declare function customGuardrail(evaluate: (request: GuardrailRequest, ctx: GuardrailCallContext) => MaybePromise<GuardrailVerdict | void>, name?: string): GuardrailTransport;
+type GuardrailPluginOptions = {
+    name: string;
+    transport: GuardrailTransport;
+    /** Which surfaces to check. Default: input + output. */
+    apply?: GuardrailPhaseName[];
+    /**
+     * `shadow` evaluates and reports but never blocks or masks. This is how a
+     * policy gets rolled out safely: measure what it would have caught first.
+     */
+    mode?: "enforce" | "shadow";
+    /** Block when the service is unreachable. Default true. */
+    failClosed?: boolean;
+    timeoutMs?: number;
+    priority?: number;
+    inheritToSubagents?: boolean;
+    /** Memoize verdicts per run. Default true. */
+    cache?: boolean | {
+        maxEntries?: number;
     };
-    buildCorrectionPrompt(error: ZodError<any>, previousAttempt: unknown): string;
-}
+    /** Extra metadata attached to every request. */
+    metadata?: Record<string, unknown>;
+};
+declare function createGuardrailPlugin(options: GuardrailPluginOptions): AgentPlugin;
 
 /**
- * Resolve the most appropriate structured output strategy for a given model.
+ * Cognipeer Console guardrail — the first-party preset.
  *
- * If the model exposes capabilities (via adapter or direct provider),
- * we use native JSON Schema support when available. Otherwise we fall back
- * to the universal tool-based approach.
+ * Talks to the Console's HOOK plane, not its single-shot evaluator:
  *
- * When direct providers are added to the SDK, they should set
- * `model.capabilities.structuredOutput = "native"` for providers that support
- * response_format (OpenAI, Gemini, etc.).
- */
-declare function resolveStrategy(model: any): StructuredOutputStrategy;
-/**
- * Extract capabilities from a model object.
- * Supports:
- *   - model.capabilities (set by adapters or direct providers)
- *   - Auto-detection from model class name / metadata
+ *   POST {baseUrl}/api/client/v1/guardrails/hooks/evaluate
+ *   Authorization: Bearer <api key>
+ *   { hook, guardrail_keys, text?, tool_name?, tool_args?, tool_result?, … }
+ *
+ * Three properties of that contract shape everything below, and getting any of
+ * them wrong turns a working policy into a silent one:
+ *
+ *   `decision`  is the EFFECTIVE verdict, already neutralised in monitor mode.
+ *               Priority runs block > redact > warn > flag > allow.
+ *   `enforced`  false means the decision was NOT applied — a dry run. Blocking
+ *               on `decision === "block"` without checking this turns every
+ *               monitoring policy into an enforcing one on the day it is
+ *               switched on for observation.
+ *   `passed`    means "no blocking finding", NOT "the request was allowed".
+ *               The two diverge in monitor mode, which is exactly when someone
+ *               reads the wrong one.
+ *
+ * `subject` (or `redacted_text` for the text case) is filled only when the
+ * service actually rewrote something; when it is present it REPLACES what was
+ * sent rather than being merged with it.
+ *
+ * The endpoint answers 200 for a finding as readily as for a clean check, and
+ * only emits 246/446 when a guardrail opts into verdict status codes — so both
+ * are declared as verdict-carrying rather than treated as transport failures.
+ * An unknown key answers 404 ON PURPOSE: a vacuous allow read as "content is
+ * safe" is the failure the whole plane exists to avoid.
  */
-declare function getModelCapabilities(model: any): ModelCapabilities;
-
-declare function captureSnapshot(state: SmartState, options?: SnapshotOptions): AgentSnapshot;
-declare function restoreSnapshot(snapshot: AgentSnapshot, restoreOptions?: RestoreSnapshotOptions): SmartState;
-
-declare function resolveToolApprovalState(state: SmartState, resolution: ToolApprovalResolution): SmartState;
-
-declare function resolveUserQuestionState(state: SmartState, resolution: UserQuestionResolution): SmartState;
 
-/**
- * The built-in ask-user tool's name. Exported because more than one layer has to
- * recognise it: `createSmartAgent` builds the tool into the list it hands to
- * `createAgent`, which must then not attach a second one of its own.
- */
-declare const ASK_USER_TOOL_NAME = "ask_user_question";
-type AskUserStateRef = {
-    pendingUserQuestions?: PendingUserQuestion[];
-    ctx?: Record<string, any>;
-    __onEvent?: (event: any) => void;
-    __currentToolCallId?: string;
-};
-declare function createAskUserQuestionTool(stateRef: AskUserStateRef, config: HumanInTheLoopAskUserConfig): ToolInterface<any, any, any>;
-
-declare function fromLangchainTools<T extends ToolInterface = ToolInterface>(tools: any[]): T[];
-
-type ResolvedReflectionConfig = {
-    enabled: boolean;
-    cadence: ReflectionCadence;
-    mode: "piggyback" | "separate";
-    maxTokens: number;
-    maxChars: number;
-    keepLast: number;
-    summarize: boolean;
-    promptTemplate?: string;
-    emitEvents: boolean;
-    maxPerRun?: number;
-    everyNTurns: number;
-    feedTo: "memory" | "plan" | "none";
-    shouldReflect?: (ctx: ReflectionHookContext) => boolean;
-    buildPrompt?: (ctx: ReflectionHookContext & {
-        defaultPrompt: string;
-        maxChars: number;
-    }) => string;
-    onReflection?: (record: ReflectionRecord, ctx: ReflectionHookContext) => void;
-};
-type ResolvedReasoning = {
-    enabled: boolean;
-    level: ReasoningLevel;
-    native?: NativeReasoningConfig;
-    reflection: ResolvedReflectionConfig;
-};
-/**
- * Validates a user-supplied ReasoningConfig and throws a descriptive error for
- * obviously-wrong values. Pure; safe to call before resolveReasoning.
- */
-declare function validateReasoningConfig(input: ReasoningConfig | undefined): void;
-declare function resolveReasoning(input: ReasoningConfig | undefined): ResolvedReasoning | undefined;
-
-/**
- * Tools the agent loop uses to steer ITSELF. Their arguments are never digested —
- * digesting them is never a win (the arguments are small) and always a risk:
- *  - `response` carries the run's final structured output,
- *  - `manage_plan` (and its deprecated alias `manage_todo_list` — same handler,
- *    same shared state, see contextTools.ts) carries the living plan,
- *  - `ask_user_question` carries the question the user's answer replies to,
- *  - `open_skill` / `bind_skill_tools` / `search_skills` name the capability being
- *    loaded, which the rest of the run reasons about,
- *  - `get_tool_response` is the recovery path itself.
- * They also default to `keep_full` on the output axis (overridable per tool).
- */
-declare const CONTROL_PLANE_TOOL_NAMES: readonly string[];
-/**
- * Delegation tools: the arguments ARE the brief handed to the child agent — the
- * parent must be able to say what it delegated. Never digested. The child's report
- * (the output) may still be archived and paged back in.
- */
-declare const DELEGATION_TOOL_NAMES: readonly string[];
-declare const DEFAULT_MAX_TOOL_INPUT_FIELD_CHARS = 2000;
-declare const DEFAULT_TOOL_INPUT_DIGEST_HEAD_CHARS = 200;
-/** Key marking a digested argument field. Recognized as a recovery reference. */
-declare const TOOL_INPUT_DIGEST_KEY = "__digest";
-/**
- * Compact textual preview of a value for archive/structured retention. Used by
- * the summarizer when an old tool response is reduced to a placeholder. Not
- * used at tool execution time.
- */
-declare function summarizeObject(value: any): string;
-/**
- * Tool-definition-declared retention specs, keyed by tool name. Built from the
- * runtime's live tool list so a skill-bound tool contributes its own declaration.
- */
-type ToolRetentionDeclarations = Map<string, ToolRetentionSpec>;
-declare function collectToolRetentionDeclarations(tools: Array<ToolInterface<any, any, any>> | undefined): ToolRetentionDeclarations;
-/**
- * Resolves the retention policy applied by the summarizer when context limits
- * are reached. Critical tools are never reduced.
- *
- * Precedence (first match wins):
- *  1. `criticalTools` — absolute, never reduced (documented contract).
- *  2. `toolResponses.retentionByTool[name].output` — caller's two-axis override.
- *  3. `toolResponses.toolResponseRetentionByTool[name]` — legacy single-axis map.
- *  4. the tool definition's own `retention.output`.
- *  5. built-in control-plane default (`keep_full`).
- *  6. `toolResponses.defaultPolicy`.
- */
-declare function resolveSummarizationRetention(toolName: string, config: ResolvedSmartAgentConfig, declarations?: ToolRetentionDeclarations): ToolResponseRetentionPolicy;
-/**
- * Resolves the retention policy applied to a tool call's ARGUMENTS.
- *
- * Precedence (first match wins):
- *  1. control-plane + delegation tools — always `keep` (hard invariant).
- *  2. `criticalTools` — a tool whose response may never be reduced does not get
- *     its request reduced either.
- *  3. `toolResponses.retentionByTool[name].input`.
- *  4. the tool definition's own `retention.input`.
- *  5. `toolResponses.defaultInputPolicy` (defaults to `keep`).
- *
- * The default is `keep`, so argument digesting never happens unless a tool or a
- * caller explicitly asks for it.
- */
-declare function resolveInputRetention(toolName: string, config: ResolvedSmartAgentConfig, declarations?: ToolRetentionDeclarations): ToolInputRetentionPolicy;
-type ToolInputDigestOptions = {
-    /** Per-field character threshold. Strings at or below this are preserved verbatim. */
-    maxFieldChars?: number;
-    /** Leading characters of a digested field kept as a preview. */
-    headChars?: number;
-    /** Execution id embedded in each marker so the model can page the original back in. */
-    executionId?: string;
-};
-type ToolInputDigestResult = {
-    /** The rewritten value. Identical reference when nothing was digested. */
-    value: unknown;
-    /** Dotted paths of the fields that were replaced by a digest marker. */
-    digestedPaths: string[];
-    /** Characters reclaimed from the serialized arguments. */
-    reclaimedChars: number;
-};
-/**
- * Field-level argument digest.
- *
- * Walks the argument structure and replaces ONLY string leaves longer than
- * `maxFieldChars` with a compact descriptor. Every other field — paths, ids,
- * modes, indexes, booleans, short strings — is preserved verbatim, so a call like
- *
- *   { filePath: "/reports/q3.md", mode: "append", section: 3, content: "<60k>" }
- *
- * compacts to
- *
- *   { filePath: "/reports/q3.md", mode: "append", section: 3,
- *     content: { __digest: { chars: 61840, sha256: "…", head: "# Q3 …", recover: "…" } } }
- *
- * The model can still state exactly what it did; only the payload it no longer
- * needs to re-read is gone. Idempotent: an existing digest marker is left alone.
- */
-declare function digestToolInputValue(value: unknown, options?: ToolInputDigestOptions): ToolInputDigestResult;
-/**
- * Digest a serialized `tool_call.function.arguments` JSON string in place.
- * Returns the input string unchanged when nothing needed digesting, when the
- * string is not parseable JSON (never guess at a non-JSON payload), or when the
- * result would not actually be smaller.
- */
-declare function digestToolInputArguments(argumentsJson: string, options?: ToolInputDigestOptions): {
-    arguments: string;
-    digestedPaths: string[];
-    reclaimedChars: number;
-};
-/**
- * Parse tool arguments against the tool's schema.
- *
- * Two passes, and the order is the contract: the raw arguments are validated
- * FIRST, so a model that emits well-typed arguments is unaffected and the schema
- * stays a real constraint. Only when that fails are the arguments run through
- * `coerceToolArgs` and re-validated — repairing the type artifacts smaller and
- * grammar-constrained backends produce (a nested object sent as a JSON string, a
- * number sent as `"60"`, `""` standing in for an omitted optional) instead of
- * spending a turn telling the model something it did not get wrong.
- *
- * Coercion never fabricates a value, so a genuinely missing required argument
- * still fails — and it fails with the ORIGINAL issues plus the shape the tool
- * actually wants, because "expected object, received string" on its own does not
- * tell a weaker model which key to fix.
- */
-declare function validateToolArgs(tool: ToolInterface<any, any, any>, args: unknown): {
-    ok: true;
-    value: any;
-    coerced?: boolean;
-} | {
-    ok: false;
-    message: string;
-};
-
-/**
- * Re-type `value` so it satisfies `schema`, walking both together.
- *
- * Returns the original value untouched whenever nothing needs repairing or
- * nothing sensible can be done — this must never throw, because it runs on the
- * error path and a throw here would replace a useful validation message with a
- * crash.
- */
-declare function coerceToolArgs(schema: unknown, value: unknown): unknown;
-
-declare function fileSink(path?: string): TraceSinkConfig;
-type CustomSinkArg = ((event: TraceEventRecord) => void | Promise<void>) | {
-    onEvent?: (event: TraceEventRecord) => void | Promise<void>;
-    onSession?: (session: TraceSessionFile) => void | Promise<void>;
+type CognipeerGuardrailConfig = {
+    /** Guardrail keys from the Console. Defaults to `COGNIPEER_GUARDRAIL_KEYS` (comma-separated). */
+    guardrailKeys?: string[];
+    /** Convenience for the single-key case. */
+    guardrailKey?: string;
+    /** Defaults to `COGNIPEER_API_KEY`. */
+    apiKey?: string;
+    /** Defaults to `COGNIPEER_BASE_URL`, then the production console. Point at localhost for local runs. */
+    baseUrl?: string;
+    /** Override the hook-evaluate path. */
+    path?: string;
+    /** Surfaces to guard. Default: input + output. Add `"tool"` / `"tool_result"` for the tool surface. */
+    apply?: GuardrailPhaseName[];
+    /** Restrict to specific check families, e.g. `["pii"]`. */
+    only?: string[];
+    /** Override the SDK-hook → Console-hook-id mapping, merged over the default. */
+    hookIds?: Record<string, string>;
+    /** Ask the service to evaluate without enforcing. Independent of `mode`. */
+    shadow?: boolean;
+    /** `shadow` here reports locally without acting, whatever the service says. */
+    mode?: "enforce" | "shadow";
+    /** Default true — an unreachable or misconfigured policy blocks rather than silently stops guarding. */
+    failClosed?: boolean;
+    /** Per-check ceiling. Default 3000ms; also sent as `budget_ms`. */
+    timeoutMs?: number;
+    retries?: number;
+    priority?: number;
+    cache?: boolean | {
+        maxEntries?: number;
+    };
+    metadata?: Record<string, unknown>;
+    buildRequest?: (requests: GuardrailRequest[], ctx: GuardrailCallContext) => unknown;
+    mapVerdict?: (response: unknown, requests: GuardrailRequest[]) => GuardrailVerdict[];
+    name?: string;
 };
-declare function customSink(handler: CustomSinkArg): TraceSinkConfig;
-declare function cognipeerSink(apiKey: string): TraceSinkConfig;
-declare function cognipeerSink(url: string | undefined, apiKey: string): TraceSinkConfig;
-declare function httpSink(url: string, headers?: Record<string, string>): TraceSinkConfig;
-/**
- * Create an OTLP/HTTP JSON sink that exports traces in OpenTelemetry format.
- * @param endpoint OTLP endpoint URL (e.g. "https://console.cognipeer.com/api/client/v1/traces")
- * @param headers Optional headers (e.g. { Authorization: "Bearer ..." })
- */
-declare function otlpSink(endpoint: string, headers?: Record<string, string>): TraceSinkConfig;
-/**
- * Convert a complete TraceSessionFile into an OTLP ExportTraceServiceRequest (JSON).
- * Produces a root span for the session and child spans for each event.
- */
-declare function traceSessionToOtlp(session: TraceSessionFile): Record<string, unknown>;
-/** Generate a W3C-compatible trace ID (32 hex chars / 128-bit). */
-declare function generateTraceId(): string;
-/** Generate an OTel span ID (16 hex chars / 64-bit). */
-declare function generateSpanId(): string;
-/**
- * Build the `tool_definitions` section for one model call, or undefined when
- * nothing usable was supplied. Exported for provider/node code that assembles
- * sections itself.
- */
-declare function buildToolDefinitionsSection(toolDefinitions: Array<{
-    name: string;
-    description?: string;
-    parameters?: Record<string, any>;
-}>): TraceToolDefinitionsSection | undefined;
-/**
- * Build the `response_format` section for one model call, or undefined when
- * nothing usable was supplied.
- *
- * Accepts either the invoke-options wrapper produced by
- * `NativeJsonSchemaStrategy.buildResponseFormat()` (`{ response_format: {…} }`)
- * or a bare `response_format` object, so callers can pass whatever they hold.
- * Exported for provider/node code that assembles sections itself.
- */
-declare function buildResponseFormatSection(responseFormat: Record<string, any> | undefined, strategy?: "native" | "tool_based"): TraceResponseFormatSection | undefined;
-/**
- * Start a streaming trace session. Should be called before recording events in streaming mode.
- * This sends the session start to the remote endpoint immediately.
- */
-declare function startStreamingSession(session: TraceSessionRuntime | undefined, agentRuntime?: AgentRuntimeConfig): Promise<void>;
+/** The Console's hook response, mapped onto the transport's three-valued verdict. */
+declare function mapConsoleHookVerdict(response: unknown, requests: GuardrailRequest[]): GuardrailVerdict[];
+declare function cognipeerGuardrail(config?: CognipeerGuardrailConfig): AgentPlugin;
 
 type MessageRole = "system" | "user" | "assistant" | "tool";
 type TextContent = {
@@ -3311,6 +3930,1479 @@ declare class ProviderError extends Error {
     constructor(message: string, provider: string, statusCode?: number | undefined, responseBody?: any | undefined);
 }
 
+/**
+ * Portkey — two integration shapes, because Portkey supports two.
+ *
+ *   Gateway    all model traffic flows through Portkey and its guardrails run
+ *              on their hop. No extra latency, but it only covers model calls —
+ *              tool arguments and tool output never reach it.
+ *   Standalone the model talks to its provider directly and we call Portkey's
+ *              guardrail API ourselves. Full coverage including the tool
+ *              surface, at the cost of an extra round trip per checked turn.
+ *
+ * Gateway mode is deliberately NOT a `wrapModel` contribution. Retargeting an
+ * arbitrary already-constructed model object is guesswork; building the
+ * provider config that points at the gateway is exact. `portkeyGateway()`
+ * returns that config.
+ */
+
+type PortkeyGatewayConfig = {
+    /** Defaults to `PORTKEY_API_KEY`. */
+    apiKey?: string;
+    /** Portkey config id carrying the guardrail attachment. */
+    configId?: string;
+    /** Portkey virtual key for the upstream provider credentials. */
+    virtualKey?: string;
+    baseURL?: string;
+    defaultModel?: string;
+    /** Merged last, so it can override anything above. */
+    headers?: Record<string, string>;
+};
+/**
+ * Build the provider config that routes model traffic through the Portkey
+ * gateway. Hand the result to `createProvider`:
+ *
+ *   const model = fromNativeProvider(createProvider(portkeyGateway({ configId })));
+ */
+declare function portkeyGateway(config?: PortkeyGatewayConfig): OpenAICompatibleProviderConfig;
+type PortkeyGuardrailConfig = {
+    /** Defaults to `PORTKEY_API_KEY`. */
+    apiKey?: string;
+    baseUrl?: string;
+    /** Path of the guardrail evaluation endpoint. */
+    path?: string;
+    /** Guardrail / check ids to run. */
+    checks?: string[];
+    apply?: GuardrailPhaseName[];
+    mode?: "enforce" | "shadow";
+    failClosed?: boolean;
+    timeoutMs?: number;
+    retries?: number;
+    priority?: number;
+    batch?: boolean;
+    cache?: boolean | {
+        maxEntries?: number;
+    };
+    metadata?: Record<string, unknown>;
+    /** Escape hatch for the exact wire shape. */
+    buildRequest?: (requests: GuardrailRequest[], ctx: GuardrailCallContext) => unknown;
+    mapVerdict?: (response: unknown, requests: GuardrailRequest[]) => GuardrailVerdict[];
+    name?: string;
+};
+/**
+ * Standalone-mode Portkey guardrails. Covers the tool surface that gateway mode
+ * cannot see, so the two are complementary rather than alternatives — running
+ * gateway for model traffic and this for tools is a valid configuration.
+ */
+declare function portkeyGuardrail(config?: PortkeyGuardrailConfig): AgentPlugin;
+
+/**
+ * PII redaction — the reference implementation of the mutation path.
+ *
+ * This plugin never blocks. It rewrites, which is the thing the v1 guardrail
+ * engine structurally could not do: a guardrail could only decide that a
+ * message containing a national id was unacceptable, not hand back the same
+ * message with the id masked.
+ *
+ * Detectors that can be checksummed are checksummed. A bare 11-digit or
+ * 16-digit regex matches order numbers, timestamps and product codes, and a
+ * redactor with a high false-positive rate gets switched off — which protects
+ * nothing at all.
+ */
+
+type PiiEntity = "TCKN" | "IBAN" | "EMAIL" | "PHONE_TR" | "CREDIT_CARD" | "IP" | "JWT" | "API_KEY";
+type PiiDetector = {
+    entity: string;
+    pattern: RegExp;
+    /** Second-stage check; a match that fails it is not a finding. */
+    validate?: (match: string) => boolean;
+};
+type PiiRedactionConfig = {
+    /** Which built-in detectors to run. Default: all of them. */
+    entities?: PiiEntity[];
+    /** Extra detectors, run after the built-ins. */
+    detectors?: PiiDetector[];
+    /** Where to redact. Default: user input, tool output and the final answer. */
+    apply?: Array<"input" | "toolOutput" | "modelOutput" | "finalAnswer">;
+    /** Build the replacement token. Default: `[REDACTED:ENTITY]`. */
+    mask?: (entity: string, match: string) => string;
+    /**
+     * Keep the last N characters visible (`[REDACTED:IBAN:…4821]`). Useful when
+     * the model must still be able to tell two redacted values apart.
+     */
+    keepLast?: number;
+    priority?: number;
+    name?: string;
+};
+/** Turkish national identification number, with its two checksum digits. */
+declare function isValidTckn(value: string): boolean;
+/** Luhn — catches most typos and nearly all non-card digit runs. */
+declare function isValidLuhn(value: string): boolean;
+/** ISO 13616 mod-97 check. */
+declare function isValidIban(value: string): boolean;
+type RedactionResult = {
+    text: string;
+    findings: Array<{
+        entity: string;
+        count: number;
+    }>;
+};
+declare function redactText(text: string, detectors: PiiDetector[], mask: (entity: string, match: string) => string): RedactionResult;
+declare function piiRedaction(config?: PiiRedactionConfig): AgentPlugin;
+
+/**
+ * Central tool policy.
+ *
+ * Today approval lives on the tool definition (`needsApproval`), which means a
+ * policy has to be edited into every tool it governs — including tools that
+ * arrived from an MCP server and are not yours to edit. This moves the decision
+ * to one place the security owner can read in full.
+ *
+ * The escalation rule is enforced by the host, not here: a hook can raise a
+ * call to `ask` or `deny`, and can never lower one. A policy that could grant
+ * `allow` over a tool's own `needsApproval: true` would be a way to switch the
+ * approval system off from a plugin.
+ */
+
+type ToolRule = {
+    /** Exact tool name, or a RegExp tested against it. */
+    tool: string | RegExp;
+    /** What to do when this rule matches. */
+    action: "allow" | "ask" | "deny";
+    /** Narrow the rule to specific arguments. */
+    when?: (args: Record<string, unknown>) => boolean;
+    /** Message shown to the reviewer, or handed back to the model on `deny`. */
+    reason?: string | ((args: Record<string, unknown>, toolName: string) => string);
+};
+type ToolPolicyConfig = {
+    /** Evaluated in order; the first match wins. */
+    rules?: ToolRule[];
+    /** Shorthand: always require approval for these tools. */
+    ask?: Array<string | RegExp>;
+    /** Shorthand: always refuse these tools. */
+    deny?: Array<string | RegExp>;
+    /**
+     * When set, any tool NOT named here is denied. The strictest useful setting
+     * for an agent with dynamically discovered tools.
+     *
+     * The SDK's own control-plane tools are exempt by default — see
+     * `governControlPlaneTools`.
+     */
+    allowOnly?: Array<string | RegExp>;
+    /**
+     * Whether `allowOnly` also governs the SDK's own machinery:
+     * `ask_user_question`, `manage_plan`, `get_tool_response`, `response`,
+     * `open_skill` and friends.
+     *
+     * Default false. An allow-list is written by naming the tools you care
+     * about, and nobody writing one means "also stop the agent from asking me a
+     * question or returning its structured output". Governing them silently
+     * breaks human-in-the-loop, planning and structured output at once, and the
+     * symptom — a run that quietly stops using half the runtime — points nowhere
+     * near the policy. Set true to govern them anyway; an explicit `deny` entry
+     * or a rule still applies to them either way.
+     */
+    governControlPlaneTools?: boolean;
+    /** Cap executions per tool, per run — a loop-breaker for retry storms. */
+    maxExecutionsPerTool?: number | Record<string, number>;
+    priority?: number;
+    name?: string;
+};
+declare function toolPolicy(config?: ToolPolicyConfig): AgentPlugin;
+/**
+ * Path sandbox for filesystem-shaped tools. Rejects absolute escapes, parent
+ * traversal, and anything resolving outside the allowed roots.
+ */
+declare function pathSandbox(config: {
+    /** Argument names that carry a path. Default: path, file, filePath, dir, directory. */
+    argNames?: string[];
+    /** Allowed prefixes. A path must start with one of them once normalized. */
+    roots: string[];
+    /** Only apply to these tools. Default: every tool that carries a path argument. */
+    tools?: Array<string | RegExp>;
+    name?: string;
+    priority?: number;
+}): AgentPlugin;
+
+/**
+ * Spend ceiling for a run.
+ *
+ * Counters are derived from `state.usage` rather than kept in the plugin's own
+ * store, which makes the budget correct across a pause/resume boundary for
+ * free: plugin stores are per-run and would reset to zero on resume, while
+ * `state.usage` is part of the snapshot.
+ */
+
+type BudgetGuardConfig = {
+    /** Hard ceiling in USD. Requires `costEstimator`. */
+    maxUsd?: number;
+    /** Hard ceiling on cumulative output tokens across the run. */
+    maxOutputTokens?: number;
+    /** Hard ceiling on model calls. */
+    maxModelCalls?: number;
+    /**
+     * Per-run pricing. Without it the USD ceiling is inert — the SDK carries no
+     * built-in price table, and a stale one is worse than none.
+     */
+    costEstimator?: CostEstimator;
+    /** `deny` stops the run; `warn` only emits. Default `deny`. */
+    onExceeded?: "deny" | "warn";
+    /** Emit a `metadata` event once this fraction of the budget is used. Default 0.8. */
+    warnAt?: number;
+    priority?: number;
+    name?: string;
+};
+declare function budgetGuard(config?: BudgetGuardConfig): AgentPlugin;
+
+/**
+ * Append-only record of what the agent tried to do.
+ *
+ * Registered at priority 0 so it observes every tool attempt *before* any
+ * policy plugin can deny it — an audit log that only sees the calls that were
+ * allowed answers the wrong question. The outcome of each attempt is reconciled
+ * at `sessionEnd` from `toolHistory`, which carries the final status
+ * (`success` / `error` / `rejected` / `handoff`) for every call.
+ */
+
+type AuditEntry = {
+    runId: string;
+    agentName?: string;
+    at: string;
+    kind: "tool_attempt" | "tool_outcome" | "notification" | "session_end";
+    toolName?: string;
+    toolCallId?: string;
+    args?: unknown;
+    status?: string;
+    detail?: unknown;
+};
+type AuditLogConfig = {
+    /** Where entries go. Defaults to `console.log` of a compact JSON line. */
+    sink?: (entry: AuditEntry) => MaybePromise<void>;
+    /** Include tool arguments. Off by default — arguments routinely carry PII. */
+    includeArgs?: boolean;
+    /** Truncate serialized arguments to this many characters. Default 2000. */
+    maxArgChars?: number;
+    name?: string;
+};
+declare function auditLog(config?: AuditLogConfig): AgentPlugin;
+
+/**
+ * Slot implementations for the two stores every product ends up writing itself:
+ * conversation history and checkpoint persistence.
+ *
+ * The in-memory versions are real implementations, not stubs — they are the
+ * right choice for tests, for single-process workers, and for a first
+ * deployment. The file-backed checkpoint store is the smallest thing that
+ * survives a restart.
+ */
+
+type ConversationPluginConfig = {
+    store: ConversationStore;
+    /**
+     * Which thread this run belongs to. A string is a fixed thread; a function
+     * reads it from the incoming state (typically `state.metadata.threadId`).
+     */
+    threadId: string | ((state: unknown) => string | undefined);
+    /** Cap the messages loaded back. Default: everything the store returns. */
+    maxMessages?: number;
+    name?: string;
+    priority?: number;
+};
+/**
+ * Hydrates the transcript on `sessionStart` and appends the new turns on
+ * `sessionEnd`. Only messages produced by this run are appended, so replaying
+ * the same thread does not duplicate history.
+ */
+declare function conversationHistory(config: ConversationPluginConfig): AgentPlugin;
+declare function inMemoryConversationStore(): ConversationStore;
+type CheckpointPluginConfig = {
+    store: CheckpointStore;
+    /** Checkpoint id. Defaults to the run id. */
+    id?: string | ((state: unknown) => string | undefined);
+    /**
+     * Which pauses to persist. Default: every non-success ending, which is when a
+     * run can actually be continued.
+     */
+    saveOn?: Array<"paused" | "cancelled" | "error" | "success">;
+    /** Build the snapshot. Defaults to `captureSnapshot` semantics via the host. */
+    capture?: (state: unknown) => MaybePromise<AgentSnapshot>;
+    name?: string;
+    priority?: number;
+};
+/**
+ * Persists a snapshot whenever a run ends in a resumable state. The SDK already
+ * has `snapshot()` / `resume()`; what it has never had is somewhere to put the
+ * result.
+ */
+declare function checkpointing(config: CheckpointPluginConfig): AgentPlugin;
+declare function inMemoryCheckpointStore(): CheckpointStore;
+/**
+ * File-backed checkpoints. One JSON file per id under `dir`. Node only — the
+ * `fs` import is dynamic so bundling for an edge runtime does not pull it in
+ * unless this function is actually called.
+ */
+declare function fileCheckpointStore(dir?: string): CheckpointStore;
+
+/**
+ * Indirect prompt-injection screening.
+ *
+ * The dangerous text in an agent run is rarely what the user typed — it is what
+ * a tool brought back: a web page, a PDF, a ticket comment, an email body. That
+ * content lands in the same transcript as the operator's instructions, and the
+ * model has no channel-level way to tell the two apart. This plugin sits on
+ * `postToolUse`, which is exactly where fetched content enters, and labels it
+ * as data.
+ *
+ * It is a heuristic and it is worth being blunt about the limits. False
+ * positives are routine (a security wiki page *about* injection trips several
+ * families at once); false negatives are cheap for an attacker (a paraphrase, a
+ * translation, a homoglyph, an instruction split across two sentences). Treat
+ * this as defence in depth behind the real controls — a tool allow-list, egress
+ * restrictions, per-tool approval — and never as a trust boundary.
+ *
+ * The default action follows from that. Annotating keeps the fetched answer
+ * available while telling the model what it is holding; blocking would throw
+ * away a page that usually still contains the information the user asked for,
+ * and a screen that destroys useful work gets switched off within a week.
+ */
+
+type PromptInjectionFamily = "override" | "roleplay" | "fakeSystem" | "promptLeak" | "exfiltration" | "imageExfil" | "encodedPayload" | "custom";
+type PromptInjectionGuardConfig = {
+    /**
+     * What to do with flagged content. Default `annotate` — see the module note.
+     * `strip` drops the offending lines, `deny` refuses the tool result outright.
+     */
+    action?: "deny" | "annotate" | "strip";
+    /**
+     * Extra patterns, checked alongside the built-in families. They count as one
+     * additional family rather than joining an existing one: a caller-written
+     * pattern is a deliberate, site-specific signal, so it scores like a strong
+     * one instead of diluting the built-in weights.
+     */
+    patterns?: RegExp[];
+    /**
+     * Minimum score before acting, 0–1. Default 0.5, which one strong family
+     * clears on its own and one weak family does not.
+     */
+    minConfidence?: number;
+    /** Surfaces to screen. Default `["toolOutput"]`. */
+    applyTo?: Array<"toolOutput" | "input">;
+    name?: string;
+    priority?: number;
+};
+type InjectionScan = {
+    /** 0–1. A coarse count of independent signals, not a probability. */
+    confidence: number;
+    families: PromptInjectionFamily[];
+};
+declare function promptInjectionGuard(config?: PromptInjectionGuardConfig): AgentPlugin;
+
+/**
+ * Contract check on the final answer.
+ *
+ * Prompt engineering states the shape an answer must have; nothing verifies it.
+ * This is the verification step: length bounds, required and forbidden shapes,
+ * and an escape hatch for the checks that only the caller can express. A
+ * violation denies with the rule that failed named in the reason, so the
+ * failure is actionable rather than a generic "output rejected".
+ *
+ * Only `maxChars` can be repaired automatically. Every other rule describes
+ * something the answer is missing or must not contain, and there is no honest
+ * local edit for that — silently patching a non-conforming answer would return
+ * something the model never wrote and nobody reviewed.
+ */
+
+type OutputGuardConfig = {
+    /** Upper bound on the answer's length. */
+    maxChars?: number;
+    /** Lower bound, checked after trimming — whitespace is not an answer. */
+    minChars?: number;
+    /** Every pattern must match. Use for required sections, citations, formats. */
+    mustMatch?: RegExp[];
+    /** No pattern may match. Use for banned phrases, internal markers, hedges. */
+    mustNotMatch?: RegExp[];
+    /** Reject an empty or whitespace-only answer. Default true. */
+    forbidEmpty?: boolean;
+    /** Caller-defined rule. Return a violation message, or `undefined` to pass. */
+    custom?: (content: string, ctx: HookContext) => string | undefined;
+    /**
+     * `deny` (default) hands the reason back so the loop can try again.
+     * `truncate` applies to `maxChars` only; anything else still denies.
+     */
+    action?: "deny" | "truncate";
+    name?: string;
+    priority?: number;
+};
+declare function outputGuard(config?: OutputGuardConfig): AgentPlugin;
+
+/**
+ * One structured record per run, shaped for a metrics pipeline.
+ *
+ * Only the things that have no ledger — how many model calls and tool calls
+ * this leg actually made — are tallied in the plugin's own store. Every number
+ * a billing or reliability dashboard will later be reconciled against is read
+ * back off the state instead: `state.usage` is the single billing ledger and
+ * `state.toolHistory` is the single record of what each call did. Both are part
+ * of the snapshot, so they survive a pause/resume; a plugin-kept token counter
+ * would restart at zero on resume and under-report the run's real bill.
+ *
+ * The counting hooks are gates, and a deny ends the chain. Sitting at priority
+ * 1 — immediately after `auditLog` (0) and ahead of every policy plugin — is
+ * what keeps a model turn that a guardrail later rejects inside the count: a
+ * metric that only sees the traffic nothing objected to describes a different
+ * agent than the one that ran.
+ */
+
+type SessionMetrics = {
+    runId: string;
+    agentName?: string;
+    status: "success" | "error" | "paused" | "cancelled";
+    durationMs: number;
+    modelCalls: number;
+    /** Every attempt, including the ones a policy refused. */
+    toolCalls: number;
+    failedToolCalls: number;
+    /** Denied by a hook or by a human at the approval gate. */
+    deniedToolCalls: number;
+    inputTokens: number;
+    outputTokens: number;
+    cachedInputTokens: number;
+    totalTokens: number;
+    /** Present only when a `costEstimator` was configured. */
+    estimatedCostUsd?: number;
+    /** Executions per tool name. Opt-in — a wide tool menu makes this unbounded. */
+    toolBreakdown?: Record<string, number>;
+};
+type SessionMetricsConfig = {
+    /** Where the record goes. Defaults to one JSON line on `console.log`. */
+    sink?: (metrics: SessionMetrics) => MaybePromise<void>;
+    /** Add per-tool execution counts. Off by default. */
+    includeToolBreakdown?: boolean;
+    /**
+     * Pricing for `estimatedCostUsd`. Deliberately NOT published as the
+     * `costEstimator` slot: a slot has exactly one owner, and a metrics plugin
+     * that claimed it would make itself un-installable next to `budgetGuard`.
+     */
+    costEstimator?: CostEstimator;
+    name?: string;
+};
+declare function sessionMetrics(config?: SessionMetricsConfig): AgentPlugin;
+
+/**
+ * Lifecycle wrapper for a Model Context Protocol server.
+ *
+ * An MCP server is not a list of tools, it is a SESSION: something has to open
+ * a transport, discover what the server offers, and close it again when the
+ * agent goes away. `tools:` can express only the middle third of that, which is
+ * why a caller wiring MCP by hand ends up leaking a child process or a socket
+ * per agent. A plugin owns `setup` and a disposer, so the session ends when the
+ * agent does.
+ *
+ * The connection itself stays the caller's dependency: `connect` is supplied by
+ * them, so `@langchain/mcp-adapters` or an official MCP client never becomes a
+ * dependency of this SDK, and any transport — stdio, SSE, streamable HTTP, an
+ * in-process fake — works the same way.
+ *
+ * Connecting happens in `setup` rather than inside the `tools` contribution
+ * because that is the only place the host applies `failureMode`. A fail-closed
+ * plugin whose server is unreachable must stop the agent from being built: the
+ * alternative is an agent that starts happily with none of the tools its
+ * instructions tell it to use, and then improvises.
+ */
+
+type McpConnection = {
+    /** The tools the server advertised. */
+    tools: ToolInterface[];
+    /** Shut the session down. Called once, when the last agent using it disposes. */
+    close?: () => Promise<void> | void;
+};
+type McpConfig = {
+    /** Opens the session. Owns the client library, the transport and the auth. */
+    connect: () => Promise<McpConnection>;
+    /**
+     * Renames discovered tools to `${prefix}__${name}`. Two servers routinely
+     * both export a `search`, and the SDK merges tools by name — without a prefix
+     * one silently shadows the other.
+     */
+    prefix?: string;
+    name?: string;
+    /** Default `"open"`: an unreachable server degrades the agent, it is not a breach. */
+    failureMode?: PluginFailureMode;
+    /** Cap on `connect`. Default 30s. */
+    timeoutMs?: number;
+};
+declare function mcp(config: McpConfig): AgentPlugin;
+
+/**
+ * Token-bucket throttle for model and tool calls.
+ *
+ * The thing this protects against is not a hostile user, it is one agent: a
+ * retry loop or a fan-out of sub-agents can put a month of traffic through a
+ * shared upstream in a minute, and the upstream's own 429 arrives too late to
+ * be cheap. So the ceiling is enforced here, where a refusal is still just a
+ * tool result the model can read.
+ *
+ * Buckets live in this closure — one set per `rateLimit()` call, i.e. per agent
+ * — and are keyed by `config.key?.(ctx) ?? "default"`. They deliberately do NOT
+ * live in `ctx.store`: that store is per RUN, so a bucket kept there would be
+ * full again on every `invoke()` and would limit nothing across runs, which is
+ * exactly the traffic pattern worth limiting. Keying also matters: without a
+ * `key`, two tenants sharing one agent instance share one budget, and the noisy
+ * one starves the quiet one.
+ */
+
+type RateLimitConfig = {
+    /** Model calls allowed per minute, across the whole agent. */
+    modelCallsPerMinute?: number;
+    /** Tool executions allowed per minute, summed over every tool. */
+    toolCallsPerMinute?: number;
+    /** Extra per-tool ceilings, checked on top of `toolCallsPerMinute`. */
+    perToolPerMinute?: Record<string, number>;
+    /**
+     * Bucket identity — a tenant, an end user, an api key. Everything the same
+     * key returns shares one budget; a missing key puts every caller in one.
+     */
+    key?: (ctx: HookContext) => string;
+    /**
+     * `deny` refuses immediately and lets the model decide what to do; `wait`
+     * blocks the call until a token frees, which smooths a burst instead of
+     * surfacing it. Default `deny`.
+     */
+    onExceeded?: "deny" | "wait";
+    /** Upper bound on a `wait`, after which the call is denied anyway. Default 5000. */
+    maxWaitMs?: number;
+    name?: string;
+    priority?: number;
+};
+declare function rateLimit(config?: RateLimitConfig): AgentPlugin;
+
+/**
+ * Exact-match cache for model responses.
+ *
+ * Agent loops replay the same prefix constantly — a retried tool, a re-planned
+ * step, a fan-out of sub-agents that all start from the same system prompt and
+ * the same question. When the wire messages and the tool menu are byte-identical
+ * the provider's answer is the only thing that is not free, so it is served
+ * from memory and the call never leaves the process. Nothing is inferred:
+ * "similar" is not a hit, only "identical" is.
+ */
+
+type ResponseCacheConfig = {
+    /** How long an entry stays servable. Default 5 minutes. */
+    ttlMs?: number;
+    /** Entry ceiling; the least recently used entry is dropped past it. Default 100. */
+    maxEntries?: number;
+    /**
+     * Replace the default key. Returning `undefined` means "do not cache this
+     * call" — the honest way to exclude anything non-deterministic (a prompt
+     * carrying `now()`, a per-user tool result) without turning the plugin off.
+     */
+    keyOf?: (input: HookMap["preModelCall"]["input"]) => string | undefined;
+    /**
+     * `run` gives every `invoke()` a fresh cache (safe by default: nothing
+     * outlives the conversation it came from); `agent` shares one cache across
+     * every run on this agent instance, which is where the real savings are and
+     * also where a stale or cross-tenant answer becomes possible. Default `run`.
+     */
+    scope?: "run" | "agent";
+    name?: string;
+    priority?: number;
+};
+declare function responseCache(config?: ResponseCacheConfig): AgentPlugin;
+
+type SigV4Credentials = {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+};
+
+/**
+ * Guardrail presets — four more services on the seam in `guardrail.ts`.
+ *
+ * Each one is the same three decisions `cognipeerGuardrail` makes and nothing
+ * more: where to POST, how to authenticate, and how that service's response
+ * becomes a `GuardrailVerdict`. None of them re-implements the plugin — the
+ * caching, shadow mode, phase skipping and fail-closed behaviour all stay in
+ * `createGuardrailPlugin`, so a fix there reaches every preset at once.
+ *
+ * How much a preset is allowed to assume differs per service, and that
+ * difference is stated per function rather than hidden:
+ *
+ *   openAIModeration     the wire contract is public, stable and versioned, so
+ *                        the mapper reads its fields directly and is strict
+ *                        about a shape it does not recognise.
+ *   azureContentSafety   path and body are what the docs look like, but they
+ *                        are NOT verified here — they live behind
+ *                        `buildRequest` / `mapVerdict` overrides, and the
+ *                        default mapper falls back to the forgiving
+ *                        `normalizeVerdicts` when it sees an unfamiliar body.
+ *   bedrockGuardrail     same caveat, plus SigV4 signing reused from
+ *                        `src/providers/utils/sigv4.ts`.
+ *   regexGuardrail       no wire contract at all: in-process patterns, so a
+ *                        team can adopt the guardrail plugin shape before it
+ *                        has a service to point at.
+ *
+ * Priorities sit in the 20-25 guardrail band already used by `cognipeer` (20)
+ * and `portkey` (25), ordered cheapest-first on purpose. R3 makes the first
+ * deny terminal for the chain, so putting the local matcher ahead of the
+ * network ones (and the free moderation call ahead of the billed ones) means
+ * the most expensive check is the one most likely never to be made — and a
+ * locally-detectable violation is never shipped to a third party at all.
+ */
+
+type OpenAIModerationConfig = {
+    /** Defaults to `OPENAI_API_KEY`. */
+    apiKey?: string;
+    /** Moderation model. Default `omni-moderation-latest`. */
+    model?: string;
+    /** Origin only — the `/v1/moderations` path is appended. Defaults to `OPENAI_BASE_URL`, then the public API. */
+    baseUrl?: string;
+    /**
+     * What a flagged result becomes. `block` (default) refuses the turn; `mask`
+     * substitutes `maskWith`, which is how a team replaces a violating answer
+     * with a fixed refusal instead of failing the run.
+     */
+    action?: "block" | "mask";
+    /** Replacement used when `action` is `mask`. */
+    maskWith?: string;
+    /** Surfaces to guard. Default: input + output. */
+    apply?: GuardrailPhaseName[];
+    /** `shadow` reports what would have been blocked without blocking. */
+    mode?: "enforce" | "shadow";
+    /** Default true — a moderation outage blocks rather than silently stops moderating. */
+    failClosed?: boolean;
+    /** Per-check ceiling. Default 3000ms. */
+    timeoutMs?: number;
+    /** Retries after the first attempt. Default 1. */
+    retries?: number;
+    priority?: number;
+    /** Memoize verdicts per run. Default true. */
+    cache?: boolean | {
+        maxEntries?: number;
+    };
+    metadata?: Record<string, unknown>;
+    name?: string;
+};
+/**
+ * OpenAI's moderation endpoint. Free, fast and text-only, which is why it sits
+ * at the cheap end of the guardrail band.
+ */
+declare function openAIModeration(config?: OpenAIModerationConfig): AgentPlugin;
+type AzureContentSafetyConfig = {
+    /** Resource endpoint, e.g. `https://my-resource.cognitiveservices.azure.com`. Defaults to `AZURE_CONTENT_SAFETY_ENDPOINT`. */
+    endpoint?: string;
+    /** Defaults to `AZURE_CONTENT_SAFETY_KEY`. */
+    apiKey?: string;
+    /** Block when a requested category reaches this severity. Default 4. */
+    severityThreshold?: number;
+    /** Categories to analyse. Default: Hate, SelfHarm, Sexual, Violence. */
+    categories?: string[];
+    /** `api-version` query parameter. */
+    apiVersion?: string;
+    /** Override the analyze path (rarely needed). */
+    path?: string;
+    apply?: GuardrailPhaseName[];
+    mode?: "enforce" | "shadow";
+    failClosed?: boolean;
+    timeoutMs?: number;
+    retries?: number;
+    priority?: number;
+    cache?: boolean | {
+        maxEntries?: number;
+    };
+    metadata?: Record<string, unknown>;
+    /** Escape hatch: build the wire request yourself. */
+    buildRequest?: (requests: GuardrailRequest[], ctx: GuardrailCallContext) => unknown;
+    /** Escape hatch: map the response to verdicts, in request order. */
+    mapVerdict?: (response: unknown, requests: GuardrailRequest[]) => GuardrailVerdict[];
+    name?: string;
+};
+/**
+ * Azure AI Content Safety. The path, body and response field names default to
+ * what the public documentation describes, but they are UNVERIFIED here: both
+ * ends of the contract are overridable (`buildRequest` / `mapVerdict`) exactly
+ * so a shape change is a one-line configuration fix rather than a fork.
+ */
+declare function azureContentSafety(config?: AzureContentSafetyConfig): AgentPlugin;
+type BedrockGuardrailConfig = {
+    /** Guardrail id from Bedrock. */
+    guardrailIdentifier: string;
+    /** Guardrail version, e.g. `"1"` or `"DRAFT"`. */
+    guardrailVersion: string;
+    /** Defaults to `AWS_REGION`, then `AWS_DEFAULT_REGION`, then `us-east-1`. */
+    region?: string;
+    /** Defaults to the standard `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_SESSION_TOKEN` variables. */
+    credentials?: SigV4Credentials;
+    /** Override the runtime host (VPC endpoint, a local mock). */
+    baseUrl?: string;
+    apply?: GuardrailPhaseName[];
+    mode?: "enforce" | "shadow";
+    failClosed?: boolean;
+    timeoutMs?: number;
+    /** Retries after the first attempt. Default 1; each attempt is signed afresh. */
+    retries?: number;
+    priority?: number;
+    cache?: boolean | {
+        maxEntries?: number;
+    };
+    metadata?: Record<string, unknown>;
+    /** Escape hatch: build the wire request yourself. */
+    buildRequest?: (request: GuardrailRequest, ctx: GuardrailCallContext) => unknown;
+    /** Escape hatch: map the response to a verdict. */
+    mapVerdict?: (response: unknown, request: GuardrailRequest) => GuardrailVerdict;
+    name?: string;
+};
+/**
+ * AWS Bedrock ApplyGuardrail. Signing is reused from the provider layer
+ * (`src/providers/utils/sigv4.ts`) rather than reimplemented — one signer, one
+ * place for a signing bug to be fixed.
+ */
+declare function bedrockGuardrail(config: BedrockGuardrailConfig): AgentPlugin;
+type RegexGuardrailConfig = {
+    /** Any match denies the turn. */
+    block?: RegExp[];
+    /** Applied in order; a changed text becomes a `mask` verdict. */
+    mask?: Array<{
+        pattern: RegExp;
+        replacement: string;
+    }>;
+    apply?: GuardrailPhaseName[];
+    mode?: "enforce" | "shadow";
+    failClosed?: boolean;
+    priority?: number;
+    cache?: boolean | {
+        maxEntries?: number;
+    };
+    metadata?: Record<string, unknown>;
+    name?: string;
+};
+/**
+ * A guardrail with no service behind it. The point is adoption order: a team
+ * can put the plugin, its phases, its shadow mode and its incident events in
+ * place today with a list of patterns, then swap the transport for a real
+ * service later without touching anything else in the agent.
+ */
+declare function regexGuardrail(config?: RegexGuardrailConfig): AgentPlugin;
+
+/**
+ * What a user is allowed to attach.
+ *
+ * A multimodal turn is an untrusted upload path with a per-token price tag: a
+ * single high-resolution image can cost more than the conversation around it,
+ * a video the provider does not support fails deep inside the request, and a
+ * `http://` URL is a server-side fetch of whatever the sender wants. None of
+ * that is visible to a text guardrail, which sees only the caption.
+ *
+ * Structural checks only — kind, count, size, media type, source. Deciding
+ * whether a picture is acceptable is a content question and belongs to a
+ * moderation service; this decides whether it should be there at all.
+ */
+
+type MediaKind = "image" | "audio" | "video" | "file" | "unknown";
+type MediaPolicyConfig = {
+    /** Kinds that may be attached. Default: every kind. */
+    allow?: MediaKind[];
+    /** Kinds that may never be attached. Checked after `allow`. */
+    deny?: MediaKind[];
+    /** Cap on attachments in one turn. */
+    maxAttachments?: number;
+    /** Cap on a single attachment, in bytes. Only measurable for inline data. */
+    maxBytesPerAttachment?: number;
+    /** Cap on the total inline bytes in one turn. */
+    maxTotalBytes?: number;
+    /** Exact media types, or a prefix ending in `/` (e.g. `"image/"`). */
+    allowedMediaTypes?: string[];
+    /** Reject `http://` sources. Default true — the provider fetches these server-side. */
+    requireHttps?: boolean;
+    /**
+     * `deny` refuses the turn and tells the user why; `strip` drops the offending
+     * parts and lets the run continue on what is left. Default `deny`, because
+     * silently answering about a picture the model never received is worse than
+     * saying no.
+     */
+    action?: "deny" | "strip";
+    name?: string;
+    priority?: number;
+};
+declare function mediaPolicy(config?: MediaPolicyConfig): AgentPlugin;
+
+/**
+ * Langfuse export, driven by hooks instead of by a tracing sink.
+ *
+ * The SDK already has a tracing runtime (`tracing: { enabled: true }` plus a
+ * sink — file / http / otlp / cognipeer / custom) and that remains the richer
+ * path: it carries prompts, tool payloads, response formats and the full span
+ * tree. This plugin exists for two reasons the sink cannot serve.
+ *
+ *   1. Packaging. A product that already ships its guardrails as plugins can
+ *      hand its users one array — `plugins: [cognipeerGuardrail(), langfuseTracing()]`
+ *      — instead of a plugin array plus a separate `tracing` block.
+ *   2. Reach. A sink only ever sees what the SDK core records. A plugin sits on
+ *      the hook chain, so it also sees things that never become trace events:
+ *      a tool call another plugin denied at `preToolUse` (recorded here as a
+ *      span that opens and never closes cleanly), a model turn a guardrail
+ *      rejected, a short-circuited call that never reached a provider.
+ *
+ * Content is deliberately NOT exported. Prompts, tool arguments and tool
+ * results stay inside the process: shipping them to a third party by default
+ * would be a surprise, and the SDK's own tracing runtime already has `logData`
+ * for anyone who wants it. What goes out is shape and cost — model, latency,
+ * token usage, tool names, outcomes. `buildPayload` is the seam for a caller
+ * who wants more.
+ *
+ * WIRE CONTRACT — UNVERIFIED. The endpoint and auth scheme below
+ * (`POST {baseUrl}/api/public/ingestion`, HTTP Basic `publicKey:secretKey`, a
+ * `{ batch: [...] }` body of typed events) are what this module assumes, and
+ * the per-event body shapes in `defaultBuildPayload` are an assumption on top
+ * of that assumption — they were NOT verified against Langfuse documentation
+ * while writing this. Everything about the body is therefore behind the
+ * overridable `buildPayload(events, ctx)`: if Langfuse's schema differs, pass
+ * your own and nothing else in this file has to move.
+ */
+
+/**
+ * A neutral, in-house description of one thing worth reporting. Hooks produce
+ * these; only `buildPayload` knows what Langfuse calls them. Keeping the two
+ * apart is what makes the unverified schema a single-function problem.
+ */
+type LangfuseEventKind = "trace-start" | "trace-end" | "generation" | "span-start" | "span-end";
+type LangfuseEvent = {
+    /** Idempotency id for this ingestion envelope — unique per event, never reused. */
+    id: string;
+    kind: LangfuseEventKind;
+    /** ISO time the event was produced (not the time the work happened). */
+    timestamp: string;
+    /** The run's Langfuse trace id. Every event of one run shares it. */
+    traceId: string;
+    /** Observation id — set for generations and spans, absent for the trace itself. */
+    observationId?: string;
+    name: string;
+    startTime?: string;
+    endTime?: string;
+    model?: string;
+    /** Token counts, already normalized across provider spellings. */
+    usage?: {
+        input?: number;
+        output?: number;
+        total?: number;
+    };
+    /** Structured outcome. Never message content — see the module header. */
+    output?: unknown;
+    level?: "DEFAULT" | "WARNING" | "ERROR";
+    statusMessage?: string;
+    metadata?: Record<string, unknown>;
+};
+/** The static, per-plugin half of a payload; the varying half is the events. */
+type LangfuseBuildContext = {
+    baseUrl: string;
+    publicKey: string;
+    release?: string;
+    userId?: string;
+    sessionId?: string;
+    tags?: string[];
+};
+type LangfuseTracingConfig = {
+    /** Defaults to `LANGFUSE_PUBLIC_KEY`. */
+    publicKey?: string;
+    /** Defaults to `LANGFUSE_SECRET_KEY`. */
+    secretKey?: string;
+    /** Defaults to `LANGFUSE_BASE_URL`, then Langfuse Cloud. Point at a self-hosted instance here. */
+    baseUrl?: string;
+    /** Build/version tag attached to the trace. */
+    release?: string;
+    /** End-user attribution for the trace. */
+    userId?: string;
+    /** Groups several runs into one Langfuse session (a chat thread, typically). */
+    sessionId?: string;
+    tags?: string[];
+    /** Flush once this many events are buffered. Default 20. */
+    flushAt?: number;
+    /** Flush a partially-filled buffer after this long. Default 5000ms. 0 disables the timer. */
+    flushIntervalMs?: number;
+    /** Escape hatch for the whole wire body — see the UNVERIFIED note in the module header. */
+    buildPayload?: (events: LangfuseEvent[], ctx: LangfuseBuildContext) => unknown;
+    /** Plugin name, when exporting to more than one Langfuse project at once. */
+    name?: string;
+};
+/** The assumed `{ batch: [...] }` ingestion body. Replaceable via `buildPayload`. */
+declare function defaultBuildPayload(events: LangfuseEvent[], ctx: LangfuseBuildContext): unknown;
+declare function langfuseTracing(config?: LangfuseTracingConfig): AgentPlugin;
+
+/**
+ * OTLP/HTTP export of a finished run, driven by a hook instead of by a sink.
+ *
+ * The SDK already ships `otlpSink(endpoint, headers)`, and when observability
+ * is configured on its own that remains the right tool — it is wired straight
+ * into `finalizeTraceSession` and needs no plugin at all. This plugin exists
+ * for the product that wants one array: `plugins: [cognipeerGuardrail(),
+ * otelTracing({ endpoint })]`, with tracing and policy declared side by side
+ * rather than in two unrelated config blocks.
+ *
+ * It does NOT re-implement the sink. The conversion is `traceSessionToOtlp`,
+ * the same function `otlpSink` uses, applied to the same session object — so a
+ * span tree exported through this plugin and one exported through the sink are
+ * the same spans. What the plugin adds is placement: it runs on the hook chain,
+ * next to the guardrails, and can therefore be turned on and off with them.
+ *
+ * Because it reads the SDK's trace session, it needs `tracing: { enabled: true }`
+ * on the agent. Without it there is no session to export and the plugin says so
+ * out loud (a `metadata` event plus a warning) rather than doing nothing: a
+ * silent no-op in an observability tool is the failure that costs the most,
+ * because it is discovered days later when someone goes looking for the traces.
+ */
+
+type OtelTracingConfig = {
+    /** OTLP/HTTP JSON traces endpoint, e.g. `https://collector.example.com/v1/traces`. */
+    endpoint: string;
+    /** Auth and tenancy headers for the collector. */
+    headers?: Record<string, string>;
+    /** `service.name` on the exported resource. Defaults to the agent's name. */
+    serviceName?: string;
+    /** Plugin name, when exporting to more than one collector at once. */
+    name?: string;
+};
+declare function otelTracing(config: OtelTracingConfig): AgentPlugin;
+
+/**
+ * Webhook-backed human-in-the-loop transport for the `approvalTransport` slot.
+ *
+ * ── Runtime status (read this before wiring it into a product) ───────────────
+ * The `approvalTransport` slot is DECLARED (`PluginProvides`) and RESOLVED (the
+ * host validates single ownership and exposes it on `host.slots`), but as of
+ * this file's writing NOTHING IN THE RUNTIME CALLS IT: `grep -rn
+ * approvalTransport src` finds only the type, the slot list and the docs table,
+ * and the tools node still pauses the run and waits for `resolveToolApproval`.
+ * Nothing reads `host.slots` at all yet, so this is the state of every slot
+ * rather than a gap peculiar to this one.
+ * Installing this plugin today changes no behaviour. It ships now because
+ * the contract — `request()` returning a resolution, or `null` to leave the run
+ * paused — is already fixed, and the tests below pin it so the day the tools
+ * node consumes the slot the transport is already proven against it.
+ *
+ * ── Wire contract ───────────────────────────────────────────────────────────
+ * The default request body and the default response parsing are THIS SDK's own
+ * convention, not a schema published by any approval product. Nothing here was
+ * verified against Slack, Teams, Jira, ServiceNow, PagerDuty or any other
+ * system, and no such schema is invented and presented as fact. Point `url` at
+ * an endpoint you control, or override `buildRequest` / `parseDecision` — the
+ * same two-function escape hatch `cognipeerGuardrail` uses for exactly this
+ * reason.
+ *
+ * ── Safety posture ──────────────────────────────────────────────────────────
+ * "I could not get an answer" is `null`, which leaves the approval pending so
+ * the host resolves it the ordinary way. That is the default on timeout and on
+ * a delivery failure: an unreachable webhook must never silently become a "yes",
+ * and it must not become an automatic "no" either, because a rejected tool call
+ * is a wrong answer handed to the model. `onTimeout: "reject"` opts into the
+ * strict reading for deployments that would rather fail the call than leave a
+ * run parked.
+ */
+
+type WebhookApprovalConfig = {
+    /** Where the pending approval is POSTed so a human can see it. */
+    url: string;
+    /** Static headers, or a thunk so a rotating token is read per call. */
+    headers?: Record<string, string> | (() => Record<string, string>);
+    /**
+     * Status endpoint polled until a decision appears. A function receives the
+     * pending approval, so a per-approval URL can be built. When omitted, the
+     * POST response itself must carry the decision (or a `pollUrl`/`statusUrl`
+     * field, which is the default convention this transport understands).
+     */
+    pollUrl?: string | ((pending: PendingToolApproval, ctx: HookContext) => string | undefined);
+    /** Gap between status checks. Default 2000ms. */
+    pollIntervalMs?: number;
+    /** Total budget for one approval, POST included. Default 300_000ms (5 min). */
+    timeoutMs?: number;
+    /** Override the POST body. Default: `{ type, runId, agentName, depth, approval }`. */
+    buildRequest?: (pending: PendingToolApproval, ctx: HookContext) => unknown;
+    /**
+     * Map a webhook or poll response to a resolution. Returning `null`/`undefined`
+     * means "no decision yet" and keeps polling — it is not an error.
+     */
+    parseDecision?: (response: unknown, pending: PendingToolApproval) => ToolApprovalResolution | null | undefined;
+    /**
+     * What an expired budget means. Default `leave-pending` (return `null`, run
+     * stays paused). `reject` resolves the approval as refused instead.
+     */
+    onTimeout?: "reject" | "leave-pending";
+    name?: string;
+};
+/**
+ * Forgiving on purpose, in the same spirit as `normalizeVerdicts`: the shape of
+ * whatever ticketing system sits behind the webhook can change without an SDK
+ * release, and a strict parser would turn a field rename into every approval
+ * timing out.
+ */
+declare function parseApprovalDecision(response: unknown, pending: PendingToolApproval): ToolApprovalResolution | null;
+declare function webhookApproval(config: WebhookApprovalConfig): AgentPlugin;
+
+/**
+ * Keeps the assistant answering in the language it is supposed to answer in.
+ *
+ * The failure this fixes is mundane and constant: a Turkish user asks a
+ * question, a tool returns an English document, and the model drifts into the
+ * language of its context instead of the language of its reader.
+ *
+ * Two hooks, because the problem has two halves:
+ *   - `preModelCall` adds a system-level instruction naming the required
+ *     language to every call. This is the half that actually fixes drift —
+ *     prevention, on the request, where the model can still act on it.
+ *   - `preFinalAnswer` measures the answer and, under `action: "deny"`, refuses
+ *     it with a reason naming both the detected and the required language, so
+ *     the loop gets a specific, actionable correction instead of a retry.
+ *
+ * `deny` is a BACKSTOP FOR DRIFT, not a gate you can demonstrate on demand.
+ * The instruction the first hook adds is the last message on the wire, so it
+ * outranks a user asking for another language: measured against a real model,
+ * five of five attempts to force a mismatch came back in the required language
+ * and the refusal never fired. That is the design working — prevention is the
+ * fix, enforcement is the safety net for the long tail where it slips. Enable
+ * `deny` for that tail, not for a guarantee, and pin `detect` if you need a
+ * deterministic test.
+ *
+ * Note what is deliberately NOT done. `preFinalAnswer` does not rewrite the
+ * answer: translating locally would return text the model never wrote and
+ * nobody reviewed (the same reasoning `outputGuard` gives for only repairing
+ * `maxChars`). And a mismatch is not surfaced at `userPromptSubmit` either —
+ * the user's language is not the thing being constrained.
+ *
+ * ── The detector is a heuristic ─────────────────────────────────────────────
+ * `detectLanguage` is stopwords plus script and diacritic evidence. It is fast,
+ * dependency-free and offline, and it is wrong on short text: "Ok" and "Merci"
+ * carry no signal, and a two-sentence answer full of code and proper nouns
+ * carries very little. `minChars` (default 40, measured after code fences,
+ * inline code, URLs and e-mail addresses are removed) is the guard against
+ * judging text that cannot be judged, and an undetectable answer is always
+ * allowed. Pass `detect` to swap in a real classifier when the cost is worth it.
+ */
+
+type LanguageGuardConfig = {
+    /**
+     * BCP-47-ish tag the answer must be in ("tr", "en-GB"). Only the base subtag
+     * is compared. The function form reads it per run — typically off
+     * `state.metadata` for a per-user locale.
+     */
+    language: string | ((ctx: HookContext) => string | undefined);
+    /**
+     * `instruct` (default) only steers the request. `deny` additionally refuses a
+     * final answer in the wrong language, costing an extra model turn.
+     */
+    action?: "deny" | "instruct";
+    /** Replace the built-in heuristic. Receives the answer with code/URLs stripped. */
+    detect?: (text: string) => string | undefined;
+    /** Below this many characters of prose the answer is never judged. Default 40. */
+    minChars?: number;
+    name?: string;
+    priority?: number;
+};
+/**
+ * Best-effort language of a piece of text: a script check first (a non-Latin
+ * script settles it outright), then stopword and diacritic scoring across the
+ * Latin profiles. Returns `undefined` when the evidence is thin or two
+ * languages score within a point of each other — saying "I don't know" is the
+ * only honest answer a heuristic this small can give, and every caller here
+ * treats it as "allow".
+ */
+declare function detectLanguage(text: string): string | undefined;
+declare function languageGuard(config: LanguageGuardConfig): AgentPlugin;
+
+/**
+ * Centralized manager for structured output across both base Agent and SmartAgent.
+ *
+ * Responsibilities:
+ * - Prepare tools or response_format depending on the resolved strategy
+ * - Build system prompt hints tailored to the strategy
+ * - Build nudge/correction prompts for retries
+ * - Parse final output from tool result or assistant content
+ * - Report structured errors (never silently swallow)
+ */
+declare class StructuredOutputManager<T> {
+    readonly strategy: StructuredOutputStrategy;
+    readonly schema: ZodSchema<T>;
+    readonly maxRetries: number;
+    constructor(schema: ZodSchema<T>, strategy: StructuredOutputStrategy, config?: StructuredOutputManagerConfig);
+    /**
+     * Get the `response` tool for tool-based strategy.
+     * Returns undefined for native strategy (no tool needed).
+     */
+    getResponseTool(): ToolInterface | undefined;
+    /**
+     * Get response_format config for native strategy.
+     * Returns undefined for tool-based strategy.
+     */
+    getResponseFormat(): Record<string, any> | undefined;
+    /**
+     * Build the system prompt hint that tells the model how to produce structured output.
+     */
+    buildSystemPromptHint(): string;
+    /**
+     * Build a nudge message for when the model didn't produce structured output.
+     * Used by the agent loop when it needs to retry.
+     * User role is intentional: OpenAI-compatible chat templates such as Qwen
+     * reject system messages anywhere except the beginning of the conversation.
+     */
+    buildNudgeMessage(isLastAttempt: boolean): {
+        role: string;
+        content: string;
+    };
+    /**
+     * Build a correction message when schema validation failed.
+     */
+    buildCorrectionMessage(error: StructuredOutputError, _previousAttempt?: unknown): {
+        role: string;
+        content: string;
+    };
+    /**
+     * Try to parse structured output from the tool-based finalization result.
+     * Called when __structuredOutputParsed is available in ctx.
+     */
+    parseFromToolResult(data: unknown): StructuredOutputResult<T>;
+    /**
+     * Try to parse structured output from assistant message content.
+     * For native strategy: content should be valid JSON.
+     * For tool-based strategy: last-resort fallback extraction from text.
+     */
+    parseFromContent(content: string): StructuredOutputResult<T>;
+    /**
+     * Create a "no output" error result.
+     */
+    noOutputResult(attempts: number, rawContent?: string): StructuredOutputResult<T>;
+    /**
+     * Create a "max retries" error result.
+     */
+    maxRetriesResult(lastError: StructuredOutputError, attempts: number, rawContent?: string): StructuredOutputResult<T>;
+}
+
+/**
+ * Tool-based structured output strategy.
+ *
+ * Injects a hidden `response` tool that the model must call with the final JSON.
+ * This is the universal fallback that works with all providers.
+ */
+declare class ToolBasedStrategy implements StructuredOutputStrategy {
+    readonly kind: "tool_based";
+    /**
+     * Create the `response` tool for a given Zod schema.
+     * The tool validates input against the schema and returns a sentinel object
+     * that the tools node picks up to finalize the structured output.
+     */
+    createResponseTool<T>(schema: ZodSchema<T>): ToolInterface;
+    /**
+     * Try to extract structured output from raw assistant text content.
+     * Used as a last resort when the model writes JSON directly instead of calling the tool.
+     */
+    extractFromText<T>(content: string, schema: ZodSchema<T>): {
+        data: T;
+    } | {
+        error: StructuredOutputError;
+    };
+    buildCorrectionPrompt(error: ZodError<any>, previousAttempt: unknown): string;
+}
+
+/**
+ * Native JSON Schema strategy for providers that support `response_format`.
+ *
+ * Works with OpenAI (gpt-4o+), Google Gemini, and similar providers
+ * that accept `response_format: { type: "json_schema", json_schema: {...} }`.
+ *
+ * The model guarantees valid JSON output matching the schema — no tool needed.
+ */
+declare class NativeJsonSchemaStrategy implements StructuredOutputStrategy {
+    readonly kind: "native";
+    private resolveJsonPointer;
+    private unwrapRootObjectSchema;
+    /**
+     * Convert a Zod schema to the JSON Schema object used in response_format.
+     */
+    toJsonSchema(schema: ZodSchema<any>, name?: string): Record<string, any>;
+    /**
+     * Build response_format configuration for the model call.
+     * Returns the object that should be spread into model invocation options.
+     */
+    buildResponseFormat(schema: ZodSchema<any>, name?: string): Record<string, any>;
+    /**
+     * Parse and validate model response content.
+     * With native support, content is guaranteed JSON — but we still validate with Zod
+     * for type safety and field-level error reporting.
+     */
+    extractOutput<T>(content: string, schema: ZodSchema<T>): {
+        data: T;
+    } | {
+        error: StructuredOutputError;
+    };
+    buildCorrectionPrompt(error: ZodError<any>, previousAttempt: unknown): string;
+}
+
+/**
+ * Resolve the most appropriate structured output strategy for a given model.
+ *
+ * If the model exposes capabilities (via adapter or direct provider),
+ * we use native JSON Schema support when available. Otherwise we fall back
+ * to the universal tool-based approach.
+ *
+ * When direct providers are added to the SDK, they should set
+ * `model.capabilities.structuredOutput = "native"` for providers that support
+ * response_format (OpenAI, Gemini, etc.).
+ */
+declare function resolveStrategy(model: any): StructuredOutputStrategy;
+/**
+ * Extract capabilities from a model object.
+ * Supports:
+ *   - model.capabilities (set by adapters or direct providers)
+ *   - Auto-detection from model class name / metadata
+ */
+declare function getModelCapabilities(model: any): ModelCapabilities;
+
+declare function captureSnapshot(state: SmartState, options?: SnapshotOptions): AgentSnapshot;
+declare function restoreSnapshot(snapshot: AgentSnapshot, restoreOptions?: RestoreSnapshotOptions): SmartState;
+
+declare function resolveToolApprovalState(state: SmartState, resolution: ToolApprovalResolution): SmartState;
+
+declare function resolveUserQuestionState(state: SmartState, resolution: UserQuestionResolution): SmartState;
+
+/**
+ * The built-in ask-user tool's name. Exported because more than one layer has to
+ * recognise it: `createSmartAgent` builds the tool into the list it hands to
+ * `createAgent`, which must then not attach a second one of its own.
+ */
+declare const ASK_USER_TOOL_NAME = "ask_user_question";
+type AskUserStateRef = {
+    pendingUserQuestions?: PendingUserQuestion[];
+    ctx?: Record<string, any>;
+    __onEvent?: (event: any) => void;
+    __currentToolCallId?: string;
+};
+declare function createAskUserQuestionTool(stateRef: AskUserStateRef, config: HumanInTheLoopAskUserConfig): ToolInterface<any, any, any>;
+
+declare function fromLangchainTools<T extends ToolInterface = ToolInterface>(tools: any[]): T[];
+
+type ResolvedReflectionConfig = {
+    enabled: boolean;
+    cadence: ReflectionCadence;
+    mode: "piggyback" | "separate";
+    maxTokens: number;
+    maxChars: number;
+    keepLast: number;
+    summarize: boolean;
+    promptTemplate?: string;
+    emitEvents: boolean;
+    maxPerRun?: number;
+    everyNTurns: number;
+    feedTo: "memory" | "plan" | "none";
+    shouldReflect?: (ctx: ReflectionHookContext) => boolean;
+    buildPrompt?: (ctx: ReflectionHookContext & {
+        defaultPrompt: string;
+        maxChars: number;
+    }) => string;
+    onReflection?: (record: ReflectionRecord, ctx: ReflectionHookContext) => void;
+};
+type ResolvedReasoning = {
+    enabled: boolean;
+    level: ReasoningLevel;
+    native?: NativeReasoningConfig;
+    reflection: ResolvedReflectionConfig;
+};
+/**
+ * Validates a user-supplied ReasoningConfig and throws a descriptive error for
+ * obviously-wrong values. Pure; safe to call before resolveReasoning.
+ */
+declare function validateReasoningConfig(input: ReasoningConfig | undefined): void;
+declare function resolveReasoning(input: ReasoningConfig | undefined): ResolvedReasoning | undefined;
+
+/**
+ * Tools the agent loop uses to steer ITSELF. Their arguments are never digested —
+ * digesting them is never a win (the arguments are small) and always a risk:
+ *  - `response` carries the run's final structured output,
+ *  - `manage_plan` (and its deprecated alias `manage_todo_list` — same handler,
+ *    same shared state, see contextTools.ts) carries the living plan,
+ *  - `ask_user_question` carries the question the user's answer replies to,
+ *  - `open_skill` / `bind_skill_tools` / `search_skills` name the capability being
+ *    loaded, which the rest of the run reasons about,
+ *  - `get_tool_response` is the recovery path itself.
+ * They also default to `keep_full` on the output axis (overridable per tool).
+ */
+declare const CONTROL_PLANE_TOOL_NAMES: readonly string[];
+/**
+ * Delegation tools: the arguments ARE the brief handed to the child agent — the
+ * parent must be able to say what it delegated. Never digested. The child's report
+ * (the output) may still be archived and paged back in.
+ */
+declare const DELEGATION_TOOL_NAMES: readonly string[];
+declare const DEFAULT_MAX_TOOL_INPUT_FIELD_CHARS = 2000;
+declare const DEFAULT_TOOL_INPUT_DIGEST_HEAD_CHARS = 200;
+/** Key marking a digested argument field. Recognized as a recovery reference. */
+declare const TOOL_INPUT_DIGEST_KEY = "__digest";
+/**
+ * Compact textual preview of a value for archive/structured retention. Used by
+ * the summarizer when an old tool response is reduced to a placeholder. Not
+ * used at tool execution time.
+ */
+declare function summarizeObject(value: any): string;
+/**
+ * Tool-definition-declared retention specs, keyed by tool name. Built from the
+ * runtime's live tool list so a skill-bound tool contributes its own declaration.
+ */
+type ToolRetentionDeclarations = Map<string, ToolRetentionSpec>;
+declare function collectToolRetentionDeclarations(tools: Array<ToolInterface<any, any, any>> | undefined): ToolRetentionDeclarations;
+/**
+ * Resolves the retention policy applied by the summarizer when context limits
+ * are reached. Critical tools are never reduced.
+ *
+ * Precedence (first match wins):
+ *  1. `criticalTools` — absolute, never reduced (documented contract).
+ *  2. `toolResponses.retentionByTool[name].output` — caller's two-axis override.
+ *  3. `toolResponses.toolResponseRetentionByTool[name]` — legacy single-axis map.
+ *  4. the tool definition's own `retention.output`.
+ *  5. built-in control-plane default (`keep_full`).
+ *  6. `toolResponses.defaultPolicy`.
+ */
+declare function resolveSummarizationRetention(toolName: string, config: ResolvedSmartAgentConfig, declarations?: ToolRetentionDeclarations): ToolResponseRetentionPolicy;
+/**
+ * Resolves the retention policy applied to a tool call's ARGUMENTS.
+ *
+ * Precedence (first match wins):
+ *  1. control-plane + delegation tools — always `keep` (hard invariant).
+ *  2. `criticalTools` — a tool whose response may never be reduced does not get
+ *     its request reduced either.
+ *  3. `toolResponses.retentionByTool[name].input`.
+ *  4. the tool definition's own `retention.input`.
+ *  5. `toolResponses.defaultInputPolicy` (defaults to `keep`).
+ *
+ * The default is `keep`, so argument digesting never happens unless a tool or a
+ * caller explicitly asks for it.
+ */
+declare function resolveInputRetention(toolName: string, config: ResolvedSmartAgentConfig, declarations?: ToolRetentionDeclarations): ToolInputRetentionPolicy;
+type ToolInputDigestOptions = {
+    /** Per-field character threshold. Strings at or below this are preserved verbatim. */
+    maxFieldChars?: number;
+    /** Leading characters of a digested field kept as a preview. */
+    headChars?: number;
+    /** Execution id embedded in each marker so the model can page the original back in. */
+    executionId?: string;
+};
+type ToolInputDigestResult = {
+    /** The rewritten value. Identical reference when nothing was digested. */
+    value: unknown;
+    /** Dotted paths of the fields that were replaced by a digest marker. */
+    digestedPaths: string[];
+    /** Characters reclaimed from the serialized arguments. */
+    reclaimedChars: number;
+};
+/**
+ * Field-level argument digest.
+ *
+ * Walks the argument structure and replaces ONLY string leaves longer than
+ * `maxFieldChars` with a compact descriptor. Every other field — paths, ids,
+ * modes, indexes, booleans, short strings — is preserved verbatim, so a call like
+ *
+ *   { filePath: "/reports/q3.md", mode: "append", section: 3, content: "<60k>" }
+ *
+ * compacts to
+ *
+ *   { filePath: "/reports/q3.md", mode: "append", section: 3,
+ *     content: { __digest: { chars: 61840, sha256: "…", head: "# Q3 …", recover: "…" } } }
+ *
+ * The model can still state exactly what it did; only the payload it no longer
+ * needs to re-read is gone. Idempotent: an existing digest marker is left alone.
+ */
+declare function digestToolInputValue(value: unknown, options?: ToolInputDigestOptions): ToolInputDigestResult;
+/**
+ * Digest a serialized `tool_call.function.arguments` JSON string in place.
+ * Returns the input string unchanged when nothing needed digesting, when the
+ * string is not parseable JSON (never guess at a non-JSON payload), or when the
+ * result would not actually be smaller.
+ */
+declare function digestToolInputArguments(argumentsJson: string, options?: ToolInputDigestOptions): {
+    arguments: string;
+    digestedPaths: string[];
+    reclaimedChars: number;
+};
+/**
+ * Parse tool arguments against the tool's schema.
+ *
+ * Two passes, and the order is the contract: the raw arguments are validated
+ * FIRST, so a model that emits well-typed arguments is unaffected and the schema
+ * stays a real constraint. Only when that fails are the arguments run through
+ * `coerceToolArgs` and re-validated — repairing the type artifacts smaller and
+ * grammar-constrained backends produce (a nested object sent as a JSON string, a
+ * number sent as `"60"`, `""` standing in for an omitted optional) instead of
+ * spending a turn telling the model something it did not get wrong.
+ *
+ * Coercion never fabricates a value, so a genuinely missing required argument
+ * still fails — and it fails with the ORIGINAL issues plus the shape the tool
+ * actually wants, because "expected object, received string" on its own does not
+ * tell a weaker model which key to fix.
+ */
+declare function validateToolArgs(tool: ToolInterface<any, any, any>, args: unknown): {
+    ok: true;
+    value: any;
+    coerced?: boolean;
+} | {
+    ok: false;
+    message: string;
+};
+
+/**
+ * Re-type `value` so it satisfies `schema`, walking both together.
+ *
+ * Returns the original value untouched whenever nothing needs repairing or
+ * nothing sensible can be done — this must never throw, because it runs on the
+ * error path and a throw here would replace a useful validation message with a
+ * crash.
+ */
+declare function coerceToolArgs(schema: unknown, value: unknown): unknown;
+
+declare function fileSink(path?: string): TraceSinkConfig;
+type CustomSinkArg = ((event: TraceEventRecord) => void | Promise<void>) | {
+    onEvent?: (event: TraceEventRecord) => void | Promise<void>;
+    onSession?: (session: TraceSessionFile) => void | Promise<void>;
+};
+declare function customSink(handler: CustomSinkArg): TraceSinkConfig;
+declare function cognipeerSink(apiKey: string): TraceSinkConfig;
+declare function cognipeerSink(url: string | undefined, apiKey: string): TraceSinkConfig;
+declare function httpSink(url: string, headers?: Record<string, string>): TraceSinkConfig;
+/**
+ * Create an OTLP/HTTP JSON sink that exports traces in OpenTelemetry format.
+ * @param endpoint OTLP endpoint URL (e.g. "https://console.cognipeer.com/api/client/v1/traces")
+ * @param headers Optional headers (e.g. { Authorization: "Bearer ..." })
+ */
+declare function otlpSink(endpoint: string, headers?: Record<string, string>): TraceSinkConfig;
+/**
+ * Convert a complete TraceSessionFile into an OTLP ExportTraceServiceRequest (JSON).
+ * Produces a root span for the session and child spans for each event.
+ */
+declare function traceSessionToOtlp(session: TraceSessionFile): Record<string, unknown>;
+/** Generate a W3C-compatible trace ID (32 hex chars / 128-bit). */
+declare function generateTraceId(): string;
+/** Generate an OTel span ID (16 hex chars / 64-bit). */
+declare function generateSpanId(): string;
+/**
+ * Build the `tool_definitions` section for one model call, or undefined when
+ * nothing usable was supplied. Exported for provider/node code that assembles
+ * sections itself.
+ */
+declare function buildToolDefinitionsSection(toolDefinitions: Array<{
+    name: string;
+    description?: string;
+    parameters?: Record<string, any>;
+}>): TraceToolDefinitionsSection | undefined;
+/**
+ * Build the `response_format` section for one model call, or undefined when
+ * nothing usable was supplied.
+ *
+ * Accepts either the invoke-options wrapper produced by
+ * `NativeJsonSchemaStrategy.buildResponseFormat()` (`{ response_format: {…} }`)
+ * or a bare `response_format` object, so callers can pass whatever they hold.
+ * Exported for provider/node code that assembles sections itself.
+ */
+declare function buildResponseFormatSection(responseFormat: Record<string, any> | undefined, strategy?: "native" | "tool_based"): TraceResponseFormatSection | undefined;
+/**
+ * Start a streaming trace session. Should be called before recording events in streaming mode.
+ * This sends the session start to the remote endpoint immediately.
+ */
+declare function startStreamingSession(session: TraceSessionRuntime | undefined, agentRuntime?: AgentRuntimeConfig): Promise<void>;
+
 type ProviderRetryPolicy = {
     /** Maximum number of retries on 429/5xx responses. Default: 3. */
     maxRetries?: number;
@@ -3527,4 +5619,4 @@ declare function fromNativeProvider(provider: BaseProvider, options?: NativeMode
  */
 declare function createProvider(config: ProviderConfig): BaseProvider;
 
-export { type AIMessage, ASK_USER_TOOL_NAME, type AgentInstance, type AgentInvokeResult, type AgentLimits, type AgentOptions, type AgentRuleOptions, type AgentRuntimeConfig, type AgentSnapshot, type AgentSnapshotMetadata, type AgentState, AnthropicProvider, type AnthropicProviderConfig, type AudioContent, AzureProvider, type AzureProviderConfig, type BaseChatMessage, type BaseChatMessagePart, type BaseChatModel, type BaseMessage, BaseProvider, BedrockProvider, type BedrockProviderConfig, type BuildChildConfig, type BuiltInRuntimeProfile, CCRStore, CONTEXT_PILOT_JSON_MARKER_KEY, CONTROL_PLANE_TOOL_NAMES, type CancellationTokenLike, type CancelledEvent, type ChatCompletionChunk, type ChatCompletionRequest, type ChatCompletionResponse, type ChildContextPolicy, type CodeDetectionRuleOptions, type CodeGuardrailOptions, type CompressToolOutputParams, type ContextPilotCCRConfig, type ContextPilotCacheAlignmentConfig, type ContextPilotCompressionConfig, type ContextPilotCompressionStats, type ContextPilotCompressorKind, type ContextPilotConfig, type ContextPilotDedupConfig, type ContextPilotDiffCompressionConfig, type ContextPilotJsonCompressionConfig, type ContextPilotLogCompressionConfig, type ContextPilotResult, type ContextPilotRuntime, type ContextPilotSearchCompressionConfig, type ContextPilotTextCompressionConfig, type ContextPolicy, type ContextToolsStateRef, type ConversationGuardrail, type CustomRuleCallback, type CustomRuleOptions, DEFAULT_MAX_TOOL_INPUT_FIELD_CHARS, DEFAULT_PROFILE_CONFIGS, DEFAULT_SKILL_POLICY, DEFAULT_SUBAGENT_POLICY, DEFAULT_SUBAGENT_TOOL_NAMES, DEFAULT_TOOL_INPUT_DIGEST_HEAD_CHARS, DELEGATION_TOOL_NAMES, DedupTracker, type DelegationEventStamp, type DelegationMode, type EvalCase, type EvalCaseResult, type EvalFamily, type EvalHarnessMetrics, type EvalHarnessParams, type EvalHarnessResult, type EvalProfileDescriptor, type EvalProfileTarget, type FileContent, type FinalAnswerEvent, type FinishReason, type GuardrailContext, type GuardrailDisposition, type GuardrailEvent, type GuardrailIncident, type GuardrailOutcome, GuardrailPhase, type GuardrailRule, type HandoffDescriptor, type HandoffEvent, type HumanInTheLoopAskUserConfig, type HumanInTheLoopOptions, type HumanInTheLoopRuntimeConfig, type ImageContent, InMemoryMemoryStore, type InvokeConfig, type JsonGuardrailOptions, type JsonSchemaRuleOptions, type LoadSkillsOptions, type MemoryFact, type MemoryProviderKind, type MemoryReadPolicy, type MemoryScope, type MemoryStore, type MemoryWritePolicy, type Message, type MetadataEvent, type ModelCapabilities, NativeJsonSchemaStrategy, type NativeModelOptions, type NativeReasoningConfig, OpenAICompatibleProvider, type OpenAICompatibleProviderConfig, OpenAIProvider, type OpenAIProviderConfig, PREOPEN_TOOL_CALL_PREFIX, type PendingToolApproval, type PendingUserQuestion, type PlanEvent, type PlanStepRecord, type PlanningMode, type PreopenSkillsResult, type ProfileConfig, type ProgressEvent, type ProgressUpdate, type PromptHooks, type ProviderConfig, ProviderError, type ToolCall as ProviderToolCall, type ToolDefinition as ProviderToolDefinition, type ProviderType, type ReasoningConfig, type ReasoningLevel, type ReflectionCadence, type ReflectionConfig, type ReflectionEvent, type ReflectionHookContext, type ReflectionRecord, type RegexGuardrailOptions, type RegexRuleOptions, type ReplanPolicy, type ResolvedContextPilotConfig, type ResolvedSmartAgentConfig, type ResolvedTraceConfig, type ResolvedTraceSink, type RestoreSnapshotOptions, type RuntimeProfile, SMALL_TIER_SKILL_POLICY, type SerializableSmartState, type Skill, type SkillDisclosure, type SkillExecutionContext, type SkillFrontmatter, type SkillFs, type SkillModelTier, type SkillPolicy, type SkillRegistryRef, type SkillToolDeps, type SkillToolHeader, type SmartAgentBudgetConfig, type SmartAgentContextConfig, type SmartAgentCustomProfileConfig, type SmartAgentDelegationConfig, type SmartAgentEvent, type SmartAgentInstance, type SmartAgentLimits, type SmartAgentMemoryConfig, type SmartAgentOptions, type SmartAgentPlanningConfig, type SmartAgentSummarizationConfig, type SmartAgentToolResponseConfig, type SmartAgentTracingConfig, type SmartModel, type SmartState, type SmartToolFn, type SnapshotOptions, type SnapshotRuntimeHint, type StreamChunk, type StreamEvent, type StructuredOutputError, type StructuredOutputFieldError, StructuredOutputManager, type StructuredOutputManagerConfig, type StructuredOutputResult, type StructuredOutputStrategy, type StructuredSummary, type SubagentDef, type SubagentEvent, type SubagentMode, type SubagentPendingRecord, type SubagentPolicy, type SubagentRegistryRef, type SubagentResult, type SubagentToolDeps, type SubagentToolNames, type SummarizationEvent, type SummarizationMode, type SummaryFactItem, type SummaryIntegrityCheck, TOOL_INPUT_DIGEST_KEY, type TextContent, type TokenCounter, type TokenUsage, type ToolApprovalEvent, type ToolApprovalResolution, type ToolApprovalStatus, ToolBasedStrategy, type ToolCachePolicy, type ToolCallEvent, type ToolInputDigestOptions, type ToolInputDigestResult, type ToolInputRetentionPolicy, type ToolInterface, type ToolResponseClassification, type ToolResponseRetentionPolicy, type ToolRetentionDeclarations, type ToolRetentionSpec, type ToolRetryPolicy, type TraceDataSection, type TraceErrorRecord, type TraceEventRecord, type TraceMessageSection, type TraceMetadataSection, type TraceSessionConfigSnapshot, type TraceSessionFile, type TraceSessionStatus, type TraceSessionSummary, type TraceSinkCognipeerConfig, type TraceSinkConfig, type TraceSinkCustomConfig, type TraceSinkFileConfig, type TraceSinkHttpConfig, type TraceSinkOtlpConfig, type TraceSinkSnapshot, type TraceSummarySection, type TraceToolCallSection, type TraceToolDefinition, type TraceToolDefinitionsSection, type TraceToolDetails, type TraceToolResponseSection, type TraceToolResultSection, type TracingConfig, type TracingMode, type UnifiedMessage, type UserQuestionAnswer, type UserQuestionAnswerSet, type UserQuestionEvent, type UserQuestionItem, type UserQuestionOption, type UserQuestionResolution, type UserQuestionStatus, VertexProvider, type VertexProviderConfig, type VolatileContentFinding, type VolatileContentPattern, agentVerdictRule, appendBoundTools, buildResponseFormatSection, buildSkillHeaderBlock, buildSubagentCatalogBlock, buildSystemPrompt, buildToolDefinitionsSection, canOpenSkill, canSpawn, captureSnapshot, codePresenceRule, coerceToolArgs, cognipeerSink, collectToolRetentionDeclarations, composeToolSets, compressDiffOutput, compressJsonOutput, compressLogOutput, compressSearchOutput, compressTextOutput, compressToolOutput, countApproxTokens, countMessagesTokens, createAgent, createAgentNode, createAskUserQuestionTool, createBindSkillToolsTool, createCodeGuardrail, createContextPilotRuntime, createContextSummarizeNode, createContextTools, createDelegateTool, createGetToolResponseTool, createGuardrail, createJsonGuardrail, createManageTodoListAliasTool, createManageTodoTool, createOpenSkillTool, createParallelTool, createProvider, createRegexGuardrail, createResolverNode, createSearchSkillsTool, createSkillRegistryRef, createSkillTools, createSmartAgent, createSpawnTool, createSubagentRegistryRef, createSubagentTools, createTool, createToolLimitFinalizeNode, createToolsNode, customCallbackRule, customSink, dedupeToolsByName, defaultTokenCounter, detectTextFormat, detectVolatileContent, digestToolInputArguments, digestToolInputValue, emptyUsage, evaluateGuardrails, extractLatestUserQuery, fileSink, findSubagent, formatZodError, fromLangchainModel, fromLangchainTools, fromNativeProvider, generateSpanId, generateTraceId, getModelCapabilities, getNestedValue, getResolvedSmartConfig, getTokenCounter, hasToolResponseRecoveryReference, httpSink, isSmartModel, jsonSchemaRule, loadSkillsFromDisk, normalizeSmartAgentOptions, otlpSink, parseSkillFrontmatter, preopenSkills, preopenToolCallId, readMemoryFacts, regexRule, resolveAvailableSkills, resolveAvailableSubagents, resolveInputRetention, resolveMemoryStore, resolveReasoning, resolveStrategy, resolveSubagentTools, resolveSummarizationRetention, resolveToolApprovalState, resolveUserQuestionState, restoreSnapshot, runSmartAgentEvalHarness, scoreItemsByRelevance, searchSkills, seedChildMessages, selectTopIndicesInOrder, setTokenCounter, startStreamingSession, summarizeObject, tokenize, traceSessionToOtlp, validateReasoningConfig, validateToolArgs, withTools, withinDepth, writeSummaryFactsToMemory };
+export { type AIMessage, ASK_USER_TOOL_NAME, type AgentInstance, type AgentInvokeResult, type AgentLimits, type AgentOptions, type AgentPlugin, type AgentRuleOptions, type AgentRuntimeConfig, type AgentSnapshot, type AgentSnapshotMetadata, type AgentState, AnthropicProvider, type AnthropicProviderConfig, type ApprovalTransport, type AudioContent, type AuditEntry, type AuditLogConfig, type AzureContentSafetyConfig, AzureProvider, type AzureProviderConfig, type BaseChatMessage, type BaseChatMessagePart, type BaseChatModel, type BaseMessage, BaseProvider, type BedrockGuardrailConfig, BedrockProvider, type BedrockProviderConfig, type BudgetGuardConfig, type BuildChildConfig, type BuiltInRuntimeProfile, CCRStore, CONSOLE_HOOK_MAP, CONTEXT_PILOT_JSON_MARKER_KEY, CONTROL_PLANE_TOOL_NAMES, type CancellationTokenLike, type CancelledEvent, type CapabilityStatus, type ChatCompletionChunk, type ChatCompletionRequest, type ChatCompletionResponse, type CheckpointPluginConfig, type CheckpointStore, type ChildContextPolicy, type CodeDetectionRuleOptions, type CodeGuardrailOptions, type CognipeerGuardrailConfig, type CompressToolOutputParams, type ContextBuilder, type ContextPilotCCRConfig, type ContextPilotCacheAlignmentConfig, type ContextPilotCompressionConfig, type ContextPilotCompressionStats, type ContextPilotCompressorKind, type ContextPilotConfig, type ContextPilotDedupConfig, type ContextPilotDiffCompressionConfig, type ContextPilotJsonCompressionConfig, type ContextPilotLogCompressionConfig, type ContextPilotResult, type ContextPilotRuntime, type ContextPilotSearchCompressionConfig, type ContextPilotTextCompressionConfig, type ContextPolicy, type ContextToolsStateRef, type ConversationGuardrail, type ConversationPluginConfig, type ConversationStore, type CostEstimator, type CustomRuleCallback, type CustomRuleOptions, DEFAULT_MAX_TOOL_INPUT_FIELD_CHARS, DEFAULT_PROFILE_CONFIGS, DEFAULT_SKILL_POLICY, DEFAULT_SUBAGENT_POLICY, DEFAULT_SUBAGENT_TOOL_NAMES, DEFAULT_TOOL_INPUT_DIGEST_HEAD_CHARS, DELEGATION_TOOL_NAMES, DedupTracker, type DelegationEventStamp, type DelegationMode, type EvalCase, type EvalCaseResult, type EvalFamily, type EvalHarnessMetrics, type EvalHarnessParams, type EvalHarnessResult, type EvalProfileDescriptor, type EvalProfileTarget, type FileContent, type FinalAnswerEvent, type FinishReason, type GateResult, type GuardrailCallContext, type GuardrailContext, type GuardrailDisposition, type GuardrailEvent, type GuardrailIncident, type GuardrailOutcome, GuardrailPhase, type GuardrailPhaseName, type GuardrailPluginOptions, type GuardrailRequest, type GuardrailRule, type GuardrailRuleResult, type GuardrailTransport, type GuardrailVerdict, type GuardrailViolation, HOOK_CONTRACT_VERSION, HOOK_NAMES, type HandoffDescriptor, type HandoffEvent, type HookContext, type HookDecision, type HookHandler, type HookMap, type HookName, type HookRegistrations, HookTimeoutError, type HttpGuardrailOptions, type HumanInTheLoopAskUserConfig, type HumanInTheLoopOptions, type HumanInTheLoopRuntimeConfig, type ImageContent, InMemoryMemoryStore, type InjectionScan, type InvokeConfig, type JsonGuardrailOptions, type JsonSchemaRuleOptions, type LangfuseBuildContext, type LangfuseEvent, type LangfuseEventKind, type LangfuseTracingConfig, type LanguageGuardConfig, type LoadSkillsOptions, type MaybePromise, type McpConfig, type McpConnection, type MediaAttachment, type MediaKind, type MediaPolicyConfig, type MemoryFact, type MemoryProviderKind, type MemoryReadPolicy, type MemoryScope, type MemoryStore, type MemoryWritePolicy, type Message, type MetadataEvent, type ModelCapabilities, NativeJsonSchemaStrategy, type NativeModelOptions, type NativeReasoningConfig, OpenAICompatibleProvider, type OpenAICompatibleProviderConfig, type OpenAIModerationConfig, OpenAIProvider, type OpenAIProviderConfig, type OtelTracingConfig, type OutputGuardConfig, PREOPEN_TOOL_CALL_PREFIX, type PendingToolApproval, type PendingUserQuestion, type PiiDetector, type PiiEntity, type PiiRedactionConfig, type PlanEvent, type PlanStepRecord, type PlanningMode, type PluginContributions, type PluginEvent, type PluginFailureMode, type PluginHost, type PluginHostOptions, type PluginLogger, type PluginProvides, type PluginRunHost, type PluginSetupContext, type PortkeyGatewayConfig, type PortkeyGuardrailConfig, type PreopenSkillsResult, type ProfileConfig, type ProgressEvent, type ProgressUpdate, type PromptHooks, type PromptInjectionFamily, type PromptInjectionGuardConfig, type PromptSource, type ProviderConfig, ProviderError, type ToolCall as ProviderToolCall, type ToolDefinition as ProviderToolDefinition, type ProviderType, type RateLimitConfig, type ReasoningConfig, type ReasoningLevel, type RedactionResult, type ReflectionCadence, type ReflectionConfig, type ReflectionEvent, type ReflectionHookContext, type ReflectionRecord, type RegexGuardrailConfig, type RegexGuardrailOptions, type RegexRuleOptions, type ReplanPolicy, type ResolvedContextPilotConfig, type ResolvedSmartAgentConfig, type ResolvedTraceConfig, type ResolvedTraceSink, type ResponseCacheConfig, type RestoreSnapshotOptions, type RuntimeProfile, SMALL_TIER_SKILL_POLICY, type SdkCapabilities, type SerializableSmartState, type SessionMetrics, type SessionMetricsConfig, type Skill, type SkillDisclosure, type SkillExecutionContext, type SkillFrontmatter, type SkillFs, type SkillModelTier, type SkillPolicy, type SkillRegistryRef, type SkillSource, type SkillToolDeps, type SkillToolHeader, type SlotName, type SmartAgentBudgetConfig, type SmartAgentContextConfig, type SmartAgentCustomProfileConfig, type SmartAgentDelegationConfig, type SmartAgentEvent, type SmartAgentInstance, type SmartAgentLimits, type SmartAgentMemoryConfig, type SmartAgentOptions, type SmartAgentPlanningConfig, type SmartAgentSummarizationConfig, type SmartAgentToolResponseConfig, type SmartAgentTracingConfig, type SmartModel, type SmartState, type SmartToolFn, type SnapshotOptions, type SnapshotRuntimeHint, type StreamChunk, type StreamEvent, type StructuredOutputError, type StructuredOutputFieldError, StructuredOutputManager, type StructuredOutputManagerConfig, type StructuredOutputResult, type StructuredOutputStrategy, type StructuredSummary, type SubagentDef, type SubagentEvent, type SubagentMode, type SubagentPendingRecord, type SubagentPolicy, type SubagentRegistryRef, type SubagentResult, type SubagentToolDeps, type SubagentToolNames, type SummarizationEvent, type SummarizationMode, type SummarizerInput, type SummarizerResult, type SummarizerStrategy, type SummaryFactItem, type SummaryIntegrityCheck, TOOL_INPUT_DIGEST_KEY, type TextContent, type TokenCounter, type TokenUsage, type ToolApprovalEvent, type ToolApprovalResolution, type ToolApprovalStatus, ToolBasedStrategy, type ToolCachePolicy, type ToolCallEvent, type ToolInputDigestOptions, type ToolInputDigestResult, type ToolInputRetentionPolicy, type ToolInterface, type ToolPolicyConfig, type ToolResponseClassification, type ToolResponseRetentionPolicy, type ToolRetentionDeclarations, type ToolRetentionSpec, type ToolRetryPolicy, type ToolRule, type TraceDataSection, type TraceErrorRecord, type TraceEventRecord, type TraceMessageSection, type TraceMetadataSection, type TraceSessionConfigSnapshot, type TraceSessionFile, type TraceSessionStatus, type TraceSessionSummary, type TraceSinkCognipeerConfig, type TraceSinkConfig, type TraceSinkCustomConfig, type TraceSinkFileConfig, type TraceSinkHttpConfig, type TraceSinkOtlpConfig, type TraceSinkSnapshot, type TraceSummarySection, type TraceToolCallSection, type TraceToolDefinition, type TraceToolDefinitionsSection, type TraceToolDetails, type TraceToolResponseSection, type TraceToolResultSection, type TracingConfig, type TracingMode, type UnifiedMessage, type UserQuestionAnswer, type UserQuestionAnswerSet, type UserQuestionEvent, type UserQuestionItem, type UserQuestionOption, type UserQuestionResolution, type UserQuestionStatus, VertexProvider, type VertexProviderConfig, type VolatileContentFinding, type VolatileContentPattern, type WebhookApprovalConfig, agentVerdictRule, appendBoundTools, auditLog, azureContentSafety, bedrockGuardrail, budgetGuard, buildHandoffTools, buildResponseFormatSection, buildSkillHeaderBlock, buildSubagentCatalogBlock, buildSystemPrompt, buildToolDefinitionsSection, canOpenSkill, canSpawn, captureSnapshot, checkpointing, codePresenceRule, coerceToolArgs, cognipeerGuardrail, cognipeerSink, collectAttachments, collectToolRetentionDeclarations, composeToolSets, compressDiffOutput, compressJsonOutput, compressLogOutput, compressSearchOutput, compressTextOutput, compressToolOutput, contentToString, conversationHistory, countApproxTokens, countMessagesTokens, createAgent, createAgentNode, createAskUserQuestionTool, createBindSkillToolsTool, createCodeGuardrail, createContextPilotRuntime, createContextSummarizeNode, createContextTools, createDelegateTool, createGetToolResponseTool, createGuardrail, createGuardrailPlugin, createJsonGuardrail, createManageTodoListAliasTool, createManageTodoTool, createOpenSkillTool, createParallelTool, createPluginHost, createProvider, createRegexGuardrail, createResolverNode, createSearchSkillsTool, createSkillRegistryRef, createSkillTools, createSmartAgent, createSpawnTool, createSubagentRegistryRef, createSubagentTools, createTool, createToolLimitFinalizeNode, createToolsNode, customCallbackRule, customGuardrail, customSink, dedupeToolsByName, defaultTokenCounter, defineHook, definePlugin, detectLanguage, detectTextFormat, detectVolatileContent, digestToolInputArguments, digestToolInputValue, emptyUsage, evaluateGuardrails, extractLatestUserQuery, extractMessageText, fileCheckpointStore, fileSink, findSubagent, formatZodError, fromLangchainModel, fromLangchainTools, fromNativeProvider, generateSpanId, generateTraceId, getModelCapabilities, getNestedValue, getResolvedSmartConfig, getTokenCounter, hasToolResponseRecoveryReference, httpGuardrail, httpSink, inMemoryCheckpointStore, inMemoryConversationStore, isHookImplemented, isSmartModel, isValidIban, isValidLuhn, isValidTckn, jsonSchemaRule, defaultBuildPayload as langfuseDefaultPayload, langfuseTracing, languageGuard, loadSkillsFromDisk, mapConsoleHookVerdict, mapTextParts, mcp, mediaPolicy, normalizeSmartAgentOptions, normalizeVerdicts, openAIModeration, otelTracing, otlpSink, outputGuard, parseApprovalDecision, parseSkillFrontmatter, pathSandbox, piiRedaction, pluginCapabilities, portkeyGateway, portkeyGuardrail, preopenSkills, preopenToolCallId, promptInjectionGuard, rateLimit, readMemoryFacts, redactText, regexGuardrail, regexRule, replaceTextContent, resolveAvailableSkills, resolveAvailableSubagents, resolveInputRetention, resolveMemoryStore, resolveReasoning, resolveStrategy, resolveSubagentTools, resolveSummarizationRetention, resolveToolApprovalState, resolveUserQuestionState, responseCache, restoreSnapshot, runSmartAgentEvalHarness, scoreItemsByRelevance, searchSkills, seedChildMessages, selectTopIndicesInOrder, sessionMetrics, setTokenCounter, startStreamingSession, summarizeObject, textFromContent, tokenize, toolPolicy, traceSessionToOtlp, validateReasoningConfig, validateToolArgs, webhookApproval, withTools, withinDepth, writeSummaryFactsToMemory };