@agimon-ai/po-core 0.0.0-alpha.25 → 0.0.0-alpha.26

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

@@ -1 +1 @@
-{"version":3,"file":"hubChannel.cjs","names":[],"sources":["../../../src/schemas/hubChannel.ts"],"sourcesContent":["import type { PoBackgroundWorkSnapshot } from './backgroundWork';\nimport type { HomeProjection } from './home';\nimport type { PoSessionStorageService } from './platform';\n\nexport interface PoHubChannelFrame {\n  type: string;\n  sessionId: string;\n  payload: unknown;\n}\n\n/** Same-process lifecycle bus shared by a host's session APIs and hub channels. */\nexport interface PoDirectEventSubscriptionOptions {\n  /** Replay the most recent value published for this frame and session, when one exists. */\n  readonly replayLatest?: boolean;\n}\n\nexport interface PoDirectEventBus {\n  publish(frameType: string, sessionId: string, payload: unknown): void;\n  subscribe(\n    frameType: string,\n    sessionId: string,\n    listener: (payload: unknown) => void,\n    options?: PoDirectEventSubscriptionOptions,\n  ): () => void;\n  /** Drop retained state for a session after its lifecycle ends. */\n  clearSession?(sessionId: string): void;\n  close(): void;\n}\n\n/**\n * The extension-agnostic baseline every surface gets for one session, computed once by the\n * session host. Extensions build on it instead of re-deriving roots and relations from cwd.\n */\nexport interface PoSessionContext {\n  readonly sessionId: string;\n  /** Persisted workspace id, shared by every session and member checkout of the workspace. */\n  readonly workspaceId: string;\n  /** The admitted workspace root. It owns configuration, composition and settings. */\n  readonly workspaceRoot: string;\n  /**\n   * The checkout the session executes in. Equals workspaceRoot unless the session runs in a\n   * member checkout, such as a worktree, which may live outside the workspace folder.\n   */\n  readonly checkoutRoot: string;\n  readonly cwd: string;\n  readonly parentSessionId?: string;\n  /** The spawner's label for the session. Opaque: hosts never interpret it. */\n  readonly provenance?: string;\n}\n\nexport interface PoHubSessionScope {\n  sessionId: string;\n  workspaceId?: string;\n  cwd: string;\n  /** Environment admitted for this session, when supplied by the host. */\n  environment?: Readonly<Record<string, string | undefined>>;\n  /** The session's baseline context, when its host knows its workspace. */\n  sessionContext?: PoSessionContext;\n}\n\nexport interface PoHubReservedWorktreeRequest {\n  readonly reservationId: string;\n  readonly parentSessionId: string;\n  readonly signal?: AbortSignal;\n}\n\nexport type PoHubReservedWorktreeProvisioner = (request: PoHubReservedWorktreeRequest) => Promise<PoHubSessionScope>;\n\n/** Selection axes a caller pins for a new session instead of the workspace defaults. */\nexport interface PoHubSessionSelection {\n  readonly majorMode?: string;\n  readonly minorModes?: readonly string[];\n  readonly profile?: string;\n  /** An empty list starts the session with no domains. */\n  readonly domains?: readonly string[];\n}\n\n/**\n * Provenance of a session a workflow step opened.\n *\n * The step's conversation belongs to the workflow that ran it and is read in\n * that workflow's view, so the session rail leaves such sessions out.\n */\nexport const WORKFLOW_STEP_SESSION_PROVENANCE = 'workflow';\n\n/**\n * Provenance of a session opened to launch workflows for its parent.\n *\n * It picks and starts work, then closes; the runs it started belong to its\n * parent. Like a detached helper, it takes no row in the session rail.\n */\nexport const WORKFLOW_DISPATCHER_SESSION_PROVENANCE = 'workflow-dispatcher';\n\n/** Provenance of a conversation an external MCP client opened and drives. */\nexport const REMOTE_CONVERSATION_SESSION_PROVENANCE = 'remote-conversation';\n\nexport interface PoHubSessionCreateRequest {\n  readonly cwd: string;\n  readonly name: string;\n  readonly parentSessionId?: string;\n  readonly sessionProvenance?: string;\n  readonly signal?: AbortSignal;\n  /** Host-issued reservation, not a caller-chosen target session id. */\n  readonly reservationId?: string;\n  /** Pinned axes stay put when the workspace defaults change between turns. */\n  readonly selection?: PoHubSessionSelection;\n  /** Pi model selector, `provider/id`, validated like `--model`. */\n  readonly model?: string;\n  /** Pi thinking level, validated like `--thinking`. */\n  readonly thinking?: string;\n  /** Text appended to the session's system prompt, like `--append-system-prompt`. */\n  readonly appendSystemPrompt?: string;\n  /** Variables layered over the host environment for the new session and the tools it runs. */\n  readonly environment?: Readonly<Record<string, string>>;\n  /** The only tools the new session's agent may see or call, like a Team agent's `tools:` list. */\n  readonly tools?: readonly string[];\n}\n\nexport interface PoHubSessionPromptOptions {\n  readonly signal?: AbortSignal;\n  /** Refuses the prompt unless the target is a direct child of this session. */\n  readonly parentSessionId?: string;\n}\n\n/** A prompt the session admitted. `settled` resolves once the agent settles and rejects on a harness fault. */\nexport interface PoHubSessionPromptReceipt {\n  readonly settled: Promise<void>;\n}\n\n/** Host-bound inter-session events. The source identity is attached by the hub, never by payload data. */\nexport interface PoSessionCommunicationEndpoint {\n  readonly sessionId: string;\n  /** Current human-readable session name, read live so renames are reflected. */\n  readonly sessionName?: string;\n  publish(targetSessionId: string, type: string, payload: unknown): boolean;\n  subscribe(type: string, listener: (sourceSessionId: string, payload: unknown) => void): () => void;\n  onPeerReady(listener: (peerSessionId: string) => void): () => void;\n  /** Describes a live peer authorized to communicate, including same-checkout peers. */\n  describePeer?(peerSessionId: string): PoSessionPeerDescription | undefined;\n  close(): void;\n}\n\n/** How a session sees a peer it may message, so an agent can address it by the name a person uses. */\nexport interface PoSessionPeerDescription {\n  readonly sessionId: string;\n  readonly name: string;\n  readonly profile?: string;\n  /** Groups both sessions belong to; empty when related through parentage or checkout. */\n  readonly sharedGroups: readonly string[];\n}\nexport interface PoPendingSessionSetup {\n  readonly id: string;\n  readonly name: string;\n  readonly createdAt: string;\n  readonly cwd?: string;\n  readonly setupKind?: 'managed-worktree' | 'existing-directory';\n  readonly status?: 'provisioning' | 'failed' | 'interrupted';\n  readonly errorCode?: 'SESSION_WORKTREE_PROVISION_FAILED' | 'SESSION_UNAVAILABLE';\n}\n\n/**\n * One short line a session's extension publishes about work it runs for that\n * session, such as a background job. The host shows it on the session's rail\n * card but never interprets it.\n */\nexport interface PoSessionActivity {\n  readonly label: string;\n  /** The work needs the reader: the rail marks the card the way it marks a pending question. */\n  readonly attention?: boolean;\n  /** ISO 8601 start of the work; the rail appends the elapsed time. */\n  readonly since?: string;\n}\n/** A host-owned setup can be fulfilled by any execution-directory provider. */\nexport interface PoHubSessionReservations {\n  read(id: string, parentSessionId: string): { sessionId: string; cwd?: string };\n  prepare(id: string, parentSessionId: string, cwd: string): Promise<{ sessionId: string; cwd: string }>;\n  complete(id: string, parentSessionId: string): Promise<PoHubSessionScope>;\n}\n\n/** Authoritative execution state. Missing background coordination is unknown, not empty. */\nexport interface PoHubSessionExecutionState {\n  readonly isIdle: boolean;\n  readonly hasPendingMessages: boolean;\n  readonly backgroundWork?: PoBackgroundWorkSnapshot;\n}\n\n/** Direct lifecycle owned by the canonical headless hub, never by a package transport. */\nexport interface PoHubSessionService {\n  create(request: PoHubSessionCreateRequest): Promise<PoHubSessionScope>;\n  close(sessionId: string): Promise<void>;\n  isLive(sessionId: string): boolean;\n  /** Reads a live child's ownership without starting a turn. */\n  readExecutionState?(\n    sessionId: string,\n    options?: Pick<PoHubSessionPromptOptions, 'parentSessionId'>,\n  ): Promise<PoHubSessionExecutionState>;\n  /** Starts a turn in a live session, as if its user had submitted `text`. */\n  prompt?(sessionId: string, text: string, options?: PoHubSessionPromptOptions): Promise<PoHubSessionPromptReceipt>;\n  /** Aborts the live session's current turn. The session stays open. */\n  abort?(sessionId: string, options?: Pick<PoHubSessionPromptOptions, 'parentSessionId'>): Promise<void>;\n  /**\n   * Adds guidance to a live session's running turn. A session with no turn in\n   * progress takes it as its next message instead.\n   */\n  steer?(\n    sessionId: string,\n    message: string,\n    options?: Pick<PoHubSessionPromptOptions, 'parentSessionId'>,\n  ): Promise<void>;\n  /**\n   * Stops a live session's runtime and keeps it dormant: its history stays\n   * readable where it is shown, and it can be woken later. A session that has\n   * done its work no longer holds a model, tools and extensions in the host.\n   */\n  release?(sessionId: string, options?: Pick<PoHubSessionPromptOptions, 'parentSessionId'>): Promise<void>;\n  readonly reservations?: PoHubSessionReservations;\n  /** Provisions a host-reserved Git worktree child. This is not exposed to remote MCP clients. */\n  provisionReservedWorktree?(request: PoHubReservedWorktreeRequest): Promise<PoHubSessionScope>;\n  /** Core host hook. A Git provider registers its implementation while its channel is mounted. */\n  registerReservedWorktreeProvisioner?(provisioner: PoHubReservedWorktreeProvisioner): () => void;\n  /**\n   * True when both live sessions have a direct parent-child relationship, or execute in the same\n   * checkout. Remote conversations only qualify through the parent-child relationship.\n   */\n  canCommunicate?(sourceSessionId: string, targetSessionId: string): boolean;\n  /** Core host hook. Session API construction removes this method before exposing the service to extensions. */\n  bindCommunication?(sessionId: string): PoSessionCommunicationEndpoint;\n}\n\nexport interface PoHubSessionApiRequest {\n  basePath: string;\n  path: string;\n  method: string;\n  body?: string | Uint8Array<ArrayBuffer> | null;\n  signal?: AbortSignal;\n  /** Forwarded by the authenticated host, including content type and trace context. */\n  headers?: RequestInit['headers'];\n}\n\nexport type PoComputerUseHostOperation = 'status' | 'targets' | 'activate' | 'observe' | 'act' | 'stop';\n\nexport interface PoComputerUseHostRequest {\n  readonly operation: PoComputerUseHostOperation;\n  readonly payload?: unknown;\n  readonly signal?: AbortSignal;\n}\n\nexport interface PoComputerUseHostBinding {\n  readonly available: boolean;\n  /** Global opt-in, separate from the presence of a native host. */\n  readonly enabled?: boolean;\n  request(scope: PoHubSessionScope, request: PoComputerUseHostRequest): Promise<unknown>;\n  /** Checks a proof injected by the owning Desktop process, never a renderer marker. */\n  authorize?(headers: Headers): boolean;\n  /** Pins a session to Desktop before asking for a native grant. Ownership is not persisted. */\n  claimSession?(sessionId: string, headers?: Headers): void;\n  ownsSession?(sessionId: string): boolean;\n  /** Server-authenticated paired identity, checked against live native approval for this session. */\n  authorizeSession?(sessionId: string, headers: Headers): boolean;\n  authorizeRecording?(sessionId: string, headers: Headers): boolean;\n  authorizeActivation?(headers: Headers): boolean;\n  /** Own pending activation only, never general session control. */\n  authorizePending?(sessionId: string, headers: Headers): boolean;\n  revokeDevice?(deviceId: string): void;\n  readRecording?(scope: PoHubSessionScope, artifactId: string, range: string): Promise<Response>;\n  forgetSession?(sessionId: string): void;\n  /** Without `sessionId` the listener hears every session's ownership change. */\n  subscribe?(listener: () => void, sessionId?: string): () => void;\n  close?(): void;\n}\n\n/** Narrow, host-bound access. An extension cannot select another session's identity. */\nexport interface PoComputerUseSessionAccess {\n  readonly available: boolean;\n  readonly enabled?: boolean;\n  authorize(headers: Headers): boolean;\n  authorizeRecording?(headers: Headers): boolean;\n  authorizeActivation?(headers: Headers): boolean;\n  authorizePending?(headers: Headers): boolean;\n  claim(headers?: Headers): void;\n  fetchRecording?(artifactId: string, range: string): Promise<Response>;\n  subscribe(listener: () => void): () => void;\n}\n\nexport interface PoHubChannelConnection {\n  connectionId: string;\n  /** Host-verified native renderer proof, never copied from a channel payload. */\n  desktopAuthorized?: boolean;\n  /** Live session authorization evaluated by the host, never a client frame. */\n  computerUseAuthorized?: boolean;\n}\n\nexport interface PoHubChannelHost {\n  sessions(): readonly PoHubSessionScope[];\n  /** Host facts and storage for trusted in-process channels, never client-supplied roots. */\n  readonly homeDirectory?: string;\n  readonly sessionStorage?: PoSessionStorageService;\n  /** Canonical hub lifecycle for sessions created by channel commands. */\n  sessionService?: PoHubSessionService;\n  /** Same-process events emitted by session packages. */\n  readonly directEvents: PoDirectEventBus;\n  publish(sessionId: string, payload: unknown): void;\n  publishToConnection?(connectionId: string, sessionId: string, payload: unknown): boolean;\n  requestSessionApi(scope: PoHubSessionScope, request: PoHubSessionApiRequest): Promise<Response>;\n  computerUse?: PoComputerUseHostBinding;\n  onNotice(message: string): void;\n}\n\nexport interface PoHubChannelSource {\n  payloadFor(scope: PoHubSessionScope): unknown;\n  /** Read-only compact projection of already-owned state. Must not start work or add watchers. */\n  homeFor?(scope: PoHubSessionScope): HomeProjection;\n  sessionAdded?(scope: PoHubSessionScope): void;\n  sessionRemoved?(sessionId: string): void;\n  close(): void;\n}\n\nexport type PoHubChannelLifecycle = 'session' | 'hub';\n\nexport interface PoHubChannel {\n  frameType: string;\n  lifecycle?: PoHubChannelLifecycle;\n  start(host: PoHubChannelHost): PoHubChannelSource;\n  receiveWithoutSubscription?: boolean;\n  receive?(scope: PoHubSessionScope, payload: unknown, connection: PoHubChannelConnection): void;\n  disconnected?(connection: PoHubChannelConnection): void;\n}\n"],"mappings":";;;;;;;AAmFA,MAAa,mCAAmC;;;;;;;AAQhD,MAAa,yCAAyC;;AAGtD,MAAa,yCAAyC"}
+{"version":3,"file":"hubChannel.cjs","names":[],"sources":["../../../src/schemas/hubChannel.ts"],"sourcesContent":["import type { PoBackgroundWorkSnapshot } from './backgroundWork';\nimport type { HomeProjection } from './home';\nimport type { PoSessionStorageService } from './platform';\n\nexport interface PoHubChannelFrame {\n  type: string;\n  sessionId: string;\n  payload: unknown;\n}\n\n/** Same-process lifecycle bus shared by a host's session APIs and hub channels. */\nexport interface PoDirectEventSubscriptionOptions {\n  /** Replay the most recent value published for this frame and session, when one exists. */\n  readonly replayLatest?: boolean;\n}\n\nexport interface PoDirectEventBus {\n  publish(frameType: string, sessionId: string, payload: unknown): void;\n  subscribe(\n    frameType: string,\n    sessionId: string,\n    listener: (payload: unknown) => void,\n    options?: PoDirectEventSubscriptionOptions,\n  ): () => void;\n  /** Drop retained state for a session after its lifecycle ends. */\n  clearSession?(sessionId: string): void;\n  close(): void;\n}\n\n/**\n * The extension-agnostic baseline every surface gets for one session, computed once by the\n * session host. Extensions build on it instead of re-deriving roots and relations from cwd.\n */\nexport interface PoSessionContext {\n  readonly sessionId: string;\n  /** Persisted workspace id, shared by every session and member checkout of the workspace. */\n  readonly workspaceId: string;\n  /** The admitted workspace root. It owns configuration, composition and settings. */\n  readonly workspaceRoot: string;\n  /**\n   * The checkout the session executes in. Equals workspaceRoot unless the session runs in a\n   * member checkout, such as a worktree, which may live outside the workspace folder.\n   */\n  readonly checkoutRoot: string;\n  readonly cwd: string;\n  readonly parentSessionId?: string;\n  /** The spawner's label for the session. Opaque: hosts never interpret it. */\n  readonly provenance?: string;\n}\n\nexport interface PoHubSessionScope {\n  sessionId: string;\n  workspaceId?: string;\n  cwd: string;\n  /** Environment admitted for this session, when supplied by the host. */\n  environment?: Readonly<Record<string, string | undefined>>;\n  /** The session's baseline context, when its host knows its workspace. */\n  sessionContext?: PoSessionContext;\n}\n\nexport interface PoHubReservedWorktreeRequest {\n  readonly reservationId: string;\n  readonly parentSessionId: string;\n  readonly signal?: AbortSignal;\n}\n\nexport type PoHubReservedWorktreeProvisioner = (request: PoHubReservedWorktreeRequest) => Promise<PoHubSessionScope>;\n\n/** Selection axes a caller pins for a new session instead of the workspace defaults. */\nexport interface PoHubSessionSelection {\n  readonly majorMode?: string;\n  readonly minorModes?: readonly string[];\n  readonly profile?: string;\n  /** An empty list starts the session with no domains. */\n  readonly domains?: readonly string[];\n}\n\n/**\n * Provenance of a session a workflow step opened.\n *\n * The step's conversation belongs to the workflow that ran it and is read in\n * that workflow's view, so the session rail leaves such sessions out.\n */\nexport const WORKFLOW_STEP_SESSION_PROVENANCE = 'workflow';\n\n/**\n * Provenance of a session opened to launch workflows for its parent.\n *\n * It picks and starts work, then closes; the runs it started belong to its\n * parent. Like a detached helper, it takes no row in the session rail.\n */\nexport const WORKFLOW_DISPATCHER_SESSION_PROVENANCE = 'workflow-dispatcher';\n\n/** Provenance of a conversation an external MCP client opened and drives. */\nexport const REMOTE_CONVERSATION_SESSION_PROVENANCE = 'remote-conversation';\n\nexport interface PoHubSessionCreateRequest {\n  readonly cwd: string;\n  readonly name: string;\n  readonly parentSessionId?: string;\n  readonly sessionProvenance?: string;\n  readonly signal?: AbortSignal;\n  /** Host-issued reservation, not a caller-chosen target session id. */\n  readonly reservationId?: string;\n  /** Pinned axes stay put when the workspace defaults change between turns. */\n  readonly selection?: PoHubSessionSelection;\n  /** Pi model selector, `provider/id`, validated like `--model`. */\n  readonly model?: string;\n  /** Pi thinking level, validated like `--thinking`. */\n  readonly thinking?: string;\n  /** Text appended to the session's system prompt, like `--append-system-prompt`. */\n  readonly appendSystemPrompt?: string;\n  /** Variables layered over the host environment for the new session and the tools it runs. */\n  readonly environment?: Readonly<Record<string, string>>;\n  /** The only tools the new session's agent may see or call, like a Team agent's `tools:` list. */\n  readonly tools?: readonly string[];\n}\n\nexport interface PoHubSessionPromptOptions {\n  readonly signal?: AbortSignal;\n  /** Refuses the prompt unless the target is a direct child of this session. */\n  readonly parentSessionId?: string;\n}\n\n/** A prompt the session admitted. `settled` resolves once the agent settles and rejects on a harness fault. */\nexport interface PoHubSessionPromptReceipt {\n  readonly settled: Promise<void>;\n}\n\n/** Host-bound inter-session events. The source identity is attached by the hub, never by payload data. */\nexport interface PoSessionCommunicationEndpoint {\n  readonly sessionId: string;\n  /** Current human-readable session name, read live so renames are reflected. */\n  readonly sessionName?: string;\n  publish(targetSessionId: string, type: string, payload: unknown): boolean;\n  subscribe(type: string, listener: (sourceSessionId: string, payload: unknown) => void): () => void;\n  onPeerReady(listener: (peerSessionId: string) => void): () => void;\n  /** Describes a live peer authorized to communicate, including same-checkout peers. */\n  describePeer?(peerSessionId: string): PoSessionPeerDescription | undefined;\n  close(): void;\n}\n\n/** How a session sees a peer it may message, so an agent can address it by the name a person uses. */\nexport interface PoSessionPeerDescription {\n  readonly sessionId: string;\n  readonly name: string;\n  readonly profile?: string;\n  /** Groups both sessions belong to; empty when related through parentage or checkout. */\n  readonly sharedGroups: readonly string[];\n}\nexport interface PoPendingSessionSetup {\n  readonly id: string;\n  readonly name: string;\n  readonly createdAt: string;\n  readonly cwd?: string;\n  readonly setupKind?: 'managed-worktree' | 'existing-directory';\n  readonly status?: 'provisioning' | 'failed' | 'interrupted';\n  readonly errorCode?: 'SESSION_WORKTREE_PROVISION_FAILED' | 'SESSION_UNAVAILABLE';\n}\n\n/**\n * One short line a session's extension publishes about work it runs for that\n * session, such as a background job. The host shows it on the session's rail\n * card but never interprets it.\n */\nexport interface PoSessionActivity {\n  readonly label: string;\n  /** The work needs the reader: the rail marks the card the way it marks a pending question. */\n  readonly attention?: boolean;\n  /** ISO 8601 start of the work; the rail appends the elapsed time. */\n  readonly since?: string;\n}\n/** A host-owned setup can be fulfilled by any execution-directory provider. */\nexport interface PoHubSessionReservations {\n  read(id: string, parentSessionId: string): { sessionId: string; cwd?: string };\n  prepare(id: string, parentSessionId: string, cwd: string): Promise<{ sessionId: string; cwd: string }>;\n  complete(id: string, parentSessionId: string): Promise<PoHubSessionScope>;\n}\n\n/** Authoritative execution state. Missing background coordination is unknown, not empty. */\nexport interface PoHubSessionExecutionState {\n  readonly isIdle: boolean;\n  readonly hasPendingMessages: boolean;\n  readonly backgroundWork?: PoBackgroundWorkSnapshot;\n}\n\n/** Direct lifecycle owned by the canonical headless hub, never by a package transport. */\nexport interface PoHubSessionService {\n  create(request: PoHubSessionCreateRequest): Promise<PoHubSessionScope>;\n  close(sessionId: string): Promise<void>;\n  isLive(sessionId: string): boolean;\n  /** Reads a live child's ownership without starting a turn. */\n  readExecutionState?(\n    sessionId: string,\n    options?: Pick<PoHubSessionPromptOptions, 'parentSessionId'>,\n  ): Promise<PoHubSessionExecutionState>;\n  /** Starts a turn in a live session, as if its user had submitted `text`. */\n  prompt?(sessionId: string, text: string, options?: PoHubSessionPromptOptions): Promise<PoHubSessionPromptReceipt>;\n  /** Aborts the live session's current turn. The session stays open. */\n  abort?(sessionId: string, options?: Pick<PoHubSessionPromptOptions, 'parentSessionId'>): Promise<void>;\n  /**\n   * Adds guidance to a live session's running turn. A session with no turn in\n   * progress takes it as its next message instead.\n   */\n  steer?(\n    sessionId: string,\n    message: string,\n    options?: Pick<PoHubSessionPromptOptions, 'parentSessionId'>,\n  ): Promise<void>;\n  /**\n   * Stops a live session's runtime and keeps it dormant: its history stays\n   * readable where it is shown, and it can be woken later. A session that has\n   * done its work no longer holds a model, tools and extensions in the host.\n   */\n  release?(sessionId: string, options?: Pick<PoHubSessionPromptOptions, 'parentSessionId'>): Promise<void>;\n  readonly reservations?: PoHubSessionReservations;\n  /** Provisions a host-reserved Git worktree child. This is not exposed to remote MCP clients. */\n  provisionReservedWorktree?(request: PoHubReservedWorktreeRequest): Promise<PoHubSessionScope>;\n  /** Core host hook. A Git provider registers its implementation while its channel is mounted. */\n  registerReservedWorktreeProvisioner?(provisioner: PoHubReservedWorktreeProvisioner): () => void;\n  /**\n   * True when both live sessions have a direct parent-child relationship, or execute in the same\n   * checkout. Remote conversations only qualify through the parent-child relationship.\n   */\n  canCommunicate?(sourceSessionId: string, targetSessionId: string): boolean;\n  /** Core host hook. Session API construction removes this method before exposing the service to extensions. */\n  bindCommunication?(sessionId: string): PoSessionCommunicationEndpoint;\n}\n\nexport interface PoHubSessionApiRequest {\n  basePath: string;\n  path: string;\n  method: string;\n  body?: string | Uint8Array<ArrayBuffer> | null;\n  signal?: AbortSignal;\n  /** Forwarded by the authenticated host, including content type and trace context. */\n  headers?: RequestInit['headers'];\n}\n\nexport type PoComputerUseHostOperation = 'status' | 'targets' | 'activate' | 'observe' | 'act' | 'stop';\n\nexport interface PoComputerUseHostRequest {\n  readonly operation: PoComputerUseHostOperation;\n  readonly payload?: unknown;\n  readonly signal?: AbortSignal;\n}\n\nexport interface PoComputerUseHostBinding {\n  readonly available: boolean;\n  /** Global opt-in, separate from the presence of a native host. */\n  readonly enabled?: boolean;\n  request(scope: PoHubSessionScope, request: PoComputerUseHostRequest): Promise<unknown>;\n  /** Checks a proof injected by the owning Desktop process, never a renderer marker. */\n  authorize?(headers: Headers): boolean;\n  /** Pins a session to Desktop before asking for a native grant. Ownership is not persisted. */\n  claimSession?(sessionId: string, headers?: Headers): void;\n  ownsSession?(sessionId: string): boolean;\n  /** Server-authenticated paired identity, checked against live native approval for this session. */\n  authorizeSession?(sessionId: string, headers: Headers): boolean;\n  authorizeRecording?(sessionId: string, headers: Headers): boolean;\n  authorizeActivation?(headers: Headers): boolean;\n  /** Own pending activation only, never general session control. */\n  authorizePending?(sessionId: string, headers: Headers): boolean;\n  revokeDevice?(deviceId: string): void;\n  /**\n   * The Desktop window, or a paired device. A `change` (asking macOS for a permission) also\n   * needs the step-up activation needs. Independent of the computer-use setting.\n   */\n  authorizePermissions?(headers: Headers, change: boolean): boolean;\n  /** Desktop's macOS permission states, after asking macOS for `permission` when it is set. */\n  permissions?(permission?: string): Promise<unknown>;\n  readRecording?(scope: PoHubSessionScope, artifactId: string, range: string): Promise<Response>;\n  forgetSession?(sessionId: string): void;\n  /** Without `sessionId` the listener hears every session's ownership change. */\n  subscribe?(listener: () => void, sessionId?: string): () => void;\n  close?(): void;\n}\n\n/** Narrow, host-bound access. An extension cannot select another session's identity. */\nexport interface PoComputerUseSessionAccess {\n  readonly available: boolean;\n  readonly enabled?: boolean;\n  authorize(headers: Headers): boolean;\n  authorizeRecording?(headers: Headers): boolean;\n  authorizeActivation?(headers: Headers): boolean;\n  authorizePending?(headers: Headers): boolean;\n  claim(headers?: Headers): void;\n  fetchRecording?(artifactId: string, range: string): Promise<Response>;\n  subscribe(listener: () => void): () => void;\n}\n\nexport interface PoHubChannelConnection {\n  connectionId: string;\n  /** Host-verified native renderer proof, never copied from a channel payload. */\n  desktopAuthorized?: boolean;\n  /** Live session authorization evaluated by the host, never a client frame. */\n  computerUseAuthorized?: boolean;\n}\n\nexport interface PoHubChannelHost {\n  sessions(): readonly PoHubSessionScope[];\n  /** Host facts and storage for trusted in-process channels, never client-supplied roots. */\n  readonly homeDirectory?: string;\n  readonly sessionStorage?: PoSessionStorageService;\n  /** Canonical hub lifecycle for sessions created by channel commands. */\n  sessionService?: PoHubSessionService;\n  /** Same-process events emitted by session packages. */\n  readonly directEvents: PoDirectEventBus;\n  publish(sessionId: string, payload: unknown): void;\n  publishToConnection?(connectionId: string, sessionId: string, payload: unknown): boolean;\n  requestSessionApi(scope: PoHubSessionScope, request: PoHubSessionApiRequest): Promise<Response>;\n  computerUse?: PoComputerUseHostBinding;\n  onNotice(message: string): void;\n}\n\nexport interface PoHubChannelSource {\n  payloadFor(scope: PoHubSessionScope): unknown;\n  /** Read-only compact projection of already-owned state. Must not start work or add watchers. */\n  homeFor?(scope: PoHubSessionScope): HomeProjection;\n  sessionAdded?(scope: PoHubSessionScope): void;\n  sessionRemoved?(sessionId: string): void;\n  close(): void;\n}\n\nexport type PoHubChannelLifecycle = 'session' | 'hub';\n\nexport interface PoHubChannel {\n  frameType: string;\n  lifecycle?: PoHubChannelLifecycle;\n  start(host: PoHubChannelHost): PoHubChannelSource;\n  receiveWithoutSubscription?: boolean;\n  receive?(scope: PoHubSessionScope, payload: unknown, connection: PoHubChannelConnection): void;\n  disconnected?(connection: PoHubChannelConnection): void;\n}\n"],"mappings":";;;;;;;AAmFA,MAAa,mCAAmC;;;;;;;AAQhD,MAAa,yCAAyC;;AAGtD,MAAa,yCAAyC"}

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

