@agent-native/dispatch 0.0.0-beta-20260819155526

package/src/actions/provider-api-register.spec.ts

@@ -0,0 +1,193 @@
+/**
+ * Tests for the org-scope authorization added to provider-api-register.
+ *
+ * Plan 014 (advisor-plans/014-custom-registry-scope-authorization.md): this
+ * action previously let ANY authenticated org member upsert/delete an
+ * ORG-scoped custom API provider with no owner/admin check. These tests
+ * assert that org-scope upsert/delete now require the caller to be an org
+ * owner or admin, while user-scope calls and org-scope reads remain
+ * unaffected.
+ */
+
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  getCredentialContext: vi.fn(),
+  execute: vi.fn(),
+  upsertCustomProvider: vi.fn(),
+  deleteCustomProvider: vi.fn(),
+  listCustomProviders: vi.fn(),
+  getCustomProvider: vi.fn(),
+}));
+
+vi.mock("@agent-native/core/server", () => ({
+  getCredentialContext: mocks.getCredentialContext,
+}));
+
+vi.mock("@agent-native/core/db", () => ({
+  getDbExec: () => ({ execute: mocks.execute }),
+}));
+
+// Keep the real `assertCanMutateCustomProviderScope` (it's the guard under
+// test's downstream enforcement point) and only mock the DB-backed CRUD
+// functions, mirroring the `importOriginal` partial-mock pattern used in
+// packages/dispatch/src/server/lib/vault-store.spec.ts.
+vi.mock("@agent-native/core/provider-api", async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import("@agent-native/core/provider-api")>();
+  return {
+    ...actual,
+    upsertCustomProvider: mocks.upsertCustomProvider,
+    deleteCustomProvider: mocks.deleteCustomProvider,
+    listCustomProviders: mocks.listCustomProviders,
+    getCustomProvider: mocks.getCustomProvider,
+  };
+});
+
+const action = (await import("./provider-api-register.js")).default;
+
+function mockOrgRole(role: string | null): void {
+  mocks.execute.mockResolvedValue({ rows: role ? [{ role }] : [] });
+}
+
+const baseUpsertInput = {
+  operation: "upsert" as const,
+  id: "my-api",
+  label: "My API",
+  baseUrl: "https://api.example.com",
+  auth: { type: "none" as const },
+};
+
+describe("provider-api-register org-scope authorization", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mocks.getCredentialContext.mockReturnValue({
+      userEmail: "member@example.com",
+      orgId: "org-a",
+    });
+    mocks.upsertCustomProvider.mockResolvedValue("my-api");
+    mocks.deleteCustomProvider.mockResolvedValue(true);
+  });
+
+  it("rejects an org-scope upsert from a plain member", async () => {
+    mockOrgRole("member");
+
+    await expect(
+      action.run({ ...baseUpsertInput, scope: "org" }),
+    ).rejects.toThrow(/owners and admins/i);
+    expect(mocks.upsertCustomProvider).not.toHaveBeenCalled();
+  });
+
+  it("rejects an org-scope delete from a plain member", async () => {
+    mockOrgRole("member");
+
+    await expect(
+      action.run({ operation: "delete", id: "my-api", scope: "org" }),
+    ).rejects.toThrow(/owners and admins/i);
+    expect(mocks.deleteCustomProvider).not.toHaveBeenCalled();
+  });
+
+  it("rejects an org-scope delete when the caller has no membership row", async () => {
+    mockOrgRole(null);
+
+    await expect(
+      action.run({ operation: "delete", id: "my-api", scope: "org" }),
+    ).rejects.toThrow(/owners and admins/i);
+    expect(mocks.deleteCustomProvider).not.toHaveBeenCalled();
+  });
+
+  it("allows an org-scope upsert from an owner and passes orgRole through", async () => {
+    mockOrgRole("owner");
+
+    await action.run({ ...baseUpsertInput, scope: "org" });
+
+    expect(mocks.upsertCustomProvider).toHaveBeenCalledWith(
+      expect.objectContaining({
+        scope: "org",
+        scopeId: "org-a",
+        orgRole: "owner",
+      }),
+    );
+  });
+
+  it("allows an org-scope delete from an admin and passes orgRole through", async () => {
+    mockOrgRole("admin");
+
+    await action.run({ operation: "delete", id: "my-api", scope: "org" });
+
+    expect(mocks.deleteCustomProvider).toHaveBeenCalledWith(
+      "org",
+      "org-a",
+      "my-api",
+      "admin",
+    );
+  });
+
+  it("does not require an org role for user-scope upsert/delete", async () => {
+    await action.run({ ...baseUpsertInput, scope: "user" });
+    await action.run({ operation: "delete", id: "my-api", scope: "user" });
+
+    expect(mocks.upsertCustomProvider).toHaveBeenCalledWith(
+      expect.objectContaining({
+        scope: "user",
+        scopeId: "member@example.com",
+        orgRole: null,
+      }),
+    );
+    expect(mocks.deleteCustomProvider).toHaveBeenCalledWith(
+      "user",
+      "member@example.com",
+      "my-api",
+      null,
+    );
+    // No membership lookup should even happen for user-scope calls.
+    expect(mocks.execute).not.toHaveBeenCalled();
+  });
+
+  it("allows an org-scope upsert/delete when the caller has no active org", async () => {
+    // No org at all — `resolveOrgId` never wired, or a genuinely org-less
+    // solo user. `scopeId` collapses to the caller's own email (same as
+    // scope: "user"), so there's no other org member to protect against;
+    // this must not hard-reject the action's own default scope.
+    mocks.getCredentialContext.mockReturnValue({
+      userEmail: "solo@example.com",
+      orgId: null,
+    });
+
+    await action.run({ ...baseUpsertInput, scope: "org" });
+    await action.run({ operation: "delete", id: "my-api", scope: "org" });
+
+    expect(mocks.upsertCustomProvider).toHaveBeenCalledWith(
+      expect.objectContaining({
+        scope: "org",
+        scopeId: "solo@example.com",
+        orgRole: "owner",
+      }),
+    );
+    expect(mocks.deleteCustomProvider).toHaveBeenCalledWith(
+      "org",
+      "solo@example.com",
+      "my-api",
+      "owner",
+    );
+    // No org, so no membership lookup should happen either.
+    expect(mocks.execute).not.toHaveBeenCalled();
+  });
+
+  it("does not gate org-scope list/get reads on org role", async () => {
+    mocks.listCustomProviders.mockResolvedValue([]);
+    mocks.getCustomProvider.mockResolvedValue(null);
+
+    await action.run({ operation: "list", scope: "org" });
+    await action.run({ operation: "get", id: "my-api", scope: "org" });
+
+    expect(mocks.listCustomProviders).toHaveBeenCalledWith("org", "org-a");
+    expect(mocks.getCustomProvider).toHaveBeenCalledWith(
+      "org",
+      "org-a",
+      "my-api",
+    );
+    // Reads are intentionally out of scope for the role gate (plan 014).
+    expect(mocks.execute).not.toHaveBeenCalled();
+  });
+});

