Skip to content

feat(federation): add dogfoodable instance federation MVP#735

Open
huntharo wants to merge 13 commits into
mainfrom
feat/pwragent-instance-federation
Open

feat(federation): add dogfoodable instance federation MVP#735
huntharo wants to merge 13 commits into
mainfrom
feat/pwragent-instance-federation

Conversation

@huntharo

@huntharo huntharo commented Jun 10, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Summary

This makes instance federation dogfoodable: a gateway PwrAgent profile can run a local federation gateway, a client profile can enroll/connect over the authenticated WebSocket transport, and any connected instance can open a remote window for the gateway or another connected client through the federation relay.

What changed

  • Adds the shared federation contracts plus desktop federation identity, enrollment, policy, store, authenticated transport, router, RPC backend bridge, health, and runtime lifecycle.
  • Adds Settings -> Federation controls for gateway/client mode, endpoint configuration, invite generation/import, live health, federation instance listing, and opening remote instance windows.
  • Advertises the federation peer directory from the gateway so clients can see/open the gateway and sibling clients.
  • Threads remote targets through the renderer, app-server IPC, composer, and agent IPC so remote windows can use remote navigation, thread reads, skill listing, startTurn, and live transcript events.
  • Relays client-to-client RPC and live backend events through the gateway.
  • Carries federated thread bindings through messaging storage/routing so external messaging can route to local or client-instance threads.
  • Documents the MVP dogfood flow, including the two-profile preview setup and current Cloudflare/app-auth boundary.

MVP test notes

This is intended to be testable with two local profiles after building the desktop app:

pnpm --filter @pwragent/desktop build
PWRAGENT_PROFILE=gateway pnpm --filter @pwragent/desktop preview
PWRAGENT_PROFILE=client pnpm --filter @pwragent/desktop preview

Known MVP limits:

  • Remote new-thread creation is not wired yet; test against an existing remote thread.
  • I did not manually run two GUI instances end-to-end before opening this PR.

Tests

pnpm test packages/shared/src/contracts/__tests__/federation.test.ts packages/shared/src/contracts/__tests__/settings.test.ts apps/desktop/src/main/__tests__/desktop-config-federation.test.ts apps/desktop/src/main/__tests__/desktop-settings-service.test.ts apps/desktop/src/main/__tests__/federation-store.test.ts apps/desktop/src/main/__tests__/federation-identity.test.ts apps/desktop/src/main/__tests__/federation-enrollment.test.ts apps/desktop/src/main/__tests__/federation-policy.test.ts apps/desktop/src/main/__tests__/federation-transport.test.ts apps/desktop/src/main/__tests__/federation-router.test.ts apps/desktop/src/main/__tests__/federation-backend-bridge.test.ts apps/desktop/src/main/__tests__/federation-window-bootstrap.test.ts apps/desktop/src/main/__tests__/federated-search-service.test.ts apps/desktop/src/main/__tests__/federation-health.test.ts apps/desktop/src/main/__tests__/federation-runtime.test.ts apps/desktop/src/renderer/src/features/settings/__tests__/FederationSettings.test.tsx
pnpm --filter @pwragent/desktop typecheck
pnpm --filter @pwragent/shared typecheck
pnpm lint:boundaries
pnpm lint:sql

Compound Engineering
GPT-5

@huntharo
huntharo force-pushed the feat/pwragent-instance-federation branch 12 times, most recently from 5f8f84d to 9e35163 Compare June 18, 2026 17:47
@huntharo huntharo mentioned this pull request Jun 21, 2026
Merged
huntharo added a commit that referenced this pull request Jun 22, 2026
@huntharo @claude
feat(federation): guard remote-window thread creation and badge remot…
0890047 
…e windows

