@theokit/agents 0.46.0 → 1.0.0

package/dist/index.d.ts

@@ -1,8 +1,7 @@
-import { G as Guardrail, R as ReasoningEffort } from './types-DVA4LQsA.js';
-export { A as AgentOptions, a as ApprovalOptions, B as BudgetOptions, C as CostBudgetExceededError, b as GuardrailAction, c as GuardrailPhase, d as GuardrailResult, e as GuardrailViolationError, H as HumanInTheLoopOptions, M as MainLoopMeta, f as MainLoopOptions, P as PolicyHandler, T as TimeoutAction, g as ToolOptions, h as ToolboxOptions } from './types-DVA4LQsA.js';
-import { L as LoopStrategy, R as ReflectionStrategy, C as CompiledAgentOptions, a as CompiledTool, b as RoundStreamFactory, S as StreamEvent, D as DelegationResult, A as AgentManifestEntry } from './bridge-entry-BQ6UUSLZ.js';
-export { c as AGENT_BRAND, d as AfterToolCallContext, e as AgentBuilder, f as AgentDefinition, g as AgentDefinitionError, h as AgentExecutionContext, i as AgentManifest, j as AgentManifestTool, k as AgentRoute, l as AgentRouteContext, m as AgentRunInfo, n as AgentStreamEvent, o as AgentTurnMetadata, p as AgentWalkResult, q as AgentWarningCode, r as AgentsPluginOptions, s as ApiErrorContext, t as ApiErrorDecision, u as ApiErrorPolicy, v as ApprovalRequiredEvent, w as ArtifactChunkEvent, x as ArtifactStartEvent, B as BackgroundDelegation, y as BeforeToolCallContext, z as BudgetExceededError, E as CheckpointSavedEvent, F as CompiledContextWindow, G as ContextualTool, H as DEFAULT_MAX_ITERATIONS, I as DefineAgentConfig, J as DelegateFn, K as DelegateOptions, M as DelegationError, N as DoneEvent, O as ErrorEvent, P as FileEditEvent, Q as HitlDecision, T as InferAgentInput, U as InferAgentToolNames, V as IterationEvent, W as LLMCallContext, X as LoopFinishReason, Y as LoopOutcome, Z as LoopStrategyConfig, _ as McpApprovalSpec, $ as McpRegistryConfig, a0 as McpRequestContext, a1 as McpSelection, a2 as PartialToolCallEvent, a3 as ProcessInputContext, a4 as ReflectionContext, a5 as ReflectionResult, a6 as ReflectionStrategyConfig, a7 as RunStartedEvent, a8 as ScoreVerdict, a9 as ScoredDelegation, aa as Scorer, ab as SdkAgentHandle, ac as SdkMessage, ad as Segment, ae as SkillsRequestContext, af as SkillsSelection, ag as StateUpdateEvent, ah as TextDeltaEvent, ai as ThinkingEvent, aj as ToolCallEvent, ak as ToolCallVeto, al as ToolHooks, am as ToolHooksPlugin, an as ToolResultEvent, ao as ToolWalkResult, ap as ToolboxWalkResult, aq as agent, ar as agentsPlugin, as as buildModelSelection, at as compileAgent, au as compileAgentDefinition, av as compileAgentModule, aw as compileContextWindow, ax as compileProjectContext, ay as compileSkills, az as compileTools, aA as contextualTool, aB as createAgentExecutionContext, aC as createApiErrorHandler, aD as createSdkAgentStream, aE as createThinkTagExtractor, aF as createToolHooksPlugin, aG as delegate, aH as delegateBackground, aI as delegateWithScoring, aJ as extractThinkTagStream, aK as generateAgentManifest, aL as generateAgentRoutes, aM as isAgentContext, aN as isAgentDefinition, aO as isApprovalRequired, aP as isDone, aQ as isError, aR as isPartialToolCall, aS as isTextDelta, aT as isToolCall, aU as isToolResult, aV as ladderReflectionStrategy, aW as loopStrategyConfigSchema, aX as mcpRegistry, aY as mcpToolApprovals, aZ as noopReflectionStrategy, a_ as presentUIMessageStream, a$ as projectContextMetadataOnlyKnobs, b0 as reflectionStrategyConfigSchema, b1 as resolveEnabledSkills, b2 as resolveLoopStrategy, b3 as resolveMcpServers, b4 as runWithApiErrorHandling, b5 as streamAgentResponse, b6 as streamAgentUIMessages, b7 as toAgentFactory, b8 as translateSdkEvent, b9 as validateUniqueRoutes, ba as walkAgentMetadata } from './bridge-entry-BQ6UUSLZ.js';
-import { PluginsSettings, Plugin, ProviderRoutingSettings, AgentDefinition, BudgetTracker, CustomTool } from '@theokit/sdk';
+import { G as Guardrail, L as LoopStrategy, R as ReflectionStrategy, C as CompiledAgentOptions, M as MainLoopMeta, a as CompiledTool, b as ReasoningEffort, c as RoundStreamFactory, S as StreamEvent, D as DelegationResult, d as ContextWindowOptions, H as HumanInTheLoopOptions, e as McpServersMap, f as MemoryOptions, P as ProjectContextOptions, g as SkillsOptions, h as SkillsSelection, T as ToolOptions, A as ApprovalOptions, i as AgentManifestEntry } from './bridge-entry-F9kHGaIn.js';
+export { j as AGENT_BRAND, k as AfterToolCallContext, l as AgentBuilder, m as AgentDefinition, n as AgentDefinitionError, o as AgentExecutionContext, p as AgentManifest, q as AgentManifestSource, r as AgentManifestTool, s as AgentOptions, t as AgentRoute, u as AgentRouteContext, v as AgentRunInfo, w as AgentStreamEvent, x as AgentTurnMetadata, y as AgentsPluginOptions, z as ApiErrorContext, B as ApiErrorDecision, E as ApiErrorPolicy, F as ApprovalRequiredEvent, I as ArtifactChunkEvent, J as ArtifactStartEvent, K as BackgroundDelegation, N as BeforeToolCallContext, O as BudgetExceededError, Q as BudgetOptions, U as CheckpointSavedEvent, V as CompiledContextWindow, W as ContextualTool, X as CostBudgetExceededError, Y as DEFAULT_MAX_ITERATIONS, Z as DefineAgentConfig, _ as DelegateFn, $ as DelegateOptions, a0 as DelegationError, a1 as DoneEvent, a2 as ErrorEvent, a3 as FileEditEvent, a4 as GuardrailAction, a5 as GuardrailPhase, a6 as GuardrailResult, a7 as GuardrailViolationError, a8 as HitlDecision, a9 as InferAgentInput, aa as InferAgentToolNames, ab as IterationEvent, ac as LLMCallContext, ad as LoopFinishReason, ae as LoopOutcome, af as LoopStrategyConfig, ag as MainLoopOptions, ah as McpApprovalSpec, ai as McpRegistryConfig, aj as McpRequestContext, ak as McpSelection, al as PartialToolCallEvent, am as PolicyHandler, an as ProcessInputContext, ao as ReflectionContext, ap as ReflectionResult, aq as ReflectionStrategyConfig, ar as RunStartedEvent, as as ScoreVerdict, at as ScoredDelegation, au as Scorer, av as SdkAgentHandle, aw as SdkMessage, ax as Segment, ay as SkillsRequestContext, az as StateUpdateEvent, aA as TextDeltaEvent, aB as ThinkingEvent, aC as TimeoutAction, aD as ToolCallEvent, aE as ToolCallVeto, aF as ToolHooks, aG as ToolHooksPlugin, aH as ToolResultEvent, aI as ToolWalkResult, aJ as ToolboxOptions, aK as ToolboxWalkResult, aL as agent, aM as agentsPlugin, aN as buildModelSelection, aO as compileAgentDefinition, aP as compileAgentModule, aQ as compileContextWindow, aR as compileProjectContext, aS as compileSkills, aT as compileTools, aU as contextualTool, aV as createAgentExecutionContext, aW as createApiErrorHandler, aX as createSdkAgentStream, aY as createThinkTagExtractor, aZ as createToolHooksPlugin, a_ as delegate, a$ as delegateBackground, b0 as delegateWithScoring, b1 as extractThinkTagStream, b2 as generateAgentManifest, b3 as generateAgentRoutes, b4 as isAgentContext, b5 as isAgentDefinition, b6 as isApprovalRequired, b7 as isDone, b8 as isError, b9 as isPartialToolCall, ba as isTextDelta, bb as isToolCall, bc as isToolResult, bd as ladderReflectionStrategy, be as loopStrategyConfigSchema, bf as mcpRegistry, bg as mcpToolApprovals, bh as noopReflectionStrategy, bi as presentUIMessageStream, bj as projectContextMetadataOnlyKnobs, bk as reflectionStrategyConfigSchema, bl as resolveEnabledSkills, bm as resolveLoopStrategy, bn as resolveMcpServers, bo as runWithApiErrorHandling, bp as streamAgentResponse, bq as streamAgentUIMessages, br as toAgentFactory, bs as translateSdkEvent } from './bridge-entry-F9kHGaIn.js';
+import * as _theokit_sdk from '@theokit/sdk';
+import { PluginsSettings, Plugin, ProviderRoutingSettings, AgentDefinition, BudgetTracker, CustomTool, InlineSkill } from '@theokit/sdk';
 import { RetryOptions } from '@theokit/sdk/retry';
 import { CompressibleMessage } from '@theokit/sdk/compaction';
 export { CompressibleMessage } from '@theokit/sdk/compaction';
