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

package/README.md

@@ -38,9 +38,9 @@ See the project walkthrough on [YouTube](https://youtu.be/4aJZCxLHD14).
 
 ## Release status
 
-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.
+ZeroG Terminal is currently a public alpha. The current release is `0.9.2-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.
+The GitHub Releases page provides a Windows x64 installer and portable executable plus a Linux x64 AppImage and Debian package 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.
 
 ## Terminal shortcuts
 
@@ -396,6 +396,59 @@ npm install --global zerogterm
 zerogterm
 ```
 
+## Connecting an AI agent through MCP
+
+ZeroG Terminal can expose the running desktop instance as a local MCP server. This
+lets an MCP-capable AI agent inspect workspaces and sessions, restore or create
+project workspaces, open SSH sessions, and request commands for your approval.
+
+1. Start ZeroG Terminal with MCP enabled:
+
+   ```bash
+   ZEROG_MCP_ENABLED=1 npx zerogterm
+   ```
+
+   On Windows PowerShell, use:
+
+   ```powershell
+   $env:ZEROG_MCP_ENABLED = "1"
+   npx zerogterm
+   ```
+
+2. Open **Settings → AI & voice → MCP** in ZeroG Terminal. Copy the displayed
+   endpoint and bearer token into your MCP client. The default endpoint is
+   `http://127.0.0.1:60056/mcp`.
+
+   MCP clients that support Streamable HTTP generally need the equivalent of:
+
+   ```json
+   {
+     "url": "http://127.0.0.1:60056/mcp",
+     "headers": {
+       "Authorization": "Bearer <token-from-zero-g-settings>"
+     }
+   }
+   ```
+
+   The exact configuration key differs between clients; use its Streamable HTTP
+   or remote MCP server setting rather than a stdio command. The token belongs to
+   the current ZeroG process, is held only in memory, and must be copied again
+   after ZeroG restarts. Never put it in source control, prompts, issue reports,
+   or shared configuration.
+
+3. Ask the agent to call `zerog_get_connection_status`, then
+   `zerog_acquire_control` with a client ID and the capabilities it needs. Read
+   capabilities require no write access; workspace changes and command requests
+   require the corresponding lease capabilities. The lease is single-client and
+   expires unless renewed.
+
+Every command request is shown in ZeroG Terminal for exact user approval before
+anything is written to a shell. Rejection, cancellation, takeover, credential
+prompts, uncertain prompts, and unsupported command shapes fail closed. MCP does
+not receive terminal output, credentials, or keystroke-level control. See the
+[full MCP protocol and security guide](docs/mcp.md) for tools, limits, and
+troubleshooting.
+
 ## Development
 
 ```bash
@@ -414,12 +467,21 @@ required whichever shell you start them from.
 for Windows and macOS, so a C/C++ toolchain is a Linux requirement rather than a
 general one — there, `npm install` compiles it.
 
-### Windows desktop release
+### Desktop releases
+
+Download the latest release for your platform from [GitHub Releases](https://github.com/HappyMonkeyAI/ZeroGTerm/releases). These alpha builds are intended for early adopters and testing rather than production use. Review the release notes before installing; SSH, WSL, PowerShell, Git Bash, and any remote `screen` sessions are provided by the host system rather than bundled with the app.
+
+#### Windows
+
+The Windows x64 installer adds ZeroG Terminal to the current user's applications. The portable `.exe` can be run without installation.
+
+These binaries are unsigned, so Windows SmartScreen may show a warning on first launch. If you downloaded the release from the official repository, choose **More info → Run anyway**.
+
+#### Linux
 
-Download the latest Windows x64 installer from [GitHub Releases](https://github.com/HappyMonkeyAI/ZeroGTerm/releases). The installer adds ZeroG Terminal to the current user's applications. The portable `.exe` can be run without installation.
+The Linux release provides an x64 AppImage and Debian package built for Ubuntu 22.04 or newer. Make the AppImage executable after downloading it, then launch it from the same directory. If the AppImage reports that FUSE2 is unavailable, install `libfuse2` on Ubuntu 22.04 or `libfuse2t64` on Ubuntu 24.04 and newer. The `.deb` package can be installed through Ubuntu's software tools or APT and does not require FUSE2.
 
-These binaries are unsigned alpha builds, so Windows SmartScreen may show a warning on first launch. If you downloaded the release from the official repository, choose **More info → Run anyway**. Review the release notes before installing; SSH, WSL, PowerShell, Git Bash, and any remote `screen` sessions are provided by the host system rather than bundled with the app.
-### Linux
+The host still needs a C/C++ toolchain when developing from source:
 
 ```bash
 sudo dnf install screen make gcc-c++ python3

package/dist/main/main/agent-hook-server.js

@@ -0,0 +1,166 @@
+// Loopback listener for the hooks of agents that ZeroG launched itself.
+//
+// Each launched agent gets its own settings file (passed with --settings, so no user or
+// project settings are edited) pointing four hook events at a URL that carries a random
+// per-agent token. The token is the only credential: the listener binds to 127.0.0.1
+// only, and a request for an unknown token is a 404 that reveals nothing. The token also
+// identifies the session, so a hook cannot claim to be a different pane.
+//
+// The hook response is an empty JSON object: ZeroG observes the agent, it never steers it
+// (no blocking, no injected context).
+import { createServer } from 'node:http';
+import { randomBytes } from 'node:crypto';
+import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+export const HOOK_EVENTS = ['UserPromptSubmit', 'Stop', 'Notification', 'SessionEnd'];
+/** A Stop payload carries the whole final message, so allow generously but not without bound. */
+const MAX_BODY_BYTES = 2 * 1024 * 1024;
+/** Settings JSON that points each observed hook event at `url`. Exported for tests. */
+export function buildHookSettings(url) {
+    const hooks = {};
+    for (const event of HOOK_EVENTS)
+        hooks[event] = [{ hooks: [{ type: 'http', url }] }];
+    return { hooks };
+}
+/** Turn a raw hook payload into the small event the controller understands, or undefined to ignore it. */
+export function parseHookPayload(sessionId, payload) {
+    if (typeof payload !== 'object' || payload === null)
+        return undefined;
+    const record = payload;
+    const name = record.hook_event_name;
+    if (typeof name !== 'string' || !HOOK_EVENTS.includes(name))
+        return undefined;
+    const text = (key) => (typeof record[key] === 'string' ? record[key] : undefined);
+    return {
+        sessionId,
+        event: name,
+        message: text('last_assistant_message'),
+        notificationType: text('notification_type'),
+        reason: text('reason')
+    };
+}
+export class AgentHookServer {
+    options;
+    byToken = new Map();
+    bySession = new Map();
+    http;
+    port = 0;
+    constructor(options) {
+        this.options = options;
+    }
+    /** Start listening on an ephemeral loopback port. Safe to call twice. */
+    async start() {
+        if (this.http)
+            return;
+        const server = createServer((req, res) => this.handle(req, res));
+        await new Promise((resolve, reject) => {
+            server.once('error', reject);
+            server.listen(0, '127.0.0.1', () => {
+                server.off('error', reject);
+                resolve();
+            });
+        });
+        const address = server.address();
+        this.port = typeof address === 'object' && address ? address.port : 0;
+        this.http = server;
+    }
+    async stop() {
+        const server = this.http;
+        this.http = undefined;
+        const sessions = Array.from(this.bySession.keys());
+        await Promise.all(sessions.map((sessionId) => this.unregister(sessionId)));
+        if (!server)
+            return;
+        await new Promise((resolve) => {
+            server.close(() => resolve());
+            server.closeAllConnections?.();
+        });
+    }
+    /** Issue a token and a settings file for one launched agent. Replaces any earlier registration for the session. */
+    async register(sessionId) {
+        if (!this.http)
+            await this.start();
+        await this.unregister(sessionId);
+        const token = randomBytes(24).toString('hex');
+        const settingsPath = join(this.options.settingsDir, `agent-${token.slice(0, 12)}.json`);
+        const url = `http://127.0.0.1:${this.port}/hook/${token}`;
+        await mkdir(this.options.settingsDir, { recursive: true });
+        // The file holds the token, so keep it to the owner where the platform supports modes.
+        await writeFile(settingsPath, JSON.stringify(buildHookSettings(url)), { mode: 0o600 });
+        this.byToken.set(token, { sessionId, settingsPath });
+        this.bySession.set(sessionId, token);
+        return { sessionId, settingsPath };
+    }
+    async unregister(sessionId) {
+        const token = this.bySession.get(sessionId);
+        if (!token)
+            return;
+        this.bySession.delete(sessionId);
+        const registration = this.byToken.get(token);
+        this.byToken.delete(token);
+        if (registration)
+            await rm(registration.settingsPath, { force: true });
+    }
+    handle(req, res) {
+        const reply = (status, body = '{}') => {
+            res.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'no-store' });
+            res.end(body);
+        };
+        const match = /^\/hook\/([0-9a-f]{48})$/.exec((req.url ?? '').split('?')[0]);
+        const registration = match ? this.byToken.get(match[1]) : undefined;
+        if (!registration)
+            return reply(404, '{"error":"not found"}');
+        if (req.method !== 'POST')
+            return reply(405, '{"error":"method not allowed"}');
+        const chunks = [];
+        let size = 0;
+        let tooLarge = false;
+        req.on('data', (chunk) => {
+            size += chunk.length;
+            if (size > MAX_BODY_BYTES) {
+                // Past the limit a chunk is counted and dropped, never kept, so a larger
+                // body costs no more memory than the limit. The request is read to its end
+                // rather than torn down so the 413 below actually reaches the sender, and
+                // Node's own requestTimeout (five minutes) bounds a sender that never
+                // finishes — one that also needs this agent's token to get this far.
+                tooLarge = true;
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on('end', () => {
+            if (tooLarge)
+                return reply(413, '{"error":"payload too large"}');
+            try {
+                const event = parseHookPayload(registration.sessionId, JSON.parse(Buffer.concat(chunks).toString('utf8')));
+                if (event)
+                    this.options.onEvent(event);
+            }
+            catch {
+                return reply(400, '{"error":"bad request"}');
+            }
+            reply(200);
+        });
+        req.on('error', () => reply(400, '{"error":"bad request"}'));
+    }
+}
+/**
+ * The command typed into the pane: the user's agent command plus the settings file.
+ *
+ * Forward slashes keep the path safe inside double quotes in PowerShell, cmd and bash alike.
+ * The command comes from a user setting, so it must be a single plain line.
+ */
+export function buildLaunchCommand(agentCommand, settingsPath) {
+    const command = agentCommand.trim();
+    if (!command || command.length > 200)
+        throw new Error('The AI command must be 1 to 200 characters.');
+    for (const ch of command) {
+        const code = ch.codePointAt(0) ?? 0;
+        if (code < 0x20 || code === 0x7f)
+            throw new Error('The AI command must be a single line with no control characters.');
+    }
+    const path = settingsPath.replaceAll('\\', '/');
+    if (path.includes('"'))
+        throw new Error('The settings path cannot contain a quote.');
+    return `${command} --settings "${path}"`;
+}

package/dist/main/main/editable.js

@@ -0,0 +1,31 @@
+// What makes a file safe to put in the editor's text box, shared by the local and
+// the remote read so the two cannot disagree about it.
+import { MAX_EDIT_BYTES } from '../shared/editing.js';
+export function megabytes(bytes) {
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MiB`;
+}
+/** Throws unless a file of this size may be opened. */
+export function checkEditableSize(size) {
+    if (size > MAX_EDIT_BYTES) {
+        throw new Error(`That file is ${megabytes(size)}; the editor opens files up to ${megabytes(MAX_EDIT_BYTES)}.`);
+    }
+}
+/**
+ * The file's bytes as text, or the reason it cannot be edited.
+ *
+ * Refused rather than coaxed: a NUL byte (the usual mark of a binary) and bytes
+ * that are not valid UTF-8 would each be damaged by a round trip through a text
+ * box, and a refused open costs nothing where a corrupted save does. The BOM is
+ * kept as a character so a save writes it back.
+ */
+export function decodeEditable(bytes) {
+    checkEditableSize(bytes.length);
+    if (bytes.includes(0))
+        throw new Error('That looks like a binary file, so it was not opened.');
+    try {
+        return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+    }
+    catch {
+        throw new Error('That file is not valid UTF-8, so it was not opened.');
+    }
+}

package/dist/main/main/host-label-store.js

@@ -0,0 +1,110 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+const SCHEMA_VERSION = 1;
+const MAX_HOSTS = 256;
+// Session names cap at 48, so a longer remembered label could never be reused.
+const MAX_LABEL = 48;
+/**
+ * Main-process-only, best-effort memory of the session label last given to each
+ * host, so the SSH dialog can offer it again instead of the user retyping
+ * "dev server" every time.
+ *
+ * Stores a host and a label — never a user name, a credential, or a command —
+ * the same guarantee the other stores make, and for the same reason: this is
+ * plain JSON in the user's profile. The renderer decides what a host is called
+ * for this purpose; the file only guarantees what comes back is well formed.
+ */
+export class HostLabelStore {
+    filePath;
+    file = { version: SCHEMA_VERSION, hosts: [] };
+    loaded = false;
+    writeQueue = Promise.resolve();
+    constructor(options) {
+        this.filePath = options.filePath;
+    }
+    async load() {
+        await this.ensureLoaded();
+        return normalizeFile(this.file) ?? { version: SCHEMA_VERSION, hosts: [] };
+    }
+    async save(input) {
+        await this.ensureLoaded();
+        // Validated on the way in as well as out: this is an IPC boundary, and a
+        // stored bad value would come back on every launch from then on.
+        const normalized = normalizeFile(input);
+        if (!normalized)
+            throw new Error('Invalid host label list.');
+        this.file = normalized;
+        await this.persist();
+        return normalized;
+    }
+    async ensureLoaded() {
+        if (this.loaded)
+            return;
+        this.loaded = true;
+        try {
+            const parsed = JSON.parse(await readFile(this.filePath, 'utf8'));
+            const normalized = normalizeFile(parsed);
+            if (normalized)
+                this.file = normalized;
+        }
+        catch {
+            this.file = { version: SCHEMA_VERSION, hosts: [] };
+        }
+    }
+    async persist() {
+        const snapshot = this.file;
+        this.writeQueue = this.writeQueue.then(async () => {
+            try {
+                await mkdir(dirname(this.filePath), { recursive: true });
+                const temp = join(dirname(this.filePath), `.host-labels.tmp-${process.pid}-${randomUUID()}`);
+                await writeFile(temp, JSON.stringify(snapshot, null, 2), { encoding: 'utf8', mode: 0o600 });
+                await rename(temp, this.filePath);
+            }
+            catch {
+                // Remembering a label must never affect terminal operation.
+            }
+        });
+        await this.writeQueue;
+    }
+}
+/** Strip control characters and cap length; the file is user-editable. */
+function safeText(value, limit) {
+    return value.replace(/[\u0000-\u001f\u007f]/g, '').trim().slice(0, limit);
+}
+function normalizeEntry(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const item = value;
+    if (typeof item.host !== 'string' || typeof item.label !== 'string')
+        return undefined;
+    const host = safeText(item.host, 256).toLowerCase();
+    const label = safeText(item.label, MAX_LABEL);
+    if (!host || !label)
+        return undefined;
+    return { host, label };
+}
+export function normalizeFile(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const item = value;
+    if (item.version !== SCHEMA_VERSION)
+        return undefined;
+    if (!Array.isArray(item.hosts))
+        return undefined;
+    // Later entries win and an entry is only kept once, so a hand-edited file
+    // that repeats a host settles on its last word rather than its first.
+    const byHost = new Map();
+    for (const raw of item.hosts) {
+        const entry = normalizeEntry(raw);
+        if (!entry)
+            continue;
+        byHost.delete(entry.host);
+        byHost.set(entry.host, entry);
+    }
+    // Oldest first, so the cap drops the host not touched for longest.
+    return { version: SCHEMA_VERSION, hosts: [...byHost.values()].slice(-MAX_HOSTS) };
+}
+export function defaultHostLabelPath(userDataPath) {
+    return join(userDataPath, 'host-labels.json');
+}

package/dist/main/main/local-fs.js

@@ -1,14 +1,18 @@
 // The local half of the transfer panel: directory listings and the three edits
-// the panel can make locally.
+// the panel can make locally, plus reading and writing one text file for the
+// built-in editor.
 //
-// Nothing here reads file *contents*. The renderer is sandboxed and has no
-// filesystem access of its own, and this module is deliberately the narrowest
-// widening of that boundary that a file browser needs: names, sizes, kinds, and
-// explicit create/rename/delete on a path the user pointed at.
+// The renderer is sandboxed and has no filesystem access of its own, and this
+// module is deliberately the narrowest widening of that boundary that a file
+// browser needs: names, sizes, kinds, and explicit create/rename/delete on a path
+// the user pointed at. File *contents* are only ever read or written by the
+// editor's two functions at the bottom, one file at a time, with limits.
 import { constants } from 'node:fs';
-import { access, lstat, mkdir, readdir, rename, rm, rmdir } from 'node:fs/promises';
+import { access, lstat, mkdir, readFile, readdir, rename, rm, rmdir, stat, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { isAbsolute, join, normalize, resolve } from 'node:path';
+import { EDIT_CONFLICT_MESSAGE, MAX_EDIT_BYTES } from '../shared/editing.js';
+import { checkEditableSize, decodeEditable, megabytes } from './editable.js';
 import { sortEntries } from '../shared/files.js';
 /**
  * A path this process will act on.
@@ -113,3 +117,50 @@ export async function removeLocalEntry(path, kind) {
     else
         await rm(target, { force: false });
 }
+/**
+ * Read one file as text for the editor, or say why it cannot be edited (see
+ * decodeEditable for what is refused).
+ *
+ * Follows a symlink, as opening it in any editor would.
+ */
+export async function readLocalFile(path) {
+    const target = resolveLocalPath(path);
+    const info = await stat(target);
+    if (!info.isFile())
+        throw new Error('That is not a file.');
+    // Checked before reading, so a huge file is refused without being loaded.
+    checkEditableSize(info.size);
+    const bytes = await readFile(target);
+    return { path: target, text: decodeEditable(bytes), size: bytes.length, mtimeMs: info.mtimeMs };
+}
+/**
+ * Save the editor's text back over the file it came from.
+ *
+ * Refused when the file's modified time is not the one it was opened with, so a
+ * change made meanwhile — an agent writing the same `.env` in the pane behind —
+ * is flagged instead of silently lost. `overwrite` is the user saying they have
+ * seen that and mean it.
+ *
+ * Written in place rather than through a temp file and a rename, which would
+ * replace a symlink with a plain file and reset the file's owner and mode. The
+ * price is that a write interrupted halfway leaves a short file, which for the
+ * small text files this opens is the lesser harm.
+ */
+export async function writeLocalFile(path, text, expectedMtimeMs, overwrite = false) {
+    const target = resolveLocalPath(path);
+    if (typeof text !== 'string')
+        throw new Error('There is no text to save.');
+    if (Buffer.byteLength(text, 'utf8') > MAX_EDIT_BYTES) {
+        throw new Error(`That is more than ${megabytes(MAX_EDIT_BYTES)}, which is more than the editor saves.`);
+    }
+    const current = await stat(target).then((info) => info, () => undefined);
+    if (!current)
+        throw new Error('That file no longer exists, so it was not saved.');
+    if (!current.isFile())
+        throw new Error('That is not a file.');
+    if (!overwrite && current.mtimeMs !== expectedMtimeMs)
+        throw new Error(EDIT_CONFLICT_MESSAGE);
+    await writeFile(target, text, 'utf8');
+    const saved = await stat(target);
+    return { size: saved.size, mtimeMs: saved.mtimeMs };
+}