@theokit/agents 0.47.0 → 1.0.0

package/dist/index.d.ts

@@ -1,7 +1,6 @@
-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 { 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';
@@ -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,7 +377,7 @@ 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;
 }
 
@@ -467,6 +485,146 @@ declare class CapabilityPreset implements 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).
  *
@@ -658,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 Capability, CapabilityConflictError, CapabilityPreset, CapabilityRegistry, type CompactionCallOptions, type CompactionStrategyConfig, CompiledAgentOptions, type CompiledAgentOptionsDraft, CompiledTool, ConfigurationError, type CostGuardOptions, DEFAULT_KEEP_TOKENS, DelegationResult, type FinalizedDraft, Guardrail, LoopStrategy, MCP_PROTOCOL_VERSION, type McpJsonSchema, type McpServerInfo, type McpToolDescriptor, ModelCapability, type OutputModerationOptions, type PiiOptions, type PromptInjectionOptions, type ProvenanceEntry, ReasoningEffort, ReflectionStrategy, RoundStreamFactory, StreamEvent, type Summarize, ToolsCapability, type TranscriptCompactionStrategy, UnknownCapabilityError, applyCapabilities, buildAgentCard, buildMcpToolDescriptors, compactionStrategyConfigSchema, costGuard, createA2ATool, createDraft, deriveConversationId, encodeAcpMessage, estimateTokens, mcpServerInfo, moderateOutputStream, outputModeration, parseConversationId, piiDetector, promptInjectionDetector, resolveCompactionStrategy, runInputGuards, runOutputGuards, setOnce, skills, 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 };

package/dist/index.js

