@cosmicdrift/kumiko-bundled-features 0.155.0 → 0.156.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.155.0",
+  "version": "0.156.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>",
@@ -18,6 +18,7 @@
     "runtime": "runtime"
   },
   "exports": {
+    "./agent-tools": "./src/agent-tools/index.ts",
     "./audit": "./src/audit/index.ts",
     "./audit/web": "./src/audit/web/index.ts",
     "./admin-shell": "./src/admin-shell/index.ts",
@@ -115,11 +116,11 @@
     "./step-dispatcher": "./src/step-dispatcher/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.155.0",
-    "@cosmicdrift/kumiko-framework": "0.155.0",
-    "@cosmicdrift/kumiko-headless": "0.155.0",
-    "@cosmicdrift/kumiko-renderer": "0.155.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.155.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.156.0",
+    "@cosmicdrift/kumiko-framework": "0.156.0",
+    "@cosmicdrift/kumiko-headless": "0.156.0",
+    "@cosmicdrift/kumiko-renderer": "0.156.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.156.0",
     "@mollie/api-client": "^4.5.0",
     "imapflow": "^1.3.3",
     "mailparser": "^3.9.8",

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

@@ -0,0 +1,179 @@
+import { describe, expect, test } from "bun:test";
+import {
+  createEntity,
+  createSelectField,
+  createTextField,
+} from "@cosmicdrift/kumiko-framework/engine";
+import type {
+  EntityDefinition,
+  QueryHandlerDef,
+  ReferenceFieldDef,
+} from "@cosmicdrift/kumiko-framework/engine/types";
+import { buildToolCatalog } from "../tool-catalog";
+import type { RegistrySearchView } from "../types";
+
+const vendorEntity = createEntity({
+  fields: {
+    name: createTextField({ searchable: true, filterable: true }),
+    iban: createTextField({ filterable: true }),
+    notes: createTextField(),
+    status: createSelectField({ options: ["active", "archived"] as const, filterable: true }),
+  },
+});
+
+const invoiceEntity = createEntity({
+  fields: {
+    vendorId: { type: "reference", entity: "vendor", filterable: true } satisfies ReferenceFieldDef,
+    description: createTextField({ searchable: true }),
+  },
+});
+
+const FAKE_HANDLER = {} as QueryHandlerDef;
+
+type EntityFixture = {
+  readonly qn: string;
+  readonly entityName: string;
+  readonly entity: EntityDefinition;
+  readonly searchableFields: readonly string[];
+};
+
+/** Handler-first fake: one entry per MOUNTED `:list` handler, mirroring what
+ *  `registry.getAllQueryHandlers()` + `getHandlerEntity()` would return for a real app. There is
+ *  no `getAllEntities()` here on purpose — an entity with no fixture is exactly "no list handler
+ *  mounted", the case `buildToolCatalog` must skip. */
+function fakeRegistry(fixtures: readonly EntityFixture[]): RegistrySearchView {
+  const byQn = new Map(fixtures.map((f) => [f.qn, FAKE_HANDLER]));
+  const entityByQn = new Map(fixtures.map((f) => [f.qn, f.entityName]));
+  const entityByName = new Map(fixtures.map((f) => [f.entityName, f.entity]));
+  const searchableByName = new Map(fixtures.map((f) => [f.entityName, f.searchableFields]));
+
+  return {
+    getAllQueryHandlers: () => byQn,
+    getHandlerEntity: (qn) => entityByQn.get(qn),
+    getEntity: (entityName) => entityByName.get(entityName),
+    getSearchableFields: (entityName) => searchableByName.get(entityName) ?? [],
+  };
+}
+
+function vendorFixture(searchableFields: readonly string[] = []): EntityFixture {
+  return {
+    qn: "vendor-feature:query:vendor:list",
+    entityName: "vendor",
+    entity: vendorEntity,
+    searchableFields,
+  };
+}
+
+function invoiceFixture(searchableFields: readonly string[] = []): EntityFixture {
+  return {
+    qn: "invoice-feature:query:invoice:list",
+    entityName: "invoice",
+    entity: invoiceEntity,
+    searchableFields,
+  };
+}
+
+describe("buildToolCatalog", () => {
+  test("generates a search_<entity> tool only when searchable fields exist", () => {
+    const registry = fakeRegistry([vendorFixture(["name"]), invoiceFixture(["description"])]);
+    const catalog = buildToolCatalog(registry);
+    const names = catalog.tools.map((t) => t.name);
+
+    expect(names).toContain("search_vendor");
+    expect(names).toContain("search_invoice");
+  });
+
+  test("skips search_<entity> when the entity has no searchable fields", () => {
+    const registry = fakeRegistry([vendorFixture([])]);
+    const catalog = buildToolCatalog(registry);
+    expect(catalog.tools.map((t) => t.name)).not.toContain("search_vendor");
+  });
+
+  test("skips an entity entirely when it has no mounted :list handler", () => {
+    // getHandlerEntity resolves it, but the qn doesn't end in ":<entity>:list" — e.g. a
+    // :detail handler picked up by a naive "any handler mentioning this entity" scan.
+    const registry: RegistrySearchView = {
+      getAllQueryHandlers: () => new Map([["vendor-feature:query:vendor:detail", FAKE_HANDLER]]),
+      getHandlerEntity: () => "vendor",
+      getEntity: () => vendorEntity,
+      getSearchableFields: () => ["name"],
+    };
+    const catalog = buildToolCatalog(registry);
+    expect(catalog.tools).toEqual([]);
+  });
+
+  test("generates one find_<entity>_by_<field> tool per filterable field", () => {
+    const registry = fakeRegistry([vendorFixture(["name"])]);
+    const catalog = buildToolCatalog(registry);
+    const names = catalog.tools.map((t) => t.name);
+
+    expect(names).toContain("find_vendor_by_name");
+    expect(names).toContain("find_vendor_by_iban");
+    expect(names).toContain("find_vendor_by_status");
+    expect(names).not.toContain("find_vendor_by_notes"); // not filterable
+  });
+
+  test("select field becomes a string schema with an enum of its options", () => {
+    const registry = fakeRegistry([vendorFixture()]);
+    const catalog = buildToolCatalog(registry);
+    const statusTool = catalog.tools.find((t) => t.name === "find_vendor_by_status");
+
+    expect(statusTool?.inputSchema).toEqual({
+      type: "object",
+      properties: { status: { type: "string", enum: ["active", "archived"] } },
+      required: ["status"],
+      additionalProperties: false,
+    });
+  });
+
+  test("reference field becomes a string schema describing the referenced entity", () => {
+    const registry = fakeRegistry([invoiceFixture()]);
+    const catalog = buildToolCatalog(registry);
+    const vendorIdTool = catalog.tools.find((t) => t.name === "find_invoice_by_vendorId");
+
+    expect(vendorIdTool?.inputSchema).toEqual({
+      type: "object",
+      properties: {
+        vendorId: { type: "string", description: 'ID referencing "vendor"' },
+      },
+      required: ["vendorId"],
+      additionalProperties: false,
+    });
+  });
+
+  test("search tool description lists every searchable field", () => {
+    const registry = fakeRegistry([vendorFixture(["name", "iban"])]);
+    const catalog = buildToolCatalog(registry);
+    const searchTool = catalog.tools.find((t) => t.name === "search_vendor");
+
+    expect(searchTool?.description).toContain("name, iban");
+  });
+
+  test("empty registry produces an empty catalog", () => {
+    const registry = fakeRegistry([]);
+    const catalog = buildToolCatalog(registry);
+    expect(catalog.tools).toEqual([]);
+    expect(catalog.dispatchTable.size).toBe(0);
+  });
+
+  test("dispatchTable maps search_<entity> to a search descriptor carrying the real qn", () => {
+    const registry = fakeRegistry([vendorFixture(["name"])]);
+    const catalog = buildToolCatalog(registry);
+    expect(catalog.dispatchTable.get("search_vendor")).toEqual({
+      kind: "search",
+      entityName: "vendor",
+      qn: "vendor-feature:query:vendor:list",
+    });
+  });
+
+  test("dispatchTable maps find_<entity>_by_<field> to a findBy descriptor carrying the real qn", () => {
+    const registry = fakeRegistry([vendorFixture()]);
+    const catalog = buildToolCatalog(registry);
+    expect(catalog.dispatchTable.get("find_vendor_by_iban")).toEqual({
+      kind: "findBy",
+      entityName: "vendor",
+      fieldName: "iban",
+      qn: "vendor-feature:query:vendor:list",
+    });
+  });
+});

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

@@ -0,0 +1,100 @@
+// Proves the property the unit tests can't: dispatchToolCall runs through the
+// REAL <entity>:list handler + permission pipeline, not a fake. Two things a
+// hand-rolled recording dispatcher would happily hide:
+//   - tenant isolation: tenant A's find_by_iban call must never surface
+//     tenant B's row, even when both tenants have the exact same IBAN value.
+//   - cap enforcement: a caller without the list handler's required role
+//     gets denied, not an empty-but-"ok" result.
+
+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 { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { buildToolCatalog } from "../tool-catalog";
+import { dispatchToolCall } from "../tool-dispatch";
+
+const vendorEntity = createEntity({
+  table: "agent_tools_test_vendors",
+  fields: {
+    name: createTextField({ required: true, searchable: true, filterable: true }),
+    iban: createTextField({ required: true, filterable: true }),
+  },
+});
+
+const vendorFeature = defineFeature("agent-tools-test-vendor", (r) => {
+  r.crud("vendor", vendorEntity, {
+    write: { access: { roles: ["Admin"] } },
+    read: { access: { roles: ["Reader"] } },
+  });
+});
+
+const VENDOR_CREATE_QN = "agent-tools-test-vendor:write:vendor:create";
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [vendorFeature] });
+  await unsafeCreateEntityTable(stack.db, vendorEntity);
+  await createEventsTable(stack.db);
+}, 20000);
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(stack.db).unsafe("DELETE FROM kumiko_events");
+  await asRawClient(stack.db).unsafe("DELETE FROM agent_tools_test_vendors");
+});
+
+const TENANT_B = "00000000-0000-4000-8000-0000000000bb";
+
+const adminA = createTestUser({ roles: ["Admin"] });
+const adminB = createTestUser({ roles: ["Admin"], tenantId: TENANT_B });
+const readerA = createTestUser({ roles: ["Reader"], id: adminA.id, tenantId: adminA.tenantId });
+const noRoleA = createTestUser({ roles: [], id: adminA.id, tenantId: adminA.tenantId });
+
+describe("dispatchToolCall — real <entity>:list pipeline", () => {
+  test("find_vendor_by_iban never leaks another tenant's row, even on an identical IBAN", async () => {
+    await stack.dispatcher.write(VENDOR_CREATE_QN, { name: "Acme A", iban: "DE-SAME" }, adminA);
+    await stack.dispatcher.write(VENDOR_CREATE_QN, { name: "Acme B", iban: "DE-SAME" }, adminB);
+
+    const catalog = buildToolCatalog(stack.registry);
+    const result = await dispatchToolCall(
+      stack.dispatcher,
+      readerA,
+      "find_vendor_by_iban",
+      { iban: "DE-SAME" },
+      catalog.dispatchTable,
+    );
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error("unreachable");
+    const rows = (result.data as { rows: readonly { name: unknown }[] }).rows;
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.name).toBe("Acme A");
+  });
+
+  test("a caller without the list handler's required role gets denied, not an empty ok result", async () => {
+    await stack.dispatcher.write(VENDOR_CREATE_QN, { name: "Acme A", iban: "DE-SAME" }, adminA);
+
+    const catalog = buildToolCatalog(stack.registry);
+    const result = await dispatchToolCall(
+      stack.dispatcher,
+      noRoleA,
+      "find_vendor_by_iban",
+      { iban: "DE-SAME" },
+      catalog.dispatchTable,
+    );
+
+    expect(result.ok).toBe(false);
+    if (result.ok) throw new Error("unreachable");
+    expect(result.error).toContain("access denied");
+  });
+});

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

