@hyperdrive.bot/fleet-server 0.3.99

package/dist/server/server/agent/providers/claude/transport/transcript-sdk-reader.js

@@ -0,0 +1,243 @@
+import * as fs from "node:fs";
+import { redactSecrets } from "./redact.js";
+/**
+ * Tails a Claude Code session-transcript JSONL (`~/.claude/projects/<slug>/<sid>.jsonl`)
+ * and reconstructs the `SDKMessage` stream the query pump consumes — so the PTY transport
+ * gets the same structured output the SDK transport yields, without the SDK.
+ *
+ * Emits only what the pump renders (see agent.ts `translateMessageToEvents`):
+ *   - `assistant` lines  → SDKAssistantMessage (text / thinking / tool_use blocks)
+ *   - `user` lines that carry a tool_result → SDKUserMessage (so tool results render)
+ * Everything else is skipped:
+ *   - plain user-prompt echoes (paseo emits the submitted user message itself via
+ *     emitSubmittedUserMessage, so re-yielding would double-render)
+ *   - `isSidechain` lines (subagent messages live in `<sid>/subagents/*.jsonl`, tracked
+ *     separately by ClaudeSidechainTracker)
+ *   - `system` lines, EXCEPT `subtype: "api_error"` (PtyQuery synthesizes the init message
+ *     from buildOptions instead). The api_error exception matters: claude writes provider
+ *     failures here (`429 Rate limit ... Retry in 16s`, auth failures, network drops) and
+ *     dropping them was the reason a rate-limited agent showed a spinner and nothing else.
+ *     The PTY path cannot recover these anywhere else, because the terminal that prints
+ *     them is unsubscribed once the readiness gate settles.
+ *   - `result` (transcript has none — PtyQuery synthesizes it on the Stop hook)
+ *   - bookkeeping: attachment / queue-operation / last-prompt / file-history-snapshot
+ *
+ * Field convention bridge: the transcript uses camelCase (`sessionId`, `parentUuid`);
+ * SDK messages use snake_case (`session_id`, `parent_tool_use_id`). The nested `message`
+ * object is already the exact BetaMessage/MessageParam the SDK produced — passed through.
+ */
+const POLL_INTERVAL_MS = 200;
+/**
+ * Human-readable text for an `api_error` line. Prefers claude's own `formatted` string
+ * (`"429 Rate limit: ... Retry in 16s."`), which is already the terse one-liner the TUI
+ * shows; falls back to the raw message, then to the bare status.
+ */
+function describeApiError(line) {
+    const err = line.error;
+    if (!err)
+        return null;
+    const text = (err.formatted ?? err.message ?? "").trim();
+    if (text)
+        return text;
+    if (typeof err.status === "number")
+        return `API error ${err.status}`;
+    return "API error";
+}
+export class TranscriptSdkReader {
+    constructor(opts) {
+        this.timer = null;
+        this.readOffset = 0;
+        this.buffer = "";
+        this.transcriptPath = opts.transcriptPath;
+        this.onMessage = opts.onMessage;
+        this.onUserPrompt = opts.onUserPrompt;
+    }
+    /**
+     * Begin streaming NEW appends. Starts at the current EOF so a `--resume`'d session
+     * (whose transcript already holds the prior conversation) only surfaces new turns.
+     * Poll-based (not fs.watch) so a not-yet-created transcript is handled cleanly — the
+     * file is created by claude only once the first turn begins.
+     */
+    start() {
+        if (this.timer)
+            return;
+        try {
+            this.readOffset = fs.existsSync(this.transcriptPath)
+                ? fs.statSync(this.transcriptPath).size
+                : 0;
+        }
+        catch {
+            this.readOffset = 0;
+        }
+        this.timer = setInterval(() => this.drain(), POLL_INTERVAL_MS);
+        if (typeof this.timer.unref === "function")
+            this.timer.unref();
+    }
+    stop() {
+        if (!this.timer)
+            return;
+        clearInterval(this.timer);
+        this.timer = null;
+    }
+    /** Drain immediately (used by tests and on final teardown to flush trailing lines). */
+    drainNow() {
+        this.drain();
+    }
+    drain() {
+        let fd = null;
+        try {
+            if (!fs.existsSync(this.transcriptPath))
+                return;
+            fd = fs.openSync(this.transcriptPath, "r");
+            const { size } = fs.fstatSync(fd);
+            if (size <= this.readOffset)
+                return;
+            const length = size - this.readOffset;
+            const buf = Buffer.alloc(length);
+            fs.readSync(fd, buf, 0, length, this.readOffset);
+            this.readOffset = size;
+            this.buffer += buf.toString("utf8");
+            const lines = this.buffer.split("\n");
+            this.buffer = lines.pop() ?? "";
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (trimmed)
+                    this.handleLine(trimmed);
+            }
+        }
+        catch {
+            // file rotated / removed between exists-check and read; ignore
+        }
+        finally {
+            if (fd !== null) {
+                try {
+                    fs.closeSync(fd);
+                }
+                catch {
+                    // ignore
+                }
+            }
+        }
+    }
+    handleLine(line) {
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if (!parsed || typeof parsed !== "object")
+            return;
+        if (parsed.isSidechain)
+            return;
+        this.notifyUserPrompt(parsed);
+        const message = this.toSdkMessage(parsed);
+        if (message)
+            this.onMessage(message);
+    }
+    /**
+     * Surface the transcript uuid of a plain user prompt: exactly the line `toSdkMessage`
+     * returns null for. Deliberately narrow -- a tool_result user line is a different thing
+     * and already reaches the pump as a message.
+     */
+    notifyUserPrompt(line) {
+        if (!this.onUserPrompt)
+            return;
+        if (line.type !== "user" || line.isMeta)
+            return;
+        if (userLineHasToolResult(line))
+            return;
+        const uuid = line.uuid ?? "";
+        if (!uuid)
+            return;
+        const text = extractUserPromptText(line);
+        if (!text)
+            return;
+        this.onUserPrompt({ uuid, text });
+    }
+    toSdkMessage(line) {
+        const session_id = line.sessionId ?? "";
+        const uuid = line.uuid ?? "";
+        switch (line.type) {
+            case "assistant": {
+                if (!line.message)
+                    return null;
+                const message = {
+                    type: "assistant",
+                    message: line.message,
+                    parent_tool_use_id: null,
+                    uuid: uuid,
+                    session_id,
+                };
+                return message;
+            }
+            case "user": {
+                if (line.isMeta)
+                    return null;
+                if (!userLineHasToolResult(line))
+                    return null;
+                const message = {
+                    type: "user",
+                    message: line.message,
+                    parent_tool_use_id: null,
+                    uuid: uuid,
+                    session_id,
+                };
+                return message;
+            }
+            case "system": {
+                // Only api_error. Every other system subtype really is bookkeeping (init is
+                // synthesized by PtyQuery, status/compact_boundary/task_* are SDK-path concerns).
+                if (line.subtype !== "api_error")
+                    return null;
+                const text = describeApiError(line);
+                if (!text)
+                    return null;
+                const message = {
+                    type: "system",
+                    subtype: "api_error",
+                    level: line.level ?? "error",
+                    error: { message: redactSecrets(text) },
+                    uuid,
+                    session_id,
+                };
+                return message;
+            }
+            default:
+                // result → synthesized on Stop; the rest is paseo/CC bookkeeping the pump never reads.
+                return null;
+        }
+    }
+}
+/**
+ * Flatten a user prompt line's content to plain text. The transcript stores it either as a
+ * bare string or as the SDK's content-block array; only `text` blocks carry prompt words.
+ */
+function extractUserPromptText(line) {
+    const content = line.message?.content;
+    if (typeof content === "string")
+        return content.trim();
+    if (!Array.isArray(content))
+        return "";
+    const parts = [];
+    for (const block of content) {
+        if (!block || typeof block !== "object")
+            continue;
+        const b = block;
+        if (b.type === "text" && typeof b.text === "string")
+            parts.push(b.text);
+    }
+    return parts.join("").trim();
+}
+/** A user transcript line carries a tool_result either at top level or in message.content. */
+function userLineHasToolResult(line) {
+    if (line.toolUseResult !== undefined)
+        return true;
+    const content = line.message?.content;
+    if (Array.isArray(content)) {
+        return content.some((block) => block && typeof block === "object" && block.type === "tool_result");
+    }
+    return false;
+}
+//# sourceMappingURL=transcript-sdk-reader.js.map

