@theokit/sdk 2.1.0 → 2.3.0

package/dist/index.cjs

@@ -2799,6 +2799,71 @@ var init_agent_factory_registry = __esm({
   }
 });
 
+// src/internal/runtime/lifecycle/run-to-completion.ts
+var run_to_completion_exports = {};
+__export(run_to_completion_exports, {
+  classifyRound: () => classifyRound,
+  runToCompletionImpl: () => runToCompletionImpl
+});
+function isEmptyRound(result) {
+  return (result.result ?? "").trim() === "";
+}
+function classifyRound(result, round, maxRounds, emptyStreak) {
+  if (result.stoppedAtIterationLimit !== true) return "done";
+  if (isEmptyRound(result) && emptyStreak >= 1) return "no_progress";
+  if (round >= maxRounds) return "step_limit";
+  return "continue";
+}
+function addUsage(acc, u) {
+  if (u === void 0) return acc;
+  const inputTokens = (acc?.inputTokens ?? 0) + u.inputTokens;
+  const outputTokens = (acc?.outputTokens ?? 0) + u.outputTokens;
+  const sumOpt = (a, b) => a === void 0 && b === void 0 ? void 0 : (a ?? 0) + (b ?? 0);
+  return {
+    inputTokens,
+    outputTokens,
+    totalTokens: inputTokens + outputTokens,
+    cacheReadTokens: sumOpt(acc?.cacheReadTokens, u.cacheReadTokens),
+    cacheWriteTokens: sumOpt(acc?.cacheWriteTokens, u.cacheWriteTokens),
+    reasoningTokens: sumOpt(acc?.reasoningTokens, u.reasoningTokens)
+  };
+}
+function buildResult(terminal, rounds, lastResult, usage) {
+  return { terminal, rounds, lastResult, ...usage !== void 0 ? { usage } : {} };
+}
+async function stepRound(agent, prompt, sendOptions, round, maxRounds, state4) {
+  const run = await agent.send(prompt, sendOptions);
+  const result = await run.wait();
+  const usage = addUsage(state4.usage, result.usage);
+  const decision = classifyRound(result, round, maxRounds, state4.emptyStreak);
+  if (decision !== "continue") return { terminal: buildResult(decision, round, result, usage) };
+  const emptyStreak = isEmptyRound(result) ? state4.emptyStreak + 1 : 0;
+  return { next: { usage, emptyStreak }, lastResult: result };
+}
+async function runToCompletionImpl(agent, message, options) {
+  const maxRounds = options?.maxRounds ?? DEFAULT_MAX_ROUNDS;
+  const continuationPrompt = options?.continuationPrompt ?? DEFAULT_CONTINUATION_PROMPT;
+  const { onTruncated, signal, sendOptions } = options ?? {};
+  let state4 = { usage: void 0, emptyStreak: 0 };
+  for (let round = 0; ; round += 1) {
+    const prompt = round === 0 ? message : continuationPrompt;
+    const outcome = await stepRound(agent, prompt, sendOptions, round, maxRounds, state4);
+    if ("terminal" in outcome) return outcome.terminal;
+    state4 = outcome.next;
+    await onTruncated?.({ round });
+    if (signal?.aborted === true) {
+      return buildResult("step_limit", round, outcome.lastResult, state4.usage);
+    }
+  }
+}
+var DEFAULT_MAX_ROUNDS, DEFAULT_CONTINUATION_PROMPT;
+var init_run_to_completion = __esm({
+  "src/internal/runtime/lifecycle/run-to-completion.ts"() {
+    DEFAULT_MAX_ROUNDS = 5;
+    DEFAULT_CONTINUATION_PROMPT = "Continue from where you left off and finish the task. If it is already complete, give the final answer.";
+  }
+});
+
 // src/internal/runtime/lifecycle/fork-agent.ts
 var fork_agent_exports = {};
 __export(fork_agent_exports, {
@@ -2887,10 +2952,10 @@ var RingBuffer;
 var init_ring_buffer = __esm({
   "src/internal/task/ring-buffer.ts"() {
     RingBuffer = class {
-      constructor(cap) {
-        this.cap = cap;
-        if (!Number.isInteger(cap) || cap < 1) {
-          throw new Error(`RingBuffer capacity must be a positive integer, got ${cap}`);
+      constructor(cap2) {
+        this.cap = cap2;
+        if (!Number.isInteger(cap2) || cap2 < 1) {
+          throw new Error(`RingBuffer capacity must be a positive integer, got ${cap2}`);
         }
       }
       cap;
@@ -6807,8 +6872,7 @@ var FixtureRunBase = class {
     if (status === "error" && this.script.errorDetail !== void 0) {
       base.error = this.script.errorDetail;
     }
-    if (this.script.usage !== void 0) base.usage = this.script.usage;
-    if (this.script.cost !== void 0) base.cost = this.script.cost;
+    applyScriptMetrics(base, this.script);
     return this.extendRunResult(applyExtraRunFields(base, this.script));
   }
   /** Subclasses override to attach runtime-specific fields (e.g. cloud git info). */
@@ -6842,6 +6906,11 @@ function makeNotifier() {
   });
   return { promise, resolve: resolve3 };
 }
+function applyScriptMetrics(base, script) {
+  if (script.usage !== void 0) base.usage = script.usage;
+  if (script.cost !== void 0) base.cost = script.cost;
+  if (script.stoppedAtIterationLimit === true) base.stoppedAtIterationLimit = true;
+}
 
 // src/internal/runtime/cloud/cloud-run.ts
 function createCloudRun(options) {
@@ -7350,6 +7419,18 @@ var CloudAgent = class {
       "fork"
     );
   }
+  /**
+   * The continuation driver re-sends against a stateful local session; the
+   * cloud runtime manages its own continuation policy server-side (M1 Phase 3).
+   *
+   * @public
+   */
+  runToCompletion() {
+    throw new exports.UnsupportedRunOperationError(
+      "Agent.runToCompletion() is not supported on cloud agents. Cloud runtime manages continuation server-side. Use a local agent.",
+      "runToCompletion"
+    );
+  }
   /**
    * Personality presets require consistent server-side enforcement that
    * the cloud runtime (pre-release) does not yet provide. Reject explicitly
@@ -10121,7 +10202,7 @@ async function loadPluginManifestFromJson(manifestPath, folderName) {
   const record = parsed;
   const name = typeof record.name === "string" ? record.name : folderName;
   const version = typeof record.version === "string" ? record.version : "0.0.0";
-  const capabilities = Array.isArray(record.capabilities) ? record.capabilities.filter((cap) => typeof cap === "string") : [];
+  const capabilities = Array.isArray(record.capabilities) ? record.capabilities.filter((cap2) => typeof cap2 === "string") : [];
   const source = manifestPath.slice(manifestPath.indexOf(".theokit/"));
   const metadata = { name, version, capabilities, source };
   if (typeof record.entry === "string") metadata.entry = record.entry;
@@ -10444,6 +10525,9 @@ var LocalRun = class extends FixtureRunBase {
   }
 };
 
+// src/internal/runtime/local-agent/real-local-run.ts
+init_errors();
+
 // src/internal/runtime/budget/budget.ts
 var IterationBudget = class {
   #remaining;
@@ -11668,6 +11752,7 @@ async function runAgentLoop(inputs) {
     const ctx = await initLoopContext(inputs);
     ctxRef = ctx;
     const budget = inputs.budget ?? new IterationBudget({ maxIterations: inputs.maxIterations ?? 8 });
+    let lastTurnDecision;
     while (budget.shouldContinue()) {
       if (inputs.budgetTracker !== void 0) {
         const decision2 = evaluateBudgetGate(inputs.budgetTracker);
@@ -11676,18 +11761,26 @@ async function runAgentLoop(inputs) {
           if (decision2.detail !== void 0) {
             ctx.error = { message: decision2.detail, code: decision2.reason ?? "budget" };
           }
+          if (decision2.reason === "iteration_limit") {
+            ctx.stoppedAtIterationLimit = true;
+          }
           break;
         }
       }
       const usingGrace = budget.remaining <= 0 && !budget.graceCallUsed;
       if (usingGrace) budget.useGraceCall();
       const decision = await runIteration(inputs, ctx);
+      lastTurnDecision = decision;
       if (decision === "done") break;
       if (decision === "error") {
         ctx.finalStatus = "error";
         break;
       }
       budget.consume();
+      inputs.budgetTracker?.nextIteration?.();
+    }
+    if (lastTurnDecision === "continue" && budget.shouldContinue() === false) {
+      ctx.stoppedAtIterationLimit = true;
     }
     if (budget.shouldContinue() === false && ctx.finalStatus === "finished" && ctx.finalText === "") {
       ctx.finalStatus = "error";
@@ -11718,7 +11811,8 @@ async function runAgentLoop(inputs) {
       conversation: ctx.conversation,
       ...usage !== void 0 ? { usage } : {},
       ...cost !== void 0 ? { cost } : {},
-      ...ctx.error !== void 0 ? { error: ctx.error } : {}
+      ...ctx.error !== void 0 ? { error: ctx.error } : {},
+      ...ctx.stoppedAtIterationLimit === true ? { stoppedAtIterationLimit: true } : {}
     };
   } finally {
     if (ctxRef !== void 0 && ctxRef.memoryProviderHandle !== void 0 && inputs.memoryProvider !== void 0) {
@@ -11775,8 +11869,8 @@ function handleToolErrorContinuation(inputs, ctx, toolResults) {
   const hasError = toolResults.some((part) => part.type === "tool_result" && part.isError === true);
   if (hasError) {
     ctx._consecutiveToolErrors = (ctx._consecutiveToolErrors ?? 0) + 1;
-    const cap = inputs.maxConsecutiveToolErrors ?? 3;
-    if (ctx._consecutiveToolErrors >= cap) return "error";
+    const cap2 = inputs.maxConsecutiveToolErrors ?? 3;
+    if (ctx._consecutiveToolErrors >= cap2) return "error";
     return "continue";
   }
   ctx._consecutiveToolErrors = 0;
@@ -14153,6 +14247,13 @@ function resolveRunProvider(options) {
   return { primary, effectiveModelId };
 }
 function buildLoopInputs(options, runId, userText) {
+  const maxIterations = options.sendOptions.maxIterations;
+  if (maxIterations !== void 0 && (!Number.isInteger(maxIterations) || maxIterations < 1)) {
+    throw new exports.ConfigurationError(
+      `SendOptions.maxIterations must be a positive integer, got ${maxIterations}`,
+      { code: "invalid_max_iterations" }
+    );
+  }
   const { primary, effectiveModelId } = resolveRunProvider(options);
   const fallback = options.agentOptions.providers?.fallback;
   const apiKeys = options.agentOptions.providers?.apiKeys;
@@ -14191,6 +14292,9 @@ function buildLoopInputs(options, runId, userText) {
     // D318 — forward SendOptions.signal to the agent loop so streamLlmTurn
     // can attach it to the LLM `fetch({ signal })` call.
     ...options.sendOptions.signal !== void 0 ? { signal: options.sendOptions.signal } : {},
+    // M1-2: per-send iteration ceiling (validated above). The loop reads
+    // inputs.maxIterations (default 8 when unset).
+    ...maxIterations !== void 0 ? { maxIterations } : {},
     // D315-D317 — tool lifecycle hooks (cost tracking + audit + retry/alert)
     ...options.agentOptions.onToolStart !== void 0 ? { onToolStart: options.agentOptions.onToolStart } : {},
     ...options.agentOptions.onToolEnd !== void 0 ? { onToolEnd: options.agentOptions.onToolEnd } : {},
@@ -14322,6 +14426,7 @@ var RealLocalRun = class extends FixtureRunBase {
     if (output.result.length > 0) this.script.result = output.result;
     if (output.usage !== void 0) this.script.usage = output.usage;
     if (output.cost !== void 0) this.script.cost = output.cost;
+    if (output.stoppedAtIterationLimit === true) this.script.stoppedAtIterationLimit = true;
     if (output.error !== void 0 && this.script.errorDetail === void 0) {
       this.script.errorDetail = {
         message: output.error.message,
@@ -15259,7 +15364,7 @@ var MEMORY_GET_SCHEMA = {
 };
 var DEFAULT_MAX_TOTAL_CHARS = 16384;
 function createMemorySearchTool(opts) {
-  const cap = opts.maxTotalChars ?? DEFAULT_MAX_TOTAL_CHARS;
+  const cap2 = opts.maxTotalChars ?? DEFAULT_MAX_TOTAL_CHARS;
   return {
     name: "memory_search",
     description: SEARCH_DESCRIPTION,
@@ -15276,7 +15381,7 @@ function createMemorySearchTool(opts) {
         ...sources !== void 0 ? { sources } : {}
       };
       const hits = await opts.index.search(query, searchOptions);
-      return JSON.stringify(capByTotalChars(hits, cap));
+      return JSON.stringify(capByTotalChars(hits, cap2));
     }
   };
 }
@@ -15844,6 +15949,13 @@ function localAgentRunUntil(agent, goal, options) {
   }
   return wrap();
 }
+function localAgentRunToCompletion(agent, message, options) {
+  async function run() {
+    const { runToCompletionImpl: runToCompletionImpl2 } = await Promise.resolve().then(() => (init_run_to_completion(), run_to_completion_exports));
+    return runToCompletionImpl2({ send: (m, o) => agent.send(m, o) }, message, options);
+  }
+  return run();
+}
 async function localAgentFork(parent, options) {
   const { forkAgentImpl: forkAgentImpl2 } = await Promise.resolve().then(() => (init_fork_agent(), fork_agent_exports));
   const { getAgentFacade: getAgentFacade2 } = await Promise.resolve().then(() => (init_agent_factory_registry(), agent_factory_registry_exports));
@@ -15907,8 +16019,8 @@ async function applyPreUserSendHook(args) {
     ...args.options.memoryContext !== void 0 ? { memoryContext: args.options.memoryContext } : {},
     ...args.sendOptions.signal !== void 0 ? { signal: args.sendOptions.signal } : {}
   };
-  const cap = args.options.maxRecallContextBytes ?? DEFAULT_MAX_RECALL_BYTES;
-  const recalled = await args.pluginManager.runPreUserSendHooks(ctx, cap);
+  const cap2 = args.options.maxRecallContextBytes ?? DEFAULT_MAX_RECALL_BYTES;
+  const recalled = await args.pluginManager.runPreUserSendHooks(ctx, cap2);
   if (recalled === void 0 || recalled.length === 0) return args.original;
   const wrapped = `<memory-context>
 ${recalled}
@@ -16384,6 +16496,10 @@ var LocalAgent = class {
   fork(options) {
     return localAgentFork({ agentId: this.agentId, options: this.options, personalitySlugSnapshot: this.personalityStore.active(this.agentId) }, options);
   }
+  // biome-ignore format: G8 budget — see runUntil comment above.
+  runToCompletion(message, options) {
+    return localAgentRunToCompletion(this, message, options);
+  }
 };
 function resolveCwd(cwd) {
   return (Array.isArray(cwd) ? cwd[0] : cwd) ?? process.cwd();
@@ -17899,6 +18015,77 @@ function createCounterBudgetTracker(options = {}) {
   };
 }
 
+// src/internal/runtime/context/replay-history.ts
+var CHARS_PER_TOKEN = 4;
+var DEFAULT_RESERVE_TOKENS = 8e3;
+function finiteOr(value, fallback) {
+  return Number.isFinite(value) ? value : fallback;
+}
+function charBudget(options) {
+  const window = finiteOr(options.contextWindowTokens, 0);
+  const reserve = finiteOr(options.reserveTokens ?? DEFAULT_RESERVE_TOKENS, DEFAULT_RESERVE_TOKENS);
+  return Math.max(0, window - reserve) * CHARS_PER_TOKEN;
+}
+function assistantText2(event) {
+  return event.message.content.filter((block) => block.type === "text").map((block) => block.text).join("");
+}
+function stringifyPayload(value) {
+  if (value === void 0) return "";
+  return typeof value === "string" ? value : JSON.stringify(value) ?? "";
+}
+function cap(content, perItemCap) {
+  return truncateWithMarker(content, Math.max(0, perItemCap)).finalContent;
+}
+function mapEvent(event, perItemCap) {
+  if (event.type === "assistant") {
+    const text = assistantText2(event);
+    return text.length > 0 ? { message: { role: "assistant", content: cap(text, perItemCap) } } : null;
+  }
+  if (event.type === "tool_call") {
+    if (event.status === "running") {
+      const content2 = cap(`[tool_call ${event.name}] ${stringifyPayload(event.args)}`, perItemCap);
+      return { message: { role: "tool_call", content: content2 }, pairId: event.call_id };
+    }
+    const content = cap(
+      `[tool_result ${event.name}] ${stringifyPayload(event.result)}`,
+      perItemCap
+    );
+    return { message: { role: "tool_result", content }, pairId: event.call_id };
+  }
+  return null;
+}
+function evictionIndices(turns) {
+  const head = turns[0];
+  if (head?.pairId === void 0) return [0];
+  const indices = [];
+  for (let i = 0; i < turns.length; i += 1) {
+    if (turns[i]?.pairId === head.pairId) indices.push(i);
+  }
+  return indices;
+}
+function totalChars(turns) {
+  return turns.reduce((n, t) => n + t.message.content.length, 0);
+}
+function trimToBudget(turns, budgetChars) {
+  const kept = [...turns];
+  while (kept.length > 1 && totalChars(kept) > budgetChars) {
+    const evict = evictionIndices(kept);
+    if (kept.length - evict.length < 1) break;
+    for (const idx of evict.sort((a, b) => b - a)) kept.splice(idx, 1);
+  }
+  return kept;
+}
+function buildReplayHistory(base, events, options) {
+  const budgetChars = charBudget(options);
+  const perItemCap = Math.max(0, options.perItemCap ?? Math.floor(budgetChars / 2));
+  const turns = base.map((message) => ({ message }));
+  for (const event of events) {
+    const turn = mapEvent(event, perItemCap);
+    if (turn !== null) turns.push(turn);
+  }
+  return trimToBudget(turns, budgetChars).map((t) => t.message);
+}
+
 // src/internal/runtime/memory/memory-provider-noop.ts
 var NOOP_ADAPTER_ID = "noop";
 var NOOP_CAPABILITIES = {
@@ -19283,6 +19470,7 @@ exports.Security = Security;
 exports.Task = Task;
 exports.Theokit = Theokit;
 exports.UsageAccumulator = UsageAccumulator;
+exports.buildReplayHistory = buildReplayHistory;
 exports.chargeAndCheckThresholds = chargeAndCheckThresholds;
 exports.computeCost = computeCost;
 exports.createAgentFactory = createAgentFactory;