@runalabs/rill-cli 0.1.4 → 0.1.5

package/README.md

@@ -205,15 +205,19 @@ Diagnostic redaction targets cookies, credential headers, URL query values, frag
 
 ## Optional agent feedback
 
-After `record stop`, compatible hosts may receive `feedbackRequested: true` and a structured `suggestedAction`. When requested, agents should submit a short Rill-specific review if practical. Workspace opt-in pre-authorizes it; feedback is optional and must not delay or affect the recording result.
+Feedback begins with `rill doctor` and `rill record start`. When the workspace enables it, their JSON includes `feedbackRequested: true` and a `feedbackBrief` asking the agent to observe what went well, confusion or friction, and possible improvements throughout setup and the run. Review only Rill and report observed experience, not invented praise or issues.
+
+At completion or abandonment, `record stop` still returns the recommended, pre-authorized `suggestedAction`. Submit a short review if practical:
 
 ```sh
-rill feedback submit <recording-id> --outcome succeeded --improvement "Make processing progress clearer"
+rill feedback submit <recording-id> --outcome succeeded --helped "The CDP URL was easy to connect to" --friction "Upload progress was unclear" --improvement "Explain upload and processing stages"
 ```
 
-`--outcome` must be `succeeded`, `failed`, or `abandoned`. Include at least one of `--helped`, `--friction`, or `--improvement`. Omit credentials, personal data, and copied page content. Feedback goes to Rill's operators and is not shown on public evidence pages.
+Startup errors retain the brief under `error.details`, with the recording ID when one was reserved. If no recording exists, submit setup feedback without an ID using `--outcome failed` or `--outcome abandoned`. Successful submission returns `feedbackStatus: "submitted"` and the recording ID (null for setup-only feedback).
+
+Only use `--no-feedback` when the user explicitly requests it, including in demos and tests. Respect the workspace preference. Feedback is optional, pre-authorized, and must not delay or affect the recording result. Authentication or connectivity failures may prevent feedback; preserve the original task result.
 
-Skip feedback when it is not requested. Use `rill record stop <recording-id> --no-feedback` to opt out for one run. A feedback failure must not delay returning the share URL.
+Setup-only feedback requires the API endpoint `POST /api/feedback` and migration `0012_setup_feedback.sql`. Deploy the migration and API before distributing this CLI change. Existing recording feedback remains compatible.
 
 ## Update and uninstall
 

package/dist/cli.js

