@boxcompute/cli 0.2.2 → 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
 ```
 

package/dist/cli.js

@@ -26,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
@@ -54,6 +55,7 @@ Examples:
   $ 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:
@@ -68,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
@@ -78,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
 
@@ -243,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 (;;) {
@@ -338,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 };
@@ -534,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.2",
+  "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