wave-agent-sdk 1.0.6 → 1.0.8

package/dist/services/artifactSession.js

@@ -0,0 +1,52 @@
+/**
+ * Session-scoped state shared between the Artifact tool and the WebFetch tool.
+ *
+ * - file_path → artifact record: lets a model republish a file it already
+ *   published this session without passing `url` again, and enables the
+ *   same-session auto-allow (the publish was already confirmed once).
+ * - slug → latest known version: powers the stale-version guard
+ *   (local knowledge older than the live version blocks a redeploy
+ *   unless `force` is set) and lets WebFetch record versions it observed.
+ *
+ * State is keyed by sessionId so parallel sessions never observe each other.
+ */
+const sessionArtifacts = new Map();
+const sessionSlugVersions = new Map();
+function fileMapFor(sessionId) {
+    let map = sessionArtifacts.get(sessionId);
+    if (!map) {
+        map = new Map();
+        sessionArtifacts.set(sessionId, map);
+    }
+    return map;
+}
+function slugMapFor(sessionId) {
+    let map = sessionSlugVersions.get(sessionId);
+    if (!map) {
+        map = new Map();
+        sessionSlugVersions.set(sessionId, map);
+    }
+    return map;
+}
+/** Record a successful publish so same-session republishes auto-allow. */
+export function recordArtifact(sessionId, filePath, record) {
+    fileMapFor(sessionId).set(filePath, record);
+    slugMapFor(sessionId).set(record.slug, record.version);
+}
+/** Look up an artifact previously published in this session by file path. */
+export function getArtifactByFilePath(sessionId, filePath) {
+    return sessionArtifacts.get(sessionId)?.get(filePath);
+}
+/** Latest version of a slug this session has observed (publish, conflict, or read). */
+export function getRecordedVersion(sessionId, slug) {
+    return sessionSlugVersions.get(sessionId)?.get(slug);
+}
+/** Record an observed version (from a publish, a 409 conflict, or a WebFetch read). */
+export function recordVersion(sessionId, slug, version) {
+    slugMapFor(sessionId).set(slug, version);
+}
+/** Clear all session-scoped artifact state (used when a session ends). */
+export function clearArtifactSession(sessionId) {
+    sessionArtifacts.delete(sessionId);
+    sessionSlugVersions.delete(sessionId);
+}

package/dist/services/configurationService.d.ts

