@hyperdrive.bot/fleet-server 0.3.99

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

@@ -0,0 +1,75 @@
+/**
+ * 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 class TurnIdReconciler {
+    constructor() {
+        this.mintedToTranscript = new Map();
+        this.promptsAwaitingUuid = [];
+        this.uuidsAwaitingPrompt = [];
+    }
+    /** Record an id paseo just minted for a prompt it is about to send. */
+    rememberMintedPrompt(id, text) {
+        if (!id)
+            return;
+        const key = normalizePromptText(text);
+        if (!key)
+            return;
+        const idx = this.uuidsAwaitingPrompt.findIndex((entry) => entry.text === key);
+        if (idx >= 0) {
+            const [hit] = this.uuidsAwaitingPrompt.splice(idx, 1);
+            if (hit)
+                this.mintedToTranscript.set(id, hit.uuid);
+            return;
+        }
+        this.promptsAwaitingUuid.push({ id, text: key });
+    }
+    /** Record a plain user-prompt line claude wrote to the transcript. Identity only. */
+    rememberTranscriptPrompt(uuid, text) {
+        if (!uuid)
+            return;
+        const key = normalizePromptText(text);
+        if (!key)
+            return;
+        const idx = this.promptsAwaitingUuid.findIndex((entry) => entry.text === key);
+        if (idx >= 0) {
+            const [hit] = this.promptsAwaitingUuid.splice(idx, 1);
+            if (hit)
+                this.mintedToTranscript.set(hit.id, uuid);
+            return;
+        }
+        this.uuidsAwaitingPrompt.push({ uuid, text: key });
+    }
+    /**
+     * 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) {
+        return this.mintedToTranscript.get(turnId) ?? turnId;
+    }
+    /** Drop all state. Called when the underlying claude session is replaced. */
+    clear() {
+        this.mintedToTranscript.clear();
+        this.promptsAwaitingUuid.length = 0;
+        this.uuidsAwaitingPrompt.length = 0;
+    }
+}
+function normalizePromptText(text) {
+    return typeof text === "string" ? text.replace(/\s+/g, " ").trim() : "";
+}
+//# sourceMappingURL=turn-id-reconciler.js.map

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