@@ -234,6 +234,13 @@ export interface PoComputerUseHostBinding {
   /** Own pending activation only, never general session control. */
   authorizePending?(sessionId: string, headers: Headers): boolean;
   revokeDevice?(deviceId: string): void;
+  /**
+   * The Desktop window, or a paired device. A `change` (asking macOS for a permission) also
+   * needs the step-up activation needs. Independent of the computer-use setting.
+   */
+  authorizePermissions?(headers: Headers, change: boolean): boolean;
+  /** Desktop's macOS permission states, after asking macOS for `permission` when it is set. */
+  permissions?(permission?: string): Promise<unknown>;
   readRecording?(scope: PoHubSessionScope, artifactId: string, range: string): Promise<Response>;
   forgetSession?(sessionId: string): void;
   /** Without `sessionId` the listener hears every session's ownership change. */

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

@@ -1 +1 @@
-{"version":3,"file":"hubChannel.d.mts","names":[],"sources":["../../../src/schemas/hubChannel.ts"],"mappings":";;;;iBAIiB;EACf;EACA;EACA;;;iBAIe;;WAEN;;iBAGM;EACf,QAAQ,mBAAmB,mBAAmB;EAC9C,UACE,mBACA,mBACA,WAAW,2BACX,UAAU;;EAGZ,cAAc;EACd;;;;;;iBAOe;WACN;;WAEA;;WAEA;;;;;WAKA;WACA;WACA;;WAEA;;iBAGM;EACf;EACA;EACA;;EAEA,cAAc,SAAS;;EAEvB,iBAAiB;;iBAGF;WACN;WACA;WACA,SAAS;;YAGR,oCAAoC,SAAS,iCAAiC,QAAQ;;iBAGjF;WACN;WACA;WACA;;WAEA;;;;;;;;qBASE;;;;;;;qBAQA;;qBAGA;iBAEI;WACN;WACA;WACA;WACA;WACA,SAAS;;WAET;;WAEA,YAAY;;WAEZ;;WAEA;;WAEA;;WAEA,cAAc,SAAS;;WAEvB;;iBAGM;WACN,SAAS;;WAET;;;iBAIM;WACN,SAAS;;;iBAIH;WACN;;WAEA;EACT,QAAQ,yBAAyB,cAAc;EAC/C,UAAU,cAAc,WAAW,yBAAyB;EAC5D,YAAY,WAAW;;EAEvB,cAAc,wBAAwB;EACtC;;;iBAIe;WACN;WACA;WACA;;WAEA;;iBAEM;WACN;WACA;WACA;WACA;WACA;WACA;WACA;;;;;;;iBAQM;WACN;;WAEA;;WAEA;;;iBAGM;EACf,KAAK,YAAY;IAA4B;IAAmB;;EAChE,QAAQ,YAAY,yBAAyB,cAAc;IAAU;IAAmB;;EACxF,SAAS,YAAY,0BAA0B,QAAQ;;;iBAIxC;WACN;WACA;WACA,iBAAiB;;;iBAIX;EACf,OAAO,SAAS,4BAA4B,QAAQ;EACpD,MAAM,oBAAoB;EAC1B,OAAO;;EAEP,oBACE,mBACA,UAAU,KAAK,gDACd,QAAQ;;EAEX,QAAQ,mBAAmB,cAAc,UAAU,4BAA4B,QAAQ;;EAEvF,OAAO,mBAAmB,UAAU,KAAK,gDAAgD;;;;;EAKzF,OACE,mBACA,iBACA,UAAU,KAAK,gDACd;;;;;;EAMH,SAAS,mBAAmB,UAAU,KAAK,gDAAgD;WAClF,eAAe;;EAExB,2BAA2B,SAAS,+BAA+B,QAAQ;;EAE3E,qCAAqC,aAAa;;;;;EAKlD,gBAAgB,yBAAyB;;EAEzC,mBAAmB,oBAAoB;;iBAGxB;EACf;EACA;EACA;EACA,gBAAgB,WAAW;EAC3B,SAAS;;EAET,UAAU;;YAGA;iBAEK;WACN,WAAW;WACX;WACA,SAAS;;iBAGH;WACN;;WAEA;EACT,QAAQ,OAAO,mBAAmB,SAAS,2BAA2B;;EAEtE,WAAW,SAAS;;EAEpB,cAAc,mBAAmB,UAAU;EAC3C,aAAa;;EAEb,kBAAkB,mBAAmB,SAAS;EAC9C,oBAAoB,mBAAmB,SAAS;EAChD,qBAAqB,SAAS;;EAE9B,kBAAkB,mBAAmB,SAAS;EAC9C,cAAc;EACd,eAAe,OAAO,mBAAmB,oBAAoB,gBAAgB,QAAQ;EACrF,eAAe;;EAEf,WAAW,sBAAsB;EACjC;;;iBAIe;WACN;WACA;EACT,UAAU,SAAS;EACnB,oBAAoB,SAAS;EAC7B,qBAAqB,SAAS;EAC9B,kBAAkB,SAAS;EAC3B,MAAM,UAAU;EAChB,gBAAgB,oBAAoB,gBAAgB,QAAQ;EAC5D,UAAU;;iBAGK;EACf;;EAEA;;EAEA;;iBAGe;EACf,qBAAqB;;WAEZ;WACA,iBAAiB;;EAE1B,iBAAiB;;WAER,cAAc;EACvB,QAAQ,mBAAmB;EAC3B,qBAAqB,sBAAsB,mBAAmB;EAC9D,kBAAkB,OAAO,mBAAmB,SAAS,yBAAyB,QAAQ;EACtF,cAAc;EACd,SAAS;;iBAGM;EACf,WAAW,OAAO;;EAElB,SAAS,OAAO,oBAAoB;EACpC,cAAc,OAAO;EACrB,gBAAgB;EAChB;;YAGU;iBAEK;EACf;EACA,YAAY;EACZ,MAAM,MAAM,mBAAmB;EAC/B;EACA,SAAS,OAAO,mBAAmB,kBAAkB,YAAY;EACjE,cAAc,YAAY"}
+{"version":3,"file":"hubChannel.d.mts","names":[],"sources":["../../../src/schemas/hubChannel.ts"],"mappings":";;;;iBAIiB;EACf;EACA;EACA;;;iBAIe;;WAEN;;iBAGM;EACf,QAAQ,mBAAmB,mBAAmB;EAC9C,UACE,mBACA,mBACA,WAAW,2BACX,UAAU;;EAGZ,cAAc;EACd;;;;;;iBAOe;WACN;;WAEA;;WAEA;;;;;WAKA;WACA;WACA;;WAEA;;iBAGM;EACf;EACA;EACA;;EAEA,cAAc,SAAS;;EAEvB,iBAAiB;;iBAGF;WACN;WACA;WACA,SAAS;;YAGR,oCAAoC,SAAS,iCAAiC,QAAQ;;iBAGjF;WACN;WACA;WACA;;WAEA;;;;;;;;qBASE;;;;;;;qBAQA;;qBAGA;iBAEI;WACN;WACA;WACA;WACA;WACA,SAAS;;WAET;;WAEA,YAAY;;WAEZ;;WAEA;;WAEA;;WAEA,cAAc,SAAS;;WAEvB;;iBAGM;WACN,SAAS;;WAET;;;iBAIM;WACN,SAAS;;;iBAIH;WACN;;WAEA;EACT,QAAQ,yBAAyB,cAAc;EAC/C,UAAU,cAAc,WAAW,yBAAyB;EAC5D,YAAY,WAAW;;EAEvB,cAAc,wBAAwB;EACtC;;;iBAIe;WACN;WACA;WACA;;WAEA;;iBAEM;WACN;WACA;WACA;WACA;WACA;WACA;WACA;;;;;;;iBAQM;WACN;;WAEA;;WAEA;;;iBAGM;EACf,KAAK,YAAY;IAA4B;IAAmB;;EAChE,QAAQ,YAAY,yBAAyB,cAAc;IAAU;IAAmB;;EACxF,SAAS,YAAY,0BAA0B,QAAQ;;;iBAIxC;WACN;WACA;WACA,iBAAiB;;;iBAIX;EACf,OAAO,SAAS,4BAA4B,QAAQ;EACpD,MAAM,oBAAoB;EAC1B,OAAO;;EAEP,oBACE,mBACA,UAAU,KAAK,gDACd,QAAQ;;EAEX,QAAQ,mBAAmB,cAAc,UAAU,4BAA4B,QAAQ;;EAEvF,OAAO,mBAAmB,UAAU,KAAK,gDAAgD;;;;;EAKzF,OACE,mBACA,iBACA,UAAU,KAAK,gDACd;;;;;;EAMH,SAAS,mBAAmB,UAAU,KAAK,gDAAgD;WAClF,eAAe;;EAExB,2BAA2B,SAAS,+BAA+B,QAAQ;;EAE3E,qCAAqC,aAAa;;;;;EAKlD,gBAAgB,yBAAyB;;EAEzC,mBAAmB,oBAAoB;;iBAGxB;EACf;EACA;EACA;EACA,gBAAgB,WAAW;EAC3B,SAAS;;EAET,UAAU;;YAGA;iBAEK;WACN,WAAW;WACX;WACA,SAAS;;iBAGH;WACN;;WAEA;EACT,QAAQ,OAAO,mBAAmB,SAAS,2BAA2B;;EAEtE,WAAW,SAAS;;EAEpB,cAAc,mBAAmB,UAAU;EAC3C,aAAa;;EAEb,kBAAkB,mBAAmB,SAAS;EAC9C,oBAAoB,mBAAmB,SAAS;EAChD,qBAAqB,SAAS;;EAE9B,kBAAkB,mBAAmB,SAAS;EAC9C,cAAc;;;;;EAKd,sBAAsB,SAAS,SAAS;;EAExC,aAAa,sBAAsB;EACnC,eAAe,OAAO,mBAAmB,oBAAoB,gBAAgB,QAAQ;EACrF,eAAe;;EAEf,WAAW,sBAAsB;EACjC;;;iBAIe;WACN;WACA;EACT,UAAU,SAAS;EACnB,oBAAoB,SAAS;EAC7B,qBAAqB,SAAS;EAC9B,kBAAkB,SAAS;EAC3B,MAAM,UAAU;EAChB,gBAAgB,oBAAoB,gBAAgB,QAAQ;EAC5D,UAAU;;iBAGK;EACf;;EAEA;;EAEA;;iBAGe;EACf,qBAAqB;;WAEZ;WACA,iBAAiB;;EAE1B,iBAAiB;;WAER,cAAc;EACvB,QAAQ,mBAAmB;EAC3B,qBAAqB,sBAAsB,mBAAmB;EAC9D,kBAAkB,OAAO,mBAAmB,SAAS,yBAAyB,QAAQ;EACtF,cAAc;EACd,SAAS;;iBAGM;EACf,WAAW,OAAO;;EAElB,SAAS,OAAO,oBAAoB;EACpC,cAAc,OAAO;EACrB,gBAAgB;EAChB;;YAGU;iBAEK;EACf;EACA,YAAY;EACZ,MAAM,MAAM,mBAAmB;EAC/B;EACA,SAAS,OAAO,mBAAmB,kBAAkB,YAAY;EACjE,cAAc,YAAY"}

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

@@ -1 +1 @@
-{"version":3,"file":"hubChannel.mjs","names":[],"sources":["../../../src/schemas/hubChannel.ts"],"sourcesContent":["import type { PoBackgroundWorkSnapshot } from './backgroundWork';\nimport type { HomeProjection } from './home';\nimport type { PoSessionStorageService } from './platform';\n\nexport interface PoHubChannelFrame {\n  type: string;\n  sessionId: string;\n  payload: unknown;\n}\n\n/** Same-process lifecycle bus shared by a host's session APIs and hub channels. */\nexport interface PoDirectEventSubscriptionOptions {\n  /** Replay the most recent value published for this frame and session, when one exists. */\n  readonly replayLatest?: boolean;\n}\n\nexport interface PoDirectEventBus {\n  publish(frameType: string, sessionId: string, payload: unknown): void;\n  subscribe(\n    frameType: string,\n    sessionId: string,\n    listener: (payload: unknown) => void,\n    options?: PoDirectEventSubscriptionOptions,\n  ): () => void;\n  /** Drop retained state for a session after its lifecycle ends. */\n  clearSession?(sessionId: string): void;\n  close(): void;\n}\n\n/**\n * The extension-agnostic baseline every surface gets for one session, computed once by the\n * session host. Extensions build on it instead of re-deriving roots and relations from cwd.\n */\nexport interface PoSessionContext {\n  readonly sessionId: string;\n  /** Persisted workspace id, shared by every session and member checkout of the workspace. */\n  readonly workspaceId: string;\n  /** The admitted workspace root. It owns configuration, composition and settings. */\n  readonly workspaceRoot: string;\n  /**\n   * The checkout the session executes in. Equals workspaceRoot unless the session runs in a\n   * member checkout, such as a worktree, which may live outside the workspace folder.\n   */\n  readonly checkoutRoot: string;\n  readonly cwd: string;\n  readonly parentSessionId?: string;\n  /** The spawner's label for the session. Opaque: hosts never interpret it. */\n  readonly provenance?: string;\n}\n\nexport interface PoHubSessionScope {\n  sessionId: string;\n  workspaceId?: string;\n  cwd: string;\n  /** Environment admitted for this session, when supplied by the host. */\n  environment?: Readonly<Record<string, string | undefined>>;\n  /** The session's baseline context, when its host knows its workspace. */\n  sessionContext?: PoSessionContext;\n}\n\nexport interface PoHubReservedWorktreeRequest {\n  readonly reservationId: string;\n  readonly parentSessionId: string;\n  readonly signal?: AbortSignal;\n}\n\nexport type PoHubReservedWorktreeProvisioner = (request: PoHubReservedWorktreeRequest) => Promise<PoHubSessionScope>;\n\n/** Selection axes a caller pins for a new session instead of the workspace defaults. */\nexport interface PoHubSessionSelection {\n  readonly majorMode?: string;\n  readonly minorModes?: readonly string[];\n  readonly profile?: string;\n  /** An empty list starts the session with no domains. */\n  readonly domains?: readonly string[];\n}\n\n/**\n * Provenance of a session a workflow step opened.\n *\n * The step's conversation belongs to the workflow that ran it and is read in\n * that workflow's view, so the session rail leaves such sessions out.\n */\nexport const WORKFLOW_STEP_SESSION_PROVENANCE = 'workflow';\n\n/**\n * Provenance of a session opened to launch workflows for its parent.\n *\n * It picks and starts work, then closes; the runs it started belong to its\n * parent. Like a detached helper, it takes no row in the session rail.\n */\nexport const WORKFLOW_DISPATCHER_SESSION_PROVENANCE = 'workflow-dispatcher';\n\n/** Provenance of a conversation an external MCP client opened and drives. */\nexport const REMOTE_CONVERSATION_SESSION_PROVENANCE = 'remote-conversation';\n\nexport interface PoHubSessionCreateRequest {\n  readonly cwd: string;\n  readonly name: string;\n  readonly parentSessionId?: string;\n  readonly sessionProvenance?: string;\n  readonly signal?: AbortSignal;\n  /** Host-issued reservation, not a caller-chosen target session id. */\n  readonly reservationId?: string;\n  /** Pinned axes stay put when the workspace defaults change between turns. */\n  readonly selection?: PoHubSessionSelection;\n  /** Pi model selector, `provider/id`, validated like `--model`. */\n  readonly model?: string;\n  /** Pi thinking level, validated like `--thinking`. */\n  readonly thinking?: string;\n  /** Text appended to the session's system prompt, like `--append-system-prompt`. */\n  readonly appendSystemPrompt?: string;\n  /** Variables layered over the host environment for the new session and the tools it runs. */\n  readonly environment?: Readonly<Record<string, string>>;\n  /** The only tools the new session's agent may see or call, like a Team agent's `tools:` list. */\n  readonly tools?: readonly string[];\n}\n\nexport interface PoHubSessionPromptOptions {\n  readonly signal?: AbortSignal;\n  /** Refuses the prompt unless the target is a direct child of this session. */\n  readonly parentSessionId?: string;\n}\n\n/** A prompt the session admitted. `settled` resolves once the agent settles and rejects on a harness fault. */\nexport interface PoHubSessionPromptReceipt {\n  readonly settled: Promise<void>;\n}\n\n/** Host-bound inter-session events. The source identity is attached by the hub, never by payload data. */\nexport interface PoSessionCommunicationEndpoint {\n  readonly sessionId: string;\n  /** Current human-readable session name, read live so renames are reflected. */\n  readonly sessionName?: string;\n  publish(targetSessionId: string, type: string, payload: unknown): boolean;\n  subscribe(type: string, listener: (sourceSessionId: string, payload: unknown) => void): () => void;\n  onPeerReady(listener: (peerSessionId: string) => void): () => void;\n  /** Describes a live peer authorized to communicate, including same-checkout peers. */\n  describePeer?(peerSessionId: string): PoSessionPeerDescription | undefined;\n  close(): void;\n}\n\n/** How a session sees a peer it may message, so an agent can address it by the name a person uses. */\nexport interface PoSessionPeerDescription {\n  readonly sessionId: string;\n  readonly name: string;\n  readonly profile?: string;\n  /** Groups both sessions belong to; empty when related through parentage or checkout. */\n  readonly sharedGroups: readonly string[];\n}\nexport interface PoPendingSessionSetup {\n  readonly id: string;\n  readonly name: string;\n  readonly createdAt: string;\n  readonly cwd?: string;\n  readonly setupKind?: 'managed-worktree' | 'existing-directory';\n  readonly status?: 'provisioning' | 'failed' | 'interrupted';\n  readonly errorCode?: 'SESSION_WORKTREE_PROVISION_FAILED' | 'SESSION_UNAVAILABLE';\n}\n\n/**\n * One short line a session's extension publishes about work it runs for that\n * session, such as a background job. The host shows it on the session's rail\n * card but never interprets it.\n */\nexport interface PoSessionActivity {\n  readonly label: string;\n  /** The work needs the reader: the rail marks the card the way it marks a pending question. */\n  readonly attention?: boolean;\n  /** ISO 8601 start of the work; the rail appends the elapsed time. */\n  readonly since?: string;\n}\n/** A host-owned setup can be fulfilled by any execution-directory provider. */\nexport interface PoHubSessionReservations {\n  read(id: string, parentSessionId: string): { sessionId: string; cwd?: string };\n  prepare(id: string, parentSessionId: string, cwd: string): Promise<{ sessionId: string; cwd: string }>;\n  complete(id: string, parentSessionId: string): Promise<PoHubSessionScope>;\n}\n\n/** Authoritative execution state. Missing background coordination is unknown, not empty. */\nexport interface PoHubSessionExecutionState {\n  readonly isIdle: boolean;\n  readonly hasPendingMessages: boolean;\n  readonly backgroundWork?: PoBackgroundWorkSnapshot;\n}\n\n/** Direct lifecycle owned by the canonical headless hub, never by a package transport. */\nexport interface PoHubSessionService {\n  create(request: PoHubSessionCreateRequest): Promise<PoHubSessionScope>;\n  close(sessionId: string): Promise<void>;\n  isLive(sessionId: string): boolean;\n  /** Reads a live child's ownership without starting a turn. */\n  readExecutionState?(\n    sessionId: string,\n    options?: Pick<PoHubSessionPromptOptions, 'parentSessionId'>,\n  ): Promise<PoHubSessionExecutionState>;\n  /** Starts a turn in a live session, as if its user had submitted `text`. */\n  prompt?(sessionId: string, text: string, options?: PoHubSessionPromptOptions): Promise<PoHubSessionPromptReceipt>;\n  /** Aborts the live session's current turn. The session stays open. */\n  abort?(sessionId: string, options?: Pick<PoHubSessionPromptOptions, 'parentSessionId'>): Promise<void>;\n  /**\n   * Adds guidance to a live session's running turn. A session with no turn in\n   * progress takes it as its next message instead.\n   */\n  steer?(\n    sessionId: string,\n    message: string,\n    options?: Pick<PoHubSessionPromptOptions, 'parentSessionId'>,\n  ): Promise<void>;\n  /**\n   * Stops a live session's runtime and keeps it dormant: its history stays\n   * readable where it is shown, and it can be woken later. A session that has\n   * done its work no longer holds a model, tools and extensions in the host.\n   */\n  release?(sessionId: string, options?: Pick<PoHubSessionPromptOptions, 'parentSessionId'>): Promise<void>;\n  readonly reservations?: PoHubSessionReservations;\n  /** Provisions a host-reserved Git worktree child. This is not exposed to remote MCP clients. */\n  provisionReservedWorktree?(request: PoHubReservedWorktreeRequest): Promise<PoHubSessionScope>;\n  /** Core host hook. A Git provider registers its implementation while its channel is mounted. */\n  registerReservedWorktreeProvisioner?(provisioner: PoHubReservedWorktreeProvisioner): () => void;\n  /**\n   * True when both live sessions have a direct parent-child relationship, or execute in the same\n   * checkout. Remote conversations only qualify through the parent-child relationship.\n   */\n  canCommunicate?(sourceSessionId: string, targetSessionId: string): boolean;\n  /** Core host hook. Session API construction removes this method before exposing the service to extensions. */\n  bindCommunication?(sessionId: string): PoSessionCommunicationEndpoint;\n}\n\nexport interface PoHubSessionApiRequest {\n  basePath: string;\n  path: string;\n  method: string;\n  body?: string | Uint8Array<ArrayBuffer> | null;\n  signal?: AbortSignal;\n  /** Forwarded by the authenticated host, including content type and trace context. */\n  headers?: RequestInit['headers'];\n}\n\nexport type PoComputerUseHostOperation = 'status' | 'targets' | 'activate' | 'observe' | 'act' | 'stop';\n\nexport interface PoComputerUseHostRequest {\n  readonly operation: PoComputerUseHostOperation;\n  readonly payload?: unknown;\n  readonly signal?: AbortSignal;\n}\n\nexport interface PoComputerUseHostBinding {\n  readonly available: boolean;\n  /** Global opt-in, separate from the presence of a native host. */\n  readonly enabled?: boolean;\n  request(scope: PoHubSessionScope, request: PoComputerUseHostRequest): Promise<unknown>;\n  /** Checks a proof injected by the owning Desktop process, never a renderer marker. */\n  authorize?(headers: Headers): boolean;\n  /** Pins a session to Desktop before asking for a native grant. Ownership is not persisted. */\n  claimSession?(sessionId: string, headers?: Headers): void;\n  ownsSession?(sessionId: string): boolean;\n  /** Server-authenticated paired identity, checked against live native approval for this session. */\n  authorizeSession?(sessionId: string, headers: Headers): boolean;\n  authorizeRecording?(sessionId: string, headers: Headers): boolean;\n  authorizeActivation?(headers: Headers): boolean;\n  /** Own pending activation only, never general session control. */\n  authorizePending?(sessionId: string, headers: Headers): boolean;\n  revokeDevice?(deviceId: string): void;\n  readRecording?(scope: PoHubSessionScope, artifactId: string, range: string): Promise<Response>;\n  forgetSession?(sessionId: string): void;\n  /** Without `sessionId` the listener hears every session's ownership change. */\n  subscribe?(listener: () => void, sessionId?: string): () => void;\n  close?(): void;\n}\n\n/** Narrow, host-bound access. An extension cannot select another session's identity. */\nexport interface PoComputerUseSessionAccess {\n  readonly available: boolean;\n  readonly enabled?: boolean;\n  authorize(headers: Headers): boolean;\n  authorizeRecording?(headers: Headers): boolean;\n  authorizeActivation?(headers: Headers): boolean;\n  authorizePending?(headers: Headers): boolean;\n  claim(headers?: Headers): void;\n  fetchRecording?(artifactId: string, range: string): Promise<Response>;\n  subscribe(listener: () => void): () => void;\n}\n\nexport interface PoHubChannelConnection {\n  connectionId: string;\n  /** Host-verified native renderer proof, never copied from a channel payload. */\n  desktopAuthorized?: boolean;\n  /** Live session authorization evaluated by the host, never a client frame. */\n  computerUseAuthorized?: boolean;\n}\n\nexport interface PoHubChannelHost {\n  sessions(): readonly PoHubSessionScope[];\n  /** Host facts and storage for trusted in-process channels, never client-supplied roots. */\n  readonly homeDirectory?: string;\n  readonly sessionStorage?: PoSessionStorageService;\n  /** Canonical hub lifecycle for sessions created by channel commands. */\n  sessionService?: PoHubSessionService;\n  /** Same-process events emitted by session packages. */\n  readonly directEvents: PoDirectEventBus;\n  publish(sessionId: string, payload: unknown): void;\n  publishToConnection?(connectionId: string, sessionId: string, payload: unknown): boolean;\n  requestSessionApi(scope: PoHubSessionScope, request: PoHubSessionApiRequest): Promise<Response>;\n  computerUse?: PoComputerUseHostBinding;\n  onNotice(message: string): void;\n}\n\nexport interface PoHubChannelSource {\n  payloadFor(scope: PoHubSessionScope): unknown;\n  /** Read-only compact projection of already-owned state. Must not start work or add watchers. */\n  homeFor?(scope: PoHubSessionScope): HomeProjection;\n  sessionAdded?(scope: PoHubSessionScope): void;\n  sessionRemoved?(sessionId: string): void;\n  close(): void;\n}\n\nexport type PoHubChannelLifecycle = 'session' | 'hub';\n\nexport interface PoHubChannel {\n  frameType: string;\n  lifecycle?: PoHubChannelLifecycle;\n  start(host: PoHubChannelHost): PoHubChannelSource;\n  receiveWithoutSubscription?: boolean;\n  receive?(scope: PoHubSessionScope, payload: unknown, connection: PoHubChannelConnection): void;\n  disconnected?(connection: PoHubChannelConnection): void;\n}\n"],"mappings":";;;;;;;AAmFA,MAAa,mCAAmC;;;;;;;AAQhD,MAAa,yCAAyC;;AAGtD,MAAa,yCAAyC"}
+{"version":3,"file":"hubChannel.mjs","names":[],"sources":["../../../src/schemas/hubChannel.ts"],"sourcesContent":["import type { PoBackgroundWorkSnapshot } from './backgroundWork';\nimport type { HomeProjection } from './home';\nimport type { PoSessionStorageService } from './platform';\n\nexport interface PoHubChannelFrame {\n  type: string;\n  sessionId: string;\n  payload: unknown;\n}\n\n/** Same-process lifecycle bus shared by a host's session APIs and hub channels. */\nexport interface PoDirectEventSubscriptionOptions {\n  /** Replay the most recent value published for this frame and session, when one exists. */\n  readonly replayLatest?: boolean;\n}\n\nexport interface PoDirectEventBus {\n  publish(frameType: string, sessionId: string, payload: unknown): void;\n  subscribe(\n    frameType: string,\n    sessionId: string,\n    listener: (payload: unknown) => void,\n    options?: PoDirectEventSubscriptionOptions,\n  ): () => void;\n  /** Drop retained state for a session after its lifecycle ends. */\n  clearSession?(sessionId: string): void;\n  close(): void;\n}\n\n/**\n * The extension-agnostic baseline every surface gets for one session, computed once by the\n * session host. Extensions build on it instead of re-deriving roots and relations from cwd.\n */\nexport interface PoSessionContext {\n  readonly sessionId: string;\n  /** Persisted workspace id, shared by every session and member checkout of the workspace. */\n  readonly workspaceId: string;\n  /** The admitted workspace root. It owns configuration, composition and settings. */\n  readonly workspaceRoot: string;\n  /**\n   * The checkout the session executes in. Equals workspaceRoot unless the session runs in a\n   * member checkout, such as a worktree, which may live outside the workspace folder.\n   */\n  readonly checkoutRoot: string;\n  readonly cwd: string;\n  readonly parentSessionId?: string;\n  /** The spawner's label for the session. Opaque: hosts never interpret it. */\n  readonly provenance?: string;\n}\n\nexport interface PoHubSessionScope {\n  sessionId: string;\n  workspaceId?: string;\n  cwd: string;\n  /** Environment admitted for this session, when supplied by the host. */\n  environment?: Readonly<Record<string, string | undefined>>;\n  /** The session's baseline context, when its host knows its workspace. */\n  sessionContext?: PoSessionContext;\n}\n\nexport interface PoHubReservedWorktreeRequest {\n  readonly reservationId: string;\n  readonly parentSessionId: string;\n  readonly signal?: AbortSignal;\n}\n\nexport type PoHubReservedWorktreeProvisioner = (request: PoHubReservedWorktreeRequest) => Promise<PoHubSessionScope>;\n\n/** Selection axes a caller pins for a new session instead of the workspace defaults. */\nexport interface PoHubSessionSelection {\n  readonly majorMode?: string;\n  readonly minorModes?: readonly string[];\n  readonly profile?: string;\n  /** An empty list starts the session with no domains. */\n  readonly domains?: readonly string[];\n}\n\n/**\n * Provenance of a session a workflow step opened.\n *\n * The step's conversation belongs to the workflow that ran it and is read in\n * that workflow's view, so the session rail leaves such sessions out.\n */\nexport const WORKFLOW_STEP_SESSION_PROVENANCE = 'workflow';\n\n/**\n * Provenance of a session opened to launch workflows for its parent.\n *\n * It picks and starts work, then closes; the runs it started belong to its\n * parent. Like a detached helper, it takes no row in the session rail.\n */\nexport const WORKFLOW_DISPATCHER_SESSION_PROVENANCE = 'workflow-dispatcher';\n\n/** Provenance of a conversation an external MCP client opened and drives. */\nexport const REMOTE_CONVERSATION_SESSION_PROVENANCE = 'remote-conversation';\n\nexport interface PoHubSessionCreateRequest {\n  readonly cwd: string;\n  readonly name: string;\n  readonly parentSessionId?: string;\n  readonly sessionProvenance?: string;\n  readonly signal?: AbortSignal;\n  /** Host-issued reservation, not a caller-chosen target session id. */\n  readonly reservationId?: string;\n  /** Pinned axes stay put when the workspace defaults change between turns. */\n  readonly selection?: PoHubSessionSelection;\n  /** Pi model selector, `provider/id`, validated like `--model`. */\n  readonly model?: string;\n  /** Pi thinking level, validated like `--thinking`. */\n  readonly thinking?: string;\n  /** Text appended to the session's system prompt, like `--append-system-prompt`. */\n  readonly appendSystemPrompt?: string;\n  /** Variables layered over the host environment for the new session and the tools it runs. */\n  readonly environment?: Readonly<Record<string, string>>;\n  /** The only tools the new session's agent may see or call, like a Team agent's `tools:` list. */\n  readonly tools?: readonly string[];\n}\n\nexport interface PoHubSessionPromptOptions {\n  readonly signal?: AbortSignal;\n  /** Refuses the prompt unless the target is a direct child of this session. */\n  readonly parentSessionId?: string;\n}\n\n/** A prompt the session admitted. `settled` resolves once the agent settles and rejects on a harness fault. */\nexport interface PoHubSessionPromptReceipt {\n  readonly settled: Promise<void>;\n}\n\n/** Host-bound inter-session events. The source identity is attached by the hub, never by payload data. */\nexport interface PoSessionCommunicationEndpoint {\n  readonly sessionId: string;\n  /** Current human-readable session name, read live so renames are reflected. */\n  readonly sessionName?: string;\n  publish(targetSessionId: string, type: string, payload: unknown): boolean;\n  subscribe(type: string, listener: (sourceSessionId: string, payload: unknown) => void): () => void;\n  onPeerReady(listener: (peerSessionId: string) => void): () => void;\n  /** Describes a live peer authorized to communicate, including same-checkout peers. */\n  describePeer?(peerSessionId: string): PoSessionPeerDescription | undefined;\n  close(): void;\n}\n\n/** How a session sees a peer it may message, so an agent can address it by the name a person uses. */\nexport interface PoSessionPeerDescription {\n  readonly sessionId: string;\n  readonly name: string;\n  readonly profile?: string;\n  /** Groups both sessions belong to; empty when related through parentage or checkout. */\n  readonly sharedGroups: readonly string[];\n}\nexport interface PoPendingSessionSetup {\n  readonly id: string;\n  readonly name: string;\n  readonly createdAt: string;\n  readonly cwd?: string;\n  readonly setupKind?: 'managed-worktree' | 'existing-directory';\n  readonly status?: 'provisioning' | 'failed' | 'interrupted';\n  readonly errorCode?: 'SESSION_WORKTREE_PROVISION_FAILED' | 'SESSION_UNAVAILABLE';\n}\n\n/**\n * One short line a session's extension publishes about work it runs for that\n * session, such as a background job. The host shows it on the session's rail\n * card but never interprets it.\n */\nexport interface PoSessionActivity {\n  readonly label: string;\n  /** The work needs the reader: the rail marks the card the way it marks a pending question. */\n  readonly attention?: boolean;\n  /** ISO 8601 start of the work; the rail appends the elapsed time. */\n  readonly since?: string;\n}\n/** A host-owned setup can be fulfilled by any execution-directory provider. */\nexport interface PoHubSessionReservations {\n  read(id: string, parentSessionId: string): { sessionId: string; cwd?: string };\n  prepare(id: string, parentSessionId: string, cwd: string): Promise<{ sessionId: string; cwd: string }>;\n  complete(id: string, parentSessionId: string): Promise<PoHubSessionScope>;\n}\n\n/** Authoritative execution state. Missing background coordination is unknown, not empty. */\nexport interface PoHubSessionExecutionState {\n  readonly isIdle: boolean;\n  readonly hasPendingMessages: boolean;\n  readonly backgroundWork?: PoBackgroundWorkSnapshot;\n}\n\n/** Direct lifecycle owned by the canonical headless hub, never by a package transport. */\nexport interface PoHubSessionService {\n  create(request: PoHubSessionCreateRequest): Promise<PoHubSessionScope>;\n  close(sessionId: string): Promise<void>;\n  isLive(sessionId: string): boolean;\n  /** Reads a live child's ownership without starting a turn. */\n  readExecutionState?(\n    sessionId: string,\n    options?: Pick<PoHubSessionPromptOptions, 'parentSessionId'>,\n  ): Promise<PoHubSessionExecutionState>;\n  /** Starts a turn in a live session, as if its user had submitted `text`. */\n  prompt?(sessionId: string, text: string, options?: PoHubSessionPromptOptions): Promise<PoHubSessionPromptReceipt>;\n  /** Aborts the live session's current turn. The session stays open. */\n  abort?(sessionId: string, options?: Pick<PoHubSessionPromptOptions, 'parentSessionId'>): Promise<void>;\n  /**\n   * Adds guidance to a live session's running turn. A session with no turn in\n   * progress takes it as its next message instead.\n   */\n  steer?(\n    sessionId: string,\n    message: string,\n    options?: Pick<PoHubSessionPromptOptions, 'parentSessionId'>,\n  ): Promise<void>;\n  /**\n   * Stops a live session's runtime and keeps it dormant: its history stays\n   * readable where it is shown, and it can be woken later. A session that has\n   * done its work no longer holds a model, tools and extensions in the host.\n   */\n  release?(sessionId: string, options?: Pick<PoHubSessionPromptOptions, 'parentSessionId'>): Promise<void>;\n  readonly reservations?: PoHubSessionReservations;\n  /** Provisions a host-reserved Git worktree child. This is not exposed to remote MCP clients. */\n  provisionReservedWorktree?(request: PoHubReservedWorktreeRequest): Promise<PoHubSessionScope>;\n  /** Core host hook. A Git provider registers its implementation while its channel is mounted. */\n  registerReservedWorktreeProvisioner?(provisioner: PoHubReservedWorktreeProvisioner): () => void;\n  /**\n   * True when both live sessions have a direct parent-child relationship, or execute in the same\n   * checkout. Remote conversations only qualify through the parent-child relationship.\n   */\n  canCommunicate?(sourceSessionId: string, targetSessionId: string): boolean;\n  /** Core host hook. Session API construction removes this method before exposing the service to extensions. */\n  bindCommunication?(sessionId: string): PoSessionCommunicationEndpoint;\n}\n\nexport interface PoHubSessionApiRequest {\n  basePath: string;\n  path: string;\n  method: string;\n  body?: string | Uint8Array<ArrayBuffer> | null;\n  signal?: AbortSignal;\n  /** Forwarded by the authenticated host, including content type and trace context. */\n  headers?: RequestInit['headers'];\n}\n\nexport type PoComputerUseHostOperation = 'status' | 'targets' | 'activate' | 'observe' | 'act' | 'stop';\n\nexport interface PoComputerUseHostRequest {\n  readonly operation: PoComputerUseHostOperation;\n  readonly payload?: unknown;\n  readonly signal?: AbortSignal;\n}\n\nexport interface PoComputerUseHostBinding {\n  readonly available: boolean;\n  /** Global opt-in, separate from the presence of a native host. */\n  readonly enabled?: boolean;\n  request(scope: PoHubSessionScope, request: PoComputerUseHostRequest): Promise<unknown>;\n  /** Checks a proof injected by the owning Desktop process, never a renderer marker. */\n  authorize?(headers: Headers): boolean;\n  /** Pins a session to Desktop before asking for a native grant. Ownership is not persisted. */\n  claimSession?(sessionId: string, headers?: Headers): void;\n  ownsSession?(sessionId: string): boolean;\n  /** Server-authenticated paired identity, checked against live native approval for this session. */\n  authorizeSession?(sessionId: string, headers: Headers): boolean;\n  authorizeRecording?(sessionId: string, headers: Headers): boolean;\n  authorizeActivation?(headers: Headers): boolean;\n  /** Own pending activation only, never general session control. */\n  authorizePending?(sessionId: string, headers: Headers): boolean;\n  revokeDevice?(deviceId: string): void;\n  /**\n   * The Desktop window, or a paired device. A `change` (asking macOS for a permission) also\n   * needs the step-up activation needs. Independent of the computer-use setting.\n   */\n  authorizePermissions?(headers: Headers, change: boolean): boolean;\n  /** Desktop's macOS permission states, after asking macOS for `permission` when it is set. */\n  permissions?(permission?: string): Promise<unknown>;\n  readRecording?(scope: PoHubSessionScope, artifactId: string, range: string): Promise<Response>;\n  forgetSession?(sessionId: string): void;\n  /** Without `sessionId` the listener hears every session's ownership change. */\n  subscribe?(listener: () => void, sessionId?: string): () => void;\n  close?(): void;\n}\n\n/** Narrow, host-bound access. An extension cannot select another session's identity. */\nexport interface PoComputerUseSessionAccess {\n  readonly available: boolean;\n  readonly enabled?: boolean;\n  authorize(headers: Headers): boolean;\n  authorizeRecording?(headers: Headers): boolean;\n  authorizeActivation?(headers: Headers): boolean;\n  authorizePending?(headers: Headers): boolean;\n  claim(headers?: Headers): void;\n  fetchRecording?(artifactId: string, range: string): Promise<Response>;\n  subscribe(listener: () => void): () => void;\n}\n\nexport interface PoHubChannelConnection {\n  connectionId: string;\n  /** Host-verified native renderer proof, never copied from a channel payload. */\n  desktopAuthorized?: boolean;\n  /** Live session authorization evaluated by the host, never a client frame. */\n  computerUseAuthorized?: boolean;\n}\n\nexport interface PoHubChannelHost {\n  sessions(): readonly PoHubSessionScope[];\n  /** Host facts and storage for trusted in-process channels, never client-supplied roots. */\n  readonly homeDirectory?: string;\n  readonly sessionStorage?: PoSessionStorageService;\n  /** Canonical hub lifecycle for sessions created by channel commands. */\n  sessionService?: PoHubSessionService;\n  /** Same-process events emitted by session packages. */\n  readonly directEvents: PoDirectEventBus;\n  publish(sessionId: string, payload: unknown): void;\n  publishToConnection?(connectionId: string, sessionId: string, payload: unknown): boolean;\n  requestSessionApi(scope: PoHubSessionScope, request: PoHubSessionApiRequest): Promise<Response>;\n  computerUse?: PoComputerUseHostBinding;\n  onNotice(message: string): void;\n}\n\nexport interface PoHubChannelSource {\n  payloadFor(scope: PoHubSessionScope): unknown;\n  /** Read-only compact projection of already-owned state. Must not start work or add watchers. */\n  homeFor?(scope: PoHubSessionScope): HomeProjection;\n  sessionAdded?(scope: PoHubSessionScope): void;\n  sessionRemoved?(sessionId: string): void;\n  close(): void;\n}\n\nexport type PoHubChannelLifecycle = 'session' | 'hub';\n\nexport interface PoHubChannel {\n  frameType: string;\n  lifecycle?: PoHubChannelLifecycle;\n  start(host: PoHubChannelHost): PoHubChannelSource;\n  receiveWithoutSubscription?: boolean;\n  receive?(scope: PoHubSessionScope, payload: unknown, connection: PoHubChannelConnection): void;\n  disconnected?(connection: PoHubChannelConnection): void;\n}\n"],"mappings":";;;;;;;AAmFA,MAAa,mCAAmC;;;;;;;AAQhD,MAAa,yCAAyC;;AAGtD,MAAa,yCAAyC"}

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 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"}
+{"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  /** Desktop's macOS privacy permissions; present on hub mounts only when Desktop hosts this server. */\n  desktopPermissions?: {\n    /** A `change` asks macOS for a permission and needs the step-up computer-use activation needs. */\n    authorize(headers: Headers, change: boolean): boolean;\n    /** The permission states, after asking macOS for `permission` when it is set. */\n    request(permission?: string): Promise<unknown>;\n  };\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

@@ -286,6 +286,13 @@ export interface PoApiContext {
   requestApi?(mount: PoApiMount, basePath: string, request: Request): Promise<Response>;
   /** Present only on a session mounted by an authenticated Desktop host. */
   computerUse?: PoComputerUseSessionAccess;
+  /** Desktop's macOS privacy permissions; present on hub mounts only when Desktop hosts this server. */
+  desktopPermissions?: {
+    /** A `change` asks macOS for a permission and needs the step-up computer-use activation needs. */
+    authorize(headers: Headers, change: boolean): boolean;
+    /** The permission states, after asking macOS for `permission` when it is set. */
+    request(permission?: string): Promise<unknown>;
+  };
   /** 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. */

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

@@ -1 +1 @@
-{"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"}
+{"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;;IAEE,UAAU,SAAS,SAAS;;IAE5B,QAAQ,sBAAsB;;;EAGhC,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.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 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"}
+{"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  /** Desktop's macOS privacy permissions; present on hub mounts only when Desktop hosts this server. */\n  desktopPermissions?: {\n    /** A `change` asks macOS for a permission and needs the step-up computer-use activation needs. */\n    authorize(headers: Headers, change: boolean): boolean;\n    /** The permission states, after asking macOS for `permission` when it is set. */\n    request(permission?: string): Promise<unknown>;\n  };\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/web/types/nativeTemplate.d.mts

@@ -1,5 +1,5 @@
 import { WebTemplateRailActions, WebTemplateRailWorkspace } from "./template.mjs";
-import { ComponentType } from "react";
+import { ComponentType, ReactNode } from "react";
 //#region src/web/types/nativeTemplate.d.ts
 /**
  * The cockpit rail's actions a phone session list can call. The same names and results as
@@ -19,6 +19,11 @@ export interface NativeTemplateSessionsProps {
   workspaces: readonly WebTemplateRailWorkspace[];
   openSession: (sessionId: string) => void;
   actions: NativeTemplateSessionsActions;
+  /**
+   * Places one control beside the app's own screen title; `null` clears it. Optional because a
+   * template may be newer than the phone app, which then keeps the control in the body.
+   */
+  setHeaderAction?: (action: ReactNode) => void;
 }
 /** Screens a native template may replace. Any it leaves out stays the app's built-in screen. */
 export interface NativeTemplateScreens {

package/dist/src/web/types/nativeTemplate.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"nativeTemplate.d.mts","names":[],"sources":["../../../../src/web/types/nativeTemplate.ts"],"mappings":";;;;;;;;YASY,gCAAgC,KAC1C,8KAWA,QACE,KACE;;;;;;;;iBAkBW;;EAEf,qBAAqB;EACrB,cAAc;EACd,SAAS;;;iBAIM;EACf,WAAW,cAAc;;;iBAIV;EACf;EACA;EACA;EACA;EACA,SAAS"}
+{"version":3,"file":"nativeTemplate.d.mts","names":[],"sources":["../../../../src/web/types/nativeTemplate.ts"],"mappings":";;;;;;;;YASY,gCAAgC,KAC1C,8KAWA,QACE,KACE;;;;;;;;iBAkBW;;EAEf,qBAAqB;EACrB,cAAc;EACd,SAAS;;;;;EAKT,mBAAmB,QAAQ;;;iBAIZ;EACf,WAAW,cAAc;;;iBAIV;EACf;EACA;EACA;EACA;EACA,SAAS"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agimon-ai/po-core",
-  "version": "0.0.0-alpha.25",
+  "version": "0.0.0-alpha.26",
   "description": "Po runtime systems and reusable core services.",
   "keywords": [
     "ai",
@@ -529,8 +529,8 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@agimon-ai/po-telemetry": "0.0.0-alpha.25",
-    "@agimon-ai/po-web-security": "0.0.0-alpha.25",
+    "@agimon-ai/po-telemetry": "0.0.0-alpha.26",
+    "@agimon-ai/po-web-security": "0.0.0-alpha.26",
     "@deepseek-ai/cordis": "4.0.5",
     "@earendil-works/chord": "1.3.0",
     "@earendil-works/pi-agent-core": "1.3.0",
@@ -553,7 +553,7 @@
     "yaml": "2.9.1"
   },
   "devDependencies": {
-    "@agimon-ai/vibe-lint-plugin-po-core": "0.0.0-alpha.25",
+    "@agimon-ai/vibe-lint-plugin-po-core": "0.0.0-alpha.26",
     "@apidevtools/swagger-parser": "^13.1.0",
     "@asyncapi/parser": "^3.6.4",
     "@earendil-works/pi-ai": "1.3.0",