@jxsuite/ai 0.39.1 → 0.39.3

package/src/harness/types.ts

@@ -0,0 +1,253 @@
+/**
+ * Types.ts — the turn engine's contract: what a host hands `runTurn`, and what it hears back.
+ *
+ * Type-only. `@jxsuite/ai/harness` re-exports all of it; the engine lives in `run.ts`.
+ *
+ * @module @jxsuite/ai/harness
+ * @license MIT
+ */
+
+import type { AiWrite, SessionFacts, ToolRegistry, ToolResult, WriteLedger } from "../tools.ts";
+import type {
+  ChatMessage,
+  JsonValue,
+  ProviderFamily,
+  SystemBlock,
+  ToolSpec,
+} from "../messages/types.ts";
+import type { StreamEvent, StreamUsageEvent } from "../streaming-client.ts";
+
+/** What one round asks the model. */
+export interface ModelRequest {
+  /** Fixed for the whole turn. */
+  readonly system: readonly SystemBlock[];
+  /** The conversation so far, this turn's own messages included. */
+  readonly messages: readonly ChatMessage[];
+  readonly tools: readonly ToolSpec[];
+}
+
+/** Streams one round's answer. Called exactly once per round. */
+export type ModelFn = (request: ModelRequest, signal: AbortSignal) => AsyncIterable<StreamEvent>;
+
+/** A provider's token count for one request. */
+export type Usage = Omit<StreamUsageEvent, "type">;
+
+/** Why a turn failed. */
+export interface TurnError {
+  readonly message: string;
+  readonly code?: string;
+}
+
+/**
+ * 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.
+ * - `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
+ *   was drawn either.
+ */
+export type TurnOutcomeKind =
+  | "complete"
+  | "cap_partial"
+  | "cap_failed"
+  | "error"
+  | "cancelled"
+  | "empty";
+
+/** 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;
+  /** 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. */
+  readonly capText: (cap: {
+    readonly maxWorkRounds: number;
+    readonly applied: readonly string[];
+    readonly errors: readonly string[];
+  }) => string;
+  /** What a turn that drew nothing says. */
+  readonly emptyText: string;
+}
+
+/** What a host can do between the engine's steps. */
+export interface TurnHooks {
+  /** After a call has settled, before its result is reported. */
+  afterTool?: (call: {
+    readonly callId: string;
+    readonly name: string;
+    readonly result: ToolResult;
+  }) => void;
+  /** When a round ends on the provider's error frame, before `round_end` reports it. */
+  onStreamError?: (error: TurnError) => void;
+}
+
+/** One turn at a time per lane: acquiring a held lock answers null. */
+export interface TurnLock {
+  /** The release function, or null when another turn holds the lock. */
+  acquire: (turnId: string) => (() => void) | null;
+  /** The turn holding the lock, or null. */
+  readonly active: string | null;
+}
+
+/** Everything one turn runs with. */
+export interface TurnInput {
+  /**
+   * The conversation before this turn's reply: it ends with the message the turn answers. The turn
+   * repairs its tool-call pairing before the first request (`transcript_repaired`).
+   */
+  readonly history: readonly ChatMessage[];
+  /** Fixed for the turn. */
+  readonly system: readonly SystemBlock[];
+  readonly model: ModelFn;
+  /** Who answers: named in each call's actor. */
+  readonly modelInfo?: { readonly family: ProviderFamily; readonly model: string };
+  readonly tools: ToolRegistry;
+  /** Stops the turn when it aborts, with its reason. */
+  readonly signal?: AbortSignal;
+  /** Defaults to a fresh message id. */
+  readonly turnId?: string;
+  /** Defaults to the session facts' own id. */
+  readonly sessionId?: string | null;
+  /** The id of round one's message, for a host that has already put a placeholder on screen. */
+  readonly firstMessageId?: string;
+  /** Mints the ids of the messages the turn adds. Defaults to chat-state's scheme and counter. */
+  readonly newId?: () => string;
+  /** The clock messages are stamped with. Defaults to `Date.now`. */
+  readonly now?: () => number;
+  readonly policy?: Partial<TurnPolicy>;
+  readonly hooks?: TurnHooks;
+  /** 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. */
+  readonly ledger?: WriteLedger;
+  /** Held for the whole turn; a turn started on a held lock throws `LaneBusyError`. */
+  readonly lock?: TurnLock;
+  /**
+   * Called with every event, synchronously and in order, before the engine takes its next step. A
+   * host that keeps its own transcript applies each event here.
+   */
+  readonly onEvent?: (event: HarnessEvent) => void;
+}
+
+/** A turn in flight. Iterate it for its events, or await `outcome`. */
+export interface TurnRun extends AsyncIterable<HarnessEvent> {
+  readonly turnId: string;
+  /** The turn's own signal: armed before `runTurn` returns, aborted by `cancel` or `input.signal`. */
+  readonly signal: AbortSignal;
+  cancel: (reason?: "user" | "superseded" | "shutdown") => void;
+  /**
+   * Rejects when something the host supplied throws (the model function, the registry's listing, a
+   * hook, `onEvent`); a provider failure is an `error` outcome.
+   */
+  readonly outcome: Promise<TurnOutcome>;
+}
+
+/** Every event carries the version, its place in the turn, and the turn. */
+interface EventBase {
+  readonly v: 1;
+  /** Strictly increasing from 0 within a turn. */
+  readonly seq: number;
+  readonly turnId: string;
+}
+
+/** What a turn reports as it runs, in the order it happens. */
+export type HarnessEvent = EventBase &
+  (
+    | { readonly type: "turn_start" }
+    | {
+        /**
+         * The history broke a tool call's pairing with its reply, and the turn repaired it before
+         * its first request (`repairToolPairs`, specs/ai.md §3.4). Heard right after `turn_start`,
+         * and only when the repair changed something. Each list is in transcript order: the calls
+         * given a seal, and the ids of the `tool` messages dropped and moved.
+         */
+        readonly type: "transcript_repaired";
+        readonly sealed: readonly string[];
+        readonly dropped: readonly string[];
+        readonly moved: readonly string[];
+      }
+    | {
+        readonly type: "round_start";
+        readonly round: number;
+        readonly workRounds: number;
+        readonly messageId: string;
+      }
+    | { readonly type: "text"; readonly messageId: string; readonly text: string }
+    | { readonly type: "reasoning"; readonly messageId: string; readonly text: string }
+    | {
+        readonly type: "tool_call_start";
+        readonly messageId: string;
+        readonly callId: string;
+        readonly name: string;
+      }
+    | {
+        readonly type: "tool_call_delta";
+        readonly messageId: string;
+        readonly callId: string;
+        readonly args: string;
+      }
+    | { readonly type: "tool_call_end"; readonly messageId: string; readonly callId: string }
+    | {
+        readonly type: "usage";
+        readonly messageId: string;
+        /** The provider's count exactly as the stream reported it. */
+        readonly frame: StreamUsageEvent;
+        /** The system prompt's estimate, so a later budget can add what it grew by since. */
+        readonly systemTokens: number;
+      }
+    | {
+        readonly type: "round_end";
+        readonly messageId: string;
+        readonly stopReason: string;
+        /** The stream ended with no `done` frame. */
+        readonly truncated: boolean;
+        /** The round's message is gone: it failed, or the turn drew nothing. */
+        readonly dropped: boolean;
+        readonly error?: TurnError;
+      }
+    | {
+        readonly type: "tool_start";
+        readonly callId: string;
+        readonly name: string;
+        readonly interactive: boolean;
+      }
+    | { readonly type: "tool_progress"; readonly callId: string; readonly progress: JsonValue }
+    | { readonly type: "write"; readonly callId: string; readonly write: AiWrite }
+    | {
+        readonly type: "tool_result";
+        readonly callId: string;
+        /** The assistant message that made the call. */
+        readonly messageId: string;
+        /** The `tool` message the result was appended as. */
+        readonly toolMessageId: string;
+        readonly result: ToolResult;
+      }
+    | { readonly type: "turn_end"; readonly outcome: TurnOutcome }
+  );
+
+/** How a turn ended, and what it left behind. */
+export interface TurnOutcome {
+  readonly kind: TurnOutcomeKind;
+  readonly turnId: string;
+  /** The last assistant message of the turn that was drawn, the cap message included. */
+  readonly anchorMessageId: string | null;
+  readonly rounds: number;
+  readonly workRounds: number;
+  readonly writes: readonly AiWrite[];
+  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. */
+  readonly cap?: { readonly messageId: string; readonly text: string };
+  /** For `error` and `empty`: the round message that was dropped. */
+  readonly removedMessageId?: string;
+  /** For `error`, `empty` and `cap_failed`. */
+  readonly error?: TurnError;
+}

