wave-agent-sdk 1.0.6 → 1.0.8

package/dist/tools/webFetchTool.js

@@ -2,12 +2,18 @@ import TurndownService from "turndown";
 import { LRUCache } from "lru-cache";
 import { WEB_FETCH_TOOL_NAME } from "../constants/tools.js";
 import { logger } from "../utils/globalLogger.js";
+import { isArtifactEnabled } from "../services/artifactAvailability.js";
+import { authService, createAuthAwareFetch } from "../services/authService.js";
+import { recordVersion } from "../services/artifactSession.js";
+import { buildPersistedOutputMessage, generatePreview, persistToolResult, } from "../utils/toolResultStorage.js";
 // --- Security Limits ---
 const MAX_HTTP_CONTENT_LENGTH = 10 * 1024 * 1024; // 10MB
 const FETCH_TIMEOUT_MS = 60000; // 60s
 const MAX_REDIRECTS = 10;
 const MAX_MARKDOWN_LENGTH = 100000;
 const USER_AGENT = "Wave-User (+https://github.com/netease-lcap/wave-agent)";
+/** Artifact HTML beyond this size is persisted to a temp file (path + head preview). */
+const ARTIFACT_PREVIEW_BYTES = 2 * 1024; // ~2KB
 // --- Cache (LRU with 15min TTL, 50MB max) ---
 const CACHE_TTL = 15 * 60 * 1000; // 15 minutes
 const CACHE_MAX_BYTES = 50 * 1024 * 1024; // 50MB
@@ -73,6 +79,124 @@ function isPermittedRedirect(originalUrl, redirectUrl) {
         return false;
     }
 }
