@agent-native/dispatch 0.40.30-nightly-20261021064625 → 0.40.30

package/dist/server/lib/app-creation-store.js

@@ -6,24 +6,27 @@ import { canonicalA2AAudience, signA2AToken } from "@agent-native/core/a2a";
 import { isActionContractError } from "@agent-native/core/action";
 import { describeErrorWithCauses } from "@agent-native/core/agent/engine/error-detail";
 import { getDbExec } from "@agent-native/core/db";
-import { getOrgDomain, isWorkspaceAppAccessAllowed, } from "@agent-native/core/org";
+import { and, eq, inArray } from "@agent-native/core/db/schema";
+import { getOrgDomain, isWorkspaceAppAccessAllowed, workspaceApps, } from "@agent-native/core/org";
 import { CredentialStoreUnavailableError, FeatureNotConfiguredError, createBuilderProject, getBuilderBranchProjectId, getConfiguredAppBasePath, getRequestContext, inferWorkspaceAppRootHomePath, isIntegrationCallerRequest, readConfiguredWorkspaceAppHomePath, resolveAppRuntimeUrl, resolveVercelDeploymentProtectionHeaders, normalizeBuilderAgentAttachments, runBuilderAgent, } from "@agent-native/core/server";
 import { getOrgSetting } from "@agent-native/core/settings";
 import { getSetting, mutateSetting, putSetting, } from "@agent-native/core/settings";
-import { BUILDER_CONNECT_PROVIDER, BUILDER_CONNECT_PROVIDER_LABEL, assertValidWorkspaceAppId, connectRequiredResult, normalizeWorkspaceAppHomePath, } from "@agent-native/core/shared";
+import { BUILDER_CONNECT_PROVIDER, BUILDER_CONNECT_PROVIDER_LABEL, assertValidWorkspaceAppId, connectRequiredResult, normalizeWorkspaceAppHomePath, parseAgentProfileMetadata, } from "@agent-native/core/shared";
 import { resolveAccess } from "@agent-native/core/sharing";
-import "../../db/index.js";
+import { getDb } from "../../db/index.js";
 import { isWorkspaceSsoAppUrl } from "../../shared/workspace-sso.js";
 import { getDispatchDefaultOwnerEmail } from "./admin-config.js";
 import { identityKeyForIncoming } from "./dispatch-integrations.js";
 import { currentOrgId, currentOwnerEmail, recordAudit, resolveLinkedOwner, } from "./dispatch-store.js";
 import { projectEnvironmentUrl, requestEnvironmentLane, } from "./environment-lane.js";
+import { invalidateOrgAppsDirectoryCache } from "./org-apps-directory-cache.js";
 import { createRequest, listSecretOptions } from "./vault-store.js";
 import { WORKSPACE_APPS_ACTION_PATH } from "./workspace-app-action-auth.js";
 import { grantWorkspaceResourcesToApp, listWorkspaceResourceOptions, } from "./workspace-resources-store.js";
 const SETTINGS_KEY = "dispatch-app-creation-settings";
 const DEFAULT_BUILDER_WORKSPACE_PROJECT_NAME = "Agent-Native Workspace";
 const APP_CREATION_SETTINGS_AUTHORIZATION_MESSAGE = "Only organization owners and admins can update app creation settings.";
+const WORKSPACE_APP_METADATA_AUTHORIZATION_MESSAGE = "Only organization owners and admins can update workspace app details.";
 const APP_CREATION_SETTINGS_REQUIRED_MESSAGE = "An organization owner or admin must configure the Builder workspace project before members can create apps.";
 const WORKSPACE_APP_METADATA_SETTINGS_KEY = "workspace-app-metadata";
 const WORKSPACE_APP_DEFAULT_VISIBILITY_KEY = "workspace-app-default-visibility";
@@ -57,6 +60,22 @@ class AppCreationSettingsAuthorizationError extends Error {
         this.name = "AppCreationSettingsAuthorizationError";
     }
 }
