@sickr/cli 0.9.3 → 0.9.4

package/dist/cli.js

@@ -12,7 +12,7 @@ import { AUTH_ENDPOINT, readCredentials, writeCredentials, clearCredentials, sta
 import { ui, card, kv } from './ui.js';
 import { AGENT_API_URL, clearAgentCredentials, disconnectAgent, fetchAgentStatus, pollAgentConnect, readAgentCredentials, rotateAgentKey, startAgentConnect, writeAgentCredentials, } from './agentAuth.js';
 const REPLAY_ENDPOINT = process.env.SICKR_REPLAY_ENDPOINT ?? 'https://sickr.ai/api/replay';
-const COMMANDS = ['init', 'record', 'open', 'list', 'share', 'stop', 'clear', 'login', 'logout', 'whoami', 'agent', 'live', 'replay', 'workflow', 'help'];
+const COMMANDS = ['init', 'record', 'open', 'list', 'share', 'stop', 'clear', 'login', 'logout', 'whoami', 'agent', 'live', 'run', 'replay', 'workflow', 'help'];
 export function parseCommand(argv) {
     const c = argv[0];
     return c && COMMANDS.includes(c) ? c : null;
@@ -112,6 +112,16 @@ Legacy replay commands remain supported:
                    replay live stop       stop the sidecar
                  While running, steer messages from the watching browser are
                  saved to ~/.sickr/inbox/<urlid>.md and printed in your terminal.
+  run <agent>    Replay Pro (Phase 2): wrap an agent in a PTY this CLI owns.
+                 Browser steer messages land directly in the agent's stdin —
+                 real remote control, no copy-paste from inbox.
+                   sickr run claude         spawn Claude Code under sickr
+                   sickr run codex          same for Codex
+                   sickr run --cmd <bin>    arbitrary command
+                 \`node-pty\` ships as an optional dep + auto-installs with the
+                 CLI on supported platforms (mac, Linux, Windows 10+).
+                 Browsers can override per-message: {mode:'queue'|'steer',
+                 submit:true|false}; default is auto-steer with submit.
   agent connect --agent-id <id>
                  Connect this machine to a configured SICKR agent using GitHub
                  browser approval. Stores the agent key in ~/.sickr/agent.json.
@@ -978,12 +988,32 @@ async function handleWorkflow(rest) {
     }
     runWorkflow(rest.length ? rest : ['status']);
 }
-async function readStdin() {
+export async function readStreamWithIdle(input, idleMs = 250, emptyMs = 1500) {
     const chunks = [];
-    for await (const chunk of process.stdin)
-        chunks.push(chunk);
+    const iterator = input[Symbol.asyncIterator]();
+    let sawData = false;
+    while (true) {
+        const timeoutMs = sawData ? idleMs : emptyMs;
+        const timeout = new Promise((resolve) => {
+            setTimeout(() => resolve({ done: true, value: undefined }), timeoutMs);
+        });
+        const next = await Promise.race([iterator.next(), timeout]);
+        if (next.done)
+            break;
+        sawData = true;
+        chunks.push(Buffer.isBuffer(next.value) ? next.value : Buffer.from(next.value));
+    }
+    if (typeof iterator.return === 'function') {
+        try {
+            void iterator.return();
+        }
+        catch { /* ignore stream cleanup failures */ }
+    }
     return Buffer.concat(chunks).toString('utf8');
 }
+async function readStdin() {
+    return readStreamWithIdle(process.stdin);
+}
 async function main() {
     const argv = process.argv.slice(2);
     if (argv.length === 0 || argv[0] === 'help' || argv.includes('--help') || argv.includes('-h')) {
@@ -1088,6 +1118,30 @@ async function main() {
             await startLive(opts);
             return;
         }
+        case 'run': {
+            // sickr run <agent> [...agent-args] [--verbose]
+            // Wraps the agent in a PTY the CLI owns. Browser steers go
+            // straight to stdin. node-pty is loaded on first use.
+            const positional = rest.filter((a) => !a.startsWith('-'));
+            const flags = rest.filter((a) => a.startsWith('-'));
+            const agent = positional[0];
+            if (!agent) {
+                process.stderr.write('sickr: usage — `sickr run <agent> [args...]` (agent: claude | codex | <bin name>)\n');
+                process.exit(1);
+                return;
+            }
+            const agentArgs = positional.slice(1);
+            const verbose = flags.includes('--verbose') || flags.includes('-v');
+            const { startRun } = await import('./run.js');
+            try {
+                await startRun({ agent, agentArgs, verbose });
+            }
+            catch (e) {
+                process.stderr.write(`sickr: ${e.message}\n`);
+                process.exit(5);
+            }
+            return;
+        }
         case 'share': {
             const yes = rest.includes('--yes') || rest.includes('-y');
             const openAfter = rest.includes('--open');

package/dist/live.js

@@ -356,7 +356,7 @@ async function loadWsShim() {
         return (mod.default ?? mod.WebSocket);
     }
     catch {
-        throw new Error('Missing optional dep `ws`. Install with: `npm i -g ws` (or `npm i ws` in your project).');
+        throw new Error('`ws` is unavailable. It ships as an optional dependency of @sickr/cli; if it failed to install, try: `npm install -g ws`.');
     }
 }
 export function stopLive() {

package/dist/run.js

@@ -0,0 +1,332 @@
+// `sickr run <agent>` — Phase 2 PTY proxy.
+//
+// Wraps a coding agent (Claude, Codex, anything) in a PTY the CLI owns.
+// Browser steer messages received over the existing WS protocol are
+// written directly into the wrapped agent's stdin as if the operator
+// typed them. Real remote control, not pasteboard.
+//
+// Phase 1 `sickr live` (passive sidecar) is unchanged and still ships.
+// Phase 2 is additive — operators pick: passive watching = `sickr live`,
+// remote control = `sickr run`.
+//
+// Wire protocol (extension to Phase 1):
+//   {kind:'steer', text, mode?:'queue'|'steer', submit?:boolean}
+// - mode='steer' (default when running under PTY)  -> pty.write(text + (submit ? \r : ''))
+// - mode='queue' (default Phase 1)                 -> append to ~/.sickr/inbox/<urlid>.md
+// - submit=true (default for steer)                -> append \r so agent acts immediately
+// - submit=false                                   -> no newline; operator can edit/confirm
+//
+// SICKR_AGENT_BIN_<NAME> env vars override resolution (e.g. CLAUDE_BIN).
+//
+// Native dep: node-pty. Dynamically imported on first use. Missing →
+// friendly install hint; doesn't break `sickr` core install.
+import { readFileSync, writeFileSync, appendFileSync, mkdirSync, existsSync, readdirSync, statSync, openSync, readSync, closeSync, unlinkSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { readCredentials } from './auth.js';
+import { runsDir } from './recorder.js';
+import { LIVE_BASE, decodeWsPayload, splitJsonObjects } from './live.js';
+/** Resolve the agent binary path. `claude` / `codex` look up <NAME>_BIN
+ *  env, else fall through to the bare name on PATH. `--cmd <path>` is
+ *  the escape hatch for arbitrary processes. */
+function resolveAgent(agent) {
+    const envOverride = process.env[`SICKR_AGENT_BIN_${agent.toUpperCase()}`] ?? process.env[`${agent.toUpperCase()}_BIN`];
+    return envOverride || agent;
+}
+/** UTC date YYYY-MM-DD — matches sickr-ui's /api/replay slot id formula. */
+function utcDate(now = new Date()) { return now.toISOString().slice(0, 10); }
+async function computeUrlid(creds, dayHint) {
+    const day = dayHint ?? utcDate();
+    const secret = process.env.SICKR_URLID_SECRET;
+    if (secret) {
+        const { createHash } = await import('node:crypto');
+        return createHash('sha256').update(`urlid|${secret}|${creds.github_user_id}|${day}`).digest('hex').slice(0, 10);
+    }
+    const r = await fetch(`${LIVE_BASE}/resolve?date=${encodeURIComponent(day)}`, {
+        headers: { Authorization: `Bearer ${creds.token}` },
+    });
+    if (!r.ok)
+        throw new Error(`resolve_failed: ${r.status}`);
+    const j = await r.json();
+    if (!j.urlid)
+        throw new Error('resolve_no_urlid');
+    return j.urlid;
+}
+function inboxDir() { return join(homedir(), '.sickr', 'inbox'); }
+/** Append a steer message to the per-urlid inbox markdown file. Same
+ *  shape Phase 1 wrote — operators who relied on the inbox keep working. */
+function appendInbox(urlid, text, at) {
+    const dir = inboxDir();
+    mkdirSync(dir, { recursive: true });
+    const file = join(dir, `${urlid}.md`);
+    if (!existsSync(file))
+        writeFileSync(file, `# steer inbox — ${urlid}\n\n`);
+    appendFileSync(file, `\n## ${at}\n\n${text}\n`);
+}
+export function decideSteer(msg, defaultMode = 'pty') {
+    const text = String(msg.text ?? '');
+    if (!text)
+        return { target: 'inbox' }; // empty steer is a no-op; route to inbox so nothing surprising lands in the agent
+    // Explicit mode wins. 'queue' = inbox. 'steer' = pty. Unknown = default.
+    const mode = msg.mode === 'queue' ? 'inbox' : msg.mode === 'steer' ? 'pty' : defaultMode;
+    if (mode === 'inbox')
+        return { target: 'inbox' };
+    // For PTY: append \r unless submit was explicitly false. Default true
+    // because the whole point of `sickr run` is auto-submit; opt out
+    // requires saying so.
+    const submit = msg.submit !== false;
+    return { target: 'pty', bytes: submit ? text + '\r' : text };
+}
+function offsetsPath() { return join(homedir(), '.sickr', 'run-offsets.json'); }
+function readOffsets() {
+    try {
+        return JSON.parse(readFileSync(offsetsPath(), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+function writeOffsets(o) {
+    mkdirSync(join(homedir(), '.sickr'), { recursive: true });
+    writeFileSync(offsetsPath(), JSON.stringify(o, null, 2));
+}
+/** Read newly-appended lines since `from` byte position. Same defensive
+ *  logic as live.ts::tailFrom but stays local to avoid the cross-file
+ *  export dance. */
+function tailFrom(path, from) {
+    const size = statSync(path).size;
+    if (size <= from)
+        return { lines: [], newOffset: from };
+    const fd = openSync(path, 'r');
+    try {
+        const len = size - from;
+        const buf = Buffer.alloc(len);
+        readSync(fd, buf, 0, len, from);
+        const chunk = buf.toString('utf8');
+        const lastNl = chunk.lastIndexOf('\n');
+        if (lastNl < 0)
+            return { lines: [], newOffset: from };
+        return { lines: chunk.slice(0, lastNl).split('\n').filter(Boolean), newOffset: from + lastNl + 1 };
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** Best-effort load of node-pty. Returns the spawn function or throws
+ *  with a copy-pasteable install hint. */
+async function loadNodePtySpawn() {
+    try {
+        const mod = await import('node-pty');
+        const spawn = mod.spawn ?? mod.default?.spawn;
+        if (!spawn)
+            throw new Error('node-pty has no spawn export');
+        return spawn;
+    }
+    catch (e) {
+        throw new Error('`node-pty` is unavailable. It ships as an optional dependency of\n' +
+            '@sickr/cli and is normally installed automatically — but native\n' +
+            'compilation may have failed at install time. Try installing it\n' +
+            'directly:\n' +
+            '  npm install -g node-pty\n' +
+            '(prebuilt binaries available for macOS, Linux, and Windows 10+;\n' +
+            'uncommon platforms may need a C++ build toolchain.)\n' +
+            `Underlying error: ${e.message ?? 'unknown'}`);
+    }
+}
+export async function startRun(opts) {
+    const creds = readCredentials();
+    if (!creds) {
+        process.stderr.write('sickr: not signed in. Run `npx sickr login` first.\n');
+        process.exit(2);
+    }
+    const ptySpawn = await loadNodePtySpawn();
+    let urlid;
+    try {
+        urlid = await computeUrlid(creds);
+    }
+    catch (e) {
+        process.stderr.write(`sickr: couldn't resolve live url (${e.message}). Replay Pro required.\n`);
+        process.exit(4);
+    }
+    const agentBin = resolveAgent(opts.agent);
+    const cols = process.stdout.columns ?? 80;
+    const rows = process.stdout.rows ?? 24;
+    process.stdout.write(`sickr: wrapping ${agentBin} in PTY. Watch + steer at: https://sickr.ai/r/${urlid}\n`);
+    process.stdout.write(`       browser steer messages land directly in your agent. ^C exits.\n\n`);
+    const pty = ptySpawn(agentBin, opts.agentArgs, {
+        name: 'xterm-256color',
+        cols, rows,
+        cwd: process.cwd(),
+        env: process.env,
+    });
+    // Wire stdio: parent stdin -> pty; pty -> parent stdout.
+    if (process.stdin.isTTY)
+        process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.on('data', (chunk) => pty.write(chunk.toString('utf8')));
+    pty.on('data', (data) => process.stdout.write(data));
+    // Forward terminal resize. SIGWINCH fires when the terminal window changes.
+    const resize = () => pty.resize(process.stdout.columns ?? cols, process.stdout.rows ?? rows);
+    process.stdout.on('resize', resize);
+    // Best-effort SIGWINCH listener on Unix; harmless no-op on Windows.
+    try {
+        process.on('SIGWINCH', resize);
+    }
+    catch { /* not supported */ }
+    // Cleanup on parent signals / pty exit.
+    let cleaned = false;
+    const cleanup = (exitCode) => {
+        if (cleaned)
+            return;
+        cleaned = true;
+        if (process.stdin.isTTY)
+            try {
+                process.stdin.setRawMode(false);
+            }
+            catch { /* ignore */ }
+        try {
+            ws?.close();
+        }
+        catch { /* ignore */ }
+        try {
+            pty.kill();
+        }
+        catch { /* already gone */ }
+        process.exit(exitCode);
+    };
+    process.on('SIGINT', () => { try {
+        pty.write('\x03');
+    }
+    catch { /* ignore */ } }); // Ctrl+C → forward to agent; let agent decide whether to exit
+    process.on('SIGTERM', () => cleanup(0));
+    process.on('SIGHUP', () => cleanup(0));
+    pty.on('exit', (exitCode) => cleanup(exitCode ?? 0));
+    // Open WS to live-service as a pusher. Same auth + url shape as live.ts.
+    const offsets = readOffsets();
+    let ws = null;
+    let backoff = 1000;
+    // Recursive reconnect loop. Runs forever.
+    const runWs = async () => {
+        try {
+            await wsSession();
+            backoff = 1000;
+        }
+        catch (e) {
+            if (opts.verbose)
+                process.stderr.write(`\nsickr: ws disconnect (${e.message}); reconnect in ${backoff}ms\n`);
+            await sleep(backoff);
+            backoff = Math.min(backoff * 2, 30_000);
+        }
+        if (!cleaned)
+            void runWs();
+    };
+    const wsSession = async () => {
+        const wsUrl = `${LIVE_BASE.replace(/^http/, 'ws')}/ws/${urlid}?role=pusher`;
+        const WS = await loadWsShim();
+        ws = new WS(wsUrl, { headers: { Authorization: `Bearer ${creds.token}` } });
+        let tailTimer = null;
+        await new Promise((resolve, reject) => {
+            let opened = false;
+            ws.addEventListener('open', () => {
+                opened = true;
+                tailTimer = setInterval(() => pumpNewLines(ws, offsets), 500);
+            });
+            ws.addEventListener('message', (ev) => {
+                const raw = decodeWsPayload(ev.data);
+                if (opts.verbose)
+                    process.stderr.write(`\nsickr: ws recv ${raw.length}b\n`);
+                let m;
+                try {
+                    m = JSON.parse(raw);
+                }
+                catch {
+                    return;
+                }
+                if (m.kind === 'steer' && m.text) {
+                    const decision = decideSteer(m);
+                    if (decision.target === 'pty' && decision.bytes != null) {
+                        try {
+                            pty.write(decision.bytes);
+                        }
+                        catch { /* PTY may have exited */ }
+                        if (opts.verbose)
+                            process.stderr.write(`sickr: pty steer ${decision.bytes.length}b\n`);
+                    }
+                    else {
+                        appendInbox(urlid, m.text, m.at ?? new Date().toISOString());
+                        if (opts.verbose)
+                            process.stderr.write(`sickr: inbox steer\n`);
+                    }
+                    if (m.id) {
+                        try {
+                            ws.send(JSON.stringify({ kind: 'inbox_ack', message_ids: [m.id] }));
+                        }
+                        catch { /* will retry */ }
+                    }
+                }
+            });
+            ws.addEventListener('close', (ev) => {
+                if (tailTimer)
+                    clearInterval(tailTimer);
+                if (!opened)
+                    reject(new Error(`close_before_open code=${ev.code}`));
+                else
+                    resolve();
+            });
+            ws.addEventListener('error', (ev) => {
+                if (tailTimer)
+                    clearInterval(tailTimer);
+                reject(new Error('ws_error' + (('message' in ev) ? `: ${ev.message ?? ''}` : '')));
+            });
+        });
+    };
+    void runWs();
+    // Block forever — pty drives the lifecycle via 'exit' → cleanup → process.exit.
+    await new Promise(() => { });
+}
+async function loadWsShim() {
+    try {
+        const mod = await import('ws');
+        return (mod.default ?? mod.WebSocket);
+    }
+    catch {
+        throw new Error('`ws` is unavailable. It ships as an optional dependency of @sickr/cli; if it failed to install, try: `npm install -g ws`.');
+    }
+}
+function pumpNewLines(ws, offsets) {
+    const dir = runsDir();
+    if (!existsSync(dir))
+        return;
+    const files = readdirSync(dir).filter((f) => f.endsWith('.ndjson'));
+    for (const f of files) {
+        const runId = f.replace(/\.ndjson$/, '');
+        const path = join(dir, f);
+        const from = offsets[runId] ?? statSync(path).size;
+        let result;
+        try {
+            result = tailFrom(path, from);
+        }
+        catch {
+            continue;
+        }
+        if (result.lines.length === 0) {
+            if (offsets[runId] === undefined)
+                offsets[runId] = from;
+            continue;
+        }
+        for (const line of result.lines) {
+            for (const fragment of splitJsonObjects(line)) {
+                try {
+                    const event = JSON.parse(fragment);
+                    ws.send(JSON.stringify({ kind: 'event', event }));
+                }
+                catch { /* skip malformed */ }
+            }
+        }
+        offsets[runId] = result.newOffset;
+    }
+    writeOffsets(offsets);
+}
+// Unused locals from .live re-export to keep tree-shaking happy.
+void unlinkSync;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sickr/cli",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "type": "module",
   "description": "npx @sickr/cli - replay, live look, and workflow orchestration for AI coding agents.",
   "bin": { "replay": "dist/cli.js", "sickr": "dist/cli.js" },
@@ -14,6 +14,10 @@
   },
   "engines": { "node": ">=20" },
   "license": "UNLICENSED",
+  "optionalDependencies": {
+    "node-pty": "^1.0.0",
+    "ws": "^8.18.0"
+  },
   "devDependencies": {
     "@types/node": "^20.14.0",
     "typescript": "^5.6.2",