@@ -0,0 +1,61 @@
+import type { HookEvent } from "@hyperdrive.bot/fleet-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;
+    /**
+     * The claude session id, used to name a tmux session deterministically so a restarted
+     * daemon reattaches the SAME agent instead of starting a second one beside it. Optional
+     * because a bare pty has no use for it.
+     */
+    sessionId?: 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 {
+    /**
+     * True once the underlying agent process has exited.
+     *
+     * Optional so a transport that genuinely cannot know stays honest by omitting it;
+     * `undefined` means "no liveness signal" and must not be read as "alive". Both shipped
+     * transports implement it.
+     */
+    readonly exited?: boolean;
+    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

package/dist/server/server/agent/providers/codex/app-server-transport.js

@@ -0,0 +1,262 @@
+import readline from "node:readline";
+import { z } from "zod";
+import { terminateWithTreeKill } from "../../../../utils/tree-kill.js";
+const DEFAULT_TIMEOUT_MS = 14 * 24 * 60 * 60 * 1000;
+const APP_SERVER_GRACEFUL_SHUTDOWN_TIMEOUT_MS = 2000;
+const APP_SERVER_FORCE_SHUTDOWN_TIMEOUT_MS = 1000;
+const STDERR_BUFFER_LIMIT = 8192;
+const CodexThreadForkResponseSchema = z
+    .object({
+    thread: z
+        .object({
+        id: z.string(),
+        sessionId: z.string().optional(),
+        forkedFromId: z.string().nullable().optional(),
+        turns: z.array(z.unknown()).optional(),
+    })
+        .passthrough(),
+    model: z.string(),
+    modelProvider: z.string(),
+    serviceTier: z.string().nullable(),
+    cwd: z.string(),
+    runtimeWorkspaceRoots: z.array(z.string()).optional().default([]),
+    instructionSources: z.array(z.string()).optional().default([]),
+    approvalPolicy: z.unknown(),
+    approvalsReviewer: z.unknown(),
+    sandbox: z.unknown(),
+    activePermissionProfile: z.unknown().optional(),
+    reasoningEffort: z.string().nullable().optional(),
+})
+    .passthrough();
+export function parseCodexThreadForkResponse(response) {
+    return CodexThreadForkResponseSchema.parse(response);
+}
+const CodexThreadRollbackResponseSchema = z
+    .object({
+    thread: z
+        .object({
+        id: z.string(),
+        sessionId: z.string().optional(),
+        forkedFromId: z.string().nullable().optional(),
+        turns: z.array(z.unknown()).optional(),
+    })
+        .passthrough(),
+})
+    .passthrough();
+export function parseCodexThreadRollbackResponse(response) {
+    return CodexThreadRollbackResponseSchema.parse(response);
+}
+function isRecord(value) {
+    return value != null && typeof value === "object" && !Array.isArray(value);
+}
+function isJsonRpcResponse(msg) {
+    if (!isRecord(msg))
+        return false;
+    return typeof msg.id === "number";
+}
+function isJsonRpcRequest(msg) {
+    if (!isRecord(msg))
+        return false;
+    return typeof msg.id === "number" && typeof msg.method === "string";
+}
+function isJsonRpcNotification(msg) {
+    if (!isRecord(msg))
+        return false;
+    return typeof msg.method === "string" && msg.id === undefined;
+}
+function readProviderSessionId(params) {
+    if (!isRecord(params)) {
+        return undefined;
+    }
+    return typeof params.threadId === "string" ? params.threadId : undefined;
+}
+function readProviderTurnId(params) {
+    if (!isRecord(params)) {
+        return undefined;
+    }
+    if (typeof params.turnId === "string") {
+        return params.turnId;
+    }
+    const turn = params.turn;
+    return isRecord(turn) && typeof turn.id === "string" ? turn.id : undefined;
+}
+export class CodexAppServerClient {
+    constructor(child, logger, getTraceContext = () => ({})) {
+        this.child = child;
+        this.logger = logger;
+        this.getTraceContext = getTraceContext;
+        this.pending = new Map();
+        this.requestHandlers = new Map();
+        this.notificationHandler = null;
+        this.nextId = 1;
+        this.disposed = false;
+        this.stderrBuffer = "";
+        this.rl = readline.createInterface({ input: child.stdout });
+        this.rl.on("line", (line) => {
+            void this.handleLine(line).catch((error) => {
+                this.logger.warn({ error, line }, "Failed to handle Codex app-server stdout line");
+            });
+        });
+        child.stderr.on("data", (chunk) => {
+            this.stderrBuffer += chunk.toString();
+            if (this.stderrBuffer.length > STDERR_BUFFER_LIMIT) {
+                this.stderrBuffer = this.stderrBuffer.slice(-STDERR_BUFFER_LIMIT);
+            }
+        });
+        child.on("error", (err) => {
+            this.logger.error({ err }, "Codex app-server child process error");
+            for (const pending of this.pending.values()) {
+                clearTimeout(pending.timer);
+                pending.reject(err);
+            }
+            this.pending.clear();
+            this.disposed = true;
+        });
+        child.on("exit", (code, signal) => {
+            const message = code === 0 && !signal
+                ? "Codex app-server exited"
+                : `Codex app-server exited with code ${code ?? "null"} and signal ${signal ?? "null"}`;
+            const error = new Error(`${message}\n${this.stderrBuffer}`.trim());
+            for (const pending of this.pending.values()) {
+                clearTimeout(pending.timer);
+                pending.reject(error);
+            }
+            this.pending.clear();
+            this.disposed = true;
+        });
+    }
+    setNotificationHandler(handler) {
+        this.notificationHandler = handler;
+    }
+    setRequestHandler(method, handler) {
+        this.requestHandlers.set(method, handler);
+    }
+    request(method, params, timeoutMs = DEFAULT_TIMEOUT_MS) {
+        if (this.disposed) {
+            return Promise.reject(new Error("Codex app-server client is closed"));
+        }
+        const id = this.nextId++;
+        const payload = { id, method, params };
+        const serialized = JSON.stringify(payload);
+        this.child.stdin.write(`${serialized}\n`);
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`Codex app-server request timed out for ${method}`));
+            }, timeoutMs);
+            this.pending.set(id, { resolve, reject, timer });
+        });
+    }
+    async forkThread(params) {
+        return parseCodexThreadForkResponse(await this.request("thread/fork", params));
+    }
+    async rollbackThread(params) {
+        return parseCodexThreadRollbackResponse(await this.request("thread/rollback", params));
+    }
+    notify(method, params) {
+        if (this.disposed) {
+            return;
+        }
+        const payload = { method, params };
+        this.child.stdin.write(`${JSON.stringify(payload)}\n`);
+    }
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.rl.close();
+        try {
+            this.child.stdin.end();
+        }
+        catch {
+            // ignore
+        }
+        const result = await terminateWithTreeKill(this.child, {
+            gracefulTimeoutMs: APP_SERVER_GRACEFUL_SHUTDOWN_TIMEOUT_MS,
+            forceTimeoutMs: APP_SERVER_FORCE_SHUTDOWN_TIMEOUT_MS,
+            onForceSignal: () => {
+                this.logger.warn({ timeoutMs: APP_SERVER_GRACEFUL_SHUTDOWN_TIMEOUT_MS }, "Codex app-server did not exit after SIGTERM; sending SIGKILL");
+            },
+        });
+        if (result === "kill-timeout") {
+            this.logger.warn({ timeoutMs: APP_SERVER_FORCE_SHUTDOWN_TIMEOUT_MS }, "Codex app-server did not report exit after SIGKILL");
+        }
+    }
+    writeJsonRpcResponse(response) {
+        if (this.disposed || this.child.stdin.destroyed || !this.child.stdin.writable) {
+            return;
+        }
+        try {
+            this.child.stdin.write(`${JSON.stringify(response)}\n`);
+        }
+        catch (error) {
+            this.logger.debug({ error }, "Failed to write Codex app-server JSON-RPC response");
+        }
+    }
+    async handleLine(line) {
+        if (!line.trim())
+            return;
+        let raw;
+        try {
+            raw = JSON.parse(line);
+        }
+        catch (error) {
+            this.logger.warn({ error, line }, "Ignoring non-JSON Codex app-server stdout line");
+            return;
+        }
+        if (!isRecord(raw)) {
+            this.logger.warn({ line }, "Parsed JSON is not an object");
+            return;
+        }
+        if (isJsonRpcResponse(raw)) {
+            const id = raw.id;
+            if (raw.result !== undefined || raw.error) {
+                const pending = this.pending.get(id);
+                if (!pending)
+                    return;
+                clearTimeout(pending.timer);
+                this.pending.delete(id);
+                if (raw.error) {
+                    pending.reject(new Error(raw.error.message ?? "Unknown error"));
+                }
+                else {
+                    pending.resolve(raw.result);
+                }
+                return;
+            }
+            if (isJsonRpcRequest(raw)) {
+                const request = raw;
+                this.traceRawEvent(request);
+                const handler = this.requestHandlers.get(request.method);
+                try {
+                    const result = handler ? await handler(request.params) : {};
+                    this.writeJsonRpcResponse({ id: request.id, result });
+                }
+                catch (error) {
+                    this.writeJsonRpcResponse({
+                        id: request.id,
+                        error: { message: error instanceof Error ? error.message : String(error) },
+                    });
+                }
+                return;
+            }
+        }
+        if (isJsonRpcNotification(raw)) {
+            this.traceRawEvent(raw);
+            this.notificationHandler?.(raw.method, raw.params);
+        }
+    }
+    traceRawEvent(raw) {
+        const traceContext = this.getTraceContext();
+        this.logger.trace({
+            provider: "codex",
+            agentId: traceContext.agentId,
+            sessionId: traceContext.sessionId ?? readProviderSessionId(raw.params),
+            turnId: traceContext.turnId ?? readProviderTurnId(raw.params),
+            method: raw.method,
+            params: raw.params,
+            rawEvent: raw,
+        }, "provider.codex.raw_event");
+    }
+}
+//# sourceMappingURL=app-server-transport.js.map

