@theokit/agents 0.47.0 → 1.0.0

package/dist/{bridge-entry-BQ6UUSLZ.d.ts → bridge-entry-F9kHGaIn.d.ts}

@@ -1,10 +1,188 @@
 import { ExecutionContext } from '@theokit/http';
-import { A as AgentOptions, g as ToolOptions, M as MainLoopMeta, a as ApprovalOptions, B as BudgetOptions, H as HumanInTheLoopOptions, t as GatewayOptions, z as MemoryOptions, O as SkillsOptions, r as ContextWindowOptions, K as ProjectContextOptions, x as McpServersMap, G as Guardrail, o as CompactionDecoratorConfig, j as CheckpointOptions, R as ReasoningEffort } from './types-DVA4LQsA.js';
-import { InlineSkill, SystemPromptResolver, SettingSource, MemorySettings, SkillsSettings, ContextSettings, CustomTool, PluginsSettings, Plugin, ProviderRoutingSettings, AgentDefinition as AgentDefinition$1, BudgetTracker, ModelSelection } from '@theokit/sdk';
+import { SystemPromptResolver, InlineSkill, SettingSource, MemorySettings, SkillsSettings, ContextSettings, CustomTool, PluginsSettings, Plugin, ProviderRoutingSettings, AgentDefinition as AgentDefinition$1, BudgetTracker, ModelSelection } from '@theokit/sdk';
 import { z } from 'zod';
 import { UIMessageChunk } from 'ai';
 import { RetryOptions } from '@theokit/sdk/retry';
 
