@runalabs/rill-cli 0.1.0

package/README.md

@@ -0,0 +1,27 @@
+# @runalabs/rill-cli
+
+Record, inspect, and share agent-controlled browser runs with Rill.
+
+## Install
+
+```sh
+npm install --global @runalabs/rill-cli@0.1.0
+rill doctor
+```
+
+Rill requires Node.js 22 or newer, Google Chrome or Chromium, and `ffmpeg`.
+The CLI defaults to the Rill private-alpha staging API. Set `RILL_API_URL` or
+pass `--api-url` to target another environment.
+
+## Record
+
+```sh
+rill login
+rill doctor
+rill record start --url https://staging.example.com --title "Agent reproduction"
+# Connect browser automation to the returned cdpUrl.
+rill record stop <recording-id>
+```
+
+Commands emit one schema-versioned JSON object to stdout. Human-readable
+progress is written to stderr.

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,939 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { Command } from "commander";
+import { hostname } from "os";
+import { basename, dirname as dirname2 } from "path";
+import { readdir, rm as rm2, stat as stat2 } from "fs/promises";
+
+// ../recorder/src/client.ts
+import { request } from "http";
+import { spawn } from "child_process";
+
+// ../recorder/src/paths.ts
+import { homedir, tmpdir } from "os";
+import { join } from "path";
+var rillDirectory = () => process.env.RILL_HOME ?? join(homedir(), ".rill");
+var daemonSocketPath = () => process.env.RILL_SOCKET ?? join(rillDirectory(), "recorder.sock");
+var daemonStatePath = () => join(rillDirectory(), "sessions.json");
+var recordingTempRoot = () => process.env.RILL_TEMP ?? join(tmpdir(), "rill-recordings");
+
+// ../recorder/src/client.ts
+async function ensureDaemon(cliEntryPath) {
+  try {
+    await callDaemon("GET", "/health");
+    return;
+  } catch {
+  }
+  const child = spawn(process.execPath, [cliEntryPath, "daemon"], { detached: true, stdio: "ignore", env: process.env });
+  child.unref();
+  const deadline = Date.now() + 1e4;
+  while (Date.now() < deadline) {
+    try {
+      await callDaemon("GET", "/health");
+      return;
+    } catch {
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+  }
+  throw new Error("The local recorder service did not start.");
+}
+function startRecording(input) {
+  return callDaemon("POST", "/sessions", input);
+}
+function stopRecording(recordingId) {
+  return callDaemon("POST", `/sessions/${encodeURIComponent(recordingId)}/stop`, {});
+}
+function recordingStatus(recordingId) {
+  return callDaemon("GET", `/sessions/${encodeURIComponent(recordingId)}`);
+}
+function callDaemon(method, path, body) {
+  return new Promise((resolve, reject) => {
+    const payload = body === void 0 ? void 0 : Buffer.from(JSON.stringify(body));
+    const outgoing = request({ socketPath: daemonSocketPath(), method, path, headers: payload ? { "Content-Type": "application/json", "Content-Length": payload.length } : void 0 }, (incoming) => {
+      const chunks = [];
+      incoming.on("data", (chunk) => chunks.push(Buffer.from(chunk)));
+      incoming.on("end", () => {
+        try {
+          const value = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+          if ((incoming.statusCode ?? 500) >= 400) reject(new Error(value.error?.message ?? `Recorder returned ${incoming.statusCode}.`));
+          else resolve(value);
+        } catch (error) {
+          reject(error);
+        }
+      });
+    });
+    outgoing.once("error", reject);
+    if (payload) outgoing.write(payload);
+    outgoing.end();
+  });
+}
+
+// ../recorder/src/daemon.ts
+import { createServer as createServer2 } from "http";
+import { mkdir as mkdir3, readFile, unlink, writeFile as writeFile2 } from "fs/promises";
+import { dirname, join as join4 } from "path";
+
+// ../recorder/src/session.ts
+import { chromium } from "playwright-core";
+import { spawn as spawn3 } from "child_process";
+import { createServer } from "net";
+import { mkdir as mkdir2, mkdtemp, rm } from "fs/promises";
+import { join as join3 } from "path";
+import { tmpdir as tmpdir2 } from "os";
+
+// ../recorder/src/bundle.ts
+import { createGzip } from "zlib";
+import { createWriteStream } from "fs";
+import { once } from "events";
+async function writeBundle(bundle, outputPath) {
+  const output = createWriteStream(outputPath, { mode: 384 });
+  const gzip = createGzip({ level: 9 });
+  gzip.pipe(output);
+  const { console: consoleEvents, network, timeline, ...manifest } = bundle;
+  gzip.write(`${JSON.stringify({ kind: "manifest", ...manifest })}
+`);
+  for (const event of consoleEvents) gzip.write(`${JSON.stringify({ kind: "console", ...event })}
+`);
+  for (const event of network) gzip.write(`${JSON.stringify({ kind: "network", ...event })}
+`);
+  for (const event of timeline) gzip.write(`${JSON.stringify({ kind: "timeline", ...event })}
+`);
+  gzip.end();
+  await once(output, "close");
+}
+
+// ../recorder/src/environment.ts
+import { existsSync } from "fs";
+function findChromeExecutable() {
+  if (process.env.RILL_CHROME_PATH) return process.env.RILL_CHROME_PATH;
+  if (process.platform === "darwin") return "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome";
+  const candidates = ["/usr/bin/google-chrome", "/usr/bin/google-chrome-stable", "/usr/bin/chromium", "/usr/bin/chromium-browser"];
+  return candidates.find((candidate) => existsSync(candidate)) ?? "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 url = new URL(input);
+    url.username = "";
+    url.password = "";
+    url.hash = "";
+    for (const key of [...url.searchParams.keys()]) url.searchParams.set(key, "[REDACTED]");
+    return url.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(([key, child]) => [key, secretKeyPattern.test(key) ? "[REDACTED]" : redactJson(child, depth + 1)]));
+  }
+  if (typeof value === "string") return redactText(value, 8e3);
+  return value;
+}
+
+// ../recorder/src/screencast.ts
+import { mkdir, writeFile } from "fs/promises";
+import { spawn as spawn2 } from "child_process";
+import { join as join2 } from "path";
+import { once as once2 } from "events";
+function createFfconcatManifest(frames, expectedDurationSeconds) {
+  if (!frames.length) throw new Error("No video frames were captured.");
+  const orderedFrames = frames.toSorted((left, right) => left.timestamp - right.timestamp);
+  const firstTimestamp = orderedFrames[0].timestamp;
+  const lines = ["ffconcat version 1.0"];
+  for (let index = 0; index < orderedFrames.length; index += 1) {
+    const frame = orderedFrames[index];
+    const next = orderedFrames[index + 1];
+    const elapsedAtFrame = Math.max(0, frame.timestamp - firstTimestamp);
+    const duration = next ? Math.max(1 / 60, next.timestamp - frame.timestamp) : Math.max(1 / 60, expectedDurationSeconds - elapsedAtFrame);
+    lines.push(`file '${frame.path.replaceAll("'", "'\\''")}'`, `duration ${duration.toFixed(6)}`);
+  }
+  lines.push(`file '${orderedFrames.at(-1).path.replaceAll("'", "'\\''")}'`);
+  return `${lines.join("\n")}
+`;
+}
+var ScreencastRecorder = class {
+  constructor(session, directory, width, height) {
+    this.session = session;
+    this.directory = directory;
+    this.width = width;
+    this.height = height;
+  }
+  frames = [];
+  pendingWrites = /* @__PURE__ */ new Set();
+  started = false;
+  frameCounter = 0;
+  async start() {
+    await mkdir(this.directory, { recursive: true, mode: 448 });
+    this.session.on("Page.screencastFrame", (payload) => {
+      const path = join2(this.directory, `frame-${String(this.frameCounter).padStart(6, "0")}.jpg`);
+      this.frameCounter += 1;
+      const write = writeFile(path, Buffer.from(payload.data, "base64"), { mode: 384 }).then(() => {
+        this.frames.push({ path, timestamp: payload.metadata.timestamp ?? Date.now() / 1e3 });
+      }).finally(() => {
+        this.pendingWrites.delete(write);
+        void this.session.send("Page.screencastFrameAck", { sessionId: payload.sessionId }).catch(() => void 0);
+      });
+      this.pendingWrites.add(write);
+    });
+    await this.session.send("Page.enable");
+    await this.session.send("Page.startScreencast", { format: "jpeg", quality: 82, maxWidth: this.width, maxHeight: this.height, everyNthFrame: 1 });
+    this.started = true;
+  }
+  async stop(outputPath, expectedDurationSeconds) {
+    if (this.started) await this.session.send("Page.stopScreencast").catch(() => void 0);
+    await new Promise((resolve) => setTimeout(resolve, 120));
+    await Promise.all(this.pendingWrites);
+    if (!this.frames.length) throw new Error("No video frames were captured.");
+    const manifestPath = join2(this.directory, "frames.ffconcat");
+    await writeFile(manifestPath, createFfconcatManifest(this.frames, expectedDurationSeconds), { mode: 384 });
+    const ffmpeg = process.env.RILL_FFMPEG ?? "ffmpeg";
+    const processHandle = spawn2(ffmpeg, ["-hide_banner", "-loglevel", "error", "-f", "concat", "-safe", "0", "-i", manifestPath, "-vsync", "vfr", "-pix_fmt", "yuv420p", "-c:v", "libvpx-vp9", "-b:v", "0", "-crf", "32", "-y", outputPath], { stdio: ["ignore", "ignore", "pipe"] });
+    let stderr = "";
+    processHandle.stderr.on("data", (chunk) => {
+      stderr += String(chunk);
+    });
+    const [exitCode] = await once2(processHandle, "exit");
+    if (exitCode !== 0) throw new Error(`ffmpeg could not finalize the recording: ${stderr.trim()}`);
+    return { frameCount: this.frames.length, outputPath };
+  }
+};
+
+// ../recorder/src/session.ts
+var severityMap = { debug: "debug", info: "info", log: "info", warning: "warning", warn: "warning", error: "error", assert: "error" };
+var RecordingSession = class _RecordingSession {
+  recordingId;
+  startedAt = /* @__PURE__ */ new Date();
+  cdpUrl;
+  browser;
+  context;
+  page;
+  browserProcess;
+  profileDirectory;
+  screencast;
+  consoleEvents = [];
+  networkEvents = [];
+  timelineEvents = [];
+  requestStart = /* @__PURE__ */ new Map();
+  requestEvents = /* @__PURE__ */ new Map();
+  stopPromise;
+  maxTimer;
+  bodyBytes = 0;
+  truncated = false;
+  constructor(options, runtime) {
+    this.recordingId = options.recordingId;
+    this.cdpUrl = runtime.cdpUrl;
+    this.browser = runtime.browser;
+    this.context = runtime.context;
+    this.page = runtime.page;
+    this.browserProcess = runtime.browserProcess;
+    this.profileDirectory = runtime.profileDirectory;
+    this.screencast = runtime.screencast;
+    this.outputDirectory = options.outputDirectory;
+  }
+  static async start(options) {
+    const width = options.width ?? 1280;
+    const height = options.height ?? 720;
+    await mkdir2(options.outputDirectory, { recursive: true, mode: 448 });
+    const runtime = options.cdpUrl ? await connectAttached(options.cdpUrl, options.outputDirectory) : await launchManaged({ headed: options.headed ?? false, width, height, outputDirectory: options.outputDirectory });
+    const cdpSession = await runtime.context.newCDPSession(runtime.page);
+    const screencast = new ScreencastRecorder(cdpSession, join3(options.outputDirectory, "frames"), width, height);
+    const session = new _RecordingSession(options, { ...runtime, screencast });
+    await session.attachDiagnostics(options.captureNetworkBodies ?? false);
+    await screencast.start();
+    if (options.url) await session.page.goto(options.url, { waitUntil: "domcontentloaded" });
+    session.maxTimer = setTimeout(() => void session.stop("max_duration"), (options.maxDurationSeconds ?? 600) * 1e3);
+    return session;
+  }
+  status() {
+    return { recordingId: this.recordingId, cdpUrl: this.cdpUrl, startedAt: this.startedAt.toISOString(), status: this.stopPromise ? "finalizing" : "recording" };
+  }
+  async stop(reason = "agent_request") {
+    this.stopPromise ??= this.finalize(reason);
+    return this.stopPromise;
+  }
+  async finalize(reason) {
+    if (this.maxTimer) clearTimeout(this.maxTimer);
+    const durationSeconds = Math.max(0.1, (Date.now() - this.startedAt.getTime()) / 1e3);
+    const outputDirectory = this.outputDirectory;
+    const videoPath = join3(outputDirectory, "recording.webm");
+    const diagnosticsPath = join3(outputDirectory, "diagnostics-v1.ndjson.gz");
+    await this.screencast.stop(videoPath, durationSeconds);
+    const bundle = {
+      schemaVersion: 1,
+      capturePolicyVersion: "safe-default-v1",
+      recordingId: this.recordingId,
+      startedAt: this.startedAt.toISOString(),
+      durationMs: Math.round(durationSeconds * 1e3),
+      bodyCaptureEnabled: this.captureNetworkBodies,
+      bodyCaptureRedacted: this.captureNetworkBodies,
+      truncated: this.truncated,
+      console: this.consoleEvents,
+      network: this.networkEvents,
+      timeline: this.timelineEvents.toSorted((left, right) => left.offsetMs - right.offsetMs)
+    };
+    await writeBundle(bundle, diagnosticsPath);
+    if (this.browserProcess) {
+      await this.browser.close().catch(() => void 0);
+      this.browserProcess.kill("SIGTERM");
+      if (this.profileDirectory) await rm(this.profileDirectory, { recursive: true, force: true }).catch(() => void 0);
+    }
+    const consoleErrors = this.consoleEvents.filter((event) => event.severity === "error").length;
+    const failedRequests = this.networkEvents.filter((event) => event.failureReason).length;
+    const httpErrors = this.networkEvents.filter((event) => (event.status ?? 0) >= 400).length;
+    return { recordingId: this.recordingId, videoPath, diagnosticsPath, durationSeconds, stoppedReason: reason, diagnostics: { consoleErrors, failedRequests, httpErrors, truncated: this.truncated, bodyCaptureEnabled: this.captureNetworkBodies } };
+  }
+  captureNetworkBodies = false;
+  outputDirectory = "";
+  async attachDiagnostics(captureNetworkBodies) {
+    this.captureNetworkBodies = captureNetworkBodies;
+    const offset = () => Date.now() - this.startedAt.getTime();
+    const pushTimeline = (event) => {
+      if (this.timelineEvents.length >= 1e4) {
+        this.truncated = true;
+        return;
+      }
+      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.page.on("framenavigated", (frame) => {
+      if (frame === this.page.mainFrame()) pushTimeline({ offsetMs: offset(), type: "navigation", label: sanitizeUrl(frame.url()) });
+    });
+    this.page.on("console", async (message) => {
+      if (this.consoleEvents.length >= 1e4) {
+        this.truncated = true;
+        return;
+      }
+      const args = await Promise.all(message.args().slice(0, 20).map(async (arg) => {
+        try {
+          return JSON.stringify(await arg.jsonValue());
+        } catch {
+          return arg.toString();
+        }
+      }));
+      const severity = severityMap[message.type()] ?? "info";
+      const location = message.location();
+      const event = { id: `con_${this.consoleEvents.length + 1}`, offsetMs: offset(), severity, text: redactText(args.join(" ") || message.text()), sourceUrl: location.url ? sanitizeUrl(location.url) : void 0, lineNumber: location.lineNumber, stack: [] };
+      this.consoleEvents.push(event);
+      if (severity === "error" || severity === "warning") pushTimeline({ offsetMs: event.offsetMs, type: "console", label: event.text.slice(0, 160), severity });
+    });
+    this.page.on("pageerror", (error) => {
+      const event = { id: `con_${this.consoleEvents.length + 1}`, offsetMs: offset(), severity: "error", text: redactText(error.message), stack: redactText(error.stack ?? "").split("\n").slice(0, 20) };
+      this.consoleEvents.push(event);
+      pushTimeline({ offsetMs: event.offsetMs, type: "exception", label: event.text.slice(0, 160), severity: "error" });
+    });
+    this.page.on("request", (request2) => {
+      if (this.networkEvents.length >= 5e3) {
+        this.truncated = true;
+        return;
+      }
+      const started = offset();
+      this.requestStart.set(request2, started);
+      const event = { id: `net_${this.networkEvents.length + 1}`, offsetMs: started, method: request2.method(), url: sanitizeUrl(request2.url()), resourceType: request2.resourceType() };
+      if (captureNetworkBodies && request2.postData()) {
+        const redacted = redactBody(request2.postData(), request2.headers()["content-type"]);
+        event.requestBody = redacted.body;
+        event.bodyOmittedReason = redacted.omittedReason;
+        if (redacted.body) this.bodyBytes += Buffer.byteLength(redacted.body);
+      }
+      this.networkEvents.push(event);
+      this.requestEvents.set(request2, event);
+    });
+    this.page.on("response", (response) => this.updateResponse(response));
+    this.page.on("requestfailed", (request2) => {
+      const event = this.requestEvents.get(request2);
+      if (!event) return;
+      event.failureReason = request2.failure()?.errorText ?? "request_failed";
+      event.durationMs = Math.max(0, offset() - (this.requestStart.get(request2) ?? offset()));
+      pushTimeline({ offsetMs: event.offsetMs, type: "network", label: `${event.method} ${event.url} \u2192 ${event.failureReason}`, severity: "error" });
+    });
+    this.page.on("requestfinished", async (request2) => {
+      const response = await request2.response();
+      if (response) await this.captureResponseBody(response);
+    });
+  }
+  updateResponse(response) {
+    const event = this.requestEvents.get(response.request());
+    if (!event) return;
+    event.status = response.status();
+    event.mimeType = response.headers()["content-type"];
+    event.durationMs = Math.max(0, Date.now() - this.startedAt.getTime() - event.offsetMs);
+    event.transferSize = Number(response.headers()["content-length"] ?? 0) || void 0;
+    if (response.status() >= 400) this.timelineEvents.push({ id: `time_${this.timelineEvents.length + 1}`, offsetMs: event.offsetMs, type: "network", label: `${event.method} ${event.url} \u2192 ${response.status()}`, severity: "error" });
+  }
+  async captureResponseBody(response) {
+    if (!this.captureNetworkBodies || this.bodyBytes >= 1e7) {
+      if (this.bodyBytes >= 1e7) this.truncated = true;
+      return;
+    }
+    const event = this.requestEvents.get(response.request());
+    if (!event) return;
+    try {
+      const body = await response.text();
+      const redacted = redactBody(body, response.headers()["content-type"]);
+      event.responseBody = redacted.body;
+      event.bodyOmittedReason ??= redacted.omittedReason;
+      if (redacted.body) this.bodyBytes += Buffer.byteLength(redacted.body);
+    } catch {
+      event.bodyOmittedReason ??= "body_unavailable";
+    }
+  }
+};
+async function launchManaged(options) {
+  const port = await getAvailablePort();
+  const profileDirectory = await mkdtemp(join3(tmpdir2(), "rill-chrome-"));
+  const executable = findChromeExecutable();
+  const args = [
+    `--remote-debugging-port=${port}`,
+    "--remote-debugging-address=127.0.0.1",
+    `--user-data-dir=${profileDirectory}`,
+    `--window-size=${options.width},${options.height}`,
+    "--no-first-run",
+    "--no-default-browser-check",
+    "--disable-background-networking",
+    "--disable-component-update",
+    "--disable-sync",
+    "--metrics-recording-only",
+    ...options.headed ? [] : ["--headless=new", "--hide-scrollbars"],
+    "about:blank"
+  ];
+  const browserProcess = spawn3(executable, args, { stdio: ["ignore", "ignore", "pipe"], detached: false });
+  const cdpUrl = `http://127.0.0.1:${port}`;
+  await waitForCdp(cdpUrl, browserProcess);
+  const browser = await chromium.connectOverCDP(cdpUrl, { artifactsDir: options.outputDirectory, isLocal: true });
+  const context = browser.contexts()[0];
+  const page = context.pages()[0] ?? await context.newPage();
+  await page.setViewportSize({ width: options.width, height: options.height });
+  return { cdpUrl, browser, context, page, browserProcess, profileDirectory };
+}
+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));
+  const address = server.address();
+  if (!address || typeof address === "string") throw new Error("Could not allocate a browser debugging port.");
+  const port = address.port;
+  await new Promise((resolve) => server.close(() => resolve()));
+  return port;
+}
+async function waitForCdp(cdpUrl, browserProcess) {
+  const deadline = Date.now() + 15e3;
+  while (Date.now() < deadline) {
+    if (browserProcess.exitCode !== null) throw new Error(`Chrome exited before its CDP endpoint became available (${browserProcess.exitCode}).`);
+    try {
+      const response = await fetch(`${cdpUrl}/json/version`);
+      if (response.ok) return;
+    } catch {
+    }
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  browserProcess.kill("SIGTERM");
+  throw new Error("Timed out waiting for Chrome DevTools Protocol.");
+}
+
+// ../recorder/src/daemon.ts
+var sessions = /* @__PURE__ */ new Map();
+var lastActivity = Date.now();
+async function runDaemon() {
+  const socketPath = daemonSocketPath();
+  await mkdir3(dirname(socketPath), { recursive: true, mode: 448 });
+  await mkdir3(recordingTempRoot(), { recursive: true, mode: 448 });
+  await restoreRecoverableSessions();
+  await unlink(socketPath).catch((error) => {
+    if (error.code !== "ENOENT") throw error;
+  });
+  const server = createServer2((request2, response) => void route(request2, response));
+  server.listen(socketPath, () => process.platform !== "win32" && import("fs/promises").then(({ chmod }) => chmod(socketPath, 384)));
+  const idleTimer = setInterval(() => {
+    const hasActiveSession = [...sessions.values()].some((entry) => entry.state === "recording" || entry.state === "finalizing");
+    if (!hasActiveSession && Date.now() - lastActivity > 5 * 6e4) server.close(() => process.exit(0));
+  }, 3e4);
+  idleTimer.unref();
+  const close = () => {
+    clearInterval(idleTimer);
+    server.close();
+    void unlink(socketPath).catch(() => void 0);
+  };
+  process.once("SIGTERM", close);
+  process.once("SIGINT", close);
+}
+async function route(request2, response) {
+  lastActivity = Date.now();
+  const url = new URL(request2.url ?? "/", "http://daemon.local");
+  if (request2.method === "GET" && url.pathname === "/health") return json(response, 200, { ok: true, pid: process.pid });
+  if (request2.method === "POST" && url.pathname === "/sessions") {
+    if ([...sessions.values()].filter((entry) => entry.state === "recording").length >= 2) return json(response, 429, { error: { code: "quota_exceeded", message: "This recorder already has two active sessions." } });
+    try {
+      const input = await readJson(request2);
+      if (!input.recordingId) return json(response, 400, { error: { code: "validation_failed", message: "recordingId is required." } });
+      const outputDirectory = join4(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" };
+      sessions.set(input.recordingId, entry);
+      const maxTimer = setTimeout(() => void finalizeEntry(entry, "max_duration"), (input.maxDurationSeconds ?? 600) * 1e3 + 250);
+      maxTimer.unref();
+      await persistState();
+      return json(response, 201, session.status());
+    } catch (error) {
+      return json(response, 500, { error: { code: "browser_unavailable", message: error instanceof Error ? error.message : "Could not start recording." } });
+    }
+  }
+  const match = url.pathname.match(/^\/sessions\/([^/]+)(?:\/(stop))?$/);
+  if (match) {
+    const entry = sessions.get(decodeURIComponent(match[1]));
+    if (!entry) return json(response, 404, { error: { code: "recording_not_found", message: "The local recording session was not found." } });
+    if (request2.method === "GET" && !match[2]) return json(response, 200, serializeEntry(entry));
+    if (request2.method === "POST" && match[2] === "stop") {
+      if (entry.state === "ready") return json(response, 200, serializeEntry(entry));
+      await finalizeEntry(entry, "agent_request");
+      return json(response, entry.result ? 200 : 500, serializeEntry(entry));
+    }
+  }
+  return json(response, 404, { error: { code: "recording_not_found", message: "Unknown recorder route." } });
+}
+async function finalizeEntry(entry, reason) {
+  if (entry.state === "ready" || entry.state === "failed") return;
+  entry.state = "finalizing";
+  try {
+    if (!entry.session) throw new Error("This recovered draft was not fully finalized. Start a new recording or purge the draft.");
+    entry.result = await entry.session.stop(reason);
+    entry.state = "ready";
+  } catch (error) {
+    entry.state = "failed";
+    entry.error = error instanceof Error ? error.message : "The recording could not be finalized.";
+  }
+  await persistState();
+}
+function serializeEntry(entry) {
+  return { ...entry.base, status: entry.state, result: entry.result, error: entry.error };
+}
+async function restoreRecoverableSessions() {
+  try {
+    const value = JSON.parse(await readFile(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 });
+    }
+  } catch {
+  }
+}
+async function persistState() {
+  const state = Object.fromEntries([...sessions.entries()].map(([id, entry]) => [id, serializeEntry(entry)]));
+  await writeFile2(daemonStatePath(), `${JSON.stringify(state, null, 2)}
+`, { mode: 384 });
+}
+async function readJson(request2) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of request2) {
+    const buffer = Buffer.from(chunk);
+    size += buffer.length;
+    if (size > 1e6) throw new Error("Request body exceeds 1 MB.");
+    chunks.push(buffer);
+  }
+  return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+}
+function json(response, status, value) {
+  response.writeHead(status, { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store" });
+  response.end(JSON.stringify(value));
+}
+
+// src/control-plane.ts
+import { createReadStream } from "fs";
+import { readFile as readFile2, stat } from "fs/promises";
+import { Upload } from "tus-js-client";
+var ControlPlaneClient = class {
+  constructor(apiUrl, token) {
+    this.apiUrl = apiUrl;
+    this.token = token;
+  }
+  health() {
+    return this.request("/api/health", {}, false);
+  }
+  agentSession() {
+    return this.request("/api/agent/session");
+  }
+  createRecording(input) {
+    return this.request("/api/recordings", { method: "POST", body: JSON.stringify(input) });
+  }
+  provisionVideo(recordingId, input) {
+    return this.request(`/api/recordings/${recordingId}/video-upload`, { method: "POST", body: JSON.stringify(input) });
+  }
+  recordingStatus(recordingId) {
+    return this.request(`/api/recordings/${recordingId}`);
+  }
+  async waitUntilPlayable(recordingId, timeoutMs = 10 * 6e4) {
+    const deadline = Date.now() + timeoutMs;
+    let intervalMs = 1e3;
+    while (Date.now() < deadline) {
+      const recording = await this.recordingStatus(recordingId);
+      if (recording.status === "ready" && recording.shareUrl) {
+        return { ...recording, shareUrl: new URL(recording.shareUrl, this.apiUrl).toString() };
+      }
+      if (recording.status === "failed") throw new Error(`processing_failed: ${recording.failure_message ?? "Cloudflare Stream could not process the recording."}`);
+      process.stderr.write(`\rprocessing ${recording.status.padEnd(12)}`);
+      await new Promise((resolve) => setTimeout(resolve, intervalMs));
+      intervalMs = Math.min(5e3, Math.round(intervalMs * 1.4));
+    }
+    throw new Error("processing_failed: Timed out waiting for the recording to become playable. Run `rill record status <recording-id>` to continue checking.");
+  }
+  async uploadVideo(uploadUrl, filePath) {
+    const file = await stat(filePath);
+    if (uploadUrl.startsWith(this.apiUrl)) {
+      const response = await fetch(uploadUrl, { method: "PUT", headers: { "Content-Length": String(file.size) }, body: createReadStream(filePath), duplex: "half" });
+      if (!response.ok) throw new Error(`Video upload failed (${response.status}).`);
+      return;
+    }
+    await new Promise((resolve, reject) => {
+      const upload = new Upload(createReadStream(filePath), {
+        uploadUrl,
+        uploadSize: file.size,
+        retryDelays: [0, 1e3, 3e3, 5e3, 1e4],
+        removeFingerprintOnSuccess: true,
+        onError: reject,
+        onSuccess: () => resolve(),
+        onProgress: (sent, total) => process.stderr.write(`\ruploading ${Math.round(sent / total * 100)}%`)
+      });
+      upload.start();
+    });
+    process.stderr.write("\n");
+  }
+  async uploadDiagnostics(recordingId, filePath, summary) {
+    const body = await readFile2(filePath);
+    return this.request(`/api/recordings/${recordingId}/diagnostics`, { method: "PUT", headers: { "Content-Encoding": "gzip", "Content-Type": "application/x-ndjson", "Content-Length": String(body.length), "X-Rill-Summary": JSON.stringify(summary) }, body });
+  }
+  createDeviceAuthorization(input) {
+    return this.request("/api/device/authorizations", { method: "POST", body: JSON.stringify(input) }, false);
+  }
+  pollDeviceAuthorization(deviceCode) {
+    return this.request("/api/device/token", { method: "POST", body: JSON.stringify({ deviceCode }) }, false);
+  }
+  inspect(shareUrl) {
+    const url = new URL(shareUrl);
+    const slug = url.pathname.split("/").filter(Boolean).at(-1);
+    if (!slug) throw new Error("The share URL does not contain a slug.");
+    return fetch(`${url.origin}/api/public/shares/${encodeURIComponent(slug)}/context`, { headers: { Accept: "application/json" } }).then(async (response) => {
+      if (!response.ok) throw new Error(`Could not inspect the share link (${response.status}).`);
+      return response.json();
+    });
+  }
+  async request(path, init = {}, authenticated = true) {
+    const headers = new Headers(init.headers);
+    if (init.body && !headers.has("Content-Type")) headers.set("Content-Type", "application/json");
+    if (authenticated) {
+      if (!this.token) throw new Error("authentication_required: Run `rill login` or set RILL_TOKEN.");
+      headers.set("Authorization", `Bearer ${this.token}`);
+    }
+    const response = await fetch(`${this.apiUrl}${path}`, { ...init, headers });
+    const value = await response.json().catch(() => null);
+    if (!response.ok) throw new Error([value?.error?.code, value?.error?.message, value?.error?.recovery].filter(Boolean).join(": ") || `Request failed (${response.status}).`);
+    return value;
+  }
+};
+
+// src/keychain.ts
+import { spawn as spawn4 } from "child_process";
+var service = "rill";
+async function saveCredential(apiUrl, token) {
+  if (process.platform === "darwin") {
+    await run("security", ["add-generic-password", "-U", "-a", apiUrl, "-s", service, "-w", token]);
+    return;
+  }
+  if (process.platform === "linux") {
+    await run("secret-tool", ["store", "--label=Rill agent credential", "service", service, "api-url", apiUrl], token);
+    return;
+  }
+  throw new Error("OS keychain storage is not supported on this platform yet. Use RILL_TOKEN.");
+}
+async function loadCredential(apiUrl) {
+  if (process.env.RILL_TOKEN) return process.env.RILL_TOKEN;
+  try {
+    if (process.platform === "darwin") return (await run("security", ["find-generic-password", "-a", apiUrl, "-s", service, "-w"])).trim();
+    if (process.platform === "linux") return (await run("secret-tool", ["lookup", "service", service, "api-url", apiUrl])).trim();
+  } catch {
+    return null;
+  }
+  return null;
+}
+function run(command, args, input) {
+  return new Promise((resolve, reject) => {
+    const child = spawn4(command, args, { stdio: ["pipe", "pipe", "pipe"] });
+    const stdout = [];
+    const stderr = [];
+    child.stdout.on("data", (chunk) => stdout.push(Buffer.from(chunk)));
+    child.stderr.on("data", (chunk) => stderr.push(Buffer.from(chunk)));
+    child.once("error", reject);
+    child.once("exit", (code) => code === 0 ? resolve(Buffer.concat(stdout).toString("utf8")) : reject(new Error(Buffer.concat(stderr).toString("utf8").trim() || `${command} exited with ${code}.`)));
+    if (input) child.stdin.end(input);
+    else child.stdin.end();
+  });
+}
+
+// src/output.ts
+function emit(value, pretty = false) {
+  process.stdout.write(`${JSON.stringify(value, null, pretty ? 2 : void 0)}
+`);
+}
+function fail(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  const [candidate] = message.split(":", 1);
+  const knownCodes = /* @__PURE__ */ new Set(["authentication_required", "scope_denied", "quota_exceeded", "browser_unavailable", "recording_not_found", "upload_interrupted", "processing_failed", "share_revoked", "validation_failed"]);
+  emit({ error: { code: knownCodes.has(candidate) ? candidate : "internal_error", message } });
+  process.exitCode = 1;
+}
+
+// src/doctor.ts
+import { spawn as spawn5 } from "child_process";
+
+// src/version.ts
+import { createRequire } from "module";
+var packageJson = createRequire(import.meta.url)("../package.json");
+var CLI_VERSION = packageJson.version;
+
+// src/doctor.ts
+var defaultDependencies = {
+  nodeVersion: process.version,
+  cliVersion: CLI_VERSION,
+  chromePath: findChromeExecutable(),
+  ffmpegPath: process.env.RILL_FFMPEG ?? "ffmpeg",
+  commandVersion,
+  loadCredential,
+  health: (apiUrl) => new ControlPlaneClient(apiUrl, null).health(),
+  agentSession: (apiUrl, token) => new ControlPlaneClient(apiUrl, token).agentSession()
+};
+async function runDoctor(apiUrl, overrides = {}) {
+  const dependencies = { ...defaultDependencies, ...overrides };
+  const checks = [];
+  if (compareVersions(normalizeVersion(dependencies.nodeVersion), "22.0.0") >= 0) {
+    checks.push({ name: "node", status: "pass", message: `Node.js ${dependencies.nodeVersion} is supported.`, version: dependencies.nodeVersion });
+  } else {
+    checks.push({ name: "node", status: "fail", message: `Node.js ${dependencies.nodeVersion} is unsupported.`, version: dependencies.nodeVersion, recovery: "Install Node.js 22 or newer, then reinstall the Rill CLI." });
+  }
+  let health = null;
+  try {
+    health = await dependencies.health(apiUrl);
+    if (!health.ok || health.service !== "rill") throw new Error("The endpoint did not identify itself as Rill.");
+    checks.push({ name: "api", status: "pass", message: `Rill API is reachable at ${apiUrl}.` });
+  } catch (error) {
+    checks.push({ name: "api", status: "fail", message: `Rill API is unreachable: ${errorMessage(error)}`, recovery: `Check the network and API URL, then rerun \`rill --api-url ${apiUrl} doctor\`.` });
+  }
+  if (!health?.minimumCliVersion || !health.recommendedCliVersion) {
+    checks.push({ name: "cli_version", status: "fail", message: `CLI ${dependencies.cliVersion} could not be checked against the API compatibility policy.`, version: dependencies.cliVersion, recovery: "Deploy a Rill API that advertises minimumCliVersion and recommendedCliVersion." });
+  } else if (compareVersions(dependencies.cliVersion, health.minimumCliVersion) < 0) {
+    checks.push({ name: "cli_version", status: "fail", message: `CLI ${dependencies.cliVersion} is older than the minimum supported version ${health.minimumCliVersion}.`, version: dependencies.cliVersion, recovery: `Run \`npm install --global @runalabs/rill-cli@${health.recommendedCliVersion}\`.` });
+  } else if (compareVersions(dependencies.cliVersion, health.recommendedCliVersion) !== 0) {
+    checks.push({ name: "cli_version", status: "warn", message: `CLI ${dependencies.cliVersion} is supported; ${health.recommendedCliVersion} is recommended.`, version: dependencies.cliVersion, recovery: `Run \`npm install --global @runalabs/rill-cli@${health.recommendedCliVersion}\`.` });
+  } else {
+    checks.push({ name: "cli_version", status: "pass", message: `CLI ${dependencies.cliVersion} is the recommended version.`, version: dependencies.cliVersion });
+  }
+  if (!health) {
+    checks.push({ name: "authentication", status: "skip", message: "Authentication was not checked because the API is unreachable.", recovery: `Restore API reachability, then run \`rill --api-url ${apiUrl} doctor\` again.` });
+  } else {
+    const token = await dependencies.loadCredential(apiUrl);
+    if (!token) {
+      checks.push({ name: "authentication", status: "fail", message: "No Rill agent credential is available.", recovery: `Run \`rill --api-url ${apiUrl} login\` or set RILL_TOKEN.` });
+    } else {
+      try {
+        const session = await dependencies.agentSession(apiUrl, token);
+        checks.push({ name: "authentication", status: "pass", message: `Credential is valid with ${session.scopes.length} scope${session.scopes.length === 1 ? "" : "s"}.` });
+      } catch (error) {
+        checks.push({ name: "authentication", status: "fail", message: `Credential validation failed: ${errorMessage(error)}`, recovery: `Run \`rill --api-url ${apiUrl} login\` to authorize a fresh credential.` });
+      }
+    }
+  }
+  checks.push(await executableCheck("chrome", dependencies.chromePath, ["--version"], dependencies.commandVersion, "Install Google Chrome or Chromium, or set RILL_CHROME_PATH to its executable."));
+  checks.push(await executableCheck("ffmpeg", dependencies.ffmpegPath, ["-version"], dependencies.commandVersion, process.platform === "darwin" ? "Install ffmpeg with `brew install ffmpeg`, or set RILL_FFMPEG." : "Install ffmpeg using the system package manager, or set RILL_FFMPEG."));
+  return { schemaVersion: 1, status: checks.some((check) => check.status === "fail") ? "error" : "ok", apiUrl, checks };
+}
+async function executableCheck(name, path, args, run2, recovery) {
+  try {
+    const version = firstLine(await run2(path, args));
+    return { name, status: "pass", message: `${name === "chrome" ? "Chrome/Chromium" : "ffmpeg"} is available.`, version, path };
+  } catch (error) {
+    return { name, status: "fail", message: `${name === "chrome" ? "Chrome/Chromium" : "ffmpeg"} is unavailable: ${errorMessage(error)}`, path, recovery };
+  }
+}
+function commandVersion(command, args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn5(command, args, { stdio: ["ignore", "pipe", "pipe"] });
+    const stdout = [];
+    const stderr = [];
+    const timeout = setTimeout(() => {
+      child.kill("SIGTERM");
+      reject(new Error("version check timed out"));
+    }, 5e3);
+    child.stdout.on("data", (chunk) => stdout.push(Buffer.from(chunk)));
+    child.stderr.on("data", (chunk) => stderr.push(Buffer.from(chunk)));
+    child.once("error", (error) => {
+      clearTimeout(timeout);
+      reject(error);
+    });
+    child.once("exit", (code) => {
+      clearTimeout(timeout);
+      const output = `${Buffer.concat(stdout).toString("utf8")}
+${Buffer.concat(stderr).toString("utf8")}`.trim();
+      if (code === 0) resolve(output);
+      else reject(new Error(output || `${command} exited with ${code}`));
+    });
+  });
+}
+function normalizeVersion(version) {
+  return version.replace(/^v/, "").split("-")[0];
+}
+function compareVersions(left, right) {
+  const leftParts = normalizeVersion(left).split(".").map(Number);
+  const rightParts = normalizeVersion(right).split(".").map(Number);
+  for (let index = 0; index < Math.max(leftParts.length, rightParts.length); index += 1) {
+    const difference = (leftParts[index] ?? 0) - (rightParts[index] ?? 0);
+    if (difference !== 0) return difference;
+  }
+  return 0;
+}
+function firstLine(value) {
+  return value.split(/\r?\n/, 1)[0].trim();
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// src/cli.ts
+var program = new Command();
+program.name("rill").description("Record, inspect, and share agent browser runs.").version(CLI_VERSION).option("--api-url <url>", "Rill control plane", process.env.RILL_API_URL ?? "https://rill-staging.tight-shadow-8e12.workers.dev").option("--pretty", "Pretty-print JSON output", false);
+program.command("daemon", { hidden: true }).action(() => runDaemon());
+program.command("doctor").description("Validate Rill prerequisites before recording.").action(async () => {
+  const options = program.opts();
+  const result = await runDoctor(options.apiUrl);
+  emit(result, options.pretty);
+  if (result.status === "error") process.exitCode = 1;
+});
+program.command("login").description("Authorize this agent using a human-approved device code.").action(async () => {
+  const options = program.opts();
+  const client = new ControlPlaneClient(options.apiUrl, null);
+  const authorization = await client.createDeviceAuthorization({ deviceName: `${hostname()} \xB7 ${process.platform}` });
+  process.stderr.write(`Open ${authorization.verificationUri} and enter ${authorization.userCode}
+`);
+  const deadline = Date.now() + authorization.expiresIn * 1e3;
+  while (Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, authorization.interval * 1e3));
+    const result = await client.pollDeviceAuthorization(authorization.deviceCode);
+    if (result.status === "pending") continue;
+    if (result.status !== "approved" || !result.token) throw new Error(`Device authorization ${result.status}.`);
+    await saveCredential(options.apiUrl, result.token);
+    emit({ schemaVersion: 1, status: "authenticated", expiresAt: result.expiresAt, apiUrl: options.apiUrl }, options.pretty);
+    return;
+  }
+  throw new Error("Device authorization expired.");
+});
+var record = program.command("record").description("Manage a browser recording session.");
+record.command("start").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) => {
+  const options = program.opts();
+  const token = await loadCredential(options.apiUrl);
+  const client = new ControlPlaneClient(options.apiUrl, token);
+  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 });
+  await ensureDaemon(process.argv[1]);
+  const local = await startRecording({ recordingId: remote.recordingId, url: commandOptions.url, cdpUrl: commandOptions.cdpUrl, headed: Boolean(commandOptions.headed), width, height, maxDurationSeconds: Number(commandOptions.maxDuration), captureNetworkBodies: remote.bodyCaptureEnabled });
+  emit({ schemaVersion: 1, recordingId: remote.recordingId, status: local.status, cdpUrl: local.cdpUrl, bodyCaptureEnabled: remote.bodyCaptureEnabled, maxDurationSeconds: Number(commandOptions.maxDuration) }, options.pretty);
+});
+record.command("stop").argument("<recording-id>").option("--no-wait").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 token = await loadCredential(options.apiUrl);
+  const client = new ControlPlaneClient(options.apiUrl, token);
+  const video = await stat2(local.result.videoPath);
+  const provisioned = await client.provisionVideo(recordingId, { sizeBytes: video.size, filename: basename(local.result.videoPath) });
+  await Promise.all([client.uploadVideo(provisioned.uploadUrl, local.result.videoPath), client.uploadDiagnostics(recordingId, local.result.diagnosticsPath, local.result.diagnostics)]);
+  const remote = commandOptions.wait === false ? null : await client.waitUntilPlayable(recordingId);
+  if (remote) process.stderr.write("\n");
+  const result = { schemaVersion: 1, recordingId, status: remote ? "ready" : "processing", shareUrl: remote?.shareUrl ?? null, durationSeconds: local.result.durationSeconds, stoppedReason: local.result.stoppedReason, diagnostics: local.result.diagnostics };
+  emit(result, options.pretty);
+  if (remote) await rm2(dirname2(local.result.videoPath), { recursive: true, force: true });
+});
+record.command("status").argument("<recording-id>").action(async (recordingId) => {
+  const options = program.opts();
+  await ensureDaemon(process.argv[1]);
+  emit({ schemaVersion: 1, ...await recordingStatus(recordingId) }, options.pretty);
+});
+program.command("upload").argument("<video-file>").option("--title <title>").option("--no-wait").action(async (videoFile, commandOptions) => {
+  const options = program.opts();
+  const token = await loadCredential(options.apiUrl);
+  const client = new ControlPlaneClient(options.apiUrl, token);
+  const file = await stat2(videoFile);
+  const recording = await client.createRecording({ title: commandOptions.title ?? basename(videoFile), sourceUrl: null });
+  const upload = await client.provisionVideo(recording.recordingId, { sizeBytes: file.size, filename: basename(videoFile) });
+  await client.uploadVideo(upload.uploadUrl, videoFile);
+  const remote = commandOptions.wait === false ? null : await client.waitUntilPlayable(recording.recordingId);
+  if (remote) process.stderr.write("\n");
+  emit({ schemaVersion: 1, recordingId: recording.recordingId, status: remote ? "ready" : "processing", shareUrl: remote?.shareUrl ?? null, diagnosticsAvailable: false }, options.pretty);
+});
+program.command("inspect").argument("<share-url>").action(async (shareUrl) => {
+  const options = program.opts();
+  emit(await new ControlPlaneClient(options.apiUrl, null).inspect(shareUrl), options.pretty);
+});
+var drafts = program.command("drafts");
+drafts.command("list").action(async () => {
+  const options = program.opts();
+  const root = process.env.RILL_TEMP ?? `${process.env.TMPDIR ?? "/tmp"}/rill-recordings`;
+  const names = await readdir(root).catch(() => []);
+  emit({ schemaVersion: 1, drafts: names }, options.pretty);
+});
+drafts.command("purge").action(async () => {
+  const options = program.opts();
+  const root = process.env.RILL_TEMP ?? `${process.env.TMPDIR ?? "/tmp"}/rill-recordings`;
+  const names = await readdir(root).catch(() => []);
+  let purged = 0;
+  for (const name of names) {
+    const path = `${root}/${name}`;
+    const metadata = await stat2(path);
+    if (Date.now() - metadata.mtimeMs > 24 * 60 * 60 * 1e3) {
+      await rm2(path, { recursive: true, force: true });
+      purged += 1;
+    }
+  }
+  emit({ schemaVersion: 1, purged }, options.pretty);
+});
+program.parseAsync().catch(fail);

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@runalabs/rill-cli",
+  "version": "0.1.0",
+  "description": "Record, inspect, and share agent-controlled browser runs with Rill.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RunaLabsDev/rill-web.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/RunaLabsDev/rill-web#readme",
+  "bugs": "https://github.com/RunaLabsDev/rill-web/issues",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "rill": "dist/cli.js"
+  },
+  "exports": {
+    ".": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "prepack": "npm run build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "commander": "^14.0.0",
+    "playwright-core": "^1.55.0",
+    "tus-js-client": "^4.3.1"
+  },
+  "devDependencies": {
+    "@rill/contracts": "*",
+    "@rill/recorder": "*",
+    "@types/node": "^24.3.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  }
+}