@witqq/agent-sdk 0.7.0 → 0.8.0

package/dist/backends/claude.js

@@ -1,4 +1,42 @@
-// src/types.ts
+// src/types/errors.ts
+var RECOVERABLE_CODES = /* @__PURE__ */ new Set([
+  "TIMEOUT" /* TIMEOUT */,
+  "RATE_LIMIT" /* RATE_LIMIT */,
+  "NETWORK" /* NETWORK */,
+  "TOOL_EXECUTION" /* TOOL_EXECUTION */,
+  "MODEL_OVERLOADED" /* MODEL_OVERLOADED */,
+  "PROVIDER_ERROR" /* PROVIDER_ERROR */
+]);
+function isRecoverableErrorCode(code) {
+  return RECOVERABLE_CODES.has(code);
+}
+function classifyAgentError(error) {
+  const msg = (error instanceof Error ? error.message : error).toLowerCase();
+  if (msg.includes("timeout") || msg.includes("timed out") || msg.includes("timedout") || msg.includes("etimedout")) {
+    return "TIMEOUT" /* TIMEOUT */;
+  }
+  if (msg.includes("rate limit") || msg.includes("rate_limit") || msg.includes("429") || msg.includes("too many requests")) {
+    return "RATE_LIMIT" /* RATE_LIMIT */;
+  }
+  if (msg.includes("unauthorized") || msg.includes("401") || msg.includes("auth") && (msg.includes("expired") || msg.includes("invalid") || msg.includes("denied") || msg.includes("failed"))) {
+    return "AUTH_EXPIRED" /* AUTH_EXPIRED */;
+  }
+  if (msg.includes("econnrefused") || msg.includes("econnreset") || msg.includes("enotfound") || msg.includes("network") || msg.includes("fetch failed") || msg.includes("socket hang up")) {
+    return "NETWORK" /* NETWORK */;
+  }
+  if (msg.includes("subprocess") || msg.includes("process exited") || msg.includes("spawn") || msg.includes("enoent") || msg.includes("killed")) {
+    return "DEPENDENCY_MISSING" /* DEPENDENCY_MISSING */;
+  }
+  if (msg.includes("abort") || msg.includes("cancel")) {
+    return "ABORTED" /* ABORTED */;
+  }
+  if (msg.includes("500") || msg.includes("502") || msg.includes("503") || msg.includes("internal server error") || msg.includes("service unavailable") || msg.includes("bad gateway") || msg.includes("overloaded")) {
+    return "PROVIDER_ERROR" /* PROVIDER_ERROR */;
+  }
+  return "PROVIDER_ERROR" /* PROVIDER_ERROR */;
+}
+
+// src/types/guards.ts
 function getTextContent(content) {
   if (typeof content === "string") return content;
   return content.filter((p) => p.type === "text").map((p) => p.text).join("\n");
@@ -8,9 +46,18 @@ function getTextContent(content) {
 var AgentSDKError = class extends Error {
   /** @internal Marker for cross-bundle identity checks */
   _agentSDKError = true;
+  /** Machine-readable error code. Prefer values from the ErrorCode enum. */
+  code;
+  /** Whether this error is safe to retry */
+  retryable;
+  /** HTTP status code hint for error classification */
+  httpStatus;
   constructor(message, options) {
     super(message, options);
     this.name = "AgentSDKError";
+    this.code = options?.code;
+    this.retryable = options?.retryable ?? false;
+    this.httpStatus = options?.httpStatus;
   }
   /** Check if an error is an AgentSDKError (works across bundled copies) */
   static is(error) {
@@ -19,28 +66,41 @@ var AgentSDKError = class extends Error {
 };
 var ReentrancyError = class extends AgentSDKError {
   constructor() {
-    super("Agent is already running. Await the current run before starting another.");
+    super("Agent is already running. Await the current run before starting another.", {
+      code: "REENTRANCY" /* REENTRANCY */
+    });
     this.name = "ReentrancyError";
   }
 };
 var DisposedError = class extends AgentSDKError {
   constructor(entity) {
-    super(`${entity} has been disposed and cannot be used.`);
+    super(`${entity} has been disposed and cannot be used.`, {
+      code: "DISPOSED" /* DISPOSED */
+    });
     this.name = "DisposedError";
   }
 };
 var SubprocessError = class extends AgentSDKError {
   constructor(message, options) {
-    super(message, options);
+    super(message, { ...options, code: "DEPENDENCY_MISSING" /* DEPENDENCY_MISSING */ });
     this.name = "SubprocessError";
   }
 };
 var AbortError = class extends AgentSDKError {
   constructor() {
-    super("Agent run was aborted.");
+    super("Agent run was aborted.", { code: "ABORTED" /* ABORTED */ });
     this.name = "AbortError";
   }
 };
+var ActivityTimeoutError = class extends AgentSDKError {
+  constructor(timeoutMs) {
+    super(`Stream activity timeout: no event received within ${timeoutMs}ms.`, {
+      code: "TIMEOUT" /* TIMEOUT */,
+      retryable: true
+    });
+    this.name = "ActivityTimeoutError";
+  }
+};
 
 // src/base-agent.ts
 var BaseAgent = class {
@@ -48,6 +108,7 @@ var BaseAgent = class {
   abortController = null;
   config;
   _cleanupExternalSignal = null;
+  _streamMiddleware = [];
   /** CLI session ID for persistent mode. Override in backends that support it. */
   get sessionId() {
     return void 0;
@@ -63,8 +124,11 @@ var BaseAgent = class {
     this.state = "running";
     try {
       const messages = [{ role: "user", content: prompt }];
-      const result = await this.executeRun(messages, options, ac.signal);
-      this.enrichAndNotifyUsage(result);
+      const result = await this.withRetry(
+        () => this.executeRun(messages, options, ac.signal),
+        options
+      );
+      this.enrichAndNotifyUsage(result, options);
       return result;
     } finally {
       this.cleanupRun();
@@ -76,8 +140,11 @@ var BaseAgent = class {
     const ac = this.createAbortController(options?.signal);
     this.state = "running";
     try {
-      const result = await this.executeRun(messages, options, ac.signal);
-      this.enrichAndNotifyUsage(result);
+      const result = await this.withRetry(
+        () => this.executeRun(messages, options, ac.signal),
+        options
+      );
+      this.enrichAndNotifyUsage(result, options);
       return result;
     } finally {
       this.cleanupRun();
@@ -90,13 +157,11 @@ var BaseAgent = class {
     this.state = "running";
     try {
       const messages = [{ role: "user", content: prompt }];
-      const result = await this.executeRunStructured(
-        messages,
-        schema,
-        options,
-        ac.signal
+      const result = await this.withRetry(
+        () => this.executeRunStructured(messages, schema, options, ac.signal),
+        options
       );
-      this.enrichAndNotifyUsage(result);
+      this.enrichAndNotifyUsage(result, options);
       return result;
     } finally {
       this.cleanupRun();
@@ -109,8 +174,10 @@ var BaseAgent = class {
     this.state = "streaming";
     try {
       const messages = [{ role: "user", content: prompt }];
-      const enriched = this.enrichStream(this.executeStream(messages, options, ac.signal));
-      yield* this.heartbeatStream(enriched);
+      yield* this.streamWithRetry(
+        () => this.applyStreamPipeline(this.executeStream(messages, options, ac.signal), options, ac),
+        options
+      );
     } finally {
       this.cleanupRun();
     }
@@ -121,12 +188,37 @@ var BaseAgent = class {
     const ac = this.createAbortController(options?.signal);
     this.state = "streaming";
     try {
-      const enriched = this.enrichStream(this.executeStream(messages, options, ac.signal));
-      yield* this.heartbeatStream(enriched);
+      yield* this.streamWithRetry(
+        () => this.applyStreamPipeline(this.executeStream(messages, options, ac.signal), options, ac),
+        options
+      );
     } finally {
       this.cleanupRun();
     }
   }
+  /** Register a stream middleware. Applied in registration order after built-in transforms. */
+  addStreamMiddleware(middleware) {
+    this.guardDisposed();
+    this._streamMiddleware.push(middleware);
+  }
+  /** Apply built-in transforms (enrich→timeout→heartbeat) then custom middleware */
+  async *applyStreamPipeline(source, options, ac) {
+    let stream = this.enrichStream(source, options);
+    stream = this.activityTimeoutStream(stream, options?.activityTimeoutMs, ac);
+    stream = this.heartbeatStream(stream);
+    if (this._streamMiddleware.length > 0) {
+      const ctx = {
+        model: options.model,
+        backend: this.backendName,
+        abortController: ac,
+        config: Object.freeze({ ...this.config })
+      };
+      for (const mw of this._streamMiddleware) {
+        stream = mw(stream, ctx);
+      }
+    }
+    yield* stream;
+  }
   abort() {
     if (this.abortController) {
       this.abortController.abort();
@@ -149,26 +241,109 @@ var BaseAgent = class {
     this.abort();
     this.state = "disposed";
   }
+  // ─── Retry Logic ─────────────────────────────────────────────
+  /** Check if an error should be retried given the retry configuration. */
+  isRetryableError(error, retry) {
+    if (error instanceof AbortError || error instanceof ReentrancyError || error instanceof DisposedError) {
+      return false;
+    }
+    if (AgentSDKError.is(error)) {
+      if (retry.retryableErrors && retry.retryableErrors.length > 0 && error.code) {
+        return retry.retryableErrors.includes(error.code);
+      }
+      if (error.retryable) return true;
+      if (error.code) return isRecoverableErrorCode(error.code);
+    }
+    return false;
+  }
+  /** Execute a function with retry logic per RetryConfig. */
+  async withRetry(fn, options) {
+    const retry = options?.retry;
+    if (!retry || !retry.maxRetries || retry.maxRetries <= 0) {
+      return fn();
+    }
+    const maxRetries = retry.maxRetries;
+    const initialDelay = retry.initialDelayMs ?? 1e3;
+    const multiplier = retry.backoffMultiplier ?? 2;
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        return await fn();
+      } catch (err) {
+        lastError = err;
+        if (attempt >= maxRetries || !this.isRetryableError(err, retry)) {
+          throw err;
+        }
+        const delay = initialDelay * Math.pow(multiplier, attempt);
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        if (options?.signal?.aborted || this.abortController?.signal.aborted) {
+          throw err;
+        }
+      }
+    }
+    throw lastError;
+  }
+  /** Execute a stream factory with pre-stream retry: retries until first event, then committed. */
+  async *streamWithRetry(factory, options) {
+    const retry = options?.retry;
+    if (!retry || !retry.maxRetries || retry.maxRetries <= 0) {
+      yield* factory();
+      return;
+    }
+    const maxRetries = retry.maxRetries;
+    const initialDelay = retry.initialDelayMs ?? 1e3;
+    const multiplier = retry.backoffMultiplier ?? 2;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        const stream = factory();
+        const iterator = stream[Symbol.asyncIterator]();
+        const first = await iterator.next();
+        if (first.done) return;
+        yield first.value;
+        while (true) {
+          const next = await iterator.next();
+          if (next.done) break;
+          yield next.value;
+        }
+        return;
+      } catch (err) {
+        if (attempt >= maxRetries || !this.isRetryableError(err, retry)) {
+          throw err;
+        }
+        const delay = initialDelay * Math.pow(multiplier, attempt);
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        if (options?.signal?.aborted || this.abortController?.signal.aborted) {
+          throw err;
+        }
+      }
+    }
+  }
+  // ─── CallOptions Resolution ──────────────────────────────────
+  /** Resolve tools to use for this call (per-call override > config default) */
+  resolveTools(options) {
+    return options?.tools ?? this.config.tools ?? [];
+  }
   // ─── Usage Enrichment ───────────────────────────────────────────
   /** Enrich result usage with model/backend and fire onUsage callback */
-  enrichAndNotifyUsage(result) {
+  enrichAndNotifyUsage(result, options) {
     if (result.usage) {
       result.usage = {
         ...result.usage,
-        model: this.config.model,
+        model: options.model,
         backend: this.backendName
       };
       this.callOnUsage(result.usage);
     }
   }
   /** Wrap a stream to enrich usage_update events and fire onUsage callback */
-  async *enrichStream(source) {
+  async *enrichStream(source, options) {
+    const model = options.model;
     for await (const event of source) {
       if (event.type === "usage_update") {
         const usage = {
           promptTokens: event.promptTokens,
           completionTokens: event.completionTokens,
-          model: this.config.model,
+          model,
           backend: this.backendName
         };
         this.callOnUsage(usage);
@@ -238,6 +413,35 @@ var BaseAgent = class {
       heartbeatResolve = null;
     }
   }
+  // ─── Activity Timeout ────────────────────────────────────────
+  /** Wrap a stream to abort on inactivity. Resets timer on every event.
+   *  When timeoutMs is not set, passes through directly. */
+  async *activityTimeoutStream(source, timeoutMs, ac) {
+    if (!timeoutMs || timeoutMs <= 0) {
+      yield* source;
+      return;
+    }
+    const iterator = source[Symbol.asyncIterator]();
+    let timerId;
+    try {
+      while (true) {
+        const timeoutPromise = new Promise((_, reject) => {
+          timerId = setTimeout(() => reject(new ActivityTimeoutError(timeoutMs)), timeoutMs);
+        });
+        const result = await Promise.race([iterator.next(), timeoutPromise]);
+        clearTimeout(timerId);
+        if (result.done) break;
+        yield result.value;
+      }
+    } catch (err) {
+      if (err instanceof ActivityTimeoutError) {
+        ac.abort(err);
+      }
+      throw err;
+    } finally {
+      clearTimeout(timerId);
+    }
+  }
   // ─── Guards ───────────────────────────────────────────────────
   guardReentrancy() {
     if (this.state === "running" || this.state === "streaming") {
@@ -336,6 +540,61 @@ function extractSchemaFromDef(schema) {
   }
 }
 
+// src/backends/shared.ts
+function extractLastUserPrompt(messages) {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i];
+    if (msg.role === "user") {
+      return getTextContent(msg.content);
+    }
+  }
+  return "";
+}
+function serializeToolCall(tc) {
+  const args = typeof tc.args === "string" ? tc.args : JSON.stringify(tc.args);
+  return `  Tool call: ${tc.name}(${args})`;
+}
+function serializeToolResult(tr) {
+  const result = typeof tr.result === "string" ? tr.result : JSON.stringify(tr.result);
+  const prefix = tr.isError ? "[ERROR] " : "";
+  return `  ${tr.name} \u2192 ${prefix}${result}`;
+}
+function buildContextualPrompt(messages) {
+  if (messages.length <= 1) {
+    return extractLastUserPrompt(messages);
+  }
+  const history = messages.slice(0, -1).map((msg) => {
+    if (msg.role === "user") {
+      return `User: ${msg.content ? getTextContent(msg.content) : ""}`;
+    }
+    if (msg.role === "tool" && msg.toolResults) {
+      const results = msg.toolResults.map(serializeToolResult).join("\n");
+      return `Tool results:
+${results}`;
+    }
+    if (msg.role === "assistant") {
+      const parts = [];
+      const thinking = msg.thinking;
+      if (thinking) {
+        parts.push(`[reasoning: ${thinking}]`);
+      }
+      const text2 = msg.content ? getTextContent(msg.content) : "";
+      if (text2) parts.push(text2);
+      if (msg.toolCalls && msg.toolCalls.length > 0) {
+        parts.push(msg.toolCalls.map(serializeToolCall).join("\n"));
+      }
+      return `Assistant: ${parts.join("\n")}`;
+    }
+    const text = msg.content ? getTextContent(msg.content) : "";
+    return `${msg.role}: ${text}`;
+  }).join("\n");
+  const lastPrompt = extractLastUserPrompt(messages);
+  return `Conversation history:
+${history}
+
+User: ${lastPrompt}`;
+}
+
 // src/backends/claude.ts
 var MCP_SERVER_NAME = "agent-sdk-tools";
 var MCP_TOOL_PREFIX = `mcp__${MCP_SERVER_NAME}__`;
@@ -345,12 +604,12 @@ function mcpToolName(toolName) {
 function stripMcpPrefix(name) {
   return name.startsWith(MCP_TOOL_PREFIX) ? name.slice(MCP_TOOL_PREFIX.length) : name;
 }
-var sdkModule = null;
+var CLAUDE_INTERNAL_TOOL_NAMES = /* @__PURE__ */ new Set(["AskUserQuestion"]);
+var _sdkMock = null;
 async function loadSDK() {
-  if (sdkModule) return sdkModule;
+  if (_sdkMock) return _sdkMock;
   try {
-    sdkModule = await import('@anthropic-ai/claude-agent-sdk');
-    return sdkModule;
+    return await import('@anthropic-ai/claude-agent-sdk');
   } catch {
     throw new SubprocessError(
       "@anthropic-ai/claude-agent-sdk is not installed. Install it: npm install @anthropic-ai/claude-agent-sdk"
@@ -358,16 +617,35 @@ async function loadSDK() {
   }
 }
 function _injectSDK(mock) {
-  sdkModule = mock;
+  _sdkMock = mock;
 }
 function _resetSDK() {
-  sdkModule = null;
+  _sdkMock = null;
 }
 var ANTHROPIC_MODELS_URL = "https://api.anthropic.com/v1/models";
 var ANTHROPIC_API_VERSION = "2023-06-01";
 var ANTHROPIC_OAUTH_BETA = "oauth-2025-04-20";
-function buildMcpServer(sdk, tools, toolResultCapture) {
-  if (tools.length === 0) return void 0;
+function normalizeAskUserInput(args) {
+  if (typeof args.question === "string") {
+    return {
+      question: args.question,
+      choices: Array.isArray(args.choices) ? args.choices : void 0,
+      allowFreeform: args.allowFreeform !== false
+    };
+  }
+  const questions = args.questions;
+  if (questions && questions.length > 0) {
+    const first = questions[0];
+    return {
+      question: first.question,
+      choices: first.options?.map((o) => o.label),
+      allowFreeform: true
+    };
+  }
+  return { question: JSON.stringify(args), allowFreeform: true };
+}
+function buildMcpServer(sdk, tools, toolResultCapture, onAskUser) {
+  if (tools.length === 0 && !onAskUser) return void 0;
   const mcpTools = tools.map((tool) => {
     const zodSchema = tool.parameters;
     const inputSchema = zodSchema.shape ?? zodToJsonSchema(tool.parameters);
@@ -391,6 +669,39 @@ function buildMcpServer(sdk, tools, toolResultCapture) {
       }
     );
   });
+  if (onAskUser) {
+    const askUserTool = sdk.tool(
+      "ask_user",
+      "Ask the user a question and wait for their response",
+      {
+        question: { type: "string", description: "The question to ask the user" },
+        choices: {
+          type: "array",
+          items: { type: "string" },
+          description: "Optional list of choices for multiple choice"
+        },
+        questions: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              question: { type: "string" },
+              options: { type: "array", items: { type: "object", properties: { label: { type: "string" } } } }
+            }
+          },
+          description: "Alternative nested question format"
+        }
+      },
+      async (args) => {
+        const normalized = normalizeAskUserInput(args);
+        const response = await onAskUser(normalized, AbortSignal.timeout(3e5));
+        return {
+          content: [{ type: "text", text: response.answer }]
+        };
+      }
+    );
+    mcpTools.push(askUserTool);
+  }
   return sdk.createSdkMcpServer({
     name: MCP_SERVER_NAME,
     version: "1.0.0",
@@ -440,6 +751,7 @@ function buildCanUseTool(config) {
     const unifiedRequest = {
       toolName,
       toolArgs: input,
+      toolCallId: options.toolUseID,
       suggestedScope: extractSuggestedScope(options.suggestions),
       rawSDKRequest: { toolName, input, ...options }
     };
@@ -516,6 +828,7 @@ function mapSDKMessage(msg, thinkingBlockIndices, toolCallTracker) {
         if (block.type === "tool_use") {
           const toolCallId = String(block.id ?? "");
           const toolName = stripMcpPrefix(block.name ?? "unknown");
+          if (CLAUDE_INTERNAL_TOOL_NAMES.has(toolName)) continue;
           if (toolCallTracker) {
             toolCallTracker.trackStart(toolCallId, toolName);
           }
@@ -539,6 +852,7 @@ function mapSDKMessage(msg, thinkingBlockIndices, toolCallTracker) {
     case "tool_use_summary": {
       const summary = msg.summary;
       const toolName = stripMcpPrefix(msg.tool_name ?? "unknown");
+      if (CLAUDE_INTERNAL_TOOL_NAMES.has(toolName)) return null;
       const precedingIds = msg.preceding_tool_use_ids;
       let toolCallId = "";
       if (precedingIds && precedingIds.length > 0) {
@@ -592,10 +906,13 @@ function mapSDKMessage(msg, thinkingBlockIndices, toolCallTracker) {
       }
       if (msg.is_error) {
         const r = msg;
+        const errorMsg = r.errors?.join("; ") ?? "Unknown error";
+        const code = classifyAgentError(errorMsg);
         return {
           type: "error",
-          error: r.errors?.join("; ") ?? "Unknown error",
-          recoverable: false
+          error: errorMsg,
+          recoverable: isRecoverableErrorCode(code),
+          code
         };
       }
       return null;
@@ -621,11 +938,6 @@ var ClaudeAgent = class extends BaseAgent {
     if (options.resumeSessionId) {
       this._sessionId = options.resumeSessionId;
     }
-    if (config.supervisor?.onAskUser) {
-      console.warn(
-        "[agent-sdk/claude] supervisor.onAskUser is not supported by the Claude CLI backend. User interaction requests from the model will not be forwarded."
-      );
-    }
   }
   get sessionId() {
     return this._sessionId;
@@ -649,12 +961,12 @@ var ClaudeAgent = class extends BaseAgent {
     const transcriptPath = home ? `${home}/.claude/projects/.session/sessions/${sessionId}/conversation.jsonl` : void 0;
     return { type: "session_info", sessionId, transcriptPath, backend: "claude" };
   }
-  buildQueryOptions(signal) {
+  buildQueryOptions(signal, options) {
     const ac = new AbortController();
     signal.addEventListener("abort", () => ac.abort(), { once: true });
     const opts = {
       abortController: ac,
-      model: this.config.model,
+      model: options.model,
       maxTurns: this.options.maxTurns,
       cwd: this.options.workingDirectory,
       pathToClaudeCodeExecutable: this.options.cliPath,
@@ -684,25 +996,85 @@ var ClaudeAgent = class extends BaseAgent {
     return opts;
   }
   async buildMcpConfig(opts, toolResultCapture) {
-    if (this.tools.length === 0) return opts;
+    const onAskUser = this.config.supervisor?.onAskUser;
+    if (this.tools.length === 0 && !onAskUser) return opts;
     const sdk = await loadSDK();
-    const mcpServer = buildMcpServer(sdk, this.tools, toolResultCapture);
+    const mcpServer = buildMcpServer(sdk, this.tools, toolResultCapture, onAskUser);
     if (mcpServer) {
       opts.mcpServers = {
         [MCP_SERVER_NAME]: mcpServer
       };
       const mcpToolNames = this.tools.map((t) => mcpToolName(t.name));
+      if (onAskUser) {
+        mcpToolNames.push(mcpToolName("ask_user"));
+      }
       opts.allowedTools = [...opts.allowedTools ?? [], ...mcpToolNames];
     }
+    if (onAskUser) {
+      opts.disallowedTools = [...opts.disallowedTools ?? [], "AskUserQuestion"];
+    }
     return opts;
   }
+  // ─── Retry Helpers (shared across executeRun/RunStructured/Stream) ──
+  /** Setup a retry query: clear session, rebuild with full history */
+  async prepareRetryQuery(sdk, messages, signal, options, toolResultCapture, modifyOpts) {
+    this.clearPersistentSession();
+    const retryPrompt = buildContextualPrompt(messages);
+    let retryOpts = this.buildQueryOptions(signal, options);
+    toolResultCapture.clear();
+    retryOpts = await this.buildMcpConfig(retryOpts, toolResultCapture);
+    modifyOpts?.(retryOpts);
+    const retryQ = sdk.query({ prompt: retryPrompt, options: retryOpts });
+    this.activeQuery = retryQ;
+    return retryQ;
+  }
+  /** Extract tool_use blocks from an assistant SDK message into toolCalls array */
+  collectToolCallsFromMessage(msg, toolCalls, toolResultCapture) {
+    if (msg.type !== "assistant") return;
+    const betaMessage = msg.message;
+    if (!betaMessage?.content) return;
+    for (const block of betaMessage.content) {
+      if (block.type === "tool_use") {
+        const toolName = stripMcpPrefix(block.name ?? "unknown");
+        if (CLAUDE_INTERNAL_TOOL_NAMES.has(toolName)) continue;
+        toolCalls.push({
+          toolName,
+          args: block.input ?? {},
+          result: toolResultCapture.get(toolName) ?? null,
+          approved: true
+        });
+      }
+    }
+  }
+  /** Back-fill tool results from capture map on summary/result messages */
+  backfillToolResults(msg, toolCalls, toolResultCapture) {
+    if (msg.type !== "tool_use_summary" && msg.type !== "result") return;
+    for (const tc of toolCalls) {
+      if (tc.result === null) {
+        const captured = toolResultCapture.get(tc.toolName);
+        if (captured !== void 0) tc.result = captured;
+      }
+    }
+  }
+  /** Wrap retry inner loop with shared error handling */
+  async withRetryErrorHandling(signal, fn) {
+    try {
+      return await fn();
+    } catch (retryError) {
+      if (this.isPersistent) this.clearPersistentSession();
+      if (signal.aborted) throw new AbortError();
+      throw retryError;
+    } finally {
+      this.activeQuery = null;
+    }
+  }
   // ─── executeRun ─────────────────────────────────────────────────
-  async executeRun(messages, _options, signal) {
+  async executeRun(messages, options, signal) {
     this.checkAbort(signal);
     const sdk = await loadSDK();
     const isResuming = this.isPersistent && this._sessionId !== void 0;
     const prompt = isResuming ? extractLastUserPrompt(messages) : buildContextualPrompt(messages);
-    let opts = this.buildQueryOptions(signal);
+    let opts = this.buildQueryOptions(signal, options);
     const toolResultCapture = /* @__PURE__ */ new Map();
     opts = await this.buildMcpConfig(opts, toolResultCapture);
     const q = sdk.query({ prompt, options: opts });
@@ -712,30 +1084,8 @@ var ClaudeAgent = class extends BaseAgent {
     let usage;
     try {
       for await (const msg of q) {
-        if (msg.type === "assistant") {
-          const betaMessage = msg.message;
-          if (betaMessage?.content) {
-            for (const block of betaMessage.content) {
-              if (block.type === "tool_use") {
-                const toolName = stripMcpPrefix(block.name ?? "unknown");
-                toolCalls.push({
-                  toolName,
-                  args: block.input ?? {},
-                  result: toolResultCapture.get(toolName) ?? null,
-                  approved: true
-                });
-              }
-            }
-          }
-        }
-        if (msg.type === "tool_use_summary" || msg.type === "result") {
-          for (const tc of toolCalls) {
-            if (tc.result === null) {
-              const captured = toolResultCapture.get(tc.toolName);
-              if (captured !== void 0) tc.result = captured;
-            }
-          }
-        }
+        this.collectToolCallsFromMessage(msg, toolCalls, toolResultCapture);
+        this.backfillToolResults(msg, toolCalls, toolResultCapture);
         if (msg.type === "result") {
           if (msg.subtype === "success") {
             const r = msg;
@@ -755,41 +1105,13 @@ var ClaudeAgent = class extends BaseAgent {
     } catch (e) {
       if (signal.aborted) throw new AbortError();
       if (isResuming && this.isPersistent) {
-        this.clearPersistentSession();
-        const retryPrompt = buildContextualPrompt(messages);
-        let retryOpts = this.buildQueryOptions(signal);
-        toolResultCapture.clear();
-        retryOpts = await this.buildMcpConfig(retryOpts, toolResultCapture);
-        const retryQ = sdk.query({ prompt: retryPrompt, options: retryOpts });
-        this.activeQuery = retryQ;
+        const retryQ = await this.prepareRetryQuery(sdk, messages, signal, options, toolResultCapture);
         toolCalls.length = 0;
         output = null;
-        try {
+        return this.withRetryErrorHandling(signal, async () => {
           for await (const msg of retryQ) {
-            if (msg.type === "assistant") {
-              const betaMessage = msg.message;
-              if (betaMessage?.content) {
-                for (const block of betaMessage.content) {
-                  if (block.type === "tool_use") {
-                    const toolName = stripMcpPrefix(block.name ?? "unknown");
-                    toolCalls.push({
-                      toolName,
-                      args: block.input ?? {},
-                      result: toolResultCapture.get(toolName) ?? null,
-                      approved: true
-                    });
-                  }
-                }
-              }
-            }
-            if (msg.type === "tool_use_summary" || msg.type === "result") {
-              for (const tc of toolCalls) {
-                if (tc.result === null) {
-                  const captured = toolResultCapture.get(tc.toolName);
-                  if (captured !== void 0) tc.result = captured;
-                }
-              }
-            }
+            this.collectToolCallsFromMessage(msg, toolCalls, toolResultCapture);
+            this.backfillToolResults(msg, toolCalls, toolResultCapture);
             if (msg.type === "result") {
               if (msg.subtype === "success") {
                 const r = msg;
@@ -806,23 +1128,17 @@ var ClaudeAgent = class extends BaseAgent {
               }
             }
           }
-        } catch (retryError) {
-          if (this.isPersistent) this.clearPersistentSession();
-          if (signal.aborted) throw new AbortError();
-          throw retryError;
-        } finally {
-          this.activeQuery = null;
-        }
-        return {
-          output,
-          structuredOutput: void 0,
-          toolCalls,
-          messages: [
-            ...messages,
-            ...output !== null ? [{ role: "assistant", content: output }] : []
-          ],
-          usage
-        };
+          return {
+            output,
+            structuredOutput: void 0,
+            toolCalls,
+            messages: [
+              ...messages,
+              ...output !== null ? [{ role: "assistant", content: output }] : []
+            ],
+            usage
+          };
+        });
       }
       if (this.isPersistent) this.clearPersistentSession();
       throw e;
@@ -841,12 +1157,12 @@ var ClaudeAgent = class extends BaseAgent {
     };
   }
   // ─── executeRunStructured ───────────────────────────────────────
-  async executeRunStructured(messages, schema, _options, signal) {
+  async executeRunStructured(messages, schema, options, signal) {
     this.checkAbort(signal);
     const sdk = await loadSDK();
     const isResuming = this.isPersistent && this._sessionId !== void 0;
     const prompt = isResuming ? extractLastUserPrompt(messages) : buildContextualPrompt(messages);
-    let opts = this.buildQueryOptions(signal);
+    let opts = this.buildQueryOptions(signal, options);
     const toolResultCapture = /* @__PURE__ */ new Map();
     opts = await this.buildMcpConfig(opts, toolResultCapture);
     const jsonSchema = zodToJsonSchema(schema.schema);
@@ -862,30 +1178,8 @@ var ClaudeAgent = class extends BaseAgent {
     let usage;
     try {
       for await (const msg of q) {
-        if (msg.type === "assistant") {
-          const betaMessage = msg.message;
-          if (betaMessage?.content) {
-            for (const block of betaMessage.content) {
-              if (block.type === "tool_use") {
-                const toolName = stripMcpPrefix(block.name ?? "unknown");
-                toolCalls.push({
-                  toolName,
-                  args: block.input ?? {},
-                  result: toolResultCapture.get(toolName) ?? null,
-                  approved: true
-                });
-              }
-            }
-          }
-        }
-        if (msg.type === "tool_use_summary" || msg.type === "result") {
-          for (const tc of toolCalls) {
-            if (tc.result === null) {
-              const captured = toolResultCapture.get(tc.toolName);
-              if (captured !== void 0) tc.result = captured;
-            }
-          }
-        }
+        this.collectToolCallsFromMessage(msg, toolCalls, toolResultCapture);
+        this.backfillToolResults(msg, toolCalls, toolResultCapture);
         if (msg.type === "result" && msg.subtype === "success") {
           const r = msg;
           output = r.result;
@@ -920,46 +1214,23 @@ var ClaudeAgent = class extends BaseAgent {
     } catch (e) {
       if (signal.aborted) throw new AbortError();
       if (isResuming && this.isPersistent) {
-        this.clearPersistentSession();
-        const retryPrompt = buildContextualPrompt(messages);
-        let retryOpts = this.buildQueryOptions(signal);
-        toolResultCapture.clear();
-        retryOpts = await this.buildMcpConfig(retryOpts, toolResultCapture);
-        retryOpts.outputFormat = {
-          type: "json_schema",
-          schema: jsonSchema
-        };
-        const retryQ = sdk.query({ prompt: retryPrompt, options: retryOpts });
-        this.activeQuery = retryQ;
+        const retryQ = await this.prepareRetryQuery(
+          sdk,
+          messages,
+          signal,
+          options,
+          toolResultCapture,
+          (opts2) => {
+            opts2.outputFormat = { type: "json_schema", schema: jsonSchema };
+          }
+        );
         toolCalls.length = 0;
         output = null;
         structuredOutput = void 0;
-        try {
+        return this.withRetryErrorHandling(signal, async () => {
           for await (const msg of retryQ) {
-            if (msg.type === "assistant") {
-              const betaMessage = msg.message;
-              if (betaMessage?.content) {
-                for (const block of betaMessage.content) {
-                  if (block.type === "tool_use") {
-                    const toolName = stripMcpPrefix(block.name ?? "unknown");
-                    toolCalls.push({
-                      toolName,
-                      args: block.input ?? {},
-                      result: toolResultCapture.get(toolName) ?? null,
-                      approved: true
-                    });
-                  }
-                }
-              }
-            }
-            if (msg.type === "tool_use_summary" || msg.type === "result") {
-              for (const tc of toolCalls) {
-                if (tc.result === null) {
-                  const captured = toolResultCapture.get(tc.toolName);
-                  if (captured !== void 0) tc.result = captured;
-                }
-              }
-            }
+            this.collectToolCallsFromMessage(msg, toolCalls, toolResultCapture);
+            this.backfillToolResults(msg, toolCalls, toolResultCapture);
             if (msg.type === "result" && msg.subtype === "success") {
               const r = msg;
               output = r.result;
@@ -991,23 +1262,17 @@ var ClaudeAgent = class extends BaseAgent {
               );
             }
           }
-        } catch (retryError) {
-          if (this.isPersistent) this.clearPersistentSession();
-          if (signal.aborted) throw new AbortError();
-          throw retryError;
-        } finally {
-          this.activeQuery = null;
-        }
-        return {
-          output,
-          structuredOutput,
-          toolCalls,
-          messages: [
-            ...messages,
-            ...output !== null ? [{ role: "assistant", content: output }] : []
-          ],
-          usage
-        };
+          return {
+            output,
+            structuredOutput,
+            toolCalls,
+            messages: [
+              ...messages,
+              ...output !== null ? [{ role: "assistant", content: output }] : []
+            ],
+            usage
+          };
+        });
       }
       if (this.isPersistent) this.clearPersistentSession();
       throw e;
@@ -1026,12 +1291,12 @@ var ClaudeAgent = class extends BaseAgent {
     };
   }
   // ─── executeStream ──────────────────────────────────────────────
-  async *executeStream(messages, _options, signal) {
+  async *executeStream(messages, options, signal) {
     this.checkAbort(signal);
     const sdk = await loadSDK();
     const isResuming = this.isPersistent && this._sessionId !== void 0;
     const prompt = isResuming ? extractLastUserPrompt(messages) : buildContextualPrompt(messages);
-    let opts = this.buildQueryOptions(signal);
+    let opts = this.buildQueryOptions(signal, options);
     const toolResultCapture = /* @__PURE__ */ new Map();
     opts = await this.buildMcpConfig(opts, toolResultCapture);
     const q = sdk.query({ prompt, options: opts });
@@ -1039,6 +1304,7 @@ var ClaudeAgent = class extends BaseAgent {
     const thinkingBlockIndices = /* @__PURE__ */ new Set();
     const toolCallTracker = new ClaudeToolCallTracker();
     const pendingStreamToolCalls = /* @__PURE__ */ new Map();
+    let hasStreamedText = false;
     try {
       for await (const msg of q) {
         if (signal.aborted) throw new AbortError();
@@ -1056,6 +1322,7 @@ var ClaudeAgent = class extends BaseAgent {
             } else if (e.type === "tool_call_end") {
               pendingStreamToolCalls.delete(e.toolCallId);
             }
+            if (e.type === "text_delta") hasStreamedText = true;
             yield e;
           }
         }
@@ -1079,22 +1346,21 @@ var ClaudeAgent = class extends BaseAgent {
             }
             yield this.emitSessionInfo(r.session_id);
           }
-          yield { type: "done", finalOutput: r.result };
+          yield {
+            type: "done",
+            finalOutput: hasStreamedText ? null : r.result,
+            ...hasStreamedText ? { streamed: true } : {}
+          };
         }
       }
     } catch (e) {
       if (signal.aborted) throw new AbortError();
       if (isResuming && this.isPersistent) {
-        this.clearPersistentSession();
-        const retryPrompt = buildContextualPrompt(messages);
-        let retryOpts = this.buildQueryOptions(signal);
-        toolResultCapture.clear();
-        retryOpts = await this.buildMcpConfig(retryOpts, toolResultCapture);
-        const retryQ = sdk.query({ prompt: retryPrompt, options: retryOpts });
-        this.activeQuery = retryQ;
+        const retryQ = await this.prepareRetryQuery(sdk, messages, signal, options, toolResultCapture);
         const retryThinkingBlockIndices = /* @__PURE__ */ new Set();
         const retryToolCallTracker = new ClaudeToolCallTracker();
         const retryPendingToolCalls = /* @__PURE__ */ new Map();
+        let retryHasStreamedText = false;
         try {
           for await (const msg of retryQ) {
             if (signal.aborted) throw new AbortError();
@@ -1112,6 +1378,7 @@ var ClaudeAgent = class extends BaseAgent {
                 } else if (ev.type === "tool_call_end") {
                   retryPendingToolCalls.delete(ev.toolCallId);
                 }
+                if (ev.type === "text_delta") retryHasStreamedText = true;
                 yield ev;
               }
             }
@@ -1135,7 +1402,11 @@ var ClaudeAgent = class extends BaseAgent {
                 }
                 yield this.emitSessionInfo(r.session_id);
               }
-              yield { type: "done", finalOutput: r.result };
+              yield {
+                type: "done",
+                finalOutput: retryHasStreamedText ? null : r.result,
+                ...retryHasStreamedText ? { streamed: true } : {}
+              };
             }
           }
         } catch (retryError) {
@@ -1158,59 +1429,6 @@ var ClaudeAgent = class extends BaseAgent {
     super.dispose();
   }
 };
-function extractLastUserPrompt(messages) {
-  for (let i = messages.length - 1; i >= 0; i--) {
-    const msg = messages[i];
-    if (msg.role === "user") {
-      return getTextContent(msg.content);
-    }
-  }
-  return "";
-}
-function serializeToolCall(tc) {
-  const args = typeof tc.args === "string" ? tc.args : JSON.stringify(tc.args);
-  return `  Tool call: ${tc.name}(${args})`;
-}
-function serializeToolResult(tr) {
-  const result = typeof tr.result === "string" ? tr.result : JSON.stringify(tr.result);
-  const prefix = tr.isError ? "[ERROR] " : "";
-  return `  ${tr.name} \u2192 ${prefix}${result}`;
-}
-function buildContextualPrompt(messages) {
-  if (messages.length <= 1) {
-    return extractLastUserPrompt(messages);
-  }
-  const history = messages.slice(0, -1).map((msg) => {
-    if (msg.role === "user") {
-      return `User: ${msg.content ? getTextContent(msg.content) : ""}`;
-    }
-    if (msg.role === "tool" && msg.toolResults) {
-      const results = msg.toolResults.map(serializeToolResult).join("\n");
-      return `Tool results:
-${results}`;
-    }
-    if (msg.role === "assistant") {
-      const parts = [];
-      const thinking = msg.thinking;
-      if (thinking) {
-        parts.push(`[reasoning: ${thinking}]`);
-      }
-      const text2 = msg.content ? getTextContent(msg.content) : "";
-      if (text2) parts.push(text2);
-      if (msg.toolCalls && msg.toolCalls.length > 0) {
-        parts.push(msg.toolCalls.map(serializeToolCall).join("\n"));
-      }
-      return `Assistant: ${parts.join("\n")}`;
-    }
-    const text = msg.content ? getTextContent(msg.content) : "";
-    return `${msg.role}: ${text}`;
-  }).join("\n");
-  const lastPrompt = extractLastUserPrompt(messages);
-  return `Conversation history:
-${history}
-
-User: ${lastPrompt}`;
-}
 var ClaudeAgentService = class {
   name = "claude";
   disposed = false;
@@ -1250,7 +1468,8 @@ var ClaudeAgentService = class {
     this.cachedModels = body.data.map((m) => ({
       id: m.id,
       name: m.display_name,
-      provider: "claude"
+      provider: "claude",
+      ...m.max_input_tokens != null && { contextWindow: m.max_input_tokens }
     }));
     return this.cachedModels;
   }