@volter-ai-dev/supercode-ui 0.1.35 → 0.1.36

package/README.md

@@ -117,6 +117,9 @@ before counting visible rows, retains native timestamps and typed tool/request l
 the uncapped residue count truthful. Hosts can narrow those limits with `ClientProjectionOptions`
 and can overlay a machine-wide session inventory, pagination state, attention, drafts, attachment
 errors, and owned/attached identities without reimplementing transcript or capability semantics.
+`projectSessionInventory` performs the corresponding title, latest-preview, activity, path, age,
+sorting, and row projection for raw machine-wide descriptors; the trusted host supplies only its
+opaque-key callback and retains the reversible locator map.
 
 ## Modularity contract
 
@@ -140,6 +143,9 @@ errors, and owned/attached identities without reimplementing transcript or capab
 
 `SupercodeUiState` is a transport-safe view model, not a duplicate controller. A trusted host maps
 `SupercodeController` snapshots and persisted inventory into it, then handles `SupercodeUiIntent`.
+An iframe or extension host can pass unknown payloads through `parseSupercodeUiIntent` before using
+`dispatchControllerIntent`; transport-specific operations can be intercepted with `handleIntent`
+while ordinary controller semantics continue through the shared dispatcher.
 The browser cannot supply locators, credentials, policy, environment variables, or arbitrary
 materialization paths. Session keys and target harnesses must be revalidated by the host.
 Harness configuration is similarly narrow: the UI can only submit a choice from the revisioned

package/controller.d.ts

