@agent-native/dispatch 0.0.0-beta-20260819155526

package/src/lib/catch-all-target.spec.ts

@@ -0,0 +1,156 @@
+import { describe, expect, it } from "vitest";
+
+import { resolveCatchAllTarget } from "./catch-all-target.js";
+
+describe("resolveCatchAllTarget", () => {
+  it("prefers the workspace manifest entry when one matches", () => {
+    expect(
+      resolveCatchAllTarget("todo", {
+        workspaceApps: [{ id: "todo", path: "/todo" }],
+        builtinAgents: [{ id: "todo", url: "https://todo.example.com" }],
+      }),
+    ).toBe("/todo");
+  });
+
+  it("falls back to the built-in template URL when no workspace manifest exists", () => {
+    expect(
+      resolveCatchAllTarget("forms", {
+        workspaceApps: null,
+        builtinAgents: [{ id: "forms", url: "http://localhost:8084" }],
+      }),
+    ).toBe("http://localhost:8084");
+  });
+
+  it("falls back to the built-in template URL when the workspace manifest does not include the app", () => {
+    expect(
+      resolveCatchAllTarget("forms", {
+        workspaceApps: [{ id: "dispatch", path: "/dispatch" }],
+        builtinAgents: [{ id: "forms", url: "http://localhost:8084" }],
+      }),
+    ).toBe("http://localhost:8084");
+  });
+
+  it("normalizes a manifest entry without a leading slash", () => {
+    expect(
+      resolveCatchAllTarget("todo", {
+        workspaceApps: [{ id: "todo", path: "todo" }],
+      }),
+    ).toBe("/todo");
+  });
+
+  it("uses app.path when id !== path (not /${appId})", () => {
+    // Before the fix, an entry whose mounted path differs from its id —
+    // e.g. id: "forms", path: "my-forms" without a leading slash — was
+    // silently rewritten to `/forms` (the appId) and routed to the wrong
+    // app. The normalizer now keeps the manifest path and only prepends
+    // the missing slash.
+    expect(
+      resolveCatchAllTarget("forms", {
+        workspaceApps: [{ id: "forms", path: "my-forms" }],
+      }),
+    ).toBe("/my-forms");
+  });
+
+  it("prefers app.url when the manifest entry has an externally-hosted URL", () => {
+    // Workspaces can point at remote deploys. The catch-all should bounce
+    // to the absolute URL instead of mounting a local path that doesn't
+    // exist inside the gateway.
+    expect(
+      resolveCatchAllTarget("forms", {
+        workspaceApps: [
+          {
+            id: "forms",
+            path: "/forms",
+            url: "https://forms.example.com",
+          },
+        ],
+      }),
+    ).toBe("https://forms.example.com");
+  });
+
+  it("ignores app.url that isn't an absolute http(s) URL and falls back to path", () => {
+    // Bare hostname — `new URL("forms.example.com")` throws, so the value
+    // is rejected and we fall through to the (validated) path. Without
+    // this, the catch-all would `throw redirect("forms.example.com")`
+    // and the browser would treat the value as a relative path inside the
+    // gateway, producing a broken redirect.
+    expect(
+      resolveCatchAllTarget("forms", {
+        workspaceApps: [
+          { id: "forms", path: "/forms", url: "forms.example.com" },
+        ],
+      }),
+    ).toBe("/forms");
+  });
+
+  it("rejects non-http(s) URL schemes (e.g. javascript:) and falls back to path", () => {
+    // Defense in depth — a hostile manifest entry can't produce a
+    // `javascript:` redirect target. Validation enforces http(s) only.
+    expect(
+      resolveCatchAllTarget("forms", {
+        workspaceApps: [
+          { id: "forms", path: "/forms", url: "javascript:alert(1)" },
+        ],
+      }),
+    ).toBe("/forms");
+  });
+
+  it("strips a trailing slash from app.url", () => {
+    expect(
+      resolveCatchAllTarget("forms", {
+        workspaceApps: [
+          { id: "forms", path: "/forms", url: "https://forms.example.com/" },
+        ],
+      }),
+    ).toBe("https://forms.example.com");
+  });
+
+  it("ignores an empty/whitespace app.url and falls back to path", () => {
+    expect(
+      resolveCatchAllTarget("forms", {
+        workspaceApps: [{ id: "forms", path: "/forms", url: "   " }],
+      }),
+    ).toBe("/forms");
+  });
+
+  it("collapses leading slashes/backslashes in app.path so `/\\evil.example` can't redirect off-origin", () => {
+    // Browsers normalize backslashes to forward slashes during URL
+    // parsing, so `throw redirect("/\\evil.example")` would resolve to
+    // `https://evil.example`. The regex covers both slash types.
+    expect(
+      resolveCatchAllTarget("forms", {
+        workspaceApps: [{ id: "forms", path: "/\\evil.example" }],
+      }),
+    ).toBe("/evil.example");
+  });
+
+  it("collapses leading double slashes in app.path so `//evil.example` can't redirect off-origin", () => {
+    // The manifest parser only checks `startsWith("/")`, so a path of
+    // `//evil.example` slips through. Browsers treat that as a network-
+    // path reference and `throw redirect("//evil.example")` would redirect
+    // to `https://evil.example` — the same phishing vector the `app.url`
+    // validator closes. Collapse the leading slashes so the redirect
+    // stays on the gateway.
+    expect(
+      resolveCatchAllTarget("forms", {
+        workspaceApps: [{ id: "forms", path: "//evil.example" }],
+      }),
+    ).toBe("/evil.example");
+  });
+
+  it("falls back to /${appId} when the manifest entry has neither path nor url", () => {
+    expect(
+      resolveCatchAllTarget("forms", {
+        workspaceApps: [{ id: "forms", path: "" }],
+      }),
+    ).toBe("/forms");
+  });
+
+  it("returns null when nothing matches", () => {
+    expect(
+      resolveCatchAllTarget("unknown-app", {
+        workspaceApps: [{ id: "dispatch", path: "/dispatch" }],
+      }),
+    ).toBeNull();
+  });
+});

