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

package/constant/getDefault.ts

@@ -2,11 +2,11 @@ import { DEFAULT_VALUE, FIELD_META, type PrimitiveScalar } from "akanjs/base";
 import type { FieldObject } from ".";
 import type { DefaultOf } from "./types";
 
-interface DefaultPlan {
+export interface DefaultPlan {
   /** Fields whose default is a value that can be shared: a primitive, `null`, or the field's own literal. */
   shared: Record<string, unknown>;
   /** Fields that have to be produced per call — a thunk, a fresh array, or a nested scalar record. */
-  perCall: [key: string, make: () => unknown][];
+  perCall: Map<string, () => unknown>;
 }
 
 const planCache = new WeakMap<FieldObject, DefaultPlan>();
@@ -17,28 +17,33 @@ const planCache = new WeakMap<FieldObject, DefaultPlan>();
  * sharing one. Only values that were already shared before this cache existed live in `shared`.
  */
 export const getDefault = <T>(fieldObj: FieldObject): DefaultOf<T> => {
-  let plan = planCache.get(fieldObj);
-  if (!plan) {
-    plan = buildPlan(fieldObj);
-    planCache.set(fieldObj, plan);
-  }
+  const plan = defaultPlanOf(fieldObj);
   const result: Record<string, unknown> = { ...plan.shared };
   for (const [key, make] of plan.perCall) result[key] = make();
   return result as DefaultOf<T>;
 };
 
+/** The per-field default rules, split as above; `HydrationPlan` reads them per field so a present value skips its thunk. */
+export const defaultPlanOf = (fieldObj: FieldObject): DefaultPlan => {
+  const cached = planCache.get(fieldObj);
+  if (cached) return cached;
+  const plan = buildPlan(fieldObj);
+  planCache.set(fieldObj, plan);
+  return plan;
+};
+
 const buildPlan = (fieldObj: FieldObject): DefaultPlan => {
   const shared: Record<string, unknown> = {};
-  const perCall: [string, () => unknown][] = [];
+  const perCall = new Map<string, () => unknown>();
   for (const [key, field] of Object.entries(fieldObj)) {
     if (field.fieldType === "hidden" || field.fieldType === "secret") shared[key] = null;
     else if (field.default !== undefined && field.default !== null) {
-      if (typeof field.default === "function") perCall.push([key, field.default as () => unknown]);
+      if (typeof field.default === "function") perCall.set(key, field.default as () => unknown);
       else shared[key] = field.default as object;
-    } else if (field.isArray) perCall.push([key, () => []]);
+    } else if (field.isArray) perCall.set(key, () => []);
     else if (field.nullable) shared[key] = null;
     else if (field.isClass) {
-      if (field.isScalar) perCall.push([key, () => getDefault(field.modelRef[FIELD_META])]);
+      if (field.isScalar) perCall.set(key, () => getDefault(field.modelRef[FIELD_META]));
       else shared[key] = null;
     } else shared[key] = (field.modelRef as unknown as typeof PrimitiveScalar)[DEFAULT_VALUE];
   }

package/constant/hydrationPlan.ts

@@ -0,0 +1,72 @@
+import { FIELD_META } from "akanjs/base";
+
+import { type Converter, converterOf } from "./crystalize";
+import { dateSlotOf, isDateSlotField, toDateValue } from "./dateSlot";
+import type { FieldObject } from "./fieldInfo";
+import { defaultPlanOf } from "./getDefault";
+
+interface PlanEntry {
+  key: string;
+  /** The own property the value lands on: the key itself, or a Date field's slot symbol. */
+  target: string | symbol;
+  convert: Converter;
+  makeDefault: () => unknown;
+}
+type PlanTarget = Record<string | symbol, unknown>;
+interface PlanOwner {
+  [FIELD_META]: FieldObject;
+}
+
+/**
+ * One hydration plan per model class, compiled from `FIELD_META` on the first instance. Reading the field map,
+ * resolving `getProps()` and dispatching on the field kind used to happen per field per instance, and was most of
+ * what a listing paid after the dayjs objects — a plan turns a row into a plain loop over precomputed converters.
+ *
+ * Cached per class rather than per field map because `fullModelOf` extends a lib model's `FIELD_META` in place;
+ * `applyConstantStatics` resets the entry whenever it finishes wiring a class.
+ */
+export class HydrationPlan {
+  static #byClass = new WeakMap<object, HydrationPlan>();
+  static of(cls: PlanOwner): HydrationPlan {
+    const cached = HydrationPlan.#byClass.get(cls);
+    if (cached) return cached;
+    const plan = new HydrationPlan(cls[FIELD_META]);
+    HydrationPlan.#byClass.set(cls, plan);
+    return plan;
+  }
+  static reset(cls: object) {
+    HydrationPlan.#byClass.delete(cls);
+  }
+
+  #entries: PlanEntry[];
+  constructor(fieldObj: FieldObject) {
+    const defaults = defaultPlanOf(fieldObj);
+    this.#entries = Object.entries(fieldObj).map(([key, field]) => {
+      const props = field.getProps();
+      const isDateSlot = isDateSlotField(props);
+      const convert: Converter = isDateSlot ? toDateValue : converterOf(props);
+      const perCall = defaults.perCall.get(key);
+      const rawDefault = perCall ?? (() => defaults.shared[key]);
+
+      return { key, target: isDateSlot ? dateSlotOf(key) : key, convert, makeDefault: () => convert(rawDefault()) };
+    });
+  }
+
+  /** Fills every field: the value when the source carries one, the field's default otherwise. */
+  construct(instance: object, source?: Record<string, unknown> | null) {
+    const target = instance as PlanTarget;
+    for (const entry of this.#entries) {
+      const value = source === undefined || source === null ? undefined : source[entry.key];
+      target[entry.target] = value === undefined ? entry.makeDefault() : entry.convert(value);
+    }
+  }
+
+  /** Overwrites only the fields the source names; `in` rather than own keys, so another instance's accessors count. */
+  assign(instance: object, source: Record<string, unknown>) {
+    const target = instance as PlanTarget;
+    for (const entry of this.#entries) {
+      if (!(entry.key in source)) continue;
+      target[entry.target] = entry.convert(source[entry.key]);
+    }
+  }
+}

