@cosmicdrift/kumiko-bundled-features 0.321.0 → 0.322.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.321.0",
+  "version": "0.322.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>",
@@ -134,12 +134,12 @@
     "./workflow-runner": "./src/workflow-runner/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.321.0",
-    "@cosmicdrift/kumiko-framework": "0.321.0",
-    "@cosmicdrift/kumiko-headless": "0.321.0",
-    "@cosmicdrift/kumiko-renderer": "0.321.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.321.0",
-    "@cosmicdrift/kumiko-types": "0.321.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.322.0",
+    "@cosmicdrift/kumiko-framework": "0.322.0",
+    "@cosmicdrift/kumiko-headless": "0.322.0",
+    "@cosmicdrift/kumiko-renderer": "0.322.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.322.0",
+    "@cosmicdrift/kumiko-types": "0.322.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -168,8 +168,8 @@
   ],
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
-    "@cosmicdrift/kumiko-locale-de": "0.321.0",
-    "@cosmicdrift/kumiko-locale-es": "0.321.0",
+    "@cosmicdrift/kumiko-locale-de": "0.322.0",
+    "@cosmicdrift/kumiko-locale-es": "0.322.0",
     "jsqr": "^1.4.0"
   }
 }

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

@@ -8,7 +8,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { buildAgentManifest } from "../agent-manifest";
-import { buildToolCatalog, toolNameForQn } from "../tool-catalog";
+import { buildToolCatalog, OPEN_FORM_TOOL_NAME, toolNameForQn } from "../tool-catalog";
 import type { AgentManifest, AgentToolMode, RegistrySearchView } from "../types";
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -440,6 +440,21 @@ describe("buildToolCatalog — built-in client tool names vs. a colliding handle
   });
 });
 
