inferrouter 0.1.7

Loop-aware router and tracing for coding agents (Claude Code, Codex). Routes workflow steps by phase and evidence and records hash-only cost/cache/verification/outcome receipts.

InferRouter

Phase-, risk-, and role-aware model routing with joined cost and verification receipts for coding agents such as Claude Code and Codex.

Status: alpha package; production-live fixed four-phase MVP Worker. The package, import, and CLI are all inferrouter. InferGuard is a separate diagnostics product.

Core workflow

prompt + bounded repository context
→ phase + risk + required agent role (Fusion/semantic policy)
→ eligible model + provider + billing lane + reasoning effort
→ readable frontier plan
→ cheaper implementation steps or subagents
→ deterministic local verification
→ bounded retry, escalation, or re-plan
→ independent frontier review
→ accepted or rejected result
→ one joined token, cost, latency, and verification receipt

Primary metric: cost per accepted patch at required quality and p95/p99 full-loop latency.

The Devin Fusion-style role decision is the first hard gate. OpenRouter-style provider, billing, and runtime selection happens only inside the eligible role set. Semantic-router signals are explicit Boolean eligibility gates, not a single prompt-complexity score. OpenRouter Fusion panel/judge deliberation is a future optional escalation lane, not the default path. Claudex is an optional compatibility bridge and is not part of this core router path.

Current milestone

Built:

request-level gateway and protocol adapters
hard tenant/capability/protocol/tool/context/latency gates
provider cooldown and bounded affinity
pre-first-byte fallback
spend controls and hash-only receipts
loop, verification, and outcome ledgers
TaskEnvelopeV1 and ContextFingerprintV1
cross-runtime canonicalization and tenant-scoped fingerprints
0.1.6 published PyPI rollback baseline: canonical Fusion/semantic role gate,
bounded repository planning context, and joined workflow usage/cost
0.1.7 candidate adds first-class OpenRouter routing, current OpenCode usage,
and the installed deterministic plus opt-in live mixed-lane release gate
production fixed four-phase Worker 89f59b62 at 100%, source annotation 34a2d76,
with rollback Worker 84992285 retained at 0%
optional experimental Claudex compatibility path: isolated opt-in launcher,
15-case deterministic evaluator, and explicit bounded live canaries/benchmark

Next:

1. merge and trusted-publish the verified 0.1.7 candidate
2. clean-install the public artifact and rerun the installed mixed-lane gate
3. expand accepted-task economics and failure drills without enabling unproven lanes

inferrouter==0.1.6 remains the latest public package. Its exact-source Worker is live at 100% after three 80/80 candidate reports, 4/4 real-Codex conformance with ten zero-fallback receipts, a passing Terra-plan/ChatGPT-implementation/local-verify/GPT-5.5-review workflow, a zero-error 10% traffic sample, a successful rollback/forward-restore rehearsal, an isolated 0.1.6 -> 0.1.5 -> 0.1.6 package rehearsal, and post-promotion convergence. The public 0.1.6 wheel then passed a clean install, workflow, downgrade to public 0.1.5, forward restore, and a second workflow run. The 0.1.7 candidate separately passed one accepted live universal workflow: exact OpenRouter Opus 4.8 planning, lower-cost exact Sonnet 4.6 execution, sandboxed local verification, independent exact Opus review, zero fallback, 3,682 tokens, $0.037006 provider-reported cost, and one valid 26-event receipt. Public package publication and clean-install proof are still pending. Claudex remains experimental, separately installed, and never a core/default lane.

Read first

1. Current SSoT
2. Universal coordinator executable contract
3. Product architecture
4. Progress tracker
5. Machine-readable status database
6. Archive lessons and integration plan
7. Historical pre-0.1.4 ship-now prompt
8. Touchdown Labs research bridge
9. Experimental Claudex compatibility bridge
10. Packaged Claudex compatibility workflow

Use docs/TOUCHDOWN_ROUTER_RUNBOOK.md for current Worker operations, docs/production-runbook.md for the explicitly labeled legacy offline/replay surface, and docs/ROUTER_MASTER_SOT.md plus audit files for chronology.

Repository boundary

OCWC22/inferrouter
  = product/runtime authority

OCWC22/Touchdown-Labs
  = company/research authority

InferGuard
  = separate diagnostics product

See TOUCHDOWN_LABS.md.

Install

uv tool install .
# or
pip install .

Install the current release with:

uv tool install 'inferrouter==0.1.6'

PyPI SHA-256: wheel 9a1df374f7ceb4d130b8467f4391f1ea41e6f1f561046b130f568e41ba29a08d; sdist ea96e631dd954857e995763f89b1762b0c95e9288a1c2fc3846014343067f876.

For rollback, 0.1.5 remains immutable. Its published wheel SHA-256 is cb332238395112d51fd9fb59712651507d53e2a2fcdee1f689bcf6dbc1762844; the sdist SHA-256 is e5d813f423b0614aafe278ee31d28e31a65d37aff41a9806aeb425cd9dd3cd68. Use that release as the isolated package rollback baseline.

