@theokit/agents 0.31.0 → 0.32.0

package/dist/{bridge-entry-DtDotZGW.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';
@@ -420,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 {
@@ -914,14 +916,27 @@ declare function agent(): AgentBuilder;
  * 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, toolName: string) => 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>;
 }
 
 /**
@@ -1281,11 +1296,17 @@ declare function delegate(SubAgentClass: Function, message: string, opts?: Deleg
 /**
  * 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`
- * 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. The processor pipeline's remaining lifecycle hooks (LLM request/response) live in the
- * SDK; this ships the two tool-boundary hooks the framework can wire today.
+ * 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 {
@@ -1314,6 +1335,19 @@ interface ToolHooks {
     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 {
@@ -1333,12 +1367,22 @@ interface ToolHookRawContext {
     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;
 }
 /**
@@ -1347,6 +1391,168 @@ interface ToolHooksPlugin {
  */
 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.
  *
@@ -1430,4 +1636,4 @@ declare function agentsPlugin(opts: AgentsPluginOptions): {
     register(app: PluginApp): void;
 };
 
-export { type ReflectionResult as $, type AgentManifestEntry as A, type BeforeToolCallContext as B, type CompiledAgentOptions as C, type DelegationResult as D, type DefineAgentConfig as E, type DelegateOptions as F, type Guardrail as G, DelegationError as H, type DoneEvent as I, type ErrorEvent as J, type FileEditEvent as K, type LoopStrategy as L, type GuardrailAction as M, type GuardrailPhase as N, type GuardrailResult as O, GuardrailViolationError as P, type InferAgentInput as Q, type ReflectionStrategy as R, type StreamEvent as S, type InferAgentToolNames as T, type IterationEvent as U, type LLMCallContext as V, type LoopFinishReason as W, type LoopOutcome as X, type LoopStrategyConfig as Y, type PartialToolCallEvent as Z, type ReflectionContext as _, type CompiledTool as a, type ReflectionStrategyConfig as a0, type RunStartedEvent as a1, type SdkMessage as a2, type Segment as a3, type SkillsRequestContext as a4, type SkillsSelection as a5, type StateUpdateEvent as a6, type TextDeltaEvent as a7, type ThinkingEvent as a8, type ToolCallEvent as a9, isAgentContext as aA, isAgentDefinition as aB, isApprovalRequired as aC, isDone as aD, isError as aE, isPartialToolCall as aF, isTextDelta as aG, isToolCall as aH, isToolResult as aI, ladderReflectionStrategy as aJ, loopStrategyConfigSchema as aK, noopReflectionStrategy as aL, projectContextMetadataOnlyKnobs as aM, reflectionStrategyConfigSchema as aN, resolveEnabledSkills as aO, resolveLoopStrategy as aP, streamAgentResponse as aQ, streamAgentUIMessages as aR, translateSdkEvent as aS, translateToUIMessageStream as aT, validateUniqueRoutes as aU, walkAgentMetadata as aV, type ToolCallVeto as aa, type ToolHooks as ab, type ToolHooksPlugin as ac, type ToolResultEvent as ad, type ToolWalkResult as ae, type ToolboxWalkResult as af, agent as ag, agentsPlugin as ah, buildModelSelection as ai, compileAgent as aj, compileAgentDefinition as ak, compileAgentModule as al, compileContextWindow as am, compileProjectContext as an, compileSkills as ao, compileTools as ap, contextualTool as aq, createAgentExecutionContext as ar, createSdkAgentStream as as, createThinkTagExtractor as at, createToolHooksPlugin as au, defineAgent as av, delegate as aw, extractThinkTagStream as ax, generateAgentManifest as ay, generateAgentRoutes as az, type RoundStreamFactory as b, 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 ApprovalRequiredEvent as r, type ArtifactChunkEvent as s, type ArtifactStartEvent as t, BudgetExceededError as u, type CheckpointSavedEvent as v, type CompiledContextWindow as w, type ContextualTool as x, CostBudgetExceededError as y, DEFAULT_MAX_ITERATIONS 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 };

package/dist/bridge.d.ts

