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

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

@@ -1 +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"}
+{"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 plugin 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  PoComputerUseSessionAccess,\n  PoDirectEventBus,\n  PoHubSessionService,\n  PoSessionCommunicationEndpoint,\n  PoSessionActivity,\n  PoSessionContext,\n} from './hubChannel';\nimport type { PoMcpProjection } from './mcpProjection';\nimport type { PoSessionStorageService } from './platform';\n/** The host-owned sync view a repository-scoped package API may inspect. */\nexport interface PoRepositorySyncView {\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?: PoMcpProjection;\n}\n\n/** Where an API runs: inside one session's server, or in the machine-wide hub. */\nexport type PoApiScope = 'global' | 'workspace' | 'session';\n\nexport const PO_API_SCOPES: readonly PoApiScope[] = ['global', 'workspace', 'session'];\n\n/** Identity of an independently mounted plugin host. */\nexport type PoApiMount =\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 PoWebComposition {\n  id: string;\n  scope: PoApiScope;\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 PoNativeComposition {\n  id: string;\n  scope: PoApiScope;\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 poApiMountPath(mount: PoApiMount & { 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 PoSocketMount =\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 parsePoSocketPath(pathname: string): PoSocketMount | 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 PO_API_ROUTE_PREFIX = '/api/plugins';\n/** Selects the hub API bundle that owns the named cockpit session. */\nexport const PO_HUB_API_SESSION_QUERY_PARAM = 'hubSession';\n\n/** Trusted caller headers written only by the cockpit-to-session proxy. */\nexport const PO_API_CALLER_LOCALITY_HEADER = 'x-po-api-caller-locality';\nexport const PO_API_CALLER_DEVICE_ID_HEADER = 'x-po-api-caller-device-id';\nexport const PO_API_CALLER_STEP_UP_HEADER = 'x-po-api-caller-step-up';\nexport const PO_API_CALLER_HEADERS = [\n  PO_API_CALLER_LOCALITY_HEADER,\n  PO_API_CALLER_DEVICE_ID_HEADER,\n  PO_API_CALLER_STEP_UP_HEADER,\n] as const;\n\nexport type PoApiCallerStepUp = 'not-required' | 'verified' | 'unavailable';\nexport type PoApiCaller =\n  | { locality: 'local'; stepUp: 'not-required' }\n  | { locality: 'remote'; deviceId: string; stepUp: PoApiCallerStepUp };\n\n/** Reads the proxy-authenticated caller identity, rejecting partial or contradictory stamps. */\nexport function poApiCallerFrom(headers: Headers): PoApiCaller | undefined {\n  const locality = headers.get(PO_API_CALLER_LOCALITY_HEADER);\n  const deviceId = headers.get(PO_API_CALLER_DEVICE_ID_HEADER);\n  const stepUp = headers.get(PO_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 PoOAuthRedirect {\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 PoRequestReceiptKey {\n  namespace: string;\n  activationId: string;\n  requestId: string;\n}\n\nexport interface PoRequestReceipt extends PoRequestReceiptKey {\n  fingerprint: string;\n  destination: string;\n  transactionId: string;\n  outcome: 'reserved' | 'admitted' | 'rejected' | 'uncertain';\n}\n\nexport interface PoRequestReceiptReservation extends PoRequestReceiptKey {\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 PoRequestReceiptReserveResult =\n  | { kind: 'reserved'; token: string }\n  | { kind: 'existing'; receipt: PoRequestReceipt }\n  | { kind: 'conflict'; receipt: PoRequestReceipt };\n\n/** A global-only receipt capability. A reservation is not an execution receipt. */\nexport interface PoRequestReceipts {\n  reserve(request: PoRequestReceiptReservation): Promise<PoRequestReceiptReserveResult>;\n  lookup(key: PoRequestReceiptKey): Promise<PoRequestReceipt | undefined>;\n  finish(\n    request: PoRequestReceiptKey & { token: string; outcome: 'admitted' | 'rejected' | 'uncertain' },\n  ): Promise<PoRequestReceipt>;\n}\n\n/** Permit returned for expensive local work. Calling it releases the slot. */\nexport interface PoHostExecutionPermit {\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 PoHostExecutionBudget {\n  acquire(signal?: AbortSignal): Promise<PoHostExecutionPermit>;\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 PoHostMediaArbitration {\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 PoPeerAgentRegistry {\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/** One agent that edits files: a hub session or an in-process child run. */\nexport interface PoEditPresenceAgent {\n  /** `session:<id>` or `run:<runId>`. Unique across the host. */\n  readonly key: string;\n  /** Read when a note is rendered, so a name registered after the edit still shows. */\n  readonly label: () => string;\n  /** Hub session id other agents can reach with intercom. */\n  readonly contact: string;\n  readonly isLive: () => boolean;\n}\n\nexport interface PoEditPresenceEntry {\n  readonly agent: PoEditPresenceAgent;\n  /** `@file` tag of the bytes this agent's last successful edit or write left behind. */\n  readonly tag: string;\n  readonly at: number;\n}\n\n/**\n * Host-wide record of the last edit each live agent made to a file, keyed by realpath then agent key.\n * Owners delete their entries when they dispose, so no callback outlives its session or run.\n */\nexport type PoEditPresenceLedger = Map<string, Map<string, PoEditPresenceEntry>>;\n\n/** Why shareFile rejects while the host has no public tunnel origin. */\nexport const PO_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 PoSharedFile {\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 PoApiContext {\n  scope: PoApiScope;\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?: PoSessionContext;\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<PoRepositorySyncView | undefined> | PoRepositorySyncView | 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?(): PoOAuthRedirect | undefined;\n  /** Canonical in-process lifecycle for sessions created by this host. */\n  sessionService?: PoHubSessionService;\n  /** Trusted in-process storage capability. APIs must retain their mount's session authorization. */\n  sessionStorage?: PoSessionStorageService;\n  /** Host-bound, authenticated inter-session event endpoint for this session. */\n  sessionCommunication?: PoSessionCommunicationEndpoint;\n  /** Same-process events shared by session APIs and hub channels. */\n  directEvents?: PoDirectEventBus;\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: PoSessionActivity | undefined): void;\n  /** Trusted in-process dispatch to an explicitly selected mounted API. No browser authentication is performed here. */\n  requestApi?(mount: PoApiMount, basePath: string, request: Request): Promise<Response>;\n  /** Present only on a session mounted by an authenticated Desktop host. */\n  computerUse?: PoComputerUseSessionAccess;\n  /** Deliver a typed method to the channel serving a session this mount reaches, 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?: PoRequestReceipts;\n  /** One host's exclusive media activity, shared across global and session scopes. */\n  mediaArbitration?: PoHostMediaArbitration;\n  /** One host-wide heavy-job budget, not a separate budget for every session. */\n  executionBudget?: PoHostExecutionBudget;\n  /** One host-wide edit presence ledger, shared by every session mount. */\n  editPresence?: PoEditPresenceLedger;\n  /** Paired agents belonging to this host only. */\n  peerAgents?: PoPeerAgentRegistry;\n  /** Machine-owned Remote Control service, mounted only by Po's own global server plugin. */\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 PO_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<PoSharedFile>;\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 PoApiHandler {\n  fetch(request: Request): Response | Promise<Response>;\n  close(): void;\n}\n\nexport interface PoApi {\n  /** Segment under /api/plugins/; globally unique across loaded packages. */\n  basePath: string;\n  start(context: PoApiContext): PoApiHandler;\n}\n"],"mappings":";AAgCA,MAAa,gBAAuC;CAAC;CAAU;CAAa;AAAS;;AA6CrF,SAAgB,eAAe,OAAsD;CACnF,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,kBAAkB,UAA6C;CAC7E,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,sBAAsB;;AAEnC,MAAa,iCAAiC;;AAG9C,MAAa,gCAAgC;AAC7C,MAAa,iCAAiC;AAC9C,MAAa,+BAA+B;AAC5C,MAAa,wBAAwB;CACnC;CACA;CACA;AACF;;AAQA,SAAgB,gBAAgB,SAA2C;CACzE,MAAM,WAAW,QAAQ,IAAI,6BAA6B;CAC1D,MAAM,WAAW,QAAQ,IAAI,8BAA8B;CAC3D,MAAM,SAAS,QAAQ,IAAI,4BAA4B;CACvD,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;;AA4GA,MAAa,mCACX"}

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

