claude
6a8a7b31c1
Three generic harness fixes from the web-ui postmortem dataset. Nothing here keys on a language, framework, build tool or task type. 1. Failure attribution. WorkflowFailedEvent carries one primary FailureAttribution (AGENT | HARNESS | WORKFLOW | ENVIRONMENT | PROVIDER | OPERATOR | UNKNOWN), defaulted to UNKNOWN so pre-field events replay unchanged. FailureAttributor is the deterministic reason->layer mapping, used both at emission and when classifying history, so the baseline and the live metric are one measurement. Emission sites set it: failWorkflow derives from the reason unless the caller knows the layer, cancellation is OPERATOR, the server catch-all falls back to HARNESS, a grounding-rejected plan is AGENT. Multi-cause chains stay on FailureTicketOpened — no second causal structure. GET /metrics/failure-attribution (FailureAttributionInspectionService, mirroring ToolReliabilityInspectionService) reports counts, share, UNKNOWN share, the preserved reasons and the ticket categories from the same sessions. Read-only: historical events are classified at READ time and reported as `inferred`, never written back over an append-only log. Baseline over the local log, 122 terminal failures: AGENT 51 (41.8%), OPERATOR 28 (23.0%), WORKFLOW 19 (15.6%), PROVIDER 15 (12.3%), HARNESS 6 (4.9%), ENVIRONMENT 3 (2.5%), UNKNOWN 0. 2. The `~` guard bug. ToolPath is now the ONE canonical normalization rule (expand a leading `~`/`~/`, keep absolutes, anchor relatives on the session working dir). Every filesystem tool, all six plane-2 path rules and the approval preview resolve through it, so policy and existence checks inspect the path the tool will operate on. `~/.gradle/init.d/offline.gradle` used to resolve to `<workspace>/~/.gradle/...`: reported non-existent AND in-workspace, so the reference gate called a real file a hallucination and the out-of-workspace prompt never fired. Containment and external-read approval behaviour are unchanged — the expanded path is simply outside the workspace, where it always belonged. 3. file_copy (#713). A first-class tool with the writer's jail, tier, receipt, replay and CAS pre/post images; static and binary assets no longer move through the model's token stream. Needed one generic split: ParamRole.SOURCE_PATH marks a path a call reads FROM, so containment gates judge both params while write-target gates (read-before-write, stale-write, write scope, write manifest) judge the mutated one. ReadBeforeWriteRule exempts any call declaring a SOURCE_PATH: its content comes from disk, not from memory, and requiring a read of a binary is unsatisfiable. Existing tools declare no SOURCE_PATH, so their behaviour is byte-identical. Tests: ToolPathTest (9), FailureAttributionTest (10), PathNormalizationRuleTest (6), FileCopyToolTest (10), plus a home-relative FileReadTool read. ./gradlew check green. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
45 lines
2.8 KiB
Markdown
45 lines
2.8 KiB
Markdown
# core/tools — AGENTS.md
|
|
|
|
## Purpose
|
|
|
|
Tool contract, registry, executor, and receipt tracking: defines the `Tool` interface, manages tool registration, executes tools within their declared tier, compresses tool output, and projects tool invocation history via the standard event-sourcing stack.
|
|
|
|
## Ownership
|
|
|
|
CORREX kernel team.
|
|
|
|
## Local Contracts
|
|
|
|
- `Tool` — primary interface all tools implement. Must declare `Tier` (from `core:events`).
|
|
- `ToolRegistry` — holds all registered tools for a session; looked up by name.
|
|
- `ToolExecutor` — executes a `Tool` given a `ToolRequest`, records `ToolEvents` in `core:events`.
|
|
- `ToolResult` — sealed result type: success with output, or failure with error.
|
|
- `ToolState` rebuilt from `ToolEvents` via `DefaultToolReducer` + `ToolProjector`.
|
|
- `DefaultToolRepository` wraps `EventReplayer<ToolState>`.
|
|
- `ToolInvocationRecord` / `ToolInvocationStatus` / `ToolCallAssessmentRecord` — history types.
|
|
- `FileMutationRecord` — records file-affecting side effects.
|
|
- `FileAffectingTool` — extended `Tool` interface for tools that write files; must declare `affectedPaths`.
|
|
- `OutputCompressionSpec` / `ToolOutputCompressor` / `DeclarativeCompressor` — compress large tool outputs to fit token budgets (Hard Invariant #6: compressed output is informational; original events are preserved).
|
|
- `ParamRole` — annotates tool parameter semantic roles: `PATH` (the path a call acts on / mutates), `SOURCE_PATH` (a path it only reads from while acting on another target, e.g. `file_copy`), `EXEC_COMMAND`, `NETWORK_TARGET`. Plane-2 gates dispatch on these, never on tool names.
|
|
- `ToolPath` — the ONE canonical path normalization rule: expands a leading `~`/`~/` to the user home, keeps absolute paths, anchors relative paths on the session's working dir (never the JVM cwd). Every filesystem tool and every plane-2 path rule must resolve through it so policy checks and execution act on the same path. `~other/…` is deliberately NOT expanded.
|
|
- `ValidationResult` — result from tool-level parameter validation (pre-execution check).
|
|
- Hard Invariant #5: all tool side effects are captured in events. Silent execution is not allowed.
|
|
|
|
## Work Guidance
|
|
|
|
- Follow the standard Events→State→Reducer→Projector→Repository pattern (see `core/AGENTS.md`).
|
|
- `DefaultToolReducer` only does `state.copy(...)`.
|
|
- `ToolExecutor` must record a `ToolExecutedEvent` (or equivalent) before returning, even on failure.
|
|
- Output compression must not discard the original event — only produce a derived summary alongside it.
|
|
- New tools implement `Tool` (or `FileAffectingTool`) and register in `ToolRegistry`. Do not instantiate tools inside `ToolExecutor`.
|
|
|
|
## Verification
|
|
|
|
```bash
|
|
./gradlew :core:tools:test --rerun-tasks
|
|
```
|
|
|
|
## Child DOX Index
|
|
|
|
No child AGENTS.md (leaf module).
|