akanjs 3.0.0-beta.1 → 3.0.0-beta.2

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.2",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/service/predefinedAdaptor/anthropicLlm.ts

@@ -101,7 +101,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}.`,
       );
@@ -294,10 +294,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 +365,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

@@ -193,10 +193,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 +215,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

@@ -98,6 +98,8 @@ export declare class AnthropicLlm extends AnthropicLlm_base implements LlmAdapto
     static userContent(message: AgentWireMessage, accepts?: LlmAccepts): AnthropicBlock[];
     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

@@ -79,6 +79,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/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/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.