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

package/dictionary/base.dictionary.ts

@@ -27,6 +27,24 @@ export const baseDictionary = serviceDictionary(["en", "ko"])
       })),
     pubsubPing: fn(["Pubsub Ping", "Pubsub Ping"]),
   }))
+  .error({
+    serverUnreachable: [
+      "Cannot reach the server. Check your connection and try again.",
+      "서버에 연결할 수 없습니다. 네트워크 상태를 확인한 뒤 다시 시도해주세요.",
+    ],
+    serverUnavailable: [
+      "The server is restarting. Please try again in a moment.",
+      "서버가 재시작 중입니다. 잠시 후 다시 시도해주세요.",
+    ],
+    gatewayTimeout: [
+      "The server took too long to answer. Please try again in a moment.",
+      "서버 응답이 지연되고 있습니다. 잠시 후 다시 시도해주세요.",
+    ],
+    unexpectedResponse: [
+      "The server returned an unexpected response ({status}).",
+      "서버가 예상하지 못한 응답을 보냈습니다. ({status})",
+    ],
+  })
   .translate({
     somethingWrong: ["Something's wrong!", "문제가 생겼어요!"],
     connecting: ["Connecting...", "연결 중..."],
@@ -48,6 +66,64 @@ export const baseDictionary = serviceDictionary(["en", "ko"])
     ok: ["OK", "확인"],
     cancel: ["Cancel", "취소"],
     unauthorized: ["Unauthorized", "권한 없음"],
+    agent: ["Agent", "에이전트"],
+    agentIntro: ["Ask about this page or tell the agent what to do.", "이 화면에 대해 묻거나 할 일을 지시해 보세요."],
+    agentPlaceholder: ["Message the agent...", "에이전트에게 메시지..."],
+    agentClear: ["Clear conversation", "대화 비우기"],
+    agentQuestion: ["The agent needs your decision", "에이전트가 결정을 요청합니다"],
+    agentAnswer: ["Type your answer...", "답변을 입력하세요..."],
+    agentListen: ["Speak to the agent", "에이전트에게 말하기"],
+    agentVoiceFailed: ["The microphone could not be used.", "마이크를 사용할 수 없습니다."],
+    agentAttach: ["Attach a file", "파일 첨부"],
+    agentAttachRemove: ["Remove attachment", "첨부 제거"],
+    agentAttachTooLarge: ["{name} is too large to attach.", "{name}은(는) 용량이 너무 커서 첨부할 수 없습니다."],
+    agentAttachUnsupported: ["{name} cannot be attached here.", "{name}은(는) 여기에 첨부할 수 없습니다."],
+    agentAttachDuplicate: ["{name} is already attached.", "{name}은(는) 이미 첨부되어 있습니다."],
+    agentAttachTooMany: [
+      "One message can carry {count} files at most.",
+      "한 메시지에는 파일을 최대 {count}개까지 첨부할 수 있습니다.",
+    ],
+    agentAttachTooMuch: [
+      "{name} would make this message too large to send.",
+      "{name}을(를) 더하면 메시지가 너무 커서 보낼 수 없습니다.",
+    ],
+    agentAnswerNeeded: ["Type an answer to the question above.", "위 질문에 대한 답을 입력하세요."],
+    agentToolDone: ["Done", "완료"],
+    agentToolFailed: ["Failed", "실패"],
+    agentToolRunning: ["Running", "실행 중"],
+    agentToolResult: ["Show what this tool returned", "이 툴이 반환한 값 보기"],
+    agentTokens: ["~{count} tokens", "약 {count} 토큰"],
+    agentSummarizing: ["Summarizing the conversation…", "대화를 요약하는 중…"],
+    agentContinue: ["This is taking a while. Keep going?", "시간이 걸리고 있습니다. 계속할까요?"],
+    agentKeepGoing: ["Keep going", "계속하기"],
+    agentCmdNew: ["Start a new conversation", "새 대화 시작"],
+    agentCmdRetry: ["Send the last message again", "마지막 메시지 다시 보내기"],
+    agentCmdCompact: ["Summarize the conversation so far", "지금까지의 대화 요약하기"],
+    agentCmdCopy: ["Copy this conversation", "이 대화 복사"],
+    agentCmdHelp: ["What you can do here", "여기서 할 수 있는 것"],
+    agentCmdTools: ["List this screen's tools", "이 화면의 툴 목록"],
+    agentHelpIntro: [
+      "Ask about this page, or tell the agent what to do. Commands:",
+      "이 화면에 대해 묻거나 할 일을 지시하세요. 커맨드:",
+    ],
+    agentHelpNote: [
+      "The agent asks before anything it should not decide alone, and Stop ends a running turn.",
+      "에이전트는 혼자 결정하면 안 되는 일을 하기 전에 물어보며, 중지는 진행 중인 턴을 끝냅니다.",
+    ],
+    agentNothingToRetry: ["There is no message to send again.", "다시 보낼 메시지가 없습니다."],
+    agentNothingToCompact: ["There is nothing to summarize yet.", "아직 요약할 대화가 없습니다."],
+    agentCompacted: ["Summarized the conversation so far.", "지금까지의 대화를 요약했습니다."],
+    agentSummary: ["Summary of the earlier conversation", "이전 대화 요약"],
+    agentBusy: ["A turn is still running. Stop it first.", "진행 중인 턴이 있습니다. 먼저 중지하세요."],
+    agentCopied: ["Conversation copied to the clipboard.", "대화를 클립보드에 복사했습니다."],
+    agentCopyFailed: ["Could not reach the clipboard.", "클립보드에 접근할 수 없습니다."],
+    agentToolsHead: ["What the agent can do on this screen:", "이 화면에서 에이전트가 할 수 있는 일:"],
+    agentToolsState: ["Readable state:", "읽을 수 있는 상태:"],
+    send: ["Send", "보내기"],
+    stop: ["Stop", "중지"],
+    skip: ["Skip", "건너뛰기"],
+    approve: ["Approve", "승인"],
+    decline: ["Decline", "거절"],
     confirmClose: ["Are you sure you want to close the modal?", "모달을 닫으시겠습니까?"],
     textTooShortError: ["More than {minlength} characters needed.", "{minlength}자 이상 필요합니다."],
     textTooLongError: ["Less than {maxlength} characters needed.", "{maxlength}자 이하로 필요합니다."],
@@ -81,6 +157,11 @@ export const baseDictionary = serviceDictionary(["en", "ko"])
     removeMsg: ["Are you sure to remove?", "정말로 삭제하시겠습니까?"],
     confirmMsg: ["Are you sure to {actionType}", "진행하시겠습니까? ({actionType})"],
     perPage: ["/page", "/페이지"],
+    refresh: ["Refresh", "새로고침"],
+    cardView: ["Card view", "카드 보기"],
+    tableView: ["Table view", "표 보기"],
+    exportCsv: ["Export CSV", "CSV 내보내기"],
+    exportJson: ["Export JSON", "JSON 내보내기"],
     actions: ["Actions", "작업"],
     new: ["New", "신규"],
     edit: ["Edit", "수정"],

package/dictionary/dictInfo.ts

@@ -206,12 +206,13 @@ export class ModelDictInfo<
     } as unknown as BaseModelCrudGetSignalTranslation<T, [string, string]>;
   }
   static baseSliceDictionary: {
-    [key in ""]: FunctionTranslation<[string, string], "query">;
+    [key in ""]: FunctionTranslation<[string, string], "queryKey" | "args">;
   } = {
     "": fn(["Universal", "유니버설"])
       .desc(["Universal Slice", "유니버설 슬라이스"])
       .arg((t) => ({
-        query: t(["Query", "쿼리"]).desc(["Query Description", "쿼리 설명"]),
+        queryKey: t(["Query", "쿼리"]).desc(["Filter query to run", "실행할 필터 쿼리"]),
+        args: t(["Arguments", "인자"]).desc(["Arguments of the filter query", "필터 쿼리의 인자"]),
       })),
   };
 
