@tcb-sandbox/cli 0.3.9 → 0.4.1

package/README.md

@@ -32,8 +32,8 @@ tcb-sandbox --session-id my-session read --path hello.txt
 ## 环境变量
 
 ```bash
-export TRW_ENDPOINT=https://your-gateway.com
-export TRW_SESSION_ID=your-session-id
+export TCB_SANDBOX_ENDPOINT=https://your-gateway.com
+export TCB_SANDBOX_SESSION_ID=your-session-id
 
 # 然后可直接使用
 tcb-sandbox health
@@ -60,6 +60,12 @@ tcb-sandbox bash --command "ls -la"
 | `pty` | PTY 终端 |
 | `snapshot` | 快照管理 |
 
+## 测试说明
+
+- `pnpm test`：CLI 契约回归（mock HTTP）
+- 不包含：`serve` 真实内嵌 TRW 行为验证
+- 跨门面（HTTP/MCP/CLI/E2B）完整矩阵请使用 sibling `../trw-example` 的 `pnpm start` 或 `pnpm test:full`
+
 ## 本地模式详情
 
 ```bash

package/dist/bundled-docs.js

@@ -486,46 +486,15 @@ export const BUNDLED_API_DOCS = {
             notes: ["Bundled fallback docs snapshot."],
         },
         {
-            name: "workspace_snapshot",
-            description: "Create async workspace snapshot uploaded to S3. Returns snapshot_id immediately.",
-            endpoint: "POST /api/tools/workspace_snapshot",
+            name: "workspace_persist",
+            description: "Immediately persist workspace to COS via rsync. Returns elapsed time in ms.",
+            endpoint: "POST /api/tools/workspace_persist",
             input_schema: {
                 type: "object",
-                properties: {
-                    exclude: { type: "array", items: { type: "string" } },
-                    include_all: { type: "boolean" },
-                },
-            },
-            limits: { max_concurrent: 2 },
-            notes: ["Bundled fallback docs snapshot."],
-        },
-        {
-            name: "workspace_snapshot_status",
-            description: "Check snapshot task status by snapshot_id or list all session tasks.",
-            endpoint: "POST /api/tools/workspace_snapshot_status",
-            input_schema: {
-                type: "object",
-                properties: {
-                    snapshot_id: { type: "string" },
-                },
+                properties: {},
             },
             limits: {},
-            notes: ["Bundled fallback docs snapshot."],
-        },
-        {
-            name: "workspace_restore",
-            description: 'Restore workspace from snapshot. mode="merge" overlays, mode="replace" cleans first.',
-            endpoint: "POST /api/tools/workspace_restore",
-            input_schema: {
-                type: "object",
-                required: ["snapshot_id"],
-                properties: {
-                    snapshot_id: { type: "string" },
-                    mode: { type: "string", enum: ["merge", "replace"] },
-                },
-            },
-            limits: {},
-            notes: ["Bundled fallback docs snapshot."],
+            notes: ["Bundled fallback docs."],
         },
     ],
 };

package/dist/cli.js

@@ -5,9 +5,8 @@ import process from "node:process";
 import { TcbSandboxClient } from "@tcb-sandbox/sdk-js";
 import { Command } from "commander";
 import { BUNDLED_API_DOCS } from "./bundled-docs.js";
-import { defaultWorkspaceRoot, runServe } from "./serve.js";
+import { defaultMultiSessionWorkspaceRoot, defaultWorkspaceRoot, runServe } from "./serve.js";
 const DEFAULT_TIMEOUT = 600_000;
