@boxcompute/cli 0.2.1 → 0.2.3

package/README.md

@@ -48,6 +48,7 @@ bxc workspaces
 bxc sandboxes
 bxc sandbox start WORKSPACE_ID
 # Use the returned sandbox instance ID for later commands.
+bxc sandbox logs SANDBOX_ID --source execute
 bxc sandbox exec SANDBOX_ID -- python -m pytest
 ```
 
@@ -61,9 +62,11 @@ Deploy the server release with both Sandbox API v1 and v2 before publishing CLI
 contract. After that, clients need only upgrade the package:
 
 ```sh
-npm install --global @boxcompute/cli@latest
+bxc update
 ```
 
-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.
+`bxc up` is the short alias. If the automatic update cannot invoke npm, use
+`npm install --global @boxcompute/cli@latest` manually. Updating preserves the
+saved BoxCompute credential and 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

@@ -13,6 +13,7 @@ export type CliDependencies = {
     now?: () => number;
     sleep?: (milliseconds: number) => Promise<void>;
     openBrowser?: (url: string) => void;
+    installUpdate?: (version: string) => Promise<void>;
     loadConnection?: (env: NodeJS.ProcessEnv) => Promise<Connection>;
     loadSavedUrl?: (env: NodeJS.ProcessEnv) => Promise<string | null>;
     saveConnection?: (url: string, token: string, env: NodeJS.ProcessEnv) => Promise<void>;

package/dist/cli.js

@@ -15,6 +15,7 @@ Usage: bxc [options] [command]
 Commands:
 
   version                         Print the version number and exit
+  update                          [alias: up] Update the CLI to the latest npm release
   login                           Log in through BoxCompute in your browser
   logout                          Revoke and remove the saved CLI credential
   auth                            [alias: login] Authentication commands
@@ -25,6 +26,7 @@ Commands:
   sandbox                         Manage isolated BoxCompute sandboxes
     start                         Create and start a workspace sandbox
     status                        Inspect one sandbox
+    logs                          Read current or retained sandbox logs
     exec                          Execute a program inside a sandbox
     delete                        [alias: rm] Destroy the runtime; the workspace remains
   skill                           [alias: skills] Manage coding-harness skills
@@ -48,10 +50,12 @@ Login options:
 Examples:
 
   $ bxc login
+  $ bxc update
   $ bxc skill detect
   $ bxc skill install
   $ bxc workspaces
   $ bxc sandbox start WORKSPACE_ID
+  $ bxc sandbox logs SANDBOX_ID --source execute
   $ bxc sandbox exec SANDBOX_ID -- python -m pytest
 
 Compatibility:
@@ -66,6 +70,7 @@ Commands:
 
   start WORKSPACE_ID              Create and start a new sandbox instance
   status SANDBOX_ID               Inspect one sandbox
+  logs SANDBOX_ID [options]       Read logs without starting the runtime
   exec SANDBOX_ID [options] -- PROGRAM [ARG...]
                                   Execute a program inside a sandbox
   delete SANDBOX_ID --yes         [alias: rm] Destroy the runtime; keep the workspace
@@ -76,6 +81,15 @@ Exec options:
   --env KEY=VALUE                 Set an environment variable; repeatable
   --timeout SECONDS               Command timeout
   --max-output-bytes BYTES        Maximum captured output
+
+Log options:
+
+  --since TIMESTAMP               Include entries at or after an RFC 3339 time
+  --until TIMESTAMP               Include entries before an RFC 3339 time
+  --stream stdout|stderr          Filter by output stream
+  --source workload|execute|process
+                                  Filter by log source
+  --limit ENTRIES                 Maximum entries (default: 1000, max: 5000)
 `;
 const skillHelp = `Manage coding-harness skills
 
@@ -133,6 +147,77 @@ export function openBrowser(url, runtime = {}) {
         // polling so headless shells and restricted WSL interop can authenticate.
     }
 }
+function releaseVersion(value) {
+    if (typeof value !== "string")
+        return null;
+    const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(value);
+    if (!match)
+        return null;
+    const parts = match.slice(1).map(Number);
+    return parts.every(Number.isSafeInteger) ? parts : null;
+}
+function compareReleaseVersions(left, right) {
+    for (let index = 0; index < left.length; index += 1) {
+        if (left[index] !== right[index])
+            return left[index] - right[index];
+    }
+    return 0;
+}
+async function installCliUpdate(version) {
+    const executable = platform() === "win32" ? "npm.cmd" : "npm";
+    await new Promise((resolve, reject) => {
+        let child;
+        try {
+            child = spawn(executable, ["install", "--global", `@boxcompute/cli@${version}`], {
+                stdio: ["ignore", "ignore", "inherit"],
+            });
+        }
+        catch (error) {
+            reject(error);
+            return;
+        }
+        child.once("error", reject);
+        child.once("exit", (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`npm exited with code ${code ?? "unknown"}`));
+        });
+    });
+}
+async function updateCli(dependencies) {
+    let response;
+    try {
+        response = await dependencies.fetch("https://registry.npmjs.org/%40boxcompute%2Fcli/latest", {
+            headers: { accept: "application/json" },
+        });
+    }
+    catch (error) {
+        throw new Error(`Could not check npm for updates: ${error?.message ?? String(error)}`);
+    }
+    if (!response.ok)
+        throw new Error(`Could not check npm for updates (HTTP ${response.status})`);
+    const latest = (await response.json()).version;
+    const currentParts = releaseVersion(CLI_VERSION);
+    const latestParts = releaseVersion(latest);
+    if (!currentParts || !latestParts || typeof latest !== "string") {
+        throw new Error("npm returned an invalid BoxCompute CLI version");
+    }
+    if (compareReleaseVersions(latestParts, currentParts) <= 0) {
+        emit(dependencies.io, dependencies.json, { updated: false, version: CLI_VERSION }, `BoxCompute CLI is already up to date (${CLI_VERSION}).\n`);
+        return 0;
+    }
+    write(dependencies.io.stderr, `Updating BoxCompute CLI from ${CLI_VERSION} to ${latest}…\n`);
+    try {
+        await dependencies.install(latest);
+    }
+    catch (error) {
+        throw new Error(`Could not install @boxcompute/cli@${latest}: ${error?.message ?? String(error)}. ` +
+            `Run \`npm install --global @boxcompute/cli@${latest}\` manually.`);
+    }
+    emit(dependencies.io, dependencies.json, { updated: true, previousVersion: CLI_VERSION, version: latest }, `Updated BoxCompute CLI to ${latest}.\n`);
+    return 0;
+}
 const delay = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
 const write = (stream, value) => { stream.write(value); };
 const emit = (io, json, value, human) => {
@@ -170,6 +255,21 @@ function positive(value, name) {
         throw new UsageError(`${name} must be a positive integer`);
     return parsed;
 }
+function timestamp(value, name) {
+    if (value === undefined)
+        return undefined;
+    const parsed = new Date(value);
+    if (Number.isNaN(parsed.valueOf()))
+        throw new UsageError(`${name} must be an RFC 3339 timestamp`);
+    return parsed.toISOString();
+}
+function oneOf(value, name, values) {
+    if (value === undefined)
+        return undefined;
+    if (!values.includes(value))
+        throw new UsageError(`${name} must be one of: ${values.join(", ")}`);
+    return value;
+}
 function environment(tokens) {
     const values = [];
     for (;;) {
@@ -265,6 +365,21 @@ function executionOutput(io, json, sandboxId, result) {
     }
     return result.exitCode ?? 1;
 }
+function logsOutput(io, json, logs) {
+    if (json) {
+        emit(io, true, { logs }, "");
+        return 0;
+    }
+    if (!logs.entries.length)
+        write(io.stdout, "No logs found.\n");
+    for (const entry of logs.entries) {
+        const process = entry.process_id ? ` ${entry.process_id}` : "";
+        write(io.stdout, `${entry.timestamp}\t${entry.stream}\t${entry.source}${process}\t${entry.message}\n`);
+    }
+    write(io.stderr, `sandbox=${logs.sandbox_id} entries=${logs.entries.length} retentionSeconds=${logs.retention_seconds}` +
+        `${logs.truncated ? " truncated=true" : ""}\n`);
+    return 0;
+}
 export async function runCli(argv, supplied = {}) {
     const env = supplied.env ?? process.env;
     const io = supplied.io ?? { stdout: process.stdout, stderr: process.stderr };
@@ -272,6 +387,7 @@ export async function runCli(argv, supplied = {}) {
     const now = supplied.now ?? Date.now;
     const sleep = supplied.sleep ?? delay;
     const openBrowserImpl = supplied.openBrowser ?? openBrowser;
+    const installUpdate = supplied.installUpdate ?? installCliUpdate;
     const load = supplied.loadConnection ?? loadConnection;
     const savedUrl = supplied.loadSavedUrl ?? loadSavedUrl;
     const save = supplied.saveConnection ?? saveConnection;
@@ -297,6 +413,8 @@ export async function runCli(argv, supplied = {}) {
     let command = args.shift();
     if (command === "login")
         command = "auth";
+    if (command === "up")
+        command = "update";
     if (command === "skills")
         command = "skill";
     if (command === "list" || command === "ls")
@@ -345,6 +463,11 @@ export async function runCli(argv, supplied = {}) {
         }
         return authenticate(args, { env, io, json, fetch: fetchImpl, now, sleep, openBrowser: openBrowserImpl, loadSavedUrl: savedUrl, saveConnection: save });
     }
+    if (command === "update") {
+        if (args.length)
+            throw new UsageError("update takes no options");
+        return updateCli({ fetch: fetchImpl, install: installUpdate, io, json });
+    }
     if (command === "skill") {
         let action = args.shift();
         if (!action) {
@@ -453,6 +576,20 @@ export async function runCli(argv, supplied = {}) {
         emit(io, json, { sandbox }, sandboxLine(sandbox));
         return 0;
     }
+    if (action === "logs") {
+        const since = timestamp(option(args, "since"), "--since");
+        const until = timestamp(option(args, "until"), "--until");
+        const stream = oneOf(option(args, "stream"), "--stream", ["stdout", "stderr"]);
+        const source = oneOf(option(args, "source"), "--source", ["workload", "execute", "process"]);
+        const limit = positive(option(args, "limit"), "--limit");
+        if (limit !== undefined && limit > 5_000)
+            throw new UsageError("--limit must be 5000 or fewer");
+        if (since && until && since >= until)
+            throw new UsageError("--since must be earlier than --until");
+        if (args.length)
+            throw new UsageError(`Unknown sandbox logs option: ${args[0]}`);
+        return logsOutput(io, json, await client.logs(id, { since, until, stream, source, limit }));
+    }
     if (action === "delete") {
         if (!flag(args, "yes") || args.length)
             throw new UsageError("sandbox delete requires SANDBOX_ID --yes");

package/dist/client.d.ts

@@ -5,6 +5,7 @@ export type Sandbox = {
     name: string;
     state: "cold" | "running";
     runtimeId: string | null;
+    retainedRuntimeId: string | null;
     image: string | null;
     createdAt: number;
     lastUsedAt: number | null;
@@ -23,6 +24,20 @@ export type Execution = {
     stderrTruncated: boolean;
     wallTimeSeconds: number;
 };
+export type SandboxLogEntry = {
+    timestamp: string;
+    stream: "stdout" | "stderr";
+    source: "workload" | "execute" | "process";
+    message: string;
+    pod_uid: string;
+    process_id?: string;
+};
+export type SandboxLogs = {
+    sandbox_id: string;
+    entries: SandboxLogEntry[];
+    truncated: boolean;
+    retention_seconds: number;
+};
 export declare class BoxComputeHttpError extends Error {
     readonly status: number;
     readonly code?: string | undefined;
@@ -46,5 +61,12 @@ export declare class BoxComputeClient {
         maxOutputBytes?: number;
         env?: Record<string, string>;
     }): Promise<Execution>;
+    logs(id: string, input?: {
+        since?: string;
+        until?: string;
+        stream?: "stdout" | "stderr";
+        source?: "workload" | "execute" | "process";
+        limit?: number;
+    }): Promise<SandboxLogs>;
     delete(id: string): Promise<void>;
 }

package/dist/client.js

@@ -66,6 +66,21 @@ export class BoxComputeClient {
             body: JSON.stringify(input),
         })).result;
     }
+    async logs(id, input = {}) {
+        const query = new URLSearchParams();
+        if (input.since)
+            query.set("since", input.since);
+        if (input.until)
+            query.set("until", input.until);
+        if (input.stream)
+            query.set("stream", input.stream);
+        if (input.source)
+            query.set("source", input.source);
+        if (input.limit !== undefined)
+            query.set("limit", String(input.limit));
+        const suffix = query.size ? `?${query}` : "";
+        return (await this.request(`/api/v2/sandboxes/${encodeURIComponent(id)}/logs${suffix}`)).logs;
+    }
     async delete(id) {
         await this.request(`/api/v2/sandboxes/${encodeURIComponent(id)}`, { method: "DELETE" });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boxcompute/cli",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Connect local AI agents to BoxCompute sandboxes",
   "keywords": [
     "boxcompute",

package/skills/boxcompute-sandbox/SKILL.md

@@ -44,6 +44,11 @@ sandbox unless the user explicitly places those secrets in scope.
 ## Lifecycle and safety
 
 - Inspect uncertain state with `bxc --json sandbox status SANDBOX_ID`.
+- Read runtime output with `bxc sandbox logs SANDBOX_ID`. Add `--json` for
+  structured entries or narrow results with `--since`, `--until`, `--stream`,
+  `--source`, and `--limit`. Log reads do not start stopped compute, and remain
+  available for the provider's nominal 30-day retention period after deletion;
+  storage pressure may shorten that period, so logs are not an archive.
 - Sandboxes persist across commands; do not destroy one merely because the
   current task is finished.
 - `bxc sandbox delete SANDBOX_ID --yes` destroys the remote runtime and is