Skip to content

firecrawl: sync submission next_steps with the shipped catalogue metadata - #96

Open
Alexgodoroja wants to merge 3 commits into
mainfrom
fix/firecrawl-next-steps
Open

firecrawl: sync submission next_steps with the shipped catalogue metadata#96
Alexgodoroja wants to merge 3 commits into
mainfrom
fix/firecrawl-next-steps

Conversation

@Alexgodoroja

Copy link
Copy Markdown
Collaborator

Follow-up to #95. Found while reviewing before sign-off.

The drift

The next_steps graph was expanded from 10 to 18 edges after #95 merged, so the merged submission no longer matches what the catalogue actually ships (pilot-protocol/pilotprotocol#447).

That is not cosmetic. submission.json is the authoring source of truth — publish-rich-from-r2.sh carries next_steps from the submission into metadata.json. So a re-publish from this submission, e.g. once the broken CATALOG_PUBLISH_TOKEN is rotated and publish-on-merge starts working again, would silently regress the graph and drop the 429 edge.

That edge is the most important one in the graph: Pilot's shared Firecrawl account runs at maxConcurrency: 2, and 429 is by far the most likely failure an agent meets.

What this adds

Verified identical to the graph shipped in #447 (json.dumps(..., sort_keys=True) equal).

  • 429 — routes to queue_status, then interact_list, because browser/interact sessions each hold one of the 2 concurrency slots until destroyed. Found live, not in the docs.
  • match-on-success-body edges — a crawl still "scraping" is normal, not a failure; an empty web[] on search means fix the query, not scrape the results.
  • a scrape whose statusCode is 401/403/429/5xx — Firecrawl succeeded, the site refused; retry with proxy:"enhanced".
  • a timeout edge pointing at activity, so the agent checks whether the job landed before paying to run it again.

Testing

TestAllSubmissionDemosValid, TestAllSubmissionNextStepsValid, TestSubmissionGatewaysAreReachable, TestSubmissionCrossAppStepsResolve all pass.

Per rule 5 of NEXT-STEPS-GRAPHS.md, every authored command was executed against the live app, and rendering was confirmed on a real pilotctl appstore install for all three edge classes:

$ pilotctl appstore call io.pilot.firecrawl firecrawl.crawl_status '{"id":"..."}'
next: still running — this is normal, not a failure. A crawl takes minutes
  1. ... firecrawl.crawl_status '{"id":"PASTE-THE-SAME-id-AGAIN"}'
     why: poll again in ~10s — polling is free and does not consume credits

No bundle change, no version bump — next_steps lives in metadata, not in the bundle.

🤖 Generated with Claude Code

Alex Godoroja and others added 3 commits August 3, 2026 15:59
…data

The graph was expanded from 10 to 18 edges after #95 merged, so the merged
submission no longer matched what the catalogue actually ships. Left as-is, a
re-publish from this submission would silently regress the graph and drop the
429 concurrency edge - the single most important one, since the shared Firecrawl
account runs at maxConcurrency 2.

Adds: 429 (with interact-session slot recovery), match-on-success-body edges for
a still-running crawl and an empty search, site-refused scrape detection, and a
timeout edge. Every command was executed against the live app.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The demo is printed at the last step of install and rendered on the website, so
it was publishing our cost basis with Firecrawl: the micro-USD ledger unit, the
'1 credit ~= 830 micro-USD' conversion, per-operation dollar prices, and the
$0.0415 budget. It also leaked that Pilot runs one shared Firecrawl account.

Restated in the published limits instead: 1000 credits, 2 concurrent calls.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The next-steps hint said 'the shared account runs at maxConcurrency 2', which
tells every agent that all Pilot users sit behind one Firecrawl team. Restated
as the user's own published limit: 2 concurrent calls.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant