feat(agent-harness): resolve interactions and dispatch tools sequentially

[iscekic]

No new behavior — the product does not yet expose the new approval and question handling.

---

Summary

commitDispatch stores DispatchPolicy, its decision, and immutable execution intent in one revision-checked transition before the executor runs.
toolResultMessage pairs settled outcomes with the original software development kit (SDK) call identifier, preserving json success output and error-json outcomes.
The existing scheduler remains the only dispatch authority; missing checkpoint mappings reject results instead of inventing call identifiers.

Files

• services/agent-harness/src/dispatch.ts — Source, added (62 lines). Records the evaluated policy before capturing the dispatch attempt and marking the call executing. Builds schema-validated SDK messages from complete checkpoints and preserves structured denial, cancellation, and failure outcomes.

InteractionCommand uses InteractionAuthorizer and AuthoritySchema to check the current user, live client, owner, and immutable context before returning stored decisions.
The journal commits decisions, events, and replies atomically; authorized retries and competing clients receive the first decision, while changed-input replay returns command_conflict.
Exact-call approvals survive mode changes; YOLO keeps question and client gates, while control closures reference durable policy or Stop commands without inventing approvals.

Files

• services/agent-harness/src/interactions.ts — Source, added (224 lines). Reuses unresolved interaction identities and stores stable question identifiers before waiting. Keeps protocol version 1 and rejects invalid commands or unsupported versions. Authenticates resolution commands before replay, fingerprints their validated inputs, and returns existing decisions without applying another resolution. Rolls back failed validation before journaling permanent rejections; transient storage failures permit retry with the same command. Links control closures to the first accepted policy or Stop command after the interaction, rather than a later settings read. Delegates state changes to the scheduler and never executes tools.

resolveInteraction keeps invalid answers pending; valid decisions resume the same run, while sequential calls recheck access and retry stale_revision through the alarm.
SchedulerStateSchema.resultMessages retains matching SDK results before continuation, merges them across writes, and defaults to an empty map for older checkpoints.
reconcile uses optional SchedulerAdapter.reconciliation for pinned backend lookups; unknown mutations block later runs without replay, and Stop preserves actual mutation outcomes.

Files

• services/agent-harness/src/scheduler.ts — Source, modified (439 changed lines). Adds durable waiting calls and atomic approval, denial, answer, and dismissal transitions, using existing immutable-call and checkpoint checks. Denials produce denied; dismissals produce cancelled; valid answers produce succeeded without calling an executor. Validates question and choice identifiers, selection bounds, free text, and cancellation rules. Rechecks current permission revisions, ignores questionAnswered and clientReady adapter hints, and releases unused request reservations while retaining authorization time. Skips already-dispatched calls; authority loss and unavailable tools settle failed calls, while other invalid decisions return invalid_input. Stores and merges result messages without imposing a smaller combined limit on individually bounded outputs. Closes controls on Stop or terminal approval failures, including when definitions disappear, and keeps terminal outcomes displayable. Reconciliation reuses the original attempt and provider reference under stored limits and epoch fences. Only declared tool names and versions permit lookup; unsupported, failed, invalid, or expired lookups leave mutations unknown. Stop cancels remaining calls and supported reads without overwriting an executing mutation's confirmed or unknown outcome.
• services/agent-harness/src/dispatch.test.ts — Test, added (1,514 lines). Uses real SQLite and injected adapters across all tool definitions and both modes, including untrusted reads, question rules, exact-call approvals, and authorization. Covers cross-client races, canonical replay, mode revisions, changed inputs, sequential outcomes, SDK pairs, history retention, and bounded outputs. Exercises journal rollback, alarm and dispatch crash boundaries, terminal refusals, Stop races, and pinned reconciliation without effect replay.

Tests: 1 test file added — services/agent-harness/src/dispatch.test.ts (1,514 added lines).
Generated: 0 files changed.

---

Visual Changes

Visual Changes: N/A

Verification

Manual verification: not run. This level adds no composed user surface.
End-to-end (E2E) and final runtime verification remain pending at the completed stack tip.

Reviewer Notes

Recorded checks

The implementer and reviewer each reported exit 0 for all four scoped checks:

• Worker Vitest: pnpm --filter @kilocode/agent-harness-worker exec vitest run src/dispatch.test.ts.
• Oxlint on the four changed files.
• Oxfmt on the four changed files.
• git diff --check on the four changed files.

Continuous integration (CI) remains pending for repository-wide tests, the unchanged A12 suite, type checks, and builds.

Scope

• Repository: Kilo-Org/cloud.
• Worktree: /Users/igor/Projects/.worktrees/shared-agent-harness-3bb0.
• Review range: shared-agent-harness-3bb0-s12...shared-agent-harness-3bb0-s13; A13 only.
• This level excludes production client grants, synchronization, adapters, runtime composition, presentation, and live acceptance.

Backend adapters must recheck current account, context, and resource access before effects.
Reconciliation adapters must prove safe outcome lookup for their declared versions; the scoped checks use injected adapters, not deployed operations.

Human steps

A13 requires no human steps before merge or after merge.
Production configuration and full backend, browser, iOS, and Android verification remain later implementation gates.

Notes

E2E: bot-e2e remains pending on the completed stack tip; this level adds no composed user surface.

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 ← this PR
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 (tip)

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Files Reviewed (4 files)

• services/agent-harness/src/dispatch.ts
• services/agent-harness/src/interactions.ts
• services/agent-harness/src/scheduler.ts
• services/agent-harness/src/dispatch.test.ts

---

_{Reviewed by grok-4.6 · Input: 163.9K · Output: 36.5K · Cached: 1.6M}

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