gipity 1.0.410 → 1.0.412

package/dist/relay/ingest-queue.js

@@ -0,0 +1,148 @@
+const DEFAULTS = {
+    maxEntries: 2000,
+    maxBytes: 8 * 1024 * 1024,
+    batchMax: 200,
+    backoffMs: [2000, 5000, 15000, 60000],
+};
+function entryBytes(e) {
+    try {
+        return JSON.stringify(e).length;
+    }
+    catch {
+        return 1024;
+    }
+}
+export class IngestQueue {
+    post;
+    queue = [];
+    bytes = 0;
+    draining = false;
+    closed = false;
+    closeDeadline = 0;
+    drainDone = Promise.resolve();
+    droppedTotal = 0;
+    markedDrop = false;
+    opts;
+    constructor(post, opts = {}) {
+        this.post = post;
+        this.opts = { ...DEFAULTS, ...opts };
+    }
+    get dropped() {
+        return this.droppedTotal;
+    }
+    /** Enqueue entries in order and kick the drainer. Sync and non-blocking. */
+    push(...entries) {
+        if (this.closed) {
+            this.opts.onWarn?.('ingest queue push after close - dropped', { count: entries.length });
+            this.droppedTotal += entries.length;
+            return;
+        }
+        for (const entry of entries) {
+            const bytes = entryBytes(entry);
+            this.queue.push({ entry, bytes });
+            this.bytes += bytes;
+        }
+        this.enforceBounds();
+        this.kick();
+    }
+    /** Stop accepting entries and drain what's left, giving up at the
+     *  deadline. Returns whether everything flushed. */
+    async close(deadlineMs = 30_000) {
+        this.closed = true;
+        this.closeDeadline = Date.now() + deadlineMs;
+        this.kick();
+        // Await until the drainer has fully settled. The re-kick in `kick`'s
+        // finally is gated on `!closed`, so once we're here no NEW drain can
+        // start - a single settled await is sufficient, but loop defensively
+        // in case a kick was mid-settle when `closed` flipped.
+        while (this.draining)
+            await this.drainDone;
+        await this.drainDone;
+        const flushed = this.queue.length === 0;
+        if (!flushed) {
+            this.droppedTotal += this.queue.length;
+            this.opts.onWarn?.('ingest queue close deadline hit - entries lost', { remaining: this.queue.length });
+            this.queue = [];
+            this.bytes = 0;
+        }
+        return { flushed, dropped: this.droppedTotal };
+    }
+    enforceBounds() {
+        let droppedNow = 0;
+        while (this.queue.length > this.opts.maxEntries || this.bytes > this.opts.maxBytes) {
+            const victim = this.queue.shift();
+            if (!victim)
+                break;
+            this.bytes -= victim.bytes;
+            droppedNow++;
+        }
+        if (droppedNow > 0) {
+            this.droppedTotal += droppedNow;
+            this.opts.onWarn?.('ingest queue overflow - oldest entries dropped', { droppedNow, droppedTotal: this.droppedTotal });
+            if (!this.markedDrop) {
+                this.markedDrop = true;
+                // Visible gap marker, placed at the head so it lands before the
+                // surviving (newer) entries.
+                const marker = { kind: 'system', content: 'Some session output could not be uploaded (upload backlog overflowed).' };
+                this.queue.unshift({ entry: marker, bytes: entryBytes(marker) });
+                this.bytes += entryBytes(marker);
+            }
+        }
+    }
+    kick() {
+        if (this.draining)
+            return;
+        this.draining = true;
+        this.drainDone = this.drain().finally(() => {
+            this.draining = false;
+            // Entries may have arrived while the final await of drain() settled.
+            // Never re-kick once closed: close() owns the last drain, and a
+            // re-kick here would POST a batch AFTER close() returned (the
+            // zombie-drain bug - post-after-ack + corrupted byte accounting).
+            if (this.queue.length && !this.closed)
+                this.kick();
+        });
+    }
+    async drain() {
+        const sleep = this.opts.sleep ?? ((ms) => new Promise(r => setTimeout(r, ms)));
+        let attempt = 0;
+        while (this.queue.length) {
+            // Remove the batch from the queue BEFORE awaiting the POST. A push
+            // that overflows the bounds during the await runs `enforceBounds`,
+            // which shifts the queue head - if the in-flight batch were still
+            // at the head, a later splice-by-index would remove the wrong
+            // entries and drift `bytes`. Holding the batch out of the queue
+            // makes overflow touch only not-in-flight entries.
+            const batch = this.queue.splice(0, this.opts.batchMax);
+            const batchBytes = batch.reduce((n, b) => n + b.bytes, 0);
+            this.bytes -= batchBytes;
+            const result = await this.post(batch.map(b => b.entry));
+            if (result.ok) {
+                attempt = 0;
+                continue;
+            }
+            // Definitive rejection (4xx: schema or auth) - a replay can never
+            // succeed, and retrying would stall the queue behind a poisoned
+            // batch. Drop it (counted + warned) and move on.
+            if (result.retryable === false) {
+                attempt = 0;
+                this.droppedTotal += batch.length;
+                this.opts.onWarn?.('ingest batch rejected by server - dropped', { count: batch.length });
+                continue;
+            }
+            // Transient failure: put the batch back at the head and retry after
+            // backoff (order preserved; source_uuid dedup makes a partial
+            // server-side success safe).
+            this.queue.unshift(...batch);
+            this.bytes += batchBytes;
+            const backoff = this.opts.backoffMs[Math.min(attempt, this.opts.backoffMs.length - 1)];
+            attempt++;
+            if (this.closed && Date.now() + backoff > this.closeDeadline)
+                return;
+            await sleep(backoff);
+            if (this.closed && Date.now() > this.closeDeadline)
+                return;
+        }
+    }
+}
+//# sourceMappingURL=ingest-queue.js.map