package/src/actions/provider-api-register.ts

@@ -0,0 +1,35 @@
+import { getDbExec } from "@agent-native/core/db";
+import { createCustomProviderRegistrationAction } from "@agent-native/core/provider-api/actions/custom-provider-registration";
+import { getCredentialContext } from "@agent-native/core/server";
+
+async function resolveCallerOrgRole(
+  orgId: string,
+  email: string,
+): Promise<string | null> {
+  try {
+    const client = getDbExec();
+    const { rows } = await client.execute({
+      sql: `SELECT role FROM org_members WHERE org_id = ? AND LOWER(email) = ? LIMIT 1`,
+      args: [orgId, email.toLowerCase()],
+    });
+    if (rows.length === 0) return null;
+    const role = (rows[0] as { role?: unknown }).role;
+    return typeof role === "string" && role ? role : null;
+  } catch {
+    return null;
+  }
+}
+
+export default createCustomProviderRegistrationAction({
+  description: `Register or update a custom API provider so the agent can call it via provider-api-request and look up its docs via provider-api-docs.
+
+IMPORTANT — credentials:
+- This action stores only credential KEY NAMES, never secret values.
+- If the required API key is not yet saved, instruct the user to add it via app Settings → Keys, or use the create-vault-secret action, before calling this action.
+- Supported auth kinds: none, bearer, basic, api-key-header.
+  google-service-account and oauth-bearer are NOT supported for custom providers.
+
+After registration the provider appears in provider-api-catalog and can be used with provider-api-request.`,
+  getContext: getCredentialContext,
+  resolveOrgRole: resolveCallerOrgRole,
+});

