0 Fork 0

Files

T

james.maesandClaude Opus 4.7 508cf924d0 docs(packages): per-package README files

Adds README.md to each of the 13 SPM packages (AgentCore, Bus, Config,
DevOverlay, Harness, Keychain, Logging, MCP, Memory, Replay, Shell, Vision,
Voice). Each covers purpose, key public types, deps, consumers, invariants
(pulled from CLAUDE.md + grep-gates + audit findings), test stack, and
notable files. Memory README explicitly marks the package functionally OFF
until vec0.dylib + Ollama models land.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-05-04 17:13:33 -05:00

2.5 KiB

Raw Permalink Blame History

Bus

Typed Swift↔JS message protocol over WKScriptMessageHandler. The webview is a pure rendering layer; this package is the only legitimate way Swift talks to the HUD and back.

Key public types

Type	Purpose
`BusOutbound` (enum)	Messages Swift→JS — `hello`, `hudState`, `tokenDelta`, `audioLevel`, `toolCallStart/End`, `turnStarted/Ended`, `sessionHistory`
`BusInbound` (enum)	Messages JS→Swift — `helloAck`, `uiReady`, `frameAttachRequested`, `chatSubmit`, `chatCancelAndSubmit`
`OutboundBatcher` (actor)	Coalesces `tokenDelta` on a 32 ms tick; forwards everything else immediately
`WebviewBridge`	The `WKScriptMessageHandler` boundary (the only place that calls `evaluateJavaScript`)
`Handshake`	Version-negotiation flow on first `uiReady`
`BusReply` / `BusError`	Reply + error types for request/response patterns

Depends on

Logging. External: swift-log.

Used by

App/AppDelegate, every subsystem that emits to the HUD, the webview-side TS package webview/packages/bus.

Key invariants / contracts

Hand-written Codable. Both BusOutbound and BusInbound declare Codable in extensions with explicit init(from:) / encode(to:). Swift's synthesized Codable would produce {"hudState": {"_0": "idle"}} instead of {"type":"hudState","state":"idle"}. Adding a case without updating both methods is a compile error — schema-drift preventer at the language level.
Schema version sync. Protocol.swift carries the version; webview/packages/bus/src/version.ts carries the TS mirror. scripts/check-bus-protocol-version.sh requires both to match.
Harness parity. scripts/check-bus-harness-parity.sh requires the TS bus fixtures to round-trip through the Swift decoder.
No evaluateJavaScript outside WebviewBridge. Grep-gated by scripts/check-no-evaluate-javascript.sh.
Single writer to HudState. scripts/check-single-writer-hudstate.sh enforces.

Tests

58 XCTest. Round-trip encoding tests, version-negotiation tests, batcher coalescing tests, content-world isolation tests (WebviewBridgeOutboundTests asserts WKContentWorld.page).

Notable files

Sources/Bus/BusOutbound.swift — Swift→JS event union + hand-written Codable
Sources/Bus/BusInbound.swift — JS→Swift event union + hand-written Codable
Sources/Bus/OutboundBatcher.swift — token-coalescing actor
Sources/Bus/WebviewBridge.swift — WKScriptMessageHandler boundary
Sources/Bus/Protocol.swift — version constant

2.5 KiB Raw Permalink Blame History

Bus