@cosmicdrift/kumiko-samples 0.401.0 → 0.402.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.401.0",
+  "version": "0.402.0",
   "description": "Source trees of the Kumiko sample recipes, sample apps and bundled features in repo layout, for tooling such as few-shot corpus builds.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.401.0",
+  "version": "0.402.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/src/agent-tools/agent-manifest.ts

@@ -21,6 +21,7 @@ import { translationValueOtherText } from "@cosmicdrift/kumiko-framework/ui-type
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import * as z from "zod";
 import { recordManifestDenyQns } from "./manifest-deny-qns.ts";
+import { isExplicitlyAgentHidden } from "./tool-catalog.ts";
 import type {
   AgentManifest,
   AgentManifestEntity,
@@ -34,6 +35,31 @@ import type {
   RegistryManifestView,
 } from "./types.ts";
 
+const FALLBACK_LOCALE = "en";
+
+/** Requested locale, then English, then the first remaining locale in code-point
+ *  order; `undefined` when the entry has no text at all (the key is then omitted). */
+function pickLabel(labels: Readonly<Record<string, string>>, locale: string): string | undefined {
+  const nonEmpty = (value: string | undefined): string | undefined =>
+    value !== undefined && value !== "" ? value : undefined;
+  const firstLocale = Object.keys(labels)
+    .sort(compareIds)
+    .find((key) => nonEmpty(labels[key]));
+  return (
+    nonEmpty(labels[locale]) ??
+    nonEmpty(labels[FALLBACK_LOCALE]) ??
+    (firstLocale !== undefined ? labels[firstLocale] : undefined)
+  );
+}
+
+function labelProp(
+  labels: Readonly<Record<string, string>>,
+  locale: string,
+): { readonly label?: string } {
+  const label = pickLabel(labels, locale);
+  return label === undefined ? {} : { label };
+}
+
 /** The manifest surfaces one string per locale — a plural entry reads as its
  *  CLDR `other` form since the manifest has no `count` to select a category. */
 function entryAsLabels(entry: TranslationEntry): Readonly<Record<string, string>> {
@@ -135,6 +161,7 @@ function buildField(
   field: FieldDefinition,
   translations: TranslationKeys,
   searchableFields: ReadonlySet<string>,
+  locale: string,
 ): AgentManifestField {
   const options =
     field.type === "select" || field.type === "multiSelect" ? field.options : undefined;
@@ -143,7 +170,7 @@ function buildField(
   return {
     name: fieldName,
     type: field.type,
-    labels: labelsForSuffix(translations, `:entity:${entityName}:field:${fieldName}`),
+    ...labelProp(labelsForSuffix(translations, `:entity:${entityName}:field:${fieldName}`), locale),
     ...(field.description !== undefined && { description: field.description }),
     ...(options !== undefined && { options }),
     ...(references !== undefined && { references }),
@@ -153,23 +180,25 @@ function buildField(
   };
 }
 
-/** Entity schemas are emitted unfiltered by design: roles gate handlers, screens,
- *  navs and workspaces, while the handler pipeline gates the values themselves.
- *  The manifest describes shape, never data. */
+/** Shape, never data. Only entities the role reaches are emitted: the manifest is
+ *  prompt payload, so every extra schema costs tokens on each turn. */
 function buildEntities(
   entities: ReadonlyMap<string, EntityDefinition>,
   translations: TranslationKeys,
   getSearchableFields: (entityName: string) => readonly string[],
+  visibleEntityNames: ReadonlySet<string>,
+  locale: string,
 ): readonly AgentManifestEntity[] {
   const result: AgentManifestEntity[] = [];
   for (const [entityName, entity] of entities) {
+    if (!visibleEntityNames.has(entityName)) continue;
     const searchableFields = new Set(getSearchableFields(entityName));
     const fields = Object.entries(entity.fields).map(([fieldName, field]) =>
-      buildField(entityName, fieldName, field, translations, searchableFields),
+      buildField(entityName, fieldName, field, translations, searchableFields, locale),
     );
     result.push({
       name: entityName,
-      labels: labelsForSuffix(translations, `:entity:${entityName}`),
+      ...labelProp(labelsForSuffix(translations, `:entity:${entityName}`), locale),
       ...(entity.description !== undefined && { description: entity.description }),
       fields,
     });
@@ -177,14 +206,32 @@ function buildEntities(
   return result;
 }
 
+const FEATURE_DESCRIPTION_MAX_CHARS = 300;
+
+// Only ". " before a capital ends the sentence, so "e.g. the" and "Art. 15" stay whole.
+const SENTENCE_END = /\.\s+(?=\p{Lu})/u;
+
+/** The manifest is prompt payload; the full text stays in `FeatureDefinition.description`
+ *  for the docs generators. */
+function leadSentence(description: string): string {
+  const text = description.replace(/\s+/g, " ").trim();
+  const end = SENTENCE_END.exec(text);
+  const sentence = end === null ? text : text.slice(0, end.index + 1);
+  return sentence.slice(0, FEATURE_DESCRIPTION_MAX_CHARS);
+}
+
 function buildFeatures(
   features: ReadonlyMap<string, FeatureDefinition>,
+  visibleFeatureNames: ReadonlySet<string>,
 ): readonly AgentManifestFeature[] {
   const result: AgentManifestFeature[] = [];
   for (const [, feature] of features) {
+    if (!visibleFeatureNames.has(feature.name)) continue;
     result.push({
       name: feature.name,
-      ...(feature.description !== undefined && { description: feature.description }),
+      ...(feature.description !== undefined && {
+        description: leadSentence(feature.description),
+      }),
       ...(feature.uiHints?.displayLabel !== undefined && {
         displayLabel: feature.uiHints.displayLabel,
       }),
@@ -237,7 +284,8 @@ function buildHandlerEntry(
 
   // `agent.expose: true` without a `description` still opts in — the author
   // asked for exposure explicitly, there's just nothing to show as prose.
-  const description = def.description ?? "";
+  const description =
+    def.description !== undefined && def.description !== "" ? def.description : undefined;
 
   let inputSchema: Readonly<Record<string, unknown>>;
   try {
@@ -254,7 +302,7 @@ function buildHandlerEntry(
   return {
     qn,
     kind,
-    description,
+    ...(description !== undefined && { description }),
     risk: exposure.risk,
     inputSchema,
     ...(entity !== undefined && { entity }),
@@ -298,6 +346,7 @@ function buildNavs(
   translations: TranslationKeys,
   roles: readonly string[],
   screens: ReadonlyMap<string, ScreenDefinition>,
+  locale: string,
 ): readonly AgentManifestNav[] {
   const result: AgentManifestNav[] = [];
   for (const [, nav] of navs) {
@@ -312,10 +361,10 @@ function buildNavs(
 
     result.push({
       id: nav.id,
-      labels: entryAsLabels(translations[nav.label] ?? {}),
+      ...labelProp(entryAsLabels(translations[nav.label] ?? {}), locale),
       ...(nav.screen !== undefined && { screen: nav.screen }),
       ...(nav.parent !== undefined && { parent: nav.parent }),
-      workspaces: visibleWorkspaces,
+      ...(visibleWorkspaces.length > 0 && { workspaces: visibleWorkspaces }),
     });
   }
   return withoutOrphanedNavs(result);
@@ -333,6 +382,70 @@ function withoutOrphanedNavs(navs: readonly AgentManifestNav[]): readonly AgentM
   }
 }
 
+// Qualified handler, screen and nav ids all start with the owning feature name.
+function featureNameOf(qualifiedId: string): string {
+  const idx = qualifiedId.indexOf(":");
+  return idx === -1 ? qualifiedId : qualifiedId.slice(0, idx);
+}
+
+function visibleFeatureNamesOf(
+  handlers: readonly AgentManifestHandler[],
+  screens: readonly AgentManifestScreen[],
+  navs: readonly AgentManifestNav[],
+): ReadonlySet<string> {
+  return new Set(
+    [...handlers.map((h) => h.qn), ...screens.map((s) => s.id), ...navs.map((n) => n.id)].map(
+      featureNameOf,
+    ),
+  );
+}
+
+function entitiesOfQueryToolsFor(
+  registry: RegistryManifestView,
+  roles: readonly string[],
+  denyQns: ReadonlySet<string>,
+): readonly string[] {
+  const names: string[] = [];
+  for (const [qn, def] of registry.getAllQueryHandlers()) {
+    const entityName = registry.getHandlerEntity(qn);
+    if (entityName === undefined || denyQns.has(qn) || isExplicitlyAgentHidden(def)) continue;
+    if (hasAccess({ roles }, def.access)) names.push(entityName);
+  }
+  return names;
+}
+
+// A reference target is "entity" or "<feature>:entity"; registry entity keys are the bare name.
+function entityNameOfReference(target: string): string {
+  return target.slice(target.lastIndexOf(":") + 1);
+}
+
+function referenceTargetsOf(entity: EntityDefinition | undefined): readonly string[] {
+  return Object.values(entity?.fields ?? {}).flatMap((field) =>
+    field.type === "reference" ? [entityNameOfReference(field.entity)] : [],
+  );
+}
+
+/** Reachable = tagged on a manifest handler, shown by a manifest screen, or read by a
+ *  registry-derived `get_`/`list_` tool (which takes labels from the manifest entity). */
+function visibleEntityNamesOf(
+  registry: RegistryManifestView,
+  roles: readonly string[],
+  denyQns: ReadonlySet<string>,
+  handlers: readonly AgentManifestHandler[],
+  screens: readonly AgentManifestScreen[],
+): ReadonlySet<string> {
+  const reachable = new Set<string>([
+    ...handlers.flatMap((handler) => (handler.entity !== undefined ? [handler.entity] : [])),
+    ...screens.flatMap((screen) => [screen.entity ?? [], screen.detailFor ?? []].flat()),
+    ...entitiesOfQueryToolsFor(registry, roles, denyQns),
+  ]);
+  const entities = registry.getAllEntities();
+  return new Set([
+    ...reachable,
+    ...[...reachable].flatMap((n) => referenceTargetsOf(entities.get(n))),
+  ]);
+}
+
 function lastSegment(qualifiedId: string): string {
   const idx = qualifiedId.lastIndexOf(":");
   return idx === -1 ? qualifiedId : qualifiedId.slice(idx + 1);
@@ -346,10 +459,42 @@ function screenTitles(
   translations: TranslationKeys,
   screenId: string,
   shortId: string,
-): AgentManifestScreen["titles"] {
-  return entryAsLabels(
-    translations[`${screenId}.title`] ?? translations[`screen:${shortId}.title`] ?? {},
+  locale: string,
+): { readonly title?: string } {
+  const title = pickLabel(
+    entryAsLabels(
+      translations[`${screenId}.title`] ?? translations[`screen:${shortId}.title`] ?? {},
+    ),
+    locale,
   );
+  return title === undefined ? {} : { title };
+}
+
+function buildScreenEntry(
+  screen: ScreenDefinition,
+  screenWorkspaces: readonly string[],
+  translations: TranslationKeys,
+  locale: string,
+): AgentManifestScreen {
+  return {
+    id: screen.id,
+    type: screen.type,
+    ...screenTitles(translations, screen.id, lastSegment(screen.id), locale),
+    // `screen.description` may be a raw i18n key (`registry.getAllTranslations()`
+    // double-prefixes it, see build-app-schema.ts:77-81) — match on suffix like
+    // `labelsForSuffix` does for entity/field labels, else fall back to the
+    // literal string as authored.
+    ...(screen.description !== undefined && {
+      description:
+        pickLabel(labelsForSuffix(translations, screen.description), locale) ?? screen.description,
+    }),
+    ...("entity" in screen && screen.entity !== undefined && { entity: screen.entity }),
+    // A detail screen takes the row id under its idParam; everything else is parameterless.
+    ...(screen.detailFor !== undefined && { params: [detailIdParam(screen)] }),
+    ...(screenWorkspaces.length > 0 && { workspaces: screenWorkspaces }),
+    ...(screen.detailFor !== undefined && { detailFor: screen.detailFor }),
+    ...("handler" in screen && typeof screen.handler === "string" && { handler: screen.handler }),
+  };
 }
 
 function buildScreens(
@@ -359,6 +504,7 @@ function buildScreens(
   translations: TranslationKeys,
   roles: readonly string[],
   visibleNavIds: ReadonlySet<string>,
+  locale: string,
 ): readonly AgentManifestScreen[] {
   const allNavs = [...navs.values()];
   const result: AgentManifestScreen[] = [];
@@ -382,29 +528,11 @@ function buildScreens(
       });
     if (!uiVisible(screen.access, roles) || !reachable) continue;
 
-    const shortId = lastSegment(screen.id);
     const screenWorkspaces = dedupeSorted(
       accessibleNavs.flatMap((nav) => visibleWorkspaceIds(nav.workspaces, workspaces, roles)),
     );
 
-    result.push({
-      id: screen.id,
-      type: screen.type,
-      titles: screenTitles(translations, screen.id, shortId),
-      // `screen.description` may be a raw i18n key (`registry.getAllTranslations()`
-      // double-prefixes it, see build-app-schema.ts:77-81) — match on suffix like
-      // `labelsForSuffix` does for entity/field labels, else fall back to the
-      // literal string as authored.
-      ...(screen.description !== undefined && {
-        description: labelsForSuffix(translations, screen.description)["en"] ?? screen.description,
-      }),
-      ...("entity" in screen && screen.entity !== undefined && { entity: screen.entity }),
-      // A detail screen takes the row id under its idParam; everything else is parameterless.
-      params: screen.detailFor !== undefined ? [detailIdParam(screen)] : [],
-      workspaces: screenWorkspaces,
-      ...(screen.detailFor !== undefined && { detailFor: screen.detailFor }),
-      ...("handler" in screen && typeof screen.handler === "string" && { handler: screen.handler }),
-    });
+    result.push(buildScreenEntry(screen, screenWorkspaces, translations, locale));
   }
   return result;
 }
@@ -413,13 +541,14 @@ function buildWorkspaces(
   workspaces: ReadonlyMap<string, WorkspaceDefinition>,
   translations: TranslationKeys,
   roles: readonly string[],
+  locale: string,
 ): readonly AgentManifestWorkspace[] {
   const result: AgentManifestWorkspace[] = [];
   for (const [, workspace] of workspaces) {
     if (!uiVisible(workspace.access, roles)) continue;
     result.push({
       id: workspace.id,
-      labels: entryAsLabels(translations[workspace.label] ?? {}),
+      ...labelProp(entryAsLabels(translations[workspace.label] ?? {}), locale),
       ...(workspace.default === true && { default: true as const }),
     });
   }
@@ -439,19 +568,16 @@ export function buildAgentManifest(
   const { roles } = options;
   assertDenyQnsExist(options.denyQns ?? [], registry);
 
-  const features = buildFeatures(registry.features);
-  const entities = buildEntities(registry.getAllEntities(), translations, (name) =>
-    registry.getSearchableFields(name),
-  );
+  const denyQns = new Set(options.denyQns ?? []);
   const handlers = buildHandlers(
     registry.getAllQueryHandlers(),
     registry.getAllWriteHandlers(),
     roles,
     (qn) => registry.getHandlerEntity(qn),
-    new Set(options.denyQns ?? []),
+    denyQns,
   );
   const screenMap = registry.getAllScreens();
-  const navs = buildNavs(navMap, workspaceMap, translations, roles, screenMap);
+  const navs = buildNavs(navMap, workspaceMap, translations, roles, screenMap, options.locale);
   const screens = buildScreens(
     screenMap,
     navMap,
@@ -459,8 +585,17 @@ export function buildAgentManifest(
     translations,
     roles,
     new Set(navs.map((nav) => nav.id)),
+    options.locale,
+  );
+  const workspaces = buildWorkspaces(workspaceMap, translations, roles, options.locale);
+  const features = buildFeatures(registry.features, visibleFeatureNamesOf(handlers, screens, navs));
+  const entities = buildEntities(
+    registry.getAllEntities(),
+    translations,
+    (name) => registry.getSearchableFields(name),
+    visibleEntityNamesOf(registry, roles, denyQns, handlers, screens),
+    options.locale,
   );
-  const workspaces = buildWorkspaces(workspaceMap, translations, roles);
 
   const manifest: AgentManifest = {
     builtForRoles: [...roles],
@@ -475,6 +610,6 @@ export function buildAgentManifest(
       ...(options.currency && { currency: options.currency }),
     },
   };
-  recordManifestDenyQns(manifest, new Set(options.denyQns ?? []));
+  recordManifestDenyQns(manifest, denyQns);
   return manifest;
 }

package/packages/bundled-features/src/agent-tools/changes.json

@@ -1,4 +1,23 @@
 [
+  {
+    "version": "0.402.0",
+    "type": "breaking",
+    "title": "Agent manifest labels are one string in the requested locale",
+    "detail": "`buildAgentManifest` used to emit every label in every locale (`labels: { de, en, es }`, often `{}`), although the caller names one `locale`. Entities, fields, navs and workspaces now carry `label?: string`, screens `title?: string`, picked in the requested locale, then English, then the first other locale, and left out when untranslated. Empty `params` and `workspaces` on screens, empty `workspaces` on navs and an empty handler `description` are left out as well (`description`, `params` and `workspaces` are optional in the types). `buildToolCatalog` reads the new fields.",
+    "migration": "Read `entity.label`, `field.label`, `nav.label`, `workspace.label` and `screen.title` instead of the `labels`/`titles` maps. Code that only passes the manifest to `buildToolCatalog` or serialises it needs no change."
+  },
+  {
+    "version": "0.402.0",
+    "type": "improvement",
+    "title": "Agent manifest shows only the first sentence of a feature description",
+    "detail": "`buildAgentManifest` emits the first sentence of `FeatureDefinition.description` (a `. ` before a capital letter ends it, so \"e.g.\" and \"Art. 15\" stay whole), at most 300 characters. The full text stays on the definition for the docs generators. In an app with 77 features the descriptions drop from about 46.6k to 12.2k characters."
+  },
+  {
+    "version": "0.402.0",
+    "type": "improvement",
+    "title": "Agent manifest features and entities follow the role",
+    "detail": "`buildAgentManifest` now leaves out a feature when none of its handlers, screens or navs remain in the manifest for the role, and an entity when no remaining handler or screen refers to it, no `get_`/`list_` tool of the role reads it and no reachable entity points at it through a reference field (one hop). Before, `features` and `entities` were identical for every role, so a restricted role paid for schemas it could not use in every system prompt. A translation-only feature such as `locale-de` no longer appears in `features`."
+  },
   {
     "version": "0.389.0",
     "type": "improvement",

package/packages/bundled-features/src/agent-tools/tool-catalog.ts

@@ -104,7 +104,7 @@ function isDetailHandlerQn(qn: string, entityName: string): boolean {
  *  `resolveAgentExposure` never runs for them. Only an EXPLICIT opt-out may hide one here —
  *  the resolver's own default is fail-closed on a missing `description`, and CRUD-generated
  *  handlers never carry one, so reusing it would delete every entity tool in every app. */
-function isExplicitlyAgentHidden(def: QueryHandlerDef): boolean {
+export function isExplicitlyAgentHidden(def: QueryHandlerDef): boolean {
   return def.agent?.expose === false;
 }
 
@@ -146,13 +146,9 @@ function addToolsForListHandler(
   }
 }
 
-function entityDisplayLabel(
-  entity: AgentManifestEntity | undefined,
-  entityName: string,
-  locale: string,
-): string {
+function entityDisplayLabel(entity: AgentManifestEntity | undefined, entityName: string): string {
   if (entity?.description) return entity.description;
-  const label = entity?.labels[locale];
+  const label = entity?.label;
   if (label) return label;
   return entityName;
 }
@@ -285,7 +281,7 @@ function stripFieldFromSchema(
 }
 
 function handlerDescription(handler: AgentManifestHandler): string {
-  return handler.description.length > 0 ? handler.description : `Run ${handler.qn}.`;
+  return handler.description ?? `Run ${handler.qn}.`;
 }
 
 /** Drops the `query`/`write` verb segment from a handler QN, joins the rest with `_`, and
@@ -483,12 +479,11 @@ function addGetTools(
   registry: RegistrySearchView,
   detailQnByEntity: ReadonlyMap<string, string>,
   entityByName: ReadonlyMap<string, AgentManifestEntity>,
-  locale: string,
   sink: CatalogSink,
 ): void {
   const getEntries = [...detailQnByEntity.entries()].sort((a, b) => compareByCodePoint(a[0], b[0]));
   for (const [entityName, qn] of getEntries) {
-    const label = entityDisplayLabel(entityByName.get(entityName), entityName, locale);
+    const label = entityDisplayLabel(entityByName.get(entityName), entityName);
     const { tool, descriptor } = buildGetTool(
       entityName,
       qn,
@@ -504,12 +499,11 @@ function addListTools(
   listQnByEntity: ReadonlyMap<string, string>,
   entityByName: ReadonlyMap<string, AgentManifestEntity>,
   roles: readonly string[],
-  locale: string,
   sink: CatalogSink,
 ): void {
   const listEntries = [...listQnByEntity.entries()].sort((a, b) => compareByCodePoint(a[0], b[0]));
   for (const [entityName, qn] of listEntries) {
-    const label = entityDisplayLabel(entityByName.get(entityName), entityName, locale);
+    const label = entityDisplayLabel(entityByName.get(entityName), entityName);
     const searchableFields = registry.getSearchableFields(entityName);
     const filterableFields = filterableFieldsOf(
       entityByName.get(entityName),
@@ -636,7 +630,6 @@ export function buildToolCatalog(
 ): ToolCatalog {
   const sink: CatalogSink = { tools: [], dispatchTable: new Map(), usedNames: new Set() };
   const roleFilter = { roles: manifest.builtForRoles };
-  const locale = manifest.tenantSettings.locale;
   const entityByName = new Map(manifest.entities.map((entity) => [entity.name, entity]));
   const denyQns = new Set(options.denyQns ?? []);
   assertCatalogMirrorsManifestDenyQns(manifest, denyQns);
@@ -647,8 +640,8 @@ export function buildToolCatalog(
     roleFilter,
     denyQns,
   );
-  addGetTools(registry, detailQnByEntity, entityByName, locale, sink);
-  addListTools(registry, listQnByEntity, entityByName, roleFilter.roles, locale, sink);
+  addGetTools(registry, detailQnByEntity, entityByName, sink);
+  addListTools(registry, listQnByEntity, entityByName, roleFilter.roles, sink);
   addQueryHandlerTools(manifest, entityListDetailQns, denyQns, sink);
   if (options.mode !== "read-only") {
     addWriteHandlerTools(manifest, detailQnByEntity, denyQns, sink);

package/packages/bundled-features/src/agent-tools/types.ts

@@ -125,8 +125,8 @@ export type AgentManifestOptions = {
 export type AgentManifestField = {
   readonly name: string;
   readonly type: string;
-  /** Label per app locale, keyed by locale code. */
-  readonly labels: Readonly<Record<string, string>>;
+  /** Label in the requested locale (English, then any other, as fallback); absent when untranslated. */
+  readonly label?: string;
   readonly description?: string;
   readonly options?: readonly string[];
   /** Entity a `reference` field points at. */
@@ -140,7 +140,7 @@ export type AgentManifestField = {
 
 export type AgentManifestEntity = {
   readonly name: string;
-  readonly labels: Readonly<Record<string, string>>;
+  readonly label?: string;
   readonly description?: string;
   readonly fields: readonly AgentManifestField[];
 };
@@ -148,7 +148,7 @@ export type AgentManifestEntity = {
 export type AgentManifestHandler = {
   readonly qn: string;
   readonly kind: "query" | "write";
-  readonly description: string;
+  readonly description?: string;
   readonly risk: AgentRisk;
   readonly inputSchema: Readonly<Record<string, unknown>>;
   readonly entity?: string;
@@ -159,11 +159,12 @@ export type AgentManifestHandler = {
 export type AgentManifestScreen = {
   readonly id: string;
   readonly type: string;
-  readonly titles: Readonly<Record<string, string>>;
+  readonly title?: string;
   readonly description?: string;
   readonly entity?: string;
-  readonly params: readonly string[];
-  readonly workspaces: readonly string[];
+  /** Only present on detail screens. */
+  readonly params?: readonly string[];
+  readonly workspaces?: readonly string[];
   /** Entity this screen is the detail view for. Distinct from `entity`: a custom
    *  screen can render entity A while being the detail view for B. */
   readonly detailFor?: string;
@@ -173,15 +174,15 @@ export type AgentManifestScreen = {
 
 export type AgentManifestNav = {
   readonly id: string;
-  readonly labels: Readonly<Record<string, string>>;
+  readonly label?: string;
   readonly screen?: string;
   readonly parent?: string;
-  readonly workspaces: readonly string[];
+  readonly workspaces?: readonly string[];
 };
 
 export type AgentManifestWorkspace = {
   readonly id: string;
-  readonly labels: Readonly<Record<string, string>>;
+  readonly label?: string;
   readonly default?: true;
 };
 

package/packages/bundled-features/src/billing-foundation/consumer-protection/confirmation-mail.ts

@@ -2,7 +2,7 @@ import { escapeHtml, escapeHtmlAttr } from "@cosmicdrift/kumiko-renderer/headles
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { Marked } from "marked";
 import {
-  isAllowedDocumentLinkHref,
+  isAllowedDocumentUrlHref,
   isDocumentPlaceholderHref,
 } from "../../template-resolver/index.ts";
 import type { CheckoutConsentRecordedPayload } from "../events.ts";
@@ -149,7 +149,7 @@ function formatDate(iso: string, locale: ConsentLocale, timeZone: string): strin
 const ROW_END = "\n\n";
 
 function isMailLinkHref(href: string): boolean {
-  return isAllowedDocumentLinkHref(href) && !isDocumentPlaceholderHref(href);
+  return isAllowedDocumentUrlHref(href) && !isDocumentPlaceholderHref(href);
 }
 
 const inlineHtmlMarkdown = new Marked({ gfm: false, breaks: false });

package/packages/bundled-features/src/inbound-mail-foundation/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.402.0",
+    "type": "breaking",
+    "title": "The inbound mail supervisor requires a lock and the dedup anchor is unique",
+    "detail": "`createInboundMailSupervisor` takes a required `lock` (a DistributedLock) instead of an optional one, so only one worker holds the IMAP watch per account; the single-process path without a lock is gone. The unmanaged table store_mail_seen_messages gets a unique index on (account_id, provider_message_id), which the ingest comment always promised; ingest-message already serialized concurrent ingests of one mail with a per-message advisory lock, so the second one reports duplicate.",
+    "migration": "Pass `lock: createDistributedLock(redis, \"kumiko:lock:inbound-mail:watch:\")` to createInboundMailSupervisor. Run `kumiko-schema generate <name>` in each app that mounts inbound-mail-foundation to get the migration for the unique index on store_mail_seen_messages; existing rows must hold no duplicate (account_id, provider_message_id)."
+  },
   {
     "version": "0.394.0",
     "type": "improvement",

package/packages/bundled-features/src/inbound-mail-foundation/entities.ts

@@ -231,6 +231,7 @@ export const syncCursorEntity = createEntity({
 export const seenMessageEntity = createEntity({
   table: "store_mail_seen_messages",
   softDelete: false,
+  indexes: [{ unique: true, columns: ["accountId", "providerMessageId"] }],
   fields: {
     accountId: createTextField({
       required: true,

package/packages/bundled-features/src/inbound-mail-foundation/watch-lease.ts

@@ -10,7 +10,7 @@ export type WatchLease = {
 // The cross-worker claim on one account's watch: acquired before plugin.watch(), renewed by a
 // heartbeat for as long as the watcher state exists, and given up locally once it is lost.
 export function createWatchLease(deps: {
-  readonly lock: DistributedLock | undefined;
+  readonly lock: DistributedLock;
   readonly ttlSeconds: number;
   readonly renewIntervalMs: number;
   readonly watchers: ReadonlyMap<string, WatcherState>;
@@ -53,7 +53,7 @@ export function createWatchLease(deps: {
   ): Promise<void> {
     state.renewTimer = null;
     // skip: supervisor stopped, generation superseded, or lease already lost — stale timer fire, nothing to renew.
-    if (!isRunning() || state.generation !== generation || !state.lockToken || !lock) return;
+    if (!isRunning() || state.generation !== generation || !state.lockToken) return;
     let renewed: boolean;
     try {
       renewed = await lock.renew(account.id, state.lockToken, ttlSeconds);
@@ -97,7 +97,7 @@ export function createWatchLease(deps: {
     account: MailAccountRecord,
     state: WatcherState,
   ): Promise<WatchLeaseResult> {
-    if (!lock || state.lockToken) return "acquired";
+    if (state.lockToken) return "acquired";
     // A throwing lock (Redis outage) reads as "not claimed": the next tick retries instead of leaving the start flag set.
     const token = await lock.acquire(account.id, { ttlSeconds: ttlSeconds }).catch((err) => {
       log(

package/packages/bundled-features/src/inbound-mail-foundation/watch-supervisor-types.ts

@@ -41,15 +41,15 @@ export type InboundMailSupervisorDeps = {
   /** Coordinates the IMAP watch (not the poll) across worker processes:
    *  before `plugin.watch()`, ensureWatcher claims a TTL lease for the
    *  account via `lock.acquire` and renews it via `lock.renew` while the
-   *  watcher lives. Omit for single-process deployments — every active
-   *  account is watched locally, same as before. */
-  readonly lock?: DistributedLock;
+   *  watcher lives. Required: without it every worker would hold its own
+   *  IDLE connection per account. */
+  readonly lock: DistributedLock;
   /** Access-token lifecycle for OAuth accounts. Defaults to a manager built
    *  from `db` + `providerCtx.secrets`; pass the instance shared with
    *  `createInboundMailConnectRoutes` so a fresh connect primes this cache. */
   readonly oauthTokens?: OAuthAccessTokenManager;
   /** TTL (seconds) for the per-account watch lease. Default 90s, renewed
-   *  every ttl/3. Only used when `lock` is set. */
+   *  every ttl/3. */
   readonly watchLeaseTtlSeconds?: number;
   readonly log?: (line: string) => void;
 };
@@ -62,7 +62,7 @@ export type WatcherState = {
    *  an already stopped watcher. */
   generation: number;
   /** Token from `deps.lock.acquire` while this worker owns the account's
-   *  watch lease; null when unclaimed (no `deps.lock`, or claim lost). */
+   *  watch lease; null when unclaimed (claim lost). */
   lockToken: string | null;
   renewTimer: ReturnType<typeof setTimeout> | null;
   /** Consecutive renew() throws — tear down once failures span a full TTL. */