@@ -777,6 +778,7 @@ export class ModelDictInfo<
       });
     });
   }
+  /** Under its own `store` node rather than beside `signal`, because the two hold the same key by design. */
   #registerErrorToRoot(refName: string, rootDict: RootDictionary) {
     this.languages.forEach((language) => {
       ensureNode(getRootModelNode(rootDict, language, refName), "error");
@@ -803,6 +805,13 @@ export class ModelDictInfo<
   }
 }
 
+/**
+ * Every parameter of `ModelDictInfo` is listed here positionally, so a parameter added to the class has to be
+ * added to all three lists below in the same slot. Omitting one does not fail to compile — inference silently
+ * shifts, so the last parameter falls off the end and becomes its default `never`, which reads at the call site
+ * as `l("<model>.<key>")` no longer existing.
+ */
+
 type AnyModelDictInfo = ModelDictInfo<any, any, any, any, any, any, any, any, any, any, any>;
 
 type MergeTwoModelDicts<ModelDict1, ModelDict2> =

package/dictionary/dictionary.ts

@@ -1,10 +1,16 @@
-import type { BaseEndpoint } from "akanjs/signal";
+import type { AgentEndpoint, AgentTurn, BaseEndpoint } from "akanjs/signal";
 
+import { agentDictionary } from "./agent.dictionary";
+import { agentTurnDictionary } from "./agentTurn.dictionary";
 import { baseDictionary } from "./base.dictionary";
