agent-accelerator 0.3.0 → 0.4.5

package/src/streaming/event-stream.ts

@@ -3,11 +3,49 @@ import type { StreamEvent, AgentResponse } from "../types/response.ts";
 /** Listener invoked for a matching stream event type or `*`. */
 export type StreamEventListener = (event: StreamEvent) => void;
 
+/** Options for AssistantMessageEventStream (Q-29). */
+export interface EventStreamOptions {
+  /**
+   * When false, `partialText`/`partialThinking` cumulative fields are stripped
+   * from events before delivery. Default true for compat (providers attach
+   * cumulative partials; consumers like wrapThinking rely on them).
+   */
+  includePartial?: boolean;
+  /** Max buffered events when no iterator is attached. Default 1000. Oldest dropped. */
+  maxBufferedEvents?: number;
+  /** Max approx bytes for a single delta event. Default 1MB. Oversized dropped. */
+  maxEventBytes?: number;
+}
+
 type Resolver = {
   resolve: (value: IteratorResult<StreamEvent>) => void;
   reject: (err: Error) => void;
 };
 
+/** Default max buffered events (Q-29). */
+export const MAX_BUFFERED_EVENTS = 1000;
+/** Default max approx bytes per delta event (Q-29). */
+export const MAX_EVENT_BYTES = 1_048_576;
+
+function approxEventBytes(event: StreamEvent): number {
+  let n = 0;
+  if (typeof event.delta === "string") n += event.delta.length;
+  if (typeof event.thinkingDelta === "string") n += event.thinkingDelta.length;
+  if (typeof event.partialText === "string") n += event.partialText.length;
+  if (typeof event.partialThinking === "string") n += event.partialThinking.length;
+  return n;
+}
+
+function reportStreamAnomaly(detail: unknown): void {
+  // why: telemetry hook only, never console — streams are hot paths and
+  // logging per-drop would spam and break no-console policy (Q-29/Q-41).
+  try {
+    (globalThis as unknown as { __agentAccelAnomaly?: (d: unknown) => void }).__agentAccelAnomaly?.(detail);
+  } catch {
+    // why: anomaly reporting must never break the stream itself.
+  }
+}
+
 /** Async-iterable event stream returned by Agent.stream and streaming Agent.run. */
 export class AssistantMessageEventStream implements AsyncIterable<StreamEvent> {
   private queue: StreamEvent[] = [];
@@ -20,6 +58,13 @@ export class AssistantMessageEventStream implements AsyncIterable<StreamEvent> {
   private finalResultPromise: Promise<AgentResponse>;
   private resolveFinalResult!: (result: AgentResponse) => void;
   private rejectFinalResult!: (err: Error) => void;
+  private readonly includePartial: boolean;
+  private readonly maxBufferedEvents: number;
+  private readonly maxEventBytes: number;
+  /** First listener exception captured for inspection (Q-29/Q-41). */
+  private listenerError: Error | null = null;
+  /** Count of events dropped by bounds (buffer cap / oversize / unbuffered). */
+  private droppedEvents = 0;
 
   /**
    * Creates an empty event stream. `Agent.stream()` creates and completes
@@ -31,7 +76,16 @@ export class AssistantMessageEventStream implements AsyncIterable<StreamEvent> {
    * stream.on("text_delta", (event) => process.stdout.write(event.delta ?? ""));
    * ```
    */
-  constructor() {
+  constructor(opts?: EventStreamOptions) {
+    this.includePartial = opts?.includePartial !== false;
+    this.maxBufferedEvents =
+      typeof opts?.maxBufferedEvents === "number" && Number.isFinite(opts.maxBufferedEvents) && opts.maxBufferedEvents > 0
+        ? Math.floor(opts.maxBufferedEvents)
+        : MAX_BUFFERED_EVENTS;
+    this.maxEventBytes =
+      typeof opts?.maxEventBytes === "number" && Number.isFinite(opts.maxEventBytes) && opts.maxEventBytes > 0
+        ? Math.floor(opts.maxEventBytes)
+        : MAX_EVENT_BYTES;
     this.finalResultPromise = new Promise<AgentResponse>((resolve, reject) => {
       this.resolveFinalResult = resolve;
       this.rejectFinalResult = reject;
@@ -40,70 +94,128 @@ export class AssistantMessageEventStream implements AsyncIterable<StreamEvent> {
     this.finalResultPromise.catch(() => {});
   }
 
+  /** First listener exception, if any listener threw (stored, never logged). */
+  getListenerError(): Error | null {
+    return this.listenerError;
+  }
+
+  /** Number of events dropped by Q-29 bounds. */
+  getDroppedCount(): number {
+    return this.droppedEvents;
+  }
+
   /** Publishes an event to listeners and async iterators. */
   push(event: StreamEvent): void {
     if (this.finished) return;
 
-    if (event.type === "error") {
-      this.error = (event.error instanceof Error ? event.error : new Error(String(event.error))) ?? new Error("Unknown error in stream");
-      // Reject final result but don't finish iterator yet — let iterators receive error event then fail
-      // Still deliver error event to listeners/consumers before marking finished? Keep consistent with agent-accel: error terminates stream
-      try { this.rejectFinalResult(this.error); } catch {}
+    // Q-29: 1MB oversize guard — drop oversized deltas (no console).
+    if (approxEventBytes(event) > this.maxEventBytes) {
+      this.droppedEvents++;
+      reportStreamAnomaly({ type: "stream_event_oversize", eventType: event.type });
+      return;
     }
 
-    // Trigger registered event listener callbacks
-    const specificListeners = this.listeners.get(event.type);
-    if (specificListeners) {
-      for (const listener of specificListeners) {
-        try { listener(event); } catch {}
-      }
-    }
-    const allListeners = this.listeners.get("*");
-    if (allListeners) {
-      for (const listener of allListeners) {
-        try { listener(event); } catch {}
-      }
+    let out: StreamEvent = event;
+    if (!this.includePartial && (event.partialText !== undefined || event.partialThinking !== undefined)) {
+      out = { ...event };
+      delete (out as { partialText?: unknown }).partialText;
+      delete (out as { partialThinking?: unknown }).partialThinking;
     }
 
-    if (event.type === "error") {
-      // Mark finished after delivering error event, reject pending resolvers
+    if (out.type === "error") {
+      this.error = (out.error instanceof Error ? out.error : new Error(String(out.error))) ?? new Error("Unknown error in stream");
+      // Single error semantic (Q-29): deliver the error event to listeners,
+      // reject result(), mark finished, reject pending iterators, and queue
+      // the error event so a late iterator observes it before failing.
+      this.deliverToListeners(out);
+      try { this.rejectFinalResult(this.error); } catch {
+        // why: rejecting an already-settled promise helper must not throw.
+      }
       this.finished = true;
       while (this.resolvers.length > 0) {
         const r = this.resolvers.shift()!;
-        // First deliver error event if they were waiting, then reject next call
-        // For simplicity, reject immediately — consumer will see error via result() or next()
         r.reject(this.error!);
       }
-      // Also queue error event for later pulls if no resolver
-      if (this.queue.length === 0) this.queue.push(event);
-      else this.queue.push(event);
+      this.enqueueBounded(out);
       return;
     }
 
+    // Trigger registered event listener callbacks
+    this.deliverToListeners(out);
+
     if (this.resolvers.length > 0) {
       const resolver = this.resolvers.shift()!;
-      resolver.resolve({ value: event, done: false });
+      resolver.resolve({ value: out, done: false });
     } else {
-      this.queue.push(event);
+      // No waiter right now (typical between `next()` polls of a burst):
+      // buffer for the iterator with a hard cap (Q-29). Overflow drops the
+      // oldest with an anomaly report — see `enqueueBounded`.
+      this.enqueueBounded(out);
+    }
+  }
+
+  private deliverToListeners(event: StreamEvent): void {
+    const specificListeners = this.listeners.get(event.type);
+    if (specificListeners) {
+      for (const listener of specificListeners) {
+        try { listener(event); } catch (e) {
+          // why: one bad listener must not break the stream or other
+          // listeners; capture the first exception for inspection instead.
+          if (!this.listenerError) {
+            this.listenerError = e instanceof Error ? e : new Error(String(e));
+          }
+        }
+      }
+    }
+    const allListeners = this.listeners.get("*");
+    if (allListeners) {
+      for (const listener of allListeners) {
+        try { listener(event); } catch (e) {
+          // why: same as above — isolate wildcard-listener failures.
+          if (!this.listenerError) {
+            this.listenerError = e instanceof Error ? e : new Error(String(e));
+          }
+        }
+      }
+    }
+  }
+
+  private enqueueBounded(event: StreamEvent): void {
+    this.queue.push(event);
+    while (this.queue.length > this.maxBufferedEvents) {
+      // Drop oldest buffered event to bound memory (Q-29). Error events are
+      // never dropped: if the oldest is an error, drop the next-oldest
+      // non-error instead; if the queue is all errors, keep them.
+      if (this.queue[0]?.type === "error") {
+        const idx = this.queue.findIndex((e) => e.type !== "error");
+        if (idx === -1) break;
+        this.queue.splice(idx, 1);
+      } else {
+        this.queue.shift();
+      }
+      this.droppedEvents++;
+      reportStreamAnomaly({ type: "stream_buffer_overflow" });
     }
   }
 
   /** Completes the stream and resolves result() with the final response. */
   end(finalResponse?: AgentResponse): void {
     if (this.finished) return;
+    if (!finalResponse) {
+      // Q-29: never hang result() — ending without a response is a
+      // programming error, so fail loudly instead of leaving consumers
+      // waiting forever.
+      this.fail(new Error("end() requires response"));
+      return;
+    }
     this.finished = true;
 
-    if (finalResponse) {
-      this.resolveFinalResult(finalResponse);
-    } else {
-      // Resolve with empty if no response — should not happen, but prevent hanging
-      // Do not reject; just finish
-    }
+    this.resolveFinalResult(finalResponse);
 
     // Flush any waiting resolvers as done
     while (this.resolvers.length > 0) {
       const resolver = this.resolvers.shift()!;
-      resolver.resolve({ value: undefined as any, done: true });
+      resolver.resolve({ value: undefined as unknown as StreamEvent, done: true });
     }
   }
 
@@ -122,7 +234,9 @@ export class AssistantMessageEventStream implements AsyncIterable<StreamEvent> {
   /** Registers a callback invoked once on cancel(). Returns an unsubscribe fn. */
   onCancel(handler: () => void): () => void {
     if (this.cancelled) {
-      try { handler(); } catch {}
+      try { handler(); } catch {
+        // why: a throwing cancel handler must not break the canceller.
+      }
       return () => {};
     }
     this.cancelHandlers.add(handler);
@@ -135,7 +249,9 @@ export class AssistantMessageEventStream implements AsyncIterable<StreamEvent> {
     if (this.finished || this.cancelled) return;
     this.cancelled = true;
     for (const h of [...this.cancelHandlers]) {
-      try { h(); } catch {}
+      try { h(); } catch {
+        // why: isolate faulty cancel handlers so every handler still runs.
+      }
     }
     this.cancelHandlers.clear();
     const err = reason instanceof Error ? reason : null;
@@ -174,7 +290,7 @@ export class AssistantMessageEventStream implements AsyncIterable<StreamEvent> {
           iteratorDone = true;
           this.cancel();
         }
-        return Promise.resolve({ value: undefined as any, done: true });
+        return Promise.resolve({ value: undefined as unknown as StreamEvent, done: true });
       },
       throw: (err?: unknown): Promise<IteratorResult<StreamEvent>> => {
         if (!iteratorDone) {
@@ -186,10 +302,9 @@ export class AssistantMessageEventStream implements AsyncIterable<StreamEvent> {
       next: (): Promise<IteratorResult<StreamEvent>> => {
         if (this.queue.length > 0) {
           const value = this.queue.shift()!;
-          // If queued error, next call should reject, but deliver error event first?
-          // Deliver error event then on next call reject
+          // If queued error, deliver the error event first; the NEXT next()
+          // call rejects so consumers observe the event before the failure.
           if (value.type === "error" && this.error) {
-            // Return error event as value, next next() will reject
             return Promise.resolve({ value, done: false });
           }
           return Promise.resolve({ value, done: false });
@@ -199,7 +314,7 @@ export class AssistantMessageEventStream implements AsyncIterable<StreamEvent> {
           if (this.error) {
             return Promise.reject(this.error);
           }
-          return Promise.resolve({ value: undefined as any, done: true });
+          return Promise.resolve({ value: undefined as unknown as StreamEvent, done: true });
         }
 
         return new Promise<IteratorResult<StreamEvent>>((resolve, reject) => {

package/src/tools/executor.ts

@@ -5,6 +5,7 @@ import type {
   ToolExecutionContext,
 } from "../types/tool.ts";
 import { toJsonSafe } from "../utils/serialization.ts";
+import { ConfigError } from "../types/errors.ts";
 
 export interface ExecuteToolsOptions {
   tools: Record<string, ToolDefinition>;
@@ -48,6 +49,180 @@ export function normalizeToolName(name: string): string {
     .toLowerCase();
 }
 
+/** Default cap for string tool results kept for model context. */
+export const DEFAULT_MAX_RESULT_CHARS = 20000;
+
+/** Identical-call repeats blocked once the per-fingerprint count reaches this. */
+export const REPEAT_BLOCK_THRESHOLD = 3;
+
+/**
+ * True when a tool call carries only `{ raw: string }` arguments — the marker
+ * shape produced by `parseStreamedToolArguments` when streamed JSON chunks
+ * never parsed to an object (truncated/incomplete arguments). Such calls must
+ * NOT execute: the model must retry with complete JSON.
+ *
+ * @example `if (isTruncatedToolCall(call)) return truncatedError(call);`
+ */
+export function isTruncatedToolCall(call: ToolCallRecord): boolean {
+  const args = call?.arguments;
+  if (!args || typeof args !== "object" || Array.isArray(args)) return false;
+  const keys = Object.keys(args);
+  return (
+    keys.length === 1 &&
+    keys[0] === "raw" &&
+    typeof (args as Record<string, unknown>).raw === "string"
+  );
+}
+
+/**
+ * Throws {@link ConfigError} when two distinct tool entries normalize to the
+ * same name (case/format-insensitive via {@link normalizeToolName}), which
+ * would otherwise make model tool calls ambiguous.
+ */
+export function assertNoToolCollisions(
+  tools: Record<string, ToolDefinition>
+): void {
+  if (!tools) return;
+  const seen = new Map<string, string>();
+  for (const [key, definition] of Object.entries(tools)) {
+    const declared = definition?.name || key;
+    for (const candidate of new Set([key, declared])) {
+      const normalized = normalizeToolName(candidate);
+      const previous = seen.get(normalized);
+      if (previous !== undefined && previous !== key) {
+        throw new ConfigError(
+          `Tool name collision: '${previous}' and '${key}' both normalize to '${normalized}'. Rename one tool so model calls are unambiguous.`
+        );
+      }
+      seen.set(normalized, key);
+    }
+  }
+}
+
+/**
+ * Redacts secrets and machine-local details from an error message before it
+ * is sent back to the model: credentials in URLs/connection strings
+ * (`scheme://...@` → `scheme://[redacted]@`) and absolute file paths
+ * (`/home/...`, `/Users/...`, `C:\...` → `[redacted-path]`).
+ */
+export function sanitizeErrorMessage(message: string): string {
+  let out = message;
+  out = out.replace(
+    /([A-Za-z][A-Za-z0-9+.-]*:\/\/)[^\s"'`@]+@/g,
+    "$1[redacted]@"
+  );
+  out = out.replace(/\/home\/[^\s"'`:;,)]*/g, "[redacted-path]");
+  out = out.replace(/\/Users\/[^\s"'`:;,)]*/g, "[redacted-path]");
+  out = out.replace(/[A-Za-z]:\\[^\s"'`:;,)]*/g, "[redacted-path]");
+  return out;
+}
+
+function resultCharLimit(toolDef: ToolDefinition): number {
+  const configured = integerOption((toolDef as any).maxResultChars);
+  return configured && configured > 0 ? configured : DEFAULT_MAX_RESULT_CHARS;
+}
+
+function truncateResultString(value: string, limit: number): string {
+  if (value.length <= limit) return value;
+  return value.slice(0, limit) + `\n[Truncated: showing ${limit} of ${value.length} chars]`;
+}
+
+/**
+ * Drops `stack` from an Error-shaped sanitized result for model context.
+ * Keeps `{ name, message }` plus any custom keys; nested values untouched.
+ */
+function stripTopLevelErrorStack(value: unknown): unknown {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return value;
+  const record = value as Record<string, unknown>;
+  if (
+    typeof record.name === "string" &&
+    typeof record.message === "string" &&
+    "stack" in record
+  ) {
+    const { stack: _dropped, ...rest } = record;
+    return rest;
+  }
+  return value;
+}
+
+/** Stable serialization for repeat-guard fingerprints (key order independent). */
+function stableSerialize(value: unknown, seen = new Set<unknown>()): string {
+  if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+  if (seen.has(value)) return "[Circular]";
+  seen.add(value);
+  try {
+    if (Array.isArray(value)) {
+      return `[${value.map((item) => stableSerialize(item, seen)).join(",")}]`;
+    }
+    const record = value as Record<string, unknown>;
+    const body = Object.keys(record)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${stableSerialize(record[key], seen)}`)
+      .join(",");
+    return `{${body}}`;
+  } finally {
+    seen.delete(value);
+  }
+}
+
+/** Fingerprint identifying an identical tool call (name + canonical args). */
+export function toolCallFingerprint(call: ToolCallRecord): string {
+  return `${call.name}\u0000${stableSerialize(call.arguments ?? {})}`;
+}
+
+/**
+ * Whether a tool definition allows identical repeats across consecutive
+ * turns. Explicit `repeatable` wins; otherwise idempotent tools default to
+ * repeatable, side-effecting tools do not.
+ */
+export function isRepeatableTool(toolDef: ToolDefinition): boolean {
+  const explicit = (toolDef as any).repeatable;
+  if (typeof explicit === "boolean") return explicit;
+  return (toolDef as any).idempotent === true;
+}
+
+/**
+ * Repeat-guard helper for the agent loop (which owns consecutive-turn state).
+ * Tracks per-fingerprint occurrence counts in `countMap`: a first sighting
+ * records count 1 and never blocks; a fingerprint already present in
+ * `fingerprints` (the previous turn's set) increments and blocks once the
+ * count reaches {@link REPEAT_BLOCK_THRESHOLD} (3). Callers must skip this
+ * check for repeatable tools (see {@link isRepeatableTool}); this helper
+ * itself stays tool-agnostic for backward compatibility.
+ */
+export function shouldBlockRepeat(
+  fingerprints: Set<string>,
+  call: ToolCallRecord,
+  countMap: Map<string, number>
+): boolean {
+  const fingerprint = toolCallFingerprint(call);
+  if (!fingerprints.has(fingerprint)) {
+    if (!countMap.has(fingerprint)) countMap.set(fingerprint, 1);
+    return false;
+  }
+  const next = (countMap.get(fingerprint) ?? 1) + 1;
+  countMap.set(fingerprint, next);
+  return next >= REPEAT_BLOCK_THRESHOLD;
+}
+
+/**
+ * Builds the synthetic blocked result for a repeat-guarded call. The
+ * machine-readable code lives at `(result as any).errorCode` while the human
+ * prefix keeps plain-string consumers working.
+ */
+export function makeRepeatBlockedResult(call: ToolCallRecord): ToolResultRecord {
+  const message =
+    `repeat_blocked: Tool '${call.name}' was called again with identical arguments. ` +
+    "The previous result is already available; reuse it or call the tool with different arguments.";
+  return {
+    id: call.id,
+    name: call.name,
+    result: { message, errorCode: "repeat_blocked" },
+    isError: true,
+    durationMs: 1,
+  };
+}
+
 function levenshtein(a: string, b: string): number {
   const row = Array.from({ length: b.length + 1 }, (_, i) => i);
   for (let i = 1; i <= a.length; i++) {
@@ -149,16 +324,19 @@ class Semaphore {
   }
 }
 
+/**
+ * True for retry-worthy failures: explicit opt-in flags (`transient` /
+ * `retryable`), retryable HTTP statuses, or retryable network codes. Never
+ * matches on message text — message content is untrusted and locale-fragile.
+ */
 function isTransientError(error: any): boolean {
   if (!error) return false;
-  if (error.transient === true || error.code === "ETIMEDOUT") return true;
+  if (error.transient === true || error.retryable === true) return true;
   const status = Number(error.status ?? error.statusCode ?? error.response?.status);
   if ([408, 425, 429, 500, 502, 503, 504].includes(status)) return true;
   const code = String(error.code || "").toUpperCase();
-  if (["ECONNRESET", "ECONNREFUSED", "EAI_AGAIN", "UND_ERR_CONNECT_TIMEOUT", "EPIPE"].includes(code)) return true;
-  return /(?:timed? ?out|temporar(?:y|ily)|connection reset|connection refused|service unavailable|rate limit|\b5\d\d\b)/i.test(
-    String(error.message || error)
-  );
+  if (["ECONNRESET", "ECONNREFUSED", "EAI_AGAIN", "ETIMEDOUT", "EPIPE", "UND_ERR_CONNECT_TIMEOUT"].includes(code)) return true;
+  return false;
 }
 
 function waitForRetry(ms: number, signal?: AbortSignal): Promise<void> {
@@ -236,6 +414,7 @@ export async function executeToolCalls(
   options: ExecuteToolsOptions
 ): Promise<ToolResultRecord[]> {
   const { tools, toolCalls, agentName, parallel = true, signal, sessionId, onSubagentEvent } = options;
+  assertNoToolCollisions(tools);
   const globalSemaphore = new Semaphore(DEFAULT_TOOL_CONCURRENCY);
   const perToolSemaphores = new Map<string, Semaphore>();
 
@@ -253,6 +432,23 @@ export async function executeToolCalls(
 
   const runSingle = async (call: ToolCallRecord): Promise<ToolResultRecord> => {
     const startTime = nowMs();
+
+    // Truncated streamed arguments (Q-12): the `{ raw }` marker means the
+    // provider's partial JSON never parsed. Never execute or overwrite wire
+    // finishReason here — return a synthetic error so the model retries with
+    // complete JSON.
+    if (isTruncatedToolCall(call)) {
+      return {
+        id: call.id,
+        name: call.name,
+        result:
+          `Error: Tool '${call.name}' arguments are truncated or incomplete and could not be parsed. ` +
+          "Call the tool again with the complete JSON arguments. Do not explain the error, just retry the call.",
+        isError: true,
+        durationMs: elapsedMs(startTime),
+      };
+    }
+
     const resolved = resolveTool(tools, call.name);
     const toolDef = resolved.definition;
 
@@ -320,11 +516,15 @@ export async function executeToolCalls(
       }
 
       const configuredTries = integerOption(toolDef.maxTries);
-      // A positive value is the total attempt count. 0/omitted falls back to
-      // a bounded default: an unbounded retry loop on a persistently failing
-      // dependency (e.g. steady 503/429) would hang the agent loop forever,
-      // so callers opt into more attempts explicitly via maxTries.
-      const maxAttempts = configuredTries && configuredTries > 0 ? configuredTries : 3;
+      // Total attempt count. Default is a single attempt: only tools marked
+      // idempotent opt into a bounded retry default (3 attempts). An explicit
+      // maxTries overrides both defaults. An unbounded retry loop on a
+      // persistently failing dependency (e.g. steady 503/429) would hang the
+      // agent loop forever, so retries are always bounded.
+      // Attempts run serially in the while loop below — never concurrently —
+      // so a non-idempotent tool cannot execute twice at the same time.
+      const isIdempotent = (toolDef as any).idempotent === true;
+      const maxAttempts = configuredTries && configuredTries > 0 ? configuredTries : (isIdempotent ? 3 : 1);
       const timeoutMs = numericOption(toolDef.timeoutMs);
       // Telemetry starts when the tool body is about to run, excluding queue
       // wait and schema validation. Retries/backoff remain part of this call.
@@ -339,26 +539,59 @@ export async function executeToolCalls(
         } catch (err: any) {
           if (signal?.aborted) throw new Error("Tool execution aborted");
           if (!isTransientError(err) || attempt >= maxAttempts) throw err;
-          // A timeout is already a deliberate per-attempt deadline. Retrying
-          // it forever by default would make timeoutMs ineffective; callers
-          // can opt into timeout retries with an explicit maxTries value.
+          // A timeout is a deliberate per-attempt deadline, not a parent
+          // cancellation (which rejects via the abort signal instead and is
+          // never retried). Retrying timeouts by default would make timeoutMs
+          // ineffective; callers opt into timeout retries with explicit
+          // maxTries. Note ctx.signal is cooperative: the timeout races the
+          // tool body, but a tool that ignores the signal still resolves.
           if (err?.code === "ETIMEDOUT" && (!configuredTries || configuredTries <= 0)) throw err;
           await waitForRetry(Math.min(30_000, 250 * 2 ** Math.min(attempt - 1, 7)), signal);
         }
       }
 
+      // Undefined means "no value", serialized null-safe as "null" (changed
+      // from the legacy "Success" marker so model context stays valid JSON).
+      if (rawResult === undefined) {
+        return {
+          id: call.id,
+          name: resolved.name,
+          result: "null",
+          isError: false,
+          durationMs: elapsedMs(executionStartTime),
+        };
+      }
+      // Stack traces stay in server logs, not model context: keep
+      // { name, message } plus custom keys, drop stack.
+      let safeResult = stripTopLevelErrorStack(toJsonSafe(rawResult));
+      if (typeof safeResult === "string") {
+        safeResult = truncateResultString(safeResult, resultCharLimit(toolDef));
+      }
       return {
         id: call.id,
         name: resolved.name,
-        result: rawResult !== undefined ? toJsonSafe(rawResult) : "Success",
+        result: safeResult,
         isError: false,
         durationMs: elapsedMs(executionStartTime),
       };
     } catch (err: any) {
+      // Never leak secrets/paths to the model. A per-tool redactError hook
+      // wins; otherwise sanitize the message (credentials, file paths).
+      let message: string;
+      const redactError = (toolDef as any)?.redactError;
+      if (typeof redactError === "function") {
+        try {
+          message = String(redactError(err));
+        } catch {
+          message = sanitizeErrorMessage(err?.message || String(err));
+        }
+      } else {
+        message = sanitizeErrorMessage(err?.message || String(err));
+      }
       return {
         id: call.id,
         name: call.name,
-        result: `Error executing ${call.name}: ${err?.message || String(err)}`,
+        result: `Error executing ${call.name}: ${message}`,
         isError: true,
         durationMs: elapsedMs(executionStartTime),
       };