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

package/ui/Agent/mentionDraft.ts

@@ -0,0 +1,101 @@
+"use client";
+import {
+  $createLineBreakNode,
+  $createParagraphNode,
+  $createTextNode,
+  $getRoot,
+  $getSelection,
+  $isElementNode,
+  $isRangeSelection,
+  $isRootNode,
+  $isTextNode,
+  type LexicalNode,
+} from "lexical";
+import { Reference } from "../../vendor/use-agentic";
+import { $createMentionNode, $isMentionNode } from "./MentionNode";
+
+/**
+ * The two directions between the composer's draft string and what the editor holds. The string stays the source
+ * of truth for the rest of the chat — it is what carries the `@[…](mention:…)` tokens onto the message — and the
+ * editor is one way of drawing it, so every offset here is an offset into **that string**, never into what the
+ * screen shows.
+ */
+export class MentionDraft {
+  /** Runs inside an editor read or update, like every `$` function. */
+  static read(): string {
+    return $getRoot().getTextContent();
+  }
+
+  /** Rebuilds the whole content from a draft string — the path every write that is not a keystroke takes. */
+  static write(text: string, caretAt?: number) {
+    const paragraph = $createParagraphNode();
+    paragraph.append(...MentionDraft.nodesOf(text));
+    $getRoot().clear().append(paragraph);
+    MentionDraft.place(caretAt ?? text.length);
+  }
+
+  static nodesOf(text: string): LexicalNode[] {
+    const nodes: LexicalNode[] = [];
+    let at = 0;
+
+    const pattern = new RegExp(Reference.pattern.source, "g");
+    for (let match = pattern.exec(text); match; match = pattern.exec(text)) {
+      const [token, label, refName, refId, path] = match;
+      if (match.index > at) nodes.push(...MentionDraft.#plain(text.slice(at, match.index)));
+      nodes.push($createMentionNode({ refName, refId, label, ...(path ? { path } : {}) }));
+      at = match.index + token.length;
+    }
+    if (at < text.length) nodes.push(...MentionDraft.#plain(text.slice(at)));
+    return nodes;
+  }
+
+  /** Where the caret sits in the draft string, or `null` when there is no collapsed caret to report. */
+  static caret(): number | null {
+    const selection = $getSelection();
+    if (!$isRangeSelection(selection)) return null;
+    const anchor = selection.anchor;
+    const node = anchor.getNode();
+    if ($isTextNode(node)) {
+      
+      const inner = $isMentionNode(node) ? (anchor.offset ? node.getTextContent().length : 0) : anchor.offset;
+      return MentionDraft.#before(node) + inner;
+    }
+    const children = $isElementNode(node) ? node.getChildren() : [];
+    const within = children.slice(0, anchor.offset).reduce((sum, child) => sum + child.getTextContent().length, 0);
+    return MentionDraft.#before(node) + within;
+  }
+
+  /** Puts the caret at a draft-string offset. Past the end, or inside a mention, it lands on the nearest edge. */
+  static place(at: number) {
+    const paragraph = $getRoot().getLastChild();
+    if (!$isElementNode(paragraph)) return;
+    let seen = 0;
+    for (const child of paragraph.getChildren()) {
+      const length = child.getTextContent().length;
+      if (at <= seen + length) {
+
+        if ($isTextNode(child) && !$isMentionNode(child)) child.select(at - seen, at - seen);
+        else if (at > seen) child.selectNext(0, 0);
+        else if (child.getPreviousSibling()) child.selectPrevious();
+        else paragraph.select(0, 0);
+        return;
+      }
+      seen += length;
+    }
+    paragraph.selectEnd();
+  }
+
+  static #plain(text: string): LexicalNode[] {
+    return text
+      .split("\n")
+      .flatMap((line, idx) => [...(idx ? [$createLineBreakNode()] : []), ...(line ? [$createTextNode(line)] : [])]);
+  }
+
+  static #before(node: LexicalNode): number {
+    let sum = 0;
+    for (let cursor = node.getPreviousSibling(); cursor; cursor = cursor.getPreviousSibling())
+      sum += cursor.getTextContent().length;
+    const parent = node.getParent();
+    return parent && !$isRootNode(parent) ? sum + MentionDraft.#before(parent) : sum;
+  }
+}