package/src/actions/provider-api-request.ts

@@ -0,0 +1,28 @@
+import {
+  createProviderApiRequestAction,
+  createProviderApiRequestSchema,
+} from "@agent-native/core/provider-api/actions/provider-api";
+import { z } from "zod";
+
+import {
+  DISPATCH_APP_ID,
+  executeProviderApiRequest,
+} from "../server/lib/provider-api.js";
+
+export default createProviderApiRequestAction(
+  { executeRequest: executeProviderApiRequest },
+  {
+    appId: DISPATCH_APP_ID,
+    description:
+      "Make an arbitrary authenticated HTTP request to a shared workspace integration, configured provider API, or custom provider registered via provider-api-register. Use this as the flexible escape hatch when Dispatch needs a provider endpoint, filter, pagination mode, payload, or API version that no canned action models. The request is constrained to the provider host, uses configured credentials automatically, blocks private/internal URLs, and redacts secrets from responses.",
+    schema: createProviderApiRequestSchema(
+      z
+        .string()
+        .min(1)
+        .describe(
+          "Provider id to call — built-in (e.g. slack, github, notion, hubspot, gmail, google_drive, google_calendar, granola, stripe, jira) or a custom provider id registered via provider-api-register. Use provider-api-catalog to list available providers.",
+        ),
+    ),
+    http: false,
+  },
+);

package/src/actions/query-staged-dataset.ts

@@ -0,0 +1,10 @@
+import { createQueryStagedDatasetAction } from "@agent-native/core/provider-api/actions/staged-datasets";
+
+import { DISPATCH_APP_ID } from "../server/lib/provider-api.js";
+
+export default createQueryStagedDatasetAction({
+  appId: DISPATCH_APP_ID,
+  description:
+    "Run a filter/aggregate/project query over a staged dataset previously written by provider-api-request (stageAs). Use after staging provider records, messages, documents, issues, events, or search results to count, group, filter, or project rows without re-fetching provider APIs.",
+  http: false,
+});

package/src/actions/read-slack-thread-context.spec.ts

@@ -0,0 +1,134 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  executeProviderApiRequest: vi.fn(),
+}));
+
+vi.mock("../server/lib/provider-api.js", () => ({
+  executeProviderApiRequest: mocks.executeProviderApiRequest,
+}));
+
+const action = (await import("./read-slack-thread-context.js")).default;
+
+describe("read-slack-thread-context", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("reads the parent thread for a child Slack permalink and preserves evidence", async () => {
+    mocks.executeProviderApiRequest.mockResolvedValue({
+      response: {
+        ok: true,
+        status: 200,
+        json: {
+          ok: true,
+          messages: [
+            {
+              ts: "1785438845.570649",
+              text: "Root https://example.com/issue",
+              attachments: [{ title: "log", url: "https://example.com/log" }],
+            },
+            {
+              ts: "1785438901.123456",
+              thread_ts: "1785438845.570649",
+              text: "Reply",
+            },
+          ],
+          response_metadata: { next_cursor: "next-page" },
+        },
+      },
+    });
+
+    await expect(
+      action.run(
+        {
+          permalink:
+            "https://builder-internal.slack.com/archives/C0ATH3CCZT4/p1785438901123456?thread_ts=1785438845.570649&cid=C0ATH3CCZT4",
+          limit: 100,
+          connectionId: "slack-connection",
+        },
+        {} as never,
+      ),
+    ).resolves.toMatchObject({
+      channelId: "C0ATH3CCZT4",
+      linkedMessageTs: "1785438901.123456",
+      threadTs: "1785438845.570649",
+      completeness: "partial",
+      nextCursor: "next-page",
+      messageCount: 2,
+      relatedLinks: ["https://example.com/issue", "https://example.com/log"],
+    });
+
+    expect(mocks.executeProviderApiRequest).toHaveBeenCalledWith({
+      provider: "slack",
+      method: "GET",
+      path: "/conversations.replies",
+      query: {
+        channel: "C0ATH3CCZT4",
+        ts: "1785438845.570649",
+        limit: 100,
+      },
+      connectionId: "slack-connection",
+      maxBytes: 2 * 1024 * 1024,
+    });
+  });
+
+  it("uses the linked message as the parent when no thread timestamp is present", async () => {
+    mocks.executeProviderApiRequest.mockResolvedValue({
+      response: { ok: true, status: 200, json: { ok: true, messages: [] } },
+    });
+
+    await action.run(
+      {
+        permalink:
+          "https://builder-internal.slack.com/archives/C123/p1234567890123456",
+        limit: 25,
+      },
+      {} as never,
+    );
+
+    expect(mocks.executeProviderApiRequest).toHaveBeenCalledWith(
+      expect.objectContaining({
+        query: {
+          channel: "C123",
+          ts: "1234567890.123456",
+          limit: 25,
+        },
+      }),
+    );
+  });
+
+  it("fails loudly when Slack returns an unreadable thread", async () => {
+    mocks.executeProviderApiRequest.mockResolvedValue({
+      response: {
+        ok: true,
+        status: 200,
+        json: { ok: false, error: "not_in_channel" },
+      },
+    });
+
+    await expect(
+      action.run(
+        {
+          permalink:
+            "https://builder-internal.slack.com/archives/C123/p1234567890123456",
+          limit: 25,
+        },
+        {} as never,
+      ),
+    ).rejects.toThrow("Slack thread read failed: not_in_channel.");
+  });
+
+  it("rejects non-Slack archive URLs before using credentials", async () => {
+    await expect(
+      action.run(
+        {
+          permalink: "https://example.com/archives/C123/p1234567890123456",
+          limit: 25,
+        },
+        {} as never,
+      ),
+    ).rejects.toThrow("Expected an https Slack archive permalink.");
+    expect(mocks.executeProviderApiRequest).not.toHaveBeenCalled();
+  });
+});

