akanjs 3.0.0-alpha.2 → 3.0.0-alpha.21

package/signal/slice.ts

@@ -1,9 +1,9 @@
-import { Any, type Assign, type Cls, type MergeAllKeyOfObjects, SLICE_DICT_SHAPE, SLICE_META } from "akanjs/base";
+import { Any, type Assign, type MergeAllKeyOfObjects, SLICE_DICT_SHAPE, SLICE_META } from "akanjs/base";
 import { applyMixins } from "akanjs/common";
 import type { DocumentModel, QueryOf } from "akanjs/constant";
 import type { FilterInstance } from "akanjs/document";
 import { type Adaptor, type AdaptorCls, dangerouslyAdapt, type ServiceModel } from "akanjs/service";
-import type { Guard, GuardCls } from "./guard";
+import type { GuardCls } from "./guard";
 import {
   buildSlice,
   type SliceBuilder,
@@ -42,12 +42,12 @@ export type SliceCls<
 
 interface RootSliceOption {
   guards?: {
-    root?: Cls<Guard> | Cls<Guard>[];
-    get?: Cls<Guard> | Cls<Guard>[];
-    cru?: Cls<Guard> | Cls<Guard>[];
-    create?: Cls<Guard> | Cls<Guard>[];
-    update?: Cls<Guard> | Cls<Guard>[];
-    remove?: Cls<Guard> | Cls<Guard>[];
+    root?: GuardCls | GuardCls[];
+    get?: GuardCls | GuardCls[];
+    cru?: GuardCls | GuardCls[];
+    create?: GuardCls | GuardCls[];
+    update?: GuardCls | GuardCls[];
+    remove?: GuardCls | GuardCls[];
   };
   prefix?: string;
 }
@@ -129,7 +129,7 @@ export function slice<
     srv.cnst.insight,
     srv.db.filter,
   );
-  const toGuards = (guard?: Cls<Guard> | Cls<Guard>[]) => (guard ? (Array.isArray(guard) ? guard : [guard]) : []);
+  const toGuards = (guard?: GuardCls | GuardCls[]) => (guard ? (Array.isArray(guard) ? guard : [guard]) : []);
   const rootGuards = toGuards(option.guards?.root);
   const getGuards = toGuards(option.guards?.get);
   const cruGuards = toGuards(option.guards?.cru);

package/signal/types.ts