@@ -1,6 +1,6 @@
-export { c as AGENT_BRAND, d as AfterToolCallContext, e as AgentBuilder, f as AgentDefinition, g as AgentDefinitionError, h as AgentExecutionContext, i as AgentManifest, A as AgentManifestEntry, j as AgentManifestTool, k as AgentRoute, l as AgentRouteContext, m as AgentRunInfo, n as AgentStreamEvent, o as AgentWalkResult, p as AgentWarningCode, q as AgentsPluginOptions, r as ApprovalRequiredEvent, s as ArtifactChunkEvent, t as ArtifactStartEvent, B as BeforeToolCallContext, u as BudgetExceededError, v as CheckpointSavedEvent, C as CompiledAgentOptions, w as CompiledContextWindow, a as CompiledTool, x as ContextualTool, E as DefineAgentConfig, F as DelegateOptions, H as DelegationError, D as DelegationResult, I as DoneEvent, J as ErrorEvent, K as FileEditEvent, Q as InferAgentInput, T as InferAgentToolNames, U as IterationEvent, V as LLMCallContext, Z as PartialToolCallEvent, a1 as RunStartedEvent, a2 as SdkMessage, a3 as Segment, a6 as StateUpdateEvent, S as StreamEvent, a7 as TextDeltaEvent, a8 as ThinkingEvent, a9 as ToolCallEvent, aa as ToolCallVeto, ab as ToolHooks, ac as ToolHooksPlugin, ad as ToolResultEvent, ae as ToolWalkResult, af as ToolboxWalkResult, ag as agent, ah as agentsPlugin, ai as buildModelSelection, aj as compileAgent, ak as compileAgentDefinition, al as compileAgentModule, am as compileContextWindow, an as compileProjectContext, ao as compileSkills, ap as compileTools, aq as contextualTool, ar as createAgentExecutionContext, as as createSdkAgentStream, at as createThinkTagExtractor, au as createToolHooksPlugin, av as defineAgent, aw as delegate, ax as extractThinkTagStream, ay as generateAgentManifest, az as generateAgentRoutes, aA as isAgentContext, aB as isAgentDefinition, aC as isApprovalRequired, aD as isDone, aE as isError, aF as isPartialToolCall, aG as isTextDelta, aH as isToolCall, aI as isToolResult, aM as projectContextMetadataOnlyKnobs, aQ as streamAgentResponse, aR as streamAgentUIMessages, aS as translateSdkEvent, aT as translateToUIMessageStream, aU as validateUniqueRoutes, aV as walkAgentMetadata } from './bridge-entry-DtDotZGW.js';
+export { c as AGENT_BRAND, d as AfterToolCallContext, e as AgentBuilder, f as AgentDefinition, g as AgentDefinitionError, h as AgentExecutionContext, i as AgentManifest, A as AgentManifestEntry, j as AgentManifestTool, k as AgentRoute, l as AgentRouteContext, m as AgentRunInfo, n as AgentStreamEvent, o as AgentWalkResult, p as AgentWarningCode, q as AgentsPluginOptions, r as ApiErrorContext, s as ApiErrorDecision, t as ApiErrorPolicy, u as ApprovalRequiredEvent, v as ArtifactChunkEvent, w as ArtifactStartEvent, B as BackgroundDelegation, x as BeforeToolCallContext, y as BudgetExceededError, z as CheckpointSavedEvent, C as CompiledAgentOptions, E as CompiledContextWindow, a as CompiledTool, F as ContextualTool, J as DefineAgentConfig, K as DelegateFn, M as DelegateOptions, N as DelegationError, D as DelegationResult, O as DoneEvent, P as ErrorEvent, Q as FileEditEvent, X as InferAgentInput, Y as InferAgentToolNames, Z as IterationEvent, _ as LLMCallContext, a2 as McpApprovalSpec, a3 as McpRegistryConfig, a4 as McpRequestContext, a5 as McpSelection, a6 as PartialToolCallEvent, a7 as ProcessInputContext, ab as RunStartedEvent, ac as ScoreVerdict, ad as ScoredDelegation, ae as Scorer, af as SdkMessage, ag as Segment, aj as StateUpdateEvent, S as StreamEvent, ak as TextDeltaEvent, al as ThinkingEvent, am as ToolCallEvent, an as ToolCallVeto, ao as ToolHooks, ap as ToolHooksPlugin, aq as ToolResultEvent, ar as ToolWalkResult, as as ToolboxWalkResult, at as agent, au as agentsPlugin, av as buildModelSelection, aw as compileAgent, ax as compileAgentDefinition, ay as compileAgentModule, az as compileContextWindow, aA as compileProjectContext, aB as compileSkills, aC as compileTools, aD as contextualTool, aE as createAgentExecutionContext, aF as createApiErrorHandler, aG as createSdkAgentStream, aH as createThinkTagExtractor, aI as createToolHooksPlugin, aJ as defineAgent, aK as delegate, aL as delegateBackground, aM as delegateWithScoring, aN as extractThinkTagStream, aO as generateAgentManifest, aP as generateAgentRoutes, aQ as isAgentContext, aR as isAgentDefinition, aS as isApprovalRequired, aT as isDone, aU as isError, aV as isPartialToolCall, aW as isTextDelta, aX as isToolCall, aY as isToolResult, a$ as mcpRegistry, b0 as mcpToolApprovals, b2 as projectContextMetadataOnlyKnobs, b6 as resolveMcpServers, b7 as runWithApiErrorHandling, b8 as streamAgentResponse, b9 as streamAgentUIMessages, ba as translateSdkEvent, bb as translateToUIMessageStream, bc as validateUniqueRoutes, bd as walkAgentMetadata } from './bridge-entry-1r1DL-mS.js';
 import '@theokit/http';
-import './skills-Dx_KJ6Eg.js';
+import './skills-DvI_LYWZ.js';
 import '@theokit/sdk';
 import 'zod';
 import 'ai';

package/dist/bridge.js