@@ -1,5 +1,6 @@
 import type {
   SessionArtifact,
+  SessionDescriptor,
   SessionFormat,
 } from '@volter-ai-dev/supercode-harness-sdk';
 import type {
@@ -55,6 +56,30 @@ export function projectClientSnapshot(
   options?: ClientProjectionOptions,
 ): SupercodeUiState;
 
+export interface SessionInventoryProjectionOptions {
+  /** Mint a transport-safe key while retaining the reversible locator only in the trusted host. */
+  keyFor(descriptor: SessionDescriptor): string;
+  now?: number;
+  home?: string;
+  active?: { harness: string; sessionId: string | null } | null;
+  maxSessions?: number;
+  liveWindowMs?: number;
+  preserveOrder?: boolean;
+}
+
+export function sessionConversationUpdatedAt(descriptor: SessionDescriptor): number | null;
+export function sessionDescriptorRuntimeStatus(
+  descriptor: SessionDescriptor,
+): 'running' | 'busy' | 'idle' | null;
+export interface ProjectedSessionRowModel extends SessionRowModel {
+  preview: string;
+  previewUpdatedAt: number | null;
+}
+export function projectSessionInventory(
+  descriptors: readonly SessionDescriptor[],
+  options: SessionInventoryProjectionOptions,
+): ProjectedSessionRowModel[];
+
 export interface ResolvableTranscriptImage {
   id?: string;
   label: string;
@@ -79,6 +104,8 @@ export interface ControllerBindingOptions {
   onIntent?: (intent: SupercodeUiIntent) => void | Promise<void>;
   onUnsupported?: (intent: SupercodeUiIntent) => void | Promise<void>;
   onError?: (error: unknown, intent: SupercodeUiIntent) => void | Promise<void>;
+  /** Return true after handling an intent to replace the standard controller mapping. */
+  handleIntent?: (intent: SupercodeUiIntent) => boolean | Promise<boolean>;
   onArtifact?: (artifact: SessionArtifact, intent: Extract<SupercodeUiIntent, { action: 'export' }>) => void | Promise<void>;
   onDraft?: (text: string) => void | Promise<void>;
   onAcknowledge?: (key: string) => void | Promise<void>;
@@ -90,6 +117,18 @@ export interface ControllerBindingOptions {
   resolveImage?: UiAdapter['resolveImage'];
 }
 
+export interface ControllerIntentTarget {
+  getSnapshot(): SupercodeClientSnapshot;
+  dispatch(action: Parameters<SupercodeController['dispatch']>[0]): Promise<SupercodeClientSnapshot>;
+  exportSession?: SupercodeController['exportSession'];
+}
+
+export function dispatchControllerIntent(
+  controller: ControllerIntentTarget,
+  intent: SupercodeUiIntent,
+  options?: ControllerBindingOptions,
+): Promise<void>;
+
 export interface SupercodeUiBinding {
   adapter: UiAdapter;
   getState(): SupercodeUiState;

package/controller.mjs

@@ -1,3 +1,4 @@
+import { conversationPreviewText } from '@volter-ai-dev/supercode-client';
 import { createToolPresentation, normalizeUiState, relativeAge } from './core.mjs';
 
 const HARNESS_LABELS = {
@@ -28,6 +29,110 @@ function workspaceName(cwd) {
   return cwd.replaceAll('\\', '/').split('/').filter(Boolean).at(-1) ?? cwd;
 }
 
+function shortWorkspacePath(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;
+}
+
+function compactTopic(value) {
+  const text = typeof value === 'string' ? value.replace(/\s+/g, ' ').trim() : '';
+  if (text.length <= 72) return text;
+  const prefix = text.slice(0, 71);
+  const boundary = prefix.lastIndexOf(' ');
+  return `${prefix.slice(0, boundary >= 40 ? boundary : 71).trimEnd()}…`;
+}
+
+export function sessionDescriptorRuntimeStatus(descriptor) {
+  const activity = descriptor?.activity;
+  if (activity && typeof activity === 'object') {
+    if (activity.presence === 'persisted') return null;
+    if (activity.turn === 'working') return 'busy';
+    if (activity.turn === 'idle' || activity.turn === 'needs_input') return 'idle';
+    if (activity.presence === 'running' || activity.presence === 'shutting_down') return 'running';
+  }
+  return ['running', 'busy', 'idle'].includes(descriptor?.live_status)
+    ? descriptor.live_status
+    : null;
+}
+
+function descriptorPreview(descriptor) {
+  for (const candidate of descriptor?.latest_message_candidates ?? []) {
+    const text = conversationPreviewText([candidate]);
+    if (!text) continue;
+    return { text, updatedAt: timestampFromMetadata(candidate.metadata) };
+  }
+  return null;
+}
+
+function descriptorTitle(descriptor) {
+  const nativeTitle = typeof descriptor?.title === 'string' ? descriptor.title.trim() : '';
+  const workspace = workspaceName(descriptor?.cwd);
+  if (nativeTitle && nativeTitle !== workspace && nativeTitle !== descriptor?.cwd) {
+    return compactTopic(nativeTitle);
+  }
+  if (descriptor?.locator?.harness !== 'claude-code' && descriptor?.locator?.harness !== 'codex') {
+    return compactTopic(nativeTitle || workspace || descriptor?.locator?.session_id?.slice(0, 8)) || 'Untitled chat';
+  }
+  const openingUserMessages = (descriptor?.preview_candidates ?? []).filter(
+    (candidate) => candidate?.role === undefined || candidate.role === 'user',
+  );
+  return compactTopic(conversationPreviewText(openingUserMessages)) || 'Untitled chat';
+}
+
+/** Timestamp represented by a messenger row, independent of native store heartbeat writes. */
+export function sessionConversationUpdatedAt(descriptor) {
+  return descriptorPreview(descriptor)?.updatedAt ?? descriptor?.updated_at_ms ?? null;
+}
+
+/**
+ * Project trusted machine-wide descriptors into the same bounded rows as controller snapshots.
+ * The host supplies opaque keys because only it may retain the reversible locator mapping.
+ */
+export function projectSessionInventory(descriptors, options) {
+  if (typeof options?.keyFor !== 'function') {
+    throw new TypeError('projectSessionInventory requires an opaque keyFor callback');
+  }
+  const now = Number.isFinite(options.now) ? options.now : Date.now();
+  const maxSessions = positiveInteger(options.maxSessions, DEFAULT_MAX_SESSIONS);
+  const liveWindowMs = positiveInteger(options.liveWindowMs, DEFAULT_LIVE_WINDOW_MS);
+  const active = options.active;
+  const seen = new Set();
+  const rows = [];
+  const ordered = options.preserveOrder
+    ? [...(descriptors ?? [])]
+    : [...(descriptors ?? [])].sort(
+        (left, right) => (sessionConversationUpdatedAt(right) ?? 0) - (sessionConversationUpdatedAt(left) ?? 0),
+      );
+  for (const descriptor of ordered) {
+    if (!descriptor?.locator) continue;
+    const key = options.keyFor(descriptor);
+    if (typeof key !== 'string' || !key || seen.has(key)) continue;
+    seen.add(key);
+    const preview = descriptorPreview(descriptor);
+    const updatedAt = typeof descriptor.updated_at_ms === 'number' ? descriptor.updated_at_ms : null;
+    rows.push({
+      key,
+      harness: descriptor.locator.harness,
+      name: workspaceName(descriptor.cwd) || 'no workspace',
+      cwd: shortWorkspacePath(descriptor.cwd, options.home),
+      title: descriptorTitle(descriptor),
+      preview: preview?.text ?? '',
+      age: relativeAge(preview?.updatedAt ?? updatedAt, now),
+      previewUpdatedAt: preview?.updatedAt ?? null,
+      updatedAt,
+      messages: typeof descriptor.message_count === 'number' ? descriptor.message_count : null,
+      active: active?.sessionId != null
+        && descriptor.locator.harness === active.harness
+        && descriptor.locator.session_id === active.sessionId,
+      live: updatedAt !== null && now - updatedAt <= liveWindowMs,
+      runtimeStatus: sessionDescriptorRuntimeStatus(descriptor),
+    });
+    if (rows.length >= maxSessions) break;
+  }
+  return rows;
+}
+
 function payloadText(payload) {
   if (typeof payload === 'string') return payload;
   try {
@@ -440,7 +545,8 @@ export function createClientProjection(snapshot, options = {}) {
   };
 }
 
-async function dispatchStandard(controller, intent, options) {
+export async function dispatchControllerIntent(controller, intent, options = {}) {
+  if (await options.handleIntent?.(intent)) return;
   const snapshot = controller.getSnapshot();
   const active = snapshot.activeSessionKey;
   if (intent.action === 'mounted') return;
@@ -496,7 +602,7 @@ export function createControllerBinding(controller, options = {}) {
   const adapter = {
     onIntent(intent) {
       return Promise.resolve(options.onIntent?.(intent))
-        .then(() => dispatchStandard(controller, intent, options))
+        .then(() => dispatchControllerIntent(controller, intent, options))
         .catch((error) => options.onError?.(error, intent))
         .then(() => undefined);
     },

package/core.d.ts

@@ -37,6 +37,7 @@ export {
   isSendKey,
   normalizeUiState,
   operationLabel,
+  parseSupercodeUiIntent,
   relativeAge,
   sessionActivity,
   sessionDisplayName,

package/core.mjs

@@ -920,3 +920,140 @@ export function terminalCommand(handoff) {
 export function isSendKey(event) {
   return event.key === 'Enter' && !event.shiftKey && !event.isComposing;
 }
+
+function intentRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : null;
+}
+
+function intentKeys(value, allowed) {
+  return Object.keys(value).every((key) => allowed.includes(key));
+}
+
+function intentContext(value) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.length > 32) return null;
+  const items = [];
+  for (const candidate of value) {
+    const item = intentRecord(candidate);
+    if (!item || !intentKeys(item, ['id', 'kind', 'label', 'detail'])) return null;
+    if (typeof item.label !== 'string' || !item.label.trim() || item.label.length > 200) return null;
+    if (typeof item.detail !== 'string' || item.detail.length > 20_000) return null;
+    if (item.id !== undefined && (typeof item.id !== 'string' || !item.id || item.id.length > 2_000)) return null;
+    if (item.kind !== undefined && (typeof item.kind !== 'string' || !item.kind || item.kind.length > 100)) return null;
+    items.push({
+      ...(typeof item.id === 'string' ? { id: item.id } : {}),
+      ...(typeof item.kind === 'string' ? { kind: item.kind } : {}),
+      label: item.label.trim(),
+      detail: item.detail,
+    });
+  }
+  return items;
+}
+
+function intentImages(value) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.length > 4) return null;
+  let totalChars = 0;
+  const items = [];
+  for (const candidate of value) {
+    const item = intentRecord(candidate);
+    if (!item || !intentKeys(item, ['id', 'label', 'url'])) return null;
+    if (typeof item.label !== 'string' || !item.label.trim() || item.label.length > 200) return null;
+    if (typeof item.url !== 'string' || !/^(?:data:image\/|https?:\/\/)/.test(item.url)) return null;
+    if (item.url.length > 12 * 1024 * 1024) return null;
+    totalChars += item.url.length;
+    if (totalChars > 32 * 1024 * 1024) return null;
+    if (item.id !== undefined && (typeof item.id !== 'string' || !item.id || item.id.length > 2_000)) return null;
+    items.push({ ...(typeof item.id === 'string' ? { id: item.id } : {}), label: item.label.trim(), url: item.url });
+  }
+  return items;
+}
+
+function intentJson(value, seen = new Set()) {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return true;
+  if (typeof value === 'number') return Number.isFinite(value);
+  if (typeof value !== 'object' || seen.has(value)) return false;
+  seen.add(value);
+  const valid = Array.isArray(value)
+    ? value.length <= 1_000 && value.every((item) => intentJson(item, seen))
+    : Object.keys(value).length <= 1_000 && Object.values(value).every((item) => intentJson(item, seen));
+  seen.delete(value);
+  return valid;
+}
+
+/** Runtime validation for the transport-safe intent union emitted by the default UI. */
+export function parseSupercodeUiIntent(value) {
+  const intent = intentRecord(value);
+  if (!intent || typeof intent.action !== 'string') return null;
+  const exact = (...keys) => intentKeys(intent, ['action', ...keys]);
+  const actionOnly = ['mounted', 'loadSessions', 'loadEarlier', 'join', 'detach', 'terminal', 'interrupt', 'refresh', 'release'];
+  if (actionOnly.includes(intent.action)) return exact() ? { action: intent.action } : null;
+  if (intent.action === 'attach' || intent.action === 'ack') {
+    return exact('key') && typeof intent.key === 'string' && intent.key.trim() && intent.key.length <= 4_000
+      ? { action: intent.action, key: intent.key.trim() }
+      : null;
+  }
+  if (intent.action === 'draft') {
+    return exact('text') && typeof intent.text === 'string' && intent.text.length <= 50_000
+      ? { action: 'draft', text: intent.text }
+      : null;
+  }
+  if (intent.action === 'send' || intent.action === 'new') {
+    const allowed = intent.action === 'new'
+      ? exact('harness', 'mode', 'text', 'context', 'images')
+      : exact('text', 'context', 'images');
+    const context = intentContext(intent.context);
+    const images = intentImages(intent.images);
+    if (!allowed || typeof intent.text !== 'string' || context === null || images === null) return null;
+    if (!intent.text.trim() && images.length === 0) return null;
+    const extras = {
+      ...(context.length ? { context } : {}),
+      ...(images.length ? { images } : {}),
+    };
+    if (intent.action === 'send') return { action: 'send', text: intent.text, ...extras };
+    if (typeof intent.harness !== 'string' || !intent.harness.trim() || intent.harness.length > 100) return null;
+    const mode = intent.mode === undefined ? undefined : intent.mode;
+    if (mode !== undefined && mode !== 'headless' && mode !== 'terminal') return null;
+    if (mode === 'terminal' && !intent.text.trim()) return null;
+    return { action: 'new', harness: intent.harness.trim(), ...(mode ? { mode } : {}), text: intent.text, ...extras };
+  }
+  if (intent.action === 'resume') {
+    return exact('mode') && (intent.mode === undefined || intent.mode === 'headless' || intent.mode === 'terminal')
+      ? { action: 'resume', ...(intent.mode ? { mode: intent.mode } : {}) }
+      : null;
+  }
+  if (intent.action === 'branch' || intent.action === 'reduce') {
+    if (!exact('targetHarness')) return null;
+    if (intent.targetHarness === undefined) return { action: intent.action };
+    return typeof intent.targetHarness === 'string' && intent.targetHarness.trim() && intent.targetHarness.length <= 100
+      ? { action: intent.action, targetHarness: intent.targetHarness.trim() }
+      : null;
+  }
+  if (intent.action === 'export') {
+    return exact('targetHarness') && typeof intent.targetHarness === 'string' && intent.targetHarness.trim() && intent.targetHarness.length <= 100
+      ? { action: 'export', targetHarness: intent.targetHarness.trim() }
+      : null;
+  }
+  if (intent.action === 'respond') {
+    if (!exact('requestId', 'optionId') || !intentJson(intent.requestId)) return null;
+    return intent.optionId === null || typeof intent.optionId === 'string'
+      ? { action: 'respond', requestId: intent.requestId, optionId: intent.optionId }
+      : null;
+  }
+  if (intent.action === 'configureHarness') {
+    if (!exact('harness', 'changes', 'expectedRevision')) return null;
+    if (typeof intent.harness !== 'string' || !intent.harness || intent.harness.length > 100) return null;
+    if (typeof intent.expectedRevision !== 'string' || !intent.expectedRevision || intent.expectedRevision.length > 500) return null;
+    if (!Array.isArray(intent.changes) || !intent.changes.length || intent.changes.length > 20) return null;
+    const changes = [];
+    for (const candidate of intent.changes) {
+      const change = intentRecord(candidate);
+      if (!change || !intentKeys(change, ['key', 'value'])) return null;
+      if (typeof change.key !== 'string' || !change.key || change.key.length > 200) return null;
+      if (change.value !== null && (typeof change.value !== 'string' || change.value.length > 500)) return null;
+      changes.push({ key: change.key, value: change.value });
+    }
+    return { action: 'configureHarness', harness: intent.harness, changes, expectedRevision: intent.expectedRevision };
+  }
+  return null;
+}

package/index.d.ts

@@ -449,6 +449,8 @@ export function canContinueHere(state: SupercodeUiState): boolean;
 export function operationLabel(operation: string | null): string;
 export function terminalCommand(handoff: NonNullable<SupercodeUiState['terminalHandoff']>): string;
 export function isSendKey(event: Pick<KeyboardEvent, 'key' | 'shiftKey' | 'isComposing'>): boolean;
+/** Strictly validate an unknown browser/wire payload as a bounded UI intent. */
+export function parseSupercodeUiIntent(value: unknown): SupercodeUiIntent | null;
 
 export function HarnessLogo(props: { id: HarnessId; activity?: SessionActivity; size?: number; onMissingLogo?(id: string): void }): VNode | null;
 export type UiIconName = 'attach' | 'back' | 'check' | 'chevron' | 'close' | 'copy' | 'down' | 'menu' | 'plus' | 'search' | 'send' | 'stop';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter-ai-dev/supercode-ui",
-  "version": "0.1.35",
+  "version": "0.1.36",
   "type": "module",
   "description": "Composable default UI kit for Supercode-powered coding-agent experiences",
   "exports": {
@@ -107,6 +107,7 @@
     }
   },
   "devDependencies": {
+    "@volter-ai-dev/supercode-client": "0.3.22",
     "@storybook/addon-a11y": "10.5.9",
     "@storybook/addon-docs": "10.5.9",
     "@storybook/addon-themes": "10.5.9",