synabun 2.0.10 → 2.1.0

package/mcp-server/src/tools/tool-groups.ts

@@ -0,0 +1,164 @@
+import { z } from 'zod/v3';
+import { text } from './response.js';
+import { isBrowserV2Enabled, reportRuntimeTools, type RuntimeToolsReport } from '../services/neural-interface.js';
+import { ALWAYS_ON_TOOLS, GATED_GROUP_IDS, TOOL_GROUPS, sortGroups, toolsOfGroup } from '../services/tool-catalog.js';
+import { resolveToolList, type AddedGroup } from '../services/tool-list.js';
+import { legacyProfileValue, persistRuntimeTools, runtimeToolsWithExternalRefs, type ToolApplyResult, type ToolRuntime } from '../services/tool-runtime.js';
+
+export const toolGroupsSchema = {
+  action: z.enum(['get', 'add', 'set']).describe(
+    'get = this runtime\'s groups, what they do on this host, and the catalog. add = load more groups for this runtime. set = replace this runtime\'s groups.'
+  ),
+  groups: z.array(z.string().min(1).max(72)).max(32).optional().describe(
+    'Group ids for add and set, from the catalog that get returns, e.g. ["gsc"] or ["browser_whatsapp"]; "all" is every group. The memory tools, loop, tool_groups and choice are always there; agents, skills and computer follow your role and grants.'
+  ),
+};
+
+export const toolGroupsDescription =
+  'Always-available router for SynaBun\'s tool groups. When a task needs a SynaBun tool this runtime does not list, call action="get", then action="add" with the group that has it, and continue once the host refreshes its tools. On Codex and Claude Code every SynaBun tool is already reachable on demand, so there it only moves the focus and needs no reload. Do not report a SynaBun capability unavailable before trying this. A change affects only this runtime, never other sessions or the default for new ones.';
+
+export interface RuntimeToolsChange {
+  result: ToolApplyResult;
+  persisted: string | null;
+  report: RuntimeToolsReport;
+  hostRefresh: 'scheduled' | 'notification' | 'unavailable' | 'not-needed';
+  toolListNotification: 'scheduled' | 'unavailable' | 'not-needed';
+}
+
+/**
+ * Change this runtime's groups: apply them (a list that could not be read is fixed by this, and the runtime
+ * returns to its host's mode), save them for a restarted child of the same runtime, tell the Neural Interface,
+ * and refresh the host. Never the default for new runtimes.
+ */
+export async function changeRuntimeTools(runtime: ToolRuntime, groups: readonly string[], added: AddedGroup[]): Promise<RuntimeToolsChange> {
+  const result = runtime.apply({ groups: [...groups], added, listError: null, mode: runtime.getHostMode(), source: 'tool_groups' });
+  const persisted = persistRuntimeTools(result.groups);
+  const inBand = result.mode === 'strict' && runtime.hasInBandRefresh();
+  const report = await reportRuntimeTools(runtimeToolsWithExternalRefs(result.groups), { mode: result.mode, legacyProfile: legacyProfileValue(result.groups), ...(inBand ? { refresh: 'in-band' as const } : {}) });
+  if (result.mode === 'strict') {
+    if (inBand) {
+      // OpenCode supports list_changed, but snapshots its registry on each step. A delayed
+      // notification/reconnect lets the next step capture stale tools. Keep the current HTTP
+      // call alive while the host fetches the new schemas and its registry debounce settles.
+      const refreshed = await runtime.refreshBeforeReply();
+      return { result, persisted, report, toolListNotification: refreshed ? 'scheduled' : 'unavailable', hostRefresh: refreshed ? 'notification' : 'unavailable' };
+    }
+    // Always queue one notification, after this answer: a managed host may also reconnect, and repeating the same
+    // groups is how a host whose tool list went stale is repaired, so it must not be a silent no-op.
+    const scheduled = runtime.scheduleToolsChangedNotification();
+    return {
+      result, persisted, report,
+      toolListNotification: scheduled ? 'scheduled' : 'unavailable',
+      hostRefresh: report.hostRefresh === 'scheduled' ? 'scheduled' : scheduled ? 'notification' : 'unavailable',
+    };
+  }
+  // A focus host already has every tool; only one coming back from an unreadable list changes what it advertises.
+  if (!result.advertisedChanged) return { result, persisted, report, toolListNotification: 'not-needed', hostRefresh: 'not-needed' };
+  const scheduled = runtime.scheduleToolsChangedNotification();
+  return { result, persisted, report, toolListNotification: scheduled ? 'scheduled' : 'unavailable', hostRefresh: scheduled ? 'notification' : 'unavailable' };
+}
+
+/** The outcome as both tool answers report it. */
+export function runtimeChangeFields(change: RuntimeToolsChange) {
+  const { result, report } = change;
+  return {
+    changed: result.changed,
+    enabled: result.enabled,
+    disabled: result.disabled,
+    totalTools: result.totalTools,
+    scope: 'current-runtime' as const,
+    runtimeStatePersisted: !!change.persisted,
+    runtimeStateReported: report.reported,
+    hostRefresh: change.hostRefresh,
+    toolListNotification: change.toolListNotification,
+    ...(report.runtimeKind ? { runtimeKind: report.runtimeKind } : {}),
+    ...(report.correlationId ? { refreshCorrelationId: report.correlationId } : {}),
+    ...(report.error ? { refreshReportError: report.error } : {}),
+  };
+}
+
+function changeNote(change: RuntimeToolsChange): string {
+  const groups = change.result.groups.join(', ') || 'memory tools only';
+  if (change.result.mode === 'focus') {
+    return change.result.advertisedChanged
+      ? 'Every SynaBun tool is back; continue once the host refreshes its tool list.'
+      : `Every SynaBun tool was already available; no reload needed. This runtime's focus is now: ${groups}.`;
+  }
+  if (change.hostRefresh === 'unavailable') {
+    return `The groups changed here, but the host refresh could not be scheduled. Retry tool_groups; if the tools still do not appear, finish with "needs SynaBun tools: ${change.result.groups.join(', ')}".`;
+  }
+  return 'Loaded; continue after the refresh.';
+}
+
+/** Keep what the runtime added before for the groups it still has, then what this change added. */
+function mergeAdded(previous: readonly AddedGroup[], next: readonly AddedGroup[], groups: readonly string[]): AddedGroup[] {
+  const merged = new Map<string, AddedGroup>();
+  for (const entry of [...previous, ...next]) if (groups.includes(entry.id) && !merged.has(entry.id)) merged.set(entry.id, entry);
+  return [...merged.values()];
+}
+
+export function toolGroupsView(runtime: ToolRuntime) {
+  const browserV2 = isBrowserV2Enabled();
+  const active = runtime.getActiveGroups();
+  const mode = runtime.getMode();
+  const listError = runtime.getListError();
+  return {
+    groups: runtime.getGroups(),
+    effect: mode,
+    source: runtime.getSource(),
+    added: runtime.getAdded(),
+    listError,
+    role: runtime.getRole(),
+    gated: Object.fromEntries(GATED_GROUP_IDS.map((id) => [id, active.has(id)])),
+    alwaysOn: [...ALWAYS_ON_TOOLS],
+    totalTools: runtime.getAdvertisedToolCount(),
+    catalog: TOOL_GROUPS.filter((group) => !group.gate).map((group) => ({
+      id: group.id,
+      label: group.label,
+      purpose: group.purpose,
+      count: toolsOfGroup(group.id, { browserV2 }).length,
+      active: active.has(group.id),
+    })),
+    note: listError
+      ? mode === 'strict'
+        ? `This runtime could not read its tool list (${listError}), so it has memory tools only: set or add the groups it needs.`
+        : `This runtime could not read its tool list (${listError}); every SynaBun tool is still reachable on demand. Set or add groups to give it a focus.`
+      : mode === 'focus'
+        ? 'This host reaches every SynaBun tool on demand; these groups are its focus, and add or set only moves it.'
+        : 'This host has exactly these groups and the always-on tools; add a group to load it.',
+  };
+}
+
+export async function handleToolGroups(runtime: ToolRuntime, args: { action: string; groups?: string[] }) {
+  if (args.action === 'get') return text(JSON.stringify(toolGroupsView(runtime), null, 2));
+
+  if (args.action === 'add' || args.action === 'set') {
+    if (!Array.isArray(args.groups)) {
+      return text(`Error: "groups" is required for action "${args.action}". Call action="get" for the catalog.`);
+    }
+    if (args.groups.some(item => item.startsWith('mcp:'))) return text(JSON.stringify({ ok: false, code: 'TOOLS_INVALID', message: 'External MCP servers are fixed for this run; dispatch again with those refs in tools.' }));
+    const resolved = resolveToolList(args.groups, { source: 'runtime' });
+    if (!resolved.ok) {
+      return text(JSON.stringify({
+        ok: false,
+        code: resolved.code,
+        problems: resolved.problems,
+        message: `${resolved.message}. Call tool_groups action="get" for the catalog.`,
+      }, null, 2));
+    }
+    const groups = args.action === 'add' ? sortGroups([...runtime.getGroups(), ...resolved.groups]) : resolved.groups;
+    const added = args.action === 'add' ? mergeAdded(runtime.getAdded(), resolved.added, groups) : resolved.added;
+    const change = await changeRuntimeTools(runtime, groups, added);
+    return text(JSON.stringify({
+      ok: true,
+      action: args.action,
+      groups: change.result.groups,
+      added: change.result.added,
+      effect: change.result.mode,
+      ...runtimeChangeFields(change),
+      note: changeNote(change),
+    }, null, 2));
+  }
+
+  return text(`Unknown action "${args.action}". Use "get", "add" or "set".`);
+}

