aimeat 1.27.0 → 1.28.0

package/dist/public/js/services/notebook-plan.js

@@ -0,0 +1,211 @@
+/**
+ * @file notebook-plan.js
+ * @description Notebook stage 2 client service — enrichment PLAN generation + step execution. The plan
+ *   itself is produced server-side (POST /v1/librarian/plan, the user's own OpenRouter model reasoning
+ *   over the note); each step is then EXECUTED here over the generic AI + librarian APIs (no-SSR), and
+ *   the result is folded back into the note with a structured Sources/References trail. Phase 1 runs
+ *   two self-fulfilled step kinds: `llm_reason` (expand using only the note) and `librarian_assess`
+ *   (summarise the user's OWN existing material found via the librarian).
+ * @structure
+ *   - buildCatalogue(feed) — compact [{agent,offerId,title,ask,latency,cost}] from the /v1/offers feed
+ *   - generatePlan(text, catalogue) — POST /v1/librarian/plan (slow AI call; full timeout, no retry)
+ *   - runStep(step, ctx) — execute one plan step → EnrichmentResult { stepId, kind, markdown, sources }
+ *   - composeEnrichedMarkdown(noteText, enrichments) — note + folded results + Sources section
+ * @version-history
+ *   v1.0.0 — 2026-06-21 — Initial (Phase 1): plan generate + reason/librarian-assess execution.
+ *   v1.1.0 — 2026-06-21 — Phase 2: `delegate` execution — dispatch a fleet agent offer via offers.ask(),
+ *     await the task (SSE + poll), read the deliverable back, fold it in with agent provenance.
+ */
+import { api } from '/js/api.js';
+import { librarianSearch } from '/js/services/memory.js';
+import * as offers from '/js/services/offers.js';
+import { getTask } from '/js/services/agent-tasks.js';
+
+const ASSESS_HITS = 6;          // how many librarian hits to feed the assessor
+const AI_TIMEOUT_MS = 1_800_000; // 30 min — same as the classify call; the model may think a while
+const DELEGATE_TIMEOUT_MS = 900_000; // 15 min — fleet offers are "minutes" to "long-running"
+
+/** Build the compact offer catalogue the planner grounds delegate steps against, from the /v1/offers
+ *  envelope (offers.listOffers()). Online agents first; bounded to keep the prompt small. */
+export function buildCatalogue(feed) {
+  const agents = feed?.data?.agents || feed?.agents || [];
+  const rows = [];
+  for (const a of agents) {
+    for (const o of (a.offers || [])) {
+      rows.push({ agent: a.agent, offerId: o.id, title: o.title, ask: o.ask, latency: o.latency, cost: o.cost, _online: !!a.online });
+    }
+  }
+  rows.sort((x, y) => (y._online === x._online) ? 0 : (y._online ? 1 : -1));
+  return rows.slice(0, 60).map(({ _online, ...r }) => r);
+}
+
+/** Ask the backend planner what enrichment steps a note would benefit from. `catalogue` is the compact
+ *  offer list (buildCatalogue) so the planner can ground delegate steps. Returns { plan, context, model }.
+ *  Slow AI call — full timeout, no retry (a 30s abort would re-fire the still-running model). */
+export async function generatePlan(text, catalogue) {
+  const resp = await api('/v1/librarian/plan', {
+    method: 'POST',
+    body: JSON.stringify({ text, catalogue: Array.isArray(catalogue) ? catalogue : [] }),
+    timeoutMs: AI_TIMEOUT_MS,
+    retries: 0,
+  });
+  if (resp?.ok === false) { const e = new Error(resp.error?.message || 'Plan failed'); e.code = resp.error?.code; throw e; }
+  return resp?.data || null;
+}
+
+/** Await a dispatched task to a terminal state, refreshing on the live-update event and polling as a
+ *  fallback. Resolves the task record on 'done'; throws on failed/stalled/timeout.
+ *  @param {string} agentName
+ *  @param {string} taskId
+ *  @param {{ onStatus?: (status: string) => void }} [opts] */
+function awaitTask(agentName, taskId, opts = {}) {
+  const { onStatus } = opts;
+  return new Promise((resolve, reject) => {
+    const deadline = Date.now() + DELEGATE_TIMEOUT_MS;
+    let settled = false;
+    const cleanup = () => { clearInterval(timer); window.removeEventListener('aimeat-live-update', onLive); };
+    async function check() {
+      if (settled) return;
+      let task = null;
+      try { const r = await getTask(agentName, taskId); task = r?.data?.task || r?.data || null; } catch { /* transient */ }
+      const status = task?.status;
+      if (status) onStatus?.(status);
+      if (status === 'done') { settled = true; cleanup(); resolve(task); return; }
+      if (status === 'failed' || status === 'stalled') { settled = true; cleanup(); reject(new Error('Agent task ' + status)); return; }
+      if (Date.now() > deadline) { settled = true; cleanup(); reject(new Error('TIMEOUT')); }
+    }
+    const onLive = (e) => { const d = e.detail?.domains; if (d && !d.has('agent-tasks')) return; check(); };
+    const timer = setInterval(check, 5000);
+    window.addEventListener('aimeat-live-update', onLive);
+    check();
+  });
+}
+
+/** One AI completion via the user's own key (budget-enforced server-side). Returns { content, model }. */
+async function aiComplete(prompt, systemPrompt) {
+  const resp = await api('/v1/ai/complete', {
+    method: 'POST',
+    body: JSON.stringify({ prompt, systemPrompt, app_id: 'notebook' }),
+    timeoutMs: AI_TIMEOUT_MS,
+    retries: 0,
+  });
+  if (resp?.ok === false) { const e = new Error(resp.error?.message || 'AI completion failed'); e.code = resp.error?.code; throw e; }
+  return resp?.data || { content: '', model: '' };
+}
+
+function priorBlock(priorEnrichments) {
+  if (!priorEnrichments?.length) return '';
+  return '\n\nResults from earlier enrichment steps:\n\n' +
+    priorEnrichments.map((e, i) => `### Step ${i + 1}\n${e.markdown}`).join('\n\n');
+}
+
+/** Execute one plan step. ctx = { noteText, priorEnrichments }. Returns an EnrichmentResult. */
+export async function runStep(step, ctx) {
+  const noteText = ctx?.noteText || '';
+  const prior = ctx?.priorEnrichments || [];
+  const retrievedAt = new Date().toISOString();
+
+  if (step.kind === 'librarian_assess') {
+    const hits = await librarianSearch(step.query, ASSESS_HITS, 'own');
+    if (!hits.length) {
+      return {
+        stepId: step.id, kind: step.kind, producedAt: retrievedAt,
+        markdown: `_No related material found in your own organisms for "${step.query}"._`,
+        sources: [],
+      };
+    }
+    const hitList = hits.map((h, i) =>
+      `${i + 1}. **${h.title || h.key}** — ${h.snippet || ''} _(${h.key})_`).join('\n');
+    const system = 'You assess a user\'s OWN existing notes/documents against a note they just captured. ' +
+      'Summarise what they already have that is relevant, what is missing, and how the existing material relates. ' +
+      'Output clean markdown only — no preamble, no invented facts beyond what is listed.';
+    const prompt = `The captured note:\n\n"""\n${noteText}\n"""\n\nRelevant existing material from the user's own organisms:\n\n${hitList}\n\nWrite a short assessment.`;
+    const { content } = await aiComplete(prompt, system);
+    return {
+      stepId: step.id, kind: step.kind, producedAt: retrievedAt,
+      markdown: (content || '').trim(),
+      sources: hits.map(h => ({
+        producer: h.producer || null,
+        origin: h.key,
+        label: h.title || h.key,
+        retrievedAt,
+      })),
+    };
+  }
+
+  if (step.kind === 'delegate') {
+    const feed = ctx?.offersFeed || await offers.listOffers();
+    const agents = feed?.data?.agents || feed?.agents || [];
+    let agentEntry = agents.find(a => a.agent === step.agent);
+    let offer = agentEntry?.offers?.find(o => o.id === step.offerId);
+    // Fallback: the planner's pick is gone/renamed — rank the live catalogue against the request.
+    if (!offer) {
+      const items = agents.flatMap(a => (a.offers || []).map(o => ({ agent: a.agent, offer: o })));
+      const { ranked } = await offers.rankOffersByNeed(step.query, items).catch(() => ({ ranked: [] }));
+      const top = ranked?.[0]?.item;
+      if (top) { agentEntry = agents.find(a => a.agent === top.agent); offer = top.offer; }
+    }
+    if (!agentEntry || !offer) throw new Error('No matching agent offer for this step');
+
+    ctx?.onStatus?.(step.id, 'dispatching');
+    const dispatch = await offers.ask(agentEntry, offer, step.query);
+    if (dispatch.kind !== 'task' || !dispatch.taskId) {
+      // Interactive/schedule-only agents can't be auto-awaited from here.
+      throw new Error(dispatch.kind === 'prompt' ? 'This agent is interactive — ask it from the Offerings tab' : 'Could not dispatch a task to this agent');
+    }
+    const task = await awaitTask(agentEntry.agent, dispatch.taskId, { onStatus: (s) => ctx?.onStatus?.(step.id, s) });
+    const content = await offers.getDeliverableContent({
+      agentGaii: agentEntry.gaii,
+      deliverableKey: task?.deliverableKey || task?.deliverable_key,
+      taskId: dispatch.taskId,
+    });
+    return {
+      stepId: step.id, kind: step.kind, producedAt: retrievedAt,
+      markdown: (content || '_The agent completed the task but returned no readable deliverable._').trim(),
+      sources: [{
+        producer: agentEntry.gaii,
+        origin: task?.deliverableKey || task?.deliverable_key || ('task:' + dispatch.taskId),
+        label: `${offer.title} (${agentEntry.agent})`,
+        retrievedAt,
+      }],
+    };
+  }
+
+  // llm_reason — expand using only the note + prior step results.
+  const system = 'You enrich a user\'s rough note by reasoning about it. Follow the instruction exactly. ' +
+    'Output clean markdown only — no preamble. Do not invent external facts; reason from what is given.';
+  const prompt = `The captured note:\n\n"""\n${noteText}\n"""${priorBlock(prior)}\n\nInstruction: ${step.query}`;
+  const { content, model } = await aiComplete(prompt, system);
+  return {
+    stepId: step.id, kind: step.kind, producedAt: retrievedAt,
+    markdown: (content || '').trim(),
+    sources: [{ producer: model || 'ai', origin: null, label: 'AI reasoning', retrievedAt }],
+  };
+}
+
+/** Compose the enriched note body: original note + each enrichment + a Sources/References section.
+ *  This is what gets filed (classify/materialize) once the user is happy. */
+export function composeEnrichedMarkdown(noteText, enrichments) {
+  if (!enrichments?.length) return noteText;
+  const parts = [noteText.trim()];
+  const allSources = [];
+  for (const e of enrichments) {
+    if (!e?.markdown) continue;
+    parts.push('', '---', '', e.markdown.trim());
+    for (const s of (e.sources || [])) allSources.push(s);
+  }
+  if (allSources.length) {
+    const seen = new Set();
+    const lines = [];
+    for (const s of allSources) {
+      const key = `${s.label}|${s.origin || ''}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      const where = s.origin ? ` — \`${s.origin}\`` : '';
+      const who = s.producer ? ` _(${String(s.producer).split('@')[0]})_` : '';
+      lines.push(`- ${s.label}${where}${who}`);
+    }
+    if (lines.length) parts.push('', '## Sources / References', '', ...lines);
+  }
+  return parts.join('\n');
+}

