@cosmicdrift/kumiko-bundled-features 0.235.2 → 0.235.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.235.2",
+  "version": "0.235.4",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -130,12 +130,12 @@
     "./workflow-runner": "./src/workflow-runner/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.235.2",
-    "@cosmicdrift/kumiko-framework": "0.235.2",
-    "@cosmicdrift/kumiko-headless": "0.235.2",
-    "@cosmicdrift/kumiko-renderer": "0.235.2",
-    "@cosmicdrift/kumiko-renderer-web": "0.235.2",
-    "@cosmicdrift/kumiko-types": "0.235.2",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.235.4",
+    "@cosmicdrift/kumiko-framework": "0.235.4",
+    "@cosmicdrift/kumiko-headless": "0.235.4",
+    "@cosmicdrift/kumiko-renderer": "0.235.4",
+    "@cosmicdrift/kumiko-renderer-web": "0.235.4",
+    "@cosmicdrift/kumiko-types": "0.235.4",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -164,7 +164,7 @@
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
     "@types/qrcode": "^1.5.5",
-    "@cosmicdrift/kumiko-locale-de": "0.235.2",
-    "@cosmicdrift/kumiko-locale-es": "0.235.2"
+    "@cosmicdrift/kumiko-locale-de": "0.235.4",
+    "@cosmicdrift/kumiko-locale-es": "0.235.4"
   }
 }

package/src/agent-tools/__tests__/agent-doc-lint.test.ts

