Merge pull request #424 from AgentWorkforce/feat/additive-broker-sdk

feat: add Rust broker and sdk-ts (additive, no removals)

Author: willwashburn

.beads/issues.jsonl

@@ -221,6 +221,20 @@
 {"id":"agent-relay-546","title":"Storage troubleshooting docs","status":"closed","priority":1,"issue_type":"task","created_at":"2026-01-28T13:07:54.784208+01:00","created_by":"khaliqgant","updated_at":"2026-01-28T13:10:21.19387+01:00","closed_at":"2026-01-28T13:10:21.19387+01:00","close_reason":"Documentation structure complete with placeholders for implementation details"}
 {"id":"agent-relay-547","title":"Add JSONL ledger to relay-pty for durability","description":"## Background\n\nThe relay-pty OutboxMonitor currently uses in-memory HashMap tracking. When relay-pty crashes or restarts, pending/in-flight messages are lost.\n\nPreviously, RelayLedger (TypeScript + SQLite) provided:\n- Crash recovery (reset processing → pending on startup)\n- Retry logic with configurable max retries\n- Audit trail for debugging\n- Content hash deduplication\n\nRelayLedger was removed because relay-pty handles the primary file-based message flow. But we lost durability features.\n\n## Proposal\n\nAdd JSONL-based ledger to relay-pty at `.agent-relay/meta/outbox-ledger.jsonl`:\n\n```json\n{\"file_id\":\"msg-001\",\"path\":\"/...\",\"status\":\"pending\",\"discovered_at\":1706540000000,\"retries\":0}\n{\"file_id\":\"msg-001\",\"status\":\"delivered\",\"processed_at\":1706540001000}\n{\"file_id\":\"msg-002\",\"status\":\"failed\",\"retries\":1,\"error\":\"daemon unreachable\"}\n```\n\n## Features to implement\n\n1. **Crash recovery** - On startup, scan JSONL for pending/processing records, retry them\n2. **Retry logic** - Track retries count, re-attempt failed deliveries up to max (3)\n3. **Audit trail** - Append delivered/failed records for debugging\n4. **Deduplication** - Check if file_id already processed before re-processing\n5. **Compaction** - Periodic compaction to keep file size manageable\n\n## Implementation\n\n1. Add `outbox_ledger.rs` module (~200-300 lines)\n2. Integrate with OutboxMonitor and parser.rs\n3. Add tests for crash recovery scenarios","status":"open","priority":2,"issue_type":"feature","created_at":"2026-01-29T09:54:06.750753+01:00","created_by":"khaliqgant","updated_at":"2026-01-29T09:54:18.992309+01:00"}
 {"id":"agent-relay-548","title":"Add getAllAgentSummaries and getStats to JSONL adapter","description":"The JSONL adapter currently lacks getAllAgentSummaries and getStats methods that exist in the SQLite adapter. These are used by the dashboard for: 1) Agent summaries: 'Recent Work' section in AgentProfilePanel 2) Stats: /api/history/stats endpoint showing message counts. The dashboard currently gracefully hides these sections when data is unavailable, but full parity would provide better UX for local users.","status":"open","priority":2,"issue_type":"task","created_at":"2026-01-29T10:46:10.962538+01:00","created_by":"khaliqgant","updated_at":"2026-01-29T10:46:20.463476+01:00"}
