akanjs 3.0.0-beta.5 → 3.0.0-beta.7

package/fetch/client/wsClient.ts

@@ -171,13 +171,13 @@ export class WsClient {
             break;
         }
       } catch (error) {
-        this.logger.warn("WebSocket message process failed");
-        console.error(error);
+        const errMsg = error instanceof Error ? error.message : String(error);
+        this.logger.warn(`WebSocket message process failed ${errMsg}`);
       }
     };
     this.#ws.onerror = (e) => {
-      this.logger.debug(`WebSocket error`);
-      console.error(e);
+      const errMsg = e instanceof Error ? e.message : String(e);
+      this.logger.verbose(`WebSocket error ${errMsg}`);
     };
     this.#ws.onclose = (event) => {
       this.logger.debug(`WebSocket closed: ${event.code} ${event.reason}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-beta.5",
+  "version": "3.0.0-beta.7",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/service/predefinedAdaptor/anthropicLlm.ts

@@ -297,9 +297,15 @@ export class AnthropicLlm
     return source.type === "base64" ? { ...source, media_type: mimeType } : source;
   }
 
+  /**
+   * Bytes beat an address when a host sent both: it already paid for them on the way in, and the address it also
+   * sent is the one it renders — which the default storage backend serves on a path only the app can resolve.
+   * Picking that costs a confident answer about a picture nothing fetched; picking the bytes costs one hop that
+   * already carries them. A URL the provider really can reach travels alone.
+   */
   static sourceOf(attachment: AgentWireAttachment): AnthropicSource | null {
-    if (attachment.url) return { type: "url", url: attachment.url };
     if (attachment.data) return { type: "base64", media_type: attachment.mimeType, data: attachment.data };
+    if (attachment.url) return { type: "url", url: attachment.url };
     return null;
   }
 

package/service/predefinedAdaptor/openaiDialect.ts

@@ -122,7 +122,7 @@ export class OpenaiDialect {
    * Text attachments are labelled into the message, because a model handed two unlabelled documents can no longer
    * cite either one. Images become their own parts only when the provider said it reads them; the dialect carries
    * one as a `data:` URL, which is the same encoding whether the bytes were inlined or already addressable, so
-   * both carriers take one branch.
+   * both carriers take one branch — the inlined bytes first, for the reason named at the branch.
    */
   static userContent(message: AgentWireMessage, accepts?: LlmAccepts): string | OpenaiContentPart[] {
     const attachments = message.attachments ?? [];
@@ -144,7 +144,8 @@ export class OpenaiDialect {
             );
             return [];
           }
-          const url = attachment.url ?? (attachment.data ? `data:${mimeType};base64,${attachment.data}` : "");
+
+          const url = attachment.data ? `data:${mimeType};base64,${attachment.data}` : (attachment.url ?? "");
           return url ? [{ type: "image_url" as const, image_url: { url } }] : [];
         });
     const text = [message.text, ...blocks, ...notes].filter(Boolean).join("\n\n");

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

@@ -109,6 +109,12 @@ export declare class AnthropicLlm extends AnthropicLlm_base implements LlmAdapto
     static userContent(message: AgentWireMessage, accepts?: LlmAccepts): AnthropicBlock[];
     /** The block's `media_type` is the essence, not whatever parameters the browser attached to it. */
     static typed(source: AnthropicSource, mimeType: string): AnthropicSource;
+    /**
+     * Bytes beat an address when a host sent both: it already paid for them on the way in, and the address it also
+     * sent is the one it renders — which the default storage backend serves on a path only the app can resolve.
+     * Picking that costs a confident answer about a picture nothing fetched; picking the bytes costs one hop that
+     * already carries them. A URL the provider really can reach travels alone.
+     */
     static sourceOf(attachment: AgentWireAttachment): AnthropicSource | null;
     static turnAnswer(answer: AnthropicAnswer): LlmTurnAnswer;
     /** The ceiling wins over the calls that did arrive — see `OpenaiDialect.stopOf` for why. */

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

@@ -77,7 +77,7 @@ export declare class OpenaiDialect {
      * Text attachments are labelled into the message, because a model handed two unlabelled documents can no longer
      * cite either one. Images become their own parts only when the provider said it reads them; the dialect carries
      * one as a `data:` URL, which is the same encoding whether the bytes were inlined or already addressable, so
-     * both carriers take one branch.
+     * both carriers take one branch — the inlined bytes first, for the reason named at the branch.
      */
     static userContent(message: AgentWireMessage, accepts?: LlmAccepts): string | OpenaiContentPart[];
     /**

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

@@ -5,7 +5,7 @@ interface AttachProps {
     onPick: (files: File[]) => void;
 }
 export declare const Attach: ({ className, label, onPick }: AttachProps) => import("react/jsx-runtime").JSX.Element;
-interface ChipsProps {
+export interface ChipsProps {
     className?: string;
     attachments: readonly MessageAttachment[];
     /** Omitted for a sent message: what is already on the wire cannot be taken back. */

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

@@ -72,9 +72,10 @@ export interface ChatProps {
      * the built-in, so it can also replace how an image is prepared.
      *
      * **A `url` is handed to the provider as the address it will fetch**, so answer `data` whenever the provider
-     * cannot reach it. A reader that uploads is the natural place to get this wrong: the default storage backend
-     * serves a path only this app can resolve, and a model handed one answers about a picture it never saw, with
-     * nothing anywhere reporting a failure.
+     * cannot reach it — the default storage backend serves a path only this app can resolve, and a model handed one
+     * answers about a picture it never saw with nothing anywhere reporting a failure. Answering **both** is the
+     * shape for that case: bytes are what the provider is given, and the address is what the chip draws, so an
+     * uploading reader gets a thumbnail without betting the answer on who can reach its storage.
      */
     attach?: AttachReader;
     /**

package/types/ui/index.d.ts

@@ -1,6 +1,7 @@
 export { AgentProvider, type AgentProviderProps, type AgentRunner, AgentSession, type AgentSessionOptions, type ChatMessage, type CompactOptions, type ContextBlock, httpRunner, type MessageAttachment, type PublishedTool, type RunnerEvent, type RunnerRequest, SessionContext, type SessionHistory, type SurfaceView, useAgent, } from "../vendor/use-agentic.d.ts";
 export { Agent } from "./Agent.d.ts";
 export { type ApprovalProps, DefaultApproval } from "./Agent/Approval.d.ts";
+export { Chips as AgentAttachments, type ChipsProps as AgentAttachmentsProps } from "./Agent/Attach.d.ts";
 export { type AgentSessionSetup, agentSessionOf } from "./Agent/agentSessionOf.d.ts";
 export { type AttachLimits, type AttachReader, maxAttachmentBytes, maxMessageAttachmentBytes, maxMessageAttachments, } from "./Agent/attachment.d.ts";
 export { type BubbleProps, DefaultBubble } from "./Agent/Bubble.d.ts";

package/ui/Agent/Attach.tsx

@@ -38,7 +38,7 @@ export const Attach = ({ className, label, onPick }: AttachProps) => {
   );
 };
 
-interface ChipsProps {
+export interface ChipsProps {
   className?: string;
 
   attachments: readonly MessageAttachment[];
@@ -57,11 +57,11 @@ export const Chips = ({ className, attachments, onRemove, removeLabel, pending =
         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/") ? (
+        {(attachment.data || attachment.url) && attachment.mimeType?.startsWith("image/") ? (
           <img
             alt={attachment.name}
             className="size-6 rounded-field object-cover"
-            src={`data:${attachment.mimeType};base64,${attachment.data}`}
+            src={attachment.data ? `data:${attachment.mimeType};base64,${attachment.data}` : attachment.url}
           />
         ) : null}
         <span className="max-w-32 truncate">{attachment.name}</span>

package/ui/Agent/Chat.tsx

@@ -111,9 +111,10 @@ export interface ChatProps {
    * the built-in, so it can also replace how an image is prepared.
    *
    * **A `url` is handed to the provider as the address it will fetch**, so answer `data` whenever the provider
-   * cannot reach it. A reader that uploads is the natural place to get this wrong: the default storage backend
-   * serves a path only this app can resolve, and a model handed one answers about a picture it never saw, with
-   * nothing anywhere reporting a failure.
+   * cannot reach it — the default storage backend serves a path only this app can resolve, and a model handed one
+   * answers about a picture it never saw with nothing anywhere reporting a failure. Answering **both** is the
+   * shape for that case: bytes are what the provider is given, and the address is what the chip draws, so an
+   * uploading reader gets a thumbnail without betting the answer on who can reach its storage.
    */
   attach?: AttachReader;
   /**

package/ui/Agent/sessionHistory.ts

@@ -8,16 +8,19 @@ export type PersistOption = boolean | { storage?: "session" | "local"; key?: str
  * 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.
+ * letting it answer from the filename. A `ref` stays for the same reason and matters more: it is the host's own
+ * handle on the file, so dropping it leaves a restored conversation with nothing but a name and size to guess
+ * from — the guess `ref` exists to retire.
  */
 const withoutContent = (message: ChatMessage): ChatMessage =>
   message.attachments?.length
     ? {
         ...message,
-        attachments: message.attachments.map(({ name, mimeType, url }) => ({
+        attachments: message.attachments.map(({ name, mimeType, url, ref }) => ({
           name,
           mimeType,
           ...(url ? { url } : {}),
+          ...(ref ? { ref } : {}),
         })),
       }
     : message;

package/ui/index.ts

@@ -21,6 +21,7 @@ export {
 } from "../vendor/use-agentic";
 export { Agent } from "./Agent";
 export { type ApprovalProps, DefaultApproval } from "./Agent/Approval";
+export { Chips as AgentAttachments, type ChipsProps as AgentAttachmentsProps } from "./Agent/Attach";
 export { type AgentSessionSetup, agentSessionOf } from "./Agent/agentSessionOf";
 export {
   type AttachLimits,

package/vendor/use-agentic/Compaction.ts

@@ -100,7 +100,9 @@ export class Compaction {
   static #line(message: ChatMessage): string {
     const parts: string[] = [];
     if (message.text) parts.push(Compaction.#clip(message.text, 1200));
-    for (const attachment of message.attachments ?? []) parts.push(`[attached ${attachment.name}]`);
+
+    for (const attachment of message.attachments ?? [])
+      parts.push(`[attached ${attachment.name}, content not carried into this summary]`);
     for (const call of message.toolCalls ?? [])
       parts.push(`[called ${call.name} ${Compaction.#clip(JSON.stringify(call.args), 200)}]`);
     for (const result of message.toolResults ?? [])