+describe("buildToolCatalog — tools/dispatchTable bijection", () => {
+  test("every tool name has exactly one dispatchTable entry, and vice versa, with no duplicates", () => {
+    const catalog = buildCatalog(ADMIN);
+    const names = catalog.tools.map((t) => t.name);
+    expect(names.length).toBeGreaterThan(0);
+    expect(new Set(names).size).toBe(names.length);
+    // open_form is the one deliberate exception: dispatch-only, claimed via
+    // claimDispatchName so the approval layer can trigger it, but never
+    // listed for the model to call directly (see addClientTools).
+    const dispatchNamesForModel = new Set(catalog.dispatchTable.keys());
+    dispatchNamesForModel.delete(OPEN_FORM_TOOL_NAME);
+    expect(dispatchNamesForModel).toEqual(new Set(names));
+  });
+});
+
 describe("toolNameForQn", () => {
   test("drops the verb segment, joins with underscores, sanitizes non-identifier characters", () => {
     expect(toolNameForQn("agent-tools-test-vendor:write:vendor:approve")).toBe(

package/src/agent-tools/__tests__/tool-dispatch.integration.test.ts

@@ -8,15 +8,21 @@
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
-import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createEntity,
+  createEntityExecutor,
+  createTextField,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
 import {
   createTestUser,
   setupTestStack,
   type TestStack,
   unsafeCreateEntityTable,
 } from "@cosmicdrift/kumiko-framework/stack";
+import * as z from "zod";
 import { buildAgentManifest } from "../agent-manifest";
-import { buildToolCatalog } from "../tool-catalog";
+import { buildToolCatalog, toolNameForQn } from "../tool-catalog";
 import { dispatchToolCall } from "../tool-dispatch";
 
 const vendorEntity = createEntity({
@@ -47,11 +53,92 @@ const vendorFeature = defineFeature("agent-tools-test-vendor", (r) => {
 
 const VENDOR_CREATE_QN = "agent-tools-test-vendor:write:vendor:create";
 
+// No softDelete — forget-gizmo-high performs a hard, irreversible purge and
+// therefore must resolve agent.risk "high" to pass the executor gate.
+const gizmoEntity = createEntity({
+  table: "agent_tools_test_gizmos",
+  fields: {
+    label: createTextField({ personal: false, reason: "test_fixture", required: true }),
+  },
+});
+const { executor: gizmoExecutor } = createEntityExecutor("gizmo", gizmoEntity);
+
+const GIZMO_CREATE_QN = "agent-tools-test-gizmo:write:gizmo:create";
+const GIZMO_FORGET_HIGH_QN = "agent-tools-test-gizmo:write:forget-gizmo-high";
+const GIZMO_DELEGATE_FORGET_MID_QN = "agent-tools-test-gizmo:write:delegate-forget-gizmo-mid";
+
+const gizmoFeature = defineFeature("agent-tools-test-gizmo", (r) => {
+  r.entity("gizmo", gizmoEntity);
+
+  r.writeHandler(
+    "gizmo:create",
+    z.object({ label: z.string() }),
+    async (event, ctx) => gizmoExecutor.create(event.payload, event.user, ctx.db),
+    { access: { roles: ["Admin"] } },
+  );
+
+  r.writeHandler(
+    "forget-gizmo-high",
+    z.object({ id: z.uuid() }),
+    async (event, ctx) => gizmoExecutor.forget({ id: event.payload.id }, event.user, ctx.db),
+    {
+      access: { roles: ["Admin"] },
+      description: "Permanently forget a gizmo (GDPR erasure).",
+      agent: { risk: "high" },
+    },
+  );
+
+  r.writeHandler(
+    "delegate-forget-gizmo-mid",
+    z.object({ id: z.uuid() }),
+    async (event, ctx) =>
+      ctx.write("agent-tools-test-gizmo:write:forget-gizmo-high", { id: event.payload.id }),
+    {
+      access: { roles: ["Admin"] },
+      description: "Delegates to forget-gizmo-high via ctx.write.",
+    },
+  );
+
+  // Simulates the enterprise "approve" write handler: an outer, mid-risk
+  // handler that itself runs the real dispatchToolCall path against a
+  // tool name given as input, the way an AI-agent turn approves a queued
+  // tool call.
+  r.writeHandler(
+    "approve",
+    z.object({ toolName: z.string(), id: z.string() }),
+    async (event) => {
+      const manifest = buildAgentManifest(stack.registry, {
+        locale: "en",
+        roles: event.user.roles,
+      });
+      const catalog = buildToolCatalog(stack.registry, manifest, { mode: "edit" });
+      // runId/toolCallId feed the write's idempotency key — must be unique
+      // per call, or a second approve() reuses the first call's cached
+      // WriteResult instead of actually re-dispatching the tool.
+      const result = await dispatchToolCall({
+        dispatcher: stack.dispatcher,
+        user: event.user,
+        toolName: event.payload.toolName,
+        input: { id: event.payload.id },
+        dispatchTable: catalog.dispatchTable,
+        runId: `run-approve:${event.payload.toolName}`,
+        toolCallId: `call-approve:${event.payload.id}`,
+      });
+      return {
+        isSuccess: true as const,
+        data: result.ok ? { ok: true } : { ok: false, error: result.error },
+      };
+    },
+    { access: { roles: ["Admin"] } },
+  );
+});
+
 let stack: TestStack;
 
 beforeAll(async () => {
-  stack = await setupTestStack({ features: [vendorFeature] });
+  stack = await setupTestStack({ features: [vendorFeature, gizmoFeature] });
   await unsafeCreateEntityTable(stack.db, vendorEntity);
+  await unsafeCreateEntityTable(stack.db, gizmoEntity, "gizmo");
 }, 20000);
 
 afterAll(async () => {
@@ -61,6 +148,7 @@ afterAll(async () => {
 beforeEach(async () => {
   await asRawClient(stack.db).unsafe("DELETE FROM kumiko_events");
   await asRawClient(stack.db).unsafe("DELETE FROM agent_tools_test_vendors");
+  await asRawClient(stack.db).unsafe("DELETE FROM agent_tools_test_gizmos");
 });
 
 const TENANT_B = "00000000-0000-4000-8000-0000000000bb";
@@ -119,3 +207,42 @@ describe("dispatchToolCall — real <entity>:list pipeline", () => {
     expect(result.error).toContain("access denied");
   });
 });
+
+describe("dispatchToolCall — the invoked tool is the entry handler, not the surrounding write handler", () => {
+  async function createGizmo(label: string): Promise<string> {
+    const { id } = await stack.http.writeOk<{ id: string }>(GIZMO_CREATE_QN, { label }, adminA);
+    return id;
+  }
+
+  async function gizmoRowExists(id: string): Promise<boolean> {
+    const rows = (await asRawClient(stack.db).unsafe(
+      "SELECT id FROM agent_tools_test_gizmos WHERE id = $1",
+      [id],
+    )) as readonly Record<string, unknown>[];
+    return rows.length > 0;
+  }
+
+  test("approve (mid) invoking a high-risk forget tool succeeds — the tool is the entry, not approve", async () => {
+    const id = await createGizmo("gone-after-tool-forget");
+    const { ok } = await stack.http.writeOk<{ ok: boolean }>(
+      "agent-tools-test-gizmo:write:approve",
+      { toolName: toolNameForQn(GIZMO_FORGET_HIGH_QN), id },
+      adminA,
+    );
+    expect(ok).toBe(true);
+    expect(await gizmoRowExists(id)).toBe(false);
+  });
+
+  test("approve (mid) invoking a mid-risk tool that delegates via ctx.write to the high forget handler is denied", async () => {
+    const id = await createGizmo("survives-delegated-forget");
+    const { ok, error } = await stack.http.writeOk<{ ok: boolean; error?: string }>(
+      "agent-tools-test-gizmo:write:approve",
+      { toolName: toolNameForQn(GIZMO_DELEGATE_FORGET_MID_QN), id },
+      adminA,
+    );
+    expect(ok).toBe(false);
+    expect(error).toContain(GIZMO_DELEGATE_FORGET_MID_QN);
+    expect(error).toContain("irreversible");
+    expect(await gizmoRowExists(id)).toBe(true);
+  });
+});

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

@@ -6,6 +6,7 @@ import type {
   NavDefinition,
   QueryHandlerDef,
   ScreenDefinition,
+  TranslationEntry,
   TranslationKeys,
   WorkspaceDefinition,
   WriteHandlerDef,
@@ -15,6 +16,7 @@ import {
   isAgentVisibleScreen,
   resolveAgentExposure,
 } from "@cosmicdrift/kumiko-framework/engine";
+import { translationValueOtherText } from "@cosmicdrift/kumiko-framework/ui-types";
 import * as z from "zod";
 import type {
   AgentManifest,
@@ -29,6 +31,14 @@ import type {
   RegistryManifestView,
 } from "./types";
 
+/** 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)]),
+  );
+}
+
 /** Translation keys carry a feature prefix the manifest can't reconstruct
  *  (`showcase:entity:item:field:title`), so match on the suffix instead. */
 function labelsForSuffix(
@@ -36,7 +46,7 @@ function labelsForSuffix(
   suffix: string,
 ): Readonly<Record<string, string>> {
   for (const [key, labels] of Object.entries(translations)) {
-    if (key === suffix || key.endsWith(suffix)) return labels;
+    if (key === suffix || key.endsWith(suffix)) return entryAsLabels(labels);
   }
   return {};
 }
@@ -226,7 +236,7 @@ function buildNavs(
 
     result.push({
       id: nav.id,
-      labels: translations[nav.label] ?? {},
+      labels: entryAsLabels(translations[nav.label] ?? {}),
       ...(nav.screen !== undefined && { screen: nav.screen }),
       ...(nav.parent !== undefined && { parent: nav.parent }),
       workspaces: visibleWorkspaces,
@@ -304,7 +314,7 @@ function buildWorkspaces(
     if (!uiVisible(workspace.access, roles)) continue;
     result.push({
       id: workspace.id,
-      labels: translations[workspace.label] ?? {},
+      labels: entryAsLabels(translations[workspace.label] ?? {}),
       ...(workspace.default === true && { default: true as const }),
     });
   }

package/src/agent-tools/tool-dispatch.ts

@@ -1,3 +1,4 @@
+import { runAsDirectCallEntry } from "@cosmicdrift/kumiko-framework/api";
 import type { SessionUser, WriteResult } from "@cosmicdrift/kumiko-framework/engine";
 import type { ToolDispatchDescriptor } from "./types";
 
@@ -355,18 +356,22 @@ export async function dispatchToolCall(request: ToolCallRequest): Promise<ToolCa
   }
 
   try {
-    switch (descriptor.kind) {
-      case "search":
-        return await dispatchSearch(descriptor, dispatcher, user, toolName, input);
-      case "findBy":
-        return await dispatchFindBy(descriptor, dispatcher, user, toolName, input);
-      case "client":
-        return dispatchClient(descriptor, input);
-      case "server":
-        return descriptor.op === "query"
-          ? await dispatchServerQuery(descriptor, dispatcher, user, input)
-          : await dispatchServerWrite(descriptor, dispatcher, user, input, runId, toolCallId);
-    }
+    // The invoked tool, not the surrounding turn/approve write handler, must
+    // be what the irreversible-operation gate sees as the entry handler.
+    return await runAsDirectCallEntry(async () => {
+      switch (descriptor.kind) {
+        case "search":
+          return await dispatchSearch(descriptor, dispatcher, user, toolName, input);
+        case "findBy":
+          return await dispatchFindBy(descriptor, dispatcher, user, toolName, input);
+        case "client":
+          return dispatchClient(descriptor, input);
+        case "server":
+          return descriptor.op === "query"
+            ? await dispatchServerQuery(descriptor, dispatcher, user, input)
+            : await dispatchServerWrite(descriptor, dispatcher, user, input, runId, toolCallId);
+      }
+    });
   } catch (err) {
     return { ok: false, error: err instanceof Error ? err.message : String(err) };
   }

package/src/crypto-shredding/handlers/forget-subject.write.ts

@@ -28,6 +28,7 @@ import {
   writeFailure,
 } from "@cosmicdrift/kumiko-framework/errors";
 import { append } from "@cosmicdrift/kumiko-framework/event-store";
+import { assertIrreversibleOperationAllowed } from "@cosmicdrift/kumiko-framework/pipeline";
 import { purgeSearchDocumentsForSubject } from "@cosmicdrift/kumiko-framework/search";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import * as z from "zod";
@@ -267,7 +268,7 @@ export const forgetSubjectWrite = defineWriteHandler({
     "Irreversibly crypto-shreds one user, tenant or record subject by erasing its encryption key, nulling its blind indexes, purging its search documents and closing the user's login, for supervisory-authority requests and operator recovery outside the automated Art. 17 cleanup pipeline.",
   // Erasing the subject key is irreversible: there is no undo, so an agent must
   // not be able to reach it at all.
-  agent: { expose: false },
+  agent: { expose: false, risk: "high" },
   escapeHatch: {
     reason:
       "denial audit append names the prober's own tenant stream on the outside-transaction db; " +
@@ -276,6 +277,7 @@ export const forgetSubjectWrite = defineWriteHandler({
       "lifecycle update and PAT revoke run on the SYSTEM user stream.",
   },
   handler: async (event, ctx) => {
+    assertIrreversibleOperationAllowed("forget-subject key erase");
     const kms = configuredPiiSubjectKms();
     if (!kms) {
       return writeFailure(

package/src/tenant/__tests__/members-facet-i18n.test.ts

@@ -6,6 +6,7 @@
 // so adding a facet option without translating it fails here rather than in
 // production.
 import { describe, expect, test } from "bun:test";
+import { translationValueOtherText } from "@cosmicdrift/kumiko-framework/ui-types";
 import { localeDeBundle } from "@cosmicdrift/kumiko-locale-de";
 import { localeEsBundle } from "@cosmicdrift/kumiko-locale-es";
 import { MEMBERS_SCREEN_ID } from "../constants";
@@ -67,7 +68,7 @@ describe("members status filter labels are localized in every shipped locale (fw
       const label = translations[key]?.["en"];
       expect(label).toBeString();
       expect(label).not.toBe(key);
-      expect((label ?? "").trim()).not.toBe("");
+      expect((label === undefined ? "" : translationValueOtherText(label)).trim()).not.toBe("");
     }
   });
 
@@ -77,7 +78,7 @@ describe("members status filter labels are localized in every shipped locale (fw
       const label = translations[key]?.["en"];
       expect(label).toBeString();
       expect(label).not.toBe(key);
-      expect((label ?? "").trim()).not.toBe("");
+      expect((label === undefined ? "" : translationValueOtherText(label)).trim()).not.toBe("");
     }
   });
 

package/src/tenant-settings/__tests__/settings-hub-i18n.test.ts

@@ -14,20 +14,16 @@
 import { describe, expect, test } from "bun:test";
 import { createConfigFeature } from "@cosmicdrift/kumiko-bundled-features/config";
 import { buildConfigFeatureSchema, createRegistry } from "@cosmicdrift/kumiko-framework/engine";
+import { translationValueOtherText } from "@cosmicdrift/kumiko-framework/ui-types";
 import { localeDeBundle } from "@cosmicdrift/kumiko-locale-de";
 import { localeEsBundle } from "@cosmicdrift/kumiko-locale-es";
-import { translationsByLocaleFromKeys } from "@cosmicdrift/kumiko-renderer";
+import { type TranslationsByKey, translationsByLocaleFromKeys } from "@cosmicdrift/kumiko-renderer";
 import { createTenantSettingsFeature } from "../feature";
 
-function translate(
-  translations: Readonly<Record<string, Readonly<Record<string, string>> | undefined>>,
-  key: string,
-  locale = "en",
-): string {
-  const byLocale = translationsByLocaleFromKeys(
-    translations as Record<string, Readonly<Record<string, string>>>,
-  );
-  return byLocale[locale]?.[key] ?? key;
+function translate(translations: TranslationsByKey, key: string, locale = "en"): string {
+  const byLocale = translationsByLocaleFromKeys(translations);
+  const value = byLocale[locale]?.[key];
+  return value === undefined ? key : translationValueOtherText(value);
 }
 
 function settingsHubLabelKeys(): readonly string[] {

package/src/user-data-rights/handlers/run-forget-cleanup.write.ts

@@ -31,7 +31,9 @@ export function createRunForgetCleanupHandler(opts: RunForgetCleanupOptions = {}
     name: "run-forget-cleanup",
     schema: z.object({}),
     access: { roles: access.privileged },
-    agent: { expose: false },
+    // Cascades into per-user forget hooks that hard-purge (executor.forget)
+    // records without softDelete — an agent must never be able to trigger it.
+    agent: { expose: false, risk: "high" },
     escapeHatch: {
       reason: RUN_FORGET_CLEANUP_REASON,
     },