zerogterm 0.8.0-alpha.1 → 0.9.0-alpha.1

package/README.md

@@ -30,6 +30,7 @@ ZeroG Terminal is an alpha project, but it is already useful as a multi-session
 - AI command suggestions from any OpenAI-compatible endpoint — Ollama, LM Studio, llama.cpp, vLLM, OpenRouter, or OpenAI itself — configured with a base URL, a model and an optional key in Settings. Ask what you want, get one command with an explanation, and approve it before it runs.
 - Sandboxed Electron renderer, context isolation, disabled Node integration, and a narrow typed preload API.
 - Safe argument-array handling and validation around SSH and `screen` session operations.
+- Optional local MCP control for inspecting and restoring workspaces, and creating explicit project workspaces. It is loopback-only, bearer-authenticated, lease-controlled, and never executes terminal commands; see [docs/mcp.md](docs/mcp.md).
 
 The project is particularly useful for terminal-based AI development workflows: start an agent in a persistent session, disconnect or suffer an interrupted connection, and reconnect later to see what it has done and continue working.
 
@@ -37,7 +38,7 @@ See the project walkthrough on [YouTube](https://youtu.be/4aJZCxLHD14).
 
 ## Release status
 
-ZeroG Terminal is currently a public alpha. The current release is `0.8.0-alpha.1`; the version history is tracked in [versions.txt](versions.txt). The running version is shown beside the wordmark in the title bar, read from the app itself rather than written into the interface, so it is accurate in a packaged build too.
+ZeroG Terminal is currently a public alpha. The current release is `0.9.0-alpha.1`; the version history is tracked in [versions.txt](versions.txt). The running version is shown beside the wordmark in the title bar, read from the app itself rather than written into the interface, so it is accurate in a packaged build too.
 
 The GitHub Releases page provides a Windows x64 installer and portable executable for each desktop release. These alpha builds are intended for early adopters and testing rather than production use. The npm package remains available for developers who prefer to launch ZeroG from Node.js.
 

package/dist/main/main/main.js

@@ -1,5 +1,6 @@
 import { app, BrowserWindow, clipboard, ipcMain, Menu, safeStorage, session, shell } from 'electron';
 import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { writeClipboardText } from './clipboard.js';
 import { ScreenService, parseWslDistributions } from './session-service.js';
@@ -16,6 +17,13 @@ import { decideExternalLink, isApplicationUrl } from './external-links.js';
 import { SftpService } from './sftp-service.js';
 import { AI_API_KEY, SPEECH_API_KEY, SecretStore, defaultSecretsPath } from './secret-store.js';
 import { AiService } from './ai-service.js';
+import { McpControl } from './mcp-control.js';
+import { McpServerHost } from './mcp-server.js';
+import { McpExecutionBroker } from './mcp-execution-broker.js';
+import { McpAudit } from './mcp-audit.js';
+import { classifyMcpPrompt } from './prompt-classifier.js';
+import { isSafeRemoteCommand } from './mcp-execution-policy.js';
+import { requireWorkspaceName } from './mcp-protocol.js';
 const __dirname = fileURLToPath(new URL('.', import.meta.url));
 const history = new SessionHistoryStore({ filePath: defaultHistoryPath(app.getPath('userData')) });
 // The only store holding what the user typed. Nothing reaches it that has not
@@ -35,6 +43,90 @@ const sftp = new SftpService({ onEvent: (event) => win?.webContents.send('sftp:e
 // API keys for speech servers. safeStorage is only usable after the app is
 // ready, which every IPC call here already is.
 const secrets = new SecretStore({ filePath: defaultSecretsPath(app.getPath('userData')), crypto: safeStorage });
+const mcpControl = new McpControl({ onChange: (status) => win?.webContents.send('mcp:status', status) });
+const mcpExecutions = new McpExecutionBroker();
+const mcpAudit = new McpAudit();
+const mcpActiveExecutions = new Map();
+const mcpExecutionOutput = new Map();
+const mcpExecutionTimers = new Map();
+function clearMcpExecution(requestId, sessionId) {
+    const timer = mcpExecutionTimers.get(requestId);
+    if (timer)
+        clearTimeout(timer);
+    mcpExecutionTimers.delete(requestId);
+    mcpExecutionOutput.delete(requestId);
+    if (sessionId) {
+        if (mcpActiveExecutions.get(sessionId) === requestId)
+            mcpActiveExecutions.delete(sessionId);
+    }
+    else {
+        for (const [activeSessionId, activeRequestId] of Array.from(mcpActiveExecutions.entries())) {
+            if (activeRequestId === requestId)
+                mcpActiveExecutions.delete(activeSessionId);
+        }
+    }
+}
+let mcpHost;
+async function restoreWorkspace(workspaceId) {
+    const file = await workspaceStore.load();
+    const workspace = file.workspaces.find((item) => item.id === workspaceId);
+    if (!workspace)
+        throw new Error(`Unknown workspace: ${workspaceId}`);
+    const existing = await service.list();
+    const restored = [];
+    for (const member of workspace.members) {
+        const match = existing.find((session) => session.id === member.sessionId ||
+            (member.kind === 'ssh' && Boolean(member.sshTarget) && session.sshTarget === member.sshTarget) ||
+            (member.kind === 'local' && Boolean(member.screenName) && session.screenName === member.screenName));
+        if (match) {
+            restored.push({ member, session: match, action: 'reused' });
+            continue;
+        }
+        const session = member.kind === 'ssh' && member.sshTarget
+            ? await service.createSsh(member.sshTarget, member.name)
+            : await service.createLocal({ name: member.name, ...(member.cwd ? { cwd: member.cwd } : {}) });
+        restored.push({ member, session, action: 'created' });
+    }
+    win?.webContents.send('mcp:workspace-restored', { workspaceId, workspaceName: workspace.name, restored });
+    return { workspaceId, workspaceName: workspace.name, restored };
+}
+async function createWorkspace() {
+    const file = await workspaceStore.load();
+    const names = new Set(file.workspaces.map((workspace) => workspace.name.toLowerCase()));
+    let index = file.workspaces.length + 1;
+    while (names.has(`workspace-${index}`))
+        index += 1;
+    const workspace = { id: `ws-${randomUUID()}`, name: `workspace-${index}`, members: [], view: { layout: 'stack', lastSplit: 'split-v', maximizedSessionId: null } };
+    await workspaceStore.save({ version: 1, workspaces: [...file.workspaces, workspace], activeWorkspaceId: workspace.id });
+    win?.webContents.send('mcp:workspace-restored', { workspaceId: workspace.id, workspaceName: workspace.name, restored: [] });
+    return { workspaceId: workspace.id, workspaceName: workspace.name, restored: [] };
+}
+async function createProjectWorkspace(request) {
+    const name = requireWorkspaceName(request.name);
+    const file = await workspaceStore.load();
+    const existing = file.workspaces.find((item) => item.name === name);
+    const running = await service.list();
+    const workspaceId = existing?.id ?? `ws-${randomUUID()}`;
+    const sessions = [];
+    for (const project of request.projects) {
+        const reused = running.find((session) => session.kind === 'local' && session.name === project.name && session.cwd === project.cwd);
+        const session = reused ?? await service.createLocal({ name: project.name, cwd: project.cwd, ...(project.backend ? { backend: project.backend } : {}) });
+        sessions.push(session);
+    }
+    const members = sessions.map((session) => ({
+        sessionId: session.id,
+        kind: session.kind,
+        name: session.name,
+        ...(session.host ? { host: session.host } : {}),
+        ...(session.screenName ? { screenName: session.screenName } : {}),
+        ...(session.backend ? { backend: session.backend } : {}),
+        ...(session.kind === 'local' && session.cwd ? { cwd: session.cwd } : {})
+    }));
+    const workspace = { id: workspaceId, name, members, view: { layout: 'grid', lastSplit: 'grid', maximizedSessionId: null } };
+    await workspaceStore.save({ version: 1, workspaces: [...file.workspaces.filter((item) => item.id !== workspaceId), workspace], activeWorkspaceId: workspaceId });
+    win?.webContents.send('mcp:workspace-restored', { workspaceId, workspaceName: name, restored: sessions.map((session, index) => ({ member: members[index], session, action: 'created' })) });
+    return { workspaceId, workspaceName: name, restored: sessions };
+}
 /** A pane's measured size, as it arrives from the renderer. */
 function parsePtySize(value) {
     if (!value || typeof value !== 'object')
@@ -229,6 +321,126 @@ ipcMain.handle('forwards:load', () => forwardStore.load());
 ipcMain.handle('forwards:save', (_event, file) => forwardStore.save(file));
 ipcMain.handle('workspaces:load', () => workspaceStore.load());
 ipcMain.handle('workspaces:save', (_event, file) => workspaceStore.save(file));
+ipcMain.handle('mcp:status', () => mcpControl.status());
+ipcMain.handle('mcp:revoke', () => { mcpControl.revoke(); mcpExecutions.revokeAll(); for (const requestId of Array.from(mcpExecutionTimers.keys()))
+    clearMcpExecution(requestId); win?.webContents.send('mcp:execution', mcpExecutions.listAll()); });
+ipcMain.handle('mcp:executions:list', () => mcpExecutions.listAll());
+ipcMain.handle('mcp:audit:list', () => mcpAudit.list());
+async function runMcpExecution(requestId) {
+    const request = mcpExecutions.listAll().find((item) => item.requestId === requestId);
+    if (!request || !('sessionId' in request))
+        throw new Error('Unknown command request.');
+    const sessions = await service.list();
+    const session = sessions.find((item) => item.id === request.sessionId);
+    if (!session)
+        throw new Error('Only attached sessions may execute approved commands.');
+    const running = mcpExecutions.start(requestId);
+    mcpActiveExecutions.set(session.id, requestId);
+    mcpExecutionOutput.set(requestId, '');
+    mcpExecutionTimers.set(requestId, setTimeout(() => {
+        const output = mcpExecutionOutput.get(requestId) ?? '';
+        service.write(session.id, '\u0003');
+        const result = mcpExecutions.finishRunning(requestId, 'timed-out', output, output.length >= running.policy.maxOutputBytes, 'Execution timed out.');
+        clearMcpExecution(requestId, session.id);
+        win?.webContents.send('mcp:execution', result);
+        win?.webContents.send('terminal:status', session.id, 'MCP command timed out.');
+    }, running.policy.maxRuntimeMs));
+    service.write(session.id, `${running.command}\n`);
+    win?.webContents.send('mcp:execution', running);
+    return running;
+}
+ipcMain.handle('mcp:execution:approve', async (_event, requestId) => {
+    if (typeof requestId !== 'string' || !requestId)
+        throw new Error('A command request id is required.');
+    const pending = mcpExecutions.listAll().find((item) => item.requestId === requestId);
+    const result = mcpExecutions.decideFromUser(requestId, 'approve');
+    if (pending && 'clientId' in pending)
+        mcpAudit.record({ at: Date.now(), requestId, clientId: pending.clientId, capability: 'session:execute', sessionId: pending.sessionId, state: 'approved', command: pending.displayCommand });
+    mcpControl.require(result.clientId, 'session:execute');
+    return runMcpExecution(requestId);
+});
+ipcMain.handle('mcp:execution:reject', (_event, requestId) => {
+    if (typeof requestId !== 'string' || !requestId)
+        throw new Error('A command request id is required.');
+    const pending = mcpExecutions.listAll().find((item) => item.requestId === requestId);
+    const result = mcpExecutions.decideFromUser(requestId, 'reject');
+    if (pending && 'clientId' in pending)
+        mcpAudit.record({ at: Date.now(), requestId, clientId: pending.clientId, capability: 'session:execute', sessionId: pending.sessionId, state: 'rejected', command: pending.displayCommand });
+    clearMcpExecution(requestId);
+    win?.webContents.send('mcp:execution', result);
+    return result;
+});
+ipcMain.handle('mcp:execution:cancel', (_event, requestId) => {
+    if (typeof requestId !== 'string' || !requestId)
+        throw new Error('A command request id is required.');
+    const pending = mcpExecutions.listAll().find((item) => item.requestId === requestId);
+    const result = mcpExecutions.cancelFromUser(requestId);
+    if (pending && 'clientId' in pending)
+        mcpAudit.record({ at: Date.now(), requestId, clientId: pending.clientId, capability: 'session:execute', sessionId: pending.sessionId, state: 'cancelled', command: pending.displayCommand });
+    clearMcpExecution(requestId);
+    win?.webContents.send('mcp:execution', result);
+    return result;
+});
+ipcMain.handle('mcp:start', async () => {
+    mcpHost ??= new McpServerHost({
+        control: mcpControl,
+        providers: {
+            listWorkspaces: () => workspaceStore.load(),
+            listSessions: () => service.list(),
+            createWorkspace,
+            restoreWorkspace,
+            createSshSession: async (request) => {
+                const session = await service.createSsh(request.target, request.name);
+                const attached = service.attach(session.id, (data) => {
+                    const requestId = mcpActiveExecutions.get(session.id);
+                    if (requestId) {
+                        const output = `${mcpExecutionOutput.get(requestId) ?? ''}${data}`.slice(0, 16 * 1024);
+                        mcpExecutionOutput.set(requestId, output);
+                        if ((output.match(/ExitCode=\d+/g) ?? []).length >= 2) {
+                            const result = mcpExecutions.finishRunning(requestId, 'completed', output, false, 'Command completed.');
+                            clearMcpExecution(requestId, session.id);
+                            win?.webContents.send('mcp:execution', result);
+                        }
+                    }
+                    win?.webContents.send('terminal:data', session.id, data);
+                }, (message) => win?.webContents.send('terminal:status', session.id, message));
+                win?.webContents.send('mcp:ssh-session-created', { session: attached });
+                return attached;
+            },
+            createProjectWorkspace,
+            requestCommand: async (request) => {
+                const sessions = await service.list();
+                const session = sessions.find((item) => item.id === request.sessionId);
+                if (!session)
+                    throw new Error('Unknown session.');
+                const result = mcpExecutions.create({ clientId: request.clientId, sessionId: request.sessionId, sessionKind: session.kind, command: request.command, policy: { allowRemoteSessions: session.kind === 'ssh', ...(request.timeoutMs === undefined ? {} : { maxRuntimeMs: request.timeoutMs }), ...(request.outputBytes === undefined ? {} : { maxOutputBytes: request.outputBytes }) } });
+                const safeRemote = session.kind === 'ssh' && isSafeRemoteCommand(result.command);
+                if (safeRemote) {
+                    const approved = mcpExecutions.approveAutomatically(result.requestId);
+                    mcpAudit.record({ at: Date.now(), requestId: approved.requestId, clientId: approved.clientId, capability: 'session:execute', sessionId: approved.sessionId, state: 'approved', command: approved.displayCommand });
+                    await runMcpExecution(approved.requestId);
+                    return mcpExecutions.get(approved.requestId, request.clientId);
+                }
+                mcpAudit.record({ at: Date.now(), requestId: result.requestId, clientId: result.clientId, capability: 'session:execute', sessionId: result.sessionId, state: 'requested', command: result.displayCommand });
+                win?.webContents.send('mcp:execution', result);
+                return result;
+            },
+            getCommandResult: async (request) => mcpExecutions.get(request.requestId, request.clientId),
+            cancelCommand: async (request) => {
+                const current = mcpExecutions.get(request.requestId, request.clientId);
+                const result = mcpExecutions.cancel(request.requestId, request.clientId);
+                const session = 'sessionId' in current ? (await service.list()).find((item) => item.id === current.sessionId) : undefined;
+                if (session?.kind === 'local')
+                    service.write(session.id, '\u0003');
+                clearMcpExecution(request.requestId);
+                return result;
+            }
+        },
+        version: app.getVersion()
+    });
+    return mcpHost.start();
+});
+ipcMain.handle('mcp:stop', async () => { await mcpHost?.stop(); });
 ipcMain.handle('sessions:backends', () => discoverShellBackends());
 ipcMain.handle('sessions:wslDistributions', async () => {
     try {
@@ -280,7 +492,30 @@ ipcMain.handle('screens:attachRemote', (_event, input, screenName) => {
 ipcMain.handle('sessions:attach', (_event, id, size) => {
     if (typeof id !== 'string' || !id)
         throw new Error('attachSession requires a session id');
-    return service.attach(id, (data) => win?.webContents.send('terminal:data', id, data), (message) => win?.webContents.send('terminal:status', id, message), parsePtySize(size));
+    return service.attach(id, (data) => {
+        const requestId = mcpActiveExecutions.get(id);
+        if (requestId) {
+            const existing = mcpExecutionOutput.get(requestId) ?? '';
+            const next = `${existing}${data}`;
+            mcpExecutionOutput.set(requestId, next.slice(0, 16 * 1024));
+            if (next.length >= 16 * 1024) {
+                service.write(id, '\u0003');
+                const result = mcpExecutions.finishRunning(requestId, 'failed', next.slice(0, 16 * 1024), true, 'Execution stopped after reaching the output limit.');
+                clearMcpExecution(requestId, id);
+                win?.webContents.send('mcp:execution', result);
+                win?.webContents.send('terminal:status', id, 'MCP execution stopped: output limit reached.');
+                return;
+            }
+            const prompt = classifyMcpPrompt(data);
+            if (prompt.kind !== 'unknown') {
+                const result = mcpExecutions.cancelFromUser(requestId, `Execution paused for a ${prompt.kind} prompt; MCP cannot answer prompts.`);
+                clearMcpExecution(requestId, id);
+                win?.webContents.send('mcp:execution', result);
+                win?.webContents.send('terminal:status', id, `MCP execution paused: ${prompt.kind} prompt requires user input.`);
+            }
+        }
+        win?.webContents.send('terminal:data', id, data);
+    }, (message) => win?.webContents.send('terminal:status', id, message), parsePtySize(size));
 });
 ipcMain.handle('sessions:close', (_event, id) => {
     if (typeof id !== 'string' || !id)
@@ -469,6 +704,65 @@ app.whenReady().then(() => {
     Menu.setApplicationMenu(null);
     watchEventLoop();
     createWindow();
+    if (process.env.ZEROG_MCP_ENABLED === '1') {
+        mcpHost ??= new McpServerHost({
+            control: mcpControl,
+            providers: {
+                listWorkspaces: () => workspaceStore.load(),
+                listSessions: () => service.list(),
+                createWorkspace,
+                restoreWorkspace,
+                createSshSession: async (request) => {
+                    const session = await service.createSsh(request.target, request.name);
+                    const attached = service.attach(session.id, (data) => {
+                        const requestId = mcpActiveExecutions.get(session.id);
+                        if (requestId) {
+                            const output = `${mcpExecutionOutput.get(requestId) ?? ''}${data}`.slice(0, 16 * 1024);
+                            mcpExecutionOutput.set(requestId, output);
+                            if ((output.match(/ExitCode=\d+/g) ?? []).length >= 2) {
+                                const result = mcpExecutions.finishRunning(requestId, 'completed', output, false, 'Command completed.');
+                                clearMcpExecution(requestId, session.id);
+                                win?.webContents.send('mcp:execution', result);
+                            }
+                        }
+                        win?.webContents.send('terminal:data', session.id, data);
+                    }, (message) => win?.webContents.send('terminal:status', session.id, message));
+                    win?.webContents.send('mcp:ssh-session-created', { session: attached });
+                    return attached;
+                },
+                createProjectWorkspace,
+                requestCommand: async (request) => {
+                    const sessions = await service.list();
+                    const session = sessions.find((item) => item.id === request.sessionId);
+                    if (!session)
+                        throw new Error('Unknown session.');
+                    const result = mcpExecutions.create({ clientId: request.clientId, sessionId: request.sessionId, sessionKind: session.kind, command: request.command, policy: { allowRemoteSessions: session.kind === 'ssh', ...(request.timeoutMs === undefined ? {} : { maxRuntimeMs: request.timeoutMs }), ...(request.outputBytes === undefined ? {} : { maxOutputBytes: request.outputBytes }) } });
+                    const safeRemote = session.kind === 'ssh' && isSafeRemoteCommand(result.command);
+                    if (safeRemote) {
+                        const approved = mcpExecutions.approveAutomatically(result.requestId);
+                        mcpAudit.record({ at: Date.now(), requestId: approved.requestId, clientId: approved.clientId, capability: 'session:execute', sessionId: approved.sessionId, state: 'approved', command: approved.displayCommand });
+                        await runMcpExecution(approved.requestId);
+                        return mcpExecutions.get(approved.requestId, request.clientId);
+                    }
+                    mcpAudit.record({ at: Date.now(), requestId: result.requestId, clientId: result.clientId, capability: 'session:execute', sessionId: result.sessionId, state: 'requested', command: result.displayCommand });
+                    win?.webContents.send('mcp:execution', result);
+                    return result;
+                },
+                getCommandResult: async (request) => mcpExecutions.get(request.requestId, request.clientId),
+                cancelCommand: async (request) => {
+                    const current = mcpExecutions.get(request.requestId, request.clientId);
+                    const result = mcpExecutions.cancel(request.requestId, request.clientId);
+                    const session = 'sessionId' in current ? (await service.list()).find((item) => item.id === current.sessionId) : undefined;
+                    if (session?.kind === 'local')
+                        service.write(session.id, '\u0003');
+                    clearMcpExecution(request.requestId);
+                    return result;
+                }
+            },
+            version: app.getVersion()
+        });
+        void mcpHost.start();
+    }
     app.on('activate', () => {
         if (!BrowserWindow.getAllWindows().length)
             createWindow();

package/dist/main/main/mcp-audit.js

@@ -0,0 +1,12 @@
+import { createHash } from 'node:crypto';
+const MAX_EVENTS = 256;
+const MAX_COMMAND = 256;
+export class McpAudit {
+    events = [];
+    record(input) {
+        this.events.push({ ...input, client: createHash('sha256').update(input.clientId).digest('hex').slice(0, 16), command: input.command.slice(0, MAX_COMMAND) });
+        if (this.events.length > MAX_EVENTS)
+            this.events.splice(0, this.events.length - MAX_EVENTS);
+    }
+    list() { return this.events.map((event) => ({ ...event })); }
+}

package/dist/main/main/mcp-control.js

@@ -0,0 +1,95 @@
+import { requireMcpCapability } from './mcp-protocol.js';
+/**
+ * The single-client control lease. This class deliberately knows nothing about
+ * MCP or Electron so revocation and expiry can be tested without a running app.
+ */
+export class McpControl {
+    leaseMs;
+    now;
+    onChange;
+    lease;
+    state = { state: 'disabled', capabilities: [] };
+    constructor(options = {}) {
+        this.leaseMs = options.leaseMs ?? 5 * 60_000;
+        this.now = options.now ?? Date.now;
+        this.onChange = options.onChange;
+    }
+    status() {
+        this.expireIfNeeded();
+        return { ...this.state, capabilities: [...this.state.capabilities] };
+    }
+    enable(endpoint) {
+        this.state = { state: 'listening', endpoint, capabilities: [] };
+        this.emit();
+        return this.status();
+    }
+    disable() {
+        this.lease = undefined;
+        this.state = { state: 'disabled', capabilities: [] };
+        this.emit();
+    }
+    connect(clientId, clientName, capabilities) {
+        if (this.state.state === 'disabled')
+            throw new Error('MCP control is disabled in ZeroG settings.');
+        if (this.lease && this.lease.clientId !== clientId && this.isLeaseActive()) {
+            throw new Error('Another AI client already holds the ZeroG control lease.');
+        }
+        const unique = Array.from(new Set(capabilities));
+        this.lease = { clientId, ...(clientName ? { clientName } : {}), capabilities: unique, expiresAt: this.now() + this.leaseMs };
+        this.state = { ...this.state, state: 'connected', clientName, leaseExpiresAt: this.lease.expiresAt, capabilities: unique };
+        this.emit();
+        return { ...this.lease, capabilities: [...this.lease.capabilities] };
+    }
+    renew(clientId) {
+        this.requireClient(clientId);
+        const lease = this.lease;
+        lease.expiresAt = this.now() + this.leaseMs;
+        this.state = { ...this.state, leaseExpiresAt: lease.expiresAt };
+        this.emit();
+        return { ...lease, capabilities: [...lease.capabilities] };
+    }
+    upgrade(clientId, capabilities) {
+        this.requireClient(clientId);
+        const lease = this.lease;
+        const unique = Array.from(new Set([...lease.capabilities, ...capabilities]));
+        lease.capabilities = unique;
+        lease.expiresAt = this.now() + this.leaseMs;
+        this.state = { ...this.state, leaseExpiresAt: lease.expiresAt, capabilities: unique };
+        this.emit();
+        return { ...lease, capabilities: [...lease.capabilities] };
+    }
+    revoke(reason = 'AI control revoked by the user.') {
+        this.lease = undefined;
+        this.state = { ...this.state, state: 'revoked', leaseExpiresAt: undefined, capabilities: [] };
+        this.emit();
+        void reason;
+    }
+    require(clientId, capability) {
+        this.expireIfNeeded();
+        const lease = this.lease;
+        if (!lease || lease.clientId !== clientId)
+            throw new Error('This AI client does not hold the active control lease.');
+        requireMcpCapability(lease, capability, this.now());
+    }
+    requireClient(clientId) {
+        this.expireIfNeeded();
+        if (!this.lease || this.lease.clientId !== clientId)
+            throw new Error('This AI client does not hold the active control lease.');
+    }
+    isLeaseActive() {
+        return Boolean(this.lease && this.lease.expiresAt > this.now());
+    }
+    expireIfNeeded() {
+        if (this.lease && this.lease.expiresAt <= this.now()) {
+            this.lease = undefined;
+            this.state = { ...this.state, state: 'revoked', leaseExpiresAt: undefined, capabilities: [] };
+            this.emit();
+        }
+    }
+    emit() {
+        this.onChange?.(this.statusWithoutExpiry());
+    }
+    statusWithoutExpiry() {
+        return { ...this.state, capabilities: [...this.state.capabilities] };
+    }
+}

package/dist/main/main/mcp-execution-broker.js

@@ -0,0 +1,126 @@
+import { randomUUID } from 'node:crypto';
+import { validateMcpCommand } from './mcp-execution-policy.js';
+/** Approval state only. Execution remains owned by the main-process PTY layer. */
+export class McpExecutionBroker {
+    maxPending;
+    pending = new Map();
+    constructor(options = {}) {
+        this.maxPending = options.maxPending ?? 8;
+    }
+    create(input) {
+        const decision = validateMcpCommand(input);
+        if (!decision.allowed || !decision.command || !decision.displayCommand)
+            throw new Error(decision.reason ?? 'Command rejected.');
+        if (Array.from(this.pending.values()).some((item) => item.request.clientId === input.clientId && item.request.sessionId === input.sessionId && item.request.state === 'pending')) {
+            throw new Error('A command approval is already pending for this session.');
+        }
+        if (Array.from(this.pending.values()).filter((item) => item.request.state === 'pending').length >= this.maxPending)
+            throw new Error('Too many pending command approvals.');
+        const now = input.now ?? Date.now();
+        const request = {
+            requestId: randomUUID(), clientId: input.clientId, sessionId: input.sessionId,
+            command: decision.command, displayCommand: decision.displayCommand, state: 'pending',
+            createdAt: now, expiresAt: now + Math.min(input.approvalTtlMs ?? 60_000, 5 * 60_000), policy: decision.policy
+        };
+        this.pending.set(request.requestId, { request });
+        return { ...request, policy: { ...request.policy } };
+    }
+    get(requestId, clientId, now = Date.now()) {
+        const item = this.owned(requestId, clientId);
+        this.expire(item, now);
+        return item.result ? { ...item.result } : { ...item.request, policy: { ...item.request.policy } };
+    }
+    decide(requestId, clientId, decision, now = Date.now()) {
+        const item = this.owned(requestId, clientId);
+        this.expire(item, now);
+        if (item.request.state !== 'pending')
+            throw new Error('Command approval is no longer pending.');
+        item.request.state = decision === 'approve' ? 'approved' : 'rejected';
+        if (decision === 'reject')
+            this.finish(item, 'rejected', 'Rejected by the user.', now);
+        return { ...item.request, policy: { ...item.request.policy } };
+    }
+    decideFromUser(requestId, decision, now = Date.now()) {
+        const item = this.pending.get(requestId);
+        if (!item)
+            throw new Error('Unknown command request.');
+        this.expire(item, now);
+        if (item.request.state !== 'pending')
+            throw new Error('Command approval is no longer pending.');
+        item.request.state = decision === 'approve' ? 'approved' : 'rejected';
+        if (decision === 'reject')
+            this.finish(item, 'rejected', 'Rejected by the user.', now);
+        return { ...item.request, policy: { ...item.request.policy } };
+    }
+    approveAutomatically(requestId, now = Date.now()) {
+        const item = this.pending.get(requestId);
+        if (!item)
+            throw new Error('Unknown command request.');
+        this.expire(item, now);
+        if (item.request.state !== 'pending')
+            throw new Error('Command approval is no longer pending.');
+        item.request.state = 'approved';
+        return { ...item.request, policy: { ...item.request.policy } };
+    }
+    start(requestId, now = Date.now()) {
+        const item = this.pending.get(requestId);
+        if (!item)
+            throw new Error('Unknown command request.');
+        this.expire(item, now);
+        if (item.request.state !== 'approved')
+            throw new Error('Command must be approved before execution.');
+        item.request.state = 'running';
+        return { ...item.request, policy: { ...item.request.policy } };
+    }
+    finishRunning(requestId, state, output, truncated, message, now = Date.now()) {
+        const item = this.pending.get(requestId);
+        if (!item)
+            throw new Error('Unknown command request.');
+        if (item.request.state !== 'running')
+            throw new Error('Command is not running.');
+        this.finish(item, state, message, now, output, truncated);
+        return item.result;
+    }
+    cancel(requestId, clientId, message = 'Cancelled by the user.', now = Date.now()) {
+        const item = this.owned(requestId, clientId);
+        this.finish(item, 'cancelled', message, now);
+        return item.result;
+    }
+    cancelFromUser(requestId, message = 'Cancelled by the user.', now = Date.now()) {
+        const item = this.pending.get(requestId);
+        if (!item)
+            throw new Error('Unknown command request.');
+        this.finish(item, 'cancelled', message, now);
+        return item.result;
+    }
+    revoke(clientId, now = Date.now()) {
+        for (const item of Array.from(this.pending.values()))
+            if (item.request.clientId === clientId && !item.result)
+                this.finish(item, 'cancelled', 'AI control was revoked.', now);
+    }
+    revokeAll(now = Date.now()) {
+        for (const item of Array.from(this.pending.values()))
+            if (!item.result)
+                this.finish(item, 'cancelled', 'AI control was revoked.', now);
+    }
+    list(clientId, now = Date.now()) {
+        return Array.from(this.pending.values()).filter((item) => item.request.clientId === clientId).map((item) => this.get(item.request.requestId, clientId, now));
+    }
+    listAll(now = Date.now()) {
+        return Array.from(this.pending.values()).map((item) => { this.expire(item, now); return item.result ? { ...item.result } : { ...item.request, policy: { ...item.request.policy } }; });
+    }
+    owned(requestId, clientId) {
+        const item = this.pending.get(requestId);
+        if (!item || item.request.clientId !== clientId)
+            throw new Error('Unknown command request.');
+        return item;
+    }
+    expire(item, now) {
+        if (!item.result && item.request.state === 'pending' && item.request.expiresAt <= now)
+            this.finish(item, 'timed-out', 'Approval expired.', now);
+    }
+    finish(item, state, message, now, output, truncated = false) {
+        item.request.state = state;
+        item.result = { requestId: item.request.requestId, state, ...(output ? { output } : {}), ...(truncated ? { truncated: true } : {}), message, completedAt: now };
+    }
+}

package/dist/main/main/mcp-execution-policy.js

@@ -0,0 +1,43 @@
+export const DEFAULT_MCP_EXECUTION_POLICY = {
+    allowShellOperators: false,
+    allowRemoteSessions: false,
+    maxCommandLength: 512,
+    maxRuntimeMs: 30_000,
+    maxOutputBytes: 16 * 1024
+};
+const CONTROL = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/;
+const SHELL_OPERATORS = /[|;&<>`$(){}\\]/;
+const CREDENTIAL_SHAPE = /(?:bearer\s+|password\s*=|token\s*=|api[_-]?key\s*=|-----begin\s+[^\r\n]+-----)/i;
+const SAFE_REMOTE_COMMANDS = /^(?:pwd|cd(?:\s+\.?\/?[A-Za-z0-9_./~-]+)?|whoami|hostname|uname(?:\s+-a)?|ls(?:\s+(?:-[al]{1,2}|\.?\/?[A-Za-z0-9_./~-]+))?|df(?:\s+-h)?(?:\s+\.?\/?[A-Za-z0-9_./~-]+)?)$/;
+export function validateMcpCommand(input) {
+    const policy = { ...DEFAULT_MCP_EXECUTION_POLICY, ...(input.policy ?? {}) };
+    if (typeof input.command !== 'string')
+        return denied(policy, 'Command must be text.');
+    const command = input.command.trim();
+    if (!command)
+        return denied(policy, 'Command is required.');
+    if (command.length > policy.maxCommandLength)
+        return denied(policy, 'Command is too long.');
+    if (/[\r\n]/.test(command))
+        return denied(policy, 'Only one command line may be requested.');
+    if (CONTROL.test(command))
+        return denied(policy, 'Command contains control characters.');
+    if (CREDENTIAL_SHAPE.test(command))
+        return denied(policy, 'Credential-like command content is disabled.');
+    if (!policy.allowShellOperators && SHELL_OPERATORS.test(command))
+        return denied(policy, 'Shell operators are disabled.');
+    if (input.sessionKind === 'ssh' && !policy.allowRemoteSessions)
+        return denied(policy, 'Remote command execution is disabled.');
+    return { allowed: true, command, displayCommand: redactCommand(command), policy };
+}
+export function isSafeRemoteCommand(command) {
+    return SAFE_REMOTE_COMMANDS.test(command.trim());
+}
+function redactCommand(command) {
+    if (CREDENTIAL_SHAPE.test(command))
+        return '[redacted command: credential-like content]';
+    return command;
+}
+function denied(policy, reason) {
+    return { allowed: false, reason, policy };
+}