@agent-native/dispatch 0.41.1-nightly-20261104110058 → 0.42.0

package/src/server/lib/app-roles.spec.ts

@@ -35,7 +35,10 @@ vi.mock("@agent-native/core/server", () => ({
 
 import { ForbiddenError } from "@agent-native/core/sharing";
 
-import { authorizeDispatchAdmin } from "./app-roles.js";
+import {
+  authorizeDispatchAdmin,
+  authorizeOrgOwnerOrAdmin,
+} from "./app-roles.js";
 
 const context = {
   caller: "http" as const,
@@ -164,3 +167,47 @@ describe("authorizeDispatchAdmin", () => {
     ).rejects.toBeInstanceOf(ForbiddenError);
   });
 });
+
+describe("authorizeOrgOwnerOrAdmin", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mocks.isStandaloneDispatchRuntime.mockReturnValue(false);
+  });
+
+  it("denies a Dispatch admin who is only an organization member", async () => {
+    mocks.roles = ["admin"];
+    mocks.validateFederatedOrganizationMembershipForCurrentRequest.mockResolvedValue(
+      { active: true, role: "member" },
+    );
+    await expect(authorizeOrgOwnerOrAdmin({}, context)).rejects.toThrow(
+      "Only organization owners and admins",
+    );
+  });
+
+  it.each(["owner", "admin"])("allows an organization %s", async (role) => {
+    mocks.validateFederatedOrganizationMembershipForCurrentRequest.mockResolvedValue(
+      { active: true, role },
+    );
+    await expect(
+      authorizeOrgOwnerOrAdmin({}, context),
+    ).resolves.toBeUndefined();
+  });
+
+  it("denies an inactive membership", async () => {
+    mocks.validateFederatedOrganizationMembershipForCurrentRequest.mockResolvedValue(
+      { active: false, role: null },
+    );
+    await expect(authorizeOrgOwnerOrAdmin({}, context)).rejects.toThrow(
+      "requires active organization membership",
+    );
+  });
+
+  it("lets a signed-in user without an organization manage their own scope", async () => {
+    await expect(
+      authorizeOrgOwnerOrAdmin({}, { ...context, orgId: null } as never),
+    ).resolves.toBeUndefined();
+    await expect(
+      authorizeOrgOwnerOrAdmin({}, { ...context, userEmail: "" }),
+    ).rejects.toBeInstanceOf(ForbiddenError);
+  });
+});

package/src/server/lib/app-roles.ts

@@ -4,6 +4,7 @@ import {
   isMissingOrganizationTableError,
   isStandaloneDispatchRuntime,
   type AppRoles,
+  type OrgRole,
   validateFederatedOrganizationMembershipForCurrentRequest,
 } from "@agent-native/core/org";
 import {
@@ -22,19 +23,21 @@ function getDispatchAccess(): AppRoles<"admin", "administer"> {
   }));
 }
 
