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

package/conversation.mjs

@@ -33,6 +33,10 @@ var EMPTY_UI_STATE = Object.freeze({
   harness: "",
   mode: "none",
   strategy: null,
+  participant: Object.freeze({ kind: "local-user", label: null, origin: null }),
+  workspaceRef: Object.freeze({ kind: "none", value: null }),
+  mirror: null,
+  holder: null,
   canSend: false,
   canSteer: false,
   canResume: false,
@@ -70,7 +74,12 @@ var EMPTY_UI_STATE = Object.freeze({
   subagentInspector: null,
   attached: null,
   owned: null,
-  attachError: null
+  attachError: null,
+  agentPackage: null,
+  contributions: Object.freeze([]),
+  agentPackageError: null,
+  agentPackageCapabilityState: null,
+  agentPackageCapabilityError: null
 });
 var TOOL_CATEGORIES = /* @__PURE__ */ new Set(["read", "search", "edit", "command", "test", "web", "agent", "plan", "other"]);
 var MAX_TOOL_FIELDS = 8;
@@ -530,7 +539,11 @@ function languageLabel(info) {
 }
 function frameCode(render, tokens, index, options, env, self) {
   const label = markdown.utils.escapeHtml(languageLabel(tokens[index]?.info ?? ""));
-  return `<div class="scui-code-block"><div class="scui-code-head"><span>${label}</span><button class="scui-code-copy" type="button" aria-label="Copy code" title="Copy code">${COPY_ICON}<span>Copy</span></button></div>${render(tokens, index, options, env, self)}</div>`;
+  const body = render(tokens, index, options, env, self).replace(
+    "<pre>",
+    `<pre tabindex="0" role="region" aria-label="${label} code">`
+  );
+  return `<div class="scui-code-block"><div class="scui-code-head"><span>${label}</span><button class="scui-code-copy" type="button" aria-label="Copy code" title="Copy code">${COPY_ICON}<span>Copy</span></button></div>${body}</div>`;
 }
 for (const kind of ["fence", "code_block"]) {
   const render = markdown.renderer.rules[kind];
@@ -588,6 +601,12 @@ function Markdown({ value, copyText }) {
 
 // src/memory.js
 var MEMORY_LIMIT = 100;
+var registry = /* @__PURE__ */ new Set();
+function uiMemory() {
+  const map = /* @__PURE__ */ new Map();
+  registry.add(map);
+  return map;
+}
 function boundedSet(map, key, value) {
   map.delete(key);
   map.set(key, value);
@@ -1091,6 +1110,26 @@ function TechnicalDetails({ entry }) {
   ] });
 }
 function TranscriptEntry({ entry, state, adapter }) {
+  if (entry.role === "opaque") {
+    return /* @__PURE__ */ jsxs3("article", { className: "scui-message scui-opaque", "data-role": "opaque", "data-kind": entry.kind, "aria-label": "Unrecognized entry", children: [
+      /* @__PURE__ */ jsxs3("div", { className: "scui-notice", "data-code": "opaque-entry", children: [
+        "Unrecognized entry kind ",
+        /* @__PURE__ */ jsx4("code", { children: entry.kind }),
+        " \u2014 kept as-is, nothing dropped"
+      ] }),
+      entry.text ? /* @__PURE__ */ jsx4(Markdown, { value: entry.text, copyText: adapter?.copyText }) : null,
+      entry.raw ? /* @__PURE__ */ jsxs3("details", { className: "scui-tool-technical", children: [
+        /* @__PURE__ */ jsx4("summary", { children: "Technical details" }),
+        /* @__PURE__ */ jsx4("div", { children: /* @__PURE__ */ jsxs3("section", { children: [
+          /* @__PURE__ */ jsx4("strong", { children: "Raw entry" }),
+          /* @__PURE__ */ jsxs3("pre", { children: [
+            entry.raw,
+            entry.truncated ? "\n[truncated]" : ""
+          ] })
+        ] }) })
+      ] }) : null
+    ] });
+  }
   if (entry.role === "request") return /* @__PURE__ */ jsx4(RequestCard, { entry, adapter, canRespond: state.canRespond });
   if (entry.role === "reasoning") {
     return /* @__PURE__ */ jsxs3("details", { className: "scui-reasoning", open: entry.streaming, children: [
@@ -1220,7 +1259,7 @@ function SessionDetails({ semantics }) {
     ] })
   ] });
 }
-var conversationMemory = /* @__PURE__ */ new Map();
+var conversationMemory = uiMemory();
 function ConversationAnnouncements({ state }) {
   const previousBusy = useRef3(state.busy);
   const [announcement, setAnnouncement] = useState2("");

package/core.d.ts

@@ -1,6 +1,11 @@
 export type {
   AttachedSessionModel,
   AgentActivityModel,
+  AgentContributionModel,
+  AgentPackageModel,
+  AgentPackageResourceModel,
+  AgentPackageResourceStateModel,
+  AgentPackageCapabilityStateModel,
   ContinuationMode,
   ControlStrategy,
   HarnessId,
@@ -13,6 +18,10 @@ export type {
   SessionMode,
   SessionRowModel,
   SessionSemanticsModel,
+  CrossSurfaceModel,
+  HarnessSessionDescriptorModel,
+  TriggerKind,
+  TriggerModel,
   StartupPhase,
   SupercodeUiIntent,
   SupercodeUiState,
@@ -36,6 +45,7 @@ export {
   groupConversation,
   harnessDisplayName,
   isSendKey,
+  normalizeContributions,
   normalizeUiState,
   operationLabel,
   projectAgentActivity,
@@ -43,6 +53,9 @@ export {
   relativeAge,
   sessionActivity,
   sessionDisplayName,
+  sessionRowsFromDescriptors,
+  surfaceLabel,
+  selectContributions,
   terminalCommand,
   toolCategory,
   toolTarget,

package/core.mjs

@@ -30,6 +30,10 @@ export const EMPTY_UI_STATE = Object.freeze({
   harness: '',
   mode: 'none',
   strategy: null,
+  participant: Object.freeze({ kind: 'local-user', label: null, origin: null }),
+  workspaceRef: Object.freeze({ kind: 'none', value: null }),
+  mirror: null,
+  holder: null,
   canSend: false,
   canSteer: false,
   canResume: false,
@@ -68,6 +72,11 @@ export const EMPTY_UI_STATE = Object.freeze({
   attached: null,
   owned: null,
   attachError: null,
+  agentPackage: null,
+  contributions: Object.freeze([]),
+  agentPackageError: null,
+  agentPackageCapabilityState: null,
+  agentPackageCapabilityError: null,
 });
 
 const ROLES = new Set(['system', 'user', 'assistant', 'tool', 'reasoning', 'request', 'notice']);
@@ -81,6 +90,10 @@ const AUTHENTICATION_PHASES = new Set(['idle', 'checking', 'required', 'configur
 const MAX_TOOL_FIELDS = 8;
 const MAX_TOOL_FIELD_CHARS = 800;
 const MAX_TOOL_PREVIEW_CHARS = 4_000;
+const MAX_CONTRIBUTIONS = 64;
+const MAX_CONTRIBUTION_JSON_DEPTH = 12;
+const MAX_CONTRIBUTION_COLLECTION = 100;
+const MAX_CONTRIBUTION_STRING_CHARS = 16_000;
 
 function record(value) {
   return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : null;
@@ -121,6 +134,165 @@ function nullableNumber(value) {
   return typeof value === 'number' && Number.isFinite(value) ? value : null;
 }
 
+function relativeContributionPath(value) {
+  if (typeof value !== 'string' || value.startsWith('/') || /^[a-z]:[\\/]/i.test(value)) return null;
+  return value.replaceAll('\\', '/').split('/').some((segment) => segment === '..')
+    ? null
+    : boundedString(value, 1_000);
+}
+
+function contributionJson(value, depth = 0, seen = new WeakSet()) {
+  if (value === null || typeof value === 'boolean' || typeof value === 'string') {
+    return typeof value === 'string' ? boundedString(value, MAX_CONTRIBUTION_STRING_CHARS) : value;
+  }
+  if (typeof value === 'number') return Number.isFinite(value) ? value : undefined;
+  if (depth >= MAX_CONTRIBUTION_JSON_DEPTH || !value || typeof value !== 'object' || seen.has(value)) {
+    return undefined;
+  }
+  seen.add(value);
+  if (Array.isArray(value)) {
+    const result = [];
+    for (const item of value.slice(0, MAX_CONTRIBUTION_COLLECTION)) {
+      const normalized = contributionJson(item, depth + 1, seen);
+      if (normalized !== undefined) result.push(normalized);
+    }
+    seen.delete(value);
+    return result;
+  }
+  const source = record(value);
+  if (!source) return undefined;
+  const result = {};
+  for (const [key, item] of Object.entries(source).slice(0, MAX_CONTRIBUTION_COLLECTION)) {
+    const normalized = contributionJson(item, depth + 1, seen);
+    if (normalized !== undefined) result[boundedString(key, 200)] = normalized;
+  }
+  seen.delete(value);
+  return result;
+}
+
+export function normalizeContributions(value) {
+  if (!Array.isArray(value)) return [];
+  return value.slice(0, MAX_CONTRIBUTIONS).flatMap((candidate) => {
+    const item = record(candidate);
+    const placement = record(item?.placement);
+    const source = relativeContributionPath(item?.source);
+    if (
+      item?.schema !== 'supercode/contribution-v1' ||
+      typeof item.id !== 'string' || !item.id.trim() ||
+      typeof item.kind !== 'string' || !item.kind.trim() ||
+      source === null
+    ) return [];
+    const data = contributionJson(item.data);
+    if (data === undefined) return [];
+    return [{
+      schema: 'supercode/contribution-v1',
+      id: boundedString(item.id, 200),
+      kind: boundedString(item.kind, 100),
+      ...(typeof item.title === 'string' ? { title: boundedString(item.title, 500) } : {}),
+      ...(placement ? { placement: {
+        ...(typeof placement.surface === 'string' ? { surface: boundedString(placement.surface, 100) } : {}),
+        ...(typeof placement.region === 'string' ? { region: boundedString(placement.region, 100) } : {}),
+      } } : {}),
+      data,
+      source,
+    }];
+  });
+}
+
+export function selectContributions(contributions, query = {}) {
+  return normalizeContributions(contributions).filter((contribution) => (
+    (query.kind === undefined || contribution.kind === query.kind) &&
+    (query.surface === undefined || contribution.placement?.surface === query.surface) &&
+    (query.region === undefined || contribution.placement?.region === query.region)
+  ));
+}
+
+function readAgentPackage(value) {
+  const agentPackage = record(value);
+  const capabilities = record(agentPackage?.capabilities);
+  const storage = record(agentPackage?.storage);
+  const relativePath = relativeContributionPath(storage?.relativePath);
+  if (
+    agentPackage?.schemaVersion !== 1 ||
+    typeof agentPackage.id !== 'string' ||
+    typeof agentPackage.name !== 'string' ||
+    typeof agentPackage.version !== 'string' ||
+    !capabilities ||
+    !Array.isArray(capabilities.required) ||
+    !Array.isArray(capabilities.optional) ||
+    !storage ||
+    relativePath === null
+  ) return null;
+  const resources = record(agentPackage.resources);
+  return {
+    id: boundedString(agentPackage.id, 200),
+    name: boundedString(agentPackage.name, 500),
+    version: boundedString(agentPackage.version, 100),
+    description: typeof agentPackage.description === 'string'
+      ? boundedString(agentPackage.description, 2_000)
+      : null,
+    capabilities: {
+      required: capabilities.required.filter((item) => typeof item === 'string').slice(0, 100).map((item) => boundedString(item, 200)),
+      optional: capabilities.optional.filter((item) => typeof item === 'string').slice(0, 100).map((item) => boundedString(item, 200)),
+    },
+    storage: { relativePath },
+    resources: resources ? Object.fromEntries(Object.entries(resources).flatMap(([id, candidate]) => {
+      const state = record(candidate);
+      if (state?.schema !== 'supercode/package-resource-state-v1') return [];
+      if (state.status === 'absent' && typeof state.contributionId === 'string') {
+        return [[boundedString(id, 200), {
+          schema: 'supercode/package-resource-state-v1',
+          status: 'absent',
+          contributionId: boundedString(state.contributionId, 200),
+        }]];
+      }
+      if (state.status === 'error' && typeof state.contributionId === 'string' && typeof state.message === 'string') {
+        return [[boundedString(id, 200), {
+          schema: 'supercode/package-resource-state-v1',
+          status: 'error',
+          contributionId: boundedString(state.contributionId, 200),
+          message: boundedString(state.message),
+        }]];
+      }
+      const resource = record(state?.resource);
+      const data = contributionJson(resource?.data);
+      if (
+        state?.status !== 'ready' ||
+        resource?.schema !== 'supercode/package-resource-v1' ||
+        typeof resource.contributionId !== 'string' ||
+        !['json', 'text'].includes(resource.format) ||
+        typeof resource.mediaType !== 'string' ||
+        data === undefined
+      ) return [];
+      return [[boundedString(id, 200), {
+        schema: 'supercode/package-resource-state-v1',
+        status: 'ready',
+        resource: {
+          schema: 'supercode/package-resource-v1',
+          contributionId: boundedString(resource.contributionId, 200),
+          format: resource.format,
+          mediaType: boundedString(resource.mediaType, 200),
+          data,
+        },
+      }]];
+    })) : {},
+  };
+}
+
+function readAgentPackageCapabilityState(value) {
+  const state = record(value);
+  if (!state) return null;
+  const fields = ['availableRequired', 'missingRequired', 'enabledOptional', 'unavailableOptional'];
+  if (!fields.every((field) => Array.isArray(state[field]))) return null;
+  return {
+    ready: state.ready === true,
+    ...Object.fromEntries(fields.map((field) => [
+      field,
+      state[field].filter((item) => typeof item === 'string').slice(0, 100).map((item) => boundedString(item, 200)),
+    ])),
+  };
+}
+
 export function relativeAge(updatedAt, now = Date.now()) {
   if (typeof updatedAt !== 'number' || !Number.isFinite(updatedAt) || updatedAt <= 0) return '';
   const delta = Math.max(0, now - updatedAt);
@@ -504,12 +676,58 @@ function readToolPresentation(value, entry) {
   };
 }
 
+// Fast-churning upstreams will emit entry kinds this messenger has never
+// seen. Dropping them silently misrepresents the session, so an addressable
+// entry (a record with a string id) whose role or shape is unrecognized is
+// kept as a safe OPAQUE entry: the original kind is preserved as a label and
+// the raw payload stays available under technical details (UNI-13, the
+// messenger counterpart of the TUI's opaque-line rule). Only an entry with no
+// usable identity is still skipped — it cannot be keyed stably across
+// re-renders.
+const OPAQUE_RAW_CHARS = 4_000;
+
+function opaqueEntry(item) {
+  // An entry that is ALREADY opaque re-normalizes to itself (state flows
+  // through normalization more than once: host fixtures, the messenger's own
+  // read, mirrors), so the original kind and raw capture must survive
+  // instead of being re-wrapped under kind "opaque".
+  const previouslyOpaque = item.role === 'opaque';
+  let raw;
+  if (previouslyOpaque && typeof item.raw === 'string') {
+    raw = item.raw;
+  } else {
+    try {
+      raw = JSON.stringify(item, null, 2) ?? '';
+    } catch {
+      raw = '[unserializable entry payload]';
+    }
+  }
+  const kind = previouslyOpaque && typeof item.kind === 'string'
+    ? item.kind
+    : typeof item.role === 'string'
+      ? item.role
+      : '';
+  return {
+    id: item.id,
+    role: 'opaque',
+    kind: boundedString(kind, 120) || 'unknown',
+    text: typeof item.text === 'string' ? boundedString(item.text, OPAQUE_RAW_CHARS) : '',
+    ts: nullableNumber(item.ts),
+    truncated: item.truncated === true || raw.length > OPAQUE_RAW_CHARS,
+    raw: boundedString(raw, OPAQUE_RAW_CHARS),
+  };
+}
+
 function readTranscript(value) {
   if (!Array.isArray(value)) return [];
   const result = [];
   for (const candidate of value) {
     const item = record(candidate);
-    if (!item || typeof item.id !== 'string' || typeof item.text !== 'string' || !ROLES.has(item.role)) continue;
+    if (!item || typeof item.id !== 'string') continue;
+    if (typeof item.text !== 'string' || !ROLES.has(item.role)) {
+      result.push(opaqueEntry(item));
+      continue;
+    }
     const entry = {
       id: item.id,
       role: item.role,
@@ -574,6 +792,105 @@ function readTranscript(value) {
   return result;
 }
 
+// ---- UNI-8..UNI-12: the universal-layer UI nouns ---------------------------
+
+/// UNI-8: WHOSE conversation a session is. The messenger's historical implicit
+/// model is you-and-agent-in-a-workspace; Hermes/OpenClaw channel sessions are
+/// someone-else-and-agent. `kind` is the honest tri-state; `label` is the
+/// human ("@jane"), `origin` the surface ("slack", "telegram", "acp").
+function readParticipant(value) {
+  const participant = record(value);
+  if (!participant) return { kind: 'local-user', label: null, origin: null };
+  return {
+    kind: ['local-user', 'foreign', 'unknown'].includes(participant.kind) ? participant.kind : 'unknown',
+    label: typeof participant.label === 'string' && participant.label ? boundedString(participant.label, 200) : null,
+    origin: typeof participant.origin === 'string' && participant.origin ? boundedString(participant.origin, 100) : null,
+  };
+}
+
+/// UNI-9: a TYPED workspace. `repo` carries a path, `channel` carries a
+/// channel label, `none` is a first-class value (Hermes assistant chats) —
+/// not an empty string pretending to be a path.
+function readWorkspaceRef(value, fallbackPath = '') {
+  const ref = record(value);
+  if (ref && ['repo', 'none', 'channel'].includes(ref.kind)) {
+    return {
+      kind: ref.kind,
+      value: ref.kind === 'none' ? null : typeof ref.value === 'string' && ref.value ? boundedString(ref.value, 500) : null,
+    };
+  }
+  // Legacy hosts send only the string path.
+  return fallbackPath
+    ? { kind: 'repo', value: boundedString(fallbackPath, 500) }
+    : { kind: 'none', value: null };
+}
+
+/// UNI-10: canonical-elsewhere. A bounded/truncated MIRROR of a session whose
+/// canonical record lives in another store (OpenClaw supervising codex, ...).
+function readMirror(value) {
+  const mirror = record(value);
+  if (!mirror || typeof mirror.canonicalHarness !== 'string' || !mirror.canonicalHarness) return null;
+  return {
+    canonicalHarness: boundedString(mirror.canonicalHarness, 100),
+    canonicalKey: typeof mirror.canonicalKey === 'string' && mirror.canonicalKey ? boundedString(mirror.canonicalKey, 300) : null,
+    bounded: mirror.bounded === true,
+    truncated: mirror.truncated === true,
+    origin: typeof mirror.origin === 'string' && mirror.origin ? boundedString(mirror.origin, 200) : null,
+  };
+}
+
+/// UNI-11: which surface HOLDS this session now. `surface: 'supercode'` =
+/// held here (writable path); any other string = held by that surface
+/// (take-over is the transition, behind confirmIntent); null holder = unheld.
+function readHolder(value) {
+  const holder = record(value);
+  if (!holder) return null;
+  const surface = typeof holder.surface === 'string' && holder.surface ? boundedString(holder.surface, 100) : null;
+  return {
+    surface,
+    canTakeOver: holder.canTakeOver === true && surface !== null && surface !== 'supercode',
+  };
+}
+
+/// UNI-12/ORCH-6: WHY a session exists. Trigger provenance for unattended
+/// work, over the server's own `Trigger` enum. `manual` is the pre-ORCH-6
+/// spelling of `human` and stays accepted so existing hosts keep working.
+const TRIGGER_KINDS = ['human', 'channel', 'cron', 'heartbeat', 'webhook', 'parent', 'api', 'unknown'];
+function readTrigger(value) {
+  const trigger = record(value);
+  if (!trigger) return null;
+  const kind = trigger.kind === 'manual' ? 'human' : trigger.kind;
+  return {
+    kind: TRIGGER_KINDS.includes(kind) ? kind : 'unknown',
+    label: typeof trigger.label === 'string' && trigger.label ? boundedString(trigger.label, 200) : null,
+    surface: typeof trigger.surface === 'string' && trigger.surface ? boundedString(trigger.surface, 300) : null,
+  };
+}
+
+/// ORCH-6: a conversation that moved to another surface (Hermes `handoff_*`).
+function readCrossSurface(value) {
+  const moved = record(value);
+  if (!moved || typeof moved.state !== 'string' || !moved.state) return null;
+  return {
+    state: boundedString(moved.state, 100),
+    platform: typeof moved.platform === 'string' && moved.platform ? boundedString(moved.platform, 100) : null,
+    error: typeof moved.error === 'string' && moved.error ? boundedString(moved.error, 500) : null,
+  };
+}
+
+/// UNI-12: recurring-run grouping. A row that REPRESENTS a group of runs of
+/// the same recurring trigger, so the inventory shows one line, not N.
+function readRecurring(value) {
+  const recurring = record(value);
+  if (!recurring || typeof recurring.groupKey !== 'string' || !recurring.groupKey) return null;
+  const runs = Number.isSafeInteger(recurring.runs) && recurring.runs > 0 ? recurring.runs : 1;
+  return {
+    groupKey: boundedString(recurring.groupKey, 300),
+    runs,
+    lastStatus: ['ok', 'failed', 'mixed'].includes(recurring.lastStatus) ? recurring.lastStatus : null,
+  };
+}
+
 function readSessions(value) {
   if (!Array.isArray(value)) return [];
   return value.flatMap((raw) => {
@@ -596,6 +913,12 @@ function readSessions(value) {
       runtimeStatus: row.runtimeStatus === 'running' || row.runtimeStatus === 'busy' || row.runtimeStatus === 'idle' ? row.runtimeStatus : null,
       ...(Number.isSafeInteger(row.subagentCount) && row.subagentCount > 0 ? { subagentCount: row.subagentCount } : {}),
       activity: ACTIVITY_PRIORITY[row.activity] !== undefined ? row.activity : undefined,
+      ...(row.participant !== undefined ? { participant: readParticipant(row.participant) } : {}),
+      workspaceRef: readWorkspaceRef(row.workspaceRef, string(row.cwd)),
+      ...(readMirror(row.mirror) ? { mirror: readMirror(row.mirror) } : {}),
+      ...(readTrigger(row.trigger) ? { trigger: readTrigger(row.trigger) } : {}),
+      ...(readRecurring(row.recurring) ? { recurring: readRecurring(row.recurring) } : {}),
+      ...(readCrossSurface(row.crossSurface) ? { crossSurface: readCrossSurface(row.crossSurface) } : {}),
     }];
   });
 }
@@ -836,6 +1159,10 @@ export function normalizeUiState(value) {
     canConfigureSettings: raw.canConfigureSettings === true,
     messaging: raw.messaging === 'live_peer' ? 'live_peer' : null,
     workspace: string(raw.workspace),
+    workspaceRef: readWorkspaceRef(raw.workspaceRef, string(raw.workspace)),
+    participant: readParticipant(raw.participant),
+    mirror: readMirror(raw.mirror),
+    holder: readHolder(raw.holder),
     taskPlan: readTaskPlan(raw.taskPlan),
     semantics: readSemantics(raw.semantics),
     terminalHandoff: readTerminalHandoff(raw.terminalHandoff),
@@ -896,6 +1223,13 @@ export function normalizeUiState(value) {
     attached: readAttached(raw.attached),
     owned: readAttached(raw.owned),
     attachError: attachError && typeof attachError.key === 'string' && typeof attachError.message === 'string' ? { key: attachError.key, message: attachError.message } : null,
+    agentPackage: readAgentPackage(raw.agentPackage),
+    contributions: normalizeContributions(raw.contributions),
+    agentPackageError: typeof raw.agentPackageError === 'string' ? boundedString(raw.agentPackageError) : null,
+    agentPackageCapabilityState: readAgentPackageCapabilityState(raw.agentPackageCapabilityState),
+    agentPackageCapabilityError: typeof raw.agentPackageCapabilityError === 'string'
+      ? boundedString(raw.agentPackageCapabilityError)
+      : null,
   };
 }
 
@@ -903,6 +1237,61 @@ export function harnessDisplayName(id) {
   return HARNESS_NAMES[id] ?? id;
 }
 
+/// ORCH-6: the compact surface key a person reads —
+/// `telegram:dm:123456`, `slack:channel:C1`, `acp`. Empty for a surface with
+/// nothing to say (a terminal session).
+export function surfaceLabel(value) {
+  const surface = record(value);
+  if (!surface) return '';
+  const parts = [surface.platform, surface.kind, surface.chat_id, surface.thread_id]
+    .filter((part) => typeof part === 'string' && part);
+  return parts.length ? boundedString(parts.join(':'), 300) : '';
+}
+
+/// ORCH-6: project `harness.v1.sessions.discover` / `sessions.load` rows into
+/// list rows. This is the ONE client-side mapping from the service's wire
+/// shape to {@link SessionRowModel}: the conversation nouns
+/// (`trigger`/`surface`/`profile`/`recurrence`/`cross_surface`/`workspace`)
+/// are read straight off the server's derivation, never re-derived here.
+export function sessionRowsFromDescriptors(value) {
+  if (!Array.isArray(value)) return [];
+  return readSessions(value.flatMap((raw) => {
+    const descriptor = record(raw);
+    const locator = record(descriptor?.locator);
+    if (!locator || typeof locator.harness !== 'string' || typeof locator.session_id !== 'string') return [];
+    const surface = record(descriptor.surface);
+    const label = surfaceLabel(surface);
+    const cwd = typeof descriptor.cwd === 'string' ? descriptor.cwd : '';
+    const title = typeof descriptor.title === 'string' ? descriptor.title : '';
+    const recurrence = record(descriptor.recurrence);
+    return [{
+      key: `${locator.harness}:${locator.session_id}`,
+      harness: locator.harness,
+      name: label || cwd.split(/[\\/]/).filter(Boolean).pop() || locator.session_id,
+      cwd,
+      title,
+      updatedAt: descriptor.updated_at_ms ?? null,
+      messages: descriptor.message_count ?? null,
+      active: false,
+      writable: false,
+      live: false,
+      runtimeStatus: null,
+      subagentCount: descriptor.child_session_count,
+      workspaceRef: descriptor.workspace,
+      trigger: { kind: descriptor.trigger ?? 'unknown', label: recurrence?.job_id ?? descriptor.profile ?? null, surface: label || null },
+      // One fire is one row: supercode renders the grouping a harness
+      // publishes, it never invents a run count it has not counted.
+      ...(recurrence?.job_id ? { recurring: { groupKey: recurrence.job_id, runs: 1, lastStatus: null } } : {}),
+      ...(descriptor.cross_surface ? { crossSurface: descriptor.cross_surface } : {}),
+      // A channel surface names the person who reached the agent; a terminal
+      // session has no platform and stays the local user.
+      ...(surface?.platform && surface?.participant_id
+        ? { participant: { kind: 'foreign', label: surface.participant_id, origin: surface.platform } }
+        : {}),
+    }];
+  }));
+}
+
 export function sessionDisplayName(session) {
   const title = session.title?.trim();
   return title && title !== session.name ? title : session.name || 'Untitled chat';