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

package/dist/headlessHub.d.mts

@@ -1,10 +1,14 @@
-import { DoomComputerUseHostBinding, DoomDirectEventBus, DoomHubChannel, DoomHubSessionApiRequest, DoomHubSessionCreateRequest, DoomHubSessionReservations, DoomHubSessionScope, DoomHubSessionService, DoomPendingSessionSetup, DoomSessionActivity } from "./src/schemas/hubChannel.mjs";
-import { DoomApiContext, DoomApiMount, DoomNativeComposition, DoomWebComposition } from "./src/schemas/packageApi.mjs";
-import { DoomPluginCaller, DoomPluginDirection, DoomPluginRegistry } from "./src/schemas/pluginProtocol.mjs";
-import { DoomServerFacet } from "./src/schemas/serverFacet.mjs";
+import { PoPlatform } from "./src/schemas/platform.mjs";
+import { PoChildThread } from "./src/systems/child/types/childSession.mjs";
+import { HomeRequest, HomeSnapshot } from "./src/schemas/home.mjs";
+import { PoComputerUseHostBinding, PoDirectEventBus, PoHubChannel, PoHubSessionApiRequest, PoHubSessionCreateRequest, PoHubSessionReservations, PoHubSessionScope, PoHubSessionService, PoPendingSessionSetup, PoSessionActivity } from "./src/schemas/hubChannel.mjs";
+import { PoApiContext, PoApiMount, PoEditPresenceLedger, PoNativeComposition, PoWebComposition } from "./src/schemas/packageApi.mjs";
+import { PoPluginCaller, PoPluginDirection, PoPluginRegistry } from "./src/schemas/pluginProtocol.mjs";
+import { PoServerPlugin } from "./src/schemas/serverPlugin.mjs";
 import "./hubChannel.mjs";
-import { LoadedServerFacet } from "./src/server/serverFacetLoader.mjs";
-import "./serverFacet.mjs";
+import { LoadedServerPackage } from "./src/server/serverPackages.mjs";
+import { PoServerScope } from "./src/server/serverScope.mjs";
+import "./serverPlugin.mjs";
 import "./packageApi.mjs";
 import { HeadlessSessionHost, HeadlessSessionHostOptions } from "./headlessSessionHost.mjs";
 import { HeadlessSessionCloseOptions, HeadlessSessionManager } from "./runtimeHeadlessSessionManager.mjs";
