@runalabs/rill-cli 0.1.14 → 0.1.15

package/README.md

@@ -124,7 +124,7 @@ rill record status <recording-id>
 
 Replace the placeholders with start's actual values. This snippet verifies attachment only until you add your flow assertions. Keep the directory for retries and remove it when finished. Playwright documents the [connected-browser disconnect behavior](https://playwright.dev/docs/api/class-browser#browser-close).
 
-Capture follows the first page selected at recording start. Keep the flow in that page: new tabs and popups do not receive complete video and diagnostic coverage. Keep the recorded page open until Rill stops.
+Capture follows the page selected at recording start. Keep the flow in that page: new tabs and popups do not receive complete video and diagnostic coverage. Keep the recorded page open until Rill stops.
 
 ### Recording options
 
@@ -135,12 +135,32 @@ Capture follows the first page selected at recording start. Keep the flow in tha
 | `--title <title>` | Name the run; defaults to a timestamped title. |
 | `--description <text>` | Describe what the run demonstrates. |
 | `--headed` | Show the managed browser; default is headless. |
-| `--cdp-url <url>` | Attach to an existing Chromium browser and record its first open page. Navigate that page with your browser tool. |
+| `--cdp-url <url>` | Attach to an existing Chromium CDP endpoint. Select a tab when several are open. |
+| `--tab-id <id>` | Record the stable target ID returned by `record tabs`; requires `--cdp-url`. |
 | `--width <pixels>` / `--height <pixels>` | Managed viewport; defaults to 1280 × 720. |
 | `--max-duration <seconds>` | Automatically finalize local capture; defaults to 600. Still call `record stop` to upload. |
 
 Rill closes browsers it launches during finalization. Attached browsers remain open.
 
