akanjs 3.0.0-alpha.7 → 3.0.0-alpha.71

package/store/agentic/StToolBuilder.ts

@@ -0,0 +1,279 @@
+import {
+  type CLIENT_VALUE,
+  type Cls,
+  dayjs,
+  type EnumInstance,
+  Int,
+  isEnum,
+  PrimitiveRegistry,
+  type PrimitiveScalar,
+} from "akanjs/base";
+import type { ParamFieldType } from "akanjs/constant";
+import {
+  AgenticSurface,
+  type JsonSchema,
+  type ToolConfirm,
+  type ToolGuard,
+  useScopePath,
+  useSurface,
+} from "../../vendor/use-agentic";
+import { tagAction } from "../actionTag";
+
+import { useEffect, useRef } from "../hooks";
+
+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.
+   */
+  settle?: boolean;
+  confirm?: ToolConfirm;
+  guard?: ToolGuard;
+}
+
+interface StToolArg {
+  name: string;
+  type: ParamFieldType;
+  optional: boolean;
+  oneOf?: readonly (string | number)[];
+}
+
+/** `oneOf` is the runtime half of `enumOf`: a value set only known once the component renders. */
+export interface StToolArgOption<V> {
+  oneOf?: readonly V[];
+}
+
+type ArgValue<T> = T extends EnumInstance<string, infer V> ? V : T extends { [CLIENT_VALUE]: infer V } ? V : never;
+
+/**
+ * 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.
+ */
+export class StToolBuilder<Args extends unknown[] = []> {
+  readonly #name: string | null;
+  readonly #desc: string;
+  readonly #meta: StToolMeta;
+  readonly #args: StToolArg[];
+
+  constructor(name: string | null, desc: string, meta: StToolMeta = {}, args: StToolArg[] = []) {
+    this.#name = name;
+    this.#desc = desc;
+    this.#meta = meta;
+    this.#args = args;
+  }
+
+  arg<T extends ParamFieldType>(name: string, type: T): StToolBuilder<[...Args, ArgValue<T>]>;
+  arg<T extends ParamFieldType, const V extends ArgValue<T>>(
+    name: string,
+    type: T,
+    option: StToolArgOption<V>,
+  ): StToolBuilder<[...Args, V]>;
+  arg<T extends ParamFieldType>(
+    name: string,
+    type: T,
+    option: StToolArgOption<ArgValue<T>> = {},
+  ): StToolBuilder<[...Args, ArgValue<T>]> {
+    return this.#push(name, type, false, option) as StToolBuilder<[...Args, ArgValue<T>]>;
+  }
+
+  opt<T extends ParamFieldType>(name: string, type: T): StToolBuilder<[...Args, ArgValue<T> | null]>;
+  opt<T extends ParamFieldType, const V extends ArgValue<T>>(
+    name: string,
+    type: T,
+    option: StToolArgOption<V>,
+  ): StToolBuilder<[...Args, V | null]>;
+  opt<T extends ParamFieldType>(
+    name: string,
+    type: T,
+    option: StToolArgOption<ArgValue<T>> = {},
+  ): StToolBuilder<[...Args, ArgValue<T> | null]> {
+    return this.#push(name, type, true, option);
+  }
+
+  #push<T extends ParamFieldType>(
+    name: string,
+    type: T,
+    optional: boolean,
+    option: StToolArgOption<ArgValue<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,
+      { name, type, optional, ...(option.oneOf ? { oneOf: option.oneOf } : {}) },
+    ]);
+  }
+
+  /** The only hook in the chain. `run`, `guard`, and `confirm` stay always-latest; the declaration is mount-static. */
+  exec(run: (...args: Args) => unknown): (...args: Args) => Promise<void> {
+    const surface = useSurface();
+    const scope = useScopePath();
+    const live = useRef({ run, meta: this.#meta });
+    live.current = { run, meta: this.#meta };
+    const declared = useRef<{ name: string | null; desc: string; meta: StToolMeta; args: StToolArg[] } | null>(null);
+    declared.current ??= { name: this.#name, desc: this.#desc, meta: this.#meta, args: this.#args };
+    const callable = useRef<((...args: Args) => Promise<void>) | null>(null);
+    if (!callable.current) {
+      const call = async (...args: Args) => {
+        await live.current.run(...args);
+      };
+      
+      callable.current = this.#name ? tagAction(call, { action: AgenticSurface.fullName(scope, this.#name) }) : call;
+    }
+    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),
+        
+        ...(spec.meta.confirm === undefined && !name.startsWith("remove")
+          ? {}
+          : {
+              confirm: (args: Record<string, unknown>) => {
+                const confirm = live.current.meta.confirm ?? name.startsWith("remove");
+                return typeof confirm === "function" ? confirm(args) : confirm;
+              },
+            }),
+        ...(spec.meta.guard === undefined
+          ? {}
+          : { guard: (args: Record<string, unknown>) => live.current.meta.guard?.(args) ?? true }),
+        run: (named) => live.current.run(...(StToolBuilder.positionalOf(name, spec.args, named) as Args)),
+      });
+    }, [surface, scopeKey, this.#name]);
+    return callable.current;
+  }
+
+  static parametersOf(args: StToolArg[]): JsonSchema | undefined {
+    if (!args.length) return undefined;
+    const required = args.filter((arg) => !arg.optional).map((arg) => arg.name);
+    return {
+      type: "object",
+      properties: Object.fromEntries(args.map((arg) => [arg.name, StToolBuilder.#argSchemaOf(arg)])),
+      ...(required.length ? { required } : {}),
+      additionalProperties: false,
+    };
+  }
+
+  static #argSchemaOf(arg: StToolArg): JsonSchema {
+    const schema = StToolBuilder.schemaOf(arg.type);
+    return arg.oneOf ? { ...schema, enum: [...arg.oneOf] } : schema;
+  }
+
+  static #describable(toolName: string, argName: string, type: ParamFieldType): boolean {
+    try {
+      StToolBuilder.schemaOf(type);
+      return true;
+    } catch (error) {
+      console.error(
+        `st.tool("${toolName}") is not published: its "${argName}" argument is ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+      return false;
+    }
+  }
+
+  /** Scalars and enums only — the value arrives as JSON from a model, so a class instance has no way in. */
+  static schemaOf(type: ParamFieldType): JsonSchema {
+    if (isEnum(type as Cls)) {
+      const enumRef = type as EnumInstance;
+      const kind = enumRef.type === String ? "string" : enumRef.type === Int ? "integer" : "number";
+      return { type: kind, enum: [...enumRef.values] };
+    }
+    const scalar = type as typeof PrimitiveScalar;
+    if (!PrimitiveRegistry.has(scalar as unknown as Cls))
+      throw new Error(`${StToolBuilder.#typeName(type)}, and st.tool takes scalar and enum arguments only.`);
+    switch (PrimitiveRegistry.getName(scalar)) {
+      case "ID":
+      case "String":
+        return { type: "string" };
+      case "Int":
+        return { type: "integer" };
+      case "Float":
+        return { type: "number" };
+      case "Boolean":
+        return { type: "boolean" };
+      case "Date":
+        return { type: "string", format: "date-time" };
+      default:
+        throw new Error(`the scalar ${PrimitiveRegistry.getName(scalar)}, which st.tool cannot describe.`);
+    }
+  }
+
+  static #typeName(type: ParamFieldType): string {
+    const named = type as { name?: string } | null | undefined;
+    return named?.name ? `the type ${named.name}` : `${String(type)}`;
+  }
+
+  static positionalOf(toolName: string, args: StToolArg[], named: Record<string, unknown>): unknown[] {
+    return args.map((arg) => {
+      const value = named[arg.name];
+      if (value === undefined || value === null) {
+        if (arg.optional) return null;
+        throw new Error(`Missing argument "${arg.name}" for ${toolName}.`);
+      }
+      return StToolBuilder.checkedValue(toolName, arg.name, arg.type, value, arg.oneOf);
+    });
+  }
+
+  /** What `AgentBridge` does for endpoint arguments, for a component tool's own — nothing on the wire enforces the published schema. */
+  static checkedValue(
+    toolName: string,
+    argName: string,
+    type: ParamFieldType,
+    value: unknown,
+    oneOf?: readonly (string | number)[],
+  ): unknown {
+    const checked = StToolBuilder.#checkedScalar(toolName, argName, type, value);
+    if (oneOf && !oneOf.includes(checked as string | number))
+      throw new Error(`Argument "${argName}" of ${toolName} must be one of: ${oneOf.join(", ")}.`);
+    return checked;
+  }
+
+  static #checkedScalar(toolName: string, argName: string, type: ParamFieldType, value: unknown): unknown {
+    if (isEnum(type as Cls)) {
+      const enumRef = type as EnumInstance;
+      if (!enumRef.values.includes(value as never))
+        throw new Error(`Argument "${argName}" of ${toolName} must be one of: ${[...enumRef.values].join(", ")}.`);
+      return value;
+    }
+    switch (PrimitiveRegistry.getName(type as typeof PrimitiveScalar)) {
+      case "ID":
+      case "String":
+        if (typeof value !== "string") throw new Error(`Argument "${argName}" of ${toolName} must be a string.`);
+        return value;
+      case "Int":
+        if (!Number.isInteger(value)) throw new Error(`Argument "${argName}" of ${toolName} must be a whole number.`);
+        return value;
+      case "Float":
+        if (typeof value !== "number" || !Number.isFinite(value))
+          throw new Error(`Argument "${argName}" of ${toolName} must be a finite number.`);
+        return value;
+      case "Boolean":
+        if (typeof value !== "boolean") throw new Error(`Argument "${argName}" of ${toolName} must be a boolean.`);
+        return value;
+      case "Date": {
+        const parsed = dayjs(value as string | number | Date);
+        if (!parsed.isValid()) throw new Error(`Argument "${argName}" of ${toolName} must be an ISO 8601 date string.`);
+        return parsed;
+      }
+      default:
+        return value;
+    }
+  }
+}

package/store/agentic/StToolDraft.ts

@@ -0,0 +1,22 @@
+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;
+
+  constructor(name: string | null, meta: StToolMeta = {}) {
+    this.#name = name;
+    this.#meta = meta;
+  }
+
+  desc(text: string): StToolBuilder {
+    return new StToolBuilder(this.#name, text, this.#meta);
+  }
+}

package/store/agentic/attachAgentic.ts

@@ -0,0 +1,33 @@
+import type { AgentFieldType } from "./AgentValue";
+import type { StExposeMeta } from "./StExposeBuilder";
+import { StExposeDraft } from "./StExposeDraft";
+import type { StStateMeta } from "./StStateBuilder";
+import { StStateDraft } from "./StStateDraft";
+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.
+   */
+  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.
+   */
+  tool: (name: string | null, meta?: StToolMeta) => StToolDraft;
+}
+
+const stAgentic: StAgentic = {
+  useState: (name, type, meta) => new StStateDraft(name, type, meta),
+  expose: (name, type, meta) => new StExposeDraft(name, type, meta),
+  tool: (name, meta) => new StToolDraft(name, meta),
+};
+
+/** Idempotent — `StoreRegistry.build` runs once per merged root, always onto the one instance. */
+export const attachAgentic = <T extends object>(instance: T): T & StAgentic => Object.assign(instance, stAgentic);

package/store/agentic/formFields.ts

@@ -0,0 +1,194 @@
+import { type Cls, FIELD_META, PrimitiveRegistry } from "akanjs/base";
+import { capitalize } from "akanjs/common";
+import { type ConstantField, ConstantRegistry, type ParamFieldType } from "akanjs/constant";
+import type { JsonSchema } from "../../vendor/use-agentic";
+import { formSetterNames } from "../formSetterNames";
+import { StToolBuilder } from "./StToolBuilder";
+
+export interface FormFieldRef {
+  refName: string;
+  key: string;
+  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;
+  }
+
+  static #buildIndex() {
+    const index = new Map<string, FormFieldRef>();
+    for (const refName of ConstantRegistry.database.keys()) {
+      const className = capitalize(refName);
+      for (const [key, field] of Object.entries(
+        ConstantRegistry.getDatabase(refName).full[FIELD_META] as { [key: string]: ConstantField },
+      ))
+        index.set(formSetterNames(className, key).setFieldOnModel, { refName, key, field });
+    }
+    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);
+    const inputFields = model.input[FIELD_META] as { [key: string]: ConstantField };
+    return Object.entries(model.full[FIELD_META] as { [key: string]: ConstantField })
+      .filter(([key]) => key in inputFields && !baseFields.has(key))
+      .flatMap(([key, field]) => {
+        const schema = FormFields.schema(field);
+        return schema ? [{ key, action: formSetterNames(className, key).setFieldOnModel, field, schema }] : [];
+      });
+  }
+
+  /**
+   * 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.
+   */
+  static schema(field: ConstantField, depth = 0): JsonSchema | null {
+    if (field.fieldType !== "property" || depth > MAX_DEPTH) return null;
+    const leaf = FormFields.#leafSchema(field, depth);
+    if (!leaf) return null;
+    let schema = leaf;
+    for (let arr = 0; arr < field.arrDepth; arr += 1) schema = { type: "array", items: schema };
+    return schema;
+  }
+
+  static #leafSchema(field: ConstantField, depth: number): JsonSchema | null {
+    const modelRef = field.modelRef as unknown as Cls;
+    if (field.enum) return StToolBuilder.schemaOf(field.enum as unknown as ParamFieldType);
+    if ((modelRef as unknown) === Map) {
+      const value = field.of ? FormFields.#ofSchema(field) : null;
+      return value ? { type: "object", additionalProperties: value } : null;
+    }
+    if (PrimitiveRegistry.has(modelRef)) {
+      try {
+        return StToolBuilder.schemaOf(modelRef as unknown as ParamFieldType);
+      } catch {
+        
+        return null;
+      }
+    }
+    if (!ConstantRegistry.isScalar(modelRef)) return null;
+    return FormFields.#objectSchema(modelRef, depth);
+  }
+
+  static #ofSchema(field: ConstantField): JsonSchema | null {
+    try {
+      return StToolBuilder.schemaOf(field.of as unknown as ParamFieldType);
+    } catch {
+      return null;
+    }
+  }
+
+  static #objectSchema(modelRef: Cls, depth: number): JsonSchema | null {
+    const entries = Object.entries(
+      (modelRef as unknown as { [key: symbol]: unknown })[FIELD_META] as {
+        [key: string]: ConstantField;
+      },
+    ).flatMap(([key, inner]) => {
+      const schema = FormFields.schema(inner, depth + 1);
+      return schema ? [[key, schema] as const] : [];
+    });
+    if (!entries.length) return null;
+    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.
+   */
+  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.`);
+      return null;
+    }
+    if (field.arrDepth > 0) return FormFields.#checkedArray(action, path, field, value, depth);
+    const modelRef = field.modelRef as unknown as Cls;
+    if ((modelRef as unknown) === Map) return FormFields.#checkedMap(action, path, field, value);
+    if (field.enum || PrimitiveRegistry.has(modelRef))
+      return StToolBuilder.checkedValue(action, path, (field.enum ?? modelRef) as unknown as ParamFieldType, value);
+    return FormFields.#checkedObject(action, path, modelRef, value, depth);
+  }
+
+  static #checkedArray(action: string, path: string, field: ConstantField, value: unknown, depth: number) {
+    if (!Array.isArray(value)) throw new Error(`"${path}" of ${action} must be an array.`);
+    const inner = Object.assign(Object.create(Object.getPrototypeOf(field) as object), field, {
+      arrDepth: field.arrDepth - 1,
+      nullable: false,
+    }) as ConstantField;
+    return value.map((item, idx) => FormFields.checked(action, `${path}[${idx}]`, inner, item, depth));
+  }
+
+  static #checkedMap(action: string, path: string, field: ConstantField, value: unknown) {
+    if (!FormFields.#isPlainObject(value)) throw new Error(`"${path}" of ${action} must be an object.`);
+    return Object.fromEntries(
+      Object.entries(value).map(([key, item]) => [
+        key,
+        StToolBuilder.checkedValue(action, `${path}.${key}`, field.of as unknown as ParamFieldType, item),
+      ]),
+    );
+  }
+
+  static #checkedObject(action: string, path: string, modelRef: Cls, value: unknown, depth: number) {
+    if (!FormFields.#isPlainObject(value)) throw new Error(`"${path}" of ${action} must be an object.`);
+    const fields = (modelRef as unknown as { [key: symbol]: unknown })[FIELD_META] as {
+      [key: string]: ConstantField;
+    };
+    const entries = Object.entries(value).map(([key, item]) => {
+      const inner = fields[key];
+      if (!inner || !FormFields.schema(inner, depth + 1))
+        throw new Error(`"${path}" of ${action} has no field "${key}".`);
+      return [key, FormFields.checked(action, `${path}.${key}`, inner, item, depth + 1)] as const;
+    });
+    return Object.fromEntries(entries);
+  }
+
+  static #isPlainObject(value: unknown): value is { [key: string]: unknown } {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+  }
+
+  /** A field no annotated control can ever name: its rows are written through `writeOn<Model>(path, value)`. */
+  static isComposite(field: ConstantField) {
+    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.
+   */
+  static rowModelOf(field: ConstantField) {
+    return field.arrDepth > 0 ? FormFields.#scalarModel(field) : null;
+  }
+
+  static #scalarModel(field: ConstantField) {
+    const modelRef = field.modelRef as unknown as Cls;
+    if (field.enum || PrimitiveRegistry.has(modelRef)) return null;
+    return ConstantRegistry.isScalar(modelRef) ? modelRef : null;
+  }
+}

package/store/agentic/index.ts

@@ -0,0 +1,12 @@
+export * from "./AgentValue";
+export * from "./attachAgentic";
+export * from "./formFields";
+export * from "./StExposeBuilder";
+export * from "./StExposeDraft";
+export * from "./StStateBuilder";
+export * from "./StStateDraft";
+export * from "./StToolBuilder";
+export * from "./StToolDraft";
+export * from "./useFieldTool";
+export * from "./useFormTools";
+export * from "./useRelationFieldTool";