@jxsuite/ai 0.39.0 → 0.39.2

package/src/messages/repair.ts

@@ -0,0 +1,211 @@
+/**
+ * Repair.ts — every tool call followed by its reply, as a provider requires.
+ *
+ * A provider accepts a request that repeats a tool call only when the call's reply comes directly
+ * after the message that made it. Several ordinary things break that: a saved session restored from
+ * the middle of a pair, history trimmed for the token budget, a turn stopped between two calls, and
+ * transcripts written before one window ran one turn, where a reply could land after a later
+ * message. `repairToolPairs` puts every pair back together (specs/ai.md §3.4).
+ *
+ * @module @jxsuite/ai/messages
+ * @license MIT
+ */
+
+import type { ChatMessage, ToolCallBlock, ToolResultBlock } from "./types.ts";
+
+/** What a seal says for a call that was cut off: its arguments never finished streaming. */
+export const SEAL_CUT_OFF =
+  "This tool call was never completed — the response was cut off before it finished.";
+
+/** What a seal says for any other call with no reply. */
+export const SEAL_RELOADED =
+  "This tool call was never completed — the session was reloaded or the history was trimmed.";
+
+/** A seal's content: the failed result a Jx tool would have serialized, keys in this order. */
+function sealContent(sentence: string): string {
+  return JSON.stringify({ success: false, error: sentence });
+}
+
+const CUT_OFF_CONTENT = sealContent(SEAL_CUT_OFF);
+const RELOADED_CONTENT = sealContent(SEAL_RELOADED);
+
+/** What {@link repairToolPairs} did, and the transcript it did it to. */
+export interface RepairReport {
+  /** The repaired transcript. Every message the repair did not create is the input's own object. */
+  readonly messages: ChatMessage[];
+  /** The id of each call given a seal, in transcript order. */
+  readonly sealed: string[];
+  /** The id of each `tool` message removed, in transcript order. */
+  readonly dropped: string[];
+  /** The id of each `tool` message put back after the request it answers, in transcript order. */
+  readonly moved: string[];
+}
+
+/**
+ * Whether a `tool` message's content is a seal rather than a reply: exactly one of the two contents
+ * {@link repairToolPairs} writes.
+ *
+ * @param {string} content
+ * @returns {boolean}
+ */
+export function isSealContent(content: string): boolean {
+  return content === CUT_OFF_CONTENT || content === RELOADED_CONTENT;
+}
+
+/**
+ * Whether a call's arguments were cut off mid-stream: there are some, and they do not parse. An
+ * empty string is a call with no arguments, not one that was cut off.
+ */
+function isCutOff(call: ToolCallBlock): boolean {
+  if (call.argumentsText === "") {
+    return false;
+  }
+  try {
+    JSON.parse(call.argumentsText);
+    return false;
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * A message's calls, one per id, in the order they were made. A call with no id cannot be answered,
+ * so nothing seals it either; a call id made twice in one message is answered by one reply.
+ */
+function callsOf(message: ChatMessage): ToolCallBlock[] {
+  const calls = new Map<string, ToolCallBlock>();
+  for (const block of message.blocks) {
+    if (block.type === "tool_call" && block.id !== "" && !calls.has(block.id)) {
+      calls.set(block.id, block);
+    }
+  }
+  return [...calls.values()];
+}
+
+/** The call id a `tool` message answers: its first result's, or the empty id when it has none. */
+function answers(message: ChatMessage): string {
+  const result = message.blocks.find(
+    (block): block is ToolResultBlock => block.type === "tool_result",
+  );
+  return result?.callId ?? "";
+}
+
+/**
+ * The seal for a call nothing answered: the `n`th of its message's unanswered calls, stamped with
+ * that message's time, under an id no message in `used` has (which it then joins).
+ */
+function seal(call: ToolCallBlock, n: number, timestamp: number, used: Set<string>): ChatMessage {
+  const base = `sealed_${call.id}_${n}`;
+  let id = base;
+  for (let k = 1; used.has(id); k++) {
+    id = `${base}_${k}`;
+  }
+  used.add(id);
+  return {
+    id,
+    role: "tool",
+    blocks: [
+      {
+        type: "tool_result",
+        callId: call.id,
+        isError: true,
+        content: isCutOff(call) ? CUT_OFF_CONTENT : RELOADED_CONTENT,
+      },
+    ],
+    timestamp,
+  };
+}
+
+/**
+ * Put every tool call and its reply back together, so a provider accepts the transcript.
+ *
+ * Pairing is per request, never by call id across the transcript, because a provider may number its
+ * calls afresh every round (`call_0` in round one and again in round two):
+ *
+ * 1. A `tool` message answers the call id of its first result. Its owner is the closest earlier
+ *    assistant message that made a call with that id and has no reply for it yet. A reply with no
+ *    owner (no earlier call, no call id, or a second reply to a call already answered) is dropped.
+ * 2. Every other message keeps its order. Directly after each assistant message that made calls come a
+ *    seal for each of its calls nothing answered, in call order, and then the replies it owns, in
+ *    their original order. A reply that was not already in the run of `tool` messages directly
+ *    after its owner is reported as moved.
+ * 3. A seal is a `tool` message carrying a failed result. It says the call was cut off when its
+ *    arguments do not parse ({@link SEAL_CUT_OFF}), and otherwise that the session was reloaded or
+ *    the history trimmed ({@link SEAL_RELOADED}). It is stamped with the requesting message's
+ *    timestamp and named `sealed_<call id>_<n>`, `n` being the call's place among that message's
+ *    unanswered calls, with `_<k>` appended when that id is taken.
+ *
+ * Pure and deterministic, and idempotent: repairing a repaired transcript reports nothing and
+ * returns the same messages.
+ *
+ * @param {readonly ChatMessage[]} messages
+ * @returns {RepairReport}
+ */
+export function repairToolPairs(messages: readonly ChatMessage[]): RepairReport {
+  /* Per call id, the indices of the assistant messages that made it, oldest first; per such message,
+     its calls, the call ids answered so far and the indices of the replies it owns. */
+  const requesters = new Map<string, number[]>();
+  const calls = new Map<number, ToolCallBlock[]>();
+  const answered = new Map<number, Set<string>>();
+  const owned = new Map<number, number[]>();
+  const dropped: string[] = [];
+
+  for (const [index, message] of messages.entries()) {
+    if (message.role === "assistant") {
+      const made = callsOf(message);
+      if (made.length > 0) {
+        calls.set(index, made);
+        answered.set(index, new Set());
+        owned.set(index, []);
+        for (const call of made) {
+          requesters.set(call.id, [...(requesters.get(call.id) ?? []), index]);
+        }
+      }
+    } else if (message.role === "tool") {
+      const callId = answers(message);
+      const owner = requesters.get(callId)?.findLast((at) => !answered.get(at)!.has(callId));
+      if (owner === undefined) {
+        dropped.push(message.id);
+      } else {
+        answered.get(owner)!.add(callId);
+        owned.get(owner)!.push(index);
+      }
+    }
+  }
+
+  const used = new Set(messages.map((message) => message.id));
+  const repaired: ChatMessage[] = [];
+  const sealed: string[] = [];
+  const moved: string[] = [];
+
+  for (const [index, message] of messages.entries()) {
+    if (message.role === "tool") {
+      continue;
+    }
+    repaired.push(message);
+    const made = calls.get(index);
+    if (!made) {
+      continue;
+    }
+    const replied = answered.get(index)!;
+    const unanswered = made.filter((call) => !replied.has(call.id));
+    for (const [n, call] of unanswered.entries()) {
+      repaired.push(seal(call, n, message.timestamp, used));
+      sealed.push(call.id);
+    }
+    // The run of `tool` messages directly after the request, in the input: a reply there stayed.
+    let runEnd = index + 1;
+    while (runEnd < messages.length && messages[runEnd]!.role === "tool") {
+      runEnd += 1;
+    }
+    for (const at of owned.get(index)!) {
+      const reply = messages[at]!;
+      repaired.push(reply);
+      if (at >= runEnd) {
+        moved.push(reply.id);
+      }
+    }
+  }
+
+  return { messages: repaired, sealed, dropped, moved };
+}

package/src/messages/types.ts

@@ -0,0 +1,202 @@
+/**
+ * Types.ts — the provider-neutral conversation model, and the v1 shape it is read from.
+ *
+ * Type-only. `@jxsuite/ai/messages` re-exports all of it; the conversions live in `convert.ts` and
+ * `openai.ts`.
+ *
+ * A conversation used to have one shape, OpenAI's: a message was `content`, an optional
+ * `reasoningContent` and an optional list of `toolCalls`, and the request was that array with the
+ * field names changed. Every provider that is not OpenAI-compatible describes a turn differently
+ * (Anthropic's thinking blocks carry a signature that must be replayed byte for byte, and its tool
+ * results ride on a user message), so a transcript written in one provider's words cannot be sent
+ * to another without guessing. A {@link ChatMessage} is a list of typed {@link Block}s instead, and
+ * each provider's adapter projects it onto its own wire (specs/ai.md §2.3).
+ *
+ * @module @jxsuite/ai/messages
+ * @license MIT
+ */
+
+import type { JsonValue, ToolResult } from "../core-types.ts";
+
+export type { JsonArray, JsonObject, JsonValue } from "../core-types.ts";
+
+/** The provider families a block can come from, and that an adapter projects onto. */
+export type ProviderFamily = "openai-compat" | "anthropic";
+
+/** Which provider produced a block, for a block that must only be replayed to that provider. */
+export interface Provenance {
+  readonly family: ProviderFamily;
+  /** The model that produced it; null only for data migrated from the v1 shape. */
+  readonly model: string | null;
+}
+
+/** Text the model wrote, or the person did. */
+export interface TextBlock {
+  readonly type: "text";
+  readonly text: string;
+}
+
+/** A thinking model's chain of thought: owed back to the provider that streamed it (§2.2). */
+export interface ReasoningBlock {
+  readonly type: "reasoning";
+  /** Empty when the provider sent only a redacted payload. */
+  readonly text: string;
+  /** Opaque, replayed unchanged to the provider that signed it. */
+  readonly signature?: string;
+  /** An opaque redacted payload, never merged into `text`. */
+  readonly redacted?: string;
+  /** Absent: the message's own `meta.family` decides, and v1 data is `openai-compat`. */
+  readonly provenance?: Provenance;
+}
+
+/** A tool call the model made. */
+export interface ToolCallBlock {
+  readonly type: "tool_call";
+  readonly id: string;
+  readonly name: string;
+  /** The arguments exactly as streamed, which may not parse: the only source of truth. */
+  readonly argumentsText: string;
+  /** An opaque per-call signature, round-tripped. */
+  readonly signature?: string;
+}
+
+/** What a tool call answered. */
+export interface ToolResultBlock {
+  readonly type: "tool_result";
+  readonly callId: string;
+  /** True when `content` parses as a result whose `success` is false; unparseable is false. */
+  readonly isError: boolean;
+  /** For a Jx tool, exactly the serialized `ToolResult`. */
+  readonly content: string;
+}
+
+/** Provider data the model has no neutral word for, kept for that provider alone. */
+export interface OpaqueBlock {
+  readonly type: "opaque";
+  readonly family: ProviderFamily;
+  readonly data: JsonValue;
+}
+
+export type Block = TextBlock | ReasoningBlock | ToolCallBlock | ToolResultBlock | OpaqueBlock;
+
+/** `system` is the v1 passthrough: a message any consumer may push, sent as it is. */
+export type Role = "user" | "assistant" | "tool" | "system";
+
+/** What a synthetic message is, for a message the harness rather than the model wrote. */
+export type MessageKind =
+  | "ctx_summary"
+  | "sealed"
+  | "round_cap"
+  | "seeded"
+  | "restored"
+  | "context"
+  | "compaction";
+
+/** Facts about a message that are never sent to a provider. */
+export interface MessageMeta {
+  readonly origin?: "model" | "harness" | "user";
+  readonly kind?: MessageKind;
+  readonly model?: string;
+  readonly family?: ProviderFamily;
+  readonly incomplete?: "error" | "truncated" | "length";
+  readonly turnId?: string;
+  /** A host's own facts, under reverse-DNS keys such as `com.jxsuite.studio/ledger`. */
+  readonly host?: Readonly<Record<string, JsonValue>>;
+}
+
+/** One message of a conversation, in no provider's words. */
+export interface ChatMessage {
+  readonly id: string;
+  readonly role: Role;
+  readonly blocks: readonly Block[];
+  readonly timestamp: number;
+  readonly meta?: MessageMeta;
+}
+
+/** What travels in a request: the role and the blocks, with no id, timestamp or meta. */
+export interface WireMessage {
+  readonly role: Role;
+  readonly blocks: readonly Block[];
+}
+
+/** A tool call as the v1 transcript records it: what the model sent, and the chip's outcome. */
+export interface LiveToolCall {
+  id: string;
+  name: string;
+  arguments: string;
+  /** Transcript-only: the outcome the chip renders. The `tool` reply is what the wire carries. */
+  result?: ToolResult | null;
+}
+
+/**
+ * The v1 message: chat-state's live shape and the shape every saved session holds, plus two
+ * optional fields.
+ */
+export interface LiveMessage {
+  id: string;
+  role: Role;
+  content: string;
+  /**
+   * The turn's chain of thought, when the provider streamed one (`reasoning_content` /
+   * `reasoning`). Kept because a thinking model's own history is not optional: DeepSeek's thinking
+   * mode REQUIRES every prior turn's `reasoning_content` back on any request that carries `tools`,
+   * which is every request the agent loop makes.
+   */
+  reasoningContent?: string;
+  toolCalls?: LiveToolCall[];
+  toolCallId?: string;
+  timestamp: number;
+  /**
+   * The message's blocks, present ONLY when the v1 fields above cannot describe them exactly: a
+   * signed, redacted or provider-bound reasoning block, an opaque block, or text and calls
+   * interleaved, for instance. The v1 fields are still written, so a reader that predates blocks
+   * keeps working.
+   */
+  blocks?: Block[];
+  meta?: MessageMeta;
+}
+
+/** One part of a system prompt. A request's parts are joined in order, with nothing between. */
+export interface SystemBlock {
+  readonly text: string;
+}
+
+/** A tool as a provider is told about it. */
+export interface ToolSpec {
+  readonly name: string;
+  readonly title?: string;
+  readonly description: string;
+  /** JSON Schema for the arguments, by reference: a host may build it with live getters. */
+  readonly inputSchema: Readonly<Record<string, unknown>>;
+  /** OpenAI's strict mode, opted into per tool. */
+  readonly strict?: boolean;
+}
+
+/** One OpenAI chat-completions tool call. */
+export interface OpenAIToolCall {
+  id: string;
+  type: "function";
+  function: { name: string; arguments: string };
+}
+
+/** One message on the OpenAI chat-completions wire. */
+export type OpenAIMessage =
+  | { role: "user" | "system"; content: string }
+  | {
+      role: "assistant";
+      content: string | null;
+      reasoning_content?: string;
+      tool_calls?: OpenAIToolCall[];
+    }
+  | { role: "tool"; tool_call_id: string; content: string };
+
+/** One tool on the OpenAI chat-completions wire: `ToolRegistry.listForLLM()`'s shape. */
+export interface OpenAITool {
+  type: "function";
+  function: {
+    name: string;
+    description: string;
+    parameters: Readonly<Record<string, unknown>>;
+    strict?: true;
+  };
+}

package/src/tools.ts

@@ -1,17 +1,18 @@
 /**
  * Tools.js — Tool registry infrastructure
  *
- * Provider-agnostic base classes for defining and registering tools that an LLM
- * can call. Tools have JSON Schema parameter definitions and execute functions.
- * The registry validates arguments before execution.
+ * Provider-agnostic base classes for defining and registering tools that an LLM can call. Tools
+ * have JSON Schema parameter definitions and execute functions. The registry validates arguments
+ * before execution.
  *
  * Every call carries a {@link ToolContext}: its own signal, its call id, who it acts for, the turn's
  * write ledger and the session's facts (specs/ai.md §3.7). A caller that has none gets a detached
- * one, so a tool run outside a turn (a test, a command) records into nothing and cannot be stopped.
+ * one, so a tool run outside a turn (a test, a command) records into nothing and cannot be
+ * stopped.
  *
- * @docs extending/embedding/assistant-harness
- * @license MIT
  * @module @jxsuite/ai/tools
+ * @license MIT
+ * @docs extending/embedding/assistant-harness
  */
 
 import type {
@@ -26,6 +27,8 @@ import type {
 export type {
   Actor,
   AiWrite,
+  JsonArray,
+  JsonObject,
   JsonValue,
   SessionFacts,
   ToolContext,
@@ -417,3 +420,96 @@ export function createToolRegistry() {
     },
   };
 }
+
+// ─── Invocation ──────────────────────────────────────────────────────────────
+
+/** A call a model made: its id, the tool, and the arguments exactly as streamed. */
+export interface ToolCall {
+  readonly callId: string;
+  readonly name: string;
+  /** Raw, and possibly not JSON: a call cut off mid-arguments still arrives. */
+  readonly argumentsText: string;
+}
+
+/** What invoking a call produced. `executed` is false when the registry was never reached. */
+export interface InvokeOutcome {
+  readonly status: "done";
+  readonly result: ToolResult;
+  readonly executed: boolean;
+}
+
+/**
+ * A result as JSON would carry it: the serialized bytes are unchanged, and `data` becomes plain
+ * JSON, so the result survives any transport that serializes it.
+ *
+ * @param {ToolResult} result
+ * @returns {ToolResult}
+ */
+export function normalizeToolResult(result: ToolResult): ToolResult {
+  // oxlint-disable-next-line unicorn/prefer-structured-clone -- the JSON round trip is the point
+  return JSON.parse(JSON.stringify(result)) as ToolResult;
+}
+
+/**
+ * A call's arguments as the object a tool takes.
+ *
+ * An empty string is no arguments. JSON that parses to something other than an object (`null`, an
+ * array, a number) is refused with its own sentence rather than reaching the registry, where a
+ * validator reading a property of `null` threw a message about the validator.
+ */
+function parseArguments(text: string): object {
+  if (!text) {
+    return {};
+  }
+  const parsed = JSON.parse(text) as unknown;
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    const type = parsed === null ? "null" : Array.isArray(parsed) ? "array" : typeof parsed;
+    throw new TypeError(`arguments must be a JSON object, got ${type}`);
+  }
+  return parsed;
+}
+
+/**
+ * Run one model call through a registry: parse its arguments, execute it with its context, and
+ * return the result as JSON would carry it. Never throws: a failure is a result the model reads.
+ *
+ * Arguments that do not parse answer `Failed to parse arguments: <reason>`, with the same prefix
+ * for a non-object, so the model reads both as one kind of mistake. The registry keeps its own
+ * texts for an unknown tool, failed validation, a gate and a tool that threw. A registry that
+ * itself throws is answered with the parse prefix too, as the agent loop always answered it, and a
+ * result JSON cannot carry is answered as one that cannot be serialized.
+ *
+ * @param {ToolRegistry} registry
+ * @param {ToolCall} call
+ * @param {ToolContext} ctx - The call's context, forwarded to the tool unchanged
+ * @returns {Promise<InvokeOutcome>}
+ */
+export async function invokeTool(
+  registry: ToolRegistry,
+  call: ToolCall,
+  ctx: ToolContext,
+): Promise<InvokeOutcome> {
+  let executed = false;
+  let result: ToolResult;
+  try {
+    const args = parseArguments(call.argumentsText);
+    executed = true;
+    result = await registry.execute(call.name, args, ctx);
+  } catch (error) {
+    result = toolError(`Failed to parse arguments: ${(error as Error).message}`);
+  }
+  try {
+    return { status: "done", result: normalizeToolResult(result), executed };
+  } catch (error) {
+    /* A result JSON cannot carry (a cycle, a BigInt) cannot be sent back to the model either. It
+       used to throw out of the turn; the model is told instead, and the turn goes on. */
+    const reason = (error as Error).message;
+    return {
+      status: "done",
+      result: toolError(
+        `Tool "${call.name}" returned a result that cannot be serialized: ${reason}`,
+      ),
+      executed,
+    };
+  }
+}