@@ -114,7 +114,7 @@ export interface SerializedArg {
   enum?: string;
 }
 export interface SerializedEndpoint extends SerializedSignalOption {
-  type: "query" | "mutation" | "pubsub" | "message";
+  type: "query" | "mutation" | "pubsub" | "message" | "prompt";
   returns: SerializedReturns;
 }
 export interface SerializedFilter {

package/store/action.ts

@@ -5,7 +5,6 @@ import {
   type FetchPolicy,
   isQueryEqual,
   Logger,
-  lowerlize,
   pathSet,
   resolveFileUploadCapability,
 } from "akanjs/common";
@@ -33,18 +32,12 @@ import type {
   SlceDbSort,
   SliceCls,
 } from "akanjs/signal";
+import { tagAction } from "./actionTag";
+import { formSetterNames } from "./formSetterNames";
+import type { SliceActionKey } from "./sliceRole";
 import type { SliceStateKey } from "./state";
 import type { SetGet, StoreSliceArgs, StoreSliceMap, StoreSliceSuffixCap } from "./types";
 
-type SliceActionKey =
-  | "initModel"
-  | "refreshModel"
-  | "selectModel"
-  | "setPageOfModel"
-  | "addPageOfModel"
-  | "setLimitOfModel"
-  | "setQueryArgsOfModel"
-  | "setSortOfModel";
 type _SliceMap<S extends SliceCls> = StoreSliceMap<S>;
 type _ActionRefName<S extends SliceCls> = SlceCnstRefName<S>;
 type _ActionCap<S extends SliceCls> = SlceCnstCapitalizedRefName<S>;
@@ -311,16 +304,7 @@ export const makeFormSetter = (refName: string, fetch: FetchProxy<any>) => {
     },
   };
   const fieldSetAction = Object.entries(modelRef[FIELD_META]).reduce((acc, [key, field]) => {
-    const [fieldKeyName, classKeyName] = [lowerlize(key), capitalize(key)];
-    const namesOfField = {
-      field: fieldKeyName,
-      Field: classKeyName,
-      setFieldOnModel: `set${classKeyName}On${className}`,
-      addFieldOnModel: `add${classKeyName}On${className}`,
-      subFieldOnModel: `sub${classKeyName}On${className}`,
-      addOrSubFieldOnModel: `addOrSub${classKeyName}On${className}`,
-      uploadFieldOnModel: `upload${classKeyName}On${className}`,
-    };
+    const namesOfField = formSetterNames(className, key);
     const singleFieldSetAction = {
       [namesOfField.setFieldOnModel]: function (this: SetGet, value: any | null) {
         this.set((state: { [key: string]: any }) => {
@@ -374,7 +358,7 @@ export const makeFormSetter = (refName: string, fetch: FetchProxy<any>) => {
             },
           }
         : {}),
-      ...(field.isClass && !!fileUploadRefName && ConstantRegistry.getRefName(field.modelRef) === fileUploadRefName
+      ...(field.isClass && fileUploadRefName && ConstantRegistry.getRefName(field.modelRef) === fileUploadRefName
         ? {
             [namesOfField.uploadFieldOnModel]: async function (
               this: SetGet,
@@ -427,6 +411,11 @@ export const makeFormSetter = (refName: string, fetch: FetchProxy<any>) => {
           }
         : {}),
     };
+
+    tagAction(singleFieldSetAction[namesOfField.setFieldOnModel] as (...args: never[]) => unknown, {
+      action: namesOfField.setFieldOnModel,
+      state: `${names.modelForm}.${namesOfField.field}`,
+    });
     return Object.assign(acc, singleFieldSetAction);
   }, {});
   return Object.assign(fieldSetAction, baseSetAction);
@@ -751,7 +740,7 @@ export const makeActions = (refName: string, slice: { [key: string]: SerializedS
       const id = typeof modelOrId === "string" ? modelOrId : modelOrId.id;
       this.set({ [names.modelFormLoading]: id, [names.modelModal]: modal ?? "edit" });
       const model = await (fetch[names.model] as (...args: any[]) => Promise<Full>)(id, { onError });
-      const modelForm = deepObjectify<Input>(model as unknown as Input);
+      const modelForm = immerify(modelRef, deepObjectify<Input>(model as unknown as Input) as object) as Input;
       this.set({
         [names.model]: model,
         [names.modelFormLoading]: false,

package/store/actionTag.ts

@@ -0,0 +1,33 @@
+import { ACTION_TAG } from "akanjs/base";
+
+/** Which module declared an action. The dictionary node its words live in is named after it. */
+export interface ActionOwner {
+  refName: string;
+}
+
+export interface ActionTag {
+  /** The `st.do` key this function is. */
+  action: string;
+  /** The state path it writes, when it writes exactly one — `userForm.name` for a field setter. */
+  state?: string;
+}
+
+/**
+ * Marks a dispatcher with what it does, so a component handed one by reference can say so in the DOM.
+ *
+ * `onChange={st.do.setNameOnUser}` is the house form for every model field, which means the component already holds
+ * everything an annotation needs — it just has no way to read it off a function. This is that way, and it is why
+ * `data-akan-*` costs an app no code at all: nobody writes the attribute, the setter carries its own name.
+ *
+ * Non-enumerable, so it survives neither `{...fn}` nor `JSON.stringify` and shows up in no spread.
+ */
+export const tagAction = <T extends (...args: never[]) => unknown>(fn: T, tag: ActionTag): T => {
+  Object.defineProperty(fn, ACTION_TAG, { value: tag, configurable: true });
+  return fn;
+};
+
+export const actionTagOf = (value: unknown): ActionTag | undefined => {
+  if (typeof value !== "function") return undefined;
+  const tag = (value as unknown as { [key: symbol]: unknown })[ACTION_TAG];
+  return tag && typeof tag === "object" ? (tag as ActionTag) : undefined;
+};

package/store/agent/AgentBridge.ts

@@ -0,0 +1,323 @@
+import { DataList } from "akanjs/base";
+import { Translator } from "akanjs/client";
+import { parseAkanI18nEnv } from "akanjs/common";
+import { ConstantRegistry, type MaskModel, mask } from "akanjs/constant";
+import { FetchClient } from "akanjs/fetch";
+import type { AgentRefusal, JsonSchema, SerializedArg, SerializedSignal } from "akanjs/signal";
+
+import { JsonSchemaBuilder } from "../../signal/schema/JsonSchemaBuilder";
+import type { StoreInstance } from "../storeInstance";
+import { StoreRegistry } from "../storeRegistry";
+import type { AgentVisibility } from "./AgentVisibility";
+import { StoreCatalogue } from "./StoreCatalogue";
+import type { SerializedStore, SerializedStoreAction, SerializedStoreState, StoreActionEffect } from "./types";
+
+export interface AgentTool {
+  name: string;
+  title?: string;
+  description?: string;
+  /** One flat named object, the shape MCP publishes. The bridge maps it onto the action's positional parameters. */
+  inputSchema: JsonSchema;
+  effect: StoreActionEffect;
+}
+
+/** One call the agent made, in the order it made them. */
+export interface AgentCall {
+  name: string;
+  args: Record<string, unknown>;
+  at: Date;
+  error?: string;
+}
+
+export interface AgentBridgeOptions {
+  /** Resolves a dictionary key to its text. Defaults to the seeded `Translator` in the active locale. */
+  resolveDescription?: (key: string) => string | undefined;
+}
+
+/**
+ * What an in-page agent may do to the app the user is looking at.
+ *
+ * Every call goes through `st.do`, which is the same single dispatch point a click goes through — so the agent
+ * cannot reach past what the UI already lets this user do, the app re-renders from the write, and the user watches
+ * the result rather than being told about it. That is why the exposure default here is the opposite of the MCP
+ * catalogue's: an external agent's `tools/list` is an attack surface built out of names the operator never chose to
+ * publish, while this one is the user's own session, under their own credential, with them watching.
+ *
+ * It is deliberately not an agent. There is no model, no provider, and no key here — an app wires whichever it uses
+ * to `tools`, `call`, and `read`. The framework's half is the catalogue, the argument checking, the masking, and the
+ * transcript; the conversation is the app's.
+ */
+export class AgentBridge {
+  readonly refusals: AgentRefusal[];
+
+  readonly #instance: StoreInstance;
+  readonly #store: SerializedStore;
+  readonly #options: AgentBridgeOptions;
+  readonly #schema = new JsonSchemaBuilder({ refPrefix: "#/$defs/" });
+  readonly #byName = new Map<string, SerializedStoreAction>();
+  readonly #calls: AgentCall[] = [];
+  readonly #visibility: AgentVisibility;
+  readonly #allTools: AgentTool[];
+  readonly #liveTools = new Map<string, { signature: string; tools: AgentTool[] }>();
+
+  /**
+   * The bridge for the app running in this process: the one store every `st.do` goes through, and every signal any
+   * client has applied. An app needs no arguments to reach its own agent surface.
+   */
+  static of(options: AgentBridgeOptions = {}) {
+    return new AgentBridge(StoreRegistry.instance, FetchClient.sharedSerializedSignal, options);
+  }
+
+  constructor(
+    instance: StoreInstance,
+    serializedSignal: Record<string, SerializedSignal>,
+    options: AgentBridgeOptions = {},
+  ) {
+    this.#instance = instance;
+    this.#options = options;
+    const catalogue = new StoreCatalogue(instance, serializedSignal);
+    this.#store = catalogue.store;
+    this.refusals = catalogue.refusals;
+    this.#visibility = catalogue.visibility;
+    for (const [name, action] of Object.entries(this.#store.action)) this.#byName.set(name, action);
+    this.#allTools = Object.entries(this.#store.action).map(([name, action]) => this.#tool(name, action));
+  }
+
+  /**
+   * The catalogued actions of the stores the rendered screen is reading right now — the live view, recomputed as
+   * components mount and unmount. Global exposure was the first cut's behavior and it published levers the screen
+   * does not respond to; the screen's own subscriptions are the honest boundary.
+   */
+  get tools(): AgentTool[] {
+    return this.toolsFor("");
+  }
+
+  /** The live view one zone session reads: owners counted from the keys that zone's own subtree subscribes. */
+  toolsFor(viewKey: string): AgentTool[] {
+    const live = this.#liveOwners(viewKey);
+    const signature = [...live].sort().join(",");
+    const cached = this.#liveTools.get(viewKey);
+    if (cached && cached.signature === signature) return cached.tools;
+    const tools = this.#allTools.filter((tool) => this.#ownerLive(tool.name, live));
+    this.#liveTools.set(viewKey, { signature, tools });
+    return tools;
+  }
+
+  get visibility(): AgentVisibility {
+    return this.#visibility;
+  }
+
+  #liveOwners(viewKey = "") {
+    return this.#visibility.liveOwners(this.#instance.liveKeysIn(viewKey));
+  }
+
+  #ownerLive(name: string, live: ReadonlySet<string>) {
+    const owner = this.#instance.actionOwners.get(name)?.refName;
+    return !owner || live.has(owner);
+  }
+
+  get state(): { [key: string]: SerializedStoreState } {
+    return this.#store.state;
+  }
+
+  get transcript(): readonly AgentCall[] {
+    return this.#calls;
+  }
+
+  subscribe(listener: () => void) {
+    return this.#instance.subscribe(listener);
+  }
+
+  /**
+   * The value behind a state key, stripped of what the model marks `hidden` or `secret`.
+   *
+   * Masking is not optional here even though the data mostly came from the server already masked: `<model>Form`
+   * holds what the *user* typed, credentials included, and an in-page agent ships what it reads to a remote model.
+   * The mask is by the declared model rather than by the value's class, because `immerify` copies a form into a
+   * plain object and the class is gone by the time anyone can ask.
+   */
+  read(key: string, viewKey = ""): unknown {
+    const entry = this.#store.state[key];
+    if (!entry) throw new Error(`Unknown state key: ${key}`);
+    const owner = this.#visibility.stateOwner(key);
+    if (owner && !this.#liveOwners(viewKey).has(owner))
+      throw new Error(`State key "${key}" is not part of the current screen's surface.`);
+    const value = AgentBridge.#unwrap(this.#instance.get()[key]);
+    if (entry.refName && entry.modelType) {
+      const model = ConstantRegistry.getModelRef(entry.refName, entry.modelType) as MaskModel;
+      return mask(model, value);
+    }
+    if (AgentBridge.#isPlainValue(value)) return value;
+    throw new Error(
+      `State key "${key}" holds an object that belongs to no model, so there is nothing to mask it by and it is not published. Read the model's own keys instead.`,
+    );
+  }
+
+  /**
+   * Dispatches through `st.do`, so what happens is what happens when the user clicks.
+   *
+   * Arguments arrive named and are mapped onto the action's parameters in declared order. An omitted optional one
+   * becomes `null`, which is what the slice query builders already expect; an omitted required one is refused,
+   * because the alternative is a call that writes `undefined` into state and reports success.
+   */
+  async call(name: string, args: Record<string, unknown> = {}, viewKey = "") {
+    const action = this.#byName.get(name);
+    if (!action) throw new Error(`Unknown action: ${name}`);
+
+    const record: AgentCall = { name, args, at: new Date() };
+    this.#calls.push(record);
+    try {
+      if (!this.#ownerLive(name, this.#liveOwners(viewKey)))
+        throw new Error(`Action "${name}" is not part of the current screen's surface.`);
+      const positional = action.args.map((arg) => this.#value(name, arg, args));
+      await this.#instance.do[name]?.(...positional);
+    } catch (error) {
+      record.error = error instanceof Error ? error.message : String(error);
+      throw error;
+    }
+  }
+
+  #value(name: string, arg: SerializedArg, args: Record<string, unknown>) {
+    if (!(arg.name in args) || args[arg.name] === undefined) {
+      if (arg.nullable || arg.type === "search") return null;
+      throw new Error(`Missing argument "${arg.name}" for ${name}.`);
+    }
+    return AgentBridge.#checked(name, arg, args[arg.name]);
+  }
+
+  /**
+   * Checks a value against what the argument declared, one level of array included.
+   *
+   * `st.do` accepts anything — it is a rest wrapper — so without this a string where an `Int` belongs is written
+   * into state and rendered, and the agent is told the call succeeded. A model argument is checked only for being
+   * an object: the published schema describes its fields and the endpoint validates them server-side.
+   */
+  static #checked(name: string, arg: SerializedArg, value: unknown): unknown {
+    const depth = arg.arrDepth ?? 0;
+    if (depth) {
+      if (!Array.isArray(value)) throw new Error(`Argument "${arg.name}" of ${name} must be an array.`);
+      return value.map((item) => AgentBridge.#checked(name, { ...arg, arrDepth: depth - 1 }, item));
+    }
+    if (value === null) return null;
+    if (arg.enum) return AgentBridge.#checkedEnum(name, arg, value);
+    switch (arg.refName) {
+      case "String":
+      case "ID":
+        return AgentBridge.#assertType(name, arg, value, "string");
+      case "Int":
+        if (!Number.isInteger(value)) throw new Error(`Argument "${arg.name}" of ${name} must be a whole number.`);
+        return value;
+      case "Float":
+        if (typeof value !== "number" || !Number.isFinite(value))
+          throw new Error(`Argument "${arg.name}" of ${name} must be a finite number.`);
+        return value;
+      case "Boolean":
+        return AgentBridge.#assertType(name, arg, value, "boolean");
+      case "Date":
+        return AgentBridge.#checkedDate(name, arg, value);
+      default:
+        if (typeof value !== "object") throw new Error(`Argument "${arg.name}" of ${name} must be an object.`);
+        return value;
+    }
+  }
+
+  static #assertType(name: string, arg: SerializedArg, value: unknown, type: "string" | "boolean") {
+    if (typeof value !== type) throw new Error(`Argument "${arg.name}" of ${name} must be a ${type}.`);
+    return value;
+  }
+
+  static #checkedEnum(name: string, arg: SerializedArg, value: unknown) {
+    const values = arg.enum ? ConstantRegistry.enum.get(arg.enum)?.values : undefined;
+    if (!values) return value;
+    if (!values.includes(value as never))
+      throw new Error(`Argument "${arg.name}" of ${name} must be one of: ${[...values].join(", ")}.`);
+    return value;
+  }
+
+  /** An agent has no `Date`, so an ISO string is what it sends. Anything unparseable is refused rather than `Invalid Date`. */
+  static #checkedDate(name: string, arg: SerializedArg, value: unknown) {
+    if (value instanceof Date) return value;
+    const parsed = typeof value === "string" ? new Date(value) : null;
+    if (!parsed || Number.isNaN(parsed.getTime()))
+      throw new Error(`Argument "${arg.name}" of ${name} must be an ISO 8601 date string.`);
+    return parsed;
+  }
+
+  #tool(name: string, action: SerializedStoreAction): AgentTool {
+    const properties = Object.fromEntries(action.args.map((arg) => [arg.name, this.#argSchema(action, arg)]));
+    const required = action.args.filter((arg) => !arg.nullable && arg.type !== "search").map((arg) => arg.name);
+    const defs = this.#schema.referencedSchemas(properties);
+    return {
+      name,
+      ...this.#texts(action),
+      inputSchema: {
+        type: "object",
+        properties,
+        ...(required.length ? { required } : {}),
+        additionalProperties: false,
+        ...(Object.keys(defs).length ? { $defs: defs } : {}),
+      },
+      effect: action.effect,
+    };
+  }
+
+  /**
+   * A store action carries no argument metadata of its own, so the prose comes from wherever the argument came
+   * from: an endpoint-named action borrows `<refName>.signal.<endpoint>.arg.<name>.desc`, and a field setter's one
+   * argument is the field, described at `<refName>.<field>.desc`. A slice role's `page`/`limit`/`sort` are the
+   * framework's own and have no dictionary entry to borrow.
+   */
+  #argSchema(action: SerializedStoreAction, arg: SerializedArg) {
+    const description = this.#argText(action, arg);
+    return {
+      ...this.#schema.arg(arg),
+      ...(description ? { description } : {}),
+      ...(arg.example !== undefined ? { examples: [arg.example] } : {}),
+    };
+  }
+
+  #argText({ refName, endpoint, field }: SerializedStoreAction, arg: SerializedArg) {
+    if (!refName) return undefined;
+    if (endpoint) return this.#text(`${refName}.signal.${endpoint}.arg.${arg.name}.desc`);
+    return field && arg.name === field ? this.#text(`${refName}.${field}.desc`) : undefined;
+  }
+
+  /**
+   * The words an agent picks the action by, borrowed from what the action is named after.
+   *
+   * The endpoint comes first, and it is right rather than merely adequate: the house rule makes `st.do.X` and
+   * `fetch.X` the same verb, so an action named after an endpoint reads as that endpoint's `.desc()`. A field
+   * setter falls back to the field's own label.
+   */
+  #texts({ refName, endpoint, field }: SerializedStoreAction) {
+    const keys = refName
+      ? [...(endpoint ? [`${refName}.signal.${endpoint}`] : []), ...(field ? [`${refName}.${field}`] : [])]
+      : [];
+    for (const key of keys) {
+      const title = this.#text(key);
+      const description = this.#text(`${key}.desc`);
+      if (title || description) return { ...(title ? { title } : {}), ...(description ? { description } : {}) };
+    }
+    return {};
+  }
+
+  #text(key: string) {
+    if (this.#options.resolveDescription) return this.#options.resolveDescription(key);
+    const locale = Translator.getActiveLocale() ?? parseAkanI18nEnv().defaultLocale;
+    const text = Translator.translateByLocale(locale, key);
+    
+    return text === key ? undefined : text;
+  }
+
+  static #unwrap(value: unknown) {
+    return value instanceof DataList ? value.values : value;
+  }
+
+  /** True when nothing inside could be carrying a model's fields, so there is nothing a mask would have to strip. */
+  static #isPlainValue(value: unknown): boolean {
+    if (value === null || value === undefined) return true;
+    if (Array.isArray(value)) return value.every((item) => AgentBridge.#isPlainValue(item));
+    if (value instanceof Date) return true;
+    return typeof value !== "object";
+  }
+}

package/store/agent/AgentContext.ts

@@ -0,0 +1,74 @@
+import type { ContextBlock, SurfaceView } from "../../vendor/use-agentic";
+import type { StoreInstance } from "../storeInstance";
+import { StoreRegistry } from "../storeRegistry";
+import type { AgentBridge } from "./AgentBridge";
+import { ensureStoreSurface } from "./storeSurface";
+
+/**
+ * The akan default context for a turn: where the user is (route), what is on screen (scopes and their curated
+ * resources), and which store keys the mounted components are reading (live keys). Live entries carry names and
+ * small primitives only — anything bigger is one `readState` call away, masked — so the block cannot bloat with
+ * what happens to be in the store. Base-store keys are excluded by the base store's own `agent: false`
+ * declaration, and the route block carries the three of them that matter.
+ */
+export class AgentContext {
+  static of(): AgentContext {
+    return new AgentContext(StoreRegistry.instance, ensureStoreSurface().bridge);
+  }
+
+  readonly #instance: StoreInstance;
+  readonly #bridge: AgentBridge;
+
+  constructor(instance: StoreInstance, bridge: AgentBridge) {
+    this.#instance = instance;
+    this.#bridge = bridge;
+  }
+
+  blocks(surface: SurfaceView, view: string[] = []): ContextBlock[] {
+    const state = this.#instance.get();
+    const { scopes, resources } = surface.snapshot();
+    return [
+      {
+        kind: "route",
+        path: String(state.pathname ?? ""),
+        params: state.params ?? {},
+        searchParams: state.searchParams ?? {},
+      },
+      ...(scopes.length || resources.length ? [{ kind: "screen", scopes, resources }] : []),
+      ...this.#liveBlock(view.join(".")),
+    ];
+  }
+
+  #liveBlock(viewKey: string): ContextBlock[] {
+    const live = [...this.#instance.liveKeysIn(viewKey).keys()]
+      .filter((key) => this.#bridge.visibility.visibleKey(key))
+      .sort()
+      .map((key) => this.#liveEntry(key));
+    return live.length ? [{ kind: "state", live, note: "Call readState(key) to read a value." }] : [];
+  }
+
+  #liveEntry(key: string) {
+    const meta = this.#bridge.state[key];
+    const value = AgentContext.#inlineValue(this.#instance.get()[key]);
+    return {
+      key,
+      ...(meta?.refName ? { model: meta.refName } : {}),
+      ...(meta ? { type: meta.type } : {}),
+      ...(value !== undefined ? { value } : {}),
+    };
+  }
+
+  /** Primitives ride inline; anything bigger stays a name the agent pulls with `readState`. */
+  static #inlineValue(value: unknown): unknown {
+    if (value === null) return null;
+    switch (typeof value) {
+      case "string":
+        return value.length <= 200 ? value : `${value.slice(0, 200)}…`;
+      case "number":
+      case "boolean":
+        return value;
+      default:
+        return undefined;
+    }
+  }
+}

package/store/agent/AgentPrompts.ts

@@ -0,0 +1,82 @@
+import { Translator } from "akanjs/client";
+import { parseAkanI18nEnv } from "akanjs/common";
+import { FetchClient } from "akanjs/fetch";
+import type { PromptContent, PromptResult, SerializedSignal } from "akanjs/signal";
+import type { ChatMessage } from "../../vendor/use-agentic";
+
+export interface AgentPrompt {
+  name: string;
+  refName: string;
+  description?: string;
+  args: { name: string; required: boolean }[];
+}
+
+/**
+ * The user-invokable `prompt()` endpoints of the mounted app, read off the serialized signals the client already
+ * holds — the same catalogue MCP lists them from, so a chat needs no listing endpoint. Guards are not evaluated
+ * here: a prompt's own GET enforces them at call time, and the refusal lands in the transcript like any failure.
+ */
+export class AgentPrompts {
+  static of(): AgentPrompts {
+    return new AgentPrompts(FetchClient.sharedSerializedSignal);
+  }
+
+  readonly #signals: Record<string, SerializedSignal>;
+
+  constructor(signals: Record<string, SerializedSignal>) {
+    this.#signals = signals;
+  }
+
+  list(): AgentPrompt[] {
+    const prompts: AgentPrompt[] = [];
+    for (const [refName, signal] of Object.entries(this.#signals))
+      for (const [name, endpoint] of Object.entries(signal.endpoint)) {
+        if (endpoint.type !== "prompt") continue;
+        prompts.push({
+          name,
+          refName,
+          ...(this.#description(refName, name) ? { description: this.#description(refName, name) } : {}),
+          args: (endpoint.args ?? []).map((arg) => ({
+            name: arg.name,
+            required: !(arg.nullable ?? arg.type === "search"),
+          })),
+        });
+      }
+    return prompts.sort((a, b) => (a.name < b.name ? -1 : 1));
+  }
+
+  find(name: string): AgentPrompt | null {
+    return this.list().find((prompt) => prompt.name === name) ?? null;
+  }
+
+  /** `/name arg1 arg2` — positional because a prompt's arguments are flat strings by protocol. */
+  static parseCommand(draft: string): { name: string; args: string[] } | null {
+    const match = /^\/([A-Za-z0-9_-]+)(?:\s+(.*))?$/.exec(draft.trim());
+    if (!match) return null;
+    return { name: match[1], args: match[2]?.split(/\s+/).filter(Boolean) ?? [] };
+  }
+
+  /** The messages a prompt returns become the user's turn, the way an MCP client sends a `prompts/get` result. */
+  static messagesOf(result: PromptResult): ChatMessage[] {
+    if (typeof result === "string") return [{ role: "user", text: result }];
+    return result.map((message) => ({ role: message.role, text: AgentPrompts.textOf(message.content) }));
+  }
+
+  static textOf(content: PromptContent): string {
+    if (content.type === "text") return content.text;
+    if (content.type === "resource") return `[resource ${content.resource.uri}]\n${content.resource.text}`;
+    if (content.type === "resource_link") return `[link ${content.name}: ${content.uri}]`;
+    return `[${content.type}]`;
+  }
+
+  #description(refName: string, name: string) {
+    return this.#text(`${refName}.signal.${name}.desc`) ?? this.#text(`${refName}.signal.${name}`);
+  }
+
+  #text(key: string) {
+    const locale = Translator.getActiveLocale() ?? parseAkanI18nEnv().defaultLocale;
+    const text = Translator.translateByLocale(locale, key);
+    
+    return text === key ? undefined : text;
+  }
+}