@prestyj/agent 5.12.0 → 5.16.0

package/dist/index.d.cts

@@ -55,6 +55,13 @@ interface AgentToolCallEndEvent {
     details?: unknown;
     isError: boolean;
     durationMs: number;
+    /**
+     * Set only when the call failed schema validation: how many consecutive
+     * times this tool produced this same validation error. 1 means the model
+     * still has room to self-correct; 3 is the threshold that ends the turn.
+     * Logged so a retry loop shows up as a count instead of identical lines.
+     */
+    invalidArgAttempt?: number;
 }
 interface AgentTurnTiming {
     /** Logical turn start, before context transforms or provider retries. Unix epoch milliseconds. */
@@ -133,7 +140,7 @@ interface AgentTurnBudgetExtendedEvent {
  */
 interface AgentTruncatedEvent {
     type: "truncated";
-    reason: "max_tokens" | "refusal" | "provider_error";
+    reason: "max_tokens" | "refusal" | "provider_error" | "empty_response";
     /** True when the loop injected a continuation and will keep going. */
     continued: boolean;
 }
@@ -394,6 +401,20 @@ declare function isBillingError(err: unknown): boolean;
  */
 declare function isUsageLimitError(err: unknown): boolean;
 declare function agentLoop(messages: Message[], options: AgentOptions): AsyncGenerator<AgentEvent, AgentResult>;
+/**
+ * A tool call that never reached its tool. Nothing ran, so nothing changed.
+ */
+declare function cancelledBeforeStartText(name: string): string;
+/**
+ * A tool call that started running and was cut off before reporting back.
+ *
+ * The distinction from {@link cancelledBeforeStartText} is the whole point: a
+ * dispatched `git push`, deploy or MCP call may well have COMPLETED before the
+ * abort landed. Telling the model it was "interrupted" reads as "it did not
+ * happen", so the model repeats the side effect — or reports to the user that
+ * something never ran when it did.
+ */
+declare function indeterminateOutcomeText(name: string): string;
 
 /**
  * A local inference server (llama.cpp, vLLM, Ollama, LM Studio) can spend
@@ -404,4 +425,4 @@ declare function agentLoop(messages: Message[], options: AgentOptions): AsyncGen
  */
 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 };
+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, cancelledBeforeStartText, indeterminateOutcomeText, isAbortError, isBillingError, isContextOverflow, isLocalBackendUrl, isUsageLimitError, setStreamDiagnostic };

package/dist/index.d.ts

@@ -55,6 +55,13 @@ interface AgentToolCallEndEvent {
     details?: unknown;
     isError: boolean;
     durationMs: number;
+    /**
+     * Set only when the call failed schema validation: how many consecutive
+     * times this tool produced this same validation error. 1 means the model
+     * still has room to self-correct; 3 is the threshold that ends the turn.
+     * Logged so a retry loop shows up as a count instead of identical lines.
+     */
+    invalidArgAttempt?: number;
 }
 interface AgentTurnTiming {
     /** Logical turn start, before context transforms or provider retries. Unix epoch milliseconds. */
@@ -133,7 +140,7 @@ interface AgentTurnBudgetExtendedEvent {
  */
 interface AgentTruncatedEvent {
     type: "truncated";
-    reason: "max_tokens" | "refusal" | "provider_error";
+    reason: "max_tokens" | "refusal" | "provider_error" | "empty_response";
     /** True when the loop injected a continuation and will keep going. */
     continued: boolean;
 }
@@ -394,6 +401,20 @@ declare function isBillingError(err: unknown): boolean;
  */
 declare function isUsageLimitError(err: unknown): boolean;
 declare function agentLoop(messages: Message[], options: AgentOptions): AsyncGenerator<AgentEvent, AgentResult>;
+/**
+ * A tool call that never reached its tool. Nothing ran, so nothing changed.
+ */
+declare function cancelledBeforeStartText(name: string): string;
+/**
+ * A tool call that started running and was cut off before reporting back.
+ *
+ * The distinction from {@link cancelledBeforeStartText} is the whole point: a
+ * dispatched `git push`, deploy or MCP call may well have COMPLETED before the
+ * abort landed. Telling the model it was "interrupted" reads as "it did not
+ * happen", so the model repeats the side effect — or reports to the user that
+ * something never ran when it did.
+ */
+declare function indeterminateOutcomeText(name: string): string;
 
 /**
  * A local inference server (llama.cpp, vLLM, Ollama, LM Studio) can spend
@@ -404,4 +425,4 @@ declare function agentLoop(messages: Message[], options: AgentOptions): AsyncGen
  */
 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 };
+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, cancelledBeforeStartText, indeterminateOutcomeText, isAbortError, isBillingError, isContextOverflow, isLocalBackendUrl, isUsageLimitError, setStreamDiagnostic };

