@agimon-ai/po-core 0.0.0-alpha.2 → 0.0.0-alpha.21

package/dist/src/schemas/serverPlugin.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"serverPlugin.cjs","names":[],"sources":["../../../src/schemas/serverPlugin.ts"],"sourcesContent":["import type { Context } from '@deepseek-ai/cordis';\n/**\n * The server plugin a package installs into a headless host.\n *\n * A package already ships a Pi extension for the agent process. This is its\n * server half: one cordis plugin that each server scope level (global,\n * workspace, session) installs into its own root, through which the package\n * contributes its HTTP surface and any behaviour that has to run outside the\n * agent.\n *\n * A plugin is installed and disposed like every other cordis plugin. It\n * registers its API through the level's host service from inside that\n * lifecycle, so server behaviour has a clear owner and disposer.\n */\nimport type { Static, TSchema } from 'typebox';\n\nimport type { RootDeclaration, RootFile } from './extensionFile';\nimport type { PoHeadlessHostService, PoHeadlessToolRestriction } from './headless';\nimport type { PoHeadlessTool, PoHeadlessCommand } from './headless';\nimport type { PoHubChannel } from './hubChannel';\nimport type { PoApi, PoApiContext, PoApiScope } from './packageApi';\nimport type { PoPluginTool, PoPluginCommand } from './pluginContributions';\nimport type { PoPluginCaller, PoPluginMethod } from './pluginProtocol';\nimport type { PoServerResources, PoServiceContract } from './serverScope';\nimport type { PoToolRestrictionDefinition } from './toolSurface';\n\n/** The host service each scope level publishes for the packages installed into it. */\nexport const PO_SERVER_HOST_SERVICE = 'po/server-host';\n\nexport interface PoServerRegistration {\n  /** Whether the API was mounted. A refused registration is a no-op handle. */\n  readonly mounted?: boolean;\n  /** Unmount the surface and close its handler. Idempotent. */\n  dispose(): void;\n}\n\n/**\n * What a package registers through at its level.\n *\n * `scope` is fixed for the life of the host: a session server never becomes a\n * hub. A package that only makes sense in one scope returns early in the other\n * rather than declaring itself twice.\n */\nexport interface PoServerHostService {\n  readonly scope: PoApiScope;\n  /** Identity and host-lent capabilities, the same record an API is started with. */\n  readonly context: PoApiContext;\n  /**\n   * Mount an API under its own base path. A base path already claimed by an\n   * earlier package is refused with a notice and a no-op handle. The same\n   * failure posture applies when the API cannot start or the host is disposed.\n   */\n  registerApi(api: PoApi): PoServerRegistration;\n  /** Register a live event source under this host's lifecycle. */\n  registerChannel(channel: PoHubChannel): PoServerRegistration;\n  /** Mount a typed call at this host's exact scope. */\n  registerMethod<TInput extends TSchema, TOutput extends TSchema>(\n    definition: PoPluginMethod<TInput, TOutput>,\n    handler: (input: Static<TInput>, caller: PoPluginCaller) => Static<TOutput> | Promise<Static<TOutput>>,\n  ): PoServerRegistration;\n  /** Base paths currently mounted, in mount order. */\n  mounted(): readonly string[];\n  /** Channel frame types currently mounted, in mount order. */\n  mountedChannels(): readonly string[];\n}\n\ndeclare module '@deepseek-ai/cordis' {\n  interface Context {\n    'po/server-host': PoServerHostService;\n  }\n}\n\nexport function readPoServerHost(context: Context): PoServerHostService | undefined {\n  return context.get(PO_SERVER_HOST_SERVICE) as PoServerHostService | undefined;\n}\n\nexport function requirePoServerHost(context: Context): PoServerHostService {\n  const service = readPoServerHost(context);\n  if (!service) throw new Error('The Po server host is unavailable. Start a Po server first.');\n  return service;\n}\n\n/** The package.json field a package declares its server plugin under. */\nexport const PO_SERVER_MANIFEST_FIELD = 'poServer';\n\nexport interface PoServerProviderOverride {\n  readonly name: string;\n  readonly baseUrl: string;\n}\nexport type PoServerProviderOverrides = (context: {\n  readonly environment: Readonly<Record<string, string | undefined>>;\n}) => readonly PoServerProviderOverride[];\n\n/** Read pure root metadata without initializing or mounting the root. */\nexport function composeServerProviderOverrides(...roots: readonly unknown[]): PoServerProviderOverrides {\n  return (context) =>\n    roots.flatMap((root) => {\n      if ((typeof root !== 'function' && typeof root !== 'object') || root === null) return [];\n      const callback = (root as { providerOverrides?: PoServerProviderOverrides }).providerOverrides;\n      return typeof callback === 'function' ? callback(context) : [];\n    });\n}\n\n/** Service contracts by the scope level that binds or waits for them. */\nexport type PoServerContracts = Readonly<Partial<Record<PoApiScope, readonly PoServiceContract<unknown>[]>>>;\n\n/**\n * One package's server contributions, as a cordis object plugin.\n *\n * The object form rather than a bare function, because it is the only shape\n * that declares its own `inject`. That matters to a scope: a plugin carrying\n * its dependencies is a single fiber, so `fiber.await()` settles once `apply`\n * has run, and the host can decide whether to open a listener from a mount\n * table it knows is complete.\n *\n * `providerOverrides`, `provides` and `injects` are pure metadata a host or the\n * build reads without running `apply`. A returned function is the disposer, run\n * when the plugin's fiber unwinds.\n */\nexport interface PoServerPlugin {\n  readonly name: string;\n  readonly providerOverrides?: PoServerProviderOverrides;\n  readonly inject?: readonly string[];\n  /** The contracts each level binds, which po-build lists as `poServer.provides`. */\n  readonly provides?: PoServerContracts;\n  /** The contracts each level waits for before it mounts, which po-build lists as `poServer.injects`. */\n  readonly injects?: PoServerContracts;\n  apply(context: Context): void | (() => void | Promise<void>) | Promise<void | (() => void | Promise<void>)>;\n}\n\n/** One instance belongs to one mounted server scope. */\nexport interface PoServerPluginContext {\n  readonly context: Context;\n  readonly host: PoServerHostService;\n  readonly agent?: PoHeadlessHostService;\n  readonly signal: AbortSignal;\n  /** Values this plugin build shares with every other level running it in the hub, released with this one. */\n  readonly resources: PoServerResources;\n  /**\n   * This package's root for `level`. At this scope's own level the root is built here and published\n   * for the levels inside it. At an outer level it is the root that level already built, without the\n   * hooks and services that run there once; when no outer level runs this package it is built here.\n   */\n  scopeRoot<TValue, TContext>(\n    level: PoApiScope,\n    root: RootFile<TValue, TContext>,\n    context: TContext,\n  ): Promise<RootDeclaration<TValue, TContext>>;\n  /**\n   * Whether a level from `level` out to this scope's parent already runs this package, so what this\n   * package declared at `level` is served there and is not mounted again here.\n   */\n  hosted(level: PoApiScope): boolean;\n}\n\nexport interface PoServerMethod {\n  register(host: PoServerHostService): PoServerRegistration;\n}\n\n/** Capture schema inference before heterogeneous methods enter a contribution array. */\nexport function defineServerMethod<TInput extends TSchema, TOutput extends TSchema>(\n  definition: PoPluginMethod<TInput, TOutput>,\n  handler: (input: Static<TInput>, caller: PoPluginCaller) => Static<TOutput> | Promise<Static<TOutput>>,\n): PoServerMethod {\n  return { register: (host) => host.registerMethod(definition, handler) };\n}\n\nexport interface PoServerPluginScope {\n  readonly services?: readonly Parameters<Context['plugin']>[0][];\n  readonly channels?: readonly (() => PoHubChannel)[];\n  readonly api?: readonly PoApi[];\n  readonly methods?: readonly PoServerMethod[];\n  readonly onStart?: (context: PoServerPluginContext) => void | Promise<void>;\n  readonly onStop?: (context: PoServerPluginContext) => void | Promise<void>;\n  readonly onDispose?: (context: PoServerPluginContext) => void | Promise<void>;\n}\n\nexport interface PoServerSessionPlugin extends PoServerPluginScope {\n  readonly tools?: readonly (PoHeadlessTool | PoPluginTool)[];\n  readonly commands?: readonly (PoHeadlessCommand | PoPluginCommand)[];\n  readonly resources?: readonly Parameters<PoHeadlessHostService['registerResource']>[0][];\n  readonly hooks?: readonly Parameters<PoHeadlessHostService['registerHook']>[0][];\n  readonly toolRestrictions?: readonly (\n    | PoHeadlessToolRestriction\n    | PoToolRestrictionDefinition<() => PoHeadlessToolRestriction>\n  )[];\n  readonly activities?: readonly Parameters<PoHeadlessHostService['registerActivity']>[0][];\n}\n\ntype ScopeDeclaration<TScope> = TScope | ((context: PoServerPluginContext) => TScope | Promise<TScope>);\n// Explicitly forbid session contributions even when a factory returns an inferred object.\ntype NonSessionScope = PoServerPluginScope & {\n  readonly [K in Exclude<keyof PoServerSessionPlugin, keyof PoServerPluginScope>]?: never;\n};\nexport interface PoServerPluginDefinition {\n  readonly providerOverrides?: PoServerProviderOverrides;\n  readonly name: string;\n  readonly inject?: readonly string[];\n  /** Each contract a level binds belongs to that level. */\n  readonly provides?: PoServerContracts;\n  /** Each contract a level waits for belongs to that level or an outer one. */\n  readonly injects?: PoServerContracts;\n  readonly global?: ScopeDeclaration<NonSessionScope>;\n  readonly workspace?: ScopeDeclaration<NonSessionScope>;\n  readonly session?: ScopeDeclaration<PoServerSessionPlugin>;\n}\n\n/** One package's validated declaration. */\nexport interface DeclaredServerPackage {\n  packageName: string;\n  packageDir: string;\n  /** Package-relative ./path to the source entry. */\n  entry: string;\n  /** Package-relative ./path to the built entry, which is what a host imports. */\n  dist: string;\n  /** Scopes this package is installed into. */\n  scopes: readonly PoApiScope[];\n  /** A selected host cannot be ready without this package's runtime capability. */\n  required?: boolean;\n}\n\nexport class PoServerManifestError extends Error {\n  constructor(packageDir: string, message: string) {\n    super(`${PO_SERVER_MANIFEST_FIELD} manifest in ${packageDir}: ${message}`);\n    this.name = 'PoServerManifestError';\n  }\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\nfunction normalizePath(packageDir: string, field: string, value: unknown): string {\n  if (typeof value !== 'string' || !value.startsWith('./') || value.includes('..')) {\n    throw new PoServerManifestError(packageDir, `${field} must be a package-relative ./path with no '..'.`);\n  }\n  return value;\n}\n\nfunction normalizeScopes(packageDir: string, value: unknown): readonly PoApiScope[] {\n  if (value === undefined) throw new PoServerManifestError(packageDir, 'scopes must be declared explicitly.');\n  if (!Array.isArray(value) || value.length === 0) {\n    throw new PoServerManifestError(packageDir, \"scopes must name 'global', 'workspace', or 'session'.\");\n  }\n  const scopes: PoApiScope[] = [];\n  for (const scope of value) {\n    if (scope !== 'session' && scope !== 'global' && scope !== 'workspace') {\n      throw new PoServerManifestError(packageDir, `Unknown scope '${String(scope)}'; resync for the three-level host.`);\n    }\n    if (!scopes.includes(scope)) scopes.push(scope);\n  }\n  return scopes;\n}\n\n/**\n * Validates one package.json's `poServer` block.\n *\n * `dist` is required because a host imports the built entry the package ships,\n * never its source.\n */\nexport function declaredServerPackagesOf(\n  packageDir: string,\n  manifest: Record<string, unknown>,\n): DeclaredServerPackage[] {\n  const declared = manifest[PO_SERVER_MANIFEST_FIELD];\n  if (declared === undefined) return [];\n  if (!isRecord(declared)) {\n    throw new PoServerManifestError(packageDir, 'the block must be an object naming entry and dist.');\n  }\n  const entry = normalizePath(packageDir, 'entry', declared.entry);\n  if (declared.dist === undefined) {\n    throw new PoServerManifestError(\n      packageDir,\n      'dist is required: a host imports the built entry the package ships, never its source.',\n    );\n  }\n  const dist = normalizePath(packageDir, 'dist', declared.dist);\n  if (declared.required !== undefined && typeof declared.required !== 'boolean') {\n    throw new PoServerManifestError(packageDir, 'required must be a boolean.');\n  }\n  return [\n    {\n      packageName: typeof manifest.name === 'string' ? manifest.name : packageDir,\n      packageDir,\n      entry,\n      dist,\n      scopes: normalizeScopes(packageDir, declared.scopes),\n      ...(typeof declared.required === 'boolean' ? { required: declared.required } : {}),\n    },\n  ];\n}\n\n/**\n * The deterministic order hosts install in. A package appears once: the first\n * directory claiming a package name keeps it and the later one is dropped with\n * a notice, so a duplicated install never installs a package twice.\n */\nexport function orderServerPackages(\n  packages: readonly DeclaredServerPackage[],\n  onNotice: (message: string) => void = () => undefined,\n): DeclaredServerPackage[] {\n  const sorted = [...packages].sort(\n    (left, right) =>\n      left.packageName.localeCompare(right.packageName) || left.packageDir.localeCompare(right.packageDir),\n  );\n  const owners = new Map<string, DeclaredServerPackage>();\n  const kept: DeclaredServerPackage[] = [];\n  for (const declared of sorted) {\n    const holder = owners.get(declared.packageName);\n    if (holder !== undefined) {\n      onNotice(\n        `server package '${declared.packageName}' from ${declared.packageDir} is skipped: ${holder.packageDir} already claims it.`,\n      );\n      continue;\n    }\n    owners.set(declared.packageName, declared);\n    kept.push(declared);\n  }\n  return kept;\n}\n"],"mappings":"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"}

