@jami-studio/dispatch 0.13.14

package/src/actions/remove-pending-workspace-app.ts

@@ -0,0 +1,17 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { removePendingWorkspaceApp } from "../server/lib/app-creation-store.js";
+
+export default defineAction({
+  description:
+    "Remove a pending Builder app entry from the Apps list. Use when the user no longer wants to track a Builder branch in Dispatch (e.g. they abandoned the build). The Builder branch itself is not affected.",
+  schema: z.object({
+    appId: z
+      .string()
+      .min(1)
+      .max(64)
+      .describe("Workspace app id of the pending entry to remove"),
+  }),
+  run: async (input) => removePendingWorkspaceApp({ appId: input.appId }),
+});

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

@@ -0,0 +1,17 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { createRequest } from "../server/lib/vault-store.js";
+
+export default defineAction({
+  description:
+    "Request access to a credential for an app. Non-admins use this to ask workspace admins to provision a secret.",
+  schema: z.object({
+    credentialKey: z
+      .string()
+      .describe("Environment variable name needed, e.g. GOOGLE_CLIENT_ID"),
+    appId: z.string().describe("App ID that needs the credential"),
+    reason: z.string().optional().describe("Why this credential is needed"),
+  }),
+  run: async (args) => createRequest(args),
+});

package/src/actions/restore-starter-workspace-resources.ts

@@ -0,0 +1,18 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { restoreStarterWorkspaceResources } from "../server/lib/workspace-resources-store.js";
+
+export default defineAction({
+  description:
+    "Restore missing starter global workspace resources such as company, brand, messaging, guardrails, and company voice. Existing resources are left unchanged.",
+  schema: z.object({
+    paths: z
+      .array(z.string())
+      .optional()
+      .describe(
+        "Optional starter resource paths to restore. Omit to restore every missing starter resource.",
+      ),
+  }),
+  run: async (args) => restoreStarterWorkspaceResources(args),
+});

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

@@ -0,0 +1,12 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { revokeGrant } from "../server/lib/vault-store.js";
+
+export default defineAction({
+  description: "Revoke an app's access to a vault secret. Admin only.",
+  schema: z.object({
+    grantId: z.string().describe("Grant ID to revoke"),
+  }),
+  run: async (args) => revokeGrant(args.grantId),
+});

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

@@ -0,0 +1,16 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import {
+  requireWorkspaceResourceCtx,
+  revokeResourceGrant,
+} from "../server/lib/workspace-resources-store.js";
+
+export default defineAction({
+  description: "Revoke an app's access to a workspace resource. Admin only.",
+  schema: z.object({
+    grantId: z.string().describe("Grant ID to revoke"),
+  }),
+  run: async (args) =>
+    revokeResourceGrant(args.grantId, requireWorkspaceResourceCtx()),
+});

package/src/actions/scaffold-workspace-app.spec.ts

@@ -0,0 +1,33 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  scaffoldWorkspaceAppFromTemplate: vi.fn(),
+}));
+
+vi.mock("../server/lib/app-creation-store.js", () => ({
+  scaffoldWorkspaceAppFromTemplate: mocks.scaffoldWorkspaceAppFromTemplate,
+}));
+
+import action from "./scaffold-workspace-app.js";
+
+describe("scaffold-workspace-app action", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("surfaces scaffold failures as user-facing action errors", async () => {
+    mocks.scaffoldWorkspaceAppFromTemplate.mockRejectedValueOnce(
+      new Error(
+        "Scaffolding from Dispatch is only available in local development.",
+      ),
+    );
+
+    await expect(
+      action.run({ template: "brain", appId: null }),
+    ).rejects.toMatchObject({
+      message:
+        "Scaffolding from Dispatch is only available in local development.",
+      statusCode: 400,
+    });
+  });
+});

package/src/actions/scaffold-workspace-app.ts

