@agimon-ai/po-session
Shared session coordination services for Po.
Package details
Install @agimon-ai/po-session from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:@agimon-ai/po-session- Package
@agimon-ai/po-session- Version
0.0.0-alpha.183- Published
- Nov 22, 2026
- Downloads
- 37.8K/mo · 6,357/wk
- Author
- agiflow-ai
- License
- BUSL-1.1
- Types
- extension
- Size
- 1.2 MB
- Dependencies
- 7 dependencies · 1 peer
Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
@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. An admission that a restart or a busy session interrupted is replayed under the same request ID. One that keeps failing for two minutes, or fails for any other reason, is marked for recovery, and the sender gets a notice that names the message.
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 directsend,messages, and correlatedreportoperations. 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.
Lanes
Messages between sessions travel in three lanes, so a busy session is not interrupted for news that can wait.
- Queued (
network.send, and Teamintercomto a session): stored, then folded with other queued messages into one digest when the recipient's run ends. A digest is written once and replayed as written after a restart. - Urgent (
network.sendwithurgent: true,network.ask, replies): joins the recipient's running turn.urgentis offered only where the host has lanes. - Logbook (
network.log, stop reports): stored without a turn. Ablockedentry wakes the coordinator. A stop report wakes it only for a session it started or messaged in the last 24 hours that is still stopped. Wakes gather for 30 seconds.
A sender may start six messages or questions to one recipient in ten minutes, two of them interrupting. Replies and notices are not counted. An unanswered question brings one reminder after three minutes, also after a restart. A session files a stop report once it has stayed stopped for 90 seconds.
sessions.start sends the brief as /goal -- <brief>, so a session with Goal keeps the brief as its goal and the result says goal: true. A brief over 4,000 characters is refused before the session is created.
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.
Computers of the same owner on a fresh account roster link themselves. Each one offers an invitation to the others every minute through po/host-requests, as a link-auto message on /control carrying a host proof instead of a step-up. The computer with the smaller host identity invites; the other accepts unless it is already linked or holds a tombstone for that host, so an unlink is never undone automatically. Both computers need a public HTTPS origin. Messages stay gated on shared session groups. Removing a computer from the account does not remove a link made this way: unlink it.
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.