@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/agent-tools/agent-doc-lint.ts

@@ -0,0 +1,166 @@
+import type {
+  FeatureDefinition,
+  QueryHandlerDef,
+  WriteHandlerDef,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  isAgentVisibleScreen,
+  QnTypes,
+  qn,
+  resolveAgentExposure,
+  toKebab,
+} from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+
+export const AgentDocGapKinds = {
+  handlerSchemaNotExpressible: "handler-schema-not-expressible",
+  handlerWithoutDescription: "handler-without-description",
+  customScreenWithoutDescription: "custom-screen-without-description",
+  exposedEntityWithoutDescription: "exposed-entity-without-description",
+} as const;
+
+export type AgentDocGapKind = (typeof AgentDocGapKinds)[keyof typeof AgentDocGapKinds];
+
+export type AgentDocGap = {
+  readonly qn: string;
+  readonly feature: string;
+  readonly kind: AgentDocGapKind;
+  readonly message: string;
+};
+
+// No shared screen-type union exists in the codebase to import (ScreenDefinition
+// is a discriminated union keyed by inline string literals) — name the one
+// value this lint cares about instead of comparing against a bare string.
+const CUSTOM_SCREEN_TYPE = "custom";
+
+const ENTITY_QN_SEGMENT = "entity";
+
+// QNs contain `:`, so localeCompare's ICU punctuation rules would make sort
+// order depend on runtime locale — compare by code point instead (same
+// reasoning as agent-manifest.ts's compareIds).
+function compareByCodePoint(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+// agent-manifest.ts silently drops an exposed handler whose schema can't be
+// converted; surface it here so the missing tool doesn't go unnoticed.
+function schemaNotExpressibleGap(
+  feature: FeatureDefinition,
+  handlerQn: string,
+  def: WriteHandlerDef | QueryHandlerDef,
+  handlerNoun: string,
+): AgentDocGap | undefined {
+  try {
+    z.toJSONSchema(def.schema, { io: "input" });
+    return undefined;
+  } catch (error) {
+    return {
+      qn: handlerQn,
+      feature: feature.name,
+      kind: AgentDocGapKinds.handlerSchemaNotExpressible,
+      message: `This ${handlerNoun} is exposed to the AI agent but its input schema can't be converted to JSON Schema (${error instanceof Error ? error.message : String(error)}), so it is left out of the agent manifest.`,
+    };
+  }
+}
+
+function handlerDocGaps(
+  feature: FeatureDefinition,
+  handlers: Readonly<Record<string, WriteHandlerDef | QueryHandlerDef>>,
+  handlerQnType: typeof QnTypes.write | typeof QnTypes.query,
+  handlerNoun: string,
+): readonly AgentDocGap[] {
+  const gaps: AgentDocGap[] = [];
+  const handlerKind = handlerQnType === QnTypes.write ? "write" : "query";
+  for (const [name, def] of Object.entries(handlers)) {
+    const handlerQn = qn(toKebab(feature.name), handlerQnType, toKebab(name));
+    const isExposed = resolveAgentExposure(def, handlerKind).expose;
+    if (isExposed) {
+      const schemaGap = schemaNotExpressibleGap(feature, handlerQn, def, handlerNoun);
+      if (schemaGap) gaps.push(schemaGap);
+    }
+    if (def.agent?.expose === false) continue;
+    if (def.description !== undefined && def.description.trim() !== "") continue;
+    gaps.push({
+      qn: handlerQn,
+      feature: feature.name,
+      kind: AgentDocGapKinds.handlerWithoutDescription,
+      message: isExposed
+        ? `This ${handlerNoun} is exposed to the AI agent but has no usable description, so the agent sees an empty tool text — set a non-empty \`description\`, or \`agent: { expose: false }\` to opt out deliberately.`
+        : `This ${handlerNoun} has no description, so it stays invisible to the AI agent — set \`description\` to expose it, or \`agent: { expose: false }\` to opt out deliberately.`,
+    });
+  }
+  return gaps;
+}
+
+function screenDocGaps(feature: FeatureDefinition): readonly AgentDocGap[] {
+  const gaps: AgentDocGap[] = [];
+  for (const [shortId, screen] of Object.entries(feature.screens ?? {})) {
+    if (
+      screen.type !== CUSTOM_SCREEN_TYPE ||
+      screen.description !== undefined ||
+      !isAgentVisibleScreen(screen)
+    )
+      continue;
+    gaps.push({
+      qn: qn(toKebab(feature.name), QnTypes.screen, toKebab(shortId)),
+      feature: feature.name,
+      kind: AgentDocGapKinds.customScreenWithoutDescription,
+      message:
+        "This custom screen has no description, so the AI agent can't tell what it's for — set `description` to explain it, or `agent: { expose: false }` to hide it from the agent deliberately.",
+    });
+  }
+  return gaps;
+}
+
+// The handlerEntityMappings record can't distinguish write from query
+// namespaces (both share one short-name-keyed map), so both must be probed
+// per mapped handler name.
+function agentVisibleEntityNames(feature: FeatureDefinition): ReadonlySet<string> {
+  const entityNames = new Set<string>();
+  for (const [handlerName, entityName] of Object.entries(feature.handlerEntityMappings ?? {})) {
+    const writeDef = feature.writeHandlers?.[handlerName];
+    if (writeDef && resolveAgentExposure(writeDef, "write").expose) entityNames.add(entityName);
+    const queryDef = feature.queryHandlers?.[handlerName];
+    if (queryDef && resolveAgentExposure(queryDef, "query").expose) entityNames.add(entityName);
+  }
+  return entityNames;
+}
+
+function exposedEntityDocGaps(feature: FeatureDefinition): readonly AgentDocGap[] {
+  const gaps: AgentDocGap[] = [];
+  for (const entityName of agentVisibleEntityNames(feature)) {
+    const entity = feature.entities?.[entityName];
+    if (!entity || entity.description !== undefined) continue;
+    gaps.push({
+      // Registry keeps entities under their raw, non-kebab name (unlike
+      // handlers/screens) — qn() would throw on a camelCase segment.
+      qn: `${toKebab(feature.name)}:${ENTITY_QN_SEGMENT}:${entityName}`,
+      feature: feature.name,
+      kind: AgentDocGapKinds.exposedEntityWithoutDescription,
+      message:
+        "This entity is reachable through an agent-visible handler, but the agent can't explain its schema — set `description` to describe it.",
+    });
+  }
+  return gaps;
+}
+
+export function findAgentDocGaps(features: readonly FeatureDefinition[]): readonly AgentDocGap[] {
+  const gaps: AgentDocGap[] = [];
+  for (const feature of features) {
+    gaps.push(
+      ...handlerDocGaps(feature, feature.writeHandlers ?? {}, QnTypes.write, "write handler"),
+    );
+    gaps.push(
+      ...handlerDocGaps(feature, feature.queryHandlers ?? {}, QnTypes.query, "query handler"),
+    );
+    gaps.push(...screenDocGaps(feature));
+    gaps.push(...exposedEntityDocGaps(feature));
+  }
+  // Map/Record iteration follows feature-mount order; the result must not
+  // depend on it (mirrors agent-manifest.ts's sortedByKey rationale).
+  return [...gaps].sort((a, b) => compareByCodePoint(a.qn, b.qn));
+}
+
+export function formatAgentDocGap(gap: AgentDocGap): string {
+  return `${gap.qn} — ${gap.message}`;
+}

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

@@ -0,0 +1,460 @@
+import type {
+  AccessRule,
+  EntityDefinition,
+  FeatureDefinition,
+  FieldDefinition,
+  NavDefinition,
+  QueryHandlerDef,
+  ScreenDefinition,
+  TranslationEntry,
+  TranslationKeys,
+  WorkspaceDefinition,
+  WriteHandlerDef,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  hasAccess,
+  isAgentVisibleScreen,
+  resolveAgentExposure,
+  SYSTEM_ONLY_JSON_SCHEMA_KEY,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { translationValueOtherText } from "@cosmicdrift/kumiko-framework/ui-types";
+import * as z from "zod";
+import type {
+  AgentManifest,
+  AgentManifestEntity,
+  AgentManifestFeature,
+  AgentManifestField,
+  AgentManifestHandler,
+  AgentManifestNav,
+  AgentManifestOptions,
+  AgentManifestScreen,
+  AgentManifestWorkspace,
+  RegistryManifestView,
+} from "./types.js";
+
+/** 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>> {
+  return Object.fromEntries(
+    Object.entries(entry).map(([locale, value]) => [locale, translationValueOtherText(value)]),
+  );
+}
+
+const labelsIndexByTranslations = new WeakMap<
+  TranslationKeys,
+  Map<string, Readonly<Record<string, string>>>
+>();
+
+/** Every tail starting at a key boundary (`:` or `.`, with and without the
+ *  separator) maps to the labels of the first key that ends with it. */
+function buildSuffixIndex(
+  translations: TranslationKeys,
+): Map<string, Readonly<Record<string, string>>> {
+  const index = new Map<string, Readonly<Record<string, string>>>();
+  for (const [key, entry] of Object.entries(translations)) {
+    const labels = entryAsLabels(entry);
+    const addTail = (start: number): void => {
+      const tail = key.slice(start);
+      if (!index.has(tail)) index.set(tail, labels);
+    };
+    addTail(0);
+    for (let position = 0; position < key.length; position++) {
+      if (key[position] === ":" || key[position] === ".") {
+        addTail(position);
+        addTail(position + 1);
+      }
+    }
+  }
+  return index;
+}
+
+/** Translation keys carry a feature prefix the manifest can't reconstruct
+ *  (`showcase:entity:item:field:title`), so match on the suffix instead. The
+ *  suffix must start at a `:` or `.` boundary of the key. */
+function labelsForSuffix(
+  translations: TranslationKeys,
+  suffix: string,
+): Readonly<Record<string, string>> {
+  let index = labelsIndexByTranslations.get(translations);
+  if (index === undefined) {
+    index = buildSuffixIndex(translations);
+    labelsIndexByTranslations.set(translations, index);
+  }
+  return index.get(suffix) ?? {};
+}
+
+/** Nav/screen/workspace gating is opt-in: no rule means visible to everyone
+ *  (NavDefinition.access). Handlers are the opposite — `hasAccess` is
+ *  default-deny there. */
+function uiVisible(access: AccessRule | undefined, roles: readonly string[]): boolean {
+  return access === undefined || hasAccess({ roles }, access);
+}
+
+// localeCompare depends on the runtime locale and ICU punctuation rules; qualified
+// names contain `:`, so compare by code point instead for deterministic ordering.
+function compareIds(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+function dedupeSorted(values: readonly string[]): readonly string[] {
+  return [...new Set(values)].sort(compareIds);
+}
+
+// Map iteration follows the feature-mount order; the manifest must not depend on it.
+function sortedByKey<T>(items: readonly T[], key: (item: T) => string): readonly T[] {
+  return [...items].sort((a, b) => compareIds(key(a), key(b)));
+}
+
+function visibleWorkspaceIds(
+  workspaceIds: readonly string[] | undefined,
+  workspaces: ReadonlyMap<string, WorkspaceDefinition>,
+  roles: readonly string[],
+): readonly string[] {
+  if (!workspaceIds) return [];
+  return dedupeSorted(
+    workspaceIds.filter((id) => {
+      const workspace = workspaces.get(id);
+      return workspace !== undefined && uiVisible(workspace.access, roles);
+    }),
+  );
+}
+
+function isFilterableField(field: FieldDefinition): boolean {
+  return "filterable" in field && field.filterable === true;
+}
+
+function isPiiField(field: FieldDefinition): boolean {
+  return "pii" in field && field.pii === true;
+}
+
+function buildField(
+  entityName: string,
+  fieldName: string,
+  field: FieldDefinition,
+  translations: TranslationKeys,
+  searchableFields: ReadonlySet<string>,
+): AgentManifestField {
+  const options =
+    field.type === "select" || field.type === "multiSelect" ? field.options : undefined;
+  const references = field.type === "reference" ? field.entity : undefined;
+
+  return {
+    name: fieldName,
+    type: field.type,
+    labels: labelsForSuffix(translations, `:entity:${entityName}:field:${fieldName}`),
+    ...(field.description !== undefined && { description: field.description }),
+    ...(options !== undefined && { options }),
+    ...(references !== undefined && { references }),
+    ...(searchableFields.has(fieldName) && { searchable: true as const }),
+    ...(isFilterableField(field) && { filterable: true as const }),
+    ...(isPiiField(field) && { pii: true as const }),
+  };
+}
+
+/** 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. */
+function buildEntities(
+  entities: ReadonlyMap<string, EntityDefinition>,
+  translations: TranslationKeys,
+  getSearchableFields: (entityName: string) => readonly string[],
+): readonly AgentManifestEntity[] {
+  const result: AgentManifestEntity[] = [];
+  for (const [entityName, entity] of entities) {
+    const searchableFields = new Set(getSearchableFields(entityName));
+    const fields = Object.entries(entity.fields).map(([fieldName, field]) =>
+      buildField(entityName, fieldName, field, translations, searchableFields),
+    );
+    result.push({
+      name: entityName,
+      labels: labelsForSuffix(translations, `:entity:${entityName}`),
+      ...(entity.description !== undefined && { description: entity.description }),
+      fields,
+    });
+  }
+  return result;
+}
+
+function buildFeatures(
+  features: ReadonlyMap<string, FeatureDefinition>,
+): readonly AgentManifestFeature[] {
+  const result: AgentManifestFeature[] = [];
+  for (const [, feature] of features) {
+    result.push({
+      name: feature.name,
+      ...(feature.description !== undefined && { description: feature.description }),
+      ...(feature.uiHints?.displayLabel !== undefined && {
+        displayLabel: feature.uiHints.displayLabel,
+      }),
+    });
+  }
+  return result;
+}
+
+// Agent dispatch never runs as a system identity, so properties the engine only
+// honors for system callers would be silently dropped — hide them from the tool.
+function withoutSystemOnlyProperties(
+  jsonSchema: Record<string, unknown>,
+): Readonly<Record<string, unknown>> {
+  const properties = jsonSchema["properties"];
+  if (typeof properties !== "object" || properties === null) return jsonSchema;
+  const hidden = Object.entries(properties)
+    .filter(
+      ([, property]) => (property as Record<string, unknown>)[SYSTEM_ONLY_JSON_SCHEMA_KEY] === true,
+    )
+    .map(([name]) => name);
+  if (hidden.length === 0) return jsonSchema;
+  const required = jsonSchema["required"];
+  return {
+    ...jsonSchema,
+    properties: Object.fromEntries(
+      Object.entries(properties).filter(([name]) => !hidden.includes(name)),
+    ),
+    ...(Array.isArray(required) && { required: required.filter((name) => !hidden.includes(name)) }),
+  };
+}
+
+function buildHandlerEntry(
+  qn: string,
+  kind: "query" | "write",
+  def: QueryHandlerDef | WriteHandlerDef,
+  roles: readonly string[],
+  getHandlerEntity: (qualifiedHandler: string) => string | undefined,
+  denyQns: ReadonlySet<string>,
+): AgentManifestHandler | undefined {
+  if (denyQns.has(qn)) return undefined;
+  const exposure = resolveAgentExposure(def, kind);
+  if (!exposure.expose) return undefined;
+  if (!hasAccess({ roles }, def.access)) return undefined;
+
+  // `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 ?? "";
+
+  let inputSchema: Readonly<Record<string, unknown>>;
+  try {
+    // A handler whose schema can't be expressed as JSON Schema (transforms,
+    // z.instanceof, ...) is unusable for an agent tool call — leave it out
+    // rather than ship a broken tool.
+    inputSchema = withoutSystemOnlyProperties(
+      z.toJSONSchema(def.schema, { io: "input" }) as Record<string, unknown>,
+    );
+  } catch {
+    return undefined;
+  }
+
+  const entity = getHandlerEntity(qn);
+  return {
+    qn,
+    kind,
+    description,
+    risk: exposure.risk,
+    inputSchema,
+    ...(entity !== undefined && { entity }),
+  };
+}
+
+function buildHandlers(
+  queryHandlers: ReadonlyMap<string, QueryHandlerDef>,
+  writeHandlers: ReadonlyMap<string, WriteHandlerDef>,
+  roles: readonly string[],
+  getHandlerEntity: (qualifiedHandler: string) => string | undefined,
+  denyQns: ReadonlySet<string>,
+): readonly AgentManifestHandler[] {
+  const result: AgentManifestHandler[] = [];
+  for (const [qn, def] of queryHandlers) {
+    const entry = buildHandlerEntry(qn, "query", def, roles, getHandlerEntity, denyQns);
+    if (entry) result.push(entry);
+  }
+  for (const [qn, def] of writeHandlers) {
+    const entry = buildHandlerEntry(qn, "write", def, roles, getHandlerEntity, denyQns);
+    if (entry) result.push(entry);
+  }
+  return result;
+}
+
+// A typo or a QN renamed by a framework update would otherwise deny nothing
+// and leave the handler exposed without anyone noticing.
+function assertDenyQnsExist(denyQns: readonly string[], registry: RegistryManifestView): void {
+  const queryHandlers = registry.getAllQueryHandlers();
+  const writeHandlers = registry.getAllWriteHandlers();
+  const unknown = denyQns.filter((qn) => !queryHandlers.has(qn) && !writeHandlers.has(qn));
+  if (unknown.length > 0) {
+    throw new Error(`agent denyQns names handlers that are not registered: ${unknown.join(", ")}`);
+  }
+}
+
+function buildNavs(
+  navs: ReadonlyMap<string, NavDefinition>,
+  workspaces: ReadonlyMap<string, WorkspaceDefinition>,
+  translations: TranslationKeys,
+  roles: readonly string[],
+  screens: ReadonlyMap<string, ScreenDefinition>,
+): readonly AgentManifestNav[] {
+  const result: AgentManifestNav[] = [];
+  for (const [, nav] of navs) {
+    if (!uiVisible(nav.access, roles)) continue;
+    // A nav pointing at an opted-out screen would leak its id and label back
+    // into the manifest the screen was just removed from.
+    const target = nav.screen !== undefined ? screens.get(nav.screen) : undefined;
+    if (target !== undefined && !isAgentVisibleScreen(target)) continue;
+    const visibleWorkspaces = visibleWorkspaceIds(nav.workspaces, workspaces, roles);
+    const hasWorkspaces = nav.workspaces !== undefined && nav.workspaces.length > 0;
+    if (hasWorkspaces && visibleWorkspaces.length === 0) continue;
+
+    result.push({
+      id: nav.id,
+      labels: entryAsLabels(translations[nav.label] ?? {}),
+      ...(nav.screen !== undefined && { screen: nav.screen }),
+      ...(nav.parent !== undefined && { parent: nav.parent }),
+      workspaces: visibleWorkspaces,
+    });
+  }
+  return withoutOrphanedNavs(result);
+}
+
+// A child under a parent hidden from this role would point at an id that
+// isn't in the manifest; hiding cascades down the whole subtree.
+function withoutOrphanedNavs(navs: readonly AgentManifestNav[]): readonly AgentManifestNav[] {
+  let remaining = navs;
+  for (;;) {
+    const ids = new Set(remaining.map((nav) => nav.id));
+    const reachable = remaining.filter((nav) => nav.parent === undefined || ids.has(nav.parent));
+    if (reachable.length === remaining.length) return remaining;
+    remaining = reachable;
+  }
+}
+
+function lastSegment(qualifiedId: string): string {
+  const idx = qualifiedId.lastIndexOf(":");
+  return idx === -1 ? qualifiedId : qualifiedId.slice(idx + 1);
+}
+
+function detailIdParam(screen: ScreenDefinition): string {
+  return screen.type === "projectionDetail" ? (screen.idParam ?? "id") : "id";
+}
+
+function buildScreens(
+  screens: ReadonlyMap<string, ScreenDefinition>,
+  navs: ReadonlyMap<string, NavDefinition>,
+  workspaces: ReadonlyMap<string, WorkspaceDefinition>,
+  translations: TranslationKeys,
+  roles: readonly string[],
+  visibleNavIds: ReadonlySet<string>,
+): readonly AgentManifestScreen[] {
+  const allNavs = [...navs.values()];
+  const result: AgentManifestScreen[] = [];
+
+  for (const [, screen] of screens) {
+    // An opted-out screen must not reach the manifest at all — the tool catalog
+    // builds `navigate`'s screen-id enum straight from `manifest.screens`.
+    if (!isAgentVisibleScreen(screen)) continue;
+    const matchingNavs = allNavs.filter((nav) => nav.screen === screen.id);
+    const accessibleNavs = matchingNavs.filter(
+      (nav) => visibleNavIds.has(nav.id) && uiVisible(nav.access, roles),
+    );
+
+    // A screen with no nav pointing at it is a detail view, reached only via
+    // navigation from a list row — never hidden by nav/workspace gating.
+    const reachable =
+      matchingNavs.length === 0 ||
+      accessibleNavs.some((nav) => {
+        if (!nav.workspaces || nav.workspaces.length === 0) return true;
+        return visibleWorkspaceIds(nav.workspaces, workspaces, roles).length > 0;
+      });
+    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: labelsForSuffix(translations, `screen:${shortId}.title`),
+      // `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 }),
+    });
+  }
+  return result;
+}
+
+function buildWorkspaces(
+  workspaces: ReadonlyMap<string, WorkspaceDefinition>,
+  translations: TranslationKeys,
+  roles: readonly 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] ?? {}),
+      ...(workspace.default === true && { default: true as const }),
+    });
+  }
+  return result;
+}
+
+/** Registry snapshot → AI-agent manifest. Pure, deterministic, no I/O — mirrors
+ *  `buildToolCatalog`'s contract, just describing the app's shape instead of
+ *  generating callable tools from it. */
+export function buildAgentManifest(
+  registry: RegistryManifestView,
+  options: AgentManifestOptions,
+): AgentManifest {
+  const translations = registry.getAllTranslations();
+  const workspaceMap = registry.getAllWorkspaces();
+  const navMap = registry.getAllNavs();
+  const { roles } = options;
+  assertDenyQnsExist(options.denyQns ?? [], registry);
+
+  const features = buildFeatures(registry.features);
+  const entities = buildEntities(registry.getAllEntities(), translations, (name) =>
+    registry.getSearchableFields(name),
+  );
+  const handlers = buildHandlers(
+    registry.getAllQueryHandlers(),
+    registry.getAllWriteHandlers(),
+    roles,
+    (qn) => registry.getHandlerEntity(qn),
+    new Set(options.denyQns ?? []),
+  );
+  const screenMap = registry.getAllScreens();
+  const navs = buildNavs(navMap, workspaceMap, translations, roles, screenMap);
+  const screens = buildScreens(
+    screenMap,
+    navMap,
+    workspaceMap,
+    translations,
+    roles,
+    new Set(navs.map((nav) => nav.id)),
+  );
+  const workspaces = buildWorkspaces(workspaceMap, translations, roles);
+
+  return {
+    builtForRoles: [...roles],
+    features: sortedByKey(features, (f) => f.name),
+    entities: sortedByKey(entities, (e) => e.name),
+    handlers: sortedByKey(handlers, (h) => h.qn),
+    screens: sortedByKey(screens, (s) => s.id),
+    navs: sortedByKey(navs, (n) => n.id),
+    workspaces: sortedByKey(workspaces, (w) => w.id),
+    tenantSettings: {
+      locale: options.locale,
+      ...(options.currency && { currency: options.currency }),
+    },
+  };
+}

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

