feat: add Reasonix engine adapter (DeepSeek-native CLI)

[Aubrey45]

Adds a BYOA engine adapter for Reasonix, the DeepSeek-native coding agent CLI (npm: reasonix). Drives 'reasonix run' headlessly with --permission-mode auto --output-format json, resumes sessions via --resume , seeds the agent home with AGENTS.md (which Reasonix loads as project memory), and reports token usage from the terminal JSON result document.

• engine.ts: ReasonixAdapter (probe/classify/run/seedHome) + reasonixReplyFromJson
• registry.ts: PAIRABLE + EngineId include reasonix
• engines.ts: UI label/bin for Reasonix

Reasonix enforces a workspace-root file-write sandbox + permission gates rather than an OS-level boundary, so it runs under CUMORA_BYOA_ALLOW_UNSANDBOXED=1 like the other compatibility engines.

Tested end-to-end: paired a local computer and ran 8 agents on
reasonix via BYOA — wake → triage → engine turn → reply all worked
(DeepSeek deepseek-v4-flash, ~3s/turn, session resume across daemon
restarts verified).

[yetone]

Thanks — and thank you for actually running it end to end. "8 agents, wake → triage → engine turn → reply, session resume across daemon restarts" is more validation than most engine PRs arrive with, and it is the part I cannot check for you.

Two things before this can land.

1. It conflicts with main. Please rebase.

2. The engine registry guard will almost certainly fail. This touches three files — engine.ts, registry.ts, src/lib/engines.ts — but making an engine runnable means adding its id to about ten hand-kept lists. #114 added scripts/guard-engine-registry.mjs for exactly this, and its header names the failure mode:

Missing one does not error — BYOA_SOURCES in particular is read through normalizeByoaSource(), which maps anything unknown to 'byoa-claude', so a half-wired engine silently bills its runs to Claude.

So a Reasonix turn would be attributed to Claude in llm_ledger and the observability panels, quietly, with nothing failing. Run this after the rebase and it will enumerate exactly what is still missing:

node --import tsx --test server/src/__tests__/guard-engine-registry.test.ts

I would expect at least BYOA_SOURCES, llm-ledger.ts, observability.ts, src/types.ts, src/api/client.ts, src/admin/api.ts, and the ENGINE_VERSION_SPECS entry in cli-version.ts (so the Computers card can report the installed Reasonix version like every other engine).

One design note, not a blocker. Gating Reasonix behind CUMORA_BYOA_ALLOW_UNSANDBOXED=1 is the right call given it enforces a workspace-root sandbox rather than an OS-level one — but please make that explicit where an operator will see it, not only in the PR description. Right now an engine that is installed and detected but never selected is invisible from the app; #138 is landing precisely to surface "installed, but Cumora will not run it here, and here is why". If Reasonix carries a refusal reason in the same shape, an operator who installs it without the opt-in gets told so instead of watching it silently not run.

Rebase, let the guard run, and ping me.

[WhichPaths]

I've written two of these adapters (#99 gemini, #113 qwen) and the registry guard (#114), so I ran this branch through both. CI has not reported on this PR at all, and there are two things it would have caught — one mechanical, one not.

The guard fails on this branch

node scripts/guard-engine-registry.mjs on pr/148 as it stands:

🚨 engine registry is half-wired:
  src/types.ts → the renderer EngineId union
  server/src/agents/computer/cli-version.ts → ENGINE_VERSION_SPECS
  server/src/agents/runtime/byoa-source.ts → BYOA_SOURCES
  server/src/agents/llm-ledger.ts → LlmCallSource
  server/src/agents/observability.ts → TriageSource
  src/admin/api.ts → the admin LlmCallSource union
  src/api/client.ts → ApiTriageSource
  scripts/guard-big-brain.mjs → R4

Most are unions to widen, but two bite at runtime: without 'byoa-reasonix' in BYOA_SOURCES every reasonix run is attributed to Claude in the ledger, and without the R4 alternation a direct spawn of the reasonix binary goes unguarded by the big-brain rule.

