Behaviour
What the action does at runtime and how it reports results.
The run
- Inputs are validated. An empty
prompt, an unknownpermissionsvalue, or a non-positivetimeoutfails the step before anything is sent. - 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 inenvoutput or in the agent's answer. This is not a sandbox. Withpermissions: fullthe agent runs as the same user and can still read the key from a parent process, for example through/proc/<pid>/environon Linux. - A local SDK agent is created against the resolved
working-directory(Agent.create({ local: { cwd } })) and the prompt is sent. - Each tool call is printed to the step log when it finishes, one line per call, such as
read src/index.tsorshell bun test. A call whose tool reports an error ends infailed. 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. - Streamed text is collected, then replaced by the final run result when the SDK provides one.
summaryis that text verbatim, with surrounding whitespace trimmed; a JSON-shaped answer is not unwrapped. - A job summary is written with the status, exit code, agent response, duration, token usage, and any stderr or diagnostics.
- 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.
permissions | Tools offered |
|---|---|
read-only | read, grep, glob, ls, semSearch, readLints, webSearch, webFetch, readTodos, updateTodos |
read-write | The default toolset without shell and task (no commands, no subagents) |
full | The 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