@neta-art/cohub-cli 8.1.1 → 8.3.0

package/dist/runtime/native/results.js

@@ -0,0 +1,128 @@
+import { readdir, readFile, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { RUNTIME_RECOVERY_BATCH_SIZE, runtimeEventSchema } from "@neta-art/cohub";
+import { atomicRuntimeJson } from "../archive-store.js";
+import { confirmQuiescentProcessGroup } from "../process-group.js";
+import { readTranscript } from "./adapters.js";
+export class ContextRequiredError extends Error {
+}
+const missing = (error) => error?.code === "ENOENT";
+/** One small receipt per Cohub-executed Turn until the server acknowledges its result. */
+export class ExecutionResults {
+    root;
+    constructor(root) {
+        this.root = root;
+    }
+    path(sessionId) { return join(this.root, "executions", `${sessionId}.json`); }
+    async read(sessionId) {
+        try {
+            const receipt = JSON.parse(await readFile(this.path(sessionId), "utf8"));
+            if (receipt.version !== 2 || receipt.sessionId !== sessionId)
+                throw new Error("Invalid execution receipt");
+            return receipt;
+        }
+        catch (error) {
+            if (missing(error))
+                return null;
+            throw error;
+        }
+    }
+    /**
+     * Admit a new Turn. An unacknowledged earlier Turn is released once the server has settled it;
+     * otherwise the server must decide first, so a result is never overwritten unseen.
+     */
+    async admit(input) {
+        const receipt = await this.read(input.sessionId);
+        if (!receipt || receipt.turnId === input.turnId)
+            return null;
+        const { resolvedTurnIds, settledTurnIds, complete } = input.context;
+        const resolved = resolvedTurnIds?.includes(receipt.turnId) === true;
+        if (resolved || settledTurnIds?.includes(receipt.turnId)) {
+            await rm(this.path(input.sessionId), { force: true });
+            return resolved ? receipt.session.path : null;
+        }
+        if (complete === false)
+            throw new ContextRequiredError("Server resolution is required for the pending native execution");
+        throw new Error(`Local turn ${receipt.turnId} has unconfirmed results; reconcile it before continuing`);
+    }
+    async start(session, input, requestId) {
+        await atomicRuntimeJson(this.path(input.sessionId), { version: 2, requestId, sessionId: input.sessionId, turnId: input.turnId, session });
+    }
+    async record(session, input, requestId, events, uncertainCleanup) {
+        await atomicRuntimeJson(this.path(input.sessionId), { version: 2, requestId, sessionId: input.sessionId, turnId: input.turnId, session, events, ...(uncertainCleanup ? { uncertainCleanup } : {}) });
+    }
+    async recover(input, requestId) {
+        const receipt = await this.read(input.sessionId);
+        if (!receipt || receipt.turnId !== input.turnId || receipt.session.harness !== input.harness)
+            return null;
+        if (requestId && receipt.requestId != null && receipt.requestId !== requestId)
+            throw new Error("Runtime result execution identity mismatch");
+        if (receipt.events) {
+            // A quiescent process group upgrades the receipt to confirmed; a live one stays uncertain.
+            if (receipt.uncertainCleanup && !receipt.uncertainCleanup.confirmedAt) {
+                if (!await confirmQuiescentProcessGroup(receipt.uncertainCleanup.processGroupId))
+                    return null;
+                receipt.uncertainCleanup.confirmedAt = new Date().toISOString();
+                await atomicRuntimeJson(this.path(input.sessionId), receipt);
+            }
+            return { session: receipt.session, events: receipt.events.map((event) => runtimeEventSchema.parse(event)) };
+        }
+        const events = await this.fromTranscript(receipt);
+        if (!events)
+            return null;
+        await this.record(receipt.session, receipt, receipt.requestId, events);
+        return { session: receipt.session, events };
+    }
+    async acknowledge(sessionId, turnId) {
+        const receipt = await this.read(sessionId);
+        if (receipt?.turnId !== turnId)
+            throw new Error("Runtime acknowledgement identity mismatch");
+        await rm(this.path(sessionId), { force: true });
+    }
+    async pendingTurnIds(sessionId) {
+        const receipt = await this.read(sessionId);
+        return receipt ? [receipt.turnId] : [];
+    }
+    async *pendingBatches() {
+        const names = await readdir(join(this.root, "executions")).catch((error) => { if (missing(error))
+            return []; throw error; });
+        let batch = [];
+        for (const name of names) {
+            if (!name.endsWith(".json"))
+                continue;
+            const receipt = await this.read(name.slice(0, -5)).catch(() => null);
+            if (!receipt)
+                continue;
+            batch.push({ sessionId: receipt.sessionId, turnId: receipt.turnId, harness: receipt.session.harness });
+            if (batch.length >= RUNTIME_RECOVERY_BATCH_SIZE) {
+                yield batch;
+                batch = [];
+            }
+        }
+        if (batch.length)
+            yield batch;
+    }
+    async fromTranscript(receipt) {
+        const transcript = await readTranscript(receipt.session.path, receipt.session.harness).catch(() => null);
+        const turn = transcript?.turns.find((entry) => entry.cloudTurnId === receipt.turnId);
+        const result = turn?.result;
+        if (!result || result.status === "interrupted" || turn !== transcript?.turns.at(-1))
+            return null;
+        const messages = result.messages.filter((message) => message.content.length);
+        if (!messages.length)
+            return null;
+        const message = (entry, ordinal) => ({
+            ordinal,
+            content: entry.content,
+            provider: entry.provider ?? null,
+            model: entry.model ?? null,
+            usage: (entry.usage ?? null),
+            stopReason: entry.stopReason ?? "stop",
+            errorMessage: entry.errorMessage ?? null,
+        });
+        return [
+            ...messages.slice(0, -1).map((entry, index) => ({ type: "message.commit", message: message(entry, index) })),
+            { type: "turn.end", message: message(messages.at(-1), messages.length - 1), resume: "native", archive: null },
+        ];
+    }
+}

package/dist/runtime/native/sessions.d.ts

@@ -0,0 +1,45 @@
+import { type RuntimeContext } from "@neta-art/cohub";
+import type { SessionTurnProjectionClient } from "../turn-projection.js";
+import type { RuntimeArchiveStore } from "../archive-store.js";
+import type { NativeIngest, TranscriptState } from "./ingest.js";
+/** How the native file for a Turn was obtained; reported with the Turn result. */
+export type ResumeKind = "native" | "restored" | "handoff" | "new";
+export type NativeSession = {
+    harness: "pi" | "codex";
+    nativeSessionId: string;
+    path: string;
+    cwd: string;
+};
+export type PreparedSession = {
+    session: NativeSession;
+    resume: ResumeKind;
+};
+/** Chooses the native file a Turn runs in. 1. */
+export declare class NativeSessions {
+    private readonly options;
+    private readonly projections;
+    constructor(options: {
+        root: string;
+        spaceId: string;
+        projectionSource: SessionTurnProjectionClient;
+        archives: RuntimeArchiveStore;
+        ingest: NativeIngest;
+        onRestoreFailed?: (error: unknown, context: {
+            sessionId: string;
+            harness: "pi" | "codex";
+            unrestorable: boolean;
+        }) => void;
+    });
+    prepare(input: {
+        sessionId: string;
+        turnId: string;
+        harness: "pi" | "codex";
+        cwd: string;
+        provider?: string | null;
+        context: RuntimeContext;
+        resumable: (transcript: TranscriptState) => boolean;
+        signal?: AbortSignal;
+    }): Promise<PreparedSession>;
+    private restore;
+    private project;
+}

package/dist/runtime/native/sessions.js

@@ -0,0 +1,92 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { serializeProjectionRecords } from "@neta-art/cohub";
+import { ArchiveNotRestorableError, importNativeArchive } from "./archive.js";
+import { piSessionDirectoryName, readTranscript } from "./adapters.js";
+import { ProjectionStore, rebindProjectionNativeSession } from "../projection-store.js";
+/** Chooses the native file a Turn runs in. 1. */
+export class NativeSessions {
+    options;
+    projections;
+    constructor(options) {
+        this.options = options;
+        this.projections = new ProjectionStore(options.projectionSource);
+    }
+    async prepare(input) {
+        const existing = this.options.ingest.transcriptFor(input.sessionId, input.harness, input.context.throughTurnId);
+        if (existing && input.resumable(existing)) {
+            return { session: { harness: existing.harness, nativeSessionId: existing.nativeSessionId, path: existing.path, cwd: existing.cwd }, resume: "native" };
+        }
+        const archive = input.context.archive;
+        if (archive && archive.harness === input.harness && archive.sessionId === input.sessionId && archive.turnId === input.context.throughTurnId) {
+            const restored = await this.restore(input, archive, input.signal).catch((error) => {
+                input.signal?.throwIfAborted();
+                // A structurally unrestorable archive falls back to projection; so does a transient
+                // failure, which simply tries the archive again on the next Turn.
+                this.options.onRestoreFailed?.(error, { sessionId: input.sessionId, harness: input.harness, unrestorable: error instanceof ArchiveNotRestorableError });
+                return null;
+            });
+            if (restored) {
+                // A restored copy is history the server already has, even where it carries no markers.
+                const through = (await readTranscript(restored.path, restored.harness).catch(() => null))?.turns.at(-1)?.key ?? null;
+                this.options.ingest.adopt(restored, input.sessionId, { turnKey: through, turnId: input.context.throughTurnId });
+                return { session: restored, resume: "restored" };
+            }
+        }
+        const projected = await this.project(input);
+        // A new Codex thread gets its file when it starts; the executor adopts it then.
+        if (projected.resume !== "new" || input.harness === "pi")
+            this.options.ingest.adopt(projected.session, input.sessionId);
+        return projected;
+    }
+    async restore(input, archive, signal) {
+        const id = randomUUID();
+        const raw = join(this.options.root, "native", "restored", `${id}.jsonl`);
+        const path = nativePath(input.harness, id, input.cwd);
+        try {
+            const restored = await this.options.archives.restore(archive, raw, signal);
+            const imported = await importNativeArchive({ source: raw, target: path, harness: input.harness, nativeSessionId: restored.nativeSessionId, id, cwd: input.cwd, signal });
+            return { harness: input.harness, nativeSessionId: imported.nativeSessionId, path, cwd: input.cwd };
+        }
+        finally {
+            await rm(raw, { force: true }).catch(() => undefined);
+        }
+    }
+    async project(input) {
+        const nativeSessionId = randomUUID();
+        const path = nativePath(input.harness, nativeSessionId, input.cwd);
+        const projection = rebindProjectionNativeSession(await this.projections.project({
+            spaceId: this.options.spaceId,
+            sessionId: input.sessionId,
+            turnId: input.turnId,
+            nativeSessionId,
+            cwd: input.cwd,
+            provider: input.provider,
+            target: input.harness,
+            throughTurnId: input.context.throughTurnId,
+        }, input.signal), nativeSessionId);
+        const session = { harness: input.harness, nativeSessionId, path, cwd: input.cwd };
+        // An empty Codex thread is created by Codex itself when the Turn starts.
+        if (!projection.turns.length && input.harness === "codex")
+            return { session, resume: "new" };
+        await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+        const temporary = `${path}.${randomUUID()}.projection`;
+        await writeFile(temporary, serializeProjectionRecords(projection.projection.records), { mode: 0o600 });
+        await rename(temporary, path);
+        return { session, resume: projection.turns.length ? "handoff" : "new" };
+    }
+}
+/** Where a harness keeps a new transcript for the bound directory. */
+function nativePath(harness, nativeSessionId, cwd) {
+    const stamp = new Date().toISOString();
+    if (harness === "pi") {
+        const agent = process.env.PI_CODING_AGENT_DIR?.trim() || join(homedir(), ".pi", "agent");
+        const directory = process.env.PI_CODING_AGENT_SESSION_DIR?.trim() || join(agent, "sessions", piSessionDirectoryName(cwd));
+        return join(directory, `${stamp.replace(/[:.]/g, "-")}_${nativeSessionId}.jsonl`);
+    }
+    const home = process.env.CODEX_HOME?.trim() || join(homedir(), ".codex");
+    const day = stamp.replace(/\.\d{3}Z$/, "").replaceAll(":", "-");
+    return join(home, "sessions", day.slice(0, 4), day.slice(5, 7), day.slice(8, 10), `rollout-${day}-${nativeSessionId}.jsonl`);
+}

package/dist/runtime/native/transcript.d.ts

@@ -0,0 +1,63 @@
+import type { ContentBlock, NativeTurnComplete, NativeTurnMessage } from "@neta-art/cohub";
+export type NativeTranscriptTurn = {
+    key: string;
+    parentKey: string | null;
+    cloudTurnId?: string;
+    userContent: ContentBlock[];
+    /**
+     * Codex records a prompt in several steps and the final form last; until this is set the user
+     * content may still change.
+     */
+    userFinal?: boolean;
+    messages: NativeTurnMessage[];
+    startedAt: string;
+    startBytes: number;
+    endBytes: number;
+    contentEndBytes: number;
+    boundaries: Record<number, string>;
+    sha256: string;
+    result: NativeTurnComplete | null;
+    path?: string;
+    rolloutId?: string;
+    sequence?: number;
+};
+export type NativeTranscript = {
+    nativeSessionId: string;
+    cwd: string;
+    cloudSessionId?: string;
+    turns: NativeTranscriptTurn[];
+    prefixes: ReadonlyMap<number, string>;
+    lineagePaths?: string[];
+    lineageRolloutIds?: string[];
+};
+export declare const NATIVE_MAX_RECORD_BYTES: number;
+export declare const NATIVE_MAX_TRANSCRIPT_BYTES: number;
+export declare const codexSessionsDirectory: () => string;
+export declare const codexArchivedSessionsDirectory: () => string;
+/** Ordinary rollout names encode one id; reverted threads append `_rollout-id`. */
+export declare function codexRolloutIdOf(fileName: string): string | null;
+export type CodexHistoryBase = {
+    rolloutId: string;
+    endOrdinal: number;
+    endBytes: number;
+};
+export type NativeTranscriptHeader = {
+    nativeSessionId: string;
+    cwd: string;
+    rolloutId?: string;
+    historyBase?: CodexHistoryBase;
+};
+/** Read only the session header before deciding whether a global Codex file belongs to this project. */
+export declare function readNativeTranscriptHeader(path: string, harness: "pi" | "codex", signal?: AbortSignal): Promise<NativeTranscriptHeader>;
+/** Raw JSONL bytes of a rollout, transparently decompressing `.zst` and honoring a lineage cutoff. */
+export declare function codexRolloutBytes(path: string, endBytes: number | null, signal?: AbortSignal): AsyncGenerator<Buffer>;
+/** Cache location for a rollout's decompressed copy; shared by capture and archival. */
+export declare function codexRolloutCachePath(source: string, cacheDirectory: string): string;
+/** Archives need plain JSONL bytes; decompress a cold `.zst` rollout into a cache once. */
+export declare function ensurePlainCodexRollout(path: string, cacheDirectory: string, signal?: AbortSignal, maxBytes?: number): Promise<string>;
+/** Partial trailing records are retried, never parsed or acknowledged as complete. */
+export declare function readNativeTranscript(path: string, harness: "pi" | "codex", options?: {
+    settled?: boolean;
+    leafId?: string | null;
+    signal?: AbortSignal;
+}): Promise<NativeTranscript>;