@kdonev/termscape 0.1.0 → 0.1.2

package/dist/hub.js

@@ -1,19 +1,22 @@
 import { randomBytes, randomUUID } from 'node:crypto';
 import { EventEmitter } from 'node:events';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { basename, resolve } from 'node:path';
-import { encodeInjection, parseAddress, slugify, } from './protocol/index.js';
+import { encodeInjection, MAX_PENDING_PROPOSALS, 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 { briefMode, ProfileRegistry } from './agents/profiles.js';
+import { AgentDetector } from './agents/detect.js';
+import { TemplateRegistry, validate as validateTemplate } from './agents/templates.js';
 import { TokenRegistry } from './agents/tokens.js';
 import { MessageRouter } from './agents/router.js';
 import { SessionManager } from './session/manager.js';
+import { briefFileFor } from './agents/wiring.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';
+export const HUB_VERSION = '0.1.2';
 /**
  * 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
@@ -39,6 +42,16 @@ export class Hub extends EventEmitter {
     db;
     store;
     profiles;
+    /**
+     * What the picker offers: an agent plus a model, an effort and a first task.
+     *
+     * Reassigned rather than mutated when a template is saved or removed: the
+     * list is a merge of three sources and one write can change a row nobody
+     * touched, so the answer is a fresh load rather than a patched one.
+     */
+    templates;
+    /** What of those profiles this machine actually has installed. */
+    agents;
     tokens;
     sessions;
     router;
@@ -53,11 +66,29 @@ export class Hub extends EventEmitter {
     /** Live SSH tunnels, keyed by host id. Not persisted: they die with the hub. */
     tunnels = new Map();
     spawnCap;
+    /**
+     * Proposals waiting on a human, newest last. In memory on purpose: the agent
+     * waiting for the answer dies with the hub, so a proposal that outlived both
+     * would be a dialog nobody could be told the outcome of.
+     */
+    proposals = new Map();
+    /**
+     * How many browsers are looking. The hub cannot see its own sockets - the
+     * server owns those - so it is told, and it only uses this to answer an
+     * agent honestly about whether anyone is there to decide.
+     */
+    viewers = 0;
     constructor(opts = {}) {
         super();
         this.db = openDb(opts.dbPath ?? paths.db());
         this.store = new Store(this.db);
         this.profiles = ProfileRegistry.load();
+        this.templates = TemplateRegistry.load(this.profiles, this.store);
+        this.agents = new AgentDetector(this.profiles);
+        // A joined hub is the only thing that knows its own PATH, so it says so
+        // rather than waiting to be asked again; peer-serve forwards this to the
+        // canvas the same way it forwards session changes.
+        this.agents.on('changed', (found) => this.emit('agents', found));
         this.tokens = new TokenRegistry();
         this.spawnCap = opts.spawnCap ?? DEFAULT_SPAWN_CAP;
         // Origin is corrected once the server binds and knows its port.
@@ -66,8 +97,12 @@ export class Hub extends EventEmitter {
         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 = 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
+        // one. The manager cannot see the registry; this is the view it needs.
+        this.sessions.remoteWindows = () => this.peers.sessions().map((s) => s.window);
         this.peers.on('host', (h) => this.emit('host', h));
+        this.peers.on('peerAgents', (hostId, found) => this.emit('hostAgents', hostId, found));
         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'));
@@ -164,6 +199,59 @@ export class Hub extends EventEmitter {
         this.emit('workspace', ws);
         return ws;
     }
+    /**
+     * Rename a workspace, or point it at a different folder.
+     *
+     * The rename is the fussy half. A workspace's name is the first segment of
+     * every agent address in it (`workspace/agent`), and those addresses are
+     * stored on the session rows, written into each agent's brief, and held by
+     * peers on other machines. Rewriting all of that under running agents would
+     * change what they had already been told they were called, so a rename is
+     * refused while anything is running here. Stopping an agent is a cheap thing
+     * to ask and an honest one; silently breaking message delivery is not.
+     *
+     * Repointing the folder is not fussy at all: a session records its own cwd
+     * at launch and resume rebuilds from that, so only agents started afterwards
+     * see the new path.
+     */
+    updateWorkspace(id, patch) {
+        const ws = this.store.getWorkspace(id);
+        if (!ws)
+            throw new Error(`unknown workspace ${id}`);
+        const next = {};
+        if (patch.rootPath !== undefined) {
+            const abs = resolve(patch.rootPath);
+            // Only a local folder can be checked from here; a remote one is the
+            // other machine's to know about, exactly as it is on create.
+            if (!ws.hostId && !existsSync(abs)) {
+                throw new Error(`folder does not exist: ${abs}`);
+            }
+            if (abs !== ws.rootPath)
+                next.rootPath = abs;
+        }
+        if (patch.name !== undefined) {
+            const wanted = slugify(patch.name);
+            if (!wanted)
+                throw new Error('a workspace needs a name');
+            if (wanted !== ws.name) {
+                const running = this.sessions.list().filter((s) => s.workspaceId === id);
+                if (running.length > 0) {
+                    throw new Error(`cannot rename while ${running.length} agent${running.length === 1 ? '' : 's'} ` +
+                        'here still exist: the name is part of their addresses. Remove them first.');
+                }
+                if (this.store.getWorkspaceByName(wanted)) {
+                    throw new Error(`a workspace called "${wanted}" already exists`);
+                }
+                next.name = wanted;
+            }
+        }
+        if (next.name === undefined && next.rootPath === undefined)
+            return ws;
+        this.store.updateWorkspace(id, next);
+        const updated = this.store.getWorkspace(id);
+        this.emit('workspace', updated);
+        return updated;
+    }
     async removeWorkspace(id) {
         const ws = this.store.getWorkspace(id);
         for (const s of this.sessions.list().filter((s) => s.workspaceId === id)) {
@@ -184,6 +272,228 @@ export class Hub extends EventEmitter {
         this.store.removeWorkspace(id);
         this.emit('workspaceRemoved', id);
     }
+    /* ----------------------------------------------------------- templates */
+    /**
+     * Create a template or replace one, from the panel.
+     *
+     * Refusals happen here, on the values, before anything is written - which is
+     * the whole reason this carries a requestId. The rules are the loader's own,
+     * called rather than restated: an agent that declares no way to spell a
+     * model or an effort cannot be given one.
+     *
+     * An id `agents.toml` has claimed is refused outright instead of being
+     * stored and then silently losing to the file at load. Storing it would
+     * leave a row in the database that never appears in the list, which is a
+     * worse thing to explain than a dialog that says no.
+     */
+    saveTemplate(input) {
+        const candidate = this.candidateTemplate(input);
+        this.store.upsertTemplate({
+            id: candidate.id,
+            description: candidate.description,
+            agent: candidate.agent,
+            model: candidate.model ?? null,
+            effort: candidate.effort ?? null,
+            prompt: candidate.prompt ?? null,
+            env: candidate.env,
+        });
+        this.reloadTemplates();
+        return this.templates.info().find((t) => t.id === candidate.id);
+    }
+    /**
+     * Everything that can say no about a template, in one place.
+     *
+     * Shared by the panel and by an agent's proposal so the two cannot drift:
+     * an agent should be refused by exactly the rule a human would be, and a
+     * proposal that would fail on accept must fail while the agent is still
+     * there to be told why.
+     */
+    candidateTemplate(input) {
+        const id = slugify(input.id);
+        if (!id)
+            throw new Error('a template needs a name');
+        // `[template.reviewer]` parses as one table called `template`, which is
+        // why that word cannot be a template id any more than it can be an agent.
+        if (id === 'template')
+            throw new Error('"template" is not usable as a name');
+        const existing = this.templates.get(id);
+        if (existing?.source === 'file') {
+            throw new Error(`"${id}" is declared in agents.toml; edit it there, or pick another name`);
+        }
+        const blank = (v) => {
+            const t = v?.trim();
+            return t ? t : undefined;
+        };
+        const candidate = {
+            id,
+            description: blank(input.description) ?? this.profiles.get(input.agent)?.description ?? id,
+            agent: input.agent,
+            model: blank(input.model),
+            effort: blank(input.effort),
+            prompt: blank(input.prompt),
+            // A name with nothing behind it is dropped rather than set to empty:
+            // an exported-but-empty variable reads as set to every program that
+            // checks, which is the opposite of leaving it out.
+            env: Object.fromEntries(Object.entries(input.env ?? {})
+                .map(([k, v]) => [k.trim(), v])
+                .filter(([k, v]) => k.length > 0 && v.length > 0)),
+            source: 'stored',
+        };
+        const problem = validateTemplate(candidate, this.profiles);
+        if (problem)
+            throw new Error(problem);
+        return candidate;
+    }
+    /**
+     * Remove a stored template.
+     *
+     * Nothing running is disturbed, and nothing pretends otherwise: a session
+     * records what its template resolved to precisely so resume cannot drift, so
+     * the agents this one started keep their model, their effort and their
+     * ability to come back. Removing one that shadowed an agent's bare template
+     * reveals that bare one again rather than emptying a row.
+     */
+    removeTemplate(id) {
+        const t = this.templates.get(id);
+        if (!t)
+            throw new Error(`unknown template "${id}"`);
+        if (t.source === 'file') {
+            throw new Error(`"${id}" is declared in agents.toml; remove it there`);
+        }
+        if (t.source === 'derived') {
+            throw new Error(`"${id}" is ${t.agent}'s own template and is not stored`);
+        }
+        this.store.removeTemplate(id);
+        this.reloadTemplates();
+    }
+    /**
+     * Rebuild the merged list and tell everyone.
+     *
+     * Rebuilt rather than patched because the merge is what changed: one write
+     * can alter a row nobody touched - removing a stored template reveals the
+     * derived one under it - and only a fresh load knows that.
+     */
+    reloadTemplates() {
+        this.templates = TemplateRegistry.load(this.profiles, this.store);
+        this.emit('templates', this.templates.info());
+    }
+    /* -------------------------------------------------- template proposals */
+    /** Told by the server, which owns the sockets. */
+    setViewers(n) {
+        this.viewers = n;
+    }
+    pendingProposals() {
+        return [...this.proposals.values()];
+    }
+    /**
+     * An agent asking for a template.
+     *
+     * Everything that can be refused is refused here, before a human is shown
+     * anything: nobody should be asked to approve a template that cannot load.
+     * What survives is put in front of whoever is watching, and the tool returns
+     * at once - a call that blocked until somebody wandered back to the canvas
+     * would be a stalled agent, and MCP clients time out.
+     */
+    async proposeTemplate(sessionId, input) {
+        const me = this.requireSession(sessionId);
+        const mine = [...this.proposals.values()].filter((p) => p.fromAddr === me.address);
+        if (mine.length >= MAX_PENDING_PROPOSALS) {
+            /*
+             * Name them. The way this limit is actually reached is a human closing
+             * the dialog without deciding, which leaves the proposal waiting and the
+             * agent blocked - and an agent that can say *which* templates are stuck
+             * lets them go and answer those, rather than reporting a number nobody
+             * can act on.
+             */
+            throw new Error(`you have ${mine.length} template proposals still waiting on a human: ` +
+                mine.map((p) => `"${p.template.id}"`).join(', ') +
+                '. Tell them those are waiting in the panel, under templates, and that each ' +
+                'can be added or declined there; you cannot propose another until one is ' +
+                'answered.');
+        }
+        // The same checks saveTemplate makes, run now rather than at accept time,
+        // so a refusal reaches the agent that can do something about it instead of
+        // the human who cannot.
+        const candidate = this.candidateTemplate(input);
+        const proposal = {
+            id: randomUUID(),
+            fromAddr: me.address,
+            proposedAt: Date.now(),
+            template: {
+                id: candidate.id,
+                agent: candidate.agent,
+                description: candidate.description ?? null,
+                model: candidate.model ?? null,
+                effort: candidate.effort ?? null,
+                prompt: candidate.prompt ?? null,
+            },
+        };
+        this.proposals.set(proposal.id, proposal);
+        this.emit('templateProposed', proposal);
+        return {
+            proposalId: proposal.id,
+            status: 'awaiting review',
+            anyoneWatching: this.viewers > 0,
+            note: (this.viewers > 0
+                ? 'A human has been shown this and can accept, edit or reject it.'
+                : 'Nobody has the canvas open right now, so nobody has seen it yet; ' +
+                    'it will be shown when someone opens it.') +
+                ` The template "${candidate.id}" does not exist until it is accepted, so do not` +
+                ' try to start an agent from it yet. The answer will be typed into your terminal.',
+        };
+    }
+    /**
+     * A human's answer.
+     *
+     * What is accepted is what the dialog showed rather than what the agent
+     * asked for, because this is a proposal and editing it is the likely path -
+     * so the fields come back with the answer.
+     */
+    resolveTemplateProposal(proposalId, accept, edits = {}) {
+        const proposal = this.proposals.get(proposalId);
+        if (!proposal)
+            throw new Error('that proposal is no longer waiting');
+        if (accept) {
+            // Before removing it: a refusal here - a name the file claimed since,
+            // say - should leave the dialog open with the proposal still live.
+            const saved = this.saveTemplate({ ...proposal.template, ...edits });
+            this.proposals.delete(proposalId);
+            this.emit('templateProposalResolved', proposalId);
+            this.tellAgent(proposal.fromAddr, `Your proposed template was accepted and saved as "${saved.id}"` +
+                (saved.id === proposal.template.id ? '' : ` (you asked for "${proposal.template.id}")`) +
+                `. It launches ${saved.agent}` +
+                [saved.model && `on ${saved.model}`, saved.effort && `at ${saved.effort} effort`]
+                    .filter(Boolean)
+                    .join(' ')
+                    .replace(/^(.)/, ' $1') +
+                '. You can start an agent from it now.');
+            return;
+        }
+        this.proposals.delete(proposalId);
+        this.emit('templateProposalResolved', proposalId);
+        this.tellAgent(proposal.fromAddr, `Your proposed template "${proposal.template.id}" was declined. Do not` +
+            ' propose it again unless you are asked to; carry on with what you were doing.');
+    }
+    /**
+     * A notice from the hub itself, typed into an agent's terminal.
+     *
+     * Its own prefix, deliberately neither `[from <address>]` nor bare text: it
+     * is not a peer talking and it is not the human either, and an agent that
+     * mistook it for one of those would either reply into the void or treat it
+     * as an instruction.
+     */
+    tellAgent(address, text) {
+        const target = this.sessions.getByAddress(address);
+        if (!target)
+            return;
+        const mode = this.profiles.get(target.profile)?.inject ?? 'bracketed';
+        try {
+            this.sessions.write(target.id, encodeInjection(`[termscape] ${text}`, mode));
+        }
+        catch {
+            // The agent is gone. Nothing to tell and nothing to fix.
+        }
+    }
     /* --------------------------------------------------------------- hosts */
     addHost(input) {
         const host = {
@@ -203,6 +513,44 @@ export class Hub extends EventEmitter {
         this.emit('host', host);
         return host;
     }
+    /**
+     * Correct a host's details after the fact.
+     *
+     * Nothing here reconnects: an ssh detail that was wrong is usually being
+     * fixed while the host sits in `error`, and the reconnect is the next thing
+     * the operator does on purpose. Saving and dialling in one step would also
+     * mean a typo in the label re-runs a deploy.
+     */
+    updateHost(hostId, patch) {
+        const host = this.store.getHost(hostId);
+        if (!host)
+            throw new Error(`unknown host ${hostId}`);
+        const ssh = ['sshHost', 'sshUser', 'sshPort', 'privateKeyPath'];
+        if (host.kind !== 'ssh' && ssh.some((k) => patch[k] !== undefined)) {
+            // An enrolled host dialled us and is reached over the socket it opened.
+            // Storing ssh details for it would be storing something nothing reads.
+            throw new Error(`${host.label} joined by itself; it has no ssh details to edit`);
+        }
+        const label = patch.label?.trim();
+        const next = {
+            ...host,
+            label: label || host.label,
+            sshHost: patch.sshHost?.trim() ?? host.sshHost,
+            sshUser: patch.sshUser?.trim() ?? host.sshUser,
+            sshPort: patch.sshPort ?? host.sshPort,
+        };
+        if (next.kind === 'ssh' && (!next.sshHost || !next.sshUser)) {
+            throw new Error('an ssh host needs a user and a host');
+        }
+        this.store.upsertHost({
+            ...next,
+            // upsertHost COALESCEs key_ref, so undefined keeps whatever is stored
+            // and an empty string is the only way to say "back to the ssh agent".
+            keyRef: patch.privateKeyPath === undefined ? null : patch.privateKeyPath.trim(),
+        });
+        this.emit('host', next);
+        return next;
+    }
     /**
      * Drop a host from the canvas, and stop the hub running on it.
      *
@@ -257,33 +605,152 @@ export class Hub extends EventEmitter {
         }
     }
     /* ------------------------------------------------------------ sessions */
+    /**
+     * Turn what the picker sent into an agent, a model and an effort.
+     *
+     * `profile` on the wire is a *template* id, and it is still called profile
+     * because every agent has a bare template under its own name - so the value
+     * a client sent before templates existed still resolves, to the same thing
+     * it always did. Anything the caller passed explicitly beats the template,
+     * which is what makes the dialog's model dropdown an override rather than a
+     * second source of truth.
+     */
+    resolveTemplate(opts) {
+        const t = this.templates.get(opts.profile);
+        if (!t) {
+            // Not a template: an agent id straight from spawn_agent or an older
+            // client. Nothing has been chosen for it, which is today's behaviour.
+            return {
+                agent: opts.profile,
+                template: null,
+                model: opts.model,
+                effort: opts.effort,
+                prompt: opts.prompt,
+            };
+        }
+        if (t.error)
+            throw new Error(`template "${t.id}": ${t.error}`);
+        return {
+            agent: t.agent,
+            template: t.id,
+            model: opts.model ?? t.model,
+            effort: opts.effort ?? t.effort,
+            prompt: opts.prompt ?? t.prompt,
+            env: t.env,
+        };
+    }
     async startSession(opts) {
         const ws = this.store.getWorkspace(opts.workspaceId);
         if (!ws)
             throw new Error(`unknown workspace ${opts.workspaceId}`);
+        const picked = this.resolveTemplate(opts);
         // 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;
+            // Resolved values cross, never the template id: a template is config
+            // and the two machines do not share config, so a name that means "opus,
+            // high effort" here may mean nothing over there. The id travels only so
+            // the window can say which one was picked.
             return this.peers.startSession(ws.hostId, {
                 workspaceName: ws.name,
                 rootPath: ws.rootPath,
-                profile: opts.profile,
+                profile: picked.agent,
+                template: picked.template,
+                model: picked.model,
+                effort: picked.effort,
+                prompt: picked.prompt,
+                // Values, like the model and the effort beside it: the template lives
+                // here and the far side has never heard of it.
+                env: picked.env,
                 name: opts.name,
                 spawnedByAddress: spawner?.address ?? null,
             });
         }
+        return this.startResolved({ ...opts, ...picked });
+    }
+    /**
+     * Start an agent whose template has already been resolved to values.
+     *
+     * Its own entry point because the peer path must not resolve again. A
+     * template is config and the two machines do not share config: if this hub
+     * happened to declare `[template.claude]` with a model, re-resolving an
+     * agent id the canvas sent would apply a choice the canvas never made.
+     */
+    async startResolved(opts) {
         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({
+        const session = await this.sessions.start({
             workspaceId: opts.workspaceId,
-            profileId: opts.profile,
-            name: opts.name,
+            profileId: opts.agent,
+            id: opts.id,
+            template: opts.template ?? null,
+            model: opts.model,
+            effort: opts.effort,
+            env: opts.env,
+            // A window called "reviewer" says more than one called "claude", so the
+            // template names the agent when nothing else did.
+            name: opts.name ?? opts.template ?? undefined,
             cwd: opts.cwd,
             spawnedBy: opts.spawnedBy ?? null,
         });
+        /*
+         * Typed in once the CLI is up rather than written into argv, where it
+         * would be a different thing entirely - and not immediately, because it
+         * would land before the program is reading. Not awaited: the window
+         * should appear now, and the instruction arrives when the agent is ready.
+         *
+         * For an agent whose brief has no flag to ride in on, the brief goes
+         * first, in the same injection rather than a separate one. Two would be
+         * two turns - the agent would answer the brief before being told what to
+         * do, and the second would have to wait out the first.
+         */
+        const opening = [this.typedBrief(session), opts.prompt]
+            .filter((part) => !!part)
+            .join('\n\n');
+        if (opening)
+            void this.deliverOpeningInstruction(session.id, opening);
+        return session;
+    }
+    /**
+     * The brief for an agent that cannot be handed one, or null.
+     *
+     * Read back off disk rather than re-rendered: the wiring wrote exactly this
+     * text a moment ago, and rendering it twice is two chances to render it
+     * differently. A profile with `brief: 'flag'` returns null here because its
+     * argv already carries the path.
+     */
+    typedBrief(session) {
+        const profile = this.profiles.get(session.profile);
+        if (!profile || briefMode(profile) !== 'typed')
+            return null;
+        try {
+            return readFileSync(briefFileFor(session.id), 'utf8');
+        }
+        catch {
+            // The brief is context, not the task. An agent that came up without it
+            // is worse off, not broken, and refusing to start it would be worse.
+            return null;
+        }
+    }
+    /**
+     * Bring a stopped session back, and re-brief it if its brief was typed.
+     *
+     * The re-brief is why this exists rather than callers reaching for
+     * `sessions.resume` directly. A CLI that had to be told where it is by
+     * having text typed at it remembers none of that across a restart, and
+     * neither of the two in that position is resumable in the first place - so
+     * what comes back is a fresh conversation that has never been told it has an
+     * address or any peers.
+     */
+    async resumeSession(sessionId) {
+        const session = await this.sessions.resume(sessionId);
+        const brief = this.typedBrief(session);
+        if (brief)
+            void this.deliverOpeningInstruction(session.id, brief);
+        return session;
     }
     async resumeWorkspace(workspaceId) {
         const out = [];
@@ -293,7 +760,7 @@ export class Hub extends EventEmitter {
             if (s.state === 'running' || s.state === 'starting')
                 continue;
             try {
-                out.push(await this.sessions.resume(s.id));
+                out.push(await this.resumeSession(s.id));
             }
             catch (err) {
                 this.emit('error', new Error(`resume ${s.address}: ${err.message}`));
@@ -330,6 +797,39 @@ export class Hub extends EventEmitter {
      * care whether a peer is on this machine or a remote one; the address is
      * the whole interface.
      */
+    /**
+     * The templates an agent can start something from.
+     *
+     * Exposed because spawn_agent takes a template id and there was no way to
+     * find out what the ids were: an agent could only pass its own profile, or
+     * guess. The environment a template sets is deliberately *not* returned —
+     * knowing that a template exists is what an agent needs to use it, and the
+     * values in there are credentials more often than not.
+     */
+    async listTemplates(sessionId, id) {
+        this.requireSession(sessionId);
+        const shown = this.templates.info().map((t) => ({
+            id: t.id,
+            description: t.description,
+            agent: t.agent,
+            model: t.model,
+            effort: t.effort,
+            prompt: t.prompt,
+            /** Names only, so a template's own config is described but not leaked. */
+            envNames: Object.keys(t.env).sort(),
+            // A template that cannot be used stays in the list saying why, exactly
+            // as it does in the picker: silently omitting it invites an agent to
+            // conclude the name was never configured and propose it again.
+            error: t.error,
+            source: t.source,
+        }));
+        if (id === undefined)
+            return { templates: shown };
+        const one = shown.find((t) => t.id === id);
+        if (!one)
+            throw new Error(`no template "${id}"`);
+        return one;
+    }
     async listAgents(sessionId, workspace) {
         const me = this.requireSession(sessionId);
         const wsById = new Map(this.store.listWorkspaces().map((w) => [w.id, w]));
@@ -478,29 +978,32 @@ export class Hub extends EventEmitter {
             : this.store.getWorkspace(me.workspaceId);
         if (!ws)
             throw new Error(`unknown workspace "${opts.workspace}"`);
+        // The child starts the way its parent did: from the same template, so the
+        // model and effort the template chose are not silently dropped in favour
+        // of the bare agent's defaults. A template that has been deleted or has
+        // since failed to load falls back to the agent itself — a spawn must not
+        // die because config changed under a running parent; a profile the
+        // spawning agent named explicitly always wins.
+        const inherited = me.template ? this.templates.get(me.template) : null;
+        const inherit = opts.profile ?? (inherited && !inherited.error ? me.template : me.profile);
+        /*
+         * One injection, delivered once, by the hub that owns the child's PTY: the
+         * template's opening instruction first, then what the spawning agent asked
+         * for, attributed. Delivering them separately would race two injections on
+         * the same ready-signal, landing back to back in undefined order, so the
+         * opening merges here and rides to the child through startSession — which
+         * also means the remote path needs no delivery of its own.
+         */
+        const templatePrompt = inherit ? (this.templates.get(inherit)?.prompt ?? null) : null;
+        const instruction = opts.prompt ? `[from ${me.address}] ${opts.prompt}` : null;
+        const opening = [templatePrompt, instruction].filter(Boolean).join('\n\n') || undefined;
         const child = await this.startSession({
             workspaceId: ws.id,
-            profile: opts.profile ?? me.profile,
+            profile: inherit,
             name: opts.name,
             spawnedBy: me.id,
+            prompt: opening,
         });
-        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,
@@ -509,11 +1012,24 @@ export class Hub extends EventEmitter {
         };
     }
     /**
-     * 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.
+     * A template's opening instruction, typed in plainly.
+     *
+     * Deliberately without the `[from <address>]` prefix: that is right for a
+     * message from a peer and wrong for an instruction from the human sitting in
+     * front of the canvas. The agent's brief tells it that a `[from ...]` line is
+     * a colleague rather than the human, so wearing that prefix here would be a
+     * lie about who is asking.
+     */
+    async deliverOpeningInstruction(sessionId, prompt) {
+        await this.typeWhenReady(sessionId, prompt);
+    }
+    /**
+     * 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
+     * then pause, which is as close to "it has drawn its prompt" as this gets
+     * without knowing the CLI.
      */
-    async deliverInitialPrompt(sessionId, fromAddr, prompt) {
+    async typeWhenReady(sessionId, text) {
         const pty = this.sessions.pty(sessionId);
         if (!pty)
             return;
@@ -539,7 +1055,7 @@ export class Hub extends EventEmitter {
             return;
         const mode = this.profiles.get(session.profile)?.inject ?? 'bracketed';
         try {
-            this.sessions.write(sessionId, encodeInjection(`[from ${fromAddr}] ${prompt}`, mode));
+            this.sessions.write(sessionId, encodeInjection(text, mode));
         }
         catch {
             // The agent died between the readiness check and the write; the message