@agent-native/dispatch 0.6.1 → 0.7.0

package/src/server/lib/vault-store.spec.ts

@@ -0,0 +1,69 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  writeAppSecret: vi.fn(),
+}));
+
+vi.mock("@agent-native/core/secrets", () => ({
+  writeAppSecret: mocks.writeAppSecret,
+}));
+
+import {
+  credentialStoreScopeForVaultCtx,
+  syncSecretsToCredentialStore,
+} from "./vault-store.js";
+
+afterEach(() => {
+  vi.clearAllMocks();
+});
+
+describe("credentialStoreScopeForVaultCtx", () => {
+  it("uses org scope when vault sync runs inside an org", () => {
+    expect(
+      credentialStoreScopeForVaultCtx({
+        ownerEmail: "admin@example.test",
+        orgId: "org_123",
+      }),
+    ).toEqual({ scope: "org", scopeId: "org_123" });
+  });
+
+  it("uses workspace solo scope when no org is active", () => {
+    expect(
+      credentialStoreScopeForVaultCtx({
+        ownerEmail: "owner@example.test",
+        orgId: null,
+      }),
+    ).toEqual({
+      scope: "workspace",
+      scopeId: "solo:owner@example.test",
+    });
+  });
+});
+
+describe("syncSecretsToCredentialStore", () => {
+  it("writes vault secrets into app_secrets without returning values", async () => {
+    const result = await syncSecretsToCredentialStore(
+      [
+        {
+          name: "OpenAI API Key",
+          credentialKey: "OPENAI_API_KEY",
+          value: "sk-test-key",
+        } as any,
+      ],
+      { ownerEmail: "admin@example.test", orgId: "org_123" },
+    );
+
+    expect(mocks.writeAppSecret).toHaveBeenCalledWith({
+      key: "OPENAI_API_KEY",
+      value: "sk-test-key",
+      scope: "org",
+      scopeId: "org_123",
+      description: "Synced from Dispatch vault: OpenAI API Key",
+    });
+    expect(result).toEqual({
+      scope: "org",
+      scopeId: "org_123",
+      keys: ["OPENAI_API_KEY"],
+    });
+  });
+});

package/src/server/lib/vault-store.ts

@@ -1,6 +1,13 @@
 import crypto from "node:crypto";
 import { and, desc, eq, isNull, or } from "drizzle-orm";
 import { discoverAgents } from "@agent-native/core/server/agent-discovery";
