@agent-native/dispatch 0.15.20 → 0.15.21

package/src/server/lib/app-creation-store.spec.ts

@@ -5,6 +5,8 @@ import {
   generateWorkspaceAppDescription,
   listAvailableWorkspaceTemplates,
   listWorkspaceApps,
+  setAppCreationSettings,
+  startWorkspaceAppCreation,
   updateWorkspaceAppMetadata,
 } from "./app-creation-store.js";
 
@@ -28,6 +30,35 @@ const mocks = vi.hoisted(() => {
         rows: state.orgRole ? [{ role: state.orgRole }] : [],
       })),
     })),
+    resolveBuilderCredentialsDetailed: vi.fn(async () => ({
+      privateKey: null as string | null,
+      publicKey: null as string | null,
+      userId: null as string | null,
+      orgName: null,
+      orgKind: null,
+      subscription: null,
+      subscriptionLevel: null,
+      subscriptionName: null,
+      isEnterprise: null,
+      isFreeAccount: null,
+      source: null,
+      lookupFailed: false,
+    })),
+    runBuilderAgent: vi.fn(),
+    resolveBuilderBranchProjectId: vi.fn(async () => ""),
+    getBuilderBranchProjectId: vi.fn(() => ""),
+    writeAppSecret: vi.fn(async () => "secret-id"),
+    deleteAppSecret: vi.fn(async () => true),
+  };
+});
+
+vi.mock("@agent-native/core/secrets", async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import("@agent-native/core/secrets")>();
+  return {
+    ...actual,
+    writeAppSecret: (...args: any[]) => mocks.writeAppSecret(...args),
+    deleteAppSecret: (...args: any[]) => mocks.deleteAppSecret(...args),
   };
 });
 
@@ -44,6 +75,21 @@ vi.mock("@agent-native/core/settings", () => ({
   putSetting: (...args: any[]) => mocks.putSetting(...args),
 }));
 
