kami
1b58bc325e
This branch's uncommitted WIP, committed together (entangled at file level). Distinct pieces of work: Freestyle QA fixes (this session): - FileEditTool: pre-validate replace anchor in validateRequest — reject a missing/ambiguous target BEFORE the approval gate, mirroring read/write's file-not-found / read-before-write pre-checks. Shared not-found/ambiguous messages between validate and execute so they can't drift. - PlanGrounder: add `scanned` flag; when no RepoMapComputedEvent was recorded, repoMapPaths is "unknown" not "empty workspace" — skip scope grounding (which proves a path ABSENT) so real paths (apps/server/**) aren't falsely rejected. Build-manifest check still runs. - FreestyleDriver: wire scanned=(repoMap!=null); on plan rejection emit a session-terminal WorkflowFailedEvent so a rejected run reads FAILED, not the COMPLETED-lie (last verdict was the planning-phase WorkflowCompleted). - ServerModule: resolve project-memory workspace root from the session's bound workspace (sessionWorkspaceRoot) instead of boot-static pm.repoRoot(), fixing the workspace-binding divergence (correx vs empty scratch dir). Retire tracked in Vikunja #266. - LaunchRegistrationRaceTest: join registered jobs before asserting launchCount — computeIfAbsent returns the Job immediately but the fire-and-forget launch body lagged awaitAll (the 49-vs-50 flake). ACR concept-compiler experiment (pre-existing WIP on this branch): - ExecutionPlanCompiler/Model/PlanLinter, #264 needs-seam (sessionArtifacts), LSP diagnostics subsystem (LspDiagnosticEvents/Runner/Lsp4j), BootWorkspace, config surface, workflow prompts/schemas, orchestrator advance-don't-rerun. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
58 lines
5.3 KiB
Markdown
58 lines
5.3 KiB
Markdown
# 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.
|
|
- `LspDiagnosticsRunner` — injected pull-diagnostics seam; diagnostics are filtered to stage-written files, recorded, and enforced before build/review.
|
|
- Review→rework loops use the configured three-cycle default, then route accumulated notes to recovery once and fail if the fixed DoD still cannot be approved.
|
|
- `StageCheckpointReconciler` — reconciles checkpoint state across stage transitions.
|
|
- Capability-gated failures first retry in place when the stage holds the required tool; an unchanged-fingerprint gate-budget exhaustion routes to the recovery/intent-holder stage when one is available, so capability possession alone cannot cause a frozen owner loop to fail the workflow.
|
|
- Three repeated `REFERENCE_EXISTS` blocks for the same build prerequisite within one stage become a `workspace_precondition` gate failure, which is eligible for file-write recovery rather than remaining disconnected tool-call noise.
|
|
- Every stage receives a small curated operating-guidance system entry: verify observed state, create required project setup, and resolve necessary scope edges without re-deliberating.
|
|
- `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
|
|
|
|
```bash
|
|
./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).
|