@agent-native/dispatch 0.0.0-beta-20260819155526

package/src/actions/create_workspace_app_embed_session.spec.ts

@@ -0,0 +1,122 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const server = vi.hoisted(() => ({
+  getRequestContext: vi.fn(),
+}));
+const apps = vi.hoisted(() => ({
+  listWorkspaceApps: vi.fn(),
+}));
+
+vi.mock("@agent-native/core/server", () => ({
+  getRequestContext: server.getRequestContext,
+}));
+vi.mock("../server/lib/app-creation-store.js", () => ({
+  listWorkspaceApps: apps.listWorkspaceApps,
+}));
+vi.mock("../server/lib/mcp-gateway.js", () => ({
+  createWorkspaceSsoEmbedSession: vi.fn(),
+}));
+
+import { assertWorkspaceEmbedSessionCaller } from "./create_workspace_app_embed_session.js";
+
+describe("assertWorkspaceEmbedSessionCaller", () => {
+  beforeEach(() => {
+    apps.listWorkspaceApps.mockClear();
+    server.getRequestContext.mockReturnValue({
+      requestOrigin: "https://dispatch.agent-native.com",
+    });
+    apps.listWorkspaceApps.mockResolvedValue([
+      {
+        id: "custom-app",
+        path: "/apps/custom-app",
+        url: "https://dispatch.agent-native.com/apps/custom-app",
+        isDispatch: false,
+      },
+    ]);
+  });
+
+  it("allows direct in-process calls and native parent bearer calls", async () => {
+    await expect(
+      assertWorkspaceEmbedSessionCaller(undefined),
+    ).resolves.toBeUndefined();
+    await expect(
+      assertWorkspaceEmbedSessionCaller(
+        new Headers({
+          Authorization: "Bearer parent-session",
+        }),
+      ),
+    ).resolves.toBeUndefined();
+    expect(apps.listWorkspaceApps).not.toHaveBeenCalled();
+  });
+
+  it("allows the native marker when Chromium adds cross-site fetch metadata", async () => {
+    await expect(
+      assertWorkspaceEmbedSessionCaller(
+        new Headers({
+          "Sec-Fetch-Site": "cross-site",
+          "X-Agent-Native-CSRF": "1",
+        }),
+      ),
+    ).resolves.toBeUndefined();
+    expect(apps.listWorkspaceApps).not.toHaveBeenCalled();
+  });
+
+  it("allows a same-origin Dispatch browser caller", async () => {
+    await expect(
+      assertWorkspaceEmbedSessionCaller(
+        new Headers({
+          Referer: "https://dispatch.agent-native.com/apps/clips",
+          "Sec-Fetch-Site": "same-origin",
+        }),
+      ),
+    ).resolves.toBeUndefined();
+    expect(apps.listWorkspaceApps).toHaveBeenCalledWith({
+      includeAgentCards: false,
+      audience: "all",
+    });
+  });
+
+  it("rejects cross-site and child-app browser callers", async () => {
+    await expect(
+      assertWorkspaceEmbedSessionCaller(
+        new Headers({
+          Referer: "https://evil.example/",
+          "Sec-Fetch-Site": "cross-site",
+        }),
+      ),
+    ).rejects.toThrow("requested by Dispatch");
+
+    await expect(
+      assertWorkspaceEmbedSessionCaller(
+        new Headers({
+          Referer: "https://dispatch.agent-native.com/apps/custom-app/",
+          "Sec-Fetch-Site": "same-origin",
+        }),
+      ),
+    ).rejects.toThrow("cannot mint sessions for themselves");
+  });
+
+  it("does not let a browser bearer bypass the fetch-metadata gate", async () => {
+    await expect(
+      assertWorkspaceEmbedSessionCaller(
+        new Headers({
+          Authorization: "Bearer attacker-set-header",
+          Referer: "https://dispatch.agent-native.com/apps/custom-app/",
+          "Sec-Fetch-Site": "same-origin",
+        }),
+      ),
+    ).rejects.toThrow("cannot mint sessions for themselves");
+  });
+
+  it("fails closed when the browser caller has no trustworthy parent context", async () => {
+    server.getRequestContext.mockReturnValue(undefined);
+    await expect(
+      assertWorkspaceEmbedSessionCaller(
+        new Headers({
+          Referer: "https://dispatch.agent-native.com/",
+          "Sec-Fetch-Site": "same-origin",
+        }),
+      ),
+    ).rejects.toThrow("requested by Dispatch");
+  });
+});

package/src/actions/create_workspace_app_embed_session.ts

