@neta-art/cohub-cli 10.5.0 → 10.6.0

package/dist/runtime/harnesses/process.js

@@ -0,0 +1,75 @@
+import { readFileSync, statSync } from "node:fs";
+import { delimiter, join, resolve, win32 } from "node:path";
+import { RpcProcessClosedError } from "../json-rpc.js";
+import { ProcessCleanupUncertainError } from "../process-group.js";
+import { downloadPublicImage } from "../../safe-remote-image.js";
+import { serializeDiagnosticError } from "../diagnostics.js";
+export const text = (value) => typeof value === "string" ? value : "";
+export const array = (value) => Array.isArray(value) ? value : [];
+export const missing = (error) => error?.code === "ENOENT";
+/** Aborted streams leave tool calls with an empty id or name. */
+export const identifiable = (value) => typeof value === "string" && value.length > 0;
+export function harnessExecutableCandidates(binary, cwd, path, platform = process.platform, pathExt = process.env.PATHEXT) {
+    const windows = platform === "win32";
+    const paths = windows ? win32 : { delimiter, join, resolve };
+    // Windows runs only PATHEXT names; npm/pnpm also write an extensionless sh script beside the .cmd shim.
+    const extensions = windows && !win32.extname(binary)
+        ? (pathExt || ".COM;.EXE;.BAT;.CMD").split(";").filter((ext) => /^\.[a-z0-9]+$/i.test(ext))
+        : [""];
+    const roots = binary.includes("/") || binary.includes("\\")
+        ? [paths.resolve(cwd, binary)]
+        : path.split(paths.delimiter).map((directory) => directory.replace(/^"(.*)"$/, "$1")).filter(Boolean).map((directory) => paths.resolve(cwd, directory, binary));
+    return roots.flatMap((root) => extensions.map((ext) => `${root}${ext}`));
+}
+/**
+ * Windows npm/pnpm installs expose harnesses as .cmd shims, which cannot be spawned
+ * without a shell. Run an .exe directly, or the shim's Node entry with this Node.
+ */
+export function harnessCommand(binary, args, cwd) {
+    if (process.platform !== "win32")
+        return [binary, args];
+    const path = harnessExecutableCandidates(binary, cwd, process.env.PATH ?? "").find((candidate) => statSync(candidate, { throwIfNoEntry: false })?.isFile());
+    if (!path)
+        throw new Error(`${binary} was not found on PATH`);
+    const extension = win32.extname(path).toLowerCase();
+    if (extension === ".exe" || extension === ".com")
+        return [path, args];
+    if ([".js", ".mjs", ".cjs"].includes(extension))
+        return [process.execPath, [path, ...args]];
+    if (extension === ".cmd") {
+        // npm (cmd-shim): SET "_prog=node" … "%dp0%\entry" %*; pnpm (@zkochan/cmd-shim): node  "%~dp0\entry" %*
+        const shim = readFileSync(path, "utf8");
+        const runsNode = /SET "_prog=node"/i.test(shim) || /^\s*node\s+"%~dp0\\/im.test(shim);
+        const entry = runsNode ? /"%~?dp0%?\\([^"]+)"\s+%\*/i.exec(shim)?.[1] : undefined;
+        if (entry)
+            return [process.execPath, [win32.join(win32.dirname(path), entry), ...args]];
+    }
+    throw new Error(`Cannot run ${path} without a shell; pass its executable option with an .exe or Node script`);
+}
+/** Variables a Turn's tools see, so a `cohub` call inside a tool knows where it runs. */
+export const turnEnvironment = (input) => ({ COHUB_SPACE_ID: input.spaceId, COHUB_SESSION_ID: input.sessionId, COHUB_TURN_ID: input.turnId });
+export async function inlineImage(block) {
+    if (block.source.type === "base64")
+        return { type: "image", data: block.source.data, mimeType: block.source.media_type };
+    const image = await downloadPublicImage(block.source.url);
+    return { type: "image", data: Buffer.from(image.bytes).toString("base64"), mimeType: image.mimeType };
+}
+export function watchHost(host, diagnostics, context) {
+    if (!diagnostics)
+        return;
+    host.onFailure((error) => {
+        if (!(error instanceof RpcProcessClosedError))
+            diagnostics.log("error", "harness.rpc_process_failed", { error: serializeDiagnosticError(error) }, { ...context, component: "harness" });
+    });
+    host.onTimeout((method, timeoutMs) => diagnostics.log("error", "harness.rpc_timeout", { method, timeoutMs }, { ...context, component: "harness" }));
+}
+/** Close a harness process Cohub started. An unconfirmable cleanup marks the result uncertain; it never masks it. */
+export async function closeHost(host, executionError) {
+    return await host.close().then(() => undefined, (cleanupError) => {
+        const processGroupId = host.processGroupId;
+        if (!(cleanupError instanceof ProcessCleanupUncertainError) || processGroupId == null)
+            throw cleanupError;
+        const detail = executionError ? `; execution error: ${executionError}` : "";
+        return { processGroupId, error: `${cleanupError.message}${detail}` };
+    });
+}

