(MOT-4391) feat(reflex): local tool-router worker with shadow-mode calibration

[rohitg00]

Refs MOT-4391

What

A new reflex worker: a local tool router for the harness loop. A 14MB on-device model (cactus-needle, CPU-only, Apache-2.0 weights) indexes the live engine function catalog and proposes the next function call for a natural-language objective, with a calibrated confidence score per proposal. It proposes only. Every call still flows through the normal policy, approval, and dispatch path, so the worker adds no execution authority.

Surface

• reflex::route { objective, observation? } returns { type, calls: [{function, payload}], confidence, reasoning, latency_ms }. type is call, respond, abstain, or refuse; low confidence means escalate to a frontier model. Passing the previous result as observation continues a chain.
• reflex::index::status / reflex::index::refresh. The index follows the engine via the engine::functions-available trigger (debounced, schema-fingerprinted, persisted across boots so warm re-init is instant).
• Shadow mode (on by default, shadow.enabled: false to disable): binds harness::hook::pre-generate and post-generate with on_error: fail_open, observe-only. For every real generation it records its own proposal beside the frontier model's actual calls (unwrapping agent_trigger, feeding prior function results back as observation) into a local jsonl that doubles as fine-tune data. reflex::shadow::report aggregates turn-level agreement per confidence bucket plus how many frontier generations went to catalog discovery.

Why

Measured on a live rig (207-function catalog) before this PR:

• Live traffic, 12 turns, 36 scored generations across three frontier models: every proposal at confidence >= 0.6 that named a call matched the frontier's actual call (4/4, zero wrong); all mismatches sat below 0.4; the lowest bucket abstained 20/20. The confidence gate is the product; thresholds come from the shadow report on your own traffic.
• Discovery overhead is real: 7 of 12 turns spent 11 frontier generations on engine::functions::list/info. Example: for "List the queue topics", the frontier model needed three generations (list, info, call) to reach engine::queue::list_topics; the router proposed the identical call in one local pass at 0.65.
• Args are often exact when it fires: state::delete {key, scope} proposed correctly at 0.80 over the bus.

Onboarding checklist (docs/sops/new-worker.md)

• iii.worker.yaml (python bundle, tags), pyproject.toml manifest, config.yaml (Path A operator defaults with env overrides), README.md per worker-readme.md, non-empty tests/
• Typed request and response schemas on every registered function
• Modules table row in the repo README
• Root iii-permissions.yaml: shadow hook targets and the catalog-change handler denied (agents must not forge calibration rows); route / index::status / shadow::report allowed
• skills/SKILL.md (when to use, boundaries, no schema dumps)
• .github/release-workers.yaml entry; release_catalog.py validate passes
• Gates run locally: ruff check, ruff format --check, pytest (13 tests), validate_worker.py

Notes for review

• The vendor runtime is process-global (no session handles), so the worker serializes model calls behind one lock and resets per decision; transcript memory stays in the harness.
• run()-style local execution in the vendor SDK is deliberately unused; complete() proposals only.
• First release should go out with registry tag next per SOP section 9.

Follow-up phases tracked as sub-issues of MOT-4391: confidence-gated decide path in the harness (MOT-4392), ExposeMode::Retrieved (MOT-4393), per-rig LoRA from the shadow corpus (MOT-4394).

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
workers	Ready	Preview	Aug 11, 2026 1:49pm
workers-tech-spec	Building	Preview	Aug 11, 2026 1:49pm

[coderabbitai]

Warning

Review limit reached

@rohitg00, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 59 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 3c2e43b0-8a61-471f-b7f6-c19e63bbd8e4

📥 Commits

Reviewing files that changed from the base of the PR and between 2d53352 and facb325.

📒 Files selected for processing (19)

• .github/release-workers.yaml
• README.md
• iii-permissions.yaml
• reflex/README.md
• reflex/config.yaml
• reflex/iii.worker.yaml
• reflex/pyproject.toml
• reflex/skills/SKILL.md
• reflex/src/__init__.py
• reflex/src/config.py
• reflex/src/main.py
• reflex/src/router.py
• reflex/src/schemas.py
• reflex/src/shadow.py
• reflex/tests/__init__.py
• reflex/tests/test_config.py
• reflex/tests/test_router.py
• reflex/tests/test_schemas.py
• reflex/tests/test_shadow.py

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

skill-check — worker

0 verified, 58 skipped (no docs/).

Layer	Result
structure	✓
vale	✓
ai	✓
render	✓

Four for four. Nicely done.