@neta-art/cohub-cli 10.4.4 → 10.6.0

package/dist/runtime/harnesses/claude.js

@@ -0,0 +1,94 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { copyNativeArchive } from "../native/archive.js";
+import { projectChainedSession, projectionMeta, projectionToolId, rebindSessionId } from "./chained-projection.js";
+import { DEFAULT_MODEL, runStreamJson, streamJsonHelp, streamJsonModel } from "./stream-json.js";
+const MAX_PROJECT_NAME = 200;
+const dataRoot = () => process.env.CLAUDE_CONFIG_DIR?.trim() || join(homedir(), ".claude");
+/**
+ * Claude Code names a project directory by replacing every non-alphanumeric UTF-16 unit; a longer
+ * name keeps its first 200 units and appends the base-36 Java string hash of the path.
+ */
+export function claudeProjectName(cwd) {
+    const name = cwd.replace(/[^a-zA-Z0-9]/g, "-");
+    if (name.length <= MAX_PROJECT_NAME)
+        return name;
+    let hash = 0;
+    for (let index = 0; index < cwd.length; index++)
+        hash = (hash * 31 + cwd.charCodeAt(index)) | 0;
+    return `${name.slice(0, MAX_PROJECT_NAME)}-${Math.abs(hash).toString(36)}`;
+}
+export const claudeProjectDirectory = (cwd) => join(dataRoot(), "projects", claudeProjectName(cwd));
+const profile = {
+    harness: "claude",
+    label: "Claude Code",
+    binary: "claude",
+    provider: "anthropic",
+    dataRoot,
+    projectDirectory: claudeProjectDirectory,
+    effortLevels: ["low", "medium", "high", "xhigh", "max"],
+};
+function anthropicBlock(block) {
+    if (block.type === "text")
+        return { type: "text", text: block.text };
+    if (block.type === "image" && block.source.type === "base64")
+        return { type: "image", source: { type: "base64", media_type: block.source.media_type, data: block.source.data } };
+    if (block.type === "tool_use")
+        return { type: "tool_use", id: projectionToolId(block.id), name: block.name.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 128) || "tool", input: block.input };
+    if (block.type === "tool_result") {
+        const content = typeof block.content === "string" ? block.content : block.content.map(anthropicBlock).filter((item) => item !== null);
+        return { type: "tool_result", tool_use_id: projectionToolId(block.tool_use_id), content, is_error: block.is_error ?? false };
+    }
+    return null;
+}
+/** Claude Code merges consecutive assistant records sharing a message id; each projected call gets its own. */
+function withAssistantIds(projection) {
+    return { ...projection, records: projection.records.map((entry) => entry.record.type !== "assistant" ? entry : {
+            ...entry, record: { ...entry.record, message: { id: `msg_${String(entry.record.uuid).replaceAll("-", "")}`, ...entry.record.message } },
+        }) };
+}
+export const claudeHarness = {
+    id: "claude",
+    binary: profile.binary,
+    async models(executable, cwd) {
+        await streamJsonHelp(profile, executable, cwd);
+        // Aliases follow the signed-in account; Haiku takes no effort level.
+        return [
+            streamJsonModel(profile, DEFAULT_MODEL, "Default", { reasoning: true, isDefault: true }),
+            streamJsonModel(profile, "opus", "Claude Opus", { reasoning: true }),
+            streamJsonModel(profile, "sonnet", "Claude Sonnet", { reasoning: true }),
+            streamJsonModel(profile, "haiku", "Claude Haiku", { reasoning: false }),
+        ];
+    },
+    run: (executor, turn) => runStreamJson(profile, executor, turn),
+    session: {
+        path: (nativeSessionId, cwd) => join(claudeProjectDirectory(cwd), `${nativeSessionId}.jsonl`),
+        startsWithoutFile: true,
+        project: (input) => withAssistantIds(projectChainedSession(input, "claude", { id: "uuid", parent: "parentUuid" }, (segment) => {
+            const content = segment.blocks.map(anthropicBlock).filter((block) => block !== null);
+            return [{
+                    isSidechain: false, userType: "external", cwd: input.cwd, sessionId: input.nativeSessionId, version: "cohub",
+                    type: segment.role, timestamp: segment.message.createdAt || input.timestamp || new Date(0).toISOString(),
+                    ...(segment.compactSummary ? { isCompactSummary: true } : {}),
+                    message: segment.role === "user"
+                        ? { role: "user", content }
+                        : {
+                            type: "message", role: "assistant", model: segment.message.model || "cohub", content,
+                            stop_reason: segment.blocks.some((block) => block.type === "tool_use") ? "tool_use" : "end_turn", stop_sequence: null,
+                            usage: { input_tokens: 0, output_tokens: 0 },
+                        },
+                    cohub: projectionMeta(input, segment.message),
+                }];
+        })),
+        rebind: rebindSessionId,
+        archive: {
+            // The copy takes a fresh id: the archived one may already exist here, and is never replaced.
+            target: ({ id, cwd }) => join(claudeProjectDirectory(cwd), `${id}.jsonl`),
+            async import(input) {
+                const { checksum } = await copyNativeArchive({ ...input, sessionId: input.id });
+                return { checksum, nativeSessionId: input.id };
+            },
+        },
+    },
+    nativeSync: false,
+};

