@jxsuite/ai 0.35.0 → 0.36.2

package/README.md

@@ -0,0 +1,177 @@
+# @jxsuite/ai
+
+The provider-agnostic substrate Jx Studio's assistant is built on: a streaming LLM client
+abstraction that normalizes provider SSE into six event shapes, a tool registry that speaks OpenAI
+function-calling, and a reactive chat store. It has no Jx-domain dependencies — only a type-only
+import of `ProblemDetails` from `@jxsuite/protocol` and `@vue/reactivity` — and its only platform
+APIs are `fetch`, `TextDecoder` and `AbortSignal`, so the same modules run in the browser and in
+Bun/Node.
+
+Governing spec: [`specs/ai.md`](../../specs/ai.md) §1-§2 (Status: Partial). User-facing
+documentation for the Studio feature lives at [`docs/studio/ai.md`](../../docs/studio/ai.md).
+
+| Entrypoint                     | Exports                                                                                                                                     |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@jxsuite/ai`                  | Barrel: the three factories, `createToolDefinition`, `createToolRegistry`, `createChatState`, `STREAM_EVENT_TYPES`, and the streaming types |
+| `@jxsuite/ai/streaming-client` | `StreamingClient`, `StreamEvent` and its six members, the three factories and their option types, `STREAM_EVENT_TYPES`                      |
+| `@jxsuite/ai/tools`            | `createToolDefinition`, `createToolRegistry`, `toolSuccess`, `toolError`, and their types                                                   |
+| `@jxsuite/ai/chat-state`       | `createChatState`, `ChatStore`, `Message`, `ToolCallRecord`, `ChatState`, `MessageRole`                                                     |
+
+`toolSuccess` / `toolError` are **not** re-exported by the barrel — import them from
+`@jxsuite/ai/tools`. Importing the subpaths rather than the root is also what makes the package
+tree-shakeable.
+
+## The streaming client
+
+`StreamingClient` is one method:
+
+```ts
+streamChat(messages: object[], tools: object[], systemPrompt: string, signal: AbortSignal)
+  : AsyncGenerator<StreamEvent>;
+```
+
+Every implementation yields the same discriminated union — `delta {content}`,
+`tool_call_start {id, name}`, `tool_call_delta {id, args}`, `tool_call_end {id}`,
+`done {stopReason}`, `error {message, code?, problem?}` — whose type strings are also published as
+`STREAM_EVENT_TYPES`. This union is the contract a third-party Studio backend must satisfy for the
+`ai/chat` route (see [`packages/protocol/README.md`](../protocol/README.md)); `@jxsuite/server`
+emits the same format without depending on this package. `StreamEvent` and each member are
+exported, so an implementer can import the type rather than reconstruct it.
+
+```ts
+import { createProxyStreamingClient } from "@jxsuite/ai";
+
+const client = createProxyStreamingClient({
+  chatUrl: "/__studio/ai/chat",
+  model: "gpt-4o",
+});
+for await (const event of client.streamChat(messages, tools, systemPrompt, signal)) {
+  switch (event.type) {
+    /* … */
+  }
+}
+```
+
+- **`createOpenAIStreamingClient({ baseUrl, apiKey, model = "gpt-4o", temperature })`** POSTs to
+  `${baseUrl}/chat/completions` with `Authorization: Bearer`, `stream: true`,
+  `stream_options: { include_usage: true }`, and `{ role: "system", content: systemPrompt }`
+  prepended to your messages. A non-empty `tools` array also sets `tool_choice: "auto"` and
+  `parallel_tool_calls: true`; an empty one sends no `tools` key. `temperature` is forwarded **only
+  when defined**, because reasoning models (GPT-5.x, o-series) reject a custom temperature — a
+  provider behaviour recorded in the source comment, not covered by a test here. It does
+  its own SSE framing and reassembles fragmented tool-call argument JSON keyed by the provider's
+  `delta.tool_calls[].index`.
+- **`createAnthropicStreamingClient({ baseUrl, apiKey })`** is a stub. It makes no network call and
+  yields exactly one `error` event with `code: "NOT_IMPLEMENTED"`. Only the OpenAI-compatible path
+  ships (`specs/ai.md` §2).
+- **`createProxyStreamingClient({ chatUrl, model = "gpt-4o", apiKey, baseUrl })`** POSTs
+  `{ messages, tools, systemPrompt, model }` to an endpoint that already speaks the normalized
+  format — the dev/desktop server's `/__studio/ai/chat`. It handles no credentials of its own;
+  `apiKey` and `baseUrl` are passed through as the `X-Api-Key` and `X-Api-Base-URL` headers only
+  when truthy, and the proxy owns the provider key. It is a pass-through, **not** a translator: it
+  re-yields whatever parses out of each `data:` line and returns at the first `done` or `error`, so
+  frames after `done` are dropped.
+
+Three behaviours are easy to get wrong when consuming the stream:
+
+1. **Cancellation is a `done`, not an `error`.** An `AbortError` from `fetch` or mid-read becomes
+   `{ type: "done", stopReason: "cancelled" }`. Treating abort as failure paints a user's Stop
+   button as a crash. The OpenAI client's other stop reasons are `"stop"`, `"tool_calls"` and
+   `"length"`.
+2. **The OpenAI client drains pending tool calls on every termination path.** `[DONE]`, a
+   `finish_reason` of `stop`, `length` or `tool_calls` (any other value is ignored and the stream
+   continues), and a body that simply closes all emit `tool_call_end` for anything still open, then
+   exactly one `done`. The proxy client tracks nothing of its own, so a body that closes without a
+   `done` frame ends its generator with no `done` at all.
+3. **`error` frames may carry an RFC 9457 `problem` beside the human `message`,** because the
+   response has already begun with a 200 and the status can no longer change (a committed standards
+   row in `specs/ai.md` §5). The field is optional and no client in this package sets it —
+   `@jxsuite/server`'s proxy is what populates it and `createProxyStreamingClient` passes it
+   through. Read `problem.type` for machine dispatch when it is present; keep showing `message`.
+
+## The tool registry
+
+`createToolRegistry()` returns `{ register, list, listForLLM, validate, execute, getDefinition }`.
+`listForLLM()` emits `{ type: "function", function: { name, description, parameters } }`, ready to
+hand straight to `streamChat`'s `tools` argument.
+
+```ts
+import { createToolDefinition, createToolRegistry, toolSuccess } from "@jxsuite/ai/tools";
+
+const registry = createToolRegistry();
+registry.register(
+  createToolDefinition({
+    name: "set_property",
+    description: "Set a property on a node",
+    parameters: {
+      type: "object",
+      properties: { path: { type: "string" } },
+      required: ["path"],
+    },
+    execute: (args) => toolSuccess(args, "set"),
+  }),
+);
+```
+
+- **`strict` and `llmStrict` are unrelated despite the names.** `strict` (default `true`) drives the
+  registry's own argument validation. `llmStrict` (default `false`) is the only one that reaches the
+  wire, adding OpenAI's `strict: true` to the emitted function schema. OpenAI strict mode demands
+  `additionalProperties: false` and every property in `required`, which Jx's own tools deliberately
+  violate — GPT-5.x rejects such a request outright (again, committed rationale rather than a test).
+- **`validate()` is a lightweight structural check, not a JSON Schema validator.** It reads only
+  `type`, `properties` and `required`: nested schemas, `enum`, `pattern`, `minimum` and every other
+  keyword are ignored. Unknown properties are ignored too (the model may send extra); a required key
+  that is present but `null`/`undefined` counts as missing; numeric strings coerce, so `"42"`
+  validates against `number`. `strict: false`, or a schema without `properties`, skips it entirely.
+- **`execute()` never throws.** An unknown tool, a validation failure, and an exception inside the
+  tool all return `{ success: false, error }` — which is what lets an agent loop feed the failure
+  back to the model and self-correct. It calls `this.validate(...)`, so it is `this`-bound: do not
+  destructure it off the registry.
+- Re-registering a name `console.warn`s and overwrites.
+
+To vary the tool set per turn, wrap rather than mutate — Studio's `createGatedToolRegistry` returns
+a `ToolRegistry` that filters `list()`/`listForLLM()` through per-tool predicates
+(`packages/studio/src/services/gated-registry.ts`).
+
+## The reactive chat store
+
+`createChatState(options?: { model?: string })` returns a `@vue/reactivity` `reactive()` store —
+`messages`, `status`, `streamingContent`, `pendingToolCalls`, `error`, `model`, `tokenCount`,
+`contextWarning` — with its mutators `Object.assign`ed onto the same proxy, so the returned value is
+both the state and the API. The model falls back to `"gpt-4o"` via `||`, so an empty string takes
+the default too. `status` is `"idle" | "streaming" | "error"`; `toMessagesArray()`
+serializes back to OpenAI wire shape (assistant `tool_calls`, `tool` messages with `tool_call_id`,
+everything else `{ role, content }`).
+
+Two ordering rules inside `beginAssistantTurn` are load-bearing, and any reimplementation must keep
+them: `status` is set to `"streaming"` **before** the placeholder message is pushed (the push itself
+triggers effects, and a reader seeing `"idle"` renders the empty placeholder as a finished message),
+and the pushed object is immediately re-read back through the proxy (`store.messages.at(-1)`) —
+mutating the raw object would notify nothing. A regression test asserts that an `effect()` reading
+`messages.at(-1).content` re-runs on every `appendDelta`.
+
+Further surprises:
+
+- **`sendMessage(text)` produces two messages**, not one: the user message plus an empty assistant
+  placeholder, and status flips to `"streaming"`. There is no way to append a bare user message with
+  it. `beginAssistantTurn()` exists separately so an agent loop can open the next round after
+  pushing tool results, with no new user message.
+- **`sendMessage` / `beginAssistantTurn` are no-ops while streaming**; `appendDelta` /
+  `appendToolCallStart` are no-ops while not streaming.
+- **`setError` and `cancelStream` delete the partial streaming message**, because it may hold
+  incomplete `tool_calls` that would poison history on the next send. That deletion is why
+  `specs/ai.md` §3.2 forbids reporting an exhausted tool-call budget as an error: the error path
+  destroys the only account of the edits that did land.
+- **`appendToolCallEnd(id)` is an intentional no-op.** Arguments are already fully accumulated; the
+  caller parses the JSON and executes the tool.
+- Message ids come from a module-level counter (`msg_${Date.now()}_${n}`), not a UUID.
+
+## Versioning
+
+Published to npm as `@jxsuite/ai` — TypeScript source, like every published `@jxsuite` library,
+following the monorepo's release train; every `exports` subpath resolves to `./src/*.ts`, so a
+consumer must be
+able to compile TypeScript out of `node_modules`. Within the monorepo, `@jxsuite/studio` depends on
+it via `workspace:^` and is its only consumer. `@vue/reactivity` is pinned to an **exact** version,
+matching `@jxsuite/studio`, `@jxsuite/runtime` and `@jxsuite/compiler`: reactive proxies from one
+copy do not track in effects from another, and the failure is silent.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/ai",
-  "version": "0.35.0",
+  "version": "0.36.2",
   "description": "AI infrastructure for Jx Suite — streaming LLM client abstraction, tool registry, and reactive chat state",
   "license": "MIT",
   "repository": {
@@ -28,10 +28,10 @@
     "upgrade": "bunx npm-check-updates -u && bun install"
   },
   "dependencies": {
-    "@jxsuite/protocol": "^1.1.0",
+    "@jxsuite/protocol": "^1.2.0",
     "@vue/reactivity": "3.5.41"
   },
   "devDependencies": {
-    "@happy-dom/global-registrator": "^20.11.2"
+    "@happy-dom/global-registrator": "^20.11.6"
   }
 }

package/src/index.ts

@@ -19,3 +19,17 @@ export {
   createAnthropicStreamingClient,
   createProxyStreamingClient,
 } from "./streaming-client.js";
+
+export type {
+  AnthropicStreamingClientOptions,
+  OpenAIStreamingClientOptions,
+  ProxyStreamingClientOptions,
+  StreamDeltaEvent,
+  StreamDoneEvent,
+  StreamErrorEvent,
+  StreamEvent,
+  StreamingClient,
+  StreamToolCallDeltaEvent,
+  StreamToolCallEndEvent,
+  StreamToolCallStartEvent,
+} from "./streaming-client.js";

package/src/streaming-client.ts

@@ -1,17 +1,21 @@
 /**
  * Streaming-client.js — Provider-agnostic streaming LLM client abstraction
  *
- * Defines the StreamingClient interface (as JSDoc typedefs), the StreamEvent union type,
+ * Defines the StreamingClient interface, the StreamEvent union every implementation yields,
  * and concrete implementations for OpenAI and Anthropic. Designed upfront so switching
  * providers is a new implementation, not a refactor.
  *
+ * The union and its six members are exported because they are the contract a third-party Studio
+ * backend implements for the `ai/chat` route, not an internal detail — see the docs page below.
+ *
  * @license MIT
  * @module @jxsuite/ai/streaming-client
+ * @docs extending/embedding/backend-protocol
  */
 
 import type { ProblemDetails } from "@jxsuite/protocol";
 