+class WorkspaceAppMetadataAuthorizationError extends Error {
+    statusCode = 403;
+    constructor() {
+        super(WORKSPACE_APP_METADATA_AUTHORIZATION_MESSAGE);
+        this.name = "WorkspaceAppMetadataAuthorizationError";
+    }
+}
+class AppCreationOwnerRoleUnavailableError extends Error {
+    statusCode = 503;
+    constructor(cause) {
+        super("Could not verify the organization role. Try again shortly.", {
+            cause,
+        });
+        this.name = "AppCreationOwnerRoleUnavailableError";
+    }
+}
 class WorkspaceAppOrgRequiredError extends Error {
     statusCode = 400;
     constructor() {
@@ -189,7 +208,7 @@ function pendingWorkspaceAppContext() {
     }
 }
 async function readSettingsRecord() {
-    const raw = await getSetting(scopedSettingsKey()).catch(() => null);
+    const raw = await getSetting(scopedSettingsKey());
     return raw && typeof raw === "object" && !Array.isArray(raw)
         ? raw
         : {};
@@ -197,6 +216,14 @@ async function readSettingsRecord() {
 function cleanOptionalText(value) {
     return typeof value === "string" && value.trim() ? value.trim() : undefined;
 }
+function normalizeCommunitySourceId(value) {
+    if (typeof value !== "string" ||
+        value.length > 100 ||
+        !/^community-[a-z0-9]+(?:-[a-z0-9]+)*$/i.test(value)) {
+        return undefined;
+    }
+    return value.toLowerCase();
+}
 function parseWorkspaceAppMetadataSettings(raw) {
     const record = raw && typeof raw === "object" && !Array.isArray(raw)
         ? raw
@@ -214,14 +241,23 @@ function parseWorkspaceAppMetadataSettings(raw) {
         const override = {};
         const name = cleanOptionalText(item.name);
         const description = cleanOptionalText(item.description);
+        const profile = parseAgentProfileMetadata({
+            whenToUse: item.whenToUse,
+        });
         const sourcePrompt = cleanOptionalText(item.sourcePrompt);
         const updatedAt = cleanOptionalText(item.updatedAt);
         const updatedBy = cleanOptionalText(item.updatedBy);
         const createdBy = cleanOptionalText(item.createdBy);
+        const communitySourceId = normalizeCommunitySourceId(item.communitySourceId);
         if (name)
             override.name = name;
         if (description)
             override.description = description;
+        if (profile?.whenToUse)
+            override.whenToUse = profile.whenToUse;
+        else if (Array.isArray(item.whenToUse) && item.whenToUse.length === 0) {
+            override.whenToUse = [];
+        }
         if (item.generated === true)
             override.generated = true;
         if (sourcePrompt)
@@ -232,6 +268,8 @@ function parseWorkspaceAppMetadataSettings(raw) {
             override.updatedBy = updatedBy;
         if (createdBy)
             override.createdBy = createdBy;
+        if (communitySourceId)
+            override.communitySourceId = communitySourceId;
         if (item.visibility === "private" || item.visibility === "org") {
             override.visibility = item.visibility;
         }
@@ -241,31 +279,54 @@ function parseWorkspaceAppMetadataSettings(raw) {
     return { apps };
 }
 async function readWorkspaceAppMetadataSettings() {
-    const raw = await getSetting(workspaceAppMetadataSettingsKey()).catch(() => null);
+    const raw = await getSetting(workspaceAppMetadataSettingsKey());
     return parseWorkspaceAppMetadataSettings(raw);
 }
 async function writeWorkspaceAppMetadataOverride(input) {
     const key = workspaceAppMetadataSettingsKey();
-    const current = parseWorkspaceAppMetadataSettings(await getSetting(key).catch(() => null));
+    const current = parseWorkspaceAppMetadataSettings(await getSetting(key));
     const appId = input.appId.trim();
     const existing = current.apps[appId] ?? {};
     const next = {
         ...existing,
         updatedAt: new Date().toISOString(),
     };
+    const hasName = Object.hasOwn(input, "name") && input.name !== undefined;
+    const hasDescription = Object.hasOwn(input, "description") && input.description !== undefined;
+    const hasWhenToUse = Object.hasOwn(input, "whenToUse") && input.whenToUse !== undefined;
     const name = cleanOptionalText(input.name);
     const description = cleanOptionalText(input.description);
+    const whenToUse = input.whenToUse;
     const sourcePrompt = cleanOptionalText(input.sourcePrompt);
     const updatedBy = cleanOptionalText(input.updatedBy);
     const createdBy = cleanOptionalText(input.createdBy);
-    if (name)
-        next.name = name;
-    else
-        delete next.name;
-    if (description)
-        next.description = description;
-    else
-        delete next.description;
+    const communitySourceId = normalizeCommunitySourceId(input.communitySourceId);
+    if (hasName) {
+        if (name)
+            next.name = name;
+        else
+            delete next.name;
+    }
+    if (hasDescription) {
+        if (description)
+            next.description = description;
+        else
+            delete next.description;
+    }
+    if (hasWhenToUse) {
+        const examples = whenToUse ?? [];
+        const profile = parseAgentProfileMetadata({
+            description: description ?? next.description,
+            whenToUse: examples,
+        });
+        if (!profile) {
+            throw new Error("Workspace app when-to-use entries must contain up to 6 non-empty examples of 140 characters or fewer.");
+        }
+        next.whenToUse = profile.whenToUse ?? [];
+    }
+    if (description && description.length > 1000) {
+        throw new Error("Workspace app descriptions must be 1,000 characters or fewer.");
+    }
     if (input.generated === true)
         next.generated = true;
     else if (input.generated === false)
@@ -276,6 +337,14 @@ async function writeWorkspaceAppMetadataOverride(input) {
         next.updatedBy = updatedBy;
     if (createdBy)
         next.createdBy = createdBy;
+    if (input.communitySourceId !== undefined) {
+        if (input.communitySourceId === null || !communitySourceId) {
+            delete next.communitySourceId;
+        }
+        else {
+            next.communitySourceId = communitySourceId;
+        }
+    }
     if (input.visibility)
         next.visibility = input.visibility;
     current.apps[appId] = next;
@@ -288,17 +357,26 @@ function applyWorkspaceAppMetadataOverride(app, settings) {
         return app;
     const name = cleanOptionalText(override.name);
     const description = cleanOptionalText(override.description);
+    const whenToUse = override.whenToUse;
     const generated = override.generated === true;
     const shouldApplyName = !!name && !generated;
     const shouldApplyDescription = !!description && (!generated || !cleanOptionalText(app.description));
     const visibility = override.visibility;
-    if (!shouldApplyName && !shouldApplyDescription && !visibility)
+    const communitySourceId = override.communitySourceId;
+    if (!shouldApplyName &&
+        !shouldApplyDescription &&
+        whenToUse === undefined &&
+        !visibility &&
+        !communitySourceId) {
         return app;
+    }
     return {
         ...app,
         ...(shouldApplyName ? { name } : {}),
         ...(shouldApplyDescription ? { description } : {}),
+        ...(whenToUse !== undefined ? { whenToUse } : {}),
         ...(visibility ? { visibility } : {}),
+        ...(communitySourceId ? { communitySourceId } : {}),
         ...(app.status === "pending" &&
             !app.createdBy &&
             (override.createdBy || override.updatedBy)
@@ -385,6 +463,11 @@ function normalizeWorkspaceAppTeams(value) {
 }
 function workspaceAppMetadataFromRecord(record) {
     const config = record["agent-native"] ?? record.agentNative;
+    const profile = parseAgentProfileMetadata({
+        whenToUse: config && typeof config === "object" && !Array.isArray(config)
+            ? config.whenToUse
+            : undefined,
+    });
     const workspaceConfig = config && typeof config === "object" && !Array.isArray(config)
         ? (config.workspaceApp ?? config.workspace ?? config)
         : {};
@@ -405,6 +488,7 @@ function workspaceAppMetadataFromRecord(record) {
         createdBy: pick(record.createdBy, record.createdByEmail, record.created_by, metadata.createdBy, metadata.createdByEmail, workspaceConfig.createdBy, workspaceConfig.createdByEmail),
         owner: pick(record.owner, record.ownerEmail, record.owner_email, metadata.owner, metadata.ownerEmail, workspaceConfig.owner, workspaceConfig.ownerEmail),
         teams,
+        ...(profile?.whenToUse ? { whenToUse: profile.whenToUse } : {}),
     };
 }
 function workspaceAppAudienceFromPackageJson(pkg) {
@@ -462,6 +546,11 @@ function parseWorkspaceAppsManifest(parsed) {
         const pathValue = typeof entry.path === "string" ? entry.path.trim() : "";
         if (!id || !pathValue.startsWith("/"))
             return null;
+        const profile = parseAgentProfileMetadata({
+            whenToUse: entry.whenToUse,
+        });
+        if (!profile)
+            return null;
         const metadata = workspaceAppMetadataFromRecord(entry);
         return {
             id,
@@ -469,6 +558,7 @@ function parseWorkspaceAppsManifest(parsed) {
                 ? entry.name.trim()
                 : titleCase(id),
             description: typeof entry.description === "string" ? entry.description : "",
+            ...(profile.whenToUse ? { whenToUse: profile.whenToUse } : {}),
             path: pathValue,
             homePath: normalizeWorkspaceAppHomePath(entry.homePath),
             url: workspaceAppLink(pathValue, entry.url),
@@ -571,6 +661,7 @@ function parsePendingWorkspaceApps(value) {
             return null;
         const now = new Date().toISOString();
         const createdAt = cleanOptionalString(record.createdAt) ?? now;
+        const communitySourceId = normalizeCommunitySourceId(record.communitySourceId);
         return {
             id,
             name: typeof record.name === "string" && record.name.trim()
@@ -600,6 +691,7 @@ function parsePendingWorkspaceApps(value) {
             ...(record.visibility === "private" || record.visibility === "org"
                 ? { visibility: record.visibility }
                 : {}),
+            ...(communitySourceId ? { communitySourceId } : {}),
             createdAt,
             updatedAt: typeof record.updatedAt === "string" && record.updatedAt.trim()
                 ? record.updatedAt.trim()
@@ -680,6 +772,7 @@ async function reservePendingWorkspaceApp(input) {
     const now = new Date().toISOString();
     const context = pendingWorkspaceAppContext();
     const creatorEmail = currentOwnerEmail();
+    const communitySourceId = normalizeCommunitySourceId(input.communitySourceId);
     await mutateSetting(scopedSettingsKey(), async (current) => {
         const raw = current && typeof current === "object" && !Array.isArray(current)
             ? current
@@ -709,6 +802,7 @@ async function reservePendingWorkspaceApp(input) {
             contextId: context?.id ?? null,
             contextLabel: context?.label ?? null,
             visibility: input.visibility,
+            ...(communitySourceId ? { communitySourceId } : {}),
             createdBy: creatorEmail,
             owner: creatorEmail,
             createdAt: now,
@@ -761,6 +855,7 @@ export async function archiveWorkspaceApp(input) {
     if (!current.includes(appId))
         current.push(appId);
     await putSetting(scopedSettingsKey(), { ...raw, archivedAppIds: current });
+    invalidateOrgAppsDirectoryCache();
     await recordAudit({
         action: "workspace-app.archived",
         targetType: "workspace-app",
@@ -776,6 +871,7 @@ export async function unarchiveWorkspaceApp(input) {
     const raw = await readSettingsRecord();
     const current = parseArchivedAppIds(raw.archivedAppIds).filter((id) => id !== appId);
     await putSetting(scopedSettingsKey(), { ...raw, archivedAppIds: current });
+    invalidateOrgAppsDirectoryCache();
     await recordAudit({
         action: "workspace-app.unarchived",
         targetType: "workspace-app",
@@ -818,6 +914,7 @@ function pendingAppToSummary(app) {
         status: "pending",
         statusLabel: "Pending Builder branch",
         visibility: app.visibility,
+        communitySourceId: app.communitySourceId,
         builderUrl: app.builderUrl,
         branchName: app.branchName,
         createdAt: app.createdAt,
@@ -1161,6 +1258,21 @@ async function filterWorkspaceAppsByAccess(apps) {
     }
     return apps.filter((app) => visibleIds.has(app.id));
 }
+async function filterOrganizationVisibleWorkspaceApps(apps, orgId) {
+    const readyApps = apps.filter((app) => app.status === "ready" && !app.archived);
+    const visibleIds = new Set();
+    const db = getDb();
+    for (let start = 0; start < readyApps.length; start += 500) {
+        const batch = readyApps.slice(start, start + 500);
+        const rows = await db
+            .select({ id: workspaceApps.id })
+            .from(workspaceApps)
+            .where(and(eq(workspaceApps.orgId, orgId), eq(workspaceApps.visibility, "org"), eq(workspaceApps.orgEnabled, true), inArray(workspaceApps.id, batch.map((app) => app.id))));
+        for (const row of rows)
+            visibleIds.add(row.id);
+    }
+    return readyApps.filter((app) => visibleIds.has(app.id));
+}
 async function recordPendingWorkspaceApp(input) {
     const now = new Date().toISOString();
     const context = pendingWorkspaceAppContext();
@@ -1174,6 +1286,8 @@ async function recordPendingWorkspaceApp(input) {
         .find(samePendingEntry);
     const creatorEmail = currentOwnerEmail();
     const existingOwnerEmail = existing?.createdBy ?? existing?.owner;
+    const communitySourceId = normalizeCommunitySourceId(input.communitySourceId) ??
+        normalizeCommunitySourceId(existing?.communitySourceId);
     if (existingOwnerEmail &&
         existingOwnerEmail.trim().toLowerCase() !== creatorEmail.toLowerCase()) {
         throw new Error(`Workspace app "${input.appId}" is already being created by another member.`);
@@ -1190,6 +1304,7 @@ async function recordPendingWorkspaceApp(input) {
         contextId: context?.id ?? null,
         contextLabel: context?.label ?? null,
         visibility: input.visibility,
+        ...(communitySourceId ? { communitySourceId } : {}),
         createdBy: existing?.createdBy ?? existing?.owner ?? creatorEmail,
         owner: existing?.owner ?? existing?.createdBy ?? creatorEmail,
         createdAt: existing?.createdAt || now,
@@ -1205,12 +1320,14 @@ async function recordPendingWorkspaceApp(input) {
     });
     await writeWorkspaceAppMetadataOverride({
         appId: input.appId,
+        name: null,
         description: input.description,
         generated: true,
         sourcePrompt: input.sourcePrompt,
         updatedBy: creatorEmail,
         createdBy: next.createdBy,
         visibility: input.visibility,
+        communitySourceId,
     });
     await recordAudit({
         action: "workspace-app.pending",
@@ -1495,6 +1612,10 @@ export async function updateWorkspaceAppMetadata(input) {
     const appId = input.appId.trim();
     assertValidWorkspaceAppId(appId);
     requireWorkspaceAppOrgId();
+    const role = await requestOwnerRole();
+    if (role !== "owner" && role !== "admin") {
+        throw new WorkspaceAppMetadataAuthorizationError();
+    }
     const apps = await listWorkspaceApps({
         includeAgentCards: false,
         includeArchived: true,
@@ -1502,34 +1623,54 @@ export async function updateWorkspaceAppMetadata(input) {
     const app = apps.find((candidate) => candidate.id === appId);
     if (!app)
         throw new Error(`Workspace app "${appId}" was not found.`);
-    const name = input.name == null ? app.name : input.name.trim();
-    const description = input.description == null
-        ? (app.description ?? undefined)
-        : input.description.trim();
-    await writeWorkspaceAppMetadataOverride({
+    const nameProvided = Object.hasOwn(input, "name") && input.name !== undefined;
+    const descriptionProvided = Object.hasOwn(input, "description") && input.description !== undefined;
+    const whenToUseProvided = Object.hasOwn(input, "whenToUse") && input.whenToUse !== undefined;
+    const name = nameProvided ? (input.name?.trim() ?? null) : app.name;
+    const description = descriptionProvided
+        ? (input.description?.trim() ?? null)
+        : (app.description ?? undefined);
+    const whenToUse = whenToUseProvided ? (input.whenToUse ?? []) : app.whenToUse;
+    const metadataOverride = {
         appId,
-        name,
-        description,
-        generated: false,
         updatedBy: currentOwnerEmail(),
+    };
+    if (nameProvided)
+        metadataOverride.name = input.name?.trim() ?? null;
+    if (descriptionProvided) {
+        metadataOverride.description = input.description?.trim() ?? null;
+    }
+    if (whenToUseProvided)
+        metadataOverride.whenToUse = input.whenToUse ?? [];
+    if (nameProvided || descriptionProvided)
+        metadataOverride.generated = false;
+    await writeWorkspaceAppMetadataOverride({
+        ...metadataOverride,
     });
+    invalidateOrgAppsDirectoryCache();
     await recordAudit({
         action: "workspace-app.metadata-updated",
         targetType: "workspace-app",
         targetId: appId,
-        summary: `Updated workspace app details for ${name}`,
+        summary: `Updated workspace app details for ${name ?? app.name}`,
         metadata: {
-            name,
+            name: name ?? app.name,
             descriptionConfigured: !!description,
+            whenToUseCount: whenToUse?.length ?? 0,
         },
     });
     const updated = (await listWorkspaceApps({
         includeAgentCards: false,
         includeArchived: true,
     })).find((candidate) => candidate.id === appId);
-    return updated ?? { ...app, name, description };
+    return (updated ?? {
+        ...app,
+        name: name ?? app.name,
+        description: description ?? app.description,
+        whenToUse,
+    });
 }
-export async function listWorkspaceApps(options = {}) {
+async function listWorkspaceAppsWithPrincipal(options = {}, principal = "user") {
     const finalize = async (apps, { persist = true } = {}) => {
         const annotated = await applyArchivedAndPending(apps);
         const recorded = await ensureWorkspaceAppRecords(annotated, {
@@ -1538,7 +1679,10 @@ export async function listWorkspaceApps(options = {}) {
         const listed = options.includeArchived
             ? recorded
             : recorded.filter((app) => !app.archived);
-        const visible = await filterWorkspaceAppsByAccess(filterAppsByAudience(listed, options.audience));
+        const candidates = filterAppsByAudience(listed, options.audience);
+        const visible = principal === "organization"
+            ? await filterOrganizationVisibleWorkspaceApps(candidates, requireWorkspaceAppOrgId())
+            : await filterWorkspaceAppsByAccess(candidates);
         return maybeIncludeAgentCards(visible, options);
     };
     let gatewayDenial = null;
@@ -1598,6 +1742,13 @@ export async function listWorkspaceApps(options = {}) {
         return finalize(apps, { persist: !unverified });
     return finalize([], { persist: !unverified });
 }
+export function listWorkspaceApps(options = {}) {
+    return listWorkspaceAppsWithPrincipal(options, "user");
+}
+export async function listOrganizationVisibleWorkspaceApps() {
+    requireWorkspaceAppOrgId();
+    return listWorkspaceAppsWithPrincipal({ includeAgentCards: false, includeArchived: false, audience: "all" }, "organization");
+}
 const ADDABLE_TEMPLATES = [
     {
         name: "mail",
@@ -1748,6 +1899,8 @@ export async function scaffoldWorkspaceAppFromTemplate(input) {
     try {
         await writeWorkspaceAppMetadataOverride({
             appId,
+            name: null,
+            description: null,
             updatedBy: creatorEmail,
             createdBy: creatorEmail,
             visibility,
@@ -1783,6 +1936,7 @@ export async function scaffoldWorkspaceAppFromTemplate(input) {
             visibility,
         },
     ]);
+    invalidateOrgAppsDirectoryCache();
     return { appId, template, output };
 }
 function runScaffoldCli(input) {
@@ -1945,8 +2099,8 @@ async function requestOwnerRole() {
         const role = rows[0]?.role;
         return typeof role === "string" ? role : null;
     }
-    catch {
-        return null;
+    catch (error) {
+        throw new AppCreationOwnerRoleUnavailableError(error);
     }
 }
 async function assertCanManageAppCreationSettings() {
@@ -2198,6 +2352,10 @@ export async function startWorkspaceAppCreation(input) {
         description: input.description,
         template: input.template,
     });
+    if (input.communitySourceId !== undefined &&
+        !normalizeCommunitySourceId(input.communitySourceId)) {
+        throw new Error("Community source ids must be valid bounded identifiers.");
+    }
     assertValidWorkspaceAppId(initial.appId);
     requireWorkspaceAppOrgId();
     normalizeBuilderAgentAttachments(input.attachments);
@@ -2244,15 +2402,41 @@ export async function startWorkspaceAppCreation(input) {
     const appDescription = input.description?.trim() ||
         generateWorkspaceAppDescription(input.prompt, built.appId);
     if (isLocal) {
-        await writeWorkspaceAppMetadataOverride({
-            appId: built.appId,
-            description: appDescription,
-            generated: true,
-            sourcePrompt: input.prompt,
-            updatedBy: currentOwnerEmail(),
-            createdBy: currentOwnerEmail(),
-            visibility: creationVisibility,
-        });
+        if (input.communitySourceId) {
+            try {
+                await reservePendingWorkspaceApp({
+                    appId: built.appId,
+                    description: appDescription,
+                    projectId: null,
+                    visibility: creationVisibility,
+                    communitySourceId: input.communitySourceId,
+                });
+            }
+            catch (err) {
+                if (err instanceof WorkspaceAppIdTakenError)
+                    return appIdTakenResult(err);
+                throw err;
+            }
+        }
+        try {
+            await writeWorkspaceAppMetadataOverride({
+                appId: built.appId,
+                name: null,
+                description: appDescription,
+                generated: true,
+                sourcePrompt: input.prompt,
+                updatedBy: currentOwnerEmail(),
+                createdBy: currentOwnerEmail(),
+                visibility: creationVisibility,
+                communitySourceId: input.communitySourceId,
+            });
+        }
+        catch (error) {
+            if (input.communitySourceId) {
+                await releasePendingWorkspaceAppReservation(built.appId);
+            }
+            throw error;
+        }
         await requestSelectedVaultKeys({
             appId: built.appId,
             selectedKeys,
@@ -2265,6 +2449,20 @@ export async function startWorkspaceAppCreation(input) {
             mode: "local-agent",
             appId: built.appId,
             prompt,
+            ...(input.communitySourceId && input.attachments?.length
+                ? {
+                    attachments: input.attachments.flatMap((attachment) => attachment.type === "upload" && attachment.text !== undefined
+                        ? [
+                            {
+                                type: "file",
+                                name: attachment.name,
+                                contentType: attachment.contentType,
+                                text: attachment.text,
+                            },
+                        ]
+                        : []),
+                }
+                : {}),
             message: "Use the local code agent to create this app in the workspace, then open it from /dispatch/apps.",
         };
     }
@@ -2300,6 +2498,9 @@ export async function startWorkspaceAppCreation(input) {
             description: appDescription,
             projectId: builderProjectId,
             visibility: creationVisibility,
+            ...(normalizeCommunitySourceId(input.communitySourceId)
+                ? { communitySourceId: input.communitySourceId }
+                : {}),
         });
     }
     catch (err) {
@@ -2307,6 +2508,23 @@ export async function startWorkspaceAppCreation(input) {
             return appIdTakenResult(err);
         throw err;
     }
+    if (input.communitySourceId) {
+        try {
+            await writeWorkspaceAppMetadataOverride({
+                appId: built.appId,
+                communitySourceId: input.communitySourceId,
+            });
+        }
+        catch (error) {
+            try {
+                await releasePendingWorkspaceAppReservation(built.appId);
+            }
+            catch (cleanupError) {
+                console.warn("[dispatch] failed to release pending workspace app reservation", cleanupError);
+            }
+            throw error;
+        }
+    }
     let result;
     try {
         result = normalizeBuilderRunResult(await runBuilderAgent({
@@ -2337,6 +2555,7 @@ export async function startWorkspaceAppCreation(input) {
         description: appDescription,
         sourcePrompt: input.prompt,
         visibility: creationVisibility,
+        communitySourceId: input.communitySourceId,
         branchName: result.branchName,
         builderUrl: result.url,
     });