package/src/message-id.ts

@@ -0,0 +1,22 @@
+/**
+ * Message-id.ts — the one source of message ids in a process.
+ *
+ * Chat-state stamps every message it creates with `msg_<epoch ms>_<n>`, and the harness mints the
+ * ids of the messages a turn adds in the same scheme. One counter serves both, so an id the harness
+ * minted can never collide with one chat-state minted, and a host can adopt either kind into the
+ * other's transcript.
+ *
+ * @license MIT
+ */
+
+let counter = 0;
+
+/**
+ * The next message id: `msg_<epoch ms>_<n>`, where `n` only ever increases.
+ *
+ * @returns {string}
+ */
+export function nextMessageId(): string {
+  counter += 1;
+  return `msg_${Date.now()}_${counter}`;
+}

package/src/messages/convert.ts

@@ -0,0 +1,216 @@
+/**
+ * Convert.ts — between the v1 transcript and the neutral conversation model.
+ *
+ * Chat-state and every saved session hold {@link LiveMessage}s, the v1 shape. A {@link ChatMessage}
+ * describes the same message as blocks. The conversion keeps every field a message's role uses
+ * except a tool call's `result`, which is the chip's copy of an outcome the `tool` reply already
+ * carries; a host that renders chips rebuilds it from the reply.
+ *
+ * @module @jxsuite/ai/messages
+ * @license MIT
+ */
+
+import type {
+  Block,
+  ChatMessage,
+  LiveMessage,
+  LiveToolCall,
+  ToolCallBlock,
+  ToolResultBlock,
+  WireMessage,
+} from "./types.ts";
+
+/** Whether a tool reply's content is a result that failed. Unparseable content is not. */
+function isErrorContent(content: string): boolean {
+  try {
+    const parsed = JSON.parse(content) as unknown;
+    return (
+      typeof parsed === "object" &&
+      parsed !== null &&
+      (parsed as { success?: unknown }).success === false
+    );
+  } catch {
+    return false;
+  }
+}
+
+/** A v1 value read as text: a string is itself, and anything else is absent. */
+function asText(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+/**
+ * The blocks a message's v1 fields describe, in the order a provider streams them.
+ *
+ * A saved session is restored without being checked, so a field can hold anything. A value of the
+ * wrong type is read as absent rather than turned into text or allowed to throw: a corrupt message
+ * is sent without its garbage, and never stops the send.
+ */
+function blocksFromFields(message: LiveMessage): Block[] {
+  if (message.role === "tool") {
+    const content = asText(message.content);
+    return [
+      {
+        type: "tool_result",
+        callId: asText(message.toolCallId),
+        isError: isErrorContent(content),
+        content,
+      },
+    ];
+  }
+  const blocks: Block[] = [];
+  if (message.role === "assistant" && typeof message.reasoningContent === "string") {
+    blocks.push({ type: "reasoning", text: message.reasoningContent });
+  }
+  if (asText(message.content)) {
+    blocks.push({ type: "text", text: message.content });
+  }
+  if (message.role === "assistant" && Array.isArray(message.toolCalls)) {
+    for (const call of message.toolCalls as unknown[]) {
+      if (typeof call !== "object" || call === null) {
+        continue;
+      }
+      const { id, name, arguments: args } = call as Record<string, unknown>;
+      blocks.push({
+        type: "tool_call",
+        id: asText(id),
+        name: asText(name),
+        argumentsText: asText(args),
+      });
+    }
+  }
+  return blocks;
+}
+
+/** Whether two JSON values are equal, member order aside. */
+function sameJson(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) {
+    return true;
+  }
+  if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) {
+    return false;
+  }
+  if (Array.isArray(a) || Array.isArray(b)) {
+    return (
+      Array.isArray(a) &&
+      Array.isArray(b) &&
+      a.length === b.length &&
+      a.every((item, i) => sameJson(item, b[i]))
+    );
+  }
+  const left = Object.entries(a).filter(([, value]) => value !== undefined);
+  const right = Object.entries(b).filter(([, value]) => value !== undefined);
+  return (
+    left.length === right.length &&
+    left.every(([key, value]) => sameJson(value, (b as Record<string, unknown>)[key]))
+  );
+}
+
+/** The concatenated text of a message's blocks of one kind. */
+function joined(blocks: readonly Block[], type: "text" | "reasoning"): string {
+  let text = "";
+  for (const block of blocks) {
+    if (block.type === type) {
+      text += block.text;
+    }
+  }
+  return text;
+}
+
+/**
+ * Whether a message is an assistant turn carrying neither text nor a tool call.
+ *
+ * Such a turn is never sent (specs/ai.md §2.2): the one that always exists is the placeholder a
+ * turn opens with, which is the answer the request carrying it would generate. A message's blocks
+ * decide when it has them; a v1 message is read by its fields, as {@link toChatMessages} reads them.
+ *
+ * @param {ChatMessage | LiveMessage} message
+ * @returns {boolean}
+ */
+export function isEmptyAssistant(message: ChatMessage | LiveMessage): boolean {
+  if (message.role !== "assistant") {
+    return false;
+  }
+  const blocks = message.blocks ?? blocksFromFields(message as LiveMessage);
+  return !blocks.some(
+    (block) => block.type === "tool_call" || (block.type === "text" && block.text !== ""),
+  );
+}
+
+/**
+ * The neutral form of a v1 transcript. A message that carries `blocks` keeps them; any other is
+ * read from its fields. Fields a v1 message does not declare are not carried.
+ *
+ * @param {readonly LiveMessage[]} live
+ * @returns {ChatMessage[]}
+ */
+export function toChatMessages(live: readonly LiveMessage[]): ChatMessage[] {
+  return live.map((message) => ({
+    id: message.id,
+    role: message.role,
+    blocks: message.blocks ? [...message.blocks] : blocksFromFields(message),
+    timestamp: message.timestamp,
+    ...(message.meta ? { meta: message.meta } : {}),
+  }));
+}
+
+/**
+ * The v1 form of a neutral transcript: every v1 field rebuilt from the blocks, and the blocks kept
+ * beside them only when those fields cannot describe them. A tool call carries no `result`.
+ *
+ * @param {readonly ChatMessage[]} messages
+ * @returns {LiveMessage[]}
+ */
+export function toLiveMessages(messages: readonly ChatMessage[]): LiveMessage[] {
+  return messages.map((message) => {
+    const live: LiveMessage = {
+      id: message.id,
+      role: message.role,
+      content: joined(message.blocks, "text"),
+      timestamp: message.timestamp,
+    };
+    if (message.role === "tool") {
+      const reply = message.blocks.find(
+        (block): block is ToolResultBlock => block.type === "tool_result",
+      );
+      if (reply) {
+        live.content = reply.content;
+        live.toolCallId = reply.callId;
+      }
+    } else if (message.role === "assistant") {
+      if (message.blocks.some((block) => block.type === "reasoning")) {
+        live.reasoningContent = joined(message.blocks, "reasoning");
+      }
+      const calls = message.blocks.filter(
+        (block): block is ToolCallBlock => block.type === "tool_call",
+      );
+      if (calls.length > 0) {
+        live.toolCalls = calls.map((call): LiveToolCall => ({
+          id: call.id,
+          name: call.name,
+          arguments: call.argumentsText,
+        }));
+      }
+    }
+    if (!sameJson(blocksFromFields(live), message.blocks)) {
+      live.blocks = [...message.blocks];
+    }
+    if (message.meta) {
+      live.meta = message.meta;
+    }
+    return live;
+  });
+}
+
+/**
+ * What a request carries: each message's role and blocks, without the empty assistant turns no
+ * provider is sent (§2.2), and without ids, timestamps or meta.
+ *
+ * @param {readonly ChatMessage[]} messages
+ * @returns {WireMessage[]}
+ */
+export function toWireMessages(messages: readonly ChatMessage[]): WireMessage[] {
+  return messages
+    .filter((message) => !isEmptyAssistant(message))
+    .map((message) => ({ role: message.role, blocks: message.blocks }));
+}