package/dist/index.js

@@ -35,6 +35,60 @@ function isLocalBackendUrl(baseUrl) {
   return false;
 }
 
+// src/output-ceiling.ts
+var TTL_MS = 24 * 60 * 60 * 1e3;
+var MIN_PLAUSIBLE_CEILING = 256;
+var MAX_PLAUSIBLE_CEILING = 1e7;
+var ceilings = /* @__PURE__ */ new Map();
+function outputRouteKey(route) {
+  return `${route.provider}\0${route.baseUrl ?? "default"}\0${route.model}`;
+}
+function parseOutputTokenCeiling(err) {
+  if (!(err instanceof Error)) return null;
+  const msg = err.message;
+  if (!/max_tokens|max output tokens|output tokens|completion tokens/i.test(msg)) return null;
+  if (err.statusCode === 402) return null;
+  if (/credit|billing|payment|insufficient|balance|quota/i.test(msg)) return null;
+  const patterns = [
+    // Anthropic: "max_tokens: 100000 > 64000, which is the maximum allowed…"
+    /max_tokens:\s*\d+\s*>\s*(\d+)/i,
+    // OpenAI: "…this model supports at most 16384 completion tokens"
+    /(?:at most|maximum of|limit of)\s+([\d,_]+)\s*(?:output|completion)?\s*tokens/i,
+    // Generic: "max output tokens is 8192" / "max_tokens must be <= 4096"
+    /(?:max_tokens|max output tokens)\b[^\d]{0,30}?([\d,_]+)/i
+  ];
+  for (const pattern of patterns) {
+    const raw = msg.match(pattern)?.[1];
+    if (raw === void 0) continue;
+    const limit = Number(raw.replace(/[,_]/g, ""));
+    if (Number.isFinite(limit) && limit >= MIN_PLAUSIBLE_CEILING && limit <= MAX_PLAUSIBLE_CEILING) {
+      return limit;
+    }
+  }
+  return null;
+}
+function rememberOutputCeiling(key, limit) {
+  const known = outputTokenCeiling(key);
+  ceilings.set(key, {
+    limit: known === void 0 ? limit : Math.min(known, limit),
+    expiresAt: Date.now() + TTL_MS
+  });
+}
+function outputTokenCeiling(key) {
+  const entry = ceilings.get(key);
+  if (!entry) return void 0;
+  if (entry.expiresAt <= Date.now()) {
+    ceilings.delete(key);
+    return void 0;
+  }
+  return entry.limit;
+}
+function clampOutputTokens(key, requested) {
+  const ceiling = outputTokenCeiling(key);
+  if (ceiling === void 0) return requested;
+  return requested === void 0 ? ceiling : Math.min(requested, ceiling);
+}
+
 // src/agent-loop.ts
 var DEFAULT_MAX_TURNS = 300;
 var DEFAULT_TOOL_TIMEOUT_MS = 3e5;
