@unoverse-platform/studio 0.1.90 → 0.1.91

package/vendor/base/src/agent-mcp/memoryContext.ts

@@ -0,0 +1,104 @@
+/**
+ * User-memory context fetch — the READ twin of memoryIngest.ts.
+ *
+ * Harness-level (model-agnostic): when an agent node's User Memory toggle
+ * (config.enableUserMemory) is ON, the harness fetches the user's standing
+ * memory block (identity + current state, non-intrusion framing included)
+ * from the memory server's GET /context at LOOP START and inlines it into the
+ * agent's system context — memory arrives with the agent, never as a
+ * model-visible tool call (MEMORY_SPEC.md v3 § Serving: zero-call standing lane).
+ *
+ * Every agent family calls this once when building its instructions. Soft-fail
+ * by design: memory server down / cold / no identity → returns "" and the agent
+ * simply starts ungrounded — memory must never block or fail the conversation.
+ */
+
+const MEMORY_SERVICE_URL = process.env.MEMORY_SERVICE_URL || "http://localhost:4114";
+const CONTEXT_FETCH_TIMEOUT_MS = 3_000;
+
+/**
+ * Fetch the user's standing memory block, ready to append to the agent's
+ * system context. Resolves identity from the node's execution context; returns
+ * "" when the toggle is off, identity is incomplete, or the fetch fails.
+ * Never throws.
+ */
+export async function fetchUserMemoryContext(
+  config: { enableUserMemory?: boolean },
+  executionContext: any,
+  logger: any,
+): Promise<string> {
+  if (config?.enableUserMemory !== true) return "";
+
+  const pubCtx = executionContext?.publishingContext;
+  const userId = pubCtx?.userId;
+  const workflowId = executionContext?.workflow?.id;
+  if (!userId || !workflowId) {
+    logger?.debug?.("[MemoryContext] Skipped — incomplete identity", {
+      hasUserId: !!userId,
+      hasWorkflowId: !!workflowId,
+    });
+    return "";
+  }
+
+  return fetchUserMemoryBlock(userId, workflowId, executionContext?.auth?.accessToken, logger);
+}
+
+/**
+ * The bare standing-context read, for callers that hold identity directly (the
+ * director's verdict lane reads it this way — no node config, no execution
+ * context). Same endpoint, same soft-fail: any problem returns "".
+ */
+export async function fetchUserMemoryBlock(userId: string, workflowId: string, accessToken?: string, logger?: any): Promise<string> {
+  if (!userId || !workflowId) return "";
+  const headers: Record<string, string> = { "Content-Type": "application/json" };
+  if (accessToken) headers["Authorization"] = `Bearer ${accessToken}`;
+
+  try {
+    const params = new URLSearchParams({ userId, workflowId });
+    const res = await fetch(`${MEMORY_SERVICE_URL}/context?${params}`, {
+      headers,
+      signal: AbortSignal.timeout(CONTEXT_FETCH_TIMEOUT_MS),
+    });
+    if (!res.ok) {
+      logger?.warn?.(`[MemoryContext] Fetch rejected: ${res.status}`);
+      return "";
+    }
+    const data = (await res.json()) as { block?: string; count?: number; identity?: string | null };
+    const block = typeof data.block === "string" ? data.block : "";
+    if (block) {
+      logger?.info?.("[MemoryContext] User context injected", {
+        hasIdentity: !!data.identity,
+        stateLines: data.count ?? 0,
+        chars: block.length,
+      });
+    }
+    return block;
+  } catch (err: any) {
+    logger?.warn?.(`[MemoryContext] Fetch failed (non-blocking): ${err?.message ?? err}`);
+    return "";
+  }
+}
+
+/**
+ * THE standard user-memory hydration — the ONE call every agent family makes.
+ *
+ * When the User Memory toggle is on, the user's context snapshot (identity,
+ * verified key facts, open tasks, learned state) is prepended to the USER
+ * PROMPT of EVERY request — the input side, not the system prompt: facts that
+ * ride with the request get factored into the answer, refresh each turn, and
+ * survive previousResponseId resume + prompt caching.
+ *
+ * Families call `hydratePromptWithUserMemory(config, executionContext, logger,
+ * prompt)` and send the result as the user turn. Toggle off / fetch failure →
+ * the prompt passes through untouched. Do NOT hand-roll the concatenation in
+ * node code — the convention lives here so it cannot drift per family.
+ */
+export async function hydratePromptWithUserMemory(
+  config: { enableUserMemory?: boolean },
+  executionContext: any,
+  logger: any,
+  prompt: string,
+): Promise<string> {
+  const block = await fetchUserMemoryContext(config, executionContext, logger);
+  return block ? `${block}\n\n---\n\n${prompt}` : prompt;
+}

