@agimon-ai/po 0.0.0-alpha.0

package/dist/src/extensions/setupDiagnostics.mjs

@@ -0,0 +1,64 @@
+import { collectDoctorReport } from "../cli/commands/doctor/index.mjs";
+import { projectHarnessEnvironment } from "@agimon-ai/po-config/harnessState";
+import { defineTool } from "@agimon-ai/po-core/serverFacet";
+import { DOOM_HELP_WHEN } from "@agimon-ai/po-core/help";
+import { Type } from "typebox";
+//#region src/extensions/setupDiagnostics.ts
+const DIAGNOSE_SETUP_NAME = "diagnose_setup";
+const guidance = {
+	"config.yaml": "po-author-config",
+	"modes.yaml": "po-author-major-mode",
+	"domains.yaml": "po-author-domain",
+	"profiles.yaml": "po-author-profile"
+};
+function createSetupDiagnosticsTool(readScope, authorize) {
+	return defineTool({
+		name: DIAGNOSE_SETUP_NAME,
+		description: "Check this session's saved configuration, installed packages, and the global web build without changing anything. Returns scoped check results and the relevant setup guidance, never configuration values or credentials.",
+		parameters: Type.Object({}, { additionalProperties: false }),
+		when: DOOM_HELP_WHEN,
+		executionMode: "serial",
+		async execute(_input, execution) {
+			const signal = authorize(execution.signal);
+			const scope = readScope();
+			const environment = projectHarnessEnvironment({
+				root: scope.repoRoot,
+				majorMode: scope.selection.majorMode,
+				domains: [...scope.selection.domains],
+				profile: scope.selection.profile
+			}, { ...scope.environment });
+			const report = collectDoctorReport(environment, scope.cwd);
+			signal.throwIfAborted();
+			authorize(execution.signal);
+			const result = {
+				scope: "current-session",
+				configurationRoot: report.repoRoot,
+				appliedSelection: {
+					majorMode: scope.selection.majorMode,
+					domains: [...scope.selection.domains],
+					profile: scope.selection.profile
+				},
+				status: report.problems === 0 && report.skipped.length === 0 ? "checks-passed" : "issues-found",
+				checks: report.sections.map((section) => ({
+					area: section.label,
+					status: section.problems.length ? "failed" : "passed",
+					problemCount: section.problems.length,
+					guidance: guidance[section.label] ?? "po-use-help"
+				})),
+				skipped: report.skipped,
+				limitations: "These are saved configuration and installation checks, not a network authentication or agent health test. Error text and configuration values are omitted to protect credentials. Inspect a failed area with its package guidance before proposing a repair."
+			};
+			return {
+				content: [{
+					type: "text",
+					text: JSON.stringify(result, null, 2)
+				}],
+				details: result
+			};
+		}
+	});
+}
+//#endregion
+export { DIAGNOSE_SETUP_NAME, createSetupDiagnosticsTool };
+
+//# sourceMappingURL=setupDiagnostics.mjs.map