package/ui/Agent/useChatReferences.ts

@@ -1,13 +1,14 @@
 "use client";
 import { type RefObject, useEffect, useMemo, useRef } from "react";
 import { type AgentSession, type MessageReference, Reference } from "../../vendor/use-agentic";
+import type { ComposerHandle } from "./Composer";
 
 interface ChatReferencesSetup {
   session: AgentSession;
   draft: string;
   /** The chat's own version snapshot — a `refer` from anywhere on the page is one of the changes it counts. */
   version: number;
-  inputRef: RefObject<HTMLTextAreaElement | null>;
+  handleRef: RefObject<ComposerHandle | null>;
   onDraft: (text: string) => void;
 }
 
@@ -21,16 +22,15 @@ interface ChatReferencesSetup {
  * whose value was never staged (pasted out of an earlier message) travels as a pointer with a note saying to read
  * it again, which is the same shape a restored conversation produces.
  */
-export const useChatReferences = ({ session, draft, version, inputRef, onDraft }: ChatReferencesSetup) => {
+export const useChatReferences = ({ session, draft, version, handleRef, onDraft }: ChatReferencesSetup) => {
   const caret = useRef<number | null>(null);
 
   useEffect(() => session.attachChat(), [session]);
   useEffect(() => {
     const pending = session.pendingInserts;
     if (!pending.length) return;
-    const area = inputRef.current;
 
-    const at = area ? area.selectionStart : draft.length;
+    const at = handleRef.current?.caret() ?? draft.length;
     const head = draft.slice(0, at);
     const tail = draft.slice(at);
     const tokens = pending.map((one) => Reference.token(one)).join(" ");
@@ -44,11 +44,8 @@ export const useChatReferences = ({ session, draft, version, inputRef, onDraft }
     const at = caret.current;
     if (at === null) return;
     caret.current = null;
-    const area = inputRef.current;
-    if (!area) return;
     
-    area.focus();
-    area.setSelectionRange(at, at);
+    handleRef.current?.setCaret(at);
   }, [draft]);
   const references = useMemo<MessageReference[]>(() => {
     const staged = new Map(session.staged.map((one) => [Reference.keyOf(one), one]));

package/ui/UiOverride/context.ts

@@ -12,6 +12,7 @@ import type { MenuProps as AgentMenuProps } from "../Agent/Menu";
 import type { QuestionProps as AgentQuestionProps } from "../Agent/Question";
 import type { QueuedProps as AgentQueuedProps } from "../Agent/Queued";
 import type { StepsProps as AgentStepsProps } from "../Agent/Steps";
+import type { ToolCardProps as AgentToolCardProps } from "../Agent/ToolCard";
 import type { BadgeProps } from "../Badge";
 import type { ButtonProps } from "../Button";
 import type { DatePickerProps, RangePickerProps, TimePickerProps } from "../DatePicker";
@@ -74,6 +75,7 @@ export interface AkanUiOverrides {
   AgentQueued: ComponentType<AgentQueuedProps>;
   AgentMenu: ComponentType<AgentMenuProps>;
   AgentMarkdown: ComponentType<AgentMarkdownProps>;
+  AgentToolCard: ComponentType<AgentToolCardProps>;
   AgentCode: ComponentType<AgentCodeProps>;
 
   Button: ComponentType<ButtonProps<unknown>>;

package/ui/index.ts

@@ -36,7 +36,7 @@ export {
 export { type BubbleProps, DefaultBubble } from "./Agent/Bubble";
 export type { ChatProps } from "./Agent/Chat";
 export { type ChatCommand, ChatCommands } from "./Agent/ChatCommands";
-export { type ComposerProps, DefaultComposer } from "./Agent/Composer";
+export { type ComposerHandle, type ComposerProps, DefaultComposer } from "./Agent/Composer";
 export { fetchRunner } from "./Agent/fetchRunner";
 export type { HistoryProps as AgentHistoryProps } from "./Agent/History";
 export { DefaultLauncher, type LauncherProps } from "./Agent/Launcher";
@@ -51,6 +51,7 @@ export {
 export { DefaultSteps, type StepsProps } from "./Agent/Steps";
 export type { PersistOption } from "./Agent/sessionHistory";
 export type { AgentBuiltin, BuiltinOption } from "./Agent/sessionView";
+export { DefaultToolCard, type ToolCardProps } from "./Agent/ToolCard";
 export { tokenCount } from "./Agent/tokenCount";
 export type { QueuedMessage } from "./Agent/useChatQueue";
 export type { ReferenceCandidate, ReferenceSource } from "./Agent/useReferenceMenu";

package/vendor/use-agentic/AgentSession.ts

@@ -2,7 +2,7 @@ import type { AgentProgressReport } from "./AgentProgress";
 import { Compaction, type CompactOptions } from "./Compaction";
 import { Reference } from "./Reference";
 import { ToolOutput } from "./ToolOutput";
-import { type ToolApprovalRequest, ToolRunner } from "./ToolRunner";
+import { type ToolApprovalRequest, type ToolCardAnswer, type ToolCardRequest, ToolRunner } from "./ToolRunner";
 import { Transcript } from "./Transcript";
 import type {
   AgentRunner,
@@ -15,6 +15,7 @@ import type {
   ToolActivity,
   ToolCallRequest,
   ToolCallResult,
+  ToolCard,
   TurnStop,
 } from "./types";
 
@@ -40,6 +41,20 @@ export interface PendingQuestion {
   dismiss: (reason?: string) => void;
 }
 
+/**
+ * A call parked on a component the app declared with the tool — a form to fill in, a choice no list of strings
+ * could carry. The loop waits on it exactly as it waits on an approval, and `render` is the app's own, so the
+ * framework decides where the card sits and nothing about what it asks.
+ */
+export interface PendingCard {
+  callId: string;
+  name: string;
+  args: Record<string, unknown>;
+  render: ToolCard;
+  submit: (value: unknown) => void;
+  dismiss: (reason?: string) => void;
+}
+
 /**
  * Where a session keeps its transcript across page loads. Storage-neutral: the host decides what backs it, so a
  * server-side transcript is as legal as web storage — which is why every method may answer asynchronously. A
@@ -150,6 +165,7 @@ export class AgentSession {
   #running = false;
   #pending: PendingApproval | null = null;
   #question: PendingQuestion | null = null;
+  #card: PendingCard | null = null;
   #staged: MessageReference[] = [];
   #inserts: MessageReference[] = [];
   #chats = 0;
@@ -174,6 +190,7 @@ export class AgentSession {
     this.#options = options;
     this.#tools = new ToolRunner(surface, {
       approve: (request, signal) => this.#awaitApproval(request, signal),
+      card: (request, signal) => this.#awaitCard(request, signal),
       settle: () => this.#options.settle?.(),
       activity: (event) => this.#options.onActivity?.(event),
       progress: ({ callId, report }) => {
@@ -234,6 +251,10 @@ export class AgentSession {
     return this.#question;
   }
 
+  get pendingCard(): PendingCard | null {
+    return this.#card;
+  }
+
   /**
    * What the user has pointed at and not yet sent.
    *
@@ -426,6 +447,7 @@ export class AgentSession {
       this.#active = null;
       this.#pending = null;
       this.#question = null;
+      this.#card = null;
       this.#progress = null;
 
       const draft = this.#messages[this.#messages.length - 1];
@@ -712,6 +734,28 @@ export class AgentSession {
     });
   }
 
+  #awaitCard(request: ToolCardRequest, signal: AbortSignal): Promise<ToolCardAnswer> {
+    return new Promise((resolve) => {
+      const settle = (answer: ToolCardAnswer) => {
+        this.#card = null;
+        signal.removeEventListener("abort", onAbort);
+        this.#notify();
+        resolve(answer);
+      };
+      const onAbort = () => settle({ error: "The user aborted the turn." });
+      signal.addEventListener("abort", onAbort);
+      this.#card = {
+        callId: request.callId,
+        name: request.name,
+        args: request.args,
+        render: request.render,
+        submit: (value) => settle({ result: value }),
+        dismiss: (reason) => settle({ error: reason ?? "The user closed the card without filling it in." }),
+      };
+      this.#notify();
+    });
+  }
+
   #awaitApproval(request: ToolApprovalRequest, signal: AbortSignal): Promise<true | string> {
     return new Promise((resolve) => {
       const settle = (value: true | string) => {

package/vendor/use-agentic/AgenticSurface.ts

@@ -183,6 +183,8 @@ export class AgenticSurface {
     try {
       const verdict = entry.guard?.(args) ?? true;
       if (verdict !== true) throw new Error(verdict);
+      
+      if (!entry.run) throw new Error(`${name} is answered by the user, and this caller cannot ask them.`);
       return await entry.run(args);
     } catch (error) {
       record.error = error instanceof Error ? error.message : String(error);

package/vendor/use-agentic/ToolRunner.ts

@@ -1,7 +1,15 @@
 import { AgentAbort } from "./AgentAbort";
 import { AgentProgress, type AgentProgressReport } from "./AgentProgress";
 import { ToolOutput } from "./ToolOutput";
-import type { SurfaceView, ToolActivity, ToolCallRequest, ToolCallResult, ToolEntry } from "./types";
+import type {
+  SurfaceView,
+  ToolActivity,
+  ToolCallRequest,
+  ToolCallResult,
+  ToolCard,
+  ToolCardEntry,
+  ToolEntry,
+} from "./types";
 
 export interface ToolApprovalRequest {
   callId: string;
@@ -11,6 +19,17 @@ export interface ToolApprovalRequest {
   message: string;
 }
 
+/** A call whose answer the user writes, handed to the host with the component its declaration named. */
+export interface ToolCardRequest {
+  callId: string;
+  name: string;
+  args: Record<string, unknown>;
+  render: ToolCard;
+}
+
+/** What the card settled on: the value the model reads back, or why there is none. */
+export type ToolCardAnswer = { result: unknown } | { error: string };
+
 /** `report` is `null` once the call is over, carrying the id so a host can ignore a clear that is not its own. */
 export interface ToolProgress {
   callId: string;
@@ -30,6 +49,13 @@ export interface ToolRunnerHost {
    * a host that may not perform the action, and the refusal says so rather than silently downgrading the gate.
    */
   approve?: (request: ToolApprovalRequest, signal: AbortSignal) => Promise<true | string>;
+  /**
+   * Parks the call until the user fills in the card its declaration named, and answers with what they submitted.
+   *
+   * Omitting it refuses those calls rather than running something in their place: a card tool has no function to
+   * fall back to — the user *is* the implementation — so a host with nowhere to render one may not answer it.
+   */
+  card?: (request: ToolCardRequest, signal: AbortSignal) => Promise<ToolCardAnswer>;
   /**
    * Awaited after a tool that changed something and before its change report is taken. A surface is read
    * synchronously and a screen does not settle synchronously, so without this the report describes the moment
@@ -98,6 +124,7 @@ export class ToolRunner {
       const fallback = this.#host.fallback;
       return fallback ? await fallback(call, signal) : { ...base, error: `Unknown tool: ${call.name}` };
     }
+    if (entry.card) return await this.#carded(call, entry, signal);
     const message = ToolRunner.confirmMessage(call.name, entry, call.args);
     if (message) {
       const approve = this.#host.approve;
@@ -109,6 +136,33 @@ export class ToolRunner {
     return await ToolRunner.#serialized(() => this.#execute(call, entry, signal));
   }
 
+  /**
+   * A call the user answers. It waits **outside** the serialization queue, for the reason an approval does: a card
+   * parked in front of somebody is not work, and holding the lock across it would let one agent's unanswered form
+   * freeze every other agent on the page.
+   *
+   * The screen is still snapshotted around the wait, because a card that writes what it collected into a store is
+   * the ordinary case and the model has to be told what moved. Nothing is drawn through `activity` — that draws a
+   * call landing *on* the page, and this one lands in the chat.
+   */
+  async #carded(call: ToolCallRequest, entry: ToolCardEntry, signal: AbortSignal): Promise<ToolCallResult> {
+    const base = { id: call.id, name: call.name };
+    const verdict = entry.guard?.(call.args) ?? true;
+    if (verdict !== true) return { ...base, error: verdict };
+    const ask = this.#host.card;
+    if (!ask) return { ...base, error: `${call.name} is answered by the user, and nothing here can ask them.` };
+    const before = this.#surface.snapshot();
+    const answered = await ask({ callId: call.id, name: call.name, args: call.args, render: entry.card }, signal);
+    if ("error" in answered) return { ...base, error: answered.error };
+    if (entry.settle !== false) await this.#host.settle?.();
+    const changes = this.#surface.diffSince(before);
+    return {
+      ...base,
+      ...(answered.result !== undefined ? { result: answered.result } : {}),
+      ...(changes.length ? { changes } : {}),
+    };
+  }
+
   async #execute(call: ToolCallRequest, entry: ToolEntry, signal: AbortSignal): Promise<ToolCallResult> {
     const base = { id: call.id, name: call.name };
     const before = this.#surface.snapshot();

package/vendor/use-agentic/types.ts

@@ -1,3 +1,5 @@
+import type { ReactNode } from "react";
+
 export type JsonSchema = Record<string, unknown>;
 
 /** `true` asks with a default message, a string is the message, a function decides from the arguments. */
@@ -6,7 +8,24 @@ export type ToolConfirm = boolean | string | ((args: Record<string, unknown>) =>
 /** Re-checked at the moment of execution; a string is the refusal reason the agent reads. */
 export type ToolGuard = (args: Record<string, unknown>) => true | string;
 
-export interface ToolEntry {
+/**
+ * What a card tool renders while its call waits, and the two ways the user ends that wait. `submit` is the call's
+ * result, `cancel` is its refusal; whichever comes first settles the call and takes the card off the screen, so a
+ * second call of either does nothing.
+ */
+export interface ToolCardControl {
+  args: Record<string, unknown>;
+  submit: (value: unknown) => void;
+  cancel: (reason?: string) => void;
+}
+
+/**
+ * Called, not mounted — the host invokes it inside its own render, so the returned tree keeps no state of its
+ * own between renders. Put anything stateful in a component the function returns.
+ */
+export type ToolCard = (control: ToolCardControl) => ReactNode;
+
+interface ToolEntryBase {
   name: string;
   description?: string;
   parameters?: JsonSchema;
@@ -17,9 +36,25 @@ export interface ToolEntry {
   settle?: boolean;
   confirm?: ToolConfirm;
   guard?: ToolGuard;
+}
+
+export interface ToolActionEntry extends ToolEntryBase {
   run: (args: Record<string, unknown>) => unknown;
+  card?: never;
+}
+
+/**
+ * A call the **user** answers rather than the screen: the host parks the call, renders `card`, and what the card
+ * submits is what the model reads back. `confirm` is not read for one — the card in front of the user is already
+ * the asking, and a gate before it would ask them twice for one thing.
+ */
+export interface ToolCardEntry extends ToolEntryBase {
+  card: ToolCard;
+  run?: never;
 }
 
+export type ToolEntry = ToolActionEntry | ToolCardEntry;
+
 /**
  * That a call is happening, for a host drawing it on the screen rather than in a transcript.
  *

package/service/predefinedAdaptor/deepseekLlm.ts

@@ -1,82 +0,0 @@
-import { Err } from "akanjs/dictionary";
-import { adapt } from "../adapt";
-import type { LlmAdaptor, LlmOption, LlmTurnAnswer, LlmTurnRequest } from "./llm.adaptor";
-import { type OpenaiAnswer, OpenaiDialect } from "./openaiDialect";
-
-/**
- * The framework's default provider, and the one an app gets without choosing.
- *
- * `accepts` is left undeclared, so by the time an attachment reaches the dialect `AgentService.readable` has
- * reduced it to its text and turned everything else into a note. That is deliberate rather than pending: DeepSeek's
- * chat API is text, and an adaptor that claimed otherwise would hand it bytes it answers about having never seen.
- * An app that wants vision swaps the role — `option.applyAdaptor(LlmAdaptorRole, OpenaiLlm)` or `AnthropicLlm`.
- */
-export class DeepseekLlm
-  extends adapt("deepseekLlm" as const, ({ use }) => ({
-    llmOption: use<LlmOption>(),
-  }))
-  implements LlmAdaptor
-{
-  get #model() {
-    return this.llmOption.model ?? "deepseek-v4-flash";
-  }
-  get #host() {
-    return this.llmOption.host ?? "https://api.deepseek.com";
-  }
-
-  async chat(request: LlmTurnRequest, onDelta?: (delta: string) => void): Promise<LlmTurnAnswer | null> {
-    if (!this.llmOption.apiKey) {
-      this.logger.warn("No LLM API key is configured — set one with option.setLlm(). Agent turns are unavailable.");
-      return null;
-    }
-    try {
-      if (!onDelta) {
-        const answer = await this.#api<OpenaiAnswer>(
-          "/chat/completions",
-          OpenaiDialect.requestBody(this.#model, request),
-        );
-        return OpenaiDialect.turnAnswer(answer);
-      }
-      const body = await this.#apiStream(
-        "/chat/completions",
-        OpenaiDialect.requestBody(this.#model, request, { stream: true }),
-      );
-      return await OpenaiDialect.consumeStream(body, onDelta);
-    } catch (error) {
-
-      this.logger.error(`DeepSeek turn failed: ${error instanceof Error ? error.message : String(error)}`);
-      throw error;
-    }
-  }
-
-  async #api<T>(path: string, body: object): Promise<T> {
-    const response = await fetch(`${this.#host}${path}`, {
-      method: "POST",
-      headers: { "content-type": "application/json", authorization: `Bearer ${this.llmOption.apiKey}` },
-      body: JSON.stringify(body),
-      
-      signal: AbortSignal.timeout(120_000),
-    });
-    if (!response.ok) throw await DeepseekLlm.refusal(response);
-    return (await response.json()) as T;
-  }
-
-  async #apiStream(path: string, body: object): Promise<ReadableStream<Uint8Array>> {
-    const response = await fetch(`${this.#host}${path}`, {
-      method: "POST",
-      headers: { "content-type": "application/json", authorization: `Bearer ${this.llmOption.apiKey}` },
-      body: JSON.stringify(body),
-      signal: AbortSignal.timeout(120_000),
-    });
-    if (!response.ok || !response.body) throw await DeepseekLlm.refusal(response);
-    return response.body;
-  }
-
-  /** Carried on the `Err` so the chat prints the provider's own sentence rather than a status number. */
-  static async refusal(response: Response): Promise<Error> {
-    return new Err("agent.error.deepseekRequestFailed", {
-      status: String(response.status),
-      reason: await OpenaiDialect.reasonOf(response),
-    });
-  }
-}

package/types/service/predefinedAdaptor/deepseekLlm.d.ts

@@ -1,19 +0,0 @@
-import type { LlmAdaptor, LlmOption, LlmTurnAnswer, LlmTurnRequest } from "./llm.adaptor";
-declare const DeepseekLlm_base: import("..").AdaptorCls<{}, {
-    llmOption: import("..").InjectInfo<"use", LlmOption, never, never>;
-}>;
-/**
- * The framework's default provider, and the one an app gets without choosing.
- *
- * `accepts` is left undeclared, so by the time an attachment reaches the dialect `AgentService.readable` has
- * reduced it to its text and turned everything else into a note. That is deliberate rather than pending: DeepSeek's
- * chat API is text, and an adaptor that claimed otherwise would hand it bytes it answers about having never seen.
- * An app that wants vision swaps the role — `option.applyAdaptor(LlmAdaptorRole, OpenaiLlm)` or `AnthropicLlm`.
- */
-export declare class DeepseekLlm extends DeepseekLlm_base implements LlmAdaptor {
-    #private;
-    chat(request: LlmTurnRequest, onDelta?: (delta: string) => void): Promise<LlmTurnAnswer | null>;
-    /** Carried on the `Err` so the chat prints the provider's own sentence rather than a status number. */
-    static refusal(response: Response): Promise<Error>;
-}
-export {};