@jxsuite/ai 0.39.0 → 0.39.2

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Kevin Shenk
+Copyright (c) 2026 Avunu LLC and Jx Suite contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/ai",
-  "version": "0.39.0",
+  "version": "0.39.2",
   "description": "AI infrastructure for Jx Suite — streaming LLM client abstraction, tool registry, and reactive chat state",
   "license": "MIT",
   "repository": {
@@ -18,7 +18,9 @@
     "./streaming-client": "./src/streaming-client.ts",
     "./tools": "./src/tools.ts",
     "./chat-state": "./src/chat-state.ts",
-    "./gateway": "./src/gateway/index.ts"
+    "./gateway": "./src/gateway/index.ts",
+    "./harness": "./src/harness/index.ts",
+    "./messages": "./src/messages/index.ts"
   },
   "publishConfig": {
     "provenance": true
@@ -29,11 +31,11 @@
     "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
-    "@jxsuite/protocol": "^2.5.0",
+    "@jxsuite/protocol": "^2.6.0",
     "@vue/reactivity": "3.5.43"
   },
   "devDependencies": {
-    "@cloudflare/workers-types": "^5.20260928.1",
+    "@cloudflare/workers-types": "^5.20261002.1",
     "@happy-dom/global-registrator": "^20.14.5"
   }
 }

package/src/chat-state.ts

@@ -1,45 +1,32 @@
 /**
  * Chat-state.js — Provider-agnostic reactive chat state management
  *
- * Manages the lifecycle of a chat conversation: messages, streaming status,
- * tool calls, and errors. Built on @vue/reactivity for fine-grained updates.
- * No Studio or Jx dependencies — reusable in any chat UI context.
+ * Manages the lifecycle of a chat conversation: messages, streaming status, tool calls, and errors.
+ * Built on @vue/reactivity for fine-grained updates. No Studio or Jx dependencies — reusable in any
+ * chat UI context.
  *
- * @license MIT
  * @module @jxsuite/ai/chat-state
+ * @license MIT
  */
 
 import { reactive } from "@vue/reactivity";
 
+import { nextMessageId } from "./message-id.ts";
+import { toChatMessages } from "./messages/convert.ts";
+import { toOpenAIMessages } from "./messages/openai.ts";
+import type { LiveMessage, LiveToolCall, OpenAIMessage, Role } from "./messages/types.ts";
 import type { StreamUsageEvent } from "./streaming-client.ts";
 import type { ToolResult } from "./tools.ts";
 
 export type ChatState = "idle" | "streaming" | "error";
 
-export type MessageRole = "user" | "assistant" | "system" | "tool";
+export type MessageRole = Role;
 
-export interface Message {
-  id: string;
-  role: MessageRole;
-  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. See {@link toMessagesArray}.
-   */
-  reasoningContent?: string;
-  toolCalls?: ToolCallRecord[];
-  toolCallId?: string;
-  timestamp: number;
-}
+/** A transcript message: the v1 shape `@jxsuite/ai/messages` reads (specs/ai.md §2.3). */
+export type Message = LiveMessage;
 
