@agent-native/dispatch 0.40.30-nightly-20261021093329 → 0.40.31

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

@@ -2,28 +2,31 @@ import { spawn } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { canonicalA2AAudience, signA2AToken } from "@agent-native/core/a2a";
-import { isActionContractError } from "@agent-native/core/action";
+import { canonicalA2AAudience, getGlobalA2ASecret, signA2AToken, } from "@agent-native/core/a2a";
+import { ActionContractError, 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 { getOrgA2ASecret, 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() {
@@ -70,13 +89,11 @@ function requireWorkspaceAppOrgId() {
         throw new WorkspaceAppOrgRequiredError();
     return orgId;
 }
-class WorkspaceAppsGatewayAuthorizationError extends Error {
-    constructor(statusCode, message = `Workspace apps gateway rejected the request with HTTP ${statusCode}.`) {
-        super(message);
+class WorkspaceAppsGatewayAuthorizationError extends ActionContractError {
+    constructor(statusCode, errorCode = "workspace_gateway_rejected", message = `Workspace apps gateway rejected the request with HTTP ${statusCode}.`) {
+        super(message, { statusCode, errorCode });
         this.name = "WorkspaceAppsGatewayAuthorizationError";
-        this.statusCode = statusCode;
     }
-    statusCode;
 }
 function warnWorkspaceAppsGatewayDenial(denial, source) {
     if (!denial)
@@ -189,7 +206,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 +214,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 +239,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 +266,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 +277,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 +335,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 +355,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 +461,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 +486,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 +544,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 +556,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),
@@ -491,6 +579,20 @@ function parseWorkspaceAppsManifest(parsed) {
         .sort(sortWorkspaceApps);
     return apps.length ? apps : null;
 }
+function parseWorkspaceAppsGatewayResponse(parsed) {
+    const rawApps = parsed && typeof parsed === "object" && !Array.isArray(parsed)
+        ? parsed.apps
+        : parsed;
+    if (!Array.isArray(rawApps))
+        return null;
+    if (rawApps.length === 0)
+        return [];
+    const apps = parseWorkspaceAppsManifest(parsed);
+    if (!apps || apps.length !== rawApps.length)
+        return null;
+    const ids = new Set(apps.map((app) => app.id.toLowerCase()));
+    return ids.size === apps.length ? apps : null;
+}
 function parseDateMs(value) {
     if (!value)
         return null;
@@ -571,6 +673,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 +703,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 +784,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 +814,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 +867,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 +883,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 +926,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 +1270,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 +1298,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 +1316,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 +1332,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",
@@ -1254,27 +1383,64 @@ async function readWorkspaceAppsFromGateway() {
         return null;
     }
     const requestContext = getRequestContext();
+    const isLocalGateway = isLocalWorkspaceGateway(baseUrl);
+    const requestOrigin = requestContext?.requestOrigin;
+    const isSameOriginGateway = requestOrigin
+        ? (() => {
+            try {
+                return new URL(requestOrigin).origin === baseUrl.origin;
+            }
+            catch {
+                // coercion-ok: an invalid request origin cannot prove a self-fetch.
+                return false;
+            }
+        })()
+        : false;
+    if (isSameOriginGateway && !isLocalGateway)
+        return null;
     const authHeaders = {};
     if (requestContext?.userEmail) {
-        const orgDomain = requestContext.orgId
-            ? (await getOrgDomain(requestContext.orgId))?.trim().toLowerCase()
-            : undefined;
+        let orgDomain;
+        let orgSecret;
+        if (requestContext.orgId) {
+            try {
+                orgDomain =
+                    (await getOrgDomain(requestContext.orgId))?.trim().toLowerCase() ||
+                        undefined;
+            }
+            catch {
+                throw new WorkspaceAppsGatewayAuthorizationError(503, "workspace_gateway_org_domain_unavailable", "Workspace apps gateway organization domain could not be read.");
+            }
+        }
         if (requestContext.orgId && !orgDomain) {
-            throw new WorkspaceAppsGatewayAuthorizationError(401, "Workspace apps gateway cannot authenticate without a resolved organization domain.");
+            throw new WorkspaceAppsGatewayAuthorizationError(401, "workspace_gateway_org_domain_missing", "Workspace apps gateway cannot authenticate without a resolved organization domain.");
         }
-        try {
-            const token = await signA2AToken(requestContext.userEmail, orgDomain, undefined, {
-                expiresIn: "1m",
-                preferGlobalSecret: true,
-                audience: canonicalA2AAudience(baseUrl.toString(), getConfiguredAppBasePath() || undefined),
-            });
-            authHeaders.Authorization = `Bearer ${token}`;
+        if (requestContext.orgId) {
+            try {
+                orgSecret =
+                    (await getOrgA2ASecret(requestContext.orgId))?.trim() || undefined;
+            }
+            catch {
+                throw new WorkspaceAppsGatewayAuthorizationError(503, "workspace_gateway_org_a2a_secret_unavailable", "Workspace apps gateway organization A2A secret could not be read.");
+            }
         }
-        catch {
-            // coercion-ok: absent signing credentials keep local unauthenticated
-            // gateway discovery available and make hosted discovery fail closed.
-            // Keep the unauthenticated local-dev gateway path available. A hosted
-            // gateway will fail closed below when its action route needs identity.
+        const globalSecret = getGlobalA2ASecret();
+        const allowLocalUnauthenticatedRequest = isLocalGateway && !orgSecret && !globalSecret;
+        if (!orgSecret && !globalSecret && !allowLocalUnauthenticatedRequest) {
+            throw new WorkspaceAppsGatewayAuthorizationError(503, "workspace_gateway_a2a_secret_missing", "Workspace apps gateway cannot authenticate because no A2A secret is configured.");
+        }
+        if (!allowLocalUnauthenticatedRequest) {
+            try {
+                const token = await signA2AToken(requestContext.userEmail, orgDomain, orgSecret, {
+                    expiresIn: "1m",
+                    preferGlobalSecret: false,
+                    audience: canonicalA2AAudience(baseUrl.toString(), getConfiguredAppBasePath() || undefined),
+                });
+                authHeaders.Authorization = `Bearer ${token}`;
+            }
+            catch {
+                throw new WorkspaceAppsGatewayAuthorizationError(503, "workspace_gateway_token_signing_failed", "Workspace apps gateway could not sign the authenticated request.");
+            }
         }
     }
     const controller = new AbortController();
@@ -1296,36 +1462,46 @@ async function readWorkspaceAppsFromGateway() {
     const protectedRedirect = protectionHeaders["x-vercel-protection-bypass"]
         ? { redirect: "manual" }
         : {};
+    const readAppsResponse = async (response) => {
+        let payload;
+        try {
+            payload = await response.json();
+        }
+        catch {
+            throw new ActionContractError("Workspace apps gateway returned an unreadable response.", {
+                statusCode: 503,
+                errorCode: "workspace_gateway_invalid_response",
+            });
+        }
+        const apps = parseWorkspaceAppsGatewayResponse(payload);
+        if (!apps) {
+            throw new ActionContractError("Workspace apps gateway returned an invalid response.", {
+                statusCode: 503,
+                errorCode: "workspace_gateway_invalid_response",
+            });
+        }
+        return { apps };
+    };
     try {
-        if (isLocalWorkspaceGateway(baseUrl)) {
+        if (isLocalGateway) {
             const localResponse = await fetch(gatewayUrl(WORKSPACE_APPS_GATEWAY_PATH), {
                 headers,
                 ...protectedRedirect,
                 signal: controller.signal,
             });
             if (localResponse.status === 401 || localResponse.status === 403) {
-                throw new WorkspaceAppsGatewayAuthorizationError(localResponse.status);
+                throw new WorkspaceAppsGatewayAuthorizationError(localResponse.status, "workspace_gateway_rejected");
             }
-            if (localResponse.ok) {
-                const apps = parseWorkspaceAppsManifest(
-                // coercion-ok: malformed gateway JSON is an unavailable registry and
-                // must fall through to the local manifest sources.
-                await localResponse.json().catch(() => null));
-                return apps ? { apps } : null;
+            if (localResponse.status !== 404 && localResponse.status !== 200) {
+                throw new ActionContractError(`Workspace apps gateway returned HTTP ${localResponse.status}.`, {
+                    statusCode: 503,
+                    errorCode: `workspace_gateway_http_${localResponse.status}`,
+                });
+            }
+            if (localResponse.status === 200) {
+                return await readAppsResponse(localResponse);
             }
         }
-        const requestOrigin = requestContext?.requestOrigin;
-        const isSameOriginGateway = requestOrigin
-            ? (() => {
-                try {
-                    return new URL(requestOrigin).origin === baseUrl.origin;
-                }
-                catch {
-                    // coercion-ok: an invalid request origin cannot prove a self-fetch.
-                    return false;
-                }
-            })()
-            : false;
         if (isSameOriginGateway || !authHeaders.Authorization)
             return null;
         const actionUrl = gatewayUrl(WORKSPACE_APPS_ACTION_PATH);
@@ -1337,20 +1513,25 @@ async function readWorkspaceAppsFromGateway() {
             signal: controller.signal,
         });
         if (actionResponse.status === 401 || actionResponse.status === 403) {
-            throw new WorkspaceAppsGatewayAuthorizationError(actionResponse.status);
+            throw new WorkspaceAppsGatewayAuthorizationError(actionResponse.status, "workspace_gateway_rejected");
         }
-        if (!actionResponse.ok)
+        if (actionResponse.status === 404)
             return null;
-        const apps = parseWorkspaceAppsManifest(
-        // coercion-ok: malformed gateway JSON is an unavailable registry and
-        // must fall through to the local manifest sources.
-        await actionResponse.json().catch(() => null));
-        return apps ? { apps } : null;
+        if (actionResponse.status !== 200) {
+            throw new ActionContractError(`Workspace apps gateway returned HTTP ${actionResponse.status}.`, {
+                statusCode: 503,
+                errorCode: `workspace_gateway_http_${actionResponse.status}`,
+            });
+        }
+        return await readAppsResponse(actionResponse);
     }
     catch (error) {
-        if (error instanceof WorkspaceAppsGatewayAuthorizationError)
+        if (error instanceof ActionContractError)
             throw error;
-        return null;
+        throw new ActionContractError("Workspace apps gateway could not be reached.", {
+            statusCode: 503,
+            errorCode: "workspace_gateway_unavailable",
+        });
     }
     finally {
         clearTimeout(timeout);
@@ -1495,6 +1676,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 +1687,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 +1743,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;
@@ -1554,6 +1762,9 @@ export async function listWorkspaceApps(options = {}) {
     if (gatewayApps) {
         return finalize(gatewayApps.apps);
     }
+    if (gatewayDenial && gatewayDenial.statusCode >= 500) {
+        throw gatewayDenial;
+    }
     const unverified = gatewayDenial !== null;
     const workspaceRoot = findWorkspaceRoot();
     const localFilesystemApps = workspaceRoot && isLocalAppCreationRuntime()
@@ -1573,8 +1784,9 @@ export async function listWorkspaceApps(options = {}) {
     // means the registry will not show this reader its apps, so they get the
     // deployment's own list instead, and none of it is recorded. (A manifest
     // answers earlier for both, with the warning above.)
-    if (gatewayDenial?.statusCode === 401)
+    if (gatewayDenial && gatewayDenial.statusCode !== 403) {
         throw gatewayDenial;
+    }
     warnWorkspaceAppsGatewayDenial(gatewayDenial, "deployment's own app list");
     if (!workspaceRoot) {
         return finalize([
@@ -1598,6 +1810,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 +1967,8 @@ export async function scaffoldWorkspaceAppFromTemplate(input) {
     try {
         await writeWorkspaceAppMetadataOverride({
             appId,
+            name: null,
+            description: null,
             updatedBy: creatorEmail,
             createdBy: creatorEmail,
             visibility,
@@ -1783,6 +2004,7 @@ export async function scaffoldWorkspaceAppFromTemplate(input) {
             visibility,
         },
     ]);
+    invalidateOrgAppsDirectoryCache();
     return { appId, template, output };
 }
 function runScaffoldCli(input) {
@@ -1945,8 +2167,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 +2420,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 +2470,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 +2517,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 +2566,9 @@ export async function startWorkspaceAppCreation(input) {
             description: appDescription,
             projectId: builderProjectId,
             visibility: creationVisibility,
+            ...(normalizeCommunitySourceId(input.communitySourceId)
+                ? { communitySourceId: input.communitySourceId }
+                : {}),
         });
     }
     catch (err) {
@@ -2307,6 +2576,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 +2623,7 @@ export async function startWorkspaceAppCreation(input) {
         description: appDescription,
         sourcePrompt: input.prompt,
         visibility: creationVisibility,
+        communitySourceId: input.communitySourceId,
         branchName: result.branchName,
         builderUrl: result.url,
     });