-export async function authorizeDispatchAdmin(
-  _args: unknown,
-  ctx?: ActionRunContext,
-): Promise<void> {
+/**
+ * The caller's active membership in the request org, or null when there is no
+ * org to check (a user without one, or standalone Dispatch with no org tables).
+ */
+async function requireActiveMembership(
+  ctx: ActionRunContext | undefined,
+  action: string,
+): Promise<{ email: string; orgId: string; role: OrgRole } | null> {
   const email =
     ctx?.userEmail !== undefined ? ctx.userEmail : getRequestUserEmail();
   const orgId = ctx?.orgId !== undefined ? ctx.orgId : getRequestOrgId();
   if (!email?.trim()) {
-    throw new ForbiddenError(
-      "Dispatch administration requires an authenticated user.",
-    );
+    throw new ForbiddenError(`${action} requires an authenticated user.`);
   }
-  if (!orgId?.trim()) return;
+  if (!orgId?.trim()) return null;
   let membership;
   try {
     membership = await validateFederatedOrganizationMembershipForCurrentRequest(
@@ -48,17 +51,46 @@ export async function authorizeDispatchAdmin(
       isMissingOrganizationTableError(error) &&
       isStandaloneDispatchRuntime()
     ) {
-      return;
+      return null;
     }
     throw error;
   }
   if (!membership.active) {
     throw new ForbiddenError(
-      "Dispatch administration requires active organization membership.",
+      `${action} requires active organization membership.`,
     );
   }
+  return { email, orgId, role: membership.role };
+}
+
+export async function authorizeDispatchAdmin(
+  _args: unknown,
+  ctx?: ActionRunContext,
+): Promise<void> {
+  const membership = await requireActiveMembership(
+    ctx,
+    "Dispatch administration",
+  );
+  if (!membership) return;
   await getDispatchAccess().assertPermission(["administer"], {
-    userEmail: email,
-    orgId,
+    userEmail: membership.email,
+    orgId: membership.orgId,
   });
 }
+
+/** Organization owners and admins only; Dispatch admin roles do not count. */
+export async function authorizeOrgOwnerOrAdmin(
+  _args: unknown,
+  ctx?: ActionRunContext,
+): Promise<void> {
+  const membership = await requireActiveMembership(
+    ctx,
+    "This organization setting",
+  );
+  if (!membership) return;
+  if (membership.role !== "owner" && membership.role !== "admin") {
+    throw new ForbiddenError(
+      "Only organization owners and admins can change this setting.",
+    );
+  }
+}

package/src/server/lib/hosted-apps-settings-schema.ts

@@ -0,0 +1,6 @@
+import { z } from "zod";
+
+/** Result of the get/set hosted-apps actions. */
+export const hostedAppsSettingsViewSchema = z.object({
+  showHostedApps: z.boolean(),
+});

package/src/server/lib/hosted-apps-settings.spec.ts

@@ -0,0 +1,154 @@
+import { isActionContractError } from "@agent-native/core/action";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  orgId: vi.fn<() => string | undefined>(() => "org-1"),
+  email: vi.fn<() => string | undefined>(() => "owner@example.test"),
+  getOrgSetting: vi.fn(),
+  getUserSetting: vi.fn(),
+  putOrgSetting: vi.fn(),
+  putUserSetting: vi.fn(),
+  getBuiltinAgents: vi.fn(),
+  loadWorkspaceAppsManifest: vi.fn(),
+}));
+
+vi.mock("@agent-native/core/server", () => ({
+  getRequestOrgId: () => mocks.orgId(),
+  getRequestUserEmail: () => mocks.email(),
+}));
+
+vi.mock("@agent-native/core/settings", () => ({
+  getOrgSetting: mocks.getOrgSetting,
+  getUserSetting: mocks.getUserSetting,
+  putOrgSetting: mocks.putOrgSetting,
+  putUserSetting: mocks.putUserSetting,
+}));
+
+vi.mock("@agent-native/core/server/agent-discovery", () => ({
+  getBuiltinAgents: mocks.getBuiltinAgents,
+  loadWorkspaceAppsManifest: mocks.loadWorkspaceAppsManifest,
+  normalizeAgentId: (id: string) => id.trim().toLowerCase(),
+}));
+
+import {
+  hideHostedAppsWhenOff,
+  HOSTED_APPS_SETTINGS_KEY,
+  InvalidHostedAppsSettingsError,
+  listHostedApps,
+  readHostedAppsSettings,
+  setHostedAppsSettings,
+} from "./hosted-apps-settings.js";
+
+const agent = (id: string) => ({
+  id,
+  name: id,
+  description: "",
+  url: `https://${id}.example.test`,
+  color: "#000000",
+});
+
+describe("hosted apps settings", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mocks.orgId.mockReturnValue("org-1");
+    mocks.email.mockReturnValue("owner@example.test");
+    mocks.getBuiltinAgents.mockReturnValue([agent("mail"), agent("slides")]);
+    mocks.loadWorkspaceAppsManifest.mockResolvedValue([{ id: "Slides" }]);
+  });
+
+  it("shows hosted apps when the org has never set it", async () => {
+    mocks.getOrgSetting.mockResolvedValue(null);
+    await expect(readHostedAppsSettings()).resolves.toEqual({
+      showHostedApps: true,
+      invalid: false,
+    });
+    expect(mocks.getOrgSetting).toHaveBeenCalledWith(
+      "org-1",
+      HOSTED_APPS_SETTINGS_KEY,
+    );
+  });
+
+  it("reads the stored org value", async () => {
+    mocks.getOrgSetting.mockResolvedValue({ showHostedApps: false });
+    await expect(readHostedAppsSettings()).resolves.toEqual({
+      showHostedApps: false,
+      invalid: false,
+    });
+  });
+
+  it("falls back to the user's setting without an org", async () => {
+    mocks.orgId.mockReturnValue(undefined);
+    mocks.getUserSetting.mockResolvedValue({ showHostedApps: false });
+    await expect(readHostedAppsSettings()).resolves.toEqual({
+      showHostedApps: false,
+      invalid: false,
+    });
+    expect(mocks.getUserSetting).toHaveBeenCalledWith(
+      "owner@example.test",
+      HOSTED_APPS_SETTINGS_KEY,
+    );
+
+    await setHostedAppsSettings({ showHostedApps: true });
+    expect(mocks.putUserSetting).toHaveBeenCalledWith(
+      "owner@example.test",
+      HOSTED_APPS_SETTINGS_KEY,
+      { showHostedApps: true },
+    );
+    expect(mocks.putOrgSetting).not.toHaveBeenCalled();
+  });
+
+  it("reports an invalid stored value and hides hosted apps for it", async () => {
+    mocks.getOrgSetting.mockResolvedValue({ showHostedApps: "no" });
+    await expect(readHostedAppsSettings()).resolves.toEqual({
+      showHostedApps: false,
+      invalid: true,
+    });
+    expect(
+      (await hideHostedAppsWhenOff([agent("mail"), agent("partner")])).map(
+        (a) => a.id,
+      ),
+    ).toEqual(["partner"]);
+  });
+
+  it("types the invalid-setting error so Settings can offer the repair", () => {
+    const error = new InvalidHostedAppsSettingsError();
+    expect(isActionContractError(error)).toBe(true);
+    expect(error).toMatchObject({
+      errorCode: "dispatch_hosted_apps_settings_invalid",
+      statusCode: 409,
+    });
+  });
+
+  it("propagates a settings read failure", async () => {
+    mocks.getOrgSetting.mockRejectedValue(new Error("db down"));
+    await expect(readHostedAppsSettings()).rejects.toThrow("db down");
+    await expect(hideHostedAppsWhenOff([agent("mail")])).rejects.toThrow(
+      "db down",
+    );
+  });
+
+  it("writes the org setting", async () => {
+    await setHostedAppsSettings({ showHostedApps: false });
+    expect(mocks.putOrgSetting).toHaveBeenCalledWith(
+      "org-1",
+      HOSTED_APPS_SETTINGS_KEY,
+      { showHostedApps: false },
+    );
+  });
+
+  it("treats a mounted workspace app with a built-in id as not hosted", async () => {
+    expect((await listHostedApps()).map((app) => app.id)).toEqual(["mail"]);
+  });
+
+  it("removes only hosted apps from agent context when off", async () => {
+    const agents = [agent("mail"), agent("slides"), agent("partner")];
+    mocks.getOrgSetting.mockResolvedValue({ showHostedApps: true });
+    expect(await hideHostedAppsWhenOff(agents)).toEqual(agents);
+
+    mocks.getOrgSetting.mockResolvedValue({ showHostedApps: false });
+    expect((await hideHostedAppsWhenOff(agents)).map((a) => a.id)).toEqual([
+      "slides",
+      "partner",
+    ]);
+  });
+});

