@neta-art/cohub-cli 6.12.0 → 7.0.1

package/dist/runtime/native-archive.js

@@ -0,0 +1,88 @@
+import { createHash, randomUUID } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { link, mkdir, open, rm } from "node:fs/promises";
+import { dirname } from "node:path";
+import { RUNTIME_MAX_FRAME_BYTES } from "@neta-art/cohub";
+import { JsonLineDecoder } from "./json-rpc.js";
+import { codexArchiveTotals } from "./codex-usage.js";
+export async function readCodexArchiveTotals(path) {
+    let totals;
+    const decoder = new JsonLineDecoder((row) => { totals = codexArchiveTotals([row]) ?? totals; });
+    for await (const bytes of createReadStream(path))
+        decoder.push(bytes);
+    decoder.end();
+    return totals;
+}
+/** Change only the header of a working copy. Raw archive bytes remain untouched. */
+export async function importNativeArchive(input) {
+    await mkdir(dirname(input.target), { recursive: true, mode: 0o700 });
+    const temporary = `${input.target}.${randomUUID()}.importing`;
+    const file = await open(temporary, "wx", 0o600);
+    const digest = createHash("sha256");
+    let headerReady = false, headerBytes = 0;
+    const fragments = [];
+    let totals;
+    const decoder = input.harness === "codex" ? new JsonLineDecoder((row) => { totals = codexArchiveTotals([row]) ?? totals; }) : null;
+    const write = async (bytes) => { digest.update(bytes); await file.writeFile(bytes); };
+    const writeHeader = async () => {
+        const header = JSON.parse(Buffer.concat(fragments).toString("utf8"));
+        if (input.harness === "pi") {
+            if (header?.type !== "session" || header.id !== input.nativeSessionId)
+                throw new Error("Pi archive identity mismatch");
+            header.cwd = input.cwd;
+            delete header.parentSession;
+        }
+        else {
+            if (header?.type !== "session_meta" || header.payload?.id !== input.nativeSessionId)
+                throw new Error("Codex archive identity mismatch");
+            header.payload.id = input.id;
+            if (header.payload.session_id != null)
+                header.payload.session_id = input.id;
+            header.payload.history_mode = "legacy";
+            header.payload.cwd = input.cwd;
+        }
+        await write(Buffer.from(`${JSON.stringify(header)}\n`));
+        fragments.length = 0;
+        headerReady = true;
+    };
+    try {
+        for await (const bytes of createReadStream(input.source, { signal: input.signal })) {
+            decoder?.push(bytes);
+            if (headerReady) {
+                await write(bytes);
+                continue;
+            }
+            const newline = bytes.indexOf(10);
+            const prefix = newline < 0 ? bytes : bytes.subarray(0, newline);
+            headerBytes += prefix.length;
+            if (headerBytes > RUNTIME_MAX_FRAME_BYTES)
+                throw new Error("Native header is too large");
+            fragments.push(prefix);
+            if (newline >= 0) {
+                await writeHeader();
+                await write(bytes.subarray(newline + 1));
+            }
+        }
+        if (!headerReady)
+            await writeHeader();
+        decoder?.end();
+        input.signal?.throwIfAborted();
+        await file.sync();
+        await file.close();
+        await link(temporary, input.target);
+        if (process.platform !== "win32") {
+            const directory = await open(dirname(input.target), "r");
+            try {
+                await directory.sync();
+            }
+            finally {
+                await directory.close();
+            }
+        }
+        return { checksum: digest.digest("hex"), nativeSessionId: input.harness === "pi" ? input.nativeSessionId : input.id, codexTokenTotals: totals };
+    }
+    finally {
+        await file.close();
+        await rm(temporary, { force: true });
+    }
+}

package/dist/runtime/process-group.d.ts

@@ -0,0 +1,3 @@
+export declare class ProcessCleanupUncertainError extends Error {
+}
+export declare function stopProcessGroup(pid: number): Promise<void>;

package/dist/runtime/process-group.js

