@agimon-ai/po-core 0.0.0-alpha.0

package/dist/src/schemas/packageApi.cjs

@@ -0,0 +1,76 @@
+//#region src/schemas/packageApi.ts
+const DOOM_API_SCOPES = [
+	"global",
+	"workspace",
+	"session"
+];
+/** Canonical public prefix. Scope selection never falls through to a parent. */
+function doomApiMountPath(mount) {
+	if (mount.scope === "global") return "/api/plugins";
+	if (mount.scope === "workspace") return `/api/workspaces/${encodeURIComponent(mount.workspaceId)}/plugins`;
+	if (!mount.workspaceId) throw new Error("A session API path requires its workspace identity.");
+	return `/api/workspaces/${encodeURIComponent(mount.workspaceId)}/sessions/${encodeURIComponent(mount.sessionId)}/plugins`;
+}
+/** Only canonical resource paths may select a protocol listener. */
+function parseDoomSocketPath(pathname) {
+	if (pathname === "/api/ws") return { scope: "global" };
+	const match = /^\/api\/workspaces\/([^/]+)(?:\/sessions\/([^/]+))?\/ws$/u.exec(pathname);
+	if (!match) return void 0;
+	try {
+		const workspaceId = decodeURIComponent(match[1]);
+		return match[2] === void 0 ? {
+			scope: "workspace",
+			workspaceId
+		} : {
+			scope: "session",
+			workspaceId,
+			sessionId: decodeURIComponent(match[2])
+		};
+	} catch {
+		return;
+	}
+}
+/** The segment an API is mounted under, below this prefix. */
+const DOOM_API_ROUTE_PREFIX = "/api/plugins";
+/** Selects the hub API bundle that owns the named cockpit session. */
+const DOOM_HUB_API_SESSION_QUERY_PARAM = "hubSession";
+/** Trusted caller headers written only by the cockpit-to-session proxy. */
+const DOOM_API_CALLER_LOCALITY_HEADER = "x-po-api-caller-locality";
+const DOOM_API_CALLER_DEVICE_ID_HEADER = "x-po-api-caller-device-id";
+const DOOM_API_CALLER_STEP_UP_HEADER = "x-po-api-caller-step-up";
+const DOOM_API_CALLER_HEADERS = [
+	DOOM_API_CALLER_LOCALITY_HEADER,
+	DOOM_API_CALLER_DEVICE_ID_HEADER,
+	DOOM_API_CALLER_STEP_UP_HEADER
+];
+/** Reads the proxy-authenticated caller identity, rejecting partial or contradictory stamps. */
+function doomApiCallerFrom(headers) {
+	const locality = headers.get(DOOM_API_CALLER_LOCALITY_HEADER);
+	const deviceId = headers.get(DOOM_API_CALLER_DEVICE_ID_HEADER);
+	const stepUp = headers.get(DOOM_API_CALLER_STEP_UP_HEADER);
+	if (locality === "local") return deviceId === null && stepUp === "not-required" ? {
+		locality,
+		stepUp
+	} : void 0;
+	if (locality === "remote" && deviceId !== null && deviceId !== "" && (stepUp === "not-required" || stepUp === "verified" || stepUp === "unavailable")) return {
+		locality,
+		deviceId,
+		stepUp
+	};
+}
+/** Why shareFile rejects while the host has no public tunnel origin. */
+const DOOM_SHARE_FILE_REMOTE_OFF_MESSAGE = "Remote access is off, so Po cannot share files with remote MCP servers. Turn it on and retry.";
+//#endregion
+exports.DOOM_API_CALLER_DEVICE_ID_HEADER = DOOM_API_CALLER_DEVICE_ID_HEADER;
+exports.DOOM_API_CALLER_HEADERS = DOOM_API_CALLER_HEADERS;
+exports.DOOM_API_CALLER_LOCALITY_HEADER = DOOM_API_CALLER_LOCALITY_HEADER;
+exports.DOOM_API_CALLER_STEP_UP_HEADER = DOOM_API_CALLER_STEP_UP_HEADER;
+exports.DOOM_API_ROUTE_PREFIX = DOOM_API_ROUTE_PREFIX;
+exports.DOOM_API_SCOPES = DOOM_API_SCOPES;
+exports.DOOM_HUB_API_SESSION_QUERY_PARAM = DOOM_HUB_API_SESSION_QUERY_PARAM;
+exports.DOOM_SHARE_FILE_REMOTE_OFF_MESSAGE = DOOM_SHARE_FILE_REMOTE_OFF_MESSAGE;
+exports.doomApiCallerFrom = doomApiCallerFrom;
+exports.doomApiMountPath = doomApiMountPath;
+exports.parseDoomSocketPath = parseDoomSocketPath;
+
+//# sourceMappingURL=packageApi.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"packageApi.cjs","names":[],"sources":["../../../src/schemas/packageApi.ts"],"sourcesContent":["/**\n * The HTTP surface a package offers its host.\n *\n * A server facet registers one with its host. The host mounts it under the API\n * route prefix, and the package writes routes relative to that mount.\n *\n * The handler is a plain fetch callback so no host and no package is committed\n * to one HTTP framework; a Hono app satisfies it through `app.fetch`.\n */\n\nimport type {\n  DoomComputerUseSessionAccess,\n  DoomDirectEventBus,\n  DoomHubSessionService,\n  DoomSessionCommunicationEndpoint,\n  DoomSessionActivity,\n  DoomSessionContext,\n} from './hubChannel';\nimport type { DoomMcpProjection } from './mcpProjection';\n/** The host-owned sync view a repository-scoped package API may inspect. */\nexport interface DoomRepositorySyncView {\n  fresh: boolean;\n  reasons: string[];\n  /** True while a background sync that may prepare what `reasons` names is running. */\n  syncing?: boolean;\n  mcpProjection?: DoomMcpProjection;\n}\n\n/** Where an API runs: inside one session's server, or in the machine-wide hub. */\nexport type DoomApiScope = 'global' | 'workspace' | 'session';\n\nexport const DOOM_API_SCOPES: readonly DoomApiScope[] = ['global', 'workspace', 'session'];\n\n/** Identity of an independently mounted plugin host. */\nexport type DoomApiMount =\n  | { scope: 'global' }\n  | { scope: 'workspace'; workspaceId: string }\n  | { scope: 'session'; sessionId: string };\n\n/** Immutable browser contribution generation paired with a server mount. */\nexport interface DoomWebComposition {\n  id: string;\n  scope: DoomApiScope;\n  revision: number;\n  manifestUrl: string;\n  rawAssetBaseUrl: string;\n  verifiedAssetBaseUrl: string;\n  /** `[slot, entry]` for each of this mount's plugin copies, the entry an absolute path below the asset prefixes. */\n  pluginEntries: [string, string][];\n  /** Every signed file this mount's slots can load, absolute below the asset prefixes. */\n  assetPaths: string[];\n  /** Per-plugin stylesheets of this mount's plugins only, so other mounts' classes never apply here. */\n  stylePaths: string[];\n  channels: string[];\n  /** The slots resolved for this mount; the shared build may hold more. */\n  plugins: string[];\n}\n\n/**\n * Immutable native contribution generation paired with a server mount. One signed CommonJS module at\n * `entryPath`, served through the same immutable plugin routes as web compositions.\n */\nexport interface DoomNativeComposition {\n  id: string;\n  scope: DoomApiScope;\n  revision: number;\n  manifestUrl: string;\n  rawAssetBaseUrl: string;\n  /** Always `/composition.js`. */\n  entryPath: string;\n  channels: string[];\n  /** The `poNative.pluginId` values resolved for this mount; the shell installs only these. */\n  plugins: string[];\n}\n\n/** Canonical public prefix. Scope selection never falls through to a parent. */\nexport function doomApiMountPath(mount: DoomApiMount & { workspaceId?: string }): string {\n  if (mount.scope === 'global') return '/api/plugins';\n  if (mount.scope === 'workspace') return `/api/workspaces/${encodeURIComponent(mount.workspaceId)}/plugins`;\n  if (!mount.workspaceId) throw new Error('A session API path requires its workspace identity.');\n  return `/api/workspaces/${encodeURIComponent(mount.workspaceId)}/sessions/${encodeURIComponent(mount.sessionId)}/plugins`;\n}\n\n/** Scope addressed by a public WebSocket upgrade. */\nexport type DoomSocketMount =\n  | { scope: 'global' }\n  | { scope: 'workspace'; workspaceId: string }\n  | { scope: 'session'; workspaceId: string; sessionId: string };\n\n/** Only canonical resource paths may select a protocol listener. */\nexport function parseDoomSocketPath(pathname: string): DoomSocketMount | undefined {\n  if (pathname === '/api/ws') return { scope: 'global' };\n  const match = /^\\/api\\/workspaces\\/([^/]+)(?:\\/sessions\\/([^/]+))?\\/ws$/u.exec(pathname);\n  if (!match) return undefined;\n  try {\n    const workspaceId = decodeURIComponent(match[1]);\n    return match[2] === undefined\n      ? { scope: 'workspace', workspaceId }\n      : { scope: 'session', workspaceId, sessionId: decodeURIComponent(match[2]) };\n  } catch {\n    return undefined;\n  }\n}\n\n/** The segment an API is mounted under, below this prefix. */\nexport const DOOM_API_ROUTE_PREFIX = '/api/plugins';\n/** Selects the hub API bundle that owns the named cockpit session. */\nexport const DOOM_HUB_API_SESSION_QUERY_PARAM = 'hubSession';\n\n/** Trusted caller headers written only by the cockpit-to-session proxy. */\nexport const DOOM_API_CALLER_LOCALITY_HEADER = 'x-po-api-caller-locality';\nexport const DOOM_API_CALLER_DEVICE_ID_HEADER = 'x-po-api-caller-device-id';\nexport const DOOM_API_CALLER_STEP_UP_HEADER = 'x-po-api-caller-step-up';\nexport const DOOM_API_CALLER_HEADERS = [\n  DOOM_API_CALLER_LOCALITY_HEADER,\n  DOOM_API_CALLER_DEVICE_ID_HEADER,\n  DOOM_API_CALLER_STEP_UP_HEADER,\n] as const;\n\nexport type DoomApiCallerStepUp = 'not-required' | 'verified' | 'unavailable';\nexport type DoomApiCaller =\n  | { locality: 'local'; stepUp: 'not-required' }\n  | { locality: 'remote'; deviceId: string; stepUp: DoomApiCallerStepUp };\n\n/** Reads the proxy-authenticated caller identity, rejecting partial or contradictory stamps. */\nexport function doomApiCallerFrom(headers: Headers): DoomApiCaller | undefined {\n  const locality = headers.get(DOOM_API_CALLER_LOCALITY_HEADER);\n  const deviceId = headers.get(DOOM_API_CALLER_DEVICE_ID_HEADER);\n  const stepUp = headers.get(DOOM_API_CALLER_STEP_UP_HEADER);\n  if (locality === 'local') {\n    return deviceId === null && stepUp === 'not-required' ? { locality, stepUp } : undefined;\n  }\n  if (\n    locality === 'remote' &&\n    deviceId !== null &&\n    deviceId !== '' &&\n    (stepUp === 'not-required' || stepUp === 'verified' || stepUp === 'unavailable')\n  ) {\n    return { locality, deviceId, stepUp };\n  }\n  return undefined;\n}\n/**\n * A browser-reachable OAuth redirect the host serves on its own listener.\n *\n * A package brokering third-party OAuth cannot use a loopback redirect when the\n * operator's browser is on another machine: `127.0.0.1` resolves to whichever\n * machine the browser runs on. The host owns a listener that is reachable from\n * wherever the cockpit is being used, so it lends that instead of the package\n * opening a port of its own.\n */\nexport interface DoomOAuthRedirect {\n  /** Absolute URL to register as the redirect target, already origin-correct. */\n  readonly redirectUri: string;\n  /**\n   * Accept redirects carrying this state. Must complete before the\n   * authorization URL is surfaced, or the redirect races its own reservation.\n   */\n  reserve(state: string, timeoutMs?: number): Promise<void>;\n  /** Resolves once the redirect carrying this state arrives. */\n  wait(state: string, timeoutMs?: number): Promise<{ code: string; state: string }>;\n  /** Drops a reservation whose flow ended without a redirect. */\n  cancel(state: string): void;\n}\n\n/** An exact, host-owned receipt address. Provider IDs are not event cursor positions. */\nexport interface DoomRequestReceiptKey {\n  namespace: string;\n  activationId: string;\n  requestId: string;\n}\n\nexport interface DoomRequestReceipt extends DoomRequestReceiptKey {\n  fingerprint: string;\n  destination: string;\n  transactionId: string;\n  outcome: 'reserved' | 'admitted' | 'rejected' | 'uncertain';\n}\n\nexport interface DoomRequestReceiptReservation extends DoomRequestReceiptKey {\n  /** Lowercase SHA-256 of the authoritative request text, never the full transcript. */\n  fingerprint: string;\n  destination: string;\n  transactionId: string;\n}\n\nexport type DoomRequestReceiptReserveResult =\n  | { kind: 'reserved'; token: string }\n  | { kind: 'existing'; receipt: DoomRequestReceipt }\n  | { kind: 'conflict'; receipt: DoomRequestReceipt };\n\n/** A global-only receipt capability. A reservation is not an execution receipt. */\nexport interface DoomRequestReceipts {\n  reserve(request: DoomRequestReceiptReservation): Promise<DoomRequestReceiptReserveResult>;\n  lookup(key: DoomRequestReceiptKey): Promise<DoomRequestReceipt | undefined>;\n  finish(\n    request: DoomRequestReceiptKey & { token: string; outcome: 'admitted' | 'rejected' | 'uncertain' },\n  ): Promise<DoomRequestReceipt>;\n}\n\n/** Permit returned for expensive local work. Calling it releases the slot. */\nexport interface DoomHostExecutionPermit {\n  (): void;\n  attachProcess?(pid: number): Promise<void>;\n}\n\n/** Host-wide admission for expensive local work. Release only after the owned process exits. */\nexport interface DoomHostExecutionBudget {\n  acquire(signal?: AbortSignal): Promise<DoomHostExecutionPermit>;\n  getSnapshot(): Readonly<{ running: number; queued: number; limit: number }>;\n}\n\n/** Synchronous host-owned exclusion across media APIs mounted at different scopes. */\nexport interface DoomHostMediaArbitration {\n  register(busy: () => boolean): () => void;\n  available(busy: () => boolean): boolean;\n}\n\n/** One host's paired agent registrations, shared across its global and session mounts. */\nexport interface DoomPeerAgentRegistry {\n  register(sessionId: string, agent: { fetch(request: Request): Promise<Response> }, hubToken: string): () => void;\n  get(sessionId: string): { fetch(request: Request): Promise<Response>; hubToken: string } | undefined;\n}\n\n/** Why shareFile rejects while the host has no public tunnel origin. */\nexport const DOOM_SHARE_FILE_REMOTE_OFF_MESSAGE =\n  'Remote access is off, so Po cannot share files with remote MCP servers. Turn it on and retry.';\n\n/**\n * A file published at a short-lived public tunnel URL: 10 minutes, 3 downloads, and gone\n * when the tunnel revision changes. Call revoke as soon as the consumer is done with it.\n */\nexport interface DoomSharedFile {\n  /** Bearer link; never log or persist it. */\n  url: string;\n  fileName: string;\n  mimeType: string;\n  size: number;\n  /** Expiry as epoch milliseconds. */\n  expiresAt: number;\n  maxDownloads: number;\n  /** Idempotent. */\n  revoke(): void;\n}\n\n/** What the host tells an API about itself when it starts. */\nexport interface DoomApiContext {\n  scope: DoomApiScope;\n  /** Stable, opaque workspace id, shared by every session and member checkout of the workspace. */\n  workspaceId?: string;\n  /**\n   * The admitted workspace root for a workspace mount. For a session mount it is the checkout\n   * the session runs in; read sessionContext for both roots. Absent from global mounts.\n   */\n  workspaceRoot?: string;\n  /** The session's baseline context; present on session mounts whose host knows its workspace. */\n  sessionContext?: DoomSessionContext;\n  /** Explicit host home, never selected by a remote request. */\n  homeDirectory?: string;\n  /** The session this host serves; absent for a hub-scoped API. */\n  sessionId?: string;\n  /** The session's working directory; absent for a hub-scoped API. */\n  cwd?: string;\n  /** Session environment admitted by the server, never supplied by remote clients. */\n  environment?: Readonly<Record<string, string | undefined>>;\n  /** Shared only with child processes in this session, never with remote API clients. */\n  internalToken?: string;\n  /** Shared only with the cockpit hub for privileged cross-session coordination. */\n  hubToken?: string;\n  /**\n   * Resolves a hub-issued opaque repository id to an admitted canonical root.\n   * Hub APIs must never accept a browser-supplied filesystem path instead.\n   */\n  resolveRepository?(repositoryId: string): string | undefined;\n  /** Reads the admitted repository's sync projection without exposing its state path. */\n  readRepositorySync?(\n    repositoryId: string,\n  ): Promise<DoomRepositorySyncView | undefined> | DoomRepositorySyncView | undefined;\n  /** Admitted workspaces available to this mount. */\n  repositories?(): readonly { id: string; name: string; path: string; active: boolean }[];\n  /** Publish a successful config write to the owning mount's refresh lifecycle. */\n  configurationChanged?(): void;\n  /**\n   * Borrows the hub's OAuth redirect surface. Undefined when the hub cannot\n   * currently serve one, in which case the package keeps its own behaviour.\n   */\n  oauthRedirect?(): DoomOAuthRedirect | undefined;\n  /** Canonical in-process lifecycle for sessions created by this host. */\n  sessionService?: DoomHubSessionService;\n  /** Host-bound, authenticated inter-session event endpoint for this session. */\n  sessionCommunication?: DoomSessionCommunicationEndpoint;\n  /** Same-process events shared by session APIs and hub channels. */\n  directEvents?: DoomDirectEventBus;\n  /**\n   * Publishes this session's activity line to every page's rail; undefined clears it.\n   * Session mounts only. The last publisher wins.\n   */\n  publishActivity?(activity: DoomSessionActivity | undefined): void;\n  /** Trusted in-process dispatch to an explicitly selected mounted API. No browser authentication is performed here. */\n  requestApi?(mount: DoomApiMount, basePath: string, request: Request): Promise<Response>;\n  /** Present only on a session mounted by an authenticated Desktop host. */\n  computerUse?: DoomComputerUseSessionAccess;\n  /** Deliver a typed method to a channel on this exact hub mount, retaining the caller's connection identity. */\n  receiveChannel?(sessionId: string, frameType: string, payload: unknown, connectionId: string): boolean;\n  /** Host-owned replay evidence, supplied only on the global mount. Never exposed to browsers or agents. */\n  requestReceipts?: DoomRequestReceipts;\n  /** One host's exclusive media activity, shared across global and session scopes. */\n  mediaArbitration?: DoomHostMediaArbitration;\n  /** One host-wide heavy-job budget, not a separate budget for every session. */\n  executionBudget?: DoomHostExecutionBudget;\n  /** Paired agents belonging to this host only. */\n  peerAgents?: DoomPeerAgentRegistry;\n  /** Machine-owned Remote Control service, mounted only by the global core facet. */\n  remoteControl?: { fetch(request: Request): Promise<Response> };\n  /**\n   * Publishes a file from this session's cwd or attachments at a short-lived tunnel URL.\n   * Session mounts only; rejects with DOOM_SHARE_FILE_REMOTE_OFF_MESSAGE while remote access is off.\n   * The host asks no consent: the caller must obtain it before passing the URL on.\n   */\n  shareFile?(path: string, label: string): Promise<DoomSharedFile>;\n  onNotice(message: string): void;\n}\n\n/**\n * One running surface. The host strips the mount prefix before calling, so\n * routes are declared relative ('/runners/:id/log') and a package never\n * repeats where it was mounted.\n */\nexport interface DoomApiHandler {\n  fetch(request: Request): Response | Promise<Response>;\n  close(): void;\n}\n\nexport interface DoomApi {\n  /** Segment under /api/plugins/; globally unique across loaded packages. */\n  basePath: string;\n  start(context: DoomApiContext): DoomApiHandler;\n}\n"],"mappings":";AA+BA,MAAa,kBAA2C;CAAC;CAAU;CAAa;AAAS;;AA6CzF,SAAgB,iBAAiB,OAAwD;CACvF,IAAI,MAAM,UAAU,UAAU,OAAO;CACrC,IAAI,MAAM,UAAU,aAAa,OAAO,mBAAmB,mBAAmB,MAAM,WAAW,EAAE;CACjG,IAAI,CAAC,MAAM,aAAa,MAAM,IAAI,MAAM,qDAAqD;CAC7F,OAAO,mBAAmB,mBAAmB,MAAM,WAAW,EAAE,YAAY,mBAAmB,MAAM,SAAS,EAAE;AAClH;;AASA,SAAgB,oBAAoB,UAA+C;CACjF,IAAI,aAAa,WAAW,OAAO,EAAE,OAAO,SAAS;CACrD,MAAM,QAAQ,4DAA4D,KAAK,QAAQ;CACvF,IAAI,CAAC,OAAO,OAAO,KAAA;CACnB,IAAI;EACF,MAAM,cAAc,mBAAmB,MAAM,EAAE;EAC/C,OAAO,MAAM,OAAO,KAAA,IAChB;GAAE,OAAO;GAAa;EAAY,IAClC;GAAE,OAAO;GAAW;GAAa,WAAW,mBAAmB,MAAM,EAAE;EAAE;CAC/E,QAAQ;EACN;CACF;AACF;;AAGA,MAAa,wBAAwB;;AAErC,MAAa,mCAAmC;;AAGhD,MAAa,kCAAkC;AAC/C,MAAa,mCAAmC;AAChD,MAAa,iCAAiC;AAC9C,MAAa,0BAA0B;CACrC;CACA;CACA;AACF;;AAQA,SAAgB,kBAAkB,SAA6C;CAC7E,MAAM,WAAW,QAAQ,IAAI,+BAA+B;CAC5D,MAAM,WAAW,QAAQ,IAAI,gCAAgC;CAC7D,MAAM,SAAS,QAAQ,IAAI,8BAA8B;CACzD,IAAI,aAAa,SACf,OAAO,aAAa,QAAQ,WAAW,iBAAiB;EAAE;EAAU;CAAO,IAAI,KAAA;CAEjF,IACE,aAAa,YACb,aAAa,QACb,aAAa,OACZ,WAAW,kBAAkB,WAAW,cAAc,WAAW,gBAElE,OAAO;EAAE;EAAU;EAAU;CAAO;AAGxC;;AAoFA,MAAa,qCACX"}

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