package/dist/src/schemas/serverPlugin.d.mts

@@ -0,0 +1,176 @@
+import { PoHubChannel } from "./hubChannel.mjs";
+import { PoApi, PoApiContext, PoApiScope } from "./packageApi.mjs";
+import { PoHeadlessCommand, PoHeadlessHostService, PoHeadlessTool, PoHeadlessToolRestriction } from "./headless.mjs";
+import { PoPluginCommand, PoPluginTool } from "./pluginContributions.mjs";
+import { PoPluginCaller, PoPluginMethod } from "./pluginProtocol.mjs";
+import { PoServerResources, PoServiceContract } from "./serverScope.mjs";
+import { PoToolRestrictionDefinition } from "./toolSurface.mjs";
+import { RootDeclaration, RootFile } from "./extensionFile.mjs";
+import { Static, TSchema } from "typebox";
+import { Context } from "@deepseek-ai/cordis";
+//#region src/schemas/serverPlugin.d.ts
+/** The host service each scope level publishes for the packages installed into it. */
+export declare const PO_SERVER_HOST_SERVICE = "po/server-host";
+export interface PoServerRegistration {
+  /** Whether the API was mounted. A refused registration is a no-op handle. */
+  readonly mounted?: boolean;
+  /** Unmount the surface and close its handler. Idempotent. */
+  dispose(): void;
+}
+/**
+ * What a package registers through at its level.
+ *
+ * `scope` is fixed for the life of the host: a session server never becomes a
+ * hub. A package that only makes sense in one scope returns early in the other
+ * rather than declaring itself twice.
+ */
+export interface PoServerHostService {
+  readonly scope: PoApiScope;
+  /** Identity and host-lent capabilities, the same record an API is started with. */
+  readonly context: PoApiContext;
+  /**
+   * Mount an API under its own base path. A base path already claimed by an
+   * earlier package is refused with a notice and a no-op handle. The same
+   * failure posture applies when the API cannot start or the host is disposed.
+   */
+  registerApi(api: PoApi): PoServerRegistration;
+  /** Register a live event source under this host's lifecycle. */
+  registerChannel(channel: PoHubChannel): PoServerRegistration;
+  /** Mount a typed call at this host's exact scope. */
+  registerMethod<TInput extends TSchema, TOutput extends TSchema>(definition: PoPluginMethod<TInput, TOutput>, handler: (input: Static<TInput>, caller: PoPluginCaller) => Static<TOutput> | Promise<Static<TOutput>>): PoServerRegistration;
+  /** Base paths currently mounted, in mount order. */
+  mounted(): readonly string[];
+  /** Channel frame types currently mounted, in mount order. */
+  mountedChannels(): readonly string[];
+}
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    'po/server-host': PoServerHostService;
+  }
+}
+export declare function readPoServerHost(context: Context): PoServerHostService | undefined;
+export declare function requirePoServerHost(context: Context): PoServerHostService;
+/** The package.json field a package declares its server plugin under. */
+export declare const PO_SERVER_MANIFEST_FIELD = "poServer";
+export interface PoServerProviderOverride {
+  readonly name: string;
+  readonly baseUrl: string;
+}
+export type PoServerProviderOverrides = (context: {
+  readonly environment: Readonly<Record<string, string | undefined>>;
+}) => readonly PoServerProviderOverride[];
+/** Read pure root metadata without initializing or mounting the root. */
+export declare function composeServerProviderOverrides(...roots: readonly unknown[]): PoServerProviderOverrides;
+/** Service contracts by the scope level that binds or waits for them. */
+export type PoServerContracts = Readonly<Partial<Record<PoApiScope, readonly PoServiceContract<unknown>[]>>>;
+/**
+ * One package's server contributions, as a cordis object plugin.
+ *
+ * The object form rather than a bare function, because it is the only shape
+ * that declares its own `inject`. That matters to a scope: a plugin carrying
+ * its dependencies is a single fiber, so `fiber.await()` settles once `apply`
+ * has run, and the host can decide whether to open a listener from a mount
+ * table it knows is complete.
+ *
+ * `providerOverrides`, `provides` and `injects` are pure metadata a host or the
+ * build reads without running `apply`. A returned function is the disposer, run
+ * when the plugin's fiber unwinds.
+ */
+export interface PoServerPlugin {
+  readonly name: string;
+  readonly providerOverrides?: PoServerProviderOverrides;
+  readonly inject?: readonly string[];
+  /** The contracts each level binds, which po-build lists as `poServer.provides`. */
+  readonly provides?: PoServerContracts;
+  /** The contracts each level waits for before it mounts, which po-build lists as `poServer.injects`. */
+  readonly injects?: PoServerContracts;
+  apply(context: Context): void | (() => void | Promise<void>) | Promise<void | (() => void | Promise<void>)>;
+}
+/** One instance belongs to one mounted server scope. */
+export interface PoServerPluginContext {
+  readonly context: Context;
+  readonly host: PoServerHostService;
+  readonly agent?: PoHeadlessHostService;
+  readonly signal: AbortSignal;
+  /** Values this plugin build shares with every other level running it in the hub, released with this one. */
+  readonly resources: PoServerResources;
+  /**
+   * This package's root for `level`. At this scope's own level the root is built here and published
+   * for the levels inside it. At an outer level it is the root that level already built, without the
+   * hooks and services that run there once; when no outer level runs this package it is built here.
+   */
+  scopeRoot<TValue, TContext>(level: PoApiScope, root: RootFile<TValue, TContext>, context: TContext): Promise<RootDeclaration<TValue, TContext>>;
+  /**
+   * Whether a level from `level` out to this scope's parent already runs this package, so what this
+   * package declared at `level` is served there and is not mounted again here.
+   */
+  hosted(level: PoApiScope): boolean;
+}
+export interface PoServerMethod {
+  register(host: PoServerHostService): PoServerRegistration;
+}
+/** Capture schema inference before heterogeneous methods enter a contribution array. */
+export declare function defineServerMethod<TInput extends TSchema, TOutput extends TSchema>(definition: PoPluginMethod<TInput, TOutput>, handler: (input: Static<TInput>, caller: PoPluginCaller) => Static<TOutput> | Promise<Static<TOutput>>): PoServerMethod;
+export interface PoServerPluginScope {
+  readonly services?: readonly Parameters<Context['plugin']>[0][];
+  readonly channels?: readonly (() => PoHubChannel)[];
+  readonly api?: readonly PoApi[];
+  readonly methods?: readonly PoServerMethod[];
+  readonly onStart?: (context: PoServerPluginContext) => void | Promise<void>;
+  readonly onStop?: (context: PoServerPluginContext) => void | Promise<void>;
+  readonly onDispose?: (context: PoServerPluginContext) => void | Promise<void>;
+}
+export interface PoServerSessionPlugin extends PoServerPluginScope {
+  readonly tools?: readonly (PoHeadlessTool | PoPluginTool)[];
+  readonly commands?: readonly (PoHeadlessCommand | PoPluginCommand)[];
+  readonly resources?: readonly Parameters<PoHeadlessHostService['registerResource']>[0][];
+  readonly hooks?: readonly Parameters<PoHeadlessHostService['registerHook']>[0][];
+  readonly toolRestrictions?: readonly (PoHeadlessToolRestriction | PoToolRestrictionDefinition<() => PoHeadlessToolRestriction>)[];
+  readonly activities?: readonly Parameters<PoHeadlessHostService['registerActivity']>[0][];
+}
+type ScopeDeclaration<TScope> = TScope | ((context: PoServerPluginContext) => TScope | Promise<TScope>);
+type NonSessionScope = PoServerPluginScope & { readonly [K in Exclude<keyof PoServerSessionPlugin, keyof PoServerPluginScope>]?: never; };
+export interface PoServerPluginDefinition {
+  readonly providerOverrides?: PoServerProviderOverrides;
+  readonly name: string;
+  readonly inject?: readonly string[];
+  /** Each contract a level binds belongs to that level. */
+  readonly provides?: PoServerContracts;
+  /** Each contract a level waits for belongs to that level or an outer one. */
+  readonly injects?: PoServerContracts;
+  readonly global?: ScopeDeclaration<NonSessionScope>;
+  readonly workspace?: ScopeDeclaration<NonSessionScope>;
+  readonly session?: ScopeDeclaration<PoServerSessionPlugin>;
+}
+/** One package's validated declaration. */
+export interface DeclaredServerPackage {
+  packageName: string;
+  packageDir: string;
+  /** Package-relative ./path to the source entry. */
+  entry: string;
+  /** Package-relative ./path to the built entry, which is what a host imports. */
+  dist: string;
+  /** Scopes this package is installed into. */
+  scopes: readonly PoApiScope[];
+  /** A selected host cannot be ready without this package's runtime capability. */
+  required?: boolean;
+}
+export declare class PoServerManifestError extends Error {
+  constructor(packageDir: string, message: string);
+}
+/**
+ * Validates one package.json's `poServer` block.
+ *
+ * `dist` is required because a host imports the built entry the package ships,
+ * never its source.
+ */
+export declare function declaredServerPackagesOf(packageDir: string, manifest: Record<string, unknown>): DeclaredServerPackage[];
+/**
+ * The deterministic order hosts install in. A package appears once: the first
+ * directory claiming a package name keeps it and the later one is dropped with
+ * a notice, so a duplicated install never installs a package twice.
+ */
+export declare function orderServerPackages(packages: readonly DeclaredServerPackage[], onNotice?: (message: string) => void): DeclaredServerPackage[];
+//#endregion
+export {};
+//# sourceMappingURL=serverPlugin.d.mts.map

