inferrouter 0.1.5

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

Loop-aware model routing and hash-only evidence for coding agents such as Claude Code and Codex.

Status: alpha. The package, import, and CLI are all inferrouter. InferGuard is a separate diagnostics product.

MVP

one coding task
→ one observed coding loop
→ safe model/provider choices by phase
→ tools and tests
→ verification
→ accepted or rejected result
→ one complete hash-only receipt chain

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

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.5 universal coordinator source candidate: typed lanes, bounded DAGs, external
executors, checkpoint re-planning, independent review, and hash-linked receipts

Next:

1. freeze the versioned candidate commit and repeat the green release ladder in CI
2. authenticate and live-probe at least two independent execution/review lanes
3. run mixed-lane canaries, failure drills, and package rollback rehearsal
4. measure accepted-task cost and latency against the fixed workflow baseline
5. publish, reinstall from PyPI, repeat the canary, then promote proven lanes

The source candidate is versioned 0.1.5 in the worktree. That is not a PyPI or production-deployment claim. The current published 0.1.4 boundary remains the fixed four-phase workflow described below until the coordinator package, live-canary, and rollback receipts complete.

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

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 .

The current published release is:

uv tool install 'inferrouter==0.1.4'

The full Python and Worker suites, strict Worker dry-run, wheel, sdist, Twine, isolated pip installs, and isolated uv tool package smokes pass locally. The candidate must repeat those gates in CI, be live-canary tested, be rolled back to the command above, and be restored before it can be published as 0.1.5.

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, or an API/SDK caller; it does not yet auto-intercept native Codex or Claude tasks. All three 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.

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 codex \
  --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 codex \
  --json

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.

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.

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.