@@ -0,0 +1,50 @@
+import { defineAction } from "@agent-native/core";
+import { getWorkspaceAppIdValidationError } from "@agent-native/core/shared";
+import { z } from "zod";
+
+import { scaffoldWorkspaceAppFromTemplate } from "../server/lib/app-creation-store.js";
+
+function userFacingActionError(err: unknown): Error & { statusCode: number } {
+  const message =
+    err instanceof Error && err.message ? err.message : String(err);
+  const error = new Error(
+    message || "Could not scaffold workspace app.",
+  ) as Error & { statusCode: number };
+  error.statusCode = 400;
+  return error;
+}
+
+export default defineAction({
+  description:
+    "Scaffold a first-party template (mail, calendar, slides, etc.) into apps/<id>/ in the current workspace. Local-dev only — runs `agent-native add-app` as a subprocess. The workspace gateway picks the new app up automatically and serves it at /<id>. For natural-language app creation, call start-workspace-app-creation instead.",
+  schema: z.object({
+    template: z
+      .string()
+      .min(1)
+      .describe(
+        "Template name (mail, calendar, slides, content, clips, analytics, forms, design, assets)",
+      ),
+    appId: z
+      .string()
+      .max(64)
+      .optional()
+      .nullable()
+      .refine((appId) => !appId || !getWorkspaceAppIdValidationError(appId), {
+        message:
+          "Use a non-reserved app id with lowercase letters, numbers, and hyphens.",
+      })
+      .describe(
+        "Optional override for the apps/<id>/ directory name; defaults to the template name",
+      ),
+  }),
+  run: async (input) => {
+    try {
+      return await scaffoldWorkspaceAppFromTemplate({
+        template: input.template,
+        appId: input.appId ?? null,
+      });
+    } catch (err) {
+      throw userFacingActionError(err);
+    }
+  },
+});

package/src/actions/search-agent-threads.ts

@@ -0,0 +1,31 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { searchAgentThreads } from "../server/lib/thread-debug-store.js";
+
+export default defineAction({
+  description:
+    "Search agent chat threads by title, preview, or full persisted thread content. Non-admins are limited to their own current Dispatch DB threads.",
+  schema: z.object({
+    sourceId: z
+      .string()
+      .default("current")
+      .describe("Thread debug source id from list-agent-thread-sources."),
+    query: z
+      .string()
+      .optional()
+      .describe(
+        "Full-text search term matched against title, preview, and thread data.",
+      ),
+    ownerEmail: z
+      .string()
+      .optional()
+      .describe(
+        "Optional owner email filter. Admins may pass '*' or omit to search the admin-visible scope.",
+      ),
+    limit: z.coerce.number().int().min(1).max(100).default(25),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async (input) => searchAgentThreads(input),
+});

package/src/actions/send-code-agent-remote-command.ts

@@ -0,0 +1,60 @@
+import { defineAction } from "@agent-native/core";
+import { getRequestUserEmail } from "@agent-native/core/server";
+import { z } from "zod";
+
+import {
+  enqueueRemoteCodeCommand,
+  type RemoteCodeCommandEnvelope,
+} from "../server/lib/dispatch-remote-commands.js";
+
+const commandSchema = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("create"), prompt: z.string().min(1) }),
+  z.object({ type: z.literal("list") }),
+  z.object({ type: z.literal("status"), runRef: z.string().optional() }),
+  z.object({
+    type: z.literal("continue"),
+    runRef: z.string().min(1),
+    text: z.string().min(1),
+  }),
+  z.object({ type: z.literal("approve"), approvalId: z.string().min(1) }),
+  z.object({ type: z.literal("deny"), approvalId: z.string().min(1) }),
+  z.object({ type: z.literal("stop"), runRef: z.string().min(1) }),
+]);
+
+export default defineAction({
+  description:
+    "Route a command to the remote Agent-Native Code host through the integration relay.",
+  schema: z.object({
+    command: commandSchema,
+    source: z
+      .object({
+        platform: z.string().default("dispatch"),
+        externalThreadId: z.string().default("dispatch"),
+        senderId: z.string().optional(),
+        senderName: z.string().optional(),
+        messageId: z.string().optional(),
+        timestamp: z.number().optional(),
+      })
+      .optional(),
+  }),
+  run: async ({ command, source }) => {
+    const ownerEmail = getRequestUserEmail();
+    if (!ownerEmail) throw new Error("no authenticated user");
+
+    const envelope: RemoteCodeCommandEnvelope = {
+      kind: "code-agent",
+      ownerEmail,
+      command,
+      source: {
+        platform: source?.platform || "dispatch",
+        externalThreadId: source?.externalThreadId || "dispatch",
+        senderId: source?.senderId,
+        senderName: source?.senderName,
+        messageId: source?.messageId,
+        timestamp: source?.timestamp ?? Date.now(),
+      },
+    };
+
+    return enqueueRemoteCodeCommand(envelope);
+  },
+});

