Skip to content

Make Codex and Claude Code subscriptions go further: a local model router that gives routine agent work to economical models and keeps your strongest model for the hard parts.

24.9 KB
Raw Blame

Agent integrations and Worker execution

Code map · Architecture · Test map

Discovery, model import, saved model routes, task collaboration and Worker execution are separate capabilities. They share configuration and lifecycle owners; native leaves supply only the ecosystem differences. A successful local check establishes a prerequisite, not a model call, installed Skill invocation or resumable task.

Agent configuration

Capability Shared owners Native detail / evidence
Scan, prepare and import model sources Source admission map, model connection assembly Pi acceptance, DSH acceptance
Configure, edit and restore models Settings transaction, typed facts, Desktop Agent feature Additional native provider guide, saved-model journey, Windows ordinary Pi/DSH clients, Windows Qoder official-account journey
Enable, edit or disable task collaboration independently CLI intent workflow, Skill effects, shared session checks CLI workflow regressions, real main-Agent → public CLI → Worker journey

Qoder/Pi/DSH/OpenCode saved models use one owned provider per Plan with an explicit Responses/Messages choice. Route grants and Gateway trust preserve alias, protocol and receipt authority across publication/restart. work.protocol is the independent frozen Worker choice. Publication budget guards report the actual installed consumers; safe conflict facts retain rejection identity through compensation and client observation. Native defaults and collaboration stay independent; restoration must verify ownership rather than infer it from a provider name.

Codex's connection guidance explains native provider-scoped session discovery before enabling routing. Default on-demand access preserves the ordinary entry for earlier sessions; advanced default takeover first requires configuration restoration. See session recovery. Worker Continue below has its own exact-history binding and does not replace the native /resume picker. OpenCode's startup target binding keeps the physical JSON/JSONC file verified by existing recovery markers; effective model facts also feed the shared configured/drift status. Its bounded Markdown reference reader adds native user Agent/Mode selectors to the same settings dependency checks; removal requires complete references, while retaining selectors permits grant rotation. Worker project ancestry uses the native Git boundary check with the filtered child HOME/XDG/PATH and shared bounded probe process. Both configuration and resource inspection require a confirmed Git stop or the filesystem root within the existing bound; an invalid marker or unavailable Git cannot truncate admission.

Hermes uses an explicit effective profile and one default main-model Plan. Desktop keeps Hermes in the common Agent list; its native host resolves the caller's existing default profile and its details can select another through the same target-read flow before settings become available. The common discovery preference remembers explicit targets as hints, with backend revalidation and per-profile failure isolation. Its bundled native middleware carries the real session into trusted Gateway correlation. The managed provider also uses the same scoped model grant as its native API key for auxiliary Chat requests; global model headers are not a credential carrier. All six supported Agents have independent management and collaboration Skills; shared Skill facts resolve their native roots through the existing ownership/Operation engine. Legacy primary roles retain their original resource meanings; the second Skill has a separate registered effect and per-facet restore reference. Hermes initiates delegation through the existing local Worker CLI and does not become a Worker executor.

Follow a task through its owners

Step / question Production owner Boundary to preserve
Select and confirm an installation Desktop preparation, protected confirmation, launch type, storage Exact canonical components, window-bound single-use confirmation and durable selection; discovery is not authority
Publish the machine-readable request shape Worker producer, Plan producer, CLI generator Typed producer sources generate CLI contracts; retain native-only forbidden fields and adapter requirements
Submit and admit work CLI submission, daemon admission, Application Daemon admission owns durable key/intent deduplication; CLI preserves returned locators and uses no local receipt
Resolve resources and construct a run Installation, native context, profile guide Effective instance HOME/config root supplies resources; per-run overrides supply route, credential and permission policy
Project native context/output budgets Shared budget policy, native projection Preserve the frozen Plan's active-candidate/protocol bounds; Gateway output capping alone cannot prove native compaction limits
Admit and attribute model requests Run authority, Gateway dispatch Sealed Plan, live run, harness, protocol and observation identity must agree
Confirm the native session/model ACP model confirmation, ACP driver Confirm typed mode before the final typed model for OpenCode; confirm the exact native model before prompt; missing capability cannot silently change the route
Continue the same task History binding, resume Restore the exact frozen context/session with a fresh credential; never select the newest history or start a replacement conversation
Start, cancel and finalize processes Executor, OS launcher, finalization Explicit argv/environment/materials and owned process identity; stopping and successful task completion are separate facts
Read, hide, expire or clean up content Reads, Continue admission, maintenance, native cleanup Saved progress is independent of execution/cleanup state; current content permission and exact cleanup ownership still apply; borrowed history is not a deletion target

Ecosystem differences

