@agent-native/core 0.113.0 → 0.114.0

package/src/mcp/builtin-tools.ts

@@ -0,0 +1,1506 @@
+/**
+ * Generic cross-app MCP tools — a stable verb set every external agent gets
+ * regardless of which template it is talking to.
+ *
+ * These are merged into the MCP action registry by
+ * `createMCPServerForRequest` (see `build-server.ts`). **Precedence: template
+ * actions win.** If a template defines an action named `list_apps` /
+ * `open_app` / `ask_app` / `create_workspace_app` / `list_templates`, the
+ * template's `ActionEntry` overwrites the builtin of the same name. This is
+ * the same template-over-framework precedence `autoDiscoverActions` uses.
+ *
+ * | Tool                  | Side effects | Returns                                  |
+ * | --------------------- | ------------ | ---------------------------------------- |
+ * | `list_apps`           | none         | `{ apps: [{ id, url, running }] }`       |
+ * | `open_app`            | none         | `{ url }` (+ deep-link `link`)           |
+ * | `create_embed_session`| ticket mint  | `{ startUrl }` for MCP App iframes       |
+ * | `ask_app`             | agent loop   | `{ app, routedVia, response }` or task   |
+ * | `ask_app_status`      | none         | poll a durable `ask_app` task            |
+ * | `create_workspace_app`| scaffolds    | `{ name, url, port, deepLink }` (+ link) |
+ *
+ * `open_app` / `create_workspace_app` return an **absolute** URL on the
+ * *target* app's origin when it differs from this app (so a workspace link
+ * lands in the right app), and a relative path for the same app / standalone.
+ * `ask_app` routes to a *different* workspace app over A2A when possible and
+ * reports `routedVia: "a2a"`; otherwise it answers locally
+ * (`routedVia: "local"`) and never falsely claims cross-app delegation.
+ * | `list_templates`      | none         | `{ templates: [...] }` (allow-list only) |
+ *
+ * Node-only at call time (workspace resolution + scaffolding use `fs`), but
+ * the module has no top-level Node imports so it bundles fine alongside
+ * `mountMCP` — the Node bits are dynamically imported inside `run()`.
+ */
+
+import type { A2AApprovedAction, Task } from "../a2a/types.js";
+import type { ActionEntry } from "../agent/production-agent.js";
+import type { ActionTool } from "../agent/types.js";
+import { getConfiguredAppBasePath } from "../server/app-base-path.js";
+import { buildDeepLink } from "../server/deep-link.js";
+import { MCP_APP_CHAT_BRIDGE_QUERY_PARAM } from "../shared/embed-auth.js";
+import type { MCPConfig } from "./build-server.js";
+import { embedApp } from "./embed-app.js";
+import { fetchOrgApps, type OrgApp } from "./org-directory.js";
+
+/** Flat map of param name → JSON-schema property. */
+type Params = Record<
+  string,
+  { type: string; description?: string; enum?: string[] }
+>;
+
+/**
+ * Build an `ActionTool`. `parameters` is wrapped in the
+ * `{ type:"object", properties, required }` shape `createMCPServerForRequest`
+ * forwards verbatim as the MCP tool `inputSchema`.
+ */
+function tool(
+  description: string,
+  parameters?: Params,
+  required?: string[],
+): ActionTool {
+  if (!parameters) return { description };
+  return {
+    description,
+    parameters: {
+      type: "object",
+      properties: parameters,
+      ...(required && required.length ? { required } : {}),
+    },
+  };
+}
+
+/**
+ * The canonical app id this MCP server is mounted for. `MCPConfig.appId` is
+ * authoritative; fall back to lowercasing `name` (which is the capitalized
+ * app id at every call site) for back-compat with configs that predate the
+ * `appId` field.
+ */
+function currentAppId(config: MCPConfig): string {
+  return (config.appId || config.name || "app").toLowerCase();
+}
+
+const CONTROL_CHARS = new RegExp("[\\u0000-\\u001f\\u007f]");
+const ASK_APP_DEFAULT_INLINE_WAIT_MS = 20_000;
+const ASK_APP_MAX_INLINE_WAIT_MS = 25_000;
+const ASK_APP_POLL_INTERVAL_MS = 1_500;
+const ASK_APP_A2A_REQUEST_TIMEOUT_MS = 10_000;
+const ASK_APP_STATUS_RETRY_DELAYS_MS = [250, 750, 1_500] as const;
+const ASK_APP_TERMINAL_STATES = new Set<string>([
+  "completed",
+  "failed",
+  "canceled",
+  "input-required",
+]);
+
+class AskAppInlineDeadlineError extends Error {
+  constructor() {
+    super("ask_app inline wait deadline reached");
+    this.name = "AskAppInlineDeadlineError";
+  }
+}
+
+type AskAppRequestMeta = { origin?: string; basePath?: string };
+
+interface AskAppRoute {
+  app: string;
+  origin: string;
+  routedVia: "local" | "a2a";
+  requestOrigin?: string;
+  note?: string;
+}
+
+interface AskAppTaskResult {
+  app: string;
+  routedVia: "local" | "a2a";
+  taskId: string;
+  status: string;
+  response?: string;
+  error?: string;
+  inputRequired?: string;
+  note?: string;
+  pollAfterMs?: number;
+  poll?: {
+    tool: "ask_app_status";
+    arguments: { app: string; taskId: string };
+  };
+  message?: string;
+  statusRead?: "unavailable";
+  retryable?: true;
+  errorCategory?: AskAppStatusErrorCategory;
+  attempts?: number;
+}
+
+type AskAppStatusErrorCategory =
+  | "transport"
+  | "timeout"
+  | "upstream_5xx"
+  | "rate_limited";
+
+function safeAppPath(raw: unknown): string | null {
+  if (typeof raw !== "string" || !raw.trim()) return null;
+  const value = raw.trim();
+  if (CONTROL_CHARS.test(value)) return null;
+  if (!value.startsWith("/")) return null;
+  if (value.startsWith("//") || value.startsWith("/\\")) return null;
+  if (/^\/[a-z][a-z0-9+.-]*:/i.test(value)) return null;
+  return value;
+}
+
+function appendParamsToPath(
+  path: string,
+  params: Record<string, string | number | boolean> | undefined,
+): string {
+  if (!params || Object.keys(params).length === 0) return path;
+  const url = new URL(path, "http://agent-native.invalid");
+  for (const [key, value] of Object.entries(params)) {
+    url.searchParams.set(key, String(value));
+  }
+  return `${url.pathname}${url.search}${url.hash}`;
+}
+
+function viewToAppPath(view: string): string | null {
+  const value = view.trim();
+  if (!value) return null;
+  return safeAppPath(value.startsWith("/") ? value : `/${value}`);
+}
+
+function withConfiguredBasePath(path: string): string {
+  const base = getConfiguredAppBasePath();
+  if (!base || path === base || path.startsWith(`${base}/`)) return path;
+  return `${base}${path}`;
+}
+
+function withMcpChatBridgeParam(path: string): string {
+  try {
+    const url = new URL(path, "http://agent-native.invalid");
+    url.searchParams.set(MCP_APP_CHAT_BRIDGE_QUERY_PARAM, "1");
+    return `${url.pathname}${url.search}${url.hash}`;
+  } catch {
+    return path;
+  }
+}
+
+function agentNativeA2AEndpoint(urlOrOrigin: string): string {
+  const value = urlOrOrigin.replace(/\/+$/, "");
+  try {
+    const parsed = new URL(value);
+    const pathname = parsed.pathname.replace(/\/+$/, "");
+    if (pathname.endsWith("/_agent-native/a2a") || pathname.endsWith("/a2a")) {
+      return value;
+    }
+  } catch {
+    // Fall through and append the conventional Agent Native endpoint.
+  }
+  return `${value}/_agent-native/a2a`;
+}
+
+function selfA2AEndpointUrl(requestMeta?: AskAppRequestMeta): string | null {
+  const origin = requestMeta?.origin?.replace(/\/+$/, "");
+  if (!origin) return null;
+  const basePath = requestMeta?.basePath || getConfiguredAppBasePath();
+  return agentNativeA2AEndpoint(`${origin}${basePath}`);
+}
+
+function boundedAskAppWaitMs(raw: unknown): number {
+  if (raw == null || raw === "") return ASK_APP_DEFAULT_INLINE_WAIT_MS;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed)) return ASK_APP_DEFAULT_INLINE_WAIT_MS;
+  return Math.max(0, Math.min(ASK_APP_MAX_INLINE_WAIT_MS, Math.trunc(parsed)));
+}
+
+function isExplicitAsyncAsk(raw: unknown): boolean {
+  return raw === true || raw === "true" || raw === 1 || raw === "1";
+}
+
+function taskState(task: Task): string {
+  return String(task.status?.state ?? "unknown");
+}
+
+function isTerminalTask(task: Task): boolean {
+  return ASK_APP_TERMINAL_STATES.has(taskState(task));
+}
+
+function taskText(task: Task): string {
+  return (
+    task.status.message?.parts
+      ?.filter(
+        (part): part is { type: "text"; text: string } => part.type === "text",
+      )
+      .map((part) => part.text)
+      .join("\n")
+      .trim() ?? ""
+  );
+}
+
+function askAppTaskResult(route: AskAppRoute, task: Task): AskAppTaskResult {
+  const status = taskState(task);
+  const response = taskText(task);
+  const base = {
+    app: route.app,
+    routedVia: route.routedVia,
+    taskId: task.id,
+    status,
+    ...(route.note ? { note: route.note } : {}),
+  };
+
+  if (status === "completed") {
+    return {
+      ...base,
+      response: response || "(no response)",
+    };
+  }
+
+  if (status === "failed" || status === "canceled") {
+    return {
+      ...base,
+      ...(response ? { response } : {}),
+      error: response || `ask_app task ${status}.`,
+    };
+  }
+
+  if (status === "input-required") {
+    const inputRequired =
+      response || "The agent needs additional input before it can continue.";
+    return {
+      ...base,
+      response: inputRequired,
+      inputRequired,
+      message: inputRequired,
+    };
+  }
+
+  return {
+    ...base,
+    pollAfterMs: ASK_APP_POLL_INTERVAL_MS,
+    poll: {
+      tool: "ask_app_status",
+      arguments: { app: route.app, taskId: task.id },
+    },
+    message:
+      `ask_app is still ${status}. Call ask_app_status with ` +
+      `taskId "${task.id}" to retrieve the final response.`,
+  };
+}
+
+/**
+ * Same shape as `askAppTaskResult`, but built from an in-process
+ * `ask-app-inline-tasks.ts` snapshot instead of an A2A `Task` — used by the
+ * no-origin fallback (no A2A task exists to describe). Kept field-for-field
+ * identical so `ask_app` / `ask_app_status` callers can't tell which backing
+ * store answered.
+ */
+function askAppInlineTaskResult(
+  selfId: string,
+  taskId: string,
+  inline: {
+    status: "working" | "completed" | "failed";
+    response?: string;
+    error?: string;
+  },
+  note?: string,
+): AskAppTaskResult {
+  const base = {
+    app: selfId,
+    routedVia: "local" as const,
+    taskId,
+    status: inline.status,
+    ...(note ? { note } : {}),
+  };
+
+  if (inline.status === "completed") {
+    return { ...base, response: inline.response || "(no response)" };
+  }
+
+  if (inline.status === "failed") {
+    return { ...base, error: inline.error || "ask_app task failed." };
+  }
+
+  return {
+    ...base,
+    pollAfterMs: ASK_APP_POLL_INTERVAL_MS,
+    poll: {
+      tool: "ask_app_status",
+      arguments: { app: selfId, taskId },
+    },
+    message:
+      `ask_app is still ${inline.status}. Call ask_app_status with ` +
+      `taskId "${taskId}" to retrieve the final response.`,
+  };
+}
+
+async function createA2AClientForAskApp(
+  origin: string,
+  requestOrigin?: string,
+  deadline?: number,
+): Promise<{
+  client: import("../a2a/client.js").A2AClient;
+  metadata: Record<string, unknown>;
+}> {
+  const { A2AClient } = await import("../a2a/client.js");
+  const { resolveA2ACallerAuth } = await import("../a2a/caller-auth.js");
+  const auth = await resolveA2ACallerAuth();
+  const metadata: Record<string, unknown> = {};
+  if (auth.userEmail) metadata.userEmail = auth.userEmail;
+  if (auth.orgDomain) metadata.orgDomain = auth.orgDomain;
+  if (requestOrigin) metadata.requestOrigin = requestOrigin;
+  const remainingMs = deadline == null ? null : deadline - Date.now();
+  return {
+    client: new A2AClient(origin, auth.apiKey, {
+      requestTimeoutMs:
+        remainingMs == null
+          ? ASK_APP_A2A_REQUEST_TIMEOUT_MS
+          : Math.max(1, Math.min(ASK_APP_A2A_REQUEST_TIMEOUT_MS, remainingMs)),
+      ...(auth.apiKeyFallbacks
+        ? { fallbackApiKeys: auth.apiKeyFallbacks }
+        : {}),
+    }),
+    metadata,
+  };
+}
+
+async function runBeforeAskAppDeadline<T>(
+  operation: () => Promise<T>,
+  deadline: number,
+): Promise<T> {
+  const remainingMs = deadline - Date.now();
+  if (remainingMs <= 0) throw new AskAppInlineDeadlineError();
+
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      operation(),
+      new Promise<T>((_resolve, reject) => {
+        timeout = setTimeout(
+          () => reject(new AskAppInlineDeadlineError()),
+          remainingMs,
+        );
+      }),
+    ]);
+  } finally {
+    if (timeout) clearTimeout(timeout);
+  }
+}
+
+async function waitForA2ATask(
+  client: import("../a2a/client.js").A2AClient,
+  initialTask: Task,
+  deadline: number | undefined,
+): Promise<Task> {
+  if (deadline == null || isTerminalTask(initialTask)) return initialTask;
+  let current = initialTask;
+
+  while (!isTerminalTask(current)) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) return current;
+    await new Promise((resolve) =>
+      setTimeout(resolve, Math.min(ASK_APP_POLL_INTERVAL_MS, remaining)),
+    );
+    if (Date.now() >= deadline) return current;
+    try {
+      current = await runBeforeAskAppDeadline(
+        () => client.getTask(initialTask.id),
+        deadline,
+      );
+    } catch (err) {
+      if (err instanceof AskAppInlineDeadlineError) return current;
+      if (!isTransientAskAppStatusError(err)) throw err;
+      if (Date.now() >= deadline) return current;
+    }
+  }
+
+  return current;
+}
+
+async function submitAskAppA2ATask(
+  route: AskAppRoute,
+  message: string,
+  maxWaitMs: number,
+  approvedActions?: A2AApprovedAction[],
+): Promise<AskAppTaskResult> {
+  const deadline = maxWaitMs > 0 ? Date.now() + maxWaitMs : undefined;
+  const { client, metadata } = await createA2AClientForAskApp(
+    route.origin,
+    route.requestOrigin,
+    deadline,
+  );
+  const task = await client.send(
+    {
+      role: "user",
+      parts: [{ type: "text", text: message }],
+    },
+    {
+      async: true,
+      metadata,
+      ...(approvedActions?.length ? { approvedActions } : {}),
+    },
+  );
+  const finalOrRunning = await waitForA2ATask(client, task, deadline);
+  return askAppTaskResult(route, finalOrRunning);
+}
+
+async function fetchAskAppA2ATask(
+  route: AskAppRoute,
+  taskId: string,
+): Promise<AskAppTaskResult> {
+  const { client } = await createA2AClientForAskApp(route.origin);
+  const maxAttempts = ASK_APP_STATUS_RETRY_DELAYS_MS.length + 1;
+  for (
+    let attempt = 0;
+    attempt <= ASK_APP_STATUS_RETRY_DELAYS_MS.length;
+    attempt++
+  ) {
+    const startedAt = Date.now();
+    try {
+      const task = await client.getTask(taskId);
+      return askAppTaskResult(route, task);
+    } catch (err) {
+      const delayMs = ASK_APP_STATUS_RETRY_DELAYS_MS[attempt];
+      const errorCategory = askAppStatusErrorCategory(err);
+      const retryable = errorCategory != null;
+      const willRetry = retryable && delayMs != null;
+      if (retryable) {
+        console.warn("[ask_app_status] tasks/get attempt failed", {
+          app: route.app,
+          routedVia: route.routedVia,
+          taskId,
+          originHost: askAppStatusOriginHost(route.origin),
+          attempt: attempt + 1,
+          maxAttempts,
+          elapsedMs: Date.now() - startedAt,
+          errorCategory,
+          errorName: err instanceof Error ? err.name : typeof err,
+          causeCode: askAppStatusErrorCauseCode(err),
+          willRetry,
+        });
+      }
+
+      if (!retryable) {
+        throw err;
+      }
+      if (delayMs == null) {
+        return askAppStatusReadUnavailableResult(
+          route,
+          taskId,
+          errorCategory,
+          maxAttempts,
+        );
+      }
+      await new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
+  }
+  throw new Error("ask_app_status retry loop exited unexpectedly.");
+}
+
+function isTransientAskAppStatusError(err: unknown): boolean {
+  return askAppStatusErrorCategory(err) != null;
+}
+
+function askAppStatusErrorCategory(
+  err: unknown,
+): AskAppStatusErrorCategory | null {
+  const message = err instanceof Error ? err.message : String(err ?? "");
+  const causeCode = askAppStatusErrorCauseCode(err) ?? "";
+  const diagnostic = `${message} ${causeCode}`;
+  if (/A2A request failed \(429\)/i.test(message)) return "rate_limited";
+  if (/A2A request failed \((?:500|502|503|504)\)/i.test(message)) {
+    return "upstream_5xx";
+  }
+  if (/etimedout|timeout|aborted|aborterror/i.test(diagnostic)) {
+    return "timeout";
+  }
+  if (
+    /\bfetch failed\b|failed to fetch|networkerror|socket hang up|econnreset/i.test(
+      diagnostic,
+    )
+  ) {
+    return "transport";
+  }
+  return null;
+}
+
+function askAppStatusErrorCauseCode(err: unknown): string | undefined {
+  if (!(err instanceof Error)) return undefined;
+  const directCode = (err as Error & { code?: unknown }).code;
+  if (typeof directCode === "string" && directCode.trim()) {
+    return directCode.trim();
+  }
+  if (!err.cause || typeof err.cause !== "object") return undefined;
+  const code = (err.cause as { code?: unknown }).code;
+  return typeof code === "string" && code.trim() ? code.trim() : undefined;
+}
+
+function askAppStatusOriginHost(origin: string): string {
+  try {
+    return new URL(origin).host;
+  } catch {
+    return "unknown";
+  }
+}
+
+function askAppStatusReadUnavailableResult(
+  route: AskAppRoute,
+  taskId: string,
+  errorCategory: AskAppStatusErrorCategory,
+  attempts: number,
+): AskAppTaskResult {
+  return {
+    app: route.app,
+    routedVia: route.routedVia,
+    taskId,
+    status: "unknown",
+    statusRead: "unavailable",
+    retryable: true,
+    errorCategory,
+    attempts,
+    pollAfterMs: ASK_APP_POLL_INTERVAL_MS,
+    poll: {
+      tool: "ask_app_status",
+      arguments: { app: route.app, taskId },
+    },
+    message:
+      "The durable ask_app task status could not be read after bounded retries. " +
+      "The task may still be running or completed. Retry ask_app_status " +
+      "with the same app and taskId; do not resubmit ask_app.",
+  };
+}
+
+/**
+ * Resolve the absolute origin of a *target* workspace app (e.g.
+ * `http://127.0.0.1:8101`) so cross-app deep links / A2A calls point at the
+ * right app instead of the current request's origin. Reuses the same
+ * workspace resolution `list_apps` / the stdio proxy use.
+ *
+ * Returns `null` when:
+ *   - the target is the current app (caller should keep relative behavior),
+ *   - there is no workspace info (standalone / single app), or
+ *   - the target app is unknown.
+ */
+async function resolveTargetAppOrigin(
+  config: MCPConfig,
+  targetAppId: string,
+): Promise<{ origin: string; id: string } | null> {
+  const target = targetAppId.trim().toLowerCase();
+  if (!target || target === currentAppId(config)) return null;
+  try {
+    const { resolveWorkspace } = await import("./workspace-resolve.js");
+    const ws = await resolveWorkspace();
+    if (!ws.isWorkspace) return null;
+    const match = ws.apps.find((a) => a.id.toLowerCase() === target);
+    if (!match) return null;
+    return { origin: match.url, id: match.id };
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// list_apps
+// ---------------------------------------------------------------------------
+
+function listAppsTool(
+  config: MCPConfig,
+  requestMeta?: { origin?: string },
+): ActionEntry {
+  return {
+    tool: tool(
+      "List the workspace apps and their URLs. Use this to discover which " +
+        "apps exist before opening or asking one. In a single-app project " +
+        "this returns just that app. When an org directory is configured " +
+        "this also includes the org's deployed sibling apps.",
+    ),
+    readOnly: true,
+    parallelSafe: true,
+    run: async () => {
+      const { resolveWorkspace } = await import("./workspace-resolve.js");
+      const ws = await resolveWorkspace();
+
+      // The MCP request is served BY the current app, so it is provably
+      // reachable at the inbound request origin — that beats a guessed
+      // `PORT || 5173` probe (which reports the wrong URL + `running:false`
+      // whenever the dev server picked a non-default port, e.g. `agent-
+      // native dev` on :8080). For the entry that IS this app (the sole
+      // entry when single-app, or the id matching `config.appId` in a
+      // workspace) prefer the live origin; other workspace apps keep their
+      // probed values.
+      const liveOrigin = requestMeta?.origin?.replace(/\/+$/, "") || "";
+      let livePort = 0;
+      if (liveOrigin) {
+        try {
+          const u = new URL(liveOrigin);
+          livePort = Number(u.port) || (u.protocol === "https:" ? 443 : 80);
+        } catch {
+          livePort = 0;
+        }
+      }
+      const selfId = (config.appId ?? "").toLowerCase();
+      const isSelf = (id: string) =>
+        !!liveOrigin &&
+        (!ws.isWorkspace || (!!selfId && id.toLowerCase() === selfId));
+
+      interface AppEntry {
+        id: string;
+        url: string;
+        port: number | undefined;
+        running: boolean;
+        source: "workspace" | "org-directory";
+      }
+
+      const apps: AppEntry[] = ws.apps.map((a) =>
+        isSelf(a.id)
+          ? {
+              id: a.id,
+              url: liveOrigin,
+              port: (livePort || a.port) as number | undefined,
+              running: true,
+              source: "workspace" as const,
+            }
+          : {
+              id: a.id,
+              url: a.url,
+              port: a.port as number | undefined,
+              running: a.running,
+              source: "workspace" as const,
+            },
+      );
+      const seenIds = new Set(apps.map((a) => a.id.toLowerCase()));
+      const seenOrigins = new Set(apps.map((a) => a.url.replace(/\/+$/, "")));
+
+      // Merge the org directory's deployed sibling apps. Inactive (no env)
+      // or any failure ⇒ fetchOrgApps() returns [] and this is a no-op, so
+      // the existing local/workspace behavior is preserved exactly.
+      const orgApps = await fetchOrgApps({
+        selfId: currentAppId(config),
+      }).catch(() => [] as OrgApp[]);
+      for (const oa of orgApps) {
+        const idKey = oa.id.toLowerCase();
+        const originKey = oa.url.replace(/\/+$/, "");
+        // Dedupe by id OR origin — a workspace app already listed wins.
+        if (seenIds.has(idKey) || seenOrigins.has(originKey)) continue;
+        seenIds.add(idKey);
+        seenOrigins.add(originKey);
+        apps.push({
+          id: oa.id,
+          url: oa.url,
+          port: undefined,
+          running: true,
+          source: "org-directory",
+        });
+      }
+
+      return {
+        workspace: ws.isWorkspace,
+        gatewayUrl: ws.gatewayUrl,
+        apps,
+      };
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// open_app
+// ---------------------------------------------------------------------------
+
+function openAppTool(
+  config: MCPConfig,
+  requestMeta?: { origin?: string },
+): ActionEntry {
+  return {
+    tool: tool(
+      "Build a deep link that opens an app at a specific view/record or " +
+        "focused route/component. No side " +
+        "effects — returns a URL the user can click to land in the running UI. " +
+        "Set embed:true when a UI-capable MCP host should render the live app " +
+        "or focused route/component inline. Omit view and path to land on the " +
+        "app's home page.",
+      {
+        app: { type: "string", description: "App id, e.g. 'mail'" },
+        view: {
+          type: "string",
+          description:
+            "Target view, e.g. 'inbox' (maps to navigate command). Optional — omit (along with path) to open the app's home page.",
+        },
+        path: {
+          type: "string",
+          description:
+            "Optional app route to open directly, e.g. '/extensions/abc', '/adhoc/q2', or '/chart?panel=...'. Must be same-origin relative. Omit (along with view) to open the app's home page.",
+        },
+        params: {
+          type: "object",
+          description:
+            "Optional record-focus / filter params, e.g. { threadId: 'abc' }",
+        },
+        embed: {
+          type: "boolean",
+          description:
+            "Render the full app or focused route/component inline in MCP Apps when the host supports it.",
+        },
+        chrome: {
+          type: "string",
+          enum: ["full", "minimal"],
+          description:
+            "Embed chrome preference for compatible app routes. Defaults to full.",
+        },
+      },
+      ["app"],
+    ),
+    readOnly: true,
+    parallelSafe: true,
+    run: async (args: Record<string, any>) => {
+      const app = String(args.app ?? "").trim();
+      const view = String(args.view ?? "").trim();
+      // `safeAppPath` rejects anything that isn't a leading-slash same-origin
+      // path. When the caller passes nothing, fall back to the app's root so a
+      // bare `open_app({app:"dispatch"})` lands on the home page instead of
+      // throwing. The model self-corrects on the retry today, but the extra
+      // round-trip wastes a turn and looks broken to the user.
+      const path = safeAppPath(args.path) || (view ? null : "/");
+      if (!app) {
+        throw new Error("open_app requires 'app'.");
+      }
+      let params: Record<string, string | number | boolean> | undefined;
+      const raw = args.params;
+      if (raw && typeof raw === "object") {
+        params = raw as Record<string, string | number | boolean>;
+      } else if (typeof raw === "string" && raw.trim()) {
+        try {
+          params = JSON.parse(raw);
+        } catch {
+          params = undefined;
+        }
+      }
+      const embeddedParam = params?.embed;
+      const chromeParam = params?.chrome;
+      let embed = args.embed === true || args.embed === "true";
+      if (
+        args.embed == null &&
+        (embeddedParam === true || embeddedParam === "true")
+      ) {
+        embed = true;
+      } else if (
+        args.embed == null &&
+        (embeddedParam === false || embeddedParam === "false")
+      ) {
+        embed = false;
+      }
+      if (
+        embeddedParam === true ||
+        embeddedParam === false ||
+        embeddedParam === "true" ||
+        embeddedParam === "false"
+      ) {
+        delete params?.embed;
+      }
+
+      const chrome =
+        typeof args.chrome === "string"
+          ? args.chrome
+          : chromeParam === "full" || chromeParam === "minimal"
+            ? chromeParam
+            : undefined;
+      if (chromeParam === "full" || chromeParam === "minimal") {
+        delete params?.chrome;
+      }
+      if (params && Object.keys(params).length === 0) params = undefined;
+
+      const directViewPath = embed && view ? viewToAppPath(view) : null;
+      const relUrl = path
+        ? appendParamsToPath(path, params)
+        : directViewPath
+          ? appendParamsToPath(directViewPath, params)
+          : buildDeepLink({ app, view, params });
+      const sameAppUrl =
+        path || directViewPath ? withConfiguredBasePath(relUrl) : relUrl;
+
+      // Cross-app target in a workspace: resolve the TARGET app's origin and
+      // return an absolute URL. Otherwise the MCP layer would prefix the
+      // relative path with the CURRENT request origin, landing the user in
+      // the wrong app (e.g. open_app({app:"calendar"}) served from Mail).
+      // Same-app / standalone keeps the relative path (current behavior).
+      const targetApp = await resolveTargetAppOrigin(config, app);
+      const appUrl = targetApp
+        ? `${targetApp.origin.replace(/\/+$/, "")}${relUrl}`
+        : sameAppUrl;
+      const url = appUrl;
+      let embedStartUrl: string | undefined;
+      let embedTargetPath: string | undefined;
+      let embedExpiresAt: number | undefined;
+
+      if (embed && !targetApp) {
+        const { getRequestContext } =
+          await import("../server/request-context.js");
+        const ctx = getRequestContext();
+        const ownerEmail = ctx?.userEmail?.trim();
+        if (ownerEmail) {
+          const { normalizeEmbedTargetPath, createEmbedSessionTicket } =
+            await import("../server/embed-session.js");
+          const { buildEmbedStartPath } =
+            await import("../server/embed-route.js");
+          const targetPath = normalizeEmbedTargetPath(
+            withMcpChatBridgeParam(url),
+            requestMeta?.origin,
+          );
+          if (targetPath) {
+            const ticket = await createEmbedSessionTicket({
+              ownerEmail,
+              orgId: ctx?.orgId,
+              targetPath,
+              scope: chrome ?? null,
+            });
+            const startPath = buildEmbedStartPath(ticket.ticket);
+            embedStartUrl = requestMeta?.origin
+              ? new URL(startPath, requestMeta.origin).toString()
+              : startPath;
+            embedTargetPath = targetPath;
+            embedExpiresAt = ticket.expiresAt;
+          }
+        }
+      }
+
+      return {
+        app,
+        ...(view ? { view } : {}),
+        ...(path ? { path } : {}),
+        url,
+        ...(embedStartUrl ? { embedStartUrl } : {}),
+        ...(embedTargetPath ? { embedTargetPath } : {}),
+        ...(embedExpiresAt ? { embedExpiresAt } : {}),
+        embed,
+      };
+    },
+    link: ({ result }) => {
+      if (!result || typeof result !== "object") return null;
+      const r = result as {
+        url?: string;
+        app?: string;
+        view?: string;
+        embed?: boolean;
+      };
+      if (r.embed) return null;
+      if (!r.url) return null;
+      return {
+        url: r.url,
+        label: `Open ${r.app ?? "app"}`,
+        view: r.view,
+      };
+    },
+    mcpApp: {
+      resource: embedApp({
+        title: "Open app",
+        description: "Render the requested app route inline.",
+        iframeTitle: "Agent Native app",
+        openLabel: "Open app",
+      }),
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// create_embed_session
+// ---------------------------------------------------------------------------
+
+function createEmbedSessionTool(requestMeta?: {
+  origin?: string;
+}): ActionEntry {
+  return {
+    tool: {
+      ...tool(
+        "MCP Apps helper: create a one-time browser embed session for a same-origin app URL. Usually called by an MCP App iframe, not directly by the model.",
+        {
+          url: {
+            type: "string",
+            description:
+              "Same-origin absolute URL or app-relative path to embed.",
+          },
+          path: {
+            type: "string",
+            description: "Same-origin app-relative path to embed.",
+          },
+          chrome: {
+            type: "string",
+            enum: ["full", "minimal"],
+            description: "Embed chrome preference. Defaults to full.",
+          },
+        },
+      ),
+      _meta: { ui: { visibility: ["app"] } },
+    } as ActionTool,
+    // App-only bootstrap helper: the ticket becomes a normal browser session,
+    // so keep it write-scoped until embed sessions can enforce MCP scopes.
+    readOnly: false,
+    parallelSafe: true,
+    run: async (args: Record<string, any>) => {
+      const { getRequestContext } =
+        await import("../server/request-context.js");
+      const ctx = getRequestContext();
+      const ownerEmail = ctx?.userEmail?.trim();
+      if (!ownerEmail) {
+        throw new Error(
+          "create_embed_session requires an authenticated MCP caller.",
+        );
+      }
+
+      const { normalizeEmbedTargetPath, createEmbedSessionTicket } =
+        await import("../server/embed-session.js");
+      const { buildEmbedStartPath } = await import("../server/embed-route.js");
+      const rawTarget =
+        typeof args.url === "string" && args.url.trim()
+          ? args.url
+          : typeof args.path === "string"
+            ? args.path
+            : "";
+      const targetPath = normalizeEmbedTargetPath(
+        rawTarget,
+        requestMeta?.origin,
+      );
+      if (!targetPath) {
+        throw new Error(
+          "create_embed_session can only embed same-origin app-relative URLs.",
+        );
+      }
+
+      const ticket = await createEmbedSessionTicket({
+        ownerEmail,
+        orgId: ctx?.orgId,
+        targetPath,
+        scope: typeof args.chrome === "string" ? args.chrome : null,
+      });
+      const startPath = buildEmbedStartPath(ticket.ticket);
+      const startUrl = requestMeta?.origin
+        ? new URL(startPath, requestMeta.origin).toString()
+        : startPath;
+      return {
+        startUrl,
+        targetPath,
+        expiresAt: ticket.expiresAt,
+      };
+    },
+  };
+}
+
+/**
+ * Route an `ask_app` message to a *different* app's agent over A2A. Shared by
+ * the workspace-resolved path and the org-directory-resolved path so the A2A
+ * call logic is not duplicated. `origin` is the target app's A2A base
+ * (workspace dev origin or the directory's `a2aUrl`); `id` is reported back.
+ *
+ * Throws on failure so the caller can be honest — it never falls back to this
+ * app's agent and pretends it was the target.
+ */
+async function routeAskOverA2A(
+  origin: string,
+  id: string,
+  message: string,
+  options?: {
+    durable?: boolean;
+    maxWaitMs?: number;
+    requestOrigin?: string;
+    approvedActions?: A2AApprovedAction[];
+  },
+): Promise<
+  { app: string; routedVia: "a2a"; response: string } | AskAppTaskResult
+> {
+  if (options?.durable) {
+    return submitAskAppA2ATask(
+      {
+        app: id,
+        origin: agentNativeA2AEndpoint(origin),
+        routedVia: "a2a",
+        requestOrigin: options.requestOrigin ?? origin,
+      },
+      message,
+      options.maxWaitMs ?? ASK_APP_DEFAULT_INLINE_WAIT_MS,
+      options.approvedActions,
+    );
+  }
+  const { callAgent } = await import("../a2a/client.js");
+  const { resolveA2ACallerAuth } = await import("../a2a/caller-auth.js");
+  // The MCP handler runs inside `runWithRequestContext`, so this is the
+  // verified caller identity and org scope. Reuse the same auth resolver as
+  // org-directory discovery so the directory lookup and actual A2A call are
+  // scoped the same way.
+  const auth = await resolveA2ACallerAuth();
+  const response = await callAgent(origin, message, {
+    apiKey: auth.apiKey,
+    userEmail: auth.userEmail,
+    orgDomain: auth.orgDomain,
+    orgSecret: auth.orgSecret,
+    requestOrigin: options?.requestOrigin,
+    approvedActions: options?.approvedActions,
+    // Bound the wait — cross-app A2A polls async by default.
+    timeoutMs: 5 * 60_000,
+  });
+  return { app: id, routedVia: "a2a", response };
+}
+
+async function resolveAskAppStatusRoute(
+  config: MCPConfig,
+  requestedApp: string,
+  requestMeta?: AskAppRequestMeta,
+): Promise<AskAppRoute> {
+  const selfId = currentAppId(config);
+  const normalized = requestedApp.trim().toLowerCase();
+  const selfEndpointUrl = selfA2AEndpointUrl(requestMeta);
+
+  if (!normalized || normalized === selfId) {
+    if (!selfEndpointUrl) {
+      throw new Error(
+        "ask_app_status requires a running app origin for local tasks.",
+      );
+    }
+    return {
+      app: selfId,
+      origin: selfEndpointUrl,
+      routedVia: "local",
+      requestOrigin: requestMeta?.origin,
+    };
+  }
+
+  const targetApp = await resolveTargetAppOrigin(config, requestedApp);
+  if (targetApp) {
+    return {
+      app: targetApp.id,
+      origin: agentNativeA2AEndpoint(targetApp.origin),
+      routedVia: "a2a",
+      requestOrigin: targetApp.origin,
+    };
+  }
+
+  const orgApps = await fetchOrgApps({ selfId }).catch(() => [] as OrgApp[]);
+  const dirMatch = orgApps.find((a) => a.id === normalized);
+  if (dirMatch) {
+    return {
+      app: dirMatch.id,
+      origin: agentNativeA2AEndpoint(dirMatch.a2aUrl),
+      routedVia: "a2a",
+      requestOrigin: dirMatch.url,
+    };
+  }
+
+  throw new Error(`No reachable ask_app task route for app "${requestedApp}".`);
+}
+
+// ---------------------------------------------------------------------------
+// ask_app
+// ---------------------------------------------------------------------------
+
+function askAppTool(
+  config: MCPConfig,
+  requestMeta?: AskAppRequestMeta,
+): ActionEntry {
+  return {
+    tool: tool(
+      "Send a natural-language message to an app's AI agent and get its " +
+        "response. Use this first for natural-language investigation, " +
+        "diagnosis, multi-step work, and changes; it runs with the app's " +
+        "full skills, instructions, tools, and context. Use direct action " +
+        "tools only for a known, bounded read or simple UI handoff. In a " +
+        "single-app project the 'app' " +
+        "param is optional (defaults to this app). When 'app' names a " +
+        "different workspace app it is routed there over A2A; the result's " +
+        "'routedVia' field reports whether it ran cross-app or locally. " +
+        "On hosted MCP, long tasks may return a durable taskId instead of a " +
+        "final response; call ask_app_status with that taskId until completed.",
+      {
+        app: {
+          type: "string",
+          description: "App id to route to (optional in a single-app project)",
+        },
+        message: {
+          type: "string",
+          description: "The message to send to the app's agent",
+        },
+        async: {
+          type: "boolean",
+          description:
+            "When true, start a durable task and return immediately with a taskId.",
+        },
+        maxWaitMs: {
+          type: "number",
+          description:
+            "Maximum time to wait inline before returning a taskId. Hosted MCP clamps this to 25000ms.",
+        },
+        approvedActions: {
+          type: "array",
+          description:
+            "Exact downstream tool calls the user explicitly authorized in this chat. Never infer authorization or include a different action.",
+          items: {
+            type: "object",
+            properties: {
+              tool: { type: "string" },
+              input: { type: "object", additionalProperties: true },
+            },
+            required: ["tool", "input"],
+          },
+        } as any,
+      },
+      ["message"],
+    ),
+    run: async (args: Record<string, any>) => {
+      const message = String(args.message ?? "").trim();
+      if (!message) throw new Error("ask_app requires a 'message'.");
+      const requestedApp = String(args.app ?? "").trim();
+      const selfId = currentAppId(config);
+      const useDurableA2A = Boolean(requestMeta?.origin);
+      const maxWaitMs = isExplicitAsyncAsk(args.async)
+        ? 0
+        : boundedAskAppWaitMs(args.maxWaitMs);
+      const approvedActions = Array.isArray(args.approvedActions)
+        ? (args.approvedActions as A2AApprovedAction[])
+        : undefined;
+
+      // Cross-app: the caller named a *different* workspace app. Route the
+      // message to THAT app's agent over A2A (its `/_agent-native/a2a`
+      // endpoint runs the real agent loop with JWT identity) rather than
+      // silently answering from this app's agent and claiming delegation.
+      const targetApp = await resolveTargetAppOrigin(config, requestedApp);
+      if (targetApp) {
+        try {
+          return await routeAskOverA2A(
+            targetApp.origin,
+            targetApp.id,
+            message,
+            {
+              durable: useDurableA2A,
+              maxWaitMs,
+              requestOrigin: targetApp.origin,
+              approvedActions,
+            },
+          );
+        } catch (err: any) {
+          // Be honest: routing was attempted and failed — do NOT fall back to
+          // this app's agent and pretend it was the target.
+          throw new Error(
+            `Failed to route ask_app to "${targetApp.id}" via A2A: ` +
+              `${err?.message ?? err}`,
+          );
+        }
+      }
+
+      // Not a known local/workspace app — try the org directory. When a
+      // directory is configured and the requested app is one of the org's
+      // deployed sibling apps, route to it over A2A (same path as above,
+      // against its `a2aUrl`). Inactive directory / any failure ⇒ orgApps is
+      // [] and this is skipped, preserving the exact local-only behavior.
+      if (requestedApp && requestedApp.toLowerCase() !== selfId) {
+        const orgApps = await fetchOrgApps({ selfId }).catch(
+          () => [] as OrgApp[],
+        );
+        const dirMatch = orgApps.find(
+          (a) => a.id === requestedApp.toLowerCase(),
+        );
+        if (dirMatch) {
+          try {
+            return await routeAskOverA2A(
+              dirMatch.a2aUrl,
+              dirMatch.id,
+              message,
+              {
+                durable: useDurableA2A,
+                maxWaitMs,
+                requestOrigin: dirMatch.url,
+                approvedActions,
+              },
+            );
+          } catch (err: any) {
+            throw new Error(
+              `Failed to route ask_app to "${dirMatch.id}" via A2A ` +
+                `(org directory): ${err?.message ?? err}`,
+            );
+          }
+        }
+      }
+
+      // Same app (or no workspace / unknown target): answer locally with this
+      // app's own ask-agent handler — the same entry point the HTTP MCP mount
+      // + A2A use, so there is no second agent runner.
+      if (!config.askAgent) {
+        throw new Error(
+          "This app does not expose an agent (no ask-agent handler).",
+        );
+      }
+
+      // If the caller named an app we couldn't route to (unknown id, or no
+      // workspace), say so honestly instead of claiming we reached it.
+      const unresolved =
+        !!requestedApp && requestedApp.toLowerCase() !== selfId;
+      const note = unresolved
+        ? `Requested app "${requestedApp}" is not a reachable workspace ` +
+          `app; answered with this app ("${selfId}") instead.`
+        : undefined;
+
+      // Hosted MCP cannot safely keep a JSON request/response open for a full
+      // agent loop: serverless gateways can return an inactivity 504 before
+      // the result body exists. When we know the running app origin, submit the
+      // local ask through the app's durable A2A task path and only wait a
+      // short bounded window for fast completions.
+      const localA2AEndpointUrl = selfA2AEndpointUrl(requestMeta);
+      if (localA2AEndpointUrl) {
+        return submitAskAppA2ATask(
+          {
+            app: selfId,
+            origin: localA2AEndpointUrl,
+            routedVia: "local",
+            requestOrigin: requestMeta?.origin,
+            ...(note ? { note } : {}),
+          },
+          message,
+          maxWaitMs,
+          approvedActions,
+        );
+      }
+
+      // No derivable app origin at all (e.g. stdio / no request context) —
+      // there is no `/_agent-native/a2a` endpoint to submit a durable task
+      // to either. Bound the wait against a process-local task map instead
+      // of awaiting config.askAgent() unbounded, so a slow agent run can't
+      // hold this MCP call open indefinitely. Settling in time keeps the
+      // original response shape; timing out returns the same still-working
+      // poll payload the A2A path would, using the same taskId contract
+      // (see ask-app-inline-tasks.ts).
+      const { startAskAppInlineTask } =
+        await import("./ask-app-inline-tasks.js");
+      const inline = await startAskAppInlineTask(
+        config.askAgent,
+        message,
+        maxWaitMs,
+      );
+      if (inline.status === "completed") {
+        return {
+          app: selfId,
+          routedVia: "local",
+          ...(note ? { note } : {}),
+          response: inline.response || "(no response)",
+        };
+      }
+      if (inline.status === "failed") {
+        // Settled with an error inside the bounded wait — surface it the
+        // same way the old unbounded `await config.askAgent(message)` did.
+        throw new Error(inline.error || "ask_app task failed.");
+      }
+      return askAppInlineTaskResult(selfId, inline.taskId, inline, note);
+    },
+  };
+}
+
+function askAppStatusTool(
+  config: MCPConfig,
+  requestMeta?: AskAppRequestMeta,
+): ActionEntry {
+  return {
+    tool: tool(
+      "Poll a durable ask_app task and return its current status or final response. " +
+        "If a transient status read stays unavailable after bounded retries, the " +
+        "result preserves the app and taskId with statusRead 'unavailable' and a " +
+        "poll instruction. Retry ask_app_status for that same task; never resubmit " +
+        "ask_app as status-read recovery because that can duplicate work.",
+      {
+        app: {
+          type: "string",
+          description:
+            "App id returned by ask_app. Optional for same-app local tasks.",
+        },
+        taskId: {
+          type: "string",
+          description: "The durable task id returned by ask_app.",
+        },
+      },
+      ["taskId"],
+    ),
+    readOnly: true,
+    parallelSafe: true,
+    run: async (args: Record<string, any>) => {
+      const taskId = String(args.taskId ?? "").trim();
+      if (!taskId) throw new Error("ask_app_status requires 'taskId'.");
+
+      // The no-derivable-origin ask_app fallback tracks its tasks in a
+      // process-local map, not the durable A2A store. Check it FIRST —
+      // before any origin requirement — so a taskId minted by that fallback
+      // never has to satisfy `resolveAskAppStatusRoute`'s "running app
+      // origin" check. Falls through to the normal A2A route when the id
+      // isn't one of these (never started here, evicted, or an ordinary A2A
+      // task id).
+      const { getAskAppInlineTask } = await import("./ask-app-inline-tasks.js");
+      const inline = getAskAppInlineTask(taskId);
+      if (inline) {
+        return askAppInlineTaskResult(currentAppId(config), taskId, inline);
+      }
+
+      const requestedApp = String(args.app ?? "").trim();
+      const route = await resolveAskAppStatusRoute(
+        config,
+        requestedApp,
+        requestMeta,
+      );
+      return fetchAskAppA2ATask(route, taskId);
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// list_templates
+// ---------------------------------------------------------------------------
+
+function listTemplatesTool(): ActionEntry {
+  return {
+    tool: tool(
+      "List the first-party templates that can be scaffolded into a workspace " +
+        "(allow-listed templates only).",
+    ),
+    readOnly: true,
+    parallelSafe: true,
+    run: async () => {
+      const { visibleTemplates } = await import("../cli/templates-meta.js");
+      return {
+        templates: visibleTemplates().map((t) => ({
+          name: t.name,
+          label: t.label,
+          hint: t.hint,
+        })),
+      };
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// create_workspace_app
+// ---------------------------------------------------------------------------
+
+function createWorkspaceAppTool(): ActionEntry {
+  return {
+    tool: tool(
+      "Scaffold a new app into the current workspace from an allow-listed " +
+        "template, then return a deep link to open it. Idempotent: if an app " +
+        "with that name already exists it is reused.",
+      {
+        name: {
+          type: "string",
+          description: "New app id (directory under apps/), e.g. 'mymail'",
+        },
+        template: {
+          type: "string",
+          description:
+            "Template to scaffold from — must be allow-listed (see list_templates)",
+        },
+      },
+      ["name", "template"],
+    ),
+    run: async (args: Record<string, any>) => {
+      const name = String(args.name ?? "").trim();
+      const template = String(args.template ?? "").trim();
+      if (!name || !template) {
+        throw new Error(
+          "create_workspace_app requires both 'name' and 'template'.",
+        );
+      }
+
+      // Enforce the strict public template allow-list. The authoritative,
+      // dependency-free source inside @agent-native/core is cli/templates-meta
+      // (kept in sync with packages/shared-app-config/templates.ts; CI guard).
+      const { visibleTemplates } = await import("../cli/templates-meta.js");
+      const allowed = new Set(visibleTemplates().map((t) => t.name));
+      if (!allowed.has(template)) {
+        throw new Error(
+          `Template "${template}" is not allow-listed. Allowed: ${[...allowed]
+            .sort()
+            .join(", ")}`,
+        );
+      }
+
+      const { findWorkspaceRoot, resolveWorkspace } =
+        await import("./workspace-resolve.js");
+      const fs = await import("node:fs");
+      const path = await import("node:path");
+
+      const root = findWorkspaceRoot(process.cwd());
+      if (!root) {
+        throw new Error(
+          "Not inside a workspace. create_workspace_app only works in a " +
+            "multi-app workspace (run from the workspace root).",
+        );
+      }
+
+      const appDir = path.join(root, "apps", name);
+      const alreadyExisted = fs.existsSync(appDir);
+
+      if (!alreadyExisted) {
+        // Reuse the CLI scaffolder directly (no second `agent-native`
+        // subprocess). `addAppToWorkspace(name, { template })` takes the
+        // non-interactive single-template path when name + one template are
+        // given. Run it from the workspace root so detectWorkspace resolves.
+        const prevCwd = process.cwd();
+        try {
+          process.chdir(root);
+          const { addAppToWorkspace } = await import("../cli/create.js");
+          await addAppToWorkspace(name, { template, noInstall: true });
+        } finally {
+          try {
+            process.chdir(prevCwd);
+          } catch {
+            // best-effort cwd restore
+          }
+        }
+      }
+
+      // The workspace gateway auto-detects new apps/* dirs (fs.watch +
+      // 2s sync) and lazily boots the dev server on first request, so we
+      // don't spawn vite ourselves — opening the deep link warms it. Resolve
+      // the port the gateway will use so we can report it.
+      const ws = await resolveWorkspace(root);
+      const appInfo = ws.apps.find((a) => a.id === name);
+      const port = appInfo?.port;
+      // The scaffolded app is always a *different* app from the host MCP
+      // server, so anchor the deep link to the new app's own origin. A
+      // relative path would otherwise be prefixed with the current request
+      // origin and land on the wrong app. Fall back to the relative path
+      // only if the gateway hasn't reported the new app's URL yet.
+      const relDeepLink = buildDeepLink({ app: name, view: "home" });
+      const deepLink = appInfo?.url
+        ? `${appInfo.url.replace(/\/+$/, "")}${relDeepLink}`
+        : relDeepLink;
+
+      return {
+        name,
+        template,
+        created: !alreadyExisted,
+        reused: alreadyExisted,
+        port,
+        url: appInfo?.url,
+        gatewayUrl: ws.gatewayUrl,
+        deepLink,
+      };
+    },
+    link: ({ result }) => {
+      if (!result || typeof result !== "object") return null;
+      const r = result as { deepLink?: string; name?: string };
+      if (!r.deepLink) return null;
+      return {
+        url: r.deepLink,
+        label: `Open ${r.name ?? "app"}`,
+        view: "home",
+      };
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the generic cross-app builtin tool registry. Called by
+ * `createMCPServerForRequest`; the result is merged UNDER the config's
+ * actions so template actions of the same name win.
+ */
+export function getBuiltinCrossAppTools(
+  config: MCPConfig,
+  requestMeta?: AskAppRequestMeta,
+): Record<string, ActionEntry> {
+  return {
+    list_apps: listAppsTool(config, requestMeta),
+    open_app: openAppTool(config, requestMeta),
+    create_embed_session: createEmbedSessionTool(requestMeta),
+    ask_app: askAppTool(config, requestMeta),
+    ask_app_status: askAppStatusTool(config, requestMeta),
+    create_workspace_app: createWorkspaceAppTool(),
+    list_templates: listTemplatesTool(),
+  };
+}