package/src/lib/catch-all-target.ts

@@ -0,0 +1,125 @@
+interface WorkspaceAppManifestEntry {
+  id?: string;
+  path?: unknown;
+  url?: unknown;
+}
+
+interface BuiltinAgentEntry {
+  id: string;
+  url?: string | null;
+}
+
+interface ResolveCatchAllTargetOptions {
+  workspaceApps?: WorkspaceAppManifestEntry[] | null;
+  builtinAgents?: BuiltinAgentEntry[] | null;
+}
+
+/**
+ * Resolve where `/dispatch/<appId>` should bounce to when it doesn't match
+ * an explicit dispatch route. Used by the `$appId` catch-all route loader.
+ *
+ * Resolution order:
+ *
+ * 1. Workspace apps manifest (env, .agent-native/workspace-apps.json, or a
+ *    filesystem scan of `apps/`).
+ *    - `app.url` (absolute URL — externally hosted workspace app) wins if
+ *      present.
+ *    - Otherwise the `app.path` mounted under the workspace gateway is
+ *      used. Path is normalized to a leading slash if missing
+ *      (e.g. manifest entry `path: "my-forms"` -> `/my-forms`), so an app
+ *      whose mounted path differs from its id ends up at the right place
+ *      instead of being silently rewritten to `/${appId}`.
+ *    - Bare entry with no path / url falls back to `/${appId}`.
+ * 2. First-party template registry. When no workspace manifest matches
+ *    (framework dev with each template on its own port, hosted dispatch
+ *    with no sibling apps), return the matching template's deploy URL —
+ *    dev URL in development (e.g. http://localhost:8084 for forms), prod
+ *    URL in production (e.g. https://forms.agent-native.com).
+ *
+ * Returns `null` if neither lookup matches, letting the route render its
+ * "Page not found" pane.
+ */
+/**
+ * Validate `app.url` is an absolute http(s) URL before we trust it as a
+ * redirect target. A bare hostname (`"forms.example.com"`) or a
+ * `javascript:` scheme would otherwise get returned verbatim from
+ * `resolveCatchAllTarget` and produce a broken redirect (or a phishing
+ * vector). Mirrors `normalizeWorkspaceAppUrl` in
+ * `packages/core/src/deploy/workspace-deploy.ts` — but inlined to avoid
+ * pulling the deploy CLI module into a runtime path.
+ */
+function validatedAbsoluteUrl(value: unknown): string | undefined {
+  if (typeof value !== "string" || !value.trim()) return undefined;
+  try {
+    const parsed = new URL(value.trim());
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+      return undefined;
+    }
+    return parsed.toString().replace(/\/$/, "");
+  } catch {
+    return undefined;
+  }
+}
+
+export function resolveCatchAllTarget(
+  appId: string,
+  options: ResolveCatchAllTargetOptions = {},
+): string | null {
+  const apps = options.workspaceApps;
+  if (apps) {
+    const app = apps.find((entry) => entry?.id === appId);
+    if (app) {
+      // Explicit externally-hosted URL wins. Workspaces that point at a
+      // remote deploy (e.g. a sibling app on Netlify) set `url` and we
+      // should bounce the user there rather than mounting a local path
+      // that doesn't exist inside the gateway. Validate the URL first —
+      // a bare hostname or non-http(s) scheme would produce a broken
+      // redirect (and a `javascript:` value would be a phishing vector).
+      const url = validatedAbsoluteUrl(app.url);
+      if (url) {
+        return url;
+      }
+      // Fall back to the mounted path. Normalize to leading slash so an
+      // entry whose path differs from its id (e.g. `id: "forms"`,
+      // `path: "my-forms"`) still lands on the correct gateway mount —
+      // not on `/${appId}`, which would silently route to the wrong app.
+      //
+      // Reject scheme-relative paths. Three variants reach this point —
+      // all of them get collapsed to a single leading slash so the
+      // redirect stays on the gateway:
+      //
+      //   `//evil.example`   — network-path reference, browser treats as
+      //                        absolute (https://evil.example).
+      //   `/\evil.example`   — browsers normalize backslashes to forward
+      //                        slashes during URL parsing, same result.
+      //   `\/evil.example`   — same idea, leading-backslash variant.
+      //
+      // The manifest parser only checks `startsWith("/")` for the first
+      // case, and even that allows `//evil...`. Defend in depth here by
+      // collapsing any run of leading slashes-or-backslashes to one
+      // forward slash. Same phishing vector that `validatedAbsoluteUrl`
+      // closes for `app.url`.
+      if (typeof app.path === "string" && app.path.trim()) {
+        const normalized = app.path.trim().replace(/^[/\\]+/, "/");
+        return normalized.startsWith("/") ? normalized : `/${normalized}`;
+      }
+      return `/${appId}`;
+    }
+  }
+  const builtin = (options.builtinAgents ?? []).find(
+    (agent) => agent.id === appId,
+  );
+  return builtin?.url ?? null;
+}
+
+export async function resolveServerCatchAllTarget(
+  appId: string,
+): Promise<string | null> {
+  if (!import.meta.env.SSR) return null;
+  const { getBuiltinAgents, loadWorkspaceAppsManifest } =
+    await import("@agent-native/core/server/agent-discovery");
+  return resolveCatchAllTarget(appId, {
+    workspaceApps: loadWorkspaceAppsManifest(),
+    builtinAgents: getBuiltinAgents("dispatch"),
+  });
+}

