fix(action): retry cursor-agent with -p after empty chat failure

Add diagnostics (version, invocation mode, merged stderr) and README troubleshooting.

Author: PunGrumpy

.changeset/smoke-test-print-fallback.md

@@ -0,0 +1,5 @@
+---
+"cursor-action": patch
+---
+
+Retry `cursor-agent` with headless print mode (`-p`) when the primary `chat` invocation fails silently or looks like a CLI mismatch; collect `cursor-agent --version` and add job-summary diagnostics. Document CI troubleshooting in the README.

README.md

@@ -25,15 +25,15 @@
 
 ## Inputs
 
-| Input               | Required | Default             | Description                                                                                          |
-| ------------------- | -------- | ------------------- | ---------------------------------------------------------------------------------------------------- |
-| `api-key`           | ✅       | —                   | Your Cursor API key. Store as a secret.                                                              |
-| `prompt`            | ✅       | —                   | The prompt to pass to `cursor-agent`.                                                                |
-| `cursor-version`    | ❌       | `latest`            | Cursor CLI build to install. Use `latest` or an exact Cursor lab build id like `2026.03.20-44cb435`. |
-| `model`             | ❌       | `auto`              | Model for the agent to use.                                                                          |
-| `working-directory` | ❌       | `.`                 | Directory the agent operates in.                                                                     |
-| `permissions`       | ❌       | `read-only`         | Agent permissions: `read-only`, `read-write`, or `full`.                                             |
-| `timeout`           | ❌       | `300`               | Timeout in seconds before the agent is killed.                                                       |
+| Input               | Required | Default     | Description                                                                                          |
+| ------------------- | -------- | ----------- | ---------------------------------------------------------------------------------------------------- |
+| `api-key`           | ✅       | —           | Your Cursor API key. Store as a secret.                                                              |
+| `prompt`            | ✅       | —           | The prompt to pass to `cursor-agent`.                                                                |
+| `cursor-version`    | ❌       | `latest`    | Cursor CLI build to install. Use `latest` or an exact Cursor lab build id like `2026.03.20-44cb435`. |
+| `model`             | ❌       | `auto`      | Model for the agent to use.                                                                          |
+| `working-directory` | ❌       | `.`         | Directory the agent operates in.                                                                     |
+| `permissions`       | ❌       | `read-only` | Agent permissions: `read-only`, `read-write`, or `full`.                                             |
+| `timeout`           | ❌       | `300`       | Timeout in seconds before the agent is killed.                                                       |
 
 ## Outputs
 
