@unoverse-platform/studio 0.1.97 → 0.1.99

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

@@ -7,7 +7,7 @@
  * outlived the accuracy (renamed 2026-08-09).
  */
 import type { RowComponent, AppInvocationContext } from "./types.js";
-import { invokeComponentAppNative } from "./invoke.js";
+import { invokeTaskNative } from "./invoke.js";
 // Pure section helpers, shared with every renderer so the rules live in one place.
 import { toDocument } from "../markdown/document.js";
 
@@ -32,27 +32,10 @@ export function rowComponentsFromResults(results: unknown): RowComponent[] {
   const seen = new Set<string>();
   if (!Array.isArray(results)) return out;
   for (const item of results as any[]) {
-    if (item?.object_type === "mcp") {
-      /**
-       * A REGISTRY ROW THAT IS A COMPONENT ARRIVES AS ITS SHELL (TEMPLATE_MODEL §12e "One
-       * ladder, one delivery", ruled 2026-09-04). A bindingless component (a manifest, no
-       * workflow — the card finder) used to be only UNLOCKED here as a tool and rendered a
-       * turn later when the model called it; meanwhile the display cards from the same
-       * search had already landed, so a `page` card held the screen for the second before
-       * the `focus` component existed. Now it lands in the SAME delivery as the cards, in
-       * its declared state, and the ladder decides among them at once. Delivered, never
-       * invoked: no row props, no outputs collected — the model's own call (still minted
-       * by discovery) merges its arguments into this slice and collects the answers.
-       * Workflow-bound apps (path A) and native MCP tools stay tools.
-       */
-      const uri = item?.metadata?.app;
-      if (typeof uri !== "string" || !uri.startsWith("unoverse://components/") || item.metadata?.workflow || item.metadata?.schema?.methods) continue;
-      const component = componentTypeFromAppUri(uri);
-      if (!component || seen.has(component)) continue;
-      seen.add(component);
-      out.push({ id: component, component, props: {}, shell: true });
-      continue;
-    }
+    // TASKS ARE ASKED, CONTENT IS RENDERED (RENDER_PIPELINE §4, locked 2026-09-06). A
+    // registry row (a component, a task, an app) is a door the LLM calls; it never reaches
+    // the screen through this lane. Only rows with a component attached — content — do.
+    if (item?.object_type === "mcp" || item?.object_type === "task") continue;
     const app = item?.metadata?.app;
     if (typeof app !== "string" || !app.startsWith("unoverse://components/") || item.metadata.workflow) continue;
     const component = componentTypeFromAppUri(app);
@@ -62,12 +45,16 @@ export function rowComponentsFromResults(results: unknown): RowComponent[] {
     out.push({
       id,
       component,
+      rank: rankOf(item),
       // 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,
+        // THE SOURCE (owner, 2026-09-11): the row's source_id rides its card, so the screen
+        // can name it and the model can scope a search to what is open.
+        ...(item.source_id ? { source_id: item.source_id } : {}),
         // 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
@@ -86,6 +73,25 @@ export function rowComponentsFromResults(results: unknown): RowComponent[] {
   return out;
 }
 
+/**
+ * THE ROW'S RELEVANCE, read the same way the search's own merge reads it
+ * (routes/dictionary/search/ranking.ts `rank`): the score where there is one, else the
+ * negated distance, so higher is always better. Rows in one delivery come from one search
+ * call, so their numbers compare even though intent scores cosine and discovery scores
+ * proximity.
+ */
+function rankOf(item: any): number | undefined {
+  const r =
+    typeof item?.similarity_score === "number"
+      ? item.similarity_score
+      : typeof item?.similarity === "number"
+        ? item.similarity
+        : typeof item?.distance === "number"
+          ? -item.distance
+          : undefined;
+  return typeof r === "number" && Number.isFinite(r) ? r : undefined;
+}
+
 /**
  * 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
@@ -93,40 +99,149 @@ export function rowComponentsFromResults(results: unknown): RowComponent[] {
  * held call resolves immediately server-side) and a failed render never breaks the
  * conversation.
  */
+/** ONE INSTANCE ON SCREEN, as the screen document says it (docs/unoverse/design/screen/UNOVERSE_SCREEN.md §2.5). */
+export interface ScreenItem {
+  /** The instance id; for a row card, the row's own id. */
+  id: string;
+  type: string;
+  /** True when the LLM called it (a task). */
+  asked?: boolean;
+  /** The state the instance is in now, the guest's own move included. */
+  state?: string;
+  /** The state it arrived in. Differs from `state` when the guest moved it: they opened it. */
+  arrived?: string;
+  /** What it shows: its props, as the delivery carried them. */
+  props?: Record<string, unknown>;
+  /** The place it is shown in, on an app that declares places. */
+  place?: string;
+}
+
+/** WHAT IS ON SCREEN, asked of the server's screen document, which registers this at boot; the
+ *  search result reads it so the model is told what the person is looking at. */
+let screenReader: ((conversationId: string) => ScreenItem[]) | null = null;
+export function onScreenRead(fn: (conversationId: string) => ScreenItem[]): void {
+  screenReader = fn;
+}
+/** THE PLACES a conversation's app declares (docs/unoverse/design/screen/UNOVERSE_SCREEN.md), asked of
+ *  the server, which registers this at boot. The conversation is always among them; nothing is
+ *  shown unless something shows it. */
+let placesReader: ((conversationId: string) => string[] | null) | null = null;
+export function onScreenPlaces(fn: (conversationId: string) => string[] | null): void {
+  placesReader = fn;
+}
+export function placesOn(conversationId: string | undefined): string[] {
+  return (conversationId && placesReader ? placesReader(conversationId) : null) ?? ["chat"];
+}
+export function screenOf(conversationId: string | undefined): ScreenItem[] {
+  return conversationId && screenReader ? screenReader(conversationId) : [];
+}
+/** The open tasks standing, by component id: what the LLM called and holds the screen. */
+export function openTasksOn(conversationId: string | undefined): string[] {
+  return screenOf(conversationId).filter((i) => i.asked).map((i) => i.type).filter(Boolean);
+}
+/** The instances the GUEST opened: moved out of the state they arrived in (a card tapped
+ *  into its page). Derived from the move, never from a state's name: no word is special. */
+export function openedOn(conversationId: string | undefined): ScreenItem[] {
+  return screenOf(conversationId).filter((i) => !i.asked && i.state && i.arrived && i.state !== i.arrived);
+}
+
+/** WHEN AN OPEN PAGE IS THE ANSWER (RENDER_PIPELINE §3.3, ruled 2026-09-07). "About it" is
+ *  narrow: a message about the page itself updates it; a NEW QUESTION is answered and shown,
+ *  and the page closes. Read loosely ("if the message is about it") the model rebuilt a
+ *  comparison for "what is the best card for travel", a question that never asked to compare
+ *  (Gavin: "but I did not ask to compare"). ONE sentence, said in the search mirror and in the
+ *  re-minted page tool, so the two can never drift. */
+export const ABOUT_THE_PAGE =
+  "Call that tool ONLY when the user's message is about the page itself: change it, add to it, swap one of its items, explain one of its rows. A new question is NOT about the page, even if the page could hold the answer: answer it and call screen_show, which closes the page.";
+
+/** WHAT THE GUEST OPENED, said in the mirror (ruled 2026-09-10): the item and its id, so
+ *  the model's next search and its getDetail carry the id of what is open. ONE sentence,
+ *  the same in the mirror and in screen_read. */
+export const ABOUT_THE_OPENED =
+  "The user is looking at it: a question is about it unless they say otherwise. Its full record is getDetail(<id>); what it is linked to, one step at a time, is walk(<id>); pass its source_id as sourceId to a search when the question is inside it.";
+
+/** The mirror's first line: any open page (a task the LLM called, with its tool), then
+ *  anything the guest opened (a card moved into its page, with its id), then the rules. */
+export function onScreenLine(open: string[], toolNameOf: (id: string) => string, opened: ScreenItem[] = []): string {
+  const page = open.length ? `ON SCREEN NOW: ${open.map((id) => `${id} (open page; its tool is ${toolNameOf(id)})`).join(", ")}. ${ABOUT_THE_PAGE} ` : "";
+  const moved = opened.length
+    ? `THE USER OPENED: ${opened.map((i) => `${i.type} ${i.id} (now in ${i.state}${titleOf(i) ? `, "${titleOf(i)}"` : ""}${sourceOf(i) ? `, source_id ${sourceOf(i)}` : ""})`).join(", ")}. ${ABOUT_THE_OPENED} `
+    : "";
+  return `${page}${moved}`;
+}
+const titleOf = (i: ScreenItem): string => (typeof i.props?.title === "string" ? (i.props.title as string).slice(0, 80) : "");
+const sourceOf = (i: ScreenItem): string => (typeof i.props?.source_id === "string" ? (i.props.source_id as string) : "");
+
+/** WHAT IS ON SCREEN, said in a search result on an app with places
+ *  (docs/unoverse/design/screen/UNOVERSE_SCREEN.md §3.1): each place and what it holds, then what this
+ *  search showed. The model reads it right before it answers. */
 /**
- * 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.
+ * WHAT THIS TURN'S SEARCHES FOUND (docs/unoverse/design/screen/UNOVERSE_SCREEN.md §3.1). A search
+ * draws nothing: the rows that carry a card wait here, per conversation, until the model shows
+ * the ones its answer is about with `screen_show`. Searches in one turn add up (a run the turn
+ * started extends its chat id); the first search of a new turn replaces them.
  */
-let emptyDeliveryListener: ((chatId: string) => void) | null = null;
-export function onEmptyRowDelivery(fn: (chatId: string) => void): void {
-  emptyDeliveryListener = fn;
+const foundRows = new Map<string, { turn: string; rows: RowComponent[] }>();
+const MAX_FOUND = 10000;
+
+export function rememberRows(conversationId: string, chatId: string, rows: RowComponent[]): void {
+  const held = foundRows.get(conversationId);
+  const sameTurn = !!held && (chatId === held.turn || chatId.startsWith(`${held.turn}:`));
+  const kept = sameTurn ? held!.rows.filter((r) => !rows.some((x) => x.id === r.id)) : [];
+  foundRows.delete(conversationId);
+  foundRows.set(conversationId, { turn: sameTurn ? held!.turn : chatId, rows: [...kept, ...rows] });
+  if (foundRows.size > MAX_FOUND) foundRows.delete(foundRows.keys().next().value!);
+}
+
+/** The id the model is given for a card: the row's universal id, as the search result shows it. */
+export const cardIdOf = (row: RowComponent): string => String(row.props?.universal_id ?? row.id);
+
+/** This turn's cards with these ids, in the order the model gave them. */
+export function rowsById(conversationId: string, ids: string[]): RowComponent[] {
+  const rows = foundRows.get(conversationId)?.rows ?? [];
+  const out: RowComponent[] = [];
+  for (const id of ids) {
+    const row = rows.find((r) => r.id === id || cardIdOf(r) === id);
+    if (row && !out.includes(row)) out.push(row);
+  }
+  return out;
+}
+
+/** The task the search put first (objects-in-spatial.md, "A task first"). */
+export interface TaskFirstLine {
+  universal_id: string;
+  title: string;
+}
+
+export function placesLine(conversationId: string | undefined, places: string[], cards: RowComponent[], task?: TaskFirstLine | null): string {
+  const items = screenOf(conversationId);
+  const named = places.filter((p) => p !== "chat");
+  const now = named
+    .map((p) => {
+      const here = items.filter((i) => i.place === p);
+      return here.length ? `${p}: ${here.map((i) => `${i.type} ${i.id}${titleOf(i) ? ` "${titleOf(i)}"` : ""}`).join(", ")}` : `${p}: empty`;
+    })
+    .join("; ");
+  const list = cards
+    .slice(0, 12)
+    .map((c) => `${cardIdOf(c)}${typeof c.props?.title === "string" ? ` "${c.props.title}"` : ""}`)
+    .join(", ");
+  const found = cards.length
+    ? ` This search found ${cards.length} card(s): ${list}. None is shown yet. If your answer is these cards themselves, call screen_show with their ids now, before reading their details: the user sees them at once, and you read while they look. If you will hand them to a task instead, such as a comparison, do not show them: the task is what the user sees.`
+    : "";
+  // A TASK FIRST (objects-in-spatial.md, 2026-09-18): the search ranked a task first, so
+  // the fact is said, and the order is: call it now, read after.
+  const opened = task
+    ? ` A task answers this request: ${task.title} (${task.universal_id}). Call it now, before reading any detail, and give it the cards it needs from this search; it is what the user sees, so do not show the cards.`
+    : "";
+  return `ON SCREEN: ${now}.${opened}${found}`;
 }
 
-/** What the delivery did with one row: rendered, held back by the director or the ladder,
- *  delivered as a shell, or failed. The search's MIRROR is written from these. */
+/** What the delivery did with one row: rendered, or failed. */
 export interface RowOutcome {
   component: string;
   id: string;
-  action: "rendered" | "held-back" | "shell" | "failed";
-}
-
-/**
- * THE SEARCH'S MIRROR (MCP_APP_PROTOCOL §0.1, ruled 2026-09-05): one line saying what the
- * delivery put on screen and what it did not show, so the model answers the screen and
- * not the rows. Empty when nothing is on screen (card-only deliveries do not mirror).
- */
-export function screenLine(outcomes: RowOutcome[]): string {
-  const shown = outcomes.filter((o) => o.action === "shell" || o.action === "rendered");
-  const hidden = outcomes.filter((o) => o.action === "held-back");
-  if (!shown.some((o) => o.action === "shell")) return "";
-  const on = shown.map((o) => (o.action === "shell" ? `${o.component} (on screen, in its opening state)` : o.component)).join(", ");
-  const off = hidden.length ? ` Not shown: ${hidden.length} result card(s), ranked below it on the app's ladder — do not describe them as visible.` : "";
-  return `On screen: ${on}. Answer by pointing the guest to what is on screen.${off}`;
+  action: "rendered" | "failed";
 }
 
 export function renderRowComponents(
@@ -136,15 +251,8 @@ export function renderRowComponents(
 ): Promise<RowOutcome[]> {
   // 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 Promise.resolve([]);
-  if (!items?.length) {
-    // The search ran on a live session and surfaced nothing — say so (§12e).
-    if (ctx.chatId) emptyDeliveryListener?.(ctx.chatId);
-    return Promise.resolve([]);
-  }
-  // 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.
+  if (!ctx.userId || !items?.length) return Promise.resolve([]);
+  // ONE DELIVERY, carried as a batch: the screen keeps the cards of one search in its order.
   const batchId = `${ctx.chatId ?? ctx.conversationId ?? "b"}:${Math.random().toString(36).slice(2, 8)}`;
   let index = 0;
   const outcomes: Promise<RowOutcome>[] = [];
@@ -160,24 +268,19 @@ export function renderRowComponents(
     // 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.
-    // A shell keys the component's own slice (no per-row instance), so the model's later
-    // call for the same component merges into it rather than drawing a second one.
     outcomes.push(
-      invokeComponentAppNative(item.component, {
+      invokeTaskNative(item.component, {
         ...ctx,
         message: "",
         props: item.props,
-        ...(item.shell ? { shell: true } : { instanceId: item.id }),
+        instanceId: item.id,
+        ...(typeof item.rank === "number" ? { rank: item.rank } : {}),
         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): RowOutcome => {
-          const action: RowOutcome["action"] = r.action === "held-back" ? "held-back" : r.action === "shell" ? "shell" : "rendered";
-          log?.(action === "held-back" ? `🧩 HELD BACK ${item.component} (${item.id})` : `🧩 RENDERED ${item.component} (${item.id})`);
-          return { component: item.component, id: item.id, action };
+        .then((): RowOutcome => {
+          log?.(`🧩 RENDERED ${item.component} (${item.id})`);
+          return { component: item.component, id: item.id, action: "rendered" };
         })
         .catch((e: any): RowOutcome => {
           log?.(`🧩 FAILED ${item.component} (${item.id}) — ${e?.message ?? e}`);
@@ -189,7 +292,7 @@ export function renderRowComponents(
 }
 
 /** `unoverse://components/journey-finder` → `journey-finder`;
- *  `unoverse://components/bpp/journey-finder` → `bpp/journey-finder` (the render ref);
+ *  `unoverse://components/<org>/finder` → `<org>/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.
@@ -201,9 +304,18 @@ export function renderRowComponents(
  * `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. */
+ * never resolved.
+ *
+ * THE HASH IS NOT PART OF THE NAME (docs/unoverse/data/objects/README.md, the object's `app`):
+ * `unoverse://components/<org>/<name>#<state>` names the interface, and the hash the state
+ * the canvas opens ONE row in. A delivery of rows names the component alone: where an
+ * arrival lands is the receiving template's (UNOVERSE_TEMPLATE_MODEL §5d, the grid place
+ * takes arrivals). Observed live 2026-09-11: the deal object named `#page`, the tool asked
+ * for was `better-alpha.deal#page`, -32602 at the door, and the voice agent described a
+ * deal nobody could see. */
 export function componentTypeFromAppUri(app: string): string {
   return String(app)
+    .replace(/#.*$/, "")
     .replace(/^unoverse:\/\/(components|templates)\//, "")
     .replace(/^\/+|\/+$/g, "");
 }
@@ -215,7 +327,7 @@ export function componentTypeFromAppUri(app: string): string {
  * 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.
+ * rows is what left a page drafting from rows of one kind while rows of another sat unusable.
  */
 export function rankedRowIds(resultContent: string, limit = 12): string[] {
   try {

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

@@ -4,8 +4,8 @@
  * 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 type { AgentToolDef, DiscoveredMCP, AppInvocationContext, OfferedFunction } from "./types.js";
+import { connectPlatformMcp, invokeTaskNative } from "./invoke.js";
 import { APP_ETIQUETTE } from "./discovery.js";
 
 /**
@@ -72,8 +72,12 @@ export async function resolveToolDefNative(
       const contract = JSON.parse(res.contents?.[0]?.text ?? "{}") as {
         description?: string;
         inputSchema?: Record<string, unknown> | null;
+        outputSchema?: Record<string, unknown> | null;
       };
-      if (!contract.inputSchema) return toolDefFromDiscoveredMCP(mcp); // not briefed — generic contract
+      // WHAT COMES BACK rides the tool (MCP `outputSchema`), briefed or not: a finder with no
+      // fillable field still tells the model, before the call, what it hands back.
+      const returns = contract.outputSchema ? { outputSchema: contract.outputSchema } : {};
+      if (!contract.inputSchema) return { ...toolDefFromDiscoveredMCP(mcp), ...returns }; // 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.
@@ -82,23 +86,60 @@ export async function resolveToolDefNative(
         name: modelToolName(mcp.methodName),
         description: `${contract.description || mcp.title || mcp.methodName}${directive} ${APP_ETIQUETTE}`,
         parameters: contract.inputSchema,
+        ...returns,
       };
     } finally {
       await close();
     }
-  } catch {
+  } catch (err) {
+    // SAID, NOT SWALLOWED (2026-09-16): a contract read that fails hands the model a tool with
+    // no schema either way, and until this line nothing reported it. The card finder reached
+    // the model with `output_schema: null` while the server's contract carried one, and the
+    // only path that produces that shape is this fallback.
+    console.warn(`[agent-mcp] contract read failed for ${mcp.appUri ?? mcp.methodName}; minted without its schema: ${err instanceof Error ? err.message : String(err)}`);
     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.
+ * adapter routes it to `invokeTaskNative` (held `/mcp` call) instead of firing.
  */
 export function isBindinglessComponentApp(mcp: DiscoveredMCP): boolean {
   return !!mcp.component && !mcp.workflowId;
 }
 
+/** A workflow task (2026-09-06): a task-augmented native tool, held until the Agent's run completes. */
+export function isWorkflowTask(mcp: DiscoveredMCP): boolean {
+  return !!mcp.taskTool;
+}
+
+/**
+ * THE ONE workflow-task adapter every agent family wires for a discovered workflow task.
+ * The model's arguments go to the tool as they are (the task's own input schema shaped
+ * them); the identity rides beside them so the server pushes the face into THIS
+ * conversation and runs the Agent as THIS caller. The held call resolves with the run's
+ * result in `output.result`.
+ */
+export function workflowTaskInvoker(
+  mcp: DiscoveredMCP,
+  identity: Pick<AppInvocationContext, "conversationId" | "userId" | "chatId" | "accessToken" | "baseUrl">,
+): (input: unknown) => ReturnType<typeof invokeTaskNative> {
+  const toolId = mcp.taskTool as string;
+  return (input: unknown) => {
+    const { message, ...rest } = (input ?? {}) as Record<string, unknown>;
+    return invokeTaskNative(toolId, {
+      conversationId: identity.conversationId,
+      userId: identity.userId,
+      accessToken: identity.accessToken,
+      chatId: identity.chatId,
+      ...(identity.baseUrl ? { baseUrl: identity.baseUrl } : {}),
+      message: typeof message === "string" ? message : "",
+      ...(Object.keys(rest).length ? { args: rest } : {}),
+    });
+  };
+}
+
 /**
  * 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
@@ -116,15 +157,50 @@ export function isBindinglessComponentApp(mcp: DiscoveredMCP): boolean {
 export function componentAppInvoker(
   mcp: DiscoveredMCP,
   identity: Pick<AppInvocationContext, "conversationId" | "userId" | "chatId" | "accessToken">,
-): (input: unknown) => ReturnType<typeof invokeComponentAppNative> {
+): (input: unknown) => ReturnType<typeof invokeTaskNative> {
   const toolId = mcp.component as string;
   return (input: unknown) => {
     const { message, ...hydrated } = (input ?? {}) as Record<string, unknown>;
-    return invokeComponentAppNative(toolId, {
+    return invokeTaskNative(toolId, {
+      conversationId: identity.conversationId,
+      userId: identity.userId,
+      accessToken: identity.accessToken,
+      chatId: identity.chatId,
+      message: typeof message === "string" ? message : "",
+      ...(Object.keys(hydrated).length ? { props: hydrated } : {}),
+    });
+  };
+}
+
+/**
+ * The ONE workflow-bound app adapter (path A), and the reason a called app now opens.
+ *
+ * An app is ALREADY a native MCP tool on the platform's own server — `registerTools`
+ * (server mcp/server/tools.ts) registers every app under its bare id plus an `<org>.<name>`
+ * alias — so opening one is the same held `/mcp` call a component app makes. Only the id
+ * differs: a path-A row carries no `component`, and its identity is the app's own name.
+ *
+ * WITHOUT THIS, a workflow-bound app minted a tool that nothing could invoke. The mint set
+ * `handoffTools` and nothing else, so `bridge.call` found no entry in `appInvokers` and fell
+ * through to `api.callService`, which addresses SERVICE methods: the platform answered
+ * "SpatialSearch has no service method \"sab-voice\"" and the call failed in 10ms while the
+ * run still reported success. Observed live on SAB (2026-09-07): the app was found, minted
+ * and CALLED, and the person watched a blank panel. Every workflow-bound app shared this —
+ * the path-B sibling three lines above had an invoker from the day it was written.
+ */
+export function workflowAppInvoker(
+  mcp: DiscoveredMCP,
+  identity: Pick<AppInvocationContext, "conversationId" | "userId" | "chatId" | "accessToken" | "baseUrl">,
+): (input: unknown) => ReturnType<typeof invokeTaskNative> {
+  const toolId = String(mcp.methodName);
+  return (input: unknown) => {
+    const { message, ...hydrated } = (input ?? {}) as Record<string, unknown>;
+    return invokeTaskNative(toolId, {
       conversationId: identity.conversationId,
       userId: identity.userId,
       accessToken: identity.accessToken,
       chatId: identity.chatId,
+      ...(identity.baseUrl ? { baseUrl: identity.baseUrl } : {}),
       message: typeof message === "string" ? message : "",
       ...(Object.keys(hydrated).length ? { props: hydrated } : {}),
     });
@@ -132,3 +208,56 @@ export function componentAppInvoker(
 }
 
 /** Context a held app call needs to reach the human on the live session. */
+
+/**
+ * A FOUND OBJECT'S FUNCTION AS A TOOL (docs/unoverse/data/spatial/objects-in-spatial.md, "Found
+ * objects' functions as tools"). Named by the function, never per object: the model sees one
+ * `getDetail`, told which objects answer it, and passes the row's universal_id beside the
+ * function's own arguments. `input: false` never reaches a tool; the function's `input` is what
+ * its author declared for callers, so it is handed over as written, with the id required.
+ */
+export function objectFunctionToolDef(fn: OfferedFunction): AgentToolDef {
+  const input = (fn.input ?? { type: "object", properties: {} }) as Record<string, any>;
+  const properties = { ...(input.properties && typeof input.properties === "object" ? input.properties : {}) };
+  const required = Array.isArray(input.required) ? input.required.filter((r: unknown) => typeof r === "string") : [];
+  const who = fn.objects.length ? ` Offered by: ${fn.objects.join(", ")}.` : "";
+  return {
+    name: modelToolName(fn.name),
+    description: `${fn.description || fn.name}${who} Pass the universal_id of a result you already hold, exactly as it appeared; never invented.`,
+    parameters: {
+      ...input,
+      type: "object",
+      properties: {
+        universal_id: { type: "string", description: "The result's universal_id, exactly as it appeared in the search result." },
+        ...properties,
+      },
+      required: ["universal_id", ...required.filter((r: string) => r !== "universal_id")],
+    },
+  };
+}
+
+/**
+ * The call: the engine's one function door, `POST /dictionary/function/<name>/<universal_id>`,
+ * with the model's other arguments as the function's params. The engine runs the function of
+ * THAT row's object (a fund's `documents`, a document's `getDetail`), or answers 404 when the
+ * row's object offers no such function, which comes back to the model as the error it is.
+ */
+export function objectFunctionInvoker(fn: OfferedFunction, engineUrl: string): (input: unknown) => Promise<unknown> {
+  return async (input: unknown) => {
+    const { universal_id, ...params } = (input ?? {}) as Record<string, unknown>;
+    const id = typeof universal_id === "string" ? universal_id.trim() : "";
+    if (!id) return { error: `${fn.name} needs the universal_id of a result you already hold.` };
+    const res = await fetch(`${engineUrl}/dictionary/function/${encodeURIComponent(fn.name)}/${encodeURIComponent(id)}`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(params),
+    });
+    const text = await res.text();
+    if (!res.ok) return { error: text || `${fn.name} answered ${res.status}` };
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  };
+}

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

@@ -25,11 +25,12 @@
  *
  * 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
+ * `invokeTaskNative` — 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:
+ * elicits, or runs an Agent and holds until it completes; the answers resolve the call).
+ * Node-MCP rows route in-process via the caller's `api.callService` because they have a node
+ * to run; component apps and WORKFLOW TASKS (every task is a native MCP tool, 2026-09-06)
+ * ride the wire. Full map:
  * docs/MCP_COMPLETE_GUIDE.md → "where YOUR code ends and native MCP begins".
  */
 
@@ -54,7 +55,7 @@ export interface DiscoveredMCP {
   /**
    * 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
+   * `invokeTaskNative` (the held native `/mcp` call) instead of firing
    * `workflow@trigger`; `workflowId`/`nodeId` are empty. Undefined for node-MCP + path-A apps.
    */
   component?: string;
@@ -62,6 +63,33 @@ export interface DiscoveredMCP {
    *  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 WORKFLOW TASK (2026-09-06): a task-augmented native tool on the platform's /mcp. The
+   * value is the tool's identity (`<org>/<name>`), spelled dotted on the wire. Calling it
+   * holds until the Agent's run completes and returns the terminal node's output.
+   */
+  taskTool?: string;
+  /**
+   * MINTED FROM A TASK ROW (object_type `task`): an outcome with a door, whichever door it
+   * has. The bridge reports a call to it as a `task` step, so the execution timeline draws
+   * it as a task and not as one more tool.
+   */
+  task?: true;
+}
+
+/**
+ * A FUNCTION THE ROWS OF A SEARCH RESULT OFFER (docs/unoverse/data/spatial/objects-in-spatial.md,
+ * "Found objects' functions as tools"): the engine names, once per NAME across the result, every
+ * public function the found rows' objects declare in api/service.yaml. The harness mints one tool
+ * per name, its input the function's own plus the row's universal_id, and a call runs that row's
+ * own object's function through the engine's one function door.
+ */
+export interface OfferedFunction {
+  name: string;
+  description: string;
+  input?: Record<string, unknown>;
+  /** The objects in the result that offer it, by title. */
+  objects: string[];
 }
 
 /** A neutral function-tool definition; each family maps this to its wire format. */
@@ -69,6 +97,8 @@ export interface AgentToolDef {
   name: string;
   description: string;
   parameters: Record<string, unknown>;
+  /** What the tool returns, from a component's `outputs` block (MCP `outputSchema`). */
+  outputSchema?: Record<string, unknown>;
 }
 
 /** Mint the model-facing tool definition for a discovered MCP. */
@@ -91,10 +121,17 @@ export interface AppInvocationContext {
   /** Deliver the component's SHELL only: render it in its declared state and return
    *  at once — never collect its outputs (§12e "Discovery delivers; it never invokes"). */
   shell?: boolean;
+  /** The row's relevance as the search scored it — the director's ordering. */
+  rank?: number;
   /** 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 };
+  /**
+   * A WORKFLOW TASK's own arguments (2026-09-06), as the model wrote them against the task's
+   * input schema. Spread into the call beside the identity; the server shapes the run from them.
+   */
+  args?: Record<string, unknown>;
   /** 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. */
@@ -130,9 +167,9 @@ export interface RowComponent {
   component: string;
   /** The row's content AS-IS — the component's state (binds resolve by name). */
   props: Record<string, unknown>;
-  /** A SHELL delivery (TEMPLATE_MODEL §12e "One ladder, one delivery"): the row is a
-   *  component that takes input (a manifest, no workflow). It arrives in the same
-   *  delivery as the cards, in its declared state, with its own defaults and NO row
-   *  props; it is never invoked here — its form opens only on the model's call. */
-  shell?: boolean;
+  /** THE ROW'S RELEVANCE, as the search scored it (`similarity_score`, else `similarity`,
+   *  else `-distance`, read exactly as `routes/dictionary/search/ranking.ts` ranks). Carried
+   *  as a NUMBER because arrival position is not rank: renders dispatch in parallel. Rows
+   *  within one delivery come from one search call, so their numbers compare. */
+  rank?: number;
 }