package/src/lib/embed-session-recovery.spec.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  EMBED_SESSION_EXPIRED_MESSAGE,
+  isEmbedSessionExpiredMessage,
+} from "./embed-session-recovery";
+
+const frameWindow = {} as Window;
+const frame = {
+  contentWindow: frameWindow,
+  src: "https://mail.example.test/_agent-native/embed/start?ticket=one",
+} as HTMLIFrameElement;
+
+describe("isEmbedSessionExpiredMessage", () => {
+  it("accepts a message from the active app frame", () => {
+    expect(
+      isEmbedSessionExpiredMessage(
+        { data: { type: EMBED_SESSION_EXPIRED_MESSAGE }, source: frameWindow },
+        frame,
+      ),
+    ).toBe(true);
+  });
+
+  it("rejects messages from another frame", () => {
+    expect(
+      isEmbedSessionExpiredMessage(
+        { data: { type: EMBED_SESSION_EXPIRED_MESSAGE }, source: {} as Window },
+        frame,
+      ),
+    ).toBe(false);
+  });
+
+  it("accepts a matching start URL when the browser omits event.source", () => {
+    expect(
+      isEmbedSessionExpiredMessage(
+        {
+          data: {
+            type: EMBED_SESSION_EXPIRED_MESSAGE,
+            embedStartUrl: frame.src,
+          },
+          source: null,
+        },
+        frame,
+      ),
+    ).toBe(true);
+  });
+
+  it("can match the expected URL before the iframe ref is available", () => {
+    expect(
+      isEmbedSessionExpiredMessage(
+        {
+          data: {
+            type: EMBED_SESSION_EXPIRED_MESSAGE,
+            embedStartUrl: frame.src,
+          },
+          source: null,
+        },
+        null,
+        frame.src,
+      ),
+    ).toBe(true);
+  });
+});