package/src/actions/send-platform-message.ts

@@ -0,0 +1,101 @@
+import { defineAction } from "@agent-native/core";
+import {
+  slackAdapter,
+  telegramAdapter,
+  emailAdapter,
+  isEmailConfigured,
+  resolveSecret,
+} from "@agent-native/core/server";
+import { z } from "zod";
+
+import {
+  getDestinationById,
+  recordAudit,
+} from "../server/lib/dispatch-store.js";
+
+function getAdapter(platform: "slack" | "telegram" | "email") {
+  if (platform === "email") return emailAdapter();
+  return platform === "slack" ? slackAdapter() : telegramAdapter();
+}
+
+async function assertOutboundConfigured(
+  platform: "slack" | "telegram" | "email",
+) {
+  if (platform === "slack" && !(await resolveSecret("SLACK_BOT_TOKEN"))) {
+    throw new Error("Slack outbound messaging is not configured");
+  }
+  if (platform === "telegram" && !(await resolveSecret("TELEGRAM_BOT_TOKEN"))) {
+    throw new Error("Telegram outbound messaging is not configured");
+  }
+  if (platform === "email") {
+    if (
+      !(await resolveSecret("EMAIL_AGENT_ADDRESS")) ||
+      !(await isEmailConfigured())
+    ) {
+      throw new Error("Email outbound messaging is not configured");
+    }
+  }
+}
+
+export default defineAction({
+  description:
+    "Send a proactive message to a saved Slack, Telegram, or email destination.",
+  schema: z.object({
+    platform: z.enum(["slack", "telegram", "email"]).optional(),
+    destinationId: z.string().optional().describe("Saved destination id"),
+    destination: z.string().optional().describe("Raw platform destination id"),
+    threadRef: z.string().optional().describe("Optional thread reference"),
+    text: z.string().describe("Message to send"),
+  }),
+  run: async ({ platform, destinationId, destination, threadRef, text }) => {
+    const saved = destinationId
+      ? await getDestinationById(destinationId)
+      : null;
+    const resolvedPlatform = (saved?.platform || platform) as
+      | "slack"
+      | "telegram"
+      | "email"
+      | undefined;
+    const resolvedDestination = saved?.destination || destination;
+    const resolvedThreadRef = saved?.threadRef || threadRef || null;
+
+    if (!resolvedPlatform || !resolvedDestination) {
+      throw new Error("A platform and destination are required");
+    }
+
+    await assertOutboundConfigured(resolvedPlatform);
+
+    const adapter = getAdapter(resolvedPlatform);
+    if (!adapter.sendMessageToTarget) {
+      throw new Error(
+        `Platform ${resolvedPlatform} does not support proactive outbound messaging`,
+      );
+    }
+
+    await adapter.sendMessageToTarget(adapter.formatAgentResponse(text), {
+      destination: resolvedDestination,
+      threadRef: resolvedThreadRef,
+      label: saved?.name || undefined,
+    });
+
+    await recordAudit({
+      action: "message.sent",
+      targetType: "destination",
+      targetId: destinationId || resolvedDestination,
+      summary: `Sent proactive ${resolvedPlatform} message${saved?.name ? ` to ${saved.name}` : ""}`,
+      metadata: {
+        platform: resolvedPlatform,
+        destination: resolvedDestination,
+        threadRef: resolvedThreadRef,
+        text,
+      },
+    });
+
+    return {
+      ok: true,
+      platform: resolvedPlatform,
+      destination: resolvedDestination,
+      threadRef: resolvedThreadRef,
+    };
+  },
+});

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

