Behaviour

The run

1. Inputs are validated. An empty prompt, an unknown permissions value, or a non-positive timeout fails the step before anything is sent.
2. The API key is registered with ::add-mask::.
3. A local SDK agent is created against the resolved working-directory (Agent.create({ local: { cwd } })) and the prompt is sent.
4. Streamed text is collected, then replaced by the final run result when the SDK provides one.
5. A job summary is written with the status, exit code, agent response, duration, token usage, and any stderr or diagnostics.

Timeouts and failures

When timeout elapses, the action requests a run cancellation. Cancelled runs exit with code 1. The step fails and reports the cancellation in the job summary.

The same applies when a run ends with an error. The action reads status and error from run.wait(), sets exit code 1, and writes the error details to stderr.

Why it installs instead of shipping one file

The action is a composite action: it sets up Node.js 24, runs npm ci --omit=dev inside its own action directory, and then executes dist/index.mjs. Expect a few seconds of install time per job.

@cursor/sdk cannot be bundled into a single file. It is a webpack build that dynamically imports its own chunks at runtime, resolved relative to its own package directory, and it resolves a native @cursor/sdk-<platform> package for the rg and cursorsandbox binaries. A bundle containing it imports cleanly and then fails inside Agent.create.

dist/ is committed and holds only this repository's own code, a few kB.

Treat the summary as untrusted

summary is model output. Interpolating it into a run: script or a github-script body splices the text into the script before it executes. Pass it through env: instead. Every example on Examples does.

Isolation

The agent runs in working-directory, and Cursor loads project rules, hooks and settings from there. Point it somewhere outside the checkout when you want a run that the repository's own .cursor/ configuration cannot influence.