@@ -3,7 +3,6 @@ import {
   AgentDefinitionError,
   AgentRunner,
   AgentRunnerBuilder,
-  AgentWarningCode,
   BudgetExceededError,
   CostBudgetExceededError,
   DEFAULT_KEEP_TOKENS,
@@ -14,7 +13,6 @@ import {
   agentsPlugin,
   buildModelSelection,
   compactionStrategyConfigSchema,
-  compileAgent,
   compileAgentDefinition,
   compileAgentModule,
   compileContextWindow,
@@ -68,11 +66,8 @@ import {
   toAgentFactory,
   tokenBudgetCompactionStrategy,
   translateSdkEvent,
-  unicodeNormalizer,
-  validateUniqueRoutes,
-  walkAgentMetadata
-} from "./chunk-FEH7JFH7.js";
-import "./chunk-NERDIS45.js";
+  unicodeNormalizer
+} from "./chunk-7KRJJX7W.js";
 import {
   __name
 } from "./chunk-7QVYU63E.js";
@@ -213,9 +208,7 @@ var skills = /* @__PURE__ */ __name((entries) => {
   return {
     name: "skills",
     apply: /* @__PURE__ */ __name((draft) => {
-      const compiled = compileSkillsSelection([
-        ...entries
-      ]);
+      const compiled = compileSkillsSelection(entries.slice());
       if (compiled.skills === void 0) return;
       const previous = draft.skills;
       draft.skills = previous === void 0 ? compiled.skills : {
@@ -296,6 +289,207 @@ var CapabilityPreset = class {
   }
 };
 
+// src/capability/agent-capabilities.ts
+function fieldCapability(name, field) {
+  return (value) => ({
+    name,
+    apply: /* @__PURE__ */ __name((draft) => {
+      setOnce(draft, field, value, name);
+    }, "apply")
+  });
+}
+__name(fieldCapability, "fieldCapability");
+var memory = fieldCapability("memory", "memory");
+var contextWindow = /* @__PURE__ */ __name((options) => ({
+  name: "context-window",
+  apply: /* @__PURE__ */ __name((draft) => {
+    setOnce(draft, "context", compileContextWindow(options).context, "context-window");
+  }, "apply")
+}), "contextWindow");
+var projectContext = fieldCapability("project-context", "projectContext");
+var mcpServers = fieldCapability("mcp", "mcpServers");
+var guardrails = fieldCapability("guardrails", "guardrails");
+var checkpoint = /* @__PURE__ */ __name((options) => ({
+  name: "checkpoint",
+  apply: /* @__PURE__ */ __name((draft) => {
+    if (options !== void 0 && options.storage !== "filesystem") {
+      console.warn(`[THEO_AGENT_CHECKPOINT_STORAGE_METADATA_ONLY] checkpoint({ storage: '${options.storage ?? "memory"}' }) does NOT resume across requests \u2014 only 'filesystem' selects the SDK's durable conversation store. Use checkpoint({ storage: 'filesystem' }) for cross-request resume.`);
+    }
+    setOnce(draft, "checkpoint", options, "checkpoint");
+  }, "apply")
+}), "checkpoint");
+var humanInTheLoop = fieldCapability("human-in-the-loop", "hitl");
+var subAgents = /* @__PURE__ */ __name((children) => ({
+  name: "sub-agents",
+  apply: /* @__PURE__ */ __name((draft) => {
+    for (const [name, child] of Object.entries(children)) {
+      if (name in draft.agents && draft.agents[name] !== child) {
+        throw new ConfigurationError(`sub-agents: filho "${name}" declarado duas vezes com defini\xE7\xF5es diferentes`);
+      }
+      draft.agents[name] = child;
+    }
+    draft.provenance.push({
+      capability: "sub-agents",
+      contributed: [
+        "agents"
+      ]
+    });
+  }, "apply")
+}), "subAgents");
+var skillsOptions = /* @__PURE__ */ __name((options) => ({
+  name: "skills",
+  apply: /* @__PURE__ */ __name((draft) => {
+    setOnce(draft, "skills", compileSkills(options), "skills");
+  }, "apply")
+}), "skillsOptions");
+var settingSources = fieldCapability("setting-sources", "settingSources");
+var plugins = fieldCapability("plugins", "plugins");
+var runContext = fieldCapability("run-context", "runContext");
+var skillsResolver = fieldCapability("skills-resolver", "skillsResolver");
+var AgentConfigCapability = class {
+  static {
+    __name(this, "AgentConfigCapability");
+  }
+  config;
+  name = "agent-config";
+  constructor(config) {
+    this.config = config;
+    if (typeof config !== "object" || config === null) {
+      throw new ConfigurationError("agent-config: esperava um objeto de configura\xE7\xE3o");
+    }
+    for (const field of [
+      "maxIterations",
+      "timeoutMs"
+    ]) {
+      const value = config[field];
+      if (value !== void 0 && (!Number.isFinite(value) || value <= 0)) {
+        throw new ConfigurationError(`agent-config: \`${field}\` deve ser um n\xFAmero positivo`);
+      }
+    }
+  }
+  apply(draft) {
+    const claimedByMainLoop = /* @__PURE__ */ __name((field) => draft.provenance.some((p) => p.capability === "main-loop" && p.contributed.includes(field)), "claimedByMainLoop");
+    if (!claimedByMainLoop("maxIterations")) {
+      setOnce(draft, "maxIterations", this.config.maxIterations, this.name);
+    }
+    if (!claimedByMainLoop("timeoutMs")) {
+      setOnce(draft, "timeoutMs", this.config.timeoutMs, this.name);
+    }
+    setOnce(draft, "systemPrompt", this.config.systemPrompt, this.name);
+    setOnce(draft, "parseThinkTags", this.config.parseThinkTags, this.name);
+    setOnce(draft, "stripToolDialect", this.config.stripToolDialect, this.name);
+    setOnce(draft, "recoverLeakedToolCalls", this.config.recoverLeakedToolCalls, this.name);
+    setOnce(draft, "stream", this.config.stream, this.name);
+  }
+};
+var MainLoopCapability = class {
+  static {
+    __name(this, "MainLoopCapability");
+  }
+  config;
+  name = "main-loop";
+  constructor(config) {
+    this.config = config;
+  }
+  apply(draft) {
+    const contributed = [];
+    if (this.config.maxIterations !== void 0) {
+      draft.maxIterations = this.config.maxIterations;
+      contributed.push("maxIterations");
+    }
+    if (this.config.timeoutMs !== void 0) {
+      draft.timeoutMs = this.config.timeoutMs;
+      contributed.push("timeoutMs");
+    }
+    if (contributed.length > 0) draft.provenance.push({
+      capability: this.name,
+      contributed
+    });
+  }
+};
+
+// src/capability/toolbox.ts
+var ToolboxCapability = class {
+  static {
+    __name(this, "ToolboxCapability");
+  }
+  name = "toolbox";
+  #instance;
+  #declarations;
+  #namespace;
+  constructor(instance, options = {}) {
+    if (typeof instance !== "object" || instance === null) {
+      throw new ConfigurationError("toolbox: esperava uma inst\xE2ncia de toolbox");
+    }
+    const declared = options.tools ?? instance.constructor.tools;
+    if (declared === void 0 || declared.length === 0) {
+      throw new ConfigurationError(`toolbox: ${instance.constructor.name} n\xE3o declara tools \u2014 use \`static tools = [...]\` ou a op\xE7\xE3o \`tools\``);
+    }
+    for (const tool of declared) {
+      if (typeof instance[tool.method] !== "function") {
+        throw new ConfigurationError(`toolbox: ${instance.constructor.name}.${tool.method} n\xE3o \xE9 um m\xE9todo (tool "${tool.name}")`);
+      }
+    }
+    this.#instance = instance;
+    this.#declarations = declared;
+    this.#namespace = options.namespace ?? "";
+  }
+  /** The compiled tools this toolbox contributes — the same shape the decorator path produces. */
+  compile() {
+    const token = this.#instance.constructor;
+    const walk = {
+      class: token,
+      namespace: this.#namespace,
+      guards: [],
+      tools: this.#declarations.map((tool) => ({
+        propertyKey: tool.method,
+        config: tool,
+        guards: [],
+        approval: tool.approval,
+        trace: tool.trace ?? false,
+        audit: tool.audit ?? false,
+        ...tool.hitl !== void 0 ? {
+          hitl: tool.hitl
+        } : {}
+      }))
+    };
+    return compileTools([
+      walk
+    ], /* @__PURE__ */ new Map([
+      [
+        token,
+        this.#instance
+      ]
+    ]));
+  }
+  apply(draft) {
+    draft.tools.push(...this.compile());
+    draft.provenance.push({
+      capability: this.name,
+      contributed: [
+        "tools"
+      ]
+    });
+    const gates = [];
+    for (const tool of this.#declarations) {
+      if (tool.hitl === void 0) continue;
+      gates.push([
+        this.#namespace === "" ? tool.name : `${this.#namespace}.${tool.name}`,
+        tool.hitl
+      ]);
+    }
+    if (gates.length === 0) return;
+    draft.hitl ??= /* @__PURE__ */ new Map();
+    for (const [key, options] of gates) draft.hitl.set(key, options);
+    draft.provenance.push({
+      capability: this.name,
+      contributed: [
+        "hitl"
+      ]
+    });
+  }
+};
+
 // src/a2a/agent-card.ts
 function trimTrailingSlash(url) {
   return url.endsWith("/") ? url.slice(0, -1) : url;
@@ -432,8 +626,12 @@ async function resolveEnabledSkills(selection, ctx) {
   if (!Array.isArray(resolved)) {
     throw new Error("[@theokit/agents] skills resolver must return an array of skill names");
   }
+  const names = resolved;
+  if (!names.every((n) => typeof n === "string" && n.trim().length > 0)) {
+    throw new Error("[@theokit/agents] skills resolver must return non-empty skill NAME strings");
+  }
   return [
-    ...resolved
+    ...names
   ];
 }
 __name(resolveEnabledSkills, "resolveEnabledSkills");
@@ -567,10 +765,10 @@ export {
   AGENT_BRAND,
   AcpClient,
   AcpMessageDecoder,
+  AgentConfigCapability,
   AgentDefinitionError,
   AgentRunner,
   AgentRunnerBuilder,
-  AgentWarningCode,
   BudgetExceededError,
   CapabilityConflictError,
   CapabilityPreset,
@@ -582,7 +780,9 @@ export {
   DelegationError,
   GuardrailViolationError,
   MCP_PROTOCOL_VERSION,
+  MainLoopCapability,
   ModelCapability,
+  ToolboxCapability,
   ToolsCapability,
   UnknownCapabilityError,
   agent,
@@ -591,14 +791,15 @@ export {
   buildAgentCard,
   buildMcpToolDescriptors,
   buildModelSelection,
+  checkpoint,
   compactionStrategyConfigSchema,
-  compileAgent,
   compileAgentDefinition,
   compileAgentModule,
   compileContextWindow,
   compileProjectContext,
   compileSkills,
   compileTools,
+  contextWindow,
   contextualTool,
   costGuard,
   createA2ATool,
@@ -617,6 +818,8 @@ export {
   extractThinkTagStream,
   generateAgentManifest,
   generateAgentRoutes,
+  guardrails,
+  humanInTheLoop,
   isAgentContext,
   isAgentDefinition,
   isApprovalRequired,
@@ -630,13 +833,17 @@ export {
   loopStrategyConfigSchema,
   mcpRegistry,
   mcpServerInfo,
+  mcpServers,
   mcpToolApprovals,
+  memory,
   moderateOutputStream,
   noopReflectionStrategy,
   outputModeration,
   parseConversationId,
   piiDetector,
+  plugins,
   presentUIMessageStream,
+  projectContext,
   projectContextMetadataOnlyKnobs,
   promptInjectionDetector,
   reflectionStrategyConfigSchema,
@@ -644,19 +851,22 @@ export {
   resolveEnabledSkills,
   resolveLoopStrategy,
   resolveMcpServers,
+  runContext,
   runInputGuards,
   runOutputGuards,
   runWithApiErrorHandling,
   setOnce,
+  settingSources,
   skills,
+  skillsOptions,
+  skillsResolver,
   streamAgentResponse,
   streamAgentUIMessages,
+  subAgents,
   toAgentFactory,
   tokenBudgetCompactionStrategy,
   translateSdkEvent,
   unicodeNormalizer,
-  validateUniqueRoutes,
-  walkAgentMetadata,
   wellKnownCardPath
 };
 //# sourceMappingURL=index.js.map