package/dist/src/extensions/setupDiagnostics.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"setupDiagnostics.mjs","names":["HELP_WHEN"],"sources":["../../../src/extensions/setupDiagnostics.ts"],"sourcesContent":["import { projectHarnessEnvironment } from '@agimon-ai/po-config/harnessState';\nimport type { DoomHeadlessSelection } from '@agimon-ai/po-core/headless';\nimport { DOOM_HELP_WHEN as HELP_WHEN } from '@agimon-ai/po-core/help';\nimport { defineTool } from '@agimon-ai/po-core/serverFacet';\nimport { Type } from 'typebox';\n\nimport { collectDoctorReport } from '../cli/commands/doctor';\n\nexport const DIAGNOSE_SETUP_NAME = 'diagnose_setup';\nexport interface SetupDiagnosticScope {\n  repoRoot: string;\n  cwd: string;\n  environment: Readonly<Record<string, string | undefined>>;\n  selection: Pick<DoomHeadlessSelection, 'majorMode' | 'domains' | 'profile'>;\n}\n\nconst guidance: Readonly<Record<string, string>> = {\n  'config.yaml': 'po-author-config',\n  'modes.yaml': 'po-author-major-mode',\n  'domains.yaml': 'po-author-domain',\n  'profiles.yaml': 'po-author-profile',\n};\n\nexport function createSetupDiagnosticsTool(\n  readScope: () => SetupDiagnosticScope,\n  authorize: (signal?: AbortSignal) => AbortSignal,\n) {\n  return defineTool({\n    name: DIAGNOSE_SETUP_NAME,\n    description:\n      \"Check this session's saved configuration, installed packages, and the global web build without changing anything. Returns scoped check results and the relevant setup guidance, never configuration values or credentials.\",\n    parameters: Type.Object({}, { additionalProperties: false }),\n    when: HELP_WHEN,\n    executionMode: 'serial',\n    async execute(_input, execution) {\n      const signal = authorize(execution.signal);\n      const scope = readScope();\n      const environment = projectHarnessEnvironment(\n        {\n          root: scope.repoRoot,\n          majorMode: scope.selection.majorMode,\n          domains: [...scope.selection.domains],\n          profile: scope.selection.profile,\n        },\n        { ...scope.environment },\n      );\n      const report = collectDoctorReport(environment, scope.cwd);\n      signal.throwIfAborted();\n      authorize(execution.signal);\n      const result = {\n        scope: 'current-session',\n        configurationRoot: report.repoRoot,\n        appliedSelection: {\n          majorMode: scope.selection.majorMode,\n          domains: [...scope.selection.domains],\n          profile: scope.selection.profile,\n        },\n        status: report.problems === 0 && report.skipped.length === 0 ? 'checks-passed' : 'issues-found',\n        checks: report.sections.map((section) => ({\n          area: section.label,\n          status: section.problems.length ? 'failed' : 'passed',\n          problemCount: section.problems.length,\n          guidance: guidance[section.label] ?? 'po-use-help',\n        })),\n        skipped: report.skipped,\n        limitations:\n          'These are saved configuration and installation checks, not a network authentication or agent health test. Error text and configuration values are omitted to protect credentials. Inspect a failed area with its package guidance before proposing a repair.',\n      };\n      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], details: result };\n    },\n  });\n}\n"],"mappings":";;;;;;AAQA,MAAa,sBAAsB;AAQnC,MAAM,WAA6C;CACjD,eAAe;CACf,cAAc;CACd,gBAAgB;CAChB,iBAAiB;AACnB;AAEA,SAAgB,2BACd,WACA,WACA;CACA,OAAO,WAAW;EAChB,MAAM;EACN,aACE;EACF,YAAY,KAAK,OAAO,CAAC,GAAG,EAAE,sBAAsB,MAAM,CAAC;EAC3D,MAAMA;EACN,eAAe;EACf,MAAM,QAAQ,QAAQ,WAAW;GAC/B,MAAM,SAAS,UAAU,UAAU,MAAM;GACzC,MAAM,QAAQ,UAAU;GACxB,MAAM,cAAc,0BAClB;IACE,MAAM,MAAM;IACZ,WAAW,MAAM,UAAU;IAC3B,SAAS,CAAC,GAAG,MAAM,UAAU,OAAO;IACpC,SAAS,MAAM,UAAU;GAC3B,GACA,EAAE,GAAG,MAAM,YAAY,CACzB;GACA,MAAM,SAAS,oBAAoB,aAAa,MAAM,GAAG;GACzD,OAAO,eAAe;GACtB,UAAU,UAAU,MAAM;GAC1B,MAAM,SAAS;IACb,OAAO;IACP,mBAAmB,OAAO;IAC1B,kBAAkB;KAChB,WAAW,MAAM,UAAU;KAC3B,SAAS,CAAC,GAAG,MAAM,UAAU,OAAO;KACpC,SAAS,MAAM,UAAU;IAC3B;IACA,QAAQ,OAAO,aAAa,KAAK,OAAO,QAAQ,WAAW,IAAI,kBAAkB;IACjF,QAAQ,OAAO,SAAS,KAAK,aAAa;KACxC,MAAM,QAAQ;KACd,QAAQ,QAAQ,SAAS,SAAS,WAAW;KAC7C,cAAc,QAAQ,SAAS;KAC/B,UAAU,SAAS,QAAQ,UAAU;IACvC,EAAE;IACF,SAAS,OAAO;IAChB,aACE;GACJ;GACA,OAAO;IAAE,SAAS,CAAC;KAAE,MAAM;KAAQ,MAAM,KAAK,UAAU,QAAQ,MAAM,CAAC;IAAE,CAAC;IAAG,SAAS;GAAO;EAC/F;CACF,CAAC;AACH"}

package/dist/utils.cjs

@@ -0,0 +1,4 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_index = require("./src/composition/repository/index.cjs");
+exports.findRepositoryRoot = require_index.findRepositoryRoot;
+exports.isRepositoryRoot = require_index.isRepositoryRoot;

package/dist/utils.d.mts

@@ -0,0 +1,2 @@
+import { findRepositoryRoot, isRepositoryRoot } from "./src/composition/repository/index.mjs";
+export { findRepositoryRoot, isRepositoryRoot };

package/dist/utils.mjs

@@ -0,0 +1,2 @@
+import { findRepositoryRoot, isRepositoryRoot } from "./src/composition/repository/index.mjs";
+export { findRepositoryRoot, isRepositoryRoot };

package/dist/webBuilder.cjs

