@pellux/goodvibes-tui 1.27.0 → 2.0.1

package/src/runtime/client/hosted-roster.ts

@@ -0,0 +1,110 @@
+/**
+ * hosted-roster.ts — the last answer the daemon gave about what it is hosting.
+ *
+ * The session picker is where a person goes to ask "what sessions are there?",
+ * and the honest answer includes conversations running inside the
+ * daemon — not only this terminal's saved transcripts and the cross-surface
+ * union. The picker is a synchronous render over modal state, though, and
+ * `sessions.hosted.list` is a round trip. This roster is the seam between them:
+ * it holds the last list the daemon answered with, refreshes on demand, and
+ * says plainly when it has never been able to ask.
+ *
+ * ── Never a fabricated empty list ─────────────────────────────────────────
+ *
+ * `capturedAt === null` means nobody has successfully read the roster yet,
+ * which is a different fact from "the daemon hosts nothing" and renders
+ * differently. A refresh that fails keeps the LAST known rows and records the
+ * reason, on the same reasoning the fleet poller keeps its rows through a blip:
+ * a momentary refusal should not make half the picker blink out.
+ *
+ * ── Why the client is bound rather than passed ────────────────────────────
+ *
+ * The picker is constructed in the input layer, which has no config manager and
+ * no home directory to resolve a daemon from. The composition root
+ * (runtime/services.ts) has both and already builds the verb caller, so it binds
+ * the client here once — the same shape the shared notification feed uses for a
+ * surface that two unrelated layers read.
+ */
+import type { HostedSessionRecord, HostedSessionsClient } from './hosted-sessions.ts';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+
+export interface HostedRosterSnapshot {
+  readonly sessions: readonly HostedSessionRecord[];
+  /** When the daemon last answered, or null when it never has. */
+  readonly capturedAt: number | null;
+  /** Why the roster is not current. Null when the last read succeeded. */
+  readonly note: string | null;
+}
+
+const NEVER_READ: HostedRosterSnapshot = { sessions: [], capturedAt: null, note: null };
+
+export class HostedSessionRoster {
+  private state: HostedRosterSnapshot = NEVER_READ;
+  private client: HostedSessionsClient | null = null;
+  private readonly listeners = new Set<() => void>();
+  private inFlight: Promise<void> | null = null;
+
+  bindClient(client: HostedSessionsClient | null): void {
+    this.client = client;
+  }
+
+  snapshot(): HostedRosterSnapshot {
+    return this.state;
+  }
+
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener);
+    return () => { this.listeners.delete(listener); };
+  }
+
+  /** Record a list a caller already has in hand (the `/hosted list` path). */
+  accept(sessions: readonly HostedSessionRecord[]): void {
+    this.state = { sessions, capturedAt: Date.now(), note: null };
+    this.emit();
+  }
+
+  /**
+   * Ask the daemon again. Never throws and never runs twice at once — a picker
+   * opened repeatedly must not stack round trips.
+   */
+  async refresh(): Promise<void> {
+    if (this.inFlight) return await this.inFlight;
+    const client = this.client;
+    if (!client) {
+      this.state = {
+        ...this.state,
+        note: 'no daemon client is wired in this terminal, so hosted sessions cannot be listed',
+      };
+      this.emit();
+      return;
+    }
+    this.inFlight = (async () => {
+      try {
+        this.accept(await client.list());
+      } catch (error) {
+        this.state = { ...this.state, note: `the daemon did not answer: ${summarizeError(error)}` };
+        this.emit();
+      } finally {
+        this.inFlight = null;
+      }
+    })();
+    await this.inFlight;
+  }
+
+  private emit(): void {
+    for (const listener of [...this.listeners]) listener();
+  }
+}
+
+let sharedRoster: HostedSessionRoster | null = null;
+
+/** The one roster the session picker reads and the composition root feeds. */
+export function getSharedHostedSessionRoster(): HostedSessionRoster {
+  sharedRoster ??= new HostedSessionRoster();
+  return sharedRoster;
+}
+
+/** Tests build their own roster; this resets the shared one between them. */
+export function resetSharedHostedSessionRoster(): void {
+  sharedRoster = null;
+}

