feat: stamp the coding agent in the request origin

[erikengervall]

Summary

The CLI now stamps the coding agent that runs it into the request origin: cli.<agent>@<cli version> when an agent is detected, cli@<cli version> otherwise. integration: 'cli' is unchanged everywhere, and the keyless X-Origin: cli header is kept as is.

• New src/utils/agent-origin.ts computes the origin once per process from environment variables that agents set in the processes they spawn (no config files on disk).
• FIRECRAWL_CLI_DISABLE_AGENT_ORIGIN=1 sends plain cli@<version>. Documented in the README.
• Detection order puts Claude Code last: its variables are the most widely inherited (IDE terminals, tmux), so a more specific agent wins when both are set.

Where the origin is sent

Path	How
Keyless POSTs (scrape, search)	body origin
interact, feedback, search-feedback, parse	body / options origin
monitor create and update	body origin
research, developer, gov GETs	origin query parameter next to integration=cli
SDK-routed calls	origin client option

SDK-routed calls (firecrawl@4.44.0, the version the CLI pins) carry the agent only after the SDK bump: that version has no origin client option and its HTTP client overwrites a body origin unless it contains "mcp". The CLI passes origin as a client option now; SDKs without it ignore the option, so nothing changes until the SDK ships support. The direct fetch paths above carry the agent immediately. Requests that have no origin field (credit usage, status, doctor, exchange calls) are unchanged.

Detected agents and sources

Slug	Variables	Source
claude-code	CLAUDECODE, CLAUDE_CODE_ENTRYPOINT	https://code.claude.com/docs/en/plugin-hints (CLAUDECODE set for Bash tool commands); anthropics/claude-code-action@c9ec2b0 (CLAUDE_CODE_ENTRYPOINT)
codex	CODEX_SANDBOX, CODEX_SANDBOX_NETWORK_DISABLED, CODEX_THREAD_ID, CODEX_MANAGED_BY_NPM/BUN/PNPM/VITE_PLUS	https://github.com/openai/codex/blob/main/codex-rs/core/src/spawn.rs ; https://github.com/openai/codex/blob/main/codex-rs/protocol/src/shell_environment.rs ; https://github.com/openai/codex/blob/main/codex-cli/bin/codex.js
cursor	CURSOR_AGENT	https://cursor.com/docs/agent/tools/terminal
gemini-cli	GEMINI_CLI	https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/shell.md
opencode	OPENCODE	process.env.OPENCODE = "1" in https://github.com/anomalyco/opencode/blob/dev/packages/opencode/src/index.ts
goose	GOOSE_TERMINAL	https://github.com/block/goose/blob/main/documentation/docs/guides/environment-variables.md ; aaif-goose/goose#7017
cline	CLINE_ACTIVE	https://docs.cline.bot/features/customization/disable-terminal-pagers

Dropped because they could not be verified from public docs or source:

• CURSOR_TRACE_ID: no public documentation, and it is likely present in every Cursor terminal, including ones a person types in.
• Amp: the AMP_* variables are user configuration, not a runtime marker, and AGENT=amp only appears in third-party reports.

Testing

• pnpm type-check, pnpm format:check, pnpm test pass (716 tests).
• New unit tests cover detection, precedence, falsy values, the opt-out, once-per-process caching and the keyless body origin.
• Existing tests that asserted origin: 'cli' or the bare integration=cli query now build the expected value with getCliOrigin(), so they pass when run inside an agent.
• Not verified against a live API.

---

Summary by cubic

The CLI now stamps the coding agent that runs it into the API request origin: cli.<agent>@<version> when an agent is detected, cli@<version> otherwise. integration: 'cli' and the keyless X-Origin: cli header are unchanged.

Details

• Agent detection reads environment variables agents set in the processes they spawn (no config files on disk) and is computed once per process.
• FIRECRAWL_CLI_DISABLE_AGENT_ORIGIN=1 (or true, yes, on) restores plain cli@<version> and is documented in the README.
• The origin is stamped into keyless POST bodies, GET query params for developer, research, and gov, and the body origin in interact, feedback, search-feedback, parse, and monitor create/update; the API now accepts origin on monitor create and update.
• SDK-routed calls pass origin as a client option; SDKs without support ignore it, so those requests carry the agent only after the matching SDK release.
• Detection is ordered innermost agent first, with Claude Code last since its variables are the most widely inherited.
• Tests pin the origin to a mock value, cover every Codex marker, and isolate the cache test from the host environment, so assertions hold regardless of the agent that runs them.

^{Written for commit 134243a. Summary will update on new commits.}

[cubic-dev-ai]

All reported issues were addressed across 18 files

<sub>Shadow auto-approve: would not auto-approve because issues were found.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 11 files (changes from recent commits).

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>Shadow auto-approve: would require human review. Adds agent-stamped request origins across many CLI API paths with an opt-out; needs human sign-off because it changes telemetry data sent by default and relies on unverified API compatibility for the new origin field (especially monitor).

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[capy-ai]

@cubic review

[cubic-dev-ai]

@cubic review

@capy-ai[bot] I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

1 issue found across 19 files

Confidence score: 5/5

• agent-origin.test.ts does not cover three Codex install markers, so regressions in their detection could go unnoticed. Add table rows for CODEX_MANAGED_BY_BUN, CODEX_MANAGED_BY_PNPM, and CODEX_MANAGED_BY_VITE_PLUS.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/__tests__/utils/agent-origin.test.ts">

<violation number="1" location="src/__tests__/utils/agent-origin.test.ts:14">
P3: The detection table omits tests for three Codex install markers. Add rows for `CODEX_MANAGED_BY_BUN`, `CODEX_MANAGED_BY_PNPM` and `CODEX_MANAGED_BY_VITE_PLUS` so a regression in any of them is caught.</violation>
</file>

<sub>Shadow auto-approve: would not auto-approve because issues were found.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 1 file (changes from recent commits).

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>Shadow auto-approve: would require human review. Adds agent-detected origin stamping (cli.<agent>@<version>) to CLI API requests with an env opt-out. Needs human sign-off: default telemetry change and unverified API-side acceptance of the new origin field on monitor/direct paths.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>