@@ -0,0 +1,59 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_webPluginManifest = require("./src/builders/web/webPluginManifest.cjs");
+const require_webPluginScan = require("./src/builders/web/webPluginScan.cjs");
+const require_index = require("./src/builders/web/index.cjs");
+const require_bundleAssetPolicy = require("./src/builders/web/bundleAssetPolicy.cjs");
+const require_webDevRoots = require("./src/builders/web/webDevRoots.cjs");
+const require_webPluginGenerate = require("./src/builders/web/webPluginGenerate.cjs");
+const require_webPluginVite = require("./src/builders/web/webPluginVite.cjs");
+const require_bundle = require("./src/builders/web/bundle.cjs");
+exports.BASE_STYLE_ENTRY = require_webPluginGenerate.BASE_STYLE_ENTRY;
+exports.BUILD_RECORD = require_index.BUILD_RECORD;
+exports.BUILTIN_CLIENT_MODULE = require_webPluginGenerate.BUILTIN_CLIENT_MODULE;
+exports.BUILTIN_CSS_MODULE = require_webPluginGenerate.BUILTIN_CSS_MODULE;
+exports.DEFAULT_REGISTRATION_ORDER = require_webPluginManifest.DEFAULT_REGISTRATION_ORDER;
+exports.PLUGIN_ROOTS_ENV = require_webDevRoots.PLUGIN_ROOTS_ENV;
+exports.PLUGIN_ROOTS_FILE = require_webDevRoots.PLUGIN_ROOTS_FILE;
+exports.WEB_PLUGIN_FACADE_CHUNK = require_webPluginVite.WEB_PLUGIN_FACADE_CHUNK;
+exports.WEB_PLUGIN_RUNTIME_SPECIFIERS = require_webPluginVite.WEB_PLUGIN_RUNTIME_SPECIFIERS;
+exports.WebPluginManifestError = require_webPluginManifest.WebPluginManifestError;
+exports.buildKeyDirectory = require_index.buildKeyDirectory;
+exports.bundleAssetPolicyPlugin = require_bundleAssetPolicy.bundleAssetPolicyPlugin;
+exports.bundleCockpitWeb = require_bundle.bundleCockpitWeb;
+exports.classifyOptionalBundleAssets = require_bundleAssetPolicy.classifyOptionalBundleAssets;
+exports.compareCodeUnits = require_webPluginManifest.compareCodeUnits;
+exports.compositionPackageRoots = require_index.compositionPackageRoots;
+exports.declaredPluginsOf = require_webPluginManifest.declaredPluginsOf;
+exports.devPluginRoots = require_webDevRoots.devPluginRoots;
+exports.duplicatePluginCopies = require_index.duplicatePluginCopies;
+exports.ensureBuiltinWebPluginModules = require_webPluginGenerate.ensureBuiltinWebPluginModules;
+exports.ensureGlobalWebBuild = require_index.ensureGlobalWebBuild;
+exports.esModuleExportNames = require_webPluginVite.esModuleExportNames;
+exports.globalBuildKey = require_index.globalBuildKey;
+exports.isWebPluginFacade = require_webPluginVite.isWebPluginFacade;
+exports.manifestClosure = require_bundle.manifestClosure;
+exports.mountWebPluginIds = require_index.mountWebPluginIds;
+exports.mountWebPluginSlots = require_index.mountWebPluginSlots;
+exports.newestGlobalWebBuildKey = require_index.newestGlobalWebBuildKey;
+exports.orderDeclaredPlugins = require_webPluginManifest.orderDeclaredPlugins;
+exports.packageRootOf = require_index.packageRootOf;
+exports.pluginBlocksOf = require_webPluginManifest.pluginBlocksOf;
+exports.pluginSlot = require_webPluginManifest.pluginSlot;
+exports.pluginStyleEntryName = require_webPluginGenerate.pluginStyleEntryName;
+exports.readBuildJson = require_index.readBuildJson;
+exports.readDevPluginRoots = require_webPluginVite.readDevPluginRoots;
+exports.readGlobalWebBuildRecord = require_index.readGlobalWebBuildRecord;
+exports.readGlobalWebBuildStatus = require_index.readGlobalWebBuildStatus;
+exports.renderBuiltinWebPluginModules = require_webPluginGenerate.renderBuiltinWebPluginModules;
+exports.renderWebPluginFacade = require_webPluginVite.renderWebPluginFacade;
+exports.scanWebPlugins = require_webPluginScan.scanWebPlugins;
+exports.singleFlightBuild = require_index.singleFlightBuild;
+exports.unslottedWebPackages = require_index.unslottedWebPackages;
+exports.webHostVersion = require_index.webHostVersion;
+exports.webPluginCssAlias = require_webPluginVite.webPluginCssAlias;
+exports.webPluginOverridePlugin = require_webPluginVite.webPluginOverridePlugin;
+exports.webPluginRuntimeAliases = require_webPluginVite.webPluginRuntimeAliases;
+exports.webPluginRuntimeFacadePlugin = require_webPluginVite.webPluginRuntimeFacadePlugin;
+exports.webPluginRuntimeGlobal = require_webPluginVite.webPluginRuntimeGlobal;
+exports.writeSyncWebPluginModules = require_webPluginGenerate.writeSyncWebPluginModules;
+exports.writeWebPluginStyleEntries = require_webPluginGenerate.writeWebPluginStyleEntries;

package/dist/webBuilder.d.mts

