@theokit/agents 0.30.2 → 0.32.0

package/dist/{bridge-entry-DzSZRp22.d.ts → bridge-entry-1r1DL-mS.d.ts}

@@ -1,5 +1,5 @@
 import { ExecutionContext } from '@theokit/http';
-import { A as AgentOptions, D as ToolOptions, m as MainLoopMeta, a as ApprovalOptions, B as BudgetOptions, l as HumanInTheLoopOptions, k as GatewayOptions, r as MemoryOptions, z as SkillsOptions, j as ContextWindowOptions, w as ProjectContextOptions, p as McpServersMap, g as CompactionDecoratorConfig, b as CheckpointOptions, R as ReasoningEffort } from './skills-Dx_KJ6Eg.js';
+import { A as AgentOptions, D as ToolOptions, m as MainLoopMeta, a as ApprovalOptions, B as BudgetOptions, l as HumanInTheLoopOptions, k as GatewayOptions, r as MemoryOptions, z as SkillsOptions, j as ContextWindowOptions, w as ProjectContextOptions, p as McpServersMap, g as CompactionDecoratorConfig, b as CheckpointOptions, R as ReasoningEffort } from './skills-DvI_LYWZ.js';
 import { SystemPromptResolver, SkillsSettings, ContextSettings, PluginsSettings, Plugin, ProviderRoutingSettings, AgentDefinition as AgentDefinition$1, BudgetTracker, ConversationStorageAdapter, CustomTool, ModelSelection } from '@theokit/sdk';
 import { UIMessageChunk } from 'ai';
 import { z } from 'zod';
@@ -102,6 +102,75 @@ declare function walkAgentMetadata(AgentClass: Function, toolboxClasses?: Functi
  */
 declare function validateUniqueRoutes(results: AgentWalkResult[]): void;
 
+/**
+ * M9 (theokit-ai-first) — guardrail contract + typed errors.
+ *
+ * ADR-0040 § D2: guardrails are a HOME/BOUNDARY concern (filter user input before the SDK,
+ * filter model output before the client). They REUSE the SDK runtime — this module makes zero
+ * LLM calls. A guard reports one of three actions; the pipeline (`pipeline.ts`) enforces them.
+ */
+/** What a guard decided for a piece of text. */
+type GuardrailAction = 'allow' | 'block' | 'redact';
+/**
+ * The result of a single guard check.
+ * - `allow`  — text passes untouched.
+ * - `block`  — the pipeline throws {@link GuardrailViolationError}; the run stops fail-fast.
+ * - `redact` — the pipeline replaces the text with {@link GuardrailResult.text} and continues.
+ */
+interface GuardrailResult {
+    action: GuardrailAction;
+    /** Human-readable reason — required in spirit for `block`, surfaced in the thrown error. */
+    reason?: string;
+    /** The transformed text — present (and used) only when `action === 'redact'`. */
+    text?: string;
+}
+/**
+ * A guardrail. A guard MAY inspect input (before the model), output (after the model), or both.
+ * A guard that omits a phase hook is skipped for that phase.
+ */
+interface Guardrail {
+    readonly name: string;
+    checkInput?(text: string): GuardrailResult | Promise<GuardrailResult>;
+    checkOutput?(text: string): GuardrailResult | Promise<GuardrailResult>;
+}
+/** Which boundary phase a violation happened in. */
+type GuardrailPhase = 'input' | 'output';
+/** Thrown (fail-fast) when a guard returns `action: 'block'`. Typed per error-handling.md. */
+declare class GuardrailViolationError extends Error {
+    readonly guardName: string;
+    readonly phase: GuardrailPhase;
+    readonly reason: string;
+    constructor(guardName: string, phase: GuardrailPhase, reason: string);
+}
+/** Thrown when {@link costGuard}'s cumulative token budget is exceeded. */
+declare class CostBudgetExceededError extends Error {
+    readonly usedTokens: number;
+    readonly maxTokens: number;
+    constructor(usedTokens: number, maxTokens: number);
+}
+
+/**
+ * M13 (theokit-ai-first) — per-request skills resolution (ADR-0040 § D2, home/boundary concern).
+ *
+ * The static `skills.enabled` filter already works (`compile-skills` maps `include` → the SDK's
+ * `enabled`). This adds a PER-REQUEST resolver so multi-tenant apps expose different skill sets to
+ * different users. A selection is either a static list or a function of the request context (the M7
+ * run-context). Discovery + injection stay in the SDK; this only CHOOSES the enabled set per call.
+ */
+/** The request context handed to a skills resolver (the M7 run-context — opaque per-request data). */
+type SkillsRequestContext = Record<string, unknown>;
+/**
+ * How the enabled skill set is chosen:
+ * - `string[]`  — a static list (same shape `skills.enabled` accepts today).
+ * - a function  — resolved per request from the {@link SkillsRequestContext} (sync or async).
+ */
+type SkillsSelection = readonly string[] | ((ctx: SkillsRequestContext) => readonly string[] | Promise<readonly string[]>);
+/**
+ * Resolve the enabled skill names for a request. Returns `undefined` when no selection is given (the
+ * SDK then enables every discovered skill). Fails fast if a resolver returns a non-array.
+ */
+declare function resolveEnabledSkills(selection: SkillsSelection | undefined, ctx: SkillsRequestContext): Promise<string[] | undefined>;
+
 /**
  * Agent compiler — transforms decorator metadata into SDK calls.
  *
@@ -116,7 +185,17 @@ interface CompiledTool {
     name: string;
     description: string;
     inputSchema: unknown;
-    handler: (input: unknown) => string | Promise<string>;
+    /**
+     * M7 — the optional 2nd `ctx` arg carries the SDK run context: `ctx.context` is the
+     * `defineAgent({ context })` / per-run value, `ctx.signal` the abort signal. Optional so the
+     * decorator `@Tool` handlers (which ignore it) stay assignable. The SDK calls the tool with
+     * both args; a handler that needs run-context (e.g. a filesystem tool reading `projectRoot`)
+     * reads `ctx?.context`.
+     */
+    handler: (input: unknown, ctx?: {
+        signal?: AbortSignal;
+        context?: unknown;
+    }) => string | Promise<string>;
 }
 /**
  * Compile @Tool metadata into tool definitions.
@@ -155,6 +234,13 @@ interface CompiledAgentOptions {
     memory?: MemoryOptions;
     skills?: SkillsSettings;
     context?: ContextSettings;
+    /**
+     * M7 — run-context injected into every tool handler's `ctx.context` by the theokit adapter
+     * (`buildSdkTools` wrapper). Populated by `defineAgent({ context })` (functional surface).
+     * NAME NOTE: distinct from the context-window `context` (`ContextSettings`) above — this is
+     * per-run user data for tools, not token-budget config.
+     */
+    runContext?: Record<string, unknown>;
     /** Raw @ProjectContext config; the adapter builds the (async) systemPrompt resolver from it. */
     projectContext?: ProjectContextOptions;
     mcpServers?: McpServersMap;
