@agimon-ai/po 0.0.0-alpha.0

package/docs/server/ipc.md

@@ -0,0 +1,97 @@
+# Client protocol and in-process APIs
+
+The canonical server has one client-neutral listener. It exposes HTTP routes and an authenticated WebSocket at `/api/ws`; the server keeps the Pi harness, typed session services, and package APIs in process.
+
+## The transport design
+
+```text
+                       po-server
+                             |
+          +------------------+------------------+
+          |                                     |
+          v                                     v
+   HTTP control surface                 /api/ws WebSocket
+ health, sessions, APIs                Pi 0.85 Chord services
+          |                                     |
+          +------------------+------------------+
+                             v
+                 DirectHarnessRuntime
+```
+
+The listener binds to loopback by default. It is a network listener with an explicit bearer capability, not a filesystem endpoint. There is no internal raw command bridge and no separate API listener.
+
+## HTTP routes
+
+The server exposes these client-neutral routes:
+
+| Route                                                                  | Contract                                    |
+| ---------------------------------------------------------------------- | ------------------------------------------- |
+| `GET /api/health`                                                      | Unauthenticated readiness and session count |
+| `GET /api/workspaces/<workspace-id>/sessions`                          | Session metadata for the headless hub       |
+| `GET /api/workspaces/<workspace-id>/sessions/<id>`                     | One session's metadata                      |
+| `GET /api/events`                                                      | Server-sent session and channel events      |
+| `GET /api/workspaces/<workspace-id>/sessions/<id>/channels`            | Current channel projections                 |
+| `POST /api/workspaces/<workspace-id>/sessions/<id>/channel/<type>`     | Deliver a channel operation                 |
+| `/api/workspaces/<workspace-id>/sessions/<id>/plugins/<base-path>/...` | Dispatch a session package API in process   |
+
+All routes other than health require the configured token. HTTP clients should send `Authorization: Bearer <token>` or `x-po-token`. The WebSocket may use the same capability in its authorization header or query string; avoid query strings when a header is available because URLs can be logged.
+
+The old raw command route is not part of this surface. Session control uses the typed protocol described below.
+
+## `/api/ws` protocol
+
+`/api/ws` carries the Pi 0.85 byte protocol over an already-authenticated WebSocket. The server hosts the stable cockpit server identity and publishes these typed services:
+
+- `po.hub.v1` lists sessions, subscribes to channel events, and sends typed channel operations;
+- `po.session-management.v1` attaches and detaches a session; and
+- `po.session.v1` exposes one session's state and operations.
+
+A client first attaches through the management service, then binds the session service for that session. The service boundary is typed even though the transport carries protocol bytes.
+
+## Typed session operations
+
+`po.session.v1` exposes:
+
+- `prompt`, with `waitFor: "accepted"` or `"settled"`;
+- `steer`, `followUp`, `abort`, and `clearQueue`;
+- `setModel`, `setThinking`, `compact`, and `setName`;
+- `rewind`, including optional summarization and instructions;
+- `extensionUiResponse`;
+- `getState`, `getSessionStats`, and `getCommands`; and
+- `getAvailableModels` and `getAvailableThinkingLevels`.
+
+A prompt waits for the agent to settle by default. `accepted` returns after authoritative submission without owning the turn lifetime. A second prompt during a turn is rejected. Steering and abort require an active turn. Context cancellation aborts the active runtime operation.
+
+The session state contains an authoritative transcript snapshot, phase, model, thinking level, queue, revision, transient progress, concurrent in-flight items, and presentation state. Typed query methods are the source of truth for current state, not an event stream assembled by a client.
+
+## Replay and consistency
+
+Chord state replication sends a fresh attachment the current service state. The session journal is the durable history source. Presentation events are retained in memory only, up to 1,024 events or 8 MiB, and the state reports how many were dropped. Current status, widget, dialog, and custom-entry projections are retained independently so a reconnect can recover current UI state. Branch navigation resets custom projections and increments `resetRevision`.
+
+The hub's session and channel event history is also bounded to 1,024 events. These windows are reconnect aids, not durable history. Clients should resnapshot and use typed queries whenever a revision gap or dropped count is observed. Query replies for full history and model discovery are not treated as replayable presentation events.
+
+## Session package APIs
+
+A package API is registered by a server facet and called through the in-process `Request` adapter. The listener strips `/api/workspaces/<workspace-id>/sessions/<id>/plugins/<base-path>` before invoking the handler, so a request to `/api/workspaces/<workspace-id>/sessions/one/plugins/runner/runs/r1/log` reaches the `runner` handler as `/runs/r1/log`.
+
+Package handlers run with the session's trusted host context. They still validate request bodies, bound reads and streams, constrain paths, and avoid returning secrets merely because the caller passed the listener token.
+
+## Related guides
+
+- [Lifecycle](lifecycle.md) explains startup, readiness, and shutdown.
+- [Session APIs](api.md) defines descriptor loading and the TypeScript surface.
+- [Security](security.md) explains token validation, listener exposure, and trusted code.
+
+## Scoped route hierarchy
+
+| Scope     | REST resource                                          | Package APIs                                                             | WebSocket                                                 |
+| --------- | ------------------------------------------------------ | ------------------------------------------------------------------------ | --------------------------------------------------------- |
+| Global    | `/api/settings`                                        | `/api/plugins/<package>`                                                 | `/api/ws`                                                 |
+| Workspace | `/api/workspaces/<workspace-id>`                       | `/api/workspaces/<workspace-id>/plugins/<package>`                       | `/api/workspaces/<workspace-id>/ws`                       |
+| Session   | `/api/workspaces/<workspace-id>/sessions/<session-id>` | `/api/workspaces/<workspace-id>/sessions/<session-id>/plugins/<package>` | `/api/workspaces/<workspace-id>/sessions/<session-id>/ws` |
+
+Workspace settings are at `/api/workspaces/<workspace-id>/settings`. Create or admit a workspace with `POST /api/workspaces` and a `root`, then create a session with `POST /api/workspaces/<workspace-id>/sessions` and an optional `name`. The admitted workspace selects the session working directory. Session listing returns only that workspace's sessions. A session ID addressed through another workspace returns `404`.
+
+The global socket retains the aggregate hub protocol used by Po Web. Workspace sockets expose only sessions in that workspace; session sockets expose only the named session. Both restrict session attachments, subscriptions, thread reads, and package calls to their addressed scope. All transports use the same Pi/Chord framing. Old flat session routes, singular plugin mounts, and `/api/pi` are removed without aliases.
+
+Startup loads global facets from the global root's live composition, workspace facets when that workspace is admitted, and session facets from the owning workspace's composition with the session's selection. REST requests dispatch only to that mount; there is no fallback to another scope.