@@ -0,0 +1,126 @@
+import { describe, expect, test } from "bun:test";
+import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import { dispatchToolCall } from "../tool-dispatch";
+import type { ToolDispatchDescriptor } from "../types";
+
+const CALLER: SessionUser = { id: "user-1", tenantId: "tenant-1", roles: ["member"] };
+
+const DISPATCH_TABLE = new Map<string, ToolDispatchDescriptor>([
+  [
+    "search_vendor",
+    { kind: "search", entityName: "vendor", qn: "vendor-feature:query:vendor:list" },
+  ],
+  [
+    "find_vendor_by_iban",
+    {
+      kind: "findBy",
+      entityName: "vendor",
+      fieldName: "iban",
+      qn: "vendor-feature:query:vendor:list",
+    },
+  ],
+]);
+
+function recordingDispatcher() {
+  const calls: { type: string; payload: unknown; user: SessionUser }[] = [];
+  return {
+    calls,
+    query: async (type: string, payload: unknown, user: SessionUser) => {
+      calls.push({ type, payload, user });
+      return { rows: [{ id: "vendor-1" }] };
+    },
+  };
+}
+
+describe("dispatchToolCall", () => {
+  test("unknown tool name returns an error result without calling the dispatcher", async () => {
+    const dispatcher = recordingDispatcher();
+    const result = await dispatchToolCall(dispatcher, CALLER, "search_ghost", {}, DISPATCH_TABLE);
+
+    expect(result).toEqual({ ok: false, error: 'Unknown tool "search_ghost"' });
+    expect(dispatcher.calls).toHaveLength(0);
+  });
+
+  test("search tool dispatches to <entity>:list with a search payload, using the caller's identity", async () => {
+    const dispatcher = recordingDispatcher();
+    const result = await dispatchToolCall(
+      dispatcher,
+      CALLER,
+      "search_vendor",
+      { query: "Müller GmbH" },
+      DISPATCH_TABLE,
+    );
+
+    expect(result).toEqual({ ok: true, data: { rows: [{ id: "vendor-1" }] } });
+    expect(dispatcher.calls).toEqual([
+      {
+        type: "vendor-feature:query:vendor:list",
+        payload: { search: "Müller GmbH", limit: 10 },
+        user: CALLER,
+      },
+    ]);
+  });
+
+  test("search tool without a query argument returns an error, no dispatcher call", async () => {
+    const dispatcher = recordingDispatcher();
+    const result = await dispatchToolCall(dispatcher, CALLER, "search_vendor", {}, DISPATCH_TABLE);
+
+    expect(result.ok).toBe(false);
+    expect(dispatcher.calls).toHaveLength(0);
+  });
+
+  test("findBy tool dispatches to <entity>:list with an exact filter payload", async () => {
+    const dispatcher = recordingDispatcher();
+    const result = await dispatchToolCall(
+      dispatcher,
+      CALLER,
+      "find_vendor_by_iban",
+      { iban: "DE89370400440532013000" },
+      DISPATCH_TABLE,
+    );
+
+    expect(result).toEqual({ ok: true, data: { rows: [{ id: "vendor-1" }] } });
+    expect(dispatcher.calls).toEqual([
+      {
+        type: "vendor-feature:query:vendor:list",
+        payload: {
+          filter: { field: "iban", op: "eq", value: "DE89370400440532013000" },
+          limit: 10,
+        },
+        user: CALLER,
+      },
+    ]);
+  });
+
+  test("findBy tool without its required field argument returns an error, no dispatcher call", async () => {
+    const dispatcher = recordingDispatcher();
+    const result = await dispatchToolCall(
+      dispatcher,
+      CALLER,
+      "find_vendor_by_iban",
+      {},
+      DISPATCH_TABLE,
+    );
+
+    expect(result.ok).toBe(false);
+    expect(dispatcher.calls).toHaveLength(0);
+  });
+
+  test("a dispatcher rejection (e.g. missing handler or failed cap check) becomes an error result, not a throw", async () => {
+    const dispatcher = {
+      query: async () => {
+        throw new Error("no handler registered for qn 'vendor:list'");
+      },
+    };
+
+    const result = await dispatchToolCall(
+      dispatcher,
+      CALLER,
+      "search_vendor",
+      { query: "anything" },
+      DISPATCH_TABLE,
+    );
+
+    expect(result).toEqual({ ok: false, error: "no handler registered for qn 'vendor:list'" });
+  });
+});

