Cursor Action

Behaviour

What the action does at runtime and how it reports results.

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:: and removed from the environment that shell commands and hooks the agent runs inherit, so it does not show up in env output or in the agent's answer. This is not a sandbox. With permissions: full the agent runs as the same user and can still read the key from a parent process, for example through /proc/<pid>/environ on Linux.
  3. A local SDK agent is created against the resolved working-directory (Agent.create({ local: { cwd } })) and the prompt is sent.
  4. Each tool call is printed to the step log when it finishes, one line per call, such as read src/index.ts or shell bun test. A call whose tool reports an error ends in failed. A shell command that exits non-zero still ran, so it does not. Arguments are shortened to 160 characters, and file contents and tool results are never printed.
  5. Streamed text is collected, then replaced by the final run result when the SDK provides one. summary is that text verbatim, with surrounding whitespace trimmed; a JSON-shaped answer is not unwrapped.
  6. A job summary is written with the status, exit code, agent response, duration, token usage, and any stderr or diagnostics.
  7. The agent is released (Symbol.asyncDispose), which shuts down the local executor the SDK started for the run.

Timeouts and failures

When timeout elapses, the action requests a run cancellation and waits at most ten seconds for the run to stop. A run that stops, or never answers, is reported as cancelled, the step exits with code 1, and the job summary records the cancellation. A run that finishes during those ten seconds keeps its result and exit code 0, with a warning that it overran the timeout.

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 uses the runner's Node.js when it is 22.13 or newer (the SDK's minimum) and sets up Node.js 24 otherwise, 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. When the action sets up Node.js 24, later steps in the job also run on it.

@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.

Permissions

The permissions input is passed to the SDK as a tool allow or deny list. It restricts the main agent loop; it is not a sandbox.

permissionsTools offered
read-onlyread, grep, glob, ls, semSearch, readLints, webSearch, webFetch, readTodos, updateTodos
read-writeThe default toolset without shell and task (no commands, no subagents)
fullThe SDK's default toolset

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.

Last updated on

On this page