[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 after 1.0.5 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 after rebasing onto main (CLI 1.0.5): 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). Step 3 was 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

  

---

Note

Medium Risk
New hosted API surface authenticated with PASCAL_API_KEY and credit-spend metadata; mitigations include credential stripping from env, no echo of keys or error bodies, and input/output bounds.

^{Reviewed by Cursor Bugbot for commit 6692cac. Bugbot is set up for automated code reviews on this repo. Configure here.}

[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.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-22T16:24:28.684077Z	6692cac	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 6692cac. Configure here.}

[cursor]

Open stream keeps the CLI running

High Severity

After a terminal SSE event or a stream error, readServerSentEvents releases the reader lock without cancelling the fetch body. Node's fetch then keeps the HTTP connection open, so the process can sit there after it has already printed the result or the error and set exitCode.

Additional Locations (1)

• packages/cli/src/architect.ts#L122-L125

 

^{Reviewed by Cursor Bugbot for commit 6692cac. Configure here.}

[cursor]

Stream errors drop the run ID

Medium Severity

After a run has started, a malformed SSE event throws invalidResponse without the run ID and tells the user to try again. The background run keeps going and there is no list command, so a retry starts a second run while credits keep getting spent on the first.

Additional Locations (2)

• packages/cli/src/architect.ts#L356-L358
• packages/cli/src/architect.ts#L539-L544

 

^{Reviewed by Cursor Bugbot for commit 6692cac. Configure here.}