package/dist/server/server/agent/providers/claude/transport/transcript-tailer.d.ts

@@ -0,0 +1,28 @@
+import type { HookEvent } from "@hyperdrive.bot/fleet-protocol/messages";
+export declare function deriveTranscriptDir(cwd: string): string;
+export interface TranscriptTailerOptions {
+    transcriptPath: string;
+    onHookEvent: (event: HookEvent) => void;
+}
+export declare class TranscriptTailer {
+    private readonly transcriptPath;
+    private readonly onHookEvent;
+    private watcher;
+    private pollTimer;
+    private readOffset;
+    private buffer;
+    constructor(opts: TranscriptTailerOptions);
+    /**
+     * True when this tailer could not get an fs watcher and is polling instead.
+     * Exposed for diagnostics and tests; callers get identical events either way.
+     */
+    get isPolling(): boolean;
+    start(): void;
+    stop(): void;
+    private startPolling;
+    private drain;
+    private emitFromLine;
+    private emitAssistantDeltas;
+    private emitUsageUpdate;
+}
+//# sourceMappingURL=transcript-tailer.d.ts.map

package/dist/server/server/agent/providers/claude/transport/transcript-tailer.js

@@ -0,0 +1,166 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+// cwd-slug derivation matches agent.ts:3468-3477 (loadPersistedHistory). The
+// claude binary writes its transcript JSONL at
+// `~/.claude/projects/<cwd.replace(/\//g, "-")>/<session-id>.jsonl`. Keep this
+// expression byte-for-byte identical — any divergence points the tailer at a
+// non-existent path.
+export function deriveTranscriptDir(cwd) {
+    const cwdSlug = cwd.replace(/\//g, "-");
+    return path.join(os.homedir(), ".claude", "projects", cwdSlug);
+}
+/**
+ * Poll cadence for the degraded (no-watcher) mode. Slow enough to be cheap when
+ * many tailers fall back at once, fast enough that assistant deltas still feel
+ * live. Only ever used when `fs.watch` could not be created.
+ */
+const POLL_FALLBACK_INTERVAL_MS = 250;
+export class TranscriptTailer {
+    constructor(opts) {
+        this.watcher = null;
+        this.pollTimer = null;
+        this.readOffset = 0;
+        this.buffer = "";
+        this.transcriptPath = opts.transcriptPath;
+        this.onHookEvent = opts.onHookEvent;
+    }
+    /**
+     * True when this tailer could not get an fs watcher and is polling instead.
+     * Exposed for diagnostics and tests; callers get identical events either way.
+     */
+    get isPolling() {
+        return this.pollTimer !== null;
+    }
+    start() {
+        if (this.watcher || this.pollTimer)
+            return;
+        try {
+            const stat = fs.statSync(this.transcriptPath);
+            this.readOffset = stat.size;
+        }
+        catch {
+            this.readOffset = 0;
+        }
+        try {
+            this.watcher = fs.watch(this.transcriptPath, { persistent: false }, () => {
+                this.drain();
+            });
+        }
+        catch {
+            // `fs.watch` is a finite resource: it throws EMFILE when the process is out
+            // of file descriptors and ENOSPC when the OS inotify watch limit is hit.
+            // Both are REACHABLE IN PRODUCTION - every Claude agent owns a tailer, so a
+            // box running a fleet of agents can exhaust either ceiling, and an
+            // unguarded throw here took the whole agent transport down at start().
+            // Degrade to polling instead: slower, but the transcript still streams.
+            this.startPolling();
+        }
+    }
+    stop() {
+        if (this.watcher) {
+            try {
+                this.watcher.close();
+            }
+            catch {
+                // already closed
+            }
+            this.watcher = null;
+        }
+        if (this.pollTimer) {
+            clearInterval(this.pollTimer);
+            this.pollTimer = null;
+        }
+    }
+    startPolling() {
+        const timer = setInterval(() => {
+            this.drain();
+        }, POLL_FALLBACK_INTERVAL_MS);
+        // Match the watcher's `persistent: false` - a tailer must never be the reason
+        // the process stays alive.
+        timer.unref?.();
+        this.pollTimer = timer;
+    }
+    drain() {
+        let fd = null;
+        try {
+            fd = fs.openSync(this.transcriptPath, "r");
+            const { size } = fs.fstatSync(fd);
+            if (size <= this.readOffset)
+                return;
+            const length = size - this.readOffset;
+            const buf = Buffer.alloc(length);
+            fs.readSync(fd, buf, 0, length, this.readOffset);
+            this.readOffset = size;
+            this.buffer += buf.toString("utf8");
+            const lines = this.buffer.split("\n");
+            this.buffer = lines.pop() ?? "";
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    continue;
+                this.emitFromLine(trimmed);
+            }
+        }
+        catch {
+            // file may have rotated / been removed; ignore
+        }
+        finally {
+            if (fd !== null) {
+                try {
+                    fs.closeSync(fd);
+                }
+                catch {
+                    // ignore
+                }
+            }
+        }
+    }
+    emitFromLine(line) {
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if (!parsed || typeof parsed !== "object")
+            return;
+        const obj = parsed;
+        this.emitAssistantDeltas(obj);
+        this.emitUsageUpdate(obj.usage);
+    }
+    emitAssistantDeltas(obj) {
+        if (obj.type !== "assistant" || !Array.isArray(obj.message?.content))
+            return;
+        for (const entry of obj.message?.content ?? []) {
+            if (entry?.type === "text" && typeof entry.text === "string" && entry.text.length > 0) {
+                this.onHookEvent({
+                    kind: "assistant_message_delta",
+                    delta: { text: entry.text },
+                });
+            }
+        }
+    }
+    emitUsageUpdate(usage) {
+        if (!usage || typeof usage !== "object")
+            return;
+        const out = {};
+        if (typeof usage.input_tokens === "number")
+            out.input_tokens = usage.input_tokens;
+        if (typeof usage.output_tokens === "number")
+            out.output_tokens = usage.output_tokens;
+        if (typeof usage.cache_creation_input_tokens === "number") {
+            out.cache_creation_input_tokens = usage.cache_creation_input_tokens;
+        }
+        if (typeof usage.cache_read_input_tokens === "number") {
+            out.cache_read_input_tokens = usage.cache_read_input_tokens;
+        }
+        if (typeof usage.total_cost_usd === "number")
+            out.total_cost_usd = usage.total_cost_usd;
+        if (Object.keys(out).length === 0)
+            return;
+        this.onHookEvent({ kind: "usage_update", usage: out });
+    }
+}
+//# sourceMappingURL=transcript-tailer.js.map