@@ -0,0 +1,200 @@
+import { describe, expect, test } from "bun:test";
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { AgentDocGapKinds, findAgentDocGaps, formatAgentDocGap } from "../agent-doc-lint";
+
+const OPEN_ACCESS = { openToAll: true } as const;
+
+async function noopWriteHandler() {
+  return { isSuccess: true as const, data: {} };
+}
+
+async function noopQueryHandler() {
+  return {};
+}
+
+describe("findAgentDocGaps", () => {
+  test("R1: exactly three undescribed handlers -> exactly three gaps with the expected QNs", () => {
+    const feature = defineFeature("doc-gap-demo", (r) => {
+      r.writeHandler("do-a", z.object({}), noopWriteHandler, { access: OPEN_ACCESS });
+      r.writeHandler("do-b", z.object({}), noopWriteHandler, { access: OPEN_ACCESS });
+      r.queryHandler("get-c", z.object({}), noopQueryHandler, { access: OPEN_ACCESS });
+    });
+
+    const gaps = findAgentDocGaps([feature]);
+
+    expect(gaps).toHaveLength(3);
+    expect(gaps.map((g) => g.qn)).toEqual([
+      "doc-gap-demo:query:get-c",
+      "doc-gap-demo:write:do-a",
+      "doc-gap-demo:write:do-b",
+    ]);
+  });
+
+  test("R1: handler with description -> no gap", () => {
+    const feature = defineFeature("doc-gap-demo", (r) => {
+      r.writeHandler("do-a", z.object({}), noopWriteHandler, {
+        access: OPEN_ACCESS,
+        description: "Does A.",
+      });
+    });
+
+    expect(findAgentDocGaps([feature])).toHaveLength(0);
+  });
+
+  test("R1: handler with agent.expose:false opt-out -> no gap", () => {
+    const feature = defineFeature("doc-gap-demo", (r) => {
+      r.writeHandler("do-a", z.object({}), noopWriteHandler, {
+        access: OPEN_ACCESS,
+        agent: { expose: false },
+      });
+    });
+
+    expect(findAgentDocGaps([feature])).toHaveLength(0);
+  });
+
+  test("R2: custom screen without description -> exactly one gap with the correct QN", () => {
+    const feature = defineFeature("doc-gap-demo", (r) => {
+      r.screen({ id: "widget-editor", type: "custom", renderer: { react: "stub" } });
+    });
+
+    const gaps = findAgentDocGaps([feature]);
+    expect(gaps).toHaveLength(1);
+    expect(gaps[0]?.qn).toBe("doc-gap-demo:screen:widget-editor");
+  });
+
+  test("R2: custom screen WITH description -> no gap", () => {
+    const feature = defineFeature("doc-gap-demo", (r) => {
+      r.screen({
+        id: "widget-editor",
+        type: "custom",
+        renderer: { react: "stub" },
+        description: "Edits a widget.",
+      });
+    });
+
+    expect(findAgentDocGaps([feature])).toHaveLength(0);
+  });
+
+  test("R2: non-custom screen without description -> no gap (only custom screens are linted)", () => {
+    const feature = defineFeature("doc-gap-demo", (r) => {
+      r.entity("widget", { fields: {}, description: "A widget." });
+      r.screen({ id: "widget-list", type: "entityList", entity: "widget", columns: [] });
+    });
+
+    expect(findAgentDocGaps([feature])).toHaveLength(0);
+  });
+
+  test("R3: entity without description with two agent-visible handlers -> exactly one gap", () => {
+    const feature = defineFeature("widgets", (r) => {
+      r.entity("widget", { fields: {} });
+      r.writeHandler("widget:create", z.object({}), noopWriteHandler, {
+        access: OPEN_ACCESS,
+        description: "Creates a widget.",
+      });
+      r.writeHandler("widget:update", z.object({}), noopWriteHandler, {
+        access: OPEN_ACCESS,
+        description: "Updates a widget.",
+      });
+    });
+
+    const gaps = findAgentDocGaps([feature]);
+    const entityGaps = gaps.filter((g) => g.qn === "widgets:entity:widget");
+    expect(entityGaps).toHaveLength(1);
+  });
+
+  test("R3: entity WITH description -> no entity gap", () => {
+    const feature = defineFeature("widgets", (r) => {
+      r.entity("widget", { fields: {}, description: "A widget." });
+      r.writeHandler("widget:create", z.object({}), noopWriteHandler, {
+        access: OPEN_ACCESS,
+        description: "Creates a widget.",
+      });
+    });
+
+    expect(findAgentDocGaps([feature]).some((g) => g.qn === "widgets:entity:widget")).toBe(false);
+  });
+
+  test("R3: entity whose only mapped handler opts out via agent.expose:false -> no entity gap", () => {
+    const feature = defineFeature("widgets", (r) => {
+      r.entity("widget", { fields: {} });
+      r.writeHandler("widget:create", z.object({}), noopWriteHandler, {
+        access: OPEN_ACCESS,
+        agent: { expose: false },
+      });
+    });
+
+    expect(findAgentDocGaps([feature]).some((g) => g.qn === "widgets:entity:widget")).toBe(false);
+  });
+
+  test("R3: fires for an agent-visible QUERY handler too (handlerEntityMappings can't distinguish namespaces)", () => {
+    const feature = defineFeature("widgets", (r) => {
+      r.entity("widget", { fields: {} });
+      r.queryHandler("widget:list", z.object({}), noopQueryHandler, {
+        access: OPEN_ACCESS,
+        description: "Lists widgets.",
+      });
+    });
+
+    const gaps = findAgentDocGaps([feature]);
+    expect(gaps.filter((g) => g.qn === "widgets:entity:widget")).toHaveLength(1);
+  });
+
+  test("R3: camelCase entity name -> qn keeps the raw name, not kebab-cased", () => {
+    const feature = defineFeature("document-ingest", (r) => {
+      r.entity("documentExtract", { fields: {} });
+      r.writeHandler("documentExtract:create", z.object({}), noopWriteHandler, {
+        access: OPEN_ACCESS,
+        description: "Creates a document extract.",
+      });
+    });
+
+    const gaps = findAgentDocGaps([feature]);
+    const entityGaps = gaps.filter(
+      (g) => g.kind === AgentDocGapKinds.exposedEntityWithoutDescription,
+    );
+    expect(entityGaps).toHaveLength(1);
+    expect(entityGaps[0]?.qn).toBe("document-ingest:entity:documentExtract");
+  });
+
+  test("clean registry (everything described) -> empty array", () => {
+    const feature = defineFeature("widgets", (r) => {
+      r.entity("widget", { fields: {}, description: "A widget." });
+      r.writeHandler("widget:create", z.object({}), noopWriteHandler, {
+        access: OPEN_ACCESS,
+        description: "Creates a widget.",
+      });
+      r.screen({
+        id: "widget-editor",
+        type: "custom",
+        renderer: { react: "stub" },
+        description: "Edits a widget.",
+      });
+    });
+
+    expect(findAgentDocGaps([feature])).toEqual([]);
+  });
+
+  test("result is sorted by qn", () => {
+    const feature = defineFeature("doc-gap-demo", (r) => {
+      r.queryHandler("get-z", z.object({}), noopQueryHandler, { access: OPEN_ACCESS });
+      r.writeHandler("do-a", z.object({}), noopWriteHandler, { access: OPEN_ACCESS });
+      r.screen({ id: "widget-editor", type: "custom", renderer: { react: "stub" } });
+    });
+
+    const qns = findAgentDocGaps([feature]).map((g) => g.qn);
+    expect(qns).toEqual([...qns].sort());
+  });
+
+  test("formatAgentDocGap includes the qn and the reason", () => {
+    const feature = defineFeature("doc-gap-demo", (r) => {
+      r.writeHandler("do-a", z.object({}), noopWriteHandler, { access: OPEN_ACCESS });
+    });
+
+    const [gap] = findAgentDocGaps([feature]);
+    expect(gap).toBeDefined();
+    const formatted = formatAgentDocGap(gap as NonNullable<typeof gap>);
+    expect(formatted).toContain((gap as NonNullable<typeof gap>).qn);
+    expect(formatted).toContain((gap as NonNullable<typeof gap>).message);
+  });
+});

