nexting-cc-bridge 0.8.3

package/dist/transcript-watcher.js

@@ -0,0 +1,138 @@
+// Tail-follows one session JSONL and emits parsed entries as
+// cc_event{kind:"transcript_append"} — the push that replaces the phone's
+// 1.5s full-transcript polling. Works for ALL session flavors (live pty TUI,
+// attach children, local shell) because the jsonl is claude's own record.
+//
+// Pure tail state machine (consumeChunk) is unit-tested; chokidar + a cheap
+// local stat() backstop are the IO glue.
+import fsp from "node:fs/promises";
+import chokidar from "chokidar";
+import { parseTranscript } from "./transcript.js";
+const BACKSTOP_MS = 3000; // fs events can be dropped; stat() locally is cheap
+export function freshTailState() {
+    return { remainder: Buffer.alloc(0), entryIndex: 0 };
+}
+/** Fold appended bytes into the tail state; complete lines → entries.
+ * Byte-level remainder so a UTF-8 char split across reads never garbles. */
+export function consumeChunk(state, chunk, parse = parseTranscript) {
+    const buf = Buffer.concat([state.remainder, chunk]);
+    const lastNl = buf.lastIndexOf(0x0a);
+    if (lastNl === -1) {
+        state.remainder = buf;
+        return { entries: [], startIndex: state.entryIndex };
+    }
+    const complete = buf.subarray(0, lastNl).toString("utf8");
+    state.remainder = Buffer.from(buf.subarray(lastNl + 1));
+    const entries = parse(complete.split("\n"));
+    const startIndex = state.entryIndex;
+    state.entryIndex += entries.length;
+    return { entries, startIndex };
+}
+export function createTranscriptFollower(opts) {
+    const parse = opts.parse ?? parseTranscript;
+    const transform = opts.transform ??
+        (async (entries, _sessionId) => entries);
+    let state = freshTailState();
+    let offset = 0;
+    let watcher = null;
+    let timer = null;
+    let busy = false;
+    async function baseline() {
+        state = freshTailState();
+        offset = 0;
+        try {
+            const st = await fsp.stat(opts.file);
+            const buf = await fsp.readFile(opts.file);
+            consumeChunk(state, buf, parse); // counts entries; baseline never emits
+            offset = st.size;
+        }
+        catch {
+            /* unreadable → counts stay 0; next poke retries */
+        }
+    }
+    async function poke() {
+        if (busy)
+            return; // a slow read must not interleave with the next tick
+        busy = true;
+        try {
+            const st = await fsp.stat(opts.file).catch(() => null);
+            if (!st)
+                return;
+            if (st.size < offset) {
+                // Truncated/rewritten (e.g. compaction) — phone refetches the anchor.
+                await baseline();
+                opts.emit({
+                    type: "cc_event",
+                    sessionId: opts.sessionId,
+                    kind: "transcript_reset",
+                    payload: {},
+                });
+                return;
+            }
+            if (st.size === offset)
+                return;
+            const fh = await fsp.open(opts.file, "r");
+            try {
+                const len = st.size - offset;
+                const buf = Buffer.alloc(len);
+                await fh.read(buf, 0, len, offset);
+                // Snapshot the tail state BEFORE consuming so a dropped emit (socket
+                // mid-reconnect, or closed during the transform await) can be rolled
+                // back in full — offset stays put and the next poke re-reads the same
+                // bytes and re-emits. Previously offset advanced before the emit, so a
+                // frame lost to a closed socket was gone for good and the phone's
+                // spinner spun until the ~4min re-watch reconciled (the "卡住，必须手动
+                // 刷新" bug).
+                const snapRemainder = state.remainder;
+                const snapEntryIndex = state.entryIndex;
+                const { entries, startIndex } = consumeChunk(state, buf, parse);
+                if (entries.length > 0) {
+                    const transformed = await transform(entries, opts.sessionId);
+                    const sent = opts.emit({
+                        type: "cc_event",
+                        sessionId: opts.sessionId,
+                        kind: "transcript_append",
+                        // `total` = authoritative jsonl entry count at emit time. The phone
+                        // uses it as a per-frame cursor: local count < total → it anchors
+                        // the gap immediately instead of waiting for the re-watch heartbeat.
+                        payload: {
+                            startIndex,
+                            entries: transformed,
+                            total: state.entryIndex,
+                        },
+                    });
+                    if (sent === false) {
+                        state.remainder = snapRemainder;
+                        state.entryIndex = snapEntryIndex;
+                        return; // leave offset unadvanced → next poke re-reads & re-emits
+                    }
+                }
+                offset = st.size;
+            }
+            finally {
+                await fh.close();
+            }
+        }
+        finally {
+            busy = false;
+        }
+    }
+    return {
+        start: async () => {
+            await baseline();
+            watcher = chokidar.watch(opts.file, { ignoreInitial: true });
+            watcher.on("change", () => void poke());
+            timer = setInterval(() => void poke(), BACKSTOP_MS);
+            timer.unref?.();
+        },
+        poke,
+        stop: () => {
+            void watcher?.close();
+            watcher = null;
+            if (timer)
+                clearInterval(timer);
+            timer = null;
+        },
+        entryCount: () => state.entryIndex,
+    };
+}

