Po core

Reusable runtime logic for Po packages. Main and child systems own session lifecycles; the kernel owns contribution selection. extensions defines native server and web plugins, pi retains harness integration, server hosts APIs and transports, and web contains browser capabilities. Shared test hosts and scenarios live under testing.

The po package composes these capabilities into the CLI and distribution. Feature packages own their policies and depend on core.

Workspace registry

Hosts bind the read-only po/workspace-registry Cordis service before serving plugins. Its public contract and helpers are exported from @agimon-ai/po-core/workspaceRegistry:

import { PO_WORKSPACE_REGISTRY_SERVICE, readPoWorkspaceRegistry } from '@agimon-ai/po-core/workspaceRegistry';

context.inject([PO_WORKSPACE_REGISTRY_SERVICE], async (context) => {
  const registry = readPoWorkspaceRegistry(context)!;
  const result = await registry.resolve({ id: host.context.workspaceId });
  if (result.status === 'found') {
    const metadata = result.workspace.metadata;
    // Validate the plugin's own metadata and choose its defaults or scope policy here.
  }
});

list() returns detached workspace records. resolve() requires exactly one non-empty selector: { id }, { name }, { path } (the canonical root), or { alias }. Results are found (with workspace), missing, or ambiguous (with candidates). Duplicate names, paths or aliases never silently select the first match. Ids are local to this host; UI routes retain their existing host-qualified ids. Returned metadata cannot mutate the inventory.

Node composition loads repository .po/workspaces.yaml and associates entries by the saved declaration name. Aliases and metadata are not persisted in the server's workspace membership file. They refresh when the host composes a workspace or session, not on every registry call. Workspaces without a matching declaration have empty metadata. Invalid policy is reported and that root is omitted from the lookup inventory until a successful composition refresh; a broken remembered root never blocks unrelated startup. Host-side sandbox records expose identity only, without reading their folders. Renaming a declaration unlinks its metadata from an existing workspace. The edge implementation exposes only its current tenant id/root with empty metadata until admission carries a declaration association.

Plugins validate their own free-form metadata and decide whether it supplies defaults or enforced scope. Core never interprets product schemas, picks credentials, or exposes sibling Cordis services. A host that does not bind the service returns undefined from readPoWorkspaceRegistry; consumers still need a core version that exports this entry point. See Po Config for declaration syntax.

Federation destination boundary

The portable packageApi entry exports verified caller stamp types, SQLite replay/feed stores, home-host workspace sharing and provider-consent records, and the calling-host grant store. SQLite is supplied through po/sqlite. Replay admission never evicts live nonces. Grant refresh refusal durably pauses that work's token admission and emits FederationWorkPaused; new consent is required to resume it.

The Node remoteRuntime entry composes the CLI's existing QR-pinned publication signer, hub trust store and injected HTTP/SQLite capabilities. Signed-in proofs ride inside the existing sealed HTTP channel. Only a claimed hub with a pinned issuer is enabled; other signed-in proof requests return 401. Trusted plugin dispatch preserves principal, org, account device and calling-host/grant stamps, while legacy callers stay unchanged.

A sealed, fresh QR pairing can submit an account-key-signed enrollment at /api/remote/federation/enroll before reconnect-key registration. The host re-attests it and durably pins the account key and current epoch. /api/remote/federation/claim checks the pinned account signature and persists the issuer JWKS and owner network. Account keys and host-scoped reconnect/biometric keys remain separate.

The default CLI accepts the claim's owner personal org only. Multi-network roster host keys and plugin-owned cross-host operation dispatch belong to later phases, so default C4 work is refused until those authorities are composed. Native enrollment transport, real-issuer deployment and production propagation remain separate verification items.

Public src/exports files only forward symbols from their owners. Po-owned Pi authoring and terminal UI exports are retired. The retained agent runtime and services/piExtensionHost preserve third-party @earendil-works/pi-coding-agent settings, package, and provider compatibility.