@@ -0,0 +1,20 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { setAppCreationSettings } from "../server/lib/app-creation-store.js";
+
+export default defineAction({
+  description:
+    "Set Dispatch settings for creating new workspace apps. Does not write env vars or files.",
+  schema: z.object({
+    builderProjectId: z
+      .string()
+      .trim()
+      .min(1)
+      .max(128)
+      .optional()
+      .nullable()
+      .describe("Default Builder project ID to use for app creation branches"),
+  }),
+  run: async (args) => setAppCreationSettings(args),
+});

package/src/actions/set-dispatch-approval-policy.ts

@@ -0,0 +1,25 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import {
+  getApprovalPolicy,
+  setApprovalPolicy,
+} from "../server/lib/dispatch-store.js";
+
+export default defineAction({
+  description: "Enable or disable dispatch approval flow for durable changes.",
+  schema: z.object({
+    enabled: z.boolean(),
+    approverEmails: z.array(z.string().email()).default([]),
+  }),
+  run: async ({ enabled, approverEmails }) => {
+    const current = await getApprovalPolicy();
+    if (
+      current.enabled === enabled &&
+      JSON.stringify(current.approverEmails) === JSON.stringify(approverEmails)
+    ) {
+      return current;
+    }
+    return setApprovalPolicy({ enabled, approverEmails });
+  },
+});

package/src/actions/set-dream-settings.spec.ts

