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

package/types/server/akanOption.d.ts

@@ -38,8 +38,15 @@ export declare class AkanOption<Env extends BackendEnv = BackendEnv> {
      * itself is on by default and `{ enabled: false }` is for an API no browser reaches.
      */
     setCrossSite(crossSite: CrossSiteOption): this;
-    /** Settings for whichever adaptor fills `LlmAdaptorRole`, injected into it as the `llmOption` use. */
-    setLlm(llmOrFn: LlmOption | ((env: Env) => LlmOption)): this;
+    /**
+     * 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)): this;
     /** Every entry in declaration order, duplicates kept: the boot stage rejects a key claimed twice. */
     getUses(env: Env): [string, PromiseOrObject<unknown>][];
     getMiddlewares(): MiddlewareCls[];

package/types/server/di/predefinedAdaptor.d.ts

@@ -1,5 +1,5 @@
 import type { DatabaseMode } from "akanjs";
-import { type AdaptorCls, BlobStorage, type CacheAdaptor, type CompressAdaptor, ConsoleLogger, type DatabaseAdaptor, DeepseekLlm, JsonCompressor, type LlmAdaptor, type LoggingAdaptor, type QueueAdaptor, type ScheduleAdaptor, Scheduler, SolidCache, SolidPubSub, SolidQueue, SqliteDatabase, type StorageAdaptor, type WebsocketAdaptor } from "akanjs/service";
+import { type AdaptorCls, BlobStorage, type CacheAdaptor, type CompressAdaptor, ConsoleLogger, type DatabaseAdaptor, JsonCompressor, type LlmAdaptor, type LoggingAdaptor, OpenaiLlm, type QueueAdaptor, type ScheduleAdaptor, Scheduler, SolidCache, SolidPubSub, SolidQueue, SqliteDatabase, type StorageAdaptor, type WebsocketAdaptor } from "akanjs/service";
 export interface PredefinedAdaptor {
     database: AdaptorCls<DatabaseAdaptor>;
     cache: AdaptorCls<CacheAdaptor>;
@@ -31,6 +31,6 @@ export declare const predefinedAdaptor: {
     logging: typeof ConsoleLogger;
     websocket: typeof SolidPubSub;
     compress: typeof JsonCompressor;
-    llm: typeof DeepseekLlm;
+    llm: typeof OpenaiLlm;
 };
 export declare const getPredefinedAdaptor: (mode?: DatabaseMode) => PredefinedAdaptor;

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

@@ -78,7 +78,7 @@ export declare class AnthropicLlm extends AnthropicLlm_base implements LlmAdapto
     /** What the API's blocks carry. A model of the family that reads neither takes the `accepts` override. */
     get accepts(): LlmAccepts;
     chat(request: LlmTurnRequest, onDelta?: (delta: string) => void): Promise<LlmTurnAnswer | null>;
-    static refusal(response: Response): Promise<Error>;
+    static refusal(host: string, response: Response): Promise<Error>;
     /** The API answers a refusal as `{ error: { type, message } }`, and the sentence is the half worth printing. */
     static reasonOf(response: Response): Promise<string>;
     static requestBody(model: string, request: LlmTurnRequest, { accepts, stream, maxTokens }?: {

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

@@ -2,7 +2,6 @@ export * from "./anthropicLlm.d.ts";
 export * from "./cache.adaptor";
 export * from "./compress.adaptor";
 export * from "./database.adaptor";
-export * from "./deepseekLlm.d.ts";
 export * from "./insightQuery.d.ts";
 export * from "./llm.adaptor";
 export * from "./logging.adaptor";

package/types/service/predefinedAdaptor/llm.adaptor.d.ts

@@ -120,7 +120,12 @@ export interface LlmAccepts {
 /**
  * Settings for whichever adaptor fills `LlmAdaptorRole`, registered with `option.setLlm(...)` and injected as the
  * `llmOption` use. It belongs to the role rather than to one provider: swapping the default for another `adapt()`
- * class re-reads the same three fields under that provider's own defaults.
+ * class re-reads the same fields under that provider's own defaults.
+ *
+ * It is the floor, not the whole shape. `setLlm` keeps whatever else it is handed, so an adaptor an app or a
+ * library wrote declares its own interface extending this one and reads it with `use<MyLlmOption>()` — a region,
+ * a project id, a deployment name reach it through the same channel the fields below do, instead of a second
+ * `option.use({...})` key beside it.
  */
 export interface LlmOption {
     apiKey?: string;
@@ -145,3 +150,11 @@ export interface LlmOption {
      */
     maxTokens?: number;
 }
+/**
+ * What the chat prints as the party that refused a turn, carried on `agent.error.llmRequestFailed`.
+ *
+ * It is the host rather than the adaptor's own name because one adaptor speaks one dialect to whatever host it
+ * is pointed at — an OpenAI-dialect class aimed at a gateway would otherwise credit OpenAI for that gateway's
+ * refusal. A host that is not a URL is printed as written; there is nothing better to say about it.
+ */
+export declare const llmProviderOf: (host: string) => string;

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

@@ -1,24 +1,33 @@
-import type { LlmAccepts, LlmAdaptor, LlmOption, LlmTurnAnswer, LlmTurnRequest } from "./llm.adaptor";
+import { type LlmAccepts, type LlmAdaptor, type LlmOption, type LlmTurnAnswer, type LlmTurnRequest } from "./llm.adaptor";
 declare const OpenaiLlm_base: import("..").AdaptorCls<{}, {
     llmOption: import("..").InjectInfo<"use", LlmOption, never, never>;
 }>;
 /**
- * OpenAI's chat-completions endpoint, and every gateway that serves the same dialect — `host` is what points it
- * at one. It is `DeepseekLlm`'s sibling rather than its replacement: same wire, and the difference that earns a
- * second class is that this one declares `accepts`, so an attached image reaches the model as an image part
- * instead of a note saying it could not be read.
+ * The OpenAI chat-completions dialect, pointed at a host — and the framework's default fill for `LlmAdaptorRole`.
+ *
+ * One class rather than one per vendor: DeepSeek, Groq, Together, OpenRouter, Ollama and a self-hosted vLLM all
+ * serve this same wire, so what distinguishes them is `option.setLlm({ host, model })` and not a protocol. A
+ * provider that speaks its own wire — Anthropic's blocks, Bedrock's signed requests — is a different adaptor
+ * class, in this package or in the app's own `srvkit/`, applied with
+ * `option.applyAdaptor(LlmAdaptorRole, TheClass)`.
  *
  * `model` is required and has no default. A default would be a model name that ages out of the provider's
- * catalogue into a 404 at the first turn, and — worse here than for a text-only adaptor — it would decide the
- * vision claim below on the app's behalf. Name the model in `option.setLlm({ model })`, and name
- * `accepts: { image: false }` beside it when that model is one of the provider's text-only ones.
+ * catalogue into a 404 at the first turn, and — worse — it would decide the vision claim below on the app's
+ * behalf.
  */
 export declare class OpenaiLlm extends OpenaiLlm_base implements LlmAdaptor {
     #private;
-    /** The endpoint takes image parts, so that is the provider's answer; a model that does not takes the override. */
-    get accepts(): LlmAccepts;
+    static readonly defaultHost = "https://api.openai.com/v1";
+    /**
+     * OpenAI's own endpoint takes image parts, so that is what is claimed for the default host. A host the app
+     * named is a gateway this class knows nothing about, and claiming vision for one is the worst guess available:
+     * the bytes reach a model that cannot decode them and the whole turn dies on a 400, where text-only degrades
+     * them to a note the model can repeat back. So a named host is text-only until `option.setLlm({ accepts })`
+     * says otherwise — as is the OpenAI model that reads no image.
+     */
+    get accepts(): LlmAccepts | undefined;
     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>;
+    static refusal(host: string, response: Response): Promise<Error>;
 }
 export {};

package/types/store/agentic/StToolBuilder.d.ts

@@ -1,6 +1,15 @@
 import { type CLIENT_VALUE, type EnumInstance } from "akanjs/base";
 import type { ParamFieldType } from "akanjs/constant";
+import type { ReactNode } from "react";
 import { type JsonSchema, type ToolConfirm, type ToolGuard } from "../../vendor/use-agentic.d.ts";
+/**
+ * The two ways a card ends the call it is parked on. `submit`'s value is what the model reads back, `cancel` is
+ * why there is none; the first one settles it and the card leaves the screen.
+ */
+export interface StToolCardControl {
+    submit: (value: unknown) => void;
+    cancel: (reason?: string) => void;
+}
 export interface StToolMeta {
     /**
      * Whether the call has to be waited out before what it did to the screen is reported back to the model. `false`
@@ -66,6 +75,19 @@ export declare class StToolBuilder<Args extends unknown[] = []> {
      * no longer offers.
      */
     exec(run: (...args: Args) => unknown): (...args: Args) => Promise<void>;
+    /**
+     * The other way a chain ends, for a tool whose answer belongs to the **user**: the call parks in the chat, the
+     * card renders there, and what it submits is what the model reads back. `.exec()` runs a function; this one runs
+     * a person, which is the whole difference — a name and a phone number are theirs to type, and a model that
+     * invents them has answered its own question.
+     *
+     * The arguments arrive positional like `.exec()`'s, and they are checked **before** the card is parked rather
+     * than while it renders: a bad argument has to reach the model as a refusal it can correct, and a throw inside
+     * the render would take the chat panel down with it instead.
+     *
+     * `confirm` is not read here. The card in front of the user is already the asking.
+     */
+    card(render: (control: StToolCardControl, ...args: Args) => ReactNode): void;
     static parametersOf(args: StToolArg[]): JsonSchema | undefined;
     /** Scalars and enums only — the value arrives as JSON from a model, so a class instance has no way in. */
     static schemaOf(type: ParamFieldType): JsonSchema;

package/types/store/agentic/attachAgentic.d.ts

@@ -14,7 +14,8 @@ export interface StAgentic {
     /** A read-only derived value the agent can read while the component is mounted: `.desc()` then `.value()`. */
     expose: <T extends AgentFieldType>(name: string | null, type: T, meta?: StExposeMeta) => StExposeDraft<T>;
     /**
-     * A component tool: `.desc()`, then `.arg()` / `.opt()`, chained onto one `.exec()` hook.
+     * A component tool: `.desc()`, then `.arg()` / `.opt()`, chained onto one terminal hook — `.exec()` for a tool
+     * a function answers, `.card()` for one the user answers in the chat.
      *
      * A falsy name declares the tool without publishing it — the callable still drives the click a person makes.
      * Every one of these ends in a hook, so a conditional surface withholds the name rather than skipping the chain.

package/types/store/baseSt.d.ts

@@ -276,7 +276,7 @@ export declare const st: import("./agentic.d.ts").StAgentic & {
         innerWidth: (options?: import("./types.d.ts").StoreUseOptions) => number;
         innerHeight: (options?: import("./types.d.ts").StoreUseOptions) => number;
         responsive: (options?: import("./types.d.ts").StoreUseOptions) => "xl" | "lg" | "md" | "sm" | "xs";
-        uiOperation: (options?: import("./types.d.ts").StoreUseOptions) => "loading" | "idle" | "sleep";
+        uiOperation: (options?: import("./types.d.ts").StoreUseOptions) => "idle" | "loading" | "sleep";
         messages: (options?: import("./types.d.ts").StoreUseOptions) => {
             type: "info" | "success" | "error" | "warning" | "loading";
             content: string;
@@ -307,7 +307,7 @@ export declare const st: import("./agentic.d.ts").StAgentic & {
         setInnerWidth: (value: number) => void;
         setInnerHeight: (value: number) => void;
         setResponsive: (value: "xl" | "lg" | "md" | "sm" | "xs") => void;
-        setUiOperation: (value: "loading" | "idle" | "sleep") => void;
+        setUiOperation: (value: "idle" | "loading" | "sleep") => void;
         setMessages: (value: {
             type: "info" | "success" | "error" | "warning" | "loading";
             content: string;

package/types/ui/Agent/Chat.d.ts

@@ -97,6 +97,12 @@ export interface ChatProps {
      * field reads as a paragraph rather than as the editor document it is stored as.
      */
     reference?: readonly ReferenceSource[];
+    /**
+     * Draws each pointer in the composer as the name it points at rather than as the `@[…](mention:…)` token that
+     * carries it. On wherever `reference` sources are declared, and `false` keeps the plain textarea — for an app
+     * that overrides the composer, or one that would rather see the tokens it is sending.
+     */
+    mentions?: boolean;
     /**
      * Raises or lowers what the composer accepts — per file, per message, and how many. The defaults are what one
      * turn's JSON safely carries to a conservative provider; an app pointed at a larger request limit, or one whose
@@ -117,6 +123,6 @@ export interface ChatProps {
  * `persist` keeps it. An enclosing AgentProvider's session wins, which is how an app isolates a surface or swaps
  * the loop while keeping this UI.
  */
-export declare const DefaultChat: ({ className, title, instructions, runner, maxTurns, compact, builtins, onCompact, defaultOpen, open: openProp, onOpenChange, launcher, visual, persist, inline, shortcut, launcherClassName, panelClassName, intro, header, chrome, defaultDraft, attach, attachLimits, reference, voice, }: ChatProps) => ReactNode;
+export declare const DefaultChat: ({ className, title, instructions, runner, maxTurns, compact, builtins, onCompact, defaultOpen, open: openProp, onOpenChange, launcher, visual, persist, inline, shortcut, launcherClassName, panelClassName, intro, header, chrome, defaultDraft, attach, attachLimits, reference, mentions, voice, }: ChatProps) => ReactNode;
 declare const _default: import("react").ComponentType<ChatProps>;
 export default _default;

package/types/ui/Agent/Composer.d.ts

@@ -1,5 +1,14 @@
 import { type KeyboardEvent, type RefObject } from "react";
 import type { AgentSession, MessageAttachment, MessageReference } from "../../vendor/use-agentic.d.ts";
+/**
+ * What the chat needs of whatever the composer draws into — a textarea, or the mention editor. Every offset is an
+ * offset into the draft string, tokens included, because that is the text the chat reasons about.
+ */
+export interface ComposerHandle {
+    focus: () => void;
+    caret: () => number | null;
+    setCaret: (at: number) => void;
+}
 export interface ComposerProps {
     className?: string;
     session: AgentSession;
@@ -26,7 +35,14 @@ export interface ComposerProps {
     onSend: () => void;
     onStop: () => void;
     inputRef?: RefObject<HTMLTextAreaElement | null>;
+    /**
+     * Draws each `@` pointer as the name it points at instead of as its token. On only where the chat was given
+     * `reference` sources, so an app that declared none never fetches the editor's chunk.
+     */
+    mentions?: boolean;
+    /** Filled by whichever input is drawn. An override that draws its own textarea leaves it null and `inputRef` answers. */
+    handleRef?: RefObject<ComposerHandle | null>;
 }
 /** What the user writes with: the staged files above, and the controls that send or stop below them. */
-export declare const DefaultComposer: ({ className, session, draft, attached, references, pending, mic, onDraft, onKeyDown, onFiles, onRemoveFile, onRemoveReference, onSend, onStop, inputRef, }: ComposerProps) => import("react/jsx-runtime").JSX.Element;
+export declare const DefaultComposer: ({ className, session, draft, attached, references, pending, mic, onDraft, onKeyDown, onFiles, onRemoveFile, onRemoveReference, onSend, onStop, inputRef, mentions, handleRef, }: ComposerProps) => import("react/jsx-runtime").JSX.Element;
 export declare const Composer: import("react").ComponentType<ComposerProps>;

package/types/ui/Agent/MentionNode.d.ts

@@ -0,0 +1,26 @@
+import { type LexicalNode, type NodeKey, type SerializedTextNode, TextNode } from "lexical";
+import { type MessageReference } from "../../vendor/use-agentic.d.ts";
+export interface SerializedMentionNode extends SerializedTextNode {
+    reference: MessageReference;
+}
+/**
+ * One `@` pointer inside the composer: the label is what the node draws, and `getTextContent()` is the
+ * `@[label](mention:…)` token — so the editor's own text is the draft string the rest of the chat already reads,
+ * pointers and all, while the person sees a name.
+ *
+ * `token` mode is what makes it one thing: the caret never lands inside it, a backspace takes the whole pointer
+ * rather than a character of a label that would then name nothing, and a paste over it replaces it entirely.
+ */
+export declare class MentionNode extends TextNode {
+    #private;
+    static getType(): string;
+    static clone(node: MentionNode): MentionNode;
+    static importJSON(json: Parameters<typeof TextNode.importJSON>[0]): MentionNode;
+    constructor(reference?: MessageReference, key?: NodeKey);
+    get reference(): MessageReference;
+    getTextContent(): string;
+    createDOM(...args: Parameters<TextNode["createDOM"]>): HTMLElement;
+    exportJSON(): SerializedMentionNode;
+}
+export declare const $createMentionNode: (reference: MessageReference) => MentionNode;
+export declare const $isMentionNode: (node: LexicalNode | null | undefined) => node is MentionNode;

package/types/ui/Agent/RichInput.d.ts

@@ -0,0 +1,22 @@
+import { type KeyboardEvent as ReactKeyboardEvent, type RefObject } from "react";
+import type { ComposerHandle } from "./Composer.d.ts";
+interface RichInputProps {
+    className?: string;
+    draft: string;
+    placeholder: string;
+    onDraft: (text: string) => void;
+    /** The textarea's own handler, unchanged: the chat reads a key off the draft and the caret, not off the DOM. */
+    onKeyDown: (event: ReactKeyboardEvent<HTMLTextAreaElement>) => void;
+    onFiles: (files: File[]) => void;
+    handleRef?: RefObject<ComposerHandle | null>;
+}
+/**
+ * The composer's input when the chat has `@` sources: the same draft string, drawn with each pointer as the name
+ * it points at instead of as the token that carries it.
+ *
+ * Lexical rather than a contenteditable of our own, for one reason — a Korean or Japanese IME composing into a
+ * contenteditable React also re-renders is the bug class the library exists to own, and it is not one an app can
+ * work around from outside.
+ */
+export declare const RichInput: ({ className, draft, placeholder, onDraft, onKeyDown, onFiles, handleRef, }: RichInputProps) => import("react/jsx-runtime").JSX.Element;
+export default RichInput;

package/types/ui/Agent/ToolCard.d.ts

@@ -0,0 +1,16 @@
+import type { PendingCard } from "../../vendor/use-agentic.d.ts";
+export interface ToolCardProps {
+    className?: string;
+    card: PendingCard;
+}
+/**
+ * A call the user answers, parked above the composer where the approval and the question cards sit. What it draws
+ * is the app's own — the declaration that published the tool also said what filling it in looks like — so this
+ * frame owns only the placement and the way out of it.
+ *
+ * The way out is not the app's to forget: a card that renders no cancel of its own would otherwise park the turn
+ * on a component the user cannot dismiss, so the frame always draws one.
+ */
+export declare const DefaultToolCard: ({ className, card }: ToolCardProps) => import("react/jsx-runtime").JSX.Element;
+declare const _default: import("react").ComponentType<ToolCardProps>;
+export default _default;

package/types/ui/Agent/markdownSpans.d.ts

@@ -1,2 +1,3 @@
 import type { ReactNode } from "react";
+/** The browser rendering of {@link MarkdownSpans}; the scanner, and which hrefs are refused, live there. */
 export declare const spans: (text: string) => ReactNode[];

package/types/ui/Agent/mentionDraft.d.ts

@@ -0,0 +1,19 @@
+import { type LexicalNode } from "lexical";
+/**
+ * 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 declare class MentionDraft {
+    #private;
+    /** Runs inside an editor read or update, like every `$` function. */
+    static read(): string;
+    /** Rebuilds the whole content from a draft string — the path every write that is not a keystroke takes. */
+    static write(text: string, caretAt?: number): void;
+    static nodesOf(text: string): LexicalNode[];
+    /** Where the caret sits in the draft string, or `null` when there is no collapsed caret to report. */
+    static caret(): number | null;
+    /** 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): void;
+}

package/types/ui/Agent/useChatReferences.d.ts

@@ -1,11 +1,12 @@
 import { type RefObject } from "react";
 import { type AgentSession, type MessageReference } from "../../vendor/use-agentic.d.ts";
+import type { ComposerHandle } from "./Composer.d.ts";
 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;
 }
 /**
@@ -18,7 +19,7 @@ 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 declare const useChatReferences: ({ session, draft, version, inputRef, onDraft }: ChatReferencesSetup) => {
+export declare const useChatReferences: ({ session, draft, version, handleRef, onDraft }: ChatReferencesSetup) => {
     references: MessageReference[];
     /** Removing the chip removes the token, because the token is what puts the reference on the message. */
     remove: (key: string) => void;

package/types/ui/UiOverride/context.d.ts

@@ -10,6 +10,7 @@ import type { MenuProps as AgentMenuProps } from "../Agent/Menu.d.ts";
 import type { QuestionProps as AgentQuestionProps } from "../Agent/Question.d.ts";
 import type { QueuedProps as AgentQueuedProps } from "../Agent/Queued.d.ts";
 import type { StepsProps as AgentStepsProps } from "../Agent/Steps.d.ts";
+import type { ToolCardProps as AgentToolCardProps } from "../Agent/ToolCard.d.ts";
 import type { BadgeProps } from "../Badge.d.ts";
 import type { ButtonProps } from "../Button.d.ts";
 import type { DatePickerProps, RangePickerProps, TimePickerProps } from "../DatePicker.d.ts";
@@ -68,6 +69,7 @@ export interface AkanUiOverrides {
     AgentQueued: ComponentType<AgentQueuedProps>;
     AgentMenu: ComponentType<AgentMenuProps>;
     AgentMarkdown: ComponentType<AgentMarkdownProps>;
+    AgentToolCard: ComponentType<AgentToolCardProps>;
     AgentCode: ComponentType<AgentCodeProps>;
     Button: ComponentType<ButtonProps<unknown>>;
     Select: ComponentType<SelectProps<string | number | boolean | null | undefined>>;

package/types/ui/index.d.ts

@@ -8,7 +8,7 @@ export { type AttachLimits, type AttachReader, maxAttachmentBytes, maxMessageAtt
 export { type BubbleProps, DefaultBubble } from "./Agent/Bubble.d.ts";
 export type { ChatProps } from "./Agent/Chat.d.ts";
 export { type ChatCommand, ChatCommands } from "./Agent/ChatCommands.d.ts";
-export { type ComposerProps, DefaultComposer } from "./Agent/Composer.d.ts";
+export { type ComposerHandle, type ComposerProps, DefaultComposer } from "./Agent/Composer.d.ts";
 export { fetchRunner } from "./Agent/fetchRunner.d.ts";
 export type { HistoryProps as AgentHistoryProps } from "./Agent/History.d.ts";
 export { DefaultLauncher, type LauncherProps } from "./Agent/Launcher.d.ts";
@@ -20,6 +20,7 @@ export { ReferenceChips as AgentReferences, type ReferenceChipsProps as AgentRef
 export { DefaultSteps, type StepsProps } from "./Agent/Steps.d.ts";
 export type { PersistOption } from "./Agent/sessionHistory.d.ts";
 export type { AgentBuiltin, BuiltinOption } from "./Agent/sessionView.d.ts";
+export { DefaultToolCard, type ToolCardProps } from "./Agent/ToolCard.d.ts";
 export { tokenCount } from "./Agent/tokenCount.d.ts";
 export type { QueuedMessage } from "./Agent/useChatQueue.d.ts";
 export type { ReferenceCandidate, ReferenceSource } from "./Agent/useReferenceMenu.d.ts";

package/types/ui/recipe/badgeRecipe.d.ts

@@ -2,14 +2,14 @@
 export declare const badgeRecipe: (variants?: Omit<({
     size?: "lg" | "md" | "sm" | "xs" | undefined;
     outline?: boolean | undefined;
-    variant?: "default" | "info" | "error" | "success" | "warning" | "primary" | "secondary" | "accent" | "neutral" | "outline" | undefined;
+    variant?: "default" | "error" | "info" | "warning" | "success" | "primary" | "secondary" | "accent" | "neutral" | "outline" | undefined;
 } & {
     class?: import("tailwind-variants").ClassValue;
     className?: never;
 }) | ({
     size?: "lg" | "md" | "sm" | "xs" | undefined;
     outline?: boolean | undefined;
-    variant?: "default" | "info" | "error" | "success" | "warning" | "primary" | "secondary" | "accent" | "neutral" | "outline" | undefined;
+    variant?: "default" | "error" | "info" | "warning" | "success" | "primary" | "secondary" | "accent" | "neutral" | "outline" | undefined;
 } & {
     class?: never;
     className?: import("tailwind-variants").ClassValue;

package/types/ui/recipe/buttonRecipe.d.ts

@@ -2,7 +2,7 @@
 export declare const buttonRecipe: (variants?: Omit<({
     size?: "lg" | "md" | "sm" | "xs" | "icon" | undefined;
     outline?: boolean | undefined;
-    variant?: "link" | "default" | "info" | "success" | "warning" | "primary" | "secondary" | "accent" | "destructive" | "neutral" | "outline" | "ghost" | undefined;
+    variant?: "link" | "default" | "info" | "warning" | "success" | "primary" | "secondary" | "accent" | "destructive" | "neutral" | "outline" | "ghost" | undefined;
     shape?: "default" | "circle" | "square" | undefined;
 } & {
     class?: import("tailwind-variants").ClassValue;
@@ -10,7 +10,7 @@ export declare const buttonRecipe: (variants?: Omit<({
 }) | ({
     size?: "lg" | "md" | "sm" | "xs" | "icon" | undefined;
     outline?: boolean | undefined;
-    variant?: "link" | "default" | "info" | "success" | "warning" | "primary" | "secondary" | "accent" | "destructive" | "neutral" | "outline" | "ghost" | undefined;
+    variant?: "link" | "default" | "info" | "warning" | "success" | "primary" | "secondary" | "accent" | "destructive" | "neutral" | "outline" | "ghost" | undefined;
     shape?: "default" | "circle" | "square" | undefined;
 } & {
     class?: never;

package/types/vendor/use-agentic/AgentSession.d.ts

@@ -1,6 +1,6 @@
 import type { AgentProgressReport } from "./AgentProgress.d.ts";
 import { type CompactOptions } from "./Compaction.d.ts";
-import type { AgentRunner, ChatMessage, ContextBlock, MessageReference, PublishedTool, SurfaceView, ToolActivity } from "./types.d.ts";
+import type { AgentRunner, ChatMessage, ContextBlock, MessageReference, PublishedTool, SurfaceView, ToolActivity, ToolCard } from "./types.d.ts";
 export interface PendingApproval {
     callId: string;
     name: string;
@@ -21,6 +21,19 @@ export interface PendingQuestion {
     answer: (value: string | string[]) => void;
     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
@@ -126,6 +139,7 @@ export declare class AgentSession {
     get isCompacting(): boolean;
     get pendingApproval(): PendingApproval | null;
     get pendingQuestion(): PendingQuestion | null;
+    get pendingCard(): PendingCard | null;
     /**
      * What the user has pointed at and not yet sent.
      *

package/types/vendor/use-agentic/ToolRunner.d.ts

@@ -1,5 +1,5 @@
 import { type AgentProgressReport } from "./AgentProgress.d.ts";
-import type { SurfaceView, ToolActivity, ToolCallRequest, ToolCallResult, ToolEntry } from "./types.d.ts";
+import type { SurfaceView, ToolActivity, ToolCallRequest, ToolCallResult, ToolCard, ToolEntry } from "./types.d.ts";
 export interface ToolApprovalRequest {
     callId: string;
     name: string;
@@ -7,6 +7,19 @@ export interface ToolApprovalRequest {
     /** What the user is asked, already resolved from the entry's `confirm`. */
     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;
@@ -25,6 +38,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

package/types/vendor/use-agentic/types.d.ts

@@ -1,9 +1,25 @@
+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. */
 export type ToolConfirm = boolean | string | ((args: Record<string, unknown>) => string | boolean);
 /** 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;
@@ -14,8 +30,21 @@ 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.
  *
@@ -236,3 +265,4 @@ export interface RunnerRequest {
 export interface AgentRunner {
     run: (request: RunnerRequest) => AsyncIterable<RunnerEvent>;
 }
+export {};