termdock 1.3.1 → 1.4.1

package/dist/server/agent/session.js

@@ -0,0 +1,162 @@
+/**
+ * Rich agent session status — the OSC 777 sentinel protocol + per-pane state
+ * machine. （设计移植自 tty7 core/cli_agent.rs，Apache-2.0；TypeScript 重写）
+ *
+ * Agent-side hooks (installed by `installers.ts`, or hand-wired) emit an
+ * OSC 777 notification whose title is AGENT_EVENT_SENTINEL and whose body is
+ * a small JSON event. The server sniffs those out of the PTY stream, folds
+ * them through `applyAgentEvent`, and streams state changes to clients for
+ * status dots, "needs your input" notifications, and session resume.
+ *
+ * Wire shape: `ESC ] 777 ; notify ; termdock://cli-agent ; {"v":1,…} BEL`
+ */
+import { agentBySlug } from './registry.js';
+export const AGENT_EVENT_SENTINEL = 'termdock://cli-agent';
+export const AGENT_EVENT_PROTOCOL_VERSION = 1;
+const EVENT_KINDS = new Set([
+    'session-start', 'prompt-submit', 'permission-request', 'question-asked',
+    'tool-complete', 'notification', 'stop', 'session-end',
+]);
+export function defaultAgentSessionState() {
+    return {
+        status: 'idle',
+        message: null,
+        sessionId: null,
+        launchArgv: null,
+        rich: false,
+        agentCwd: null,
+        activity: 0,
+    };
+}
+/**
+ * Fold one rich event into the state. Pure transition function — the caller
+ * owns *when* to call it and who to tell.
+ */
+export function applyAgentEvent(state, ev) {
+    state.rich = true;
+    if (ev.sessionId)
+        state.sessionId = ev.sessionId;
+    if (ev.cwd)
+        state.agentCwd = ev.cwd;
+    switch (ev.kind) {
+        case 'session-start':
+            state.status = 'idle';
+            state.message = null;
+            break;
+        case 'prompt-submit':
+            state.status = 'working';
+            state.message = null;
+            break;
+        // Explicit blocks from agents that distinguish them (Codex/OpenCode
+        // plugins): always the urgent "needs you" state.
+        case 'permission-request':
+        case 'question-asked':
+            state.status = 'waiting';
+            state.message = ev.message;
+            break;
+        // Claude Code overloads its single Notification hook: it fires *mid-turn*
+        // for a permission/decision prompt (a genuine block), but ALSO *between*
+        // turns as an idle "waiting for your input" reminder — which must not
+        // masquerade as a block. Escalate only when a turn is actually in flight;
+        // keyed on turn phase, not the message text, so it survives version/locale
+        // changes.
+        case 'notification':
+            if (state.status === 'working') {
+                state.status = 'waiting';
+                state.message = ev.message;
+            }
+            break;
+        // A tool call finished. Only meaningful as the recovery edge out of a
+        // block: the user answered the permission prompt, the approved tool ran,
+        // so the turn is moving again — no agent emits an explicit "permission
+        // replied" signal, so the next tool completion is that signal. Guarded on
+        // waiting so the steady stream of completions during normal work is a
+        // no-op and can never overwrite done between turns.
+        case 'tool-complete':
+            // The count moves even when the status doesn't: a tool call is the one
+            // signal that the working tree may have just changed mid-turn.
+            state.activity = (state.activity + 1) >>> 0;
+            if (state.status === 'waiting') {
+                state.status = 'working';
+                state.message = null;
+            }
+            break;
+        case 'stop':
+            state.status = 'done';
+            state.message = ev.message;
+            break;
+        // The agent session ended but its id stays: agents can resume an *ended*
+        // session, which is exactly what restore does. Its cwd claim does NOT
+        // stay: with no agent running, the pane's real directory is the truth.
+        case 'session-end':
+            state.status = 'idle';
+            state.message = null;
+            state.agentCwd = null;
+            break;
+    }
+}
+function nonEmpty(s) {
+    return typeof s === 'string' && s.trim().length > 0 ? s : null;
+}
+/**
+ * Parse a complete OSC payload (identifier included, e.g.
+ * `777;notify;termdock://cli-agent;{"v":1,…}`) into an AgentEvent. Returns
+ * null for anything that isn't a well-formed sentinel event — including
+ * unknown `event` values, so the protocol can grow without old servers
+ * mis-classifying new events.
+ */
+export function parseAgentEvent(payload) {
+    if (!payload.startsWith('777;notify;'))
+        return null;
+    const rest = payload.slice('777;notify;'.length);
+    if (!rest.startsWith(AGENT_EVENT_SENTINEL))
+        return null;
+    const json = rest.slice(AGENT_EVENT_SENTINEL.length);
+    if (!json.startsWith(';'))
+        return null;
+    let w;
+    try {
+        w = JSON.parse(json.slice(1));
+    }
+    catch {
+        return null;
+    }
+    if (!w || typeof w !== 'object')
+        return null;
+    const eventName = nonEmpty(w.event);
+    if (!eventName || !EVENT_KINDS.has(eventName))
+        return null;
+    return {
+        agent: agentBySlug(nonEmpty(w.agent)),
+        kind: eventName,
+        sessionId: nonEmpty(w.session_id),
+        message: nonEmpty(w.message),
+        cwd: nonEmpty(w.cwd),
+    };
+}
+/**
+ * Build the sentinel OSC sequence for one hook invocation — the emitter side,
+ * kept here so tests can round-trip it through `parseAgentEvent`.
+ * `payloadJson` is the hook's raw stdin JSON from the agent; fields are lifted
+ * into the sentinel body (snake_case, with camelCase aliases for Grok).
+ */
+export function buildHookSequence(agent, event, stdinJson) {
+    let payload = {};
+    try {
+        const parsed = JSON.parse(stdinJson);
+        if (parsed && typeof parsed === 'object')
+            payload = parsed;
+    }
+    catch { /* garbage stdin still yields a well-formed bare event */ }
+    const body = {
+        v: AGENT_EVENT_PROTOCOL_VERSION,
+        agent,
+        event,
+    };
+    for (const [key, alias] of [['session_id', 'sessionId'], ['message', 'message'], ['cwd', 'cwd']]) {
+        const v = nonEmpty(payload[key]) ?? nonEmpty(payload[alias]);
+        if (v)
+            body[key] = v;
+    }
+    return `\x1b]777;notify;${AGENT_EVENT_SENTINEL};${JSON.stringify(body)}\x07`;
+}

