@jxsuite/ai 0.39.5 → 0.41.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/ai",
-  "version": "0.39.5",
+  "version": "0.41.0",
   "description": "AI infrastructure for Jx Suite — streaming LLM client abstraction, tool registry, and reactive chat state",
   "license": "MIT",
   "repository": {
@@ -20,7 +20,9 @@
     "./chat-state": "./src/chat-state.ts",
     "./gateway": "./src/gateway/index.ts",
     "./harness": "./src/harness/index.ts",
-    "./messages": "./src/messages/index.ts"
+    "./messages": "./src/messages/index.ts",
+    "./jx-tools": "./src/jx-tools/index.ts",
+    "./catalog": "./src/catalog/index.ts"
   },
   "publishConfig": {
     "provenance": true
@@ -31,11 +33,12 @@
     "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
-    "@jxsuite/protocol": "^4.0.0",
+    "@jxsuite/protocol": "^5.0.0",
+    "@jxsuite/schema": "^4.1.0",
     "@vue/reactivity": "3.5.44"
   },
   "devDependencies": {
-    "@cloudflare/workers-types": "^5.20261016.1",
-    "@happy-dom/global-registrator": "^21.0.3"
+    "@cloudflare/workers-types": "^5.20261026.1",
+    "@happy-dom/global-registrator": "^21.0.4"
   }
 }

package/src/catalog/catalog.ts

@@ -0,0 +1,166 @@
+/**
+ * Tool catalogs (specs/ai.md §3.10): which tools a host has (membership), and which of them the
+ * model is offered and may call right now (advertisement and the gate).
+ *
+ * @module @jxsuite/ai/catalog
+ * @license MIT
+ */
+
+import { isFunction } from "@jxsuite/schema/guards";
+import { createToolRegistry, toolError } from "../tools.ts";
+import type {
+  ToolAnnotations,
+  ToolArguments,
+  ToolContext,
+  ToolDefinition,
+  ToolRegistry,
+} from "../tools.ts";
+
+/** What a tool's name may be: what every provider and MCP accept. */
+export const TOOL_NAME_PATTERN = /^[a-zA-Z0-9_-]{1,64}$/;
+
+/** A catalog member: a tool definition with the title and the hints a catalog requires. */
+export type CatalogEntry = ToolDefinition & {
+  readonly title: string;
+  readonly annotations: ToolAnnotations;
+};
+
+/** A host's tools, each name once, in the order they were given. */
+export interface Catalog {
+  readonly entries: readonly CatalogEntry[];
+  /** The member named `name`. */
+  readonly get: (name: string) => CatalogEntry | undefined;
+}
+
+/** Why a catalog refused a tool. */
+export class CatalogError extends Error {
+  /**
+   * `name`: the name is not {@link TOOL_NAME_PATTERN}. `duplicate`: two tools share it. `schema`:
+   * its parameters are not an object schema. `annotations`: it has no title or no hints.
+   */
+  readonly code: "name" | "duplicate" | "schema" | "annotations";
+
+  constructor(code: CatalogError["code"], message: string) {
+    super(message);
+    this.name = "CatalogError";
+    this.code = code;
+  }
+}
+
+/** The entry, or the reason it cannot be one. */
+function admit(tool: ToolDefinition): CatalogEntry {
+  if (!TOOL_NAME_PATTERN.test(tool.name)) {
+    throw new CatalogError("name", `Tool name "${tool.name}" is not ${TOOL_NAME_PATTERN}.`);
+  }
+  if (tool.parameters.type !== "object") {
+    throw new CatalogError("schema", `Tool "${tool.name}" parameters are not an object schema.`);
+  }
+  const { annotations, title } = tool;
+  if (title === undefined || annotations === undefined) {
+    throw new CatalogError("annotations", `Tool "${tool.name}" has no title or no annotations.`);
+  }
+  return { ...tool, annotations, title };
+}
+
+/**
+ * A catalog of `groups`, in order. Membership is decided here, once: a tool is a member or the
+ * catalog is not built.
+ *
+ * @param {...(readonly ToolDefinition[])} groups
+ * @returns {Catalog}
+ * @throws {CatalogError} For an invalid or duplicate name, a non-object parameter schema, or a
+ *   missing title or annotations
+ */
+export function createCatalog(...groups: readonly (readonly ToolDefinition[])[]): Catalog {
+  const byName = new Map<string, CatalogEntry>();
+  for (const tool of groups.flat()) {
+    if (byName.has(tool.name)) {
+      throw new CatalogError("duplicate", `Tool "${tool.name}" is in the catalog twice.`);
+    }
+    byName.set(tool.name, admit(tool));
+  }
+  const entries = [...byName.values()];
+  return { entries, get: (name) => byName.get(name) };
+}
+
+/**
+ * Whether `entry` may be called with `args` right now: null, or what it requires (the end of the
+ * sentence the model reads, such as `"an open project"`). `args` is null when the question is
+ * whether to offer the tool at all.
+ */
+export type Gate = (entry: CatalogEntry, args: ToolArguments | null) => string | null;
+
+/** How a host sees its catalog this round. */
+export interface CatalogView {
+  /** Refuses a member, at listing and at call time alike. */
+  readonly gate?: Gate;
+  /**
+   * Narrows what the model is offered, without refusing the call: a member it returns false for is
+   * not listed, and a call to it still runs.
+   */
+  readonly advertise?: (entry: CatalogEntry) => boolean;
+}
+
+/** A catalog with the plain registry that validates and runs its members. */
+interface CatalogRun {
+  members: Catalog;
+  runner: ToolRegistry;
+}
+
+/**
+ * The registry a turn reads its tools from: `list()` is the members, `listForLLM()` the members the
+ * view admits, and `execute` refuses a call the gate refuses, naming what it requires. `catalog`
+ * may be a function, read on every call, for a host whose membership follows its own state.
+ *
+ * @param {Catalog | (() => Catalog)} catalog
+ * @param {CatalogView} [view]
+ * @returns {ToolRegistry}
+ */
+export function catalogRegistry(
+  catalog: Catalog | (() => Catalog),
+  { advertise, gate }: CatalogView = {},
+): ToolRegistry {
+  const runners = new WeakMap<Catalog, ToolRegistry>();
+
+  /** The catalog now, and the registry that validates and runs its members. */
+  function current(): CatalogRun {
+    const members = isFunction(catalog) ? catalog() : catalog;
+    let runner = runners.get(members);
+    if (!runner) {
+      runner = createToolRegistry();
+      for (const entry of members.entries) {
+        runner.register(entry);
+      }
+      runners.set(members, runner);
+    }
+    return { members, runner };
+  }
+
+  function offered(entry: CatalogEntry): boolean {
+    return (gate?.(entry, null) ?? null) === null && (advertise?.(entry) ?? true);
+  }
+
+  return {
+    register() {
+      throw new TypeError("A catalog's members are given to createCatalog, not registered.");
+    },
+    list: () => [...current().members.entries],
+    listForLLM() {
+      const { members, runner } = current();
+      const names = new Set(members.entries.filter(offered).map((entry) => entry.name));
+      // The runner's own listing, so the bytes are the ones a plain registry sends.
+      return runner.listForLLM().filter((_tool, at) => names.has(members.entries[at]!.name));
+    },
+    getDefinition: (name) => current().members.get(name),
+    validate: (name, args) => current().runner.validate(name, args),
+    async execute(name: string, args: ToolArguments, ctx?: ToolContext) {
+      const { members, runner } = current();
+      const entry = members.get(name);
+      const requires = entry ? (gate?.(entry, args) ?? null) : null;
+      if (requires !== null) {
+        return toolError(`Tool "${name}" is not available right now — it requires ${requires}.`);
+      }
+      return runner.execute(name, args, ctx);
+    },
+  };
+}