package/dist/src/schemas/serverPlugin.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serverPlugin.d.mts","names":[],"sources":["../../../src/schemas/serverPlugin.ts"],"mappings":";;;;;;;;;;;;qBA2Ba;iBAEI;;WAEN;;EAET;;;;;;;;;iBAUe;WACN,OAAO;;WAEP,SAAS;;;;;;EAMlB,YAAY,KAAK,QAAQ;;EAEzB,gBAAgB,SAAS,eAAe;;EAExC,eAAe,eAAe,SAAS,gBAAgB,SACrD,YAAY,eAAe,QAAQ,UACnC,UAAU,OAAO,OAAO,SAAS,QAAQ,mBAAmB,OAAO,WAAW,QAAQ,OAAO,YAC5F;;EAEH;;EAEA;;;YAIU;IACR,kBAAkB;;;wBAIN,iBAAiB,SAAS,UAAU;wBAIpC,oBAAoB,SAAS,UAAU;;qBAO1C;iBAEI;WACN;WACA;;YAEC,6BAA6B;WAC9B,aAAa,SAAS;eAClB;;wBAGC,kCAAkC,4BAA4B;;YAUlE,oBAAoB,SAAS,QAAQ,OAAO,qBAAqB;;;;;;;;;;;;;;iBAe5D;WACN;WACA,oBAAoB;WACpB;;WAEA,WAAW;;WAEX,UAAU;EACnB,MAAM,SAAS,+BAA+B,iBAAiB,6BAA6B;;;iBAI7E;WACN,SAAS;WACT,MAAM;WACN,QAAQ;WACR,QAAQ;;WAER,WAAW;;;;;;EAMpB,UAAU,QAAQ,UAChB,OAAO,YACP,MAAM,SAAS,QAAQ,WACvB,SAAS,WACR,QAAQ,gBAAgB,QAAQ;;;;;EAKnC,OAAO,OAAO;;iBAGC;EACf,SAAS,MAAM,sBAAsB;;;wBAIvB,mBAAmB,eAAe,SAAS,gBAAgB,SACzE,YAAY,eAAe,QAAQ,UACnC,UAAU,OAAO,OAAO,SAAS,QAAQ,mBAAmB,OAAO,WAAW,QAAQ,OAAO,YAC5F;iBAIc;WACN,oBAAoB,WAAW;WAC/B,2BAA2B;WAC3B,eAAe;WACf,mBAAmB;WACnB,WAAW,SAAS,iCAAiC;WACrD,UAAU,SAAS,iCAAiC;WACpD,aAAa,SAAS,iCAAiC;;iBAGjD,8BAA8B;WACpC,kBAAkB,iBAAiB;WACnC,qBAAqB,oBAAoB;WACzC,qBAAqB,WAAW;WAChC,iBAAiB,WAAW;WAC5B,6BACL,4BACA,kCAAkC;WAE7B,sBAAsB,WAAW;;KAGvC,iBAAiB,UAAU,WAAW,SAAS,0BAA0B,SAAS,QAAQ;KAE1F,kBAAkB,kCACX,KAAK,cAAc,6BAA6B;iBAE3C;WACN,oBAAoB;WACpB;WACA;;WAEA,WAAW;;WAEX,UAAU;WACV,SAAS,iBAAiB;WAC1B,YAAY,iBAAiB;WAC7B,UAAU,iBAAiB;;;iBAIrB;EACf;EACA;;EAEA;;EAEA;;EAEA,iBAAiB;;EAEjB;;qBAGW,8BAA8B;EACzC,YAAY,oBAAoB;;;;;;;;wBAsClB,yBACd,oBACA,UAAU,0BACT;;;;;;wBAkCa,oBACd,mBAAmB,yBACnB,YAAW,2BACV"}