package/constant/immerify.ts

@@ -1,16 +1,14 @@
 import { FIELD_META } from "akanjs/base";
+import { plainFieldsOf } from "akanjs/common";
 import { immerable } from "immer";
 import type { ConstantModelRef } from ".";
 
 export const immerify = <T extends object>(modelRef: ConstantModelRef, objOrArr: T): T => {
   if (Array.isArray(objOrArr)) return objOrArr.map((val) => immerify(modelRef, val as object)) as T;
-  const immeredObj = Object.assign({}, objOrArr, {
-    [immerable]: true,
-  }) as Record<string, unknown>;
-  const objRecord = objOrArr as Record<string, unknown>;
+  const immeredObj = Object.assign(plainFieldsOf(objOrArr), { [immerable]: true }) as Record<string, unknown>;
   Object.entries(modelRef[FIELD_META]).forEach(([key, field]) => {
-    if (field.isScalar && field.isClass && !!objRecord[key])
-      immeredObj[key] = immerify(field.modelRef, objRecord[key] as object);
+    if (field.isScalar && field.isClass && immeredObj[key])
+      immeredObj[key] = immerify(field.modelRef, immeredObj[key] as object);
   });
   return immeredObj as T;
 };

package/constant/index.ts

@@ -1,10 +1,15 @@
 export * from "./cascadePaths";
 export * from "./constantRegistry";
 export * from "./crystalize";
+export * from "./dateSlot";
 export * from "./deserialize";
 export * from "./fieldInfo";
+export * from "./fieldQueryMeta";
 export * from "./getDefault";
+export * from "./hydrationPlan";
 export * from "./immerify";
+export * from "./labelOf";
+export * from "./mask";
 export * from "./purify";
 export * from "./serialize";
 export * from "./textFieldPathSet";

package/constant/labelOf.ts

