wave-agent-sdk 1.0.6 → 1.0.8

package/builtin/skills/settings/ENV.md

@@ -27,6 +27,7 @@ Wave uses several environment variables to control its core functionality. Varia
 | `WAVE_CUSTOM_HEADERS` | Custom HTTP headers for the AI gateway. Newline-separated `Key: Value` pairs (e.g., `"X-Foo: bar\nAuthorization: Bearer xxx"`). | - |
 | `WAVE_MODEL` | The primary AI model to use for the agent. | `gemini-3-flash` |
 | `WAVE_FAST_MODEL` | The fast AI model to use for quick tasks. | `gemini-2.5-flash` |
+| `WAVE_VISION_MODEL` | Vision-capable model used by the built-in `vision` subagent for image recognition. When set, the built-in `vision` subagent is registered (its frontmatter `model: visionModel` resolves to this value); when unset, the subagent is not loaded. Useful when the main model is fast but non-vision (e.g. DeepSeek). | - (not registered) |
 | `WAVE_MAX_INPUT_TOKENS` | Maximum number of input tokens allowed. | `200000` |
 | `WAVE_MAX_OUTPUT_TOKENS` | Maximum number of output tokens allowed. | `32000` |
 | `WAVE_DISABLE_AUTO_MEMORY` | Set to `1` or `true` to disable the auto-memory feature. | `false` |

package/builtin/skills/settings/MODELS.md

@@ -105,12 +105,15 @@ You can also set the default models Wave uses via environment variables in `sett
   "env": {
     "WAVE_MODEL": "gemini-3-flash",
     "WAVE_FAST_MODEL": "gemini-2.5-flash",
+    "WAVE_VISION_MODEL": "qwen-vl-max",
     "WAVE_MAX_INPUT_TOKENS": "100000",
     "WAVE_MAX_OUTPUT_TOKENS": "4096"
   }
 }
 ```
 
+`WAVE_VISION_MODEL` names a vision-capable model for the built-in `vision` subagent. Setting it registers the subagent, whose frontmatter `model: visionModel` resolves to this value — so a fast non-vision main model can delegate image recognition. Leave it unset to disable the built-in `vision` subagent.
+
 ## Live Reload
 
 Model configurations support **live reload**. When you modify the `models` field or model-related environment variables in `settings.json`, the changes take effect immediately without restarting Wave.

package/builtin/subagents/vision.md

@@ -0,0 +1,18 @@
+---
+name: vision
+description: 'Image recognition specialist that runs on the model specified by the WAVE_VISION_MODEL environment variable. Use this when the current model does not support image recognition but the user has shared an image (identify the image by its "[Image source: <path>]" metadata). Pass the image file path(s) in the prompt; this agent reads the image with the Read tool and returns a detailed text description of its contents.'
+tools: [Read]
+model: visionModel
+---
+
+You are an image recognition specialist. You run on a vision-capable model and your job is to look at image files and return detailed text descriptions of their contents.
+
+When given image file path(s):
+- Use the Read tool on each image path to load it. The Read tool returns the image as base64 image data that you can see directly.
+- Describe the image contents in detail: what is shown, any visible text (transcribe verbatim where relevant), layout, colors, objects, and anything else the caller asked about.
+- If an image cannot be read (file missing, not an image, or too large), report the error clearly and state which path failed.
+- Do not invent or guess content you cannot see — only describe what the image actually shows.
+- Return your description directly as a text message. Do NOT create files.
+- Avoid using emojis in your response.
+
+Complete the image recognition task and report your findings clearly.

package/dist/agent.d.ts

