@unoverse-platform/studio 0.1.103 → 0.1.104

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unoverse-platform/studio",
-  "version": "0.1.103",
+  "version": "0.1.104",
   "type": "module",
   "description": "Unoverse Studio: the local authoring app. Reads your own rx/ folder, no backend.",
   "scripts": {
@@ -26,7 +26,9 @@
     "@codemirror/state": "^6.5.2",
     "@codemirror/theme-one-dark": "^6.1.2",
     "@codemirror/view": "^6.37.1",
-    "@modelcontextprotocol/sdk": "^1.25.1",
+    "@modelcontextprotocol/client": "^2.2.0",
+    "@modelcontextprotocol/ext-apps": "^2.0.3",
+    "@modelcontextprotocol/server": "^2.2.0",
     "@smithy/protocol-http": "^5.5.14",
     "@smithy/signature-v4": "^5.6.10",
     "@tailwindcss/vite": "^4.0.0",

package/screens/AtomsView.tsx

@@ -7,7 +7,8 @@
  * Meta (no manifest). Ported from apps/unoverse/web/studio (kept diffable).
  */
 import { useEffect, useMemo, useState, type MouseEvent as ReactMouseEvent } from "react";
-import { UnoverseComponent, type ResolvedTheme } from "@unoverse/sdk";
+import type { ResolvedTheme } from "@unoverse/sdk";
+import { UnoverseComponent } from "./react/unoverse";
 import { client, authedFetch } from "studio-host";
 import { usePersistentState } from "studio-host";
 import { NAV, SCREEN, navItem } from "./chrome";

package/screens/ComponentsView.tsx

@@ -5,7 +5,8 @@
  */
 import { useCallback, useEffect, useMemo, useState } from "react";
 import { ComponentStore } from "@unoverse/sdk";
-import { UnoverseComponent, type ResolvedTheme } from "@unoverse/sdk";
+import type { ResolvedTheme } from "@unoverse/sdk";
+import { UnoverseComponent } from "./react/unoverse";
 import { client, authedFetch, hasSourceAccess } from "studio-host";
 import { SourceView } from "./SourceView";
 import { stateActivation, faceOf, faceAxisOf, switchLayers } from "./states";

package/screens/NativeAppHost.tsx

@@ -10,8 +10,7 @@
  * required, from the thing that owns it. Nothing is vendored, nothing is bundled.
  */
 import { useEffect, useRef, useState } from "react";
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
 
 const APP_UI_URI = "ui://unoverse/app.html";
 

package/screens/TemplatesLibraryView.tsx

@@ -15,7 +15,8 @@
  * NOT TemplatesView.tsx: that name is taken by the Apps screen (the legacy noun).
  */
 import { useEffect, useMemo, useState, useSyncExternalStore, useCallback, type MouseEvent as ReactMouseEvent } from "react";
-import { ComponentStore, UnoverseComponent, type ResolvedTheme } from "@unoverse/sdk";
+import { ComponentStore, type ResolvedTheme } from "@unoverse/sdk";
+import { UnoverseComponent } from "./react/unoverse";
 import { client, authedFetch, usePersistentState, useRegistryToggles, ToggleSwitch } from "studio-host";
 import { NAV, SCREEN, navItem, navSubItem } from "./chrome";
 
@@ -53,6 +54,8 @@ interface TemplateDef {
   defaultLayout?: string;
   /** Seeding map the loader assembles: face → interface refs. */
   preview?: Record<string, string[]>;
+  /** The components it holds, one stand-in per item of its own preview data, per state. */
+  heldSeeds?: Record<string, { key: string; component: string; props: Record<string, unknown> }[]>;
 }
 
 const PREVIEW_CHAT = "preview";
@@ -185,6 +188,16 @@ export function TemplatesLibraryView({ theme, org }: { theme: ResolvedTheme; org
     });
     const base = current.defaultLayout ?? (current.layouts ? Object.keys(current.layouts)[0] : undefined);
     if (base) store.mergeComponentState(PREVIEW_CHAT, TEMPLATE_NODE, { state: base });
+    // WHAT IT HOLDS (docs/design/templates.md "Holding a component"): each item its own
+    // instance under the template's node id, the id the SDK's held slot looks for. With no
+    // screen here, an opened one stays in its spot and draws its own page there.
+    const held = new Set<string>();
+    for (const seed of Object.values(current.heldSeeds ?? {}).flat()) {
+      const nodeId = `${TEMPLATE_NODE}:${seed.component}:${seed.key}`;
+      if (held.has(nodeId)) continue;
+      held.add(nodeId);
+      store.apply({ type: "COMPONENT_INIT", chatId: PREVIEW_CHAT, nodeId, component: { type: seed.component, props: seed.props } });
+    }
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [store, current]);
 