package/dist/server/server/agent/providers/codex/rewind.d.ts

@@ -0,0 +1,21 @@
+import type { CodexThreadForkParams, CodexThreadForkResponse, CodexThreadRollbackParams, CodexThreadRollbackResponse } from "./app-server-transport.js";
+export interface CodexRewindClient {
+    forkThread?(params: CodexThreadForkParams): Promise<CodexThreadForkResponse>;
+    rollbackThread?(params: CodexThreadRollbackParams): Promise<CodexThreadRollbackResponse>;
+    request(method: string, params?: unknown, timeoutMs?: number): Promise<unknown>;
+}
+export interface CodexUserMessageTurnIndex {
+    resolve(messageId: string): number | null;
+    count(): number;
+}
+export declare function revertCodexConversation(input: {
+    client: CodexRewindClient;
+    threadId: string | null;
+    messageId: string;
+    cwd?: string | null;
+    model?: string | null;
+    serviceTier?: string | null;
+    userMessageTurns: CodexUserMessageTurnIndex;
+    setThreadId: (threadId: string) => void | Promise<void>;
+}): Promise<void>;
+//# sourceMappingURL=rewind.d.ts.map

package/dist/server/server/agent/providers/codex/rewind.js

@@ -0,0 +1,46 @@
+import { parseCodexThreadForkResponse, parseCodexThreadRollbackResponse, } from "./app-server-transport.js";
+async function forkCodexThread(client, params) {
+    if (client.forkThread) {
+        return client.forkThread(params);
+    }
+    return parseCodexThreadForkResponse(await client.request("thread/fork", params));
+}
+async function rollbackCodexThread(client, params) {
+    if (client.rollbackThread) {
+        return client.rollbackThread(params);
+    }
+    return parseCodexThreadRollbackResponse(await client.request("thread/rollback", params));
+}
+export async function revertCodexConversation(input) {
+    if (!input.threadId) {
+        throw new Error("Codex thread is not ready for rewind");
+    }
+    const targetTurnIndex = input.userMessageTurns.resolve(input.messageId);
+    if (targetTurnIndex === null) {
+        throw new Error(`Codex could not find user message ${input.messageId} in the current thread`);
+    }
+    const currentUserTurnCount = input.userMessageTurns.count();
+    const numTurns = currentUserTurnCount - targetTurnIndex;
+    if (numTurns < 0) {
+        throw new Error(`Codex user message ${input.messageId} is outside the current thread`);
+    }
+    // Fork is non-destructive: the old thread file stays on disk and remains
+    // recoverable with `codex resume <old-uuid>` if the rewind target was wrong.
+    const forked = await forkCodexThread(input.client, {
+        threadId: input.threadId,
+        cwd: input.cwd ?? null,
+        model: input.model ?? null,
+        serviceTier: input.serviceTier ?? null,
+        excludeTurns: false,
+        persistExtendedHistory: true,
+    });
+    const forkedThreadId = forked.thread.id;
+    // Codex rollback is chat-only by design. File edits from rewound turns stay
+    // on disk; a future file primitive would be a separate capability.
+    const rolledBack = await rollbackCodexThread(input.client, {
+        threadId: forkedThreadId,
+        numTurns,
+    });
+    await input.setThreadId(rolledBack.thread.id);
+}
+//# sourceMappingURL=rewind.js.map

