@kdonev/termscape 0.1.0

package/dist/hub.js

@@ -0,0 +1,636 @@
+import { randomBytes, randomUUID } from 'node:crypto';
+import { EventEmitter } from 'node:events';
+import { existsSync } from 'node:fs';
+import { basename, resolve } from 'node:path';
+import { encodeInjection, parseAddress, slugify, } from './protocol/index.js';
+import { openDb } from './db/index.js';
+import { Store } from './db/store.js';
+import { ProfileRegistry } from './agents/profiles.js';
+import { TokenRegistry } from './agents/tokens.js';
+import { MessageRouter } from './agents/router.js';
+import { SessionManager } from './session/manager.js';
+import { PeerRegistry } from './remote/registry.js';
+import { deploy } from './remote/deployer.js';
+import { hubTarballPath } from './remote/tarball.js';
+import { paths } from './paths.js';
+export const HUB_VERSION = '0.1.0';
+/**
+ * How long changes are pooled before every attached machine is told the
+ * canvas has moved on. A status change is a session change, and agents change
+ * status several times a turn.
+ */
+const ANNOUNCE_COALESCE_MS = 300;
+/** Colours cycled through when a workspace is created, for canvas grouping. */
+const WORKSPACE_COLORS = [
+    '#7c9cf5',
+    '#68b06e',
+    '#d08b5b',
+    '#b06ec2',
+    '#4ea3b8',
+    '#c2607a',
+];
+/** How many agents one workspace may hold, bounding runaway recursive spawns. */
+export const DEFAULT_SPAWN_CAP = 12;
+/**
+ * The hub: owns the database, the sessions, and the routing between agents.
+ * The web server and the MCP endpoint are thin layers over this.
+ */
+export class Hub extends EventEmitter {
+    db;
+    store;
+    profiles;
+    tokens;
+    sessions;
+    router;
+    peers;
+    /**
+     * The link back to the canvas this hub was attached to, if it was. Null on a
+     * hub that owns a canvas — which is what makes the difference between the
+     * two roles a null check rather than a flag.
+     */
+    uplink = null;
+    announceTimer = null;
+    /** Live SSH tunnels, keyed by host id. Not persisted: they die with the hub. */
+    tunnels = new Map();
+    spawnCap;
+    constructor(opts = {}) {
+        super();
+        this.db = openDb(opts.dbPath ?? paths.db());
+        this.store = new Store(this.db);
+        this.profiles = ProfileRegistry.load();
+        this.tokens = new TokenRegistry();
+        this.spawnCap = opts.spawnCap ?? DEFAULT_SPAWN_CAP;
+        // Origin is corrected once the server binds and knows its port.
+        this.sessions = new SessionManager(this.store, this.profiles, this.tokens, 'http://127.0.0.1:0');
+        this.router = new MessageRouter(this.store, this.sessions, this.profiles, (m) => this.emit('message', m));
+        this.sessions.on('session', (s) => this.emit('session', s));
+        this.sessions.on('removed', (id, address) => this.emit('removed', id, address));
+        this.sessions.on('data', (id, chunk) => this.emit('data', id, chunk));
+        this.peers = new PeerRegistry(this.store, HUB_VERSION);
+        this.peers.on('host', (h) => this.emit('host', h));
+        this.peers.on('peerSession', (s) => this.emit('session', s));
+        this.peers.on('peerSessionRemoved', (addr) => this.emit('removed', addr, addr));
+        this.peers.on('peerSessionsChanged', () => this.emit('peersChanged'));
+        this.peers.on('output', (address, data) => {
+            // Remote output is addressed by name; the browser keys on session id,
+            // and for remote sessions the address *is* the id it was given.
+            this.emit('data', address, data);
+        });
+        // A host asking us to act on an address it cannot resolve itself. We are
+        // the only hub that knows where every address on this canvas lives, and
+        // the answer travels back the way the question came.
+        this.peers.on('relay', (ask, reply) => {
+            const done = (p) => p.then((result) => reply(true, result, null), (err) => reply(false, null, err.message));
+            if (ask.t === 'deliver')
+                return void done(this.deliverFrom(ask.from, ask.to, ask.body));
+            return void done(this.readScreenAt(ask.address, ask.lines));
+        });
+        // Every attached machine's view of the canvas is whatever we last told it,
+        // so anything that changes who is running has to be followed by telling
+        // them again.
+        this.peers.on('directoryStale', () => this.scheduleAnnounce());
+        this.on('session', () => this.scheduleAnnounce());
+        this.on('removed', () => this.scheduleAnnounce());
+        this.on('peersChanged', () => this.scheduleAnnounce());
+        // Anything the DB still calls running died with the previous hub.
+        this.sessions.reconcileOnBoot();
+        this.reconcileHostsOnBoot();
+    }
+    /**
+     * A persisted `connected` is a lie the moment this process starts: the
+     * tunnels and sockets died with the last one. Mark every host down, then
+     * redial the ones we know how to reach. Enrolled hosts are left alone —
+     * they dial us, and arrive on their own.
+     */
+    reconcileHostsOnBoot() {
+        for (const host of this.store.listHosts()) {
+            this.store.upsertHost({ ...host, state: 'disconnected', error: null });
+            if (host.kind !== 'ssh')
+                continue;
+            void this.connectHost(host.id).catch((err) => {
+                this.emit('hostLog', host.id, `reconnect failed: ${err.message}`);
+            });
+        }
+    }
+    /** Local sessions plus every session reported by a connected peer. */
+    allSessions() {
+        return [...this.sessions.list(), ...this.peers.sessions()];
+    }
+    /**
+     * Resolve an address to a local session, one on a peer we hold, one the
+     * canvas told us about, or nothing.
+     *
+     * The three are exclusive by construction: a hub either owns the canvas and
+     * has peers, or is attached to one and has an uplink. Never both.
+     */
+    locate(address) {
+        if (this.sessions.getByAddress(address))
+            return 'local';
+        if (this.peers.find(address))
+            return 'remote';
+        return this.uplink?.agents().some((a) => a.address === address) ? 'uplink' : null;
+    }
+    /**
+     * Attach this hub to the canvas reachable over `uplink`.
+     *
+     * Called by whatever owns the socket, once, at wiring time. A hub that owns
+     * its own canvas never calls it.
+     */
+    setUplink(uplink) {
+        this.uplink = uplink;
+    }
+    setOrigin(origin) {
+        this.sessions.setHubOrigin(origin);
+    }
+    /* ---------------------------------------------------------- workspaces */
+    createWorkspace(name, rootPath, hostId = null) {
+        const abs = resolve(rootPath);
+        if (!hostId && !existsSync(abs)) {
+            throw new Error(`folder does not exist: ${abs}`);
+        }
+        const existing = this.store.listWorkspaces();
+        const wsName = uniqueWorkspaceName(slugify(name || basename(abs)), existing.map((w) => w.name));
+        const ws = {
+            id: randomUUID(),
+            name: wsName,
+            kind: hostId ? 'remote' : 'local',
+            rootPath: abs,
+            hostId,
+            color: WORKSPACE_COLORS[existing.length % WORKSPACE_COLORS.length],
+            createdAt: Date.now(),
+            archivedAt: null,
+        };
+        this.store.insertWorkspace(ws);
+        this.emit('workspace', ws);
+        return ws;
+    }
+    async removeWorkspace(id) {
+        const ws = this.store.getWorkspace(id);
+        for (const s of this.sessions.list().filter((s) => s.workspaceId === id)) {
+            this.sessions.remove(s.id);
+        }
+        // A workspace on a host owns no PTY here: its agents run over there, and
+        // the peer has to be told about each one or they come back on the next
+        // resync as windows belonging to a workspace that no longer exists. The
+        // peer's own workspace id means nothing in this database, so they are
+        // found the only way they can be - by the workspace half of the address.
+        if (ws?.hostId) {
+            for (const s of this.peers.sessions()) {
+                if (parseAddress(s.address)?.workspace === ws.name) {
+                    await this.peers.removeSession(s.address);
+                }
+            }
+        }
+        this.store.removeWorkspace(id);
+        this.emit('workspaceRemoved', id);
+    }
+    /* --------------------------------------------------------------- hosts */
+    addHost(input) {
+        const host = {
+            id: randomUUID(),
+            label: input.label || `${input.sshUser}@${input.sshHost}`,
+            kind: 'ssh',
+            sshHost: input.sshHost,
+            sshUser: input.sshUser,
+            sshPort: input.sshPort,
+            platform: null,
+            hubVersion: null,
+            state: 'disconnected',
+            lastSeenAt: null,
+            error: null,
+        };
+        this.store.upsertHost({ ...host, keyRef: input.privateKeyPath ?? null });
+        this.emit('host', host);
+        return host;
+    }
+    /**
+     * Drop a host from the canvas, and stop the hub running on it.
+     *
+     * Stopping it matters more than it looks: that hub is a daemon on someone
+     * else's machine, and if it keeps running it holds its own install open —
+     * on Windows an in-use .node cannot be deleted, so re-joining that machine
+     * fails on a permission error rather than replacing the files.
+     */
+    async removeHost(hostId) {
+        await this.peers.requestShutdown(hostId).catch(() => false);
+        this.peers.remove(hostId);
+        void this.tunnels.get(hostId)?.dispose().catch(() => { });
+        this.tunnels.delete(hostId);
+        this.store.removeHost(hostId);
+        this.emit('hostRemoved', hostId);
+    }
+    /**
+     * Deploy the hub to a host if needed, tunnel to it, and join it to the
+     * directory. The peer token is minted per connection and never written to
+     * the local database.
+     */
+    async connectHost(hostId) {
+        const host = this.store.listHosts().find((h) => h.id === hostId);
+        if (!host)
+            throw new Error(`unknown host ${hostId}`);
+        if (host.kind !== 'ssh' || !host.sshHost || !host.sshUser) {
+            throw new Error(`"${host.label}" enrolled itself and dials this hub; there is nothing here to connect to. ` +
+                'Re-run the join command on that machine if it has not come back.');
+        }
+        const token = randomBytes(24).toString('base64url');
+        this.store.upsertHost({ ...host, state: 'connecting', error: null });
+        this.emit('host', { ...host, state: 'connecting', error: null });
+        try {
+            const result = await deploy({
+                sshHost: host.sshHost,
+                sshUser: host.sshUser,
+                sshPort: host.sshPort,
+                privateKeyPath: this.store.hostKeyRef(hostId) ?? undefined,
+                token,
+                expectedVersion: HUB_VERSION,
+                packagePath: hubTarballPath() ?? undefined,
+                log: (line) => this.emit('hostLog', hostId, line),
+            });
+            this.tunnels.set(hostId, result);
+            this.peers.add(host, result.localUrl, token);
+        }
+        catch (err) {
+            const message = err.message;
+            this.store.upsertHost({ ...host, state: 'error', error: message });
+            this.emit('host', { ...host, state: 'error', error: message });
+            throw err;
+        }
+    }
+    /* ------------------------------------------------------------ sessions */
+    async startSession(opts) {
+        const ws = this.store.getWorkspace(opts.workspaceId);
+        if (!ws)
+            throw new Error(`unknown workspace ${opts.workspaceId}`);
+        // A workspace that belongs to a host runs its agents there. The peer owns
+        // the PTY; what comes back is a session we show on our own canvas.
+        if (ws.hostId) {
+            const spawner = opts.spawnedBy ? this.sessions.get(opts.spawnedBy) : null;
+            return this.peers.startSession(ws.hostId, {
+                workspaceName: ws.name,
+                rootPath: ws.rootPath,
+                profile: opts.profile,
+                name: opts.name,
+                spawnedByAddress: spawner?.address ?? null,
+            });
+        }
+        const count = this.sessions.list().filter((s) => s.workspaceId === opts.workspaceId).length;
+        if (count >= this.spawnCap) {
+            throw new Error(`workspace already has ${count} agents (cap ${this.spawnCap}); stop one first`);
+        }
+        return this.sessions.start({
+            workspaceId: opts.workspaceId,
+            profileId: opts.profile,
+            name: opts.name,
+            cwd: opts.cwd,
+            spawnedBy: opts.spawnedBy ?? null,
+        });
+    }
+    async resumeWorkspace(workspaceId) {
+        const out = [];
+        for (const s of this.sessions.list()) {
+            if (s.workspaceId !== workspaceId)
+                continue;
+            if (s.state === 'running' || s.state === 'starting')
+                continue;
+            try {
+                out.push(await this.sessions.resume(s.id));
+            }
+            catch (err) {
+                this.emit('error', new Error(`resume ${s.address}: ${err.message}`));
+            }
+        }
+        return out;
+    }
+    moveWindow(sessionId, rect) {
+        this.sessions.moveWindow(sessionId, rect);
+    }
+    setViewport(v) {
+        this.store.saveViewport(v);
+    }
+    /* ------------------------------------------------- AgentApi (MCP tools) */
+    requireSession(sessionId) {
+        const s = this.sessions.get(sessionId);
+        if (!s)
+            throw new Error('your session is no longer known to the hub');
+        return s;
+    }
+    async whoami(sessionId) {
+        const s = this.requireSession(sessionId);
+        const ws = this.store.getWorkspace(s.workspaceId);
+        return {
+            address: s.address,
+            workspace: ws?.name ?? null,
+            cwd: s.cwd,
+            profile: s.profile,
+            spawnedBy: s.spawnedBy ? this.sessions.get(s.spawnedBy)?.address ?? null : null,
+        };
+    }
+    /**
+     * One flat directory across every hub. An agent should not have to know or
+     * care whether a peer is on this machine or a remote one; the address is
+     * the whole interface.
+     */
+    async listAgents(sessionId, workspace) {
+        const me = this.requireSession(sessionId);
+        const wsById = new Map(this.store.listWorkspaces().map((w) => [w.id, w]));
+        const local = this.sessions.list().map((s) => ({
+            address: s.address,
+            workspace: wsById.get(s.workspaceId)?.name ?? null,
+            profile: s.profile,
+            state: s.state,
+            status: s.status,
+            statusText: s.statusText,
+            host: 'local',
+            isYou: s.id === me.id,
+        }));
+        const hostLabels = new Map(this.store.listHosts().map((h) => [h.id, h.label]));
+        const remote = this.peers.sessions().map((s) => {
+            // A remote session's workspace row lives on its own hub, not here, so
+            // the workspace name comes from the address and the host from the
+            // registry rather than from a local join that would always miss.
+            const hostId = this.peers.hostIdFor(s.address);
+            return {
+                address: s.address,
+                workspace: s.address.split('/')[0] ?? null,
+                profile: s.profile,
+                state: s.state,
+                status: s.status,
+                statusText: s.statusText,
+                host: (hostId ? hostLabels.get(hostId) : undefined) ?? 'remote',
+                isYou: false,
+            };
+        });
+        // What the canvas told us about, on a hub attached to one. Its own view
+        // is the only complete one, so this is where an agent on an attached
+        // machine learns that anything exists beyond this machine.
+        const fromCanvas = (this.uplink?.agents() ?? []).map((a) => ({ ...a, isYou: false }));
+        return [...local, ...remote, ...fromCanvas].filter((a) => !workspace || a.workspace === workspace);
+    }
+    async sendMessage(sessionId, to, text) {
+        const me = this.requireSession(sessionId);
+        if (me.address === to)
+            throw new Error('cannot send a message to yourself');
+        return this.deliverFrom(me.address, to, text);
+    }
+    /**
+     * Tell every attached machine who is on the canvas.
+     *
+     * Coalesced, because a status change is a session change and agents change
+     * status several times a turn; the directory only needs to be right once the
+     * dust settles. Unrefed so a pending announcement never holds the hub up.
+     */
+    scheduleAnnounce() {
+        // Most hubs have nobody to tell: one that owns a canvas with no machines
+        // attached, and every hub that is itself an attached machine.
+        if (this.announceTimer || !this.peers.any)
+            return;
+        this.announceTimer = setTimeout(() => {
+            this.announceTimer = null;
+            this.peers.announce((hostId) => this.directoryFor(hostId));
+        }, ANNOUNCE_COALESCE_MS);
+        this.announceTimer.unref?.();
+    }
+    /**
+     * The canvas as one machine on it should see it: everything, minus that
+     * machine's own agents. It has those already, and sending them back would
+     * have every agent over there listed twice.
+     */
+    directoryFor(hostId) {
+        const wsById = new Map(this.store.listWorkspaces().map((w) => [w.id, w]));
+        const hostLabels = new Map(this.store.listHosts().map((h) => [h.id, h.label]));
+        const here = this.sessions.list().map((s) => ({
+            address: s.address,
+            workspace: wsById.get(s.workspaceId)?.name ?? null,
+            profile: s.profile,
+            state: s.state,
+            status: s.status,
+            statusText: s.statusText,
+            // What the machine that owns the canvas is called, from anywhere else.
+            host: 'canvas',
+        }));
+        const elsewhere = this.peers
+            .sessions()
+            .filter((s) => this.peers.hostIdFor(s.address) !== hostId)
+            .map((s) => ({
+            address: s.address,
+            workspace: s.address.split('/')[0] ?? null,
+            profile: s.profile,
+            state: s.state,
+            status: s.status,
+            statusText: s.statusText,
+            host: hostLabels.get(this.peers.hostIdFor(s.address) ?? '') ?? 'remote',
+        }));
+        return [...here, ...elsewhere];
+    }
+    /**
+     * Deliver on behalf of an address this hub has already established.
+     *
+     * Three ways out, and which one is taken is the only difference between an
+     * agent in the next window, one on a machine this hub holds, and one only
+     * the canvas can reach. No caller sees which.
+     */
+    async deliverFrom(fromAddr, to, text) {
+        const where = this.locate(to);
+        // An unknown address goes down the local path deliberately: the router
+        // records the failed attempt with its reason, which is what keeps the
+        // promise that no message is ever dropped silently.
+        if (where === 'local' || where === null) {
+            const r = this.router.send(fromAddr, to, text);
+            if (!r.delivered)
+                throw new Error(r.error ?? 'delivery failed');
+            return { delivered: true, to, deliveredAt: r.deliveredAt };
+        }
+        // Off this machine: whoever owns the PTY performs the injection. We still
+        // record the attempt locally so the message log and the canvas edge are
+        // complete on this side too.
+        const id = randomUUID();
+        const sentAt = Date.now();
+        try {
+            if (where === 'remote')
+                await this.peers.deliver(fromAddr, to, text);
+            // Only the canvas knows where every address lives, so an attached hub
+            // hands the message up rather than trying to route it itself.
+            else
+                await this.uplink.ask({ t: 'deliver', from: fromAddr, to, body: text });
+            const m = {
+                id, fromAddr, toAddr: to, body: text,
+                sentAt, deliveredAt: Date.now(), deliveryState: 'delivered', error: null,
+            };
+            this.store.insertMessage(m);
+            this.emit('message', m);
+            return { delivered: true, to, deliveredAt: m.deliveredAt };
+        }
+        catch (err) {
+            const m = {
+                id, fromAddr, toAddr: to, body: text,
+                sentAt, deliveredAt: null, deliveryState: 'failed',
+                error: err.message,
+            };
+            this.store.insertMessage(m);
+            this.emit('message', m);
+            throw err;
+        }
+    }
+    async spawnAgent(sessionId, opts) {
+        const me = this.requireSession(sessionId);
+        const ws = opts.workspace
+            ? this.store.getWorkspaceByName(opts.workspace)
+            : this.store.getWorkspace(me.workspaceId);
+        if (!ws)
+            throw new Error(`unknown workspace "${opts.workspace}"`);
+        const child = await this.startSession({
+            workspaceId: ws.id,
+            profile: opts.profile ?? me.profile,
+            name: opts.name,
+            spawnedBy: me.id,
+        });
+        if (opts.prompt) {
+            // The child's CLI is not listening yet; wait for it to come up before
+            // typing, otherwise the first instruction is written into the void.
+            if (ws.hostId) {
+                // The child's PTY is on the peer, so the readiness wait belongs there
+                // too; a plain delivery is the only thing this side can do.
+                void this.peers
+                    .deliver(me.address, child.address, opts.prompt)
+                    .catch(() => {
+                    // Recorded by the message log on the owning hub; a spawn that
+                    // succeeded should not fail because the greeting did not land.
+                });
+            }
+            else {
+                void this.deliverInitialPrompt(child.id, me.address, opts.prompt);
+            }
+        }
+        return {
+            address: child.address,
+            workspace: ws.name,
+            profile: child.profile,
+            promptQueued: !!opts.prompt,
+        };
+    }
+    /**
+     * Wait for a freshly spawned agent to produce output (its prompt) before
+     * injecting the first instruction. Bounded so a CLI that never prints
+     * cannot leave this hanging.
+     */
+    async deliverInitialPrompt(sessionId, fromAddr, prompt) {
+        const pty = this.sessions.pty(sessionId);
+        if (!pty)
+            return;
+        const ready = await new Promise((res) => {
+            let settled = false;
+            const done = (v) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                pty.off('data', onData);
+                res(v);
+            };
+            const onData = () => setTimeout(() => done(true), 1200);
+            const timer = setTimeout(() => done(false), 20_000);
+            timer.unref?.();
+            pty.on('data', onData);
+        });
+        if (!ready || !pty.running)
+            return;
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return;
+        const mode = this.profiles.get(session.profile)?.inject ?? 'bracketed';
+        try {
+            this.sessions.write(sessionId, encodeInjection(`[from ${fromAddr}] ${prompt}`, mode));
+        }
+        catch {
+            // The agent died between the readiness check and the write; the message
+            // log already reflects that it never started.
+        }
+    }
+    async readScreen(sessionId, address, lines) {
+        this.requireSession(sessionId);
+        return this.readScreenAt(address, lines);
+    }
+    /**
+     * read_screen for a caller this hub has already established — either an
+     * agent of its own, or a peer that authenticated one and is asking on its
+     * behalf. Resolves the address the same three ways a delivery does.
+     */
+    async readScreenAt(address, lines) {
+        const where = this.locate(address);
+        if (where === 'remote')
+            return this.peers.readScreen(address, lines);
+        if (where === 'uplink') {
+            return this.uplink.ask({
+                t: 'readScreen',
+                address,
+                lines,
+            });
+        }
+        const target = this.sessions.getByAddress(address);
+        if (!target)
+            throw new Error(`no agent at address "${address}"`);
+        const pty = this.sessions.pty(target.id);
+        if (!pty) {
+            const snap = this.store.getSnapshot(target.id);
+            if (!snap)
+                throw new Error(`agent "${address}" has no screen to read`);
+            return { address, running: false, screen: '(not running; last saved screen only)' };
+        }
+        return { address, running: pty.running, screen: pty.tailLines(lines ?? 40) };
+    }
+    async setStatus(sessionId, text) {
+        const s = this.requireSession(sessionId);
+        this.sessions.setStatusText(s.id, text);
+        return { ok: true };
+    }
+    async stopAgent(sessionId, address) {
+        const me = this.requireSession(sessionId);
+        const target = this.sessions.getByAddress(address);
+        if (!target) {
+            // Spawn lineage lives on the hub that owns the session, so the
+            // spawned-by rule below is enforced over there, by that hub.
+            if (this.locate(address) === 'remote') {
+                await this.peers.stopSession(address);
+                return { stopped: address };
+            }
+            throw new Error(`no agent at address "${address}"`);
+        }
+        if (target.id === me.id)
+            throw new Error('use your own exit command to stop yourself');
+        // An agent may only stop what it created. Otherwise a single confused
+        // agent could take down the whole canvas.
+        if (target.spawnedBy !== me.id) {
+            throw new Error(`"${address}" was not spawned by you; only its spawner may stop it`);
+        }
+        this.sessions.stop(target.id);
+        return { stopped: address };
+    }
+    /* ------------------------------------------------------------ lifecycle */
+    messages() {
+        return this.store.listMessages();
+    }
+    shutdown() {
+        for (const t of this.tunnels.values())
+            void t.dispose().catch(() => { });
+        this.tunnels.clear();
+        this.peers.closeAll();
+        this.sessions.shutdown();
+        try {
+            this.db.close();
+        }
+        catch {
+            // Already closed.
+        }
+    }
+}
+function uniqueWorkspaceName(desired, taken) {
+    const set = new Set(taken);
+    if (!set.has(desired))
+        return desired;
+    for (let n = 2; n < 1000; n++) {
+        if (!set.has(`${desired}-${n}`))
+            return `${desired}-${n}`;
+    }
+    throw new Error(`could not allocate a workspace name for "${desired}"`);
+}
+//# sourceMappingURL=hub.js.map