package/dist/server/server/agent/providers/claude/transport/truncate-session.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Story 2.1 — pure fork primitive for Rewind (2.2) and Edit (2.4).
+ *
+ * `truncateSessionAt` copies a Claude Code transcript JSONL up to and
+ * including the matched turn into a freshly-minted new session id's path.
+ * The source transcript is opened read-only and NEVER mutated — the
+ * abandoned branch stays on disk forever.
+ *
+ * The destination write is byte-identical to the source's prefix (we slice
+ * raw bytes, never re-serialize JSON) so downstream consumers (the `claude`
+ * CLI's `--resume`, transcript-tailer's offset math) see the same shape.
+ */
+export type TruncateSessionErrorCode = "source_missing" | "turn_not_found" | "empty_source" | "destination_exists" | "invalid_source_line";
+export declare class TruncateSessionError extends Error {
+    readonly code: TruncateSessionErrorCode;
+    readonly context: Record<string, unknown>;
+    constructor(code: TruncateSessionErrorCode, context?: Record<string, unknown>);
+}
+export interface TruncateSessionAtParams {
+    sessionId: string;
+    turnId: string;
+    cwd: string;
+    /**
+     * When true (default), the matched turn is included in the new transcript
+     * (Rewind semantics — preserve through and including the matched user
+     * message). When false, the matched turn is excluded (Edit semantics — cut
+     * just before the matched turn so the caller can append a replacement).
+     */
+    inclusive?: boolean;
+    /** Test-only injection point; defaults to randomUUID(). */
+    newSessionId?: string;
+    /** Test-only injection point; reserved for future audit timestamps. */
+    now?: () => Date;
+}
+export interface TruncateSessionAtResult {
+    newSessionId: string;
+    newTranscriptPath: string;
+    linesCopied: number;
+}
+export declare function truncateSessionAt(params: TruncateSessionAtParams): TruncateSessionAtResult;
+/**
+ * Does this transcript contain an actual conversation, or only bookkeeping?
+ *
+ * `claude --resume` refuses a transcript with no `user`/`assistant` line ("No conversation
+ * found with session ID"). Truncating before the FIRST user message produces exactly that:
+ * a file holding nothing but `queue-operation` entries. Callers use this to decide between
+ * resuming the fork and starting fresh.
+ */
+export declare function transcriptHasConversation(transcriptPath: string): boolean;
+//# sourceMappingURL=truncate-session.d.ts.map