package/vendor/base/src/agent-mcp/memoryIngest.ts

@@ -0,0 +1,88 @@
+/**
+ * Memory ingest — the agent saves its own conversation turns.
+ *
+ * Harness-level (model-agnostic): when an agent node's User Memory toggle
+ * (config.enableUserMemory) is ON, each completed turn (original user input +
+ * final agent answer — never intermediate iterations or tool chatter) is
+ * POSTed to the memory server's /memory/ingest, which feeds the L1→L4
+ * cascade (see docs/architecture/MEMORY_SPEC.md). Replaces the retired
+ * GravityMemoryStore canvas node.
+ *
+ * Every agent family calls this at turn completion with its own node type;
+ * fire-and-forget — memory must never block or fail the conversation.
+ */
+
+const MEMORY_SERVICE_URL = process.env.MEMORY_SERVICE_URL || "http://localhost:4114";
+
+export interface ConversationTurn {
+  userMessage: string;
+  agentResponse: string;
+  reasoning?: string;
+}
+
+/**
+ * Save one completed conversation turn to the memory server.
+ * Resolves identity from the node's execution context; silently no-ops when
+ * the toggle is off or identity is incomplete (e.g. canvas test runs with no
+ * conversation). Never throws.
+ */
+export function ingestConversationTurn(
+  config: { enableUserMemory?: boolean },
+  executionContext: any,
+  turn: ConversationTurn,
+  logger: any,
+  sourceNodeType: string,
+): void {
+  if (config?.enableUserMemory !== true) return;
+  if (!turn.userMessage && !turn.agentResponse) return;
+
+  const pubCtx = executionContext?.publishingContext;
+  const userId = pubCtx?.userId;
+  const workflowId = executionContext?.workflow?.id;
+  const conversationId = pubCtx?.conversationId;
+  if (!userId || !workflowId || !conversationId) {
+    logger?.debug?.("[MemoryIngest] Skipped — incomplete identity", {
+      hasUserId: !!userId,
+      hasWorkflowId: !!workflowId,
+      hasConversationId: !!conversationId,
+    });
+    return;
+  }
+
+  const payload: Record<string, any> = {
+    userId,
+    workflowId,
+    conversationId,
+    executionId: executionContext?.executionId || "",
+    sourceNodeId: executionContext?.nodeId,
+    sourceNodeType,
+    timestamp: new Date().toISOString(),
+  };
+  // Only include fields with content — /memory/ingest rejects all-empty events
+  if (turn.userMessage) payload.userMessage = turn.userMessage;
+  if (turn.agentResponse) payload.agentResponse = turn.agentResponse;
+  if (turn.reasoning) payload.reasoning = turn.reasoning;
+
+  const headers: Record<string, string> = { "Content-Type": "application/json" };
+  const accessToken = executionContext?.auth?.accessToken;
+  if (accessToken) headers["Authorization"] = `Bearer ${accessToken}`;
+
+  fetch(`${MEMORY_SERVICE_URL}/memory/ingest`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(payload),
+  })
+    .then((res) => {
+      if (!res.ok) {
+        logger?.warn?.(`[MemoryIngest] Ingest rejected: ${res.status}`);
+      } else {
+        logger?.info?.("[MemoryIngest] Turn saved to memory", {
+          userMsg: turn.userMessage.length,
+          agentResp: turn.agentResponse.length,
+        });
+      }
+    })
+    .catch((err) => {
+      logger?.warn?.(`[MemoryIngest] Ingest failed (non-blocking): ${err.message}`);
+    });
+}

