@sickr/cli 0.9.2

package/dist/hookConfig.js

@@ -0,0 +1,49 @@
+// PreToolUse (not PostToolUse) captures each tool action once — hooking both
+// would record every tool twice. Stop carries the assistant's final response.
+const EVENTS = ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'Stop'];
+const TAG = 'npx @sickr/cli record';
+const LEGACY_TAGS = ['@sickr/replay record', 'npx sickr record'];
+/**
+ * Merge the SICKR recording hooks into a Claude Code settings object.
+ * Idempotent — re-running never duplicates the SICKR hook. Preserves any
+ * existing unrelated hooks.
+ */
+export function mergeHooks(settings, binPath) {
+    const next = { ...(settings ?? {}) };
+    next.hooks = { ...(next.hooks ?? {}) };
+    for (const ev of EVENTS) {
+        const groups = Array.isArray(next.hooks[ev]) ? [...next.hooks[ev]] : [];
+        const serialized = JSON.stringify(groups);
+        const present = serialized.includes(TAG) || LEGACY_TAGS.some((tag) => serialized.includes(tag));
+        if (!present)
+            groups.push({ hooks: [{ type: 'command', command: `${binPath} record` }] });
+        next.hooks[ev] = groups;
+    }
+    return next;
+}
+/**
+ * Remove the SICKR recording hooks from a Claude Code settings object — the
+ * inverse of mergeHooks. Unrelated hooks are preserved; an event left with no
+ * hooks is dropped so settings.json stays clean.
+ */
+export function removeHooks(settings) {
+    const next = { ...(settings ?? {}) };
+    if (!next.hooks)
+        return next;
+    const hooks = { ...next.hooks };
+    for (const ev of EVENTS) {
+        const groups = Array.isArray(hooks[ev]) ? hooks[ev] : undefined;
+        if (!groups)
+            continue;
+        const kept = groups.filter((g) => {
+            const serialized = JSON.stringify(g);
+            return !serialized.includes(TAG) && !LEGACY_TAGS.some((tag) => serialized.includes(tag));
+        });
+        if (kept.length > 0)
+            hooks[ev] = kept;
+        else
+            delete hooks[ev];
+    }
+    next.hooks = hooks;
+    return next;
+}

package/dist/live.js