package/docs/server/lifecycle.md

@@ -0,0 +1,108 @@
+# Session lifecycle
+
+Package hooks follow the [plugin lifecycle contract](../../../po-core/docs/plugins.md): register, `onStart`, `onStop`, unregister, and `onDispose`. Server readiness waits for required plugin startup; browser reconnects do not restart those plugins.
+
+`po-server` owns one session boundary from startup through shutdown. The Pi harness, session services, package facets, and listener live in the same process. A client can disconnect without stopping the runtime, and a later client can recover the current replicated state.
+
+## The ownership model
+
+```text
+po-server process
+  |
+  +-- session manager and headless hub
+  +-- DirectHarnessRuntime
+  +-- typed management and session services
+  +-- package facet host and in-process API handlers
+  +-- HTTP and WebSocket listener, including /api/ws
+  +-- v4 JSONL session journal
+```
+
+The server, not a client, owns runtime disposal and history ownership. This gives clients a stable protocol endpoint while the runtime continues processing a turn or while a client reconnects.
+
+## Startup is readiness-ordered
+
+The server publishes the listener only after the runtime and required facets are ready:
+
+```text
+parse options and identity
+          |
+          v
+read token and compose the global scope from configuration
+          |
+          v
+import eligible facets from built package entries
+          |
+          v
+create DirectHarnessRuntime and prepare the headless host
+          |
+          v
+activate facets and initialize typed session services
+          |
+          v
+bind HTTP and /api/ws
+          |
+          v
+wait for the runtime
+```
+
+The executable performs these steps:
+
+1. Parse server options before `--` and keep the remaining values as embedded harness arguments.
+2. Read and trim the token file. An empty token stops startup, and the token is never placed in the process argument vector.
+3. Resolve session identity and harness options from the caller's repository.
+4. Compose the scope from configuration, collect the selected packages' `poServer` entries, check that each built entry stays inside its package, and filter by ownership and scope before importing modules through their content-addressed URLs.
+5. Create the direct runtime with explicit history ownership, model configuration, session identity, and working directory.
+6. Prepare and activate the selected server facets. Required failures stop readiness; optional failures are reported and isolated.
+7. Mount in-process package API handlers and initialize the typed session projection.
+8. Bind the loopback HTTP listener and authenticated `/api/ws` WebSocket endpoint.
+
+A startup error is written to stderr with a `[po-server]` prefix and exits non-zero. Successful startup waits for the direct runtime, not for a client to connect.
+
+## Steady state
+
+Once ready, the server holds a stable session boundary:
+
+| Owned resource                     | Lifetime                         |
+| ---------------------------------- | -------------------------------- |
+| Session ID and name                | Whole server process             |
+| Direct harness runtime             | Whole server process             |
+| Typed session state and operations | Whole server process             |
+| Package facet registrations        | Until shutdown or facet disposal |
+| HTTP and `/api/ws` listener        | Whole server process             |
+| Session journal ownership          | Whole server process             |
+
+The session service projects runtime activity into an authoritative snapshot, transient progress, concurrent in-flight items, and bounded presentation events. A client does not need to remain connected for the runtime to update the journal.
+
+Selection and minor-mode changes are applied through the in-process headless host. They update the runtime's tools, resources, and projected composition without changing the server identity or requiring another Pi process.
+
+## Reconnect and replay
+
+A new protocol attachment receives replicated state rather than an old transport backlog. The session state includes the current transcript, phase, model, thinking level, queue, in-flight items, and presentation projection. The session journal remains the durable source for history and is rehydrated when the runtime opens it.
+
+Live presentation events are bounded to 1,024 events or 8 MiB. The state reports a `dropped` count when that window overflows. Latest status, widget, dialog, and custom-entry projections are retained separately, so a reconnect can render current UI state even after older live events were discarded. A branch replacement resets custom presentation state and reports `resetRevision`.
+
+This is recovery state, not an audit log. Clients that need authoritative transcript or configuration data should use the typed snapshot and query operations. A client must not infer missing history from the bounded presentation window.
+
+## Package facet changes
+
+Each facet is imported through a URL that changes with its package content. Rebuilding or upgrading a package does not mutate a running session: the next new session imports the new build. Global and workspace scopes are checked again when a session opens or a workspace is admitted, and remount when an entry changed; a failed remount restores the previous facets. After a set number of superseded package versions, the server restarts at the next idle moment so old modules do not accumulate. During shutdown, facet disposers run before the host and runtime release their resources.
+
+## Shutdown and failures
+
+`SIGINT`, `SIGTERM`, runtime exit, and explicit disposal all disable new operations and release resources in ownership order:
+
+1. stop accepting new package and session operations;
+2. close active facet registrations and package handlers;
+3. stop the headless host and pending extension interactions;
+4. close the typed service projection and direct runtime;
+5. release history ownership and close the JSONL repository;
+6. close the listener and flush bounded telemetry.
+
+A runtime failure is a session failure. The server does not replace it with an alternate process or silently switch to another module set. A history ownership conflict likewise fails closed to avoid concurrent writers.
+
+## Related guides
+
+- [Getting started](getting-started.md) covers launch options and live composition.
+- [IPC](ipc.md) explains `/api/ws`, typed services, HTTP routes, and replay.
+- [Session APIs](api.md) explains descriptor loading and handler lifetime.
+- [Security](security.md) describes listener, token, history, and trusted-code boundaries.

