@k2b/cloud 0.6.0 → 0.8.0

package/src/api/capability-streams.ts

@@ -0,0 +1,262 @@
+import { z } from "zod";
+import { readBoundedJson } from "../_internal/bounded-json";
+import { getCapability } from "../_internal/registry";
+import { recordCapabilityExecution } from "../capabilities/executions";
+import { exactStream } from "../capabilities/stream-body";
+import type { CapabilityStream } from "../contracts/capabilities";
+import {
+  CAPABILITY_MAX_RESULT_BYTES,
+  CAPABILITY_ORIGIN_HEADER,
+  CapabilityErrorSchema,
+  CapabilityOriginSchema,
+  CapabilityStreamSchema,
+  CapabilityStreamStatusSchema,
+  capabilityResultSchema,
+} from "../contracts/capabilities";
+import type { RequestAuthority } from "../server";
+import { invocationAuthorityFromRequest } from "../services/identity/invocation-authority";
+import { capabilityInvocationOperation } from "../services/identity/invocation-operations";
+import { signInvocationToken } from "../services/identity/invocation-token";
+import { withActiveIdentitySigner } from "../services/identity/key-ring";
+import { logger } from "../services/logging";
+import { decryptSecret, encryptSecret } from "../services/secrets";
+import { LOCALE_HEADER } from "../shared/locale";
+import type { CapabilityDispatchDependencies } from "./capabilities";
+
+const log = logger("capability-streams");
+
+const Grant = z.object({
+  purpose: z.literal("capability-stream-v2"),
+  continuation: z.string().nullable(),
+  origin: CapabilityOriginSchema.default("http"),
+  appId: z.string(),
+  kind: z.enum(["queries", "actions"]),
+  capabilityId: z.string(),
+  schemaHash: z.string(),
+  authority: z.string(),
+  stream: CapabilityStreamSchema,
+  requestId: z.string(),
+});
+const binding = (authority: RequestAuthority) => JSON.stringify(invocationAuthorityFromRequest(authority));
+export async function sealCapabilityStream(
+  stream: CapabilityStream,
+  params: {
+    appId: string;
+    kind: "queries" | "actions";
+    capabilityId: string;
+    schemaHash: string;
+    authority: RequestAuthority;
+    requestId: string;
+    origin?: z.infer<typeof CapabilityOriginSchema>;
+    continuation?: string;
+  },
+): Promise<CapabilityStream> {
+  if (Buffer.byteLength(stream.id) > 2048) throw new Error("Provider stream ID exceeds 2 KiB");
+  const grant = Grant.parse({
+    ...params,
+    purpose: "capability-stream-v2",
+    continuation: params.continuation ?? null,
+    authority: binding(params.authority),
+    stream,
+  });
+  return CapabilityStreamSchema.parse({ ...stream, id: await encryptSecret(grant) });
+}
+const denied = (status = 403, code = "STREAM_DENIED") =>
+  Response.json({ code, message: "Stream unavailable or not authorized" }, { status });
+
+/** A transfer continues an already-authorized operation; it cannot manufacture a new Action. */
+export async function dispatchCapabilityStream(
+  request: Request,
+  authority: RequestAuthority,
+  verb: string,
+  dependencies: CapabilityDispatchDependencies & {
+    recordStreamExecution?: typeof recordCapabilityExecution;
+    continuation?: string;
+    allow?: (operation: { appId: string; capabilityId: string }) => Promise<boolean>;
+  } = {},
+): Promise<Response> {
+  const id = request.headers.get("x-cloud-stream-id");
+  if (!id || id.length > 8192 || !["read", "write", "status", "abort"].includes(verb)) return denied(400);
+  let grant: z.infer<typeof Grant>;
+  try {
+    grant = Grant.parse(await decryptSecret(id));
+  } catch {
+    return denied();
+  }
+  try {
+    if (grant.authority !== binding(authority)) return denied();
+  } catch {
+    return denied();
+  }
+  if (grant.continuation !== (dependencies.continuation ?? null)) return denied();
+  if (dependencies.allow && !(await dependencies.allow(grant))) return denied();
+  if (Date.parse(grant.stream.expiresAt) <= Date.now()) return denied(410, "STREAM_EXPIRED");
+  if ((verb === "read") !== (grant.stream.direction === "read")) return denied();
+  if (
+    authority.credentialKind === "oauth" &&
+    !authority.scopes.some((scope) => scope === "admin" || scope === (grant.kind === "actions" ? "write" : "read"))
+  )
+    return denied();
+  const startedAt = new Date();
+  let recorded = false;
+  let destructive = false;
+  const record = async (status: number, errorCode: string | null = null) => {
+    if (recorded || (verb !== "read" && verb !== "write")) return;
+    recorded = true;
+    const actor = authority.actor;
+    const actorId = actor.kind === "user" ? actor.user.id : actor.serviceAccount.id;
+    const subject = authority.accessSubject;
+    const subjectId = subject.type === "user" ? subject.userId : subject.serviceAccountId;
+    await (dependencies.recordStreamExecution ?? recordCapabilityExecution)({
+      requestId: grant.requestId,
+      origin: grant.origin,
+      appId: grant.appId,
+      capability: `${grant.appId}.${grant.capabilityId}`,
+      kind: grant.kind === "queries" ? "query" : "action",
+      destructive,
+      actorKind: actor.kind,
+      actorId,
+      userId: actor.kind === "user" ? actor.user.id : (actor.delegatedUser?.id ?? null),
+      accessSubject: subjectId !== actorId ? { type: subject.type, id: subjectId } : null,
+      status: status < 400 ? "succeeded" : status === 403 ? "denied" : status === 504 ? "timed_out" : "failed",
+      errorCode,
+      inputMeta: { type: "object", keys: [`stream.${verb}`], omittedKeys: 0 },
+      outputMeta: status < 400 ? { type: "number", value: grant.stream.size } : null,
+      startedAt,
+      completedAt: new Date(),
+    }).catch(() => log.error("Stream execution could not be recorded", { requestId: grant.requestId }));
+  };
+  const signal = AbortSignal.any([request.signal, AbortSignal.timeout(300_000)]);
+  try {
+    const entry = await (dependencies.getCapability ?? getCapability)(grant.appId);
+    const operation = entry?.manifest[grant.kind].find((item) => item.localId === grant.capabilityId);
+    if (
+      !entry ||
+      !operation ||
+      operation.schemaHash !== grant.schemaHash ||
+      operation.stream?.direction !== grant.stream.direction ||
+      grant.stream.size > operation.stream.maxBytes
+    )
+      return denied(409, "SCHEMA_MISMATCH");
+    destructive = "destructive" in operation && operation.destructive;
+    const signed = await (dependencies.withActiveSigner ?? withActiveIdentitySigner)(
+      "invocation",
+      (signer) =>
+        (dependencies.signInvocation ?? signInvocationToken)({
+          targetAppId: grant.appId,
+          callingAppId: "core",
+          operation: capabilityInvocationOperation(grant.kind, grant.capabilityId),
+          schemaHash: operation.schemaHash,
+          authority: invocationAuthorityFromRequest(authority),
+          requestId: grant.requestId,
+          signer,
+          issuer: signer.issuer,
+        }),
+      { signal, timeoutMs: 30_000 },
+    );
+    const headers = new Headers({
+      authorization: `Bearer ${signed.token}`,
+      "x-request-id": grant.requestId,
+      "x-cloud-capability-schema-hash": operation.schemaHash,
+      "x-cloud-stream-offer": Buffer.from(JSON.stringify(grant.stream)).toString("base64url"),
+      "content-type": "application/octet-stream",
+    });
+    headers.set(CAPABILITY_ORIGIN_HEADER, grant.origin);
+    if (request.headers.has(LOCALE_HEADER)) headers.set(LOCALE_HEADER, request.headers.get(LOCALE_HEADER)!);
+    if (request.headers.has("accept-language")) headers.set("accept-language", request.headers.get("accept-language")!);
+    const body =
+      verb === "write"
+        ? exactStream(
+            request.body ??
+              new ReadableStream({
+                start(c) {
+                  c.close();
+                },
+              }),
+            grant.stream.size,
+          )
+        : undefined;
+    const response = await (dependencies.fetch ?? fetch)(
+      `${entry.endpoint}/streams/${grant.kind}/${encodeURIComponent(grant.capabilityId)}/${verb}`,
+      {
+        method: "POST",
+        headers,
+        body,
+        signal,
+        redirect: "error",
+        // @ts-expect-error Bun and Node stream request bodies use duplex.
+        duplex: body ? "half" : undefined,
+      },
+    );
+    log.info("Capability stream response", {
+      requestId: grant.requestId,
+      appId: grant.appId,
+      capabilityId: grant.capabilityId,
+      verb,
+      status: response.status,
+      bytes: grant.stream.size,
+    });
+    if (verb === "read" && response.ok) {
+      if (!response.body) return denied(502, "STREAM_FAILED");
+      const reader = exactStream(response.body, grant.stream.size).getReader();
+      return new Response(
+        new ReadableStream({
+          async pull(controller) {
+            try {
+              const chunk = await reader.read();
+              if (chunk.done) {
+                await record(200);
+                controller.close();
+              } else controller.enqueue(chunk.value);
+            } catch {
+              await record(502, "STREAM_FAILED");
+              controller.error(new Error("Incomplete capability stream"));
+            }
+          },
+          async cancel(reason) {
+            await reader.cancel(reason).catch(() => undefined);
+            await record(499, "REQUEST_CANCELLED");
+          },
+        }),
+        {
+          headers: {
+            "content-type": grant.stream.mediaType,
+            "content-length": String(grant.stream.size),
+            "cache-control": "no-store",
+            "x-content-type-options": "nosniff",
+          },
+        },
+      );
+    }
+    const receipt = await readBoundedJson(response, CAPABILITY_MAX_RESULT_BYTES);
+    if (!receipt.ok) {
+      await record(502, "STREAM_FAILED");
+      return denied(502, "STREAM_FAILED");
+    }
+    if (response.ok) {
+      const parsed = (verb === "write" ? capabilityResultSchema(z.unknown()) : CapabilityStreamStatusSchema).safeParse(receipt.data);
+      if (!parsed.success) {
+        await record(502, "STREAM_FAILED");
+        return denied(502, "STREAM_FAILED");
+      }
+      const nested =
+        verb === "write" ? parsed.data : "state" in parsed.data && parsed.data.state === "completed" ? parsed.data.result : null;
+      if (nested && typeof nested === "object" && "stream" in nested) {
+        await record(502, "STREAM_FAILED");
+        return denied(502, "STREAM_FAILED");
+      }
+    }
+    if (!response.ok) {
+      const error = CapabilityErrorSchema.safeParse(receipt.data);
+      const status = response.status === 401 ? 502 : response.status;
+      await record(status, error.success ? error.data.code : "STREAM_FAILED");
+      if (!error.success || response.status === 401) return denied(status, "STREAM_FAILED");
+    } else await record(response.status);
+    return Response.json(receipt.data, { status: response.status, headers: { "cache-control": "no-store" } });
+  } catch {
+    const status = request.signal.aborted ? 499 : signal.aborted ? 504 : 502;
+    const code = status === 499 ? "REQUEST_CANCELLED" : status === 504 ? "DEADLINE_EXCEEDED" : "STREAM_FAILED";
+    await record(status, code);
+    return Response.json({ code, message: "Transfer interrupted; inspect write status before retrying" }, { status });
+  }
+}