@@ -0,0 +1,302 @@
+import { DoomComputerUseSessionAccess, DoomDirectEventBus, DoomHubSessionService, DoomSessionActivity, DoomSessionCommunicationEndpoint, DoomSessionContext } from "./hubChannel.mjs";
+import { DoomMcpProjection } from "./mcpProjection.mjs";
+//#region src/schemas/packageApi.d.ts
+/** The host-owned sync view a repository-scoped package API may inspect. */
+export interface DoomRepositorySyncView {
+  fresh: boolean;
+  reasons: string[];
+  /** True while a background sync that may prepare what `reasons` names is running. */
+  syncing?: boolean;
+  mcpProjection?: DoomMcpProjection;
+}
+/** Where an API runs: inside one session's server, or in the machine-wide hub. */
+export type DoomApiScope = 'global' | 'workspace' | 'session';
+export declare const DOOM_API_SCOPES: readonly DoomApiScope[];
+/** Identity of an independently mounted plugin host. */
+export type DoomApiMount = {
+  scope: 'global';
+} | {
+  scope: 'workspace';
+  workspaceId: string;
+} | {
+  scope: 'session';
+  sessionId: string;
+};
+/** Immutable browser contribution generation paired with a server mount. */
+export interface DoomWebComposition {
+  id: string;
+  scope: DoomApiScope;
+  revision: number;
+  manifestUrl: string;
+  rawAssetBaseUrl: string;
+  verifiedAssetBaseUrl: string;
+  /** `[slot, entry]` for each of this mount's plugin copies, the entry an absolute path below the asset prefixes. */
+  pluginEntries: [string, string][];
+  /** Every signed file this mount's slots can load, absolute below the asset prefixes. */
+  assetPaths: string[];
+  /** Per-plugin stylesheets of this mount's plugins only, so other mounts' classes never apply here. */
+  stylePaths: string[];
+  channels: string[];
+  /** The slots resolved for this mount; the shared build may hold more. */
+  plugins: string[];
+}
+/**
+ * Immutable native contribution generation paired with a server mount. One signed CommonJS module at
+ * `entryPath`, served through the same immutable plugin routes as web compositions.
+ */
+export interface DoomNativeComposition {
+  id: string;
+  scope: DoomApiScope;
+  revision: number;
+  manifestUrl: string;
+  rawAssetBaseUrl: string;
+  /** Always `/composition.js`. */
+  entryPath: string;
+  channels: string[];
+  /** The `poNative.pluginId` values resolved for this mount; the shell installs only these. */
+  plugins: string[];
+}
+/** Canonical public prefix. Scope selection never falls through to a parent. */
+export declare function doomApiMountPath(mount: DoomApiMount & {
+  workspaceId?: string;
+}): string;
+/** Scope addressed by a public WebSocket upgrade. */
+export type DoomSocketMount = {
+  scope: 'global';
+} | {
+  scope: 'workspace';
+  workspaceId: string;
+} | {
+  scope: 'session';
+  workspaceId: string;
+  sessionId: string;
+};
+/** Only canonical resource paths may select a protocol listener. */
+export declare function parseDoomSocketPath(pathname: string): DoomSocketMount | undefined;
+/** The segment an API is mounted under, below this prefix. */
+export declare const DOOM_API_ROUTE_PREFIX = "/api/plugins";
+/** Selects the hub API bundle that owns the named cockpit session. */
+export declare const DOOM_HUB_API_SESSION_QUERY_PARAM = "hubSession";
+/** Trusted caller headers written only by the cockpit-to-session proxy. */
+export declare const DOOM_API_CALLER_LOCALITY_HEADER = "x-po-api-caller-locality";
+export declare const DOOM_API_CALLER_DEVICE_ID_HEADER = "x-po-api-caller-device-id";
+export declare const DOOM_API_CALLER_STEP_UP_HEADER = "x-po-api-caller-step-up";
+export declare const DOOM_API_CALLER_HEADERS: readonly ["x-po-api-caller-locality", "x-po-api-caller-device-id", "x-po-api-caller-step-up"];
+export type DoomApiCallerStepUp = 'not-required' | 'verified' | 'unavailable';
+export type DoomApiCaller = {
+  locality: 'local';
+  stepUp: 'not-required';
+} | {
+  locality: 'remote';
+  deviceId: string;
+  stepUp: DoomApiCallerStepUp;
+};
+/** Reads the proxy-authenticated caller identity, rejecting partial or contradictory stamps. */
+export declare function doomApiCallerFrom(headers: Headers): DoomApiCaller | undefined;
+/**
+ * A browser-reachable OAuth redirect the host serves on its own listener.
+ *
+ * A package brokering third-party OAuth cannot use a loopback redirect when the
+ * operator's browser is on another machine: `127.0.0.1` resolves to whichever
+ * machine the browser runs on. The host owns a listener that is reachable from
+ * wherever the cockpit is being used, so it lends that instead of the package
+ * opening a port of its own.
+ */
+export interface DoomOAuthRedirect {
+  /** Absolute URL to register as the redirect target, already origin-correct. */
+  readonly redirectUri: string;
+  /**
+   * Accept redirects carrying this state. Must complete before the
+   * authorization URL is surfaced, or the redirect races its own reservation.
+   */
+  reserve(state: string, timeoutMs?: number): Promise<void>;
+  /** Resolves once the redirect carrying this state arrives. */
+  wait(state: string, timeoutMs?: number): Promise<{
+    code: string;
+    state: string;
+  }>;
+  /** Drops a reservation whose flow ended without a redirect. */
+  cancel(state: string): void;
+}
+/** An exact, host-owned receipt address. Provider IDs are not event cursor positions. */
+export interface DoomRequestReceiptKey {
+  namespace: string;
+  activationId: string;
+  requestId: string;
+}
+export interface DoomRequestReceipt extends DoomRequestReceiptKey {
+  fingerprint: string;
+  destination: string;
+  transactionId: string;
+  outcome: 'reserved' | 'admitted' | 'rejected' | 'uncertain';
+}
+export interface DoomRequestReceiptReservation extends DoomRequestReceiptKey {
+  /** Lowercase SHA-256 of the authoritative request text, never the full transcript. */
+  fingerprint: string;
+  destination: string;
+  transactionId: string;
+}
+export type DoomRequestReceiptReserveResult = {
+  kind: 'reserved';
+  token: string;
+} | {
+  kind: 'existing';
+  receipt: DoomRequestReceipt;
+} | {
+  kind: 'conflict';
+  receipt: DoomRequestReceipt;
+};
+/** A global-only receipt capability. A reservation is not an execution receipt. */
+export interface DoomRequestReceipts {
+  reserve(request: DoomRequestReceiptReservation): Promise<DoomRequestReceiptReserveResult>;
+  lookup(key: DoomRequestReceiptKey): Promise<DoomRequestReceipt | undefined>;
+  finish(request: DoomRequestReceiptKey & {
+    token: string;
+    outcome: 'admitted' | 'rejected' | 'uncertain';
+  }): Promise<DoomRequestReceipt>;
+}
+/** Permit returned for expensive local work. Calling it releases the slot. */
+export interface DoomHostExecutionPermit {
+  (): void;
+  attachProcess?(pid: number): Promise<void>;
+}
+/** Host-wide admission for expensive local work. Release only after the owned process exits. */
+export interface DoomHostExecutionBudget {
+  acquire(signal?: AbortSignal): Promise<DoomHostExecutionPermit>;
+  getSnapshot(): Readonly<{
+    running: number;
+    queued: number;
+    limit: number;
+  }>;
+}
+/** Synchronous host-owned exclusion across media APIs mounted at different scopes. */
+export interface DoomHostMediaArbitration {
+  register(busy: () => boolean): () => void;
+  available(busy: () => boolean): boolean;
+}
+/** One host's paired agent registrations, shared across its global and session mounts. */
+export interface DoomPeerAgentRegistry {
+  register(sessionId: string, agent: {
+    fetch(request: Request): Promise<Response>;
+  }, hubToken: string): () => void;
+  get(sessionId: string): {
+    fetch(request: Request): Promise<Response>;
+    hubToken: string;
+  } | undefined;
+}
+/** Why shareFile rejects while the host has no public tunnel origin. */
+export declare const DOOM_SHARE_FILE_REMOTE_OFF_MESSAGE = "Remote access is off, so Po cannot share files with remote MCP servers. Turn it on and retry.";
+/**
+ * A file published at a short-lived public tunnel URL: 10 minutes, 3 downloads, and gone
+ * when the tunnel revision changes. Call revoke as soon as the consumer is done with it.
+ */
+export interface DoomSharedFile {
+  /** Bearer link; never log or persist it. */
+  url: string;
+  fileName: string;
+  mimeType: string;
+  size: number;
+  /** Expiry as epoch milliseconds. */
+  expiresAt: number;
+  maxDownloads: number;
+  /** Idempotent. */
+  revoke(): void;
+}
+/** What the host tells an API about itself when it starts. */
+export interface DoomApiContext {
+  scope: DoomApiScope;
+  /** Stable, opaque workspace id, shared by every session and member checkout of the workspace. */
+  workspaceId?: string;
+  /**
+   * The admitted workspace root for a workspace mount. For a session mount it is the checkout
+   * the session runs in; read sessionContext for both roots. Absent from global mounts.
+   */
+  workspaceRoot?: string;
+  /** The session's baseline context; present on session mounts whose host knows its workspace. */
+  sessionContext?: DoomSessionContext;
+  /** Explicit host home, never selected by a remote request. */
+  homeDirectory?: string;
+  /** The session this host serves; absent for a hub-scoped API. */
+  sessionId?: string;
+  /** The session's working directory; absent for a hub-scoped API. */
+  cwd?: string;
+  /** Session environment admitted by the server, never supplied by remote clients. */
+  environment?: Readonly<Record<string, string | undefined>>;
+  /** Shared only with child processes in this session, never with remote API clients. */
+  internalToken?: string;
+  /** Shared only with the cockpit hub for privileged cross-session coordination. */
+  hubToken?: string;
+  /**
+   * Resolves a hub-issued opaque repository id to an admitted canonical root.
+   * Hub APIs must never accept a browser-supplied filesystem path instead.
+   */
+  resolveRepository?(repositoryId: string): string | undefined;
+  /** Reads the admitted repository's sync projection without exposing its state path. */
+  readRepositorySync?(repositoryId: string): Promise<DoomRepositorySyncView | undefined> | DoomRepositorySyncView | undefined;
+  /** Admitted workspaces available to this mount. */
+  repositories?(): readonly {
+    id: string;
+    name: string;
+    path: string;
+    active: boolean;
+  }[];
+  /** Publish a successful config write to the owning mount's refresh lifecycle. */
+  configurationChanged?(): void;
+  /**
+   * Borrows the hub's OAuth redirect surface. Undefined when the hub cannot
+   * currently serve one, in which case the package keeps its own behaviour.
+   */
+  oauthRedirect?(): DoomOAuthRedirect | undefined;
+  /** Canonical in-process lifecycle for sessions created by this host. */
+  sessionService?: DoomHubSessionService;
+  /** Host-bound, authenticated inter-session event endpoint for this session. */
+  sessionCommunication?: DoomSessionCommunicationEndpoint;
+  /** Same-process events shared by session APIs and hub channels. */
+  directEvents?: DoomDirectEventBus;
+  /**
+   * Publishes this session's activity line to every page's rail; undefined clears it.
+   * Session mounts only. The last publisher wins.
+   */
+  publishActivity?(activity: DoomSessionActivity | undefined): void;
+  /** Trusted in-process dispatch to an explicitly selected mounted API. No browser authentication is performed here. */
+  requestApi?(mount: DoomApiMount, basePath: string, request: Request): Promise<Response>;
+  /** Present only on a session mounted by an authenticated Desktop host. */
+  computerUse?: DoomComputerUseSessionAccess;
+  /** Deliver a typed method to a channel on this exact hub mount, retaining the caller's connection identity. */
+  receiveChannel?(sessionId: string, frameType: string, payload: unknown, connectionId: string): boolean;
+  /** Host-owned replay evidence, supplied only on the global mount. Never exposed to browsers or agents. */
+  requestReceipts?: DoomRequestReceipts;
+  /** One host's exclusive media activity, shared across global and session scopes. */
+  mediaArbitration?: DoomHostMediaArbitration;
+  /** One host-wide heavy-job budget, not a separate budget for every session. */
+  executionBudget?: DoomHostExecutionBudget;
+  /** Paired agents belonging to this host only. */
+  peerAgents?: DoomPeerAgentRegistry;
+  /** Machine-owned Remote Control service, mounted only by the global core facet. */
+  remoteControl?: {
+    fetch(request: Request): Promise<Response>;
+  };
+  /**
+   * Publishes a file from this session's cwd or attachments at a short-lived tunnel URL.
+   * Session mounts only; rejects with DOOM_SHARE_FILE_REMOTE_OFF_MESSAGE while remote access is off.
+   * The host asks no consent: the caller must obtain it before passing the URL on.
+   */
+  shareFile?(path: string, label: string): Promise<DoomSharedFile>;
+  onNotice(message: string): void;
+}
+/**
+ * One running surface. The host strips the mount prefix before calling, so
+ * routes are declared relative ('/runners/:id/log') and a package never
+ * repeats where it was mounted.
+ */
+export interface DoomApiHandler {
+  fetch(request: Request): Response | Promise<Response>;
+  close(): void;
+}
+export interface DoomApi {
+  /** Segment under /api/plugins/; globally unique across loaded packages. */
+  basePath: string;
+  start(context: DoomApiContext): DoomApiHandler;
+}
+//#endregion
+//# sourceMappingURL=packageApi.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"packageApi.d.mts","names":[],"sources":["../../../src/schemas/packageApi.ts"],"mappings":";;;;iBAoBiB;EACf;EACA;;EAEA;EACA,gBAAgB;;;YAIN;qBAEC,0BAA0B;;YAG3B;EACN;;EACA;EAAoB;;EACpB;EAAkB;;;iBAGP;EACf;EACA,OAAO;EACP;EACA;EACA;EACA;;EAEA;;EAEA;;EAEA;EACA;;EAEA;;;;;;iBAOe;EACf;EACA,OAAO;EACP;EACA;EACA;;EAEA;EACA;;EAEA;;;wBAIc,iBAAiB,OAAO;EAAiB;;;YAQ7C;EACN;;EACA;EAAoB;;EACpB;EAAkB;EAAqB;;;wBAG7B,oBAAoB,mBAAmB;;qBAe1C;;qBAEA;;qBAGA;qBACA;qBACA;qBACA;YAMD;YACA;EACN;EAAmB;;EACnB;EAAoB;EAAkB,QAAQ;;;wBAGpC,kBAAkB,SAAS,UAAU;;;;;;;;;;iBA0BpC;;WAEN;;;;;EAKT,QAAQ,eAAe,qBAAqB;;EAE5C,KAAK,eAAe,qBAAqB;IAAU;IAAc;;;EAEjE,OAAO;;;iBAIQ;EACf;EACA;EACA;;iBAGe,2BAA2B;EAC1C;EACA;EACA;EACA;;iBAGe,sCAAsC;;EAErD;EACA;EACA;;YAGU;EACN;EAAkB;;EAClB;EAAkB,SAAS;;EAC3B;EAAkB,SAAS;;;iBAGhB;EACf,QAAQ,SAAS,gCAAgC,QAAQ;EACzD,OAAO,KAAK,wBAAwB,QAAQ;EAC5C,OACE,SAAS;IAA0B;IAAe;MACjD,QAAQ;;;iBAII;;EAEf,eAAe,cAAc;;;iBAId;EACf,QAAQ,SAAS,cAAc,QAAQ;EACvC,eAAe;IAAW;IAAiB;IAAgB;;;;iBAI5C;EACf,SAAS;EACT,UAAU;;;iBAIK;EACf,SAAS,mBAAmB;IAAS,MAAM,SAAS,UAAU,QAAQ;KAAa;EACnF,IAAI;IAAsB,MAAM,SAAS,UAAU,QAAQ;IAAW;;;;qBAI3D;;;;;iBAOI;;EAEf;EACA;EACA;EACA;;EAEA;EACA;;EAEA;;;iBAIe;EACf,OAAO;;EAEP;;;;;EAKA;;EAEA,iBAAiB;;EAEjB;;EAEA;;EAEA;;EAEA,cAAc,SAAS;;EAEvB;;EAEA;;;;;EAKA,mBAAmB;;EAEnB,oBACE,uBACC,QAAQ,sCAAsC;;EAEjD;IAA4B;IAAY;IAAc;IAAc;;;EAEpE;;;;;EAKA,kBAAkB;;EAElB,iBAAiB;;EAEjB,uBAAuB;;EAEvB,eAAe;;;;;EAKf,iBAAiB,UAAU;;EAE3B,YAAY,OAAO,cAAc,kBAAkB,SAAS,UAAU,QAAQ;;EAE9E,cAAc;;EAEd,gBAAgB,mBAAmB,mBAAmB,kBAAkB;;EAExE,kBAAkB;;EAElB,mBAAmB;;EAEnB,kBAAkB;;EAElB,aAAa;;EAEb;IAAkB,MAAM,SAAS,UAAU,QAAQ;;;;;;;EAMnD,WAAW,cAAc,gBAAgB,QAAQ;EACjD,SAAS;;;;;;;iBAQM;EACf,MAAM,SAAS,UAAU,WAAW,QAAQ;EAC5C;;iBAGe;;EAEf;EACA,MAAM,SAAS,iBAAiB"}