package/dist/server/server/agent/providers/claude/transport/truncate-session.js

@@ -0,0 +1,121 @@
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import { resolveTranscriptPath } from "./claude-paths.js";
+export class TruncateSessionError extends Error {
+    constructor(code, context = {}) {
+        super(`truncate session failed: ${code}`);
+        this.name = "TruncateSessionError";
+        this.code = code;
+        this.context = context;
+    }
+}
+export function truncateSessionAt(params) {
+    const { sessionId, turnId, cwd } = params;
+    const inclusive = params.inclusive ?? true;
+    const newSessionId = params.newSessionId ?? randomUUID();
+    const srcPath = resolveTranscriptPath({ cwd, sessionId });
+    const destPath = resolveTranscriptPath({ cwd, sessionId: newSessionId });
+    if (!fs.existsSync(srcPath)) {
+        throw new TruncateSessionError("source_missing", { srcPath });
+    }
+    if (fs.existsSync(destPath)) {
+        throw new TruncateSessionError("destination_exists", { newSessionId, destPath });
+    }
+    const raw = fs.readFileSync(srcPath, "utf8");
+    // Walk the source byte-by-byte so the eventual write is the exact source
+    // prefix (preserves both the line terminator style — \n vs \r\n — and any
+    // trailing newline after the matched line).
+    let cursor = 0;
+    let matchedEnd = -1;
+    let lineIndex = 0;
+    let sawNonEmpty = false;
+    while (cursor < raw.length) {
+        // Find the end of the current line (either \r\n, \n, or end-of-string).
+        let lineEnd = cursor;
+        while (lineEnd < raw.length && raw[lineEnd] !== "\n")
+            lineEnd++;
+        // Include the trailing \n in the slice if present.
+        const sliceEnd = lineEnd < raw.length ? lineEnd + 1 : lineEnd;
+        const lineContentEnd = lineEnd > cursor && raw[lineEnd - 1] === "\r" ? lineEnd - 1 : lineEnd;
+        const lineText = raw.slice(cursor, lineContentEnd);
+        if (lineText.length > 0) {
+            sawNonEmpty = true;
+            let parsed;
+            try {
+                parsed = JSON.parse(lineText);
+            }
+            catch {
+                throw new TruncateSessionError("invalid_source_line", {
+                    srcPath,
+                    lineIndex,
+                });
+            }
+            if (isObjectWithUuid(parsed) && parsed.uuid === turnId) {
+                // Inclusive (Rewind): keep through end of matched line.
+                // Exclusive (Edit): cut at the start of the matched line.
+                matchedEnd = inclusive ? sliceEnd : cursor;
+                lineIndex += 1;
+                break;
+            }
+        }
+        lineIndex += 1;
+        cursor = sliceEnd;
+    }
+    if (!sawNonEmpty) {
+        throw new TruncateSessionError("empty_source", { srcPath });
+    }
+    if (matchedEnd === -1) {
+        throw new TruncateSessionError("turn_not_found", { srcPath, turnId });
+    }
+    const prefixBytes = Buffer.from(raw.slice(0, matchedEnd), "utf8");
+    const tmpPath = `${destPath}.tmp-${process.pid}`;
+    fs.writeFileSync(tmpPath, prefixBytes);
+    fs.renameSync(tmpPath, destPath);
+    return {
+        newSessionId,
+        newTranscriptPath: destPath,
+        linesCopied: lineIndex,
+    };
+}
+function isObjectWithUuid(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "uuid" in value &&
+        typeof value.uuid === "string");
+}
+/**
+ * Does this transcript contain an actual conversation, or only bookkeeping?
+ *
+ * `claude --resume` refuses a transcript with no `user`/`assistant` line ("No conversation
+ * found with session ID"). Truncating before the FIRST user message produces exactly that:
+ * a file holding nothing but `queue-operation` entries. Callers use this to decide between
+ * resuming the fork and starting fresh.
+ */
+export function transcriptHasConversation(transcriptPath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(transcriptPath, "utf8");
+    }
+    catch {
+        return false;
+    }
+    for (const line of raw.split("\n")) {
+        const text = line.trim();
+        if (!text)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            continue;
+        }
+        if (typeof parsed !== "object" || parsed === null)
+            continue;
+        const type = parsed.type;
+        if (type === "user" || type === "assistant")
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=truncate-session.js.map

