Reason Provider

What it is

Reason is a remote coding agent: its planning, model calls and tools all run on Reason's servers. Omniscio talks to it over Reason's public HTTP API (https://api.reasonmachines.com/v3) — there is nothing to install. The vendor's reason command-line tool is deliberately not used: its installer refuses Windows, while the API works the same on every computer.

What the user sees

A Reason session looks like any other session in the sidebar and main pane, with a few differences:

• The first message posts a "Watch Reason work on this live" link to Reason's own page for the run.
• Reason's answer appears when a turn finishes (Reason reports one reply per turn), not word by word.
• If Reason opens a pull request, a "Reason opened a pull request" row links to it — once.
• When a turn did not succeed, a plain row says so: "Reason says this didn't succeed", or "Reason is waiting on you to continue" when it needs your input. A finished turn on its own is never presented as a success.
• Cost shows as "cost not reported" for now, never a misleading $0.

Where to find it

Settings → Accounts → Reason (Reason Machines) — shown with the other alternative providers.

1. Turn on Allow Reason sessions in any project (off by default).
2. Press Get your Reason API key — it opens https://reasonmachines.com/customize?tab=api. Create a key with the run and sessions:read scopes and paste it into Reason API Key. The key is stored encrypted and never reaches the app window.

Then start a Reason session the same three ways as any provider: the new session's provider picker, a project's Default provider, or anything that creates a session with provider: 'reason'.

How it behaves

• Repository. If the project folder has a GitHub origin remote, Reason is pointed at it as owner/name (never the remote URL, which can carry a token). The repository must be connected to Reason first; if it is not, the error row says so. With no GitHub remote, Reason starts without a repository and a row explains why.
• Spend ceiling. Every session is created with a $20 spend ceiling on your Reason account, so a runaway remote run cannot drain it.
• Stop. Pressing Stop on a running turn asks Reason to cancel the run, so it stops working (and spending) too. Your next message is sent to the same Reason session.
• Errors, in plain words. A rejected key, a key missing a scope, an empty quota, a rate limit, a lost connection and an unknown session each get their own sentence.

Limitations (v1)

• No live word-by-word progress (use the "watch live" link), no images, no MCP servers.
• No cost reporting yet, even though Reason reports a dollar figure — a tracked follow-up.
• A running session is not re-attached after an Omniscio restart.

For agents

How it works under the hood

• Client — reason-client.ts: resolves the workspace from GET /v3/self (cached per key), then POST …/sessions (prompt, repo, an idempotency key of the Omniscio session id plus a hash of the prompt, and execution_budget.spend_limit_usd), GET …/sessions/:id, the paged GET …/conversation, POST …/messages (with a fresh client_message_id) and POST …/cancel. Both POSTs are idempotent, so a request whose answer was lost is replayed once with the identical body; an HTTP rejection is never retried. completion_mode is deliberately not sent: without it, a finished turn reports success, and action_required means it is waiting on a person.
• Manager — reason-session-manager.ts extends BaseExternalSessionManager, registered once in engine-registrations.ts. It polls the session and its conversation every 5 s (jittered backoff after failures, lost contact after 5 in a row). A turn ends on a reply item it has not seen before — never on the lifecycle status, which still shows the previous turn right after a follow-up. Before every follow-up it reads the whole conversation, marks every existing reply as seen, and counts how many earlier user turns still owe a reply (prompts + follow-ups minus replies) — those late replies are consumed, whatever their status, so an earlier or cancelled turn's answer is never shown as the new one. A status of error/suspended with no reply for two polls ends the turn with a row (quota_exhausted gets the out-of-credit sentence) once the turn was seen running, on the first turn, or after a minute of a follow-up that never started. Stop and End both cancel a turn that is in flight; the Send-while-running redirect waits for the cancel before sending.
• Credentials — reasonApiKey (encrypted at rest, redacted from the renderer and the settings CLI) read through the derived provider credential store; readiness is the standard toggle + key.
• Contract — reason-provider-contract.md.

Files

• src/main/services/engines/reason-client.ts
• src/main/services/engines/reason-session-manager.ts
• src/renderer/src/features/settings/sections/accounts/ReasonSection.tsx
• src/shared/providers/registry.ts — the reason descriptor

Related

• devin-provider.md — the other remote REST-poll coding agent, and the template this one follows
• switching-providers.md — every provider and how to switch