@@ -81,9 +81,10 @@ export declare class ConfigurationService {
      * @param fastModel - Fast model override (optional)
      * @param maxTokens - Max output tokens override (optional)
      * @param permissionMode - Permission mode override (optional)
+     * @param visionModel - Vision model override (optional)
      * @returns Resolved model configuration with defaults
      */
-    resolveModelConfig(model?: string, fastModel?: string, maxTokens?: number, permissionMode?: PermissionMode): ModelConfig;
+    resolveModelConfig(model?: string, fastModel?: string, maxTokens?: number, permissionMode?: PermissionMode, visionModel?: string): ModelConfig;
     /**
      * Resolves token limit with fallbacks
      * Resolution priority: override > options > env (from settings.json) > process.env > default
@@ -196,6 +197,13 @@ export declare function mergeEnvironmentConfig(userEnv: Record<string, string> |
  * Supports both hooks and environment variables with proper validation
  */
 export declare function loadWaveConfigFromFile(filePath: string): WaveConfiguration | null;
+/**
+ * Load the user-level (~/.wave/settings.json) `env` block only — no workdir
+ * dependency. Used at daemon startup to apply WAVE_SERVER_URL before any agent
+ * initializes: auth queries (getAuthStatus) can run before the first agent,
+ * and AuthService falls back to the default URL otherwise.
+ */
+export declare function loadUserConfigEnv(): Record<string, string>;
 /**
  * Load and merge Wave configuration from both user and project sources
  * Project configuration takes precedence over user configuration

package/dist/services/configurationService.js

@@ -459,9 +459,10 @@ export class ConfigurationService {
      * @param fastModel - Fast model override (optional)
      * @param maxTokens - Max output tokens override (optional)
      * @param permissionMode - Permission mode override (optional)
+     * @param visionModel - Vision model override (optional)
      * @returns Resolved model configuration with defaults
      */
-    resolveModelConfig(model, fastModel, maxTokens, permissionMode) {
+    resolveModelConfig(model, fastModel, maxTokens, permissionMode, visionModel) {
         // Resolve agent model: override > options > currentConfiguration (settings.json model, possibly remote-merged) > process.env
         // Priority: user's explicit model field > admin's env.WAVE_MODEL default.
         // If admin wants hard enforcement, they set the `model` scalar field (overwrites local in mergeRemoteSettings).
@@ -473,11 +474,16 @@ export class ConfigurationService {
         const resolvedFastModel = fastModel ||
             this.options.fastModel ||
             (this.envSnapshot.WAVE_FAST_MODEL ?? process.env.WAVE_FAST_MODEL);
+        // Resolve vision model: override > options > process.env (includes settings.json env)
+        const resolvedVisionModel = visionModel ||
+            this.options.visionModel ||
+            (this.envSnapshot.WAVE_VISION_MODEL ?? process.env.WAVE_VISION_MODEL);
         // Resolve max output tokens
         const resolvedMaxTokens = this.resolveMaxOutputTokens(maxTokens);
         const baseConfig = {
             model: resolvedAgentModel,
             fastModel: resolvedFastModel,
+            visionModel: resolvedVisionModel,
             maxTokens: resolvedMaxTokens,
             permissionMode: permissionMode ?? this.options.permissionMode,
         };
@@ -1062,9 +1068,13 @@ export function loadWaveConfigFromFile(filePath) {
             autoMemoryEnabled: config.autoMemoryEnabled !== undefined
                 ? config.autoMemoryEnabled
                 : undefined,
+            autoMemoryFrequency: config.autoMemoryFrequency !== undefined
+                ? config.autoMemoryFrequency
+                : undefined,
             models: config.models || undefined,
             marketplaces: config.marketplaces || undefined,
             worktree: config.worktree || undefined,
+            enableArtifact: config.enableArtifact !== undefined ? config.enableArtifact : undefined,
         };
     }
     catch (error) {
@@ -1079,6 +1089,16 @@ export function loadWaveConfigFromFile(filePath) {
         throw error;
     }
 }
+/**
+ * Load the user-level (~/.wave/settings.json) `env` block only — no workdir
+ * dependency. Used at daemon startup to apply WAVE_SERVER_URL before any agent
+ * initializes: auth queries (getAuthStatus) can run before the first agent,
+ * and AuthService falls back to the default URL otherwise.
+ */
+export function loadUserConfigEnv() {
+    const config = loadWaveConfigFromFile(getUserConfigPaths()[0]);
+    return config?.env ?? {};
+}
 /**
  * Load and merge Wave configuration from both user and project sources
  * Project configuration takes precedence over user configuration
@@ -1199,6 +1219,10 @@ export function loadMergedWaveConfig(workdir) {
         if (config.worktree !== undefined) {
             mergedConfig.worktree = config.worktree;
         }
+        // Merge enableArtifact (last one wins)
+        if (config.enableArtifact !== undefined) {
+            mergedConfig.enableArtifact = config.enableArtifact;
+        }
         // Merge models
         if (config.models) {
             if (!mergedConfig.models)
@@ -1237,5 +1261,6 @@ export function loadMergedWaveConfig(workdir) {
             ? mergedConfig.models
             : undefined,
         worktree: mergedConfig.worktree,
+        enableArtifact: mergedConfig.enableArtifact,
     };
 }

package/dist/services/initializationService.js

@@ -64,6 +64,11 @@ export class InitializationService {
             const phaseStart = performance.now();
             // Load hooks configuration using ConfigurationService
             const configResult = await configurationService.loadMergedConfiguration(workdir);
+            // Rebuild subagent configurations now that settings.json env is loaded
+            // into the snapshot: conditional builtin subagents (model: visionModel
+            // → WAVE_VISION_MODEL) can only register once the env is available.
+            // Plugin agents are preserved by refreshConfigurations.
+            await subagentManager.refreshConfigurations();
             hookManager.loadConfigurationFromWaveConfig(configResult.configuration);
             // Update plugin manager with enabled plugins configuration
             if (configResult.configuration?.enabledPlugins) {

package/dist/tools/agentTool.js

@@ -172,7 +172,8 @@ When using the Agent tool, you must specify a subagent_type parameter to select
                                     success: true,
                                     content: `Agent backgrounded with ID: ${taskId}.${outputPath ? ` Real-time output: ${outputPath}` : ""}`,
                                     shortResult: "Agent backgrounded",
-                                    isManuallyBackgrounded: true,
+                                    backgroundedByUser: true,
+                                    backgroundTaskId: taskId,
                                 });
                             },
                         });

package/dist/tools/artifactTool.d.ts

@@ -0,0 +1,2 @@
+import type { ToolPlugin } from "./types.js";
+export declare const artifactTool: ToolPlugin;

package/dist/tools/artifactTool.js

@@ -0,0 +1,357 @@
+import { readFileSync } from "fs";
+import path from "path";
+import { marked } from "marked";
+import { ARTIFACT_TOOL_NAME } from "../constants/tools.js";
+import { authService, createAuthAwareFetch } from "../services/authService.js";
+import { logger } from "../utils/globalLogger.js";
+import { recordArtifact, getArtifactByFilePath, getRecordedVersion, recordVersion, } from "../services/artifactSession.js";
+// --- Limits ---
+const DEPLOY_TIMEOUT_MS = 30000;
+const PROBE_TIMEOUT_MS = 15000;
+/** Server-side content limit — POSTs above this get a 413. */
+const ARTIFACT_MAX_CONTENT_BYTES = 16 * 1024 * 1024; // 16MB
+const LABEL_MAX_LENGTH = 60;
+const DEFAULT_FAVICON = "📄";
+function isValidFavicon(favicon) {
+    if (!favicon || favicon.trim().length === 0)
+        return false;
+    // Count code points excluding variation selectors (👨‍👩‍👧 counts as 3 and is
+    // rejected — only simple 1-2 emoji are accepted per the server contract).
+    const codePoints = [...favicon].filter((cp) => cp !== "\uFE0F");
+    if (codePoints.length < 1 || codePoints.length > 2)
+        return false;
+    return codePoints.every((cp) => {
+        // \p{Emoji} also matches ASCII digits/letters — plain text is not an emoji.
+        if (/[A-Za-z0-9]/.test(cp))
+            return false;
+        return /\p{Emoji}/u.test(cp);
+    });
+}
+/** Extract the artifact slug from a `{host}/code/artifact/{slug}` URL. */
+function extractSlugFromUrl(url) {
+    try {
+        const parsed = new URL(url);
+        const match = parsed.pathname.match(/^\/code\/artifact\/([^/]+)\/?$/);
+        return match ? decodeURIComponent(match[1]) : null;
+    }
+    catch {
+        return null;
+    }
+}
+function escapeHtml(s) {
+    return s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+}
+/** Render Markdown to a complete HTML document (client-side md→HTML). */
+function renderMarkdown(md, title) {
+    const body = marked.parse(md, { async: false });
+    const titleTag = title ? `<title>${escapeHtml(title)}</title>` : "";
+    return `<!DOCTYPE html><html lang="zh-CN"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">${titleTag}</head><body>${body}</body></html>`;
+}
+/** Probe an artifact's current metadata (`via=model_read` marks model access). */
+async function probeFrame(slug, signal) {
+    const serverUrl = authService.getServerUrl();
+    const authFetch = createAuthAwareFetch(globalThis.fetch);
+    try {
+        const res = await authFetch(`${serverUrl}/api/frame/${encodeURIComponent(slug)}?via=model_read`, { method: "GET", signal });
+        if (res.status === 404)
+            return null;
+        if (!res.ok) {
+            logger?.warn("Artifact probe failed", {
+                slug,
+                status: res.status,
+                statusText: res.statusText,
+            });
+            return null;
+        }
+        return (await res.json());
+    }
+    catch (err) {
+        logger?.warn("Artifact probe error", { slug, error: String(err) });
+        return null;
+    }
+}
+export const artifactTool = {
+    name: ARTIFACT_TOOL_NAME,
+    isConcurrencySafe: false,
+    config: {
+        type: "function",
+        function: {
+            name: ARTIFACT_TOOL_NAME,
+            description: "Publish local HTML or Markdown files as shareable web pages (artifacts). " +
+                "Each publish returns a private URL you can share; the page is only accessible to you " +
+                "unless you change its sharing. Only .html and .md files are supported — inline content " +
+                "is not accepted. Markdown files are rendered to HTML automatically. " +
+                "Pass `url` (an existing artifact URL) to redeploy that artifact, " +
+                "or omit it to republish a file already published in this session. " +
+                "Use `force` to overwrite an artifact that has been updated by someone else.",
+            parameters: {
+                type: "object",
+                properties: {
+                    file_path: {
+                        type: "string",
+                        description: "Path to the .html or .md file to publish (relative to the working directory). The file must exist.",
+                    },
+                    favicon: {
+                        type: "string",
+                        description: "1-2 emoji characters shown as the page favicon (no text, URLs, or HTML). Defaults to 📄.",
+                    },
+                    label: {
+                        type: "string",
+                        description: `Optional short label for the artifact (max ${LABEL_MAX_LENGTH} characters).`,
+                    },
+                    url: {
+                        type: "string",
+                        description: "Existing artifact URL to redeploy, e.g. https://host/code/artifact/abc123. Omit when republishing a file already published earlier in this session.",
+                    },
+                    force: {
+                        type: "boolean",
+                        description: "Set true to overwrite an artifact that was updated since this session last saw it (stale version or conflict).",
+                    },
+                },
+                required: ["file_path"],
+            },
+        },
+    },
+    formatCompactParams: (params) => {
+        const filePath = typeof params.file_path === "string" ? params.file_path : "";
+        const url = typeof params.url === "string" ? params.url : "";
+        return `${ARTIFACT_TOOL_NAME}(${filePath}${url ? ` → ${url}` : ""})`;
+    },
+    execute: async (args, context) => {
+        const filePath = typeof args.file_path === "string" ? args.file_path.trim() : "";
+        if (!filePath) {
+            return {
+                success: false,
+                content: "",
+                error: `${ARTIFACT_TOOL_NAME}: missing required parameter "file_path"`,
+            };
+        }
+        const faviconRaw = typeof args.favicon === "string" ? args.favicon.trim() : "";
+        const favicon = faviconRaw || DEFAULT_FAVICON;
+        if (!isValidFavicon(favicon)) {
+            return {
+                success: false,
+                content: "",
+                error: `${ARTIFACT_TOOL_NAME}: favicon must be 1-2 emoji characters (e.g. "📄" or "🔖"), no text, URLs, or HTML markup`,
+            };
+        }
+        const labelRaw = typeof args.label === "string" ? args.label.trim() : "";
+        const label = labelRaw || undefined;
+        if (label !== undefined && label.length > LABEL_MAX_LENGTH) {
+            return {
+                success: false,
+                content: "",
+                error: `${ARTIFACT_TOOL_NAME}: label must be at most ${LABEL_MAX_LENGTH} characters (got ${label.length})`,
+            };
+        }
+        const force = args.force === true;
+        const urlRaw = typeof args.url === "string" ? args.url.trim() : "";
+        const url = urlRaw || undefined;
+        let slug;
+        if (url) {
+            slug = extractSlugFromUrl(url);
+            if (!slug) {
+                return {
+                    success: false,
+                    content: "",
+                    error: `${ARTIFACT_TOOL_NAME}: url must point to an artifact page ({host}/code/artifact/{slug})`,
+                };
+            }
+        }
+        // Resolve and read the file (relative to the workdir).
+        const absolutePath = path.resolve(context.workdir, filePath);
+        const ext = path.extname(absolutePath).toLowerCase();
+        if (ext !== ".html" && ext !== ".md") {
+            return {
+                success: false,
+                content: "",
+                error: `${ARTIFACT_TOOL_NAME}: only .html and .md files can be published as artifacts (got "${ext || "no extension"}")`,
+            };
+        }
+        let fileContent;
+        try {
+            fileContent = readFileSync(absolutePath, "utf-8");
+        }
+        catch {
+            return {
+                success: false,
+                content: "",
+                error: `${ARTIFACT_TOOL_NAME}: file not found or unreadable: ${filePath}`,
+            };
+        }
+        const content = ext === ".md" ? renderMarkdown(fileContent, label) : fileContent;
+        const contentBytes = Buffer.byteLength(content, "utf-8");
+        if (contentBytes > ARTIFACT_MAX_CONTENT_BYTES) {
+            return {
+                success: false,
+                content: "",
+                error: `${ARTIFACT_TOOL_NAME}: content exceeds the ${Math.floor(ARTIFACT_MAX_CONTENT_BYTES / 1024 / 1024)}MB server limit (${(contentBytes / 1024 / 1024).toFixed(1)}MB). Reduce the file or split it up.`,
+            };
+        }
+        if (!authService.getSSOToken()) {
+            return {
+                success: false,
+                content: "",
+                error: `${ARTIFACT_TOOL_NAME}: not authenticated. Run /login to connect your account before publishing artifacts.`,
+            };
+        }
+        const sessionId = context.sessionId || "";
+        const signal = context.abortSignal
+            ? AbortSignal.any([
+                context.abortSignal,
+                AbortSignal.timeout(DEPLOY_TIMEOUT_MS),
+            ])
+            : AbortSignal.timeout(DEPLOY_TIMEOUT_MS);
+        // Redeploy: probe current metadata for baseVersion, shared-live detection,
+        // and the stale-version guard.
+        let serverVersion;
+        let sharedLive = false;
+        if (url && slug) {
+            const meta = await probeFrame(slug, AbortSignal.timeout(PROBE_TIMEOUT_MS));
+            if (!meta) {
+                return {
+                    success: false,
+                    content: "",
+                    error: `${ARTIFACT_TOOL_NAME}: artifact not found at ${url}. It may have been deleted or the URL is invalid.`,
+                };
+            }
+            serverVersion = meta.version;
+            sharedLive = !!(meta.perm && meta.perm.mode !== "owner" && !meta.shared);
+            const recorded = getRecordedVersion(sessionId, slug);
+            if (recorded !== undefined && recorded !== meta.version && !force) {
+                return {
+                    success: false,
+                    content: "",
+                    error: `${ARTIFACT_TOOL_NAME}: stale version — this artifact has been updated to version ${meta.version} since this session last saw version ${recorded}. Pass "force": true to overwrite it anyway.`,
+                };
+            }
+        }
+        // Permission check: first publish and shared-live redeploys require
+        // confirmation; republishing a file/artifact this session already
+        // confirmed once auto-allows (matching Claude Code's behavior).
+        const publishedThisSession = !!getArtifactByFilePath(sessionId, filePath) ||
+            (slug ? getRecordedVersion(sessionId, slug) !== undefined : false);
+        const needsConfirm = !publishedThisSession || sharedLive;
+        if (context.permissionManager && needsConfirm) {
+            const permissionContext = context.permissionManager.createContext(ARTIFACT_TOOL_NAME, context.permissionMode || "default", context.canUseToolCallback, {
+                file_path: filePath,
+                ...(favicon !== DEFAULT_FAVICON ? { favicon } : {}),
+                ...(label !== undefined ? { label } : {}),
+                ...(url !== undefined ? { url } : {}),
+                ...(force ? { force: true } : {}),
+            }, context.toolCallId);
+            if (sharedLive) {
+                permissionContext.warning =
+                    "此 artifact 处于 shared-live 状态（共享且实时更新），重新部署后所有访问者都会立即看到新内容。";
+                permissionContext.hidePersistentOption = true;
+            }
+            const permissionResult = await context.permissionManager.checkPermission(permissionContext);
+            if (permissionResult.behavior === "deny") {
+                return {
+                    success: false,
+                    content: "",
+                    error: `${ARTIFACT_TOOL_NAME} operation denied by user, reason: ${permissionResult.message || "No reason provided"}`,
+                };
+            }
+        }
+        // Deploy.
+        const serverUrl = authService.getServerUrl();
+        const authFetch = createAuthAwareFetch(globalThis.fetch);
+        const body = {
+            content,
+            favicon,
+            ...(label !== undefined ? { label } : {}),
+            ...(url !== undefined ? { url } : {}),
+            ...(serverVersion !== undefined ? { baseVersion: serverVersion } : {}),
+            ...(force ? { force: true } : {}),
+        };
+        let res;
+        try {
+            res = await authFetch(`${serverUrl}/api/frame/deploy/direct`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(body),
+                signal,
+            });
+        }
+        catch (err) {
+            logger?.warn("Artifact deploy request failed", { error: String(err) });
+            return {
+                success: false,
+                content: "",
+                error: `${ARTIFACT_TOOL_NAME}: failed to reach the server: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+        const data = (await res.json().catch(() => ({})));
+        if (res.status === 201) {
+            const deploy = data;
+            recordArtifact(sessionId, filePath, {
+                url: deploy.url,
+                slug: deploy.slug,
+                version: deploy.version,
+            });
+            const lines = [`Artifact published: ${deploy.url}`];
+            if (deploy.path)
+                lines.push(`Path: ${deploy.path}`);
+            if (deploy.title)
+                lines.push(`Title: ${deploy.title}`);
+            lines.push(`Version: ${deploy.version}`);
+            return {
+                success: true,
+                content: lines.join("\n"),
+                shortResult: `Published ${filePath} → ${deploy.url}`,
+            };
+        }
+        if (res.status === 409) {
+            const live = typeof data.live === "string" ? data.live : undefined;
+            if (live && slug) {
+                recordVersion(sessionId, slug, live);
+            }
+            const serverMessage = typeof data.message === "string"
+                ? data.message
+                : typeof data.error === "string"
+                    ? data.error
+                    : "the artifact has been updated by someone else";
+            return {
+                success: false,
+                content: "",
+                error: `${ARTIFACT_TOOL_NAME}: conflict detected — ${serverMessage}${live ? ` (live version: ${live})` : ""}. Pass "force": true to overwrite the live version.`,
+            };
+        }
+        if (res.status === 413) {
+            return {
+                success: false,
+                content: "",
+                error: `${ARTIFACT_TOOL_NAME}: the published content is too large (server limit is 16MB). Reduce the file or split it up.`,
+            };
+        }
+        if (res.status === 400) {
+            const serverMessage = typeof data.message === "string"
+                ? data.message
+                : typeof data.error === "string"
+                    ? data.error
+                    : "the server rejected the content";
+            return {
+                success: false,
+                content: "",
+                error: `${ARTIFACT_TOOL_NAME}: the server rejected the publish — ${serverMessage}`,
+            };
+        }
+        if (res.status === 401 || res.status === 403) {
+            return {
+                success: false,
+                content: "",
+                error: `${ARTIFACT_TOOL_NAME}: authentication failed (HTTP ${res.status}). Run /login again and retry.`,
+            };
+        }
+        logger?.warn("Artifact deploy unexpected status", {
+            status: res.status,
+            statusText: res.statusText,
+        });
+        return {
+            success: false,
+            content: "",
+            error: `${ARTIFACT_TOOL_NAME}: server returned HTTP ${res.status} ${res.statusText}`,
+        };
+    },
+};

package/dist/tools/bashTool.js

@@ -219,17 +219,14 @@ The working directory persists between commands. Try to maintain your current wo
             const { id: taskId } = backgroundTaskManager.startShell(command, undefined, context.workdir);
             const task = backgroundTaskManager.getTask(taskId);
             const outputPath = task?.outputPath;
-            const backgroundMsg = [
-                `Command started in background with ID: ${taskId}.`,
-                `You will be notified automatically when it completes.`,
-                outputPath
-                    ? `output_file: ${outputPath}`
-                    : `Use ${READ_TOOL_NAME} tool with task_id="${taskId}" to read the output.`,
-            ].join("\n");
+            const backgroundMsg = outputPath
+                ? `Command running in background with ID: ${taskId}. Output is being written to: ${outputPath}`
+                : `Command running in background with ID: ${taskId}. Use ${READ_TOOL_NAME} tool with task_id="${taskId}" to read the output.`;
             return {
                 success: true,
                 content: recoveryNotice + backgroundMsg,
                 shortResult: `Background process ${taskId} started${outputPath ? ` → ${outputPath}` : ""}`,
+                backgroundTaskId: taskId,
             };
         }
         // Foreground execution (original behavior)
@@ -303,9 +300,10 @@ The working directory persists between commands. Try to maintain your current wo
                             const outputPath = task?.outputPath;
                             resolve({
                                 success: true,
-                                content: `Command moved to background with ID: ${taskId}.${outputPath ? ` Real-time output: ${outputPath}` : ""}`,
+                                content: `Command was manually backgrounded by user with ID: ${taskId}.${outputPath ? ` Output is being written to: ${outputPath}` : ""}`,
                                 shortResult: `Process ${taskId} backgrounded`,
-                                isManuallyBackgrounded: true,
+                                backgroundedByUser: true,
+                                backgroundTaskId: taskId,
                             });
                         }
                         else {
@@ -337,8 +335,10 @@ The working directory persists between commands. Try to maintain your current wo
                             logger.info(`[Bash] Command timed out after ${timeout}ms, auto-backgrounded as ${taskId}`);
                             resolve({
                                 success: true,
-                                content: `Command timed out after ${timeout / 1000} seconds and was moved to background with ID: ${taskId}.${outputPath ? ` Real-time output: ${outputPath}` : ""}`,
-                                shortResult: `Process ${taskId} auto-backgrounded (timeout)`,
+                                content: `Command exceeded the timeout (${timeout / 1000}s) and was moved to the background with ID: ${taskId}. It is still running — you will be notified when it completes.${outputPath ? ` Output is being written to: ${outputPath}` : ""}`,
+                                shortResult: `Process ${taskId} auto-backgrounded`,
+                                assistantAutoBackgrounded: true,
+                                backgroundTaskId: taskId,
                             });
                         }
                         else {

package/dist/tools/types.d.ts

@@ -37,7 +37,9 @@ export interface ToolResult {
         data: string;
         mediaType?: string;
     }>;
-    isManuallyBackgrounded?: boolean;
+    backgroundTaskId?: string;
+    backgroundedByUser?: boolean;
+    assistantAutoBackgrounded?: boolean;
     metadata?: Record<string, unknown>;
 }
 export interface ToolContext {