package/src/server/lib/hosted-apps-settings.ts

@@ -0,0 +1,108 @@
+import { ActionContractError } from "@agent-native/core/action";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server";
+import {
+  getBuiltinAgents,
+  loadWorkspaceAppsManifest,
+  normalizeAgentId,
+  type DiscoveredAgent,
+} from "@agent-native/core/server/agent-discovery";
+import {
+  getOrgSetting,
+  getUserSetting,
+  putOrgSetting,
+  putUserSetting,
+} from "@agent-native/core/settings";
+
+import { HOSTED_APPS_SETTINGS_INVALID_ERROR_CODE } from "../../shared/hosted-apps-settings.js";
+
+export const HOSTED_APPS_SETTINGS_KEY = "dispatch-hosted-apps-settings";
+
+export interface HostedAppsSettings {
+  showHostedApps: boolean;
+}
+
+// A contract error, so its code reaches Settings, which offers the save that
+// repairs it; a bare error would arrive as an anonymous 500.
+export class InvalidHostedAppsSettingsError extends ActionContractError {
+  constructor() {
+    super(
+      `Stored ${HOSTED_APPS_SETTINGS_KEY} is not { showHostedApps: boolean }. Save the Agent-Native.com hosted apps setting again to repair it.`,
+      { errorCode: HOSTED_APPS_SETTINGS_INVALID_ERROR_CODE, statusCode: 409 },
+    );
+    this.name = "InvalidHostedAppsSettingsError";
+  }
+}
+
+/**
+ * Built-in catalog apps this workspace offers. A mounted workspace app with a
+ * built-in's id is a workspace app; the built-in config never applies to it.
+ */
+export async function listHostedApps(): Promise<DiscoveredAgent[]> {
+  const workspaceApps = await loadWorkspaceAppsManifest();
+  const workspaceIds = new Set(
+    (workspaceApps ?? []).map((app) => normalizeAgentId(app.id)),
+  );
+  return getBuiltinAgents("dispatch").filter(
+    (agent) => !workspaceIds.has(agent.id),
+  );
+}
+
+function hostedAppsSettingsScope() {
+  const orgId = getRequestOrgId();
+  if (orgId) return { scope: "org" as const, scopeId: orgId };
+  const email = getRequestUserEmail();
+  return email ? { scope: "user" as const, scopeId: email } : null;
+}
+
+/**
+ * The stored setting. An unreadable value is `invalid` and hides hosted apps,
+ * so it cannot fail the app lists or agent context; Settings reports it.
+ */
+export async function readHostedAppsSettings(): Promise<
+  HostedAppsSettings & { invalid: boolean }
+> {
+  const scope = hostedAppsSettingsScope();
+  // No org and no user means there is nowhere the setting could be stored.
+  if (!scope) return { showHostedApps: true, invalid: false };
+  const raw =
+    scope.scope === "org"
+      ? await getOrgSetting(scope.scopeId, HOSTED_APPS_SETTINGS_KEY)
+      : await getUserSetting(scope.scopeId, HOSTED_APPS_SETTINGS_KEY);
+  if (raw === null) return { showHostedApps: true, invalid: false };
+  if (typeof raw.showHostedApps !== "boolean") {
+    return { showHostedApps: false, invalid: true };
+  }
+  return { showHostedApps: raw.showHostedApps, invalid: false };
+}
+
+export async function setHostedAppsSettings(
+  next: HostedAppsSettings,
+): Promise<HostedAppsSettings> {
+  const scope = hostedAppsSettingsScope();
+  if (!scope) {
+    throw Object.assign(
+      new Error("Sign in to change the Agent-Native.com hosted apps setting."),
+      { statusCode: 401 },
+    );
+  }
+  const value = { showHostedApps: next.showHostedApps };
+  if (scope.scope === "org") {
+    await putOrgSetting(scope.scopeId, HOSTED_APPS_SETTINGS_KEY, value);
+  } else {
+    await putUserSetting(scope.scopeId, HOSTED_APPS_SETTINGS_KEY, value);
+  }
+  return value;
+}
+
+/** Hides hosted apps from Dispatch's lists and agent context when off. */
+export async function hideHostedAppsWhenOff<T extends { id: string }>(
+  agents: T[],
+): Promise<T[]> {
+  const { showHostedApps } = await readHostedAppsSettings();
+  if (showHostedApps) return agents;
+  const hostedIds = new Set((await listHostedApps()).map((app) => app.id));
+  return agents.filter((agent) => !hostedIds.has(agent.id));
+}

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