package/dist/server/server/agent/providers/codex/test-utils/fake-app-server.d.ts

@@ -0,0 +1,36 @@
+import type { ChildProcessWithoutNullStreams } from "node:child_process";
+import { PassThrough } from "node:stream";
+import type { AgentSession, AgentStreamEvent } from "../../../agent-sdk-types.js";
+type JsonObject = Record<string, unknown>;
+type FakeCodexAppServerHandler = (params: unknown) => unknown;
+type CodexAppServerChildProcess = ChildProcessWithoutNullStreams & {
+    stdin: PassThrough;
+    stdout: PassThrough;
+    stderr: PassThrough;
+};
+export interface FakeCodexAppServer {
+    readonly child: CodexAppServerChildProcess;
+    readonly recordedRollbacks: JsonObject[];
+    assertNoErrors(): void;
+    waitForTurnStart(): Promise<JsonObject>;
+    nextResponse(): Promise<string>;
+    completeTurn(params?: {
+        threadId?: string;
+    }): void;
+    requestCommandApproval(params: {
+        itemId: string;
+        threadId: string;
+        turnId: string;
+        command: string;
+        cwd: string;
+        reason: string;
+    }): void;
+    waitForCommandApprovalDecision(itemId: string): Promise<unknown>;
+}
+export declare function createCodexAppServerChildProcess(): CodexAppServerChildProcess;
+export declare function createFakeCodexAppServer(handlers?: Record<string, FakeCodexAppServerHandler>): FakeCodexAppServer;
+export declare function waitForNextPermission(session: AgentSession): Promise<Extract<AgentStreamEvent, {
+    type: "permission_requested";
+}>>;
+export {};
+//# sourceMappingURL=fake-app-server.d.ts.map