package/screens/TemplatesView.tsx

@@ -23,7 +23,8 @@ import { useCallback, useEffect, useMemo, useState, useSyncExternalStore } from
 import { useAuth } from "react-oidc-context";
 import { usePersistentState, useRegistryToggles, ToggleSwitch } from "studio-host";
 import { ComponentStore } from "@unoverse/sdk";
-import { StreamedUnoverseApp, useUnoverseConnection, computeAppWidth, resolveActiveLayout, visible, type ResolvedTheme, type UseVoiceServiceConfig } from "@unoverse/sdk";
+import { computeAppWidth, resolveActiveLayout, visible, type ResolvedTheme } from "@unoverse/sdk";
+import { StreamedUnoverseApp, useUnoverseConnection, type UseVoiceServiceConfig } from "./react/unoverse";
 import { NativeAppHost } from "./NativeAppHost";
 import { inArrangement, viewOfSlice } from "./states";
 import { client, authedFetch, hasAuth, hasSourceAccess, UNOVERSE_BASE, liveUniverseUrl } from "studio-host";

package/screens/index.ts

@@ -37,3 +37,7 @@ export { ConfigForm, defaultsFromSchema } from "./ConfigForm";
 // The source view renders only where the host grants source access, so it is exported
 // unconditionally and returns null in Canvas (docs/architecture/authoring/LOCAL_STUDIO.md).
 export { SourceView } from "./SourceView";
+// The React faces of the plain SDK (the SDK has no React): one component, an app, the live
+// connection and the voice service, for the React hosts that share these screens.
+export { UnoverseComponent, StreamedUnoverseApp, useUnoverseConnection, useVoiceService } from "./react/unoverse";
+export type { UnoverseComponentProps, StreamedUnoverseAppProps, UnoverseConnection, UseVoiceServiceConfig, VoiceService } from "./react/unoverse";

package/screens/react/unoverse.tsx

