akanjs 3.0.0-alpha.38 → 3.0.0-alpha.39

package/dictionary/base.dictionary.ts

@@ -54,6 +54,10 @@ export const baseDictionary = serviceDictionary(["en", "ko"])
     agentClear: ["Clear conversation", "대화 비우기"],
     agentQuestion: ["The agent needs your decision", "에이전트가 결정을 요청합니다"],
     agentAnswer: ["Type your answer...", "답변을 입력하세요..."],
+    agentAttach: ["Attach a file", "파일 첨부"],
+    agentAttachRemove: ["Remove attachment", "첨부 제거"],
+    agentAttachTooLarge: ["{name} is too large to attach.", "{name}은(는) 용량이 너무 커서 첨부할 수 없습니다."],
+    agentAttachUnsupported: ["{name} cannot be attached here.", "{name}은(는) 여기에 첨부할 수 없습니다."],
     agentContinue: ["This is taking a while. Keep going?", "시간이 걸리고 있습니다. 계속할까요?"],
     agentKeepGoing: ["Keep going", "계속하기"],
     agentCmdNew: ["Start a new conversation", "새 대화 시작"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-alpha.38",
+  "version": "3.0.0-alpha.39",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/service/agent.service.ts

@@ -1,5 +1,10 @@
 import { Err } from "akanjs/dictionary";
-import type { LlmTurnRequest } from "./predefinedAdaptor/llm.adaptor";
+import type {
+  AgentWireAttachment,
+  AgentWireMessage,
+  LlmAccepts,
+  LlmTurnRequest,
+} from "./predefinedAdaptor/llm.adaptor";
 import { LlmAdaptorRole } from "./predefinedAdaptor/role.adaptor";
 import { serve } from "./serve";
 
@@ -7,8 +12,49 @@ export class AgentService extends serve("agent" as const, ({ plug }) => ({
   llm: plug(LlmAdaptorRole),
 })) {
   async runTurn(request: LlmTurnRequest, onDelta?: (delta: string) => void) {
-    const answer = await this.llm.chat(request, onDelta);
+    const answer = await this.llm.chat(AgentService.readable(request, this.llm.accepts), onDelta);
     if (!answer) throw new Err("agent.error.llmUnavailable");
     return { text: answer.text ?? "", toolCalls: answer.toolCalls ?? [], stop: answer.stop };
   }
+
+  /**
+   * Replaces every attachment the provider cannot read with a note naming it, so no adaptor has to think about
+   * attachments it does not support and none can lose one quietly. The model has to be *told*, not merely spared:
+   * a file that vanishes on the way in is one it answers about from the filename, confidently and wrongly.
+   *
+   * The note rides in the message text because that is the one field every provider mapping already reads.
+   */
+  static readable(request: LlmTurnRequest, accepts: LlmAccepts | undefined): LlmTurnRequest {
+    if (!request.messages.some((message) => message.attachments?.length)) return request;
+    const messages = request.messages.map((message) => AgentService.readableMessage(message, accepts ?? {}));
+    return { ...request, messages };
+  }
+
+  private static readableMessage(message: AgentWireMessage, accepts: LlmAccepts): AgentWireMessage {
+    const { attachments = [], ...rest } = message;
+    if (!attachments.length) return message;
+    const kept = attachments.filter((attachment) => AgentService.isReadable(attachment, accepts));
+    if (kept.length === attachments.length) return message;
+    const notes = attachments.filter((attachment) => !kept.includes(attachment)).map(AgentService.note);
+    return {
+      ...rest,
+      ...(kept.length ? { attachments: kept } : {}),
+      text: [message.text, ...notes].filter(Boolean).join("\n\n"),
+    };
+  }
+
+  /** Extracted text is readable by every model there is; bytes and links need the provider to say so. */
+  private static isReadable(attachment: AgentWireAttachment, accepts: LlmAccepts): boolean {
+    if (attachment.text) return true;
+    if (!attachment.data && !attachment.url) return false;
+    return attachment.mimeType.startsWith("image/") ? !!accepts.image : !!accepts.document;
+  }
+
+  private static note(attachment: AgentWireAttachment): string {
+    const why =
+      attachment.data || attachment.url
+        ? "this model cannot read that type"
+        : "its content is no longer available, as a reloaded conversation keeps the name and not the bytes";
+    return `[Attachment not read: ${attachment.name} (${attachment.mimeType}) — ${why}. Tell the user it was not read instead of guessing what it holds, and ask for the text if the answer needs it.]`;
+  }
 }

package/service/predefinedAdaptor/deepseekLlm.ts

@@ -201,7 +201,19 @@ export class DeepseekLlm
             : {}),
         },
       ];