@@ -0,0 +1,26 @@
+/**
+ * The one line a human scans for. A model that writes its own `Light<Model>.label()` owns the answer, since
+ * display logic is the Light class's job; otherwise it is derived from what the model already declared — the
+ * `text: "title"` search role names exactly that field, so an agent-facing label costs no new declaration.
+ * Falls back to the conventional `title`/`name` keys; the id is the caller's floor.
+ */
+export const labelOf = (model: unknown, value: unknown): string | undefined => {
+  if (!value || typeof value !== "object") return undefined;
+  const source = value as Record<string, unknown>;
+  const written = source.label;
+  if (typeof written === "function") {
+    try {
+      const label = (written as () => unknown).call(source);
+      if (typeof label === "string" && label) return label;
+    } catch {
+    }
+  }
+  const paths = (model as { text?: { title?: Iterable<string> } } | null)?.text?.title;
+  const titlePath = [...(paths ?? [])].find((path) => !path.includes(".") && !path.includes("["));
+  for (const key of [titlePath, "title", "name"]) {
+    if (!key) continue;
+    const candidate = source[key];
+    if (typeof candidate === "string" && candidate) return candidate;
+  }
+  return undefined;
+};

package/constant/mask.ts

@@ -0,0 +1,67 @@
+import { FIELD_META } from "akanjs/base";
+
+/**
+ * A model as masking reads it — the constructor, for the field metadata it carries at runtime.
+ *
+ * Structural rather than `ConstantModelRef` so that anything holding the class can name it, and read through
+ * `FIELD_META` the way `resolveReturn` reads it.
+ */
+export interface MaskModel {
+  name: string;
+}
+
+/** The part of a field's metadata masking turns on. Mirrors what `resolveReturn` branches over. */
+interface MaskField {
+  fieldType?: string;
+  isClass?: boolean;
+  modelRef?: MaskModel;
+  visual?: boolean;
+}
+
+export const maskFieldsOf = (model: MaskModel): Record<string, MaskField> | null => {
+  const fields = (model as unknown as { [key: symbol]: unknown })[FIELD_META];
+  return fields && typeof fields === "object" ? (fields as Record<string, MaskField>) : null;
+};
+
+/**
+ * The `hidden` and `secret` field names of `model` that `value` still carries populated.
+ *
+ * `visual` is deliberately not among them. A refusal here means a value must not be published at all, and a blur
+ * placeholder is not a secret — it is merely not worth its tokens, which masking answers by dropping it.
+ */
+export const leakingFieldsOf = (model: MaskModel, value: Record<string, unknown>): string[] => {
+  const fields = maskFieldsOf(model);
+  if (!fields) return [];
+  return Object.entries(fields)
+    .filter(([key, field]) => (field.fieldType === "hidden" || field.fieldType === "secret") && key in value)
+    .map(([key]) => key);
+};
+
+/**
+ * Strips what a model marks `hidden`, `secret`, or `visual`, by the model the caller names rather than by the one
+ * the value happens to still carry. The first two are secrecy and the third is cost, but the answer is the same
+ * one — leave the field out — and this is the only place every AI-facing read already passes through.
+ *
+ * That distinction is the whole point. A check that reads the class off the value can only mask what arrives as an
+ * instance, so a `{ ...doc }` spread, a `toJSON()`, an `immerify()`, or a round-trip through `JSON.stringify` reaches
+ * its destination with the metadata already gone and nothing can be done about it. A named model is metadata the
+ * value cannot lose, so a hydrated document and a plain object copied out of one mask identically.
+ *
+ * This is the field half of `resolveReturn` and deliberately not the whole of it. That one also loads every relation
+ * it walks past, which is right for a query's return value and wrong here, where the value is already in hand.
+ *
+ * Returns `unknown` rather than the argument's type, because what comes back is missing fields that type promises.
+ */
+export const mask = (model: MaskModel, value: unknown): unknown => {
+  if (value === null || value === undefined || typeof value !== "object") return value;
+  if (Array.isArray(value)) return value.map((item: unknown) => mask(model, item));
+  const fields = maskFieldsOf(model);
+  if (!fields) return value;
+  const source = value as Record<string, unknown>;
+  const masked: Record<string, unknown> = {};
+  for (const [key, field] of Object.entries(fields)) {
+    if (field.fieldType === "hidden" || field.fieldType === "secret" || field.visual || !(key in source)) continue;
+    masked[key] = field.isClass && field.modelRef ? mask(field.modelRef, source[key]) : source[key];
+  }
+  return masked;
+};

package/constant/purify.ts

@@ -31,18 +31,24 @@ type Purified<O> = O extends BaseObject
       : O extends object
         ? PurifiedModel<O>
         : O;
