@cosmicdrift/kumiko-bundled-features 0.241.0 → 0.242.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.241.0",
+  "version": "0.242.0",
   "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.241.0",
-    "@cosmicdrift/kumiko-framework": "0.241.0",
-    "@cosmicdrift/kumiko-headless": "0.241.0",
-    "@cosmicdrift/kumiko-renderer": "0.241.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.241.0",
-    "@cosmicdrift/kumiko-types": "0.241.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.242.0",
+    "@cosmicdrift/kumiko-framework": "0.242.0",
+    "@cosmicdrift/kumiko-headless": "0.242.0",
+    "@cosmicdrift/kumiko-renderer": "0.242.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.242.0",
+    "@cosmicdrift/kumiko-types": "0.242.0",
     "@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.241.0",
-    "@cosmicdrift/kumiko-locale-es": "0.241.0"
+    "@cosmicdrift/kumiko-locale-de": "0.242.0",
+    "@cosmicdrift/kumiko-locale-es": "0.242.0"
   }
 }

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

@@ -128,6 +128,46 @@ describe("findAgentDocGaps", () => {
     expect(findAgentDocGaps([feature])).toHaveLength(0);
   });
 
+  test("R2: custom screen with agent.expose:false opt-out -> no gap", () => {
+    const feature = defineFeature("doc-gap-demo", (r) => {
+      r.screen({
+        id: "sysadmin-secrets",
+        type: "custom",
+        renderer: { react: "stub" },
+        agent: { expose: false },
+      });
+    });
+
+    expect(findAgentDocGaps([feature])).toHaveLength(0);
+  });
+
+  test("R2: custom screen with agent.expose:true but no description -> still a gap", () => {
+    const feature = defineFeature("doc-gap-demo", (r) => {
+      r.screen({
+        id: "widget-editor",
+        type: "custom",
+        renderer: { react: "stub" },
+        agent: { expose: true },
+      });
+    });
+
+    const gaps = findAgentDocGaps([feature]);
+    expect(gaps).toHaveLength(1);
+    expect(gaps[0]?.qn).toBe("doc-gap-demo:screen:widget-editor");
+    expect(gaps[0]?.kind).toBe(AgentDocGapKinds.customScreenWithoutDescription);
+  });
+
+  test("R2: the custom-screen gap message names both ways out", () => {
+    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(formatAgentDocGap(gaps[0]!)).toContain("agent: { expose: false }");
+    expect(formatAgentDocGap(gaps[0]!)).toContain("`description`");
+  });
+
   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." });

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

@@ -183,4 +183,40 @@ describe("buildAgentManifest", () => {
     const entityNames = manifestA.entities.map((e) => e.name);
     expect(entityNames).toEqual([...entityNames].sort());
   });
+
+  test("a nav pointing at an opted-out screen is dropped too, so the screen id never leaks via navs", () => {
+    const feature = defineFeature("nav-leak-test", (r) => {
+      r.screen({
+        id: "sysadmin-secrets",
+        type: "custom",
+        renderer: { react: "stub" },
+        description: "Webhook secrets.",
+        agent: { expose: false },
+      });
+      r.screen({
+        id: "public-board",
+        type: "custom",
+        renderer: { react: "stub" },
+        description: "Public board.",
+      });
+      r.nav({
+        id: "sysadmin-secrets",
+        label: "nav-leak-test:nav:sysadmin-secrets",
+        screen: "nav-leak-test:screen:sysadmin-secrets",
+      });
+      r.nav({
+        id: "public-board",
+        label: "nav-leak-test:nav:public-board",
+        screen: "nav-leak-test:screen:public-board",
+      });
+    });
+
+    const manifest = buildAgentManifest(createRegistry([feature]), {
+      locale: "en",
+      roles: ["admin"],
+    });
+
+    expect(manifest.navs.map((n) => n.screen)).toEqual(["nav-leak-test:screen:public-board"]);
+    expect(manifest.screens.map((s) => s.id)).toEqual(["nav-leak-test:screen:public-board"]);
+  });
 });

package/src/agent-tools/__tests__/tool-catalog.test.ts

@@ -303,6 +303,57 @@ describe("buildToolCatalog — client tools", () => {
     expect(descriptor.screenIds.has("catalog-test:screen:widget-approve-form")).toBe(true);
   });
 
