@theokit/agents 0.46.0 → 1.0.0

package/dist/{chunk-YBNKD5UM.js → chunk-7KRJJX7W.js}

@@ -1,50 +1,142 @@
-import {
-  AGENT_CONFIG,
-  AGENT_MAIN_LOOP,
-  Audit,
-  Budget,
-  RequiresApproval,
-  TOOLBOX_CONFIG,
-  TOOL_CONFIG,
-  TOOL_METHODS,
-  Trace,
-  getAgentConfig,
-  getCheckpointConfig,
-  getCompactionConfig,
-  getContextWindowConfig,
-  getGatewayConfig,
-  getGuardrailsConfig,
-  getHumanInTheLoopConfig,
-  getMcpConfig,
-  getMemoryConfig,
-  getMeta,
-  getMixins,
-  getProjectContextConfig,
-  getSkillsConfig,
-  getSubAgents
-} from "./chunk-NERDIS45.js";
 import {
   __name
 } from "./chunk-7QVYU63E.js";
 
-// src/bridge/agent-execution-context.ts
-function createAgentExecutionContext(base, agent2, run, toolCall) {
+// src/bridge/define-agent.ts
+var AGENT_BRAND = /* @__PURE__ */ Symbol.for("theokit.agent.definition");
+function defineAgent(config) {
   return {
-    getRequest: /* @__PURE__ */ __name(() => base.getRequest(), "getRequest"),
-    getUrl: /* @__PURE__ */ __name(() => base.getUrl(), "getUrl"),
-    getClass: /* @__PURE__ */ __name(() => base.getClass(), "getClass"),
-    getMethodName: /* @__PURE__ */ __name(() => base.getMethodName(), "getMethodName"),
-    getAgent: /* @__PURE__ */ __name(() => agent2, "getAgent"),
-    getRun: /* @__PURE__ */ __name(() => run, "getRun"),
-    getToolCall: /* @__PURE__ */ __name(() => toolCall ?? null, "getToolCall"),
-    isAgentContext: /* @__PURE__ */ __name(() => true, "isAgentContext")
+    ...config,
+    [AGENT_BRAND]: true
   };
 }
-__name(createAgentExecutionContext, "createAgentExecutionContext");
-function isAgentContext(ctx) {
-  return "isAgentContext" in ctx && ctx.isAgentContext();
+__name(defineAgent, "defineAgent");
+function isAgentDefinition(value) {
+  return typeof value === "object" && value !== null && value[AGENT_BRAND] === true;
 }
-__name(isAgentContext, "isAgentContext");
+__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
+    } : {},
+    // M49 — memory flows to the projection layer; `assembleM8CreateOptions` forwards it to Agent.create.
+    ...def.memory !== void 0 ? {
+      memory: def.memory
+    } : {},
+    // Hooks are converted here — the layer EVERY path converges on — rather than on the builder, so
+    // `defineAgent({ hooks })` cannot type-check and silently no-op. A lifecycle hook that is
+    // declared but never registered is a security gate that does not gate.
+    ...compileHooksAndPlugins(def),
+    // 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 compileHooksAndPlugins(def) {
+  const map = def.hooks;
+  const entries = Object.entries(map ?? {}).filter(([, h]) => typeof h === "function");
+  const explicit = def.plugins ?? [];
+  if (entries.length === 0) {
+    return def.plugins !== void 0 ? {
+      plugins: def.plugins
+    } : {};
+  }
+  const plugin = {
+    name: "theokit-builder-hooks",
+    version: "1.0.0",
+    kind: "general",
+    register(ctx) {
+      for (const [hookName, handler] of entries) {
+        ctx.on(hookName, handler);
+      }
+    }
+  };
+  return {
+    plugins: [
+      ...explicit,
+      plugin
+    ]
+  };
+}
+__name(compileHooksAndPlugins, "compileHooksAndPlugins");
+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/compile-context-window.ts
 var STRATEGY_KNOBS = [
@@ -67,198 +159,6 @@ function compileContextWindow(options) {
 }
 __name(compileContextWindow, "compileContextWindow");
 
-// src/bridge/compile-project-context.ts
-var UNMAPPED_KNOBS = [
-  "indexStrategy",
-  "relevanceStrategy",
-  "maxFilesInContext",
-  "includeExtensions",
-  "rootMarkers"
-];
-function projectContextMetadataOnlyKnobs(options) {
-  const opts = options;
-  return UNMAPPED_KNOBS.filter((knob) => opts[knob] !== void 0);
-}
-__name(projectContextMetadataOnlyKnobs, "projectContextMetadataOnlyKnobs");
-function compileProjectContext(options, base) {
-  return async (promptCtx) => {
-    const resolvedBase = typeof base === "function" ? await base(promptCtx) : base;
-    const cwd = promptCtx.cwd;
-    if (!cwd) {
-      return resolvedBase ?? "";
-    }
-    const { buildEnvContext, buildRepoMap } = await import("@theokit/sdk-tools");
-    const { readProjectInstructions } = await import("@theokit/sdk/project");
-    const env = buildEnvContext(cwd);
-    const repoMap = buildRepoMap(cwd, {
-      ignore: options.ignorePatterns
-    });
-    let instructions = "";
-    try {
-      instructions = (await readProjectInstructions(cwd)).content ?? "";
-    } catch {
-      instructions = "";
-    }
-    return [
-      env,
-      repoMap,
-      instructions,
-      resolvedBase
-    ].filter(Boolean).join("\n\n");
-  };
-}
-__name(compileProjectContext, "compileProjectContext");
-
-// src/bridge/walk-agent-metadata.ts
-import "reflect-metadata";
-import { Reflector } from "@theokit/http";
-var USE_GUARDS = /* @__PURE__ */ Symbol.for("theokit:http-decorators:use-guards");
-var USE_INTERCEPTORS = /* @__PURE__ */ Symbol.for("theokit:http-decorators:use-interceptors");
-var USE_FILTERS = /* @__PURE__ */ Symbol.for("theokit:http-decorators:use-filters");
-var AgentWarningCode = {
-  INTERCEPTOR_METADATA_ONLY: "THEO_AGENT_INTERCEPTOR_METADATA_ONLY",
-  FILTER_METADATA_ONLY: "THEO_AGENT_FILTER_METADATA_ONLY",
-  BUDGET_TOP_LEVEL_METADATA_ONLY: "THEO_AGENT_BUDGET_TOP_LEVEL_METADATA_ONLY",
-  CONTEXT_STRATEGY_METADATA_ONLY: "THEO_AGENT_CONTEXT_STRATEGY_METADATA_ONLY",
-  PROJECT_CONTEXT_KNOB_METADATA_ONLY: "THEO_AGENT_PROJECT_CONTEXT_KNOB_METADATA_ONLY",
-  CHECKPOINT_STORAGE_METADATA_ONLY: "THEO_AGENT_CHECKPOINT_STORAGE_METADATA_ONLY"
-};
-var reflectorInstance = new Reflector();
-function walkToolbox(ToolboxClass) {
-  const config = getMeta(TOOLBOX_CONFIG, ToolboxClass) ?? {};
-  const methods = getMeta(TOOL_METHODS, ToolboxClass) ?? [];
-  const classGuards = getMeta(USE_GUARDS, ToolboxClass) ?? [];
-  const tools = methods.map((propertyKey) => {
-    const toolConfig = getMeta(TOOL_CONFIG, ToolboxClass, propertyKey);
-    if (!toolConfig) {
-      throw new Error(`[@theokit/agents] Toolbox ${ToolboxClass.name}: method '${String(propertyKey)}' is in TOOL_METHODS but has no @Tool() config.`);
-    }
-    const methodGuards = getMeta(USE_GUARDS, ToolboxClass, propertyKey) ?? [];
-    const ref = reflectorInstance;
-    const approvalVal = ref.get(RequiresApproval, ToolboxClass, propertyKey);
-    const traceVal = ref.get(Trace, ToolboxClass, propertyKey);
-    const auditVal = ref.get(Audit, ToolboxClass, propertyKey);
-    return {
-      propertyKey,
-      config: toolConfig,
-      guards: [
-        ...classGuards,
-        ...methodGuards
-      ],
-      approval: approvalVal && typeof approvalVal === "object" && "reason" in approvalVal ? approvalVal : void 0,
-      capabilities: void 0,
-      budget: void 0,
-      trace: traceVal ?? false,
-      audit: auditVal ?? false,
-      hitl: getHumanInTheLoopConfig(ToolboxClass, propertyKey)
-    };
-  });
-  return {
-    class: ToolboxClass,
-    namespace: config.namespace ?? "",
-    tools,
-    guards: classGuards
-  };
-}
-__name(walkToolbox, "walkToolbox");
-function warnUnmappedDecoratorKnobs(agentName, contextWindow, projectContext) {
-  if (contextWindow) {
-    const { metadataOnlyKnobs } = compileContextWindow(contextWindow);
-    if (metadataOnlyKnobs.length > 0) {
-      console.warn(`[${AgentWarningCode.CONTEXT_STRATEGY_METADATA_ONLY}] Agent ${agentName}: @ContextWindow knob(s) ${metadataOnlyKnobs.join(", ")} are metadata-only \u2014 the SDK manages transcript compaction internally. Only maxTokens is forwarded to Agent.create({ context }).`);
-    }
-  }
-  if (projectContext) {
-    const unmapped = projectContextMetadataOnlyKnobs(projectContext);
-    if (unmapped.length > 0) {
-      console.warn(`[${AgentWarningCode.PROJECT_CONTEXT_KNOB_METADATA_ONLY}] Agent ${agentName}: @ProjectContext knob(s) ${unmapped.join(", ")} are metadata-only \u2014 the repo map is composed via buildRepoMap/buildEnvContext/readProjectInstructions; only ignorePatterns is forwarded.`);
-    }
-  }
-}
-__name(warnUnmappedDecoratorKnobs, "warnUnmappedDecoratorKnobs");
-function warnNonDurableCheckpoint(agentName, checkpoint) {
-  if (checkpoint && checkpoint.storage !== "filesystem") {
-    console.warn(`[${AgentWarningCode.CHECKPOINT_STORAGE_METADATA_ONLY}] Agent ${agentName}: @Checkpoint({ storage: '${checkpoint.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.`);
-  }
-}
-__name(warnNonDurableCheckpoint, "warnNonDurableCheckpoint");
-var agentWalkCache = /* @__PURE__ */ new WeakMap();
-function walkAgentMetadata(AgentClass, toolboxClasses = []) {
-  if (toolboxClasses.length === 0) {
-    const cached = agentWalkCache.get(AgentClass);
-    if (cached) return cached;
-  }
-  const agentConfig = getMeta(AGENT_CONFIG, AgentClass);
-  if (!agentConfig) {
-    throw new Error(`[@theokit/agents] Class ${AgentClass.name} is missing @Agent() decorator.`);
-  }
-  const mainLoop = getMeta(AGENT_MAIN_LOOP, AgentClass);
-  if (!mainLoop) {
-    throw new Error(`[@theokit/agents] Agent ${AgentClass.name} is missing @MainLoop() decorator. Decorate exactly one method with @MainLoop().`);
-  }
-  const guards = getMeta(USE_GUARDS, AgentClass) ?? [];
-  const interceptors = getMeta(USE_INTERCEPTORS, AgentClass) ?? [];
-  if (interceptors.length > 0) {
-    console.warn(`[${AgentWarningCode.INTERCEPTOR_METADATA_ONLY}] Agent ${AgentClass.name}: @UseInterceptors is metadata-only on agents and will not execute. Agent pipeline shares guards with HTTP but uses a distinct execution model. Interceptors are reserved for future agent-specific lifecycle hooks.`);
-  }
-  const filters = getMeta(USE_FILTERS, AgentClass) ?? [];
-  if (filters.length > 0) {
-    console.warn(`[${AgentWarningCode.FILTER_METADATA_ONLY}] Agent ${AgentClass.name}: @UseFilters is metadata-only on agents and will not catch agent runtime errors. Agent errors flow through SSE error events, not HTTP exception filters. Filters are reserved for future agent-specific error handling.`);
-  }
-  const agentBudget = reflectorInstance.get(Budget, AgentClass);
-  if (agentBudget) {
-    console.warn(`[${AgentWarningCode.BUDGET_TOP_LEVEL_METADATA_ONLY}] Agent ${AgentClass.name}: @Budget on top-level agents is metadata-only in this version. Budget enforcement currently applies to delegate() calls only. Top-level run enforcement will be wired through SDK cost tracking in a future release.`);
-  }
-  const toolboxes = toolboxClasses.map(walkToolbox);
-  const gateway = getGatewayConfig(AgentClass);
-  const subAgentClasses = getSubAgents(AgentClass);
-  const memory = getMemoryConfig(AgentClass);
-  const skills = getSkillsConfig(AgentClass);
-  const mcpServers = getMcpConfig(AgentClass);
-  const guardrails = getGuardrailsConfig(AgentClass);
-  const contextWindow = getContextWindowConfig(AgentClass);
-  const projectContext = getProjectContextConfig(AgentClass);
-  warnUnmappedDecoratorKnobs(AgentClass.name, contextWindow, projectContext);
-  const compaction = getCompactionConfig(AgentClass);
-  const checkpoint = getCheckpointConfig(AgentClass);
-  warnNonDurableCheckpoint(AgentClass.name, checkpoint);
-  const result = {
-    agentConfig,
-    mainLoop,
-    toolboxes,
-    guards,
-    interceptors,
-    filters,
-    route: agentConfig.route,
-    gateway,
-    subAgentClasses,
-    memory,
-    skills,
-    contextWindow,
-    projectContext,
-    mcpServers,
-    guardrails,
-    compaction,
-    checkpoint
-  };
-  if (toolboxClasses.length === 0) {
-    agentWalkCache.set(AgentClass, result);
-  }
-  return result;
-}
-__name(walkAgentMetadata, "walkAgentMetadata");
-function validateUniqueRoutes(results) {
-  const seen = /* @__PURE__ */ new Map();
-  for (const r of results) {
-    const existing = seen.get(r.route);
-    if (existing) {
-      throw new Error(`[@theokit/agents] Duplicate agent route '${r.route}': both '${existing}' and '${r.agentConfig.name}' declare it.`);
-    }
-    seen.set(r.route, r.agentConfig.name);
-  }
-}
-__name(validateUniqueRoutes, "validateUniqueRoutes");
-
 // src/bridge/compile-skills.ts
 function compileSkills(options) {
   if (options.autoDiscover) {
@@ -278,18 +178,6 @@ function toolRuntimeName(namespace, toolName) {
   return namespace ? `${namespace}.${toolName}` : toolName;
 }
 __name(toolRuntimeName, "toolRuntimeName");
-function compileHitlGates(toolboxes) {
-  const gates = /* @__PURE__ */ new Map();
-  for (const tb of toolboxes) {
-    for (const tool of tb.tools) {
-      if (tool.hitl) {
-        gates.set(toolRuntimeName(tb.namespace, tool.config.name), tool.hitl);
-      }
-    }
-  }
-  return gates;
-}
-__name(compileHitlGates, "compileHitlGates");
 function compileTools(toolboxes, toolboxInstances) {
   const tools = [];
   for (const tb of toolboxes) {
@@ -314,46 +202,67 @@ function compileTools(toolboxes, toolboxInstances) {
   return tools;
 }
 __name(compileTools, "compileTools");
-function compileSubAgents(subAgentClasses) {
-  const agents = {};
-  for (const cls of subAgentClasses) {
-    const config = getAgentConfig(cls);
-    if (!config) continue;
-    agents[config.name] = {
-      model: config.model,
-      systemPrompt: config.systemPrompt
-    };
-  }
-  return agents;
-}
-__name(compileSubAgents, "compileSubAgents");
-function compileAgent(walkResult, toolboxInstances = /* @__PURE__ */ new Map()) {
-  const tools = compileTools(walkResult.toolboxes, toolboxInstances);
-  const agents = compileSubAgents(walkResult.subAgentClasses);
-  const hitl = compileHitlGates(walkResult.toolboxes);
+
+// src/bridge/agent-execution-context.ts
+function createAgentExecutionContext(base, agent2, run, toolCall) {
   return {
-    model: walkResult.agentConfig.model,
-    reasoningEffort: walkResult.agentConfig.reasoningEffort,
-    parseThinkTags: walkResult.agentConfig.parseThinkTags,
-    stripToolDialect: walkResult.agentConfig.stripToolDialect,
-    recoverLeakedToolCalls: walkResult.agentConfig.recoverLeakedToolCalls,
-    systemPrompt: walkResult.agentConfig.systemPrompt,
-    tools,
-    agents,
-    memory: walkResult.memory,
-    skills: walkResult.skills ? compileSkills(walkResult.skills) : void 0,
-    context: walkResult.contextWindow ? compileContextWindow(walkResult.contextWindow).context : void 0,
-    projectContext: walkResult.projectContext,
-    mcpServers: walkResult.mcpServers,
-    guardrails: walkResult.guardrails,
-    maxIterations: walkResult.mainLoop.maxIterations ?? walkResult.agentConfig.maxIterations,
-    timeoutMs: walkResult.mainLoop.timeoutMs ?? walkResult.agentConfig.timeoutMs,
-    stream: walkResult.agentConfig.stream ?? true,
-    hitl: hitl.size > 0 ? hitl : void 0,
-    checkpoint: walkResult.checkpoint
+    getRequest: /* @__PURE__ */ __name(() => base.getRequest(), "getRequest"),
+    getUrl: /* @__PURE__ */ __name(() => base.getUrl(), "getUrl"),
+    getClass: /* @__PURE__ */ __name(() => base.getClass(), "getClass"),
+    getMethodName: /* @__PURE__ */ __name(() => base.getMethodName(), "getMethodName"),
+    getAgent: /* @__PURE__ */ __name(() => agent2, "getAgent"),
+    getRun: /* @__PURE__ */ __name(() => run, "getRun"),
+    getToolCall: /* @__PURE__ */ __name(() => toolCall ?? null, "getToolCall"),
+    isAgentContext: /* @__PURE__ */ __name(() => true, "isAgentContext")
+  };
+}
+__name(createAgentExecutionContext, "createAgentExecutionContext");
+function isAgentContext(ctx) {
+  return "isAgentContext" in ctx && ctx.isAgentContext();
+}
+__name(isAgentContext, "isAgentContext");
+
+// src/bridge/compile-project-context.ts
+var UNMAPPED_KNOBS = [
+  "indexStrategy",
+  "relevanceStrategy",
+  "maxFilesInContext",
+  "includeExtensions",
+  "rootMarkers"
+];
+function projectContextMetadataOnlyKnobs(options) {
+  const opts = options;
+  return UNMAPPED_KNOBS.filter((knob) => opts[knob] !== void 0);
+}
+__name(projectContextMetadataOnlyKnobs, "projectContextMetadataOnlyKnobs");
+function compileProjectContext(options, base) {
+  return async (promptCtx) => {
+    const resolvedBase = typeof base === "function" ? await base(promptCtx) : base;
+    const cwd = promptCtx.cwd;
+    if (!cwd) {
+      return resolvedBase ?? "";
+    }
+    const { buildEnvContext, buildRepoMap } = await import("@theokit/sdk-tools");
+    const { readProjectInstructions } = await import("@theokit/sdk/project");
+    const env = buildEnvContext(cwd);
+    const repoMap = buildRepoMap(cwd, {
+      ignore: options.ignorePatterns
+    });
+    let instructions = "";
+    try {
+      instructions = (await readProjectInstructions(cwd)).content ?? "";
+    } catch {
+      instructions = "";
+    }
+    return [
+      env,
+      repoMap,
+      instructions,
+      resolvedBase
+    ].filter(Boolean).join("\n\n");
   };
 }
-__name(compileAgent, "compileAgent");
+__name(compileProjectContext, "compileProjectContext");
 
 // src/bridge/agent-sse-handler.ts
 var encoder = new TextEncoder();
@@ -506,142 +415,6 @@ 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
-    } : {},
-    // M49 — memory flows to the projection layer; `assembleM8CreateOptions` forwards it to Agent.create.
-    ...def.memory !== void 0 ? {
-      memory: def.memory
-    } : {},
-    // Hooks are converted here — the layer EVERY path converges on — rather than on the builder, so
-    // `defineAgent({ hooks })` cannot type-check and silently no-op. A lifecycle hook that is
-    // declared but never registered is a security gate that does not gate.
-    ...compileHooksAndPlugins(def),
-    // 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 compileHooksAndPlugins(def) {
-  const map = def.hooks;
-  const entries = Object.entries(map ?? {}).filter(([, h]) => typeof h === "function");
-  const explicit = def.plugins ?? [];
-  if (entries.length === 0) {
-    return def.plugins !== void 0 ? {
-      plugins: def.plugins
-    } : {};
-  }
-  const plugin = {
-    name: "theokit-builder-hooks",
-    version: "1.0.0",
-    kind: "general",
-    register(ctx) {
-      for (const [hookName, handler] of entries) {
-        ctx.on(hookName, handler);
-      }
-    }
-  };
-  return {
-    plugins: [
-      ...explicit,
-      plugin
-    ]
-  };
-}
-__name(compileHooksAndPlugins, "compileHooksAndPlugins");
-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;
@@ -1152,9 +925,12 @@ function buildExtraCreateOptions(overrides, compiled) {
   const recoverLeakedToolCalls = overrides.recoverLeakedToolCalls ?? compiled.recoverLeakedToolCalls ?? false;
   const extra = {};
   if (overrides.plugins !== void 0) {
-    extra.plugins = Array.isArray(overrides.plugins) && Array.isArray(compiled.plugins) ? [
-      ...compiled.plugins,
-      ...overrides.plugins
+    const asArray = /* @__PURE__ */ __name((v) => Array.isArray(v) ? v : void 0, "asArray");
+    const overrideList = asArray(overrides.plugins);
+    const compiledList = asArray(compiled.plugins);
+    extra.plugins = overrideList !== void 0 && compiledList !== void 0 ? [
+      ...compiledList,
+      ...overrideList
     ] : overrides.plugins;
   }
   if (overrides.providers !== void 0) {
@@ -1353,7 +1129,7 @@ function createSdkAgentStream(compiled, compiledTools, apiKey, overrides = {}) {
   const reasoningEffort = overrides.reasoningEffort ?? compiled.reasoningEffort;
   const { parseThinkTags, stripToolDialect } = resolveTextTransformFlags(compiled, overrides);
   const runContext = overrides.runContext ?? compiled.runContext;
-  return (message, sessionId, factoryOpts) => ({
+  const factory = /* @__PURE__ */ __name((message, sessionId, factoryOpts) => ({
     async *[Symbol.asyncIterator]() {
       const runId = `run-${Date.now()}`;
       const t0 = Date.now();
@@ -1407,6 +1183,9 @@ function createSdkAgentStream(compiled, compiledTools, apiKey, overrides = {}) {
         };
       }
     }
+  }), "factory");
+  return Object.assign(factory, {
+    resolvedModel: model
   });
 }
 __name(createSdkAgentStream, "createSdkAgentStream");
@@ -1904,6 +1683,125 @@ var UIMessageStreamPresenter = class {
     return out;
   }
 };
+var ANSI = {
+  text: "",
+  reasoning: "\x1B[2m",
+  tool: "\x1B[36m",
+  "tool-result": "\x1B[2m",
+  "tool-error": "\x1B[31m",
+  error: "\x1B[31m",
+  status: "\x1B[35m",
+  finish: "\x1B[2m"
+};
+var RESET = "\x1B[0m";
+function preview(value, max) {
+  const raw = typeof value === "string" ? value : safeJson(value);
+  const flat = raw.replace(/\s+/g, " ").trim();
+  return flat.length > max ? `${flat.slice(0, max - 1)}\u2026` : flat;
+}
+__name(preview, "preview");
+__name2(preview, "preview");
+function safeJson(value) {
+  if (value === void 0 || value === null) return "";
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return typeof value === "bigint" ? value.toString() : "";
+  }
+}
+__name(safeJson, "safeJson");
+__name2(safeJson, "safeJson");
+function suffix(open, value, close) {
+  return value === void 0 ? "" : open + value + close;
+}
+__name(suffix, "suffix");
+__name2(suffix, "suffix");
+var TerminalPresenter = class {
+  static {
+    __name(this, "TerminalPresenter");
+  }
+  static {
+    __name2(this, "TerminalPresenter");
+  }
+  surface = "terminal";
+  #ansi;
+  #max;
+  constructor(options = {}) {
+    this.#ansi = options.ansi ?? false;
+    this.#max = options.maxPreview ?? 88;
+  }
+  present(event) {
+    switch (event.type) {
+      case "text":
+        return event.text.length > 0 ? [
+          this.#row("text", event.text)
+        ] : [];
+      case "reasoning":
+        return event.text.length > 0 ? [
+          this.#row("reasoning", `\xB7 ${event.text}`)
+        ] : [];
+      case "tool-call":
+        return [
+          this.#row("tool", `\u23FA ${event.name}(${preview(event.input, this.#max)})`)
+        ];
+      case "tool-result":
+        return [
+          this.#toolResult(event.isError === true, preview(event.result, this.#max))
+        ];
+      case "error":
+        return [
+          this.#row("error", `\u2716 ${event.message}${suffix(" (", event.code, ")")}`)
+        ];
+      case "status":
+        return [
+          this.#row("status", `\u25CF ${event.status}${suffix(" \u2014 ", event.detail, "")}`)
+        ];
+      case "finish":
+        return [
+          this.#row("finish", this.#finishText(event.reason, event.usage?.totalTokens))
+        ];
+      // `partial-tool-call` streams incremental args — the committed `tool-call` renders them.
+      default:
+        return [];
+    }
+  }
+  #toolResult(isError2, body) {
+    return this.#row(isError2 ? "tool-error" : "tool-result", `  \u23BF ${body}`);
+  }
+  #finishText(reason, tokens) {
+    const r = suffix(" ", reason, "");
+    const t = tokens === void 0 ? "" : ` \xB7 ${tokens} tokens`;
+    return `<<${r}${t} >>`;
+  }
+  #row(kind, text) {
+    return {
+      kind,
+      text: this.#ansi && ANSI[kind] !== "" ? `${ANSI[kind]}${text}${RESET}` : text
+    };
+  }
+};
+var JsonPresenter = class {
+  static {
+    __name(this, "JsonPresenter");
+  }
+  static {
+    __name2(this, "JsonPresenter");
+  }
+  surface = "json";
+  #ns;
+  constructor(options = {}) {
+    this.#ns = options.namespace ?? "agent.";
+  }
+  present(event) {
+    const { type, ...payload } = event;
+    return [
+      {
+        type: `${this.#ns}${type}`,
+        ...payload
+      }
+    ];
+  }
+};
 
 // src/bridge/present-ui-message-stream.ts
 function toAgentOutputEvent(e) {
@@ -2172,19 +2070,18 @@ function extractDefaultExport(mod) {
   return mod;
 }
 __name(extractDefaultExport, "extractDefaultExport");
+function isCompiledAgentOptions(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  return Array.isArray(v.tools) && typeof v.agents === "object" && v.agents !== null;
+}
+__name(isCompiledAgentOptions, "isCompiledAgentOptions");
 function compileAgentModule(mod, source = "agent module") {
   const def = extractDefaultExport(mod);
   if (isAgentDefinition(def)) {
     return compileAgentDefinition(def);
   }
-  if (typeof def === "function" && getAgentConfig(def) !== void 0) {
-    const walk = walkAgentMetadata(def, getMixins(def));
-    const instances = /* @__PURE__ */ new Map();
-    for (const tb of walk.toolboxes) {
-      instances.set(tb.class, new tb.class());
-    }
-    return compileAgent(walk, instances);
-  }
+  if (isCompiledAgentOptions(def)) return def;
   throw new AgentDefinitionError(source);
 }
 __name(compileAgentModule, "compileAgentModule");
@@ -2258,12 +2155,16 @@ function streamAgentUIMessages(compiled, apiKey, input) {
     source = asAgentStream(events2);
   } else {
     const queue = new EventQueue();
-    input.signal?.addEventListener("abort", () => queue.close(), {
+    input.signal?.addEventListener("abort", () => {
+      queue.close();
+    }, {
       once: true
     });
     const plugin = createHitlPlugin({
       gated: input.hitl.gated,
-      emit: /* @__PURE__ */ __name((e) => queue.push(e), "emit"),
+      emit: /* @__PURE__ */ __name((e) => {
+        queue.push(e);
+      }, "emit"),
       awaitApproval: input.hitl.awaitApproval
     });
     const sdkStream = createSdkAgentStream(compiled, compiled.tools, apiKey, {
@@ -2901,9 +2802,9 @@ var AgentRunner = class {
     this.streamEnabled = state.streamEnabled;
     this.compaction = state.compaction;
   }
-  /** Start a fluent builder for `AgentClass`. */
-  static builder(AgentClass) {
-    return new AgentRunnerBuilder(AgentClass);
+  /** Start a fluent builder from an already-compiled spec. */
+  static fromSpec(spec) {
+    return new AgentRunnerBuilder(spec);
   }
   /**
   * V4-D-stream: stream the agent's events LIVE across the reflective loop, returning
@@ -2965,12 +2866,12 @@ var AgentRunnerBuilder = class {
   static {
     __name(this, "AgentRunnerBuilder");
   }
-  AgentClass;
+  spec;
   reflectionOverride;
   streamEnabled = true;
   compactionOverride;
-  constructor(AgentClass) {
-    this.AgentClass = AgentClass;
+  constructor(spec) {
+    this.spec = spec;
   }
   /** Override the default reflection strategy (OCP — plan Drawback #2). No arg ⇒ keep default. */
   reflection(strategy) {
@@ -2994,23 +2895,19 @@ var AgentRunnerBuilder = class {
     };
     return 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() {
-    const walk = walkAgentMetadata(this.AgentClass, []);
-    const toolboxInstances = new Map(walk.toolboxes.map((tb) => [
-      tb.class,
-      new tb.class()
-    ]));
-    const compiled = compileAgent(walk, toolboxInstances);
-    const loopStrategy = resolveLoopStrategy(walk.mainLoop.strategy, walk.mainLoop.maxIterations);
-    const reflectionStrategy = this.reflectionOverride ?? (walk.mainLoop.strategy === "plan-act-reflect" ? ladderReflectionStrategy : noopReflectionStrategy);
-    const compactionDecl = this.compactionOverride ?? walk.compaction;
+    const { spec } = this;
+    const strategy = spec.strategy ?? "simple-chat";
+    const loopStrategy = resolveLoopStrategy(strategy, spec.maxIterations);
+    const reflectionStrategy = this.reflectionOverride ?? (strategy === "plan-act-reflect" ? ladderReflectionStrategy : noopReflectionStrategy);
+    const compactionDecl = this.compactionOverride ?? spec.compaction;
     const compaction = compactionDecl ? resolveCompactionStrategy(compactionDecl.name, {
       keepTokens: compactionDecl.keepTokens
     }) : void 0;
     return new AgentRunner({
-      compiled,
-      agentName: walk.agentConfig.name,
+      compiled: spec.compiled,
+      agentName: spec.name,
       loopStrategy,
       reflectionStrategy,
       streamEnabled: this.streamEnabled,
@@ -3037,22 +2934,17 @@ function mergeTools(parentTools, subTools) {
   ];
 }
 __name(mergeTools, "mergeTools");
-async function delegate(SubAgentClass, message, opts = {}) {
-  const apiKey = requireApiKey(opts, SubAgentClass.name);
+async function delegate(spec, message, opts = {}) {
+  const apiKey = requireApiKey(opts, spec.name);
   const effectiveMessage = opts.onDelegationStart ? await opts.onDelegationStart({
-    subAgent: SubAgentClass.name,
+    subAgent: spec.name,
     input: message
   }) : message;
-  const walk = walkAgentMetadata(SubAgentClass, []);
-  const toolboxInstances = new Map(walk.toolboxes.map((tb) => [
-    tb.class,
-    new tb.class()
-  ]));
-  const compiled = compileAgent(walk, toolboxInstances);
+  const { compiled } = spec;
   const allTools = mergeTools(opts.parentTools ?? [], compiled.tools);
   const budget = Math.min(opts.budget ?? Infinity, opts.parentBudgetRemaining ?? Infinity);
   const streamFactory = opts.streamFactory ?? createSdkAgentStream(compiled, allTools, apiKey, {
-    model: opts.model ?? walk.agentConfig.model,
+    model: opts.model ?? compiled.model,
     cwd: opts.cwd,
     plugins: opts.plugins,
     providers: opts.providers,
@@ -3061,19 +2953,19 @@ async function delegate(SubAgentClass, message, opts = {}) {
     sdkTools: opts.sdkTools
   });
   const sessionId = opts.sessionId ?? `sub-${crypto.randomUUID()}`;
-  const loopStrategy = resolveLoopStrategy(walk.mainLoop.strategy, opts.maxIterations ?? walk.mainLoop.maxIterations);
+  const loopStrategy = resolveLoopStrategy(spec.strategy ?? "simple-chat", opts.maxIterations ?? spec.maxIterations);
   const reflection = opts.reflection ?? (loopStrategy.name === "plan-act-reflect" ? ladderReflectionStrategy : noopReflectionStrategy);
   const result = await runReflectiveLoop(streamFactory, effectiveMessage, sessionId, {
     loop: loopStrategy,
     reflection,
     budget,
-    agentName: SubAgentClass.name,
+    agentName: spec.name,
     signal: opts.signal,
     retry: opts.retry
   });
   if (opts.onDelegationComplete) {
     return await opts.onDelegationComplete({
-      subAgent: SubAgentClass.name,
+      subAgent: spec.name,
       result
     });
   }
@@ -3204,6 +3096,9 @@ async function delegateWithScoring(subAgent, message, opts) {
     }
     if (verdict.feedback) currentMessage = feedbackTemplate(message, verdict.feedback);
   }
+  if (lastResult === void 0) {
+    throw new Error("[@theokit/agents] delegateWithScoring: no round ran (maxRounds < 1)");
+  }
   return {
     result: lastResult,
     rounds: maxRounds,
@@ -3279,11 +3174,11 @@ function mcpToolApprovals(specs) {
 __name(mcpToolApprovals, "mcpToolApprovals");
 
 // src/manifest/agent-manifest.ts
-function generateAgentManifest(walkResults) {
+function generateAgentManifest(sources) {
   return {
     version: "1.0",
     generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    agents: walkResults.map((r) => ({
+    agents: sources.map((r) => ({
       name: r.agentConfig.name,
       route: r.route,
       model: r.agentConfig.model,
@@ -3322,7 +3217,17 @@ function generateAgentManifest(walkResults) {
 __name(generateAgentManifest, "generateAgentManifest");
 
 // src/theokit-plugin.ts
-import "reflect-metadata";
+function validateUniqueRoutes(results) {
+  const seen = /* @__PURE__ */ new Map();
+  for (const r of results) {
+    const existing = seen.get(r.route);
+    if (existing !== void 0) {
+      throw new Error(`[@theokit/agents] Duplicate agent route '${r.route}': both '${existing}' and '${r.agentConfig.name}' declare it.`);
+    }
+    seen.set(r.route, r.agentConfig.name);
+  }
+}
+__name(validateUniqueRoutes, "validateUniqueRoutes");
 function agentsPlugin(opts) {
   let routes = null;
   return {
@@ -3343,25 +3248,24 @@ function agentsPlugin(opts) {
 __name(agentsPlugin, "agentsPlugin");
 function initRoutes(opts) {
   const allRoutes = [];
-  const walkResults = [];
-  for (const AgentClass of opts.agents) {
-    const mixins = getMixins(AgentClass);
-    const toolboxes = [
-      ...opts.toolboxes ?? [],
-      ...mixins
-    ];
-    const walkResult = walkAgentMetadata(AgentClass, toolboxes);
-    walkResults.push(walkResult);
-    const compiled = compileAgent(walkResult, /* @__PURE__ */ new Map());
-    const createRun = opts.createRunFactory ? opts.createRunFactory(compiled, walkResult) : defaultCreateRun(compiled);
-    const agentRoutes = generateAgentRoutes({
-      walkResult,
-      compiledOptions: compiled,
-      createRun
+  const routeIdentities = [];
+  for (const entry of opts.agents) {
+    routeIdentities.push({
+      route: entry.route,
+      agentConfig: {
+        name: entry.name
+      }
     });
-    allRoutes.push(...agentRoutes);
+    const createRun = opts.createRunFactory ? opts.createRunFactory(entry.compiled) : defaultCreateRun(entry.compiled);
+    allRoutes.push(...generateAgentRoutes({
+      walkResult: {
+        route: entry.route
+      },
+      compiledOptions: entry.compiled,
+      createRun
+    }));
   }
-  validateUniqueRoutes(walkResults);
+  validateUniqueRoutes(routeIdentities);
   return compileRoutePatterns(allRoutes);
 }
 __name(initRoutes, "initRoutes");
@@ -3403,17 +3307,17 @@ function matchRoute(routes, method, pathname) {
 __name(matchRoute, "matchRoute");
 
 export {
+  AGENT_BRAND,
+  isAgentDefinition,
+  compileAgentDefinition,
+  compileSkillsSelection,
+  compileContextWindow,
+  compileSkills,
+  compileTools,
   createAgentExecutionContext,
   isAgentContext,
-  compileContextWindow,
   projectContextMetadataOnlyKnobs,
   compileProjectContext,
-  AgentWarningCode,
-  walkAgentMetadata,
-  validateUniqueRoutes,
-  compileSkills,
-  compileTools,
-  compileAgent,
   streamAgentResponse,
   isTextDelta,
   isToolCall,
@@ -3423,9 +3327,6 @@ export {
   isError,
   isApprovalRequired,
   generateAgentRoutes,
-  AGENT_BRAND,
-  isAgentDefinition,
-  compileAgentDefinition,
   translateSdkEvent,
   buildModelSelection,
   createThinkTagExtractor,
@@ -3475,4 +3376,4 @@ export {
   generateAgentManifest,
   agentsPlugin
 };
-//# sourceMappingURL=chunk-YBNKD5UM.js.map
+//# sourceMappingURL=chunk-7KRJJX7W.js.map