@@ -26,13 +30,15 @@ export interface HeadlessProfileIdentity {
 export interface HeadlessHubSession {
   readonly id: string;
   readonly workspaceId?: string;
-  webComposition?: DoomWebComposition;
-  nativeComposition?: DoomNativeComposition;
+  webComposition?: PoWebComposition;
+  nativeComposition?: PoNativeComposition;
   readonly name: string;
   readonly cwd: string;
   readonly createdAt: string;
   readonly parentSessionId?: string;
   readonly sessionProvenance?: string;
+  /** User-assigned groups; sessions sharing one may message each other. Empty when none. */
+  readonly groups?: readonly string[];
   readonly updatedAt?: string;
   readonly phase?: 'idle' | 'turn' | 'compaction' | 'retry';
   readonly phaseSince?: string;
@@ -40,13 +46,15 @@ export interface HeadlessHubSession {
   readonly everPrompted?: boolean;
   readonly awaitingInput?: boolean;
   readonly lastSettledAt?: string;
+  /** Authoritative session-owned work; null is unknown, absent is an older host. */
+  readonly backgroundWorkActive?: boolean | null;
   /** Branch and dirty flag of the session cwd; absent outside a git work tree. */
   readonly git?: SessionGitStatus;
   /** Selected profile; absent when the session runs without one. */
   readonly profile?: HeadlessSessionProfile;
-  readonly pendingSetups?: readonly DoomPendingSessionSetup[];
+  readonly pendingSetups?: readonly PoPendingSessionSetup[];
   /** The line the session's extension last published about work it runs; absent when none. */
-  readonly activity?: DoomSessionActivity;
+  readonly activity?: PoSessionActivity;
   /** Environment admitted for this session, when supplied by the host. */
   readonly environment?: Readonly<Record<string, string | undefined>>;
   readonly host: HeadlessSessionHost;
@@ -71,6 +79,11 @@ export type HeadlessHubEvent = {
   kind: 'removed';
   sessionId: string;
   dormant?: true;
+} |
+/** A dormant session's record changed; clients reread it from the dormant list. */
+{
+  kind: 'dormant_changed';
+  sessionId: string;
 } | {
   kind: 'workspace_upsert';
   workspace: HeadlessWorkspace;
@@ -92,34 +105,43 @@ export type HeadlessHubEvent = {
 };
 export interface HeadlessHubOptions {
   manager: HeadlessSessionManager;
+  /** Host capabilities for the global and workspace scope roots, injected by the composition root. */
+  platform: PoPlatform;
   /** Resolves the hub credential, because the server reads its token file after the hub exists. */
   hubToken?: () => string | undefined;
   /** Creates a session through the canonical cockpit lifecycle for hub channels. */
-  createSession?: (request: DoomHubSessionCreateRequest,
+  createSession?: (request: PoHubSessionCreateRequest,
   /**
    * Set when a workspace-mounted package creates a session with no parent. The host must
    * refuse a cwd outside that workspace before admitting anything.
    */
   placement?: {
     workspaceId: string;
-  }) => Promise<DoomHubSessionScope>;
+  }) => Promise<PoHubSessionScope>;
   onNotice?: (message: string) => void;
-  sessionReservations?: DoomHubSessionReservations;
-  requestSessionApi?: (scope: DoomHubSessionScope, request: DoomHubSessionApiRequest) => Promise<Response>;
-  computerUse?: DoomComputerUseHostBinding;
+  sessionReservations?: PoHubSessionReservations;
+  requestSessionApi?: (scope: PoHubSessionScope, request: PoHubSessionApiRequest) => Promise<Response>;
+  computerUse?: PoComputerUseHostBinding;
   admitWorkspace?: (request: HeadlessWorkspaceAdmission) => Promise<HeadlessWorkspace>;
   onWorkspaceRemoved?: (workspaceId: string) => void;
   /** Reads a session cwd's git status; defaults to the git CLI. */
   readGitStatus?: (cwd: string) => Promise<SessionGitStatus | undefined>;
   /** Resolves a profile's persona presentation for a workspace root; sessions show no avatar without it. */
   resolveProfileIdentity?: (root: string, profile: string) => HeadlessProfileIdentity | undefined;
+  /**
+   * Publishes a session's web and native compositions for one major mode of a workspace root,
+   * so the session mounts only that mode's plugins. Called when the session registers and
+   * whenever its major mode changes; without it a session keeps its creation compositions.
+   */
+  publishSessionCompositions?: (sessionId: string, root: string, majorMode: string) => Pick<HeadlessHubSession, 'webComposition' | 'nativeComposition'>;
 }
 export interface HeadlessHub {
   /** Canonical direct lifecycle shared by hub channels, APIs, and sessions. */
-  readonly sessionService: DoomHubSessionService;
-  /** Lifecycle-owned event path shared by session facets and hub channels. */
-  readonly directEvents: DoomDirectEventBus;
-  readonly computerUse?: DoomComputerUseHostBinding;
+  readonly sessionService: PoHubSessionService;
+  /** Lifecycle-owned event path shared by session packages and hub channels. */
+  readonly directEvents: PoDirectEventBus;
+  readonly computerUse?: PoComputerUseHostBinding;
+  readHome?(request: HomeRequest, authorizeSession: (sessionId: string) => boolean): Promise<HomeSnapshot>;
   snapshot(): readonly HeadlessHubSession[];
   session(sessionId: string): HeadlessHubSession | undefined;
   runtime(sessionId: string): HeadlessSessionHost['runtime'] | undefined;
@@ -134,38 +156,51 @@ export interface HeadlessHub {
   closeSession(sessionId: string, options?: HeadlessSessionCloseOptions): Promise<void>;
   /** Publishes removal of a persisted session that has no live host. */
   notifySessionRemoved(sessionId: string): void;
+  /** Publishes a changed record of a persisted session that has no live host. */
+  notifyDormantChanged(sessionId: string): void;
   /** Publishes setup-only children through the parent's normal session updates. */
-  setPendingSessionSetups?(sessionId: string, pending: readonly DoomPendingSessionSetup[]): void;
+  setPendingSessionSetups?(sessionId: string, pending: readonly PoPendingSessionSetup[]): void;
   /** Replaces the session's activity line; undefined clears it. Unknown sessions are ignored. */
-  setSessionActivity?(sessionId: string, activity: DoomSessionActivity | undefined): void;
+  setSessionActivity?(sessionId: string, activity: PoSessionActivity | undefined): void;
   /** Dispatches an authenticated package API request inside the owning process. */
-  requestSessionApi(scope: DoomHubSessionScope, request: DoomHubSessionApiRequest): Promise<Response>;
-  /** Mounts the selected hub facets once, before the headless server accepts clients. */
-  mountFacets(facets: readonly (DoomServerFacet | LoadedServerFacet)[], context?: DoomApiContext): Promise<void>;
+  requestSessionApi(scope: PoHubSessionScope, request: PoHubSessionApiRequest): Promise<Response>;
+  /**
+   * Publishes a global or workspace scope's host, one mount table for the life of the scope, built
+   * from `context` (the global scope by default), then installs its first `packages`. A workspace
+   * is announced available only once they install. When any step fails the scope is discarded with
+   * whatever it installed, so serving it again starts clean.
+   */
+  serveScope(context?: PoApiContext, packages?: readonly (PoServerPlugin | LoadedServerPackage)[]): Promise<void>;
+  /**
+   * Installs packages into a served global or workspace scope. Installation only adds: a package
+   * already installed from the same build is skipped, one whose build changed is replaced (and its
+   * previous build restored when the new one fails), and one missing from `packages` stays.
+   */
+  installPackages(mount: PoApiMount, packages: readonly (PoServerPlugin | LoadedServerPackage)[]): Promise<void>;
   /**
-   * Swaps a mounted global or workspace scope to a new facet set, with the context it was
-   * mounted with. The old facets unwind through the same path `removeWorkspace` uses before
-   * the new ones apply, so their API base paths and channels can be claimed again. When the
-   * new set fails to install, the previous facets are reinstalled and the error is rethrown.
+   * The scope a session's own scope opens below: its workspace's when it has one, else the global
+   * scope. Contracts bound at those levels reach the session's packages as native services.
    */
-  replaceFacets(mount: DoomApiMount, facets: readonly (DoomServerFacet | LoadedServerFacet)[]): Promise<void>;
+  sessionParentScope(workspaceId: string | undefined): Promise<PoServerScope>;
   workspaces(): readonly HeadlessWorkspace[];
   registerWorkspace(workspace: HeadlessWorkspace): void;
   admitWorkspace(request: HeadlessWorkspaceAdmission): Promise<HeadlessWorkspace>;
   removeWorkspace(workspaceId: string): Promise<void>;
-  requestApi(mount: DoomApiMount, basePath: string, request: Request): Promise<Response>;
-  /** The dispatch table hub facets mount into, shared with session hosts this hub serves. */
-  readonly pluginRegistry: DoomPluginRegistry;
-  invokePlugin(call: unknown, direction: DoomPluginDirection, caller?: DoomPluginCaller): Promise<unknown>;
-  registerChannel(channel: DoomHubChannel, mount?: DoomApiMount): () => void;
+  requestApi(mount: PoApiMount, basePath: string, request: Request): Promise<Response>;
+  /** The dispatch table hub packages mount into, shared with session hosts this hub serves. */
+  readonly pluginRegistry: PoPluginRegistry;
+  /** The edit presence ledger shared by every session host this hub serves. */
+  readonly editPresence: PoEditPresenceLedger;
+  invokePlugin(call: unknown, direction: PoPluginDirection, caller?: PoPluginCaller): Promise<unknown>;
+  registerChannel(channel: PoHubChannel, mount?: PoApiMount): () => void;
   channelTypes(): readonly string[];
   channelFrames(sessionId: string): Array<{
     type: string;
     sessionId: string;
     payload: unknown;
   }>;
-  /** Resolves a channel-owned child journal for the browser thread projection. */
-  threadJournal(sessionId: string, threadId: string): string | undefined;
+  /** A child run of the session, for the browser thread projection. */
+  childThread(sessionId: string, threadId: string): PoChildThread | undefined;
   receiveChannel(sessionId: string, frameType: string, payload: unknown, connectionId: string, desktopAuthorized?: boolean, computerUseAuthorized?: boolean): void;
   disconnectChannels(connectionId: string): void;
   close(): Promise<void>;

package/dist/headlessHub.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"headlessHub.d.mts","names":[],"sources":["../src/server/headlessHub.ts"],"mappings":";;;;;;;;;;;;;;iBAkDiB;WACN;WACA;;WAEA;;;iBAIM;WACN;WACA;;iBAGM;WACN;WACA;EACT,iBAAiB;EACjB,oBAAoB;WACX;WACA;WACA;WACA;WACA;WACA;WACA;WACA;WACA;WACA;WACA;WACA;;WAEA,MAAM;;WAEN,UAAU;WACV,yBAAyB;;WAEzB,WAAW;;WAEX,cAAc,SAAS;WACvB,MAAM;;iBAGA;WACN;WACA;WACA;WACA;;;iBAIM;WACN;WACA;;YAGC;EACN;EAAgB,SAAS;;;;EAEzB;EAAiB;EAAmB;;EACpC;EAA0B,WAAW;;EACrC;EAA2B;;EAC3B;EAAiB;EAAmB;EAAmB;EAAkB;;;;EAEzE;EAAe;EAAmB,OAAO;;iBAE9B;EACf,SAAS;;EAET;;EAEA,iBACE,SAAS,6BAKT;;;;;EAAA;IAAc;QACX,QAAQ;EACb,YAAY;EACZ,sBAAsB;EACtB,qBAAqB,OAAO,qBAAqB,SAAS,6BAA6B,QAAQ;EAC/F,cAAc;EACd,kBAAkB,SAAS,+BAA+B,QAAQ;EAClE,sBAAsB;;EAEtB,iBAAiB,gBAAgB,QAAQ;;EAEzC,0BAA0B,cAAc,oBAAoB;;iBAG7C;;WAEN,gBAAgB;;WAEhB,cAAc;WACd,cAAc;EACvB,qBAAqB;EACrB,QAAQ,oBAAoB;EAC5B,QAAQ,oBAAoB;;EAE5B,cAAc;IAAsB;IAAkB,OAAO;;EAC7D,QAAQ,WAAW,OAAO;EAC1B,SAAS,SAAS;EAClB,OAAO,SAAS,6BAA6B,QAAQ;EACrD,aAAa,mBAAmB,UAAU,8BAA8B;;EAExE,qBAAqB;;EAErB,yBAAyB,mBAAmB,kBAAkB;;EAE9D,oBAAoB,mBAAmB,UAAU;;EAEjD,kBAAkB,OAAO,qBAAqB,SAAS,2BAA2B,QAAQ;;EAE1F,YAAY,kBAAkB,kBAAkB,sBAAsB,UAAU,iBAAiB;;;;;;;EAOjG,cAAc,OAAO,cAAc,kBAAkB,kBAAkB,uBAAuB;EAC9F,uBAAuB;EACvB,kBAAkB,WAAW;EAC7B,eAAe,SAAS,6BAA6B,QAAQ;EAC7D,gBAAgB,sBAAsB;EACtC,WAAW,OAAO,cAAc,kBAAkB,SAAS,UAAU,QAAQ;;WAEpE,gBAAgB;EACzB,aAAa,eAAe,WAAW,qBAAqB,SAAS,mBAAmB;EACxF,gBAAgB,SAAS,gBAAgB,QAAQ;EACjD;EACA,cAAc,oBAAoB;IAAQ;IAAc;IAAmB;;;EAE3E,cAAc,mBAAmB;EACjC,eACE,mBACA,mBACA,kBACA,sBACA,6BACA;EAEF,mBAAmB;EACnB,SAAS;;;wBAuCK,kBAAkB,SAAS,qBAAqB"}
+{"version":3,"file":"headlessHub.d.mts","names":[],"sources":["../src/server/headlessHub.ts"],"mappings":";;;;;;;;;;;;;;;;;;iBAkEiB;WACN;WACA;;WAEA;;;iBAIM;WACN;WACA;;iBAGM;WACN;WACA;EACT,iBAAiB;EACjB,oBAAoB;WACX;WACA;WACA;WACA;WACA;;WAEA;WACA;WACA;WACA;WACA;WACA;WACA;WACA;;WAEA;;WAEA,MAAM;;WAEN,UAAU;WACV,yBAAyB;;WAEzB,WAAW;;WAEX,cAAc,SAAS;WACvB,MAAM;;iBAGA;WACN;WACA;WACA;WACA;;;iBAIM;WACN;WACA;;YAGC;EACN;EAAgB,SAAS;;;;EAEzB;EAAiB;EAAmB;;;;EAEpC;EAAyB;;EACzB;EAA0B,WAAW;;EACrC;EAA2B;;EAC3B;EAAiB;EAAmB;EAAmB;EAAkB;;;;EAEzE;EAAe;EAAmB,OAAO;;iBAE9B;EACf,SAAS;;EAET,UAAU;;EAEV;;EAEA,iBACE,SAAS;;;;;EAKT;IAAc;QACX,QAAQ;EACb,YAAY;EACZ,sBAAsB;EACtB,qBAAqB,OAAO,mBAAmB,SAAS,2BAA2B,QAAQ;EAC3F,cAAc;EACd,kBAAkB,SAAS,+BAA+B,QAAQ;EAClE,sBAAsB;;EAEtB,iBAAiB,gBAAgB,QAAQ;;EAEzC,0BAA0B,cAAc,oBAAoB;;;;;;EAM5D,8BACE,mBACA,cACA,sBACG,KAAK;;iBAGK;;WAEN,gBAAgB;;WAEhB,cAAc;WACd,cAAc;EACvB,UAAU,SAAS,aAAa,mBAAmB,gCAAgC,QAAQ;EAC3F,qBAAqB;EACrB,QAAQ,oBAAoB;EAC5B,QAAQ,oBAAoB;;EAE5B,cAAc;IAAsB;IAAkB,OAAO;;EAC7D,QAAQ,WAAW,OAAO;EAC1B,SAAS,SAAS;EAClB,OAAO,SAAS,6BAA6B,QAAQ;EACrD,aAAa,mBAAmB,UAAU,8BAA8B;;EAExE,qBAAqB;;EAErB,qBAAqB;;EAErB,yBAAyB,mBAAmB,kBAAkB;;EAE9D,oBAAoB,mBAAmB,UAAU;;EAEjD,kBAAkB,OAAO,mBAAmB,SAAS,yBAAyB,QAAQ;;;;;;;EAOtF,WAAW,UAAU,cAAc,qBAAqB,iBAAiB,yBAAyB;;;;;;EAMlG,gBAAgB,OAAO,YAAY,oBAAoB,iBAAiB,yBAAyB;;;;;EAKjG,mBAAmB,kCAAkC,QAAQ;EAC7D,uBAAuB;EACvB,kBAAkB,WAAW;EAC7B,eAAe,SAAS,6BAA6B,QAAQ;EAC7D,gBAAgB,sBAAsB;EACtC,WAAW,OAAO,YAAY,kBAAkB,SAAS,UAAU,QAAQ;;WAElE,gBAAgB;;WAEhB,cAAc;EACvB,aAAa,eAAe,WAAW,mBAAmB,SAAS,iBAAiB;EACpF,gBAAgB,SAAS,cAAc,QAAQ;EAC/C;EACA,cAAc,oBAAoB;IAAQ;IAAc;IAAmB;;;EAE3E,YAAY,mBAAmB,mBAAmB;EAClD,eACE,mBACA,mBACA,kBACA,sBACA,6BACA;EAEF,mBAAmB;EACnB,SAAS;;;wBAoDK,kBAAkB,SAAS,qBAAqB"}