feat: define agent adapter contract

[devkade]

Summary

• Adds a domain-level AgentAdapterContract for portable worker adapters.
• Defines launch/send/capture/interrupt/health/readiness/report/substrate expectations without binding core runtime to a specific CLI.
• Adds a default Codex / Pi / Claude Code compatibility matrix and fail-closed contract validation.
• Documents the adapter-neutral execution boundary in the README.

Linked issue

Closes #188
Refs #167

Problem

The objective-driven learning runtime needs to run different worker tools through one substrate boundary, but the contract for adapter capabilities, readiness proof, health behavior, and worker reports was not explicit. Without this, future runtime phases could accidentally couple core scheduling to a single CLI or accept workers that cannot produce enough evidence for task completion.

Options considered

1. Keep the adapter boundary as README-only design text.
   • Pros: smallest change.
   • Cons: no executable contract; later worker code could drift from the design.
2. Add a full worker execution implementation now.
   • Pros: moves closer to end-to-end runtime execution.
   • Cons: too broad for Design: define portable agent adapter and execution substrate contracts #188 and would mix adapter contract design with dispatch/heartbeat implementation phases.
3. Add a typed domain contract plus validation and a small compatibility matrix.
   • Pros: executable boundary, reviewable size, no runtime side effects.
   • Cons: later phases still need to wire the contract into live worker dispatch.

Selected approach

• Selected option: typed domain contract plus validation.
• Why this one: it closes Design: define portable agent adapter and execution substrate contracts #188’s contract acceptance criteria while keeping the slice under the kapi-agent review size target and avoiding premature runtime implementation.
• Risks/trade-offs: the matrix is a domain contract, not a live adapter probe; actual adapter wiring remains for worker execution phases.

Implementation by file/surface

• src/domain/agent-adapter.ts
  • Defines adapter capabilities, operation support levels, substrate kinds, worker report formats, and AgentAdapterContract.
  • Validates required capability/substrate presence, launch/send support, health support, nonce-equivalent readiness, positive timeout, structured worker report fields, and Codex/Pi/Claude Code compatibility notes.
  • Adds DEFAULT_AGENT_ADAPTER_MATRIX for Codex, Pi, and Claude Code compatible workers.
• test/agent-adapter.test.ts
  • Covers the default matrix and fail-closed validation for missing readiness/health/report/compatibility guarantees.
• README.md
  • Documents the adapter-neutral worker execution boundary beside the existing graph execution runtime boundary.

Why this fixes it

#188 asks for an AgentAdapter contract, ExecutionSubstrate contract, capability matching/readiness/health expectations, structured worker report contract, and compatibility notes for Codex/Pi/Claude Code. This PR makes those constraints executable in the domain layer and documents the public boundary, while leaving concrete worker dispatch implementation to later runtime phases.

QA / Verification

• npm ci — pass
• npx tsx --test test/agent-adapter.test.ts — pass, 2 tests
• npm run check — pass
• npm run check:unused — pass
• npm run quality:budgets — pass with existing non-failing warnings: code_smells=51 > 20; coverage not configured
• npm run verify — pass, 507 passed / 11 skipped; same existing non-failing quality warning
• git diff --check — pass

Anomalies observed

• Existing quality:budgets warning remains: code_smells=51 > 20; this PR does not change that budget.
• Coverage remains not configured, matching current repo behavior.
• This is a split replacement for the Design: define portable agent adapter and execution substrate contracts #188-sized portion of oversized PR feat: add runtime state event spine #227; feat: add runtime state event spine #227 still remains open for the broader runtime-spine work and should be reconciled separately.

Risks / Follow-up

• This PR does not implement live adapter launch/dispatch/heartbeat behavior.
• Later runtime phases still need to connect this contract to claim/lease and worker execution flows.

kapi-agent review expectations and current-head merge gate

• Expected focus: contract completeness for Design: define portable agent adapter and execution substrate contracts #188, fail-closed validation, generic naming, and no coupling to GitHub/Ragna/kapi-agent semantics.
• Merge gate: require current-head kapi-agent approval and successful kapi-agent/review check before merge.

[devkade]

@kapi-agent review

Revision explanation for current head 588a362373f1d00fe87a3e1d0767faec88438d54:

