@kdonev/termscape 0.1.7 → 0.1.9

package/dist/hub.js

@@ -4,7 +4,7 @@ import { readFileSync } from 'node:fs';
 import { encodeInjection, INJECT_SUBMIT, MAX_PENDING_PROPOSALS, parseAddress, slugify, } from './protocol/index.js';
 import { openDb } from './db/index.js';
 import { Store } from './db/store.js';
-import { briefMode, ProfileRegistry } from './agents/profiles.js';
+import { briefMode, isPlainTerminal, ProfileRegistry } from './agents/profiles.js';
 import { AgentDetector } from './agents/detect.js';
 import { TemplateRegistry, overlayCanvasTemplates, validate as validateTemplate, } from './agents/templates.js';
 import { TokenRegistry } from './agents/tokens.js';
@@ -18,9 +18,10 @@ import { PeerRegistry } from './remote/registry.js';
 import { SPAWN_RELAY_TIMEOUT_MS } from './remote/peer-serve.js';
 import { deploy } from './remote/deployer.js';
 import { hubTarballPath } from './remote/tarball.js';
+import { debug } from './debug.js';
 import { paths } from './paths.js';
 import { checkFolder, folderName } from './folders.js';
-export const HUB_VERSION = '0.1.7';
+export const HUB_VERSION = '0.1.9';
 /**
  * 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
@@ -33,6 +34,17 @@ const ANNOUNCE_COALESCE_MS = 300;
  */
 const OPENING_QUIET_MS = 1500;
 const OPENING_READY_CAP_MS = 20_000;
