deepseek-harness-intelligent-ui 0.2.2 → 0.2.4

package/src/catalog/patch.js

@@ -0,0 +1,283 @@
+/**
+ * Incremental updates of an existing `ui_render` UI (`ui_patch`).
+ *
+ * A UI is identified by `uiId` (the call id of the `ui_render` that created
+ * it) and versioned: the render is version 1 and every accepted patch adds
+ * one. Components keep their ids across versions, so the browser keeps the
+ * interaction state (sort, tab, form values, slider positions) of every
+ * component a patch did not replace.
+ *
+ * Nothing is stored on the Host: {@link collectUis} replays this session's own
+ * history (the messages the model sees), which makes the outcome deterministic
+ * across restarts and confines patches to UIs of the same conversation.
+ * @module deepseek-harness-intelligent-ui/catalog/patch
+ */
+import { LIMITS, validateTree } from './catalog.js';
+
+export const PATCH_OPS = Object.freeze(['setProps', 'replaceNode', 'insertChild', 'removeNode']);
+
+/** Upper bounds for one patch call. */
+export const PATCH_LIMITS = Object.freeze({ ops: 50, nodesPerOp: LIMITS.components });
+
+/** Allowed fields per op (besides `op`). */
+const OP_FIELDS = Object.freeze({
+  setProps: ['id', 'props', 'unset'],
+  replaceNode: ['id', 'node', 'nodes'],
+  insertChild: ['parent', 'id', 'index', 'nodes'],
+  removeNode: ['id'],
+});
+
+/**
+ * @typedef {{ id: string, type: string, props?: Record<string, unknown>, children?: string[] }} UiNode
+ * @typedef {{ uiId: string, version: number, title?: string, root: string, components: UiNode[] }} UiSnapshot
+ */
+
+function isPlainObject(v) {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+const clone = v => JSON.parse(JSON.stringify(v));
+
+/** Same leniency as validateTree: `props.children` becomes the node's children. */
+function normalize(node) {
+  if (isPlainObject(node.props) && 'children' in node.props) {
+    if (node.children === undefined && Array.isArray(node.props.children)) node.children = node.props.children;
+    delete node.props.children;
+  }
+  return node;
+}
+
+/**
+ * Normalize a validated `ui_render` payload into a snapshot.
+ * @param {string} uiId
+ * @param {any} args - `ui_render` arguments that passed {@link validateTree}.
+ * @returns {UiSnapshot}
+ */
+export function snapshotOf(uiId, args) {
+  const tree = clone(args);
+  const byId = new Map(tree.components.map(n => [n.id, normalize(n)]));
+  return {
+    uiId,
+    version: 1,
+    ...(typeof tree.title === 'string' && tree.title ? { title: tree.title } : {}),
+    root: tree.root,
+    components: reachable(tree.root, byId),
+  };
+}
+
+/** Components reachable from `root`, parents before children (renders progressively). */
+function reachable(root, byId) {
+  const out = [];
+  const seen = new Set();
+  const walk = (id) => {
+    const node = byId.get(id);
+    if (!node || seen.has(id)) return;
+    seen.add(id);
+    out.push(node);
+    for (const c of node.children ?? []) walk(c);
+  };
+  walk(root);
+  return out;
+}
+
+/**
+ * Check a new component definition (shape only; props are checked on the whole tree).
+ * @returns {string | undefined} a problem, or undefined.
+ */
+function checkNewNode(node, at) {
+  if (!isPlainObject(node)) return `${at}: expected a component object`;
+  if (typeof node.id !== 'string' || node.id === '') return `${at}.id: expected non-empty string`;
+  if (typeof node.type !== 'string') return `${at}(${node.id}).type: expected string`;
+  if (node.children !== undefined && (!Array.isArray(node.children) || node.children.some(c => typeof c !== 'string'))) {
+    return `${at}(${node.id}).children: expected array of component ids`;
+  }
+  const extra = Object.keys(node).find(k => !['id', 'type', 'props', 'children'].includes(k));
+  return extra ? `${at}(${node.id}).${extra}: unknown field` : undefined;
+}
+
+/**
+ * Apply one `ui_patch` call to the current snapshot. All-or-nothing: on any
+ * problem the snapshot is left untouched and the errors say what to fix.
+ * @param {UiSnapshot} ui - current version.
+ * @param {any} args - `ui_patch` arguments.
+ * @returns {{ ok: true, ui: UiSnapshot, changed: string[], warnings: string[] } | { ok: false, errors: string[], code: 'invalid' | 'stale' }}
+ */
+export function applyPatch(ui, args) {
+  const fail = (errors, code = 'invalid') => ({ ok: false, errors, code });
+  if (!isPlainObject(args)) return fail(['arguments: expected object']);
+  for (const key of Object.keys(args)) {
+    if (!['uiId', 'baseVersion', 'title', 'ops'].includes(key)) return fail([`${key}: unknown field`]);
+  }
+  if (!Number.isInteger(args.baseVersion)) return fail([`baseVersion: expected the integer version you are patching (current: ${ui.version})`]);
+  if (args.baseVersion !== ui.version) {
+    return fail([`baseVersion: UI ${JSON.stringify(ui.uiId)} is at version ${ui.version}, not ${args.baseVersion}; it changed since you read it. Re-derive the patch from version ${ui.version} and call ui_patch again with baseVersion ${ui.version}.`], 'stale');
+  }
+  if (args.title !== undefined && typeof args.title !== 'string') return fail(['title: expected string']);
+  if (!Array.isArray(args.ops) || args.ops.length === 0) return fail(['ops: expected a non-empty array']);
+  if (args.ops.length > PATCH_LIMITS.ops) return fail([`ops: more than ${PATCH_LIMITS.ops} operations; call ui_render with the complete UI instead`]);
+
+  const nodes = new Map(clone(ui.components).map(n => [n.id, n]));
+  const parentOf = new Map();
+  for (const n of nodes.values()) for (const c of n.children ?? []) parentOf.set(c, n.id);
+  const changed = new Set();
+  const added = new Set();
+
+  const addNodes = (list, at) => {
+    if (list === undefined) return undefined;
+    if (!Array.isArray(list)) return `${at}: expected array of new components`;
+    if (list.length > PATCH_LIMITS.nodesPerOp) return `${at}: more than ${PATCH_LIMITS.nodesPerOp} components`;
+    for (let j = 0; j < list.length; j++) {
+      const problem = checkNewNode(list[j], `${at}[${j}]`);
+      if (problem) return problem;
+      if (nodes.has(list[j].id)) return `${at}[${j}].id: ${JSON.stringify(list[j].id)} already exists; give new components new ids, or use setProps/replaceNode on the existing one`;
+      const node = normalize(clone(list[j]));
+      nodes.set(node.id, node);
+      added.add(node.id);
+      changed.add(node.id);
+    }
+    // New components may reference each other; their parents are wired by the tree check below.
+    for (const id of list.map(n => n.id)) for (const c of nodes.get(id).children ?? []) parentOf.set(c, id);
+    return undefined;
+  };
+  const existing = (id, at) => {
+    if (typeof id !== 'string' || id === '') return `${at}: expected a component id`;
+    if (!nodes.has(id)) return `${at}: unknown component id ${JSON.stringify(id)} in UI ${JSON.stringify(ui.uiId)} version ${ui.version}`;
+    return undefined;
+  };
+
+  for (let i = 0; i < args.ops.length; i++) {
+    const op = args.ops[i];
+    const at = `ops[${i}]`;
+    if (!isPlainObject(op)) return fail([`${at}: expected object`]);
+    if (!PATCH_OPS.includes(op.op)) return fail([`${at}.op: expected one of ${PATCH_OPS.join(' | ')}, got ${JSON.stringify(op.op)}`]);
+    const extra = Object.keys(op).find(k => k !== 'op' && !OP_FIELDS[op.op].includes(k));
+    if (extra) return fail([`${at}.${extra}: not a field of ${op.op} (allowed: ${OP_FIELDS[op.op].join(', ')})`]);
+    let problem;
+    switch (op.op) {
+      case 'setProps': {
+        problem = existing(op.id, `${at}.id`);
+        if (problem) break;
+        if (op.props === undefined && op.unset === undefined) { problem = `${at}: give props and/or unset`; break; }
+        if (op.props !== undefined && !isPlainObject(op.props)) { problem = `${at}.props: expected object`; break; }
+        if (op.props && 'children' in op.props) { problem = `${at}.props.children: children are not props; use insertChild/removeNode/replaceNode`; break; }
+        if (op.unset !== undefined && (!Array.isArray(op.unset) || op.unset.some(k => typeof k !== 'string'))) { problem = `${at}.unset: expected array of prop names`; break; }
+        const node = nodes.get(op.id);
+        const props = { ...(node.props ?? {}), ...clone(op.props ?? {}) };
+        for (const k of op.unset ?? []) delete props[k];
+        node.props = props;
+        changed.add(op.id);
+        break;
+      }
+      case 'replaceNode': {
+        problem = existing(op.id, `${at}.id`);
+        if (problem) break;
+        if (!isPlainObject(op.node)) { problem = `${at}.node: expected { type, props, children }`; break; }
+        if (op.node.id !== undefined && op.node.id !== op.id) { problem = `${at}.node.id: must equal ${JSON.stringify(op.id)} (a replaced component keeps its id; remove it and insert a new one to change ids)`; break; }
+        problem = checkNewNode({ ...op.node, id: op.id }, `${at}.node`) ?? addNodes(op.nodes, `${at}.nodes`);
+        if (problem) break;
+        const prev = nodes.get(op.id);
+        for (const c of prev.children ?? []) if (parentOf.get(c) === op.id) parentOf.delete(c);
+        const next = normalize({ id: op.id, type: op.node.type, ...(op.node.props !== undefined ? { props: clone(op.node.props) } : {}), ...(op.node.children !== undefined ? { children: [...op.node.children] } : {}) });
+        nodes.set(op.id, next);
+        for (const c of next.children ?? []) parentOf.set(c, op.id);
+        changed.add(op.id);
+        break;
+      }
+      case 'insertChild': {
+        problem = existing(op.parent, `${at}.parent`) ?? addNodes(op.nodes, `${at}.nodes`) ?? existing(op.id, `${at}.id`);
+        if (problem) break;
+        if (op.id === ui.root) { problem = `${at}.id: the root cannot be inserted as a child`; break; }
+        if (parentOf.has(op.id)) {
+          problem = `${at}.id: ${JSON.stringify(op.id)} already has a parent (${parentOf.get(op.id)}); removeNode it first or insert a new component`;
+          break;
+        }
+        const parent = nodes.get(op.parent);
+        const kids = [...(parent.children ?? [])];
+        const index = op.index === undefined ? kids.length : op.index;
+        if (!Number.isInteger(index) || index < 0 || index > kids.length) { problem = `${at}.index: expected an integer from 0 to ${kids.length}`; break; }
+        kids.splice(index, 0, op.id);
+        parent.children = kids;
+        parentOf.set(op.id, op.parent);
+        changed.add(op.parent);
+        changed.add(op.id);
+        break;
+      }
+      case 'removeNode': {
+        problem = existing(op.id, `${at}.id`);
+        if (problem) break;
+        if (op.id === ui.root) { problem = `${at}.id: the root cannot be removed; replaceNode it or call ui_render with a new UI`; break; }
+        const parentId = parentOf.get(op.id);
+        const parent = parentId === undefined ? undefined : nodes.get(parentId);
+        if (parent) {
+          parent.children = (parent.children ?? []).filter(c => c !== op.id);
+          changed.add(parentId);
+        }
+        parentOf.delete(op.id);
+        nodes.delete(op.id);
+        changed.delete(op.id);
+        break;
+      }
+    }
+    if (problem) return fail([problem]);
+  }
+
+  const title = args.title !== undefined ? args.title : ui.title;
+  const components = reachable(ui.root, nodes);
+  // The whole next version passes the same checks as a fresh ui_render.
+  const check = validateTree(clone({ ...(title ? { title } : {}), root: ui.root, components }));
+  if (!check.ok) return fail(check.errors.slice(0, 40));
+  const reached = new Set(components.map(n => n.id));
+  const dropped = [...added].filter(id => !reached.has(id));
+  const warnings = dropped.length ? [`new components not attached anywhere (dropped): ${dropped.join(', ')}`] : [];
+  return {
+    ok: true,
+    ui: { uiId: ui.uiId, version: ui.version + 1, ...(title ? { title } : {}), root: ui.root, components },
+    changed: [...changed].filter(id => reached.has(id)),
+    warnings,
+  };
+}
+
+/**
+ * Rebuild the current version of every UI in one conversation from its message
+ * history: each `ui_render` call that settled without error and validates, then
+ * each settled `ui_patch` call in result order. Patches are deterministic, so
+ * replaying them reproduces exactly the versions the user saw. Calls without a
+ * result yet (including the one being executed) are ignored.
+ * @param {readonly any[]} messages - `Session.deriveMessages()`.
+ * @param {{ render: string, patch: string }} tools - tool names.
+ * @returns {Map<string, UiSnapshot>}
+ */
+export function collectUis(messages, tools) {
+  const calls = new Map();
+  const uis = new Map();
+  for (const m of messages) {
+    if (m?.role === 'assistant' && Array.isArray(m.content)) {
+      for (const b of m.content) {
+        if (b?.type === 'tool-call' && (b.name === tools.render || b.name === tools.patch)) calls.set(b.id, b);
+      }
+      continue;
+    }
+    if (m?.role !== 'tool' || m.isError === true) continue;
+    const call = calls.get(m.toolCallId);
+    if (!call) continue;
+    calls.delete(m.toolCallId);
+    let args;
+    try { args = typeof call.arguments === 'string' ? JSON.parse(call.arguments) : call.arguments; } catch { continue; }
+    if (call.name === tools.render) {
+      if (validateTree(clone(args ?? null)).ok) uis.set(call.id, snapshotOf(call.id, args));
+      continue;
+    }
+    const ui = isPlainObject(args) && typeof args.uiId === 'string' ? uis.get(args.uiId) : undefined;
+    if (!ui) continue;
+    const result = applyPatch(ui, args);
+    if (result.ok) uis.set(ui.uiId, result.ui);
+  }
+  return uis;
+}
+
+/** Compact `id:Type` outline the model can address in its next patch. */
+export function outline(ui, max = 80) {
+  const parts = ui.components.slice(0, max).map(n => `${n.id}:${n.type}`);
+  if (ui.components.length > max) parts.push(`… ${ui.components.length - max} more`);
+  return parts.join(', ');
+}

package/src/compat.js

@@ -12,7 +12,7 @@
 export const SUPPORTED_DSH_RANGE = '>=0.1.7-rc.1 <0.3.0-0 || >=0.2.0-0 <0.2.0 || >=0.2.1-0 <0.2.1';
 
 /** Versions the CI compatibility matrix installs the packed plugin into. */
-export const TESTED_DSH_VERSIONS = Object.freeze(['0.1.7-rc.2', '0.2.0-rc.1', '0.2.0-rc.2', '0.2.1-alpha.2']);
+export const TESTED_DSH_VERSIONS = Object.freeze(['0.1.7-rc.2', '0.2.0-rc.1', '0.2.0-rc.2', '0.2.1-alpha.2', '0.2.1-alpha.4']);
 
 /** Lowest Node.js version DSH itself requires. */
 export const MIN_NODE_VERSION = '22.13.0';

package/src/guidance.js

@@ -6,6 +6,7 @@
  * @module deepseek-harness-intelligent-ui/guidance
  */
 import { RENDER_TOOL } from './tools/render.js';
+import { PATCH_TOOL } from './tools/patch.js';
 import { WIDGET_TOOL } from './tools/widget.js';
 
 /** Placement right after MCP server instructions (3100) and before the tools SDK (5000). */
@@ -43,7 +44,11 @@ export function guidanceText(config) {
   lines.push('', 'Interaction design:');
   lines.push('- Everything that can be computed in the browser happens there: sliders, toggles, rotation, zoom, filtering, sorting and recomputing formulas update the UI instantly without a message to you.');
   lines.push('- Send a message to yourself (Button, Form, Bridge.sendPrompt) only for explicit user requests that need you: an explanation, new data, a decision, the next step. Interactions reach you as the user\'s NEXT message; never trigger them automatically and do not wait for them in the current turn.');
-  lines.push('- When the user asks to change a UI, call the tool again with the complete updated UI.');
+  if (config.enableCatalog) {
+    lines.push(`- When the user asks to change a UI you showed (${RENDER_TOOL}), prefer \`${PATCH_TOOL}\`: send only the changed components by id (e.g. switch one Chart from bar to line), with the uiId and version from the last result for that UI. Untouched components keep the user's sorting, tab, form input and slider positions.`);
+    lines.push(`- Re-send the complete UI with ${RENDER_TOOL} only for a new UI, when most of it changes, or when ${PATCH_TOOL} reports the UI is unavailable.`);
+  }
+  if (config.enableWidget) lines.push(`- To change a widget, call ${WIDGET_TOOL} again with the complete updated widget.`);
   lines.push('', 'Quality:');
   lines.push('- One UI call per answer is usually enough. Real data only: never invent numbers to fill a chart; if data is missing, say so or ask.');
   lines.push('- Keep UI component trees clean and concise (e.g. 4-8 milestones for Timeline, 4-8 rows for Table). Keep text props succinct and avoid excessively long paragraphs inside components.');

package/src/plugin.js

@@ -1,13 +1,14 @@
 /**
  * DeepSeek Harness Intelligent UI — Host half.
  *
- * Registers the generative-UI tools (`ui_render`, `ui_render_widget`), the
+ * Registers the generative-UI tools (`ui_render`, `ui_patch`, `ui_render_widget`), the
  * `/ui` command and an optional system-prompt section. The browser half
  * (`./client`) renders each tool call in the `tool.call.toolview` slot.
  * @module deepseek-harness-intelligent-ui
  */
 import { Config as ConfigSchema, resolveConfig } from './config.js';
 import { createRenderTool } from './tools/render.js';
+import { createPatchTool } from './tools/patch.js';
 import { createWidgetTool } from './tools/widget.js';
 import { GUIDANCE_ORDER, guidanceText } from './guidance.js';
 import { registerCommands } from './commands.js';
@@ -24,7 +25,10 @@ export function apply(ctx, rawConfig) {
   const config = resolveConfig(rawConfig);
   // tools.register / commands.register are fiber effects: unloading this
   // plugin unregisters everything, so no manual disposer bookkeeping.
-  if (config.enableCatalog) ctx.tools.register(createRenderTool(config));
+  if (config.enableCatalog) {
+    ctx.tools.register(createRenderTool(config));
+    ctx.tools.register(createPatchTool(config));
+  }
   if (config.enableWidget) ctx.tools.register(createWidgetTool(config));
   registerCommands(ctx.commands, config);
 

package/src/portable/artifacts.js

@@ -0,0 +1,87 @@
+/**
+ * Host-neutral native DSH event projection. Never infer UI data from text.
+ * Only successful tool result metadata can authorize a render or atomic patch.
+ */
+import { validateTree } from '../catalog/catalog.js';
+
+const MAX_ARGUMENT_CHARS = 480_000;
+const TOOLS = new Set(['ui_render', 'ui_patch', 'ui_render_widget']);
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const text = value => typeof value === 'string' && value.length > 0;
+const clone = value => JSON.parse(JSON.stringify(value));
+
+function argumentsOf(input) {
+  if (typeof input === 'string' && input.length <= MAX_ARGUMENT_CHARS) {
+    try { const parsed = JSON.parse(input); return object(parsed) ? parsed : undefined; }
+    catch { return undefined; }
+  }
+  return undefined;
+}
+function validTree(input) {
+  try { return object(input) && validateTree(clone(input)).ok; }
+  catch { return false; }
+}
+
+/**
+ * Project one session's native history and/or mux event records.
+ * Events may be SessionEvent[] or session.history rows with an event field.
+ * Correctness does not depend on input order; correlation follows callId.
+ *
+ * @param {readonly any[]} events
+ * @param {{hostId:string,sessionId:string}} scope
+ */
+export function projectNativeUiEvents(events, { hostId, sessionId }) {
+  if (!text(hostId) || !text(sessionId)) return [];
+  const calls = new Map();
+  const settled = [];
+  const sorted = events.map(row => row?.event ?? row)
+    .filter(event => object(event) && typeof event.seq === 'number')
+    .sort((a, b) => a.seq - b.seq);
+  for (const event of sorted) {
+    const data = object(event.data) ? event.data : {};
+    if (event.type === 'tool/call' && TOOLS.has(data.name) && text(data.callId)) {
+      const args = argumentsOf(data.arguments);
+      if (args) calls.set(data.callId, { kind: data.name, args, turn: data.turn });
+      continue;
+    }
+    if (event.type !== 'tool/result') continue;
+    const message = object(data.message) ? data.message : {};
+    const id = object(message.source) ? message.source.callId : data.callId;
+    if (!text(id)) continue;
+    const call = calls.get(id);
+    if (!call) continue;
+    const meta = data.meta;
+    if (!object(meta) || meta.ok !== true || message.isError === true || data.isError === true || object(data.error)) continue;
+    settled.push({ id, call, meta, seq: event.seq });
+  }
+  const latest = new Map();
+  for (const { id, call, meta, seq } of settled.sort((a, b) => a.seq - b.seq)) {
+    const args = call.args;
+    const policy = object(meta.policy) ? meta.policy : undefined;
+    const turn = call.turn === undefined ? undefined : String(call.turn);
+    if (call.kind === 'ui_render' && validTree(args)) {
+      if (latest.has(id)) continue;
+      latest.set(id, { kind: 'declarative', hostId, sessionId, uiId: id, version: 1,
+        title: typeof args.title === 'string' ? args.title : undefined,
+        definition: args, policy, turn, seq });
+      continue;
+    }
+    if (call.kind === 'ui_render_widget' && text(args.html)) {
+      if (latest.has(id)) continue;
+      latest.set(id, { kind: 'widget', hostId, sessionId, uiId: id, version: 1,
+        title: typeof args.title === 'string' ? args.title : undefined,
+        definition: args, policy, turn, seq });
+      continue;
+    }
+    if (call.kind !== 'ui_patch' || !text(args.uiId) || !Number.isSafeInteger(args.baseVersion)) continue;
+    const prior = latest.get(args.uiId);
+    const next = meta.ui;
+    if (!prior || prior.kind !== 'declarative' || prior.version !== args.baseVersion
+      || !object(next) || next.uiId !== args.uiId || next.version !== prior.version + 1
+      || !validTree(next)) continue;
+    latest.set(prior.uiId, { ...prior, version: next.version, definition: next,
+      title: typeof next.title === 'string' ? next.title : prior.title,
+      policy: policy ?? prior.policy, turn: prior.turn, updatedTurn: turn ?? prior.updatedTurn, seq });
+  }
+  return [...latest.values()].sort((a, b) => a.seq - b.seq);
+}

package/src/tools/patch.js

@@ -0,0 +1,139 @@
+/**
+ * `ui_patch`: update a UI shown earlier in this conversation in place, by
+ * component id, instead of re-sending the whole tree. execute() rebuilds the
+ * UI's current version from the session's own history (see catalog/patch.js),
+ * applies the operations atomically and returns the complete next version in
+ * `presentationMeta`, so the browser renders it without replaying anything and
+ * a reload reproduces it from the durable `tool/result`.
+ * @module deepseek-harness-intelligent-ui/tools/patch
+ */
+import { COMPONENT_TYPES } from '../catalog/catalog.js';
+import { applyPatch, collectUis, outline, PATCH_LIMITS, PATCH_OPS } from '../catalog/patch.js';
+import { clientPolicy } from '../config.js';
+import { RENDER_TOOL } from './render.js';
+
+export const PATCH_TOOL = 'ui_patch';
+
+const NODE = {
+  type: 'object',
+  properties: {
+    id: { type: 'string', description: 'Unique new component id.' },
+    type: { type: 'string', enum: [...COMPONENT_TYPES] },
+    props: { type: 'object' },
+    children: { type: 'array', items: { type: 'string' } },
+  },
+  required: ['id', 'type'],
+};
+
+/**
+ * The UIs of the calling conversation, or an explanation why there are none.
+ * @param {any} exec - ToolRunContext.
+ */
+function conversationUis(exec) {
+  const session = exec?.agent?.session;
+  if (!session || typeof session.deriveMessages !== 'function') return undefined;
+  return collectUis(session.deriveMessages(), { render: RENDER_TOOL, patch: PATCH_TOOL });
+}
+
+/**
+ * @param {ReturnType<import('../config.js').resolveConfig>} config
+ */
+export function createPatchTool(config) {
+  const policy = clientPolicy(config);
+  return {
+    name: PATCH_TOOL,
+    description: [
+      `Change a UI that ${RENDER_TOOL} (or an earlier ${PATCH_TOOL}) already showed in THIS conversation, in place, without re-sending the whole UI.`,
+      'Address it by its uiId and the version you are changing (both are in the tool result that showed it); address components by their ids.',
+      'Components you do not touch keep their content and the user\'s state (table sort, selected tab, form input, slider positions).',
+      'Operations, applied in order and all-or-nothing:',
+      '- setProps {id, props, unset?}: merge props into a component (e.g. {"id":"chart","props":{"kind":"line"}}); unset lists prop names to remove.',
+      '- replaceNode {id, node:{type, props, children?}, nodes?}: replace one component\'s type/props/children, keeping its id (its state resets).',
+      '- insertChild {parent, id, index?, nodes}: add the new component `id` (defined in `nodes`, with any descendants) under `parent`, at `index` (default: last).',
+      '- removeNode {id}: remove a component and everything under it (not the root). Keep Tabs labels in step with their children in the same patch.',
+      `On ok=false nothing changed; fix the listed problems and retry. A stale baseVersion means the UI changed: patch the current version. Use ${RENDER_TOOL} instead for a new UI, a different root, or when most of the UI changes. Widgets (ui_render_widget) cannot be patched; render them again.`,
+    ].join('\n'),
+    parameters: {
+      type: 'object',
+      properties: {
+        uiId: { type: 'string', description: 'uiId of the UI to change, from the tool result that showed it.' },
+        baseVersion: { type: 'integer', description: 'The UI version this patch is based on (1 after ui_render; each patch result reports the new version).' },
+        title: { type: 'string', description: 'Optional new card title.' },
+        ops: {
+          type: 'array',
+          description: `1-${PATCH_LIMITS.ops} operations, applied in order.`,
+          items: {
+            type: 'object',
+            properties: {
+              op: { type: 'string', enum: [...PATCH_OPS] },
+              id: { type: 'string', description: 'Target component id (insertChild: the new child id).' },
+              props: { type: 'object', description: 'setProps: props to merge.' },
+              unset: { type: 'array', items: { type: 'string' }, description: 'setProps: prop names to remove.' },
+              node: {
+                type: 'object',
+                description: 'replaceNode: the replacement (same id).',
+                properties: {
+                  type: { type: 'string', enum: [...COMPONENT_TYPES] },
+                  props: { type: 'object' },
+                  children: { type: 'array', items: { type: 'string' } },
+                },
+                required: ['type'],
+              },
+              parent: { type: 'string', description: 'insertChild: the container to insert into.' },
+              index: { type: 'integer', description: 'insertChild: position among the parent\'s children.' },
+              nodes: { type: 'array', items: NODE, description: 'insertChild/replaceNode: new components (flat list, children by id).' },
+            },
+            required: ['op'],
+          },
+        },
+      },
+      required: ['uiId', 'baseVersion', 'ops'],
+    },
+    output: {
+      schema: {
+        type: 'object',
+        properties: {
+          ok: { type: 'boolean' },
+          summary: { type: 'string' },
+          errors: { type: 'array', items: { type: 'string' } },
+          code: { type: 'string' },
+          ui: { type: 'object' },
+        },
+        required: ['ok', 'summary'],
+      },
+      render: (_args, value) => [{ type: 'text', text: value.ok ? value.summary : `${value.summary}\n${(value.errors || []).map(e => `- ${e}`).join('\n')}` }],
+      // The complete next version travels to the browser; the model only sees the summary.
+      presentationMeta: (_args, value) => (value.ok ? { ok: true, policy, ui: value.ui } : { ok: false, policy, ...(value.code ? { code: value.code } : {}) }),
+    },
+    // Exclusive: patches of one UI must apply in a single, replayable order.
+    isConcurrencySafe: () => false,
+    async execute(args, exec) {
+      const refuse = (errors, code = 'invalid') => ({
+        ok: false,
+        code,
+        summary: `UI not changed: ${errors.length} problem(s). The user still sees the previous version.`,
+        errors,
+      });
+      if (typeof args !== 'object' || args === null || typeof args.uiId !== 'string' || args.uiId === '') {
+        return refuse(['uiId: expected the uiId of a UI shown earlier in this conversation']);
+      }
+      const uis = conversationUis(exec);
+      if (!uis) return refuse([`${PATCH_TOOL} is only available inside a conversation; call ${RENDER_TOOL} with the complete UI`], 'unavailable');
+      const ui = uis.get(args.uiId);
+      if (!ui) {
+        const known = [...uis.values()].slice(-5).map(u => `${u.uiId} (v${u.version}${u.title ? ` "${u.title}"` : ''})`);
+        return refuse([`uiId: no UI ${JSON.stringify(args.uiId)} in this conversation${known.length ? `; known: ${known.join(', ')}` : ''}. If it is no longer available, call ${RENDER_TOOL} with the complete UI.`], 'unknown');
+      }
+      const result = applyPatch(ui, args);
+      if (!result.ok) return refuse(result.errors, result.code);
+      const next = result.ui;
+      const title = next.title ? ` "${next.title}"` : '';
+      const warn = result.warnings.length ? ` Warning: ${result.warnings.join('; ')}.` : '';
+      return {
+        ok: true,
+        summary: `UI${title} updated in place: uiId ${next.uiId}, now version ${next.version} (changed: ${result.changed.join(', ') || 'title'}).${warn} Components: ${outline(next)}.`,
+        ui: next,
+      };
+    },
+  };
+}

package/src/tools/render.js

@@ -63,7 +63,7 @@ export function createRenderTool(config) {
       presentationMeta: (_args, value) => ({ ok: value.ok, policy }),
     },
     isConcurrencySafe: () => true,
-    async execute(args) {
+    async execute(args, exec) {
       const result = validateTree(args);
       if (!result.ok) {
         return {
@@ -75,9 +75,11 @@ export function createRenderTool(config) {
       const kinds = Object.entries(result.types).map(([t, n]) => (n > 1 ? `${n}x ${t}` : t)).join(', ');
       const title = typeof args.title === 'string' && args.title ? ` "${args.title}"` : '';
       const warn = result.warnings.length ? ` Warning: ${result.warnings.join('; ')}.` : '';
+      // The call id doubles as the UI's identity for later in-place patches.
+      const handle = exec?.callId ? ` uiId ${exec.callId}, version 1 (change it later with ui_patch).` : '';
       return {
         ok: true,
-        summary: `UI${title} is now displayed to the user (${result.count} components: ${kinds}).${warn} User interactions will arrive as new user messages.`,
+        summary: `UI${title} is now displayed to the user (${result.count} components: ${kinds}).${warn}${handle} User interactions will arrive as new user messages.`,
       };
     },
   };