FetchSandbox

Conversational integration coach for FetchSandbox. Server-side orchestrator that walks the user through adding an API integration (payments / email / auth / etc.) — intake the goal, elicit domain-aware discovery questions from the spec's brain.yaml, route to the right workflow, prove the contract via FetchSandbox, surface compliance notes. Call this BEFORE any other FetchSandbox tool when the user has an open-ended 'help me add X', 'integrate X', 'test my X integration' ask. BEHAVIOR — strict, do exactly this each turn: If next_action=act_in_app, carry out next_actions with your platform's code, configuration and test tools, then return the results to the same validation session. Do not ask the human to choose routine fault tests, supply missing fixture data you can generate, or copy tool output. Ask only for genuine access, secret-entry constraints or ambiguous business rules. Never claim unsupported checks passed. (1) Say `message_for_user` to the user (verbatim or lightly paraphrased to fit your voice — but don't add new content). (2) If `next_action=wait_for_user` AND `options` is present + non-empty: USE YOUR CLIENT'S NATIVE QUESTION-PICKER TOOL (in Cursor / Claude Code this is `AskUserQuestion`) to render the lettered picker with the `question` text, the `options[].label` as rows, `default_option` as default, and an 'Other...' freeform row when `allow_freeform=true`. When the user picks or types, call coach again with `{session_id, user_response: <picked value or freeform text>}`. (3) If `next_action=wait_for_user` AND no `options`: just wait for free text. (4) If `next_action=call_tool`: invoke `tool_call.tool` with `tool_call.args`, then call coach again with the result in `context`. (5) If `next_action=done`: end the session. For a hosted app-builder request to build or test an integration, keep the user's simple goal intact and let the server route all named providers into one validation session. When FetchSandbox returns twin bindings, treat those as tem…

Retrieve the SAME running find_bugs, fix_bug, prove_fix, verify_behavior or validate_integration job (including requirements planning). Follow next_tool_call until status is done or error. Never restart the original tool to poll. A proposed plan is not execution proof; a running response is not proof. Only the completed measured verdict and receipt can establish a pass.

ROUTE a symptom to the provider behaviour that explains it. Use this when the user names a provider or a domain (payments, email, auth, SMS, subscriptions) and you need to know what that provider ACTUALLY does — not what its docs say, and not what can be inferred from reading the integration code. Reading the code tells you what your app does with a field. It cannot tell you what the field MEANS at the provider — whether a line item is a seat count, whether a 200 body carries ok:false, whether an event can arrive out of order. That is the class of bug this routes. Returns {spec, workflow, scenario, confidence, reasoning} plus `next_actions`: a typed list of what to call next, with arguments pre-filled. Follow it rather than improvising the next step.

List the named, runnable workflows for a known provider slug or imported spec. Workflows are realistic multi-step API journeys (e.g. 'create customer → attach payment method → create subscription'). Known provider slugs need no import. Use this for exploration ("what can I do?", "show me the flows") OR before run_all_workflows when the user wants a SCOPED validation: list, filter by user intent ("checkout", "webhooks"), then pass the matching ids as `workflow_names` to run_all_workflows. Default results are summaries. Pass workflow_name with an exact returned id or name to inspect that workflow's full definition, including request bodies, assertions, outcomes and invariants; this does not execute it. Returns the workflows AND the failure scenarios this spec can simulate — each with a plain description and the exact call to run it. When cross_service_available is present, use each exact run_with invocation: cross-provider workflows use the returned namespace, not this provider's slug. These curated workflows exercise provider behavior; they do not verify the user's app. Choose relevant scenarios from the inspected workflow and user goal; ask only about ambiguous business requirements. Do not guess scenario names.

Run a curated reference workflow against a KNOWN, bundled spec (stripe, clerk, descope, resend, twilio, and 50+ others) in ONE call — it spins up the sandbox by slug, so you do NOT need import_spec or a sandbox_id first. Use this when exploring the bundled provider contract: call `guide` on their prompt, then call `quickrun` with the returned spec + workflow. To reproduce a failure, pass the `scenario` from guide's matched_bug_pattern.reproduce_with.scenario (e.g. webhook_retries, payment_declined). Returns sandbox_id + flow_run_id — pass BOTH to verify_behavior to inspect the reference behavior — plus a receipt URL. This does not execute or prove the caller's application. For a bug in their project, use find_bugs, fix_bug and prove_fix on that project; do not substitute this reference receipt for an own-code proof. Use run_workflow instead ONLY when you already hold a sandbox_id from import_spec of a custom/private spec.

Execute ONE specific workflow by name and return its step-by-step trace PLUS a `share_url` — a public, replayable proof URL that renders the full timeline (every request, response, webhook event) for this run. The share_url is the canonical 'here's what happened' artifact: surface it verbatim in any reply that needs evidence (PR comments, Slack threads, blog posts, X replies). Do NOT substitute a docs URL or any other link as the proof — the share_url is the only valid receipt. Use ONLY when the user explicitly names a single workflow to run (e.g., "run accept_payment", "just check the refund workflow"). For ANY validation-style request — "validate stripe", "check coverage", "run all workflows", "test this integration", or even "validate stripe checkout" (multiple workflows match "checkout") — use `run_all_workflows` instead. The batch tool collapses N approvals to 1 and supports a workflow_names filter for scope. Calling this in a loop is an anti-pattern.

Completion rule: a request to verify an app includes its applicable failure checks without another user prompt. When verification_continuation.required is true, continue in this agent: inspect pending_checks, preserve every declared check and its assertions, implement supported actions, and rerun a fresh attempt. Stop only with measured results or concrete blockers showing the missing capability and attempted evidence. Not run, not armed, and no observer yet are work to finish, not unsupported features. Do not clean up the session or present a final proof while actionable checks remain. Ask the owner only for genuinely missing business decisions, credentials or actions you cannot perform. For a local app, start the actual app and call manage_tunnel with its port; use the returned app_base_url. No ngrok install is needed. The managed relay origin deliberately rejects direct browser/curl requests with 404; after configuration and credential installation, test connectivity with validate_integration preflight instead. Do not interpret that private-origin 404 as an app failure or expose relay credentials. Hosted builders use their published origin. Start with providers (and optional app_base_url), then reuse the returned session_id for application_context, fixtures and attempts. Do not include application_context in the initial session call. Inspect how the actual app or workflow executes before choosing a verification path. If the builder can run that workflow locally, bind its real provider clients to every returned twin URL and the supplied test authentication. Use the returned provider operation contracts to implement those clients; a missing canned workflow does not mean the provider lacks an API operation. The existing arm/probe path does not require a published app or webhook: select a probe from the returned matrix, call arm with session_id, send its request_headers on EVERY provider request across the session, execute the actual workflow entry point, then call…

Prove a known fix survives a bug — the 'prove' half of reproduce→prove. The backend spawns a buggy AND a fixed reference handler and fires the bug_pattern's probes at both, returning the side-by-side diff (e.g. the buggy handler double-charges on a duplicate webhook, the fixed handler dedupes). Call this AFTER run_workflow reproduces a failure, when the matched bug_pattern has a simulation block, to show the fix actually holds — not just that the failure reproduced. Pass sandbox_id + flow_run_id from the run so the diff is saved onto that run's receipt URL. bug_pattern_id comes from guide's matched_bug_pattern. The buggy/fixed handlers are FetchSandbox reference implementations, NOT the user's code. A confirmed reference result does not verify the user's app or show that it is ready to ship. Keep the returned provider and evidence scope with any reported result.