akanjs 3.0.0-beta.13 → 3.0.0-beta.15

package/common/codeAgentWire.ts

@@ -0,0 +1,409 @@
+import type { CodeAgentApprovalPolicy, CodeAgentInteractionMode, CodeAgentProfile } from "./codeAgentProfile";
+
+/**
+ * The wire between a code agent core and whatever is driving it — the terminal TUI, the non-interactive stream
+ * printer, or a browser over a relay. It is the only thing the two sides share, so it lives here: a browser
+ * bundle has to know these types and cannot import the CLI.
+ *
+ * **These events are ours, not the engine's.** They are a deliberate narrowing of what the underlying agent
+ * loop emits, so an engine upgrade stops at the core instead of reaching every host and the web UI. The cost is
+ * one mapping function in the core; the alternative is a version bump that breaks three consumers at once.
+ *
+ * **Nothing here carries a payload proportional to a file.** A `write` call's arguments are the whole new file
+ * body and a `read` result is the whole old one; putting either on the wire sends hundreds of KB per edit to a
+ * browser and then keeps it there. Labels are clipped to {@link codeAgentLabelChars} and outputs to
+ * {@link codeAgentOutputChars}, with `truncated` saying so. The unclipped text lives in the transcript the core
+ * owns, which is where a model reads it from anyway.
+ *
+ * **`seq` belongs to a transport, not to the session end to end.** It is monotonic for the life of one
+ * connection, and a relay that merges these frames with its own **re-stamps** them — otherwise a client holds
+ * two watermarks and the order between the two streams is undefined. A reconnecting client replays from the
+ * last `seq` it saw on *that* transport, and resets to 0 when the session changes, or every frame of the next
+ * session reads as a duplicate.
+ */
+
+export const codeAgentWireVersion = 1;
+
+/** One line in a collapsed row. */
+export const codeAgentLabelChars = 200;
+/** A tool result on the wire. The model's own copy is not clipped. */
+export const codeAgentOutputChars = 2_000;
+
+/** How hard the model is asked to think before it answers. */
+export type CodeAgentEffort = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+
+export interface CodeAgentSessionInfo {
+  sessionId: string;
+  cwd: string;
+  profile: string;
+  model: { provider: string; id: string; name: string } | undefined;
+  tools: string[];
+  /** Absent when the model reports no window, which is not the same as a window of zero. */
+  contextTokens: number | undefined;
+  /** Absent when the model does no reasoning at all — which is not the same as reasoning turned `off`. */
+  effort: CodeAgentEffort | undefined;
+  /** What this session calls itself, once it has been asked something. */
+  name: string | undefined;
+  /**
+   * Whether asking a person ends the turn, read once instead of inferred per question.
+   *
+   * `await`: the question happens **inside** a turn, the `turnId` does not change, and no `turn_end` is
+   * emitted for it. `suspend`: the core emits `turn_end` with `awaiting` right after `question`, and the
+   * answer opens a **new** turn with a new `turnId`. A host that treated "question" as a turn boundary in both
+   * would either split a turn that never ended or merge two that did.
+   */
+  interaction: { question: CodeAgentInteractionMode; approval: CodeAgentInteractionMode };
+}
+
+/**
+ * Why a turn ended.
+ *
+ * `awaiting` means a person was asked something and the turn was closed to wait for them — it is reported only
+ * by a profile whose `interaction` suspends; one that awaits keeps the question inside the turn and never emits
+ * it. A host reads {@link CodeAgentSessionInfo.interaction} once to know which shape to expect.
+ *
+ * **`truncated` is a partial success, not a failure.** The model hit its output cap mid-answer: the text that
+ * arrived is real and must be kept, and the useful offer is "continue", not "retry". Folding it into `done` is
+ * the expensive mistake — the answer is then stored as complete, and on the next turn the memory window
+ * replays it as something the model finished saying, so every later turn reasons from a sentence that stopped
+ * in the middle. Folding it into `error` is the other one: it throws away good output and offers a retry that
+ * will truncate at the same place.
+ *
+ * `maxTurns` is a limit on how many times the agent loops, not on how long one message is. Nothing in the core
+ * emits it today; it is here for a host that imposes its own ceiling.
+ *
+ * **Order contract, in force for every profile:**
+ * - an assistant `message` for a turn is always emitted **before** that turn's `turn_end`;
+ * - that holds for `aborted` and `truncated` too — whatever the model produced before the cut is emitted,
+ *   because a host that persists on the terminal frame would otherwise store an answer-less turn and the
+ *   symptom reads as "interrupting loses the reply".
+ */
+export type CodeAgentStopReason = "done" | "aborted" | "truncated" | "error" | "awaiting" | "maxTurns";
+
+/**
+ * `blocked` is not a flavour of `error` — a blocked call never executes, so a host that counts errors, derives
+ * a file tree from writes, or retries failures must be able to tell the two apart.
+ */
+export type CodeAgentToolOutcome = "ok" | "error" | "blocked";
+
+/** What the call does to the workspace, so a host can react without learning every tool name. */
+export type CodeAgentToolOp = "read" | "write" | "delete" | "list" | "search" | "execute" | "other";
+
+/**
+ * Carried on **both** the start and the end frame.
+ *
+ * A host folding by `toolCallId` replaces the part on the end frame; a summary present only on start leaves a
+ * finished `bash` labelled "bash" with the command gone.
+ */
+export interface CodeAgentToolSummary {
+  toolCallId: string;
+  name: string;
+  op: CodeAgentToolOp;
+  /**
+   * The file this call names, when it names one.
+   *
+   * ⚠️ **Progress, not a change list.** An edit made through `bash` — `sed -i`, `mv`, a codemod, a script —
+   * names no path here, and neither does the sweep of generated barrels a single `akan sync` rewrites, which
+   * is most of the files a scaffold touches. A `blocked` call names a path it never wrote. Anything that has
+   * to be *correct* about what changed reads `git status`; this field is for showing the row.
+   */
+  path?: string;
+  /** Clipped to {@link codeAgentLabelChars}. */
+  title: string;
+}
+
+export interface CodeAgentQuestionOption {
+  key: string;
+  label: string;
+  detail?: string;
+  /** The one to take when the user says "you decide". */
+  recommended?: boolean;
+}
+
+/**
+ * A question is a conversation turn; an approval is a gate on one tool call. They differ in every property that
+ * matters — cardinality, lifetime, whether they survive into the transcript — so they are two events, not one
+ * with a discriminator.
+ */
+export interface CodeAgentQuestion {
+  questionId: string;
+  prompt: string;
+  kind: "text" | "select" | "confirm";
+  options?: CodeAgentQuestionOption[];
+  multiSelect?: boolean;
+  /** Whether a free-text answer is accepted alongside, or instead of, the options. */
+  freeText?: boolean;
+}
+
+/**
+ * Structured, not a string: a multi-select answer joined into prose cannot be parsed back, so a client that
+ * reconnects cannot restore which boxes were ticked. The prose the transcript needs is derived once, by
+ * {@link codeAgentRenderAnswer}, rather than by each host separately.
+ */
+export interface CodeAgentAnswer {
+  keys?: string[];
+  text?: string;
+}
+
+export interface CodeAgentApprovalRequest {
+  approvalId: string;
+  toolCallId: string;
+  name: string;
+  /** What the call will do, rendered and clipped. */
+  summary: string;
+  policy: CodeAgentApprovalPolicy;
+}
+
+export type CodeAgentEventBody =
+  | { type: "session"; info: CodeAgentSessionInfo }
+  | { type: "turn_start"; turnId: string }
+  | { type: "turn_end"; turnId: string; stopReason: CodeAgentStopReason }
+  | { type: "text_delta"; turnId: string; text: string }
+  | { type: "thinking_delta"; turnId: string; text: string }
+  | { type: "message"; turnId: string; role: "user" | "assistant"; text: string }
+  | { type: "tool_start"; turnId: string; tool: CodeAgentToolSummary }
+  | { type: "tool_progress"; turnId: string; toolCallId: string; text: string }
+  | {
+      type: "tool_end";
+      turnId: string;
+      tool: CodeAgentToolSummary;
+      outcome: CodeAgentToolOutcome;
+      output: string;
+      truncated: boolean;
+    }
+  | { type: "question"; question: CodeAgentQuestion }
+  | { type: "question_resolved"; questionId: string; answer: CodeAgentAnswer; rendered: string }
+  | { type: "approval"; request: CodeAgentApprovalRequest }
+  | { type: "approval_resolved"; approvalId: string; approved: boolean }
+  | { type: "context"; used: number; max: number | undefined }
+  | { type: "compaction"; phase: "start" | "end"; reason: "manual" | "threshold" | "overflow" }
+  | { type: "retry"; attempt: number; maxAttempts: number; delayMs: number; message: string }
+  | { type: "queue"; steering: string[]; followUp: string[] }
+  | { type: "notice"; level: "info" | "warning" | "error"; message: string }
+  | { type: "error"; message: string; fatal: boolean }
+  | { type: "idle" }
+  /**
+   * A frame the **host** made, carried in the core's sequence so it orders against engine frames.
+   *
+   * `kind` is opaque here: no code in this file or in the core branches on its value. Plan steps, warming and
+   * preview lifecycle, deployment progress — all of them belong to whoever runs the agent, and a second channel
+   * for them would leave their order against `text_delta` undefined. When `id` is present a client **upserts**
+   * by it, because one step emitting pending → running → done must be one row, not three.
+   *
+   * `persist` is per **frame**, not per `kind`: the same plan step is worth storing when it reports `done` and
+   * must not be stored while it is still `pending`, because a step that never started reads later as one that
+   * did. It defaults to false — a host that forgets to set it loses a row, which is cheaper than a permanent
+   * record of every transient status it ever emitted.
+   */
+  | { type: "host"; kind: string; id?: string; persist?: boolean; payload: unknown };
+
+export type CodeAgentEvent = CodeAgentEventBody & { seq: number };
+
+export type CodeAgentEventType = CodeAgentEventBody["type"];
+
+/**
+ * Whether an event belongs in a stored transcript or only on a live screen.
+ *
+ * Folding and persisting are different rules, and conflating them is a bug in both directions: a `pending`
+ * step written to permanent history reads later as "this was done", and a reconnecting client that replays
+ * only persisted frames loses the tool row it was watching.
+ *
+ * **A transcript is not a memory window.** What a person sees on reopening and what the model is given on the
+ * next turn are two questions, and this table answers only the first. The memory window is derived from
+ * `message` rows and nothing else — a summariser fed `turn_start`, `turn_end` and `compaction` rows spends its
+ * input on bookkeeping. That is also why a question and its answer are rendered into message text rather than
+ * left as structure: the next turn reads content, not frames.
+ *
+ * `host` is the one entry the table cannot settle, because the same `kind` persists in one frame and not in the
+ * next. Its row is the default; the frame's own `persist` decides. Use {@link codeAgentShouldPersist}.
+ */
+export const codeAgentEventPersistence: { [key in CodeAgentEventType]: "live" | "persist" } = {
+  session: "live",
+  turn_start: "persist",
+  turn_end: "persist",
+  text_delta: "live",
+  thinking_delta: "live",
+  message: "persist",
+  tool_start: "live",
+  tool_progress: "live",
+  tool_end: "persist",
+  question: "persist",
+  question_resolved: "persist",
+  approval: "live",
+  approval_resolved: "live",
+  context: "live",
+  compaction: "persist",
+  retry: "live",
+  queue: "live",
+  notice: "live",
+  error: "persist",
+  idle: "live",
+  host: "live",
+};
+
+/**
+ * `answer` and `approve` are separate from `prompt` on purpose: answering a pending question is not a new
+ * instruction, and a host that routed it through `prompt` would open a turn while the question slot is still
+ * occupied — leaving a card on screen that still looks clickable.
+ */
+/**
+ * A browser holds bytes and a terminal holds a path, so `string[]` would be implemented differently on each
+ * side and diverge the first time one of them handed the other its own form.
+ */
+export type CodeAgentImage = { path: string } | { data: string; mime: string };
+
+/**
+ * The name a session takes from the first thing it was asked.
+ *
+ * Derived from the text rather than written by the model: a session name is worth one glance in a list, and
+ * generating one would be a second request standing between the person and their first answer — charged again
+ * on every session that is opened and abandoned.
+ */
+export const codeAgentSessionName = (text: string, max = 40) => {
+  const words = text
+    .replace(/```[\s\S]*?```/g, " ")
+    .replace(/[^\p{L}\p{N}]+/gu, " ")
+    .trim()
+    .toLowerCase()
+    .split(/\s+/)
+    .filter((word) => !!word);
+  const name: string[] = [];
+  for (const word of words) {
+    if (name.length && [...name, word].join("-").length > max) break;
+    name.push(word);
+  }
+  return name.join("-").slice(0, max) || "session";
+};
+
+export type CodeAgentCommand =
+  | { type: "prompt"; message: string; images?: CodeAgentImage[]; deliverAs?: "steer" | "followUp" }
+  | { type: "answer"; questionId: string; answer: CodeAgentAnswer }
+  | { type: "approve"; approvalId: string; approved: boolean }
+  | { type: "abort" }
+  | { type: "compact"; instructions?: string }
+  | { type: "set_model"; provider: string; modelId: string }
+  | { type: "fork"; entryId: string }
+  | { type: "new_session" }
+  /**
+   * Current state, plus every frame after `sinceSeq` when one is given.
+   *
+   * A browser that reloads mid-turn needs the frames it missed, not a snapshot: the completed messages survive
+   * in the transcript either way, but the `text_delta` and `tool_start` frames of the bubble still being
+   * written exist nowhere else. A terminal host never discovers this — its process and its session die
+   * together — which is why it is in the contract rather than waiting for the web host to find it.
+   */
+  | { type: "get_state"; sinceSeq?: number }
+  | { type: "shutdown" };
+
+export type CodeAgentCommandType = CodeAgentCommand["type"];
+
+export interface CodeAgentRequest {
+  id: string;
+  command: CodeAgentCommand;
+}
+
+export interface CodeAgentReply {
+  type: "reply";
+  id: string;
+  ok: boolean;
+  error?: string;
+  data?: unknown;
+}
+
+export type CodeAgentFrame = ({ type: "event" } & { event: CodeAgentEvent }) | CodeAgentReply;
+
+export const isCodeAgentReply = (frame: CodeAgentFrame): frame is CodeAgentReply => frame.type === "reply";
+
+/** The table, with a `host` frame's own `persist` taking precedence over the default. */
+export const codeAgentShouldPersist = (event: CodeAgentEventBody) =>
+  event.type === "host" ? event.persist === true : codeAgentEventPersistence[event.type] === "persist";
+
+export const codeAgentClip = (text: string, max: number) => (text.length <= max ? text : `${text.slice(0, max - 1)}…`);
+
+/**
+ * The prose form of an answer, made once.
+ *
+ * Compaction and the next turn read `role`/`content` only, so an answer that exists solely as structure is an
+ * answer the agent will not remember giving.
+ */
+export const codeAgentRenderAnswer = (question: CodeAgentQuestion, answer: CodeAgentAnswer) => {
+  const labels = (answer.keys ?? []).map((key) => question.options?.find((option) => option.key === key)?.label ?? key);
+  return [labels.join(", "), answer.text].filter(Boolean).join(" — ");
+};
+
+const toolOutcomeMark: { [key in CodeAgentToolOutcome]: string } = { ok: "✓", error: "✗", blocked: "⦸" };
+
+/** A one-line rendering of an event, shared by the stream printer and the TUI so the two cannot drift. */
+export const codeAgentEventLabel = (event: CodeAgentEventBody): string => {
+  switch (event.type) {
+    case "session":
+
+      return [
+        `session ${event.info.sessionId}`,
+        event.info.model?.name ?? "no model",
+        event.info.contextTokens ? `${Math.round(event.info.contextTokens / 1000)}k ctx` : "unknown ctx",
+        event.info.profile,
+      ].join(" · ");
+    case "turn_start":
+      return "turn start";
+    case "turn_end":
+      return event.stopReason === "truncated"
+        ? "turn end — the answer was cut off at the model's output limit"
+        : `turn end (${event.stopReason})`;
+    case "text_delta":
+      return event.text;
+    case "thinking_delta":
+      return event.text;
+    case "message":
+      return `${event.role}: ${event.text}`;
+    case "tool_start":
+      return `→ ${event.tool.title}`;
+    case "tool_end":
+      return `${toolOutcomeMark[event.outcome]} ${event.tool.title}`;
+    case "tool_progress":
+      return `  ${event.text}`;
+    case "question":
+      return `? ${event.question.prompt}`;
+    case "question_resolved":
+      return `= ${event.rendered}`;
+    case "approval":
+      return `approve? ${event.request.summary}`;
+    case "approval_resolved":
+      return event.approved ? "approved" : "denied";
+    case "context":
+      return `context ${event.used}${event.max ? `/${event.max}` : ""}`;
+    case "compaction":
+      return `compaction ${event.phase} (${event.reason})`;
+    case "retry":
+      return `retry ${event.attempt}/${event.maxAttempts} in ${event.delayMs}ms — ${event.message}`;
+    case "queue":
+      return `queued ${event.steering.length} steering, ${event.followUp.length} follow-up`;
+    case "notice":
+      return `[${event.level}] ${event.message}`;
+    case "error":
+      return `error: ${event.message}`;
+    case "idle":
+      return "idle";
+    case "host":
+      return `${event.kind}${event.id ? ` ${event.id}` : ""}`;
+    default:
+      return "";
+  }
+};
+
+export interface CodeAgentState {
+  info: CodeAgentSessionInfo;
+  streaming: boolean;
+  /** Present only when `get_state` asked for a replay. Empty when nothing was missed. */
+  frames?: CodeAgentEvent[];
+  /** How far back a replay can reach. A client behind this must reload the transcript instead. */
+  replayFrom: number;
+}
+
+export interface CodeAgentStartOptions {
+  cwd: string;
+  profile: CodeAgentProfile;
+  model?: { provider: string; id: string };
+  /** Resume this session instead of opening a new one. */
+  sessionId?: string;
+}

