@neta-art/cohub-cli 2.2.1 → 2.2.2

package/dist/avatar.js

@@ -18,7 +18,7 @@ export async function uploadAvatarAsset(input) {
         filename: "avatar.webp",
     });
 }
-const CHAT_IMAGE_MAX_EDGE = 2160;
+const CHAT_IMAGE_MAX_EDGE = 1984;
 const CHAT_IMAGE_QUALITY = 86;
 export async function normalizeChatImageFile(path) {
     return sharp(path)

package/dist/commands/references.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerReferences(program: Command): void;

package/dist/commands/references.js

@@ -0,0 +1,153 @@
+import { createClient } from "../client.js";
+import { table, json as outJson, jsonRequested, error, handleHttp } from "../output.js";
+const RESOURCE_TYPES = new Set([
+    "space",
+    "session",
+    "checkpoint",
+]);
+const REFERENCE_KINDS = new Set([
+    "session_fork",
+    "space_fork",
+    "checkpoint_fork",
+    "mention",
+    "tool_call",
+    "mod",
+    "participant",
+]);
+const DIRECTIONS = new Set(["out", "in", "both"]);
+const GROUP_BYS = new Set(["kind", "targetType", "sourceType", "day"]);
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function parseSource(value) {
+    const idx = value.indexOf(":");
+    if (idx <= 0)
+        throw new Error("Source must be <type>:<id>, e.g. session:<uuid>");
+    const type = value.slice(0, idx);
+    const id = value.slice(idx + 1).trim();
+    if (!RESOURCE_TYPES.has(type))
+        throw new Error(`Invalid resource type: ${type}`);
+    if (!id)
+        throw new Error("Missing resource id");
+    return { type, id };
+}
+function parseKinds(value) {
+    const kinds = value?.split(",").map((k) => k.trim()).filter(Boolean);
+    if (!kinds?.length)
+        return undefined;
+    const invalid = kinds.find((k) => !REFERENCE_KINDS.has(k));
+    if (invalid)
+        throw new Error(`Invalid reference kind: ${invalid}`);
+    return [...new Set(kinds)];
+}
+function clampNumber(value, fallback, min, max) {
+    const parsed = Number(value ?? fallback);
+    if (!Number.isFinite(parsed))
+        return fallback;
+    return Math.min(Math.max(Math.floor(parsed), min), max);
+}
+export function registerReferences(program) {
+    const references = program
+        .command("references")
+        .description("Inspect resource references (forks, mentions, tool calls, mods, participants)");
+    references
+        .command("query")
+        .description("List references touching a resource")
+        .argument("<source>", "Resource selector, e.g. session:<uuid> or space:<uuid>")
+        .option("--direction <dir>", "out | in | both", "both")
+        .option("--kinds <kinds>", "Comma-separated kinds to include")
+        .option("--days <n>", "Only references seen within the last N days")
+        .option("--limit <n>", "Maximum rows, 1-500", "200")
+        .option("--json", "Output as JSON")
+        .addHelpText("after", `
+
+Examples:
+  cohub references query session:<uuid> --json
+  cohub references query space:<uuid> --direction in --kinds mention,tool_call
+  cohub references query space:<uuid> --kinds mod --days 30
+`)
+        .action(async (source, opts) => {
+        const client = createClient();
+        try {
+            const ref = parseSource(source);
+            const direction = (opts.direction ?? "both");
+            if (!DIRECTIONS.has(direction))
+                return error(`Invalid direction: ${opts.direction}`);
+            const kinds = parseKinds(opts.kinds);
+            const days = opts.days ? clampNumber(opts.days, 30, 1, 365) : undefined;
+            const limit = clampNumber(opts.limit, 200, 1, 500);
+            const result = await client.references.query({
+                source: `${ref.type}:${ref.id}`,
+                direction,
+                kinds,
+                days,
+                limit,
+            });
+            if (jsonRequested(opts))
+                return outJson(result);
+            const rows = result.references.map((r) => ({
+                kind: r.kind,
+                source: `${r.sourceType}:${r.sourceId.slice(0, 8)}`,
+                target: `${r.targetType}:${r.targetId.slice(0, 8)}`,
+                count: r.count,
+                lastSeen: r.updatedAt.slice(0, 10),
+            }));
+            table(rows, [
+                { key: "kind", label: "Kind" },
+                { key: "source", label: "Source" },
+                { key: "target", label: "Target" },
+                { key: "count", label: "Count" },
+                { key: "lastSeen", label: "Last Seen" },
+            ]);
+        }
+        catch (e) {
+            if (e instanceof Error && (e.message.startsWith("Invalid") || e.message.startsWith("Source must") || e.message.startsWith("Missing"))) {
+                return error(e.message);
+            }
+            handleHttp(e);
+        }
+    });
+    references
+        .command("aggregate")
+        .description("Grouped reference counts for a space")
+        .argument("<spaceId>", "Space id")
+        .option("--group-by <field>", "kind | targetType | sourceType | day", "kind")
+        .option("--kinds <kinds>", "Comma-separated kinds to include")
+        .option("--days <n>", "Only references seen within the last N days")
+        .option("--json", "Output as JSON")
+        .addHelpText("after", `
+
+Examples:
+  cohub references aggregate <spaceId> --json
+  cohub references aggregate <spaceId> --group-by targetType
+  cohub references aggregate <spaceId> --group-by day --days 30
+`)
+        .action(async (spaceId, opts) => {
+        const client = createClient();
+        try {
+            if (!UUID_PATTERN.test(spaceId.trim()))
+                return error("Invalid space id");
+            const groupBy = (opts.groupBy ?? "kind");
+            if (!GROUP_BYS.has(groupBy))
+                return error(`Invalid group-by: ${opts.groupBy}`);
+            const kinds = parseKinds(opts.kinds);
+            const days = opts.days ? clampNumber(opts.days, 30, 1, 365) : undefined;
+            const result = await client.references.aggregate({ spaceId: spaceId.trim(), groupBy, kinds, days });
+            if (jsonRequested(opts))
+                return outJson(result);
+            const rows = result.groups.map((g) => ({
+                group: g.group,
+                references: g.references,
+                total: g.total,
+            }));
+            table(rows, [
+                { key: "group", label: "Group" },
+                { key: "references", label: "References" },
+                { key: "total", label: "Total" },
+            ]);
+        }
+        catch (e) {
+            if (e instanceof Error && e.message.startsWith("Invalid"))
+                return error(e.message);
+            handleHttp(e);
+        }
+    });
+}

package/dist/commands/sandbox.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerSandbox(program: Command): void;

package/dist/commands/sandbox.js

@@ -0,0 +1,170 @@
+import { spawn } from "node:child_process";
+import { stat } from "node:fs/promises";
+import { createInterface } from "node:readline";
+import { resolve } from "node:path";
+import { resolveCohubEnvironment, resolveWebsocketUrl } from "@neta-art/cohub";
+import { requireAccessToken } from "../auth.js";
+import { createClient } from "../client.js";
+import { error, json as outJson, jsonRequested, ok, spinner } from "../output.js";
+import { resolveSpace } from "../space.js";
+import { ensureSandboxdBinary, SandboxdDownloadError } from "./sandboxd-binary.js";
+// Derive the gateway relay control endpoint from the realtime websocket URL,
+// e.g. wss://gateway.cohub.run/ws -> wss://gateway.cohub.run/sandbox/relay.
+const resolveRelayUrl = () => {
+    const explicit = process.env.COHUB_RELAY_URL?.trim();
+    if (explicit)
+        return explicit;
+    const wsUrl = resolveWebsocketUrl({ url: process.env.COHUB_WS_URL });
+    return wsUrl.replace(/\/ws$/, "/sandbox/relay");
+};
+const confirm = async (question) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = await new Promise((res) => rl.question(`${question} [y/N] `, res));
+        return /^y(es)?$/i.test(answer.trim());
+    }
+    finally {
+        rl.close();
+    }
+};
+const webBaseUrl = () => resolveCohubEnvironment() === "prod" ? "https://cohub.run" : "https://dev.cohub.run";
+// Consent copy is deliberately explicit: a local sandbox runs agent-issued
+// shell commands as the current OS user. File RPCs are fenced to the folder,
+// but shell commands are NOT — they can read/write anything the user can
+// (SSH keys, other repos, etc). This mirrors the trust model of running an
+// AI coding agent locally and must be surfaced clearly before starting.
+const consentMessage = (rootDir, target) => [
+    `Start ${target} exposing ${rootDir}?`,
+    "",
+    "Agents in this space will be able to:",
+    `  • read and write files under ${rootDir}`,
+    "  • run shell commands as your user (full access to your machine, not just this folder)",
+    "",
+    "Only continue if you trust this space's collaborators.",
+].join("\n");
+export function registerSandbox(program) {
+    const cmd = program.command("sandbox").description("Run a local folder as a space sandbox");
+    // ── sandbox up ──
+    cmd
+        .command("up [dir]")
+        .description("Expose a local folder to a space as its sandbox (foreground; Ctrl-C to stop)")
+        .option("-s, --space <id>", "Bind to an existing space instead of creating one")
+        .option("-n, --name <name>", "Name for the newly created space")
+        .option("-y, --yes", "Skip the confirmation prompt")
+        .option("--json", "Output as JSON")
+        .action(async (dir, opts) => {
+        const rootDir = resolve(dir ?? process.cwd());
+        const info = await stat(rootDir).catch(() => null);
+        if (!info?.isDirectory()) {
+            return error("Invalid directory", `${rootDir} is not a directory`);
+        }
+        // A single spinner: first status starts it, later statuses only update the
+        // label (calling start twice would leak the previous interval).
+        const spin = spinner();
+        let spinnerStarted = false;
+        let binary;
+        try {
+            binary = await ensureSandboxdBinary({
+                onStatus: (msg) => {
+                    if (spinnerStarted) {
+                        spin.update(msg);
+                    }
+                    else {
+                        spin.start(msg);
+                        spinnerStarted = true;
+                    }
+                },
+            });
+            if (spinnerStarted)
+                spin.stop("");
+        }
+        catch (err) {
+            if (spinnerStarted)
+                spin.stop("");
+            if (err instanceof SandboxdDownloadError)
+                return error("Sandbox runtime unavailable", err.message);
+            throw err;
+        }
+        const relayUrl = resolveRelayUrl();
+        const token = await requireAccessToken();
+        const client = createClient();
+        // Resolve or create the target space.
+        let spaceId = opts.space?.trim() || program.opts().space?.trim();
+        if (!spaceId) {
+            if (!opts.yes) {
+                const proceed = await confirm(consentMessage(rootDir, "a new local space"));
+                if (!proceed)
+                    return error("Aborted", "No space was created");
+            }
+            const created = await client.spaces.create({
+                name: opts.name,
+                config: { sandbox: { provider: "local" } },
+            });
+            spaceId = created.space.id;
+            ok(`Created local space ${spaceId}`);
+        }
+        else {
+            // A local runner can only attach to a space whose sandbox provider is
+            // "local" (provider is fixed at space creation). Fail early with a clear
+            // message instead of letting the gateway reject the connection later.
+            const existing = await client.space(spaceId).sandbox.get().catch(() => null);
+            if (existing?.sandbox?.provider !== "local") {
+                return error("Not a local space", `Space ${spaceId} is not configured for a local sandbox. Create one with 'cohub sandbox up' (without --space).`);
+            }
+            if (!opts.yes) {
+                const proceed = await confirm(consentMessage(rootDir, `space ${spaceId}`));
+                if (!proceed)
+                    return error("Aborted", "Sandbox was not started");
+            }
+        }
+        const url = `${webBaseUrl()}/spaces/${spaceId}`;
+        if (jsonRequested(opts)) {
+            outJson({ spaceId, rootDir, relayUrl, url });
+        }
+        else {
+            ok(`Sandbox ready — open ${url}`);
+            console.log(`  Serving: ${rootDir}`);
+            console.log("  Press Ctrl-C to stop.\n");
+        }
+        // Spawn the runner in the foreground. It dials the gateway relay and
+        // stays connected until the process is interrupted.
+        const child = spawn(binary, ["--local", "--space", spaceId, "--root", rootDir, "--relay", relayUrl], {
+            stdio: ["ignore", "inherit", "inherit"],
+            env: { ...process.env, COHUB_RELAY_TOKEN: token },
+        });
+        const stop = () => child.kill("SIGTERM");
+        process.on("SIGINT", stop);
+        process.on("SIGTERM", stop);
+        await new Promise((res) => {
+            child.on("exit", (code, signal) => {
+                if (signal)
+                    console.log(`\nSandbox stopped (${signal}).`);
+                else if (code !== 0)
+                    console.error(`Sandbox exited with code ${code}.`);
+                res();
+            });
+            child.on("error", (err) => error("Failed to start sandbox", err.message));
+        });
+    });
+    // ── sandbox status ──
+    cmd
+        .command("status")
+        .description("Show the current sandbox status for a space")
+        .option("-s, --space <id>", "Target space ID")
+        .option("--json", "Output as JSON")
+        .action(async (opts) => {
+        const spaceId = opts.space?.trim() || resolveSpace(program);
+        const client = createClient();
+        const result = await client.space(spaceId).sandbox.get().catch(() => null);
+        const sandbox = result?.sandbox ?? null;
+        if (jsonRequested(opts))
+            return outJson({ spaceId, sandbox });
+        if (!sandbox) {
+            console.log("  (no sandbox)");
+            return;
+        }
+        console.log(`  space:    ${spaceId}`);
+        console.log(`  provider: ${sandbox.provider ?? "cloud"}`);
+        console.log(`  status:   ${sandbox.status ?? "unknown"}`);
+    });
+}

