@agimon-ai/po-config
Typed configuration loading, validation, and host services for composing Po sessions.
Package details
Install @agimon-ai/po-config from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:@agimon-ai/po-config- Package
@agimon-ai/po-config- Version
0.0.0-alpha.183- Published
- Nov 22, 2026
- Downloads
- 57.4K/mo · 10.2K/wk
- Author
- agiflow-ai
- License
- BUSL-1.1
- Types
- package
- Size
- 2.3 MB
- Dependencies
- 5 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-config
Typed configuration loading, validation, and session selection state for Po. The distribution loads Config before selectable packages; do not add it to a layer.
Requires Node.js 24 or newer. Pi consumers use the peer version declared in package.json.
Runtime settings
Po reads host settings from ~/.po/config.yaml and repository settings from <repoRoot>/.po/config.yaml. The strict runtime reader also applies the selected person's cached issuer-global settings beneath the host file, for portable keys only. It uses the session starter's identity when supplied, otherwise the host owner's. A missing cache contributes nothing. See Hierarchy.
Merge rules depend on the field: repository trust policy defaults to ask; editor choice and autonomous voice capture are host-only; planning, voice, and default selection merge where supported. Unknown keys and invalid values fail loading. The settings inspection reader readPoConfigLayers currently reports host and repository layers, not the cached global layer.
projectTrust: ask
selection:
preset: copilot
domains: [default]
profile: reviewer
Selection names defaults. Definitions belong in presets.yaml, domains.yaml, and profiles.yaml, whose owning packages provide Help guidance. The configuration contract gives authoring examples; the parser in src/services/configPolicy owns accepted fields and merge behavior.
Workspace declarations
Declare workspaces in repository .po/workspaces.yaml:
workspaces:
- name: Product
path: .
alias: product
instructions: Focus on this product.
metadata:
'@example/plugin': { projectId: product }
Paths currently must resolve to the repository root, including equivalent symlinks. Declarations can share that root while receiving distinct workspace IDs. Names and aliases must be unique within the file. Metadata is JSON, not a credential store or an authorization boundary; each consuming plugin validates its own fields.
An existing declaration file is authoritative, including workspaces: []. Invalid or blank files fail rather than falling back. Only an absent file permits the deprecated repository config.yaml list. Personal declarations are ignored; Po does not migrate files automatically. Instructions are copied on initial admission, not overwritten later.
Hosts read declarations at composition boundaries with readWorkspaceDeclarations. Plugins inject po/workspace-registry instead of rereading YAML. Resolve the current workspace ID; path lookup can be ambiguous when declarations share a root.
Consume the session snapshot
Inject PO_CONFIG_SERVICE and call requirePoConfigContext inside the owning service fiber:
import { PO_CONFIG_SERVICE, requirePoConfigContext } from '@agimon-ai/po-config';
context.inject([PO_CONFIG_SERVICE], (context) => {
const snapshot = requirePoConfigContext(context);
// Consume snapshot.settings without mutating it.
});
Snapshots are deeply frozen. Do not retain one across provider or session replacement. Selection changes go through the shared coordinator, not direct edits to harness state. Runtime packages use injected configuration; host composition code can use the FileSystem-based readPoConfig with explicit environment and home directory. Node-only loaders are compatibility shims, not portable runtime APIs.
Focused exports include /config, /piConfig, /configSchema, and /piContext; inspect package.json for the current public surface.
Remote session summary
The remote show_session tool returns a read-only summary and an MCP App for compatible hosts. It exposes session identity and selection, not credentials, instruction text, or absolute repository paths. Conversation-routed callers must preserve host-supplied conversation metadata on every call, including refresh. Otherwise use a dedicated-session connection; there is no shared-session fallback.
MCP UI assets are generated by the build. Do not edit them or reuse an old content-hashed resource URI. Source tests do not establish behavior inside a third-party MCP App host.
Development
Run pnpm build, pnpm typecheck, pnpm test, and pnpm lint from this package. Help guidance is published through llms.txt and src/prompts.
License
Business Source License 1.1: free for personal use, organisations under USD 1M revenue, non-profits and education. See LICENSE and https://agimon.ai/licensing.