This installs inferrouter and inferrouter-routerd.

Universal coordinator

The coordinator is the cross-provider workflow the product is aiming at. It is explicitly invoked with one CLI/SDK goal and records whether that goal came from Codex, Claude Code, OpenCode, or an API/SDK caller; it does not auto-intercept native client tasks. All four entry labels use the same bounded state machine. The planner emits a validated DAG; every step is routed at a checkpoint to a configured local, subscription, API, GMI, or registered OpenAI-compatible lane. Local verification and an independent reviewer must pass before acceptance. The automatic planner prompt contains only content-free counts, hashes, and root fingerprints—not repository-controlled filenames or raw README, AGENTS, manifest, status, or diff contents. Needed file inspection uses read-only tools. The graph's operator-goal SHA-256 is trace binding only; a separate, explicit per-run write gate is enforced outside the planner. Incremental Codex attribution reconstructs model state only from bytes at or before the saved tail offset, so later model context cannot relabel earlier token usage.

Prove the core policy and executor plumbing offline with the deterministic installed-artifact evaluator. This uses the real coordinator, receipt store, subprocess adapters, Git inspection, and sandboxed verifier, but fixture model responses; it does not claim live provider authentication, entitlement, model quality, or subscription billing:

python -m inferrouter.evals.production_workflow --json

# Release gate: fixture-safe by default; --live makes paid OpenRouter calls.
inferrouter eval mixed-lane --json
OPENROUTER_API_KEY=... inferrouter eval mixed-lane --live --json

inferrouter coordinator --print-spec

# Configuration/auth only. No model probe.
inferrouter coordinator doctor --json

# Also prove exact model identity, entitlement, and liveness for configured remote lanes.
inferrouter coordinator doctor --live --json

# Preflight and rank without a model/tool call.
inferrouter coordinator run \
  --goal 'Implement the requested change and prove it with tests.' \
  --workdir . \
  --entry-client opencode \
  --dry-run \
  --json

# Execute after at least one planner, one implementation lane, local verification,
# and an independent reviewer are ready.
inferrouter coordinator run \
  --goal 'Implement the requested change and prove it with tests.' \
  --workdir . \
  --entry-client opencode \
  --allow-writes \
  --json

Workspace writes are denied by default. --allow-writes is the operator's per-run authorization for planner-selected worktree edits; the goal hash is trace binding only and cannot grant that permission.

The packaged profile references credential environment-variable names; it does not contain credential values. Codex uses the isolated ~/.touchdown/subscription_codex_home. Claude Code uses its native subscription login with ambient API/cloud credentials removed. API and registered endpoint keys resolve only inside their executor. Fable is excluded unless an exact-model live probe succeeds; a silent native model fallback fails the lane.

OpenCode provider path

The production-proven OpenCode path in this release is OpenCode to OpenRouter, not OpenCode directly to the Touchdown Worker. Keep the key in the environment and use an OpenCode custom provider such as:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "touchdown-openrouter": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Touchdown OpenRouter",
      "options": {
        "baseURL": "https://openrouter.ai/api/v1",
        "apiKey": "{env:OPENROUTER_API_KEY}"
      },
      "models": {
        "anthropic/claude-opus-4.8": {"name": "Claude Opus 4.8"},
        "anthropic/claude-sonnet-4.6": {"name": "Claude Sonnet 4.6"}
      }
    }
  }
}

opencode run --pure --format json \
  --model touchdown-openrouter/anthropic/claude-sonnet-4.6 \
  'Implement the bounded task and run its tests.'

This direct provider path emits current OpenCode token and reported-cost events. It is not automatic checkpoint routing by itself; use inferrouter coordinator run --entry-client opencode for the full plan/execute/verify/review workflow. Direct OpenCode-to-Worker streaming/tool execution remains disabled because its current request shape fails upstream compatibility.

Private handoff text is stored outside the writable repository under ~/.touchdown/inferrouter/coordinator/<run-id>/ with owner-only permissions. events.jsonl contains only hash-linked metadata. Check it independently with:

inferrouter coordinator verify-receipt \
  ~/.touchdown/inferrouter/coordinator/<run-id>/events.jsonl

That command proves canonical structure and hash-link integrity. The chain is not yet signed or externally anchored, so a process with the same filesystem ownership could still rewrite and rehash the entire history. Do not treat it as third-party authenticity proof until a frozen terminal receipt is anchored.

The full behavioral contract is inferrouter/workflows/UNIVERSAL_COORDINATOR_WORKFLOW.md.

Configured-only doctor proves a viable local workflow shape, not live readiness. doctor --live probes configured remote lanes and returns top-level ok only when it can prove an exact-model planner, a mutating executor, local verification, and an independent exact-model reviewer. Operators must still inspect every intended lane because top-level success does not mean every configured lane passed. Codex requires a separate isolated exact-model canary because the live doctor does not call Codex.