package/src/catalog/index.ts

@@ -0,0 +1,17 @@
+/**
+ * `@jxsuite/ai/catalog`: a host's tools as one catalog (specs/ai.md §3.10). Membership is decided
+ * once, by `createCatalog`, which refuses a duplicate or malformed tool; what the model is offered
+ * each round, and which calls are refused, is the host's view over it. `toMcpTool` and
+ * `toCallToolResult` project members and results into MCP's shapes.
+ *
+ * Worker-safe: the module graph is this directory, `../tools.ts` and `@jxsuite/schema/guards`.
+ *
+ * @module @jxsuite/ai/catalog
+ * @license MIT
+ * @docs extending/embedding/assistant-harness
+ */
+
+export { catalogRegistry, CatalogError, createCatalog, TOOL_NAME_PATTERN } from "./catalog.ts";
+export type { Catalog, CatalogEntry, CatalogView, Gate } from "./catalog.ts";
+export { toCallToolResult, toMcpTool } from "./mcp.ts";
+export type { McpCallToolResult, McpToolJson } from "./mcp.ts";

package/src/catalog/mcp.ts

@@ -0,0 +1,80 @@
+/**
+ * A catalog member as the Model Context Protocol names a tool, and a tool result as MCP returns one
+ * (specs/ai.md §3.10). Pure data: no MCP SDK is imported, so any host can serve them.
+ *
+ * @module @jxsuite/ai/catalog
+ * @license MIT
+ */
+
+import type { Undoability } from "../jx-tools/types.ts";
+import type { JSONSchema, ToolResult } from "../tools.ts";
+import type { CatalogEntry } from "./catalog.ts";
+
+/** A tool as an MCP `tools/list` result names it. */
+export interface McpToolJson {
+  name: string;
+  title: string;
+  description: string;
+  inputSchema: JSONSchema;
+  /** All four, always stated: MCP's defaults are the opposite of a safe guess for some. */
+  annotations: {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+  };
+  _meta: { "com.jxsuite/undoable": Undoability };
+}
+
+/**
+ * `entry` as an MCP tool. `undoable` is the serving host's: whether it can take the tool's writes
+ * back.
+ *
+ * @param {CatalogEntry} entry
+ * @param {{ undoable: Undoability }} facts
+ * @returns {McpToolJson}
+ */
+export function toMcpTool(
+  entry: CatalogEntry,
+  { undoable }: { undoable: Undoability },
+): McpToolJson {
+  const { destructiveHint, idempotentHint, openWorldHint, readOnlyHint } = entry.annotations;
+  return {
+    _meta: { "com.jxsuite/undoable": undoable },
+    annotations: { destructiveHint, idempotentHint, openWorldHint, readOnlyHint },
+    description: entry.description,
+    inputSchema: entry.parameters,
+    name: entry.name,
+    title: entry.title,
+  };
+}
+
+/** An MCP `tools/call` result. */
+export interface McpCallToolResult {
+  content: { type: "text"; text: string }[];
+  isError?: true;
+}
+
+/**
+ * A tool result as MCP returns it: the summary, then the data as JSON, each its own text block; a
+ * failure is its error, flagged. A success with neither is the result itself, as JSON.
+ *
+ * @param {ToolResult} result
+ * @returns {McpCallToolResult}
+ */
+export function toCallToolResult(result: ToolResult): McpCallToolResult {
+  if (!result.success) {
+    return { content: [{ text: result.error ?? "The tool failed.", type: "text" }], isError: true };
+  }
+  const texts: string[] = [];
+  if (result.summary !== undefined) {
+    texts.push(result.summary);
+  }
+  if (result.data !== undefined) {
+    texts.push(JSON.stringify(result.data));
+  }
+  if (texts.length === 0) {
+    texts.push(JSON.stringify(result));
+  }
+  return { content: texts.map((text) => ({ text, type: "text" })) };
+}

