@unoverse-platform/studio 0.1.89 → 0.1.91

package/local/plugin.ts

@@ -18,7 +18,7 @@
 import { designHome } from "./design-home.mjs";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
-import { resolve } from "path";
+import { resolve, dirname } from "path";
 import { readdirSync, existsSync, readFileSync, statSync } from "fs";
 import type { Plugin, ViteDevServer } from "vite";
 import { findProjectRoot, loadCatalog } from "./catalog.js";
@@ -187,19 +187,27 @@ export function localStudioHost(): Plugin {
        * The loaders live in `@unoverse-platform/base`. Studio reuses them rather than
        * growing a second implementation that would drift.
        *
-       * RESOLVED THROUGH NODE, not by walking the tree. This used to be
-       * `resolve(root, "../unoverse/server/src")`, which was two problems in one: it
-       * reached into another app's source, so Studio could never be published, and it
-       * silently broke the moment those files moved into `base` — the paths pointed at
-       * nothing and no test covered the path.
+       * TWO PLACES, IN THIS ORDER. In the monorepo base is a workspace package and Node
+       * finds it, so edits to packages/base are live while developing. In a published
+       * Studio there is no such package to find: base left npm on 2026-09-03 (it ships
+       * inside the core image instead — `UNOVERSE_BASE_BOUNDARY.md` §1a), so its source is
+       * frozen into `vendor/base/src` at pack time by scripts/vendor-base.mjs.
        *
-       * Asking Node where the package is means it works from a checkout OR from
-       * node_modules, which is what makes standalone Studio possible.
+       * The earlier version of this resolved ONLY through Node, which was right while base
+       * was installable and became a crash the moment it was not. Before that it was
+       * `resolve(root, "../unoverse/server/src")`, reaching into another app's source, which
+       * is what kept Studio from being publishable at all.
        */
-      baseSrc = resolve(
-        createRequire(import.meta.url).resolve("@unoverse-platform/base/package.json"),
-        "../src",
-      );
+      const vendored = resolve(dirname(fileURLToPath(import.meta.url)), "../vendor/base/src");
+      try {
+        baseSrc = resolve(
+          createRequire(import.meta.url).resolve("@unoverse-platform/base/package.json"),
+          "../src",
+        );
+      } catch {
+        baseSrc = vendored;
+      }
+      if (!existsSync(baseSrc)) baseSrc = vendored;
 
       const ssr = (id: string) => server.ssrLoadModule(id) as Promise<Record<string, unknown>>;
       const catalog = loadCatalog(baseSrc, ssr, projectRoot);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unoverse-platform/studio",
-  "version": "0.1.89",
+  "version": "0.1.91",
   "type": "module",
   "description": "Unoverse Studio: the local authoring app. Reads your own rx/ folder, no backend.",
   "scripts": {
@@ -8,9 +8,11 @@
     "build": "vite build",
     "preview": "vite preview",
     "typecheck": "tsc --noEmit",
-    "prepack": "node scripts/vendor-sdk.mjs"
+    "prepack": "node scripts/vendor-sdk.mjs && node scripts/vendor-base.mjs"
   },
   "dependencies": {
+    "@aws-crypto/sha256-js": "^5.2.0",
+    "@aws-sdk/util-dynamodb": "^3.996.7",
     "@cfworker/json-schema": "^4.1.1",
     "@codemirror/autocomplete": "^6.18.6",
     "@codemirror/commands": "^6.8.1",
@@ -25,10 +27,17 @@
     "@codemirror/theme-one-dark": "^6.1.2",
     "@codemirror/view": "^6.37.1",
     "@modelcontextprotocol/sdk": "^1.25.1",
+    "@smithy/protocol-http": "^5.5.14",
+    "@smithy/signature-v4": "^5.6.10",
     "@tailwindcss/vite": "^4.0.0",
-    "@unoverse-platform/base": "^0.3.37",
     "@unoverse-platform/marketplace": "*",
     "@vitejs/plugin-react": "^4.3.4",
+    "acorn": "^8.17.0",
+    "fast-memoize": "^2.5.2",
+    "fast-xml-parser": "^5.2.5",
+    "handlebars": "^4.7.8",
+    "ioredis": "^5.3.0",
+    "lucide": "^1.21.0",
     "lucide-react": "^0.546.0",
     "markdown-to-jsx": "^7.7.17",
     "oidc-client-ts": "^3.4.1",
@@ -37,6 +46,7 @@
     "react-oidc-context": "^3.1.0",
     "tailwindcss": "^4.0.0",
     "vite": "^6.0.0",
+    "ws": "^8.18.0",
     "yaml": "^2.4.0"
   },
   "license": "MIT",

package/screens/TemplatesLibraryView.tsx

@@ -23,7 +23,8 @@ import { NAV, SCREEN, navItem } from "./chrome";
 
 interface TemplateSection {
   /** static = placed as designed; copywriter = written into through its briefs;
-   *  director = decided from what streams in (§9b, the three words). */
+   *  director = the judge: a search place (with `component`) or a delivery band
+   *  (without) — one word since 2026-09-02 (§9b + §9e). */
   kind: "static" | "copywriter" | "director";
   /** The state instances render in at this section — what the claim matches. */
   face: string;
@@ -36,9 +37,15 @@ interface TemplateSection {
    *  previews as written and filled rather than as a page of ghosts. */
   seeds?: Record<string, Record<string, unknown>>;
   state?: string;
-  limit?: number;
   rules?: string;
   preview?: string[];
+  /** Director places (§9e): the grammar, echoed for the dock table. `ask` appears
+   *  only after derivation (rule 10d) — never authored. */
+  ask?: string;
+  type?: "discovery" | "intent";
+  include?: string[];
+  pick?: number;
+  items?: { min: number; max: number };
 }
 interface TemplateDef {
   name: string;
@@ -73,13 +80,26 @@ const refOf = (t: TemplateDef) => (t.org ? `${t.org}/${t.name}` : t.name);
 
 /** One section's description for the dock table — the three words (§9b). */
 function sectionLabel(sec: TemplateSection): { name: string; filler: string; rules: string } {
+  // ONE WORD, TWO MODES (§9e, 2026-09-02): with `component` = a search place; without =
+  // a delivery band. Both show as the director's — the judge is the same.
+  if (sec.kind === "director" && sec.component)
+    return {
+      name: sec.component,
+      filler: "director",
+      rules: [
+        sec.items ? `items ${sec.items.min}–${sec.items.max}` : null,
+        sec.type ?? null,
+        sec.include?.length ? sec.include.join("+") : null,
+        sec.pick != null ? `pick ${sec.pick}` : null,
+      ].filter(Boolean).join(" · "),
+    };
   if (sec.kind === "director")
     return {
       name: "director",
       filler: "director",
       rules: [
         sec.state ? `state ${sec.state}` : null,
-        sec.limit != null ? `limit ${sec.limit}` : null,
+        sec.pick != null ? `pick ${sec.pick}` : null,
         sec.rules ?? null,
       ].filter(Boolean).join(" · "),
     };
@@ -151,11 +171,16 @@ export function TemplatesLibraryView({ theme, org }: { theme: ResolvedTheme; org
     const secs = (base && current?.sections?.[base]) || [];
     const out: { nodeId: string; ref: string; face?: string; framed: boolean; seed?: Record<string, unknown> }[] = [];
     for (const sec of secs) {
-      if (sec.kind === "director") {
+      // ONE word, two modes (§9e rule 10b, 2026-09-02): a director WITH a component is a
+      // SEARCH place — its mock is its own component's preview, seeded exactly like a
+      // linked part. Only the BAND form (no ref) seeds stand-ins. This branch predates
+      // the merge and read every director as a band, so search places seeded nothing and
+      // the template previewed with those sections simply missing.
+      if (sec.ref) {
+        out.push({ nodeId: `${sec.face}~${sec.ref}`, ref: sec.ref, face: sec.face, framed: true, seed: sec.seeds?.[sec.ref] });
+      } else if (sec.kind === "director") {
         for (const [i, ref] of (sec.preview ?? []).entries())
           out.push({ nodeId: `${sec.face}~${ref}~${i}`, ref, face: sec.face, framed: false, seed: sec.seeds?.[ref] });
-      } else if (sec.ref) {
-        out.push({ nodeId: `${sec.face}~${sec.ref}`, ref: sec.ref, face: sec.face, framed: true, seed: sec.seeds?.[sec.ref] });
       }
     }
     return out;

package/screens/TemplatesView.tsx

@@ -590,7 +590,7 @@ export function TemplatesView({
     const base = d.defaultLayout ?? Object.keys(d.layouts ?? {})[0];
     const out: { ref: string; face: string; props: Record<string, unknown> }[] = [];
     for (const sec of (base && d.sections?.[base]) || []) {
-      const refs = sec.kind === "director" ? (sec.preview ?? []) : sec.ref ? [sec.ref] : [];
+      const refs = sec.ref ? [sec.ref] : sec.kind === "director" ? (sec.preview ?? []) : [];
       for (const ref of refs) out.push({ ref, face: sec.face, props: sec.seeds?.[ref] ?? {} });
     }
     return out;

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

@@ -0,0 +1,203 @@
+/**
+ * WHAT SPATIAL FOUND, AND WHAT IT UNLOCKS.
+ *
+ * Reading `object_type: "mcp"` rows out of a discovery result and normalising three row
+ * kinds into one shape, so a model gets one tool per row regardless of which kind it was.
+ * Also the etiquette an interactive app carries, and the anchoring a follow-up search needs.
+ */
+import type { AgentToolExchange, DiscoveredMCP, AppInvocationContext } from "./types.js";
+
+/** The discovery tools whose results can carry `object_type: "mcp"` rows. */
+export const DISCOVERY_TOOL_NAMES: readonly string[] = ["findIntent", "discoverRelated"];
+
+import { parseToolResult } from "./handoff.js";
+import { componentTypeFromAppUri } from "./rowComponents.js";
+import { isBindinglessComponentApp } from "./tools.js";
+import { leanToolResultForModel } from "./lean.js";
+
+/**
+ * Extract discovered MCPs from discovery-tool results (`object_type: "mcp"` rows).
+ *
+ * Three row kinds, all minted as one model tool:
+ *   - node-MCP rows: carry a registered `metadata.schema.methods`.
+ *   - Path A — workflow-bound app rows (UNOVERSE_MCP_APP_PROTOCOL §4b): no schema —
+ *     the app IS the tool, minted from the manifest call contract (name + inputSchema);
+ *     calling it fires `workflow@trigger`.
+ *   - Path B — bindingless component-app rows (§0.1): an `app` URI but NO workflow. The
+ *     app IS the tool; calling it makes the held native `/mcp` call
+ *     (`invokeComponentAppNative`) — the SERVER renders the component + elicits, nothing
+ *     to fire. Carries `component` (the app-tool id) instead of workflow/trigger.
+ *
+ * Path B also covers CONTENT-TREE rows (object_type "service"/"need") with an app
+ * ATTACHED (`metadata.app: "unoverse://components/<id>"`): a promoted service reacts
+ * exactly like a discovered component app — the manifest's `defaultState` decides the
+ * render (inline card, focus, …). These rows carry no `metadata.name`, so the tool is
+ * minted under the component id and deduped across rows pointing at the same app.
+ *
+ * App descriptions gain the INTERACTIVE-APP etiquette so the model promotes the UI
+ * instead of answering alongside it (observed live: a full interview streamed next to
+ * the wizard asking the same questions).
+ */
+export const APP_ETIQUETTE =
+  "INTERACTIVE APP: calling this renders a UI the user " +
+  "completes on screen. When you call it, reply with at most ONE short sentence inviting the user to it — " +
+  "never answer the request in text alongside it, never list options, never ask questions the app will " +
+  "collect. If the result includes `output`, those are the user's complete answers — continue the task " +
+  "with them (search if the request needs a lookup) and only then answer. " +
+  "If your instructions include background about this user, every text field you compose here is written " +
+  "FOR that person — use their name and what you know about them in headlines, intros, and copy; " +
+  "generic audience-neutral brochure copy is wrong when you know who is reading.";
+
+
+export function parseDiscoveredMCPs(calls: AgentToolExchange[]): DiscoveredMCP[] {
+  const discovered: DiscoveredMCP[] = [];
+  for (const call of calls) {
+    if (!DISCOVERY_TOOL_NAMES.includes(call.name)) continue;
+    // The spatial search tools return `{ count, results, queryPoint }` — the items live
+    // under `.results`. (Some callers/older shapes hand back a bare array.) Accept both,
+    // else nothing is ever discovered (the object isn't an array → the loop is skipped).
+    const parsed = parseToolResult(call.resultContent);
+    const results = Array.isArray(parsed) ? parsed : Array.isArray(parsed?.results) ? parsed.results : null;
+    if (!results) continue;
+    for (const item of results) {
+      if (item?.object_type !== "mcp") continue;
+      if (item.metadata?.schema?.methods) {
+        const methodName = Object.keys(item.metadata.schema.methods)[0];
+        if (!methodName) continue;
+        discovered.push({
+          id: item.id || item.universal_id,
+          title: item.title || "",
+          description: item.description || "",
+          workflowId: item.metadata?.workflowId || item.workflow_id,
+          nodeId: item.metadata?.nodeId,
+          methodName,
+          schema: item.metadata?.schema,
+        });
+      } else if (item.metadata?.workflow && item.metadata?.trigger) {
+        // PATH A — workflow-bound app: calling it fires workflow@trigger.
+        const methodName = item.metadata.name;
+        if (!methodName) continue;
+        const input = item.metadata.inputSchema || { type: "object", properties: { message: { type: "string" } } };
+        const appDescription = `${item.description || item.title || methodName} ${APP_ETIQUETTE}`;
+        discovered.push({
+          id: item.id || item.universal_id,
+          title: item.title || "",
+          description: appDescription,
+          workflowId: item.metadata.workflow || item.workflow_id,
+          nodeId: item.metadata.trigger,
+          methodName,
+          schema: { methods: { [methodName]: { description: appDescription, input } } },
+        });
+      } else if (item.metadata?.app && !item.metadata?.workflow) {
+        // PATH B — bindingless component app: no workflow. Minted like an app tool; the
+        // adapter passes `component` to `invokeComponentAppNative` (held native `/mcp`
+        // call → the SERVER renders + elicits) instead of firing. The row carries NO
+        // schema — the input schema is pulled LIVE from `<appUri>/schema` at mint time
+        // (`resolveToolDefNative`); this default is the un-briefed fallback only.
+        const methodName = item.metadata.name;
+        if (!methodName) continue;
+        const input = { type: "object", properties: {} };
+        const appDescription = `${item.description || item.title || methodName} ${APP_ETIQUETTE}`;
+        discovered.push({
+          id: item.id || item.universal_id,
+          title: item.title || "",
+          description: appDescription,
+          workflowId: "",
+          nodeId: "",
+          methodName,
+          component: componentTypeFromAppUri(item.metadata.app),
+          appUri: String(item.metadata.app),
+          schema: { methods: { [methodName]: { description: appDescription, input } } },
+        });
+      }
+    }
+  }
+  return discovered;
+}
+
+/** A content-tree row's attached card, ready to render — see parseRowComponents. */
+
+/**
+ * THE ONE DISCOVERY ABSORBER — what EVERY agent family does with a discovery tool's
+ * result, in one place (never re-implemented in an adapter):
+ *   1. UNLOCK: each discovered component app's tool joins `discoveredApps` — the set a
+ *      native MCP attachment's `toolFilter` reads, so the app appears in the model's
+ *      next `tools/list` (spatial selects; MCP serves).
+ *   2. LEAN: returns the model-facing projection of the rows (full cargo was already
+ *      consumed by the card lane and this unlock pass; raw rows cost ~100k tokens).
+ * Non-discovery results pass through untouched.
+ *
+ * DISCOVERY NEVER CALLS THE APP. Finding a component in search results is not someone
+ * asking for it; only the model's own tool call is. Two fire-and-forget calls lived here
+ * (a shell-open on unlock, a draft top-up when a later search carried images) to paint a
+ * composed page's frame early. Both were `invokeComponentAppNative`, so on an app whose
+ * component declares `outputs` each one rendered the component AND opened its own
+ * elicitation: observed live 2026-08-10, three renders and three concurrent forms in ONE
+ * turn, of which the channel can hold only one (connection.tsx keeps a single pending
+ * resolver). Native MCP is one call, one render, one elicitation, answers back to the
+ * model (MCP_TEMPLATE_PROTOCOL §3.3). An early frame, if wanted again, cannot be an app
+ * invocation.
+ *
+ * `onAppUnlocked` — fired ONCE per newly-unlocked path-B app, and AWAITED before the lean
+ * result returns. A family that mints its own SDK tool per app (rather than exposing them
+ * through a native MCP attachment's `toolFilter`) wires the mint here: parsing + dedup stay
+ * in this one absorber, and the tool is registered before the model's next turn reads it.
+ */
+export async function handleDiscoveryResult(
+  toolName: string,
+  resultContent: string,
+  discoveredApps: Set<string>,
+  identity: Pick<AppInvocationContext, "conversationId" | "userId" | "chatId" | "accessToken">,
+  log?: (msg: string) => void,
+  onAppUnlocked?: (mcp: DiscoveredMCP) => Promise<void> | void,
+): Promise<string> {
+  if (!DISCOVERY_TOOL_NAMES.includes(toolName)) return resultContent;
+  for (const mcp of parseDiscoveredMCPs([{ name: toolName, resultContent }])) {
+    if (isBindinglessComponentApp(mcp) && mcp.component && !discoveredApps.has(mcp.component)) {
+      discoveredApps.add(mcp.component);
+      log?.(`🔓 App tool unlocked: ${mcp.component}`);
+      if (onAppUnlocked) await onAppUnlocked(mcp);
+    }
+  }
+  return leanToolResultForModel(resultContent);
+}
+
+/**
+ * THE SKILLS THE SEARCH SAID ARE IN FORCE where this query landed.
+ *
+ * The engine resolves them: a query anchors on the map, the point is inside a region or it
+ * is not, and that region's attached skills ride back on the search envelope. Nothing here
+ * decides anything — this only lifts them out before `leanToolResultForModel` drops the key,
+ * which it does because the model must never receive a skill as a TOOL RESULT. A tool result
+ * is an item in the conversation and items cannot be removed; the whole point of loading a
+ * skill this way is that it can be dropped again by simply not sending it.
+ *
+ * NULL AND EMPTY ARE DIFFERENT ANSWERS, and the difference is the whole contract. `null`
+ * means this reply said nothing about where the conversation is (not a placement search, or
+ * it failed) — leave whatever is in force alone. `[]` means it WAS placed and nothing
+ * applies there: unassigned ground, or a region nobody attached a skill to. That is an
+ * instruction to clear, not an absence of news.
+ */
+export function parseRegionSkills(resultContent: string): LoadedRegionSkill[] | null {
+  try {
+    const parsed = JSON.parse(resultContent);
+    const skills = parsed?.regionSkills;
+    if (!Array.isArray(skills)) return null;
+    return skills.filter((s: any) => s?.name && s?.instructions);
+  } catch {
+    return null;
+  }
+}
+
+export interface LoadedRegionSkill {
+  name: string;
+  title?: string;
+  instructions: string;
+  regionId?: string;
+  regionName?: string | null;
+  depth?: number;
+  /** How long the engine took to resolve it, for the timeline bar. */
+  ms?: number;
+}
+
+/** A neutral function-tool definition; each family maps this to its wire format. */

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

@@ -0,0 +1,56 @@
+/**
+ * DOES THIS TOOL CALL END THE TURN?
+ *
+ * Decided by PROVENANCE and RESULT SHAPE, never by a hardcoded list of tool names. A tool
+ * wired in up front keeps the conversation going; one spatial surfaced mid-loop is a handoff
+ * candidate, and whether it actually ends the turn depends on what came back.
+ */
+import type { AgentToolExchange } from "./types.js";
+
+/** Parse a tool result content string to JSON; non-JSON comes back verbatim. */
+export function parseToolResult(content: string): any {
+  try {
+    return JSON.parse(content || "{}");
+  } catch {
+    return content;
+  }
+}
+
+/**
+ * Whether any tool call is a dynamically-discovered workflow handoff.
+ *
+ * Provenance, not a hardcoded name list: a tool keeps the conversation going if it
+ * was wired in up front (`coreToolNames`, the getSchema set — SpatialSearch, memory,
+ * connector MCPs). Only tools spatial surfaced mid-loop are handoff candidates.
+ * With no wired-tool info we can't identify a handoff, so we keep going.
+ */
+export function hasDynamicHandoff(toolNames: string[], coreToolNames?: Set<string>): boolean {
+  if (!coreToolNames || coreToolNames.size === 0) return false;
+  return toolNames.some((name) => !coreToolNames.has(name));
+}
+
+/**
+ * Whether this batch of tool calls ENDS the agent's turn.
+ *
+ * Refined by RESULT shape: a dynamically-discovered tool whose result carries
+ * `output` (or an explicit completed/error status) is an interactive app's SLOW
+ * CALL — the user completed it and the answers ARE the result; the conversation
+ * CONTINUES with them. Only the fire-and-forget handoff signature
+ * ({ status: "started" } / unparseable) ends the turn.
+ */
+export function isTurnEndingHandoff(calls: AgentToolExchange[], coreToolNames?: Set<string>): boolean {
+  if (
+    !hasDynamicHandoff(
+      calls.map((c) => c.name),
+      coreToolNames,
+    )
+  ) {
+    return false;
+  }
+  return calls.some((c) => {
+    if (coreToolNames?.has(c.name)) return false;
+    const res = parseToolResult(c.resultContent);
+    if (res && typeof res === "object" && (res.output || res.status === "completed" || res.status === "error")) return false;
+    return true;
+  });
+}

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

@@ -0,0 +1,44 @@
+/**
+ * AGENT MCP HARNESS — the model-agnostic half of a conversational agent's tool loop.
+ *
+ * Every agent family (OpenAI, GLM, Grok, …) shares the SAME platform behaviour: which
+ * spatial-search results become callable tools, how an interactive app presents itself to
+ * the model, and when a tool call ENDS the agent's turn. This folder is that behaviour,
+ * once. 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 state this exists to prevent was real:
+ * OpenAI-only, GLM unable to discover apps at all, Grok forked. A conformance guard fails
+ * the build if a family re-implements any of it.
+ *
+ * THIS FILE IS THE PUBLIC SURFACE and nothing else. The harness was one 823-line module;
+ * it is now split by JOB, the same way `manifests/runtime/` is, so a reader looking for how
+ * a turn ends is not scrolling past row-component rendering to find it.
+ *
+ *   types       the shapes, no behaviour
+ *   handoff     does this call end the turn?
+ *   discovery   what spatial found, and what it unlocks
+ *   rowComponents  rows that name a component, rendered rather than described
+ *   lean        projecting a result down to what the model needs
+ *   tools       minting a model tool from a discovered app
+ *   invoke      THE ONE WIRE CALL, where our code ends and native MCP begins
+ *   memory*     conversation ingest and user-memory hydration
+ */
+
+export type {
+  AgentToolExchange,
+  DiscoveredMCP,
+  RowComponent,
+  AgentToolDef,
+  AppInvocationContext,
+} from "./types.js";
+
+export { DISCOVERY_TOOL_NAMES, APP_ETIQUETTE, parseDiscoveredMCPs, handleDiscoveryResult, parseRegionSkills, type LoadedRegionSkill } from "./discovery.js";
+export { parseToolResult, hasDynamicHandoff, isTurnEndingHandoff } from "./handoff.js";
+export { rowComponentsFromResults, renderRowComponents, rankedRowIds, componentTypeFromAppUri, onEmptyRowDelivery } from "./rowComponents.js";
+export { leanToolResultForModel } from "./lean.js";
+export { toolDefFromDiscoveredMCP, resolveToolDefNative, isBindinglessComponentApp, componentAppInvoker, modelToolName } from "./tools.js";
+export { invokeComponentAppNative, connectPlatformMcp } from "./invoke.js";
+
+export { ingestConversationTurn, type ConversationTurn } from "./memoryIngest.js";
+export { fetchUserMemoryContext, hydratePromptWithUserMemory } from "./memoryContext.js";

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

@@ -0,0 +1,140 @@
+/**
+ * THE ONE WIRE CALL. Where our code ends and native MCP begins.
+ *
+ * Everything else in this folder is interpretation and routing that never touches the MCP
+ * wire. This is the exception: `invokeComponentAppNative` opens a client and makes a real
+ * `tools/call`. From there the server renders, elicits, and its answers resolve the call.
+ *
+ * Node-MCP rows and path-A workflow apps do NOT come through here — they route in-process
+ * via the caller's `api.callService`, because they have a node or a workflow to run. Only a
+ * path-B component app, with nothing local to call, rides the wire.
+ */
+import type { AppInvocationContext, DiscoveredMCP } from "./types.js";
+
+/**
+ * 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). */
+export async function connectPlatformMcp(
+  ctx: Pick<AppInvocationContext, "accessToken" | "baseUrl">,
+): Promise<{ client: any; close: () => Promise<void> }> {
+  const { Client } = await import("@modelcontextprotocol/sdk/client/index.js");
+  const { StreamableHTTPClientTransport } = await import("@modelcontextprotocol/sdk/client/streamableHttp.js");
+
+  const base = (ctx.baseUrl || process.env.UNOVERSE_SERVICE_URL || "http://localhost:4106").replace(/\/$/, "");
+  const accessToken = ctx.accessToken;
+  const authFetch = accessToken
+    ? async (url: string | URL, init?: RequestInit): Promise<Response> => {
+        const headers = new Headers(init?.headers);
+        headers.set("Authorization", `Bearer ${accessToken}`);
+        return fetch(url, { ...init, headers });
+      }
+    : undefined;
+
+  const client = new Client({ name: "unoverse-agent-mcp", version: "1.0.0" });
+  const transport = new StreamableHTTPClientTransport(
+    new URL(`${base}/mcp`),
+    authFetch ? { fetch: authFetch } : undefined,
+  );
+  await client.connect(transport);
+  return { client, close: () => client.close().catch(() => {}) };
+}
+
+export async function invokeComponentAppNative(
+  toolId: string,
+  ctx: AppInvocationContext,
+): Promise<{ status: "completed"; output?: Record<string, unknown>; conversationId?: string; action?: string; message?: string }> {
+  const { client, close } = await connectPlatformMcp(ctx);
+  try {
+    const result = (await client.callTool(
+      {
+        // Org-qualified refs are served as dotted aliases (no "/" in MCP tool names).
+        name: toolId.replace(/\//g, "."),
+        arguments: {
+          message: ctx.message ?? "",
+          ...(ctx.conversationId ? { conversationId: ctx.conversationId } : {}),
+          ...(ctx.userId ? { userId: ctx.userId } : {}),
+          ...(ctx.chatId ? { chatId: ctx.chatId } : {}),
+          ...(ctx.props ? { props: ctx.props } : {}),
+          ...(ctx.instanceId ? { instanceId: ctx.instanceId } : {}),
+          ...(ctx.fromRow ? { fromRow: true } : {}),
+          ...(ctx.batch ? { batch: ctx.batch } : {}),
+        },
+      },
+      undefined,
+      // A human is completing the wizard — lift the SDK's 60s default to 24h.
+      { timeout: 24 * 60 * 60 * 1000 },
+    )) as {
+      isError?: boolean;
+      content?: Array<{ type: string; text?: string }>;
+      structuredContent?: { output?: Record<string, unknown>; conversationId?: string; action?: string };
+    };
+    // A handler exception arrives as an isError RESULT, not a rejection — surface it, or a
+    // broken run masquerades as "completed with no output".
+    if (result.isError) {
+      throw new Error(result.content?.find((c) => c.type === "text")?.text || `${toolId} app tool call failed`);
+    }
+    const output = result.structuredContent?.output;
+    const resultText = result.content?.find((c) => c.type === "text")?.text;
+    // BRIEFED component result (output carries `rendered`): the TEXT is the instruction
+    // channel — the referee's "NOT RENDERED — <violations>" correction or the mirror's
+    // "Rendered. The guest now sees this page…" reflection. Pass it through VERBATIM so
+    // the standard tool-retry loop can self-correct / refine. The canned profile guidance
+    // below is for ELICITATION outputs only — substituting it here hid the referee from
+    // the model (observed live: composed args dropped, model told "profile collected").
+    if (output && typeof (output as { rendered?: unknown }).rendered === "boolean") {
+      return {
+        status: "completed",
+        output,
+        conversationId: result.structuredContent?.conversationId,
+        action: result.structuredContent?.action,
+        ...(resultText ? { message: resultText } : {}),
+      };
+    }
+    return {
+      // The held call RESOLVED — mark it completed so `isTurnEndingHandoff` keeps the
+      // conversation going. Without this, a display-only app (no `outputs` block, e.g. a
+      // showcase card) returns { app, conversationId } — the fire-and-forget handoff
+      // signature — and the loop SILENTLY ENDS THE TURN right after the render (observed
+      // live: card streamed in, then no follow-up text, twice).
+      status: "completed",
+      output,
+      conversationId: result.structuredContent?.conversationId,
+      action: result.structuredContent?.action,
+      // Tell the calling model what the output MEANS and that the task is NOT done yet.
+      // Without this the model summarises the answers and stops instead of using them —
+      // observed live: it returned a generic reply and never re-searched (iteration with
+      // toolCalls:0). The legacy MCPInvoker returned this same guidance; dropping it in the
+      // de-fork is why "the model does nothing with the answers". Restores the behaviour.
+      ...(output && Object.keys(output).length
+        ? {
+            message:
+              "`output` is the user's complete profile collected by the app — do NOT ask for any of these values again. The user's request is NOT yet fulfilled: any earlier search predates these answers. Search NOW with a query built from this profile and recommend the specific matches you find.",
+          }
+        : {
+            message:
+              "The component is now displayed on the user's screen. Continue your answer for the user now — the render is a visual aid, not your reply.",
+          }),
+    };
+  } finally {
+    await close();
+  }
+}
+
+// Memory ingest — every agent family saves completed turns the same way.