feat(agent-harness): define portable domain and snapshots

[iscekic]

No new behavior — this change adds data definitions without changing the running product.

---

Summary

ConversationSchema and PermissionModeSchema default missing settings to ask/revision 0; LegacyMessageSchema, MessageSchema, MessagePartSchema, ConversationProducer, and MessageProducer normalize legacy text without authority.
ProtocolVersionSchema, ContextSchema, ErrorSchema, WaitingSchema, RunStateSchema, RunSchema, ToolOutcomeSchema, ExecutionTargetSchema, ApprovalRecordSchema, and ToolCallSchema validate portable recovery records and preserve complete tool calls.
InteractionSchema, ClientSchema, ExecutionGrantSchema, PendingClientActionSchema, SnapshotSchema, EventEnvelopeSchema, HistoryCursorSchema, and EventCursorSchema preserve recovery state; callers must authenticate producers that claim harness provenance.

Files

• packages/agent-harness/src/contracts.ts — added (A; source; +271/−0 lines). Reuses gateway context directly to avoid Web globals. Adds protocol, identifier, timestamp, error, and strict variant validation. Keeps owner and legacy message client identifiers as strings. Permissions allow ask or yolo. Runs retain origin, model, and variant metadata; waiting and failed states require their payloads. Freezes validated tool records, contexts, targets, approvals, and nested arguments. Calls retain definitions, effects, approvals, and backend/client/interaction targets; results exist exactly when settled. Outcomes distinguish success, failure, denial, cancellation, and uncertainty, including reasons and optional provider references. Interactions retain approval decisions or question answers and dismissals. Browser/mobile clients retain supported tool versions and revocation times. Grants bind the owner, conversation, client, call, context, definition, input digest, generation, and expiry. Pending actions require client targets and retain their blocking reason and nullable grant. Harness messages require the protocol version and run identity; tool parts retain complete records without extra lookups. Citations allow only http/https URLs. Missing message fields default to text parts, clientId: null, and harness incomplete: false. Legacy parsing discards supplied authority and parts; compatibility defaults remain until old records and callers disappear. Snapshots require recovery fields independently of recent messages, including opaque history cursors, pending actions, and unresolved interactions. Active runs must be running, waiting, or stopping; queued runs must be queued. Events carry conversation, message, run, interaction, or nullable client-action payloads. Event cursors accept zero, while event sequences require positive integers. Exports the normalized Conversation, Message, Run, ToolCall, ToolOutcome, Interaction, Client, ExecutionGrant, Snapshot, and EventEnvelope types separately from producer inputs.

Tests: 1 file added (A; test; +410/−0 lines): packages/agent-harness/src/contracts.test.ts. Covers normalization, serialization, authority retention, immutability, recovery fields, and invalid variants. The handoff reports 114 passing contract tests and passing scoped checks.
Generated: 0 files changed.

---

Verification

No manual tests ran for this description. This level adds inert portable schemas only.

Visual Changes

Visual Changes: N/A

Reviewer Notes

Human steps

No human steps are required before or after merge.

Scope and worktrees

• Repository: Kilo-Org/cloud.
• Worktree: /Users/igor/Projects/.worktrees/shared-agent-harness-3bb0.
• Branch: shared-agent-harness-3bb0-s2; base: origin/shared-agent-harness-3bb0.
• Scope: Level 2 portable schemas only; this change adds no runtime or hosts.

Notes

E2E: This level adds inert portable schemas only. Full runtime verification runs on the completed stack tip.

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 ← this PR
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
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

Files Reviewed (2 files)

• packages/agent-harness/src/contracts.ts
• packages/agent-harness/src/contracts.test.ts

---

_{Reviewed by grok-4.6 · Input: 110.4K · Output: 23.7K · Cached: 553.7K}

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

[iscekic]

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