-import { registerServiceTrans } from "./locale";
+import { registerScalarTrans, registerServiceTrans } from "./locale";
 import { makeTrans } from "./trans";
 
-export const dictionary = { base: registerServiceTrans<"base", BaseEndpoint, typeof baseDictionary>(baseDictionary) };
+export const dictionary = {
+  base: registerServiceTrans<"base", BaseEndpoint, typeof baseDictionary>(baseDictionary),
+  agentTurn: registerScalarTrans<"agentTurn", AgentTurn, typeof agentTurnDictionary>(agentTurnDictionary),
+  agent: registerServiceTrans<"agent", AgentEndpoint, typeof agentDictionary>(agentDictionary),
+};
 
 export const { Err, translate, msg, getDictionary, getAllDictionary, __Dict_Key__, __Error_Key__ } =
   makeTrans(dictionary);

package/dictionary/index.ts

@@ -1,3 +1,4 @@
+export * from "./DictionaryLookup";
 export * from "./dictInfo";
 export {
   __Dict_Key__,

package/dictionary/trans.ts

@@ -1,5 +1,5 @@
 import type { GetStateObject, ObjectAssign, Prettify } from "akanjs/base";
-import { pathGet } from "akanjs/common";
+import { pathGetLoose } from "akanjs/common";
 
 import { DictionaryRegistry } from "./dictionaryRegistry";
 import type { DictModule } from "./locale";
@@ -177,7 +177,7 @@ export const makeTrans = <
     const msgKey = msgKeys.join(".");
     const langDict = rootDictionary[lang] ?? {};
     const model = langDict[modelName as string] ?? {};
-    const message = pathGet(msgKey as string, model, ".", { t: key }) as { t: string };
+    const message = pathGetLoose(msgKey as string, model, ".", { t: key }) as { t: string };
     return message.t;
   };
   const getDictionary = (lang: Language) => {

package/document/documentQuery.ts

@@ -157,6 +157,7 @@ export const createDocumentQueryHelper = () => ({
   lte: (value: unknown) => op("lte", value),
   between: (from: unknown, to: unknown) => op("between", [from, to]),
   exists: (path: string) => ({ [path]: op("exists") }),
+
   missing: (path: string) => ({ [path]: op("missing") }),
   empty: (path: string) => ({ [path]: op("empty") }),
   has: (value: unknown) => op("has", value),

package/document/filterMeta.ts

@@ -1,16 +1,18 @@
-import type { Cls, MergeAllDoubleKeyOfObjects, MergeAllKeyOfTypes } from "akanjs/base";
-import { FILTER_DICT_SHAPE, FILTER_META } from "akanjs/base";
-import type {
-  BaseObject,
-  ConstantFieldTypeInput,
-  DocumentModel,
-  FieldToValue,
-  PlainTypeToFieldType,
-  QueryOf,
-  Serialized,
+import type { Cls, EnumInstance, MergeAllDoubleKeyOfObjects, MergeAllKeyOfTypes } from "akanjs/base";
+import { FILTER_DICT_SHAPE, FILTER_META, getNonArrayModel, isEnum } from "akanjs/base";
+import {
+  type BaseObject,
+  type ConstantFieldType,
+  type ConstantFieldTypeInput,
+  type DocumentModel,
+  deserialize,
+  type FieldToValue,
+  type PlainTypeToFieldType,
+  type QueryOf,
+  type Serialized,
 } from "akanjs/constant";
 
-import type { DocumentQuery, DocumentQueryHelper } from "./documentQuery";
+import { type DocumentQuery, type DocumentQueryHelper, documentQueryHelper } from "./documentQuery";
 import type { ConstantFilterMeta } from "./types";
 
 const isObjectRecord = (value: unknown): value is Record<string, unknown> =>
@@ -98,6 +100,70 @@ export const fillMissingFilterArgs = (filterInfo: FilterInfo, args: unknown[]) =
   return [...args, ...Array(filterInfo.args.length - args.length).fill(undefined)];
 };
 
+export interface FilterArgInfo {
+  name: string;
+  argRef: ConstantFieldType;
+  arrDepth: number;
+  enum?: EnumInstance;
+  nullable: boolean;
+  ref?: string;
+}
+/** Unwraps a filter arg's declaration the way `EndpointInfo.getArgInfo` unwraps an endpoint's. */
+export const getFilterArgInfo = (arg: FilterInfo["args"][number]): FilterArgInfo => {
+  const [singleArg, arrDepth] = getNonArrayModel(arg.argRef as Cls);
+  const argIsEnum = isEnum(singleArg);
+  return {
+    name: arg.name,
+    argRef: (argIsEnum ? (singleArg as EnumInstance).type : singleArg) as ConstantFieldType,
+    arrDepth,
+    enum: argIsEnum ? (singleArg as EnumInstance) : undefined,
+    nullable: !!arg.option?.nullable,
+    ref: arg.option?.ref,
+  };
+};
+export const getFilterArgInfos = (filterInfo: FilterInfo): FilterArgInfo[] => filterInfo.args.map(getFilterArgInfo);
+
+/** A caller named a filter that does not exist, or gave it arguments it cannot take. Its callers answer 400. */
+export class FilterQueryError extends Error {}
+
+const tryDeserializeFilterArg = (arg: FilterArgInfo, value: unknown, key: string) => {
+  try {
+    return deserialize(arg.argRef, arg.arrDepth, value, { key: arg.name, nullable: arg.nullable });
+  } catch (error) {
+    throw new FilterQueryError(
+      `Invalid filter argument "${arg.name}" for key: ${key}: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+};
+
+/**
+ * Compiles a `(queryKey, args)` pair into the query its filter declares — the root slice's whole contract.
+ * Every arg is parsed by the type the filter declared for it, so a Date arg reaches the query as a Dayjs and
+ * an id that is not one is refused here rather than becoming a query that matches nothing. Args past the
+ * declared ones are dropped: the caller names a filter, never a query.
+ */
+export const resolveFilterQuery = (
+  filterRef: FilterCls,
+  queryKey?: string | null,
+  args?: unknown[] | null,
+): QueryOf<any> => {
+  const key = queryKey || "any";
+  const filterInfo = getFilterMeta(filterRef).query[key];
+  const queryFn = filterInfo?.queryFn;
+  if (!queryFn) throw new FilterQueryError(`No filter query for key: ${key}`);
+  const given = Array.isArray(args) ? args : [];
+  const queryArgs = getFilterArgInfos(filterInfo).map((arg, idx) => {
+    const value = given[idx];
+    if (!arg.nullable && (value === null || value === undefined))
+      throw new FilterQueryError(`Missing filter argument "${arg.name}" for key: ${key}`);
+    const parsed = tryDeserializeFilterArg(arg, value, key);
+
+    return parsed === null ? undefined : parsed;
+  });
+  
+  return queryFn(...queryArgs, documentQueryHelper) as QueryOf<any>;
+};
+
 export const assertFilterFitsCrud = (refName: string, queryKey: string, className: string) => {
   if (queryKey.toLowerCase() !== refName.toLowerCase()) return;
   throw new Error(
@@ -209,7 +275,6 @@ interface ArgProps<Value = unknown> {
   nullable?: boolean;
   ref?: string;
   default?: Value;
-  renderOption?: (arg: never) => string;
 }
 export class FilterInfo<ArgNames extends string[] = any, Args extends any[] = any, Model = any> {
   readonly argNames: ArgNames = [] as unknown as ArgNames;

package/document/index.ts

@@ -7,5 +7,6 @@ export * from "./documentSchema";
 export * from "./filterMeta";
 export * from "./into";
 export * from "./loaderInfo";
+export * from "./noDocumentError";
 export * from "./schema";
 export * from "./types";

package/document/noDocumentError.ts

@@ -0,0 +1,12 @@
+/**
+ * A `pick` or a `get` that matched nothing. Typed so a caller can tell "you asked for something that is not
+ * there" from "we broke" — an agent-facing transport in particular must not log a stack and answer "the server
+ * failed" every time a model guesses an id.
+ *
+ * The message is unchanged from the bare `Error` this replaces, because callers already match on it, and the
+ * `statusCode` does not reach the HTTP layer: `isExceptionLike` wants a `toJSON` too, so a missing document
+ * stays a 500 there until someone decides framework-wide that it should be a 404.
+ */
+export class NoDocumentError extends Error {
+  readonly statusCode = 404;
+}

package/document/types.ts

@@ -21,7 +21,6 @@ export interface FilterArgProps {
   nullable?: boolean;
   ref?: string;
   default?: string | number | boolean | object | null | (() => string | number | boolean | object | null);
-  renderOption?: (value: never) => string;
   enum?: EnumInstance;
 }
 

package/fetch/agentTurn.ts

@@ -0,0 +1,19 @@
+import { Any, enumOf } from "akanjs/base";
+import { ConstantRegistry, via } from "akanjs/constant";
+
+export class AgentStop extends enumOf("agentStop", ["end", "toolUse"] as const) {}
+
+export class AgentTurn extends via((field) => ({
+  text: field(String, { default: "" }), // the assistant's words; empty when the turn is only tool calls
+  toolCalls: field([Any]), // { id, name, args } per call — args carries the tool's own schema, not a model's
+  stop: field(AgentStop, { default: "end" }),
+})) {
+  isToolUse() {
+    return this.stop === "toolUse";
+  }
+}
+
+export const agentTurnConstant = ConstantRegistry.buildScalar("agentTurn" as const, AgentTurn, {
+  AgentTurn,
+  AgentStop,
+});