package/dist/runtime/harnesses/stream-json.d.ts

@@ -0,0 +1,28 @@
+import type { RuntimeTurnInput } from "@neta-art/cohub";
+import type { Executor } from "../native/execution.js";
+import type { HarnessModel, HarnessRun, HarnessTurn } from "./types.js";
+/** Runs without `--model`, so the CLI's own configuration and account default apply. */
+export declare const DEFAULT_MODEL = "default";
+/** A Claude Code–compatible CLI (`-p --input-format stream-json --output-format stream-json`). */
+export type StreamJsonProfile = {
+    harness: RuntimeTurnInput["harness"];
+    label: string;
+    binary: string;
+    provider: string;
+    /** Root holding `projects/<project>/<session>.jsonl`. */
+    dataRoot(): string;
+    projectDirectory(cwd: string): string;
+    /** Thinking levels accepted by `--effort`. */
+    effortLevels: readonly string[];
+};
+/** The CLI's help, after checking it offers every flag a Turn uses. */
+export declare function streamJsonHelp(profile: StreamJsonProfile, executable: string, cwd: string): Promise<string>;
+export declare function streamJsonModel(profile: StreamJsonProfile, id: string, name: string, options: {
+    reasoning: boolean;
+    isDefault?: boolean;
+}): HarnessModel;
+/**
+ * One Turn per process. Unattended execution never grants an approval: workspace edits follow
+ * `acceptEdits` and every other tool follows the user's own permission rules.
+ */
+export declare function runStreamJson(profile: StreamJsonProfile, executor: Executor, turn: HarnessTurn): Promise<HarnessRun>;

package/dist/runtime/harnesses/stream-json.js