package/dist/runtime/harnesses/codex.d.ts

@@ -0,0 +1,4 @@
+import type { LocalHarnessAdapter, ThreadKind } from "./types.js";
+/** Codex's first line is the only place a thread's purpose is recorded. */
+export declare function codexThreadKind(payload: Record<string, unknown>): ThreadKind;
+export declare const codexHarness: LocalHarnessAdapter;

package/dist/runtime/harnesses/codex.js

@@ -0,0 +1,229 @@
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+import { projectNativeSession } from "@neta-art/cohub";
+import { JsonRpcProcess, record } from "../json-rpc.js";
+import { codexModelCatalog } from "../model-catalog.js";
+import { describeError } from "../../network-error.js";
+import { openPrivateServer } from "../native/codex-link.js";
+import { ArchiveNotRestorableError, copyNativeArchive } from "../native/archive.js";
+import { codexArchivedSessionsDirectory, codexRolloutBytes, codexRolloutIdOf, codexSessionsDirectory, ensurePlainCodexRollout, readFirstRecord, readNativeTranscript, } from "../native/transcript.js";
+import { codexTranslator } from "../native/translate.js";
+import { array, closeHost, harnessCommand, inlineImage, text, turnEnvironment, watchHost } from "./process.js";
+/** A stop request that the harness does not honour within this long ends its private process. */
+const ABORT_ESCALATION_MS = 5_000;
+function codexSessionPath(nativeSessionId) {
+    const home = process.env.CODEX_HOME?.trim() || join(homedir(), ".codex");
+    const day = new Date().toISOString().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`);
+}
+async function initializeCodex(rpc) {
+    await rpc.request("initialize", { clientInfo: { name: "cohub", title: "Cohub", version: "1" }, capabilities: { experimentalApi: true } });
+    rpc.write({ method: "initialized", params: {} });
+}
+/** Codex's first line is the only place a thread's purpose is recorded. */
+export function codexThreadKind(payload) {
+    const source = payload.source;
+    if (source && typeof source === "object")
+        return record(record(source).subagent).thread_spawn ? "spawned" : "internal";
+    return ["subagent", "guardian_review", "memory_consolidation"].includes(text(payload.thread_source)) ? "internal" : "user";
+}
+async function runCodex(executor, turn) {
+    const { input, signal, context } = turn;
+    const shared = await executor.codex.get();
+    const prepared = await executor.sessions.prepare({
+        sessionId: input.sessionId, turnId: input.turnId, harness: "codex", cwd: executor.cwd,
+        provider: input.provider, context: input.context, signal,
+        // Only the shared server coordinates with terminal clients; a private one never opens their files.
+        resumable: (transcript) => transcript.path !== turn.diverged && (transcript.origin === "cohub" || shared !== null),
+    });
+    let session = prepared.session;
+    let host = null;
+    let channel = shared;
+    let message = { ordinal: 0, content: [] };
+    let begun = false;
+    try {
+        if (!channel) {
+            host = new JsonRpcProcess(...harnessCommand(executor.executables.codex || "codex", ["app-server", "--listen", "stdio://"], executor.cwd), executor.cwd, "jsonrpc", turnEnvironment(input));
+            watchHost(host, executor.diagnostics, context);
+            channel = await openPrivateServer(host);
+        }
+        const codex = channel;
+        const threadOptions = {
+            cwd: executor.cwd,
+            ...(input.model ? { model: input.model } : {}),
+            ...(input.provider && input.provider !== "codex" ? { modelProvider: input.provider } : {}),
+            ...(input.accessMode === "read_only" ? { sandbox: "read-only" } : {}),
+            // Tools of a shared server otherwise see the environment of whoever started that server.
+            config: { "shell_environment_policy.set.COHUB_SPACE_ID": input.spaceId, "shell_environment_policy.set.COHUB_SESSION_ID": input.sessionId },
+        };
+        const existing = { ...threadOptions, threadId: session.nativeSessionId, path: session.path, excludeTurns: true };
+        const opened = prepared.resume === "new" ? await codex.request("thread/start", threadOptions)
+            : prepared.resume === "restored" ? await codex.request("thread/fork", existing)
+                : await codex.request("thread/resume", existing);
+        const thread = record(opened.thread);
+        if (typeof thread.id !== "string" || typeof thread.path !== "string")
+            throw new Error("Codex did not provide a durable native thread");
+        const threadId = thread.id;
+        if (thread.path !== session.path || threadId !== session.nativeSessionId) {
+            session = { ...session, nativeSessionId: threadId, path: thread.path };
+            executor.ingest.adopt(session, input.sessionId);
+        }
+        const translator = codexTranslator(turn.emit, { provider: text(opened.modelProvider) || "codex", model: text(opened.model) || input.model || null });
+        const content = await codexPrompt(input);
+        signal.throwIfAborted();
+        await turn.started(session);
+        begun = true;
+        let nativeTurnId = null;
+        executor.codex.driving.add(threadId);
+        await new Promise((resolve, reject) => {
+            let escalation;
+            let done = false;
+            const finish = (error) => {
+                if (done)
+                    return;
+                done = true;
+                off();
+                offClose();
+                signal.removeEventListener("abort", abort);
+                clearTimeout(escalation);
+                if (error)
+                    reject(error);
+                else
+                    resolve();
+            };
+            const interrupt = () => { if (nativeTurnId)
+                void codex.request("turn/interrupt", { threadId, turnId: nativeTurnId }).catch(() => undefined); };
+            const off = codex.onEvent((event) => {
+                const params = event.params;
+                if (event.id != null) {
+                    // An unattended Cohub Turn never grants an escalation.
+                    if (!codex.shared || params.threadId === threadId && (!nativeTurnId || params.turnId === nativeTurnId))
+                        codex.refuse(event.id, "Approval requires an interactive local client");
+                    return;
+                }
+                if (params.threadId !== threadId)
+                    return;
+                // A resumed thread replays its last usage; only this Turn's counts belong to it.
+                if (event.method === "thread/tokenUsage/updated" && params.turnId !== nativeTurnId)
+                    return;
+                if (event.method === "turn/started" && !nativeTurnId) {
+                    nativeTurnId = text(record(params.turn).id) || null;
+                    if (signal.aborted)
+                        interrupt();
+                }
+                if (event.method === "turn/completed" && nativeTurnId && text(record(params.turn).id) !== nativeTurnId)
+                    return;
+                try {
+                    if (translator.push(event))
+                        finish();
+                }
+                catch (error) {
+                    finish(error);
+                }
+            });
+            const offClose = codex.onClose((error) => finish(error));
+            const abort = () => {
+                interrupt();
+                if (host)
+                    escalation = setTimeout(() => void host?.close().catch(() => undefined), ABORT_ESCALATION_MS);
+            };
+            signal.addEventListener("abort", abort, { once: true });
+            codex.request("turn/start", { threadId, clientUserMessageId: input.turnId, input: content, ...(input.thinkingLevel ? { effort: input.thinkingLevel === "off" ? "none" : input.thinkingLevel } : {}) })
+                .then((result) => { nativeTurnId ??= text(record(result.turn).id) || null; if (signal.aborted)
+                interrupt(); })
+                .catch(finish);
+        }).finally(() => executor.codex.driving.delete(threadId));
+        message = translator.last();
+    }
+    catch (error) {
+        if (!begun) {
+            if (host)
+                await closeHost(host, null).catch(() => undefined);
+            throw error;
+        }
+        message = { ...message, stopReason: signal.aborted ? "aborted" : "error", errorMessage: signal.aborted ? null : describeError(error) };
+    }
+    return { session, resume: prepared.resume, message, host };
+}
+async function codexPrompt(input) {
+    return await Promise.all(input.messages.flatMap((message) => message.content).map(async (block) => {
+        if (block.type === "image") {
+            const image = await inlineImage(block);
+            return { type: "image", url: `data:${image.mimeType};base64,${image.data}` };
+        }
+        return { type: "text", text: block.type === "text" ? block.text : JSON.stringify(block), text_elements: [] };
+    }));
+}
+export const codexHarness = {
+    id: "codex",
+    binary: "codex",
+    async models(executable, cwd) {
+        const rpc = new JsonRpcProcess(...harnessCommand(executable, ["app-server", "--listen", "stdio://"], cwd), cwd, "jsonrpc");
+        try {
+            await initializeCodex(rpc);
+            const config = await rpc.request("config/read", { includeLayers: false, cwd });
+            const entries = [];
+            const cursors = new Set();
+            let cursor = null;
+            do {
+                const result = await rpc.request("model/list", { cursor, limit: 100 });
+                entries.push(...array(result.data));
+                cursor = typeof result.nextCursor === "string" ? result.nextCursor : null;
+                if (entries.length > 2000 || cursor && cursors.has(cursor))
+                    throw new Error("Invalid model catalog pagination");
+                if (cursor)
+                    cursors.add(cursor);
+            } while (cursor);
+            return codexModelCatalog(config, entries);
+        }
+        finally {
+            await rpc.close();
+        }
+    },
+    run: runCodex,
+    session: {
+        path: (nativeSessionId) => codexSessionPath(nativeSessionId),
+        startsWithoutFile: true,
+        project: (input) => projectNativeSession(input, "codex"),
+        rebind: (records, nativeSessionId) => records.map((entry) => entry.sourceTurnId === null && entry.record.type === "session_meta"
+            ? { ...entry, record: { ...entry.record, payload: { ...record(entry.record.payload), id: nativeSessionId, session_id: nativeSessionId } } }
+            : entry),
+        archive: {
+            target: ({ id }) => codexSessionPath(id),
+            async import(input) {
+                const { checksum } = await copyNativeArchive({
+                    ...input,
+                    header: (header) => {
+                        const payload = record(header.payload);
+                        if (header.type !== "session_meta" || payload.id !== input.nativeSessionId)
+                            throw new Error("Codex archive identity mismatch");
+                        // A leaf archive does not carry its ancestor rollout.
+                        if (payload.history_base != null)
+                            throw new ArchiveNotRestorableError("Codex archive references history it does not carry; rebuild from the Session instead");
+                        return { ...header, payload: { ...payload, id: input.id, ...(payload.session_id != null ? { session_id: input.id } : {}), history_mode: "legacy", cwd: input.cwd } };
+                    },
+                });
+                return { checksum, nativeSessionId: input.id };
+            },
+        },
+    },
+    transcript: {
+        roots: () => [codexSessionsDirectory(), codexArchivedSessionsDirectory()],
+        acceptsDirectory: () => true,
+        acceptsTranscript: (path) => codexRolloutIdOf(basename(path)) !== null,
+        async header(path, signal) {
+            const header = await readFirstRecord(codexRolloutBytes(path, null, signal));
+            const payload = record(header.payload);
+            if (header.type !== "session_meta" || !text(payload.id) || !text(payload.cwd))
+                return null;
+            return { harness: "codex", nativeSessionId: text(payload.id), cwd: text(payload.cwd), thread: codexThreadKind(payload) };
+        },
+        read: (path, signal) => readNativeTranscript(path, "codex", { signal }),
+        boundaries: ['"UserMessage"', '"user_message"', '"turn_complete"', '"task_complete"', '"turn_aborted"'],
+        turnEndRecorded: true,
+        userFinalMarked: true,
+        globalTurnKeys: true,
+        archiveSource: (path, cacheDirectory) => ensurePlainCodexRollout(path, cacheDirectory),
+    },
+    nativeSync: true,
+};

package/dist/runtime/harnesses/index.d.ts

@@ -0,0 +1,16 @@
+import { type LocalHarness, type RuntimeCapabilities } from "@neta-art/cohub";
+import type { HarnessExecutables, LocalHarnessAdapter, NativeTranscriptFormat } from "./types.js";
+export type { HarnessExecutables, HarnessModel, HarnessResult, LocalHarnessAdapter } from "./types.js";
+export { harnessCommand, harnessExecutableCandidates } from "./process.js";
+export declare const harnessAdapter: (harness: LocalHarness) => LocalHarnessAdapter;
+export declare const harnessExecutable: (harness: LocalHarness, executables: HarnessExecutables) => string;
+/** Harnesses whose terminal conversations can sync to the Space. */
+export declare const nativeSyncHarnesses: (harnesses: readonly LocalHarness[]) => ("claude" | "codex" | "pi" | "workbuddy")[];
+export declare function transcriptFormat(harness: LocalHarness): NativeTranscriptFormat;
+/** Discover installed executables only; authentication/capability errors stay explicit. */
+export declare function installedHarnesses(cwd: string, executables: HarnessExecutables, path?: string): Promise<LocalHarness[]>;
+/**
+ * Explicitly requested harnesses must all work. With `onUnavailable`, a failing harness is reported
+ * and left out instead, so auto-discovery still starts with the ones that work.
+ */
+export declare function discoverHarnesses(harnesses: LocalHarness[], executables: HarnessExecutables, cwd: string, onUnavailable?: (harness: LocalHarness, error: unknown) => void): Promise<RuntimeCapabilities>;

package/dist/runtime/harnesses/index.js

@@ -0,0 +1,57 @@
+import { access, stat } from "node:fs/promises";
+import { constants } from "node:fs";
+import { LOCAL_HARNESS_SPECS, LOCAL_HARNESSES } from "@neta-art/cohub";
+import { harnessExecutableCandidates } from "./process.js";
+import { piHarness } from "./pi.js";
+import { codexHarness } from "./codex.js";
+import { claudeHarness } from "./claude.js";
+import { workbuddyHarness } from "./workbuddy.js";
+export { harnessCommand, harnessExecutableCandidates } from "./process.js";
+/** Every local harness is one adapter; the protocol registry lists their identities. Built lazily to tolerate import cycles. */
+let registry = null;
+const adapters = () => registry ??= { pi: piHarness, codex: codexHarness, claude: claudeHarness, workbuddy: workbuddyHarness };
+export const harnessAdapter = (harness) => adapters()[harness];
+export const harnessExecutable = (harness, executables) => executables[harness] || adapters()[harness].binary;
+/** Harnesses whose terminal conversations can sync to the Space. */
+export const nativeSyncHarnesses = (harnesses) => harnesses.filter((harness) => adapters()[harness].nativeSync);
+export function transcriptFormat(harness) {
+    const format = adapters()[harness].transcript;
+    if (!format)
+        throw new Error(`${LOCAL_HARNESS_SPECS[harness].label} transcripts cannot be read`);
+    return format;
+}
+/** Discover installed executables only; authentication/capability errors stay explicit. */
+export async function installedHarnesses(cwd, executables, path = process.env.PATH ?? "") {
+    const explicit = LOCAL_HARNESSES.filter((harness) => executables[harness]);
+    const found = await Promise.all((explicit.length ? explicit : LOCAL_HARNESSES).map(async (harness) => {
+        for (const candidate of harnessExecutableCandidates(harnessExecutable(harness, executables), cwd, path)) {
+            try {
+                await access(candidate, process.platform === "win32" ? constants.F_OK : constants.X_OK);
+                if ((await stat(candidate)).isFile())
+                    return harness;
+            }
+            catch { /* Try the next PATH entry. */ }
+        }
+        return null;
+    }));
+    return found.filter((harness) => harness !== null);
+}
+/**
+ * Explicitly requested harnesses must all work. With `onUnavailable`, a failing harness is reported
+ * and left out instead, so auto-discovery still starts with the ones that work.
+ */
+export async function discoverHarnesses(harnesses, executables, cwd, onUnavailable) {
+    const catalogs = await Promise.all(harnesses.map(async (harness) => {
+        try {
+            return { harness, models: await adapters()[harness].models(harnessExecutable(harness, executables), cwd) };
+        }
+        catch (error) {
+            if (!onUnavailable)
+                throw error;
+            onUnavailable(harness, error);
+            return null;
+        }
+    }));
+    const available = catalogs.filter((catalog) => catalog !== null);
+    return { harnesses: available.map((catalog) => catalog.harness), models: available.flatMap((catalog) => catalog.models) };
+}

package/dist/runtime/harnesses/pi.d.ts

@@ -0,0 +1,4 @@
+import type { LocalHarnessAdapter } from "./types.js";
+/** Pi's encoding of a project directory into its session folder name. */
+export declare const piSessionDirectoryName: (cwd: string) => string;
+export declare const piHarness: LocalHarnessAdapter;

package/dist/runtime/harnesses/pi.js

@@ -0,0 +1,247 @@
+import { createReadStream } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { projectNativeSession } from "@neta-art/cohub";
+import { JsonRpcProcess, record } from "../json-rpc.js";
+import { piModelCatalog } from "../model-catalog.js";
+import { describeError } from "../../network-error.js";
+import { PI_DISCONNECTED } from "../native/pi-link.js";
+import { copyNativeArchive } from "../native/archive.js";
+import { readFirstRecord, readNativeTranscript } from "../native/transcript.js";
+import { piTranslator } from "../native/translate.js";
+import { array, closeHost, harnessCommand, inlineImage, text, turnEnvironment, watchHost } from "./process.js";
+/** A stop request that the harness does not honour within this long ends its private process. */
+const ABORT_ESCALATION_MS = 5_000;
+/** Pause before asking a busy Pi again, so a Turn that is starting has reported itself. */
+const PI_BUSY_RETRY_MS = 100;
+/** Pi stop reasons that end a reply; anything else (a tool call) means more is coming. */
+const PI_ENDED = ["stop", "length", "error", "aborted"];
+const agentDirectory = () => process.env.PI_CODING_AGENT_DIR?.trim() || join(homedir(), ".pi", "agent");
+const sessionRoot = () => process.env.PI_CODING_AGENT_SESSION_DIR?.trim() || join(agentDirectory(), "sessions");
+/** Pi's encoding of a project directory into its session folder name. */
+export const piSessionDirectoryName = (cwd) => `--${cwd.replace(/^[/\\]/, "").replace(/[/\\:]/g, "-")}--`;
+/** Whether a Pi project folder may hold sessions of `cwd` or a subdirectory of it. */
+function piProjectFolderMatches(folder, cwd) {
+    const project = piSessionDirectoryName(cwd).slice(0, -2);
+    const name = basename(folder);
+    return name === `${project}--` || name.startsWith(`${project}-`);
+}
+function piSessionPath(nativeSessionId, cwd) {
+    const directory = process.env.PI_CODING_AGENT_SESSION_DIR?.trim() || join(agentDirectory(), "sessions", piSessionDirectoryName(cwd));
+    return join(directory, `${new Date().toISOString().replace(/[:.]/g, "-")}_${nativeSessionId}.jsonl`);
+}
+async function runPi(executor, turn) {
+    const { input, signal, context } = turn;
+    // Cohub drives every Pi through its extension, which needs the control socket and a recent Pi.
+    if (executor.pi.unavailable)
+        throw new Error(executor.pi.unavailable);
+    const prepared = await executor.sessions.prepare({
+        sessionId: input.sessionId, turnId: input.turnId, harness: "pi", cwd: executor.cwd,
+        provider: input.provider, context: input.context, signal,
+        // A terminal Pi is continued only through its extension; without one it is read-only.
+        resumable: (transcript) => transcript.path !== turn.diverged && (transcript.origin === "cohub" || executor.pi.find(transcript.nativeSessionId) !== null),
+    });
+    let session = prepared.session;
+    let link = executor.pi.find(session.nativeSessionId);
+    let host = null;
+    let message = { ordinal: 0, content: [] };
+    let begun = false;
+    try {
+        if (!link) {
+            host = new JsonRpcProcess(...harnessCommand(executor.executables.pi || "pi", ["--mode", "rpc", "--session", session.path, "-e", executor.piExtension], executor.cwd), executor.cwd, "pi", turnEnvironment(input));
+            watchHost(host, executor.diagnostics, context);
+            const rpc = host;
+            // Nobody is at this Pi's terminal to answer an extension's question.
+            rpc.onEvent((event) => {
+                if (event.type === "extension_ui_request" && ["confirm", "select", "input", "editor"].includes(text(event.method)))
+                    rpc.write({ type: "extension_ui_response", id: event.id, cancelled: true });
+            });
+            await configurePiHost(host, input);
+            link = await Promise.race([
+                executor.pi.waitFor({ sessionId: session.nativeSessionId, sessionFile: session.path }, signal),
+                new Promise((_, reject) => host?.onFailure(reject)),
+            ]);
+        }
+        const piSession = link;
+        session = { ...session, nativeSessionId: piSession.sessionId };
+        // Never interleave with a Turn a terminal user is running; follow it instead.
+        await executor.pi.idle(piSession.sessionId, signal);
+        const content = await piPrompt(input);
+        signal.throwIfAborted();
+        await turn.started(session);
+        begun = true;
+        const translator = piTranslator(turn.emit);
+        const model = !host && input.model && input.provider ? { provider: input.provider, id: input.model } : null;
+        await new Promise((resolve, reject) => {
+            let escalation;
+            /** Events held until Pi takes the prompt; until then they belong to a terminal Turn. */
+            let held = [];
+            let done = false;
+            const finish = (error) => {
+                if (done)
+                    return;
+                done = true;
+                off();
+                signal.removeEventListener("abort", abort);
+                clearTimeout(escalation);
+                if (error)
+                    reject(error);
+                else
+                    resolve();
+            };
+            const feed = (event) => {
+                try {
+                    if (translator.push(event))
+                        finish();
+                }
+                catch (error) {
+                    finish(error);
+                }
+            };
+            const off = executor.pi.subscribe(piSession.sessionId, (event) => {
+                if (event.type === PI_DISCONNECTED) {
+                    finish(new Error("Pi exited during the Turn"));
+                    return;
+                }
+                if (held)
+                    held.push(event);
+                else
+                    feed(event);
+            });
+            const abort = () => {
+                // Not taken yet: the Pi is running someone else's Turn, which is not Cohub's to stop.
+                if (held) {
+                    finish(signal.reason ?? new Error("Aborted"));
+                    return;
+                }
+                void executor.pi.abort(piSession.sessionId).catch(() => undefined);
+                if (host)
+                    escalation = setTimeout(() => void host?.close().catch(() => undefined), ABORT_ESCALATION_MS);
+            };
+            signal.addEventListener("abort", abort, { once: true });
+            void (async () => {
+                for (;;) {
+                    // Only what follows this request can be this Turn's.
+                    held = [];
+                    const { accepted } = await executor.pi.prompt(piSession.sessionId, { turnId: input.turnId, content, model, thinkingLevel: host ? null : input.thinkingLevel ?? null, env: turnEnvironment(input) });
+                    if (accepted)
+                        break;
+                    // The terminal started a Turn first: wait for it to settle, then ask again.
+                    await new Promise((resolve) => setTimeout(resolve, PI_BUSY_RETRY_MS));
+                    await executor.pi.idle(piSession.sessionId, signal);
+                    if (done)
+                        return;
+                }
+                const events = held ?? [];
+                held = null;
+                if (done) {
+                    void executor.pi.abort(piSession.sessionId).catch(() => undefined);
+                    return;
+                }
+                for (const event of events)
+                    feed(event);
+                if (signal.aborted)
+                    abort();
+            })().catch(finish);
+            if (signal.aborted)
+                abort();
+        });
+        message = translator.last();
+        // The Pi keeps running for its terminal user; its tools no longer work for this Turn.
+        if (!host)
+            void executor.pi.context(piSession.sessionId, { COHUB_TURN_ID: null }).catch(() => undefined);
+    }
+    catch (error) {
+        // Before the prompt, nothing ran and the error is the outcome.
+        if (!begun) {
+            if (host)
+                await closeHost(host, null).catch(() => undefined);
+            throw error;
+        }
+        message = { ...message, stopReason: signal.aborted ? "aborted" : "error", errorMessage: signal.aborted ? null : describeError(error) };
+    }
+    return { session, resume: prepared.resume, message, host };
+}
+/** A Pi that Cohub starts is configured through its RPC before the extension takes the prompt. */
+async function configurePiHost(host, input) {
+    if (input.model) {
+        let provider = input.provider;
+        if (!provider) {
+            const catalog = await host.request("get_available_models");
+            const matches = (Array.isArray(catalog.models) ? catalog.models : []).map(record).filter((model) => model.id === input.model);
+            if (matches.length !== 1)
+                throw new Error("Select a provider for this local model");
+            provider = text(matches[0]?.provider);
+        }
+        await host.request("set_model", { provider, modelId: input.model });
+    }
+    if (input.thinkingLevel)
+        await host.request("set_thinking_level", { level: input.thinkingLevel });
+}
+async function piPrompt(input) {
+    const blocks = input.messages.flatMap((message) => message.content);
+    return await Promise.all(blocks.map(async (block) => {
+        if (block.type === "image")
+            return await inlineImage(block);
+        return { type: "text", text: block.type === "text" ? block.text : JSON.stringify(block) };
+    }));
+}
+export const piHarness = {
+    id: "pi",
+    binary: "pi",
+    async models(executable, cwd) {
+        const rpc = new JsonRpcProcess(...harnessCommand(executable, ["--mode", "rpc", "--no-session"], cwd), cwd, "pi");
+        try {
+            const result = await rpc.request("get_available_models");
+            const state = await rpc.request("get_state");
+            return piModelCatalog(array(result.models), state);
+        }
+        finally {
+            await rpc.close();
+        }
+    },
+    run: runPi,
+    session: {
+        path: piSessionPath,
+        startsWithoutFile: false,
+        project: (input) => projectNativeSession(input, "pi"),
+        rebind: (records, nativeSessionId) => records.map((entry) => entry.sourceTurnId === null && entry.record.type === "session"
+            ? { ...entry, record: { ...entry.record, id: nativeSessionId, affinity: { ...record(entry.record.affinity), threadId: nativeSessionId } } }
+            : entry),
+        archive: {
+            target: ({ id, cwd }) => piSessionPath(id, cwd),
+            async import(input) {
+                const { checksum } = await copyNativeArchive({
+                    ...input,
+                    header: (header) => {
+                        if (header.type !== "session" || header.id !== input.nativeSessionId)
+                            throw new Error("Pi archive identity mismatch");
+                        const next = { ...header, cwd: input.cwd };
+                        delete next.parentSession;
+                        return next;
+                    },
+                });
+                return { checksum, nativeSessionId: input.nativeSessionId };
+            },
+        },
+    },
+    transcript: {
+        roots: () => [sessionRoot()],
+        acceptsDirectory: (path, root, cwd) => Boolean(process.env.PI_CODING_AGENT_SESSION_DIR?.trim()) || dirname(path) !== root || piProjectFolderMatches(path, cwd),
+        acceptsTranscript: (path, cwd) => path.endsWith(".jsonl") && (Boolean(process.env.PI_CODING_AGENT_SESSION_DIR?.trim()) || piProjectFolderMatches(dirname(path), cwd)),
+        async header(path, signal) {
+            const header = await readFirstRecord(createReadStream(path, { signal }));
+            if (header.type !== "session" || !text(header.id) || !text(header.cwd))
+                return null;
+            return { harness: "pi", nativeSessionId: text(header.id), cwd: text(header.cwd), thread: "user" };
+        },
+        // A Pi Turn's end is inferred by the caller, so the tail is parsed as settled here.
+        read: (path, signal) => readNativeTranscript(path, "pi", { settled: true, signal }),
+        boundaries: ['"role":"user"', ...PI_ENDED.map((reason) => `"stopReason":"${reason}"`)],
+        turnEndRecorded: false,
+        replyEnded: (turn) => PI_ENDED.includes(turn.messages.at(-1)?.stopReason ?? ""),
+        userFinalMarked: false,
+        globalTurnKeys: false,
+    },
+    nativeSync: true,
+};