Skip to content

feat(federation): complete remote instance federation - #735

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

feat(federation): complete remote instance federation#735
huntharo wants to merge 15 commits into
mainfrom
feat/pwragent-instance-federation

Conversation

@huntharo

@huntharo huntharo commented Jun 10, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Summary

Completes the U1-U9 instance-federation workflow: gateway and client instances can enroll over the authenticated WebSocket transport, discover every connected federation member, open branded remote windows, operate remote threads with live events, search across instances, and route messaging bindings to remote threads through the gateway relay.

What changed

  • Completes the federation backend surface for navigation, thread creation/fork/review, turn start/steer/interrupt/compact, pending requests and approvals, model/runtime/execution settings, skills, environment selection/actions with setup progress, and workspace handoff.
  • Relays client-to-client RPC, backend events, and environment progress through the gateway with capability checks, deadlines, loop prevention, reconnect backoff, duplicate-session replacement, and active revocation.
  • Adds federation-aware thread search with source identity, remote-window selection, partial-failure reporting, and no local fallback.
  • Routes messaging browse/resume/bind/status/turn controls/settings/approvals to remote owners while keeping callback payloads provider-neutral and remote thread identities collision-safe.
  • Expands Settings with Cloudflare Access service-token and mTLS credentials, peer health, unavailable reasons, audit diagnostics, revocation, and connected-only remote-window actions.
  • Brands remote windows and thread chrome with the authoritative instance label.
  • Adds docs/federation.md with local dogfood, Cloudflare Tunnel, Access, mTLS, credential, diagnostics, revocation, and threat-model guidance.

Test locally

Build the desktop app, then launch isolated gateway and client profiles:

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

Use Settings -> Federation on the gateway to generate an invite, import it on the client, then use the connected peer list to open either instance. Detailed direct-local and Cloudflare setup is in docs/federation.md.

Cloudflare provisioning remains an operator-managed deployment step; PwrAgent stores and applies the configured Access/mTLS credentials but does not create tunnels or Access policies.

Validation

  • pnpm test (388 files, 4,874 tests)
  • pnpm typecheck
  • pnpm lint:eslint (0 errors; repository warning baseline remains)
  • pnpm lint:boundaries
  • pnpm lint:codex-storage
  • pnpm lint:colors
  • pnpm lint:sql
  • pnpm licenses:check

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
@huntharo
huntharo force-pushed the feat/pwragent-instance-federation branch from ddef291 to bf92519 Compare July 26, 2026 19:30
@huntharo huntharo changed the title feat(federation): add dogfoodable instance federation MVP feat(federation): complete remote instance federation Jul 26, 2026
@huntharo
huntharo force-pushed the feat/pwragent-instance-federation branch from 0f28802 to 911bdec Compare July 27, 2026 03:40
huntharo and others added 15 commits July 27, 2026 01:36
@huntharo
feat(federation): add authenticated instance transport foundation
6a47c7a
@huntharo
feat(federation): map app server operations over rpc
0692e94
@huntharo
feat(federation): bootstrap remote window targets
2144d90
@huntharo
feat(federation): add federated thread search service
a8f108c
@huntharo
feat(messaging): carry federated thread bindings
592d705
@huntharo
feat(federation): surface health diagnostics
9279f8e
@huntharo
feat(federation): add settings health pane
7feaefd
@huntharo
feat(federation): wire dogfoodable MVP runtime
25a6215
@huntharo
feat(federation): stream remote backend events
188545e
@huntharo
feat(federation): advertise and relay peer instances
8eb4d88
@huntharo
refactor(federation): rename child role to client
52e4643
@huntharo
fix(ci): update federation test mocks and licenses
83eeea1
@huntharo
feat(federation): route remote thread controls
5038fd6
@huntharo
feat(federation): complete remote federation workflows
9ca1271
@huntharo
docs(federation): add operator setup guide
9c14cbe
@huntharo
huntharo force-pushed the feat/pwragent-instance-federation branch from 911bdec to 9c14cbe Compare July 27, 2026 05:39
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