package/dist/transcript.js

@@ -0,0 +1,346 @@
+import { mediaFromImageBlock, mediaFromLocalPath } from "./media-hydrator.js";
+const TEXT_CAP = 16 * 1024;
+const RECENT_TEXT_CAP = 2000;
+const RECENT_LIMIT = 20;
+function parseLine(line) {
+    const s = line.trim();
+    if (!s)
+        return null;
+    try {
+        return JSON.parse(s);
+    }
+    catch {
+        return null;
+    }
+}
+function capText(text) {
+    if (text.length <= TEXT_CAP)
+        return { text };
+    return {
+        text: text.slice(0, TEXT_CAP),
+        truncatedChars: text.length - TEXT_CAP,
+    };
+}
+/** tool_result content can be a string or an array of text blocks. */
+function toolResultText(content) {
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content)) {
+        return content
+            .map((b) => (typeof b === "string" ? b : (b?.text ?? "")))
+            .join("");
+    }
+    return "";
+}
+/** Claude Code writes a user entry starting with this marker when Esc aborts a
+ * turn after output started ("[Request interrupted by user]" / "…for tool use]"). */
+const INTERRUPT_MARKER = "[Request interrupted";
+function isInterruptText(text) {
+    return typeof text === "string" && text.startsWith(INTERRUPT_MARKER);
+}
+/**
+ * True when a user message is purely Claude Code's Esc-interrupt marker:
+ * string content starting with the marker, or block content whose text block(s)
+ * all start with the marker — with NO tool_result blocks (a tool_result means
+ * real turn data the phone must still see). Per-line/stateless on purpose so the
+ * full-file parse (scanner.readFullTranscript) and the incremental watcher
+ * (transcript-watcher consumeChunk) map identical entry sequences and indexes.
+ */
+function isAbortedUserContent(content) {
+    if (typeof content === "string")
+        return isInterruptText(content);
+    if (!Array.isArray(content))
+        return false;
+    let sawInterruptText = false;
+    for (const b of content) {
+        if (typeof b !== "object" || b === null)
+            continue;
+        if (b.type === "tool_result")
+            return false;
+        if (b.type === "text") {
+            if (!isInterruptText(b.text))
+                return false;
+            sawInterruptText = true;
+        }
+    }
+    return sawInterruptText;
+}
+/** Concatenate the human-readable text from a message's content blocks. */
+function blocksToText(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    const parts = [];
+    for (const b of content) {
+        if (typeof b !== "object" || b === null)
+            continue;
+        switch (b.type) {
+            case "text":
+                parts.push(b.text ?? "");
+                break;
+            case "thinking":
+                parts.push(b.thinking ?? "");
+                break;
+            case "tool_use":
+                parts.push(`[tool_use: ${b.name}]`);
+                break;
+            case "tool_result":
+                parts.push(toolResultText(b.content));
+                break;
+            case "image":
+                parts.push("[image]");
+                break;
+        }
+    }
+    return parts.join(" ").trim();
+}
+/** Rebuild the full kind-tagged timeline from raw JSONL lines (for the read-only viewer). */
+export function parseTranscript(lines) {
+    const out = [];
+    for (const line of lines) {
+        const o = parseLine(line);
+        if (!o)
+            continue;
+        const ts = o.timestamp ?? null;
+        if (o.type === "system") {
+            out.push({ kind: "system", subtype: o.subtype, timestamp: ts });
+            continue;
+        }
+        if (o.type !== "user" && o.type !== "assistant")
+            continue;
+        const role = o.type;
+        const content = o.message?.content;
+        // Esc-interrupt marker → a system/turn_aborted entry INSTEAD of user_text,
+        // so the phone's shape-derived spinner knows the turn is over (a trailing
+        // user_text would read as "user spoke, turn still running").
+        if (role === "user" && isAbortedUserContent(content)) {
+            out.push({ kind: "system", subtype: "turn_aborted", timestamp: ts });
+            continue;
+        }
+        if (typeof content === "string") {
+            const c = capText(content);
+            out.push({
+                kind: role === "user" ? "user_text" : "assistant_text",
+                timestamp: ts,
+                ...c,
+            });
+            continue;
+        }
+        if (!Array.isArray(content))
+            continue;
+        const outputTokens = role === "assistant" ? o.message?.usage?.output_tokens : undefined;
+        for (const b of content) {
+            if (typeof b !== "object" || b === null)
+                continue;
+            switch (b.type) {
+                case "text":
+                    out.push({
+                        kind: role === "user" ? "user_text" : "assistant_text",
+                        timestamp: ts,
+                        ...(typeof outputTokens === "number" ? { outputTokens } : {}),
+                        ...capText(b.text ?? ""),
+                    });
+                    break;
+                case "thinking":
+                    out.push({
+                        kind: "thinking",
+                        timestamp: ts,
+                        ...capText(b.thinking ?? ""),
+                    });
+                    break;
+                case "tool_use":
+                    out.push({
+                        kind: "tool_use",
+                        timestamp: ts,
+                        name: b.name,
+                        inputJson: JSON.stringify(b.input ?? {}),
+                    });
+                    break;
+                case "tool_result": {
+                    const c = capText(toolResultText(b.content));
+                    const toolUseId = typeof b.tool_use_id === "string" ? b.tool_use_id : undefined;
+                    out.push({
+                        kind: "tool_result",
+                        timestamp: ts,
+                        toolUseId,
+                        isError: !!b.is_error,
+                        ...c,
+                    });
+                    const filePath = o.tool_use_result?.file?.filePath;
+                    if (typeof filePath === "string") {
+                        const media = mediaFromLocalPath(filePath);
+                        if (media) {
+                            out.push({
+                                kind: "image",
+                                timestamp: ts,
+                                toolUseId,
+                                media,
+                            });
+                        }
+                    }
+                    break;
+                }
+                case "image": {
+                    const media = mediaFromImageBlock(b);
+                    out.push({
+                        kind: "image",
+                        timestamp: ts,
+                        ...(media ? { media } : {}),
+                    });
+                    break;
+                }
+            }
+        }
+    }
+    return out;
+}
+/** True when a user row only carries tool_result blocks back to the model —
+ * turn internals, not a message the user typed. */
+function isToolResultCarrier(content) {
+    return (Array.isArray(content) &&
+        content.some((b) => typeof b === "object" && b !== null && b.type === "tool_result"));
+}
+/** THE counting rule, shared by summarize() (windowed fallback) and the exact
+ * incremental message counter — one parsed jsonl entry advances the state.
+ * A message = a real user message (not tool_result carrier / Esc-interrupt /
+ * isMeta injection) or the start of an assistant turn (chunks merge; meta and
+ * tool_result rows do not break a turn). */
+export function ccCountEntry(o, st) {
+    if (o?.type === "user") {
+        const c = o.message?.content;
+        if (!o.isMeta && !isToolResultCarrier(c) && !isAbortedUserContent(c)) {
+            st.messages++;
+            st.inAssistantTurn = false;
+        }
+    }
+    else if (o?.type === "assistant") {
+        if (!st.inAssistantTurn) {
+            st.messages++;
+            st.inAssistantTurn = true;
+        }
+    }
+}
+/** Raw-line reducer for createMessageCounter (claude engine). */
+export function ccCountReducer(line, st) {
+    const o = parseLine(line);
+    if (o)
+        ccCountEntry(o, st);
+}
+/** Slice by Unicode code points — safer than UTF-16 .slice (no split surrogates).
+ *  Grapheme clusters (e.g. ZWJ emoji sequences) may still split; acceptable for titles. */
+function sliceCodePoints(text, max) {
+    return [...text].slice(0, max).join("");
+}
+/** Strip Claude Code's UI hint suffix from an away_summary recap. */
+function cleanRecap(content) {
+    return content.replace(/\s*\(disable recaps in \/config\)\s*$/, "").trim();
+}
+/**
+ * Derive a list-row title from a user message, together with its source kind.
+ * Slash-command wrappers become "/name" with source "command";
+ * local-command caveats yield null so the next real message is tried;
+ * plain text returns the text with source "user-text".
+ */
+export function titleFromUserText(text) {
+    const name = text.match(/<command-name>\s*(\/?[\w:-]+)\s*<\/command-name>/)?.[1] ??
+        text.match(/<command-message>\s*([\w:-]+)/)?.[1];
+    if (name)
+        return {
+            title: name.startsWith("/") ? name : "/" + name,
+            source: "command",
+        };
+    if (text.startsWith("<local-command-caveat>"))
+        return null;
+    return { title: text, source: "user-text" };
+}
+/** Derive the lightweight list-row fields from JSONL lines. */
+export function summarize(lines) {
+    const entries = lines.map(parseLine).filter(Boolean);
+    let title = null;
+    let titleSource = null;
+    let cwd = null;
+    let firstMessageAt = null;
+    let lastAgentMessageAt = null;
+    const countState = { messages: 0, inAssistantTurn: false };
+    let recap = null;
+    const recent = [];
+    for (const o of entries) {
+        if (o.type === "ai-title" && o.aiTitle && !title) {
+            title = o.aiTitle;
+            titleSource = "ai-title";
+        }
+        if (cwd === null && typeof o.cwd === "string")
+            cwd = o.cwd;
+        if (o.type === "system" &&
+            o.subtype === "away_summary" &&
+            typeof o.content === "string") {
+            const cleaned = cleanRecap(o.content);
+            if (cleaned)
+                recap = cleaned; // latest one wins
+        }
+        if (o.type === "user" || o.type === "assistant") {
+            ccCountEntry(o, countState);
+            const ts = o.timestamp ?? null;
+            if (firstMessageAt === null)
+                firstMessageAt = ts;
+            if (o.type === "assistant" && ts)
+                lastAgentMessageAt = ts;
+            const text = blocksToText(o.message?.content);
+            if (title === null && o.type === "user" && text) {
+                const derived = titleFromUserText(text);
+                if (derived) {
+                    title = sliceCodePoints(derived.title, 120);
+                    titleSource = derived.source;
+                }
+            }
+            recent.push({
+                role: o.message?.role ?? o.type,
+                text: text.slice(0, RECENT_TEXT_CAP),
+                timestamp: ts,
+            });
+        }
+    }
+    const recentMessages = recent.slice(-RECENT_LIMIT);
+    const summary = recentMessages.length > 0
+        ? recentMessages[recentMessages.length - 1].text
+            .replace(/\s+/g, " ")
+            .slice(0, 200)
+        : null;
+    return {
+        title,
+        titleSource,
+        cwd,
+        firstMessageAt,
+        lastAgentMessageAt,
+        totalMessages: countState.messages,
+        summary,
+        recap,
+        recentMessages,
+    };
+}
+/**
+ * Merge head- and tail-window summaries of one session file.
+ * The freshest recap (Claude Code's live away_summary) wins the title slot —
+ * it tracks the whole conversation, unlike the first user message.
+ */
+export function combineSummaries(headSum, tailSum) {
+    const recap = tailSum.recap ?? headSum.recap;
+    return {
+        title: recap ?? headSum.title ?? tailSum.title,
+        titleSource: recap
+            ? "recap"
+            : headSum.title
+                ? headSum.titleSource
+                : tailSum.titleSource,
+        cwd: headSum.cwd ?? tailSum.cwd,
+        firstMessageAt: headSum.firstMessageAt,
+        lastAgentMessageAt: tailSum.lastAgentMessageAt ?? headSum.lastAgentMessageAt,
+        totalMessages: Math.max(headSum.totalMessages, tailSum.totalMessages),
+        summary: tailSum.summary ?? headSum.summary,
+        recap,
+        recentMessages: tailSum.recentMessages.length
+            ? tailSum.recentMessages
+            : headSum.recentMessages,
+    };
+}

