@theokit/agents 7.5.0 → 8.0.0

package/dist/{chunk-WKBZZQBO.js → chunk-C7UXZWVY.js}

@@ -1,3 +1,8 @@
+import {
+  compileAgentDefinition,
+  defineAgent,
+  isAgentDefinition
+} from "./chunk-4VHCH6IZ.js";
 import {
   __name
 } from "./chunk-Z4QWC7IK.js";
@@ -5,142 +10,6 @@ import {
 // src/errors.ts
 import { ConfigurationError } from "@theokit/sdk/errors";
 
-// 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/compile-context-window.ts
 var STRATEGY_KNOBS = [
   "compactionStrategy",
@@ -352,7 +221,7 @@ data: ${JSON.stringify(errorEvent)}
     headers: {
       "content-type": "text/event-stream",
       "cache-control": "no-cache",
-      "connection": "keep-alive"
+      connection: "keep-alive"
     }
   });
 }
@@ -456,27 +325,38 @@ function generateAgentRoutes(ctx) {
 __name(generateAgentRoutes, "generateAgentRoutes");
 
 // src/guardrails/types.ts
-var GuardrailViolationError = class extends Error {
+import { TheokitAgentError } from "@theokit/sdk/errors";
+var GuardrailViolationError = class extends TheokitAgentError {
   static {
     __name(this, "GuardrailViolationError");
   }
   guardName;
   phase;
   reason;
+  name = "GuardrailViolationError";
   constructor(guardName, phase, reason) {
-    super(`Guardrail "${guardName}" blocked ${phase}: ${reason}`), this.guardName = guardName, this.phase = phase, this.reason = reason;
-    this.name = "GuardrailViolationError";
+    super(`Guardrail "${guardName}" blocked ${phase}: ${reason}`, {
+      code: "GUARDRAIL_VIOLATION",
+      // A blocked prompt is a REFUSAL, not a hiccup. Retrying re-submits the very input a
+      // prompt-injection or PII guard just rejected.
+      isRetryable: false
+    }), this.guardName = guardName, this.phase = phase, this.reason = reason;
   }
 };
-var CostBudgetExceededError = class extends Error {
+var CostBudgetExceededError = class extends TheokitAgentError {
   static {
     __name(this, "CostBudgetExceededError");
   }
   usedTokens;
   maxTokens;
+  name = "CostBudgetExceededError";
   constructor(usedTokens, maxTokens) {
-    super(`Cost budget exceeded: ${usedTokens} > ${maxTokens} tokens`), this.usedTokens = usedTokens, this.maxTokens = maxTokens;
-    this.name = "CostBudgetExceededError";
+    super(`Cost budget exceeded: ${usedTokens} > ${maxTokens} tokens`, {
+      code: "COST_BUDGET_EXCEEDED",
+      // The budget does not refill on retry; retrying spends the next request against the same
+      // exhausted ceiling.
+      isRetryable: false
+    }), this.usedTokens = usedTokens, this.maxTokens = maxTokens;
   }
 };
 
@@ -1149,6 +1029,9 @@ function posturePlugins(posturePolicy, gated) {
         })
       ];
     case "auto-approve":
+      if (!posturePolicy.confinedBy.enforced) {
+        throw new Error(`[@theokit/agents] approval posture "auto-approve" claims confinement ("${posturePolicy.reason}"), but the sandbox reports it is NOT enforced: ${posturePolicy.confinedBy.detail} (mode: ${posturePolicy.confinedBy.mode}). Auto-approving gated tools without enforced confinement runs arbitrary commands with no human and no sandbox. Use "interactive" (a human decides) or "auto-reject" (fail-closed) until the sandbox reports enforced.`);
+      }
       return [
         createToolHooksPlugin({
           beforeToolCall: /* @__PURE__ */ __name((ctx) => {
@@ -1212,11 +1095,12 @@ function assembleM8CreateOptions(compiled) {
     options.plugins = compiled.plugins;
     applied.push("plugins");
   }
-  const settingSources = resolveSettingSources(compiled);
-  if (settingSources) {
+  if (compiled.settingSources !== void 0 && compiled.settingSources.length > 0) {
     options.local = {
       ...options.local,
-      settingSources
+      settingSources: [
+        ...compiled.settingSources
+      ]
     };
     applied.push("settingSources");
   }
@@ -1255,17 +1139,6 @@ function assembleM8CreateOptions(compiled) {
   };
 }
 __name(assembleM8CreateOptions, "assembleM8CreateOptions");
-function resolveSettingSources(compiled) {
-  const explicit = compiled.settingSources;
-  if (explicit && explicit.length > 0) return [
-    ...explicit
-  ];
-  if (compiled.skills) return [
-    "project"
-  ];
-  return void 0;
-}
-__name(resolveSettingSources, "resolveSettingSources");
 function realUsageDone(result, t0) {
   const u = result.usage;
   const inputTokens = u?.inputTokens ?? 0;
@@ -1947,6 +1820,20 @@ function makeBuilder(config) {
         tool
       ]
     }), "tool"),
+    tools: /* @__PURE__ */ __name((list) => makeBuilder({
+      ...config,
+      tools: [
+        ...config.tools ?? [],
+        ...list
+      ]
+    }), "tools"),
+    // `when` is deliberately not a conditional-typed return: the branch runs or it does not, and
+    // either way the caller gets a builder carrying the same accumulated state. Returning `builder`
+    // unchanged on `false` is what makes it a true no-op rather than a reset.
+    when: /* @__PURE__ */ __name((condition, apply) => {
+      const builder = makeBuilder(config);
+      return condition ? apply(builder) : builder;
+    }, "when"),
     guardrail: /* @__PURE__ */ __name((g) => makeBuilder({
       ...config,
       guardrails: [
@@ -1973,9 +1860,9 @@ function makeBuilder(config) {
       ...config,
       skills: selection
     }), "skills"),
-    settingSources: /* @__PURE__ */ __name((sources) => makeBuilder({
+    settingSources: /* @__PURE__ */ __name((selection) => makeBuilder({
       ...config,
-      settingSources: sources
+      settingSources: selection
     }), "settingSources"),
     memory: /* @__PURE__ */ __name((settings) => makeBuilder({
       ...config,
@@ -2010,13 +1897,18 @@ var AgentBuilder = {
 };
 
 // src/bridge/agent-endpoint.ts
-var AgentDefinitionError = class extends Error {
+import { TheokitAgentError as TheokitAgentError2 } from "@theokit/sdk/errors";
+var AgentDefinitionError = class extends TheokitAgentError2 {
   static {
     __name(this, "AgentDefinitionError");
   }
+  name = "AgentDefinitionError";
   constructor(source) {
-    super(`[@theokit/agents] ${source}: an agents/ file must default-export a defineAgent(...) value or an @Agent-decorated class.`);
-    this.name = "AgentDefinitionError";
+    super(`[@theokit/agents] ${source}: an agents/ file must default-export a defineAgent(...) value or an @Agent-decorated class.`, {
+      code: "AGENT_DEFINITION_INVALID",
+      // a malformed module does not become well-formed by being loaded twice.
+      isRetryable: false
+    });
   }
 };
 function extractDefaultExport(mod) {
@@ -2262,28 +2154,39 @@ var noopReflectionStrategy = {
 };
 
 // src/bridge/delegation-types.ts
-var DelegationBudgetExceededError = class extends Error {
+import { TheokitAgentError as TheokitAgentError3 } from "@theokit/sdk/errors";
+var DelegationBudgetExceededError = class extends TheokitAgentError3 {
   static {
     __name(this, "DelegationBudgetExceededError");
   }
   agentName;
   actualCost;
   budgetLimit;
+  name = "DelegationBudgetExceededError";
   constructor(agentName, actualCost, budgetLimit) {
-    super(`Agent "${agentName}" exceeded budget: $${actualCost.toFixed(4)} > $${budgetLimit.toFixed(4)}`), this.agentName = agentName, this.actualCost = actualCost, this.budgetLimit = budgetLimit;
-    this.name = "DelegationBudgetExceededError";
+    super(`Agent "${agentName}" exceeded budget: $${actualCost.toFixed(4)} > $${budgetLimit.toFixed(4)}`, {
+      code: "DELEGATION_BUDGET_EXCEEDED",
+      // The budget does not refill on retry.
+      isRetryable: false
+    }), this.agentName = agentName, this.actualCost = actualCost, this.budgetLimit = budgetLimit;
   }
 };
 var BudgetExceededError = DelegationBudgetExceededError;
-var DelegationError = class extends Error {
+var DelegationError = class extends TheokitAgentError3 {
   static {
     __name(this, "DelegationError");
   }
   agentName;
   cause;
+  name = "DelegationError";
   constructor(agentName, cause) {
-    super(`Delegation to agent "${agentName}" failed: ${cause instanceof Error ? cause.message : String(cause)}`), this.agentName = agentName, this.cause = cause;
-    this.name = "DelegationError";
+    super(`Delegation to agent "${agentName}" failed: ${cause instanceof Error ? cause.message : String(cause)}`, {
+      code: "DELEGATION_FAILED",
+      // Not retryable AT THIS LEVEL: whether the underlying cause is transient is the cause's own
+      // answer, and `cause` is carried so a caller can ask it rather than guess from the wrapper.
+      isRetryable: false,
+      cause
+    }), this.agentName = agentName, this.cause = cause;
   }
 };
 
@@ -2757,6 +2660,36 @@ var GoalRunner = class {
   }
 };
 
+// src/loop/format-goal-event.ts
+function formatGoalEvent(event) {
+  const candidate = event;
+  if (candidate === null || typeof candidate !== "object" || typeof candidate.type !== "string") {
+    return "[goal] unrecognised event (malformed)";
+  }
+  switch (event.type) {
+    case "turn_start":
+      return `[goal] turn ${event.turn} started \u2014 ${event.goal}`;
+    case "agent_response":
+      return `[goal] turn ${event.turn} response: ${event.content}`;
+    case "judge_verdict":
+      return `[goal] turn ${event.turn} judged ${event.verdict}: ${event.reason}` + // Surfaced rather than hidden: a verdict the judge could not parse reached a decision by
+      // fallback, and an operator reading the log needs to know which of the two happened.
+      (event.parseFailed ? " (verdict could not be parsed)" : "");
+    case "continuation":
+      return `[goal] turn ${event.turn} continuing: ${event.prompt}`;
+    case "status_change":
+      return `[goal] status ${event.status}: ${event.reason}`;
+    default:
+      return formatUnrecognised(event);
+  }
+}
+__name(formatGoalEvent, "formatGoalEvent");
+function formatUnrecognised(event) {
+  const { type } = event;
+  return `[goal] unrecognised event: ${String(type)}`;
+}
+__name(formatUnrecognised, "formatUnrecognised");
+
 // src/bridge/agent-orchestrator.ts
 function requireApiKey(opts, agentName) {
   const apiKey = opts.apiKey ?? "";
@@ -2842,11 +2775,69 @@ function createApiErrorHandler(policy) {
 }
 __name(createApiErrorHandler, "createApiErrorHandler");
 
+// src/bridge/delegation-lifecycle.ts
+import { TheokitAgentError as TheokitAgentError4 } from "@theokit/sdk/errors";
+var DelegationTimeoutError = class extends TheokitAgentError4 {
+  static {
+    __name(this, "DelegationTimeoutError");
+  }
+  name = "DelegationTimeoutError";
+  constructor(subAgent, timeoutMs) {
+    super(`delegation to "${subAgent}" exceeded its ${String(timeoutMs)} ms clock cap. This is a WALL CLOCK limit, not a budget: the run may have been progressing and simply slow, or hung. Raise \`timeoutMs\` if the work legitimately takes longer.`, {
+      code: "DELEGATION_TIMEOUT",
+      // A hang is often transient — the model, a tool or a network call. Unlike the budget errors,
+      // this one is worth another attempt, which is exactly why it is a separate class.
+      isRetryable: true
+    });
+  }
+};
+async function withClockCap(promise, timeoutMs, subAgent) {
+  let timer;
+  const clock = new Promise((_resolve, reject) => {
+    timer = setTimeout(() => {
+      reject(new DelegationTimeoutError(subAgent, timeoutMs));
+    }, timeoutMs);
+  });
+  try {
+    return await Promise.race([
+      promise,
+      clock
+    ]);
+  } finally {
+    if (timer !== void 0) clearTimeout(timer);
+  }
+}
+__name(withClockCap, "withClockCap");
+async function withEphemeralAgent(create, body, options = {}) {
+  const { agent, dispose } = await create();
+  try {
+    return await body(agent);
+  } finally {
+    try {
+      await dispose();
+    } catch (error) {
+      options.onDisposeError?.(error);
+    }
+  }
+}
+__name(withEphemeralAgent, "withEphemeralAgent");
+
 // src/bridge/delegation-scoring.ts
+function isPort(target) {
+  return typeof target.run === "function";
+}
+__name(isPort, "isPort");
+async function runOnce(target, message, delegateFn, opts) {
+  const port = isPort(target);
+  const started = port ? target.run(message) : delegateFn(target, message, opts);
+  if (opts.timeoutMs === void 0) return started;
+  return withClockCap(started, opts.timeoutMs, port ? "port" : target.name);
+}
+__name(runOnce, "runOnce");
 function delegateBackground(subAgent, message, opts = {}) {
   const { delegateFn = delegate, ...delegateOpts } = opts;
   let isSettled = false;
-  const promise = delegateFn(subAgent, message, delegateOpts).finally(() => {
+  const promise = runOnce(subAgent, message, delegateFn, delegateOpts).finally(() => {
     isSettled = true;
   });
   promise.catch(() => void 0);
@@ -2870,7 +2861,7 @@ async function delegateWithScoring(subAgent, message, opts) {
   let currentMessage = message;
   let lastResult;
   for (let round = 1; round <= maxRounds; round++) {
-    const result = await delegateFn(subAgent, currentMessage, delegateOpts);
+    const result = await runOnce(subAgent, currentMessage, delegateFn, delegateOpts);
     lastResult = result;
     const verdict = await scorer(result);
     verdicts.push(verdict);
@@ -2964,7 +2955,7 @@ __name(mcpToolApprovals, "mcpToolApprovals");
 // src/bridge/mcp-file.ts
 import { existsSync, readFileSync } from "fs";
 import { join } from "path";
-import { TheokitAgentError } from "@theokit/sdk/errors";
+import { TheokitAgentError as TheokitAgentError5 } from "@theokit/sdk/errors";
 function warningChannel(opts) {
   return opts.onWarn ?? ((warning) => {
     process.stderr.write(`[@theokit/agents] ${warning}
@@ -2972,7 +2963,7 @@ function warningChannel(opts) {
   });
 }
 __name(warningChannel, "warningChannel");
-var McpFileError = class extends TheokitAgentError {
+var McpFileError = class extends TheokitAgentError5 {
   static {
     __name(this, "McpFileError");
   }
@@ -3232,10 +3223,6 @@ __name(matchRoute, "matchRoute");
 
 export {
   ConfigurationError,
-  AGENT_BRAND,
-  isAgentDefinition,
-  compileAgentDefinition,
-  compileSkillsSelection,
   compileContextWindow,
   compileSkills,
   toolRuntimeName,
@@ -3296,9 +3283,13 @@ export {
   AgentRunnerBuilder,
   GoalRunner,
   JudgeCredentialError,
+  formatGoalEvent,
   delegate,
   runWithApiErrorHandling,
   createApiErrorHandler,
+  DelegationTimeoutError,
+  withClockCap,
+  withEphemeralAgent,
   delegateBackground,
   delegateWithScoring,
   resolveMcpServers,
@@ -3309,4 +3300,4 @@ export {
   generateAgentManifest,
   agentsPlugin
 };
-//# sourceMappingURL=chunk-WKBZZQBO.js.map
+//# sourceMappingURL=chunk-C7UXZWVY.js.map