package/dist/public/js/services/notebook.js

@@ -8,9 +8,16 @@
  *   note as a workspace DOCUMENT.
  * @structure
  *   - classifyNote(text) — POST /v1/librarian/classify
+ *   - distributeNote(text) — POST /v1/librarian/distribute (split into placed chunks)
  *   - materializeDocument(plan) — resolve/create org → ws → document space → write doc → drop source
+ *   - distributeChunks(chunks, sourceKey, onProgress) — materialize each chunk to its home
+ *   - getNotebookSettings/saveNotebookSettings — the per-owner trust toggles (notebook.settings)
  * @version-history
  *   v1.0.0 — 2026-06-19 — Initial: classify + materialize-document orchestration (slice B).
+ *   v1.1.0 — 2026-06-21 — Phase 3: distribute (split → many homes) + notebook.settings trust toggles.
+ *   v1.2.0 — 2026-06-21 — (reverted) materializeRecord/patchRecord removed — the Tracked Response flow
+ *     now writes records through the proper workspace draft→publish path (services/organisms.js), not a
+ *     raw memory write, so records land in the right namespace/owner and show up with activity.
  */
 import { api, apiPost } from '/js/api.js';
 import { createMemory, getMemory, deleteMemory } from '/js/services/memory.js';
@@ -37,6 +44,50 @@ export async function classifyNote(text) {
   return resp?.data || null;
 }
 
