Files

T

kami 82674e85c4 feat(inference): capability-aware routing for tool-heavy stages

Add CapabilityAwareRoutingStrategy — it hard-filters to providers that declare every
required capability (like FirstAvailable) but ranks the matches by summed required-capability
score; ties keep list order, so it is a strict superset of first-available. The server now
wires it as the routing policy.

The orchestrator augments a stage's required capabilities with ModelCapability.ToolCalling
when the stage grants tools, so tool-heavy stages route to the best tool-calling model rather
than whichever healthy provider comes first.

Scores come from each provider's declared capabilities(); observed per-model reliability
(GET /metrics/tool-reliability) can feed in later as an additional weight.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-29 11:06:20 +00:00

4.3 KiB

Raw Permalink Blame History

core/kernel — AGENTS.md

Purpose

Top-level orchestration: drives session lifecycle through workflow stages, coordinates retries, manages approval gating, runs static analysis, and provides deterministic replay of past sessions.

Ownership

CORREX kernel team. This is the integration point for all other core/ modules. Changes here affect end-to-end session behavior.

Local Contracts

SessionOrchestrator / DefaultSessionOrchestrator — primary entry point for launching and advancing sessions through workflow stages.
OrchestrationState / OrchestrationReducer (DefaultOrchestrationReducer) / OrchestrationProjector / OrchestrationRepository — standard event-sourcing stack for orchestration state.
RetryCoordinator / DefaultRetryCoordinator — manages retry logic per RetryPolicy.
On a recoverable tool failure dispatchToolCalls feeds the failing tool's argument schema back into context alongside the error (toolArgsHint), so the model self-corrects a malformed call instead of repeating it — the contract stays strict; the feedback is what loosens.
Stages that grant tools (allowedTools non-empty) request ModelCapability.ToolCalling on top of their declared capabilities when routing, so the capability-aware strategy steers them to the best tool-calling model.
ApprovalGateway — kernel-side approval bridge; calls core:approvals engine before executing gated operations. Per-tool gating in dispatchToolCalls builds the ApprovalContext mode from the session's bound operator profile (boundProfile.approvalMode, mapped by approvalModeFor): unset/prompt keeps a human in the loop (default), auto auto-approves up to T2, yolo all tiers, deny blocks above T0. The engine is always consulted (Invariant #4 holds); policy/plane-2 BLOCK stays terminal regardless of mode.
ReplayOrchestrator / ReplayInferenceProvider / ReplayStrategy — deterministic replay of a session from its event log. ReplayInferenceProvider returns recorded responses — no live LLM (Hard Invariant #8).
SubagentRunner / InSessionSubagentRunner — runs sub-agent invocations within an active session.
StaticAnalysisRunner / ProcessStaticAnalysisRunner — runs static analysis tools and records results as events.
StageCheckpointReconciler — reconciles checkpoint state across stage transitions.
JournalCompactionService — triggers journal compaction and emits JournalCompactedEvent.
OrchestratorEngines / OrchestratorRepositories — dependency bundles for wiring.
WorkspaceContext / WorkspaceToolRegistryProvider — workspace-scoped tool registry provisioning.
RepoKnowledgeRetriever — retrieves repo knowledge facts recorded as events (Hard Invariant #9: observations recorded at query time, not re-queried during replay).
BriefEchoDiff / BriefReferenceExtractor — brief grounding utilities.
CritiqueOutcomeCorrelator — correlates critique findings with orchestration outcomes for calibration.
ContextFeedback — feeds context signals back into the orchestration loop.
PreemptRedirect — handles steering/preempt events mid-session.
ReplayArtifactMissingException — thrown when replay requires an artifact that was not recorded.

Work Guidance

Follow the standard Events→State→Reducer→Projector→Repository pattern (see core/AGENTS.md).
DefaultOrchestrationReducer only does state.copy(...). All routing decisions live in DefaultSessionOrchestrator.
Hard Invariant #3: DefaultSessionOrchestrator decides; LLM proposals from core:inference are inputs, not decisions.
Hard Invariant #4: ApprovalGateway must be called before any gated operation. Policy denial is terminal.
Hard Invariant #8: ReplayOrchestrator must never call a live provider. Use ReplayInferenceProvider.
OrchestratorEngines and OrchestratorRepositories are the canonical wiring containers. Add new dependencies there, not as ad-hoc constructor params scattered across callers.

Verification

./gradlew :core:kernel:test --rerun-tasks

Tests in testing/kernel/ (RetryCoordinator, ReplayInferenceProvider, LaunchRegistrationRace, ContextFeedback) and testing/replay/ (session replay, execution plan, refinement, repo knowledge replay).

Child DOX Index

No child AGENTS.md (leaf module).

4.3 KiB Raw Permalink Blame History