@prestyj/agent 5.9.0 → 5.11.0

package/dist/index.d.cts

@@ -20,6 +20,13 @@ interface AgentTool<T extends z.ZodType = z.ZodType> extends Tool {
      * batch runs in source order so stateful mutations cannot race each other.
      */
     executionMode?: ToolExecutionMode;
+    /**
+     * Overrides the loop's default per-tool timeout. A tool that owns a longer
+     * internal budget than the default must declare it here, or the loop cancels
+     * it first and the tool's own timeout — with its specific, actionable error
+     * message — becomes unreachable.
+     */
+    timeoutMs?: number;
     execute: (args: z.infer<T>, context: ToolContext) => ToolExecuteResult | Promise<ToolExecuteResult>;
 }
 interface AgentTextDeltaEvent {
@@ -70,6 +77,21 @@ interface AgentTurnEndEvent {
     usage: Usage;
     timing: AgentTurnTiming;
 }
+/**
+ * A safe point between steps: the assistant message and every tool result for
+ * this turn are now in the message array, and no provider call is in flight.
+ *
+ * Hosts that persist a transcript flush here. Without it a crash mid-run loses
+ * the WHOLE turn — including tool results whose side effects already landed on
+ * disk — because the only flush happens after the loop returns.
+ *
+ * Yielded immediately after tool results are appended, so it pairs with
+ * `turn_end` (which covers the assistant half) to cover every message.
+ */
+interface AgentCheckpointEvent {
+    type: "checkpoint";
+    turn: number;
+}
 interface AgentDoneEvent {
     type: "agent_done";
     totalTurns: number;
@@ -87,6 +109,21 @@ interface AgentMaxTurnsEvent {
     totalTurns: number;
     maxTurns: number;
 }
+/**
+ * Emitted when the loop was about to stop on an exhausted turn budget but the
+ * host granted an extension instead. The effective budget is raised and the
+ * loop continues with a continuation prompt, so this is NOT terminal — unlike
+ * `max_turns`, which still fires if the extended budget is also spent.
+ */
+interface AgentTurnBudgetExtendedEvent {
+    type: "turn_budget_extended";
+    /** Turn number at which the budget was exhausted. */
+    turn: number;
+    /** New effective `maxTurns` after the extension. */
+    grantedTurns: number;
+    /** 1-based extension count for this run. */
+    extension: number;
+}
 /**
  * Warning signal emitted when a turn ended on a non-clean stop reason —
  * `max_tokens` (output clipped at the model's output-token limit), `refusal`,
@@ -148,7 +185,7 @@ interface AgentFollowUpMessageEvent {
     type: "follow_up_message";
     content: Message["content"];
 }
-type AgentEvent = AgentTextDeltaEvent | AgentThinkingDeltaEvent | AgentToolCallStartEvent | AgentToolCallUpdateEvent | AgentToolCallEndEvent | AgentToolCallDeltaEvent | AgentServerToolCallEvent | AgentServerToolResultEvent | AgentSteeringMessageEvent | AgentFollowUpMessageEvent | AgentRetryEvent | AgentTurnEndEvent | AgentDoneEvent | AgentMaxTurnsEvent | AgentTruncatedEvent | AgentErrorEvent;
+type AgentEvent = AgentTextDeltaEvent | AgentThinkingDeltaEvent | AgentToolCallStartEvent | AgentToolCallUpdateEvent | AgentToolCallEndEvent | AgentToolCallDeltaEvent | AgentServerToolCallEvent | AgentServerToolResultEvent | AgentSteeringMessageEvent | AgentFollowUpMessageEvent | AgentRetryEvent | AgentTurnEndEvent | AgentCheckpointEvent | AgentDoneEvent | AgentMaxTurnsEvent | AgentTurnBudgetExtendedEvent | AgentTruncatedEvent | AgentErrorEvent;
 interface TransformContextOptions {
     /** Force a transform after the provider reports context overflow. */
     force?: boolean;
@@ -168,6 +205,12 @@ interface AgentOptions {
     /** Control whether tools may/must be called, or select a named tool when supported. */
     toolChoice?: StreamOptions["toolChoice"];
     maxTurns?: number;
+    /**
+     * How many times `onTurnBudgetExhausted` may grant extra turns in one run.
+     * Each grant raises the effective budget by the original `maxTurns`.
+     * Default: 2. Set 0 to disable extensions entirely.
+     */
+    maxTurnExtensions?: number;
     maxTokens?: number;
     temperature?: number;
     thinking?: StreamOptions["thinking"];
@@ -234,6 +277,18 @@ interface AgentOptions {
      * on read.
      */
     getFollowUpMessages?: () => Promise<Message[] | null> | Message[] | null;
+    /**
+     * Consulted when a tool-running turn exhausts the turn budget mid-task,
+     * before the loop emits the terminal `max_turns` event. Return true to grant
+     * another `maxTurns` worth of turns; false (the default when unset) keeps
+     * today's hard cut-off. Hosts should only grant on evidence of progress —
+     * extending a spinning agent just buys it more tokens to spin with.
+     */
+    onTurnBudgetExhausted?: (ctx: {
+        turn: number;
+        maxTurns: number;
+        extension: number;
+    }) => Promise<boolean> | boolean;
 }
 interface AgentResult {
     message: AssistantMessage;
@@ -324,4 +379,13 @@ declare function isBillingError(err: unknown): boolean;
 declare function isUsageLimitError(err: unknown): boolean;
 declare function agentLoop(messages: Message[], options: AgentOptions): AsyncGenerator<AgentEvent, AgentResult>;
 
-export { Agent, type AgentDoneEvent, type AgentErrorEvent, type AgentEvent, type AgentFollowUpMessageEvent, type AgentOptions, type AgentResult, type AgentRetryEvent, type AgentServerToolCallEvent, type AgentServerToolResultEvent, type AgentSteeringMessageEvent, AgentStream, type AgentTextDeltaEvent, type AgentThinkingDeltaEvent, type AgentTool, type AgentToolCallDeltaEvent, type AgentToolCallEndEvent, type AgentToolCallStartEvent, type AgentToolCallUpdateEvent, type AgentTurnEndEvent, type AgentTurnTiming, type StreamDiagnosticFn, type StructuredToolResult, type ToolContext, type ToolExecuteResult, type ToolExecutionMode, type TransformContextOptions, agentLoop, isAbortError, isBillingError, isContextOverflow, isUsageLimitError, setStreamDiagnostic };
+/**
+ * A local inference server (llama.cpp, vLLM, Ollama, LM Studio) can spend
+ * minutes prefilling a large prompt before it emits its first token. The
+ * first-event watchdog that protects hosted streams turns that into an abort
+ * → retry → cold-prefill loop that never converges, so it is disabled for
+ * loopback backends.
+ */
+declare function isLocalBackendUrl(baseUrl?: string): boolean;
+
+export { Agent, type AgentDoneEvent, type AgentErrorEvent, type AgentEvent, type AgentFollowUpMessageEvent, type AgentOptions, type AgentResult, type AgentRetryEvent, type AgentServerToolCallEvent, type AgentServerToolResultEvent, type AgentSteeringMessageEvent, AgentStream, type AgentTextDeltaEvent, type AgentThinkingDeltaEvent, type AgentTool, type AgentToolCallDeltaEvent, type AgentToolCallEndEvent, type AgentToolCallStartEvent, type AgentToolCallUpdateEvent, type AgentTurnEndEvent, type AgentTurnTiming, type StreamDiagnosticFn, type StructuredToolResult, type ToolContext, type ToolExecuteResult, type ToolExecutionMode, type TransformContextOptions, agentLoop, isAbortError, isBillingError, isContextOverflow, isLocalBackendUrl, isUsageLimitError, setStreamDiagnostic };

package/dist/index.d.ts

@@ -20,6 +20,13 @@ interface AgentTool<T extends z.ZodType = z.ZodType> extends Tool {
      * batch runs in source order so stateful mutations cannot race each other.
      */
     executionMode?: ToolExecutionMode;
+    /**
+     * Overrides the loop's default per-tool timeout. A tool that owns a longer
+     * internal budget than the default must declare it here, or the loop cancels
+     * it first and the tool's own timeout — with its specific, actionable error
+     * message — becomes unreachable.
+     */
+    timeoutMs?: number;
     execute: (args: z.infer<T>, context: ToolContext) => ToolExecuteResult | Promise<ToolExecuteResult>;
 }
 interface AgentTextDeltaEvent {
@@ -70,6 +77,21 @@ interface AgentTurnEndEvent {
     usage: Usage;
     timing: AgentTurnTiming;
 }
+/**
+ * A safe point between steps: the assistant message and every tool result for
+ * this turn are now in the message array, and no provider call is in flight.
+ *
+ * Hosts that persist a transcript flush here. Without it a crash mid-run loses
+ * the WHOLE turn — including tool results whose side effects already landed on
+ * disk — because the only flush happens after the loop returns.
+ *
+ * Yielded immediately after tool results are appended, so it pairs with
+ * `turn_end` (which covers the assistant half) to cover every message.
+ */
+interface AgentCheckpointEvent {
+    type: "checkpoint";
+    turn: number;
+}
 interface AgentDoneEvent {
     type: "agent_done";
     totalTurns: number;
@@ -87,6 +109,21 @@ interface AgentMaxTurnsEvent {
     totalTurns: number;
     maxTurns: number;
 }
+/**
+ * Emitted when the loop was about to stop on an exhausted turn budget but the
+ * host granted an extension instead. The effective budget is raised and the
+ * loop continues with a continuation prompt, so this is NOT terminal — unlike
+ * `max_turns`, which still fires if the extended budget is also spent.
+ */
+interface AgentTurnBudgetExtendedEvent {
+    type: "turn_budget_extended";
+    /** Turn number at which the budget was exhausted. */
+    turn: number;
+    /** New effective `maxTurns` after the extension. */
+    grantedTurns: number;
+    /** 1-based extension count for this run. */
+    extension: number;
+}
 /**
  * Warning signal emitted when a turn ended on a non-clean stop reason —
  * `max_tokens` (output clipped at the model's output-token limit), `refusal`,
@@ -148,7 +185,7 @@ interface AgentFollowUpMessageEvent {
     type: "follow_up_message";
     content: Message["content"];
 }
-type AgentEvent = AgentTextDeltaEvent | AgentThinkingDeltaEvent | AgentToolCallStartEvent | AgentToolCallUpdateEvent | AgentToolCallEndEvent | AgentToolCallDeltaEvent | AgentServerToolCallEvent | AgentServerToolResultEvent | AgentSteeringMessageEvent | AgentFollowUpMessageEvent | AgentRetryEvent | AgentTurnEndEvent | AgentDoneEvent | AgentMaxTurnsEvent | AgentTruncatedEvent | AgentErrorEvent;
+type AgentEvent = AgentTextDeltaEvent | AgentThinkingDeltaEvent | AgentToolCallStartEvent | AgentToolCallUpdateEvent | AgentToolCallEndEvent | AgentToolCallDeltaEvent | AgentServerToolCallEvent | AgentServerToolResultEvent | AgentSteeringMessageEvent | AgentFollowUpMessageEvent | AgentRetryEvent | AgentTurnEndEvent | AgentCheckpointEvent | AgentDoneEvent | AgentMaxTurnsEvent | AgentTurnBudgetExtendedEvent | AgentTruncatedEvent | AgentErrorEvent;
 interface TransformContextOptions {
     /** Force a transform after the provider reports context overflow. */
     force?: boolean;
@@ -168,6 +205,12 @@ interface AgentOptions {
     /** Control whether tools may/must be called, or select a named tool when supported. */
     toolChoice?: StreamOptions["toolChoice"];
     maxTurns?: number;
+    /**
+     * How many times `onTurnBudgetExhausted` may grant extra turns in one run.
+     * Each grant raises the effective budget by the original `maxTurns`.
+     * Default: 2. Set 0 to disable extensions entirely.
+     */
+    maxTurnExtensions?: number;
     maxTokens?: number;
     temperature?: number;
     thinking?: StreamOptions["thinking"];
@@ -234,6 +277,18 @@ interface AgentOptions {
      * on read.
      */
     getFollowUpMessages?: () => Promise<Message[] | null> | Message[] | null;
+    /**
+     * Consulted when a tool-running turn exhausts the turn budget mid-task,
+     * before the loop emits the terminal `max_turns` event. Return true to grant
+     * another `maxTurns` worth of turns; false (the default when unset) keeps
+     * today's hard cut-off. Hosts should only grant on evidence of progress —
+     * extending a spinning agent just buys it more tokens to spin with.
+     */
+    onTurnBudgetExhausted?: (ctx: {
+        turn: number;
+        maxTurns: number;
+        extension: number;
+    }) => Promise<boolean> | boolean;
 }
 interface AgentResult {
     message: AssistantMessage;
@@ -324,4 +379,13 @@ declare function isBillingError(err: unknown): boolean;
 declare function isUsageLimitError(err: unknown): boolean;
 declare function agentLoop(messages: Message[], options: AgentOptions): AsyncGenerator<AgentEvent, AgentResult>;
 
-export { Agent, type AgentDoneEvent, type AgentErrorEvent, type AgentEvent, type AgentFollowUpMessageEvent, type AgentOptions, type AgentResult, type AgentRetryEvent, type AgentServerToolCallEvent, type AgentServerToolResultEvent, type AgentSteeringMessageEvent, AgentStream, type AgentTextDeltaEvent, type AgentThinkingDeltaEvent, type AgentTool, type AgentToolCallDeltaEvent, type AgentToolCallEndEvent, type AgentToolCallStartEvent, type AgentToolCallUpdateEvent, type AgentTurnEndEvent, type AgentTurnTiming, type StreamDiagnosticFn, type StructuredToolResult, type ToolContext, type ToolExecuteResult, type ToolExecutionMode, type TransformContextOptions, agentLoop, isAbortError, isBillingError, isContextOverflow, isUsageLimitError, setStreamDiagnostic };
+/**
+ * A local inference server (llama.cpp, vLLM, Ollama, LM Studio) can spend
+ * minutes prefilling a large prompt before it emits its first token. The
+ * first-event watchdog that protects hosted streams turns that into an abort
+ * → retry → cold-prefill loop that never converges, so it is disabled for
+ * loopback backends.
+ */
+declare function isLocalBackendUrl(baseUrl?: string): boolean;
+
+export { Agent, type AgentDoneEvent, type AgentErrorEvent, type AgentEvent, type AgentFollowUpMessageEvent, type AgentOptions, type AgentResult, type AgentRetryEvent, type AgentServerToolCallEvent, type AgentServerToolResultEvent, type AgentSteeringMessageEvent, AgentStream, type AgentTextDeltaEvent, type AgentThinkingDeltaEvent, type AgentTool, type AgentToolCallDeltaEvent, type AgentToolCallEndEvent, type AgentToolCallStartEvent, type AgentToolCallUpdateEvent, type AgentTurnEndEvent, type AgentTurnTiming, type StreamDiagnosticFn, type StructuredToolResult, type ToolContext, type ToolExecuteResult, type ToolExecutionMode, type TransformContextOptions, agentLoop, isAbortError, isBillingError, isContextOverflow, isLocalBackendUrl, isUsageLimitError, setStreamDiagnostic };

package/dist/index.js

@@ -8,9 +8,36 @@ import {
   EventStream,
   EZCoderAIError,
   isHardBillingMessage,
-  redactValue
+  redactValue,
+  sliceHead,
+  sliceTail
 } from "@prestyj/ai";
+
+// src/local-backend.ts
+function isLocalBackendUrl(baseUrl) {
+  if (!baseUrl) return false;
+  let host;
+  try {
+    host = new URL(baseUrl).hostname.toLowerCase();
+  } catch {
+    return false;
+  }
+  if (host === "[::1]" || host === "::1") return true;
+  if (host === "localhost" || host.endsWith(".localhost")) return true;
+  if (host === "0.0.0.0") return true;
+  if (host.endsWith(".local")) return true;
+  const ipv4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+  if (ipv4) {
+    const octets = ipv4.slice(1).map(Number);
+    if (octets.some((n) => n > 255)) return false;
+    return octets[0] === 127;
+  }
+  return false;
+}
+
+// src/agent-loop.ts
 var DEFAULT_MAX_TURNS = 300;
+var DEFAULT_TOOL_TIMEOUT_MS = 3e5;
 var _diagFn = null;
 function setStreamDiagnostic(fn) {
   _diagFn = fn;
@@ -213,6 +240,9 @@ function abortablePromise(promise, signal) {
     promise.then(resolveOnce, rejectOnce);
   });
 }
+function turnBudgetContinuationPrompt() {
+  return "[You reached the turn limit for this segment but the work is not finished, so you have been granted more turns. Before continuing, state in one or two sentences what is already done and what remains, then keep going from there \u2014 do not restart work that is already complete.]";
+}
 function abortableSleep(ms, signal) {
   if (signal?.aborted) return Promise.reject(createAbortError());
   return new Promise((resolve, reject) => {
@@ -234,6 +264,9 @@ function closeIterator(iterator) {
 }
 async function* agentLoop(messages, options) {
   const maxTurns = options.maxTurns ?? DEFAULT_MAX_TURNS;
+  let effectiveMaxTurns = maxTurns;
+  const maxTurnExtensions = Math.max(0, options.maxTurnExtensions ?? 2);
+  let turnExtensions = 0;
   const maxContinuations = options.maxContinuations ?? 5;
   let toolMap = new Map((options.tools ?? []).map((t) => [t.name, t]));
   const totalUsage = { inputTokens: 0, outputTokens: 0 };
@@ -276,16 +309,17 @@ async function* agentLoop(messages, options) {
   const STREAM_THINKING_IDLE_TIMEOUT_MS = 3e5;
   const STREAM_THINKING_HARD_TIMEOUT_MS = 6e5;
   const NON_STREAMING_HARD_TIMEOUT_MS = 3e5;
-  const isSakana = options.provider === "sakana";
-  const firstEventTimeoutMs = isSakana ? STREAM_THINKING_IDLE_TIMEOUT_MS : STREAM_FIRST_EVENT_TIMEOUT_MS;
-  const initialHardTimeoutMs = isSakana ? STREAM_THINKING_HARD_TIMEOUT_MS : STREAM_HARD_TIMEOUT_MS;
+  const usesSilentReasoningBudget = options.provider === "sakana" || options.provider === "openai" && options.thinking != null;
+  const localBackend = isLocalBackendUrl(options.baseUrl);
+  const firstEventTimeoutMs = localBackend ? Number.POSITIVE_INFINITY : usesSilentReasoningBudget ? STREAM_THINKING_IDLE_TIMEOUT_MS : STREAM_FIRST_EVENT_TIMEOUT_MS;
+  const initialHardTimeoutMs = localBackend || usesSilentReasoningBudget ? STREAM_THINKING_HARD_TIMEOUT_MS : STREAM_HARD_TIMEOUT_MS;
   const MAX_TOOLCALL_DELTA_CHARS = 1e6;
-  const MAX_TOOLCALL_DELTA_EVENTS = 2e4;
+  const MAX_TOOLCALL_NO_PROGRESS_EVENTS = 2e4;
   let logicalTurnStartedAt = 0;
   let firstProviderEventAt;
   let providerDurationMs = 0;
   try {
-    while (turn < maxTurns) {
+    while (turn < effectiveMaxTurns) {
       options.signal?.throwIfAborted();
       turn++;
       if (logicalTurnStartedAt === 0) logicalTurnStartedAt = Date.now();
@@ -306,7 +340,11 @@ async function* agentLoop(messages, options) {
           messages: messages.length,
           chars: msgChars,
           provider: options.provider,
-          model: options.model
+          model: options.model,
+          thinking: options.thinking ?? "off",
+          firstEventTimeoutMs,
+          initialHardTimeoutMs,
+          localBackend
         });
       }
       if (firstTurn && options.getSteeringMessages) {
@@ -352,6 +390,7 @@ async function* agentLoop(messages, options) {
       let lastEventType = "";
       let toolcallDeltaChars = 0;
       let toolcallDeltaCount = 0;
+      let toolcallNoProgressCount = 0;
       let runawayDetected = null;
       let attemptText = "";
       let lastYieldEndTime = Date.now();
@@ -364,6 +403,7 @@ async function* agentLoop(messages, options) {
         if (useNonStreamingFallback) return;
         if (idleTimer) clearTimeout(idleTimer);
         const timeoutMs = hasReceivedEvent ? STREAM_IDLE_TIMEOUT_MS : hasReceivedThinking ? STREAM_THINKING_IDLE_TIMEOUT_MS : firstEventTimeoutMs;
+        if (!Number.isFinite(timeoutMs)) return;
         idleTimer = setTimeout(() => {
           diag("idle_timeout_fired", {
             events: streamEventCount,
@@ -505,11 +545,13 @@ async function* agentLoop(messages, options) {
             const chunkChars = event.argsJson?.length ?? 0;
             toolcallDeltaChars += chunkChars;
             toolcallDeltaCount++;
-            if (!runawayDetected && (toolcallDeltaChars > MAX_TOOLCALL_DELTA_CHARS || toolcallDeltaCount > MAX_TOOLCALL_DELTA_EVENTS)) {
+            toolcallNoProgressCount = chunkChars > 0 ? 0 : toolcallNoProgressCount + 1;
+            if (!runawayDetected && (toolcallDeltaChars > MAX_TOOLCALL_DELTA_CHARS || toolcallNoProgressCount > MAX_TOOLCALL_NO_PROGRESS_EVENTS)) {
               runawayDetected = {
                 kind: toolcallDeltaChars > MAX_TOOLCALL_DELTA_CHARS ? "chars" : "events",
                 chars: toolcallDeltaChars,
-                events: toolcallDeltaCount
+                events: toolcallDeltaCount,
+                noProgressEvents: toolcallNoProgressCount
               };
               diag("runaway_toolcall_detected", {
                 ...runawayDetected,
@@ -691,11 +733,15 @@ async function* agentLoop(messages, options) {
             turn--;
             continue;
           }
-          const detail = runawayDetected.kind === "chars" ? `${(runawayDetected.chars / 1024).toFixed(0)} KB of tool-call arguments` : `${runawayDetected.events} tool-call delta events`;
+          const detail = runawayDetected.kind === "chars" ? `${(runawayDetected.chars / 1024).toFixed(0)} KB of tool-call arguments` : `${runawayDetected.noProgressEvents} consecutive tool-call delta events without argument progress`;
           yield {
             type: "error",
-            error: new Error(
-              `The model repeatedly failed to close a tool call after ${MAX_RUNAWAY_TOOLCALL_RETRIES} automatic retries (${detail}). Switch models and retry; your conversation is preserved.`
+            error: new EZCoderAIError(
+              `The model repeatedly failed to close a tool call after ${MAX_RUNAWAY_TOOLCALL_RETRIES} automatic retries (${detail}). Your conversation is preserved.`,
+              {
+                source: "provider",
+                hint: "Retry once. If it keeps happening, switch models and continue the preserved conversation."
+              }
             )
           };
           break;
@@ -722,7 +768,15 @@ async function* agentLoop(messages, options) {
               role: "assistant",
               content: [{ type: "text", text: attemptText }]
             });
-            messages.push({ role: "user", content: PARTIAL_CONTINUATION_PROMPT });
+            messages.push({
+              role: "user",
+              content: PARTIAL_CONTINUATION_PROMPT,
+              provenance: {
+                source: "runtime",
+                kind: "continuation",
+                visibility: "hidden"
+              }
+            });
             preservedChars = attemptText.length;
           }
           diag("retry", {
@@ -748,15 +802,29 @@ async function* agentLoop(messages, options) {
           continue;
         }
         if (transportFailure) {
+          const cause = malformed ? "malformed_stream" : socketDrop ? "socket_drop" : "stream_stall";
           diag("stall_exhausted", {
             stallRetries: MAX_STALL_RETRIES,
             provider: options.provider,
-            model: options.model
+            model: options.model,
+            cause,
+            nonStreaming: useNonStreamingFallback,
+            events: streamEventCount,
+            eventTypes: eventTypeCounts,
+            lastEventType,
+            sinceLastEventMs: Date.now() - lastEventTime,
+            attemptDurationMs: Date.now() - streamCallStart,
+            maxConsumerLagMs
           });
           yield {
             type: "error",
-            error: new Error(
-              `The API provider's stream stalled ${MAX_STALL_RETRIES} times \u2014 the provider may be experiencing capacity issues. Your conversation is preserved. Send another message to retry.`
+            error: new EZCoderAIError(
+              `The connection to the API provider stopped responding after ${MAX_STALL_RETRIES} automatic retries. Your conversation is preserved.`,
+              {
+                source: "network",
+                hint: "Retry once. If it keeps happening on this device, disable any VPN or proxy and allow EZ Coder through firewall or antivirus web protection.",
+                cause: err
+              }
             )
           };
           break;
@@ -827,6 +895,9 @@ async function* agentLoop(messages, options) {
       useNonStreamingFallback = false;
       totalUsage.inputTokens += response.usage.inputTokens;
       totalUsage.outputTokens += response.usage.outputTokens;
+      if (response.usage.reasoningTokens) {
+        totalUsage.reasoningTokens = (totalUsage.reasoningTokens ?? 0) + response.usage.reasoningTokens;
+      }
       if (response.usage.cacheRead) {
         totalUsage.cacheRead = (totalUsage.cacheRead ?? 0) + response.usage.cacheRead;
       }
@@ -878,7 +949,15 @@ async function* agentLoop(messages, options) {
               model: options.model
             });
             yield { type: "truncated", reason: "max_tokens", continued: true };
-            messages.push({ role: "user", content: MAX_TOKENS_CONTINUATION_PROMPT });
+            messages.push({
+              role: "user",
+              content: MAX_TOKENS_CONTINUATION_PROMPT,
+              provenance: {
+                source: "runtime",
+                kind: "continuation",
+                visibility: "hidden"
+              }
+            });
             continue;
           }
           yield { type: "truncated", reason: "max_tokens", continued: false };
@@ -954,6 +1033,7 @@ async function* agentLoop(messages, options) {
       );
       const executionResult = hasSequentialToolCall ? yield* executeToolCallsMixed(toolCalls, toolResults, executionOptions) : yield* executeToolCallsParallel(toolCalls, toolResults, executionOptions);
       messages.push({ role: "tool", content: executionResult.toolResults });
+      yield { type: "checkpoint", turn };
       const toolsAborted = executionResult.aborted;
       if (fatalToolArgumentError) {
         if (fatalToolArgumentRecoverable && !toolArgumentAutoContinueUsed) {
@@ -985,8 +1065,51 @@ async function* agentLoop(messages, options) {
           }
         }
       }
-      if (turn >= maxTurns) {
-        hitMaxTurns = true;
+      if (turn >= effectiveMaxTurns) {
+        let extended = false;
+        if (options.onTurnBudgetExhausted && turnExtensions < maxTurnExtensions) {
+          const extension = turnExtensions + 1;
+          let granted = false;
+          try {
+            granted = await options.onTurnBudgetExhausted({
+              turn,
+              maxTurns: effectiveMaxTurns,
+              extension
+            });
+          } catch {
+            granted = false;
+          }
+          if (granted) {
+            turnExtensions = extension;
+            effectiveMaxTurns += maxTurns;
+            extended = true;
+            diag("turn_budget_extended", {
+              turn,
+              grantedTurns: effectiveMaxTurns,
+              extension,
+              provider: options.provider,
+              model: options.model
+            });
+            yield {
+              type: "turn_budget_extended",
+              turn,
+              grantedTurns: effectiveMaxTurns,
+              extension
+            };
+            messages.push({
+              role: "user",
+              content: turnBudgetContinuationPrompt(),
+              provenance: {
+                source: "runtime",
+                kind: "continuation",
+                visibility: "hidden"
+              }
+            });
+          }
+        }
+        if (!extended) {
+          hitMaxTurns = true;
+        }
       }
     }
   } finally {
@@ -1002,14 +1125,15 @@ async function* agentLoop(messages, options) {
   if (hitMaxTurns) {
     diag("max_turns_reached", {
       turn,
-      maxTurns,
+      maxTurns: effectiveMaxTurns,
+      extensions: turnExtensions,
       provider: options.provider,
       model: options.model
     });
     yield {
       type: "max_turns",
       totalTurns: turn,
-      maxTurns
+      maxTurns: effectiveMaxTurns
     };
   }
   yield {
@@ -1045,7 +1169,7 @@ async function executeSingleToolCall(toolCall, options, pushEvent) {
     try {
       const parsed = tool.parameters.parse(toolCall.args);
       const callerSignal = options.signal;
-      const toolTimeout = AbortSignal.timeout(3e5);
+      const toolTimeout = AbortSignal.timeout(tool.timeoutMs ?? DEFAULT_TOOL_TIMEOUT_MS);
       const ctx = {
         signal: callerSignal ? AbortSignal.any([callerSignal, toolTimeout]) : toolTimeout,
         toolCallId: toolCall.id,
@@ -1258,9 +1382,9 @@ function capToolResults(toolResults, maxToolResultChars) {
     const originalChars = toolResult.content.length;
     const headChars = Math.floor(max * 0.7);
     const tailChars = max - headChars;
-    const head = toolResult.content.slice(0, headChars);
-    const tail = toolResult.content.slice(-tailChars);
-    const omitted = originalChars - headChars - tailChars;
+    const head = sliceHead(toolResult.content, headChars);
+    const tail = sliceTail(toolResult.content, tailChars);
+    const omitted = originalChars - head.length - tail.length;
     toolResult.content = head + `
 
 [... ${omitted} characters omitted ...]
@@ -1295,11 +1419,11 @@ function capTurnToolResults(toolResults, maxTurnToolResultChars) {
     const headChars = Math.floor(fairShare * 0.7);
     const tailChars = fairShare - headChars;
     const omitted = originalChars - fairShare;
-    toolResult.content = toolResult.content.slice(0, headChars) + `
+    toolResult.content = sliceHead(toolResult.content, headChars) + `
 
 [... ${omitted} characters trimmed: this turn's combined tool results exceeded the per-turn budget. Re-run this call alone with narrower filters or offset/limit if you need the omitted content ...]
 
-` + (tailChars > 0 ? toolResult.content.slice(-tailChars) : "");
+` + sliceTail(toolResult.content, tailChars);
     toolResult.capped = {
       originalChars: toolResult.capped?.originalChars ?? originalChars,
       keptChars: toolResult.content.length,
@@ -1318,12 +1442,14 @@ function truncateToolResultText(text, maxChars) {
   if (text.length <= maxChars) return text;
   const tailChars = Math.min(Math.floor(maxChars * 0.3), 2e4);
   const headChars = Math.max(maxChars - tailChars, 0);
-  const omitted = text.length - headChars - tailChars;
-  return `${text.slice(0, headChars)}
+  const head = sliceHead(text, headChars);
+  const tail = sliceTail(text, tailChars);
+  const omitted = text.length - head.length - tail.length;
+  return `${head}
 
 [... ${omitted} characters omitted after context overflow ...]
 
-${text.slice(-tailChars)}`;
+${tail}`;
 }
 function truncateOversizedToolResults(messages, maxChars) {
   if (maxChars <= 0) return false;
@@ -1575,6 +1701,7 @@ export {
   isAbortError,
   isBillingError,
   isContextOverflow,
+  isLocalBackendUrl,
   isUsageLimitError,
   setStreamDiagnostic
 };