package/src/lib/embed-session-recovery.ts

@@ -0,0 +1,26 @@
+export const EMBED_SESSION_EXPIRED_MESSAGE = "agentNative.embedSessionExpired";
+
+interface EmbedSessionExpiredMessage {
+  type?: unknown;
+  embedStartUrl?: unknown;
+}
+
+export function isEmbedSessionExpiredMessage(
+  event: Pick<MessageEvent, "data" | "source">,
+  frame: Pick<HTMLIFrameElement, "contentWindow" | "src"> | null,
+  expectedStartUrl?: string | null,
+): boolean {
+  const data =
+    event.data && typeof event.data === "object"
+      ? (event.data as EmbedSessionExpiredMessage)
+      : null;
+  if (data?.type !== EMBED_SESSION_EXPIRED_MESSAGE) return false;
+
+  const frameWindow = frame?.contentWindow;
+  if (frameWindow && event.source === frameWindow) return true;
+  if (event.source !== null) return false;
+  if (typeof data.embedStartUrl !== "string") return false;
+
+  const frameUrl = frame?.src || expectedStartUrl;
+  return Boolean(frameUrl && data.embedStartUrl === frameUrl);
+}

package/src/lib/other-apps.spec.ts

@@ -0,0 +1,133 @@
+import { describe, expect, it } from "vitest";
+
+import { filterOtherApps } from "./other-apps.js";
+
+describe("filterOtherApps", () => {
+  it("keeps available linked apps while excluding workspace apps", () => {
+    expect(
+      filterOtherApps(
+        [
+          {
+            id: "slides",
+            name: "Slides",
+            url: "https://slides.agent-native.com",
+          },
+          {
+            id: "analytics",
+            name: "Analytics",
+            description: "Explore data",
+            url: "https://analytics.agent-native.com",
+          },
+          {
+            id: "coach",
+            name: "Coach",
+            url: "https://workspace.example.com/coach",
+            source: "workspace",
+          },
+          {
+            id: "dispatch",
+            name: "Dispatch",
+            url: "https://dispatch.agent-native.com",
+          },
+        ],
+        [{ id: "coach" }],
+      ),
+    ).toEqual([
+      {
+        id: "analytics",
+        name: "Analytics",
+        description: "Explore data",
+        url: "https://analytics.agent-native.com",
+      },
+      {
+        id: "slides",
+        name: "Slides",
+        url: "https://slides.agent-native.com",
+      },
+    ]);
+  });
+
+  it("drops invalid URLs and duplicate app ids", () => {
+    expect(
+      filterOtherApps(
+        [
+          {
+            id: "analytics",
+            name: "Analytics",
+            url: "https://analytics.agent-native.com",
+          },
+          {
+            id: "Analytics",
+            name: "Analytics duplicate",
+            url: "https://duplicate.example.com",
+          },
+          { id: "relative", name: "Relative", url: "/relative" },
+        ],
+        [],
+      ),
+    ).toEqual([
+      {
+        id: "analytics",
+        name: "Analytics",
+        url: "https://analytics.agent-native.com",
+      },
+    ]);
+  });
+
+  it("hides the unsupported CRM and Research entries", () => {
+    expect(
+      filterOtherApps(
+        [
+          {
+            id: "crm",
+            name: "CRM",
+            url: "https://crm.example.com",
+          },
+          {
+            id: "research",
+            name: "Research",
+            url: "https://research.example.com",
+          },
+          {
+            id: "mail",
+            name: "Mail",
+            url: "https://mail.agent-native.com",
+          },
+        ],
+        [],
+      ),
+    ).toEqual([
+      {
+        id: "mail",
+        name: "Mail",
+        url: "https://mail.agent-native.com",
+      },
+    ]);
+  });
+
+  it("hides the generic chat starter from connected app launchers", () => {
+    expect(
+      filterOtherApps(
+        [
+          {
+            id: "chat",
+            name: "Chat",
+            url: "https://chat.agent-native.com",
+          },
+          {
+            id: "mail",
+            name: "Mail",
+            url: "https://mail.agent-native.com",
+          },
+        ],
+        [],
+      ),
+    ).toEqual([
+      {
+        id: "mail",
+        name: "Mail",
+        url: "https://mail.agent-native.com",
+      },
+    ]);
+  });
+});

package/src/lib/other-apps.ts

