@agent-native/dispatch 0.0.0-beta-20260819155526

package/src/actions/connect-external-agent.ts

@@ -0,0 +1,92 @@
+import { defineAction } from "@agent-native/core";
+import { getDbExec } from "@agent-native/core/db";
+import {
+  resourceGetByPath,
+  resourcePut,
+  sharedResourceOwner,
+} from "@agent-native/core/resources/store";
+import { z } from "zod";
+
+import {
+  currentOrgId,
+  currentOwnerEmail,
+} from "../server/lib/dispatch-store.js";
+
+function slugify(value: string): string {
+  return (
+    value
+      .trim()
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "") || "agent"
+  );
+}
+
+async function assertCanManageSharedAgent() {
+  const orgId = currentOrgId();
+  if (!orgId) return;
+  const actor = currentOwnerEmail().trim().toLowerCase();
+  const result = await getDbExec().execute({
+    sql: "SELECT role FROM org_members WHERE org_id = ? AND LOWER(email) = ? LIMIT 1",
+    args: [orgId, actor],
+  });
+  const role = result.rows[0]?.role;
+  if (role !== "owner" && role !== "admin") {
+    throw new Error(
+      "Only organization owners and admins can connect shared agents.",
+    );
+  }
+}
+
+export default defineAction({
+  description:
+    "Connect an existing HTTP/A2A agent to Dispatch. This stores only its public endpoint and metadata; authentication remains in the normal A2A/MCP connection flow.",
+  schema: z.object({
+    url: z.string().min(1).describe("HTTP or HTTPS agent endpoint"),
+    name: z.string().max(160).optional().describe("Agent name"),
+    description: z.string().max(500).optional().describe("Short description"),
+    scope: z
+      .enum(["shared", "personal"])
+      .default("shared")
+      .describe("Share with the workspace or keep the connection personal"),
+  }),
+  run: async ({ url, name, description, scope }) => {
+    const parsed = new URL(url.trim());
+    if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+      throw new Error("Use an http:// or https:// endpoint URL.");
+    }
+    if (parsed.username || parsed.password) {
+      throw new Error("Do not include credentials in the endpoint URL.");
+    }
+
+    if (scope === "shared") await assertCanManageSharedAgent();
+    const agentName = name?.trim() || parsed.hostname.replace(/^www\./, "");
+    const id = slugify(agentName);
+    const path = `remote-agents/${id}.json`;
+    const owner =
+      scope === "shared"
+        ? sharedResourceOwner(currentOrgId())
+        : currentOwnerEmail();
+    const existing = await resourceGetByPath(owner, path);
+    if (existing) {
+      throw new Error(
+        `An external agent already exists at ${path}. Rename it before connecting again.`,
+      );
+    }
+
+    const manifest = {
+      id,
+      name: agentName,
+      ...(description?.trim() ? { description: description.trim() } : {}),
+      url: parsed.toString(),
+    };
+    const resource = await resourcePut(
+      owner,
+      path,
+      JSON.stringify(manifest, null, 2),
+      "application/json",
+    );
+
+    return { status: "created" as const, resource, agent: manifest, scope };
+  },
+});

package/src/actions/create-browser-chat-session.spec.ts

