@hyperdrive.bot/paseo-server 0.2.6

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

@@ -0,0 +1,28 @@
+import type { HookEvent } from "@hyperdrive.bot/paseo-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,41 @@
+/**
+ * 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;
+//# sourceMappingURL=truncate-session.d.ts.map

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

@@ -0,0 +1,86 @@
+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");
+}
+//# sourceMappingURL=truncate-session.js.map

package/dist/server/server/agent/providers/claude/transport/types.d.ts

@@ -0,0 +1,47 @@
+import type { HookEvent } from "@hyperdrive.bot/paseo-protocol/messages";
+export interface AgentTransportSpawnOptions {
+    binary: string;
+    args: string[];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    dims?: {
+        cols: number;
+        rows: number;
+    };
+    /**
+     * Path to a temp file written by spawn-config-writer.buildSpawnArgs() when
+     * the appended system prompt exceeded the inline-size threshold. The
+     * transport is responsible for unlinking this file in kill().
+     */
+    systemPromptFilePath?: string;
+}
+export type AgentTransportContext = {
+    transport: "pty";
+    pid: number;
+    cwd: string;
+    dims: {
+        cols: number;
+        rows: number;
+    };
+} | {
+    transport: "sdk";
+    pid: number | null;
+    cwd: string;
+};
+export interface AgentTransport {
+    spawn(opts: AgentTransportSpawnOptions): Promise<void>;
+    write(text: string): Promise<void>;
+    /**
+     * Write raw bytes to the transport WITHOUT bracketed-paste framing — for
+     * sending real keypresses (control chords, arrows, Esc) that drive the
+     * agent's interactive TUI, as opposed to pasted text. Optional: only the PTY
+     * transport drives a TUI; transports without one omit it.
+     */
+    writeRaw?(data: string): Promise<void>;
+    kill(timeoutMs?: number): Promise<void>;
+    onHookEvent(handler: (event: HookEvent) => void): () => void;
+    onData(handler: (chunk: string) => void): () => void;
+    onExit(handler: (code: number | null, signal: NodeJS.Signals | null) => void): () => void;
+    context(): AgentTransportContext;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/server/server/agent/providers/claude/transport/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/server/server/agent/providers/codex/app-server-transport.d.ts

@@ -0,0 +1,90 @@
+import type { ChildProcessWithoutNullStreams } from "node:child_process";
+import type { Logger } from "pino";
+import { z } from "zod";
+type RequestHandler = (params: unknown) => unknown;
+type NotificationHandler = (method: string, params: unknown) => void;
+export interface CodexThreadForkParams {
+    threadId: string;
+    path?: string | null;
+    model?: string | null;
+    modelProvider?: string | null;
+    serviceTier?: string | null;
+    cwd?: string | null;
+    runtimeWorkspaceRoots?: string[] | null;
+    approvalPolicy?: unknown;
+    approvalsReviewer?: unknown;
+    sandbox?: unknown;
+    permissions?: string | null;
+    config?: Record<string, unknown> | null;
+    baseInstructions?: string | null;
+    developerInstructions?: string | null;
+    ephemeral?: boolean;
+    threadSource?: unknown;
+    excludeTurns?: boolean;
+    persistExtendedHistory?: boolean;
+}
+declare const CodexThreadForkResponseSchema: z.ZodObject<{
+    thread: z.ZodObject<{
+        id: z.ZodString;
+        sessionId: z.ZodOptional<z.ZodString>;
+        forkedFromId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        turns: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    }, z.core.$loose>;
+    model: z.ZodString;
+    modelProvider: z.ZodString;
+    serviceTier: z.ZodNullable<z.ZodString>;
+    cwd: z.ZodString;
+    runtimeWorkspaceRoots: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+    instructionSources: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+    approvalPolicy: z.ZodUnknown;
+    approvalsReviewer: z.ZodUnknown;
+    sandbox: z.ZodUnknown;
+    activePermissionProfile: z.ZodOptional<z.ZodUnknown>;
+    reasoningEffort: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$loose>;
+export type CodexThreadForkResponse = z.infer<typeof CodexThreadForkResponseSchema>;
+export declare function parseCodexThreadForkResponse(response: unknown): CodexThreadForkResponse;
+export interface CodexThreadRollbackParams {
+    threadId: string;
+    numTurns: number;
+}
+declare const CodexThreadRollbackResponseSchema: z.ZodObject<{
+    thread: z.ZodObject<{
+        id: z.ZodString;
+        sessionId: z.ZodOptional<z.ZodString>;
+        forkedFromId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        turns: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    }, z.core.$loose>;
+}, z.core.$loose>;
+export type CodexThreadRollbackResponse = z.infer<typeof CodexThreadRollbackResponseSchema>;
+export declare function parseCodexThreadRollbackResponse(response: unknown): CodexThreadRollbackResponse;
+export interface CodexAppServerTraceContext {
+    agentId?: string;
+    sessionId?: string;
+    turnId?: string;
+}
+export declare class CodexAppServerClient {
+    private readonly child;
+    private readonly logger;
+    private readonly getTraceContext;
+    private readonly rl;
+    private readonly pending;
+    private readonly requestHandlers;
+    private notificationHandler;
+    private nextId;
+    private disposed;
+    private stderrBuffer;
+    constructor(child: ChildProcessWithoutNullStreams, logger: Logger, getTraceContext?: () => CodexAppServerTraceContext);
+    setNotificationHandler(handler: NotificationHandler): void;
+    setRequestHandler(method: string, handler: RequestHandler): void;
+    request(method: string, params?: unknown, timeoutMs?: number): Promise<unknown>;
+    forkThread(params: CodexThreadForkParams): Promise<CodexThreadForkResponse>;
+    rollbackThread(params: CodexThreadRollbackParams): Promise<CodexThreadRollbackResponse>;
+    notify(method: string, params?: unknown): void;
+    dispose(): Promise<void>;
+    private writeJsonRpcResponse;
+    private handleLine;
+    private traceRawEvent;
+}
+export {};
+//# sourceMappingURL=app-server-transport.d.ts.map