+// --- Artifact read channel ---
+/** Extract the artifact slug from a `{host}/code/artifact/{slug}` URL. */
+function extractArtifactSlug(url) {
+    try {
+        const parsed = new URL(url);
+        const match = parsed.pathname.match(/^\/code\/artifact\/([^/]+)\/?$/);
+        return match ? decodeURIComponent(match[1]) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Fetch artifact metadata (`via=model_read`) then the HTML content (Bearer).
+ * Returns markdown (HTML converted via turndown) on success.
+ */
+async function readArtifact(url, slug, abortSignal) {
+    const serverUrl = authService.getServerUrl();
+    const authFetch = createAuthAwareFetch(globalThis.fetch);
+    const signal = abortSignal
+        ? AbortSignal.any([abortSignal, AbortSignal.timeout(FETCH_TIMEOUT_MS)])
+        : AbortSignal.timeout(FETCH_TIMEOUT_MS);
+    let meta;
+    try {
+        const metaRes = await authFetch(`${serverUrl}/api/frame/${encodeURIComponent(slug)}?via=model_read`, { method: "GET", signal });
+        if (metaRes.status === 404) {
+            return {
+                kind: "error",
+                error: `Artifact not found: ${url} (it may have been deleted)`,
+            };
+        }
+        if (!metaRes.ok) {
+            return {
+                kind: "error",
+                error: `Failed to fetch artifact metadata: ${metaRes.status} ${metaRes.statusText}`,
+            };
+        }
+        meta = (await metaRes.json());
+    }
+    catch (error) {
+        logger?.warn("Artifact read metadata failed", {
+            slug,
+            error: String(error),
+        });
+        return {
+            kind: "error",
+            error: `Failed to fetch artifact metadata: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    const contentUrl = typeof meta.contentUrl === "string" ? meta.contentUrl : "";
+    const version = typeof meta.version === "string" ? meta.version : "";
+    if (!contentUrl) {
+        return {
+            kind: "error",
+            error: "Artifact metadata did not include a contentUrl",
+        };
+    }
+    let html;
+    try {
+        const contentRes = await authFetch(new URL(contentUrl, serverUrl).toString(), { method: "GET", signal });
+        if (!contentRes.ok) {
+            return {
+                kind: "error",
+                error: `Failed to fetch artifact content: ${contentRes.status} ${contentRes.statusText}`,
+            };
+        }
+        html = await contentRes.text();
+    }
+    catch (error) {
+        logger?.warn("Artifact read content failed", {
+            slug,
+            error: String(error),
+        });
+        return {
+            kind: "error",
+            error: `Failed to fetch artifact content: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    const turndownService = new TurndownService();
+    const markdown = turndownService.turndown(html);
+    return {
+        kind: "ok",
+        slug,
+        version,
+        markdown,
+        bytes: new TextEncoder().encode(markdown).length,
+    };
+}
+/**
+ * Process an artifact read result: persist content >~2KB to a temp file
+ * (return file path + head preview), run the prompt, attach artifactRead metadata.
+ */
+async function processArtifactRead(url, prompt, markdown, slug, version, context) {
+    const bytes = new TextEncoder().encode(markdown).length;
+    let aiInput = markdown;
+    let persistedMessage = "";
+    if (bytes > ARTIFACT_PREVIEW_BYTES) {
+        const filePath = persistToolResult(markdown, "artifact");
+        if (filePath) {
+            persistedMessage = buildPersistedOutputMessage(markdown.length, filePath, generatePreview(markdown));
+            aiInput = persistedMessage;
+        }
+        else {
+            aiInput =
+                markdown.substring(0, MAX_MARKDOWN_LENGTH) +
+                    "\n\n... (content truncated, failed to persist full output)";
+        }
+    }
+    const result = await processWithAI(url, prompt, aiInput, 200, "OK", context, bytes);
+    result.metadata = { artifactRead: { slug, ver: version } };
+    if (persistedMessage) {
+        // Append the persisted-output message so the model can Read the full content.
+        result.content = result.content
+            ? result.content + "\n\n" + persistedMessage
+            : persistedMessage;
+    }
+    return result;
+}
 // --- Tool ---
 export const webFetchTool = {
     name: WEB_FETCH_TOOL_NAME,
@@ -141,6 +265,23 @@ Usage notes:
                 error: validation.error,
             };
         }
+        // Artifact URL interception: {host}/code/artifact/{slug} goes through the
+        // dedicated read channel (via=model_read + Bearer) instead of a public fetch.
+        // Only when the Artifact tool is enabled (spec 6.4: disabled = no interception).
+        if (isArtifactEnabled(context.workdir)) {
+            const artifactSlug = extractArtifactSlug(url);
+            if (artifactSlug) {
+                const readResult = await readArtifact(url, artifactSlug, context.abortSignal);
+                if (readResult.kind === "error") {
+                    return { success: false, content: "", error: readResult.error };
+                }
+                if (context.sessionId && readResult.version) {
+                    // Keep the stale-version guard in sync with what the model has seen.
+                    recordVersion(context.sessionId, artifactSlug, readResult.version);
+                }
+                return processArtifactRead(url, prompt, readResult.markdown, artifactSlug, readResult.version, context);
+            }
+        }
         try {
             const cached = cache.get(url);
             if (cached) {

package/dist/types/agent.d.ts

@@ -25,6 +25,8 @@ export interface AgentOptions {
     fetch?: ClientOptions["fetch"];
     model?: string;
     fastModel?: string;
+    /** Vision-capable model used by the builtin vision subagent (resolved from WAVE_VISION_MODEL env var). */
+    visionModel?: string;
     maxInputTokens?: number;
     maxTokens?: number;
     /** Preferred language for agent communication */

package/dist/types/config.d.ts

@@ -22,6 +22,8 @@ export interface ModelCapabilities {
 export interface ModelConfig {
     model?: string;
     fastModel?: string;
+    /** Vision-capable model for image recognition subagents (resolved from WAVE_VISION_MODEL env var). */
+    visionModel?: string;
     maxTokens?: number;
     permissionMode?: PermissionMode;
     capabilities?: ModelCapabilities;

package/dist/types/configuration.d.ts

@@ -55,6 +55,8 @@ export interface WaveConfiguration {
         /** Base ref for new worktrees: "fresh" (origin/<default-branch>, default) | "head" (local HEAD) */
         baseRef?: "fresh" | "head";
     };
+    /** Whether the Artifact tool is enabled. Unset follows the code default constant (ARTIFACT_DEFAULT_ENABLED). */
+    enableArtifact?: boolean;
 }
 /**
  * Legacy alias for backward compatibility - will be deprecated

package/dist/types/core.d.ts

@@ -2,7 +2,6 @@
  * Core foundational types used across multiple domains
  * Dependencies: None (foundation layer)
  */
-import type { CompletionUsage } from "openai/resources";
 /**
  * Logger interface definition
  * Compatible with OpenAI package Logger interface
@@ -15,7 +14,7 @@ export interface Logger {
 }
 /**
  * Usage statistics for AI operations
- * Extends OpenAI's Usage format with additional tracking fields
+ * Extends OpenAI's Usage format with normalized cache fields
  */
 export interface Usage {
     prompt_tokens: number;
@@ -25,38 +24,6 @@ export interface Usage {
     operation_type?: "agent" | "compact";
     cache_read_input_tokens?: number;
     cache_creation_input_tokens?: number;
-    cache_creation?: {
-        ephemeral_5m_input_tokens: number;
-        ephemeral_1h_input_tokens: number;
-    };
-}
-/**
- * Enhanced usage metrics including Claude cache information
- * Backward compatible with standard OpenAI CompletionUsage
- */
-export interface ClaudeUsage extends CompletionUsage {
-    prompt_tokens: number;
-    completion_tokens: number;
-    total_tokens: number;
-    /**
-     * Number of tokens read from existing cache
-     * Indicates cost savings from cache hits
-     */
-    cache_read_input_tokens?: number;
-    /**
-     * Number of tokens used to create new cache entries
-     * Investment in future cache hits
-     */
-    cache_creation_input_tokens?: number;
-    /**
-     * Detailed breakdown of cache creation by duration
-     */
-    cache_creation?: {
-        /** Tokens cached for 5 minute duration */
-        ephemeral_5m_input_tokens: number;
-        /** Tokens cached for 1 hour duration */
-        ephemeral_1h_input_tokens: number;
-    };
 }
 /**
  * Represents a diff change for tool parameter-based diff display

package/dist/types/index.d.ts

@@ -38,3 +38,4 @@ export * from "./workflow.js";
 export type { SessionMetadata, SessionData } from "../services/session.js";
 export type { ToolBlockUpdateCallbackParams } from "../utils/messageOperations.js";
 export type { QueuedMessage } from "../managers/messageQueue.js";
+export type { SubagentConfiguration } from "../utils/subagentParser.js";

package/dist/types/messaging.d.ts

@@ -52,7 +52,9 @@ export interface ToolBlock {
     error?: string | Error;
     compactParams?: string;
     parametersChunk?: string;
-    isManuallyBackgrounded?: boolean;
+    backgroundTaskId?: string;
+    backgroundedByUser?: boolean;
+    assistantAutoBackgrounded?: boolean;
     timestamp?: number;
 }
 export interface ImageBlock {

package/dist/types/permissions.d.ts

@@ -36,9 +36,11 @@ export interface ToolPermissionContext {
     toolCallId?: string;
     /** The content of the plan being exited from */
     planContent?: string;
+    /** Optional warning line to surface in the confirmation UI (e.g. shared-live redeploy impact) */
+    warning?: string;
 }
 /** List of tools that require permission checks in default mode */
-export declare const RESTRICTED_TOOLS: readonly ["Edit", "Bash", "Write", "EnterPlanMode", "ExitPlanMode", "AskUserQuestion"];
+export declare const RESTRICTED_TOOLS: readonly ["Edit", "Bash", "Write", "EnterPlanMode", "ExitPlanMode", "AskUserQuestion", "Artifact"];
 /** Type for restricted tool names */
 export type RestrictedTool = (typeof RESTRICTED_TOOLS)[number];
 export declare const OPERATION_CANCELLED_BY_USER = "Operation cancelled by user";

package/dist/types/permissions.js

@@ -2,7 +2,7 @@
  * Permission system types for Wave Agent SDK
  * Dependencies: None
  */
-import { EDIT_TOOL_NAME, BASH_TOOL_NAME, WRITE_TOOL_NAME, ENTER_PLAN_MODE_TOOL_NAME, EXIT_PLAN_MODE_TOOL_NAME, ASK_USER_QUESTION_TOOL_NAME, } from "../constants/tools.js";
+import { EDIT_TOOL_NAME, BASH_TOOL_NAME, WRITE_TOOL_NAME, ENTER_PLAN_MODE_TOOL_NAME, EXIT_PLAN_MODE_TOOL_NAME, ASK_USER_QUESTION_TOOL_NAME, ARTIFACT_TOOL_NAME, } from "../constants/tools.js";
 /** List of tools that require permission checks in default mode */
 export const RESTRICTED_TOOLS = [
     EDIT_TOOL_NAME,
@@ -11,5 +11,6 @@ export const RESTRICTED_TOOLS = [
     ENTER_PLAN_MODE_TOOL_NAME,
     EXIT_PLAN_MODE_TOOL_NAME,
     ASK_USER_QUESTION_TOOL_NAME,
+    ARTIFACT_TOOL_NAME,
 ];
 export const OPERATION_CANCELLED_BY_USER = "Operation cancelled by user";

package/dist/utils/bashParser.d.ts

@@ -46,6 +46,12 @@ export interface ToolRule {
     depth: number;
     scopeFlags?: string[];
 }
+/**
+ * Global scope flags for git that only change the target repository or
+ * configuration, not the subcommand being run. Shared by TOOL_RULES (smart
+ * prefix extraction) and stripGitScopePrefix (rule matching).
+ */
+export declare const GIT_SCOPE_FLAGS: string[];
 export declare const TOOL_RULES: Record<string, ToolRule>;
 /**
  * Registry of dangerous subcommands for specific tools.
@@ -71,6 +77,14 @@ export declare function hasProcessSubstitution(command: string): boolean;
  * sed -i modifies files in place and must NOT be auto-allowed. FR-019.5.
  */
 export declare function hasSedInPlace(command: string): boolean;
+/**
+ * Removes leading git global scope flags (e.g. `git -C <path>`, `git -c <key>=<value>`,
+ * `git --git-dir <path>`) from a command string, so that `git -C /tmp/foo status` is
+ * classified the same as `git status`. Only the leading sequence before the git
+ * subcommand is stripped; the remainder is re-joined with single spaces.
+ * Returns the input unchanged when nothing is stripped.
+ */
+export declare function stripGitScopePrefix(command: string): string;
 /**
  * Extracts a "smart prefix" from a bash command based on common developer tools.
  * Returns null if the command is blacklisted or cannot be safely prefix-matched.

package/dist/utils/bashParser.js

@@ -500,6 +500,18 @@ export const READ_ONLY_COMMANDS = [
     "bc",
     "sleep",
 ];
+/**
+ * Global scope flags for git that only change the target repository or
+ * configuration, not the subcommand being run. Shared by TOOL_RULES (smart
+ * prefix extraction) and stripGitScopePrefix (rule matching).
+ */
+export const GIT_SCOPE_FLAGS = [
+    "-C",
+    "-c",
+    "--directory",
+    "--work-tree",
+    "--git-dir",
+];
 export const TOOL_RULES = {
     // Node/JS
     npm: { depth: 2, scopeFlags: ["--prefix", "-C", "--registry"] },
@@ -517,7 +529,7 @@ export const TOOL_RULES = {
     // Git
     git: {
         depth: 2,
-        scopeFlags: ["-C", "-c", "--directory", "--work-tree", "--git-dir"],
+        scopeFlags: GIT_SCOPE_FLAGS,
     },
     // Python
     python: { depth: 2 },
@@ -670,6 +682,38 @@ export function hasSedInPlace(command) {
         return false;
     return tokens.some((token) => /^-i(\..*)?$/.test(token));
 }
+/**
+ * Removes leading git global scope flags (e.g. `git -C <path>`, `git -c <key>=<value>`,
+ * `git --git-dir <path>`) from a command string, so that `git -C /tmp/foo status` is
+ * classified the same as `git status`. Only the leading sequence before the git
+ * subcommand is stripped; the remainder is re-joined with single spaces.
+ * Returns the input unchanged when nothing is stripped.
+ */
+export function stripGitScopePrefix(command) {
+    const trimmed = command.trim();
+    if (!/^git(?:\s|$)/.test(trimmed))
+        return command;
+    const tokens = trimmed.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) || [];
+    if (tokens.length === 0 || tokens[0] !== "git")
+        return command;
+    let i = 1;
+    while (i < tokens.length) {
+        const token = tokens[i];
+        const eqIndex = token.indexOf("=");
+        const flag = eqIndex > 0 ? token.slice(0, eqIndex) : token;
+        if (!GIT_SCOPE_FLAGS.includes(flag))
+            break;
+        if (eqIndex > 0) {
+            i++; // --flag=value form carries its own value
+        }
+        else {
+            i += 2; // skip the flag and its argument
+        }
+    }
+    if (i === 1)
+        return command;
+    return ["git", ...tokens.slice(i)].join(" ");
+}
 /**
  * Extracts a "smart prefix" from a bash command based on common developer tools.
  * Returns null if the command is blacklisted or cannot be safely prefix-matched.

package/dist/utils/cacheControlUtils.d.ts

@@ -7,6 +7,7 @@
  */
 import type { ChatCompletionMessageParam, ChatCompletionContentPart, ChatCompletionContentPartText, CompletionUsage } from "openai/resources";
 import type { ModelCapabilities } from "../types/config.js";
+import type { Usage } from "../types/core.js";
 /**
  * Cache control directive for Claude models
  */
@@ -28,22 +29,6 @@ export interface ClaudeChatCompletionContentPartText extends ChatCompletionConte
 export interface ExtendedPromptTokensDetails extends CompletionUsage.PromptTokensDetails {
     cache_creation_input_tokens?: number;
 }
-/**
- * Enhanced usage metrics including cache information
- * Supports both Claude-specific top-level fields and OpenAI-standard prompt_tokens_details
- */
-export interface ClaudeUsage extends CompletionUsage {
-    prompt_tokens: number;
-    completion_tokens: number;
-    total_tokens: number;
-    cache_read_input_tokens?: number;
-    cache_creation_input_tokens?: number;
-    cache_creation?: {
-        ephemeral_5m_input_tokens: number;
-        ephemeral_1h_input_tokens: number;
-    };
-    prompt_tokens_details?: ExtendedPromptTokensDetails;
-}
 /**
  * Validates cache control structure
  * @param control - Object to validate
@@ -85,16 +70,9 @@ export declare function countContentBlocks(messages: ChatCompletionMessageParam[
 export declare function transformMessagesForExplicitCache(messages: ChatCompletionMessageParam[], capabilities?: ModelCapabilities): ChatCompletionMessageParam[];
 /**
  * Extends standard usage with cache metrics
- * Extracts cache tokens from both Claude-specific top-level fields and
- * OpenAI-standard prompt_tokens_details (used by Gemini, DeepSeek, etc.)
- * @param standardUsage - OpenAI usage response
- * @param cacheMetrics - Additional cache metrics from the API response
+ * Extracts cache tokens from OpenAI-standard prompt_tokens_details
+ * (cached_tokens and the gateway-provided cache_creation_input_tokens)
+ * @param usage - OpenAI usage response
  * @returns Extended usage with cache information
  */
-export declare function extendUsageWithCacheMetrics(standardUsage: CompletionUsage, cacheMetrics?: Partial<ClaudeUsage>): ClaudeUsage;
-/**
- * Validates Claude usage structure
- * @param usage - Usage object to validate
- * @returns True if usage structure is valid
- */
-export declare function isValidClaudeUsage(usage: unknown): usage is ClaudeUsage;
+export declare function extendUsageWithCacheMetrics(usage: CompletionUsage): Usage;

package/dist/utils/cacheControlUtils.js

@@ -207,84 +207,23 @@ export function transformMessagesForExplicitCache(messages, capabilities) {
 }
 /**
  * Extends standard usage with cache metrics
- * Extracts cache tokens from both Claude-specific top-level fields and
- * OpenAI-standard prompt_tokens_details (used by Gemini, DeepSeek, etc.)
- * @param standardUsage - OpenAI usage response
- * @param cacheMetrics - Additional cache metrics from the API response
+ * Extracts cache tokens from OpenAI-standard prompt_tokens_details
+ * (cached_tokens and the gateway-provided cache_creation_input_tokens)
+ * @param usage - OpenAI usage response
  * @returns Extended usage with cache information
  */
-export function extendUsageWithCacheMetrics(standardUsage, cacheMetrics) {
+export function extendUsageWithCacheMetrics(usage) {
     const baseUsage = {
-        prompt_tokens: standardUsage.prompt_tokens,
-        completion_tokens: standardUsage.completion_tokens,
-        total_tokens: standardUsage.total_tokens,
+        prompt_tokens: usage.prompt_tokens,
+        completion_tokens: usage.completion_tokens,
+        total_tokens: usage.total_tokens,
     };
-    if (!cacheMetrics) {
-        return baseUsage;
+    const details = usage.prompt_tokens_details;
+    if (details?.cached_tokens != null) {
+        baseUsage.cache_read_input_tokens = details.cached_tokens;
     }
-    // Extract cache_read_input_tokens from Claude top-level field
-    if (typeof cacheMetrics.cache_read_input_tokens === "number") {
-        baseUsage.cache_read_input_tokens = cacheMetrics.cache_read_input_tokens;
-    }
-    // Fallback to prompt_tokens_details.cached_tokens (OpenAI standard)
-    else if (cacheMetrics.prompt_tokens_details?.cached_tokens != null) {
-        baseUsage.cache_read_input_tokens =
-            cacheMetrics.prompt_tokens_details.cached_tokens;
-    }
-    // Extract cache_creation_input_tokens from Claude top-level field
-    if (typeof cacheMetrics.cache_creation_input_tokens === "number") {
-        baseUsage.cache_creation_input_tokens =
-            cacheMetrics.cache_creation_input_tokens;
-    }
-    // Fallback to prompt_tokens_details.cache_creation_input_tokens
-    else if (cacheMetrics.prompt_tokens_details?.cache_creation_input_tokens != null) {
-        baseUsage.cache_creation_input_tokens =
-            cacheMetrics.prompt_tokens_details.cache_creation_input_tokens;
-    }
-    // Extract cache_creation breakdown (Claude-specific)
-    if (cacheMetrics.cache_creation &&
-        typeof cacheMetrics.cache_creation.ephemeral_5m_input_tokens === "number" &&
-        typeof cacheMetrics.cache_creation.ephemeral_1h_input_tokens === "number") {
-        baseUsage.cache_creation = {
-            ephemeral_5m_input_tokens: cacheMetrics.cache_creation.ephemeral_5m_input_tokens,
-            ephemeral_1h_input_tokens: cacheMetrics.cache_creation.ephemeral_1h_input_tokens,
-        };
+    if (details?.cache_creation_input_tokens != null) {
+        baseUsage.cache_creation_input_tokens = details.cache_creation_input_tokens;
     }
     return baseUsage;
 }
-/**
- * Validates Claude usage structure
- * @param usage - Usage object to validate
- * @returns True if usage structure is valid
- */
-export function isValidClaudeUsage(usage) {
-    if (!usage || typeof usage !== "object") {
-        return false;
-    }
-    const usageObj = usage;
-    // Check required standard fields
-    const hasStandardFields = typeof usageObj.prompt_tokens === "number" &&
-        typeof usageObj.completion_tokens === "number" &&
-        typeof usageObj.total_tokens === "number";
-    if (!hasStandardFields) {
-        return false;
-    }
-    // Check optional cache fields
-    const hasCacheFields = (usageObj.cache_read_input_tokens === undefined ||
-        typeof usageObj.cache_read_input_tokens === "number") &&
-        (usageObj.cache_creation_input_tokens === undefined ||
-            typeof usageObj.cache_creation_input_tokens === "number");
-    if (!hasCacheFields) {
-        return false;
-    }
-    // Check cache_creation object if present
-    if (usageObj.cache_creation !== undefined) {
-        const cacheCreation = usageObj.cache_creation;
-        if (typeof cacheCreation !== "object" ||
-            typeof cacheCreation.ephemeral_5m_input_tokens !== "number" ||
-            typeof cacheCreation.ephemeral_1h_input_tokens !== "number") {
-            return false;
-        }
-    }
-    return true;
-}

package/dist/utils/convertMessagesForAPI.js

@@ -158,14 +158,38 @@ export function convertMessagesForAPI(messages, options) {
                     tool_calls = undefined;
                 }
             }
-            // Construct assistant message - only add if there is meaningful content or tool calls
+            // Construct assistant message - only add if there is meaningful content,
+            // tool calls, or reasoning content. Reasoning-only messages (a truncated
+            // turn that produced nothing but thinking) must be preserved so the next
+            // round can continue from the previous reasoning instead of starting
+            // over (aligned with Claude Code's thinking trajectory preservation).
             const hasContent = content && content.trim().length > 0;
             const hasToolCalls = tool_calls && tool_calls.length > 0;
-            if (hasContent || hasToolCalls) {
+            const hasReasoning = reasoning_content && reasoning_content.trim().length > 0;
+            if (hasContent || hasToolCalls || hasReasoning) {
+                // OpenAI-compatible upstreams reject assistant messages where neither
+                // content nor tool_calls is set — a reasoning_content-only message
+                // gets stripped and returns 400 "content or tool_calls must be set"
+                // (this is fine for Claude Code, whose thinking blocks ARE content).
+                // When a turn produced only thinking (interrupted/truncated
+                // mid-reasoning), the thinking stays on its native reasoning_content
+                // field (the channel reasoning models natively continue from), and
+                // content carries an explanatory note so the request stays valid and
+                // the model knows the thinking was cut off and auto-preserved.
+                // Tool calls are meaningful content of their own — a reasoning +
+                // tool-call turn is not truncated, so no note is injected.
+                const fallbackContent = hasContent
+                    ? content
+                    : hasReasoning && !hasToolCalls
+                        ? "[Note: The reasoning above was cut off before completion. It was auto-preserved from an interrupted or truncated turn — continue from where it left off, or disregard it if no longer relevant.]"
+                        : undefined;
                 const assistantMessage = {
                     role: "assistant",
-                    content: hasContent ? content : undefined,
+                    content: fallbackContent,
                     tool_calls,
+                    // Sent whenever reasoning exists: alongside real text it is the
+                    // turn's own thinking; in the fallback case it carries the
+                    // preserved thinking itself (content only holds the note).
                     ...(reasoning_content ? { reasoning_content } : {}),
                     ...(message.additionalFields ? { ...message.additionalFields } : {}),
                 };
@@ -196,12 +220,25 @@ export function convertMessagesForAPI(messages, options) {
                             type: "text",
                             text: "[User shared an image, but the current model does not support image recognition]",
                         });
+                        // Append source path metadata for local-file images so the main
+                        // model can delegate recognition to a vision subagent (which
+                        // reads the path with the Read tool). Inline dataURLs are
+                        // skipped — only persisted paths are delegatable.
+                        block.imageUrls.forEach((imageUrl) => {
+                            if (!imageUrl.startsWith("data:image/")) {
+                                contentParts.push({
+                                    type: "text",
+                                    text: `[Image source: ${imageUrl}]`,
+                                });
+                            }
+                        });
                     }
                     else {
                         block.imageUrls.forEach((imageUrl) => {
                             // Check if it's already base64, convert if not
+                            const isDataUrl = imageUrl.startsWith("data:image/");
                             let finalImageUrl = imageUrl;
-                            if (!imageUrl.startsWith("data:image/")) {
+                            if (!isDataUrl) {
                                 // If it's a file path, it needs to be converted to base64
                                 try {
                                     finalImageUrl = convertImageToBase64(imageUrl);
@@ -219,6 +256,16 @@ export function convertMessagesForAPI(messages, options) {
                                     detail: "auto",
                                 },
                             });
+                            // Aligned with Claude Code: when the image comes from a local
+                            // file (not an inline dataURL), append its source path as text
+                            // metadata so the model can reference the file with tools
+                            // (e.g. a vision-model subagent reading the image).
+                            if (!isDataUrl) {
+                                contentParts.push({
+                                    type: "text",
+                                    text: `[Image source: ${imageUrl}]`,
+                                });
+                            }
                         });
                     }
                 }

package/dist/utils/messageOperations.d.ts

@@ -40,7 +40,9 @@ export interface UpdateToolBlockParams {
     }>;
     compactParams?: string;
     parametersChunk?: string;
-    isManuallyBackgrounded?: boolean;
+    backgroundTaskId?: string;
+    backgroundedByUser?: boolean;
+    assistantAutoBackgrounded?: boolean;
     timestamp?: number;
 }
 export type AgentToolBlockUpdateParams = Omit<UpdateToolBlockParams, "messages">;
@@ -86,7 +88,7 @@ export declare const addToolBlockToMessageInMessages: (messages: Message[], mess
     messages: Message[];
     toolBlockId: string;
 };
-export declare const updateToolBlockInMessage: ({ messages, id, messageId, parameters, result, success, error, stage, name, shortResult, startLineNumber, images, compactParams, parametersChunk, isManuallyBackgrounded, }: UpdateToolBlockParams) => {
+export declare const updateToolBlockInMessage: ({ messages, id, messageId, parameters, result, success, error, stage, name, shortResult, startLineNumber, images, compactParams, parametersChunk, backgroundTaskId, backgroundedByUser, assistantAutoBackgrounded, }: UpdateToolBlockParams) => {
     messages: Message[];
     messageId?: string;
 };