+/**
+ * How long a delivery waits for a starting agent before going in regardless.
+ *
+ * There has to be a bound. A session's readiness gate deliberately outlasts
+ * its own cap while a question is on screen - the instruction is still wanted
+ * once the human answers - but a `send_message` that blocks its caller until
+ * somebody walks over to a window is worse than a message that arrives badly.
+ * So the wait is bounded here, and past it delivery is what it always was:
+ * immediate, recorded, and the CLI's business.
+ */
+const DELIVERY_WAIT_CAP_MS = 20_000;
 /** Colours cycled through when a workspace is created, for canvas grouping. */
 const WORKSPACE_COLORS = [
     '#7c9cf5',
@@ -84,6 +96,16 @@ export class Hub extends EventEmitter {
      * two roles a null check rather than a flag.
      */
     uplink = null;
+    /**
+     * Per session: resolves once its CLI is reading and its opening instruction,
+     * if it had one, has been typed and sent.
+     *
+     * Every delivery to a local session queues behind this. Without it a message
+     * sent to an agent that was still starting - which is exactly what an agent
+     * that has just called `spawn_agent` does next - was written into a program
+     * not yet reading, and sat in the composer unsent forever (issue 27).
+     */
+    opened = new Map();
     announceTimer = null;
     /** Live SSH tunnels, keyed by host id. Not persisted: they die with the hub. */
     tunnels = new Map();
@@ -120,7 +142,11 @@ export class Hub extends EventEmitter {
         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('removed', (id, address) => {
+            // Nothing left to open, and nothing left to hold a delivery for.
+            this.opened.delete(id);
+            this.emit('removed', id, address);
+        });
         this.sessions.on('data', (id, chunk) => this.emit('data', id, chunk));
         this.peers = new PeerRegistry(this.store, HUB_VERSION, (address) => this.sessions.getByAddress(address)?.id ?? null);
         // Peer windows share the canvas, so a new local window must not land on
@@ -249,6 +275,19 @@ export class Hub extends EventEmitter {
             this.uplink?.agents().find((a) => a.address === address);
         return found ? { address, parentAddress: found.parentAddress ?? null } : null;
     }
+    /**
+     * Whether the window at `address` is a shell rather than an agent, as far
+     * as this hub can tell. Profiles are judged against this hub's own
+     * registry, which holds every built-in one; a custom profile only another
+     * machine declares reads as an agent, which is what it was before.
+     */
+    isShellAt(address) {
+        const profile = this.sessions.getByAddress(address)?.profile ??
+            this.peers.find(address)?.session.profile ??
+            this.uplink?.agents().find((a) => a.address === address)?.profile;
+        const p = profile ? this.profiles.get(profile) : null;
+        return p ? isPlainTerminal(p) : false;
+    }
     /**
      * Refuse to act on an address the viewer may not see, in exactly the words
      * used for one that does not exist: a hidden agent must not be discoverable
@@ -862,8 +901,7 @@ export class Hub extends EventEmitter {
         const opening = [this.typedBrief(session), opts.prompt]
             .filter((part) => !!part)
             .join('\n\n');
-        if (opening)
-            void this.deliverOpeningInstruction(session.id, opening);
+        this.noteOpening(session.id, opening || null);
         this.store.setOpeningPrompt(session.id, opts.restorePrompt === undefined ? (opts.prompt ?? null) : opts.restorePrompt);
         return session;
     }
@@ -900,9 +938,9 @@ export class Hub extends EventEmitter {
      */
     async resumeSession(sessionId) {
         const session = await this.sessions.resume(sessionId);
-        const brief = this.typedBrief(session);
-        if (brief)
-            void this.deliverOpeningInstruction(session.id, brief);
+        // A fresh CLI, so a fresh gate: messages must wait for this one to be
+        // reading just as they did when it first started.
+        this.noteOpening(session.id, this.typedBrief(session));
         return session;
     }
     /**
@@ -924,8 +962,7 @@ export class Hub extends EventEmitter {
         const opening = [this.typedBrief(session), this.store.getOpeningPrompt(sessionId)]
             .filter((part) => !!part)
             .join('\n\n');
-        if (opening)
-            void this.deliverOpeningInstruction(session.id, opening);
+        this.noteOpening(session.id, opening || null);
         return session;
     }
     async resumeWorkspace(workspaceId) {
@@ -1408,6 +1445,16 @@ export class Hub extends EventEmitter {
             throw new Error('cannot send a message to yourself');
         this.requireVisible(me, to);
         const result = await this.deliverFrom(me.address, to, text);
+        // A shell never answers: what it prints stays on its own screen, and
+        // reading that screen is the only way to see it - not polling (issue 30).
+        if (this.isShellAt(to)) {
+            return {
+                ...result,
+                note: `${to} is a shell, not an agent: your text was run there as a command, ` +
+                    'without a [from ...] prefix, and nothing will be sent back to you. Call ' +
+                    'read_screen on it to see the output.',
+            };
+        }
         // Only a successful send counts as a question asked - deliverFrom throws
         // on failure, so a message that never arrived does not excuse polling.
         this.pollWatch.noteMessage(me.address, to);
@@ -1478,6 +1525,19 @@ export class Hub extends EventEmitter {
         // 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) {
+            // Behind the target's opening, if it is still starting. This is the one
+            // place delivery is not immediate, and the exception earns itself: the
+            // alternative is writing into a CLI that is not reading, which is not a
+            // delivery at all.
+            const target = this.sessions.getByAddress(to);
+            if (target) {
+                const t0 = Date.now();
+                await this.awaitOpened(target.id);
+                const waited = Date.now() - t0;
+                if (waited > 50) {
+                    debug('deliver', `${fromAddr} -> ${to}: held ${waited}ms behind the agent's opening`);
+                }
+            }
             const r = this.router.send(fromAddr, to, text);
             if (!r.delivered)
                 throw new Error(r.error ?? 'delivery failed');
@@ -1488,6 +1548,10 @@ export class Hub extends EventEmitter {
         // complete on this side too.
         const id = randomUUID();
         const sentAt = Date.now();
+        debug('deliver', `message ${id} ${fromAddr} -> ${to} (${text.length} chars): ` +
+            (where === 'remote'
+                ? `to the attached machine ${this.peers.hostIdFor(to) ?? '?'}, which types it`
+                : 'up to the canvas, which routes it'));
         try {
             if (where === 'remote')
                 await this.peers.deliver(fromAddr, to, text);
@@ -1501,9 +1565,11 @@ export class Hub extends EventEmitter {
             };
             this.store.insertMessage(m);
             this.emit('message', m);
+            debug('deliver', `message ${id}: accepted after ${Date.now() - sentAt}ms`);
             return { delivered: true, to, deliveredAt: m.deliveredAt };
         }
         catch (err) {
+            debug('deliver', `message ${id}: failed - ${err.message}`);
             const m = {
                 id, fromAddr, toAddr: to, body: text,
                 sentAt, deliveredAt: null, deliveryState: 'failed',
@@ -1579,7 +1645,13 @@ export class Hub extends EventEmitter {
          * gets there.
          */
         const picked = await this.pickSpawnTemplate(me, opts.profile);
-        const instruction = opts.prompt ? `[from ${me.address}] ${opts.prompt}` : null;
+        // Attributed, except in a shell, which would run the prefix (issue 30).
+        const childProfile = this.profiles.get(picked.agent);
+        const instruction = !opts.prompt
+            ? null
+            : childProfile && isPlainTerminal(childProfile)
+                ? opts.prompt
+                : `[from ${me.address}] ${opts.prompt}`;
         const opening = [picked.prompt, instruction].filter(Boolean).join('\n\n') || undefined;
         // A `host` naming something beyond this hub's own machine has to go up
         // the link: an attached hub holds rows for nothing but itself, and only
@@ -1705,6 +1777,48 @@ export class Hub extends EventEmitter {
     async deliverOpeningInstruction(sessionId, prompt) {
         await this.typeWhenReady(sessionId, prompt);
     }
+    /**
+     * Record how a session opens, and hold every later delivery behind it.
+     *
+     * Registered whether or not there is anything to type: an agent started with
+     * no instruction at all still has a CLI that is not reading yet, and that is
+     * the case issue 27 was reported for. Not awaited by the caller - the window
+     * appears now - but stored, so the first message to arrive waits for the
+     * same moment the instruction would have.
+     */
+    noteOpening(sessionId, opening) {
+        const done = opening
+            ? this.deliverOpeningInstruction(sessionId, opening)
+            : this.awaitReady(sessionId).then(() => { });
+        // Failures are the gate opening, not the gate jamming: a session that died
+        // on the way up must not hold its own message log hostage.
+        this.opened.set(sessionId, done.catch(() => { }));
+    }
+    /**
+     * Wait for a local session to be ready to be typed at, but not forever.
+     *
+     * Once resolved the promise stays resolved, so this costs a steady-state
+     * delivery a microtask and nothing else.
+     */
+    async awaitOpened(sessionId) {
+        const gate = this.opened.get(sessionId);
+        if (!gate)
+            return;
+        let timer;
+        try {
+            await Promise.race([
+                gate,
+                new Promise((res) => {
+                    timer = setTimeout(res, DELIVERY_WAIT_CAP_MS);
+                    timer.unref?.();
+                }),
+            ]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
     /**
      * Wait for the CLI to be up, then type. Written straight away the text lands
      * before the program is reading it; the wait is for output to arrive and
@@ -1725,17 +1839,65 @@ export class Hub extends EventEmitter {
      * taken as answers to it. Such a screen is waited out until it changes.
      */
     async typeWhenReady(sessionId, text) {
+        const t0 = Date.now();
+        debug('deliver', `${sessionId} first instruction (${text.length} chars): waiting for the CLI`);
+        const ready = await this.awaitReady(sessionId);
         const pty = this.sessions.pty(sessionId);
-        if (!pty)
+        if (!ready || !pty?.running) {
+            debug('deliver', `${sessionId} first instruction dropped after ${Date.now() - t0}ms: ` +
+                (pty?.running ? 'the CLI never drew anything' : 'the CLI exited'));
+            return;
+        }
+        const session = this.sessions.get(sessionId);
+        if (!session)
             return;
+        const mode = this.profiles.get(session.profile)?.inject ?? 'bracketed';
+        debug('deliver', `${sessionId} first instruction: CLI ready after ${Date.now() - t0}ms, typing it`);
+        try {
+            // Awaited, so that a caller holding this session's readiness gate is not
+            // released until the Enter is in: a message injected between the paste
+            // and its Enter is folded into the same prompt.
+            await this.sessions.inject(sessionId, encodeInjection(text, mode), INJECT_SUBMIT);
+        }
+        catch {
+            // The agent died between the readiness check and the write; the message
+            // log already reflects that it never started.
+        }
+    }
+    /**
+     * Wait until the CLI in a session is up and reading, or give up.
+     *
+     * Split out of `typeWhenReady` because typing is not the only thing that has
+     * to wait for this. A message delivered to an agent whose CLI has not
+     * started reading is written into a program that is not listening: the paste
+     * lands in a composer that is not there yet and the Enter goes nowhere, and
+     * what the sender sees is a delivery that was recorded and never acted on.
+     * See `deliverFrom`.
+     */
+    async awaitReady(sessionId) {
+        const pty = this.sessions.pty(sessionId);
+        if (!pty)
+            return false;
         const profile = this.profiles.get(this.sessions.get(sessionId)?.profile ?? '');
         const hint = profile?.askingHint ? new RegExp(profile.askingHint, 'i') : null;
         // A question on screen outlasts any cap: the human answers it when they
         // get to the window, and the instruction is still wanted after that.
         const asking = () => !!hint && hint.test(pty.tailLines(pty.rows));
-        const ready = await new Promise((res) => {
+        /*
+         * Quiet is not enough for an agent that reports through hooks. On kid7,
+         * starting straight after an update, Claude Code had drawn its prompt and
+         * gone quiet five seconds in - and was not reading yet: the instruction
+         * typed then lost its Enter, and SessionStart only arrived after the paste.
+         * Its first hook is the agent saying it is up, so for such an agent that
+         * is what readiness waits for, on top of the quiet. The cap still applies,
+         * so an agent whose hooks never run is not held forever.
+         */
+        const wantsHook = !!profile?.mcp && profile.status === 'hooks';
+        const hooked = () => !wantsHook || pty.hooksReported;
+        return new Promise((res) => {
             let settled = false;
             let seen = false;
+            let isQuiet = false;
             let quiet = null;
             const done = (v) => {
                 if (settled)
@@ -1746,40 +1908,54 @@ export class Hub extends EventEmitter {
                     clearTimeout(quiet);
                 pty.off('data', onData);
                 pty.off('exit', onExit);
+                pty.off('hook', onHook);
                 res(v);
             };
+            const settle = () => {
+                if (asking()) {
+                    debug('deliver', `${sessionId} quiet, but a question is on screen; still waiting`);
+                    return;
+                }
+                if (!hooked()) {
+                    debug('deliver', `${sessionId} quiet, but its hooks have not reported yet; still waiting`);
+                    return;
+                }
+                debug('deliver', `${sessionId} ready: no output for ${OPENING_QUIET_MS}ms, hooks reported`);
+                done(true);
+            };
             const onData = () => {
                 seen = true;
+                isQuiet = false;
                 if (quiet)
                     clearTimeout(quiet);
                 quiet = setTimeout(() => {
                     quiet = null;
-                    if (!asking())
-                        done(true);
+                    isQuiet = true;
+                    settle();
                 }, OPENING_QUIET_MS);
             };
+            // A hook that lands after the quiet is what the quiet was waiting for.
+            const onHook = () => {
+                if (isQuiet)
+                    settle();
+            };
             const onExit = () => done(false);
             const cap = setTimeout(() => {
-                if (!asking())
-                    done(seen);
+                if (asking())
+                    return;
+                debug('deliver', `${sessionId} ${OPENING_READY_CAP_MS}ms cap reached ` +
+                    (!seen
+                        ? 'with no output at all'
+                        : hooked()
+                            ? 'while still drawing; typing anyway'
+                            : 'and its hooks never reported; typing anyway'));
+                done(seen);
             }, OPENING_READY_CAP_MS);
             cap.unref?.();
             pty.on('data', onData);
             pty.on('exit', onExit);
+            pty.on('hook', onHook);
         });
-        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.inject(sessionId, encodeInjection(text, mode), INJECT_SUBMIT);
-        }
-        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) {
         const me = this.requireSession(sessionId);
@@ -1790,6 +1966,9 @@ export class Hub extends EventEmitter {
         // readScreenAt: that path also serves peers asking on this hub's behalf
         // for a caller it never authenticated, and the count belongs to the
         // caller's own hub.
+        // Not for a shell: watching its screen is how its output is read at all.
+        if (this.isShellAt(address))
+            return result;
         const note = this.pollWatch.noteRead(me.address, address);
         return note ? { ...result, note } : result;
     }