package/dist/server/agentHook.js

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+/**
+ * termdock agent-hook emitter — the agent-side half of the rich status channel.
+ * （设计移植自 tty7 core/agent_hooks.rs，Apache-2.0；TypeScript/Node 重写）
+ *
+ * Invoked by agent hooks as: `node agentHook.js <agent> <event>`.
+ * Reads the hook's JSON payload from stdin, builds one sentinel OSC 777
+ * sequence, and writes it to the controlling terminal, where the termdock
+ * server sniffs it out of the PTY stream and folds it into the pane's
+ * session state.
+ *
+ * Emission is gated on the TERMDOCK environment variable (injected into every
+ * shell termdock spawns / every managed tmux session), so hooks installed
+ * globally stay silent when an agent runs in another terminal.
+ *
+ * Always exits 0 quietly — a hook that fails must never break the agent's
+ * own flow (agents surface nonzero exits).
+ *
+ * This entry must stay dependency-light (fast cold start): only stdlib +
+ * the pure protocol module.
+ */
+import fs from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { buildHookSequence } from './agent/session.js';
+/** The env var termdock sets in every spawned shell; the emitter refuses to
+ *  write escape sequences into terminals that aren't termdock's. */
+const TERMDOCK_ENV_MARKER = 'TERMDOCK';
+/** Env var Grok Build's hook runner injects into every hook process it spawns.
+ *  Its presence identifies *who ran us* — grok also scans ~/.claude/settings.json
+ *  for hooks (its Claude-compat layer), so a termdock Claude Code integration
+ *  also fires inside grok panes and must be relabeled to the agent that
+ *  actually ran it. */
+const GROK_HOOK_ENV = 'GROK_HOOK_EVENT';
+/** Cap on how much hook stdin we'll read: real payloads are a few hundred
+ *  bytes of JSON; anything huge is not for us. */
+const MAX_STDIN = 64 * 1024;
+/**
+ * The sentinel event one hook invocation maps onto, or null to stay silent.
+ * Most hooks pass their event through; the exceptions are the single catch-all
+ * `notification` hook Copilot and Grok expose, which fires for *every*
+ * notification type. Only the types that always mean a real block escalate to
+ * `permission-request`; everything else is dropped rather than parroted.
+ *
+ * The two agents draw that line differently. Copilot's `permission_prompt`
+ * only fires when it is actually asking, so it counts; grok dispatches the
+ * same type *before* its permission system decides — on essentially every tool
+ * call, auto-approved ones included — so only `elicitation_dialog` (grok
+ * asking the user a question) survives there.
+ */
+function effectiveEvent(agent, event, stdinJson) {
+    if ((agent === 'copilot' || agent === 'grok') && event === 'notification') {
+        const blocks = stdinJson.includes('elicitation_dialog')
+            || (agent === 'copilot' && stdinJson.includes('permission_prompt'));
+        return blocks ? 'permission-request' : null;
+    }
+    return event;
+}
+/** Write raw bytes to a tty device, best-effort. */
+function writeDev(path, bytes) {
+    try {
+        const fd = fs.openSync(path, 'w');
+        try {
+            fs.writeSync(fd, bytes);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The controlling-tty device of the nearest ancestor that has one — the agent
+ * process, when it ran us detached. Claude Code runs hooks *detached* from
+ * the controlling terminal (they have no /dev/tty), but the agent process
+ * itself still owns the pane's PTY slave. Walk up the parent chain via `ps`
+ * (the hook runs at most a few times per turn, so the spawn is negligible).
+ */
+function ancestorTtyDevice() {
+    let pid = process.ppid;
+    for (let i = 0; i < 8 && pid > 1; i++) {
+        let tty = '';
+        let ppid = 1;
+        try {
+            const out = execFileSync('ps', ['-o', 'tty=', '-o', 'ppid=', '-p', String(pid)], {
+                encoding: 'utf8',
+                stdio: ['ignore', 'pipe', 'ignore'],
+                timeout: 2000,
+            });
+            const fields = out.trim().split(/\s+/);
+            tty = fields[0] ?? '';
+            ppid = parseInt(fields[1] ?? '1', 10) || 1;
+        }
+        catch {
+            return null;
+        }
+        if (tty && tty !== '??' && tty !== '?') {
+            return `/dev/${tty}`;
+        }
+        pid = ppid;
+    }
+    return null;
+}
+/**
+ * Write the sequence to the pane's PTY so the server sniffs it as pane output.
+ * Two routes: /dev/tty (hook attached to its tty), or an ancestor's tty
+ * device (agent ran us detached — write its PTY slave directly; writing the
+ * slave sends output to the master, exactly like /dev/tty would).
+ *
+ * Inside tmux the pane's tty is tmux's own PTY slave: a bare OSC would be
+ * consumed by tmux and never reach the attached client. When $TMUX is set we
+ * wrap the sequence in a DCS passthrough, which tmux (with allow-passthrough
+ * enabled, as termdock sets on managed sessions) forwards to its client —
+ * the termdock server — as the plain inner OSC.
+ */
+function writeToControllingTty(sequence, inTmuxPane) {
+    // Only genuine tmux panes (TMUX_PANE is set by tmux itself) get the DCS
+    // passthrough wrap; a bare inherited TMUX just means an ancestor ran tmux.
+    const wire = inTmuxPane
+        ? `\x1bPtmux;${sequence.replace(/\x1b/g, '\x1b\x1b')}\x1b\\`
+        : sequence;
+    if (writeDev('/dev/tty', wire))
+        return true;
+    const dev = ancestorTtyDevice();
+    if (dev)
+        return writeDev(dev, wire);
+    return false;
+}
+function main() {
+    try {
+        // Gate: emit when (a) inside a termdock-spawned shell (TERMDOCK env), or
+        // (b) inside any tmux pane (TMUX+TMUX_PANE) — there the passthrough wrap
+        // self-gates: sessions without allow-passthrough (anything termdock
+        // doesn't manage) swallow the sequence harmlessly. Anything else: stay
+        // silent, so globally-installed hooks don't leak into other terminals.
+        const inTmuxPane = !!(process.env.TMUX && process.env.TMUX_PANE);
+        if (!process.env[TERMDOCK_ENV_MARKER] && !inTmuxPane)
+            return;
+        // Command line: `agentHook.js agent-hook <agent> <event>` — the literal
+        // `agent-hook <slug>` token doubles as the installer's ownership marker.
+        const args = process.argv.slice(2);
+        if (args[0] === 'agent-hook')
+            args.shift();
+        let agent = args[0] ?? '';
+        const eventArg = args[1] ?? '';
+        if (!agent || !eventArg)
+            return;
+        if (process.env[GROK_HOOK_ENV])
+            agent = 'grok';
+        // Hook payload: the agent writes JSON and closes stdin. Absent/malformed
+        // input still emits the bare event — the state machine works without ids
+        // or messages. A tty stdin means the spawner inherited the pane's terminal
+        // instead of piping a payload; reading it would block forever on an EOF
+        // that never comes and swallow the user's keystrokes, so skip it.
+        let input = '';
+        if (!process.stdin.isTTY) {
+            try {
+                input = fs.readFileSync(0, 'utf8').slice(0, MAX_STDIN);
+            }
+            catch { /* no payload */ }
+        }
+        const event = effectiveEvent(agent, eventArg, input);
+        if (!event)
+            return;
+        writeToControllingTty(buildHookSequence(agent, event, input), inTmuxPane);
+    }
+    catch {
+        // Never break the agent's flow.
+    }
+    process.exit(0);
+}
+main();

package/dist/server/cli.js

@@ -145,8 +145,11 @@ Options:
   --change-audit-show <id> [cwd]
                      Print one hunk's diff/context by Termdock hunk ID.
   --change-audit-explain <id> [cwd]
-                     Read a natural-language explanation from stdin and inject
-                     it for the specified Termdock hunk ID.
+                      Read a natural-language explanation from stdin and inject
+                      it for the specified Termdock hunk ID.
+  --agent-plugin-init <slug>
+                      Scaffold a new agent plugin with a manifest template and
+                      guidance. Creates ~/.termdock/agent-plugins/<slug>/.
   -h, --help         Show this help message
 
 Short commands:
@@ -178,6 +181,7 @@ Short commands:
   pc                 Same as --clear-password
   pwc                Same as --clear-password
   https              Same as --setup-local-https
+  ap <slug>          Same as --agent-plugin-init <slug>
 
 Password examples:
   ${c.dim('# Set password interactively (recommended)')}
@@ -465,6 +469,8 @@ function parseArgs(argv) {
     let changeAuditList;
     let changeAuditShow;
     let injectChangeAuditHunk;
+    let agentPluginInit = false;
+    let agentPluginSlug;
     // Short command aliases for the common path. Keep these positional-only so
     // long-form flags remain the single source of truth for option semantics.
     if (argv[0] && !argv[0].startsWith('-')) {
@@ -560,6 +566,11 @@ function parseArgs(argv) {
                 injectChangeAuditHunk = { id: next, cwd };
             argv = argv.slice(cwd ? 3 : 2);
         }
+        else if (command === 'ap' && next && !next.startsWith('-')) {
+            agentPluginInit = true;
+            agentPluginSlug = next;
+            argv = argv.slice(2);
+        }
     }
     for (let index = 0; index < argv.length; index += 1) {
         const arg = argv[index];
@@ -732,6 +743,17 @@ function parseArgs(argv) {
             index += cwd ? 2 : 1;
             continue;
         }
+        if (arg === '--agent-plugin-init') {
+            agentPluginInit = true;
+            const slug = argv[index + 1];
+            if (!slug || slug.startsWith('-')) {
+                console.error(`${ICON.err} ${c.red('--agent-plugin-init requires a slug')}`);
+                process.exit(1);
+            }
+            agentPluginSlug = slug;
+            index += 1;
+            continue;
+        }
         if (!arg.startsWith('-')) {
             if (attachTmux && !attachTmuxName) {
                 attachTmuxName = arg;
@@ -773,6 +795,8 @@ function parseArgs(argv) {
         changeAuditList,
         changeAuditShow,
         injectChangeAuditHunk,
+        agentPluginInit,
+        agentPluginSlug,
     };
 }
 // Reads a single line from stdin without echoing keystrokes. Used for password
@@ -2311,6 +2335,98 @@ async function refreshDefaultHttpsCertificateSafely() {
         return false;
     }
 }
+// ---------------------------------------------------------------------------
+// Agent plugin scaffolding
+// ---------------------------------------------------------------------------
+const VALID_PLUGIN_SLUG_RE = /^[a-z][a-z0-9-]*$/;
+async function runAgentPluginInit(slug) {
+    if (!VALID_PLUGIN_SLUG_RE.test(slug) || slug.length > 40) {
+        console.error(`${ICON.err} ${c.red(`Invalid slug: "${slug}"`)}`);
+        console.error('  Slug must be lowercase alphanumeric with hyphens, 1–40 chars (e.g. "my-agent").');
+        process.exit(1);
+    }
+    const pluginsDir = path.join(os.homedir(), '.termdock', 'agent-plugins');
+    const pluginDir = path.join(pluginsDir, slug);
+    if (fs.existsSync(pluginDir)) {
+        console.error(`${ICON.err} ${c.red(`Plugin "${slug}" already exists at ${pluginDir}`)}`);
+        console.error('  Remove it first or use a different slug.');
+        process.exit(1);
+    }
+    const manifest = {
+        version: 1,
+        slug,
+        displayName: slug, // user should rename
+        aliases: [slug],
+        accentColor: '#4385BE',
+        hooks: {
+            target: `~/.${slug}/settings.json`,
+            events: [
+                { hook: 'SessionStart', event: 'session-start' },
+                { hook: 'UserPromptSubmit', event: 'prompt-submit' },
+                { hook: 'Notification', event: 'notification' },
+                { hook: 'PostToolUse', event: 'tool-complete' },
+                { hook: 'Stop', event: 'stop' },
+                { hook: 'SessionEnd', event: 'session-end' },
+            ],
+        },
+        resume: {
+            command: `${slug} --resume {sessionId}`,
+            staleFlags: ['--resume', '-r', '--session'],
+        },
+    };
+    const iconSvg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="white" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+  <circle cx="12" cy="12" r="10"/>
+  <path d="M12 6v6l4 2"/>
+</svg>
+`;
+    fs.mkdirSync(pluginDir, { recursive: true });
+    fs.writeFileSync(path.join(pluginDir, 'manifest.json'), JSON.stringify(manifest, null, 2), 'utf8');
+    fs.writeFileSync(path.join(pluginDir, 'icon.svg'), iconSvg, 'utf8');
+    console.log(`${ICON.ok} Plugin scaffolded at ${c.cyan(pluginDir)}`);
+    console.log('');
+    console.log(`  ${c.bold('manifest.json')}  — agent identity, aliases, hook events, resume command`);
+    console.log(`  ${c.bold('icon.svg')}     — brand icon (SVG, used as CSS mask)`);
+    console.log('');
+    console.log(c.bold('Next steps:'));
+    console.log('');
+    console.log(`  1. Edit ${c.cyan(`"displayName"`)} — the human-readable label shown in the UI.`);
+    console.log(`  2. Check ${c.cyan(`"aliases"`)} — add all command names your agent uses.`);
+    console.log(`  3. Set ${c.cyan(`"accentColor"`)} to your agent's brand color (hex, e.g. "#FF6600").`);
+    console.log(`  4. Verify ${c.cyan(`"hooks.target"`)} — the path to your agent's own hooks config file.`);
+    console.log(`     Use ${c.dim('~')}-abbreviated absolute paths (e.g. ${c.dim('~/.claude/settings.json')}).`);
+    console.log(`  5. Map ${c.cyan(`"hooks.events"`)} — left side is your agent's event name,`);
+    console.log(`     right side is one of our sentinel events:`);
+    console.log('');
+    console.log('     ' + c.bold('Sentinel events (what they mean):'));
+    console.log(`       ${c.green('session-start')}       — agent session begins (resets state)`);
+    console.log(`       ${c.green('prompt-submit')}        — user sent a prompt (agent starts working)`);
+    console.log(`       ${c.green('permission-request')}   — agent is blocked, needs your approval`);
+    console.log(`       ${c.green('question-asked')}        — agent is blocked, needs your answer`);
+    console.log(`       ${c.green('notification')}         — agent nudged you (only escalates mid-turn)`);
+    console.log(`       ${c.green('tool-complete')}        — a tool finished (recovery from waiting)`);
+    console.log(`       ${c.green('stop')}                 — turn finished, agent idle`);
+    console.log(`       ${c.green('session-end')}          — agent session ended (keeps resume id)`);
+    console.log('');
+    console.log('     Optional per-event fields:');
+    console.log(`       ${c.dim('"matcher"')} — narrow the event by type (e.g. ${c.dim('"elicitation_dialog"')})`);
+    console.log(`       ${c.dim('"timeout"')} — hook timeout in seconds (default: no limit)`);
+    console.log('');
+    console.log(`  6. Replace ${c.cyan('icon.svg')} with your agent's brand icon (SVG, 24×24 viewBox).`);
+    console.log(`     The icon is rendered white-on-brand-color as a CSS mask.`);
+    console.log('');
+    console.log(`  7. Set the ${c.cyan('"resume.command"')} to your agent's session resume command.`);
+    console.log(`     Must contain ${c.dim('{sessionId}')} — replaced with the real id at runtime.`);
+    console.log('');
+    console.log('  After editing, restart termdock to load the plugin:');
+    console.log(`    ${c.cyan('td --stop && td')}`);
+    console.log('');
+    console.log('  Then go to Settings → Agent Hooks to install hooks for your agent.');
+    console.log('');
+    console.log('  For manual plugins from JSON, use the "Add Plugin" panel in Settings.');
+    console.log('');
+    console.log(c.dim('  Built-in agents with hook support live in src/server/agent/installers.ts'));
+    console.log(c.dim('  as a reference for more complex integrations (owned JS/TS files, etc.).'));
+}
 async function main() {
     if (options.setupLocalHttps) {
         try {
@@ -2362,6 +2478,10 @@ async function main() {
         await runInjectChangeAuditHunk(options.injectChangeAuditHunk);
         process.exit(0);
     }
+    if (options.agentPluginInit) {
+        await runAgentPluginInit(options.agentPluginSlug);
+        process.exit(0);
+    }
     if (options.setPassword) {
         await runSetPassword();
         process.exit(0);