package/src/harness/index.ts

@@ -16,10 +16,11 @@
 export { LaneBusyError, createTurnLock } from "./lock.ts";
 export { fromStreamingClient, joinSystem } from "./model.ts";
 export { CHARS_PER_TOKEN, DEFAULT_TURN_POLICY } from "./policy.ts";
-export { runTurn } from "./run.ts";
+export { assistantActorId, runTurn } from "./run.ts";
 
 export type {
   HarnessEvent,
+  InteractionStrategy,
   ModelFn,
   ModelRequest,
   TurnError,

package/src/harness/policy.ts

@@ -5,6 +5,7 @@
  * @license MIT
  */
 
+import { proceedAlways } from "../tools.ts";
 import type { TurnPolicy } from "./types.ts";
 
 /** Average characters per token: the estimate every budget used before providers reported counts. */
@@ -36,4 +37,5 @@ export const DEFAULT_TURN_POLICY: TurnPolicy = {
     );
   },
   emptyText: "The model sent back an empty reply.",
+  approval: proceedAlways,
 };

package/src/harness/run.ts

@@ -35,8 +35,9 @@ import {
   createToolContext,
   invokeTool,
   linkCallSignal,
+  toolError,
 } from "../tools.ts";
-import type { Actor } from "../tools.ts";
+import type { Actor, ToolCall, ToolContext } from "../tools.ts";
 import { LaneBusyError } from "./lock.ts";
 import { joinSystem } from "./model.ts";
 import { DEFAULT_TURN_POLICY } from "./policy.ts";
@@ -136,6 +137,15 @@ function createEventQueue() {
   };
 }
 
