@volter-ai-dev/supercode-ui 0.1.64 → 0.1.66

package/README.md

@@ -237,6 +237,17 @@ The optional attention tracker baselines initial inventory without inventing unr
 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.
 
+A native-store inbox can use `createNativeSessionAttentionTracker` instead. It consumes projected
+session rows plus their native descriptors, persists opaque message cursors, ignores tool and
+heartbeat churn, treats compaction as a new baseline, and returns the delay for one host-owned
+settlement timer. This keeps unread and finished semantics identical in an editor, extension,
+desktop app, or mobile companion without moving file persistence into the UI package.
+
+`createNativeMessengerState` wraps that ledger with bounded per-conversation drafts and per-harness
+Terminal/Headless preferences. It emits one serializable snapshot, so native hosts do not need to
+duplicate state parsing or coordinate several independent maps. The host still owns where that
+snapshot is stored, its debounce and encryption policy, and any multi-device synchronization.
+
 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/host.d.ts

@@ -72,6 +72,72 @@ export function createSessionAttentionTracker(
   options?: SessionAttentionTrackerOptions,
 ): SessionAttentionTracker;
 
+export interface NativeSessionAttentionTrackerState {
+  version: 1;
+  attention: import('./index.js').SessionAttention[];
+  observedCursors: Record<string, string>;
+}
+
+export interface NativeSessionAttentionObservation {
+  sessions: readonly import('./index.js').SessionRowModel[];
+  descriptors: readonly import('@volter-ai-dev/supercode-harness-sdk').SessionDescriptor[];
+  keyForDescriptor(
+    descriptor: import('@volter-ai-dev/supercode-harness-sdk').SessionDescriptor,
+  ): string;
+  controller?: SupercodeClientSnapshot | null;
+  attachedKey?: string | null;
+  panelVisible?: boolean;
+  now?: number;
+  settleMs?: number;
+}
+
+export class NativeSessionAttentionTracker {
+  constructor(options?: {
+    state?: unknown;
+    onChange?(state: NativeSessionAttentionTrackerState): void;
+  });
+  acknowledge(key: string): boolean;
+  observe(options: NativeSessionAttentionObservation): {
+    attention: import('./index.js').SessionAttention[];
+    settleAfterMs: number | null;
+  };
+  snapshot(): NativeSessionAttentionTrackerState;
+}
+
+export function createNativeSessionAttentionTracker(options?: {
+  state?: unknown;
+  onChange?(state: NativeSessionAttentionTrackerState): void;
+}): NativeSessionAttentionTracker;
+
+export interface NativeMessengerStateSnapshot extends NativeSessionAttentionTrackerState {
+  drafts: Record<string, string>;
+  preferredLaunchModes: Record<string, 'headless' | 'terminal'>;
+}
+
+export function normalizeNativeMessengerState(value: unknown): NativeMessengerStateSnapshot;
+
+export class NativeMessengerState {
+  constructor(options?: {
+    state?: unknown;
+    onChange?(state: NativeMessengerStateSnapshot): void;
+  });
+  acknowledge(key: string): boolean;
+  observeAttention(options: NativeSessionAttentionObservation): {
+    attention: import('./index.js').SessionAttention[];
+    settleAfterMs: number | null;
+  };
+  draft(key: string): string;
+  setDraft(key: string, draft: string): boolean;
+  preferredLaunchMode(harness: string): 'headless' | 'terminal' | null;
+  setPreferredLaunchMode(harness: string, mode: 'headless' | 'terminal'): boolean;
+  snapshot(): NativeMessengerStateSnapshot;
+}
+
+export function createNativeMessengerState(options?: {
+  state?: unknown;
+  onChange?(state: NativeMessengerStateSnapshot): void;
+}): NativeMessengerState;
+
 export interface RemoteUiBindingOptions
   extends Pick<
     UiAdapter,

package/host.mjs

@@ -1,12 +1,20 @@
 import { parseSupercodeUiIntent, sessionActivity } from './core.mjs';
 import { dispatchControllerIntent, projectClientSnapshot } from './controller.mjs';
+import { conversationPreviewText } from '@volter-ai-dev/supercode-client';
 
 const FRAME_SCHEMA = 'supercode.ui-host-state.v1';
+const NATIVE_STATE_LIMIT = 500;
 
 function objectRecord(value) {
   return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
 }
 