-type PurifiedWithObjectToId<T, StateKeys extends keyof GetStateObject<T> = keyof GetStateObject<T>> = {
-  [K in StateKeys as null extends T[K] ? never : K]: Purified<T[K]>;
-} & {
-  [K in StateKeys as null extends T[K] ? K : never]?: Purified<T[K]> | undefined;
-};
-export type PurifiedModel<T> = T extends (infer S)[]
-  ? PurifiedModel<S>[]
-  : T extends string | number | boolean | Dayjs | File
+type PurifiedWithObjectToId<T, StateKeys extends keyof GetStateObject<T> = keyof GetStateObject<T>> =
+  
+  unknown extends T
     ? T
-    : T extends Map<infer K, infer V>
-      ? Map<K, PurifiedModel<V>>
-      : PurifiedWithObjectToId<T>;
+    : {
+        [K in StateKeys as null extends T[K] ? never : K]: Purified<T[K]>;
+      } & {
+        [K in StateKeys as null extends T[K] ? K : never]?: Purified<T[K]> | undefined;
+      };
+export type PurifiedModel<T> = unknown extends T
+  ? T
+  : T extends (infer S)[]
+    ? PurifiedModel<S>[]
+    : T extends string | number | boolean | Dayjs | File
+      ? T
+      : T extends Map<infer K, infer V>
+        ? Map<K, PurifiedModel<V>>
+        : PurifiedWithObjectToId<T>;
 
 export type UploadableClientArg<T> = [T] extends [File[]] ? File[] | FileList : T;
 

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/constant/types.ts

@@ -14,21 +14,27 @@ type ObjectToId<O> = O extends BaseObject
         ? DocumentModel<O>
         : O;
 
-type Docify<T, _StateKeys extends keyof GetStateObject<T> = keyof GetStateObject<T>> = {
-  [K in _StateKeys as null extends T[K] ? never : K]-?: ObjectToId<NonNullable<T[K]>>;
-} & {
-  [K in _StateKeys as null extends T[K] ? K : never]?: ObjectToId<NonNullable<T[K]>> | undefined;
-};
-export type DocumentModel<T> = T extends (infer S)[]
-  ? DocumentModel<S>[]
-  : T extends string | number | boolean | Dayjs | File
-    ? T
-    : T extends Map<infer K, infer V>
-      ? Map<K, DocumentModel<V>>
-      : Docify<T>;
+type Docify<T, _StateKeys extends keyof GetStateObject<T> = keyof GetStateObject<T>> = unknown extends T
+  ? T
+  : { [K in _StateKeys as null extends T[K] ? never : K]-?: ObjectToId<NonNullable<T[K]>> } & {
+      [K in _StateKeys as null extends T[K] ? K : never]?: ObjectToId<NonNullable<T[K]>> | undefined;
+    };
+export type DocumentModel<T> = unknown extends T
+  ? T
+  : T extends (infer S)[]
+    ? DocumentModel<S>[]
+    : T extends string | number | boolean | Dayjs | File
+      ? T
+      : T extends Map<infer K, infer V>
+        ? Map<K, DocumentModel<V>>
+        : Docify<T>;
 
 export type FieldState<T> = T extends { id: string } ? T | null : T;
-export type DefaultOf<S> = GetStateObject<{ [K in keyof S]: FieldState<S[K]> }>;
+export type DefaultOf<S> = {
+  [K in keyof S as S[K] extends (...args: never[]) => unknown ? never : K extends "prototype" ? never : K]: FieldState<
+    S[K]
+  >;
+};
 
 export type DefaultOfSchema<Schema, RelationKey = never> = [RelationKey] extends [never]
   ? Schema

package/constant/via.ts

