wave-agent-sdk 1.0.7 → 1.0.9

package/dist/services/aiService.d.ts

@@ -28,7 +28,7 @@ export interface CallAgentOptions {
     onToolUpdate?: (toolCall: {
         id: string;
         name: string;
-        parameters: string;
+        parameters?: string;
         parametersChunk?: string;
         stage?: "start" | "streaming" | "running" | "end";
     }) => void;

package/dist/services/aiService.js

@@ -425,7 +425,9 @@ async function processStreamingResponse(stream, onContentUpdate, onToolUpdate, o
                     if (functionDelta.arguments) {
                         existingCall.function.arguments += functionDelta.arguments;
                     }
-                    // Emit streaming updates for all chunks with actual content (including first chunk)
+                    // Emit streaming updates for all chunks with actual content (including first chunk).
+                    // Streaming carries only the delta `parametersChunk` — consumers accumulate it;
+                    // authoritative `parameters` arrives at `start` (empty) / `running` / `end`.
                     if (onToolUpdate &&
                         existingCall.function.name &&
                         functionDelta.arguments &&
@@ -434,7 +436,6 @@ async function processStreamingResponse(stream, onContentUpdate, onToolUpdate, o
                         onToolUpdate({
                             id: existingCall.id,
                             name: existingCall.function.name,
-                            parameters: existingCall.function.arguments,
                             parametersChunk: functionDelta.arguments,
                             stage: "streaming",
                         });

package/dist/services/artifactAvailability.d.ts

@@ -0,0 +1,9 @@
+/** Code default for Artifact availability. Flip to true after the frame backend goes live. */
+export declare const ARTIFACT_DEFAULT_ENABLED = false;
+/**
+ * Whether the Artifact tool should be registered / usable for the given workdir.
+ * Resolution order: remote managed settings (`enableArtifact` from
+ * `GET /api/wave/settings`, admin override) → explicit `enableArtifact` in local
+ * merged settings → code default.
+ */
+export declare function isArtifactEnabled(workdir?: string): boolean;

package/dist/services/artifactAvailability.js

@@ -0,0 +1,34 @@
+/**
+ * Artifact feature availability.
+ *
+ * The frame backend (`POST /api/frame/deploy/direct`) is not live yet, so the
+ * code default is DISABLED. Internal beta / gradual rollout enables the feature
+ * via settings.json `enableArtifact: true` without code changes. Once the
+ * backend goes live, flip `ARTIFACT_DEFAULT_ENABLED` to `true` so an unset
+ * `enableArtifact` defaults to enabled (matching Claude Code's `enableArtifact`
+ * "unset follows feature availability" semantics).
+ */
+import { loadMergedWaveConfig } from "./configurationService.js";
+import { getRemoteSettingsSync } from "./remoteSettingsService.js";
+/** Code default for Artifact availability. Flip to true after the frame backend goes live. */
+export const ARTIFACT_DEFAULT_ENABLED = false;
+/**
+ * Whether the Artifact tool should be registered / usable for the given workdir.
+ * Resolution order: remote managed settings (`enableArtifact` from
+ * `GET /api/wave/settings`, admin override) → explicit `enableArtifact` in local
+ * merged settings → code default.
+ */
+export function isArtifactEnabled(workdir) {
+    // Remote managed settings win (same last-write-wins semantics as `model`).
+    const remote = getRemoteSettingsSync();
+    if (remote?.enableArtifact !== undefined) {
+        return remote.enableArtifact;
+    }
+    if (workdir) {
+        const config = loadMergedWaveConfig(workdir);
+        if (config?.enableArtifact !== undefined) {
+            return config.enableArtifact;
+        }
+    }
+    return ARTIFACT_DEFAULT_ENABLED;
+}

package/dist/services/artifactSession.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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.
+ */
+export interface ArtifactRecord {
+    url: string;
+    slug: string;
+    version: string;
+}
+/** Record a successful publish so same-session republishes auto-allow. */
+export declare function recordArtifact(sessionId: string, filePath: string, record: ArtifactRecord): void;
+/** Look up an artifact previously published in this session by file path. */
+export declare function getArtifactByFilePath(sessionId: string, filePath: string): ArtifactRecord | undefined;
+/** Latest version of a slug this session has observed (publish, conflict, or read). */
+export declare function getRecordedVersion(sessionId: string, slug: string): string | undefined;
+/** Record an observed version (from a publish, a 409 conflict, or a WebFetch read). */
+export declare function recordVersion(sessionId: string, slug: string, version: string): void;
+/** Clear all session-scoped artifact state (used when a session ends). */
+export declare function clearArtifactSession(sessionId: string): void;

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

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) {
@@ -1209,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)
@@ -1247,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/services/remoteSettingsService.js

@@ -307,6 +307,8 @@ export function mergeRemoteSettings(localMerged, remote) {
         result.marketplaces = remote.marketplaces;
     if (remote.enabledPlugins !== undefined)
         result.enabledPlugins = remote.enabledPlugins;
+    if (remote.enableArtifact !== undefined)
+        result.enableArtifact = remote.enableArtifact;
     return result;
 }
 /**

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}`,
+        };
+    },
+};