@agimon-ai/po-core 0.0.0-alpha.38 → 0.0.0-alpha.39

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';\nimport type { PoWorkflowContextService } from './workflow';\n\n/** Compact host-wide session attention, published over the existing direct event bus. */\nexport const PO_SESSION_ATTENTION_EVENT = 'po.session.attention';\n\nexport interface PoSessionAttention {\n  readonly name?: string;\n  readonly phase: 'idle' | 'turn' | 'compaction' | 'retry';\n  readonly awaitingInput: boolean;\n  readonly settledAt?: string;\n  readonly dialog?: {\n    readonly id: string;\n    readonly title: string;\n    readonly message?: string;\n    readonly purpose?: 'feedback';\n  };\n}\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\n/** Provenance of the host-wide Voice conversation that relays between the person and other sessions. */\nexport const VOICE_ORCHESTRATOR_SESSION_PROVENANCE = 'voice-orchestrator';\n\n/** A stopped session that keeps its record and can be revived. */\nexport interface PoHubDormantSession {\n  readonly sessionId: string;\n  readonly name: string;\n  readonly workspaceId: string;\n  readonly sessionProvenance?: string;\n}\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  /** Trusted in-process step bootstrap only. Never accepted from a remote request or persisted. */\n  readonly workflowContext?: PoWorkflowContextService;\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  /** This session's own group names, read live so group edits are reflected. */\n  readonly groups?: readonly 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  /** Every ready peer this session may message right now, including ones a later group edit made reachable. */\n  listPeers?(): readonly PoSessionPeerDescription[];\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  /** Global mount only: stopped sessions that keep their record. */\n  dormant?(): readonly PoHubDormantSession[];\n  /** Global mount only: reopens a stopped session under its own id. */\n  revive?(sessionId: string): 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  /** Global mount only: admits, or returns, the workspace in the host folder with this name. */\n  admitWorkspace?(request: { name: string }): Promise<{ id: string; root: string }>;\n  /** Global mount only: the host's admitted workspaces, read live. */\n  workspaces?(): readonly PoHubWorkspace[];\n}\n\nexport interface PoHubWorkspace {\n  readonly id: string;\n  readonly root: string;\n  readonly name?: string;\n  readonly available?: boolean;\n  /** Absent when the workspace runs on this host without a sandbox. */\n  readonly sandboxState?: 'starting' | 'running' | 'stopping' | 'unavailable' | 'failed';\n  readonly sandboxReason?: string;\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":";;AAMA,MAAa,6BAA6B;;;;;;;AA8F1C,MAAa,mCAAmC;;;;;;;AAQhD,MAAa,yCAAyC;;AAGtD,MAAa,yCAAyC;;AAGtD,MAAa,wCAAwC"}
+{"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';\nimport type { PoWorkflowContextService } from './workflow';\n\n/** Compact host-wide session attention, published over the existing direct event bus. */\nexport const PO_SESSION_ATTENTION_EVENT = 'po.session.attention';\n\nexport interface PoSessionAttention {\n  readonly name?: string;\n  readonly phase: 'idle' | 'turn' | 'compaction' | 'retry';\n  readonly awaitingInput: boolean;\n  readonly settledAt?: string;\n  readonly dialog?: {\n    readonly id: string;\n    readonly title: string;\n    readonly message?: string;\n    readonly purpose?: 'feedback';\n  };\n}\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\n/** Provenance of the host-wide Voice conversation that relays between the person and other sessions. */\nexport const VOICE_ORCHESTRATOR_SESSION_PROVENANCE = 'voice-orchestrator';\n\n/** A stopped session that keeps its record and can be revived. */\nexport interface PoHubDormantSession {\n  readonly sessionId: string;\n  readonly name: string;\n  readonly workspaceId: string;\n  readonly sessionProvenance?: string;\n}\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  /** Trusted in-process step bootstrap only. Never accepted from a remote request or persisted. */\n  readonly workflowContext?: PoWorkflowContextService;\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  /** This session's own group names, read live so group edits are reflected. */\n  readonly groups?: readonly 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  /** Every ready peer this session may message right now, including ones a later group edit made reachable. */\n  listPeers?(): readonly PoSessionPeerDescription[];\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  /** Global mount only: stopped sessions that keep their record. */\n  dormant?(): readonly PoHubDormantSession[];\n  /** Global mount only: reopens a stopped session under its own id. */\n  revive?(sessionId: string): 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  /** Global mount only: admits, or returns, the workspace in the host folder with this name. */\n  admitWorkspace?(request: { name: string }): Promise<{ id: string; root: string }>;\n  /** Global mount only: the host's admitted workspaces, read live. */\n  workspaces?(): readonly PoHubWorkspace[];\n}\n\nexport interface PoHubWorkspace {\n  readonly id: string;\n  readonly root: string;\n  readonly name?: string;\n  readonly available?: boolean;\n  /** The sandbox provider that runs this workspace; absent means it runs on this host. */\n  readonly sandbox?: string;\n  /**\n   * The sandbox's live state. On a workspace that runs on this host, `unavailable` only means the sandbox\n   * cannot be switched on now; its sessions still run here.\n   */\n  readonly sandboxState?: 'starting' | 'running' | 'stopping' | 'unavailable' | 'failed';\n  readonly sandboxReason?: string;\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":";;AAMA,MAAa,6BAA6B;;;;;;;AA8F1C,MAAa,mCAAmC;;;;;;;AAQhD,MAAa,yCAAyC;;AAGtD,MAAa,yCAAyC;;AAGtD,MAAa,wCAAwC"}

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

@@ -329,7 +329,12 @@ export interface PoHubWorkspace {
   readonly root: string;
   readonly name?: string;
   readonly available?: boolean;
-  /** Absent when the workspace runs on this host without a sandbox. */
+  /** The sandbox provider that runs this workspace; absent means it runs on this host. */
+  readonly sandbox?: string;
+  /**
+   * The sandbox's live state. On a workspace that runs on this host, `unavailable` only means the sandbox
+   * cannot be switched on now; its sessions still run here.
+   */
   readonly sandboxState?: 'starting' | 'running' | 'stopping' | 'unavailable' | 'failed';
   readonly sandboxReason?: string;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"hubChannel.d.mts","names":[],"sources":["../../../src/schemas/hubChannel.ts"],"mappings":"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"}
+{"version":3,"file":"hubChannel.d.mts","names":[],"sources":["../../../src/schemas/hubChannel.ts"],"mappings":"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"}

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';\nimport type { PoWorkflowContextService } from './workflow';\n\n/** Compact host-wide session attention, published over the existing direct event bus. */\nexport const PO_SESSION_ATTENTION_EVENT = 'po.session.attention';\n\nexport interface PoSessionAttention {\n  readonly name?: string;\n  readonly phase: 'idle' | 'turn' | 'compaction' | 'retry';\n  readonly awaitingInput: boolean;\n  readonly settledAt?: string;\n  readonly dialog?: {\n    readonly id: string;\n    readonly title: string;\n    readonly message?: string;\n    readonly purpose?: 'feedback';\n  };\n}\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\n/** Provenance of the host-wide Voice conversation that relays between the person and other sessions. */\nexport const VOICE_ORCHESTRATOR_SESSION_PROVENANCE = 'voice-orchestrator';\n\n/** A stopped session that keeps its record and can be revived. */\nexport interface PoHubDormantSession {\n  readonly sessionId: string;\n  readonly name: string;\n  readonly workspaceId: string;\n  readonly sessionProvenance?: string;\n}\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  /** Trusted in-process step bootstrap only. Never accepted from a remote request or persisted. */\n  readonly workflowContext?: PoWorkflowContextService;\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  /** This session's own group names, read live so group edits are reflected. */\n  readonly groups?: readonly 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  /** Every ready peer this session may message right now, including ones a later group edit made reachable. */\n  listPeers?(): readonly PoSessionPeerDescription[];\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  /** Global mount only: stopped sessions that keep their record. */\n  dormant?(): readonly PoHubDormantSession[];\n  /** Global mount only: reopens a stopped session under its own id. */\n  revive?(sessionId: string): 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  /** Global mount only: admits, or returns, the workspace in the host folder with this name. */\n  admitWorkspace?(request: { name: string }): Promise<{ id: string; root: string }>;\n  /** Global mount only: the host's admitted workspaces, read live. */\n  workspaces?(): readonly PoHubWorkspace[];\n}\n\nexport interface PoHubWorkspace {\n  readonly id: string;\n  readonly root: string;\n  readonly name?: string;\n  readonly available?: boolean;\n  /** Absent when the workspace runs on this host without a sandbox. */\n  readonly sandboxState?: 'starting' | 'running' | 'stopping' | 'unavailable' | 'failed';\n  readonly sandboxReason?: string;\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":";;AAMA,MAAa,6BAA6B;;;;;;;AA8F1C,MAAa,mCAAmC;;;;;;;AAQhD,MAAa,yCAAyC;;AAGtD,MAAa,yCAAyC;;AAGtD,MAAa,wCAAwC"}
+{"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';\nimport type { PoWorkflowContextService } from './workflow';\n\n/** Compact host-wide session attention, published over the existing direct event bus. */\nexport const PO_SESSION_ATTENTION_EVENT = 'po.session.attention';\n\nexport interface PoSessionAttention {\n  readonly name?: string;\n  readonly phase: 'idle' | 'turn' | 'compaction' | 'retry';\n  readonly awaitingInput: boolean;\n  readonly settledAt?: string;\n  readonly dialog?: {\n    readonly id: string;\n    readonly title: string;\n    readonly message?: string;\n    readonly purpose?: 'feedback';\n  };\n}\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\n/** Provenance of the host-wide Voice conversation that relays between the person and other sessions. */\nexport const VOICE_ORCHESTRATOR_SESSION_PROVENANCE = 'voice-orchestrator';\n\n/** A stopped session that keeps its record and can be revived. */\nexport interface PoHubDormantSession {\n  readonly sessionId: string;\n  readonly name: string;\n  readonly workspaceId: string;\n  readonly sessionProvenance?: string;\n}\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  /** Trusted in-process step bootstrap only. Never accepted from a remote request or persisted. */\n  readonly workflowContext?: PoWorkflowContextService;\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  /** This session's own group names, read live so group edits are reflected. */\n  readonly groups?: readonly 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  /** Every ready peer this session may message right now, including ones a later group edit made reachable. */\n  listPeers?(): readonly PoSessionPeerDescription[];\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  /** Global mount only: stopped sessions that keep their record. */\n  dormant?(): readonly PoHubDormantSession[];\n  /** Global mount only: reopens a stopped session under its own id. */\n  revive?(sessionId: string): 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  /** Global mount only: admits, or returns, the workspace in the host folder with this name. */\n  admitWorkspace?(request: { name: string }): Promise<{ id: string; root: string }>;\n  /** Global mount only: the host's admitted workspaces, read live. */\n  workspaces?(): readonly PoHubWorkspace[];\n}\n\nexport interface PoHubWorkspace {\n  readonly id: string;\n  readonly root: string;\n  readonly name?: string;\n  readonly available?: boolean;\n  /** The sandbox provider that runs this workspace; absent means it runs on this host. */\n  readonly sandbox?: string;\n  /**\n   * The sandbox's live state. On a workspace that runs on this host, `unavailable` only means the sandbox\n   * cannot be switched on now; its sessions still run here.\n   */\n  readonly sandboxState?: 'starting' | 'running' | 'stopping' | 'unavailable' | 'failed';\n  readonly sandboxReason?: string;\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":";;AAMA,MAAa,6BAA6B;;;;;;;AA8F1C,MAAa,mCAAmC;;;;;;;AAQhD,MAAa,yCAAyC;;AAGtD,MAAa,yCAAyC;;AAGtD,MAAa,wCAAwC"}

package/dist/src/server/directHarnessRuntime.cjs

@@ -129,6 +129,7 @@ async function createLaneRuntime(options, attached) {
 		let activeNames = new Set(options.activeToolNames ?? tools.map((t) => t.name));
 		let settings = {
 			extensions: [{ name: "po.host" }],
+			documentRetentionMs: 6e4,
 			stream: options.streamOptions,
 			retry: options.retry,
 			compaction: options.compaction,