zerogterm 0.9.0-alpha.1 → 0.9.2-alpha.1

package/dist/main/main/main.js

@@ -10,8 +10,10 @@ import { CommandHistoryStore, defaultCommandHistoryPath } from './command-histor
 import { WorkspaceStore, defaultWorkspacePath } from './workspace-store.js';
 import { PortForwardService } from './port-forward-service.js';
 import { PortForwardStore, defaultPortForwardPath } from './port-forward-store.js';
+import { readRemoteFile, writeRemoteFile } from './remote-file.js';
+import { HostLabelStore, defaultHostLabelPath } from './host-label-store.js';
 import { buildRemoteScreenAttachArgs, buildRemoteScreenDiscoveryArgs, listKnownConnections, parseRemoteScreenList, validateKnownConnection } from './ssh-inventory.js';
-import { createLocalDirectory, listLocalDirectory, localHome, removeLocalEntry, renameLocalEntry } from './local-fs.js';
+import { createLocalDirectory, listLocalDirectory, localHome, readLocalFile, removeLocalEntry, renameLocalEntry, writeLocalFile } from './local-fs.js';
 import { wslHomeDirectory } from './wsl-home.js';
 import { decideExternalLink, isApplicationUrl } from './external-links.js';
 import { SftpService } from './sftp-service.js';
