@optima-chat/browser-cli 0.24.0 → 0.25.1

package/dist/index.js

@@ -160,10 +160,11 @@ function clearSessionId(onlyIfEquals) {
 
 // src/api.ts
 var BrowserAPIError = class extends Error {
-  constructor(statusCode, errorCode, message) {
+  constructor(statusCode, errorCode, message, details) {
     super(message);
     this.statusCode = statusCode;
     this.errorCode = errorCode;
+    this.details = details;
     this.name = "BrowserAPIError";
   }
 };
@@ -173,7 +174,7 @@ function toAPIError(status, statusText, body) {
     return new BrowserAPIError(status, "http_error", `HTTP ${status}: ${detail}`);
   }
   if (detail?.message) {
-    return new BrowserAPIError(status, detail.error ?? "unknown", detail.message);
+    return new BrowserAPIError(status, detail.error ?? "unknown", detail.message, detail);
   }
   return new BrowserAPIError(status, "unknown", `HTTP ${status}: ${statusText}`);
 }
@@ -199,7 +200,7 @@ function conversationHeader() {
   const conv = conversationId();
   return conv ? { "X-Optima-Conversation": conv } : {};
 }
-async function request(path, options = {}) {
+async function request(path, options = {}, originalTaskConversation) {
   const url = `${BROWSER_API_URL}${path}`;
   const auth = authHeader();
   let response;
@@ -209,7 +210,7 @@ async function request(path, options = {}) {
       headers: {
         "Content-Type": "application/json",
         ...auth,
-        ...conversationHeader(),
+        ...originalTaskConversation === void 0 ? conversationHeader() : originalTaskConversation === null ? {} : { "X-Optima-Conversation": originalTaskConversation },
         ...options.headers
       }
     });
@@ -322,6 +323,12 @@ var BrowserAPI = class {
       throw err;
     }
   }
+  async handoff(sessionId, timeoutSeconds) {
+    return request(`/api/sessions/${sessionId}/handoff`, { method: "POST", body: JSON.stringify({ timeout_seconds: timeoutSeconds }) });
+  }
+  async resumeHandoff(sessionId) {
+    return request(`/api/sessions/${sessionId}/handoff`, { method: "DELETE" });
+  }
   async getStatus(sessionId) {
     return request(`/api/sessions/${sessionId}/status`);
   }
@@ -443,8 +450,32 @@ var BrowserAPI = class {
       body: JSON.stringify(payload)
     });
   }