@@ -0,0 +1,9 @@
+import { DEFAULT_REGISTRATION_ORDER, DeclaredWebPlugin, PluginManifestField, WebPluginEntryDeclaration, WebPluginManifestError, compareCodeUnits, declaredPluginsOf, orderDeclaredPlugins, pluginBlocksOf, pluginSlot } from "./src/builders/web/webPluginManifest.mjs";
+import { BUILD_RECORD, GlobalWebBuildInput, GlobalWebBuildRecord, GlobalWebBuildResult, buildKeyDirectory, compositionPackageRoots, duplicatePluginCopies, ensureGlobalWebBuild, globalBuildKey, mountWebPluginIds, mountWebPluginSlots, newestGlobalWebBuildKey, packageRootOf, readBuildJson, readGlobalWebBuildRecord, readGlobalWebBuildStatus, singleFlightBuild, unslottedWebPackages, webHostVersion } from "./src/builders/web/index.mjs";
+import { BundleCockpitWebOptions, BundleCockpitWebResult, WebPluginBuildRecord, bundleCockpitWeb, manifestClosure } from "./src/builders/web/bundle.mjs";
+import { BASE_STYLE_ENTRY, BUILTIN_CLIENT_MODULE, BUILTIN_CSS_MODULE, SyncGeneratedModules, WebPluginRegistryModules, WebPluginStyleEntries, ensureBuiltinWebPluginModules, pluginStyleEntryName, renderBuiltinWebPluginModules, writeSyncWebPluginModules, writeWebPluginStyleEntries } from "./src/builders/web/webPluginGenerate.mjs";
+import { scanWebPlugins } from "./src/builders/web/webPluginScan.mjs";
+import { ExportNameReader, WEB_PLUGIN_FACADE_CHUNK, WEB_PLUGIN_RUNTIME_SPECIFIERS, esModuleExportNames, isWebPluginFacade, readDevPluginRoots, renderWebPluginFacade, webPluginCssAlias, webPluginOverridePlugin, webPluginRuntimeAliases, webPluginRuntimeFacadePlugin, webPluginRuntimeGlobal } from "./src/builders/web/webPluginVite.mjs";
+import { bundleAssetPolicyPlugin, classifyOptionalBundleAssets } from "./src/builders/web/bundleAssetPolicy.mjs";
+import { DevPluginRootsInput, PLUGIN_ROOTS_ENV, PLUGIN_ROOTS_FILE, devPluginRoots } from "./src/builders/web/webDevRoots.mjs";
+export { BASE_STYLE_ENTRY, BUILD_RECORD, BUILTIN_CLIENT_MODULE, BUILTIN_CSS_MODULE, BundleCockpitWebOptions, BundleCockpitWebResult, DEFAULT_REGISTRATION_ORDER, DeclaredWebPlugin, DevPluginRootsInput, ExportNameReader, GlobalWebBuildInput, GlobalWebBuildRecord, GlobalWebBuildResult, PLUGIN_ROOTS_ENV, PLUGIN_ROOTS_FILE, PluginManifestField, SyncGeneratedModules, WEB_PLUGIN_FACADE_CHUNK, WEB_PLUGIN_RUNTIME_SPECIFIERS, WebPluginBuildRecord, WebPluginEntryDeclaration, WebPluginManifestError, WebPluginRegistryModules, WebPluginStyleEntries, buildKeyDirectory, bundleAssetPolicyPlugin, bundleCockpitWeb, classifyOptionalBundleAssets, compareCodeUnits, compositionPackageRoots, declaredPluginsOf, devPluginRoots, duplicatePluginCopies, ensureBuiltinWebPluginModules, ensureGlobalWebBuild, esModuleExportNames, globalBuildKey, isWebPluginFacade, manifestClosure, mountWebPluginIds, mountWebPluginSlots, newestGlobalWebBuildKey, orderDeclaredPlugins, packageRootOf, pluginBlocksOf, pluginSlot, pluginStyleEntryName, readBuildJson, readDevPluginRoots, readGlobalWebBuildRecord, readGlobalWebBuildStatus, renderBuiltinWebPluginModules, renderWebPluginFacade, scanWebPlugins, singleFlightBuild, unslottedWebPackages, webHostVersion, webPluginCssAlias, webPluginOverridePlugin, webPluginRuntimeAliases, webPluginRuntimeFacadePlugin, webPluginRuntimeGlobal, writeSyncWebPluginModules, writeWebPluginStyleEntries };

package/dist/webBuilder.mjs

@@ -0,0 +1,9 @@
+import { DEFAULT_REGISTRATION_ORDER, WebPluginManifestError, compareCodeUnits, declaredPluginsOf, orderDeclaredPlugins, pluginBlocksOf, pluginSlot } from "./src/builders/web/webPluginManifest.mjs";
+import { scanWebPlugins } from "./src/builders/web/webPluginScan.mjs";
+import { BUILD_RECORD, buildKeyDirectory, compositionPackageRoots, duplicatePluginCopies, ensureGlobalWebBuild, globalBuildKey, mountWebPluginIds, mountWebPluginSlots, newestGlobalWebBuildKey, packageRootOf, readBuildJson, readGlobalWebBuildRecord, readGlobalWebBuildStatus, singleFlightBuild, unslottedWebPackages, webHostVersion } from "./src/builders/web/index.mjs";
+import { bundleAssetPolicyPlugin, classifyOptionalBundleAssets } from "./src/builders/web/bundleAssetPolicy.mjs";
+import { PLUGIN_ROOTS_ENV, PLUGIN_ROOTS_FILE, devPluginRoots } from "./src/builders/web/webDevRoots.mjs";
+import { BASE_STYLE_ENTRY, BUILTIN_CLIENT_MODULE, BUILTIN_CSS_MODULE, ensureBuiltinWebPluginModules, pluginStyleEntryName, renderBuiltinWebPluginModules, writeSyncWebPluginModules, writeWebPluginStyleEntries } from "./src/builders/web/webPluginGenerate.mjs";
+import { WEB_PLUGIN_FACADE_CHUNK, WEB_PLUGIN_RUNTIME_SPECIFIERS, esModuleExportNames, isWebPluginFacade, readDevPluginRoots, renderWebPluginFacade, webPluginCssAlias, webPluginOverridePlugin, webPluginRuntimeAliases, webPluginRuntimeFacadePlugin, webPluginRuntimeGlobal } from "./src/builders/web/webPluginVite.mjs";
+import { bundleCockpitWeb, manifestClosure } from "./src/builders/web/bundle.mjs";
+export { BASE_STYLE_ENTRY, BUILD_RECORD, BUILTIN_CLIENT_MODULE, BUILTIN_CSS_MODULE, DEFAULT_REGISTRATION_ORDER, PLUGIN_ROOTS_ENV, PLUGIN_ROOTS_FILE, WEB_PLUGIN_FACADE_CHUNK, WEB_PLUGIN_RUNTIME_SPECIFIERS, WebPluginManifestError, buildKeyDirectory, bundleAssetPolicyPlugin, bundleCockpitWeb, classifyOptionalBundleAssets, compareCodeUnits, compositionPackageRoots, declaredPluginsOf, devPluginRoots, duplicatePluginCopies, ensureBuiltinWebPluginModules, ensureGlobalWebBuild, esModuleExportNames, globalBuildKey, isWebPluginFacade, manifestClosure, mountWebPluginIds, mountWebPluginSlots, newestGlobalWebBuildKey, orderDeclaredPlugins, packageRootOf, pluginBlocksOf, pluginSlot, pluginStyleEntryName, readBuildJson, readDevPluginRoots, readGlobalWebBuildRecord, readGlobalWebBuildStatus, renderBuiltinWebPluginModules, renderWebPluginFacade, scanWebPlugins, singleFlightBuild, unslottedWebPackages, webHostVersion, webPluginCssAlias, webPluginOverridePlugin, webPluginRuntimeAliases, webPluginRuntimeFacadePlugin, webPluginRuntimeGlobal, writeSyncWebPluginModules, writeWebPluginStyleEntries };

