@theokit/sdk 2.1.0 → 2.2.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 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). */
@@ -8008,6 +8012,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 +8021,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 +8071,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 +11021,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 +11066,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 +11128,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 +11216,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,