@@ -0,0 +1,102 @@
+import { defineAction } from "@agent-native/core";
+import { getRequestContext } from "@agent-native/core/server";
+import { z } from "zod";
+
+import { listWorkspaceApps } from "../server/lib/app-creation-store.js";
+import { createWorkspaceSsoEmbedSession } from "../server/lib/mcp-gateway.js";
+
+function isPathWithinApp(pathname: string, appPath: string): boolean {
+  const normalized = appPath.replace(/\/+$/, "") || "/";
+  return normalized === "/"
+    ? pathname.startsWith("/")
+    : pathname === normalized || pathname.startsWith(`${normalized}/`);
+}
+
+/**
+ * Browser callers must come from the Dispatch parent surface. Native callers
+ * carry the parent bearer explicitly; direct in-process action calls have no
+ * request headers and are already inside the server authorization boundary.
+ */
+export async function assertWorkspaceEmbedSessionCaller(
+  headers: Headers | undefined,
+): Promise<void> {
+  if (!headers) return;
+
+  const fetchSite = headers.get("sec-fetch-site")?.trim().toLowerCase();
+  // Electron's Chromium fetch adds Sec-Fetch-Site even for the native broker's
+  // server request. The custom header is not sendable by a cross-origin page
+  // without a successful CORS preflight, so it is the native CSRF marker.
+  if (
+    fetchSite &&
+    fetchSite !== "same-origin" &&
+    headers.get("x-agent-native-csrf")?.trim() === "1"
+  ) {
+    return;
+  }
+  // Browsers always send Sec-Fetch-Site and page scripts cannot forge or strip
+  // this forbidden header. Native clients without fetch metadata authenticate
+  // through the normal action request context below.
+  if (!fetchSite) return;
+  if (fetchSite !== "same-origin") {
+    throw new Error("Workspace app sessions must be requested by Dispatch.");
+  }
+
+  const referer = headers.get("referer");
+  const requestOrigin = getRequestContext()?.requestOrigin;
+  if (!referer || !requestOrigin) {
+    throw new Error("Workspace app sessions must be requested by Dispatch.");
+  }
+
+  let refererUrl: URL;
+  try {
+    refererUrl = new URL(referer);
+  } catch {
+    throw new Error("Workspace app sessions must be requested by Dispatch.");
+  }
+  if (refererUrl.origin !== requestOrigin) {
+    throw new Error("Workspace app sessions must be requested by Dispatch.");
+  }
+  const apps = await listWorkspaceApps({
+    includeAgentCards: false,
+    audience: "all",
+  });
+  if (
+    apps.some(
+      (app) =>
+        !app.isDispatch && isPathWithinApp(refererUrl.pathname, app.path),
+    )
+  ) {
+    throw new Error("Workspace apps cannot mint sessions for themselves.");
+  }
+}
+
+export default defineAction({
+  description:
+    "Create a one-time app-scoped embed session for a workspace app opened inside Dispatch. This browser-only path is rollout-gated and never exposes an app's reusable session to another app.",
+  schema: z.object({
+    app: z
+      .string()
+      .optional()
+      .describe("Workspace app id when path is app-relative."),
+    url: z
+      .string()
+      .optional()
+      .describe("Absolute app URL 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: false,
+  agentTool: false,
+  toolCallable: false,
+  run: async (args, context) => {
+    await assertWorkspaceEmbedSessionCaller(context?.requestHeaders);
+    return createWorkspaceSsoEmbedSession(args);
+  },
+});

package/src/actions/delete-destination.ts

@@ -0,0 +1,12 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { deleteDestination } from "../server/lib/dispatch-store.js";
+
+export default defineAction({
+  description: "Delete a saved dispatch destination.",
+  schema: z.object({
+    id: z.string().describe("Destination id"),
+  }),
+  run: async ({ id }) => deleteDestination(id),
+});

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

@@ -0,0 +1,10 @@
+import { createDeleteStagedDatasetAction } from "@agent-native/core/provider-api/actions/staged-datasets";
+
+import { DISPATCH_APP_ID } from "../server/lib/provider-api.js";
+
+export default createDeleteStagedDatasetAction({
+  appId: DISPATCH_APP_ID,
+  description:
+    "Delete a staged dataset by id, freeing its scratch storage. Use after analysis is complete or before re-staging under the same name. Only the owner who staged the dataset can delete it.",
+  http: false,
+});

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

@@ -0,0 +1,13 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { deleteSecret } from "../server/lib/vault-store.js";
+
+export default defineAction({
+  description:
+    "Delete a secret from the workspace vault. Also revokes all active grants for this secret. Admin only.",
+  schema: z.object({
+    id: z.string().describe("Secret ID to delete"),
+  }),
+  run: async (args) => deleteSecret(args.id),
+});

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

@@ -0,0 +1,13 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { deleteWorkspaceResource } from "../server/lib/workspace-resources-store.js";
+
+export default defineAction({
+  description:
+    "Delete a workspace resource and revoke all its grants. When Dispatch approval policy is enabled, deleting an All-app resource queues an approval request before taking effect.",
+  schema: z.object({
+    id: z.string().describe("Resource ID to delete"),
+  }),
+  run: async (args) => deleteWorkspaceResource(args.id),
+});

package/src/actions/deny-vault-request.ts

@@ -0,0 +1,13 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { denyRequest, requireVaultCtx } from "../server/lib/vault-store.js";
+
+export default defineAction({
+  description: "Deny a pending vault secret request. Admin only.",
+  schema: z.object({
+    id: z.string().describe("Request ID to deny"),
+    reason: z.string().optional().describe("Reason for denial"),
+  }),
+  run: async (args) => denyRequest(args.id, args.reason, requireVaultCtx()),
+});

package/src/actions/ensure-dream-job.ts

@@ -0,0 +1,77 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { ensureDreamJob } from "../server/lib/dreams-store.js";
+
+export default defineAction({
+  description:
+    "Create or update the personal recurring Dispatch dream job resource at jobs/dispatch-dream.md.",
+  schema: z.object({
+    schedule: z
+      .string()
+      .optional()
+      .describe(
+        'Optional five-field cron schedule. Defaults to weekly: "0 9 * * 1".',
+      ),
+    sourceId: z
+      .string()
+      .default("all")
+      .describe("Thread debug source id for the recurring dream pass."),
+    sourceIds: z
+      .array(z.string().min(1))
+      .optional()
+      .describe("Optional explicit source ids for recurring dream passes."),
+    allSources: z.coerce
+      .boolean()
+      .default(true)
+      .describe("Scan every connected source for recurring dream passes."),
+    query: z
+      .string()
+      .optional()
+      .describe("Optional search term to focus recurring dream passes."),
+    limit: z.coerce.number().int().min(1).max(50).default(8),
+    sourceTimeoutMs: z.coerce
+      .number()
+      .int()
+      .min(1000)
+      .max(60000)
+      .default(30000)
+      .describe("Per-source timeout in milliseconds."),
+    sourceConcurrency: z.coerce
+      .number()
+      .int()
+      .min(1)
+      .max(8)
+      .default(2)
+      .describe("How many sources to scan at once."),
+    sourceStartStaggerMs: z.coerce
+      .number()
+      .int()
+      .min(0)
+      .max(5000)
+      .default(250)
+      .describe("Delay between source starts within each 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."),
+    minCandidateCount: z.coerce
+      .number()
+      .int()
+      .min(0)
+      .max(50)
+      .default(1)
+      .describe("Skip recurring report creation below this candidate count."),
+  }),
+  run: async (input) => ensureDreamJob(input),
+});

package/src/actions/get-agent-thread-debug.ts

@@ -0,0 +1,41 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { getAgentThreadDebug } from "../server/lib/thread-debug-store.js";
+
+export default defineAction({
+  description:
+    "Get a full read-only debug snapshot by chat thread ID or copied request/run ID, including persisted messages, raw thread_data, run events, traces, feedback, evals, and checkpoints when present.",
+  schema: z
+    .object({
+      sourceId: z
+        .string()
+        .default("current")
+        .describe("Thread debug source id from list-agent-thread-sources."),
+      threadId: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Agent chat thread ID to inspect."),
+      runId: z
+        .string()
+        .min(1)
+        .optional()
+        .describe(
+          "Copied Agent Native request/run ID, usually shown as run-..., to resolve to its owning chat thread.",
+        ),
+      ownerEmail: z
+        .string()
+        .optional()
+        .describe("Optional owner email scope for admin cross-user lookups."),
+      maxRuns: z.coerce.number().int().min(1).max(50).default(20),
+      maxEvents: z.coerce.number().int().min(1).max(2000).default(600),
+      maxTraceSpans: z.coerce.number().int().min(1).max(2000).default(500),
+    })
+    .refine((input) => Boolean(input.threadId || input.runId), {
+      message: "Provide either threadId or runId.",
+    }),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async (input) => getAgentThreadDebug(input),
+});

package/src/actions/get-app-creation-settings.ts

@@ -0,0 +1,12 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { getAppCreationSettings } from "../server/lib/app-creation-store.js";
+
+export default defineAction({
+  description:
+    "Get Dispatch settings for creating new workspace apps, including the default Builder project.",
+  schema: z.object({}),
+  http: { method: "GET" },
+  run: async () => getAppCreationSettings(),
+});

package/src/actions/get-dispatch-settings.ts

@@ -0,0 +1,11 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { getApprovalPolicy } from "../server/lib/dispatch-store.js";
+
+export default defineAction({
+  description: "Get dispatch approval settings for the current organization.",
+  schema: z.object({}),
+  http: { method: "GET" },
+  run: async () => getApprovalPolicy(),
+});

package/src/actions/get-dream-settings.ts

@@ -0,0 +1,13 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { getDreamSettings } from "../server/lib/dreams-store.js";
+
+export default defineAction({
+  description:
+    "Read recurring Dispatch dream settings, including schedule, source scope, timeout, and minimum candidate threshold.",
+  schema: z.object({}),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async () => getDreamSettings(),
+});

package/src/actions/get-dream.ts

@@ -0,0 +1,15 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { getDream } from "../server/lib/dreams-store.js";
+
+export default defineAction({
+  description:
+    "Get one Dispatch dream report and its evidence-backed proposals.",
+  schema: z.object({
+    id: z.string().min(1).describe("Dream id."),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async ({ id }) => getDream(id),
+});

package/src/actions/get-vault-access-settings.ts

@@ -0,0 +1,12 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { getVaultAccessSettings } from "../server/lib/vault-store.js";
+
+export default defineAction({
+  description:
+    "Get the Dispatch vault access mode. Defaults to all-apps, where every workspace app can use every vault key.",
+  schema: z.object({}),
+  http: { method: "GET" },
+  run: async () => getVaultAccessSettings(),
+});

package/src/actions/get-workspace-info.ts

@@ -0,0 +1,12 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { getWorkspaceInfo } from "../server/lib/app-creation-store.js";
+
+export default defineAction({
+  description:
+    "Get the current workspace's identity (name and app count) from the workspace root package.json. Surfaced in the Dispatch UI so users can see which workspace their apps belong to.",
+  schema: z.object({}),
+  http: { method: "GET" },
+  run: async () => getWorkspaceInfo(),
+});

package/src/actions/get-workspace-resource-effective-context.ts

@@ -0,0 +1,35 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { getWorkspaceResourceEffectiveContext } from "../server/lib/workspace-resources-store.js";
+
+export default defineAction({
+  description:
+    "Preview how a Dispatch workspace resource resolves for an app/user at runtime: workspace default, organization/app override, and personal override, plus whether the resource is all-app or selected-only.",
+  schema: z.object({
+    resourceId: z
+      .string()
+      .optional()
+      .describe("Workspace resource id to inspect."),
+    path: z
+      .string()
+      .optional()
+      .describe(
+        "Resource path to inspect, such as context/brand.md. Optional when resourceId is provided.",
+      ),
+    appId: z
+      .string()
+      .optional()
+      .describe(
+        "Workspace app id to preview. All-app resources are inherited by every app; selected-only resources require a grant.",
+      ),
+    userEmail: z
+      .string()
+      .optional()
+      .describe(
+        "User email for personal overrides. Defaults to the current Dispatch user.",
+      ),
+  }),
+  http: { method: "GET" },
+  run: async (args) => getWorkspaceResourceEffectiveContext(args),
+});

package/src/actions/grant-vault-secrets-to-app.ts

@@ -0,0 +1,21 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { grantSecretsToApp } from "../server/lib/vault-store.js";
+
+export default defineAction({
+  description:
+    "Grant multiple Dispatch vault secrets to a workspace app in manual vault access mode. Admin only. Existing active grants are skipped.",
+  http: { method: "POST" },
+  schema: z.object({
+    appId: z
+      .string()
+      .regex(/^[a-z][a-z0-9-]{0,63}$/)
+      .describe("Workspace app id/path, e.g. customer-health"),
+    secretIds: z
+      .array(z.string())
+      .max(100)
+      .describe("Vault secret IDs to grant to the app"),
+  }),
+  run: async (args) => grantSecretsToApp(args.secretIds, args.appId),
+});

package/src/actions/grant-workspace-resources-to-app.ts

@@ -0,0 +1,17 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { grantWorkspaceResourcesToApp } from "../server/lib/workspace-resources-store.js";
+
+export default defineAction({
+  description:
+    "Grant several selected workspace resources, knowledge packs, or MCP servers to an app, skipping existing active grants.",
+  schema: z.object({
+    appId: z.string().describe("App ID receiving the resources"),
+    resourceIds: z
+      .array(z.string())
+      .max(100)
+      .describe("Workspace resource IDs to grant"),
+  }),
+  run: async (args) => grantWorkspaceResourcesToApp(args),
+});