agent: show partial results when a run hits its credit limit

[rakshith48]

What this does

When an agent run stops because it hit its credit limit, the CLI now shows what the agent found so far, instead of just printing an error.

• Prints a clear "Stopped at credit limit" notice with the run's message.
• Shows the partial result:
  • --json: the output includes partial, partialSchemaValid and stopReason, plus success: false and error.
  • Human output: the partial is labelled "Partial Result (incomplete)", with "matches schema" or "does not match schema" when the server sends that.
  • If the server recovered nothing, it says "No partial result was recovered."
• Says how to continue: send a follow-up on the thread (the next turn picks up from the partial), or rerun with a higher --max-credits.
• --wait runs still exit 1, the same as any other failed run.
• firecrawl agent thread <id> shows each run's partial and adds a "continue" hint when the latest turn stopped at its credit limit.

When the new fields are missing, nothing changes. That covers older servers and the default setup, since the server flag starts off. Other failed runs still print Error: ... and exit 1 exactly as before.

Notes

• The pinned SDK (firecrawl@4.40.0) does not have these fields in its types yet, so the CLI reads them defensively from the raw response. It does not bump to an unreleased SDK.
• A plain status check (firecrawl agent <job-id>, without --wait) still exits 0 for a failed run, as it does today. It now also shows the notice and the partial.
• In --json mode, or with -o, the notice goes to stderr so the JSON or file output stays clean.

Merge order

Merge this after firecrawl/firecrawl#4812 is deployed. Source PRs:

• Agent: expose incomplete results in status and threads firecrawl#4812: exposes partial / partialSchemaValid / stopReason on GET /v2/agent/{id} and thread runs
• firecrawl/extract-v3#187: recovers a bounded partial after a max-credit stop

Testing

• pnpm run format:check, pnpm run type-check, pnpm run build and pnpm test all pass (663 tests).
• New end-to-end tests against the local fake API cover: a waited run in JSON and human mode, a credit stop with no partial, an unrelated failure staying the same, a status check, and a thread listing.

🤖 Generated with Claude Code

---

Summary by cubic

Shows what an agent found so far when a run stops at its credit limit, instead of just printing an error.

• Adds a credit-limit notice with the run's message and how to continue: follow up on the thread or rerun with a higher --max-credits.
• JSON output now includes partial, partialSchemaValid, and stopReason; human output labels the partial "Partial Result (incomplete)" and notes schema validity when the server sends it.
• firecrawl agent thread <id> shows each run's partial and adds a continue hint when the latest turn stopped at its credit limit.
• Waited runs still exit 1, and output is unchanged when the new fields are absent (older servers).
• Credit-limit JSON output is flushed before exiting so piped results aren't cut off.
• In --json or --output mode, the notice goes to stderr to keep stdout pure JSON or the file clean.
• Merge after the server change exposing these fields is deployed.

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

[cubic-dev-ai]

All reported issues were addressed across 3 files

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

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 2 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 auto-approve. Adds credit-limit stop handling to the agent CLI: failed runs now surface the recovered partial, stop reason, and continue hints in human, JSON, and thread output, guarded so older servers are unchanged. Bounded, well-tested output improvement.

Re-trigger cubic</sub>