package/src/agent-tools/__tests__/agent-manifest.test.ts

@@ -0,0 +1,180 @@
+import { describe, expect, test } from "bun:test";
+import {
+  createEntity,
+  createRegistry,
+  createSelectField,
+  createTextField,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+import type { ReferenceFieldDef, TextFieldDef } from "@cosmicdrift/kumiko-framework/engine/types";
+import { z } from "zod";
+import { buildAgentManifest } from "../agent-manifest";
+
+const gatedEntity = createEntity({
+  fields: {
+    status: createSelectField({ options: ["draft", "active"] as const, filterable: true }),
+    ownerId: { type: "reference", entity: "user" } satisfies ReferenceFieldDef,
+    title: createTextField({ searchable: true }),
+    // Raw ResolvedPiiFlags form — the manifest is schema, not rows, so this
+    // must never surface a value, only the marker.
+    secretNote: { type: "text", pii: true } satisfies TextFieldDef,
+  },
+});
+
+function buildTestFeature() {
+  return defineFeature("agent-manifest-test", (r) => {
+    r.entity("widget", gatedEntity);
+
+    r.queryHandler("widget:lookup", z.object({ id: z.string() }), async () => ({}), {
+      access: { roles: ["admin", "viewer"] },
+      description: "Look up a widget by id.",
+    });
+
+    r.writeHandler(
+      "widget:archive",
+      z.object({ id: z.string() }),
+      async () => ({ isSuccess: true, data: {} }),
+      {
+        access: { roles: ["admin"] },
+        description: "Archive a widget.",
+      },
+    );
+
+    r.queryHandler("widget:undescribed", z.object({ id: z.string() }), async () => ({}), {
+      access: { roles: ["admin", "viewer"] },
+    });
+
+    r.queryHandler(
+      "widget:oddschema",
+      z.object({ occurredAt: z.instanceof(Date) }),
+      async () => ({}),
+      {
+        access: { roles: ["admin", "viewer"] },
+        description: "Takes a schema z.toJSONSchema cannot express.",
+      },
+    );
+  });
+}
+
+const otherEntity = createEntity({
+  fields: {
+    label: createTextField({ searchable: true }),
+  },
+});
+
+// Name sorts alphabetically before "agent-manifest-test" so mount order and
+// sort order provably diverge in the determinism test below.
+function buildOtherFeature() {
+  return defineFeature("aa-other-feature", (r) => {
+    r.entity("other", otherEntity);
+
+    r.queryHandler("other:lookup", z.object({ id: z.string() }), async () => ({}), {
+      access: { roles: ["admin"] },
+      description: "Look up an other by id.",
+    });
+  });
+}
+
+describe("buildAgentManifest", () => {
+  test("fail-closed: a handler without description and without agent.expose is never exposed", () => {
+    const registry = createRegistry([buildTestFeature()]);
+    const admin = buildAgentManifest(registry, { locale: "en", roles: ["admin"] });
+    const viewer = buildAgentManifest(registry, { locale: "en", roles: ["viewer"] });
+
+    expect(admin.handlers.some((h) => h.qn.endsWith(":undescribed"))).toBe(false);
+    expect(viewer.handlers.some((h) => h.qn.endsWith(":undescribed"))).toBe(false);
+  });
+
+  test("role gating: viewer sees the query handler but not the admin-only write handler", () => {
+    const registry = createRegistry([buildTestFeature()]);
+    const viewer = buildAgentManifest(registry, { locale: "en", roles: ["viewer"] });
+    const admin = buildAgentManifest(registry, { locale: "en", roles: ["admin"] });
+
+    expect(viewer.handlers.some((h) => h.qn.endsWith(":lookup"))).toBe(true);
+    expect(viewer.handlers.some((h) => h.qn.endsWith(":archive"))).toBe(false);
+    expect(admin.handlers.some((h) => h.qn.endsWith(":lookup"))).toBe(true);
+    expect(admin.handlers.some((h) => h.qn.endsWith(":archive"))).toBe(true);
+  });
+
+  test("risk defaults: query defaults to low, write defaults to mid", () => {
+    const registry = createRegistry([buildTestFeature()]);
+    const admin = buildAgentManifest(registry, { locale: "en", roles: ["admin"] });
+
+    const queryHandler = admin.handlers.find((h) => h.qn.endsWith(":lookup"));
+    const writeHandler = admin.handlers.find((h) => h.qn.endsWith(":archive"));
+
+    expect(queryHandler?.risk).toBe("low");
+    expect(writeHandler?.risk).toBe("mid");
+  });
+
+  test("inputSchema is a real JSON Schema derived from the zod schema's properties", () => {
+    const registry = createRegistry([buildTestFeature()]);
+    const admin = buildAgentManifest(registry, { locale: "en", roles: ["admin"] });
+    const queryHandler = admin.handlers.find((h) => h.qn.endsWith(":lookup"));
+
+    expect(queryHandler?.inputSchema).toMatchObject({
+      type: "object",
+      properties: { id: { type: "string" } },
+    });
+  });
+
+  test("a handler whose schema toJSONSchema cannot express is dropped, others stay", () => {
+    const registry = createRegistry([buildTestFeature()]);
+    const admin = buildAgentManifest(registry, { locale: "en", roles: ["admin"] });
+
+    expect(admin.handlers.some((h) => h.qn.endsWith(":oddschema"))).toBe(false);
+    expect(admin.handlers.some((h) => h.qn.endsWith(":lookup"))).toBe(true);
+    expect(admin.handlers.some((h) => h.qn.endsWith(":archive"))).toBe(true);
+  });
+
+  test("PII field carries only the marker, never a value", () => {
+    const registry = createRegistry([buildTestFeature()]);
+    const admin = buildAgentManifest(registry, { locale: "en", roles: ["admin"] });
+    const widget = admin.entities.find((e) => e.name === "widget");
+    const secretNote = widget?.fields.find((f) => f.name === "secretNote");
+
+    expect(secretNote).toEqual({
+      name: "secretNote",
+      type: "text",
+      labels: {},
+      pii: true,
+    });
+  });
+
+  test("select field carries its options, reference field carries the referenced entity", () => {
+    const registry = createRegistry([buildTestFeature()]);
+    const admin = buildAgentManifest(registry, { locale: "en", roles: ["admin"] });
+    const widget = admin.entities.find((e) => e.name === "widget");
+
+    expect(widget?.fields.find((f) => f.name === "status")).toMatchObject({
+      type: "select",
+      options: ["draft", "active"],
+      filterable: true,
+    });
+    expect(widget?.fields.find((f) => f.name === "ownerId")).toMatchObject({
+      type: "reference",
+      references: "user",
+    });
+    expect(widget?.fields.find((f) => f.name === "title")).toMatchObject({
+      type: "text",
+      searchable: true,
+    });
+  });
+
+  test("deterministic: manifest is independent of feature mount order", () => {
+    const featureA = buildTestFeature();
+    const featureB = buildOtherFeature();
+    const registryA = createRegistry([featureA, featureB]);
+    const registryB = createRegistry([featureB, featureA]);
+    const manifestA = buildAgentManifest(registryA, { locale: "en", roles: ["admin"] });
+    const manifestB = buildAgentManifest(registryB, { locale: "en", roles: ["admin"] });
+
+    expect(manifestA).toEqual(manifestB);
+
+    const qns = manifestA.handlers.map((h) => h.qn);
+    expect(qns).toEqual([...qns].sort());
+
+    const entityNames = manifestA.entities.map((e) => e.name);
+    expect(entityNames).toEqual([...entityNames].sort());
+  });
+});

package/src/agent-tools/__tests__/feature.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, spyOn, test } from "bun:test";
+import { defineFeature, validateBoot } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { AGENT_TOOLS_FEATURE_NAME, createAgentToolsFeature } from "../feature";
+
+async function noopWriteHandler() {
+  return { isSuccess: true as const, data: {} };
+}
+
+function undocumentedHandlersFeature() {
+  return defineFeature("doc-gap-demo", (r) => {
+    r.writeHandler("do-a", z.object({}), noopWriteHandler, { access: { openToAll: true } });
+    r.writeHandler("do-b", z.object({}), noopWriteHandler, { access: { openToAll: true } });
+    r.writeHandler("do-c", z.object({}), noopWriteHandler, { access: { openToAll: true } });
+  });
+}
+
+describe("createAgentToolsFeature", () => {
+  test("declares name, description, ui hints and exactly one boot check", () => {
+    const feature = createAgentToolsFeature();
+    expect(feature.name).toBe(AGENT_TOOLS_FEATURE_NAME);
+    expect(feature.description?.length ?? 0).toBeGreaterThan(0);
+    expect(feature.uiHints?.displayLabel).toBeTruthy();
+    expect(feature.bootChecks).toHaveLength(1);
+  });
+
+  test("boot check WARNS on undocumented handlers instead of failing the boot", () => {
+    const warn = spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      expect(() =>
+        validateBoot([createAgentToolsFeature(), undocumentedHandlersFeature()]),
+      ).not.toThrow();
+      expect(warn).toHaveBeenCalled();
+      const loggedLines = warn.mock.calls.flat().join("\n");
+      expect(loggedLines).toContain("doc-gap-demo:write:do-a");
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  test("boot check stays silent for a fully-described registry", () => {
+    const describedFeature = defineFeature("doc-clean-demo", (r) => {
+      r.writeHandler("do-a", z.object({}), noopWriteHandler, {
+        access: { openToAll: true },
+        description: "Does A.",
+      });
+    });
+
+    const warn = spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      expect(() => validateBoot([createAgentToolsFeature(), describedFeature])).not.toThrow();
+      expect(warn).not.toHaveBeenCalled();
+    } finally {
+      warn.mockRestore();
+    }
+  });
+});

package/src/agent-tools/agent-doc-lint.ts

@@ -0,0 +1,122 @@
+import type {
+  FeatureDefinition,
+  QueryHandlerDef,
+  WriteHandlerDef,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { QnTypes, qn, resolveAgentExposure, toKebab } from "@cosmicdrift/kumiko-framework/engine";
+
+export const AgentDocGapKinds = {
+  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;
+}
+
+function handlerDocGaps(
+  feature: FeatureDefinition,
+  handlers: Readonly<Record<string, WriteHandlerDef | QueryHandlerDef>>,
+  handlerQnType: typeof QnTypes.write | typeof QnTypes.query,
+  handlerNoun: string,
+): readonly AgentDocGap[] {
+  const gaps: AgentDocGap[] = [];
+  for (const [name, def] of Object.entries(handlers)) {
+    if (def.description !== undefined || def.agent?.expose === false) continue;
+    gaps.push({
+      qn: qn(toKebab(feature.name), handlerQnType, toKebab(name)),
+      feature: feature.name,
+      kind: AgentDocGapKinds.handlerWithoutDescription,
+      message: `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) 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.",
+    });
+  }
+  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/src/agent-tools/agent-manifest.ts

@@ -0,0 +1,329 @@
+import type {
+  AccessRule,
+  EntityDefinition,
+  FeatureDefinition,
+  FieldDefinition,
+  NavDefinition,
+  QueryHandlerDef,
+  ScreenDefinition,
+  TranslationKeys,
+  WorkspaceDefinition,
+  WriteHandlerDef,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { hasAccess, resolveAgentExposure } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import type {
+  AgentManifest,
+  AgentManifestEntity,
+  AgentManifestFeature,
+  AgentManifestField,
+  AgentManifestHandler,
+  AgentManifestNav,
+  AgentManifestOptions,
+  AgentManifestScreen,
+  AgentManifestWorkspace,
+  RegistryManifestView,
+} from "./types";
+
+/** Translation keys carry a feature prefix the manifest can't reconstruct
+ *  (`showcase:entity:item:field:title`), so match on the suffix instead. */
+function labelsForSuffix(
+  translations: TranslationKeys,
+  suffix: string,
+): Readonly<Record<string, string>> {
+  for (const [key, labels] of Object.entries(translations)) {
+    if (key === suffix || key.endsWith(suffix)) return labels;
+  }
+  return {};
+}
+
+/** 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;
+}
+
+function buildHandlerEntry(
+  qn: string,
+  kind: "query" | "write",
+  def: QueryHandlerDef | WriteHandlerDef,
+  roles: readonly string[],
+  getHandlerEntity: (qualifiedHandler: string) => string | undefined,
+): AgentManifestHandler | 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 = z.toJSONSchema(def.schema, { io: "input" }) as Readonly<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,
+): readonly AgentManifestHandler[] {
+  const result: AgentManifestHandler[] = [];
+  for (const [qn, def] of queryHandlers) {
+    const entry = buildHandlerEntry(qn, "query", def, roles, getHandlerEntity);
+    if (entry) result.push(entry);
+  }
+  for (const [qn, def] of writeHandlers) {
+    const entry = buildHandlerEntry(qn, "write", def, roles, getHandlerEntity);
+    if (entry) result.push(entry);
+  }
+  return result;
+}
+
+function buildNavs(
+  navs: ReadonlyMap<string, NavDefinition>,
+  workspaces: ReadonlyMap<string, WorkspaceDefinition>,
+  translations: TranslationKeys,
+  roles: readonly string[],
+): readonly AgentManifestNav[] {
+  const result: AgentManifestNav[] = [];
+  for (const [, nav] of navs) {
+    if (!uiVisible(nav.access, roles)) 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: translations[nav.label] ?? {},
+      ...(nav.screen !== undefined && { screen: nav.screen }),
+      ...(nav.parent !== undefined && { parent: nav.parent }),
+      workspaces: visibleWorkspaces,
+    });
+  }
+  return result;
+}
+
+function lastSegment(qualifiedId: string): string {
+  const idx = qualifiedId.lastIndexOf(":");
+  return idx === -1 ? qualifiedId : qualifiedId.slice(idx + 1);
+}
+
+function buildScreens(
+  screens: ReadonlyMap<string, ScreenDefinition>,
+  navs: ReadonlyMap<string, NavDefinition>,
+  workspaces: ReadonlyMap<string, WorkspaceDefinition>,
+  translations: TranslationKeys,
+  roles: readonly string[],
+): readonly AgentManifestScreen[] {
+  const allNavs = [...navs.values()];
+  const result: AgentManifestScreen[] = [];
+
+  for (const [, screen] of screens) {
+    const matchingNavs = allNavs.filter((nav) => nav.screen === screen.id);
+    const accessibleNavs = matchingNavs.filter((nav) => 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 !== undefined && { description: screen.description }),
+      ...("entity" in screen && screen.entity !== undefined && { entity: screen.entity }),
+      // A detail screen takes the row id; everything else is parameterless.
+      params: screen.detailFor !== undefined ? ["id"] : [],
+      workspaces: screenWorkspaces,
+    });
+  }
+  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: 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;
+
+  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),
+  );
+  const navs = buildNavs(navMap, workspaceMap, translations, roles);
+  const screens = buildScreens(registry.getAllScreens(), navMap, workspaceMap, translations, roles);
+  const workspaces = buildWorkspaces(workspaceMap, translations, roles);
+
+  return {
+    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/src/agent-tools/feature.ts

@@ -0,0 +1,36 @@
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { findAgentDocGaps, formatAgentDocGap } from "./agent-doc-lint";
+
+export const AGENT_TOOLS_FEATURE_NAME = "agent-tools";
+
+export function createAgentToolsFeature(): FeatureDefinition {
+  return defineFeature(AGENT_TOOLS_FEATURE_NAME, (r) => {
+    r.describe(
+      "Builds a tool catalog and an agent manifest from the mounted registry so an LLM agent can call handlers and understand the app's shape. A handler, custom screen, or entity without a `description` stays invisible to the agent by construction (see `resolveAgentExposure`) — this feature surfaces those gaps at boot and via `kumiko agent lint` so an app author notices before an agent silently can't see a feature.",
+    );
+    r.uiHints({
+      displayLabel: "AI Agent Tools",
+      category: "ai",
+      recommended: false,
+    });
+
+    // Warns instead of throwing: undocumented handlers/screens/entities are a
+    // usability gap for the agent, not an invalid app — failing the boot here
+    // would turn every incrementally-documented app into an outage.
+    r.bootCheck(({ features }) => {
+      const gaps = findAgentDocGaps(features);
+      if (gaps.length === 0) {
+        // skip: no documentation gaps, nothing to warn about
+        return;
+      }
+      // biome-ignore lint/suspicious/noConsole: operator-visibility at boot for agent-doc gaps
+      console.warn(
+        `[agent-tools] ${gaps.length} handler/screen/entity gap(s) invisible to the AI agent — run \`kumiko agent lint\` for details:`,
+      );
+      for (const gap of gaps) {
+        // biome-ignore lint/suspicious/noConsole: operator-visibility at boot for agent-doc gaps
+        console.warn(`  ${formatAgentDocGap(gap)}`);
+      }
+    });
+  });
+}

