@boxcompute/cli 0.1.1 → 0.2.0

package/README.md

@@ -33,14 +33,37 @@ compatible coding harnesses. It does not recursively scan your home directory.
 Use `bxc skill install all` to target every supported harness, or name one or
 more explicitly. Run `bxc skill remove --yes` to uninstall matching copies.
 
+Skills installed by `bxc` are managed copies. A global CLI upgrade refreshes an
+untouched managed copy during installation, with a safe retry on the next
+normal `bxc` command if package lifecycle scripts were disabled. Locally
+modified skills are never overwritten; the CLI reports the path and leaves
+replacement behind the explicit `bxc skill install --force` command. Start a
+new agent session after the CLI reports that a skill was updated.
+
 ## Use sandboxes
 
 ```sh
 bxc doctor
+bxc workspaces
 bxc sandboxes
 bxc sandbox start WORKSPACE_ID
-bxc sandbox exec WORKSPACE_ID -- python -m pytest
+# Use the returned sandbox instance ID for later commands.
+bxc sandbox exec SANDBOX_ID -- python -m pytest
 ```
 
 Run `bxc` or `bxc --help` for the complete command reference. The previous
 `bcompute` executable remains available as a compatibility alias.
+
+## Upgrade rollout
+
+Deploy the server release with both Sandbox API v1 and v2 before publishing CLI
+0.2. Existing CLI 0.1 clients remain on the legacy v1 workspace-sandbox
+contract. After that, clients need only upgrade the package:
+
+```sh
+npm install --global @boxcompute/cli@latest
+```
+
+The installation refreshes untouched managed skills before the client's next
+agent session. The new CLI uses v2 for multi-instance sandboxes and gives a
+server-first upgrade message if it reaches an older deployment.

