@agimon-ai/po-session

Shared session coordination services for Po.

The foundation owns the session-scoped background-work coordinator used by optional execution packages. It also provides SQLite-backed delivery with host-bound sender identities, durable inbox and outbox state, acknowledgements, keyed duplicate suppression, and prompt admission that wakes idle recipients. Interrupted admission is marked for recovery and is never replayed automatically.

Its public services also include:

• An in-memory, permission-filtered presence directory with qualified references, separate reachability, runtime, activity, and Voice facts, incarnation and sequence tracking, expiry, and snapshot recovery after sequence gaps.
• A SQLite communication-group registry with one owner authority, explicit qualified members, enrollment policy, revision conflicts, and current-membership authorization.
• An agent-facing intercom service for discover, attributed direct send, messages, and correlated report operations. Compositions acquire this service explicitly. Group membership grants only discovery and messaging, never session controls or Voice ownership.

Session delivery rechecks current authority before each initial send and queued retry. Removing a member therefore blocks later publication while preserving already accepted delivery evidence.

Paired hosts

A paired host is configured privately in ~/.po/session/peers.json. The file must be owner-only (0600). Each peer needs an HTTPS tunnel URL, a shared secret of at least 32 characters, and explicit operation-specific session allowlists. Pairing alone grants no Session or Voice access.

{
  "version": 1,
  "hostId": "home-host",
  "peers": [
    {
      "hostId": "work-host",
      "url": "https://work.example.net/",
      "secret": "replace-with-a-private-32-character-minimum-secret",
      "allowedSessionIds": ["approved-message-session-id"],
      "allowedVoiceSessionIds": ["approved-voice-session-id"]
    }
  ]
}

Use peer/<host-id>/<session-id> as a qualified target. allowedSessionIds grants durable messages and acknowledgements. allowedVoiceSessionIds separately grants bounded Voice client-media relay operations. Neither grant exposes owner, /host/*, or /hub/* routes.

Host links

po/session-peers owns the live peer configuration and atomic private writes. Host identity is stable across tunnel URL changes. The existing version-1 format accepts optional URL generations and revocation tombstones; existing allowlist readers remain compatible.

The sealed API under /api/plugins/session-peer exposes GET /links and POST /link/prepare, /link/accept, /link/unlink, and /link/hint. Prepare, accept, and unlink require a fresh peer.link step-up. Quick-tunnel linking requires a native device-key session; named tunnels also accept passkeys. An invite expires after 60 seconds and is consumed once. The app relays public ECDH material, never the derived link secret.

Links begin with empty messaging and Voice allowlists. They do not chain through a third host. Peer delivery is sealed using an authenticated handshake; a URL hint cannot bypass it. Signed rebinds must name the sender itself and advance its URL generation. Unlinking stores a tombstone. Removing a paired device does not remove a host link.

Development

pnpm build
pnpm typecheck
pnpm test
pnpm lint

Account network peer links

createRosterPeerLink(ports) adds direct host-key-authenticated sealed links using an already verified C6 snapshot. Supply it as createPeerLink({ network, ... }) to expose it alongside the existing invite control as control.network. connect(hostId, token, exchange) and accept(proof, token) sign fresh ephemeral handshake keys with signEnvelope using the roster host key. The receiving host's authorize port must validate the identity token's issuer, audience, current membership, and proof-bound caller host. The verifyRequest port must perform normal destination C3/C4 verification, including durable replay admission. Neither a roster entry, an identity token alone, nor a channel grants application permissions. Roster keys use base64url DER P-256 SPKI encoding.

Channels recheck roster epoch, membership and keys on each use. Publish C6 changes before admitting new traffic; removal or key rotation refuses existing channels. Fresh handshakes are required after restart. The account path does not write legacy peer secrets or session permission lists. Existing 60-second invites and pre-account session links retain their behavior and confer no network capability. Direct links do not require an elected coordinator: in a two-voter network with one down, existing direct authorized traffic can continue even though neither roster writes nor coordinated relay service can progress. Election is CFT, not Byzantine-safe. Actual host roster-sync and network activation are composition responsibilities, not implicit consequences of enabling session peers.