@@ -2,11 +2,18 @@ import { describe, expect, it, vi } from "vitest";
 
 const mocks = vi.hoisted(() => ({
   createAgentChatPlugin: vi.fn((options: Record<string, unknown>) => options),
+  registerAgentContextAgentFilter: vi.fn(),
+  hideHostedAppsWhenOff: vi.fn(),
 }));
 
 vi.mock("@agent-native/core/server", () => ({
   createAgentChatPlugin: mocks.createAgentChatPlugin,
   getBuilderWorkspaceUrl: () => null,
+  registerAgentContextAgentFilter: mocks.registerAgentContextAgentFilter,
+}));
+
+vi.mock("../lib/hosted-apps-settings.js", () => ({
+  hideHostedAppsWhenOff: mocks.hideHostedAppsWhenOff,
 }));
 
 vi.mock("@agent-native/core/org", () => ({
@@ -48,6 +55,15 @@ describe("Dispatch agent chat plugin", () => {
     );
   });
 
+  it("hides hosted apps from its own agent context through the setting", async () => {
+    await import("./agent-chat.js");
+
+    expect(mocks.registerAgentContextAgentFilter).toHaveBeenCalledWith(
+      "dispatch",
+      mocks.hideHostedAppsWhenOff,
+    );
+  });
+
   it("routes customer credit questions to the owning workspace app", async () => {
     await import("./agent-chat.js");
 

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

@@ -2,9 +2,11 @@ import { getOrgContext } from "@agent-native/core/org";
 import {
   createAgentChatPlugin,
   getBuilderWorkspaceUrl,
+  registerAgentContextAgentFilter,
 } from "@agent-native/core/server";
 
 import { dispatchActions } from "../../actions/index.js";
+import { hideHostedAppsWhenOff } from "../lib/hosted-apps-settings.js";
 import {
   workspaceAppActionRouteAuth,
   WORKSPACE_APP_CLAIM_ACTION_PATH,
@@ -41,6 +43,8 @@ const INITIAL_TOOL_NAMES = [
   "navigate",
 ];
 
+registerAgentContextAgentFilter("dispatch", hideHostedAppsWhenOff);
+
 export default createAgentChatPlugin({
   appId: "dispatch",
   connectApps: true,
@@ -89,11 +93,12 @@ Use the standard workspace primitives:
 - You receive a compact available-apps block with sibling workspace app names and descriptions. Use it to pick the right A2A target, and call list-connected-agents or tool-search only when you need fresh details.
 - Hosted/connected A2A neighbors such as Analytics and Content come from the available-apps context or list-connected-agents. list-workspace-apps only inventories apps mounted inside this workspace deployment; never use a missing row there to conclude that a connected agent is unavailable.
 - When answering whether a mounted workspace app exposes an agent card or A2A endpoint, call list-workspace-apps with includeAgentCards=true. If you have not requested that probe, absence of agent-card fields means unchecked, not unavailable.
-- When creating a new workspace app, create a separate app under apps/<app-id> with apps/<app-id>/package.json including a concise generated description, mount it at /<app-id>, use relative /<app-id> links, never hardcode localhost or dev ports, use shadcn/ui with @tabler/icons-react rather than lucide-react, and ensure the React Router client entry preserves APP_BASE_PATH/VITE_APP_BASE_PATH via appBasePath(). There is no separate workspace app registry to edit.
+- When creating a new workspace app, create a separate app under apps/<app-id> with apps/<app-id>/package.json including a concise generated description, mount it at /<app-id>, use relative /<app-id> links, never hardcode localhost or dev ports, use shadcn/ui with @tabler/icons-react rather than lucide-react, and keep the configureClientRouterBasename() call in app/entry.client.tsx so the app hydrates at /<app-id>. There is no separate workspace app registry to edit.
 - When a user asks to rename an existing workspace app or change its Dispatch title/description, call update-workspace-app-metadata with the existing appId from list-workspace-apps. This is a metadata-only edit — never call start-workspace-app-creation, which creates a new app and Builder branch.
 - When an explicit app-creation request already includes a source brief or a concrete repeatable workflow, call start-workspace-app-creation without asking non-blocking product or UX questions. Choose recommended defaults, let the Builder handoff record assumptions, and ask only for authorization, credentials, a destructive action, an ambiguous target workspace, or a genuinely missing workflow.
 - If the chat template is used, treat it as scaffolding only: the finished app must be branded as the requested app with its own home screen/navigation/package metadata/manifest, and must not leave visible "Chat", "Starter", "Blank app", or "New app" UI behind.
-- Treat first-party apps such as Mail, Calendar, Analytics, Brain, Assets, and Dispatch as existing hosted/connected neighbors available through links and A2A/default connected agents. Do not create wrapper apps, child apps, nested routes, or cloned template copies just to give a new app access to them; build only the genuinely new workflow and delegate cross-app work to those existing apps.
+- Treat the apps in the available-apps context as existing neighbors available through links and A2A. Do not create wrapper apps, child apps, nested routes, or cloned template copies just to give a new app access to them; build only the genuinely new workflow and delegate cross-app work to those existing apps.
+- Owners and admins can hide Agent-Native.com hosted apps for the organization with set-hosted-apps-settings; get-hosted-apps-settings reads it. When hidden they are left out of available-apps and list-connected-agents marks them hiddenFromLaunchers, but call-agent by name still reaches them.
 - Integration grants are not provider capability limits. For ad hoc provider inspection, querying, reporting, or troubleshooting, call provider-api-catalog/provider-api-docs, then provider-api-request against the provider's real HTTP API. Use connectionId for a specific shared grant and accountId for a specific OAuth account. Never expose secret values or silently widen app access while doing this.
 - For broad provider searches, joins, classification, corpus counts, or absence claims, fetch every relevant page or an explicitly bounded cohort, stage/save large responses with stageAs/saveToFile/fetchAllPages, and reduce them with query-staged-dataset or run-code. Report source, filters, row counts, pagination, truncation, failed pages, and uncovered gaps.
 - Use list-dispatch-usage-metrics only for this workspace's own members' agent/LLM usage and spend, or aggregate adoption of an accessible workspace app. For agent/LLM usage or spend, call it with scope=workspace and the requested sinceDays; it reports workspace-member usage only. For app adoption, call it with scope=app and appId; app creators can see aggregate daily/weekly active users and tracked actions for their own app, while organization owners/admins can inspect any accessible app. App scope omits individual users and prompt previews. External customer, account, or company usage, credits, activity, or product data belongs to the relevant app: use its identity in <relevant-apps> when clear, or call describe-workspace-apps with a query when ownership is unclear. Do not use this action for external customer/account/company data.

package/src/server/plugins/integrations.ts

@@ -23,7 +23,7 @@ Default posture:
 - Use relevant-apps prompt profiles first, then list-connected-agents when you need fresh details. If that context is absent or does not list the needed capability, search with describe-workspace-apps query="<capability>" before assuming a request must be handled locally.
 - Hosted/connected A2A neighbors such as Analytics and Content come from the relevant-apps context or list-connected-agents. If neither identifies the needed capability, use describe-workspace-apps before concluding a connected agent is unavailable. list-workspace-apps only inventories apps mounted inside this workspace deployment; never use a missing row there to conclude that a connected agent is unavailable.
 - When asked whether a mounted workspace app exposes an agent card or A2A endpoint, call list-workspace-apps with includeAgentCards=true. Without that probe, missing agent-card fields mean unchecked, not unavailable.
-- Treat first-party apps such as Mail, Calendar, Analytics, Brain, Assets, and Dispatch as existing hosted/connected neighbors available through links and A2A/default connected agents. Do not create wrapper apps, child apps, nested routes, or cloned template copies just to give a new app access to them; build only the genuinely new workflow and delegate cross-app work to those existing apps.
+- Treat the apps in the relevant-apps context as existing neighbors available through links and A2A. Do not create wrapper apps, child apps, nested routes, or cloned template copies just to give a new app access to them; build only the genuinely new workflow and delegate cross-app work to those existing apps.
 - Integration grants are not provider capability limits. For ad hoc provider inspection, querying, reporting, or troubleshooting, call provider-api-catalog/provider-api-docs, then provider-api-request against the provider's real HTTP API. Use connectionId for a specific shared grant and accountId for a specific OAuth account. Never expose secret values or silently widen app access while doing this.
 - Keep durable memory and operating instructions in resources rather than ephemeral chat.
 - Reply in the originating thread unless the user explicitly asks you to send to a saved destination.
@@ -38,9 +38,9 @@ When a user asks for something:
 - Exception: if the downstream agent reports a missing model/provider credential, do not name exact env vars, Vault keys, tokens, or secrets. Say the target app needs an LLM connection and recommend using Builder/managed LLM for that app; keep bring-your-own provider keys as a secondary option only if the user asks.
 - If the user asks to create, build, make, scaffold, or generate an "agent" from Dispatch chat or by tagging @agent-native in Slack, email, or Telegram, first classify the ask. If it is a simple Dispatch-native behavior like a reminder, digest, monitor, routing rule, saved instruction, or recurring workflow, create or update the recurring job/resource/destination in Dispatch. If it is a robust unique product or teammate that needs its own UI, data model, actions, integrations, or domain workflow, treat it as a new workspace app and call start-workspace-app-creation.
 - If a user asks to rename an existing workspace app or change its Dispatch title/description, call update-workspace-app-metadata with the existing appId from list-workspace-apps. Do not call start-workspace-app-creation for a metadata-only edit because that starts a new app and Builder branch.
-- If a new-app prompt asks for access to Mail, Calendar, Analytics, Brain, Assets, or similar first-party app data/agents, keep using the existing hosted/connected app and A2A path. Do not ask Builder to scaffold those apps as children of the new app unless the user explicitly asks for a customized app from that template.
+- If a new-app prompt asks for access to Mail, Calendar, Analytics, Brain, Assets, or similar first-party app data/agents, keep using the existing app through A2A. Do not ask Builder to scaffold those apps as children of the new app unless the user explicitly asks for a customized app from that template.
 - If the chat template is used, treat it as scaffolding only: the finished app must be branded as the requested app with its own home screen/navigation/package metadata/manifest, and must not leave visible "Chat", "Starter", "Blank app", or "New app" UI behind.
-- If the user explicitly asks for a new app or workspace app, call start-workspace-app-creation with their prompt and include a concise generated description by default. Do not satisfy a new-app request by adding a route, page, component, or file inside apps/chat or another existing app unless the user explicitly asks to modify that existing app. When the prompt contains a source brief or concrete repeatable workflow, choose recommended defaults and do not ask non-blocking product or UX questions; ask only for authorization, credentials, a destructive action, an ambiguous target workspace, or a genuinely missing workflow. If the request is too vague to classify, ask one concise follow-up. If the action returns mode "builder", reply with the Builder branch URL; Builder is responsible for creating the separate workspace app under apps/<app-id>, mounting it at /<app-id>, ensuring apps/<app-id>/package.json exists with name/displayName and description so Dispatch discovers it, using relative /<app-id> links instead of hardcoded localhost/dev ports, and preserving APP_BASE_PATH/VITE_APP_BASE_PATH in the React Router client entry. The new app lives at the workspace root /<app-id>, NOT under /dispatch/<app-id>, /apps/<app-id>, or any other Dispatch tab — when telling the user where to find it, link to /<app-id> only. There is no separate workspace app registry to edit. If it returns mode "local-agent", tell the user it is ready for the local code agent and include the returned app path/prompt summary. Dispatch reuses the connected workspace Builder project or provisions it through the Builder Projects API when an organization owner/admin starts the first app; members need an owner/admin to configure the project first. Do not ask the user to use Builder org/beta settings. If it returns mode "builder-unavailable", the action also returns a \`reason\` code plus a user-facing \`message\` and (for some reasons) an operator-facing \`detail\`. Relay the \`message\` to the user as-is; only surface \`detail\` when the user is clearly an operator debugging the deployment (e.g. troubleshooting a broken Builder connection for the workspace), never as routine detail for an end user. If it returns mode "app-id-taken", the app id is already in use: \`conflict\` is "registered" for a live app or "pending" for a creation in flight, and \`owner\` names who started it. Relay the \`message\` and propose a different app id; never retry the same id.
+- If the user explicitly asks for a new app or workspace app, call start-workspace-app-creation with their prompt and include a concise generated description by default. Do not satisfy a new-app request by adding a route, page, component, or file inside apps/chat or another existing app unless the user explicitly asks to modify that existing app. When the prompt contains a source brief or concrete repeatable workflow, choose recommended defaults and do not ask non-blocking product or UX questions; ask only for authorization, credentials, a destructive action, an ambiguous target workspace, or a genuinely missing workflow. If the request is too vague to classify, ask one concise follow-up. If the action returns mode "builder", reply with the Builder branch URL; Builder is responsible for creating the separate workspace app under apps/<app-id>, mounting it at /<app-id>, ensuring apps/<app-id>/package.json exists with name/displayName and description so Dispatch discovers it, using relative /<app-id> links instead of hardcoded localhost/dev ports, and keeping the configureClientRouterBasename() call in app/entry.client.tsx. The new app lives at the workspace root /<app-id>, NOT under /dispatch/<app-id>, /apps/<app-id>, or any other Dispatch tab — when telling the user where to find it, link to /<app-id> only. There is no separate workspace app registry to edit. If it returns mode "local-agent", tell the user it is ready for the local code agent and include the returned app path/prompt summary. Dispatch reuses the connected workspace Builder project or provisions it through the Builder Projects API when an organization owner/admin starts the first app; members need an owner/admin to configure the project first. Do not ask the user to use Builder org/beta settings. If it returns mode "builder-unavailable", the action also returns a \`reason\` code plus a user-facing \`message\` and (for some reasons) an operator-facing \`detail\`. Relay the \`message\` to the user as-is; only surface \`detail\` when the user is clearly an operator debugging the deployment (e.g. troubleshooting a broken Builder connection for the workspace), never as routine detail for an end user. If it returns mode "app-id-taken", the app id is already in use: \`conflict\` is "registered" for a live app or "pending" for a creation in flight, and \`owner\` names who started it. Relay the \`message\` and propose a different app id; never retry the same id.
 - For digests, reminders, or saved behavior, prefer recurring jobs, resources, or destinations over chat replies.
 - Keep responses concise and operational — messaging platforms have character limits.
 - Use markdown sparingly (bold and lists are fine, avoid complex formatting).

package/src/shared/hosted-apps-settings.ts

@@ -0,0 +1,3 @@
+/** The stored setting is not `{ showHostedApps: boolean }`; saving repairs it. */
+export const HOSTED_APPS_SETTINGS_INVALID_ERROR_CODE =
+  "dispatch_hosted_apps_settings_invalid";

package/src/styles/dispatch.css

@@ -17,22 +17,51 @@
   display: none;
 }
 
-.dispatch-chat-first-notice {
+/* Chat history uses the shadcn sidebar metrics the apps rail below it gets
+   from SidebarGroupLabel: 32px labels and rows, 8px inner padding, 4px gaps. */
+.dispatch-chat-first-chats .an-chat-history__section-label {
   display: flex;
   align-items: center;
-  justify-content: space-between;
-  gap: 0.75rem;
-  border-bottom: 1px solid hsl(var(--border));
-  background: hsl(var(--muted) / 0.35);
-  padding: 0.5rem 0.75rem;
-  color: hsl(var(--muted-foreground));
+  min-height: 2rem;
+  padding: 0 0.5rem;
+  color: hsl(var(--sidebar-foreground) / 0.7);
   font-size: 0.75rem;
+  font-weight: 500;
+  letter-spacing: 0;
+  text-transform: none;
 }
 
-.dispatch-chat-first-notice button {
-  flex: none;
-  color: hsl(var(--foreground));
-  font-weight: 600;
+.dispatch-chat-first-chats .an-chat-history--rail .an-chat-history__list {
+  padding-block: 0;
+}
+
+.dispatch-chat-first-chats .an-chat-history--rail .an-chat-history__section {
+  gap: 0.25rem;
+  padding-block: 0.5rem;
+}
+
+.dispatch-chat-first-chats .an-chat-history--rail .an-chat-history-row,
+.dispatch-chat-first-chats
+  .an-chat-history--rail
+  .an-chat-history__skeleton-row {
+  margin-inline: 0;
+}
+
+.dispatch-chat-first-chats .an-chat-history--rail .an-chat-history-row__button,
+.dispatch-chat-first-chats
+  .an-chat-history--rail
+  .an-chat-history__skeleton-row {
+  min-height: 2rem;
+  padding-inline: 0.5rem;
+}
+
+.dispatch-chat-first-chats .an-chat-history-rail__section-footer {
+  padding: 0;
+}
+
+.dispatch-chat-first-chats .an-chat-history-rail__section-toggle {
+  min-height: 2rem;
+  padding: 0 0.5rem;
 }
 
 @media (max-width: 767px) {

package/dist/components/available-apps-section.d.ts

@@ -1,9 +0,0 @@
-import type { ConnectedAppSummary, WorkspaceAppId } from "../lib/other-apps.js";
-export declare function AvailableAppsSection({ connectedApps, workspaceApps, query, onConnected, className, }: {
-    connectedApps: ConnectedAppSummary[];
-    workspaceApps: WorkspaceAppId[];
-    query?: string;
-    onConnected?: () => void;
-    className?: string;
-}): import("node_modules/@types/react").JSX.Element | null;
-//# sourceMappingURL=available-apps-section.d.ts.map

package/dist/components/available-apps-section.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"available-apps-section.d.ts","sourceRoot":"","sources":["../../src/components/available-apps-section.tsx"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAwB7E,wBAAgB,oBAAoB,CAAC,EACnC,aAAa,EACb,aAAa,EACb,KAAU,EACV,WAAW,EACX,SAAS,GACV,EAAE;IACD,aAAa,EAAE,mBAAmB,EAAE,CAAC;IACrC,aAAa,EAAE,cAAc,EAAE,CAAC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,0DAqCA"}