feat(agent): add onTermsRequired to firecrawl_agent and keep terms fields in status

[rakshith48]

Why

Agent runs now call only the Alexandria providers whose data terms the team has accepted. Gated providers are skipped and reported back (firecrawl/extract-v3#182). MCP callers had no way to choose what happens, and the status tool's structured content dropped the fields that say what was skipped.

What changes

• firecrawl_agent takes an optional onTermsRequired: "skip" | "ask", forwarded as exchange.onTermsRequired. If it's omitted, no exchange is sent and the server default ("skip") applies. Any other value fails parameter validation, including "fail" (cut from v1 in the extract-v3#182 scope cut). There is no auto-accept mode.
• The firecrawl_agent description now explains exchange.skippedProviders and exchange.requiresAction, and describes each provider's digest as string | null, always present, with terms/show supplying it when it is null. It tells calling agents: "Never call terms/accept without the user's explicit consent to that provider's terms; a data request is not consent." After consent, they run the accept call through firecrawl_scrape and start firecrawl_agent again. The description stays under the 2,048-character cap (the budget test passes).
• agentStatusOutputSchema now names exchange, pendingApproval and message. Without that, fastmcp drops them from structuredContent, and Codex-style clients never see skippedProviders or requiresAction.
• README (onTermsRequired argument and the consent rule) and CHANGELOG [Unreleased].

Scope note: the MCP agent tool doesn't expose threadId or exchange.approve today, so an MCP caller can't use the ask mode's approvalId continuation. The documented MCP flow is: get consent, call terms/accept, then run the agent again. The new run sees the acceptance. Exposing thread continuation on the MCP tool would be a separate change.

Tests

• tests/mcp-smoke.test.mjs, new case. The tool schema lists the enum, and the description carries the consent sentence. onTermsRequired: "ask" is forwarded as exchange: { onTermsRequired: "ask" }. Omitting it sends no exchange, and "fail" is rejected. firecrawl_agent_status structured content keeps exchange.skippedProviders, exchange.requiresAction, pendingApproval.kind and message.
• npm test gives 123 pass, 0 fail. tsc --noEmit is clean. npm run lint reports one error in src/alexandria.ts:97 (expand unused). It's already on main and isn't touched here.

Related PRs and deploy order

1. firecrawl/extract-v3#182 (backend)
2. feat(agent): accept exchange.onTermsRequired; type terms-required fields in gateway and SDKs firecrawl#4759 (gateway accepts exchange.onTermsRequired; this PR must not release before it deploys, or onTermsRequired calls get a 400)
3. firecrawl/firecrawl-web#3758 (dashboard flag NEXT_PUBLIC_AGENT_TERMS_OFFER)
4. After the gateway: SDKs (in firecrawl#4759), this PR, and docs (docs(agent): document exchange.onTermsRequired and the terms-required flow firecrawl-docs#1466)

🤖 Generated with Claude Code