@@ -0,0 +1,68 @@
+import { readdir, readFile } from "node:fs/promises";
+import { setTimeout as delay } from "node:timers/promises";
+import { spawn } from "node:child_process";
+export class ProcessCleanupUncertainError extends Error {
+}
+async function groupAlive(pid) {
+    try {
+        process.kill(-pid, 0);
+    }
+    catch (error) {
+        if (error.code === "ESRCH")
+            return false;
+        throw error;
+    }
+    if (process.platform !== "linux")
+        return true;
+    // Linux can retain reparented zombies: they cannot execute, but kill(0) still sees them.
+    for (const entry of await readdir("/proc")) {
+        if (!/^\d+$/.test(entry))
+            continue;
+        try {
+            const stat = await readFile(`/proc/${entry}/stat`, "utf8");
+            // After removing `pid (comm)`: state, ppid, pgrp, session, ...
+            const [state, _parentPid, processGroupId] = stat.slice(stat.lastIndexOf(")") + 2).split(" ");
+            if (Number(processGroupId) === pid && state !== "Z" && state !== "X")
+                return true;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT" && error.code !== "ESRCH")
+                throw error;
+        }
+    }
+    return false;
+}
+export async function stopProcessGroup(pid) {
+    try {
+        if (process.platform === "win32") {
+            await new Promise((resolve, reject) => {
+                const task = spawn("taskkill", ["/PID", String(pid), "/T", "/F"], { stdio: "ignore", timeout: 5000 });
+                task.once("error", reject);
+                task.once("exit", (code) => code === 0 ? resolve() : reject(new Error(`taskkill exited ${code}`)));
+            });
+            return;
+        }
+        const signal = (value) => {
+            try {
+                process.kill(-pid, value);
+            }
+            catch (error) {
+                if (error.code !== "ESRCH")
+                    throw error;
+            }
+        };
+        signal("SIGTERM");
+        const started = Date.now();
+        while (await groupAlive(pid)) {
+            const elapsed = Date.now() - started;
+            if (elapsed >= 5000)
+                throw new Error("Process group is still running");
+            if (elapsed >= 2000)
+                signal("SIGKILL");
+            await delay(25);
+        }
+    }
+    catch (cause) {
+        throw new ProcessCleanupUncertainError("Tool process cleanup could not be confirmed; execution remains unresolved", { cause });
+    }
+}

package/dist/runtime/session-store.d.ts

@@ -0,0 +1,47 @@
+import { type RuntimeExecutionEvent, type HarnessArchive, type RuntimePendingExecution, type RuntimeTurnInput } from "@neta-art/cohub";
+import { RuntimeArchiveStore, type ArchiveTransport } from "./archive-store.js";
+import type { CodexTokenTotals } from "./codex-usage.js";
+export declare class ContextRequiredError extends Error {
+    readonly historyOnly: boolean;
+    constructor(message: string, historyOnly?: boolean);
+}
+export type NativeSession = {
+    version: 1;
+    sessionId: string;
+    harness: "pi" | "codex";
+    nativeSessionId: string;
+    path: string;
+    cwd?: string;
+    throughTurnId: string | null;
+    revision: string;
+    checksum: string;
+    pendingTurnId: string | null;
+    resultChecksum?: string;
+    archivePendingTurnId?: string;
+    codexTokenTotals?: CodexTokenTotals;
+};
+/** Local references are hints validated against actual native files, never cloud existence claims. */
+export declare class RuntimeSessionStore {
+    readonly root: string;
+    readonly archives: RuntimeArchiveStore;
+    private archiveFlush;
+    constructor(spaceId: string, stateRoot?: string, transport?: ArchiveTransport);
+    private statePath;
+    pendingExecutionBatches(): AsyncGenerator<RuntimePendingExecution[]>;
+    flushArchives(signal: AbortSignal): Promise<void>;
+    private flushArchiveOutbox;
+    pendingTurnIds(sessionId: string): Promise<string[]>;
+    prepare(input: RuntimeTurnInput, cwd: string, signal?: AbortSignal): Promise<{
+        state: NativeSession;
+        resume: "native" | "restored" | "handoff" | "new";
+    }>;
+    started(state: NativeSession, turnId: string): Promise<void>;
+    private resultPath;
+    recordResult(state: NativeSession, requestId: string, events: RuntimeExecutionEvent[]): Promise<void>;
+    recoverResult(input: Pick<RuntimeTurnInput, "sessionId" | "harness" | "turnId">, requestId?: string): Promise<{
+        state: NativeSession;
+        events: RuntimeExecutionEvent[];
+    } | null>;
+    archive(state: NativeSession, turnId: string): Promise<HarnessArchive | null>;
+    acknowledge(state: NativeSession, turnId: string, revision: string): Promise<void>;
+}