+### Record a tab you already use
+
+Your Chromium browser must already expose a CDP endpoint; Rill cannot attach to an ordinary unexposed tab. Keep the endpoint local or otherwise access-controlled. This does not launch a second browser, switch tabs automatically or provide Safari/Firefox support.
+
+```bash
+rill record tabs --cdp-url http://127.0.0.1:9222
+rill record start --cdp-url http://127.0.0.1:9222 --tab-id <tab-id> --title "Checkout review"
+# Continue your flow in that exact tab, then finalize/upload:
+rill record stop <recording-id>
+```
+
+Discovery requires no Rill sign-in and returns `tabId`, title and a sanitized URL. Query values, credentials and fragments are removed; embedded data/file URLs are omitted. Tab titles can still contain private content. Start returns the selected `tabId` at the top level and in `browserAttachment`. If only one page is open, `--tab-id` is optional. Several pages without a selection, or a closed/missing ID, fail instead of recording a different page. A tab ID remains tied to that tab across navigation; relist after closing it.
+
+Keep automation on the selected target. For Playwright, inspect each page with `context.newCDPSession(page)`, call `Target.getTargetInfo`, match `targetInfo.targetId` to the returned `tabId`, and detach that inspection session. Do not assume `context.pages()[0]` is the recorded tab. `--url` deliberately navigates the selected tab when supplied; omit it to record the page as it is. Capture stays on this tab; popups and other tabs are not fully covered.
+
+An older running recorder service cannot honor tab selection. Start detects this and fails before sending capture instructions. Finish active recordings first; the service exits after five idle minutes when it has no retained recoverable captures. For an immediate manual restart, inspect the local `/health` response over the configured Rill socket, verify its recorder PID, and terminate only that idle recorder process. Restarting it interrupts active captures; this release does not restart it automatically.
+
+The CDP connection and disconnect behavior follow the [Playwright browser API](https://playwright.dev/docs/api/class-browser#browser-close).
+
 ## Set up a coding agent
 
 Install and authenticate the CLI where the agent runs. No separate skill installation is required. Optionally save the following workflow in your agent's project instructions or skill setup; it is also available in the [public agent instructions](https://userill.dev/docs/cli#agents):
@@ -187,6 +207,7 @@ Use `rill --help` or `<command> --help` for supported flags.
 | `rill connect --email <email> [--no-wait]` | Start or resume account approval. |
 | `rill connect status <authorization-id>` | Poll a saved approval once; obey `retryAfterSeconds`. |
 | `rill doctor` | Check prerequisites, API compatibility, and authentication. |
+| `rill record tabs --cdp-url <url>` | List existing Chromium tabs without starting a recording. |
 | `rill record start [options]` | Start a managed or attached browser recording. |
 | `rill record stop <recording-id>` | Finalize and upload; supports `--no-wait` and `--no-feedback`. |
 | `rill record status <recording-id>` | Read remote state first, then local capture for unsubmitted recordings; local completion is `captured`. |
@@ -343,3 +364,9 @@ Run `rill whoami` (or `rill --pretty whoami`) to verify your current identity. J
 `record start` and active local `record status` return `startedAt`, `stopsAt`, `maxDurationSeconds`, `elapsedSeconds`, and `remainingSeconds`. Use the remaining time to budget retries. After automatic capture stop, status reports `captured` with the stop/upload command; zero remaining time does not mean playback is ready. Fields may be absent for recovered drafts or an older daemon.
 
 Remote frame uploads write accepted/total MiB, transfer speed and an approximate remaining transfer time to stderr. Estimates use this attempt's observed transfers, including retry delays, and exclude previously uploaded bytes. They do not estimate queue or encoding time. JSON stdout stays machine readable. Failed local captures offer an explicit cancellation command for their remote slot; local drafts are retained.
+
+### Failed local capture recovery
+
+If the local recorder reports a terminal failure without a finalized artifact, `rill record stop <id>` attempts to release its unused server reservation and preserves the capture error. The JSON error uses `local_capture_failed` with `details.reservationReleased`; a failed cleanup includes the status command for the selected API origin.
+
+When `record start` is blocked by a recording concurrency slot, it checks the reported blocking recording in the local daemon. A confirmed failed capture with no artifact can release its own unused reservation, then retry creation once with the same request ID. Missing/active local state, retained artifacts, other credentials, Stream uploads, encoding jobs and quota-counted reservations are preserved. Older servers or unavailable networks leave the original quota error and manual recovery guidance intact. Daily upload/storage limits still apply. This change does not resume a failed capture, import missing diagnostics, or add Windows recording support.

package/dist/cli.js

@@ -116,12 +116,13 @@ function recordingNextStep(apiUrl, recordingId, status, options = {}) {
   if (["uploading", "queued", "encoding", "processing", "finalizing"].includes(status)) return { nextCommand: cliCommand(apiUrl, "record", "status", recordingId), message: "Finalizing recordings hold a concurrency slot. Wait for ready; cancel only if abandoning the recording." };
   return {};
 }
-function browserAttachment(cdpUrl) {
+function browserAttachment(cdpUrl, tabId) {
   return {
     protocol: "cdp",
     cdpUrl,
+    ...tabId ? { tabId } : {},
     playwrightMethod: "chromium.connectOverCDP",
-    instructions: "Attach to this endpoint and use the existing browser context. A browser tool must explicitly support CDP attachment; do not drive a separate browser. Disconnect the automation client without closing the recorded browser, then run record stop.",
+    instructions: (tabId ? "Record only the returned tabId. Match it using a page CDP session and Target.getTargetInfo; do not pick the first page. " : "") + "Attach to this endpoint and use the existing browser context. A browser tool must explicitly support CDP attachment; do not drive a separate browser. Disconnect the automation client without closing the recorded browser, then run record stop.",
     shellFallback: "See the shell-only Playwright example in the Rill CLI README; install playwright-core in a temporary directory outside the project."
   };
 }
@@ -452,6 +453,9 @@ var ControlPlaneClient = class {
   createRecording(input) {
     return this.request("/api/recordings", { method: "POST", body: JSON.stringify(input) });
   }
+  failLocalCapture(recordingId) {
+    return this.request(`/api/recordings/${encodeURIComponent(recordingId)}/local-failed`, { method: "POST", body: "{}" });
+  }
   markRecordingStarted(recordingId, input) {
     return this.request(`/api/recordings/${recordingId}/local-started`, {
       method: "POST",
@@ -15147,19 +15151,20 @@ var frameManifestSchema = external_exports.object({
 });
 
 // src/remote-encoding.ts
-async function withFrameUploadRetry(upload, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
+async function withFrameUploadRetry(upload, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), canRetry = () => true) {
   for (let attempt = 0; ; attempt++) {
     try {
       return await upload();
     } catch (error51) {
       const status = error51 instanceof ControlPlaneError || error51 instanceof ControlPlaneHttpError ? error51.httpStatus : void 0;
       const transient = status !== void 0 ? status === 408 || status === 429 || status >= 500 : error51 instanceof TypeError || error51 instanceof DOMException && ["TimeoutError", "AbortError"].includes(error51.name);
-      if (!transient || attempt >= 7) throw error51;
+      if (!transient || attempt >= 7 || !canRetry()) throw error51;
       const delay = Math.min(15e3, 1e3 * 2 ** attempt);
       process.stderr.write(`
 Frame upload interrupted; retrying in ${delay / 1e3}s.
 `);
       await sleep(delay);
+      if (!canRetry()) throw error51;
     }
   }
 }
@@ -15175,8 +15180,12 @@ async function submitFrameCapture(client, id, directory) {
   try {
     const total = manifest.frames.reduce((n, f) => n + f.size, 0);
     if ((await file2.stat()).size !== total) throw new Error("Capture bytes do not match the manifest.");
-    const uploaded = new Set(status.uploadedParts);
-    let acceptedBytes = [...uploaded].reduce((sum, part) => sum + (Number.isInteger(part) && part >= 0 && part < Math.ceil(total / ENCODING_PART_BYTES) ? Math.min(ENCODING_PART_BYTES, total - part * ENCODING_PART_BYTES) : 0), 0);
+    const parts = Math.ceil(total / ENCODING_PART_BYTES);
+    const uploaded = new Set(status.uploadedParts.filter((part) => Number.isInteger(part) && part >= 0 && part < parts));
+    const missing = Array.from({ length: parts }, (_, part) => part).filter((part) => !uploaded.has(part));
+    let next = 0, failed = false;
+    let firstFailure;
+    let acceptedBytes = [...uploaded].reduce((sum, part) => sum + Math.min(ENCODING_PART_BYTES, total - part * ENCODING_PART_BYTES), 0);
     let transferredBytes = 0;
     const startedAt = Date.now();
     const progress = () => {
@@ -15186,20 +15195,34 @@ async function submitFrameCapture(client, id, directory) {
       process.stderr.write(`\ruploading frames ${Math.floor(acceptedBytes / total * 100)}% \xB7 ${(acceptedBytes / 1048576).toFixed(2)}/${(total / 1048576).toFixed(2)} MiB${rate > 0 ? ` \xB7 ${(rate / 1048576).toFixed(2)} MiB/s` : ""}${remaining}`);
     };
     progress();
-    for (let part = 0; part < Math.ceil(total / ENCODING_PART_BYTES); part++) {
-      if (uploaded.has(part)) continue;
-      const bytes = Buffer.alloc(Math.min(ENCODING_PART_BYTES, total - part * ENCODING_PART_BYTES));
-      let offset = 0;
-      while (offset < bytes.length) {
-        const r = await file2.read(bytes, offset, bytes.length - offset, part * ENCODING_PART_BYTES + offset);
-        if (!r.bytesRead) throw new Error("Incomplete capture bytes.");
-        offset += r.bytesRead;
-      }
-      await withFrameUploadRetry(() => client.uploadEncodingPart(id, part, bytes));
-      acceptedBytes += bytes.length;
-      transferredBytes += bytes.length;
-      progress();
-    }
+    const transfer = async () => {
+      while (!failed) {
+        const part = missing[next++];
+        if (part === void 0) return;
+        try {
+          const bytes = Buffer.alloc(Math.min(ENCODING_PART_BYTES, total - part * ENCODING_PART_BYTES));
+          let offset = 0;
+          while (offset < bytes.length) {
+            const r = await file2.read(bytes, offset, bytes.length - offset, part * ENCODING_PART_BYTES + offset);
+            if (!r.bytesRead) throw new Error("Incomplete capture bytes.");
+            offset += r.bytesRead;
+          }
+          if (failed) return;
+          await withFrameUploadRetry(() => client.uploadEncodingPart(id, part, bytes), void 0, () => !failed);
+          acceptedBytes += bytes.length;
+          transferredBytes += bytes.length;
+          progress();
+        } catch (error51) {
+          if (!failed) {
+            firstFailure = error51;
+            failed = true;
+          }
+          throw error51;
+        }
+      }
+    };
+    await Promise.allSettled(Array.from({ length: Math.min(3, missing.length) }, transfer));
+    if (failed) throw firstFailure;
   } finally {
     await file2.close();
   }
@@ -15327,11 +15350,118 @@ async function windowsIpcIdentity(directory = join5(rillDirectory(), "windows-ip
 // ../recorder/src/client.ts
 import { request as request2 } from "http";
 import { spawn as spawn4 } from "child_process";
-async function ensureDaemon(cliEntryPath) {
+
+// ../recorder/src/browser-tabs.ts
+import { chromium } from "playwright-core";
+
+// ../recorder/src/redaction.ts
+var secretKeyPattern = /(?:pass(?:word)?|secret|token|api[_-]?key|authorization|cookie|session|access[_-]?token|refresh[_-]?token|client[_-]?secret)/i;
+var tokenValuePattern = /\b(?:sk|pk|ghp|github_pat|xox[baprs]|eyJ)[-_a-zA-Z0-9.]{16,}\b/g;
+function sanitizeUrl(input) {
   try {
-    await callDaemon("GET", "/health");
-    return;
+    const url2 = new URL(input);
+    url2.username = "";
+    url2.password = "";
+    url2.hash = "";
+    for (const key2 of [...url2.searchParams.keys()]) url2.searchParams.set(key2, "[REDACTED]");
+    return url2.toString();
   } catch {
+    return "[invalid-url]";
+  }
+}
+function redactText(value, maxLength = 8e3) {
+  return value.replace(tokenValuePattern, "[REDACTED]").slice(0, maxLength);
+}
+function redactBody(value, contentType, maxBytes = 65536) {
+  if (Buffer.byteLength(value) > maxBytes) return { body: void 0, omittedReason: "body_too_large" };
+  if (!isAllowedBodyType(contentType)) return { body: void 0, omittedReason: "unsupported_content_type" };
+  if (contentType?.includes("json")) {
+    try {
+      const parsed = JSON.parse(value);
+      return { body: JSON.stringify(redactJson(parsed)) };
+    } catch {
+      return { body: redactText(value) };
+    }
+  }
+  return { body: redactText(value) };
+}
+function isAllowedBodyType(contentType) {
+  if (!contentType) return false;
+  const normalized = contentType.toLowerCase();
+  return normalized.includes("application/json") || normalized.includes("application/problem+json") || normalized.includes("application/graphql-response+json") || normalized.includes("text/plain") || normalized.includes("application/xml") || normalized.includes("text/xml");
+}
+function redactJson(value, depth = 0) {
+  if (depth > 12) return "[TRUNCATED]";
+  if (Array.isArray(value)) return value.slice(0, 100).map((item) => redactJson(item, depth + 1));
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).slice(0, 200).map(([key2, child]) => [key2, secretKeyPattern.test(key2) ? "[REDACTED]" : redactJson(child, depth + 1)]));
+  }
+  if (typeof value === "string") return redactText(value, 8e3);
+  return value;
+}
+
+// ../recorder/src/browser-tabs.ts
+function validateTabSelection(options) {
+  if (options.tabId && !options.cdpUrl) throw new Error("validation_failed: --tab-id requires --cdp-url.");
+}
+async function tabs(browser) {
+  const result = [];
+  for (const context of browser.contexts()) for (const page of context.pages()) {
+    if (page.isClosed()) continue;
+    const session = await context.newCDPSession(page).catch(() => null);
+    if (!session) {
+      if (page.isClosed()) continue;
+      throw new Error("browser_unavailable: Could not inspect an open tab.");
+    }
+    try {
+      const { targetInfo } = await session.send("Target.getTargetInfo");
+      result.push({ page, context, tab: { tabId: targetInfo.targetId, url: /^(?:https?:|about:)/i.test(page.url()) ? sanitizeUrl(page.url()) : `[${page.url().split(":", 1)[0]} URL omitted]`, title: redactText(targetInfo.title, 200) } });
+    } catch (error51) {
+      if (!page.isClosed()) throw error51;
+    } finally {
+      await session.detach().catch(() => void 0);
+    }
+  }
+  return result;
+}
+async function listBrowserTabs(cdpUrl) {
+  const browser = await chromium.connectOverCDP(cdpUrl, { noDefaults: true });
+  try {
+    return (await tabs(browser)).map((entry) => entry.tab);
+  } finally {
+    await browser.close();
+  }
+}
+async function connectRecordingTab(cdpUrl, outputDirectory, tabId) {
+  const browser = await chromium.connectOverCDP(cdpUrl, { artifactsDir: outputDirectory, isLocal: true, noDefaults: true });
+  try {
+    const available = await tabs(browser);
+    const selected = tabId ? available.find((entry) => entry.tab.tabId === tabId) : available.length === 1 ? available[0] : void 0;
+    if (!selected) {
+      if (tabId) throw new Error("browser_unavailable: The selected tab is no longer available. Run record tabs --cdp-url <endpoint> and choose an open tab.");
+      if (!available.length) throw new Error("browser_unavailable: The attached browser has no page target to record.");
+      throw new Error("validation_failed: Several tabs are open. Run record tabs --cdp-url <endpoint>, then record start --cdp-url <endpoint> --tab-id <tab-id>.");
+    }
+    return { cdpUrl, browser, context: selected.context, page: selected.page, tabId: selected.tab.tabId };
+  } catch (error51) {
+    await browser.close().catch(() => void 0);
+    throw error51;
+  }
+}
+
+// ../recorder/src/client.ts
+async function ensureDaemon(cliEntryPath, requireTabSelection = false) {
+  const check2 = (health2) => {
+    if (requireTabSelection && !health2.capabilities?.includes("tab-selection-v1")) throw new Error("browser_unavailable: The running Rill recorder predates tab selection. Stop active recordings, then restart the recorder service before attaching.");
+  };
+  let health;
+  try {
+    health = await callDaemon("GET", "/health");
+  } catch {
+  }
+  if (health) {
+    check2(health);
+    return;
   }
   const child = spawn4(process.execPath, [cliEntryPath, "daemon"], { detached: true, stdio: "ignore", env: process.env, windowsHide: true });
   let startupError;
@@ -15343,11 +15473,13 @@ async function ensureDaemon(cliEntryPath) {
   while (Date.now() < deadline) {
     if (startupError) throw startupError;
     try {
-      await callDaemon("GET", "/health");
-      return;
+      health = await callDaemon("GET", "/health");
     } catch {
       await new Promise((resolve) => setTimeout(resolve, 100));
+      continue;
     }
+    check2(health);
+    return;
   }
   throw new Error("The local recorder service did not start.");
 }
@@ -15424,6 +15556,55 @@ import { createServer as createServer2 } from "http";
 import { mkdir as mkdir7, readFile as readFile7, unlink, writeFile as writeFile6, rename as rename2, stat as stat4, chmod } from "fs/promises";
 import { dirname, join as join10 } from "path";
 
+// ../recorder/src/click-capture.ts
+import { randomUUID as randomUUID2 } from "crypto";
+async function captureClicks(page, session, onClick) {
+  const binding = `__rillClick_${randomUUID2().replaceAll("-", "")}`;
+  const source = `(() => {
+    const key = ${JSON.stringify(binding)};
+    if (window[key + '_listener']) return;
+    const listener = event => {
+      const target = event.target;
+      const label = target?.innerText?.trim().slice(0, 80) || target?.getAttribute?.('aria-label') || target?.tagName || 'Element';
+      try { window[key](JSON.stringify({ x: event.clientX, y: event.clientY, label })); } catch {}
+    };
+    window[key + '_listener'] = listener;
+    document.addEventListener('click', listener, { capture: true });
+  })();`;
+  const receive = (event) => {
+    if (event.name !== binding) return;
+    try {
+      const value = JSON.parse(event.payload);
+      if (typeof value.x === "number" && Number.isFinite(value.x) && typeof value.y === "number" && Number.isFinite(value.y) && typeof value.label === "string") onClick({ x: value.x, y: value.y, label: value.label.slice(0, 80) });
+    } catch {
+    }
+  };
+  let identifier;
+  session.on("Runtime.bindingCalled", receive);
+  const cleanup = async () => {
+    session.off("Runtime.bindingCalled", receive);
+    if (identifier) await session.send("Page.removeScriptToEvaluateOnNewDocument", { identifier }).catch(() => void 0);
+    await Promise.all(page.frames().map((frame) => frame.evaluate((key2) => {
+      const target = window;
+      const listener = target[key2 + "_listener"];
+      if (typeof listener === "function") document.removeEventListener("click", listener, { capture: true });
+      delete target[key2 + "_listener"];
+      delete target[key2];
+    }, binding).catch(() => void 0)));
+    await session.send("Runtime.removeBinding", { name: binding }).catch(() => void 0);
+  };
+  try {
+    await session.send("Runtime.enable");
+    await session.send("Runtime.addBinding", { name: binding });
+    ({ identifier } = await session.send("Page.addScriptToEvaluateOnNewDocument", { source }));
+    await Promise.all(page.frames().map((frame) => frame.evaluate(source)));
+    return cleanup;
+  } catch (error51) {
+    await cleanup();
+    throw error51;
+  }
+}
+
 // ../contracts/src/cloud-blocklist.ts
 var blockedCloudDomains = [
   // Torrent indexes and unofficial software-download destinations.
@@ -15764,7 +15945,7 @@ async function attachCursorOverlay(page, cdp, input) {
 }
 
 // ../recorder/src/session.ts
-import { chromium } from "playwright-core";
+import { chromium as chromium2 } from "playwright-core";
 import { spawn as spawn6 } from "child_process";
 import { createServer } from "net";
 import { mkdir as mkdir6, mkdtemp, rm as rm5, writeFile as writeFile5 } from "fs/promises";
@@ -15806,52 +15987,6 @@ function findChromeExecutable(platform = process.platform, env = process.env, ex
   return candidates.find(exists) ?? "google-chrome";
 }
 
-// ../recorder/src/redaction.ts
-var secretKeyPattern = /(?:pass(?:word)?|secret|token|api[_-]?key|authorization|cookie|session|access[_-]?token|refresh[_-]?token|client[_-]?secret)/i;
-var tokenValuePattern = /\b(?:sk|pk|ghp|github_pat|xox[baprs]|eyJ)[-_a-zA-Z0-9.]{16,}\b/g;
-function sanitizeUrl(input) {
-  try {
-    const url2 = new URL(input);
-    url2.username = "";
-    url2.password = "";
-    url2.hash = "";
-    for (const key2 of [...url2.searchParams.keys()]) url2.searchParams.set(key2, "[REDACTED]");
-    return url2.toString();
-  } catch {
-    return "[invalid-url]";
-  }
-}
-function redactText(value, maxLength = 8e3) {
-  return value.replace(tokenValuePattern, "[REDACTED]").slice(0, maxLength);
-}
-function redactBody(value, contentType, maxBytes = 65536) {
-  if (Buffer.byteLength(value) > maxBytes) return { body: void 0, omittedReason: "body_too_large" };
-  if (!isAllowedBodyType(contentType)) return { body: void 0, omittedReason: "unsupported_content_type" };
-  if (contentType?.includes("json")) {
-    try {
-      const parsed = JSON.parse(value);
-      return { body: JSON.stringify(redactJson(parsed)) };
-    } catch {
-      return { body: redactText(value) };
-    }
-  }
-  return { body: redactText(value) };
-}
-function isAllowedBodyType(contentType) {
-  if (!contentType) return false;
-  const normalized = contentType.toLowerCase();
-  return normalized.includes("application/json") || normalized.includes("application/problem+json") || normalized.includes("application/graphql-response+json") || normalized.includes("text/plain") || normalized.includes("application/xml") || normalized.includes("text/xml");
-}
-function redactJson(value, depth = 0) {
-  if (depth > 12) return "[TRUNCATED]";
-  if (Array.isArray(value)) return value.slice(0, 100).map((item) => redactJson(item, depth + 1));
-  if (value && typeof value === "object") {
-    return Object.fromEntries(Object.entries(value).slice(0, 200).map(([key2, child]) => [key2, secretKeyPattern.test(key2) ? "[REDACTED]" : redactJson(child, depth + 1)]));
-  }
-  if (typeof value === "string") return redactText(value, 8e3);
-  return value;
-}
-
 // ../recorder/src/encoding.ts
 import { open as open2, writeFile as writeFile3, mkdir as mkdir4 } from "fs/promises";
 import { spawn as spawn5 } from "child_process";
@@ -16009,6 +16144,7 @@ var RecordingSession = class _RecordingSession {
   recordingId;
   startedAt = /* @__PURE__ */ new Date();
   cdpUrl;
+  tabId;
   browser;
   context;
   page;
@@ -16023,6 +16159,7 @@ var RecordingSession = class _RecordingSession {
   stopPromise;
   maxTimer;
   maxDurationSeconds;
+  removeClickCapture;
   removeCursorOverlay;
   diagnosticsPaused = false;
   secretValues = [];
@@ -16039,6 +16176,7 @@ var RecordingSession = class _RecordingSession {
     this.captureSignal = options.signal;
     this.recordingId = options.recordingId;
     this.cdpUrl = runtime.cdpUrl;
+    this.tabId = runtime.tabId;
     this.browser = runtime.browser;
     this.context = runtime.context;
     this.page = runtime.page;
@@ -16048,16 +16186,25 @@ var RecordingSession = class _RecordingSession {
     this.outputDirectory = options.outputDirectory;
   }
   static async start(options) {
+    validateTabSelection(options);
     const width = options.width ?? 1280;
     const height = options.height ?? 720;
     await mkdir6(options.outputDirectory, { recursive: true, mode: 448 });
     if (options.encoding === "remote") await writeFile5(join9(options.outputDirectory, "remote-capture.json"), JSON.stringify({ expiresAt: Date.now() + 864e5 }), { mode: 384 });
-    const runtime = options.cdpUrl ? await connectAttached(options.cdpUrl, options.outputDirectory) : await launchManaged({ headed: options.headed ?? false, width, height, outputDirectory: options.outputDirectory, proxyServer: options.proxyServer, blockServiceWorkers: options.blockServiceWorkers });
-    const cdpSession = await runtime.context.newCDPSession(runtime.page);
+    const runtime = options.cdpUrl ? await connectRecordingTab(options.cdpUrl, options.outputDirectory, options.tabId) : await launchManaged({ headed: options.headed ?? false, width, height, outputDirectory: options.outputDirectory, proxyServer: options.proxyServer, blockServiceWorkers: options.blockServiceWorkers });
+    let cdpSession;
+    try {
+      cdpSession = await runtime.context.newCDPSession(runtime.page);
+    } catch (error51) {
+      await runtime.browser.close().catch(() => void 0);
+      if ("browserProcess" in runtime && runtime.browserProcess) await terminateBrowser(runtime.browserProcess);
+      if ("profileDirectory" in runtime && runtime.profileDirectory) await rm5(runtime.profileDirectory, { recursive: true, force: true }).catch(() => void 0);
+      throw error51;
+    }
     const screencast = new ScreencastRecorder(cdpSession, join9(options.outputDirectory, "frames"), width, height);
     const session = new _RecordingSession(options, { ...runtime, screencast });
     try {
-      await session.attachDiagnostics(options.captureNetworkBodies ?? false);
+      await session.attachDiagnostics(options.captureNetworkBodies ?? false, cdpSession);
       if (!options.hideCursor) session.removeCursorOverlay = await attachCursorOverlay(runtime.page, cdpSession, options.cursorAppearance);
       await options.beforeCapture?.(runtime.page);
       session.startedAt = /* @__PURE__ */ new Date();
@@ -16082,6 +16229,7 @@ var RecordingSession = class _RecordingSession {
     return {
       recordingId: this.recordingId,
       cdpUrl: this.cdpUrl,
+      ...this.tabId ? { tabId: this.tabId } : {},
       startedAt: this.startedAt.toISOString(),
       maxDurationSeconds: this.maxDurationSeconds,
       elapsedSeconds,
@@ -16118,9 +16266,10 @@ var RecordingSession = class _RecordingSession {
       await writeBundle(safeBundle, diagnosticsPath);
       await this.screencast.stop(videoPath, durationSeconds, this.encoding === "remote", this.captureSignal);
     } finally {
-      await this.removeCursorOverlay?.();
+      await this.removeClickCapture?.().catch(() => void 0);
+      await this.removeCursorOverlay?.().catch(() => void 0);
+      await this.browser.close().catch(() => void 0);
       if (this.browserProcess) {
-        await this.browser.close().catch(() => void 0);
         await terminateBrowser(this.browserProcess);
         if (this.profileDirectory) await rm5(this.profileDirectory, { recursive: true, force: true }).catch(() => void 0);
       }
@@ -16135,7 +16284,7 @@ var RecordingSession = class _RecordingSession {
   videoFormat = "webm";
   encoding = "local";
   outputDirectory = "";
-  async attachDiagnostics(captureNetworkBodies) {
+  async attachDiagnostics(captureNetworkBodies, cdpSession) {
     this.captureNetworkBodies = captureNetworkBodies;
     const offset = () => Date.now() - this.startedAt.getTime();
     const pushTimeline = (event) => {
@@ -16146,14 +16295,7 @@ var RecordingSession = class _RecordingSession {
       }
       this.timelineEvents.push({ id: `time_${this.timelineEvents.length + 1}`, ...event });
     };
-    await this.page.exposeFunction("__rillClick", (payload) => pushTimeline({ offsetMs: offset(), type: "click", label: `${payload.label || "Element"} at ${Math.round(payload.x)},${Math.round(payload.y)}` })).catch(() => void 0);
-    await this.page.addInitScript(() => {
-      document.addEventListener("click", (event) => {
-        const target = event.target;
-        const label = target?.innerText?.trim().slice(0, 80) || target?.getAttribute("aria-label") || target?.tagName || "Element";
-        void window.__rillClick?.({ x: event.clientX, y: event.clientY, label });
-      }, { capture: true });
-    });
+    this.removeClickCapture = await captureClicks(this.page, cdpSession, (payload) => pushTimeline({ offsetMs: offset(), type: "click", label: `${payload.label || "Element"} at ${Math.round(payload.x)},${Math.round(payload.y)}` }));
     this.page.on("framenavigated", (frame) => {
       if (frame === this.page.mainFrame()) pushTimeline({ offsetMs: offset(), type: "navigation", label: sanitizeUrl(frame.url()) });
     });
@@ -16264,7 +16406,7 @@ async function launchManaged(options) {
   const cdpUrl = `http://127.0.0.1:${port}`;
   try {
     await waitForCdp(cdpUrl, browserProcess);
-    const browser = await chromium.connectOverCDP(cdpUrl, { artifactsDir: options.outputDirectory, isLocal: true });
+    const browser = await chromium2.connectOverCDP(cdpUrl, { artifactsDir: options.outputDirectory, isLocal: true });
     const context = options.blockServiceWorkers ? await browser.newContext({ serviceWorkers: "block" }) : browser.contexts()[0];
     const page = context.pages()[0] ?? await context.newPage();
     await page.setViewportSize({ width: options.width, height: options.height });
@@ -16275,13 +16417,6 @@ async function launchManaged(options) {
     throw error51;
   }
 }
-async function connectAttached(cdpUrl, outputDirectory) {
-  const browser = await chromium.connectOverCDP(cdpUrl, { artifactsDir: outputDirectory, isLocal: true, noDefaults: true });
-  const context = browser.contexts()[0];
-  const page = context.pages()[0];
-  if (!page) throw new Error("The attached browser has no page target to record.");
-  return { cdpUrl, browser, context, page };
-}
 async function getAvailablePort() {
   const server = createServer();
   await new Promise((resolve, reject) => server.listen(0, "127.0.0.1", resolve).once("error", reject));
@@ -16366,7 +16501,7 @@ async function runDaemon() {
 async function route(request3, response) {
   lastActivity = Date.now();
   const url2 = new URL(request3.url ?? "/", "http://daemon.local");
-  if (request3.method === "GET" && url2.pathname === "/health") return json2(response, 200, { ok: true, pid: process.pid });
+  if (request3.method === "GET" && url2.pathname === "/health") return json2(response, 200, { ok: true, pid: process.pid, capabilities: ["tab-selection-v1"] });
   if (request3.method === "POST" && url2.pathname === "/sessions") {
     if ([...sessions.values()].filter((entry) => entry.state === "recording").length >= 2) return json2(response, 429, { error: { code: "quota_exceeded", message: "This recorder already has two active sessions." } });
     try {
@@ -16375,7 +16510,7 @@ async function route(request3, response) {
       const outputDirectory = join10(recordingTempRoot(), input.recordingId);
       const session = await RecordingSession.start({ ...input, outputDirectory });
       const status = session.status();
-      const entry = { session, base: { recordingId: status.recordingId, cdpUrl: status.cdpUrl, startedAt: status.startedAt }, state: "recording" };
+      const entry = { session, base: { recordingId: status.recordingId, cdpUrl: status.cdpUrl, tabId: status.tabId, startedAt: status.startedAt }, state: "recording" };
       sessions.set(input.recordingId, entry);
       const maxTimer = setTimeout(() => void finalizeEntry(entry, "max_duration"), Math.max(0, Date.parse(status.stopsAt) - Date.now()) + 250);
       maxTimer.unref();
@@ -16426,7 +16561,7 @@ async function restoreRecoverableSessions() {
     const value = JSON.parse(await readFile7(daemonStatePath(), "utf8"));
     for (const [id, entry] of Object.entries(value)) {
       if (entry.status !== "ready" && entry.status !== "failed") continue;
-      sessions.set(id, { base: { recordingId: entry.recordingId, cdpUrl: entry.cdpUrl, startedAt: entry.startedAt }, state: entry.status, result: entry.result, error: entry.error });
+      sessions.set(id, { base: { recordingId: entry.recordingId, cdpUrl: entry.cdpUrl, tabId: entry.tabId, startedAt: entry.startedAt }, state: entry.status, result: entry.result, error: entry.error });
     }
   } catch {
   }
@@ -16502,7 +16637,7 @@ function emit(value, pretty = false) {
 function failureValue(error51) {
   const message = error51 instanceof Error ? error51.message : String(error51);
   const [candidate] = message.split(":", 1);
-  const knownCodes = /* @__PURE__ */ new Set(["authentication_required", "authorization_not_found", "expired_token", "access_denied", "unsupported_platform", "scope_denied", "quota_exceeded", "browser_unavailable", "recording_not_found", "upload_interrupted", "processing_pending", "processing_failed", "share_revoked", "validation_failed"]);
+  const knownCodes = /* @__PURE__ */ new Set(["authentication_required", "authorization_not_found", "expired_token", "access_denied", "unsupported_platform", "scope_denied", "quota_exceeded", "browser_unavailable", "local_capture_failed", "recording_not_found", "upload_interrupted", "processing_pending", "processing_failed", "share_revoked", "validation_failed"]);
   const structured = error51 && typeof error51 === "object" ? error51 : {};
   const code = structured.code && knownCodes.has(structured.code) ? structured.code : knownCodes.has(candidate) ? candidate : "internal_error";
   return { error: { code, message, ...structured.recovery ? { recovery: structured.recovery } : {}, ...structured.details ? { details: structured.details } : {} } };
@@ -16778,6 +16913,48 @@ async function remoteAwareRecordingStatus(recordingId, dependencies, apiUrl = "h
     return remoteView;
   }
 }
+async function releaseFailedLocalCapture(id, dependencies) {
+  const local = await dependencies.localStatus(id).catch(() => null);
+  if (!local || local.recordingId !== id || local.status !== "failed" || local.result) return false;
+  try {
+    await dependencies.failRemote(id);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function createRecordingWithRecovery(dependencies) {
+  try {
+    return await dependencies.createRemote();
+  } catch (error51) {
+    if (!(error51 instanceof ControlPlaneError) || error51.code !== "quota_exceeded") throw error51;
+    const quota = error51.details?.quota;
+    if (!quota || !["credential_concurrency", "workspace_concurrency"].includes(String(quota.type)) || typeof quota.blockingRecordingId !== "string" || !/^rec_[a-zA-Z0-9_-]+$/.test(quota.blockingRecordingId)) throw error51;
+    if (!await releaseFailedLocalCapture(quota.blockingRecordingId, dependencies)) throw error51;
+    dependencies.onRecovered?.(quota.blockingRecordingId);
+    return dependencies.createRemote();
+  }
+}
+async function stopRecordingWithCompensation(id, dependencies, apiUrl) {
+  let local;
+  try {
+    local = await dependencies.stopLocal(id);
+  } catch (error51) {
+    const known = await dependencies.localStatus(id).catch(() => null);
+    if (!known || known.recordingId !== id || known.status !== "failed" || known.result) throw error51;
+    local = known;
+  }
+  if (local.recordingId === id && local.status === "failed" && !local.result) {
+    const released = await releaseFailedLocalCapture(id, dependencies);
+    throw new ControlPlaneError(
+      "local_capture_failed",
+      local.error ?? "The local capture could not be finalized.",
+      released ? "Its unused recording slot was released. Start a new recording." : `The recording slot could not be released automatically. Check ${cliCommand(apiUrl, "record", "status", id)} before cancelling it.`,
+      { recordingId: id, reservationReleased: released }
+    );
+  }
+  return local;
+}
 
 // src/config.ts
 var PRODUCTION_API_URL = "https://userill.dev";
@@ -16881,9 +17058,14 @@ for (const action of ["status", "cancel"]) cloudRun.command(action).argument("<r
   if (options.json || options.pretty) emit(customerRun(run2), options.pretty);
   else process.stdout.write(formatCloudRun(run2));
 });
-record2.command("start").option("--encoding <mode>", "remote or local", "remote").option("--url <url>").option("--title <title>").option("--description <description>", "").option("--headed").option("--cdp-url <url>").option("--width <pixels>", "", "1280").option("--height <pixels>", "", "720").option("--max-duration <seconds>", "", "600").action(async (commandOptions) => {
+record2.command("tabs").requiredOption("--cdp-url <url>", "Existing Chromium CDP endpoint").action(async (commandOptions) => {
+  const options = program.opts();
+  emit({ schemaVersion: 1, tabs: await listBrowserTabs(commandOptions.cdpUrl) }, options.pretty);
+});
+record2.command("start").option("--encoding <mode>", "remote or local", "remote").option("--url <url>").option("--title <title>").option("--description <description>", "").option("--headed").option("--cdp-url <url>").option("--tab-id <id>", "Record this existing tab from record tabs").option("--width <pixels>", "", "1280").option("--height <pixels>", "", "720").option("--max-duration <seconds>", "", "600").action(async (commandOptions) => {
   const options = program.opts();
   assertRecorderTransport();
+  validateTabSelection(commandOptions);
   await ensureAnonymousCredential(options.apiUrl);
   const client = new ControlPlaneClient(options.apiUrl, () => loadCredential(options.apiUrl));
   const result = await withRunFeedback(() => client.agentSession(), async (rememberRecording) => {
@@ -16892,12 +17074,21 @@ record2.command("start").option("--encoding <mode>", "remote or local", "remote"
     if (!Number.isFinite(Number(commandOptions.maxDuration)) || Number(commandOptions.maxDuration) < 1 || Number(commandOptions.maxDuration) > 600) throw new Error("Recording duration must be between 1 and 600 seconds.");
     const width = Number(commandOptions.width);
     const height = Number(commandOptions.height);
-    const remote = await client.createRecording({ title: commandOptions.title ?? `Browser recording \xB7 ${(/* @__PURE__ */ new Date()).toISOString()}`, description: commandOptions.description, sourceUrl: commandOptions.url ?? null, width, height });
+    const metadata = { requestId: crypto.randomUUID(), title: commandOptions.title ?? `Browser recording \xB7 ${(/* @__PURE__ */ new Date()).toISOString()}`, description: commandOptions.description, sourceUrl: commandOptions.url ?? null, width, height };
+    const remote = await createRecordingWithRecovery({
+      createRemote: () => client.createRecording(metadata),
+      localStatus: recordingStatus,
+      failRemote: (id) => client.failLocalCapture(id),
+      onRecovered: (id) => {
+        process.stderr.write(`Released the unused slot for failed local capture ${id}.
+`);
+      }
+    });
     rememberRecording(remote.recordingId);
     const local = await startRecordingWithCompensation(remote, {
       startLocal: async () => {
-        await ensureDaemon(process.argv[1]);
-        return startRecording({ encoding: commandOptions.encoding, recordingId: remote.recordingId, url: commandOptions.url, cdpUrl: commandOptions.cdpUrl, headed: Boolean(commandOptions.headed), width, height, maxDurationSeconds: Math.min(Number(commandOptions.maxDuration), remote.maxDurationSeconds ?? 600), captureNetworkBodies: remote.bodyCaptureEnabled, cursorAppearance: remote.cursorAppearance });
+        await ensureDaemon(process.argv[1], Boolean(commandOptions.cdpUrl));
+        return startRecording({ encoding: commandOptions.encoding, recordingId: remote.recordingId, url: commandOptions.url, cdpUrl: commandOptions.cdpUrl, tabId: commandOptions.tabId, headed: Boolean(commandOptions.headed), width, height, maxDurationSeconds: Math.min(Number(commandOptions.maxDuration), remote.maxDurationSeconds ?? 600), captureNetworkBodies: remote.bodyCaptureEnabled, cursorAppearance: remote.cursorAppearance });
       },
       cancelRemote: (recordingId, reason) => client.cancelRecording(recordingId, reason)
     }, options.apiUrl);
@@ -16908,16 +17099,20 @@ record2.command("start").option("--encoding <mode>", "remote or local", "remote"
       headed: Boolean(commandOptions.headed),
       attached: Boolean(commandOptions.cdpUrl)
     }).catch(() => void 0);
-    return { schemaVersion: 1, recordingId: remote.recordingId, status: local.status, cdpUrl: local.cdpUrl, browserAttachment: browserAttachment(local.cdpUrl), startedAt: local.startedAt, stopsAt: local.stopsAt, elapsedSeconds: local.elapsedSeconds, remainingSeconds: local.remainingSeconds, bodyCaptureEnabled: remote.bodyCaptureEnabled, anonymous: remote.anonymous ?? false, expiresAt: remote.expiresAt ?? null, maxDurationSeconds: Math.min(Number(commandOptions.maxDuration), remote.maxDurationSeconds ?? 600) };
+    return { schemaVersion: 1, recordingId: remote.recordingId, status: local.status, cdpUrl: local.cdpUrl, ...local.tabId ? { tabId: local.tabId } : {}, browserAttachment: browserAttachment(local.cdpUrl, local.tabId), startedAt: local.startedAt, stopsAt: local.stopsAt, elapsedSeconds: local.elapsedSeconds, remainingSeconds: local.remainingSeconds, bodyCaptureEnabled: remote.bodyCaptureEnabled, anonymous: remote.anonymous ?? false, expiresAt: remote.expiresAt ?? null, maxDurationSeconds: Math.min(Number(commandOptions.maxDuration), remote.maxDurationSeconds ?? 600) };
   });
   emit(result, options.pretty);
 });
 record2.command("stop").argument("<recording-id>").option("--no-wait").option("--no-feedback", "Disable feedback only when the user explicitly requests it").action(async (recordingId, commandOptions) => {
   const options = program.opts();
   await ensureDaemon(process.argv[1]);
-  const local = await stopRecording(recordingId);
-  if (!local.result) throw new Error(local.error ?? "The recorder did not produce an artifact.");
   const client = new ControlPlaneClient(options.apiUrl, () => loadCredential(options.apiUrl));
+  const local = await stopRecordingWithCompensation(recordingId, {
+    stopLocal: stopRecording,
+    localStatus: recordingStatus,
+    failRemote: (id) => client.failLocalCapture(id)
+  }, options.apiUrl);
+  if (!local.result) throw new Error(local.error ?? "The recorder did not produce an artifact.");
   const stopped = await client.markRecordingStopped(recordingId, {
     durationSeconds: local.result.durationSeconds,
     stoppedReason: local.result.stoppedReason,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runalabs/rill-cli",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "Record, inspect, and share agent-controlled browser runs with Rill.",
   "license": "Apache-2.0",
   "repository": {