package/dist/turn-probe.js

@@ -0,0 +1,152 @@
+// PTY turn-activity probe. Covers the Esc-before-output abort case the jsonl
+// can NEVER show: pressing Esc before any assistant output writes nothing to the
+// session file, so the phone's shape-derived spinner spins until its watchdog.
+//
+// Mechanism: the engine's TUI prints a "running marker" (e.g. "esc to interrupt")
+// in its status line while a turn is in flight. For every hub term bound to a
+// sessionId we substring-match each raw pty output chunk (ANSI-stripped,
+// case-insensitive, with a small tail carry so a marker split across chunks
+// still matches). Marker seen → armed + latched running (emit term_turn
+// running:true on the transition).
+//
+// Idle detection is OUTPUT QUIESCENCE, not marker recency. Empirical (claude
+// 2.1.170 in a real pty): the TUI uses incremental diff repaints — the marker
+// string is painted ONCE when the spinner line first renders; subsequent
+// animation ticks repaint only the changed chars (verb/seconds/tokens). So a
+// marker-recency timeout would false-idle every turn longer than the window.
+// But while a turn is genuinely running the pty is never quiet (spinner seconds
+// repaint at least every ~1s; observed max gap 0.94s over 30s), and after Esc
+// (or a normal turn end) output goes COMPLETELY silent. Hence: ANY output chunk
+// on the term refreshes lastOutputAt; the sweep latches idle and emits
+// term_turn running:false only after QUIET_MS of total pty silence (>8x margin
+// vs the ~1s running repaint cadence).
+//
+// Note: a turn that ends NORMALLY also goes silent, so running:false is emitted
+// ~QUIET_MS after completion too — correct and harmless: the phone gates on its
+// own shape-derived working state and only uses this as an abort/death signal.
+//
+// Liveness heartbeat: while latched running, the sweep RE-EMITS running:true
+// every HEARTBEAT_MS. This is the only true "still alive" signal the phone can
+// get during a long single-turn generation that writes nothing to jsonl (e.g.
+// building one big report): the TUI's token counter / spinner are local repaints
+// that never reach the phone, so without this the phone's no-progress watchdog
+// (180s) false-kills a live session as "stopped". The heartbeat is a TRUE
+// signal — a dead/finished turn goes pty-silent within QUIET_MS and latches idle
+// FIRST, so a heartbeat only ever fires while output is genuinely churning.
+//
+// Arm-on-sighting by design: if the CLI ever changes its TUI strings the probe
+// simply never arms — silent no-op, zero false positives. running:false is
+// NEVER emitted unless a marker was seen at least once on this term.
+//
+// Frame contract (rides the same cc_event path as the transcript watcher; the
+// cloud relays unknown cc_event kinds transparently):
+//   { type:"cc_event", sessionId, kind:"term_turn", payload:{ running:boolean } }
+const QUIET_MS = 8000; // total pty output silence → turn considered over
+const SWEEP_MS = 2500; // idle-latch scan cadence
+const HEARTBEAT_MS = 30000; // re-emit running:true this often while latched running
+/** Strip ANSI CSI/OSC escape sequences — TUI redraws interleave them with text. */
+export function stripAnsi(s) {
+    return s
+        .replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)?/g, "") // OSC
+        .replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, "") // CSI
+        .replace(/\x1b[@-Z\\-_]/g, ""); // 2-char escapes
+}
+export function createTurnProbe(opts) {
+    const markers = opts.markers.map((m) => m.toLowerCase()).filter(Boolean);
+    const maxMarkerLen = markers.reduce((a, m) => Math.max(a, m.length), 0);
+    const quietMs = opts.quietMs ?? QUIET_MS;
+    const heartbeatMs = opts.heartbeatMs ?? HEARTBEAT_MS;
+    const now = opts.now ?? Date.now;
+    const terms = new Map();
+    function emitTurn(sessionId, running) {
+        opts.emit({
+            type: "cc_event",
+            sessionId,
+            kind: "term_turn",
+            payload: { running },
+        });
+    }
+    const sweep = setInterval(() => {
+        const t = now();
+        for (const st of terms.values()) {
+            if (!st.armed || st.latched !== "running")
+                continue;
+            if (t - st.lastOutputAt > quietMs) {
+                st.latched = "idle";
+                emitTurn(st.sessionId, false);
+            }
+            else if (t - st.lastRunningEmitAt >= heartbeatMs) {
+                // pty still churning (not yet quiet) → session is demonstrably alive.
+                // Re-emit running:true so the phone's no-progress watchdog resets.
+                st.lastRunningEmitAt = t;
+                emitTurn(st.sessionId, true);
+            }
+        }
+    }, opts.sweepMs ?? SWEEP_MS);
+    sweep.unref?.();
+    return {
+        noteTermHello(termId, sessionId) {
+            if (!sessionId)
+                return; // unbound term (e.g. bare mirror) — nothing to attribute to
+            const existing = terms.get(termId);
+            if (existing) {
+                existing.sessionId = sessionId; // re-reg after a shell reconnect; keep probe state
+                return;
+            }
+            terms.set(termId, {
+                sessionId,
+                armed: false,
+                lastOutputAt: 0,
+                latched: null,
+                tail: "",
+                lastRunningEmitAt: 0,
+            });
+        },
+        noteOutput(termId, dataBase64) {
+            if (markers.length === 0)
+                return;
+            const st = terms.get(termId);
+            if (!st)
+                return; // not bound to a session
+            let text;
+            try {
+                text = Buffer.from(dataBase64, "base64").toString("utf8");
+            }
+            catch {
+                return;
+            }
+            // ANY output (marker or not) counts as turn activity — the TUI's diff
+            // repaints stop painting the marker after the first render, but never
+            // stop ticking the spinner while a turn runs.
+            st.lastOutputAt = now();
+            const hay = st.tail + stripAnsi(text).toLowerCase();
+            st.tail = hay.slice(-(maxMarkerLen - 1));
+            if (!markers.some((m) => hay.includes(m)))
+                return;
+            st.armed = true;
+            if (st.latched !== "running") {
+                st.latched = "running";
+                st.lastRunningEmitAt = now();
+                emitTurn(st.sessionId, true);
+            }
+        },
+        noteTermBye(termId) {
+            terms.delete(termId);
+        },
+        reemitForSession(sessionId) {
+            for (const st of terms.values()) {
+                if (st.sessionId !== sessionId)
+                    continue;
+                if (st.armed && st.latched !== null) {
+                    if (st.latched === "running")
+                        st.lastRunningEmitAt = now();
+                    emitTurn(st.sessionId, st.latched === "running");
+                }
+            }
+        },
+        stop() {
+            clearInterval(sweep);
+            terms.clear();
+        },
+    };
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+// Shared data model — mirrors LoopWeave's SessionInfo, trimmed to read-only v1.
+export {};