package/src/agent-tools/index.ts

@@ -0,0 +1,9 @@
+export { buildToolCatalog } from "./tool-catalog";
+export type { ToolCallResult, ToolDispatcher } from "./tool-dispatch";
+export { dispatchToolCall } from "./tool-dispatch";
+export type {
+  RegistrySearchView,
+  ToolCatalog,
+  ToolDefinition,
+  ToolDispatchDescriptor,
+} from "./types";

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

@@ -0,0 +1,130 @@
+import type { EntityDefinition, FieldDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import type {
+  RegistrySearchView,
+  ToolCatalog,
+  ToolDefinition,
+  ToolDispatchDescriptor,
+} from "./types";
+
+/** Field types that declare `filterable` (per `packages/framework/src/engine/types/fields.ts`).
+ *  Mapped to the JSON-Schema type an LLM tool-call argument should use. `undefined` = field type
+ *  is skipped for exact-lookup tools (not filterable at the type level). */
+function jsonSchemaTypeForField(
+  field: FieldDefinition,
+): Readonly<Record<string, unknown>> | undefined {
+  switch (field.type) {
+    case "text":
+    case "multiSelect":
+    case "date":
+    case "timestamp":
+    case "locatedTimestamp":
+      return { type: "string" };
+    case "select":
+      return { type: "string", enum: field.options };
+    case "boolean":
+      return { type: "boolean" };
+    case "number":
+    case "bigInt":
+    case "decimal":
+    case "money":
+      return { type: "number" };
+    case "reference":
+      return { type: "string", description: `ID referencing "${field.entity}"` };
+    default:
+      return undefined;
+  }
+}
+
+function isFilterable(field: FieldDefinition): boolean {
+  return "filterable" in field && field.filterable === true;
+}
+
+function buildSearchTool(entityName: string, searchableFields: readonly string[]): ToolDefinition {
+  return {
+    name: `search_${entityName}`,
+    description: `Full-text search over ${entityName} across fields: ${searchableFields.join(", ")}. Returns ranked candidates, not a single answer — may need a follow-up find_${entityName}_by_* call to disambiguate.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Free-text search query" },
+      },
+      required: ["query"],
+      additionalProperties: false,
+    },
+  };
+}
+
+function buildFindByTool(
+  entityName: string,
+  fieldName: string,
+  fieldSchema: Readonly<Record<string, unknown>>,
+): ToolDefinition {
+  return {
+    name: `find_${entityName}_by_${fieldName}`,
+    description: `Exact lookup of ${entityName} where ${fieldName} matches.`,
+    inputSchema: {
+      type: "object",
+      properties: { [fieldName]: fieldSchema },
+      required: [fieldName],
+      additionalProperties: false,
+    },
+  };
+}
+
+/** True for a `:list`-verb entity query handler, e.g. "my-feature:query:vendor:list" for entity
+ *  "vendor" — the only handler shape whose payload accepts `search`/`filter` (see
+ *  `packages/framework/src/db/event-store-executor-read.ts`). Handler-first iteration, not
+ *  name-reconstruction: `entityName` here always comes from `registry.getHandlerEntity(qn)`,
+ *  the registry's own answer for this exact qn, never guessed from kebab-casing rules. */
+function isListHandlerQn(qn: string, entityName: string): boolean {
+  return qn.endsWith(`:${entityName}:list`);
+}
+
+function addToolsForListHandler(
+  registry: RegistrySearchView,
+  qn: string,
+  entityName: string,
+  entity: EntityDefinition,
+  tools: ToolDefinition[],
+  dispatchTable: Map<string, ToolDispatchDescriptor>,
+): void {
+  const searchableFields = registry.getSearchableFields(entityName);
+  if (searchableFields.length > 0) {
+    const tool = buildSearchTool(entityName, searchableFields);
+    tools.push(tool);
+    dispatchTable.set(tool.name, { kind: "search", entityName, qn });
+  }
+
+  for (const [fieldName, field] of Object.entries(
+    entity.fields as Record<string, FieldDefinition>,
+  )) {
+    if (!isFilterable(field)) continue;
+    const fieldSchema = jsonSchemaTypeForField(field);
+    if (!fieldSchema) continue;
+    const tool = buildFindByTool(entityName, fieldName, fieldSchema);
+    tools.push(tool);
+    dispatchTable.set(tool.name, { kind: "findBy", entityName, fieldName, qn });
+  }
+}
+
+/** Registry snapshot → agent tool catalog. Pure, deterministic, no I/O, no permission check —
+ *  every tool here is a name+schema only; `tool-dispatch.ts` is what actually calls a
+ *  permission-checked query handler when the LLM invokes one of these by name. Iterates mounted
+ *  `:list` handlers (not `getAllEntities()`) so the catalog never advertises a tool for an entity
+ *  that has no callable list handler — a wasted tool-call the LLM would just fail on. */
+export function buildToolCatalog(registry: RegistrySearchView): ToolCatalog {
+  const tools: ToolDefinition[] = [];
+  const dispatchTable = new Map<string, ToolDispatchDescriptor>();
+
+  for (const [qn] of registry.getAllQueryHandlers()) {
+    const entityName = registry.getHandlerEntity(qn);
+    if (!entityName || !isListHandlerQn(qn, entityName)) continue;
+
+    const entity = registry.getEntity(entityName);
+    if (!entity) continue;
+
+    addToolsForListHandler(registry, qn, entityName, entity, tools, dispatchTable);
+  }
+
+  return { tools, dispatchTable };
+}

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

@@ -0,0 +1,82 @@
+import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import type { ToolDispatchDescriptor } from "./types";
+
+/** Narrow view of `Dispatcher` (packages/framework/src/pipeline/dispatcher.ts) — dispatch only
+ *  ever needs `query`, and this keeps the module testable without constructing a real Dispatcher.
+ *  Callers pass either the app's real `dispatcher` or `{ query: ctx.queryAs }` from inside a
+ *  handler — both run the same `executeQuery` pipeline with a caller-supplied SessionUser, never
+ *  `systemQuery`/`createSystemUser`/`createAnonymousUser` (all of which drop the caller's identity). */
+export type ToolDispatcher = {
+  query(type: string, payload: unknown, user: SessionUser): Promise<unknown>;
+};
+
+export type ToolCallResult =
+  | { readonly ok: true; readonly data: unknown }
+  | { readonly ok: false; readonly error: string };
+
+const RESULT_LIMIT = 10;
+
+/** Execute one LLM-issued tool call. `callerUser` MUST be the real Tenant+User identity of
+ *  whoever's search this is running on behalf of — every call goes through `<entity>:list`,
+ *  the same handler + permission pipeline as a normal HTTP list request (search/filter are both
+ *  native `<entity>:list` payload fields, see `packages/framework/src/db/event-store-executor-read.ts`).
+ *  Never throws — a missing tool, a missing argument, or a rejected handler call (e.g. no
+ *  `<entity>:list` handler mounted, or a cap check failing) all come back as `{ ok: false }` so
+ *  the agent loop can feed the error back to the model instead of crashing. */
+export async function dispatchToolCall(
+  dispatcher: ToolDispatcher,
+  callerUser: SessionUser,
+  toolName: string,
+  toolInput: Readonly<Record<string, unknown>>,
+  dispatchTable: ReadonlyMap<string, ToolDispatchDescriptor>,
+): Promise<ToolCallResult> {
+  const descriptor = dispatchTable.get(toolName);
+  if (!descriptor) {
+    return { ok: false, error: `Unknown tool "${toolName}"` };
+  }
+
+  const payload =
+    descriptor.kind === "search"
+      ? buildSearchPayload(toolName, toolInput)
+      : buildFindByPayload(toolName, descriptor.fieldName, toolInput);
+  if (!payload.ok) {
+    return payload;
+  }
+
+  try {
+    const data = await dispatcher.query(descriptor.qn, payload.value, callerUser);
+    return { ok: true, data };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+type PayloadResult =
+  | { readonly ok: true; readonly value: Readonly<Record<string, unknown>> }
+  | { readonly ok: false; readonly error: string };
+
+function buildSearchPayload(
+  toolName: string,
+  toolInput: Readonly<Record<string, unknown>>,
+): PayloadResult {
+  const query = toolInput["query"];
+  if (typeof query !== "string" || query.length === 0) {
+    return { ok: false, error: `Tool "${toolName}" requires a non-empty string "query" argument` };
+  }
+  return { ok: true, value: { search: query, limit: RESULT_LIMIT } };
+}
+
+function buildFindByPayload(
+  toolName: string,
+  fieldName: string,
+  toolInput: Readonly<Record<string, unknown>>,
+): PayloadResult {
+  const value = toolInput[fieldName];
+  if (value === undefined) {
+    return { ok: false, error: `Tool "${toolName}" requires a "${fieldName}" argument` };
+  }
+  return {
+    ok: true,
+    value: { filter: { field: fieldName, op: "eq", value }, limit: RESULT_LIMIT },
+  };
+}