package/dist/src/schemas/packageApi.mjs

@@ -0,0 +1,66 @@
+//#region src/schemas/packageApi.ts
+const DOOM_API_SCOPES = [
+	"global",
+	"workspace",
+	"session"
+];
+/** Canonical public prefix. Scope selection never falls through to a parent. */
+function doomApiMountPath(mount) {
+	if (mount.scope === "global") return "/api/plugins";
+	if (mount.scope === "workspace") return `/api/workspaces/${encodeURIComponent(mount.workspaceId)}/plugins`;
+	if (!mount.workspaceId) throw new Error("A session API path requires its workspace identity.");
+	return `/api/workspaces/${encodeURIComponent(mount.workspaceId)}/sessions/${encodeURIComponent(mount.sessionId)}/plugins`;
+}
+/** Only canonical resource paths may select a protocol listener. */
+function parseDoomSocketPath(pathname) {
+	if (pathname === "/api/ws") return { scope: "global" };
+	const match = /^\/api\/workspaces\/([^/]+)(?:\/sessions\/([^/]+))?\/ws$/u.exec(pathname);
+	if (!match) return void 0;
+	try {
+		const workspaceId = decodeURIComponent(match[1]);
+		return match[2] === void 0 ? {
+			scope: "workspace",
+			workspaceId
+		} : {
+			scope: "session",
+			workspaceId,
+			sessionId: decodeURIComponent(match[2])
+		};
+	} catch {
+		return;
+	}
+}
+/** The segment an API is mounted under, below this prefix. */
+const DOOM_API_ROUTE_PREFIX = "/api/plugins";
+/** Selects the hub API bundle that owns the named cockpit session. */
+const DOOM_HUB_API_SESSION_QUERY_PARAM = "hubSession";
+/** Trusted caller headers written only by the cockpit-to-session proxy. */
+const DOOM_API_CALLER_LOCALITY_HEADER = "x-po-api-caller-locality";
+const DOOM_API_CALLER_DEVICE_ID_HEADER = "x-po-api-caller-device-id";
+const DOOM_API_CALLER_STEP_UP_HEADER = "x-po-api-caller-step-up";
+const DOOM_API_CALLER_HEADERS = [
+	DOOM_API_CALLER_LOCALITY_HEADER,
+	DOOM_API_CALLER_DEVICE_ID_HEADER,
+	DOOM_API_CALLER_STEP_UP_HEADER
+];
+/** Reads the proxy-authenticated caller identity, rejecting partial or contradictory stamps. */
+function doomApiCallerFrom(headers) {
+	const locality = headers.get(DOOM_API_CALLER_LOCALITY_HEADER);
+	const deviceId = headers.get(DOOM_API_CALLER_DEVICE_ID_HEADER);
+	const stepUp = headers.get(DOOM_API_CALLER_STEP_UP_HEADER);
+	if (locality === "local") return deviceId === null && stepUp === "not-required" ? {
+		locality,
+		stepUp
+	} : void 0;
+	if (locality === "remote" && deviceId !== null && deviceId !== "" && (stepUp === "not-required" || stepUp === "verified" || stepUp === "unavailable")) return {
+		locality,
+		deviceId,
+		stepUp
+	};
+}
+/** Why shareFile rejects while the host has no public tunnel origin. */
+const DOOM_SHARE_FILE_REMOTE_OFF_MESSAGE = "Remote access is off, so Po cannot share files with remote MCP servers. Turn it on and retry.";
+//#endregion
+export { DOOM_API_CALLER_DEVICE_ID_HEADER, DOOM_API_CALLER_HEADERS, DOOM_API_CALLER_LOCALITY_HEADER, DOOM_API_CALLER_STEP_UP_HEADER, DOOM_API_ROUTE_PREFIX, DOOM_API_SCOPES, DOOM_HUB_API_SESSION_QUERY_PARAM, DOOM_SHARE_FILE_REMOTE_OFF_MESSAGE, doomApiCallerFrom, doomApiMountPath, parseDoomSocketPath };
+
+//# sourceMappingURL=packageApi.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"packageApi.mjs","names":[],"sources":["../../../src/schemas/packageApi.ts"],"sourcesContent":["/**\n * The HTTP surface a package offers its host.\n *\n * A server facet registers one with its host. The host mounts it under the API\n * route prefix, and the package writes routes relative to that mount.\n *\n * The handler is a plain fetch callback so no host and no package is committed\n * to one HTTP framework; a Hono app satisfies it through `app.fetch`.\n */\n\nimport type {\n  DoomComputerUseSessionAccess,\n  DoomDirectEventBus,\n  DoomHubSessionService,\n  DoomSessionCommunicationEndpoint,\n  DoomSessionActivity,\n  DoomSessionContext,\n} from './hubChannel';\nimport type { DoomMcpProjection } from './mcpProjection';\n/** The host-owned sync view a repository-scoped package API may inspect. */\nexport interface DoomRepositorySyncView {\n  fresh: boolean;\n  reasons: string[];\n  /** True while a background sync that may prepare what `reasons` names is running. */\n  syncing?: boolean;\n  mcpProjection?: DoomMcpProjection;\n}\n\n/** Where an API runs: inside one session's server, or in the machine-wide hub. */\nexport type DoomApiScope = 'global' | 'workspace' | 'session';\n\nexport const DOOM_API_SCOPES: readonly DoomApiScope[] = ['global', 'workspace', 'session'];\n\n/** Identity of an independently mounted plugin host. */\nexport type DoomApiMount =\n  | { scope: 'global' }\n  | { scope: 'workspace'; workspaceId: string }\n  | { scope: 'session'; sessionId: string };\n\n/** Immutable browser contribution generation paired with a server mount. */\nexport interface DoomWebComposition {\n  id: string;\n  scope: DoomApiScope;\n  revision: number;\n  manifestUrl: string;\n  rawAssetBaseUrl: string;\n  verifiedAssetBaseUrl: string;\n  /** `[slot, entry]` for each of this mount's plugin copies, the entry an absolute path below the asset prefixes. */\n  pluginEntries: [string, string][];\n  /** Every signed file this mount's slots can load, absolute below the asset prefixes. */\n  assetPaths: string[];\n  /** Per-plugin stylesheets of this mount's plugins only, so other mounts' classes never apply here. */\n  stylePaths: string[];\n  channels: string[];\n  /** The slots resolved for this mount; the shared build may hold more. */\n  plugins: string[];\n}\n\n/**\n * Immutable native contribution generation paired with a server mount. One signed CommonJS module at\n * `entryPath`, served through the same immutable plugin routes as web compositions.\n */\nexport interface DoomNativeComposition {\n  id: string;\n  scope: DoomApiScope;\n  revision: number;\n  manifestUrl: string;\n  rawAssetBaseUrl: string;\n  /** Always `/composition.js`. */\n  entryPath: string;\n  channels: string[];\n  /** The `poNative.pluginId` values resolved for this mount; the shell installs only these. */\n  plugins: string[];\n}\n\n/** Canonical public prefix. Scope selection never falls through to a parent. */\nexport function doomApiMountPath(mount: DoomApiMount & { workspaceId?: string }): string {\n  if (mount.scope === 'global') return '/api/plugins';\n  if (mount.scope === 'workspace') return `/api/workspaces/${encodeURIComponent(mount.workspaceId)}/plugins`;\n  if (!mount.workspaceId) throw new Error('A session API path requires its workspace identity.');\n  return `/api/workspaces/${encodeURIComponent(mount.workspaceId)}/sessions/${encodeURIComponent(mount.sessionId)}/plugins`;\n}\n\n/** Scope addressed by a public WebSocket upgrade. */\nexport type DoomSocketMount =\n  | { scope: 'global' }\n  | { scope: 'workspace'; workspaceId: string }\n  | { scope: 'session'; workspaceId: string; sessionId: string };\n\n/** Only canonical resource paths may select a protocol listener. */\nexport function parseDoomSocketPath(pathname: string): DoomSocketMount | undefined {\n  if (pathname === '/api/ws') return { scope: 'global' };\n  const match = /^\\/api\\/workspaces\\/([^/]+)(?:\\/sessions\\/([^/]+))?\\/ws$/u.exec(pathname);\n  if (!match) return undefined;\n  try {\n    const workspaceId = decodeURIComponent(match[1]);\n    return match[2] === undefined\n      ? { scope: 'workspace', workspaceId }\n      : { scope: 'session', workspaceId, sessionId: decodeURIComponent(match[2]) };\n  } catch {\n    return undefined;\n  }\n}\n\n/** The segment an API is mounted under, below this prefix. */\nexport const DOOM_API_ROUTE_PREFIX = '/api/plugins';\n/** Selects the hub API bundle that owns the named cockpit session. */\nexport const DOOM_HUB_API_SESSION_QUERY_PARAM = 'hubSession';\n\n/** Trusted caller headers written only by the cockpit-to-session proxy. */\nexport const DOOM_API_CALLER_LOCALITY_HEADER = 'x-po-api-caller-locality';\nexport const DOOM_API_CALLER_DEVICE_ID_HEADER = 'x-po-api-caller-device-id';\nexport const DOOM_API_CALLER_STEP_UP_HEADER = 'x-po-api-caller-step-up';\nexport const DOOM_API_CALLER_HEADERS = [\n  DOOM_API_CALLER_LOCALITY_HEADER,\n  DOOM_API_CALLER_DEVICE_ID_HEADER,\n  DOOM_API_CALLER_STEP_UP_HEADER,\n] as const;\n\nexport type DoomApiCallerStepUp = 'not-required' | 'verified' | 'unavailable';\nexport type DoomApiCaller =\n  | { locality: 'local'; stepUp: 'not-required' }\n  | { locality: 'remote'; deviceId: string; stepUp: DoomApiCallerStepUp };\n\n/** Reads the proxy-authenticated caller identity, rejecting partial or contradictory stamps. */\nexport function doomApiCallerFrom(headers: Headers): DoomApiCaller | undefined {\n  const locality = headers.get(DOOM_API_CALLER_LOCALITY_HEADER);\n  const deviceId = headers.get(DOOM_API_CALLER_DEVICE_ID_HEADER);\n  const stepUp = headers.get(DOOM_API_CALLER_STEP_UP_HEADER);\n  if (locality === 'local') {\n    return deviceId === null && stepUp === 'not-required' ? { locality, stepUp } : undefined;\n  }\n  if (\n    locality === 'remote' &&\n    deviceId !== null &&\n    deviceId !== '' &&\n    (stepUp === 'not-required' || stepUp === 'verified' || stepUp === 'unavailable')\n  ) {\n    return { locality, deviceId, stepUp };\n  }\n  return undefined;\n}\n/**\n * A browser-reachable OAuth redirect the host serves on its own listener.\n *\n * A package brokering third-party OAuth cannot use a loopback redirect when the\n * operator's browser is on another machine: `127.0.0.1` resolves to whichever\n * machine the browser runs on. The host owns a listener that is reachable from\n * wherever the cockpit is being used, so it lends that instead of the package\n * opening a port of its own.\n */\nexport interface DoomOAuthRedirect {\n  /** Absolute URL to register as the redirect target, already origin-correct. */\n  readonly redirectUri: string;\n  /**\n   * Accept redirects carrying this state. Must complete before the\n   * authorization URL is surfaced, or the redirect races its own reservation.\n   */\n  reserve(state: string, timeoutMs?: number): Promise<void>;\n  /** Resolves once the redirect carrying this state arrives. */\n  wait(state: string, timeoutMs?: number): Promise<{ code: string; state: string }>;\n  /** Drops a reservation whose flow ended without a redirect. */\n  cancel(state: string): void;\n}\n\n/** An exact, host-owned receipt address. Provider IDs are not event cursor positions. */\nexport interface DoomRequestReceiptKey {\n  namespace: string;\n  activationId: string;\n  requestId: string;\n}\n\nexport interface DoomRequestReceipt extends DoomRequestReceiptKey {\n  fingerprint: string;\n  destination: string;\n  transactionId: string;\n  outcome: 'reserved' | 'admitted' | 'rejected' | 'uncertain';\n}\n\nexport interface DoomRequestReceiptReservation extends DoomRequestReceiptKey {\n  /** Lowercase SHA-256 of the authoritative request text, never the full transcript. */\n  fingerprint: string;\n  destination: string;\n  transactionId: string;\n}\n\nexport type DoomRequestReceiptReserveResult =\n  | { kind: 'reserved'; token: string }\n  | { kind: 'existing'; receipt: DoomRequestReceipt }\n  | { kind: 'conflict'; receipt: DoomRequestReceipt };\n\n/** A global-only receipt capability. A reservation is not an execution receipt. */\nexport interface DoomRequestReceipts {\n  reserve(request: DoomRequestReceiptReservation): Promise<DoomRequestReceiptReserveResult>;\n  lookup(key: DoomRequestReceiptKey): Promise<DoomRequestReceipt | undefined>;\n  finish(\n    request: DoomRequestReceiptKey & { token: string; outcome: 'admitted' | 'rejected' | 'uncertain' },\n  ): Promise<DoomRequestReceipt>;\n}\n\n/** Permit returned for expensive local work. Calling it releases the slot. */\nexport interface DoomHostExecutionPermit {\n  (): void;\n  attachProcess?(pid: number): Promise<void>;\n}\n\n/** Host-wide admission for expensive local work. Release only after the owned process exits. */\nexport interface DoomHostExecutionBudget {\n  acquire(signal?: AbortSignal): Promise<DoomHostExecutionPermit>;\n  getSnapshot(): Readonly<{ running: number; queued: number; limit: number }>;\n}\n\n/** Synchronous host-owned exclusion across media APIs mounted at different scopes. */\nexport interface DoomHostMediaArbitration {\n  register(busy: () => boolean): () => void;\n  available(busy: () => boolean): boolean;\n}\n\n/** One host's paired agent registrations, shared across its global and session mounts. */\nexport interface DoomPeerAgentRegistry {\n  register(sessionId: string, agent: { fetch(request: Request): Promise<Response> }, hubToken: string): () => void;\n  get(sessionId: string): { fetch(request: Request): Promise<Response>; hubToken: string } | undefined;\n}\n\n/** Why shareFile rejects while the host has no public tunnel origin. */\nexport const DOOM_SHARE_FILE_REMOTE_OFF_MESSAGE =\n  'Remote access is off, so Po cannot share files with remote MCP servers. Turn it on and retry.';\n\n/**\n * A file published at a short-lived public tunnel URL: 10 minutes, 3 downloads, and gone\n * when the tunnel revision changes. Call revoke as soon as the consumer is done with it.\n */\nexport interface DoomSharedFile {\n  /** Bearer link; never log or persist it. */\n  url: string;\n  fileName: string;\n  mimeType: string;\n  size: number;\n  /** Expiry as epoch milliseconds. */\n  expiresAt: number;\n  maxDownloads: number;\n  /** Idempotent. */\n  revoke(): void;\n}\n\n/** What the host tells an API about itself when it starts. */\nexport interface DoomApiContext {\n  scope: DoomApiScope;\n  /** Stable, opaque workspace id, shared by every session and member checkout of the workspace. */\n  workspaceId?: string;\n  /**\n   * The admitted workspace root for a workspace mount. For a session mount it is the checkout\n   * the session runs in; read sessionContext for both roots. Absent from global mounts.\n   */\n  workspaceRoot?: string;\n  /** The session's baseline context; present on session mounts whose host knows its workspace. */\n  sessionContext?: DoomSessionContext;\n  /** Explicit host home, never selected by a remote request. */\n  homeDirectory?: string;\n  /** The session this host serves; absent for a hub-scoped API. */\n  sessionId?: string;\n  /** The session's working directory; absent for a hub-scoped API. */\n  cwd?: string;\n  /** Session environment admitted by the server, never supplied by remote clients. */\n  environment?: Readonly<Record<string, string | undefined>>;\n  /** Shared only with child processes in this session, never with remote API clients. */\n  internalToken?: string;\n  /** Shared only with the cockpit hub for privileged cross-session coordination. */\n  hubToken?: string;\n  /**\n   * Resolves a hub-issued opaque repository id to an admitted canonical root.\n   * Hub APIs must never accept a browser-supplied filesystem path instead.\n   */\n  resolveRepository?(repositoryId: string): string | undefined;\n  /** Reads the admitted repository's sync projection without exposing its state path. */\n  readRepositorySync?(\n    repositoryId: string,\n  ): Promise<DoomRepositorySyncView | undefined> | DoomRepositorySyncView | undefined;\n  /** Admitted workspaces available to this mount. */\n  repositories?(): readonly { id: string; name: string; path: string; active: boolean }[];\n  /** Publish a successful config write to the owning mount's refresh lifecycle. */\n  configurationChanged?(): void;\n  /**\n   * Borrows the hub's OAuth redirect surface. Undefined when the hub cannot\n   * currently serve one, in which case the package keeps its own behaviour.\n   */\n  oauthRedirect?(): DoomOAuthRedirect | undefined;\n  /** Canonical in-process lifecycle for sessions created by this host. */\n  sessionService?: DoomHubSessionService;\n  /** Host-bound, authenticated inter-session event endpoint for this session. */\n  sessionCommunication?: DoomSessionCommunicationEndpoint;\n  /** Same-process events shared by session APIs and hub channels. */\n  directEvents?: DoomDirectEventBus;\n  /**\n   * Publishes this session's activity line to every page's rail; undefined clears it.\n   * Session mounts only. The last publisher wins.\n   */\n  publishActivity?(activity: DoomSessionActivity | undefined): void;\n  /** Trusted in-process dispatch to an explicitly selected mounted API. No browser authentication is performed here. */\n  requestApi?(mount: DoomApiMount, basePath: string, request: Request): Promise<Response>;\n  /** Present only on a session mounted by an authenticated Desktop host. */\n  computerUse?: DoomComputerUseSessionAccess;\n  /** Deliver a typed method to a channel on this exact hub mount, retaining the caller's connection identity. */\n  receiveChannel?(sessionId: string, frameType: string, payload: unknown, connectionId: string): boolean;\n  /** Host-owned replay evidence, supplied only on the global mount. Never exposed to browsers or agents. */\n  requestReceipts?: DoomRequestReceipts;\n  /** One host's exclusive media activity, shared across global and session scopes. */\n  mediaArbitration?: DoomHostMediaArbitration;\n  /** One host-wide heavy-job budget, not a separate budget for every session. */\n  executionBudget?: DoomHostExecutionBudget;\n  /** Paired agents belonging to this host only. */\n  peerAgents?: DoomPeerAgentRegistry;\n  /** Machine-owned Remote Control service, mounted only by the global core facet. */\n  remoteControl?: { fetch(request: Request): Promise<Response> };\n  /**\n   * Publishes a file from this session's cwd or attachments at a short-lived tunnel URL.\n   * Session mounts only; rejects with DOOM_SHARE_FILE_REMOTE_OFF_MESSAGE while remote access is off.\n   * The host asks no consent: the caller must obtain it before passing the URL on.\n   */\n  shareFile?(path: string, label: string): Promise<DoomSharedFile>;\n  onNotice(message: string): void;\n}\n\n/**\n * One running surface. The host strips the mount prefix before calling, so\n * routes are declared relative ('/runners/:id/log') and a package never\n * repeats where it was mounted.\n */\nexport interface DoomApiHandler {\n  fetch(request: Request): Response | Promise<Response>;\n  close(): void;\n}\n\nexport interface DoomApi {\n  /** Segment under /api/plugins/; globally unique across loaded packages. */\n  basePath: string;\n  start(context: DoomApiContext): DoomApiHandler;\n}\n"],"mappings":";AA+BA,MAAa,kBAA2C;CAAC;CAAU;CAAa;AAAS;;AA6CzF,SAAgB,iBAAiB,OAAwD;CACvF,IAAI,MAAM,UAAU,UAAU,OAAO;CACrC,IAAI,MAAM,UAAU,aAAa,OAAO,mBAAmB,mBAAmB,MAAM,WAAW,EAAE;CACjG,IAAI,CAAC,MAAM,aAAa,MAAM,IAAI,MAAM,qDAAqD;CAC7F,OAAO,mBAAmB,mBAAmB,MAAM,WAAW,EAAE,YAAY,mBAAmB,MAAM,SAAS,EAAE;AAClH;;AASA,SAAgB,oBAAoB,UAA+C;CACjF,IAAI,aAAa,WAAW,OAAO,EAAE,OAAO,SAAS;CACrD,MAAM,QAAQ,4DAA4D,KAAK,QAAQ;CACvF,IAAI,CAAC,OAAO,OAAO,KAAA;CACnB,IAAI;EACF,MAAM,cAAc,mBAAmB,MAAM,EAAE;EAC/C,OAAO,MAAM,OAAO,KAAA,IAChB;GAAE,OAAO;GAAa;EAAY,IAClC;GAAE,OAAO;GAAW;GAAa,WAAW,mBAAmB,MAAM,EAAE;EAAE;CAC/E,QAAQ;EACN;CACF;AACF;;AAGA,MAAa,wBAAwB;;AAErC,MAAa,mCAAmC;;AAGhD,MAAa,kCAAkC;AAC/C,MAAa,mCAAmC;AAChD,MAAa,iCAAiC;AAC9C,MAAa,0BAA0B;CACrC;CACA;CACA;AACF;;AAQA,SAAgB,kBAAkB,SAA6C;CAC7E,MAAM,WAAW,QAAQ,IAAI,+BAA+B;CAC5D,MAAM,WAAW,QAAQ,IAAI,gCAAgC;CAC7D,MAAM,SAAS,QAAQ,IAAI,8BAA8B;CACzD,IAAI,aAAa,SACf,OAAO,aAAa,QAAQ,WAAW,iBAAiB;EAAE;EAAU;CAAO,IAAI,KAAA;CAEjF,IACE,aAAa,YACb,aAAa,QACb,aAAa,OACZ,WAAW,kBAAkB,WAAW,cAAc,WAAW,gBAElE,OAAO;EAAE;EAAU;EAAU;CAAO;AAGxC;;AAoFA,MAAa,qCACX"}