+vi.mock("@agent-native/core/server", async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import("@agent-native/core/server")>();
+  return {
+    ...actual,
+    resolveBuilderCredentialsDetailed: (...args: any[]) =>
+      mocks.resolveBuilderCredentialsDetailed(...args),
+    runBuilderAgent: (...args: any[]) => mocks.runBuilderAgent(...args),
+    resolveBuilderBranchProjectId: (...args: any[]) =>
+      mocks.resolveBuilderBranchProjectId(...args),
+    getBuilderBranchProjectId: (...args: any[]) =>
+      mocks.getBuilderBranchProjectId(...args),
+  };
+});
+
 vi.mock("./dispatch-store.js", async (importOriginal) => {
   const actual = await importOriginal<typeof import("./dispatch-store.js")>();
   return {
@@ -58,6 +104,22 @@ afterEach(() => {
   vi.clearAllMocks();
   mocks.settings.clear();
   mocks.state.orgRole = "admin";
+  mocks.resolveBuilderCredentialsDetailed.mockResolvedValue({
+    privateKey: null,
+    publicKey: null,
+    userId: null,
+    orgName: null,
+    orgKind: null,
+    subscription: null,
+    subscriptionLevel: null,
+    subscriptionName: null,
+    isEnterprise: null,
+    isFreeAccount: null,
+    source: null,
+    lookupFailed: false,
+  });
+  mocks.resolveBuilderBranchProjectId.mockResolvedValue("");
+  mocks.getBuilderBranchProjectId.mockReturnValue("");
   globalThis.fetch = originalFetch;
 });
 
@@ -377,3 +439,193 @@ describe("listWorkspaceApps", () => {
     expect(templates).toEqual([]);
   });
 });
+
+describe("startWorkspaceAppCreation", () => {
+  const leakedProjectId = "940ebc5a83164aa6a37dde445e494f3a";
+
+  function stubHostedRuntime() {
+    vi.stubEnv("NODE_ENV", "production");
+  }
+
+  function stubBuilderProjectConfigured() {
+    vi.stubEnv("DISPATCH_BUILDER_PROJECT_ID", leakedProjectId);
+  }
+
+  function credentials(overrides: Record<string, unknown> = {}) {
+    return {
+      privateKey: null,
+      publicKey: null,
+      userId: null,
+      orgName: null,
+      orgKind: null,
+      subscription: null,
+      subscriptionLevel: null,
+      subscriptionName: null,
+      isEnterprise: null,
+      isFreeAccount: null,
+      source: null,
+      lookupFailed: false,
+      ...overrides,
+    };
+  }
+
+  function create(appId = "onboarding") {
+    return runWithRequestContext({ userEmail: "dev@example.test" }, () =>
+      startWorkspaceAppCreation({ prompt: "Track onboarding tasks", appId }),
+    );
+  }
+
+  it("returns builder-not-connected without leaking the project id when no Builder credentials are configured", async () => {
+    stubHostedRuntime();
+    stubBuilderProjectConfigured();
+    mocks.resolveBuilderCredentialsDetailed.mockResolvedValue(credentials());
+
+    const result = (await create()) as any;
+
+    expect(result.mode).toBe("builder-unavailable");
+    expect(result.reason).toBe("builder-not-connected");
+    expect(result.message).not.toContain(leakedProjectId);
+    expect(mocks.runBuilderAgent).not.toHaveBeenCalled();
+  });
+
+  it("returns credential-store-unavailable when the credential lookup itself fails", async () => {
+    stubHostedRuntime();
+    stubBuilderProjectConfigured();
+    mocks.resolveBuilderCredentialsDetailed.mockResolvedValue(
+      credentials({ lookupFailed: true }),
+    );
+
+    const result = (await create()) as any;
+
+    expect(result.mode).toBe("builder-unavailable");
+    expect(result.reason).toBe("credential-store-unavailable");
+    expect(mocks.runBuilderAgent).not.toHaveBeenCalled();
+  });
+
+  it("returns builder-error with the raw failure in detail when runBuilderAgent throws", async () => {
+    stubHostedRuntime();
+    stubBuilderProjectConfigured();
+    mocks.resolveBuilderCredentialsDetailed.mockResolvedValue(
+      credentials({
+        privateKey: "priv",
+        publicKey: "pub",
+        userId: "builder-user-1",
+      }),
+    );
+    mocks.runBuilderAgent.mockRejectedValue(
+      new Error("Builder keys are not configured"),
+    );
+
+    const result = (await create()) as any;
+
+    expect(result.mode).toBe("builder-unavailable");
+    expect(result.reason).toBe("builder-error");
+    expect(result.detail).toBe("Builder keys are not configured");
+    expect(result.message).not.toContain(leakedProjectId);
+  });
+
+  it("starts the Builder branch and passes the resolved userId through", async () => {
+    stubHostedRuntime();
+    stubBuilderProjectConfigured();
+    mocks.resolveBuilderCredentialsDetailed.mockResolvedValue(
+      credentials({
+        privateKey: "priv",
+        publicKey: "pub",
+        userId: "builder-user-42",
+      }),
+    );
+    mocks.runBuilderAgent.mockResolvedValue({
+      branchName: "onboarding1",
+      url: "https://builder.io/app/projects/project-1/branch/onboarding1",
+      status: "processing",
+    });
+
+    const result = (await create()) as any;
+
+    expect(result.mode).toBe("builder");
+    expect(mocks.runBuilderAgent).toHaveBeenCalledWith(
+      expect.objectContaining({ userId: "builder-user-42" }),
+    );
+  });
+
+  it("returns coming-soon when no Builder project is configured", async () => {
+    stubHostedRuntime();
+
+    const result = (await create()) as any;
+
+    expect(result.mode).toBe("coming-soon");
+    expect(mocks.resolveBuilderCredentialsDetailed).not.toHaveBeenCalled();
+  });
+});
+
+describe("setAppCreationSettings", () => {
+  const projectId = "274d28fec94b48f2b2d68f2274d390eb";
+  const orgId = "builder_io";
+
+  function save(
+    builderProjectId: string | null,
+    ctx: { userEmail: string; orgId?: string } = {
+      userEmail: "dev@example.test",
+      orgId,
+    },
+  ) {
+    return runWithRequestContext(ctx, () =>
+      setAppCreationSettings({ builderProjectId }),
+    );
+  }
+
+  it("stores the project id as an org-scoped credential so member apps resolve it", async () => {
+    await save(projectId);
+
+    expect(mocks.writeAppSecret).toHaveBeenCalledWith(
+      expect.objectContaining({
+        key: "BUILDER_BRANCH_PROJECT_ID",
+        value: projectId,
+        scope: "org",
+        scopeId: orgId,
+      }),
+    );
+    expect(mocks.deleteAppSecret).not.toHaveBeenCalled();
+  });
+
+  it("scopes the credential to one organization rather than every tenant", async () => {
+    await save(projectId);
+
+    const [args] = mocks.writeAppSecret.mock.calls.at(-1) as [
+      { scope: string; scopeId: string },
+    ];
+    expect(args.scope).not.toBe("user");
+    expect(args.scopeId).toBe(orgId);
+  });
+
+  it("falls back to a solo workspace scope when there is no active org", async () => {
+    await save(projectId, { userEmail: "dev@example.test" });
+
+    expect(mocks.writeAppSecret).toHaveBeenCalledWith(
+      expect.objectContaining({
+        scope: "workspace",
+        scopeId: "solo:dev@example.test",
+      }),
+    );
+  });
+
+  it("removes the credential when the project id is cleared", async () => {
+    await save(null);
+
+    expect(mocks.deleteAppSecret).toHaveBeenCalledWith({
+      key: "BUILDER_BRANCH_PROJECT_ID",
+      scope: "org",
+      scopeId: orgId,
+    });
+    expect(mocks.writeAppSecret).not.toHaveBeenCalled();
+  });
+
+  it("does not save the setting when the credential write fails", async () => {
+    mocks.writeAppSecret.mockRejectedValueOnce(
+      new Error("credential store down"),
+    );
+
+    await expect(save(projectId)).rejects.toThrow("credential store down");
+    expect(mocks.putSetting).not.toHaveBeenCalled();
+  });
+});

package/src/server/lib/app-creation-store.ts

@@ -4,12 +4,17 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { getDbExec } from "@agent-native/core/db";
+import {
+  deleteAppSecret,
+  writeAppSecret,
+  type SecretScope,
+} from "@agent-native/core/secrets";
 import {
   getBuilderBranchProjectId,
   getRequestContext,
   isIntegrationCallerRequest,
   resolveBuilderBranchProjectId,
-  resolveBuilderCredentials,
+  resolveBuilderCredentialsDetailed,
   runBuilderAgent,
 } from "@agent-native/core/server";
 import { getSetting, putSetting } from "@agent-native/core/settings";
@@ -30,6 +35,9 @@ import {
 } from "./workspace-resources-store.js";
 
 const SETTINGS_KEY = "dispatch-app-creation-settings";
+const BUILDER_BRANCH_PROJECT_SECRET_KEY = "BUILDER_BRANCH_PROJECT_ID";
+const BUILDER_BRANCH_PROJECT_SECRET_DESCRIPTION =
+  "Builder project for cloud code-change branches (set in Dispatch)";
 const WORKSPACE_APP_METADATA_SETTINGS_KEY = "workspace-app-metadata";
 const WORKSPACE_APPS_ENV_KEY = "AGENT_NATIVE_WORKSPACE_APPS_JSON";
 const WORKSPACE_APPS_MANIFEST_FILE = "workspace-apps.json";
@@ -209,6 +217,16 @@ function scopedSettingsKey(): string {
   return `${SETTINGS_KEY}:user:${currentOwnerEmail()}`;
 }
 
+function builderProjectSecretTarget(): {
+  scope: Extract<SecretScope, "org" | "workspace">;
+  scopeId: string;
+} | null {
+  const orgId = currentOrgId();
+  if (orgId) return { scope: "org", scopeId: orgId };
+  const email = currentOwnerEmail();
+  return email ? { scope: "workspace", scopeId: `solo:${email}` } : null;
+}
+
 function workspaceAppMetadataSettingsKey(): string {
   const orgId = currentOrgId();
   if (orgId) return `${WORKSPACE_APP_METADATA_SETTINGS_KEY}:org:${orgId}`;
@@ -1500,6 +1518,29 @@ export async function setAppCreationSettings(input: {
   await assertCanManageAppCreationSettings();
   const builderProjectId = input.builderProjectId?.trim() || null;
   const raw = await readSettingsRecord();
+
+  // The credential store, not this settings row, is what
+  // `resolveBuilderBranchProjectId()` reads. Write it first: a saved setting
+  // whose secret never landed reports the project as configured while cloud
+  // code changes stay silently disabled.
+  const secretTarget = builderProjectSecretTarget();
+  if (secretTarget) {
+    const ref = {
+      key: BUILDER_BRANCH_PROJECT_SECRET_KEY,
+      scope: secretTarget.scope,
+      scopeId: secretTarget.scopeId,
+    };
+    if (builderProjectId) {
+      await writeAppSecret({
+        ...ref,
+        value: builderProjectId,
+        description: BUILDER_BRANCH_PROJECT_SECRET_DESCRIPTION,
+      });
+    } else {
+      await deleteAppSecret(ref);
+    }
+  }
+
   await putSetting(scopedSettingsKey(), { ...raw, builderProjectId });
   await recordAudit({
     action: "settings.updated",
@@ -1649,7 +1690,7 @@ function normalizeBuilderRunResult(result: unknown): {
 }
 
 async function remoteAppCreationAuthorization(): Promise<
-  { ok: true } | { ok: false; message: string }
+  { ok: true } | { ok: false; reason: "identity-not-linked"; message: string }
 > {
   const ownerEmail = currentOwnerEmail();
   const isIntegrationCaller = isIntegrationCallerRequest();
@@ -1658,6 +1699,7 @@ async function remoteAppCreationAuthorization(): Promise<
     if (await defaultOwnerAppCreationAllowed()) return { ok: true };
     return {
       ok: false,
+      reason: "identity-not-linked",
       message:
         "Messaging-triggered app creation is using the deployment default Dispatch owner. " +
         "Link the messaging identity to a Dispatch user with /link, start the app from Dispatch while signed in, or explicitly set ENABLE_BUILDER=true for this deployment.",
@@ -1670,6 +1712,7 @@ async function remoteAppCreationAuthorization(): Promise<
     : "Synthetic integration";
   return {
     ok: false,
+    reason: "identity-not-linked",
     message:
       `${source} app creation needs a trusted Dispatch owner before Builder can start a branch. ` +
       "Link the messaging identity to a Dispatch user with /link, start the app from Dispatch while signed in, or explicitly set ENABLE_BUILDER=true for this deployment.",
@@ -1788,6 +1831,65 @@ async function grantSelectedWorkspaceResources(input: {
   await grantWorkspaceResourcesToApp(input);
 }
 
+/**
+ * Discriminates why `startWorkspaceAppCreation` could not hand off to Builder.
+ * UIs and agents should branch on this instead of parsing `message` text.
+ */
+export type AppCreationUnavailableReason =
+  | "identity-not-linked"
+  | "builder-not-connected"
+  | "credential-store-unavailable"
+  | "builder-error";
+
+export interface AppCreationIdentityUnavailableResult {
+  mode: "builder-unavailable";
+  appId: string;
+  reason: "identity-not-linked";
+  message: string;
+}
+
+export interface AppCreationBuilderUnavailableResult {
+  mode: "builder-unavailable";
+  appId: string;
+  reason: Exclude<AppCreationUnavailableReason, "identity-not-linked">;
+  message: string;
+  /** Raw underlying error text for agents/operators debugging the deployment. */
+  detail?: string;
+  projectId: string;
+}
+
+export interface AppCreationLocalAgentResult {
+  mode: "local-agent";
+  appId: string;
+  prompt: string;
+  message: string;
+}
+
+export interface AppCreationComingSoonResult {
+  mode: "coming-soon";
+  appId: string;
+  message: string;
+}
+
+export interface AppCreationBuilderResult {
+  mode: "builder";
+  appId: string;
+  path: string;
+  projectId: string;
+  branchName: string;
+  url: string;
+  workspaceUrl: string | null;
+  status: string;
+  message: string;
+}
+
+export type StartWorkspaceAppCreationResult =
+  | AppCreationIdentityUnavailableResult
+  | AppCreationBuilderUnavailableResult
+  | AppCreationLocalAgentResult
+  | AppCreationComingSoonResult
+  | AppCreationBuilderResult;
+
 export async function startWorkspaceAppCreation(input: {
   prompt: string;
   appId?: string | null;
@@ -1795,7 +1897,7 @@ export async function startWorkspaceAppCreation(input: {
   template?: string | null;
   secretIds?: string[];
   resourceIds?: string[];
-}) {
+}): Promise<StartWorkspaceAppCreationResult> {
   const initial = buildWorkspaceAppPrompt({
     prompt: input.prompt,
     appId: input.appId,
@@ -1811,6 +1913,7 @@ export async function startWorkspaceAppCreation(input: {
       return {
         mode: "builder-unavailable",
         appId: initial.appId,
+        reason: authorization.reason,
         message: authorization.message,
       };
     }
@@ -1866,14 +1969,51 @@ export async function startWorkspaceAppCreation(input: {
     };
   }
 
+  let builderCreds: Awaited<
+    ReturnType<typeof resolveBuilderCredentialsDetailed>
+  >;
+  try {
+    builderCreds = await resolveBuilderCredentialsDetailed();
+  } catch {
+    return {
+      mode: "builder-unavailable",
+      appId: built.appId,
+      reason: "credential-store-unavailable",
+      projectId: settings.builderProjectId,
+      message:
+        "Could not read your Builder connection just now. Try creating the app again in a moment.",
+    };
+  }
+
+  if (builderCreds.lookupFailed) {
+    return {
+      mode: "builder-unavailable",
+      appId: built.appId,
+      reason: "credential-store-unavailable",
+      projectId: settings.builderProjectId,
+      message:
+        "Could not read your Builder connection just now. Try creating the app again in a moment.",
+    };
+  }
+
+  if (!builderCreds.privateKey || !builderCreds.publicKey) {
+    return {
+      mode: "builder-unavailable",
+      appId: built.appId,
+      reason: "builder-not-connected",
+      projectId: settings.builderProjectId,
+      message: "Connect your Builder account to create apps from Dispatch.",
+    };
+  }
+
+  const builderUserId = builderCreds.userId || undefined;
+
   let result: {
     branchName: string;
     url: string;
     status: string;
   };
   try {
-    const builderCreds = await resolveBuilderCredentials().catch(() => null);
-    const builderUserId = builderCreds?.userId || undefined;
     result = normalizeBuilderRunResult(
       await runBuilderAgent({
         prompt,
@@ -1891,11 +2031,11 @@ export async function startWorkspaceAppCreation(input: {
     return {
       mode: "builder-unavailable",
       appId: built.appId,
+      reason: "builder-error",
       projectId: settings.builderProjectId,
+      detail,
       message:
-        `Builder app creation is configured for project ${settings.builderProjectId}, ` +
-        `but it could not start yet: ${detail}. Connect Builder for this user, ` +
-        `link the messaging identity to that user, or configure deployment-managed Builder credentials for this workspace.`,
+        "Builder could not start the app branch. This is usually temporary — try again.",
     };
   }
 

package/src/server/plugins/integrations.ts

@@ -42,7 +42,7 @@ When a user asks for something:
 - If the user asks to create, build, make, scaffold, or generate an "agent" from Dispatch chat or by tagging @agent-native in Slack, email, or Telegram, first classify the ask. If it is a simple Dispatch-native behavior like a reminder, digest, monitor, routing rule, saved instruction, or recurring workflow, create or update the recurring job/resource/destination in Dispatch. If it is a robust unique product or teammate that needs its own UI, data model, actions, integrations, or domain workflow, treat it as a new workspace app and call start-workspace-app-creation.
 - If a new-app prompt asks for access to Mail, Calendar, Analytics, Brain, Assets, or similar first-party app data/agents, keep using the existing hosted/connected app and A2A path. Do not ask Builder to scaffold those apps as children of the new app unless the user explicitly asks for a customized fork/copy.
 - If the chat template is used, treat it as scaffolding only: the finished app must be branded as the requested app with its own home screen/navigation/package metadata/manifest, and must not leave visible "Chat", "Starter", "Blank app", or "New app" UI behind.
-- If the user explicitly asks for a new app or workspace app, call start-workspace-app-creation with their prompt and include a concise generated description by default. Do not satisfy a new-app request by adding a route, page, component, or file inside apps/chat or another existing app unless the user explicitly asks to modify that existing app. If the request is too vague to classify, ask one concise follow-up. If the action returns mode "builder", reply with the Builder branch URL; Builder is responsible for creating the separate workspace app under apps/<app-id>, mounting it at /<app-id>, ensuring apps/<app-id>/package.json exists with name/displayName and description so Dispatch discovers it, using relative /<app-id> links instead of hardcoded localhost/dev ports, and preserving APP_BASE_PATH/VITE_APP_BASE_PATH via appBasePath() in the React Router client entry. The new app lives at the workspace root /<app-id>, NOT under /dispatch/<app-id>, /apps/<app-id>, or any other Dispatch tab — when telling the user where to find it, link to /<app-id> only. There is no separate workspace app registry to edit. If it returns mode "local-agent", tell the user it is ready for the local code agent and include the returned app path/prompt summary. If it returns mode "coming-soon", say this requires a code change and they can edit locally or use Builder.io to edit this code in the cloud and continue customizing the app any way they like; do not send them to Builder org/beta settings. If it returns mode "builder-unavailable", report the action's message exactly enough to preserve the missing identity/credential detail.
+- If the user explicitly asks for a new app or workspace app, call start-workspace-app-creation with their prompt and include a concise generated description by default. Do not satisfy a new-app request by adding a route, page, component, or file inside apps/chat or another existing app unless the user explicitly asks to modify that existing app. If the request is too vague to classify, ask one concise follow-up. If the action returns mode "builder", reply with the Builder branch URL; Builder is responsible for creating the separate workspace app under apps/<app-id>, mounting it at /<app-id>, ensuring apps/<app-id>/package.json exists with name/displayName and description so Dispatch discovers it, using relative /<app-id> links instead of hardcoded localhost/dev ports, and preserving APP_BASE_PATH/VITE_APP_BASE_PATH via appBasePath() in the React Router client entry. The new app lives at the workspace root /<app-id>, NOT under /dispatch/<app-id>, /apps/<app-id>, or any other Dispatch tab — when telling the user where to find it, link to /<app-id> only. There is no separate workspace app registry to edit. If it returns mode "local-agent", tell the user it is ready for the local code agent and include the returned app path/prompt summary. If it returns mode "coming-soon", say this requires a code change and they can edit locally or use Builder.io to edit this code in the cloud and continue customizing the app any way they like; do not send them to Builder org/beta settings. If it returns mode "builder-unavailable", the action also returns a \`reason\` code plus a user-facing \`message\` and (for some reasons) an operator-facing \`detail\`. Relay the \`message\` to the user as-is; only surface \`detail\` when the user is clearly an operator debugging the deployment (e.g. troubleshooting a broken Builder connection for the workspace), never as routine detail for an end user.
 - For digests, reminders, or saved behavior, prefer recurring jobs, resources, or destinations over chat replies.
 - Keep responses concise and operational — messaging platforms have character limits.
 - Use markdown sparingly (bold and lists are fine, avoid complex formatting).