james.maesandClaude Opus 4.7
508cf924d0
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>
43 lines
2.5 KiB
Markdown
43 lines
2.5 KiB
Markdown
# 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
|