-    return [{ role: "user" as const, content: message.text ?? "" }];
+    return [{ role: "user" as const, content: DeepseekLlm.userContent(message) }];
+  }
+
+  /**
+   * `accepts` is left undeclared, so by the time an attachment reaches here `AgentService.readable` has reduced it
+   * to its text and turned everything else into a note. Each block is labelled because a model handed two
+   * unlabelled documents can no longer cite either one.
+   */
+  static userContent(message: AgentWireMessage): string {
+    const blocks = (message.attachments ?? []).flatMap((attachment) =>
+      attachment.text ? [`--- attachment: ${attachment.name} (${attachment.mimeType}) ---\n${attachment.text}`] : [],
+    );
+    return [message.text, ...blocks].filter(Boolean).join("\n\n");
   }
 
   static turnAnswer(answer: DeepseekAnswer): LlmTurnAnswer {

package/service/predefinedAdaptor/llm.adaptor.ts

@@ -12,6 +12,20 @@ export interface AgentWireToolResult {
   error?: string;
 }
 
+/**
+ * A file the caller attached to one message. Exactly one carrier reaches the model — `data` as inlined bytes, `url`
+ * as something the provider fetches, `text` as content already extracted — and which of them a given provider can
+ * read is what `LlmAccepts` answers.
+ */
+export interface AgentWireAttachment {
+  name: string;
+  mimeType: string;
+  /** Base64, with no `data:` prefix. */
+  data?: string;
+  url?: string;
+  text?: string;
+}
+
 /**
  * One transcript message of the in-page agent wire (`use-agentic`'s WIRE.md), typed at both ends independently —
  * the wire is the contract, so the server never imports the client package.
@@ -19,6 +33,7 @@ export interface AgentWireToolResult {
 export interface AgentWireMessage {
   role: "user" | "assistant" | "tool";
   text?: string;
+  attachments?: AgentWireAttachment[];
   toolCalls?: AgentWireToolCall[];
   toolResults?: AgentWireToolResult[];
   error?: string;
@@ -62,6 +77,22 @@ export interface LlmAdaptor {
    * answer. An adapter may ignore it — the caller treats zero reported deltas as "answered whole".
    */
   chat(request: LlmTurnRequest, onDelta?: (delta: string) => void): Promise<LlmTurnAnswer | null>;
+  /** Which attachment carriers this provider's model can read. Omitted means text only. */
+  readonly accepts?: LlmAccepts;
+}
+
+/**
+ * What an adaptor's model reads beyond text. Declared rather than defaulted to true, because the failure of
+ * guessing wrong is the worst one available: a provider handed bytes it cannot decode either rejects the whole
+ * turn or accepts it having seen nothing, and the model then answers confidently about a file it never read.
+ * `AgentService` degrades what is not accepted into a note the model can repeat back, so a text-only provider
+ * needs no attachment code at all — which is every provider until somebody swaps one in for vision.
+ */
+export interface LlmAccepts {
+  /** Inlined or linked image bytes. */
+  image?: boolean;
+  /** Non-image bytes handed over whole — a PDF the model parses itself. */
+  document?: boolean;
 }
 
 /**

package/store/agent/AgentPrompts.ts

@@ -1,7 +1,7 @@
 import { Translator } from "akanjs/client";
 import { parseAkanI18nEnv } from "akanjs/common";
 import { FetchClient } from "akanjs/fetch";
-import type { PromptContent, PromptResult, SerializedSignal } from "akanjs/signal";
+import type { PromptContent, PromptMessage, PromptResult, SerializedSignal } from "akanjs/signal";
 import type { ChatMessage } from "../../vendor/use-agentic";
 
 export interface AgentPrompt {
@@ -59,7 +59,25 @@ export class AgentPrompts {
   /** The messages a prompt returns become the user's turn, the way an MCP client sends a `prompts/get` result. */
   static messagesOf(result: PromptResult): ChatMessage[] {
     if (typeof result === "string") return [{ role: "user", text: result }];
-    return result.map((message) => ({ role: message.role, text: AgentPrompts.textOf(message.content) }));
+    return result.map((message) => AgentPrompts.#messageOf(message));
+  }
+
+  /**
+   * A binary block becomes an attachment. It used to become the string `[image]`, which a model reads as having
+   * been shown a picture — so a prompt built with `Msg.imageOf` produced confident answers about bytes that never
+   * left the server. The other block types are text already and stay text.
+   */
+  static #messageOf(message: PromptMessage): ChatMessage {
+    const { role, content } = message;
+    if (content.type !== "image" && content.type !== "audio") return { role, text: AgentPrompts.textOf(content) };
+    const name = AgentPrompts.#binaryName(content.mimeType);
+    return { role, attachments: [{ name, mimeType: content.mimeType, data: content.data }] };
+  }
+
+  /** `Msg.image` carries no filename — the protocol has nowhere to put one — so the type is the label. */
+  static #binaryName(mimeType: string) {
+    const [kind, subtype] = mimeType.split("/");
+    return subtype ? `${kind}.${subtype.split("+")[0]}` : mimeType;
   }
 
   static textOf(content: PromptContent): string {

package/types/dictionary/base.dictionary.d.ts

@@ -1 +1 @@
-export declare const baseDictionary: import("./dictInfo.d.ts").ServiceDictInfo<[string, string], "ping" | "pingBody" | "pingParam" | "pingQuery" | "wsPing" | "pubsubPing", never, "error" | "remove" | "save" | "refresh" | "password" | "stop" | "send" | "skip" | "agent" | "ok" | "connecting" | "new" | "somethingWrong" | "connected" | "serverDisconnected" | "refreshing" | "tryReconnecting" | "serverHasProblem" | "checkServerStatus" | "success" | "failed" | "processing" | "processed" | "noData" | "invalidValueError" | "emailInvalidError" | "phoneInvalidError" | "cancel" | "unauthorized" | "agentIntro" | "agentPlaceholder" | "agentClear" | "agentQuestion" | "agentAnswer" | "agentContinue" | "agentKeepGoing" | "agentCmdNew" | "agentCmdRetry" | "agentCmdCopy" | "agentCmdHelp" | "agentCmdTools" | "agentHelpIntro" | "agentHelpNote" | "agentNothingToRetry" | "agentBusy" | "agentCopied" | "agentCopyFailed" | "agentToolsHead" | "agentToolsState" | "approve" | "decline" | "confirmClose" | "textTooShortError" | "textTooLongError" | "selectTooShortError" | "selectTooLongError" | "numberTooSmallError" | "numberTooBigError" | "passwordNotMatchError" | "selectDateError" | "priceUnit" | "passwordConfirm" | "noOptions" | "addModel" | "createModel" | "createSuccess" | "updateModel" | "removeModel" | "updateSuccess" | "removeSuccess" | "sureToRemove" | "irreversibleOps" | "typeNameToRemove" | "yesRemove" | "removeMsg" | "confirmMsg" | "perPage" | "cardView" | "tableView" | "exportCsv" | "exportJson" | "actions" | "edit" | "view">;
+export declare const baseDictionary: import("./dictInfo.d.ts").ServiceDictInfo<[string, string], "ping" | "pingBody" | "pingParam" | "pingQuery" | "wsPing" | "pubsubPing", never, "error" | "remove" | "save" | "refresh" | "password" | "stop" | "send" | "skip" | "agent" | "ok" | "connecting" | "new" | "somethingWrong" | "connected" | "serverDisconnected" | "refreshing" | "tryReconnecting" | "serverHasProblem" | "checkServerStatus" | "success" | "failed" | "processing" | "processed" | "noData" | "invalidValueError" | "emailInvalidError" | "phoneInvalidError" | "cancel" | "unauthorized" | "agentIntro" | "agentPlaceholder" | "agentClear" | "agentQuestion" | "agentAnswer" | "agentAttach" | "agentAttachRemove" | "agentAttachTooLarge" | "agentAttachUnsupported" | "agentContinue" | "agentKeepGoing" | "agentCmdNew" | "agentCmdRetry" | "agentCmdCopy" | "agentCmdHelp" | "agentCmdTools" | "agentHelpIntro" | "agentHelpNote" | "agentNothingToRetry" | "agentBusy" | "agentCopied" | "agentCopyFailed" | "agentToolsHead" | "agentToolsState" | "approve" | "decline" | "confirmClose" | "textTooShortError" | "textTooLongError" | "selectTooShortError" | "selectTooLongError" | "numberTooSmallError" | "numberTooBigError" | "passwordNotMatchError" | "selectDateError" | "priceUnit" | "passwordConfirm" | "noOptions" | "addModel" | "createModel" | "createSuccess" | "updateModel" | "removeModel" | "updateSuccess" | "removeSuccess" | "sureToRemove" | "irreversibleOps" | "typeNameToRemove" | "yesRemove" | "removeMsg" | "confirmMsg" | "perPage" | "cardView" | "tableView" | "exportCsv" | "exportJson" | "actions" | "edit" | "view">;

package/types/dictionary/dictionary.d.ts

@@ -1,13 +1,13 @@
 import type { AgentEndpoint, AgentTurn, BaseEndpoint } from "akanjs/signal";
 export declare const dictionary: {
-    base: import("./locale.d.ts").DictModule<import("./locale.d.ts").ServiceTranslatorKey<"base", BaseEndpoint, "error" | "remove" | "save" | "refresh" | "password" | "stop" | "send" | "skip" | "agent" | "ok" | "connecting" | "new" | "somethingWrong" | "connected" | "serverDisconnected" | "refreshing" | "tryReconnecting" | "serverHasProblem" | "checkServerStatus" | "success" | "failed" | "processing" | "processed" | "noData" | "invalidValueError" | "emailInvalidError" | "phoneInvalidError" | "cancel" | "unauthorized" | "agentIntro" | "agentPlaceholder" | "agentClear" | "agentQuestion" | "agentAnswer" | "agentContinue" | "agentKeepGoing" | "agentCmdNew" | "agentCmdRetry" | "agentCmdCopy" | "agentCmdHelp" | "agentCmdTools" | "agentHelpIntro" | "agentHelpNote" | "agentNothingToRetry" | "agentBusy" | "agentCopied" | "agentCopyFailed" | "agentToolsHead" | "agentToolsState" | "approve" | "decline" | "confirmClose" | "textTooShortError" | "textTooLongError" | "selectTooShortError" | "selectTooLongError" | "numberTooSmallError" | "numberTooBigError" | "passwordNotMatchError" | "selectDateError" | "priceUnit" | "passwordConfirm" | "noOptions" | "addModel" | "createModel" | "createSuccess" | "updateModel" | "removeModel" | "updateSuccess" | "removeSuccess" | "sureToRemove" | "irreversibleOps" | "typeNameToRemove" | "yesRemove" | "removeMsg" | "confirmMsg" | "perPage" | "cardView" | "tableView" | "exportCsv" | "exportJson" | "actions" | "edit" | "view">, never>;
+    base: import("./locale.d.ts").DictModule<import("./locale.d.ts").ServiceTranslatorKey<"base", BaseEndpoint, "error" | "remove" | "save" | "refresh" | "password" | "stop" | "send" | "skip" | "agent" | "ok" | "connecting" | "new" | "somethingWrong" | "connected" | "serverDisconnected" | "refreshing" | "tryReconnecting" | "serverHasProblem" | "checkServerStatus" | "success" | "failed" | "processing" | "processed" | "noData" | "invalidValueError" | "emailInvalidError" | "phoneInvalidError" | "cancel" | "unauthorized" | "agentIntro" | "agentPlaceholder" | "agentClear" | "agentQuestion" | "agentAnswer" | "agentAttach" | "agentAttachRemove" | "agentAttachTooLarge" | "agentAttachUnsupported" | "agentContinue" | "agentKeepGoing" | "agentCmdNew" | "agentCmdRetry" | "agentCmdCopy" | "agentCmdHelp" | "agentCmdTools" | "agentHelpIntro" | "agentHelpNote" | "agentNothingToRetry" | "agentBusy" | "agentCopied" | "agentCopyFailed" | "agentToolsHead" | "agentToolsState" | "approve" | "decline" | "confirmClose" | "textTooShortError" | "textTooLongError" | "selectTooShortError" | "selectTooLongError" | "numberTooSmallError" | "numberTooBigError" | "passwordNotMatchError" | "selectDateError" | "priceUnit" | "passwordConfirm" | "noOptions" | "addModel" | "createModel" | "createSuccess" | "updateModel" | "removeModel" | "updateSuccess" | "removeSuccess" | "sureToRemove" | "irreversibleOps" | "typeNameToRemove" | "yesRemove" | "removeMsg" | "confirmMsg" | "perPage" | "cardView" | "tableView" | "exportCsv" | "exportJson" | "actions" | "edit" | "view">, never>;
     agentTurn: import("./locale.d.ts").DictModule<import("./locale.d.ts").ScalarTranslatorKey<"agentTurn", AgentTurn, never> | `agentStop.${string}` | `agentStop.${string}.desc`, never>;
     agent: import("./locale.d.ts").DictModule<import("./locale.d.ts").ServiceTranslatorKey<"agent", AgentEndpoint, never>, "agent.error.llmUnavailable" | "agent.error.deepseekRequestFailed">;
 };
-export declare const Err: import("./trans.d.ts").ErrConstructor<"agent.error.llmUnavailable" | "agent.error.deepseekRequestFailed">, translate: (lang: "en" | "ko" | "zhChs" | "zhCht" | "ja", key: import("./locale.d.ts").ServiceTranslatorKey<"base", BaseEndpoint, "error" | "remove" | "save" | "refresh" | "password" | "stop" | "send" | "skip" | "agent" | "ok" | "connecting" | "new" | "somethingWrong" | "connected" | "serverDisconnected" | "refreshing" | "tryReconnecting" | "serverHasProblem" | "checkServerStatus" | "success" | "failed" | "processing" | "processed" | "noData" | "invalidValueError" | "emailInvalidError" | "phoneInvalidError" | "cancel" | "unauthorized" | "agentIntro" | "agentPlaceholder" | "agentClear" | "agentQuestion" | "agentAnswer" | "agentContinue" | "agentKeepGoing" | "agentCmdNew" | "agentCmdRetry" | "agentCmdCopy" | "agentCmdHelp" | "agentCmdTools" | "agentHelpIntro" | "agentHelpNote" | "agentNothingToRetry" | "agentBusy" | "agentCopied" | "agentCopyFailed" | "agentToolsHead" | "agentToolsState" | "approve" | "decline" | "confirmClose" | "textTooShortError" | "textTooLongError" | "selectTooShortError" | "selectTooLongError" | "numberTooSmallError" | "numberTooBigError" | "passwordNotMatchError" | "selectDateError" | "priceUnit" | "passwordConfirm" | "noOptions" | "addModel" | "createModel" | "createSuccess" | "updateModel" | "removeModel" | "updateSuccess" | "removeSuccess" | "sureToRemove" | "irreversibleOps" | "typeNameToRemove" | "yesRemove" | "removeMsg" | "confirmMsg" | "perPage" | "cardView" | "tableView" | "exportCsv" | "exportJson" | "actions" | "edit" | "view"> | import("./locale.d.ts").ScalarTranslatorKey<"agentTurn", AgentTurn, never> | `agentStop.${string}` | `agentStop.${string}.desc` | import("./locale.d.ts").ServiceTranslatorKey<"agent", AgentEndpoint, never>, data?: import("./trans.d.ts").TranslationData) => string, msg: {
-    info: (key: import("./locale.d.ts").ServiceTranslatorKey<"base", BaseEndpoint, "error" | "remove" | "save" | "refresh" | "password" | "stop" | "send" | "skip" | "agent" | "ok" | "connecting" | "new" | "somethingWrong" | "connected" | "serverDisconnected" | "refreshing" | "tryReconnecting" | "serverHasProblem" | "checkServerStatus" | "success" | "failed" | "processing" | "processed" | "noData" | "invalidValueError" | "emailInvalidError" | "phoneInvalidError" | "cancel" | "unauthorized" | "agentIntro" | "agentPlaceholder" | "agentClear" | "agentQuestion" | "agentAnswer" | "agentContinue" | "agentKeepGoing" | "agentCmdNew" | "agentCmdRetry" | "agentCmdCopy" | "agentCmdHelp" | "agentCmdTools" | "agentHelpIntro" | "agentHelpNote" | "agentNothingToRetry" | "agentBusy" | "agentCopied" | "agentCopyFailed" | "agentToolsHead" | "agentToolsState" | "approve" | "decline" | "confirmClose" | "textTooShortError" | "textTooLongError" | "selectTooShortError" | "selectTooLongError" | "numberTooSmallError" | "numberTooBigError" | "passwordNotMatchError" | "selectDateError" | "priceUnit" | "passwordConfirm" | "noOptions" | "addModel" | "createModel" | "createSuccess" | "updateModel" | "removeModel" | "updateSuccess" | "removeSuccess" | "sureToRemove" | "irreversibleOps" | "typeNameToRemove" | "yesRemove" | "removeMsg" | "confirmMsg" | "perPage" | "cardView" | "tableView" | "exportCsv" | "exportJson" | "actions" | "edit" | "view"> | import("./locale.d.ts").ScalarTranslatorKey<"agentTurn", AgentTurn, never> | `agentStop.${string}` | `agentStop.${string}.desc` | import("./locale.d.ts").ServiceTranslatorKey<"agent", AgentEndpoint, never>, option?: import("./trans.d.ts").TransMessageOption) => void;
-    success: (key: import("./locale.d.ts").ServiceTranslatorKey<"base", BaseEndpoint, "error" | "remove" | "save" | "refresh" | "password" | "stop" | "send" | "skip" | "agent" | "ok" | "connecting" | "new" | "somethingWrong" | "connected" | "serverDisconnected" | "refreshing" | "tryReconnecting" | "serverHasProblem" | "checkServerStatus" | "success" | "failed" | "processing" | "processed" | "noData" | "invalidValueError" | "emailInvalidError" | "phoneInvalidError" | "cancel" | "unauthorized" | "agentIntro" | "agentPlaceholder" | "agentClear" | "agentQuestion" | "agentAnswer" | "agentContinue" | "agentKeepGoing" | "agentCmdNew" | "agentCmdRetry" | "agentCmdCopy" | "agentCmdHelp" | "agentCmdTools" | "agentHelpIntro" | "agentHelpNote" | "agentNothingToRetry" | "agentBusy" | "agentCopied" | "agentCopyFailed" | "agentToolsHead" | "agentToolsState" | "approve" | "decline" | "confirmClose" | "textTooShortError" | "textTooLongError" | "selectTooShortError" | "selectTooLongError" | "numberTooSmallError" | "numberTooBigError" | "passwordNotMatchError" | "selectDateError" | "priceUnit" | "passwordConfirm" | "noOptions" | "addModel" | "createModel" | "createSuccess" | "updateModel" | "removeModel" | "updateSuccess" | "removeSuccess" | "sureToRemove" | "irreversibleOps" | "typeNameToRemove" | "yesRemove" | "removeMsg" | "confirmMsg" | "perPage" | "cardView" | "tableView" | "exportCsv" | "exportJson" | "actions" | "edit" | "view"> | import("./locale.d.ts").ScalarTranslatorKey<"agentTurn", AgentTurn, never> | `agentStop.${string}` | `agentStop.${string}.desc` | import("./locale.d.ts").ServiceTranslatorKey<"agent", AgentEndpoint, never>, option?: import("./trans.d.ts").TransMessageOption) => void;
-    error: (key: import("./locale.d.ts").ServiceTranslatorKey<"base", BaseEndpoint, "error" | "remove" | "save" | "refresh" | "password" | "stop" | "send" | "skip" | "agent" | "ok" | "connecting" | "new" | "somethingWrong" | "connected" | "serverDisconnected" | "refreshing" | "tryReconnecting" | "serverHasProblem" | "checkServerStatus" | "success" | "failed" | "processing" | "processed" | "noData" | "invalidValueError" | "emailInvalidError" | "phoneInvalidError" | "cancel" | "unauthorized" | "agentIntro" | "agentPlaceholder" | "agentClear" | "agentQuestion" | "agentAnswer" | "agentContinue" | "agentKeepGoing" | "agentCmdNew" | "agentCmdRetry" | "agentCmdCopy" | "agentCmdHelp" | "agentCmdTools" | "agentHelpIntro" | "agentHelpNote" | "agentNothingToRetry" | "agentBusy" | "agentCopied" | "agentCopyFailed" | "agentToolsHead" | "agentToolsState" | "approve" | "decline" | "confirmClose" | "textTooShortError" | "textTooLongError" | "selectTooShortError" | "selectTooLongError" | "numberTooSmallError" | "numberTooBigError" | "passwordNotMatchError" | "selectDateError" | "priceUnit" | "passwordConfirm" | "noOptions" | "addModel" | "createModel" | "createSuccess" | "updateModel" | "removeModel" | "updateSuccess" | "removeSuccess" | "sureToRemove" | "irreversibleOps" | "typeNameToRemove" | "yesRemove" | "removeMsg" | "confirmMsg" | "perPage" | "cardView" | "tableView" | "exportCsv" | "exportJson" | "actions" | "edit" | "view"> | import("./locale.d.ts").ScalarTranslatorKey<"agentTurn", AgentTurn, never> | `agentStop.${string}` | `agentStop.${string}.desc` | import("./locale.d.ts").ServiceTranslatorKey<"agent", AgentEndpoint, never>, option?: import("./trans.d.ts").TransMessageOption) => void;
-    warning: (key: import("./locale.d.ts").ServiceTranslatorKey<"base", BaseEndpoint, "error" | "remove" | "save" | "refresh" | "password" | "stop" | "send" | "skip" | "agent" | "ok" | "connecting" | "new" | "somethingWrong" | "connected" | "serverDisconnected" | "refreshing" | "tryReconnecting" | "serverHasProblem" | "checkServerStatus" | "success" | "failed" | "processing" | "processed" | "noData" | "invalidValueError" | "emailInvalidError" | "phoneInvalidError" | "cancel" | "unauthorized" | "agentIntro" | "agentPlaceholder" | "agentClear" | "agentQuestion" | "agentAnswer" | "agentContinue" | "agentKeepGoing" | "agentCmdNew" | "agentCmdRetry" | "agentCmdCopy" | "agentCmdHelp" | "agentCmdTools" | "agentHelpIntro" | "agentHelpNote" | "agentNothingToRetry" | "agentBusy" | "agentCopied" | "agentCopyFailed" | "agentToolsHead" | "agentToolsState" | "approve" | "decline" | "confirmClose" | "textTooShortError" | "textTooLongError" | "selectTooShortError" | "selectTooLongError" | "numberTooSmallError" | "numberTooBigError" | "passwordNotMatchError" | "selectDateError" | "priceUnit" | "passwordConfirm" | "noOptions" | "addModel" | "createModel" | "createSuccess" | "updateModel" | "removeModel" | "updateSuccess" | "removeSuccess" | "sureToRemove" | "irreversibleOps" | "typeNameToRemove" | "yesRemove" | "removeMsg" | "confirmMsg" | "perPage" | "cardView" | "tableView" | "exportCsv" | "exportJson" | "actions" | "edit" | "view"> | import("./locale.d.ts").ScalarTranslatorKey<"agentTurn", AgentTurn, never> | `agentStop.${string}` | `agentStop.${string}.desc` | import("./locale.d.ts").ServiceTranslatorKey<"agent", AgentEndpoint, never>, option?: import("./trans.d.ts").TransMessageOption) => void;
-    loading: (key: import("./locale.d.ts").ServiceTranslatorKey<"base", BaseEndpoint, "error" | "remove" | "save" | "refresh" | "password" | "stop" | "send" | "skip" | "agent" | "ok" | "connecting" | "new" | "somethingWrong" | "connected" | "serverDisconnected" | "refreshing" | "tryReconnecting" | "serverHasProblem" | "checkServerStatus" | "success" | "failed" | "processing" | "processed" | "noData" | "invalidValueError" | "emailInvalidError" | "phoneInvalidError" | "cancel" | "unauthorized" | "agentIntro" | "agentPlaceholder" | "agentClear" | "agentQuestion" | "agentAnswer" | "agentContinue" | "agentKeepGoing" | "agentCmdNew" | "agentCmdRetry" | "agentCmdCopy" | "agentCmdHelp" | "agentCmdTools" | "agentHelpIntro" | "agentHelpNote" | "agentNothingToRetry" | "agentBusy" | "agentCopied" | "agentCopyFailed" | "agentToolsHead" | "agentToolsState" | "approve" | "decline" | "confirmClose" | "textTooShortError" | "textTooLongError" | "selectTooShortError" | "selectTooLongError" | "numberTooSmallError" | "numberTooBigError" | "passwordNotMatchError" | "selectDateError" | "priceUnit" | "passwordConfirm" | "noOptions" | "addModel" | "createModel" | "createSuccess" | "updateModel" | "removeModel" | "updateSuccess" | "removeSuccess" | "sureToRemove" | "irreversibleOps" | "typeNameToRemove" | "yesRemove" | "removeMsg" | "confirmMsg" | "perPage" | "cardView" | "tableView" | "exportCsv" | "exportJson" | "actions" | "edit" | "view"> | import("./locale.d.ts").ScalarTranslatorKey<"agentTurn", AgentTurn, never> | `agentStop.${string}` | `agentStop.${string}.desc` | import("./locale.d.ts").ServiceTranslatorKey<"agent", AgentEndpoint, never>, option?: import("./trans.d.ts").TransMessageOption) => void;
-}, getDictionary: (lang: "en" | "ko" | "zhChs" | "zhCht" | "ja") => object, getAllDictionary: () => import("./trans.d.ts").RootDictionary, __Dict_Key__: import("./locale.d.ts").ServiceTranslatorKey<"base", BaseEndpoint, "error" | "remove" | "save" | "refresh" | "password" | "stop" | "send" | "skip" | "agent" | "ok" | "connecting" | "new" | "somethingWrong" | "connected" | "serverDisconnected" | "refreshing" | "tryReconnecting" | "serverHasProblem" | "checkServerStatus" | "success" | "failed" | "processing" | "processed" | "noData" | "invalidValueError" | "emailInvalidError" | "phoneInvalidError" | "cancel" | "unauthorized" | "agentIntro" | "agentPlaceholder" | "agentClear" | "agentQuestion" | "agentAnswer" | "agentContinue" | "agentKeepGoing" | "agentCmdNew" | "agentCmdRetry" | "agentCmdCopy" | "agentCmdHelp" | "agentCmdTools" | "agentHelpIntro" | "agentHelpNote" | "agentNothingToRetry" | "agentBusy" | "agentCopied" | "agentCopyFailed" | "agentToolsHead" | "agentToolsState" | "approve" | "decline" | "confirmClose" | "textTooShortError" | "textTooLongError" | "selectTooShortError" | "selectTooLongError" | "numberTooSmallError" | "numberTooBigError" | "passwordNotMatchError" | "selectDateError" | "priceUnit" | "passwordConfirm" | "noOptions" | "addModel" | "createModel" | "createSuccess" | "updateModel" | "removeModel" | "updateSuccess" | "removeSuccess" | "sureToRemove" | "irreversibleOps" | "typeNameToRemove" | "yesRemove" | "removeMsg" | "confirmMsg" | "perPage" | "cardView" | "tableView" | "exportCsv" | "exportJson" | "actions" | "edit" | "view"> | import("./locale.d.ts").ScalarTranslatorKey<"agentTurn", AgentTurn, never> | `agentStop.${string}` | `agentStop.${string}.desc` | import("./locale.d.ts").ServiceTranslatorKey<"agent", AgentEndpoint, never>, __Error_Key__: "agent.error.llmUnavailable" | "agent.error.deepseekRequestFailed";
+export declare const Err: import("./trans.d.ts").ErrConstructor<"agent.error.llmUnavailable" | "agent.error.deepseekRequestFailed">, translate: (lang: "en" | "ko" | "zhChs" | "zhCht" | "ja", key: import("./locale.d.ts").ServiceTranslatorKey<"base", BaseEndpoint, "error" | "remove" | "save" | "refresh" | "password" | "stop" | "send" | "skip" | "agent" | "ok" | "connecting" | "new" | "somethingWrong" | "connected" | "serverDisconnected" | "refreshing" | "tryReconnecting" | "serverHasProblem" | "checkServerStatus" | "success" | "failed" | "processing" | "processed" | "noData" | "invalidValueError" | "emailInvalidError" | "phoneInvalidError" | "cancel" | "unauthorized" | "agentIntro" | "agentPlaceholder" | "agentClear" | "agentQuestion" | "agentAnswer" | "agentAttach" | "agentAttachRemove" | "agentAttachTooLarge" | "agentAttachUnsupported" | "agentContinue" | "agentKeepGoing" | "agentCmdNew" | "agentCmdRetry" | "agentCmdCopy" | "agentCmdHelp" | "agentCmdTools" | "agentHelpIntro" | "agentHelpNote" | "agentNothingToRetry" | "agentBusy" | "agentCopied" | "agentCopyFailed" | "agentToolsHead" | "agentToolsState" | "approve" | "decline" | "confirmClose" | "textTooShortError" | "textTooLongError" | "selectTooShortError" | "selectTooLongError" | "numberTooSmallError" | "numberTooBigError" | "passwordNotMatchError" | "selectDateError" | "priceUnit" | "passwordConfirm" | "noOptions" | "addModel" | "createModel" | "createSuccess" | "updateModel" | "removeModel" | "updateSuccess" | "removeSuccess" | "sureToRemove" | "irreversibleOps" | "typeNameToRemove" | "yesRemove" | "removeMsg" | "confirmMsg" | "perPage" | "cardView" | "tableView" | "exportCsv" | "exportJson" | "actions" | "edit" | "view"> | import("./locale.d.ts").ScalarTranslatorKey<"agentTurn", AgentTurn, never> | `agentStop.${string}` | `agentStop.${string}.desc` | import("./locale.d.ts").ServiceTranslatorKey<"agent", AgentEndpoint, never>, data?: import("./trans.d.ts").TranslationData) => string, msg: {
+    info: (key: import("./locale.d.ts").ServiceTranslatorKey<"base", BaseEndpoint, "error" | "remove" | "save" | "refresh" | "password" | "stop" | "send" | "skip" | "agent" | "ok" | "connecting" | "new" | "somethingWrong" | "connected" | "serverDisconnected" | "refreshing" | "tryReconnecting" | "serverHasProblem" | "checkServerStatus" | "success" | "failed" | "processing" | "processed" | "noData" | "invalidValueError" | "emailInvalidError" | "phoneInvalidError" | "cancel" | "unauthorized" | "agentIntro" | "agentPlaceholder" | "agentClear" | "agentQuestion" | "agentAnswer" | "agentAttach" | "agentAttachRemove" | "agentAttachTooLarge" | "agentAttachUnsupported" | "agentContinue" | "agentKeepGoing" | "agentCmdNew" | "agentCmdRetry" | "agentCmdCopy" | "agentCmdHelp" | "agentCmdTools" | "agentHelpIntro" | "agentHelpNote" | "agentNothingToRetry" | "agentBusy" | "agentCopied" | "agentCopyFailed" | "agentToolsHead" | "agentToolsState" | "approve" | "decline" | "confirmClose" | "textTooShortError" | "textTooLongError" | "selectTooShortError" | "selectTooLongError" | "numberTooSmallError" | "numberTooBigError" | "passwordNotMatchError" | "selectDateError" | "priceUnit" | "passwordConfirm" | "noOptions" | "addModel" | "createModel" | "createSuccess" | "updateModel" | "removeModel" | "updateSuccess" | "removeSuccess" | "sureToRemove" | "irreversibleOps" | "typeNameToRemove" | "yesRemove" | "removeMsg" | "confirmMsg" | "perPage" | "cardView" | "tableView" | "exportCsv" | "exportJson" | "actions" | "edit" | "view"> | import("./locale.d.ts").ScalarTranslatorKey<"agentTurn", AgentTurn, never> | `agentStop.${string}` | `agentStop.${string}.desc` | import("./locale.d.ts").ServiceTranslatorKey<"agent", AgentEndpoint, never>, option?: import("./trans.d.ts").TransMessageOption) => void;
+    success: (key: import("./locale.d.ts").ServiceTranslatorKey<"base", BaseEndpoint, "error" | "remove" | "save" | "refresh" | "password" | "stop" | "send" | "skip" | "agent" | "ok" | "connecting" | "new" | "somethingWrong" | "connected" | "serverDisconnected" | "refreshing" | "tryReconnecting" | "serverHasProblem" | "checkServerStatus" | "success" | "failed" | "processing" | "processed" | "noData" | "invalidValueError" | "emailInvalidError" | "phoneInvalidError" | "cancel" | "unauthorized" | "agentIntro" | "agentPlaceholder" | "agentClear" | "agentQuestion" | "agentAnswer" | "agentAttach" | "agentAttachRemove" | "agentAttachTooLarge" | "agentAttachUnsupported" | "agentContinue" | "agentKeepGoing" | "agentCmdNew" | "agentCmdRetry" | "agentCmdCopy" | "agentCmdHelp" | "agentCmdTools" | "agentHelpIntro" | "agentHelpNote" | "agentNothingToRetry" | "agentBusy" | "agentCopied" | "agentCopyFailed" | "agentToolsHead" | "agentToolsState" | "approve" | "decline" | "confirmClose" | "textTooShortError" | "textTooLongError" | "selectTooShortError" | "selectTooLongError" | "numberTooSmallError" | "numberTooBigError" | "passwordNotMatchError" | "selectDateError" | "priceUnit" | "passwordConfirm" | "noOptions" | "addModel" | "createModel" | "createSuccess" | "updateModel" | "removeModel" | "updateSuccess" | "removeSuccess" | "sureToRemove" | "irreversibleOps" | "typeNameToRemove" | "yesRemove" | "removeMsg" | "confirmMsg" | "perPage" | "cardView" | "tableView" | "exportCsv" | "exportJson" | "actions" | "edit" | "view"> | import("./locale.d.ts").ScalarTranslatorKey<"agentTurn", AgentTurn, never> | `agentStop.${string}` | `agentStop.${string}.desc` | import("./locale.d.ts").ServiceTranslatorKey<"agent", AgentEndpoint, never>, option?: import("./trans.d.ts").TransMessageOption) => void;
+    error: (key: import("./locale.d.ts").ServiceTranslatorKey<"base", BaseEndpoint, "error" | "remove" | "save" | "refresh" | "password" | "stop" | "send" | "skip" | "agent" | "ok" | "connecting" | "new" | "somethingWrong" | "connected" | "serverDisconnected" | "refreshing" | "tryReconnecting" | "serverHasProblem" | "checkServerStatus" | "success" | "failed" | "processing" | "processed" | "noData" | "invalidValueError" | "emailInvalidError" | "phoneInvalidError" | "cancel" | "unauthorized" | "agentIntro" | "agentPlaceholder" | "agentClear" | "agentQuestion" | "agentAnswer" | "agentAttach" | "agentAttachRemove" | "agentAttachTooLarge" | "agentAttachUnsupported" | "agentContinue" | "agentKeepGoing" | "agentCmdNew" | "agentCmdRetry" | "agentCmdCopy" | "agentCmdHelp" | "agentCmdTools" | "agentHelpIntro" | "agentHelpNote" | "agentNothingToRetry" | "agentBusy" | "agentCopied" | "agentCopyFailed" | "agentToolsHead" | "agentToolsState" | "approve" | "decline" | "confirmClose" | "textTooShortError" | "textTooLongError" | "selectTooShortError" | "selectTooLongError" | "numberTooSmallError" | "numberTooBigError" | "passwordNotMatchError" | "selectDateError" | "priceUnit" | "passwordConfirm" | "noOptions" | "addModel" | "createModel" | "createSuccess" | "updateModel" | "removeModel" | "updateSuccess" | "removeSuccess" | "sureToRemove" | "irreversibleOps" | "typeNameToRemove" | "yesRemove" | "removeMsg" | "confirmMsg" | "perPage" | "cardView" | "tableView" | "exportCsv" | "exportJson" | "actions" | "edit" | "view"> | import("./locale.d.ts").ScalarTranslatorKey<"agentTurn", AgentTurn, never> | `agentStop.${string}` | `agentStop.${string}.desc` | import("./locale.d.ts").ServiceTranslatorKey<"agent", AgentEndpoint, never>, option?: import("./trans.d.ts").TransMessageOption) => void;
+    warning: (key: import("./locale.d.ts").ServiceTranslatorKey<"base", BaseEndpoint, "error" | "remove" | "save" | "refresh" | "password" | "stop" | "send" | "skip" | "agent" | "ok" | "connecting" | "new" | "somethingWrong" | "connected" | "serverDisconnected" | "refreshing" | "tryReconnecting" | "serverHasProblem" | "checkServerStatus" | "success" | "failed" | "processing" | "processed" | "noData" | "invalidValueError" | "emailInvalidError" | "phoneInvalidError" | "cancel" | "unauthorized" | "agentIntro" | "agentPlaceholder" | "agentClear" | "agentQuestion" | "agentAnswer" | "agentAttach" | "agentAttachRemove" | "agentAttachTooLarge" | "agentAttachUnsupported" | "agentContinue" | "agentKeepGoing" | "agentCmdNew" | "agentCmdRetry" | "agentCmdCopy" | "agentCmdHelp" | "agentCmdTools" | "agentHelpIntro" | "agentHelpNote" | "agentNothingToRetry" | "agentBusy" | "agentCopied" | "agentCopyFailed" | "agentToolsHead" | "agentToolsState" | "approve" | "decline" | "confirmClose" | "textTooShortError" | "textTooLongError" | "selectTooShortError" | "selectTooLongError" | "numberTooSmallError" | "numberTooBigError" | "passwordNotMatchError" | "selectDateError" | "priceUnit" | "passwordConfirm" | "noOptions" | "addModel" | "createModel" | "createSuccess" | "updateModel" | "removeModel" | "updateSuccess" | "removeSuccess" | "sureToRemove" | "irreversibleOps" | "typeNameToRemove" | "yesRemove" | "removeMsg" | "confirmMsg" | "perPage" | "cardView" | "tableView" | "exportCsv" | "exportJson" | "actions" | "edit" | "view"> | import("./locale.d.ts").ScalarTranslatorKey<"agentTurn", AgentTurn, never> | `agentStop.${string}` | `agentStop.${string}.desc` | import("./locale.d.ts").ServiceTranslatorKey<"agent", AgentEndpoint, never>, option?: import("./trans.d.ts").TransMessageOption) => void;
+    loading: (key: import("./locale.d.ts").ServiceTranslatorKey<"base", BaseEndpoint, "error" | "remove" | "save" | "refresh" | "password" | "stop" | "send" | "skip" | "agent" | "ok" | "connecting" | "new" | "somethingWrong" | "connected" | "serverDisconnected" | "refreshing" | "tryReconnecting" | "serverHasProblem" | "checkServerStatus" | "success" | "failed" | "processing" | "processed" | "noData" | "invalidValueError" | "emailInvalidError" | "phoneInvalidError" | "cancel" | "unauthorized" | "agentIntro" | "agentPlaceholder" | "agentClear" | "agentQuestion" | "agentAnswer" | "agentAttach" | "agentAttachRemove" | "agentAttachTooLarge" | "agentAttachUnsupported" | "agentContinue" | "agentKeepGoing" | "agentCmdNew" | "agentCmdRetry" | "agentCmdCopy" | "agentCmdHelp" | "agentCmdTools" | "agentHelpIntro" | "agentHelpNote" | "agentNothingToRetry" | "agentBusy" | "agentCopied" | "agentCopyFailed" | "agentToolsHead" | "agentToolsState" | "approve" | "decline" | "confirmClose" | "textTooShortError" | "textTooLongError" | "selectTooShortError" | "selectTooLongError" | "numberTooSmallError" | "numberTooBigError" | "passwordNotMatchError" | "selectDateError" | "priceUnit" | "passwordConfirm" | "noOptions" | "addModel" | "createModel" | "createSuccess" | "updateModel" | "removeModel" | "updateSuccess" | "removeSuccess" | "sureToRemove" | "irreversibleOps" | "typeNameToRemove" | "yesRemove" | "removeMsg" | "confirmMsg" | "perPage" | "cardView" | "tableView" | "exportCsv" | "exportJson" | "actions" | "edit" | "view"> | import("./locale.d.ts").ScalarTranslatorKey<"agentTurn", AgentTurn, never> | `agentStop.${string}` | `agentStop.${string}.desc` | import("./locale.d.ts").ServiceTranslatorKey<"agent", AgentEndpoint, never>, option?: import("./trans.d.ts").TransMessageOption) => void;
+}, getDictionary: (lang: "en" | "ko" | "zhChs" | "zhCht" | "ja") => object, getAllDictionary: () => import("./trans.d.ts").RootDictionary, __Dict_Key__: import("./locale.d.ts").ServiceTranslatorKey<"base", BaseEndpoint, "error" | "remove" | "save" | "refresh" | "password" | "stop" | "send" | "skip" | "agent" | "ok" | "connecting" | "new" | "somethingWrong" | "connected" | "serverDisconnected" | "refreshing" | "tryReconnecting" | "serverHasProblem" | "checkServerStatus" | "success" | "failed" | "processing" | "processed" | "noData" | "invalidValueError" | "emailInvalidError" | "phoneInvalidError" | "cancel" | "unauthorized" | "agentIntro" | "agentPlaceholder" | "agentClear" | "agentQuestion" | "agentAnswer" | "agentAttach" | "agentAttachRemove" | "agentAttachTooLarge" | "agentAttachUnsupported" | "agentContinue" | "agentKeepGoing" | "agentCmdNew" | "agentCmdRetry" | "agentCmdCopy" | "agentCmdHelp" | "agentCmdTools" | "agentHelpIntro" | "agentHelpNote" | "agentNothingToRetry" | "agentBusy" | "agentCopied" | "agentCopyFailed" | "agentToolsHead" | "agentToolsState" | "approve" | "decline" | "confirmClose" | "textTooShortError" | "textTooLongError" | "selectTooShortError" | "selectTooLongError" | "numberTooSmallError" | "numberTooBigError" | "passwordNotMatchError" | "selectDateError" | "priceUnit" | "passwordConfirm" | "noOptions" | "addModel" | "createModel" | "createSuccess" | "updateModel" | "removeModel" | "updateSuccess" | "removeSuccess" | "sureToRemove" | "irreversibleOps" | "typeNameToRemove" | "yesRemove" | "removeMsg" | "confirmMsg" | "perPage" | "cardView" | "tableView" | "exportCsv" | "exportJson" | "actions" | "edit" | "view"> | import("./locale.d.ts").ScalarTranslatorKey<"agentTurn", AgentTurn, never> | `agentStop.${string}` | `agentStop.${string}.desc` | import("./locale.d.ts").ServiceTranslatorKey<"agent", AgentEndpoint, never>, __Error_Key__: "agent.error.llmUnavailable" | "agent.error.deepseekRequestFailed";

package/types/service/agent.service.d.ts

@@ -1,4 +1,4 @@
-import type { LlmTurnRequest } from "./predefinedAdaptor/llm.adaptor";
+import type { LlmAccepts, LlmTurnRequest } from "./predefinedAdaptor/llm.adaptor";
 declare const AgentService_base: import("./serve.d.ts").ServiceCls<"agent", {}, {
     llm: import("./injectInfo.d.ts").InjectInfo<"plug", import("./predefinedAdaptor.d.ts").LlmAdaptor, never, never>;
 }>;
@@ -8,5 +8,17 @@ export declare class AgentService extends AgentService_base {
         toolCalls: import("./predefinedAdaptor.d.ts").AgentWireToolCall[];
         stop: "end" | "toolUse";
     }>;
+    /**
+     * Replaces every attachment the provider cannot read with a note naming it, so no adaptor has to think about
+     * attachments it does not support and none can lose one quietly. The model has to be *told*, not merely spared:
+     * a file that vanishes on the way in is one it answers about from the filename, confidently and wrongly.
+     *
+     * The note rides in the message text because that is the one field every provider mapping already reads.
+     */
+    static readable(request: LlmTurnRequest, accepts: LlmAccepts | undefined): LlmTurnRequest;
+    private static readableMessage;
+    /** Extracted text is readable by every model there is; bytes and links need the provider to say so. */
+    private static isReadable;
+    private static note;
 }
 export {};

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