@@ -0,0 +1,281 @@
+/**
+ * THE REACT ADAPTER for the Unoverse SDK, for the React apps that host it (Studio, the canvas).
+ *
+ * The SDK has no React (apps/unoverse/web/sdk/CLAUDE.md): it draws with `mountComponent`,
+ * `mountApp`, `openConnection` and `createVoiceService`. These four names give a React tree the
+ * same props it always passed, each a thin mount of the plain API into one element. Nothing here
+ * draws or decides: the SDK does (docs/unoverse/design/sdk/UNOVERSE_SDK_NO_REACT.md §6 (a)).
+ */
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore, type ReactNode } from "react";
+import { createPortal } from "react-dom";
+import {
+  mountComponent,
+  mountApp,
+  openConnection,
+  createVoiceService,
+  sessionUserId,
+  type ActionHandler,
+  type AppMount,
+  type ComponentMount,
+  type ComponentStore,
+  type ResolvedTheme,
+  type UnoverseClient,
+  type UnoverseConnection as PlainConnection,
+  type UnoverseConnectionConfig,
+  type UnoverseSessionParams,
+  type VoiceService as PlainVoiceService,
+  type VoiceServiceConfig,
+  type VoiceServiceState,
+} from "@unoverse/sdk";
+
+/** One element the plain mount draws into; `display: contents` keeps it out of layout. */
+function useHost() {
+  const ref = useRef<HTMLDivElement>(null);
+  return { ref, el: () => ref.current };
+}
+
+export interface UnoverseComponentProps {
+  client: UnoverseClient;
+  uri?: string;
+  data?: Record<string, unknown>;
+  store?: ComponentStore;
+  chatId?: string;
+  nodeId?: string;
+  extraData?: Record<string, unknown>;
+  onAction?: ActionHandler;
+  theme?: ResolvedTheme;
+  isolate?: boolean;
+  fill?: boolean;
+  /** What a `Place` in the definition draws (React content, drawn into the place). */
+  place?: (name: string) => ReactNode;
+  appStore?: ComponentStore;
+}
+
+/** React content the plain SDK draws into an element it is handed (a place, a chrome). */
+function usePortals() {
+  const holders = useRef(new Map<string, { el: HTMLDivElement; node: ReactNode; sig: string }>());
+  const [, redraw] = useState(0);
+  /** The element for `key`, with `node` to draw in it; redraws only when `sig` changes. */
+  const hold = useCallback((key: string, node: ReactNode, sig: string) => {
+    let h = holders.current.get(key);
+    if (!h) {
+      h = { el: document.createElement("div"), node, sig };
+      h.el.style.display = "contents";
+      holders.current.set(key, h);
+      queueMicrotask(() => redraw((n) => n + 1));
+    } else {
+      h.node = node;
+      if (h.sig !== sig) {
+        h.sig = sig;
+        queueMicrotask(() => redraw((n) => n + 1));
+      }
+    }
+    return h.el;
+  }, []);
+  const portals = [...holders.current.entries()].map(([key, h]) => createPortal(h.node, h.el, key));
+  return { hold, portals };
+}
+
+export function UnoverseComponent(props: UnoverseComponentProps) {
+  const host = useHost();
+  const mount = useRef<ComponentMount | null>(null);
+  const { hold, portals } = usePortals();
+  const latest = useRef(props);
+  latest.current = props;
+  const options = () => {
+    const p = latest.current;
+    return {
+      client: p.client as never,
+      uri: p.uri,
+      data: p.data,
+      store: p.store,
+      chatId: p.chatId,
+      nodeId: p.nodeId,
+      extraData: p.extraData,
+      onAction: p.onAction,
+      theme: p.theme,
+      isolate: p.isolate,
+      fill: p.fill,
+      appStore: p.appStore,
+      place: p.place ? (name: string) => [hold(`place:${name}`, latest.current.place?.(name), name)] : undefined,
+    };
+  };
+  useLayoutEffect(() => {
+    const m = mountComponent(options());
+    mount.current = m;
+    host.el()?.append(...m.nodes);
+    return () => {
+      m.destroy();
+      m.nodes.forEach((n) => n.parentNode?.removeChild(n));
+      mount.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- one mount; props flow through update
+  }, []);
+  useLayoutEffect(() => {
+    mount.current?.update(options());
+  });
+  return (
+    <div ref={host.ref} style={{ display: "contents" }}>
+      {portals}
+    </div>
+  );
+}
+
+export interface StreamedUnoverseAppProps {
+  client: UnoverseClient;
+  store: ComponentStore;
+  uri: string;
+  onAction?: ActionHandler;
+  theme?: ResolvedTheme;
+  props?: Record<string, unknown>;
+  isolate?: boolean;
+  /** DEV CHROME ON A CONTAINER: React content drawn above a Container's content. */
+  templateChrome?: (info: { name: string; states: string[]; active?: string; set: (state: string) => void }) => ReactNode;
+  /** The voice service config, for a `service: "voice"` app (the SDK starts it). */
+  voice?: VoiceServiceConfig;
+  /** The voice service, when the host already runs one. */
+  voiceService?: Pick<PlainVoiceService, "startCall" | "endCall" | "toggleMute">;
+}
+
+export function StreamedUnoverseApp(props: StreamedUnoverseAppProps) {
+  const host = useHost();
+  const mount = useRef<AppMount | null>(null);
+  const { hold, portals } = usePortals();
+  const latest = useRef(props);
+  latest.current = props;
+  // The app's own voice service, when given a config and no service.
+  const own = useMemo(
+    () => (props.voice && !props.voiceService ? createVoiceService({ ...props.voice, wsUrl: props.client.serverOrigin.replace(/^http/, "ws") }) : null),
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- one per config identity
+    [props.voice, props.voiceService, props.client],
+  );
+  useEffect(() => () => own?.destroy(), [own]);
+  const options = () => {
+    const p = latest.current;
+    return {
+      client: p.client as never,
+      store: p.store,
+      uri: p.uri,
+      onAction: p.onAction,
+      theme: p.theme,
+      props: p.props,
+      isolate: p.isolate,
+      voice: p.voiceService ?? own ?? undefined,
+      templateChrome: p.templateChrome
+        ? (info: { name: string; states: string[]; active?: string; set: (state: string) => void }) =>
+            hold(`chrome:${info.name}`, latest.current.templateChrome?.(info), JSON.stringify([info.states, info.active]))
+        : undefined,
+      doc: document,
+    };
+  };
+  useLayoutEffect(() => {
+    const m = mountApp(options());
+    mount.current = m;
+    host.el()?.append(...m.nodes);
+    return () => {
+      m.destroy();
+      m.nodes.forEach((n) => n.parentNode?.removeChild(n));
+      mount.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- one mount; props flow through update
+  }, []);
+  useLayoutEffect(() => {
+    mount.current?.update(options());
+  });
+  return (
+    <div ref={host.ref} style={{ display: "contents" }}>
+      {portals}
+    </div>
+  );
+}
+
+export interface UnoverseConnection {
+  isConnected: boolean;
+  isReady: boolean;
+  refusal: string | null;
+  sendMessage: (text: string) => void;
+  trigger: (input?: Record<string, unknown>) => void;
+  sendAction: (action: string, data: Record<string, unknown>) => void;
+  resolveElicitation: (state: Record<string, unknown>, action?: "accept" | "cancel") => boolean;
+  /** The workflow-selected template (MCP app) name, or null. */
+  activeApp: string | null;
+}
+
+const IDLE = { isConnected: false, isReady: false, refusal: null };
+
+/** The live connection, opened for a React host and re-rendered on its status. */
+export function useUnoverseConnection(
+  config: UnoverseConnectionConfig,
+  session: UnoverseSessionParams,
+  store: ComponentStore,
+  options: { enabled?: boolean; onAppSwitch?: (app: string) => void; onJoinCall?: (workflowId?: string) => void } = {},
+): UnoverseConnection {
+  const enabled = options.enabled ?? true;
+  // Read through refs, so a host's inline arrow or a new app never tears the stream down.
+  const callbacks = useRef(options);
+  callbacks.current = options;
+  const appId = useRef(session.appId);
+  appId.current = session.appId;
+  const userId = sessionUserId(session.userId, config.getAccessToken);
+  const chatId = session.chatId ?? session.conversationId;
+  const [conn, setConn] = useState<PlainConnection | null>(null);
+  useEffect(() => {
+    if (!enabled) return; // mock mode: no live stream
+    const c = openConnection(config, session, store, {
+      onAppSwitch: (app) => callbacks.current.onAppSwitch?.(app),
+      onJoinCall: (w) => callbacks.current.onJoinCall?.(w),
+      appId: () => appId.current,
+    });
+    setConn(c);
+    return () => {
+      c.close();
+      setConn(null);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- keyed on the fields the connection reads
+  }, [enabled, config.streamUrl, session.workflowId, session.targetTriggerNode, userId, session.conversationId, chatId, config.getAccessToken, store]);
+  const status = useSyncExternalStore(
+    useCallback((cb: () => void) => (conn ? conn.subscribe(cb) : () => {}), [conn]),
+    useCallback(() => conn?.status() ?? IDLE, [conn]),
+  );
+  const activeApp = useSyncExternalStore(
+    useCallback((cb: () => void) => store.subscribe(cb), [store]),
+    useCallback(() => store.getActiveApp().name, [store]),
+  );
+  // Without a connection (mock mode, or before it opens) a send still shows the person's turn
+  // and the thinking state; the run itself is dropped, loudly.
+  const sendMessage = useCallback(
+    (text: string) => {
+      if (conn) return conn.sendMessage(text);
+      const message = text.trim();
+      if (!message) return;
+      const turn = `${chatId}:t${Date.now().toString(36)}${Math.floor(Math.random() * 1296).toString(36)}`;
+      store.addUserMessage(turn, message);
+      store.startResponse(turn);
+      console.error("[unoverse] trigger dropped — MCP stream not connected yet");
+    },
+    [conn, chatId, store],
+  );
+  const trigger = useCallback((input?: Record<string, unknown>) => (conn ? conn.trigger(input) : console.error("[unoverse] trigger dropped — MCP stream not connected yet")), [conn]);
+  const sendAction = useCallback((action: string, data: Record<string, unknown>) => conn?.sendAction(action, data), [conn]);
+  const resolveElicitation = useCallback((state: Record<string, unknown>, action: "accept" | "cancel" = "accept") => conn?.resolveElicitation(state, action) ?? false, [conn]);
+  return { ...status, sendMessage, trigger, sendAction, resolveElicitation, activeApp };
+}
+
+export type UseVoiceServiceConfig = VoiceServiceConfig;
+export type VoiceService = Omit<PlainVoiceService, "subscribe" | "destroy" | "state"> & { state: VoiceServiceState };
+
+/** The voice service, held for a React host and re-rendered on its state. */
+export function useVoiceService(config: UseVoiceServiceConfig): VoiceService {
+  const { session } = config;
+  const service = useMemo(
+    () => createVoiceService(config),
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- keyed on what the service reads
+    [config.apiUrl, config.wsUrl, config.getAccessToken, config.store, session.userId, session.conversationId, session.chatId, session.workflowId, session.targetTriggerNode],
+  );
+  useEffect(() => () => service.destroy(), [service]);
+  const state = useSyncExternalStore(
+    (cb) => service.subscribe(cb),
+    () => service.state,
+  );
+  return { state, startCall: service.startCall, joinCall: service.joinCall, endCall: service.endCall, toggleMute: service.toggleMute, unlock: service.unlock };
+}

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

@@ -38,7 +38,7 @@ export { parseToolResult, isTurnEndingHandoff } from "./handoff.js";
 export { rowComponentsFromResults, renderRowComponents, rankedRowIds, componentTypeFromAppUri, onScreenRead, onScreenPlaces, placesOn, placesLine, rememberRows, rowsById, cardIdOf, screenOf, openedOn, type ScreenItem, openTasksOn, onScreenLine, ABOUT_THE_PAGE, ABOUT_THE_OPENED } from "./rowComponents.js";
 export { leanToolResultForModel } from "./lean.js";
 export { toolDefFromDiscoveredMCP, resolveToolDefNative, isBindinglessComponentApp, componentAppInvoker, isWorkflowTask, workflowTaskInvoker, workflowAppInvoker, modelToolName, objectFunctionToolDef, objectFunctionInvoker } from "./tools.js";
-export { invokeTaskNative, connectPlatformMcp } from "./invoke.js";
+export { invokeTaskNative, connectPlatformMcp, TRACE_META } from "./invoke.js";
 
 export { ingestConversationTurn, type ConversationTurn } from "./memoryIngest.js";
 export { fetchUserMemoryContext, hydratePromptWithUserMemory } from "./memoryContext.js";

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

@@ -31,13 +31,16 @@ import type { AppInvocationContext, DiscoveredMCP } from "./types.js";
  * harness (every agent family) using the app id it parsed at mint time — so it needs NO
  * server-side (XState) schema cache.
  */
+/** The `_meta` key a platform call carries its caller under (AppInvocationContext.trace). */
+export const TRACE_META = "unoverse/trace";
+
 /** 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 { Client } = await import("@modelcontextprotocol/client");
+  const { StreamableHTTPClientTransport } = await import("@modelcontextprotocol/client");
 
   const base = (ctx.baseUrl || process.env.UNOVERSE_SERVICE_URL || "http://localhost:4106").replace(/\/$/, "");
   const accessToken = ctx.accessToken;
@@ -94,6 +97,7 @@ export async function invokeTaskNative(
           // A workflow task's own arguments, as the model wrote them against the task's schema.
           ...(ctx.args ?? {}),
         },
+        ...(ctx.trace?.executionId && ctx.trace?.nodeId ? { _meta: { [TRACE_META]: ctx.trace } } : {}),
       },
       undefined,
       // A human is completing the wizard, or an Agent is working — lift the SDK's 60s default to 24h.

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

@@ -123,7 +123,7 @@ export function isWorkflowTask(mcp: DiscoveredMCP): boolean {
  */
 export function workflowTaskInvoker(
   mcp: DiscoveredMCP,
-  identity: Pick<AppInvocationContext, "conversationId" | "userId" | "chatId" | "accessToken" | "baseUrl">,
+  identity: Pick<AppInvocationContext, "conversationId" | "userId" | "chatId" | "accessToken" | "baseUrl" | "trace">,
 ): (input: unknown) => ReturnType<typeof invokeTaskNative> {
   const toolId = mcp.taskTool as string;
   return (input: unknown) => {
@@ -133,6 +133,7 @@ export function workflowTaskInvoker(
       userId: identity.userId,
       accessToken: identity.accessToken,
       chatId: identity.chatId,
+      ...(identity.trace ? { trace: { ...identity.trace, kind: "task" } } : {}),
       ...(identity.baseUrl ? { baseUrl: identity.baseUrl } : {}),
       message: typeof message === "string" ? message : "",
       ...(Object.keys(rest).length ? { args: rest } : {}),
@@ -156,7 +157,7 @@ export function workflowTaskInvoker(
  */
 export function componentAppInvoker(
   mcp: DiscoveredMCP,
-  identity: Pick<AppInvocationContext, "conversationId" | "userId" | "chatId" | "accessToken">,
+  identity: Pick<AppInvocationContext, "conversationId" | "userId" | "chatId" | "accessToken" | "trace">,
 ): (input: unknown) => ReturnType<typeof invokeTaskNative> {
   const toolId = mcp.component as string;
   return (input: unknown) => {
@@ -166,6 +167,7 @@ export function componentAppInvoker(
       userId: identity.userId,
       accessToken: identity.accessToken,
       chatId: identity.chatId,
+      ...(identity.trace ? { trace: { ...identity.trace, kind: mcp.task ? "task" : "tool" } } : {}),
       message: typeof message === "string" ? message : "",
       ...(Object.keys(hydrated).length ? { props: hydrated } : {}),
     });
@@ -190,7 +192,7 @@ export function componentAppInvoker(
  */
 export function workflowAppInvoker(
   mcp: DiscoveredMCP,
-  identity: Pick<AppInvocationContext, "conversationId" | "userId" | "chatId" | "accessToken" | "baseUrl">,
+  identity: Pick<AppInvocationContext, "conversationId" | "userId" | "chatId" | "accessToken" | "baseUrl" | "trace">,
 ): (input: unknown) => ReturnType<typeof invokeTaskNative> {
   const toolId = String(mcp.methodName);
   return (input: unknown) => {
@@ -200,6 +202,7 @@ export function workflowAppInvoker(
       userId: identity.userId,
       accessToken: identity.accessToken,
       chatId: identity.chatId,
+      ...(identity.trace ? { trace: { ...identity.trace, kind: mcp.task ? "task" : "tool" } } : {}),
       ...(identity.baseUrl ? { baseUrl: identity.baseUrl } : {}),
       message: typeof message === "string" ? message : "",
       ...(Object.keys(hydrated).length ? { props: hydrated } : {}),
@@ -242,12 +245,18 @@ export function objectFunctionToolDef(fn: OfferedFunction): AgentToolDef {
  * 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> {
+export function objectFunctionInvoker(
+  fn: OfferedFunction,
+  engineUrl: string,
+  /** Who is asking: the run and the calling node. The function records its own call under them. */
+  caller?: { executionId?: string; nodeId?: string },
+): (input: unknown) => Promise<unknown> {
+  const who = caller?.executionId && caller?.nodeId ? `?${new URLSearchParams({ executionId: caller.executionId, caller: caller.nodeId })}` : "";
   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)}`, {
+    const res = await fetch(`${engineUrl}/dictionary/function/${encodeURIComponent(fn.name)}/${encodeURIComponent(id)}${who}`, {
       method: "POST",
       headers: { "content-type": "application/json" },
       body: JSON.stringify(params),

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

@@ -105,6 +105,12 @@ export interface AgentToolDef {
 
 /** Context a held app call needs to reach the human on the live session. */
 export interface AppInvocationContext {
+  /**
+   * WHO IS CALLING, for the tool's own row on the trace (packages/docs/nodes/mcp-services.md,
+   * "Who records a call"): the run and the calling node, and whether the call opens a task.
+   * Sent as the call's `_meta`, never as an argument; absent for a call no model made.
+   */
+  trace?: { executionId?: string; nodeId?: string; kind?: "tool" | "task" };
   /** The caller's stream session — where the wizard renders and elicitation is answered. */
   conversationId?: string;
   userId?: string;