What changed:

• Added a typed AgentAdapterContract and validation for worker capability/substrate/readiness/report/health guarantees.
• Added a default Codex/Pi/Claude Code compatibility matrix.
• Added focused regression tests and README boundary documentation.

Why this closes the prior feedback:

• This is a split, bounded Design: define portable agent adapter and execution substrate contracts #188 contract slice from the oversized runtime-spine PR surface; it avoids live runtime implementation and keeps the change reviewable.
• The domain contract remains generic and does not introduce GitHub/Ragna/kapi-agent semantics.

Verification:

• npm ci — pass
• npx tsx --test test/agent-adapter.test.ts — pass
• npm run check — pass
• npm run check:unused — pass
• npm run quality:budgets — pass with existing non-failing code_smells warning
• npm run verify — pass, 507 passed / 11 skipped
• git diff --check — pass

[kapi-agent]

kapi-agent review completed

The formal GitHub PR review and required check were submitted separately. This request comment is kept concise to avoid duplicating the full review body.

kapi-agent request lifecycle:

• Status: COMPLETED
• Head: 588a362373f1
• Formal review event: APPROVE
• Review API status: 200
• Required check API status: 201

[kapi-agent]

kapi-agent review

Verdict: APPROVE

Final approval summary

Review journey

This PR defines the agent adapter contract slice for issue #188. The semantic scope is bounded: it adds a typed domain contract, a default Codex/Pi/Claude Code compatibility matrix, validation tests, and a small README note. It does not implement live worker dispatch, heartbeat loops, or CLI-specific runtime behavior. There was no prior kapi-agent blocking review for this head.

What changed

• Added src/domain/agent-adapter.ts with:
  • AgentAdapterContract
  • capability/substrate/report/readiness support types
  • fail-closed validateAgentAdapterContract
  • DEFAULT_AGENT_ADAPTER_MATRIX
• Added test/agent-adapter.test.ts covering valid defaults and missing guarantee failures.
• Updated README.md to document the adapter-neutral worker execution boundary.

Why this is correct

The change makes the adapter boundary executable without coupling the domain layer to a specific CLI. Required readiness, health, report, substrate, and compatibility expectations are now explicit and validated. The implementation stays product-neutral and avoids pulling runtime/process/GitHub-specific behavior into the domain layer.

Evidence

• Verifier gate: PASS — npm ci && npm run verify exited 0.
• Size gate: PASS — 145 changed lines, below the 200-line semantic review threshold.
• Revision-explanation status: not required, but found.
• Ilchul review harness: PASS — STANDARD risk, no blocking findings.
• Inspected files: src/domain/agent-adapter.ts, test/agent-adapter.test.ts, README.md.

Remaining risks and approval rationale

Remaining risk is limited to future integration: this contract is not yet wired into live adapter launch/dispatch/heartbeat flows. That is explicitly documented as follow-up and is appropriate for this bounded contract PR. Approval is justified because the gates pass, the scope is reviewable, tests cover the new fail-closed behavior, and no blocking correctness or safety issue remains.

Blocking issues

None.

Warnings / risks

• src/domain/agent-adapter.ts: compatibility validation is intentionally lightweight text matching. That is acceptable for this contract slice, but future live adapter registration may need stronger capability negotiation than notes-based validation.
• This does not implement live adapter behavior; later runtime phases must ensure concrete adapters actually satisfy this contract.

Suggestions

• Consider adding future tests for duplicate/unknown report field handling if runtime consumers depend on exact report schemas.
• Consider formatting the long compatibilityNotes arrays across multiple lines in a follow-up cleanup for readability.

Looks good

• The domain layer remains free of GitHub/Ragna/kapi-agent coupling.
• Validation fails closed for missing readiness nonce, health behavior, report fields, substrates, and compatibility notes.
• Tests are focused and map directly to the new contract behavior.
• README is updated alongside the behavior/documented boundary change.

Verification notes

• Verifier gate status: PASS — npm ci && npm run verify exited 0.
• Size gate status: PASS — 145 changed lines.
• Revision-explanation status: not required; explanation found.
• Ilchul harness gate: PASS — STANDARD risk, no blocking findings.
• PR evidence also reports targeted test, typecheck, unused check, quality budgets, verify, and git diff --check passing.

