@k2b/cloud 0.43.0 → 0.44.0

package/src/_internal/capabilities.ts

@@ -1,5 +1,16 @@
+import type { AppEventDefinition, AppEventSubscriptionDefinition } from "../contracts/app-events";
+import {
+  type CapabilityEventManifest,
+  CapabilityEventManifestSchema,
+  CapabilityQualifiedIdSchema,
+  type CapabilitySubscriptionManifest,
+  CapabilitySubscriptionManifestSchema,
+} from "../contracts/capabilities";
+import { RESOURCE_PAGES_PER_TYPE, resourcePageIssue } from "../contracts/resource-pages";
 import { hasOAuthScope } from "../server/oauth-scope";
 import { capabilityMessages } from "../shared/capability-messages";
+import { assertAppEventDeclarationSize, assertBoundedAppEventSchema, compileAppEventSchema } from "./app-event-schemas";
+import { capabilityVia } from "./capability-origin";
 import { capabilityHash, projectSchema, stableJsonValue } from "./capability-schemas";
 
 export { capabilityHash } from "./capability-schemas";
@@ -13,6 +24,7 @@ import {
   CAPABILITY_MAX_RESULT_BYTES,
   CAPABILITY_MAX_REVIEW_RESPONSE_BYTES,
   CAPABILITY_PROTOCOL_VERSION,
+  CAPABILITY_RESOURCE_COLORS,
   type CapabilityActionDefinition,
   type CapabilityActionManifest,
   CapabilityActionPolicySchema,
@@ -42,6 +54,7 @@ import {
   type CapabilitySearchTagDefinition,
   type CapabilityStreamDefinition,
   type CapabilityUniversalSearchDefinition,
+  CloudResourceViewSchema,
   capabilityActionPolicy,
   capabilityResultSchema,
   UniversalSearchDataSchema,
@@ -83,6 +96,8 @@ const DECLARATION_FIELDS = {
   commands: true,
   fileProvider: true,
   calendarSource: true,
+  events: true,
+  subscribes: true,
 } satisfies DefinedFields<CapabilityDefinitions>;
 const CALENDAR_SOURCE_FIELDS = {
   calendars: true,
@@ -92,7 +107,14 @@ const CALENDAR_SOURCE_FIELDS = {
   delete: true,
 } satisfies DefinedFields<CapabilityCalendarSourceDeclaration>;
 const FILE_PROVIDER_FIELDS = { list: true, read: true, save: true } satisfies DefinedFields<CapabilityFileProviderDeclaration>;
-const TYPE_FIELDS = { title: true, description: true, icon: true, reader: true } satisfies DefinedFields<CapabilityResourceTypeDefinition>;
+const TYPE_FIELDS = {
+  title: true,
+  description: true,
+  icon: true,
+  color: true,
+  reader: true,
+  pages: true,
+} satisfies DefinedFields<CapabilityResourceTypeDefinition>;
 const QUERY_FIELDS = {
   title: true,
   description: true,
@@ -160,7 +182,12 @@ export type CompiledCapabilityAction = {
   resultSchema: z.ZodType;
 };
 
+export type CompiledAppEvent = { definition: AppEventDefinition; manifest: CapabilityEventManifest };
+export type CompiledAppEventSubscription = { definition: AppEventSubscriptionDefinition; manifest: CapabilitySubscriptionManifest };
+
 export type CompiledCapabilities = {
+  events: ReadonlyMap<string, CompiledAppEvent>;
+  subscribes: ReadonlyMap<string, CompiledAppEventSubscription>;
   manifest: CapabilityManifest;
   presentation?: CapabilityPresentationCatalog;
   typeIds: ReadonlySet<string>;
@@ -443,6 +470,7 @@ export const compileCapabilityPresentation = (
   const queries = new Map(manifest.queries.map((operation) => [operation.localId, operation]));
   const actions = new Map(manifest.actions.map((operation) => [operation.localId, operation]));
   const commands = new Map(manifest.commands.map((operation) => [operation.localId, operation]));
+  const events = new Map((manifest.events ?? []).map((event) => [event.localId, event]));
   let sentences: Record<string, CapabilityActionSentences> | undefined;
   if (catalog.sentences !== undefined) {
     if (!catalog.sentences || typeof catalog.sentences !== "object" || Array.isArray(catalog.sentences)) {
@@ -470,7 +498,9 @@ export const compileCapabilityPresentation = (
       throw new Error(`Capability presentation translation ${canonical} must be an object`);
     }
     const raw = rawTranslation as Record<string, unknown>;
-    const extra = Object.keys(raw).find((key) => key !== "types" && key !== "queries" && key !== "actions" && key !== "commands");
+    const extra = Object.keys(raw).find(
+      (key) => key !== "types" && key !== "queries" && key !== "actions" && key !== "commands" && key !== "events",
+    );
     if (strict && extra) throw new Error(`Capability presentation translation ${canonical} contains unsupported field "${extra}"`);
     const compileGroup = <T>(
       group: unknown,
@@ -514,12 +544,20 @@ export const compileCapabilityPresentation = (
         ...(copy.description ? { description: String(copy.description).trim() } : {}),
       };
     });
+    const translatedEvents = compileGroup(raw.events, events, "Event", (entry, _definition, label) => {
+      const parsed = z.object({
+        title: z.string().trim().min(1).max(120).optional(),
+        description: z.string().trim().min(1).max(1000).optional(),
+      });
+      return (strict ? parsed.strict() : parsed).parse(entry);
+    });
     const operationPresentation = (entry: unknown, operation: Parameters<typeof compileOperationPresentation>[1], label: string) =>
       compileOperationPresentation(entry, operation, label, strict);
     const translatedQueries = compileGroup(raw.queries, queries, "Query", operationPresentation);
     const translatedActions = compileGroup(raw.actions, actions, "Action", operationPresentation);
     const translatedCommands = compileGroup(raw.commands, commands, "Command", operationPresentation);
     translations[canonical] = {
+      ...(translatedEvents ? { events: translatedEvents } : {}),
       ...(translatedTypes ? { types: translatedTypes } : {}),
       ...(translatedQueries ? { queries: translatedQueries } : {}),
       ...(translatedActions ? { actions: translatedActions } : {}),
@@ -634,7 +672,11 @@ const compileOperationSchemas = (definition: CapabilityQueryDefinition | Capabil
   };
 };
 
-export const compileCapabilities = (appId: string, definitions: CapabilityDefinitions): CompiledCapabilities => {
+export const compileCapabilities = (
+  appId: string,
+  definitions: CapabilityDefinitions,
+  routes?: readonly string[],
+): CompiledCapabilities => {
   if (definitions.protocolVersion !== CAPABILITY_PROTOCOL_VERSION) {
     throw new Error(`Unsupported capability protocol version ${String(definitions.protocolVersion)}`);
   }
@@ -658,6 +700,15 @@ export const compileCapabilities = (appId: string, definitions: CapabilityDefini
     .map(([localId, definition]) => {
       registerLocalId(localId, "Resource type");
       assertDefinedFields(definition, TYPE_FIELDS, `Resource type ${localId}`);
+      if (definition.pages !== undefined) {
+        if (!definition.reader) throw new Error(`Resource type ${localId}: pages require a reader`);
+        if (!Array.isArray(definition.pages) || definition.pages.length > RESOURCE_PAGES_PER_TYPE)
+          throw new Error(`Resource type ${localId}: at most ${RESOURCE_PAGES_PER_TYPE} pages are allowed`);
+        for (const path of definition.pages) {
+          const issue = typeof path === "string" ? resourcePageIssue(path, routes, appId) : "Expected a page pattern string";
+          if (issue) throw new Error(`Resource type ${localId} pages: ${issue}`);
+        }
+      }
       assertText(definition.title, `Resource type ${localId} title`, 120);
       assertText(definition.description, `Resource type ${localId} description`, 500);
       return {
@@ -665,6 +716,7 @@ export const compileCapabilities = (appId: string, definitions: CapabilityDefini
         title: definition.title.trim(),
         description: definition.description.trim(),
         ...(definition.icon ? { icon: definition.icon } : {}),
+        ...(definition.color !== undefined ? { color: z.enum(CAPABILITY_RESOURCE_COLORS).parse(definition.color) } : {}),
         ...(definition.reader !== undefined ? { reader: CapabilityLocalIdSchema.parse(definition.reader) } : {}),
       };
     });
@@ -821,18 +873,74 @@ export const compileCapabilities = (appId: string, definitions: CapabilityDefini
       });
     });
 
+  const events = new Map<string, CompiledAppEvent>();
+  for (const [localId, definition] of Object.entries(definitions.events ?? {}).sort(([a], [b]) => a.localeCompare(b))) {
+    registerLocalId(localId, "Event");
+    assertDefinedFields(
+      definition,
+      {
+        version: true,
+        title: true,
+        description: true,
+        subject: true,
+        place: true,
+        schema: true,
+        automation: true,
+      } satisfies DefinedFields<AppEventDefinition>,
+      `Event ${localId}`,
+    );
+    if (!types.some((type) => type.localId === definition.subject)) throw new Error(`Event ${localId} subject must reference a local Type`);
+    if (definition.place && !types.some((type) => type.localId === definition.place && type.reader))
+      throw new Error(`Event ${localId} place must reference a local Type with a reader`);
+    const schemas = compileAppEventSchema(definition.schema, `Event ${localId} data`);
+    assertAppEventDeclarationSize(appId, localId, definition, schemas.dataSchema);
+    const manifest = CapabilityEventManifestSchema.parse({
+      localId,
+      version: definition.version,
+      title: definition.title,
+      description: definition.description,
+      subject: definition.subject,
+      ...(definition.place !== undefined ? { place: definition.place } : {}),
+      ...schemas,
+      ...(definition.automation !== undefined ? { automation: definition.automation } : {}),
+    });
+    events.set(localId, { definition, manifest });
+  }
+  const subscribes = new Map<string, CompiledAppEventSubscription>();
+  for (const [type, definition] of Object.entries(definitions.subscribes ?? {}).sort(([a], [b]) => a.localeCompare(b))) {
+    CapabilityQualifiedIdSchema.parse(type);
+    assertDefinedFields(
+      definition,
+      { version: true, schema: true, run: true } satisfies DefinedFields<AppEventSubscriptionDefinition>,
+      `Subscription ${type}`,
+    );
+    if (typeof definition.run !== "function") throw new Error(`Subscription ${type} needs run`);
+    const manifest = CapabilitySubscriptionManifestSchema.parse({
+      type,
+      version: definition.version,
+      ...compileAppEventSchema(definition.schema, `Subscription ${type} data`, "reader"),
+    });
+    subscribes.set(type, { definition, manifest });
+  }
+
   const policies = Object.fromEntries(
     [...actions].flatMap(([localId, action]) => (action.definition.policy ? [[localId, action.definition.policy]] : [])),
   );
   const fileProvider = definitions.fileProvider;
   const calendarSource = definitions.calendarSource;
+  const resourcePages = Object.entries(definitions.types ?? {})
+    .sort(([a], [b]) => a.localeCompare(b))
+    .flatMap(([type, definition]) => (definition.pages ?? []).map((path) => ({ type, path })));
   const manifestBase = {
+    ...(resourcePages.length ? { resourcePages } : {}),
     protocolVersion: CAPABILITY_PROTOCOL_VERSION,
     appId,
     types,
     queries: [...queries.values()].map((entry) => entry.manifest),
     actions: [...actions.values()].map((entry) => entry.manifest),
     commands,
+    ...(definitions.events !== undefined ? { events: [...events.values()].map((event) => event.manifest) } : {}),
+    ...(definitions.subscribes !== undefined ? { subscribes: [...subscribes.values()].map((subscription) => subscription.manifest) } : {}),
     ...(Object.keys(policies).length ? { policies } : {}),
     // Omitted when unused so manifests without a provider keep their earlier hash.
     ...(calendarSource ? { calendarSource: { ...calendarSource } } : {}),
@@ -862,7 +970,7 @@ export const compileCapabilities = (appId: string, definitions: CapabilityDefini
     throw new Error(`Capability manifest exceeds the ${MAX_CAPABILITY_MANIFEST_BYTES}-byte registry limit`);
   }
   const presentation = compileCapabilityPresentation(manifest, definitions.presentation);
-  return { manifest, presentation, typeIds, queries, actions };
+  return { manifest, presentation, typeIds, queries, actions, events, subscribes };
 };
 
 const applySchemaPresentation = (schema: Record<string, unknown>, descriptions: Readonly<Record<string, string>> | undefined) => {
@@ -1007,6 +1115,16 @@ export const resolveCapabilityManifestPresentation = (
             }
           : operation;
       }),
+      ...(current.events
+        ? {
+            events: current.events.map((event) => {
+              const copy = translation.events?.[event.localId];
+              return copy ? { ...event, title: copy.title ?? event.title, description: copy.description ?? event.description } : event;
+            }),
+          }
+        : {}),
+      ...(current.subscribes ? { subscribes: current.subscribes } : {}),
+      ...(current.resourcePages ? { resourcePages: current.resourcePages } : {}),
       ...(current.calendarSource ? { calendarSource: current.calendarSource } : {}),
       ...(current.fileProvider ? { fileProvider: current.fileProvider } : {}),
       ...(current.policies ? { policies: current.policies } : {}),
@@ -1047,16 +1165,26 @@ const assertUsableOperation = (operation: CapabilityQueryManifest | CapabilityAc
   if (operation.schemaHash !== expectedSchemaHash) throw new Error(`Operation ${operation.localId} schemaHash does not match its schemas`);
   if ("universalSearch" in operation && operation.universalSearch) {
     const expectedInput = projectSchema(UniversalSearchInputSchema, "Universal Search input", "input");
-    const expectedData = projectSchema(UniversalSearchDataSchema, "Universal Search data", "output");
     if (
       capabilityHash(operation.inputSchema) !== capabilityHash(expectedInput) ||
-      capabilityHash(operation.dataSchema) !== capabilityHash(expectedData)
+      !universalSearchDataHashes().includes(capabilityHash(operation.dataSchema))
     ) {
       throw new Error(`Operation ${operation.localId} advertises Universal Search with non-canonical schemas`);
     }
   }
 };
 
+/**
+ * The Universal Search data schemas a live manifest may declare: the current one, and the one before results gained
+ * `context` and `status`, so an app built by the previous release keeps its search while Core is already newer. Its
+ * results still parse, because both fields are optional.
+ */
+let searchDataHashes: string[] | undefined;
+const universalSearchDataHashes = () =>
+  (searchDataHashes ??= [UniversalSearchDataSchema, z.array(CloudResourceViewSchema.omit({ context: true, status: true })).max(100)].map(
+    (schema) => capabilityHash(projectSchema(schema, "Universal Search data", "output")),
+  ));
+
 const assertUsableCommand = (command: CapabilityCommandManifest): void => {
   z.fromJSONSchema(structuredClone(command.inputSchema));
   assertClosedObjectInput(command.inputSchema, `Command ${command.localId} input`);
@@ -1079,7 +1207,7 @@ export const parseCapabilityManifest = (value: unknown, expectedAppId: string):
   const sent = CapabilityManifestSchema.parse(value);
   if (sent.appId !== expectedAppId) throw new Error(`manifest appId must be ${expectedAppId}`);
   const localIds = new Set<string>();
-  for (const { localId } of [...sent.types, ...sent.queries, ...sent.actions, ...sent.commands]) {
+  for (const { localId } of [...sent.types, ...sent.queries, ...sent.actions, ...sent.commands, ...(sent.events ?? [])]) {
     if (localIds.has(localId)) throw new Error(`localId ${localId} is declared more than once across Types, Queries, and Actions`);
     localIds.add(localId);
   }
@@ -1087,15 +1215,27 @@ export const parseCapabilityManifest = (value: unknown, expectedAppId: string):
   const { manifestHash: _sentHash, ...sentBase } = value as Record<string, unknown>;
   if (sent.manifestHash !== capabilityHash(sentBase)) throw new Error("manifestHash does not match the manifest");
 
+  const usableEventSchema = (entry: CapabilityEventManifest | CapabilitySubscriptionManifest) => {
+    assertBoundedAppEventSchema(entry.dataSchema);
+    if (entry.schemaHash !== capabilityHash({ dataSchema: entry.dataSchema }))
+      throw new Error("Event schemaHash does not match its schema");
+  };
+  const subscriptionTypes = new Set<string>();
+  for (const subscription of sent.subscribes ?? []) {
+    if (subscriptionTypes.has(subscription.type)) throw new Error(`Duplicate subscription ${subscription.type}`);
+    subscriptionTypes.add(subscription.type);
+  }
   // Reading the usable entries again leaves out what depends on an entry left out here.
   const manifest = CapabilityManifestSchema.parse({
     ...sent,
+    ...(sent.events ? { events: sent.events.filter((event) => passes(() => usableEventSchema(event))) } : {}),
+    ...(sent.subscribes ? { subscribes: sent.subscribes.filter((subscription) => passes(() => usableEventSchema(subscription))) } : {}),
     queries: sent.queries.filter((query) => passes(() => assertUsableOperation(query))),
     actions: sent.actions.filter((action) => passes(() => assertUsableOperation(action))),
     commands: sent.commands.filter((command) => passes(() => assertUsableCommand(command))),
   });
   const queries = new Map(manifest.queries.map((query) => [query.localId, query]));
-  return {
+  return CapabilityManifestSchema.parse({
     ...manifest,
     types: manifest.types.map((type) => {
       const reader = type.reader === undefined ? undefined : queries.get(type.reader);
@@ -1104,7 +1244,7 @@ export const parseCapabilityManifest = (value: unknown, expectedAppId: string):
       const { reader: _unusable, ...withoutReader } = type;
       return withoutReader;
     }),
-  };
+  });
 };
 
 const schemaSemantics = (value: unknown): unknown => {
@@ -1435,7 +1575,10 @@ export const invokeCompiledCapability = async (params: {
       },
     };
   }
-  let context = params.context;
+  let context: CapabilityExecutionContext = {
+    ...params.context,
+    via: capabilityVia(params.context.origin),
+  };
   if (params.kind === "action") {
     const action = operation as CompiledCapabilityAction;
     if (action.manifest.idempotency === "required" && !params.context.idempotencyKey) {
@@ -1481,7 +1624,7 @@ export const invokeCompiledCapability = async (params: {
         },
       };
     }
-    context = { ...params.context, idempotencyKey: idempotencyKey.data };
+    context = { ...context, idempotencyKey: idempotencyKey.data };
   }
   const input = operation.definition.input.safeParse(params.input);
   if (!input.success) {
@@ -1603,7 +1746,10 @@ export const reviewCompiledCapability = async (params: {
   }
   if (params.context.signal.aborted) return cancelledInvocation(params.context.locale);
   try {
-    const reviewed = await operation.definition.review(input.data, params.context);
+    const reviewed = await operation.definition.review(input.data, {
+      ...params.context,
+      via: capabilityVia(params.context.origin),
+    });
     if (!reviewed.ok) {
       return normalizeProviderError(reviewed.error, "Capability review returned an invalid error", params.onUnexpectedError);
     }

package/src/_internal/capability-origin.ts

@@ -0,0 +1,4 @@
+import type { CapabilityOrigin, CapabilityVia } from "../contracts/capabilities";
+
+/** Visible provenance never changes the authority of an invocation. */
+export const capabilityVia = (origin: CapabilityOrigin): CapabilityVia => (origin === "assistant" || origin === "mcp" ? origin : null);

package/src/_internal/capability-streams.ts

@@ -9,6 +9,7 @@ import {
 } from "../contracts/capabilities";
 import { hasOAuthScope } from "../server/oauth-scope";
 import type { CompiledCapabilities } from "./capabilities";
+import { capabilityVia } from "./capability-origin";
 import { capabilityActionReceiptIssues } from "./capability-reviews";
 
 const failure = (status: number, code: string, message: string) => Response.json({ code, message }, { status });
@@ -38,13 +39,14 @@ export async function invokeCapabilityStream(params: {
     }
     return parsed;
   };
+  const context = { ...params.context, via: capabilityVia(params.context.origin) };
   try {
     const stream = CapabilityStreamSchema.parse(JSON.parse(Buffer.from(offer, "base64url").toString()));
     if (stream.direction !== definition.direction || stream.size > definition.maxBytes || Date.parse(stream.expiresAt) <= Date.now())
       return failure(410, "STREAM_EXPIRED", "Stream expired or outside its byte budget");
     if (definition.direction === "read") {
       if (params.verb !== "read") return failure(403, "STREAM_DENIED", "Read-only stream");
-      const response = await definition.read(stream, params.context);
+      const response = await definition.read(stream, context);
       if (!response.ok || !response.body) {
         await response.body?.cancel();
         return failure(502, "STREAM_FAILED", "Source could not be read");
@@ -65,18 +67,18 @@ export async function invokeCapabilityStream(params: {
         stream.size,
       );
       try {
-        const value = await definition.write(stream, body, params.context);
+        const value = await definition.write(stream, body, context);
         result = receipt(value);
       } finally {
         if (!body.locked) await body.cancel().catch(() => undefined);
       }
     } else if (params.verb === "status") {
-      const status = CapabilityStreamStatusSchema.parse(await definition.status(stream, params.context));
+      const status = CapabilityStreamStatusSchema.parse(await definition.status(stream, context));
       if (status.state === "completed") receipt(status.result);
       result = status;
     } else if (params.verb === "abort") {
-      await definition.abort(stream, params.context);
-      const status = CapabilityStreamStatusSchema.parse(await definition.status(stream, params.context));
+      await definition.abort(stream, context);
+      const status = CapabilityStreamStatusSchema.parse(await definition.status(stream, context));
       if (status.state === "completed") receipt(status.result);
       result = status;
     } else return failure(400, "STREAM_INVALID", "Unknown stream operation");

package/src/_internal/define-app.ts

@@ -1,12 +1,18 @@
 import { type AppSkillDefinition, appSkillManifestHash, registerAppSkills, validateAppSkillCatalog } from "../ai/app-skills";
 import { createOwnedAppAccessRoutes } from "../api/app-access";
+import { createAppEventDeliveryRoutes } from "../api/app-event-delivery";
+import { createResourceAppAccessRoutes } from "../api/app-resource-access";
 import { type AppAccessDeclaration, compileAppAccess } from "../contracts/app-access";
+import { startAppEventDelivery } from "../events/app-event-delivery";
+import { bindAppEvents } from "../events/app-events";
 import { startLiveOutbox } from "../events/live";
 import { registerHelp } from "../services/help";
 import { preloadLayoutHelp } from "../ssr/help";
 import { registerPageSwap } from "../ssr/page-swap";
 import { preloadPanelConsent } from "../ssr/panel-consent";
 import { appAccessManagementPath } from "./app-access-path";
+import { bindResourceAppAccess, RESOURCE_ACCESS_PATH } from "./app-access-resources";
+import { registerApplicationPackage, resolveApplicationPackage } from "./application-package";
 import { invokeCapabilityStream } from "./capability-streams";
 import { withCapabilityRequestTimeout } from "./capability-timeout";
 import { bindProcessApplicationId, clearProcessApplicationId } from "./process-identity";
@@ -28,6 +34,7 @@ import { generateSpecs } from "hono-openapi";
 import { CLOUD_CLI_PLUGIN_ROUTE } from "../cli/plugin";
 import { env } from "../config/env";
 import type {
+  AppAdminArea,
   AppAdminNavigationGroup,
   AppAppearance,
   AppCliModules,
@@ -151,6 +158,8 @@ type ResolvedPageOptions = PageOptions & {
  */
 export type AppOptions<S extends AppSettingsMap = {}, N extends NotificationDefinitionMap = {}, AppId extends string = string> = {
   id: AppId;
+  /** Shared object-store package. Defaults to the app ID. */
+  package?: string;
   access?: AppAccessDeclaration;
   name: string;
   icon: string;
@@ -167,7 +176,7 @@ export type AppOptions<S extends AppSettingsMap = {}, N extends NotificationDefi
   adminHref?: string;
   /** Multi-link admin navigation contributed by this app. */
   adminNav?: ReadonlyArray<{
-    section?: "ai";
+    section?: AppAdminArea;
     id?: string;
     label: string;
     links: ReadonlyArray<{ label: string; href: string; icon: string }>;
@@ -183,7 +192,7 @@ export type AppOptions<S extends AppSettingsMap = {}, N extends NotificationDefi
      * Same-origin path of a `GET` route this app serves below one of its
      * `routes`. After the page loads, the shell reads it with the person's
      * session and shows the returned `AppNavBadge` count on the app's icon in
-     * the rail and the app grid. Protect it like any other route.
+     * the rail, the phone bar, and the app grid. Protect it like any other route.
      */
     badge?: string;
   };
@@ -224,6 +233,17 @@ export type AppOptions<S extends AppSettingsMap = {}, N extends NotificationDefi
   pwa?: {
     /** Coarse visibility in the mobile app, like `nav.requiresRoles`. Routes and services still authorize. */
     requiresRoles?: Role[];
+    /**
+     * Same-origin path of a `GET` route this app serves that returns an `AppNavBadge`: the count beside the part in
+     * the app's sidebar, such as unread messages. Like `nav.badge`, it must be one of the app's own paths.
+     */
+    badge?: string;
+    /**
+     * Same-origin path of a `GET` route this app serves that returns a `PwaPartSummary`: one line under the part on
+     * Start, such as "5 tasks for you", in the reader's locale, and its count beside the part in the sidebar when the
+     * part has no `badge`. It may be the badge's route. It must be one of the app's own paths.
+     */
+    summary?: string;
   };
   /**
    * Dashboard widget endpoints this app exposes. Each entry references an
@@ -396,7 +416,21 @@ const validateAppPwaPart = (opts: Pick<AppOptions, "id" | "routes" | "pwa">): Ap
   if (!isPwaPartId(opts.id)) {
     throw new Error(`App "${opts.id}" cannot declare pwa; a part needs a plain id other than pwa, settings and offline`);
   }
-  return { href: `/pwa/${opts.id}`, requiresRoles: opts.pwa.requiresRoles ? [...opts.pwa.requiresRoles] : undefined };
+  const { badge, summary } = opts.pwa;
+  for (const [field, path] of [
+    ["badge", badge],
+    ["summary", summary],
+  ] as const) {
+    if (path !== undefined && !isOwnAppPath(path, [...opts.routes, `/pwa/${opts.id}`])) {
+      throw new Error(`App "${opts.id}" declares pwa.${field} "${path}"; it must be a same-origin path below one of its routes`);
+    }
+  }
+  return {
+    href: `/pwa/${opts.id}`,
+    requiresRoles: opts.pwa.requiresRoles ? [...opts.pwa.requiresRoles] : undefined,
+    ...(badge ? { badge } : {}),
+    ...(summary ? { summary } : {}),
+  };
 };
 
 /** The badge route is read by the browser through the gateway, so it must be one of this app's own paths. */
@@ -448,6 +482,7 @@ export const defineApp = <
   const notifications = bindNotificationDefinitions(opts.id, opts.notifications);
   const cliModules = validateAppCliModules(opts.id, opts.cli);
   const pwaPart = validateAppPwaPart(opts);
+  const packageName = resolveApplicationPackage(opts.id, opts.package);
   const installable = opts.installable === undefined ? undefined : validateInstallable(opts.id, opts.routes, opts.installable);
   if (installable === null)
     throw new Error(`App "${opts.id}" declares invalid installable; use a canonical own /app/<id>/<surface>/ path covered by routes`);
@@ -616,6 +651,7 @@ export const defineApp = <
 
   // ── 2. Meta ───────────────────────────────────────────────────────────
   const baseMeta: AppMeta = {
+    package: packageName,
     id: opts.id,
     platformPermissions: opts.platformPermissions
       ? opts.platformPermissions.map((permission) => PlatformPermissionSchema.parse(permission))
@@ -685,7 +721,8 @@ export const defineApp = <
         }
       })());
     try {
-      bindProcessApplicationId(meta.id, meta.platformPermissions);
+      await registerApplicationPackage(meta.id, packageName);
+      bindProcessApplicationId(meta.id, meta.platformPermissions, packageName);
       cleanup.unshift(clearProcessApplicationId);
       const startedAt = Date.now();
 
@@ -693,7 +730,8 @@ export const defineApp = <
       // derive the spec from. The mount block lower down uses the same
       // flag so the registry never points at a URL that 404s.
       const advertiseOpenapi = !!(opts.openapi && startOpts.openapi);
-      const compiledCapabilities = startOpts.capabilities ? compileCapabilities(meta.id, startOpts.capabilities) : undefined;
+      const compiledCapabilities = startOpts.capabilities ? compileCapabilities(meta.id, startOpts.capabilities, meta.routes) : undefined;
+      if (startOpts.capabilities) bindAppEvents(meta.id, startOpts.capabilities, compiledCapabilities);
       const compiledHelp = startOpts.help
         ? compileHelp({
             appId: meta.id,
@@ -704,6 +742,7 @@ export const defineApp = <
 
       // Registry entry
       const entry: AppRegistryEntry = {
+        package: packageName,
         id: meta.id,
         access: meta.access,
         name: meta.name,
@@ -744,7 +783,12 @@ export const defineApp = <
         legalLinks: meta.legalLinks ? meta.legalLinks.map((l) => ({ ...l })) : undefined,
         searchLinks: meta.searchLinks,
         pwa: meta.pwa
-          ? { href: meta.pwa.href, requiresRoles: meta.pwa.requiresRoles ? [...meta.pwa.requiresRoles] : undefined }
+          ? {
+              href: meta.pwa.href,
+              requiresRoles: meta.pwa.requiresRoles ? [...meta.pwa.requiresRoles] : undefined,
+              ...(meta.pwa.badge ? { badge: meta.pwa.badge } : {}),
+              ...(meta.pwa.summary ? { summary: meta.pwa.summary } : {}),
+            }
           : undefined,
         installable: meta.installable,
         panel: meta.panel
@@ -868,6 +912,9 @@ export const defineApp = <
 
       if (installable) server.route("/", createInstallableRoutes(meta.id, installable));
 
+      if (compiledCapabilities?.subscribes.size)
+        server.route("/api/_internal/events/v1", createAppEventDeliveryRoutes(compiledCapabilities));
+
       if (compiledCapabilities) {
         const invoke = async (c: Context<AuthContext>, kind: "query" | "action" | "review") =>
           withCapabilityRequestTimeout(c, kind, async () => {
@@ -1030,6 +1077,8 @@ export const defineApp = <
         );
       }
 
+      cleanup.push(bindResourceAppAccess(meta.id, opts.access));
+      server.route(RESOURCE_ACCESS_PATH, createResourceAppAccessRoutes(meta));
       cleanup.push(() => stopAppAccessConnections());
       if (meta.access?.kind === "grants") {
         server.route(appAccessManagementPath(meta), createOwnedAppAccessRoutes(meta, opts.access?.canManage));
@@ -1100,6 +1149,8 @@ export const defineApp = <
       const startOutbox = async () => {
         const stopLiveOutbox = await startLiveOutbox(meta.id);
         if (stopLiveOutbox) cleanup.push(stopLiveOutbox);
+        const stopAppEvents = await startAppEventDelivery(meta.id);
+        if (stopAppEvents) cleanup.push(stopAppEvents);
       };
       // An application fails before any setup when Core has not created the platform outbox yet.
       // Core creates it in its own setup, so it starts publishing after that.

package/src/_internal/object-store-area.ts

@@ -0,0 +1,9 @@
+import { getProcessApplicationPackage } from "./process-identity";
+
+/** The single application-to-area mapping. No caller-supplied application or area ID. */
+export const objectStoreArea = (visibility: "private" | "public" = "private"): string => {
+  const packageName = getProcessApplicationPackage();
+  if (!packageName) throw new Error("Start the application before using the object store.");
+  if (!/^[a-z][a-z0-9-]{0,79}$/.test(packageName)) throw new Error("Invalid object-store application package.");
+  return `${visibility}/${packageName}/`;
+};