akanjs 3.0.0-beta.1 → 3.0.0-beta.10

package/common/index.ts

@@ -111,6 +111,7 @@ export { sleep } from "./sleep";
 export { splitVersion } from "./splitVersion";
 export { getBasePathFromPathname, parseBasePaths, parseSubRouteHosts, resolveSubRouteHosts } from "./subRoute";
 export { TrustedProxy } from "./TrustedProxy";
+export { toPathSegments } from "./toPathSegments";
 export type * from "./types";
 export {
   type WebsocketAuthAckData,

package/common/pathGet.ts

@@ -1,13 +1,23 @@
+import { toPathSegments } from "./toPathSegments";
+
 type Indexable = Record<string | number, unknown>;
+type PathSegment = string | number;
 
 const isIndexable = (value: unknown): value is Indexable => Object(value) === value;
 
+const readChild = (container: Indexable, key: PathSegment) =>
+  container instanceof Map ? (container as Map<PathSegment, unknown>).get(key) : container[key];
+
 export const pathGet = (
   path: string | (string | number)[],
   obj: unknown,
   separator = ".",
   fallback: unknown = null,
 ): unknown => {
-  const properties = Array.isArray(path) ? path : path.split(separator);
-  return properties.reduce((prev, curr) => (isIndexable(prev) ? (prev[curr] ?? fallback) : fallback), obj);
+
+  const properties = separator === "." ? toPathSegments(path) : Array.isArray(path) ? [...path] : path.split(separator);
+  return properties.reduce<unknown>(
+    (prev, curr) => (isIndexable(prev) ? (readChild(prev, curr) ?? fallback) : fallback),
+    obj,
+  );
 };

package/common/pathSet.ts

@@ -1,10 +1,9 @@
+import { toPathSegments } from "./toPathSegments";
+
 type MutableIndexable = Record<string | number, unknown>;
 type PathSegment = string | number;
 type Container = MutableIndexable | Map<PathSegment, unknown>;
 
-const toPathSegments = (path: string | readonly PathSegment[]) =>
-  Array.isArray(path) ? [...path] : path.toString().match(/[^.[\]]+/g) || [];
-
 const readChild = (container: Container, key: PathSegment) =>
   container instanceof Map ? container.get(key) : container[key];
 

package/common/toPathSegments.ts

@@ -0,0 +1,10 @@
+type PathSegment = string | number;
+
+/**
+ * The one definition of what a dotted path's segments are, so a path that writes and a path that reads cannot
+ * disagree about it. `a.0.b` and `a[0].b` are the same three segments — the bracket form is what a form field
+ * hands `writeOn<Model>`, and a read of the same path has to accept the same spelling or the agent can write
+ * somewhere it cannot read back.
+ */
+export const toPathSegments = (path: string | readonly PathSegment[]) =>
+  Array.isArray(path) ? [...path] : path.toString().match(/[^.[\]]+/g) || [];

package/common/types.ts

@@ -5,7 +5,11 @@ export interface FetchPolicy<Returns = unknown> {
   onError?: (error: string) => void;
   token?: string;
   partial?: string[];
-  timeout?: number;
+  /**
+   * Milliseconds before this call is abandoned, `false` to wait as long as the runtime will. Overrides the
+   * endpoint's declared `timeout`, which overrides the client's own default.
+   */
+  timeout?: number | false;
   /**
    * A `pubsub` subscription only: called after the room has been resubscribed following a dropped connection.
    *

package/dictionary/agentTurn.dictionary.ts

@@ -19,11 +19,15 @@ export const agentTurnDictionary = scalarDictionary(["en", "ko"])
       "클라이언트가 실행할 툴 호출 목록 ({ id, name, args })",
     ]),
     stop: t(["Stop", "종료 사유"]).desc([
-      "Why the turn ended — end, or toolUse when tool results are awaited",
-      "턴이 끝난 이유 — end 또는 툴 결과를 기다리는 toolUse",
+      "Why the turn ended — end, toolUse when tool results are awaited, or length when the provider cut it off",
+      "턴이 끝난 이유 — end, 툴 결과를 기다리는 toolUse, 프로바이더가 잘라낸 length",
     ]),
   }))
   .enum<AgentStop>("agentStop", (t) => ({
     end: t(["End", "종료"]).desc(["The final answer", "최종 응답"]),
     toolUse: t(["Tool Use", "툴 사용"]).desc(["The model awaits tool results", "모델이 툴 결과를 기다린다"]),
+    length: t(["Length", "길이 초과"]).desc([
+      "The provider's answer ceiling cut the turn off, so it is incomplete",
+      "프로바이더의 응답 상한에 걸려 턴이 잘렸다. 미완성이다",
+    ]),
   }));

package/dictionary/base.dictionary.ts

@@ -81,6 +81,11 @@ export const baseDictionary = serviceDictionary(["en", "ko"])
     agentAttach: ["Attach a file", "파일 첨부"],
     agentAttachRemove: ["Remove attachment", "첨부 제거"],
     agentAttachReading: ["Reading…", "읽는 중…"],
+    agentReferenceRemove: ["Remove reference", "참조 제거"],
+    agentReferenceFailed: [
+      "{label} could not be read, so the agent has only its name.",
+      "{label}을(를) 읽지 못해 이름만 전달됩니다.",
+    ],
     agentAttachTooLarge: ["{name} is too large to attach.", "{name}은(는) 용량이 너무 커서 첨부할 수 없습니다."],
     agentAttachUnsupported: ["{name} cannot be attached here.", "{name}은(는) 여기에 첨부할 수 없습니다."],
     agentAttachDuplicate: ["{name} is already attached.", "{name}은(는) 이미 첨부되어 있습니다."],

package/fetch/agentTurn.ts

@@ -1,7 +1,7 @@
 import { Any, enumOf } from "akanjs/base";
 import { ConstantRegistry, via } from "akanjs/constant";
 
-export class AgentStop extends enumOf("agentStop", ["end", "toolUse"] as const) {}
+export class AgentStop extends enumOf("agentStop", ["end", "toolUse", "length"] as const) {}
 
 export class AgentTurn extends via((field) => ({
   text: field(String, { default: "" }), // the assistant's words; empty when the turn is only tool calls

package/fetch/client/fetchClient.ts

@@ -173,6 +173,13 @@ export class FetchClient {
         }
       : signal;
   }
+  /**
+   * The budget for every call that neither names one nor is served by an endpoint declaring one. `false` waits
+   * as long as the runtime will, which is the browser's own limit — minutes.
+   */
+  setTimeout(timeout?: number | false) {
+    this.http.setTimeout(timeout);
+  }
   setErrorConstructor(ErrorCls?: ErrorConstructor) {
     this.ErrorCls = ErrorCls;
     this.http.setErrorConstructor(ErrorCls);
@@ -316,8 +323,9 @@ export class FetchClient {
           const url = FetchClient.makeHttpUrl(key, endpoint, prefix, argMap);
           const headers = this.#makeAuthHeaders(option);
           const baseUrl = option?.origin;
+          const timeout = option?.timeout ?? endpoint.timeout;
 
-          const requestQuery = () => this.http.get(url, { headers, baseUrl });
+          const requestQuery = () => this.http.get(url, { headers, baseUrl, timeout });
 
           const claim = baseUrl
             ? { value: requestQuery(), owned: true }
@@ -339,6 +347,7 @@ export class FetchClient {
           const response = await this.http.send(endpoint.method ?? "POST", url, body, {
             headers: this.#makeAuthHeaders(option),
             baseUrl: option?.origin,
+            timeout: option?.timeout ?? endpoint.timeout,
           });
           const parsedReturn = parseReturn(response, { crystalize: option?.crystalize ?? true });
           return parsedReturn;
@@ -827,7 +836,15 @@ export class FetchClient {
       connect = false,
       base,
       Err,
-    }: { origin?: string; connect?: boolean; base?: FetchProxy; Err?: ErrorConstructor } = {},
+      timeout,
+    }: {
+      origin?: string;
+      connect?: boolean;
+      base?: FetchProxy;
+      Err?: ErrorConstructor;
+      /** This app's own default request budget, for calls no endpoint and no caller gave one. */
+      timeout?: number | false;
+    } = {},
   ): {
     sig: ClientSignalMap<SigType>;
     fetch: SigType["fetch"];
@@ -838,6 +855,7 @@ export class FetchClient {
     const proxy =
       shared ??
       FetchClient.#makeProxy<unknown, Record<string, SliceMeta>>(new FetchClient(origin, {}, serializedSignal, Err));
+    if (timeout !== undefined) proxy.instance.setTimeout(timeout);
     if (connect) proxy.instance.connect();
     const sig = {} as any;
     Object.entries(serializedSignal).forEach(([refName, serializedSignal]) => {

package/fetch/client/httpClient.ts

@@ -49,6 +49,10 @@ export class HttpClient {
   setErrorConstructor(ErrorCls?: ErrorConstructor) {
     this.ErrorCls = ErrorCls;
   }
+  /** The budget every call that names none takes. `false` waits as long as the runtime will. */
+  setTimeout(timeout?: number | false) {
+    this.#timeout = timeout;
+  }
   #resolveBaseUrl(baseUrl?: string) {
     return (baseUrl ?? this.baseUrl).replace(/\/$/, "");
   }

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/index.ts

@@ -292,6 +292,11 @@ export interface SubspaceDeclaration {
   repo: string;
   /** Apps this subspace serves. Libraries are never listed — they are derived from each app's closure. */
   apps: string[];
+  /**
+   * The cloud workspace this subspace deploys from — its own `AKAN_WORKSPACE_ID`, not this workspace's.
+   * `akan subspace upload-env` is the only thing that reads it.
+   */
+  workspaceId?: string;
 }
 
 /**

package/package.json

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

package/server/di/diLifecycle.ts

@@ -17,7 +17,7 @@ import { agentTurnConstant, agentTurnDocument } from "../../signal/agentTurn";
 import { Base, BaseEndpoint, BaseInternal } from "../../signal/base.signal";
 import type { Endpoint } from "../../signal/endpoint";
 import type { Internal } from "../../signal/internal";
-import { Logging, type MiddlewareCls } from "../../signal/middleware";
+import { Cache, Logging, type MiddlewareCls, Timeout } from "../../signal/middleware";
 import type { ServerSignal, ServerSignalCls } from "../../signal/serverSignal";
 import { SignalRegistry } from "../../signal/signalRegistry";
 import type { AkanLib, DatabaseModule, ScalarModule, ServiceModule } from "../akanLib";
@@ -126,6 +126,10 @@ export class DiLifecycle {
       : null;
     if (frameworkAgent) this.#service.set("agent", frameworkAgent);
     this.#middleware.set(Logging.refName, Logging);
+
+    this.#middleware.set(Timeout.refName, Timeout);
+
+    this.#middleware.set(Cache.refName, Cache);
     const defaultOption = createDefaultAkanOption();
     defaultOption.getMiddlewares().forEach((middleware) => {
       this.#middleware.set(middleware.refName, middleware);

package/service/agent.service.ts

@@ -2,6 +2,7 @@ import { Err } from "akanjs/dictionary";
 import type {
   AgentWireAttachment,
   AgentWireMessage,
+  AgentWireReference,
   LlmAccepts,
   LlmTurnRequest,
 } from "./predefinedAdaptor/llm.adaptor";
@@ -16,7 +17,9 @@ export class AgentService extends serve("agent" as const, ({ plug }) => ({
 
     const names = ToolNames.of(request);
     const prepared = names.encode(
-      AgentService.instructed(AgentService.readable(AgentService.explained(request), this.llm.accepts)),
+      AgentService.instructed(
+        AgentService.readable(AgentService.referenced(AgentService.explained(request)), this.llm.accepts),
+      ),
     );
     const answer = await this.llm.chat(prepared, onDelta);
     if (!answer) throw new Err("agent.error.llmUnavailable");
@@ -68,6 +71,94 @@ export class AgentService extends serve("agent" as const, ({ plug }) => ({
     return { ...rest, text: [message.text, `[The turn failed: ${error}]`].filter(Boolean).join("\n\n") };
   }
 
+  /**
+   * The ceiling one reference's value may add to a turn, mirroring the client's own — the browser clips before it
+   * stages, and this is the same answer given again where nothing can route around it. `runTurn` is the only path
+   * to `chat()`, so a host that builds the wire itself, an older client, and a replayed transcript all pass here.
+   */
+  static readonly referenceLimit = 20_000;
+
+  /**
+   * Folds what the user pointed at into the message they pointed with, as text.
+   *
+   * Text rather than a carrier of its own for the same reason the note in `readable` is text: it is the one field
+   * every provider mapping already reads, so Anthropic, the OpenAI dialect and DeepSeek need no change between
+   * them and none of them can drop a reference quietly.
+   *
+   * The heading rides once per message rather than once per reference, and lives here rather than in `preamble`
+   * because most conversations never carry one — a sentence about mention tokens in every turn of every app is
+   * paid by every app that has no references at all.
+   */
+  static referenced(request: LlmTurnRequest): LlmTurnRequest {
+    if (!request.messages.some((message) => message.references?.length)) return request;
+    return { ...request, messages: request.messages.map((message) => AgentService.referencedMessage(message)) };
+  }
+
+  private static referencedMessage(message: AgentWireMessage): AgentWireMessage {
+    const { references = [], ...rest } = message;
+    if (!references.length) return message;
+    const block = [AgentService.referenceHeading, ...references.map(AgentService.referenceLine)].join("\n\n");
+    return { ...rest, text: [message.text, block].filter(Boolean).join("\n\n") };
+  }
+
+  /**
+   * Not decoration, and not free to shorten. Both halves of the sentence were observed doing their job, against
+   * Anthropic, with the same referenced field and only the published tools changed:
+   *
+   * - With no tool on the screen to re-read with, the model opened its answer by saying so — that it could see
+   *   only the snapshot and the field might have been edited since. Unprompted, ahead of the answer.
+   * - With the screen's own tools passed (a state read and a write), it issued the read instead of answering,
+   *   and stopped the turn there.
+   *
+   * So it reads as an instruction rather than as framing: it re-reads where it can and says it cannot where it
+   * cannot, which is the pair a turn confidently quoting a stale value is bought against. Two scenarios against
+   * one provider, not the per-cell runs behind `preamble` — enough to keep the sentence, not enough to call it
+   * measured.
+   */
+  static readonly referenceHeading =
+    "[Referenced data: the user pointed at this while writing the message above, with the @[label](mention:…) " +
+    "tokens in it. Each value is what it was at the moment they sent the message, not what it is now — read it " +
+    "again with a tool before relying on it, and do not assume an edit you have made since is reflected here.]";
+
+  /**
+   * A string value is printed as itself rather than as JSON. It is the common case — one field of one document —
+   * and a quoted, escaped copy of a paragraph is harder for a model to read back and to quote from than the
+   * paragraph. It is also what a clipped value already is, so the cut JSON prints as the fragment it is.
+   *
+   * The pointer leads the line rather than riding the wire alone, and that is what the label cannot do. Pointed
+   * at a saved document while a *different* document of the same model sat open on the screen, the model
+   * compared the two ids, said the edit it could make would land on the wrong one, and stopped to ask — with no
+   * write call. Two references sharing a label are still two ids here, so keep the id ahead of the label.
+   */
+  private static referenceLine(reference: AgentWireReference): string {
+    const at = `${reference.refName}/${reference.refId}${reference.path ? `#${reference.path}` : ""}`;
+    const head = `${at} (${reference.label}):`;
+    if (reference.value === undefined)
+      return `${head} [not read: ${reference.note ?? "the value was not carried into this conversation"}]`;
+    const text =
+      typeof reference.value === "string" ? reference.value : (JSON.stringify(reference.value, null, 2) ?? "null");
+    const body =
+      text.length <= AgentService.referenceLimit
+        ? text
+        : `${text.slice(0, AgentService.referenceLimit)}…\n[Clipped at ${AgentService.referenceLimit} characters.]`;
+    return `${head}\n${AgentService.fenced(body)}${reference.note ? `\n[${reference.note}]` : ""}`;
+  }
+
+  /**
+   * Where a value ends. A multi-line one — the usual shape of the prose field somebody points at — otherwise runs
+   * straight into the next reference's heading, and the model reads one value that swallowed the next label.
+   *
+   * The fence grows past the longest backtick run inside the value, which is CommonMark's own answer to the same
+   * problem: a fixed fence is one that a value containing a fence breaks out of, and a value containing a fence is
+   * ordinary here, because the thing being pointed at is often something a person wrote.
+   */
+  private static fenced(text: string): string {
+    const runs = text.match(/`+/g);
+    const longest = runs ? Math.max(...runs.map((run) => run.length)) : 0;
+    const fence = "`".repeat(Math.max(3, longest + 1));
+    return `${fence}\n${text}\n${fence}`;
+  }
+
   /**
    * 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:
@@ -98,14 +189,18 @@ export class AgentService extends serve("agent" as const, ({ plug }) => ({
   private static isReadable(attachment: AgentWireAttachment, accepts: LlmAccepts): boolean {
     if (attachment.text) return true;
     if (!attachment.data && !attachment.url) return false;
+
+    if (typeof attachment.mimeType !== "string") 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";
+      !attachment.data && !attachment.url
+        ? "its content is no longer available, as a reloaded conversation keeps the name and not the bytes"
+        : typeof attachment.mimeType === "string"
+          ? "this model cannot read that type"
+          : "it names no type it could be read as";
     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/anthropicLlm.ts

@@ -58,6 +58,18 @@ export class AnthropicLlm
    */
   static readonly defaultMaxTokens = 8192;
 
+  /**
+   * The four the API's image block reads. An exact set rather than an `image/*` prefix, because by the time an
+   * attachment reaches here `accepts.image` has already carried it past `AgentService.readable`: a phone's
+   * `image/heic` — the iPhone camera default, so the likeliest non-canonical image an app sees — arrives as bytes,
+   * becomes a block the API refuses, and takes the **whole turn** down on a 400 rather than going unread.
+   *
+   * The app cannot gate it either: `AttachReader` answers `null` for "not mine", which falls through to the
+   * built-in reader that base64s any `image/*`, so there is no way for a reader to refuse one. The check belongs
+   * where the block vocabulary is known, which is here.
+   */
+  static readonly imageTypes = new Set(["image/jpeg", "image/png", "image/gif", "image/webp"]);
+
   get #host() {
     return this.llmOption.host ?? "https://api.anthropic.com/v1";
   }
@@ -101,7 +113,7 @@ export class AnthropicLlm
    * so it is one line to diagnose rather than a model that appears to have refused.
    */
   #reported(answer: LlmTurnAnswer): LlmTurnAnswer {
-    if (!answer.text && !answer.toolCalls?.length)
+    if (!answer.text && !answer.toolCalls?.length && answer.stop !== "length")
       this.logger.warn(
         `Anthropic answered with no text and no tool call. If this repeats, raise option.setLlm({ maxTokens }) — currently ${this.llmOption.maxTokens ?? AnthropicLlm.defaultMaxTokens}.`,
       );
@@ -266,9 +278,13 @@ export class AnthropicLlm
         ];
       const source = AnthropicLlm.sourceOf(attachment);
       if (!source) return [];
-      if (accepts?.image && attachment.mimeType.startsWith("image/")) return [{ type: "image", source }];
+      
+      const mimeType = attachment.mimeType.split(";")[0].trim().toLowerCase();
+      if (accepts?.image && AnthropicLlm.imageTypes.has(mimeType))
+        return [{ type: "image", source: AnthropicLlm.typed(source, mimeType) }];
 
-      if (accepts?.document && attachment.mimeType === "application/pdf") return [{ type: "document", source }];
+      if (accepts?.document && mimeType === "application/pdf")
+        return [{ type: "document", source: AnthropicLlm.typed(source, mimeType) }];
       notes.push(`[Attachment not read: ${attachment.name} (${attachment.mimeType}) — this API has no block for it.]`);
       return [];
     });
@@ -276,9 +292,20 @@ export class AnthropicLlm
     return [...(text ? [{ type: "text" as const, text }] : []), ...blocks];
   }
 
+  /** The block's `media_type` is the essence, not whatever parameters the browser attached to it. */
+  static typed(source: AnthropicSource, mimeType: string): AnthropicSource {
+    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;
   }
 
@@ -294,10 +321,16 @@ export class AnthropicLlm
     return {
       ...(text ? { text } : {}),
       ...(toolCalls.length ? { toolCalls } : {}),
-      stop: answer.stop_reason === "tool_use" || toolCalls.length ? "toolUse" : "end",
+      stop: AnthropicLlm.stopOf(answer.stop_reason, toolCalls.length),
     };
   }
 
+  /** The ceiling wins over the calls that did arrive — see `OpenaiDialect.stopOf` for why. */
+  static stopOf(reason: string | null | undefined, calls: number): LlmTurnAnswer["stop"] {
+    if (reason === "max_tokens") return "length";
+    return reason === "tool_use" || calls ? "toolUse" : "end";
+  }
+
   /**
    * The API streams named SSE events rather than one chunk shape. A tool call opens as `content_block_start`
    * carrying its id and name and then arrives as `input_json_delta` fragments of a JSON string, so it is assembled
@@ -359,7 +392,7 @@ export class AnthropicLlm
     return {
       ...(text ? { text } : {}),
       ...(toolCalls.length ? { toolCalls } : {}),
-      stop: stopReason === "tool_use" || toolCalls.length ? "toolUse" : "end",
+      stop: AnthropicLlm.stopOf(stopReason, toolCalls.length),
     };
   }
 

package/service/predefinedAdaptor/llm.adaptor.ts

@@ -28,6 +28,22 @@ export interface AgentWireAttachment {
   ref?: string;
 }
 
+/**
+ * Data the caller pointed at while writing one message, rather than a file they attached. `value` is a snapshot
+ * taken when the message was sent and already masked by the host — the server has no model class to mask it with,
+ * so what the browser staged is what leaves. `refName`/`refId`/`path` are the way back to the current value, which
+ * is why they travel even when the value itself does not.
+ */
+export interface AgentWireReference {
+  refName: string;
+  refId: string;
+  label: string;
+  path?: string;
+  value?: unknown;
+  /** Read by the model in place of a value there is none of — clipped, unreadable, or gone from a restored chat. */
+  note?: 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.
@@ -36,6 +52,7 @@ export interface AgentWireMessage {
   role: "user" | "assistant" | "tool";
   text?: string;
   attachments?: AgentWireAttachment[];
+  references?: AgentWireReference[];
   toolCalls?: AgentWireToolCall[];
   toolResults?: AgentWireToolResult[];
   error?: string;
@@ -68,7 +85,13 @@ export interface LlmTurnRequest {
 export interface LlmTurnAnswer {
   text?: string;
   toolCalls?: AgentWireToolCall[];
-  stop: "end" | "toolUse";
+  /**
+   * Why the turn ended. `"length"` is the provider's ceiling — `finish_reason: "length"`, `stop_reason:
+   * "max_tokens"` — and it is distinguished from `"end"` because the two are indistinguishable downstream
+   * otherwise: a truncated answer reads as a complete one, and a turn cut off mid tool call carries no complete
+   * call at all, so it would end the loop looking exactly like a model that chose to stop.
+   */
+  stop: "end" | "toolUse" | "length";
 }
 
 /**

package/service/predefinedAdaptor/openaiDialect.ts

@@ -34,6 +34,14 @@ export interface OpenaiMessage {
  * read to a note in the text.
  */
 export class OpenaiDialect {
+  /**
+   * The types this dialect's image part reads. Exact rather than an `image/*` prefix and declared apart from
+   * Anthropic's identical-looking set, because the two are each a provider's own list and only happen to agree:
+   * an unsupported one passed through is a refused *request*, not an unread attachment, so the safe direction is
+   * to name what is known to work and note the rest.
+   */
+  static readonly imageTypes = new Set(["image/jpeg", "image/png", "image/gif", "image/webp"]);
+
   static requestBody(
     model: string,
     request: LlmTurnRequest,
@@ -114,20 +122,33 @@ 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 ?? [];
+    const notes: string[] = [];
     const blocks = attachments.flatMap((attachment) =>
       attachment.text ? [`--- attachment: ${attachment.name} (${attachment.mimeType}) ---\n${attachment.text}`] : [],
     );
-    const text = [message.text, ...blocks].filter(Boolean).join("\n\n");
-    if (!accepts?.image) return text;
-    const images = attachments.flatMap((attachment) => {
-      if (!attachment.mimeType.startsWith("image/")) return [];
-      const url = attachment.url ?? (attachment.data ? `data:${attachment.mimeType};base64,${attachment.data}` : "");
-      return url ? [{ type: "image_url" as const, image_url: { url } }] : [];
-    });
+    const images = !accepts?.image
+      ? []
+      : attachments.flatMap((attachment) => {
+          if (attachment.text) return [];
+          
+          const mimeType = attachment.mimeType.split(";")[0].trim().toLowerCase();
+
+          if (!mimeType.startsWith("image/")) return [];
+          if (!OpenaiDialect.imageTypes.has(mimeType)) {
+            notes.push(
+              `[Attachment not read: ${attachment.name} (${attachment.mimeType}) — this API reads no image of that type.]`,
+            );
+            return [];
+          }
+
+          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");
     if (!images.length) return text;
     return [...(text ? [{ type: "text" as const, text }] : []), ...images];
   }
@@ -193,10 +214,19 @@ export class OpenaiDialect {
     return {
       ...(text ? { text } : {}),
       ...(toolCalls.length ? { toolCalls } : {}),
-      stop: finish === "tool_calls" || toolCalls.length ? "toolUse" : "end",
+      stop: OpenaiDialect.stopOf(finish, toolCalls.length),
     };
   }
 
+  /**
+   * The ceiling wins over the calls that did arrive. A turn the provider cut short is one whose last call may be
+   * missing, so running the batch it did finish is acting on half an intention.
+   */
+  static stopOf(finish: string | null | undefined, calls: number): LlmTurnAnswer["stop"] {
+    if (finish === "length") return "length";
+    return finish === "tool_calls" || calls ? "toolUse" : "end";
+  }
+
   static turnAnswer(answer: OpenaiAnswer): LlmTurnAnswer {
     const choice = answer.choices?.[0];
     const toolCalls = (choice?.message?.tool_calls ?? []).flatMap((call) => {
@@ -206,7 +236,7 @@ export class OpenaiDialect {
     return {
       ...(choice?.message?.content ? { text: choice.message.content } : {}),
       ...(toolCalls.length ? { toolCalls } : {}),
-      stop: choice?.finish_reason === "tool_calls" || toolCalls.length ? "toolUse" : "end",
+      stop: OpenaiDialect.stopOf(choice?.finish_reason, toolCalls.length),
     };
   }
 

package/signal/agentTurnStream.ts

@@ -3,7 +3,7 @@ import type { AgentWireToolCall } from "akanjs/service";
 interface StreamedTurn {
   text?: string;
   toolCalls?: AgentWireToolCall[];
-  stop?: "end" | "toolUse";
+  stop?: "end" | "toolUse" | "length";
 }
 
 /**
@@ -44,7 +44,10 @@ export class AgentTurnStream {
           if (!streamed && turn.text) send({ type: "text", delta: turn.text });
           const toolCalls = turn.toolCalls ?? [];
           for (const call of toolCalls) send({ type: "toolCall", id: call.id, name: call.name, args: call.args });
-          send({ type: "done", stop: turn.stop === "toolUse" || toolCalls.length ? "toolUse" : "end" });
+          
+          const stop =
+            turn.stop === "length" ? "length" : turn.stop === "toolUse" || toolCalls.length ? "toolUse" : "end";
+          send({ type: "done", stop });
         } catch (error) {
           
           send({ type: "error", ...AgentTurnStream.failure(error) });