-export interface ToolCallRecord {
-  id: string;
-  name: string;
-  arguments: string;
-  result?: ToolResult | null;
-}
+/** A tool call on a transcript message, carrying the outcome its chip renders. */
+export type ToolCallRecord = LiveToolCall;
 
 /**
  * The provider's own count for the last request, and where in the transcript it was taken.
@@ -86,13 +73,8 @@ export interface ChatStore {
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
-let _idCounter = 0;
-
-/** @returns {string} */
-function uid() {
-  _idCounter += 1;
-  return `msg_${Date.now()}_${_idCounter}`;
-}
+/** A fresh message id, from the counter the harness shares. */
+const uid = nextMessageId;
 
 /** A token count a budget can use: a finite, non-negative number. */
 function isCount(value: unknown): value is number {
@@ -126,7 +108,7 @@ function isCount(value: unknown): value is number {
  *   recordUsage: (usage: StreamUsageEvent, opts?: { systemTokens?: number }) => void;
  *   clearUsage: () => void;
  *   setContextWarning: (warning: boolean) => void;
- *   toMessagesArray: () => object[];
+ *   toMessagesArray: () => OpenAIMessage[];
  * }}
  */
 export function createChatState(opts: { model?: string } = {}) {
@@ -434,11 +416,11 @@ export function createChatState(opts: { model?: string } = {}) {
     }
     const { type: _type, ...counts } = usage;
     const counted = _streamingMessage ?? store.messages.at(-1);
-    /* Replayed means SENT: `toMessagesArray` drops an assistant turn carrying neither text nor
-       tool calls, reasoning and all, so a turn that only thought is not replayed either. */
-    const replayed = Boolean(
-      counted?.reasoningContent && (counted.content || (counted.toolCalls?.length ?? 0) > 0),
-    );
+    /* Replayed means SENT, so the projection that builds the request is asked: it drops an
+       assistant turn carrying neither text nor tool calls, reasoning and all, so a turn that only
+       thought is not replayed either. */
+    const [sent] = counted ? toOpenAIMessages(toChatMessages([counted])) : [];
+    const replayed = sent?.role === "assistant" && Boolean(sent.reasoning_content);
     const unreplayed = replayed || !isCount(usage.reasoningTokens) ? 0 : usage.reasoningTokens;
     const contextTokens = Math.max(0, usage.inputTokens + usage.outputTokens - unreplayed);
     store.usage = {
@@ -466,74 +448,14 @@ export function createChatState(opts: { model?: string } = {}) {
   }
 
   /**
-   * Convert the current chat state to an array suitable for sending to an LLM API. Includes the
-   * system prompt as the first message and all conversation turns.
-   *
-   * Two things it does NOT do verbatim, both because the array is a transcript for the UI and this
-   * is the wire:
-   *
-   * 1. **An assistant turn carrying neither text nor tool calls is dropped.** The one that always
-   *    exists is {@link beginAssistantTurn}'s placeholder — the message being generated by the very
-   *    request this builds, so it is a turn that has not happened yet. It reached providers as a
-   *    trailing `{"role":"assistant","content":""}`, which most read as an empty prefill and
-   *    ignore; DeepSeek's thinking mode instead answers 400 `The reasoning_content in the thinking
-   *    mode must be passed back to the API`, because a thinking-mode assistant turn owes it one.
-   *    `persistChat` in Studio already skipped the same message for the same reason — it just
-   *    skipped it on the way to storage, and nothing skipped it on the way to the provider.
-   * 2. **`reasoning_content` is replayed when the turn has one.** DeepSeek requires the reasoning of
-   *    all previous turns back on any request carrying `tools` — which is every request the agent
-   *    loop makes — and ignores it on requests that carry none, so echoing what the provider itself
-   *    streamed is safe for providers that never send it (they get no field at all).
+   * The conversation as the OpenAI chat-completions `messages` array the next request carries:
+   * `toOpenAIMessages(toChatMessages(messages))` from `@jxsuite/ai/messages`, which says what the
+   * wire leaves out and why (specs/ai.md §2.2). The system prompt travels separately.
    *
-   * @returns {object[]}
+   * @returns {OpenAIMessage[]}
    */
-  function toMessagesArray() {
-    const out = [];
-
-    for (const msg of store.messages) {
-      if (msg.role === "assistant") {
-        const calls = msg.toolCalls ?? [];
-        if (!msg.content && calls.length === 0) {
-          continue;
-        }
-        const entry: {
-          role: string;
-          content: string | null;
-          reasoning_content?: string;
-          tool_calls?: object[];
-        } = {
-          role: "assistant",
-          content: calls.length > 0 ? msg.content || null : msg.content,
-        };
-        if (msg.reasoningContent) {
-          entry.reasoning_content = msg.reasoningContent;
-        }
-        if (calls.length > 0) {
-          entry.tool_calls = calls.map((tc) => ({
-            id: tc.id,
-            type: "function",
-            function: {
-              name: tc.name,
-              arguments: tc.arguments,
-            },
-          }));
-        }
-        out.push(entry);
-      } else if (msg.role === "tool") {
-        out.push({
-          role: "tool",
-          tool_call_id: msg.toolCallId,
-          content: msg.content,
-        });
-      } else {
-        out.push({
-          role: msg.role,
-          content: msg.content,
-        });
-      }
-    }
-
-    return out;
+  function toMessagesArray(): OpenAIMessage[] {
+    return toOpenAIMessages(toChatMessages(store.messages));
   }
 
   return Object.assign(store, {

package/src/core-types.ts

@@ -10,18 +10,29 @@
  * running one turn. A {@link ToolContext} carries those facts with the call instead, so the same
  * tool can run in a page, a Worker or an MCP server (specs/ai.md §3.7).
  *
- * @license MIT
  * @module @jxsuite/ai/tools
+ * @license MIT
+ */
+
+/**
+ * A value that survives a JSON round trip unchanged.
+ *
+ * The array and object members are named interfaces rather than inline types on purpose. Vue's
+ * `reactive()` unwraps a store's type member by member, and an inline recursive alias gives it a
+ * fresh type at every level, so a store holding one (chat-state's messages can carry a block's
+ * opaque data) fails to compile as "excessively deep". A named interface is the same type at every
+ * level, and the walk stops.
  */
+export type JsonValue = null | boolean | number | string | JsonArray | JsonObject;
 
-/** A value that survives a JSON round trip unchanged. */
-export type JsonValue =
-  | null
-  | boolean
-  | number
-  | string
-  | JsonValue[]
-  | { [key: string]: JsonValue };
+/** A JSON array. */
+// oxlint-disable-next-line typescript/no-empty-interface, typescript/no-empty-object-type -- named, see JsonValue
+export interface JsonArray extends Array<JsonValue> {}
+
+/** A JSON object. */
+export interface JsonObject {
+  [key: string]: JsonValue;
+}
 
 /** What a tool call answers. */
 export interface ToolResult {

package/src/harness/index.ts

@@ -0,0 +1,34 @@
+/**
+ * `@jxsuite/ai/harness`: the turn engine (specs/ai.md §3.8).
+ *
+ * `runTurn` takes a conversation, a model function and a tool registry, and runs one user turn to
+ * its end: it streams each round, runs the calls the model made, feeds their results back, and
+ * stops when the model stops calling tools or the work budget runs out. Everything it does is an
+ * event a host can apply to its own transcript, and how the turn ended is a `TurnOutcome`.
+ *
+ * Worker-safe: it imports `./tools` and `./messages` and nothing host-bound
+ * (`tests/worker-safety.test.ts`, `tsconfig.worker.json`).
+ *
+ * @module @jxsuite/ai/harness
+ * @docs extending/embedding/assistant-harness
+ */
+
+export { LaneBusyError, createTurnLock } from "./lock.ts";
+export { fromStreamingClient, joinSystem } from "./model.ts";
+export { DEFAULT_TURN_POLICY } from "./policy.ts";
+export { runTurn } from "./run.ts";
+
+export type {
+  HarnessEvent,
+  ModelFn,
+  ModelRequest,
+  TurnError,
+  TurnHooks,
+  TurnInput,
+  TurnLock,
+  TurnOutcome,
+  TurnOutcomeKind,
+  TurnPolicy,
+  TurnRun,
+  Usage,
+} from "./types.ts";

package/src/harness/lock.ts

@@ -0,0 +1,45 @@
+/**
+ * Lock.ts — one turn at a time.
+ *
+ * @module @jxsuite/ai/harness
+ * @license MIT
+ */
+
+import type { TurnLock } from "./types.ts";
+
+/** Thrown, synchronously, by `runTurn` when its lock is already held by another turn. */
+export class LaneBusyError extends Error {
+  constructor(active: string) {
+    super(`A turn is already running (${active}).`);
+    this.name = "LaneBusyError";
+  }
+}
+
+/**
+ * A lock one turn holds at a time. A release function releases only the hold it was returned for,
+ * so a late call from a turn that already ended cannot free a newer turn's hold.
+ *
+ * @returns {TurnLock}
+ */
+export function createTurnLock(): TurnLock {
+  let active: string | null = null;
+  let hold = 0;
+  return {
+    acquire(turnId) {
+      if (active !== null) {
+        return null;
+      }
+      active = turnId;
+      hold += 1;
+      const mine = hold;
+      return () => {
+        if (hold === mine) {
+          active = null;
+        }
+      };
+    },
+    get active() {
+      return active;
+    },
+  };
+}

package/src/harness/model.ts

@@ -0,0 +1,37 @@
+/**
+ * Model.ts — a model function over a v1 streaming client.
+ *
+ * @module @jxsuite/ai/harness
+ * @license MIT
+ */
+
+import { toOpenAIMessages, toOpenAITools } from "../messages/openai.ts";
+import type { SystemBlock } from "../messages/types.ts";
+import type { StreamingClient } from "../streaming-client.ts";
+import type { ModelFn } from "./types.ts";
+
+/**
+ * A request's system prompt as one text: its parts joined in order, with nothing between.
+ *
+ * @param {readonly SystemBlock[]} system
+ * @returns {string}
+ */
+export function joinSystem(system: readonly SystemBlock[]): string {
+  return system.map((block) => block.text).join("");
+}
+
+/**
+ * A model function that sends each round through `client.streamChat`, projected onto the OpenAI
+ * chat-completions wire (specs/ai.md §2.3). `streamChat` is read off the client on every call, so a
+ * host that swaps it between rounds is honoured, and it is called exactly once per round.
+ *
+ * @param {StreamingClient} client
+ * @returns {ModelFn}
+ */
+export function fromStreamingClient(client: StreamingClient): ModelFn {
+  return (request, signal) => {
+    const messages = toOpenAIMessages(request.messages);
+    const tools = toOpenAITools(request.tools);
+    return client.streamChat(messages, tools, joinSystem(request.system), signal);
+  };
+}

package/src/harness/policy.ts

@@ -0,0 +1,39 @@
+/**
+ * Policy.ts — the numbers and words a turn is bounded and reported by.
+ *
+ * @module @jxsuite/ai/harness
+ * @license MIT
+ */
+
+import type { TurnPolicy } from "./types.ts";
+
+/** Average characters per token: the estimate every budget used before providers reported counts. */
+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).
+ *
+ * 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.
+ */
+export const DEFAULT_TURN_POLICY: TurnPolicy = {
+  maxWorkRounds: 5,
+  maxRounds: 25,
+  estimateTokens: (text) => Math.ceil(text.length / CHARS_PER_TOKEN),
+  capText: ({ maxWorkRounds, applied, errors }) => {
+    const unique = [...new Set(errors)];
+    const appliedPart =
+      applied.length > 0
+        ? `\n\nChanges applied so far:\n${applied.map((s) => `- ${s}`).join("\n")}`
+        : "";
+    const errorPart =
+      unique.length > 0 ? `\n\nErrors encountered:\n${unique.map((e) => `- ${e}`).join("\n")}` : "";
+    return (
+      `I ran out of tool-call rounds (${maxWorkRounds}) before finishing.${appliedPart}${errorPart}` +
+      `\n\nYou can continue by sending another message, or try a more specific request.`
+    );
+  },
+  emptyText: "The model sent back an empty reply.",
+};