vigthoria-cli 1.13.18 → 1.13.22

package/dist/utils/update-policy.d.ts

@@ -0,0 +1,18 @@
+export type ResolvedUpdateSource = {
+    kind: 'registry';
+    installTarget: string;
+    expectedSha256: null;
+} | {
+    kind: 'local';
+    installTarget: string;
+    expectedSha256: string | null;
+} | {
+    kind: 'remote';
+    downloadUrl: string;
+    expectedSha256: string;
+};
+export declare function compareSemanticVersions(leftRaw: string, rightRaw: string): number;
+export declare function resolveUpdateSource(rawTarget: string, options?: {
+    sha256?: unknown;
+    cwd?: string;
+}): ResolvedUpdateSource;

package/dist/utils/update-policy.js

@@ -0,0 +1,137 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { CliCommandError } from './command-contract.js';
+import { assertTrustedEndpoint } from './network-policy.js';
+const SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+const SHA256 = /^[a-f0-9]{64}$/i;
+function parseSemanticVersion(raw) {
+    const value = String(raw || '').trim();
+    const match = SEMVER.exec(value);
+    if (!match) {
+        throw new CliCommandError(`Invalid semantic version: ${value || '(empty)'}`, {
+            code: 'UPDATE_VERSION_INVALID',
+            category: 'usage',
+        });
+    }
+    const prerelease = match[4] ? match[4].split('.') : [];
+    if (prerelease.some((identifier) => /^\d+$/.test(identifier) && identifier.length > 1 && identifier.startsWith('0'))) {
+        throw new CliCommandError(`Invalid semantic version: ${value}`, {
+            code: 'UPDATE_VERSION_INVALID',
+            category: 'usage',
+        });
+    }
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: Number(match[3]),
+        prerelease,
+    };
+}
+export function compareSemanticVersions(leftRaw, rightRaw) {
+    const left = parseSemanticVersion(leftRaw);
+    const right = parseSemanticVersion(rightRaw);
+    for (const key of ['major', 'minor', 'patch']) {
+        if (left[key] !== right[key])
+            return left[key] < right[key] ? -1 : 1;
+    }
+    if (left.prerelease.length === 0 || right.prerelease.length === 0) {
+        if (left.prerelease.length === right.prerelease.length)
+            return 0;
+        return left.prerelease.length === 0 ? 1 : -1;
+    }
+    const length = Math.max(left.prerelease.length, right.prerelease.length);
+    for (let index = 0; index < length; index += 1) {
+        const leftPart = left.prerelease[index];
+        const rightPart = right.prerelease[index];
+        if (leftPart === undefined || rightPart === undefined)
+            return leftPart === undefined ? -1 : 1;
+        if (leftPart === rightPart)
+            continue;
+        const leftNumeric = /^\d+$/.test(leftPart);
+        const rightNumeric = /^\d+$/.test(rightPart);
+        if (leftNumeric && rightNumeric)
+            return Number(leftPart) < Number(rightPart) ? -1 : 1;
+        if (leftNumeric !== rightNumeric)
+            return leftNumeric ? -1 : 1;
+        return leftPart < rightPart ? -1 : 1;
+    }
+    return 0;
+}
+function normalizeChecksum(raw) {
+    const value = String(raw || '').trim().toLowerCase();
+    if (!value)
+        return null;
+    if (!SHA256.test(value)) {
+        throw new CliCommandError('Update SHA-256 must contain exactly 64 hexadecimal characters.', {
+            code: 'UPDATE_CHECKSUM_INVALID',
+            category: 'usage',
+        });
+    }
+    return value;
+}
+export function resolveUpdateSource(rawTarget, options = {}) {
+    const target = String(rawTarget || '').trim();
+    const expectedSha256 = normalizeChecksum(options.sha256);
+    if (!target) {
+        throw new CliCommandError('Update source is required.', {
+            code: 'UPDATE_SOURCE_REQUIRED',
+            category: 'usage',
+        });
+    }
+    if (/^https?:\/\//i.test(target)) {
+        const endpoint = assertTrustedEndpoint(target, { audience: 'release' });
+        if (!endpoint.pathname.toLowerCase().endsWith('.tgz')) {
+            throw new CliCommandError('Remote update source must identify a .tgz archive.', {
+                code: 'UPDATE_ARCHIVE_INVALID',
+                category: 'usage',
+            });
+        }
+        if (!expectedSha256) {
+            throw new CliCommandError('Remote update sources require --sha256 so the downloaded package can be verified.', {
+                code: 'UPDATE_CHECKSUM_REQUIRED',
+                category: 'usage',
+            });
+        }
+        return { kind: 'remote', downloadUrl: endpoint.toString(), expectedSha256 };
+    }
+    if (target.includes('://') || /^git(?:\+|@)/i.test(target)) {
+        throw new CliCommandError('Git and non-HTTPS update sources are not supported.', {
+            code: 'UPDATE_SOURCE_UNTRUSTED',
+            category: 'usage',
+        });
+    }
+    if (target.startsWith('vigthoria-cli@')) {
+        parseSemanticVersion(target.slice('vigthoria-cli@'.length));
+        if (expectedSha256) {
+            throw new CliCommandError('--sha256 applies only to local or HTTPS archive sources.', {
+                code: 'UPDATE_CHECKSUM_NOT_APPLICABLE',
+                category: 'usage',
+            });
+        }
+        return { kind: 'registry', installTarget: target, expectedSha256: null };
+    }
+    const candidatePath = path.resolve(options.cwd || process.cwd(), target);
+    if (target.toLowerCase().endsWith('.tgz') || fs.existsSync(candidatePath)) {
+        let stat;
+        try {
+            stat = fs.statSync(candidatePath);
+        }
+        catch {
+            throw new CliCommandError(`Local update archive does not exist: ${candidatePath}`, {
+                code: 'UPDATE_ARCHIVE_NOT_FOUND',
+                category: 'configuration',
+            });
+        }
+        if (!stat.isFile() || !candidatePath.toLowerCase().endsWith('.tgz')) {
+            throw new CliCommandError('Local update source must be an existing .tgz file.', {
+                code: 'UPDATE_ARCHIVE_INVALID',
+                category: 'configuration',
+            });
+        }
+        return { kind: 'local', installTarget: fs.realpathSync(candidatePath), expectedSha256 };
+    }
+    throw new CliCommandError('Update source must be an exact vigthoria-cli@<version> package or a local/HTTPS .tgz archive.', {
+        code: 'UPDATE_SOURCE_INVALID',
+        category: 'usage',
+    });
+}