@@ -601,7 +601,7 @@ var ControlPlaneClient = class {
     return this.request("/api/health", {}, false);
   }
   agentSession() {
-    return this.request("/api/agent/session");
+    return this.request("/api/agent/session", { signal: AbortSignal.timeout(5e3) });
   }
   reportCliCommand(input) {
     return this.request("/api/analytics/cli-command", { method: "POST", body: JSON.stringify(input) });
@@ -622,7 +622,7 @@ var ControlPlaneClient = class {
     });
   }
   submitRecordingFeedback(recordingId, input) {
-    return this.request(`/api/recordings/${recordingId}/feedback`, {
+    return this.request(recordingId ? `/api/recordings/${recordingId}/feedback` : "/api/feedback", {
       method: "POST",
       body: JSON.stringify(input)
     });
@@ -794,6 +794,62 @@ function fail(error) {
   process.exitCode = 1;
 }
 
+// src/feedback-protocol.ts
+function suggestedFeedbackAction(recordingId) {
+  return {
+    type: "rill.feedback.submit",
+    recommended: true,
+    authorizedBy: "workspace_opt_in",
+    confirmationRequired: false,
+    failurePolicy: "non_blocking",
+    recordingId
+  };
+}
+function recordingFeedbackFields(recordingId, feedbackRequested) {
+  return feedbackRequested ? { feedbackRequested: true, suggestedAction: suggestedFeedbackAction(recordingId) } : { feedbackRequested: false };
+}
+function feedbackSubmissionReceipt(recordingId) {
+  return {
+    schemaVersion: 1,
+    recordingId,
+    feedbackStatus: "submitted"
+  };
+}
+function runFeedbackFields(feedbackEnabled, recordingId = null) {
+  return feedbackEnabled ? {
+    feedbackRequested: true,
+    feedbackBrief: {
+      authorizedBy: "workspace_opt_in",
+      confirmationRequired: false,
+      failurePolicy: "non_blocking",
+      recordingId,
+      instruction: "Observe your Rill experience throughout setup and the run. At completion or abandonment, submit a short factual review if practical. Feedback is optional and must not delay or affect the recording result. Only use --no-feedback when the user explicitly requests it.",
+      prompts: {
+        whatHelped: "What went well? Which Rill commands, browser setup steps, outputs, or recovery guidance helped?",
+        friction: "Where did you get confused, get stuck, or need to guess? Consider prerequisites, starting or connecting to the browser, commands, diagnostics, uploads, and recovery.",
+        improvement: "What possible improvements would make Rill easier or more useful? Prioritize actionable ideas grounded in this run."
+      },
+      submitCommand: `rill feedback submit${recordingId ? ` ${recordingId}` : ""} --outcome <${recordingId ? "succeeded|failed|abandoned" : "failed|abandoned"}> --helped <text> --friction <text> --improvement <text>`,
+      scope: "Review Rill, not the target website. Report only observed experience; do not invent problems or praise. Exclude credentials, personal data, and copied page content."
+    }
+  } : { feedbackRequested: false };
+}
+async function withRunFeedback(session, start) {
+  const enabled = await session().then((value) => value.agentFeedbackEnabled).catch(() => false);
+  let recordingId = null;
+  try {
+    const result = await start((id) => {
+      recordingId = id;
+    });
+    return { ...result, ...runFeedbackFields(enabled, result.recordingId) };
+  } catch (cause) {
+    const error = cause instanceof Error ? cause : new Error(String(cause));
+    const structured = error;
+    structured.details = { ...structured.details, ...runFeedbackFields(enabled, recordingId) };
+    throw error;
+  }
+}
+
 // src/doctor.ts
 import { spawn as spawn5 } from "child_process";
 
@@ -816,6 +872,7 @@ var defaultDependencies = {
 async function runDoctor(apiUrl, overrides = {}) {
   const dependencies = { ...defaultDependencies, ...overrides };
   const checks = [];
+  let feedbackEnabled = false;
   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 {
@@ -849,6 +906,7 @@ async function runDoctor(apiUrl, overrides = {}) {
     } else {
       try {
         const session = await dependencies.agentSession(apiUrl, token);
+        feedbackEnabled = session.agentFeedbackEnabled;
         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.` });
@@ -857,7 +915,7 @@ async function runDoctor(apiUrl, overrides = {}) {
   }
   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 };
+  return { schemaVersion: 1, status: checks.some((check) => check.status === "fail") ? "error" : "ok", apiUrl, checks, ...runFeedbackFields(feedbackEnabled) };
 }
 async function executableCheck(name, path, args, run2, recovery) {
   try {
@@ -945,28 +1003,6 @@ function controlPlaneUrl(environmentUrl) {
   return environmentUrl ?? PRODUCTION_API_URL;
 }
 
-// src/feedback-protocol.ts
-function suggestedFeedbackAction(recordingId) {
-  return {
-    type: "rill.feedback.submit",
-    recommended: true,
-    authorizedBy: "workspace_opt_in",
-    confirmationRequired: false,
-    failurePolicy: "non_blocking",
-    recordingId
-  };
-}
-function recordingFeedbackFields(recordingId, feedbackRequested) {
-  return feedbackRequested ? { feedbackRequested: true, suggestedAction: suggestedFeedbackAction(recordingId) } : { feedbackRequested: false };
-}
-function feedbackSubmissionReceipt(recordingId) {
-  return {
-    schemaVersion: 1,
-    recordingId,
-    feedbackStatus: "submitted"
-  };
-}
-
 // 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", controlPlaneUrl(process.env.RILL_API_URL)).option("--pretty", "Pretty-print JSON output", false);
@@ -1001,26 +1037,30 @@ record.command("start").option("--url <url>").option("--title <title>").option("
   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 });
-  const local = await startRecordingWithCompensation(remote, {
-    startLocal: async () => {
-      await ensureDaemon(process.argv[1]);
-      return startRecording({ recordingId: remote.recordingId, url: commandOptions.url, cdpUrl: commandOptions.cdpUrl, headed: Boolean(commandOptions.headed), width, height, maxDurationSeconds: Number(commandOptions.maxDuration), captureNetworkBodies: remote.bodyCaptureEnabled });
-    },
-    cancelRemote: (recordingId, reason) => client.cancelRecording(recordingId, reason)
+  const result = await withRunFeedback(() => client.agentSession(), async (rememberRecording) => {
+    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 });
+    rememberRecording(remote.recordingId);
+    const local = await startRecordingWithCompensation(remote, {
+      startLocal: async () => {
+        await ensureDaemon(process.argv[1]);
+        return startRecording({ recordingId: remote.recordingId, url: commandOptions.url, cdpUrl: commandOptions.cdpUrl, headed: Boolean(commandOptions.headed), width, height, maxDurationSeconds: Number(commandOptions.maxDuration), captureNetworkBodies: remote.bodyCaptureEnabled });
+      },
+      cancelRemote: (recordingId, reason) => client.cancelRecording(recordingId, reason)
+    });
+    await client.markRecordingStarted(remote.recordingId, {
+      cliVersion: CLI_VERSION,
+      os: process.platform,
+      arch: process.arch,
+      headed: Boolean(commandOptions.headed),
+      attached: Boolean(commandOptions.cdpUrl)
+    }).catch(() => void 0);
+    return { schemaVersion: 1, recordingId: remote.recordingId, status: local.status, cdpUrl: local.cdpUrl, bodyCaptureEnabled: remote.bodyCaptureEnabled, maxDurationSeconds: Number(commandOptions.maxDuration) };
   });
-  await client.markRecordingStarted(remote.recordingId, {
-    cliVersion: CLI_VERSION,
-    os: process.platform,
-    arch: process.arch,
-    headed: Boolean(commandOptions.headed),
-    attached: Boolean(commandOptions.cdpUrl)
-  }).catch(() => void 0);
-  emit({ schemaVersion: 1, recordingId: remote.recordingId, status: local.status, cdpUrl: local.cdpUrl, bodyCaptureEnabled: remote.bodyCaptureEnabled, maxDurationSeconds: Number(commandOptions.maxDuration) }, options.pretty);
+  emit(result, options.pretty);
 });
-record.command("stop").argument("<recording-id>").option("--no-wait").option("--no-feedback").action(async (recordingId, commandOptions) => {
+record.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);
@@ -1052,19 +1092,20 @@ record.command("stop").argument("<recording-id>").option("--no-wait").option("--
   if (remote) await rm2(dirname2(local.result.videoPath), { recursive: true, force: true });
 });
 var feedback = program.command("feedback").description("Submit a short Rill product review for a recorded run.");
-feedback.command("submit").argument("<recording-id>").requiredOption("--outcome <outcome>", "succeeded, failed, or abandoned").option("--helped <text>", "What helped during the run", "").option("--friction <text>", "What created friction during the run", "").option("--improvement <text>", "The single most useful Rill improvement", "").action(async (recordingId, commandOptions) => {
+feedback.command("submit").argument("[recording-id]", "Omit only when setup failed before a recording was created").requiredOption("--outcome <outcome>", "succeeded, failed, or abandoned").option("--helped <text>", "What went well or helped during setup and the run", "").option("--friction <text>", "What created friction during the run", "").option("--improvement <text>", "Possible Rill improvements, prioritized by usefulness", "").action(async (recordingId, commandOptions) => {
+  if (!recordingId && commandOptions.outcome === "succeeded") throw new Error("validation_failed: Setup feedback without a recording must have a failed or abandoned outcome.");
   if (!["succeeded", "failed", "abandoned"].includes(commandOptions.outcome)) throw new Error("validation_failed: Feedback outcome must be succeeded, failed, or abandoned.");
   if (![commandOptions.helped, commandOptions.friction, commandOptions.improvement].some((value) => value.trim())) throw new Error("validation_failed: Include at least one short feedback answer.");
   const options = program.opts();
   const token = await loadCredential(options.apiUrl);
   const client = new ControlPlaneClient(options.apiUrl, token);
-  await client.submitRecordingFeedback(recordingId, {
+  await client.submitRecordingFeedback(recordingId ?? null, {
     outcome: commandOptions.outcome,
     whatHelped: commandOptions.helped,
     friction: commandOptions.friction,
     improvement: commandOptions.improvement
   });
-  emit(feedbackSubmissionReceipt(recordingId), options.pretty);
+  emit(feedbackSubmissionReceipt(recordingId ?? null), options.pretty);
 });
 record.command("status").argument("<recording-id>").action(async (recordingId) => {
   const options = program.opts();

package/package.json

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