@@ -170,9 +169,8 @@ declare const tokenBudgetCompactionStrategy: TranscriptCompactionStrategy;
 /**
  * AgentRunner — the imperative twin of `@MainLoop` (plan ADR D4, V4-B).
  *
- * `AgentRunner.builder(AgentClass).reflection().stream().build()` walks +
- * compiles the agent and resolves the SAME `{ compiled, loopStrategy }` that
- * `delegate()` resolves for the decorator path (two on-ramps, one runtime).
+ * `AgentRunner.fromSpec(spec).reflection().stream().build()` resolves the loop strategy from
+ * an already-compiled spec (the capability-authored agent). `delegate()` shares the same runtime.
  * `build()` is the compile boundary (no I/O, no IoC — standalone, mirrors
  * Spring's `ChatClient.builder(...).build()`); `stream()`/`run()` do the I/O via
  * `runReflectiveLoopStream` (the SAME loop `delegate()` drains — DRY, ADR 0031).
@@ -206,7 +204,7 @@ interface AgentRunnerRunOptions {
      * M1 (Axis-A SWAP): per-run extended-thinking effort. Merge-over-compiled —
      * `opts.reasoningEffort ?? compiled.reasoningEffort` (resolved in the adapter, single site).
      * Mapped to the SDK `ModelSelection.params` so the provider reasons (surfaced as `thinking`
-     * StreamEvents). Absent ⇒ the compiled `@Agent({ reasoningEffort })` (or none).
+     * StreamEvents). Absent ⇒ the compiled reasoning effort (or none).
      */
     readonly reasoningEffort?: ReasoningEffort;
     /**
@@ -287,7 +285,7 @@ interface AgentRunnerRunOptions {
     readonly retry?: RetryOptions;
 }
 /**
- * A built, runnable agent. Construct via {@link AgentRunner.builder} — the
+ * A built, runnable agent. Construct via {@link AgentRunner.fromSpec} — the
  * constructor takes already-resolved state and is an internal detail.
  */
 /** Already-resolved state handed to the {@link AgentRunner} constructor (internal). */