@@ -413,6 +413,17 @@ export declare class Agent {
      * @returns The subagent instance or null if not found
      */
     getSubagentInstance(subagentId: string): import("./managers/subagentManager.js").SubagentInstance | null;
+    /**
+     * Get all subagent configurations visible in this session (built-in,
+     * user, project, and plugin agents).
+     * @returns The list of subagent configurations
+     */
+    getSubagentConfigurations(): import("./utils/subagentParser.js").SubagentConfiguration[];
+    /**
+     * Get currently active subagent instances (status active/initializing).
+     * @returns The list of active subagent instances
+     */
+    getActiveSubagentInstances(): import("./managers/subagentManager.js").SubagentInstance[];
     /**
      * Get the current task list ID
      */

package/dist/agent.js

@@ -973,6 +973,21 @@ export class Agent {
     getSubagentInstance(subagentId) {
         return this.subagentManager.getInstance(subagentId);
     }
+    /**
+     * Get all subagent configurations visible in this session (built-in,
+     * user, project, and plugin agents).
+     * @returns The list of subagent configurations
+     */
+    getSubagentConfigurations() {
+        return this.subagentManager.getConfigurations();
+    }
+    /**
+     * Get currently active subagent instances (status active/initializing).
+     * @returns The list of active subagent instances
+     */
+    getActiveSubagentInstances() {
+        return this.subagentManager.getActiveInstances();
+    }
     /**
      * Get the current task list ID
      */

package/dist/constants/tools.d.ts

@@ -22,3 +22,4 @@ export declare const WEB_FETCH_TOOL_NAME = "WebFetch";
 export declare const ENTER_WORKTREE_TOOL_NAME = "EnterWorktree";
 export declare const EXIT_WORKTREE_TOOL_NAME = "ExitWorktree";
 export declare const WORKFLOW_TOOL_NAME = "Workflow";
+export declare const ARTIFACT_TOOL_NAME = "Artifact";

package/dist/constants/tools.js

@@ -22,3 +22,4 @@ export const WEB_FETCH_TOOL_NAME = "WebFetch";
 export const ENTER_WORKTREE_TOOL_NAME = "EnterWorktree";
 export const EXIT_WORKTREE_TOOL_NAME = "ExitWorktree";
 export const WORKFLOW_TOOL_NAME = "Workflow";
+export const ARTIFACT_TOOL_NAME = "Artifact";

package/dist/index.d.ts

@@ -23,7 +23,9 @@ export * from "./utils/gitUtils.js";
 export * from "./utils/nameGenerator.js";
 export * from "./utils/worktreeSession.js";
 export * from "./utils/worktreeUtils.js";
-export { loadMergedWaveConfig } from "./services/configurationService.js";
+export { loadMergedWaveConfig, loadUserConfigEnv, } from "./services/configurationService.js";
 export * from "./types/index.js";
+export type { SubagentConfiguration } from "./utils/subagentParser.js";
+export type { SubagentInstance } from "./managers/subagentManager.js";
 export * from "./tools/buildTool.js";
 export type { ToolPlugin, ToolResult, ToolContext } from "./tools/types.js";

package/dist/index.js

@@ -27,7 +27,7 @@ export * from "./utils/gitUtils.js";
 export * from "./utils/nameGenerator.js";
 export * from "./utils/worktreeSession.js";
 export * from "./utils/worktreeUtils.js";
-export { loadMergedWaveConfig } from "./services/configurationService.js";
+export { loadMergedWaveConfig, loadUserConfigEnv, } from "./services/configurationService.js";
 export * from "./types/index.js";
 // Export tool building utilities
 export * from "./tools/buildTool.js";

package/dist/managers/aiManager.js

@@ -20,6 +20,14 @@ import { logOTelEvent } from "../telemetry/events.js";
 const MAX_FORK_TURNS = 3;
 /** Max turns for the auto-memory extraction fork. */
 const MAX_AUTO_MEMORY_FORK_TURNS = 5;
+/**
+ * Max consecutive auto-resumes after `finish_reason === "length"` when the
+ * truncated turn produced NO tool calls (aligned with Claude Code's
+ * MAX_OUTPUT_TOKENS_RECOVERY_LIMIT). A tool call resets the counter — it is
+ * real progress. Exhausting the limit terminates the turn with an error
+ * instead of re-planning forever.
+ */
+const MAX_OUTPUT_TOKENS_RECOVERY_LIMIT = 3;
 // Truncate text to `max` chars and append a "… [+N chars]" marker when exceeded.
 // Used for background_tasks description/command fields (≤1000 chars per spec FR-063).
 function truncateWithMarker(text, max) {
@@ -138,6 +146,9 @@ export class AIManager {
             if (this.modelOverride === "fastModel") {
                 modelToUse = parentModelConfig.fastModel;
             }
+            else if (this.modelOverride === "visionModel") {
+                modelToUse = parentModelConfig.visionModel;
+            }
             else if (this.modelOverride !== "inherit") {
                 modelToUse = this.modelOverride;
             }
@@ -1217,6 +1228,10 @@ ${question}`;
                 toolAbortController = this.toolAbortController;
             }
             let turnDepth = turnOffset;
+            // Consecutive truncation recoveries within this turn (no tool calls
+            // in between). Reset to 0 on tool calls / at each sendAIMessage entry,
+            // matching Claude Code's maxOutputTokensRecoveryCount semantics.
+            let maxOutputTokensRecoveryCount = 0;
             inner: while (true) {
                 let llmSpan;
                 try {
@@ -1300,10 +1315,15 @@ ${question}`;
                             // Use parametersChunk as compact param for better performance
                             // No need to extract params or generate compact params during streaming
                             // Update tool block with streaming parameters using parametersChunk as compact param
+                            // `parameters` is only present on start/running/end (authoritative); streaming
+                            // carries only `parametersChunk`, so don't forward `parameters: undefined`
+                            // (it would overwrite the accumulated block params in consumers)
                             this.messageManager.updateToolBlock({
                                 id: toolCall.id,
                                 name: toolCall.name,
-                                parameters: toolCall.parameters,
+                                ...(toolCall.parameters !== undefined
+                                    ? { parameters: toolCall.parameters }
+                                    : {}),
                                 parametersChunk: toolCall.parametersChunk,
                                 stage: toolCall.stage || "streaming", // Default to streaming if stage not provided
                             });
@@ -1383,9 +1403,6 @@ ${question}`;
                             ...(result.usage.cache_creation_input_tokens !== undefined && {
                                 cache_creation_input_tokens: result.usage.cache_creation_input_tokens,
                             }),
-                            ...(result.usage.cache_creation && {
-                                cache_creation: result.usage.cache_creation,
-                            }),
                         };
                     }
                     // Set usage on the assistant message if available
@@ -1465,13 +1482,34 @@ ${question}`;
                             const lastMessage = this.messageManager.getMessages()[this.messageManager.getMessages().length - 1];
                             const toolBlocks = lastMessage?.blocks.filter((block) => block.type === "tool") || [];
                             const hasBackgrounded = toolBlocks.length > 0 &&
-                                toolBlocks.some((block) => block.isManuallyBackgrounded);
+                                toolBlocks.some((block) => block.backgroundedByUser);
                             if (hasBackgrounded) {
                                 logger?.info("Some tools were manually backgrounded, stopping.");
                             }
                             else if (!isCurrentlyAborted) {
+                                // If the response was truncated WITHOUT any tool calls,
+                                // enforce the consecutive recovery limit (aligned with Claude
+                                // Code's MAX_OUTPUT_TOKENS_RECOVERY_LIMIT = 3). Re-planning
+                                // loops that never produce output would otherwise continue
+                                // until the platform kills the task.
+                                if (result.finish_reason === "length" &&
+                                    toolCalls.length === 0 &&
+                                    maxOutputTokensRecoveryCount >=
+                                        MAX_OUTPUT_TOKENS_RECOVERY_LIMIT) {
+                                    this.messageManager.addErrorBlock(`Response exceeded the output token limit ${MAX_OUTPUT_TOKENS_RECOVERY_LIMIT + 1} consecutive times without producing output or tool calls. Stopped to avoid an infinite loop. Break the remaining work into smaller pieces and try again.`);
+                                    break inner;
+                                }
                                 // If response was truncated, add a hidden continuation message
                                 if (result.finish_reason === "length") {
+                                    if (toolCalls.length === 0) {
+                                        // Pure truncation — count toward the recovery limit.
+                                        maxOutputTokensRecoveryCount++;
+                                    }
+                                    else {
+                                        // Truncated with tool calls — real progress, reset the
+                                        // consecutive counter.
+                                        maxOutputTokensRecoveryCount = 0;
+                                    }
                                     this.messageManager.addUserMessage({
                                         content: "Output token limit hit. Resume directly — no apology, no recap of what you were doing. Pick up mid-thought if that is where the cut happened. Break remaining work into smaller pieces.",
                                         isMeta: true,
@@ -1884,7 +1922,9 @@ ${question}`;
                 name: toolName,
                 compactParams,
                 shortResult: toolResult.shortResult,
-                isManuallyBackgrounded: toolResult.isManuallyBackgrounded,
+                backgroundTaskId: toolResult.backgroundTaskId,
+                backgroundedByUser: toolResult.backgroundedByUser,
+                assistantAutoBackgrounded: toolResult.assistantAutoBackgrounded,
                 startLineNumber: toolResult.startLineNumber,
                 images: toolResult.images,
                 timestamp: Date.now(),
@@ -1903,7 +1943,6 @@ ${question}`;
                 stage: "end",
                 name: toolName,
                 compactParams,
-                isManuallyBackgrounded: false,
                 timestamp: Date.now(),
             });
         }

package/dist/managers/messageManager.d.ts

@@ -26,7 +26,7 @@ export interface MessageManagerCallbacks {
     onCompactionStateChange?: (isCompacting: boolean) => void;
     onAddBangMessage?: (command: string, messageId: string) => void;
     onUpdateBangMessage?: (command: string, output: string, messageId: string) => void;
-    onCompleteBangMessage?: (command: string, exitCode: number, messageId: string) => void;
+    onCompleteBangMessage?: (command: string, exitCode: number, messageId: string, output?: string) => void;
     onInfoBlockAdded?: (content: string) => void;
     onShowRewind?: () => void;
     onFileHistoryBlockAdded?: (snapshots: import("../types/reversion.js").FileSnapshot[]) => void;

package/dist/managers/messageManager.js

@@ -446,7 +446,7 @@ export class MessageManager {
         });
         this.setMessages(updatedMessages);
         const messageId = this.findBangMessageId(command) ?? "";
-        this.callbacks.onCompleteBangMessage?.(command, exitCode, messageId);
+        this.callbacks.onCompleteBangMessage?.(command, exitCode, messageId, output?.trim());
     }
     /**
      * Find the message ID of the most recent message containing a bang block
@@ -686,7 +686,9 @@ export class MessageManager {
                 stage: "end",
                 success: false,
                 error: errorMessage,
-                isManuallyBackgrounded: block.isManuallyBackgrounded,
+                backgroundTaskId: block.backgroundTaskId,
+                backgroundedByUser: block.backgroundedByUser,
+                assistantAutoBackgrounded: block.assistantAutoBackgrounded,
                 timestamp,
             });
         }
@@ -730,7 +732,11 @@ export class MessageManager {
         // only sees messages from the latest compact summary forward — matching
         // the compact and resume behaviors (which also fold memory).
         this.setMessages(sliceFromLastCompact(newMessages));
-        this.savedMessageCount = newMessages.length;
+        // savedMessageCount tracks in-memory progress, so it must be the folded
+        // length. Using the full disk count here would make saveSession's
+        // slice(savedMessageCount) empty after a rewind past a compact boundary
+        // and silently drop every subsequent message from the session file.
+        this.savedMessageCount = this.messages.length;
     }
     /**
      * Rewrite the session file with the current messages.

package/dist/managers/permissionManager.d.ts

@@ -82,6 +82,11 @@ export declare class PermissionManager {
      * Get all instance-specific denied rules
      */
     getInstanceDeniedRules(): string[];
+    /**
+     * Add an instance-level allowed rule (session-level, in-memory only).
+     * Unlike addPermissionRule, this does NOT persist to settings.local.json.
+     */
+    addInstanceAllowedRule(rule: string): void;
     /**
      * Get all additional directories
      */

package/dist/managers/permissionManager.js

@@ -8,7 +8,7 @@
 import path from "node:path";
 import { minimatch } from "minimatch";
 import { RESTRICTED_TOOLS } from "../types/permissions.js";
-import { splitBashCommand, stripEnvVars, stripRedirections, hasWriteRedirections, getSmartPrefix, isDangerousFind, hasCommandSubstitution, hasProcessSubstitution, hasSedInPlace, DANGEROUS_COMMANDS, READ_ONLY_COMMANDS, } from "../utils/bashParser.js";
+import { splitBashCommand, stripEnvVars, stripRedirections, hasWriteRedirections, getSmartPrefix, isDangerousFind, hasCommandSubstitution, hasProcessSubstitution, hasSedInPlace, stripGitScopePrefix, DANGEROUS_COMMANDS, READ_ONLY_COMMANDS, } from "../utils/bashParser.js";
 import { isPathInside } from "../utils/pathSafety.js";
 import { BASH_TOOL_NAME, EDIT_TOOL_NAME, WRITE_TOOL_NAME, READ_TOOL_NAME, ASK_USER_QUESTION_TOOL_NAME, } from "../constants/tools.js";
 const DEFAULT_ALLOWED_RULES = [
@@ -140,6 +140,15 @@ export class PermissionManager {
     getInstanceDeniedRules() {
         return [...this.instanceDeniedRules];
     }
+    /**
+     * Add an instance-level allowed rule (session-level, in-memory only).
+     * Unlike addPermissionRule, this does NOT persist to settings.local.json.
+     */
+    addInstanceAllowedRule(rule) {
+        if (!this.instanceAllowedRules.includes(rule)) {
+            this.instanceAllowedRules.push(rule);
+        }
+    }
     /**
      * Get all additional directories
      */
@@ -676,7 +685,14 @@ export class PermissionManager {
                 .replace(/\*/g, ".*"); // Replace * with .*
             const regex = new RegExp(`^${regexPattern}$`, "s");
             const matched = regex.test(processedPart);
-            return matched;
+            if (matched)
+                return true;
+            // Leading git global scope flags (e.g. `git -C <path>`) only change the
+            // target repository, not the subcommand being run, so rules like
+            // Bash(git status*) also cover `git -C <path> status`. The raw command
+            // is checked first so path-specific rules (e.g. deny rules on
+            // `git -C /secret status`) still match.
+            return regex.test(stripGitScopePrefix(processedPart));
         }
         // Handle path-based rules (e.g., "Read(**/*.env)")
         const pathTools = [READ_TOOL_NAME, WRITE_TOOL_NAME, EDIT_TOOL_NAME];

package/dist/managers/pluginManager.d.ts

@@ -6,10 +6,19 @@ export interface PluginManagerOptions {
 }
 export declare class PluginManager {
     private container;
+    /**
+     * Read-only helper scripts shipped by builtin plugins that the agent runs via
+     * Bash. When such a plugin is enabled, its rules are registered as instance
+     * level allow rules (in-memory only, never persisted) so the scripts run
+     * without a permission prompt. Wildcards keep the rules valid across install
+     * locations; each rule anchors on the script filename.
+     */
+    private static readonly BUILTIN_PLUGIN_ALLOW_RULES;
     private plugins;
     private workdir;
     private enabledPlugins;
     constructor(container: Container, options: PluginManagerOptions);
+    private get permissionManager();
     private get skillManager();
     private get hookManager();
     private get lspManager();

package/dist/managers/pluginManager.js

@@ -11,6 +11,9 @@ export class PluginManager {
         this.workdir = options.workdir;
         this.enabledPlugins = options.enabledPlugins || {};
     }
+    get permissionManager() {
+        return this.container.get("PermissionManager");
+    }
     get skillManager() {
         return this.container.get("SkillManager");
     }
@@ -221,6 +224,13 @@ export class PluginManager {
                 if (this.enabledPlugins[`${entry.name}@builtin`] !== true)
                     continue;
                 await this.loadSinglePlugin(path.join(builtinDir, entry.name));
+                // Register allow rules only after the plugin actually loaded, so a
+                // failed load never leaves permission grants behind.
+                if (this.plugins.has(entry.name)) {
+                    for (const rule of PluginManager.BUILTIN_PLUGIN_ALLOW_RULES[entry.name] || []) {
+                        this.permissionManager?.addInstanceAllowedRule(rule);
+                    }
+                }
             }
         }
         catch (error) {
@@ -240,3 +250,13 @@ export class PluginManager {
         return this.plugins.get(name);
     }
 }
+/**
+ * Read-only helper scripts shipped by builtin plugins that the agent runs via
+ * Bash. When such a plugin is enabled, its rules are registered as instance
+ * level allow rules (in-memory only, never persisted) so the scripts run
+ * without a permission prompt. Wildcards keep the rules valid across install
+ * locations; each rule anchors on the script filename.
+ */
+PluginManager.BUILTIN_PLUGIN_ALLOW_RULES = {
+    sdd: ["Bash(node *spec-count.js*)"],
+};

package/dist/managers/subagentManager.d.ts

@@ -87,6 +87,18 @@ export declare class SubagentManager {
      * Load all available subagent configurations and cache them
      */
     loadConfigurations(): Promise<SubagentConfiguration[]>;
+    /**
+     * Rebuild the cached subagent configurations. Called after settings.json
+     * env becomes available (post loadMergedConfiguration) so conditional
+     * builtin subagents (e.g. `model: visionModel` requiring WAVE_VISION_MODEL)
+     * register correctly. Plugin agents are preserved across the rebuild.
+     */
+    refreshConfigurations(): Promise<SubagentConfiguration[]>;
+    /**
+     * Get the merged environment (OS env overlaid with settings.json env) used
+     * for conditional subagent registration (e.g. WAVE_VISION_MODEL).
+     */
+    private getMergedEnv;
     /**
      * Get cached configurations synchronously (must call loadConfigurations first)
      */

package/dist/managers/subagentManager.js

@@ -70,10 +70,40 @@ export class SubagentManager {
     async loadConfigurations() {
         if (this.cachedConfigurations === null) {
             const { loadSubagentConfigurations } = await import("../utils/subagentParser.js");
-            this.cachedConfigurations = await loadSubagentConfigurations(this.workdir);
+            this.cachedConfigurations = await loadSubagentConfigurations(this.workdir, this.getMergedEnv());
         }
         return this.cachedConfigurations;
     }
+    /**
+     * Rebuild the cached subagent configurations. Called after settings.json
+     * env becomes available (post loadMergedConfiguration) so conditional
+     * builtin subagents (e.g. `model: visionModel` requiring WAVE_VISION_MODEL)
+     * register correctly. Plugin agents are preserved across the rebuild.
+     */
+    async refreshConfigurations() {
+        // Preserve plugin agents (namespaced `pluginName:agentName`) across the rebuild
+        const pluginAgents = (this.cachedConfigurations ?? []).filter((config) => config.name.includes(":"));
+        this.cachedConfigurations = null;
+        await this.loadConfigurations();
+        for (const agent of pluginAgents) {
+            this.cachedConfigurations.push(agent);
+        }
+        // Re-sort by priority then name (matches registerPluginAgents)
+        this.cachedConfigurations.sort((a, b) => {
+            if (a.priority !== b.priority)
+                return a.priority - b.priority;
+            return a.name.localeCompare(b.name);
+        });
+        return this.cachedConfigurations;
+    }
+    /**
+     * Get the merged environment (OS env overlaid with settings.json env) used
+     * for conditional subagent registration (e.g. WAVE_VISION_MODEL).
+     */
+    getMergedEnv() {
+        return (this.configurationService?.getMergedEnv?.() ??
+            process.env);
+    }
     /**
      * Get cached configurations synchronously (must call loadConfigurations first)
      */
@@ -95,7 +125,7 @@ export class SubagentManager {
         }
         // Fall back to filesystem scan for non-plugin agents
         const { findSubagentByName } = await import("../utils/subagentParser.js");
-        return findSubagentByName(name, this.workdir);
+        return findSubagentByName(name, this.workdir, this.getMergedEnv());
     }
     /**
      * Register plugin agents into the cached configurations.

package/dist/managers/toolManager.js

@@ -9,6 +9,8 @@ import { cronCreateTool } from "../tools/cronCreateTool.js";
 import { cronDeleteTool } from "../tools/cronDeleteTool.js";
 import { cronListTool } from "../tools/cronListTool.js";
 import { webFetchTool } from "../tools/webFetchTool.js";
+import { artifactTool } from "../tools/artifactTool.js";
+import { isArtifactEnabled } from "../services/artifactAvailability.js";
 // New tools
 import { globTool } from "../tools/globTool.js";
 import { grepTool } from "../tools/grepTool.js";
@@ -95,6 +97,11 @@ class ToolManager {
             exitWorktreeTool,
             workflowTool,
         ];
+        // Artifact is a feature-gated tool: not registered at all while the frame
+        // backend is not live, unless settings.json opts in via enableArtifact: true.
+        if (isArtifactEnabled(this.container.get("Workdir"))) {
+            builtInTools.push(artifactTool);
+        }
         for (const tool of builtInTools) {
             if (this.shouldEnableTool(tool.name)) {
                 this.toolsRegistry.set(tool.name, tool);

package/dist/services/aiService.d.ts

@@ -1,7 +1,6 @@
 import { ChatCompletionMessageToolCall } from "openai/resources";
 import { ChatCompletionMessageParam, ChatCompletionFunctionTool } from "openai/resources.js";
-import type { GatewayConfig, ModelConfig } from "../types/index.js";
-import { type ClaudeUsage } from "../utils/cacheControlUtils.js";
+import type { GatewayConfig, ModelConfig, Usage } from "../types/index.js";
 import { type SystemPromptBlock } from "../prompts/index.js";
 /**
  * Resets the rate limiter state. Primarily used for testing.
@@ -29,7 +28,7 @@ export interface CallAgentOptions {
     onToolUpdate?: (toolCall: {
         id: string;
         name: string;
-        parameters: string;
+        parameters?: string;
         parametersChunk?: string;
         stage?: "start" | "streaming" | "running" | "end";
     }) => void;
@@ -40,7 +39,7 @@ export interface CallAgentResult {
     content?: string;
     tool_calls?: ChatCompletionMessageToolCall[];
     reasoning_content?: string;
-    usage?: ClaudeUsage;
+    usage?: Usage;
     finish_reason?: "stop" | "length" | "tool_calls" | "content_filter" | "function_call" | null;
     response_headers?: Record<string, string>;
     additionalFields?: Record<string, unknown>;

package/dist/services/aiService.js

@@ -202,17 +202,9 @@ export async function callAgent(options) {
             });
             const finalMessage = response.choices[0]?.message;
             const finishReason = response.choices[0]?.finish_reason || null;
-            let totalUsage = response.usage
-                ? {
-                    prompt_tokens: response.usage.prompt_tokens,
-                    completion_tokens: response.usage.completion_tokens,
-                    total_tokens: response.usage.total_tokens,
-                }
+            const totalUsage = response.usage
+                ? extendUsageWithCacheMetrics(response.usage)
                 : undefined;
-            // Extend usage with cache metrics (Claude top-level + OpenAI prompt_tokens_details)
-            if (totalUsage && response.usage) {
-                totalUsage = extendUsageWithCacheMetrics(totalUsage, response.usage);
-            }
             const result = {};
             if (finalMessage) {
                 const { content: finalContent, tool_calls: finalToolCalls, reasoning_content: finalReasoningContent, ...otherFields } = finalMessage;
@@ -353,14 +345,8 @@ async function processStreamingResponse(stream, onContentUpdate, onToolUpdate, o
             }
             // Check for usage information in any chunk
             if (chunk.usage) {
-                let chunkUsage = {
-                    prompt_tokens: chunk.usage.prompt_tokens,
-                    completion_tokens: chunk.usage.completion_tokens,
-                    total_tokens: chunk.usage.total_tokens,
-                };
-                // Extend usage with cache metrics (Claude top-level + OpenAI prompt_tokens_details)
-                chunkUsage = extendUsageWithCacheMetrics(chunkUsage, chunk.usage);
-                usage = chunkUsage;
+                // Extend usage with cache metrics from OpenAI prompt_tokens_details
+                usage = extendUsageWithCacheMetrics(chunk.usage);
             }
             // Check for finish_reason in the choice
             const choice = chunk.choices?.[0];
@@ -439,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 &&
@@ -448,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,7 @@
+/** 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.
+ * Explicit `enableArtifact` in merged settings wins over the code default.
+ */
+export declare function isArtifactEnabled(workdir?: string): boolean;

package/dist/services/artifactAvailability.js

@@ -0,0 +1,26 @@
+/**
+ * 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";
+/** 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.
+ * Explicit `enableArtifact` in merged settings wins over the code default.
+ */
+export function isArtifactEnabled(workdir) {
+    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;