@@ -0,0 +1,392 @@
+// `replay live` sidecar — keeps a WebSocket open to sickr-live-service,
+// tails ~/.sickr/runs/*.ndjson for new lines, pushes each line as an event,
+// and writes received steer messages into ~/.sickr/inbox/<urlid>.md so the
+// operator can paste them into their agent's prompt box.
+//
+// Design constraints:
+//   - Hooks MUST stay zero-network. The sidecar is the only network party.
+//     If the sidecar dies, recording still works locally; the operator can
+//     `share` post-session as usual.
+//   - One sidecar per machine. A pid-file in ~/.sickr/live.pid prevents
+//     accidental double-start.
+//   - Auto-reconnect with exponential backoff. The WS will drop on Wi-Fi
+//     changes / sleep; we don't want the operator to babysit it.
+//   - 3-concurrent-agent quota enforced client-side. Server enforces too,
+//     but local enforcement is friendlier (no in-flight rejection).
+//
+// SICKR_LIVE_URL env var lets us point at a dev Worker for testing.
+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';
+export const LIVE_BASE = (process.env.SICKR_LIVE_URL ?? 'https://live-service.sickr.ai').replace(/\/+$/, '');
+function pidPath() { return join(homedir(), '.sickr', 'live.pid'); }
+function inboxDir() { return join(homedir(), '.sickr', 'inbox'); }
+function offsetsPath() { return join(homedir(), '.sickr', 'live-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 bytes [from..size) of a file. Returns lines as strings. */
+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');
+        // The last newline-delimited line might be partial — only consume complete lines.
+        const lastNl = chunk.lastIndexOf('\n');
+        if (lastNl < 0)
+            return { lines: [], newOffset: from };
+        const complete = chunk.slice(0, lastNl);
+        const lines = complete.split('\n').filter(Boolean);
+        return { lines, newOffset: from + lastNl + 1 };
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** UTC date YYYY-MM-DD — matches the server's urlid formula. */
+function utcDate(now = new Date()) { return now.toISOString().slice(0, 10); }
+/** Compute the deterministic urlid for the current user + day.
+ *  Matches sickr-ui's /api/replay and sickr-live-service's auth helper. */
+async function computeUrlid(creds, dayHint) {
+    // The CLI doesn't know URLID_SECRET — we don't ship it client-side.
+    // Instead the CLI asks the server for the current urlid via /snapshot
+    // self-resolution: the server computes urlid from session+date and returns
+    // it. For the bootstrap we use a thin GET to the live service.
+    const day = dayHint ?? utcDate();
+    // The /resolve endpoint isn't part of the spec yet — fall back to asking
+    // the snapshot endpoint for the "auto" urlid. To keep this self-contained,
+    // we'll add a server-side /resolve endpoint mirror; see TODO below.
+    // For now the urlid is hashed locally if SICKR_URLID_SECRET is in env (dev path).
+    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);
+    }
+    // Production path: ask the server.
+    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;
+}
+/** Append a steer line to the per-urlid inbox markdown file. */
+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 async function startLive(opts = {}) {
+    const creds = readCredentials();
+    if (!creds) {
+        process.stderr.write('sickr: not signed in. Run `npx @sickr/cli login` first.\n');
+        process.exit(2);
+    }
+    if (existsSync(pidPath())) {
+        const pid = Number(readFileSync(pidPath(), 'utf8').trim());
+        if (pid && isAlive(pid)) {
+            process.stderr.write(`sickr: live sidecar already running (pid ${pid}). Run \`replay live stop\` first.\n`);
+            process.exit(3);
+        }
+        // Stale pid file from a previous crash.
+        try {
+            unlinkSync(pidPath());
+        }
+        catch { /* ignore */ }
+    }
+    mkdirSync(join(homedir(), '.sickr'), { recursive: true });
+    writeFileSync(pidPath(), String(process.pid));
+    process.on('SIGINT', () => { try {
+        unlinkSync(pidPath());
+    }
+    catch { /**/ } process.exit(0); });
+    process.on('SIGTERM', () => { try {
+        unlinkSync(pidPath());
+    }
+    catch { /**/ } process.exit(0); });
+    if (opts.background) {
+        process.stderr.write('sickr: --background not implemented yet in this build; running foreground.\n');
+    }
+    // Resolve today's urlid up-front so we fail fast on auth / config.
+    let urlid;
+    try {
+        urlid = await computeUrlid(creds);
+    }
+    catch (e) {
+        process.stderr.write(`sickr: couldn't resolve live url (${e.message}). Replay Pro required.\n`);
+        try {
+            unlinkSync(pidPath());
+        }
+        catch { /* ignore */ }
+        process.exit(4);
+    }
+    process.stdout.write(`sickr: live mode active. Watch at: https://sickr.ai/r/${urlid}\n`);
+    process.stdout.write(`       events flow as your agent works. Press ^C to stop.\n`);
+    process.stdout.write(`       steer messages will appear in ~/.sickr/inbox/${urlid}.md\n\n`);
+    await runLoop(creds, urlid, opts);
+}
+/** Main loop: WS reconnect + NDJSON tail polling. Never returns. */
+async function runLoop(creds, urlid, opts) {
+    let backoff = 1000;
+    for (;;) {
+        try {
+            await sessionLoop(creds, urlid, opts);
+            backoff = 1000; // graceful end — reset backoff
+        }
+        catch (e) {
+            if (opts.verbose)
+                process.stderr.write(`sickr: live disconnect: ${e.message}; reconnecting in ${backoff}ms\n`);
+            await sleep(backoff);
+            backoff = Math.min(backoff * 2, 30_000);
+        }
+    }
+}
+async function sessionLoop(creds, urlid, opts) {
+    const wsUrl = `${LIVE_BASE.replace(/^http/, 'ws')}/ws/${urlid}?role=pusher`;
+    // Use the `ws` npm module — node:WebSocket doesn't accept custom headers
+    // (it follows the browser constructor signature) and we need to pass the
+    // Bearer token via Authorization, not a URL query param (which would land
+    // in CF access logs unencrypted).
+    const WS = await loadWsShim();
+    const ws = new WS(wsUrl, { headers: { Authorization: `Bearer ${creds.token}` } });
+    await new Promise((resolve, reject) => {
+        let opened = false;
+        const offsets = readOffsets();
+        let tailTimer = null;
+        ws.addEventListener('open', () => {
+            opened = true;
+            if (opts.verbose)
+                process.stderr.write('sickr: live WS connected\n');
+            tailTimer = setInterval(() => pumpNewLines(ws, offsets, opts), 500);
+        });
+        ws.addEventListener('message', (ev) => {
+            const raw = decodeWsPayload(ev.data);
+            if (opts.verbose)
+                process.stderr.write(`sickr: ws recv (${raw.length}b): ${raw.slice(0, 120)}\n`);
+            let m;
+            try {
+                m = JSON.parse(raw);
+            }
+            catch {
+                return;
+            }
+            if (m.kind === 'steer' && m.text) {
+                const at = m.at ?? new Date().toISOString();
+                appendInbox(urlid, m.text, at);
+                process.stderr.write(`\n▸ steer from viewer @ ${at}\n  ${m.text.split('\n').join('\n  ')}\n  (saved to ~/.sickr/inbox/${urlid}.md)\n\n`);
+                if (m.id) {
+                    try {
+                        ws.send(JSON.stringify({ kind: 'inbox_ack', message_ids: [m.id] }));
+                    }
+                    catch { /* will retry on reconnect */ }
+                }
+            }
+            else if (m.kind === 'watcher_state') {
+                // Quiet — could log "viewer connected/left".
+            }
+        });
+        ws.addEventListener('close', (ev) => {
+            if (tailTimer)
+                clearInterval(tailTimer);
+            if (!opened)
+                reject(new Error(`close_before_open code=${ev.code}`));
+            else
+                resolve(); // normal close → outer loop reconnects with reset backoff
+        });
+        ws.addEventListener('error', (ev) => {
+            if (tailTimer)
+                clearInterval(tailTimer);
+            reject(new Error('ws_error' + (('message' in ev) ? `: ${ev.message ?? ''}` : '')));
+        });
+    });
+}
+/** Read any new lines from each NDJSON in runs/, push them as events. */
+function pumpNewLines(ws, offsets, opts) {
+    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; // first sighting: start at EOF, don't replay history
+        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) {
+            // Tolerant parse: one NDJSON line may contain multiple concatenated
+            // JSON objects if the OS interleaved two appendFileSync writes
+            // (observed on Windows when Claude + Codex hooks fire near-simultaneously).
+            // Split on `}{` boundaries and try each fragment.
+            for (const fragment of splitJsonObjects(line)) {
+                try {
+                    const event = JSON.parse(fragment);
+                    ws.send(JSON.stringify({ kind: 'event', event }));
+                }
+                catch (e) {
+                    if (opts.verbose)
+                        process.stderr.write(`sickr: skipped malformed event fragment (${e.message})\n`);
+                }
+            }
+        }
+        offsets[runId] = result.newOffset;
+    }
+    writeOffsets(offsets);
+}
+/** Split a line that may contain MULTIPLE concatenated JSON objects into
+ *  individual object strings. Defensive splitter that respects quotes +
+ *  escapes (so a `}{` inside a string doesn't split). Used to recover from
+ *  the rare case where two `appendFileSync` writes interleave on the same
+ *  NDJSON file and produce `{...}{...}\n` instead of `{...}\n{...}\n`.
+ *
+ *  Returns `[line]` unchanged for normal single-object lines. Exported for
+ *  test coverage. */
+export function splitJsonObjects(line) {
+    const out = [];
+    let depth = 0;
+    let inString = false;
+    let escape = false;
+    let start = 0;
+    for (let i = 0; i < line.length; i++) {
+        const c = line[i];
+        if (escape) {
+            escape = false;
+            continue;
+        }
+        if (inString) {
+            if (c === '\\')
+                escape = true;
+            else if (c === '"')
+                inString = false;
+            continue;
+        }
+        if (c === '"') {
+            inString = true;
+            continue;
+        }
+        if (c === '{') {
+            if (depth === 0)
+                start = i;
+            depth++;
+        }
+        else if (c === '}') {
+            depth--;
+            if (depth === 0) {
+                out.push(line.slice(start, i + 1));
+            }
+        }
+    }
+    // No braces found at all (or unbalanced)? Return the original line so the
+    // outer JSON.parse can still try (and fail loudly if it's not JSON).
+    if (out.length === 0)
+        return [line];
+    return out;
+}
+/** Decode a WebSocket `MessageEvent.data` payload into a UTF-8 string.
+ *  The browser WebSocket gives strings for text frames; the Node `ws`
+ *  package gives Buffers; some shims give ArrayBuffer/Uint8Array. Reading
+ *  any of those as `typeof === 'string'` silently produces empty JSON,
+ *  which dropped steer messages on the CLI side in 0.9.0-beta.2 (#bug6).
+ *  Always run inbound frames through this. Exported for test coverage. */
+export function decodeWsPayload(data) {
+    if (typeof data === 'string')
+        return data;
+    if (data == null)
+        return '';
+    // Buffer / Uint8Array / ArrayBuffer all expose toString — but ArrayBuffer's
+    // default toString returns "[object ArrayBuffer]", so coerce via Uint8Array.
+    if (data instanceof ArrayBuffer)
+        return Buffer.from(new Uint8Array(data)).toString('utf8');
+    if (ArrayBuffer.isView(data))
+        return Buffer.from(data.buffer, data.byteOffset, data.byteLength).toString('utf8');
+    if (typeof data.toString === 'function') {
+        try {
+            return data.toString('utf8');
+        }
+        catch {
+            return '';
+        }
+    }
+    return '';
+}
+function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function loadWsShim() {
+    try {
+        const mod = await import('ws');
+        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).');
+    }
+}
+export function stopLive() {
+    if (!existsSync(pidPath())) {
+        process.stdout.write('sickr: no live sidecar running.\n');
+        return;
+    }
+    const pid = Number(readFileSync(pidPath(), 'utf8').trim());
+    if (!pid) {
+        try {
+            unlinkSync(pidPath());
+        }
+        catch { /**/ }
+        return;
+    }
+    try {
+        process.kill(pid, 'SIGTERM');
+    }
+    catch { /* already gone */ }
+    try {
+        unlinkSync(pidPath());
+    }
+    catch { /* ignore */ }
+    process.stdout.write(`sickr: stopped live sidecar (pid ${pid}).\n`);
+}
+export function liveStatus() {
+    if (!existsSync(pidPath())) {
+        process.stdout.write('sickr: live not running.\n');
+        return;
+    }
+    const pid = Number(readFileSync(pidPath(), 'utf8').trim());
+    process.stdout.write(`sickr: live sidecar pid=${pid} alive=${pid ? isAlive(pid) : false}\n`);
+}