@@ -125,6 +125,17 @@ The action caches the extracted Cursor CLI package across jobs using `@actions/c
 
 ---
 
+## Troubleshooting (CI / smoke tests)
+
+### `cursor-agent` exits with code 1 and little or no output
+
+- **API key & billing**: Ensure `CURSOR_API_KEY` is set and valid. Agent / headless features may require an eligible Cursor plan; some errors only show up once the CLI talks to Cursor’s API.
+- **Model**: The default `model: auto` should work for most accounts. If you pin `model`, confirm that model is available for your subscription.
+- **CLI contract changes**: This action first runs `cursor-agent chat …` (with `--allow-*` flags from `permissions`). If that fails with no output or an “unknown command”-style error, it automatically retries using headless **print mode** (`-p`, `--output-format text`) as documented in the [Cursor headless CLI](https://cursor.com/docs/cli/headless) docs.
+- **Debugging**: On failure, check the **job summary** — it includes `cursor-agent --version`, which invocation mode was used (`chat` vs `print`), merged stderr, and a **Diagnostics** section when both attempts fail.
+
+---
+
 ## Versioning
 
 This project uses [changesets](https://github.com/changesets/changesets) for versioning. See [`.changeset/README.md`](.changeset/README.md) for how to add a changeset when contributing.

__tests__/output.test.ts

@@ -91,6 +91,16 @@ describe("setOutputs", () => {
     expect(outputs.summary).toBe("Output field text");
   });
 
+  it("extracts summary from JSON text field", async () => {
+    const result = {
+      exitCode: 0,
+      stderr: "",
+      stdout: JSON.stringify({ text: "Text field value" }),
+    };
+    const outputs = await setOutputs(result, false);
+    expect(outputs.summary).toBe("Text field value");
+  });
+
   it("handles empty stdout gracefully", async () => {
     const result = { exitCode: 0, stderr: "", stdout: "" };
     const outputs = await setOutputs(result, false);

__tests__/runner.test.ts

@@ -11,7 +11,14 @@ type ExecFn = (
   options?: ExecOptions
 ) => Promise<number>;
 
+type GetExecOutputFn = (
+  commandLine: string,
+  args?: string[],
+  options?: ExecOptions
+) => Promise<{ exitCode: number; stderr: string; stdout: string }>;
+
 const mockExec = mock<ExecFn>();
+const mockGetExecOutput = mock<GetExecOutputFn>();
 const mockWarning = mock<typeof actionsCore.warning>();
 
 mock.module("@actions/core", () => ({
@@ -23,28 +30,39 @@ mock.module("@actions/core", () => ({
 
 mock.module("@actions/exec", () => ({
   exec: mockExec,
+  getExecOutput: mockGetExecOutput,
 }));
 
 const { runAgent } = await import("../src/runner");
 
+/** All `exec` invocations from the last test run. */
+const getExecCalls = (): {
+  args?: string[];
+  commandLine: string;
+  options?: ExecOptions;
+}[] =>
+  mockExec.mock.calls.map((call) => {
+    const [commandLine, args, options] = call as [
+      string,
+      string[] | undefined,
+      ExecOptions | undefined,
+    ];
+    return { args, commandLine, options };
+  });
+
 /** First `exec` invocation from the last test run (asserts the call exists). */
 const getExecCall = (): {
   args?: string[];
   commandLine: string;
   options?: ExecOptions;
 } => {
-  expect(mockExec).toHaveBeenCalled();
-  const [call] = mockExec.mock.calls;
-  expect(call).toBeDefined();
-  if (call === undefined) {
+  const calls = getExecCalls();
+  expect(calls.length).toBeGreaterThan(0);
+  const [first] = calls;
+  if (first === undefined) {
     throw new Error("expected exec to have been called");
   }
-  const [commandLine, args, options] = call as [
-    string,
-    string[] | undefined,
-    ExecOptions | undefined,
-  ];
-  return { args, commandLine, options };
+  return first;
 };
 
 const baseInputs: ActionInputs = {
@@ -60,6 +78,11 @@ const baseInputs: ActionInputs = {
 describe("runAgent", () => {
   beforeEach(() => {
     mock.clearAllMocks();
+    mockGetExecOutput.mockResolvedValue({
+      exitCode: 0,
+      stderr: "",
+      stdout: "cursor-agent 9.9.9-test\n",
+    });
   });
 
   it("calls cursor-agent with correct base args", async () => {
@@ -79,6 +102,7 @@ describe("runAgent", () => {
         ignoreReturnCode: true,
       })
     );
+    expect(mockGetExecOutput).not.toHaveBeenCalled();
   });
 
   it("includes --model flag", async () => {
@@ -122,6 +146,7 @@ describe("runAgent", () => {
     mockExec.mockResolvedValue(42);
     const result = await runAgent(baseInputs);
     expect(result.exitCode).toBe(42);
+    expect(mockExec).toHaveBeenCalledTimes(2);
   });
 
   it("surfaces stderr in a warning when cursor-agent fails", async () => {
@@ -132,6 +157,7 @@ describe("runAgent", () => {
 
     await runAgent(baseInputs);
 
+    expect(mockExec).toHaveBeenCalledTimes(1);
     expect(mockWarning).toHaveBeenCalledWith(
       expect.stringContaining("cursor-agent stderr:")
     );
@@ -140,9 +166,99 @@ describe("runAgent", () => {
     );
   });
 
+  it("does not fall back to print when chat fails with substantive stderr", async () => {
+    mockExec.mockImplementation((_cmd, _args, options) => {
+      options?.listeners?.stderr?.(Buffer.from("billing error for model\n"));
+      return Promise.resolve(1);
+    });
+
+    const result = await runAgent(baseInputs);
+
+    expect(mockExec).toHaveBeenCalledTimes(1);
+    expect(result.invocationMode).toBe("chat");
+    expect(result.diagnostics).toContain("Primary (chat)");
+    expect(result.diagnostics).not.toContain("Fallback (print)");
+  });
+
+  it("falls back to headless print when chat exits with no output", async () => {
+    mockExec.mockResolvedValueOnce(1).mockResolvedValueOnce(0);
+
+    const result = await runAgent(baseInputs);
+
+    expect(mockExec).toHaveBeenCalledTimes(2);
+    expect(mockGetExecOutput).toHaveBeenCalledWith(
+      "cursor-agent",
+      ["--version"],
+      expect.objectContaining({ silent: true })
+    );
+    const [, second] = getExecCalls();
+    const [firstPrintArg] = second?.args ?? [];
+    expect(firstPrintArg).toBe("-p");
+    expect(second?.args).toContain("--output-format");
+    expect(second?.args).toContain("text");
+    expect(result.exitCode).toBe(0);
+    expect(result.invocationMode).toBe("print");
+  });
+
+  it("falls back to print when stderr suggests unknown command", async () => {
+    mockExec
+      .mockImplementationOnce((_cmd, _args, options) => {
+        options?.listeners?.stderr?.(
+          Buffer.from("Error: unknown command chat\n")
+        );
+        return Promise.resolve(1);
+      })
+      .mockResolvedValueOnce(0);
+
+    await runAgent(baseInputs);
+
+    expect(mockExec).toHaveBeenCalledTimes(2);
+    const [, secondUnknown] = getExecCalls();
+    const [firstPrintArgUnknown] = secondUnknown?.args ?? [];
+    expect(firstPrintArgUnknown).toBe("-p");
+  });
+
+  it("adds --force on print fallback for read-write permissions", async () => {
+    mockExec.mockResolvedValueOnce(1).mockResolvedValueOnce(0);
+
+    await runAgent({ ...baseInputs, permissions: "read-write" });
+
+    const [, secondRw] = getExecCalls();
+    const printArgs = secondRw?.args;
+    expect(printArgs).toContain("--force");
+  });
+
+  it("does not add --force on print fallback for read-only", async () => {
+    mockExec.mockResolvedValueOnce(1).mockResolvedValueOnce(0);
+
+    await runAgent({ ...baseInputs, permissions: "read-only" });
+
+    const [, secondRo] = getExecCalls();
+    const printArgs = secondRo?.args;
+    expect(printArgs).not.toContain("--force");
+  });
+
+  it("merges stderr and sets diagnostics when both invocations fail", async () => {
+    mockExec
+      .mockResolvedValueOnce(1)
+      .mockImplementationOnce((_cmd, _args, options) => {
+        options?.listeners?.stderr?.(Buffer.from("print mode failed\n"));
+        return Promise.resolve(2);
+      });
+
+    const result = await runAgent(baseInputs);
+
+    expect(result.exitCode).toBe(2);
+    expect(result.invocationMode).toBe("print");
+    expect(result.stderr).toContain("primary (chat)");
+    expect(result.stderr).toContain("fallback (print -p)");
+    expect(result.diagnostics).toContain("Hints:");
+    expect(result.diagnostics).toContain("CURSOR_API_KEY");
+  });
+
   it("sets CURSOR_DISABLE_UPDATE for pinned versions", async () => {
     mockExec.mockResolvedValue(0);
-    await runAgent({ ...baseInputs, cursorVersion: "1.2.3" });
+    await runAgent({ ...baseInputs, cursorVersion: "2026.03.20-44cb435" });
 
     const { options } = getExecCall();
     expect(options?.env?.CURSOR_DISABLE_UPDATE).toBe("1");

src/output.ts

@@ -26,6 +26,9 @@ const parseSummary = (stdout: string): string => {
       if (typeof parsed.output === "string") {
         return parsed.output.trim();
       }
+      if (typeof parsed.text === "string") {
+        return parsed.text.trim();
+      }
     }
   } catch {
     // Not JSON — fall through to raw text handling
@@ -50,15 +53,25 @@ const writeJobSummary = async (
       ? "✅ Success"
       : `❌ Failed (exit ${result.exitCode})`;
 
+  const tableRows: [string, string][] = [
+    ["Status", status],
+    ["Exit Code", String(result.exitCode)],
+  ];
+  if (result.invocationMode) {
+    tableRows.push(["Invocation mode", result.invocationMode]);
+  }
+  if (result.cliVersion) {
+    tableRows.push(["cursor-agent --version", result.cliVersion]);
+  }
+
   await summary
     .addHeading("Cursor Agent Run", 2)
     .addTable([
       [
         { data: "Field", header: true },
         { data: "Value", header: true },
       ],
-      ["Status", status],
-      ["Exit Code", String(result.exitCode)],
+      ...tableRows.map(([field, value]) => [field, value]),
     ])
     .addHeading("Agent Response", 3)
     .addRaw(text ? `\n\`\`\`\n${text}\n\`\`\`\n` : "_No output was produced._");
@@ -72,6 +85,15 @@ const writeJobSummary = async (
       );
   }
 
+  const diag = result.diagnostics?.trim();
+  if (diag) {
+    await summary
+      .addHeading("Diagnostics", 3)
+      .addRaw(
+        `\n\`\`\`\n${diag.slice(0, 20_000)}${diag.length > 20_000 ? "\n… (truncated)" : ""}\n\`\`\`\n`
+      );
+  }
+
   await summary.write();
 };