@unoverse-platform/studio 0.1.115 → 0.1.117

package/screens/index.ts

@@ -25,7 +25,10 @@ export { TemplatesLibraryView } from "./TemplatesLibraryView";
 export { DesignSystemView } from "./DesignSystemView";
 export { SkillsView } from "./SkillsView";
 // Agents: the one file authored for the map (docs.unoverse.ai/design/tasks), one lane in both Studios.
-export { AgentsView } from "./AgentsView";
+export { AgentsView, agentForCanvas } from "./AgentsView";
+// An Agent drawn off its agent.yaml: Studio's lane, and Signal's Agent page beside its runs.
+export { AgentChain } from "./AgentChain";
+export type { AgentFolderItem } from "./AgentChain";
 export { IdentityView } from "./IdentityView";
 export { PromptBlocksView } from "./PromptBlocksView";
 export { IdentityHeader } from "./IdentityHeader";

package/src/host.ts

@@ -110,6 +110,11 @@ class LocalUnoverseClient {
     );
   }
 
+  /** A component's task runs in a universe. A folder runs none, so it fills nothing. */
+  async runTask(): Promise<Record<string, unknown>> {
+    return {};
+  }
+
   /**
    * Read a definition, and STAMP EVERY NODE WITH ITS PATH.
    *

package/src/index.css

@@ -5,3 +5,14 @@ body,
 #root {
   height: 100%;
 }
+
+/* PRINT: only the template stage prints, one 1280x720 page per slide; Studio's chrome stays out.
+   The page is the stage's own size, so a stage drawn at Desktop width (1280) prints at scale 1. */
+@media print {
+  @page { size: 1280px 720px; margin: 0; }
+  html, body, #root, #root * { height: auto !important; min-height: 0 !important; overflow: visible !important; }
+  body *:not([data-print-stage]):not([data-print-stage] *):not(:has([data-print-stage])) { display: none !important; }
+  :has(> [data-print-stage]), :has([data-print-stage]) { display: block !important; padding: 0 !important; margin: 0 !important; border: 0 !important; }
+  [data-print-stage] { padding: 0 !important; }
+  [data-print-stage] > div { width: 1280px !important; max-width: none !important; margin: 0 !important; }
+}

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

@@ -5,6 +5,7 @@
  * 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 { taskUri } from "../definitions/registry/taskUri.js";
 import type { AgentToolExchange, DiscoveredMCP, AppInvocationContext, OfferedFunction } from "./types.js";
 
 /** The discovery tools whose results can carry `object_type: "mcp"` rows. */
@@ -71,7 +72,7 @@ export function parseDiscoveredMCPs(calls: AgentToolExchange[]): DiscoveredMCP[]
         // A TASK IS A TOOL, DESCRIBED LIKE ONE (owner ruling 2026-09-08). This used to close
         // with TASK_ETIQUETTE — "calling this runs an Agent and holds until it completes while
         // the person watches its progress on screen; say in one short sentence what you are
-        // doing" — and the only thing it told the model to DO was speak. Measured on SAB
+        // doing" — and the only thing it told the model to DO was speak. Measured on a bank
         // (2026-09-08): across four runs of one question the model called once and, three
         // times, emitted exactly one sentence of intent and ended the turn, with no
         // function-call events in the stream at all.
@@ -89,7 +90,9 @@ export function parseDiscoveredMCPs(calls: AgentToolExchange[]): DiscoveredMCP[]
           workflowId: item.metadata.workflow || item.workflow_id,
           nodeId: item.metadata.trigger,
           methodName,
-          taskTool: String(methodName),
+          // The task's one URI when the map row holds it (docs/mcp/MCP_TASKS.md § 2a), else its name;
+          // the wire call names the tool from either by the one rule (invoke.ts).
+          taskTool: String(taskUri(item.metadata?.task) ?? methodName),
           schema: { methods: { [methodName]: { description: taskDescription, input } } },
         });
       } else if (item.metadata?.schema?.methods) {

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

@@ -22,6 +22,7 @@
  *   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
+ *   progressive many tools held behind search_tools and call_tool (MCP Client Best Practices)
  *   memory*     conversation ingest and user-memory hydration
  */
 
@@ -38,7 +39,8 @@ 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, TRACE_META } from "./invoke.js";
+export { invokeTaskNative, connectPlatformMcp, TRACE_META, readTask, answerTask } from "./invoke.js";
+export { shouldDefer, metaTools, searchAnswer, searchTools, estimateTokens, DEFER_ABOVE_TOKENS, SEARCH_TOOLS, CALL_TOOL, type HeldTool } from "./progressive.js";
 
 export { ingestConversationTurn, type ConversationTurn } from "./memoryIngest.js";
 export { fetchUserMemoryContext, hydratePromptWithUserMemory } from "./memoryContext.js";

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