package/dist/commands/sandboxd-binary.d.ts

@@ -0,0 +1,9 @@
+export declare const SANDBOXD_VERSION = "v1.82.2";
+export declare class SandboxdDownloadError extends Error {
+    name: string;
+}
+export type EnsureSandboxdOptions = {
+    version?: string;
+    onStatus?: (message: string) => void;
+};
+export declare const ensureSandboxdBinary: (options?: EnsureSandboxdOptions) => Promise<string>;

package/dist/commands/sandboxd-binary.js

@@ -0,0 +1,217 @@
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { createReadStream, createWriteStream } from "node:fs";
+import { chmod, copyFile, mkdir, mkdtemp, rename, rm, stat } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { Readable } from "node:stream";
+// The sandboxd binary version is pinned independently of the CLI package: it
+// only needs to change when apps/sandbox changes, and the agent-sandbox wire
+// protocol ("1") guarantees backward compatibility.
+//
+// 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
+// default download.
+export const SANDBOXD_VERSION = "v1.82.2";
+const BINARY_NAME = "cohub-sandboxd";
+// Public CDN prefix hosting the release archives (the repo is private, so the
+// GitHub Release assets are not publicly downloadable). Overridable for staging
+// or self-hosting.
+const cdnBaseUrl = () => (process.env.COHUB_SANDBOXD_CDN_BASE_URL?.trim() || "https://public.cohub.run/sandboxd").replace(/\/+$/, "");
+const DOWNLOAD_TIMEOUT_MS = 120_000;
+const LOCK_STALE_MS = 5 * 60 * 1000;
+// Map Node's platform/arch to the Go GOOS/GOARCH used in release asset names.
+const GOOS_BY_PLATFORM = { darwin: "darwin", linux: "linux" };
+const GOARCH_BY_ARCH = { x64: "amd64", arm64: "arm64" };
+export class SandboxdDownloadError extends Error {
+    name = "SandboxdDownloadError";
+}
+const resolveTarget = () => {
+    const goos = GOOS_BY_PLATFORM[process.platform];
+    const goarch = GOARCH_BY_ARCH[process.arch];
+    if (!goos || !goarch) {
+        throw new SandboxdDownloadError(`Unsupported platform ${process.platform}/${process.arch}. Set COHUB_SANDBOXD_BIN to a locally built binary.`);
+    }
+    return { goos, goarch };
+};
+const cacheDir = (version) => join(homedir(), ".cache", "cohub", "sandboxd", version);
+const cachedBinaryPath = (version) => join(cacheDir(version), BINARY_NAME);
+const archiveName = (version, target) => `${BINARY_NAME}_${version}_${target.goos}_${target.goarch}.tar.gz`;
+const isExecutableFile = async (path) => {
+    const info = await stat(path).catch(() => null);
+    return Boolean(info?.isFile());
+};
+const sha256File = async (path) => {
+    const hash = createHash("sha256");
+    await pipeline(createReadStream(path), hash);
+    return hash.digest("hex");
+};
+// Run `fn` under a single AbortController whose timeout spans the entire body
+// read (not just the response headers), and normalize any network / timeout
+// failure into a user-readable SandboxdDownloadError.
+const withTimeout = async (what, fn) => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), DOWNLOAD_TIMEOUT_MS);
+    try {
+        return await fn(controller.signal);
+    }
+    catch (err) {
+        if (err instanceof SandboxdDownloadError)
+            throw err;
+        if (controller.signal.aborted) {
+            throw new SandboxdDownloadError(`${what} timed out after ${DOWNLOAD_TIMEOUT_MS / 1000}s`);
+        }
+        throw new SandboxdDownloadError(`${what} failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+};
+// Download a URL straight to disk. The timeout covers the full stream, so a
+// stalled body can never hang indefinitely.
+const downloadToFile = (url, accept, destPath) => withTimeout(`Download of ${url}`, async (signal) => {
+    const response = await fetch(url, { signal, headers: { accept } });
+    if (!response.ok)
+        throw new SandboxdDownloadError(`Download failed (${response.status}) for ${url}`);
+    if (!response.body)
+        throw new SandboxdDownloadError(`Empty response body for ${url}`);
+    // Cast: Node's web-stream typings diverge from the DOM lib bundled by tsc.
+    await pipeline(Readable.fromWeb(response.body), createWriteStream(destPath));
+});
+// Fetch a small text resource (the checksum manifest) under the same timeout.
+const fetchText = (url, accept) => withTimeout(`Download of ${url}`, async (signal) => {
+    const response = await fetch(url, { signal, headers: { accept } });
+    if (!response.ok)
+        throw new SandboxdDownloadError(`Download failed (${response.status}) for ${url}`);
+    return (await response.text()).trim();
+});
+// List the entries of a `.tar.gz` without extracting, so we can reject archives
+// that contain anything other than the expected single binary (path traversal,
+// symlinks, extra entries) before touching the filesystem.
+const listTarGz = (archivePath) => new Promise((res, rej) => {
+    const child = spawn("tar", ["-tzf", archivePath], { stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => {
+        stdout += chunk.toString();
+    });
+    child.stderr.on("data", (chunk) => {
+        stderr += chunk.toString();
+    });
+    child.on("error", rej);
+    child.on("close", (code) => code === 0
+        ? res(stdout.split("\n").map((line) => line.trim()).filter(Boolean))
+        : rej(new SandboxdDownloadError(`tar listing failed: ${stderr.trim() || `exit ${code}`}`)));
+});
+// Extract a single-file `.tar.gz` using the system tar (universally present on
+// macOS and Linux), keeping the CLI free of native archive dependencies.
+const extractTarGz = (archivePath, cwd) => new Promise((res, rej) => {
+    const child = spawn("tar", ["-xzf", archivePath, "-C", cwd], { stdio: ["ignore", "ignore", "pipe"] });
+    let stderr = "";
+    child.stderr.on("data", (chunk) => {
+        stderr += chunk.toString();
+    });
+    child.on("error", 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.
+const withLock = async (version, fn) => {
+    const lockPath = join(cacheDir(version), ".download.lock");
+    await mkdir(dirname(lockPath), { recursive: true });
+    for (let attempt = 0; attempt < 600; attempt += 1) {
+        try {
+            await mkdir(lockPath);
+            try {
+                return await fn();
+            }
+            finally {
+                await rm(lockPath, { recursive: true, force: true });
+            }
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+            const info = await stat(lockPath).catch(() => null);
+            if (info && Date.now() - info.mtimeMs > LOCK_STALE_MS) {
+                await rm(lockPath, { recursive: true, force: true }).catch(() => undefined);
+                continue;
+            }
+            await new Promise((r) => setTimeout(r, 500));
+        }
+    }
+    throw new SandboxdDownloadError("Timed out waiting for the sandboxd download lock");
+};
+const downloadAndVerify = async (version, target) => {
+    const name = archiveName(version, target);
+    const archiveUrl = `${cdnBaseUrl()}/${version}/${name}`;
+    const checksumUrl = `${archiveUrl}.sha256`;
+    const tempDir = await mkdtemp(join(tmpdir(), "cohub-sandboxd-"));
+    try {
+        const archivePath = join(tempDir, name);
+        // Fetch archive to disk (timeout covers the full body stream).
+        await downloadToFile(archiveUrl, "application/gzip", archivePath);
+        // Fetch and verify checksum. The .sha256 file is `<hash>  <filename>`.
+        const checksumText = await fetchText(checksumUrl, "text/plain");
+        const expected = checksumText.split(/\s+/)[0]?.toLowerCase();
+        if (!expected || !/^[0-9a-f]{64}$/.test(expected)) {
+            throw new SandboxdDownloadError(`Invalid checksum manifest for ${name}`);
+        }
+        const actual = (await sha256File(archivePath)).toLowerCase();
+        if (actual !== expected) {
+            throw new SandboxdDownloadError(`Checksum mismatch for ${name} (expected ${expected}, got ${actual})`);
+        }
+        // Verify the archive contains exactly the expected binary before extracting,
+        // guarding against path traversal / unexpected entries from a tampered CDN.
+        const entries = await listTarGz(archivePath);
+        if (entries.length !== 1 || entries[0] !== BINARY_NAME) {
+            throw new SandboxdDownloadError(`Unexpected archive contents for ${name}: ${entries.join(", ") || "(empty)"}`);
+        }
+        // Extract the single binary from the archive.
+        await extractTarGz(archivePath, tempDir);
+        const extractedBinary = join(tempDir, BINARY_NAME);
+        if (!(await isExecutableFile(extractedBinary))) {
+            throw new SandboxdDownloadError(`Archive ${name} did not contain ${BINARY_NAME}`);
+        }
+        // Atomically move into the version cache (fall back to copy across devices).
+        const dest = cachedBinaryPath(version);
+        await mkdir(dirname(dest), { recursive: true });
+        await rename(extractedBinary, dest).catch(async (err) => {
+            if (err.code !== "EXDEV")
+                throw err;
+            await copyFile(extractedBinary, dest);
+        });
+        await chmod(dest, 0o755);
+        return dest;
+    }
+    finally {
+        await rm(tempDir, { recursive: true, force: true }).catch(() => undefined);
+    }
+};
+// Resolve a runnable sandboxd binary path, downloading (once, cached) if needed.
+// COHUB_SANDBOXD_BIN always takes precedence for local development and offline use.
+export const ensureSandboxdBinary = async (options = {}) => {
+    const override = process.env.COHUB_SANDBOXD_BIN?.trim();
+    if (override) {
+        if (!(await isExecutableFile(override))) {
+            throw new SandboxdDownloadError(`COHUB_SANDBOXD_BIN=${override} is not a file`);
+        }
+        return override;
+    }
+    const version = options.version?.trim() || SANDBOXD_VERSION;
+    const cached = cachedBinaryPath(version);
+    if (await isExecutableFile(cached))
+        return cached;
+    const target = resolveTarget();
+    return withLock(version, async () => {
+        // Re-check inside the lock: another process may have finished downloading.
+        if (await isExecutableFile(cached))
+            return cached;
+        options.onStatus?.(`Downloading sandbox runtime ${version} (${target.goos}/${target.goarch})`);
+        const path = await downloadAndVerify(version, target);
+        options.onStatus?.("Sandbox runtime ready");
+        return path;
+    });
+};

package/dist/commands/spaces.js

@@ -678,6 +678,28 @@ function registerLabels(spacesCmd) {
             handleHttp(e);
         }
     });
+    labelsCmd
+        .command("patch <resourceType> <resourceRef>")
+        .description("Patch resource labels")
+        .option("--add <refs>", "Comma-separated label refs to add")
+        .option("--remove <refs>", "Comma-separated label refs to remove")
+        .option("--json", "Output as JSON")
+        .action(async (resourceType, resourceRef, opts) => {
+        const spaceId = resolveSpace(spacesCmd);
+        const client = createClient();
+        try {
+            const result = await client.space(spaceId).labels.patchResourceLabels(parseLabelResourceType(resourceType), resourceRef, {
+                addLabelRefs: parseLabelRefs(opts.add),
+                removeLabelRefs: parseLabelRefs(opts.remove),
+            });
+            if (jsonRequested(opts))
+                return outJson(result);
+            ok("Resource labels patched");
+        }
+        catch (e) {
+            handleHttp(e);
+        }
+    });
     labelsCmd
         .command("set <resourceType> <resourceRef> [labelRefs...]")
         .description("Set resource labels")

package/dist/index.js

@@ -9,8 +9,10 @@ import { registerMe } from "./commands/me.js";
 import { registerModels } from "./commands/models.js";
 import { registerProfile } from "./commands/profile.js";
 import { registerSearch } from "./commands/search.js";
+import { registerReferences } from "./commands/references.js";
 import { registerPrompt, registerSpaces } from "./commands/spaces.js";
 import { maybeHandleRunCommand } from "./commands/run.js";
+import { registerSandbox } from "./commands/sandbox.js";
 import { registerTasks } from "./commands/tasks.js";
 import { registerWorks } from "./commands/works.js";
 import { ensureCliSelfUpdated } from "./self-update.js";
@@ -40,6 +42,7 @@ Common commands:
   cohub spaces ls
   cohub -s <space-id> prompt "Fix the failing tests"
   cohub -s <space-id> run -- git status
+  cohub sandbox up ./my-project
   cohub search "release notes"
   cohub -s <space-id> spaces sessions turns ls <session-id>
   cohub -s <space-id> spaces files ls
@@ -58,10 +61,12 @@ registerProfile(program);
 registerMe(program);
 registerPrompt(program);
 registerSpaces(program);
+registerSandbox(program);
 registerChannels(program);
 registerGenerations(program);
 registerModels(program);
 registerSearch(program);
+registerReferences(program);
 registerTasks(program);
 registerCronJobs(program);
 registerWorks(program);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neta-art/cohub-cli",
-  "version": "2.2.1",
+  "version": "2.2.2",
   "description": "CLI for Cohub — spaces, sessions, and agent collaboration.",
   "type": "module",
   "license": "UNLICENSED",
@@ -16,7 +16,7 @@
     "@neta-art/generation": "^0.1.10",
     "commander": "^14.0.3",
     "sharp": "^0.34.5",
-    "@neta-art/cohub": "2.2.1"
+    "@neta-art/cohub": "2.3.0"
   },
   "publishConfig": {
     "access": "public"