akanjs 3.0.0-alpha.8 → 3.0.0-alpha.80

package/store/agentic/StExposeBuilder.ts

@@ -0,0 +1,50 @@
+import { useAgentResource } from "../../vendor/use-agentic";
+
+import { useRef } from "../hooks";
+import { type AgentFieldType, AgentValue, type AgentValueOf } from "./AgentValue";
+
+export interface StExposeMeta {
+  /** `false` keeps the key out of post-call diff reports — for values that change on their own every second. */
+  report?: boolean;
+}
+
+/**
+ * A read-only value past its description, waiting for the value itself. `.value()` is the one hook.
+ *
+ * The declared type is what makes the read safe: it typechecks what the component hands over and it decides how
+ * the value is rendered, so a model's `hidden` and `secret` fields are stripped by the model that was named
+ * rather than by whatever class the value still happens to carry.
+ */
+export class StExposeBuilder<T extends AgentFieldType> {
+  readonly #name: string | null;
+  readonly #type: T;
+  readonly #desc: string;
+  readonly #meta: StExposeMeta;
+
+  constructor(name: string | null, type: T, desc: string, meta: StExposeMeta = {}) {
+    this.#name = name;
+    this.#type = type;
+    this.#desc = desc;
+    this.#meta = meta;
+  }
+
+  /**
+   * A thunk is read when the agent reads, which is the difference that matters for a value assembled out of a ref
+   * the children fill in after this render — computing it here would publish whatever was there before they ran.
+   */
+  value(value: AgentValueOf<T> | (() => AgentValueOf<T>) | null | undefined): void {
+    const declared = useRef<{ key: string | null; name: string | null } | null>(null);
+
+    if (declared.current?.key !== this.#name)
+      declared.current = {
+        key: this.#name,
+        name: this.#name && AgentValue.publishable(`st.expose("${this.#name}")`, this.#type) ? this.#name : null,
+      };
+    useAgentResource(declared.current.name, value, {
+      description: this.#desc,
+      report: this.#meta.report,
+      serialize: (current) =>
+        AgentValue.serialize(this.#type, typeof current === "function" ? (current as () => unknown)() : current),
+    });
+  }
+}

package/store/agentic/StExposeDraft.ts

@@ -0,0 +1,24 @@
+import type { AgentFieldType } from "./AgentValue";
+import { StExposeBuilder, type StExposeMeta } from "./StExposeBuilder";
+
+/**
+ * A readable value before it has said what it is: `st.expose("x", ID).desc("…")`.
+ *
+ * A falsy name declares nothing and publishes nothing, so a component whose publication is conditional keeps a
+ * constant hook count instead of branching around the chain.
+ */
+export class StExposeDraft<T extends AgentFieldType> {
+  readonly #name: string | null;
+  readonly #type: T;
+  readonly #meta: StExposeMeta;
+
+  constructor(name: string | null, type: T, meta: StExposeMeta = {}) {
+    this.#name = name;
+    this.#type = type;
+    this.#meta = meta;
+  }
+
+  desc(text: string): StExposeBuilder<T> {
+    return new StExposeBuilder(this.#name, this.#type, text, this.#meta);
+  }
+}

package/store/agentic/StStateBuilder.ts

@@ -0,0 +1,90 @@
+import { capitalize } from "akanjs/common";
+import type { ParamFieldType } from "akanjs/constant";
+import type { Dispatch, SetStateAction } from "react";
+import { type JsonSchema, useAgentState } from "../../vendor/use-agentic";
+
+import { useRef } from "../hooks";
+import { type AgentFieldType, AgentValue, type AgentValueOf } from "./AgentValue";
+import { StToolBuilder } from "./StToolBuilder";
+
+export interface StStateMeta {
+  /** `false` keeps the key out of post-call diff reports — for values that change on their own every second. */
+  report?: boolean;
+  /** Publishes a `set<Name>` tool writing the type this state declares. Read-only without it. */
+  set?: boolean;
+}
+
+interface StStateDeclaration {
+  /** The name as written this render, which is what says whether the resolution below still applies. */
+  key: string | null;
+  name: string | null;
+  set: { schema: JsonSchema; type: ParamFieldType } | null;
+}
+
+/**
+ * Local state past its description, waiting for its initial value. `.init()` is the one hook and returns what
+ * `useState` returns.
+ *
+ * The declared type does both halves: it renders the read, and — with `set` — it is the schema of the setter tool
+ * an agent writes through. A type nothing can describe costs the write, not the read and not the render.
+ */
+export class StStateBuilder<T extends AgentFieldType> {
+  readonly #name: string | null;
+  readonly #type: T;
+  readonly #desc: string;
+  readonly #meta: StStateMeta;
+
+  constructor(name: string | null, type: T, desc: string, meta: StStateMeta = {}) {
+    this.#name = name;
+    this.#type = type;
+    this.#desc = desc;
+    this.#meta = meta;
+  }
+
+  init(
+    initial: AgentValueOf<T> | (() => AgentValueOf<T>),
+  ): [AgentValueOf<T>, Dispatch<SetStateAction<AgentValueOf<T>>>];
+  init(
+    initial: AgentValueOf<T> | null | (() => AgentValueOf<T> | null),
+  ): [AgentValueOf<T> | null, Dispatch<SetStateAction<AgentValueOf<T> | null>>];
+
+  init(initial: AgentValueOf<T> | null | (() => AgentValueOf<T> | null)): unknown {
+    type Value = AgentValueOf<T> | null;
+    const name = this.#name;
+    const type = this.#type;
+    const declared = useRef<StStateDeclaration | null>(null);
+
+    if (declared.current?.key !== name)
+      declared.current = {
+        key: name,
+        name: name && AgentValue.publishable(`st.useState("${name}")`, type) ? name : null,
+        set: name && this.#meta.set ? StStateBuilder.#writable(name, type) : null,
+      };
+    const { set } = declared.current;
+    return useAgentState<Value>(declared.current.name, initial, {
+      description: this.#desc,
+      report: this.#meta.report,
+      serialize: (value) => AgentValue.serialize(type, value),
+      ...(set
+        ? {
+            set: set.schema,
+            parse: (value) =>
+              StToolBuilder.checkedValue(`set${capitalize(name ?? "")}`, "value", set.type, value) as Value,
+          }
+        : {}),
+    });
+  }
+
+  /** A `set` an agent could only call wrong leaves the key readable — the same trade `st.tool`'s `.arg` makes. */
+  static #writable(name: string, type: AgentFieldType): StStateDeclaration["set"] {
+    const scalar = type as unknown as ParamFieldType;
+    try {
+      return { schema: StToolBuilder.schemaOf(scalar), type: scalar };
+    } catch (error) {
+      console.error(
+        `st.useState("${name}") stays read-only: writing ${error instanceof Error ? error.message : String(error)}`,
+      );
+      return null;
+    }
+  }
+}

package/store/agentic/StStateDraft.ts

@@ -0,0 +1,23 @@
+import type { AgentFieldType } from "./AgentValue";
+import { StStateBuilder, type StStateMeta } from "./StStateBuilder";
+
+/**
+ * Local state before it has said what it is: `st.useState("tab", String, { set: true }).desc("…")`.
+ *
+ * A falsy name keeps the state and publishes nothing, so a conditional surface never changes the hook count.
+ */
+export class StStateDraft<T extends AgentFieldType> {
+  readonly #name: string | null;
+  readonly #type: T;
+  readonly #meta: StStateMeta;
+
+  constructor(name: string | null, type: T, meta: StStateMeta = {}) {
+    this.#name = name;
+    this.#type = type;
+    this.#meta = meta;
+  }
+
+  desc(text: string): StStateBuilder<T> {
+    return new StStateBuilder(this.#name, this.#type, text, this.#meta);
+  }
+}

package/store/agentic/StToolBuilder.ts

@@ -0,0 +1,293 @@
+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 || null;
+    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, 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.
+   */
+  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);
+    if (declared.current?.name !== this.#name)
+      declared.current = { name: this.#name, desc: this.#desc, meta: this.#meta, args: this.#args };
+    const callable = useRef<{ name: string | null; fn: (...args: Args) => Promise<void> } | null>(null);
+    if (callable.current?.name !== this.#name) {
+      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,
+      };
+    }
+    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.fn;
+  }
+
+  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);