@k2b/cloud 0.42.0 → 0.44.0

package/src/capabilities/executions.ts

@@ -54,6 +54,9 @@ export const capabilityValueMeta = (value: unknown): CapabilityValueMeta => {
 export type CapabilityExecutionInput = {
   /** Correlation id shared with the invocation token, the app audit row, and request logs. */
   requestId: string;
+  invocationId?: string | null;
+  parentInvocationId?: string | null;
+  viaAppId?: string | null;
   origin: CapabilityOrigin;
   appId: string;
   /** Fully qualified capability name, such as `contacts.list`. */
@@ -79,6 +82,9 @@ export type CapabilityExecutionInput = {
 export type CapabilityExecution = {
   id: string;
   requestId: string;
+  invocationId?: string | null;
+  parentInvocationId?: string | null;
+  viaAppId?: string | null;
   origin: CapabilityOrigin;
   appId: string;
   capability: string;
@@ -115,12 +121,12 @@ export const recordCapabilityExecution = async (input: CapabilityExecutionInput)
         deadline.check();
         const [row] = await db<{ id: string }[]>`
     INSERT INTO capabilities.executions (
-      request_id, origin, app_id, capability, kind, destructive,
+      request_id, invocation_id, parent_invocation_id, via_app_id, origin, app_id, capability, kind, destructive,
       actor_kind, actor_id, user_id, access_subject_type, access_subject_id,
       status, error_code, input_meta, output_meta, idempotency_key, replayed,
       started_at, completed_at, duration_ms
     ) VALUES (
-      ${input.requestId}, ${input.origin}, ${input.appId}, ${input.capability}, ${input.kind}, ${input.destructive},
+      ${input.requestId}, ${input.invocationId ?? null}, ${input.parentInvocationId ?? null}, ${input.viaAppId ?? null}, ${input.origin}, ${input.appId}, ${input.capability}, ${input.kind}, ${input.destructive},
       ${input.actorKind ?? null}, ${input.actorId ?? null}, ${input.userId ?? null},
       ${input.accessSubject?.type ?? null}, ${input.accessSubject?.id ?? null},
       ${input.status}, ${input.errorCode ?? null},
@@ -168,7 +174,8 @@ const filterSql = (filter: CapabilityExecutionFilter) => sql`
 `;
 
 const columns = () => sql`
-  execution.id::text AS id, execution.request_id AS "requestId", execution.origin, execution.app_id AS "appId",
+  execution.id::text AS id, execution.request_id AS "requestId",
+  execution.invocation_id::text AS "invocationId", execution.parent_invocation_id::text AS "parentInvocationId", execution.via_app_id AS "viaAppId", execution.origin, execution.app_id AS "appId",
   execution.capability, execution.kind, execution.destructive,
   execution.actor_kind AS "actorKind", execution.actor_id::text AS "actorId", execution.user_id::text AS "userId",
   execution.access_subject_type AS "accessSubjectType", execution.access_subject_id::text AS "accessSubjectId",

package/src/capabilities/migrate.ts

@@ -55,6 +55,10 @@ export const migrateCloudCapabilities = async (): Promise<void> => {
 
   await sql`ALTER TABLE capabilities.executions ADD COLUMN IF NOT EXISTS replayed BOOLEAN NOT NULL DEFAULT false`.simple();
 
+  await sql`ALTER TABLE capabilities.executions ADD COLUMN IF NOT EXISTS invocation_id UUID`.simple();
+  await sql`ALTER TABLE capabilities.executions ADD COLUMN IF NOT EXISTS parent_invocation_id UUID`.simple();
+  await sql`ALTER TABLE capabilities.executions ADD COLUMN IF NOT EXISTS via_app_id TEXT`.simple();
+
   // Platform-owned idempotency claims. One row per
   // (app, capability, principal, key); the dispatcher claims before it
   // forwards and resolves the row once the outcome is known. Response bodies

package/src/capabilities/nested.ts

@@ -0,0 +1,43 @@
+import { env } from "../config/env";
+import type { CapabilityExecutionContext } from "../contracts/capabilities";
+import { capabilityMessages } from "../shared/capability-messages";
+import { invokeCapabilityWithDataSchema } from "./server";
+
+/** Framework-owned closure: the invocation credential never becomes handler data. */
+export const createNestedCapabilityQuery =
+  (source: Request): NonNullable<CapabilityExecutionContext["query"]> =>
+  async (invocation, schema) => {
+    if (!env.CLOUD_CORE_INTERNAL_ORIGIN)
+      return {
+        ok: false,
+        error: {
+          code: "APP_UNAVAILABLE",
+          message: capabilityMessages(source.headers.get("x-cloud-locale") ?? undefined).cloudUnavailable,
+          status: 503,
+        },
+      };
+    return invokeCapabilityWithDataSchema({ ...invocation, kind: "query" }, schema, {
+      signal: source.signal,
+      locale: source.headers.get("x-cloud-locale"),
+      transport: async (request) => {
+        const match = new URL(request.url).pathname.match(/^\/api\/capabilities\/v1\/queries\/([^/]+)\/([^/]+)$/);
+        if (!match) throw new Error("Only a nested Query is supported");
+        const { input } = await request.json();
+        const headers = new Headers({ "content-type": "application/json" });
+        const token = source.headers.get("authorization");
+        if (!token) throw new Error("A parent invocation is required");
+        headers.set("authorization", token);
+        for (const name of ["x-cloud-locale", "traceparent", "tracestate"]) {
+          const value = source.headers.get(name);
+          if (value) headers.set(name, value);
+        }
+        return fetch(new URL("/api/_internal/identity/v1/invoke-child", request.url), {
+          method: "POST",
+          headers,
+          signal: request.signal,
+          redirect: "error",
+          body: JSON.stringify({ targetApp: decodeURIComponent(match[1]!), capabilityId: decodeURIComponent(match[2]!), input }),
+        });
+      },
+    });
+  };

package/src/capabilities/server-invoke.ts

@@ -0,0 +1,202 @@
+import { z } from "zod";
+import { dispatchCapability, loadCapabilityCatalogPage } from "../api/capabilities";
+import {
+  CAPABILITY_FRAMEWORK_ERROR_CODES,
+  CAPABILITY_MAX_CATALOG_BYTES,
+  CapabilityCatalogSchema,
+  type CapabilityOrigin,
+  capabilityResultSchema,
+} from "../contracts/capabilities";
+import type { RequestAuthority } from "../server";
+import { coreOrigin } from "../services/identity/core-origin";
+import { capabilityMessages } from "../shared/capability-messages";
+import { LOCALE_HEADER } from "../shared/locale";
+import { readCapabilityResponse } from "./response";
+import { combineCapabilitySignals } from "./signals";
+import type { CapabilityCatalogClientResult, CapabilityClientError, CapabilityClientResult, CapabilityInvocation } from "./types";
+
+/**
+ * The server capability client: the caller's credentials, the request to Core, invocation, and the catalog. Its own
+ * module, so readers built on it, such as the calendar reader, and the public `capabilities/server` entry share it.
+ */
+
+export type CapabilityCaller = {
+  /** Core-only in-process authority; other applications must use a Core transport. */
+  authority?: RequestAuthority;
+  /** Trusted server transport to Core. Never supplied by a browser or sandbox. */
+  transport?: (request: Request) => Promise<Response>;
+  origin?: CapabilityOrigin;
+
+  authorization?: string | null;
+  cookie?: string | null;
+  requestId?: string | null;
+  traceparent?: string | null;
+  tracestate?: string | null;
+  /** BCP 47 locale of the originating request, forwarded as invocation metadata. */
+  locale?: string | null;
+  signal?: AbortSignal;
+  /** Durable background authority. `authorization` must be the owning app's workload credential. */
+  mandate?: { id: string; revision: number; callingAppId: string };
+};
+
+export { coreOrigin } from "../services/identity/core-origin";
+
+export const callerRequest = async (
+  caller: CapabilityCaller,
+  path: string,
+  idempotencyKey?: string,
+  invocationSignal?: AbortSignal,
+): Promise<Request> => {
+  const headers = new Headers();
+  if (caller.authorization) headers.set("authorization", caller.authorization);
+  if (!caller.mandate) {
+    if (caller.cookie) headers.set("cookie", caller.cookie);
+    if (caller.requestId) headers.set("x-request-id", caller.requestId);
+    if (caller.traceparent) headers.set("traceparent", caller.traceparent);
+    if (caller.tracestate) headers.set("tracestate", caller.tracestate);
+    if (caller.locale) headers.set(LOCALE_HEADER, caller.locale);
+    if (idempotencyKey) headers.set("idempotency-key", idempotencyKey);
+  } else {
+    headers.set("x-cloud-app-id", caller.mandate.callingAppId);
+  }
+  const signal = combineCapabilitySignals(caller.signal, invocationSignal);
+  return new Request(new URL(path, await coreOrigin(caller.mandate !== undefined)), { method: "POST", headers, signal });
+};
+
+export const unavailable = (
+  cause: unknown,
+  invocation?: Pick<CapabilityInvocation, "kind" | "idempotencyKey">,
+  locale?: string,
+): { ok: false; error: CapabilityClientError } => ({
+  ok: false,
+  error:
+    invocation?.kind === "action" && !invocation.idempotencyKey
+      ? {
+          code: CAPABILITY_FRAMEWORK_ERROR_CODES.actionOutcomeUnknown,
+          message: capabilityMessages(locale).actionOutcomeUnknown,
+          status: 502,
+          details: { retrySafe: false },
+        }
+      : cause instanceof Error && cause.name === "AbortError"
+        ? {
+            code: CAPABILITY_FRAMEWORK_ERROR_CODES.requestCancelled,
+            message: capabilityMessages(locale).requestCancelled,
+            status: 499,
+          }
+        : {
+            code: CAPABILITY_FRAMEWORK_ERROR_CODES.appUnavailable,
+            message: capabilityMessages(locale).cloudUnavailable,
+            status: 503,
+          },
+});
+
+const invokeCapabilityWithResultSchema = async <TDataSchema extends z.ZodType, TInput = unknown>(
+  invocation: CapabilityInvocation<TInput>,
+  dataSchema: TDataSchema,
+  caller: CapabilityCaller,
+): Promise<CapabilityClientResult<z.output<TDataSchema>>> => {
+  try {
+    const path = caller.mandate
+      ? "/api/_internal/identity/v1/invoke"
+      : `/api/capabilities/v1/${invocation.kind === "query" ? "queries" : "actions"}/${encodeURIComponent(invocation.appId)}/${encodeURIComponent(invocation.capabilityId)}`;
+    const request = await callerRequest(caller, path, invocation.idempotencyKey, invocation.signal);
+    if (caller.authority) {
+      if (caller.authorization || caller.cookie || caller.mandate || caller.transport)
+        throw new Error("Use exactly one capability authority source");
+      const outcome = await dispatchCapability({
+        request,
+        kind: invocation.kind === "query" ? "queries" : "actions",
+        appId: invocation.appId,
+        capabilityId: invocation.capabilityId,
+        input: invocation.input,
+        authority: caller.authority,
+        locale: caller.locale ?? undefined,
+        origin: caller.origin ?? "app",
+      });
+      return readCapabilityResponse(outcome, capabilityResultSchema(dataSchema, { consumer: true }));
+    }
+    const response = await (caller.transport ?? fetch)(
+      new Request(request, {
+        body: JSON.stringify(
+          caller.mandate
+            ? {
+                kind: invocation.kind,
+                targetApp: invocation.appId,
+                capabilityId: invocation.capabilityId,
+                input: invocation.input,
+                mandateId: caller.mandate.id,
+                mandateRevision: caller.mandate.revision,
+                ...(invocation.idempotencyKey ? { idempotencyKey: invocation.idempotencyKey } : {}),
+                ...(caller.requestId || caller.traceparent || caller.tracestate || caller.locale
+                  ? {
+                      metadata: {
+                        ...(caller.requestId ? { requestId: caller.requestId } : {}),
+                        ...(caller.traceparent ? { traceparent: caller.traceparent } : {}),
+                        ...(caller.tracestate ? { tracestate: caller.tracestate } : {}),
+                        ...(caller.locale ? { locale: caller.locale } : {}),
+                      },
+                    }
+                  : {}),
+              }
+            : { input: invocation.input },
+        ),
+      }),
+    );
+    return readCapabilityResponse(response, capabilityResultSchema(dataSchema, { consumer: true }));
+  } catch (cause) {
+    return unavailable(cause, invocation, caller.locale ?? undefined);
+  }
+};
+
+export const invokeCapability = <TInput = unknown>(
+  invocation: CapabilityInvocation<TInput>,
+  caller: CapabilityCaller,
+): Promise<CapabilityClientResult<unknown>> => invokeCapabilityWithResultSchema(invocation, z.unknown(), caller);
+
+export const invokeCapabilityWithDataSchema = <TDataSchema extends z.ZodType, TInput = unknown>(
+  invocation: CapabilityInvocation<TInput>,
+  dataSchema: TDataSchema,
+  caller: CapabilityCaller,
+): Promise<CapabilityClientResult<z.output<TDataSchema>>> => invokeCapabilityWithResultSchema(invocation, dataSchema, caller);
+
+export const listCapabilityCatalog = async (
+  options: { cursor?: string; limit?: number; locale?: string; authority?: RequestAuthority | null; caller?: CapabilityCaller } = {},
+): Promise<CapabilityCatalogClientResult> => {
+  const limit = options.limit ?? 25;
+  const messages = capabilityMessages(options.locale);
+  if (!Number.isInteger(limit) || limit < 1 || limit > 25) {
+    return {
+      ok: false,
+      error: { code: "VALIDATION_FAILED", message: messages.catalogLimit({ max: 25 }), status: 400 },
+    };
+  }
+  try {
+    if (options.caller) {
+      const caller = options.caller;
+      if (options.authority) throw new Error("Use one catalog authority source");
+      if (caller.authority && (caller.authorization || caller.cookie || caller.mandate || caller.transport))
+        throw new Error("Use exactly one capability authority source");
+      if (caller.authority)
+        return {
+          ok: true,
+          data: await loadCapabilityCatalogPage({ cursor: options.cursor, limit }, {}, caller.locale ?? options.locale, caller.authority),
+        };
+      if (caller.mandate) throw new Error("Calendar discovery requires request credentials");
+      const query = new URLSearchParams({ limit: String(limit) });
+      if (options.cursor) query.set("cursor", options.cursor);
+      const request = new Request(await callerRequest(caller, `/api/capabilities/v1/catalog?${query}`), { method: "GET" });
+      return await readCapabilityResponse(
+        await (caller.transport ?? fetch)(request),
+        CapabilityCatalogSchema,
+        CAPABILITY_MAX_CATALOG_BYTES,
+        caller.signal,
+      );
+    }
+    return {
+      ok: true,
+      data: await loadCapabilityCatalogPage({ cursor: options.cursor, limit }, {}, options.locale, options.authority ?? null),
+    };
+  } catch {
+    return { ok: false, error: { code: "APP_UNAVAILABLE", message: messages.cloudUnavailable, status: 503 } };
+  }
+};

package/src/capabilities/server.ts

@@ -1,35 +1,25 @@
-import { z } from "zod";
 import { resolveCapabilityActionWording, resolveCapabilityManifestPresentation } from "../_internal/capabilities";
 import type { CapabilityActionWording } from "../_internal/capability-sentences";
 import { getApp, getCapability } from "../_internal/registry";
-import { dispatchCapability, loadCapabilityCatalogPage } from "../api/capabilities";
-import { env } from "../config/env";
-import {
-  CAPABILITY_FRAMEWORK_ERROR_CODES,
-  CAPABILITY_MAX_REVIEW_RESPONSE_BYTES,
-  CapabilityActionReviewDataSchema,
-  type CapabilityOrigin,
-  capabilityResultSchema,
-} from "../contracts/capabilities";
+import { dispatchCapability } from "../api/capabilities";
+import { CAPABILITY_MAX_REVIEW_RESPONSE_BYTES, CapabilityActionReviewDataSchema } from "../contracts/capabilities";
 import type { RequestAuthority } from "../server";
 import { canUseApp } from "../services/app-access";
-import { get } from "../services/settings";
 import { resolveAppPresentation } from "../shared/app-presentation";
-import { publicCloudOrigin } from "../shared/app-url";
 import { capabilityMessages } from "../shared/capability-messages";
 import { DEFAULT_LOCALE, LOCALE_HEADER } from "../shared/locale";
 import { readCapabilityResponse } from "./response";
+import { type CapabilityCaller, callerRequest, coreOrigin, unavailable } from "./server-invoke";
 import { combineCapabilitySignals } from "./signals";
-import type {
-  CapabilityCatalogAppClientResult,
-  CapabilityCatalogClientResult,
-  CapabilityClientError,
-  CapabilityClientResult,
-  CapabilityInvocation,
-  CapabilityReviewClientResult,
-} from "./types";
+import type { CapabilityCatalogAppClientResult, CapabilityInvocation, CapabilityReviewClientResult } from "./types";
 
 export type { CapabilityActionWording } from "../_internal/capability-sentences";
+export {
+  type CapabilityCaller,
+  invokeCapability,
+  invokeCapabilityWithDataSchema,
+  listCapabilityCatalog,
+} from "./server-invoke";
 export type {
   CapabilityCatalogApp,
   CapabilityCatalogAppClientResult,
@@ -39,173 +29,6 @@ export type {
   CapabilityReviewClientResult,
 } from "./types";
 
-export type CapabilityCaller = {
-  /** Core-only in-process authority; other applications must use a Core transport. */
-  authority?: RequestAuthority;
-  /** Trusted server transport to Core. Never supplied by a browser or sandbox. */
-  transport?: (request: Request) => Promise<Response>;
-  origin?: CapabilityOrigin;
-
-  authorization?: string | null;
-  cookie?: string | null;
-  requestId?: string | null;
-  traceparent?: string | null;
-  tracestate?: string | null;
-  /** BCP 47 locale of the originating request, forwarded as invocation metadata. */
-  locale?: string | null;
-  signal?: AbortSignal;
-  /** Durable background authority. `authorization` must be the owning app's workload credential. */
-  mandate?: { id: string; revision: number; callingAppId: string };
-};
-
-const coreOrigin = async (internal = false): Promise<string> => {
-  const configured = env.CLOUD_CORE_INTERNAL_ORIGIN;
-  if (internal && !configured) throw new Error("CLOUD_CORE_INTERNAL_ORIGIN is required for mandate-backed invocation");
-  const origin = configured || publicCloudOrigin(await get<string>("app.url"));
-  const url = new URL(origin);
-  if (url.protocol !== "http:" && url.protocol !== "https:") throw new Error("CLOUD_CORE_INTERNAL_ORIGIN must use http or https");
-  return url.origin;
-};
-
-const callerRequest = async (
-  caller: CapabilityCaller,
-  path: string,
-  idempotencyKey?: string,
-  invocationSignal?: AbortSignal,
-): Promise<Request> => {
-  const headers = new Headers();
-  if (caller.authorization) headers.set("authorization", caller.authorization);
-  if (!caller.mandate) {
-    if (caller.cookie) headers.set("cookie", caller.cookie);
-    if (caller.requestId) headers.set("x-request-id", caller.requestId);
-    if (caller.traceparent) headers.set("traceparent", caller.traceparent);
-    if (caller.tracestate) headers.set("tracestate", caller.tracestate);
-    if (caller.locale) headers.set(LOCALE_HEADER, caller.locale);
-    if (idempotencyKey) headers.set("idempotency-key", idempotencyKey);
-  } else {
-    headers.set("x-cloud-app-id", caller.mandate.callingAppId);
-  }
-  const signal = combineCapabilitySignals(caller.signal, invocationSignal);
-  return new Request(new URL(path, await coreOrigin(caller.mandate !== undefined)), { method: "POST", headers, signal });
-};
-
-const unavailable = (
-  cause: unknown,
-  invocation?: Pick<CapabilityInvocation, "kind" | "idempotencyKey">,
-  locale?: string,
-): { ok: false; error: CapabilityClientError } => ({
-  ok: false,
-  error:
-    invocation?.kind === "action" && !invocation.idempotencyKey
-      ? {
-          code: CAPABILITY_FRAMEWORK_ERROR_CODES.actionOutcomeUnknown,
-          message: capabilityMessages(locale).actionOutcomeUnknown,
-          status: 502,
-          details: { retrySafe: false },
-        }
-      : cause instanceof Error && cause.name === "AbortError"
-        ? {
-            code: CAPABILITY_FRAMEWORK_ERROR_CODES.requestCancelled,
-            message: capabilityMessages(locale).requestCancelled,
-            status: 499,
-          }
-        : {
-            code: CAPABILITY_FRAMEWORK_ERROR_CODES.appUnavailable,
-            message: capabilityMessages(locale).cloudUnavailable,
-            status: 503,
-          },
-});
-
-const invokeCapabilityWithResultSchema = async <TDataSchema extends z.ZodType, TInput = unknown>(
-  invocation: CapabilityInvocation<TInput>,
-  dataSchema: TDataSchema,
-  caller: CapabilityCaller,
-): Promise<CapabilityClientResult<z.output<TDataSchema>>> => {
-  try {
-    const path = caller.mandate
-      ? "/api/_internal/identity/v1/invoke"
-      : `/api/capabilities/v1/${invocation.kind === "query" ? "queries" : "actions"}/${encodeURIComponent(invocation.appId)}/${encodeURIComponent(invocation.capabilityId)}`;
-    const request = await callerRequest(caller, path, invocation.idempotencyKey, invocation.signal);
-    if (caller.authority) {
-      if (caller.authorization || caller.cookie || caller.mandate || caller.transport)
-        throw new Error("Use exactly one capability authority source");
-      const outcome = await dispatchCapability({
-        request,
-        kind: invocation.kind === "query" ? "queries" : "actions",
-        appId: invocation.appId,
-        capabilityId: invocation.capabilityId,
-        input: invocation.input,
-        authority: caller.authority,
-        locale: caller.locale ?? undefined,
-        origin: caller.origin ?? "app",
-      });
-      return readCapabilityResponse(outcome, capabilityResultSchema(dataSchema, { consumer: true }));
-    }
-    const response = await (caller.transport ?? fetch)(
-      new Request(request, {
-        body: JSON.stringify(
-          caller.mandate
-            ? {
-                kind: invocation.kind,
-                targetApp: invocation.appId,
-                capabilityId: invocation.capabilityId,
-                input: invocation.input,
-                mandateId: caller.mandate.id,
-                mandateRevision: caller.mandate.revision,
-                ...(invocation.idempotencyKey ? { idempotencyKey: invocation.idempotencyKey } : {}),
-                ...(caller.requestId || caller.traceparent || caller.tracestate || caller.locale
-                  ? {
-                      metadata: {
-                        ...(caller.requestId ? { requestId: caller.requestId } : {}),
-                        ...(caller.traceparent ? { traceparent: caller.traceparent } : {}),
-                        ...(caller.tracestate ? { tracestate: caller.tracestate } : {}),
-                        ...(caller.locale ? { locale: caller.locale } : {}),
-                      },
-                    }
-                  : {}),
-              }
-            : { input: invocation.input },
-        ),
-      }),
-    );
-    return readCapabilityResponse(response, capabilityResultSchema(dataSchema, { consumer: true }));
-  } catch (cause) {
-    return unavailable(cause, invocation, caller.locale ?? undefined);
-  }
-};
-
-export const invokeCapability = <TInput = unknown>(
-  invocation: CapabilityInvocation<TInput>,
-  caller: CapabilityCaller,
-): Promise<CapabilityClientResult<unknown>> => invokeCapabilityWithResultSchema(invocation, z.unknown(), caller);
-
-export const invokeCapabilityWithDataSchema = <TDataSchema extends z.ZodType, TInput = unknown>(
-  invocation: CapabilityInvocation<TInput>,
-  dataSchema: TDataSchema,
-  caller: CapabilityCaller,
-): Promise<CapabilityClientResult<z.output<TDataSchema>>> => invokeCapabilityWithResultSchema(invocation, dataSchema, caller);
-
-export const listCapabilityCatalog = async (
-  options: { cursor?: string; limit?: number; locale?: string; authority?: RequestAuthority | null } = {},
-): Promise<CapabilityCatalogClientResult> => {
-  const limit = options.limit ?? 25;
-  const messages = capabilityMessages(options.locale);
-  if (!Number.isInteger(limit) || limit < 1 || limit > 25) {
-    return {
-      ok: false,
-      error: { code: "VALIDATION_FAILED", message: messages.catalogLimit({ max: 25 }), status: 400 },
-    };
-  }
-  try {
-    return {
-      ok: true,
-      data: await loadCapabilityCatalogPage({ cursor: options.cursor, limit }, {}, options.locale, options.authority ?? null),
-    };
-  } catch {
-    return { ok: false, error: { code: "APP_UNAVAILABLE", message: messages.cloudUnavailable, status: 503 } };
-  }
-};
-
 export const getCapabilityCatalogApp = async (
   appId: string,
   locale?: string,
@@ -333,6 +156,22 @@ export async function transferCapabilityStream(
   return caller.transport ? caller.transport(request) : fetch(request, { redirect: "error" });
 }
 
+export {
+  CALENDAR_VIEW_MAX_RANGE_MS,
+  type CalendarReadResult,
+  CalendarReadResultSchema,
+  type CalendarSelection,
+  CalendarSourceErrorSchema,
+  type CalendarSourceListEntry,
+  CalendarSourceListEntrySchema,
+  type CalendarSourceState,
+  CalendarSourceStateSchema,
+  type CalendarSourceSummary,
+  CalendarSourceSummarySchema,
+  CalendarViewRangeSchema,
+  listCalendarSources,
+  readCalendarEvents,
+} from "./calendar-sources";
 export {
   actionReview,
   type CapabilityReviewForms,

package/src/capabilities/testing.ts

@@ -17,8 +17,11 @@ import {
 } from "../contracts/capabilities";
 
 /** Compile and validate the public manifest an app would register at startup. */
-export const compileCapabilityManifest = (appId: string, definitions: CapabilityDefinitions): CapabilityManifest =>
-  compileCapabilities(appId, definitions).manifest;
+export const compileCapabilityManifest = (
+  appId: string,
+  definitions: CapabilityDefinitions,
+  routes?: readonly string[],
+): CapabilityManifest => compileCapabilities(appId, definitions, routes).manifest;
 
 /** Fail a provider compatibility test when a published local id changed incompatibly. */
 export const assertCapabilityManifestEvolution = (previous: CapabilityManifest, next: CapabilityManifest): void => {

package/src/cli/access.ts

@@ -49,6 +49,7 @@ export type AccessCommandAdapter<TResource extends AccessResource> = {
   scopes?: readonly [string, ...string[]];
   allowPublic?: boolean;
   allowAuthenticated?: boolean;
+  /** Defaults to true; false preserves an explicitly restricted resource contract. */
   allowServiceAccounts?: boolean;
   examples?: {
     list?: readonly string[];
@@ -217,7 +218,7 @@ export const resolveAccessPrincipal = async (
       "--group",
       ...(options.allowAuthenticated === false ? [] : ["--authenticated"]),
       ...(options.allowPublic === true ? ["--public"] : []),
-      ...(options.allowServiceAccounts === true ? ["--service-account"] : []),
+      ...(options.allowServiceAccounts !== false ? ["--service-account"] : []),
     ];
     throw new Error(`Pass exactly one principal flag: ${allowedFlags.join(", ")}.`);
   }
@@ -225,8 +226,8 @@ export const resolveAccessPrincipal = async (
   if (flags.authenticated && options.allowAuthenticated === false) {
     throw new Error("This resource does not allow authenticated-audience grants.");
   }
-  if (flags.serviceAccount && options.allowServiceAccounts !== true) {
-    throw new Error("Service-account grants are hidden by default. Enable allowServiceAccounts for this access command.");
+  if (flags.serviceAccount && options.allowServiceAccounts === false) {
+    throw new Error("This resource does not allow service-account access grants.");
   }
   if (flags.authenticated) return { type: "authenticated" };
   if (flags.public) return { type: "public" };
@@ -348,11 +349,11 @@ const accessIdFlag = {
 
 export const createAccessCommands = <TResource extends AccessResource>(adapter: AccessCommandAdapter<TResource>) => {
   const allowed = normalizeAllowedPermissions(adapter.allowedPermissions);
-  const searchableKinds = adapter.allowServiceAccounts ? PRINCIPAL_KINDS : (["user", "group"] as const);
+  const searchableKinds = adapter.allowServiceAccounts !== false ? PRINCIPAL_KINDS : (["user", "group"] as const);
   const principalFlagOptions = {
     includePublicFlag: adapter.allowPublic === true,
     includeAuthenticatedFlag: adapter.allowAuthenticated !== false,
-    includeServiceAccountFlag: adapter.allowServiceAccounts === true,
+    includeServiceAccountFlag: adapter.allowServiceAccounts !== false,
   };
   const resolve = (ctx: CloudCliContext, args: string[]) => adapter.resolveResource(ctx, args);
   const scopeFlag: { scope?: ReturnType<typeof flag.string> } = adapter.scopes