feat(agent): exchange options and terms approval on firecrawl_agent

[rakshith48]

Builds on #446 (merged), which added threadId and mode. Together with #446, this replaces #445.

Why

With exchange.onTermsRequired: "ask", an agent turn can end on a terms offer: a pendingApproval with kind: "terms", plus exchange.requiresAction. Before this PR, an MCP caller could run terms/accept but couldn't answer the offer on the same thread.

What changed

• firecrawl_agent takes exchange, a strict object that mirrors the gateway's agentExchangeSchema (firecrawl#4759). It is forwarded through the SDK's startAgent; firecrawl 4.40.0 passes exchange through as-is. The fields:
  • enabled
  • toolkits: at most 5, the agent service's limit
  • maxCalls: 1 to 30
  • requireApproval
  • approve: {approvalId, callIds?, always?}
  • decline: {approvalId}
  • onTermsRequired: "skip" | "ask"
• Checks that reject a call before anything is sent:
  • approve or decline without threadId. Without a thread, the agent service silently ignores them.
  • approve and decline together. The agent service silently prefers approve.
  • requireApproval without mode: "chat" on the same request. The agent service checks the request's own mode, not the thread's inherited one, and the gateway turns its 400 into a 500.
• The tool description covers:
  • skippedProviders and requiresAction.
  • The ask-mode flow: show the user the terms, get their EXPLICIT consent, run terms/accept through firecrawl_scrape, then call firecrawl_agent with the same threadId and exchange.approve: {approvalId}.
  • Declining: send exchange.decline: {approvalId}.
  • Never auto-accepting terms.
  • It stays under CLAUDE_CODE_TEXT_CAP.
• firecrawl_agent_status keeps exchange and pendingApproval in its structured content, in both the terms and the paid-call shape.
• README (exchange arguments, the 4-step terms flow, an approve example) and CHANGELOG updated.

Tests

• New tests cover:
  • Schema parity with the gateway.
  • Exact request bodies for approve, decline, a paid-call approve and onTermsRequired.
  • Rejected inputs, with a check that none of them reach the API.
  • Status output for both pendingApproval shapes.
• Results: npm test 126/126 pass, tsc clean, eslint clean on the changed files (rebased onto main after feat(agent): continue a thread from firecrawl_agent #446 merged).

Known gaps

• Answer errors come back as a generic 500. A stale approvalId (approval_stale, 409) is rejected by the agent service after the gateway passes the request through, and the gateway returns 500 "Failed to passthrough agent request.".
• A prompt is required on approve/decline turns. MCP keeps prompt at min(1), so callers send a short message such as "I accepted the terms. Continue."

🤖 Generated with Claude Code

[cubic-dev-ai]

All reported issues were addressed across 5 files

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | 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>Requires human review: Adds exchange to firecrawl_agent to answer pending terms/paid-call approvals on the same thread, with tests and docs. It changes the MCP tool's public request/response shape and adds a terms/paid-call approval flow, so human sign-off is needed.

Re-trigger cubic</sub>