@neta-art/cohub-cli 6.11.2 → 7.0.0

package/README.md

@@ -79,6 +79,27 @@ cohub -s <spaceId> spaces prompt "message" --json
 COHUB_SPACE_ID=<spaceId> cohub spaces prompt "message" --json
 ```
 
+## Local Runtime / 本地 Runtime
+
+Connect one local workspace to a Space and select Pi or Codex per turn.
+将一个本地工作区连接到 Space，每轮可选择 Pi 或 Codex。
+
+```bash
+cohub runtime up ./project --harness pi --harness codex
+cohub runtime up ./project --space <spaceId> --harness codex
+cohub -s <spaceId> spaces prompt "Continue / 继续" --harness codex
+cohub runtime status --space <spaceId>
+```
+
+The Runtime uses WebSockets, native Pi RPC / Codex app-server, and existing cloud
+streaming. Local executables and credentials are required. `sandbox up` has been
+removed. Reconnection and result reconciliation are automatic; no recovery command is needed.
+See [Runtime details](../../docs/local-runtime.md).
+
+Runtime 使用 WebSocket、原生 Pi RPC / Codex app-server 和现有云端流式链路。
+需要本机已安装并登录对应程序。Runtime 断线重连和结果核对自动完成，无需恢复命令。
+仅在无法确定结果时，由 Space 页头提供异常确认。旧 `sandbox up` 命令已移除。
+
 ## Chats and prompts
 
 Use `spaces prompt` for immediate sends, delayed sends, one-time schedules, recurring schedules, new Chats, and existing Chats.

package/dist/commands/apps.js

@@ -31,6 +31,15 @@ function parseJsonObject(value, name) {
     }
     return error(`Invalid ${name}`, `${name} must be a JSON object`);
 }
+/** Human-readable version provenance: a session title, a channel, or blank. */
+function formatVersionSource(value) {
+    if (!value || typeof value !== "object")
+        return "";
+    const source = value;
+    if (source?.session)
+        return source.session.title?.trim() || source.session.id;
+    return source?.via ? `via ${source.via}` : "";
+}
 function parseJsonValue(value, name) {
     if (!value)
         return null;
@@ -499,7 +508,7 @@ export function registerApps(program) {
         .option("--app-scope <scope>", "Scope granted directly to the app runtime (space.view, session.view, file.view, file.edit, taskrun.view, session.prompt.readonly, session.prompt.fullaccess, command.execute)", collectOption, [])
         .option("--viewer-scope <scope>", "Deprecated: viewer grants are no longer gated by the app configuration", collectOption, [])
         .option("--clear-app-scopes", "Clear app runtime scopes")
-        .option("--clear-viewer-scopes", "Clear viewer-requestable scopes")
+        .option("--clear-viewer-scopes", "Deprecated: clear legacy scope metadata / 已废弃：清除旧权限元数据")
         .option("--meta <json>", "App metadata as a JSON object")
         .option("--hide-cohub-bar", "Hide the Cohub footer bar on the public app page")
         .option("--show-cohub-bar", "Show the Cohub footer bar on the public app page")
@@ -599,6 +608,7 @@ export function registerApps(program) {
                 { key: "id", label: "ID" },
                 { key: "targetType", label: "Target" },
                 { key: "targetRef", label: "Ref" },
+                { key: "source", label: "Source", format: formatVersionSource },
                 { key: "createdAt", label: "Created" },
             ]);
         }
@@ -718,6 +728,7 @@ export function registerApps(program) {
         .description("Grant an app scopes as the current user")
         .requiredOption("--scope <scope>", "Scope to grant (repeatable)", collectOption, [])
         .option("--space <spaceId>", "Target space; defaults to the app's own space")
+        .option("--extend", "Add scopes without replacing active grants / 增加权限，保留有效授权")
         .option("--json", "Output as JSON")
         .action(async (appRef, opts) => {
         const client = createClient();
@@ -726,6 +737,7 @@ export function registerApps(program) {
             const result = await client.apps.authorize(detail.app.id, {
                 scopes: opts.scope,
                 ...(opts.space ? { spaceId: opts.space } : {}),
+                ...(opts.extend ? { scopeMode: "extend" } : {}),
             });
             if (jsonRequested(opts))
                 return outJson(result);

package/dist/commands/runtime.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+export declare const resolveLocalSpaceName: (root: string, name?: string) => string;
+export declare function parseRuntimeHarnesses(values: string[]): ("pi" | "codex")[];
+export declare function registerRuntime(program: Command): void;

package/dist/commands/runtime.js

@@ -0,0 +1,117 @@
+import { spawn } from "node:child_process";
+import { stat } from "node:fs/promises";
+import { basename, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { isLocalHarness, resolveCohubEnvironment, resolveWebsocketUrl } from "@neta-art/cohub";
+import { requireAccessToken } from "../auth.js";
+import { createClient } from "../client.js";
+import { error, json as outJson, jsonRequested } from "../output.js";
+import { resolveSpace } from "../space.js";
+import { discoverHarnesses } from "../runtime/harness.js";
+import { serveRuntime } from "../runtime/connection.js";
+import { RuntimeSessionStore } from "../runtime/session-store.js";
+import { ensureSandboxdBinary } from "./sandboxd-binary.js";
+export const resolveLocalSpaceName = (root, name) => name?.trim() || basename(root) || "local-space";
+export function parseRuntimeHarnesses(values) {
+    const names = values.flatMap((value) => value.split(",")).map((name) => name.trim()).filter(Boolean);
+    if (names.some((name) => !isLocalHarness(name)))
+        throw new Error("Harness must be pi or codex / Harness 必须是 pi 或 codex");
+    return [...new Set(names.length ? names : ["pi"])];
+}
+export function registerRuntime(program) {
+    const runtime = program.command("runtime").description("Connect a local workspace / 连接本地工作区");
+    runtime.command("up [dir]")
+        .description("Connect local Harnesses and files / 连接本地 Harness 与文件")
+        .option("-s, --space <id>", "Target Space / 目标 Space")
+        .option("-n, --name <name>", "New Space name / 新 Space 名称")
+        .option("--harness <name>", "Pi or Codex; repeatable / Pi 或 Codex，可重复", (value, previous) => [...previous, value], [])
+        .option("--pi <path>", "Pi executable / Pi 可执行文件")
+        .option("--codex <path>", "Codex executable / Codex 可执行文件")
+        .option("-y, --yes", "Accept local execution access / 同意本机执行权限")
+        .option("--json", "JSON output / JSON 输出")
+        .action(async (dir, options) => {
+        const controller = new AbortController();
+        const stop = () => controller.abort();
+        process.once("SIGINT", stop);
+        process.once("SIGTERM", stop);
+        try {
+            const root = resolve(dir ?? process.cwd());
+            if (!(await stat(root)).isDirectory())
+                throw new Error("Workspace is not a directory / 工作区不是目录");
+            const harnesses = parseRuntimeHarnesses(options.harness);
+            if (!options.yes) {
+                if (!process.stdin.isTTY)
+                    throw new Error("Use --yes to authorize local execution / 请使用 --yes 授权本机执行");
+                const rl = createInterface({ input: process.stdin, output: process.stderr });
+                try {
+                    const answer = await rl.question(`Connect ${root}? Space collaborators can run commands as your OS user, beyond this folder.\n连接此目录？Space 协作者可使用当前系统用户执行命令，权限不限于此目录。 [y/N] `);
+                    if (!/^y(es)?$/i.test(answer.trim()))
+                        return;
+                }
+                finally {
+                    rl.close();
+                }
+            }
+            const capabilities = await discoverHarnesses(harnesses, options, root);
+            const client = createClient();
+            const requested = options.space?.trim() || program.opts().space?.trim();
+            const spaceId = requested || (await client.spaces.create({ name: resolveLocalSpaceName(root, options.name), config: { sandbox: { provider: "local" } } })).space.id;
+            const sandbox = (await client.space(spaceId).sandbox.get()).sandbox;
+            if (sandbox?.provider !== "local")
+                throw new Error("Space does not have a local Runtime / Space 不是本地 Runtime");
+            const binary = await ensureSandboxdBinary();
+            const wsBase = resolveWebsocketUrl({ url: process.env.COHUB_WS_URL });
+            const url = new URL(wsBase);
+            url.pathname = "/runtime/relay";
+            const relay = new URL(wsBase);
+            relay.pathname = "/sandbox/relay";
+            let bridge = null;
+            let bridgeClosed = Promise.resolve();
+            const token = await requireAccessToken();
+            try {
+                await serveRuntime({
+                    spaceId, cwd: root, url: url.toString(), capabilities, harnesses: options,
+                    token: requireAccessToken, signal: controller.signal, store: new RuntimeSessionStore(spaceId, undefined, client.space(spaceId)),
+                    onReady: () => {
+                        if (!bridge) {
+                            bridge = spawn(binary, ["--local", "--space", spaceId, "--root", root, "--relay", process.env.COHUB_RELAY_URL?.trim() || relay.toString()], { stdio: ["ignore", "inherit", "inherit"], env: { ...process.env, COHUB_RELAY_TOKEN: token } });
+                            bridgeClosed = new Promise((resolveClosed) => bridge?.once("close", () => resolveClosed()));
+                            bridge.on("error", (cause) => { console.error(cause); controller.abort(); });
+                            bridge.once("exit", () => controller.abort());
+                        }
+                        const webUrl = `${resolveCohubEnvironment() === "prod" ? "https://cohub.live" : "https://dev.cohub.live"}/spaces/${spaceId}`;
+                        if (jsonRequested(options))
+                            outJson({ spaceId, root, harnesses, url: webUrl });
+                        else
+                            console.error(`Runtime connected / Runtime 已连接: ${webUrl}`);
+                    },
+                });
+            }
+            finally {
+                if (bridge) {
+                    const child = bridge;
+                    child.kill("SIGTERM");
+                    const timeout = setTimeout(() => child.kill("SIGKILL"), 3000);
+                    await bridgeClosed;
+                    clearTimeout(timeout);
+                }
+            }
+        }
+        catch (cause) {
+            if (!controller.signal.aborted)
+                error("Runtime failed / Runtime 失败", cause instanceof Error ? cause.message : String(cause));
+        }
+        finally {
+            process.removeListener("SIGINT", stop);
+            process.removeListener("SIGTERM", stop);
+        }
+    });
+    runtime.command("status").description("Runtime status / Runtime 状态").option("-s, --space <id>", "Target Space / 目标 Space").action(async (options) => {
+        const spaceId = options.space?.trim() || await resolveSpace(program);
+        const { archives } = new RuntimeSessionStore(spaceId);
+        const [status, pendingLocalArchives, failedLocalArchives] = await Promise.all([
+            createClient().space(spaceId).getRuntime(), archives.pendingCount(), archives.failedCaptureCount(),
+        ]);
+        outJson({ ...status, pendingLocalArchives, failedLocalArchives });
+    });
+}

package/dist/commands/sandboxd-binary.js

@@ -12,7 +12,7 @@ import { Readable } from "node:stream";
 //
 // IMPORTANT: this must point at a tag whose CDN artifacts have already been
 // published by .github/workflows/sandbox-binaries-build.yml. Only bump it AFTER
-// that tag's publish-cdn job has succeeded, otherwise `sandbox up` 404s on the
+// that tag's publish-cdn job has succeeded, otherwise `runtime up` 404s on the
 // default download.
 export const SANDBOXD_VERSION = "v1.82.4";
 const BINARY_NAME = "cohub-sandboxd";
@@ -117,7 +117,7 @@ const extractTarGz = (archivePath, cwd) => new Promise((res, rej) => {
     child.on("close", (code) => code === 0 ? res() : rej(new SandboxdDownloadError(`tar extraction failed: ${stderr.trim() || `exit ${code}`}`)));
 });
 // Cross-process lock via atomic mkdir, mirroring the CLI self-update lock so two
-// concurrent `sandbox up` invocations don't download the same archive twice.
+// concurrent `runtime up` invocations don't download the same archive twice.
 const withLock = async (version, fn) => {
     const lockPath = join(cacheDir(version), ".download.lock");
     await mkdir(dirname(lockPath), { recursive: true });

package/dist/commands/spaces.js

@@ -282,6 +282,7 @@ async function sendPrompt(command, words, opts) {
             content: promptContent,
             model: opts.model,
             provider: opts.provider,
+            harness: opts.harness,
             thinkingLevel: thinkingLevel,
             accessMode: opts.readOnly ? "read_only" : "full_access",
             intent: opts.steer ? "steer" : undefined,
@@ -388,6 +389,7 @@ export function registerPrompt(program) {
         .option("--title <title>", "Title for a newly created session or schedule")
         .option("-m, --model <model>", "Model name")
         .option("-p, --provider <provider>", "Provider name")
+        .option("--harness <harness>", "Harness: cohub, pi, or codex", "cohub")
         .option("--thinking-level <level>", "Thinking level: off|minimal|low|medium|high|xhigh|max")
         .option("--read-only", "Use read-only tools")
         .option("--steer", "Interrupt the current turn and run immediately")
@@ -615,6 +617,7 @@ export function registerSpaces(program) {
         .command("prompt [content...]", { hidden: true })
         .alias("send")
         .description("Send or schedule a prompt in the target space")
+        .option("--harness <harness>", "Harness: cohub, pi, or codex", "cohub")
         .option("--session <id>", "Target session ID")
         .option("--title <title>", "Title for a newly created session or schedule")
         .option("-m, --model <model>", "Model name")

package/dist/index.js

@@ -17,7 +17,7 @@ import { registerReferences } from "./commands/references.js";
 import { registerReferrals } from "./commands/referrals.js";
 import { registerPrompt, registerSpaces } from "./commands/spaces.js";
 import { maybeHandleRunCommand, printRunHelp } from "./commands/run.js";
-import { registerSandbox } from "./commands/sandbox.js";
+import { registerRuntime } from "./commands/runtime.js";
 import { registerTasks } from "./commands/tasks.js";
 import { registerDesktop, registerLegacyUi } from "./commands/desktop.js";
 import { registerApps } from "./commands/apps.js";
@@ -53,7 +53,7 @@ Common commands:
   cohub prompt "Fix the failing tests"
   cohub completion "Summarize AGENTS.md" --system-prompt AGENTS.md --stream
   cohub run -- git status
-  cohub sandbox up ./my-project
+  cohub runtime up ./my-project
   cohub search "release notes"
   cohub -s <space-id> boards inspect <board-id>
   cohub -s <space-id> spaces turns ls --author others
@@ -82,7 +82,7 @@ registerProfile(program);
 registerMe(program);
 registerPrompt(program);
 registerSpaces(program);
-registerSandbox(program);
+registerRuntime(program);
 registerChannels(program);
 registerGenerations(program);
 registerModels(program);

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

@@ -0,0 +1,44 @@
+import { type HarnessArchive, type HarnessArchiveIndex, type RuntimeArchivePage, type RuntimeArchiveUpload } from "@neta-art/cohub";
+export type ArchiveTransport = {
+    fetchObject?: typeof fetch;
+    prepareRuntimeArchive(index: HarnessArchiveIndex, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        uploads: RuntimeArchiveUpload[];
+    }>;
+    commitRuntimeArchive(index: HarnessArchiveIndex, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        ready: true;
+    }>;
+    getRuntimeArchive(sessionId: string, turnId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<RuntimeArchivePage>;
+};
+export declare function checksumNativeFile(path: string): Promise<string>;
+export declare function atomicRuntimeJson(path: string, value: unknown): Promise<void>;
+/** Immutable local segments are the outbox. Model acknowledgements never remove them. */
+export declare class RuntimeArchiveStore {
+    readonly root: string;
+    private readonly transport?;
+    private flushing;
+    private readonly capturing;
+    constructor(root: string, transport?: ArchiveTransport | undefined);
+    pendingCount(): Promise<number>;
+    failedCaptureCount(): Promise<number>;
+    hasCapture(turnId: string): Promise<boolean>;
+    private version;
+    private blob;
+    private saveBlob;
+    private readIndex;
+    stage(state: {
+        sessionId: string;
+        harness: "pi" | "codex";
+        nativeSessionId: string;
+        path: string;
+    }, turnId: string): Promise<HarnessArchive>;
+    private capture;
+    flush(signal: AbortSignal): Promise<void>;
+    private drain;
+    restore(reference: HarnessArchive, target: string, signal?: AbortSignal): Promise<HarnessArchiveIndex>;
+}