package/src/api/help.ts

@@ -1,78 +1,42 @@
 import { Hono, type MiddlewareHandler } from "hono";
-import { createHelpCatalog, findHelpDocument, resolveAppHelp, searchHelpCatalog } from "../_internal/help-catalog";
-import { getApp, getHelp } from "../_internal/registry";
-import type { AppRegistryEntry, HelpRegistryEntry } from "../contracts/registry";
 import { type AuthContext, auth, getLocale } from "../server";
+import { createHelpReader, type HelpReaderFactory } from "../services/help";
 import type { HelpDocumentPayload, HelpSearchPayload } from "../shared/help";
 import { renderHelpMarkdown } from "../shared/markdown";
-import { type HelpApiMessages, helpApiMessages } from "./help-messages";
+import { helpApiMessages } from "./help-messages";
 
 export type HelpRouteDependencies = {
-  getApp?: (appId: string) => Promise<AppRegistryEntry | null>;
-  getHelp?: (appId: string) => Promise<HelpRegistryEntry | null>;
+  help?: HelpReaderFactory;
   authenticate?: MiddlewareHandler<AuthContext>;
   renderMarkdown?: (markdown: string) => string;
 };
 
-const resolveHelp = async (appId: string, dependencies: HelpRouteDependencies, t: HelpApiMessages) => {
-  const resolved = await resolveAppHelp(appId, { getApp: dependencies.getApp ?? getApp, getHelp: dependencies.getHelp ?? getHelp });
-  if (resolved.status === "missing") {
-    return Response.json({ code: "APP_UNAVAILABLE", message: t.unavailable({ appId }) }, { status: 404 });
-  }
-  if (resolved.status === "stale") {
-    return Response.json({ code: "HELP_STALE", message: t.stale({ appId }) }, { status: 503 });
-  }
-  return resolved;
-};
-
 export const createHelpRoutes = (dependencies: HelpRouteDependencies = {}) => {
-  const renderedByApp = new Map<string, { manifestHash: string; documents: Map<string, string> }>();
-  const renderMarkdown = dependencies.renderMarkdown ?? renderHelpMarkdown;
-  const renderDocument = (help: HelpRegistryEntry, locale: string, documentId: string, markdown: string): string => {
-    let cached = renderedByApp.get(help.appId);
-    if (!cached || cached.manifestHash !== help.manifestHash) {
-      cached = { manifestHash: help.manifestHash, documents: new Map() };
-      renderedByApp.set(help.appId, cached);
-    }
-    const cacheKey = `${locale}:${documentId}`;
-    const html = cached.documents.get(cacheKey);
-    if (html !== undefined) return html;
-    const rendered = renderMarkdown(markdown);
-    cached.documents.set(cacheKey, rendered);
-    return rendered;
-  };
-
+  const reader = dependencies.help ?? createHelpReader;
   return new Hono<AuthContext>()
     .use(dependencies.authenticate ?? auth.requireRole("*"))
     .get("/help/v1/:appId/search", async (c) => {
       const locale = getLocale(c);
-      const { t } = helpApiMessages.resolve([locale]);
-      const resolved = await resolveHelp(c.req.param("appId"), dependencies, t);
-      if (resolved instanceof Response) return resolved;
       const query = c.req.query("q")?.trim().slice(0, 200) ?? "";
-      const catalog = createHelpCatalog([resolved.help], locale);
       const payload: HelpSearchPayload = {
-        locale: catalog[0]?.locale ?? resolved.help.baseLocale ?? "en",
-        ids: query ? searchHelpCatalog(catalog, { query, appId: resolved.app.id, limit: 25 }).map((document) => document.documentId) : [],
+        locale,
+        ids: (await reader(locale).search({ query, appId: c.req.param("appId"), limit: 25 })).map((document) => document.documentId),
       };
       return c.json(payload);
     })
     .get("/help/v1/:appId/documents/:documentId", async (c) => {
       const locale = getLocale(c);
       const { t } = helpApiMessages.resolve([locale]);
-      const resolved = await resolveHelp(c.req.param("appId"), dependencies, t);
-      if (resolved instanceof Response) return resolved;
-      const document = findHelpDocument(createHelpCatalog([resolved.help], locale), resolved.app.id, c.req.param("documentId"));
+      const document = await reader(locale).read({ appId: c.req.param("appId"), documentId: c.req.param("documentId") });
       if (!document) return c.json({ code: "HELP_NOT_FOUND", message: t.notFound }, 404);
       const payload: HelpDocumentPayload = {
         locale: document.locale,
         id: document.documentId,
         title: document.title,
         markdown: document.markdown,
-        html: renderDocument(resolved.help, document.locale, document.documentId, document.markdown),
+        html: (dependencies.renderMarkdown ?? renderHelpMarkdown)(document.markdown),
       };
       return c.json(payload);
     });
 };