+/**
+ * Provider-agnostic extended-thinking knob (M1 reasoning-visibility). The common set autocompletes;
+ * `(string & {})` accepts provider-specific values forward-compat (mirrors `AgentRunErrorCode`) — the
+ * SDK validates the value against the model's catalog. Defined in this leaf module so every layer
+ * (`@Agent` config, compiler, runner, sdk-adapter) imports it without an import cycle.
+ */
+type ReasoningEffort = 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | (string & {});
+/** Scalar agent configuration. */
+interface AgentOptions {
+    /** Unique agent name (kebab-case). */
+    name: string;
+    /** HTTP route prefix (e.g., '/api/agents/support'). */
+    route: string;
+    /** LLM model identifier (e.g., 'claude-sonnet-4-5-20250929'). */
+    model?: string;
+    /** Extended-thinking effort; mapped to the SDK `ModelSelection.params` so the provider reasons. */
+    reasoningEffort?: ReasoningEffort;
+    /**
+     * Opt-in (default false): convert inline `<think>…</think>` in the text stream into `thinking`
+     * events (M2) — for models that emit reasoning as inline tags (qwen/deepseek) rather than via a
+     * native reasoning param. Off by default since a code assistant may emit literal `<think>` in text.
+     */
+    parseThinkTags?: boolean;
+    /**
+     * Opt-in (default false): strip a leaked Hermes `<function=…></tool_call>` tool-call dialect out of
+     * the visible text (theocode#32) — for models (qwen/qwen3-coder) that intermittently emit tool calls
+     * as text instead of native `tool_calls`. Off by default since a code assistant may emit a literal
+     * `<function=` in answer/code text. Sibling of {@link parseThinkTags}.
+     */
+    stripToolDialect?: boolean;
+    /**
+     * Opt-in (default false): recover a leaked Hermes `<function=…></tool_call>` tool-call dialect so the
+     * call actually EXECUTES (theokit#58 follow-up). Where {@link stripToolDialect} only hides the leaked
+     * block from the visible text, this enables the SDK's `extractToolCallsFromContent` on the chat route,
+     * so a `chat_completions` finish with ZERO native `tool_calls` has its text scanned for the dialect and
+     * any recovered calls are dispatched by the loop. For models (qwen/qwen3-coder via OpenRouter) that
+     * leak tool calls as text. Off by default (a code assistant may print a literal `<function=`); fail-open.
+     * Has effect only when {@link AgentOptions} routes a provider via `providers.routes`. Sibling of
+     * {@link stripToolDialect} — typically enabled together.
+     */
+    recoverLeakedToolCalls?: boolean;
+    /** Enable SSE streaming (default: true). */
+    stream?: boolean;
+    /** Maximum loop iterations before forcing a terminal response. */
+    maxIterations?: number;
+    /** Timeout in milliseconds for the entire agent run. */
+    timeoutMs?: number;
+    /**
+     * System prompt for the agent. Either a static string OR a
+     * {@link SystemPromptResolver} computed per request (V4-L.1, Axis-B) — the SDK
+     * invokes the resolver each send with the run's `SystemPromptContext` (cwd, etc.).
+     */
+    systemPrompt?: string | SystemPromptResolver;
+}
+/** Configuration stored by @MainLoop() decorator. */
+interface MainLoopOptions {
+    /** Execution strategy. */
+    strategy?: 'simple-chat' | 'plan-act-reflect' | 'react';
+    /** Maximum iterations for this loop. */
+    maxIterations?: number;
+    /** Timeout in milliseconds. */
+    timeoutMs?: number;
+}
+/** Internal representation of a resolved @MainLoop. */
+interface MainLoopMeta {
+    propertyKey: string | symbol;
+    strategy: 'simple-chat' | 'plan-act-reflect' | 'react';
+    maxIterations?: number;
+    timeoutMs?: number;
+}
+/** Configuration stored by @Toolbox() decorator. */
+interface ToolboxOptions {
+    /** Namespace prefix for all tools in this toolbox (e.g., 'support'). */
+    namespace?: string;
+}
+/** Configuration stored by @Tool() decorator. */
+interface ToolOptions {
+    /** Tool name (surfaced to LLM). */
+    name: string;
+    /** LLM-facing description. */
+    description: string;
+    /** Zod input schema — compiled to JSON Schema via defineTool(). */
+    input: z.ZodType;
+    /** Risk level (informational — feeds manifest + UI). */
+    risk?: 'low' | 'medium' | 'high';
+}
+/** Budget configuration for @Budget() decorator. */
+interface BudgetOptions {
+    /** Maximum cost in USD for this scope. */
+    maxCostUsd: number;
+    /** Rolling window for budget tracking. */
+    window?: 'daily' | 'monthly';
+}
+/** Approval configuration for @RequiresApproval() decorator. */
+interface ApprovalOptions {
+    /** Reason shown to the approver. */
+    reason: string;
+}
+/** Policy handler function type. */
+type PolicyHandler = (user: {
+    roles: string[];
+}) => boolean;
+/**
+ * M53 — moved here from the `@HumanInTheLoop` decorator, which is being deleted: the type is
+ * consumed by `compileHitlGates` and the toolbox capability, not by the decorator alone.
+ */
+type TimeoutAction = 'abort' | 'proceed' | 'retry';
+interface HumanInTheLoopOptions {
+    /** Question shown to the human approver. */
+    question: string;
+    /** Timeout in milliseconds before onTimeout fires (default: 300_000 = 5 min). */
+    timeout?: number;
+    /** Action when timeout expires (default: 'abort'). */
+    onTimeout?: TimeoutAction;
+    /** Show the tool input to the approver (default: true). */
+    showInput?: boolean;
+    /**
+     * M20 — an optional JSON-schema descriptor of the custom payload the approver may attach (edited
+     * args, a review note). Carried into the `approval_required` event + `GET /approvals` so the UI
+     * knows what to collect. A plain JSON object, not a live Zod schema (keeps the wire serializable).
+     */
+    payloadSchema?: Record<string, unknown>;
+}
+/** M53 — moved from the `@MCP` decorator being deleted; consumed by the bridge and the adapter. */
+interface McpServerConfig {
+    /** Command to start the MCP server. */
+    command: string;
+    /** Arguments passed to the command. */
+    args?: string[];
+    /** Environment variables for the server process. */
+    env?: Record<string, string>;
+    /** Working directory for the server process. */
+    cwd?: string;
+}
+type McpServersMap = Record<string, McpServerConfig>;
+/** M53 — moved from the `@ProjectContext` decorator being deleted; read by the compiler. */
+type IndexStrategy = 'tree-sitter' | 'regex' | 'none';
+type RelevanceStrategy = 'git-history' | 'import-graph' | 'semantic' | 'manual';
+interface ProjectContextOptions {
+    /** Files that mark the project root (searched upward from cwd). */
+    rootMarkers?: string[];
+    /** How to index the codebase for structural understanding. */
+    indexStrategy?: IndexStrategy;
+    /** Maximum files to include in context per request. */
+    maxFilesInContext?: number;
+    /** How to rank file relevance when selecting context. */
+    relevanceStrategy?: RelevanceStrategy;
+    /** Glob patterns to exclude from indexing and context. */
+    ignorePatterns?: string[];
+    /** File extensions to include in indexing (default: all text files). */
+    includeExtensions?: string[];
+}
+type CheckpointStrategy = 'after-tool-call' | 'after-iteration' | 'manual';
+type CheckpointStorage = 'memory' | 'filesystem' | 'drizzle' | 'redis';
+interface CheckpointOptions {
+    /** Where to persist checkpoints. */
+    storage?: CheckpointStorage;
+    /** When to auto-checkpoint (default: 'after-tool-call'). */
+    strategy?: CheckpointStrategy;
+    /** Maximum checkpoints to retain per run (rolling window). */
+    maxCheckpoints?: number;
+    /** Time-to-live in ms before checkpoints expire (default: 3_600_000 = 1h). */
+    ttl?: number;
+}
+type MemoryProvider = 'built-in' | 'honcho' | 'supermemory' | 'mem0';
+type MemoryScope = 'per-user' | 'per-agent' | 'per-tenant' | 'global';
+interface MemoryOptions {
+    /** Memory provider backend. */
+    provider?: MemoryProvider;
+    /** Enable semantic search via embeddings. */
+    embeddings?: boolean;
+    /** Enable full-text search (FTS5). */
+    fts?: boolean;
+    /** Memory isolation scope (default: 'per-user'). */
+    scope?: MemoryScope;
+    /** Maximum facts to retain per scope (0 = unlimited). */
+    maxFacts?: number;
+}
+
 /**
  * AgentExecutionContext — extends http-decorators' ExecutionContext with agent-specific methods.
  *
@@ -17,7 +195,7 @@ interface AgentRunInfo {
     startedAt: Date;
 }
 interface AgentExecutionContext extends ExecutionContext {
-    /** The agent's configuration from @Agent() decorator. */
+    /** The agent's scalar configuration. */
     getAgent(): AgentOptions;
     /** The current run information. */
     getRun(): AgentRunInfo;
