feat(agent-harness): define closed internal operation contracts

[iscekic]

No new behavior — This level defines internal operations but does not enable them for product users.

---

Summary

HarnessOperationSchema and HarnessOperation restrict input to six named operations; Id, Time, and WebReservation constrain identifiers, times, generations, and optional reservations.
harnessOperationScope binds canonical wire input to capability scope and preserves omitted legacy dispatchStartedAt values rather than inventing timestamps.
bounded, safeError, messages, harnessOperationFailure, and invalid enforce the default 65,536-byte output limit and sanitized recovery states without activating an endpoint.

Files

• apps/web/src/lib/agent-harness/operation-contract.ts — Added server-only source (+149/−0 lines). Accepts only execute, reconcile, read, history, projection, and retirement, using named ToolRequestSchema requests and rejecting extra fields. Validates universally unique identifiers (UUIDs), normalizes them to lowercase, and requires nonnegative integer times and generations. Restricts read purposes to read, import, project, and drain; history accepts 1–50 entries and defaults to 50. Projections require an identifier, nonempty key, user/assistant role, content, and an ISO 8601 timestamp; clientId defaults to null. Optional reservations carry reservation/run/tool identifiers, start/deadline times, and fixed tool, reserved, and webRequest: true markers. Validates before JavaScript Object Notation (JSON) normalization, retaining defaults and omitting absent optional fields. Binds the complete input digest to the agent-harness:operations audience, conversation, operation, definition version 1, dispatch identity, and backend target. Measures serialized output, including JSON overhead, in 8-bit Unicode Transformation Format (UTF-8) bytes against a configurable limit; valid empty values pass unchanged. Treats failed or undefined serialization and schema failures as invalid output; oversized output produces a limit failure unless uncertainty takes precedence. Uses fixed messages for every ErrorSchema code, removes extra error fields, and preserves codes and retry flags. Keeps explicit rejections and reauthorization distinct from non-retryable outcome_unknown failures when the outcome is uncertain. Failure mapping permits retries only for storage failures and SERVICE_UNAVAILABLE tool failures; invalid raises BAD_REQUEST.
• apps/web/src/lib/agent-harness/operation-contract.test.ts — Added test (+148/−0 lines). Covers operation types, strict fields, defaults, optionals, key ordering, signed-input changes, redaction, recovery states, byte limits, empty values, and invalid output.

capability and authorizedInput provide reusable signed-authority tests without live service or database access.
Real authorization and scope parsing run against mocked grants, registry records, users, membership checks, and thread lookup.
The fixture resets access and expiry before each test and restores spies afterward, so operation suites share isolated state.

Files

• apps/web/src/lib/agent-harness/operation-test-fixture.ts — Added test helper (+116/−0 lines). Supplies fixed identities, a controlled clock, operation builders, signed capabilities, and JSON transport simulation. Mocks existing secrets and database/runtime dependencies without adding deployment configuration; exposes access, role, and expiry controls for operation suites.

Tests: 2 files added — operation-contract.test.ts and operation-test-fixture.ts (+264/−0 lines total).
Generated: 0 files changed.

---

Verification

Manual verification: not run. No endpoint activates at this level.
The isolated checks do not establish live endpoint or database behavior.

Visual Changes

Visual Changes: N/A

Reviewer Notes

Human steps

None. This level requires no new environment value, secret, migration, flag, or deployment order.

Recorded checks

• The handoff reports 59 passing isolated tests and passing changed-file lint, format, and whitespace checks.
• This description round did not rerun the tests.
• Repository-wide type and build validation remain with continuous integration (CI).

Scope

• Repository: Kilo-Org/cloud; worktree: /Users/igor/Projects/.worktrees/shared-agent-harness-3bb0.
• Review range: shared-agent-harness-3bb0-s29...shared-agent-harness-3bb0-s30.
• This level does not wire maintenance authorization, named dispatch, provider reservations, or endpoint composition.

Runtime verification remains pending at the stack tip. This level adds closed internal operation contracts without activating an endpoint.

Stacked PRs — merge bottom to top. Each level shows only its own diff.

Runtime verification (E2E, user advocacy, simplify) runs on the tip PR over every level.
Every level keeps its own checks, its own bot review, and its own threads; each one is answered on its own PR.
Each level is its own deliverable: it builds and passes its own checks alone.
A finding on a level is repaired on that level, then carried upward with stack.sh forward.

