@theokit/sdk 2.1.0 → 2.3.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 2.3.0
+
+### Minor Changes
+
+- d7d5215: M1-3 — `buildReplayHistory(base, events, options)` pure stateless continuation-history rebuild (plan `m1-continuation-history`).
+
+  The stateless complement to M1 Phase 3's `runToCompletion` (which covers the stateful-session path). For a server / serverless handler that re-runs an agent on a fresh request and must reconstruct working memory from persisted stream events, `buildReplayHistory` serializes a round's `SDKMessage[]` into a bounded `StoredMessage[]` you can replay as prior history:
+
+  - maps assistant text → `assistant`; tool `running` → `tool_call` (args); tool `completed`/`error` → `tool_result` (carrying the result content the continued model needs);
+  - drops the oldest turns — pair-safe (a `tool_call` and its `tool_result` are never split) — until the total fits a context-window-derived char budget, keeping ≥ 1;
+  - truncates an oversized single turn (reusing the SDK's `truncateWithMarker`) rather than dropping it;
+  - pure, synchronous, dependency-free; a non-finite `contextWindowTokens` collapses to budget 0 (never returns an unbounded history).
+
+  Exported from `@theokit/sdk` with `ReplayHistoryOptions`. Replaces the outer-loop history rebuild a code-assistant server otherwise hand-rolls.
+
+- f218630: M1 Phase 3 — `agent.runToCompletion()` continuation driver (plan `m1-run-to-completion`).
+
+  Builds on M1-2's `RunResult.stoppedAtIterationLimit` signal: a single `agent.send()` truncates when the model still wants tools at the loop's iteration ceiling. `runToCompletion(message, options?)` re-sends a short continuation prompt — the agent's stateful session preserves the conversation — until a genuine terminal:
+
+  - `done` — a round finished without truncating.
+  - `step_limit` — `maxRounds` (default 5) exhausted, or aborted via `signal`, while still truncating.
+  - `no_progress` — two consecutive rounds produced empty output.
+
+  Returns `{ terminal, rounds, lastResult, usage }` with token usage summed across rounds. Options: `maxRounds`, `continuationPrompt`, `onTruncated`, `signal`, `sendOptions`. Local agents only — cloud agents throw `UnsupportedRunOperationError` (the cloud runtime manages continuation server-side). This replaces the outer continuation loop a code-assistant builder would otherwise hand-roll.
+
+## 2.2.0
+
+### Minor Changes
+
+- efe183e: M1 Reliable harness — make the agent loop's iteration ceiling real (plan `m1-reliable-harness`).
+
+  - **M1-1:** the agent loop now calls `BudgetTracker.nextIteration?.()` once per completed turn, and `nextIteration?()` is an optional member of the `BudgetTracker` interface. `createCounterBudgetTracker({ maxIterations: N })` now actually halts the loop after N turns (it was dead — nothing called it). Additive and backward-compatible: trackers that only gate on tokens/USD omit the method.
+  - **M1-2 (knob):** `SendOptions.maxIterations` lets a builder raise/lower the loop's default 8-turn cap per `agent.send` call. Validated at the boundary (positive integer; invalid throws `ConfigurationError`). Default of 8 preserved when unset.
+  - **M1-2 (truncation signal):** `RunResult.stoppedAtIterationLimit` is `true` when the loop stopped at its iteration ceiling with tool work still pending (silent truncation) vs a clean `done` finish. Lets a caller/continuation driver detect and recover.
+
 ## 2.1.0
 
 ### Minor Changes

package/dist/a2a/index.cjs

@@ -2313,6 +2313,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;
+}
 var FixtureRunBase;
 var init_fixture_run_base = __esm({
   "src/internal/runtime/fixtures/fixture-run-base.ts"() {
@@ -2419,8 +2424,7 @@ var init_fixture_run_base = __esm({
         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). */
@@ -2999,6 +3003,18 @@ var init_cloud_agent = __esm({
           "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 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
@@ -8008,6 +8024,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);
@@ -8016,18 +8033,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";
@@ -8058,7 +8083,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) {
@@ -11007,6 +11033,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 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;
@@ -11045,6 +11078,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 } : {},
@@ -11104,6 +11140,7 @@ function buildMcpMap(options) {
 var pluginProvidersAnnounced, RealLocalRun;
 var init_real_local_run = __esm({
   "src/internal/runtime/local-agent/real-local-run.ts"() {
+    init_errors();
     init_loop();
     init_fallback_client();
     init_model_identifier();
@@ -11191,6 +11228,7 @@ var init_real_local_run = __esm({
         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,
@@ -14164,6 +14202,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, state2) {
+  const run = await agent.send(prompt, sendOptions);
+  const result = await run.wait();
+  const usage = addUsage(state2.usage, result.usage);
+  const decision = classifyRound(result, round, maxRounds, state2.emptyStreak);
+  if (decision !== "continue") return { terminal: buildResult(decision, round, result, usage) };
+  const emptyStreak = isEmptyRound(result) ? state2.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 state2 = { 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, state2);
+    if ("terminal" in outcome) return outcome.terminal;
+    state2 = outcome.next;
+    await onTruncated?.({ round });
+    if (signal?.aborted === true) {
+      return buildResult("step_limit", round, outcome.lastResult, state2.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, {
@@ -14244,6 +14347,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));
@@ -15378,6 +15488,10 @@ var init_local_agent = __esm({
       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);
+      }
     };
   }
 });