@@ -16,11 +16,14 @@ import {
   compileTools,
   contextualTool,
   createAgentExecutionContext,
+  createApiErrorHandler,
   createSdkAgentStream,
   createThinkTagExtractor,
   createToolHooksPlugin,
   defineAgent,
   delegate,
+  delegateBackground,
+  delegateWithScoring,
   extractThinkTagStream,
   generateAgentManifest,
   generateAgentRoutes,
@@ -33,15 +36,19 @@ import {
   isTextDelta,
   isToolCall,
   isToolResult,
+  mcpRegistry,
+  mcpToolApprovals,
   projectContextMetadataOnlyKnobs,
+  resolveMcpServers,
+  runWithApiErrorHandling,
   streamAgentResponse,
   streamAgentUIMessages,
   translateSdkEvent,
   translateToUIMessageStream,
   validateUniqueRoutes,
   walkAgentMetadata
-} from "./chunk-BWYBOMKR.js";
-import "./chunk-FI6ZG2YP.js";
+} from "./chunk-5VIRIPVV.js";
+import "./chunk-3AX6M5TF.js";
 import "./chunk-7QVYU63E.js";
 export {
   AGENT_BRAND,
@@ -61,11 +68,14 @@ export {
   compileTools,
   contextualTool,
   createAgentExecutionContext,
+  createApiErrorHandler,
   createSdkAgentStream,
   createThinkTagExtractor,
   createToolHooksPlugin,
   defineAgent,
   delegate,
+  delegateBackground,
+  delegateWithScoring,
   extractThinkTagStream,
   generateAgentManifest,
   generateAgentRoutes,
@@ -78,7 +88,11 @@ export {
   isTextDelta,
   isToolCall,
   isToolResult,
+  mcpRegistry,
+  mcpToolApprovals,
   projectContextMetadataOnlyKnobs,
+  resolveMcpServers,
+  runWithApiErrorHandling,
   streamAgentResponse,
   streamAgentUIMessages,
   translateSdkEvent,

package/dist/{chunk-FI6ZG2YP.js → chunk-3AX6M5TF.js}

@@ -311,4 +311,4 @@ export {
   Mixin,
   getMixins
 };
-//# sourceMappingURL=chunk-FI6ZG2YP.js.map
+//# sourceMappingURL=chunk-3AX6M5TF.js.map

package/dist/chunk-3AX6M5TF.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/metadata/index.ts","../src/metadata/keys.ts","../src/decorators/agent.ts","../src/decorators/policies.ts","../src/decorators/observability.ts","../src/decorators/gateway.ts","../src/decorators/sub-agents.ts","../src/decorators/memory.ts","../src/decorators/skills.ts","../src/decorators/mcp.ts","../src/decorators/human-in-the-loop.ts","../src/decorators/context-window.ts","../src/decorators/compaction.ts","../src/decorators/checkpoint.ts","../src/decorators/project-context.ts","../src/decorators/mixin.ts"],"sourcesContent":["// Re-export setMeta/getMeta from http-decorators (DRY — single metadata engine)\n// Relative path for workspace-local usage; vitest resolves via alias\nexport { setMeta, getMeta } from '@theokit/http'\n\nexport * from './keys.js'\n","/** Symbol.for metadata keys for agent decorators — cross-module safe with SWC loader. */\n\nexport const AGENT_CONFIG = Symbol.for('theokit:agents:config')\nexport const AGENT_MAIN_LOOP = Symbol.for('theokit:agents:main-loop')\nexport const TOOLBOX_CONFIG = Symbol.for('theokit:agents:toolbox')\nexport const TOOL_CONFIG = Symbol.for('theokit:agents:tool')\nexport const TOOL_METHODS = Symbol.for('theokit:agents:tool-methods')\n","/**\n * @Agent() — marks a class as an AI agent controller.\n *\n * Convention over configuration:\n *   @Agent()                    → name + route inferred from class name\n *   @Agent({ model: '...' })   → name + route inferred, model explicit\n *   @Agent({ name, route, model }) → fully explicit\n *\n * @example\n * ```ts\n * // Convention: SupportAgent → name: 'support', route: '/api/agents/support'\n * @Agent()\n * class SupportAgent { ... }\n *\n * // Partial: infer name + route, set model\n * @Agent({ model: 'claude-sonnet-4-5-20250929' })\n * class SupportAgent { ... }\n *\n * // Explicit: full control\n * @Agent({ name: 'support-agent', route: '/api/agents/support', model: '...' })\n * class SupportAgent { ... }\n * ```\n */\nimport { setMeta, getMeta, AGENT_CONFIG } from '../metadata/index.js'\nimport type { AgentOptions } from '../types.js'\n\n/**\n * Infer agent name and route from class name (Rails-style convention).\n *\n * SupportAgent     → name: 'support',      route: '/api/agents/support'\n * ResearchAgent    → name: 'research',     route: '/api/agents/research'\n * CodeReviewAgent  → name: 'code-review',  route: '/api/agents/code-review'\n */\nfunction inferAgentMeta(className: string): { name: string; route: string } {\n  const stripped = className.replace(/Agent$/, '')\n  const kebab = stripped\n    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')\n    .replace(/([A-Z])([A-Z][a-z])/g, '$1-$2')\n    .toLowerCase()\n  return { name: kebab, route: `/api/agents/${kebab}` }\n}\n\nexport function Agent(options?: Partial<AgentOptions>): ClassDecorator {\n  return (target: Function) => {\n    const inferred = inferAgentMeta(target.name)\n    setMeta(AGENT_CONFIG, target, {\n      stream: true,\n      name: inferred.name,\n      route: inferred.route,\n      ...options, // explicit values override inferred\n    })\n  }\n}\n\nexport function getAgentConfig(target: Function): AgentOptions | undefined {\n  return getMeta<AgentOptions>(AGENT_CONFIG, target)\n}\n","/**\n * Agent-native policy decorators — built on http-decorators' createDecorator<T>().\n *\n * These decorators work with Reflector.getAllAndOverride() for hierarchical\n * resolution: tool → toolbox → agent (method-level overrides class-level).\n */\nimport { createDecorator } from '@theokit/http'\n\nimport type { ApprovalOptions, BudgetOptions, PolicyHandler } from '../types.js'\n\n/** Mark a tool as requiring human approval before execution. */\nexport const RequiresApproval = createDecorator<ApprovalOptions>()\n\n/** Require specific capabilities (permissions) to execute a tool. */\nexport const RequiresCapability = createDecorator<string[]>()\n\n/** Set a cost budget for an agent or tool scope. */\nexport const Budget = createDecorator<BudgetOptions>()\n\n/** Attach policy handler functions (CASL-style authorization). */\nexport const Policy = createDecorator<PolicyHandler[]>()\n","/**\n * Observability decorators for agent tracing and auditing.\n */\nimport { createDecorator } from '@theokit/http'\n\n/** Enable distributed tracing for a tool/toolbox/agent. */\nexport const Trace = createDecorator<boolean>()\n\n/** Enable audit logging for a tool/toolbox/agent. */\nexport const Audit = createDecorator<boolean>()\n","/**\n * @Gateway() — declares which platform adapters an agent supports.\n *\n * Stores gateway configuration metadata on the agent class.\n * The GatewayRunner reads this to auto-wire adapters without manual plumbing.\n *\n * @example\n * ```ts\n * @Agent({ name: 'support', route: '/api/agents/support' })\n * @Gateway({\n *   platforms: ['telegram', 'discord', 'slack'],\n *   sessionStrategy: 'per-user',\n * })\n * @UseGuards(AuthGuard)\n * class SupportAgent {\n *   @MainLoop()\n *   async run(ctx: AgentContext) { ... }\n * }\n * ```\n */\nimport { setMeta, getMeta } from '../metadata/index.js'\n\nconst GATEWAY_CONFIG = Symbol.for('theokit:agents:gateway')\n\nexport type PlatformName =\n  | 'telegram'\n  | 'discord'\n  | 'slack'\n  | 'whatsapp'\n  | 'teams'\n  | 'email'\n  | 'sms'\n  | 'mattermost'\n  | 'line'\n  | 'matrix'\n\nexport type SessionStrategy =\n  | 'per-user'       // telegram-dm-{userId}\n  | 'per-channel'    // telegram-grp-{channelId}\n  | 'per-thread'     // telegram-tpc-{channelId}-{topicId}\n\nexport interface GatewayOptions {\n  /** Platform adapters this agent supports. */\n  platforms: PlatformName[]\n  /** How to resolve agentId from inbound events (default: 'per-user'). */\n  sessionStrategy?: SessionStrategy\n  /** Auto-start typing indicator while agent processes (default: true). */\n  typing?: boolean\n}\n\nexport function Gateway(options: GatewayOptions): ClassDecorator {\n  return (target: Function) => {\n    setMeta(GATEWAY_CONFIG, target, { typing: true, sessionStrategy: 'per-user', ...options })\n  }\n}\n\nexport function getGatewayConfig(target: Function): GatewayOptions | undefined {\n  return getMeta<GatewayOptions>(GATEWAY_CONFIG, target)\n}\n\n/**\n * Resolve a stable agentId from a platform event based on the session strategy.\n *\n * Mirrors @theokit/gateway SessionRouter.defaultStrategy() but is configurable\n * via the @Gateway decorator.\n */\nexport function resolveSessionId(\n  strategy: SessionStrategy,\n  platform: string,\n  sender: { id: string },\n  channel: { id: string; type: 'dm' | 'group' | 'thread'; topicId?: string },\n): string {\n  switch (strategy) {\n    case 'per-user':\n      return `${platform}-dm-${sender.id}`\n    case 'per-channel':\n      return `${platform}-grp-${channel.id}`\n    case 'per-thread':\n      return `${platform}-tpc-${channel.id}-${channel.topicId ?? 'main'}`\n  }\n}\n","/**\n * @SubAgents() — declares child agents that a parent agent can handoff to.\n *\n * Compiles to the SDK's `AgentOptions.agents` map. The parent agent\n * can delegate work to sub-agents via the built-in Agent tool.\n *\n * @example\n * ```ts\n * @Agent({ name: 'orchestrator', route: '/api/agents/orchestrator' })\n * @SubAgents([ResearchAgent, CoderAgent, ReviewerAgent])\n * class OrchestratorAgent {\n *   @MainLoop({ strategy: 'plan-act-reflect' })\n *   async run(ctx: AgentContext) { ... }\n * }\n * ```\n *\n * Each referenced class MUST be decorated with @Agent().\n * The compiler reads their metadata to build the SDK agents map.\n */\nimport { setMeta, getMeta } from '../metadata/index.js'\n\nimport { getAgentConfig } from './agent.js'\n\nconst SUB_AGENTS = Symbol.for('theokit:agents:sub-agents')\n\nexport function SubAgents(agentClasses: Function[]): ClassDecorator {\n  return (target: Function) => {\n    // Validate at decoration time: all classes must have @Agent\n    for (const cls of agentClasses) {\n      const config = getAgentConfig(cls)\n      if (!config) {\n        throw new Error(\n          `[@theokit/agents] @SubAgents on ${target.name}: class ${cls.name} is missing @Agent() decorator.`,\n        )\n      }\n    }\n    setMeta(SUB_AGENTS, target, agentClasses)\n  }\n}\n\nexport function getSubAgents(target: Function): Function[] {\n  return getMeta<Function[]>(SUB_AGENTS, target) ?? []\n}\n","/**\n * @Memory() — declares persistent memory configuration for an agent.\n *\n * Compiles to SDK's MemorySettings in Agent.create({ memory }).\n * Memory is per-agent, scoped by session strategy.\n *\n * @example\n * ```ts\n * @Agent({ name: 'support', route: '/api/agents/support' })\n * @Memory({ provider: 'built-in', embeddings: true, fts: true, scope: 'per-user' })\n * class SupportAgent { ... }\n * ```\n */\nimport { setMeta, getMeta } from '../metadata/index.js'\n\nconst MEMORY_CONFIG = Symbol.for('theokit:agents:memory')\n\nexport type MemoryProvider = 'built-in' | 'honcho' | 'supermemory' | 'mem0'\nexport type MemoryScope = 'per-user' | 'per-agent' | 'per-tenant' | 'global'\n\nexport interface MemoryOptions {\n  /** Memory provider backend. */\n  provider?: MemoryProvider\n  /** Enable semantic search via embeddings. */\n  embeddings?: boolean\n  /** Enable full-text search (FTS5). */\n  fts?: boolean\n  /** Memory isolation scope (default: 'per-user'). */\n  scope?: MemoryScope\n  /** Maximum facts to retain per scope (0 = unlimited). */\n  maxFacts?: number\n}\n\nexport function Memory(options: MemoryOptions = {}): ClassDecorator {\n  return (target: Function) => {\n    setMeta(MEMORY_CONFIG, target, {\n      provider: 'built-in',\n      embeddings: false,\n      fts: false,\n      scope: 'per-user',\n      ...options,\n    })\n  }\n}\n\nexport function getMemoryConfig(target: Function): MemoryOptions | undefined {\n  return getMeta<MemoryOptions>(MEMORY_CONFIG, target)\n}\n","/**\n * @Skills() — declares markdown skill files injected into the agent's system prompt.\n *\n * Compiles to SDK's SkillsSettings in Agent.create({ skills }).\n * Skills are .theokit/skills/<name>/SKILL.md files discovered at agent creation.\n *\n * @example\n * ```ts\n * @Agent({ name: 'support', route: '/api/agents/support' })\n * @Skills(['customer-service', 'refund-policy', 'escalation-protocol'])\n * class SupportAgent { ... }\n * ```\n */\nimport { setMeta, getMeta } from '../metadata/index.js'\n\nconst SKILLS_CONFIG = Symbol.for('theokit:agents:skills')\n\nexport interface SkillsOptions {\n  /** Skill names to include (resolved from .theokit/skills/<name>/SKILL.md). */\n  include: string[]\n  /** Auto-discover all skills in .theokit/skills/ (default: false). */\n  autoDiscover?: boolean\n}\n\nexport function Skills(namesOrOptions: string[] | SkillsOptions): ClassDecorator {\n  return (target: Function) => {\n    const options: SkillsOptions = Array.isArray(namesOrOptions)\n      ? { include: namesOrOptions, autoDiscover: false }\n      : namesOrOptions\n    setMeta(SKILLS_CONFIG, target, options)\n  }\n}\n\nexport function getSkillsConfig(target: Function): SkillsOptions | undefined {\n  return getMeta<SkillsOptions>(SKILLS_CONFIG, target)\n}\n","/**\n * @MCP() — declares Model Context Protocol servers available to an agent.\n *\n * Compiles to SDK's mcpServers in Agent.create({ mcpServers }).\n * Each key is a server name; the value is the server configuration.\n *\n * @example\n * ```ts\n * @Agent({ name: 'dev', route: '/api/agents/dev' })\n * @MCP({\n *   github: { command: 'npx', args: ['-y', '@modelcontextprotocol/server-github'] },\n *   filesystem: { command: 'npx', args: ['-y', '@mcp/server-filesystem', '/workspace'] },\n * })\n * class DevAgent { ... }\n * ```\n */\nimport { setMeta, getMeta } from '../metadata/index.js'\n\nconst MCP_CONFIG = Symbol.for('theokit:agents:mcp')\n\nexport interface McpServerConfig {\n  /** Command to start the MCP server. */\n  command: string\n  /** Arguments passed to the command. */\n  args?: string[]\n  /** Environment variables for the server process. */\n  env?: Record<string, string>\n  /** Working directory for the server process. */\n  cwd?: string\n}\n\nexport type McpServersMap = Record<string, McpServerConfig>\n\nexport function MCP(servers: McpServersMap): ClassDecorator {\n  return (target: Function) => {\n    setMeta(MCP_CONFIG, target, servers)\n  }\n}\n\nexport function getMcpConfig(target: Function): McpServersMap | undefined {\n  return getMeta<McpServersMap>(MCP_CONFIG, target)\n}\n","/**\n * @HumanInTheLoop() — pause agent execution to request human approval.\n *\n * When applied to a @Tool method, the agent pauses before executing the tool\n * and emits an 'approval_required' SSE event. The client must POST to the\n * callback URL to approve or deny. If denied or timed out, the tool is skipped.\n *\n * @example\n * ```ts\n * @Toolbox({ namespace: 'ops' })\n * class OpsTools {\n *   @Tool({ name: 'deploy', description: 'Deploy to prod', input: z.object({...}) })\n *   @HumanInTheLoop({\n *     question: 'Confirm deployment to production?',\n *     timeout: 300_000,\n *     onTimeout: 'abort',\n *   })\n *   async deploy(input: {...}) { ... }\n * }\n * ```\n *\n * SSE event emitted:\n * ```json\n * { \"type\": \"approval_required\", \"toolName\": \"ops.deploy\", \"question\": \"...\", \"callbackUrl\": \"/agents/x/approve/call-123\" }\n * ```\n */\nimport { setMeta, getMeta } from '../metadata/index.js'\n\nconst HITL_CONFIG = Symbol.for('theokit:agents:human-in-the-loop')\n\nexport type TimeoutAction = 'abort' | 'proceed' | 'retry'\n\nexport interface HumanInTheLoopOptions {\n  /** Question shown to the human approver. */\n  question: string\n  /** Timeout in milliseconds before onTimeout fires (default: 300_000 = 5 min). */\n  timeout?: number\n  /** Action when timeout expires (default: 'abort'). */\n  onTimeout?: TimeoutAction\n  /** Show the tool input to the approver (default: true). */\n  showInput?: boolean\n  /**\n   * M20 — an optional JSON-schema descriptor of the custom payload the approver may attach (edited\n   * args, a review note). Carried into the `approval_required` event + `GET /approvals` so the UI\n   * knows what to collect. A plain JSON object, not a live Zod schema (keeps the wire serializable).\n   */\n  payloadSchema?: Record<string, unknown>\n}\n\nexport function HumanInTheLoop(options: HumanInTheLoopOptions): MethodDecorator {\n  return (target: object, propertyKey: string | symbol) => {\n    const actualTarget = target.constructor\n    setMeta(\n      HITL_CONFIG,\n      actualTarget,\n      {\n        timeout: 300_000,\n        onTimeout: 'abort',\n        showInput: true,\n        ...options,\n      },\n      propertyKey,\n    )\n  }\n}\n\nexport function getHumanInTheLoopConfig(\n  target: Function,\n  propertyKey: string | symbol,\n): HumanInTheLoopOptions | undefined {\n  return getMeta<HumanInTheLoopOptions>(HITL_CONFIG, target, propertyKey)\n}\n","/**\n * @ContextWindow() — declares context window management strategy.\n *\n * Controls how the agent handles context when conversation history grows\n * beyond the LLM's context window. Mirrors Claude Code's PreCompact behavior.\n *\n * @example\n * ```ts\n * @Agent({ name: 'research', route: '/research' })\n * @ContextWindow({\n *   maxTokens: 100_000,\n *   compactionStrategy: 'summarize-oldest',\n *   preserveSystemPrompt: true,\n *   preserveLastN: 10,\n * })\n * class ResearchAgent { ... }\n * ```\n */\nimport { setMeta, getMeta } from '../metadata/index.js'\n\nconst CONTEXT_WINDOW_CONFIG = Symbol.for('theokit:agents:context-window')\n\nexport type ContextCompactionStrategy =\n  | 'truncate-oldest'      // Drop oldest messages beyond limit\n  | 'summarize-oldest'     // LLM-summarize oldest messages into a single message\n  | 'sliding-window'       // Keep last N messages only\n  | 'priority-based'       // Keep tool results + recent; summarize reasoning\n\nexport interface ContextWindowOptions {\n  /** Maximum tokens before compaction triggers. */\n  maxTokens?: number\n  /** How to compact when maxTokens is exceeded. */\n  compactionStrategy?: ContextCompactionStrategy\n  /** Always preserve the system prompt during compaction (default: true). */\n  preserveSystemPrompt?: boolean\n  /** Number of recent messages to always keep intact (default: 10). */\n  preserveLastN?: number\n  /** Keep all tool results even during compaction (default: true). */\n  preserveToolResults?: boolean\n}\n\nexport function ContextWindow(options: ContextWindowOptions = {}): ClassDecorator {\n  return (target: Function) => {\n    setMeta(CONTEXT_WINDOW_CONFIG, target, {\n      maxTokens: 100_000,\n      compactionStrategy: 'summarize-oldest',\n      preserveSystemPrompt: true,\n      preserveLastN: 10,\n      preserveToolResults: true,\n      ...options,\n    })\n  }\n}\n\nexport function getContextWindowConfig(target: Function): ContextWindowOptions | undefined {\n  return getMeta<ContextWindowOptions>(CONTEXT_WINDOW_CONFIG, target)\n}\n","/**\n * `@Compaction(name, opts)` — declares the agent's transcript-compaction strategy\n * (V4-F). Metadata-only: it records the choice; `AgentRunner.build()` resolves it\n * to a concrete {@link TranscriptCompactionStrategy} via `resolveCompactionStrategy`\n * (EC-5 — an invalid name/budget fails fast at build, not at decoration).\n *\n * Mirrors the `@ContextWindow` metadata pattern (`setMeta`/`getMeta` + a unique\n * Symbol). NOT auto-applied by the loop (ADR D1) — the resolved strategy is exposed\n * as `runner.compaction` for the app to call.\n *\n * @example\n * ```ts\n * @Agent({ model })\n * @Compaction('token-budget', { keepTokens: 8000 })\n * class CodeAgent {}\n * ```\n */\nimport { setMeta, getMeta } from '../metadata/index.js'\n\nconst COMPACTION_CONFIG = Symbol.for('theokit:agents:compaction')\n\n/** Stored `@Compaction` declaration (resolved + validated at `AgentRunner.build()`). */\nexport interface CompactionDecoratorConfig {\n  /** Strategy name (e.g. `'token-budget'`). Validated at resolve time. */\n  name: string\n  /** Token budget for `'token-budget'`. Required at resolve time (EC-2). */\n  keepTokens?: number\n}\n\nexport function Compaction(name: string, options: { keepTokens?: number } = {}): ClassDecorator {\n  return (target: Function) => {\n    setMeta(COMPACTION_CONFIG, target, { name, keepTokens: options.keepTokens })\n  }\n}\n\nexport function getCompactionConfig(target: Function): CompactionDecoratorConfig | undefined {\n  return getMeta<CompactionDecoratorConfig>(COMPACTION_CONFIG, target)\n}\n","/**\n * @Checkpoint() — enables resumable agent execution from the last successful step.\n *\n * Long-running agents (research, code review, multi-step workflows) can fail\n * partway through. Without checkpointing, users restart from step 1 — wasting\n * tokens, time, and cost.\n *\n * Inspired by tRPC's tracked() + lastEventId pattern and Dapr's actor state\n * checkpointing. The agent persists a recovery point after each successful\n * tool call or iteration, and can resume from that point on retry.\n *\n * @example\n * ```ts\n * @Agent({ name: 'research', route: '/research' })\n * @Checkpoint({\n *   storage: 'filesystem', // only 'filesystem' resumes across requests in the M2 harness (M4)\n *   strategy: 'after-tool-call',\n *   maxCheckpoints: 20,\n *   ttl: 3_600_000,  // 1h\n * })\n * class ResearchAgent {\n *   @MainLoop({ strategy: 'plan-act-reflect', maxIterations: 15 })\n *   async run() {}\n * }\n *\n * // Resume: a follow-up POST /api/agents/research with the SAME sessionId replays the persisted\n * // history. NOTE (M4): only `storage: 'filesystem'` resumes across requests today — `memory`\n * // (the default below) is per-run; `drizzle`/`redis` are not shipped by the SDK. A non-filesystem\n * // @Checkpoint emits a THEO_AGENT_CHECKPOINT_STORAGE_METADATA_ONLY warning (honest enforcement).\n * ```\n */\nimport { setMeta, getMeta } from '../metadata/index.js'\n\nconst CHECKPOINT_CONFIG = Symbol.for('theokit:agents:checkpoint')\n\nexport type CheckpointStrategy =\n  | 'after-tool-call' // checkpoint after every successful tool execution\n  | 'after-iteration' // checkpoint after every loop iteration\n  | 'manual' // only checkpoint when explicitly called via ctx.checkpoint()\n\nexport type CheckpointStorage = 'memory' | 'filesystem' | 'drizzle' | 'redis'\n\nexport interface CheckpointOptions {\n  /** Where to persist checkpoints. */\n  storage?: CheckpointStorage\n  /** When to auto-checkpoint (default: 'after-tool-call'). */\n  strategy?: CheckpointStrategy\n  /** Maximum checkpoints to retain per run (rolling window). */\n  maxCheckpoints?: number\n  /** Time-to-live in ms before checkpoints expire (default: 3_600_000 = 1h). */\n  ttl?: number\n}\n\n/** Serializable checkpoint state. */\nexport interface CheckpointState {\n  id: string\n  runId: string\n  agentName: string\n  step: number\n  messages: unknown[]\n  toolResults: unknown[]\n  createdAt: number\n  resumeToken: string\n}\n\nexport function Checkpoint(options: CheckpointOptions = {}): ClassDecorator {\n  return (target: Function) => {\n    setMeta(CHECKPOINT_CONFIG, target, {\n      storage: 'memory',\n      strategy: 'after-tool-call',\n      maxCheckpoints: 10,\n      ttl: 3_600_000,\n      ...options,\n    })\n  }\n}\n\nexport function getCheckpointConfig(target: Function): CheckpointOptions | undefined {\n  return getMeta<CheckpointOptions>(CHECKPOINT_CONFIG, target)\n}\n","/**\n * @ProjectContext() — declares how the agent understands the codebase.\n *\n * A code assistant needs to know: what's the project root, which files\n * are relevant, how to parse code structure, what to ignore. This\n * metadata feeds the context window management and file discovery.\n *\n * @example\n * ```ts\n * @Agent({ name: 'coder', route: '/agents/coder' })\n * @ProjectContext({\n *   rootMarkers: ['package.json', 'tsconfig.json'],\n *   indexStrategy: 'tree-sitter',\n *   maxFilesInContext: 20,\n *   relevanceStrategy: 'git-history',\n *   ignorePatterns: ['node_modules', 'dist', '.git'],\n * })\n * class CoderAgent { ... }\n * ```\n */\nimport { setMeta, getMeta } from '../metadata/index.js'\n\nconst PROJECT_CONTEXT_CONFIG = Symbol.for('theokit:agents:project-context')\n\nexport type IndexStrategy =\n  | 'tree-sitter'    // Parse AST for structural understanding\n  | 'regex'          // Simple regex-based symbol extraction\n  | 'none'           // No indexing — rely on grep/glob only\n\nexport type RelevanceStrategy =\n  | 'git-history'     // Prioritize recently-edited files\n  | 'import-graph'    // Follow import chains from entry points\n  | 'semantic'        // Embedding-based similarity search\n  | 'manual'          // Only files explicitly provided\n\nexport interface ProjectContextOptions {\n  /** Files that mark the project root (searched upward from cwd). */\n  rootMarkers?: string[]\n  /** How to index the codebase for structural understanding. */\n  indexStrategy?: IndexStrategy\n  /** Maximum files to include in context per request. */\n  maxFilesInContext?: number\n  /** How to rank file relevance when selecting context. */\n  relevanceStrategy?: RelevanceStrategy\n  /** Glob patterns to exclude from indexing and context. */\n  ignorePatterns?: string[]\n  /** File extensions to include in indexing (default: all text files). */\n  includeExtensions?: string[]\n}\n\nexport function ProjectContext(options: ProjectContextOptions = {}): ClassDecorator {\n  return (target: Function) => {\n    setMeta(PROJECT_CONTEXT_CONFIG, target, {\n      rootMarkers: ['package.json', 'tsconfig.json', 'go.mod', 'Cargo.toml', 'pyproject.toml'],\n      indexStrategy: 'regex',\n      maxFilesInContext: 20,\n      relevanceStrategy: 'git-history',\n      ignorePatterns: ['node_modules', 'dist', 'build', '.git', 'coverage', '__pycache__'],\n      ...options,\n    })\n  }\n}\n\nexport function getProjectContextConfig(target: Function): ProjectContextOptions | undefined {\n  return getMeta<ProjectContextOptions>(PROJECT_CONTEXT_CONFIG, target)\n}\n","/**\n * @Mixin() — compose reusable capability classes into an agent.\n *\n * Mixins are classes with @Tool methods that can be shared across agents.\n * @Mixin copies tool metadata from mixin classes to the decorated agent,\n * making those tools available without inheritance.\n *\n * @example\n * ```ts\n * // Define reusable capabilities\n * class WithSearchCapability {\n *   @Tool({ name: 'web_search', description: 'Search', input: z.object({...}) })\n *   async webSearch(input) { ... }\n * }\n *\n * class WithFileSystem {\n *   @Tool({ name: 'read_file', description: 'Read', input: z.object({...}) })\n *   async readFile(input) { ... }\n * }\n *\n * // Compose into agent\n * @Agent({ name: 'research', route: '/research' })\n * @Mixin(WithSearchCapability, WithFileSystem)\n * class ResearchAgent {\n *   @MainLoop()\n *   async run() {}\n * }\n * ```\n */\nimport { setMeta, getMeta } from '../metadata/index.js'\n\nconst MIXIN_CLASSES = Symbol.for('theokit:agents:mixins')\n\nexport function Mixin(...mixinClasses: Function[]): ClassDecorator {\n  return (target: Function) => {\n    const existing = getMeta<Function[]>(MIXIN_CLASSES, target) ?? []\n    setMeta(MIXIN_CLASSES, target, [...existing, ...mixinClasses])\n  }\n}\n\nexport function getMixins(target: Function): Function[] {\n  return getMeta<Function[]>(MIXIN_CLASSES, target) ?? []\n}\n"],"mappings":"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","names":["setMeta","getMeta","AGENT_CONFIG","Symbol","for","AGENT_MAIN_LOOP","TOOLBOX_CONFIG","TOOL_CONFIG","TOOL_METHODS","inferAgentMeta","className","stripped","replace","kebab","toLowerCase","name","route","Agent","options","target","inferred","setMeta","AGENT_CONFIG","stream","getAgentConfig","getMeta","createDecorator","RequiresApproval","RequiresCapability","Budget","Policy","createDecorator","Trace","Audit","GATEWAY_CONFIG","Symbol","for","Gateway","options","target","setMeta","typing","sessionStrategy","getGatewayConfig","getMeta","resolveSessionId","strategy","platform","sender","channel","id","topicId","SUB_AGENTS","Symbol","for","SubAgents","agentClasses","target","cls","config","getAgentConfig","Error","name","setMeta","getSubAgents","getMeta","MEMORY_CONFIG","Symbol","for","Memory","options","target","setMeta","provider","embeddings","fts","scope","getMemoryConfig","getMeta","SKILLS_CONFIG","Symbol","for","Skills","namesOrOptions","target","options","Array","isArray","include","autoDiscover","setMeta","getSkillsConfig","getMeta","MCP_CONFIG","Symbol","for","MCP","servers","target","setMeta","getMcpConfig","getMeta","HITL_CONFIG","Symbol","for","HumanInTheLoop","options","target","propertyKey","actualTarget","setMeta","timeout","onTimeout","showInput","getHumanInTheLoopConfig","getMeta","CONTEXT_WINDOW_CONFIG","Symbol","for","ContextWindow","options","target","setMeta","maxTokens","compactionStrategy","preserveSystemPrompt","preserveLastN","preserveToolResults","getContextWindowConfig","getMeta","COMPACTION_CONFIG","Symbol","for","Compaction","name","options","target","setMeta","keepTokens","getCompactionConfig","getMeta","CHECKPOINT_CONFIG","Symbol","for","Checkpoint","options","target","setMeta","storage","strategy","maxCheckpoints","ttl","getCheckpointConfig","getMeta","PROJECT_CONTEXT_CONFIG","Symbol","for","ProjectContext","options","target","setMeta","rootMarkers","indexStrategy","maxFilesInContext","relevanceStrategy","ignorePatterns","getProjectContextConfig","getMeta","MIXIN_CLASSES","Symbol","for","Mixin","mixinClasses","target","existing","getMeta","setMeta","getMixins"]}