1. shared-agent-harness-3bb0 — chore(agent-harness): register workspaces and enforce CI boundaries #5632
2. shared-agent-harness-3bb0-s2 — feat(agent-harness): define portable domain and snapshots #5637
3. shared-agent-harness-3bb0-s3 — feat(agent-harness): define commands tools and permission policy #5639
4. shared-agent-harness-3bb0-s4 — feat(agent-harness): share client state and cursor recovery #5643
5. shared-agent-harness-3bb0-s5 — feat(agent-harness): persist command intents and execution receipts #5647
6. shared-agent-harness-3bb0-s6 — feat(db): add harness ingress grants and retirement fences #5655
7. shared-agent-harness-3bb0-s7 — feat(agent-harness): deliver legacy history and project durable text #5659
8. shared-agent-harness-3bb0-s8 — feat(agent-harness): authorize durable grants and registered clients #5662
9. shared-agent-harness-3bb0-s9 — feat(agent-harness): fence retirement and retry payload cleanup #5667
10. shared-agent-harness-3bb0-s10 — feat(agent-harness): persist authoritative state in SQLite #5675
11. shared-agent-harness-3bb0-s11 — feat(agent-harness): admit durable runs and revisioned commands #5678
12. shared-agent-harness-3bb0-s12 — feat(agent-harness): recover queued runs and stream checkpointed steps #5688
13. shared-agent-harness-3bb0-s13 — feat(agent-harness): resolve interactions and dispatch tools sequentially #5693
14. shared-agent-harness-3bb0-s14 — feat(agent-harness): fence designated client tool execution #5697
15. shared-agent-harness-3bb0-s15 — feat(agent-harness): synchronize durable snapshots and legacy history #5701
16. shared-agent-harness-3bb0-s16 — feat(agent-harness): reuse authorized invitations with durable replay #5704
17. shared-agent-harness-3bb0-s17 — feat(integrations): bound repository transport for harness reads #5710
18. shared-agent-harness-3bb0-s18 — feat(integrations): expose bounded authorized repository reads #5714
19. shared-agent-harness-3bb0-s19 — feat(agent-harness): expose named authorized resource reads #5718
20. shared-agent-harness-3bb0-s20 — feat(sessions): bound history transport for harness reads #5724
21. shared-agent-harness-3bb0-s21 — feat(agent-harness): read scoped Cloud Agent context and progress #5726
22. shared-agent-harness-3bb0-s22 — fix(agent-harness): preserve ordered Cloud Agent dispatch identity #5731
23. shared-agent-harness-3bb0-s23 — feat(agent-harness): hand coding work to authorized Cloud Agent sessions #5733
24. shared-agent-harness-3bb0-s24 — feat(agent-harness): authorize scoped MCP gateway connections #5737
25. shared-agent-harness-3bb0-s25 — feat(agent-harness): bound MCP gateway transport in the Worker #5740
26. shared-agent-harness-3bb0-s26 — feat(agent-harness): execute validated remote MCP tools #5743
27. shared-agent-harness-3bb0-s27 — refactor(exa): share provider dispatch and usage recording #5746
28. shared-agent-harness-3bb0-s28 — feat(agent-harness): authorize bounded web provider requests #5747
29. shared-agent-harness-3bb0-s29 — feat(agent-harness): normalize web sources and preserve citations #5749
30. shared-agent-harness-3bb0-s30 — feat(agent-harness): define closed internal operation contracts #5753 ← this PR
31. shared-agent-harness-3bb0-s31 — feat(agent-harness): authorize internal maintenance operations #5754
32. shared-agent-harness-3bb0-s32 — feat(agent-harness): authorize named Kilo operation dispatch #5755
33. shared-agent-harness-3bb0-s33 — feat(agent-harness): authorize internal provider operations #5757
34. shared-agent-harness-3bb0-s34 — feat(agent-harness): secure the internal operations endpoint #5758
35. shared-agent-harness-3bb0-s35 — feat(agent-harness): bound and sanitize model streams #5767
36. shared-agent-harness-3bb0-s36 — feat(agent-harness): secure billed model inference #5776
37. shared-agent-harness-3bb0-s37 — test(agent-harness): cover model gateway security boundaries #5777 (tip)

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Executive Summary

Reviewed the new closed internal operation contracts, tests, and fixture; signed-input digest, failure sanitization, and output bounds are consistent with existing harness authorization.

Files Reviewed (3 files)

• apps/web/src/lib/agent-harness/operation-contract.ts
• apps/web/src/lib/agent-harness/operation-contract.test.ts
• apps/web/src/lib/agent-harness/operation-test-fixture.ts

---

_{Reviewed by grok-4.6 · Input: 125.9K · Output: 21.7K · Cached: 804.6K}

_{Review guidance: REVIEW.md from base branch shared-agent-harness-3bb0-s29}

[iscekic]

Closing: the owner stopped this workflow section. The branch is retained.