package/dist/relay/onboarding.js

@@ -1,13 +1,20 @@
 /**
- * One-time first-run relay onboarding. Called from `gipity claude` after
- * auth + project selection. Asks up to four Y/n questions (all default Y);
- * pressing Enter four times leaves the user with a paired + running
- * daemon that auto-starts on every subsequent `gipity claude` invocation,
- * and - if they said yes to the last question - also starts at OS login.
+ * Interactive relay setup — the single flow that pairs this computer as a
+ * relay, starts the daemon, and (optionally) installs the OS login service.
+ * ONE implementation, shared by both entry points:
+ *
+ *   - `gipity claude`  → `maybeOfferRelayOn()`  (mode 'offer-once': runs on the
+ *                        very first launch, then never nags again).
+ *   - `gipity setup`   → `runRelaySetup({ mode: 'run-now' })` (the user asked
+ *                        for it explicitly, so always run — even to re-pair or
+ *                        fix autostart on a machine that already answered).
+ *
+ * All the non-interactive primitives live in `setup.ts` (`pairDevice`,
+ * `startDaemon`, `installAutostart`); this module is only the prompts + copy.
  */
 import { hostname } from 'os';
 import { prompt, confirm } from '../utils.js';
-import { bold, brand, dim, success, error as clrError, muted, info } from '../colors.js';
+import { bold, brand, dim, success, error as clrError, muted } from '../colors.js';
 import * as state from './state.js';
 import { UnsupportedPlatformError } from './installers.js';
 import { pairDevice, startDaemon, installAutostart } from './setup.js';
@@ -16,28 +23,41 @@ import { pairDevice, startDaemon, installAutostart } from './setup.js';
  *  keep their import path. */
 export const ensureDaemonRunning = startDaemon;
 /**
- * First-run prompt block. Idempotent: if the user has already answered
- * (`relay_enabled` is a boolean), this is a no-op. Non-interactive flows
- * (e.g. `gipity claude -p`) should skip calling this.
+ * Pair this computer as a relay and get it running. Returns `true` if the relay
+ * ended up enabled (or was already), `false` if the user declined or a step
+ * failed. Non-interactive flows (e.g. `gipity claude -p`) must not call this.
  */
