@prestyj/agent 5.8.0 → 5.10.0

package/dist/index.d.cts

@@ -87,9 +87,22 @@ interface AgentMaxTurnsEvent {
     totalTurns: number;
     maxTurns: 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`,
+ * or a provider-reported `error` stop. Distinguishes a truncated/degraded
+ * completion from a clean one so hosts can warn the user instead of silently
+ * presenting incomplete output as done.
+ */
+interface AgentTruncatedEvent {
+    type: "truncated";
+    reason: "max_tokens" | "refusal" | "provider_error";
+    /** True when the loop injected a continuation and will keep going. */
+    continued: boolean;
+}
 interface AgentRetryEvent {
     type: "retry";
-    reason: "overloaded" | "rate_limit" | "provider_error" | "empty_response" | "stream_stall" | "overflow_compact" | "tool_argument_glitch";
+    reason: "overloaded" | "rate_limit" | "provider_error" | "empty_response" | "stream_stall" | "overflow_compact" | "tool_argument_glitch" | "runaway_toolcall";
     attempt: number;
     maxAttempts: number;
     delayMs: number;
@@ -135,7 +148,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 | AgentErrorEvent;
+type AgentEvent = AgentTextDeltaEvent | AgentThinkingDeltaEvent | AgentToolCallStartEvent | AgentToolCallUpdateEvent | AgentToolCallEndEvent | AgentToolCallDeltaEvent | AgentServerToolCallEvent | AgentServerToolResultEvent | AgentSteeringMessageEvent | AgentFollowUpMessageEvent | AgentRetryEvent | AgentTurnEndEvent | AgentDoneEvent | AgentMaxTurnsEvent | AgentTruncatedEvent | AgentErrorEvent;
 interface TransformContextOptions {
     /** Force a transform after the provider reports context overflow. */
     force?: boolean;
@@ -311,4 +324,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

@@ -87,9 +87,22 @@ interface AgentMaxTurnsEvent {
     totalTurns: number;
     maxTurns: 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`,
+ * or a provider-reported `error` stop. Distinguishes a truncated/degraded
+ * completion from a clean one so hosts can warn the user instead of silently
+ * presenting incomplete output as done.
+ */
+interface AgentTruncatedEvent {
+    type: "truncated";
+    reason: "max_tokens" | "refusal" | "provider_error";
+    /** True when the loop injected a continuation and will keep going. */
+    continued: boolean;
+}
 interface AgentRetryEvent {
     type: "retry";
-    reason: "overloaded" | "rate_limit" | "provider_error" | "empty_response" | "stream_stall" | "overflow_compact" | "tool_argument_glitch";
+    reason: "overloaded" | "rate_limit" | "provider_error" | "empty_response" | "stream_stall" | "overflow_compact" | "tool_argument_glitch" | "runaway_toolcall";
     attempt: number;
     maxAttempts: number;
     delayMs: number;
@@ -135,7 +148,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 | AgentErrorEvent;
+type AgentEvent = AgentTextDeltaEvent | AgentThinkingDeltaEvent | AgentToolCallStartEvent | AgentToolCallUpdateEvent | AgentToolCallEndEvent | AgentToolCallDeltaEvent | AgentServerToolCallEvent | AgentServerToolResultEvent | AgentSteeringMessageEvent | AgentFollowUpMessageEvent | AgentRetryEvent | AgentTurnEndEvent | AgentDoneEvent | AgentMaxTurnsEvent | AgentTruncatedEvent | AgentErrorEvent;
 interface TransformContextOptions {
     /** Force a transform after the provider reports context overflow. */
     force?: boolean;
@@ -311,4 +324,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

@@ -10,6 +10,30 @@ import {
   isHardBillingMessage,
   redactValue
 } 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 _diagFn = null;
 function setStreamDiagnostic(fn) {
@@ -188,7 +212,11 @@ function createAbortError() {
 }
 function abortablePromise(promise, signal) {
   if (!signal) return promise;
-  if (signal.aborted) return Promise.reject(createAbortError());
+  if (signal.aborted) {
+    promise.catch(() => {
+    });
+    return Promise.reject(createAbortError());
+  }
   return new Promise((resolve, reject) => {
     let settled = false;
     const cleanup = () => signal.removeEventListener("abort", onAbort);
@@ -244,6 +272,7 @@ async function* agentLoop(messages, options) {
   let overloadRetries = 0;
   let emptyResponseRetries = 0;
   let stallRetries = 0;
+  let runawayToolcallRetries = 0;
   let overflowCompactionAttempts = 0;
   let toolResultTruncationAttempted = false;
   const invalidToolArgumentCounts = /* @__PURE__ */ new Map();
@@ -252,11 +281,16 @@ async function* agentLoop(messages, options) {
   const MAX_OVERLOAD_RETRIES = 10;
   const MAX_EMPTY_RESPONSE_RETRIES = 2;
   const MAX_STALL_RETRIES = 10;
+  const MAX_RUNAWAY_TOOLCALL_RETRIES = 2;
+  const RUNAWAY_TOOLCALL_RETRY_DELAY_MS = 1e3;
   const MAX_OVERFLOW_COMPACTIONS = 2;
   const STALL_RETRIES_BEFORE_NON_STREAMING = 2;
   const STALL_DELAY_MS = 1e3;
   const MIN_PARTIAL_PRESERVE_CHARS = 200;
   const PARTIAL_CONTINUATION_PROMPT = "[Your previous response was cut off by a connection failure. The text above is what was already delivered to the user. Continue exactly from where it stopped \u2014 do not repeat or restart it.]";
+  const MAX_OUTPUT_CONTINUATIONS = 2;
+  const MAX_TOKENS_CONTINUATION_PROMPT = "[Your previous response hit the output-token limit and was cut off. The text above is what was already delivered to the user. Continue exactly from where it stopped \u2014 do not repeat or restart it.]";
+  let maxTokensContinuations = 0;
   const OVERLOAD_BASE_DELAY_MS = 2e3;
   const OVERLOAD_MAX_DELAY_MS = 3e4;
   const STREAM_FIRST_EVENT_TIMEOUT_MS = 45e3;
@@ -266,9 +300,10 @@ 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;
   let logicalTurnStartedAt = 0;
@@ -296,7 +331,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) {
@@ -354,6 +393,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,
@@ -659,11 +699,33 @@ async function* agentLoop(messages, options) {
             provider: options.provider,
             model: options.model
           });
+          if (runawayToolcallRetries < MAX_RUNAWAY_TOOLCALL_RETRIES) {
+            runawayToolcallRetries++;
+            const delayMs = RUNAWAY_TOOLCALL_RETRY_DELAY_MS * runawayToolcallRetries;
+            diag("retry", {
+              reason: "runaway_toolcall",
+              attempt: runawayToolcallRetries,
+              maxAttempts: MAX_RUNAWAY_TOOLCALL_RETRIES,
+              delayMs,
+              ...runawayDetected
+            });
+            yield {
+              type: "retry",
+              reason: "runaway_toolcall",
+              attempt: runawayToolcallRetries,
+              maxAttempts: MAX_RUNAWAY_TOOLCALL_RETRIES,
+              delayMs,
+              silent: true
+            };
+            await abortableSleep(delayMs, options.signal);
+            turn--;
+            continue;
+          }
           const detail = runawayDetected.kind === "chars" ? `${(runawayDetected.chars / 1024).toFixed(0)} KB of tool-call arguments` : `${runawayDetected.events} tool-call delta events`;
           yield {
             type: "error",
             error: new Error(
-              `The model glitched mid-tool-call and produced ${detail} without closing the call. This is usually an upstream model bug \u2014 try the same request again or switch models. Your conversation is preserved.`
+              `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.`
             )
           };
           break;
@@ -716,15 +778,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;
@@ -764,6 +840,7 @@ async function* agentLoop(messages, options) {
       }
       overloadRetries = 0;
       stallRetries = 0;
+      runawayToolcallRetries = 0;
       const contentArr = Array.isArray(response.message.content) ? response.message.content : null;
       const hasActionableContent = response.message.content !== "" && contentArr !== null && contentArr.some(
         (p) => p.type === "text" || p.type === "tool_call" || p.type === "server_tool_call"
@@ -835,6 +912,27 @@ async function* agentLoop(messages, options) {
       consecutivePauses = 0;
       const allToolCalls = extractToolCalls(response.message.content);
       if (response.stopReason !== "tool_use" && allToolCalls.length === 0) {
+        if (response.stopReason === "max_tokens") {
+          if (maxTokensContinuations < MAX_OUTPUT_CONTINUATIONS) {
+            maxTokensContinuations++;
+            diag("max_tokens_continuation", {
+              attempt: maxTokensContinuations,
+              maxAttempts: MAX_OUTPUT_CONTINUATIONS,
+              provider: options.provider,
+              model: options.model
+            });
+            yield { type: "truncated", reason: "max_tokens", continued: true };
+            messages.push({ role: "user", content: MAX_TOKENS_CONTINUATION_PROMPT });
+            continue;
+          }
+          yield { type: "truncated", reason: "max_tokens", continued: false };
+        } else if (response.stopReason === "refusal" || response.stopReason === "error") {
+          yield {
+            type: "truncated",
+            reason: response.stopReason === "refusal" ? "refusal" : "provider_error",
+            continued: false
+          };
+        }
         if (options.getSteeringMessages) {
           const steering = await options.getSteeringMessages();
           if (steering && steering.length > 0) {
@@ -1201,16 +1299,22 @@ function capToolResults(toolResults, maxToolResultChars) {
   const max = Math.min(maxToolResultChars, hardMax);
   for (const toolResult of toolResults) {
     if (typeof toolResult.content !== "string" || toolResult.content.length <= max) continue;
+    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 = toolResult.content.length - headChars - tailChars;
+    const omitted = originalChars - headChars - tailChars;
     toolResult.content = head + `
 
 [... ${omitted} characters omitted ...]
 
 ` + tail;
+    toolResult.capped = {
+      originalChars,
+      keptChars: toolResult.content.length,
+      scope: "per-result"
+    };
   }
 }
 function capTurnToolResults(toolResults, maxTurnToolResultChars) {
@@ -1231,14 +1335,20 @@ function capTurnToolResults(toolResults, maxTurnToolResultChars) {
       continue;
     }
     remaining -= fairShare;
+    const originalChars = toolResult.content.length;
     const headChars = Math.floor(fairShare * 0.7);
     const tailChars = fairShare - headChars;
-    const omitted = toolResult.content.length - fairShare;
+    const omitted = originalChars - fairShare;
     toolResult.content = toolResult.content.slice(0, 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) : "");
+    toolResult.capped = {
+      originalChars: toolResult.capped?.originalChars ?? originalChars,
+      keptChars: toolResult.content.length,
+      scope: "per-turn"
+    };
   }
 }
 function normalizeToolResult(raw) {
@@ -1509,6 +1619,7 @@ export {
   isAbortError,
   isBillingError,
   isContextOverflow,
+  isLocalBackendUrl,
   isUsageLimitError,
   setStreamDiagnostic
 };