@@ -0,0 +1,40 @@
+[
+  {
+    "version": "0.338.0",
+    "type": "improvement",
+    "title": "entity get/list tools honour agent.risk, PII-bearing system lists are high risk",
+    "detail": "agent-tools: `get_<entity>` and `list_<entity>` take their risk from the entity handler's `agent.risk` instead of a hard-coded `low`. The SystemAdmin `user:list`, `user:detail` and `download-attempt:list` handlers declare `risk: \"high\"`.",
+    "migration": "No action needed: handlers without an agent.risk hint stay low risk."
+  },
+  {
+    "version": "0.338.0",
+    "type": "fix",
+    "title": "agent entity tools no longer filter on read-restricted fields",
+    "detail": "agent-tools: `list_<entity>` filters and `find_<entity>_by_<field>` tools only offer filterable fields that every caller role may read without a row condition. A role- or ownership-restricted filterable field can no longer be probed through `totalCount` or hit/miss results.",
+    "migration": "No action needed: fields whose access.read is not unconditionally open to the agent's roles drop out of list filters and find-by tools."
+  },
+  {
+    "version": "0.337.0",
+    "type": "fix",
+    "title": "agent tool name collisions are disambiguated, audit search is substring, encrypted config bounds errors do not echo the value",
+    "detail": "The agent manifest reports a detail screen's configured `idParam` and builds its label index once per manifest. Handler tools whose names collide after sanitizing or truncation are no longer dropped; the later one gets a QN-hash suffix. The audit log search matches event types by substring instead of exact equality. Config bounds errors no longer echo an encrypted value. The MFA account label never falls back to the internal user id. The tenant caps list resolves limits in parallel."
+  },
+  {
+    "version": "0.335.0",
+    "type": "breaking",
+    "title": "Manifest rejects unknown denyQns, drops navs under hidden parents; doc lint flags blank and exposed-undescribed handlers",
+    "detail": "Agent tools: `buildAgentManifest` now throws when `denyQns` names a handler that is not registered, so a typo can no longer leave a handler exposed. Navs whose parent is hidden from the role are dropped from the manifest, and screens reachable only through them are no longer listed. The agent doc lint reports handlers that are exposed without a description and treats a blank description as a gap.",
+    "migration": "`buildAgentManifest` now throws when `denyQns` names a handler that is not registered; remove stale or misspelled entries from your `denyQns` lists."
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "Agent doc lint reports exposed handlers with a non-convertible input schema"
+  },
+  {
+    "version": "0.313.0",
+    "type": "fix",
+    "title": "Agent manifest now resolves a screen's i18n-key description to English prose",
+    "detail": "buildAgentManifest passed screen.description straight through even when\na feature registered it as an i18n key (e.g. \"audit.log.detail.subtitle\")\nrather than literal text, so agents saw the raw key instead of prose.\nIt now resolves through the registry's translations the same way\nlabelsForSuffix already does for entity/field labels, falling back to\nthe literal string when the description isn't a registered key."
+  }
+]