@jxsuite/ai 0.39.2 → 0.39.4

package/src/harness/run.ts

@@ -57,18 +57,33 @@ type EventBody = HarnessEvent extends infer E
     : never
   : never;
 
+/** True when a member name of a usage frame is one of the counts {@link Usage} names. */
+function isUsageField(key: string): key is keyof Usage {
+  return (
+    key === "inputTokens" ||
+    key === "outputTokens" ||
+    key === "cachedInputTokens" ||
+    key === "reasoningTokens"
+  );
+}
+
+/** True when a count a backend's usage frame carries is a number, which the frame does not prove. */
+function isCount(value: unknown): value is number {
+  return typeof value === "number";
+}
+
 /** Two usage counts summed field by field; a field either one reports is reported. */
 function addUsage(total: Usage | null, next: Usage): Usage {
   if (total === null) {
     return { ...next };
   }
-  const sum: Record<string, number> = { ...total };
+  const sum: Usage = { ...total };
   for (const [key, value] of Object.entries(next)) {
-    if (typeof value === "number") {
+    if (isUsageField(key) && isCount(value)) {
       sum[key] = (sum[key] ?? 0) + value;
     }
   }
-  return sum as unknown as Usage;
+  return sum;
 }
 
 /**
@@ -103,7 +118,8 @@ function createEventQueue() {
     },
     async *read(): AsyncGenerator<HarnessEvent> {
       let index = 0;
-      while (true) {
+      // `push` and `close` change what this loop reads from outside it, so it exits from within.
+      for (;;) {
         if (index < events.length) {
           yield events[index]!;
           index += 1;
@@ -154,6 +170,9 @@ export function runTurn(input: TurnInput): TurnRun {
     };
   }
   const { signal } = controller;
+  /* Read through a call: the signal aborts from outside, between awaits, which narrowing on
+     `signal.aborted` cannot see. */
+  const aborted = (): boolean => signal.aborted;
   const settle = () => {
     unlink();
     release();
@@ -163,13 +182,10 @@ 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 actor: Actor = {
-    id: `assistant:${sessionId ?? "local"}:${turnId}`,
-    kind: "assistant",
-    ...(input.modelInfo ? { model: input.modelInfo.model } : {}),
-    sessionId,
-    turnId,
-  };
+  const actorId = `assistant:${sessionId ?? "local"}:${turnId}`;
+  const actor: Actor = input.modelInfo
+    ? { id: actorId, kind: "assistant", model: input.modelInfo.model, sessionId, turnId }
+    : { id: actorId, kind: "assistant", sessionId, turnId };
 
   const queue = createEventQueue();
   let seq = 0;
@@ -181,6 +197,8 @@ export function runTurn(input: TurnInput): TurnRun {
       return;
     }
     ended = body.type === "turn_end";
+    /* SAFETY: EventBody is HarnessEvent with exactly `v`, `seq` and `turnId` omitted, member by
+       member, and this adds those three back, so the result is the member `body` came from. */
     const event = { v: 1, seq, turnId, ...body } as HarnessEvent;
     seq += 1;
     input.onEvent?.(event);
@@ -320,10 +338,9 @@ export function runTurn(input: TurnInput): TurnRun {
 
       const truncated = !sawDone;
       if (errorMessage) {
-        const error: TurnError = {
-          message: errorMessage,
-          ...(errorCode ? { code: errorCode } : {}),
-        };
+        const error: TurnError = errorCode
+          ? { message: errorMessage, code: errorCode }
+          : { message: errorMessage };
         input.hooks?.onStreamError?.(error);
         emit({ type: "round_end", messageId, stopReason, truncated, dropped: true, error });
         return finish("error", { error, removedMessageId: messageId });
@@ -331,7 +348,7 @@ export function runTurn(input: TurnInput): TurnRun {
 
       /* A turn that has drawn nothing by the end of a round with no calls ends here. A stopped
          round is not empty: the author ended it. */
-      const stopped = stopReason === "cancelled" || signal.aborted;
+      const stopped = stopReason === "cancelled" || aborted();
       const drawn = text !== "" || records.length > 0;
       if (calls.size === 0 && !stopped && !drawnBefore && anchor === null && !drawn) {
         emit({ type: "round_end", messageId, stopReason, truncated, dropped: true });
@@ -353,13 +370,15 @@ export function runTurn(input: TurnInput): TurnRun {
         for (const record of records) {
           blocks.push({ type: "tool_call", ...record });
         }
-        appended.push({
+        const drawnMessage: ChatMessage = {
           id: messageId,
           role: "assistant",
           blocks,
           timestamp: now(),
-          ...(truncated ? { meta: { incomplete: "truncated" as const } } : {}),
-        });
+        };
+        appended.push(
+          truncated ? { ...drawnMessage, meta: { incomplete: "truncated" } } : drawnMessage,
+        );
         anchor = messageId;
       }
       if (calls.size === 0 || stopped) {
@@ -368,7 +387,7 @@ export function runTurn(input: TurnInput): TurnRun {
 
       let didWork = false;
       for (const [callId, call] of calls) {
-        if (signal.aborted) {
+        if (aborted()) {
           return finish("cancelled");
         }
         emit({
@@ -437,7 +456,7 @@ export function runTurn(input: TurnInput): TurnRun {
         workRounds += 1;
       }
       // A Stop that landed during the round's last call opens no further round.
-      if (signal.aborted) {
+      if (aborted()) {
         return finish("cancelled");
       }
     }
@@ -459,14 +478,14 @@ export function runTurn(input: TurnInput): TurnRun {
   }
 
   const outcome = loop().finally(settle);
-  outcome.then(
-    () => {
+  void (async () => {
+    try {
+      await outcome;
       queue.close();
-    },
-    (error: unknown) => {
+    } catch (error) {
       queue.close({ error });
-    },
-  );
+    }
+  })();
 
   return {
     turnId,

package/src/index.ts

@@ -32,6 +32,7 @@ export {
 export type { UpstreamCacheHints } from "./cache-hints.js";
 
 export type {
+  AiCredentials,
   AnthropicStreamingClientOptions,
   OpenAIStreamingClientOptions,
   ProxyStreamingClientOptions,

package/src/messages/convert.ts

@@ -20,25 +20,42 @@ import type {
   WireMessage,
 } from "./types.ts";
 
+/**
+ * True when an unchecked value (a v1 field, a `tools` listing's member) is a string. A v1 field
+ * that is anything else is absent (see {@link blocksFromFields}).
+ */
+export function isText(value: unknown): value is string {
+  return typeof value === "string";
+}
+
+/**
+ * A v1 tool call as a restored session may hold it: never checked, so any member may be missing or
+ * hold anything.
+ */
+interface StoredToolCall {
+  readonly id?: unknown;
+  readonly name?: unknown;
+  readonly arguments?: unknown;
+}
+
+/**
+ * True when an unchecked value (a stored tool call, a parsed tool reply, a `tools` listing's
+ * member) is an object whose members may be read; null and every primitive are not.
+ */
+export function isMemberBag(value: unknown): value is object {
+  return typeof value === "object" && value !== null;
+}
+
 /** 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
-    );
+    const parsed: unknown = JSON.parse(content);
+    return isMemberBag(parsed) && "success" in parsed && parsed.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.
  *
@@ -48,46 +65,81 @@ function asText(value: unknown): string {
  */
 function blocksFromFields(message: LiveMessage): Block[] {
   if (message.role === "tool") {
-    const content = asText(message.content);
+    const content = isText(message.content) ? message.content : "";
     return [
       {
         type: "tool_result",
-        callId: asText(message.toolCallId),
+        callId: isText(message.toolCallId) ? message.toolCallId : "",
         isError: isErrorContent(content),
         content,
       },
     ];
   }
   const blocks: Block[] = [];
-  if (message.role === "assistant" && typeof message.reasoningContent === "string") {
+  if (message.role === "assistant" && isText(message.reasoningContent)) {
     blocks.push({ type: "reasoning", text: message.reasoningContent });
   }
-  if (asText(message.content)) {
+  if (isText(message.content) && 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) {
+    // A restored session's calls are unchecked, so each is read as what it may really be.
+    const stored: readonly unknown[] = message.toolCalls;
+    for (const call of stored) {
+      if (!isMemberBag(call)) {
         continue;
       }
-      const { id, name, arguments: args } = call as Record<string, unknown>;
+      // Every member of StoredToolCall is optional and `unknown`, so any object is one.
+      const { id, name, arguments: args }: StoredToolCall = call;
       blocks.push({
         type: "tool_call",
-        id: asText(id),
-        name: asText(name),
-        argumentsText: asText(args),
+        id: isText(id) ? id : "",
+        name: isText(name) ? name : "",
+        argumentsText: isText(args) ? args : "",
       });
     }
   }
   return blocks;
 }
 
+/**
+ * A value {@link sameJson} walks: JSON, in which an object member may also be `undefined` (an
+ * optional member left unset), which counts as absent.
+ */
+type Walked = null | boolean | number | string | Walked[] | WalkedObject;
+
+/** An object {@link sameJson} walks. */
+interface WalkedObject {
+  readonly [member: string]: Walked | undefined;
+}
+
+/** True when a walked value is an array or an object rather than a primitive or `null`. */
+function isComposite(value: Walked | undefined): value is Walked[] | WalkedObject {
+  return typeof value === "object" && value !== null;
+}
+
+/**
+ * A block as the JSON {@link sameJson} walks: a shallow copy, which carries every member (an
+ * undefined one included) and so compares exactly as the block itself would. A reasoning block's
+ * `provenance` is copied too, since it is the one member that is itself an object.
+ *
+ * @param {Block} block
+ * @returns {WalkedObject}
+ */
+function walkedBlock(block: Block): WalkedObject {
+  if (block.type !== "reasoning") {
+    return { ...block };
+  }
+  const { provenance, ...rest } = block;
+  return provenance === undefined ? rest : { ...rest, provenance: { ...provenance } };
+}
+
 /** Whether two JSON values are equal, member order aside. */
-function sameJson(a: unknown, b: unknown): boolean {
+function sameJson(a: Walked | undefined, b: Walked | undefined): boolean {
   if (Object.is(a, b)) {
     return true;
   }
-  if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) {
+  if (!isComposite(a) || !isComposite(b)) {
     return false;
   }
   if (Array.isArray(a) || Array.isArray(b)) {
@@ -100,10 +152,7 @@ function sameJson(a: unknown, b: unknown): boolean {
   }
   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]))
-  );
+  return left.length === right.length && left.every(([key, value]) => sameJson(value, b[key]));
 }
 
 /** The concatenated text of a message's blocks of one kind. */
@@ -131,6 +180,7 @@ export function isEmptyAssistant(message: ChatMessage | LiveMessage): boolean {
   if (message.role !== "assistant") {
     return false;
   }
+  // SAFETY: a ChatMessage always carries `blocks`, so a message without them is a LiveMessage.
   const blocks = message.blocks ?? blocksFromFields(message as LiveMessage);
   return !blocks.some(
     (block) => block.type === "tool_call" || (block.type === "text" && block.text !== ""),
@@ -145,13 +195,12 @@ export function isEmptyAssistant(message: ChatMessage | LiveMessage): boolean {
  * @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 } : {}),
-  }));
+  return live.map((message): ChatMessage => {
+    const { id, role, timestamp, meta } = message;
+    const blocks = message.blocks ? [...message.blocks] : blocksFromFields(message);
+    const chat: ChatMessage = { id, role, blocks, timestamp };
+    return meta ? { ...chat, meta } : chat;
+  });
 }
 
 /**
@@ -192,7 +241,13 @@ export function toLiveMessages(messages: readonly ChatMessage[]): LiveMessage[]
         }));
       }
     }
-    if (!sameJson(blocksFromFields(live), message.blocks)) {
+    const rebuilt = blocksFromFields(live).map((block) => walkedBlock(block));
+    if (
+      !sameJson(
+        rebuilt,
+        message.blocks.map((block) => walkedBlock(block)),
+      )
+    ) {
       live.blocks = [...message.blocks];
     }
     if (message.meta) {
@@ -210,7 +265,7 @@ export function toLiveMessages(messages: readonly ChatMessage[]): LiveMessage[]
  * @returns {WireMessage[]}
  */
 export function toWireMessages(messages: readonly ChatMessage[]): WireMessage[] {
-  return messages
-    .filter((message) => !isEmptyAssistant(message))
-    .map((message) => ({ role: message.role, blocks: message.blocks }));
+  return messages.flatMap((message): WireMessage[] =>
+    isEmptyAssistant(message) ? [] : [{ role: message.role, blocks: message.blocks }],
+  );
 }

package/src/messages/openai.ts

@@ -9,7 +9,8 @@
  * @license MIT
  */
 
-import { isEmptyAssistant } from "./convert.ts";
+import type { JSONSchema } from "../tools.ts";
+import { isEmptyAssistant, isMemberBag, isText } from "./convert.ts";
 import type {
   ChatMessage,
   OpenAIMessage,
@@ -113,15 +114,34 @@ export function toOpenAIMessages(messages: readonly ChatMessage[]): OpenAIMessag
  * @returns {OpenAITool[]}
  */
 export function toOpenAITools(tools: readonly ToolSpec[]): OpenAITool[] {
-  return tools.map((tool) => ({
-    type: "function",
-    function: {
+  return tools.map((tool): OpenAITool => {
+    const fn: OpenAITool["function"] = {
       name: tool.name,
       description: tool.description,
       parameters: tool.inputSchema,
-      ...(tool.strict === true ? { strict: true as const } : {}),
-    },
-  }));
+    };
+    if (tool.strict === true) {
+      fn.strict = true;
+    }
+    return { type: "function", function: fn };
+  });
+}
+
+/**
+ * A `tools` entry as {@link fromOpenAITools} reads it: any object, whose members are checked before
+ * they are used.
+ */
+interface ListedTool {
+  readonly type?: unknown;
+  readonly function?: unknown;
+}
+
+/** A `tools` entry's `function` member, read the same way. */
+interface ListedFunction {
+  readonly name?: unknown;
+  readonly description?: unknown;
+  readonly parameters?: unknown;
+  readonly strict?: unknown;
 }
 
 /**
@@ -133,28 +153,29 @@ export function toOpenAITools(tools: readonly ToolSpec[]): OpenAITool[] {
  * @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;
+  return tools.map((tool, index): ToolSpec => {
+    // Every member of ListedTool and ListedFunction is optional and `unknown`: any object is one.
+    const listed: ListedTool = tool;
+    const fn: ListedFunction | undefined = isMemberBag(listed.function)
+      ? listed.function
+      : 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
+      listed.type !== "function" ||
+      fn === undefined ||
+      !isText(fn.name) ||
+      !isText(fn.description) ||
+      !isMemberBag(fn.parameters)
     ) {
       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 } : {}),
-    };
+    /* SAFETY: `parameters` was just checked to be a non-null object, and it is kept by reference
+       and never read here: it is the schema the listing's registry was given as a JSONSchema. */
+    const inputSchema = fn.parameters as Readonly<JSONSchema>;
+    if (fn.strict === true) {
+      return { name: fn.name, description: fn.description, inputSchema, strict: true };
+    }
+    return { name: fn.name, description: fn.description, inputSchema };
   });
 }

package/src/messages/types.ts

@@ -17,6 +17,7 @@
  */
 
 import type { JsonValue, ToolResult } from "../core-types.ts";
+import type { JSONSchema } from "../tools.ts";
 
 export type { JsonArray, JsonObject, JsonValue } from "../core-types.ts";
 
@@ -167,7 +168,7 @@ export interface ToolSpec {
   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>>;
+  readonly inputSchema: Readonly<JSONSchema>;
   /** OpenAI's strict mode, opted into per tool. */
   readonly strict?: boolean;
 }
@@ -196,7 +197,7 @@ export interface OpenAITool {
   function: {
     name: string;
     description: string;
-    parameters: Readonly<Record<string, unknown>>;
+    parameters: Readonly<JSONSchema>;
     strict?: true;
   };
 }