@unoverse-platform/studio 0.1.89 → 0.1.91

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

@@ -0,0 +1,111 @@
+/**
+ * PROJECTING A RESULT DOWN TO WHAT THE MODEL NEEDS.
+ *
+ * A search result carries far more than the model can use, and everything it does not use
+ * is context it pays for. The full rows are still used for minting tools; this is only what
+ * goes back into the conversation.
+ */
+
+// Model-usable metadata fields — everything the calling LLM has ever actually used from
+// a search row. The RAW rows (full bodyCopy markdown, openGraph, jsonLd, questions,
+// crawl bookkeeping) are for the SERVER side — the card lane and app mint consume them
+// BEFORE this projection is applied — and were costing ~100k tokens per search in the
+// model's thread (observed live: context-window overflow on the first refinement turn).
+const MODEL_METADATA_FIELDS = [
+  "title",
+  "tagline",
+  "shortDescription",
+  "introParagraph",
+  "callToAction",
+  // NO raw image URLs (primaryImage/images): with ref-hydration the model references a
+  // row by universal_id and the SERVER fills the bytes — `hasImage` is all it needs.
+  "app",
+  /**
+   * A NEED's one editorial field: the short verb its page leads with ("Advance Career",
+   * "Explore Jobs", "Check Requirements"). Needs are extracted rather than authored, so they
+   * carry none of the five fields above and reached the model with no metadata at all.
+   *
+   * Here AND in the node's own keep-list, because this projection runs second and drops
+   * whatever it does not name: either half alone is a no-op. `questions` was considered and
+   * left out — four sentences a row is the cost this projection exists to avoid.
+   */
+  "action",
+  "name",
+  "kind",
+  "org",
+  "category",
+  "whenToUse",
+  "section",
+] as const;
+
+/**
+ * LEAN RESULT FOR THE MODEL: project a search-shaped tool result down to the fields the
+ * calling LLM actually uses (title/description/needs/URL/real image URLs/similarity —
+ * and for app rows the discovery meta; the app's input schema already rides the MINTED
+ * TOOL, never re-sent here). Non-search results pass through untouched. Applied AFTER
+ * card rendering and app discovery, which need the full rows.
+ */
+export function leanToolResultForModel(resultContent: string): string {
+  try {
+    const parsed = JSON.parse(resultContent);
+    if (!parsed || !Array.isArray(parsed.results)) return resultContent;
+    const lean = {
+      count: parsed.count,
+      results: parsed.results.map((r: Record<string, any>) => {
+        const m = (r.metadata ?? {}) as Record<string, unknown>;
+        const meta: Record<string, unknown> = {};
+        for (const k of MODEL_METADATA_FIELDS) if (m[k] !== undefined) meta[k] = m[k];
+        // hasImage: precomputed by the node's projection, else derived — the model's
+        // signal that this row can serve as an image REF (it never sees the URL).
+        const hasImage =
+          r.hasImage ??
+          Boolean(
+            (typeof m.primaryImage === "string" && m.primaryImage) ||
+              (Array.isArray(m.images) && m.images.length) ||
+              r.object_type === "image",
+          );
+        return {
+          // The row's HANDLE — hydration refs and follow-up lookups address by this.
+          universal_id: r.universal_id,
+          title: r.title,
+          description: r.description,
+          ...(r.key_need ? { key_need: r.key_need } : {}),
+          object_type: r.object_type,
+          // One relevance number per mode: similarity (intent) or distance (discovery).
+          ...(typeof r.similarity === "number" ? { similarity: r.similarity } : {}),
+          ...(typeof r.distance === "number" ? { distance: r.distance } : {}),
+          source_url: r.source_url,
+          // The standard source identity (migration 021) — lets the model (and anyone
+          // reading the trace) scope follow-ups to ONE source ("only this doc's needs").
+          // 12 chars: cheaper than the URL it complements.
+          ...(r.source_id ? { source_id: r.source_id } : {}),
+          hasImage,
+          ...(Object.keys(meta).length ? { metadata: meta } : {}),
+        };
+      }),
+    };
+    return JSON.stringify(lean);
+  } catch {
+    return resultContent;
+  }
+}
+
+/**
+ * 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. SHELL-OPEN (fire-and-forget): one empty native call per newly discovered app —
+ *      the server renders the page SKELETON immediately, so the guest sees the page
+ *      exist seconds in and watches it hydrate, never a blank panel while the model
+ *      composes.
+ *   3. 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.
+ *
+ * `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.
+ */

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. */