+function setRecentBounded(map, key, value) {
+  map.delete(key);
+  map.set(key, value);
+  while (map.size > NATIVE_STATE_LIMIT) map.delete(map.keys().next().value);
+}
+
 function defaultInstanceId() {
   if (typeof globalThis.crypto?.randomUUID === 'function') return globalThis.crypto.randomUUID();
   return `host-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
@@ -321,6 +329,362 @@ export function createSessionAttentionTracker(options) {
   return new SessionAttentionTracker(options);
 }
 
+function nativeAttentionState(value) {
+  const parsed = objectRecord(value);
+  const attention = Array.isArray(parsed?.attention)
+    ? parsed.attention.slice(0, NATIVE_STATE_LIMIT).flatMap((candidate) => {
+        const item = objectRecord(candidate);
+        if (
+          typeof item?.key !== 'string' ||
+          !item.key ||
+          item.key.length > 200 ||
+          !['unseen', 'finished', 'failed'].includes(item.kind)
+        ) return [];
+        return [{
+          key: item.key,
+          kind: item.kind,
+          unreadCount: Number.isSafeInteger(item.unreadCount)
+            ? Math.max(1, Math.min(999, item.unreadCount))
+            : 1,
+          ...(Number.isSafeInteger(item.afterMessages) && item.afterMessages >= 0
+            ? { afterMessages: item.afterMessages }
+            : {}),
+          ...(typeof item.preview === 'string' && item.preview
+            ? { preview: item.preview.slice(0, 240) }
+            : {}),
+        }];
+      })
+    : [];
+  const cursors = objectRecord(parsed?.observedCursors);
+  const observedCursors = cursors
+    ? Object.fromEntries(
+        Object.entries(cursors).slice(0, NATIVE_STATE_LIMIT).filter(
+          ([key, cursor]) => key.length <= 200 && typeof cursor === 'string' && cursor.length <= 200,
+        ),
+      )
+    : {};
+  return { version: 1, attention, observedCursors };
+}
+
+function conversationObservation(descriptor) {
+  const candidates = (descriptor?.latest_message_candidates ?? []).flatMap((candidate) => {
+    if (
+      typeof candidate?.cursor !== 'string' ||
+      !candidate.cursor ||
+      (candidate.role !== 'user' && candidate.role !== 'assistant')
+    ) return [];
+    const preview = conversationPreviewText([candidate]);
+    return preview
+      ? [{ cursor: candidate.cursor, role: candidate.role, preview }]
+      : [];
+  });
+  return { cursor: candidates[0]?.cursor ?? null, candidates };
+}
+
+function assistantDelta(current, priorCursor) {
+  if (current.cursor === null || current.cursor === priorCursor) return 0;
+  const priorIndex = priorCursor === null
+    ? -1
+    : current.candidates.findIndex((candidate) => candidate.cursor === priorCursor);
+  const newlyObserved = priorIndex >= 0
+    ? current.candidates.slice(0, priorIndex)
+    : current.candidates;
+  return newlyObserved.filter((candidate) => candidate.role === 'assistant').length;
+}
+
+/** Native-cursor attention reducer for a messenger-style session catalog. Tool records and
+ * heartbeat writes never manufacture unread counts; only new human-visible assistant boundaries
+ * do. The host owns persistence and the one settlement timer requested by `observe()`. */
+export class NativeSessionAttentionTracker {
+  #attention;
+  #observedCursors;
+  #observedUpdates = new Map();
+  #onChange;
+  #priorRuntimeActive = false;
+  #priorRuntimeKey = null;
+
+  constructor(options = {}) {
+    const state = nativeAttentionState(options.state);
+    this.#attention = new Map(state.attention.map((item) => [item.key, item]));
+    this.#observedCursors = new Map(Object.entries(state.observedCursors));
+    this.#onChange = options.onChange;
+  }
+
+  observe(options) {
+    const rows = Array.isArray(options?.sessions) ? options.sessions : [];
+    const descriptors = Array.isArray(options?.descriptors) ? options.descriptors : [];
+    if (typeof options?.keyForDescriptor !== 'function') {
+      throw new TypeError('NativeSessionAttentionTracker requires keyForDescriptor.');
+    }
+    const now = Number.isFinite(options.now) ? options.now : Date.now();
+    const settleMs = Number.isFinite(options.settleMs) && options.settleMs >= 0
+      ? options.settleMs
+      : 15_000;
+    const descriptorByKey = new Map(
+      descriptors.map((descriptor) => [options.keyForDescriptor(descriptor), descriptor]),
+    );
+    let changed = false;
+    let settleAfterMs = null;
+
+    for (const row of rows) {
+      const current = conversationObservation(descriptorByKey.get(row.key));
+      let prior = this.#observedUpdates.get(row.key);
+      if (prior === undefined) {
+        const persistedCursor = this.#observedCursors.get(row.key) ?? null;
+        prior = {
+          cursor: persistedCursor,
+          messages: row.messages,
+          runtimeStatus: row.runtimeStatus,
+        };
+        if (persistedCursor === null) {
+          this.#observedUpdates.set(row.key, {
+            cursor: current.cursor,
+            messages: row.messages,
+            runtimeStatus: row.runtimeStatus,
+          });
+          if (current.cursor !== null) {
+            setRecentBounded(this.#observedCursors, row.key, current.cursor);
+            changed = true;
+          }
+          continue;
+        }
+      }
+
+      const rewritten = row.messages !== null && prior.messages !== null && row.messages < prior.messages;
+      const cursorChanged = current.cursor !== null && current.cursor !== prior.cursor;
+      const settledAt = row.previewUpdatedAt ?? row.updatedAt;
+      const elapsed = settledAt === null ? null : now - settledAt;
+      const settled = elapsed !== null && elapsed >= settleMs;
+      const completed = prior.runtimeStatus === 'busy' && row.runtimeStatus === 'idle';
+
+      if (rewritten) {
+        prior.cursor = current.cursor;
+      } else if (cursorChanged && row.runtimeStatus !== 'busy' && (completed || settled)) {
+        const delta = assistantDelta(current, prior.cursor);
+        if (delta > 0) {
+          changed = this.#mark(
+            row.key,
+            completed ? 'finished' : 'unseen',
+            row.preview,
+            delta,
+            prior.messages,
+          ) || changed;
+        }
+        prior.cursor = current.cursor;
+      } else if (cursorChanged && row.runtimeStatus !== 'busy' && elapsed !== null) {
+        const remaining = Math.max(0, settleMs - elapsed);
+        settleAfterMs = settleAfterMs === null ? remaining : Math.min(settleAfterMs, remaining);
+      }
+
+      if (prior.cursor !== null && this.#observedCursors.get(row.key) !== prior.cursor) {
+        setRecentBounded(this.#observedCursors, row.key, prior.cursor);
+        changed = true;
+      }
+      this.#observedUpdates.set(row.key, {
+        cursor: prior.cursor,
+        messages: row.messages,
+        runtimeStatus: row.runtimeStatus,
+      });
+    }
+
+    const controller = options.controller;
+    const runtimeActive = controller
+      ? controller.turn?.state !== 'idle' || controller.requests?.some((request) => request.status === 'pending')
+      : false;
+    const runtimeKey = options.attachedKey || this.#priorRuntimeKey;
+    if (
+      this.#priorRuntimeActive &&
+      !runtimeActive &&
+      this.#priorRuntimeKey &&
+      !(options.panelVisible === true && options.attachedKey === this.#priorRuntimeKey)
+    ) {
+      const lastAssistant = [...(controller?.conversation ?? [])].reverse().find(
+        (entry) => entry.kind === 'message' && entry.role === 'assistant' && entry.text.trim(),
+      );
+      const preview = lastAssistant?.kind === 'message'
+        ? lastAssistant.text.replace(/\s+/g, ' ').trim()
+        : undefined;
+      changed = this.#mark(
+        this.#priorRuntimeKey,
+        controller?.error ? 'failed' : 'finished',
+        preview,
+      ) || changed;
+    }
+    this.#priorRuntimeActive = runtimeActive;
+    this.#priorRuntimeKey = runtimeActive ? runtimeKey : null;
+
+    if (changed) this.#emit();
+    const visible = new Set(rows.map((row) => row.key));
+    return {
+      attention: [...this.#attention.values()].filter((item) => visible.has(item.key)),
+      settleAfterMs,
+    };
+  }
+
+  acknowledge(key) {
+    if (!this.#attention.delete(key)) return false;
+    this.#emit();
+    return true;
+  }
+
+  snapshot() {
+    return {
+      version: 1,
+      attention: structuredClone([...this.#attention.values()]),
+      observedCursors: Object.fromEntries(this.#observedCursors),
+    };
+  }
+
+  #mark(key, kind, preview, unreadDelta = 1, afterMessages = null) {
+    const prior = this.#attention.get(key);
+    const boundedPreview = typeof preview === 'string' && preview
+      ? preview.slice(0, 240)
+      : undefined;
+    const sameEvent = boundedPreview
+      ? prior?.preview === boundedPreview
+      : prior?.kind === kind && prior.preview === undefined;
+    const unreadCount = sameEvent
+      ? (prior?.unreadCount ?? Math.max(1, unreadDelta))
+      : Math.min((prior?.unreadCount ?? 0) + Math.max(1, unreadDelta), 999);
+    const next = {
+      key,
+      kind: prior?.kind === 'failed' && kind !== 'failed' ? 'failed' : kind,
+      unreadCount,
+      ...(prior?.afterMessages !== undefined
+        ? { afterMessages: prior.afterMessages }
+        : Number.isSafeInteger(afterMessages) && afterMessages >= 0
+          ? { afterMessages }
+          : {}),
+      ...(boundedPreview ? { preview: boundedPreview } : {}),
+    };
+    if (JSON.stringify(prior) === JSON.stringify(next)) return false;
+    setRecentBounded(this.#attention, key, next);
+    return true;
+  }
+
+  #emit() {
+    this.#onChange?.(this.snapshot());
+  }
+}
+
+export function createNativeSessionAttentionTracker(options) {
+  return new NativeSessionAttentionTracker(options);
+}
+
+export function normalizeNativeMessengerState(value) {
+  const parsed = objectRecord(value);
+  const attention = nativeAttentionState(parsed);
+  const draftRecord = objectRecord(parsed?.drafts);
+  const drafts = draftRecord
+    ? Object.fromEntries(
+        Object.entries(draftRecord).slice(0, NATIVE_STATE_LIMIT).flatMap(([key, draft]) =>
+          key && key.length <= 200 && typeof draft === 'string' && draft
+            ? [[key, draft.slice(0, 50_000)]]
+            : [],
+        ),
+      )
+    : {};
+  const modeRecord = objectRecord(parsed?.preferredLaunchModes);
+  const preferredLaunchModes = modeRecord
+    ? Object.fromEntries(
+        Object.entries(modeRecord).slice(0, NATIVE_STATE_LIMIT).filter(
+          ([key, mode]) =>
+            key && key.length <= 200 && (mode === 'headless' || mode === 'terminal'),
+        ),
+      )
+    : {};
+  return {
+    version: 1,
+    attention: attention.attention,
+    observedCursors: attention.observedCursors,
+    drafts,
+    preferredLaunchModes,
+  };
+}
+
+/** One serializable, bounded state owner for native-session messenger chrome. Storage location,
+ * encryption, debounce, and multi-device synchronization remain host policy. */
+export class NativeMessengerState {
+  #attention;
+  #drafts;
+  #onChange;
+  #preferredLaunchModes;
+
+  constructor(options = {}) {
+    const state = normalizeNativeMessengerState(options.state);
+    this.#onChange = options.onChange;
+    this.#drafts = new Map(Object.entries(state.drafts));
+    this.#preferredLaunchModes = new Map(Object.entries(state.preferredLaunchModes));
+    this.#attention = new NativeSessionAttentionTracker({
+      state,
+      onChange: () => this.#emit(),
+    });
+  }
+
+  observeAttention(options) {
+    return this.#attention.observe(options);
+  }
+
+  acknowledge(key) {
+    return this.#attention.acknowledge(key);
+  }
+
+  draft(key) {
+    return this.#drafts.get(key) ?? '';
+  }
+
+  setDraft(key, draft) {
+    if (typeof key !== 'string' || !key || key.length > 200 || typeof draft !== 'string') {
+      throw new TypeError('NativeMessengerState draft needs a bounded key and string value.');
+    }
+    const next = draft.slice(0, 50_000);
+    const previous = this.#drafts.get(key) ?? '';
+    if (previous === next) return false;
+    if (next) setRecentBounded(this.#drafts, key, next);
+    else this.#drafts.delete(key);
+    this.#emit();
+    return true;
+  }
+
+  preferredLaunchMode(harness) {
+    return this.#preferredLaunchModes.get(harness) ?? null;
+  }
+
+  setPreferredLaunchMode(harness, mode) {
+    if (
+      typeof harness !== 'string' ||
+      !harness ||
+      harness.length > 200 ||
+      (mode !== 'headless' && mode !== 'terminal')
+    ) {
+      throw new TypeError('NativeMessengerState launch preference must be headless or terminal.');
+    }
+    if (this.#preferredLaunchModes.get(harness) === mode) return false;
+    setRecentBounded(this.#preferredLaunchModes, harness, mode);
+    this.#emit();
+    return true;
+  }
+
+  snapshot() {
+    const attention = this.#attention.snapshot();
+    return {
+      version: 1,
+      attention: attention.attention,
+      observedCursors: attention.observedCursors,
+      drafts: Object.fromEntries(this.#drafts),
+      preferredLaunchModes: Object.fromEntries(this.#preferredLaunchModes),
+    };
+  }
+
+  #emit() {
+    this.#onChange?.(this.snapshot());
+  }
+}
+
+export function createNativeMessengerState(options) {
+  return new NativeMessengerState(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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter-ai-dev/supercode-ui",
-  "version": "0.1.64",
+  "version": "0.1.66",
   "type": "module",
   "description": "Composable default UI kit for Supercode-powered coding-agent experiences",
   "exports": {