feat(agent-harness): secure the internal operations endpoint

[iscekic]

No new behavior — the product's screens and available actions remain unchanged.

---

Summary

POST /api/internal/agent-harness/operations requires x-internal-api-key to match the existing INTERNAL_API_SECRET and a signed Authorization: Bearer capability.
It enforces 65,536-byte requests, 1,048,576-byte complete replies, cache-control: no-store, and a 60-second maxDuration to bound transport without caching authority-sensitive results.
On overflow, web replies retain actual nullable costMicrodollars in a sanitized, non-retryable limit_exceeded result, even during cancellation races.

Files

• apps/web/src/app/api/internal/agent-harness/operations/route.ts — Added source (+76/−0 lines). Compares service secrets in constant time and rejects missing or malformed bearer credentials before reading the body. Requires JavaScript Object Notation (JSON) bodies and rejects malformed 8-bit Unicode Transformation Format (UTF-8) encoding. Counts streamed bytes before parsing, then cancels and releases the body reader. Measures the complete serialized reply, including its envelope, and sends the checked string with application/json and no-store headers. Accepts exactly 1,048,576 bytes; larger web replies retain null, zero, or positive cost in a small status: failed result with status 200. Other reply overflow returns status 400. Service authentication failures and missing bearer credentials return 401. Operation errors use 403 for access_revoked, 503 when retryable, and 400 otherwise; result envelopes return 200. Forwards the request's cancellation signal to execution.
• apps/web/src/lib/agent-harness/internal.test.ts — Added test (+516/−0 lines). Covers service and capability authentication, authority loss, signed request tampering, malformed or oversized bodies, output validation, connection redaction, empty results, and sanitized recovery. Exercises dispatch identity, legacy reconciliation, lost invitation outcomes, reservation binding, cancellation, history, projection, and fenced retirement. Checks exact-limit and one-byte-over web responses with null, zero, and positive costs, including cancellation races and actual response bytes.

The server-only executeHarnessOperation applies HarnessOperationSchema to route execute, reconcile, read, history, projection, and retirement through existing helpers.
This preserves current primary authority, signed input digests, immutable dispatchStartedAt, and matching web reservations without exposing arbitrary procedure names.
Legacy reconciliation keeps an absent dispatchStartedAt explicit, and uncertain mutations retain outcome_unknown instead of claiming cancellation or success.

Files

• apps/web/src/lib/agent-harness/operations.ts — Added source (+36/−0 lines). Validates and bounds input before routing authority reads, history delivery, text projection, and retirement to their existing helpers. Routes Model Context Protocol (MCP) operations mcp.discover and mcp.call, plus web.search and web.retrieve, to provider helpers. Sends other allowed execution and reconciliation requests to the dispatch helper, retaining named preconditions and primary authorization checks. Preserves original dispatch timestamps and digests; new cloud mutations still require a timestamp, while legacy reconciliation keeps its absence. Retains signed reservation checks for the operation, run, call, and original deadline rather than creating a replacement reservation. Keeps retirement tied to the exact signed purge and matching primary generation fence, without requiring a live grant. Passes cancellation through execution and reconciliation, preserves validated outputs, and re-exports harnessOperationFailure for shared sanitized errors and outer failures.

Tests: 1 test file added — internal.test.ts (+516/−0 lines).
Generated: 0 files changed.

---

Verification

Manual verification: not run because the endpoint does not yet connect to a complete product journey.
Worker composition, billed model inference, live providers, presentation, and cross-client verification remain later planned work.

Visual Changes

Visual Changes: N/A

Reviewer Notes

Human steps

This level requires no human setup before or after merge.
Product pull request merges remain human-owned.

Recorded checks

• The supplied repair report records 83 passing endpoint cases, including 24 exact-size and cancellation cases, plus clean scoped lint, formatting, and whitespace checks.
• The isolated suite replaces database access and external adapters; it does not verify live providers or committed reservation origin.
• This description round did not rerun product checks. Repository-wide lint, tests, type checks, builds, and actual PostgreSQL execution remain unverified.

Notes

• Runtime verification remains pending until the complete backend, browser, iOS, and Android integration reaches the stack tip.
• Font-scaling variants, including large text and dynamic type: owner-descoped.
• Light, dark, and other theme variants, including variant-only geometry: owner-descoped.
• Visual contrast, scaled-text layout, and screen-reader presentation checks: owner-descoped.

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

• apps/web/src/app/api/internal/agent-harness/operations/route.ts
• apps/web/src/lib/agent-harness/operations.ts
• apps/web/src/lib/agent-harness/internal.test.ts

---

_{Reviewed by grok-4.6 · Input: 139.5K · Output: 26.3K · Cached: 456.8K}

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

[iscekic]

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