@@ -1,19 +1,20 @@
-import { DoomComputerUseSessionAccess, DoomDirectEventBus, DoomHubSessionService, DoomSessionActivity, DoomSessionCommunicationEndpoint, DoomSessionContext } from "./hubChannel.mjs";
-import { DoomMcpProjection } from "./mcpProjection.mjs";
+import { PoSessionStorageService } from "./platform.mjs";
+import { PoComputerUseSessionAccess, PoDirectEventBus, PoHubSessionService, PoSessionActivity, PoSessionCommunicationEndpoint, PoSessionContext } from "./hubChannel.mjs";
+import { PoMcpProjection } from "./mcpProjection.mjs";
 //#region src/schemas/packageApi.d.ts
 /** The host-owned sync view a repository-scoped package API may inspect. */
-export interface DoomRepositorySyncView {
+export interface PoRepositorySyncView {
   fresh: boolean;
   reasons: string[];
   /** True while a background sync that may prepare what `reasons` names is running. */
   syncing?: boolean;
-  mcpProjection?: DoomMcpProjection;
+  mcpProjection?: PoMcpProjection;
 }
 /** 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[];
+export type PoApiScope = 'global' | 'workspace' | 'session';
+export declare const PO_API_SCOPES: readonly PoApiScope[];
 /** Identity of an independently mounted plugin host. */
-export type DoomApiMount = {
+export type PoApiMount = {
   scope: 'global';
 } | {
   scope: 'workspace';
@@ -23,9 +24,9 @@ export type DoomApiMount = {
   sessionId: string;
 };
 /** Immutable browser contribution generation paired with a server mount. */
-export interface DoomWebComposition {
+export interface PoWebComposition {
   id: string;
-  scope: DoomApiScope;
+  scope: PoApiScope;
   revision: number;
   manifestUrl: string;
   rawAssetBaseUrl: string;
@@ -44,9 +45,9 @@ export interface DoomWebComposition {
  * 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 {
+export interface PoNativeComposition {
   id: string;
-  scope: DoomApiScope;
+  scope: PoApiScope;
   revision: number;
   manifestUrl: string;
   rawAssetBaseUrl: string;
@@ -57,11 +58,11 @@ export interface DoomNativeComposition {
   plugins: string[];
 }
 /** Canonical public prefix. Scope selection never falls through to a parent. */
-export declare function doomApiMountPath(mount: DoomApiMount & {
+export declare function poApiMountPath(mount: PoApiMount & {
   workspaceId?: string;
 }): string;
 /** Scope addressed by a public WebSocket upgrade. */
-export type DoomSocketMount = {
+export type PoSocketMount = {
   scope: 'global';
 } | {
   scope: 'workspace';
@@ -72,27 +73,27 @@ export type DoomSocketMount = {
   sessionId: string;
 };
 /** Only canonical resource paths may select a protocol listener. */
-export declare function parseDoomSocketPath(pathname: string): DoomSocketMount | undefined;
+export declare function parsePoSocketPath(pathname: string): PoSocketMount | undefined;
 /** The segment an API is mounted under, below this prefix. */
-export declare const DOOM_API_ROUTE_PREFIX = "/api/plugins";
+export declare const PO_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";
+export declare const PO_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 = {
+export declare const PO_API_CALLER_LOCALITY_HEADER = "x-po-api-caller-locality";
+export declare const PO_API_CALLER_DEVICE_ID_HEADER = "x-po-api-caller-device-id";
+export declare const PO_API_CALLER_STEP_UP_HEADER = "x-po-api-caller-step-up";
+export declare const PO_API_CALLER_HEADERS: readonly ["x-po-api-caller-locality", "x-po-api-caller-device-id", "x-po-api-caller-step-up"];
+export type PoApiCallerStepUp = 'not-required' | 'verified' | 'unavailable';
+export type PoApiCaller = {
   locality: 'local';
   stepUp: 'not-required';
 } | {
   locality: 'remote';
   deviceId: string;
-  stepUp: DoomApiCallerStepUp;
+  stepUp: PoApiCallerStepUp;
 };
 /** Reads the proxy-authenticated caller identity, rejecting partial or contradictory stamps. */
-export declare function doomApiCallerFrom(headers: Headers): DoomApiCaller | undefined;
+export declare function poApiCallerFrom(headers: Headers): PoApiCaller | undefined;
 /**
  * A browser-reachable OAuth redirect the host serves on its own listener.
  *
@@ -102,7 +103,7 @@ export declare function doomApiCallerFrom(headers: Headers): DoomApiCaller | und
  * wherever the cockpit is being used, so it lends that instead of the package
  * opening a port of its own.
  */
-export interface DoomOAuthRedirect {
+export interface PoOAuthRedirect {
   /** Absolute URL to register as the redirect target, already origin-correct. */
   readonly redirectUri: string;
   /**
@@ -119,50 +120,50 @@ export interface DoomOAuthRedirect {
   cancel(state: string): void;
 }
 /** An exact, host-owned receipt address. Provider IDs are not event cursor positions. */
-export interface DoomRequestReceiptKey {
+export interface PoRequestReceiptKey {
   namespace: string;
   activationId: string;
   requestId: string;
 }
-export interface DoomRequestReceipt extends DoomRequestReceiptKey {
+export interface PoRequestReceipt extends PoRequestReceiptKey {
   fingerprint: string;
   destination: string;
   transactionId: string;
   outcome: 'reserved' | 'admitted' | 'rejected' | 'uncertain';
 }
-export interface DoomRequestReceiptReservation extends DoomRequestReceiptKey {
+export interface PoRequestReceiptReservation extends PoRequestReceiptKey {
   /** Lowercase SHA-256 of the authoritative request text, never the full transcript. */
   fingerprint: string;
   destination: string;
   transactionId: string;
 }
-export type DoomRequestReceiptReserveResult = {
+export type PoRequestReceiptReserveResult = {
   kind: 'reserved';
   token: string;
 } | {
   kind: 'existing';
-  receipt: DoomRequestReceipt;
+  receipt: PoRequestReceipt;
 } | {
   kind: 'conflict';
-  receipt: DoomRequestReceipt;
+  receipt: PoRequestReceipt;
 };
 /** 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 & {
+export interface PoRequestReceipts {
+  reserve(request: PoRequestReceiptReservation): Promise<PoRequestReceiptReserveResult>;
+  lookup(key: PoRequestReceiptKey): Promise<PoRequestReceipt | undefined>;
+  finish(request: PoRequestReceiptKey & {
     token: string;
     outcome: 'admitted' | 'rejected' | 'uncertain';
-  }): Promise<DoomRequestReceipt>;
+  }): Promise<PoRequestReceipt>;
 }
 /** Permit returned for expensive local work. Calling it releases the slot. */
-export interface DoomHostExecutionPermit {
+export interface PoHostExecutionPermit {
   (): 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>;
+export interface PoHostExecutionBudget {
+  acquire(signal?: AbortSignal): Promise<PoHostExecutionPermit>;
   getSnapshot(): Readonly<{
     running: number;
     queued: number;
@@ -170,12 +171,12 @@ export interface DoomHostExecutionBudget {
   }>;
 }
 /** Synchronous host-owned exclusion across media APIs mounted at different scopes. */
-export interface DoomHostMediaArbitration {
+export interface PoHostMediaArbitration {
   register(busy: () => boolean): () => void;
   available(busy: () => boolean): boolean;
 }
 /** One host's paired agent registrations, shared across its global and session mounts. */
-export interface DoomPeerAgentRegistry {
+export interface PoPeerAgentRegistry {
   register(sessionId: string, agent: {
     fetch(request: Request): Promise<Response>;
   }, hubToken: string): () => void;
@@ -184,13 +185,34 @@ export interface DoomPeerAgentRegistry {
     hubToken: string;
   } | undefined;
 }
+/** One agent that edits files: a hub session or an in-process child run. */
+export interface PoEditPresenceAgent {
+  /** `session:<id>` or `run:<runId>`. Unique across the host. */
+  readonly key: string;
+  /** Read when a note is rendered, so a name registered after the edit still shows. */
+  readonly label: () => string;
+  /** Hub session id other agents can reach with intercom. */
+  readonly contact: string;
+  readonly isLive: () => boolean;
+}
+export interface PoEditPresenceEntry {
+  readonly agent: PoEditPresenceAgent;
+  /** `@file` tag of the bytes this agent's last successful edit or write left behind. */
+  readonly tag: string;
+  readonly at: number;
+}
+/**
+ * Host-wide record of the last edit each live agent made to a file, keyed by realpath then agent key.
+ * Owners delete their entries when they dispose, so no callback outlives its session or run.
+ */
+export type PoEditPresenceLedger = Map<string, Map<string, PoEditPresenceEntry>>;
 /** 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.";
+export declare const PO_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 {
+export interface PoSharedFile {
   /** Bearer link; never log or persist it. */
   url: string;
   fileName: string;
@@ -203,8 +225,8 @@ export interface DoomSharedFile {
   revoke(): void;
 }
 /** What the host tells an API about itself when it starts. */
-export interface DoomApiContext {
-  scope: DoomApiScope;
+export interface PoApiContext {
+  scope: PoApiScope;
   /** Stable, opaque workspace id, shared by every session and member checkout of the workspace. */
   workspaceId?: string;
   /**
@@ -213,7 +235,7 @@ export interface DoomApiContext {
    */
   workspaceRoot?: string;
   /** The session's baseline context; present on session mounts whose host knows its workspace. */
-  sessionContext?: DoomSessionContext;
+  sessionContext?: PoSessionContext;
   /** Explicit host home, never selected by a remote request. */
   homeDirectory?: string;
   /** The session this host serves; absent for a hub-scoped API. */
@@ -232,7 +254,7 @@ export interface DoomApiContext {
    */
   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;
+  readRepositorySync?(repositoryId: string): Promise<PoRepositorySyncView | undefined> | PoRepositorySyncView | undefined;
   /** Admitted workspaces available to this mount. */
   repositories?(): readonly {
     id: string;
@@ -246,42 +268,46 @@ export interface DoomApiContext {
    * 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;
+  oauthRedirect?(): PoOAuthRedirect | undefined;
   /** Canonical in-process lifecycle for sessions created by this host. */
-  sessionService?: DoomHubSessionService;
+  sessionService?: PoHubSessionService;
+  /** Trusted in-process storage capability. APIs must retain their mount's session authorization. */
+  sessionStorage?: PoSessionStorageService;
   /** Host-bound, authenticated inter-session event endpoint for this session. */
-  sessionCommunication?: DoomSessionCommunicationEndpoint;
+  sessionCommunication?: PoSessionCommunicationEndpoint;
   /** Same-process events shared by session APIs and hub channels. */
-  directEvents?: DoomDirectEventBus;
+  directEvents?: PoDirectEventBus;
   /**
    * 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;
+  publishActivity?(activity: PoSessionActivity | 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>;
+  requestApi?(mount: PoApiMount, 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. */
+  computerUse?: PoComputerUseSessionAccess;
+  /** Deliver a typed method to the channel serving a session this mount reaches, 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;
+  requestReceipts?: PoRequestReceipts;
   /** One host's exclusive media activity, shared across global and session scopes. */
-  mediaArbitration?: DoomHostMediaArbitration;
+  mediaArbitration?: PoHostMediaArbitration;
   /** One host-wide heavy-job budget, not a separate budget for every session. */
-  executionBudget?: DoomHostExecutionBudget;
+  executionBudget?: PoHostExecutionBudget;
+  /** One host-wide edit presence ledger, shared by every session mount. */
+  editPresence?: PoEditPresenceLedger;
   /** Paired agents belonging to this host only. */
-  peerAgents?: DoomPeerAgentRegistry;
-  /** Machine-owned Remote Control service, mounted only by the global core facet. */
+  peerAgents?: PoPeerAgentRegistry;
+  /** Machine-owned Remote Control service, mounted only by Po's own global server plugin. */
   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.
+   * Session mounts only; rejects with PO_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>;
+  shareFile?(path: string, label: string): Promise<PoSharedFile>;
   onNotice(message: string): void;
 }
 /**
@@ -289,14 +315,14 @@ export interface DoomApiContext {
  * routes are declared relative ('/runners/:id/log') and a package never
  * repeats where it was mounted.
  */
-export interface DoomApiHandler {
+export interface PoApiHandler {
   fetch(request: Request): Response | Promise<Response>;
   close(): void;
 }
-export interface DoomApi {
+export interface PoApi {
   /** Segment under /api/plugins/; globally unique across loaded packages. */
   basePath: string;
-  start(context: DoomApiContext): DoomApiHandler;
+  start(context: PoApiContext): PoApiHandler;
 }
 //#endregion
 //# sourceMappingURL=packageApi.d.mts.map

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

@@ -1 +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"}
+{"version":3,"file":"packageApi.d.mts","names":[],"sources":["../../../src/schemas/packageApi.ts"],"mappings":";;;;;iBAqBiB;EACf;EACA;;EAEA;EACA,gBAAgB;;;YAIN;qBAEC,wBAAwB;;YAGzB;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,eAAe,OAAO;EAAe;;;YAQzC;EACN;;EACA;EAAoB;;EACpB;EAAkB;EAAqB;;;wBAG7B,kBAAkB,mBAAmB;;qBAexC;;qBAEA;;qBAGA;qBACA;qBACA;qBACA;YAMD;YACA;EACN;EAAmB;;EACnB;EAAoB;EAAkB,QAAQ;;;wBAGpC,gBAAgB,SAAS,UAAU;;;;;;;;;;iBA0BlC;;WAEN;;;;;EAKT,QAAQ,eAAe,qBAAqB;;EAE5C,KAAK,eAAe,qBAAqB;IAAU;IAAc;;;EAEjE,OAAO;;;iBAIQ;EACf;EACA;EACA;;iBAGe,yBAAyB;EACxC;EACA;EACA;EACA;;iBAGe,oCAAoC;;EAEnD;EACA;EACA;;YAGU;EACN;EAAkB;;EAClB;EAAkB,SAAS;;EAC3B;EAAkB,SAAS;;;iBAGhB;EACf,QAAQ,SAAS,8BAA8B,QAAQ;EACvD,OAAO,KAAK,sBAAsB,QAAQ;EAC1C,OACE,SAAS;IAAwB;IAAe;MAC/C,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;;;;iBAIvD;;WAEN;;WAEA;;WAEA;WACA;;iBAGM;WACN,OAAO;;WAEP;WACA;;;;;;YAOC,uBAAuB,YAAY,YAAY;;qBAG9C;;;;;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,oCAAoC;;EAE/C;IAA4B;IAAY;IAAc;IAAc;;;EAEpE;;;;;EAKA,kBAAkB;;EAElB,iBAAiB;;EAEjB,iBAAiB;;EAEjB,uBAAuB;;EAEvB,eAAe;;;;;EAKf,iBAAiB,UAAU;;EAE3B,YAAY,OAAO,YAAY,kBAAkB,SAAS,UAAU,QAAQ;;EAE5E,cAAc;;EAEd,gBAAgB,mBAAmB,mBAAmB,kBAAkB;;EAExE,kBAAkB;;EAElB,mBAAmB;;EAEnB,kBAAkB;;EAElB,eAAe;;EAEf,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,eAAe"}

package/dist/src/schemas/packageApi.mjs

@@ -1,18 +1,18 @@
 //#region src/schemas/packageApi.ts
-const DOOM_API_SCOPES = [
+const PO_API_SCOPES = [
 	"global",
 	"workspace",
 	"session"
 ];
 /** Canonical public prefix. Scope selection never falls through to a parent. */
-function doomApiMountPath(mount) {
+function poApiMountPath(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) {
+function parsePoSocketPath(pathname) {
 	if (pathname === "/api/ws") return { scope: "global" };
 	const match = /^\/api\/workspaces\/([^/]+)(?:\/sessions\/([^/]+))?\/ws$/u.exec(pathname);
 	if (!match) return void 0;
@@ -31,23 +31,23 @@ function parseDoomSocketPath(pathname) {
 	}
 }
 /** The segment an API is mounted under, below this prefix. */
-const DOOM_API_ROUTE_PREFIX = "/api/plugins";
+const PO_API_ROUTE_PREFIX = "/api/plugins";
 /** Selects the hub API bundle that owns the named cockpit session. */
-const DOOM_HUB_API_SESSION_QUERY_PARAM = "hubSession";
+const PO_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
+const PO_API_CALLER_LOCALITY_HEADER = "x-po-api-caller-locality";
+const PO_API_CALLER_DEVICE_ID_HEADER = "x-po-api-caller-device-id";
+const PO_API_CALLER_STEP_UP_HEADER = "x-po-api-caller-step-up";
+const PO_API_CALLER_HEADERS = [
+	PO_API_CALLER_LOCALITY_HEADER,
+	PO_API_CALLER_DEVICE_ID_HEADER,
+	PO_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);
+function poApiCallerFrom(headers) {
+	const locality = headers.get(PO_API_CALLER_LOCALITY_HEADER);
+	const deviceId = headers.get(PO_API_CALLER_DEVICE_ID_HEADER);
+	const stepUp = headers.get(PO_API_CALLER_STEP_UP_HEADER);
 	if (locality === "local") return deviceId === null && stepUp === "not-required" ? {
 		locality,
 		stepUp
@@ -59,8 +59,8 @@ function doomApiCallerFrom(headers) {
 	};
 }
 /** 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.";
+const PO_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 };
+export { PO_API_CALLER_DEVICE_ID_HEADER, PO_API_CALLER_HEADERS, PO_API_CALLER_LOCALITY_HEADER, PO_API_CALLER_STEP_UP_HEADER, PO_API_ROUTE_PREFIX, PO_API_SCOPES, PO_HUB_API_SESSION_QUERY_PARAM, PO_SHARE_FILE_REMOTE_OFF_MESSAGE, parsePoSocketPath, poApiCallerFrom, poApiMountPath };
 
 //# sourceMappingURL=packageApi.mjs.map

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

@@ -1 +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"}
+{"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 plugin 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  PoComputerUseSessionAccess,\n  PoDirectEventBus,\n  PoHubSessionService,\n  PoSessionCommunicationEndpoint,\n  PoSessionActivity,\n  PoSessionContext,\n} from './hubChannel';\nimport type { PoMcpProjection } from './mcpProjection';\nimport type { PoSessionStorageService } from './platform';\n/** The host-owned sync view a repository-scoped package API may inspect. */\nexport interface PoRepositorySyncView {\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?: PoMcpProjection;\n}\n\n/** Where an API runs: inside one session's server, or in the machine-wide hub. */\nexport type PoApiScope = 'global' | 'workspace' | 'session';\n\nexport const PO_API_SCOPES: readonly PoApiScope[] = ['global', 'workspace', 'session'];\n\n/** Identity of an independently mounted plugin host. */\nexport type PoApiMount =\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 PoWebComposition {\n  id: string;\n  scope: PoApiScope;\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 PoNativeComposition {\n  id: string;\n  scope: PoApiScope;\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 poApiMountPath(mount: PoApiMount & { 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 PoSocketMount =\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 parsePoSocketPath(pathname: string): PoSocketMount | 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 PO_API_ROUTE_PREFIX = '/api/plugins';\n/** Selects the hub API bundle that owns the named cockpit session. */\nexport const PO_HUB_API_SESSION_QUERY_PARAM = 'hubSession';\n\n/** Trusted caller headers written only by the cockpit-to-session proxy. */\nexport const PO_API_CALLER_LOCALITY_HEADER = 'x-po-api-caller-locality';\nexport const PO_API_CALLER_DEVICE_ID_HEADER = 'x-po-api-caller-device-id';\nexport const PO_API_CALLER_STEP_UP_HEADER = 'x-po-api-caller-step-up';\nexport const PO_API_CALLER_HEADERS = [\n  PO_API_CALLER_LOCALITY_HEADER,\n  PO_API_CALLER_DEVICE_ID_HEADER,\n  PO_API_CALLER_STEP_UP_HEADER,\n] as const;\n\nexport type PoApiCallerStepUp = 'not-required' | 'verified' | 'unavailable';\nexport type PoApiCaller =\n  | { locality: 'local'; stepUp: 'not-required' }\n  | { locality: 'remote'; deviceId: string; stepUp: PoApiCallerStepUp };\n\n/** Reads the proxy-authenticated caller identity, rejecting partial or contradictory stamps. */\nexport function poApiCallerFrom(headers: Headers): PoApiCaller | undefined {\n  const locality = headers.get(PO_API_CALLER_LOCALITY_HEADER);\n  const deviceId = headers.get(PO_API_CALLER_DEVICE_ID_HEADER);\n  const stepUp = headers.get(PO_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 PoOAuthRedirect {\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 PoRequestReceiptKey {\n  namespace: string;\n  activationId: string;\n  requestId: string;\n}\n\nexport interface PoRequestReceipt extends PoRequestReceiptKey {\n  fingerprint: string;\n  destination: string;\n  transactionId: string;\n  outcome: 'reserved' | 'admitted' | 'rejected' | 'uncertain';\n}\n\nexport interface PoRequestReceiptReservation extends PoRequestReceiptKey {\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 PoRequestReceiptReserveResult =\n  | { kind: 'reserved'; token: string }\n  | { kind: 'existing'; receipt: PoRequestReceipt }\n  | { kind: 'conflict'; receipt: PoRequestReceipt };\n\n/** A global-only receipt capability. A reservation is not an execution receipt. */\nexport interface PoRequestReceipts {\n  reserve(request: PoRequestReceiptReservation): Promise<PoRequestReceiptReserveResult>;\n  lookup(key: PoRequestReceiptKey): Promise<PoRequestReceipt | undefined>;\n  finish(\n    request: PoRequestReceiptKey & { token: string; outcome: 'admitted' | 'rejected' | 'uncertain' },\n  ): Promise<PoRequestReceipt>;\n}\n\n/** Permit returned for expensive local work. Calling it releases the slot. */\nexport interface PoHostExecutionPermit {\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 PoHostExecutionBudget {\n  acquire(signal?: AbortSignal): Promise<PoHostExecutionPermit>;\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 PoHostMediaArbitration {\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 PoPeerAgentRegistry {\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/** One agent that edits files: a hub session or an in-process child run. */\nexport interface PoEditPresenceAgent {\n  /** `session:<id>` or `run:<runId>`. Unique across the host. */\n  readonly key: string;\n  /** Read when a note is rendered, so a name registered after the edit still shows. */\n  readonly label: () => string;\n  /** Hub session id other agents can reach with intercom. */\n  readonly contact: string;\n  readonly isLive: () => boolean;\n}\n\nexport interface PoEditPresenceEntry {\n  readonly agent: PoEditPresenceAgent;\n  /** `@file` tag of the bytes this agent's last successful edit or write left behind. */\n  readonly tag: string;\n  readonly at: number;\n}\n\n/**\n * Host-wide record of the last edit each live agent made to a file, keyed by realpath then agent key.\n * Owners delete their entries when they dispose, so no callback outlives its session or run.\n */\nexport type PoEditPresenceLedger = Map<string, Map<string, PoEditPresenceEntry>>;\n\n/** Why shareFile rejects while the host has no public tunnel origin. */\nexport const PO_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 PoSharedFile {\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 PoApiContext {\n  scope: PoApiScope;\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?: PoSessionContext;\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<PoRepositorySyncView | undefined> | PoRepositorySyncView | 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?(): PoOAuthRedirect | undefined;\n  /** Canonical in-process lifecycle for sessions created by this host. */\n  sessionService?: PoHubSessionService;\n  /** Trusted in-process storage capability. APIs must retain their mount's session authorization. */\n  sessionStorage?: PoSessionStorageService;\n  /** Host-bound, authenticated inter-session event endpoint for this session. */\n  sessionCommunication?: PoSessionCommunicationEndpoint;\n  /** Same-process events shared by session APIs and hub channels. */\n  directEvents?: PoDirectEventBus;\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: PoSessionActivity | undefined): void;\n  /** Trusted in-process dispatch to an explicitly selected mounted API. No browser authentication is performed here. */\n  requestApi?(mount: PoApiMount, basePath: string, request: Request): Promise<Response>;\n  /** Present only on a session mounted by an authenticated Desktop host. */\n  computerUse?: PoComputerUseSessionAccess;\n  /** Deliver a typed method to the channel serving a session this mount reaches, 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?: PoRequestReceipts;\n  /** One host's exclusive media activity, shared across global and session scopes. */\n  mediaArbitration?: PoHostMediaArbitration;\n  /** One host-wide heavy-job budget, not a separate budget for every session. */\n  executionBudget?: PoHostExecutionBudget;\n  /** One host-wide edit presence ledger, shared by every session mount. */\n  editPresence?: PoEditPresenceLedger;\n  /** Paired agents belonging to this host only. */\n  peerAgents?: PoPeerAgentRegistry;\n  /** Machine-owned Remote Control service, mounted only by Po's own global server plugin. */\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 PO_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<PoSharedFile>;\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 PoApiHandler {\n  fetch(request: Request): Response | Promise<Response>;\n  close(): void;\n}\n\nexport interface PoApi {\n  /** Segment under /api/plugins/; globally unique across loaded packages. */\n  basePath: string;\n  start(context: PoApiContext): PoApiHandler;\n}\n"],"mappings":";AAgCA,MAAa,gBAAuC;CAAC;CAAU;CAAa;AAAS;;AA6CrF,SAAgB,eAAe,OAAsD;CACnF,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,kBAAkB,UAA6C;CAC7E,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,sBAAsB;;AAEnC,MAAa,iCAAiC;;AAG9C,MAAa,gCAAgC;AAC7C,MAAa,iCAAiC;AAC9C,MAAa,+BAA+B;AAC5C,MAAa,wBAAwB;CACnC;CACA;CACA;AACF;;AAQA,SAAgB,gBAAgB,SAA2C;CACzE,MAAM,WAAW,QAAQ,IAAI,6BAA6B;CAC1D,MAAM,WAAW,QAAQ,IAAI,8BAA8B;CAC3D,MAAM,SAAS,QAAQ,IAAI,4BAA4B;CACvD,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;;AA4GA,MAAa,mCACX"}

package/dist/src/schemas/platform.cjs

@@ -0,0 +1,34 @@
+//#region src/schemas/platform.ts
+const PO_FS_SERVICE = "po/fs";
+const PO_SHELL_SERVICE = "po/shell";
+const PO_SQLITE_SERVICE = "po/sqlite";
+const PO_SESSION_STORAGE_SERVICE = "po/session-storage";
+function readPoFs(context) {
+	return context.get(PO_FS_SERVICE);
+}
+function requirePoFs(context) {
+	const service = readPoFs(context);
+	if (!service) throw new Error(`The '${PO_FS_SERVICE}' service is unavailable. Start a Po server first.`);
+	return service;
+}
+function requirePoShell(context) {
+	const service = context.get(PO_SHELL_SERVICE);
+	if (!service) throw new Error(`The '${PO_SHELL_SERVICE}' service is unavailable. Start a Po server first.`);
+	return service;
+}
+function requirePoSqlite(context) {
+	const service = context.get(PO_SQLITE_SERVICE);
+	if (!service) throw new Error(`The '${PO_SQLITE_SERVICE}' service is unavailable. Start a Po server first.`);
+	return service;
+}
+//#endregion
+exports.PO_FS_SERVICE = PO_FS_SERVICE;
+exports.PO_SESSION_STORAGE_SERVICE = PO_SESSION_STORAGE_SERVICE;
+exports.PO_SHELL_SERVICE = PO_SHELL_SERVICE;
+exports.PO_SQLITE_SERVICE = PO_SQLITE_SERVICE;
+exports.readPoFs = readPoFs;
+exports.requirePoFs = requirePoFs;
+exports.requirePoShell = requirePoShell;
+exports.requirePoSqlite = requirePoSqlite;
+
+//# sourceMappingURL=platform.cjs.map