@@ -57,6 +57,12 @@ export declare class DeepseekLlm extends DeepseekLlm_base implements LlmAdaptor
     /** Context rides below the instructions framed as data — screen state must never read as directives. */
     static systemPrompt({ instructions, context }: LlmTurnRequest): string;
     static providerMessages(message: AgentWireMessage): DeepseekMessage[];
+    /**
+     * `accepts` is left undeclared, so by the time an attachment reaches here `AgentService.readable` has reduced it
+     * to its text and turned everything else into a note. Each block is labelled because a model handed two
+     * unlabelled documents can no longer cite either one.
+     */
+    static userContent(message: AgentWireMessage): string;
     static turnAnswer(answer: DeepseekAnswer): LlmTurnAnswer;
     /** The provider sends arguments as a JSON string; an unparsable one becomes an empty call rather than a crash. */
     static parsedArgs(raw: string | undefined): Record<string, unknown>;

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

@@ -10,6 +10,19 @@ export interface AgentWireToolResult {
     changes?: unknown[];
     error?: string;
 }
+/**
+ * A file the caller attached to one message. Exactly one carrier reaches the model — `data` as inlined bytes, `url`
+ * as something the provider fetches, `text` as content already extracted — and which of them a given provider can
+ * read is what `LlmAccepts` answers.
+ */
+export interface AgentWireAttachment {
+    name: string;
+    mimeType: string;
+    /** Base64, with no `data:` prefix. */
+    data?: string;
+    url?: string;
+    text?: string;
+}
 /**
  * One transcript message of the in-page agent wire (`use-agentic`'s WIRE.md), typed at both ends independently —
  * the wire is the contract, so the server never imports the client package.
@@ -17,6 +30,7 @@ export interface AgentWireToolResult {
 export interface AgentWireMessage {
     role: "user" | "assistant" | "tool";
     text?: string;
+    attachments?: AgentWireAttachment[];
     toolCalls?: AgentWireToolCall[];
     toolResults?: AgentWireToolResult[];
     error?: string;
@@ -55,6 +69,21 @@ export interface LlmAdaptor {
      * answer. An adapter may ignore it — the caller treats zero reported deltas as "answered whole".
      */
     chat(request: LlmTurnRequest, onDelta?: (delta: string) => void): Promise<LlmTurnAnswer | null>;
