[Discovery] CLI: pascal architect run/status/cancel

[Aymericr]

What does this PR do?

Adds three commands to @pascal-app/cli. Together they form a thin client over Pascal's hosted OpenAI-compatible Responses API (https://editor.pascal.app/api/v1/responses), authenticated with the agent's PASCAL_API_KEY:

• pascal architect run "<brief>" creates a background run (background: true, store: true) and streams it over SSE while you stay attached. Text deltas go to stdout and progress goes to stderr. Ctrl+C detaches without cancelling (exit 130). --detach queues the run and returns its ID straight away.
  • --effort low|medium|high|pro selects the architect-<effort> model. Without it, the run uses architect.
  • --project <id> is sent as metadata.project_id.
  • --max-credits <n> is sent as metadata.pascal_max_credits.
  • --json prints a stable run object (schemaVersion: 1).
• pascal architect status <id> calls GET /responses/{id}.
• pascal architect cancel <id> calls POST /responses/{id}/cancel.

Errors. A 503 with executor_unavailable, sent either as an HTTP error or as an SSE error event, becomes architect_executor_unavailable, with a message saying no run was started. That error exits with 75 (EX_TEMPFAIL); so do 429 and other 503s, so scripts can tell when retrying will help. 401 and 403 point you to pascal agent status. The CLI never echoes the key or the server's HTTP error bodies, and it strips control sequences from server text before printing it.

Shared code. agent-account.ts now exports requireAgentApiKey, used by both the agent and architect commands.

Docs. Only the CLI README changed, per the docs owner. It says the commands ship in the next @pascal-app/cli release and gives no credit estimates.

How to test

1. cd packages/cli && bun test src should report 137 passing tests, including the new architect.test.ts and the CLI process tests in cli.test.ts.
2. bun run build, then node dist/bin/pascal.js architect --help should print the architect usage.
3. node dist/bin/pascal.js architect run "x" --effort max should fail with invalid_option and exit 2.
4. PASCAL_API_KEY=sk_test_fake node dist/bin/pascal.js architect status resp_probe --json should return architect_unauthorized (HTTP 401) from the live endpoint.
5. With a real agent key: pascal architect run "A small cabin" --effort low should stream output; press Ctrl+C, then pascal architect status <id>.

Ran: bun run check-types and bun run build in packages/cli, bun test src (137 pass), and the repo-level bun run check (passes with warnings only). Steps 3 and 4 were run by hand. Step 5 was not run, because no real agent key was available.

Screenshots / screen recording

N/A — non-visual change

Checklist

• I've tested this locally with bun dev
• My code follows the existing code style (run bun check to verify)
• I've updated relevant documentation (if applicable)
• This PR targets the main branch

  

[Aymericr]

Docs review (README vs code). Looks accurate overall; a few fixes:

1. Statuses: write in_progress (that's what --json returns). Suggest: "…queued, in_progress (shown as "in progress"), completed…"
2. --max-credits: suggest "Stop the run before it spends more than n credits (positive integer); sent as metadata.pascal_max_credits." Matches the help text and doesn't overpromise, since paid service tools are billed separately.
3. Add the missing errors: architect_insufficient_credits (account lacks credits), architect_run_not_found (no run with that ID visible to this key), architect_stream_interrupted (connection dropped but the run continues; check with pascal architect status <id>). All exit 1.
4. ARCHITECT_HELP links to /docs/developers/mcp; point it to https://editor.pascal.app/docs/developers/cli, which will be live before release.
5. Nit: Ctrl+C before the run is confirmed also exits 130 with no run ID.

I'll publish docs/developers/cli.mdx once this merges and ships to npm.