package/docs/server/security.md

@@ -0,0 +1,101 @@
+# Security and trust boundaries
+
+`po-server` protects access to one local agent runtime. It is not a sandbox and it is not a public gateway. The harness may run shell commands with the account's authority, so reaching its control surface is equivalent to controlling that session.
+
+## The trust model
+
+```text
+trusted owner account
+  |
+  +-- po-server
+        +-- DirectHarnessRuntime
+        +-- configured extensions and server facets
+        +-- session journal and in-process APIs
+        +-- authenticated HTTP/WebSocket listener
+  |
+  +-- trusted local client or Po Web
+        +-- browser boundary owned by Po Web
+```
+
+The server answers which callers can reach the session. Loopback binding and a random token narrow that set. They do not defend against root, a compromised owner account, hostile code already running as that owner, or a malicious extension loaded into the runtime.
+
+Remote browser authentication, tunnel policy, passkeys, and containment belong to Po Web. The server's listener is not a replacement for those controls.
+
+## Security goals
+
+The design aims to:
+
+- keep the default listener on loopback;
+- keep the session token out of process arguments and application state sent to clients;
+- authenticate direct HTTP and `/api/ws` protocol access with a random capability;
+- load only the built `poServer` entries the scope's configuration selects, each confined to its package;
+- keep package handlers in process while isolating optional facet failures; and
+- preserve session history ownership so two runtimes cannot write the same journal concurrently.
+
+It does not attempt to:
+
+- contain the harness or trusted package code;
+- protect data from the account running the server;
+- encrypt traffic when the listener is exposed without TLS; or
+- authorize arbitrary reverse proxies or tunnels.
+
+## Capability map
+
+| Asset                       | Protection                                                             | Remaining trust                                                       |
+| --------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| HTTP and `/api/ws` listener | Loopback by default; token required except health                      | Owner, root, token holder, and any exposed reverse proxy              |
+| Listener token              | Read from a file and compared as a bearer capability                   | Caller creates and protects the file                                  |
+| Server facets               | Live composition, entries confined to their package, content URLs      | Repository configuration and installed package contents are trusted   |
+| Session journal             | Explicit history ownership and v4 JSONL storage                        | Owner and any process able to access the session directory            |
+| Package APIs                | In-process registration and fixed route mounts                         | Handlers are trusted executable code                                  |
+| Direct harness              | Same-process runtime with configured working directory and environment | Command, configuration, repository, model providers, and dependencies |
+
+Create the token before launch with an owner-only umask:
+
+```bash
+(umask 077; openssl rand -base64 32 > "$token_file")
+```
+
+Do not store it in the repository, a shared runtime directory, a public environment variable, or an argument list. Rotating it requires stopping the server, replacing the protected file, and starting the session again.
+
+## Listener authentication
+
+`/api/health` is intentionally unauthenticated so a local supervisor can check readiness. Every other HTTP route and the `/api/ws` upgrade require the configured token. HTTP clients should use `Authorization: Bearer <token>` or `x-po-token`. A WebSocket client may use the same capability in its upgrade headers or query string. Prefer a header because URLs can appear in logs.
+
+A token authenticates the caller to the session. It is not a per-operation permission system. A holder can prompt, steer, abort, change configuration, rewind, answer extension UI, and invoke mounted package APIs. Treat it as full session control.
+
+## Package trust
+
+The server does not compile or discover package code while serving a request. When it admits a scope or starts a session, it composes that scope's configuration, reads the selected packages' `poServer` declarations, confines each built entry to its package, filters ownership and scope, and then imports and starts each eligible facet.
+
+Required facet failures prevent readiness. Optional failures are reported and isolated. An import that times out or throws is not retried, and a failed entry never selects an alternate directory or legacy module set.
+
+Package handlers receive trusted process context, not automatic browser authorization. Validate bodies, bound reads and streams, constrain file paths to the intended scope, and do not return secrets merely because a request arrived with a valid server token.
+
+## Browser and remote access
+
+Po Web owns browser authentication and proxies `/api/ws` to the session server. It can add the server token on the upstream request without exposing that token to browser JavaScript. A remote browser receives Po Web's separate device and session credentials, which can still grant powerful session control.
+
+Before putting the cockpit behind a tunnel, review the web package's pairing, origin, cookie, passkey, sealed transport, signed bundle, and optional container controls. Do not publish the server listener through an unauthenticated TCP forwarder. A tunnel changes reachability, not authority.
+
+## Data, replay, and diagnostics
+
+The session journal contains conversation and tool history according to the upstream v4 JSONL format. The runtime also keeps current transcript state, in-flight work, and bounded presentation events in process memory. Presentation history is limited to 1,024 events or 8 MiB and reports dropped events; current projections are retained separately. This supports reconnect recovery but is not a durable audit log.
+
+Server telemetry records lifecycle and coarse usage events. Its transcript aggregate omits message and tool content. This is a telemetry property, not a guarantee that clients, extensions, package APIs, or the harness do not log their own data.
+
+## Operating posture
+
+1. Create the token under an owner-only directory.
+2. Keep the session journal, installed packages, and the Po home build directory private.
+3. Treat repository configuration, model providers, extensions, and server facets as executable inputs.
+4. Bind direct servers to loopback unless an authenticated TLS boundary is already in place.
+5. Use Po Web's documented controls for browser and remote access.
+6. Rotate the token by replacing the file while the server is stopped.
+7. Do not rely on an obscure path, port, or URL as authentication.
+
+## Known limits
+
+Loopback and file permissions do not defend against root or the owner account. A token holder can control the session. Package APIs and extensions run as trusted code. The replay window and transcript projection keep data in process memory, while the journal persists session history. None of these controls contain what the harness can do inside its working environment.
+
+See [IPC](ipc.md) for exact protocol behavior and [Lifecycle](lifecycle.md) for startup, cleanup, and history recovery.