+    /** Which attachment carriers this provider's model can read. Omitted means text only. */
+    readonly accepts?: LlmAccepts;
+}
+/**
+ * What an adaptor's model reads beyond text. Declared rather than defaulted to true, because the failure of
+ * guessing wrong is the worst one available: a provider handed bytes it cannot decode either rejects the whole
+ * turn or accepts it having seen nothing, and the model then answers confidently about a file it never read.
+ * `AgentService` degrades what is not accepted into a note the model can repeat back, so a text-only provider
+ * needs no attachment code at all — which is every provider until somebody swaps one in for vision.
+ */
+export interface LlmAccepts {
+    /** Inlined or linked image bytes. */
+    image?: boolean;
+    /** Non-image bytes handed over whole — a PDF the model parses itself. */
+    document?: boolean;
 }
 /**
  * Settings for whichever adaptor fills `LlmAdaptorRole`, registered with `option.setLlm(...)` and injected as the

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

@@ -0,0 +1,16 @@
+import type { MessageAttachment } from "../../vendor/use-agentic.d.ts";
+interface AttachProps {
+    className?: string;
+    label: string;
+    onPick: (files: File[]) => void;
+}
+export declare const Attach: ({ className, label, onPick }: AttachProps) => import("react/jsx-runtime").JSX.Element;
+interface ChipsProps {
+    className?: string;
+    attachments: readonly MessageAttachment[];
+    /** Omitted for a sent message: what is already on the wire cannot be taken back. */
+    onRemove?: (index: number) => void;
+    removeLabel?: string;
+}
+export declare const Chips: ({ className, attachments, onRemove, removeLabel }: ChipsProps) => import("react/jsx-runtime").JSX.Element;
+export {};

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