@@ -319,6 +373,16 @@ async function* agentLoop(messages, options) {
   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;
+  let providerCalls = 0;
+  let nonStreamingCalls = 0;
+  let warnedNonStreaming = false;
+  const MAX_OUTPUT_CEILING_RETRIES = 1;
+  let outputCeilingRetries = 0;
+  const ceilingKey = outputRouteKey({
+    provider: options.provider,
+    model: options.model,
+    baseUrl: options.baseUrl
+  });
   const OVERLOAD_BASE_DELAY_MS = 2e3;
   const OVERLOAD_MAX_DELAY_MS = 3e4;
   const STREAM_FIRST_EVENT_TIMEOUT_MS = 45e3;
@@ -448,6 +512,18 @@ async function* agentLoop(messages, options) {
       let streamIterator = null;
       try {
         diag("stream_call", { nonStreaming: useNonStreamingFallback });
+        providerCalls++;
+        if (useNonStreamingFallback) nonStreamingCalls++;
+        if (!warnedNonStreaming && nonStreamingCalls >= 3) {
+          warnedNonStreaming = true;
+          diag("non_streaming_session", {
+            nonStreamingCalls,
+            providerCalls,
+            provider: options.provider,
+            model: options.model,
+            impact: "streaming is disabled for this session after repeated stalls: failed turns are re-billed in full instead of resuming from partial output, and replies appear only when complete"
+          });
+        }
         streamCallStart = Date.now();
         providerAttemptStartedAt = streamCallStart;
         let liveApiKey = options.apiKey;
@@ -473,7 +549,9 @@ async function* agentLoop(messages, options) {
           serverTools: options.serverTools,
           toolChoice: options.toolChoice,
           webSearch: options.webSearch,
-          maxTokens: options.maxTokens,
+          // Clamped to whatever ceiling this route has already rejected us for
+          // (identity when nothing has been learned).
+          maxTokens: clampOutputTokens(ceilingKey, options.maxTokens),
           temperature: options.temperature,
           thinking: options.thinking,
           apiKey: liveApiKey,
@@ -630,6 +708,29 @@ async function* agentLoop(messages, options) {
           });
           throw err;
         }
+        const statedCeiling = parseOutputTokenCeiling(err);
+        if (statedCeiling !== null) {
+          rememberOutputCeiling(ceilingKey, statedCeiling);
+          diag("output_ceiling_learned", {
+            ceiling: statedCeiling,
+            requested: options.maxTokens,
+            provider: options.provider,
+            model: options.model
+          });
+          if (outputCeilingRetries < MAX_OUTPUT_CEILING_RETRIES) {
+            outputCeilingRetries++;
+            yield {
+              type: "retry",
+              reason: "provider_error",
+              attempt: outputCeilingRetries,
+              maxAttempts: MAX_OUTPUT_CEILING_RETRIES,
+              delayMs: 0,
+              silent: true
+            };
+            turn--;
+            continue;
+          }
+        }
         if (isContextOverflow(err)) {
           const overflowDetails = extractContextOverflowDetails(err);
           diag("context_overflow_detected", {
@@ -925,6 +1026,7 @@ async function* agentLoop(messages, options) {
           continue;
         }
       }
+      const emptyExhausted = !hasActionableContent;
       emptyResponseRetries = 0;
       useNonStreamingFallback = false;
       totalUsage.inputTokens += response.usage.inputTokens;
@@ -938,9 +1040,11 @@ async function* agentLoop(messages, options) {
       if (response.usage.cacheWrite) {
         totalUsage.cacheWrite = (totalUsage.cacheWrite ?? 0) + response.usage.cacheWrite;
       }
-      messages.push(response.message);
-      latestProviderUsage = response.usage;
-      usageAnchorIndex = messages.length - 1;
+      if (!emptyExhausted) {
+        messages.push(response.message);
+        latestProviderUsage = response.usage;
+        usageAnchorIndex = messages.length - 1;
+      }
       const completedAt = Date.now();
       const outputTokensPerSecond = providerDurationMs > 0 && response.usage.outputTokens > 0 ? response.usage.outputTokens / (providerDurationMs / 1e3) : void 0;
       const timing = {
@@ -972,8 +1076,15 @@ 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 (emptyExhausted || response.stopReason !== "tool_use" && allToolCalls.length === 0) {
+        if (emptyExhausted) {
+          diag("empty_response_exhausted", {
+            provider: options.provider,
+            model: options.model,
+            stopReason: response.stopReason
+          });
+          yield { type: "truncated", reason: "empty_response", continued: false };
+        } else if (response.stopReason === "max_tokens") {
           if (maxTokensContinuations < MAX_OUTPUT_CONTINUATIONS) {
             maxTokensContinuations++;
             diag("max_tokens_continuation", {
@@ -1195,6 +1306,7 @@ async function executeSingleToolCall(toolCall, options, pushEvent) {
   let resultContent;
   let details;
   let isError = false;
+  let invalidArgAttempt;
   const tool = options.toolMap.get(toolCall.name);
   if (!tool) {
     resultContent = `Unknown tool: ${toolCall.name}`;
@@ -1232,6 +1344,7 @@ async function executeSingleToolCall(toolCall, options, pushEvent) {
         const failureKey = `${toolCall.name}:${prettyError}`;
         const failureCount = (options.invalidToolArgumentCounts.get(failureKey) ?? 0) + 1;
         options.invalidToolArgumentCounts.set(failureKey, failureCount);
+        invalidArgAttempt = failureCount;
         resultContent = `Invalid arguments for tool \`${toolCall.name}\`:
 ` + prettyError + "\nRe-issue the call with each field as the correct type.";
         if (failureCount >= 3) {
@@ -1248,6 +1361,8 @@ async function executeSingleToolCall(toolCall, options, pushEvent) {
             toolCall.name
           );
         }
+      } else if (options.signal?.aborted && isAbortError(err)) {
+        resultContent = indeterminateOutcomeText(toolCall.name);
       } else {
         resultContent = redactValue(err instanceof Error ? err.message : String(err));
       }
@@ -1262,7 +1377,8 @@ async function executeSingleToolCall(toolCall, options, pushEvent) {
     result: toolResultPreview(resultContent),
     details,
     isError,
-    durationMs
+    durationMs,
+    ...invalidArgAttempt === void 0 ? {} : { invalidArgAttempt }
   });
   return { toolCallId: toolCall.id, content: resultContent, isError };
 }
@@ -1270,6 +1386,7 @@ async function* executeToolCallsMixed(toolCalls, initialToolResults, options) {
   const eventStream = new EventStream();
   const state = { finalized: false };
   const resultsById = /* @__PURE__ */ new Map();
+  const dispatchedIds = /* @__PURE__ */ new Set();
   const abortHandler = () => eventStream.abort(new Error("aborted"));
   options.signal?.addEventListener("abort", abortHandler, { once: true });
   const phases = [];
@@ -1294,6 +1411,7 @@ async function* executeToolCallsMixed(toolCalls, initialToolResults, options) {
       for (const phase of phases) {
         if (options.signal?.aborted) break;
         if (phase.sequential) {
+          dispatchedIds.add(phase.sequential.id);
           const record = await executeSingleToolCall(
             phase.sequential,
             options,
@@ -1301,6 +1419,7 @@ async function* executeToolCallsMixed(toolCalls, initialToolResults, options) {
           );
           resultsById.set(record.toolCallId, record);
         } else if (phase.parallel.length === 1) {
+          dispatchedIds.add(phase.parallel[0].id);
           const record = await executeSingleToolCall(
             phase.parallel[0],
             options,
@@ -1310,6 +1429,7 @@ async function* executeToolCallsMixed(toolCalls, initialToolResults, options) {
         } else {
           await Promise.all(
             phase.parallel.map(async (toolCall) => {
+              dispatchedIds.add(toolCall.id);
               const record = await executeSingleToolCall(
                 toolCall,
                 options,
@@ -1340,7 +1460,7 @@ async function* executeToolCallsMixed(toolCalls, initialToolResults, options) {
     options.signal?.removeEventListener("abort", abortHandler);
     state.finalized = true;
   }
-  const toolResults = buildToolResults(initialToolResults, toolCalls, resultsById);
+  const toolResults = buildToolResults(initialToolResults, toolCalls, resultsById, dispatchedIds);
   capToolResults(toolResults, options.maxToolResultChars);
   capTurnToolResults(toolResults, options.maxTurnToolResultChars);
   return { toolResults, aborted };
@@ -1349,10 +1469,12 @@ async function* executeToolCallsParallel(toolCalls, initialToolResults, options)
   const eventStream = new EventStream();
   const state = { finalized: false };
   const resultsById = /* @__PURE__ */ new Map();
+  const dispatchedIds = /* @__PURE__ */ new Set();
   const abortHandler = () => eventStream.abort(new Error("aborted"));
   options.signal?.addEventListener("abort", abortHandler, { once: true });
   Promise.all(
     toolCalls.map(async (toolCall) => {
+      dispatchedIds.add(toolCall.id);
       const record = await executeSingleToolCall(
         toolCall,
         options,
@@ -1380,12 +1502,18 @@ async function* executeToolCallsParallel(toolCalls, initialToolResults, options)
     options.signal?.removeEventListener("abort", abortHandler);
     state.finalized = true;
   }
-  const toolResults = buildToolResults(initialToolResults, toolCalls, resultsById);
+  const toolResults = buildToolResults(initialToolResults, toolCalls, resultsById, dispatchedIds);
   capToolResults(toolResults, options.maxToolResultChars);
   capTurnToolResults(toolResults, options.maxTurnToolResultChars);
   return { toolResults, aborted };
 }
-function buildToolResults(initialToolResults, toolCalls, resultsById) {
+function cancelledBeforeStartText(name) {
+  return `\`${name}\` was cancelled before it started, so it had no effect. Safe to retry.`;
+}
+function indeterminateOutcomeText(name) {
+  return `\`${name}\` started running and was cut off before it reported back, so its outcome is UNKNOWN \u2014 it may have completed. Check the real state (re-read the file, re-run a status command) before retrying it, and do not tell the user it did not happen.`;
+}
+function buildToolResults(initialToolResults, toolCalls, resultsById, dispatchedIds) {
   const toolResults = [...initialToolResults];
   for (const toolCall of toolCalls) {
     const result = resultsById.get(toolCall.id);
@@ -1397,10 +1525,11 @@ function buildToolResults(initialToolResults, toolCalls, resultsById) {
         isError: result.isError || void 0
       });
     } else {
+      const dispatched = dispatchedIds?.has(toolCall.id) ?? true;
       toolResults.push({
         type: "tool_result",
         toolCallId: toolCall.id,
-        content: "Tool execution was aborted.",
+        content: dispatched ? indeterminateOutcomeText(toolCall.name) : cancelledBeforeStartText(toolCall.name),
         isError: true
       });
     }
@@ -1548,32 +1677,22 @@ function repairToolPairingAdjacent(messages) {
     const msg = messages[i];
     if (msg.role !== "assistant") continue;
     if (typeof msg.content === "string" || !Array.isArray(msg.content)) continue;
-    const toolCallIds = msg.content.filter((p) => p.type === "tool_call").map((p) => p.id);
-    if (toolCallIds.length === 0) continue;
+    const orphanCalls = msg.content.filter((p) => p.type === "tool_call").map((p) => p);
+    if (orphanCalls.length === 0) continue;
+    const repaired = (call) => ({
+      type: "tool_result",
+      toolCallId: call.id,
+      content: indeterminateOutcomeText(call.name),
+      isError: true
+    });
     const next = messages[i + 1];
     if (next?.role === "tool" && Array.isArray(next.content)) {
       const existingIds = new Set(next.content.map((r) => r.toolCallId));
-      const missing = toolCallIds.filter((id) => !existingIds.has(id));
-      if (missing.length > 0) {
-        for (const id of missing) {
-          next.content.push({
-            type: "tool_result",
-            toolCallId: id,
-            content: "Tool execution was interrupted.",
-            isError: true
-          });
-        }
+      for (const call of orphanCalls) {
+        if (!existingIds.has(call.id)) next.content.push(repaired(call));
       }
     } else {
-      messages.splice(i + 1, 0, {
-        role: "tool",
-        content: toolCallIds.map((id) => ({
-          type: "tool_result",
-          toolCallId: id,
-          content: "Tool execution was interrupted.",
-          isError: true
-        }))
-      });
+      messages.splice(i + 1, 0, { role: "tool", content: orphanCalls.map(repaired) });
     }
   }
   const toolCallIdSet = /* @__PURE__ */ new Set();
@@ -1732,6 +1851,8 @@ export {
   Agent,
   AgentStream,
   agentLoop,
+  cancelledBeforeStartText,
+  indeterminateOutcomeText,
   isAbortError,
   isBillingError,
   isContextOverflow,