@agent-native/dispatch 0.6.1 → 0.8.0

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

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { getSetting, putSetting } from "@agent-native/core/settings";
+import { assertValidWorkspaceAppId } from "@agent-native/core/shared";
 import {
   getBuilderBranchProjectId,
   getRequestContext,
@@ -12,7 +13,6 @@ import {
   runBuilderAgent,
 } from "@agent-native/core/server";
 import { getDbExec } from "@agent-native/core/db";
-import { assertValidWorkspaceAppId } from "@agent-native/core/shared";
 import {
   currentOrgId,
   currentOwnerEmail,
@@ -28,6 +28,7 @@ import {
 } from "./workspace-resources-store.js";
 
 const SETTINGS_KEY = "dispatch-app-creation-settings";
+const WORKSPACE_APP_METADATA_SETTINGS_KEY = "workspace-app-metadata";
 const WORKSPACE_APPS_ENV_KEY = "AGENT_NATIVE_WORKSPACE_APPS_JSON";
 const WORKSPACE_APPS_MANIFEST_FILE = "workspace-apps.json";
 const WORKSPACE_APPS_GATEWAY_PATH = "/_workspace/apps";
@@ -35,6 +36,9 @@ const WORKSPACE_APPS_GATEWAY_TIMEOUT_MS = 1_000;
 const MAX_PENDING_APPS = 50;
 const AGENT_CARD_PATH = "/.well-known/agent-card.json";
 const AGENT_CARD_FETCH_TIMEOUT_MS = 1_500;
+const DEFAULT_WORKSPACE_APP_AUDIENCE = "internal";
+
+type WorkspaceAppAudience = "internal" | "public";
 
 export interface WorkspaceAppSummary {
   id: string;
@@ -43,6 +47,9 @@ export interface WorkspaceAppSummary {
   path: string;
   url: string | null;
   isDispatch: boolean;
+  audience: WorkspaceAppAudience;
+  publicPaths: string[];
+  protectedPaths: string[];
   status?: "ready" | "pending";
   statusLabel?: string;
   builderUrl?: string | null;
@@ -64,6 +71,7 @@ export interface ListWorkspaceAppsOptions {
    * when rendering the "Hidden apps" expander.
    */
   includeArchived?: boolean;
+  audience?: WorkspaceAppAudience | "all";
 }
 
 export interface AvailableWorkspaceTemplate {
@@ -103,10 +111,24 @@ interface PendingWorkspaceApp {
   builderUrl: string | null;
   branchName: string | null;
   projectId: string | null;
+  audience?: WorkspaceAppAudience;
   createdAt: string;
   updatedAt: string;
 }
 
+interface WorkspaceAppMetadataOverride {
+  name?: string;
+  description?: string;
+  generated?: boolean;
+  sourcePrompt?: string;
+  updatedAt?: string;
+  updatedBy?: string;
+}
+
+interface WorkspaceAppMetadataSettings {
+  apps: Record<string, WorkspaceAppMetadataOverride>;
+}
+
 function readJson(file: string): any {
   try {
     return JSON.parse(fs.readFileSync(file, "utf8"));
@@ -137,12 +159,56 @@ function titleCase(value: string): string {
     .join(" ");
 }
 
+function normalizeWhitespace(value: string): string {
+  return value.replace(/\s+/g, " ").trim();
+}
+
+function ensureSentence(value: string): string {
+  if (!value) return value;
+  const capitalized = value.charAt(0).toUpperCase() + value.slice(1);
+  return /[.!?]$/.test(capitalized) ? capitalized : `${capitalized}.`;
+}
+
+function clipSentence(value: string, max = 180): string {
+  if (value.length <= max) return value;
+  const clipped = value
+    .slice(0, max - 1)
+    .replace(/\s+\S*$/, "")
+    .trim();
+  return `${clipped || value.slice(0, max - 1).trim()}…`;
+}
+
+export function generateWorkspaceAppDescription(
+  prompt: string,
+  appId: string,
+): string {
+  const cleaned = normalizeWhitespace(prompt)
+    .replace(
+      /^(please\s+)?(build|create|make|generate|scaffold)\s+(me\s+|us\s+)?/i,
+      "",
+    )
+    .replace(
+      /^(an?\s+)?(workspace\s+)?(agent-native\s+)?(app|tool)\s+(that|to|for)\s+/i,
+      "",
+    )
+    .replace(/^(an?\s+)?(dashboard|workspace|agent)\s+(that|to|for)\s+/i, "");
+
+  if (!cleaned) return `Workspace app for ${titleCase(appId)}.`;
+  return clipSentence(ensureSentence(cleaned));
+}
+
 function scopedSettingsKey(): string {
   const orgId = currentOrgId();
   if (orgId) return `${SETTINGS_KEY}:org:${orgId}`;
   return `${SETTINGS_KEY}:user:${currentOwnerEmail()}`;
 }
 
+function workspaceAppMetadataSettingsKey(): string {
+  const orgId = currentOrgId();
+  if (orgId) return `${WORKSPACE_APP_METADATA_SETTINGS_KEY}:org:${orgId}`;
+  return `${WORKSPACE_APP_METADATA_SETTINGS_KEY}:user:${currentOwnerEmail()}`;
+}
+
 async function readSettingsRecord(): Promise<Record<string, any>> {
   const raw = await getSetting(scopedSettingsKey()).catch(() => null);
   return raw && typeof raw === "object" && !Array.isArray(raw)
@@ -150,6 +216,114 @@ async function readSettingsRecord(): Promise<Record<string, any>> {
     : {};
 }
 
+function cleanOptionalText(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function parseWorkspaceAppMetadataSettings(
+  raw: unknown,
+): WorkspaceAppMetadataSettings {
+  const record =
+    raw && typeof raw === "object" && !Array.isArray(raw)
+      ? (raw as Record<string, unknown>)
+      : {};
+  const rawApps =
+    record.apps &&
+    typeof record.apps === "object" &&
+    !Array.isArray(record.apps)
+      ? (record.apps as Record<string, unknown>)
+      : {};
+  const apps: Record<string, WorkspaceAppMetadataOverride> = {};
+
+  for (const [id, value] of Object.entries(rawApps)) {
+    if (!id.trim() || !value || typeof value !== "object") continue;
+    const item = value as Record<string, unknown>;
+    const override: WorkspaceAppMetadataOverride = {};
+    const name = cleanOptionalText(item.name);
+    const description = cleanOptionalText(item.description);
+    const sourcePrompt = cleanOptionalText(item.sourcePrompt);
+    const updatedAt = cleanOptionalText(item.updatedAt);
+    const updatedBy = cleanOptionalText(item.updatedBy);
+
+    if (name) override.name = name;
+    if (description) override.description = description;
+    if (item.generated === true) override.generated = true;
+    if (sourcePrompt) override.sourcePrompt = sourcePrompt;
+    if (updatedAt) override.updatedAt = updatedAt;
+    if (updatedBy) override.updatedBy = updatedBy;
+
+    if (Object.keys(override).length > 0) apps[id.trim()] = override;
+  }
+
+  return { apps };
+}
+
+async function readWorkspaceAppMetadataSettings(): Promise<WorkspaceAppMetadataSettings> {
+  const raw = await getSetting(workspaceAppMetadataSettingsKey()).catch(
+    () => null,
+  );
+  return parseWorkspaceAppMetadataSettings(raw);
+}
+
+async function writeWorkspaceAppMetadataOverride(input: {
+  appId: string;
+  name?: string | null;
+  description?: string | null;
+  generated?: boolean;
+  sourcePrompt?: string | null;
+  updatedBy?: string | null;
+}): Promise<WorkspaceAppMetadataSettings> {
+  const key = workspaceAppMetadataSettingsKey();
+  const current = parseWorkspaceAppMetadataSettings(
+    await getSetting(key).catch(() => null),
+  );
+  const appId = input.appId.trim();
+  const existing = current.apps[appId] ?? {};
+  const next: WorkspaceAppMetadataOverride = {
+    ...existing,
+    updatedAt: new Date().toISOString(),
+  };
+  const name = cleanOptionalText(input.name);
+  const description = cleanOptionalText(input.description);
+  const sourcePrompt = cleanOptionalText(input.sourcePrompt);
+  const updatedBy = cleanOptionalText(input.updatedBy);
+
+  if (name) next.name = name;
+  else delete next.name;
+  if (description) next.description = description;
+  else delete next.description;
+  if (input.generated === true) next.generated = true;
+  else if (input.generated === false) delete next.generated;
+  if (sourcePrompt) next.sourcePrompt = sourcePrompt;
+  if (updatedBy) next.updatedBy = updatedBy;
+
+  current.apps[appId] = next;
+  await putSetting(key, { apps: current.apps });
+  return current;
+}
+
+function applyWorkspaceAppMetadataOverride(
+  app: WorkspaceAppSummary,
+  settings: WorkspaceAppMetadataSettings,
+): WorkspaceAppSummary {
+  const override = settings.apps[app.id];
+  if (!override) return app;
+
+  const name = cleanOptionalText(override.name);
+  const description = cleanOptionalText(override.description);
+  const generated = override.generated === true;
+  const shouldApplyName = !!name && !generated;
+  const shouldApplyDescription =
+    !!description && (!generated || !cleanOptionalText(app.description));
+  if (!shouldApplyName && !shouldApplyDescription) return app;
+
+  return {
+    ...app,
+    ...(shouldApplyName ? { name } : {}),
+    ...(shouldApplyDescription ? { description } : {}),
+  };
+}
+
 function workspaceAppUrl(appPath: string): string | null {
   const base =
     process.env.WORKSPACE_GATEWAY_URL ||
@@ -180,6 +354,85 @@ function workspaceAppLink(
   }
 }
 
+function normalizeWorkspaceAppAudience(value: unknown): WorkspaceAppAudience {
+  return value === "public" ? "public" : DEFAULT_WORKSPACE_APP_AUDIENCE;
+}
+
+function normalizeWorkspaceAppPathList(value: unknown): string[] {
+  let rawPaths: unknown[] = [];
+  if (Array.isArray(value)) {
+    rawPaths = value;
+  } else if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (!trimmed) return [];
+    try {
+      const parsed = JSON.parse(trimmed);
+      rawPaths = Array.isArray(parsed) ? parsed : [trimmed];
+    } catch {
+      rawPaths = trimmed.split(",");
+    }
+  }
+
+  const paths = rawPaths
+    .map((entry) => (typeof entry === "string" ? entry.trim() : ""))
+    .filter((entry) => entry.startsWith("/"))
+    .map((entry) =>
+      entry.length > 1 && entry.endsWith("/") ? entry.slice(0, -1) : entry,
+    );
+  return Array.from(new Set(paths));
+}
+
+function workspaceAppAudienceFromPackageJson(
+  pkg: unknown,
+): WorkspaceAppAudience | undefined {
+  if (!pkg || typeof pkg !== "object" || Array.isArray(pkg)) return undefined;
+  const record = pkg as Record<string, any>;
+  const config = record["agent-native"] ?? record.agentNative;
+  const nested =
+    config && typeof config === "object" && !Array.isArray(config)
+      ? (config as Record<string, any>)
+      : {};
+  const raw =
+    nested.workspaceApp?.audience ??
+    nested.workspace?.audience ??
+    nested.audience ??
+    record.workspaceAppAudience;
+  if (raw === undefined) return undefined;
+  return normalizeWorkspaceAppAudience(raw);
+}
+
+function workspaceAppRouteAccessFromPackageJson(pkg: unknown): {
+  publicPaths: string[];
+  protectedPaths: string[];
+} {
+  if (!pkg || typeof pkg !== "object" || Array.isArray(pkg)) {
+    return { publicPaths: [], protectedPaths: [] };
+  }
+  const record = pkg as Record<string, any>;
+  const config = record["agent-native"] ?? record.agentNative;
+  const nested =
+    config && typeof config === "object" && !Array.isArray(config)
+      ? (config as Record<string, any>)
+      : {};
+  return {
+    publicPaths: normalizeWorkspaceAppPathList(
+      nested.workspaceApp?.publicPaths ??
+        nested.workspaceApp?.publicPagePaths ??
+        nested.workspace?.publicPaths ??
+        nested.publicPaths ??
+        record.workspaceAppPublicPaths,
+    ),
+    protectedPaths: normalizeWorkspaceAppPathList(
+      nested.workspaceApp?.protectedPaths ??
+        nested.workspaceApp?.privatePaths ??
+        nested.workspaceApp?.authRequiredPaths ??
+        nested.workspace?.protectedPaths ??
+        nested.protectedPaths ??
+        record.workspaceAppProtectedPaths,
+    ),
+  };
+}
+
 function parseWorkspaceAppsManifest(parsed: any): WorkspaceAppSummary[] | null {
   const rawApps = Array.isArray(parsed?.apps)
     ? parsed.apps
@@ -208,6 +461,12 @@ function parseWorkspaceAppsManifest(parsed: any): WorkspaceAppSummary[] | null {
           typeof entry.isDispatch === "boolean"
             ? entry.isDispatch
             : id === "dispatch",
+        audience:
+          entry.audience === undefined
+            ? DEFAULT_WORKSPACE_APP_AUDIENCE
+            : normalizeWorkspaceAppAudience(entry.audience),
+        publicPaths: normalizeWorkspaceAppPathList(entry.publicPaths),
+        protectedPaths: normalizeWorkspaceAppPathList(entry.protectedPaths),
         status: "ready",
       } satisfies WorkspaceAppSummary;
     })
@@ -228,7 +487,7 @@ function sortWorkspaceApps(a: WorkspaceAppSummary, b: WorkspaceAppSummary) {
 function parsePendingWorkspaceApps(value: unknown): PendingWorkspaceApp[] {
   if (!Array.isArray(value)) return [];
   return value
-    .map((entry) => {
+    .map((entry): PendingWorkspaceApp | null => {
       if (!entry || typeof entry !== "object") return null;
       const record = entry as Record<string, unknown>;
       const id = typeof record.id === "string" ? record.id.trim() : "";
@@ -259,6 +518,9 @@ function parsePendingWorkspaceApps(value: unknown): PendingWorkspaceApp[] {
           typeof record.projectId === "string" && record.projectId.trim()
             ? record.projectId.trim()
             : null,
+        ...(record.audience === undefined
+          ? {}
+          : { audience: normalizeWorkspaceAppAudience(record.audience) }),
         createdAt:
           typeof record.createdAt === "string" && record.createdAt.trim()
             ? record.createdAt.trim()
@@ -356,6 +618,9 @@ function pendingAppToSummary(app: PendingWorkspaceApp): WorkspaceAppSummary {
     path: app.path,
     url: app.builderUrl,
     isDispatch: false,
+    audience: app.audience ?? DEFAULT_WORKSPACE_APP_AUDIENCE,
+    publicPaths: [],
+    protectedPaths: [],
     status: "pending",
     statusLabel: "Building in Builder",
     builderUrl: app.builderUrl,
@@ -494,6 +759,8 @@ async function maybeIncludeAgentCards(
 async function recordPendingWorkspaceApp(input: {
   appId: string;
   projectId: string | null;
+  description: string;
+  sourcePrompt: string;
   branchName?: string | null;
   builderUrl?: string | null;
 }) {
@@ -505,6 +772,7 @@ async function recordPendingWorkspaceApp(input: {
     id: input.appId,
     name: titleCase(input.appId),
     description:
+      input.description ||
       "Builder is creating this app. The workspace path becomes live after the branch is merged and deployed.",
     path: `/${input.appId}`,
     builderUrl: input.builderUrl?.trim() || null,
@@ -522,6 +790,14 @@ async function recordPendingWorkspaceApp(input: {
     ].slice(0, MAX_PENDING_APPS),
   });
 
+  await writeWorkspaceAppMetadataOverride({
+    appId: input.appId,
+    description: input.description,
+    generated: true,
+    sourcePrompt: input.sourcePrompt,
+    updatedBy: currentOwnerEmail(),
+  });
+
   await recordAudit({
     action: "workspace-app.pending",
     targetType: "workspace-app",
@@ -614,11 +890,12 @@ function readWorkspaceAppsFromFilesystem(
 
   const apps = fs
     .readdirSync(appsDir, { withFileTypes: true })
-    .filter((entry) => entry.isDirectory())
+    .filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))
     .map((entry): WorkspaceAppSummary | null => {
       const appDir = path.join(appsDir, entry.name);
       const pkg = readJson(path.join(appDir, "package.json"));
       if (!pkg) return null;
+      const routeAccess = workspaceAppRouteAccessFromPackageJson(pkg);
       return {
         id: entry.name,
         name: pkg.displayName || titleCase(entry.name),
@@ -626,6 +903,11 @@ function readWorkspaceAppsFromFilesystem(
         path: `/${entry.name}`,
         url: workspaceAppUrl(`/${entry.name}`),
         isDispatch: entry.name === "dispatch",
+        audience:
+          workspaceAppAudienceFromPackageJson(pkg) ??
+          DEFAULT_WORKSPACE_APP_AUDIENCE,
+        publicPaths: routeAccess.publicPaths,
+        protectedPaths: routeAccess.protectedPaths,
         status: "ready",
       } satisfies WorkspaceAppSummary;
     })
@@ -689,17 +971,92 @@ async function applyArchivedAndPending(
   apps: WorkspaceAppSummary[],
   options: ListWorkspaceAppsOptions,
 ): Promise<WorkspaceAppSummary[]> {
-  const [withPending, archivedIds] = await Promise.all([
+  const [withPending, archivedIds, metadataSettings] = await Promise.all([
     appendPendingWorkspaceApps(apps),
     listArchivedAppIds(),
+    readWorkspaceAppMetadataSettings(),
   ]);
   const archivedSet = new Set(archivedIds);
-  const annotated = withPending.map((app) =>
-    archivedSet.has(app.id) ? { ...app, archived: true } : app,
-  );
+  const annotated = withPending.map((app) => {
+    const withMetadata = applyWorkspaceAppMetadataOverride(
+      app,
+      metadataSettings,
+    );
+    return archivedSet.has(app.id)
+      ? { ...withMetadata, archived: true }
+      : withMetadata;
+  });
   return options.includeArchived
-    ? annotated
-    : annotated.filter((app) => !app.archived);
+    ? filterAppsByAudience(annotated, options.audience)
+    : filterAppsByAudience(
+        annotated.filter((app) => !app.archived),
+        options.audience,
+      );
+}
+
+function filterAppsByAudience(
+  apps: WorkspaceAppSummary[],
+  audience: ListWorkspaceAppsOptions["audience"],
+): WorkspaceAppSummary[] {
+  if (!audience || audience === "all") return apps;
+  return apps.filter(
+    (app) =>
+      (app.audience ?? DEFAULT_WORKSPACE_APP_AUDIENCE) ===
+      normalizeWorkspaceAppAudience(audience),
+  );
+}
+
+export async function updateWorkspaceAppMetadata(input: {
+  appId: string;
+  name?: string | null;
+  description?: string | null;
+}): Promise<WorkspaceAppSummary> {
+  await assertCanManageAppCreationSettings();
+  const appId = input.appId.trim();
+  assertValidWorkspaceAppId(appId);
+
+  const apps = await listWorkspaceApps({
+    includeAgentCards: false,
+    includeArchived: true,
+  });
+  const app = apps.find((candidate) => candidate.id === appId);
+  if (!app) throw new Error(`Workspace app "${appId}" was not found.`);
+
+  // Treat undefined/null as "field omitted, leave existing value alone"; an
+  // explicit empty string clears the override (the app reverts to its
+  // built-in name / no description). Without this, a partial update that
+  // only touches one field silently wipes the other.
+  const name = input.name == null ? app.name : input.name.trim();
+  const description =
+    input.description == null
+      ? (app.description ?? undefined)
+      : input.description.trim();
+  await writeWorkspaceAppMetadataOverride({
+    appId,
+    name,
+    description,
+    generated: false,
+    updatedBy: currentOwnerEmail(),
+  });
+
+  await recordAudit({
+    action: "workspace-app.metadata-updated",
+    targetType: "workspace-app",
+    targetId: appId,
+    summary: `Updated workspace app details for ${name}`,
+    metadata: {
+      name,
+      descriptionConfigured: !!description,
+    },
+  });
+
+  const updated = (
+    await listWorkspaceApps({
+      includeAgentCards: false,
+      includeArchived: true,
+    })
+  ).find((candidate) => candidate.id === appId);
+  return updated ?? { ...app, name, description };
 }
 
 export async function listWorkspaceApps(
@@ -745,6 +1102,9 @@ export async function listWorkspaceApps(
             path: "/dispatch",
             url: workspaceAppUrl("/dispatch"),
             isDispatch: true,
+            audience: DEFAULT_WORKSPACE_APP_AUDIENCE,
+            publicPaths: [],
+            protectedPaths: [],
             status: "ready",
           },
         ],
@@ -1166,6 +1526,7 @@ async function remoteAppCreationAuthorization(): Promise<
 function buildWorkspaceAppPrompt(input: {
   prompt: string;
   appId?: string | null;
+  description?: string | null;
   template?: string | null;
   selectedKeys?: string[];
   selectedResources?: WorkspaceResourceOption[];
@@ -1176,6 +1537,9 @@ function buildWorkspaceAppPrompt(input: {
       input.prompt.replace(/\b(build|create|make|an?|the|app|tool)\b/gi, " "),
     ) ||
     "new-app";
+  const appDescription =
+    input.description?.trim() ||
+    generateWorkspaceAppDescription(input.prompt, appId);
   const selectedKeys = input.selectedKeys || [];
   const selectedResources = input.selectedResources || [];
   const resourceList = selectedResources.length
@@ -1192,6 +1556,7 @@ function buildWorkspaceAppPrompt(input: {
       "Create a new agent-native app in this workspace.",
       "",
       `App name: ${appId}`,
+      `App description: ${appDescription}`,
       `Template to start from: ${input.template || "starter"}`,
       `User prompt: ${input.prompt.trim()}`,
       "If the user mentions a product or company such as Granola, Loom, Superhuman, Linear, or Notion, treat it as product inspiration unless they explicitly ask to connect to that service. Do not invent or require third-party API keys like GRANOLA_API_KEY just because a product is named.",
@@ -1199,6 +1564,7 @@ function buildWorkspaceAppPrompt(input: {
         ? `Dispatch vault keys selected for this app: ${selectedKeys.join(", ")}`
         : "Dispatch vault keys selected for this app: none",
       `Dispatch workspace resources selected for this app:\n${resourceList}`,
+      `Dispatch workspace resources with scope=all are global. After the app exists, sync workspace resources to appId "${appId}" so global skills, guardrail instructions, and reference resources reach the new app even when no per-app resources were selected.`,
       "",
       `Use the workspace app layout: create it under apps/${appId}, mount it at /${appId}, keep it on the shared workspace database/hosting model, and avoid table-name collisions by namespacing any new domain tables to the app.`,
       `Important routing rule: from outside the app, link to /${appId}; inside apps/${appId}, React Router routes are app-local. Use <Link to="/review"> and navigate("/review"), not "/${appId}/review"; APP_BASE_PATH supplies the mounted prefix, and hardcoding it causes doubled URLs like /${appId}/${appId}/review.`,
@@ -1209,8 +1575,8 @@ function buildWorkspaceAppPrompt(input: {
         ? `Dispatch will create pending vault requests for the selected keys for appId "${appId}" after this app creation request is accepted. Do not grant or sync vault keys directly from the app-creation branch.`
         : "Do not grant or request any Dispatch vault keys unless the user asks later.",
       selectedResources.length
-        ? `Dispatch will create workspace resource grants for the selected resources for appId "${appId}". After the app exists, sync workspace resources so the app receives those shared resources. Add a short note to apps/${appId}/AGENTS.md telling the app agent to read relevant shared resources under context/ or the selected resource paths before doing GTM/domain work.`
-        : "Do not grant any Dispatch workspace resources unless the user asks later.",
+        ? `Dispatch will create workspace resource grants for the selected resources for appId "${appId}". After the app exists, sync workspace resources so the app receives both global and selected shared resources.`
+        : "Do not grant any selected-only Dispatch workspace resources unless the user asks later.",
       "",
       "Agent-native rules (these are the framework's contract — not optional):",
       `- Persist ALL data in SQL via Drizzle. Add tables to apps/${appId}/server/db/schema.ts and migrations to apps/${appId}/server/plugins/db.ts. NEVER use localStorage, sessionStorage, IndexedDB, or in-memory state for anything the user expects to persist — agent and UI must read the same source of truth.`,
@@ -1222,11 +1588,13 @@ function buildWorkspaceAppPrompt(input: {
       "",
       "Branch readiness requirements before handing off:",
       "- The CLI auto-fills package.json name and displayName from the app id; only edit the description / scripts / dependencies if the app actually needs more than the template provides.",
+      `- Save a concise, human-readable app description in apps/${appId}/package.json "description" so Dispatch, A2A discovery, and connected agents can describe what this app does. Use the description above or improve it based on the prompt.`,
       "- Do not add or update workspace-apps.json or .agent-native/workspace-apps.json unless the app needs an explicit external URL override; the root deploy generates the workspace app registry from apps/* and deploy metadata.",
       "- Update pnpm-lock.yaml when adding or changing dependencies so Netlify can install the branch reliably.",
       "- Update the app manifest/package/deploy metadata needed by the existing workspace deployment model; do not leave the branch relying only on uncommitted local state.",
-      "- Verify the app's agent card/A2A metadata is ready so Dispatch can discover and delegate to the app after deployment.",
-      "- Include a final verification note covering the registry entry, manifest/deploy metadata, and agent-card readiness.",
+      "- Verify the app's agent card/A2A metadata is ready so Dispatch can discover and delegate to the app after deployment. Every sibling workspace app should be usable over A2A by default through call-agent.",
+      "- Give the app agent context that sibling workspace apps are available over A2A with names and descriptions from the workspace app registry; do not hardcode a stale app list.",
+      "- Include a final verification note covering the registry entry, manifest/deploy metadata, relative same-origin routing, and agent-card readiness.",
       `When it is ready, start or update the workspace dev server and navigate the user to /${appId}.`,
     ].join("\n"),
   };
@@ -1270,6 +1638,7 @@ async function grantSelectedWorkspaceResources(input: {
 export async function startWorkspaceAppCreation(input: {
   prompt: string;
   appId?: string | null;
+  description?: string | null;
   template?: string | null;
   secretIds?: string[];
   resourceIds?: string[];
@@ -1277,6 +1646,7 @@ export async function startWorkspaceAppCreation(input: {
   const initial = buildWorkspaceAppPrompt({
     prompt: input.prompt,
     appId: input.appId,
+    description: input.description,
     template: input.template,
   });
   assertValidWorkspaceAppId(initial.appId);
@@ -1304,11 +1674,15 @@ export async function startWorkspaceAppCreation(input: {
   const built = buildWorkspaceAppPrompt({
     prompt: input.prompt,
     appId: input.appId,
+    description: input.description,
     template: input.template,
     selectedKeys,
     selectedResources,
   });
   const prompt = built.prompt;
+  const appDescription =
+    input.description?.trim() ||
+    generateWorkspaceAppDescription(input.prompt, built.appId);
 
   if (isLocal) {
     await requestSelectedVaultKeys({
@@ -1375,6 +1749,8 @@ export async function startWorkspaceAppCreation(input: {
   await recordPendingWorkspaceApp({
     appId: built.appId,
     projectId: settings.builderProjectId,
+    description: appDescription,
+    sourcePrompt: input.prompt,
     branchName: result.branchName,
     builderUrl: result.url,
   });

package/src/server/lib/dispatch-integrations.ts

@@ -5,6 +5,7 @@ import type {
 import { resolveOrgIdForEmail } from "@agent-native/core/org";
 import crypto from "node:crypto";
 import { consumeLinkToken, resolveLinkedOwner } from "./dispatch-store.js";
+import { handleRemoteCodeCommand } from "./dispatch-remote-commands.js";
 
 type SlackSenderProfile = {
   email: string | null;
@@ -195,11 +196,17 @@ export async function resolveDispatchOwner(
 
 export async function beforeDispatchProcess(
   incoming: IncomingMessage,
-  _adapter: PlatformAdapter,
+  adapter: PlatformAdapter,
 ): Promise<{ handled: true; responseText?: string } | { handled: false }> {
   const trimmed = incoming.text.trim();
-  const match = trimmed.match(/^\/link\s+([a-zA-Z0-9_-]+)$/);
-  if (!match) return { handled: false };
+  const commandText =
+    contextString(incoming.platformContext.rawText) || trimmed;
+  const match = commandText.match(/^\/link(?:@\w+)?\s+([a-zA-Z0-9_-]+)$/);
+  if (!match) {
+    return handleRemoteCodeCommand(incoming, adapter, {
+      resolveOwner: () => resolveDispatchOwner(incoming),
+    });
+  }
 
   try {
     const owner = await consumeLinkToken({