---

Engine: pi

[devkade]

@kapi-agent review --force

Revision explanation for current head e074d695a86958e5b9c398de0d16916e675122d4:

What changed

• Rebased PR feat: define agent adapter contract #229 onto current dev after PR feat: define policy reward calibration #228 was merged.
• No intentional source changes beyond replaying the existing agent adapter contract slice on the updated base.

Why this closes the prior feedback

• Preserves the previously approved implementation while satisfying the branch-up-to-date merge gate.

Verification

• npm run check — pass
• npm run verify — pass
• git diff --check — pass

[kapi-agent]

kapi-agent review completed

The formal GitHub PR review and required check were submitted separately. This request comment is kept concise to avoid duplicating the full review body.

kapi-agent request lifecycle:

• Status: COMPLETED
• Head: e074d695a869
• Formal review event: APPROVE
• Review API status: 200
• Required check API status: 201

[kapi-agent]

kapi-agent review

Verdict: APPROVE

Final approval summary

Review journey

This PR defines the agent adapter contract slice for issue #188. The semantic scope remains bounded: it adds a typed domain contract, a default Codex/Pi/Claude Code compatibility matrix, validation tests, and a small README note. It does not implement live dispatch, heartbeat loops, or CLI-specific adapter runtime behavior. kapi-agent previously approved this change; the current revision rebases the same approved slice onto the updated dev base.

What changed

• Added src/domain/agent-adapter.ts with AgentAdapterContract, substrate/capability/report/readiness types, fail-closed validation, and the default adapter matrix.
• Added test/agent-adapter.test.ts for valid default contracts and missing guarantee failures.
• Updated README.md to document the adapter-neutral worker execution boundary.
• Current revision explanation states the head was rebased after PR #228 with no intentional source changes beyond replaying this slice.

Why this is correct

The contract makes readiness, health, report, substrate, and compatibility expectations explicit without coupling the domain layer to a specific CLI. The validation fails closed for missing core guarantees, including nonce-equivalent readiness, health behavior, report fields, and compatibility notes. The implementation stays domain-level and product-neutral, matching the stated bounded goal.

Evidence

• Verifier gate: PASS — npm ci && npm run verify exited 0.
• Size gate: PASS — 145 changed lines, below the 200-line semantic review threshold.
• Ilchul review harness: PASS — STANDARD risk, neutral conclusion, no blocking findings.
• Revision explanation status: not required now, and found.
• Inspected files: src/domain/agent-adapter.ts, test/agent-adapter.test.ts, and README diff/context.

Remaining risks and approval rationale

Remaining risks are limited and non-blocking: this is a contract/matrix slice, not live adapter probing or runtime dispatch. Later phases still need to wire this contract into worker execution and validate concrete adapter behavior. Approval is justified because the change is bounded, tested, documented, passes all gates, and no blocking correctness or safety issue remains.

Blocking issues

• None.

Warnings / risks

• src/domain/agent-adapter.ts: compatibility validation is intentionally lightweight text matching. That is acceptable for this contract slice, but future live adapter registration should prefer structured compatibility declarations over regex note checks.
• Runtime integration remains follow-up work; this PR does not prove actual Codex/Pi/Claude Code launch, capture, readiness, or report behavior.

Suggestions

• In a later integration PR, add concrete adapter registration/probing tests that validate real readiness markers and worker report parsing.
• Consider replacing compatibility-note regex checks with structured compatibility fields once the matrix is consumed by runtime code.

Looks good

• The domain contract is explicit and avoids importing runtime/process/GitHub-specific concerns.
• Validation fails closed for the important execution guarantees.
• Tests cover both the default matrix and a deliberately invalid adapter.
• README is aligned with the new boundary and keeps implementation expectations clear.

Verification notes

• Verifier gate status: PASS — npm ci && npm run verify exited 0.
• Size gate status: PASS — 145 changed lines < 200.
• Revision-explanation status: not required now; explanation found.
• Ilchul review harness gate: PASS — STANDARD risk, no blocking findings.
• Author-provided evidence also reports npm run check, npm run verify, and git diff --check passing after rebase.

---

Engine: pi