@agimon-ai/doompi-core 0.0.1-alpha.70

package/dist/schemas/serverFacet.d.cts

@@ -0,0 +1,141 @@
+import { DoomHubChannel } from "./hubChannel.cjs";
+import { DoomApi, DoomApiContext, DoomApiScope } from "./packageApi.cjs";
+import { DoomHeadlessCommand, DoomHeadlessHostService, DoomHeadlessTool, DoomHeadlessToolRestriction } from "./headless.cjs";
+import { DoomPluginCommand, DoomPluginTool } from "./pluginContributions.cjs";
+import { DoomPluginCaller, DoomPluginMethod } from "./pluginProtocol.cjs";
+import { DoomToolRestrictionDefinition } from "./toolSurface.cjs";
+import { Static, TSchema } from "typebox";
+import { Context } from "@deepseek-ai/cordis";
+//#region src/schemas/serverFacet.d.ts
+/** The host a server facet contributes to. */
+export declare const DOOM_SERVER_HOST_SERVICE = "doom/server-host";
+export interface DoomServerRegistration {
+  /** 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 facet is handed when it installs.
+ *
+ * `scope` is fixed for the life of the host: a session server never becomes a
+ * hub. A facet that only makes sense in one scope returns early in the other
+ * rather than declaring itself twice.
+ */
+export interface DoomServerHostService {
+  readonly scope: DoomApiScope;
+  /** Identity and host-lent capabilities, the same record an API is started with. */
+  readonly context: DoomApiContext;
+  /**
+   * Mount an API under its own base path. A base path already claimed by an
+   * earlier facet 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: DoomApi): DoomServerRegistration;
+  /** Register a live event source under this host's lifecycle. */
+  registerChannel(channel: DoomHubChannel): DoomServerRegistration;
+  /** Mount a typed call at this host's exact scope. */
+  registerMethod<TInput extends TSchema, TOutput extends TSchema>(definition: DoomPluginMethod<TInput, TOutput>, handler: (input: Static<TInput>, caller: DoomPluginCaller) => Static<TOutput> | Promise<Static<TOutput>>): DoomServerRegistration;
+  /** 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 {
+    'doom/server-host': DoomServerHostService;
+  }
+}
+export declare function readDoomServerHost(context: Context): DoomServerHostService | undefined;
+export declare function requireDoomServerHost(context: Context): DoomServerHostService;
+/** The package.json field a package declares its server facet under. */
+export declare const DOOM_SERVER_FACET_MANIFEST_FIELD = "doompiServer";
+/** The default export a facet module must provide, so a host can install it. */
+export declare const DOOM_SERVER_FACET_EXPORT = "default";
+/**
+ * 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 host: 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. A function facet calling `ctx.inject` inside
+ * itself mounts a child fiber that the host has no handle on.
+ *
+ * A returned function is the disposer, run when the host's root unwinds.
+ */
+export interface DoomServerFacet {
+  readonly inject?: readonly string[];
+  apply(context: Context): void | (() => void | Promise<void>) | Promise<void | (() => void | Promise<void>)>;
+}
+/** One instance belongs to one mounted server scope. */
+export interface DoomServerPluginContext {
+  readonly context: Context;
+  readonly host: DoomServerHostService;
+  readonly agent?: DoomHeadlessHostService;
+  readonly signal: AbortSignal;
+}
+export interface DoomServerMethod {
+  register(host: DoomServerHostService): DoomServerRegistration;
+}
+/** Capture schema inference before heterogeneous methods enter a contribution array. */
+export declare function defineServerMethod<TInput extends TSchema, TOutput extends TSchema>(definition: DoomPluginMethod<TInput, TOutput>, handler: (input: Static<TInput>, caller: DoomPluginCaller) => Static<TOutput> | Promise<Static<TOutput>>): DoomServerMethod;
+export interface DoomServerPluginScope {
+  readonly services?: readonly Parameters<Context['plugin']>[0][];
+  readonly channels?: readonly (() => DoomHubChannel)[];
+  readonly api?: readonly DoomApi[];
+  readonly methods?: readonly DoomServerMethod[];
+  readonly onStart?: (context: DoomServerPluginContext) => void | Promise<void>;
+  readonly onStop?: (context: DoomServerPluginContext) => void | Promise<void>;
+  readonly onDispose?: (context: DoomServerPluginContext) => void | Promise<void>;
+}
+export interface DoomServerSessionPlugin extends DoomServerPluginScope {
+  readonly tools?: readonly (DoomHeadlessTool | DoomPluginTool)[];
+  readonly commands?: readonly (DoomHeadlessCommand | DoomPluginCommand)[];
+  readonly resources?: readonly Parameters<DoomHeadlessHostService['registerResource']>[0][];
+  readonly hooks?: readonly Parameters<DoomHeadlessHostService['registerHook']>[0][];
+  readonly toolRestrictions?: readonly (DoomHeadlessToolRestriction | DoomToolRestrictionDefinition<() => DoomHeadlessToolRestriction>)[];
+  readonly activities?: readonly Parameters<DoomHeadlessHostService['registerActivity']>[0][];
+}
+type ScopeDeclaration<TScope> = TScope | ((context: DoomServerPluginContext) => TScope | Promise<TScope>);
+type NonSessionScope = DoomServerPluginScope & { readonly [K in Exclude<keyof DoomServerSessionPlugin, keyof DoomServerPluginScope>]?: never; };
+export interface DoomServerPluginDefinition {
+  readonly name: string;
+  readonly inject?: readonly string[];
+  readonly global?: ScopeDeclaration<NonSessionScope>;
+  readonly workspace?: ScopeDeclaration<NonSessionScope>;
+  readonly session?: ScopeDeclaration<DoomServerSessionPlugin>;
+}
+/** One package's validated declaration. */
+export interface DeclaredServerFacet {
+  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 facet is installed into; both when the package names neither. */
+  scopes: readonly DoomApiScope[];
+  /** A selected host cannot be ready without this package's runtime capability. */
+  required?: boolean;
+}
+export declare class DoomServerFacetManifestError extends Error {
+  constructor(packageDir: string, message: string);
+}
+/** Narrows a module's default export, so a broken package is a notice rather than a crash. */
+export declare function isDoomServerFacet(value: unknown): value is DoomServerFacet;
+/**
+ * Validates one package.json's `doompiServer` block.
+ *
+ * `dist` is required because a host imports the built entry the package ships,
+ * never its source.
+ */
+export declare function declaredServerFacetsOf(packageDir: string, manifest: Record<string, unknown>): DeclaredServerFacet[];
+/**
+ * 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 facet twice.
+ */
+export declare function orderServerFacets(facets: readonly DeclaredServerFacet[], onNotice?: (message: string) => void): DeclaredServerFacet[];
+//#endregion
+//# sourceMappingURL=serverFacet.d.cts.map

package/dist/schemas/serverFacet.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serverFacet.d.cts","names":[],"sources":["../../src/schemas/serverFacet.ts"],"mappings":";;;;;;;;;;qBAwBa;iBAEI;;WAEN;;EAET;;;;;;;;;iBAUe;WACN,OAAO;;WAEP,SAAS;;;;;;EAMlB,YAAY,KAAK,UAAU;;EAE3B,gBAAgB,SAAS,iBAAiB;;EAE1C,eAAe,eAAe,SAAS,gBAAgB,SACrD,YAAY,iBAAiB,QAAQ,UACrC,UAAU,OAAO,OAAO,SAAS,QAAQ,qBAAqB,OAAO,WAAW,QAAQ,OAAO,YAC9F;;EAEH;;EAEA;;;YAIU;IACR,oBAAoB;;;wBAIR,mBAAmB,SAAS,UAAU;wBAItC,sBAAsB,SAAS,UAAU;;qBAO5C;;qBAGA;;;;;;;;;;;;;iBAcI;WACN;EACT,MAAM,SAAS,+BAA+B,iBAAiB,6BAA6B;;;iBAI7E;WACN,SAAS;WACT,MAAM;WACN,QAAQ;WACR,QAAQ;;iBAGF;EACf,SAAS,MAAM,wBAAwB;;;wBAIzB,mBAAmB,eAAe,SAAS,gBAAgB,SACzE,YAAY,iBAAiB,QAAQ,UACrC,UAAU,OAAO,OAAO,SAAS,QAAQ,qBAAqB,OAAO,WAAW,QAAQ,OAAO,YAC9F;iBAIc;WACN,oBAAoB,WAAW;WAC/B,2BAA2B;WAC3B,eAAe;WACf,mBAAmB;WACnB,WAAW,SAAS,mCAAmC;WACvD,UAAU,SAAS,mCAAmC;WACtD,aAAa,SAAS,mCAAmC;;iBAGnD,gCAAgC;WACtC,kBAAkB,mBAAmB;WACrC,qBAAqB,sBAAsB;WAC3C,qBAAqB,WAAW;WAChC,iBAAiB,WAAW;WAC5B,6BACL,8BACA,oCAAoC;WAE/B,sBAAsB,WAAW;;KAGvC,iBAAiB,UAAU,WAAW,SAAS,4BAA4B,SAAS,QAAQ;KAE5F,kBAAkB,oCACX,KAAK,cAAc,+BAA+B;iBAE7C;WACN;WACA;WACA,SAAS,iBAAiB;WAC1B,YAAY,iBAAiB;WAC7B,UAAU,iBAAiB;;;iBAIrB;EACf;EACA;;EAEA;;EAEA;;EAEA,iBAAiB;;EAEjB;;qBAGW,qCAAqC;EAChD,YAAY,oBAAoB;;;wBAWlB,kBAAkB,iBAAiB,SAAS;;;;;;;wBAmC5C,uBAAuB,oBAAoB,UAAU,0BAA0B;;;;;;wBAkC/E,kBACd,iBAAiB,uBACjB,YAAW,2BACV"}

package/dist/schemas/serverFacet.d.mts

@@ -0,0 +1,141 @@
+import { DoomHubChannel } from "./hubChannel.mjs";
+import { DoomApi, DoomApiContext, DoomApiScope } from "./packageApi.mjs";
+import { DoomHeadlessCommand, DoomHeadlessHostService, DoomHeadlessTool, DoomHeadlessToolRestriction } from "./headless.mjs";
+import { DoomPluginCommand, DoomPluginTool } from "./pluginContributions.mjs";
+import { DoomPluginCaller, DoomPluginMethod } from "./pluginProtocol.mjs";
+import { DoomToolRestrictionDefinition } from "./toolSurface.mjs";
+import { Static, TSchema } from "typebox";
+import { Context } from "@deepseek-ai/cordis";
+//#region src/schemas/serverFacet.d.ts
+/** The host a server facet contributes to. */
+export declare const DOOM_SERVER_HOST_SERVICE = "doom/server-host";
+export interface DoomServerRegistration {
+  /** 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 facet is handed when it installs.
+ *
+ * `scope` is fixed for the life of the host: a session server never becomes a
+ * hub. A facet that only makes sense in one scope returns early in the other
+ * rather than declaring itself twice.
+ */
+export interface DoomServerHostService {
+  readonly scope: DoomApiScope;
+  /** Identity and host-lent capabilities, the same record an API is started with. */
+  readonly context: DoomApiContext;
+  /**
+   * Mount an API under its own base path. A base path already claimed by an
+   * earlier facet 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: DoomApi): DoomServerRegistration;
+  /** Register a live event source under this host's lifecycle. */
+  registerChannel(channel: DoomHubChannel): DoomServerRegistration;
+  /** Mount a typed call at this host's exact scope. */
+  registerMethod<TInput extends TSchema, TOutput extends TSchema>(definition: DoomPluginMethod<TInput, TOutput>, handler: (input: Static<TInput>, caller: DoomPluginCaller) => Static<TOutput> | Promise<Static<TOutput>>): DoomServerRegistration;
+  /** 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 {
+    'doom/server-host': DoomServerHostService;
+  }
+}
+export declare function readDoomServerHost(context: Context): DoomServerHostService | undefined;
+export declare function requireDoomServerHost(context: Context): DoomServerHostService;
+/** The package.json field a package declares its server facet under. */
+export declare const DOOM_SERVER_FACET_MANIFEST_FIELD = "doompiServer";
+/** The default export a facet module must provide, so a host can install it. */
+export declare const DOOM_SERVER_FACET_EXPORT = "default";
+/**
+ * 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 host: 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. A function facet calling `ctx.inject` inside
+ * itself mounts a child fiber that the host has no handle on.
+ *
+ * A returned function is the disposer, run when the host's root unwinds.
+ */
+export interface DoomServerFacet {
+  readonly inject?: readonly string[];
+  apply(context: Context): void | (() => void | Promise<void>) | Promise<void | (() => void | Promise<void>)>;
+}
+/** One instance belongs to one mounted server scope. */
+export interface DoomServerPluginContext {
+  readonly context: Context;
+  readonly host: DoomServerHostService;
+  readonly agent?: DoomHeadlessHostService;
+  readonly signal: AbortSignal;
+}
+export interface DoomServerMethod {
+  register(host: DoomServerHostService): DoomServerRegistration;
+}
+/** Capture schema inference before heterogeneous methods enter a contribution array. */
+export declare function defineServerMethod<TInput extends TSchema, TOutput extends TSchema>(definition: DoomPluginMethod<TInput, TOutput>, handler: (input: Static<TInput>, caller: DoomPluginCaller) => Static<TOutput> | Promise<Static<TOutput>>): DoomServerMethod;
+export interface DoomServerPluginScope {
+  readonly services?: readonly Parameters<Context['plugin']>[0][];
+  readonly channels?: readonly (() => DoomHubChannel)[];
+  readonly api?: readonly DoomApi[];
+  readonly methods?: readonly DoomServerMethod[];
+  readonly onStart?: (context: DoomServerPluginContext) => void | Promise<void>;
+  readonly onStop?: (context: DoomServerPluginContext) => void | Promise<void>;
+  readonly onDispose?: (context: DoomServerPluginContext) => void | Promise<void>;
+}
+export interface DoomServerSessionPlugin extends DoomServerPluginScope {
+  readonly tools?: readonly (DoomHeadlessTool | DoomPluginTool)[];
+  readonly commands?: readonly (DoomHeadlessCommand | DoomPluginCommand)[];
+  readonly resources?: readonly Parameters<DoomHeadlessHostService['registerResource']>[0][];
+  readonly hooks?: readonly Parameters<DoomHeadlessHostService['registerHook']>[0][];
+  readonly toolRestrictions?: readonly (DoomHeadlessToolRestriction | DoomToolRestrictionDefinition<() => DoomHeadlessToolRestriction>)[];
+  readonly activities?: readonly Parameters<DoomHeadlessHostService['registerActivity']>[0][];
+}
+type ScopeDeclaration<TScope> = TScope | ((context: DoomServerPluginContext) => TScope | Promise<TScope>);
+type NonSessionScope = DoomServerPluginScope & { readonly [K in Exclude<keyof DoomServerSessionPlugin, keyof DoomServerPluginScope>]?: never; };
+export interface DoomServerPluginDefinition {
+  readonly name: string;
+  readonly inject?: readonly string[];
+  readonly global?: ScopeDeclaration<NonSessionScope>;
+  readonly workspace?: ScopeDeclaration<NonSessionScope>;
+  readonly session?: ScopeDeclaration<DoomServerSessionPlugin>;
+}
+/** One package's validated declaration. */
+export interface DeclaredServerFacet {
+  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 facet is installed into; both when the package names neither. */
+  scopes: readonly DoomApiScope[];
+  /** A selected host cannot be ready without this package's runtime capability. */
+  required?: boolean;
+}
+export declare class DoomServerFacetManifestError extends Error {
+  constructor(packageDir: string, message: string);
+}
+/** Narrows a module's default export, so a broken package is a notice rather than a crash. */
+export declare function isDoomServerFacet(value: unknown): value is DoomServerFacet;
+/**
+ * Validates one package.json's `doompiServer` block.
+ *
+ * `dist` is required because a host imports the built entry the package ships,
+ * never its source.
+ */
+export declare function declaredServerFacetsOf(packageDir: string, manifest: Record<string, unknown>): DeclaredServerFacet[];
+/**
+ * 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 facet twice.
+ */
+export declare function orderServerFacets(facets: readonly DeclaredServerFacet[], onNotice?: (message: string) => void): DeclaredServerFacet[];
+//#endregion
+//# sourceMappingURL=serverFacet.d.mts.map

package/dist/schemas/serverFacet.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serverFacet.d.mts","names":[],"sources":["../../src/schemas/serverFacet.ts"],"mappings":";;;;;;;;;;qBAwBa;iBAEI;;WAEN;;EAET;;;;;;;;;iBAUe;WACN,OAAO;;WAEP,SAAS;;;;;;EAMlB,YAAY,KAAK,UAAU;;EAE3B,gBAAgB,SAAS,iBAAiB;;EAE1C,eAAe,eAAe,SAAS,gBAAgB,SACrD,YAAY,iBAAiB,QAAQ,UACrC,UAAU,OAAO,OAAO,SAAS,QAAQ,qBAAqB,OAAO,WAAW,QAAQ,OAAO,YAC9F;;EAEH;;EAEA;;;YAIU;IACR,oBAAoB;;;wBAIR,mBAAmB,SAAS,UAAU;wBAItC,sBAAsB,SAAS,UAAU;;qBAO5C;;qBAGA;;;;;;;;;;;;;iBAcI;WACN;EACT,MAAM,SAAS,+BAA+B,iBAAiB,6BAA6B;;;iBAI7E;WACN,SAAS;WACT,MAAM;WACN,QAAQ;WACR,QAAQ;;iBAGF;EACf,SAAS,MAAM,wBAAwB;;;wBAIzB,mBAAmB,eAAe,SAAS,gBAAgB,SACzE,YAAY,iBAAiB,QAAQ,UACrC,UAAU,OAAO,OAAO,SAAS,QAAQ,qBAAqB,OAAO,WAAW,QAAQ,OAAO,YAC9F;iBAIc;WACN,oBAAoB,WAAW;WAC/B,2BAA2B;WAC3B,eAAe;WACf,mBAAmB;WACnB,WAAW,SAAS,mCAAmC;WACvD,UAAU,SAAS,mCAAmC;WACtD,aAAa,SAAS,mCAAmC;;iBAGnD,gCAAgC;WACtC,kBAAkB,mBAAmB;WACrC,qBAAqB,sBAAsB;WAC3C,qBAAqB,WAAW;WAChC,iBAAiB,WAAW;WAC5B,6BACL,8BACA,oCAAoC;WAE/B,sBAAsB,WAAW;;KAGvC,iBAAiB,UAAU,WAAW,SAAS,4BAA4B,SAAS,QAAQ;KAE5F,kBAAkB,oCACX,KAAK,cAAc,+BAA+B;iBAE7C;WACN;WACA;WACA,SAAS,iBAAiB;WAC1B,YAAY,iBAAiB;WAC7B,UAAU,iBAAiB;;;iBAIrB;EACf;EACA;;EAEA;;EAEA;;EAEA,iBAAiB;;EAEjB;;qBAGW,qCAAqC;EAChD,YAAY,oBAAoB;;;wBAWlB,kBAAkB,iBAAiB,SAAS;;;;;;;wBAmC5C,uBAAuB,oBAAoB,UAAU,0BAA0B;;;;;;wBAkC/E,kBACd,iBAAiB,uBACjB,YAAW,2BACV"}

package/dist/schemas/serverFacet.mjs

@@ -0,0 +1,93 @@
+//#region src/schemas/serverFacet.ts
+/** The host a server facet contributes to. */
+const DOOM_SERVER_HOST_SERVICE = "doom/server-host";
+function readDoomServerHost(context) {
+	return context.get(DOOM_SERVER_HOST_SERVICE);
+}
+function requireDoomServerHost(context) {
+	const service = readDoomServerHost(context);
+	if (!service) throw new Error("The Doom server host is unavailable. Start a Doom server first.");
+	return service;
+}
+/** The package.json field a package declares its server facet under. */
+const DOOM_SERVER_FACET_MANIFEST_FIELD = "doompiServer";
+/** The default export a facet module must provide, so a host can install it. */
+const DOOM_SERVER_FACET_EXPORT = "default";
+/** Capture schema inference before heterogeneous methods enter a contribution array. */
+function defineServerMethod(definition, handler) {
+	return { register: (host) => host.registerMethod(definition, handler) };
+}
+var DoomServerFacetManifestError = class extends Error {
+	constructor(packageDir, message) {
+		super(`${DOOM_SERVER_FACET_MANIFEST_FIELD} manifest in ${packageDir}: ${message}`);
+		this.name = "DoomServerFacetManifestError";
+	}
+};
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Narrows a module's default export, so a broken package is a notice rather than a crash. */
+function isDoomServerFacet(value) {
+	return isRecord(value) && typeof value.apply === "function";
+}
+function normalizePath(packageDir, field, value) {
+	if (typeof value !== "string" || !value.startsWith("./") || value.includes("..")) throw new DoomServerFacetManifestError(packageDir, `${field} must be a package-relative ./path with no '..'.`);
+	return value;
+}
+function normalizeScopes(packageDir, value) {
+	if (value === void 0) throw new DoomServerFacetManifestError(packageDir, "scopes must be declared explicitly.");
+	if (!Array.isArray(value) || value.length === 0) throw new DoomServerFacetManifestError(packageDir, "scopes must name 'global', 'workspace', or 'session'.");
+	const scopes = [];
+	for (const scope of value) {
+		if (scope !== "session" && scope !== "global" && scope !== "workspace") throw new DoomServerFacetManifestError(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 `doompiServer` block.
+*
+* `dist` is required because a host imports the built entry the package ships,
+* never its source.
+*/
+function declaredServerFacetsOf(packageDir, manifest) {
+	const declared = manifest[DOOM_SERVER_FACET_MANIFEST_FIELD];
+	if (declared === void 0) return [];
+	if (!isRecord(declared)) throw new DoomServerFacetManifestError(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 DoomServerFacetManifestError(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 DoomServerFacetManifestError(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 facet twice.
+*/
+function orderServerFacets(facets, onNotice = () => void 0) {
+	const sorted = [...facets].sort((left, right) => left.packageName.localeCompare(right.packageName) || left.packageDir.localeCompare(right.packageDir));
+	const owners = /* @__PURE__ */ new Map();
+	const kept = [];
+	for (const facet of sorted) {
+		const holder = owners.get(facet.packageName);
+		if (holder !== void 0) {
+			onNotice(`server facet '${facet.packageName}' from ${facet.packageDir} is skipped: ${holder.packageDir} already claims it.`);
+			continue;
+		}
+		owners.set(facet.packageName, facet);
+		kept.push(facet);
+	}
+	return kept;
+}
+//#endregion
+export { DOOM_SERVER_FACET_EXPORT, DOOM_SERVER_FACET_MANIFEST_FIELD, DOOM_SERVER_HOST_SERVICE, DoomServerFacetManifestError, declaredServerFacetsOf, defineServerMethod, isDoomServerFacet, orderServerFacets, readDoomServerHost, requireDoomServerHost };
+
+//# sourceMappingURL=serverFacet.mjs.map

package/dist/schemas/serverFacet.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"serverFacet.mjs","names":[],"sources":["../../src/schemas/serverFacet.ts"],"sourcesContent":["import type { Context } from '@deepseek-ai/cordis';\n/**\n * The server facet a package installs into a headless host.\n *\n * A package already ships a Pi extension facet for the agent process. This is\n * the second facet: one cordis plugin that a session server or the cockpit hub\n * installs, through which the package contributes its HTTP surface and any\n * behaviour that has to run outside the agent.\n *\n * A facet is installed and disposed like every other Doom contribution. It\n * registers its API from inside that lifecycle, so server behaviour has a clear\n * owner and disposer.\n */\nimport type { Static, TSchema } from 'typebox';\n\nimport type { DoomHeadlessHostService, DoomHeadlessToolRestriction } from './headless';\nimport type { DoomHeadlessTool, DoomHeadlessCommand } from './headless';\nimport type { DoomHubChannel } from './hubChannel';\nimport type { DoomApi, DoomApiContext, DoomApiScope } from './packageApi';\nimport type { DoomPluginTool, DoomPluginCommand } from './pluginContributions';\nimport type { DoomPluginCaller, DoomPluginMethod } from './pluginProtocol';\nimport type { DoomToolRestrictionDefinition } from './toolSurface';\n\n/** The host a server facet contributes to. */\nexport const DOOM_SERVER_HOST_SERVICE = 'doom/server-host';\n\nexport interface DoomServerRegistration {\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 facet is handed when it installs.\n *\n * `scope` is fixed for the life of the host: a session server never becomes a\n * hub. A facet that only makes sense in one scope returns early in the other\n * rather than declaring itself twice.\n */\nexport interface DoomServerHostService {\n  readonly scope: DoomApiScope;\n  /** Identity and host-lent capabilities, the same record an API is started with. */\n  readonly context: DoomApiContext;\n  /**\n   * Mount an API under its own base path. A base path already claimed by an\n   * earlier facet 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: DoomApi): DoomServerRegistration;\n  /** Register a live event source under this host's lifecycle. */\n  registerChannel(channel: DoomHubChannel): DoomServerRegistration;\n  /** Mount a typed call at this host's exact scope. */\n  registerMethod<TInput extends TSchema, TOutput extends TSchema>(\n    definition: DoomPluginMethod<TInput, TOutput>,\n    handler: (input: Static<TInput>, caller: DoomPluginCaller) => Static<TOutput> | Promise<Static<TOutput>>,\n  ): DoomServerRegistration;\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    'doom/server-host': DoomServerHostService;\n  }\n}\n\nexport function readDoomServerHost(context: Context): DoomServerHostService | undefined {\n  return context.get(DOOM_SERVER_HOST_SERVICE) as DoomServerHostService | undefined;\n}\n\nexport function requireDoomServerHost(context: Context): DoomServerHostService {\n  const service = readDoomServerHost(context);\n  if (!service) throw new Error('The Doom server host is unavailable. Start a Doom server first.');\n  return service;\n}\n\n/** The package.json field a package declares its server facet under. */\nexport const DOOM_SERVER_FACET_MANIFEST_FIELD = 'doompiServer';\n\n/** The default export a facet module must provide, so a host can install it. */\nexport const DOOM_SERVER_FACET_EXPORT = 'default';\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 host: 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. A function facet calling `ctx.inject` inside\n * itself mounts a child fiber that the host has no handle on.\n *\n * A returned function is the disposer, run when the host's root unwinds.\n */\nexport interface DoomServerFacet {\n  readonly inject?: readonly string[];\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 DoomServerPluginContext {\n  readonly context: Context;\n  readonly host: DoomServerHostService;\n  readonly agent?: DoomHeadlessHostService;\n  readonly signal: AbortSignal;\n}\n\nexport interface DoomServerMethod {\n  register(host: DoomServerHostService): DoomServerRegistration;\n}\n\n/** Capture schema inference before heterogeneous methods enter a contribution array. */\nexport function defineServerMethod<TInput extends TSchema, TOutput extends TSchema>(\n  definition: DoomPluginMethod<TInput, TOutput>,\n  handler: (input: Static<TInput>, caller: DoomPluginCaller) => Static<TOutput> | Promise<Static<TOutput>>,\n): DoomServerMethod {\n  return { register: (host) => host.registerMethod(definition, handler) };\n}\n\nexport interface DoomServerPluginScope {\n  readonly services?: readonly Parameters<Context['plugin']>[0][];\n  readonly channels?: readonly (() => DoomHubChannel)[];\n  readonly api?: readonly DoomApi[];\n  readonly methods?: readonly DoomServerMethod[];\n  readonly onStart?: (context: DoomServerPluginContext) => void | Promise<void>;\n  readonly onStop?: (context: DoomServerPluginContext) => void | Promise<void>;\n  readonly onDispose?: (context: DoomServerPluginContext) => void | Promise<void>;\n}\n\nexport interface DoomServerSessionPlugin extends DoomServerPluginScope {\n  readonly tools?: readonly (DoomHeadlessTool | DoomPluginTool)[];\n  readonly commands?: readonly (DoomHeadlessCommand | DoomPluginCommand)[];\n  readonly resources?: readonly Parameters<DoomHeadlessHostService['registerResource']>[0][];\n  readonly hooks?: readonly Parameters<DoomHeadlessHostService['registerHook']>[0][];\n  readonly toolRestrictions?: readonly (\n    | DoomHeadlessToolRestriction\n    | DoomToolRestrictionDefinition<() => DoomHeadlessToolRestriction>\n  )[];\n  readonly activities?: readonly Parameters<DoomHeadlessHostService['registerActivity']>[0][];\n}\n\ntype ScopeDeclaration<TScope> = TScope | ((context: DoomServerPluginContext) => TScope | Promise<TScope>);\n// Explicitly forbid session contributions even when a factory returns an inferred object.\ntype NonSessionScope = DoomServerPluginScope & {\n  readonly [K in Exclude<keyof DoomServerSessionPlugin, keyof DoomServerPluginScope>]?: never;\n};\nexport interface DoomServerPluginDefinition {\n  readonly name: string;\n  readonly inject?: readonly string[];\n  readonly global?: ScopeDeclaration<NonSessionScope>;\n  readonly workspace?: ScopeDeclaration<NonSessionScope>;\n  readonly session?: ScopeDeclaration<DoomServerSessionPlugin>;\n}\n\n/** One package's validated declaration. */\nexport interface DeclaredServerFacet {\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 facet is installed into; both when the package names neither. */\n  scopes: readonly DoomApiScope[];\n  /** A selected host cannot be ready without this package's runtime capability. */\n  required?: boolean;\n}\n\nexport class DoomServerFacetManifestError extends Error {\n  constructor(packageDir: string, message: string) {\n    super(`${DOOM_SERVER_FACET_MANIFEST_FIELD} manifest in ${packageDir}: ${message}`);\n    this.name = 'DoomServerFacetManifestError';\n  }\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\n/** Narrows a module's default export, so a broken package is a notice rather than a crash. */\nexport function isDoomServerFacet(value: unknown): value is DoomServerFacet {\n  return isRecord(value) && typeof value.apply === 'function';\n}\n\nfunction normalizePath(packageDir: string, field: string, value: unknown): string {\n  if (typeof value !== 'string' || !value.startsWith('./') || value.includes('..')) {\n    throw new DoomServerFacetManifestError(packageDir, `${field} must be a package-relative ./path with no '..'.`);\n  }\n  return value;\n}\n\nfunction normalizeScopes(packageDir: string, value: unknown): readonly DoomApiScope[] {\n  if (value === undefined) throw new DoomServerFacetManifestError(packageDir, 'scopes must be declared explicitly.');\n  if (!Array.isArray(value) || value.length === 0) {\n    throw new DoomServerFacetManifestError(packageDir, \"scopes must name 'global', 'workspace', or 'session'.\");\n  }\n  const scopes: DoomApiScope[] = [];\n  for (const scope of value) {\n    if (scope !== 'session' && scope !== 'global' && scope !== 'workspace') {\n      throw new DoomServerFacetManifestError(\n        packageDir,\n        `Unknown scope '${String(scope)}'; resync for the three-level host.`,\n      );\n    }\n    if (!scopes.includes(scope)) scopes.push(scope);\n  }\n  return scopes;\n}\n\n/**\n * Validates one package.json's `doompiServer` block.\n *\n * `dist` is required because a host imports the built entry the package ships,\n * never its source.\n */\nexport function declaredServerFacetsOf(packageDir: string, manifest: Record<string, unknown>): DeclaredServerFacet[] {\n  const declared = manifest[DOOM_SERVER_FACET_MANIFEST_FIELD];\n  if (declared === undefined) return [];\n  if (!isRecord(declared)) {\n    throw new DoomServerFacetManifestError(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 DoomServerFacetManifestError(\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 DoomServerFacetManifestError(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 facet twice.\n */\nexport function orderServerFacets(\n  facets: readonly DeclaredServerFacet[],\n  onNotice: (message: string) => void = () => undefined,\n): DeclaredServerFacet[] {\n  const sorted = [...facets].sort(\n    (left, right) =>\n      left.packageName.localeCompare(right.packageName) || left.packageDir.localeCompare(right.packageDir),\n  );\n  const owners = new Map<string, DeclaredServerFacet>();\n  const kept: DeclaredServerFacet[] = [];\n  for (const facet of sorted) {\n    const holder = owners.get(facet.packageName);\n    if (holder !== undefined) {\n      onNotice(\n        `server facet '${facet.packageName}' from ${facet.packageDir} is skipped: ${holder.packageDir} already claims it.`,\n      );\n      continue;\n    }\n    owners.set(facet.packageName, facet);\n    kept.push(facet);\n  }\n  return kept;\n}\n"],"mappings":"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"}