akanjs 3.0.0-alpha.52 → 3.0.0-alpha.54

package/constant/fieldInfo.ts

@@ -505,6 +505,14 @@ export interface FieldObject {
   [key: string]: ConstantField;
 }
 
+/**
+ * `text` names a column in the plaintext search mirror, so a masked field carrying one would publish what it
+ * masks through search — the class build refuses it (`TextFieldPaths`). Removing the key from the option type
+ * moves that refusal to the call site, where the fix is obvious. Distributive because `FieldOption` is a union:
+ * a plain `Omit` over it would collapse to the keys the members share.
+ */
+type WithoutTextRole<Option> = Option extends unknown ? Omit<Option, "text"> : never;
+
 type FieldOption<
   Value extends ConstantFieldTypeInput,
   MapValue = Value extends MapConstructor ? typeof PrimitiveScalar : never,
@@ -568,7 +576,7 @@ field.hidden = <
   MapValue = Value extends MapConstructor ? typeof PrimitiveScalar : never,
 >(
   value: Value,
-  option: FieldOption<Value, MapValue> = {},
+  option: WithoutTextRole<FieldOption<Value, MapValue>> = {},
 ) =>
   new FieldInfo<"hidden", Value, ExplicitType, MapValue>(value, {
     ...option,
@@ -581,7 +589,7 @@ field.secret = <
   MapValue = Value extends MapConstructor ? typeof PrimitiveScalar : never,
 >(
   value: Value,
-  option: FieldOption<Value, MapValue> = {},
+  option: WithoutTextRole<FieldOption<Value, MapValue>> = {},
 ) =>
   new FieldInfo<"secret", Value | null, ExplicitType | null, MapValue>(value, {
     ...option,
@@ -596,7 +604,7 @@ export const resolve = <
   MapValue = Value extends MapConstructor ? typeof PrimitiveScalar : never,
 >(
   value: Value,
-  option: FieldOption<Value, MapValue> = {},
+  option: WithoutTextRole<FieldOption<Value, MapValue>> = {},
 ) =>
   new FieldInfo<"resolve", Value, ExplicitType, MapValue>(value, {
     ...option,

package/constant/textFieldPaths.ts

@@ -34,17 +34,23 @@ export class TextFieldPaths extends TextFieldPathSet {
   }
 
   #assertReachable(path: string, parent: ConstantField) {
-    if (parent.fieldType === "secret") throw new Error(`Text field "${path}" is under a secret field`);
-    if (parent.fieldType === "hidden") throw new Error(`Text field "${path}" is under a hidden field`);
-    if (parent.fieldType === "resolve") throw new Error(`Text field "${path}" is under a resolved field`);
+
+    const fix = `Drop the text role on "${path}", or leave the parent unmasked.`;
+    if (parent.fieldType === "secret") throw new Error(`Text field "${path}" is under a secret field. ${fix}`);
+    if (parent.fieldType === "hidden") throw new Error(`Text field "${path}" is under a hidden field. ${fix}`);
+    if (parent.fieldType === "resolve") throw new Error(`Text field "${path}" is under a resolved field. ${fix}`);
     if (parent.arrDepth > 1) throw new Error(`Text field "${path}" is under a nested array and cannot be indexed`);
   }
 
   #assertIndexable(key: string, role: TextFieldRole, field: ConstantField) {
-    
-    if (field.fieldType === "secret") throw new Error(`Text field "${key}" is secret and must not be indexed`);
-    if (field.fieldType === "hidden") throw new Error(`Text field "${key}" is hidden and must not be indexed`);
-    if (field.fieldType === "resolve") throw new Error(`Text field "${key}" is resolved and is absent from _doc`);
+
+    const masked = `The search mirror stores plaintext. Drop the text role on "${key}", or make the field plain.`;
+    if (field.fieldType === "secret")
+      throw new Error(`Text field "${key}" is secret and must not be indexed. ${masked}`);
+    if (field.fieldType === "hidden")
+      throw new Error(`Text field "${key}" is hidden and must not be indexed. ${masked}`);
+    if (field.fieldType === "resolve")
+      throw new Error(`Text field "${key}" is resolved and is absent from _doc. Drop the text role on "${key}".`);
     if (field.isMap) throw new Error(`Text field "${key}" is a Map and cannot be indexed`);
     if (field.arrDepth > 1) throw new Error(`Text field "${key}" is a nested array and cannot be indexed`);
     const modelRef = field.modelRef as unknown as Cls;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-alpha.52",
+  "version": "3.0.0-alpha.54",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/server/routeTreeBuilder.ts

@@ -191,6 +191,7 @@ export class RouteTreeBuilder {
     parentLayouts: RouteRender[] = [],
     parentPaths: string[] = [],
     parentHead?: ResolveHead,
+    parentOverrides: RouteRender[] = [],
   ): PathRoute[] {
     const parentPath = parentPaths.filter((p) => p !== "/").join("");
     const currentPathSegment = /^\/\(.*\)$/.test(route.path) ? "" : route.path;
@@ -201,8 +202,10 @@ export class RouteTreeBuilder {
     const currentLayout = !isRoot && route.renderLayout ? route.renderLayout : null;
 
     const currentOverrideRenders = route.renderOverrides ? [route.renderOverrides] : [];
-    const renderRootLayouts = [...parentRootLayouts, ...(currentRootLayout ? [currentRootLayout] : [])];
-    const renderLayouts = [...parentLayouts, ...currentOverrideRenders, ...(currentLayout ? [currentLayout] : [])];
+    const overrideRenders = [...parentOverrides, ...currentOverrideRenders];
+    const rootLayoutStack = [...parentRootLayouts, ...(currentRootLayout ? [currentRootLayout] : [])];
+    const renderRootLayouts = [...overrideRenders, ...rootLayoutStack];
+    const renderLayouts = [...parentLayouts, ...(currentLayout ? [currentLayout] : [])];
     if (route.renderLayout) {
       this.#fallbackRoutes.push({
         path: routePath,
@@ -213,11 +216,10 @@ export class RouteTreeBuilder {
     }
     const routeHead = RouteTreeBuilder.#composeHeadResolvers(route.renderLayout?.resolveHead, parentHead);
     const pageRenderRootLayouts =
-      route.pageIncludesOwnLayout === false && currentRootLayout ? parentRootLayouts : renderRootLayouts;
-    const pageRenderLayouts =
-      route.pageIncludesOwnLayout === false && currentLayout
-        ? [...parentLayouts, ...currentOverrideRenders]
-        : renderLayouts;
+      route.pageIncludesOwnLayout === false && currentRootLayout
+        ? [...overrideRenders, ...parentRootLayouts]
+        : renderRootLayouts;
+    const pageRenderLayouts = route.pageIncludesOwnLayout === false && currentLayout ? parentLayouts : renderLayouts;
     const pageHead = route.pageIncludesOwnLayout === false ? parentHead : routeHead;
     return [
       ...(route.renderPage
@@ -236,7 +238,7 @@ export class RouteTreeBuilder {
         : []),
       ...(route.children.size
         ? [...route.children.values()].flatMap((child) =>
-            this.#getPathRoutes(child, renderRootLayouts, renderLayouts, pathSegments, routeHead),
+            this.#getPathRoutes(child, rootLayoutStack, renderLayouts, pathSegments, routeHead, overrideRenders),
           )
         : []),
     ];

package/service/predefinedAdaptor/llm.adaptor.ts

@@ -48,7 +48,6 @@ export interface AgentWireTool {
   name: string;
   description?: string;
   parameters?: Record<string, unknown>;
-  effect?: string;
   needsConfirm?: boolean;
 }
 

package/store/agent/StoreSurfaceSource.ts

@@ -56,7 +56,6 @@ export class StoreSurfaceSource implements SurfaceSource {
         required: ["path"],
         additionalProperties: false,
       },
-      effect: "state",
       
       guard: (args) =>
         typeof args.path === "string" && args.path.startsWith("/") && !args.path.startsWith("//")
@@ -83,7 +82,6 @@ export class StoreSurfaceSource implements SurfaceSource {
       description:
         "Go back to the previous page in this session's history. Use it to undo a navigation; use navigate for a path.",
       parameters: { type: "object", properties: {}, additionalProperties: false },
-      effect: "state",
       
       guard: () => (router.canGoBack() ? true : "There is no previous page in this session's history."),
       run: async () => {
@@ -112,7 +110,7 @@ export class StoreSurfaceSource implements SurfaceSource {
         },
         additionalProperties: false,
       },
-      effect: "query",
+      settle: false,
       run: (args) => {
         const root = StoreSurfaceSource.#zoneRoot(viewKey);
         const section = typeof args.section === "string" ? args.section.trim() : "";
@@ -149,7 +147,6 @@ export class StoreSurfaceSource implements SurfaceSource {
         required: ["target"],
         additionalProperties: false,
       },
-      effect: "state",
       run: (args) => {
         const name = typeof args.target === "string" ? args.target.trim() : "";
         if (!name) throw new Error("highlight needs a target.");
@@ -182,7 +179,6 @@ export class StoreSurfaceSource implements SurfaceSource {
         required: ["key"],
         additionalProperties: false,
       },
-      effect: "state",
       run: (args: Record<string, unknown>) => {
         this.#bridge ??= AgentBridge.of();
         return this.#bridge.read(String(args.key), viewKey);

package/store/agentic/AgentValue.ts

@@ -0,0 +1,119 @@
+import {
+  type CLIENT_VALUE,
+  type Cls,
+  type Dayjs,
+  dayjs,
+  type EnumInstance,
+  type FIELD_META,
+  type GetStateObject,
+  isEnum,
+  PrimitiveRegistry,
+  type PrimitiveScalar,
+  type UnCls,
+} from "akanjs/base";
+import { type ConstantModelRef, type MaskModel, mask, maskFieldsOf } from "akanjs/constant";
+
+type AgentSingleType = typeof PrimitiveScalar | EnumInstance<string, any> | ConstantModelRef;
+
+/** What a readable declaration names its value as. One level of array, because a published value is one JSON shape. */
+export type AgentFieldType = AgentSingleType | AgentSingleType[];
+
+/**
+ * A model class resolves to its state object rather than its instance type, so a component may hand over either
+ * the hydrated document or the plain data copied out of one — masking reads the model that was named, not the
+ * class the value still carries.
+ *
+ * A scalar is recognised by `refName` and has to be matched before `FIELD_META`: `via.ts` augments the global
+ * `String`, `Boolean`, `Date` and `Map` constructors with `DatabaseConstantStatics`, so those four carry field
+ * metadata and would otherwise read as models. A model carries no `refName`, and `Map` — carrying neither — falls
+ * through to the model branch and is refused at declaration time instead.
+ */
+export type AgentValueOf<T> = T extends readonly (infer F)[]
+  ? AgentValueOf<F>[]
+  : T extends { refName: "Any" }
+    ? unknown
+    : T extends EnumInstance<string, infer V>
+      ? V
+      : T extends DateConstructor
+        ? Dayjs | Date | string
+        : T extends { refName: string; [CLIENT_VALUE]: infer V }
+          ? V
+          : T extends { [FIELD_META]: unknown }
+            ? GetStateObject<UnCls<T>>
+            : T extends { [CLIENT_VALUE]: infer V }
+              ? V
+              : unknown;
+
+type ValueKind = "any" | "date" | "scalar" | "enum" | "model";
+
+/**
+ * Turns a declared type into what an agent may read of a value of that type.
+ *
+ * The type is the whole declaration: it typechecks what the component hands over, and it decides how the value is
+ * rendered — a model class masks by that model, a `Date` leaves as an ISO string, a scalar passes. `Any` is the
+ * escape hatch and passes the value untouched, so a payload nobody modeled stays publishable and the caller owns
+ * whether it is JSON and whether it is worth its tokens.
+ */
+export class AgentValue {
+  static serialize(type: AgentFieldType, value: unknown): unknown {
+    const single = Array.isArray(type) ? type[0] : type;
+    if (Array.isArray(type) && Array.isArray(value)) return value.map((item) => AgentValue.#one(single, item));
+    return AgentValue.#one(single, value);
+  }
+
+  /**
+   * Reports an unreadable type the way `st.tool` reports an undescribable argument — on the console, and the
+   * declaration goes unpublished. Throwing would cost the route its server render over an agent-tooling mistake.
+   */
+  static publishable(owner: string, type: AgentFieldType): boolean {
+    try {
+      AgentValue.#kindOf(Array.isArray(type) ? type[0] : type);
+      return true;
+    } catch (error) {
+      console.error(`${owner} is not published: its type is ${error instanceof Error ? error.message : String(error)}`);
+      return false;
+    }
+  }
+
+  static #one(type: AgentSingleType, value: unknown): unknown {
+    if (value === null || value === undefined) return value;
+    switch (AgentValue.#kindOf(type)) {
+      case "date": {
+        const parsed = dayjs(value as string | number | Date);
+        return parsed.isValid() ? parsed.toISOString() : null;
+      }
+      case "model":
+        return mask(type as MaskModel, value);
+      default:
+        return value;
+    }
+  }
+
+  static #kindOf(type: AgentSingleType): ValueKind {
+    if (isEnum(type as Cls)) return "enum";
+    if (PrimitiveRegistry.has(type as unknown as Cls)) {
+      const refName = PrimitiveRegistry.getName(type as typeof PrimitiveScalar);
+      switch (refName) {
+        case "Any":
+          return "any";
+        case "Date":
+          return "date";
+        case "ID":
+        case "String":
+        case "Int":
+        case "Float":
+        case "Boolean":
+          return "scalar";
+        default:
+          throw new Error(`the scalar ${refName}, which an agent cannot read.`);
+      }
+    }
+    if (maskFieldsOf(type as MaskModel)) return "model";
+    throw new Error(`${AgentValue.#typeName(type)}, and a readable value is a scalar, an enum, a model, or Any.`);
+  }
+
+  static #typeName(type: AgentSingleType): string {
+    const named = type as { name?: string } | null | undefined;
+    return named?.name ? `the type ${named.name}` : `${String(type)}`;
+  }
+}

package/store/agentic/StExposeBuilder.ts

@@ -0,0 +1,47 @@
+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<{ name: string | null } | null>(null);
+    declared.current ??= {
+      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,85 @@
+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 {
+  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);
+    declared.current ??= {
+      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

@@ -13,7 +13,6 @@ import {
   AgenticSurface,
   type JsonSchema,
   type ToolConfirm,
-  type ToolEffect,
   type ToolGuard,
   useScopePath,
   useSurface,
@@ -23,15 +22,14 @@ import { tagAction } from "../actionTag";
 import { useEffect, useRef } from "../hooks";
 
 export interface StToolMeta {
-  desc?: string;
-  effect?: ToolEffect;
-  confirm?: ToolConfirm;
-  guard?: ToolGuard;
   /**
-   * Set by a component that renders once per row. It is only true when the row's id rides in an argument rather
-   * than in the closure, which is what makes every row's registration interchangeable.
+   * 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.
    */
-  shared?: boolean;
+  settle?: boolean;
+  confirm?: ToolConfirm;
+  guard?: ToolGuard;
 }
 
 interface StToolArg {
@@ -43,18 +41,19 @@ interface StToolArg {
 
 /** `oneOf` is the runtime half of `enumOf`: a value set only known once the component renders. */
 export interface StToolArgOption<V> {
-  optional?: boolean;
   oneOf?: readonly V[];
 }
 
 type ArgValue<T> = T extends EnumInstance<string, infer V> ? V : T extends { [CLIENT_VALUE]: infer V } ? V : never;
 
 /**
- * A component tool in the signal's vocabulary: `st.tool("x", { desc }).arg("id", ID).exec(fn)`.
+ * 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()` only
- * accumulates data; `.exec()` is the one hook, so the chain must complete in one unconditional statement.
+ * 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
@@ -62,21 +61,18 @@ type ArgValue<T> = T extends EnumInstance<string, infer V> ? V : T extends { [CL
  */
 export class StToolBuilder<Args extends unknown[] = []> {
   readonly #name: string | null;
+  readonly #desc: string;
   readonly #meta: StToolMeta;
   readonly #args: StToolArg[];
 
-  constructor(name: string | null, meta: StToolMeta = {}, 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> & { optional: true },
-  ): StToolBuilder<[...Args, V | null]>;
   arg<T extends ParamFieldType, const V extends ArgValue<T>>(
     name: string,
     type: T,
@@ -86,12 +82,35 @@ export class StToolBuilder<Args extends unknown[] = []> {
     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.#meta, [
+    return new StToolBuilder(published, this.#desc, this.#meta, [
       ...this.#args,
-      { name, type, optional: !!option.optional, ...(option.oneOf ? { oneOf: option.oneOf } : {}) },
+      { name, type, optional, ...(option.oneOf ? { oneOf: option.oneOf } : {}) },
     ]);
   }
 
@@ -101,8 +120,8 @@ export class StToolBuilder<Args extends unknown[] = []> {
     const scope = useScopePath();
     const live = useRef({ run, meta: this.#meta });
     live.current = { run, meta: this.#meta };
-    const declared = useRef<{ name: string | null; meta: StToolMeta; args: StToolArg[] } | null>(null);
-    declared.current ??= { name: this.#name, meta: this.#meta, args: this.#args };
+    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) => {
@@ -118,9 +137,8 @@ export class StToolBuilder<Args extends unknown[] = []> {
       if (!spec || !name) return;
       return surface.registerTool(scope, {
         name,
-        description: spec.meta.desc,
-        effect: spec.meta.effect,
-        ...(spec.meta.shared ? { shared: true } : {}),
+        description: spec.desc,
+        settle: spec.meta.settle,
         parameters: StToolBuilder.parametersOf(spec.args),
         
         ...(spec.meta.confirm === undefined && !name.startsWith("remove")

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);
+  }
+}