package/dist/server/server/agent/providers/claude/transport/turn-id-reconciler.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Pairs the user-message id paseo mints with the uuid `claude` writes into the transcript.
+ *
+ * Why this exists: on the PTY transport the prompt is TYPED INTO THE TERMINAL, so claude
+ * writes the transcript line and mints its uuid, while paseo minted its own id earlier (to
+ * render the bubble immediately) and handed that to the app. Edit and Rewind resolve a turn
+ * by scanning the transcript for `uuid === turnId` (`truncateSessionAt`), so without a pairing
+ * every edit fails `turn_not_found`.
+ *
+ * Pairing key is the prompt text, oldest match first, because either side can arrive first:
+ * the mint happens before the keystrokes, the transcript line only after claude has read
+ * them. Unmatched entries wait in their queue rather than being guessed at by position -- a
+ * queued or retried message would make position lie.
+ *
+ * Text is compared on collapsed whitespace: the terminal round-trip is not byte-preserving.
+ */
+export declare class TurnIdReconciler {
+    private readonly mintedToTranscript;
+    private readonly promptsAwaitingUuid;
+    private readonly uuidsAwaitingPrompt;
+    /** Record an id paseo just minted for a prompt it is about to send. */
+    rememberMintedPrompt(id: string, text: string): void;
+    /** Record a plain user-prompt line claude wrote to the transcript. Identity only. */
+    rememberTranscriptPrompt(uuid: string, text: string): void;
+    /**
+     * Map a turn id onto one that exists in the transcript.
+     *
+     * Passthrough when no pairing is known, which is correct twice over: on the SDK transport,
+     * and for turns replayed off disk, the id the app holds already IS the transcript uuid. A
+     * miss therefore degrades to the previous behaviour rather than inventing a turn.
+     */
+    resolve(turnId: string): string;
+    /** Drop all state. Called when the underlying claude session is replaced. */
+    clear(): void;
+}
+//# sourceMappingURL=turn-id-reconciler.d.ts.map