+import { writeAppSecret, type SecretScope } from "@agent-native/core/secrets";
+import {
+  getOrgSetting,
+  getUserSetting,
+  putOrgSetting,
+  putUserSetting,
+} from "@agent-native/core/settings";
 import { getDb, schema } from "../../db/index.js";
 import {
   currentOwnerEmail,
@@ -8,6 +15,16 @@ import {
   recordAudit,
 } from "./dispatch-store.js";
 
+const VAULT_ACCESS_SETTINGS_KEY = "dispatch-vault-access-settings";
+
+export type VaultAccessMode = "all-apps" | "manual";
+
+export interface VaultAccessSettings {
+  mode: VaultAccessMode;
+  scope: "org" | "user";
+  scopeId: string;
+}
+
 /**
  * Caller-supplied access context for vault operations.
  *
@@ -40,10 +57,10 @@ function ctxScope<T extends { ownerEmail: any; orgId: any }>(
   table: T,
   ctx: VaultCtx,
 ) {
-  return or(
-    eq(table.ownerEmail, ctx.ownerEmail),
-    ctx.orgId ? eq(table.orgId, ctx.orgId) : isNull(table.orgId),
-  );
+  if (!ctx.orgId) {
+    return and(eq(table.ownerEmail, ctx.ownerEmail), isNull(table.orgId));
+  }
+  return or(eq(table.ownerEmail, ctx.ownerEmail), eq(table.orgId, ctx.orgId));
 }
 
 /** Build a ctx that scopes to a specific row's owner/org (used when a
@@ -68,12 +85,57 @@ function safeJson(value: unknown) {
   return JSON.stringify(value ?? null);
 }
 
-function orgFilter<T extends { ownerEmail: any; orgId: any }>(table: T) {
+function scopedFilter<T extends { ownerEmail: any; orgId: any }>(table: T) {
+  return ctxScope(table, requireVaultCtx());
+}
+
+function normalizeCredentialKey(value: string) {
+  return value.trim();
+}
+
+function vaultAccessScope() {
   const orgId = currentOrgId();
-  return and(
-    eq(table.ownerEmail, currentOwnerEmail()),
-    orgId ? eq(table.orgId, orgId) : isNull(table.orgId),
-  );
+  if (orgId) return { scope: "org" as const, scopeId: orgId };
+  return { scope: "user" as const, scopeId: currentOwnerEmail() };
+}
+
+function parseVaultAccessMode(value: unknown): VaultAccessMode {
+  return value === "manual" ? "manual" : "all-apps";
+}
+
+export async function getVaultAccessSettings(): Promise<VaultAccessSettings> {
+  const scope = vaultAccessScope();
+  const raw =
+    scope.scope === "org"
+      ? await getOrgSetting(scope.scopeId, VAULT_ACCESS_SETTINGS_KEY)
+      : await getUserSetting(scope.scopeId, VAULT_ACCESS_SETTINGS_KEY);
+  return {
+    ...scope,
+    mode: parseVaultAccessMode(raw?.mode),
+  };
+}
+
+export async function setVaultAccessSettings(input: {
+  mode: VaultAccessMode;
+}): Promise<VaultAccessSettings> {
+  const scope = vaultAccessScope();
+  const next = { mode: parseVaultAccessMode(input.mode) };
+  if (scope.scope === "org") {
+    await putOrgSetting(scope.scopeId, VAULT_ACCESS_SETTINGS_KEY, next);
+  } else {
+    await putUserSetting(scope.scopeId, VAULT_ACCESS_SETTINGS_KEY, next);
+  }
+  await recordAudit({
+    action: "vault.access-settings.updated",
+    targetType: "vault-settings",
+    targetId: VAULT_ACCESS_SETTINGS_KEY,
+    summary:
+      next.mode === "all-apps"
+        ? "Set vault access to all workspace apps"
+        : "Set vault access to manual per-app grants",
+    metadata: next,
+  });
+  return getVaultAccessSettings();
 }
 
 // ─── Vault Audit ──────────────────────────────────────────────────
@@ -106,7 +168,7 @@ export async function listVaultAudit(limit = 50) {
   return db
     .select()
     .from(schema.vaultAuditLog)
-    .where(orgFilter(schema.vaultAuditLog))
+    .where(scopedFilter(schema.vaultAuditLog))
     .orderBy(desc(schema.vaultAuditLog.createdAt))
     .limit(limit);
 }
@@ -118,7 +180,7 @@ export async function listSecrets() {
   return db
     .select()
     .from(schema.vaultSecrets)
-    .where(orgFilter(schema.vaultSecrets))
+    .where(scopedFilter(schema.vaultSecrets))
     .orderBy(desc(schema.vaultSecrets.updatedAt));
 }
 
@@ -149,6 +211,55 @@ export async function createSecret(
 ) {
   const db = getDb();
   const timestamp = now();
+  const credentialKey = normalizeCredentialKey(input.credentialKey);
+  if (!credentialKey) throw new Error("Credential key is required");
+  const existing = await db
+    .select()
+    .from(schema.vaultSecrets)
+    .where(
+      and(
+        eq(schema.vaultSecrets.credentialKey, credentialKey),
+        ctxScope(schema.vaultSecrets, ctx),
+      ),
+    )
+    .orderBy(desc(schema.vaultSecrets.updatedAt))
+    .limit(1);
+
+  if (existing[0]) {
+    await db
+      .update(schema.vaultSecrets)
+      .set({
+        name: input.name,
+        credentialKey,
+        value: input.value,
+        provider: input.provider || null,
+        description: input.description || null,
+        updatedAt: timestamp,
+      })
+      .where(
+        and(
+          eq(schema.vaultSecrets.id, existing[0].id),
+          ctxScope(schema.vaultSecrets, ctx),
+        ),
+      );
+
+    await recordVaultAudit({
+      action: "secret.updated",
+      secretId: existing[0].id,
+      summary: `Updated secret "${input.name}" (${credentialKey})`,
+      metadata: { credentialKey, provider: input.provider },
+    });
+
+    await recordAudit({
+      action: "vault.secret.updated",
+      targetType: "vault-secret",
+      targetId: existing[0].id,
+      summary: `Updated vault secret "${input.name}" (${credentialKey})`,
+    });
+
+    return getSecret(existing[0].id, ctx);
+  }
+
   const secretId = id();
   const actor = ctx.ownerEmail;
 
@@ -157,7 +268,7 @@ export async function createSecret(
     ownerEmail: actor,
     orgId: ctx.orgId,
     name: input.name,
-    credentialKey: input.credentialKey,
+    credentialKey,
     value: input.value,
     provider: input.provider || null,
     description: input.description || null,
@@ -169,15 +280,15 @@ export async function createSecret(
   await recordVaultAudit({
     action: "secret.created",
     secretId,
-    summary: `Created secret "${input.name}" (${input.credentialKey})`,
-    metadata: { credentialKey: input.credentialKey, provider: input.provider },
+    summary: `Created secret "${input.name}" (${credentialKey})`,
+    metadata: { credentialKey, provider: input.provider },
   });
 
   await recordAudit({
     action: "vault.secret.created",
     targetType: "vault-secret",
     targetId: secretId,
-    summary: `Created vault secret "${input.name}" (${input.credentialKey})`,
+    summary: `Created vault secret "${input.name}" (${credentialKey})`,
   });
 
   return getSecret(secretId, ctx);
@@ -259,7 +370,7 @@ export async function listGrants(filter?: {
   appId?: string;
 }) {
   const db = getDb();
-  const conditions = [orgFilter(schema.vaultGrants)];
+  const conditions = [scopedFilter(schema.vaultGrants)];
   if (filter?.secretId) {
     conditions.push(eq(schema.vaultGrants.secretId, filter.secretId) as any);
   }
@@ -340,7 +451,16 @@ export async function grantSecretsToApp(
   appId: string,
   ctx: VaultCtx = requireVaultCtx(),
 ) {
+  const access = await getVaultAccessSettings();
   const uniqueSecretIds = Array.from(new Set(secretIds));
+  if (access.mode === "all-apps") {
+    return {
+      appId,
+      accessMode: access.mode,
+      created: [],
+      skipped: uniqueSecretIds,
+    };
+  }
   const existingActive = (await listGrants({ appId })).filter(
     (grant) => grant.status === "active",
   );
@@ -362,7 +482,7 @@ export async function grantSecretsToApp(
     }
   }
 
-  return { appId, created, skipped };
+  return { appId, accessMode: access.mode, created, skipped };
 }
 
 export async function revokeGrant(
@@ -403,6 +523,40 @@ export async function revokeGrant(
   return getGrant(grantId, ctx);
 }
 
+// ─── Shared Credential Store Sync ─────────────────────────────────
+
+type VaultSecretRow = typeof schema.vaultSecrets.$inferSelect;
+
+export function credentialStoreScopeForVaultCtx(ctx: VaultCtx): {
+  scope: Extract<SecretScope, "org" | "workspace">;
+  scopeId: string;
+} {
+  if (ctx.orgId) return { scope: "org", scopeId: ctx.orgId };
+  return { scope: "workspace", scopeId: `solo:${ctx.ownerEmail}` };
+}
+
+export async function syncSecretsToCredentialStore(
+  secrets: VaultSecretRow[],
+  ctx: VaultCtx,
+) {
+  const target = credentialStoreScopeForVaultCtx(ctx);
+  const syncedKeys: string[] = [];
+
+  for (const secret of secrets) {
+    if (!secret.credentialKey || !secret.value) continue;
+    await writeAppSecret({
+      key: secret.credentialKey,
+      value: secret.value,
+      scope: target.scope,
+      scopeId: target.scopeId,
+      description: `Synced from Dispatch vault: ${secret.name}`,
+    });
+    syncedKeys.push(secret.credentialKey);
+  }
+
+  return { ...target, keys: syncedKeys };
+}
+
 // ─── Sync ──────────────────────────────────────────────────────
 
 export async function syncGrantsToApp(
@@ -410,46 +564,78 @@ export async function syncGrantsToApp(
   ctx: VaultCtx = requireVaultCtx(),
 ) {
   const db = getDb();
+  const access = await getVaultAccessSettings();
   const agents = await discoverAgents("dispatch");
   const agent = agents.find((a) => a.id === appId);
   if (!agent) throw new Error(`App "${appId}" not found in agent registry`);
 
-  const grants = await listGrants({ appId });
-  const activeGrants = grants.filter((g) => g.status === "active");
-  if (activeGrants.length === 0) {
-    return { appId, synced: 0, keys: [] };
-  }
+  const secretsToSync: VaultSecretRow[] = [];
+  const activeGrants =
+    access.mode === "manual"
+      ? (await listGrants({ appId })).filter((g) => g.status === "active")
+      : [];
 
-  // Resolve secret values for each grant
-  const vars: Array<{ key: string; value: string }> = [];
-  for (const grant of activeGrants) {
-    const secret = await getSecret(grant.secretId, ctx);
-    if (secret) {
-      vars.push({ key: secret.credentialKey, value: secret.value });
+  if (access.mode === "all-apps") {
+    const secrets = await listSecrets();
+    for (const secret of secrets) {
+      secretsToSync.push(secret);
+    }
+  } else {
+    for (const grant of activeGrants) {
+      const secret = await getSecret(grant.secretId, ctx);
+      if (secret) {
+        secretsToSync.push(secret);
+      }
     }
   }
 
-  if (vars.length === 0) {
-    return { appId, synced: 0, keys: [] };
+  if (secretsToSync.length === 0) {
+    return { appId, accessMode: access.mode, synced: 0, keys: [] };
   }
 
-  // Push to the app's env-vars endpoint
-  const res = await fetch(`${agent.url}/_agent-native/env-vars`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ vars }),
-  });
-
-  if (!res.ok) {
-    const err = await res.text().catch(() => "Unknown error");
-    throw new Error(`Failed to sync to ${appId}: ${err}`);
+  const credentialStoreSync = await syncSecretsToCredentialStore(
+    secretsToSync,
+    ctx,
+  );
+  const vars = secretsToSync.map((secret) => ({
+    key: secret.credentialKey,
+    value: secret.value,
+  }));
+  let envVarSync:
+    | { status: "synced"; keys: string[] }
+    | { status: "skipped"; reason: string }
+    | { status: "failed"; reason: string };
+
+  // Best-effort push to the app's env-vars endpoint for local/dev apps that
+  // still read process.env directly. Production/shared-DB apps intentionally
+  // reject env writes; the encrypted app_secrets sync above is the canonical
+  // path for request-scoped credentials.
+  try {
+    const res = await fetch(`${agent.url}/_agent-native/env-vars`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ vars }),
+    });
+
+    if (res.ok) {
+      const result = await res.json();
+      envVarSync = { status: "synced", keys: result.saved || [] };
+    } else {
+      const err = await res.text().catch(() => "Unknown error");
+      envVarSync = { status: "skipped", reason: err };
+    }
+  } catch (err) {
+    envVarSync = {
+      status: "failed",
+      reason: err instanceof Error ? err.message : String(err),
+    };
   }
 
-  const result = await res.json();
-  const syncedKeys: string[] = result.saved || [];
+  const syncedKeys = credentialStoreSync.keys;
   const timestamp = now();
 
-  // Update syncedAt on grants that were successfully pushed
+  // Update syncedAt on grants that were successfully pushed to the shared
+  // credential store. All-apps mode has no explicit grant rows to update.
   for (const grant of activeGrants) {
     const secret = await getSecret(grant.secretId, ctx);
     if (secret && syncedKeys.includes(secret.credentialKey)) {
@@ -464,17 +650,36 @@ export async function syncGrantsToApp(
     action: "secret.synced",
     appId,
     summary: `Synced ${syncedKeys.length} secret(s) to ${appId}: ${syncedKeys.join(", ")}`,
-    metadata: { syncedKeys },
+    metadata: {
+      syncedKeys,
+      accessMode: access.mode,
+      credentialStore: {
+        scope: credentialStoreSync.scope,
+        scopeId: credentialStoreSync.scopeId,
+      },
+      envVars: envVarSync,
+    },
   });
 
-  return { appId, synced: syncedKeys.length, keys: syncedKeys };
+  return {
+    appId,
+    accessMode: access.mode,
+    synced: syncedKeys.length,
+    keys: syncedKeys,
+    credentialStore: {
+      scope: credentialStoreSync.scope,
+      scopeId: credentialStoreSync.scopeId,
+      synced: credentialStoreSync.keys.length,
+    },
+    envVars: envVarSync,
+  };
 }
 
 // ─── Requests ──────────────────────────────────────────────────────
 
 export async function listRequests(filter?: { status?: string }) {
   const db = getDb();
-  const conditions = [orgFilter(schema.vaultRequests)];
+  const conditions = [scopedFilter(schema.vaultRequests)];
   if (filter?.status) {
     conditions.push(eq(schema.vaultRequests.status, filter.status) as any);
   }
@@ -671,10 +876,12 @@ export interface AppIntegrations {
   url: string;
   color: string;
   integrations: IntegrationEntry[];
+  vaultAccessMode: VaultAccessMode;
   reachable: boolean;
 }
 
 export async function listIntegrationsCatalog(): Promise<AppIntegrations[]> {
+  const access = await getVaultAccessSettings();
   const agents = await discoverAgents("dispatch");
   const grants = await listGrants();
   const secrets = await listSecrets();
@@ -695,6 +902,7 @@ export async function listIntegrationsCatalog(): Promise<AppIntegrations[]> {
           url: agent.url,
           color: agent.color,
           integrations: [],
+          vaultAccessMode: access.mode,
           reachable: false,
         });
         continue;
@@ -720,7 +928,9 @@ export async function listIntegrationsCatalog(): Promise<AppIntegrations[]> {
           required: env.required,
           configured: env.configured,
           vaultGranted:
-            !!matchingSecret && grantedSecretIds.has(matchingSecret.id),
+            !!matchingSecret &&
+            (access.mode === "all-apps" ||
+              grantedSecretIds.has(matchingSecret.id)),
           vaultSecretId: matchingSecret?.id,
         };
       });
@@ -731,6 +941,7 @@ export async function listIntegrationsCatalog(): Promise<AppIntegrations[]> {
         url: agent.url,
         color: agent.color,
         integrations,
+        vaultAccessMode: access.mode,
         reachable: true,
       });
     } catch {
@@ -740,6 +951,7 @@ export async function listIntegrationsCatalog(): Promise<AppIntegrations[]> {
         url: agent.url,
         color: agent.color,
         integrations: [],
+        vaultAccessMode: access.mode,
         reachable: false,
       });
     }
@@ -751,15 +963,20 @@ export async function listIntegrationsCatalog(): Promise<AppIntegrations[]> {
 // ─── Vault Overview (for dashboard) ──────────────────────────────
 
 export async function listVaultOverview() {
-  const [secrets, grants, requests] = await Promise.all([
+  const [secrets, grants, requests, access] = await Promise.all([
     listSecrets(),
     listGrants(),
     listRequests(),
+    getVaultAccessSettings(),
   ]);
+  const manualGrantCount = grants.filter((g) => g.status === "active").length;
 
   return {
+    accessMode: access.mode,
     secretCount: secrets.length,
-    activeGrantCount: grants.filter((g) => g.status === "active").length,
+    activeGrantCount:
+      access.mode === "all-apps" ? secrets.length : manualGrantCount,
+    manualGrantCount,
     pendingRequestCount: requests.filter((r) => r.status === "pending").length,
   };
 }

package/src/server/plugins/agent-chat.ts

@@ -27,8 +27,9 @@ Use the standard workspace primitives:
 - Read and update resources like AGENTS.md, LEARNINGS.md, jobs/*.md, agents/*.md, and remote-agents/*.json when appropriate.
 - Use recurring jobs for scheduled behavior.
 - Use custom agent profiles in agents/*.md for local spawned work and remote-agents/*.json for remote A2A apps.
+- You receive a compact available-apps block with sibling workspace app names and descriptions. Use it to pick the right A2A target, and call list-connected-agents or tool-search only when you need fresh details.
 - When answering whether workspace apps expose agent cards or A2A endpoints, call list-workspace-apps with includeAgentCards=true. If you have not requested that probe, absence of agent-card fields means unchecked, not unavailable.
-- When creating a new workspace app, create a separate app under apps/<app-id> with apps/<app-id>/package.json, mount it at /<app-id>, use relative /<app-id> links, never hardcode localhost or dev ports, use shadcn/ui with @tabler/icons-react rather than lucide-react, and ensure the React Router client entry preserves APP_BASE_PATH/VITE_APP_BASE_PATH via appBasePath(). There is no separate workspace app registry to edit.
+- When creating a new workspace app, create a separate app under apps/<app-id> with apps/<app-id>/package.json including a concise generated description, mount it at /<app-id>, use relative /<app-id> links, never hardcode localhost or dev ports, use shadcn/ui with @tabler/icons-react rather than lucide-react, and ensure the React Router client entry preserves APP_BASE_PATH/VITE_APP_BASE_PATH via appBasePath(). There is no separate workspace app registry to edit.
 - Treat first-party apps such as Mail, Calendar, Analytics, and Dispatch as existing hosted/connected neighbors available through links and A2A/default connected agents. Do not create wrapper apps, child apps, nested routes, or cloned template copies just to give a new app access to them; build only the genuinely new workflow and delegate cross-app work to those existing apps.
 
 When a user asks for something like a digest, reminder, routing rule, or saved behavior:

package/src/server/plugins/core-routes.ts

@@ -1,5 +1,10 @@
 import { createCoreRoutesPlugin } from "@agent-native/core/server";
 import { envKeys } from "../lib/env-config.js";
+import { registerDispatchOnboardingSteps } from "../lib/onboarding-steps.js";
+
+// Register before the core plugin so "create your first app" (order 5) appears
+// above the auto-generated Slack/Telegram steps (order 60). Idempotent.
+registerDispatchOnboardingSteps();
 
 export default createCoreRoutesPlugin({
   envKeys,

package/src/server/plugins/integrations.ts

@@ -11,7 +11,7 @@ const DISPATCH_INTEGRATION_SYSTEM_PROMPT = `You are the central dispatch for thi
 Default posture:
 - Treat Slack, Telegram, and email as shared entrypoints into the workspace.
 - Heavily delegate domain work to specialized agents through A2A (call-agent) when another app owns the job. Apps you can delegate to include slides (decks/presentations), analytics (data/dashboards), content (docs/articles), videos (Remotion compositions), forms (form builder), clips (screen recordings), design (visual designs), and images (brand image libraries and generated raster imagery).
-- Use list-connected-agents to see what agents are available before assuming a request must be handled locally.
+- Use the available-apps prompt context first, then list-connected-agents when you need fresh details, to see what agents are available before assuming a request must be handled locally.
 - When asked whether workspace apps expose agent cards or A2A endpoints, call list-workspace-apps with includeAgentCards=true. Without that probe, missing agent-card fields mean unchecked, not unavailable.
 - Treat first-party apps such as Mail, Calendar, Analytics, and Dispatch as existing hosted/connected neighbors available through links and A2A/default connected agents. Do not create wrapper apps, child apps, nested routes, or cloned template copies just to give a new app access to them; build only the genuinely new workflow and delegate cross-app work to those existing apps.
 - Keep durable memory and operating instructions in resources rather than ephemeral chat.
@@ -23,7 +23,7 @@ When a user asks for something:
 - Exception: if the downstream agent reports a missing model/provider credential, do not name exact env vars, Vault keys, tokens, or secrets. Say the target app needs an LLM connection and recommend connecting Builder/managed LLM for that app; keep bring-your-own provider keys as a secondary option only if the user asks.
 - 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, 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 user explicitly asks for a new app or workspace app, call start-workspace-app-creation with their prompt. Do not satisfy a new-app request by adding a route, page, component, or file inside apps/starter 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 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" or "builder-unavailable", explain the missing Builder setup and ask them to connect/configure Builder.
+- 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 when possible. Do not satisfy a new-app request by adding a route, page, component, or file inside apps/starter 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" or "builder-unavailable", explain the missing Builder setup and ask them to connect/configure Builder.
 - 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).