@volter-ai-dev/supercode-ui 0.1.63 → 0.1.65

package/README.md

@@ -237,6 +237,12 @@ 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.
+
 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
@@ -263,6 +269,9 @@ opaque-key callback and retains the reversible locator map. Its `isWritable` cap
 is fail-closed: unread badges remain neutral until the host proves a real send or terminal-control
 path. Runtime activity remains independent, so a read-only channel can still truthfully show that
 its external agent is working or needs input.
+`matchesSessionRef`, `projectAttachedSession`, and `formatWorkspacePath` complete that trusted-host
+adapter so products do not need local copies of active-session matching, fallback header identity,
+or home-relative path formatting.
 
 ## Modularity contract
 

package/controller.d.ts

@@ -72,6 +72,23 @@ export interface SessionInventoryProjectionOptions {
   isWritable?(descriptor: SessionDescriptor): boolean;
 }
 
+export interface ActiveSessionRef {
+  harness: string;
+  sessionId: string | null;
+}
+
+export function formatWorkspacePath(cwd: string | null | undefined, home?: string): string;
+export function matchesSessionRef(
+  descriptor: SessionDescriptor,
+  active: ActiveSessionRef | null | undefined,
+): boolean;
+export function projectAttachedSession(
+  active: ActiveSessionRef | null | undefined,
+  rows: readonly SessionRowModel[],
+  fallbackWorkspace: string,
+  home?: string,
+): AttachedSessionModel | null;
+
 export function sessionConversationUpdatedAt(descriptor: SessionDescriptor): number | null;
 export function sessionDescriptorRuntimeStatus(
   descriptor: SessionDescriptor,

package/controller.mjs

@@ -29,12 +29,42 @@ function workspaceName(cwd) {
   return cwd.replaceAll('\\', '/').split('/').filter(Boolean).at(-1) ?? cwd;
 }
 
-function shortWorkspacePath(cwd, home) {
+export function formatWorkspacePath(cwd, home) {
   if (typeof cwd !== 'string' || !cwd) return '';
   const root = typeof home === 'string' && home.endsWith('/') ? home.slice(0, -1) : home;
   return root && (cwd === root || cwd.startsWith(`${root}/`)) ? `~${cwd.slice(root.length)}` : cwd;
 }
 
+export function matchesSessionRef(descriptor, active) {
+  return Boolean(
+    active?.sessionId !== null &&
+      active?.sessionId !== undefined &&
+      descriptor?.locator?.harness === active.harness &&
+      descriptor?.locator?.session_id === active.sessionId,
+  );
+}
+
+export function projectAttachedSession(active, rows, fallbackWorkspace, home) {
+  if (!active?.harness) return null;
+  const row = rows.find((candidate) => candidate.active);
+  if (row) {
+    return {
+      key: row.key,
+      harness: row.harness,
+      name: row.name,
+      cwd: row.cwd,
+      title: row.title,
+    };
+  }
+  return {
+    key: '',
+    harness: active.harness,
+    name: workspaceName(fallbackWorkspace) || 'no workspace',
+    cwd: formatWorkspacePath(fallbackWorkspace, home),
+    title: workspaceName(fallbackWorkspace) || 'Untitled chat',
+  };
+}
+
 function compactTopic(value) {
   const text = typeof value === 'string' ? value.replace(/\s+/g, ' ').trim() : '';
   if (text.length <= 72) return text;
@@ -115,7 +145,7 @@ export function projectSessionInventory(descriptors, options) {
       key,
       harness: descriptor.locator.harness,
       name: workspaceName(descriptor.cwd) || 'no workspace',
-      cwd: shortWorkspacePath(descriptor.cwd, options.home),
+      cwd: formatWorkspacePath(descriptor.cwd, options.home),
       title: descriptorTitle(descriptor),
       preview: preview?.text ?? '',
       age: relativeAge(preview?.updatedAt ?? updatedAt, now),

package/host.d.ts

@@ -72,6 +72,43 @@ 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 RemoteUiBindingOptions
   extends Pick<
     UiAdapter,

package/host.mjs

@@ -1,5 +1,6 @@
 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';
 
@@ -321,6 +322,246 @@ 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, 500).flatMap((candidate) => {
+        const item = objectRecord(candidate);
+        if (
+          typeof item?.key !== 'string' ||
+          !['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, 500).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) {
+            this.#observedCursors.set(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) {
+        this.#observedCursors.set(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;
+    this.#attention.set(key, next);
+    return true;
+  }
+
+  #emit() {
+    this.#onChange?.(this.snapshot());
+  }
+}
+
+export function createNativeSessionAttentionTracker(options) {
+  return new NativeSessionAttentionTracker(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.63",
+  "version": "0.1.65",
   "type": "module",
   "description": "Composable default UI kit for Supercode-powered coding-agent experiences",
   "exports": {