+/** Ask the backend to SPLIT a note into placed chunks (notebook stage 3). Slow AI call — full timeout,
+ *  no retry (same reasoning as classifyNote). Returns the DistributeResult envelope's data. */
+export async function distributeNote(text) {
+  const resp = await api('/v1/librarian/distribute', {
+    method: 'POST',
+    body: JSON.stringify({ text }),
+    timeoutMs: 1_800_000,
+    retries: 0,
+  });
+  if (resp?.ok === false) { const e = new Error(resp.error?.message || 'Distribute failed'); e.code = resp.error?.code; throw e; }
+  return resp?.data || null;
+}
+
+/**
+ * Park an inbox message into the notebook for later processing, preserving the link back to the
+ * original message and the "owes a reply" intent (so when the note is later turned into a tracked
+ * response, the binding re-attaches to the source message). Stored as a normal notebook inbox entry.
+ * @param {object} msg  The inbox message ({ id, body, conversationId, direction, senderGhii, recipientGhii }).
+ * @param {{ title?: string, content?: string, mode?: 'auto'|'approve' }} [opts]
+ */
+export async function parkMessageToNotebook(msg, opts = {}) {
+  const key = 'notebook.inbox.' + Date.now();
+  const peerGhii = msg?.direction === 'outbound' ? (msg?.recipientGhii || '') : (msg?.senderGhii || '');
+  const value = {
+    text: (opts.content && opts.content.trim()) || msg?.body || '',
+    title: opts.title || '',
+    capturedAt: new Date().toISOString(),
+    source: { kind: 'message', messageId: msg?.id, conversationId: msg?.conversationId, peerGhii, originNodeId: (peerGhii.split('@')[1] || '') },
+    trackedResponseIntent: { owes: true, mode: opts.mode || 'approve' },
+  };
+  const resp = await createMemory(key, value, 'private');
+  if (resp?.ok === false) throw new Error(resp.error?.message || 'Could not park to notebook');
+  return { key };
+}
+
+/** The per-owner notebook trust toggles ({ autoDetectIntent, autoRunPlan, autoDistribute }). */
+export async function getNotebookSettings() {
+  try { const r = await getMemory('notebook.settings'); return (r?.data?.value) || {}; }
+  catch { return {}; }
+}
+export async function saveNotebookSettings(settings) {
+  return createMemory('notebook.settings', settings, 'private');
+}
+
 /** A document-space objectType for a memory-backed workspace. */
 function docSpaceObjectType() {
   return { name: 'Pages', namespace: DOC_SPACE, schemaRef: 'schema:document@1', mode: 'document', backing: 'memory', writeRole: 'member', cardinality: 'many', versioned: true };
@@ -122,3 +173,49 @@ export async function materializeDocument(plan) {
 
   return { organismId, workspaceId, space, docId };
 }
+
+/**
+ * Materialize each chunk of a distribute plan into its own home. Chunks with a resolved home go there;
+ * chunks the model proposed a NEW name for create that org/workspace; chunks with neither are grouped
+ * into a single shared "Notebook" organism (created once, reused) so unplaced pieces are never lost.
+ * The source inbox note is dropped ONLY after every chunk has been filed.
+ * @param {Array} chunks  DistributeChunk[] from distributeNote().
+ * @param {string} [sourceKey]  Inbox note key to delete once all chunks are filed.
+ * @param {(index:number, status:'running'|'done'|'failed', result?:object)=>void} [onProgress]
+ * @returns {Promise<Array>} per-chunk materialize results
+ */
+export async function distributeChunks(chunks, sourceKey, onProgress) {
+  const results = [];
+  let notebookFallback = null;   // { organismId, workspaceId, space } for unplaced chunks
+  for (let i = 0; i < chunks.length; i++) {
+    const c = chunks[i];
+    onProgress?.(i, 'running');
+    const organismName = c.createNew?.organismName || c.organismName;
+    const plan = {
+      organismId: c.organismId || null,
+      organismName,
+      workspaceId: c.workspaceId || null,
+      workspaceName: c.createNew?.workspaceName || c.workspaceName,
+      space: c.space || null,
+      title: c.title,
+      markdown: c.markdown,
+    };
+    const unplaced = !plan.organismId && !organismName;
+    if (unplaced && notebookFallback) {
+      plan.organismId = notebookFallback.organismId;
+      plan.workspaceId = notebookFallback.workspaceId;
+      plan.space = notebookFallback.space;
+    }
+    try {
+      const res = await materializeDocument(plan);   // no sourceKey — don't delete per chunk
+      if (unplaced && !notebookFallback) notebookFallback = { organismId: res.organismId, workspaceId: res.workspaceId, space: res.space };
+      results.push(res);
+      onProgress?.(i, 'done', res);
+    } catch (e) {
+      onProgress?.(i, 'failed');
+      throw e;   // surface the failure; source note is NOT deleted so nothing is lost
+    }
+  }
+  if (sourceKey) await deleteMemory(sourceKey).catch(() => {});
+  return results;
+}

package/dist/public/js/services/organisms.js

@@ -6,6 +6,9 @@
  *   resolve gate approvals.
  * @usage import * as orgService from '/js/services/organisms.js';
  * @version-history
+ *   v1.2.1 — 2026-06-21 — Decode HTML entities in workspace names on read (listWorkspaces +
+ *     discoverWorkspaces) so legacy double-escaped registry names (e.g. "STT & Voice") render
+ *     as plain text in the list + breadcrumb.
  *   v1.2.0 — 2026-06-16 — Generator prompt: each objectType gets a one-line "description" and a
  *     matching "type.<name>.desc" i18n key, so generated workspaces are self-describing (the
  *     workspace UI shows the description under each space's title).
@@ -15,6 +18,7 @@
  *     "{ns}.{field}.hint" and "type.{name}" labels the workspace UI renders.
  */
 import { api, apiGet, apiPost, apiPut, apiPatch, apiDelete } from '/js/api.js';
+import { decodeEntities } from '/js/utils.js';
 
 /** Does this space's data live in workspace memory keys (records/documents the workspace view can
  *  show)? Missing backing counts as memory. Mirrors the server's isMemoryBackedSpace — THE one
@@ -514,6 +518,37 @@ export async function getWorkspaceOverview(orgId, wsId) {
   } catch { return ''; }
 }
 
+/** Deterministic GRAPH of the whole organism (workspaces → spaces + counts/last-activity, members,
+ *  agents) — the data behind the interactive mindmap. Returns null on failure. */
+export async function getOrganismGraph(orgId) {
+  try {
+    const r = await apiGet(`/v1/organisms/${encodeURIComponent(orgId)}/graph`);
+    return r?.data?.graph || null;
+  } catch { return null; }
+}
+
+/** Deterministic GRAPH of ONE workspace (root = workspace, with its spaces). Returns null on failure. */
+export async function getWorkspaceGraph(orgId, wsId) {
+  try {
+    const r = await apiGet(`/v1/organisms/${encodeURIComponent(orgId)}/workspace/graph?ws=${encodeURIComponent(wsId)}`);
+    return r?.data?.graph || null;
+  } catch { return null; }
+}
+
+/** Organism STRUCTURE TIMELINE: { current, history } — the trackable structure fingerprint's current
+ *  value + archived prior versions (newest first). Returns { current: null, history: [] } on failure. */
+export async function getStructureHistory(orgId) {
+  try {
+    const r = await apiGet(`/v1/organisms/${encodeURIComponent(orgId)}/structure/history`);
+    return r?.data || { current: null, history: [] };
+  } catch { return { current: null, history: [] }; }
+}
+
+/** Save a workspace's free-form README (markdown). Creator/admin only (enforced server-side). */
+export async function saveWorkspaceReadme(orgId, wsId, readme) {
+  return apiPut(`/v1/organisms/${encodeURIComponent(orgId)}/workspace?ws=${encodeURIComponent(wsId)}`, { ws: wsId, readme });
+}
+
 /** Overwrite a workspace's manifest (e.g. edited name/summary/policy from Settings). */
 export async function saveManifest(orgId, wsId, manifest) {
   return apiPost('/v1/memory', { key: `${wsRoot(orgId, wsId)}.meta.manifest`, value: manifest, visibility: 'private' });
@@ -529,7 +564,9 @@ export async function listWorkspaces(orgId) {
   try {
     const resp = await apiGet(`/v1/memory?prefix=${encodeURIComponent(key)}`);
     const item = (resp?.data?.items || []).find(i => i.key === key);
-    return Array.isArray(item?.value?.workspaces) ? item.value.workspaces : [];
+    const list = Array.isArray(item?.value?.workspaces) ? item.value.workspaces : [];
+    // Names are plain text; legacy import paths stored them HTML-escaped. Decode for display.
+    return list.map(w => (w && w.name ? { ...w, name: decodeEntities(w.name) } : w));
   } catch { return []; }
 }
 
@@ -546,7 +583,9 @@ export async function saveWorkspaceRegistry(orgId, workspaces) {
 export async function discoverWorkspaces(orgId) {
   try {
     const resp = await apiGet(`/v1/organisms/${encodeURIComponent(orgId)}/workspaces`);
-    return Array.isArray(resp?.data?.workspaces) ? resp.data.workspaces : [];
+    const list = Array.isArray(resp?.data?.workspaces) ? resp.data.workspaces : [];
+    // Names are plain text; legacy import paths stored them HTML-escaped. Decode for display.
+    return list.map(w => (w && w.name ? { ...w, name: decodeEntities(w.name) } : w));
   } catch { return []; }
 }
 

package/dist/public/js/services/tracked-responses.js

@@ -0,0 +1,103 @@
+/**
+ * @file tracked-responses.js
+ * @description Frontend service for Tracked Responses — the Memory Contract that owes a (possibly
+ *   federated) reply to an inbox message once a watched workspace record satisfies a condition.
+ *   Thin wrappers over /v1/tracked-responses; plus message-importance flags stored as owner memory
+ *   (no schema migration) for the lightweight "Important / needs reply" tier.
+ * @structure create / list / get / getDraft / evaluate / markReplied / cancel + importance flags
+ * @usage import * as tracked from '/js/services/tracked-responses.js';
+ * @version-history
+ *   v1.0.0 — 2026-06-21 — Initial service (Tracked Responses + importance flags).
+ */
+import { api, apiGet } from '/js/api.js';
+import { createMemory, getMemory, deleteMemory } from '/js/services/memory.js';
+
+const enc = encodeURIComponent;
+const FLAG_PREFIX = 'message-flag.';
+const flagKey = (messageId) => `${FLAG_PREFIX}${messageId}.latest`;
+
+/** Create a Tracked Response from an inbox message. `watch` = { key, condition:{field,equals} }. */
+export async function createTrackedResponse({ messageId, watch, response, references, title, tier } = /** @type {{ messageId?: any, watch?: any, response?: any, references?: any, title?: any, tier?: any }} */ ({})) {
+  const resp = await api('/v1/tracked-responses', {
+    method: 'POST',
+    body: JSON.stringify({ message_id: messageId, watch, response, references, title, tier }),
+  });
+  if (resp?.ok === false) throw new Error(resp.error?.message || 'Could not create tracked response');
+  return resp?.data?.trackedResponse || null;
+}
+
+/** AI triage: form the intent for a message as an actionable record (organism/workspace + record TYPE
+ *  + title/content + completion condition). Slow AI call — full timeout, no retry. Returns
+ *  { suggestion, context:{organisms:[{id,name,workspaces:[{id,name,recordTypes:[{namespace,name}]}]}]} }. */
+export async function triageMessage(text) {
+  const resp = await api('/v1/tracked-responses/classify', { method: 'POST', body: JSON.stringify({ text }), timeoutMs: 1_800_000, retries: 0 });
+  if (resp?.ok === false) { const e = new Error(resp.error?.message || 'Triage failed'); e.code = resp.error?.code; throw e; }
+  return resp?.data || null;
+}
+
+/** AI fill: produce a record value conforming to the chosen record type's ACTUAL schema (any shape,
+ *  AI-authored per workspace) + the schema-correct completion condition + inject field. Validated
+ *  server-side before returning. Slow AI call. Returns { value, condition, inject }. */
+export async function fillRecord({ organismId, ws, namespace, recordId, message, title, content } = /** @type {{ organismId?: any, ws?: any, namespace?: any, recordId?: any, message?: any, title?: any, content?: any }} */ ({})) {
+  const resp = await api('/v1/tracked-responses/fill', {
+    method: 'POST',
+    body: JSON.stringify({ organism_id: organismId, ws, namespace, record_id: recordId, message, title, content }),
+    timeoutMs: 1_800_000, retries: 0,
+  });
+  if (resp?.ok === false) { const e = new Error(resp.error?.message || 'Fill failed'); e.code = resp.error?.code; throw e; }
+  return resp?.data || null;
+}
+
+export async function listTrackedResponses(state) {
+  const r = await apiGet(`/v1/tracked-responses${state ? `?state=${enc(state)}` : ''}`);
+  return r?.data?.trackedResponses || [];
+}
+
+export async function getTrackedResponse(id) {
+  const r = await apiGet(`/v1/tracked-responses/${enc(id)}`);
+  return r?.data?.trackedResponse || null;
+}
+
+/** The suggested reply built when an approve-mode contract fired ({ draft:{body,result}, source, state }). */
+export async function getTrackedResponseDraft(id) {
+  const r = await apiGet(`/v1/tracked-responses/${enc(id)}/draft`);
+  return r?.data || null;
+}
+
+export async function evaluateTrackedResponse(id) {
+  const r = await api(`/v1/tracked-responses/${enc(id)}/evaluate`, { method: 'POST' });
+  return r?.data?.trackedResponse || null;
+}
+
+export async function markTrackedResponseReplied(id, sentMessageId) {
+  return api(`/v1/tracked-responses/${enc(id)}/replied`, { method: 'POST', body: JSON.stringify({ sent_message_id: sentMessageId }) });
+}
+
+export async function cancelTrackedResponse(id) {
+  return api(`/v1/tracked-responses/${enc(id)}/cancel`, { method: 'POST' });
+}
+
+// ── Lightweight "Important / needs reply" flag (Tier 1) — owner memory, no schema migration ──
+export async function setMessageImportant(messageId, important) {
+  if (important) return createMemory(flagKey(messageId), { important: true, at: new Date().toISOString() }, 'private');
+  return deleteMemory(flagKey(messageId)).catch(() => {});
+}
+
+export async function isMessageImportant(messageId) {
+  try { const r = await getMemory(flagKey(messageId)); return !!(r?.data?.value?.important); }
+  catch { return false; }
+}
+
+/** Return the set of message ids the owner flagged important (for the "Needs reply" filter). Uses a
+ *  PREFIX query so it fetches only the tiny `message-flag.*` set — never the whole memory store. A flag
+ *  record exists ONLY while important (un-flag deletes it), so key-presence is sufficient. */
+export async function listImportantMessageIds() {
+  try {
+    const r = await apiGet(`/v1/memory?prefix=${enc(FLAG_PREFIX)}`);
+    const items = r?.data?.items || [];
+    return items
+      .map(m => String(m.key || ''))
+      .filter(k => k.startsWith(FLAG_PREFIX))
+      .map(k => k.slice(FLAG_PREFIX.length).replace(/\.latest$/, ''));
+  } catch { return []; }
+}

package/dist/public/js/utils.js

@@ -13,6 +13,21 @@ export function escHtml(s) {
     .replace(/"/g, '"');
 }
 
+/** Decode the common HTML entities back to plain text. Some names (e.g. workspace registry names)
+ *  were HTML-escaped at write by older import paths, so a literal "STT & Voice" reached storage as
+ *  "STT & Voice" and then double-escaped on render. Names are plain text — decode them for
+ *  display. HTM re-escapes on render, so this stays XSS-safe. Decode & LAST so "<"
+ *  resolves to "&lt;", not "<". */
+export function decodeEntities(s) {
+  if (!s) return '';
+  return String(s)
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&amp;/g, '&');
+}
+
 /** Attribute-escape a string (for use inside HTML attributes). */
 export function escAttr(s) {
   if (!s) return '';