@volter-ai-dev/supercode-ui 0.1.58 → 0.1.60

package/README.md

@@ -185,11 +185,45 @@ mounted.update(binding.getState());
 ```
 
 The binding maps standard controller operations, including verified reduce-and-continue, and
-projects its durable reduction receipt directly. Host-owned pagination, durable attention,
-drafts, and artifact materialization remain explicit callbacks. A
+projects its durable reduction receipt directly. Host-owned session-list pagination, durable
+attention, drafts, and artifact materialization remain explicit callbacks. Transcript pagination
+dispatches to the controller by default. A
 browser should receive projected state from a trusted host rather than instantiate a local
 controller or gain filesystem authority.
 
+### Bind across a process boundary
+
+Browser-hosted products use the transport-neutral host binding instead of recreating snapshot
+ordering and intent dispatch around the same controller:
+
+```js
+import { createRemoteControllerHost, createRemoteUiBinding } from '@volter-ai-dev/supercode-ui/host';
+
+// Trusted process
+const host = createRemoteControllerHost(controller);
+events.send(host.getFrame());
+host.subscribe((frame) => events.send(frame));
+http.onIntent((intent) => host.dispatch(intent));
+
+// Browser
+const binding = createRemoteUiBinding({
+  initialFrame,
+  dispatch: (intent) => http.postIntent(intent),
+  attention: {
+    state: loadAttention(),
+    onChange: saveAttention,
+  },
+});
+events.onFrame((frame) => binding.receive(frame));
+```
+
+Each serializable frame carries a host-process identity, workspace generation, monotonic sequence,
+controller revision, canonical UI state, and stable opaque reconnect identities. The browser store
+rejects duplicate and stale frames, including delayed action responses from a retired host process.
+The optional attention tracker baselines initial inventory without inventing unread dots, persists
+by stable opaque identity, and marks only newer conversation evidence or a proven runtime completion.
+HTTP, SSE, WebSocket, authentication, and product shell behavior remain host-owned transports.
+
 Native continuation exposes one action and a quiet execution-transport selector. A host with a real
 terminal provider can add `terminal` to `continuationModes` and handle `onResumeTerminal`; Terminal
 is then the initial choice and Headless remains available from the selector. The UI never infers

package/controller.d.ts

@@ -121,6 +121,9 @@ export interface ControllerBindingOptions {
   onAcknowledge?: (key: string) => void | Promise<void>;
   onLoadSessions?: () => void | Promise<void>;
   onLoadEarlier?: () => void | Promise<void>;
+  onOpenSubagents?: (key: string) => void | Promise<void>;
+  onOpenSubagent?: (parentKey: string, key: string) => void | Promise<void>;
+  onCloseSubagents?: () => void | Promise<void>;
   onStartTerminal?: (intent: Extract<SupercodeUiIntent, { action: 'new' }>) => void | Promise<void>;
   onResumeTerminal?: (intent: Extract<SupercodeUiIntent, { action: 'resume' }>) => void | Promise<void>;
   copyText?: UiAdapter['copyText'];

package/controller.mjs

@@ -433,7 +433,7 @@ function attached(snapshot) {
     harness: session.harness,
     name: workspaceName(session.cwd),
     cwd: session.cwd ?? '',
-    title: session.title ?? 'Untitled chat',
+    title: session.displayTitle ?? session.title ?? 'Untitled chat',
   };
 }
 
@@ -509,14 +509,19 @@ function projectClientSnapshotInternal(snapshot, options, imageRegistry) {
     harness: session.harness,
     name: workspaceName(session.cwd),
     cwd: session.cwd ?? '',
-    title: session.title ?? 'Untitled chat',
-    age: relativeAge(session.updatedAt, now),
+    title: session.displayTitle ?? session.title ?? 'Untitled chat',
+    preview: session.preview ?? '',
+    age: relativeAge(session.previewUpdatedAt ?? session.updatedAt, now),
+    previewUpdatedAt: session.previewUpdatedAt ?? null,
     updatedAt: session.updatedAt ?? null,
     messages: session.messageCount ?? null,
     active: session.key === snapshot.activeSessionKey,
     writable: session.key === snapshot.activeSessionKey && actions.send === true,
     live: typeof session.updatedAt === 'number' && now - session.updatedAt <= liveWindowMs,
     runtimeStatus: session.liveStatus ?? null,
+    ...(Number.isSafeInteger(session.childSessionCount) && session.childSessionCount > 0
+      ? { subagentCount: session.childSessionCount }
+      : {}),
   }));
   const sessions = options.sessions ?? snapshotSessions;
   const active = options.attached === undefined ? attached(snapshot) : options.attached;
@@ -677,7 +682,16 @@ export async function dispatchControllerIntent(controller, intent, options = {})
   if (intent.action === 'draft') return options.onDraft?.(intent.text);
   if (intent.action === 'ack') return options.onAcknowledge?.(intent.key);
   if (intent.action === 'loadSessions') return options.onLoadSessions?.();
-  if (intent.action === 'loadEarlier') return options.onLoadEarlier?.();
+  if (intent.action === 'loadEarlier') {
+    return options.onLoadEarlier
+      ? options.onLoadEarlier()
+      : controller.dispatch({ type: 'loadEarlier' });
+  }
+  if (intent.action === 'openSubagents') return options.onOpenSubagents?.(intent.key);
+  if (intent.action === 'openSubagent') {
+    return options.onOpenSubagent?.(intent.parentKey, intent.key);
+  }
+  if (intent.action === 'closeSubagents') return options.onCloseSubagents?.();
   return options.onUnsupported?.(intent);
 }
 

package/host.d.ts

@@ -0,0 +1,103 @@
+import type { SupercodeClientSnapshot, SupercodeController } from '@volter-ai-dev/supercode-client';
+import type { ClientProjectionOptions, ControllerBindingOptions } from './controller.js';
+import type { SupercodeUiIntent, SupercodeUiState, UiAdapter } from './index.js';
+
+export interface RemoteUiFrame {
+  schema: 'supercode.ui-host-state.v1';
+  hostInstanceId: string;
+  generation: number;
+  sequence: number;
+  controllerRevision: number;
+  workspace: string;
+  state: SupercodeUiState;
+  sessionIdentities: ReadonlyArray<{ key: string; identity: string }>;
+}
+
+export interface RemoteControllerHostOptions extends Omit<ControllerBindingOptions, 'projection'> {
+  hostInstanceId?: string;
+  projection?(snapshot: SupercodeClientSnapshot): ClientProjectionOptions;
+}
+
+export class RemoteControllerHost {
+  constructor(controller: SupercodeController, options?: RemoteControllerHostOptions);
+  close(): void;
+  dispatch(intent: unknown): Promise<RemoteUiFrame>;
+  getFrame(): RemoteUiFrame;
+  refreshProjection(): RemoteUiFrame;
+  restore(identity: string, connection: 'observe' | 'attach'): Promise<RemoteUiFrame>;
+  subscribe(listener: (frame: RemoteUiFrame) => void): () => void;
+}
+
+export function createRemoteControllerHost(
+  controller: SupercodeController,
+  options?: RemoteControllerHostOptions,
+): RemoteControllerHost;
+
+export function assertRemoteUiFrame(value: unknown): RemoteUiFrame;
+
+export class RemoteUiStore {
+  constructor(initialFrame?: RemoteUiFrame | null);
+  getFrame(): RemoteUiFrame | null;
+  getState(): SupercodeUiState | null;
+  receive(frame: unknown): boolean;
+  subscribe(listener: (state: SupercodeUiState, frame: RemoteUiFrame) => void): () => void;
+}
+
+export function createRemoteUiStore(initialFrame?: RemoteUiFrame | null): RemoteUiStore;
+
+export interface SessionAttentionTrackerState {
+  version: 1;
+  sessions: Record<string, {
+    observedAt: number;
+    messages: number | null;
+    activity: import('./index.js').SessionActivity;
+    attention: import('./index.js').SessionAttention['kind'] | null;
+  }>;
+}
+
+export interface SessionAttentionTrackerOptions {
+  state?: unknown;
+  onChange?(state: SessionAttentionTrackerState): void;
+}
+
+export class SessionAttentionTracker {
+  constructor(options?: SessionAttentionTrackerOptions);
+  acknowledge(frame: RemoteUiFrame, key: string): boolean;
+  attention(frame: RemoteUiFrame): import('./index.js').SessionAttention[];
+  observe(frame: RemoteUiFrame): import('./index.js').SessionAttention[];
+  snapshot(): SessionAttentionTrackerState;
+}
+
+export function createSessionAttentionTracker(
+  options?: SessionAttentionTrackerOptions,
+): SessionAttentionTracker;
+
+export interface RemoteUiBindingOptions
+  extends Pick<
+    UiAdapter,
+    | 'confirmIntent'
+    | 'pickContext'
+    | 'resolveImage'
+    | 'openKeyboardShortcuts'
+    | 'onClose'
+    | 'onOpen'
+    | 'copyText'
+    | 'now'
+  > {
+  initialFrame?: RemoteUiFrame | null;
+  attention?: SessionAttentionTrackerOptions;
+  dispatch(intent: SupercodeUiIntent): Promise<RemoteUiFrame | null | void>;
+  handleIntent?(intent: SupercodeUiIntent): boolean | Promise<boolean>;
+  onAcknowledge?(key: string): void | Promise<void>;
+}
+
+export interface RemoteUiBinding {
+  adapter: UiAdapter;
+  close(): void;
+  getFrame(): RemoteUiFrame | null;
+  getState(): SupercodeUiState | null;
+  receive(frame: unknown): boolean;
+  subscribe(listener: (state: SupercodeUiState, frame: RemoteUiFrame) => void): () => void;
+}
+
+export function createRemoteUiBinding(options: RemoteUiBindingOptions): RemoteUiBinding;

package/host.mjs

@@ -0,0 +1,384 @@
+import { parseSupercodeUiIntent, sessionActivity } from './core.mjs';
+import { dispatchControllerIntent, projectClientSnapshot } from './controller.mjs';
+
+const FRAME_SCHEMA = 'supercode.ui-host-state.v1';
+
+function objectRecord(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+}
+
+function defaultInstanceId() {
+  if (typeof globalThis.crypto?.randomUUID === 'function') return globalThis.crypto.randomUUID();
+  return `host-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+
+/** Runtime guard for transport payloads received from a trusted Supercode host. */
+export function assertRemoteUiFrame(value) {
+  const frame = objectRecord(value);
+  const state = objectRecord(frame?.state);
+  if (
+    frame?.schema !== FRAME_SCHEMA ||
+    typeof frame.hostInstanceId !== 'string' ||
+    !frame.hostInstanceId ||
+    !Number.isSafeInteger(frame.generation) ||
+    frame.generation < 1 ||
+    !Number.isSafeInteger(frame.sequence) ||
+    frame.sequence < 1 ||
+    !Number.isSafeInteger(frame.controllerRevision) ||
+    frame.controllerRevision < 0 ||
+    typeof frame.workspace !== 'string' ||
+    !state ||
+    !Array.isArray(state.sessions) ||
+    !Array.isArray(state.transcript) ||
+    !Array.isArray(frame.sessionIdentities) ||
+    !frame.sessionIdentities.every(
+      (item) =>
+        objectRecord(item) &&
+        typeof item.key === 'string' &&
+        typeof item.identity === 'string',
+    )
+  ) {
+    throw new TypeError('Malformed Supercode remote UI frame.');
+  }
+  return value;
+}
+
+/** Trusted-host binding that projects one ordered, serializable UI frame and
+ * dispatches the same typed intents as an in-process messenger. */
+export class RemoteControllerHost {
+  #bindingOptions;
+  #controller;
+  #frame;
+  #generation = 0;
+  #hostInstanceId;
+  #lastControllerRevision = -1;
+  #listeners = new Set();
+  #sequence = 0;
+  #unsubscribe;
+  #workspace = null;
+
+  constructor(controller, options = {}) {
+    if (
+      !controller ||
+      typeof controller.getSnapshot !== 'function' ||
+      typeof controller.subscribe !== 'function' ||
+      typeof controller.dispatch !== 'function'
+    ) {
+      throw new TypeError('RemoteControllerHost requires a SupercodeController-compatible object.');
+    }
+    this.#controller = controller;
+    this.#hostInstanceId = options.hostInstanceId ?? defaultInstanceId();
+    if (typeof this.#hostInstanceId !== 'string' || !this.#hostInstanceId) {
+      throw new TypeError('RemoteControllerHost hostInstanceId must be a non-empty string.');
+    }
+    this.#bindingOptions = options;
+    this.#capture(true);
+    this.#unsubscribe = controller.subscribe(() => this.#capture(false));
+  }
+
+  close() {
+    this.#unsubscribe?.();
+    this.#unsubscribe = null;
+    this.#listeners.clear();
+  }
+
+  getFrame() {
+    return this.#frame;
+  }
+
+  subscribe(listener) {
+    this.#listeners.add(listener);
+    listener(this.#frame);
+    return () => this.#listeners.delete(listener);
+  }
+
+  /** Reproject host-owned overlays such as machine-wide inventory or durable attention. */
+  refreshProjection() {
+    this.#capture(true);
+    return this.#frame;
+  }
+
+  async dispatch(value) {
+    const intent = parseSupercodeUiIntent(value);
+    if (!intent) throw new TypeError('Invalid Supercode UI intent.');
+    const sequence = this.#sequence;
+    await dispatchControllerIntent(this.#controller, intent, this.#bindingOptions);
+    if (this.#sequence === sequence) this.#capture(true);
+    return this.#frame;
+  }
+
+  async restore(identity, connection) {
+    if (typeof identity !== 'string' || !identity) {
+      throw new TypeError('RemoteControllerHost restore identity must be a non-empty string.');
+    }
+    if (connection !== 'observe' && connection !== 'attach') {
+      throw new TypeError('RemoteControllerHost restore connection must be observe or attach.');
+    }
+    const sequence = this.#sequence;
+    await this.#controller.dispatch({ type: 'restore', identity, connection });
+    if (this.#sequence === sequence) this.#capture(true);
+    return this.#frame;
+  }
+
+  #capture(force) {
+    const snapshot = this.#controller.getSnapshot();
+    if (snapshot.workspace !== this.#workspace) {
+      this.#workspace = snapshot.workspace;
+      this.#generation += 1;
+      this.#lastControllerRevision = -1;
+      force = true;
+    }
+    if (!force && snapshot.revision === this.#lastControllerRevision) return;
+    this.#lastControllerRevision = snapshot.revision;
+    this.#sequence += 1;
+    const projection = this.#bindingOptions.projection?.(snapshot) ?? {};
+    this.#frame = Object.freeze({
+      schema: FRAME_SCHEMA,
+      hostInstanceId: this.#hostInstanceId,
+      generation: this.#generation,
+      sequence: this.#sequence,
+      controllerRevision: snapshot.revision,
+      workspace: snapshot.workspace,
+      state: projectClientSnapshot(snapshot, projection),
+      sessionIdentities: Object.freeze(
+        snapshot.sessions.map((session) =>
+          Object.freeze({ key: session.key, identity: session.identity }),
+        ),
+      ),
+    });
+    for (const listener of this.#listeners) listener(this.#frame);
+  }
+}
+
+export function createRemoteControllerHost(controller, options) {
+  return new RemoteControllerHost(controller, options);
+}
+
+/** Monotonic browser-side store. Once a newer host process is accepted, frames
+ * from every retired process are rejected permanently. */
+export class RemoteUiStore {
+  #frame = null;
+  #listeners = new Set();
+  #retiredHostInstances = new Set();
+
+  constructor(initialFrame) {
+    if (initialFrame !== undefined && initialFrame !== null) this.receive(initialFrame);
+  }
+
+  getFrame() {
+    return this.#frame;
+  }
+
+  getState() {
+    return this.#frame?.state ?? null;
+  }
+
+  subscribe(listener) {
+    this.#listeners.add(listener);
+    if (this.#frame) listener(this.#frame.state, this.#frame);
+    return () => this.#listeners.delete(listener);
+  }
+
+  receive(value) {
+    const next = assertRemoteUiFrame(value);
+    const current = this.#frame;
+    if (current) {
+      if (next.hostInstanceId !== current.hostInstanceId) {
+        if (this.#retiredHostInstances.has(next.hostInstanceId)) return false;
+        this.#retiredHostInstances.add(current.hostInstanceId);
+      } else if (
+        next.generation < current.generation ||
+        (next.generation === current.generation && next.sequence <= current.sequence)
+      ) {
+        return false;
+      }
+    }
+    this.#frame = next;
+    for (const listener of this.#listeners) listener(next.state, next);
+    return true;
+  }
+}
+
+export function createRemoteUiStore(initialFrame) {
+  return new RemoteUiStore(initialFrame);
+}
+
+function attentionState(value) {
+  const parsed = objectRecord(value);
+  const sessions = objectRecord(parsed?.sessions);
+  return {
+    version: 1,
+    sessions: sessions
+      ? Object.fromEntries(
+          Object.entries(sessions).flatMap(([identity, record]) => {
+            const item = objectRecord(record);
+            if (!item) return [];
+            return [[identity, {
+              observedAt: Number.isFinite(item.observedAt) ? item.observedAt : 0,
+              messages: Number.isFinite(item.messages) ? item.messages : null,
+              activity: typeof item.activity === 'string' ? item.activity : 'idle',
+              attention: ['unseen', 'finished', 'failed'].includes(item.attention)
+                ? item.attention
+                : null,
+            }]];
+          }),
+        )
+      : {},
+  };
+}
+
+function activeActivity(value) {
+  return value === 'running' || value === 'working' || value === 'needs-input';
+}
+
+/** Reference durable attention reducer. It baselines initial inventory without
+ * manufacturing unread state, then records only newer conversation or runtime evidence. */
+export class SessionAttentionTracker {
+  #onChange;
+  #state;
+
+  constructor(options = {}) {
+    this.#state = attentionState(options.state);
+    this.#onChange = options.onChange;
+  }
+
+  observe(frameValue) {
+    const frame = assertRemoteUiFrame(frameValue);
+    const identities = new Map(frame.sessionIdentities.map((item) => [item.key, item.identity]));
+    let changed = false;
+    for (const row of frame.state.sessions) {
+      const identity = identities.get(row.key);
+      if (!identity) continue;
+      const observedAt = row.previewUpdatedAt ?? row.updatedAt ?? 0;
+      const messages = Number.isFinite(row.messages) ? row.messages : null;
+      const activity = sessionActivity(frame.state, row);
+      const prior = this.#state.sessions[identity];
+      if (!prior) {
+        this.#state.sessions[identity] = {
+          observedAt,
+          messages,
+          activity,
+          attention: null,
+        };
+        changed = true;
+        continue;
+      }
+      const newerConversation =
+        observedAt > prior.observedAt ||
+        (messages !== null && prior.messages !== null && messages > prior.messages);
+      let attention = prior.attention;
+      if (newerConversation) attention = 'unseen';
+      if (activeActivity(prior.activity) && !activeActivity(activity)) {
+        attention = frame.state.error ? 'failed' : 'finished';
+      }
+      const next = {
+        observedAt: Math.max(prior.observedAt, observedAt),
+        messages:
+          messages === null
+            ? prior.messages
+            : prior.messages === null
+              ? messages
+              : Math.max(prior.messages, messages),
+        activity,
+        attention,
+      };
+      if (JSON.stringify(next) !== JSON.stringify(prior)) {
+        this.#state.sessions[identity] = next;
+        changed = true;
+      }
+    }
+    if (changed) this.#emit();
+    return this.attention(frame);
+  }
+
+  attention(frameValue) {
+    const frame = assertRemoteUiFrame(frameValue);
+    return frame.sessionIdentities.flatMap(({ key, identity }) => {
+      const attention = this.#state.sessions[identity]?.attention;
+      return attention ? [{ key, kind: attention }] : [];
+    });
+  }
+
+  acknowledge(frameValue, key) {
+    const frame = assertRemoteUiFrame(frameValue);
+    const identity = frame.sessionIdentities.find((item) => item.key === key)?.identity;
+    if (!identity || !this.#state.sessions[identity]?.attention) return false;
+    this.#state.sessions[identity].attention = null;
+    this.#emit();
+    return true;
+  }
+
+  snapshot() {
+    return structuredClone(this.#state);
+  }
+
+  #emit() {
+    this.#onChange?.(this.snapshot());
+  }
+}
+
+export function createSessionAttentionTracker(options) {
+  return new SessionAttentionTracker(options);
+}
+
+/** Browser binding for any transport that can post one intent and return an
+ * optional authoritative frame. Local host actions may intercept an intent. */
+export function createRemoteUiBinding(options) {
+  if (!options || typeof options.dispatch !== 'function') {
+    throw new TypeError('createRemoteUiBinding requires a dispatch function.');
+  }
+  const store = new RemoteUiStore(options.initialFrame);
+  const attention = options.attention
+    ? new SessionAttentionTracker(options.attention)
+    : null;
+  let projectedState = null;
+  const listeners = new Set();
+  const project = (frame) => {
+    projectedState = attention
+      ? { ...frame.state, attention: attention.observe(frame) }
+      : frame.state;
+    for (const listener of listeners) listener(projectedState, frame);
+  };
+  const unsubscribeStore = store.subscribe((_state, frame) => project(frame));
+  const adapter = {
+    async onIntent(value) {
+      const intent = parseSupercodeUiIntent(value);
+      if (!intent) throw new TypeError('Invalid Supercode UI intent.');
+      if (intent.action === 'ack' && attention) {
+        const frame = store.getFrame();
+        if (frame && attention.acknowledge(frame, intent.key)) project(frame);
+        await options.onAcknowledge?.(intent.key);
+        return;
+      }
+      if (await options.handleIntent?.(intent)) return;
+      const frame = await options.dispatch(intent);
+      if (frame) store.receive(frame);
+    },
+    ...(options.confirmIntent ? { confirmIntent: options.confirmIntent } : {}),
+    ...(options.pickContext ? { pickContext: options.pickContext } : {}),
+    ...(options.resolveImage ? { resolveImage: options.resolveImage } : {}),
+    ...(options.openKeyboardShortcuts
+      ? { openKeyboardShortcuts: options.openKeyboardShortcuts }
+      : {}),
+    ...(options.onClose ? { onClose: options.onClose } : {}),
+    ...(options.onOpen ? { onOpen: options.onOpen } : {}),
+    ...(options.copyText ? { copyText: options.copyText } : {}),
+    ...(options.now ? { now: options.now } : {}),
+  };
+  return {
+    adapter,
+    getFrame: () => store.getFrame(),
+    getState: () => projectedState ?? store.getState(),
+    receive: (frame) => store.receive(frame),
+    subscribe(listener) {
+      listeners.add(listener);
+      const frame = store.getFrame();
+      if (frame && projectedState) listener(projectedState, frame);
+      return () => listeners.delete(listener);
+    },
+    close() {
+      unsubscribeStore();
+      listeners.clear();
+    },
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter-ai-dev/supercode-ui",
-  "version": "0.1.58",
+  "version": "0.1.60",
   "type": "module",
   "description": "Composable default UI kit for Supercode-powered coding-agent experiences",
   "exports": {
@@ -16,6 +16,10 @@
       "types": "./controller.d.ts",
       "import": "./controller.mjs"
     },
+    "./host": {
+      "types": "./host.d.ts",
+      "import": "./host.mjs"
+    },
     "./preact": {
       "types": "./components.d.ts",
       "import": "./components.mjs"
@@ -108,6 +112,8 @@
     "core.d.ts",
     "controller.mjs",
     "controller.d.ts",
+    "host.mjs",
+    "host.d.ts",
     "components.mjs",
     "components.d.ts",
     "activity.mjs",