package/llms.txt

@@ -0,0 +1,12 @@
+# Po
+
+Package-owned guidance for using and extending the Po agent harness.
+
+## How to author
+
+- [Author a Po extension](./src/prompts/po-author-extension/SKILL.md): Create or update a Po extension inside or outside this monorepo.
+- [Extension authoring contract](./src/prompts/po-author-extension/references/extension-contract.md): Package shape, Cordis lifecycle, Help contribution, and verification requirements.
+
+## Package reference
+
+- [Package README](./README.md): Installation, configuration, modes, domains, profiles, and runtime behavior.

package/package.json

@@ -0,0 +1,295 @@
+{
+  "name": "@agimon-ai/po",
+  "version": "0.0.0-alpha.0",
+  "description": "Opinionated, composable agent harness for scoped tools, skills, MCP servers, and developer workflows.",
+  "keywords": [
+    "agent-harness",
+    "ai",
+    "coding-agent",
+    "developer-tools",
+    "pi",
+    "pi-coding-agent",
+    "pi-package",
+    "po"
+  ],
+  "homepage": "https://agimon.ai",
+  "bugs": {
+    "url": "https://github.com/AgiFlow/po/issues"
+  },
+  "license": "MIT",
+  "author": "Vuong Ngo",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AgiFlow/po.git",
+    "directory": "packages/cli/po"
+  },
+  "bin": {
+    "doom-runner": "./dist/bin/doomRunner.mjs",
+    "po": "./dist/bin/cli.mjs",
+    "po-server": "./dist/bin/serve.mjs"
+  },
+  "files": [
+    "assets",
+    "dist",
+    "docs/server",
+    "llms.txt",
+    "README.md",
+    "src/prompts"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./bin/cli": {
+      "types": "./dist/bin/cli.d.mts",
+      "import": "./dist/bin/cli.mjs",
+      "require": "./dist/bin/cli.cjs"
+    },
+    "./bin/doomRunner": {
+      "types": "./dist/bin/doomRunner.d.mts",
+      "import": "./dist/bin/doomRunner.mjs",
+      "require": "./dist/bin/doomRunner.cjs"
+    },
+    "./cli": {
+      "types": "./dist/cli.d.mts",
+      "import": "./dist/cli.mjs",
+      "require": "./dist/cli.cjs"
+    },
+    "./cliApp": {
+      "types": "./dist/cliApp.d.mts",
+      "import": "./dist/cliApp.mjs",
+      "require": "./dist/cliApp.cjs"
+    },
+    "./compatibilityOptions": {
+      "types": "./dist/compatibilityOptions.d.mts",
+      "import": "./dist/compatibilityOptions.mjs",
+      "require": "./dist/compatibilityOptions.cjs"
+    },
+    "./help": {
+      "types": "./dist/help.d.mts",
+      "import": "./dist/help.mjs",
+      "require": "./dist/help.cjs"
+    },
+    "./matrixOptions": {
+      "types": "./dist/matrixOptions.d.mts",
+      "import": "./dist/matrixOptions.mjs",
+      "require": "./dist/matrixOptions.cjs"
+    },
+    "./options": {
+      "types": "./dist/options.d.mts",
+      "import": "./dist/options.mjs",
+      "require": "./dist/options.cjs"
+    },
+    "./commands": {
+      "types": "./dist/commands.d.mts",
+      "import": "./dist/commands.mjs",
+      "require": "./dist/commands.cjs"
+    },
+    "./baseCommand": {
+      "types": "./dist/baseCommand.d.mts",
+      "import": "./dist/baseCommand.mjs",
+      "require": "./dist/baseCommand.cjs"
+    },
+    "./compatibilityCommand": {
+      "types": "./dist/compatibilityCommand.d.mts",
+      "import": "./dist/compatibilityCommand.mjs",
+      "require": "./dist/compatibilityCommand.cjs"
+    },
+    "./emitMcpCommand": {
+      "types": "./dist/emitMcpCommand.d.mts",
+      "import": "./dist/emitMcpCommand.mjs",
+      "require": "./dist/emitMcpCommand.cjs"
+    },
+    "./explainCommand": {
+      "types": "./dist/explainCommand.d.mts",
+      "import": "./dist/explainCommand.mjs",
+      "require": "./dist/explainCommand.cjs"
+    },
+    "./initCommand": {
+      "types": "./dist/initCommand.d.mts",
+      "import": "./dist/initCommand.mjs",
+      "require": "./dist/initCommand.cjs"
+    },
+    "./config": {
+      "types": "./dist/config.d.mts",
+      "import": "./dist/config.mjs",
+      "require": "./dist/config.cjs"
+    },
+    "./harnessState": {
+      "types": "./dist/harnessState.d.mts",
+      "import": "./dist/harnessState.mjs",
+      "require": "./dist/harnessState.cjs"
+    },
+    "./projectTrust": {
+      "types": "./dist/projectTrust.d.mts",
+      "import": "./dist/projectTrust.mjs",
+      "require": "./dist/projectTrust.cjs"
+    },
+    "./extensions/server": {
+      "types": "./dist/extensions/server.d.mts",
+      "import": "./dist/extensions/server.mjs",
+      "require": "./dist/extensions/server.cjs"
+    },
+    "./services": {
+      "types": "./dist/services.d.mts",
+      "import": "./dist/services.mjs",
+      "require": "./dist/services.cjs"
+    },
+    "./compatibility": {
+      "types": "./dist/compatibility.d.mts",
+      "import": "./dist/compatibility.mjs",
+      "require": "./dist/compatibility.cjs"
+    },
+    "./antigravity": {
+      "types": "./dist/antigravity.d.mts",
+      "import": "./dist/antigravity.mjs",
+      "require": "./dist/antigravity.cjs"
+    },
+    "./codex": {
+      "types": "./dist/codex.d.mts",
+      "import": "./dist/codex.mjs",
+      "require": "./dist/codex.cjs"
+    },
+    "./process": {
+      "types": "./dist/process.d.mts",
+      "import": "./dist/process.mjs",
+      "require": "./dist/process.cjs"
+    },
+    "./shared": {
+      "types": "./dist/shared.d.mts",
+      "import": "./dist/shared.mjs",
+      "require": "./dist/shared.cjs"
+    },
+    "./compatibilityContext": {
+      "types": "./dist/compatibilityContext.d.mts",
+      "import": "./dist/compatibilityContext.mjs",
+      "require": "./dist/compatibilityContext.cjs"
+    },
+    "./harnessContext": {
+      "types": "./dist/harnessContext.d.mts",
+      "import": "./dist/harnessContext.mjs",
+      "require": "./dist/harnessContext.cjs"
+    },
+    "./matrixSwitcher": {
+      "types": "./dist/matrixSwitcher.d.mts",
+      "import": "./dist/matrixSwitcher.mjs",
+      "require": "./dist/matrixSwitcher.cjs"
+    },
+    "./mcpFilter": {
+      "types": "./dist/mcpFilter.d.mts",
+      "import": "./dist/mcpFilter.mjs",
+      "require": "./dist/mcpFilter.cjs"
+    },
+    "./resourceCollector": {
+      "types": "./dist/resourceCollector.d.mts",
+      "import": "./dist/resourceCollector.mjs",
+      "require": "./dist/resourceCollector.cjs"
+    },
+    "./utils": {
+      "types": "./dist/utils.d.mts",
+      "import": "./dist/utils.mjs",
+      "require": "./dist/utils.cjs"
+    },
+    "./repository": {
+      "types": "./dist/repository.d.mts",
+      "import": "./dist/repository.mjs",
+      "require": "./dist/repository.cjs"
+    },
+    "./package.json": "./package.json",
+    "./webBuilder": {
+      "types": "./dist/webBuilder.d.mts",
+      "import": "./dist/webBuilder.mjs",
+      "require": "./dist/webBuilder.cjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@agimon-ai/log-sink-mcp": "0.30.12",
+    "@agimon-ai/po-autostop": "0.0.0-alpha.0",
+    "@agimon-ai/po-cache": "0.0.0-alpha.0",
+    "@agimon-ai/po-config": "0.0.0-alpha.0",
+    "@agimon-ai/po-core": "0.0.0-alpha.0",
+    "@agimon-ai/po-domain": "0.0.0-alpha.0",
+    "@agimon-ai/po-major-mode": "0.0.0-alpha.0",
+    "@agimon-ai/po-minor-mode": "0.0.0-alpha.0",
+    "@agimon-ai/po-notification": "0.0.0-alpha.0",
+    "@agimon-ai/po-profile": "0.0.0-alpha.0",
+    "@agimon-ai/po-session": "0.0.0-alpha.0",
+    "@agimon-ai/po-skill": "0.0.0-alpha.0",
+    "@agimon-ai/po-telemetry": "0.0.0-alpha.0",
+    "@agimon-ai/po-ui": "0.0.0-alpha.0",
+    "@agimon-ai/po-web-components": "0.0.0-alpha.0",
+    "@agimon-ai/po-web-security": "0.0.0-alpha.0",
+    "@deepseek-ai/cordis": "4.0.4",
+    "@earendil-works/chord": "1.0.2",
+    "@earendil-works/pi-agent-core": "1.0.2",
+    "@earendil-works/pi-coding-agent": "1.0.2",
+    "@earendil-works/pi-protocol": "1.0.2",
+    "@earendil-works/pi-server": "1.0.2",
+    "@hono/node-server": "2.1.3",
+    "@simplewebauthn/server": "^14.0.3",
+    "@tailwindcss/vite": "4.3.3",
+    "@vitejs/plugin-react": "6.1.1",
+    "cross-spawn": "7.0.6",
+    "gpt-tokenizer": "4.0.0",
+    "hono": "4.13.12",
+    "minimatch": "10.2.6",
+    "protobufjs": "8.8.0",
+    "rolldown": "1.2.12",
+    "tailwindcss": "4.3.3",
+    "typebox": "1.3.34",
+    "vite": "8.3.2",
+    "ws": "8.22.0",
+    "yaml": "2.9.1"
+  },
+  "devDependencies": {
+    "@agimon-ai/po-runner": "0.0.0-alpha.0",
+    "@agimon-ai/vibe-lint-plugin-doom-cli": "0.0.0-alpha.0",
+    "@earendil-works/pi-ai": "1.0.2",
+    "@earendil-works/pi-client": "1.0.2",
+    "@modelcontextprotocol/ext-apps": "2.0.3",
+    "@modelcontextprotocol/server": "2.2.0",
+    "@playwright/test": "1.63.0",
+    "@types/cross-spawn": "6.0.6",
+    "@types/node": "26.6.4",
+    "@types/ws": "8.18.2",
+    "@vitest/coverage-v8": "5.0.3",
+    "tsdown": "0.23.0",
+    "typescript": "7.0.2",
+    "vitest": "5.0.3"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "poApiVersion": 1,
+  "poServer": {
+    "entry": "./src/extensions/server.ts",
+    "dist": "./dist/extensions/server.mjs",
+    "scopes": [
+      "global",
+      "workspace",
+      "session"
+    ],
+    "contracts": {
+      "entry": "./src/exports/apiContracts.ts",
+      "dist": "./dist/apiContracts.mjs"
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest --run",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.app.json",
+    "test-system": "vitest run --config vitest.system.config.ts",
+    "lint": "oxlint . && oxfmt . --check",
+    "fixcode": "oxlint . --fix && oxfmt .",
+    "test:app": "playwright test --config playwright.app.config.ts"
+  }
+}

package/src/prompts/po-author-extension/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: po-author-extension
+description: Create or update a Po extension package inside the Po monorepo or as an external npm package. Use for package layout, Pi discovery entries, shared Cordis lifecycle, package-owned Help, and extension verification.
+---
+
+# Author a Po extension
+
+Build the smallest extension that owns one clear capability and follows the host lifecycle already used by nearby Po packages.
+
+## Choose the environment
+
+- Inside the Po monorepo, read `AGENTS.md` and `templates/doom-extension/scaffold.yaml` before writing. Use the canonical `scaffold-doom-extension` definition when it fits, then keep only the folders the capability needs.
+- Outside the monorepo, create the equivalent public ESM package manually and depend on published Po foundation packages. Never publish `workspace:*` ranges.
+
+Choose the package tier from the capability, not convenience:
+
+- `packages/core/*` for runtime foundations that must always be present.
+- `packages/default/*` for normal distribution features selected by default configuration.
+- `packages/minor/*` for optional modes.
+- `packages/clients/*` for standalone client-facing processes.
+- `packages/expo/*` for Expo config plugins used by native clients. Extensions never go here; ship native UI as `.native` files in the extension's own package.
+- `layers/<layer>/*` for selectable layer extensions.
+
+## Workflow
+
+1. Inspect a nearby package with the same host surfaces and reuse its structure.
+2. Put logic in `services/<serviceName>/index.ts`, service ports in `type.ts`, mutable state in `models`, request handlers in `controllers`, and tools in `tools`. Keep reusable types, schemas, and constant data in their named folders. Do not create `adapters`, `container`, `commands`, or `providers` roots.
+3. Author each contribution at `src/extensions/<scope>/(backend|frontend)/<surface>/<name>[.<target>].<ext>`. Export one declaration or factory through the typed `define*` helper for that surface. Do not hand-write `pi.ts`, `server.ts`, or `web.ts`; `poExtension()` generates them beneath ignored `generated/` and builds the published host artifacts.
+4. Return typed contributions from a named declaration or per-mount factory. Factories may be async. Use optional `onStart`, `onStop`, and `onDispose` hooks for lifecycle work; helpers own Cordis initialization, registration, readiness, and cleanup.
+5. Put provider plugins in services and include them in the `services` contribution array. Consume required providers inside an owning injection with the corresponding `require...` accessor. The helper handles optional providers for native contributions such as resources and minor modes.
+6. Keep package exports explicit and flat under `src/exports`, with only reusable APIs. If the extension contributes Help, publish `src/prompts/<skill-name>/SKILL.md`, link it from `llms.txt`, and declare its descriptor in `resources` with the exact package name and `import.meta.url`.
+7. For frontend contributions, add a root `tsconfig.web.json`, keep routed `(frontend)` files out of the Node project, and typecheck both projects.
+8. Run the repository checks or equivalent standalone package checks before publishing.
+
+Read [references/extension-contract.md](references/extension-contract.md) for the concrete package, lifecycle, and verification contract.