@@ -32,77 +210,51 @@ declare function createAgentExecutionContext(base: ExecutionContext, agent: Agen
 declare function isAgentContext(ctx: ExecutionContext): ctx is AgentExecutionContext;
 
 /**
- * Walk decorator metadata on agent + toolbox classes.
- * Mirrors http-decorators' walkControllerMetadata() pattern.
+ * M9 (theokit-ai-first) — guardrail contract + typed errors.
  *
- * EC-1: throws if @Agent class is missing @MainLoop.
- * EC-4: throws on duplicate routes across agents.
+ * 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';
 /**
- * Stable warning codes for agent pipeline metadata-only decorators.
- * Test by code, not by message string. Document in agent support matrix.
+ * 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.
  */
-declare const AgentWarningCode: {
-    readonly INTERCEPTOR_METADATA_ONLY: "THEO_AGENT_INTERCEPTOR_METADATA_ONLY";
-    readonly FILTER_METADATA_ONLY: "THEO_AGENT_FILTER_METADATA_ONLY";
-    readonly BUDGET_TOP_LEVEL_METADATA_ONLY: "THEO_AGENT_BUDGET_TOP_LEVEL_METADATA_ONLY";
-    readonly CONTEXT_STRATEGY_METADATA_ONLY: "THEO_AGENT_CONTEXT_STRATEGY_METADATA_ONLY";
-    readonly PROJECT_CONTEXT_KNOB_METADATA_ONLY: "THEO_AGENT_PROJECT_CONTEXT_KNOB_METADATA_ONLY";
-    readonly CHECKPOINT_STORAGE_METADATA_ONLY: "THEO_AGENT_CHECKPOINT_STORAGE_METADATA_ONLY";
-};
-interface AgentWalkResult {
-    agentConfig: AgentOptions;
-    mainLoop: MainLoopMeta;
-    toolboxes: ToolboxWalkResult[];
-    guards: Function[];
-    interceptors: Function[];
-    filters: Function[];
-    route: string;
-    gateway?: GatewayOptions;
-    subAgentClasses: Function[];
-    memory?: MemoryOptions;
-    skills?: SkillsOptions;
-    contextWindow?: ContextWindowOptions;
-    projectContext?: ProjectContextOptions;
-    mcpServers?: McpServersMap;
-    /** M9 — `@Guardrails([...])` input/output guards when the class declares them; absent ⇒ none. */
-    guardrails?: readonly Guardrail[];
-    compaction?: CompactionDecoratorConfig;
-    /** `@Checkpoint` config (M4) when the agent declares resumable execution; absent ⇒ no checkpoint. */
-    checkpoint?: CheckpointOptions;
-}
-interface ToolboxWalkResult {
-    class: Function;
-    namespace: string;
-    tools: ToolWalkResult[];
-    guards: Function[];
-}
-interface ToolWalkResult {
-    propertyKey: string | symbol;
-    config: ToolOptions;
-    guards: Function[];
-    approval?: ApprovalOptions;
-    capabilities?: string[];
-    budget?: BudgetOptions;
-    trace: boolean;
-    audit: boolean;
-    /** `@HumanInTheLoop` config when the tool method is gated (M4); absent ⇒ not gated. */
-    hitl?: HumanInTheLoopOptions;
+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;
 }
 /**
- * Walk all metadata on an agent class and its toolboxes.
- * Memoized per AgentClass via WeakMap.
- *
- * @throws Error if @Agent is missing @MainLoop (EC-1)
+ * 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.
  */
-declare function walkAgentMetadata(AgentClass: Function, toolboxClasses?: Function[]): AgentWalkResult;
-/**
- * Validate that no two agents share the same route prefix.
- *
- * @throws Error on duplicate routes (EC-4)
- */
-declare function validateUniqueRoutes(results: AgentWalkResult[]): void;
+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).
@@ -141,6 +293,32 @@ declare function resolveEnabledSkills(selection: SkillsSelection | undefined, ct
  * EC-3: throws if toolbox instance is missing from the instances map.
  */
 
+/**
+ * M53 — the input shape `compileTools`/`compileHitlGates` consume, declared WITH them now that the
+ * metadata walk that used to own it is gone. `ToolboxCapability` builds this from a class'
+ * `static tools` declaration.
+ */
+/** A guard/interceptor class token — identity only (the DI container instantiates it). */
+type ClassToken = abstract new (...args: never[]) => object;
+interface ToolWalkResult {
+    propertyKey: string | symbol;
+    config: ToolOptions;
+    guards: ClassToken[];
+    approval?: ApprovalOptions;
+    capabilities?: string[];
+    budget?: BudgetOptions;
+    trace: boolean;
+    audit: boolean;
+    /** HITL config when the tool is gated (M4); absent ⇒ not gated. */
+    hitl?: HumanInTheLoopOptions;
+}
+interface ToolboxWalkResult {
+    /** The toolbox class — used as the identity key into `toolboxInstances`. */
+    class: ClassToken;
+    namespace: string;
+    tools: ToolWalkResult[];
+    guards: ClassToken[];
+}
 /** Minimal interface matching defineTool() result shape. */
 interface CompiledTool {
     name: string;
@@ -164,7 +342,7 @@ interface CompiledTool {
  * @param toolboxes - Walked toolbox metadata
  * @param toolboxInstances - Map of Toolbox class → instantiated object (for `this` binding)
  */
-declare function compileTools(toolboxes: ToolboxWalkResult[], toolboxInstances: Map<Function, object>): CompiledTool[];
+declare function compileTools(toolboxes: ToolboxWalkResult[], toolboxInstances: Map<ClassToken, object>): CompiledTool[];
 /** Compiled sub-agent definition matching SDK AgentDefinition shape. */
 interface CompiledSubAgent {
     model?: string;
@@ -180,13 +358,13 @@ interface CompiledSubAgent {
 /** Compiled agent options ready for SDK Agent.create(). */
 interface CompiledAgentOptions {
     model?: string;
-    /** Extended-thinking effort declared via `@Agent({ reasoningEffort })`; mapped to SDK ModelSelection.params. */
+    /** Extended-thinking effort; mapped to SDK ModelSelection.params. */
     reasoningEffort?: ReasoningEffort;
-    /** Opt-in `<think>`-tag extraction declared via `@Agent({ parseThinkTags })` (M2); wraps the stream when true. */
+    /** Opt-in `<think>`-tag extraction (M2); wraps the stream when true. */
     parseThinkTags?: boolean;
-    /** Opt-in tool-dialect stripping declared via `@Agent({ stripToolDialect })` (theocode#32); strips leaked `<function=…></tool_call>` from text when true. */
+    /** Opt-in tool-dialect stripping (theocode#32); strips leaked `<function=…></tool_call>` from text when true. */
     stripToolDialect?: boolean;
-    /** Opt-in leaked-dialect recovery declared via `@Agent({ recoverLeakedToolCalls })` (theokit#58); enables the SDK route's `extractToolCallsFromContent` so leaked tool calls EXECUTE when true. */
+    /** Opt-in leaked-dialect recovery (theokit#58); enables the SDK route's `extractToolCallsFromContent` so leaked tool calls EXECUTE when true. */
     recoverLeakedToolCalls?: boolean;
     /** Static prompt OR a per-request {@link SystemPromptResolver} (V4-L.1, Axis-B). */
     systemPrompt?: string | SystemPromptResolver;
@@ -239,12 +417,6 @@ interface CompiledAgentOptions {
      */
     skillsResolver?: SkillsSelection;
 }
-/**
- * Compile @Agent metadata into SDK-compatible options.
- *
- * EC-7: agents without toolboxes produce tools: [].
- */
-declare function compileAgent(walkResult: AgentWalkResult, toolboxInstances?: Map<Function, object>): CompiledAgentOptions;
 
 /**
  * M8-3 — compile `@Skills` metadata into the SDK's `SkillsSettings`.
@@ -261,6 +433,16 @@ declare function compileAgent(walkResult: AgentWalkResult, toolboxInstances?: Ma
  *                              enables every discovered skill)
  */
 
+/**
+ * M53 — the options shape lives WITH its conversion now. It used to be declared on the decorator
+ * that is being deleted, which would have taken a type the compiler needs down with it.
+ */
+interface SkillsOptions {
+    /** Skill names to include (resolved from `.theokit/skills/<name>/SKILL.md`). */
+    include: string[];
+    /** Auto-discover every skill under `.theokit/skills/` (default: false). */
+    autoDiscover?: boolean;
+}
 declare function compileSkills(options: SkillsOptions): SkillsSettings;
 
 /**
@@ -275,6 +457,23 @@ declare function compileSkills(options: SkillsOptions): SkillsSettings;
  * (ADR D2) instead of silently dropping them (G10 — honest enforcement).
  */
 
+/** How to compact the transcript when `maxTokens` is exceeded. */
+type ContextCompactionStrategy = 'truncate-oldest' | 'summarize-oldest' | 'sliding-window' | 'priority-based';
+/**
+ * M53 — declared here, with its conversion, instead of on the decorator being deleted.
+ */
+interface ContextWindowOptions {
+    /** Maximum tokens before compaction triggers. */
+    maxTokens?: number;
+    /** How to compact when maxTokens is exceeded. */
+    compactionStrategy?: ContextCompactionStrategy;
+    /** Always preserve the system prompt during compaction (default: true). */
+    preserveSystemPrompt?: boolean;
+    /** Number of recent messages to always keep intact (default: 10). */
+    preserveLastN?: number;
+    /** Keep all tool results even during compaction (default: true). */
+    preserveToolResults?: boolean;
+}
 interface CompiledContextWindow {
     /** SDK-shaped context budget passed to `Agent.create({ context })`. */
     context: ContextSettings;
@@ -490,7 +689,7 @@ declare function isApprovalRequired(e: AgentStreamEvent): e is ApprovalRequiredE
 /**
  * Auto-generate HTTP routes from @Agent metadata — Web Standard.
  *
- * Per ADR D5: @Agent({ route }) auto-generates two endpoints:
+ * Per ADR D5: an agent's `route` auto-generates two endpoints:
  * - POST {route}/chat  — send message, receive SSE stream
  * - GET  {route}/runs/:runId — get run status/result
  *
@@ -503,7 +702,14 @@ interface AgentRoute {
     handler: (request: Request) => Promise<Response>;
 }
 interface AgentRouteContext {
-    walkResult: AgentWalkResult;
+    /**
+     * M53 — only the mounting `route` was ever read from the walk, so the generator declares that
+     * instead of the whole `AgentWalkResult` (which chained it to the decorator metadata walk).
+     * `AgentWalkResult` satisfies this structurally, so the decorator path is unchanged.
+     */
+    walkResult: {
+        route: string;
+    };
     compiledOptions: CompiledAgentOptions;
     createRun: (message: string, sessionId: string) => AsyncIterable<StreamEvent>;
     getRun?: (runId: string) => Promise<{
@@ -542,7 +748,7 @@ interface DefineAgentConfig<TInput extends z.ZodType = z.ZodType> {
     model?: string;
     /** Static system prompt. */
     system?: string;
-    /** Extended-thinking effort (mirrors `@Agent({ reasoningEffort })`). */
+    /** Extended-thinking effort. */
     reasoningEffort?: ReasoningEffort;
     /**
      * Pre-built tools. Accepts the `@theokit/sdk` `CustomTool` that `defineAgentTool`
@@ -738,9 +944,11 @@ interface RuntimeOverrides {
  * Returns a function that, given a message + sessionId, yields TheoKit
  * AgentStreamEvent via the SDK's Agent.create() + Run.stream() pipeline.
  */
-declare function createSdkAgentStream(compiled: CompiledAgentOptions, compiledTools: CompiledTool[], apiKey: string, overrides?: RuntimeOverrides): (message: string, sessionId: string, factoryOpts?: {
+declare function createSdkAgentStream(compiled: CompiledAgentOptions, compiledTools: CompiledTool[], apiKey: string, overrides?: RuntimeOverrides): ((message: string, sessionId: string, factoryOpts?: {
     disableTools?: boolean;
-}) => AsyncIterable<StreamEvent>;
+}) => AsyncIterable<StreamEvent>) & {
+    resolvedModel: string;
+};
 /**
  * The minimal `SDKAgent` surface a serving host needs (ACP checks `agentId: string` + `send: fn`).
  * `Agent.getOrCreate` returns the real SDK agent — this alias just types what {@link toAgentFactory}
@@ -1080,16 +1288,6 @@ interface HitlWiring {
 declare class AgentDefinitionError extends Error {
     constructor(source: string);
 }
-/**
- * Compile a loaded `agents/` module to SDK-ready options. Accepts a `defineAgent` value
- * (zero-config surface) OR an `@Agent`-decorated class (advanced surface). `source` labels
- * the fail-fast error (typically the file path).
- *
- * For a class agent, its `@Mixin(...)` toolboxes are gathered (the declared tool-association
- * mechanism, same as `app.ts`/`theokit-plugin.ts`) and instantiated with a no-arg `new` — the
- * zero-config file convention has no DI container. This is what makes a `@HumanInTheLoop`-gated
- * tool on a mixin actually gate through the M2 endpoint (M4): its config reaches `compiled.hitl`.
- */
 declare function compileAgentModule(mod: unknown, source?: string): CompiledAgentOptions;
 /** HITL wiring supplied by the harness (mount-agent): the gated-tool map + the approval resolver. */
 interface StreamHitlOptions {
@@ -1423,7 +1621,19 @@ interface DelegateOptions {
  *   metric (`THEO_AGENT_MAINLOOP_RUNTIME_APPLIED`) + typed-error + cumulative budget
  *   all live in the shared driver, so they fire identically on both paths.
  */
-declare function delegate(SubAgentClass: Function, message: string, opts?: DelegateOptions): Promise<DelegationResult>;
+/**
+ * What `delegate` needs from a sub-agent: a name and already-compiled options (built by
+ * `applyCapabilities`). Compatible with {@link AgentRunnerSpec} — one spec drives both on-ramps.
+ */
+interface SubAgentSpec {
+    readonly name: string;
+    readonly compiled: CompiledAgentOptions;
+    /** Loop strategy (`@MainLoop({ strategy })`); absent ⇒ the same `'simple-chat'` default. */
+    readonly strategy?: MainLoopMeta['strategy'];
+    /** Loop ceiling (`@MainLoop({ maxIterations })`); a per-run override still wins. */
+    readonly maxIterations?: number;
+}
+declare function delegate(spec: SubAgentSpec, message: string, opts?: DelegateOptions): Promise<DelegationResult>;
 
 /**
  * M10 (theokit-ai-first) — createToolHooksPlugin: `beforeToolCall` / `afterToolCall` observability.
@@ -1585,7 +1795,7 @@ declare function createApiErrorHandler<R = unknown>(policy: ApiErrorPolicy<R>):
  */
 
 /** The delegation primitive both wrappers drive. Defaults to the M12 {@link delegate}. */
-type DelegateFn = (subAgent: Function, message: string, opts?: DelegateOptions) => Promise<DelegationResult>;
+type DelegateFn = (subAgent: SubAgentSpec, 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. */
@@ -1598,7 +1808,7 @@ interface BackgroundDelegation {
  * 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 & {
+declare function delegateBackground(subAgent: SubAgentSpec, 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. */
@@ -1626,7 +1836,7 @@ interface ScoredDelegation {
  * `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 & {
+declare function delegateWithScoring(subAgent: SubAgentSpec, message: string, opts: DelegateOptions & {
     scorer: Scorer;
     maxRounds?: number;
     delegateFn?: DelegateFn;
@@ -1690,7 +1900,63 @@ declare function mcpToolApprovals(specs: Record<string, McpApprovalSpec>): Recor
  *
  * Feeds: theokit agents list/inspect, TheoCloud deploy, UI agent consoles.
  */
-
+/**
+ * M53 — the manifest's OWN input contract, listing exactly the members it reads. It used to take an
+ * `AgentWalkResult`, which chained the manifest to the decorator metadata walk that M53 deletes.
+ *
+ * `AgentWalkResult` satisfies this structurally, so the decorator path keeps working unchanged while
+ * the migration is in flight; once the walk is gone, the capability path builds this directly. The
+ * point is that the manifest never needed the whole walk — only these members.
+ */
+interface AgentManifestSource {
+    readonly agentConfig: {
+        name: string;
+        model?: string;
+        stream?: boolean;
+    };
+    readonly route: string;
+    readonly mainLoop: {
+        propertyKey: string | symbol;
+        strategy: string;
+    };
+    readonly guards: readonly {
+        name: string;
+    }[];
+    readonly interceptors: readonly {
+        name: string;
+    }[];
+    readonly toolboxes: readonly {
+        namespace?: string;
+        tools: readonly {
+            config: {
+                name: string;
+                description: string;
+                risk?: string;
+            };
+            approval?: unknown;
+            capabilities?: string[];
+            trace: boolean;
+            audit: boolean;
+        }[];
+    }[];
+    readonly gateway?: {
+        platforms: string[];
+        sessionStrategy?: string;
+    };
+    readonly subAgentClasses: readonly {
+        name: string;
+    }[];
+    readonly memory?: {
+        provider?: string;
+        embeddings?: boolean;
+        fts?: boolean;
+        scope?: string;
+    };
+    readonly skills?: {
+        include?: string[];
+    };
+    readonly mcpServers?: Record<string, unknown>;
+}
 interface AgentManifest {
     version: '1.0';
     generatedAt: string;
@@ -1732,10 +1998,10 @@ interface AgentManifestTool {
     audit: boolean;
 }
 /**
- * Generate a serializable agent manifest from walked metadata.
+ * Generate a serializable agent manifest from an {@link AgentManifestSource} per agent.
  * All Function references are converted to string names for JSON safety.
  */
-declare function generateAgentManifest(walkResults: AgentWalkResult[]): AgentManifest;
+declare function generateAgentManifest(sources: AgentManifestSource[]): AgentManifest;
 
 /**
  * agentsPlugin() — TheoKit dev-server plugin for agent routes.
@@ -1746,13 +2012,19 @@ declare function generateAgentManifest(walkResults: AgentWalkResult[]): AgentMan
  * Per ADR D6: structural { name, register } shape (no compile-time theokit dep).
  */
 
+/**
+ * An agent the plugin mounts: its name, route and already-compiled options (from `applyCapabilities`).
+ */
+interface PluginAgentEntry {
+    readonly name: string;
+    readonly route: string;
+    readonly compiled: CompiledAgentOptions;
+}
 interface AgentsPluginOptions {
-    /** Agent classes decorated with @Agent(). */
-    agents: Function[];
-    /** Toolbox classes (or use @Mixin on agents). */
-    toolboxes?: Function[];
+    /** Agents to mount: prepared entries built by `applyCapabilities`. */
+    agents: PluginAgentEntry[];
     /** Factory that creates agent runs — bridges to SDK Agent.create() + agent.send(). */
-    createRunFactory?: (compiled: CompiledAgentOptions, walkResult: AgentWalkResult) => (message: string, sessionId: string) => AsyncIterable<StreamEvent>;
+    createRunFactory?: (compiled: CompiledAgentOptions) => (message: string, sessionId: string) => AsyncIterable<StreamEvent>;
 }
 interface PluginApp {
     addHook(name: string, fn: (ctx: {
@@ -1768,4 +2040,4 @@ declare function agentsPlugin(opts: AgentsPluginOptions): {
     register(app: PluginApp): void;
 };
 
-export { type McpRegistryConfig as $, type AgentManifestEntry as A, type BackgroundDelegation as B, type CompiledAgentOptions as C, type DelegationResult as D, type CheckpointSavedEvent as E, type CompiledContextWindow as F, type ContextualTool as G, DEFAULT_MAX_ITERATIONS as H, type DefineAgentConfig as I, type DelegateFn as J, type DelegateOptions as K, type LoopStrategy as L, DelegationError as M, type DoneEvent as N, type ErrorEvent as O, type FileEditEvent as P, type HitlDecision as Q, type ReflectionStrategy as R, type StreamEvent as S, type InferAgentInput as T, type InferAgentToolNames as U, type IterationEvent as V, type LLMCallContext as W, type LoopFinishReason as X, type LoopOutcome as Y, type LoopStrategyConfig as Z, type McpApprovalSpec as _, type CompiledTool as a, projectContextMetadataOnlyKnobs as a$, type McpRequestContext as a0, type McpSelection as a1, type PartialToolCallEvent as a2, type ProcessInputContext as a3, type ReflectionContext as a4, type ReflectionResult as a5, type ReflectionStrategyConfig as a6, type RunStartedEvent as a7, type ScoreVerdict as a8, type ScoredDelegation as a9, contextualTool as aA, createAgentExecutionContext as aB, createApiErrorHandler as aC, createSdkAgentStream as aD, createThinkTagExtractor as aE, createToolHooksPlugin as aF, delegate as aG, delegateBackground as aH, delegateWithScoring as aI, extractThinkTagStream as aJ, generateAgentManifest as aK, generateAgentRoutes as aL, isAgentContext as aM, isAgentDefinition as aN, isApprovalRequired as aO, isDone as aP, isError as aQ, isPartialToolCall as aR, isTextDelta as aS, isToolCall as aT, isToolResult as aU, ladderReflectionStrategy as aV, loopStrategyConfigSchema as aW, mcpRegistry as aX, mcpToolApprovals as aY, noopReflectionStrategy as aZ, presentUIMessageStream as a_, type Scorer as aa, type SdkAgentHandle as ab, type SdkMessage as ac, type Segment as ad, type SkillsRequestContext as ae, type SkillsSelection as af, type StateUpdateEvent as ag, type TextDeltaEvent as ah, type ThinkingEvent as ai, type ToolCallEvent as aj, type ToolCallVeto as ak, type ToolHooks as al, type ToolHooksPlugin as am, type ToolResultEvent as an, type ToolWalkResult as ao, type ToolboxWalkResult as ap, agent as aq, agentsPlugin as ar, buildModelSelection as as, compileAgent as at, compileAgentDefinition as au, compileAgentModule as av, compileContextWindow as aw, compileProjectContext as ax, compileSkills as ay, compileTools as az, type RoundStreamFactory as b, reflectionStrategyConfigSchema as b0, resolveEnabledSkills as b1, resolveLoopStrategy as b2, resolveMcpServers as b3, runWithApiErrorHandling as b4, streamAgentResponse as b5, streamAgentUIMessages as b6, toAgentFactory as b7, translateSdkEvent as b8, validateUniqueRoutes as b9, walkAgentMetadata as ba, 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 AgentTurnMetadata as o, type AgentWalkResult as p, AgentWarningCode as q, type AgentsPluginOptions as r, type ApiErrorContext as s, type ApiErrorDecision as t, type ApiErrorPolicy as u, type ApprovalRequiredEvent as v, type ArtifactChunkEvent as w, type ArtifactStartEvent as x, type BeforeToolCallContext as y, BudgetExceededError as z };
+export { type DelegateOptions as $, type ApprovalOptions as A, type ApiErrorDecision as B, type CompiledAgentOptions as C, type DelegationResult as D, type ApiErrorPolicy as E, type ApprovalRequiredEvent as F, type Guardrail as G, type HumanInTheLoopOptions as H, type ArtifactChunkEvent as I, type ArtifactStartEvent as J, type BackgroundDelegation as K, type LoopStrategy as L, type MainLoopMeta as M, type BeforeToolCallContext as N, BudgetExceededError as O, type ProjectContextOptions as P, type BudgetOptions as Q, type ReflectionStrategy as R, type StreamEvent as S, type ToolOptions as T, type CheckpointSavedEvent as U, type CompiledContextWindow as V, type ContextualTool as W, CostBudgetExceededError as X, DEFAULT_MAX_ITERATIONS as Y, type DefineAgentConfig as Z, type DelegateFn as _, type CompiledTool as a, delegateBackground as a$, DelegationError as a0, type DoneEvent as a1, type ErrorEvent as a2, type FileEditEvent as a3, type GuardrailAction as a4, type GuardrailPhase as a5, type GuardrailResult as a6, GuardrailViolationError as a7, type HitlDecision as a8, type InferAgentInput as a9, type TextDeltaEvent as aA, type ThinkingEvent as aB, type TimeoutAction as aC, type ToolCallEvent as aD, type ToolCallVeto as aE, type ToolHooks as aF, type ToolHooksPlugin as aG, type ToolResultEvent as aH, type ToolWalkResult as aI, type ToolboxOptions as aJ, type ToolboxWalkResult as aK, agent as aL, agentsPlugin as aM, buildModelSelection as aN, compileAgentDefinition as aO, compileAgentModule as aP, compileContextWindow as aQ, compileProjectContext as aR, compileSkills as aS, compileTools as aT, contextualTool as aU, createAgentExecutionContext as aV, createApiErrorHandler as aW, createSdkAgentStream as aX, createThinkTagExtractor as aY, createToolHooksPlugin as aZ, delegate as a_, type InferAgentToolNames as aa, type IterationEvent as ab, type LLMCallContext as ac, type LoopFinishReason as ad, type LoopOutcome as ae, type LoopStrategyConfig as af, type MainLoopOptions as ag, type McpApprovalSpec as ah, type McpRegistryConfig as ai, type McpRequestContext as aj, type McpSelection as ak, type PartialToolCallEvent as al, type PolicyHandler as am, type ProcessInputContext as an, type ReflectionContext as ao, type ReflectionResult as ap, type ReflectionStrategyConfig as aq, type RunStartedEvent as ar, type ScoreVerdict as as, type ScoredDelegation as at, type Scorer as au, type SdkAgentHandle as av, type SdkMessage as aw, type Segment as ax, type SkillsRequestContext as ay, type StateUpdateEvent as az, type ReasoningEffort as b, delegateWithScoring as b0, extractThinkTagStream as b1, generateAgentManifest as b2, generateAgentRoutes as b3, isAgentContext as b4, isAgentDefinition as b5, isApprovalRequired as b6, isDone as b7, isError as b8, isPartialToolCall as b9, isTextDelta as ba, isToolCall as bb, isToolResult as bc, ladderReflectionStrategy as bd, loopStrategyConfigSchema as be, mcpRegistry as bf, mcpToolApprovals as bg, noopReflectionStrategy as bh, presentUIMessageStream as bi, projectContextMetadataOnlyKnobs as bj, reflectionStrategyConfigSchema as bk, resolveEnabledSkills as bl, resolveLoopStrategy as bm, resolveMcpServers as bn, runWithApiErrorHandling as bo, streamAgentResponse as bp, streamAgentUIMessages as bq, toAgentFactory as br, translateSdkEvent as bs, type RoundStreamFactory as c, type ContextWindowOptions as d, type McpServersMap as e, type MemoryOptions as f, type SkillsOptions as g, type SkillsSelection as h, type AgentManifestEntry as i, AGENT_BRAND as j, type AfterToolCallContext as k, type AgentBuilder as l, type AgentDefinition as m, AgentDefinitionError as n, type AgentExecutionContext as o, type AgentManifest as p, type AgentManifestSource as q, type AgentManifestTool as r, type AgentOptions as s, type AgentRoute as t, type AgentRouteContext as u, type AgentRunInfo as v, type AgentStreamEvent as w, type AgentTurnMetadata as x, type AgentsPluginOptions as y, type ApiErrorContext as z };