package/dist/recorder.js

@@ -0,0 +1,154 @@
+import { mkdirSync, appendFileSync, readFileSync, existsSync, readdirSync, statSync, openSync, readSync, closeSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { redact } from './redact.js';
+/**
+ * Best-effort: pull the assistant's final natural-language reply from a Claude
+ * Code transcript (JSONL). Each line is `{type:'assistant', message:{content:[…]}}`
+ * with blocks of type text/thinking/tool_use — we want the last message that has
+ * `text` blocks. Reverse-scans so big transcripts stay cheap. Never throws.
+ */
+export function extractLastAssistantText(transcriptPath) {
+    try {
+        // Read only the tail — the final assistant message is at the end, and CC
+        // transcripts can be tens of MB. Keeps the Stop hook from blocking the agent.
+        const TAIL = 512 * 1024;
+        const size = statSync(transcriptPath).size;
+        let content;
+        if (size <= TAIL) {
+            content = readFileSync(transcriptPath, 'utf8');
+        }
+        else {
+            const fd = openSync(transcriptPath, 'r');
+            try {
+                const buf = Buffer.alloc(TAIL);
+                readSync(fd, buf, 0, TAIL, size - TAIL);
+                content = buf.toString('utf8');
+            }
+            finally {
+                closeSync(fd);
+            }
+        }
+        const lines = content.split('\n');
+        for (let i = lines.length - 1; i >= 0; i--) {
+            const line = lines[i].trim();
+            if (!line)
+                continue;
+            let o;
+            try {
+                o = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            const msg = o && typeof o.message === 'object' && o.message ? o.message : o;
+            const role = (msg && msg.role) || (o && o.type);
+            if (role !== 'assistant')
+                continue;
+            const content = msg && msg.content;
+            if (!Array.isArray(content))
+                continue;
+            const text = content
+                .filter((b) => b && b.type === 'text' && typeof b.text === 'string')
+                .map((b) => b.text)
+                .join('\n')
+                .trim();
+            if (text)
+                return text;
+        }
+    }
+    catch { /* best-effort */ }
+    return '';
+}
+export function runsDir() {
+    return join(homedir(), '.sickr', 'runs');
+}
+/** Render a TodoWrite tool input as a readable checklist. */
+function formatTodos(todos) {
+    const mark = (s) => (s === 'completed' ? '[x]' : s === 'in_progress' ? '[~]' : '[ ]');
+    return todos.map((t) => `${mark(t.status)} ${String(t.content ?? t.activeForm ?? '')}`).join('\n');
+}
+/** Render an AskUserQuestion tool input as question(s) with their options. */
+function formatQuestions(questions) {
+    return questions
+        .map((q) => {
+        const header = q.header ? `[${String(q.header)}] ` : '';
+        const opts = Array.isArray(q.options)
+            ? q.options.map((o) => `  · ${String(o.label ?? '')}`).join('\n')
+            : '';
+        return `${header}${String(q.question ?? '')}${opts ? '\n' + opts : ''}`;
+    })
+        .join('\n\n');
+}
+/**
+ * Map one hook payload (Claude Code OR Codex — same field names) to a redacted
+ * run event. `ctx` supplies the human/agent display labels.
+ */
+export function mapEvent(cc, now = new Date(), ctx = {}) {
+    const at = now.toISOString();
+    const name = String(cc.hook_event_name ?? '');
+    // Carry session_id forward so the renderer can distinguish multiple
+    // parallel Claude/Codex sessions on the same urlid. Short-hash so the
+    // NDJSON stays lean — the renderer only needs identity, not the full id.
+    const rawSession = String(cc.session_id ?? '');
+    const session = rawSession ? rawSession.slice(0, 12) : undefined;
+    const agent = ctx.agent;
+    const base = { at, agent, session };
+    switch (name) {
+        case 'SessionStart':
+            return { kind: 'start', label: 'Session', detail: redact(String(cc.cwd ?? '')), ...base };
+        case 'UserPromptSubmit':
+            return { kind: 'prompt', label: (ctx.human || 'Human').slice(0, 40), detail: redact(String(cc.prompt ?? '')).slice(0, 400), ...base };
+        case 'Stop': {
+            // Codex hands us the reply directly; Claude Code we read from the transcript.
+            const text = String(cc.last_assistant_message ?? '') || (cc.transcript_path ? extractLastAssistantText(String(cc.transcript_path)) : '');
+            return { kind: 'response', label: (ctx.agent || 'Agent').slice(0, 40), detail: redact(text).slice(0, 2000), ...base };
+        }
+        case 'PreToolUse':
+        case 'PostToolUse': {
+            const tool = String(cc.tool_name ?? 'tool');
+            const input = (cc.tool_input ?? {});
+            let raw;
+            if (tool === 'TodoWrite' && Array.isArray(input.todos)) {
+                raw = formatTodos(input.todos);
+            }
+            else if (tool === 'AskUserQuestion' && Array.isArray(input.questions)) {
+                raw = formatQuestions(input.questions);
+            }
+            else {
+                raw = String(input.command ?? input.file_path ?? input.path ?? JSON.stringify(input));
+            }
+            return { kind: 'tool', label: tool, detail: redact(raw).slice(0, 800), ...base };
+        }
+        default:
+            return { kind: 'tool', label: name || 'event', detail: '', ...base };
+    }
+}
+export function appendEvent(runId, cc, ctx = {}) {
+    const dir = runsDir();
+    mkdirSync(dir, { recursive: true });
+    appendFileSync(join(dir, `${runId}.ndjson`), JSON.stringify(mapEvent(cc, new Date(), ctx)) + '\n');
+}
+export function loadRun(runId) {
+    const file = join(runsDir(), `${runId}.ndjson`);
+    const events = existsSync(file)
+        ? readFileSync(file, 'utf8').split('\n').filter(Boolean).map((l) => JSON.parse(l))
+        : [];
+    return {
+        id: runId,
+        cwd: events.find((e) => e.kind === 'start')?.detail ?? '',
+        startedAt: events[0]?.at ?? '',
+        events,
+    };
+}
+/** Most recently modified run id, or null if none. */
+export function latestRunId() {
+    const dir = runsDir();
+    if (!existsSync(dir))
+        return null;
+    const files = readdirSync(dir).filter((f) => f.endsWith('.ndjson'));
+    if (files.length === 0)
+        return null;
+    files.sort((a, b) => statSync(join(dir, b)).mtimeMs - statSync(join(dir, a)).mtimeMs);
+    return files[0].replace(/\.ndjson$/, '');
+}