@@ -1,5 +1,6 @@
 import { type ReactNode } from "react";
 import { type AgentRunner } from "../../vendor/use-agentic.d.ts";
+import { type AttachReader } from "./attachment.d.ts";
 import { type PersistOption } from "./sessionHistory.d.ts";
 export interface ChatProps {
     className?: string;
@@ -14,6 +15,13 @@ export interface ChatProps {
     persist?: PersistOption;
     /** Renders in the page flow instead of floating above it — a zone chat that lives inside its own section. */
     inline?: boolean;
+    /**
+     * Reads a file the user attached into an attachment, or answers `null` to leave it to the built-in reader
+     * (images as bytes, text as text). This is where an app puts what needs a parser — a PDF's text, a spreadsheet's
+     * cells — since the framework carries attachments but depends on nothing that can extract one. It runs before
+     * the built-in, so it can also replace how an image is prepared.
+     */
+    attach?: AttachReader;
 }
 /**
  * The user-facing half of the in-page agent: one floating chat wired to the same surface the dock inspects.
@@ -22,6 +30,6 @@ export interface ChatProps {
  * no history). 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, defaultOpen, persist, inline, }: ChatProps) => ReactNode;
+export declare const DefaultChat: ({ className, title, instructions, runner, maxTurns, defaultOpen, persist, inline, attach, }: ChatProps) => ReactNode;
 declare const _default: import("react").ComponentType<ChatProps>;
 export default _default;

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

@@ -0,0 +1,23 @@
+import type { MessageAttachment } from "../../vendor/use-agentic.d.ts";
+/** Turns one picked file into an attachment, or `null` to say this reader does not handle that file. */
+export type AttachReader = (file: File) => Promise<MessageAttachment | null>;
+/**
+ * Per-file ceiling for the composer. The bytes ride inside one turn's JSON request, so a file past this is not a
+ * slow attachment — it is a request the relay and the provider both refuse, and refusing it here is the only place
+ * the user learns which file it was.
+ */
+export declare const maxAttachmentBytes: number;
+export type AttachFailure = "tooLarge" | "unsupported";
+export declare class Attachment {
+    #private;
+    /**
+     * Reads what a browser can read on its own — an image as bytes, a text-ish file as text — and hands everything
+     * else to the app's own reader. That split is the layer boundary: a PDF needs a parser, so extracting one is the
+     * app's business (`attach`), while carrying the result is the framework's.
+     *
+     * The app's reader runs first so it can also replace the built-in handling, which is what downscaling an image
+     * before it costs a megabyte of prompt looks like.
+     */
+    static read(file: File, attach?: AttachReader): Promise<MessageAttachment | AttachFailure>;
+    static failure(value: MessageAttachment | AttachFailure): value is AttachFailure;
+}

package/types/ui/Dropdown.d.ts

@@ -14,8 +14,10 @@ export interface DropdownProps {
     dropdownClassName?: string;
     /** Trigger edge the menu lines up with. Position is computed, so a `left-0` class cannot do this. */
     align?: "start" | "end";
+    /** Names this dropdown for the in-page agent. Without it the menu publishes nothing — two on one screen would share a name. */
+    namespace?: string;
 }
-export declare const DefaultDropdown: ({ value, content, className, buttonClassName, dropdownClassName, align, }: DropdownProps) => import("react/jsx-runtime").JSX.Element;
+export declare const DefaultDropdown: ({ value, content, className, buttonClassName, dropdownClassName, align, namespace, }: DropdownProps) => import("react/jsx-runtime").JSX.Element;
 /**
  * Dropdown. Resolves to a route-scoped override when a `page/**\/_overrides.tsx`
  * in the route's ancestry declares one, otherwise renders {@link DefaultDropdown}.

package/types/ui/index.d.ts

@@ -1,4 +1,5 @@
 export { Agent } from "./Agent.d.ts";
+export { type AttachReader, maxAttachmentBytes } from "./Agent/attachment.d.ts";
 export { agentAttrs } from "./agentAttrs.d.ts";
 export { animated } from "./animated.d.ts";
 export { Badge } from "./Badge.d.ts";

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

@@ -101,9 +101,32 @@ export interface ToolCallResult {
     changes?: ResourceDiff[];
     error?: string;
 }
+/**
+ * A file the user handed the conversation rather than the screen — which is why it rides a message instead of a
+ * tool, the same reason `askUser` belongs to the session and not to the surface.
+ *
+ * Three carriers, one of which every attachment must have: `data` inlines the bytes, `url` points at something the
+ * provider can fetch, and `text` is content somebody already extracted — the only form a text-only model can read.
+ * They mirror what the server's own `Msg.image` / `Msg.link` / `Msg.resource` builders produce, so a prompt's
+ * attachment and a user's are the same thing on the wire.
+ *
+ * Whether a given carrier reaches the model is the provider's answer, not this type's: a backend drops what its
+ * model cannot read and says so in the transcript, because a silently dropped file is one the model then
+ * hallucinates about.
+ */
+export interface MessageAttachment {
+    name: string;
+    mimeType: string;
+    /** Base64, with no `data:` prefix. */
+    data?: string;
+    url?: string;
+    text?: string;
+}
 export interface ChatMessage {
     role: ChatRole;
     text?: string;
+    /** Files the message carries. Content, not instructions — a backend frames them the way it frames context. */
+    attachments?: MessageAttachment[];
     toolCalls?: ToolCallRequest[];
     toolResults?: ToolCallResult[];
     /** A failed or capped turn, recorded in the transcript rather than thrown past it. */

package/ui/Agent/Attach.tsx

@@ -0,0 +1,77 @@
+"use client";
+import { cn } from "akanjs/client";
+import { useRef } from "react";
+import { AiOutlineClose, AiOutlinePaperClip } from "react-icons/ai";
+import type { MessageAttachment } from "../../vendor/use-agentic";
+
+interface AttachProps {
+  className?: string;
+  label: string;
+  onPick: (files: File[]) => void;
+}
+
+export const Attach = ({ className, label, onPick }: AttachProps) => {
+  const ref = useRef<HTMLInputElement>(null);
+  return (
+    <>
+      <button
+        aria-label={label}
+        className={cn("shrink-0 text-foreground/50 hover:text-foreground", className)}
+        onClick={() => ref.current?.click()}
+        title={label}
+        type="button"
+      >
+        <AiOutlinePaperClip />
+      </button>
+      <input
+        className="hidden"
+        multiple
+        onChange={(event) => {
+          onPick([...(event.target.files ?? [])]);
+          
+          event.target.value = "";
+        }}
+        ref={ref}
+        type="file"
+      />
+    </>
+  );
+};
+
+interface ChipsProps {
+  className?: string;
+  attachments: readonly MessageAttachment[];
+  /** Omitted for a sent message: what is already on the wire cannot be taken back. */
+  onRemove?: (index: number) => void;
+  removeLabel?: string;
+}
+
+export const Chips = ({ className, attachments, onRemove, removeLabel }: ChipsProps) => (
+  <div className={cn("flex flex-wrap gap-1", className)}>
+    {attachments.map((attachment, idx) => (
+      <span
+        className="flex items-center gap-1 rounded-field bg-muted px-2 py-0.5 text-xs"
+        key={`${attachment.name}-${idx}`}
+      >
+        {attachment.data && attachment.mimeType.startsWith("image/") ? (
+          <img
+            alt={attachment.name}
+            className="size-6 rounded-field object-cover"
+            src={`data:${attachment.mimeType};base64,${attachment.data}`}
+          />
+        ) : null}
+        <span className="max-w-32 truncate">{attachment.name}</span>
+        {onRemove ? (
+          <button
+            aria-label={removeLabel}
+            className="text-foreground/40 hover:text-foreground"
+            onClick={() => onRemove(idx)}
+            type="button"
+          >
+            <AiOutlineClose />
+          </button>
+        ) : null}
+      </span>
+    ))}
+  </div>
+);

package/ui/Agent/Bubble.tsx

@@ -1,6 +1,7 @@
 "use client";
 import { cn } from "akanjs/client";
 import { type AgentProgressReport, AgentSession, type ChatMessage, type ToolCallResult } from "../../vendor/use-agentic";
+import { Chips } from "./Attach";
 import Markdown from "./Markdown";
 
 interface BubbleProps {
@@ -90,13 +91,11 @@ export default function Bubble({ className, message, progress, results }: Bubble
     );
   if (message.role === "user")
     return (
-      <div
-        className={cn(
-          "max-w-[85%] self-end whitespace-pre-wrap rounded-box bg-primary/10 px-3 py-2 text-sm",
-          className,
-        )}
-      >
-        {message.text}
+      <div className={cn("flex max-w-[85%] flex-col items-end gap-1 self-end", className)}>
+        {message.attachments?.length ? <Chips attachments={message.attachments} className="justify-end" /> : null}
+        {message.text ? (
+          <p className="whitespace-pre-wrap rounded-box bg-primary/10 px-3 py-2 text-sm">{message.text}</p>
+        ) : null}
       </div>
     );
   const isDrafting = !message.text && !message.toolCalls?.length && !message.error;

package/ui/Agent/Chat.tsx

@@ -5,11 +5,13 @@ import { AgentContext, type AgentPrompt, AgentPrompts, ensureStoreSurface, Scree
 import { type ReactNode, useContext, useEffect, useRef, useState, useSyncExternalStore } from "react";
 import { createPortal } from "react-dom";
 import { AiOutlineClear, AiOutlineClose } from "react-icons/ai";
-import { type AgentRunner, AgentSession, SessionContext } from "../../vendor/use-agentic";
+import { type AgentRunner, AgentSession, type MessageAttachment, SessionContext } from "../../vendor/use-agentic";
 import { Button } from "../Button";
 import { inputRecipe } from "../recipe";
 import { createOverridable } from "../UiOverride";
 import Approval from "./Approval";
+import { Attach, Chips } from "./Attach";
+import { Attachment, type AttachReader } from "./attachment";
 import Bubble from "./Bubble";
 import { type ChatCommand, ChatCommands } from "./ChatCommands";
 import { fetchRunner } from "./fetchRunner";
@@ -30,6 +32,13 @@ export interface ChatProps {
   persist?: PersistOption;
   /** Renders in the page flow instead of floating above it — a zone chat that lives inside its own section. */
   inline?: boolean;
+  /**
+   * Reads a file the user attached into an attachment, or answers `null` to leave it to the built-in reader
+   * (images as bytes, text as text). This is where an app puts what needs a parser — a PDF's text, a spreadsheet's
+   * cells — since the framework carries attachments but depends on nothing that can extract one. It runs before
+   * the built-in, so it can also replace how an image is prepared.
+   */
+  attach?: AttachReader;
 }
 
 const isApplePlatform = () => /Mac|iPhone|iPad|iPod/i.test(navigator.platform);
@@ -52,6 +61,7 @@ export const DefaultChat = ({
   defaultOpen = false,
   persist,
   inline = false,
+  attach,
 }: ChatProps) => {
   const { l } = usePage();
   const provided = useContext(SessionContext);
@@ -76,6 +86,7 @@ export const DefaultChat = ({
   );
   const [open, setOpen] = useState(defaultOpen);
   const [draft, setDraft] = useState("");
+  const [attached, setAttached] = useState<MessageAttachment[]>([]);
   const sent = useRef<string[]>([]);
   const stashed = useRef("");
   const [recall, setRecall] = useState(0);
@@ -128,6 +139,21 @@ export const DefaultChat = ({
       session.report(`/${prompt.name} failed: ${error instanceof Error ? error.message : String(error)}`);
     }
   };
+  /** Staged one at a time so one unreadable file names itself instead of failing the whole drop silently. */
+  const attachFiles = async (files: File[]) => {
+    for (const file of files) {
+      try {
+        const read = await Attachment.read(file, attach);
+        if (!Attachment.failure(read)) setAttached((current) => [...current, read]);
+        else
+          session.note(
+            l(read === "tooLarge" ? "base.agentAttachTooLarge" : "base.agentAttachUnsupported", { name: file.name }),
+          );
+      } catch (error) {
+        session.report(`${file.name}: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+  };
   const remember = (text: string) => {
     if (sent.current[sent.current.length - 1] !== text) sent.current = [...sent.current, text].slice(-30);
     setRecall(0);
@@ -157,10 +183,10 @@ export const DefaultChat = ({
   };
   const send = () => {
     const text = draft.trim();
-    if (!text) return;
+    if (!text && !attached.length) return;
 
     const question = session.pendingQuestion;
-    if (question) {
+    if (question && text) {
       setDraft("");
       question.answer(question.multiple ? [text] : text);
       return;
@@ -175,12 +201,17 @@ export const DefaultChat = ({
     if (session.isRunning) return;
     const prompt = command ? prompts.current?.find(command.name) : null;
     setDraft("");
-    remember(text);
+    if (text) remember(text);
     if (command && prompt) {
       void runPrompt(prompt, command.args);
       return;
     }
-    void session.send(text);
+    if (!attached.length) {
+      void session.send(text);
+      return;
+    }
+    setAttached([]);
+    void session.send([{ role: "user", ...(text ? { text } : {}), attachments: attached }]);
   };
   const query = /^\/[A-Za-z0-9_-]*$/.test(draft) ? draft : "";
   const commandMenu = query ? ChatCommands.list(l).filter((command) => `/${command.name}`.startsWith(query)) : [];
@@ -241,6 +272,11 @@ export const DefaultChat = ({
         !inline && floatingLayer,
         className,
       )}
+      onDragOver={(event) => event.preventDefault()}
+      onDrop={(event) => {
+        event.preventDefault();
+        void attachFiles([...event.dataTransfer.files]);
+      }}
     >
       <header className="flex items-center gap-2 border-foreground/5 border-b px-4 py-3">
         <span className="font-semibold text-sm">{title ?? l("base.agent")}</span>
@@ -278,34 +314,50 @@ export const DefaultChat = ({
         <Question key={session.pendingQuestion.callId} question={session.pendingQuestion} />
       ) : null}
       <Menu commands={commandMenu} onCommand={runCommand} onPrompt={pick} prompts={promptMenu} />
-      <div className="flex items-center gap-2 border-foreground/5 border-t p-3">
-        <input
-          className={inputRecipe({ size: "sm" }, "flex-1")}
-          onChange={(event) => setDraft(event.target.value)}
-          ref={inputRef}
-          onKeyDown={(event) => {
-            
-            if ((event.key === "ArrowUp" || event.key === "ArrowDown") && sent.current.length) {
+      <div className="flex flex-col gap-2 border-foreground/5 border-t p-3">
+        {attached.length ? (
+          <Chips
+            attachments={attached}
+            onRemove={(idx) => setAttached((current) => current.filter((_, at) => at !== idx))}
+            removeLabel={l("base.agentAttachRemove")}
+          />
+        ) : null}
+        <div className="flex items-center gap-2">
+          <Attach label={l("base.agentAttach")} onPick={(files) => void attachFiles(files)} />
+          <input
+            className={inputRecipe({ size: "sm" }, "flex-1")}
+            onChange={(event) => setDraft(event.target.value)}
+            ref={inputRef}
+            onKeyDown={(event) => {
+              
+              if ((event.key === "ArrowUp" || event.key === "ArrowDown") && sent.current.length) {
+                event.preventDefault();
+                step(event.key === "ArrowUp" ? 1 : -1);
+                return;
+              }
+              if (event.key !== "Enter" || event.nativeEvent.isComposing) return;
               event.preventDefault();
-              step(event.key === "ArrowUp" ? 1 : -1);
-              return;
-            }
-            if (event.key !== "Enter" || event.nativeEvent.isComposing) return;
-            event.preventDefault();
-            send();
-          }}
-          placeholder={session.pendingQuestion ? l("base.agentAnswer") : l("base.agentPlaceholder")}
-          value={draft}
-        />
-        {session.isRunning && !session.pendingQuestion ? (
-          <Button onClick={session.abort} size="sm" variant="outline">
-            {l("base.stop")}
-          </Button>
-        ) : (
-          <Button disabled={!draft.trim()} onClick={send} size="sm">
-            {l("base.send")}
-          </Button>
-        )}
+              send();
+            }}
+            onPaste={(event) => {
+              const files = [...event.clipboardData.files];
+              if (!files.length) return;
+              event.preventDefault();
+              void attachFiles(files);
+            }}
+            placeholder={session.pendingQuestion ? l("base.agentAnswer") : l("base.agentPlaceholder")}
+            value={draft}
+          />
+          {session.isRunning && !session.pendingQuestion ? (
+            <Button onClick={session.abort} size="sm" variant="outline">
+              {l("base.stop")}
+            </Button>
+          ) : (
+            <Button disabled={!draft.trim() && !attached.length} onClick={send} size="sm">
+              {l("base.send")}
+            </Button>
+          )}
+        </div>
       </div>
     </aside>,
   );

package/ui/Agent/ChatCommands.ts

@@ -72,6 +72,8 @@ export class ChatCommands {
       if (message.local) continue;
       lines.push(`**${message.role}**`);
       if (message.text) lines.push(message.text);
+      for (const attachment of message.attachments ?? [])
+        lines.push(`- attached \`${attachment.name}\` (${attachment.mimeType})`);
       for (const call of message.toolCalls ?? []) lines.push(`- call \`${call.name}\` ${JSON.stringify(call.args)}`);
       for (const result of message.toolResults ?? [])
         lines.push(

package/ui/Agent/attachment.ts

@@ -0,0 +1,53 @@
+import type { MessageAttachment } from "../../vendor/use-agentic";
+
+/** Turns one picked file into an attachment, or `null` to say this reader does not handle that file. */
+export type AttachReader = (file: File) => Promise<MessageAttachment | null>;
+
+/**
+ * Per-file ceiling for the composer. The bytes ride inside one turn's JSON request, so a file past this is not a
+ * slow attachment — it is a request the relay and the provider both refuse, and refusing it here is the only place
+ * the user learns which file it was.
+ */
+export const maxAttachmentBytes = 4 * 1024 * 1024;
+
+export type AttachFailure = "tooLarge" | "unsupported";
+
+const textMimes = new Set(["application/json", "application/xml", "application/x-yaml", "application/yaml"]);
+
+export class Attachment {
+  /**
+   * Reads what a browser can read on its own — an image as bytes, a text-ish file as text — and hands everything
+   * else to the app's own reader. That split is the layer boundary: a PDF needs a parser, so extracting one is the
+   * app's business (`attach`), while carrying the result is the framework's.
+   *
+   * The app's reader runs first so it can also replace the built-in handling, which is what downscaling an image
+   * before it costs a megabyte of prompt looks like.
+   */
+  static async read(file: File, attach?: AttachReader): Promise<MessageAttachment | AttachFailure> {
+    if (file.size > maxAttachmentBytes) return "tooLarge";
+    const injected = await attach?.(file);
+    if (injected) return injected;
+    
+    const mimeType = file.type.split(";")[0].trim().toLowerCase();
+    if (mimeType.startsWith("image/")) return { name: file.name, mimeType, data: await Attachment.#base64(file) };
+    if (mimeType.startsWith("text/") || textMimes.has(mimeType))
+      return { name: file.name, mimeType: mimeType || "text/plain", text: await file.text() };
+    return "unsupported";
+  }
+
+  static failure(value: MessageAttachment | AttachFailure): value is AttachFailure {
+    return typeof value === "string";
+  }
+
+  /**
+   * Chunked because `String.fromCharCode(...bytes)` spreads one argument per byte, and a megabyte of them is a
+   * RangeError rather than a slow call.
+   */
+  static async #base64(file: File): Promise<string> {
+    const bytes = new Uint8Array(await file.arrayBuffer());
+    const chunk = 0x8000;
+    let binary = "";
+    for (let at = 0; at < bytes.length; at += chunk) binary += String.fromCharCode(...bytes.subarray(at, at + chunk));
+    return btoa(binary);
+  }
+}

package/ui/Agent/sessionHistory.ts

@@ -3,6 +3,25 @@ import type { ChatMessage, SessionHistory } from "../../vendor/use-agentic";
 
 export type PersistOption = boolean | { storage?: "session" | "local"; key?: string };
 
+/**
+ * Attachment content never reaches storage. Web storage is a few megabytes per origin, one screenshot fills a
+ * chunk of it, and `AgentSession` swallows a failed save — so persisting the bytes would quietly stop persisting
+ * the transcript itself. The name and type stay so a restored conversation still reads as what happened, and a
+ * `url` stays because a pointer is not content; the server then tells the model the content is gone rather than
+ * letting it answer from the filename.
+ */
+const withoutContent = (message: ChatMessage): ChatMessage =>
+  message.attachments?.length
+    ? {
+        ...message,
+        attachments: message.attachments.map(({ name, mimeType, url }) => ({
+          name,
+          mimeType,
+          ...(url ? { url } : {}),
+        })),
+      }
+    : message;
+
 /**
  * Maps the `persist` prop onto a `SessionHistory` over web storage. Session storage is the default on purpose:
  * surviving a refresh is the whole ask, and a transcript that dies with the tab never lingers on a shared machine
@@ -24,7 +43,7 @@ export const sessionHistoryOf = (persist: PersistOption | undefined, pathKey = "
       return parsed.v === version && Array.isArray(parsed.messages) ? parsed.messages : null;
     },
     save: (messages) => {
-      storage.setItem(key, JSON.stringify({ v: version, messages: messages.slice(-cap) }));
+      storage.setItem(key, JSON.stringify({ v: version, messages: messages.slice(-cap).map(withoutContent) }));
     },
     clear: () => {
       storage.removeItem(key);

package/ui/Dropdown.tsx

@@ -1,8 +1,11 @@
 "use client";
 import { cn } from "akanjs/client";
+import { capitalize } from "akanjs/common";
+import { st } from "akanjs/store";
 import { type ReactNode, useEffect, useId, useRef, useState } from "react";
 import { createPortal } from "react-dom";
 
+import { agentAttrs } from "./agentAttrs";
 import { buttonRecipe } from "./Button";
 import {
   isOwnOverlayClick,
@@ -32,6 +35,8 @@ export interface DropdownProps {
   dropdownClassName?: string;
   /** Trigger edge the menu lines up with. Position is computed, so a `left-0` class cannot do this. */
   align?: "start" | "end";
+  /** Names this dropdown for the in-page agent. Without it the menu publishes nothing — two on one screen would share a name. */
+  namespace?: string;
 }
 
 export const DefaultDropdown = ({
@@ -41,9 +46,11 @@ export const DefaultDropdown = ({
   buttonClassName,
   dropdownClassName,
   align = "end",
+  namespace,
 }: DropdownProps) => {
   const [opened, setOpened] = useState(false);
-  const [mounted, setMounted] = useState(false);
+
+  const [portal, setPortal] = useState<HTMLElement | null>(null);
   const ref = useRef<HTMLDivElement>(null);
   const menuRef = useRef<HTMLUListElement>(null);
   const scope = useOverlayScope(useId());
@@ -52,6 +59,29 @@ export const DefaultDropdown = ({
   
   const recipe = useUiRecipe("button") ?? buttonRecipe;
   const position = useOverlayPosition({ opened, triggerRef: ref, panelRef: menuRef, align });
+  const suffix = namespace ? capitalize(namespace) : "";
+  st.expose(namespace ? `dropdownIn${suffix}` : null, opened, { desc: "Whether this dropdown menu is showing." });
+  const openDropdown = st
+    .tool(namespace ? `openDropdownIn${suffix}` : null, {
+      desc: `Open the ${namespace ?? ""} dropdown menu.`,
+      effect: "state",
+    })
+    .exec(() => {
+      setOpened(true);
+    });
+  const closeDropdown = st
+    .tool(namespace ? `closeDropdownIn${suffix}` : null, {
+      desc: `Close the ${namespace ?? ""} dropdown menu.`,
+      effect: "state",
+    })
+    .exec(() => {
+      setOpened(false);
+    });
+  
+  const toggle = opened ? closeDropdown : openDropdown;
+  useEffect(() => {
+    setPortal(document.body);
+  }, []);
   useEffect(() => {
     if (!opened) return;
     const onMouseDown = (e: MouseEvent) => {
@@ -102,15 +132,15 @@ export const DefaultDropdown = ({
         aria-haspopup="menu"
         aria-expanded={opened}
         className={recipe({ variant: "ghost" }, ["flex", buttonClassName])}
-        onClick={() => {
-          setMounted(true);
-          setOpened((o) => !o);
-        }}
+        onClick={toggle}
+        {...agentAttrs(toggle)}
       >
         {value}
       </button>
-      {/* Hidden rather than unmounted once opened: unmounting takes any overlay a menu item opened down with it. */}
-      {mounted && typeof document !== "undefined" ? createPortal(menu, document.body) : null}
+      {/* Mounted from the first render and hidden while closed: a menu item declares its tool on mount, so an
+          unmounted menu publishes nothing an agent could find — and unmounting an open one takes any overlay
+          a menu item opened down with it. */}
+      {portal ? createPortal(menu, portal) : null}
     </div>
   );
 };

package/ui/index.ts

@@ -1,4 +1,5 @@
 export { Agent } from "./Agent";
+export { type AttachReader, maxAttachmentBytes } from "./Agent/attachment";
 export { agentAttrs } from "./agentAttrs";
 export { animated } from "./animated";
 export { Badge } from "./Badge";

package/vendor/use-agentic/AgentSession.ts

@@ -237,7 +237,9 @@ export class AgentSession {
    */
   retry = async (): Promise<boolean> => {
     if (this.#active) return false;
-    const at = this.#messages.findLastIndex((message) => message.role === "user" && !!message.text);
+    const at = this.#messages.findLastIndex(
+      (message) => message.role === "user" && (!!message.text || !!message.attachments?.length),
+    );
     if (at < 0) return false;
     const again = this.#messages[at];
     this.#messages = this.#messages.slice(0, at);

package/vendor/use-agentic/WIRE.md

@@ -33,6 +33,24 @@ tools, and the loop stay in the client; the server serves exactly one stateless
 - `context` blocks are host vocabulary. The server forwards them to the model as data, framed as data.
 - Everything is JSON-serializable by contract; a tool whose `result` is not is the tool's bug.
 
+## Attachments
+
+A message may carry files in `attachments` (`MessageAttachment`, `types.ts`) — one of `data` (base64 bytes), `url`,
+or `text` (already-extracted content), plus `name` and `mimeType`:
+
+```jsonc
+{ "role": "user", "text": "What does this chart say?",
+  "attachments": [{ "name": "q3.png", "mimeType": "image/png", "data": "iVBORw0KG…" }] }
+```
+
+They are content, not instructions, and the server frames them the way it frames `context`. **A backend must not
+silently drop one its model cannot read** — a file the model never saw is a file it invents an answer about. Replace
+it with a note in the message text saying which file was not read and why, so the model can say so and ask for
+another form. `text` is readable by every provider by definition, which is what makes an extracted PDF work against
+a text-only model.
+
+Nothing here is stored: the wire carries the bytes for exactly one turn's request.
+
 ## Response
 
 `200` with a single JSON object:

package/vendor/use-agentic/types.ts

@@ -119,9 +119,33 @@ export interface ToolCallResult {
   error?: string;
 }
 
+/**
+ * A file the user handed the conversation rather than the screen — which is why it rides a message instead of a
+ * tool, the same reason `askUser` belongs to the session and not to the surface.
+ *
+ * Three carriers, one of which every attachment must have: `data` inlines the bytes, `url` points at something the
+ * provider can fetch, and `text` is content somebody already extracted — the only form a text-only model can read.
+ * They mirror what the server's own `Msg.image` / `Msg.link` / `Msg.resource` builders produce, so a prompt's
+ * attachment and a user's are the same thing on the wire.
+ *
+ * Whether a given carrier reaches the model is the provider's answer, not this type's: a backend drops what its
+ * model cannot read and says so in the transcript, because a silently dropped file is one the model then
+ * hallucinates about.
+ */
+export interface MessageAttachment {
+  name: string;
+  mimeType: string;
+  /** Base64, with no `data:` prefix. */
+  data?: string;
+  url?: string;
+  text?: string;
+}
+
 export interface ChatMessage {
   role: ChatRole;
   text?: string;
+  /** Files the message carries. Content, not instructions — a backend frames them the way it frames context. */
+  attachments?: MessageAttachment[];
   toolCalls?: ToolCallRequest[];
   toolResults?: ToolCallResult[];
   /** A failed or capped turn, recorded in the transcript rather than thrown past it. */