feat(agent): send Alexandria exchange settings and answer approvals

[mogery]

POST /v2/agent only uses Alexandria providers when the request carries an exchange object, and firecrawl agent had no way to send one. So CLI agent runs never used connected providers, and a turn that stopped for approval couldn't be answered from the CLI.

What shipped

New firecrawl agent flags, each mapping onto one exchange field:

Flag	exchange field
--alexandria / --no-alexandria	enabled (unset unless given)
--toolkits <slugs>	toolkits (comma-separated)
--max-calls <n>	maxCalls
--require-approval	requireApproval
--approve <approvalId> + --call-ids <ids>, --always	approve: { approvalId, callIds, always }
--decline <approvalId>	decline: { approvalId }
--on-terms-required <skip|ask>	onTermsRequired

• exchange is built only when at least one of these flags is given, and it goes out with the start request on both the --wait path and the plain start path. Without a flag, the request is unchanged, so a follow-up turn still inherits the previous turn's settings.
• The CLI fails fast, before calling the API, in three cases: --approve/--decline without --thread, both flags together, and --require-approval without --mode chat. Without that last check the API returns an opaque 500. All other limits (toolkit count, maxCalls range, ID format) are left to the server.
• Human-readable status output now shows the run's Alexandria summary: paid calls, credits, and skipped providers with their terms links. When the turn ended on a pendingApproval, the output prints its ID and reason, the calls waiting for approval (or, for a terms approval, the providers whose terms must be accepted in the dashboard first), and the exact follow-up commands:

  firecrawl agent "<follow-up prompt>" --thread <threadId> --mode chat --approve <id>
  firecrawl agent "<follow-up prompt>" --thread <threadId> --mode chat --decline <id>
  

  --json output carries pendingApproval and exchange as-is.
• The firecrawl SDK goes from 4.40.0 to 4.44.0. 4.40.0 already forwarded exchange, but its types lacked onTermsRequired, terms approvals and skippedProviders.
• The flags are documented in the README agent section and in skills/firecrawl-agent/SKILL.md.

Tests

The new cases are in src/__tests__/alexandria-beta.test.ts and run against the existing mock API server:

• The flags map onto the exchange body, including --decline with --no-alexandria.
• No exchange is sent when no flag is given.
• Each of the three fail-fast cases exits 1 without making a request.
• Pending-approval output for calls and terms approvals, run through --wait. This also checks that exchange is sent on the wait path.

Local runs: format:check, type-check and build pass, and pnpm test passes 683/683. A bun build --compile binary also builds and prints the new help text.

Release

This bumps package.json to 1.26.2, so merging publishes firecrawl-cli@1.26.2 to npm and cuts the v1.26.2 binary release.

---

Summary by cubic

Lets firecrawl agent send Alexandria provider settings and answer pending approvals, so CLI runs can use connected providers and users can approve or decline turns that stopped for approval.

• Adds --alexandria/--no-alexandria, --toolkits, --max-calls, --require-approval, --approve (with --call-ids, --always), --decline, and --on-terms-required flags, each mapping onto a field of the exchange request body.
• Sends exchange only when at least one Alexandria flag is given, keeping the request unchanged otherwise so follow-up turns inherit the previous turn's settings.
• Fails fast before calling the API for invalid combinations: --approve/--decline without --thread, both together, and --require-approval without --mode chat.
• Human-readable status output now prints a pending approval with its ID, reason, waiting calls (or terms links), and the exact --approve/--decline follow-up commands; --json carries pendingApproval and exchange as-is.
• Bumps firecrawl from 4.40.0 to 4.44.0 for onTermsRequired, terms approvals, and skipped-provider types, and releases 1.26.2.

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

[cubic-dev-ai]

All reported issues were addressed across 8 files

<sub>Shadow auto-approve: would not auto-approve because issues were found.
Tip: instead of fixing issues one by one fix them all with cubic

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