package/dist/cli.d.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { type Connection } from "./config.js";
-import { detectHarnesses, installSkill, readSkill, removeSkill } from "./skill.js";
+import { detectHarnesses, installSkill, readSkill, removeSkill, syncManagedSkills } from "./skill.js";
 type Io = {
     stdout: NodeJS.WritableStream;
     stderr: NodeJS.WritableStream;
@@ -20,6 +20,7 @@ export type CliDependencies = {
     installSkill?: typeof installSkill;
     removeSkill?: typeof removeSkill;
     readSkill?: typeof readSkill;
+    syncManagedSkills?: typeof syncManagedSkills;
 };
 export declare function runCli(argv: string[], supplied?: CliDependencies): Promise<number>;
 export declare function formatCliError(error: unknown): string;

package/dist/cli.js

@@ -5,7 +5,7 @@ import { hostname, platform } from "node:os";
 import { fileURLToPath } from "node:url";
 import { BoxComputeClient, BoxComputeHttpError, publicRequest, } from "./client.js";
 import { clearConnection, loadConnection, loadSavedUrl, saveConnection, } from "./config.js";
-import { HARNESS_IDS, detectHarnesses, installSkill, readSkill, removeSkill, } from "./skill.js";
+import { HARNESS_IDS, detectHarnesses, installSkill, readSkill, removeSkill, syncManagedSkills, } from "./skill.js";
 const DEFAULT_URL = "https://app.boxcompute.ai";
 const CLI_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 const rootHelp = `BoxCompute CLI
@@ -20,9 +20,10 @@ Commands:
   auth                            [alias: login] Authentication commands
     logout                        Revoke and remove the saved CLI credential
   doctor                          Verify the saved connection
-  sandboxes                       [aliases: list, ls] List workspaces and sandbox state
+  workspaces                      List workspaces that can own sandboxes
+  sandboxes                       [aliases: list, ls] List sandbox instances
   sandbox                         Manage isolated BoxCompute sandboxes
-    start                         Start or resume a workspace sandbox
+    start                         Create and start a workspace sandbox
     status                        Inspect one sandbox
     exec                          Execute a program inside a sandbox
     delete                        [alias: rm] Destroy the runtime; the workspace remains
@@ -49,7 +50,9 @@ Examples:
   $ bxc login
   $ bxc skill detect
   $ bxc skill install
-  $ bxc sandbox exec WORKSPACE_ID -- python -m pytest
+  $ bxc workspaces
+  $ bxc sandbox start WORKSPACE_ID
+  $ bxc sandbox exec SANDBOX_ID -- python -m pytest
 
 Compatibility:
 
@@ -61,7 +64,7 @@ Usage: bxc sandbox <command> [options]
 
 Commands:
 
-  start WORKSPACE_ID              Start or resume a workspace sandbox
+  start WORKSPACE_ID              Create and start a new sandbox instance
   status SANDBOX_ID               Inspect one sandbox
   exec SANDBOX_ID [options] -- PROGRAM [ARG...]
                                   Execute a program inside a sandbox
@@ -229,6 +232,9 @@ async function authenticate(args, dependencies) {
 function sandboxLine(sandbox) {
     return `${sandbox.id}\t${sandbox.state}\t${sandbox.name}\n`;
 }
+function workspaceLine(workspace) {
+    return `${workspace.id}\t${workspace.name}\n`;
+}
 function executionOutput(io, json, sandboxId, result) {
     if (json)
         emit(io, true, { sandboxId, ...result }, "");
@@ -254,6 +260,7 @@ export async function runCli(argv, supplied = {}) {
     const install = supplied.installSkill ?? installSkill;
     const remove = supplied.removeSkill ?? removeSkill;
     const skillText = supplied.readSkill ?? readSkill;
+    const syncSkills = supplied.syncManagedSkills ?? syncManagedSkills;
     const args = [...argv];
     const json = flag(args, "json");
     const versionRequested = args[0] === "version" || anyFlag(args, "--version", "-V", "-v");
@@ -274,6 +281,26 @@ export async function runCli(argv, supplied = {}) {
         command = "skill";
     if (command === "list" || command === "ls")
         command = "sandboxes";
+    const canAutoSync = supplied.syncManagedSkills !== undefined || supplied.env === undefined ||
+        Boolean(env.HOME || env.USERPROFILE);
+    if (command !== "skill" && canAutoSync) {
+        try {
+            const synced = await syncSkills(env);
+            const updated = synced.filter((item) => item.status === "updated");
+            const modified = synced.filter((item) => item.status === "modified");
+            if (updated.length) {
+                write(io.stderr, `Updated the BoxCompute skill for ${updated.flatMap((item) => item.agents).join(", ")}. ` +
+                    "Start a new agent session to load it.\n");
+            }
+            for (const item of modified) {
+                write(io.stderr, `Kept locally modified BoxCompute skill at ${item.path}; run ` +
+                    "`bxc skill install --force` to replace it.\n");
+            }
+        }
+        catch (error) {
+            write(io.stderr, `Could not check installed BoxCompute skills: ${error?.message ?? String(error)}\n`);
+        }
+    }
     if (command === "logout") {
         if (args.length)
             throw new UsageError("logout takes no options");
@@ -367,14 +394,21 @@ export async function runCli(argv, supplied = {}) {
     const client = new BoxComputeClient(connection, fetchImpl);
     if (command === "doctor") {
         const sandboxes = await client.list();
-        emit(io, json, { connected: true, url: connection.url, sandboxes: sandboxes.length }, `Connected to ${connection.url} · ${sandboxes.length} workspace${sandboxes.length === 1 ? "" : "s"}\n`);
+        emit(io, json, { connected: true, url: connection.url, sandboxes: sandboxes.length }, `Connected to ${connection.url} · ${sandboxes.length} sandbox${sandboxes.length === 1 ? "" : "es"}\n`);
         return 0;
     }
     if (command === "sandboxes") {
         if (args.length)
             throw new UsageError("sandboxes takes no options");
         const sandboxes = await client.list();
-        emit(io, json, { sandboxes }, sandboxes.length ? sandboxes.map(sandboxLine).join("") : "No workspaces found. Create one in BoxCompute first.\n");
+        emit(io, json, { sandboxes }, sandboxes.length ? sandboxes.map(sandboxLine).join("") : "No sandboxes found. Start one for a BoxCompute workspace first.\n");
+        return 0;
+    }
+    if (command === "workspaces") {
+        if (args.length)
+            throw new UsageError("workspaces takes no options");
+        const workspaces = await client.listWorkspaces();
+        emit(io, json, { workspaces }, workspaces.length ? workspaces.map(workspaceLine).join("") : "No workspaces found. Create one in BoxCompute first.\n");
         return 0;
     }
     if (command !== "sandbox")

package/dist/client.d.ts

@@ -3,12 +3,17 @@ export type Sandbox = {
     id: string;
     workspaceId: string;
     name: string;
-    state: "not-created" | "cold" | "running";
+    state: "cold" | "running";
     runtimeId: string | null;
     image: string | null;
     createdAt: number;
     lastUsedAt: number | null;
 };
+export type Workspace = {
+    id: string;
+    name: string;
+    createdAt: number;
+};
 export type Execution = {
     stdout: string;
     stderr: string;
@@ -30,6 +35,7 @@ export declare class BoxComputeClient {
     constructor(connection: Connection, fetchImpl?: typeof fetch);
     private request;
     list(): Promise<Sandbox[]>;
+    listWorkspaces(): Promise<Workspace[]>;
     logout(): Promise<void>;
     inspect(id: string): Promise<Sandbox>;
     start(workspaceId: string): Promise<Sandbox>;

package/dist/client.js

@@ -25,35 +25,48 @@ export class BoxComputeClient {
         this.connection = connection;
         this.fetchImpl = fetchImpl;
     }
-    request(pathname, init = {}) {
+    async request(pathname, init = {}) {
         const headers = new Headers(init.headers);
         headers.set("authorization", `Bearer ${this.connection.token}`);
-        return publicRequest(this.connection.url, pathname, { ...init, headers }, this.fetchImpl);
+        try {
+            return await publicRequest(this.connection.url, pathname, { ...init, headers }, this.fetchImpl);
+        }
+        catch (error) {
+            const isV2Discovery = pathname === "/api/v2/sandboxes" ||
+                pathname === "/api/v2/workspaces" || pathname === "/api/v2/auth";
+            if (isV2Discovery && error instanceof BoxComputeHttpError && error.status === 404) {
+                throw new BoxComputeHttpError(404, "This BoxCompute server does not support Sandbox API v2 yet. Upgrade the server before this CLI.", error.code);
+            }
+            throw error;
+        }
     }
     async list() {
-        return (await this.request("/api/v1/sandboxes")).sandboxes;
+        return (await this.request("/api/v2/sandboxes")).sandboxes;
+    }
+    async listWorkspaces() {
+        return (await this.request("/api/v2/workspaces")).workspaces;
     }
     async logout() {
-        await this.request("/api/v1/auth", { method: "DELETE" });
+        await this.request("/api/v2/auth", { method: "DELETE" });
     }
     async inspect(id) {
-        return (await this.request(`/api/v1/sandboxes/${encodeURIComponent(id)}`)).sandbox;
+        return (await this.request(`/api/v2/sandboxes/${encodeURIComponent(id)}`)).sandbox;
     }
     async start(workspaceId) {
-        return (await this.request("/api/v1/sandboxes", {
+        return (await this.request("/api/v2/sandboxes", {
             method: "POST",
             headers: { "content-type": "application/json" },
             body: JSON.stringify({ workspaceId }),
         })).sandbox;
     }
     async execute(id, input) {
-        return (await this.request(`/api/v1/sandboxes/${encodeURIComponent(id)}/execute`, {
+        return (await this.request(`/api/v2/sandboxes/${encodeURIComponent(id)}/execute`, {
             method: "POST",
             headers: { "content-type": "application/json" },
             body: JSON.stringify(input),
         })).result;
     }
     async delete(id) {
-        await this.request(`/api/v1/sandboxes/${encodeURIComponent(id)}`, { method: "DELETE" });
+        await this.request(`/api/v2/sandboxes/${encodeURIComponent(id)}`, { method: "DELETE" });
     }
 }

package/dist/postinstall.d.ts

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

package/dist/postinstall.js

@@ -0,0 +1,24 @@
+import { syncManagedSkills } from "./skill.js";
+// A global CLI upgrade happens before the user starts their coding harness, so
+// this is the one point where an untouched installed skill can be refreshed in
+// time for the next agent session. Package managers that suppress lifecycle
+// scripts still get the same safe check on the next normal bxc invocation.
+const globalInstall = process.env.npm_config_global === "true" ||
+    process.env.npm_config_global === "1";
+if (globalInstall) {
+    try {
+        const results = await syncManagedSkills(process.env);
+        const updated = results.filter((item) => item.status === "updated");
+        const modified = results.filter((item) => item.status === "modified");
+        if (updated.length) {
+            console.log(`Updated the BoxCompute skill for ${updated.flatMap((item) => item.agents).join(", ")}.`);
+        }
+        for (const item of modified) {
+            console.warn(`Kept locally modified BoxCompute skill at ${item.path}; ` +
+                "run `bxc skill install --force` to replace it.");
+        }
+    }
+    catch (error) {
+        console.warn(`Could not check installed BoxCompute skills: ${error?.message ?? String(error)}`);
+    }
+}

package/dist/skill.d.ts

@@ -19,11 +19,16 @@ export type SkillInstallationResult = SkillInstallation & {
 export type SkillRemovalResult = SkillInstallation & {
     status: "removed" | "missing";
 };
+export type SkillSyncResult = SkillInstallation & {
+    status: "updated" | "unchanged" | "modified";
+};
 export declare function detectHarnesses(env?: NodeJS.ProcessEnv): Promise<HarnessDetection[]>;
 export declare function installSkill(requested?: AgentTarget | AgentTarget[], options?: {
     force?: boolean;
     env?: NodeJS.ProcessEnv;
 }): Promise<SkillInstallationResult[]>;
+/** Refresh untouched skill copies installed by bxc, preserving local edits. */
+export declare function syncManagedSkills(env?: NodeJS.ProcessEnv): Promise<SkillSyncResult[]>;
 export declare function removeSkill(requested?: AgentTarget | AgentTarget[], options?: {
     force?: boolean;
     env?: NodeJS.ProcessEnv;

package/dist/skill.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { constants } from "node:fs";
-import { access, cp, mkdir, readFile, readdir, rename, rm, stat } from "node:fs/promises";
+import { access, cp, mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -20,6 +20,14 @@ export const HARNESS_IDS = [
     "agents",
 ];
 const sourceSkill = fileURLToPath(new URL("../skills/boxcompute-sandbox", import.meta.url));
+const MANAGED_SKILL_FILE = ".boxcompute-managed.json";
+const MANAGED_BY = "@boxcompute/cli";
+// @boxcompute/cli 0.1.2 predates managed manifests. Recognizing its packaged
+// digest gives existing customers a one-time automatic bridge into managed
+// updates without treating arbitrary skill directories as ours.
+const LEGACY_MANAGED_DIGESTS = new Set([
+    "00d64cd0c71847976baaf6e3d449c0cf1d5fe0d3b3c752b2a05faba906916338",
+]);
 function locations(env) {
     const home = env.HOME || homedir();
     return {
@@ -51,10 +59,12 @@ async function directoryDigest(directory) {
     const digest = createHash("sha256");
     const walk = async (current, prefix = "") => {
         const entries = await readdir(current, { withFileTypes: true });
-        entries.sort((left, right) => left.name.localeCompare(right.name));
+        entries.sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
         for (const entry of entries) {
             const relative = path.posix.join(prefix, entry.name);
             const absolute = path.join(current, entry.name);
+            if (relative === MANAGED_SKILL_FILE)
+                continue;
             if (entry.isDirectory())
                 await walk(absolute, relative);
             else if (entry.isFile()) {
@@ -79,6 +89,47 @@ async function matchesPackagedSkill(candidate) {
         return false;
     }
 }
+async function managedManifest(candidate) {
+    try {
+        const parsed = JSON.parse(await readFile(path.join(candidate, MANAGED_SKILL_FILE), "utf8"));
+        return parsed.schema === 1 && parsed.managedBy === MANAGED_BY &&
+            typeof parsed.contentDigest === "string"
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function writeManagedManifest(candidate) {
+    const manifest = {
+        schema: 1,
+        managedBy: MANAGED_BY,
+        contentDigest: await directoryDigest(candidate),
+    };
+    await writeFile(path.join(candidate, MANAGED_SKILL_FILE), `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
+}
+async function isUnmodifiedManagedSkill(candidate) {
+    try {
+        const currentDigest = await directoryDigest(candidate);
+        if (LEGACY_MANAGED_DIGESTS.has(currentDigest))
+            return true;
+        const manifest = await managedManifest(candidate);
+        return manifest?.contentDigest === currentDigest;
+    }
+    catch {
+        return false;
+    }
+}
+async function replaceWithPackagedSkill(candidate) {
+    await mkdir(path.dirname(candidate), { recursive: true });
+    const temporary = `${candidate}.tmp-${process.pid}`;
+    await rm(temporary, { recursive: true, force: true });
+    await cp(sourceSkill, temporary, { recursive: true });
+    await writeManagedManifest(temporary);
+    await rm(candidate, { recursive: true, force: true });
+    await rename(temporary, candidate);
+}
 async function commandExists(command, env) {
     if (!env.PATH)
         return false;
@@ -158,21 +209,47 @@ export async function installSkill(requested = "auto", options = {}) {
             return { ...item, status: "updated" };
         if (await matchesPackagedSkill(item.path))
             return { ...item, status: "unchanged" };
+        if (await isUnmodifiedManagedSkill(item.path))
+            return { ...item, status: "updated" };
         throw new Error(`${item.path} already exists and differs; pass --force to replace it`);
     }));
     for (const item of planned) {
         if (item.status === "unchanged")
-            continue;
-        await mkdir(path.dirname(item.path), { recursive: true });
-        const temporary = `${item.path}.tmp-${process.pid}`;
-        await rm(temporary, { recursive: true, force: true });
-        await cp(sourceSkill, temporary, { recursive: true });
-        if (options.force)
-            await rm(item.path, { recursive: true, force: true });
-        await rename(temporary, item.path);
+            await writeManagedManifest(item.path);
+        else
+            await replaceWithPackagedSkill(item.path);
     }
     return planned;
 }