+{"id":"agent-relay-549","title":"Verified PTY delivery in Rust broker","status":"closed","priority":0,"issue_type":"feature","created_at":"2026-02-16T10:16:04.973451+01:00","created_by":"khaliqgant","updated_at":"2026-02-16T13:50:58.692578+01:00","closed_at":"2026-02-16T13:50:58.692578+01:00","close_reason":"Wave 2: Echo verification implemented in commits cf93556f and 845b9ece. PTY delivery now includes echo buffer matching for verified injection.","dependencies":[{"issue_id":"agent-relay-549","depends_on_id":"agent-relay-555","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
+{"id":"agent-relay-550","title":"Enable local send_message with async Relaycast publish","status":"closed","priority":0,"issue_type":"feature","created_at":"2026-02-16T10:16:05.791673+01:00","created_by":"khaliqgant","updated_at":"2026-02-16T13:50:58.742089+01:00","closed_at":"2026-02-16T13:50:58.742089+01:00","close_reason":"Wave 3: send_message handler now forwards to Relaycast REST API when target is not a local worker. RelaycastHttpClient implemented with register, send_dm, send_to_channel. Protocol events RelaycastPublished/RelaycastPublishFailed added. All 98 tests pass.","dependencies":[{"issue_id":"agent-relay-550","depends_on_id":"agent-relay-549","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
+{"id":"agent-relay-551","title":"Broker crash recovery with PID tracking","status":"in_progress","priority":0,"issue_type":"feature","created_at":"2026-02-16T10:16:07.049221+01:00","created_by":"khaliqgant","updated_at":"2026-02-16T14:08:27.900283+01:00"}
+{"id":"agent-relay-552","title":"Activity confirmation after PTY injection","status":"open","priority":1,"issue_type":"feature","created_at":"2026-02-16T10:16:07.824585+01:00","created_by":"khaliqgant","updated_at":"2026-02-16T10:16:07.824585+01:00","dependencies":[{"issue_id":"agent-relay-552","depends_on_id":"agent-relay-549","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
+{"id":"agent-relay-553","title":"Adaptive throttling for PTY injection","status":"open","priority":1,"issue_type":"feature","created_at":"2026-02-16T10:16:09.041173+01:00","created_by":"khaliqgant","updated_at":"2026-02-16T10:16:09.041173+01:00","dependencies":[{"issue_id":"agent-relay-553","depends_on_id":"agent-relay-552","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
+{"id":"agent-relay-554","title":"Delivery receipts from broker to SDK","status":"open","priority":1,"issue_type":"feature","created_at":"2026-02-16T10:16:09.954487+01:00","created_by":"khaliqgant","updated_at":"2026-02-16T10:16:09.954487+01:00","dependencies":[{"issue_id":"agent-relay-554","depends_on_id":"agent-relay-549","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"agent-relay-554","depends_on_id":"agent-relay-550","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
+{"id":"agent-relay-555","title":"TDD integration tests for broker delivery guarantees","status":"open","priority":1,"issue_type":"task","created_at":"2026-02-16T10:16:10.878661+01:00","created_by":"khaliqgant","updated_at":"2026-02-16T10:21:22.32265+01:00"}
+{"id":"agent-relay-556","title":"Benchmark suite: broker vs old stack","status":"open","priority":1,"issue_type":"task","created_at":"2026-02-16T10:24:07.558772+01:00","created_by":"khaliqgant","updated_at":"2026-02-16T10:24:07.558772+01:00","dependencies":[{"issue_id":"agent-relay-556","depends_on_id":"agent-relay-550","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
+{"id":"agent-relay-557","title":"Stdio pipe bottleneck: add concurrency or switch to Unix socket","status":"open","priority":1,"issue_type":"bug","created_at":"2026-02-16T10:25:10.799822+01:00","created_by":"khaliqgant","updated_at":"2026-02-16T10:25:10.799822+01:00"}
+{"id":"agent-relay-558","title":"Move auth token out of WebSocket URL query string","status":"open","priority":2,"issue_type":"bug","created_at":"2026-02-16T10:25:11.656551+01:00","created_by":"khaliqgant","updated_at":"2026-02-16T10:25:11.656551+01:00"}
+{"id":"agent-relay-559","title":"Add flock guard to prevent multi-broker conflicts","status":"open","priority":2,"issue_type":"bug","created_at":"2026-02-16T10:25:12.493286+01:00","created_by":"khaliqgant","updated_at":"2026-02-16T10:25:12.493286+01:00"}
+{"id":"agent-relay-560","title":"Decompose main.rs into modules","status":"open","priority":3,"issue_type":"task","created_at":"2026-02-16T10:25:13.270209+01:00","created_by":"khaliqgant","updated_at":"2026-02-16T10:25:13.270209+01:00"}
+{"id":"agent-relay-561","title":"Make PTY auto-response patterns configurable","status":"open","priority":2,"issue_type":"task","created_at":"2026-02-16T10:25:14.688369+01:00","created_by":"khaliqgant","updated_at":"2026-02-16T10:25:14.688369+01:00"}
+{"id":"agent-relay-562","title":"Atomic state persistence with tmp+rename","status":"open","priority":2,"issue_type":"bug","created_at":"2026-02-16T10:25:15.484908+01:00","created_by":"khaliqgant","updated_at":"2026-02-16T10:25:15.484908+01:00"}
 {"id":"agent-relay-5af","title":"Hook doesn't integrate with daemon-based messaging","description":"hooks/inbox-check/hook.ts reads from file-based inbox but the daemon uses SQLite. When using daemon mode, the hook won't see messages. Need to: (1) Query daemon storage, (2) Or ensure inbox files are written in daemon mode too.","status":"open","priority":2,"issue_type":"bug","created_at":"2025-12-20T00:18:35.503078+01:00","updated_at":"2025-12-20T00:18:35.503078+01:00"}
 {"id":"agent-relay-5fa","title":"Add exponential backoff for daemon reconnection","description":"Implement graceful reconnection with exponential backoff delays [100, 500, 1000, 2000, 5000ms]. After max attempts, operate offline gracefully. See docs/TMUX_IMPROVEMENTS.md for implementation details.","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-12-20T21:28:48.055013+01:00","updated_at":"2025-12-20T21:33:42.229756+01:00","closed_at":"2025-12-20T21:33:42.229756+01:00"}
 {"id":"agent-relay-5g0","title":"Heartbeat timeout could be more configurable","description":"In connection.ts:196, heartbeat timeout is hardcoded as 2x heartbeatMs. This should be independently configurable. Also, heartbeat failures immediately kill the connection - could implement exponential backoff for transient issues.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-20T00:18:03.556614+01:00","updated_at":"2025-12-23T23:03:07.563273+01:00","closed_at":"2025-12-23T23:03:07.563273+01:00"}

.beads/phase6-execution-plan.md

@@ -0,0 +1,55 @@
+# Rust Conventions
+
+This rule applies to all Rust files in `src/` and `tests/`.
+
+## Error Handling
+
+- Use `anyhow::Result` for application-level errors (CLI, main, tests)
+- Use `thiserror` for library-level error types that callers match on
+- Never `unwrap()` in production code — use `?` or handle explicitly
+- Telemetry and logging must be infallible — silently ignore errors
+
+## Logging
+
+- Use `tracing` macros: `tracing::info!`, `tracing::warn!`, `tracing::error!`
+- Use structured fields: `tracing::info!(agent = %name, "spawned")`
+- Set log levels via `RUST_LOG` env var (uses `tracing-subscriber` with `env-filter`)
+
+## Async
+
+- All async code uses `tokio` runtime
+- Prefer `tokio::select!` for concurrent operations
+- Use `tokio::spawn` for background tasks that should not block the main loop
+- Cancel safety: document whether async functions are cancel-safe
+
+## Naming
+
+- Modules: snake_case
+- Types/Structs/Enums: PascalCase
+- Functions/Methods: snake_case
+- Constants: UPPER_SNAKE_CASE
+- Enum variants: PascalCase
+
+## Module Organization
+
+- `lib.rs` re-exports public modules
+- `main.rs` contains CLI entry point and runtime orchestration
+- One concern per module (e.g., `auth.rs`, `dedup.rs`, `scheduler.rs`)
+
+## Dependencies
+
+- Minimize new dependencies — prefer what's already in `Cargo.toml`
+- Use feature flags to keep binary size small
+- Unix-only dependencies go under `[target.'cfg(unix)'.dependencies]`
+
+## Testing
+
+- Unit tests go in `#[cfg(test)] mod tests` within the source file
+- Integration tests go in `tests/` directory
+- Stress tests use `#[ignore]` attribute and run separately
+
+## Serialization
+
+- Use `serde` derive macros for JSON serialization
+- Use `#[serde(rename_all = "snake_case")]` for enum variants
+- Protocol types must match the TypeScript SDK definitions in `packages/sdk-ts/src/protocol.ts`

.claude/rules/rust.md

@@ -0,0 +1,58 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  rust-test:
+    name: Rust Tests (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo test
+
+  rust-clippy:
+    name: Clippy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo clippy -- -D warnings
+
+  rust-fmt:
+    name: Format
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt
+      - run: cargo fmt -- --check
+
+  sdk-check:
+    name: SDK TypeScript Check
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: packages/sdk-ts
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+      - run: npm install
+      - run: npx tsc --noEmit