@jxsuite/ai 0.42.0 → 0.43.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/ai",
-  "version": "0.42.0",
+  "version": "0.43.0",
   "description": "AI infrastructure for Jx Suite — streaming LLM client abstraction, tool registry, and reactive chat state",
   "license": "MIT",
   "repository": {
@@ -33,8 +33,8 @@
     "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
-    "@jxsuite/protocol": "^6.2.0",
-    "@jxsuite/schema": "^5.0.0",
+    "@jxsuite/protocol": "^6.2.2",
+    "@jxsuite/schema": "^5.2.0",
     "@vue/reactivity": "3.5.44"
   },
   "devDependencies": {

package/src/harness/policy.ts

@@ -12,18 +12,30 @@ import type { TurnPolicy } from "./types.ts";
 export const CHARS_PER_TOKEN = 4;
 
 /**
- * The defaults: five rounds of work, twenty-five rounds in all, and the texts the agent loop has
- * always used (specs/ai.md §3.2, §3.4).
+ * The defaults: thirty rounds of work, sixty rounds in all, three identical rounds, and the texts a
+ * turn ends on (specs/ai.md §3.2, §3.4, §3.8).
  *
- * Five bounds AUTONOMOUS work. A round that ends by blocking on a person is the opposite of runaway
- * (it cannot advance without them), so a round whose calls were all interactive does not spend that
- * budget. Twenty-five is the backstop that keeps a turn provably finite anyway.
+ * Thirty bounds AUTONOMOUS work. It was five, which a turn spent finding its way around a project
+ * before it had changed or answered anything. A round that ends by blocking on a person is the
+ * opposite of runaway (it cannot advance without them), so a round whose calls were all interactive
+ * does not spend that budget. Sixty is the backstop that keeps a turn provably finite anyway, and a
+ * model going round in circles is stopped long before either, by its repeating itself.
  */
 export const DEFAULT_TURN_POLICY: TurnPolicy = {
-  maxWorkRounds: 5,
-  maxRounds: 25,
+  maxWorkRounds: 30,
+  maxRounds: 60,
+  maxIdenticalRounds: 3,
+  parallelReadOnly: false,
   estimateTokens: (text) => Math.ceil(text.length / CHARS_PER_TOKEN),
-  capText: ({ maxWorkRounds, applied, errors }) => {
+  closingText: (reason) =>
+    `${
+      reason === "repeating"
+        ? "Your last tool calls keep returning the same results, so they will not help."
+        : "This turn has used its whole tool budget."
+    } No further tool call will run. This note is from the system, not the author. Reply to the ` +
+    `author now in plain text: answer as much as you can from what you already found, say what ` +
+    `you changed, and say what is left. They can ask you to continue in their next message.`,
+  capText: ({ maxWorkRounds, reason, applied, errors }) => {
     const unique = [...new Set(errors)];
     const appliedPart =
       applied.length > 0
@@ -31,8 +43,12 @@ export const DEFAULT_TURN_POLICY: TurnPolicy = {
         : "";
     const errorPart =
       unique.length > 0 ? `\n\nErrors encountered:\n${unique.map((e) => `- ${e}`).join("\n")}` : "";
+    const why =
+      reason === "repeating"
+        ? "I stopped because my tool calls kept returning the same results."
+        : `I ran out of tool-call rounds (${maxWorkRounds}) before finishing.`;
     return (
-      `I ran out of tool-call rounds (${maxWorkRounds}) before finishing.${appliedPart}${errorPart}` +
+      `${why}${appliedPart}${errorPart}` +
       `\n\nYou can continue by sending another message, or try a more specific request.`
     );
   },

package/src/harness/run.ts

@@ -9,10 +9,11 @@
  * - **The calls decide whether tools run, not the finish reason** (§2). A round whose stream carried
  *   tool calls executes them whatever finish the provider reported. Cancellation is the exception:
  *   a round that ends `cancelled`, or whose signal is aborted, runs nothing it streamed.
- * - **A partial success is not a failure** (§3.2). Running out of work rounds after applying
- *   something ends on an ordinary message saying what was applied; only a turn that applied nothing
- *   ends as a failure. Applied means it wrote: a call counts when it succeeded with a summary and
- *   recorded at least one `ok` write.
+ * - **A turn that stops working still answers** (§3.2, §3.8). Running out of work rounds, or making
+ *   the same calls with the same results, opens one closing round whose calls do not run, so the
+ *   model says what it found and did. Without a reply, a turn that applied something ends on the
+ *   harness's message saying what; only one that applied nothing ends as a failure. Applied means
+ *   it wrote: a call counts when it succeeded with a summary and recorded at least one `ok` write.
  * - **A turn that drew nothing says so** (§3.2), as an `empty` outcome, rather than ending silent.
  * - **Stop is checked between calls and after the round** (§2), so a Stop that lands mid-call stops
  *   the calls after it, and one that lands during the last call opens no further round.
@@ -43,6 +44,7 @@ import { joinSystem } from "./model.ts";
 import { DEFAULT_TURN_POLICY } from "./policy.ts";
 import type {
   HarnessEvent,
+  CapReason,
   TurnError,
   TurnInput,
   TurnOutcome,
@@ -260,6 +262,10 @@ export function runTurn(input: TurnInput): TurnRun {
     let workRounds = 0;
     let lastUsage: Usage | null = null;
     let totalUsage: Usage | null = null;
+    /* How many rounds made exactly these calls and got exactly these results. Nothing the model
+       could learn from a further one differs, so the count is what "stuck" means here. */
+    const roundsSeen = new Map<string, number>();
+    let repeating = false;
 
     const finish = (
       kind: TurnOutcomeKind,
@@ -282,18 +288,85 @@ export function runTurn(input: TurnInput): TurnRun {
       return outcome;
     };
 
+    /* How a turn that stopped working ends when the model gave no closing reply. A turn that applied
+       something still says what (§3.2); one that applied nothing has nothing to report but that. */
+    const capped = (reason: CapReason): TurnOutcome => {
+      const text = policy.capText({
+        maxWorkRounds: policy.maxWorkRounds,
+        reason,
+        applied,
+        errors,
+      });
+      if (applied.length === 0) {
+        return finish("cap_failed", { error: { message: text } });
+      }
+      const capId = newId();
+      appended.push({
+        id: capId,
+        role: "assistant",
+        blocks: [{ type: "text", text }],
+        timestamp: now(),
+        meta: { origin: "harness", kind: "round_cap" },
+      });
+      anchor = capId;
+      return finish("cap_partial", { cap: { messageId: capId, text } });
+    };
+
+    /** How many calls from the front of `calls` run together: at least the first. */
+    const parallelRunLength = (calls: readonly (readonly [string, { name: string }])[]): number => {
+      if (!policy.parallelReadOnly) {
+        return 1;
+      }
+      const end = calls.findIndex(([, call]) => {
+        const definition = input.tools.getDefinition(call.name);
+        return (
+          definition?.annotations?.readOnlyHint !== true ||
+          definition.interactive === true ||
+          definition.interaction !== undefined
+        );
+      });
+      if (end === -1) {
+        return calls.length;
+      }
+      return Math.max(end, 1);
+    };
+
     emit({ type: "turn_start" });
     const { sealed, dropped, moved } = repair;
     if (sealed.length + dropped.length + moved.length > 0) {
       emit({ type: "transcript_repaired", sealed, dropped, moved });
     }
-    for (let round = 1; round <= policy.maxRounds && workRounds < policy.maxWorkRounds; round++) {
+    /* The turn ends from inside this loop: on a round with no calls, or on the closing round, which
+       the bounds below reach whatever the model does. */
+    for (let round = 1; ; round++) {
       rounds = round;
+      let closing: CapReason | null = null;
+      if (repeating) {
+        closing = "repeating";
+      } else if (round > policy.maxRounds || workRounds >= policy.maxWorkRounds) {
+        closing = "budget";
+      }
       const messageId =
         round === 1 && input.firstMessageId !== undefined ? input.firstMessageId : newId();
-      emit({ type: "round_start", round, workRounds, messageId });
+      emit(
+        closing
+          ? { type: "round_start", round, workRounds, messageId, closing }
+          : { type: "round_start", round, workRounds, messageId },
+      );
 
+      /* A closing round still lists the tools. Taking them away would refuse the request on a
+         provider that wants a listing beside any call in the history, and would throw away the
+         prompt cache for its last request; a call the model makes anyway is simply not run. */
       const tools = fromOpenAITools(input.tools.listForLLM());
+      const note: ChatMessage | null = closing
+        ? {
+            id: newId(),
+            role: "user",
+            blocks: [{ type: "text", text: policy.closingText(closing) }],
+            timestamp: now(),
+            meta: { origin: "harness", kind: "round_cap" },
+          }
+        : null;
       let text = "";
       let reasoning: string | undefined;
       /* The message records each call as it starts, the way a transcript shows it; execution keys
@@ -306,9 +379,26 @@ export function runTurn(input: TurnInput): TurnRun {
       let errorCode: string | undefined;
 
       for await (const frame of input.model(
-        { system: input.system, messages: [...history, ...appended], tools },
+        note
+          ? {
+              system: input.system,
+              messages: [...history, ...appended, note],
+              tools,
+              closing: note,
+            }
+          : { system: input.system, messages: [...history, ...appended], tools },
         signal,
       )) {
+        /* A closing round's calls will not run, so they are not drawn either: a call on screen, or
+           in the transcript, with no reply is a question this turn has already decided to leave. */
+        if (
+          closing &&
+          (frame.type === "tool_call_start" ||
+            frame.type === "tool_call_delta" ||
+            frame.type === "tool_call_end")
+        ) {
+          continue;
+        }
         switch (frame.type) {
           case "delta": {
             text += frame.content;
@@ -377,13 +467,20 @@ export function runTurn(input: TurnInput): TurnRun {
           : { message: errorMessage };
         input.hooks?.onStreamError?.(error);
         emit({ type: "round_end", messageId, stopReason, truncated, dropped: true, error });
-        return finish("error", { error, removedMessageId: messageId });
+        // The closing round was a courtesy: losing it is not what the turn failed of.
+        return closing && !aborted()
+          ? capped(closing)
+          : finish("error", { error, removedMessageId: messageId });
       }
 
       /* A turn that has drawn nothing by the end of a round with no calls ends here. A stopped
          round is not empty: the author ended it. */
       const stopped = stopReason === "cancelled" || aborted();
       const drawn = text !== "" || records.length > 0;
+      if (closing && !stopped && text.trim() === "") {
+        emit({ type: "round_end", messageId, stopReason, truncated, dropped: true });
+        return capped(closing);
+      }
       if (calls.size === 0 && !stopped && !drawnBefore && anchor === null && !drawn) {
         emit({ type: "round_end", messageId, stopReason, truncated, dropped: true });
         return finish("empty", {
@@ -415,100 +512,111 @@ export function runTurn(input: TurnInput): TurnRun {
         );
         anchor = messageId;
       }
-      if (calls.size === 0 || stopped) {
-        return finish(stopped ? "cancelled" : "complete");
+      if (stopped) {
+        return finish("cancelled");
+      }
+      if (closing) {
+        return finish("cap_partial");
+      }
+      if (calls.size === 0) {
+        return finish("complete");
       }
 
+      /* The calls run in stream order. With `parallelReadOnly`, a run of neighbouring read-only
+         calls runs at once, because none of them can change what another reads; their results are
+         still reported in order, so the transcript and the wire see what a serial turn would. A
+         question or a write is never in such a run, so it still sees everything before it. */
       let didWork = false;
-      for (const [callId, call] of calls) {
+      const seen: string[] = [];
+      const pending = [...calls];
+      while (pending.length > 0) {
         if (aborted()) {
           return finish("cancelled");
         }
-        emit({
-          type: "tool_start",
-          callId,
-          name: call.name,
-          interactive: input.tools.getDefinition(call.name)?.interactive === true,
-        });
-        const before = ledger.writes.length;
-        /* The call's own signal: it aborts with the turn, and is unlinked once the call settles, so
-           a Stop later in the turn reaches nothing that already finished. */
-        const link = linkCallSignal(signal);
-        const ctx = createToolContext({
-          actor,
-          callId,
-          ledger,
-          progress: (progress) => {
-            emit({ type: "tool_progress", callId, progress });
-          },
-          session,
-          signal: link.signal,
-        });
-        let result;
-        try {
-          result = await invoke(
-            { callId, name: call.name, argumentsText: call.argumentsText },
-            ctx,
-            link.signal,
-          );
-        } finally {
-          link.release();
-        }
-        input.hooks?.afterTool?.({ callId, name: call.name, result });
-        // A call that suspends the turn on a person does not spend its work budget.
-        if (input.tools.getDefinition(call.name)?.interactive !== true) {
-          didWork = true;
-        }
-        if (!result.success && result.error) {
-          errors.push(result.error);
-        }
-        const recorded = ledger.writes.slice(before);
-        if (result.success && result.summary && recorded.some((write) => write.ok)) {
-          applied.push(result.summary);
-        }
-        for (const write of recorded) {
-          emit({ type: "write", callId, write });
-        }
-        const toolMessageId = newId();
-        appended.push({
-          id: toolMessageId,
-          role: "tool",
-          blocks: [
-            {
-              type: "tool_result",
+        const batch = pending.splice(0, parallelRunLength(pending));
+        let writesSeen = ledger.writes.length;
+        const results = await Promise.all(
+          batch.map(async ([callId, call]) => {
+            emit({
+              type: "tool_start",
               callId,
-              isError: result.success === false,
-              content: JSON.stringify(result),
-            },
-          ],
-          timestamp: now(),
-        });
-        emit({ type: "tool_result", callId, messageId, toolMessageId, result });
+              name: call.name,
+              interactive: input.tools.getDefinition(call.name)?.interactive === true,
+            });
+            /* The call's own signal: it aborts with the turn, and is unlinked once the call
+               settles, so a Stop later in the turn reaches nothing that already finished. */
+            const link = linkCallSignal(signal);
+            const ctx = createToolContext({
+              actor,
+              callId,
+              ledger,
+              progress: (progress) => {
+                emit({ type: "tool_progress", callId, progress });
+              },
+              session,
+              signal: link.signal,
+            });
+            try {
+              return await invoke(
+                { callId, name: call.name, argumentsText: call.argumentsText },
+                ctx,
+                link.signal,
+              );
+            } finally {
+              link.release();
+            }
+          }),
+        );
+        for (const [index, [callId, call]] of batch.entries()) {
+          const result = results[index]!;
+          input.hooks?.afterTool?.({ callId, name: call.name, result });
+          // A call that suspends the turn on a person does not spend its work budget.
+          if (input.tools.getDefinition(call.name)?.interactive !== true) {
+            didWork = true;
+          }
+          if (!result.success && result.error) {
+            errors.push(result.error);
+          }
+          const recorded = ledger.writes.slice(writesSeen);
+          writesSeen = ledger.writes.length;
+          if (result.success && result.summary && recorded.some((write) => write.ok)) {
+            applied.push(result.summary);
+          }
+          for (const write of recorded) {
+            emit({ type: "write", callId, write });
+          }
+          const content = JSON.stringify(result);
+          seen.push(call.name, call.argumentsText, content);
+          const toolMessageId = newId();
+          appended.push({
+            id: toolMessageId,
+            role: "tool",
+            blocks: [
+              {
+                type: "tool_result",
+                callId,
+                isError: result.success === false,
+                content,
+              },
+            ],
+            timestamp: now(),
+          });
+          emit({ type: "tool_result", callId, messageId, toolMessageId, result });
+        }
       }
 
       if (didWork) {
         workRounds += 1;
+        const fingerprint = JSON.stringify(seen);
+        const count = (roundsSeen.get(fingerprint) ?? 0) + 1;
+        roundsSeen.set(fingerprint, count);
+        repeating = count >= policy.maxIdenticalRounds;
       }
       // A Stop that landed during the round's last call opens no further round.
       if (aborted()) {
         return finish("cancelled");
       }
     }
-
-    const capText = policy.capText({ maxWorkRounds: policy.maxWorkRounds, applied, errors });
-    if (applied.length > 0) {
-      const capId = newId();
-      appended.push({
-        id: capId,
-        role: "assistant",
-        blocks: [{ type: "text", text: capText }],
-        timestamp: now(),
-        meta: { origin: "harness", kind: "round_cap" },
-      });
-      anchor = capId;
-      return finish("cap_partial", { cap: { messageId: capId, text: capText } });
-    }
-    return finish("cap_failed", { error: { message: capText } });
   }
 
   const outcome = loop().finally(settle);

package/src/harness/types.ts

@@ -33,6 +33,11 @@ export interface ModelRequest {
   /** The conversation so far, this turn's own messages included. */
   readonly messages: readonly ChatMessage[];
   readonly tools: readonly ToolSpec[];
+  /**
+   * The note a closing round ends on (specs/ai.md §3.8), already the last of `messages`. It is on
+   * no transcript, so a host that projects its request from its own transcript sends it from here.
+   */
+  readonly closing?: ChatMessage;
 }
 
 /** Streams one round's answer. Called exactly once per round. */
@@ -51,9 +56,10 @@ export interface TurnError {
  * How a turn ended.
  *
  * - `complete`: the model stopped calling tools after drawing something.
- * - `cap_partial`: the work budget ran out after something was applied; the turn ends on a message
- *   saying what.
- * - `cap_failed`: the work budget ran out with nothing applied.
+ * - `cap_partial`: the turn stopped working (its work budget ran out, or it was repeating itself) and
+ *   ended on a message: the model's closing reply, or the harness's when something was applied and
+ *   the model gave none.
+ * - `cap_failed`: the turn stopped working, nothing was applied, and the model gave no closing reply.
  * - `error`: the provider sent an error frame.
  * - `cancelled`: the turn was stopped.
  * - `empty`: the model answered with neither text nor a tool call, and nothing earlier in the turn
@@ -67,17 +73,27 @@ export type TurnOutcomeKind =
   | "cancelled"
   | "empty";
 
+/** Why a turn stopped working: its work budget ran out, or it was repeating itself. */
+export type CapReason = "budget" | "repeating";
+
 /** The numbers and words a turn is bounded and reported by. */
 export interface TurnPolicy {
   /** Rounds that did work: a round whose calls were all interactive does not count. */
   readonly maxWorkRounds: number;
   /** Rounds of every kind, so a turn ends whatever the model does. */
   readonly maxRounds: number;
+  /** How many rounds of the same calls with the same results it takes to call a turn stuck. */
+  readonly maxIdenticalRounds: number;
+  /** What a turn's closing round tells the model. */
+  readonly closingText: (reason: CapReason) => string;
+  /** Whether neighbouring read-only calls in a round run at once. Their results stay in order. */
+  readonly parallelReadOnly: boolean;
   /** A token estimate for a text, reported beside each usage count for the system prompt. */
   readonly estimateTokens: (text: string) => number;
-  /** What a turn that ran out of work rounds says. */
+  /** What a turn says when it stopped working and the model gave no closing reply. */
   readonly capText: (cap: {
     readonly maxWorkRounds: number;
+    readonly reason: CapReason;
     readonly applied: readonly string[];
     readonly errors: readonly string[];
   }) => string;
@@ -209,6 +225,8 @@ export type HarnessEvent = EventBase &
         readonly round: number;
         readonly workRounds: number;
         readonly messageId: string;
+        /** Set on a closing round (specs/ai.md §3.8): the last, whose calls will not run. */
+        readonly closing?: CapReason;
       }
     | { readonly type: "text"; readonly messageId: string; readonly text: string }
     | { readonly type: "reasoning"; readonly messageId: string; readonly text: string }
@@ -287,7 +305,7 @@ export interface TurnOutcome {
   readonly usage: { readonly last: Usage | null; readonly total: Usage | null };
   /** Every message the turn added, in its final form. */
   readonly appended: readonly ChatMessage[];
-  /** For `cap_partial`: the message the turn ended on. */
+  /** For a `cap_partial` the harness ended, the model having given no closing reply: its message. */
   readonly cap?: { readonly messageId: string; readonly text: string };
   /** For `error` and `empty`: the round message that was dropped. */
   readonly removedMessageId?: string;