@@ -0,0 +1,291 @@
+import { execFile } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { access, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { JsonRpcProcess, record } from "../json-rpc.js";
+import { describeError } from "../../network-error.js";
+import { array, closeHost, harnessCommand, identifiable, inlineImage, missing, text, turnEnvironment, watchHost } from "./process.js";
+/** A stop request that the harness does not honour within this long ends its process. */
+const ABORT_ESCALATION_MS = 5_000;
+/** After input closes, the CLI flushes its transcript; it is reaped when it does not exit by then. */
+const FLUSH_TIMEOUT_MS = 10_000;
+/**
+ * Plan mode still honours the user's allow rules, so a read-only Turn also gets only these
+ * built-in tools and no configured MCP servers.
+ */
+const READ_ONLY_TOOLS = "Read,Glob,Grep";
+/** Flags every Turn relies on; an executable whose help lacks one is an older or unrelated CLI. */
+const REQUIRED_FLAGS = ["--input-format", "--output-format", "--include-partial-messages", "--session-id", "--resume", "--permission-mode", "--tools", "--strict-mcp-config", "--model", "--effort"];
+const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+/** Runs without `--model`, so the CLI's own configuration and account default apply. */
+export const DEFAULT_MODEL = "default";
+/** The CLI's help, after checking it offers every flag a Turn uses. */
+export async function streamJsonHelp(profile, executable, cwd) {
+    const { stdout } = await promisify(execFile)(...harnessCommand(executable, ["--help"], cwd), { cwd, encoding: "utf8", timeout: 30_000, maxBuffer: 4 * 1024 * 1024, windowsHide: true });
+    const missingFlags = REQUIRED_FLAGS.filter((flag) => !new RegExp(`(^|[\\s,])${flag}(?=[\\s,=<]|$)`, "m").test(stdout));
+    if (missingFlags.length)
+        throw new Error(`${executable} is not a supported ${profile.label} CLI (missing ${missingFlags.join(", ")}); update ${profile.label}`);
+    return stdout;
+}
+export function streamJsonModel(profile, id, name, options) {
+    return {
+        harness: profile.harness, provider: profile.provider, id, name,
+        ...(options.isDefault ? { isDefault: true } : {}),
+        ...(options.reasoning ? { reasoning: true, thinkingLevelMap: Object.fromEntries(THINKING_LEVELS.map((level) => [level, profile.effortLevels.includes(level) ? level : null])) } : {}),
+    };
+}
+/** A session's file is found by id; the project directory naming is only the fast path. */
+async function findSession(profile, nativeSessionId, cwd) {
+    const name = `${nativeSessionId}.jsonl`;
+    const exists = (path) => access(path).then(() => true, () => false);
+    const preferred = (() => { try {
+        return join(profile.projectDirectory(cwd), name);
+    }
+    catch {
+        return null;
+    } })();
+    if (preferred && await exists(preferred))
+        return preferred;
+    const projects = join(profile.dataRoot(), "projects");
+    const entries = await readdir(projects, { withFileTypes: true }).catch((error) => { if (missing(error))
+        return []; throw error; });
+    for (const entry of entries) {
+        const candidate = join(projects, entry.name, name);
+        if (entry.isDirectory() && await exists(candidate))
+            return candidate;
+    }
+    return null;
+}
+function streamContent(value) {
+    return array(value).flatMap((entry) => {
+        const block = record(entry);
+        if (block.type === "text")
+            return [{ type: "text", text: text(block.text) }];
+        if (block.type === "thinking")
+            return [{ type: "thinking", thinking: text(block.thinking), ...(text(block.signature) ? { signature: text(block.signature) } : {}) }];
+        if (block.type === "tool_use")
+            return identifiable(block.id) && identifiable(block.name) ? [{ type: "tool_use", id: block.id, name: block.name, input: record(block.input) }] : [];
+        const source = record(block.source);
+        if (block.type === "image" && source.type === "base64")
+            return [{ type: "image", source: { type: "base64", data: text(source.data), media_type: text(source.media_type) } }];
+        return [];
+    });
+}
+function streamUsage(value, cost) {
+    const usage = record(value);
+    const count = (key) => typeof usage[key] === "number" ? usage[key] : 0;
+    const input = count("input_tokens"), output = count("output_tokens"), cacheRead = count("cache_read_input_tokens"), cacheWrite = count("cache_creation_input_tokens");
+    if (!input && !output && !cacheRead && !cacheWrite)
+        return undefined;
+    return { input, output, cacheRead, cacheWrite, totalTokens: input + output + cacheRead + cacheWrite, ...(typeof cost === "number" && cost > 0 ? { cost: { total: cost } } : {}) };
+}
+async function prompt(input) {
+    const content = await Promise.all(input.messages.flatMap((message) => message.content).map(async (block) => {
+        if (block.type !== "image")
+            return { type: "text", text: block.type === "text" ? block.text : JSON.stringify(block) };
+        const image = await inlineImage(block);
+        return { type: "image", source: { type: "base64", media_type: image.mimeType, data: image.data } };
+    }));
+    return { type: "user", message: { role: "user", content } };
+}
+/** Maps stream-json output onto Cohub's streaming protocol; sub-agent traffic stays in the native transcript. */
+function streamJsonTranslator(emit, identity) {
+    const messages = new Map();
+    const owners = new Map();
+    let current = null;
+    let streaming = null;
+    let model = identity.model;
+    let final = null;
+    const snapshot = (message) => ({
+        ordinal: message.ordinal, content: [...message.content, ...message.partial.values()], provider: identity.provider, model: message.model ?? model,
+        stopReason: message.content.some((block) => block.type === "tool_use") ? "tool_use" : "stop",
+    });
+    const begin = (id, messageModel) => {
+        const existing = messages.get(id);
+        if (existing)
+            return existing;
+        if (current)
+            emit({ type: "message.commit", message: snapshot(current) });
+        const message = { ordinal: messages.size, content: [], partial: new Map(), model: messageModel };
+        messages.set(id, message);
+        current = message;
+        emit({ type: "message.start", ordinal: message.ordinal });
+        return message;
+    };
+    const last = () => current ? snapshot(current) : { ordinal: 0, content: [], provider: identity.provider, model };
+    return {
+        /** The final `result`, or `null` while the Turn runs. */
+        result: () => final,
+        last,
+        push(event) {
+            if (event.parent_tool_use_id)
+                return false;
+            if (event.type === "system" && event.subtype === "init") {
+                model = text(event.model) || model;
+                return false;
+            }
+            if (event.type === "stream_event") {
+                const stream = record(event.event);
+                if (stream.type === "message_start")
+                    streaming = begin(text(record(stream.message).id) || randomUUID(), text(record(stream.message).model) || null);
+                const delta = record(stream.delta);
+                if (streaming && stream.type === "content_block_delta" && (delta.type === "text_delta" || delta.type === "thinking_delta")) {
+                    const index = Number(stream.index ?? 0), chunk = text(delta.text ?? delta.thinking);
+                    const previous = streaming.partial.get(index);
+                    streaming.partial.set(index, delta.type === "text_delta"
+                        ? { type: "text", text: (previous?.type === "text" ? previous.text : "") + chunk }
+                        : { type: "thinking", thinking: (previous?.type === "thinking" ? previous.thinking : "") + chunk });
+                    emit({ type: "text.delta", ordinal: streaming.ordinal, index, kind: delta.type === "text_delta" ? "text" : "thinking", delta: chunk });
+                }
+                return false;
+            }
+            if (event.type === "assistant") {
+                const native = record(event.message);
+                const message = begin(text(native.id) || randomUUID(), text(native.model) || null);
+                // Complete blocks supersede what streamed so far.
+                message.partial.clear();
+                for (const block of streamContent(native.content)) {
+                    const index = block.type === "tool_use" ? message.content.findIndex((existing) => existing.type === "tool_use" && existing.id === block.id) : -1;
+                    if (index >= 0)
+                        message.content[index] = block;
+                    else
+                        message.content.push(block);
+                    if (block.type === "tool_use")
+                        owners.set(block.id, message);
+                }
+                emit({ type: "content.replace", ordinal: message.ordinal, content: [...message.content] });
+                return false;
+            }
+            if (event.type === "user") {
+                for (const entry of array(record(event.message).content)) {
+                    const block = record(entry);
+                    const id = text(block.tool_use_id);
+                    const owner = block.type === "tool_result" ? owners.get(id) : undefined;
+                    if (!owner)
+                        continue;
+                    owner.content = owner.content.filter((existing) => existing.type !== "tool_result" || existing.tool_use_id !== id);
+                    owner.content.push({ type: "tool_result", tool_use_id: id, content: typeof block.content === "string" ? block.content : streamContent(block.content), is_error: Boolean(block.is_error) });
+                    emit({ type: "content.replace", ordinal: owner.ordinal, content: [...owner.content] });
+                }
+                return false;
+            }
+            if (event.type !== "result")
+                return false;
+            const failed = event.is_error === true || event.subtype !== "success";
+            final = {
+                ...last(),
+                stopReason: failed ? "error" : "stop",
+                errorMessage: failed ? text(event.result) || array(event.errors).map(text).join("\n") || text(event.subtype) || "Turn failed" : null,
+                usage: streamUsage(event.usage, event.total_cost_usd),
+            };
+            return true;
+        },
+    };
+}
+/**
+ * One Turn per process. Unattended execution never grants an approval: workspace edits follow
+ * `acceptEdits` and every other tool follows the user's own permission rules.
+ */
+export async function runStreamJson(profile, executor, turn) {
+    const { input, signal, context } = turn;
+    const prepared = await executor.sessions.prepare({
+        sessionId: input.sessionId, turnId: input.turnId, harness: profile.harness, cwd: executor.cwd,
+        provider: input.provider, context: input.context, signal,
+        // Only a file Cohub wrote and advanced is continued; nothing else writes to it.
+        resumable: (transcript) => transcript.path !== turn.diverged && transcript.origin === "cohub",
+    });
+    let session = prepared.session;
+    const effort = input.thinkingLevel && profile.effortLevels.includes(input.thinkingLevel) ? input.thinkingLevel : null;
+    const args = [
+        "-p", "--input-format", "stream-json", "--output-format", "stream-json", "--verbose", "--include-partial-messages",
+        ...(prepared.resume === "new" ? ["--session-id", session.nativeSessionId] : ["--resume", session.nativeSessionId]),
+        ...(input.accessMode === "read_only" ? ["--permission-mode", "plan", "--tools", READ_ONLY_TOOLS, "--strict-mcp-config"] : ["--permission-mode", "acceptEdits"]),
+        ...(input.model && input.model !== DEFAULT_MODEL ? ["--model", input.model] : []),
+        ...(effort ? ["--effort", effort] : []),
+    ];
+    const content = await prompt(input);
+    signal.throwIfAborted();
+    const host = new JsonRpcProcess(...harnessCommand(executor.executables[profile.harness] || profile.binary, args, executor.cwd), executor.cwd, "stream", turnEnvironment(input));
+    watchHost(host, executor.diagnostics, context);
+    const translator = streamJsonTranslator(turn.emit, { provider: profile.provider, model: input.model && input.model !== DEFAULT_MODEL ? input.model : null });
+    let message = { ordinal: 0, content: [] };
+    let begun = false;
+    try {
+        await turn.started(session);
+        begun = true;
+        await new Promise((resolve, reject) => {
+            let escalation;
+            let done = false;
+            const finish = (error) => {
+                if (done)
+                    return;
+                done = true;
+                off();
+                offFailure();
+                signal.removeEventListener("abort", abort);
+                clearTimeout(escalation);
+                if (error)
+                    reject(error);
+                else
+                    resolve();
+            };
+            const offFailure = host.onFailure((error) => finish(error));
+            const off = host.onEvent((event) => {
+                // An unattended Cohub Turn never grants a permission request.
+                if (event.type === "control_request") {
+                    try {
+                        host.write({ type: "control_response", response: { subtype: "success", request_id: event.request_id, response: { behavior: "deny", message: "Approval requires an interactive local client" } } });
+                    }
+                    catch (error) {
+                        finish(error);
+                    }
+                    return;
+                }
+                try {
+                    if (translator.push(event))
+                        finish();
+                }
+                catch (error) {
+                    finish(error);
+                }
+            });
+            const abort = () => {
+                try {
+                    host.write({ type: "control_request", request_id: randomUUID(), request: { subtype: "interrupt" } });
+                }
+                catch { /* Escalation closes the process. */ }
+                escalation = setTimeout(() => void host.close().catch(() => undefined), ABORT_ESCALATION_MS);
+            };
+            signal.addEventListener("abort", abort, { once: true });
+            try {
+                host.write(content);
+            }
+            catch (error) {
+                finish(error);
+            }
+            if (signal.aborted)
+                abort();
+        });
+        message = translator.result() ?? translator.last();
+        // A stopped Turn ends with an error result; the stop is not a failure to report.
+        if (signal.aborted)
+            message = { ...message, stopReason: "aborted", errorMessage: null };
+    }
+    catch (error) {
+        if (!begun) {
+            await closeHost(host, null).catch(() => undefined);
+            throw error;
+        }
+        message = { ...translator.last(), stopReason: signal.aborted ? "aborted" : "error", errorMessage: signal.aborted ? null : describeError(error) };
+    }
+    // Closing input lets the CLI flush its transcript before the executor reaps the process.
+    host.endInput();
+    await host.exited(FLUSH_TIMEOUT_MS);
+    const path = await findSession(profile, session.nativeSessionId, executor.cwd);
+    if (path && (path !== session.path || prepared.resume === "new")) {
+        session = { ...session, path };
+        executor.ingest.adopt(session, input.sessionId);
+    }
+    return { session, resume: prepared.resume, message, host };
+}

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

@@ -0,0 +1,108 @@
+import type { LocalHarness, NativeProjection, ProjectionInput, ProjectionRecord, RuntimeCapabilities, RuntimeExecutionEvent, RuntimeMessage, RuntimeTurnInput } from "@neta-art/cohub";
+import type { JsonRpcProcess } from "../json-rpc.js";
+import type { RuntimeDiagnosticContext } from "../diagnostics.js";
+import type { Executor } from "../native/execution.js";
+import type { NativeSession, ResumeKind } from "../native/sessions.js";
+import type { NativeTranscript, NativeTranscriptTurn } from "../native/transcript.js";
+export type HarnessExecutables = Partial<Record<LocalHarness, string>>;
+export type HarnessModel = RuntimeCapabilities["models"][number];
+export type HarnessResult = {
+    session: NativeSession;
+    event: Extract<RuntimeExecutionEvent, {
+        type: "turn.end";
+    }>;
+    uncertainCleanup?: {
+        processGroupId: number;
+        error: string;
+    };
+};
+/** One Cohub Turn handed to an adapter. `started` must be awaited right before the prompt is sent. */
+export type HarnessTurn = {
+    input: RuntimeTurnInput;
+    emit: (event: RuntimeExecutionEvent) => void;
+    signal: AbortSignal;
+    /** A native file the server resolved as stopped; it is never continued. */
+    diverged: string | null;
+    started: (session: NativeSession) => Promise<void>;
+    context?: RuntimeDiagnosticContext;
+};
+/** `host` is a process Cohub started for this Turn; the executor closes it. */
+export type HarnessRun = {
+    session: NativeSession;
+    resume: ResumeKind;
+    message: RuntimeMessage;
+    host: JsonRpcProcess | null;
+};
+export type ThreadKind = "user" | "internal" | "spawned";
+export type SessionHeader = {
+    harness: LocalHarness;
+    nativeSessionId: string;
+    cwd: string;
+    thread: ThreadKind;
+};
+/** Native session files: where they live, how Cohub history is written into them, and how archives restore. */
+export type NativeSessionFormat = {
+    /** File for a new native session of `cwd`. */
+    path(nativeSessionId: string, cwd: string): string;
+    /** An empty session is created by the harness itself instead of a projected file. */
+    startsWithoutFile: boolean;
+    project(input: ProjectionInput): NativeProjection;
+    /** Rewrite the session identity of a full projection. */
+    rebind(records: ProjectionRecord[], nativeSessionId: string): ProjectionRecord[];
+    archive: {
+        /** Working-copy path of a restored archive; `id` is fresh, `nativeSessionId` the archived one. */
+        target(input: {
+            id: string;
+            nativeSessionId: string;
+            cwd: string;
+        }): string;
+        /** Copy raw archive bytes to `target`, adjusting only the header; returns the copy's session id. */
+        import(input: NativeArchiveImport): Promise<{
+            checksum: string;
+            nativeSessionId: string;
+        }>;
+    };
+};
+export type NativeArchiveImport = {
+    source: string;
+    target: string;
+    nativeSessionId: string;
+    id: string;
+    cwd: string;
+    signal?: AbortSignal;
+};
+/** Reading a harness's own transcripts. Required for native sync and receipt-less recovery. */
+export type NativeTranscriptFormat = {
+    roots(): string[];
+    /** Whether a directory found under a root can hold transcripts of `cwd`. */
+    acceptsDirectory(path: string, root: string, cwd: string): boolean;
+    /** Name-only check: can this path hold a transcript of `cwd`? */
+    acceptsTranscript(path: string, cwd: string): boolean;
+    header(path: string, signal?: AbortSignal): Promise<SessionHeader | null>;
+    /** Parse into Turns. Without `turnEndRecorded`, the tail is parsed as settled and withdrawn by the caller while in flight. */
+    read(path: string, signal?: AbortSignal): Promise<NativeTranscript>;
+    /** Record substrings that begin or end a Turn; new bytes without one need no parse. */
+    boundaries: string[];
+    /** The file records each Turn's end, so a Turn without a result is still running. */
+    turnEndRecorded: boolean;
+    /** Otherwise: whether the tail's last reply ended (a quiet period then settles it). */
+    replyEnded?(turn: NativeTranscriptTurn): boolean;
+    /** The prompt is recorded in steps and marked final (`userFinal`); a Turn is sent only once it is. */
+    userFinalMarked: boolean;
+    /** Turn keys are unique across sessions (forks share their history's Turns). */
+    globalTurnKeys: boolean;
+    /** Plain JSONL bytes for archival when the file itself is stored differently. */
+    archiveSource?(path: string, cacheDirectory: string): Promise<string>;
+};
+export type LocalHarnessAdapter = {
+    id: LocalHarness;
+    /** Executable looked up on PATH unless overridden. */
+    binary: string;
+    /** Fails when the harness cannot run. */
+    models(executable: string, cwd: string): Promise<HarnessModel[]>;
+    run(executor: Executor, turn: HarnessTurn): Promise<HarnessRun>;
+    session: NativeSessionFormat;
+    transcript?: NativeTranscriptFormat;
+    /** Terminal conversations can be synced to the Space (requires `transcript`). */
+    nativeSync: boolean;
+};

package/dist/runtime/harnesses/types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,15 @@
+import type { LocalHarnessAdapter } from "./types.js";
+/** Mirrors CodeBuddy's project naming, including its truncation hash for long paths. */
+export declare function workbuddyProjectName(cwd: string): string;
+/** The CLI lists selectable models (built-in and `models.json`) in its `--model` help. */
+export declare function workbuddyModels(help: string): {
+    harness: "claude" | "codex" | "pi" | "workbuddy";
+    provider: string;
+    id: string;
+    name: string;
+    isDefault?: boolean | undefined;
+    reasoning?: boolean | undefined;
+    defaultThinkingLevel?: "high" | "low" | "max" | "medium" | "minimal" | "off" | "xhigh" | undefined;
+    thinkingLevelMap?: Partial<Record<"high" | "low" | "max" | "medium" | "minimal" | "off" | "xhigh", string | null>> | undefined;
+}[];
+export declare const workbuddyHarness: LocalHarnessAdapter;

package/dist/runtime/harnesses/workbuddy.js

@@ -0,0 +1,99 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { copyNativeArchive } from "../native/archive.js";
+import { projectChainedSession, projectionMeta, projectionToolId, rebindSessionId, toolResultText } from "./chained-projection.js";
+import { DEFAULT_MODEL, runStreamJson, streamJsonHelp, streamJsonModel } from "./stream-json.js";
+/** WorkBuddy's CLI is CodeBuddy Code; both share its data root. */
+const dataRoot = () => process.env.CODEBUDDY_CONFIG_DIR?.trim() || join(homedir(), ".codebuddy");
+const MAX_NAME_BYTES = 255;
+const TRUNCATED_NAME_BYTES = 180;
+/** Mirrors CodeBuddy's project naming, including its truncation hash for long paths. */
+export function workbuddyProjectName(cwd) {
+    const base = cwd.replace(/[/\\:]/g, "-").replace(/^-+/, "").replace(/-+$/, "").replace(/-+/g, "-");
+    if (Buffer.byteLength(base, "utf8") <= MAX_NAME_BYTES)
+        return base;
+    let prefix = "", bytes = 0;
+    for (const character of base) {
+        const size = Buffer.byteLength(character, "utf8");
+        if (bytes + size > TRUNCATED_NAME_BYTES)
+            break;
+        bytes += size;
+        prefix += character;
+    }
+    let hash = 5381;
+    for (const byte of Buffer.from(base, "utf8"))
+        hash = 33 * hash ^ byte;
+    return `${prefix}-${(hash >>> 0).toString(36)}`;
+}
+const projectDirectory = (cwd) => join(dataRoot(), "projects", workbuddyProjectName(cwd));
+const profile = {
+    harness: "workbuddy",
+    label: "WorkBuddy",
+    binary: "codebuddy",
+    provider: "codebuddy",
+    dataRoot,
+    projectDirectory,
+    effortLevels: ["minimal", "low", "medium", "high", "xhigh", "max"],
+};
+/** The CLI lists selectable models (built-in and `models.json`) in its `--model` help. */
+export function workbuddyModels(help) {
+    const list = /--model <model>[\s\S]*?Currently supported:\s*\(([^)]*)\)/.exec(help)?.[1] ?? "";
+    const ids = [...new Set(list.split(",").map((id) => id.trim()).filter((id) => /^[\w.:/@-]{1,255}$/.test(id) && id !== DEFAULT_MODEL))];
+    if (!ids.length)
+        throw new Error("WorkBuddy lists no models; sign in to WorkBuddy or configure a model");
+    // The CLI ignores an effort level a model does not support.
+    return [streamJsonModel(profile, DEFAULT_MODEL, "Default", { reasoning: true, isDefault: true }), ...ids.map((id) => streamJsonModel(profile, id, id, { reasoning: true }))];
+}
+export const workbuddyHarness = {
+    id: "workbuddy",
+    binary: profile.binary,
+    models: async (executable, cwd) => workbuddyModels(await streamJsonHelp(profile, executable, cwd)),
+    run: (executor, turn) => runStreamJson(profile, executor, turn),
+    session: {
+        path: (nativeSessionId, cwd) => join(projectDirectory(cwd), `${nativeSessionId}.jsonl`),
+        startsWithoutFile: true,
+        // CodeBuddy stores Responses-style items: one record per message, call or result.
+        project: (input) => {
+            const names = new Map();
+            return projectChainedSession(input, "workbuddy", { id: "id", parent: "parentId" }, (segment) => {
+                const base = { timestamp: Date.parse(segment.message.createdAt) || 0, sessionId: input.nativeSessionId, cwd: input.cwd, cohub: projectionMeta(input, segment.message) };
+                if (segment.role === "user") {
+                    if (segment.blocks.some((block) => block.type === "tool_result")) {
+                        return segment.blocks.flatMap((block) => block.type === "tool_result"
+                            ? [{ ...base, type: "function_call_result", callId: projectionToolId(block.tool_use_id), name: names.get(block.tool_use_id) ?? "tool", status: "completed", output: { type: "text", text: toolResultText(block) } }]
+                            : []);
+                    }
+                    const content = segment.blocks.flatMap((block) => block.type === "text" ? [{ type: "input_text", text: block.text }]
+                        : block.type === "image" && block.source.type === "base64" ? [{ type: "input_image", image: `data:${block.source.media_type};base64,${block.source.data}` }]
+                            : []);
+                    return content.length ? [{ ...base, type: "message", role: "user", content, providerData: { startsNewUserRequest: true } }] : [];
+                }
+                const records = [];
+                for (const block of segment.blocks) {
+                    if (block.type === "text") {
+                        const previous = records.at(-1);
+                        if (previous?.type === "message")
+                            previous.content.push({ type: "output_text", text: block.text });
+                        else
+                            records.push({ ...base, type: "message", role: "assistant", status: "completed", content: [{ type: "output_text", text: block.text }] });
+                    }
+                    else if (block.type === "tool_use") {
+                        names.set(block.id, block.name);
+                        records.push({ ...base, type: "function_call", callId: projectionToolId(block.id), name: block.name, arguments: JSON.stringify(block.input) });
+                    }
+                }
+                return records;
+            });
+        },
+        rebind: rebindSessionId,
+        archive: {
+            // The copy takes a fresh id: the archived one may already exist here, and is never replaced.
+            target: ({ id, cwd }) => join(projectDirectory(cwd), `${id}.jsonl`),
+            async import(input) {
+                const { checksum } = await copyNativeArchive({ ...input, sessionId: input.id });
+                return { checksum, nativeSessionId: input.id };
+            },
+        },
+    },
+    nativeSync: false,
+};

package/dist/runtime/json-rpc.d.ts

@@ -32,11 +32,17 @@ export declare class JsonRpcProcess {
     private stderr;
     private closed;
     private closing;
-    constructor(binary: string, args: string[], cwd: string, mode: "pi" | "codex", context?: Record<string, string>);
+    private inputEnded;
+    /** `pi` and `jsonrpc` correlate request responses; `stream` delivers every line as an event. */
+    constructor(binary: string, args: string[], cwd: string, mode: "pi" | "jsonrpc" | "stream", context?: Record<string, string>);
     private fail;
     private receive;
     write(value: unknown): void;
     request(method: string, params?: JsonRecord, timeoutMs?: number): Promise<JsonRecord>;
+    /** Signal end of input; a stream-mode CLI flushes its transcript and exits. */
+    endInput(): void;
+    /** Whether the process exits within the timeout. */
+    exited(timeoutMs: number): Promise<boolean>;
     onEvent(listener: (event: JsonRecord) => void): () => boolean;
     onFailure(listener: (error: Error) => void): () => boolean;
     onTimeout(listener: (method: string, timeoutMs: number) => void): () => boolean;