@@ -0,0 +1,57 @@
+import { isDefaultWorkspaceAppHiddenId } from "./workspace-apps";
+
+export interface ConnectedAppSummary {
+  id: string;
+  name: string;
+  description?: string;
+  url: string;
+  /** Canonical app-home URL used for launchers; `url` remains the A2A endpoint. */
+  homeUrl?: string;
+  color?: string;
+  source?: "builtin" | "custom" | "workspace";
+}
+
+export interface WorkspaceAppId {
+  id: string;
+  isDispatch?: boolean;
+}
+
+const HIDDEN_OTHER_APP_IDS = new Set(["crm", "research"]);
+
+function isHttpUrl(value: string): boolean {
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+export function filterOtherApps(
+  connectedApps: ConnectedAppSummary[],
+  workspaceApps: WorkspaceAppId[],
+): ConnectedAppSummary[] {
+  const workspaceAppIds = new Set([
+    "dispatch",
+    ...workspaceApps.map((app) => app.id.trim().toLowerCase()),
+  ]);
+  const seen = new Set<string>();
+
+  return connectedApps
+    .filter((app) => {
+      const id = app.id.trim().toLowerCase();
+      if (
+        !id ||
+        isDefaultWorkspaceAppHiddenId(id) ||
+        HIDDEN_OTHER_APP_IDS.has(id) ||
+        workspaceAppIds.has(id) ||
+        seen.has(id)
+      )
+        return false;
+      if (app.source === "workspace") return false;
+      if (!isHttpUrl(app.url)) return false;
+      seen.add(id);
+      return true;
+    })
+    .sort((a, b) => a.name.localeCompare(b.name));
+}

package/src/lib/overview-chat.spec.ts

@@ -0,0 +1,51 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const sendToAgentChatMock = vi.hoisted(() => vi.fn(() => "chat-tab"));
+
+vi.mock("@agent-native/core/client/agent-chat", () => ({
+  sendToAgentChat: sendToAgentChatMock,
+}));
+
+const { submitOverviewPrompt } = await import("./overview-chat.js");
+
+describe("submitOverviewPrompt", () => {
+  beforeEach(() => {
+    sendToAgentChatMock.mockClear();
+  });
+
+  it("sends overview prompts to a new local agent tab outside Builder", () => {
+    const tabId = submitOverviewPrompt(" build a metrics app ", "auto");
+
+    expect(tabId).toBe("chat-tab");
+    expect(sendToAgentChatMock).toHaveBeenCalledWith({
+      message: "build a metrics app",
+      submit: true,
+      newTab: true,
+      model: "auto",
+    });
+  });
+
+  it("can submit to a mounted page chat without opening the sidebar", () => {
+    const tabId = submitOverviewPrompt(" build a metrics app ", "auto", {
+      openSidebar: false,
+      selectedEngine: "openai",
+      selectedEffort: "high",
+    });
+
+    expect(tabId).toBe("chat-tab");
+    expect(sendToAgentChatMock).toHaveBeenCalledWith({
+      message: "build a metrics app",
+      submit: true,
+      newTab: true,
+      model: "auto",
+      engine: "openai",
+      effort: "high",
+      openSidebar: false,
+    });
+  });
+
+  it("ignores empty prompts", () => {
+    expect(submitOverviewPrompt("   ", "auto")).toBeNull();
+    expect(sendToAgentChatMock).not.toHaveBeenCalled();
+  });
+});

package/src/lib/overview-chat.ts

@@ -0,0 +1,29 @@
+import {
+  sendToAgentChat,
+  type AgentChatMessage,
+} from "@agent-native/core/client/agent-chat";
+
+interface OverviewChatOptions {
+  openSidebar?: boolean;
+  selectedEngine?: string | null;
+  selectedEffort?: AgentChatMessage["effort"];
+}
+
+export function submitOverviewPrompt(
+  message: string,
+  selectedModel?: string | null,
+  options?: OverviewChatOptions,
+): string | null {
+  const trimmed = message.trim();
+  if (!trimmed) return null;
+
+  return sendToAgentChat({
+    message: trimmed,
+    submit: true,
+    newTab: true,
+    model: selectedModel || undefined,
+    ...(options?.selectedEngine ? { engine: options.selectedEngine } : {}),
+    ...(options?.selectedEffort ? { effort: options.selectedEffort } : {}),
+    ...(options?.openSidebar === false ? { openSidebar: false } : {}),
+  });
+}