@theokit/agents 0.43.0 → 0.44.0

package/dist/{bridge-entry-Bo3LsMQF.d.ts → bridge-entry-BW1ifbWg.d.ts}

@@ -1,8 +1,8 @@
 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, SkillsSettings, ContextSettings, PluginsSettings, Plugin, ProviderRoutingSettings, AgentDefinition as AgentDefinition$1, BudgetTracker, CustomTool, ModelSelection } from '@theokit/sdk';
-import { UIMessageChunk } from 'ai';
+import { InlineSkill, SystemPromptResolver, SettingSource, 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';
 
 /**
@@ -513,6 +513,114 @@ interface AgentRouteContext {
 /** Generate HTTP routes for a single agent. Returns Web Standard handlers. */
 declare function generateAgentRoutes(ctx: AgentRouteContext): AgentRoute[];
 
+/**
+ * M2 (theokit-ai-first) — `defineAgent`, the zero-config imperative agent surface.
+ *
+ * ADR-B1: `defineAgent({...})` (default-exported from a top-level `agents/<name>.ts`) is
+ * the canonical zero-config surface; the `@Agent` class decorator stays the advanced/DI
+ * surface. Both compile to {@link CompiledAgentOptions} and run through the same SDK
+ * runtime (`createSdkAgentStream`) — one runtime, two syntaxes.
+ *
+ * This module is PURE metadata (sdk-runtime.md / G2): `defineAgent` describes an agent, it
+ * NEVER calls an LLM. It imports only `zod` (types) + the compiler shape — no `theokit`
+ * core, preserving the agents → (nothing) dependency direction (G1).
+ */
+
+/**
+ * Brand tag for a `defineAgent` value. `Symbol.for` (global registry, not `Symbol()`) so
+ * the brand survives duplicate module instances (dual-package / bundling) — the scanner's
+ * brand-check then works regardless of which copy created the definition.
+ */
+declare const AGENT_BRAND: unique symbol;
+/** Config accepted by {@link defineAgent}. */
+interface DefineAgentConfig<TInput extends z.ZodType = z.ZodType> {
+    /** Zod schema for the request body — lifted into the typed client (M2, {@link InferAgentInput}). */
+    input?: TInput;
+    /** Model id (e.g. `claude-sonnet-4-6`). Falls back to the SDK default when omitted. */
+    model?: string;
+    /** Static system prompt. */
+    system?: string;
+    /** Extended-thinking effort (mirrors `@Agent({ reasoningEffort })`). */
+    reasoningEffort?: ReasoningEffort;
+    /**
+     * Pre-built tools. Accepts the `@theokit/sdk` `CustomTool` that `defineAgentTool`
+     * (theokit/server) and every `@theokit/sdk-tools` factory return (issue #81) — they are
+     * normalized to the internal {@link CompiledTool} shape at compile time.
+     */
+    tools?: readonly CustomTool[];
+    /**
+     * M7 — run-context: an opaque, per-agent object forwarded to every tool handler's
+     * `ctx.context` at run time (injected by the theokit adapter's tool wrapper). Set shared config
+     * (e.g. `{ projectRoot }`) ONCE at the agent level instead of baking it into each tool
+     * factory. Mirrors ai-sdk `experimental_context`, mastra `RuntimeContext`, and
+     * openai-agents-js `RunContext`. Distinct from `@Agent`'s context-window `context`.
+     */
+    context?: Record<string, unknown>;
+    /**
+     * M9 — guardrails: input/output guards applied at the framework boundary (ADR-0040 § D2).
+     * Input guards run on the user message before the SDK runtime; a `block` fails the run fast.
+     * Built-ins live in `@theokit/agents` (`promptInjectionDetector`, `piiDetector`, `costGuard`,
+     * `unicodeNormalizer`, `outputModeration`).
+     */
+    guardrails?: readonly Guardrail[];
+    /**
+     * M14 — HITL approvals keyed by tool name. Each gated tool pauses the run and emits an
+     * `approval_required` event until approved (reuses the same `compiled.hitl` wiring the `@Agent`
+     * + `@HumanInTheLoop` path produces). A key that does not match a declared tool fails fast at
+     * compile time.
+     */
+    approvals?: Record<string, HumanInTheLoopOptions>;
+    /**
+     * M13 — skills selection: a static list (compiled straight to the SDK `skills.enabled`) OR a
+     * per-request resolver `(ctx) => string[]` (carried on `compiled.skillsResolver`, resolved by the
+     * request path against the run-context). Absent ⇒ the SDK enables every discovered skill.
+     */
+    skills?: SkillsSelection;
+    /**
+     * theokit-file-based-config — opt into `.theokit/` file-based config (skills, subagents, hooks,
+     * MCP, context, cron). The SDK discovers config from these roots under the app's `cwd`:
+     * `"project"` = `<cwd>/.theokit/`, `"user"` = `~/.theokit/`. Absent ⇒ inline (code) config only.
+     * SECURITY: enabling `"project"` enables shell-executing hooks from `.theokit/hooks.json` — this
+     * is opt-in because `.theokit/` is the app's own repo (informed consent). The SDK owns discovery
+     * + execution (G2 / ADR-0040); theokit only wires this into `Agent.create({ local.settingSources })`.
+     */
+    settingSources?: readonly SettingSource[];
+    /**
+     * MCP servers available to the agent — the builder-chain equivalent of the `@MCP` class
+     * decorator. Each key is a server name; the value is the server configuration. Forwarded
+     * unchanged to `Agent.create({ mcpServers })` (the SDK owns MCP execution). Absent ⇒ no MCP.
+     */
+    mcpServers?: McpServersMap;
+}
+/**
+ * A branded agent definition — the value {@link defineAgent} returns.
+ *
+ * `TTools` (M8) is a phantom type parameter carrying the tool-name union: the `agent()` builder
+ * threads its accumulated literal tool names here (`.build()` returns `AgentDefinition<TInput,
+ * 'a' | 'b'>`), so the generated client (`.theokit/agents.d.ts`) can expose them via
+ * {@link InferAgentToolNames}. `defineAgent` leaves it `string` (its tools array carries no literal
+ * names). Never present at runtime.
+ */
+type AgentDefinition<TInput extends z.ZodType = z.ZodType, TTools extends string = string> = DefineAgentConfig<TInput> & {
+    readonly [AGENT_BRAND]: true;
+    readonly __toolNames?: TTools;
+};
+/** Infer the request type of an agent definition from its `input` Zod schema. */
+type InferAgentInput<T> = T extends AgentDefinition<infer S> ? (S extends z.ZodType ? z.infer<S> : never) : never;
+/**
+ * Infer the tool-name union of an agent definition (M8). Yields the literal union for agents built
+ * with the `agent()` builder (`'read_file' | 'count_lines'`), or `string` for `defineAgent` agents
+ * whose tools array carries no literal names.
+ */
+type InferAgentToolNames<T> = T extends AgentDefinition<z.ZodType, infer N> ? N : never;
+/** Brand-check: is `value` a {@link defineAgent} result? */
+declare function isAgentDefinition(value: unknown): value is AgentDefinition;
+/**
+ * Lower a definition to the SDK-ready {@link CompiledAgentOptions} — the same shape
+ * `compileAgent` (decorator path) produces, so both surfaces converge on one runtime.
+ */
+declare function compileAgentDefinition(def: AgentDefinition): CompiledAgentOptions;
+
 /**
  * SDK Adapter — bridges @theokit/agents decorators → @theokit/sdk runtime.
  *
@@ -597,6 +705,33 @@ interface RuntimeOverrides {
 declare function createSdkAgentStream(compiled: CompiledAgentOptions, compiledTools: CompiledTool[], apiKey: string, overrides?: RuntimeOverrides): (message: string, sessionId: string, factoryOpts?: {
     disableTools?: boolean;
 }) => AsyncIterable<StreamEvent>;
+/**
+ * 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}
+ * hands back without re-exporting the full `@theokit/sdk` `Agent` type.
+ */
+interface SdkAgentHandle {
+    readonly agentId: string;
+    send: (msg: string, opts?: unknown) => unknown;
+    dispose: () => Promise<void>;
+}
+/**
+ * #12 — bridge a builder/`defineAgent` {@link TheokitAgentDefinition} to a real `SDKAgent` FACTORY,
+ * so surfaces that require an `SDKAgent` (or `(sessionId) => SDKAgent`) — notably `theokit acp`,
+ * whose entry default-export must be one — can serve an agent defined with the `agent()` chain.
+ *
+ * The factory reuses the SAME projection the streaming path uses (`compileAgentDefinition` → tools /
+ * model / `assembleM8CreateOptions`), so the served agent has identical tools, model, system prompt,
+ * skills, and `mcpServers`. Keyed per `sessionId` via `Agent.getOrCreate` (matches the run path).
+ *
+ * NOTE: HITL approvals (`.approval(...)`) are driven by the framework's streaming runner, not by
+ * `Agent.create`; a raw `SDKAgent` from this factory does not auto-pause gated tools — the serving
+ * surface (e.g. the ACP client) owns approval. Tools still execute; they are simply not HITL-gated here.
+ */
+declare function toAgentFactory(def: AgentDefinition, opts: {
+    apiKey: string;
+    overrides?: RuntimeOverrides;
+}): (sessionId: string) => Promise<SdkAgentHandle>;
 
 /**
  * Model-selection mapping (M1 reasoning-visibility) — the single site that turns a
@@ -685,108 +820,6 @@ declare function translateToUIMessageStream(events: AsyncIterable<AgentStreamEve
     textId: string;
 }): AsyncGenerator<UIMessageChunk, void, unknown>;
 
-/**
- * M2 (theokit-ai-first) — `defineAgent`, the zero-config imperative agent surface.
- *
- * ADR-B1: `defineAgent({...})` (default-exported from a top-level `agents/<name>.ts`) is
- * the canonical zero-config surface; the `@Agent` class decorator stays the advanced/DI
- * surface. Both compile to {@link CompiledAgentOptions} and run through the same SDK
- * runtime (`createSdkAgentStream`) — one runtime, two syntaxes.
- *
- * This module is PURE metadata (sdk-runtime.md / G2): `defineAgent` describes an agent, it
- * NEVER calls an LLM. It imports only `zod` (types) + the compiler shape — no `theokit`
- * core, preserving the agents → (nothing) dependency direction (G1).
- */
-
-/**
- * Brand tag for a `defineAgent` value. `Symbol.for` (global registry, not `Symbol()`) so
- * the brand survives duplicate module instances (dual-package / bundling) — the scanner's
- * brand-check then works regardless of which copy created the definition.
- */
-declare const AGENT_BRAND: unique symbol;
-/** Config accepted by {@link defineAgent}. */
-interface DefineAgentConfig<TInput extends z.ZodType = z.ZodType> {
-    /** Zod schema for the request body — lifted into the typed client (M2, {@link InferAgentInput}). */
-    input?: TInput;
-    /** Model id (e.g. `claude-sonnet-4-6`). Falls back to the SDK default when omitted. */
-    model?: string;
-    /** Static system prompt. */
-    system?: string;
-    /** Extended-thinking effort (mirrors `@Agent({ reasoningEffort })`). */
-    reasoningEffort?: ReasoningEffort;
-    /**
-     * Pre-built tools. Accepts the `@theokit/sdk` `CustomTool` that `defineAgentTool`
-     * (theokit/server) and every `@theokit/sdk-tools` factory return (issue #81) — they are
-     * normalized to the internal {@link CompiledTool} shape at compile time.
-     */
-    tools?: readonly CustomTool[];
-    /**
-     * M7 — run-context: an opaque, per-agent object forwarded to every tool handler's
-     * `ctx.context` at run time (injected by the theokit adapter's tool wrapper). Set shared config
-     * (e.g. `{ projectRoot }`) ONCE at the agent level instead of baking it into each tool
-     * factory. Mirrors ai-sdk `experimental_context`, mastra `RuntimeContext`, and
-     * openai-agents-js `RunContext`. Distinct from `@Agent`'s context-window `context`.
-     */
-    context?: Record<string, unknown>;
-    /**
-     * M9 — guardrails: input/output guards applied at the framework boundary (ADR-0040 § D2).
-     * Input guards run on the user message before the SDK runtime; a `block` fails the run fast.
-     * Built-ins live in `@theokit/agents` (`promptInjectionDetector`, `piiDetector`, `costGuard`,
-     * `unicodeNormalizer`, `outputModeration`).
-     */
-    guardrails?: readonly Guardrail[];
-    /**
-     * M14 — HITL approvals keyed by tool name. Each gated tool pauses the run and emits an
-     * `approval_required` event until approved (reuses the same `compiled.hitl` wiring the `@Agent`
-     * + `@HumanInTheLoop` path produces). A key that does not match a declared tool fails fast at
-     * compile time.
-     */
-    approvals?: Record<string, HumanInTheLoopOptions>;
-    /**
-     * M13 — skills selection: a static list (compiled straight to the SDK `skills.enabled`) OR a
-     * per-request resolver `(ctx) => string[]` (carried on `compiled.skillsResolver`, resolved by the
-     * request path against the run-context). Absent ⇒ the SDK enables every discovered skill.
-     */
-    skills?: SkillsSelection;
-    /**
-     * theokit-file-based-config — opt into `.theokit/` file-based config (skills, subagents, hooks,
-     * MCP, context, cron). The SDK discovers config from these roots under the app's `cwd`:
-     * `"project"` = `<cwd>/.theokit/`, `"user"` = `~/.theokit/`. Absent ⇒ inline (code) config only.
-     * SECURITY: enabling `"project"` enables shell-executing hooks from `.theokit/hooks.json` — this
-     * is opt-in because `.theokit/` is the app's own repo (informed consent). The SDK owns discovery
-     * + execution (G2 / ADR-0040); theokit only wires this into `Agent.create({ local.settingSources })`.
-     */
-    settingSources?: readonly SettingSource[];
-}
-/**
- * A branded agent definition — the value {@link defineAgent} returns.
- *
- * `TTools` (M8) is a phantom type parameter carrying the tool-name union: the `agent()` builder
- * threads its accumulated literal tool names here (`.build()` returns `AgentDefinition<TInput,
- * 'a' | 'b'>`), so the generated client (`.theokit/agents.d.ts`) can expose them via
- * {@link InferAgentToolNames}. `defineAgent` leaves it `string` (its tools array carries no literal
- * names). Never present at runtime.
- */
-type AgentDefinition<TInput extends z.ZodType = z.ZodType, TTools extends string = string> = DefineAgentConfig<TInput> & {
-    readonly [AGENT_BRAND]: true;
-    readonly __toolNames?: TTools;
-};
-/** Infer the request type of an agent definition from its `input` Zod schema. */
-type InferAgentInput<T> = T extends AgentDefinition<infer S> ? (S extends z.ZodType ? z.infer<S> : never) : never;
-/**
- * Infer the tool-name union of an agent definition (M8). Yields the literal union for agents built
- * with the `agent()` builder (`'read_file' | 'count_lines'`), or `string` for `defineAgent` agents
- * whose tools array carries no literal names.
- */
-type InferAgentToolNames<T> = T extends AgentDefinition<z.ZodType, infer N> ? N : never;
-/** Brand-check: is `value` a {@link defineAgent} result? */
-declare function isAgentDefinition(value: unknown): value is AgentDefinition;
-/**
- * Lower a definition to the SDK-ready {@link CompiledAgentOptions} — the same shape
- * `compileAgent` (decorator path) produces, so both surfaces converge on one runtime.
- */
-declare function compileAgentDefinition(def: AgentDefinition): CompiledAgentOptions;
-
 /**
  * M8 — `agent()`, the fluent agent builder with accumulative **type-state**.
  *
@@ -894,6 +927,13 @@ interface AgentBuilder<TInput extends z.ZodType | UnsetMarker = UnsetMarker, TMo
      * shell-executing hooks from `.theokit/hooks.json` — opt-in because `.theokit/` is your own repo.
      */
     settingSources(sources: readonly SettingSource[]): AgentBuilder<TInput, TModel, TContext, TTools>;
+    /**
+     * Declare MCP (Model Context Protocol) servers available to this agent — the builder-chain
+     * equivalent of the `@MCP` class decorator. Each key is a server name; the value is its config
+     * (`command` / `args` / `env` / `cwd`). Forwarded to `Agent.create({ mcpServers })`; the SDK owns
+     * MCP execution. Call once — a later call replaces the map.
+     */
+    mcp(servers: McpServersMap): AgentBuilder<TInput, TModel, TContext, TTools>;
     /**
      * Apply a reusable partial chain (Spring-Boot-style composition). `preset` receives the current
      * builder and returns an advanced one; its accumulated type-state flows through.
@@ -1656,4 +1696,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, resolveEnabledSkills 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, createAgentExecutionContext as aA, createApiErrorHandler as aB, createSdkAgentStream as aC, createThinkTagExtractor as aD, createToolHooksPlugin as aE, delegate as aF, delegateBackground as aG, delegateWithScoring as aH, extractThinkTagStream as aI, generateAgentManifest as aJ, generateAgentRoutes as aK, isAgentContext as aL, isAgentDefinition as aM, isApprovalRequired as aN, isDone as aO, isError as aP, isPartialToolCall as aQ, isTextDelta as aR, isToolCall as aS, isToolResult as aT, ladderReflectionStrategy as aU, loopStrategyConfigSchema as aV, mcpRegistry as aW, mcpToolApprovals as aX, noopReflectionStrategy as aY, projectContextMetadataOnlyKnobs as aZ, reflectionStrategyConfigSchema as a_, type Scorer as aa, type SdkMessage as ab, type Segment as ac, type SkillsRequestContext as ad, type SkillsSelection as ae, type StateUpdateEvent as af, type TextDeltaEvent as ag, type ThinkingEvent as ah, type ToolCallEvent as ai, type ToolCallVeto as aj, type ToolHooks as ak, type ToolHooksPlugin as al, type ToolResultEvent as am, type ToolWalkResult as an, type ToolboxWalkResult as ao, agent as ap, agentsPlugin as aq, buildModelSelection as ar, compileAgent as as, compileAgentDefinition as at, compileAgentModule as au, compileContextWindow as av, compileProjectContext as aw, compileSkills as ax, compileTools as ay, contextualTool as az, type RoundStreamFactory as b, resolveLoopStrategy as b0, resolveMcpServers as b1, runWithApiErrorHandling as b2, streamAgentResponse as b3, streamAgentUIMessages as b4, translateSdkEvent as b5, translateToUIMessageStream as b6, validateUniqueRoutes as b7, walkAgentMetadata as b8, 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 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, reflectionStrategyConfigSchema 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, projectContextMetadataOnlyKnobs 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, resolveEnabledSkills as b0, resolveLoopStrategy as b1, resolveMcpServers as b2, runWithApiErrorHandling as b3, streamAgentResponse as b4, streamAgentUIMessages as b5, toAgentFactory as b6, translateSdkEvent as b7, translateToUIMessageStream 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 };

package/dist/bridge.d.ts

@@ -1,4 +1,4 @@
-export { c as AGENT_BRAND, d as AfterToolCallContext, e as AgentBuilder, f as AgentDefinition, g as AgentDefinitionError, h as AgentExecutionContext, i as AgentManifest, A as AgentManifestEntry, j as AgentManifestTool, k as AgentRoute, l as AgentRouteContext, m as AgentRunInfo, n as AgentStreamEvent, o as 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, C as CompiledAgentOptions, F as CompiledContextWindow, a as CompiledTool, G as ContextualTool, I as DefineAgentConfig, J as DelegateFn, K as DelegateOptions, M as DelegationError, D as DelegationResult, N as DoneEvent, O as ErrorEvent, P as FileEditEvent, T as InferAgentInput, U as InferAgentToolNames, V as IterationEvent, W as LLMCallContext, _ as McpApprovalSpec, $ as McpRegistryConfig, a0 as McpRequestContext, a1 as McpSelection, a2 as PartialToolCallEvent, a3 as ProcessInputContext, a7 as RunStartedEvent, a8 as ScoreVerdict, a9 as ScoredDelegation, aa as Scorer, ab as SdkMessage, ac as Segment, af as StateUpdateEvent, S as StreamEvent, ag as TextDeltaEvent, ah as ThinkingEvent, ai as ToolCallEvent, aj as ToolCallVeto, ak as ToolHooks, al as ToolHooksPlugin, am as ToolResultEvent, an as ToolWalkResult, ao as ToolboxWalkResult, ap as agent, aq as agentsPlugin, ar as buildModelSelection, as as compileAgent, at as compileAgentDefinition, au as compileAgentModule, av as compileContextWindow, aw as compileProjectContext, ax as compileSkills, ay as compileTools, az as contextualTool, aA as createAgentExecutionContext, aB as createApiErrorHandler, aC as createSdkAgentStream, aD as createThinkTagExtractor, aE as createToolHooksPlugin, aF as delegate, aG as delegateBackground, aH as delegateWithScoring, aI as extractThinkTagStream, aJ as generateAgentManifest, aK as generateAgentRoutes, aL as isAgentContext, aM as isAgentDefinition, aN as isApprovalRequired, aO as isDone, aP as isError, aQ as isPartialToolCall, aR as isTextDelta, aS as isToolCall, aT as isToolResult, aW as mcpRegistry, aX as mcpToolApprovals, aZ as projectContextMetadataOnlyKnobs, b1 as resolveMcpServers, b2 as runWithApiErrorHandling, b3 as streamAgentResponse, b4 as streamAgentUIMessages, b5 as translateSdkEvent, b6 as translateToUIMessageStream, b7 as validateUniqueRoutes, b8 as walkAgentMetadata } from './bridge-entry-Bo3LsMQF.js';
+export { c as AGENT_BRAND, d as AfterToolCallContext, e as AgentBuilder, f as AgentDefinition, g as AgentDefinitionError, h as AgentExecutionContext, i as AgentManifest, A as AgentManifestEntry, j as AgentManifestTool, k as AgentRoute, l as AgentRouteContext, m as AgentRunInfo, n as AgentStreamEvent, o as 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, C as CompiledAgentOptions, F as CompiledContextWindow, a as CompiledTool, G as ContextualTool, I as DefineAgentConfig, J as DelegateFn, K as DelegateOptions, M as DelegationError, D as DelegationResult, N as DoneEvent, O as ErrorEvent, P as FileEditEvent, T as InferAgentInput, U as InferAgentToolNames, V as IterationEvent, W as LLMCallContext, _ as McpApprovalSpec, $ as McpRegistryConfig, a0 as McpRequestContext, a1 as McpSelection, a2 as PartialToolCallEvent, a3 as ProcessInputContext, a7 as RunStartedEvent, a8 as ScoreVerdict, a9 as ScoredDelegation, aa as Scorer, ab as SdkAgentHandle, ac as SdkMessage, ad as Segment, ag as StateUpdateEvent, S as StreamEvent, 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, aX as mcpRegistry, aY as mcpToolApprovals, a_ as projectContextMetadataOnlyKnobs, b2 as resolveMcpServers, b3 as runWithApiErrorHandling, b4 as streamAgentResponse, b5 as streamAgentUIMessages, b6 as toAgentFactory, b7 as translateSdkEvent, b8 as translateToUIMessageStream, b9 as validateUniqueRoutes, ba as walkAgentMetadata } from './bridge-entry-BW1ifbWg.js';
 import '@theokit/http';
 import './types-DVA4LQsA.js';
 import '@theokit/sdk';

package/dist/bridge.js

@@ -42,11 +42,12 @@ import {
   runWithApiErrorHandling,
   streamAgentResponse,
   streamAgentUIMessages,
+  toAgentFactory,
   translateSdkEvent,
   translateToUIMessageStream,
   validateUniqueRoutes,
   walkAgentMetadata
-} from "./chunk-5VK63XGX.js";
+} from "./chunk-6WOLHCZB.js";
 import "./chunk-NERDIS45.js";
 import "./chunk-7QVYU63E.js";
 export {
@@ -93,6 +94,7 @@ export {
   runWithApiErrorHandling,
   streamAgentResponse,
   streamAgentUIMessages,
+  toAgentFactory,
   translateSdkEvent,
   translateToUIMessageStream,
   validateUniqueRoutes,

package/dist/{chunk-5VK63XGX.js → chunk-6WOLHCZB.js}

@@ -506,6 +506,107 @@ function generateAgentRoutes(ctx) {
 }
 __name(generateAgentRoutes, "generateAgentRoutes");
 
+// src/bridge/define-agent.ts
+var AGENT_BRAND = /* @__PURE__ */ Symbol.for("theokit.agent.definition");
+function defineAgent(config) {
+  return {
+    ...config,
+    [AGENT_BRAND]: true
+  };
+}
+__name(defineAgent, "defineAgent");
+function isAgentDefinition(value) {
+  return typeof value === "object" && value !== null && value[AGENT_BRAND] === true;
+}
+__name(isAgentDefinition, "isAgentDefinition");
+function toCompiledTool(tool) {
+  const handler = tool.handler;
+  const compiled = {
+    name: tool.name,
+    description: tool.description,
+    inputSchema: tool.inputSchema,
+    handler: /* @__PURE__ */ __name((input, ctx) => handler(input, ctx), "handler")
+  };
+  for (const sym of Object.getOwnPropertySymbols(tool)) {
+    ;
+    compiled[sym] = tool[sym];
+  }
+  return compiled;
+}
+__name(toCompiledTool, "toCompiledTool");
+function compileAgentDefinition(def) {
+  return {
+    model: def.model,
+    reasoningEffort: def.reasoningEffort,
+    systemPrompt: def.system,
+    tools: (def.tools ?? []).map(toCompiledTool),
+    agents: {},
+    stream: true,
+    // M7 — run-context flows to CompiledAgentOptions.runContext (distinct from the
+    // context-window `context` field the decorator path uses); absent ⇒ no key.
+    ...def.context !== void 0 ? {
+      runContext: def.context
+    } : {},
+    // M9 — guardrails flow through unchanged; the runner applies them at the input boundary.
+    ...def.guardrails !== void 0 ? {
+      guardrails: def.guardrails
+    } : {},
+    // M14 — HITL approvals compile into the same `hitl` map the decorator path produces.
+    ...def.approvals !== void 0 ? {
+      hitl: compileApprovals(def)
+    } : {},
+    // M13 — skills: a static list → SDK skills.enabled; a resolver → carried for the request path.
+    ...compileSkillsSelection(def.skills),
+    // theokit-file-based-config — the declared `.theokit/` sources flow to the run path, which
+    // projects them into `Agent.create({ local.settingSources })`; absent ⇒ inline config only.
+    ...def.settingSources !== void 0 ? {
+      settingSources: def.settingSources
+    } : {},
+    // MCP — builder/`defineAgent` servers converge on the same `mcpServers` field the `@MCP`
+    // decorator path populates; the SDK adapter forwards it to `Agent.create({ mcpServers })`.
+    ...def.mcpServers !== void 0 ? {
+      mcpServers: def.mcpServers
+    } : {}
+  };
+}
+__name(compileAgentDefinition, "compileAgentDefinition");
+function compileSkillsSelection(skills) {
+  if (skills === void 0) return {};
+  if (typeof skills === "function") return {
+    skillsResolver: skills
+  };
+  const enabled = [];
+  const inline = [];
+  for (const entry of skills) {
+    if (typeof entry === "string") enabled.push(entry);
+    else inline.push(entry);
+  }
+  return {
+    skills: {
+      enabled,
+      autoInject: true,
+      ...inline.length > 0 ? {
+        inline
+      } : {}
+    }
+  };
+}
+__name(compileSkillsSelection, "compileSkillsSelection");
+function compileApprovals(def) {
+  const toolNames = new Set((def.tools ?? []).map((t) => t.name));
+  const gates = /* @__PURE__ */ new Map();
+  for (const [toolName, options] of Object.entries(def.approvals ?? {})) {
+    if (!toolNames.has(toolName)) {
+      throw new Error(`[@theokit/agents] defineAgent approval references unknown tool "${toolName}". Declared tools: ${[
+        ...toolNames
+      ].join(", ") || "(none)"}.`);
+    }
+    gates.set(toolName, options);
+  }
+  return gates;
+}
+__name(compileApprovals, "compileApprovals");
+
 // src/bridge/event-translator.ts
 function asString(value, fallback) {
   if (typeof value === "string") return value;
@@ -1301,6 +1402,43 @@ async function* streamSdkAgent(rt, compiled, sdkTools, opts) {
   }
 }
 __name(streamSdkAgent, "streamSdkAgent");
+function toAgentFactory(def, opts) {
+  const compiled = compileAgentDefinition(def);
+  const overrides = opts.overrides ?? {};
+  const model = overrides.model ?? compiled.model ?? "openai/gpt-4o-mini";
+  const reasoningEffort = overrides.reasoningEffort ?? compiled.reasoningEffort;
+  const runContext = overrides.runContext ?? compiled.runContext;
+  return async (sessionId) => {
+    const rt = await loadSdkRuntime();
+    if (!rt) {
+      throw new Error("[@theokit/agents] @theokit/sdk is not installed \u2014 run: pnpm add @theokit/sdk");
+    }
+    const sdkTools = buildSdkTools(compiled.tools, rt.defineTool, overrides.sdkTools, runContext);
+    const inlineSkills = compiled.skills?.inline;
+    if (inlineSkills !== void 0 && inlineSkills.length > 0 && rt.defineSkillReadTool !== void 0 && !compiled.tools.some((t) => t.name === "skill_read")) {
+      sdkTools.push(rt.defineSkillReadTool(inlineSkills));
+    }
+    const { options: m8 } = assembleM8CreateOptions(compiled);
+    if (overrides.cwd !== void 0) m8.local = {
+      ...m8.local,
+      cwd: overrides.cwd
+    };
+    if (overrides.baseDir !== void 0) m8.local = {
+      ...m8.local,
+      baseDir: overrides.baseDir
+    };
+    const extra = buildExtraCreateOptions(overrides, compiled);
+    const agent2 = await rt.Agent.getOrCreate(sessionId, {
+      apiKey: opts.apiKey,
+      model: buildModelSelection(model, reasoningEffort),
+      tools: sdkTools,
+      ...m8,
+      ...extra
+    });
+    return agent2;
+  };
+}
+__name(toAgentFactory, "toAgentFactory");
 
 // src/bridge/ui-message-stream-translator.ts
 function* closeOpenBlock(state, textId) {
@@ -1487,97 +1625,6 @@ function doneToMetadata(event) {
 }
 __name(doneToMetadata, "doneToMetadata");
 
-// src/bridge/define-agent.ts
-var AGENT_BRAND = /* @__PURE__ */ Symbol.for("theokit.agent.definition");
-function defineAgent(config) {
-  return {
-    ...config,
-    [AGENT_BRAND]: true
-  };
-}
-__name(defineAgent, "defineAgent");
-function isAgentDefinition(value) {
-  return typeof value === "object" && value !== null && value[AGENT_BRAND] === true;
-}
-__name(isAgentDefinition, "isAgentDefinition");
-function toCompiledTool(tool) {
-  const handler = tool.handler;
-  return {
-    name: tool.name,
-    description: tool.description,
-    inputSchema: tool.inputSchema,
-    handler: /* @__PURE__ */ __name((input, ctx) => handler(input, ctx), "handler")
-  };
-}
-__name(toCompiledTool, "toCompiledTool");
-function compileAgentDefinition(def) {
-  return {
-    model: def.model,
-    reasoningEffort: def.reasoningEffort,
-    systemPrompt: def.system,
-    tools: (def.tools ?? []).map(toCompiledTool),
-    agents: {},
-    stream: true,
-    // M7 — run-context flows to CompiledAgentOptions.runContext (distinct from the
-    // context-window `context` field the decorator path uses); absent ⇒ no key.
-    ...def.context !== void 0 ? {
-      runContext: def.context
-    } : {},
-    // M9 — guardrails flow through unchanged; the runner applies them at the input boundary.
-    ...def.guardrails !== void 0 ? {
-      guardrails: def.guardrails
-    } : {},
-    // M14 — HITL approvals compile into the same `hitl` map the decorator path produces.
-    ...def.approvals !== void 0 ? {
-      hitl: compileApprovals(def)
-    } : {},
-    // M13 — skills: a static list → SDK skills.enabled; a resolver → carried for the request path.
-    ...compileSkillsSelection(def.skills),
-    // theokit-file-based-config — the declared `.theokit/` sources flow to the run path, which
-    // projects them into `Agent.create({ local.settingSources })`; absent ⇒ inline config only.
-    ...def.settingSources !== void 0 ? {
-      settingSources: def.settingSources
-    } : {}
-  };
-}
-__name(compileAgentDefinition, "compileAgentDefinition");
-function compileSkillsSelection(skills) {
-  if (skills === void 0) return {};
-  if (typeof skills === "function") return {
-    skillsResolver: skills
-  };
-  const enabled = [];
-  const inline = [];
-  for (const entry of skills) {
-    if (typeof entry === "string") enabled.push(entry);
-    else inline.push(entry);
-  }
-  return {
-    skills: {
-      enabled,
-      autoInject: true,
-      ...inline.length > 0 ? {
-        inline
-      } : {}
-    }
-  };
-}
-__name(compileSkillsSelection, "compileSkillsSelection");
-function compileApprovals(def) {
-  const toolNames = new Set((def.tools ?? []).map((t) => t.name));
-  const gates = /* @__PURE__ */ new Map();
-  for (const [toolName, options] of Object.entries(def.approvals ?? {})) {
-    if (!toolNames.has(toolName)) {
-      throw new Error(`[@theokit/agents] defineAgent approval references unknown tool "${toolName}". Declared tools: ${[
-        ...toolNames
-      ].join(", ") || "(none)"}.`);
-    }
-    gates.set(toolName, options);
-  }
-  return gates;
-}
-__name(compileApprovals, "compileApprovals");
-
 // src/bridge/agent-builder.ts
 function contextualTool(tool, _requiredContext) {
   return tool;
@@ -1642,6 +1689,10 @@ function makeBuilder(config) {
       ...config,
       settingSources: sources
     }), "settingSources"),
+    mcp: /* @__PURE__ */ __name((servers) => makeBuilder({
+      ...config,
+      mcpServers: servers
+    }), "mcp"),
     use: /* @__PURE__ */ __name((preset) => preset(runtime), "use"),
     build: /* @__PURE__ */ __name(() => defineAgent(config), "build")
   };
@@ -2966,15 +3017,16 @@ export {
   isError,
   isApprovalRequired,
   generateAgentRoutes,
+  AGENT_BRAND,
+  isAgentDefinition,
+  compileAgentDefinition,
   translateSdkEvent,
   buildModelSelection,
   createThinkTagExtractor,
   extractThinkTagStream,
   createSdkAgentStream,
+  toAgentFactory,
   translateToUIMessageStream,
-  AGENT_BRAND,
-  isAgentDefinition,
-  compileAgentDefinition,
   contextualTool,
   agent,
   AgentDefinitionError,
@@ -3017,4 +3069,4 @@ export {
   generateAgentManifest,
   agentsPlugin
 };
-//# sourceMappingURL=chunk-5VK63XGX.js.map
+//# sourceMappingURL=chunk-6WOLHCZB.js.map