package/docs/server/api-export.md

@@ -0,0 +1,86 @@
+# Export compiled client contracts
+
+After installing the global root's and the workspace's packages, run this in the workspace:
+
+```sh
+po sync
+po api-export --out ./api-schema --strict
+# Select a different session composition:
+po api-export --out ./api-schema --major-mode copilot --strict
+```
+
+The command composes the global root and the workspace live and reads each selected server facet's built `poServer.contracts.dist` straight from its installed package. Each contract module is imported in a bounded child process; the command never imports a server facet, installs packages, or starts servers. A package without a readable contract is recorded as a coverage gap. Run `po sync` first if the configuration names packages that are not installed yet.
+
+The export contains:
+
+- `openapi.json`: OpenAPI 3.1 HTTP operations, scoped plugin paths, request and response schemas, authentication, and named SSE payload schemas in `x-sse-events`.
+- `asyncapi.json`: AsyncAPI 3.0 Pi envelopes, Chord calls, subscriptions and state deltas, session methods and reconstructed state, and selected extension methods and channel payloads. `x-po` identifies scope, service, member, direction through the operation action, and operation kind.
+- `manifest.json`: selected global, workspace and session modes, contract fingerprints (the generation is always `live`), composition fingerprints, package and protocol versions, explicit dynamic values, coverage gaps, and SHA-256 hashes of both documents.
+
+The global and workspace scopes use their own default major modes. `--major-mode` changes only the session composition. Local WebSockets carry framed CBOR; remote WebSockets carry sealed envelopes around those bytes. Channel operations describe decoded payloads, not JSON WebSocket frames. The selected package's `service` and `member` identify plugin calls carried through `po.plugin.v1.invoke`.
+
+Export with `--strict` in CI. An incomplete export is still written for review, but the command exits with status 1. Missing third-party declarations do not prevent normal sync. Dynamic tool, provider and author-capability values are listed explicitly; exporting a schema does not freeze runtime capabilities or prove a client compatible.
+
+Compare committed artifacts for API drift, then validate actual client requests, server responses and decoded socket traffic against their operation schemas. Verify the document hashes before consuming a bundle, since the manifest is written last. The web client contract tests exercise real HTTP handlers; the core contract tests use the public Pi and Chord codecs and independent OpenAPI and AsyncAPI parsers.
+
+## Declare a package contract
+
+Add a separate data entry to the existing server metadata:
+
+```json
+{
+  "poServer": {
+    "entry": "./src/extensions/server.ts",
+    "dist": "./dist/extensions/server.mjs",
+    "scopes": ["session"],
+    "contracts": {
+      "entry": "./src/exports/apiContracts.ts",
+      "dist": "./dist/api-contracts.mjs"
+    }
+  }
+}
+```
+
+Build the contract as its own entry. Keep its graph free of handlers, lifecycle hooks, environment reads and service initialization. Declare every imported runtime dependency in `dependencies`, including `typebox` when using it. Undeclared imports can be accidentally bundled and behave differently after compilation.
+
+```ts
+import { defineApiContract } from '@agimon-ai/po-core/apiContracts';
+
+export default defineApiContract({
+  version: 1,
+  http: [
+    {
+      id: 'status',
+      scope: 'session',
+      basePath: 'example',
+      path: '/status',
+      method: 'GET',
+      authentication: 'owner',
+      description: 'Read status.',
+      responses: {
+        '200': {
+          description: 'Current status.',
+          schema: {
+            type: 'object',
+            properties: { ready: { type: 'boolean' } },
+            required: ['ready'],
+          },
+        },
+      },
+    },
+  ],
+  sockets: [],
+  dynamic: [],
+});
+```
+
+Source schemas use JSON Schema draft-07, including TypeBox output. The exporter namespaces local references and translates tuple keywords for OpenAPI 3.1. Use self-contained local references, without `$id` or remote references. An API-free facet should declare empty `http` and `sockets` arrays. Use `gaps` for known missing declarations; never use an unconstrained schema to hide missing coverage.
+
+The exporter is a separate `api-export` command, not a `sync` flag. For a local distribution build:
+
+```sh
+node packages/cli/po/dist/bin/cli.mjs sync
+node packages/cli/po/dist/bin/cli.mjs api-export --out /tmp/po-api-schema --strict
+```
+
+OpenAPI uses direct settings routes, plural `plugins` mounts, and workspace-nested session resources. AsyncAPI declares `/api/ws`, `/api/workspaces/{workspaceId}/ws`, and `/api/workspaces/{workspaceId}/sessions/{sessionId}/ws`. The global channel also declares the routed workspace and session operations available through the aggregate hub connection. `x-po.transportScope` identifies the addressed channel separately from the operation's composition scope.