package/mcp-server/src/tools/whiteboard-format.ts

@@ -10,6 +10,9 @@ import {
   elementBox,
   resolveArrowPoints,
   formatBox,
+  hasNestedLevels,
+  listMarkers,
+  normalizeListItems,
   type WbAnalysis,
   type WbElement,
   type WbPoint,
@@ -150,10 +153,13 @@ export function formatElement(el: WbElement, byId: Map<string, WbElement>, opts:
       break;
     }
     case 'list': {
-      const items = Array.isArray(el.items) ? el.items : [];
-      lines.push(`[${el.id}] LIST ${formatBox(box, est)}${z}${rot} ${el.fontSize || 18}px ${el.ordered ? 'numbered' : 'bulleted'} ${plural(items.length, 'item')}${color}`);
+      // Nested items are indented two spaces per level, with their level's bullet / numbering.
+      const { items, levels } = normalizeListItems(el.items, el.levels);
+      const markers = listMarkers(levels, !!el.ordered);
+      const nested = hasNestedLevels(levels) ? `, nested ${Math.max(...levels) + 1} levels` : '';
+      lines.push(`[${el.id}] LIST ${formatBox(box, est)}${z}${rot} ${el.fontSize || 18}px ${el.ordered ? 'numbered' : 'bulleted'} ${plural(items.length, 'item')}${nested}${color}`);
       const shown = opts.verbose ? items : items.slice(0, LIST_PREVIEW_ITEMS);
-      shown.forEach((item, i) => lines.push(`    ${el.ordered ? `${i + 1}.` : '•'} ${item}`));
+      shown.forEach((item, i) => lines.push(`    ${'  '.repeat(levels[i])}${markers[i]} ${item}`));
       if (shown.length < items.length) lines.push(`    … +${items.length - shown.length} more`);
       if (!items.length) lines.push('    (empty)');
       break;

package/mcp-server/src/tools/whiteboard-tools.ts

@@ -1,7 +1,17 @@
 import { z } from 'zod/v3';
 import * as ni from '../services/neural-interface.js';
 import { text, image } from './response.js';
-import { SHAPE_TYPES, SECTION_TYPE_NAMES, ELEMENT_TYPES, DEFAULT_VIEWPORT, type WbElement, type WbViewport } from '../services/whiteboard-geometry.js';
+import {
+  SHAPE_TYPES,
+  SECTION_TYPE_NAMES,
+  ELEMENT_TYPES,
+  DEFAULT_VIEWPORT,
+  LIST_MAX_LEVEL,
+  hasNestedLevels,
+  normalizeListItems,
+  type WbElement,
+  type WbViewport,
+} from '../services/whiteboard-geometry.js';
 import {
   formatReadText,
   formatReadJson,
@@ -28,6 +38,29 @@ const coordModeSchema = z.enum(['px', 'pct']).optional().describe(
 
 const COLOR_HELP = 'CSS color. Default rgba(255,255,255,0.85). Palette: #ef4444 red, #f97316 orange, #eab308 yellow, #22c55e green, #3b82f6 blue, #a855f7 purple, #ec4899 pink, #06b6d4 cyan';
 
+// One list bullet: a plain string (top level, as always) or { text, level } for a nested one.
+const listItemSchema = z.union([
+  z.string(),
+  z.object({
+    text: z.string(),
+    level: z.number().int().min(0).max(LIST_MAX_LEVEL).optional().describe(`Nesting level, 0 = top (default). At most one deeper than the item above (deeper is lowered); the first item is always 0. Max ${LIST_MAX_LEVEL}.`),
+  }),
+]);
+const LIST_ITEMS_HELP = `One entry per bullet: a string (top level) or {text, level} for a nested bullet (level 0-${LIST_MAX_LEVEL}; sub-items of the item above). Nested levels are indented with their own bullet / numbering style.`;
+
+/**
+ * List items as the store keeps them: `items` strings, plus `levels` only when something is nested. A caller
+ * that sends plain strings sends exactly what it always did (an older server never sees an object).
+ */
+function storedListFields(fields: Record<string, unknown>): Record<string, unknown> {
+  if (!Array.isArray(fields.items)) return fields;
+  const { items, levels } = normalizeListItems(fields.items);
+  const out: Record<string, unknown> = { ...fields, items };
+  if (hasNestedLevels(levels)) out.levels = levels;
+  else delete out.levels;
+  return out;
+}
+
 /** After a mutation, re-read the board (no image payloads) for scoped warnings. */
 async function warningsFor(ids: string[]): Promise<string[]> {
   if (!ids.length) return [];
@@ -85,7 +118,7 @@ const addElementSchema = z.object({
   width: z.number().optional().describe('Width (shape/image/section). Ignored for text/list — they auto-size.'),
   height: z.number().optional().describe('Height (shape/image/section). Ignored for text/list.'),
   content: z.string().optional().describe('Text content (text). \\n = line break. Text does not wrap: long single lines get wide.'),
-  items: z.array(z.string()).optional().describe('List items (list). One string per bullet.'),
+  items: z.array(listItemSchema).optional().describe(`List items (list). ${LIST_ITEMS_HELP}`),
   ordered: z.boolean().optional().describe('Numbered list instead of bullets (list). Default false.'),
   fontSize: z.number().optional().describe('Font size px. Defaults: text 22, list 18.'),
   color: z.string().optional().describe(COLOR_HELP),
@@ -117,7 +150,8 @@ export const whiteboardAddDescription =
   + 'Guidance: keep content within ~70-80% of the usable width, centered, fit vertically, ~20px margins.';
 
 export async function handleWhiteboardAdd(args: { elements: Record<string, unknown>[]; coordMode?: string; layout?: string }) {
-  const result = await ni.addWhiteboardElements(args.elements, args.coordMode, args.layout);
+  const elements = args.elements.map(el => (el && el.type === 'list' ? storedListFields(el) : el));
+  const result = await ni.addWhiteboardElements(elements, args.coordMode, args.layout);
   if (result.error) {
     const errors = Array.isArray(result.errors) ? (result.errors as { index: number; type?: string; error: string }[]) : [];
     const detail = errors.length ? '\n' + errors.map(e => `  #${e.index + 1} ${e.type || '?'} — ${e.error}`).join('\n') : '';
@@ -141,7 +175,7 @@ const updateFieldsSchema = z.object({
   width: z.number().optional().describe('Ignored for text/list (auto-sized).'),
   height: z.number().optional().describe('Ignored for text/list (auto-sized).'),
   content: z.string().optional().describe('New text content (text). \\n = line break.'),
-  items: z.array(z.string()).optional().describe('New list items (list).'),
+  items: z.array(listItemSchema).optional().describe(`New list items (list); they replace all of them, levels included (plain strings make the list flat). ${LIST_ITEMS_HELP}`),
   ordered: z.boolean().optional(),
   fontSize: z.number().optional(),
   color: z.string().optional().describe(COLOR_HELP),
@@ -194,7 +228,7 @@ export async function handleWhiteboardUpdate(args: { id?: string; updates?: Reco
     return text('updates is empty — nothing to change.');
   }
 
-  const ops = items.map(it => ({ op: 'update', id: it.id, updates: it.updates, ...(it.parent ? { parent: it.parent } : {}) }));
+  const ops = items.map(it => ({ op: 'update', id: it.id, updates: storedListFields(it.updates || {}), ...(it.parent ? { parent: it.parent } : {}) }));
   const result = await ni.batchWhiteboardOps(ops, args.coordMode);
   if (result.error) {
     return text(`Failed to update: ${result.error}`);