-const DEFAULT_ACCEPT_HEADER = "application/problem+json, application/json;q=0.9, text/markdown;q=0.8, */*;q=0.1";
 const LOG_PRIORITIES = {
     debug: 10,
     info: 20,
@@ -92,17 +91,6 @@ function resolveLogFormat(opts) {
 function shouldLog(ctx, level) {
     return LOG_PRIORITIES[level] >= LOG_PRIORITIES[ctx.logLevel];
 }
-function maskHeaderValue(key, value) {
-    const lower = key.toLowerCase();
-    if (lower.includes("authorization") ||
-        lower.includes("api-key") ||
-        lower.includes("token") ||
-        lower.includes("cookie") ||
-        lower.includes("session")) {
-        return "***";
-    }
-    return value;
-}
 const SENSITIVE_JSON_KEY_RE = /(authorization|api[_-]?key|token|secret|password|cookie|session|value)/i;
 function redactJsonForDebug(input) {
     if (Array.isArray(input)) {
@@ -262,7 +250,7 @@ Quick Start
   tcb-sandbox serve    # alias: local — embedded TRW on loopback
   tcb-sandbox --endpoint http://127.0.0.1:9000 health
   tcb-sandbox --endpoint http://127.0.0.1:9000 docs
-  tcb-sandbox --endpoint http://127.0.0.1:9000 --session-id demo tools call read --param path=README.md
+  tcb-sandbox --endpoint http://127.0.0.1:9000 --session-id demo read README.md
 
 Error Handling
   HTTP failures are parsed as RFC 9457 problem details when available.
@@ -271,17 +259,23 @@ Error Handling
     program
         .command("serve")
         .alias("local")
-        .description("Run embedded tcb-remote-workspace locally (multi-session; X-Cloudbase-Session-Id; no auth).")
+        .description("Run embedded tcb-remote-workspace locally. Default: single-workspace (no session header needed). Use --multi-session for session-based subdirectories.")
         .option("--port <n>", "Listen port", "9000")
         .option("--host <addr>", "Bind address (use 0.0.0.0 for all interfaces)", "127.0.0.1")
-        .option("--workspace-root <path>", "Parent directory; each session is a subdirectory by session id", defaultWorkspaceRoot())
+        .option("--workspace-root <path>", "Workspace directory (single mode) or parent directory for session subdirectories (multi-session mode)")
+        .option("--multi-session", "Enable multi-session mode: each X-Cloudbase-Session-Id creates a subdirectory under workspace-root", false)
         .action(async function (opts) {
         const port = asInt(opts.port);
-        const workspaceRoot = path.resolve(opts.workspaceRoot);
+        const resolvedRoot = opts.workspaceRoot
+            ? path.resolve(opts.workspaceRoot)
+            : opts.multiSession
+                ? defaultMultiSessionWorkspaceRoot()
+                : defaultWorkspaceRoot();
         const code = await runServe({
             host: opts.host,
             port,
-            workspaceRoot,
+            workspaceRoot: resolvedRoot,
+            multiSession: opts.multiSession,
         });
         process.exit(code === null ? 0 : code);
     });
@@ -310,7 +304,7 @@ Error Handling
             const response = await client.system.apiDocs();
             docs = ("data" in response ? response.data : response);
         }
-        catch (err) {
+        catch (_err) {
             logMessage(ctx, "warn", "GET /api/docs unavailable, using bundled fallback docs");
             docs = BUNDLED_API_DOCS;
         }
@@ -731,61 +725,27 @@ Error Handling
             return printJson(result);
         printPretty("Capability Invoke", result);
     });
-    const snapshot = program
-        .command("snapshot")
-        .description("Workspace snapshot and restore (S3-backed)");
-    snapshot
-        .command("create")
-        .description("Create async workspace snapshot and upload to S3")
-        .option("--exclude <patterns...>", "Additional exclude patterns")
-        .option("--include-all", "Skip default excludes (only sensitive files still excluded)")
-        .action(async function (options) {
-        const ctx = buildContext(this);
-        ensureSessionId(ctx);
-        const client = createSdkClientFromContext(ctx);
-        logMessage(ctx, "info", "POST /api/tools/workspace_snapshot");
-        const response = await client.other.workspaceSnapshot({
-            exclude: options.exclude,
-            include_all: options.includeAll,
-        });
-        const result = "data" in response ? response.data : response;
-        if (ctx.output === "json")
-            return printJson(result);
-        printPretty("Snapshot Create", result);
-    });
-    snapshot
-        .command("status [snapshotId]")
-        .description("Check snapshot status (single or all session tasks)")
-        .action(async function (snapshotId) {
-        const ctx = buildContext(this);
-        ensureSessionId(ctx);
-        const client = createSdkClientFromContext(ctx);
-        logMessage(ctx, "info", "POST /api/tools/workspace_snapshot_status");
-        const response = await client.other.workspaceSnapshotStatus({
-            snapshot_id: snapshotId,
-        });
-        const result = "data" in response ? response.data : response;
-        if (ctx.output === "json")
-            return printJson(result);
-        printPretty("Snapshot Status", result);
-    });
-    snapshot
-        .command("restore <snapshotId>")
-        .description("Restore workspace from snapshot (supports cross-session)")
-        .option("--mode <mode>", 'Restore mode: "merge" (default) or "replace"', "merge")
-        .action(async function (snapshotId, options) {
+    program
+        .command("persist")
+        .description("Persist workspace to COS storage immediately (rsync)")
+        .action(async function () {
         const ctx = buildContext(this);
         ensureSessionId(ctx);
-        const client = createSdkClientFromContext(ctx);
-        logMessage(ctx, "info", "POST /api/tools/workspace_restore");
-        const response = await client.other.workspaceRestore({
-            snapshot_id: snapshotId,
-            mode: options.mode,
+        logMessage(ctx, "info", "POST /api/tools/workspace_persist");
+        const url = `${ctx.endpoint}/api/tools/workspace_persist`;
+        const response = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                ...ctx.headers,
+            },
+            body: JSON.stringify({}),
+            signal: AbortSignal.timeout(ctx.timeout),
         });
-        const result = "data" in response ? response.data : response;
+        const result = await response.json();
         if (ctx.output === "json")
             return printJson(result);
-        printPretty("Snapshot Restore", result);
+        printPretty("Persist", result);
     });
     const secrets = program.command("secrets").description("Secrets helpers (session-scoped)");
     secrets

package/dist/serve.js

@@ -123,6 +123,9 @@ function pythonVersion() {
     return m ? m[1] : line.replace(/^Python\s+/i, "") || "?";
 }
 export function defaultWorkspaceRoot() {
+    return path.join(os.homedir(), ".tcb-sandbox", "workspace");
+}
+export function defaultMultiSessionWorkspaceRoot() {
     return path.join(os.homedir(), ".tcb-sandbox", "workspaces");
 }
 const MOTD_ASCII = "\n    ____ _                 _ ____\n   / ___| | ___  _   _  __| | __ )  __ _ ___  ___\n  | |   | |/ _ \\| | | |/ _` |  _ \\ / _` / __|/ _ \\\n  | |___| | (_) | |_| | (_| | |_) | (_| \\__ \\  __/\n   \\____|_|\\___/ \\__,_|\\__,_|____/ \\__,_|___/\\___|\n     Remote Workspace\n";
@@ -139,8 +142,14 @@ export function printServeBanner(opts, trwMain, sandboxStatus) {
     lines.push(MOTD_ASCII.replace(/^\n/, "").replace(/\n$/, ""));
     lines.push("");
     lines.push(`  ${S.dim("Listen   :")} ${base}`);
-    lines.push(`  ${S.dim("Session  :")} ${S.bold("X-Cloudbase-Session-Id")} ${S.dim("（不传时默认 default；示例 test-03271546 → 子目录 test-03271546）")}`);
-    lines.push(`  ${S.dim("Workspace:")} ${wsRoot}${path.sep}${S.dim("<session-id>")}`);
+    if (opts.multiSession) {
+        lines.push(`  ${S.dim("Session  :")} ${S.bold("X-Cloudbase-Session-Id")} ${S.dim("（multi-session mode; each session → subdirectory）")}`);
+        lines.push(`  ${S.dim("Workspace:")} ${wsRoot}${path.sep}${S.dim("<session-id>")}`);
+    }
+    else {
+        lines.push(`  ${S.dim("Session  :")} ${S.dim("（single-workspace mode; no session header needed）")}`);
+        lines.push(`  ${S.dim("Workspace:")} ${wsRoot}`);
+    }
     lines.push(`  ${S.dim("Disk     :")} ${disk}`);
     if (sandboxStatus) {
         const sandboxColor = sandboxStatus.startsWith("active") ? S.green : S.yellow;
@@ -193,7 +202,7 @@ async function isPortInUse(host, port) {
 const SHUTDOWN_TIMEOUT_MS = 10_000;
 const MAX_RESTART_COUNT = 3;
 const MIN_UPTIME_FOR_HEALTHY_MS = 5_000;
-function ensureMcporterConfig(workspaceRoot) {
+function ensureMcporterConfig(_workspaceRoot) {
     const mcporterDir = path.join(os.homedir(), ".mcporter");
     const configPath = path.join(mcporterDir, "mcporter.json");
     if (fs.existsSync(configPath))
@@ -239,6 +248,8 @@ export async function runServe(opts) {
         HOST: opts.host,
         PORT: String(opts.port),
         WORKSPACE_ROOT: opts.workspaceRoot,
+        WORKSPACE_MODE: opts.multiSession ? "multi" : "single",
+        LOCAL_MODE: "true",
     };
     let shutdownRequested = false;
     let restartCount = 0;