-
 export type HelpApiType = ReturnType<typeof createHelpRoutes>;

package/src/api/index.ts

@@ -16,21 +16,24 @@
 import { Hono } from "hono";
 import { prettyJSON } from "hono/pretty-json";
 import { createAiApprovalPreferenceRoutes } from "../ai/approval-routes";
+import { createCodeCapabilityRoutes } from "../ai/code-capability-routes";
 import { aiProjectsRoutes } from "../ai/projects-routes";
 import { aiRoutes } from "../ai/routes";
 import { aiSkillsRoutes } from "../ai/skills-routes";
 import accountsEntitiesRoutes from "./accounts-entities";
-import adminAiUsageRoutes from "./admin-ai-usage";
 import adminAiProjectsRoutes from "./admin-ai-projects";
+import adminAiQuotaRoutes from "./admin-ai-quotas";
 import adminAiSkillsRoutes from "./admin-ai-skills";
+import adminAiUsageRoutes from "./admin-ai-usage";
 import adminCoreSettingsRoutes from "./admin-core-settings";
 import adminIdentityRoutes from "./admin-identity";
 import adminLifecycleRoutes from "./admin-lifecycle";
 import adminLinuxIdentityRoutes from "./admin-linux-identities";
+import adminRailRoutes from "./admin-rail";
 import { adminAnnouncementRoutes, announcementRoutes } from "./announcements";
