@prestyj/agent 5.28.1 → 5.29.1

package/dist/index.cjs

@@ -22,7 +22,12 @@ var index_exports = {};
 __export(index_exports, {
   Agent: () => Agent,
   AgentStream: () => AgentStream,
+  DEFAULT_STREAM_RULE_MAX_RETRIES: () => DEFAULT_STREAM_RULE_MAX_RETRIES,
+  DEFAULT_STREAM_RULE_WINDOW_CHARS: () => DEFAULT_STREAM_RULE_WINDOW_CHARS,
+  JsonEscapeDecoder: () => JsonEscapeDecoder,
+  StreamRuleMonitor: () => StreamRuleMonitor,
   agentLoop: () => agentLoop,
+  buildStreamRuleReminder: () => buildStreamRuleReminder,
   cancelledBeforeStartText: () => cancelledBeforeStartText,
   indeterminateOutcomeText: () => indeterminateOutcomeText,
   isAbortError: () => isAbortError,
@@ -30,16 +35,17 @@ __export(index_exports, {
   isContextOverflow: () => isContextOverflow,
   isLocalBackendUrl: () => isLocalBackendUrl,
   isUsageLimitError: () => isUsageLimitError,
+  repairToolPairingAdjacent: () => repairToolPairingAdjacent,
   setStreamDiagnostic: () => setStreamDiagnostic
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/agent.ts
-var import_ai2 = require("@prestyj/ai");
+var import_ai3 = require("@prestyj/ai");
 
 // src/agent-loop.ts
 var import_zod = require("zod");
-var import_ai = require("@prestyj/ai");
+var import_ai2 = require("@prestyj/ai");
 
 // src/local-backend.ts
 function isLocalBackendUrl(baseUrl) {
@@ -63,6 +69,107 @@ function isLocalBackendUrl(baseUrl) {
   return false;
 }
 
+// src/tool-call-hints.ts
+var import_ai = require("@prestyj/ai");
+function normalizeName(name) {
+  return name.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+function editDistance(a, b) {
+  let beforePrevious = [];
+  let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    const current = [i];
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      let distance = Math.min(
+        (previous[j] ?? 0) + 1,
+        (current[j - 1] ?? 0) + 1,
+        (previous[j - 1] ?? 0) + cost
+      );
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+        distance = Math.min(distance, (beforePrevious[j - 2] ?? 0) + 1);
+      }
+      current[j] = distance;
+    }
+    beforePrevious = previous;
+    previous = current;
+  }
+  return previous[b.length] ?? 0;
+}
+function closestName(name, candidates) {
+  const target = normalizeName(name);
+  if (!target) return void 0;
+  const limit = Math.min(3, Math.max(1, Math.floor(target.length / 3)));
+  let best;
+  for (const candidate of [...candidates].sort()) {
+    if (candidate === name) continue;
+    const distance = editDistance(target, normalizeName(candidate));
+    if (distance > limit) continue;
+    if (!best || distance < best.distance) best = { name: candidate, distance };
+  }
+  return best?.name;
+}
+function unknownToolMessage(name, available) {
+  const suggestion = closestName(name, available);
+  if (suggestion) return `Unknown tool: ${name}. Did you mean \`${suggestion}\`?`;
+  const names = [...available].sort();
+  const listed = names.length > 40 ? `${names.slice(0, 40).join(", ")}, \u2026` : names.join(", ");
+  const searchHint = available.includes("tool_search") ? " If the capability is not listed, call `tool_search` to load it." : "";
+  return `Unknown tool: ${name}. Available tools: ${listed}.${searchHint}`;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function typeLabel(node) {
+  if (!isRecord(node)) return "any";
+  if (Array.isArray(node.enum)) {
+    return node.enum.map((value) => JSON.stringify(value)).join(" | ");
+  }
+  const variants = node.anyOf ?? node.oneOf;
+  if (Array.isArray(variants)) {
+    return [...new Set(variants.map(typeLabel))].filter((t) => t !== "null").join(" | ") || "any";
+  }
+  if (node.type === "array") return `${typeLabel(node.items)}[]`;
+  if (Array.isArray(node.type)) {
+    return node.type.filter((t) => t !== "null").join(" | ") || "any";
+  }
+  return typeof node.type === "string" ? node.type : "any";
+}
+function objectShape(tool) {
+  let schema;
+  try {
+    schema = (0, import_ai.resolveToolSchema)(tool);
+  } catch {
+    return void 0;
+  }
+  if (!isRecord(schema) || !isRecord(schema.properties)) return void 0;
+  const required = new Set(
+    Array.isArray(schema.required) ? schema.required.filter((r) => typeof r === "string") : []
+  );
+  return { properties: schema.properties, required };
+}
+function argumentHints(tool, args) {
+  const shape = objectShape(tool);
+  if (!shape) return "";
+  const names = Object.keys(shape.properties);
+  if (names.length === 0) return `Expected arguments: none.`;
+  const fields = names.map((name) => {
+    const optional = shape.required.has(name) ? "" : "?";
+    return `${name}${optional}: ${typeLabel(shape.properties[name])}`;
+  });
+  const lines = [`Expected arguments: { ${fields.join(", ")} }`];
+  if (isRecord(args)) {
+    for (const key of Object.keys(args).sort()) {
+      if (key in shape.properties) continue;
+      const suggestion = closestName(key, names);
+      lines.push(
+        suggestion ? `Unknown field \`${key}\` \u2014 did you mean \`${suggestion}\`?` : `Unknown field \`${key}\` is not a parameter of this tool.`
+      );
+    }
+  }
+  return lines.join("\n");
+}
+
 // src/output-ceiling.ts
 var TTL_MS = 24 * 60 * 60 * 1e3;
 var MIN_PLAUSIBLE_CEILING = 256;
@@ -117,12 +224,162 @@ function clampOutputTokens(key, requested) {
   return requested === void 0 ? ceiling : Math.min(requested, ceiling);
 }
 
+// src/stream-rules.ts
+var DEFAULT_STREAM_RULE_MAX_RETRIES = 3;
+var DEFAULT_STREAM_RULE_WINDOW_CHARS = 1024;
+var JSON_ESCAPES = {
+  n: "\n",
+  r: "\r",
+  t: "	",
+  b: "\b",
+  f: "\f",
+  '"': '"',
+  "\\": "\\",
+  "/": "/"
+};
+var JsonEscapeDecoder = class {
+  pending = "";
+  push(chunk) {
+    const input = this.pending + chunk;
+    this.pending = "";
+    if (!input.includes("\\")) return input;
+    let out = "";
+    let i = 0;
+    while (i < input.length) {
+      const ch = input.charAt(i);
+      if (ch !== "\\") {
+        out += ch;
+        i++;
+        continue;
+      }
+      if (i + 1 >= input.length) {
+        this.pending = input.slice(i);
+        break;
+      }
+      const next = input.charAt(i + 1);
+      if (next === "u") {
+        if (i + 6 > input.length) {
+          this.pending = input.slice(i);
+          break;
+        }
+        const hex = input.slice(i + 2, i + 6);
+        out += /^[0-9a-fA-F]{4}$/.test(hex) ? String.fromCharCode(Number.parseInt(hex, 16)) : input.slice(i, i + 6);
+        i += 6;
+        continue;
+      }
+      out += JSON_ESCAPES[next] ?? next;
+      i += 2;
+    }
+    return out;
+  }
+};
+var StreamRuleMonitor = class {
+  maxRetries;
+  rules;
+  windowChars;
+  fired = /* @__PURE__ */ new Set();
+  retries = 0;
+  textWindow = "";
+  toolStreams = /* @__PURE__ */ new Map();
+  constructor(config) {
+    this.rules = config.rules;
+    this.maxRetries = Math.max(0, config.maxRetries ?? DEFAULT_STREAM_RULE_MAX_RETRIES);
+    this.windowChars = Math.max(64, config.windowChars ?? DEFAULT_STREAM_RULE_WINDOW_CHARS);
+  }
+  /** False once the retry cap is spent or every rule has fired — skip all matching. */
+  get active() {
+    return this.retries < this.maxRetries && this.fired.size < this.rules.length;
+  }
+  get retriesUsed() {
+    return this.retries;
+  }
+  beginAttempt() {
+    this.textWindow = "";
+    this.toolStreams.clear();
+  }
+  checkText(delta) {
+    if (!this.active || !delta) return null;
+    const scan = this.textWindow + delta;
+    this.textWindow = scan.slice(-this.windowChars);
+    const rules = this.match(scan, "text");
+    return rules.length > 0 ? { rules, source: "text" } : null;
+  }
+  checkToolArgs(id, toolName, argsDelta) {
+    if (!this.active || !argsDelta) return null;
+    let state = this.toolStreams.get(id);
+    if (!state) {
+      state = { window: "", decoder: new JsonEscapeDecoder() };
+      this.toolStreams.set(id, state);
+    }
+    const scan = state.window + state.decoder.push(argsDelta);
+    state.window = scan.slice(-this.windowChars);
+    const rules = this.match(scan, "tool", toolName);
+    return rules.length > 0 ? { rules, source: "tool", toolName } : null;
+  }
+  /** Consume one retry and mark the rules fired. Returns the retry ordinal (1-based). */
+  recordTrigger(rules) {
+    for (const rule of rules) this.fired.add(rule.name);
+    this.retries++;
+    return this.retries;
+  }
+  match(scan, source, toolName) {
+    const hits = [];
+    for (const rule of this.rules) {
+      if (this.fired.has(rule.name)) continue;
+      if (rule.scope !== "both" && rule.scope !== source) continue;
+      if (source === "tool" && rule.tools && toolName !== void 0) {
+        if (!rule.tools.includes(toolName)) continue;
+      }
+      rule.pattern.lastIndex = 0;
+      if (rule.pattern.test(scan)) hits.push(rule);
+    }
+    return hits;
+  }
+};
+function buildStreamRuleReminder(rules) {
+  const blocks = rules.map(
+    (rule) => `<system-reminder reason="stream_rule" rule="${rule.name.replace(/"/g, "'")}">
+Your previous response was interrupted mid-stream because it violated this rule. The interrupted output was discarded: the user never saw it and no tool call from it ran. Regenerate the response from the start and follow the rule:
+
+${rule.reminder.trim()}
+</system-reminder>`
+  );
+  return {
+    role: "user",
+    content: blocks.join("\n\n"),
+    provenance: { source: "runtime", kind: "notification", visibility: "hidden" }
+  };
+}
+
 // src/agent-loop.ts
 var DEFAULT_MAX_TURNS = 300;
 var DEFAULT_TOOL_TIMEOUT_MS = 3e5;
+var PREEMPT_GRACE_MS = 500;
+var STEER_INTERRUPTED_TEXT = "Interrupted: the user sent a new message.";
+var ATOMIC_TOOL_NAMES = /* @__PURE__ */ new Set(["edit", "write", "multi_edit", "apply_patch", "notebook_edit"]);
+function isInterruptibleTool(tool, name) {
+  if (tool?.interruptible !== void 0) return tool.interruptible;
+  return !ATOMIC_TOOL_NAMES.has(name);
+}
+function markSteerInterrupted(record) {
+  const content = record.content;
+  let next;
+  if (typeof content === "string") {
+    next = content.trim() ? `${STEER_INTERRUPTED_TEXT}
+Partial output:
+${content}` : STEER_INTERRUPTED_TEXT;
+  } else {
+    next = [
+      { type: "text", text: `${STEER_INTERRUPTED_TEXT}
+Partial output:` },
+      ...content
+    ];
+  }
+  return { toolCallId: record.toolCallId, content: next, isError: true };
+}
 var _toolRedaction;
 function toolRedactionOptions() {
-  _toolRedaction ??= { secrets: (0, import_ai.environmentSecrets)(process.env) };
+  _toolRedaction ??= { secrets: (0, import_ai2.environmentSecrets)(process.env) };
   return _toolRedaction;
 }
 var _diagFn = null;
@@ -205,7 +462,7 @@ function isBillingError(err) {
   if (!(err instanceof Error)) return false;
   const statusCode = err.statusCode;
   if (statusCode === 402) return true;
-  return (0, import_ai.isHardBillingMessage)(err.message);
+  return (0, import_ai2.isHardBillingMessage)(err.message);
 }
 function isUsageLimitError(err) {
   if (!(err instanceof Error)) return false;
@@ -430,6 +687,7 @@ async function* agentLoop(messages, options) {
   let runawayToolcallRetries = 0;
   let overflowCompactionAttempts = 0;
   let toolResultTruncationAttempted = false;
+  const streamRuleMonitor = options.streamRules && options.streamRules.rules.length > 0 ? new StreamRuleMonitor(options.streamRules) : null;
   const invalidToolArgumentCounts = /* @__PURE__ */ new Map();
   let toolArgumentAutoContinueUsed = false;
   let useNonStreamingFallback = false;
@@ -483,16 +741,7 @@ async function* agentLoop(messages, options) {
       turn++;
       if (logicalTurnStartedAt === 0) logicalTurnStartedAt = Date.now();
       toolMap = new Map((options.tools ?? []).map((t) => [t.name, t]));
-      let msgChars = 0;
-      for (const m of messages) {
-        if (typeof m.content === "string") msgChars += m.content.length;
-        else if (Array.isArray(m.content)) {
-          for (const p of m.content) {
-            if ("text" in p && typeof p.text === "string") msgChars += p.text.length;
-            if ("content" in p && typeof p.content === "string") msgChars += p.content.length;
-          }
-        }
-      }
+      const msgChars = countMessageChars(messages);
       let firstEventTimeoutMs;
       let initialHardTimeoutMs;
       if (baseFirstEventTimeoutMs === STREAM_FIRST_EVENT_TIMEOUT_MS) {
@@ -563,6 +812,9 @@ async function* agentLoop(messages, options) {
       let toolcallNoProgressCount = 0;
       let runawayDetected = null;
       let attemptText = "";
+      let streamRuleHit = null;
+      let attemptThinkingChars = 0;
+      streamRuleMonitor?.beginAttempt();
       let lastYieldEndTime = Date.now();
       let maxConsumerLagMs = 0;
       const forwardAbort = () => streamController.abort();
@@ -629,7 +881,7 @@ async function* agentLoop(messages, options) {
             });
           }
         }
-        const result = (0, import_ai.stream)({
+        const result = (0, import_ai2.stream)({
           provider: options.provider,
           model: options.model,
           messages,
@@ -649,8 +901,11 @@ async function* agentLoop(messages, options) {
           transportSessionId: options.transportSessionId,
           projectId: liveProjectId,
           cacheRetention: options.cacheRetention,
+          onContextPrepared: options.onContextPrepared,
           promptCacheKey: options.promptCacheKey,
           serviceTier: options.serviceTier,
+          responsesLite: options.responsesLite,
+          strictTools: options.strictTools,
           supportsImages: options.supportsImages,
           supportsVideo: options.supportsVideo,
           compaction: options.compaction,
@@ -726,8 +981,14 @@ async function* agentLoop(messages, options) {
           }
           if (event.type === "text_delta") {
             attemptText += event.text;
+            streamRuleHit = streamRuleMonitor?.checkText(event.text) ?? null;
+            if (streamRuleHit) {
+              streamController.abort();
+              break;
+            }
             yield { type: "text_delta", text: event.text };
           } else if (event.type === "thinking_delta") {
+            attemptThinkingChars += event.text.length;
             yield { type: "thinking_delta", text: event.text };
           } else if (event.type === "server_toolcall") {
             yield {
@@ -748,6 +1009,11 @@ async function* agentLoop(messages, options) {
             toolcallDeltaChars += chunkChars;
             toolcallDeltaCount++;
             toolcallNoProgressCount = chunkChars > 0 ? 0 : toolcallNoProgressCount + 1;
+            streamRuleHit = streamRuleMonitor?.checkToolArgs(event.id, event.name, event.argsJson ?? "") ?? null;
+            if (streamRuleHit) {
+              streamController.abort();
+              break;
+            }
             if (!runawayDetected && (toolcallDeltaChars > MAX_TOOLCALL_DELTA_CHARS || toolcallNoProgressCount > MAX_TOOLCALL_NO_PROGRESS_EVENTS)) {
               runawayDetected = {
                 kind: toolcallDeltaChars > MAX_TOOLCALL_DELTA_CHARS ? "chars" : "events",
@@ -770,6 +1036,54 @@ async function* agentLoop(messages, options) {
           lastYieldEndTime = Date.now();
           resetIdleTimer();
         }
+        if (streamRuleHit && streamRuleMonitor) {
+          const attempt = streamRuleMonitor.recordTrigger(streamRuleHit.rules);
+          const ruleNames = streamRuleHit.rules.map((rule) => rule.name);
+          const priorPrompt = latestProviderUsage ? latestProviderUsage.inputTokens + (latestProviderUsage.cacheRead ?? 0) + (latestProviderUsage.cacheWrite ?? 0) : 0;
+          const newChars = priorPrompt > 0 && usageAnchorIndex !== void 0 ? countMessageChars(messages.slice(usageAnchorIndex + 1)) : msgChars;
+          const abortedUsage = {
+            inputTokens: Math.ceil(newChars / 4),
+            outputTokens: Math.ceil(
+              (attemptText.length + attemptThinkingChars + toolcallDeltaChars) / 4
+            ),
+            ...priorPrompt > 0 ? { cacheRead: priorPrompt } : {}
+          };
+          totalUsage.inputTokens += abortedUsage.inputTokens;
+          totalUsage.outputTokens += abortedUsage.outputTokens;
+          if (abortedUsage.cacheRead) {
+            totalUsage.cacheRead = (totalUsage.cacheRead ?? 0) + abortedUsage.cacheRead;
+          }
+          diag("stream_rule_triggered", {
+            rules: ruleNames.join(","),
+            source: streamRuleHit.source,
+            toolName: streamRuleHit.toolName,
+            attempt,
+            maxAttempts: streamRuleMonitor.maxRetries,
+            discardedChars: attemptText.length + toolcallDeltaChars,
+            provider: options.provider,
+            model: options.model
+          });
+          messages.push(buildStreamRuleReminder(streamRuleHit.rules));
+          yield {
+            type: "stream_rule_triggered",
+            rules: ruleNames,
+            source: streamRuleHit.source,
+            ...streamRuleHit.toolName !== void 0 ? { toolName: streamRuleHit.toolName } : {},
+            attempt,
+            maxAttempts: streamRuleMonitor.maxRetries,
+            usage: abortedUsage
+          };
+          yield {
+            type: "retry",
+            reason: "stream_rule",
+            attempt,
+            maxAttempts: streamRuleMonitor.maxRetries,
+            delayMs: 0,
+            silent: true
+          };
+          turn--;
+          continue;
+        }
         diag("stream_done", {
           events: streamEventCount,
           totalMs: Date.now() - streamCallStart,
@@ -961,7 +1275,7 @@ async function* agentLoop(messages, options) {
           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 import_ai.EZCoderAIError(
+            error: new import_ai2.EZCoderAIError(
               `The model repeatedly failed to close a tool call after ${MAX_RUNAWAY_TOOLCALL_RETRIES} automatic retries (${detail}). Your conversation is preserved.`,
               {
                 source: "provider",
@@ -1043,7 +1357,7 @@ async function* agentLoop(messages, options) {
           });
           yield {
             type: "error",
-            error: new import_ai.EZCoderAIError(
+            error: new import_ai2.EZCoderAIError(
               `The connection to the API provider stopped responding after ${MAX_STALL_RETRIES} automatic retries. Your conversation is preserved.`,
               {
                 source: "network",
@@ -1276,10 +1590,14 @@ async function* agentLoop(messages, options) {
         fatalToolArgumentRecoverable = recoverable;
         fatalToolArgumentToolName = toolName;
       };
+      const preempt = new AbortController();
+      const unsubscribeSteering = options.onSteeringAvailable?.(() => preempt.abort());
       const executionOptions = {
         signal: options.signal,
+        preemptSignal: options.onSteeringAvailable ? preempt.signal : void 0,
         maxToolResultChars: options.maxToolResultChars,
         maxTurnToolResultChars: options.maxTurnToolResultChars,
+        transformToolResult: options.transformToolResult,
         toolMap,
         invalidToolArgumentCounts,
         markFatalToolArgumentError,
@@ -1288,7 +1606,15 @@ async function* agentLoop(messages, options) {
       const hasSequentialToolCall = toolCalls.some(
         (toolCall) => toolMap.get(toolCall.name)?.executionMode === "sequential"
       );
-      const executionResult = hasSequentialToolCall ? yield* executeToolCallsMixed(toolCalls, toolResults, executionOptions) : yield* executeToolCallsParallel(toolCalls, toolResults, executionOptions);
+      let executionResult;
+      try {
+        executionResult = hasSequentialToolCall ? yield* executeToolCallsMixed(toolCalls, toolResults, executionOptions) : yield* executeToolCallsParallel(toolCalls, toolResults, executionOptions);
+      } finally {
+        unsubscribeSteering?.();
+      }
+      if (executionResult.preempted) {
+        diag("steer_preempted_tools", { turn, provider: options.provider, model: options.model });
+      }
       messages.push({ role: "tool", content: executionResult.toolResults });
       yield { type: "checkpoint", turn };
       const toolsAborted = executionResult.aborted;
@@ -1445,7 +1771,7 @@ async function executeSingleToolCall(toolCall, options, pushEvent) {
     options.seenToolCalls.add(signature);
   }
   if (!tool) {
-    resultContent = `Unknown tool: ${toolCall.name}`;
+    resultContent = unknownToolMessage(toolCall.name, [...options.toolMap.keys()]);
     isError = true;
   } else {
     try {
@@ -1462,8 +1788,12 @@ async function executeSingleToolCall(toolCall, options, pushEvent) {
       }
       const callerSignal = options.signal;
       const toolTimeout = AbortSignal.timeout(tool.timeoutMs ?? DEFAULT_TOOL_TIMEOUT_MS);
+      const preemptSignal = isInterruptibleTool(tool, toolCall.name) ? options.preemptSignal : void 0;
+      const toolSignals = [callerSignal, toolTimeout, preemptSignal].filter(
+        (s) => s !== void 0
+      );
       const ctx = {
-        signal: callerSignal ? AbortSignal.any([callerSignal, toolTimeout]) : toolTimeout,
+        signal: toolSignals.length === 1 ? toolTimeout : AbortSignal.any(toolSignals),
         toolCallId: toolCall.id,
         onUpdate: (update) => {
           pushEvent({
@@ -1473,13 +1803,25 @@ async function executeSingleToolCall(toolCall, options, pushEvent) {
           });
         }
       };
+      const hardSignals = [callerSignal, toolTimeout].filter(
+        (s) => s !== void 0
+      );
       const raw = await abortablePromise(
         Promise.resolve().then(() => tool.execute(parsed, ctx)),
-        ctx.signal
+        hardSignals.length === 1 ? toolTimeout : AbortSignal.any(hardSignals)
       );
       const normalized = normalizeToolResult(raw);
-      resultContent = (0, import_ai.redactValue)(normalized.content, toolRedactionOptions());
-      details = (0, import_ai.redactValue)(normalized.details, toolRedactionOptions());
+      resultContent = (0, import_ai2.redactValue)(normalized.content, toolRedactionOptions());
+      details = (0, import_ai2.redactValue)(normalized.details, toolRedactionOptions());
+      if (options.transformToolResult) {
+        try {
+          resultContent = options.transformToolResult(
+            { name: toolCall.name, args: toolCall.args },
+            resultContent
+          );
+        } catch {
+        }
+      }
       for (const key of options.invalidToolArgumentCounts.keys()) {
         if (key.startsWith(`${toolCall.name}:`)) options.invalidToolArgumentCounts.delete(key);
       }
@@ -1491,12 +1833,14 @@ async function executeSingleToolCall(toolCall, options, pushEvent) {
         const failureCount = (options.invalidToolArgumentCounts.get(failureKey) ?? 0) + 1;
         options.invalidToolArgumentCounts.set(failureKey, failureCount);
         invalidArgAttempt = failureCount;
+        const hints = argumentHints(tool, toolCall.args);
         resultContent = `Invalid arguments for tool \`${toolCall.name}\`:
-` + prettyError + "\nRe-issue the call with each field as the correct type.";
+` + prettyError + (hints ? `
+${hints}` : "") + "\nRe-issue the call with each field as the correct type.";
         if (failureCount >= 3) {
           const recoverable = Object.keys(toolCall.args ?? {}).length === 0;
           options.markFatalToolArgumentError(
-            new import_ai.EZCoderAIError(
+            new import_ai2.EZCoderAIError(
               `The model repeatedly issued invalid arguments for tool \`${toolCall.name}\`. This is usually an upstream model/tool-calling bug` + (recoverable ? " (the provider's stream returned empty tool-call arguments)" : "") + `. Your conversation is preserved; send another message or switch models to continue.`,
               {
                 source: "provider",
@@ -1510,15 +1854,24 @@ async function executeSingleToolCall(toolCall, options, pushEvent) {
       } else if (options.signal?.aborted && isAbortError(err)) {
         resultContent = indeterminateOutcomeText(toolCall.name);
       } else {
-        resultContent = (0, import_ai.redactValue)(
+        resultContent = (0, import_ai2.redactValue)(
           err instanceof Error ? err.message : String(err),
           toolRedactionOptions()
         );
       }
     }
   }
-  resultContent = (0, import_ai.redactValue)(resultContent, toolRedactionOptions());
-  details = (0, import_ai.redactValue)(details, toolRedactionOptions());
+  resultContent = (0, import_ai2.redactValue)(resultContent, toolRedactionOptions());
+  details = (0, import_ai2.redactValue)(details, toolRedactionOptions());
+  if (options.preemptSignal?.aborted && isInterruptibleTool(options.toolMap.get(toolCall.name), toolCall.name)) {
+    const marked = markSteerInterrupted({
+      toolCallId: toolCall.id,
+      content: resultContent,
+      isError
+    });
+    resultContent = marked.content;
+    isError = true;
+  }
   const durationMs = Date.now() - startTime;
   pushEvent({
     type: "tool_call_end",
@@ -1531,13 +1884,67 @@ async function executeSingleToolCall(toolCall, options, pushEvent) {
   });
   return { toolCallId: toolCall.id, content: resultContent, isError };
 }
+function createPreemptTracker(options, eventStream, state, resultsById, dispatchedIds) {
+  const running = /* @__PURE__ */ new Map();
+  let graceTimer;
+  const preemptSignal = options.preemptSignal;
+  const abandon = () => {
+    graceTimer = void 0;
+    for (const [id, entry] of running) {
+      if (!entry.interruptible || resultsById.has(id)) continue;
+      resultsById.set(id, { toolCallId: id, content: STEER_INTERRUPTED_TEXT, isError: true });
+      pushToolEvent(eventStream, state, {
+        type: "tool_call_end",
+        toolCallId: id,
+        result: STEER_INTERRUPTED_TEXT,
+        isError: true,
+        durationMs: Date.now() - entry.startedAt
+      });
+      running.delete(id);
+    }
+    if (running.size === 0) eventStream.close();
+  };
+  const onPreempt = () => {
+    if (graceTimer === void 0) graceTimer = setTimeout(abandon, PREEMPT_GRACE_MS);
+  };
+  preemptSignal?.addEventListener("abort", onPreempt, { once: true });
+  return {
+    async run(toolCall) {
+      if (options.preemptSignal?.aborted) return;
+      dispatchedIds.add(toolCall.id);
+      const interruptible = isInterruptibleTool(options.toolMap.get(toolCall.name), toolCall.name);
+      running.set(toolCall.id, { toolCall, interruptible, startedAt: Date.now() });
+      const record = await executeSingleToolCall(
+        toolCall,
+        options,
+        (event) => pushToolEvent(eventStream, state, event)
+      );
+      running.delete(toolCall.id);
+      if (resultsById.has(toolCall.id)) return;
+      const alreadyMarked = typeof record.content === "string" ? record.content.startsWith(STEER_INTERRUPTED_TEXT) : record.content[0]?.type === "text" && record.content[0].text.startsWith(STEER_INTERRUPTED_TEXT);
+      resultsById.set(
+        toolCall.id,
+        interruptible && preemptSignal?.aborted && !alreadyMarked ? markSteerInterrupted(record) : record
+      );
+      if (preemptSignal?.aborted && graceTimer === void 0 && running.size === 0) {
+        eventStream.close();
+      }
+    },
+    preempted: () => preemptSignal?.aborted === true,
+    dispose: () => {
+      if (graceTimer !== void 0) clearTimeout(graceTimer);
+      preemptSignal?.removeEventListener("abort", onPreempt);
+    }
+  };
+}
 async function* executeToolCallsMixed(toolCalls, initialToolResults, options) {
-  const eventStream = new import_ai.EventStream();
+  const eventStream = new import_ai2.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 tracker = createPreemptTracker(options, eventStream, state, resultsById, dispatchedIds);
   const phases = [];
   let currentParallel = [];
   for (const toolCall of toolCalls) {
@@ -1558,40 +1965,18 @@ async function* executeToolCallsMixed(toolCalls, initialToolResults, options) {
   void (async () => {
     try {
       for (const phase of phases) {
-        if (options.signal?.aborted) break;
+        if (options.signal?.aborted || options.preemptSignal?.aborted) break;
         if (phase.sequential) {
           const signature = JSON.stringify([
             phase.sequential.name,
             canonicalToolArgs(phase.sequential.args)
           ]);
           if (!options.seenToolCalls.has(signature)) options.seenToolCalls.clear();
-          dispatchedIds.add(phase.sequential.id);
-          const record = await executeSingleToolCall(
-            phase.sequential,
-            options,
-            (event) => pushToolEvent(eventStream, state, event)
-          );
-          resultsById.set(record.toolCallId, record);
+          await tracker.run(phase.sequential);
         } else if (phase.parallel.length === 1) {
-          dispatchedIds.add(phase.parallel[0].id);
-          const record = await executeSingleToolCall(
-            phase.parallel[0],
-            options,
-            (event) => pushToolEvent(eventStream, state, event)
-          );
-          resultsById.set(record.toolCallId, record);
+          await tracker.run(phase.parallel[0]);
         } else {
-          await Promise.all(
-            phase.parallel.map(async (toolCall) => {
-              dispatchedIds.add(toolCall.id);
-              const record = await executeSingleToolCall(
-                toolCall,
-                options,
-                (event) => pushToolEvent(eventStream, state, event)
-              );
-              resultsById.set(record.toolCallId, record);
-            })
-          );
+          await Promise.all(phase.parallel.map((toolCall) => tracker.run(toolCall)));
         }
       }
       if (!state.finalized) eventStream.close();
@@ -1612,31 +1997,23 @@ async function* executeToolCallsMixed(toolCalls, initialToolResults, options) {
     }
   } finally {
     options.signal?.removeEventListener("abort", abortHandler);
+    tracker.dispose();
     state.finalized = true;
   }
   const toolResults = buildToolResults(initialToolResults, toolCalls, resultsById, dispatchedIds);
   capToolResults(toolResults, options.maxToolResultChars);
   capTurnToolResults(toolResults, options.maxTurnToolResultChars);
-  return { toolResults, aborted };
+  return { toolResults, aborted, preempted: !aborted && tracker.preempted() };
 }
 async function* executeToolCallsParallel(toolCalls, initialToolResults, options) {
-  const eventStream = new import_ai.EventStream();
+  const eventStream = new import_ai2.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,
-        (event) => pushToolEvent(eventStream, state, event)
-      );
-      resultsById.set(record.toolCallId, record);
-    })
-  ).then(() => {
+  const tracker = createPreemptTracker(options, eventStream, state, resultsById, dispatchedIds);
+  Promise.all(toolCalls.map((toolCall) => tracker.run(toolCall))).then(() => {
     if (!state.finalized) eventStream.close();
   }).catch((err) => {
     if (!state.finalized) eventStream.abort(err instanceof Error ? err : new Error(String(err)));
@@ -1654,12 +2031,13 @@ async function* executeToolCallsParallel(toolCalls, initialToolResults, options)
     }
   } finally {
     options.signal?.removeEventListener("abort", abortHandler);
+    tracker.dispose();
     state.finalized = true;
   }
   const toolResults = buildToolResults(initialToolResults, toolCalls, resultsById, dispatchedIds);
   capToolResults(toolResults, options.maxToolResultChars);
   capTurnToolResults(toolResults, options.maxTurnToolResultChars);
-  return { toolResults, aborted };
+  return { toolResults, aborted, preempted: !aborted && tracker.preempted() };
 }
 function cancelledBeforeStartText(name) {
   return `\`${name}\` was cancelled before it started, so it had no effect. Safe to retry.`;
@@ -1699,8 +2077,8 @@ function capToolResults(toolResults, maxToolResultChars) {
     const originalChars = toolResult.content.length;
     const headChars = Math.floor(max * 0.7);
     const tailChars = max - headChars;
-    const head = (0, import_ai.sliceHead)(toolResult.content, headChars);
-    const tail = (0, import_ai.sliceTail)(toolResult.content, tailChars);
+    const head = (0, import_ai2.sliceHead)(toolResult.content, headChars);
+    const tail = (0, import_ai2.sliceTail)(toolResult.content, tailChars);
     const omitted = originalChars - head.length - tail.length;
     toolResult.content = head + `
 
@@ -1736,11 +2114,11 @@ function capTurnToolResults(toolResults, maxTurnToolResultChars) {
     const headChars = Math.floor(fairShare * 0.7);
     const tailChars = fairShare - headChars;
     const omitted = originalChars - fairShare;
-    toolResult.content = (0, import_ai.sliceHead)(toolResult.content, headChars) + `
+    toolResult.content = (0, import_ai2.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 ...]
 
-` + (0, import_ai.sliceTail)(toolResult.content, tailChars);
+` + (0, import_ai2.sliceTail)(toolResult.content, tailChars);
     toolResult.capped = {
       originalChars: toolResult.capped?.originalChars ?? originalChars,
       keptChars: toolResult.content.length,
@@ -1759,8 +2137,8 @@ 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 head = (0, import_ai.sliceHead)(text, headChars);
-  const tail = (0, import_ai.sliceTail)(text, tailChars);
+  const head = (0, import_ai2.sliceHead)(text, headChars);
+  const tail = (0, import_ai2.sliceTail)(text, tailChars);
   const omitted = text.length - head.length - tail.length;
   return `${head}
 
@@ -1826,6 +2204,19 @@ function sanitizeOrphanedServerTools(messages) {
     break;
   }
 }
+function countMessageChars(messages) {
+  let chars = 0;
+  for (const m of messages) {
+    if (typeof m.content === "string") chars += m.content.length;
+    else if (Array.isArray(m.content)) {
+      for (const p of m.content) {
+        if ("text" in p && typeof p.text === "string") chars += p.text.length;
+        if ("content" in p && typeof p.content === "string") chars += p.content.length;
+      }
+    }
+  }
+  return chars;
+}
 function repairToolPairingAdjacent(messages) {
   for (let i = 0; i < messages.length; i++) {
     const msg = messages[i];
@@ -1896,7 +2287,7 @@ var AgentStream = class {
   rejectResult;
   hasConsumer = false;
   constructor(generator, onDone) {
-    this.events = new import_ai2.EventStream();
+    this.events = new import_ai3.EventStream();
     this.resultPromise = new Promise((resolve, reject) => {
       this.resolveResult = resolve;
       this.rejectResult = reject;
@@ -1942,6 +2333,7 @@ var Agent = class {
   options;
   steeringQueue = [];
   followUpQueue = [];
+  steeringListeners = /* @__PURE__ */ new Set();
   constructor(options) {
     this.options = options;
     if (options.system) {
@@ -1966,9 +2358,14 @@ var Agent = class {
   get running() {
     return this._running;
   }
-  /** Queue a steering message for injection after current tool execution completes. */
+  /**
+   * Queue a steering message. Instant interrupt: if tools are running, the
+   * interruptible ones are preempted right away and the message is injected
+   * before the next model call (the turn continues — unlike abort/Stop).
+   */
   steer(msg) {
     this.steeringQueue.push(msg);
+    for (const listener of [...this.steeringListeners]) listener();
   }
   /** Queue a follow-up message for injection when the agent would otherwise stop. */
   followUp(msg) {
@@ -1988,6 +2385,14 @@ var Agent = class {
         const all = [...callerResult ?? [], ...queued];
         return all.length > 0 ? all : null;
       },
+      onSteeringAvailable: (listener) => {
+        this.steeringListeners.add(listener);
+        const unsubscribeCaller = this.options.onSteeringAvailable?.(listener);
+        return () => {
+          this.steeringListeners.delete(listener);
+          unsubscribeCaller?.();
+        };
+      },
       getFollowUpMessages: async () => {
         const callerResult = await this.options.getFollowUpMessages?.() ?? [];
         const queued = this.followUpQueue.splice(0);
@@ -2005,7 +2410,12 @@ var Agent = class {
 0 && (module.exports = {
   Agent,
   AgentStream,
+  DEFAULT_STREAM_RULE_MAX_RETRIES,
+  DEFAULT_STREAM_RULE_WINDOW_CHARS,
+  JsonEscapeDecoder,
+  StreamRuleMonitor,
   agentLoop,
+  buildStreamRuleReminder,
   cancelledBeforeStartText,
   indeterminateOutcomeText,
   isAbortError,
@@ -2013,6 +2423,7 @@ var Agent = class {
   isContextOverflow,
   isLocalBackendUrl,
   isUsageLimitError,
+  repairToolPairingAdjacent,
   setStreamDiagnostic
 });
 //# sourceMappingURL=index.cjs.map