Three dogfood UX fixes for the instance-federation MVP (#735):

- Block new-thread creation in a remote window instead of silently
  creating a LOCAL thread on the client instance. createThread and
  materializeDirectoryLaunchpad now bail with a clear message when a
  renderer federation target is active; the launchpad path throws so the
  composer preserves the typed prompt.
- Add RemoteWindowBadge in the sidebar masthead so remote windows are
  visually distinct from local ones.
- Surface peer reachability via a connection-status dot on the badge
  (connected / pending / offline), polling federation health.

Reuses existing theme tokens; the brand-token contract test still passes.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
huntharo added a commit that referenced this pull request Jun 22, 2026
@huntharo @claude
docs(federation): plan encrypted LAN transport and messaging routing
48ce220 
Two follow-up plans for the instance-federation MVP (#735):

- Encrypted, identity-bound direct/LAN transport: a Noise_IK channel over
  the existing WebSocket reusing the pinned instance identity, closing the
  post-auth cleartext read/inject exposure when not behind Cloudflare.
- Messaging -> remote-thread routing: wires the currently-dead federated
  messaging helpers into a reachable end-to-end path (browse surfacing,
  bind stamping, bridge routing, remote event delivery) behind a
  default-off messaging_route capability.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
huntharo added a commit that referenced this pull request Jul 2, 2026
@huntharo @claude
feat(federation): instance federation with encrypted transport
6bd0241 
Federation feature collapsed onto current main as a single linear commit
(developed across #735/#872/#892 with interim merge commits). Rebuilt via one
3-way squash of the tested branch tip onto main; the only conflict was an
additive preload import list, resolved by keeping both.

Includes:
- Instance federation MVP: authenticated WebSocket control plane; peer
  enrollment / identity / policy / store; router + RPC backend bridge; remote
  window targets; federated search; Settings -> Federation; messaging
  federated-thread bindings.
- Remote-window UX guardrails: block remote-window thread creation (no silent
  local thread), RemoteWindowBadge with live peer connection status.
- Encrypted, mutually-authenticated transport: hand-written Noise_IK on Node's
  built-in crypto (locked to the official Noise test vectors), per-frame AEAD,
  gateway static key pinned via the invite, Ed25519 identity proof channel-bound
  to the handshake hash. Encrypted by construction (no plaintext LAN path).
- Plans: encrypted-LAN-transport and messaging-routing follow-ups.

Federation ships disabled by default; encrypted when enabled.

Verified: shared+desktop typecheck, lint:boundaries, lint:sql, and the federation
+ merge-sensitive suites (196 tests) green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@huntharo
huntharo force-pushed the feat/pwragent-instance-federation branch from 0b83e3a to 6bd0241 Compare July 2, 2026 19:21
@huntharo huntharo closed this Jul 2, 2026
@huntharo huntharo reopened this Jul 2, 2026
huntharo added a commit that referenced this pull request Jul 2, 2026
@huntharo @claude
feat(federation): instance federation with encrypted transport
5ebe184 
Federation feature collapsed onto current main as a single linear commit
(developed across #735/#872/#892 with interim merge commits). Rebuilt via one
3-way squash of the tested branch tip onto main; the only conflict was an
additive preload import list, resolved by keeping both.

Includes:
- Instance federation MVP: authenticated WebSocket control plane; peer
  enrollment / identity / policy / store; router + RPC backend bridge; remote
  window targets; federated search; Settings -> Federation; messaging
  federated-thread bindings.
- Remote-window UX guardrails: block remote-window thread creation (no silent
  local thread), RemoteWindowBadge with live peer connection status.
- Encrypted, mutually-authenticated transport: hand-written Noise_IK on Node's
  built-in crypto (locked to the official Noise test vectors), per-frame AEAD,
  gateway static key pinned via the invite, Ed25519 identity proof channel-bound
  to the handshake hash. Encrypted by construction (no plaintext LAN path).
- Plans: encrypted-LAN-transport and messaging-routing follow-ups.

Federation ships disabled by default; encrypted when enabled.

Verified: shared+desktop typecheck, lint:boundaries, lint:sql, and the federation
+ merge-sensitive suites (196 tests) green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@huntharo huntharo closed this Jul 2, 2026
@huntharo huntharo reopened this Jul 2, 2026
@huntharo
huntharo force-pushed the feat/pwragent-instance-federation branch from 6bd0241 to 5ebe184 Compare July 2, 2026 21:59
huntharo added a commit that referenced this pull request Jul 5, 2026
@huntharo @claude
feat(federation): instance federation with encrypted transport
5250772 
Federation feature collapsed onto current main as a single linear commit
(developed across #735/#872/#892 with interim merge commits). Rebuilt via one
3-way squash of the tested branch tip onto main; the only conflict was an
additive preload import list, resolved by keeping both.

Includes:
- Instance federation MVP: authenticated WebSocket control plane; peer
  enrollment / identity / policy / store; router + RPC backend bridge; remote
  window targets; federated search; Settings -> Federation; messaging
  federated-thread bindings.
- Remote-window UX guardrails: block remote-window thread creation (no silent
  local thread), RemoteWindowBadge with live peer connection status.
- Encrypted, mutually-authenticated transport: hand-written Noise_IK on Node's
  built-in crypto (locked to the official Noise test vectors), per-frame AEAD,
  gateway static key pinned via the invite, Ed25519 identity proof channel-bound
  to the handshake hash. Encrypted by construction (no plaintext LAN path).
- Plans: encrypted-LAN-transport and messaging-routing follow-ups.

Federation ships disabled by default; encrypted when enabled.

Verified: shared+desktop typecheck, lint:boundaries, lint:sql, and the federation
+ merge-sensitive suites (196 tests) green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@huntharo
huntharo force-pushed the feat/pwragent-instance-federation branch 3 times, most recently from 5ba7298 to 5c935a0 Compare July 7, 2026 02:55
@huntharo
huntharo force-pushed the feat/pwragent-instance-federation branch 2 times, most recently from 38027f3 to ddef291 Compare July 15, 2026 03:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@huntharo