@@ -11,6 +11,7 @@
  * Node-MCP rows still route in-process via the caller's `api.callService`: they have a
  * node to run. Renamed from `invokeComponentAppNative` when workflow tasks joined it.
  */
+import { taskToolName } from "../definitions/registry/taskUri.js";
 import type { AppInvocationContext, DiscoveredMCP } from "./types.js";
 
 /**
@@ -73,35 +74,174 @@ export async function connectPlatformMcp(
   };
 }
 
+/** The tasks extension's id (`io.modelcontextprotocol/tasks`), as the official library names it. */
+const TASKS_EXTENSION = "io.modelcontextprotocol/tasks";
+const MODERN = "2026-07-28";
+
+type CallResult = {
+  isError?: boolean;
+  content?: Array<{ type: string; text?: string }>;
+  structuredContent?: Record<string, any>;
+};
+
+/** A 2026-07-28 client on the platform's /mcp that declared the tasks extension, and the official
+ *  task session over it: what every native task call below is made on. Close the client after. */
+async function openTaskSession(ctx: Pick<AppInvocationContext, "baseUrl" | "accessToken">) {
+  const { Client, StreamableHTTPClientTransport } = await import("@modelcontextprotocol/client");
+  const { createTaskSessionFromClient } = await import("@modelcontextprotocol/ext-tasks/client");
+  const base = (ctx.baseUrl || process.env.UNOVERSE_SERVICE_URL || "http://localhost:4106").replace(/\/$/, "");
+  const auth: Record<string, string> = ctx.accessToken ? { Authorization: `Bearer ${ctx.accessToken}` } : {};
+  const clientInfo = { name: "unoverse-agent-mcp", version: "1.0.0" };
+  const clientCapabilities = { extensions: { [TASKS_EXTENSION]: {} } };
+  const client = new Client(clientInfo, { versionNegotiation: { mode: { pin: MODERN } }, capabilities: clientCapabilities } as never);
+  await client.connect(
+    new StreamableHTTPClientTransport(new URL(`${base}/mcp`), {
+      fetch: (url: string | URL, init?: RequestInit) => fetch(url, { ...init, headers: { ...Object.fromEntries(new Headers(init?.headers)), ...auth } }),
+    }),
+  );
+  let next = 0;
+  const rawDispatch = async (request: { method: string; params?: Record<string, unknown> }) => {
+    const id = `task-${++next}`;
+    const name = request.method === "tools/call" ? request.params?.name : request.method.startsWith("tasks/") ? request.params?.taskId : undefined;
+    const res = await fetch(`${base}/mcp`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        accept: "application/json, text/event-stream",
+        "mcp-protocol-version": MODERN,
+        "mcp-method": request.method,
+        ...(typeof name === "string" ? { "mcp-name": name } : {}),
+        ...auth,
+      },
+      body: JSON.stringify({ jsonrpc: "2.0", id, ...request }),
+    });
+    const text = await res.text();
+    // A JSON answer, or a stream whose last message for this id is the answer.
+    if (!text.includes("data: ")) return JSON.parse(text);
+    const answers = text.split("\n").filter((l) => l.startsWith("data: ")).map((l) => JSON.parse(l.slice(6)));
+    return answers.filter((m) => m.id === id).pop() ?? answers.pop();
+  };
+  const session = createTaskSessionFromClient(client as never, {
+    endpointId: `${base}/mcp`,
+    rawDispatch: rawDispatch as never,
+    v2RequestFraming: { protocolVersion: MODERN, clientInfo, clientCapabilities },
+  } as never);
+  return { client, session };
+}
+
+/**
+ * ONE CALL, FOLLOWED AS AN MCP TASK WHEN IT IS ONE (docs/mcp/MCP_TASKS.md steps 6 and 7). Every
+ * Task is an MCP task: a workflow, a form, an app that asks. The harness calls as a 2026-07-28
+ * client that declared the tasks extension, so a Task answers at once with its task and the
+ * official client (`@modelcontextprotocol/ext-tasks/client`) follows it to its result; a call
+ * with nothing to wait for answers at once, through the same client. Several calls in one turn
+ * each follow their own task, side by side.
+ *
+ * The one piece of host code the library asks for is `rawDispatch`: it sends one JSON-RPC request
+ * on the 2026 framing and hands back the response. The host owns request ids, so it adds them.
+ */
+async function callFollowingTasks(toolId: string, args: Record<string, unknown>, ctx: AppInvocationContext): Promise<CallResult> {
+  const { resultFromTaskOutcome } = await import("@modelcontextprotocol/ext-tasks/client");
+  const { client, session } = await openTaskSession(ctx);
+  try {
+    const execution = await session.callTool(
+      // THE TOOL NAME FROM THE TASK'S ONE URI (docs/mcp/MCP_TASKS.md § 2a): a task URI or its short
+      // form `<org>/<name>` is called as `<org>.<name>`; anything else (a bare app id) as given.
+      taskToolName(toolId) ?? toolId,
+      args as never,
+      {
+        ...(ctx.trace?.executionId && ctx.trace?.nodeId ? { metadata: { [TRACE_META]: ctx.trace as never } } : {}),
+        // A person completing a form, or an Agent working: either may take many minutes; the run's own cap ends it first.
+        requestTimeoutMs: 24 * 60 * 60 * 1000,
+      },
+    );
+    if (execution.kind === "task") console.log(`[unoverse:task] FOLLOW ${toolId}: followed as an MCP task to its result`);
+    // THE CALLING RUN STOPPED: the task it follows is cancelled (native `tasks/cancel`), so it does
+    // not run on for nobody. The outcome then reads cancelled, and the call fails with it.
+    const stop = () => {
+      if (execution.kind !== "task") return;
+      console.log(`[unoverse:task] CANCEL ${toolId}: its caller's run stopped`);
+      void execution.cancel().catch(() => {});
+    };
+    if (ctx.signal?.aborted) stop();
+    else ctx.signal?.addEventListener("abort", stop, { once: true });
+    try {
+      // WHAT THE TASK IS DOING, AS IT CHANGES (docs/mcp/MCP_TASKS.md § 5). The extension's own
+      // settle hands every task update to `onEvent`; each new statusMessage goes to the caller,
+      // once per change, and a caller that did not ask for them is never told.
+      let lastStatus = "";
+      const onEvent = ctx.onStatus
+        ? (event: { type: string; task?: { statusMessage?: string } }) => {
+            const message = event.type === "task" ? String(event.task?.statusMessage ?? "").trim() : "";
+            if (!message || message === lastStatus) return;
+            lastStatus = message;
+            try {
+              ctx.onStatus!(message);
+            } catch {
+              /* a listener's failure never fails the task it watches */
+            }
+          }
+        : undefined;
+      const { outcome } = await execution.settle(onEvent ? ({ onEvent } as never) : undefined);
+      return resultFromTaskOutcome(outcome) as CallResult;
+    } finally {
+      ctx.signal?.removeEventListener("abort", stop);
+    }
+  } finally {
+    await client.close().catch(() => {});
+  }
+}
+
+/** A workflow Task: its result comes back as `output.result`, the run's result as text. */
+export async function invokeWorkflowTask(
+  toolId: string,
+  ctx: AppInvocationContext,
+): Promise<{ status: "completed"; output?: Record<string, unknown>; conversationId?: string; message?: string }> {
+  const result = await callFollowingTasks(
+    toolId,
+    {
+      message: ctx.message ?? "",
+      ...(ctx.conversationId ? { conversationId: ctx.conversationId } : {}),
+      ...(ctx.userId ? { userId: ctx.userId } : {}),
+      ...(ctx.chatId ? { chatId: ctx.chatId } : {}),
+      ...((ctx.args ?? {}) as Record<string, never>),
+    },
+    ctx,
+  );
+  const text = result.content?.find((c) => c.type === "text")?.text ?? "";
+  if (result.isError) throw new Error(text || `${toolId} did not complete`);
+  return {
+    status: "completed",
+    output: { result: text },
+    conversationId: ctx.conversationId,
+    message:
+      "The Agent completed. `output.result` is what it found, already shown to the person on screen. " +
+      "Continue the task with it: answer from it, and do not repeat it verbatim unless asked.",
+  };
+}
+
 export async function invokeTaskNative(
   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(
+  {
+    const result = (await callFollowingTasks(
+      toolId,
       {
-        // 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.shell ? { shell: true } : {}),
-          ...(typeof ctx.rank === "number" ? { rank: ctx.rank } : {}),
-          ...(ctx.batch ? { batch: ctx.batch } : {}),
-          // 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 } } : {}),
+        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.shell ? { shell: true } : {}),
+        ...(typeof ctx.rank === "number" ? { rank: ctx.rank } : {}),
+        ...(ctx.batch ? { batch: ctx.batch } : {}),
+        // A workflow task's own arguments, as the model wrote them against the task's schema.
+        ...(ctx.args ?? {}),
       },
-      undefined,
-      // A human is completing the wizard, or an Agent is working — lift the SDK's 60s default to 24h.
-      { timeout: 24 * 60 * 60 * 1000 },
+      ctx,
     )) as {
       isError?: boolean;
       content?: Array<{ type: string; text?: string }>;
@@ -125,6 +265,9 @@ export async function invokeTaskNative(
       return {
         status: "completed",
         output: { result: result.structuredContent.result },
+        // THE TASK'S OWN ID (owner 2026-10-24: "save the task, show it in the timeline, click it
+        // to see it"): the run that did this, so the caller can record it where the work belongs.
+        ...(result.structuredContent?.executionId ? { run: result.structuredContent.executionId } : {}),
         conversationId: result.structuredContent?.conversationId,
         message:
           "The Agent completed. `output.result` is what it found, already shown to the person on screen. " +
@@ -167,9 +310,40 @@ export async function invokeTaskNative(
               "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.
+
+/**
+ * A TASK THAT ALREADY EXISTS, by its id (docs/mcp/MCP_TASKS.md § 5c): the official client's
+ * `session.task(id)`. Read gives where it is and, once it has finished, what it produced; answer
+ * replies to what a waiting task asks (`tasks/update`). Nothing else: MCP offers nothing else.
+ */
+export async function readTask(taskId: string, ctx: Pick<AppInvocationContext, "baseUrl" | "accessToken">): Promise<{ taskId: string; status: string; statusMessage?: string; asks?: unknown; result?: string }> {
+  const { client, session } = await openTaskSession(ctx);
+  try {
+    const task = (session as any).task(taskId);
+    const view = await task.snapshot();
+    const raw = (view.raw ?? {}) as Record<string, any>;
+    const done = (raw.result?.content ?? []).find((c: any) => c?.type === "text")?.text;
+    return {
+      taskId: view.taskId,
+      status: view.status,
+      ...(view.statusMessage ? { statusMessage: view.statusMessage } : {}),
+      ...(raw.inputRequests && Object.keys(raw.inputRequests).length ? { asks: raw.inputRequests } : {}),
+      ...(typeof done === "string" && done ? { result: done } : {}),
+    };
+  } finally {
+    await client.close().catch(() => {});
+  }
+}
+
+export async function answerTask(taskId: string, inputResponses: Record<string, unknown>, ctx: Pick<AppInvocationContext, "baseUrl" | "accessToken">): Promise<void> {
+  const { client, session } = await openTaskSession(ctx);
+  try {
+    await (session as any).task(taskId).updateJson(inputResponses);
+  } finally {
+    await client.close().catch(() => {});
+  }
+}

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

@@ -0,0 +1,124 @@
+/**
+ * PROGRESSIVE TOOL DISCOVERY (MCP 2026-07-28, Client Best Practices; docs/mcp/MCP_2026-07-28.md
+ * § 4, 3e; packages/docs/nodes/mcp-services.md, "Many tools").
+ *
+ * A host with many tools does not hand the model every definition. It keeps them, gives the
+ * model a `search_tools` meta-tool, and loads a definition only when the job needs it. Our
+ * harness is the host for every Agent, so this is decided here, once, for every model.
+ *
+ * THE TOOL LIST NEVER CHANGES DURING A RUN. A found tool is not added to the list: it is called
+ * through `call_tool`, MCP's "single stable call_tool({name, args}) meta-tool so the array never
+ * changes". Adding it would break the model's prompt cache at that turn.
+ *
+ * Pure: the tools come in, the offer and the answers go out. The bridge does the calling.
+ */
+
+/** A tool as the bridge holds it: what the model would be offered, plus the server it is from. */
+export interface HeldTool {
+  name: string;
+  description: string;
+  parameters: unknown;
+  server?: string;
+}
+
+/**
+ * THE THRESHOLD, in estimated tokens of definitions. MCP: switch "once the tool definitions take
+ * up a significant part of the available context window", for example 1% to 5%. 2,000 is 1% of a
+ * 200k window and under 2% of a 128k one. Below it, every tool is offered as before.
+ */
+export const DEFER_ABOVE_TOKENS = 2000;
+
+/** How many tools one search hands back: a few that fit, never the catalogue. */
+const MATCHES = 5;
+
+export const SEARCH_TOOLS = "search_tools";
+export const CALL_TOOL = "call_tool";
+
+/** About four characters a token: the usual estimate, and close enough to pick a side of 2,000. */
+export function estimateTokens(tools: HeldTool[]): number {
+  return Math.ceil(JSON.stringify(tools.map(({ name, description, parameters }) => ({ name, description, parameters }))).length / 4);
+}
+
+/** Should these tools be held back behind search? */
+export function shouldDefer(tools: HeldTool[]): boolean {
+  return estimateTokens(tools) > DEFER_ABOVE_TOKENS;
+}
+
+/** A tool in one line: its name and the first sentence of what it does, never its schema. */
+function oneLine(t: HeldTool): string {
+  const first = String(t.description ?? "").split(/(?<=[.!?:])\s/)[0].trim();
+  return `- ${t.name}: ${first.length > 140 ? `${first.slice(0, 137)}...` : first}`;
+}
+
+/**
+ * THE CATALOGUE: every held tool in one line, grouped by server (MCP: "names and one-line
+ * descriptions", "group tools by server"). The model sees what it has and loads a definition only
+ * when it needs it; without the lines an Agent never knew a tool existed, so it never searched and
+ * named tools it did not have (Bob, 2026-10-11). Stable for the run, so the prompt cache holds.
+ */
+export function catalogue(held: HeldTool[]): string {
+  const groups = new Map<string, HeldTool[]>();
+  for (const t of held) {
+    const key = t.server ?? "";
+    groups.set(key, [...(groups.get(key) ?? []), t]);
+  }
+  return [...groups.entries()].map(([server, tools]) => [server ? `${server}:` : "", ...tools.map(oneLine)].filter(Boolean).join("\n")).join("\n");
+}
+
+/** The two meta-tools, offered in place of the held ones. The search carries the catalogue. */
+export function metaTools(held: HeldTool[]): HeldTool[] {
+  return [
+    {
+      name: SEARCH_TOOLS,
+      description:
+        `Load the full definition (input schema) of the tools you need before you call them. Describe the job in plain words, or give a tool's name; the answer is the tools that fit, each with its server and full input schema. Call it before ${CALL_TOOL} for any tool whose schema you do not yet hold. The tools you have:\n${catalogue(held)}`,
+      parameters: {
+        type: "object",
+        properties: { query: { type: "string", description: "What you need to do, e.g. 'save a person's email address'." } },
+        required: ["query"],
+      },
+    },
+    {
+      name: CALL_TOOL,
+      description: `Call one tool that ${SEARCH_TOOLS} found, by its exact name, with arguments matching its input schema.`,
+      parameters: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: `The tool's exact name, as ${SEARCH_TOOLS} gave it.` },
+          arguments: { type: "object", description: "The tool's arguments, matching its input schema." },
+        },
+        required: ["name"],
+      },
+    },
+  ];
+}
+
+const words = (s: string): string[] => s.toLowerCase().split(/[^a-z0-9]+/).filter((w) => w.length > 1);
+
+/**
+ * KEYWORD SEARCH, the first of MCP's strategies ("simple and effective, particularly for descriptive
+ * tool names and descriptions"). A word of the query in the tool's name counts most, then in its
+ * server, then in its description. A name's own parts count: `send_message` is "send" and "message".
+ */
+export function searchTools(held: HeldTool[], query: string): Array<{ name: string; server?: string; description: string; inputSchema: unknown }> {
+  const asked = [...new Set(words(query))];
+  const scored = held
+    .map((t) => {
+      const name = new Set(words(t.name.replace(/([a-z0-9])([A-Z])/g, "$1 $2")));
+      const server = new Set(words((t.server ?? "").replace(/([a-z0-9])([A-Z])/g, "$1 $2")));
+      const text = new Set(words(t.description));
+      const score = asked.reduce((s, w) => s + (name.has(w) ? 3 : 0) + (server.has(w) ? 2 : 0) + (text.has(w) ? 1 : 0), 0);
+      return { t, score };
+    })
+    .filter((x) => x.score > 0)
+    .sort((a, b) => b.score - a.score);
+  return scored.slice(0, MATCHES).map(({ t }) => ({ name: t.name, ...(t.server ? { server: t.server } : {}), description: t.description, inputSchema: t.parameters }));
+}
+
+/** The answer to a search the model reads: the matches, or what to do when there are none. */
+export function searchAnswer(held: HeldTool[], query: string): string {
+  const found = searchTools(held, String(query ?? ""));
+  if (found.length) return JSON.stringify({ tools: found });
+  const servers = [...new Set(held.map((t) => t.server).filter(Boolean))];
+  return JSON.stringify({ tools: [], note: `No tool matched "${query}". Describe the job in other words${servers.length ? `, or name a server: ${servers.join(", ")}` : ""}.` });
+}

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

@@ -5,7 +5,7 @@
  * 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, OfferedFunction } from "./types.js";
-import { connectPlatformMcp, invokeTaskNative } from "./invoke.js";
+import { connectPlatformMcp, invokeTaskNative, invokeWorkflowTask } from "./invoke.js";
 import { APP_ETIQUETTE } from "./discovery.js";
 
 /**
@@ -109,30 +109,35 @@ 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. */
+/** A workflow task (2026-09-06): a native tool the harness follows as an MCP task to its result (step 6). */
 export function isWorkflowTask(mcp: DiscoveredMCP): boolean {
   return !!mcp.taskTool;
 }
 
+/** What a caller may hear while a task it called runs: its status, each time it changes. */
+export type TaskCallHooks = Pick<AppInvocationContext, "onStatus">;
+
 /**
  * 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`.
+ * conversation and runs the Agent as THIS caller. The task is followed to its result
+ * (docs/mcp/MCP_TASKS.md step 6), which comes back in `output.result`.
  */
 export function workflowTaskInvoker(
   mcp: DiscoveredMCP,
-  identity: Pick<AppInvocationContext, "conversationId" | "userId" | "chatId" | "accessToken" | "baseUrl" | "trace">,
-): (input: unknown) => ReturnType<typeof invokeTaskNative> {
+  identity: Pick<AppInvocationContext, "conversationId" | "userId" | "chatId" | "accessToken" | "baseUrl" | "trace" | "signal">,
+): (input: unknown, hooks?: TaskCallHooks) => ReturnType<typeof invokeWorkflowTask> {
   const toolId = mcp.taskTool as string;
-  return (input: unknown) => {
+  return (input: unknown, hooks?: TaskCallHooks) => {
     const { message, ...rest } = (input ?? {}) as Record<string, unknown>;
-    return invokeTaskNative(toolId, {
+    return invokeWorkflowTask(toolId, {
+      ...(hooks?.onStatus ? { onStatus: hooks.onStatus } : {}),
       conversationId: identity.conversationId,
       userId: identity.userId,
       accessToken: identity.accessToken,
       chatId: identity.chatId,
+      ...(identity.signal ? { signal: identity.signal } : {}),
       ...(identity.trace ? { trace: { ...identity.trace, kind: "task" } } : {}),
       ...(identity.baseUrl ? { baseUrl: identity.baseUrl } : {}),
       message: typeof message === "string" ? message : "",
@@ -157,7 +162,7 @@ export function workflowTaskInvoker(
  */
 export function componentAppInvoker(
   mcp: DiscoveredMCP,
-  identity: Pick<AppInvocationContext, "conversationId" | "userId" | "chatId" | "accessToken" | "trace">,
+  identity: Pick<AppInvocationContext, "conversationId" | "userId" | "chatId" | "accessToken" | "trace" | "signal">,
 ): (input: unknown) => ReturnType<typeof invokeTaskNative> {
   const toolId = mcp.component as string;
   return (input: unknown) => {
@@ -167,6 +172,7 @@ export function componentAppInvoker(
       userId: identity.userId,
       accessToken: identity.accessToken,
       chatId: identity.chatId,
+      ...(identity.signal ? { signal: identity.signal } : {}),
       ...(identity.trace ? { trace: { ...identity.trace, kind: mcp.task ? "task" : "tool" } } : {}),
       message: typeof message === "string" ? message : "",
       ...(Object.keys(hydrated).length ? { props: hydrated } : {}),
@@ -186,13 +192,13 @@ export function componentAppInvoker(
  * `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
+ * run still reported success. Observed live on a bank (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" | "trace">,
+  identity: Pick<AppInvocationContext, "conversationId" | "userId" | "chatId" | "accessToken" | "baseUrl" | "trace" | "signal">,
 ): (input: unknown) => ReturnType<typeof invokeTaskNative> {
   const toolId = String(mcp.methodName);
   return (input: unknown) => {
@@ -202,6 +208,7 @@ export function workflowAppInvoker(
       userId: identity.userId,
       accessToken: identity.accessToken,
       chatId: identity.chatId,
+      ...(identity.signal ? { signal: identity.signal } : {}),
       ...(identity.trace ? { trace: { ...identity.trace, kind: mcp.task ? "task" : "tool" } } : {}),
       ...(identity.baseUrl ? { baseUrl: identity.baseUrl } : {}),
       message: typeof message === "string" ? message : "",

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

@@ -111,6 +111,14 @@ export interface AppInvocationContext {
    * 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 calling run's stop signal: when the run stops, a task it follows is cancelled (`tasks/cancel`). */
+  signal?: AbortSignal;
+  /**
+   * WHAT THE TASK IS DOING NOW, as it changes: each new `statusMessage` of a task this call
+   * follows, from the tasks extension's own updates (docs/mcp/MCP_TASKS.md § 5, "what reaches
+   * the model"). The caller decides what to do with it; an Agent narrates it.
+   */
+  onStatus?: (statusMessage: string) => void;
   /** The caller's stream session — where the wizard renders and elicitation is answered. */
   conversationId?: string;
   userId?: string;

package/vendor/base/src/auth/agentSwitch.ts

@@ -0,0 +1,52 @@
+/**
+ * SWITCHING AN AGENT ON (docs/architecture/signal/AGENTS.md § 7, § 7a; UNO-221).
+ *
+ * An Agent folder says the most it may ever do (`access`). It does nothing until a person switches
+ * it on in this environment; that person is responsible for it (`act` on its token). Three rules:
+ *
+ *   - no daily budget, no Agent (§ 9): switching on is refused;
+ *   - the person must hold everything in `access`: refused, naming what they lack;
+ *   - its token carries `access` capped at what the owner holds, never more.
+ *
+ * Pure: who the person is and what they hold come in; the engine keeps the switch
+ * (`engine/src/agentKeys/agentSwitch.ts`).
+ */
+import { grantedTo } from "../security/permissions.js";
+
+/** What switching on needs from the Agent's folder. */
+export interface SwitchableAgent {
+  /** `<org>/<name>`. */
+  ref: string;
+  access: string[];
+  budget?: { perDay?: string };
+}
+
+/** The person switching it on, as the gate read them. */
+export interface SwitchingPerson {
+  id: string;
+  roles?: string[];
+  permissions?: string[];
+}
+
+export type SwitchCheck =
+  | { ok: true; ownerPermissions: string[] }
+  | { ok: false; reason: "no-budget" | "lacks-access"; missing: string[]; message: string };
+
+/** May this person switch this Agent on? When yes, what they hold is kept as the cap. */
+export function checkSwitchOn(agent: SwitchableAgent, person: SwitchingPerson): SwitchCheck {
+  if (!agent.budget?.perDay?.trim()) {
+    return { ok: false, reason: "no-budget", missing: [], message: `${agent.ref} has no daily budget: set budget.perDay in its agent.yaml` };
+  }
+  const held = grantedTo(person);
+  const missing = agent.access.filter((p) => !held.has(p as never));
+  if (missing.length) {
+    return { ok: false, reason: "lacks-access", missing, message: `To switch on ${agent.ref} you need ${missing.join(", ")}` };
+  }
+  return { ok: true, ownerPermissions: [...held].sort() };
+}
+
+/** What its token carries: its `access`, never more than the owner holds. */
+export function agentPermissions(access: string[], ownerPermissions: string[]): string[] {
+  const owner = new Set(ownerPermissions);
+  return access.filter((p) => owner.has(p));
+}