package/vendor/base/src/agent-mcp/rowComponents.ts

@@ -0,0 +1,172 @@
+/**
+ * ROW COMPONENTS: a search result row may NAME a component, and surfacing the row renders
+ * that component rather than describing it.
+ *
+ * It is whatever component the row attached — a page, a chart, a document, a product panel.
+ * Nothing here is card-shaped; the lane was called "cards" for its first use and the name
+ * outlived the accuracy (renamed 2026-08-09).
+ */
+import type { RowComponent, AppInvocationContext } from "./types.js";
+import { invokeComponentAppNative } from "./invoke.js";
+// Pure section helpers, shared with every renderer so the rules live in one place.
+import { toDocument } from "../markdown/document.js";
+
+
+/**
+ * Extract renderable COMPONENTS from search RESULT ROWS — content-tree rows
+ * (service/need) with a component ATTACHED (`metadata.app`, no workflow).
+ *
+ * The attachment is a component URI, so it is ANY component the row's author chose,
+ * not a card. (`unoverse://components/…` only: a row naming a template or carrying a
+ * `workflow` is skipped — the latter is a TOOL the model calls.)
+ *
+ * These NEVER reach a model's toolset: the component renders DATA-DRIVEN the moment
+ * discovery surfaces its row — the conversation flows normally and it simply appears
+ * (however many rows carry one). The model is neither asked nor able to decide; there
+ * is no prompt. The lane executes in the SPATIAL SEARCH NODE (the search that produced
+ * the rows renders them — every agent family gets the behavior by wiring the node), via
+ * `renderRowComponents` below.
+ */
+export function rowComponentsFromResults(results: unknown): RowComponent[] {
+  const out: RowComponent[] = [];
+  const seen = new Set<string>();
+  if (!Array.isArray(results)) return out;
+  for (const item of results as any[]) {
+    if (item?.object_type === "mcp") continue; // registry apps are TOOLS (path A/B above)
+    const app = item?.metadata?.app;
+    if (typeof app !== "string" || !app.startsWith("unoverse://components/") || item.metadata.workflow) continue;
+    const component = componentTypeFromAppUri(app);
+    const id = String(item.id || item.universal_id || `${component}:${item.title ?? ""}`);
+    if (!component || seen.has(id)) continue;
+    seen.add(id);
+    out.push({
+      id,
+      component,
+      // The row's content IS the component's state. Row-level facts ride along:
+      // `link` is the row's page as a LABELLED markdown link — tagline (fallback
+      // title) linked to source_url, ready for a Markdown bind.
+      props: {
+        title: item.title,
+        description: item.description,
+        // EVERY row carries `sections`, so a renderer has ONE thing to read. A row promoted
+        // before the structuring pass existed has only `bodyCopy`, which is a valid document
+        // of one prose section — synthesised here rather than in each renderer, and never
+        // overwriting the sections the row already carries.
+        ...(!item.metadata.sections && item.metadata.bodyCopy
+          ? { sections: [{ kind: "prose", heading: "", body: item.metadata.bodyCopy }] }
+          : {}),
+        ...(item.metadata.sections ? toDocument(item.metadata.sections, item.metadata.layout as string) : {}),
+        ...(item.source_url
+          ? { link: `[${item.metadata.tagline || item.title || item.source_url}](${item.source_url})` }
+          : {}),
+        ...item.metadata,
+      },
+    });
+  }
+  return out;
+}
+
+/**
+ * Render the components discovered rows carry, on the caller's live session — the ONE
+ * place this lane executes (every agent family calls this; adapters never re-implement
+ * it). Renders are fire-and-forget (a display component declares no `outputs`, so the
+ * held call resolves immediately server-side) and a failed render never breaks the
+ * conversation.
+ */
+/**
+ * THE EMPTY DELIVERY IS SAID, NOT INFERRED (UNOVERSE_TEMPLATE_MODEL §12e, the
+ * mechanical spent rule): a component-capable search that ran and surfaced
+ * nothing has REPLACED the previous answer with nothing, and the receiver needs
+ * to know. One listener (the server's director bookkeeping) registers here at
+ * boot; the lane announces, the receiver decides. In-process only by design —
+ * if the lane ever runs out of process the note goes missing and the rule fails
+ * toward KEEP, the safe side.
+ */
+let emptyDeliveryListener: ((chatId: string) => void) | null = null;
+export function onEmptyRowDelivery(fn: (chatId: string) => void): void {
+  emptyDeliveryListener = fn;
+}
+
+export function renderRowComponents(
+  items: RowComponent[] | undefined,
+  ctx: AppInvocationContext,
+  log?: (msg: string) => void,
+): void {
+  // No live session (builder/test/headless callers) → nothing to render; the
+  // search stays pure automatically — no flag juggling needed by the caller.
+  if (!ctx.userId) return;
+  if (!items?.length) {
+    // The search ran on a live session and surfaced nothing — say so (§12e).
+    if (ctx.chatId) emptyDeliveryListener?.(ctx.chatId);
+    return;
+  }
+  // ONE DELIVERY, announced as a batch (UNOVERSE_TEMPLATE_MODEL §12e): the server's
+  // director waits for all siblings, judges once, and only the held set renders —
+  // in verdict order, before anything reaches the screen.
+  const batchId = `${ctx.chatId ?? ctx.conversationId ?? "b"}:${Math.random().toString(36).slice(2, 8)}`;
+  let index = 0;
+  for (const item of items) {
+    // Per-row instance id: keys the render `<component>:<rowId>` server-side, so
+    // multiple rows sharing one component each get their OWN slice (and a repeat
+    // render of the same row re-merges the same slice — idempotent, no dupes).
+    log?.(
+      `🧩 dispatching ${item.component} (${item.id}) → conv=${ctx.conversationId ?? "MISSING"} ` +
+        `chat=${ctx.chatId ?? "MISSING"} user=${ctx.userId ?? "MISSING"} token=${ctx.accessToken ? "yes" : "NO"}`,
+    );
+    // fromRow: this content came from the DATABASE, not from a model composing parts.
+    // Without it the brief referee judges the row — a component that renders the Document
+    // inherits its prose/keyFacts briefs and gets rejected for parts nobody composes.
+    // Fire-and-forget, log on settle: a slow render must not hold up the answer.
+    invokeComponentAppNative(item.component, { ...ctx, message: "", props: item.props, instanceId: item.id, fromRow: true, batch: { id: batchId, size: items.length, index: index++ } })
+      // "RENDERED" must mean rendered: a director-dropped card resolves too
+      // (action: "held-back") and saying RENDERED for it is the exact
+      // proof-of-nothing this log line was once rewritten to stop telling.
+      .then((r) => log?.(r.action === "held-back" ? `🧩 HELD BACK ${item.component} (${item.id})` : `🧩 RENDERED ${item.component} (${item.id})`))
+      .catch((e: any) => log?.(`🧩 FAILED ${item.component} (${item.id}) — ${e?.message ?? e}`));
+  }
+}
+
+/** `unoverse://components/journey-finder` → `journey-finder`;
+ *  `unoverse://components/bpp/journey-finder` → `bpp/journey-finder` (the render ref);
+ *  `unoverse://templates/<org>/<page>` → `<org>/<page>`.
+ *  The org survives: names are unique only within a tier, so stripping to the last
+ *  segment would collapse two orgs' same-named components into one ambiguous type.
+ *
+ * BOTH HOMES, because an app URI names the tier it lives in (`componentUri`, meta.ts:
+ * "the address says WHAT it is"). This stripped `components/` alone, so a discovered
+ * TEMPLATE fell through with its whole URI intact — and the caller, which swaps `/` for
+ * `.` because MCP tool names carry no slash, asked the door for
+ * `unoverse:..templates.<org>.<page>`. Observed live 2026-08-31: an agent
+ * composed an entire page, every part filled, and the call bounced with -32602 at the
+ * door. Silent but for the agent's own trace, since nothing downstream logs a name it
+ * never resolved. */
+export function componentTypeFromAppUri(app: string): string {
+  return String(app)
+    .replace(/^unoverse:\/\/(components|templates)\//, "")
+    .replace(/^\/+|\/+$/g, "");
+}
+
+/**
+ * THE UNLOCKING SEARCH'S ROWS, in rank order — the material a page can be DRAFTED from
+ * before the model has written a word (2026-09-01).
+ *
+ * Every row, not only the ones carrying a component: a draft fills parts that need no
+ * authoring (an image ref, a gallery of pure refs), and those reference CONTENT, which has
+ * nothing to do with whether a row has a card attached. Restricting this to card-carrying
+ * rows is what left a page drafting from three hotels while the attractions sat unusable.
+ */
+export function rankedRowIds(resultContent: string, limit = 12): string[] {
+  try {
+    const parsed = JSON.parse(resultContent) as { results?: unknown };
+    if (!Array.isArray(parsed?.results)) return [];
+    const out: string[] = [];
+    for (const r of parsed.results as Record<string, unknown>[]) {
+      const id = r?.universal_id ?? r?.id;
+      if (typeof id === "string" && id.trim() && !out.includes(id)) out.push(id);
+      if (out.length >= limit) break;
+    }
+    return out;
+  } catch {
+    return []; // a search result we cannot read drafts nothing; the page still opens
+  }
+}

package/vendor/base/src/agent-mcp/tools.ts

@@ -0,0 +1,134 @@
+/**
+ * MINTING A MODEL TOOL FROM A DISCOVERED APP.
+ *
+ * One discovered row becomes one tool definition. A path-B component app has no schema on
+ * the row at all, so its input schema is read LIVE from the app's own resource at mint time.
+ */
+import type { AgentToolDef, DiscoveredMCP, AppInvocationContext } from "./types.js";
+import { connectPlatformMcp, invokeComponentAppNative } from "./invoke.js";
+import { APP_ETIQUETTE } from "./discovery.js";
+
+/**
+ * AN IDENTITY IS NOT A TOOL NAME, and this is where the two meet.
+ *
+ * A discovered app's method name is its platform IDENTITY — for an org component that is the
+ * qualified ref `<org>/<name>` (UNOVERSE_COMPONENT_ORGS.md), because two orgs may ship the
+ * same component name. A slash is legal in an identity and legal in the `unoverse://` address
+ * built from it. It is NOT legal in a model tool name: every vendor with tool calling
+ * constrains the name, and OpenAI rejects the whole request with
+ * `Invalid 'tools[N].name': string does not match pattern '^[a-zA-Z0-9_-]+$'`.
+ *
+ * Observed live 2026-08-24, on two universes and two orgs: an agent discovered an org
+ * component app, minted it as its sixth tool, and every turn after the discovery 400'd. Turn
+ * one had passed, because the static service methods are manifest-authored and never carry
+ * an org — only a DISCOVERED app arrives org-qualified.
+ *
+ * REPLACE THE SEPARATOR, NEVER DROP THE ORG. Stripping the prefix would produce a legal name
+ * and reintroduce exactly the collision the qualified ref exists to prevent: two orgs shipping
+ * `journey-finder` into one conversation would mint one tool name twice, and `live`'s dedupe
+ * (toolloop) would silently keep whichever landed first. Substituting the illegal character
+ * keeps the name unique and keeps the org readable to the model.
+ *
+ * THE NAME IS ALSO THE ROUTE BACK. `toolBridge` keys `appInvokers` by the minted name and the
+ * invoker closes over the original `mcp`, so the sanitised name round-trips to the right app
+ * without a reverse lookup. Anything unminted falls through to `api.callService`, which is
+ * addressed by service method names that never carry an org.
+ */
+export function modelToolName(identity: string): string {
+  return String(identity).replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+
+/** Mint the model-facing tool definition for a discovered MCP. */
+export function toolDefFromDiscoveredMCP(mcp: DiscoveredMCP): AgentToolDef {
+  const methodDef = mcp.schema?.methods?.[mcp.methodName];
+  return {
+    name: modelToolName(mcp.methodName),
+    description: methodDef?.description || mcp.description || mcp.title,
+    parameters: methodDef?.input || { type: "object", properties: { message: { type: "string" } } },
+  };
+}
+
+/**
+ * Mint the model-facing tool definition, pulling a component app's schema LIVE.
+ *
+ * NATIVE MCP, no copies: a path-B app row carries only its `appUri` — the schema is a
+ * `resources/read` of `<appUri>/schema` on the platform server, compiled fresh from the
+ * definition at read time. Always current (no reconcile), always in document order (a
+ * DB-stored copy can't hold key order), and the same source the server's referee
+ * validates against — schema drift is structurally impossible. Non-app tools (and any
+ * pull failure) fall back to the synchronous mint.
+ */
+export async function resolveToolDefNative(
+  mcp: DiscoveredMCP,
+  ctx: Pick<AppInvocationContext, "accessToken" | "baseUrl">,
+): Promise<AgentToolDef> {
+  if (!isBindinglessComponentApp(mcp) || !mcp.appUri) return toolDefFromDiscoveredMCP(mcp);
+  try {
+    const { client, close } = await connectPlatformMcp(ctx);
+    try {
+      const res = (await client.readResource({ uri: `${mcp.appUri}/schema` })) as {
+        contents?: Array<{ text?: string }>;
+      };
+      const contract = JSON.parse(res.contents?.[0]?.text ?? "{}") as {
+        description?: string;
+        inputSchema?: Record<string, unknown> | null;
+      };
+      if (!contract.inputSchema) return toolDefFromDiscoveredMCP(mcp); // not briefed — generic contract
+      // A BRIEFED schema carries the composer directive in its top-level description.
+      // Models read TOOL descriptions far more reliably than schema descriptions —
+      // surface it there too, so the briefed tool self-instructs at both levels.
+      const directive = typeof contract.inputSchema.description === "string" ? ` ${contract.inputSchema.description}` : "";
+      return {
+        name: modelToolName(mcp.methodName),
+        description: `${contract.description || mcp.title || mcp.methodName}${directive} ${APP_ETIQUETTE}`,
+        parameters: contract.inputSchema,
+      };
+    } finally {
+      await close();
+    }
+  } catch {
+    return toolDefFromDiscoveredMCP(mcp);
+  }
+}
+
+/**
+ * A bindingless component app (path B): a `component` app-tool id and NO workflow. The
+ * adapter routes it to `invokeComponentAppNative` (held `/mcp` call) instead of firing.
+ */
+export function isBindinglessComponentApp(mcp: DiscoveredMCP): boolean {
+  return !!mcp.component && !mcp.workflowId;
+}
+
+/**
+ * The ONE component-app adapter every agent family wires for a discovered bindingless
+ * component app (path B). MCP-NATIVE by design: the tool's schema is the instruction
+ * channel — for a BRIEFED component it was compiled from the definition's `brief` tags
+ * (server briefSchema → registry metadata.inputSchema → the minted tool), so the model
+ * hydrates real fields, not a prose protocol. This closure is the composer's APPLY half:
+ * every arg beyond `message` IS that hydrated content and forwards as `props`, which the
+ * platform MCP server seeds into the rendered component's state. Non-briefed apps carry
+ * only `message` — behavior unchanged.
+ *
+ * Agent families should wire exactly:
+ *   `service[methodName] = componentAppInvoker(mcp, identity)`
+ * and never hand-roll the arg mapping again.
+ */
+export function componentAppInvoker(
+  mcp: DiscoveredMCP,
+  identity: Pick<AppInvocationContext, "conversationId" | "userId" | "chatId" | "accessToken">,
+): (input: unknown) => ReturnType<typeof invokeComponentAppNative> {
+  const toolId = mcp.component as string;
+  return (input: unknown) => {
+    const { message, ...hydrated } = (input ?? {}) as Record<string, unknown>;
+    return invokeComponentAppNative(toolId, {
+      conversationId: identity.conversationId,
+      userId: identity.userId,
+      accessToken: identity.accessToken,
+      chatId: identity.chatId,
+      message: typeof message === "string" ? message : "",
+      ...(Object.keys(hydrated).length ? { props: hydrated } : {}),
+    });
+  };
+}
+
+/** Context a held app call needs to reach the human on the live session. */

package/vendor/base/src/agent-mcp/types.ts

@@ -0,0 +1,130 @@
+/**
+ * The shapes the harness passes around. No behaviour, so every other file here can import
+ * it without importing anything else.
+ */
+
+/**
+ * AGENT MCP HARNESS — the model-agnostic half of a conversational agent's tool loop.
+ *
+ * Every agent family (OpenAI, GLM, Grok, …) shares the SAME platform behavior:
+ *   - which spatial-search results become callable tools (node-MCP rows + Unoverse
+ *     app rows carrying the manifest call contract),
+ *   - how an interactive APP tool presents itself to the model (the etiquette lives
+ *     in the tool DESCRIPTION — the only channel that reaches a model for a tool
+ *     minted MID-conversation; instructions are built once at loop start),
+ *   - when a tool call ENDS the agent's turn (provenance + result shape, never a
+ *     hardcoded name list).
+ *
+ * This module is that behavior, once — `@unoverse-platform/base/agent-mcp`.
+ * Agent families keep only their streaming adapters (wire shapes, chunk handling,
+ * token accounting) and map their tool-call objects into `AgentToolExchange` to
+ * consume it. Fixes land here and reach every family — the previous state
+ * (openai-only, GLM unable to discover apps at all, Grok forked) is exactly what
+ * this exists to prevent. A conformance guard fails the build if an agent family
+ * re-implements this logic instead of importing it.
+ *
+ * THE ONE-WIRE-CALL RULE — where our code ends and native MCP begins. Everything here
+ * is pure interpretation/routing and never touches the MCP wire, EXCEPT
+ * `invokeComponentAppNative` — the single function that opens an MCP client and makes a
+ * real `tools/call`. From that call onward it is all native MCP (the server renders +
+ * elicits; the answers resolve the call). Node-MCP rows and path-A workflow apps route
+ * in-process via the caller's `api.callService` because they have a node/workflow to run;
+ * only path-B component apps (nothing local to call) ride the wire. Full map:
+ * docs/MCP_COMPLETE_GUIDE.md → "where YOUR code ends and native MCP begins".
+ */
+
+/** One executed tool call, reduced to what the harness needs: its name and the
+ *  raw result content string the model will see. */
+export interface AgentToolExchange {
+  name: string;
+  resultContent: string;
+}
+
+/** A spatial-discovered MCP, normalized: node-MCP rows and Unoverse app rows both
+ *  come out in this shape, ready to mint as a model tool via `toolDefFromDiscoveredMCP`. */
+export interface DiscoveredMCP {
+  id: string;
+  title: string;
+  description: string;
+  workflowId: string;
+  nodeId: string;
+  methodName: string;
+  /** Full method schema ({ methods: { [name]: { description, input } } }). */
+  schema?: any;
+  /**
+   * PATH B (UNOVERSE_MCP_APP_PROTOCOL §0.1 / §4b): a self-contained component app —
+   * an `app` URI but NO workflow. Holds the app-tool id the adapter hands to
+   * `invokeComponentAppNative` (the held native `/mcp` call) instead of firing
+   * `workflow@trigger`; `workflowId`/`nodeId` are empty. Undefined for node-MCP + path-A apps.
+   */
+  component?: string;
+  /** PATH B: the app's resource URI (`unoverse://components/[<org>/]<name>`) — the ONLY
+   *  schema handle. The tool's input schema is read LIVE from `<appUri>/schema` at mint
+   *  time (`resolveToolDefNative`); spatial rows carry no schema copy. */
+  appUri?: string;
+}
+
+/** A neutral function-tool definition; each family maps this to its wire format. */
+export interface AgentToolDef {
+  name: string;
+  description: string;
+  parameters: Record<string, unknown>;
+}
+
+/** Mint the model-facing tool definition for a discovered MCP. */
+
+/** Context a held app call needs to reach the human on the live session. */
+export interface AppInvocationContext {
+  /** The caller's stream session — where the wizard renders and elicitation is answered. */
+  conversationId?: string;
+  userId?: string;
+  /** The current TURN id — the component renders in this turn's bubble. */
+  chatId?: string;
+  /** Seeds the elicitation prompt; the app tool schema requires the field (may be ""). */
+  message?: string;
+  /** Content-tree app rows: the row's content, seeded as-is into the component's state. */
+  props?: Record<string, unknown>;
+  /** Content-tree app rows: the ROW id — keys the render `<component>:<instanceId>` so multiple rows sharing a component don't collide. */
+  instanceId?: string;
+  /** These props are ROW DATA, not a model's composition — skip the brief referee. */
+  fromRow?: boolean;
+  /** The delivery batch this render belongs to (UNOVERSE_TEMPLATE_MODEL §12e): the
+   *  server's director judges the WHOLE batch before anything renders. `size` is how
+   *  many siblings to wait for; `index` is this render's arrival position. */
+  batch?: { id: string; size: number; index: number };
+  /** Forwarded as a Bearer token so the internal `/mcp` call rides the gated lane too. */
+  accessToken?: string;
+  /** Internal MCP base; defaults to UNOVERSE_SERVICE_URL or http://localhost:4106. */
+  baseUrl?: string;
+}
+
+/**
+ * NATIVE MCP APP INVOCATION (UNOVERSE_MCP_APP_PROTOCOL §3.3 / §4b) — the held
+ * slow-call that renders a component app and returns the user's submitted answers to
+ * the CALLING model.
+ *
+ * A bindingless component app has no workflow to fire. Calling it is ONE held
+ * `tools/call` to the platform's internal MCP server (`/mcp`): the server registered the
+ * app as a tool (mcpServer `listApps()`), renders the component on the caller's live
+ * session and ELICITS its declared `outputs` block, then resolves the call with
+ * `{ output }`. No polling and no timeout by design — an abandoned form is a tool call
+ * that never returns (the SDK's 60s default is lifted to 24h). The answers come back as
+ * the tool result so the model continues in-turn.
+ *
+ * This is the modern replacement for the legacy engine's
+ * `MCPInvoker.awaitAppOutputNative`: same native slow-call, but driven from this shared
+ * harness (every agent family) using the app id it parsed at mint time — so it needs NO
+ * server-side (XState) schema cache.
+ */
+/** Open an MCP client on the platform's internal `/mcp` — the ONE wire-connect shared by
+ *  every native call this harness makes (app invocation, live schema read). */
+
+/** A content-tree row's attached COMPONENT, ready to render — see rowComponentsFromResults. */
+export interface RowComponent {
+  /** The row's identity — dedupe key (one render per row, ever). */
+  id: string;
+  /** The component app-tool id (`unoverse://components/<id>` → `<id>`). */
+  component: string;
+  /** The row's content AS-IS — the component's state (binds resolve by name). */
+  props: Record<string, unknown>;
+}