@@ -0,0 +1,81 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  setDreamSettings: vi.fn(),
+}));
+
+vi.mock("../server/lib/dreams-store.js", () => ({
+  setDreamSettings: mocks.setDreamSettings,
+}));
+
+import action from "./set-dream-settings.js";
+
+describe("set-dream-settings action", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mocks.setDreamSettings.mockImplementation(async (input) => ({
+      enabled: false,
+      schedule: "0 9 * * 1",
+      sourceId: "all",
+      sourceIds: [],
+      allSources: true,
+      query: null,
+      limit: 8,
+      sourceTimeoutMs: 30000,
+      sourceConcurrency: 2,
+      sourceStartStaggerMs: 250,
+      threadConcurrency: 3,
+      threadTimeoutMs: 8000,
+      minCandidateCount: 1,
+      ...input,
+    }));
+  });
+
+  it("coerces numeric fields and preserves explicit clears", async () => {
+    await action.run({
+      enabled: true,
+      schedule: "0 8 * * 2",
+      sourceId: "current",
+      sourceIds: [],
+      allSources: false,
+      query: "",
+      limit: "50",
+      sourceTimeoutMs: "60000",
+      sourceConcurrency: "8",
+      sourceStartStaggerMs: "5000",
+      threadConcurrency: "10",
+      threadTimeoutMs: "30000",
+      minCandidateCount: "0",
+    } as any);
+
+    expect(mocks.setDreamSettings).toHaveBeenCalledWith({
+      enabled: true,
+      schedule: "0 8 * * 2",
+      sourceId: "current",
+      sourceIds: [],
+      allSources: false,
+      query: "",
+      limit: 50,
+      sourceTimeoutMs: 60000,
+      sourceConcurrency: 8,
+      sourceStartStaggerMs: 5000,
+      threadConcurrency: 10,
+      threadTimeoutMs: 30000,
+      minCandidateCount: 0,
+    });
+  });
+
+  it("rejects out-of-range numeric settings before writing", async () => {
+    await expect(action.run({ limit: "0" } as any)).rejects.toThrow(
+      /Invalid action parameters/,
+    );
+    await expect(
+      action.run({ sourceTimeoutMs: "60001" } as any),
+    ).rejects.toThrow(/Invalid action parameters/);
+    await expect(
+      action.run({ threadTimeoutMs: "30001" } as any),
+    ).rejects.toThrow(/Invalid action parameters/);
+
+    expect(mocks.setDreamSettings).not.toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,45 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { setDreamSettings } from "../server/lib/dreams-store.js";
+
+export default defineAction({
+  description:
+    "Update recurring Dispatch dream settings without immediately running or applying a dream pass.",
+  schema: z.object({
+    enabled: z
+      .boolean()
+      .optional()
+      .describe("Whether recurring dreams are on."),
+    schedule: z
+      .string()
+      .optional()
+      .describe('Five-field cron schedule, for example "0 9 * * 1".'),
+    sourceId: z
+      .string()
+      .optional()
+      .describe(
+        "Thread debug source id. Use 'all' for every connected source.",
+      ),
+    sourceIds: z
+      .array(z.string().min(1))
+      .optional()
+      .describe("Optional explicit source ids to scan together."),
+    allSources: z.coerce
+      .boolean()
+      .optional()
+      .describe("Scan every connected thread-debug source."),
+    query: z
+      .string()
+      .optional()
+      .describe("Optional search term for recurring dream passes."),
+    limit: z.coerce.number().int().min(1).max(50).optional(),
+    sourceTimeoutMs: z.coerce.number().int().min(1000).max(60000).optional(),
+    sourceConcurrency: z.coerce.number().int().min(1).max(8).optional(),
+    sourceStartStaggerMs: z.coerce.number().int().min(0).max(5000).optional(),
+    threadConcurrency: z.coerce.number().int().min(1).max(10).optional(),
+    threadTimeoutMs: z.coerce.number().int().min(1000).max(30000).optional(),
+    minCandidateCount: z.coerce.number().int().min(0).max(50).optional(),
+  }),
+  run: async (input) => setDreamSettings(input),
+});

package/src/actions/set-mcp-app-access.ts

@@ -0,0 +1,60 @@
+import { defineAction } from "@agent-native/core";
+import { discoverAgents } from "@agent-native/core/server/agent-discovery";
+import { z } from "zod";
+
+import { recordAudit } from "../server/lib/dispatch-store.js";
+import { setDispatchMcpAppAccessSettings } from "../server/lib/mcp-access-store.js";
+import listMcpAppAccess from "./list-mcp-app-access.js";
+
+const modeSchema = z.enum(["all-apps", "selected-apps"]);
+
+export default defineAction({
+  description:
+    "Set which apps are available through Dispatch's unified MCP gateway.",
+  schema: z.object({
+    mode: modeSchema.describe(
+      "Use all-apps to expose every discovered app, or selected-apps to allow only selectedAppIds.",
+    ),
+    selectedAppIds: z
+      .array(z.string())
+      .default([])
+      .describe("App IDs to expose when mode is selected-apps."),
+  }),
+  run: async (args) => {
+    const agents = await discoverAgents("dispatch");
+    const knownIds = new Set(agents.map((agent) => agent.id));
+    const selectedAppIds = Array.from(
+      new Set(
+        args.selectedAppIds
+          .map((id) => id.trim().toLowerCase())
+          .filter(Boolean),
+      ),
+    );
+    const unknown = selectedAppIds.filter((id) => !knownIds.has(id));
+    if (unknown.length > 0) {
+      throw new Error(
+        `Unknown app(s): ${unknown.join(", ")}. Use list-mcp-app-access to see available app IDs.`,
+      );
+    }
+    if (args.mode === "selected-apps" && selectedAppIds.length === 0) {
+      throw new Error("selected-apps mode requires at least one app ID.");
+    }
+
+    await setDispatchMcpAppAccessSettings({
+      mode: args.mode,
+      selectedAppIds,
+    });
+    await recordAudit({
+      action: "mcp-access.updated",
+      targetType: "dispatch-mcp-access",
+      targetId: "unified-mcp",
+      summary:
+        args.mode === "all-apps"
+          ? "Allowed Dispatch MCP access to all apps"
+          : `Allowed Dispatch MCP access to ${selectedAppIds.length} selected app(s)`,
+      metadata: { mode: args.mode, selectedAppIds },
+    }).catch(() => {});
+
+    return listMcpAppAccess.run({});
+  },
+});

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

@@ -0,0 +1,17 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { setVaultAccessSettings } from "../server/lib/vault-store.js";
+
+export default defineAction({
+  description:
+    "Set the Dispatch vault access mode. Use all-apps for the default workspace-wide mode or manual to require explicit per-app grants.",
+  schema: z.object({
+    mode: z
+      .enum(["all-apps", "manual"])
+      .describe(
+        "all-apps shares every vault key with every app; manual requires grants",
+      ),
+  }),
+  run: async (args) => setVaultAccessSettings(args),
+});

package/src/actions/start-workspace-app-creation.ts

@@ -0,0 +1,49 @@
+import { defineAction } from "@agent-native/core";
+import { getWorkspaceAppIdValidationError } from "@agent-native/core/shared";
+import { z } from "zod";
+
+import { startWorkspaceAppCreation } from "../server/lib/app-creation-store.js";
+
+export default defineAction({
+  description:
+    'Start creating a new workspace app from Dispatch when the request truly needs its own app. Callers should include a concise generated description by default; Dispatch generates one from the prompt when omitted. In local dev this returns a code-agent prompt; in production it creates a Builder branch only when a Builder branch project is configured. If the result mode is "coming-soon", the work still requires a code change but no Builder Cloud Agent can run here; tell the user to edit locally or use Builder.io to edit this code in the cloud and continue customizing the app any way they like, and do not send them to Builder org/beta settings. The result must be a separate workspace app under apps/<app-id>, not a new route or file in apps/chat. If chat is used as the source template, the finished app must be branded as the requested app and must not leave visible "Chat", "Starter", "Blank app", or "New app" UI behind. If the request needs Mail, Calendar, Analytics, Brain, Assets, or another first-party app, use the existing hosted/connected app via links or A2A; do not clone, wrap, or nest those templates inside the new app unless the user explicitly asks for a customized copy.',
+  schema: z.object({
+    prompt: z.string().min(1).describe("The user's app creation request"),
+    appId: z
+      .string()
+      .max(64)
+      .refine((appId) => !getWorkspaceAppIdValidationError(appId), {
+        message:
+          "Use a non-reserved app id with lowercase letters, numbers, and hyphens.",
+      })
+      .optional()
+      .nullable()
+      .describe("Desired workspace app id/path"),
+    template: z
+      .string()
+      .optional()
+      .nullable()
+      .describe("Template to start from"),
+    description: z
+      .string()
+      .max(500)
+      .optional()
+      .nullable()
+      .describe(
+        "Concise AI-generated description of the app based on the user's prompt. Dispatch saves this while the app is being created.",
+      ),
+    secretIds: z
+      .array(z.string())
+      .max(100)
+      .optional()
+      .describe("Dispatch vault secret IDs to grant to the app"),
+    resourceIds: z
+      .array(z.string())
+      .max(100)
+      .optional()
+      .describe(
+        "Dispatch workspace resource IDs or knowledge packs to grant to the app",
+      ),
+  }),
+  run: async (args) => startWorkspaceAppCreation(args),
+});