+import { createAppApprovalRoutes } from "./app-approval";
 import { appDiscoveryRoutes } from "./apps";
 import { createAuthRoutes } from "./auth";
-import { createAppApprovalRoutes } from "./app-approval";
 import { createCapabilityRoutes } from "./capabilities";
 import { createHelpRoutes } from "./help";
 import { createMcpRoutes } from "./mcp";
@@ -66,10 +69,12 @@ const buildCoreApi = (options: CoreApiOptions) => {
     .route("/apps", appDiscoveryRoutes)
     .route("/announcements", announcementRoutes)
     .route("/admin/core/ai-usage", adminAiUsageRoutes)
+    .route("/admin/core/ai-quotas", adminAiQuotaRoutes)
     .route("/admin/core/ai-projects", adminAiProjectsRoutes)
     .route("/admin/core/ai-skills", adminAiSkillsRoutes)
     .route("/admin/core/announcements", adminAnnouncementRoutes)
     .route("/admin/core/settings", adminCoreSettingsRoutes)
+    .route("/admin/core/rail", adminRailRoutes)
     .route("/admin/core/linux-identities", adminLinuxIdentityRoutes)
     .route("/admin/identity", adminIdentityRoutes)
     .route("/admin/sync", createSyncOpsProxyRoutes())
@@ -77,6 +82,7 @@ const buildCoreApi = (options: CoreApiOptions) => {
     .route("/ai/approval-preferences", approvalPreferenceRoutes)
     .route("/ai/projects", aiProjectsRoutes)
     .route("/ai/skills", aiSkillsRoutes)
+    .route("/_internal/ai/code", createCodeCapabilityRoutes())
     .route("/ai", aiRoutes)
     .route("/", helpRoutes)
     .route("/", capabilityRoutes)

package/src/api/mcp.ts

@@ -15,17 +15,9 @@ import {
 import { Hono, type MiddlewareHandler } from "hono";
 import { z } from "zod";
 import { readBoundedJson } from "../_internal/bounded-json";
-import {
-  findHelpDocument,
-  HELP_SEARCH_MAX_LIMIT,
-  type HelpCatalogDocument,
-  helpResourceUri,
-  loadHelpCatalog,
-  parseHelpResourceUri,
-  readHelpCatalog,
-  searchHelpCatalog,
-} from "../_internal/help-catalog";
-import { getCapability, listApps, listHelp } from "../_internal/registry";
+import { HELP_SEARCH_MAX_LIMIT, helpResourceUri, parseHelpResourceUri, readHelpArticle } from "../_internal/help-catalog";
+import { getCapability, listApps } from "../_internal/registry";
+import { capabilityValueMeta, recordCapabilityExecution } from "../capabilities/executions";
 import {
   CAPABILITY_FRAMEWORK_ERROR_CODES,
   CAPABILITY_MAX_REQUEST_BYTES,
@@ -39,8 +31,10 @@ import {
   cloudResourceRefAppId,
   resolveCapabilityResourceReader,
 } from "../contracts/capabilities";
-import type { AppRegistryEntry, CapabilityRegistryEntry, HelpRegistryEntry } from "../contracts/registry";
+import type { AppRegistryEntry, CapabilityRegistryEntry } from "../contracts/registry";
 import { type AuthContext, auth, type RequestAuthority, rateLimit, rejectReservedWorkloadCredential, resolveLocale } from "../server";
+import { createHelpReader, type HelpArticle, type HelpMetadata, type HelpReader, type HelpReaderFactory } from "../services/help";
+import { normalizeInvocationRequestId } from "../services/identity/invocation-token";
 import { logger } from "../services/logging";
 import { get } from "../services/settings";
 import { cloudMcpResourceUri, publicCloudOrigin } from "../shared/app-url";
@@ -61,7 +55,7 @@ const log = logger("mcp");
 
 type McpRouteDependencies = CapabilityDispatchDependencies & {
   listApps?: () => Promise<AppRegistryEntry[]>;
-  listHelp?: () => Promise<HelpRegistryEntry[]>;
+  help?: HelpReaderFactory;
   getOperatorLocale?: () => Promise<string | undefined>;
   getAppUrl?: () => Promise<string>;
   authenticate?: MiddlewareHandler<AuthContext>;
@@ -375,13 +369,12 @@ const semanticResourceLinks = (body: Record<string, unknown>, origin: string): C
   }));
 };
 
-const helpResource = (document: HelpCatalogDocument): Resource => ({
+const helpResource = (document: HelpMetadata): Resource => ({
   uri: helpResourceUri(document.appId, document.documentId),
   name: `${document.appName}: ${document.title}`,
   title: document.title,
   description: document.description ?? `Product Help from ${document.appName}.`,
   mimeType: "text/markdown",
-  size: new TextEncoder().encode(document.markdown).byteLength,
   annotations: { audience: ["assistant"], priority: 0.8 },
   _meta: {
     "cloud/appId": document.appId,
@@ -391,10 +384,10 @@ const helpResource = (document: HelpCatalogDocument): Resource => ({
   },
 });
 
-const helpResourcePage = (catalog: readonly HelpCatalogDocument[], cursor?: string): { resources: Resource[]; nextCursor?: string } => {
+const helpResourcePage = (catalog: readonly HelpMetadata[], cursor?: string): { resources: Resource[]; nextCursor?: string } => {
   const resources = catalog
     .map(helpResource)
-    .sort((left, right) => left.uri.localeCompare(right.uri))
+    .sort((left, right) => (left.uri < right.uri ? -1 : left.uri > right.uri ? 1 : 0))
     .filter((resource) => !cursor || resource.uri > cursor)
     .slice(0, MCP_RESOURCE_PAGE_SIZE);
   const hasMore =
@@ -412,7 +405,7 @@ const hasOnlyKeys = (value: Record<string, unknown>, keys: readonly string[]): b
 const validationToolError = (message: string): CallToolResult =>
   boundedToolResult({ code: CAPABILITY_FRAMEWORK_ERROR_CODES.validationFailed, message }, true);
 
-const callHelpTool = async (name: string, argsValue: unknown, catalog: readonly HelpCatalogDocument[]): Promise<CallToolResult | null> => {
+const callHelpTool = async (name: string, argsValue: unknown, reader: HelpReader): Promise<CallToolResult | null> => {
   const args = helpArguments(argsValue);
   if (name === HELP_SEARCH_TOOL) {
     const query = typeof args.query === "string" ? args.query.trim() : "";
@@ -428,7 +421,7 @@ const callHelpTool = async (name: string, argsValue: unknown, catalog: readonly
     ) {
       return validationToolError("cloud__help__search requires query (1-200 characters) and an optional limit from 1 to 25");
     }
-    const documents = searchHelpCatalog(catalog, { query, appId, limit });
+    const documents = await reader.search({ query, appId, limit });
     const result = boundedToolResult({ documents }, false);
     result.content.push(
       ...documents.map((document) => ({
@@ -457,7 +450,8 @@ const callHelpTool = async (name: string, argsValue: unknown, catalog: readonly
         "cloud__help__read requires exact appId and documentId values and accepts an optional query up to 200 characters",
       );
     }
-    const document = readHelpCatalog(catalog, { appId, documentId, query });
+    const article = await reader.read({ appId, documentId });
+    const document = article ? readHelpArticle(article, query) : null;
     if (!document) return boundedToolResult({ code: "HELP_NOT_FOUND", message: "Help document is not in the current live catalog" }, true);
     const result = boundedToolResult({ document }, false);
     result.content.push({
@@ -486,8 +480,8 @@ const createMcpServer = (
     (helpLocale ??= (dependencies.getOperatorLocale ?? (() => get<string>("app.locale")))().then((operatorDefault) =>
       resolveLocale(request.headers, operatorDefault),
     ));
-  const helpCatalog = async () =>
-    loadHelpCatalog({ listApps: registry, listHelp: dependencies.listHelp ?? listHelp }, await resolveHelpLocale());
+  const helpReader = async () =>
+    (dependencies.help ?? ((locale) => createHelpReader(locale, { listApps: registry })))(await resolveHelpLocale());
   const hasScope = (scope: "read" | "write"): boolean =>
     oauthScopes === null || oauthScopes.includes(scope) || oauthScopes.includes("admin");
   const requireScope = (scope: "read" | "write"): void => {
@@ -507,10 +501,10 @@ const createMcpServer = (
       throw new McpError(ErrorCode.InvalidParams, "Invalid Cloud Help resource cursor");
     }
     try {
-      return helpResourcePage(await helpCatalog(), message.params?.cursor);
+      return helpResourcePage(await (await helpReader()).list(message.params?.cursor), message.params?.cursor);
     } catch (error) {
       log.error("Failed to list MCP Help resources", { error: error instanceof Error ? error.message : String(error) });
-      throw new McpError(ErrorCode.InternalError, "Help registry is currently unavailable", {
+      throw new McpError(ErrorCode.InternalError, "Help is currently unavailable", {
         code: CAPABILITY_FRAMEWORK_ERROR_CODES.appUnavailable,
       });
     }
@@ -520,16 +514,15 @@ const createMcpServer = (
     requireScope("read");
     const identity = parseHelpResourceUri(message.params.uri);
     if (!identity) throw new McpError(ErrorCode.InvalidParams, "Unknown Cloud Help resource URI");
-    let catalog: HelpCatalogDocument[];
+    let document: HelpArticle | null;
     try {
-      catalog = await helpCatalog();
+      document = await (await helpReader()).read(identity);
     } catch (error) {
-      log.error("Failed to read MCP Help catalog", { error: error instanceof Error ? error.message : String(error) });
-      throw new McpError(ErrorCode.InternalError, "Help registry is currently unavailable", {
+      log.error("Failed to read Help", { error: error instanceof Error ? error.message : String(error) });
+      throw new McpError(ErrorCode.InternalError, "Help is currently unavailable", {
         code: CAPABILITY_FRAMEWORK_ERROR_CODES.appUnavailable,
       });
     }
-    const document = findHelpDocument(catalog, identity.appId, identity.documentId);
     if (!document) throw new McpError(ErrorCode.InvalidParams, "Help resource is not in the current live catalog");
     return {
       contents: [
@@ -567,13 +560,10 @@ const createMcpServer = (
         return boundedToolResult({ code: "FORBIDDEN", message: "OAuth scope read is required" }, true);
       }
       try {
-        return (await callHelpTool(message.params.name, message.params.arguments, await helpCatalog()))!;
+        return (await callHelpTool(message.params.name, message.params.arguments, await helpReader()))!;
       } catch (error) {
         log.error("Failed to call MCP Help tool", { error: error instanceof Error ? error.message : String(error) });
-        return boundedToolResult(
-          { code: CAPABILITY_FRAMEWORK_ERROR_CODES.appUnavailable, message: "Help registry is currently unavailable" },
-          true,
-        );
+        return boundedToolResult({ code: CAPABILITY_FRAMEWORK_ERROR_CODES.appUnavailable, message: "Help is currently unavailable" }, true);
       }
     }
     let selected: CapabilityTool | null;
@@ -615,6 +605,26 @@ const createMcpServer = (
     }
     const requiredScope = selected.kind === "actions" ? "write" : "read";
     if (!hasScope(requiredScope)) {
+      // Denied before the dispatcher, so this surface records the same row the
+      // dispatcher would have written.
+      const at = new Date();
+      const actor = authority?.actor;
+      await recordCapabilityExecution({
+        requestId: normalizeInvocationRequestId(request.headers.get("x-request-id")) ?? crypto.randomUUID(),
+        origin: "mcp",
+        appId: selected.app.appId,
+        capability: `${selected.app.appId}.${selected.operation.localId}`,
+        kind: selected.kind === "actions" ? "action" : "query",
+        destructive: "destructive" in selected.operation ? selected.operation.destructive : false,
+        actorKind: actor?.kind ?? null,
+        actorId: actor?.kind === "user" ? actor.user.id : (actor?.serviceAccount.id ?? null),
+        userId: actor?.kind === "user" ? actor.user.id : (actor?.delegatedUser?.id ?? null),
+        status: "denied",
+        errorCode: "FORBIDDEN",
+        inputMeta: capabilityValueMeta(message.params.arguments ?? {}),
+        startedAt: at,
+        completedAt: at,
+      }).catch((error) => log.error("MCP denial could not be recorded", { error: error instanceof Error ? error.message : String(error) }));
       return boundedToolResult({ code: "FORBIDDEN", message: `OAuth scope ${requiredScope} is required` }, true);
     }
 
@@ -626,6 +636,7 @@ const createMcpServer = (
     const response = await dispatchCapability({
       request: new Request(request.url, { method: "POST", headers, signal: request.signal }),
       kind: selected.kind,
+      origin: "mcp",
       appId: selected.app.appId,
       capabilityId: selected.operation.localId,
       input: args,

package/src/api/me-web-vitals.ts

@@ -0,0 +1,35 @@
+import { Hono } from "hono";
+import { bodyLimit } from "hono/body-limit";
+import { describeRoute } from "hono-openapi";
+import { WEB_VITALS_MAX_BYTES, type WebVitalsReport, WebVitalsReportSchema } from "../contracts/web-vitals";
+import { type AuthContext, requiresAuth, v } from "../server";
+import { logger } from "../services/logging";
+import { get } from "../services/settings";
+
+const log = logger("web-vitals");
+
+/** Mounted below /me's authentication, user guard and rate limit. Client reports are diagnostics, not audit facts. */
+export const createMeWebVitalsRoutes = (
+  record: (report: WebVitalsReport) => void = (report) => log.info(report.name, report),
+  isEnabled: () => Promise<boolean> = async () => (await get("observability.web_vitals.enabled")) === true,
+) =>
+  new Hono<AuthContext>().post(
+    "/web-vitals",
+    describeRoute({
+      tags: ["Me"],
+      summary: "Report browser page performance",
+      ...requiresAuth,
+      responses: {
+        204: { description: "Report processed; discarded when collection is disabled" },
+        400: { description: "Invalid report" },
+        413: { description: "Report too large" },
+      },
+    }),
+    bodyLimit({ maxSize: WEB_VITALS_MAX_BYTES }),
+    v("json", WebVitalsReportSchema),
+    async (c) => {
+      if (!c.get("user")) return c.json({ message: "Authentication required" }, 401);
+      if (await isEnabled()) record(c.req.valid("json"));
+      return c.body(null, 204);
+    },
+  );

package/src/api/me.ts

@@ -50,6 +50,7 @@ import {
 import { MandatePolicyV1Schema } from "../services/mandates";
 
 import { createMeRailRoutes } from "./me-rail";
+import { createMeWebVitalsRoutes } from "./me-web-vitals";
 
 const toAccountsActor = (user: AuthContext["Variables"]["user"]) => ({
   userId: user.id,
@@ -187,6 +188,7 @@ const app = new Hono<AuthContext>()
   .use(auth.requireUser())
   .route("/", mandateRoutes)
   .route("/", createMeRailRoutes())
+  .route("/", createMeWebVitalsRoutes())
 
   .get(
     "/activity",