package/dist/utils/v3-agent-client.d.ts

@@ -0,0 +1,40 @@
+export interface V3HealthResult {
+    healthy: boolean;
+    endpoint: string;
+    error?: string;
+}
+export interface V3PreflightResult {
+    ok: boolean;
+    status: number;
+    endpoint: string;
+    reason?: string;
+}
+export interface V3AgentClientDependencies {
+    getConfiguredApiUrl(): string;
+    getAccessToken(): string | null;
+    getServiceKey(): string | null;
+    setServiceKey(key: string): void;
+    fetchServiceKey(token: string): Promise<string | null>;
+    refreshToken(): Promise<boolean>;
+    fetch(input: string, init: RequestInit): Promise<Response>;
+    sanitizeError(text: string): string;
+    debug(message: string): void;
+}
+export declare class V3AgentClient {
+    private readonly dependencies;
+    constructor(dependencies: V3AgentClientDependencies);
+    isDirectBaseUrl(baseUrl: string): boolean;
+    getBaseUrls(preferLocal?: boolean): string[];
+    runUrl(baseUrl: string): string;
+    continueUrl(baseUrl: string): string;
+    backgroundUrl(baseUrl: string, suffix?: string): string;
+    approvalUrl(baseUrl: string): string;
+    healthUrl(baseUrl: string): string;
+    headers(): Record<string, string>;
+    ensureServiceKey(): Promise<void>;
+    health(): Promise<V3HealthResult>;
+    preflight(baseUrl: string, context: Record<string, any>): Promise<V3PreflightResult>;
+    run(baseUrl: string, body: Record<string, any>, context: Record<string, any>, signal: AbortSignal): Promise<Response>;
+    requestBackground<T>(method: 'GET' | 'POST', suffix?: string, body?: unknown, query?: string): Promise<T>;
+    resolveApproval(body: Record<string, unknown>): Promise<any>;
+}

package/dist/utils/v3-agent-client.js