@@ -24,6 +26,8 @@ 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';
+import { PaneLinkController, pasteAndSubmit } from './pane-link.js';
+import { AgentHookServer, buildLaunchCommand } from './agent-hook-server.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
@@ -32,6 +36,7 @@ const history = new SessionHistoryStore({ filePath: defaultHistoryPath(app.getPa
 const commands = new CommandHistoryStore({ filePath: defaultCommandHistoryPath(app.getPath('userData')) });
 const workspaceStore = new WorkspaceStore({ filePath: defaultWorkspacePath(app.getPath('userData')) });
 const forwardStore = new PortForwardStore({ filePath: defaultPortForwardPath(app.getPath('userData')) });
+const hostLabelStore = new HostLabelStore({ filePath: defaultHostLabelPath(app.getPath('userData')) });
 // Tunnels outlive the Ports view being closed: authenticating again is a real
 // cost to pay for having looked away.
 const forwards = new PortForwardService({ onEvent: (event) => win?.webContents.send('forwards:event', event) });
@@ -67,6 +72,46 @@ function clearMcpExecution(requestId, sessionId) {
     }
 }
 let mcpHost;
+// Pane link: agents ZeroG launches report their turns over loopback hooks, and the
+// controller relays a finished reply into the linked pane. See src/main/pane-link.ts.
+const paneLinks = new PaneLinkController({
+    deliver: (sessionId, text) => pasteAndSubmit((id, data) => service.write(id, data), sessionId, text),
+    onChange: (snapshot) => win?.webContents.send('paneLinks:changed', snapshot)
+});
+const agentHooks = new AgentHookServer({
+    settingsDir: join(app.getPath('userData'), 'pane-link'),
+    onEvent: (event) => paneLinks.handle(event)
+});
+ipcMain.handle('paneLinks:launchAgent', async (_event, sessionId, agentCommand) => {
+    const id = requireString(sessionId, 'A pane');
+    const command = requireString(agentCommand, 'The AI command');
+    const info = (await service.list()).find((candidate) => candidate.id === id);
+    if (!info)
+        throw new Error('That pane is not available.');
+    // The hook URL is a Windows/Linux loopback address. An SSH host or a WSL2 guest cannot reach it.
+    if (info.kind !== 'local' || info.backend === 'wsl') {
+        throw new Error('Linked agents run in local panes only (not SSH or WSL).');
+    }
+    const { settingsPath } = await agentHooks.register(id);
+    try {
+        const line = buildLaunchCommand(command, settingsPath);
+        paneLinks.registerAgent(id, info.name);
+        // One leading space: a freshly opened shell was seen to swallow the first
+        // keystroke ("laude: command not found"). If it is the space that goes, the
+        // command is intact; if nothing goes, a leading space is harmless in bash,
+        // PowerShell and cmd.
+        service.write(id, ` ${line}\r`);
+    }
+    catch (error) {
+        await agentHooks.unregister(id);
+        throw error;
+    }
+});
+ipcMain.handle('paneLinks:list', () => paneLinks.snapshot());
+ipcMain.handle('paneLinks:link', (_event, a, b, cap) => paneLinks.link(requireString(a, 'A pane'), requireString(b, 'A pane'), typeof cap === 'number' ? cap : undefined));
+ipcMain.handle('paneLinks:relayLast', (_event, linkId, from) => paneLinks.relayLast(requireString(linkId, 'A link'), requireString(from, 'A pane')));
+ipcMain.handle('paneLinks:unlink', (_event, linkId) => paneLinks.unlink(requireString(linkId, 'A link')));
+ipcMain.handle('paneLinks:resume', (_event, linkId) => paneLinks.resume(requireString(linkId, 'A link')));
 async function restoreWorkspace(workspaceId) {
     const file = await workspaceStore.load();
     const workspace = file.workspaces.find((item) => item.id === workspaceId);
@@ -319,6 +364,8 @@ ipcMain.handle('forwards:close', (_event, id) => forwards.close(requireString(id
 ipcMain.handle('forwards:answerPrompt', (_event, id, answer) => forwards.answerPrompt(requireString(id, 'A shared port'), requireString(answer, 'An answer')));
 ipcMain.handle('forwards:load', () => forwardStore.load());
 ipcMain.handle('forwards:save', (_event, file) => forwardStore.save(file));
+ipcMain.handle('hostLabels:load', () => hostLabelStore.load());
+ipcMain.handle('hostLabels:save', (_event, file) => hostLabelStore.save(file));
 ipcMain.handle('workspaces:load', () => workspaceStore.load());
 ipcMain.handle('workspaces:save', (_event, file) => workspaceStore.save(file));
 ipcMain.handle('mcp:status', () => mcpControl.status());
@@ -381,61 +428,64 @@ ipcMain.handle('mcp:execution:cancel', (_event, 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);
-                        }
+function createMcpProviders() {
+    return {
+        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;
+                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;
+        }
+    };
+}
+ipcMain.handle('mcp:start', async () => {
+    mcpHost ??= new McpServerHost({
+        control: mcpControl,
+        providers: createMcpProviders(),
         version: app.getVersion()
     });
     return mcpHost.start();
@@ -521,6 +571,8 @@ ipcMain.handle('sessions:close', (_event, id) => {
     if (typeof id !== 'string' || !id)
         throw new Error('closeSession requires a session id');
     service.close(id);
+    paneLinks.unregisterAgent(id);
+    void agentHooks.unregister(id);
 });
 ipcMain.on('terminal:write', (_event, sessionId, data) => {
     if (typeof sessionId === 'string' && typeof data === 'string')
@@ -644,6 +696,14 @@ ipcMain.handle('fs:wslHome', async (_event, distribution) => {
 ipcMain.handle('fs:listLocal', (_event, path) => listLocalDirectory(typeof path === 'string' && path ? path : undefined));
 ipcMain.handle('fs:mkdirLocal', (_event, path) => createLocalDirectory(requireString(path, 'A folder path')));
 ipcMain.handle('fs:renameLocal', (_event, from, to) => renameLocalEntry(requireString(from, 'The current path'), requireString(to, 'The new path')));
+ipcMain.handle('fs:readLocalFile', (_event, path) => readLocalFile(requireString(path, 'A file path')));
+ipcMain.handle('fs:writeLocalFile', (_event, path, text, expectedMtimeMs, overwrite) => {
+    if (typeof text !== 'string')
+        throw new Error('There is no text to save.');
+    if (typeof expectedMtimeMs !== 'number' || !Number.isFinite(expectedMtimeMs))
+        throw new Error('When the file was opened is required.');
+    return writeLocalFile(requireString(path, 'A file path'), text, expectedMtimeMs, overwrite === true);
+});
 ipcMain.handle('fs:removeLocal', (_event, path, kind) => removeLocalEntry(requireString(path, 'A path'), requireEntryKind(kind)));
 ipcMain.handle('sftp:open', (_event, target, cwd) => sftp.open(requireString(target, 'An SSH target'), typeof cwd === 'string' && cwd ? cwd : undefined));
 ipcMain.handle('sftp:list', (_event, id, path) => sftp.list(requireString(id, 'A transfer connection'), typeof path === 'string' && path ? path : undefined));
@@ -659,6 +719,12 @@ ipcMain.handle('sftp:answerPrompt', (_event, id, answer) => {
         throw new Error('An answer is required.');
     sftp.answerPrompt(requireString(id, 'A transfer connection'), answer);
 });
+ipcMain.handle('sftp:readFile', (_event, id, path) => readRemoteFile(sftp, requireString(id, 'A transfer connection'), requireString(path, 'A remote file')));
+ipcMain.handle('sftp:writeFile', (_event, id, path, text, opened, overwrite) => {
+    if (typeof text !== 'string' || typeof opened !== 'string')
+        throw new Error('There is no text to save.');
+    return writeRemoteFile(sftp, requireString(id, 'A transfer connection'), requireString(path, 'A remote file'), text, opened, overwrite === true);
+});
 ipcMain.handle('sftp:close', (_event, id) => sftp.close(requireString(id, 'A transfer connection')));
 // The key is read here, per request, and never handed to the renderer.
 const ai = new AiService({ readApiKey: () => secrets.get(AI_API_KEY) });
@@ -707,58 +773,7 @@ app.whenReady().then(() => {
     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;
-                }
-            },
+            providers: createMcpProviders(),
             version: app.getVersion()
         });
         void mcpHost.start();
@@ -768,6 +783,9 @@ app.whenReady().then(() => {
             createWindow();
     });
 });
+app.on('before-quit', () => {
+    void agentHooks.stop();
+});
 app.on('window-all-closed', () => {
     if (process.platform !== 'darwin')
         app.quit();

package/dist/main/main/pane-link.js

@@ -0,0 +1,335 @@
+// Pane link: relay one agent's finished reply into another agent's prompt.
+//
+// This module is the decision logic only. It owns no sockets and no PTYs: the hook
+// server feeds it what the agents report (a prompt was submitted, a turn finished, the
+// agent needs attention, the session ended) and it answers by asking for text to be
+// delivered to a session. Keeping it that small is what lets every safety rule below be
+// exercised in a unit test with a fake clock.
+//
+// Why hook events and not terminal output: a throwaway prototype that guessed turn ends
+// from a quiet timer and scraped the reply off the screen declared turns finished while
+// the agent was still thinking and forwarded spinner glyphs and echoed prompts. The Stop
+// hook reports the turn end exactly and carries the final message verbatim.
+//
+// Safety rules enforced here (CONTEXT.md: no autonomous agent loops without an explicit
+// design):
+//  - A link exists only because the user asked for it, between two agents ZeroG itself
+//    launched, and it ends on the user's say-so, on the turn cap, or when either agent exits.
+//  - Text is only delivered to an agent that is idle. If the partner is busy the link
+//    pauses and holds the message; it never types into a running turn.
+//  - Relayed text is untrusted input to the receiving agent. It is stripped of control
+//    characters (an ESC would let a reply close the bracketed paste early and have the rest
+//    typed as keystrokes), size-capped, and labelled as coming from another agent.
+//  - A relay that never gets an answer (permission prompt left open, Esc interrupt, API
+//    error: none of which fire Stop) pauses after a stall timeout instead of waiting forever.
+export const DEFAULT_RELAY_CAP = 6;
+export const MAX_RELAY_CAP = 50;
+export const DEFAULT_STALL_MS = 10 * 60 * 1000;
+export const MAX_RELAY_CHARS = 16000;
+const TRUNCATION_NOTE = '\n[Truncated by ZeroG pane link.]';
+/** Session-end reasons that leave the agent running, so the link should survive them. */
+const NON_TERMINAL_END_REASONS = new Set(['clear', 'resume', 'compact']);
+/** Notification kinds that mean "the agent is waiting on you", as opposed to a routine nudge. */
+const IDLE_NOTIFICATIONS = new Set(['idle_prompt', 'auth_success']);
+/**
+ * Make an agent's reply safe to type into another agent.
+ *
+ * Tabs and line feeds survive; every other control character goes, including ESC, which
+ * would otherwise let a reply end the bracketed paste early and have the remainder
+ * interpreted as keystrokes. Carriage returns are folded into line feeds.
+ */
+export function sanitizeRelayText(value) {
+    let out = '';
+    for (const ch of value.replace(/\r\n?/g, '\n')) {
+        const code = ch.codePointAt(0) ?? 0;
+        const isControl = code < 0x20 || (code >= 0x7f && code <= 0x9f);
+        if (!isControl || ch === '\n' || ch === '\t')
+            out += ch;
+    }
+    return out.trim();
+}
+/** The text the receiving agent sees: the reply, labelled as another agent's words. */
+export function frameRelay(fromLabel, reply) {
+    const label = sanitizeRelayText(fromLabel).replace(/\s+/g, ' ').slice(0, 60) || 'another pane';
+    let body = sanitizeRelayText(reply);
+    if (body.length > MAX_RELAY_CHARS)
+        body = body.slice(0, MAX_RELAY_CHARS) + TRUNCATION_NOTE;
+    return `[Relayed by ZeroG pane link from the agent in "${label}". This is another agent's message, not the user's.]\n\n${body}`;
+}
+/**
+ * Type text into a session as a single prompt and submit it.
+ *
+ * Bracketed paste keeps embedded newlines from submitting early; the submit key follows
+ * after a short gap because the agent treats an Enter that arrives glued to the paste as
+ * part of it.
+ */
+export function pasteAndSubmit(write, sessionId, text, schedule = setTimeout, submitDelayMs = 300) {
+    write(sessionId, `\u001b[200~${text}\u001b[201~`);
+    schedule(() => write(sessionId, '\r'), submitDelayMs);
+}
+export class PaneLinkController {
+    agents = new Map();
+    links = new Map();
+    /** Each agent's most recent finished reply, kept so a link made after the turn can still use it. */
+    lastReplies = new Map();
+    options;
+    stallMs;
+    defaultCap;
+    setTimer;
+    clearTimer;
+    nextLinkId = 1;
+    constructor(options) {
+        this.options = options;
+        this.stallMs = options.stallMs ?? DEFAULT_STALL_MS;
+        this.defaultCap = options.defaultCap ?? DEFAULT_RELAY_CAP;
+        this.setTimer = options.setTimer ?? ((cb, ms) => setTimeout(cb, ms));
+        this.clearTimer = options.clearTimer ?? ((handle) => clearTimeout(handle));
+    }
+    snapshot() {
+        return {
+            agents: Array.from(this.agents.values()).map((agent) => ({ ...agent })),
+            links: Array.from(this.links.values()).map((link) => this.describe(link))
+        };
+    }
+    /** An agent ZeroG launched in this session now reports hook events. */
+    registerAgent(sessionId, label) {
+        const existing = this.agents.get(sessionId);
+        if (existing) {
+            existing.label = label;
+        }
+        else {
+            this.agents.set(sessionId, { sessionId, label, phase: 'idle', needsAttention: false, hasReply: false });
+        }
+        this.emit();
+    }
+    /** The session is gone (pane closed, agent unregistered): end its link and forget it. */
+    unregisterAgent(sessionId) {
+        const agent = this.agents.get(sessionId);
+        if (!agent)
+            return;
+        if (agent.linkId)
+            this.breakLink(agent.linkId, `The agent in "${agent.label}" exited.`);
+        this.agents.delete(sessionId);
+        this.lastReplies.delete(sessionId);
+        this.emit();
+    }
+    /** Link two idle agents. Throws a user-readable message when the link is not allowed. */
+    link(aSessionId, bSessionId, cap) {
+        if (aSessionId === bSessionId)
+            throw new Error('Choose two different panes to link.');
+        const a = this.agents.get(aSessionId);
+        const b = this.agents.get(bSessionId);
+        if (!a || !b)
+            throw new Error('Both panes must be running an agent started with "Start linked agent".');
+        if (a.linkId || b.linkId)
+            throw new Error('A pane can only be in one link at a time. Break the existing link first.');
+        if (a.phase !== 'idle' || b.phase !== 'idle')
+            throw new Error('Wait for both agents to finish their current turn before linking.');
+        // A broken link stays listed so its reason can be read; starting a new one retires it.
+        for (const stale of Array.from(this.links.values())) {
+            if (stale.status === 'broken' && [stale.a, stale.b].some((id) => id === aSessionId || id === bSessionId))
+                this.links.delete(stale.id);
+        }
+        const relays = cap ?? this.defaultCap;
+        if (!Number.isInteger(relays) || relays < 1 || relays > MAX_RELAY_CAP) {
+            throw new Error(`The relay limit must be a whole number from 1 to ${MAX_RELAY_CAP}.`);
+        }
+        const link = { id: `link-${this.nextLinkId++}`, a: aSessionId, b: bSessionId, status: 'active', turns: 0, cap: relays };
+        this.links.set(link.id, link);
+        a.linkId = link.id;
+        b.linkId = link.id;
+        this.emit();
+        return this.describe(link);
+    }
+    /** The user breaks the link. Removes it entirely. */
+    unlink(linkId) {
+        const link = this.links.get(linkId);
+        if (!link)
+            return;
+        this.dropLink(link);
+        this.emit();
+    }
+    /** Re-arm a paused link, delivering the held reply if there is one and the partner is ready. */
+    resume(linkId) {
+        const link = this.links.get(linkId);
+        if (!link)
+            throw new Error('That link no longer exists.');
+        if (link.status !== 'paused')
+            return this.describe(link);
+        const held = link.held;
+        link.status = 'active';
+        link.reason = undefined;
+        link.waitingOn = undefined;
+        if (held) {
+            link.held = undefined;
+            this.relay(link, held.from, held.text);
+        }
+        this.emit();
+        return this.describe(link);
+    }
+    /**
+     * Relay an agent's most recent reply now. For a link made after the agent's turn
+     * finished (nothing else would ever trigger it) and for resuming by hand.
+     */
+    relayLast(linkId, fromSessionId) {
+        const link = this.links.get(linkId);
+        if (!link)
+            throw new Error('That link no longer exists.');
+        if (link.status === 'broken')
+            throw new Error('That link has ended. Link the panes again first.');
+        if (fromSessionId !== link.a && fromSessionId !== link.b)
+            throw new Error('That pane is not part of this link.');
+        const reply = this.lastReplies.get(fromSessionId);
+        if (!reply)
+            throw new Error('That agent has not finished a reply yet.');
+        if (link.waitingOn)
+            throw new Error('Wait for the agent that is already working on a relayed message.');
+        link.status = 'active';
+        link.reason = undefined;
+        link.held = undefined;
+        this.relay(link, fromSessionId, reply);
+        this.emit();
+        return this.describe(link);
+    }
+    /** Feed an event reported by an agent's hooks. */
+    handle(event) {
+        const agent = this.agents.get(event.sessionId);
+        if (!agent)
+            return;
+        const link = agent.linkId ? this.links.get(agent.linkId) : undefined;
+        switch (event.event) {
+            case 'UserPromptSubmit':
+                agent.phase = 'busy';
+                agent.needsAttention = false;
+                break;
+            case 'Notification':
+                if (!IDLE_NOTIFICATIONS.has(event.notificationType ?? ''))
+                    agent.needsAttention = true;
+                break;
+            case 'SessionEnd':
+                if (NON_TERMINAL_END_REASONS.has(event.reason ?? ''))
+                    break;
+                if (link)
+                    this.breakLink(link.id, `The agent in "${agent.label}" exited.`);
+                this.agents.delete(agent.sessionId);
+                break;
+            case 'Stop':
+                agent.phase = 'idle';
+                agent.needsAttention = false;
+                if (sanitizeRelayText(event.message ?? '')) {
+                    this.lastReplies.set(agent.sessionId, event.message ?? '');
+                    agent.hasReply = true;
+                }
+                if (link)
+                    this.onTurnFinished(link, agent, event.message ?? '');
+                break;
+        }
+        this.emit();
+    }
+    onTurnFinished(link, agent, message) {
+        if (link.status !== 'active')
+            return;
+        // We are waiting on the other agent, so this turn is not one we should relay (the user
+        // is driving this pane by hand). The expected answer will still arrive from the other side.
+        if (link.waitingOn && link.waitingOn !== agent.sessionId)
+            return;
+        this.cancelStall(link);
+        link.waitingOn = undefined;
+        if (!sanitizeRelayText(message)) {
+            this.pause(link, `The agent in "${agent.label}" finished without a reply to relay.`);
+            return;
+        }
+        if (link.turns >= link.cap) {
+            this.breakLink(link.id, `Reached the limit of ${link.cap} relays.`);
+            return;
+        }
+        this.relay(link, agent.sessionId, message);
+    }
+    relay(link, fromSessionId, message) {
+        const from = this.agents.get(fromSessionId);
+        const toSessionId = link.a === fromSessionId ? link.b : link.a;
+        const to = this.agents.get(toSessionId);
+        if (!from || !to) {
+            this.breakLink(link.id, 'One of the linked agents is gone.');
+            return;
+        }
+        if (link.turns >= link.cap) {
+            this.breakLink(link.id, `Reached the limit of ${link.cap} relays.`);
+            return;
+        }
+        if (to.phase !== 'idle' || to.needsAttention) {
+            link.held = { from: fromSessionId, text: message };
+            this.pause(link, to.needsAttention
+                ? `The agent in "${to.label}" is waiting for you. Answer it, then resume.`
+                : `The agent in "${to.label}" is busy. Resume once it finishes.`);
+            return;
+        }
+        to.phase = 'busy';
+        link.turns += 1;
+        link.waitingOn = toSessionId;
+        this.options.deliver(toSessionId, frameRelay(from.label, message));
+        this.armStall(link, to.label);
+    }
+    pause(link, reason) {
+        this.cancelStall(link);
+        link.status = 'paused';
+        link.reason = reason;
+    }
+    breakLink(linkId, reason) {
+        const link = this.links.get(linkId);
+        if (!link)
+            return;
+        this.cancelStall(link);
+        link.status = 'broken';
+        link.reason = reason;
+        link.waitingOn = undefined;
+        link.held = undefined;
+        for (const sessionId of [link.a, link.b]) {
+            const agent = this.agents.get(sessionId);
+            if (agent?.linkId === link.id)
+                agent.linkId = undefined;
+        }
+        // A broken link stays listed so the user can read why it ended; it no longer holds either pane.
+    }
+    dropLink(link) {
+        this.cancelStall(link);
+        for (const sessionId of [link.a, link.b]) {
+            const agent = this.agents.get(sessionId);
+            if (agent?.linkId === link.id)
+                agent.linkId = undefined;
+        }
+        this.links.delete(link.id);
+    }
+    armStall(link, waitingLabel) {
+        this.cancelStall(link);
+        link.stallTimer = this.setTimer(() => {
+            link.stallTimer = undefined;
+            if (link.status !== 'active')
+                return;
+            this.pause(link, `No reply from "${waitingLabel}". It may be waiting for approval or was interrupted.`);
+            this.emit();
+        }, this.stallMs);
+    }
+    cancelStall(link) {
+        if (link.stallTimer !== undefined) {
+            this.clearTimer(link.stallTimer);
+            link.stallTimer = undefined;
+        }
+    }
+    describe(link) {
+        return {
+            id: link.id,
+            a: link.a,
+            b: link.b,
+            status: link.status,
+            turns: link.turns,
+            cap: link.cap,
+            reason: link.reason,
+            waitingOn: link.waitingOn,
+            holding: link.held !== undefined
+        };
+    }
+    emit() {
+        this.options.onChange?.(this.snapshot());
+    }
+}