input_tokens does not mean what usageFromClaude thinks

The usage field names already match EngineUsage

The names do. The semantics are the other convention, and that is the trap — it is the same one gemini set for me in #99.

From reasonix's own internal/cli/run_output.go, identical at the v1.31.1 you verified against and at today's v1.36.0:

s.usage.InputTokens              += e.Usage.PromptTokens      // → "input_tokens"
s.usage.CacheReadInputTokens     += e.Usage.CacheHitTokens    // → "cache_read_input_tokens"
s.usage.CacheCreationInputTokens += e.Usage.CacheMissTokens   // → "cache_creation_input_tokens"

and internal/provider/provider.go defines those as parts of a whole:

PromptTokens     int  // the complete input
CacheHitTokens   int  // prompt tokens served from cache
CacheMissTokens  int  // prompt tokens not cached, including CacheWriteTokens

So input_tokens == cache_read_input_tokens + cache_creation_input_tokens. normaliseUsage says the same thing from the other side (miss = prompt - hit).

Cumora's contract is the opposite, and states it explicitly in cost.ts:

All counts are the RAW (uncached) counts as the provider reports them: inputTokens excludes the cached portion

usageFromClaude therefore files the whole prompt under inputTokens and files its two halves again under the cache buckets. Second-order: reasonix's cache_creation_input_tokens is CacheMissTokens — ordinary uncached input, not a cache write — so it lands in cacheCreationTokens, which effectiveCostUsd bills at the cache-write premium (1.25× input on the Anthropic rows).

With total = hit + miss, the billed cost becomes

(hit + miss)·in  +  hit·cachedIn  +  miss·cacheWrite

where it should be miss·in + hit·cachedIn. Every cached token is charged an extra full input rate, and every fresh token is charged the write premium instead of the input rate. cacheHitRate is understated by the same construction, since its denominator is inputTokens + cachedInputTokens and inputTokens already contains the cached ones.

The reasonix fields map onto EngineUsage cleanly once read the other way — no subtraction needed, because the miss bucket is the fresh input:

// reasonix reports Anthropic's field NAMES with OpenAI's semantics:
// input_tokens is the whole prompt; the two cache fields are its parts, and
// cache_creation_input_tokens is CacheMissTokens (uncached input), not a
// cache WRITE. Cumora's cache-write bucket carries a price premium, so the
// raw document must not be passed through.
const hit = num(obj.usage?.cache_read_input_tokens)
const miss = num(obj.usage?.cache_creation_input_tokens)
const usage: EngineUsage = {
  input_tokens: miss,                   // fresh input
  cache_read_input_tokens: hit,
  cache_creation_input_tokens: 0,       // reasonix does not report writes separately
  output_tokens: num(obj.usage?.output_tokens),
}

usageFromOpenAI in cost.ts exists for exactly this class of provider, and gemini needed the same treatment in #99 — worth a line of comment either way, because the field names will keep inviting the pass-through.

Everything else read well to me: leaving reasonix out of SANDBOXED_ENGINE_IDS is right given the workspace-root sandbox, the --resume handling matches the one-shot pattern, and reasonixReplyFromJson fails loudly on a non-result document instead of guessing.

[yetone]