package/src/agent-tools/index.ts

@@ -1,7 +1,21 @@
+export type { AgentDocGap, AgentDocGapKind } from "./agent-doc-lint";
+export { AgentDocGapKinds, findAgentDocGaps, formatAgentDocGap } from "./agent-doc-lint";
+export { buildAgentManifest } from "./agent-manifest";
+export { AGENT_TOOLS_FEATURE_NAME, createAgentToolsFeature } from "./feature";
 export { buildToolCatalog } from "./tool-catalog";
 export type { ToolCallResult, ToolDispatcher } from "./tool-dispatch";
 export { dispatchToolCall } from "./tool-dispatch";
 export type {
+  AgentManifest,
+  AgentManifestEntity,
+  AgentManifestFeature,
+  AgentManifestField,
+  AgentManifestHandler,
+  AgentManifestNav,
+  AgentManifestOptions,
+  AgentManifestScreen,
+  AgentManifestWorkspace,
+  RegistryManifestView,
   RegistrySearchView,
   ToolCatalog,
   ToolDefinition,

package/src/agent-tools/types.ts

@@ -1,4 +1,14 @@
-import type { EntityDefinition, QueryHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import type {
+  AgentRisk,
+  EntityDefinition,
+  FeatureDefinition,
+  NavDefinition,
+  QueryHandlerDef,
+  ScreenDefinition,
+  TranslationKeys,
+  WorkspaceDefinition,
+  WriteHandlerDef,
+} from "@cosmicdrift/kumiko-framework/engine";
 
 /** Mirrors `ToolDefinition` in `@cosmicdriftgamestudio/kumiko-ai-foundation` (providers/types.ts)
  *  field-for-field so a generated catalog needs no translation layer at the call site. Kept as
@@ -36,3 +46,104 @@ export type ToolCatalog = {
   readonly tools: readonly ToolDefinition[];
   readonly dispatchTable: ReadonlyMap<string, ToolDispatchDescriptor>;
 };
+
+// --- agent manifest ---
+
+export type AgentManifestOptions = {
+  readonly locale: string;
+  readonly roles: readonly string[];
+  /** Tenant currency — the registry knows nothing about tenants, so the
+   *  caller passes it through into the manifest's tenant-settings block. */
+  readonly currency?: string;
+};
+
+export type AgentManifestField = {
+  readonly name: string;
+  readonly type: string;
+  /** Label per app locale, keyed by locale code. */
+  readonly labels: Readonly<Record<string, string>>;
+  readonly description?: string;
+  readonly options?: readonly string[];
+  /** Entity a `reference` field points at. */
+  readonly references?: string;
+  readonly searchable?: true;
+  readonly filterable?: true;
+  /** Marks the field as personal data. Never carries a value — the manifest
+   *  is schema, not rows. */
+  readonly pii?: true;
+};
+
+export type AgentManifestEntity = {
+  readonly name: string;
+  readonly labels: Readonly<Record<string, string>>;
+  readonly description?: string;
+  readonly fields: readonly AgentManifestField[];
+};
+
+export type AgentManifestHandler = {
+  readonly qn: string;
+  readonly kind: "query" | "write";
+  readonly description: string;
+  readonly risk: AgentRisk;
+  readonly inputSchema: Readonly<Record<string, unknown>>;
+  readonly entity?: string;
+};
+
+export type AgentManifestScreen = {
+  readonly id: string;
+  readonly type: string;
+  readonly titles: Readonly<Record<string, string>>;
+  readonly description?: string;
+  readonly entity?: string;
+  readonly params: readonly string[];
+  readonly workspaces: readonly string[];
+};
+
+export type AgentManifestNav = {
+  readonly id: string;
+  readonly labels: Readonly<Record<string, string>>;
+  readonly screen?: string;
+  readonly parent?: string;
+  readonly workspaces: readonly string[];
+};
+
+export type AgentManifestWorkspace = {
+  readonly id: string;
+  readonly labels: Readonly<Record<string, string>>;
+  readonly default?: true;
+};
+
+export type AgentManifestFeature = {
+  readonly name: string;
+  readonly description?: string;
+  readonly displayLabel?: string;
+};
+
+export type AgentManifest = {
+  readonly features: readonly AgentManifestFeature[];
+  readonly entities: readonly AgentManifestEntity[];
+  readonly handlers: readonly AgentManifestHandler[];
+  readonly screens: readonly AgentManifestScreen[];
+  readonly navs: readonly AgentManifestNav[];
+  readonly workspaces: readonly AgentManifestWorkspace[];
+  readonly tenantSettings: {
+    readonly locale: string;
+    readonly currency?: string;
+  };
+};
+
+/** Narrow view of `Registry` for manifest generation — same rationale as
+ *  `RegistrySearchView`: tests build a plain object instead of a full
+ *  Registry; a real `createRegistry(...)` result is structurally assignable. */
+export type RegistryManifestView = {
+  readonly features: ReadonlyMap<string, FeatureDefinition>;
+  getAllEntities(): ReadonlyMap<string, EntityDefinition>;
+  getAllQueryHandlers(): ReadonlyMap<string, QueryHandlerDef>;
+  getAllWriteHandlers(): ReadonlyMap<string, WriteHandlerDef>;
+  getHandlerEntity(qualifiedHandler: string): string | undefined;
+  getSearchableFields(entityName: string): readonly string[];
+  getAllTranslations(): TranslationKeys;
+  getAllScreens(): ReadonlyMap<string, ScreenDefinition>;
+  getAllNavs(): ReadonlyMap<string, NavDefinition>;
+  getAllWorkspaces(): ReadonlyMap<string, WorkspaceDefinition>;
+};