@agent-native/core 0.98.16 → 0.99.0

package/corpus/core/src/embedding/agent.ts

@@ -39,17 +39,19 @@ function trimEndpointPath(pathname: string, suffix: string): string | null {
   return normalized.slice(0, -suffix.length) || "/";
 }
 
+const MCP_PUBLIC_PATH = "/mcp";
+const MCP_LEGACY_PATH = "/_agent-native/mcp";
+
 export function getMcpUrl(
   url: string,
   options: AgentEndpointOptions = {},
 ): string {
   const parsed = appUrl(url, options);
-  const trimmed = trimEndpointPath(parsed.pathname, "/_agent-native/mcp");
-  if (trimmed !== null) {
-    parsed.pathname = `${trimmed.replace(/\/$/, "")}/_agent-native/mcp`;
-  } else {
-    parsed.pathname = `${parsed.pathname.replace(/\/$/, "")}/_agent-native/mcp`;
-  }
+  const trimmed =
+    trimEndpointPath(parsed.pathname, MCP_LEGACY_PATH) ??
+    trimEndpointPath(parsed.pathname, MCP_PUBLIC_PATH);
+  const basePath = (trimmed ?? parsed.pathname).replace(/\/$/, "");
+  parsed.pathname = `${basePath}${MCP_PUBLIC_PATH}`;
   parsed.search = "";
   parsed.hash = "";
   return parsed.toString();

package/corpus/core/src/localization/default-messages.ts

@@ -620,6 +620,13 @@ const messages = {
         description: "Manage payments, subscriptions, and customers.",
         useCase: "Payments, subscriptions, invoicing, customer management",
       },
+      atlassian: {
+        description: "Read and write Jira issues and Confluence content.",
+        useCase:
+          "Project management, issue tracking, documentation, team collaboration",
+        setupNote:
+          "Your Atlassian organization admin may need to allow this app's domain and enable the required Rovo MCP permissions before OAuth can complete.",
+      },
     },
     auth: {
       none: "No auth",

package/corpus/core/src/mcp/ask-app-inline-tasks.ts

@@ -0,0 +1,125 @@
+/**
+ * Process-local fallback task tracker for `ask_app` (and the legacy
+ * `ask-agent` meta-tool) for the one case where no app origin is derivable
+ * from the MCP request — `selfA2AEndpointUrl(requestMeta)` returns null in
+ * `builtin-tools.ts`. Without an origin there is no `/_agent-native/a2a`
+ * endpoint to submit a durable task to, so `config.askAgent(message)` used
+ * to be awaited unbounded, which can hold a hosted MCP request open past a
+ * serverless gateway's inactivity timeout. This gives that path the same
+ * bounded "return a taskId, keep working in the background" contract as the
+ * durable A2A path, without needing a database.
+ *
+ * Entries are **process-local, not durable** — they live only in this
+ * server instance's memory and are lost on restart or if a different
+ * instance handles the poll. That is an acceptable trade-off here: this
+ * fallback only exists because no app origin was derivable in the first
+ * place, so there was never a reachable endpoint another instance could
+ * have polled anyway.
+ *
+ * Eviction is lazy (checked on each map access) instead of timer-based, so
+ * this stays serverless-safe — nothing keeps the process alive to sweep.
+ */
+
+type AskAppInlineTaskStatus = "working" | "completed" | "failed";
+
+interface AskAppInlineTaskEntry {
+  status: AskAppInlineTaskStatus;
+  response?: string;
+  error?: string;
+  createdAt: number;
+  settledAt?: number;
+}
+
+export interface AskAppInlineTaskSnapshot {
+  taskId: string;
+  status: AskAppInlineTaskStatus;
+  response?: string;
+  error?: string;
+}
+
+const SETTLED_TASK_TTL_MS = 10 * 60_000;
+const UNSETTLED_TASK_TTL_MS = 30 * 60_000;
+
+const inlineTasks = new Map<string, AskAppInlineTaskEntry>();
+
+function evictStaleInlineTasks(now: number): void {
+  for (const [taskId, entry] of inlineTasks) {
+    const ttlMs =
+      entry.settledAt != null ? SETTLED_TASK_TTL_MS : UNSETTLED_TASK_TTL_MS;
+    const anchor = entry.settledAt ?? entry.createdAt;
+    if (now - anchor > ttlMs) inlineTasks.delete(taskId);
+  }
+}
+
+function toSnapshot(
+  taskId: string,
+  entry: AskAppInlineTaskEntry,
+): AskAppInlineTaskSnapshot {
+  return {
+    taskId,
+    status: entry.status,
+    ...(entry.response !== undefined ? { response: entry.response } : {}),
+    ...(entry.error !== undefined ? { error: entry.error } : {}),
+  };
+}
+
+/**
+ * Start `askAgent(message)` under a fresh process-local taskId and wait up
+ * to `maxWaitMs` for it to settle. The map entry is written synchronously
+ * before the async work starts, so a poll racing this call can never see a
+ * missing taskId. Returns the settled snapshot when it finishes in time, or
+ * a `"working"` snapshot once `maxWaitMs` elapses — the caller can hand that
+ * taskId back to `getAskAppInlineTask` later to pick up the final result.
+ */
+export async function startAskAppInlineTask(
+  askAgent: (message: string) => Promise<string>,
+  message: string,
+  maxWaitMs: number,
+): Promise<AskAppInlineTaskSnapshot> {
+  const now = Date.now();
+  evictStaleInlineTasks(now);
+
+  const taskId = globalThis.crypto.randomUUID();
+  const entry: AskAppInlineTaskEntry = { status: "working", createdAt: now };
+  inlineTasks.set(taskId, entry);
+
+  const settled = askAgent(message).then(
+    (response) => {
+      entry.status = "completed";
+      entry.response = response;
+      entry.settledAt = Date.now();
+    },
+    (err) => {
+      entry.status = "failed";
+      entry.error =
+        err instanceof Error
+          ? err.message
+          : String(err ?? "ask_app task failed.");
+      entry.settledAt = Date.now();
+    },
+  );
+
+  if (maxWaitMs > 0) {
+    await Promise.race([
+      settled,
+      new Promise<void>((resolve) => setTimeout(resolve, maxWaitMs)),
+    ]);
+  }
+
+  return toSnapshot(taskId, entry);
+}
+
+/**
+ * Look up a process-local inline task started by `startAskAppInlineTask`.
+ * Returns `undefined` when the id is unknown — never started here, already
+ * evicted, or (in a multi-instance deployment) started on a different
+ * instance. Callers should fall through to the normal A2A HTTP status path
+ * in that case.
+ */
+export function getAskAppInlineTask(
+  taskId: string,
+): AskAppInlineTaskSnapshot | undefined {
+  evictStaleInlineTasks(Date.now());
+  const entry = inlineTasks.get(taskId);
+  return entry ? toSnapshot(taskId, entry) : undefined;
+}

package/corpus/core/src/mcp/build-server.ts

@@ -204,6 +204,35 @@ export interface MCPRequestMeta {
   inlineMcpApps?: boolean;
 }
 
+const ASK_AGENT_DEFAULT_INLINE_WAIT_MS = 20_000;
+const ASK_AGENT_MAX_INLINE_WAIT_MS = 25_000;
+
+function boundedAskAgentWaitMs(raw: unknown): number {
+  if (raw == null || raw === "") return ASK_AGENT_DEFAULT_INLINE_WAIT_MS;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed)) return ASK_AGENT_DEFAULT_INLINE_WAIT_MS;
+  return Math.max(
+    0,
+    Math.min(ASK_AGENT_MAX_INLINE_WAIT_MS, Math.trunc(parsed)),
+  );
+}
+
+function isExplicitAsyncAskAgent(raw: unknown): boolean {
+  return raw === true || raw === "true" || raw === 1 || raw === "1";
+}
+
+function formatAskAgentResult(result: unknown): string {
+  if (typeof result === "string") return result;
+  if (result && typeof result === "object") {
+    const record = result as Record<string, unknown>;
+    if (record.status === "completed" && typeof record.response === "string") {
+      return record.response;
+    }
+  }
+  const serialized = JSON.stringify(result);
+  return serialized === undefined ? String(result) : serialized;
+}
+
 /**
  * Deploy-toggleable kill switch for inline MCP App embeds — the `ui://`
  * resource reference hosts like Codex / Cursor / ChatGPT render in a sandboxed
@@ -1618,7 +1647,9 @@ export async function createMCPServerForRequest(
           description:
             "Send a natural-language message to the app's AI agent and get a response. " +
             "Use this for complex, multi-step tasks that require the agent's reasoning " +
-            "and full context about the app.",
+            "and full context about the app. On hosted MCP, the server waits briefly " +
+            "for fast completions and returns a taskId plus ask_app_status polling " +
+            "instructions when the agent needs longer.",
           inputSchema: {
             type: "object" as const,
             properties: {
@@ -1626,6 +1657,16 @@ export async function createMCPServerForRequest(
                 type: "string",
                 description: "The message to send to the agent",
               },
+              async: {
+                type: "boolean",
+                description:
+                  "Start a durable task and return immediately with a taskId.",
+              },
+              maxWaitMs: {
+                type: "number",
+                description:
+                  "Maximum inline wait in milliseconds. Hosted MCP clamps this to 25000ms.",
+              },
             },
             required: ["message"],
           },
@@ -1668,8 +1709,29 @@ export async function createMCPServerForRequest(
         }
         const message = args?.message ?? "";
         try {
-          const result = await config.askAgent(message);
-          return { content: [{ type: "text", text: result }] };
+          // Keep the legacy meta-tool compatible for local callers, but use
+          // the same durable A2A submission path as ask_app whenever this is
+          // an HTTP/hosted request. A full agent loop must never be held open
+          // for minutes behind one MCP tools/call request. Always route
+          // through ask_app's own run() — even with no request origin, since
+          // it now bounds that case too via its process-local inline-task
+          // fallback (ask-app-inline-tasks.ts) instead of us awaiting
+          // config.askAgent() here unbounded. This is the shared helper: no
+          // second task map to keep in sync.
+          const hostedAskApp = getBuiltinCrossAppTools(
+            config,
+            requestMeta,
+          ).ask_app;
+          const result = await hostedAskApp.run({
+            message,
+            async: isExplicitAsyncAskAgent(args?.async),
+            maxWaitMs: isExplicitAsyncAskAgent(args?.async)
+              ? 0
+              : boundedAskAgentWaitMs(args?.maxWaitMs),
+          });
+          return {
+            content: [{ type: "text", text: formatAskAgentResult(result) }],
+          };
         } catch (err: any) {
           return {
             content: [{ type: "text", text: `Error: ${err.message}` }],

package/corpus/core/src/mcp/builtin-tools.ts

@@ -88,14 +88,23 @@ 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;
 }
 
@@ -106,7 +115,9 @@ interface AskAppTaskResult {
   status: string;
   response?: string;
   error?: string;
+  inputRequired?: string;
   note?: string;
+  pollAfterMs?: number;
   poll?: {
     tool: "ask_app_status";
     arguments: { app: string; taskId: string };
@@ -236,8 +247,20 @@ function askAppTaskResult(route: AskAppRoute, task: Task): AskAppTaskResult {
     };
   }
 
+  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 },
@@ -248,7 +271,57 @@ function askAppTaskResult(route: AskAppRoute, task: Task): AskAppTaskResult {
   };
 }
 
-async function createA2AClientForAskApp(origin: string): Promise<{
+/**
+ * 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>;
 }> {
@@ -258,9 +331,14 @@ async function createA2AClientForAskApp(origin: string): Promise<{
   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: ASK_APP_A2A_REQUEST_TIMEOUT_MS,
+      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 }
         : {}),
@@ -269,13 +347,35 @@ async function createA2AClientForAskApp(origin: string): Promise<{
   };
 }
 
+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,
-  maxWaitMs: number,
+  deadline: number | undefined,
 ): Promise<Task> {
-  if (maxWaitMs <= 0 || isTerminalTask(initialTask)) return initialTask;
-  const deadline = Date.now() + maxWaitMs;
+  if (deadline == null || isTerminalTask(initialTask)) return initialTask;
   let current = initialTask;
 
   while (!isTerminalTask(current)) {
@@ -284,13 +384,16 @@ async function waitForA2ATask(
     await new Promise((resolve) =>
       setTimeout(resolve, Math.min(ASK_APP_POLL_INTERVAL_MS, remaining)),
     );
+    if (Date.now() >= deadline) return current;
     try {
-      current = await client.getTask(initialTask.id);
-    } catch {
-      // Transient status fetch failures should not turn a successfully
-      // submitted durable task into a failed MCP call.
+      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;
-      continue;
     }
   }
 
@@ -302,7 +405,12 @@ async function submitAskAppA2ATask(
   message: string,
   maxWaitMs: number,
 ): Promise<AskAppTaskResult> {
-  const { client, metadata } = await createA2AClientForAskApp(route.origin);
+  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",
@@ -313,7 +421,7 @@ async function submitAskAppA2ATask(
       metadata,
     },
   );
-  const finalOrRunning = await waitForA2ATask(client, task, maxWaitMs);
+  const finalOrRunning = await waitForA2ATask(client, task, deadline);
   return askAppTaskResult(route, finalOrRunning);
 }
 
@@ -778,13 +886,22 @@ async function routeAskOverA2A(
   origin: string,
   id: string,
   message: string,
-  options?: { durable?: boolean; maxWaitMs?: number },
+  options?: {
+    durable?: boolean;
+    maxWaitMs?: number;
+    requestOrigin?: string;
+  },
 ): Promise<
   { app: string; routedVia: "a2a"; response: string } | AskAppTaskResult
 > {
   if (options?.durable) {
     return submitAskAppA2ATask(
-      { app: id, origin: agentNativeA2AEndpoint(origin), routedVia: "a2a" },
+      {
+        app: id,
+        origin: agentNativeA2AEndpoint(origin),
+        routedVia: "a2a",
+        requestOrigin: options.requestOrigin ?? origin,
+      },
       message,
       options.maxWaitMs ?? ASK_APP_DEFAULT_INLINE_WAIT_MS,
     );
@@ -801,6 +918,7 @@ async function routeAskOverA2A(
     userEmail: auth.userEmail,
     orgDomain: auth.orgDomain,
     orgSecret: auth.orgSecret,
+    requestOrigin: options?.requestOrigin,
     // Bound the wait — cross-app A2A polls async by default.
     timeoutMs: 5 * 60_000,
   });
@@ -822,7 +940,12 @@ async function resolveAskAppStatusRoute(
         "ask_app_status requires a running app origin for local tasks.",
       );
     }
-    return { app: selfId, origin: selfEndpointUrl, routedVia: "local" };
+    return {
+      app: selfId,
+      origin: selfEndpointUrl,
+      routedVia: "local",
+      requestOrigin: requestMeta?.origin,
+    };
   }
 
   const targetApp = await resolveTargetAppOrigin(config, requestedApp);
@@ -831,6 +954,7 @@ async function resolveAskAppStatusRoute(
       app: targetApp.id,
       origin: agentNativeA2AEndpoint(targetApp.origin),
       routedVia: "a2a",
+      requestOrigin: targetApp.origin,
     };
   }
 
@@ -841,6 +965,7 @@ async function resolveAskAppStatusRoute(
       app: dirMatch.id,
       origin: agentNativeA2AEndpoint(dirMatch.a2aUrl),
       routedVia: "a2a",
+      requestOrigin: dirMatch.url,
     };
   }
 
@@ -914,6 +1039,7 @@ function askAppTool(
             {
               durable: useDurableA2A,
               maxWaitMs,
+              requestOrigin: targetApp.origin,
             },
           );
         } catch (err: any) {
@@ -947,6 +1073,7 @@ function askAppTool(
               {
                 durable: useDurableA2A,
                 maxWaitMs,
+                requestOrigin: dirMatch.url,
               },
             );
           } catch (err: any) {
@@ -988,6 +1115,7 @@ function askAppTool(
             app: selfId,
             origin: localA2AEndpointUrl,
             routedVia: "local",
+            requestOrigin: requestMeta?.origin,
             ...(note ? { note } : {}),
           },
           message,
@@ -995,13 +1123,35 @@ function askAppTool(
         );
       }
 
-      const response = await config.askAgent(message);
-      return {
-        app: selfId,
-        routedVia: "local",
-        ...(note ? { note } : {}),
-        response,
-      };
+      // 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);
     },
   };
 }
@@ -1031,6 +1181,20 @@ function askAppStatusTool(
     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,