@threadbase-sh/streamer 1.43.0 → 1.44.0

package/dist/index.d.cts

@@ -192,6 +192,11 @@ interface ManagedSession {
      * Cleared implicitly when a resume overwrites the stub with a real session.
      */
     rehydrated?: boolean;
+    /**
+     * This live session was re-adopted from the pty-host during boot rather than
+     * spawned by this streamer process. Internal lifecycle provenance only.
+     */
+    reconciled?: boolean;
     /**
      * What this session was doing when the streamer stopped it, for a stub whose
      * `status` had to flatten to `idle`. Only ever set from a registry row whose
@@ -276,7 +281,7 @@ type WSMessage = {
     reworkAttempt?: number;
 } | {
     type: "session_list";
-    sessions: SessionResponse[];
+    sessions: readonly SessionResponse[];
 } | {
     type: "conversation_event";
     sessionId: string;
@@ -488,7 +493,8 @@ interface ConversationListResponse {
 type SessionSortKey = "startedAt" | "lastActivityAt" | "projectName" | "status";
 type SortOrder = "asc" | "desc";
 interface SessionListPage {
-    sessions: SessionResponse[];
+    /** Response copies, like `SessionStore.list()` — see the note there. */
+    sessions: readonly Readonly<SessionResponse>[];
     nextCursor: string | null;
     total: number;
 }
@@ -1392,11 +1398,21 @@ declare class SessionStore {
     initAgentSession(sessionId: string, dedupeCapacity: number): void;
     updateManaged(sessionId: string, updates: Partial<ManagedSession>): ManagedSession | null;
     removeManaged(sessionId: string): boolean;
+    /**
+     * The **live** stored record — mutating it mutates the store. Paired with
+     * `get()`, which hands back a throwaway response copy. Prefer
+     * `updateManaged()` for writes; this is for readers that need the internal
+     * shape (Date fields, `rehydrated`, …) rather than the wire shape.
+     */
     getManaged(sessionId: string): ManagedSession | null;
     setDiscovered(processes: DiscoveredProcess[]): void;
+    /**
+     * The **live** stored records — mutating an element mutates the store. Paired
+     * with `list()`, which hands back throwaway response copies.
+     */
     listManaged(): ManagedSession[];
-    list(ptyAttachedIds: Set<string>): SessionResponse[];
-    get(sessionId: string, ptyAttachedIds: Set<string>): SessionResponse | null;
+    list(ptyAttachedIds: Set<string>): readonly Readonly<SessionResponse>[];
+    get(sessionId: string, ptyAttachedIds: Set<string>): Readonly<SessionResponse> | null;
     paginate(ptyAttachedIds: Set<string>, query: SessionListQuery): SessionListPage;
 }
 
@@ -1450,9 +1466,30 @@ declare class RuntimeStore {
     close(): void;
 }
 
