@agent-native/dispatch 0.40.30-nightly-20261021093329 → 0.40.31

package/src/server/lib/connect-apps.ts

@@ -0,0 +1,149 @@
+import { ssrfSafeFetch } from "@agent-native/core/extensions/url-safety";
+
+import {
+  buildAgentCardUrl,
+  normalizeConnectUrl,
+  parseConnectAgentCard,
+  type ConnectAgentCard,
+  type MarketplaceApp,
+} from "../../lib/connect-apps.js";
+
+const CONNECT_FETCH_TIMEOUT_MS = 5_000;
+const MARKETPLACE_MAX_BYTES = 1_000_000;
+const AGENT_CARD_MAX_BYTES = 256_000;
+const MAX_MARKETPLACE_CANDIDATES = 50;
+
+async function readLimitedText(
+  response: Response,
+  maxBytes: number,
+  label: string,
+): Promise<string> {
+  const declaredLength = Number(response.headers.get("content-length"));
+  if (Number.isFinite(declaredLength) && declaredLength > maxBytes) {
+    throw new Error(`${label} is too large`);
+  }
+
+  if (!response.body) return "";
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let totalBytes = 0;
+  let body = "";
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      totalBytes += value.byteLength;
+      if (totalBytes > maxBytes) {
+        await reader.cancel();
+        throw new Error(`${label} is too large`);
+      }
+      body += decoder.decode(value, { stream: true });
+    }
+    return body + decoder.decode();
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+async function fetchJsonText(
+  url: string,
+  maxBytes: number,
+  label: string,
+  assertUrlAllowed?: (url: string) => void,
+) {
+  const response = await ssrfSafeFetch(
+    url,
+    {
+      headers: { accept: "application/json" },
+      signal: AbortSignal.timeout(CONNECT_FETCH_TIMEOUT_MS),
+    },
+    {
+      maxRedirects: 3,
+      requireDispatcher: true,
+      httpsOnly: true,
+      ...(assertUrlAllowed ? { assertUrlAllowed } : {}),
+    },
+  );
+  if (!response.ok) throw new Error(`${label} returned ${response.status}`);
+  return readLimitedText(response, maxBytes, label);
+}
+
+export async function fetchConnectAgentCard(
+  appUrl: string,
+): Promise<ConnectAgentCard> {
+  const target = normalizeConnectUrl(appUrl);
+  if (!target || target.protocol !== "https:") {
+    throw new Error("Enter a secure app URL.");
+  }
+
+  const cardUrl = new URL(buildAgentCardUrl(target.toString()));
+  const body = await fetchJsonText(
+    cardUrl.toString(),
+    AGENT_CARD_MAX_BYTES,
+    "Agent card",
+    (url) => {
+      const redirect = new URL(url);
+      if (
+        redirect.origin !== cardUrl.origin ||
+        redirect.pathname !== cardUrl.pathname
+      ) {
+        throw new Error("Agent card redirects must stay on the requested URL.");
+      }
+    },
+  );
+  const card = parseConnectAgentCard(
+    JSON.parse(body),
+    target.origin,
+    target.pathname,
+  );
+  if (!card) {
+    throw new Error("This app has an invalid or incompatible agent card.");
+  }
+  return card;
+}
+
+export async function fetchMarketplaceApps(
+  feedUrl = "https://www.agent-native.com/apps.json",
+): Promise<MarketplaceApp[]> {
+  const feed = normalizeConnectUrl(feedUrl);
+  if (!feed || feed.protocol !== "https:") {
+    throw new Error("Marketplace feed URL must use HTTPS.");
+  }
+
+  const body = await fetchJsonText(
+    feed.toString(),
+    MARKETPLACE_MAX_BYTES,
+    "Marketplace feed",
+  );
+  const payload = JSON.parse(body) as { apps?: unknown };
+  if (!Array.isArray(payload.apps)) {
+    throw new Error("Marketplace feed is invalid");
+  }
+
+  const candidates = payload.apps
+    .filter((entry): entry is MarketplaceApp => {
+      if (!entry || typeof entry !== "object") return false;
+      const app = entry as Record<string, unknown>;
+      const url =
+        typeof app.url === "string" ? normalizeConnectUrl(app.url) : null;
+      return (
+        typeof app.id === "string" &&
+        typeof app.name === "string" &&
+        typeof app.description === "string" &&
+        Boolean(url && url.protocol === "https:") &&
+        Array.isArray(app.capabilities) &&
+        app.capabilities.every((capability) => typeof capability === "string")
+      );
+    })
+    .slice(0, MAX_MARKETPLACE_CANDIDATES);
+
+  const verified = await Promise.allSettled(
+    candidates.map(async (app) => {
+      const card = await fetchConnectAgentCard(app.url);
+      return card.connect ? { ...app, capabilities: ["connect"] } : null;
+    }),
+  );
+  return verified.flatMap((result) =>
+    result.status === "fulfilled" && result.value ? [result.value] : [],
+  );
+}