package/common/index.ts

@@ -7,6 +7,8 @@ export {
   legacyAuthTokenKey,
   readAuthToken,
 } from "./authToken";
+export { CodeAgentClient, type CodeAgentTransport } from "./CodeAgentClient";
+export { CodeTranscript, type CodeTranscriptPart } from "./CodeTranscript";
 export { capitalize } from "./capitalize";
 export { clamp } from "./clamp";
 export {
@@ -15,6 +17,52 @@ export {
   forwardedHeaders,
   normalizeIpAddress,
 } from "./clientAddress";
+export {
+  type CodeAgentApprovalPolicy,
+  type CodeAgentBuiltinTool,
+  type CodeAgentInteractionMode,
+  type CodeAgentMcpServerRef,
+  type CodeAgentPresetName,
+  type CodeAgentProfile,
+  type CodeAgentSubagentBudget,
+  codeAgentDeniedPaths,
+  codeAgentPresets,
+  codeAgentReadOnlyBuiltins,
+  isCodeAgentPresetName,
+} from "./codeAgentProfile";
+export {
+  type CodeAgentAnswer,
+  type CodeAgentApprovalRequest,
+  type CodeAgentCommand,
+  type CodeAgentCommandType,
+  type CodeAgentEffort,
+  type CodeAgentEvent,
+  type CodeAgentEventBody,
+  type CodeAgentEventType,
+  type CodeAgentFrame,
+  type CodeAgentImage,
+  type CodeAgentQuestion,
+  type CodeAgentQuestionOption,
+  type CodeAgentReply,
+  type CodeAgentRequest,
+  type CodeAgentSessionInfo,
+  type CodeAgentStartOptions,
+  type CodeAgentState,
+  type CodeAgentStopReason,
+  type CodeAgentToolOp,
+  type CodeAgentToolOutcome,
+  type CodeAgentToolSummary,
+  codeAgentClip,
+  codeAgentEventLabel,
+  codeAgentEventPersistence,
+  codeAgentLabelChars,
+  codeAgentOutputChars,
+  codeAgentRenderAnswer,
+  codeAgentSessionName,
+  codeAgentShouldPersist,
+  codeAgentWireVersion,
+  isCodeAgentReply,
+} from "./codeAgentWire";
 export { deepObjectify } from "./deepObjectify";
 export type { DynamicRecord } from "./dynamicRecord";
 export { EventStream, type EventStreamOptions } from "./eventStream";
@@ -66,6 +114,9 @@ export {
   registerLogContextReader,
 } from "./logContext";
 export { lowerlize } from "./lowerlize";
+export { type MarkdownBlock, MarkdownBlocks, type MarkdownItem } from "./markdownBlocks";
+export { type MarkdownSpan, MarkdownSpans } from "./markdownSpans";
+export { type Align, MarkdownTable, type TableBlock } from "./markdownTable";
 export {
   isMcpDescribableArg,
   type McpExposureEndpoint,

package/common/markdownSpans.ts

@@ -0,0 +1,57 @@
+export type MarkdownSpan =
+  | { kind: "text"; text: string }
+  | { kind: "code"; text: string }
+  | { kind: "strong"; text: string }
+  | { kind: "em"; text: string }
+  | { kind: "del"; text: string }
+  | { kind: "link"; text: string; href: string }
+  /** A link whose href was refused, or an image: rendered as its label, by every host. */
+  | { kind: "plain"; text: string };
+
+const inline =
+  /(!?)\[([^\]]*)\]\(((?:[^\s()]|\([^\s()]*\))+)\)|`([^`]+)`|\*\*([\s\S]+?)\*\*|\*([^*\n]+?)\*|~~([\s\S]+?)~~/g;
+
+/**
+ * The inline scanner both hosts read: a browser turns these into elements, a terminal into styled text.
+ *
+ * It is here rather than beside either renderer because the two decisions that matter are not rendering
+ * decisions. **A link's scheme is refused for everyone** — this text comes from a model and from tool results
+ * carrying stored user input, and React writes a `javascript:` href out as given. And **underscore emphasis is
+ * deliberately unmatched**: snake_case is everywhere in this content, and `some_var_name` italicising mid-word
+ * reads worse than a literal `_emphasis_` does.
+ */
+export class MarkdownSpans {
+  static of(text: string): MarkdownSpan[] {
+    const spans: MarkdownSpan[] = [];
+    let cut = 0;
+    for (const match of text.matchAll(inline)) {
+      const at = match.index;
+      const [, image, label, href, code, strong, em, del] = match;
+      if (at > cut) spans.push({ kind: "text", text: text.slice(cut, at) });
+      cut = at + match[0].length;
+      if (href !== undefined)
+        spans.push(
+          image || !MarkdownSpans.isSafeHref(href)
+            ? { kind: "plain", text: label ?? "" }
+            : { kind: "link", text: label ?? "", href },
+        );
+      else if (code !== undefined) spans.push({ kind: "code", text: code });
+      else if (strong !== undefined) spans.push({ kind: "strong", text: strong });
+      else if (em !== undefined) spans.push({ kind: "em", text: em });
+      else if (del !== undefined) spans.push({ kind: "del", text: del });
+    }
+    if (cut < text.length) spans.push({ kind: "text", text: text.slice(cut) });
+    return spans;
+  }
+
+  static isSafeHref(href: string) {
+    return !/^[a-z][a-z0-9+.-]*:/i.test(href) || /^(?:https?|mailto|tel):/i.test(href);
+  }
+
+  /** The text with every marker removed, for a host that has no styling to give — a width measurement, a log. */
+  static plain(text: string): string {
+    return MarkdownSpans.of(text)
+      .map((span) => (span.kind === "link" ? span.text : span.text))
+      .join("");
+  }
+}

package/dictionary/agent.dictionary.ts

@@ -24,16 +24,9 @@ export const agentDictionary = serviceDictionary(["en", "ko"])
       "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}",
-    ],
-    openaiRequestFailed: [
-      "OpenAI refused this turn with status {status}. Reason: {reason}",
-      "OpenAI가 이번 턴을 거절했습니다 (status {status}). 사유: {reason}",
-    ],
-    anthropicRequestFailed: [
-      "Anthropic refused this turn with status {status}. Reason: {reason}",
-      "Anthropic이 이번 턴을 거절했습니다 (status {status}). 사유: {reason}",
+
+    llmRequestFailed: [
+      "{provider} refused this turn with status {status}. Reason: {reason}",
+      "{provider}가 이번 턴을 거절했습니다 (status {status}). 사유: {reason}",
     ],
   });

package/dictionary/base.dictionary.ts

@@ -75,6 +75,7 @@ export const baseDictionary = serviceDictionary(["en", "ko"])
     agentPlaceholder: ["Message the agent...", "에이전트에게 메시지..."],
     agentClear: ["Clear conversation", "대화 비우기"],
     agentQuestion: ["The agent needs your decision", "에이전트가 결정을 요청합니다"],
+    agentToolCard: ["The agent needs you to fill this in", "에이전트가 입력을 요청합니다"],
     agentAnswer: ["Type your answer...", "답변을 입력하세요..."],
     agentListen: ["Speak to the agent", "에이전트에게 말하기"],
     agentVoiceFailed: ["The microphone could not be used.", "마이크를 사용할 수 없습니다."],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-beta.13",
+  "version": "3.0.0-beta.15",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -198,8 +198,10 @@
     }
   },
   "dependencies": {
+    "@lexical/plain-text": "^0.51.0",
     "dayjs": "^1.11.20",
     "immer": "^11.1.8",
+    "lexical": "^0.51.0",
     "tailwind-merge": "^3.3.1",
     "tailwind-variants": "^3.3.0"
   },

package/server/akanOption.ts

@@ -73,8 +73,15 @@ export class AkanOption<Env extends BackendEnv = BackendEnv> {
     this.#crossSite = crossSite;
     return this;
   }
-  /** Settings for whichever adaptor fills `LlmAdaptorRole`, injected into it as the `llmOption` use. */
-  setLlm(llmOrFn: LlmOption | ((env: Env) => LlmOption)) {
+  /**
+   * Settings for whichever adaptor fills `LlmAdaptorRole`, injected into it as the `llmOption` use.
+   *
+   * The argument is generic so that whatever an adaptor needs beyond `LlmOption` travels here too: an adaptor an
+   * app or a library wrote declares its own interface extending it, reads it with `use<MyLlmOption>()`, and its
+   * region or project id rides the same channel the shipped fields do. Entries merge in mount order with the
+   * app's last, so a library may name a host and the app the key.
+   */
+  setLlm<Option extends LlmOption>(llmOrFn: Option | ((env: Env) => Option)) {
     if (typeof llmOrFn === "function") this.#getLlms.push(llmOrFn);
     else this.#getLlms.push(() => llmOrFn);
     return this;

package/server/di/predefinedAdaptor.ts

@@ -10,13 +10,13 @@ import {
   ConsoleLogger,
   type DatabaseAdaptor,
   DatabaseAdaptorRole,
-  DeepseekLlm,
   JsonCompressor,
   LibsqlDatabase,
   type LlmAdaptor,
   LlmAdaptorRole,
   type LoggingAdaptor,
   LoggingAdaptorRole,
+  OpenaiLlm,
   PostgresDatabase,
   type QueueAdaptor,
   QueueAdaptorRole,
@@ -68,7 +68,7 @@ export const predefinedAdaptor = {
   logging: ConsoleLogger,
   websocket: SolidPubSub,
   compress: JsonCompressor,
-  llm: DeepseekLlm,
+  llm: OpenaiLlm,
 };
 
 export const getPredefinedAdaptor = (mode: DatabaseMode = "single"): PredefinedAdaptor => {

package/service/predefinedAdaptor/anthropicLlm.ts

@@ -9,6 +9,7 @@ import type {
   LlmTurnAnswer,
   LlmTurnRequest,
 } from "./llm.adaptor";
+import { llmProviderOf } from "./llm.adaptor";
 
 type AnthropicSource = { type: "base64"; media_type: string; data: string } | { type: "url"; url: string };
 type AnthropicBlock =
@@ -136,7 +137,7 @@ export class AnthropicLlm
       
       signal: AbortSignal.timeout(120_000),
     });
-    if (!response.ok) throw await AnthropicLlm.refusal(response);
+    if (!response.ok) throw await AnthropicLlm.refusal(this.#host, response);
     return (await response.json()) as T;
   }
 
@@ -147,12 +148,13 @@ export class AnthropicLlm
       body: JSON.stringify(body),
       signal: AbortSignal.timeout(120_000),
     });
-    if (!response.ok || !response.body) throw await AnthropicLlm.refusal(response);
+    if (!response.ok || !response.body) throw await AnthropicLlm.refusal(this.#host, response);
     return response.body;
   }
 
-  static async refusal(response: Response): Promise<Error> {
-    return new Err("agent.error.anthropicRequestFailed", {
+  static async refusal(host: string, response: Response): Promise<Error> {
+    return new Err("agent.error.llmRequestFailed", {
+      provider: llmProviderOf(host),
       status: String(response.status),
       reason: await AnthropicLlm.reasonOf(response),
     });