@@ -0,0 +1,122 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const server = vi.hoisted(() => ({
+  buildStartPath: vi.fn(
+    (ticket: string) => `/_agent-native/embed/start?ticket=${ticket}`,
+  ),
+  createTicket: vi.fn(),
+  getContext: vi.fn(),
+  getEmail: vi.fn(),
+}));
+const dispatch = vi.hoisted(() => ({
+  getConfig: vi.fn(),
+}));
+const integrations = vi.hoisted(() => ({
+  createRemoteDevice: vi.fn(),
+}));
+
+vi.mock("@agent-native/core/server", () => ({
+  buildEmbedStartPath: server.buildStartPath,
+  createEmbedSessionTicket: server.createTicket,
+  getRequestContext: server.getContext,
+  getRequestUserEmail: server.getEmail,
+  withConfiguredAppBasePath: (origin: string) => origin,
+}));
+vi.mock("@agent-native/core/integrations", () => ({
+  createRemoteDevice: integrations.createRemoteDevice,
+}));
+vi.mock("../server/index.js", () => ({
+  getDispatchConfig: dispatch.getConfig,
+}));
+
+import action from "./create-browser-chat-session.js";
+
+const nonce = "browser-chat-nonce-1234567890";
+const extensionId = "abcdefghijklmnopabcdefghijklmnop";
+const parentOrigin = `chrome-extension://${extensionId}`;
+
+describe("create-browser-chat-session", () => {
+  beforeEach(() => {
+    server.createTicket.mockReset();
+    server.getContext.mockReturnValue({
+      orgId: "org-example",
+      requestOrigin: "https://dispatch.example.com",
+    });
+    server.getEmail.mockReturnValue("user@example.com");
+    dispatch.getConfig.mockReturnValue({
+      browserExtensionIds: [extensionId],
+    });
+    integrations.createRemoteDevice.mockResolvedValue({
+      device: { id: "remote-device-example" },
+      token: "anr_example",
+    });
+  });
+
+  it("mints a one-time ticket bound to the bridge nonce and parent origin", async () => {
+    server.createTicket.mockResolvedValue({
+      ticket: "ticket-example",
+      ticketHash: "hash-example",
+      expiresAt: 12345,
+    });
+
+    await expect(action.run({ nonce, extensionId })).resolves.toEqual({
+      startPath: "/_agent-native/embed/start?ticket=ticket-example",
+      expiresAt: 12345,
+      parentOrigin,
+      remoteDevice: {
+        id: "remote-device-example",
+        token: "anr_example",
+      },
+      relayBaseUrl: "https://dispatch.example.com",
+    });
+    expect(server.createTicket).toHaveBeenCalledWith({
+      ownerEmail: "user@example.com",
+      orgId: "org-example",
+      targetPath:
+        "/browser-chat?browserChatNonce=browser-chat-nonce-1234567890&browserChatParentOrigin=chrome-extension%3A%2F%2Fabcdefghijklmnopabcdefghijklmnop",
+      scope: "browser-chat",
+      ttlSeconds: 60,
+    });
+    expect(action.agentTool).toBe(false);
+    expect(action.toolCallable).toBe(false);
+    expect(integrations.createRemoteDevice).toHaveBeenCalledWith({
+      ownerEmail: "user@example.com",
+      orgId: "org-example",
+      label: "Agent Native for Chrome",
+      platform: "chrome-extension",
+      metadata: {
+        browserExtension: { extensionId },
+        computerCapabilities: {
+          browser: {
+            observe: true,
+            control: true,
+            provider: "agent-native-chrome-extension",
+          },
+        },
+      },
+    });
+  });
+
+  it("fails closed without an authenticated Dispatch identity", async () => {
+    server.getEmail.mockReturnValue(undefined);
+
+    await expect(action.run({ nonce, extensionId })).rejects.toThrow(
+      "Sign in to Dispatch",
+    );
+    expect(server.createTicket).not.toHaveBeenCalled();
+  });
+
+  it("rejects an extension id that is not configured in production", async () => {
+    const previousNodeEnv = process.env.NODE_ENV;
+    process.env.NODE_ENV = "production";
+    dispatch.getConfig.mockReturnValue({ browserExtensionIds: [] });
+    try {
+      await expect(action.run({ nonce, extensionId })).rejects.toThrow(
+        "not allowed",
+      );
+    } finally {
+      process.env.NODE_ENV = previousNodeEnv;
+    }
+    expect(server.createTicket).not.toHaveBeenCalled();
+  });
+});

package/src/actions/create-browser-chat-session.ts