@@ -325,8 +323,8 @@ declare class AgentRunner {
      */
     readonly compaction?: TranscriptCompactionStrategy;
     constructor(state: AgentRunnerState);
-    /** Start a fluent builder for `AgentClass`. */
-    static builder(AgentClass: Function): AgentRunnerBuilder;
+    /** Start a fluent builder from an already-compiled spec. */
+    static fromSpec(spec: AgentRunnerSpec): AgentRunnerBuilder;
     /**
      * V4-D-stream: stream the agent's events LIVE across the reflective loop, returning
      * the aggregated {@link DelegationResult} as the generator's return value. This is the
@@ -340,13 +338,33 @@ declare class AgentRunner {
     /** Run the agent to a terminal result via the shared reflective loop (collect mode). */
     run(message: string, opts: AgentRunnerRunOptions): Promise<DelegationResult>;
 }
+/**
+ * M53 — what the runner actually needs in order to run: an already-compiled agent plus the two
+ * loop knobs. It used to derive all of this from `walkAgentMetadata`, which chained the runner to
+ * the decorator surface. `strategy` and `compaction` are the two non-waist channels ADR 0002 keeps
+ * (the builder's `.compaction()` already outranked the decorator; this just names the input).
+ */
+/**
+ * The already-compiled agent the runner executes. Field-compatible with `SubAgentSpec` on purpose —
+ * one spec drives both `AgentRunner.fromSpec` and `delegate`.
+ */
+interface AgentRunnerSpec {
+    readonly name: string;
+    readonly compiled: CompiledAgentOptions;
+    readonly strategy?: MainLoopMeta['strategy'];
+    readonly maxIterations?: number;
+    readonly compaction?: {
+        name: string;
+        keepTokens?: number;
+    };
+}
 /** Fluent builder — accumulates config; `build()` is the compile boundary. */
 declare class AgentRunnerBuilder {
-    private readonly AgentClass;
+    private readonly spec;
     private reflectionOverride?;
     private streamEnabled;
     private compactionOverride?;
-    constructor(AgentClass: Function);
+    constructor(spec: AgentRunnerSpec);
     /** Override the default reflection strategy (OCP — plan Drawback #2). No arg ⇒ keep default. */
     reflection(strategy?: ReflectionStrategy): this;
     /** Record the streaming preference (see {@link AgentRunner.streamEnabled}). */
@@ -359,10 +377,254 @@ declare class AgentRunnerBuilder {
     compaction(name: string, options?: {
         keepTokens?: number;
     }): this;
-    /** Walk + compile + resolve strategies — the compile→execute boundary (no I/O). */
+    /** Resolve strategies from the spec — the compile→execute boundary (no I/O). */
     build(): AgentRunner;
 }
 
+/**
+ * M52 — the capability layer: object-oriented, composable authoring that produces the EXISTING narrow
+ * waist (`CompiledAgentOptions`), which `assembleM8CreateOptions` already turns into `Agent.create`
+ * options. No new spec and no new adapter were invented (ADR-1/ADR-2) — a third representation would be
+ * the very duplication this initiative removes.
+ */
+/** Which capability contributed which fields — makes the wiring inspectable as DATA. */
+interface ProvenanceEntry {
+    readonly capability: string;
+    readonly contributed: readonly string[];
+}
+/** The mutable draft a capability enriches. `tools`/`agents` are pre-seeded (required in the waist). */
+interface CompiledAgentOptionsDraft extends Partial<Omit<CompiledAgentOptions, 'tools' | 'agents'>> {
+    tools: CompiledAgentOptions['tools'];
+    agents: CompiledAgentOptions['agents'];
+    readonly provenance: ProvenanceEntry[];
+}
+/**
+ * **Strategy + value-level Decorator.** N independent ways to enrich an agent (model, tools, skills,
+ * MCP, HITL…), added or removed without touching the builder — a central `switch` would violate OCP.
+ */
+interface Capability {
+    /** Stable identity — used for provenance and conflict messages. */
+    readonly name: string;
+    apply(draft: CompiledAgentOptionsDraft): void;
+}
+/** Two capabilities set the same scalar field to different values — a composition bug, never last-wins. */
+declare class CapabilityConflictError extends Error {
+    readonly name = "CapabilityConflictError";
+    constructor(field: string, previous: unknown, next: unknown, capability: string);
+}
+/**
+ * A fresh draft. `stream` is deliberately NOT seeded: a pre-seeded value would make
+ * `setOnce(draft, 'stream', false, …)` throw a conflict against a default nobody declared, so
+ * `stream: false` would be structurally unreachable. The default is applied at finalize instead.
+ */
+declare function createDraft(): CompiledAgentOptionsDraft;
+/** A draft that has been finalized — the waist's required `stream` is settled. */
+type FinalizedDraft = CompiledAgentOptionsDraft & {
+    stream: boolean;
+};
+/** Apply capabilities in declaration order (deterministic) and return the draft. */
+declare function applyCapabilities(capabilities: readonly Capability[], draft?: CompiledAgentOptionsDraft): FinalizedDraft;
+/** Set a scalar exactly once — fail-fast on a conflicting redeclaration (Rule 8). */
+declare function setOnce<K extends keyof CompiledAgentOptionsDraft>(draft: CompiledAgentOptionsDraft, field: K, value: CompiledAgentOptionsDraft[K], capability: string): void;
+
+/**
+ * M52 — three real capabilities proving the contract against genuine variation: one that VALIDATES and
+ * can conflict (model), one that ACCUMULATES (tools), and one that is pure DATA (skills — a plain
+ * factory, because a class with no behavior would be ceremony: KISS).
+ */
+/** Typed authoring failure — surfaced at build time, never a silent bad agent. */
+declare class ConfigurationError extends Error {
+    readonly name = "ConfigurationError";
+}
+/** Sets the model id (and optional reasoning effort). CLASS: it validates and can conflict. */
+declare class ModelCapability implements Capability {
+    private readonly id;
+    private readonly reasoningEffort?;
+    readonly name = "model";
+    constructor(id: string, reasoningEffort?: CompiledAgentOptionsDraft['reasoningEffort']);
+    apply(draft: CompiledAgentOptionsDraft): void;
+}
+/** Adds tools. CLASS: it ACCUMULATES (never overwrites), which is behavior worth owning. */
+declare class ToolsCapability implements Capability {
+    #private;
+    readonly name = "tools";
+    constructor(tools: readonly CompiledTool[]);
+    apply(draft: CompiledAgentOptionsDraft): void;
+}
+/**
+ * Enables skills by name. FUNCTION, not class: it carries no behavior beyond assignment — a class here
+ * would be ceremony (the honest counter-example to "everything must be a class").
+ */
+declare const skills: (entries: readonly (string | InlineSkill)[]) => Capability;
+
+/**
+ * M52 — resolution + composition. The registry is what unlocks FILE-BASED authoring (a config lists
+ * capability names): resolving name → capability without a switch that grows per feature (OCP).
+ */
+/** Fail-fast with the known set — never `undefined` leaking into the pipeline. */
+declare class UnknownCapabilityError extends Error {
+    readonly name = "UnknownCapabilityError";
+    constructor(requested: string, known: readonly string[]);
+}
+/** **Registry + Factory Method.** */
+declare class CapabilityRegistry {
+    #private;
+    register(name: string, factory: (arg: unknown) => Capability): this;
+    has(name: string): boolean;
+    names(): string[];
+    resolve(name: string, arg?: unknown): Capability;
+}
+/**
+ * **Composite** — a preset behaves like ONE capability, so a caller says `codingAgent()` instead of
+ * spreading an array at the call site. Members apply in declaration order (deterministic).
+ */
+declare class CapabilityPreset implements Capability {
+    #private;
+    readonly name: string;
+    constructor(name: string, members: readonly Capability[]);
+    apply(draft: CompiledAgentOptionsDraft): void;
+}
+
+/** `@Memory` → `memory`. */
+declare const memory: (value: NonNullable<MemoryOptions | _theokit_sdk.MemorySettings | undefined>) => Capability;
+/**
+ * `@ContextWindow` → `context`. DELEGATES to `compileContextWindow`, which is the canonical
+ * `ContextWindowOptions → ContextSettings` conversion (it also reports the metadata-only knobs).
+ * Taking a pre-converted value here would duplicate that knowledge — the exact divergence the M52
+ * zero-behavior proof caught in `skills`.
+ */
+declare const contextWindow: (options: ContextWindowOptions) => Capability;
+/** `@ProjectContext` → `projectContext`. */
+declare const projectContext: (value: ProjectContextOptions) => Capability;
+/** `@MCP` → `mcpServers`. */
+declare const mcpServers: (value: McpServersMap) => Capability;
+/** `@Guardrails` → `guardrails`. */
+declare const guardrails: (value: readonly Guardrail[]) => Capability;
+/**
+ * `@Checkpoint` → `checkpoint`. Carries the non-durable WARNING the metadata walk used to emit: only
+ * `'filesystem'` selects the SDK's durable store, so any other storage cannot resume across
+ * requests. The warning moves WITH the feature — a declared checkpoint that silently cannot resume
+ * is exactly the kind of no-op this project refuses to ship.
+ */
+declare const checkpoint: (options: CompiledAgentOptions["checkpoint"]) => Capability;
+/** `@HumanInTheLoop` → `hitl` (keyed `"<toolbox>.<tool>"`, as `compileHitlGates` keys it today). */
+declare const humanInTheLoop: (value: Map<string, HumanInTheLoopOptions>) => Capability;
+/**
+ * `@SubAgents` → `agents`. MERGES instead of `setOnce`: `agents` is a pre-seeded collection on the
+ * draft (`createDraft` gives it `{}`), so a `setOnce` would conflict against the seed itself — the
+ * same trap the pre-seeded `stream` sprang in M52. Merging also lets a preset declare a baseline
+ * child set that a call site extends.
+ */
+declare const subAgents: (children: CompiledAgentOptions["agents"]) => Capability;
+/**
+ * `@Skills({ include, autoDiscover })` → `skills`. Delegates to `compileSkills` (same reason as
+ * `contextWindow`). Distinct from the M52 `skills([...])`, which takes the plain name/inline list.
+ */
+declare const skillsOptions: (options: SkillsOptions) => Capability;
+/** Functional-path fields that had no decorator source — closing the gap list, not adding surface. */
+declare const settingSources: (value: readonly _theokit_sdk.SettingSource[]) => Capability;
+declare const plugins: (value: readonly unknown[]) => Capability;
+declare const runContext: (value: Record<string, unknown>) => Capability;
+declare const skillsResolver: (value: NonNullable<SkillsSelection | undefined>) => Capability;
+/** The scalar agent config (name/route are HTTP concerns, never agent config). */
+interface AgentConfig {
+    readonly systemPrompt?: CompiledAgentOptions['systemPrompt'];
+    readonly parseThinkTags?: boolean;
+    readonly stripToolDialect?: boolean;
+    readonly recoverLeakedToolCalls?: boolean;
+    readonly stream?: boolean;
+    readonly maxIterations?: number;
+    readonly timeoutMs?: number;
+}
+/**
+ * Scalar waist fields (formerly the `@Agent` options). CLASS, not a factory: it validates, and it is the one
+ * capability that writes fields another capability may legitimately override (see
+ * {@link MainLoopCapability}).
+ */
+declare class AgentConfigCapability implements Capability {
+    private readonly config;
+    readonly name = "agent-config";
+    constructor(config: AgentConfig);
+    apply(draft: CompiledAgentOptionsDraft): void;
+}
+/**
+ * `@MainLoop({ maxIterations, timeoutMs })` → the same two fields `@Agent` can write.
+ *
+ * PRECEDENCE, preserved deliberately: `compileAgent` resolves these as
+ * `mainLoop.x ?? agentConfig.x` — the main-loop declaration WINS when both are present. A plain
+ * `setOnce` would raise a conflict where the pipeline has a defined winner, so this capability
+ * OVERRIDES instead. That is the one place in the layer where a later write beats an earlier one,
+ * and it exists to keep behavior identical, not for convenience.
+ */
+declare class MainLoopCapability implements Capability {
+    private readonly config;
+    readonly name = "main-loop";
+    constructor(config: {
+        maxIterations?: number;
+        timeoutMs?: number;
+    });
+    apply(draft: CompiledAgentOptionsDraft): void;
+}
+
+/**
+ * M53 — tools without `@Toolbox`/`@Tool`.
+ *
+ * A toolbox class declares its tools as DATA (`static tools`) and keeps its handlers as ordinary
+ * methods; the capability takes an INSTANCE. That preserves what the decorators actually bought —
+ * grouping under a namespace and handlers bound to the instance (so a toolbox can hold state and
+ * injected dependencies) — with no metadata reflection at all.
+ *
+ * The compilation itself is NOT reimplemented: it delegates to `compileTools`, the same function the
+ * decorator path calls, so namespacing (`toolRuntimeName`), handler binding and the fail-fast checks
+ * stay in one place.
+ *
+ * @example
+ * ```ts
+ * class SupportTools {
+ *   static tools: ToolDeclaration[] = [
+ *     { name: 'search', description: 'Search tickets', input: z.object({ q: z.string() }), method: 'search' },
+ *   ]
+ *   async search({ q }: { q: string }): Promise<string> { return `found ${q}` }
+ * }
+ *
+ * const agent = applyCapabilities([
+ *   new ModelCapability('openai/gpt-5.4'),
+ *   new ToolboxCapability(new SupportTools(), { namespace: 'support' }),
+ * ])
+ * ```
+ */
+interface ToolDeclaration extends ToolOptions {
+    /** Method on the toolbox instance that implements this tool. */
+    readonly method: string;
+    /** Require human approval before the tool runs (surfaced in the manifest). */
+    readonly approval?: ApprovalOptions;
+    /** Gate the tool behind human-in-the-loop (M4). */
+    readonly hitl?: HumanInTheLoopOptions;
+    /** Manifest-only observability flags. */
+    readonly trace?: boolean;
+    readonly audit?: boolean;
+}
+/** A toolbox instance whose class declares its tools. */
+interface ToolboxSource {
+    readonly constructor: {
+        tools?: readonly ToolDeclaration[];
+    };
+}
+interface ToolboxOptions {
+    /** Prefix for every tool name (`"<namespace>.<tool>"`), as `@Toolbox({ namespace })` did. */
+    readonly namespace?: string;
+    /** Declarations, when they are not on the class as `static tools`. */
+    readonly tools?: readonly ToolDeclaration[];
+}
+declare class ToolboxCapability implements Capability {
+    #private;
+    readonly name = "toolbox";
+    constructor(instance: object, options?: ToolboxOptions);
+    /** The compiled tools this toolbox contributes — the same shape the decorator path produces. */
+    compile(): CompiledTool[];
+    apply(draft: CompiledAgentOptionsDraft): void;
+}
+
 /**
  * M15 (theokit-ai-first) — A2A agent card generation (ADR-0040 § D2, home/discovery concern).
  *
@@ -554,4 +816,4 @@ declare class AcpClient {
     private handleServerRequest;
 }
 
-export { type A2AAuth, type A2ACapabilities, type A2ASkill, type A2AToolConfig, AcpClient, AcpMessageDecoder, type AcpTransport, type AgentCard, AgentManifestEntry, AgentRunner, AgentRunnerBuilder, type AgentRunnerRunOptions, type BuildAgentCardOptions, type CompactionCallOptions, type CompactionStrategyConfig, CompiledAgentOptions, CompiledTool, type CostGuardOptions, DEFAULT_KEEP_TOKENS, DelegationResult, Guardrail, LoopStrategy, MCP_PROTOCOL_VERSION, type McpJsonSchema, type McpServerInfo, type McpToolDescriptor, type OutputModerationOptions, type PiiOptions, type PromptInjectionOptions, ReasoningEffort, ReflectionStrategy, RoundStreamFactory, StreamEvent, type Summarize, type TranscriptCompactionStrategy, buildAgentCard, buildMcpToolDescriptors, compactionStrategyConfigSchema, costGuard, createA2ATool, deriveConversationId, encodeAcpMessage, estimateTokens, mcpServerInfo, moderateOutputStream, outputModeration, parseConversationId, piiDetector, promptInjectionDetector, resolveCompactionStrategy, runInputGuards, runOutputGuards, tokenBudgetCompactionStrategy, unicodeNormalizer, wellKnownCardPath };
+export { type A2AAuth, type A2ACapabilities, type A2ASkill, type A2AToolConfig, AcpClient, AcpMessageDecoder, type AcpTransport, type AgentCard, type AgentConfig, AgentConfigCapability, AgentManifestEntry, AgentRunner, AgentRunnerBuilder, type AgentRunnerRunOptions, ApprovalOptions, type BuildAgentCardOptions, type Capability, CapabilityConflictError, CapabilityPreset, CapabilityRegistry, type CompactionCallOptions, type CompactionStrategyConfig, CompiledAgentOptions, type CompiledAgentOptionsDraft, CompiledTool, ConfigurationError, type CostGuardOptions, DEFAULT_KEEP_TOKENS, DelegationResult, type FinalizedDraft, Guardrail, HumanInTheLoopOptions, LoopStrategy, MCP_PROTOCOL_VERSION, MainLoopCapability, MainLoopMeta, type McpJsonSchema, type McpServerInfo, type McpToolDescriptor, ModelCapability, type OutputModerationOptions, type PiiOptions, type PromptInjectionOptions, type ProvenanceEntry, ReasoningEffort, ReflectionStrategy, RoundStreamFactory, SkillsSelection, StreamEvent, type Summarize, type ToolDeclaration, ToolOptions, ToolboxCapability, type ToolboxSource, ToolsCapability, type TranscriptCompactionStrategy, UnknownCapabilityError, applyCapabilities, buildAgentCard, buildMcpToolDescriptors, checkpoint, compactionStrategyConfigSchema, contextWindow, costGuard, createA2ATool, createDraft, deriveConversationId, encodeAcpMessage, estimateTokens, guardrails, humanInTheLoop, mcpServerInfo, mcpServers, memory, moderateOutputStream, outputModeration, parseConversationId, piiDetector, plugins, projectContext, promptInjectionDetector, resolveCompactionStrategy, runContext, runInputGuards, runOutputGuards, setOnce, settingSources, skills, skillsOptions, skillsResolver, subAgents, tokenBudgetCompactionStrategy, unicodeNormalizer, wellKnownCardPath };