@optima-chat/browser-cli 0.23.0 → 0.25.0

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}`);
 }
@@ -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`);
   }
@@ -446,6 +453,18 @@ var BrowserAPI = class {
   async getScriptTask(taskId) {
     return request(`/api/script-tasks/${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", {
       method: "POST",
@@ -491,6 +510,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 +597,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();
@@ -833,8 +885,18 @@ function parseWaitTimeout(raw) {
   return n;
 }
 function stillRunningMessage(task, waitedS, nowMs = Date.now()) {
-  const started = task.created_at ? Date.parse(task.created_at) : Number.NaN;
-  const elapsed = Number.isFinite(started) ? `running for ${Math.max(0, Math.round((nowMs - started) / 1e3))}s` : `waited ${waitedS}s`;
+  const secondsSince = (iso) => {
+    const t = iso ? Date.parse(iso) : Number.NaN;
+    return Number.isFinite(t) ? Math.max(0, Math.round((nowMs - t) / 1e3)) : null;
+  };
+  const created = secondsSince(task.created_at);
+  let elapsed;
+  if (task.queue?.queued) {
+    elapsed = `queued, ${task.queue.ahead} task(s) of this user ahead` + (created !== null ? `, created ${created}s ago` : "");
+  } else {
+    const ran = secondsSince(task.queue?.started_at) ?? created;
+    elapsed = ran !== null ? `running for ${ran}s` : `waited ${waitedS}s`;
+  }
   const step = task.total_steps ? `, step ${task.current_step}/${task.total_steps}` : "";
   const waiting = waitingHumanLine(task);
   return `Still running (${elapsed}${step}). Call again as a separate command: browser-cli script-task ${task.id} --wait` + (waiting ? ` --through-human
@@ -985,7 +1047,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") {
@@ -1025,6 +1092,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);

package/package.json

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