package/docs/server/api.md

@@ -0,0 +1,144 @@
+# Session APIs
+
+Session APIs let a Po package add HTTP behavior beside the direct headless runtime it extends. A package facet is imported from the package's built `poServer.dist` entry, registered in `po-server`, and called in process. The public client route is `/api/workspaces/<workspace-id>/sessions/<session-id>/plugins/<base-path>/...`.
+
+This guide also covers the package's TypeScript exports for Node.js callers that want to compose the same in-process services.
+
+## The design
+
+```text
+package.json poServer declaration
+                |
+                v
+   live composition of the session's root
+                |
+                v
+   built dist entry, content-addressed URL
+                |
+                v
+       direct headless host
+       start(context) per API
+                |
+                v
+       in-process Request dispatch
+                |
+                v
+ /api/workspaces/<workspace-id>/sessions/<id>/plugins/<base-path>/...
+```
+
+The server resolves facet candidates from the same live composition that selects the session runtime. This ensures:
+
+- the API implementation follows the same repository, mode, and package selection as the session runtime;
+- each built entry resolves inside its own package and is imported through a URL that changes with the package content; and
+- discovery and validation happen when a scope is admitted or a session starts, not by scanning arbitrary modules at request time.
+
+The server starts each handler once, routes requests by a fixed base path, and calls `close()` during shutdown. A broken optional API is isolated so it does not take down the runtime or unrelated packages.
+
+## Declare a session API
+
+A package declares one `poServer` facet in `package.json`:
+
+```json
+{
+  "poServer": {
+    "entry": "./src/extensions/server.ts",
+    "dist": "./dist/extensions/server.mjs",
+    "scopes": ["session"]
+  }
+}
+```
+
+Publish a default-exported `DoomServerFacet` through that entry. In its `apply`, use `requireDoomServerHost(context).registerApi(api)` and return a disposer that calls the registration's `dispose()`. Declare the host service in `inject` and check scope before registering. The API implementation owns its base path.
+
+Paths are package-relative and cannot escape the package. The server records the built module path and the modes and layers that selected the package, and uses that ownership for admission. See the [complete facet example](../../../../clients/po-web/docs/package-apis.md#declare-an-api).
+
+## Implement the handler
+
+Each API registered by a facet implements this lifecycle:
+
+```ts
+interface DoomApi {
+  basePath: string;
+  start(context: DoomApiContext): {
+    fetch(request: Request): Response | Promise<Response>;
+    close(): void;
+  };
+}
+```
+
+`start()` creates session-owned resources once. `fetch()` handles requests relative to the package mount. `close()` must release timers, watchers, streams, and other resources created during startup.
+
+Keep the API adapter reusable and have the facet import it. The facet's disposer closes the registration.
+
+## Selecting the API composition
+
+The session root's configuration is the only composition source. The server reads the `poServer` declaration of each package that composition selects, checks that its built entry stays inside the package, and filters candidates by scope and ownership before importing them. It never scans arbitrary package manifests at request time and never falls back to an alternate module directory.
+
+Rebuild the package after changing a server-side API. The next new session imports the new build; running sessions keep the module they loaded.
+
+A composition that selects no API is a valid no-API state. In that case package API requests return `404`; the server still provides the typed session protocol. A required eligible facet failure prevents readiness. An optional facet failure is reported and does not remove unrelated APIs.
+
+## Routing and isolation
+
+The public path is:
+
+```text
+/api/workspaces/<workspace-id>/sessions/<session-id>/plugins/<base-path>/<package route>
+```
+
+The server removes the session and package mount prefix before calling the handler. A path outside the route returns `404`. An unknown base path returns a JSON `404`. A handler exception becomes a generic JSON `500`; other APIs remain mounted. Invalid base paths are rejected before dispatch.
+
+When two eligible APIs claim the same base path, the first keeps it and the later registration is skipped. Disabled candidates are not imported and do not reserve mount paths.
+
+## Host context and authority
+
+A session handler receives:
+
+| Field           | Meaning                                                 |
+| --------------- | ------------------------------------------------------- |
+| `scope`         | Always `session`                                        |
+| `sessionId`     | Identity of the owning session                          |
+| `cwd`           | Session working directory                               |
+| `internalToken` | Optional process context for trusted child coordination |
+| `hubToken`      | Optional context for trusted cockpit coordination       |
+| `onNotice`      | Host-visible diagnostic callback                        |
+
+These values are process context for trusted package code, not automatic route authorization. A handler must validate its own inputs and enforce resource bounds. It must not accept browser-supplied authorization headers as proof of identity. If caller identity or step-up state matters, use the trusted context supplied by Po Web.
+
+Package APIs are executable trusted code. They can access the session's authority, journal, and working directory according to their implementation. Treat generated modules like extensions and review their path, body, stream, and secret handling.
+
+## TypeScript server exports
+
+The core package publishes the in-process building blocks through `@agimon-ai/po/server`:
+
+| Export                              | Responsibility                                                   |
+| ----------------------------------- | ---------------------------------------------------------------- |
+| `createHeadlessSessionManager`      | Own direct session hosts and dispose them                        |
+| `createHeadlessHub`                 | Aggregate sessions, channels, and package API dispatch           |
+| `serveHeadlessServer`               | Expose HTTP and authenticated `/api/ws` WebSocket routes         |
+| `createAgentSessionRuntime`         | Project a direct runtime into typed session state and operations |
+| `createAgentServerService`          | Adapt one typed session service to the Pi protocol host          |
+| `createRpcTranscript`               | Reduce runtime events into the authoritative transcript          |
+| `createHeadlessChildSessionService` | Provide explicitly requested child-session capabilities          |
+
+A minimal composition is:
+
+```ts
+import { createHeadlessHub, createHeadlessSessionManager, serveHeadlessServer } from '@agimon-ai/po/server';
+
+const manager = createHeadlessSessionManager();
+const hub = createHeadlessHub({ manager });
+const server = await serveHeadlessServer({
+  headlessHub: hub,
+  port: 7533,
+  token: tokenFromOwnerOnlyFile,
+});
+```
+
+The caller remains responsible for creating admitted direct session hosts, closing `server`, closing `hub`, and closing `manager` in that order. The executable performs that lifecycle for the command-line case.
+
+## Related guides
+
+- [IPC](ipc.md) explains `/api/ws`, typed operations, package dispatch, and replay.
+- [Lifecycle](lifecycle.md) explains when facets load and close.
+- [Security](security.md) describes trusted package code and context capabilities.

package/docs/server/getting-started.md

@@ -0,0 +1,114 @@
+# Getting started
+
+`po-server` is the process boundary for one client-neutral headless Po session. It embeds the Pi harness, typed session services, and package facets in one process, then publishes an authenticated HTTP and WebSocket listener.
+
+## Choose the topology
+
+Use the server directly for a local client or a durable headless session:
+
+```text
+client -> authenticated HTTP/WebSocket listener -> po-server
+                                      \-> DirectHarnessRuntime
+```
+
+Add Po Web when a browser or remote cockpit should control the session:
+
+```text
+browser -> Po Web -> authenticated /api/ws WebSocket -> po-server
+                                                     \-> DirectHarnessRuntime
+```
+
+Po Web owns browser authentication and remote-access policy. A direct client is responsible for presenting the server token.
+
+## Requirements
+
+- Node.js 24 or newer
+- The packages your configuration names installed (`po sync` installs them)
+- A private token file
+
+The server composes each scope live from configuration and imports only the built entries that composition selects. It does not discover arbitrary package modules at startup.
+
+Install core, which owns the `po-server` executable:
+
+```bash
+npm install -g @agimon-ai/po
+```
+
+## Start a session
+
+```bash
+token_file="$(mktemp)"
+(umask 077; openssl rand -base64 32 > "$token_file")
+
+po-server \
+  --auth-token-file "$token_file" \
+  --name work \
+  -- --major-mode copilot
+```
+
+Server options come before `--`. Everything after it configures the embedded harness. The server validates those arguments, resolves the composition live, creates a direct runtime, and waits for that runtime to exit.
+
+The token is a session-control capability. It is read from the file so it does not appear in the server argument list. The server rejects an empty token but does not create or protect the file for you. Keep the file in a private directory with restrictive permissions.
+
+## What startup creates
+
+A ready session owns:
+
+| Resource               | Purpose                                                                 |
+| ---------------------- | ----------------------------------------------------------------------- |
+| Loopback HTTP listener | Health, discovery, channel, and package API routes                      |
+| `/api/ws` WebSocket    | Authenticated Pi 0.85 Chord protocol                                    |
+| Direct harness runtime | In-process Pi execution and typed session operations                    |
+| Session journal        | Upstream v4 JSONL history, normally below `~/.po/agent/server/sessions` |
+| Loaded server facets   | Built `poServer` entries the composition selects                        |
+
+No separate API listener or filesystem endpoint is created. The session service hydrates its authoritative snapshot from the journal and publishes it through the protocol state.
+
+## Command options
+
+| Option                     | Default        | Meaning                                                 |
+| -------------------------- | -------------- | ------------------------------------------------------- |
+| `--auth-token-file <path>` | required       | File containing the listener token                      |
+| `--name <name>`            | `untitled`     | Session name shown by clients                           |
+| `--session-id <id>`        | generated UUID | Stable session identity; it must not contain `/`        |
+| `--web [port]`             | 7533           | Listener port; the listener is started for every server |
+| `-- <harness arguments>`   | none           | Arguments passed to the embedded headless harness       |
+
+There is no server-side command, runtime-directory, or API-directory fallback. Composition comes from the live configuration of each scope. A required facet that cannot be imported fails startup instead of selecting a different module set.
+
+## Select the runtime composition
+
+The server follows the repository that owns the session working directory; a member checkout such as a worktree resolves its composition from the workspace root. It composes that configuration, collects the selected packages' `poServer` entries, filters them for the active major mode and layers, and installs the resulting facets into the direct headless host.
+
+Each entry is imported through a URL that changes with the package content. After you rebuild or upgrade a package, the next new session imports the new build without a server restart; running sessions keep the module they loaded. Run `po sync` after changing configuration that names new packages, so they are installed.
+
+## Add the browser cockpit
+
+Po Web can proxy the server's `/api/ws` endpoint:
+
+```bash
+npm install -g @agimon-ai/po-web
+
+po-web
+```
+
+Configure the cockpit with the server URL and token through its documented pairing and discovery flow. The browser connects to the web surface, not to a private server credential. The server remains responsible for token validation at its listener.
+
+## Stop and recover
+
+`SIGINT` and `SIGTERM` dispose the headless host, close package facets, stop the direct runtime, close the listener, and release history ownership. A normal stop leaves the v4 session journal available for a later server.
+
+If startup fails while composing a scope or loading a required facet, no ready listener is published. Treat a failed composition, failed required facet, or history ownership conflict as a readiness failure, not as permission to use another module set.
+
+## Development
+
+Run from `packages/cli/po`:
+
+```bash
+pnpm build
+pnpm typecheck
+pnpm test
+pnpm lint
+```
+
+Read [Security](security.md) before sharing a listener or token. Read [Session APIs](api.md) when a package needs a session HTTP surface.

package/docs/server/index.md

@@ -0,0 +1,67 @@
+# Headless session server
+
+**The canonical client-neutral server for a Po session.**
+
+`po-server` embeds a `DirectHarnessRuntime` and its typed session services in one process. It does not launch a second Pi process or expose an internal filesystem transport. Clients use the authenticated HTTP surface and the `/api/ws` WebSocket endpoint. A command-line server owns one session; the exported hub and session manager can host more than one session in a process.
+
+The `@agimon-ai/po` core package owns this executable and the `@agimon-ai/po/server` API. It is a standalone process, not a Pi extension. Do not add it to `.po/modes.yaml`.
+
+## Install
+
+Requires Node.js 24 or newer and the packages your Po configuration names.
+
+```bash
+npm install -g @agimon-ai/po
+```
+
+Run `po sync` in the session repository to install the configured packages and the global web build. The server composes each scope live from configuration, so later configuration changes need no restart.
+
+## Quick start
+
+Create an owner-only token file, then pass harness arguments after `--`:
+
+```bash
+token_file="$(mktemp)"
+(umask 077; openssl rand -base64 32 > "$token_file")
+
+po-server \
+  --auth-token-file "$token_file" \
+  -- --major-mode copilot
+```
+
+The server listens on loopback port 7533 by default. Use `--web 9000` to select another port. The option name is retained for CLI compatibility, but the listener is the server's normal client-neutral HTTP and WebSocket surface, not an optional browser-only service.
+
+The token is read from the file, not the command line. Keep the file private. A direct client presents the token to the HTTP routes and `/api/ws`; Po Web can proxy the endpoint after applying its own browser and remote-access controls.
+
+## How it works
+
+Startup composes the global scope from configuration and imports the eligible server facets from their packages' built entries. It then creates the direct harness, session service, and package API handlers in process. The listener provides:
+
+- `/api/ws`, an authenticated WebSocket carrying the Pi 0.85 Chord protocol;
+- `/api/health`, an unauthenticated readiness check;
+- `/api/workspaces/<workspace-id>/sessions` and related routes for discovery and channel access; and
+- session package APIs below `/api/workspaces/<workspace-id>/sessions/<session-id>/plugins/<base-path>/...`.
+
+The Pi protocol exposes typed management, hub, and session services. Session calls operate directly on the same runtime that owns the session journal. No raw command bridge, child-process fallback, or separate package API transport sits between a client and the runtime.
+
+## Security
+
+The server binds to loopback by default and requires the token for every route except `/api/health`. A token file keeps the capability out of process listings. The server is not a sandbox: the harness, extensions, and server facets run with the account's authority.
+
+Po Web owns browser authentication, remote tunnels, device cookies, and passkeys. When it proxies a session, browser code does not need the server token. Do not publish the server listener without an authenticated boundary.
+
+Read [Security and trust boundaries](security.md) before sharing a listener or token.
+
+## Guides
+
+| Guide                                 | What it covers                                                    |
+| ------------------------------------- | ----------------------------------------------------------------- |
+| [Getting started](getting-started.md) | Installation, options, live composition, and web integration      |
+| [Lifecycle](lifecycle.md)             | In-process startup, readiness, shutdown, and history ownership    |
+| [IPC](ipc.md)                         | The `/api/ws` protocol, typed operations, HTTP routes, and replay |
+| [Session APIs](api.md)                | `poServer` facets, package handlers, and TypeScript exports       |
+| [Security](security.md)               | Tokens, listener exposure, trusted code, and data boundaries      |
+
+## License
+
+[MIT](../../LICENSE)