+/** Refresh untouched skill copies installed by bxc, preserving local edits. */
+export async function syncManagedSkills(env = process.env) {
+    const detections = await detectHarnesses(env);
+    const destinations = new Map();
+    for (const target of detections.filter((item) => item.installed)) {
+        const current = destinations.get(target.path);
+        if (current)
+            current.agents.push(target.label);
+        else
+            destinations.set(target.path, { agents: [target.label], path: target.path });
+    }
+    const sourceDigest = await directoryDigest(sourceSkill);
+    const results = [];
+    for (const item of destinations.values()) {
+        const currentDigest = await directoryDigest(item.path);
+        if (currentDigest === sourceDigest) {
+            await writeManagedManifest(item.path);
+            results.push({ ...item, status: "unchanged" });
+        }
+        else if (await isUnmodifiedManagedSkill(item.path)) {
+            await replaceWithPackagedSkill(item.path);
+            results.push({ ...item, status: "updated" });
+        }
+        else {
+            results.push({ ...item, status: "modified" });
+        }
+    }
+    return results;
+}
 export async function removeSkill(requested = "auto", options = {}) {
     const env = options.env ?? process.env;
     const detections = await detectHarnesses(env);
@@ -196,7 +273,9 @@ export async function removeSkill(requested = "auto", options = {}) {
     const removals = await Promise.all([...destinations.values()].map(async (item) => {
         if (!await exists(item.path))
             return { ...item, status: "missing" };
-        if (!options.force && !await matchesPackagedSkill(item.path)) {
+        if (!options.force &&
+            !await matchesPackagedSkill(item.path) &&
+            !await isUnmodifiedManagedSkill(item.path)) {
             throw new Error(`${item.path} differs from the packaged skill; pass --force to remove it`);
         }
         return { ...item, status: "removed" };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boxcompute/cli",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Connect local AI agents to BoxCompute sandboxes",
   "keywords": [
     "boxcompute",
@@ -35,6 +35,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "lint": "oxlint --max-warnings 0 src test",
+    "postinstall": "node --eval \"const fs = require('node:fs'); if (fs.existsSync('dist/postinstall.js')) import('./dist/postinstall.js')\"",
     "prepack": "bun run build",
     "test": "bun test",
     "typecheck": "tsc --noEmit -p tsconfig.json"

package/skills/boxcompute-sandbox/SKILL.md

@@ -9,20 +9,18 @@ Use `bxc` as the only interface. Authentication belongs to the human: if
 `bxc doctor` says the client is not authenticated, ask the user to run
 `bxc auth`; never request, read, print, or transmit their saved credential.
 
-## Choose the workspace
+## Choose or create a sandbox
 
-Run `bxc --json sandboxes` and select the workspace whose name matches the
-task. Do not assume the first result is correct. If no workspace fits, tell the
-user to create one in BoxCompute; the CLI deliberately does not create account
-workspaces.
-
-Start or resume it with:
+Run `bxc --json workspaces` to choose the parent workspace, including when it
+does not have a sandbox yet. Run `bxc --json sandboxes` to inspect existing
+instances and do not assume the first result is correct. To allocate another
+isolated instance under a workspace, start one with:
 
 ```sh
 bxc --json sandbox start WORKSPACE_ID
 ```
 
-The stable workspace ID is also the sandbox ID used by later commands.
+The returned sandbox `id` is the stable instance ID used by later commands.
 
 ## Execute work