package/src/actions/read-slack-thread-context.ts

@@ -0,0 +1,171 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { executeProviderApiRequest } from "../server/lib/provider-api.js";
+
+const SlackPermalinkSchema = z
+  .string()
+  .url()
+  .refine((value) => {
+    const url = new URL(value);
+    return (
+      url.protocol === "https:" &&
+      url.hostname.endsWith(".slack.com") &&
+      url.pathname.startsWith("/archives/")
+    );
+  }, "Expected an https Slack archive permalink.")
+  .describe("Slack message permalink from the issue or feedback report.");
+
+type SlackMessage = {
+  ts?: string;
+  thread_ts?: string;
+  user?: string;
+  username?: string;
+  bot_id?: string;
+  text?: string;
+  blocks?: unknown;
+  attachments?: unknown;
+  files?: unknown;
+  reactions?: unknown;
+};
+
+function parseSlackPermalink(permalink: string) {
+  const url = new URL(permalink);
+  const match = url.pathname.match(/^\/archives\/([^/]+)\/p(\d{16})$/);
+  if (!match) {
+    throw new Error(
+      "Slack permalink must include a channel id and 16-digit message timestamp.",
+    );
+  }
+
+  const [, channelId, compactTimestamp] = match;
+  const linkedMessageTs = `${compactTimestamp.slice(0, 10)}.${compactTimestamp.slice(10)}`;
+  const threadTs = url.searchParams.get("thread_ts") || linkedMessageTs;
+
+  return { channelId, linkedMessageTs, threadTs };
+}
+
+function getResponseJson(response: unknown): Record<string, unknown> {
+  if (!response || typeof response !== "object") {
+    throw new Error("Slack thread read returned no response metadata.");
+  }
+
+  const value = response as { json?: unknown; status?: number; ok?: boolean };
+  if (value.ok !== true) {
+    throw new Error(
+      `Slack thread read failed with HTTP ${value.status ?? "unknown"}.`,
+    );
+  }
+  if (!value.json || typeof value.json !== "object") {
+    throw new Error("Slack thread read returned no JSON body.");
+  }
+
+  const body = value.json as Record<string, unknown>;
+  if (body.ok !== true) {
+    const error = typeof body.error === "string" ? body.error : "unknown_error";
+    throw new Error(`Slack thread read failed: ${error}.`);
+  }
+  return body;
+}
+
+function collectLinks(value: unknown, links: Set<string>): void {
+  if (typeof value === "string") {
+    for (const match of value.matchAll(/https?:\/\/[^\s<>|]+/g)) {
+      links.add(match[0].replace(/[),.;]+$/, ""));
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) collectLinks(item, links);
+    return;
+  }
+  if (!value || typeof value !== "object") return;
+
+  for (const [key, child] of Object.entries(value)) {
+    if (key === "url" && typeof child === "string") links.add(child);
+    else collectLinks(child, links);
+  }
+}
+
+function projectMessage(message: SlackMessage) {
+  return {
+    ts: message.ts ?? null,
+    threadTs: message.thread_ts ?? null,
+    user: message.user ?? null,
+    username: message.username ?? null,
+    botId: message.bot_id ?? null,
+    text: message.text ?? "",
+    ...(message.blocks ? { blocks: message.blocks } : {}),
+    ...(message.attachments ? { attachments: message.attachments } : {}),
+    ...(message.files ? { files: message.files } : {}),
+    ...(message.reactions ? { reactions: message.reactions } : {}),
+  };
+}
+
+export default defineAction({
+  description:
+    "Read the complete Slack thread behind an issue permalink before diagnosing or fixing it. Resolves a child permalink to its parent, returns messages plus attachments and related links, and reports pagination completeness. Read-only; never joins a channel or sends a message.",
+  schema: z.object({
+    permalink: SlackPermalinkSchema,
+    limit: z.coerce
+      .number()
+      .int()
+      .min(1)
+      .max(1000)
+      .default(100)
+      .describe("Maximum Slack messages to return in this page."),
+    cursor: z
+      .string()
+      .optional()
+      .describe("Slack response_metadata.next_cursor from a previous page."),
+    connectionId: z
+      .string()
+      .optional()
+      .describe(
+        "Optional connected Slack workspace id when several are granted.",
+      ),
+  }),
+  http: false,
+  readOnly: true,
+  run: async ({ permalink, limit, cursor, connectionId }) => {
+    const parsed = parseSlackPermalink(permalink);
+    const result = await executeProviderApiRequest({
+      provider: "slack",
+      method: "GET",
+      path: "/conversations.replies",
+      query: {
+        channel: parsed.channelId,
+        ts: parsed.threadTs,
+        limit,
+        ...(cursor ? { cursor } : {}),
+      },
+      connectionId,
+      maxBytes: 2 * 1024 * 1024,
+    });
+
+    const response = (result as { response?: unknown }).response;
+    const body = getResponseJson(response);
+    const messages = Array.isArray(body.messages)
+      ? (body.messages as SlackMessage[])
+      : [];
+    const nextCursor =
+      body.response_metadata && typeof body.response_metadata === "object"
+        ? (body.response_metadata as { next_cursor?: unknown }).next_cursor
+        : null;
+    const relatedLinks = new Set<string>();
+    collectLinks(messages, relatedLinks);
+
+    return {
+      permalink,
+      channelId: parsed.channelId,
+      linkedMessageTs: parsed.linkedMessageTs,
+      threadTs: parsed.threadTs,
+      messages: messages.map(projectMessage),
+      messageCount: messages.length,
+      completeness: nextCursor ? "partial" : "complete",
+      nextCursor:
+        typeof nextCursor === "string" && nextCursor ? nextCursor : null,
+      relatedLinks: [...relatedLinks],
+    };
+  },
+});

package/src/actions/reject-dispatch-change.ts

@@ -0,0 +1,13 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { rejectRequest } from "../server/lib/dispatch-store.js";
+
+export default defineAction({
+  description: "Reject a pending dispatch change request.",
+  schema: z.object({
+    id: z.string().describe("Approval request id"),
+    reason: z.string().optional().describe("Optional rejection reason"),
+  }),
+  run: async ({ id, reason }) => rejectRequest(id, reason),
+});

package/src/actions/reject-dream-proposal.ts

@@ -0,0 +1,13 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { rejectDreamProposal } from "../server/lib/dreams-store.js";
+
+export default defineAction({
+  description: "Reject one pending Dispatch dream proposal.",
+  schema: z.object({
+    id: z.string().min(1).describe("Dream proposal id."),
+    reason: z.string().optional().describe("Optional rejection reason."),
+  }),
+  run: async ({ id, reason }) => rejectDreamProposal(id, reason),
+});