@theokit/agents 10.1.0 → 11.1.0

package/dist/{chunk-CKRM5Q2K.js → chunk-2I6DQUJP.js}

@@ -4,7 +4,10 @@ import {
 } from "./chunk-RKWCXVYG.js";
 import {
   compileAgentDefinition
-} from "./chunk-4VHCH6IZ.js";
+} from "./chunk-LLIERPF3.js";
+import {
+  createRunUsageMeter
+} from "./chunk-OXNDJSAJ.js";
 import {
   __name
 } from "./chunk-Z4QWC7IK.js";
@@ -382,8 +385,8 @@ function createHitlPlugin(wiring) {
           approved: raw
         } : raw;
         if (decision.approved) return void 0;
-        let message = `Tool '${c.name}' denied by human approver`;
-        if (decision.reason) message += `: ${decision.reason}`;
+        let message = decision.settledBy === "timeout" ? `Tool '${c.name}' was not approved: ${decision.reason ?? "the approval window expired with no decision"}. Decide within the window, or raise 'timeout' on the tool's approval options.` : `Tool '${c.name}' denied by human approver`;
+        if (decision.settledBy !== "timeout" && decision.reason) message += `: ${decision.reason}`;
         if (decision.payload !== void 0) {
           message += ` (payload: ${JSON.stringify(decision.payload)})`;
         }
@@ -485,6 +488,14 @@ function buildModelSelection(model, effort) {
   };
 }
 __name(buildModelSelection, "buildModelSelection");
+function modelIdOf(model) {
+  return typeof model === "string" ? model : model.id;
+}
+__name(modelIdOf, "modelIdOf");
+function contextWindowOf(model) {
+  return typeof model === "string" ? void 0 : model.contextWindow;
+}
+__name(contextWindowOf, "contextWindowOf");
 function reasoningEffortOf(model) {
   const params = typeof model === "string" ? void 0 : model.params;
   return params?.find((p) => p.id === PARAM_THINKING)?.value;
@@ -497,6 +508,16 @@ function asString(value, fallback) {
   return fallback;
 }
 __name(asString, "asString");
+function toolResultExitCode(value) {
+  if (typeof value !== "object" || value === null) return void 0;
+  const code = value.exitCode;
+  return typeof code === "number" ? code : void 0;
+}
+__name(toolResultExitCode, "toolResultExitCode");
+function reportsToolFailure(result) {
+  return (toolResultExitCode(result) ?? 0) !== 0;
+}
+__name(reportsToolFailure, "reportsToolFailure");
 function serializeToolOutput(value, fallback) {
   if (typeof value === "string") return value;
   if (value === void 0 || value === null) return fallback;
@@ -559,7 +580,9 @@ function translateToolCallEvent(msg) {
         toolName,
         output: serializeToolOutput(msg.result, ""),
         durationMs: 0,
-        isError: false
+        // #388 — `completed` is the SDK's word for "the call is over", not for "the call worked".
+        // The exit code is the part that says which, and it was being thrown away here.
+        isError: reportsToolFailure(msg.result)
       }
     ];
   }
@@ -722,7 +745,13 @@ function translateInteractionUpdate(update) {
           toolName: update.toolCall.name,
           output: serializeToolOutput(update.toolCall.result, ""),
           durationMs: 0,
-          isError: false
+          // #388 — the same predicate, and on this shape it answers `false` for a reason rather
+          // than by decree: `ToolCall` (`@theokit/sdk/dist/types/updates.d.ts`) declares only
+          // `{callId, name, args?, result?}`, and the SDK fills `result` with `renderToolResult()`
+          // — a rendered string — so the exit code structurally cannot travel here. The message-
+          // shaped report of the same call is the one that carries it, and `dedupeTools` is what
+          // lets it contribute (`sdk-timeline.ts`).
+          isError: reportsToolFailure(update.toolCall.result)
         }
       ];
     case "shell-output-delta":
@@ -901,10 +930,17 @@ function assembleM8CreateOptions(compiled) {
   };
 }
 __name(assembleM8CreateOptions, "assembleM8CreateOptions");