package/dist/src/schemas/serverPlugin.mjs

@@ -0,0 +1,95 @@
+//#region src/schemas/serverPlugin.ts
+/** The host service each scope level publishes for the packages installed into it. */
+const PO_SERVER_HOST_SERVICE = "po/server-host";
+function readPoServerHost(context) {
+	return context.get(PO_SERVER_HOST_SERVICE);
+}
+function requirePoServerHost(context) {
+	const service = readPoServerHost(context);
+	if (!service) throw new Error("The Po server host is unavailable. Start a Po server first.");
+	return service;
+}
+/** The package.json field a package declares its server plugin under. */
+const PO_SERVER_MANIFEST_FIELD = "poServer";
+/** Read pure root metadata without initializing or mounting the root. */
+function composeServerProviderOverrides(...roots) {
+	return (context) => roots.flatMap((root) => {
+		if (typeof root !== "function" && typeof root !== "object" || root === null) return [];
+		const callback = root.providerOverrides;
+		return typeof callback === "function" ? callback(context) : [];
+	});
+}
+/** Capture schema inference before heterogeneous methods enter a contribution array. */
+function defineServerMethod(definition, handler) {
+	return { register: (host) => host.registerMethod(definition, handler) };
+}
+var PoServerManifestError = class extends Error {
+	constructor(packageDir, message) {
+		super(`${PO_SERVER_MANIFEST_FIELD} manifest in ${packageDir}: ${message}`);
+		this.name = "PoServerManifestError";
+	}
+};
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizePath(packageDir, field, value) {
+	if (typeof value !== "string" || !value.startsWith("./") || value.includes("..")) throw new PoServerManifestError(packageDir, `${field} must be a package-relative ./path with no '..'.`);
+	return value;
+}
+function normalizeScopes(packageDir, value) {
+	if (value === void 0) throw new PoServerManifestError(packageDir, "scopes must be declared explicitly.");
+	if (!Array.isArray(value) || value.length === 0) throw new PoServerManifestError(packageDir, "scopes must name 'global', 'workspace', or 'session'.");
+	const scopes = [];
+	for (const scope of value) {
+		if (scope !== "session" && scope !== "global" && scope !== "workspace") throw new PoServerManifestError(packageDir, `Unknown scope '${String(scope)}'; resync for the three-level host.`);
+		if (!scopes.includes(scope)) scopes.push(scope);
+	}
+	return scopes;
+}
+/**
+* Validates one package.json's `poServer` block.
+*
+* `dist` is required because a host imports the built entry the package ships,
+* never its source.
+*/
+function declaredServerPackagesOf(packageDir, manifest) {
+	const declared = manifest[PO_SERVER_MANIFEST_FIELD];
+	if (declared === void 0) return [];
+	if (!isRecord(declared)) throw new PoServerManifestError(packageDir, "the block must be an object naming entry and dist.");
+	const entry = normalizePath(packageDir, "entry", declared.entry);
+	if (declared.dist === void 0) throw new PoServerManifestError(packageDir, "dist is required: a host imports the built entry the package ships, never its source.");
+	const dist = normalizePath(packageDir, "dist", declared.dist);
+	if (declared.required !== void 0 && typeof declared.required !== "boolean") throw new PoServerManifestError(packageDir, "required must be a boolean.");
+	return [{
+		packageName: typeof manifest.name === "string" ? manifest.name : packageDir,
+		packageDir,
+		entry,
+		dist,
+		scopes: normalizeScopes(packageDir, declared.scopes),
+		...typeof declared.required === "boolean" ? { required: declared.required } : {}
+	}];
+}
+/**
+* The deterministic order hosts install in. A package appears once: the first
+* directory claiming a package name keeps it and the later one is dropped with
+* a notice, so a duplicated install never installs a package twice.
+*/
+function orderServerPackages(packages, onNotice = () => void 0) {
+	const sorted = [...packages].sort((left, right) => left.packageName.localeCompare(right.packageName) || left.packageDir.localeCompare(right.packageDir));
+	const owners = /* @__PURE__ */ new Map();
+	const kept = [];
+	for (const declared of sorted) {
+		const holder = owners.get(declared.packageName);
+		if (holder !== void 0) {
+			onNotice(`server package '${declared.packageName}' from ${declared.packageDir} is skipped: ${holder.packageDir} already claims it.`);
+			continue;
+		}
+		owners.set(declared.packageName, declared);
+		kept.push(declared);
+	}
+	return kept;
+}
+//#endregion
+export { PO_SERVER_HOST_SERVICE, PO_SERVER_MANIFEST_FIELD, PoServerManifestError, composeServerProviderOverrides, declaredServerPackagesOf, defineServerMethod, orderServerPackages, readPoServerHost, requirePoServerHost };
+
+//# sourceMappingURL=serverPlugin.mjs.map