+  test("a screen with agent.expose:false is absent from the navigate enum and from the manifest", () => {
+    const feature = defineFeature("exposure-test", (r) => {
+      r.screen({
+        id: "sysadmin-secrets",
+        type: "custom",
+        renderer: { react: "stub" },
+        description: "Webhook secrets.",
+        agent: { expose: false },
+      });
+      r.screen({
+        id: "public-board",
+        type: "custom",
+        renderer: { react: "stub" },
+        description: "Public board.",
+      });
+    });
+    const registry = createRegistry([feature]);
+    const manifest = buildAgentManifest(registry, { locale: "en", roles: ["Admin"] });
+    const catalog = buildToolCatalog(registry, manifest, { mode: "edit" });
+
+    expect(manifest.screens.map((s) => s.id)).toContain("exposure-test:screen:public-board");
+    expect(manifest.screens.map((s) => s.id)).not.toContain(
+      "exposure-test:screen:sysadmin-secrets",
+    );
+
+    const descriptor = catalog.dispatchTable.get("navigate");
+    if (descriptor?.kind !== "client" || descriptor.op !== "navigate")
+      throw new Error("wrong kind");
+    expect(descriptor.screenIds.has("exposure-test:screen:sysadmin-secrets")).toBe(false);
+    expect(descriptor.screenIds.has("exposure-test:screen:public-board")).toBe(true);
+
+    const navTool = catalog.tools.find((t) => t.name === "navigate");
+    const schema = navTool?.inputSchema ?? {};
+    const properties = isRecord(schema["properties"]) ? schema["properties"] : {};
+    const screenIdSchema = isRecord(properties["screenId"]) ? properties["screenId"] : {};
+    const enumValues = Array.isArray(screenIdSchema["enum"]) ? screenIdSchema["enum"] : [];
+    expect(enumValues).toContain("exposure-test:screen:public-board");
+    expect(enumValues).not.toContain("exposure-test:screen:sysadmin-secrets");
+  });
+
+  test("a screen without an agent slot stays in the navigate enum", () => {
+    const catalog = buildCatalog(ADMIN);
+    const descriptor = catalog.dispatchTable.get("navigate");
+    if (descriptor?.kind !== "client" || descriptor.op !== "navigate")
+      throw new Error("wrong kind");
+    // None of catalog-test's screens carry a description either — this is the
+    // regression guard against a screen without an `agent` slot silently
+    // fail-closing (the way a handler without a description would).
+    expect(descriptor.screenIds.has("catalog-test:screen:widget-detail")).toBe(true);
+  });
+
   test("open_form maps the actionForm handler and the entityEdit create/update handlers", () => {
     const catalog = buildCatalog(ADMIN);
     const descriptor = catalog.dispatchTable.get("open_form");

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

@@ -3,7 +3,13 @@ import type {
   QueryHandlerDef,
   WriteHandlerDef,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { QnTypes, qn, resolveAgentExposure, toKebab } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  isAgentVisibleScreen,
+  QnTypes,
+  qn,
+  resolveAgentExposure,
+  toKebab,
+} from "@cosmicdrift/kumiko-framework/engine";
 
 export const AgentDocGapKinds = {
   handlerWithoutDescription: "handler-without-description",
@@ -56,13 +62,18 @@ function handlerDocGaps(
 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;
+    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.",
+        "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;

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

@@ -10,7 +10,11 @@ import type {
   WorkspaceDefinition,
   WriteHandlerDef,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { hasAccess, resolveAgentExposure } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  hasAccess,
+  isAgentVisibleScreen,
+  resolveAgentExposure,
+} from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
 import type {
   AgentManifest,
@@ -204,10 +208,15 @@ function buildNavs(
   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;
@@ -239,6 +248,9 @@ function buildScreens(
   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) => uiVisible(nav.access, roles));
 
@@ -312,8 +324,9 @@ export function buildAgentManifest(
     roles,
     (qn) => registry.getHandlerEntity(qn),
   );
-  const navs = buildNavs(navMap, workspaceMap, translations, roles);
-  const screens = buildScreens(registry.getAllScreens(), navMap, workspaceMap, translations, roles);
+  const screenMap = registry.getAllScreens();
+  const navs = buildNavs(navMap, workspaceMap, translations, roles, screenMap);
+  const screens = buildScreens(screenMap, navMap, workspaceMap, translations, roles);
   const workspaces = buildWorkspaces(workspaceMap, translations, roles);
 
   return {

package/src/agent-tools/feature.ts

@@ -6,7 +6,7 @@ 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.",
+      "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 or entity without a `description` stays invisible to the agent by construction (see `resolveAgentExposure`), while a screen stays visible unless it opts out with `agent: { expose: false }` (see `isAgentVisibleScreen`) — this feature surfaces the resulting 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",