+/**
+ * The id a turn's {@link Actor} carries: `assistant:<sessionId|local>:<turnId>`. A host that keys
+ * anything on the actor before the turn starts (Studio's batch lane, specs/ai.md §3.3) builds it
+ * here, so the key it opens cannot drift from the one each call's context will name.
+ */
+export function assistantActorId(sessionId: string | null, turnId: string): string {
+  return `assistant:${sessionId ?? "local"}:${turnId}`;
+}
+
 /**
  * Start one turn. It begins at once and runs to its end whether or not anyone reads its events;
  * `onEvent` hears each one synchronously, in order, before the engine takes its next step.
@@ -182,7 +192,7 @@ export function runTurn(input: TurnInput): TurnRun {
   const session = input.session ?? createSessionFacts();
   const ledger = input.ledger ?? createLedger();
   const sessionId = input.sessionId === undefined ? session.sessionId : input.sessionId;
-  const actorId = `assistant:${sessionId ?? "local"}:${turnId}`;
+  const actorId = assistantActorId(sessionId, turnId);
   const actor: Actor = input.modelInfo
     ? { id: actorId, kind: "assistant", model: input.modelInfo.model, sessionId, turnId }
     : { id: actorId, kind: "assistant", sessionId, turnId };
@@ -217,6 +227,30 @@ export function runTurn(input: TurnInput): TurnRun {
     .slice(answered + 1)
     .some((message) => message.role === "assistant" && !isEmptyAssistant(message));
 
+  const interactions = input.interactions ?? { mode: "none" };
+
+  /**
+   * Invoke one call to its result. A call that needs a person is put to the host's strategy and
+   * invoked again with the answer, so no tool body ever awaits a person (specs/ai.md §3.11).
+   */
+  async function invoke(call: ToolCall, ctx: ToolContext, callSignal: AbortSignal) {
+    let outcome = await invokeTool(input.tools, call, ctx, { approval: policy.approval });
+    while (outcome.status === "needs_input") {
+      if (interactions.mode === "none") {
+        return toolError(`${call.name} needs a person, and none is available here.`);
+      }
+      const { request } = outcome;
+      emit({ type: "interaction_request", callId: call.callId, request });
+      const response = await interactions.resolve(request, {
+        callId: call.callId,
+        signal: callSignal,
+      });
+      emit({ type: "interaction_settled", callId: call.callId, response });
+      outcome = await invokeTool(input.tools, call, ctx, { approval: policy.approval, response });
+    }
+    return outcome.result;
+  }
+
   async function loop(): Promise<TurnOutcome> {
     const appended: ChatMessage[] = [];
     const applied: string[] = [];
@@ -412,11 +446,11 @@ export function runTurn(input: TurnInput): TurnRun {
         });
         let result;
         try {
-          ({ result } = await invokeTool(
-            input.tools,
+          result = await invoke(
             { callId, name: call.name, argumentsText: call.argumentsText },
             ctx,
-          ));
+            link.signal,
+          );
         } finally {
           link.release();
         }

package/src/harness/types.ts

@@ -7,7 +7,16 @@
  * @license MIT
  */
 
-import type { AiWrite, SessionFacts, ToolRegistry, ToolResult, WriteLedger } from "../tools.ts";
+import type {
+  AiWrite,
+  ApprovalPolicy,
+  InteractionRequest,
+  InteractionResponse,
+  SessionFacts,
+  ToolRegistry,
+  ToolResult,
+  WriteLedger,
+} from "../tools.ts";
 import type {
   ChatMessage,
   JsonValue,
@@ -74,8 +83,28 @@ export interface TurnPolicy {
   }) => string;
   /** What a turn that drew nothing says. */
   readonly emptyText: string;
+  /** Whether each call needs the author's approval before it runs. Defaults to `proceedAlways`. */
+  readonly approval: ApprovalPolicy;
 }
 
+/**
+ * How a turn gets a person's answer when a call needs one (specs/ai.md §3.11): `inline` asks the
+ * host and waits on the answer within the turn, and `none` answers that nobody is available.
+ */
+export type InteractionStrategy =
+  | {
+      readonly mode: "inline";
+      /**
+       * The person's answer to `request`. Resolve it when the call's `signal` aborts too, with the
+       * answer a stopped turn gives (for a question, unanswered and not skipped).
+       */
+      readonly resolve: (
+        request: InteractionRequest,
+        at: { readonly callId: string; readonly signal: AbortSignal },
+      ) => Promise<InteractionResponse>;
+    }
+  | { readonly mode: "none" };
+
 /** What a host can do between the engine's steps. */
 export interface TurnHooks {
   /** After a call has settled, before its result is reported. */
@@ -123,6 +152,8 @@ export interface TurnInput {
   readonly now?: () => number;
   readonly policy?: Partial<TurnPolicy>;
   readonly hooks?: TurnHooks;
+  /** How a call that needs a person gets their answer. Defaults to `{ mode: "none" }`. */
+  readonly interactions?: InteractionStrategy;
   /** What the conversation's tools remember across turns. Defaults to a fresh set. */
   readonly session?: SessionFacts;
   /** Where the turn's tools record their writes. Defaults to a fresh ledger. */
@@ -218,6 +249,18 @@ export type HarnessEvent = EventBase &
         readonly name: string;
         readonly interactive: boolean;
       }
+    | {
+        /** The call needs a person before it can run, and the host was asked. */
+        readonly type: "interaction_request";
+        readonly callId: string;
+        readonly request: InteractionRequest;
+      }
+    | {
+        /** The person answered (or the turn's stop answered for them). */
+        readonly type: "interaction_settled";
+        readonly callId: string;
+        readonly response: InteractionResponse;
+      }
     | { readonly type: "tool_progress"; readonly callId: string; readonly progress: JsonValue }
     | { readonly type: "write"; readonly callId: string; readonly write: AiWrite }
     | {