@@ -0,0 +1,165 @@
+import { hasLocalV3AgentCapability } from './runtime-capability.js';
+import { isLocalTestfarmMode } from './localTestMode.js';
+import { scanOutboundContext } from './secret-policy.js';
+export class V3AgentClient {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    isDirectBaseUrl(baseUrl) {
+        try {
+            return new URL(String(baseUrl)).port.endsWith('8030');
+        }
+        catch {
+            return /(?:127\.0\.0\.1|localhost|172\.19\.0\.1|host\.lan):(?:\d*8030|8030)/.test(String(baseUrl));
+        }
+    }
+    getBaseUrls(preferLocal = false) {
+        const configured = String(this.dependencies.getConfiguredApiUrl() || 'https://coder.vigthoria.io').replace(/\/$/, '');
+        const localTestMode = isLocalTestfarmMode();
+        const explicit = Boolean(process.env.VIGTHORIA_V3_AGENT_URL || process.env.V3_AGENT_URL);
+        const local = [
+            process.env.VIGTHORIA_V3_AGENT_URL,
+            process.env.V3_AGENT_URL,
+            ...(hasLocalV3AgentCapability() ? ['http://127.0.0.1:8030'] : []),
+        ].filter(Boolean).map((url) => String(url).replace(/\/$/, ''));
+        const remote = (localTestMode ? [configured] : [configured, 'https://coder.vigthoria.io'])
+            .filter(Boolean).map((url) => String(url).replace(/\/$/, ''));
+        return [...new Set((preferLocal || localTestMode || explicit) && local.length ? [...local, ...remote] : [...remote, ...local])];
+    }
+    runUrl(baseUrl) { return `${baseUrl}${this.isDirectBaseUrl(baseUrl) ? '/api/agent/run' : '/api/v3-agent/run'}`; }
+    continueUrl(baseUrl) { return `${baseUrl}${this.isDirectBaseUrl(baseUrl) ? '/api/agent/continue' : '/api/v3-agent/continue'}`; }
+    backgroundUrl(baseUrl, suffix = '') {
+        const clean = suffix ? `/${suffix.replace(/^\/+/, '')}` : '';
+        return `${baseUrl}${this.isDirectBaseUrl(baseUrl) ? '/api/agent/background' : '/api/v3-agent/background'}${clean}`;
+    }
+    approvalUrl(baseUrl) { return `${baseUrl}${this.isDirectBaseUrl(baseUrl) ? '/api/agent/approval' : '/api/v3-agent/approval'}`; }
+    healthUrl(baseUrl) { return `${baseUrl}${this.isDirectBaseUrl(baseUrl) ? '/health' : '/api/v3-agent/health'}`; }
+    headers() {
+        const headers = { 'Content-Type': 'application/json', Accept: 'text/event-stream' };
+        const token = this.dependencies.getAccessToken();
+        if (token) {
+            headers.Authorization = `Bearer ${token}`;
+            headers.Cookie = `vigthoria-auth-token=${token}`;
+        }
+        const key = process.env.VIGTHORIA_V3_SERVICE_KEY || process.env.V3_SERVICE_KEY || process.env.HYPERLOOP_SERVICE_KEY || this.dependencies.getServiceKey();
+        if (key)
+            headers['X-Service-Key'] = key;
+        return headers;
+    }
+    async ensureServiceKey() {
+        if (process.env.VIGTHORIA_V3_SERVICE_KEY || process.env.V3_SERVICE_KEY || process.env.HYPERLOOP_SERVICE_KEY || this.dependencies.getServiceKey())
+            return;
+        const token = this.dependencies.getAccessToken();
+        if (!token)
+            return;
+        try {
+            const key = await this.dependencies.fetchServiceKey(token);
+            if (key) {
+                this.dependencies.setServiceKey(key);
+                this.dependencies.debug('V3 service key retrieved and cached from Coder API.');
+            }
+        }
+        catch { /* health and run calls surface unavailable authentication */ }
+    }
+    async health() {
+        const endpoints = this.getBaseUrls(false);
+        const failures = [];
+        for (const baseUrl of endpoints) {
+            for (let attempt = 1; attempt <= 3; attempt += 1) {
+                try {
+                    const response = await this.dependencies.fetch(this.healthUrl(baseUrl), { method: 'GET', headers: this.headers(), signal: AbortSignal.timeout(8000) });
+                    if (response.status === 401 || response.status === 403)
+                        return { healthy: false, endpoint: this.runUrl(baseUrl), error: 'V3 service rejected authentication. Please re-login to refresh your token.' };
+                    if (response.ok || response.status === 405)
+                        return { healthy: true, endpoint: this.runUrl(baseUrl) };
+                    failures.push(`${this.healthUrl(baseUrl)} attempt ${attempt}: HTTP ${response.status}`);
+                }
+                catch (error) {
+                    failures.push(`${this.healthUrl(baseUrl)} attempt ${attempt}: ${this.dependencies.sanitizeError(error?.message || String(error)).slice(0, 160) || 'network error'}`);
+                }
+                if (attempt < 3)
+                    await new Promise((resolve) => setTimeout(resolve, 1000 * attempt));
+            }
+        }
+        return { healthy: false, endpoint: endpoints[0] ? this.runUrl(endpoints[0]) : 'unknown', error: `V3 service is not reachable during startup preflight. Checked ${endpoints.length} endpoint(s). ${failures.slice(-3).join(' | ')}` };
+    }
+    async preflight(baseUrl, context) {
+        const endpoint = this.healthUrl(baseUrl);
+        const headers = this.headers();
+        headers['X-Vigthoria-Preflight'] = '1';
+        if (context.mcpContextId)
+            headers['X-MCP-Context-Id'] = String(context.mcpContextId);
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 12_000);
+        try {
+            const response = await this.dependencies.fetch(endpoint, { method: 'GET', headers, signal: controller.signal });
+            if (response.status === 401 || response.status === 403) {
+                const detail = await response.text().catch(() => '');
+                return { ok: false, status: response.status, endpoint, reason: this.dependencies.sanitizeError(detail).slice(0, 200) || 'Unauthorized' };
+            }
+            return { ok: true, status: response.status, endpoint };
+        }
+        catch (error) {
+            const reason = this.dependencies.sanitizeError(error?.message || String(error)).slice(0, 200);
+            return { ok: /aborted|timeout|timed out|network/i.test(reason), status: 0, endpoint, reason };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    async run(baseUrl, body, context, signal) {
+        const request = () => {
+            const headers = this.headers();
+            if (context.mcpContextId)
+                headers['X-MCP-Context-Id'] = String(context.mcpContextId);
+            if (context.operationId) {
+                headers['Idempotency-Key'] = String(context.operationId);
+                headers['X-Vigthoria-Operation-Id'] = String(context.operationId);
+            }
+            return this.dependencies.fetch(this.runUrl(baseUrl), { method: 'POST', headers, body: JSON.stringify(scanOutboundContext(body).value), signal });
+        };
+        let response = await request();
+        if (response.status === 401 && await this.dependencies.refreshToken())
+            response = await request();
+        return response;
+    }
+    async requestBackground(method, suffix = '', body, query = '') {
+        await this.ensureServiceKey();
+        const errors = [];
+        for (const baseUrl of this.getBaseUrls(false)) {
+            try {
+                const response = await this.dependencies.fetch(`${this.backgroundUrl(baseUrl, suffix)}${query}`, {
+                    method, headers: this.headers(), ...(body === undefined ? {} : { body: JSON.stringify(scanOutboundContext(body).value) }),
+                });
+                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(`V3 background request failed: ${errors.join('; ')}`);
+    }
+    async resolveApproval(body) {
+        await this.ensureServiceKey();
+        const errors = [];
+        for (const baseUrl of this.getBaseUrls(false)) {
+            try {
+                const response = await this.dependencies.fetch(this.approvalUrl(baseUrl), { method: 'POST', headers: this.headers(), body: JSON.stringify(body) });
+                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 resolve background approval: ${errors.join('; ')}`);
+    }
+}

package/dist/utils/v3-workspace-service.d.ts

@@ -0,0 +1,28 @@
+export interface V3WorkspaceSnapshot {
+    fileCount: number;
+    paths: string[];
+    signature: string;
+}
+export interface V3WorkspaceServiceDependencies {
+    resolveTargetPath(context: Record<string, any>): string | null;
+    warn(message: string): void;
+}
+export declare class V3WorkspaceService {
+    private readonly dependencies;
+    constructor(dependencies: V3WorkspaceServiceDependencies);
+    collectFileContents(rootPath: string, filePaths: string[]): Record<string, string>;
+    hasOutput(context?: Record<string, any>): boolean;
+    snapshot(rootPath: string): V3WorkspaceSnapshot;
+    waitForSettle(context?: Record<string, any>, options?: Record<string, any>): Promise<void>;
+    extractExpectedFiles(message?: string, context?: Record<string, any>): string[];
+    captureMutation(event: any, streamedFiles: Record<string, string>, serverRoot?: string | null): void;
+    applyStreamEvent(event: any, context?: Record<string, any>, serverRoot?: string | null): boolean;
+    resolveClientToolPath(rootPath: string, rawPath: unknown, sourceRoots?: string[]): {
+        relativePath: string;
+        absolutePath: string;
+    } | null;
+    writeFile(rootPath: string, rawPath: string, content: string, sourceRoot?: string): boolean;
+    deleteFile(rootPath: string, rawPath: string): boolean;
+    recover(context?: Record<string, any>, streamedFiles?: Record<string, string>, expectedFiles?: string[]): void;
+    normalizeRelativePath(rawPath: string, rootPath?: string): string;
+}

package/dist/utils/v3-workspace-service.js

@@ -0,0 +1,279 @@
+import fs from 'fs';
+import path from 'path';
+import { containsHighConfidenceSecret, isSensitivePath } from './secret-policy.js';
+import { resolveWorkspacePath } from './workspace-boundary.js';
+import { isV3WorkspaceRootAliasPath, normalizeV3WorkspaceRelativePath } from './v3-workspace-path.js';
+const BINARY_EXTENSIONS = new Set([
+    '.png', '.jpg', '.jpeg', '.gif', '.bmp', '.ico', '.webp', '.avif',
+    '.mp3', '.mp4', '.wav', '.ogg', '.webm', '.flac', '.aac',
+    '.zip', '.gz', '.tar', '.rar', '.7z', '.bz2', '.exe', '.dll', '.so',
+    '.dylib', '.bin', '.dat', '.woff', '.woff2', '.ttf', '.eot', '.otf',
+    '.pdf', '.doc', '.docx', '.xls', '.xlsx', '.ppt', '.pptx', '.db',
+    '.sqlite', '.sqlite3', '.pyc', '.pyo', '.class', '.o', '.obj', '.DS_Store', '.lock',
+]);
+export class V3WorkspaceService {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    collectFileContents(rootPath, filePaths) {
+        const result = {};
+        let totalBytes = 0;
+        for (const suppliedPath of filePaths) {
+            if (totalBytes >= 2 * 1024 * 1024)
+                break;
+            const relativePath = suppliedPath.replace(/\\/g, '/');
+            if (BINARY_EXTENSIONS.has(path.extname(relativePath).toLowerCase()))
+                continue;
+            if (/(^|\/)\.(git|hg)(\/|$)/.test(relativePath) || isSensitivePath(relativePath))
+                continue;
+            const agentState = /^\.vigthoria\/agent-state\//i.test(relativePath);
+            if (!agentState && /(^|\/)\.vigthoria(\/|$)/.test(relativePath))
+                continue;
+            try {
+                const absolutePath = resolveWorkspacePath(rootPath, relativePath);
+                const stat = fs.statSync(absolutePath);
+                if (!stat.isFile() || stat.size > 200 * 1024 || stat.size === 0)
+                    continue;
+                const content = fs.readFileSync(absolutePath, 'utf8');
+                if (containsHighConfidenceSecret(content) || /[\x00-\x08\x0e-\x1f]/.test(content.slice(0, 512)))
+                    continue;
+                result[suppliedPath] = content;
+                totalBytes += Buffer.byteLength(content, 'utf8');
+            }
+            catch {
+                // Unreadable or escaped paths are not outbound context.
+            }
+        }
+        return result;
+    }
+    hasOutput(context = {}) {
+        try {
+            const root = this.dependencies.resolveTargetPath(context);
+            if (!root || !fs.existsSync(root))
+                return false;
+            const stack = [fs.realpathSync(root)];
+            while (stack.length > 0) {
+                const current = stack.pop();
+                for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+                    if (entry.name === '.git' || entry.name === 'node_modules' || entry.name === '.vigthoria')
+                        continue;
+                    const fullPath = path.join(current, entry.name);
+                    if (entry.isSymbolicLink())
+                        continue;
+                    if (entry.isFile())
+                        return true;
+                    if (entry.isDirectory())
+                        stack.push(fullPath);
+                }
+            }
+        }
+        catch {
+            return false;
+        }
+        return false;
+    }
+    snapshot(rootPath) {
+        const canonicalRoot = fs.realpathSync(rootPath);
+        const stack = [canonicalRoot];
+        const entries = [];
+        while (stack.length > 0) {
+            const current = stack.pop();
+            for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+                if (entry.name === '.git' || entry.name === 'node_modules' || entry.isSymbolicLink())
+                    continue;
+                const fullPath = path.join(current, entry.name);
+                const relativePath = path.relative(canonicalRoot, fullPath).replace(/\\/g, '/');
+                if (isSensitivePath(relativePath))
+                    continue;
+                if (entry.isDirectory())
+                    stack.push(fullPath);
+                else if (entry.isFile()) {
+                    const stat = fs.statSync(fullPath);
+                    entries.push(`${relativePath}:${stat.size}:${stat.mtimeMs}`);
+                }
+            }
+        }
+        entries.sort();
+        return { fileCount: entries.length, paths: entries.map((entry) => entry.split(':', 1)[0]), signature: entries.join('|') };
+    }
+    async waitForSettle(context = {}, options = {}) {
+        const rootPath = this.dependencies.resolveTargetPath(context);
+        if (!rootPath || !fs.existsSync(rootPath))
+            return;
+        const timeoutMs = options.timeoutMs || 15000;
+        const pollMs = options.pollMs || 300;
+        const stableMs = options.stableMs || 1200;
+        const expectedFiles = Array.isArray(options.expectedFiles)
+            ? options.expectedFiles.map((entry) => String(entry || '').trim()).filter(Boolean)
+            : [];
+        const start = Date.now();
+        let stableSince = 0;
+        let lastSignature = '';
+        while (Date.now() - start < timeoutMs) {
+            const current = this.snapshot(rootPath);
+            if (current.fileCount > 0 && expectedFiles.every((filePath) => current.paths.includes(filePath))) {
+                if (current.signature === lastSignature) {
+                    if (!stableSince)
+                        stableSince = Date.now();
+                    if (Date.now() - stableSince >= stableMs)
+                        return;
+                }
+                else {
+                    lastSignature = current.signature;
+                    stableSince = Date.now();
+                }
+            }
+            else {
+                lastSignature = current.signature;
+                stableSince = 0;
+            }
+            await new Promise((resolve) => setTimeout(resolve, pollMs));
+        }
+    }
+    extractExpectedFiles(message = '', context = {}) {
+        const candidates = new Set();
+        for (const value of [message, context.rawMessage, context.agentPrompt]) {
+            const text = String(value || '');
+            for (const pattern of [/`([^`]+\.(?:html|css|js|jsx|ts|tsx|json|md|py|sh))`/gi, /\b([A-Za-z0-9_./-]+\.(?:html|css|js|jsx|ts|tsx|json|md|py|sh))\b/g]) {
+                let match;
+                while ((match = pattern.exec(text)) !== null) {
+                    const filePath = match[1].trim().replace(/^\.\//, '');
+                    if (filePath && !/^https?:\/\//i.test(filePath) && !isSensitivePath(filePath))
+                        candidates.add(filePath);
+                }
+            }
+        }
+        return [...candidates];
+    }
+    captureMutation(event, streamedFiles, serverRoot) {
+        if (!event || !streamedFiles)
+            return;
+        if (event.type === 'file_mutation' && typeof event.path === 'string') {
+            const filePath = this.normalizeRelativePath(event.path, serverRoot || undefined);
+            if (!filePath || isSensitivePath(filePath))
+                return;
+            if (event.action === 'delete')
+                delete streamedFiles[filePath];
+            else if (typeof event.content === 'string')
+                streamedFiles[filePath] = event.content;
+            return;
+        }
+        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 : '');
+            const filePath = this.normalizeRelativePath(targetPath, serverRoot || undefined);
+            if ((name === 'write_file' || name === 'edit_file') && filePath && !isSensitivePath(filePath) && typeof args.content === 'string') {
+                streamedFiles[filePath] = args.content;
+            }
+        }
+    }
+    applyStreamEvent(event, context = {}, serverRoot) {
+        if (!event || !['file_mutation', 'workspace_snapshot'].includes(String(event.type || '')))
+            return false;
+        const rootPath = this.dependencies.resolveTargetPath(context);
+        if (!rootPath)
+            return false;
+        if (event.type === 'workspace_snapshot' && event.files && typeof event.files === 'object') {
+            let applied = false;
+            for (const [rawPath, content] of Object.entries(event.files)) {
+                if (typeof content === 'string')
+                    applied = this.writeFile(rootPath, rawPath, content, serverRoot || undefined) || applied;
+            }
+            return applied;
+        }
+        const relativePath = this.normalizeRelativePath(event.path, serverRoot || undefined);
+        if (!relativePath)
+            return false;
+        if (event.action === 'delete')
+            return this.deleteFile(rootPath, relativePath);
+        return typeof event.content === 'string' && this.writeFile(rootPath, relativePath, event.content, rootPath);
+    }
+    resolveClientToolPath(rootPath, rawPath, sourceRoots = []) {
+        const raw = String(rawPath || '.').trim();
+        const roots = [rootPath, ...sourceRoots.filter(Boolean)];
+        let relativePath = '';
+        for (const sourceRoot of roots) {
+            relativePath = this.normalizeRelativePath(raw, sourceRoot);
+            if (relativePath || raw === '.' || raw === '')
+                break;
+        }
+        if (!relativePath && raw !== '.' && raw !== '' && !roots.some((sourceRoot) => isV3WorkspaceRootAliasPath(raw, sourceRoot)))
+            return null;
+        if (relativePath && isSensitivePath(relativePath))
+            return null;
+        try {
+            const absolutePath = relativePath
+                ? resolveWorkspacePath(rootPath, relativePath, { allowMissing: true })
+                : fs.realpathSync(path.resolve(rootPath));
+            return { relativePath: relativePath || '.', absolutePath };
+        }
+        catch {
+            return null;
+        }
+    }
+    writeFile(rootPath, rawPath, content, sourceRoot) {
+        const relativePath = this.normalizeRelativePath(rawPath, sourceRoot || rootPath);
+        if (!relativePath || isSensitivePath(relativePath)) {
+            this.dependencies.warn(`Refusing to write V3 path: ${path.basename(relativePath || rawPath)}`);
+            return false;
+        }
+        let absolutePath;
+        try {
+            absolutePath = resolveWorkspacePath(rootPath, relativePath, { allowMissing: true });
+        }
+        catch {
+            this.dependencies.warn(`Refusing to write V3 file outside workspace: ${rawPath}`);
+            return false;
+        }
+        try {
+            fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
+            if (fs.existsSync(absolutePath) && fs.readFileSync(absolutePath, 'utf8') === content)
+                return false;
+            fs.writeFileSync(absolutePath, content, 'utf8');
+            return true;
+        }
+        catch (error) {
+            this.dependencies.warn(`Failed to write V3 file ${relativePath}: ${error.message}`);
+            return false;
+        }
+    }
+    deleteFile(rootPath, rawPath) {
+        const relativePath = this.normalizeRelativePath(rawPath, rootPath);
+        if (!relativePath || isSensitivePath(relativePath))
+            return false;
+        try {
+            const absolutePath = resolveWorkspacePath(rootPath, relativePath);
+            if (fs.existsSync(absolutePath) && fs.statSync(absolutePath).isFile()) {
+                fs.unlinkSync(absolutePath);
+                return true;
+            }
+        }
+        catch (error) {
+            this.dependencies.warn(`Failed to delete V3 file ${relativePath}: ${error.message}`);
+        }
+        return false;
+    }
+    recover(context = {}, streamedFiles = {}, expectedFiles = []) {
+        const rootPath = this.dependencies.resolveTargetPath(context);
+        if (!rootPath || Object.keys(streamedFiles).length === 0)
+            return;
+        try {
+            fs.mkdirSync(rootPath, { recursive: true });
+        }
+        catch {
+            return;
+        }
+        const targets = expectedFiles.length > 0 ? [...new Set([...expectedFiles, ...Object.keys(streamedFiles)])] : Object.keys(streamedFiles);
+        for (const targetPath of targets) {
+            const relativePath = this.normalizeRelativePath(targetPath, rootPath);
+            const content = streamedFiles[relativePath];
+            if (relativePath && typeof content === 'string')
+                this.writeFile(rootPath, relativePath, content, rootPath);
+        }
+    }
+    normalizeRelativePath(rawPath, rootPath) {
+        return normalizeV3WorkspaceRelativePath(rawPath, rootPath);
+    }
+}