@cosmicdrift/kumiko-bundled-features 0.320.0 → 0.322.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.320.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.320.0",
-    "@cosmicdrift/kumiko-framework": "0.320.0",
-    "@cosmicdrift/kumiko-headless": "0.320.0",
-    "@cosmicdrift/kumiko-renderer": "0.320.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.320.0",
-    "@cosmicdrift/kumiko-types": "0.320.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.320.0",
-    "@cosmicdrift/kumiko-locale-es": "0.320.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/billing-foundation/__tests__/billing-plans.integration.test.ts

@@ -232,6 +232,7 @@ async function createSubscription(
     tier: string;
     providerSubscriptionId: string;
     providerCustomerId: string;
+    cancelAtIso: string | null;
   }> = {},
   onStack: TestStack = stack,
 ) {
@@ -247,6 +248,7 @@ async function createSubscription(
       status: overrides.status ?? SubscriptionStatuses.active,
       tier: overrides.tier ?? "starter",
       currentPeriodEndIso: "2026-06-01T00:00:00Z",
+      ...(overrides.cancelAtIso !== undefined && { cancelAtIso: overrides.cancelAtIso }),
       rawPayload: '{"raw":"payload"}',
     },
     admin,
@@ -503,6 +505,31 @@ describe("switch-plan", () => {
     expect(error.httpStatus).toBe(409);
   });
 
+  test("switching a subscription that is scheduled to cancel is a conflict, and the query offers unavailable instead of switch", async () => {
+    const admin = adminFor(7034);
+    await createSubscription(admin.tenantId, {
+      tier: "starter",
+      providerSubscriptionId: "sub_switch_7034",
+      cancelAtIso: "2026-07-01T00:00:00Z",
+    });
+
+    const result = (await stack.http.queryOk(
+      "billing-foundation:query:billing-plans",
+      {},
+      admin,
+    )) as { plans: Array<{ tier: string; action: string }> };
+    expect(result.plans.find((p) => p.tier === "pro")?.action).toBe("unavailable");
+
+    const error = await stack.http.writeErr(
+      SubscriptionFoundationHandlers.switchPlan,
+      { tier: "pro" },
+      admin,
+    );
+    expect(error.httpStatus).toBe(409);
+    expect(error.i18nKey).toBe("billing-foundation.errors.cancellationScheduled");
+    expect(switchCalls).toHaveLength(0);
+  });
+
   test("the provider rejecting the switch because two tiers share one Stripe product surfaces as a 422, not a 500", async () => {
     const admin = adminFor(7024);
     await createSubscription(admin.tenantId, {

package/src/billing-foundation/__tests__/checkout-core.test.ts

@@ -1,15 +1,18 @@
 import { describe, expect, test } from "bun:test";
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
 import { UnconfiguredError, UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
 // Aliased — an un-aliased `Temporal` would shadow the ambient global
 // `Temporal` TYPE `SubscriptionView.lastChangedAt` resolves against.
 import { Temporal as TemporalPolyfill } from "temporal-polyfill";
 import {
   assertRedirectOrigins,
+  isBillingEnabled,
   isNonEmptyStringArray,
   isOwnProviderCustomer,
   joinBaseUrl,
 } from "../checkout-core";
 import type { SubscriptionView } from "../get-subscription-for-tenant";
+import type { SubscriptionProviderPlugin } from "../types";
 
 function subscriptionView(overrides: Partial<SubscriptionView> = {}): SubscriptionView {
   return {
@@ -151,3 +154,35 @@ describe("isOwnProviderCustomer", () => {
     expect(isOwnProviderCustomer(subscriptionView(), "mock", "cus_own")).toBe(true);
   });
 });
+
+function fakeCtxWithProvider(
+  entries: ReadonlyArray<{ readonly entityName: string; readonly options: unknown }>,
+): HandlerContext {
+  return {
+    registry: {
+      getExtensionUsages: () => entries,
+    },
+  } as unknown as HandlerContext; // @cast-boundary test-fixture — only registry is exercised
+}
+
+describe("isBillingEnabled", () => {
+  test("false when no provider with that name is registered", async () => {
+    const ctx = fakeCtxWithProvider([]);
+    expect(await isBillingEnabled(ctx, "stripe")).toBe(false);
+  });
+
+  test("false when the registered plugin's own isBillingEnabled reports false", async () => {
+    const plugin: SubscriptionProviderPlugin = {
+      verifyAndParseWebhook: async () => null,
+      isBillingEnabled: async () => false,
+    };
+    const ctx = fakeCtxWithProvider([{ entityName: "stripe", options: plugin }]);
+    expect(await isBillingEnabled(ctx, "stripe")).toBe(false);
+  });
+
+  test("true when the registered plugin has no isBillingEnabled (defaults to enabled)", async () => {
+    const plugin: SubscriptionProviderPlugin = { verifyAndParseWebhook: async () => null };
+    const ctx = fakeCtxWithProvider([{ entityName: "stripe", options: plugin }]);
+    expect(await isBillingEnabled(ctx, "stripe")).toBe(true);
+  });
+});