vigthoria-cli 1.10.51 → 1.10.55

package/dist/utils/api.js

@@ -9,6 +9,8 @@ import https from 'https';
 import net from 'net';
 import path from 'path';
 import WebSocket from 'ws';
+import { buildSemanticContext } from './context-ranker.js';
+import { getChangedFiles } from './workspace-cache.js';
 export const VIGTHORIA_HUB_CREDITS_URL = 'https://hub.vigthoria.io/credits';
 export const VIGTHORIA_SERVER_TEMPORARILY_UNAVAILABLE_MESSAGE = 'Vigthoria Server is temporarily not available. Please try again later. If the issue persists, please contact support.';
 export class CLIError extends Error {
@@ -282,6 +284,11 @@ export class APIClient {
     vigFlowTokens = new Map();
     _httpsAgent = null;
     lastChatTransportErrors = [];
+    clientToolErrors = [];
+    pendingV3ClientToolTasks = new Set();
+    /** Tracks files mutated via client_tool_request during an active V3 SSE stream. */
+    activeV3StreamedFiles = null;
+    activeV3StreamContext = null;
     constructor(config, logger) {
         this.config = config;
         this.logger = logger;
@@ -631,6 +638,13 @@ export class APIClient {
         }
         return `${baseUrl}/api/v3-agent/continue`;
     }
+    getV3AgentBackgroundUrl(baseUrl, suffix = '') {
+        const cleanSuffix = suffix ? `/${suffix.replace(/^\/+/, '')}` : '';
+        if (/127\.0\.0\.1:8030|localhost:8030/.test(baseUrl)) {
+            return `${baseUrl}/api/agent/background${cleanSuffix}`;
+        }
+        return `${baseUrl}/api/v3-agent/background${cleanSuffix}`;
+    }
     getOperatorBaseUrls() {
         const configuredModelsApiUrl = String(this.config.get('modelsApiUrl') || 'https://api.vigthoria.io').replace(/\/$/, '');
         const urls = [
@@ -720,7 +734,7 @@ export class APIClient {
                 continue;
             }
             for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
-                if (entry.name === '.git' || entry.name === 'node_modules') {
+                if (entry.name === '.git' || entry.name === 'node_modules' || entry.name === '.vigthoria') {
                     continue;
                 }
                 const fullPath = path.join(current, entry.name);
@@ -1410,11 +1424,18 @@ export class APIClient {
         const targetPath = resolvedContext.targetPath || resolvedContext.projectPath || resolvedContext.workspacePath || resolvedContext.projectRoot || process.cwd();
         const localWorkspacePath = this.resolveAgentTargetPath(resolvedContext);
         const serverWorkspacePath = this.resolveServerBindableWorkspacePath(resolvedContext);
-        const localWorkspaceSummary = this.buildLocalWorkspaceSummary(localWorkspacePath);
+        const promptFocus = String(resolvedContext.rawPrompt || resolvedContext.contextualPrompt || resolvedContext.prompt || '');
+        const localWorkspaceSummary = this.buildLocalWorkspaceSummary(localWorkspacePath, promptFocus);
         const requestedModel = String(resolvedContext.model || resolvedContext.requestedModel || 'agent');
         const resolvedModel = this.resolvePermittedModelId(requestedModel);
         const localWorkspaceName = this.getDisplayWorkspaceName(localWorkspacePath);
         const localWorkspaceRef = localWorkspaceName ? `vigthoria://local-workspace/${localWorkspaceName}` : null;
+        const executionSurface = String(resolvedContext.executionSurface || resolvedContext.clientSurface || 'cli');
+        const localMachineCapable = resolvedContext.localMachineCapable !== false;
+        const clientToolExecution = resolvedContext.clientToolExecution === false
+            ? false
+            : (resolvedContext.clientToolExecution === true
+                || (localMachineCapable && ['cli', 'fork', 'local-ide', 'desktop', 'local'].includes(executionSurface)));
         const publicRuntimeEnvironment = this.buildPublicRuntimeEnvironment(resolvedContext.agentRuntime, {
             localWorkspacePath,
             serverWorkspacePath,
@@ -1448,7 +1469,9 @@ export class APIClient {
             legacyFallbackAllowed: resolvedContext.legacyFallbackAllowed === true,
             executionSurface: resolvedContext.executionSurface || 'cli',
             clientSurface: resolvedContext.clientSurface || 'cli',
-            localMachineCapable: resolvedContext.localMachineCapable !== false,
+            localMachineCapable,
+            clientToolExecution,
+            client_tool_execution: clientToolExecution,
             runtimeEnvironment: publicRuntimeEnvironment,
             workspacePath: effectiveWorkspacePath,
             projectPath: effectiveWorkspacePath,
@@ -1471,6 +1494,11 @@ export class APIClient {
             requestStartedAt: resolvedContext.requestStartedAt,
             subscriptionPlan: this.config.getNormalizedPlan() || null,
             email: this.config.get('email') || null,
+            vigthoriaBrain: resolvedContext.vigthoriaBrain || null,
+            vigthoria_brain: resolvedContext.vigthoriaBrain || null,
+            codebaseContext: resolvedContext.codebaseContext || '',
+            accountBrainContext: resolvedContext.accountBrainContext || '',
+            projectMemory: resolvedContext.projectMemory || '',
         };
         return this.compactV3Context(payload);
     }
@@ -1602,6 +1630,8 @@ export class APIClient {
             contextId: resolvedContext.contextId,
             traceId: resolvedContext.traceId,
             requestStartedAt: resolvedContext.requestStartedAt,
+            vigthoriaBrain: resolvedContext.vigthoriaBrain || null,
+            vigthoria_brain: resolvedContext.vigthoriaBrain || null,
         });
     }
     extractEmergencyAppName(message = '', fallback = 'Signal Desk') {
@@ -2075,7 +2105,7 @@ menu {
         const headers = await this.getMcpHeaders();
         const localWorkspacePath = this.resolveAgentTargetPath(executionContext);
         const workspacePath = this.resolveServerBindableWorkspacePath(executionContext);
-        const localWorkspaceSummary = this.buildLocalWorkspaceSummary(localWorkspacePath);
+        const localWorkspaceSummary = this.buildLocalWorkspaceSummary(localWorkspacePath, String(executionContext.rawPrompt || executionContext.contextualPrompt || executionContext.prompt || ''));
         const metadata = {
             source: 'vigthoria-cli',
             sharedContextId: executionContext.contextId,
@@ -2236,7 +2266,7 @@ menu {
             cwd: serverBindableWorkspace ? paths.serverWorkspacePath || null : (localName ? `vigthoria://local-workspace/${localName}` : null),
         };
     }
-    buildLocalWorkspaceSummary(rootPath) {
+    buildLocalWorkspaceSummary(rootPath, requestFocus = '') {
         if (!rootPath || !fs.existsSync(rootPath)) {
             return null;
         }
@@ -2247,8 +2277,31 @@ menu {
                 files: [],
             };
             const snapshot = this.getAgentWorkspaceSnapshot(rootPath);
+            const candidatePaths = snapshot.paths.filter((entry) => !/(^|[\/\\])\.vigthoria([\/\\]|$)/.test(entry));
+            let orderedPaths = candidatePaths;
+            try {
+                const ranked = buildSemanticContext(rootPath, requestFocus, 60).topFiles.map((file) => file.path);
+                const changes = getChangedFiles(rootPath, candidatePaths);
+                const ordered = new Set();
+                for (const filePath of changes.changed)
+                    ordered.add(filePath);
+                for (const filePath of ranked)
+                    ordered.add(filePath);
+                for (const filePath of changes.unchanged)
+                    ordered.add(filePath);
+                orderedPaths = Array.from(ordered);
+                summary.semanticRank = ranked.slice(0, 20);
+                summary.changeSummary = {
+                    changed: changes.changed.length,
+                    unchanged: changes.unchanged.length,
+                    total: changes.total,
+                };
+            }
+            catch {
+                orderedPaths = candidatePaths;
+            }
             summary.fileCount = snapshot.fileCount;
-            summary.files = snapshot.paths.slice(0, 40);
+            summary.files = orderedPaths.slice(0, 40);
             const packageJsonPath = path.join(rootPath, 'package.json');
             if (fs.existsSync(packageJsonPath)) {
                 const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
@@ -2266,7 +2319,7 @@ menu {
             }
             // Hydrate workspace: include actual file contents so the V3 server
             // can populate the remote workspace before the agent starts.
-            summary.workspaceFiles = this.collectWorkspaceFileContents(rootPath, snapshot.paths);
+            summary.workspaceFiles = this.collectWorkspaceFileContents(rootPath, orderedPaths);
             return summary;
         }
         catch (error) {
@@ -2302,6 +2355,8 @@ menu {
                 continue;
             if (/(^|[\/\\])\.(git|hg)([\/\\]|$)/.test(relativePath))
                 continue;
+            if (/(^|[\/\\])\.vigthoria([\/\\]|$)/.test(relativePath))
+                continue;
             const absolutePath = path.join(rootPath, relativePath);
             try {
                 const stat = fs.statSync(absolutePath);
@@ -2481,6 +2536,19 @@ menu {
             return;
         }
         if (event.type !== 'tool_call') {
+            if (event.type === 'tool_result' && event.success) {
+                const name = String(event.name || event.tool || '').trim();
+                const args = event.arguments || {};
+                const targetPath = typeof event.target === 'string'
+                    ? event.target
+                    : (typeof args.path === 'string' ? args.path : '');
+                if ((name === 'write_file' || name === 'edit_file') && targetPath) {
+                    const filePath = this.normalizeAgentWorkspaceRelativePath(targetPath, serverRoot || undefined);
+                    if (filePath && typeof args.content === 'string') {
+                        streamedFiles[filePath] = args.content;
+                    }
+                }
+            }
             return;
         }
         const args = event.arguments || {};
@@ -2533,6 +2601,178 @@ menu {
         }
         return false;
     }
+    resolveV3ClientToolPath(rootPath, rawPath) {
+        const relativePath = this.normalizeAgentWorkspaceRelativePath(String(rawPath || '.'), rootPath);
+        if (!relativePath && String(rawPath || '.').trim() !== '.') {
+            return null;
+        }
+        const absolutePath = path.resolve(rootPath, relativePath || '.');
+        const resolvedRoot = path.resolve(rootPath);
+        if (absolutePath !== resolvedRoot && !absolutePath.startsWith(resolvedRoot + path.sep)) {
+            return null;
+        }
+        return { relativePath: relativePath || '.', absolutePath };
+    }
+    recordV3ClientToolMutation(event, context, result) {
+        if (!result.success) {
+            return;
+        }
+        const name = String(event.name || event.tool || '').trim();
+        if (name !== 'write_file' && name !== 'edit_file') {
+            return;
+        }
+        const args = event.arguments || {};
+        const rootPath = this.resolveAgentTargetPath(context);
+        if (!rootPath) {
+            return;
+        }
+        const target = this.resolveV3ClientToolPath(rootPath, args.path || '.');
+        if (!target) {
+            return;
+        }
+        const bucket = this.activeV3StreamedFiles || context.__v3StreamedFiles;
+        if (!bucket) {
+            return;
+        }
+        if (name === 'write_file' && typeof args.content === 'string') {
+            bucket[target.relativePath] = args.content;
+            return;
+        }
+        if (name === 'edit_file') {
+            try {
+                bucket[target.relativePath] = fs.readFileSync(target.absolutePath, 'utf8');
+            }
+            catch {
+                // ignore read failures; success was already reported by the client tool
+            }
+        }
+    }
+    async executeV3ClientToolRequest(event, context = {}) {
+        const rootPath = this.resolveAgentTargetPath(context);
+        if (!rootPath) {
+            return { success: false, output: '', error: 'No local workspace path is available for client tool execution.' };
+        }
+        const name = String(event.name || event.tool || '').trim();
+        const args = event.arguments || {};
+        const target = this.resolveV3ClientToolPath(rootPath, args.path || args.cwd || '.');
+        if (!target) {
+            return { success: false, output: '', error: 'Tool path is outside the workspace.' };
+        }
+        try {
+            if (name === 'write_file') {
+                if (typeof args.content !== 'string')
+                    return { success: false, output: '', error: 'write_file requires string content.' };
+                fs.mkdirSync(path.dirname(target.absolutePath), { recursive: true });
+                fs.writeFileSync(target.absolutePath, args.content, 'utf8');
+                const result = { success: true, output: `Updated ${target.relativePath}` };
+                this.recordV3ClientToolMutation(event, context, result);
+                return result;
+            }
+            if (name === 'edit_file') {
+                const oldString = typeof args.old_string === 'string' ? args.old_string : String(args.old_text || '');
+                const newString = typeof args.new_string === 'string' ? args.new_string : String(args.new_text || '');
+                if (!oldString)
+                    return { success: false, output: '', error: 'edit_file requires old_string.' };
+                const existing = fs.readFileSync(target.absolutePath, 'utf8');
+                const count = existing.split(oldString).length - 1;
+                if (count !== 1)
+                    return { success: false, output: '', error: `old_string found ${count} times; expected exactly once.` };
+                fs.writeFileSync(target.absolutePath, existing.replace(oldString, newString), 'utf8');
+                const result = { success: true, output: `Edited ${target.relativePath}` };
+                this.recordV3ClientToolMutation(event, context, result);
+                return result;
+            }
+            if (name === 'read_file') {
+                return { success: true, output: fs.readFileSync(target.absolutePath, 'utf8') };
+            }
+            if (name === 'list_directory') {
+                const entries = fs.readdirSync(target.absolutePath, { withFileTypes: true })
+                    .filter((entry) => !['node_modules', '.git'].includes(entry.name))
+                    .map((entry) => `${entry.isDirectory() ? '[DIR] ' : ''}${entry.name}`);
+                return { success: true, output: entries.join('\n') || '(empty)' };
+            }
+            if (name === 'glob' || name === 'search_files') {
+                const pattern = String(args.pattern || args.query || '').toLowerCase();
+                const files = [];
+                const walk = (dir) => {
+                    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+                        if (['node_modules', '.git'].includes(entry.name))
+                            continue;
+                        const absolute = path.join(dir, entry.name);
+                        if (entry.isDirectory()) {
+                            walk(absolute);
+                            continue;
+                        }
+                        const relative = path.relative(rootPath, absolute).replace(/\\/g, '/');
+                        if (!pattern || relative.toLowerCase().includes(pattern.replace(/\*/g, ''))) {
+                            files.push(relative);
+                        }
+                        else if (name === 'search_files') {
+                            const content = fs.readFileSync(absolute, 'utf8');
+                            if (content.toLowerCase().includes(pattern))
+                                files.push(relative);
+                        }
+                    }
+                };
+                walk(fs.statSync(target.absolutePath).isDirectory() ? target.absolutePath : rootPath);
+                return { success: true, output: files.slice(0, 200).join('\n') || '(no matches)' };
+            }
+            if (name === 'syntax_check') {
+                const content = fs.readFileSync(target.absolutePath, 'utf8');
+                if (/\.json$/i.test(target.absolutePath))
+                    JSON.parse(content);
+                return { success: true, output: `Syntax check passed: ${target.relativePath}` };
+            }
+            if (name === 'run_command') {
+                const command = String(args.command || '').trim();
+                if (!command)
+                    return { success: false, output: '', error: 'run_command requires command.' };
+                const { exec } = await import('child_process');
+                return await new Promise((resolve) => {
+                    exec(command, { cwd: target.absolutePath, timeout: Number(args.timeout || 30000) }, (error, stdout, stderr) => {
+                        resolve({
+                            success: !error,
+                            output: String(stdout || stderr || '').slice(0, 12000),
+                            error: error ? String(stderr || error.message) : '',
+                        });
+                    });
+                });
+            }
+            return { success: false, output: '', error: `Unsupported client tool: ${name}` };
+        }
+        catch (error) {
+            return { success: false, output: '', error: error.message };
+        }
+    }
+    async handleV3ClientToolRequest(event, context = {}, responseUrl) {
+        const contextId = String(event.context_id || context.contextId || '').trim();
+        const callId = String(event.call_id || '').trim();
+        const toolName = String(event.tool || event.name || 'client_tool').trim();
+        if (!contextId || !callId)
+            return;
+        const backendUrl = responseUrl ? new URL(responseUrl).origin : (context.mcpContextBackendUrl || null);
+        try {
+            const result = await this.executeV3ClientToolRequest(event, context);
+            try {
+                await this.submitClientToolResult(contextId, callId, result, backendUrl);
+            }
+            catch (submitError) {
+                const submitMessage = submitError.message || String(submitError);
+                if (result.success) {
+                    this.recordClientToolError(`Local ${toolName} succeeded on your machine, but the Vigthoria agent could not accept the result (${submitMessage}). Your workspace may not have synced to the server.`);
+                    return;
+                }
+                throw submitError;
+            }
+            if (!result.success && result.error) {
+                this.recordClientToolError(`Local ${toolName} failed: ${result.error}`);
+            }
+        }
+        catch (error) {
+            this.recordClientToolError(`Local tool bridge failed for ${toolName}: ${error.message}`);
+            throw error;
+        }
+    }
     writeV3AgentWorkspaceFile(rootPath, rawPath, content, sourceRoot) {
         const relativePath = this.normalizeAgentWorkspaceRelativePath(rawPath, sourceRoot || rootPath);
         if (!relativePath) {
@@ -3054,6 +3294,7 @@ document.addEventListener('DOMContentLoaded', () => {
             .replace(/<\/think>/gi, '</thinking>')
             .replace(/<thinking>[\s\S]*?<\/thinking>/gi, '')
             .replace(/<tool_call>[\s\S]*?<\/tool_call>/gi, '')
+            .replace(/<tool_code>[\s\S]*?<\/tool_code>/gi, '')
             .replace(/```json\s*\[\s*\{[\s\S]*?"tool"[\s\S]*?\}\s*\]\s*```/gi, '')
             .replace(/```json\s*\{[\s\S]*?"tool"[\s\S]*?\}\s*```/gi, '')
             .replace(/^\s*(?:json\s*)?\[\s*\{[\s\S]*?"tool"[\s\S]*$/gim, '')
@@ -3146,10 +3387,27 @@ document.addEventListener('DOMContentLoaded', () => {
         };
         return sanitizeValue(event);
     }
+    resolveAgentChangedFiles(data) {
+        const streamed = data?.files && typeof data.files === 'object' ? data.files : {};
+        const clientMutations = this.activeV3StreamedFiles && typeof this.activeV3StreamedFiles === 'object'
+            ? this.activeV3StreamedFiles
+            : {};
+        return { ...streamed, ...clientMutations };
+    }
+    finalizeV3AgentWorkflowResponse(data, response) {
+        const changedFiles = this.resolveAgentChangedFiles(data);
+        this.activeV3StreamedFiles = null;
+        this.activeV3StreamContext = null;
+        return {
+            ...response,
+            changedFiles,
+        };
+    }
     async collectV3AgentStream(response, context = {}) {
         if (!response.body || typeof response.body.getReader !== 'function') {
             return response.json();
         }
+        this.clearAgentRunDiagnostics();
         const reader = response.body.getReader();
         const decoder = new TextDecoder();
         let buffer = '';
@@ -3158,183 +3416,202 @@ document.addEventListener('DOMContentLoaded', () => {
         let contextId = response.headers.get('x-context-id') || String(context.contextId || '').trim() || null;
         let serverWorkspaceRoot = null;
         const streamedFiles = {};
+        this.activeV3StreamedFiles = streamedFiles;
+        this.activeV3StreamContext = context;
+        context.__v3StreamedFiles = streamedFiles;
         const idleTimeoutMs = context.agentIdleTimeoutMs || DEFAULT_V3_AGENT_IDLE_TIMEOUT_MS;
-        while (true) {
-            let chunk;
-            try {
-                const readPromise = reader.read();
-                while (true) {
-                    const timeoutSentinel = Symbol('v3-agent-idle-timeout');
-                    const result = idleTimeoutMs > 0
-                        ? await Promise.race([
-                            readPromise,
-                            new Promise((resolve) => {
-                                setTimeout(() => resolve(timeoutSentinel), idleTimeoutMs);
-                            }),
-                        ])
-                        : await readPromise;
-                    if (result !== timeoutSentinel) {
-                        chunk = result;
-                        break;
+        try {
+            while (true) {
+                let chunk;
+                try {
+                    const readPromise = reader.read();
+                    while (true) {
+                        const timeoutSentinel = Symbol('v3-agent-idle-timeout');
+                        const result = idleTimeoutMs > 0
+                            ? await Promise.race([
+                                readPromise,
+                                new Promise((resolve) => {
+                                    setTimeout(() => resolve(timeoutSentinel), idleTimeoutMs);
+                                }),
+                            ])
+                            : await readPromise;
+                        if (result !== timeoutSentinel) {
+                            chunk = result;
+                            break;
+                        }
+                        if (this.hasAgentWorkspaceOutput(context)) {
+                            const stalledError = new Error('V3 agent stream stalled after writing workspace output');
+                            stalledError.name = 'AbortError';
+                            stalledError.partialData = {
+                                task_id: events.find((event) => event && event.task_id)?.task_id || null,
+                                context_id: contextId,
+                                result: final,
+                                events,
+                                files: streamedFiles,
+                            };
+                            throw stalledError;
+                        }
                     }
-                    if (this.hasAgentWorkspaceOutput(context)) {
-                        const stalledError = new Error('V3 agent stream stalled after writing workspace output');
-                        stalledError.name = 'AbortError';
-                        stalledError.partialData = {
+                }
+                catch (error) {
+                    if (error && error.name === 'AbortError') {
+                        error.partialData = {
                             task_id: events.find((event) => event && event.task_id)?.task_id || null,
                             context_id: contextId,
                             result: final,
                             events,
                             files: streamedFiles,
                         };
-                        throw stalledError;
                     }
+                    throw error;
                 }
-            }
-            catch (error) {
-                if (error && error.name === 'AbortError') {
-                    error.partialData = {
-                        task_id: events.find((event) => event && event.task_id)?.task_id || null,
-                        context_id: contextId,
-                        result: final,
-                        events,
-                        files: streamedFiles,
-                    };
+                const { done, value } = chunk;
+                if (done) {
+                    break;
                 }
-                throw error;
-            }
-            const { done, value } = chunk;
-            if (done) {
-                break;
-            }
-            buffer += decoder.decode(value, { stream: true });
-            const frames = buffer.split(/\r?\n\r?\n/);
-            buffer = frames.pop() || '';
-            for (const frame of frames) {
-                const lines = frame.split(/\r?\n/);
-                const dataLines = [];
-                let explicitEventType = null;
-                for (const rawLine of lines) {
-                    const line = rawLine.trimEnd();
-                    if (!line || line.startsWith(':')) {
-                        continue;
+                buffer += decoder.decode(value, { stream: true });
+                const frames = buffer.split(/\r?\n\r?\n/);
+                buffer = frames.pop() || '';
+                for (const frame of frames) {
+                    const lines = frame.split(/\r?\n/);
+                    const dataLines = [];
+                    let explicitEventType = null;
+                    for (const rawLine of lines) {
+                        const line = rawLine.trimEnd();
+                        if (!line || line.startsWith(':')) {
+                            continue;
+                        }
+                        if (line.startsWith('event:')) {
+                            explicitEventType = line.slice(6).trim() || null;
+                            continue;
+                        }
+                        if (line.startsWith('data:')) {
+                            dataLines.push(line.slice(5).trimStart());
+                        }
                     }
-                    if (line.startsWith('event:')) {
-                        explicitEventType = line.slice(6).trim() || null;
+                    const payload = dataLines.join('\n').trim();
+                    if (!payload || payload === '[DONE]') {
                         continue;
                     }
-                    if (line.startsWith('data:')) {
-                        dataLines.push(line.slice(5).trimStart());
+                    let event;
+                    try {
+                        event = JSON.parse(payload);
                     }
-                }
-                const payload = dataLines.join('\n').trim();
-                if (!payload || payload === '[DONE]') {
-                    continue;
-                }
-                let event;
-                try {
-                    event = JSON.parse(payload);
-                }
-                catch {
-                    event = {
-                        type: explicitEventType || 'message',
-                        content: payload,
-                    };
-                }
-                if (explicitEventType && (!event.type || event.type === 'message')) {
-                    event.type = explicitEventType;
-                }
-                const userEvent = this.sanitizeV3AgentEventForUser(event);
-                events.push(userEvent);
-                if (!contextId && typeof event.context_id === 'string' && event.context_id.trim()) {
-                    contextId = event.context_id.trim();
-                }
-                if (!serverWorkspaceRoot && event.type === 'context' && typeof event.workspace_root === 'string' && event.workspace_root.trim()) {
-                    serverWorkspaceRoot = event.workspace_root.trim();
-                }
-                this.captureV3AgentStreamMutation(event, streamedFiles, serverWorkspaceRoot);
-                this.applyV3AgentStreamEventToWorkspace(event, context, serverWorkspaceRoot);
-                // Empty workspace soft guard: the first list_directory result can be
-                // transiently empty before remote workspace hydration catches up.
-                // Avoid hard-failing here; let the stream continue.
-                if (event.type === 'tool_result'
-                    && event.name === 'list_directory'
-                    && event.success === true
-                    && serverWorkspaceRoot
-                    && typeof event.output === 'string') {
-                    const listOutput = event.output.trim();
-                    const looksEmpty = listOutput === `[${serverWorkspaceRoot}]`
-                        || listOutput === `[${serverWorkspaceRoot}/]`
-                        || listOutput === `[${serverWorkspaceRoot}]\\n`
-                        || /^\[\/tmp\/vig-remote-server-[^\]]+\]\s*$/.test(listOutput);
-                    if (looksEmpty) {
-                        const localPath = this.resolveAgentTargetPath(context);
-                        const localHasFiles = localPath && fs.existsSync(localPath) && this.hasAgentWorkspaceOutput({ ...context, projectPath: localPath, targetPath: localPath });
-                        if (localHasFiles) {
-                            this.logger?.debug?.('V3 remote workspace initially empty; waiting for hydration instead of aborting.');
+                    catch {
+                        event = {
+                            type: explicitEventType || 'message',
+                            content: payload,
+                        };
+                    }
+                    if (explicitEventType && (!event.type || event.type === 'message')) {
+                        event.type = explicitEventType;
+                    }
+                    const userEvent = this.sanitizeV3AgentEventForUser(event);
+                    events.push(userEvent);
+                    if (!contextId && typeof event.context_id === 'string' && event.context_id.trim()) {
+                        contextId = event.context_id.trim();
+                    }
+                    if (!serverWorkspaceRoot && event.type === 'context' && typeof event.workspace_root === 'string' && event.workspace_root.trim()) {
+                        serverWorkspaceRoot = event.workspace_root.trim();
+                    }
+                    if (event.type === 'client_tool_request') {
+                        const toolTask = this.handleV3ClientToolRequest(event, context, response.url).catch((error) => {
+                            this.logger.warn(`Failed to handle V3 client tool request: ${error.message}`);
+                        });
+                        this.pendingV3ClientToolTasks.add(toolTask);
+                        void toolTask.finally(() => {
+                            this.pendingV3ClientToolTasks.delete(toolTask);
+                        });
+                    }
+                    this.captureV3AgentStreamMutation(event, streamedFiles, serverWorkspaceRoot);
+                    this.applyV3AgentStreamEventToWorkspace(event, context, serverWorkspaceRoot);
+                    // Empty workspace soft guard: the first list_directory result can be
+                    // transiently empty before remote workspace hydration catches up.
+                    // Avoid hard-failing here; let the stream continue.
+                    if (event.type === 'tool_result'
+                        && event.name === 'list_directory'
+                        && event.success === true
+                        && serverWorkspaceRoot
+                        && typeof event.output === 'string') {
+                        const listOutput = event.output.trim();
+                        const looksEmpty = listOutput === `[${serverWorkspaceRoot}]`
+                            || listOutput === `[${serverWorkspaceRoot}/]`
+                            || listOutput === `[${serverWorkspaceRoot}]\\n`
+                            || /^\[\/tmp\/vig-remote-server-[^\]]+\]\s*$/.test(listOutput);
+                        if (looksEmpty) {
+                            const localPath = this.resolveAgentTargetPath(context);
+                            const localHasFiles = localPath && fs.existsSync(localPath) && this.hasAgentWorkspaceOutput({ ...context, projectPath: localPath, targetPath: localPath });
+                            if (localHasFiles) {
+                                this.logger?.debug?.('V3 remote workspace initially empty; waiting for hydration instead of aborting.');
+                            }
                         }
                     }
-                }
-                if (typeof context.onStreamEvent === 'function') {
-                    try {
-                        context.onStreamEvent(userEvent);
+                    if (typeof context.onStreamEvent === 'function') {
+                        try {
+                            context.onStreamEvent(userEvent);
+                        }
+                        catch {
+                            // Ignore UI callback failures; never break the agent stream for them.
+                        }
                     }
-                    catch {
-                        // Ignore UI callback failures; never break the agent stream for them.
+                    if (event.type === 'error') {
+                        if (event.checkpointed && event.task_id) {
+                            // Agent checkpointed — return data so caller can auto-continue
+                            return {
+                                task_id: event.task_id,
+                                context_id: contextId,
+                                result: final || event,
+                                events,
+                                files: streamedFiles,
+                                partial: true,
+                                checkpointed: true,
+                                checkpointed_task_id: event.task_id,
+                            };
+                        }
+                        if (this.hasAgentWorkspaceOutput(context)) {
+                            return {
+                                task_id: events.find((entry) => entry && entry.task_id)?.task_id || null,
+                                context_id: contextId,
+                                result: final || event,
+                                events,
+                                files: streamedFiles,
+                                partial: true,
+                            };
+                        }
+                        throw new Error(event.message || 'V3 agent returned an error');
                     }
-                }
-                if (event.type === 'error') {
-                    if (event.checkpointed && event.task_id) {
-                        // Agent checkpointed — return data so caller can auto-continue
-                        return {
-                            task_id: event.task_id,
-                            context_id: contextId,
-                            result: final || event,
-                            events,
-                            files: streamedFiles,
-                            partial: true,
-                            checkpointed: true,
-                            checkpointed_task_id: event.task_id,
-                        };
+                    if (event.type === 'complete' || event.type === 'message') {
+                        final = event;
                     }
-                    if (this.hasAgentWorkspaceOutput(context)) {
+                    // Exit stream early on complete — agent is done; server-side teardown
+                    // can hold the connection open for many seconds otherwise.
+                    if (event.type === 'complete') {
+                        reader.cancel().catch(() => { });
                         return {
                             task_id: events.find((entry) => entry && entry.task_id)?.task_id || null,
                             context_id: contextId,
-                            result: final || event,
+                            result: final,
                             events,
                             files: streamedFiles,
-                            partial: true,
+                            serverWorkspaceRoot: serverWorkspaceRoot || null,
                         };
                     }
-                    throw new Error(event.message || 'V3 agent returned an error');
-                }
-                if (event.type === 'complete' || event.type === 'message') {
-                    final = event;
-                }
-                // Exit stream early on complete — agent is done; server-side teardown
-                // can hold the connection open for many seconds otherwise.
-                if (event.type === 'complete') {
-                    reader.cancel().catch(() => { });
-                    return {
-                        task_id: events.find((entry) => entry && entry.task_id)?.task_id || null,
-                        context_id: contextId,
-                        result: final,
-                        events,
-                        files: streamedFiles,
-                        serverWorkspaceRoot: serverWorkspaceRoot || null,
-                    };
                 }
             }
+            await Promise.allSettled([...this.pendingV3ClientToolTasks]);
+            return {
+                task_id: events.find((event) => event && event.task_id)?.task_id || null,
+                context_id: contextId,
+                result: final,
+                events,
+                files: streamedFiles,
+                serverWorkspaceRoot: serverWorkspaceRoot || null,
+                clientToolErrors: this.getClientToolErrors(),
+            };
+        }
+        finally {
+            await Promise.allSettled([...this.pendingV3ClientToolTasks]);
         }
-        return {
-            task_id: events.find((event) => event && event.task_id)?.task_id || null,
-            context_id: contextId,
-            result: final,
-            events,
-            files: streamedFiles,
-            serverWorkspaceRoot: serverWorkspaceRoot || null,
-        };
     }
     async runV3AgentWorkflow(message, context = {}) {
         const executionContext = await this.bindExecutionContext(context);
@@ -3457,14 +3734,14 @@ document.addEventListener('DOMContentLoaded', () => {
                             await this.ensureAgentFrontendPolish(message, executionContext);
                             const previewGate = await this.runTemplateServicePreviewGate(message, executionContext);
                             const finalContextId = continuationData.context_id || data.context_id || response.headers.get('x-context-id') || requestExecutionContext.contextId || null;
-                            return {
+                            return this.finalizeV3AgentWorkflowResponse(continuationData, {
                                 content: this.formatV3AgentResponse(continuationData) || this.formatV3AgentResponse(data),
                                 taskId: continuationData.task_id || data.task_id || null,
                                 contextId: finalContextId,
                                 backendUrl: baseUrl,
                                 partial: continuationData.checkpointed === true,
                                 metadata: { source: 'v3-agent', mode: 'agent', contextId: finalContextId, continuations, previewGate },
-                            };
+                            });
                         }
                         const contextId = data.context_id || response.headers.get('x-context-id') || requestExecutionContext.contextId || null;
                         const mcpContextId = response.headers.get('x-mcp-context-id') || requestExecutionContext.mcpContextId || null;
@@ -3476,13 +3753,13 @@ document.addEventListener('DOMContentLoaded', () => {
                             errors.push(`${baseUrl}: workflow rejected the result - ${previewGate.error || 'Workspace changes were not fully validated.'}`);
                             continue;
                         }
-                        return {
+                        return this.finalizeV3AgentWorkflowResponse(data, {
                             content: this.formatV3AgentResponse(data),
                             taskId: data.task_id || null,
                             contextId,
                             backendUrl: baseUrl,
                             metadata: { source: 'v3-agent', mode: 'agent', contextId, mcpContextId, previewGate },
-                        };
+                        });
                     }
                     catch (error) {
                         if (error && error.name === 'AbortError' && error.partialData && this.hasAgentWorkspaceOutput(executionContext)) {
@@ -3490,14 +3767,14 @@ document.addEventListener('DOMContentLoaded', () => {
                             await this.waitForAgentWorkspaceSettle(executionContext, { expectedFiles });
                             await this.ensureAgentFrontendPolish(message, executionContext);
                             const previewGate = await this.runTemplateServicePreviewGate(message, executionContext);
-                            return {
+                            return this.finalizeV3AgentWorkflowResponse(error.partialData, {
                                 content: this.formatV3AgentResponse(error.partialData) || 'V3 agent wrote workspace files before the request timed out waiting for a final summary.',
                                 taskId: error.partialData.task_id || null,
                                 contextId: error.partialData.context_id || requestExecutionContext.contextId || executionContext.contextId || null,
                                 backendUrl: baseUrl,
                                 partial: true,
                                 metadata: { source: 'v3-agent', mode: 'agent', partial: true, contextId: error.partialData.context_id || requestExecutionContext.contextId || executionContext.contextId || null, mcpContextId: requestExecutionContext.mcpContextId || executionContext.mcpContextId || null, previewGate },
-                            };
+                            });
                         }
                         errors.push(`${baseUrl}: ${error?.message || String(error)}`);
                     }
@@ -3559,6 +3836,158 @@ document.addEventListener('DOMContentLoaded', () => {
         }
         throw new Error(errors.join(' | '));
     }
+    async startV3BackgroundJob(message, context = {}) {
+        await this.ensureV3ServiceKey();
+        const executionContext = await this.bindExecutionContext({
+            ...context,
+            backgroundJob: true,
+            clientToolExecution: false,
+        });
+        const requestedModel = String(executionContext.model || executionContext.requestedModel || 'agent');
+        const resolvedModel = this.resolvePermittedModelId(requestedModel);
+        const body = {
+            request: message,
+            context: this.buildV3AgentContext({
+                ...executionContext,
+                backgroundJob: true,
+                clientToolExecution: false,
+            }),
+            stream: false,
+            model: resolvedModel,
+            mcp_context_id: executionContext.mcpContextId || undefined,
+        };
+        const errors = [];
+        for (const baseUrl of this.getV3AgentBaseUrls(false)) {
+            try {
+                const response = await fetch(this.getV3AgentBackgroundUrl(baseUrl), {
+                    method: 'POST',
+                    headers: await this.getV3AgentHeaders(),
+                    body: JSON.stringify(body),
+                });
+                if (!response.ok) {
+                    errors.push(`${baseUrl}: ${response.status} ${await response.text().catch(() => '')}`);
+                    continue;
+                }
+                return await response.json();
+            }
+            catch (error) {
+                errors.push(`${baseUrl}: ${error?.message || String(error)}`);
+            }
+        }
+        throw new Error(`Unable to start background job: ${errors.join('; ')}`);
+    }
+    async listV3BackgroundJobs(limit = 20) {
+        await this.ensureV3ServiceKey();
+        const errors = [];
+        for (const baseUrl of this.getV3AgentBaseUrls(false)) {
+            try {
+                const response = await fetch(`${this.getV3AgentBackgroundUrl(baseUrl)}?limit=${encodeURIComponent(String(limit))}`, {
+                    method: 'GET',
+                    headers: await this.getV3AgentHeaders(),
+                });
+                if (!response.ok) {
+                    errors.push(`${baseUrl}: ${response.status}`);
+                    continue;
+                }
+                const data = await response.json();
+                return Array.isArray(data.jobs) ? data.jobs : [];
+            }
+            catch (error) {
+                errors.push(`${baseUrl}: ${error?.message || String(error)}`);
+            }
+        }
+        throw new Error(`Unable to list background jobs: ${errors.join('; ')}`);
+    }
+    async getV3BackgroundJob(jobId) {
+        await this.ensureV3ServiceKey();
+        const errors = [];
+        for (const baseUrl of this.getV3AgentBaseUrls(false)) {
+            try {
+                const response = await fetch(this.getV3AgentBackgroundUrl(baseUrl, encodeURIComponent(jobId)), {
+                    method: 'GET',
+                    headers: await this.getV3AgentHeaders(),
+                });
+                if (!response.ok) {
+                    errors.push(`${baseUrl}: ${response.status}`);
+                    continue;
+                }
+                return await response.json();
+            }
+            catch (error) {
+                errors.push(`${baseUrl}: ${error?.message || String(error)}`);
+            }
+        }
+        throw new Error(`Unable to get background job: ${errors.join('; ')}`);
+    }
+    async cancelV3BackgroundJob(jobId) {
+        await this.ensureV3ServiceKey();
+        const errors = [];
+        for (const baseUrl of this.getV3AgentBaseUrls(false)) {
+            try {
+                const response = await fetch(this.getV3AgentBackgroundUrl(baseUrl, `${encodeURIComponent(jobId)}/cancel`), {
+                    method: 'POST',
+                    headers: await this.getV3AgentHeaders(),
+                });
+                if (!response.ok) {
+                    errors.push(`${baseUrl}: ${response.status}`);
+                    continue;
+                }
+                return await response.json();
+            }
+            catch (error) {
+                errors.push(`${baseUrl}: ${error?.message || String(error)}`);
+            }
+        }
+        throw new Error(`Unable to cancel background job: ${errors.join('; ')}`);
+    }
+    async getV3BackgroundJobFiles(jobId) {
+        await this.ensureV3ServiceKey();
+        const errors = [];
+        for (const baseUrl of this.getV3AgentBaseUrls(false)) {
+            try {
+                const response = await fetch(this.getV3AgentBackgroundUrl(baseUrl, `${encodeURIComponent(jobId)}/files`), {
+                    method: 'GET',
+                    headers: await this.getV3AgentHeaders(),
+                });
+                if (!response.ok) {
+                    errors.push(`${baseUrl}: ${response.status}`);
+                    continue;
+                }
+                return await response.json();
+            }
+            catch (error) {
+                errors.push(`${baseUrl}: ${error?.message || String(error)}`);
+            }
+        }
+        throw new Error(`Unable to fetch background job files: ${errors.join('; ')}`);
+    }
+    async applyV3BackgroundJobFiles(jobId, context = {}) {
+        const data = await this.getV3BackgroundJobFiles(jobId);
+        const rootPath = this.resolveAgentTargetPath({
+            ...context,
+            workspacePath: context.workspacePath || data.local_workspace_path,
+            projectPath: context.projectPath || data.local_workspace_path,
+            targetPath: context.targetPath || data.local_workspace_path,
+        });
+        if (!rootPath) {
+            throw new Error('No local workspace path available for applying background job files.');
+        }
+        const applied = [];
+        const skipped = [];
+        for (const [relativePath, content] of Object.entries(data.files || {})) {
+            if (typeof content !== 'string') {
+                skipped.push(relativePath);
+                continue;
+            }
+            if (this.writeV3AgentWorkspaceFile(rootPath, relativePath, content, rootPath)) {
+                applied.push(relativePath);
+            }
+            else {
+                skipped.push(relativePath);
+            }
+        }
+        return { applied, skipped, status: data.status };
+    }
     formatOperatorResponse(data = {}) {
         // If the server returned a direct answer field, prefer it (for lookup tasks)
         if (typeof data.answer === 'string' && data.answer.trim()) {
@@ -5094,6 +5523,19 @@ document.addEventListener('DOMContentLoaded', () => {
     getLastChatTransportErrors() {
         return this.lastChatTransportErrors;
     }
+    getClientToolErrors() {
+        return [...this.clientToolErrors];
+    }
+    clearAgentRunDiagnostics() {
+        this.clientToolErrors = [];
+        this.pendingV3ClientToolTasks.clear();
+    }
+    recordClientToolError(message) {
+        const trimmed = sanitizeUserFacingErrorText(String(message || '')).slice(0, 280);
+        if (trimmed && !this.clientToolErrors.includes(trimmed)) {
+            this.clientToolErrors.push(trimmed);
+        }
+    }
     async submitClientToolResult(contextId, callId, result, backendUrl) {
         const trimmedContextId = String(contextId || '').trim();
         const trimmedCallId = String(callId || '').trim();
@@ -5130,6 +5572,10 @@ document.addEventListener('DOMContentLoaded', () => {
                 await new Promise((resolve) => setTimeout(resolve, 120 * (attempt + 1)));
                 continue;
             }
+            if (response.status === 404 && /no pending client tool call/i.test(errorText)) {
+                // Server already consumed or timed out this call — treat as idempotent when local work succeeded.
+                return;
+            }
             throw new Error(`Client tool result rejected (${response.status}): ${sanitizeUserFacingErrorText(errorText).slice(0, 200)}`);
         }
     }