Ecosystem Resource context Worker transport / native owner History and acceptance
Codex HOME/CODEX_HOME and project Skills Selected ACP adapter; profile Borrowed native history, exact session; native context guide
Claude Code HOME/CLAUDE_CONFIG_DIR and project Skills Selected ACP adapter with protected environment; profile Borrowed transcript, exact identity and flush; native context guide
Qoder HOME/QODER_CONFIG_DIR and project Skills Selected native ACP CLI; profile Borrowed opaque history, exact ACP load; Qoder guide
Pi HOME/PI_CODING_AGENT_DIR, project and installed package Skills Selected npm CLI + Node, bundled SDK→ACP bridge; profile Task-owned v3 transcript, validated before open; Pi guide
DeepSeek Harness (DSH) HOME/DSH_HOME, project and custom Skill roots Selected native ACP CLI and public run patch; profile Task-owned opaque history, exact ACP resume; DSH guide
OpenCode HOME/XDG, explicit config and additive resource roots, project Skills Selected native ACP binary; profile Borrowed opaque SQLite history, bounded format admission and exact ACP load; OpenCode guide

OpenCode's passive Agent and Worker discovery also inspect the official installer's ~/.opencode/bin directory when a GUI launch lacks its shell PATH. Agent discovery keeps the PATH entry first; a saved explicit installation never falls back to a different binary. This does not grant a Worker selection or native-format capability.

The profile guide owns startup flags, credential delivery, native tool permissions and resource restrictions. Do not duplicate the shared admission, process or retention lifecycle for an ecosystem.

On Windows, native launch admission resolves known npm producers to their declared JavaScript entry and selected Node; it never evaluates a .cmd shim. System shell selectors come from the actual Windows system directory. Worker and CPA subscription-source HOME discovery use the same account native-profile selector in the daemon control runtime, while explicit ecosystem configuration roots retain their existing meaning. Managed Claude drive paths project Rust's verbatim spelling only after reparse-free native file identity checks. Discovery and launch share that boundary; the launch retains the selected image and trusted helper handles. UNC and device aliases remain outside this contract. Live checks capture output in private files and retain the process Job until all owned tools stop. Follow those owners for shell, environment, timeout or background-session differences rather than duplicating ecosystem lifecycle code. OpenCode's isolated collaboration probe pins the system Windows PowerShell and quotes the public CLI for that shell. The native tool ID bash does not imply Git Bash. Its npm locator uses the shared declared-producer reader after PATH resolution, then selects the unique native platform package without running a shim.

The Windows Qoder collaboration probe retains the actual Skill directory and file before launching the client. Its receipt binding accepts equivalent disk spellings only after native identity, captured permissions and content checks; it rejects foreign/reparse paths, changed files and split messages. The HTTP peer still requires correlated native Skill and CLI results. No credential contents enter these checks. The private workspace projection binds Qoder and Git Bash to one ordinary drive spelling of the same private directory. Its Bash call uses Git Bash syntax on Windows: the selected CLI's native DOS path is quoted for Bash. The separate PowerShell tool is not that execution boundary; see the probe ownership guide.

The Codex collaboration check selects the native restricted-token sandbox for its Windows read-only process. Its independent write rejection control must observe the actual shell's denied write before accepting Skill reads and execution of the public CLI; a policy rejection before shell execution is not successful sandbox evidence. Its closed tool-output facts are observed before failed receipt checks return, so early rejection retains fixed execution-header facts without logging native output or session identifiers. Nonce-bound script checkpoints retain the entered phase, fixed language mode and numeric failures; they cannot replace the actual denied-write receipt. Follow the read-only control owner for the Windows parse-only gate and shell boundaries.

CLI dependency input projects ordinary local drive paths to the existing canonical selection before transport, retaining file and ancestor leases through the call. Already canonical requests preserve completed-operation replay even after the selected files disappear; Application still owns the canonical tuple, revision and durable transaction. The shared npm reader lets callers inspect original manifest and declared-entry names before reading or canonicalizing them. The Pi locator uses that boundary to bind a generated shim to the package's declared entry and manifest digest without evaluating the shim or changing borrowed ownership. Direct Pi entries retain the single package reader and its nearest-match semantics; original declared-bin names are inspected before canonicalization, so an alias cannot disappear from the identity check.

Pi compatibility is a capability contract

Selected dependency checks allow bounded cold startup: native version reads have a 10-second deadline and the offline Pi SDK check has 15 seconds. This is separate from directory discovery's scan budget and from the admitted task deadline. A timeout does not invalidate the saved selection or consume a submission key. Failures expose a closed check stage and reason through the existing machine error message key, with transient inspection/timeouts marked retryable. No native output, environment value or credential is included. A dependency failure after admission leaves the run Failed and writes an explicitly HiRoute-authored reason to its existing progress stream, never a successful model result. The same selection and exact Continue request can be retried after a transient check.