package/dist/src/schemas/pluginContributions.cjs

@@ -0,0 +1,19 @@
+//#region src/schemas/pluginContributions.ts
+/** Preserve schema inference at the declaration, before heterogeneous composition. */
+function defineTool(tool) {
+	return {
+		...tool,
+		kind: "tool"
+	};
+}
+function defineCommand(command) {
+	return {
+		...command,
+		kind: "command"
+	};
+}
+//#endregion
+exports.defineCommand = defineCommand;
+exports.defineTool = defineTool;
+
+//# sourceMappingURL=pluginContributions.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pluginContributions.cjs","names":[],"sources":["../../../src/schemas/pluginContributions.ts"],"sourcesContent":["import type { Static, TSchema } from 'typebox';\n\nimport type { DoomNotificationRequest } from './notification';\n\n/** Capabilities available to portable commands on both agent hosts. */\nexport interface DoomPluginExecution {\n  readonly cwd: string;\n  readonly signal?: AbortSignal;\n  notify(request: DoomNotificationRequest): void | Promise<void>;\n}\n\nexport interface DoomPluginToolResult {\n  content: ({ type: 'text'; text: string } | { type: 'image'; data: string; mimeType: string })[];\n  details?: unknown;\n  isError?: boolean;\n}\n\nexport interface DoomPluginToolExecution extends DoomPluginExecution {\n  readonly toolCallId: string;\n  update(result: DoomPluginToolResult): void;\n}\n\nexport interface DoomPluginTool<TParameters extends TSchema = TSchema> {\n  readonly kind: 'tool';\n  readonly when?: {\n    readonly state?: Readonly<Record<string, string>>;\n    attribution?: { kind: 'minor' | 'domain'; mode: string; label?: string };\n    readonly domain?: string;\n  };\n  readonly name: string;\n  readonly label?: string;\n  readonly description: string;\n  readonly parameters: TParameters;\n  readonly promptSnippet?: string;\n  readonly promptGuidelines?: readonly string[];\n  readonly executionMode?: 'parallel' | 'serial';\n  execute(input: Static<TParameters>, execution: DoomPluginToolExecution): Promise<DoomPluginToolResult>;\n}\n\nexport interface DoomPluginCommand {\n  readonly kind: 'command';\n  readonly name: string;\n  readonly description: string;\n  execute(args: string, execution: DoomPluginExecution): void | Promise<void>;\n}\n\n/** Preserve schema inference at the declaration, before heterogeneous composition. */\nexport function defineTool<TParameters extends TSchema>(\n  tool: Omit<DoomPluginTool<TParameters>, 'kind'>,\n): DoomPluginTool<TParameters> {\n  return { ...tool, kind: 'tool' };\n}\n\nexport function defineCommand(command: Omit<DoomPluginCommand, 'kind'>): DoomPluginCommand {\n  return { ...command, kind: 'command' };\n}\n"],"mappings":";;AA+CA,SAAgB,WACd,MAC6B;CAC7B,OAAO;EAAE,GAAG;EAAM,MAAM;CAAO;AACjC;AAEA,SAAgB,cAAc,SAA6D;CACzF,OAAO;EAAE,GAAG;EAAS,MAAM;CAAU;AACvC"}

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