package/src/runtime/client/hosted-session-stream.ts

@@ -0,0 +1,178 @@
+/**
+ * hosted-session-stream.ts — watching a conversation that is running somewhere
+ * else.
+ *
+ * A hosted session's loop is the ORDINARY Orchestrator, composed inside the
+ * daemon. So it emits exactly what a local turn emits — STREAM_DELTA, tool
+ * starts, tool results, turn transitions — on the `turn` and `tools` runtime
+ * domains, and the control-plane forwards those domains to any subscriber with
+ * the session id stamped on every envelope. There is no hosted-only token
+ * stream to consume and this file does not invent one: it opens the same event
+ * stream a client already uses and keeps the frames whose id matches the
+ * session it was told to watch.
+ *
+ * The third domain is `session`, which carries `hosted-session-update` — the
+ * lifecycle channel: created, attached, detached, turn started, turn ended,
+ * terminated, restored. That is how an attached terminal learns its session was
+ * killed from another surface, or that a turn started that it did not begin.
+ *
+ * ── Why a refused stream is a value, not a throw ──────────────────────────
+ *
+ * The same reasoning the SDK's approval-update watcher records: a stream can be
+ * refused (no daemon, a 401, a proxy that will not hold a connection), and the
+ * caller must still be able to act on the session over the verbs. `watch`
+ * resolves to null instead of throwing, and the caller says so honestly rather
+ * than pretending the conversation ended.
+ */
+import { openServerSentEventStream } from '@/runtime/index.ts';
+import { logger, summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+import type { HostedSessionUpdatePayload } from '@pellux/goodvibes-sdk/platform/hosted-sessions';
+
+/** The domains a hosted session's whole story arrives on. */
+export const HOSTED_SESSION_STREAM_DOMAINS = ['turn', 'tools', 'session'] as const;
+
+/** The wire event name the daemon publishes hosted lifecycle notices on. */
+export const HOSTED_SESSION_LIFECYCLE_WIRE_EVENT = 'hosted-session-update';
+
+/** One runtime-domain frame, already narrowed to the watched session. */
+export interface HostedSessionStreamEvent {
+  readonly domain: 'turn' | 'tools';
+  /** The runtime event type, e.g. STREAM_DELTA, TOOL_EXECUTING, TURN_COMPLETED. */
+  readonly type: string;
+  readonly sessionId: string;
+  readonly at: number;
+  readonly payload: Record<string, unknown>;
+}
+
+export interface WatchHostedSessionOptions {
+  /** The daemon's base URL, e.g. `http://127.0.0.1:3421`. */
+  readonly baseUrl: string;
+  /** The hosted session id to keep frames for. Everything else is discarded. */
+  readonly sessionId: string;
+  readonly getAuthToken?: (() => string | null | Promise<string | null>) | undefined;
+  /** Every turn/tools frame belonging to this session. */
+  readonly onEvent: (event: HostedSessionStreamEvent) => void;
+  /** Every lifecycle transition of this session. */
+  readonly onLifecycle?: ((update: HostedSessionUpdatePayload) => void) | undefined;
+  /** The stream dropped for good. The caller decides what to say about it. */
+  readonly onTerminate?: ((error: unknown) => void) | undefined;
+  readonly fetchImpl?: typeof fetch | undefined;
+  readonly signal?: AbortSignal | undefined;
+}
+
+/** A live subscription. `close()` is idempotent. */
+export interface HostedSessionSubscription {
+  close(): void;
+}
+
+/**
+ * The control-plane events URL narrowed to the three domains a hosted session
+ * speaks on. Narrowing matters: an unnarrowed subscriber receives every domain
+ * the daemon publishes, which for a client watching one conversation is a great
+ * deal of traffic it would immediately discard.
+ */
+export function hostedSessionStreamUrl(baseUrl: string): string {
+  const url = new URL('/api/control-plane/events', baseUrl);
+  url.searchParams.set('domains', HOSTED_SESSION_STREAM_DOMAINS.join(','));
+  return url.toString();
+}
+
+/** Read a serialized runtime envelope, or null when the frame is not one. */
+export function readHostedStreamEnvelope(
+  domain: 'turn' | 'tools',
+  payload: unknown,
+): HostedSessionStreamEvent | null {
+  if (typeof payload !== 'object' || payload === null) return null;
+  const envelope = payload as Record<string, unknown>;
+  const type = envelope['type'];
+  const sessionId = envelope['sessionId'];
+  if (typeof type !== 'string' || type.length === 0) return null;
+  if (typeof sessionId !== 'string' || sessionId.length === 0) return null;
+  const body = envelope['payload'];
+  return {
+    domain,
+    type,
+    sessionId,
+    at: typeof envelope['ts'] === 'number' ? envelope['ts'] : Date.now(),
+    payload: typeof body === 'object' && body !== null ? body as Record<string, unknown> : {},
+  };
+}
+
+/** Read a hosted lifecycle notice, or null when the frame is not one. */
+export function readHostedLifecycleNotice(payload: unknown): HostedSessionUpdatePayload | null {
+  if (typeof payload !== 'object' || payload === null) return null;
+  const record = payload as Record<string, unknown>;
+  const session = record['session'];
+  const event = record['event'];
+  if (typeof event !== 'string' || typeof session !== 'object' || session === null) return null;
+  if (typeof (session as Record<string, unknown>)['id'] !== 'string') return null;
+  return record as unknown as HostedSessionUpdatePayload;
+}
+
+/**
+ * Open a subscription to one hosted session's live output.
+ *
+ * Resolves to null when the stream could not be opened; the reason is logged
+ * once rather than thrown into a keystroke path, and the caller keeps whatever
+ * it had (the verbs still work — the conversation is simply not being watched).
+ */
+export async function watchHostedSession(
+  options: WatchHostedSessionOptions,
+): Promise<HostedSessionSubscription | null> {
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+  if (typeof fetchImpl !== 'function') {
+    logger.debug('[hosted-sessions] no fetch implementation is available for the session stream');
+    return null;
+  }
+  const deliver = (event: HostedSessionStreamEvent): void => {
+    if (event.sessionId !== options.sessionId) return;
+    try {
+      options.onEvent(event);
+    } catch (error) {
+      // A throwing subscriber must not take the stream down for itself.
+      logger.debug('[hosted-sessions] a stream subscriber threw', { error: summarizeError(error) });
+    }
+  };
+  try {
+    const close = await openServerSentEventStream(
+      fetchImpl,
+      hostedSessionStreamUrl(options.baseUrl),
+      {
+        onEvent: (eventName, payload) => {
+          if (eventName === 'turn' || eventName === 'tools') {
+            const event = readHostedStreamEnvelope(eventName, payload);
+            if (event) deliver(event);
+            return;
+          }
+          if (eventName !== HOSTED_SESSION_LIFECYCLE_WIRE_EVENT) return;
+          const notice = readHostedLifecycleNotice(payload);
+          if (!notice || notice.session.id !== options.sessionId) return;
+          try {
+            options.onLifecycle?.(notice);
+          } catch (error) {
+            logger.debug('[hosted-sessions] a lifecycle subscriber threw', { error: summarizeError(error) });
+          }
+        },
+        onTerminate: ({ error }) => options.onTerminate?.(error),
+      },
+      {
+        ...(options.getAuthToken ? { getAuthToken: options.getAuthToken } : {}),
+        ...(options.signal ? { signal: options.signal } : {}),
+      },
+    );
+    let closed = false;
+    return {
+      close: (): void => {
+        if (closed) return;
+        closed = true;
+        close();
+      },
+    };
+  } catch (error) {
+    logger.info('[hosted-sessions] the session stream could not be opened; the session is still steerable over its verbs', {
+      sessionId: options.sessionId,
+      error: summarizeError(error),
+    });
+    return null;
+  }
+}

package/src/runtime/client/hosted-sessions.ts

@@ -0,0 +1,187 @@
+/**
+ * hosted-sessions.ts — this terminal's handle on a conversation the DAEMON runs.
+ *
+ * A local session's loop lives in this process: the orchestrator, the tools and
+ * the permission gate are all here, and closing the terminal ends the work. A
+ * HOSTED session is the same loop composed on the other side of the wire, in
+ * the daemon, driven by the five `sessions.hosted.*` verbs. Local stays the
+ * default experience; hosting is something the user asks for.
+ *
+ * ── What this module is, and what it deliberately is not ──────────────────
+ *
+ * It is the five lifecycle verbs plus the ORDINARY session verbs a hosted id
+ * also answers to. There is no `sessions.hosted.steer` and this file does not
+ * invent one: `sessions.steer`, `sessions.followUp` and
+ * `sessions.toolCalls.cancel` resolve a hosted session's id daemon-side, so
+ * steering a hosted conversation is the same call as steering any other. Two
+ * spellings of one action is how they drift apart.
+ *
+ * It is not the stream. The hosted loop is the ordinary Orchestrator, so its
+ * tokens, tool calls and turn transitions arrive on the `turn` and `tools`
+ * event domains stamped with the hosted session's id — see
+ * hosted-session-stream.ts, which watches exactly what a local session watches
+ * and filters on the id `attach` handed back.
+ *
+ * ── Why the verbs go through DaemonVerbCaller ─────────────────────────────
+ *
+ * Every `sessions.hosted.*` verb is declared `transport: ['ws']` with no REST
+ * path of its own, so `sdk.operator.invoke` refuses them before making a
+ * request. `createDaemonVerbCaller` (operator-endpoint.ts) already handles that
+ * exact class by falling through to the generic gateway route — which IS the
+ * binding for a ws-declared verb reached over HTTP.
+ */
+import { hostname } from 'node:os';
+import type {
+  CreateHostedSessionInput,
+  HostedDetachPolicy,
+  HostedSessionHistoryMessage,
+  HostedSessionRecord,
+} from '@pellux/goodvibes-sdk/platform/hosted-sessions';
+import type { DaemonVerbCaller } from './operator-endpoint.ts';
+
+export type {
+  CreateHostedSessionInput,
+  HostedDetachPolicy,
+  HostedSessionHistoryMessage,
+  HostedSessionRecord,
+};
+
+/** What `sessions.hosted.attach` answers with: the record, and what was said so far. */
+export interface HostedSessionAttachment {
+  readonly session: HostedSessionRecord;
+  readonly history: readonly HostedSessionHistoryMessage[];
+}
+
+/**
+ * How this terminal names itself to the daemon when it attaches.
+ *
+ * It has to be stable for the life of the process and distinct between two
+ * terminals on one machine, because the detach policy is applied when the LAST
+ * client leaves: two windows sharing one id would make the first `detach` look
+ * like the last one. Host + pid is both, and it is readable in
+ * `attachedClients` — a person reading the record can tell which terminal that
+ * is.
+ */
+let cachedClientId: string | null = null;
+export function terminalHostedClientId(): string {
+  cachedClientId ??= `tui-${hostname()}-${process.pid}`;
+  return cachedClientId;
+}
+
+/** The narrow client the command layer and the panel share. */
+export interface HostedSessionsClient {
+  /** This terminal's attach identity — the same string the records carry. */
+  readonly clientId: string;
+  list(options?: { readonly includeTerminated?: boolean }): Promise<readonly HostedSessionRecord[]>;
+  create(input: Omit<CreateHostedSessionInput, 'clientId'>): Promise<HostedSessionRecord>;
+  attach(sessionId: string): Promise<HostedSessionAttachment>;
+  detach(sessionId: string): Promise<HostedSessionRecord>;
+  kill(sessionId: string): Promise<HostedSessionRecord>;
+  /** Send a message into a running hosted session — the ordinary steer verb. */
+  steer(sessionId: string, body: string): Promise<void>;
+  /** Queue a message for after the current turn — the ordinary follow-up verb. */
+  followUp(sessionId: string, body: string): Promise<void>;
+  /** Cancel one in-flight tool call — the ordinary live-turn verb. */
+  cancelToolCall(sessionId: string, callId: string): Promise<boolean>;
+}
+
+/**
+ * Drop the keys a verb was not given a value for.
+ *
+ * The gateway validates against the declared input schema and a present-but-
+ * undefined property is not the same as an absent one on the wire; sending
+ * `{ title: undefined }` is how a caller that meant "no title" gets a
+ * validation refusal instead.
+ */
+function withoutUndefined(input: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(input)) {
+    if (value !== undefined) out[key] = value;
+  }
+  return out;
+}
+
+export function createHostedSessionsClient(verbs: DaemonVerbCaller): HostedSessionsClient {
+  const clientId = terminalHostedClientId();
+  return {
+    clientId,
+    async list(options): Promise<readonly HostedSessionRecord[]> {
+      const result = await verbs.invoke<{ sessions: readonly HostedSessionRecord[] }>(
+        'sessions.hosted.list',
+        withoutUndefined({ includeTerminated: options?.includeTerminated }),
+      );
+      return result.sessions ?? [];
+    },
+    async create(input): Promise<HostedSessionRecord> {
+      const result = await verbs.invoke<{ session: HostedSessionRecord }>(
+        'sessions.hosted.create',
+        withoutUndefined({
+          workspaceRoot: input.workspaceRoot,
+          title: input.title,
+          modelId: input.modelId,
+          initialPrompt: input.initialPrompt,
+          detachPolicy: input.detachPolicy,
+          clientId,
+        }),
+      );
+      return result.session;
+    },
+    async attach(sessionId): Promise<HostedSessionAttachment> {
+      const result = await verbs.invoke<HostedSessionAttachment>(
+        'sessions.hosted.attach',
+        { sessionId, clientId },
+      );
+      return { session: result.session, history: result.history ?? [] };
+    },
+    async detach(sessionId): Promise<HostedSessionRecord> {
+      const result = await verbs.invoke<{ session: HostedSessionRecord }>(
+        'sessions.hosted.detach',
+        { sessionId, clientId },
+      );
+      return result.session;
+    },
+    async kill(sessionId): Promise<HostedSessionRecord> {
+      const result = await verbs.invoke<{ session: HostedSessionRecord }>(
+        'sessions.hosted.kill',
+        { sessionId },
+      );
+      return result.session;
+    },
+    async steer(sessionId, body): Promise<void> {
+      await verbs.invoke('sessions.steer', { sessionId, body, surfaceKind: 'tui' });
+    },
+    async followUp(sessionId, body): Promise<void> {
+      await verbs.invoke('sessions.followUp', { sessionId, body, surfaceKind: 'tui' });
+    },
+    async cancelToolCall(sessionId, callId): Promise<boolean> {
+      const result = await verbs.invoke<{ cancelled: boolean }>(
+        'sessions.toolCalls.cancel',
+        { sessionId, callId },
+      );
+      return result.cancelled === true;
+    },
+  };
+}
+
+/**
+ * One line describing what leaving this session would do right now, in the
+ * words the record itself carries.
+ *
+ * The policy is the daemon's answer, never this client's guess: a session
+ * created with an override reports the override, and one following the setting
+ * reports the setting's current value. Rendering a locally-remembered default
+ * here is how a user learns the wrong thing about a quit.
+ */
+export function describeDetachEffect(record: HostedSessionRecord): string {
+  const source = record.detachPolicy === null
+    ? 'the hostedSessions.detachPolicy setting'
+    : 'this session\'s own override';
+  return record.effectiveDetachPolicy === 'survive'
+    ? `leaving keeps it running (survive, from ${source})`
+    : `leaving ends it (kill, from ${source})`;
+}
+
+/** A short, stable label for a record in a list. Never invents a title. */
+export function hostedSessionLabel(record: HostedSessionRecord): string {
+  return record.title.trim() || record.id;
+}