Files

T

claude 6a8a7b31c1 fix(events,tools,toolintent): failure attribution, one path normalization rule, file_copy (#713 )

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>

2026-08-27 11:57:49 +04:00

3.3 KiB

Raw Blame History

apps/server

Purpose

Ktor HTTP + WebSocket server. Exposes the orchestration kernel to CLI and TUI clients, manages session lifecycle, and streams events over WebSocket.

Ownership

All sources under apps/server/src/.

Local Contracts

HTTP REST routes

GET/POST /sessions — session browse and start (POST accepts an optional intent brief, parity with the WS StartSession)
POST /sessions/{id}/resume — resume a session after restart
GET/POST /tasks — task listing and management
GET/POST /providers — provider configuration
GET/POST /workflows — workflow management
GET /health — health report (probes: event-store, llama-server, disk watermark)
GET /stats — metrics report (MetricsProjection)
GET /metrics/tool-reliability — per-model tool-call validity across the event log (ToolReliabilityInspectionService); groundwork for capability-aware routing
GET /metrics/failure-attribution — terminal-failure attribution across the event log (FailureAttributionInspectionService): count and share per FailureAttribution layer, the UNKNOWN share, the preserved reasons behind each row, and the FailureTicketOpened categories from the same sessions. Read-only: events recorded before WorkflowFailedEvent.attribution existed are classified at read time by FailureAttributor and reported as inferred, never written back.
Optional [git] transport creates run/<sessionId> from a server-local checkout and pushes it at terminal state; clients review with ordinary Git and never supply a remote URL as cwd.
Repo-map L3 embeddings use bounded, recorded source descriptors (module/package, imports, leading purpose comment, symbols); raw file bodies are never embedded. Their versioned repomap:v2 namespace forces a one-time re-embed when the semantic document format changes.
At boot, tools.workspace_root is the authoritative default tool jail. Every session records its own resolved workspace binding; repo maps, project memory, profile/instruction snapshots, and git run branches use that binding and skip unbound sessions. [project] never supplies a workspace root.

WebSocket protocol (`/ws`)

ServerMessage (server → client): sealed hierarchy — SessionMessage (event-derived, carries sequence + sessionSequence) and NonEventMessage (control/infra). Variants include session lifecycle, approval requests, clarification requests, narration, proposed workflows, health/metrics pushes.
ClientMessage (client → server): StartSession, ApproveToolCall, RejectToolCall, GrantApproval, AnswerClarification, SetChatMode, and others.
All protocol types are in protocol/ (Dtos.kt, ServerMessage.kt, ClientMessage.kt, ProtocolSerializer.kt).

Health monitoring

HealthMonitor runs probes on a schedule; results folded via HealthProjection into HealthState.
Adding a probe: implement HealthProbe, register in ServerModule.

Work Guidance

Follow Kotlin rules in root CLAUDE.md.
Route handlers must not contain domain logic — delegate to core services injected via ServerModule.
New WS message variants require updating both ServerMessage/ClientMessage sealed classes and ProtocolSerializer.

Verification

./gradlew :apps:server:test --rerun-tasks

Child DOX Index

No child AGENTS.md (leaf module).

3.3 KiB Raw Blame History