+  async settleScriptTaskSession(taskId) {
+    const task = await this.getScriptTask(taskId);
+    const proof = task.execution_evidence;
+    if (task.id !== taskId || !["failed", "cancelled", "needs_fallback", "completed"].includes(task.status) || !proof || proof.protocol !== "script-execution/v1" || proof.task_id !== taskId || proof.worker_ended !== true || !(proof.conversation === null || typeof proof.conversation === "string")) {
+      throw new Error("Original task execution/conversation unresolved; refusing session settlement");
+    }
+    return request(
+      `/api/script-tasks/${encodeURIComponent(taskId)}/settle-session`,
+      { method: "POST" },
+      proof.conversation
+    );
+  }
   async getScriptTask(taskId) {
-    return request(`/api/script-tasks/${taskId}`);
+    return request(`/api/script-tasks/${encodeURIComponent(taskId)}`);
+  }
+  async sourceCapabilities() {
+    return request(`/api/script-source-capabilities`);
+  }
+  async observeSource(taskId) {
+    return request(`/api/script-tasks/${encodeURIComponent(taskId)}/source`);
+  }
+  async releaseSource(taskId) {
+    return request(`/api/script-tasks/${encodeURIComponent(taskId)}/source`, { method: "DELETE" });
+  }
+  async sourceScreenshot(taskId, observationId) {
+    return requestBinary(`/api/script-tasks/${encodeURIComponent(taskId)}/source/observations/${encodeURIComponent(observationId)}/screenshot`);
   }
   async sendFile(src, dest) {
     return request("/api/files/send", {
@@ -491,6 +522,12 @@ function formatStatus(status) {
   lines.push(`Status: ${status.status}`);
   lines.push(`Created: ${status.created_at}`);
   lines.push(`Idle: ${status.idle_seconds}s`);
+  if (status.handoff) {
+    lines.push(`Handoff: ${status.handoff.state}`);
+    lines.push(`Expires: ${status.handoff.expires_at}`);
+    lines.push(`Remaining: ${status.handoff.remaining_seconds}s`);
+    lines.push(`Recovery: ${status.handoff.recovery}`);
+  }
   if (status.execution) {
     const where = status.execution === "sidecar" ? "user's machine" : "server-driven";
     lines.push(`Execution: ${status.execution} (${where})`);
@@ -572,6 +609,33 @@ function registerLifecycleCommands(program2) {
       process.exit(1);
     }
   });
+  program2.command("handoff").description("Reserve the current session/tab for human review (bounded, no submission)").option("--timeout-seconds <seconds>", "Retention from now, 60\u20133600 seconds; retries keep the original deadline", "1800").action(async (opts) => {
+    try {
+      const seconds = Number(opts.timeoutSeconds);
+      if (!Number.isInteger(seconds) || seconds < 60 || seconds > 3600) {
+        throw new Error("timeout-seconds must be an integer between 60 and 3600");
+      }
+      const result = await api.handoff(loadSessionId(), seconds);
+      console.log(`Session: ${result.session_id}
+Handoff: ${result.handoff.state}
+Expires: ${result.handoff.expires_at}
+Remaining: ${result.handoff.remaining_seconds}s
+Recovery: ${result.handoff.recovery}`);
+    } catch (err) {
+      console.error(formatError(err));
+      process.exit(1);
+    }
+  });
+  program2.command("handoff-resume").description("Release human retention without navigating, submitting, or closing the tab").action(async () => {
+    try {
+      const result = await api.resumeHandoff(loadSessionId());
+      console.log(`Session: ${result.session_id}
+Handoff released. Inspect the current page and verify submission before restoring or retrying.`);
+    } catch (err) {
+      console.error(formatError(err));
+      process.exit(1);
+    }
+  });
   program2.command("status").description("Show session status").action(async () => {
     try {
       const sessionId = loadSessionId();
@@ -995,7 +1059,12 @@ function formatScriptTask(task) {
       lines.push("");
     }
     const sid = task.session_id;
-    lines.push(
+    const source = output.source_handoff;
+    if (source) {
+      lines.push(JSON.stringify(source));
+      lines.push(`Submission remains unknown. Read only: browser-cli observe-source ${task.id}`);
+      lines.push(`Release without closing a page: browser-cli release-source ${task.id}`);
+    } else lines.push(
       sid ? `Session ${sid} may still be open \u2014 continue with browser-cli --session ${sid} dom/click/input, or free it with browser-cli --session ${sid} close` : "Session id not reported \u2014 if one remains, close it by id: browser-cli --session <id> close"
     );
   } else if (task.status === "failed") {
@@ -1035,6 +1104,50 @@ function resolveSubmitSource(opts) {
   throw new Error("\u5FC5\u987B\u7ED9 --code-file \u6216 --code-dir");
 }
 function registerScriptCommands(program2) {
+  program2.command("observe-source <task-id>").description("Read the exact original task page without navigation or replay; does not renew retention").option("--out <directory>", "Save text/JSON evidence before attempting screenshot download").action(async (taskId, opts) => {
+    try {
+      const capability = await api.sourceCapabilities();
+      if (capability.protocol !== "source-observation/v1" || !capability.task_bound_observation) {
+        throw new Error("source_observation_unsupported: backend capability unavailable; do not launch a replacement page");
+      }
+      const result = await api.observeSource(taskId);
+      if (opts.out) {
+        const directory = resolve(opts.out);
+        mkdirSync2(directory, { recursive: true });
+        const evidence = join3(directory, `${result.observation.id}.json`);
+        writeFileSync3(evidence, JSON.stringify(result, null, 2));
+        if (result.observation.screenshot_path) {
+          try {
+            writeFileSync3(
+              join3(directory, `${result.observation.id}.png`),
+              await api.sourceScreenshot(taskId, result.observation.id)
+            );
+          } catch (err) {
+            result.observation.screenshot_error = String(err);
+            writeFileSync3(evidence, JSON.stringify(result, null, 2));
+          }
+        }
+      }
+      console.log(JSON.stringify(result, null, 2));
+    } catch (err) {
+      const details = err && typeof err === "object" && "details" in err ? err.details : void 0;
+      if (opts.out && details) {
+        const directory = resolve(opts.out);
+        mkdirSync2(directory, { recursive: true });
+        writeFileSync3(join3(directory, "source-refused.json"), JSON.stringify(details, null, 2));
+      }
+      console.error(formatError(err));
+      process.exitCode = 1;
+    }
+  });
+  program2.command("release-source <task-id>").description("Release a task's bounded source lease; never closes or navigates a page").action(async (taskId) => {
+    try {
+      console.log(JSON.stringify(await api.releaseSource(taskId), null, 2));
+    } catch (err) {
+      console.error(formatError(err));
+      process.exitCode = 1;
+    }
+  });
   program2.command("submit-script").description("Submit a script (write to EFS)").requiredOption("--name <name>", "Script name").option("--code-file <path>", "Path to Python script file (\u7B49\u4EF7\u4E8E\u300C\u53EA\u6709 script.py\u300D)").option("--code-dir <dir>", "Path to a skill directory (script.py + _*.py \u4E00\u8D77\u9001)").action(async (opts) => {
     try {
       const files = resolveSubmitSource(opts);
@@ -1126,7 +1239,7 @@ ${downloadHint(result)}`);
       process.exit(1);
     }
   });
-  program2.command("script-task").argument("<task-id>", "Task ID").description("Check script task status").option("--download [path]", "Save the task's exported file (default: ./<filename>)").option("--json", "Print the raw task (status / error / full output) as JSON").option(
+  program2.command("script-task").argument("<task-id>", "Task ID").description("Check script task status").option("--settle-session", "Read the original task, then settle its ended channel under its server-recorded conversation; keeps the current session and never classifies publication").option("--download [path]", "Save the task's exported file (default: ./<filename>)").option("--json", "Print the raw task (status / error / full output) as JSON").option(
     "--wait",
     `Block until the task finishes (completed / failed / needs_fallback), at most --timeout seconds. Exit code: 0 completed, 2 failed / needs_fallback, 3 still running (call again), 4 waiting for the store owner (e.g. captcha; tell them, then --wait --through-human), 1 error`
   ).option("--through-human", "With --wait: keep waiting while the script waits for the store owner (exit 4 otherwise)").option("--timeout <seconds>", `With --wait: max seconds to wait (default ${WAIT_DEFAULT_TIMEOUT_S}, max ${WAIT_MAX_TIMEOUT_S})`).action(async (taskId, opts) => {
@@ -1136,6 +1249,7 @@ ${downloadHint(result)}`);
       }
       if (opts.timeout !== void 0 && !opts.wait) throw new Error("--timeout \u53EA\u80FD\u548C --wait \u4E00\u8D77\u7528");
       if (opts.throughHuman && !opts.wait) throw new Error("--through-human \u53EA\u80FD\u548C --wait \u4E00\u8D77\u7528");
+      if (opts.settleSession && (opts.wait || opts.download !== void 0)) throw new Error("--settle-session cannot combine with --wait/--download");
       const timeoutS = opts.timeout === void 0 ? WAIT_DEFAULT_TIMEOUT_S : parseWaitTimeout(opts.timeout);
       let task;
       if (opts.wait) {
@@ -1154,12 +1268,12 @@ ${downloadHint(result)}`);
           return;
         }
       } else {
-        task = await api.getScriptTask(taskId);
+        task = opts.settleSession ? await api.settleScriptTaskSession(taskId) : await api.getScriptTask(taskId);
       }
       const stoppedExit = () => {
         if (opts.wait && task.status !== "completed") process.exit(EXIT_TASK_STOPPED);
       };
-      if (task.status === "needs_fallback" && task.session_id) saveSessionId(task.session_id);
+      if (!opts.settleSession && task.status === "needs_fallback" && task.session_id) saveSessionId(task.session_id);
       if (opts.json) {
         console.log(JSON.stringify(task, null, 2));
         stoppedExit();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optima-chat/browser-cli",
-  "version": "0.24.0",
+  "version": "0.25.1",
   "type": "module",
   "main": "./dist/index.js",
   "bin": {