@k2b/cloud 0.29.0 → 0.30.0

package/src/cli/access.ts

@@ -28,10 +28,24 @@ export type AccessCommandAdapter<TResource extends AccessResource> = {
   resourceArgDescription?: string;
   resolveResource: AccessCommandResourceResolver<TResource>;
   list: (ctx: CloudCliContext, resource: TResource) => Promise<AccessEntry[]>;
-  grant: (ctx: CloudCliContext, resource: TResource, principal: Principal, permission: AccessPermission) => Promise<AccessEntry>;
-  update: (ctx: CloudCliContext, resource: TResource, accessId: string, permission: AccessPermission) => Promise<void>;
+  /** `scope` is one of `scopes`, or undefined when the command line names none. */
+  grant: (
+    ctx: CloudCliContext,
+    resource: TResource,
+    principal: Principal,
+    permission: AccessPermission,
+    scope?: string,
+  ) => Promise<AccessEntry>;
+  /** `scope` is one of `scopes`, or undefined to keep the grant's scope. */
+  update: (ctx: CloudCliContext, resource: TResource, accessId: string, permission: AccessPermission, scope?: string) => Promise<void>;
   revoke: (ctx: CloudCliContext, resource: TResource, accessId: string) => Promise<void>;
   allowedPermissions?: readonly AccessPermission[];
+  /**
+   * Parts of the resource a grant can cover, as the resource's access API names them in `scope`:
+   * the whole resource first (shown for entries without a scope), then narrower parts. Adds
+   * `--scope` to `grant` and `set` and a SCOPE column to `list`.
+   */
+  scopes?: readonly [string, ...string[]];
   allowPublic?: boolean;
   allowAuthenticated?: boolean;
   allowServiceAccounts?: boolean;
@@ -243,7 +257,7 @@ const entryTypeLabel = (entry: AccessEntry): string => {
 };
 
 // Resource-bound service accounts back resource API keys, which are managed with those keys.
-const accessRows = (entries: AccessEntry[], options: { includeServiceAccounts?: boolean } = {}) =>
+const accessRows = (entries: AccessEntry[], options: { includeServiceAccounts?: boolean; scopes?: readonly string[] } = {}) =>
   entries
     .filter((entry) => options.includeServiceAccounts || entry.serviceAccountKind !== "resource_bound")
     .sort((a, b) => {
@@ -256,6 +270,7 @@ const accessRows = (entries: AccessEntry[], options: { includeServiceAccounts?:
       principal: entryDisplayName(entry),
       type: entryTypeLabel(entry),
       permission: entry.permission,
+      ...(options.scopes ? { scope: entry.scope ?? options.scopes[0] } : {}),
       createdAt: entry.createdAt,
     }));
 
@@ -269,7 +284,7 @@ const printStructured = (ctx: CloudCliContext, value: unknown): boolean => {
 export const printAccessEntries = (
   ctx: CloudCliContext,
   entries: AccessEntry[],
-  options: { includeServiceAccounts?: boolean; jsonValue?: unknown } = {},
+  options: { includeServiceAccounts?: boolean; jsonValue?: unknown; scopes?: readonly string[] } = {},
 ) => {
   if (printStructured(ctx, options.jsonValue ?? entries)) return;
   const rows = accessRows(entries, options);
@@ -281,6 +296,7 @@ export const printAccessEntries = (
     { key: "principal", label: "PRINCIPAL" },
     { key: "type", label: "TYPE" },
     { key: "permission", label: "PERMISSION" },
+    ...(options.scopes ? [{ key: "scope" as const, label: "SCOPE" }] : []),
     { key: "accessId", label: "ACCESS ID" },
   ]);
 };
@@ -349,6 +365,19 @@ export const createAccessCommands = <TResource extends AccessResource>(adapter:
     includeServiceAccountFlag: adapter.allowServiceAccounts === true,
   };
   const resolve = (ctx: CloudCliContext, args: string[]) => adapter.resolveResource(ctx, args);
+  const scopeFlag: { scope?: ReturnType<typeof flag.string> } = adapter.scopes
+    ? {
+        scope: flag.string({
+          description: `Part of the ${adapter.resourceLabel} the grant covers. Allowed: ${adapter.scopes.join(", ")}`,
+        }),
+      }
+    : {};
+  const scopeSuffix = (scope: string | undefined): string => (scope && scope !== adapter.scopes?.[0] ? ` (${scope})` : "");
+  const scopeOf = (flags: { scope?: string }): string | undefined => {
+    if (flags.scope === undefined) return undefined;
+    if (!adapter.scopes?.includes(flags.scope)) throw new Error(`Scope must be one of: ${adapter.scopes?.join(", ") ?? "none"}.`);
+    return flags.scope;
+  };
   const resourceArgs = {
     args: arg.rest({
       valueLabel: adapter.resourceArgLabel ?? adapter.resourceLabel,
@@ -374,6 +403,7 @@ export const createAccessCommands = <TResource extends AccessResource>(adapter:
       printAccessEntries(ctx, entries, {
         includeServiceAccounts: flags.includeServiceAccounts,
         jsonValue: { resource, entries },
+        scopes: adapter.scopes,
       });
     },
   });
@@ -385,16 +415,18 @@ export const createAccessCommands = <TResource extends AccessResource>(adapter:
     flags: {
       ...principalFlags(principalFlagOptions),
       permission: flag.enum(allowed, { required: true, description: `Permission to grant. Allowed: ${allowed.join(", ")}` }),
+      ...scopeFlag,
     },
     examples: adapter.examples?.grant,
     async run({ ctx, args, flags }) {
       const resource = await resolve(ctx, args.args);
       const permission = flags.permission as AccessPermission;
       assertAllowedPermission(permission, allowed);
+      const scope = scopeOf(flags);
       const principal = await resolveAccessPrincipal(ctx, flags as PrincipalFlags, adapter);
-      const entry = await adapter.grant(ctx, resource, principal, permission);
+      const entry = await adapter.grant(ctx, resource, principal, permission, scope);
       if (!printStructured(ctx, { resource, entry }))
-        ctx.print(`Granted ${permission} on ${resource.label} to ${entryDisplayName(entry)}.`);
+        ctx.print(`Granted ${permission}${scopeSuffix(scope)} on ${resource.label} to ${entryDisplayName(entry)}.`);
     },
   });
 
@@ -407,17 +439,19 @@ export const createAccessCommands = <TResource extends AccessResource>(adapter:
       ...principalFlags(principalFlagOptions),
       ...accessIdFlag,
       permission: flag.enum(allowed, { required: true, description: `Permission to set. Allowed: ${allowed.join(", ")}` }),
+      ...scopeFlag,
     },
     examples: adapter.examples?.set,
     async run({ ctx, args, flags }) {
       const resource = await resolve(ctx, args.args);
       const permission = flags.permission as AccessPermission;
       assertAllowedPermission(permission, allowed);
+      const scope = scopeOf(flags);
 
       if (flags.accessId) {
-        await adapter.update(ctx, resource, flags.accessId, permission);
-        if (!printStructured(ctx, { resource, accessId: flags.accessId, permission, action: "updated" })) {
-          ctx.print(`Updated ${flags.accessId} to ${permission} on ${resource.label}.`);
+        await adapter.update(ctx, resource, flags.accessId, permission, scope);
+        if (!printStructured(ctx, { resource, accessId: flags.accessId, permission, scope, action: "updated" })) {
+          ctx.print(`Updated ${flags.accessId} to ${permission}${scopeSuffix(scope)} on ${resource.label}.`);
         }
         return;
       }
@@ -426,15 +460,15 @@ export const createAccessCommands = <TResource extends AccessResource>(adapter:
       const entries = await adapter.list(ctx, resource);
       const existing = entries.find((entry) => principalKey(entry.principal) === principalKey(principal));
       if (existing) {
-        await adapter.update(ctx, resource, existing.id, permission);
-        if (!printStructured(ctx, { resource, accessId: existing.id, permission, action: "updated" })) {
-          ctx.print(`Updated ${entryDisplayName(existing)} to ${permission} on ${resource.label}.`);
+        await adapter.update(ctx, resource, existing.id, permission, scope);
+        if (!printStructured(ctx, { resource, accessId: existing.id, permission, scope, action: "updated" })) {
+          ctx.print(`Updated ${entryDisplayName(existing)} to ${permission}${scopeSuffix(scope)} on ${resource.label}.`);
         }
         return;
       }
-      const entry = await adapter.grant(ctx, resource, principal, permission);
+      const entry = await adapter.grant(ctx, resource, principal, permission, scope);
       if (!printStructured(ctx, { resource, entry, action: "created" })) {
-        ctx.print(`Granted ${permission} on ${resource.label} to ${entryDisplayName(entry)}.`);
+        ctx.print(`Granted ${permission}${scopeSuffix(scope)} on ${resource.label} to ${entryDisplayName(entry)}.`);
       }
     },
   });

package/src/cli/admin/ai-skills.ts

@@ -4,7 +4,7 @@ import { apiGet, apiJson, queryString } from "./shared";
 
 export const aiSkillCommands = [
   command("ai skills list", {
-    summary: "List all Skills with template origin, version, status, and revision (platform admin)",
+    summary: "List all Skills with source app, availability, status, and revision (platform admin)",
     flags: {
       search: flag.string(),
       page: flag.int({ min: 1, default: 1 }),
@@ -15,49 +15,69 @@ export const aiSkillCommands = [
         ctx,
         `/api/admin/core/ai-skills${queryString(flags)}`,
       );
-      printRows(ctx, result, result.items, [
-        { key: "shortId" },
-        { key: "name" },
-        { key: "revision" },
-        { key: "templateId" },
-        { key: "templateVersion" },
-        { key: "currentTemplateVersion" },
-        { key: "templateStatus" },
-      ]);
-    },
-  }),
-  command("ai skills templates", {
-    summary: "List current trusted Skill template IDs and versions",
-    run: async ({ ctx }) => {
-      const result = await apiGet<{ templates: { templateId: string; name: string; version: number }[] }>(
+      printRows(
         ctx,
-        "/api/admin/core/ai-skills/templates",
+        result,
+        result.items.map((skill) => ({
+          ...skill,
+          app: skill.source?.appName ?? "",
+          status: skill.source?.status ?? "",
+          available: skill.source?.available ?? "",
+          appVersion: skill.source?.appVersion ?? "",
+        })),
+        [
+          { key: "shortId" },
+          { key: "name" },
+          { key: "revision" },
+          { key: "app" },
+          { key: "status" },
+          { key: "available" },
+          { key: "appVersion" },
+        ],
       );
-      printRows(ctx, result, result.templates, [{ key: "templateId" }, { key: "name" }, { key: "version" }]);
     },
   }),
-  ...(["associate", "reset"] as const).map((mode) =>
-    command(`ai skills ${mode}`, {
-      summary:
-        mode === "associate"
-          ? "Associate an existing Skill with a template, preserving all content"
-          : "Replace all linked Skill content and references with the current template",
-      args: { skillId: arg.required() },
-      flags: {
-        templateId: flag.string({ name: "template", required: true }),
-        templateVersion: flag.int({ name: "template-version", required: true, min: 1 }),
-        expectedRevision: flag.int({ name: "revision", required: true, min: 1 }),
-        yes: confirmFlag("Confirm the exact Skill and template; export customized content before resetting"),
-      },
+  command("ai skills reset", {
+    summary: "Replace Skill content and references with the owning app's current version",
+    args: { skillId: arg.required() },
+    flags: {
+      expectedRevision: flag.int({ name: "revision", required: true, min: 1 }),
+      expectedAppVersion: flag.string({ name: "app-version", required: true }),
+      yes: confirmFlag("Confirm resetting this Skill; export customized content first"),
+    },
+    run: async ({ ctx, args, flags }) => {
+      if (!flags.yes) throw new Error("Review the Skill first, then confirm with --yes.");
+      const result = await apiJson(ctx, "POST", `/api/admin/core/ai-skills/${encodeURIComponent(args.skillId)}/reset`, {
+        expectedRevision: flags.expectedRevision,
+        expectedAppVersion: flags.expectedAppVersion,
+        confirmed: true,
+      });
+      if (!printStructured(ctx, result)) ctx.print("Skill reset to the app version.");
+    },
+  }),
+  ...(
+    [
+      ["restore", "Install a deleted app Skill again from the app's version, when its name is free", "App Skill installed."],
+      [
+        "adopt",
+        "Link the existing Skill that holds an app Skill's name to that app, keeping its content",
+        "Existing Skill linked to the app.",
+      ],
+    ] as const
+  ).map(([action, summary, done]) =>
+    command(`ai skills ${action}`, {
+      summary,
+      args: { appId: arg.required(), name: arg.required() },
+      flags: { yes: confirmFlag(`Confirm the app and Skill name to ${action}`) },
       run: async ({ ctx, args, flags }) => {
-        if (!flags.yes) throw new Error("Review the Skill and template first, then confirm with --yes.");
-        const { yes: _yes, ...input } = flags;
-        const result = await apiJson(ctx, "POST", `/api/admin/core/ai-skills/${encodeURIComponent(args.skillId)}/template`, {
-          ...input,
-          mode,
-          confirmed: true,
-        });
-        if (!printStructured(ctx, result)) ctx.print("Skill template updated.");
+        if (!flags.yes) throw new Error("Review the app Skill first, then confirm with --yes.");
+        const result = await apiJson(
+          ctx,
+          "POST",
+          `/api/admin/core/ai-skills/apps/${encodeURIComponent(args.appId)}/skills/${encodeURIComponent(args.name)}/${action}`,
+          { confirmed: true },
+        );
+        if (!printStructured(ctx, result)) ctx.print(done);
       },
     }),
   ),

package/src/cli/admin/outgoing-mail.ts

@@ -2,6 +2,8 @@ import {
   type AdminMailApp,
   type AdminMailProfile,
   type AdminMailRecord,
+  MailLogAccessSchema,
+  MailLogAppIdSchema,
   type MailPage,
   MailProfileInputSchema,
   type MailRetention,
@@ -181,8 +183,16 @@ export const outgoingMailCommands = [
       printJsonOrTable(
         ctx,
         result,
-        result.items.map((app) => ({ ...app, profiles: app.profiles.join(",") })),
-        [{ key: "appId" }, { key: "name" }, { key: "declared" }, { key: "mode" }, { key: "profiles" }],
+        result.items.map((app) => ({ ...app, reads: app.readDeclared, profiles: app.profiles.join(","), logApps: app.logApps.join(",") })),
+        [
+          { key: "appId" },
+          { key: "name" },
+          { key: "declared" },
+          { key: "reads" },
+          { key: "mode" },
+          { key: "profiles" },
+          { key: "logApps" },
+        ],
       );
     },
   }),
@@ -212,4 +222,22 @@ export const outgoingMailCommands = [
       );
     },
   }),
+  command("outgoing-mail apps set-log-access", {
+    summary: "Choose which other applications' mail logs an app may read",
+    args: { app: arg.required({ valueLabel: "app" }) },
+    flags: {
+      apps: flag.string({ description: "Comma-separated source application IDs" }),
+      ownOnly: flag.boolean({ description: "Remove all other application log grants" }),
+      yes: confirmFlag("Confirm application mail log access change"),
+    },
+    async run({ ctx, args, flags }) {
+      confirmed(flags.yes);
+      if ((flags.apps !== undefined) === !!flags.ownOnly) throw new Error("Choose exactly one of --apps or --own-only.");
+      const reader = MailLogAppIdSchema.safeParse(args.app);
+      const value = MailLogAccessSchema.safeParse({ apps: flags.apps?.split(",").map((app) => app.trim()) ?? [] });
+      if (!reader.success || args.app === "core" || !value.success || value.data.apps.includes(args.app))
+        throw new Error("Choose a valid reader and distinct source apps other than Core or the reader itself.");
+      print(ctx, await apiJson(ctx, "PUT", `${root}/apps/${encodeURIComponent(args.app)}/log-access`, value.data));
+    },
+  }),
 ];

package/src/contracts/announcement-cookie.ts

@@ -0,0 +1,62 @@
+/**
+ * The announcements cookie, without schemas: the shell reads and writes it on every page and must not load the
+ * announcement validators for that. `AnnouncementCookieStateSchema` in `./announcements` describes the same shape.
+ */
+export const ANNOUNCEMENTS_COOKIE = "cloud_announcements";
+export const ANNOUNCEMENTS_COOKIE_MAX_AGE_SECONDS = 60 * 60 * 24 * 365;
+export const MAX_DISMISSED_BANNER_VERSIONS = 50;
+
+export type AnnouncementCookieState = {
+  seenAnnouncementVersion: number;
+  dismissedBannerVersions: number[];
+};
+
+export const DEFAULT_ANNOUNCEMENT_COOKIE_STATE: AnnouncementCookieState = {
+  seenAnnouncementVersion: 0,
+  dismissedBannerVersions: [],
+};
+
+const isVersion = (value: unknown, minimum: number): value is number =>
+  typeof value === "number" && Number.isSafeInteger(value) && value >= minimum;
+
+/** Any invalid field resets the whole state, as a failed schema parse did. */
+const normalizeCookieState = (value: unknown): AnnouncementCookieState => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return DEFAULT_ANNOUNCEMENT_COOKIE_STATE;
+  const { seenAnnouncementVersion = 0, dismissedBannerVersions = [] } = value as Partial<Record<keyof AnnouncementCookieState, unknown>>;
+  if (!isVersion(seenAnnouncementVersion, 0)) return DEFAULT_ANNOUNCEMENT_COOKIE_STATE;
+  if (!Array.isArray(dismissedBannerVersions) || !dismissedBannerVersions.every((version) => isVersion(version, 1)))
+    return DEFAULT_ANNOUNCEMENT_COOKIE_STATE;
+  const dismissed = [...new Set(dismissedBannerVersions)].sort((a, b) => b - a).slice(0, MAX_DISMISSED_BANNER_VERSIONS);
+
+  return {
+    seenAnnouncementVersion: Math.max(0, seenAnnouncementVersion),
+    dismissedBannerVersions: dismissed,
+  };
+};
+
+export const parseAnnouncementCookieValue = (value: string | null | undefined): AnnouncementCookieState => {
+  if (!value) return DEFAULT_ANNOUNCEMENT_COOKIE_STATE;
+  try {
+    return normalizeCookieState(JSON.parse(decodeURIComponent(value)));
+  } catch {
+    return DEFAULT_ANNOUNCEMENT_COOKIE_STATE;
+  }
+};
+
+export const parseAnnouncementCookieHeader = (cookieHeader: string | null | undefined): AnnouncementCookieState => {
+  if (!cookieHeader) return DEFAULT_ANNOUNCEMENT_COOKIE_STATE;
+  const match = cookieHeader.match(new RegExp(`(?:^|;\\s*)${ANNOUNCEMENTS_COOKIE}=([^;]+)`));
+  return parseAnnouncementCookieValue(match?.[1]);
+};
+
+export const serializeAnnouncementCookieState = (state: AnnouncementCookieState): string =>
+  encodeURIComponent(JSON.stringify(normalizeCookieState(state)));
+
+export const mergeAnnouncementCookieState = (
+  current: AnnouncementCookieState,
+  patch: Partial<AnnouncementCookieState>,
+): AnnouncementCookieState =>
+  normalizeCookieState({
+    seenAnnouncementVersion: Math.max(current.seenAnnouncementVersion, patch.seenAnnouncementVersion ?? 0),
+    dismissedBannerVersions: [...current.dismissedBannerVersions, ...(patch.dismissedBannerVersions ?? [])],
+  });

package/src/contracts/announcements.ts

@@ -1,8 +1,17 @@
 import { z } from "zod";
-
-export const ANNOUNCEMENTS_COOKIE = "cloud_announcements";
-export const ANNOUNCEMENTS_COOKIE_MAX_AGE_SECONDS = 60 * 60 * 24 * 365;
-export const MAX_DISMISSED_BANNER_VERSIONS = 50;
+import type { AnnouncementCookieState } from "./announcement-cookie";
+
+export {
+  ANNOUNCEMENTS_COOKIE,
+  ANNOUNCEMENTS_COOKIE_MAX_AGE_SECONDS,
+  type AnnouncementCookieState,
+  DEFAULT_ANNOUNCEMENT_COOKIE_STATE,
+  MAX_DISMISSED_BANNER_VERSIONS,
+  mergeAnnouncementCookieState,
+  parseAnnouncementCookieHeader,
+  parseAnnouncementCookieValue,
+  serializeAnnouncementCookieState,
+} from "./announcement-cookie";
 
 export const AnnouncementKindSchema = z.enum(["announcement", "banner"]);
 export type AnnouncementKind = z.infer<typeof AnnouncementKindSchema>;
@@ -13,13 +22,7 @@ export type AnnouncementTone = z.infer<typeof AnnouncementToneSchema>;
 export const AnnouncementCookieStateSchema = z.object({
   seenAnnouncementVersion: z.number().int().nonnegative().default(0),
   dismissedBannerVersions: z.array(z.number().int().positive()).default([]),
-});
-export type AnnouncementCookieState = z.infer<typeof AnnouncementCookieStateSchema>;
-
-export const DEFAULT_ANNOUNCEMENT_COOKIE_STATE: AnnouncementCookieState = {
-  seenAnnouncementVersion: 0,
-  dismissedBannerVersions: [],
-};
+}) satisfies z.ZodType<AnnouncementCookieState>;
 
 export const AnnouncementEntrySchema = z.object({
   id: z.uuid(),
@@ -78,44 +81,3 @@ export const ActiveAnnouncementsResponseSchema = z.object({
   latestAnnouncementVersion: z.number().int().nonnegative(),
 });
 export type ActiveAnnouncementsResponse = z.infer<typeof ActiveAnnouncementsResponseSchema>;
-
-const normalizeCookieState = (value: unknown): AnnouncementCookieState => {
-  const parsed = AnnouncementCookieStateSchema.safeParse(value);
-  if (!parsed.success) return DEFAULT_ANNOUNCEMENT_COOKIE_STATE;
-  const dismissed = [...new Set(parsed.data.dismissedBannerVersions)]
-    .filter((version) => Number.isInteger(version) && version > 0)
-    .sort((a, b) => b - a)
-    .slice(0, MAX_DISMISSED_BANNER_VERSIONS);
-
-  return {
-    seenAnnouncementVersion: Math.max(0, parsed.data.seenAnnouncementVersion),
-    dismissedBannerVersions: dismissed,
-  };
-};
-
-export const parseAnnouncementCookieValue = (value: string | null | undefined): AnnouncementCookieState => {
-  if (!value) return DEFAULT_ANNOUNCEMENT_COOKIE_STATE;
-  try {
-    return normalizeCookieState(JSON.parse(decodeURIComponent(value)));
-  } catch {
-    return DEFAULT_ANNOUNCEMENT_COOKIE_STATE;
-  }
-};
-
-export const parseAnnouncementCookieHeader = (cookieHeader: string | null | undefined): AnnouncementCookieState => {
-  if (!cookieHeader) return DEFAULT_ANNOUNCEMENT_COOKIE_STATE;
-  const match = cookieHeader.match(new RegExp(`(?:^|;\\s*)${ANNOUNCEMENTS_COOKIE}=([^;]+)`));
-  return parseAnnouncementCookieValue(match?.[1]);
-};
-
-export const serializeAnnouncementCookieState = (state: AnnouncementCookieState): string =>
-  encodeURIComponent(JSON.stringify(normalizeCookieState(state)));
-
-export const mergeAnnouncementCookieState = (
-  current: AnnouncementCookieState,
-  patch: Partial<AnnouncementCookieState>,
-): AnnouncementCookieState =>
-  normalizeCookieState({
-    seenAnnouncementVersion: Math.max(current.seenAnnouncementVersion, patch.seenAnnouncementVersion ?? 0),
-    dismissedBannerVersions: [...current.dismissedBannerVersions, ...(patch.dismissedBannerVersions ?? [])],
-  });

package/src/contracts/capabilities.ts

@@ -349,6 +349,26 @@ export type CapabilityUniversalSearchDefinition = {
 
 export type CapabilitySchemaPresentation = Readonly<Record<string, string>>;
 
+/**
+ * What one Action does, in words people read in approvals, receipts, and step rows. Each sentence is a
+ * template: `{input.to}` inserts a field of the validated call input by its dotted schema path, and
+ * `done` may also read the Action's result data with `{data.id}`. Cloud inserts values as escaped,
+ * bounded plain text, formats fields with a `date` or `date-time` schema format for the reader, and
+ * names an object by its email, address, or path before its display name. A sentence whose value is
+ * missing falls back to the generic wording, so every sentence stays optional. A `done` sentence
+ * replaces the result's runtime summary in the receipt.
+ */
+export type CapabilityActionSentences = {
+  /** What will happen, as a short instruction: "Send email to {input.to}". */
+  approval?: string;
+  /** What happened after the Action ran: "Sent email to {input.to}". */
+  done?: string;
+  /** What did not happen because the person rejected it: "Did not send email to {input.to}". */
+  rejected?: string;
+  /** What did not happen because the turn ended first: "Email to {input.to} not sent". */
+  notRun?: string;
+};
+
 export type CapabilityOperationPresentationTranslation = {
   title?: string;
   description?: string;
@@ -358,6 +378,8 @@ export type CapabilityOperationPresentationTranslation = {
   data?: CapabilitySchemaPresentation;
   /** Search-tag presentation keyed by the stable tag token. */
   searchTags?: Readonly<Record<string, { title?: string; description?: string }>>;
+  /** Actions only: the complete set of sentences in this locale. */
+  sentences?: CapabilityActionSentences;
 };
 
 export type CapabilityPresentationTranslation = {
@@ -370,6 +392,8 @@ export type CapabilityPresentationTranslation = {
 export type CapabilityPresentationCatalog = {
   /** Locale of the complete Type, Query, Action, search-tag, and schema presentation. */
   baseLocale: string;
+  /** Optional Action sentences in the base locale, keyed by Action local ID. */
+  sentences?: Readonly<Record<string, CapabilityActionSentences>>;
   /** Partial presentation overlays with exact -> ancestor -> base fallback. */
   translations: Readonly<Record<string, CapabilityPresentationTranslation>>;
 };

package/src/contracts/outgoing-mail.ts

@@ -2,7 +2,7 @@ import type { PageParams, Paginated, ServiceError } from "@k2b/stdlib";
 import { z } from "zod";
 import { type RequestActor, ServiceAccountSchema, UserSchema } from "./shared";
 
-export const PlatformPermissionSchema = z.enum(["mail:send"]);
+export const PlatformPermissionSchema = z.enum(["mail:send", "mail:read"]);
 export type PlatformPermission = z.infer<typeof PlatformPermissionSchema>;
 export const MailRetentionSchema = z.object({ contentDays: z.int().min(1).max(36500), recordDays: z.int().min(1).max(36500) }).strict();
 export type MailRetention = z.infer<typeof MailRetentionSchema>;
@@ -74,6 +74,7 @@ export type MailProfile = z.infer<typeof MailProfileSchema>;
 export const MailErrorCodeSchema = z.enum([
   "bad_input",
   "profile_not_allowed",
+  "app_not_allowed",
   "profile_required",
   "quota_exceeded",
   "backlog_full",
@@ -110,14 +111,31 @@ export const AdminMailProfileSchema = MailProfileInputSchema.omit({ smtpPassword
   appCount: z.int(),
 });
 export type AdminMailProfile = z.infer<typeof AdminMailProfileSchema>;
-export type AdminMailApp = {
-  appId: string;
-  name: string;
-  registered: boolean;
-  declared: boolean;
-  mode: "default" | "selected";
-  profiles: string[];
-};
+export const AdminMailAppSchema = z.object({
+  appId: z.string(),
+  name: z.string(),
+  registered: z.boolean(),
+  declared: z.boolean(),
+  mode: z.enum(["default", "selected"]),
+  profiles: z.array(z.string()),
+  /** Whether the registered app declares `mail:read`; grants in `logApps` only apply with it. */
+  readDeclared: z.boolean(),
+  /** Other apps whose send log this app may read, besides its own. */
+  logApps: z.array(z.string()),
+});
+export type AdminMailApp = z.infer<typeof AdminMailAppSchema>;
+/** Application IDs as registered, like sender access; Core's own mail is never readable by apps. */
+export const MailLogAppIdSchema = z.string().min(1);
+/** How many other apps' send logs an administrator can let one app read. */
+const MAIL_LOG_GRANT_LIMIT = 100;
+export const MailLogAccessSchema = z
+  .object({ apps: z.array(MailLogAppIdSchema).max(MAIL_LOG_GRANT_LIMIT) })
+  .strict()
+  .refine(
+    (value) => new Set(value.apps).size === value.apps.length && !value.apps.includes("core"),
+    "Choose distinct apps other than core",
+  );
+export type MailLogAccess = z.infer<typeof MailLogAccessSchema>;
 
 export const MailStatusSchema = z.enum(["queued", "sending", "sent", "failed", "bounced", "cancelled"]);
 export type MailStatus = z.infer<typeof MailStatusSchema>;
@@ -218,11 +236,38 @@ export const MailFilterSchema = z
     batchId: z.uuid().optional(),
     status: z.array(MailStatusSchema).max(6).optional(),
     since: z.iso.datetime({ offset: true }).optional(),
+    /** Exclusive upper bound on `createdAt`. */
+    until: z.iso.datetime({ offset: true }).optional(),
+    /**
+     * Apps whose records to read; omitted means only the calling app. Others need `mail:read` and an
+     * administrator grant. Holds everything `mail.readableApps()` returns: the caller and every grant.
+     */
+    apps: z
+      .array(MailLogAppIdSchema)
+      .min(1)
+      .max(MAIL_LOG_GRANT_LIMIT + 1)
+      .refine((apps) => new Set(apps).size === apps.length, "Choose distinct apps")
+      .optional(),
+    /**
+     * Case-insensitive substring of a recipient address or the subject. Three letters or digits in a row
+     * give the trigram index something to look up; without them every record would be a candidate.
+     */
+    q: z
+      .string()
+      .refine((value) => !/[\x00-\x1f\x7f]/.test(value), "Search must not contain control characters")
+      .trim()
+      .max(200)
+      .regex(/[\p{L}\p{N}]{3}/u, "Search needs three letters or digits in a row")
+      .optional(),
+    /** One recipient address, matched exactly but case-insensitively. */
+    recipient: z.string().trim().pipe(mailAddress).optional(),
   })
   .strict();
 export type MailFilter = z.infer<typeof MailFilterSchema>;
 export const MailRecordSchema = z.object({
   id: z.uuid(),
+  /** The app that sent the record. */
+  appId: z.string(),
   batchId: z.uuid().optional(),
   profile: z.string(),
   ref: ref.optional(),
@@ -241,7 +286,6 @@ export const MailRecordSchema = z.object({
 });
 export type MailRecord = z.infer<typeof MailRecordSchema>;
 export const AdminMailRecordSchema = MailRecordSchema.omit({ text: true }).extend({
-  appId: z.string(),
   errorCode: z.string().optional(),
   response: z.string().optional(),
 });
@@ -252,9 +296,10 @@ export type MailPage<T = MailRecord> = Paginated<T> & { nextCursor?: string };
 export const MailPageParamsSchema = z
   .object({ page: z.int().min(1).optional(), perPage: z.int().min(1).max(100).optional(), cursor: z.string().max(1024).optional() })
   .strict();
-export const AdminMailFilterSchema = MailFilterSchema.extend({
+export const AdminMailFilterSchema = MailFilterSchema.omit({ apps: true }).extend({
   app: z.string().min(1).optional(),
   profile: MailProfileKeySchema.optional(),
+  /** Administrators search a recipient substring. */
   recipient: z.string().max(320).optional(),
 });
 export type AdminMailFilter = z.infer<typeof AdminMailFilterSchema>;

package/src/contracts/pwa-paths.ts

@@ -1,6 +1,11 @@
 /**
- * Paths of the installable mobile app, without schemas, so browser code that runs on every page can test for an
- * app page without loading the contract's validators.
+ * Paths and ids of the installable mobile app, without schemas, so browser code that runs on every page can test for
+ * an app page without loading the contract's validators.
  */
 export const PWA_SCOPE = "/pwa/";
 export const PWA_AUTH_PATH = "/pwa/_auth";
+export const PWA_SERVICE_WORKER_PATH = "/pwa/sw.js";
+/** Ids that can never own a part: the shell itself and its own pages `/pwa/settings` and `/pwa/offline`. */
+export const PWA_RESERVED_IDS = ["pwa", "settings", "offline"] as const;
+/** Whether the app with this id may have a part at `/pwa/<id>`: a plain app id that the shell does not reserve. */
+export const isPwaPartId = (id: string): boolean => /^[a-z][a-z0-9-]*$/.test(id) && !PWA_RESERVED_IDS.some((reserved) => reserved === id);

package/src/contracts/pwa.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
-import { PWA_AUTH_PATH, PWA_SCOPE } from "./pwa-paths";
+import { isPwaPartId, PWA_AUTH_PATH, PWA_RESERVED_IDS, PWA_SCOPE, PWA_SERVICE_WORKER_PATH } from "./pwa-paths";
 
-export { PWA_AUTH_PATH, PWA_SCOPE };
+export { isPwaPartId, PWA_AUTH_PATH, PWA_RESERVED_IDS, PWA_SCOPE, PWA_SERVICE_WORKER_PATH };
 
 /**
  * The installable mobile app (preview). One shell application `pwa` owns the
@@ -11,11 +11,6 @@ export { PWA_AUTH_PATH, PWA_SCOPE };
 export const PWA_SHELL_APP_ID = "pwa";
 export const PWA_API_PATH = "/api/auth/pwa/v1";
 export const PWA_MANIFEST_PATH = "/pwa/manifest.webmanifest";
-export const PWA_SERVICE_WORKER_PATH = "/pwa/sw.js";
-/** Ids that can never own a part: the shell itself and its own pages `/pwa/settings` and `/pwa/offline`. */
-export const PWA_RESERVED_IDS = ["pwa", "settings", "offline"] as const;
-/** Whether the app with this id may have a part at `/pwa/<id>`: a plain app id that the shell does not reserve. */
-export const isPwaPartId = (id: string): boolean => /^[a-z][a-z0-9-]*$/.test(id) && !PWA_RESERVED_IDS.some((reserved) => reserved === id);
 /**
  * The page canvas of the app (`--k2b-surface-canvas` of `@k2b/ui`) in light and dark. App documents paint it
  * before any stylesheet loads and give it to the status bar.