-export async function maybeOfferRelayOn() {
-    if (state.getRelayEnabled() !== undefined) {
-        // Already answered - just ensure the daemon is running if they're opted in.
+export async function runRelaySetup(opts) {
+    const alreadyAnswered = state.getRelayEnabled() !== undefined;
+    // `gipity claude` first-run: honor the user's prior choice and don't re-ask.
+    if (opts.mode === 'offer-once' && alreadyAnswered) {
         if (state.isRelayEnabled() && !state.isPaused())
             ensureDaemonRunning();
-        return;
+        return state.isRelayEnabled();
+    }
+    // Header. `gipity setup` frames it as the deliberate action it is; the
+    // `gipity claude` first-run frames it as an optional add-on it's offering.
+    if (opts.mode === 'run-now') {
+        console.log(`  ${bold('Set up this computer as a relay')}`);
+        console.log(`  ${dim('A relay runs Claude Code (or Codex) here so you can drive it from the web (')}${brand('gipity.ai')}${dim(') on any browser.')}`);
+        console.log(`  ${dim('It uses your Claude or Codex subscription — the cheapest way to pay for tokens.')}`);
+    }
+    else {
+        console.log(`  ${bold('Remote control of Claude Code')}`);
+        console.log(`  ${dim('Drive this Claude Code from the web (')}${brand('gipity.ai')}${dim(') on any browser (desktop or phone).')}`);
+        console.log('');
+        console.log(`  ${dim('Enable now (takes 2 seconds) or turn on later with')} ${brand('gipity setup')}`);
     }
-    console.log(`  ${bold('Remote control of Claude Code')}`);
-    console.log(`  ${dim('Drive this Claude Code from the web (')}${brand('gipity.ai')}${dim(') on any browser (desktop or phone).')}`);
-    console.log('');
-    console.log(`  ${dim('Enable now (takes 2 seconds) or turn on later with')} ${brand('gipity relay install')}`);
     console.log('');
-    const enable = await confirm('  Enable remote control?', { default: 'yes' });
+    const promptText = opts.mode === 'run-now'
+        ? '  Set up remote control on this computer?'
+        : '  Enable remote control?';
+    const enable = await confirm(promptText, { default: 'yes' });
     if (!enable) {
         state.setRelayEnabled(false);
         console.log(`  ${muted('Skipped.')}`);
         console.log('');
-        return;
+        return false;
     }
     // Device name - show hostname as the default; Enter accepts.
     const defaultName = hostname() || 'my-pc';
@@ -46,7 +66,7 @@ export async function maybeOfferRelayOn() {
     if (!name || name.length > 100) {
         console.error(`  ${clrError('Device name must be 1–100 non-whitespace characters. Skipping.')}`);
         state.setRelayEnabled(false);
-        return;
+        return false;
     }
     // Create the device directly (user-auth, no pair code). `pairDevice` writes
     // the device + flips relay_enabled on; we only have to render the outcome.
@@ -56,12 +76,12 @@ export async function maybeOfferRelayOn() {
     }
     catch (err) {
         console.error(`\n  ${clrError(`Could not create device: ${err?.message || err}`)}`);
-        console.error(`  ${dim('Skipping for now - we\'ll offer again next time. Or turn it on with `gipity relay install`.')}`);
+        console.error(`  ${dim('Skipping for now - we\'ll offer again next time. Or turn it on with `gipity setup`.')}`);
         // Deliberately DON'T persist relay_enabled here: the user SAID YES, and
         // this is a transient failure (network blip, server down). Leaving the
         // tri-state unset means onboarding re-offers on the next `gipity claude`
         // run instead of silently opting the user out forever.
-        return;
+        return false;
     }
     // Start the daemon for this session.
     const startNow = await confirm('  Start the relay now (and on future `gipity claude` runs)?', { default: 'yes' });
@@ -93,6 +113,14 @@ export async function maybeOfferRelayOn() {
     console.log(`  ${success(`Registered as ${bold(device.name)} (${device.guid}).`)}`);
     console.log(`  ${dim('In the Gipity web CLI, type `/claude` to dispatch messages to this PC.')}`);
     console.log('');
-    void info;
+    return true;
+}
+/**
+ * First-run prompt block for `gipity claude`. Idempotent: if the user has
+ * already answered, this is a no-op (beyond keeping the daemon alive).
+ * Non-interactive flows (e.g. `gipity claude -p`) should skip calling this.
+ */
+export async function maybeOfferRelayOn() {
+    await runRelaySetup({ mode: 'offer-once' });
 }
 //# sourceMappingURL=onboarding.js.map

package/dist/relay/redact.js

@@ -60,7 +60,7 @@ const THIRD_PARTY_KEY_RES = [
 ];
 /** Replace every occurrence of each known secret - plus any JWT-, Anthropic-,
  *  or well-known-third-party-key-shaped substring - in `text` with the marker. */
-function redactString(text, secrets) {
+export function redactString(text, secrets) {
     let out = text;
     for (const secret of secrets) {
         if (out.includes(secret))

package/dist/relay/stream-delta.js

@@ -0,0 +1,235 @@
+/**
+ * Token-streaming delta pipeline for the relay daemon.
+ *
+ * With `--include-partial-messages`, Claude Code emits `stream_event`
+ * envelopes (content_block_start / content_block_delta / content_block_stop)
+ * carrying text, thinking, and tool-input fragments as they generate. The
+ * daemon forwards them - throttled and redacted - to
+ * `POST /remote-sessions/:convGuid/stream-delta`, which the server
+ * broadcasts to the web CLI as `dispatch:delta`. Purely ephemeral: no DB
+ * write, no retry; the persisted assistant/tool entries (whole events)
+ * remain the source of truth and replace the streamed view on the next
+ * refresh.
+ *
+ * Redaction across chunk boundaries: a secret split over two fragments
+ * would defeat a per-fragment scrub. The accumulator therefore only ever
+ * emits up to the last WHITESPACE boundary (holding back the trailing
+ * partial token until more input or block close) and scrubs each emitted
+ * span. Secrets in our threat set (host OAuth/API/device tokens, JWTs,
+ * provider keys) are contiguous non-whitespace tokens, so a held-back
+ * partial token can never leak a complete secret and a completed token is
+ * always scrubbed whole. Multi-line PEM blocks are the one shape this
+ * can't fully hold back - accepted on this ephemeral channel (the
+ * persisted path fully redacts, and the streamed text is replaced by the
+ * redacted stored message within seconds).
+ */
+import { redactString } from './redact.js';
+/** A trailing token longer than this is emitted anyway (minified code,
+ *  base64 blobs) - holding back indefinitely would stall the stream. No
+ *  credential in our threat set is this long. */
+const MAX_HOLDBACK = 4096;
+/** PEM key markers. A private key block spans multiple whitespace-
+ *  separated lines, so the whitespace-boundary holdback would emit
+ *  `BEGIN` before `END` arrives and per-span redaction would miss it.
+ *  emitUpTo holds the whole block back until END so it scrubs whole. */
+const PEM_BEGIN = /-----BEGIN [A-Z ]*PRIVATE KEY-----/;
+const PEM_END = /-----END [A-Z ]*PRIVATE KEY-----/;
+/** Emit boundary: everything up to (and including) the last whitespace.
+ *  `closing` (block stop) emits everything. */
+export function safeEmitBoundary(s, closing) {
+    if (closing)
+        return s.length;
+    const m = s.match(/\S+$/);
+    if (!m)
+        return s.length;
+    if (m[0].length > MAX_HOLDBACK)
+        return s.length;
+    return s.length - m[0].length;
+}
+/**
+ * Per-spawn accumulator: feed it raw stream_event envelopes, it returns
+ * redaction-safe StreamDeltaEvents ready to batch. Skips subagent events
+ * (parent_tool_use_id set) - those belong to the nested Task timeline,
+ * not the main stream zone.
+ */
+export class DeltaAccumulator {
+    getSecrets;
+    blocks = new Map();
+    /** The in-flight message's id, captured from `message_start` -
+     *  content_block_* events don't carry it themselves. This is what makes
+     *  the client-side finalize swap line up: persisted assistant rows are
+     *  keyed `msg_id#n` (Phase 2 source_uuid), streamed blocks `msg_id:n`. */
+    currentMessageId = 'msg';
+    constructor(getSecrets) {
+        this.getSecrets = getSecrets;
+    }
+    /** Map one parsed stream-json event to zero or more delta events. */
+    note(evt) {
+        if (evt.type !== 'stream_event')
+            return [];
+        if (evt.parent_tool_use_id)
+            return []; // subagent stream - not ours (Phase 6)
+        const inner = evt.event;
+        if (!inner || typeof inner.type !== 'string')
+            return [];
+        if (inner.type === 'message_start') {
+            if (typeof inner.message?.id === 'string' && inner.message.id) {
+                this.currentMessageId = inner.message.id;
+            }
+            return [];
+        }
+        const messageId = this.currentMessageId;
+        if (inner.type === 'content_block_start') {
+            const idx = typeof inner.index === 'number' ? inner.index : 0;
+            const cb = inner.content_block ?? {};
+            const type = cb.type === 'text' ? 'text' : cb.type === 'thinking' ? 'thinking' : cb.type === 'tool_use' ? 'tool_use' : null;
+            if (!type)
+                return [];
+            this.blocks.set(`${messageId}:${idx}`, { type, raw: '', rawEmitted: 0, outEmitted: 0, started: true });
+            const out = { message_id: messageId, block_index: idx, block_type: type, kind: 'start' };
+            if (type === 'tool_use' && typeof cb.name === 'string')
+                out.tool_name = cb.name;
+            return [out];
+        }
+        if (inner.type === 'content_block_delta') {
+            const idx = typeof inner.index === 'number' ? inner.index : 0;
+            const d = inner.delta ?? {};
+            const fragment = typeof d.text === 'string' ? d.text
+                : typeof d.thinking === 'string' ? d.thinking
+                    : typeof d.partial_json === 'string' ? d.partial_json
+                        : null;
+            if (fragment === null || fragment === '')
+                return [];
+            const key = `${messageId}:${idx}`;
+            let b = this.blocks.get(key);
+            if (!b) {
+                // Delta without a start (daemon restarted mid-message or an
+                // unknown block type at start time) - infer the type.
+                const type = typeof d.partial_json === 'string' ? 'tool_use'
+                    : typeof d.thinking === 'string' ? 'thinking' : 'text';
+                b = { type, raw: '', rawEmitted: 0, outEmitted: 0, started: false };
+                this.blocks.set(key, b);
+            }
+            b.raw += fragment;
+            return this.emitUpTo(messageId, idx, b, false);
+        }
+        if (inner.type === 'content_block_stop') {
+            const idx = typeof inner.index === 'number' ? inner.index : 0;
+            const key = `${messageId}:${idx}`;
+            const b = this.blocks.get(key);
+            if (!b)
+                return [];
+            const out = this.emitUpTo(messageId, idx, b, true);
+            out.push({ message_id: messageId, block_index: idx, block_type: b.type, kind: 'stop' });
+            this.blocks.delete(key);
+            return out;
+        }
+        return [];
+    }
+    emitUpTo(messageId, idx, b, closing) {
+        // Scan only the not-yet-emitted tail: the boundary can never precede
+        // rawEmitted (already a whitespace boundary), and running the regex
+        // over the full accumulated `raw` on every fragment is O(n²) over a
+        // long block - a big minified/base64 tool-input block would stall the
+        // daemon's event loop (which also drives the ingest queue + ticks).
+        const tail = b.raw.slice(b.rawEmitted);
+        // PEM keys are the one multi-LINE secret the whitespace-boundary
+        // holdback doesn't catch: `-----BEGIN … PRIVATE KEY-----` and its
+        // `-----END-----` land in different spans, so per-span redactString
+        // never sees them together. When an unterminated BEGIN marker is in
+        // the pending tail, hold the WHOLE tail back until END arrives (or the
+        // block closes), so redactString scrubs the complete block in one span.
+        if (!closing && PEM_BEGIN.test(tail) && !PEM_END.test(tail))
+            return [];
+        const tailBoundary = safeEmitBoundary(tail, closing);
+        if (tailBoundary <= 0)
+            return [];
+        const span = tail.slice(0, tailBoundary);
+        const boundary = b.rawEmitted + tailBoundary;
+        b.rawEmitted = boundary;
+        const scrubbed = redactString(span, this.getSecrets());
+        if (!scrubbed)
+            return [];
+        const evt = {
+            message_id: messageId,
+            block_index: idx,
+            block_type: b.type,
+            kind: 'delta',
+            text: scrubbed,
+            acc_offset: b.outEmitted,
+        };
+        b.outEmitted += scrubbed.length;
+        return [evt];
+    }
+}
+// ─── Throttled batcher ──────────────────────────────────────────────────
+const FLUSH_INTERVAL_MS = 150;
+const FLUSH_BYTES = 4096;
+/** Server-side caps (mirror the /stream-delta Zod schema). */
+const MAX_EVENTS_PER_FLUSH = 64;
+const MAX_TEXT_PER_FLUSH = 16_384;
+/**
+ * Buffers delta events and flushes them as numbered batches every 150ms
+ * or 4KB, whichever first. Fire-and-forget by design: a lost flush
+ * self-heals (the client detects the `acc_offset` gap and the next
+ * refresh replaces the stream zone with the stored message anyway).
+ */
+export class DeltaBatcher {
+    send;
+    intervalMs;
+    buffer = [];
+    bufferedText = 0;
+    seq = 0;
+    timer = null;
+    closed = false;
+    constructor(send, intervalMs = FLUSH_INTERVAL_MS) {
+        this.send = send;
+        this.intervalMs = intervalMs;
+    }
+    push(events) {
+        if (this.closed || events.length === 0)
+            return;
+        for (const e of events) {
+            this.buffer.push(e);
+            this.bufferedText += e.text?.length ?? 0;
+        }
+        if (this.bufferedText >= FLUSH_BYTES || this.buffer.length >= MAX_EVENTS_PER_FLUSH) {
+            this.flush();
+            return;
+        }
+        if (!this.timer) {
+            this.timer = setTimeout(() => this.flush(), this.intervalMs);
+            this.timer.unref?.();
+        }
+    }
+    flush() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        while (this.buffer.length) {
+            // Respect both server caps per POST: event count and total text.
+            const batch = [];
+            let text = 0;
+            while (this.buffer.length && batch.length < MAX_EVENTS_PER_FLUSH) {
+                const next = this.buffer[0];
+                const nextLen = next.text?.length ?? 0;
+                if (batch.length > 0 && text + nextLen > MAX_TEXT_PER_FLUSH)
+                    break;
+                // A single oversized event gets truncated rather than wedging the queue.
+                if (nextLen > MAX_TEXT_PER_FLUSH)
+                    next.text = next.text.slice(0, MAX_TEXT_PER_FLUSH);
+                batch.push(this.buffer.shift());
+                text += next.text?.length ?? 0;
+            }
+            this.bufferedText = Math.max(0, this.bufferedText - text);
+            this.send({ seq: this.seq++, events: batch });
+        }
+        this.bufferedText = 0;
+    }
+    close() {
+        this.flush();
+        this.closed = true;
+    }
+}
+//# sourceMappingURL=stream-delta.js.map

package/dist/relay/stream-json.js

@@ -58,31 +58,61 @@ function joinAssistantText(content) {
     }
     return parts.join('\n');
 }
-/** Map a single stream-json event to zero or more ingest entries. An
- *  assistant event may yield one `assistant` entry AND one `tool_use`
- *  entry per tool_use block within it (server persists each tool call
- *  as its own `role='tool'` row, then updates it when the matching
- *  `tool_result` arrives).
- *
- *  `toolNames` (optional) is a per-dispatch `tool_use_id → tool_name`
- *  map threaded across events by the daemon: assistant events record
- *  each tool call's name, the later user event with the paired
- *  `tool_result` reads it back so the server can denormalize `tool_name`
- *  onto the tool row even when the result lands as a stub. */
-export function mapEventToEntries(evt, toolNames) {
+export function mapEventToEntries(evt, ctx) {
+    // Back-compat: older call sites (and tests) pass the bare toolNames map.
+    const c = ctx instanceof Map ? { toolNames: ctx } : (ctx ?? {});
+    const toolNames = c.toolNames;
     const out = [];
     if (evt.type === 'system' && evt.subtype === 'init') {
         const s = evt;
-        if (s.session_id)
-            out.push({ kind: 'attach', session_id: s.session_id, cwd: s.cwd, source: 'startup' });
+        if (s.session_id) {
+            out.push({
+                kind: 'attach',
+                session_id: s.session_id,
+                cwd: s.cwd,
+                source: 'startup',
+                model: typeof s.model === 'string' ? s.model : undefined,
+                tools_count: Array.isArray(s.tools) ? s.tools.length : undefined,
+                mcp_count: Array.isArray(s.mcp_servers) ? s.mcp_servers.length : undefined,
+                api_key_source: typeof s.apiKeySource === 'string' ? s.apiKeySource : undefined,
+            });
+        }
         return out;
     }
+    // Context compaction boundary - the server has a `compact` kind for this
+    // (renders as a "context compacted" marker); nothing emitted it before.
+    if (evt.type === 'system' && evt.subtype === 'compact_boundary') {
+        const trigger = evt.compact_metadata?.trigger ?? evt.trigger;
+        out.push({ kind: 'compact', trigger: typeof trigger === 'string' ? trigger : undefined });
+        return out;
+    }
+    // Subagent attribution: the envelope carries the spawning Task/Agent
+    // tool_use id on every event from that subagent's turn.
+    const parentToolUseId = typeof evt.parent_tool_use_id === 'string'
+        ? evt.parent_tool_use_id : undefined;
     if (evt.type === 'assistant') {
         const msg = evt.message ?? {};
         const content = Array.isArray(msg.content) ? msg.content : [];
         const text = joinAssistantText(content);
         if (text || content.length) {
-            out.push({ kind: 'assistant', text, blocks: content, ...usageFields(msg) });
+            const entry = { kind: 'assistant', text, blocks: content, ...usageFields(msg), parent_tool_use_id: parentToolUseId };
+            // source_uuid = `${msg.id}#${eventSeq}`. The client's stream-zone
+            // finalize-swap matches this against its block key `${msg.id}:${block_index}`,
+            // i.e. it relies on eventSeq === block_index. That holds because
+            // Claude Code (with --include-partial-messages) emits exactly ONE
+            // assistant event per content block, in index order (verified
+            // against CLI v2.1.199 in the Phase 0 spike: a thinking block and a
+            // text block arrived as two separate assistant events, seq 0 and 1,
+            // matching block indices 0 and 1). If a future CLI ever packs two
+            // blocks into one assistant event, seq lags index for later blocks
+            // and those streamed blocks aren't removed until the ack wipes the
+            // zone - a cosmetic, self-healing duplication, not data loss.
+            if (typeof msg.id === 'string' && msg.id && c.msgSeq) {
+                const n = c.msgSeq.get(msg.id) ?? 0;
+                c.msgSeq.set(msg.id, n + 1);
+                entry.source_uuid = `${msg.id}#${n}`;
+            }
+            out.push(entry);
         }
         for (const block of content) {
             if (block?.type === 'tool_use' && typeof block.id === 'string') {
@@ -93,6 +123,8 @@ export function mapEventToEntries(evt, toolNames) {
                     tool_use_id: block.id,
                     tool_name: toolName,
                     tool_input: block.input ?? null,
+                    source_uuid: block.id,
+                    parent_tool_use_id: parentToolUseId,
                 });
             }
         }
@@ -109,6 +141,7 @@ export function mapEventToEntries(evt, toolNames) {
                     tool_name: toolNames?.get(block.tool_use_id),
                     content: block.content ?? null,
                     is_error: Boolean(block.is_error),
+                    parent_tool_use_id: parentToolUseId,
                 });
             }
         }
@@ -130,6 +163,19 @@ export function mapEventToEntries(evt, toolNames) {
         }
         return out;
     }
+    // Deliberately unmapped chatter (hook lifecycle, per-chunk thinking
+    // token counts, rate-limit notices, and stream_event token deltas -
+    // the latter are handled by the separate stream-delta pipeline) -
+    // skipped without accounting so a normal session doesn't log dozens of
+    // "unmapped" entries. Everything else unknown IS accounted via
+    // onUnmapped so a new Claude Code event type shows up in the daemon
+    // log instead of vanishing silently.
+    const subtype = evt.subtype;
+    const KNOWN_NOISE = new Set(['hook_started', 'hook_response', 'thinking_tokens', 'status', 'task_started', 'task_progress', 'task_updated', 'task_notification']);
+    if (!(evt.type === 'system' && subtype && KNOWN_NOISE.has(subtype))
+        && evt.type !== 'rate_limit_event' && evt.type !== 'stream_event') {
+        c.onUnmapped?.(evt.type, subtype);
+    }
     return out;
 }
 /** Pull token usage + model + stop_reason off an assistant stream `message`.