-type StreamEvent =
+export type StreamEvent =
   | StreamDeltaEvent
   | StreamToolCallStartEvent
   | StreamToolCallDeltaEvent
@@ -19,29 +23,29 @@ type StreamEvent =
   | StreamDoneEvent
   | StreamErrorEvent;
 
-interface StreamDeltaEvent {
+export interface StreamDeltaEvent {
   type: "delta";
   content: string;
 }
 
-interface StreamToolCallStartEvent {
+export interface StreamToolCallStartEvent {
   type: "tool_call_start";
   id: string;
   name: string;
 }
 
-interface StreamToolCallDeltaEvent {
+export interface StreamToolCallDeltaEvent {
   type: "tool_call_delta";
   id: string;
   args: string;
 }
 
-interface StreamToolCallEndEvent {
+export interface StreamToolCallEndEvent {
   type: "tool_call_end";
   id: string;
 }
 
-interface StreamDoneEvent {
+export interface StreamDoneEvent {
   type: "done";
   stopReason: string;
 }
@@ -56,7 +60,7 @@ interface StreamDoneEvent {
  * half (a `type` a client can key on), `message` stays the human half every existing reader already
  * shows, and `code` remains for the providers that send one.
  */
-interface StreamErrorEvent {
+export interface StreamErrorEvent {
   type: "error";
   message: string;
   code?: string;
@@ -162,17 +166,19 @@ export const STREAM_EVENT_TYPES = {
  *   near-deterministic eval runs.
  * @returns {StreamingClient}
  */
+export interface OpenAIStreamingClientOptions {
+  baseUrl: string;
+  apiKey: string;
+  model?: string;
+  temperature?: number | undefined;
+}
+
 export function createOpenAIStreamingClient({
   baseUrl,
   apiKey,
   model = "gpt-4o",
   temperature,
-}: {
-  baseUrl: string;
-  apiKey: string;
-  model?: string;
-  temperature?: number | undefined;
-}): StreamingClient {
+}: OpenAIStreamingClientOptions): StreamingClient {
   /**
    * @param {object[]} messages
    * @param {object[]} tools
@@ -398,10 +404,14 @@ export function createOpenAIStreamingClient({
  * @param {string} _opts.apiKey
  * @returns {StreamingClient}
  */
-export function createAnthropicStreamingClient(_opts: {
+export interface AnthropicStreamingClientOptions {
   baseUrl: string;
   apiKey: string;
-}): StreamingClient {
+}
+
+export function createAnthropicStreamingClient(
+  _opts: AnthropicStreamingClientOptions,
+): StreamingClient {
   /**
    * @yields {StreamEvent} Normalized stream events.
    * @returns {AsyncGenerator<StreamEvent>}
@@ -431,17 +441,19 @@ export function createAnthropicStreamingClient(_opts: {
  * @param {string} [opts.baseUrl] - Optional OpenAI-compatible base URL, sent as `X-Api-Base-URL`
  * @returns {StreamingClient}
  */
+export interface ProxyStreamingClientOptions {
+  chatUrl: string;
+  model?: string;
+  apiKey?: string | undefined;
+  baseUrl?: string | undefined;
+}
+
 export function createProxyStreamingClient({
   chatUrl,
   model = "gpt-4o",
   apiKey,
   baseUrl,
-}: {
-  chatUrl: string;
-  model?: string;
-  apiKey?: string | undefined;
-  baseUrl?: string | undefined;
-}): StreamingClient {
+}: ProxyStreamingClientOptions): StreamingClient {
   /**
    * @param {object[]} messages
    * @param {object[]} tools