@@ -0,0 +1,99 @@
+import { defineAction } from "@agent-native/core";
+import { createRemoteDevice } from "@agent-native/core/integrations";
+import {
+  buildEmbedStartPath,
+  createEmbedSessionTicket,
+  getRequestContext,
+  getRequestUserEmail,
+  withConfiguredAppBasePath,
+} from "@agent-native/core/server";
+import { z } from "zod";
+
+import {
+  BROWSER_CHAT_NONCE_QUERY_PARAM,
+  BROWSER_CHAT_PARENT_ORIGIN_QUERY_PARAM,
+  browserChatExtensionIdSchema,
+  browserChatNonceSchema,
+} from "../lib/browser-chat-protocol.js";
+import { isBrowserExtensionIdAllowed } from "../server/lib/browser-extension-allowlist.js";
+
+export default defineAction({
+  description:
+    "Create a one-time authenticated Dispatch browser-chat embed session for an approved Agent-Native Chrome extension.",
+  schema: z
+    .object({
+      nonce: browserChatNonceSchema,
+      extensionId: browserChatExtensionIdSchema,
+    })
+    .strict(),
+  readOnly: false,
+  parallelSafe: true,
+  agentTool: false,
+  toolCallable: false,
+  run: async ({ nonce, extensionId }) => {
+    const ownerEmail = getRequestUserEmail()?.trim();
+    if (!ownerEmail) {
+      throw new Error(
+        "Sign in to Dispatch before connecting the browser extension.",
+      );
+    }
+
+    const requestContext = getRequestContext();
+    const { browserExtensionIds } = await import("../server/index.js").then(
+      (module) => module.getDispatchConfig(),
+    );
+    if (
+      !isBrowserExtensionIdAllowed({
+        extensionId,
+        configIds: browserExtensionIds,
+        nodeEnv: process.env.NODE_ENV,
+        requestOrigin: requestContext?.requestOrigin,
+      })
+    ) {
+      throw new Error(
+        "This browser extension is not allowed to connect to Dispatch.",
+      );
+    }
+
+    const parentOrigin = `chrome-extension://${extensionId}`;
+    const requestOrigin = requestContext?.requestOrigin;
+    if (!requestOrigin) {
+      throw new Error("Dispatch could not resolve its browser relay URL.");
+    }
+    const query = new URLSearchParams({
+      [BROWSER_CHAT_NONCE_QUERY_PARAM]: nonce,
+      [BROWSER_CHAT_PARENT_ORIGIN_QUERY_PARAM]: parentOrigin,
+    });
+    const session = await createEmbedSessionTicket({
+      ownerEmail,
+      orgId: requestContext?.orgId ?? null,
+      targetPath: `/browser-chat?${query}`,
+      scope: "browser-chat",
+      ttlSeconds: 60,
+    });
+    const remote = await createRemoteDevice({
+      ownerEmail,
+      orgId: requestContext?.orgId ?? null,
+      label: "Agent Native for Chrome",
+      platform: "chrome-extension",
+      metadata: {
+        browserExtension: { extensionId },
+        computerCapabilities: {
+          browser: {
+            observe: true,
+            control: true,
+            provider: "agent-native-chrome-extension",
+          },
+        },
+      },
+    });
+
+    return {
+      startPath: buildEmbedStartPath(session.ticket),
+      expiresAt: session.expiresAt,
+      parentOrigin,
+      remoteDevice: { id: remote.device.id, token: remote.token },
+      relayBaseUrl: withConfiguredAppBasePath(requestOrigin),
+    };
+  },
+});

package/src/actions/create-dream-report.ts

@@ -0,0 +1,77 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { createDreamReport } from "../server/lib/dreams-store.js";
+
+export default defineAction({
+  description:
+    "Create a Dispatch dream report from existing thread-debug records and produce pending, evidence-backed memory proposals without calling an LLM.",
+  schema: z.object({
+    sourceId: z
+      .string()
+      .default("current")
+      .describe(
+        "Thread debug source id from list-agent-thread-sources. Use 'all' to scan every connected source.",
+      ),
+    sourceIds: z
+      .array(z.string().min(1))
+      .optional()
+      .describe(
+        "Optional explicit source ids to scan together. When provided, sourceId is treated as aggregate.",
+      ),
+    allSources: z.coerce
+      .boolean()
+      .default(false)
+      .describe(
+        "Scan every connected thread-debug source with partial results.",
+      ),
+    query: z
+      .string()
+      .optional()
+      .describe("Optional search term to focus dream candidate discovery."),
+    ownerEmail: z
+      .string()
+      .optional()
+      .describe(
+        "Optional owner email filter. Admins may pass '*' or omit to use their admin-visible scope.",
+      ),
+    limit: z.coerce.number().int().min(1).max(50).default(20),
+    sourceTimeoutMs: z.coerce
+      .number()
+      .int()
+      .min(1000)
+      .max(60000)
+      .default(15000)
+      .describe("Per-source timeout in milliseconds for partial scans."),
+    sourceConcurrency: z.coerce
+      .number()
+      .int()
+      .min(1)
+      .max(8)
+      .default(2)
+      .describe("How many thread-debug sources to scan at once."),
+    sourceStartStaggerMs: z.coerce
+      .number()
+      .int()
+      .min(0)
+      .max(5000)
+      .default(250)
+      .describe("Delay between source starts within a scan batch."),
+    threadConcurrency: z.coerce
+      .number()
+      .int()
+      .min(1)
+      .max(10)
+      .default(3)
+      .describe("How many threads to inspect at once within each source."),
+    threadTimeoutMs: z.coerce
+      .number()
+      .int()
+      .min(1000)
+      .max(30000)
+      .default(8000)
+      .describe("Per-thread debug timeout in milliseconds."),
+    title: z.string().optional().describe("Optional title for the dream pass."),
+  }),
+  run: async (input) => createDreamReport(input),
+});