+interface HostHeartbeatState {
+    registryState: "known" | "unknown";
+    referencedSessionIds: string[];
+}
+/**
+ * A duplex line channel. Deliberately not a socket: the runner is tested
+ * against an in-memory pair, and PR 7 supplies the real one over a unix socket
+ * (POSIX) or named pipe (Windows).
+ */
+interface HostTransport {
+    send(line: string): void;
+    onLine(handler: (line: string) => void): void;
+    onClose(handler: () => void): void;
+    close(): void;
+}
+
 declare class LiveSessionManager {
     private runners;
+    private remoteRunner;
+    private options;
     constructor(options?: PTYManagerOptions);
+    useRemoteRunner(transport: HostTransport): Promise<ManagedSession[]>;
+    isRemote(): boolean;
+    startRemoteHeartbeat(getState: () => HostHeartbeatState): void;
     start(sessionId: string, options: StartSessionOptions & {
         provider?: ProviderName;
     }): Promise<ManagedSession>;
@@ -1474,6 +1511,7 @@ declare class LiveSessionManager {
     dispose(): void;
     private runnerFor;
     private assertSupportedProvider;
+    private activeRunners;
 }
 
 declare class WSHub {
@@ -1960,6 +1998,8 @@ declare class StreamerServer {
      * it is set once that rollout has been discovered.
      */
     private spawnArgvToken;
+    /** Restore registry-only metadata after the host mirror has been adopted. */
+    private refreshHostedSessionsFromRegistry;
     /**
      * Mirror a freshly-spawned session into the durable registry (C1 Phase 2).
      *

package/dist/index.d.ts

@@ -192,6 +192,11 @@ interface ManagedSession {
      * Cleared implicitly when a resume overwrites the stub with a real session.
      */
     rehydrated?: boolean;
+    /**
+     * This live session was re-adopted from the pty-host during boot rather than
+     * spawned by this streamer process. Internal lifecycle provenance only.
+     */
+    reconciled?: boolean;
     /**
      * What this session was doing when the streamer stopped it, for a stub whose
      * `status` had to flatten to `idle`. Only ever set from a registry row whose
@@ -276,7 +281,7 @@ type WSMessage = {
     reworkAttempt?: number;
 } | {
     type: "session_list";
-    sessions: SessionResponse[];
+    sessions: readonly SessionResponse[];
 } | {
     type: "conversation_event";
     sessionId: string;
@@ -488,7 +493,8 @@ interface ConversationListResponse {
 type SessionSortKey = "startedAt" | "lastActivityAt" | "projectName" | "status";
 type SortOrder = "asc" | "desc";
 interface SessionListPage {
-    sessions: SessionResponse[];
+    /** Response copies, like `SessionStore.list()` — see the note there. */
+    sessions: readonly Readonly<SessionResponse>[];
     nextCursor: string | null;
     total: number;
 }
@@ -1392,11 +1398,21 @@ declare class SessionStore {
     initAgentSession(sessionId: string, dedupeCapacity: number): void;
     updateManaged(sessionId: string, updates: Partial<ManagedSession>): ManagedSession | null;
     removeManaged(sessionId: string): boolean;
+    /**
+     * The **live** stored record — mutating it mutates the store. Paired with
+     * `get()`, which hands back a throwaway response copy. Prefer
+     * `updateManaged()` for writes; this is for readers that need the internal
+     * shape (Date fields, `rehydrated`, …) rather than the wire shape.
+     */
     getManaged(sessionId: string): ManagedSession | null;
     setDiscovered(processes: DiscoveredProcess[]): void;
+    /**
+     * The **live** stored records — mutating an element mutates the store. Paired
+     * with `list()`, which hands back throwaway response copies.
+     */
     listManaged(): ManagedSession[];
-    list(ptyAttachedIds: Set<string>): SessionResponse[];
-    get(sessionId: string, ptyAttachedIds: Set<string>): SessionResponse | null;
+    list(ptyAttachedIds: Set<string>): readonly Readonly<SessionResponse>[];
+    get(sessionId: string, ptyAttachedIds: Set<string>): Readonly<SessionResponse> | null;
     paginate(ptyAttachedIds: Set<string>, query: SessionListQuery): SessionListPage;
 }
 
@@ -1450,9 +1466,30 @@ declare class RuntimeStore {
     close(): void;
 }
 
+interface HostHeartbeatState {
+    registryState: "known" | "unknown";
+    referencedSessionIds: string[];
+}
+/**
+ * A duplex line channel. Deliberately not a socket: the runner is tested
+ * against an in-memory pair, and PR 7 supplies the real one over a unix socket
+ * (POSIX) or named pipe (Windows).
+ */
+interface HostTransport {
+    send(line: string): void;
+    onLine(handler: (line: string) => void): void;
+    onClose(handler: () => void): void;
+    close(): void;
+}
+
 declare class LiveSessionManager {
     private runners;
+    private remoteRunner;
+    private options;
     constructor(options?: PTYManagerOptions);
+    useRemoteRunner(transport: HostTransport): Promise<ManagedSession[]>;
+    isRemote(): boolean;
+    startRemoteHeartbeat(getState: () => HostHeartbeatState): void;
     start(sessionId: string, options: StartSessionOptions & {
         provider?: ProviderName;
     }): Promise<ManagedSession>;
@@ -1474,6 +1511,7 @@ declare class LiveSessionManager {
     dispose(): void;
     private runnerFor;
     private assertSupportedProvider;
+    private activeRunners;
 }
 
 declare class WSHub {
@@ -1960,6 +1998,8 @@ declare class StreamerServer {
      * it is set once that rollout has been discovered.
      */
     private spawnArgvToken;
+    /** Restore registry-only metadata after the host mirror has been adopted. */
+    private refreshHostedSessionsFromRegistry;
     /**
      * Mirror a freshly-spawned session into the durable registry (C1 Phase 2).
      *