The existing error envelope and managed progress format remain current; this adds no saved dependency fields, schema conversion or alternate legacy reader.

Runtime admission and the SDK contract bind the selected CLI's declared executable and SDK export from the same package. Production checks interfaces required by the operation, not the acceptance release label:

  • Static import and saved-model configuration do not require Worker session APIs.
  • Collaboration requires the native resource loader and read/bash/public CLI path.
  • New work requires provider/key binding, resources and new-session interfaces.
  • Continue additionally requires native open and the exact supported transcript; missing history never falls back to creating a new session.

The bridge keeps an empty in-memory credential store, offline package discovery and task-owned history. It validates branch-local v3 context edits without rewriting original messages. Process regressions cover creation/cancel/disconnect races; failure ingestion maps closed failure stages without exposing native exception text. These checks do not replace real native compaction, Continue or concurrent-route journeys.

DeepSeek Harness

DSH uses public CLI/configuration and native ACP; there is no SDK import or native history decoder. Static source/configuration rules belong to the native leaf. Local capability checks inspect public composition without model activation and keep collaboration resources independent of model-provider edits.

The Worker profile adds a final run-owned patch while preserving borrowed resource roots. Continue requires advertised session/resume, the exact native/ACP session ID and frozen context/route; DSH interprets its own history. Missing or unusable history fails without session/new. Custom compositions and cross-version continuation require separate evidence; an acceptance pin is not a production version allowlist.

State and lifetime

Codex adapters missing AIR sessionFailure fail during actual initialize, before session creation/load. The ACP owner adds an actionable [HiRoute] reason to the existing Worker progress window; lifecycle flushes it after owned process cleanup. This host explanation is separate from the model result.

Claude terminal finalization keeps ACP live while the exact native transcript drains after result publication and credential revocation. Terminal tool/text admission closes first; bounded history observation controls Continue eligibility. An interrupted observation retains the published result and finalization lease with history readiness false. Follow the ACP guide and causal tests for this ordering; installed native tools and Continue require their own acceptance.

The task root owns context descriptors and exact-session bindings. Run roots own temporary launch materials and credentials. Borrowed HOME/config/history remain native-owned; Continue reads the original descriptor rather than today's service environment. Pi and DSH history is task-owned, but permission to Continue still comes from HiRoute's current task/content state.

Only registered old Codex/Claude tasks may use the legacy private-root recovery path in the compatibility registry. A corrupted current binding is not legacy absence. Resource discovery and native permission policy are separate; using one OS account does not make HOME a sandbox. The legacy scanner encodes filesystem components with / at the retained-path boundary; native Windows separators do not change that portable contract.

Preparing is committed before any native process can spawn. Cancelling an Accepted run therefore atomically records Cancelled with complete cleanup; a stale executor cannot cross the preparation revision check. Once preparation has started, cancellation still needs owned-process stop evidence. Startup may settle the old revision-2 Cancelling record only when the exact record proves that preparation, process binding and prompt intent never occurred.

The shared startup coordinator protects same-daemon Codex borrowed-root initialization and OpenCode database initialization. OpenCode rechecks the captured configuration and read-only database admission after waiting on its frozen database path. Coordination ends at successful ACP initialize, before session creation/load or prompt; tasks remain concurrent. An unconfirmed initializer retains occupancy until owned stop verifies its exact process. Retry Cancel through the existing task action; residual acknowledgement or daemon restart is not proof that the original processes stopped. Other roots and clients retain independent execution.

Representative scenarios

Behavior Start with
Installation confirmation, one-shot authority and exact saved selection Shared session tests, Desktop scenario map
Actual user/project Skills and exact Continue after restart or source replacement Native context journey, ecosystem acceptance guide above
Concurrent routes, cancellation isolation and missing-history rejection Shared boundary journey, assertion guide
Native tool summarization and compaction remain on the frozen route Compaction journey, Qoder native leaf
Token-free startup, foreign settings preserved, exact history and cleanup Profile tests, history tests, material tests
Unconfirmed initializer recovery, credential revocation and owned stop Startup journeys, journal tests, platform tests
Hidden/expired content blocks read and Continue; borrowed neighbors survive Read/Continue journey, maintenance tests

Use the test map and selected ecosystem run guide for inputs, writable roots, required outcomes and cleanup. Shared request changes require the configured Mac desktop-pilot --all-targets compile gate; ignored native targets need explicit execution. Shared Product Session filters are commands::worker_tasks::tests, session::checks::tests and commands::model_connection_web::tests; zero selected tests prove nothing about those consumers.

The OpenCode native Windows leaf is windows_opencode_business.rs, selected by actual_windows_opencode_worker_native_history_and_cancellation in windows_headless.rs. It shares the public routing/Worker receipt oracle and Job cancellation assertions with existing Windows acceptance; it adds no alternative production lifecycle.