Phase-routed Codex workflow

Install the isolated gateway profile once, then run one bounded coding task:

inferrouter install codex

mkdir -p ~/.touchdown/subscription_codex_home
chmod 700 ~/.touchdown/subscription_codex_home
CODEX_HOME=~/.touchdown/subscription_codex_home codex login

inferrouter workflow \
  --goal 'Implement the requested repository change and preserve existing behavior.' \
  --verify 'python3 -m pytest -q'

The command uses the Touchdown API gateway for read-only planning, a dedicated persistent Touchdown Codex home for ChatGPT-subscription implementation, the operator-supplied local command for verification, and the API gateway for read-only final review. The dedicated profile gets its own separate initial ChatGPT login, so OAuth refreshes persist there and normal ~/.codex is never used as a workflow profile. Revocation or logout can require signing in again. The workflow fails unless implementation, verification, repository/config integrity, and the exact final review verdict all pass. This MVP is for trusted/private repositories; implementation tools can read their own dedicated Codex authentication file.

The executable Markdown contract is inferrouter/workflows/PRODUCTION_PHASE_WORKFLOW.md. Print the contract shipped in the installed package with:

inferrouter workflow --print-spec

Coding-loop quickstart

inferrouter loop goal \
  --loop-id fix_auth_tests \
  --goal "auth tests pass" \
  --verify "python -m pytest tests/auth -q" \
  --max-turns 5 --agent codex \
  -- codex exec "fix the failing auth tests"

Hash-only local evidence is written under .touchdown/:

.touchdown/loops/loop_runs.jsonl
.touchdown/loops/verifications.jsonl
.touchdown/session.json

Other commands:

inferrouter loop turn --agent generic -- <command>
inferrouter loop report [--loop-id L]
inferrouter loop usage [--by loop|task|phase|provider|model]
inferrouter doctor --split
inferrouter --help

Claude Code and Codex launchers

inferrouter claude -- -p "summarize the failing test log"
inferrouter codex -- summarize the failing test log

The split proxy is explicit and self-managed:

inferrouter proxy status
inferrouter proxy stop

The gateway routes API requests. It does not silently intercept every local prompt and does not create subagents by itself.

An explicitly unsupported compatibility option can run the Claude Code shell against Codex through a separately installed Claudex proxy:

inferrouter claudex setup --acknowledge-unsupported --model gpt-5.6-sol
inferrouter claudex doctor
inferrouter claudex launch -- -p "summarize the failing test log"

# Deterministic, no-network compatibility gate. Expected today: 15/15.
inferrouter eval claudex --out-dir out/evals/claudex

# Plan only by default; no paid or subscription request.
inferrouter benchmark claudex

# Explicit unsupported live gates. Requires exact reviewed Claudex and auth.
inferrouter eval claudex --live --acknowledge-unsupported
inferrouter benchmark claudex --live --acknowledge-unsupported --runs 3

The merged 0.1.6 source passes 1,038 Python tests, the core deterministic phase-routed workflow eval, the Claudex 15/15 offline rubric, Twine validation, and isolated Python 3.11 wheel, sdist, and uv tool smokes. CI repeats the installed core workflow eval on macOS and makes the existing required python-tests context fail if either the unit or workflow gate fails. The fixed four-phase Worker path is live-proven; the universal coordinator's live mixed-lane authentication, quality, and economics proof remains missing.

This is not automatic routing and is never installed or enabled by default. The InferRouter guard rebuilds the child environment from a strict non-secret allowlist; redirects Claudex, Claude, Codex, XDG, and temporary-file roots under ~/.touchdown; caps runtime and retries; denies known built-in Agent/Task/workflow/cron fan-out tools; and writes a hash-only receipt. It does not enforce a true global agent, process, request, or token cap. This is not an OS sandbox: tools can still reach files under the inherited HOME, and Bash/process/request/token fan-out is not proxy-enforced. See the compatibility boundary and production rubric.

Production gateway

The documented gateway is:

https://touchdown-router.odd-star-67a4.workers.dev

Request path:

customer request
→ tenant/capability/protocol/tool/context/latency gates
→ cheapest viable configured route
→ bounded provider fallback
→ protocol-correct stream
→ hash-only receipt

Repository main may be ahead of the live Worker. A merged feature is not a deployment claim. Use the progress tracker and runbook for current live evidence.

Safety defaults

• Package-local commands make no live provider call unless explicitly configured.
• Raw prompts, source code, tool content, outputs, and credentials stay out of receipts and reports.
• Unsupported protocol semantics fail closed.
• Fallback happens only before client-visible output.
• Cost never overrides tenant, safety, capability, protocol, tool, context, or latency eligibility.

Development

python -m pytest -q
uv build
bash scripts/package_smoke.sh

The import package, distribution name, and CLI command are all inferrouter.

Contributing

See CONTRIBUTING.md, Code of Conduct, and SECURITY.md.

License

Apache License 2.0. See LICENSE and NOTICE.