@pellux/goodvibes-tui 1.7.0 → 1.9.0

package/src/runtime/session-inbound-inputs.ts

@@ -0,0 +1,252 @@
+/**
+ * session-inbound-inputs.ts
+ *
+ * D3 (One-Platform Wave 2, live-surface steer delivery — the inbound half of the
+ * session spine): the TUI's INBOUND path for steer/follow-up inputs that another
+ * live surface (e.g. the webui) queued against THIS TUI's session.
+ *
+ * Charter: when the owning surface is LIVE (heartbeating within the daemon's
+ * SURFACE_ROUTE_FRESHNESS window), a steer is DELIVERED to that surface rather
+ * than spawning a daemon-side executor (which would fail on the daemon's empty
+ * model registry). The daemon already does its half — `sessions.steer` /
+ * `sessions.followUp` to a surface-managed session with a fresh participant
+ * QUEUES the input for the surface (mode 'queued-for-surface') instead of
+ * spawning. This poller is the surface completing that contract:
+ *
+ *   1. poll `sessions.inputs.list` for QUEUED inputs on ITS OWN sessionId
+ *      (the query is scoped by sessionId, so a steer for another session can
+ *      never land here — the per-session isolation the concurrent-sessions
+ *      charter requires);
+ *   2. hand each steer/follow-up to `onSteer` (the surface-side injection into
+ *      the TUI's turn machinery — narrate "steer received from <surface>" and
+ *      fire the next-turn boundary), skipping the TUI's own submissions;
+ *   3. acknowledge on the wire via `sessions.inputs.deliver` (queued → delivered)
+ *      so every surface sees delivery truth live and the input is not re-picked.
+ *
+ * Discipline (mirrors SessionSpineClient): every wire call is best-effort and
+ * never throws into the render/keystroke path; a failed poll leaves the cursor
+ * where it was so the input is retried on the next tick (deliver is the only
+ * de-dup — an input already advanced past 'queued' is not returned again).
+ */
+
+import { logger } from '@pellux/goodvibes-sdk/platform/utils';
+import type {
+  SharedSessionInputIntent,
+  SharedSessionInputRecord,
+} from '@pellux/goodvibes-sdk/platform/control-plane';
+
+/** The TUI's own participant surfaceId — inputs it authored are never re-injected. */
+export const TUI_SURFACE_ID = 'surface:tui';
+
+/** The narrow inbound wire surface this poller needs. Structurally satisfied by
+ * the http operator client's `sessions.inputs` (list + deliver). Typed against
+ * this shape rather than the concrete client so tests inject a stub. */
+export interface SpineInboundInputsClient {
+  listInputs(
+    sessionId: string,
+    options: { readonly state?: string; readonly since?: number; readonly limit?: number },
+  ): Promise<{ readonly inputs: readonly SharedSessionInputRecord[] }>;
+  deliverInput(
+    sessionId: string,
+    inputId: string,
+    options?: { readonly consumed?: boolean },
+  ): Promise<unknown>;
+}
+
+/** A steer/follow-up collected from the wire for surface-side injection. */
+export interface InboundSteer {
+  readonly inputId: string;
+  readonly sessionId: string;
+  readonly intent: SharedSessionInputIntent;
+  readonly body: string;
+  readonly surfaceKind: string | undefined;
+  readonly surfaceId: string | undefined;
+  readonly displayName: string | undefined;
+}
+
+type InboundLogger = Pick<typeof logger, 'debug' | 'info'>;
+
+export interface SessionInboundInputPollerOptions {
+  /** Returns the TUI's current live sessionId, or null when there is none yet.
+   * Read on every tick so a session swap re-targets the poll automatically. */
+  readonly sessionId: () => string | null;
+  /** Surface-side injection: narrate + deliver the steer into the turn machinery. */
+  readonly onSteer: (steer: InboundSteer) => void;
+  readonly intervalMs?: number;
+  readonly now?: () => number;
+  readonly log?: InboundLogger;
+  /** The poller's own surfaceId — inputs it authored are skipped (default TUI). */
+  readonly ownSurfaceId?: string;
+}
+
+const DEFAULT_POLL_INTERVAL_MS = 4_000;
+
+export class SessionInboundInputPoller {
+  private readonly sessionId: () => string | null;
+  private readonly onSteer: (steer: InboundSteer) => void;
+  private readonly intervalMs: number;
+  private readonly now: () => number;
+  private readonly log: InboundLogger;
+  private readonly ownSurfaceId: string;
+
+  private client: SpineInboundInputsClient | null = null;
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private polling = false;
+  /** Exclusive createdAt cursor, per session — a session swap resets it. */
+  private cursor = 0;
+  private cursorSessionId: string | null = null;
+
+  constructor(options: SessionInboundInputPollerOptions) {
+    this.sessionId = options.sessionId;
+    this.onSteer = options.onSteer;
+    this.intervalMs = Math.max(250, options.intervalMs ?? DEFAULT_POLL_INTERVAL_MS);
+    this.now = options.now ?? (() => Date.now());
+    this.log = options.log ?? logger;
+    this.ownSurfaceId = options.ownSurfaceId ?? TUI_SURFACE_ID;
+  }
+
+  /** Whether a backend is attached (external daemon adopted). */
+  get active(): boolean {
+    return this.client !== null;
+  }
+
+  /**
+   * Attach the wire client and begin polling (external daemon adopted). Idempotent:
+   * re-activating swaps the client without stacking timers.
+   */
+  activate(client: SpineInboundInputsClient): void {
+    this.client = client;
+    if (this.timer === null) {
+      this.timer = setInterval(() => { void this.pollOnce(); }, this.intervalMs);
+      this.timer.unref?.();
+    }
+    this.log.info('session inbound-input poller activated — collecting queued steers for this surface', {});
+  }
+
+  /** Detach the backend and stop polling (daemon mode resolved to non-external, or lost). */
+  deactivate(reason: string): void {
+    this.client = null;
+    if (this.timer !== null) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    this.log.info('session inbound-input poller deactivated', { reason });
+  }
+
+  /** Stop the timer (shutdown). */
+  dispose(): void {
+    if (this.timer !== null) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+
+  /**
+   * One poll pass: collect queued steer/follow-up inputs for the current session,
+   * inject each, and acknowledge delivery. Returns the number of steers delivered.
+   * Best-effort: any wire error is absorbed and the pass is retried next tick.
+   */
+  async pollOnce(): Promise<number> {
+    const client = this.client;
+    if (!client || this.polling) return 0;
+    const sessionId = this.sessionId();
+    if (!sessionId) return 0;
+
+    // A session swap resets the cursor so we never skip the new session's backlog.
+    if (sessionId !== this.cursorSessionId) {
+      this.cursor = 0;
+      this.cursorSessionId = sessionId;
+    }
+
+    this.polling = true;
+    let delivered = 0;
+    try {
+      const result = await client.listInputs(sessionId, { state: 'queued', since: this.cursor });
+      const inputs = result?.inputs ?? [];
+      for (const input of inputs) {
+        // Advance the cursor across every queued input we observe (even skipped
+        // ones) so it is monotonic; deliver() is the real de-dup for injected ones.
+        if (input.createdAt > this.cursor) this.cursor = input.createdAt;
+
+        if (input.state !== 'queued') continue;
+        if (input.intent !== 'steer' && input.intent !== 'follow-up') continue;
+        // Never re-inject this surface's OWN submissions.
+        if (input.surfaceId === this.ownSurfaceId) continue;
+
+        const steer: InboundSteer = {
+          inputId: input.id,
+          sessionId,
+          intent: input.intent,
+          body: input.body,
+          surfaceKind: input.surfaceKind,
+          surfaceId: input.surfaceId,
+          displayName: input.displayName,
+        };
+        try {
+          this.onSteer(steer);
+        } catch (error) {
+          // A failing injection must not wedge the poll loop or drop the ack —
+          // narrate-and-continue; the input is still acked so it is not re-picked.
+          this.log.debug('session inbound steer injection threw — continuing', {
+            error: error instanceof Error ? error.message : String(error),
+          });
+        }
+        try {
+          // consumed:false → queued → delivered (surface has collected it).
+          await client.deliverInput(sessionId, input.id, { consumed: false });
+          delivered += 1;
+        } catch (error) {
+          this.log.debug('session inbound deliver ack failed — will retry', {
+            error: error instanceof Error ? error.message : String(error),
+          });
+        }
+      }
+    } catch (error) {
+      // Poll failed entirely (daemon gone, transient): keep the cursor, retry next tick.
+      this.log.debug('session inbound-input poll failed — retry next tick', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+    } finally {
+      this.polling = false;
+    }
+    return delivered;
+  }
+}
+
+/** Format the operator-facing narration for an inbound steer, e.g.
+ * "steer received from webui (Alice): resize the panel". */
+export function narrateInboundSteer(steer: InboundSteer): string {
+  const surface = steer.surfaceKind ?? steer.surfaceId ?? 'another surface';
+  const who = steer.displayName ? ` (${steer.displayName})` : '';
+  const verb = steer.intent === 'follow-up' ? 'follow-up received from' : 'steer received from';
+  return `${verb} ${surface}${who}: ${steer.body}`;
+}
+
+/**
+ * Build the standard bootstrap-time poller: sessionId tracks the live runtime
+ * session ref, and onSteer narrates the steer to the operator then injects it
+ * via the SAME path COMPANION_MESSAGE_RECEIVED uses (orchestrator.handleUserInput
+ * when wired, else a bare conversation append + render request as a fallback
+ * before the orchestrator ref is patched). Extracted from bootstrap-core.ts to
+ * keep this module (not the bootstrap god-function) the owner of the wiring.
+ */
+export function createBootstrapInboundInputPoller(deps: {
+  readonly runtimeSessionIdRef: { readonly value: string };
+  readonly routeOrBuffer: (text: string, priority: 'low' | 'high') => void;
+  readonly orchestratorHandleUserInputRef: { readonly value: ((text: string) => void) | null };
+  readonly conversation: { readonly addUserMessage: (text: string) => void };
+  readonly requestRender: () => void;
+}): SessionInboundInputPoller {
+  return new SessionInboundInputPoller({
+    sessionId: () => deps.runtimeSessionIdRef.value || null,
+    onSteer: (steer) => {
+      deps.routeOrBuffer(narrateInboundSteer(steer), 'low');
+      if (deps.orchestratorHandleUserInputRef.value) {
+        deps.orchestratorHandleUserInputRef.value(steer.body);
+      } else {
+        deps.conversation.addUserMessage(steer.body);
+        deps.requestRender();
+      }
+    },
+  });
+}

package/src/runtime/session-spine-transport.ts

@@ -0,0 +1,64 @@
+/**
+ * session-spine-transport.ts
+ *
+ * W3-T1 (One-Platform Wave 3, TUI session-spine cutover): the thin typed-client
+ * adapter that lets the TUI's bootstrap drive the SDK's
+ * `@pellux/goodvibes-sdk/platform/runtime/session-spine` `SessionSpineClient`
+ * (extracted in W3-S4) via its injected `SpineTransport` seam.
+ *
+ * The TUI is SDK-clean here: `SpineSessionsClient` is exactly the narrow wire
+ * surface the old TUI-local `session-spine-client.ts` declared (structurally
+ * satisfied by `HttpTransport.operator.sessions`), and `createTuiSpineTransport`
+ * folds it into the SDK's `SpineTransport` the SAME way the SDK's own
+ * consumability proof (`session-spine-daemon-integration.test.ts`) does:
+ * resolve -> `'ok'`, throw -> `'offline'`. The TUI never emits `'rejected'` — it
+ * has no durable-refusal vocabulary to fold (that distinction is the agent's
+ * REST mirror's job, per the SDK's divergence ruling #6/#7).
+ */
+import type {
+  RegisterSharedSessionInput,
+  SharedSessionRecord,
+  SharedSessionRegisterResult,
+} from '@pellux/goodvibes-sdk/platform/control-plane';
+import type { SpineResult, SpineTransport } from '@pellux/goodvibes-sdk/platform/runtime/session-spine';
+
+/**
+ * The minimal wire surface this adapter needs. Structurally satisfied by BOTH
+ * the SDK's in-process `OperatorClient['sessions']` (DirectTransport) and the
+ * wire `HttpTransportOperatorClient['sessions']` (HttpTransport) — bootstrap.ts
+ * only ever constructs an Http-backed instance in practice, but this is
+ * deliberately typed against the narrow shape rather than either concrete
+ * transport type so it has no compile-time dependency on which transport
+ * backs it.
+ */
+export interface SpineSessionsClient {
+  register(input: RegisterSharedSessionInput): Promise<SharedSessionRegisterResult>;
+  close(sessionId: string): Promise<SharedSessionRecord | null>;
+}
+
+/**
+ * Adapt the TUI's typed `SpineSessionsClient` into the SDK `SessionSpineClient`'s
+ * injected `SpineTransport`. A rejecting wire call is treated as a transient
+ * connectivity fault (`'offline'`) rather than a durable refusal — the same
+ * binary reachability model the pre-extraction TUI-local client used.
+ */
+export function createTuiSpineTransport(sessionsClient: SpineSessionsClient): SpineTransport {
+  return {
+    register: async (input: RegisterSharedSessionInput): Promise<SpineResult> => {
+      try {
+        await sessionsClient.register(input);
+        return { outcome: 'ok' };
+      } catch (error) {
+        return { outcome: 'offline', error: error instanceof Error ? error.message : String(error) };
+      }
+    },
+    close: async (sessionId: string): Promise<SpineResult> => {
+      try {
+        await sessionsClient.close(sessionId);
+        return { outcome: 'ok' };
+      } catch (error) {
+        return { outcome: 'offline', error: error instanceof Error ? error.message : String(error) };
+      }
+    },
+  };
+}

package/src/runtime/terminal-output-guard.ts

@@ -40,7 +40,14 @@ export type TuiTerminalOutputGuardOptions = {
   readonly stdout: WritableStreamLike;
   readonly stderr?: WritableStreamLike;
   readonly active?: boolean;
-  readonly notify: (message: string) => void;
+  /**
+   * Called (rate-limited) after intercepts with the cumulative count of direct
+   * writes captured this session, so an honest quiet counter (e.g. /debug) can
+   * refresh. The per-write detail is already recorded to the activity log via
+   * logger.warn — this callback intentionally does NOT push transcript lines.
+   * (UX-B item 1a.)
+   */
+  readonly onCapture?: (total: number) => void;
 };
 
 const MAX_LOG_TEXT = 4_000;
@@ -208,21 +215,21 @@ export function installTerminalOutputGuard(options: TerminalOutputGuardOptions):
 }
 
 export function installTuiTerminalOutputGuard(options: TuiTerminalOutputGuardOptions): TerminalOutputGuard {
-  let capturedWriteCount = 0;
+  let totalInterceptedWrites = 0;
   let lastNoticeAt = 0;
   return installTerminalOutputGuard({
     stdout: options.stdout,
     stderr: options.stderr,
     active: options.active,
-    onIntercept: (event) => {
-      capturedWriteCount++;
+    onIntercept: () => {
+      // Each intercept is already logged (logger.warn in record()). Here we only
+      // maintain a cumulative counter and, rate-limited, refresh a quiet counter
+      // surface — no repeated transcript lines. (UX-B item 1a.)
+      totalInterceptedWrites++;
       const now = Date.now();
       if (now - lastNoticeAt < 5_000) return;
-      const count = capturedWriteCount;
-      capturedWriteCount = 0;
       lastNoticeAt = now;
-      const plural = count === 1 ? '' : 's';
-      options.notify(`[Terminal] Captured ${count} direct ${event.source} write${plural} that would have corrupted the TUI: ${event.preview}`);
+      options.onCapture?.(totalInterceptedWrites);
     },
   });
 }

package/src/runtime/ui-services.ts

@@ -6,7 +6,7 @@ import { createUiReadModels, type UiReadModels, type UiReadModelOptions } from '
 import type { ForensicsRegistry } from '@/runtime/index.ts';
 import type { ControlPlaneRecentEvent } from '@pellux/goodvibes-sdk/platform/control-plane';
 import type { ApprovalBroker } from '@pellux/goodvibes-sdk/platform/control-plane';
-import type { SharedSessionBroker } from '@pellux/goodvibes-sdk/platform/control-plane';
+import { SessionUnionCache, type SessionReadFacade } from '@pellux/goodvibes-sdk/platform/runtime/session-spine';
 import type { ShellPathService } from '@/runtime/index.ts';
 import type { HostServiceStatus } from '@/runtime/index.ts';
 import type { SecretsManager } from '../config/secrets.ts';
@@ -39,7 +39,13 @@ export interface UiProviderServices {
 
 export interface UiSessionServices {
   readonly sessionManager: RuntimeServices['sessionManager'];
-  readonly sessionBroker: SharedSessionBroker;
+  /**
+   * The panel-facing session READ source is the cross-surface union
+   * facade, not the raw local broker — in adopted-daemon ('external') mode the
+   * local broker misses sessions hosted for other surfaces. Sync signature
+   * preserved; the facade's cache makes that honest (see session-union-cache.ts).
+   */
+  readonly sessionBroker: SessionReadFacade;
   readonly sessionOrchestration: RuntimeServices['sessionOrchestration'];
   readonly sessionMemoryStore: RuntimeServices['sessionMemoryStore'];
 }
@@ -65,6 +71,10 @@ export interface UiPlatformServices {
       readonly httpListenerPortInUse?: boolean;
       readonly daemonStatus?: HostServiceStatus;
       readonly httpListenerStatus?: HostServiceStatus;
+      // Honest session-spine posture for the footer segment, driven by
+      // the spine client's own live wire attempts (not the one-shot adopt probe).
+      readonly sessionSpineActive?: boolean;
+      readonly sessionSpineStatus?: 'unknown' | 'online' | 'offline';
     };
     restart(): Promise<{
       readonly daemonRunning: boolean;
@@ -126,6 +136,12 @@ export interface UiRuntimeServices {
 export interface UiRuntimeServicesOptions extends UiReadModelOptions {
   readonly forensicsRegistry?: ForensicsRegistry;
   readonly getControlPlaneRecentEvents?: (limit: number) => readonly ControlPlaneRecentEvent[];
+  /**
+   * The shared session read facade constructed in bootstrap-core (so
+   * bootstrap.ts can drive its adopted-external/embedded/local mode). When omitted
+   * (test callers), a local-only passthrough facade over the broker is auto-created.
+   */
+  readonly sessionUnionCache?: SessionUnionCache;
 }
 
 export function createUiRuntimeServices(
@@ -157,7 +173,7 @@ export function createUiRuntimeServices(
     },
     sessions: {
       sessionManager: runtimeServices.sessionManager,
-      sessionBroker: runtimeServices.sessionBroker,
+      sessionBroker: options.sessionUnionCache ?? new SessionUnionCache({ local: runtimeServices.sessionBroker }),
       sessionOrchestration: runtimeServices.sessionOrchestration,
       sessionMemoryStore: runtimeServices.sessionMemoryStore,
     },