akanjs 3.0.0-beta.2 → 3.0.0-beta.20

package/store/agentic/StToolBuilder.ts

@@ -9,6 +9,7 @@ import {
   type PrimitiveScalar,
 } from "akanjs/base";
 import type { ParamFieldType } from "akanjs/constant";
+import type { ReactNode } from "react";
 import {
   AgenticSurface,
   type JsonSchema,
@@ -21,23 +22,20 @@ import { tagAction } from "../actionTag";
 
 import { useEffect, useRef } from "../hooks";
 
+/** `submit`'s value is what the model reads back; the first of the two calls settles the card. */
+export interface StToolCardControl {
+  submit: (value: unknown) => void;
+  cancel: (reason?: string) => void;
+}
+
 export interface StToolMeta {
-  /**
-   * Whether the call has to be waited out before what it did to the screen is reported back to the model. `false`
-   * is a read that returns what is already there; the default waits, because a write may still be landing when
-   * `exec` resolves and a report taken then describes the screen one tick before the call.
-   */
+  /** Default true: the screen is waited out before the call reports; `false` for a read of what is already there. */
   settle?: boolean;
   confirm?: ToolConfirm;
   guard?: ToolGuard;
 }
 
-/**
- * What one argument may be: a scalar, an enum, or **one** array level of either. The array level is here because
- * `fill<Model>Form` already describes exactly that for a form field, so the same shape reaching an agent through a
- * form and not through a component tool was an oversight rather than a boundary — and a tool that cannot say
- * "a list of these" says it in prose instead, which is a format the app then owns a parser for.
- */
+/** A scalar, an enum, or one array level of either. */
 export type StToolArgType = ParamFieldType | readonly [ParamFieldType];
 
 interface StToolArg {
@@ -53,24 +51,11 @@ export interface StToolArgOption<V> {
 }
 
 type ScalarValue<T> = T extends EnumInstance<string, infer V> ? V : T extends { [CLIENT_VALUE]: infer V } ? V : never;
-/** What one element carries, which is the whole argument unless it is an array. `oneOf` narrows this one. */
 type ElementValue<T> = T extends readonly [infer E] ? ScalarValue<E> : ScalarValue<T>;
 type ArgValue<T> = T extends readonly [unknown] ? ElementValue<T>[] : ElementValue<T>;
 type NarrowedValue<T, V> = T extends readonly [unknown] ? V[] : V;
 
-/**
- * A component tool past its description: `.arg()` for what the caller must pass, `.opt()` for what it may, and
- * one `.exec()`.
- *
- * This is not A12's rejected store-action builder — a store action derives its schema from the endpoint it is
- * named after, while a component tool exists nowhere else, so declaring is the only source there is. `.arg()` and
- * `.opt()` only accumulate data; `.exec()` is the one hook, so the chain must complete in one unconditional
- * statement.
- *
- * A falsy name declares the tool without publishing it: the callable still works for the click that a person
- * makes, and nothing reaches the agent. That is how a conditional surface stays writable at all — `.exec()` is a
- * hook, so a component can never skip the declaration, only the publication.
- */
+/** `.arg()`/`.opt()` only accumulate; `.exec()` is the hook. A falsy name declares the tool without publishing it. */
 export class StToolBuilder<Args extends unknown[] = []> {
   readonly #name: string | null;
   readonly #desc: string;
@@ -78,7 +63,7 @@ export class StToolBuilder<Args extends unknown[] = []> {
   readonly #args: StToolArg[];
 
   constructor(name: string | null, desc: string, meta: StToolMeta = {}, args: StToolArg[] = []) {
-
+    
     this.#name = name || null;
     this.#desc = desc;
     this.#meta = meta;
@@ -119,7 +104,7 @@ export class StToolBuilder<Args extends unknown[] = []> {
     optional: boolean,
     option: StToolArgOption<ElementValue<T>>,
   ): StToolBuilder<[...Args, ArgValue<T> | null]> {
-
+    
     const published = this.#name && StToolBuilder.#describable(this.#name, name, type) ? this.#name : null;
     return new StToolBuilder(published, this.#desc, this.#meta, [
       ...this.#args,
@@ -127,16 +112,7 @@ export class StToolBuilder<Args extends unknown[] = []> {
     ]);
   }
 
-  /**
-   * The only hook in the chain. `run`, `guard`, and `confirm` stay always-latest, and so does the **name** —
-   * `desc` and `args` are read once per name because a component that renders once per row declares one tool
-   * many times and only its own arguments differ.
-   *
-   * The name has to follow the render, because withholding it is how a conditional surface is written
-   * (`st.tool(canRemove && "removeX")`). Frozen on the first render it failed both ways: a control that appeared
-   * later never published, and — worse — one that went away stayed published, leaving an agent a lever the screen
-   * no longer offers.
-   */
+  /** The hook. `run`/`guard`/`confirm` and the name follow every render; `desc`/`args` are read once per name. */
   exec(run: (...args: Args) => unknown): (...args: Args) => Promise<void> {
     const surface = useSurface();
     const scope = useScopePath();
@@ -150,7 +126,6 @@ export class StToolBuilder<Args extends unknown[] = []> {
       const call = async (...args: Args) => {
         await live.current.run(...args);
       };
-      
       callable.current = {
         name: this.#name,
         fn: this.#name ? tagAction(call, { action: AgenticSurface.fullName(scope, this.#name) }) : call,
@@ -184,6 +159,39 @@ export class StToolBuilder<Args extends unknown[] = []> {
     return callable.current.fn;
   }
 
+  /** A tool the user answers with a chat card. Args are checked in the guard, before the card parks; no `confirm`. */
+  card(render: (control: StToolCardControl, ...args: Args) => ReactNode): void {
+    const surface = useSurface();
+    const scope = useScopePath();
+    const live = useRef({ render, meta: this.#meta });
+    live.current = { render, meta: this.#meta };
+    const declared = useRef<{ name: string | null; desc: string; meta: StToolMeta; args: StToolArg[] } | null>(null);
+    if (declared.current?.name !== this.#name)
+      declared.current = { name: this.#name, desc: this.#desc, meta: this.#meta, args: this.#args };
+    const scopeKey = scope.join(".");
+    useEffect(() => {
+      const spec = declared.current;
+      const name = spec?.name;
+      if (!spec || !name) return;
+      return surface.registerTool(scope, {
+        name,
+        description: spec.desc,
+        settle: spec.meta.settle,
+        parameters: StToolBuilder.parametersOf(spec.args),
+        guard: (args) => {
+          try {
+            StToolBuilder.positionalOf(name, spec.args, args);
+          } catch (error) {
+            return error instanceof Error ? error.message : String(error);
+          }
+          return live.current.meta.guard?.(args) ?? true;
+        },
+        card: ({ args, submit, cancel }) =>
+          live.current.render({ submit, cancel }, ...(StToolBuilder.positionalOf(name, spec.args, args) as Args)),
+      });
+    }, [surface, scopeKey, this.#name]);
+  }
+
   static parametersOf(args: StToolArg[]): JsonSchema | undefined {
     if (!args.length) return undefined;
     const required = args.filter((arg) => !arg.optional).map((arg) => arg.name);
@@ -199,7 +207,6 @@ export class StToolBuilder<Args extends unknown[] = []> {
     return StToolBuilder.#schemaOfArg(arg.type, arg.oneOf);
   }
 
-  /** The array level `FormFields` wraps a field's leaf in, for an argument that declared one instead. */
   static #schemaOfArg(type: StToolArgType, oneOf?: readonly (string | number)[]): JsonSchema {
     const narrowed = (schema: JsonSchema): JsonSchema => (oneOf ? { ...schema, enum: [...oneOf] } : schema);
     if (!Array.isArray(type)) return narrowed(StToolBuilder.schemaOf(type as ParamFieldType));
@@ -223,7 +230,7 @@ export class StToolBuilder<Args extends unknown[] = []> {
     }
   }
 
-  /** Scalars and enums only — the value arrives as JSON from a model, so a class instance has no way in. */
+  /** Scalars and enums only (a value arrives as JSON); throws for anything else. */
   static schemaOf(type: ParamFieldType): JsonSchema {
     if (isEnum(type as Cls)) {
       const enumRef = type as EnumInstance;
@@ -267,7 +274,7 @@ export class StToolBuilder<Args extends unknown[] = []> {
     });
   }
 
-  /** What `AgentBridge` does for endpoint arguments, for a component tool's own — nothing on the wire enforces the published schema. */
+  /** Nothing on the wire enforces the published schema, so every argument value is checked here. */
   static checkedValue(
     toolName: string,
     argName: string,

package/store/agentic/StToolDraft.ts

@@ -1,12 +1,5 @@
 import { StToolBuilder, type StToolMeta } from "./StToolBuilder";
 
-/**
- * A component tool before it has said what it does: `st.tool("x", { confirm }).desc("…")`.
- *
- * The description is the step that has to happen, so it is the one the type insists on. A model picks a tool by
- * that sentence and by nothing else, and the surface reads it a second time to tell fifty rows publishing one
- * interchangeable verb from two components that happened to pick the same name.
- */
 export class StToolDraft {
   readonly #name: string | null;
   readonly #meta: StToolMeta;

package/store/agentic/attachAgentic.ts

@@ -7,19 +7,11 @@ import type { StToolMeta } from "./StToolBuilder";
 import { StToolDraft } from "./StToolDraft";
 
 export interface StAgentic {
-  /**
-   * Local state the in-page agent can read: `.desc()` then `.init()`, which is the hook and returns what
-   * `useState` returns. Writes need `set: true` and go through the generated `set<Name>` tool.
-   */
+  /** Agent-readable local state: `.desc()` then `.init()` (the hook). Agent writes need `set: true`. */
   useState: <T extends AgentFieldType>(name: string | null, type: T, meta?: StStateMeta) => StStateDraft<T>;
   /** A read-only derived value the agent can read while the component is mounted: `.desc()` then `.value()`. */
   expose: <T extends AgentFieldType>(name: string | null, type: T, meta?: StExposeMeta) => StExposeDraft<T>;
-  /**
-   * A component tool: `.desc()`, then `.arg()` / `.opt()`, chained onto one `.exec()` hook.
-   *
-   * A falsy name declares the tool without publishing it — the callable still drives the click a person makes.
-   * Every one of these ends in a hook, so a conditional surface withholds the name rather than skipping the chain.
-   */
+  /** `.desc()`, `.arg()`/`.opt()`, then the hook `.exec()` or `.card()`. A falsy name declares without publishing. */
   tool: (name: string | null, meta?: StToolMeta) => StToolDraft;
 }
 

package/store/agentic/formFields.ts

@@ -11,21 +11,12 @@ export interface FormFieldRef {
   field: ConstantField;
 }
 
-/** Written by the document layer, never by the person at the form. */
 const baseFields = new Set(["id", "createdAt", "updatedAt", "removedAt"]);
 const MAX_DEPTH = 4;
 
-/**
- * What a form's fields look like to an agent: which setter action belongs to which field, what shape a value for
- * it has, and whether a value it sent is one that field accepts.
- *
- * The action-to-field map is built **forward** from `formSetterNames`, never by taking a name apart:
- * `set(.+)On(.+)` has more than one reading whenever a field or a model name contains `On`.
- */
 export class FormFields {
   static #index: Map<string, FormFieldRef> | null = null;
 
-  /** Every `set<Field>On<Model>` this client knows, against the field it writes. */
   static ref(action: string): FormFieldRef | null {
     FormFields.#index ??= FormFields.#buildIndex();
     return FormFields.#index.get(action) ?? null;
@@ -43,7 +34,6 @@ export class FormFields {
     return index;
   }
 
-  /** The fields of a model's form an agent may write, with the setter each one answers to. */
   static patchable(refName: string): { key: string; action: string; field: ConstantField; schema: JsonSchema }[] {
     const className = capitalize(refName);
     const model = ConstantRegistry.getDatabase(refName);
@@ -56,14 +46,7 @@ export class FormFields {
       });
   }
 
-  /**
-   * The shape a value for one field has, or null when there is nothing honest to publish.
-   *
-   * A relation is left out rather than described as its id: the form holds the whole related document, so writing
-   * an id would need a lookup the store does not do — a relation is picked or uploaded, never typed. `hidden`,
-   * `secret`, and `resolve` are out at every level, the first two because their reads are masked and a writer for
-   * one would be the door around that, the last because it is computed and has no setter at all.
-   */
+  /** Null for a relation (picked, never typed) and for hidden/secret/resolve, whose writer would bypass the mask. */
   static schema(field: ConstantField, depth = 0): JsonSchema | null {
     if (field.fieldType !== "property" || depth > MAX_DEPTH) return null;
     const leaf = FormFields.#leafSchema(field, depth);
@@ -81,6 +64,8 @@ export class FormFields {
       return value ? { type: "object", additionalProperties: value } : null;
     }
     if (PrimitiveRegistry.has(modelRef)) {
+      
+      if (PrimitiveRegistry.agentOf(modelRef)) return null;
       try {
         return StToolBuilder.schemaOf(modelRef as unknown as ParamFieldType);
       } catch {
@@ -93,6 +78,7 @@ export class FormFields {
   }
 
   static #ofSchema(field: ConstantField): JsonSchema | null {
+    if (PrimitiveRegistry.agentOf(field.of)) return null;
     try {
       return StToolBuilder.schemaOf(field.of as unknown as ParamFieldType);
     } catch {
@@ -113,12 +99,7 @@ export class FormFields {
     return { type: "object", properties: Object.fromEntries(entries), additionalProperties: false };
   }
 
-  /**
-   * The value the store should receive, or a throw naming what was wrong with the one that arrived.
-   *
-   * `additionalProperties: false` travels in the published schema and nothing on the wire enforces it, so an
-   * undeclared key is reported here rather than written into the form and shipped on the next submit.
-   */
+  /** Throws on a bad value: nothing on the wire enforces the published schema, `additionalProperties` included. */
   static checked(action: string, path: string, field: ConstantField, value: unknown, depth = 0): unknown {
     if (value === null) {
       if (!field.nullable) throw new Error(`"${path}" of ${action} does not take null.`);
@@ -169,20 +150,12 @@ export class FormFields {
     return !!value && typeof value === "object" && !Array.isArray(value);
   }
 
-  /**
-   * The tool that lists what a field can be set to. One name across both picker hooks on purpose: a form draws a
-   * relation picker and an upload control side by side, and a model that learned this name on one field spells it
-   * the same on the next. Two names one word apart would cost a failed call to learn.
-   */
+  /** Shared by both picker hooks on purpose, so a model that learned it on one field spells it the same on the next. */
   static optionsToolName(refName: string, key: string): string {
     return `load${capitalize(key)}OptionsOn${capitalize(refName)}`;
   }
 
-  /**
-   * The database model a relation field points at, or null for anything else — a primitive, an enum, a scalar.
-   * It is the question both picker hooks ask of a field `schema` refused, and the refusal alone does not answer
-   * it: a `hidden` scalar and an undescribable one are refused too, and neither is something to pick.
-   */
+  /** The database model a relation field points at, else null. */
   static relationOf(field: ConstantField): string | null {
     const modelRef = field.modelRef as unknown as Cls;
     if (field.fieldType !== "property" || field.enum || !modelRef || PrimitiveRegistry.has(modelRef)) return null;
@@ -195,14 +168,7 @@ export class FormFields {
     return field.arrDepth > 0 || (field.modelRef as unknown) === Map || !!FormFields.#scalarModel(field);
   }
 
-  /**
-   * The embedded model an array field's rows are, or null for every other field.
-   *
-   * This is the one shape where writing the whole array is a hazard rather than an inconvenience: the agent has to
-   * echo every row it is *not* changing, `checked` validates types and not values, so one mistyped row it was never
-   * asked to touch is written silently. A relation array is excluded — its rows travel as ids, which are the payload
-   * and are refused by name when wrong — and so is an array of primitives, for the same reason.
-   */
+  /** The embedded model of an array field's rows, else null — relation and primitive arrays included. */
   static rowModelOf(field: ConstantField) {
     return field.arrDepth > 0 ? FormFields.#scalarModel(field) : null;
   }

package/store/agentic/index.ts

@@ -7,7 +7,7 @@ export * from "./StStateBuilder";
 export * from "./StStateDraft";
 export * from "./StToolBuilder";
 export * from "./StToolDraft";
+export * from "./useAgentReference";
 export * from "./useFieldTool";
-export * from "./useFileFieldTool";
 export * from "./useFormTools";
 export * from "./useRelationFieldTool";

package/store/agentic/useAgentReference.ts

@@ -0,0 +1,31 @@
+"use client";
+import { SessionContext } from "../../vendor/use-agentic";
+
+import { useContext } from "../hooks";
+import { type AgentFieldType, AgentValue, type AgentValueOf } from "./AgentValue";
+
+/** `refName`/`refId`/`path` say what was pointed at; `value` is what the model is shown now, masked by `type`. */
+export interface AgentReferenceInput<T extends AgentFieldType> {
+  refName: string;
+  refId: string;
+  /** What the chip draws and what the token in the draft spells. */
+  label: string;
+  /** A dotted path into the document, in `pathSet`'s vocabulary. Absent points at the whole of it. */
+  path?: string;
+  type: T;
+  value: AgentValueOf<T>;
+}
+
+/** Stages a reference in the enclosing agent session; outside one it warns and does nothing. */
+export const useAgentReference = () => {
+  const session = useContext(SessionContext);
+  return <T extends AgentFieldType>({ type, value, ...pointer }: AgentReferenceInput<T>) => {
+    const owner = `reference ${pointer.refName}/${pointer.refId}`;
+    if (!session) {
+      console.warn(`${owner} was not staged: this component is not inside an <Agent.Chat /> or <Agent.Zone />.`);
+      return;
+    }
+    if (!AgentValue.publishable(owner, type)) return;
+    session.refer({ ...pointer, value: AgentValue.serialize(type, value) });
+  };
+};

package/store/agentic/useFieldTool.ts

@@ -9,12 +9,6 @@ import { useEffect, useRef } from "../hooks";
 import { StoreRegistry } from "../storeRegistry";
 import { type FormFieldRef, FormFields } from "./formFields";
 
-/**
- * A control's `transform` is what it does to every value a person types, so an agent's write goes through it too —
- * otherwise a `Field.Phone` stores `010-1234-5678` for the person and the raw digits for the agent. It normalizes
- * one scalar, so an array-valued control (`TextList`, `Tags`, `DoubleNumber`) applies it per element. A cleared
- * nullable field stays null: a normalizer written for a value would turn it into one.
- */
 const normalized = (value: unknown, transform: unknown): unknown => {
   if (typeof transform !== "function" || value === null) return value;
   const apply = transform as (input: unknown) => unknown;
@@ -30,20 +24,16 @@ const rowsOf = (ref: FormFieldRef): unknown[] => {
   return Array.isArray(rows) ? rows : [];
 };
 
-/**
- * Append and remove-by-index for an array of embedded rows, beside the whole-array setter.
- *
- * Not new authority: the setter this control already published can produce any array these two can, so they are
- * strictly weaker — which is what makes deriving them from the same field sound. What they add is that neither can
- * touch a row it was not given, so the agent stops having to retype the rows it is leaving alone.
- *
- * Both take a list and act atomically. Removing indices one call at a time would shift the ones not yet removed, so
- * `sub` filters the whole set at once, the way the generated action already does.
- *
- * `add` appends and publishes no insert position: the `+` a person presses always appends, and the framework cannot
- * see the `limit` an app may pass from its own `onAdd`. `addOrSub` is never published — it matches by `indexOf`, so
- * on rows it compares by reference and every toggle would append.
- */
+const isOutside = (idx: unknown, length: number) =>
+  typeof idx !== "number" || !Number.isInteger(idx) || idx < 0 || idx >= length;
+
+const idxsParameters: JsonSchema = {
+  type: "object",
+  properties: { idxs: { type: "array", items: { type: "integer" } } },
+  required: ["idxs"],
+  additionalProperties: false,
+};
+
 const rowEntries = (ref: FormFieldRef, arraySchema: JsonSchema): ToolEntry[] => {
   if (!FormFields.rowModelOf(ref.field)) return [];
   const names = formSetterNames(capitalize(ref.refName), ref.key);
@@ -66,19 +56,12 @@ const rowEntries = (ref: FormFieldRef, arraySchema: JsonSchema): ToolEntry[] =>
     {
       name: names.subFieldOnModel,
       description: `Remove rows of ${ref.key} from the ${ref.refName} form by their positions, counting from 0.`,
-      parameters: {
-        type: "object",
-        properties: { idxs: { type: "array", items: { type: "integer" } } },
-        required: ["idxs"],
-        additionalProperties: false,
-      },
+      parameters: idxsParameters,
       guard: (args) => {
         const idxs = args.idxs;
         if (!Array.isArray(idxs) || !idxs.length) return `"idxs" of ${names.subFieldOnModel} takes at least one index.`;
         const length = rowsOf(ref).length;
-        const outside = idxs.filter(
-          (idx) => typeof idx !== "number" || !Number.isInteger(idx) || idx < 0 || idx >= length,
-        );
+        const outside = idxs.filter((idx) => isOutside(idx, length));
         if (!outside.length) return true;
         return `${ref.key} has ${length} ${length === 1 ? "row" : "rows"}, so ${outside.join(", ")} is out of range.`;
       },
@@ -88,23 +71,14 @@ const rowEntries = (ref: FormFieldRef, arraySchema: JsonSchema): ToolEntry[] =>
 };
 
 export interface FieldToolOptions {
-  /** The control's own normalizer. Applied to the agent's write exactly as it is to the person's typing. */
+  /** Applied to the agent's write exactly as to the person's typing. */
   transform?: unknown;
-  /** True while the person cannot use the control. Publishes nothing, so the agent gets no lever the screen withholds. */
+  /** While true, nothing is published. */
   disabled?: boolean;
-  /** The person can drag entries into a new order, so `move<Field>On<Model>` is a lever the screen really has. */
+  /** Also publishes `move<Field>On<Model>`, for a list the person can drag. */
   sortable?: boolean;
 }
 
-/**
- * Reorder-by-position for a list the person can drag, beside the whole-array setter.
- *
- * The drag is the lever the screen actually offers, and it changes no row's content — so an agent asked to move one
- * row should not have to retype the nine it is leaving alone, which is the same argument that gives an embedded-row
- * array its `add`/`sub`. There is no store action behind it: reordering *is* a whole-array write, so this splices
- * the live rows and hands them to the setter the drag hands them to, `transform` deliberately not applied — the
- * values are already stored, and normalizing them again is not something dragging does.
- */
 const moveEntry = (ref: FormFieldRef, onChange: () => (value: unknown) => unknown): ToolEntry => {
   const name = formSetterNames(capitalize(ref.refName), ref.key).moveFieldOnModel;
   return {
@@ -118,10 +92,7 @@ const moveEntry = (ref: FormFieldRef, onChange: () => (value: unknown) => unknow
     },
     guard: (args) => {
       const length = rowsOf(ref).length;
-      const outside = ["from", "to"].filter((key) => {
-        const idx = args[key];
-        return typeof idx !== "number" || !Number.isInteger(idx) || idx < 0 || idx >= length;
-      });
+      const outside = ["from", "to"].filter((key) => isOutside(args[key], length));
       if (!outside.length) return true;
       return `${ref.key} has ${length} ${length === 1 ? "entry" : "entries"}, so ${outside.join(" and ")} is out of range.`;
     },
@@ -134,19 +105,7 @@ const moveEntry = (ref: FormFieldRef, onChange: () => (value: unknown) => unknow
   };
 };
 
-/**
- * Publishes the setter a form control is already holding, for exactly as long as the control is usable.
- *
- * The control is the declaration — the same rule the rest of the surface follows. A handler passed by reference
- * (`onChange={st.do.setTitleOnTask}`) names the field it writes, so the tool and the person press one function;
- * an inline arrow names nothing and publishes nothing, which is the existing `data-akan-action` rule with
- * consequences. Publishing from the form's subscription instead would offer every field of the model, including
- * the ones this template draws no control for.
- *
- * `disabled` withdraws the tool for the same reason the whole surface is declaration-only: a field the person
- * cannot type into is not one an agent may write in their place. It also closes the field to `fill<Model>Form`,
- * whose guard offers only what a control published — so one gate covers both writers.
- */
+/** Publishes a by-reference setter while its control is usable; `disabled` also closes it to `fill<Model>Form`. */
 export const useFieldTool = (onChange: unknown, { transform, disabled, sortable }: FieldToolOptions = {}) => {
   const surface = useSurface();
   const scope = useScopePath();
@@ -181,3 +140,162 @@ export const useFieldTool = (onChange: unknown, { transform, disabled, sortable
     };
   }, [surface, scopeKey, action, off, !!sortable]);
 };
+
+export interface FileFieldSource<T extends { id: string }> {
+  /** Read live on every call. Omitted publishes nothing. */
+  read?: () => readonly T[];
+  label: (file: T) => string;
+  /** The list's cap; nothing derives it from the field, so without it the limit is only the server's `Err`. */
+  max?: number;
+  min?: number;
+  disabled?: boolean;
+}
+
+const counted = (num: number) => `${num} ${num === 1 ? "file" : "files"}`;
+
+/** Lists offered files and sets the field by id; `add`/`sub` are the only way to keep files `read` does not offer. */
+export const useFileFieldTool = <T extends { id: string }>(
+  onChange: unknown,
+  { read, label, max, min, disabled }: FileFieldSource<T>,
+) => {
+  const surface = useSurface();
+  const scope = useScopePath();
+  const action = actionTagOf(onChange)?.action ?? null;
+  const live = useRef({ onChange, read, label });
+  live.current = { onChange, read, label };
+  const scopeKey = scope.join(".");
+  useEffect(() => {
+    if (!action || disabled || !read) return;
+    const ref = FormFields.ref(action);
+    const target = ref && FormFields.relationOf(ref.field);
+    
+    if (!ref || !target || FormFields.schema(ref.field)) return;
+    const many = ref.field.arrDepth > 0;
+    const nullable = !!ref.field.nullable && !many;
+    const names = formSetterNames(capitalize(ref.refName), ref.key);
+    const listName = FormFields.optionsToolName(ref.refName, ref.key);
+    const argName = many ? `${ref.key}Ids` : `${ref.key}Id`;
+    const id: JsonSchema = { type: "string" };
+    const ids: JsonSchema = { type: "array", items: id };
+    const files = () => live.current.read?.() ?? [];
+    const options = () => files().map((file) => ({ id: file.id, label: live.current.label(file) }));
+    const held = (value: unknown): T[] => {
+      const list = files();
+      const wanted = Array.isArray(value) ? value : [value];
+      return wanted.flatMap((one) => {
+        const found = list.find((file) => file.id === one);
+        return found ? [found] : [];
+      });
+    };
+    const pair = many && !!dispatcherOf(names.addFieldOnModel) && !!dispatcherOf(names.subFieldOnModel);
+    const guardIds = (name: string, value: unknown, allowNull: boolean): true | string => {
+      if (allowNull && (value === null || value === undefined)) return true;
+      const wanted = Array.isArray(value) ? value : [value];
+      if (!Array.isArray(value) && Array.isArray(wanted[0])) return `"${argName}" of ${name} takes ids, not a list.`;
+      const list = files();
+      const missing = wanted.filter((one) => typeof one !== "string" || !list.some((file) => file.id === one));
+      if (!missing.length) return true;
+      const route = pair
+        ? ` A file already on ${ref.key} may not be offered at all — it can only be removed by position, with ${names.subFieldOnModel}.`
+        : "";
+      if (!list.length)
+        return `No file is offered for ${ref.key} yet — one has to be attached or uploaded first.${route}`;
+      return `The ${ref.refName} form offers no file ${missing.join(", ")}. It offers: ${list
+        .map((file) => `${file.id} (${live.current.label(file)})`)
+        .join(", ")}.${route}`;
+    };
+    const guardCount = (after: number, subbing = false): true | string => {
+      if (max !== undefined && after > max)
+        return `${ref.key} holds at most ${counted(max)}, and that would make ${after}. Remove one with ${names.subFieldOnModel} first.`;
+      if (min !== undefined && after < min)
+        return `${ref.key} holds at least ${counted(min)}, and that would leave ${after}.${
+          subbing ? ` Replace one with ${names.addFieldOnModel} instead.` : ""
+        }`;
+      return true;
+    };
+    const capNote = [
+      max === undefined ? "" : `It holds at most ${counted(max)}.`,
+      min === undefined ? "" : `It holds at least ${counted(min)}.`,
+    ]
+      .filter(Boolean)
+      .join(" ");
+    const entries: ToolEntry[] = [
+      {
+        name: listName,
+        description: `List the files the ${ref.refName} form can put in ${ref.key}, by id. Pass an id from it to ${action}.`,
+        settle: false,
+        run: () => options(),
+      },
+      {
+        name: action,
+        description: [
+          many
+            ? `Replace ${ref.key} on the ${ref.refName} form with files from ${listName}, by id. Every file not named is dropped, including one this list does not offer — use ${names.addFieldOnModel} to keep what is already there.`
+            : `Set ${ref.key} on the ${ref.refName} form to one file from ${listName}, by id.`,
+          many ? capNote : "",
+        ]
+          .filter(Boolean)
+          .join(" "),
+        parameters: {
+          type: "object",
+          properties: { [argName]: many ? ids : id },
+          ...(nullable ? {} : { required: [argName] }),
+          additionalProperties: false,
+        },
+        guard: (args) => {
+          const named = guardIds(action, args[argName], nullable);
+          if (named !== true || !many) return named;
+          return guardCount(Array.isArray(args[argName]) ? (args[argName] as unknown[]).length : 0);
+        },
+        run: (args) => {
+          const picked = held(args[argName]);
+          return (live.current.onChange as (value: unknown) => unknown)(many ? picked : (picked[0] ?? null));
+        },
+      },
+    ];
+    if (pair)
+      entries.push(
+        {
+          name: names.addFieldOnModel,
+          description: [
+            `Append files from ${listName} to ${ref.key} on the ${ref.refName} form, by id. Leaves every file already there untouched.`,
+            capNote,
+          ]
+            .filter(Boolean)
+            .join(" "),
+          parameters: {
+            type: "object",
+            properties: { [argName]: ids },
+            required: [argName],
+            additionalProperties: false,
+          },
+          guard: (args) => {
+            const named = guardIds(names.addFieldOnModel, args[argName], false);
+            if (named !== true) return named;
+            const adding = Array.isArray(args[argName]) ? (args[argName] as unknown[]).length : 0;
+            return guardCount(rowsOf(ref).length + adding);
+          },
+          run: (args) => dispatcherOf(names.addFieldOnModel)?.(held(args[argName])),
+        },
+        {
+          name: names.subFieldOnModel,
+          description: `Remove files from ${ref.key} on the ${ref.refName} form by their positions, counting from 0.`,
+          parameters: idxsParameters,
+          guard: (args) => {
+            const idxs = args.idxs;
+            if (!Array.isArray(idxs) || !idxs.length)
+              return `"idxs" of ${names.subFieldOnModel} takes at least one position.`;
+            const length = rowsOf(ref).length;
+            const outside = idxs.filter((idx) => isOutside(idx, length));
+            if (outside.length) return `${ref.key} holds ${counted(length)}, so ${outside.join(", ")} is out of range.`;
+            return guardCount(length - new Set(idxs).size, true);
+          },
+          run: (args) => dispatcherOf(names.subFieldOnModel)?.(args.idxs),
+        },
+      );
+    const registered = entries.map((entry) => surface.registerTool(scope, entry));
+    return () => {
+      for (const unregister of registered) unregister();
+    };
+  }, [surface, scopeKey, action, disabled, !read, max, min]);
+};