package/dist/src/schemas/serverPlugin.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"serverPlugin.mjs","names":[],"sources":["../../../src/schemas/serverPlugin.ts"],"sourcesContent":["import type { Context } from '@deepseek-ai/cordis';\n/**\n * The server plugin a package installs into a headless host.\n *\n * A package already ships a Pi extension for the agent process. This is its\n * server half: one cordis plugin that each server scope level (global,\n * workspace, session) installs into its own root, through which the package\n * contributes its HTTP surface and any behaviour that has to run outside the\n * agent.\n *\n * A plugin is installed and disposed like every other cordis plugin. It\n * registers its API through the level's host service from inside that\n * lifecycle, so server behaviour has a clear owner and disposer.\n */\nimport type { Static, TSchema } from 'typebox';\n\nimport type { RootDeclaration, RootFile } from './extensionFile';\nimport type { PoHeadlessHostService, PoHeadlessToolRestriction } from './headless';\nimport type { PoHeadlessTool, PoHeadlessCommand } from './headless';\nimport type { PoHubChannel } from './hubChannel';\nimport type { PoApi, PoApiContext, PoApiScope } from './packageApi';\nimport type { PoPluginTool, PoPluginCommand } from './pluginContributions';\nimport type { PoPluginCaller, PoPluginMethod } from './pluginProtocol';\nimport type { PoServerResources, PoServiceContract } from './serverScope';\nimport type { PoToolRestrictionDefinition } from './toolSurface';\n\n/** The host service each scope level publishes for the packages installed into it. */\nexport const PO_SERVER_HOST_SERVICE = 'po/server-host';\n\nexport interface PoServerRegistration {\n  /** Whether the API was mounted. A refused registration is a no-op handle. */\n  readonly mounted?: boolean;\n  /** Unmount the surface and close its handler. Idempotent. */\n  dispose(): void;\n}\n\n/**\n * What a package registers through at its level.\n *\n * `scope` is fixed for the life of the host: a session server never becomes a\n * hub. A package that only makes sense in one scope returns early in the other\n * rather than declaring itself twice.\n */\nexport interface PoServerHostService {\n  readonly scope: PoApiScope;\n  /** Identity and host-lent capabilities, the same record an API is started with. */\n  readonly context: PoApiContext;\n  /**\n   * Mount an API under its own base path. A base path already claimed by an\n   * earlier package is refused with a notice and a no-op handle. The same\n   * failure posture applies when the API cannot start or the host is disposed.\n   */\n  registerApi(api: PoApi): PoServerRegistration;\n  /** Register a live event source under this host's lifecycle. */\n  registerChannel(channel: PoHubChannel): PoServerRegistration;\n  /** Mount a typed call at this host's exact scope. */\n  registerMethod<TInput extends TSchema, TOutput extends TSchema>(\n    definition: PoPluginMethod<TInput, TOutput>,\n    handler: (input: Static<TInput>, caller: PoPluginCaller) => Static<TOutput> | Promise<Static<TOutput>>,\n  ): PoServerRegistration;\n  /** Base paths currently mounted, in mount order. */\n  mounted(): readonly string[];\n  /** Channel frame types currently mounted, in mount order. */\n  mountedChannels(): readonly string[];\n}\n\ndeclare module '@deepseek-ai/cordis' {\n  interface Context {\n    'po/server-host': PoServerHostService;\n  }\n}\n\nexport function readPoServerHost(context: Context): PoServerHostService | undefined {\n  return context.get(PO_SERVER_HOST_SERVICE) as PoServerHostService | undefined;\n}\n\nexport function requirePoServerHost(context: Context): PoServerHostService {\n  const service = readPoServerHost(context);\n  if (!service) throw new Error('The Po server host is unavailable. Start a Po server first.');\n  return service;\n}\n\n/** The package.json field a package declares its server plugin under. */\nexport const PO_SERVER_MANIFEST_FIELD = 'poServer';\n\nexport interface PoServerProviderOverride {\n  readonly name: string;\n  readonly baseUrl: string;\n}\nexport type PoServerProviderOverrides = (context: {\n  readonly environment: Readonly<Record<string, string | undefined>>;\n}) => readonly PoServerProviderOverride[];\n\n/** Read pure root metadata without initializing or mounting the root. */\nexport function composeServerProviderOverrides(...roots: readonly unknown[]): PoServerProviderOverrides {\n  return (context) =>\n    roots.flatMap((root) => {\n      if ((typeof root !== 'function' && typeof root !== 'object') || root === null) return [];\n      const callback = (root as { providerOverrides?: PoServerProviderOverrides }).providerOverrides;\n      return typeof callback === 'function' ? callback(context) : [];\n    });\n}\n\n/** Service contracts by the scope level that binds or waits for them. */\nexport type PoServerContracts = Readonly<Partial<Record<PoApiScope, readonly PoServiceContract<unknown>[]>>>;\n\n/**\n * One package's server contributions, as a cordis object plugin.\n *\n * The object form rather than a bare function, because it is the only shape\n * that declares its own `inject`. That matters to a scope: a plugin carrying\n * its dependencies is a single fiber, so `fiber.await()` settles once `apply`\n * has run, and the host can decide whether to open a listener from a mount\n * table it knows is complete.\n *\n * `providerOverrides`, `provides` and `injects` are pure metadata a host or the\n * build reads without running `apply`. A returned function is the disposer, run\n * when the plugin's fiber unwinds.\n */\nexport interface PoServerPlugin {\n  readonly name: string;\n  readonly providerOverrides?: PoServerProviderOverrides;\n  readonly inject?: readonly string[];\n  /** The contracts each level binds, which po-build lists as `poServer.provides`. */\n  readonly provides?: PoServerContracts;\n  /** The contracts each level waits for before it mounts, which po-build lists as `poServer.injects`. */\n  readonly injects?: PoServerContracts;\n  apply(context: Context): void | (() => void | Promise<void>) | Promise<void | (() => void | Promise<void>)>;\n}\n\n/** One instance belongs to one mounted server scope. */\nexport interface PoServerPluginContext {\n  readonly context: Context;\n  readonly host: PoServerHostService;\n  readonly agent?: PoHeadlessHostService;\n  readonly signal: AbortSignal;\n  /** Values this plugin build shares with every other level running it in the hub, released with this one. */\n  readonly resources: PoServerResources;\n  /**\n   * This package's root for `level`. At this scope's own level the root is built here and published\n   * for the levels inside it. At an outer level it is the root that level already built, without the\n   * hooks and services that run there once; when no outer level runs this package it is built here.\n   */\n  scopeRoot<TValue, TContext>(\n    level: PoApiScope,\n    root: RootFile<TValue, TContext>,\n    context: TContext,\n  ): Promise<RootDeclaration<TValue, TContext>>;\n  /**\n   * Whether a level from `level` out to this scope's parent already runs this package, so what this\n   * package declared at `level` is served there and is not mounted again here.\n   */\n  hosted(level: PoApiScope): boolean;\n}\n\nexport interface PoServerMethod {\n  register(host: PoServerHostService): PoServerRegistration;\n}\n\n/** Capture schema inference before heterogeneous methods enter a contribution array. */\nexport function defineServerMethod<TInput extends TSchema, TOutput extends TSchema>(\n  definition: PoPluginMethod<TInput, TOutput>,\n  handler: (input: Static<TInput>, caller: PoPluginCaller) => Static<TOutput> | Promise<Static<TOutput>>,\n): PoServerMethod {\n  return { register: (host) => host.registerMethod(definition, handler) };\n}\n\nexport interface PoServerPluginScope {\n  readonly services?: readonly Parameters<Context['plugin']>[0][];\n  readonly channels?: readonly (() => PoHubChannel)[];\n  readonly api?: readonly PoApi[];\n  readonly methods?: readonly PoServerMethod[];\n  readonly onStart?: (context: PoServerPluginContext) => void | Promise<void>;\n  readonly onStop?: (context: PoServerPluginContext) => void | Promise<void>;\n  readonly onDispose?: (context: PoServerPluginContext) => void | Promise<void>;\n}\n\nexport interface PoServerSessionPlugin extends PoServerPluginScope {\n  readonly tools?: readonly (PoHeadlessTool | PoPluginTool)[];\n  readonly commands?: readonly (PoHeadlessCommand | PoPluginCommand)[];\n  readonly resources?: readonly Parameters<PoHeadlessHostService['registerResource']>[0][];\n  readonly hooks?: readonly Parameters<PoHeadlessHostService['registerHook']>[0][];\n  readonly toolRestrictions?: readonly (\n    | PoHeadlessToolRestriction\n    | PoToolRestrictionDefinition<() => PoHeadlessToolRestriction>\n  )[];\n  readonly activities?: readonly Parameters<PoHeadlessHostService['registerActivity']>[0][];\n}\n\ntype ScopeDeclaration<TScope> = TScope | ((context: PoServerPluginContext) => TScope | Promise<TScope>);\n// Explicitly forbid session contributions even when a factory returns an inferred object.\ntype NonSessionScope = PoServerPluginScope & {\n  readonly [K in Exclude<keyof PoServerSessionPlugin, keyof PoServerPluginScope>]?: never;\n};\nexport interface PoServerPluginDefinition {\n  readonly providerOverrides?: PoServerProviderOverrides;\n  readonly name: string;\n  readonly inject?: readonly string[];\n  /** Each contract a level binds belongs to that level. */\n  readonly provides?: PoServerContracts;\n  /** Each contract a level waits for belongs to that level or an outer one. */\n  readonly injects?: PoServerContracts;\n  readonly global?: ScopeDeclaration<NonSessionScope>;\n  readonly workspace?: ScopeDeclaration<NonSessionScope>;\n  readonly session?: ScopeDeclaration<PoServerSessionPlugin>;\n}\n\n/** One package's validated declaration. */\nexport interface DeclaredServerPackage {\n  packageName: string;\n  packageDir: string;\n  /** Package-relative ./path to the source entry. */\n  entry: string;\n  /** Package-relative ./path to the built entry, which is what a host imports. */\n  dist: string;\n  /** Scopes this package is installed into. */\n  scopes: readonly PoApiScope[];\n  /** A selected host cannot be ready without this package's runtime capability. */\n  required?: boolean;\n}\n\nexport class PoServerManifestError extends Error {\n  constructor(packageDir: string, message: string) {\n    super(`${PO_SERVER_MANIFEST_FIELD} manifest in ${packageDir}: ${message}`);\n    this.name = 'PoServerManifestError';\n  }\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\nfunction normalizePath(packageDir: string, field: string, value: unknown): string {\n  if (typeof value !== 'string' || !value.startsWith('./') || value.includes('..')) {\n    throw new PoServerManifestError(packageDir, `${field} must be a package-relative ./path with no '..'.`);\n  }\n  return value;\n}\n\nfunction normalizeScopes(packageDir: string, value: unknown): readonly PoApiScope[] {\n  if (value === undefined) throw new PoServerManifestError(packageDir, 'scopes must be declared explicitly.');\n  if (!Array.isArray(value) || value.length === 0) {\n    throw new PoServerManifestError(packageDir, \"scopes must name 'global', 'workspace', or 'session'.\");\n  }\n  const scopes: PoApiScope[] = [];\n  for (const scope of value) {\n    if (scope !== 'session' && scope !== 'global' && scope !== 'workspace') {\n      throw new PoServerManifestError(packageDir, `Unknown scope '${String(scope)}'; resync for the three-level host.`);\n    }\n    if (!scopes.includes(scope)) scopes.push(scope);\n  }\n  return scopes;\n}\n\n/**\n * Validates one package.json's `poServer` block.\n *\n * `dist` is required because a host imports the built entry the package ships,\n * never its source.\n */\nexport function declaredServerPackagesOf(\n  packageDir: string,\n  manifest: Record<string, unknown>,\n): DeclaredServerPackage[] {\n  const declared = manifest[PO_SERVER_MANIFEST_FIELD];\n  if (declared === undefined) return [];\n  if (!isRecord(declared)) {\n    throw new PoServerManifestError(packageDir, 'the block must be an object naming entry and dist.');\n  }\n  const entry = normalizePath(packageDir, 'entry', declared.entry);\n  if (declared.dist === undefined) {\n    throw new PoServerManifestError(\n      packageDir,\n      'dist is required: a host imports the built entry the package ships, never its source.',\n    );\n  }\n  const dist = normalizePath(packageDir, 'dist', declared.dist);\n  if (declared.required !== undefined && typeof declared.required !== 'boolean') {\n    throw new PoServerManifestError(packageDir, 'required must be a boolean.');\n  }\n  return [\n    {\n      packageName: typeof manifest.name === 'string' ? manifest.name : packageDir,\n      packageDir,\n      entry,\n      dist,\n      scopes: normalizeScopes(packageDir, declared.scopes),\n      ...(typeof declared.required === 'boolean' ? { required: declared.required } : {}),\n    },\n  ];\n}\n\n/**\n * The deterministic order hosts install in. A package appears once: the first\n * directory claiming a package name keeps it and the later one is dropped with\n * a notice, so a duplicated install never installs a package twice.\n */\nexport function orderServerPackages(\n  packages: readonly DeclaredServerPackage[],\n  onNotice: (message: string) => void = () => undefined,\n): DeclaredServerPackage[] {\n  const sorted = [...packages].sort(\n    (left, right) =>\n      left.packageName.localeCompare(right.packageName) || left.packageDir.localeCompare(right.packageDir),\n  );\n  const owners = new Map<string, DeclaredServerPackage>();\n  const kept: DeclaredServerPackage[] = [];\n  for (const declared of sorted) {\n    const holder = owners.get(declared.packageName);\n    if (holder !== undefined) {\n      onNotice(\n        `server package '${declared.packageName}' from ${declared.packageDir} is skipped: ${holder.packageDir} already claims it.`,\n      );\n      continue;\n    }\n    owners.set(declared.packageName, declared);\n    kept.push(declared);\n  }\n  return kept;\n}\n"],"mappings":"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"}

