@ultimat3/admin 30.8.0 → 30.9.0

package/CLAUDE.md

@@ -95,7 +95,7 @@ Two products, one package, **two entry points**: `@ultimat3/admin/dev` (`src/dev
 | `batch.ts` / `batch-queue.ts` / `batch-bar.tsx` / `batch-job.ts` | a batch through the gate / its queued half / the bar and row checkboxes / the `admin.batch` job |
 | `resource-fields.ts` / `resource-layout.ts` / `related.ts` / `list-columns.tsx` | one column → one field / sections and form groups / related lists / a resource's table columns |
 | `audit.ts` / `audit-pg.ts` / `json-text.ts` / `audit-request.ts` | the log interface + memory log / the Postgres log / readable JSON for a cell or a diff / the trail's URL ⇄ `AuditRequest`, the history cursor |
-| `mcp-tools.ts` / `mcp-scopes.ts` / `mcp.ts` | tool derivation, each tool's scope (pure) / scope → tools for `defineAppMcp`, a token's expanded scopes / transport wiring |
+| `mcp-tools.ts` / `mcp-scopes.ts` / `mcp.ts` / `mcp-dispatch.ts` | tool derivation, each tool's scope (pure) / scope → tools for `defineAppMcp`, a token's scopes / transport / one call |
 | `test-ctx.ts` | `adminTestCtx({ actor?, granted? })` — the `CrudCtx` a test hands a page or a CRUD call; `staticAuthz` over a grant list, its own audit log. What `x g admin:page`'s emitted render test calls |
 | `jobs/` | the jobs dashboard: entities, repos, the where translation, actions, labels, resources, the overview and its `/_x` tab |
 | `batch-matching.ts` / `audit-schema.ts` | a set-based "all matching" / the audit table's DDL, a leaf |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/admin",
-  "version": "30.8.0",
+  "version": "30.9.0",
   "description": "Two dashboards: the /_x framework dev panels and the generated, AI-first app admin",
   "keywords": [
     "ultimate",
@@ -45,21 +45,21 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "30.8.0",
-    "@ultimat3/ai": "30.8.0",
-    "@ultimat3/cache": "30.8.0",
-    "@ultimat3/core": "30.8.0",
-    "@ultimat3/db": "30.8.0",
-    "@ultimat3/entity": "30.8.0",
-    "@ultimat3/http": "30.8.0",
-    "@ultimat3/i18n": "30.8.0",
-    "@ultimat3/jobs": "30.8.0",
-    "@ultimat3/mcp": "30.8.0",
-    "@ultimat3/money": "30.8.0",
-    "@ultimat3/policy": "30.8.0",
-    "@ultimat3/query": "30.8.0",
-    "@ultimat3/render": "30.8.0",
-    "@ultimat3/schema": "30.8.0",
-    "@ultimat3/ui": "30.8.0"
+    "@ultimat3/action": "30.9.0",
+    "@ultimat3/ai": "30.9.0",
+    "@ultimat3/cache": "30.9.0",
+    "@ultimat3/core": "30.9.0",
+    "@ultimat3/db": "30.9.0",
+    "@ultimat3/entity": "30.9.0",
+    "@ultimat3/http": "30.9.0",
+    "@ultimat3/i18n": "30.9.0",
+    "@ultimat3/jobs": "30.9.0",
+    "@ultimat3/mcp": "30.9.0",
+    "@ultimat3/money": "30.9.0",
+    "@ultimat3/policy": "30.9.0",
+    "@ultimat3/query": "30.9.0",
+    "@ultimat3/render": "30.9.0",
+    "@ultimat3/schema": "30.9.0",
+    "@ultimat3/ui": "30.9.0"
   }
 }

package/src/entity-columns.ts

@@ -5,6 +5,8 @@
 // physical columns. And a foreign key is read back from `$describe()`, because the binding
 // that turns `() => orgs.id` into `"orgs.id"` is private to @ultimat3/entity.
 
+import { isUltimateError } from '@ultimat3/core';
+import { SchemaUnsupportedError, toWireSchema, type WireJsonSchema } from '@ultimat3/schema';
 import { AdminFieldUnsupportedError } from './errors';
 import type { AdminColumnMeta, AdminEntity } from './registry';
 
@@ -31,6 +33,12 @@ export interface AdminColumnFacts {
   readonly length?: number;
   readonly values?: readonly string[];
   readonly references?: AdminColumnReference;
+  /**
+   * What a `json()` or `arrayOf()` value is, as JSON Schema: the column's own schema, so an MCP
+   * argument is typed by the one judge of the value. `{}` (any) where none can be derived. Absent
+   * on every other kind, whose scalar type the field type already says. SQL NULL is `nullable`.
+   */
+  readonly valueSchema?: WireJsonSchema;
 }
 
 const parseReference = (entity: string, property: string, target: string): AdminColumnReference => {
@@ -61,25 +69,49 @@ const referencesOf = (entity: AdminEntity): ReadonlyMap<string, AdminColumnRefer
   return out;
 };
 
+/**
+ * The declared schema as a tool argument, or `{}` when it cannot be said (`X_SCHEMA_UNSUPPORTED`)
+ * — permissive, so the entity's own parse still judges the value. Any other throw is a defect.
+ */
+const declaredSchema = (schema: unknown): WireJsonSchema => {
+  if (schema === undefined) return {};
+  try {
+    return toWireSchema(schema);
+  } catch (error) {
+    if (isUltimateError(error) && error.code === SchemaUnsupportedError.code) return {};
+    throw error;
+  }
+};
+
+/** The VALUE's shape; whether the column also takes SQL NULL is `nullable`, beside it. */
+const valueSchemaOf = (meta: AdminColumnMeta): WireJsonSchema | undefined => {
+  if (meta.kind !== 'jsonb' && meta.kind !== 'array') return undefined;
+  return meta.kind === 'array' ? { type: 'array' } : declaredSchema(meta.schema);
+};
+
 const factsFor = (
   name: string,
   meta: AdminColumnMeta,
   primaryKey: boolean,
   references: AdminColumnReference | undefined,
-): AdminColumnFacts => ({
-  name,
-  kind: meta.kind,
-  nullable: !meta.notNull,
-  primaryKey,
-  unique: meta.unique,
-  index: meta.index,
-  // A value the writer never supplies. `.default('free')` is a starting value the operator
-  // may still change, so it stays writable — only a generated one is read-only.
-  generated: meta.default?.kind === 'generated' || meta.onUpdate !== undefined,
-  ...(meta.length === undefined ? {} : { length: meta.length }),
-  ...(meta.values === undefined ? {} : { values: meta.values }),
-  ...(references === undefined ? {} : { references }),
-});
+): AdminColumnFacts => {
+  const valueSchema = valueSchemaOf(meta);
+  return {
+    name,
+    kind: meta.kind,
+    nullable: !meta.notNull,
+    primaryKey,
+    unique: meta.unique,
+    index: meta.index,
+    // A value the writer never supplies. `.default('free')` is a starting value the operator
+    // may still change, so it stays writable — only a generated one is read-only.
+    generated: meta.default?.kind === 'generated' || meta.onUpdate !== undefined,
+    ...(meta.length === undefined ? {} : { length: meta.length }),
+    ...(meta.values === undefined ? {} : { values: meta.values }),
+    ...(references === undefined ? {} : { references }),
+    ...(valueSchema === undefined ? {} : { valueSchema }),
+  };
+};
 
 const factsOf = (entity: AdminEntity, sealed: boolean): readonly AdminColumnFacts[] => {
   const references = referencesOf(entity);

package/src/index.ts

@@ -244,14 +244,8 @@ export {
   scopeNamed,
 } from './list-scope';
 export { AdminScopeTabs, type AdminScopeTabsProps } from './list-scope-tabs';
-export {
-  type AdminMcpActor,
-  type AdminMcpOptions,
-  type AdminToolResult,
-  adminMcp,
-  callAdminTool,
-  type McpInput,
-} from './mcp';
+export { type AdminMcpActor, type AdminMcpOptions, adminMcp } from './mcp';
+export { type AdminToolResult, callAdminTool, type McpInput } from './mcp-dispatch';
 export { adminTokenScopes, adminToolScopes } from './mcp-scopes';
 export {
   type AdminMcpTool,

package/src/mcp-dispatch.ts

@@ -0,0 +1,221 @@
+// One admin MCP tool call, dispatched: the tool resolved against the actor's own allowed list, then
+// handed to the CRUD call, action gate, batch or search its button uses. No transport here — that is
+// `mcp.ts`, which runs this AS the caller; a direct `callAdminTool` is the same path.
+
+import { invokeAdminAction } from './action-gate';
+import { invokeRowAction } from './action-row';
+import type { AdminApp } from './admin';
+import { batchPlan, runAdminBatch } from './batch';
+import { batchEnqueue } from './batch-job';
+import {
+  adminCreate,
+  adminDestroy,
+  adminDetail,
+  adminList,
+  adminUpdate,
+  type CrudCtx,
+  type CrudResult,
+} from './crud';
+import { AdminFilterInvalidError } from './errors';
+import { type AskedFilter, checkedFilter } from './list-filters';
+import { type AdminMcpTool, adminMcpTools } from './mcp-tools';
+import type { AdminAction, AdminRow } from './registry';
+import { adminSearch } from './search';
+import type { ValidationIssue } from './validate';
+
+export type McpInput = Readonly<Record<string, unknown>>;
+
+export type AdminToolResult =
+  | { readonly ok: true; readonly data: unknown }
+  | { readonly ok: false; readonly error: string; readonly reason: string };
+
+const str = (input: McpInput, key: string): string => {
+  const value = input[key];
+  return typeof value === 'string' ? value : '';
+};
+
+const num = (input: McpInput, key: string): number | undefined => {
+  const value = input[key];
+  return typeof value === 'number' ? value : undefined;
+};
+
+const withoutKeys = (input: McpInput, keys: readonly string[]): Record<string, unknown> => {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(input)) {
+    if (!keys.includes(key)) out[key] = value;
+  }
+  return out;
+};
+
+/** The `where` argument as a list of asked filters; anything else in it is refused by name. */
+const askedFilters = (where: unknown): readonly AskedFilter[] => {
+  if (where === undefined || where === null) return [];
+  const list: readonly unknown[] = Array.isArray(where) ? where : [where];
+  return list.map((one) => {
+    const bag = (typeof one === 'object' && one !== null ? one : {}) as Record<string, unknown>;
+    const op = bag['op'];
+    return {
+      // A predicate with no `field` names the empty one, which no resource derives.
+      field: typeof bag['field'] === 'string' ? bag['field'] : '',
+      ...(typeof op === 'string' ? { op } : {}),
+      value: bag['value'],
+    };
+  });
+};
+
+const actionByName = (app: AdminApp, name: string): AdminAction | undefined =>
+  [...app.resources.flatMap((resource) => resource.actions), ...app.globalActions].find(
+    (action) => action.name === name,
+  );
+
+/**
+ * Dispatch one tool call. The tool must be in this actor's allowed list — resolving the name
+ * against `adminMcpTools()` is what makes "the agent sees what it may do" true rather than
+ * aspirational.
+ */
+export async function callAdminTool(
+  app: AdminApp,
+  ctx: CrudCtx,
+  name: string,
+  input: McpInput,
+): Promise<AdminToolResult> {
+  const tool = adminMcpTools(app, ctx).find((candidate) => candidate.name === name);
+  // NOT dead code, and not the only gate: the registry's `visibleTo` predicate already hides
+  // this tool from a caller who may not use it, so an MCP call cannot reach here refused.
+  // Every other entry point (a direct `callAdminTool`, a future transport) can, so this stays
+  // as defence in depth — the authz decision must not live only in the catalog filter.
+  if (tool === undefined) {
+    return {
+      ok: false,
+      error: 'X_ADMIN_TOOL_FORBIDDEN',
+      reason: `tool "${name}" is not available to actor ${ctx.actor.id}`,
+    };
+  }
+  return dispatch(app, ctx, tool, input);
+}
+
+async function dispatch(
+  app: AdminApp,
+  ctx: CrudCtx,
+  tool: AdminMcpTool,
+  input: McpInput,
+): Promise<AdminToolResult> {
+  if (tool.kind === 'search') {
+    const result = await adminSearch({ term: str(input, 'term'), resources: app.resources, ctx });
+    return { ok: true, data: result };
+  }
+
+  if (tool.kind === 'action') {
+    const action = actionByName(app, tool.action ?? '');
+    if (action === undefined) {
+      return { ok: false, error: 'X_ADMIN_TOOL_FORBIDDEN', reason: 'action is not registered' };
+    }
+    const owner = app.resources.find((resource) => resource.actions.includes(action));
+    const own = withoutKeys(input, ['id', 'ids', 'confirmation']);
+    const confirmation = str(input, 'confirmation');
+    // `ids`: the same tool as a batch — the bar's own path, row by row through the gate.
+    if (owner !== undefined && action.batch !== undefined && Array.isArray(input['ids'])) {
+      const ids = (input['ids'] as readonly unknown[]).filter(
+        (one): one is string => typeof one === 'string',
+      );
+      const result = await runAdminBatch({
+        resource: owner,
+        action,
+        ctx,
+        selection: { kind: 'ids', ids },
+        input: own,
+        confirmation,
+        ...(batchPlan(action) === null ? {} : { enqueue: batchEnqueue(app.basePath) }),
+      });
+      if (result.ok) return { ok: true, data: result };
+      if (result.kind === 'invalid') return invalidIssues(result.issues);
+      return { ok: false, error: 'X_ADMIN_DENIED', reason: result.decision.reason };
+    }
+    const id = str(input, 'id');
+    // The row a row-level rule — and the action's own `when` — decides about, loaded through the
+    // resource that OWNS the action: what the UI's button does. A global action names no row.
+    const result =
+      owner !== undefined && id !== ''
+        ? await invokeRowAction({ resource: owner, action, id, ctx, input: own, confirmation })
+        : await invokeAdminAction({
+            action,
+            input: { ...own, ...(id === '' ? {} : { id }) },
+            actor: ctx.actor,
+            authz: ctx.authz,
+            audit: ctx.audit,
+            requestId: ctx.requestId,
+            subject: {
+              ...(action.entity === undefined ? {} : { entity: action.entity }),
+              ...(id === '' ? {} : { id }),
+            },
+            // The agent must echo the token, exactly as the UI makes an operator type it.
+            confirmation,
+          });
+    if (result.ok) return { ok: true, data: result.value };
+    if (result.kind === 'not-applicable') {
+      return { ok: false, error: result.error.code, reason: result.error.cause };
+    }
+    if (result.kind === 'invalid') return invalidIssues(result.issues);
+    return { ok: false, error: 'X_ADMIN_DENIED', reason: result.decision.reason };
+  }
+
+  const resource = app.resource(tool.entity ?? '');
+  switch (tool.kind) {
+    case 'list': {
+      const limit = num(input, 'limit');
+      const scope = str(input, 'scope');
+      try {
+        // `where` through the same validator a URL's `f.<field>` passes, and the scope by name:
+        // an agent filters by exactly what an operator can, and the resource's row scope rides
+        // the read inside `adminList` whatever the agent sends.
+        const result = await adminList(resource, ctx, {
+          cursor: str(input, 'cursor'),
+          ...(limit === undefined ? {} : { limit }),
+          ...(scope === '' ? {} : { scope }),
+          filters: askedFilters(input['where']).map((asked) => checkedFilter(resource, asked)),
+        });
+        return result.ok
+          ? { ok: true, data: result.page }
+          : { ok: false, error: 'X_ADMIN_DENIED', reason: result.decision.reason };
+      } catch (error) {
+        if (!(error instanceof AdminFilterInvalidError)) throw error;
+        return { ok: false, error: error.code, reason: error.cause };
+      }
+    }
+    case 'read':
+      return crudResult(await adminDetail(resource, ctx, str(input, 'id')));
+    case 'create':
+      return crudResult(await adminCreate(resource, ctx, input));
+    case 'update':
+      return crudResult(
+        await adminUpdate(resource, ctx, str(input, 'id'), withoutKeys(input, ['id'])),
+      );
+    case 'delete':
+      return crudResult(
+        await adminDestroy(resource, ctx, str(input, 'id'), str(input, 'confirmation')),
+      );
+  }
+}
+
+/** The schema's issues, as the one string an agent's result carries. */
+const invalidIssues = (issues: readonly ValidationIssue[]): AdminToolResult => ({
+  ok: false,
+  error: 'X_ADMIN_INVALID',
+  reason: JSON.stringify(issues),
+});
+
+function crudResult(result: CrudResult<AdminRow>): AdminToolResult {
+  if (result.ok) return { ok: true, data: result.row };
+  if (result.kind === 'denied') {
+    return { ok: false, error: 'X_ADMIN_DENIED', reason: result.decision.reason };
+  }
+  // No row by that id — or none this caller's row scope lets them see, which reads the same.
+  if (result.kind === 'missing') {
+    return { ok: false, error: 'X_ADMIN_INVALID', reason: 'no row has that id' };
+  }
+  // Reached only by a caller that sent a version; the update tool sends none.
+  if (result.kind === 'stale') {
+    return { ok: false, error: 'X_ADMIN_INVALID', reason: 'the row changed since it was read' };
+  }
+  return invalidIssues(result.issues);
+}

package/src/mcp-tools.ts

@@ -6,10 +6,12 @@
 // model, not UI copy read by a person, so they are not `t()` keys.
 
 import { toolDescription } from '@ultimat3/core';
+import type { WireJsonSchema } from '@ultimat3/schema';
 import { adminPermissionForAction, decideAction, permissionsForAction } from './action-gate';
 import type { AdminApp } from './admin';
 import { type AdminDecision, decideAll } from './authz';
 import { type CrudCtx, decideOperation, permissionsForOperation } from './crud';
+import { adminColumnsOf } from './entity-columns';
 import type { AdminFieldType } from './fields';
 import { type AdminOperation, type AdminPermission, adminPermissionFor } from './permissions';
 import type { AdminAction } from './registry';
@@ -23,6 +25,13 @@ export interface AdminToolField {
   readonly required: boolean;
   /** The argument is a LIST of `type`: the list tool's `where` is a list of predicates. */
   readonly list?: true;
+  /**
+   * The argument's exact JSON Schema, where `type` cannot say it: a `json()` or `arrayOf()`
+   * column's value is an array, an object, a scalar or `null` by its own schema, never "object".
+   */
+  readonly schema?: WireJsonSchema;
+  /** The column takes SQL NULL: the argument admits `null` beside its type (`mcp.ts`). */
+  readonly nullable?: true;
 }
 
 export interface AdminMcpTool {
@@ -83,12 +92,23 @@ const actionDescription = (action: AdminAction): string =>
       : ` Pass ids: [...] to run it once per row; the answer counts done, refused and failed${action.destructive === true ? ', and confirmation is "<entity>:<n> rows"' : ''}.`,
   ].join('');
 
-const formFields = (resource: AdminResource): readonly AdminToolField[] =>
-  resource.formFields.map((field) => ({
-    name: field.name,
-    type: field.type,
-    required: field.required,
-  }));
+/**
+ * Every form field, with what its column says beyond the type: a `json` one its value schema (`{}`,
+ * any, where none exists), a nullable one that it takes `null` — the form's empty box, over MCP.
+ */
+const formFields = (resource: AdminResource): readonly AdminToolField[] => {
+  const facts = new Map(adminColumnsOf(resource.entity).map((column) => [column.name, column]));
+  return resource.formFields.map((field) => {
+    const column = facts.get(field.name);
+    return {
+      name: field.name,
+      type: field.type,
+      required: field.required,
+      ...(field.type === 'json' ? { schema: column?.valueSchema ?? {} } : {}),
+      ...(column?.nullable === true ? { nullable: true as const } : {}),
+    };
+  });
+};
 
 /**
  * The list tool says what it filters by, because a schema cannot: `where` is a list of

package/src/mcp.ts

@@ -1,6 +1,7 @@
 // The AI-first surface: the admin's resources and actions as MCP tools, wired through
 // `defineAppMcp` so the user's agents drive the user's app. Same authz, same audit, same
 // confirmation rules as the buttons — this file adds a transport, not a second back door.
+// What one call DOES is `mcp-dispatch.ts`; this file is the catalog, the schemas and the caller.
 
 import type { Actor } from '@ultimat3/core';
 import { agentActor, ctxOf, hasContext, runWithContext, withChildContext } from '@ultimat3/core';
@@ -17,226 +18,17 @@ import {
   type ResolvedToken,
   type ToolArgs,
 } from '@ultimat3/mcp';
-import { invokeAdminAction } from './action-gate';
-import { invokeRowAction } from './action-row';
 import type { AdminApp } from './admin';
 import type { AdminActor } from './authz';
-import { batchPlan, runAdminBatch } from './batch';
-import { batchEnqueue } from './batch-job';
-import {
-  adminCreate,
-  adminDestroy,
-  adminDetail,
-  adminList,
-  adminUpdate,
-  type CrudCtx,
-  type CrudResult,
-} from './crud';
-import { AdminFilterInvalidError } from './errors';
 import type { AdminFieldType } from './fields';
-import { type AskedFilter, checkedFilter } from './list-filters';
+import { callAdminTool } from './mcp-dispatch';
 import { adminTokenScopes, adminToolScopes, includedToolScopes } from './mcp-scopes';
-import { type AdminMcpTool, adminMcpTools, adminToolCatalog } from './mcp-tools';
-import type { AdminAction, AdminRow } from './registry';
-import { adminSearch } from './search';
-import type { ValidationIssue } from './validate';
-
-export type McpInput = Readonly<Record<string, unknown>>;
-
-export type AdminToolResult =
-  | { readonly ok: true; readonly data: unknown }
-  | { readonly ok: false; readonly error: string; readonly reason: string };
-
-const str = (input: McpInput, key: string): string => {
-  const value = input[key];
-  return typeof value === 'string' ? value : '';
-};
-
-const num = (input: McpInput, key: string): number | undefined => {
-  const value = input[key];
-  return typeof value === 'number' ? value : undefined;
-};
-
-const withoutKeys = (input: McpInput, keys: readonly string[]): Record<string, unknown> => {
-  const out: Record<string, unknown> = {};
-  for (const [key, value] of Object.entries(input)) {
-    if (!keys.includes(key)) out[key] = value;
-  }
-  return out;
-};
-
-/** The `where` argument as a list of asked filters; anything else in it is refused by name. */
-const askedFilters = (where: unknown): readonly AskedFilter[] => {
-  if (where === undefined || where === null) return [];
-  const list: readonly unknown[] = Array.isArray(where) ? where : [where];
-  return list.map((one) => {
-    const bag = (typeof one === 'object' && one !== null ? one : {}) as Record<string, unknown>;
-    const op = bag['op'];
-    return {
-      // A predicate with no `field` names the empty one, which no resource derives.
-      field: typeof bag['field'] === 'string' ? bag['field'] : '',
-      ...(typeof op === 'string' ? { op } : {}),
-      value: bag['value'],
-    };
-  });
-};
-
-const actionByName = (app: AdminApp, name: string): AdminAction | undefined =>
-  [...app.resources.flatMap((resource) => resource.actions), ...app.globalActions].find(
-    (action) => action.name === name,
-  );
-
-/**
- * Dispatch one tool call. The tool must be in this actor's allowed list — resolving the name
- * against `adminMcpTools()` is what makes "the agent sees what it may do" true rather than
- * aspirational.
- */
-export async function callAdminTool(
-  app: AdminApp,
-  ctx: CrudCtx,
-  name: string,
-  input: McpInput,
-): Promise<AdminToolResult> {
-  const tool = adminMcpTools(app, ctx).find((candidate) => candidate.name === name);
-  // NOT dead code, and not the only gate: the registry's `visibleTo` predicate already hides
-  // this tool from a caller who may not use it, so an MCP call cannot reach here refused.
-  // Every other entry point (a direct `callAdminTool`, a future transport) can, so this stays
-  // as defence in depth — the authz decision must not live only in the catalog filter.
-  if (tool === undefined) {
-    return {
-      ok: false,
-      error: 'X_ADMIN_TOOL_FORBIDDEN',
-      reason: `tool "${name}" is not available to actor ${ctx.actor.id}`,
-    };
-  }
-  return dispatch(app, ctx, tool, input);
-}
-
-async function dispatch(
-  app: AdminApp,
-  ctx: CrudCtx,
-  tool: AdminMcpTool,
-  input: McpInput,
-): Promise<AdminToolResult> {
-  if (tool.kind === 'search') {
-    const result = await adminSearch({ term: str(input, 'term'), resources: app.resources, ctx });
-    return { ok: true, data: result };
-  }
-
-  if (tool.kind === 'action') {
-    const action = actionByName(app, tool.action ?? '');
-    if (action === undefined) {
-      return { ok: false, error: 'X_ADMIN_TOOL_FORBIDDEN', reason: 'action is not registered' };
-    }
-    const owner = app.resources.find((resource) => resource.actions.includes(action));
-    const own = withoutKeys(input, ['id', 'ids', 'confirmation']);
-    const confirmation = str(input, 'confirmation');
-    // `ids`: the same tool as a batch — the bar's own path, row by row through the gate.
-    if (owner !== undefined && action.batch !== undefined && Array.isArray(input['ids'])) {
-      const ids = (input['ids'] as readonly unknown[]).filter(
-        (one): one is string => typeof one === 'string',
-      );
-      const result = await runAdminBatch({
-        resource: owner,
-        action,
-        ctx,
-        selection: { kind: 'ids', ids },
-        input: own,
-        confirmation,
-        ...(batchPlan(action) === null ? {} : { enqueue: batchEnqueue(app.basePath) }),
-      });
-      if (result.ok) return { ok: true, data: result };
-      if (result.kind === 'invalid') return invalidIssues(result.issues);
-      return { ok: false, error: 'X_ADMIN_DENIED', reason: result.decision.reason };
-    }
-    const id = str(input, 'id');
-    // The row a row-level rule — and the action's own `when` — decides about, loaded through the
-    // resource that OWNS the action: what the UI's button does. A global action names no row.
-    const result =
-      owner !== undefined && id !== ''
-        ? await invokeRowAction({ resource: owner, action, id, ctx, input: own, confirmation })
-        : await invokeAdminAction({
-            action,
-            input: { ...own, ...(id === '' ? {} : { id }) },
-            actor: ctx.actor,
-            authz: ctx.authz,
-            audit: ctx.audit,
-            requestId: ctx.requestId,
-            subject: {
-              ...(action.entity === undefined ? {} : { entity: action.entity }),
-              ...(id === '' ? {} : { id }),
-            },
-            // The agent must echo the token, exactly as the UI makes an operator type it.
-            confirmation,
-          });
-    if (result.ok) return { ok: true, data: result.value };
-    if (result.kind === 'not-applicable') {
-      return { ok: false, error: result.error.code, reason: result.error.cause };
-    }
-    if (result.kind === 'invalid') return invalidIssues(result.issues);
-    return { ok: false, error: 'X_ADMIN_DENIED', reason: result.decision.reason };
-  }
-
-  const resource = app.resource(tool.entity ?? '');
-  switch (tool.kind) {
-    case 'list': {
-      const limit = num(input, 'limit');
-      const scope = str(input, 'scope');
-      try {
-        // `where` through the same validator a URL's `f.<field>` passes, and the scope by name:
-        // an agent filters by exactly what an operator can, and the resource's row scope rides
-        // the read inside `adminList` whatever the agent sends.
-        const result = await adminList(resource, ctx, {
-          cursor: str(input, 'cursor'),
-          ...(limit === undefined ? {} : { limit }),
-          ...(scope === '' ? {} : { scope }),
-          filters: askedFilters(input['where']).map((asked) => checkedFilter(resource, asked)),
-        });
-        return result.ok
-          ? { ok: true, data: result.page }
-          : { ok: false, error: 'X_ADMIN_DENIED', reason: result.decision.reason };
-      } catch (error) {
-        if (!(error instanceof AdminFilterInvalidError)) throw error;
-        return { ok: false, error: error.code, reason: error.cause };
-      }
-    }
-    case 'read':
-      return crudResult(await adminDetail(resource, ctx, str(input, 'id')));
-    case 'create':
-      return crudResult(await adminCreate(resource, ctx, input));
-    case 'update':
-      return crudResult(
-        await adminUpdate(resource, ctx, str(input, 'id'), withoutKeys(input, ['id'])),
-      );
-    case 'delete':
-      return crudResult(
-        await adminDestroy(resource, ctx, str(input, 'id'), str(input, 'confirmation')),
-      );
-  }
-}
-
-/** The schema's issues, as the one string an agent's result carries. */
-const invalidIssues = (issues: readonly ValidationIssue[]): AdminToolResult => ({
-  ok: false,
-  error: 'X_ADMIN_INVALID',
-  reason: JSON.stringify(issues),
-});
-
-function crudResult(result: CrudResult<AdminRow>): AdminToolResult {
-  if (result.ok) return { ok: true, data: result.row };
-  if (result.kind === 'denied') {
-    return { ok: false, error: 'X_ADMIN_DENIED', reason: result.decision.reason };
-  }
-  // No row by that id — or none this caller's row scope lets them see, which reads the same.
-  if (result.kind === 'missing') {
-    return { ok: false, error: 'X_ADMIN_INVALID', reason: 'no row has that id' };
-  }
-  // Reached only by a caller that sent a version; the update tool sends none.
-  if (result.kind === 'stale') {
-    return { ok: false, error: 'X_ADMIN_INVALID', reason: 'the row changed since it was read' };
-  }
-  return invalidIssues(result.issues);
-}
+import {
+  type AdminMcpTool,
+  type AdminToolField,
+  adminMcpTools,
+  adminToolCatalog,
+} from './mcp-tools';
 
 /**
  * What a session token resolves to: the actor, and optionally the admin scopes the TOKEN was
@@ -301,11 +93,30 @@ const JSON_TYPE: Readonly<Record<AdminFieldType, NonNullable<JsonSchema['type']>
  * exactly the arguments the action needs; a made-up field list would describe a contract nobody
  * validates against. Open lets the action's own validation be the one that decides.
  */
+const NULL_SCHEMA: JsonSchema = { type: 'null' };
+
+/** `{}` admits anything; otherwise only a `null` type or a `null` branch says so. */
+const admitsNull = (schema: JsonSchema): boolean =>
+  Object.keys(schema).length === 0 ||
+  schema.type === 'null' ||
+  (schema.anyOf?.some((branch) => branch.type === 'null') ?? false);
+
+/**
+ * One argument. A field's own schema first — `JSON_TYPE` is the kind's scalar, and a `json()`
+ * column's value is whatever its schema says, where a blanket `object` refused every array and
+ * every JSON `null`. A nullable column takes `null` beside it, which the server's argument check
+ * otherwise refused before the entity was asked.
+ */
+const argumentSchema = (field: AdminToolField): JsonSchema => {
+  const value = field.schema ?? { type: JSON_TYPE[field.type] };
+  return field.nullable === true && !admitsNull(value) ? { anyOf: [value, NULL_SCHEMA] } : value;
+};
+
 const inputSchema = (tool: AdminMcpTool): JsonSchema => ({
   type: 'object',
   properties: Object.fromEntries(
     tool.input.map((field) => {
-      const one = { type: JSON_TYPE[field.type] };
+      const one = argumentSchema(field);
       return [field.name, field.list === true ? { type: 'array', items: one } : one];
     }),
   ),

package/src/registry.ts

@@ -42,6 +42,8 @@ export interface AdminColumnMeta {
    * server. Present means the admin derives NO readable field for it — see `entity-columns.ts`.
    */
   readonly sealed?: { readonly lookup: boolean };
+  /** `json(schema)`'s schema: what a `json()` column's MCP argument is typed by (`entity-columns.ts`). */
+  readonly schema?: unknown;
 }
 
 /** One column of a registered entity. An `@ultimat3/entity` `Column` satisfies this. */