package/dist/runtime/session-store.js

@@ -0,0 +1,300 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, open, readFile, readdir, rm } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { contextToPiMessages, RUNTIME_RECOVERY_BATCH_SIZE, selectRuntimeContextMessages, runtimeEventSchema } from "@neta-art/cohub";
+import { RuntimeArchiveStore, checksumNativeFile, atomicRuntimeJson as atomicJson } from "./archive-store.js";
+import { importNativeArchive, readCodexArchiveTotals } from "./native-archive.js";
+export class ContextRequiredError extends Error {
+    historyOnly;
+    constructor(message, historyOnly = false) {
+        super(message);
+        this.historyOnly = historyOnly;
+    }
+}
+const checksum = (data) => createHash("sha256").update(data).digest("hex");
+const missing = (error) => error?.code === "ENOENT";
+class CaptureUnavailableError extends Error {
+}
+/** Local references are hints validated against actual native files, never cloud existence claims. */
+export class RuntimeSessionStore {
+    root;
+    archives;
+    archiveFlush = null;
+    constructor(spaceId, stateRoot = join(homedir(), ".local", "state", "cohub", "runtime"), transport) {
+        this.root = join(stateRoot, spaceId);
+        this.archives = new RuntimeArchiveStore(join(this.root, "archives"), transport);
+    }
+    statePath(input) { return join(this.root, input.harness, `${input.sessionId}.json`); }
+    async *pendingExecutionBatches() {
+        let batch = [];
+        for (const harness of ["pi", "codex"]) {
+            const directory = join(this.root, harness);
+            const names = await readdir(directory).catch((error) => { if (missing(error))
+                return []; throw error; });
+            for (const name of names) {
+                if (!name.endsWith(".json"))
+                    continue;
+                try {
+                    const state = JSON.parse(await readFile(join(directory, name), "utf8"));
+                    if (state.version !== 1 || state.harness !== harness || !state.sessionId || !state.pendingTurnId)
+                        continue;
+                    batch.push({ sessionId: state.sessionId, turnId: state.pendingTurnId, harness });
+                    if (batch.length >= RUNTIME_RECOVERY_BATCH_SIZE) {
+                        yield batch;
+                        batch = [];
+                    }
+                }
+                catch (error) {
+                    console.error(`Runtime session state unreadable: ${join(directory, name)}`, error);
+                }
+            }
+        }
+        if (batch.length)
+            yield batch;
+    }
+    async flushArchives(signal) {
+        this.archiveFlush ??= this.flushArchiveOutbox(signal).finally(() => { this.archiveFlush = null; });
+        return this.archiveFlush;
+    }
+    async flushArchiveOutbox(signal) {
+        const captures = join(this.archives.root, "captures");
+        const names = await readdir(captures).catch((error) => { if (missing(error))
+            return []; throw error; });
+        for (const name of names) {
+            signal.throwIfAborted();
+            if (!name.endsWith(".json"))
+                continue;
+            let receipt;
+            try {
+                receipt = await readFile(join(captures, name), "utf8");
+                let state;
+                try {
+                    state = JSON.parse(receipt);
+                }
+                catch {
+                    throw new CaptureUnavailableError("Invalid capture receipt");
+                }
+                const turnId = state?.archivePendingTurnId;
+                if (typeof turnId !== "string" || typeof state?.path !== "string" || typeof state.resultChecksum !== "string") {
+                    throw new CaptureUnavailableError("Invalid capture receipt");
+                }
+                if (!await this.archives.hasCapture(turnId)) {
+                    const digest = await checksumNativeFile(state.path).catch((error) => {
+                        if (missing(error))
+                            throw new CaptureUnavailableError("Native session missing");
+                        throw error;
+                    });
+                    if (digest !== state.resultChecksum)
+                        throw new CaptureUnavailableError("Native session changed; original files retained");
+                    signal.throwIfAborted();
+                    await this.archives.stage(state, turnId);
+                }
+                await rm(join(captures, name), { force: true });
+            }
+            catch (error) {
+                signal.throwIfAborted();
+                if (error instanceof CaptureUnavailableError && receipt !== undefined) {
+                    // Preserve the exact receipt before retiring it from the retry queue. Never alter native files.
+                    await atomicJson(join(this.archives.root, "failed", "captures", `${name}.${checksum(receipt)}.json`), {
+                        receipt, reason: error.message, failedAt: new Date().toISOString(),
+                    });
+                    await rm(join(captures, name), { force: true });
+                    console.error("Archive capture unavailable; receipt retained:", error.message);
+                }
+                else
+                    console.error("Archive capture pending:", error);
+            }
+        }
+        await this.archives.flush(signal);
+    }
+    async pendingTurnIds(sessionId) {
+        const ids = [];
+        for (const harness of ["pi", "codex"]) {
+            try {
+                const state = JSON.parse(await readFile(this.statePath({ sessionId, harness }), "utf8"));
+                if (state.sessionId !== sessionId || state.harness !== harness)
+                    throw new Error("Local session identity mismatch");
+                if (state.pendingTurnId)
+                    ids.push(state.pendingTurnId);
+            }
+            catch (error) {
+                if (!missing(error))
+                    throw error;
+            }
+        }
+        return ids;
+    }
+    async prepare(input, cwd, signal) {
+        let previous = null;
+        try {
+            previous = JSON.parse(await readFile(this.statePath(input), "utf8"));
+        }
+        catch (error) {
+            if (!missing(error))
+                throw new Error("Local session state is unreadable; original files were preserved", { cause: error });
+        }
+        if (previous) {
+            if (previous.sessionId !== input.sessionId || previous.harness !== input.harness)
+                throw new Error("Local session identity mismatch");
+            const pending = previous.pendingTurnId;
+            if (pending) {
+                const resolved = input.context.resolvedTurnIds?.includes(pending) === true;
+                const settled = input.context.settledTurnIds?.includes(pending) === true;
+                const lostAcknowledgement = Boolean(previous.resultChecksum) && pending === input.context.throughTurnId && pending !== input.turnId;
+                // A human-confirmed stop is authoritative: rebuild from durable history instead of
+                // resuming a native projection whose outcome the server never recorded.
+                const retire = resolved || (settled && !lostAcknowledgement);
+                const nativeChecksum = await checksumNativeFile(previous.path).catch((error) => { if (missing(error))
+                    return null; throw error; });
+                if (previous.resultChecksum && (settled || resolved) && nativeChecksum && nativeChecksum !== previous.resultChecksum) {
+                    throw new Error("Native session changed outside Cohub; original data was preserved");
+                }
+                if (retire) {
+                    // The server reached a terminal state for this turn. Archive the local projection and
+                    // rebuild from durable context; native files are never deleted, so nothing is lost.
+                    const receipt = await readFile(this.resultPath(previous), "utf8").catch((error) => { if (missing(error))
+                        return null; throw error; });
+                    const retired = { state: previous, receipt };
+                    await atomicJson(join(this.root, "retired", `${pending}.${checksum(JSON.stringify(retired))}.json`), retired);
+                    previous = null;
+                }
+                else if (lostAcknowledgement) {
+                    // The server already persisted this turn; only our acknowledgement was lost.
+                    await this.acknowledge(previous, pending, input.context.revision);
+                }
+                else if (input.context.complete === false) {
+                    throw new ContextRequiredError("Server resolution is required for the pending native execution");
+                }
+                else {
+                    throw new Error(`Local turn ${pending} has unconfirmed results; reconcile it before continuing`);
+                }
+            }
+        }
+        if (previous) {
+            try {
+                if (await checksumNativeFile(previous.path) !== previous.checksum)
+                    throw new Error("Native session changed outside Cohub; original data was preserved");
+                if (previous.archivePendingTurnId) {
+                    await this.archives.stage(previous, previous.archivePendingTurnId);
+                    previous.archivePendingTurnId = undefined;
+                    await atomicJson(this.statePath(previous), previous);
+                }
+                if (input.harness === "codex" && !previous.codexTokenTotals)
+                    previous.codexTokenTotals = await readCodexArchiveTotals(previous.path);
+                if (previous.cwd === cwd && previous.throughTurnId === input.context.throughTurnId && previous.revision === input.context.revision)
+                    return { state: previous, resume: "native" };
+            }
+            catch (error) {
+                if (!missing(error))
+                    throw error;
+            }
+        }
+        if (input.context.complete === false && !input.context.archive)
+            throw new ContextRequiredError("Full context is required to materialize this session");
+        const id = randomUUID();
+        const path = join(this.root, input.harness, `${id}.jsonl`);
+        const archive = input.context.archive;
+        const restore = archive?.harness === input.harness && archive.sessionId === input.sessionId && archive.turnId === input.context.throughTurnId;
+        const rawPath = join(this.root, "archives", "restored", `${id}.jsonl`);
+        const state = {
+            version: 1, harness: input.harness, sessionId: input.sessionId, nativeSessionId: id,
+            path, cwd, throughTurnId: input.context.throughTurnId, revision: input.context.revision, checksum: "", pendingTurnId: null,
+        };
+        if (restore) {
+            try {
+                const restored = await this.archives.restore(archive, rawPath, signal);
+                Object.assign(state, await importNativeArchive({ source: rawPath, target: path, harness: input.harness, nativeSessionId: restored.nativeSessionId, id, cwd, signal }));
+                return { state, resume: "restored" };
+            }
+            catch (error) {
+                signal?.throwIfAborted();
+                console.error("Native archive unavailable; rebuilding from durable history:", error);
+            }
+        }
+        if (input.context.complete === false)
+            throw new ContextRequiredError("Database history is required after archive recovery failed", true);
+        let data = null;
+        if (input.harness === "pi") {
+            const entries = [{ type: "session", version: 3, id, cwd, timestamp: new Date().toISOString() }];
+            let parentId = null;
+            const history = selectRuntimeContextMessages(input.context.messages);
+            const summary = history[0]?.role === "system" ? history[0].content.find((block) => block.type === "system_note" && block.note_type === "compacted") : undefined;
+            let compaction;
+            if (summary?.type === "system_note") {
+                parentId = randomUUID().slice(0, 8);
+                compaction = { type: "compaction", id: parentId, parentId: null, timestamp: new Date().toISOString(), summary: summary.text,
+                    firstKeptEntryId: "", tokensBefore: history[0]?.meta?.compaction?.tokensBefore ?? 0 };
+                entries.push(compaction);
+            }
+            for (const message of contextToPiMessages(history)) {
+                const entryId = randomUUID().slice(0, 8);
+                if (compaction && !compaction.firstKeptEntryId)
+                    compaction.firstKeptEntryId = entryId;
+                entries.push({ type: "message", id: entryId, parentId, timestamp: new Date().toISOString(), message });
+                parentId = entryId;
+            }
+            data = `${entries.map((entry) => JSON.stringify(entry)).join("\n")}\n`;
+        }
+        if (data != null) {
+            await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+            const file = await open(path, "wx", 0o600);
+            try {
+                await file.writeFile(data);
+                await file.sync();
+            }
+            finally {
+                await file.close();
+            }
+            state.checksum = checksum(data);
+        }
+        return { state, resume: input.context.messages.length ? "handoff" : "new" };
+    }
+    async started(state, turnId) { state.pendingTurnId = turnId; state.resultChecksum = undefined; await atomicJson(this.statePath(state), state); }
+    resultPath(state) { return join(this.root, "results", `${state.sessionId}.${state.harness}.json`); }
+    async recordResult(state, requestId, events) {
+        if (!state.pendingTurnId)
+            throw new Error("Cannot record a result for an idle native session");
+        state.resultChecksum = await checksumNativeFile(state.path);
+        if (state.archivePendingTurnId)
+            await atomicJson(join(this.archives.root, "captures", `${state.archivePendingTurnId}.json`), state);
+        await atomicJson(this.resultPath(state), { requestId, state, events });
+        await atomicJson(this.statePath(state), state);
+    }
+    async recoverResult(input, requestId) {
+        try {
+            const saved = JSON.parse(await readFile(this.resultPath(input), "utf8"));
+            if (saved.state.sessionId !== input.sessionId || saved.state.harness !== input.harness)
+                throw new Error("Runtime result identity mismatch");
+            if (saved.state.pendingTurnId !== input.turnId)
+                return null;
+            if (requestId && saved.requestId !== requestId)
+                throw new Error("Runtime result execution identity mismatch");
+            return { state: saved.state, events: saved.events.map((event) => runtimeEventSchema.parse(event)) };
+        }
+        catch (error) {
+            if (missing(error))
+                return null;
+            throw error;
+        }
+    }
+    async archive(state, turnId) {
+        if (!state.path)
+            return null;
+        state.archivePendingTurnId = turnId;
+        const reference = await this.archives.stage(state, turnId);
+        state.archivePendingTurnId = undefined;
+        return reference;
+    }
+    async acknowledge(state, turnId, revision) {
+        if (state.pendingTurnId !== turnId)
+            throw new Error("Runtime acknowledgement identity mismatch");
+        const currentChecksum = await checksumNativeFile(state.path).catch((error) => { if (missing(error))
+            return state.resultChecksum ?? state.checksum; throw error; });
+        if (state.resultChecksum && currentChecksum !== state.resultChecksum)
+            throw new Error("Native data changed before acknowledgement; files preserved");
+        const acknowledged = { ...state, checksum: currentChecksum, pendingTurnId: null, resultChecksum: undefined, throughTurnId: turnId, revision };
+        await atomicJson(this.statePath(state), acknowledged);
+        Object.assign(state, acknowledged);
+    }
+}

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@neta-art/cohub-cli",
-  "version": "6.12.0",
+  "version": "7.0.1",
   "description": "CLI for Cohub — spaces, sessions, and agent collaboration.",
   "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
   "license": "Apache-2.0",
   "bin": {
     "cohub": "./bin/cohub.js"
@@ -15,18 +18,20 @@
     "NOTICE"
   ],
   "dependencies": {
-    "@neta-art/generation": "^0.1.28",
+    "@neta-art/generation": "^0.1.30",
     "commander": "^15.0.0",
     "pixi.js": "^8.20.1",
     "sharp": "^0.35.4",
-    "@neta-art/cohub": "8.17.0"
+    "@neta-art/cohub": "8.19.0"
   },
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
     "@types/node": "^26.4.0",
-    "typescript": "^7.0.2"
+    "@types/ws": "^8.18.1",
+    "typescript": "^7.0.2",
+    "ws": "^8.21.3"
   },
   "optionalDependencies": {
     "@napi-rs/canvas": "^1.0.8"
@@ -34,6 +39,8 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "test": "node ../../scripts/test/run.mjs 'tests/**/*.test.ts'",
+    "test:runtime": "node --import tsx --test tests/runtime-*.integration.ts",
+    "test:runtime:native": "node --import tsx tests/runtime-native.smoke.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   }
 }

package/dist/commands/sandbox.d.ts

@@ -1,3 +0,0 @@
-import type { Command } from "commander";
-export declare const resolveLocalSpaceName: (rootDir: string, requestedName?: string) => string;
-export declare function registerSandbox(program: Command): void;