@xenosystem/agent-interface-host 0.1.3

package/dist/workspace/WorkspaceHostService.js

@@ -0,0 +1,841 @@
+import { spawn } from 'node:child_process';
+import { commandSucceeded } from '../isolation/CommandExecution.js';
+import { LocalCommandExecutor } from '../isolation/LocalCommandExecutor.js';
+/**
+ * ⚠️ This file has THREE process starts. Only ONE is adopted, and naming all
+ * three matters — an earlier version of this note said "the PTY is not part of
+ * this adoption", which was true and skipped `startTerminal` entirely. Naming
+ * one of several paths is the same mistake as naming the wrong one.
+ *
+ * 1. `runCommand` — ADOPTED. Runs through `CommandExecutionPort`.
+ * 2. `startTerminal` — still spawns directly. A fire-and-forget session that
+ *    outlives its request and is reaped by its own timer, so it is not the
+ *    port's one-call-one-result shape either.
+ * 3. `startPty` — a streaming, interactive session: stdin, resize, continuous
+ *    output. `xeno-use`'s exec surface has the SAME gap — `Command::output()`
+ *    buffers to completion — so streaming exec is recorded there as a new
+ *    capability rather than a defect. Forcing either through this port would
+ *    mean inventing a shape neither side has.
+ */
+const commandExecutor = new LocalCommandExecutor();
+import { closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, statSync, writeFileSync, } from 'node:fs';
+import { dirname, extname, isAbsolute, join, relative, resolve } from 'node:path';
+import { evaluateIpcPolicy } from '../policy/policyGuard.js';
+import { ScrollbackBuffer } from './scrollbackBuffer.js';
+const MAX_FILE_BYTES = 1024 * 1024;
+const MAX_COMMAND_OUTPUT_BYTES = 200_000;
+const MAX_PTY_SCROLLBACK_BYTES = 500_000;
+const MAX_GRANTS = 1_000;
+/**
+ * Host-owned workspace authority, migrated from XENO Hub's workspace IPC
+ * implementation. The renderer can narrow trusted grants but cannot mint new
+ * roots; only the desktop/Hub composition calls grantDirectory after a native
+ * user picker or an audited migration.
+ */
+export class WorkspaceHostService {
+    grantStorePath;
+    applicationGrantStorePath;
+    managedConversationRoot;
+    terminalSessions = new Map();
+    ptySessions = new Map();
+    grants = new Map();
+    applicationGrants = new Map();
+    eventSink = () => { };
+    nodePtyLoadPromise = null;
+    nodePtyLoadError = null;
+    executionEnvironment;
+    constructor(options) {
+        this.executionEnvironment = options.executionEnvironment;
+        const rootDirectory = resolve(options.rootDirectory);
+        mkdirSync(rootDirectory, { recursive: true });
+        this.grantStorePath = join(rootDirectory, 'workspace-grants.json');
+        this.applicationGrantStorePath = join(rootDirectory, 'application-grants.json');
+        this.managedConversationRoot = options.managedConversationRoot
+            ? resolve(options.managedConversationRoot)
+            : null;
+        this.loadGrants();
+        this.loadApplicationGrants();
+    }
+    setEventSink(sink) {
+        this.eventSink = sink;
+    }
+    grantDirectory(request) {
+        try {
+            const requested = cleanPath(request.path);
+            if (!requested)
+                return { success: false, path: null, error: 'Directory path is empty.' };
+            if (!existsSync(requested) || !statSync(requested).isDirectory()) {
+                return { success: false, path: null, error: 'Selected directory does not exist.' };
+            }
+            const canonical = canonicalExistingPath(requested);
+            const key = pathKey(canonical);
+            this.grants.set(key, {
+                path: canonical,
+                source: request.source,
+                createdAt: this.grants.get(key)?.createdAt || Date.now(),
+            });
+            this.persistGrants();
+            return { success: true, path: canonical, error: null };
+        }
+        catch (error) {
+            return { success: false, path: null, error: safeError(error, 'Failed to grant workspace access.') };
+        }
+    }
+    /**
+     * The directories the user has explicitly granted, canonicalised.
+     *
+     * 🔴 Read-only, and it mints nothing. The comment above `grantDirectory`
+     * states the rule this preserves: the renderer can narrow trusted grants but
+     * cannot create roots, and only the desktop/Hub composition grants one after a
+     * native dialog. Exposing the SET is not exposing the ability to add to it.
+     *
+     * It exists because a host-side feature that needs "the user's project" has
+     * exactly one honest answer: what they authorised. Anything else — the home
+     * directory, a guess from the process cwd — would read a tree nobody
+     * permitted, which is the failure the workspace authority exists to prevent.
+     */
+    grantedDirectories() {
+        return [...this.grants.values()].map((grant) => grant.path);
+    }
+    grantApplication(request) {
+        try {
+            const requested = cleanPath(request.path);
+            if (!requested)
+                return { success: false, appPath: null, error: 'Application path is empty.' };
+            if (!existsSync(requested) || !statSync(requested).isFile()) {
+                return { success: false, appPath: null, error: 'Selected application does not exist.' };
+            }
+            const canonical = canonicalExistingPath(requested);
+            const key = pathKey(canonical);
+            this.applicationGrants.set(key, {
+                path: canonical,
+                source: request.source,
+                createdAt: this.applicationGrants.get(key)?.createdAt || Date.now(),
+            });
+            this.persistApplicationGrants();
+            return { success: true, appPath: canonical, error: null };
+        }
+        catch (error) {
+            return { success: false, appPath: null, error: safeError(error, 'Failed to grant application access.') };
+        }
+    }
+    authorizeExistingFile(request, action, id = 'workspace.file.authorize') {
+        const authorized = this.authorizePath(request, request.path, action, id);
+        if (authorized.error)
+            return { success: false, path: null, error: authorized.error };
+        const filePath = authorized.path;
+        try {
+            if (!existsSync(filePath))
+                return { success: false, path: null, error: 'File not found.' };
+            if (!statSync(filePath).isFile()) {
+                return { success: false, path: null, error: 'Target path is not a file.' };
+            }
+            return { success: true, path: canonicalExistingPath(filePath), error: null };
+        }
+        catch (error) {
+            return { success: false, path: null, error: safeError(error, 'Failed to inspect file path.') };
+        }
+    }
+    authorizeApplication(request) {
+        const requestedPath = cleanPath(request.appPath);
+        if (!requestedPath)
+            return { success: false, appPath: null, error: 'Application path is empty.' };
+        try {
+            if (!existsSync(requestedPath) || !statSync(requestedPath).isFile()) {
+                return { success: false, appPath: null, error: 'Executable file not found.' };
+            }
+            const canonical = canonicalExistingPath(requestedPath);
+            const key = pathKey(canonical);
+            const allowed = normalizeExistingFiles(request.allowedApplications);
+            if (!this.applicationGrants.has(key) || !allowed.some((candidate) => pathKey(candidate) === key)) {
+                return { success: false, appPath: canonical, error: 'Application is not allowlisted by the host.' };
+            }
+            const evaluation = evaluateIpcPolicy({
+                caller: {
+                    workspaceId: request.workspaceId,
+                    teamId: request.teamId,
+                    agentId: request.agentId,
+                    allowedDirectories: [dirname(canonical)],
+                },
+                workspaceId: request.workspaceId,
+                teamId: request.teamId,
+                agentId: request.agentId,
+                allowedDirectories: [dirname(canonical)],
+                rootDirectory: dirname(canonical),
+            }, { action: 'execute', kind: 'app', id: 'workspace.app.open', path: canonical });
+            if (!evaluation.allowed) {
+                return { success: false, appPath: canonical, error: `Policy denied: ${evaluation.decision.reason}` };
+            }
+            return { success: true, appPath: canonical, error: null };
+        }
+        catch (error) {
+            return { success: false, appPath: null, error: safeError(error, 'Failed to inspect application path.') };
+        }
+    }
+    listDirectory(request) {
+        const denied = this.authorizePath(request, request.dirPath, 'read', 'workspace.directory.list');
+        if (denied.error)
+            return { success: false, entries: [], error: denied.error };
+        const directory = denied.path;
+        try {
+            if (!existsSync(directory))
+                return { success: false, entries: [], error: 'Directory not found.' };
+            if (!statSync(directory).isDirectory()) {
+                return { success: false, entries: [], error: 'Target path is not a directory.' };
+            }
+            const entries = [];
+            for (const entry of readdirSync(directory, { withFileTypes: true })) {
+                const fullPath = resolve(directory, entry.name);
+                try {
+                    if (entry.isSymbolicLink() || lstatSync(fullPath).isSymbolicLink())
+                        continue;
+                    if (!isCanonicalPathInside(fullPath, denied.allowedRoots))
+                        continue;
+                    const stats = statSync(fullPath);
+                    const isDirectory = stats.isDirectory();
+                    if (!isDirectory && !stats.isFile())
+                        continue;
+                    entries.push({
+                        name: entry.name,
+                        path: fullPath,
+                        size: isDirectory ? 0 : stats.size,
+                        modified: stats.mtime.toISOString(),
+                        type: isDirectory ? 'directory' : 'file',
+                        extension: isDirectory ? '' : extname(entry.name).slice(1).toLowerCase(),
+                    });
+                }
+                catch {
+                    // Match the mature Hub behavior: one unreadable entry does not fail a listing.
+                }
+            }
+            entries.sort((left, right) => {
+                if (left.type !== right.type)
+                    return left.type === 'directory' ? -1 : 1;
+                return left.name.localeCompare(right.name, undefined, { numeric: true, sensitivity: 'base' });
+            });
+            return { success: true, entries, error: null };
+        }
+        catch (error) {
+            return { success: false, entries: [], error: safeError(error, 'Failed to list directory.') };
+        }
+    }
+    readFile(request) {
+        const denied = this.authorizePath(request, request.path, 'read', 'workspace.file.read');
+        if (denied.error)
+            return { success: false, path: null, content: '', bytes: 0, error: denied.error };
+        const filePath = denied.path;
+        try {
+            if (!existsSync(filePath)) {
+                return { success: false, path: null, content: '', bytes: 0, error: 'File not found.' };
+            }
+            const stats = statSync(filePath);
+            if (!stats.isFile()) {
+                return { success: false, path: null, content: '', bytes: 0, error: 'Target path is not a file.' };
+            }
+            if (stats.size > MAX_FILE_BYTES) {
+                return { success: false, path: filePath, content: '', bytes: stats.size, error: 'File exceeds 1MB limit.' };
+            }
+            const content = readFileSync(filePath);
+            if (content.includes(0)) {
+                return { success: false, path: filePath, content: '', bytes: stats.size, error: 'Binary files are not supported yet.' };
+            }
+            return { success: true, path: filePath, content: content.toString('utf8'), bytes: stats.size, error: null };
+        }
+        catch (error) {
+            return { success: false, path: filePath, content: '', bytes: 0, error: safeError(error, 'Failed to read file.') };
+        }
+    }
+    writeFile(request) {
+        if (Buffer.byteLength(request.content || '', 'utf8') > MAX_FILE_BYTES) {
+            return { success: false, path: null, bytes: 0, error: 'File content exceeds 1MB limit.' };
+        }
+        const denied = this.authorizePath(request, request.path, 'write', 'workspace.file.write', true);
+        if (denied.error)
+            return { success: false, path: null, bytes: 0, error: denied.error };
+        const filePath = denied.path;
+        try {
+            mkdirSync(dirname(filePath), { recursive: true });
+            if (!isCanonicalPathInside(filePath, denied.allowedRoots, true)) {
+                return { success: false, path: null, bytes: 0, error: 'Target path resolves outside trusted workspace grants.' };
+            }
+            writeFileSync(filePath, request.content || '', { encoding: 'utf8' });
+            return {
+                success: true,
+                path: filePath,
+                bytes: Buffer.byteLength(request.content || '', 'utf8'),
+                error: null,
+            };
+        }
+        catch (error) {
+            return { success: false, path: filePath, bytes: 0, error: safeError(error, 'Failed to write file.') };
+        }
+    }
+    async runCommand(request) {
+        const command = String(request.command || '').trim();
+        if (!command)
+            return commandFailure('Command is empty.');
+        if (containsForbiddenSyntax(command))
+            return commandFailure('Command contains forbidden shell syntax.');
+        if (containsDangerousAction(command))
+            return commandFailure('Command blocked for safety.');
+        const denied = this.authorizePath(request, request.cwd || request.allowedDirectories[0] || '', 'execute', 'workspace.command.run');
+        if (denied.error)
+            return commandFailure(denied.error);
+        const cwd = denied.path;
+        if (!existsSync(cwd) || !statSync(cwd).isDirectory())
+            return commandFailure('Working directory not found.');
+        const timeoutMs = clampInteger(request.timeoutMs, 20_000, 1_000, 120_000);
+        /**
+         * The SECOND adopter of `CommandExecutionPort` — ADE §5.3.
+         *
+         * 🔴 The guards above stay here, deliberately. `containsForbiddenSyntax`,
+         * `containsDangerousAction` and `authorizePath` are CALLER-side policy: they
+         * decide whether this host is willing to ask for the command at all, which
+         * is a different question from where it then runs. Pushing them into the
+         * executor would apply them to every future caller — including a sandboxed
+         * one, where a path allowlist is the wrong instrument — and would put a
+         * rule inside the shared callee that only one caller means.
+         *
+         * ⚠️ None of them is containment. §5.3 is explicit that a rule inside the
+         * shell it runs in does not confine anything; these reduce what gets asked
+         * for, and the substrate is what will refuse.
+         *
+         * `shellInvocation` already returns `{command, args}`, so this site needed
+         * no argv change at all — it was already spelling a shell AS argv, which is
+         * the pattern the port's rule generalises rather than imposes.
+         */
+        const invocation = shellInvocation(command, true);
+        // 🔴 Resolved PER CALL, from the conversation this request belongs to.
+        // Caching an executor on the service would outlive the run that justified
+        // it and keep sending commands to a torn-down container — or, worse, keep
+        // reporting containment after it ended. With no environment injected this
+        // is the module's local executor, exactly as before.
+        const executor = this.executionEnvironment?.executorFor(request.conversationId)
+            ?? commandExecutor;
+        const result = await executor.execute({
+            argv: [invocation.command, ...invocation.args],
+            cwd,
+            timeoutMs,
+            maxOutputBytes: MAX_COMMAND_OUTPUT_BYTES,
+        });
+        return {
+            success: commandSucceeded(result),
+            stdout: result.stdout,
+            stderr: result.stderr,
+            exitCode: result.exitCode,
+            cwd,
+            // The contract uses `null` for absence here; the port omits the key.
+            error: result.error ?? null,
+            // 🔴 Newly REPORTED rather than newly happening. This method has always
+            // trimmed at 200 KB; it just never said so, and a caller reading a short
+            // output concluded that was all the command printed.
+            truncated: result.truncated,
+        };
+    }
+    startTerminal(request) {
+        const command = String(request.command || '').trim();
+        if (!command)
+            return terminalStartFailure('Command is empty.');
+        if (containsDangerousAction(command))
+            return terminalStartFailure('Command blocked for safety.');
+        const denied = this.authorizePath(request, request.cwd || request.allowedDirectories[0] || '', 'execute', 'workspace.terminal.start');
+        if (denied.error)
+            return terminalStartFailure(denied.error);
+        const cwd = denied.path;
+        const timeoutMs = clampInteger(request.timeoutMs, 300_000, 1_000, 900_000);
+        const terminalId = uniqueId('terminal');
+        const invocation = shellInvocation(command, false);
+        try {
+            const child = spawn(invocation.command, invocation.args, {
+                cwd,
+                windowsHide: true,
+                shell: false,
+                env: process.env,
+            });
+            const session = {
+                id: terminalId,
+                ownerInstanceId: request.client.instanceId,
+                command,
+                cwd,
+                process: child,
+                timer: null,
+                timedOut: false,
+            };
+            this.terminalSessions.set(terminalId, session);
+            session.timer = setTimeout(() => {
+                const active = this.terminalSessions.get(terminalId);
+                if (!active)
+                    return;
+                active.timedOut = true;
+                active.process.kill();
+            }, timeoutMs);
+            child.stdout.on('data', (chunk) => {
+                this.eventSink('workspace.terminal.data', { terminalId, stream: 'stdout', chunk: chunk.toString() });
+            });
+            child.stderr.on('data', (chunk) => {
+                this.eventSink('workspace.terminal.data', { terminalId, stream: 'stderr', chunk: chunk.toString() });
+            });
+            child.once('error', (error) => {
+                const active = this.cleanupTerminal(terminalId);
+                if (!active)
+                    return;
+                this.eventSink('workspace.terminal.exit', {
+                    terminalId,
+                    command,
+                    cwd,
+                    success: false,
+                    exitCode: null,
+                    error: error.message || 'Failed to start terminal command.',
+                    ownerInstanceId: active?.ownerInstanceId || request.client.instanceId,
+                });
+            });
+            child.once('close', (exitCode) => {
+                const active = this.cleanupTerminal(terminalId);
+                if (!active)
+                    return;
+                this.eventSink('workspace.terminal.exit', {
+                    terminalId,
+                    command,
+                    cwd,
+                    success: !active.timedOut && exitCode === 0,
+                    exitCode,
+                    error: active.timedOut ? `Command timed out after ${timeoutMs}ms.` : null,
+                    ownerInstanceId: active.ownerInstanceId,
+                });
+            });
+            return { success: true, terminalId, cwd, error: null };
+        }
+        catch (error) {
+            return { success: false, terminalId: null, cwd, error: safeError(error, 'Failed to start terminal command.') };
+        }
+    }
+    stopTerminal(request) {
+        const session = this.terminalSessions.get(String(request.terminalId || '').trim());
+        const denied = this.authorizeSession(request, session);
+        if (denied)
+            return { success: false, error: denied };
+        session.process.kill();
+        return { success: true, error: null };
+    }
+    async startPty(request) {
+        const denied = this.authorizePath(request, request.cwd || request.allowedDirectories[0] || '', 'execute', 'workspace.pty.start');
+        if (denied.error)
+            return ptyStartFailure(denied.error);
+        const cwd = denied.path;
+        const terminalId = uniqueId('pty');
+        const cols = clampInteger(request.cols, 80, 20, 240);
+        const rows = clampInteger(request.rows, 24, 6, 120);
+        try {
+            const nodePty = await this.loadNodePty();
+            if (!nodePty) {
+                return ptyStartFailure(`PTY terminal is unavailable${this.nodePtyLoadError ? `: ${this.nodePtyLoadError}` : '.'}`, cwd);
+            }
+            const shell = process.platform === 'win32' ? 'powershell.exe' : (process.env.SHELL || '/bin/bash');
+            const args = process.platform === 'win32' ? ['-NoLogo'] : [];
+            const processHandle = nodePty.spawn(shell, args, {
+                name: 'xterm-256color',
+                cols,
+                rows,
+                cwd,
+                env: { ...process.env, TERM: 'xterm-256color', COLORTERM: 'truecolor' },
+                ...(process.platform === 'win32' ? { useConpty: true, useConptyDll: true } : {}),
+            });
+            const session = {
+                id: terminalId,
+                ownerInstanceId: request.client.instanceId,
+                cwd,
+                process: processHandle,
+                output: new ScrollbackBuffer(MAX_PTY_SCROLLBACK_BYTES),
+            };
+            this.ptySessions.set(terminalId, session);
+            processHandle.onData((data) => {
+                const active = this.ptySessions.get(terminalId);
+                if (!active)
+                    return;
+                active.output.append(data);
+                this.eventSink('workspace.pty.data', { terminalId, data, ownerInstanceId: active.ownerInstanceId });
+            });
+            processHandle.onExit(({ exitCode, signal }) => {
+                const active = this.ptySessions.get(terminalId);
+                this.ptySessions.delete(terminalId);
+                this.eventSink('workspace.pty.exit', {
+                    terminalId,
+                    exitCode,
+                    signal,
+                    ownerInstanceId: active?.ownerInstanceId || request.client.instanceId,
+                });
+            });
+            return { success: true, terminalId, cwd, error: null };
+        }
+        catch (error) {
+            return { success: false, terminalId: null, cwd, error: safeError(error, 'Failed to start PTY terminal.') };
+        }
+    }
+    snapshotPty(request) {
+        const terminalId = String(request.terminalId || '').trim();
+        const session = this.ptySessions.get(terminalId);
+        const denied = this.authorizeSession(request, session);
+        if (denied) {
+            return { success: false, exists: !!session, terminalId, cwd: null, output: '', error: denied };
+        }
+        return { success: true, exists: true, terminalId, cwd: session.cwd, output: session.output.read(), error: null };
+    }
+    inputPty(request) {
+        const session = this.ptySessions.get(String(request.terminalId || '').trim());
+        const denied = this.authorizeSession(request, session);
+        if (denied)
+            return { success: false, error: denied };
+        session.process.write(String(request.data || '').slice(0, 100_000));
+        return { success: true, error: null };
+    }
+    resizePty(request) {
+        const session = this.ptySessions.get(String(request.terminalId || '').trim());
+        const denied = this.authorizeSession(request, session);
+        if (denied)
+            return { success: false, error: denied };
+        session.process.resize(clampInteger(request.cols, 80, 20, 240), clampInteger(request.rows, 24, 6, 120));
+        return { success: true, error: null };
+    }
+    clearPty(request) {
+        const session = this.ptySessions.get(String(request.terminalId || '').trim());
+        const denied = this.authorizeSession(request, session);
+        if (denied)
+            return { success: false, error: denied };
+        session.output.clear();
+        return { success: true, error: null };
+    }
+    stopPty(request) {
+        const session = this.ptySessions.get(String(request.terminalId || '').trim());
+        const denied = this.authorizeSession(request, session);
+        if (denied)
+            return { success: false, error: denied };
+        this.ptySessions.delete(session.id);
+        session.process.kill();
+        return { success: true, error: null };
+    }
+    close() {
+        for (const session of this.terminalSessions.values()) {
+            if (session.timer)
+                clearTimeout(session.timer);
+            try {
+                session.process.kill();
+            }
+            catch { /* process already exited */ }
+        }
+        this.terminalSessions.clear();
+        for (const session of this.ptySessions.values()) {
+            try {
+                session.process.kill();
+            }
+            catch { /* process already exited */ }
+        }
+        this.ptySessions.clear();
+    }
+    authorizePath(request, rawPath, action, id, allowMissing = false) {
+        const path = cleanPath(rawPath);
+        if (!path)
+            return { path: null, allowedRoots: [], error: 'Path is empty.' };
+        const allowedRoots = this.effectiveAllowedRoots(request.allowedDirectories, request.conversationId);
+        if (allowedRoots.length === 0) {
+            return { path: null, allowedRoots, error: 'No trusted workspace directories are granted.' };
+        }
+        if (!isCanonicalPathInside(path, allowedRoots, allowMissing)) {
+            return { path: null, allowedRoots, error: 'Path is outside trusted workspace grants.' };
+        }
+        const evaluation = evaluateIpcPolicy({
+            caller: {
+                workspaceId: request.workspaceId,
+                teamId: request.teamId,
+                agentId: request.agentId,
+                allowedDirectories: allowedRoots,
+            },
+            workspaceId: request.workspaceId,
+            teamId: request.teamId,
+            agentId: request.agentId,
+            conversationId: request.conversationId,
+            allowedDirectories: allowedRoots,
+            rootDirectory: path,
+        }, { action, kind: action === 'execute' ? 'tool' : 'file', id, path });
+        if (!evaluation.allowed) {
+            return { path: null, allowedRoots, error: `Policy denied: ${evaluation.decision.reason}` };
+        }
+        return { path, allowedRoots, error: null };
+    }
+    authorizeSession(request, session) {
+        if (!session)
+            return 'Terminal session not found.';
+        if (session.ownerInstanceId !== request.client.instanceId)
+            return 'Terminal session belongs to another surface.';
+        return null;
+    }
+    effectiveAllowedRoots(requestedDirectories, conversationId) {
+        const requested = normalizeExistingDirectories(requestedDirectories);
+        const trusted = [...this.grants.values()].map((grant) => grant.path);
+        const effective = requested.filter((candidate) => trusted.some((root) => isSubPath(candidate, root)));
+        const conversationRoot = this.resolveManagedConversationRoot(conversationId);
+        if (conversationRoot && !effective.some((candidate) => pathKey(candidate) === pathKey(conversationRoot))) {
+            effective.push(conversationRoot);
+        }
+        return effective;
+    }
+    resolveManagedConversationRoot(conversationId) {
+        if (!this.managedConversationRoot || typeof conversationId !== 'string' || !conversationId.trim())
+            return null;
+        const safeConversationId = conversationId
+            .replace(/[^A-Za-z0-9._-]/g, '_')
+            .slice(0, 120) || 'conversation';
+        const candidate = resolve(this.managedConversationRoot, safeConversationId);
+        try {
+            if (!existsSync(candidate) || !statSync(candidate).isDirectory())
+                return null;
+            const canonicalManagedRoot = canonicalExistingPath(this.managedConversationRoot);
+            const canonicalConversationRoot = canonicalExistingPath(candidate);
+            return isSubPath(canonicalConversationRoot, canonicalManagedRoot) ? canonicalConversationRoot : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    cleanupTerminal(terminalId) {
+        const session = this.terminalSessions.get(terminalId);
+        if (!session)
+            return undefined;
+        if (session.timer)
+            clearTimeout(session.timer);
+        session.timer = null;
+        this.terminalSessions.delete(terminalId);
+        return session;
+    }
+    async loadNodePty() {
+        if (!this.nodePtyLoadPromise) {
+            this.nodePtyLoadPromise = import('node-pty')
+                .then((loaded) => {
+                const namespace = loaded;
+                const module = (namespace.default || namespace);
+                if (typeof module.spawn !== 'function')
+                    throw new Error('node-pty did not expose a spawn function.');
+                this.nodePtyLoadError = null;
+                return module;
+            })
+                .catch((error) => {
+                this.nodePtyLoadError = safeError(error, 'Failed to load node-pty.');
+                return null;
+            });
+        }
+        return this.nodePtyLoadPromise;
+    }
+    loadGrants() {
+        try {
+            if (!existsSync(this.grantStorePath))
+                return;
+            const parsed = JSON.parse(readFileSync(this.grantStorePath, 'utf8'));
+            if (parsed.version !== 1 || !Array.isArray(parsed.grants))
+                return;
+            for (const grant of parsed.grants.slice(0, MAX_GRANTS)) {
+                if (!grant || typeof grant.path !== 'string' || !existsSync(grant.path))
+                    continue;
+                if (!statSync(grant.path).isDirectory())
+                    continue;
+                const canonical = canonicalExistingPath(grant.path);
+                this.grants.set(pathKey(canonical), {
+                    path: canonical,
+                    source: grant.source === 'legacy-migration' || grant.source === 'host-managed'
+                        ? grant.source
+                        : 'user-picker',
+                    createdAt: typeof grant.createdAt === 'number' ? grant.createdAt : Date.now(),
+                });
+            }
+        }
+        catch {
+            // A corrupt grant file fails closed. The user can select the directory again.
+            this.grants.clear();
+        }
+    }
+    loadApplicationGrants() {
+        try {
+            if (!existsSync(this.applicationGrantStorePath))
+                return;
+            const parsed = JSON.parse(readFileSync(this.applicationGrantStorePath, 'utf8'));
+            if (parsed.version !== 1 || !Array.isArray(parsed.applications))
+                return;
+            for (const grant of parsed.applications.slice(0, MAX_GRANTS)) {
+                if (!grant || typeof grant.path !== 'string' || !existsSync(grant.path))
+                    continue;
+                if (!statSync(grant.path).isFile())
+                    continue;
+                const canonical = canonicalExistingPath(grant.path);
+                this.applicationGrants.set(pathKey(canonical), {
+                    path: canonical,
+                    source: grant.source === 'legacy-migration' || grant.source === 'host-managed'
+                        ? grant.source
+                        : 'user-picker',
+                    createdAt: typeof grant.createdAt === 'number' ? grant.createdAt : Date.now(),
+                });
+            }
+        }
+        catch {
+            // A corrupt executable grant file fails closed.
+            this.applicationGrants.clear();
+        }
+    }
+    persistGrants() {
+        const payload = {
+            version: 1,
+            grants: [...this.grants.values()]
+                .sort((left, right) => left.createdAt - right.createdAt || left.path.localeCompare(right.path))
+                .slice(-MAX_GRANTS),
+        };
+        const temporary = `${this.grantStorePath}.tmp-${process.pid}-${Date.now()}`;
+        writeFileSync(temporary, JSON.stringify(payload, null, 2), 'utf8');
+        const descriptor = openSync(temporary, 'r+');
+        try {
+            fsyncSync(descriptor);
+        }
+        finally {
+            closeSync(descriptor);
+        }
+        renameSync(temporary, this.grantStorePath);
+    }
+    persistApplicationGrants() {
+        const payload = {
+            version: 1,
+            applications: [...this.applicationGrants.values()]
+                .sort((left, right) => left.createdAt - right.createdAt || left.path.localeCompare(right.path))
+                .slice(-MAX_GRANTS),
+        };
+        persistJsonAtomically(this.applicationGrantStorePath, payload);
+    }
+}
+function normalizeExistingDirectories(values) {
+    const result = [];
+    const seen = new Set();
+    for (const value of Array.isArray(values) ? values.slice(0, 100) : []) {
+        try {
+            const path = canonicalExistingPath(String(value || ''));
+            if (!statSync(path).isDirectory())
+                continue;
+            const key = pathKey(path);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            result.push(path);
+        }
+        catch {
+            // Invalid/unavailable roots are ignored and therefore fail closed.
+        }
+    }
+    return result;
+}
+function normalizeExistingFiles(values) {
+    const result = [];
+    const seen = new Set();
+    for (const value of Array.isArray(values) ? values.slice(0, 100) : []) {
+        try {
+            const path = canonicalExistingPath(String(value || ''));
+            if (!statSync(path).isFile())
+                continue;
+            const key = pathKey(path);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            result.push(path);
+        }
+        catch {
+            // Invalid/unavailable application paths are ignored and therefore fail closed.
+        }
+    }
+    return result;
+}
+function persistJsonAtomically(path, payload) {
+    const temporary = `${path}.tmp-${process.pid}-${Date.now()}`;
+    writeFileSync(temporary, JSON.stringify(payload, null, 2), 'utf8');
+    const descriptor = openSync(temporary, 'r+');
+    try {
+        fsyncSync(descriptor);
+    }
+    finally {
+        closeSync(descriptor);
+    }
+    renameSync(temporary, path);
+}
+function canonicalExistingPath(path) {
+    return realpathSync.native(resolve(path));
+}
+function canonicalForContainment(path, allowMissing) {
+    const absolute = resolve(path);
+    if (existsSync(absolute))
+        return canonicalExistingPath(absolute);
+    if (!allowMissing)
+        return null;
+    let ancestor = dirname(absolute);
+    while (!existsSync(ancestor)) {
+        const parent = dirname(ancestor);
+        if (parent === ancestor)
+            return null;
+        ancestor = parent;
+    }
+    const canonicalAncestor = canonicalExistingPath(ancestor);
+    const remainder = relative(ancestor, absolute);
+    if (!remainder || remainder.startsWith('..') || isAbsolute(remainder))
+        return null;
+    return resolve(canonicalAncestor, remainder);
+}
+function isCanonicalPathInside(path, roots, allowMissing = false) {
+    const canonical = canonicalForContainment(path, allowMissing);
+    return !!canonical && roots.some((root) => isSubPath(canonical, root));
+}
+function isSubPath(childPath, parentPath) {
+    const child = pathKey(resolve(childPath));
+    const parent = pathKey(resolve(parentPath));
+    if (child === parent)
+        return true;
+    const separator = process.platform === 'win32' ? '\\' : '/';
+    return child.startsWith(parent.endsWith(separator) ? parent : `${parent}${separator}`);
+}
+function pathKey(path) {
+    const normalized = resolve(path);
+    return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
+}
+function cleanPath(value) {
+    if (typeof value !== 'string' || !value.trim() || value.includes('\0'))
+        return '';
+    return resolve(value.trim());
+}
+function containsForbiddenSyntax(command) {
+    return /(\r|\n|&&|\|\||;|`|>|<|\$\()/.test(command);
+}
+function containsDangerousAction(command) {
+    return /\b(remove-item|rm|rmdir|del|erase|format|diskpart|shutdown|reboot|restart-computer|stop-computer)\b/i.test(command);
+}
+function shellInvocation(command, nonInteractive) {
+    if (process.platform === 'win32') {
+        return {
+            command: 'powershell.exe',
+            args: ['-NoLogo', '-NoProfile', ...(nonInteractive ? ['-NonInteractive'] : []), '-Command', command],
+        };
+    }
+    return { command: '/bin/bash', args: ['-lc', command] };
+}
+function clampInteger(value, fallback, minimum, maximum) {
+    return typeof value === 'number' && Number.isFinite(value)
+        ? Math.max(minimum, Math.min(maximum, Math.floor(value)))
+        : fallback;
+}
+function uniqueId(prefix) {
+    return `${prefix}_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+}
+function commandFailure(error) {
+    // `truncated: false` is a FACT here, not a filler: the command was refused
+    // before it ran, so there is no output and nothing was trimmed.
+    return { success: false, stdout: '', stderr: '', exitCode: null, cwd: null, error, truncated: false };
+}
+function terminalStartFailure(error) {
+    return { success: false, terminalId: null, cwd: null, error };
+}
+function ptyStartFailure(error, cwd = null) {
+    return { success: false, terminalId: null, cwd, error };
+}
+function safeError(error, fallback) {
+    return error instanceof Error && error.message.trim() ? error.message.slice(0, 1_000) : fallback;
+}
+//# sourceMappingURL=WorkspaceHostService.js.map