feat(agent-harness): normalize web sources and preserve citations

[iscekic]

No new behavior — this change adds internal web processing without changing the features people can use.

---

Summary

executeWeb validates a current web reservation before calling an injected provider for web.search or web.retrieve, keeping provider access separate from normalization.
The Reply and Sources schemas validate replies; WebResult returns bounded, untrusted content with source metadata, citations, and actual or unknown costMicrodollars.
The scheduler must supply the committed reservation and retain uncertain consumption; normalization preserves Unicode, empty results, and failure retryability without estimating provider prices.

Files

• services/agent-harness/src/tools/web.ts — added (+159/−0 lines). Rejects invalid requests, inadmissible or expired reservations, and oversized arguments before dispatch. Passes the response byte limit and abort signal to the provider. Caps search results by the requested and runtime limits, snippets by Unicode characters, and one retrieved page by encoded bytes. Normalizes web addresses, trims titles with an address fallback, converts publication dates, and marks content untrusted: true. Validates shared output schemas and rejects malformed data, non-web or credential-bearing addresses, and invalid dates. Empty searches return no results; empty retrievals return a blank page with the requested address. Only nonblank normalized text produces citation parts. Counts the full result envelope, including citations and cost, and provider failures against the output byte limit; overflow returns limit_exceeded. Preserves provider error details and retryability; missing status, 408, 429, and server errors permit retry, while other retrieval failures do not. Retains zero, actual, or unknown costs even when normalization fails. Lost responses permit retry with unknown cost; cancellation does not permit retry.

Tests: 1 test file added: services/agent-harness/src/tools/web.test.ts (+236/−0 lines). Tests cover normalization, empty results, byte bounds, provider failures, reservation validation, and costs using injected providers and reloaded serialized reservations. They also check five-request exhaustion after an uncertain response, with Exa costs outside the model ceiling.
Generated: 0 files changed.

---

Verification

Manual verification: not run. This level adds isolated normalization without activating a host. A32 and bot-e2e own live-provider, cross-client, and visual evidence.

Visual Changes

Visual Changes: N/A

Reviewer Notes

Human steps

No human steps are required before merge or after merge.

Recorded checks

• The implementer reports 39 focused tests passed, including all ten preserved cases, with scoped oxlint and oxfmt checks passing.
• The reviewer inspected these records; neither the reviewer nor this description round independently reran the tests.
• Auxiliary Git no-index comparisons returned difference status, not product failures. The committed scoped whitespace check passed afterward.

The tests inject the provider and reload serialized reservations; they do not prove authenticated dispatch or durable scheduler wiring.
A21/A22 own authenticated composition and durable reservation wiring; A28–A31 own presentation.
Repository-wide type and build validation remain with continuous integration (CI).

Runtime verification remains pending at the stack tip. This level adds bounded web normalization and citations without activating a new host.

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

WARNING: publishedDate schema rejects Exa's null dates

title already uses .nullish(), but publishedDate is only .optional(). A typical Exa result with "publishedDate": null fails Sources.parse and the whole search/retrieve becomes invalid_output. .nullish() matches title, and the existing falsy check still omits publishedAt.

Suggested change

	publishedDate: z.string().optional(),
	publishedDate: z.string().nullish(),

---

Reply with @kilocode-bot fix it to have Kilo Code address this issue.

[kilo-code-bot]

Code Review Summary

Status: 1 Issue Found | Recommendation: Address before merge

Executive Summary

Sources rejects Exa's common publishedDate: null, failing the entire web search/retrieve as invalid_output.

Overview

Severity	Count
CRITICAL	0
WARNING	1
SUGGESTION	0

Issue Details (click to expand)

WARNING

File	Line	Issue
services/agent-harness/src/tools/web.ts	28	publishedDate uses .optional() so Exa null dates fail the whole result

Files Reviewed (2 files)

• services/agent-harness/src/tools/web.ts - 1 issue
• services/agent-harness/src/tools/web.test.ts - 0 issues

Fix these issues in Kilo Cloud

---

_{Reviewed by grok-4.6 · Input: 279.4K · Output: 26.3K · Cached: 816.6K}

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

[iscekic]

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