@@ -0,0 +1,56 @@
+import { DoomNotificationRequest } from "./notification.mjs";
+import { Static, TSchema } from "typebox";
+//#region src/schemas/pluginContributions.d.ts
+/** Capabilities available to portable commands on both agent hosts. */
+export interface DoomPluginExecution {
+  readonly cwd: string;
+  readonly signal?: AbortSignal;
+  notify(request: DoomNotificationRequest): void | Promise<void>;
+}
+export interface DoomPluginToolResult {
+  content: ({
+    type: 'text';
+    text: string;
+  } | {
+    type: 'image';
+    data: string;
+    mimeType: string;
+  })[];
+  details?: unknown;
+  isError?: boolean;
+}
+export interface DoomPluginToolExecution extends DoomPluginExecution {
+  readonly toolCallId: string;
+  update(result: DoomPluginToolResult): void;
+}
+export interface DoomPluginTool<TParameters extends TSchema = TSchema> {
+  readonly kind: 'tool';
+  readonly when?: {
+    readonly state?: Readonly<Record<string, string>>;
+    attribution?: {
+      kind: 'minor' | 'domain';
+      mode: string;
+      label?: string;
+    };
+    readonly domain?: string;
+  };
+  readonly name: string;
+  readonly label?: string;
+  readonly description: string;
+  readonly parameters: TParameters;
+  readonly promptSnippet?: string;
+  readonly promptGuidelines?: readonly string[];
+  readonly executionMode?: 'parallel' | 'serial';
+  execute(input: Static<TParameters>, execution: DoomPluginToolExecution): Promise<DoomPluginToolResult>;
+}
+export interface DoomPluginCommand {
+  readonly kind: 'command';
+  readonly name: string;
+  readonly description: string;
+  execute(args: string, execution: DoomPluginExecution): void | Promise<void>;
+}
+/** Preserve schema inference at the declaration, before heterogeneous composition. */
+export declare function defineTool<TParameters extends TSchema>(tool: Omit<DoomPluginTool<TParameters>, 'kind'>): DoomPluginTool<TParameters>;
+export declare function defineCommand(command: Omit<DoomPluginCommand, 'kind'>): DoomPluginCommand;
+//#endregion
+//# sourceMappingURL=pluginContributions.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pluginContributions.d.mts","names":[],"sources":["../../../src/schemas/pluginContributions.ts"],"mappings":";;;;iBAKiB;WACN;WACA,SAAS;EAClB,OAAO,SAAS,iCAAiC;;iBAGlC;EACf;IAAY;IAAc;;IAAmB;IAAe;IAAc;;EAC1E;EACA;;iBAGe,gCAAgC;WACtC;EACT,OAAO,QAAQ;;iBAGA,eAAe,oBAAoB,UAAU;WACnD;WACA;aACE,QAAQ,SAAS;IAC1B;MAAgB;MAA0B;MAAc;;aAC/C;;WAEF;WACA;WACA;WACA,YAAY;WACZ;WACA;WACA;EACT,QAAQ,OAAO,OAAO,cAAc,WAAW,0BAA0B,QAAQ;;iBAGlE;WACN;WACA;WACA;EACT,QAAQ,cAAc,WAAW,6BAA6B;;;wBAIhD,WAAW,oBAAoB,SAC7C,MAAM,KAAK,eAAe,wBACzB,eAAe;wBAIF,cAAc,SAAS,KAAK,6BAA6B"}