package/src/server/lib/org-apps-directory-cache.spec.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { createOrgDirectorySuccessCache } from "./org-apps-directory-cache.js";
+
+describe("createOrgDirectorySuccessCache", () => {
+  it("coalesces same-key refreshes and isolates cache keys", async () => {
+    let resolveLoad!: (value: string[]) => void;
+    const load = vi.fn(
+      () =>
+        new Promise<string[]>((resolve) => {
+          resolveLoad = resolve;
+        }),
+    );
+    const cache = createOrgDirectorySuccessCache<string[]>();
+
+    const first = cache.get("org-a|user:alice", load);
+    const second = cache.get("org-a|user:alice", load);
+    expect(load).toHaveBeenCalledTimes(1);
+    resolveLoad(["analytics"]);
+    await expect(Promise.all([first, second])).resolves.toEqual([
+      ["analytics"],
+      ["analytics"],
+    ]);
+
+    await cache.get("org-a|user:bob", async () => ["mail"]);
+    expect(load).toHaveBeenCalledTimes(1);
+  });
+
+  it("caches successful values until expiry and retries failures", async () => {
+    let now = 1_000;
+    const cache = createOrgDirectorySuccessCache<string[]>({
+      ttlMs: 60,
+      now: () => now,
+    });
+    const load = vi
+      .fn<() => Promise<string[]>>()
+      .mockResolvedValueOnce(["content"])
+      .mockRejectedValueOnce(new Error("directory unavailable"))
+      .mockResolvedValueOnce(["design"])
+      .mockResolvedValueOnce(["design-updated"]);
+
+    await expect(cache.get("org-a", load)).resolves.toEqual(["content"]);
+    now += 59;
+    await expect(cache.get("org-a", load)).resolves.toEqual(["content"]);
+    now += 2;
+    await expect(cache.get("org-a", load)).rejects.toThrow(
+      "directory unavailable",
+    );
+    await expect(cache.get("org-a", load)).resolves.toEqual(["design"]);
+    expect(load).toHaveBeenCalledTimes(3);
+  });
+
+  it("does not repopulate after invalidation while a refresh is in flight", async () => {
+    let resolveLoad!: (value: string[]) => void;
+    const cache = createOrgDirectorySuccessCache<string[]>();
+    const staleLoad = cache.get(
+      "org-a",
+      () =>
+        new Promise<string[]>((resolve) => {
+          resolveLoad = resolve;
+        }),
+    );
+
+    cache.clear();
+    resolveLoad(["before-edit"]);
+    await expect(staleLoad).resolves.toEqual(["before-edit"]);
+    await expect(
+      cache.get("org-a", async () => ["after-edit"]),
+    ).resolves.toEqual(["after-edit"]);
+  });
+});

package/src/server/lib/org-apps-directory-cache.ts

@@ -0,0 +1,66 @@
+export interface CachedOrgDirectoryAgent {
+  id: string;
+  name: string;
+  description?: string;
+  whenToUse?: string[];
+  url: string;
+  source?: "workspace" | "org-directory" | "remote-agent" | "builtin";
+}
+
+export interface OrgDirectorySuccessCache<T> {
+  get(key: string, load: () => Promise<T>): Promise<T>;
+  clear(): void;
+}
+
+export function createOrgDirectorySuccessCache<T>(input?: {
+  ttlMs?: number;
+  now?: () => number;
+}): OrgDirectorySuccessCache<T> {
+  const ttlMs = input?.ttlMs ?? 60_000;
+  const now = input?.now ?? Date.now;
+  const values = new Map<string, { value: T; expiresAt: number }>();
+  const inFlight = new Map<string, Promise<T>>();
+  let generation = 0;
+
+  return {
+    async get(key, load) {
+      const cached = values.get(key);
+      if (cached && cached.expiresAt > now()) return cached.value;
+      values.delete(key);
+
+      const pending = inFlight.get(key);
+      if (pending) return pending;
+
+      const loadGeneration = generation;
+      const refresh = load()
+        .then((value) => {
+          if (loadGeneration === generation) {
+            values.set(key, { value, expiresAt: now() + ttlMs });
+          }
+          return value;
+        })
+        .finally(() => {
+          if (inFlight.get(key) === refresh) inFlight.delete(key);
+        });
+      inFlight.set(key, refresh);
+      return refresh;
+    },
+    clear() {
+      generation += 1;
+      values.clear();
+      inFlight.clear();
+    },
+  };
+}
+
+export const orgAppsDirectoryCache =
+  createOrgDirectorySuccessCache<CachedOrgDirectoryAgent[]>();
+
+export const orgAppsDirectoryAccessCache = createOrgDirectorySuccessCache<
+  Set<string>
+>({ ttlMs: 15_000 });
+
+export function invalidateOrgAppsDirectoryCache(): void {
+  orgAppsDirectoryCache.clear();
+  orgAppsDirectoryAccessCache.clear();
+}

package/src/server/plugins/integrations.spec.ts

