akanjs 3.0.0-beta.1 → 3.0.0-beta.3

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/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/package.json

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

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,6 +292,11 @@ 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;
+  }
+
   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 };
@@ -294,10 +315,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 +386,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

@@ -68,7 +68,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,
@@ -118,16 +126,28 @@ export class OpenaiDialect {
    */
   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.url ?? (attachment.data ? `data:${mimeType};base64,${attachment.data}` : "");
+          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 +213,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 +235,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) });

package/types/fetch/agentTurn.d.ts

@@ -1,5 +1,5 @@
 import { Any } from "akanjs/base";
-declare const AgentStop_base: import("akanjs/base").EnumInstance<"agentStop", "end" | "toolUse">;
+declare const AgentStop_base: import("akanjs/base").EnumInstance<"agentStop", "length" | "end" | "toolUse">;
 export declare class AgentStop extends AgentStop_base {
 }
 declare const AgentTurn_base: import("akanjs/constant").ConstantCls<import("akanjs/constant").ExtractFieldInfoObject<{
@@ -466,10 +466,10 @@ export declare class AgentTurn extends AgentTurn_base {
 export declare const agentTurnConstant: import("akanjs/constant").ScalarConstantModel<"agentTurn", AgentTurn, import("akanjs/constant").DefaultOf<AgentTurn>, {
     text: string;
     toolCalls: unknown[];
-    stop: NonNullable<"end" | "toolUse">;
+    stop: NonNullable<"length" | "end" | "toolUse">;
 } & {}, {
     text: string;
     toolCalls: unknown[];
-    stop: "end" | "toolUse";
+    stop: "length" | "end" | "toolUse";
 } & {}>;
 export {};

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

@@ -6,7 +6,7 @@ export declare class AgentService extends AgentService_base {
     runTurn(request: LlmTurnRequest, onDelta?: (delta: string) => void): Promise<{
         text: string;
         toolCalls: import("./predefinedAdaptor.d.ts").AgentWireToolCall[];
-        stop: "end" | "toolUse";
+        stop: "length" | "end" | "toolUse";
     }>;
     /**
      * The framework's half of the system prompt, ahead of whatever the app said so the app's text stays the more

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

@@ -64,6 +64,17 @@ export declare class AnthropicLlm extends AnthropicLlm_base implements LlmAdapto
      * model refusing, so it is `option.setLlm({ maxTokens })` and not a constant.
      */
     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: Set<string>;
     /** What the API's blocks carry. A model of the family that reads neither takes the `accepts` override. */
     get accepts(): LlmAccepts;
     chat(request: LlmTurnRequest, onDelta?: (delta: string) => void): Promise<LlmTurnAnswer | null>;
@@ -96,8 +107,12 @@ export declare class AnthropicLlm extends AnthropicLlm_base implements LlmAdapto
     static providerMessages(messages: AgentWireMessage[], accepts?: LlmAccepts): AnthropicMessage[];
     static providerMessage(message: AgentWireMessage, accepts?: LlmAccepts): AnthropicMessage;
     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;
     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. */
+    static stopOf(reason: string | null | undefined, calls: number): LlmTurnAnswer["stop"];
     /**
      * 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

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

@@ -61,7 +61,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";
 }
 /**
  * The provider seam for one stateless agent turn: the whole transcript in, one assistant answer out. The server

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

@@ -47,6 +47,13 @@ export interface OpenaiMessage {
  * read to a note in the text.
  */
 export declare 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: Set<string>;
     static requestBody(model: string, request: LlmTurnRequest, { accepts, stream }?: {
         accepts?: LlmAccepts;
         stream?: boolean;
@@ -79,6 +86,11 @@ export declare class OpenaiDialect {
      * by index and parsed once at the end; only assistant text is worth reporting as it arrives.
      */
     static consumeStream(body: ReadableStream<Uint8Array>, onDelta: (delta: string) => void): Promise<LlmTurnAnswer>;
+    /**
+     * 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"];
     static turnAnswer(answer: OpenaiAnswer): 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/signal/agent.signal.d.ts

@@ -12,7 +12,7 @@ declare const AgentEndpoint_base: import("./endpoint.d.ts").EndpointCls<import("
     }, ["messages", "tools", "context", "instructions"], [arg: unknown[], arg: unknown[], arg: unknown[], arg?: string | null | undefined], [arg: Bun.BunRequest<string>], [arg: unknown[], arg: unknown[], arg: unknown[], arg: string | undefined], typeof AgentTurn, AgentTurn, Promise<AgentTurn | {
         text: string;
         toolCalls: import("akanjs/service").AgentWireToolCall[];
-        stop: "end" | "toolUse";
+        stop: "length" | "end" | "toolUse";
     }>, false>;
 }>;
 export declare class AgentEndpoint extends AgentEndpoint_base {

package/types/signal/agentTurn.d.ts

@@ -2,7 +2,7 @@ export { AgentStop, AgentTurn, agentTurnConstant } from "akanjs/fetch";
 declare const AgentTurnDocument_base: import("akanjs/document").DatabaseCls<{
     text: string;
     toolCalls: unknown[];
-    stop: NonNullable<"end" | "toolUse">;
+    stop: NonNullable<"length" | "end" | "toolUse">;
 } & {}>;
 export declare class AgentTurnDocument extends AgentTurnDocument_base {
 }

package/types/signal/agentTurnStream.d.ts

@@ -2,7 +2,7 @@ import type { AgentWireToolCall } from "akanjs/service";
 interface StreamedTurn {
     text?: string;
     toolCalls?: AgentWireToolCall[];
-    stop?: "end" | "toolUse";
+    stop?: "end" | "toolUse" | "length";
 }
 /**
  * The streaming half of the agent turn wire (use-agentic WIRE.md): the same endpoint answers `text/event-stream`

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

@@ -70,6 +70,11 @@ export interface ChatProps {
      * (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.
+     *
+     * **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.
      */
     attach?: AttachReader;
     /**

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

@@ -114,6 +114,12 @@ export interface ToolCallResult {
  * model cannot read and says so in the transcript, because a silently dropped file is one the model then
  * hallucinates about.
  */
+/**
+ * Why an assistant turn ended. `length` is the provider's own ceiling rather than the model's choice, so the turn
+ * is incomplete — a truncated answer and a turn cut off before its tool call finished both arrive this way, and
+ * neither is distinguishable from `end` without it.
+ */
+export type TurnStop = "end" | "toolUse" | "length";
 export interface MessageAttachment {
     name: string;
     mimeType: string;
@@ -165,7 +171,7 @@ export type RunnerEvent = {
     args: Record<string, unknown>;
 } | {
     type: "done";
-    stop: "end" | "toolUse";
+    stop: TurnStop;
 }
 /**
  * `data` accompanies a message that is a code rather than a sentence — the values whoever resolves the code

package/ui/Agent/Chat.tsx

@@ -109,6 +109,11 @@ export interface ChatProps {
    * (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.
+   *
+   * **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.
    */
   attach?: AttachReader;
   /**

package/vendor/use-agentic/AgentSession.ts

@@ -12,6 +12,7 @@ import type {
   SurfaceView,
   ToolCallRequest,
   ToolCallResult,
+  TurnStop,
 } from "./types";
 
 export interface PendingApproval {
@@ -264,6 +265,15 @@ export class AgentSession {
           this.#unanswered(toolCalls);
           return;
         }
+
+        if (stop === "length") {
+
+          this.#fail(
+            "The model ran out of room mid-answer, so this turn is incomplete. Ask again, or raise the answer limit.",
+          );
+          if (toolCalls.length) this.#unanswered(toolCalls);
+          return;
+        }
         if (stop !== "toolUse" || !toolCalls.length) return;
         const toolResults: ToolCallResult[] = [];
         for (const call of toolCalls)
@@ -478,7 +488,7 @@ export class AgentSession {
     return text;
   }
 
-  async #assistantTurn(signal: AbortSignal): Promise<{ toolCalls: ToolCallRequest[]; stop: "end" | "toolUse" }> {
+  async #assistantTurn(signal: AbortSignal): Promise<{ toolCalls: ToolCallRequest[]; stop: TurnStop }> {
     const { tools, guides } = this.#surface.snapshot();
     const instructions = [this.#options.instructions, ...guides].filter(Boolean).join("\n\n");
     const request: RunnerRequest = {
@@ -493,7 +503,7 @@ export class AgentSession {
     this.#append({ role: "assistant" });
     let text = "";
     const toolCalls: ToolCallRequest[] = [];
-    let stop: "end" | "toolUse" = "end";
+    let stop: TurnStop = "end";
     for await (const event of this.#runner.run(request)) {
       if (signal.aborted) break;
       if (event.type === "text") {

package/vendor/use-agentic/httpRunner.ts

@@ -10,7 +10,7 @@ export interface HttpRunnerOptions {
 interface TurnAnswer {
   text?: string;
   toolCalls?: ToolCallRequest[];
-  stop?: "end" | "toolUse";
+  stop?: "end" | "toolUse" | "length";
 }
 
 const eventTypes = new Set(["text", "toolCall", "done", "error"]);

package/vendor/use-agentic/types.ts

@@ -131,6 +131,13 @@ export interface ToolCallResult {
  * model cannot read and says so in the transcript, because a silently dropped file is one the model then
  * hallucinates about.
  */
+/**
+ * Why an assistant turn ended. `length` is the provider's own ceiling rather than the model's choice, so the turn
+ * is incomplete — a truncated answer and a turn cut off before its tool call finished both arrive this way, and
+ * neither is distinguishable from `end` without it.
+ */
+export type TurnStop = "end" | "toolUse" | "length";
+
 export interface MessageAttachment {
   name: string;
   mimeType: string;
@@ -178,7 +185,7 @@ export interface ContextBlock {
 export type RunnerEvent =
   | { type: "text"; delta: string }
   | { type: "toolCall"; id: string; name: string; args: Record<string, unknown> }
-  | { type: "done"; stop: "end" | "toolUse" }
+  | { type: "done"; stop: TurnStop }
   /**
    * `data` accompanies a message that is a code rather than a sentence — the values whoever resolves the code
    * interpolates into its text. A host that does not know the code shows the message as it stands.