package/src/actions/create-link-token.ts

@@ -0,0 +1,13 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { createLinkToken } from "../server/lib/dispatch-store.js";
+
+export default defineAction({
+  description:
+    "Create a /link token so a Slack or Telegram user can bind to their personal dispatch identity.",
+  schema: z.object({
+    platform: z.enum(["slack", "telegram"]),
+  }),
+  run: async ({ platform }) => createLinkToken(platform),
+});

package/src/actions/create-pylon-ticket.ts

@@ -0,0 +1,111 @@
+import { defineAction } from "@agent-native/core";
+import { resolveSecret } from "@agent-native/core/server";
+import { z } from "zod";
+
+import { recordAudit } from "../server/lib/dispatch-store.js";
+
+const PYLON_API_BASE =
+  process.env.PYLON_API_BASE_URL || "https://api.usepylon.com";
+
+export default defineAction({
+  description:
+    "Create a Pylon ticket. Use to escalate blockers from client meetings, route unmatched #customer-* posts that have no Slack channel, or open a follow-up that needs tracking. Requires PYLON_API_KEY in the Vault.",
+  schema: z.object({
+    title: z.string().min(1).describe("Short ticket title"),
+    bodyHtml: z
+      .string()
+      .min(1)
+      .describe("HTML body — Pylon renders this in the ticket"),
+    requesterEmail: z
+      .string()
+      .email()
+      .optional()
+      .describe("Email of the person the ticket is on behalf of"),
+    requesterName: z.string().optional(),
+    accountId: z
+      .string()
+      .optional()
+      .describe(
+        "Pylon account ID — provide either this OR requesterEmail to identify the subject",
+      ),
+    priority: z.enum(["urgent", "high", "medium", "low"]).optional(),
+    tags: z.array(z.string()).optional(),
+    assigneeId: z.string().optional(),
+    teamId: z.string().optional(),
+  }),
+  run: async (input) => {
+    const apiKey = await resolveSecret("PYLON_API_KEY");
+    if (!apiKey) {
+      throw new Error(
+        "PYLON_API_KEY is not set. Add it to the Dispatch Vault.",
+      );
+    }
+    if (!input.accountId && !input.requesterEmail) {
+      throw new Error(
+        "Pylon requires either accountId or requesterEmail to identify the ticket subject.",
+      );
+    }
+
+    const payload: Record<string, unknown> = {
+      title: input.title,
+      body_html: input.bodyHtml,
+    };
+    if (input.accountId) payload.account_id = input.accountId;
+    if (input.requesterEmail) payload.requester_email = input.requesterEmail;
+    if (input.requesterName) payload.requester_name = input.requesterName;
+    if (input.priority) payload.priority = input.priority;
+    if (input.tags?.length) payload.tags = input.tags;
+    if (input.assigneeId) payload.assignee_id = input.assigneeId;
+    if (input.teamId) payload.team_id = input.teamId;
+
+    const res = await fetch(`${PYLON_API_BASE}/issues`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(payload),
+    });
+
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(
+        `Pylon ticket creation failed (HTTP ${res.status})${text ? `: ${text.slice(0, 500)}` : ""}`,
+      );
+    }
+
+    const data = (await res.json().catch(() => null)) as Record<
+      string,
+      unknown
+    > | null;
+    const issue =
+      data && typeof data === "object" && "issue" in data
+        ? ((data as { issue?: Record<string, unknown> }).issue ?? {})
+        : (data ?? {});
+    const ticketId =
+      issue && typeof (issue as { id?: unknown }).id === "string"
+        ? (issue as { id: string }).id
+        : "";
+
+    await recordAudit({
+      action: "pylon.ticket.created",
+      targetType: "pylon-ticket",
+      targetId: ticketId || null,
+      summary: `Created Pylon ticket: ${input.title}`,
+      metadata: {
+        title: input.title,
+        priority: input.priority,
+        tags: input.tags,
+        accountId: input.accountId,
+        requesterEmail: input.requesterEmail,
+        ticketId,
+      },
+    });
+
+    return {
+      ok: true as const,
+      ticketId,
+      ticket: issue,
+    };
+  },
+});

package/src/actions/create-vault-grant.ts

@@ -0,0 +1,16 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { createGrant } from "../server/lib/vault-store.js";
+
+export default defineAction({
+  description:
+    "Grant an app access to a vault secret in manual vault access mode. Admin only.",
+  schema: z.object({
+    secretId: z.string().describe("ID of the secret to grant"),
+    appId: z
+      .string()
+      .describe("App ID to grant access to, e.g. mail, calendar"),
+  }),
+  run: async (args) => createGrant(args.secretId, args.appId),
+});