package/dist/src/schemas/serverScope.cjs

@@ -0,0 +1,37 @@
+//#region src/schemas/serverScope.ts
+/**
+* The server inversion-of-control tree: global, then one scope per workspace, then one per session.
+*
+* Each level has its own cordis root. A contract names an abstract service and the one level whose
+* plugin binds the concrete value; every descendant level sees that value as a native cordis service,
+* so `inject` and `ctx.get` work unchanged. A level never sees a contract bound below it.
+*/
+const PO_SERVER_SCOPE_SERVICE = "po/server-scope";
+/** Outermost first, so a lower index is an ancestor level. */
+const PO_SERVER_SCOPE_LEVELS = [
+	"global",
+	"workspace",
+	"session"
+];
+function defineServiceContract(name, options) {
+	return {
+		name,
+		scope: options.scope
+	};
+}
+function readPoServerScope(context) {
+	return context.get(PO_SERVER_SCOPE_SERVICE);
+}
+function requirePoServerScope(context) {
+	const service = readPoServerScope(context);
+	if (!service) throw new Error("The Po server scope is unavailable. Install packages through a Po server scope.");
+	return service;
+}
+//#endregion
+exports.PO_SERVER_SCOPE_LEVELS = PO_SERVER_SCOPE_LEVELS;
+exports.PO_SERVER_SCOPE_SERVICE = PO_SERVER_SCOPE_SERVICE;
+exports.defineServiceContract = defineServiceContract;
+exports.readPoServerScope = readPoServerScope;
+exports.requirePoServerScope = requirePoServerScope;
+
+//# sourceMappingURL=serverScope.cjs.map