@@ -1,4 +1,5 @@
 import {
+  Binary,
   CLIENT_VALUE,
   type Cls,
   DEFAULT_VALUE,
@@ -9,12 +10,13 @@ import {
   PURIFIED_VALUE,
   SERVER_VALUE,
 } from "akanjs/base";
-import { applyMixins } from "akanjs/common";
+import { applyMixins, plainFieldsOf } from "akanjs/common";
 import { immerable } from "immer";
 
-import { crystalize, getDefault } from ".";
+import { getDefault } from ".";
 import { CascadePaths } from "./cascadePaths";
 import { ConstantRegistry } from "./constantRegistry";
+import { dateAccessorOf, isDateSlotField } from "./dateSlot";
 import {
   ConstantField,
   type ExtractFieldInfoObject,
@@ -26,6 +28,7 @@ import {
   field,
   resolve,
 } from "./fieldInfo";
+import { HydrationPlan } from "./hydrationPlan";
 import { makePurify, type PurifiedModel, type PurifyFunc } from "./purify";
 import { TextFieldPaths } from "./textFieldPaths";
 import type { BaseInsight, BaseObject, ConstantType, DefaultOf, DefaultOfSchema, NonFunctionalKeys } from "./types";
@@ -200,22 +203,16 @@ const getBaseConstantClass = (field: FieldObject, modelType: ConstantType = "sca
     static enums: Set<EnumInstance> = new Set();
     [immerable] = true;
     constructor(obj?: Partial<unknown>) {
-      this.set({
-        ...(this.constructor as ConstantCls).getDefault(),
-        ...((obj ?? {}) as Partial<typeof this>),
-      });
+      HydrationPlan.of(this.constructor as ConstantCls).construct(this, obj as Record<string, unknown> | undefined);
     }
     set(obj: Partial<typeof this>) {
-      Object.entries(obj).forEach(([key, value]) => {
-        
-        if (!(this.constructor as ConstantCls)[FIELD_META][key] as unknown as object | undefined) return;
-        const field = (this.constructor as ConstantCls)[FIELD_META][key];
-        if (!field) throw new Error(`Field ${key} not found`);
-        const fieldProp = field.getProps();
-        (this as Record<string, unknown>)[key] = crystalize(fieldProp, value);
-      });
+      HydrationPlan.of(this.constructor as ConstantCls).assign(this, obj as Record<string, unknown>);
       return this;
     }
+    
+    toJSON() {
+      return plainFieldsOf(this);
+    }
   }
   return BaseConstant as unknown as ConstantCls;
 };
@@ -430,12 +427,18 @@ declare global {
 }
 
 const applyConstantStatics = <Model>(model: ConstantCls<Model>, fieldMap: FieldObject): ConstantCls<Model> => {
-  const defaultValue = getDefault(model[FIELD_META]);
+
+  let defaultValue: DefaultOf<Model> | undefined;
   Object.assign(model, {
     purify: makePurify(model),
-    getDefault: () => ({ ...defaultValue }),
+    getDefault: () => {
+      defaultValue ??= getDefault<Model>(model[FIELD_META]);
+      return { ...defaultValue };
+    },
   });
-  Object.entries(fieldMap).forEach(([, field]) => {
+  Object.entries(fieldMap).forEach(([key, field]) => {
+    if ((field.modelRef as unknown) === Binary || (field.of as unknown) === Binary)
+      throw new Error(`Field "${key}" is Binary, which is not storable. Reference the File model instead.`);
     if (field.enum) model.enums.add(field.enum);
     if (!field.isClass) return;
     if (field.isScalar) model.children.add(field.modelRef);
@@ -446,6 +449,10 @@ const applyConstantStatics = <Model>(model: ConstantCls<Model>, fieldMap: FieldO
   });
   model.text.collect(fieldMap);
   model.cascade.collect(fieldMap);
+
+  for (const [key, field] of Object.entries(model[FIELD_META]))
+    if (isDateSlotField(field.getProps())) Object.defineProperty(model.prototype, key, dateAccessorOf(key));
+  HydrationPlan.reset(model);
   return model as unknown as ConstantCls<Model>;
 };
 

package/dictionary/DictionaryLookup.ts

@@ -0,0 +1,30 @@
+import { pathGetLoose } from "akanjs/common";
+import { DictionaryRegistry } from "./dictionaryRegistry";
+import type { DictionaryNode } from "./trans";
+
+/**
+ * Reads translated text out of the merged dictionary tree by dotted key (`user.signal.createUser.arg.data.desc`).
+ *
+ * Unlike `translate`, a missing key resolves to `undefined` rather than echoing the key back: callers here are
+ * document generators (OpenAPI, MCP) that must omit an absent description instead of emitting `"user.signal.…"`
+ * as if it were prose. The merged root is snapshotted once per instance, so build a fresh one per document.
+ */
+export class DictionaryLookup {
+  readonly language: string;
+  readonly #models: Record<string, DictionaryNode>;
+  constructor(language?: string) {
+    const root = DictionaryRegistry.getRoot();
+    this.language = language && root[language] ? language : (Object.keys(root).at(0) ?? "en");
+    this.#models = root[this.language] ?? {};
+  }
+
+  /** A bare refName names the model node itself, which holds no text of its own — its label is `<refName>.modelName`. */
+  text(key: string): string | undefined {
+    const [refName, ...rest] = key.split(".");
+    if (!refName) return undefined;
+    const model = this.#models[refName];
+    const node = (rest.length ? pathGetLoose(rest, model) : model) as { t?: unknown } | null;
+    const text = node?.t;
+    return typeof text === "string" && text.length ? text : undefined;
+  }
+}

package/dictionary/agent.dictionary.ts

@@ -0,0 +1,31 @@
+import type { AgentEndpoint } from "akanjs/signal";
+
+import { serviceDictionary } from "./dictInfo";
+
+export const agentDictionary = serviceDictionary(["en", "ko"])
+  .endpoint<AgentEndpoint>((fn) => ({
+    runAgentTurn: fn(["Run Agent Turn", "에이전트 턴 실행"])
+      .desc([
+        "Relays one in-page agent turn to the model and returns its answer; tools execute in the caller's browser",
+        "인페이지 에이전트 턴 하나를 모델에 릴레이하고 응답을 돌려준다. 툴 실행은 호출자의 브라우저에서 한다",
+      ])
+      .arg((t) => ({
+        messages: t(["Messages", "메시지"]).desc(["The whole transcript in wire shape", "와이어 형태의 전체 대화"]),
+        tools: t(["Tools", "툴"]).desc(["The published tool catalogue, schemas only", "게시된 툴 카탈로그 (스키마만)"]),
+        context: t(["Context", "컨텍스트"]).desc([
+          "Screen context blocks, forwarded as data",
+          "화면 컨텍스트 블록 (데이터로 전달)",
+        ]),
+        instructions: t(["Instructions", "지시문"]).desc(["App-level system instructions", "앱 수준 시스템 지시문"]),
+      })),
+  }))
+  .error({
+    llmUnavailable: [
+      "The agent is unavailable — this app has no language model configured",
+      "에이전트를 사용할 수 없습니다. 이 앱에 언어 모델이 설정되어 있지 않습니다",
+    ],
+    deepseekRequestFailed: [
+      "DeepSeek refused this turn with status {status}. Reason: {reason}",
+      "DeepSeek가 이번 턴을 거절했습니다 (status {status}). 사유: {reason}",
+    ],
+  });

package/dictionary/agentTurn.dictionary.ts

@@ -0,0 +1,29 @@
+import type { AgentStop, AgentTurn } from "akanjs/signal";
+
+import { scalarDictionary } from "./dictInfo";
+
+export const agentTurnDictionary = scalarDictionary(["en", "ko"])
+  .of((t) =>
+    t(["Agent Turn", "에이전트 턴"]).desc([
+      "One assistant answer of an in-page agent turn",
+      "인페이지 에이전트 턴의 어시스턴트 응답 하나",
+    ]),
+  )
+  .model<AgentTurn>((t) => ({
+    text: t(["Text", "텍스트"]).desc([
+      "What the assistant said; empty when the turn is only tool calls",
+      "어시스턴트가 말한 내용. 툴 호출뿐인 턴에서는 비어 있다",
+    ]),
+    toolCalls: t(["Tool Calls", "툴 호출"]).desc([
+      "Tool calls the client should execute, as { id, name, args }",
+      "클라이언트가 실행할 툴 호출 목록 ({ id, name, args })",
+    ]),
+    stop: t(["Stop", "종료 사유"]).desc([
+      "Why the turn ended — end, or toolUse when tool results are awaited",
+      "턴이 끝난 이유 — end 또는 툴 결과를 기다리는 toolUse",
+    ]),
+  }))
+  .enum<AgentStop>("agentStop", (t) => ({
+    end: t(["End", "종료"]).desc(["The final answer", "최종 응답"]),
+    toolUse: t(["Tool Use", "툴 사용"]).desc(["The model awaits tool results", "모델이 툴 결과를 기다린다"]),
+  }));