-function realUsageDone(result, t0) {
+function stopReasonOf(result) {
+  if (result.stoppedByDoomLoop === true) return "no_progress";
+  if (result.stoppedAtIterationLimit === true) return "step_limit";
+  return void 0;
+}
+__name(stopReasonOf, "stopReasonOf");
+function realUsageDone(result, t0, model) {
   const u = result.usage;
   const inputTokens = u?.inputTokens ?? 0;
   const outputTokens = u?.outputTokens ?? 0;
+  const stopReason = stopReasonOf(result);
   return {
     type: "done",
     result: result.result ?? "",
@@ -919,10 +955,18 @@ function realUsageDone(result, t0) {
       cacheWriteTokens: u?.cacheWriteTokens ?? 0
     },
     durationMs: Date.now() - t0,
-    cost: result.cost?.amount ?? 0
+    cost: result.cost?.amount ?? 0,
+    ...terminalExtras(stopReason, model)
   };
 }
 __name(realUsageDone, "realUsageDone");
+function terminalExtras(stopReason, model) {
+  const extras = {};
+  if (stopReason !== void 0) extras.stopReason = stopReason;
+  if (model !== void 0) extras.model = model;
+  return extras;
+}
+__name(terminalExtras, "terminalExtras");
 
 // src/bridge/sdk-error.ts
 function sdkErrorEvent(err) {
@@ -954,6 +998,20 @@ function bucketFor(e, seen) {
   return void 0;
 }
 __name(bucketFor, "bucketFor");
+function isToolLifecycleEvent(e) {
+  return e.type === "tool_call" || e.type === "tool_result" || e.type === "partial_tool_call";
+}
+__name(isToolLifecycleEvent, "isToolLifecycleEvent");
+function mergeIntoPending(e, ids, seen) {
+  if (e.type !== "tool_result" || !e.isError) return;
+  const held = seen.pending.find((p) => p.ids.some((id) => ids.includes(id)));
+  if (held?.event.type !== "tool_result") return;
+  held.event = {
+    ...held.event,
+    isError: true
+  };
+}
+__name(mergeIntoPending, "mergeIntoPending");
 function dedupeTools(events, raw, seen) {
   return events.filter((e) => {
     if (e.type === "thinking") {
@@ -965,16 +1023,39 @@ function dedupeTools(events, raw, seen) {
     if (bucket === void 0) return true;
     const ids = idsOf(e, raw);
     if (ids.length === 0) return true;
-    if (ids.some((id) => bucket.has(id))) return false;
+    if (ids.some((id) => bucket.has(id))) {
+      mergeIntoPending(e, ids, seen);
+      return false;
+    }
     for (const id of ids) bucket.add(id);
+    if (e.type === "tool_result") {
+      seen.pending.push({
+        ids,
+        event: e
+      });
+      return false;
+    }
     return true;
   });
 }
 __name(dedupeTools, "dedupeTools");
+function releasePendingToolResults(translated, seen) {
+  if (seen.pending.length === 0) return [];
+  if (translated.length === 0 || translated.every(isToolLifecycleEvent)) return [];
+  return flushPendingToolResults(seen);
+}
+__name(releasePendingToolResults, "releasePendingToolResults");
+function flushPendingToolResults(seen) {
+  const out = seen.pending.map((p) => p.event);
+  seen.pending = [];
+  return out;
+}
+__name(flushPendingToolResults, "flushPendingToolResults");
 function createToolSeen() {
   return {
     started: /* @__PURE__ */ new Set(),
     completed: /* @__PURE__ */ new Set(),
+    pending: [],
     sawThinkingDelta: false
   };
 }
@@ -983,15 +1064,37 @@ function translateTimelineEvent(ev, runId, seen) {
   if (ev.kind === "delta") {
     if (ev.update === void 0) return [];
     const events2 = translateInteractionUpdate(ev.update);
-    return dedupeTools(events2, ev.update, seen);
+    const released2 = releasePendingToolResults(events2, seen);
+    return [
+      ...released2,
+      ...dedupeTools(events2, ev.update, seen)
+    ];
   }
   if (ev.message === void 0) return [];
   const events = translateSdkEvent(ev.message, runId);
   const kept = ev.textAlreadyStreamed === true ? events.filter((e) => e.type !== "text_delta") : events;
-  return dedupeTools(kept, ev.message, seen);
+  const released = releasePendingToolResults(kept, seen);
+  return [
+    ...released,
+    ...dedupeTools(kept, ev.message, seen)
+  ];
 }
 __name(translateTimelineEvent, "translateTimelineEvent");
 
+// src/bridge/tool-context-injection.ts
+function withInjectedToolContext(handler, injection) {
+  return (input, ctx) => handler(input, {
+    ...ctx,
+    ...injection.runContext !== void 0 ? {
+      context: injection.runContext.value
+    } : {},
+    ...injection.meter !== void 0 ? {
+      usage: injection.meter.snapshot()
+    } : {}
+  });
+}
+__name(withInjectedToolContext, "withInjectedToolContext");
+
 // src/bridge/tool-dialect-stripper.ts
 var OPEN2 = "<function=";
 var CLOSE2 = "</tool_call>";
@@ -1090,6 +1193,61 @@ async function* stripToolDialectStream(source) {
 }
 __name(stripToolDialectStream, "stripToolDialectStream");
 
+// src/bridge/turn-retry.ts
+import { TheokitAgentError as TheokitAgentError2 } from "@theokit/sdk/errors";
+function asText(value) {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+__name(asText, "asText");
+function startFailure(event, outcome) {
+  if (outcome.failure !== void 0) return outcome.failure;
+  return new TheokitAgentError2(asText(event.message) ?? "The turn failed before producing any output.", {
+    code: asText(event.code) ?? "TURN_START_FAILED",
+    isRetryable: event.retryable === true
+  });
+}
+__name(startFailure, "startFailure");
+async function startTurn(open, retry) {
+  const attempt = /* @__PURE__ */ __name(async () => {
+    const { stream, outcome } = open();
+    const it = stream[Symbol.asyncIterator]();
+    try {
+      const first = await it.next();
+      if (!first.done && first.value.type === "error") throw startFailure(first.value, outcome);
+      return {
+        it,
+        first
+      };
+    } catch (err) {
+      await it.return?.(void 0);
+      throw err;
+    }
+  }, "attempt");
+  const { Retry } = await import("@theokit/sdk/retry");
+  return Retry.create(attempt, retry);
+}
+__name(startTurn, "startTurn");
+async function* withTurnStartRetry(open, retry) {
+  const { it, first } = await startTurn(open, retry);
+  let next = first;
+  while (!next.done) {
+    yield next.value;
+    next = await it.next();
+  }
+}
+__name(withTurnStartRetry, "withTurnStartRetry");
+function runTurnWithRetry(open, retry) {
+  if (retry === void 0) return open();
+  return withTurnStartRetry(() => {
+    const outcome = {};
+    return {
+      stream: open(outcome),
+      outcome
+    };
+  }, retry);
+}
+__name(runTurnWithRetry, "runTurnWithRetry");
+
 // src/bridge/sdk-adapter.ts
 function withLeakedDialectRecovery(providers) {
   return {
@@ -1121,6 +1279,10 @@ function buildExtraCreateOptions(overrides, compiled) {
   return extra;
 }
 __name(buildExtraCreateOptions, "buildExtraCreateOptions");
+function applyStepCeiling(sendOptions, maxIterations) {
+  if (maxIterations !== void 0) sendOptions.maxIterations = maxIterations;
+}
+__name(applyStepCeiling, "applyStepCeiling");
 async function loadSdkRuntime() {
   try {
     const sdk = await import("@theokit/sdk");
@@ -1157,15 +1319,19 @@ function hasZodInputSchema(schema) {
   return typeof schema?.parse === "function";
 }
 __name(hasZodInputSchema, "hasZodInputSchema");
-function withRunContext(handler, runContext) {
-  return (input, ctx) => handler(input, {
-    ...ctx,
-    context: runContext
-  });
-}
-__name(withRunContext, "withRunContext");
-function buildSdkTools(compiledTools, defineTool, extraSdkTools = [], runContext) {
-  const has = runContext !== void 0;
+function buildSdkTools(compiledTools, defineTool, extraSdkTools = [], runContext, meter) {
+  const injection = {
+    ...runContext !== void 0 ? {
+      runContext: {
+        value: runContext
+      }
+    } : {},
+    ...meter !== void 0 ? {
+      meter
+    } : {}
+  };
+  const has = injection.runContext !== void 0 || injection.meter !== void 0;
+  const inject = /* @__PURE__ */ __name((h) => has ? withInjectedToolContext(h, injection) : h, "inject");
   return [
     ...compiledTools.map((t) => {
       if (hasZodInputSchema(t.inputSchema)) {
@@ -1173,17 +1339,17 @@ function buildSdkTools(compiledTools, defineTool, extraSdkTools = [], runContext
           name: t.name,
           description: t.description,
           inputSchema: t.inputSchema,
-          handler: has ? withRunContext(t.handler, runContext) : t.handler
+          handler: inject(t.handler)
         });
       }
       return has ? {
         ...t,
-        handler: withRunContext(t.handler, runContext)
+        handler: inject(t.handler)
       } : t;
     }),
     ...extraSdkTools.map((t) => has ? {
       ...t,
-      handler: withRunContext(t.handler, runContext)
+      handler: inject(t.handler)
     } : t)
   ];
 }
@@ -1208,7 +1374,11 @@ function createSdkAgentStream(compiled, compiledTools, apiKey, overrides = {}) {
         };
         return;
       }
-      const sdkTools = buildSdkTools(compiledTools, rt.defineTool, overrides.sdkTools, runContext);
+      const usageMeter = overrides.exposeUsageToTools === true ? createRunUsageMeter({
+        contextWindowTokens: contextWindowOf(model),
+        delegate: overrides.budgetTracker
+      }) : void 0;
+      const sdkTools = buildSdkTools(compiledTools, rt.defineTool, overrides.sdkTools, runContext, usageMeter);
       const inlineSkills = compiled.skills?.inline;
       if (inlineSkills !== void 0 && inlineSkills.length > 0 && rt.defineSkillReadTool !== void 0 && !compiledTools.some((t) => t.name === "skill_read")) {
         sdkTools.push(rt.defineSkillReadTool(inlineSkills));
@@ -1225,20 +1395,27 @@ function createSdkAgentStream(compiled, compiledTools, apiKey, overrides = {}) {
         source: runContextSource,
         keys: runContext !== void 0 ? Object.keys(runContext) : []
       });
+      const turnOpts = {
+        apiKey: await resolverApiKey(apiKey),
+        model,
+        reasoningEffort,
+        overrides,
+        parseThinkTags,
+        stripToolDialect,
+        sessionId,
+        message,
+        factoryOpts,
+        runId,
+        t0,
+        ...usageMeter !== void 0 ? {
+          usageMeter
+        } : {}
+      };
       try {
-        yield* streamSdkAgent(rt, compiled, sdkTools, {
-          apiKey: await resolverApiKey(apiKey),
-          model,
-          reasoningEffort,
-          overrides,
-          parseThinkTags,
-          stripToolDialect,
-          sessionId,
-          message,
-          factoryOpts,
-          runId,
-          t0
-        });
+        yield* runTurnWithRetry((outcome) => streamSdkAgent(rt, compiled, sdkTools, outcome === void 0 ? turnOpts : {
+          ...turnOpts,
+          outcome
+        }), overrides.retry);
       } catch (err) {
         yield sdkErrorEvent(err);
       }
@@ -1262,6 +1439,7 @@ async function* streamSdkAgent(rt, compiled, sdkTools, opts) {
     baseDir: overrides.baseDir
   };
   const extra = buildExtraCreateOptions(overrides, compiled);
+  if (opts.usageMeter !== void 0) extra.budgetTracker = opts.usageMeter.tracker;
   if (applied.length > 0) {
     debugLog("[THEO_AGENT_M8_RUNTIME_APPLIED]", {
       skills: applied.includes("skills"),
@@ -1283,6 +1461,7 @@ async function* streamSdkAgent(rt, compiled, sdkTools, opts) {
     };
     const sendOptions = {};
     if (factoryOpts?.disableTools === true) sendOptions.toolChoice = "none";
+    applyStepCeiling(sendOptions, compiled.maxIterations);
     if (overrides.onRunEvent !== void 0) sendOptions.onRunEvent = overrides.onRunEvent;
     const sendInput = overrides.images && overrides.images.length > 0 ? {
       text: message,
@@ -1292,14 +1471,22 @@ async function* streamSdkAgent(rt, compiled, sdkTools, opts) {
     const timeline = /* @__PURE__ */ __name(async function* () {
       const run = await sendPromise;
       const seen = createToolSeen();
-      for await (const ev of run.events()) {
-        for (const event of translateTimelineEvent(ev, runId, seen)) {
+      const emit = /* @__PURE__ */ __name(function* (events) {
+        for (const event of events) {
           if (event.type === "error") state.sawError = true;
           if (event.type === "done") continue;
           state.lastEventType = event.type;
           yield event;
         }
+      }, "emit");
+      for await (const ev of run.events()) {
+        const translated = translateTimelineEvent(ev, runId, seen);
+        if (opts.outcome !== void 0 && state.lastEventType === "" && translated.some((e) => e.type === "error")) {
+          opts.outcome.failure = (await (await sendPromise).wait()).error?.cause;
+        }
+        yield* emit(translated);
       }
+      yield* emit(flushPendingToolResults(seen));
     }, "timeline");
     for await (const event of applyTextTransforms(timeline(), {
       parseThinkTags,
@@ -1317,7 +1504,7 @@ async function* streamSdkAgent(rt, compiled, sdkTools, opts) {
         };
       }
     } else {
-      yield realUsageDone(await (await sendPromise).wait(), t0);
+      yield realUsageDone(await (await sendPromise).wait(), t0, modelIdOf(model));
     }
   } finally {
     await agent.dispose();
@@ -1356,10 +1543,24 @@ function toAgentFactory(def, opts) {
       ...m8,
       ...extra
     });
-    return withGuardrails(agent, compiled.guardrails);
+    return withGuardrails(withStepCeiling(agent, compiled.maxIterations), compiled.guardrails);
   };
 }
 __name(toAgentFactory, "toAgentFactory");
+function withStepCeiling(handle, maxIterations) {
+  if (maxIterations === void 0) return handle;
+  return {
+    get agentId() {
+      return handle.agentId;
+    },
+    dispose: /* @__PURE__ */ __name(() => handle.dispose(), "dispose"),
+    send: /* @__PURE__ */ __name((msg, sendOpts) => handle.send(msg, {
+      maxIterations,
+      ...sendOpts
+    }), "send")
+  };
+}
+__name(withStepCeiling, "withStepCeiling");
 function withGuardrails(handle, guardrails) {
   if (guardrails === void 0 || guardrails.length === 0) return handle;
   return {
@@ -1491,8 +1692,8 @@ var noopReflectionStrategy = {
 };
 
 // src/bridge/delegation-types.ts
-import { TheokitAgentError as TheokitAgentError2 } from "@theokit/sdk/errors";
-var DelegationBudgetExceededError = class extends TheokitAgentError2 {
+import { TheokitAgentError as TheokitAgentError3 } from "@theokit/sdk/errors";
+var DelegationBudgetExceededError = class extends TheokitAgentError3 {
   static {
     __name(this, "DelegationBudgetExceededError");
   }
@@ -1509,7 +1710,7 @@ var DelegationBudgetExceededError = class extends TheokitAgentError2 {
   }
 };
 var BudgetExceededError = DelegationBudgetExceededError;
-var DelegationError = class extends TheokitAgentError2 {
+var DelegationError = class extends TheokitAgentError3 {
   static {
     __name(this, "DelegationError");
   }
@@ -2029,9 +2230,10 @@ __name(formatUnrecognised, "formatUnrecognised");
 
 // src/bridge/agent-orchestrator.ts
 function requireApiKey(opts, agentName) {
+  if (opts.apiKey === null) return "";
   const apiKey = opts.apiKey ?? "";
   if (!apiKey) {
-    throw new DelegationError(agentName, "No API key provided. Pass apiKey in DelegateOptions.");
+    throw new DelegationError(agentName, "No API key provided. Pass apiKey in DelegateOptions, or `apiKey: null` when the provider takes no credential (a local model).");
   }
   return apiKey;
 }
@@ -2098,8 +2300,8 @@ async function delegate(spec, message, opts = {}) {
 __name(delegate, "delegate");
 
 // src/bridge/delegation-lifecycle.ts
-import { TheokitAgentError as TheokitAgentError3 } from "@theokit/sdk/errors";
-var DelegationTimeoutError = class extends TheokitAgentError3 {
+import { TheokitAgentError as TheokitAgentError4 } from "@theokit/sdk/errors";
+var DelegationTimeoutError = class extends TheokitAgentError4 {
   static {
     __name(this, "DelegationTimeoutError");
   }
@@ -2262,4 +2464,4 @@ export {
   delegateBackground,
   delegateWithScoring
 };
-//# sourceMappingURL=chunk-CKRM5Q2K.js.map
+//# sourceMappingURL=chunk-2I6DQUJP.js.map