package/dist/src/schemas/serverScope.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"serverScope.cjs","names":[],"sources":["../../../src/schemas/serverScope.ts"],"sourcesContent":["import type { Context, Events } from '@deepseek-ai/cordis';\n\nimport type { PoApiScope } from './packageApi';\n\n/**\n * The server inversion-of-control tree: global, then one scope per workspace, then one per session.\n *\n * Each level has its own cordis root. A contract names an abstract service and the one level whose\n * plugin binds the concrete value; every descendant level sees that value as a native cordis service,\n * so `inject` and `ctx.get` work unchanged. A level never sees a contract bound below it.\n */\nexport const PO_SERVER_SCOPE_SERVICE = 'po/server-scope';\n\n/** Outermost first, so a lower index is an ancestor level. */\nexport const PO_SERVER_SCOPE_LEVELS: readonly PoApiScope[] = ['global', 'workspace', 'session'];\n\n/** An abstract service: the name every level resolves and the level that provides it. */\nexport interface PoServiceContract<T> {\n  readonly name: string;\n  readonly scope: PoApiScope;\n  /** Type carrier only; never set at runtime. */\n  readonly _type?: T;\n}\n\nexport function defineServiceContract<T>(name: string, options: { readonly scope: PoApiScope }): PoServiceContract<T> {\n  return { name, scope: options.scope };\n}\n\n/** Names one shared value. Array parts stay distinct, so `['a', 1]` and `'a,1'` are different keys. */\nexport type PoServerResourceKey = string | readonly (string | number | boolean | null)[];\n\n/**\n * Values one plugin build shares across every level it runs at in one hub.\n *\n * The first level to acquire a key creates its value; each acquiring level releases it when that\n * level unwinds, and the last release disposes it with the `dispose` the creating call passed. The\n * store belongs to the hub, never to a module, so two hubs in one process share nothing. A new build of\n * the plugin has its own store, so a session running the old build keeps what it acquired until it\n * closes.\n */\nexport interface PoServerResources {\n  acquire<T>(\n    key: PoServerResourceKey,\n    create: () => T | Promise<T>,\n    dispose?: (value: T) => void | Promise<void>,\n  ): Promise<T>;\n}\n\n/** One held share of a value; releasing it twice is a no-op. */\nexport interface PoServerResourceLease<T> {\n  readonly value: T;\n  release(): Promise<void>;\n}\n\n/** What one plugin build shares in this hub, seen from one scope. `defineServerPlugin` is its caller. */\nexport interface PoServerPluginShare<TRoots> {\n  acquire<T>(\n    key: PoServerResourceKey,\n    create: () => T | Promise<T>,\n    dispose?: (value: T) => void | Promise<void>,\n  ): Promise<PoServerResourceLease<T>>;\n  /** Marks this scope as running the plugin and holding `roots` for the scopes inside it, until withdrawn. */\n  run(roots: TRoots): () => void;\n  /** What every scope running the plugin, from the `from` level out to this scope's parent, holds; innermost first. */\n  outer(from: PoApiScope): readonly TRoots[];\n}\n\n/** What a plugin sees of the scope it is installed into. */\nexport interface PoServerScopeService {\n  readonly level: PoApiScope;\n  /**\n   * Bind the concrete value of a contract owned by this level, visible here and in every descendant.\n   * Settles once every descendant publishes it. The binding unwinds with the calling fiber; the\n   * resolved disposer withdraws it earlier.\n   */\n  provide<T>(contract: PoServiceContract<T>, value: T): Promise<() => Promise<void>>;\n  /** The value bound at the contract's level on this scope's ancestor path, if any. */\n  resolve<T>(contract: PoServiceContract<T>): T | undefined;\n  /** Deliver a cordis event to this scope's root and every ancestor root. */\n  emit<K extends keyof Events>(name: K, ...args: Parameters<Events[K]>): void;\n  /** Deliver a cordis event to this scope's root and every descendant root; siblings never see it. */\n  broadcast<K extends keyof Events>(name: K, ...args: Parameters<Events[K]>): void;\n  /** What the plugin build `owner` shares in this hub. One store per build, kept by the outermost scope. */\n  plugin<TRoots>(owner: object): PoServerPluginShare<TRoots>;\n}\n\ndeclare module '@deepseek-ai/cordis' {\n  interface Context {\n    'po/server-scope': PoServerScopeService;\n  }\n}\n\nexport function readPoServerScope(context: Context): PoServerScopeService | undefined {\n  return context.get(PO_SERVER_SCOPE_SERVICE) as PoServerScopeService | undefined;\n}\n\nexport function requirePoServerScope(context: Context): PoServerScopeService {\n  const service = readPoServerScope(context);\n  if (!service) throw new Error('The Po server scope is unavailable. Install packages through a Po server scope.');\n  return service;\n}\n"],"mappings":";;;;;;;;AAWA,MAAa,0BAA0B;;AAGvC,MAAa,yBAAgD;CAAC;CAAU;CAAa;AAAS;AAU9F,SAAgB,sBAAyB,MAAc,SAA+D;CACpH,OAAO;EAAE;EAAM,OAAO,QAAQ;CAAM;AACtC;AAkEA,SAAgB,kBAAkB,SAAoD;CACpF,OAAO,QAAQ,IAAI,uBAAuB;AAC5C;AAEA,SAAgB,qBAAqB,SAAwC;CAC3E,MAAM,UAAU,kBAAkB,OAAO;CACzC,IAAI,CAAC,SAAS,MAAM,IAAI,MAAM,iFAAiF;CAC/G,OAAO;AACT"}

package/dist/src/schemas/serverScope.d.mts

@@ -0,0 +1,77 @@
+import { PoApiScope } from "./packageApi.mjs";
+import { Context, Events } from "@deepseek-ai/cordis";
+//#region src/schemas/serverScope.d.ts
+/**
+ * The server inversion-of-control tree: global, then one scope per workspace, then one per session.
+ *
+ * Each level has its own cordis root. A contract names an abstract service and the one level whose
+ * plugin binds the concrete value; every descendant level sees that value as a native cordis service,
+ * so `inject` and `ctx.get` work unchanged. A level never sees a contract bound below it.
+ */
+export declare const PO_SERVER_SCOPE_SERVICE = "po/server-scope";
+/** Outermost first, so a lower index is an ancestor level. */
+export declare const PO_SERVER_SCOPE_LEVELS: readonly PoApiScope[];
+/** An abstract service: the name every level resolves and the level that provides it. */
+export interface PoServiceContract<T> {
+  readonly name: string;
+  readonly scope: PoApiScope;
+  /** Type carrier only; never set at runtime. */
+  readonly _type?: T;
+}
+export declare function defineServiceContract<T>(name: string, options: {
+  readonly scope: PoApiScope;
+}): PoServiceContract<T>;
+/** Names one shared value. Array parts stay distinct, so `['a', 1]` and `'a,1'` are different keys. */
+export type PoServerResourceKey = string | readonly (string | number | boolean | null)[];
+/**
+ * Values one plugin build shares across every level it runs at in one hub.
+ *
+ * The first level to acquire a key creates its value; each acquiring level releases it when that
+ * level unwinds, and the last release disposes it with the `dispose` the creating call passed. The
+ * store belongs to the hub, never to a module, so two hubs in one process share nothing. A new build of
+ * the plugin has its own store, so a session running the old build keeps what it acquired until it
+ * closes.
+ */
+export interface PoServerResources {
+  acquire<T>(key: PoServerResourceKey, create: () => T | Promise<T>, dispose?: (value: T) => void | Promise<void>): Promise<T>;
+}
+/** One held share of a value; releasing it twice is a no-op. */
+export interface PoServerResourceLease<T> {
+  readonly value: T;
+  release(): Promise<void>;
+}
+/** What one plugin build shares in this hub, seen from one scope. `defineServerPlugin` is its caller. */
+export interface PoServerPluginShare<TRoots> {
+  acquire<T>(key: PoServerResourceKey, create: () => T | Promise<T>, dispose?: (value: T) => void | Promise<void>): Promise<PoServerResourceLease<T>>;
+  /** Marks this scope as running the plugin and holding `roots` for the scopes inside it, until withdrawn. */
+  run(roots: TRoots): () => void;
+  /** What every scope running the plugin, from the `from` level out to this scope's parent, holds; innermost first. */
+  outer(from: PoApiScope): readonly TRoots[];
+}
+/** What a plugin sees of the scope it is installed into. */
+export interface PoServerScopeService {
+  readonly level: PoApiScope;
+  /**
+   * Bind the concrete value of a contract owned by this level, visible here and in every descendant.
+   * Settles once every descendant publishes it. The binding unwinds with the calling fiber; the
+   * resolved disposer withdraws it earlier.
+   */
+  provide<T>(contract: PoServiceContract<T>, value: T): Promise<() => Promise<void>>;
+  /** The value bound at the contract's level on this scope's ancestor path, if any. */
+  resolve<T>(contract: PoServiceContract<T>): T | undefined;
+  /** Deliver a cordis event to this scope's root and every ancestor root. */
+  emit<K extends keyof Events>(name: K, ...args: Parameters<Events[K]>): void;
+  /** Deliver a cordis event to this scope's root and every descendant root; siblings never see it. */
+  broadcast<K extends keyof Events>(name: K, ...args: Parameters<Events[K]>): void;
+  /** What the plugin build `owner` shares in this hub. One store per build, kept by the outermost scope. */
+  plugin<TRoots>(owner: object): PoServerPluginShare<TRoots>;
+}
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    'po/server-scope': PoServerScopeService;
+  }
+}
+export declare function readPoServerScope(context: Context): PoServerScopeService | undefined;
+export declare function requirePoServerScope(context: Context): PoServerScopeService;
+//#endregion
+//# sourceMappingURL=serverScope.d.mts.map