@@ -0,0 +1,60 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  createIntegrationsPlugin: vi.fn(),
+  integrationsPlugin: vi.fn(),
+  getDispatchConfig: vi.fn(),
+}));
+
+vi.mock("@agent-native/core/server", () => ({
+  createIntegrationsPlugin: mocks.createIntegrationsPlugin,
+}));
+
+vi.mock("../../actions/index.js", () => ({
+  dispatchActions: { ask_app: {} },
+}));
+
+vi.mock("../index.js", () => ({
+  getDispatchConfig: mocks.getDispatchConfig,
+}));
+
+vi.mock("../lib/dispatch-integrations.js", () => ({
+  beforeDispatchProcess: vi.fn(),
+  resolveDispatchExecutionContext: vi.fn(),
+}));
+
+describe("Dispatch integrations plugin", () => {
+  beforeEach(() => {
+    vi.resetModules();
+    mocks.createIntegrationsPlugin.mockReset();
+    mocks.integrationsPlugin.mockReset();
+    mocks.getDispatchConfig.mockReset();
+    mocks.createIntegrationsPlugin.mockReturnValue(mocks.integrationsPlugin);
+    mocks.getDispatchConfig.mockReturnValue({});
+  });
+
+  it("routes delegation from the prompt resource context without a peer roster", async () => {
+    const { default: dispatchIntegrationsPlugin } =
+      await import("./integrations.js");
+    const nitroApp = {};
+
+    await dispatchIntegrationsPlugin(nitroApp);
+
+    expect(mocks.createIntegrationsPlugin).toHaveBeenCalledWith(
+      expect.objectContaining({
+        appId: "dispatch",
+        systemPrompt: expect.stringContaining(
+          'search with describe-workspace-apps query="<capability>"',
+        ),
+      }),
+    );
+    const options = mocks.createIntegrationsPlugin.mock.calls[0][0];
+    expect(options.systemPrompt).not.toContain(
+      "Apps you can delegate to include",
+    );
+    expect(options.systemPrompt).toContain("the relevant-apps context");
+    expect(options.systemPrompt).not.toContain("available-apps context");
+    expect(options.systemPrompt).not.toContain("slides (decks/presentations)");
+    expect(mocks.integrationsPlugin).toHaveBeenCalledWith(nitroApp);
+  });
+});

package/src/server/plugins/integrations.ts

@@ -19,9 +19,9 @@ const DISPATCH_INTEGRATION_SYSTEM_PROMPT = `You are the central dispatch for thi
 
 Default posture:
 - Treat Slack, Telegram, and email as shared entrypoints into the workspace.
-- Heavily delegate domain work to specialized agents through A2A (call-agent) when another app owns the job. Apps you can delegate to include slides (decks/presentations), analytics (data/dashboards), content (docs/articles), forms (form builder), clips (screen recordings), design (visual designs), and assets (brand libraries plus generated images/videos).
-- Use the available-apps prompt context first, then list-connected-agents when you need fresh details, to see what agents are available before assuming a request must be handled locally.
-- Hosted/connected A2A neighbors such as Analytics and Content come from the available-apps context or list-connected-agents. list-workspace-apps only inventories apps mounted inside this workspace deployment; never use a missing row there to conclude that a connected agent is unavailable.
+- Heavily delegate domain work to specialized agents through A2A (call-agent) when another app owns the job.
+- Use relevant-apps prompt profiles first, then list-connected-agents when you need fresh details. If that context is absent or does not list the needed capability, search with describe-workspace-apps query="<capability>" before assuming a request must be handled locally.
+- Hosted/connected A2A neighbors such as Analytics and Content come from the relevant-apps context or list-connected-agents. If neither identifies the needed capability, use describe-workspace-apps before concluding a connected agent is unavailable. list-workspace-apps only inventories apps mounted inside this workspace deployment; never use a missing row there to conclude that a connected agent is unavailable.
 - When asked whether a mounted workspace app exposes an agent card or A2A endpoint, call list-workspace-apps with includeAgentCards=true. Without that probe, missing agent-card fields mean unchecked, not unavailable.
 - Treat first-party apps such as Mail, Calendar, Analytics, Brain, Assets, and Dispatch as existing hosted/connected neighbors available through links and A2A/default connected agents. Do not create wrapper apps, child apps, nested routes, or cloned template copies just to give a new app access to them; build only the genuinely new workflow and delegate cross-app work to those existing apps.
 - Integration grants are not provider capability limits. For ad hoc provider inspection, querying, reporting, or troubleshooting, call provider-api-catalog/provider-api-docs, then provider-api-request against the provider's real HTTP API. Use connectionId for a specific shared grant and accountId for a specific OAuth account. Never expose secret values or silently widen app access while doing this.

package/src/shared/labs.ts

@@ -0,0 +1,9 @@
+import { defineLab } from "@agent-native/core/labs/registry";
+
+export const COMMUNITY_APPS_LAB = defineLab({
+  key: "dispatch.community-apps",
+  displayName: "Community apps",
+  description:
+    "Connect trusted remote agents and install reviewed, pinned community app templates.",
+  keywords: "community apps templates connect install",
+});