feat(cli): preserve and display API agent hints

[ericciarla]

Problem and result

CLI commands currently drop optional response guidance when rebuilding API envelopes or unwrapping SDK results. Preserve agent_hints across Search, Scrape, Parse, Map and Alexandria so an agent can see the server's next-step and feedback guidance, including on empty results and failures.

• JSON retains hints and available operation/error metadata. Empty Search results still emit their JSON envelope. A keyless success:false response remains a failure even when HTTP succeeds.
• Readable/raw modes print hints to stderr, keeping page content, pipes and content files clean. Explicit JSON takes precedence over query-answer-only output so metadata is retained.
• --no-agent-hints suppresses guidance locally, including JSON. This flag does not add unsupported request-body parameters or claim to disable generation on the server.
• The CLI neither generates hints nor executes suggested actions. Existing output stays the same when no hints are returned, except the documented empty/error JSON handling and retained Map IDs.

Dependency and rollout

Companion API/SDK PR: firecrawl/firecrawl#4641.

Search and Parse read raw response envelopes; keyless Scrape also preserves outer metadata directly. Authenticated Scrape, Map and Alexandria depend on a published SDK containing the metadata preservation in that PR. The current pinned firecrawl@4.40.0 drops those fields. Keep this draft until that release can be pinned and validated; this PR does not invent a future version or publish packages.

Separate from skill-routing PR #226; no skills or release identity are changed here.

Validation

• Full CLI suite: 459 tests passed.
• After the final keyless failure guard and additional regression test: all 16 focused hint tests passed; build and formatting passed again.
• Local HTTP integration tests cover empty/error Search responses and suppression. No paid or production API calls.
• TypeScript build, formatting and git diff --check passed.

---

Summary by cubic

Previously, the CLI dropped optional agent_hints from Search, Scrape, Parse, Map, and Alexandria responses. It now preserves them for JSON output and displays them on stderr for readable and raw output, while --no-agent-hints suppresses them locally without changing requests or executing suggestions.

Migration

• Authenticated Scrape, Map, and Alexandria require an SDK release that preserves hints on results and SdkError; the pinned firecrawl@4.40.0 does not preserve all of these fields.
• Search, Parse, and keyless Scrape preserve response envelopes directly, including empty results, typed failures, and server-provided IDs.

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