package/src/actions/create-vault-secret.ts

@@ -0,0 +1,28 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { createSecret } from "../server/lib/vault-store.js";
+
+export default defineAction({
+  description:
+    "Store a secret in the workspace vault. Admin only. Existing credential keys are updated. By default, saved vault keys are available to every workspace app; manual mode uses per-app grants.",
+  schema: z.object({
+    credentialKey: z
+      .string()
+      .min(1)
+      .describe("Environment variable name, e.g. GOOGLE_CLIENT_ID"),
+    value: z.string().min(1).describe("The secret value"),
+    name: z.string().min(1).describe("Human-readable label for this secret"),
+    provider: z
+      .string()
+      .optional()
+      .describe("Provider grouping tag, e.g. google, sendgrid, slack"),
+    description: z.string().optional().describe("Optional description"),
+  }),
+  // This action's whole purpose is to carry a secret `value`. The vault owns
+  // secret storage; the audit log must record THAT a secret was created — never
+  // the value. Opt out of input capture so the trail can't become a second
+  // durable credential store.
+  audit: { recordInputs: false },
+  run: async (args) => createSecret(args),
+});

package/src/actions/create-workspace-resource-grant.ts

@@ -0,0 +1,16 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { createResourceGrant } from "../server/lib/workspace-resources-store.js";
+
+export default defineAction({
+  description:
+    "Grant an app access to a workspace resource (skill, instruction, agent, knowledge pack, or MCP server). Admin only.",
+  schema: z.object({
+    resourceId: z.string().describe("Workspace resource ID"),
+    appId: z
+      .string()
+      .describe("App ID to grant access to, e.g. mail, analytics"),
+  }),
+  run: async (args) => createResourceGrant(args.resourceId, args.appId),
+});

package/src/actions/create-workspace-resource.ts

@@ -0,0 +1,37 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { createWorkspaceResource } from "../server/lib/workspace-resources-store.js";
+
+export default defineAction({
+  description:
+    'Create a workspace-wide skill, instruction, agent profile, reference resource, or MCP server. Set scope to "all" for runtime inheritance by every app, or "selected" to grant per-app. When Dispatch approval policy is enabled, All-app creates queue an approval request before taking effect.',
+  schema: z.object({
+    kind: z
+      .enum([
+        "skill",
+        "instruction",
+        "agent",
+        "agent-file",
+        "knowledge",
+        "mcp-server",
+      ])
+      .describe(
+        "Resource kind: skill, instruction, agent, agent-file, knowledge, or mcp-server",
+      ),
+    name: z.string().describe("Human-readable name"),
+    description: z.string().optional().describe("Short description"),
+    path: z
+      .string()
+      .describe(
+        'Resource path in target apps. Use "skills/<name>/SKILL.md" for skills, "AGENTS.md" or "instructions/<name>.md" for always-on guardrails, "context/<name>.md" for reference resources, "agents/<name>.md" for custom agents, and "mcp-servers/<name>.json" for HTTP MCP servers.',
+      ),
+    content: z.string().describe("Full resource content (markdown or JSON)"),
+    scope: z
+      .enum(["all", "selected"])
+      .describe(
+        '"all" = inherited by every app at runtime, "selected" = only apps with explicit grants',
+      ),
+  }),
+  run: async (args) => createWorkspaceResource(args),
+});

package/src/actions/create_embed_session.ts

@@ -0,0 +1,30 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { createGrantedDispatchMcpEmbedSession } from "../server/lib/mcp-gateway.js";
+
+export default defineAction({
+  description:
+    "MCP Apps helper: create a browser embed session for a Dispatch-granted app URL. Usually called by an MCP App iframe, not directly by the model.",
+  schema: z.object({
+    app: z
+      .string()
+      .optional()
+      .describe("Optional granted app id when path is app-relative."),
+    url: z
+      .string()
+      .optional()
+      .describe("Absolute URL returned by open_app, or app-relative path."),
+    path: z
+      .string()
+      .optional()
+      .describe("App-relative path. Requires app when url is not provided."),
+    chrome: z
+      .enum(["full", "minimal"])
+      .optional()
+      .describe("Embed chrome preference. Defaults to full."),
+  }),
+  readOnly: false,
+  parallelSafe: true,
+  run: async (args) => createGrantedDispatchMcpEmbedSession(args),
+});