package/dist/src/schemas/pluginContributions.mjs

@@ -0,0 +1,18 @@
+//#region src/schemas/pluginContributions.ts
+/** Preserve schema inference at the declaration, before heterogeneous composition. */
+function defineTool(tool) {
+	return {
+		...tool,
+		kind: "tool"
+	};
+}
+function defineCommand(command) {
+	return {
+		...command,
+		kind: "command"
+	};
+}
+//#endregion
+export { defineCommand, defineTool };
+
+//# sourceMappingURL=pluginContributions.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pluginContributions.mjs","names":[],"sources":["../../../src/schemas/pluginContributions.ts"],"sourcesContent":["import type { Static, TSchema } from 'typebox';\n\nimport type { DoomNotificationRequest } from './notification';\n\n/** Capabilities available to portable commands on both agent hosts. */\nexport interface DoomPluginExecution {\n  readonly cwd: string;\n  readonly signal?: AbortSignal;\n  notify(request: DoomNotificationRequest): void | Promise<void>;\n}\n\nexport interface DoomPluginToolResult {\n  content: ({ type: 'text'; text: string } | { type: 'image'; data: string; mimeType: string })[];\n  details?: unknown;\n  isError?: boolean;\n}\n\nexport interface DoomPluginToolExecution extends DoomPluginExecution {\n  readonly toolCallId: string;\n  update(result: DoomPluginToolResult): void;\n}\n\nexport interface DoomPluginTool<TParameters extends TSchema = TSchema> {\n  readonly kind: 'tool';\n  readonly when?: {\n    readonly state?: Readonly<Record<string, string>>;\n    attribution?: { kind: 'minor' | 'domain'; mode: string; label?: string };\n    readonly domain?: string;\n  };\n  readonly name: string;\n  readonly label?: string;\n  readonly description: string;\n  readonly parameters: TParameters;\n  readonly promptSnippet?: string;\n  readonly promptGuidelines?: readonly string[];\n  readonly executionMode?: 'parallel' | 'serial';\n  execute(input: Static<TParameters>, execution: DoomPluginToolExecution): Promise<DoomPluginToolResult>;\n}\n\nexport interface DoomPluginCommand {\n  readonly kind: 'command';\n  readonly name: string;\n  readonly description: string;\n  execute(args: string, execution: DoomPluginExecution): void | Promise<void>;\n}\n\n/** Preserve schema inference at the declaration, before heterogeneous composition. */\nexport function defineTool<TParameters extends TSchema>(\n  tool: Omit<DoomPluginTool<TParameters>, 'kind'>,\n): DoomPluginTool<TParameters> {\n  return { ...tool, kind: 'tool' };\n}\n\nexport function defineCommand(command: Omit<DoomPluginCommand, 'kind'>): DoomPluginCommand {\n  return { ...command, kind: 'command' };\n}\n"],"mappings":";;AA+CA,SAAgB,WACd,MAC6B;CAC7B,OAAO;EAAE,GAAG;EAAM,MAAM;CAAO;AACjC;AAEA,SAAgB,cAAc,SAA6D;CACzF,OAAO;EAAE,GAAG;EAAS,MAAM;CAAU;AACvC"}