Thanks for this — the adapter itself is good work. reasonixReplyFromJson handles the cases that matter (empty output, non-JSON output, a JSON document that isn't a result, is_error with and without detail), the session-resume path is modelled the same way the other one-shot engines do it, and the comment explaining why reasonix stays out of SANDBOXED_ENGINE_IDS is exactly the reasoning I'd want recorded there. The --model handling — no flag at all when the caller has none, so the probe exercises the operator's real default — is a detail most adapters get wrong on the first pass.

I can't merge it yet. Two blockers, one of which is mechanical:

1. No CI has ever run on this branch, and it now conflicts with main. GitHub reports zero check runs and CONFLICTING / DIRTY. I merged 16 PRs today, several of them into server/src/agents/computer/engine.ts, so please rebase onto current main.

2. Adding an EngineId is a cross-cutting change, and this PR only covers 3 of the ~13 places that need it. npm run guard:engine-registry exists precisely to catch this; run it locally after the rebase and it will list them. From reading scripts/guard-engine-registry.mjs against your diff, these are still missing:

• src/types.ts — the renderer EngineId union
• server/src/agents/computer/cli-version.ts — ENGINE_VERSION_SPECS (without it the Computers tab can't report the installed reasonix version)
• server/src/agents/runtime/byoa-source.ts — BYOA_SOURCES must gain 'byoa-reasonix'. This is the one that fails silently: normalizeByoaSource() maps anything unknown to 'byoa-claude', so every reasonix run still gets billed and recorded — just attributed to Claude in the ledger.
• server/src/agents/llm-ledger.ts — widen LlmCallSource with 'byoa-reasonix'
• server/src/agents/observability.ts — widen TriageSource
• src/admin/api.ts — widen the admin LlmCallSource
• src/api/client.ts — widen ApiTriageSource
• server/src/agents/computer/registry.ts — ENGINE_BINS, and the r.engine === '<id>' default-model fallback in listAgentsForComputer

Separately, and not covered by the guard: server/src/agents/computer/model-catalog.ts declares const PRESETS: Record<EngineId, EngineModelCatalog>. Widening EngineId without adding a reasonix entry there is a hard server:typecheck failure, so that one will block the build outright.

3. Please add a unit test for reasonixReplyFromJson. server/src/__tests__/agents-computer-engine-qwen.test.ts is the precedent — a parser that turns engine stdout into a reply, usage and an error is exactly the thing that breaks quietly when the upstream CLI changes its output shape, and it's pure, so it's cheap to test. Cover at minimum: a success document, is_error: true with and without an error string, non-JSON stdout, and empty stdout.

One question rather than a blocker: the doc comment says the contract was verified against reasonix v1.31.1, and you've run 8 agents on it end to end — that's more validation than most adapters arrive with, thank you. Given that, could you also add a reasonix entry to SECURE_ENGINE_MIN_VERSIONS if there's a floor below which the --output-format json contract differs? If there isn't one, say so in the PR and I'll take it as-is.

Work through the guard, get the checks green, and I'll merge it.

[yetone]

Following up on my review from yesterday — status unchanged, so this is just a nudge rather than new feedback.

The branch is still CONFLICTING and still has zero CI runs, and I merged another six PRs into main today (#224, #216, #215, #177, #187, #222), so it has drifted further. The checklist in my earlier comment is still the work: rebase, then npm run guard:engine-registry will enumerate the ~10 registration points an EngineId needs beyond the 3 this PR touches, plus the PRESETS entry in model-catalog.ts that server:typecheck will demand, plus a unit test for reasonixReplyFromJson.

The adapter itself is still good work and I'd like to land it — it just needs to be wired in everywhere before it can be. Ping me when CI is green.

[yetone]

Following up on my earlier note: this still cannot merge, and the conflict has grown. Against current main it now conflicts in three files:

• server/src/agents/computer/engine.ts
• server/src/agents/computer/registry.ts
• src/lib/engines.ts

main has moved substantially since you opened this — #235 (per-engine default models) and #231/a702da0 (per-engine session stores, structured engine failure kinds) both landed in exactly these files. A rebase now will be less work than a rebase later, and I would rather merge this than let it keep drifting.

When you rebase, two things to fold in:

1. Add reasonix to the R4 binary list in scripts/guard-big-brain.mjs so the guard covers it too. feat: add ZCode as a BYOA engine via the zcode-acp-server ACP bridge #247 does this for its engine and it is the right pattern — the guard should know about every engine binary.
2. engine.ts now has classifyEngineFailure / engineFailureOf. Map a missing-session condition to resume-not-found if the DeepSeek CLI can report one; otherwise leave it unknown, which is deliberately never auto-replayed.

The adapter itself looked reasonable when I read it. It is only the drift that is blocking.