package/src/messages/index.ts

@@ -0,0 +1,47 @@
+/**
+ * `@jxsuite/ai/messages`: the provider-neutral conversation model (specs/ai.md §2.3).
+ *
+ * A conversation is a list of {@link ChatMessage}s, each a list of typed blocks: text, reasoning,
+ * tool calls, tool results, and provider data with no neutral word. Chat-state and saved sessions
+ * keep the v1 shape ({@link LiveMessage}); `toChatMessages` and `toLiveMessages` convert between
+ * the two, and `toOpenAIMessages` is the OpenAI-compatible projection every request is built with.
+ * `repairToolPairs` puts every tool call back beside its reply before a request carries it
+ * (specs/ai.md §3.4).
+ *
+ * Worker-safe: it imports nothing at runtime outside itself (`tests/worker-safety.test.ts`,
+ * `tsconfig.worker.json`).
+ *
+ * @module @jxsuite/ai/messages
+ * @docs extending/embedding/assistant-harness
+ */
+
+export { isEmptyAssistant, toChatMessages, toLiveMessages, toWireMessages } from "./convert.ts";
+export { fromOpenAITools, toOpenAIMessages, toOpenAITools } from "./openai.ts";
+export { SEAL_CUT_OFF, SEAL_RELOADED, isSealContent, repairToolPairs } from "./repair.ts";
+export type { RepairReport } from "./repair.ts";
+
+export type {
+  Block,
+  ChatMessage,
+  JsonArray,
+  JsonObject,
+  JsonValue,
+  LiveMessage,
+  LiveToolCall,
+  MessageKind,
+  MessageMeta,
+  OpaqueBlock,
+  OpenAIMessage,
+  OpenAITool,
+  OpenAIToolCall,
+  Provenance,
+  ProviderFamily,
+  ReasoningBlock,
+  Role,
+  SystemBlock,
+  TextBlock,
+  ToolCallBlock,
+  ToolResultBlock,
+  ToolSpec,
+  WireMessage,
+} from "./types.ts";