@@ -171,6 +257,18 @@ interface CompiledAgentOptions {
      * durable SDK conversation storage (`storage: 'filesystem'`) so a same-`sessionId` request resumes.
      */
     checkpoint?: CheckpointOptions;
+    /**
+     * M9 — guardrails: input/output guards applied at the framework boundary (ADR-0040 § D2).
+     * Input guards run on the user message BEFORE the SDK runtime sees it (fail-fast on `block`).
+     * They REUSE the runtime; they never reimplement it. Absent/empty ⇒ no guards.
+     */
+    guardrails?: readonly Guardrail[];
+    /**
+     * M13 — per-request skills resolver (from `defineAgent({ skills: (ctx) => [...] })`). The request
+     * path resolves it against the run-context (`resolveEnabledSkills`) and sets `skills.enabled`
+     * before the SDK runs. Not consumed by the SDK directly (it reads `skills`). Absent ⇒ no resolver.
+     */
+    skillsResolver?: SkillsSelection;
 }
 /**
  * Compile @Agent metadata into SDK-compatible options.
@@ -322,6 +420,8 @@ interface ApprovalRequiredEvent {
     input?: unknown;
     callbackUrl: string;
     timeoutMs: number;
+    /** M20 — JSON-schema descriptor of the custom payload the approver may attach (optional). */
+    payloadSchema?: Record<string, unknown>;
 }
 /** Agent encountered an error. */
 interface ErrorEvent {
@@ -474,6 +574,12 @@ interface RuntimeOverrides {
     recoverLeakedToolCalls?: boolean;
     /** Per-run cwd → `Agent.create({ local: { cwd } })` → `SystemPromptContext.cwd`. */
     cwd?: string;
+    /**
+     * M7 — per-run run-context override (`?? compiled.runContext`). Injected into every tool
+     * handler's `ctx.context` by `buildSdkTools`. Lets a single request override the agent-level
+     * `defineAgent({ context })` (mirrors `model`/`cwd`).
+     */
+    runContext?: Record<string, unknown>;
     /**
      * Per-run plugins (e.g. permission gate selected by request mode). Accepts EITHER
      * named-plugin discovery settings (`{ enabled: [...] }`) OR an array of code `Plugin`
@@ -632,13 +738,56 @@ interface DefineAgentConfig<TInput extends z.ZodType = z.ZodType> {
      * normalized to the internal {@link CompiledTool} shape at compile time.
      */
     tools?: readonly CustomTool[];
+    /**
+     * M7 — run-context: an opaque, per-agent object forwarded to every tool handler's
+     * `ctx.context` at run time (injected by the theokit adapter's tool wrapper). Set shared config
+     * (e.g. `{ projectRoot }`) ONCE at the agent level instead of baking it into each tool
+     * factory. Mirrors ai-sdk `experimental_context`, mastra `RuntimeContext`, and
+     * openai-agents-js `RunContext`. Distinct from `@Agent`'s context-window `context`.
+     */
+    context?: Record<string, unknown>;
+    /**
+     * M9 — guardrails: input/output guards applied at the framework boundary (ADR-0040 § D2).
+     * Input guards run on the user message before the SDK runtime; a `block` fails the run fast.
+     * Built-ins live in `@theokit/agents` (`promptInjectionDetector`, `piiDetector`, `costGuard`,
+     * `unicodeNormalizer`, `outputModeration`).
+     */
+    guardrails?: readonly Guardrail[];
+    /**
+     * M14 — HITL approvals keyed by tool name. Each gated tool pauses the run and emits an
+     * `approval_required` event until approved (reuses the same `compiled.hitl` wiring the `@Agent`
+     * + `@HumanInTheLoop` path produces). A key that does not match a declared tool fails fast at
+     * compile time.
+     */
+    approvals?: Record<string, HumanInTheLoopOptions>;
+    /**
+     * M13 — skills selection: a static list (compiled straight to the SDK `skills.enabled`) OR a
+     * per-request resolver `(ctx) => string[]` (carried on `compiled.skillsResolver`, resolved by the
+     * request path against the run-context). Absent ⇒ the SDK enables every discovered skill.
+     */
+    skills?: SkillsSelection;
 }
-/** A branded agent definition — the value {@link defineAgent} returns. */
-type AgentDefinition<TInput extends z.ZodType = z.ZodType> = DefineAgentConfig<TInput> & {
+/**
+ * A branded agent definition — the value {@link defineAgent} returns.
+ *
+ * `TTools` (M8) is a phantom type parameter carrying the tool-name union: the `agent()` builder
+ * threads its accumulated literal tool names here (`.build()` returns `AgentDefinition<TInput,
+ * 'a' | 'b'>`), so the generated client (`.theokit/agents.d.ts`) can expose them via
+ * {@link InferAgentToolNames}. `defineAgent` leaves it `string` (its tools array carries no literal
+ * names). Never present at runtime.
+ */
+type AgentDefinition<TInput extends z.ZodType = z.ZodType, TTools extends string = string> = DefineAgentConfig<TInput> & {
     readonly [AGENT_BRAND]: true;
+    readonly __toolNames?: TTools;
 };
 /** Infer the request type of an agent definition from its `input` Zod schema. */
 type InferAgentInput<T> = T extends AgentDefinition<infer S> ? (S extends z.ZodType ? z.infer<S> : never) : never;
+/**
+ * Infer the tool-name union of an agent definition (M8). Yields the literal union for agents built
+ * with the `agent()` builder (`'read_file' | 'count_lines'`), or `string` for `defineAgent` agents
+ * whose tools array carries no literal names.
+ */
+type InferAgentToolNames<T> = T extends AgentDefinition<z.ZodType, infer N> ? N : never;
 /**
  * Define a zero-config agent. Identity/normalizer (like `defineRoute`) — returns the config
  * branded so the scanner recognizes it. Compilation is deferred to {@link compileAgentDefinition}.
@@ -652,6 +801,106 @@ declare function isAgentDefinition(value: unknown): value is AgentDefinition;
  */
 declare function compileAgentDefinition(def: AgentDefinition): CompiledAgentOptions;
 
+/**
+ * M8 — `agent()`, the fluent agent builder with accumulative **type-state**.
+ *
+ * `agent().context<C>().tool(t).model(id).system(s).build()` accumulates type parameters the way
+ * the most-loved TS DX does (tRPC `t.procedure.input().query()`, Zod, Hono) and resolves to the
+ * **SAME branded `AgentDefinition`** that {@link defineAgent} produces — one runtime, N syntaxes
+ * (ADR-B1). The value is entirely at the type level; `.build()` delegates to `defineAgent`, so
+ * convergence with the `defineAgent` / `@Agent` surfaces is by construction.
+ *
+ * Compile-time guarantees (proven by `tests/type/agent-builder.test-d.ts`):
+ * - `.build()` is a compile error when `.model()` was never called (UnsetMarker technique — tRPC
+ *   `utils.ts:2-4` / `procedureBuilder.ts:362-379`).
+ * - `.tool(t)` is a compile error when the tool declares a required run-context ⊄ the agent's `C`.
+ * - tool names accumulate into a union type parameter (`TTools`).
+ *
+ * PURE metadata (sdk-runtime.md / G2): the builder describes an agent, it NEVER calls an LLM.
+ */
+
+/**
+ * A required-but-unset builder field. Branded (a literal intersected with a unique brand) so no
+ * ordinary value can satisfy it — the terminal-method guards below key off it. tRPC's UnsetMarker.
+ */
+type UnsetMarker = 'theokit.unset' & {
+    readonly __brand: 'theokit.unset';
+};
+/**
+ * Compile-error carriers. When a guarded method's precondition fails, its signature demands an
+ * argument of one of these types, which the caller cannot supply — the labeled tuple element
+ * surfaces the reason in the error. (Idiomatic gate for zero-arg terminal methods.)
+ */
+interface MissingModelError {
+    readonly __theokitError: 'call .model(id) before .build()';
+}
+interface ToolContextError<TRequired> {
+    readonly __theokitError: 'this tool requires a run-context not provided via .context()';
+    readonly required: TRequired;
+}
+/** The agent context before `.context()` is called — satisfies only tools with no requirement. */
+type EmptyContext = Record<never, never>;
+/**
+ * A tool that MAY declare, at the type level, the run-context shape it needs. A plain
+ * {@link CustomTool} (`TRequired = unknown`) is satisfied by any agent context. Build one that
+ * carries a literal name + optional required-context via {@link contextualTool}.
+ */
+interface ContextualTool<TName extends string = string, TRequired = unknown> extends CustomTool {
+    readonly name: TName;
+    /** Phantom — never present at runtime; carries the required run-context type for `.tool()`. */
+    readonly __requiredContext?: TRequired;
+}
+/**
+ * Tag a {@link CustomTool} with a literal name (so `.tool()` can accumulate the tool-name union)
+ * and, optionally, a required run-context type. The `requiredContext` argument is a type-only
+ * witness — pass `undefined as C` or a sample value; it is never read at runtime.
+ */
+declare function contextualTool<TName extends string, TRequired = unknown>(tool: CustomTool & {
+    name: TName;
+}, _requiredContext?: TRequired): ContextualTool<TName, TRequired>;
+/**
+ * The fluent builder. Each method returns a NEW builder type with the relevant type parameter
+ * advanced (immutable chaining). Runtime state is a plain {@link DefineAgentConfig} accumulator.
+ */
+interface AgentBuilder<TInput extends z.ZodType | UnsetMarker = UnsetMarker, TModel extends string | UnsetMarker = UnsetMarker, TContext = EmptyContext, TTools extends string = never> {
+    /** Set the request schema (lifted into the typed client via {@link AgentDefinition}). */
+    input<S extends z.ZodType>(schema: S): AgentBuilder<S, TModel, TContext, TTools>;
+    /**
+     * Set the model id. Required before `.build()`. COMPILE ERROR when called twice — the argument
+     * type collapses to `never` once the model is set (tRPC's set-once technique).
+     */
+    model(id: TModel extends UnsetMarker ? string : never): AgentBuilder<TInput, string, TContext, TTools>;
+    /** Set the static system prompt. */
+    system(prompt: string): AgentBuilder<TInput, TModel, TContext, TTools>;
+    /** Set the extended-thinking effort. */
+    reasoningEffort(effort: ReasoningEffort): AgentBuilder<TInput, TModel, TContext, TTools>;
+    /** Set the run-context (M7) — the object every tool handler receives as `ctx.context`. */
+    context<C extends Record<string, unknown>>(value: C): AgentBuilder<TInput, TModel, C, TTools>;
+    /**
+     * Add a tool. Accumulates its name into `TTools`. COMPILE ERROR when the tool declares a
+     * required run-context (`ContextualTool<_, TRequired>`) that the agent's `TContext` does not
+     * satisfy — set it first with `.context()`.
+     */
+    tool<TName extends string, TRequired>(tool: ContextualTool<TName, TRequired>, ...guard: TContext extends TRequired ? [] : [error: ToolContextError<TRequired>]): AgentBuilder<TInput, TModel, TContext, TTools | TName>;
+    /**
+     * Apply a reusable partial chain (Spring-Boot-style composition). `preset` receives the current
+     * builder and returns an advanced one; its accumulated type-state flows through.
+     */
+    use<TResult>(preset: (builder: AgentBuilder<TInput, TModel, TContext, TTools>) => TResult): TResult;
+    /**
+     * Resolve to the branded {@link AgentDefinition} — the SAME value `defineAgent` returns.
+     * COMPILE ERROR when `.model()` was never called.
+     */
+    build(...guard: TModel extends UnsetMarker ? [error: MissingModelError] : []): AgentDefinition<TInput extends z.ZodType ? TInput : z.ZodType, TTools>;
+    /** Phantom — lets type tests read the accumulated tool-name union. Never present at runtime. */
+    readonly __toolNames?: TTools;
+}
+/**
+ * Start a fluent agent definition. Chain `.model()` (required) + `.context()` / `.system()` /
+ * `.input()` / `.tool()` / `.use()`, then `.build()` to get the branded {@link AgentDefinition}.
+ */
+declare function agent(): AgentBuilder;
+
 /**
  * M4 (theokit-ai-first) — the HITL producer: a `pre_tool_call` plugin that pauses the SDK run
  * for a human-in-the-loop tool approval.
@@ -667,14 +916,27 @@ declare function compileAgentDefinition(def: AgentDefinition): CompiledAgentOpti
  * surfaces as a tool result the model self-corrects on).
  */
 
+/**
+ * M20 — a settled HITL decision. Structural mirror of the harness's `ApprovalDecision` (the agents
+ * package must not import from `theokit` — dependency direction). `awaitApproval` may resolve a bare
+ * boolean (legacy) OR this object; the plugin normalizes both.
+ */
+interface HitlDecision {
+    approved: boolean;
+    reason?: string;
+    payload?: unknown;
+}
 /** Injected wiring — the harness (mount-agent) supplies these; the plugin stays pure. */
 interface HitlWiring {
     /** Tool name → its `@HumanInTheLoop` config. A tool absent here is NOT gated. */
     gated: Map<string, HumanInTheLoopOptions>;
     /** Push the approval-required event into the agent stream (the translator emits the chunk). */
     emit: (event: ApprovalRequiredEvent) => void;
-    /** Await the human decision for `approvalId`; resolves true=approve, false=deny (or timeout). */
-    awaitApproval: (approvalId: string, opts: HumanInTheLoopOptions) => Promise<boolean>;
+    /**
+     * Await the human decision for `approvalId`; resolves approve/deny (or timeout). M20 — may resolve
+     * a bare boolean (legacy) OR a {@link HitlDecision} carrying an approver `reason` + `payload`.
+     */
+    awaitApproval: (approvalId: string, opts: HumanInTheLoopOptions, toolName: string) => Promise<boolean | HitlDecision>;
 }
 
 /**
@@ -921,6 +1183,34 @@ declare const ladderReflectionStrategy: ReflectionStrategy;
  */
 declare const noopReflectionStrategy: ReflectionStrategy;
 
+/**
+ * runReflectiveLoop — the multi-round reflective driver that gives `@MainLoop`
+ * its runtime (closes the metadata-only gap, V4-A / plan ADR D2).
+ *
+ * Per round it consumes ONE SDK stream turn (the model call stays in the SDK —
+ * the factory is `createSdkAgentStream(...)`, injected for testability), derives
+ * a {@link LoopOutcome}, asks the {@link ReflectionStrategy} for feedback, then
+ * the {@link LoopStrategy} whether to continue. Bounded by `maxIterations`
+ * (forced terminal at the ceiling — never an infinite loop). The bridge owns the
+ * loop; the SDK owns the model call (sdk-runtime.md / ADR 0031 — no second runtime).
+ *
+ * `runReflectiveLoop` is INTERNAL (not re-exported from the package barrel,
+ * Drawback #4) — consumed by `delegate()` (T2.2) and `AgentRunner` (T3.1).
+ *
+ * referencia: knowledge-base/references/mastra agent.ts (re-enter the loop with feedback).
+ */
+
+/** One SDK stream turn: `createSdkAgentStream(...)` returns this shape. */
+/**
+ * Opens one round's SDK stream. `opts.disableTools` (step-cap force-close) asks the factory to
+ * gate tools OFF for THIS round (the SDK adapter maps it to `tool_choice:"none"` at send-time, so a
+ * cached agent — whose tools can't be un-registered — is still forced to a text summary). Optional +
+ * ignored by injected test factories ⇒ backward-compatible.
+ */
+type RoundStreamFactory = (message: string, sessionId: string, opts?: {
+    disableTools?: boolean;
+}) => AsyncIterable<StreamEvent>;
+
 /**
  * Multi-agent orchestration runtime.
  *
@@ -967,6 +1257,27 @@ interface DelegateOptions {
     reflection?: ReflectionStrategy;
     /** Per-run loop-ceiling override (`?? SubAgent @MainLoop maxIterations`). */
     maxIterations?: number;
+    /**
+     * Called BEFORE the sub-agent runs. Returns the input the sub-agent will receive — return
+     * `ctx.input` unchanged, or a rewritten string (e.g. inject a persona). A transform, not a veto.
+     */
+    onDelegationStart?: (ctx: {
+        subAgent: string;
+        input: string;
+    }) => string | Promise<string>;
+    /**
+     * Called AFTER the sub-agent completes. Returns the result the supervisor sees — return
+     * `ctx.result` unchanged, or a transformed one (e.g. redact, score, re-wrap).
+     */
+    onDelegationComplete?: (ctx: {
+        subAgent: string;
+        result: DelegationResult;
+    }) => DelegationResult | Promise<DelegationResult>;
+    /**
+     * Injected stream factory (parity with `AgentRunnerRunOptions.streamFactory`) — drives the loop
+     * directly instead of the SDK adapter (tests / custom transport). Absent ⇒ `createSdkAgentStream`.
+     */
+    streamFactory?: RoundStreamFactory;
 }
 /**
  * Delegate a task to a sub-agent and collect its result.
@@ -982,6 +1293,266 @@ interface DelegateOptions {
  */
 declare function delegate(SubAgentClass: Function, message: string, opts?: DelegateOptions): Promise<DelegationResult>;
 
+/**
+ * M10 (theokit-ai-first) — createToolHooksPlugin: `beforeToolCall` / `afterToolCall` observability.
+ *
+ * ADR-0040 § D2: a HOME/BOUNDARY plugin over the SDK's OWN `pre_tool_call` / `post_tool_call` /
+ * `pre_llm_call` / `post_llm_call` / `pre_user_send` hooks (mirrors {@link createHitlPlugin}). It
+ * calls no LLM, dispatches no tool, runs no second loop — the SDK owns the run. `beforeToolCall`
+ * may VETO a call; `afterToolCall` observes the result.
+ *
+ * M19 — `processInput` completes the input side of the processor pipeline, wired to the SDK
+ * `pre_user_send` hook. NOTE (honest ceiling): the SDK does NOT let a plugin mutate the raw
+ * prompt/stream; `pre_user_send` lets a handler INJECT derived context (`recalledContext`) BEFORE
+ * the model. So `processInput` receives the prompt and returns an optional string, which the SDK
+ * injects as a `<memory-context>` block ahead of the prompt. The api-error side of M19 lives in
+ * `./api-error-handler` (a sibling factory — the SDK owns retry and exposes no error hook).
+ */
+/** A tool call about to run (mirrored from the SDK `pre_tool_call` context — type-only). */
+interface BeforeToolCallContext {
+    name: string;
+    args: Record<string, unknown>;
+}
+/** A veto returned from `beforeToolCall` — blocks the tool; the SDK surfaces `message` to the model. */
+interface ToolCallVeto {
+    block: true;
+    message: string;
+}
+/** A completed tool call (mirrored from the SDK `post_tool_call` context — type-only). */
+interface AfterToolCallContext {
+    name: string;
+    result: unknown;
+}
+interface ToolHooks {
+    /** Observe (and optionally VETO) every tool call before it runs. Return a veto or nothing. */
+    beforeToolCall?: (ctx: BeforeToolCallContext) => ToolCallVeto | undefined | Promise<ToolCallVeto | undefined>;
+    /** Observe every tool call's result after it runs. */
+    afterToolCall?: (ctx: AfterToolCallContext) => void | Promise<void>;
+    /**
+     * M10 — observe every LLM turn BEFORE it runs (SDK `pre_llm_call`). Observability only — the
+     * SDK's LLM-call context carries `{ agentId, runId, iteration }`, not the mutable request body.
+     */
+    beforeLLMCall?: (ctx: LLMCallContext) => void | Promise<void>;
+    /** M10 — observe every LLM turn AFTER it completes (SDK `post_llm_call`). Observability only. */
+    afterLLMCall?: (ctx: LLMCallContext) => void | Promise<void>;
+    /**
+     * M19 — pre-process the user input BEFORE the model runs (SDK `pre_user_send`). Receives the
+     * prompt; return a string to INJECT as derived context ahead of it (the SDK wraps it in a
+     * `<memory-context>` block), or `undefined` to inject nothing. The SDK does not expose raw-prompt
+     * mutation to plugins, so this is additive, not a rewrite of the caller's stream.
+     */
+    processInput?: (ctx: ProcessInputContext) => string | undefined | Promise<string | undefined>;
+}
+/** Context of the input seam (mirrors the SDK `PreUserSendContext`). */
+interface ProcessInputContext {
+    prompt: string;
+    agentId: string;
+    runId: string;
+}
+/** Context of an LLM turn (mirrors the SDK `LlmCallContext` for `pre_llm_call`/`post_llm_call`). */
+interface LLMCallContext {
+    agentId: string;
+    runId: string;
+    /** 0-based iteration index of the current turn, when available. */
+    iteration?: number;
+}
+/**
+ * Minimal SDK hook context (type-only — no runtime import, keeps the SDK peer optional). Tool hooks
+ * carry `name`/`args`/`result`; LLM hooks carry `iteration`. All optional so one shape covers both.
+ */
+interface ToolHookRawContext {
+    agentId: string;
+    runId: string;
+    name?: string;
+    args?: Record<string, unknown>;
+    result?: unknown;
+    iteration?: number;
+    /** M19 — the user prompt, present on the `pre_user_send` seam. */
+    prompt?: string;
+}
+interface ToolHooksPluginContext {
+    on(hook: string, handler: (ctx: ToolHookRawContext) => unknown): void;
+}
+interface ToolHooksPlugin {
+    name: string;
+    /** SDK `BasePlugin.version` — required by the `@theokit/sdk` Plugin contract. */
+    version: string;
+    /**
+     * SDK Plugin discriminator. MUST be `'general'` — the SDK's `isCodePlugin()` gate filters out any
+     * plugin object lacking `kind: 'general'` (a `register()`-only object is silently dropped and its
+     * hooks NEVER fire). Regression guard for the M10/M19 latent E2E bug.
+     */
+    kind: 'general';
+    register(ctx: ToolHooksPluginContext): void;
+}
+/**
+ * Build the tool-hooks plugin. Registers ONLY the hooks provided (inert when none) so it adds no
+ * overhead unless used. The returned object is a structural `@theokit/sdk` `Plugin`.
+ */
+declare function createToolHooksPlugin(hooks: ToolHooks): ToolHooksPlugin;
+
+/**
+ * M19 (theokit-ai-first) — `processApiError`: app-level fallback around an agent run.
+ *
+ * ADR-0040 § D2 + sdk-runtime.md: the `@theokit/sdk` runtime OWNS the LLM call AND its own
+ * retry/backoff, and exposes NO api-error hook to plugins. This module is therefore NOT a plugin —
+ * it is a thin app-boundary wrapper (the M19 DoD explicitly allows "a sibling factory"). It
+ * RE-INVOKES the caller's run thunk on error; it never calls an LLM, never dispatches a tool, never
+ * reimplements retry inside the loop (G2). The SDK's internal retry runs first; this handles what
+ * survives it — a second, app-owned fallback layer (the M19 top-risk note: "app-level fallback, not
+ * a second retry loop" inside the SDK).
+ */
+/** What the app decides after seeing an API error. */
+interface ApiErrorDecision<R = unknown> {
+    /** Re-invoke the run thunk once more. Ignored past `maxAttempts`. */
+    retry?: boolean;
+    /**
+     * A value to return INSTEAD of rethrowing, when `retry` is false/absent. Lets the app degrade
+     * gracefully (e.g. a canned response) rather than surface the raw provider error.
+     */
+    fallback?: R;
+}
+/** Context handed to the app's error handler for each failed attempt (1-based). */
+interface ApiErrorContext {
+    error: unknown;
+    /** 1-based attempt number that just failed. */
+    attempt: number;
+}
+interface ApiErrorPolicy<R = unknown> {
+    /** Called once per failed attempt. Return `{ retry: true }` to try again, or a `{ fallback }`. */
+    processApiError: (ctx: ApiErrorContext) => ApiErrorDecision<R> | Promise<ApiErrorDecision<R>>;
+    /**
+     * Hard cap on total attempts (defaults to 3). A backstop so a handler that always returns
+     * `{ retry: true }` cannot loop forever (mirrors the SDK's own bounded retry philosophy).
+     */
+    maxAttempts?: number;
+}
+/**
+ * Run `thunk`, applying the app's `processApiError` policy on failure. Returns the run's value on
+ * success, the policy's `fallback` when it declines to retry with one, or rethrows the last error.
+ *
+ * `thunk` is typically `() => agent.send(msg).then((r) => r.wait())` — a whole SDK run. On retry the
+ * thunk is re-invoked from scratch (a fresh run), never resumed mid-loop.
+ */
+declare function runWithApiErrorHandling<R>(thunk: () => Promise<R>, policy: ApiErrorPolicy<R>): Promise<R>;
+/**
+ * Build a reusable guard bound to one policy. `const guard = createApiErrorHandler({ ... })` then
+ * `guard(() => agent.send(m).then((r) => r.wait()))` — the same policy applied to many runs.
+ */
+declare function createApiErrorHandler<R = unknown>(policy: ApiErrorPolicy<R>): (thunk: () => Promise<R>) => Promise<R>;
+
+/**
+ * M25 (theokit-ai-first) — background delegation + task-completion scoring.
+ *
+ * Two THIN wrappers over the M12 `delegate` (ADR 0038/0040): no new orchestration engine, no second
+ * loop, no new store. `delegateBackground` kicks off a sub-agent without blocking the supervisor and
+ * hands back a handle to await later. `delegateWithScoring` runs `delegate`, scores the result with
+ * an injected scorer, and re-delegates with the scorer's feedback until it passes or `maxRounds` is
+ * hit. The `delegate` implementation is injectable (`delegateFn`) so this is testable without a
+ * SubAgent class or an LLM — and so it NEVER re-implements the delegation runtime.
+ */
+
+/** The delegation primitive both wrappers drive. Defaults to the M12 {@link delegate}. */
+type DelegateFn = (subAgent: Function, message: string, opts?: DelegateOptions) => Promise<DelegationResult>;
+/** A running background delegation the supervisor can await/poll later. */
+interface BackgroundDelegation {
+    /** Await the sub-agent's result (or rejection). Idempotent — returns the same settled promise. */
+    wait(): Promise<DelegationResult>;
+    /** Whether the underlying delegation has resolved or rejected. */
+    settled(): boolean;
+}
+/**
+ * Start a sub-agent WITHOUT blocking the supervisor. Returns immediately with a handle; the
+ * supervisor keeps working and calls `wait()` when it needs the result. A thin async wrapper over
+ * `delegate` — not a scheduler (Top-risk 1). Rejections are still observable via `wait()`.
+ */
+declare function delegateBackground(subAgent: Function, message: string, opts?: DelegateOptions & {
+    delegateFn?: DelegateFn;
+}): BackgroundDelegation;
+/** A scorer's verdict on a sub-agent result. `feedback` is fed back into the next round on failure. */
+interface ScoreVerdict {
+    pass: boolean;
+    /** Optional numeric score (0..1) for logging/telemetry. */
+    score?: number;
+    /** Guidance appended to the next delegation when `pass` is false. */
+    feedback?: string;
+}
+/** Scores a sub-agent result. Opt-in (Top-risk 2) — the caller supplies it, and pays its cost. */
+type Scorer = (result: DelegationResult) => ScoreVerdict | Promise<ScoreVerdict>;
+/** The outcome of a scored delegation: the final result plus the per-round verdict trail. */
+interface ScoredDelegation {
+    result: DelegationResult;
+    /** Rounds actually run (1..maxRounds). */
+    rounds: number;
+    /** Whether the final round passed the scorer. */
+    passed: boolean;
+    /** The verdict from each round, in order. */
+    verdicts: ScoreVerdict[];
+}
+/**
+ * Run `delegate`, score the result, and re-delegate with the scorer's feedback until it passes or
+ * `maxRounds` is reached. Each round is ONE `delegate` call — no second loop, no new store. Returns
+ * the final result (passing, or the last attempt) with the per-round verdict trail.
+ */
+declare function delegateWithScoring(subAgent: Function, message: string, opts: DelegateOptions & {
+    scorer: Scorer;
+    maxRounds?: number;
+    delegateFn?: DelegateFn;
+    feedbackTemplate?: (message: string, feedback: string) => string;
+}): Promise<ScoredDelegation>;
+
+/**
+ * M24 (ADR-0041) — MCP follow-ups, framework-side layer over the `@MCP` config (ADR-0040 § D2).
+ *
+ * Three home/boundary helpers that compose with the existing `@MCP` / `defineAgent` surfaces — the
+ * SDK still owns MCP server EXECUTION (`Agent.create({ mcpServers })`); these only shape the config:
+ *  - `resolveMcpServers` — per-request resolver so multi-tenant apps hand different MCP creds to
+ *    different callers (mirrors the M13 skills resolver);
+ *  - `mcpRegistry` — build a server config for a known MCP registry (Composio / mcp.run);
+ *  - `mcpToolApprovals` — mark MCP tools for approval, producing the M14 `approvals` entries so a
+ *    gated MCP tool routes through the (E2E-proven) HITL flow.
+ */
+
+/** The request context handed to an MCP resolver (the M7 run-context — opaque per-request data). */
+type McpRequestContext = Record<string, unknown>;
+/**
+ * How the MCP server set is chosen:
+ * - a map      — static `@MCP`-style config.
+ * - a function — resolved per request from the {@link McpRequestContext} (sync or async).
+ */
+type McpSelection = McpServersMap | ((ctx: McpRequestContext) => McpServersMap | Promise<McpServersMap>);
+/**
+ * Resolve the MCP servers for a request. Returns `undefined` when no selection is given. Fails fast
+ * if a resolver returns a non-object (error-handling.md). Multi-tenant apps pass a function that
+ * reads per-user credentials from `ctx`.
+ */
+declare function resolveMcpServers(selection: McpSelection | undefined, ctx: McpRequestContext): Promise<McpServersMap | undefined>;
+/** Config for {@link mcpRegistry}. `registry` selects a known provider. */
+interface McpRegistryConfig {
+    registry: 'composio' | 'mcp.run';
+    /** The registry API key (kept in the server's env, never logged). */
+    apiKey: string;
+    /** Composio: the app toolkits to expose (e.g. `['github', 'slack']`). */
+    apps?: string[];
+    /** mcp.run: the profile to connect. */
+    profile?: string;
+}
+/**
+ * Build an {@link McpServersMap} for a known MCP registry. Emits an `npx`-launched server config with
+ * the API key in `env`. Documented registries: **Composio** (`@composio/mcp`) and **mcp.run**
+ * (`@mcp.run/cli`). Other registries are wired manually via a raw `@MCP` entry.
+ */
+declare function mcpRegistry(config: McpRegistryConfig): McpServersMap;
+/** An MCP tool's approval spec: full {@link HumanInTheLoopOptions} or a bare question string. */
+type McpApprovalSpec = HumanInTheLoopOptions | string;
+/**
+ * Mark MCP tools for human approval (`requireToolApproval`). Returns the `Record<toolName,
+ * HumanInTheLoopOptions>` shape the M14 `defineAgent({ approvals })` map consumes — so a gated MCP
+ * tool routes through the same (E2E-proven) HITL flow as a native gated tool. A bare string is
+ * shorthand for `{ question }`.
+ */
+declare function mcpToolApprovals(specs: Record<string, McpApprovalSpec>): Record<string, HumanInTheLoopOptions>;
+
 /**
  * Agent manifest generator — build-time JSON describing all agents, tools, guards, policies.
  *
@@ -1065,4 +1636,4 @@ declare function agentsPlugin(opts: AgentsPluginOptions): {
     register(app: PluginApp): void;
 };
 
-export { buildModelSelection as $, AGENT_BRAND as A, BudgetExceededError as B, type CompiledAgentOptions as C, type DelegationResult as D, type ErrorEvent as E, type FileEditEvent as F, type LoopOutcome as G, type LoopStrategyConfig as H, type InferAgentInput as I, type ReflectionContext as J, type ReflectionResult as K, type LoopStrategy as L, type ReflectionStrategyConfig as M, type RunStartedEvent as N, type SdkMessage as O, type PartialToolCallEvent as P, type Segment as Q, type ReflectionStrategy as R, type StreamEvent as S, type StateUpdateEvent as T, type TextDeltaEvent as U, type ThinkingEvent as V, type ToolCallEvent as W, type ToolResultEvent as X, type ToolWalkResult as Y, type ToolboxWalkResult as Z, agentsPlugin as _, type CompiledTool as a, compileAgent as a0, compileAgentDefinition as a1, compileAgentModule as a2, compileContextWindow as a3, compileProjectContext as a4, compileSkills as a5, compileTools as a6, createAgentExecutionContext as a7, createSdkAgentStream as a8, createThinkTagExtractor as a9, defineAgent as aa, delegate as ab, extractThinkTagStream as ac, generateAgentManifest as ad, generateAgentRoutes as ae, isAgentContext as af, isAgentDefinition as ag, isApprovalRequired as ah, isDone as ai, isError as aj, isPartialToolCall as ak, isTextDelta as al, isToolCall as am, isToolResult as an, ladderReflectionStrategy as ao, loopStrategyConfigSchema as ap, noopReflectionStrategy as aq, projectContextMetadataOnlyKnobs as ar, reflectionStrategyConfigSchema as as, resolveLoopStrategy as at, streamAgentResponse as au, streamAgentUIMessages as av, translateSdkEvent as aw, translateToUIMessageStream as ax, validateUniqueRoutes as ay, walkAgentMetadata as az, type AgentDefinition as b, AgentDefinitionError as c, type AgentExecutionContext as d, type AgentManifest as e, type AgentManifestEntry as f, type AgentManifestTool as g, type AgentRoute as h, type AgentRouteContext as i, type AgentRunInfo as j, type AgentStreamEvent as k, type AgentWalkResult as l, AgentWarningCode as m, type AgentsPluginOptions as n, type ApprovalRequiredEvent as o, type ArtifactChunkEvent as p, type ArtifactStartEvent as q, type CheckpointSavedEvent as r, type CompiledContextWindow as s, DEFAULT_MAX_ITERATIONS as t, type DefineAgentConfig as u, type DelegateOptions as v, DelegationError as w, type DoneEvent as x, type IterationEvent as y, type LoopFinishReason as z };
+export { type LoopFinishReason as $, type AgentManifestEntry as A, type BackgroundDelegation as B, type CompiledAgentOptions as C, type DelegationResult as D, type CompiledContextWindow as E, type ContextualTool as F, type Guardrail as G, CostBudgetExceededError as H, DEFAULT_MAX_ITERATIONS as I, type DefineAgentConfig as J, type DelegateFn as K, type LoopStrategy as L, type DelegateOptions as M, DelegationError as N, type DoneEvent as O, type ErrorEvent as P, type FileEditEvent as Q, type ReflectionStrategy as R, type StreamEvent as S, type GuardrailAction as T, type GuardrailPhase as U, type GuardrailResult as V, GuardrailViolationError as W, type InferAgentInput as X, type InferAgentToolNames as Y, type IterationEvent as Z, type LLMCallContext as _, type CompiledTool as a, mcpRegistry as a$, type LoopOutcome as a0, type LoopStrategyConfig as a1, type McpApprovalSpec as a2, type McpRegistryConfig as a3, type McpRequestContext as a4, type McpSelection as a5, type PartialToolCallEvent as a6, type ProcessInputContext as a7, type ReflectionContext as a8, type ReflectionResult as a9, compileProjectContext as aA, compileSkills as aB, compileTools as aC, contextualTool as aD, createAgentExecutionContext as aE, createApiErrorHandler as aF, createSdkAgentStream as aG, createThinkTagExtractor as aH, createToolHooksPlugin as aI, defineAgent as aJ, delegate as aK, delegateBackground as aL, delegateWithScoring as aM, extractThinkTagStream as aN, generateAgentManifest as aO, generateAgentRoutes as aP, isAgentContext as aQ, isAgentDefinition as aR, isApprovalRequired as aS, isDone as aT, isError as aU, isPartialToolCall as aV, isTextDelta as aW, isToolCall as aX, isToolResult as aY, ladderReflectionStrategy as aZ, loopStrategyConfigSchema as a_, type ReflectionStrategyConfig as aa, type RunStartedEvent as ab, type ScoreVerdict as ac, type ScoredDelegation as ad, type Scorer as ae, type SdkMessage as af, type Segment as ag, type SkillsRequestContext as ah, type SkillsSelection as ai, type StateUpdateEvent as aj, type TextDeltaEvent as ak, type ThinkingEvent as al, type ToolCallEvent as am, type ToolCallVeto as an, type ToolHooks as ao, type ToolHooksPlugin as ap, type ToolResultEvent as aq, type ToolWalkResult as ar, type ToolboxWalkResult as as, agent as at, agentsPlugin as au, buildModelSelection as av, compileAgent as aw, compileAgentDefinition as ax, compileAgentModule as ay, compileContextWindow as az, type RoundStreamFactory as b, mcpToolApprovals as b0, noopReflectionStrategy as b1, projectContextMetadataOnlyKnobs as b2, reflectionStrategyConfigSchema as b3, resolveEnabledSkills as b4, resolveLoopStrategy as b5, resolveMcpServers as b6, runWithApiErrorHandling as b7, streamAgentResponse as b8, streamAgentUIMessages as b9, translateSdkEvent as ba, translateToUIMessageStream as bb, validateUniqueRoutes as bc, walkAgentMetadata as bd, AGENT_BRAND as c, type AfterToolCallContext as d, type AgentBuilder as e, type AgentDefinition as f, AgentDefinitionError as g, type AgentExecutionContext as h, type AgentManifest as i, type AgentManifestTool as j, type AgentRoute as k, type AgentRouteContext as l, type AgentRunInfo as m, type AgentStreamEvent as n, type AgentWalkResult as o, AgentWarningCode as p, type AgentsPluginOptions as q, type ApiErrorContext as r, type ApiErrorDecision as s, type ApiErrorPolicy as t, type ApprovalRequiredEvent as u, type ArtifactChunkEvent as v, type ArtifactStartEvent as w, type BeforeToolCallContext as x, BudgetExceededError as y, type CheckpointSavedEvent as z };