package/dist/src/schemas/serverScope.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serverScope.d.mts","names":[],"sources":["../../../src/schemas/serverScope.ts"],"mappings":";;;;;;;;;;qBAWa;;qBAGA,iCAAiC;;iBAG7B,kBAAkB;WACxB;WACA,OAAO;;WAEP,QAAQ;;wBAGH,sBAAsB,GAAG,cAAc;WAAoB,OAAO;IAAe,kBAAkB;;YAKvG;;;;;;;;;;iBAWK;EACf,QAAQ,GACN,KAAK,qBACL,cAAc,IAAI,QAAQ,IAC1B,WAAW,OAAO,aAAa,gBAC9B,QAAQ;;;iBAII,sBAAsB;WAC5B,OAAO;EAChB,WAAW;;;iBAII,oBAAoB;EACnC,QAAQ,GACN,KAAK,qBACL,cAAc,IAAI,QAAQ,IAC1B,WAAW,OAAO,aAAa,gBAC9B,QAAQ,sBAAsB;;EAEjC,IAAI,OAAO;;EAEX,MAAM,MAAM,sBAAsB;;;iBAInB;WACN,OAAO;;;;;;EAMhB,QAAQ,GAAG,UAAU,kBAAkB,IAAI,OAAO,IAAI,cAAc;;EAEpE,QAAQ,GAAG,UAAU,kBAAkB,KAAK;;EAE5C,KAAK,gBAAgB,QAAQ,MAAM,MAAM,MAAM,WAAW,OAAO;;EAEjE,UAAU,gBAAgB,QAAQ,MAAM,MAAM,MAAM,WAAW,OAAO;;EAEtE,OAAO,QAAQ,gBAAgB,oBAAoB;;;YAIzC;IACR,mBAAmB;;;wBAIP,kBAAkB,SAAS,UAAU;wBAIrC,qBAAqB,SAAS,UAAU"}

package/dist/src/schemas/serverScope.mjs

@@ -0,0 +1,33 @@
+//#region src/schemas/serverScope.ts
+/**
+* The server inversion-of-control tree: global, then one scope per workspace, then one per session.
+*
+* Each level has its own cordis root. A contract names an abstract service and the one level whose
+* plugin binds the concrete value; every descendant level sees that value as a native cordis service,
+* so `inject` and `ctx.get` work unchanged. A level never sees a contract bound below it.
+*/
+const PO_SERVER_SCOPE_SERVICE = "po/server-scope";
+/** Outermost first, so a lower index is an ancestor level. */
+const PO_SERVER_SCOPE_LEVELS = [
+	"global",
+	"workspace",
+	"session"
+];
+function defineServiceContract(name, options) {
+	return {
+		name,
+		scope: options.scope
+	};
+}
+function readPoServerScope(context) {
+	return context.get(PO_SERVER_SCOPE_SERVICE);
+}
+function requirePoServerScope(context) {
+	const service = readPoServerScope(context);
+	if (!service) throw new Error("The Po server scope is unavailable. Install packages through a Po server scope.");
+	return service;
+}
+//#endregion
+export { PO_SERVER_SCOPE_LEVELS, PO_SERVER_SCOPE_SERVICE, defineServiceContract, readPoServerScope, requirePoServerScope };
+
+//# sourceMappingURL=serverScope.mjs.map

package/dist/src/schemas/serverScope.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"serverScope.mjs","names":[],"sources":["../../../src/schemas/serverScope.ts"],"sourcesContent":["import type { Context, Events } from '@deepseek-ai/cordis';\n\nimport type { PoApiScope } from './packageApi';\n\n/**\n * The server inversion-of-control tree: global, then one scope per workspace, then one per session.\n *\n * Each level has its own cordis root. A contract names an abstract service and the one level whose\n * plugin binds the concrete value; every descendant level sees that value as a native cordis service,\n * so `inject` and `ctx.get` work unchanged. A level never sees a contract bound below it.\n */\nexport const PO_SERVER_SCOPE_SERVICE = 'po/server-scope';\n\n/** Outermost first, so a lower index is an ancestor level. */\nexport const PO_SERVER_SCOPE_LEVELS: readonly PoApiScope[] = ['global', 'workspace', 'session'];\n\n/** An abstract service: the name every level resolves and the level that provides it. */\nexport interface PoServiceContract<T> {\n  readonly name: string;\n  readonly scope: PoApiScope;\n  /** Type carrier only; never set at runtime. */\n  readonly _type?: T;\n}\n\nexport function defineServiceContract<T>(name: string, options: { readonly scope: PoApiScope }): PoServiceContract<T> {\n  return { name, scope: options.scope };\n}\n\n/** Names one shared value. Array parts stay distinct, so `['a', 1]` and `'a,1'` are different keys. */\nexport type PoServerResourceKey = string | readonly (string | number | boolean | null)[];\n\n/**\n * Values one plugin build shares across every level it runs at in one hub.\n *\n * The first level to acquire a key creates its value; each acquiring level releases it when that\n * level unwinds, and the last release disposes it with the `dispose` the creating call passed. The\n * store belongs to the hub, never to a module, so two hubs in one process share nothing. A new build of\n * the plugin has its own store, so a session running the old build keeps what it acquired until it\n * closes.\n */\nexport interface PoServerResources {\n  acquire<T>(\n    key: PoServerResourceKey,\n    create: () => T | Promise<T>,\n    dispose?: (value: T) => void | Promise<void>,\n  ): Promise<T>;\n}\n\n/** One held share of a value; releasing it twice is a no-op. */\nexport interface PoServerResourceLease<T> {\n  readonly value: T;\n  release(): Promise<void>;\n}\n\n/** What one plugin build shares in this hub, seen from one scope. `defineServerPlugin` is its caller. */\nexport interface PoServerPluginShare<TRoots> {\n  acquire<T>(\n    key: PoServerResourceKey,\n    create: () => T | Promise<T>,\n    dispose?: (value: T) => void | Promise<void>,\n  ): Promise<PoServerResourceLease<T>>;\n  /** Marks this scope as running the plugin and holding `roots` for the scopes inside it, until withdrawn. */\n  run(roots: TRoots): () => void;\n  /** What every scope running the plugin, from the `from` level out to this scope's parent, holds; innermost first. */\n  outer(from: PoApiScope): readonly TRoots[];\n}\n\n/** What a plugin sees of the scope it is installed into. */\nexport interface PoServerScopeService {\n  readonly level: PoApiScope;\n  /**\n   * Bind the concrete value of a contract owned by this level, visible here and in every descendant.\n   * Settles once every descendant publishes it. The binding unwinds with the calling fiber; the\n   * resolved disposer withdraws it earlier.\n   */\n  provide<T>(contract: PoServiceContract<T>, value: T): Promise<() => Promise<void>>;\n  /** The value bound at the contract's level on this scope's ancestor path, if any. */\n  resolve<T>(contract: PoServiceContract<T>): T | undefined;\n  /** Deliver a cordis event to this scope's root and every ancestor root. */\n  emit<K extends keyof Events>(name: K, ...args: Parameters<Events[K]>): void;\n  /** Deliver a cordis event to this scope's root and every descendant root; siblings never see it. */\n  broadcast<K extends keyof Events>(name: K, ...args: Parameters<Events[K]>): void;\n  /** What the plugin build `owner` shares in this hub. One store per build, kept by the outermost scope. */\n  plugin<TRoots>(owner: object): PoServerPluginShare<TRoots>;\n}\n\ndeclare module '@deepseek-ai/cordis' {\n  interface Context {\n    'po/server-scope': PoServerScopeService;\n  }\n}\n\nexport function readPoServerScope(context: Context): PoServerScopeService | undefined {\n  return context.get(PO_SERVER_SCOPE_SERVICE) as PoServerScopeService | undefined;\n}\n\nexport function requirePoServerScope(context: Context): PoServerScopeService {\n  const service = readPoServerScope(context);\n  if (!service) throw new Error('The Po server scope is unavailable. Install packages through a Po server scope.');\n  return service;\n}\n"],"mappings":";;;;;;;;AAWA,MAAa,0BAA0B;;AAGvC,MAAa,yBAAgD;CAAC;CAAU;CAAa;AAAS;AAU9F,SAAgB,sBAAyB,MAAc,SAA+D;CACpH,OAAO;EAAE;EAAM,OAAO,QAAQ;CAAM;AACtC;AAkEA,SAAgB,kBAAkB,SAAoD;CACpF,OAAO,QAAQ,IAAI,uBAAuB;AAC5C;AAEA,SAAgB,qBAAqB,SAAwC;CAC3E,MAAM,UAAU,kBAAkB,OAAO;CACzC,IAAI,CAAC,SAAS,MAAM,IAAI,MAAM,iFAAiF;CAC/G,OAAO;AACT"}