package/src/messages/openai.ts

@@ -0,0 +1,160 @@
+/**
+ * Openai.ts — the neutral conversation, and the tools, on the OpenAI chat-completions wire.
+ *
+ * The OpenAI-compatible projection is the one every v1 request was built with
+ * (`createChatState().toMessagesArray()`), stated once so a harness, a gateway and chat-state
+ * cannot each keep a copy that drifts (specs/ai.md §2.2, §2.3).
+ *
+ * @module @jxsuite/ai/messages
+ * @license MIT
+ */
+
+import { isEmptyAssistant } from "./convert.ts";
+import type {
+  ChatMessage,
+  OpenAIMessage,
+  OpenAITool,
+  OpenAIToolCall,
+  ReasoningBlock,
+  ToolSpec,
+} from "./types.ts";
+
+/**
+ * Whether a reasoning block is replayed to an OpenAI-compatible provider: it came from one (its own
+ * provenance, else its message's family, else the v1 default), and it is not redacted. A block
+ * another family signed is that family's to read, and a redacted payload is nobody's text.
+ */
+function replays(block: ReasoningBlock, message: ChatMessage): boolean {
+  const family = block.provenance?.family ?? message.meta?.family ?? "openai-compat";
+  return family === "openai-compat" && block.redacted === undefined;
+}
+
+/**
+ * A conversation as an OpenAI chat-completions `messages` array. The system prompt travels
+ * separately.
+ *
+ * Two things it does NOT do verbatim, both because a transcript is not the wire:
+ *
+ * 1. **An assistant turn carrying neither text nor tool calls is dropped** ({@link isEmptyAssistant}).
+ *    The one that always exists is the placeholder a turn opens with: the message being generated
+ *    by the very request this builds. 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.
+ * 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).
+ *
+ * Assistant `content` is `null` when the turn made calls and wrote nothing; a `tool` message is one
+ * entry per result; any other role is `{ role, content }`, its text byte for byte.
+ *
+ * @param {readonly ChatMessage[]} messages @returns {OpenAIMessage[]}
+ */
+export function toOpenAIMessages(messages: readonly ChatMessage[]): OpenAIMessage[] {
+  const out: OpenAIMessage[] = [];
+  for (const message of messages) {
+    if (message.role === "assistant") {
+      if (isEmptyAssistant(message)) {
+        continue;
+      }
+      let text = "";
+      let reasoning = "";
+      const calls: OpenAIToolCall[] = [];
+      for (const block of message.blocks) {
+        if (block.type === "text") {
+          text += block.text;
+        } else if (block.type === "reasoning" && replays(block, message)) {
+          reasoning += block.text;
+        } else if (block.type === "tool_call") {
+          calls.push({
+            id: block.id,
+            type: "function",
+            function: { name: block.name, arguments: block.argumentsText },
+          });
+        }
+      }
+      const entry: Extract<OpenAIMessage, { role: "assistant" }> = {
+        role: "assistant",
+        content: calls.length > 0 ? text || null : text,
+      };
+      if (reasoning) {
+        entry.reasoning_content = reasoning;
+      }
+      if (calls.length > 0) {
+        entry.tool_calls = calls;
+      }
+      out.push(entry);
+    } else if (message.role === "tool") {
+      for (const block of message.blocks) {
+        if (block.type === "tool_result") {
+          out.push({ role: "tool", tool_call_id: block.callId, content: block.content });
+        }
+      }
+    } else {
+      let text = "";
+      for (const block of message.blocks) {
+        if (block.type === "text") {
+          text += block.text;
+        }
+      }
+      out.push({ role: message.role, content: text });
+    }
+  }
+  return out;
+}
+
+/**
+ * Tools as an OpenAI chat-completions `tools` array, in `ToolRegistry.listForLLM()`'s shape: the
+ * same members in the same order, so the serialized request is byte for byte what it was. A tool's
+ * `title` has no OpenAI field and is not sent.
+ *
+ * @param {readonly ToolSpec[]} tools
+ * @returns {OpenAITool[]}
+ */
+export function toOpenAITools(tools: readonly ToolSpec[]): OpenAITool[] {
+  return tools.map((tool) => ({
+    type: "function",
+    function: {
+      name: tool.name,
+      description: tool.description,
+      parameters: tool.inputSchema,
+      ...(tool.strict === true ? { strict: true as const } : {}),
+    },
+  }));
+}
+
+/**
+ * The tools an OpenAI chat-completions `tools` array describes. Each schema is kept by reference,
+ * so a schema built with live getters still serializes live.
+ *
+ * @param {readonly object[]} tools - `ToolRegistry.listForLLM()`, or any array of that shape
+ * @returns {ToolSpec[]}
+ * @throws {TypeError} When an entry is not a function tool with a name, a description and a schema
+ */
+export function fromOpenAITools(tools: readonly object[]): ToolSpec[] {
+  return tools.map((tool, index) => {
+    const fn = (tool as { type?: unknown; function?: unknown }).function as
+      | { name?: unknown; description?: unknown; parameters?: unknown; strict?: unknown }
+      | undefined;
+    if (
+      (tool as { type?: unknown }).type !== "function" ||
+      typeof fn !== "object" ||
+      fn === null ||
+      typeof fn.name !== "string" ||
+      typeof fn.description !== "string" ||
+      typeof fn.parameters !== "object" ||
+      fn.parameters === null
+    ) {
+      throw new TypeError(
+        `tools[${index}] is not an OpenAI function tool with a name, a description and parameters`,
+      );
+    }
+    return {
+      name: fn.name,
+      description: fn.description,
+      inputSchema: fn.parameters as Readonly<Record<string, unknown>>,
+      ...(fn.strict === true ? { strict: true } : {}),
+    };
+  });
+}