@jxsuite/ai 0.39.3 → 0.39.4

package/README.md

@@ -4,13 +4,13 @@ The provider-agnostic substrate Jx Studio's assistant is built on: a streaming L
 
 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`, the `ChatUsage` type, `STREAM_EVENT_TYPES`, the streaming types, and the prompt-cache hints (below)                                           |
-| `@jxsuite/ai/streaming-client` | `StreamingClient`, `StreamEvent` and its eight members, the three factories and their option types, `STREAM_EVENT_TYPES`, `usageEventFromOpenAI` and its `OpenAIUsage` input type, and the prompt-cache hints                               |
-| `@jxsuite/ai/tools`            | `createToolDefinition`, `createToolRegistry`, `toolSuccess`, `toolError`, the call context (`createToolContext`, `createLedger`, `createSessionFacts`, `linkCallSignal`), and their types                                                   |
-| `@jxsuite/ai/chat-state`       | `createChatState`, `ChatStore`, `ChatUsage`, `Message`, `ToolCallRecord`, `ChatState`, `MessageRole`                                                                                                                                        |
-| `@jxsuite/ai/gateway`          | `createChatHandler`, `modelsResponse`, `normalizeOpenAIStream`, `encodeSse`, `problemResponse`, `extractUpstreamErrorMessage`, the prompt-cache hints, and the `Upstream`, `GatewayRefusal`, `ChatAdmission` and `ChatGatewayOptions` types |
+| Entrypoint                     | Exports                                                                                                                                                                                                                                                                                                                    |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@jxsuite/ai`                  | Barrel: the three factories, `createToolDefinition`, `createToolRegistry`, `createChatState`, the `ChatUsage` type, `STREAM_EVENT_TYPES`, the streaming types, and the prompt-cache hints (below)                                                                                                                          |
+| `@jxsuite/ai/streaming-client` | `StreamingClient`, `StreamEvent` and its eight members, the three factories and their option types, `STREAM_EVENT_TYPES`, `usageEventFromOpenAI` and its `OpenAIUsage` input type, and the prompt-cache hints                                                                                                              |
+| `@jxsuite/ai/tools`            | `createToolDefinition`, `createToolRegistry`, `toolSuccess`, `toolError`, the call context (`createToolContext`, `createLedger`, `createSessionFacts`, `linkCallSignal`), and their types                                                                                                                                  |
+| `@jxsuite/ai/chat-state`       | `createChatState`, `ChatStore`, `ChatUsage`, `ChatState`; the messages it holds are `LiveMessage`, `LiveToolCall` and `Role` from `@jxsuite/ai/messages`, which this subpath also exports under their former names `Message`, `ToolCallRecord` and `MessageRole`                                                           |
+| `@jxsuite/ai/gateway`          | `createChatHandler`, `DEFAULT_UPSTREAM_BASE_URL` (the upstream it targets when none is configured), `modelsResponse`, `normalizeOpenAIStream`, `encodeSse`, `problemResponse`, `extractUpstreamErrorMessage`, the prompt-cache hints, and the `Upstream`, `GatewayRefusal`, `ChatAdmission` and `ChatGatewayOptions` types |
 
 `toolSuccess` / `toolError` are **not** re-exported by the barrel. Import them from `@jxsuite/ai/tools`. Importing the subpaths instead of the root is also what makes the package tree-shakeable.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/ai",
-  "version": "0.39.3",
+  "version": "0.39.4",
   "description": "AI infrastructure for Jx Suite — streaming LLM client abstraction, tool registry, and reactive chat state",
   "license": "MIT",
   "repository": {
@@ -31,11 +31,11 @@
     "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
-    "@jxsuite/protocol": "^2.6.1",
-    "@vue/reactivity": "3.5.43"
+    "@jxsuite/protocol": "^3.0.0",
+    "@vue/reactivity": "3.5.44"
   },
   "devDependencies": {
-    "@cloudflare/workers-types": "^5.20261002.1",
-    "@happy-dom/global-registrator": "^20.14.5"
+    "@cloudflare/workers-types": "^5.20261016.1",
+    "@happy-dom/global-registrator": "^21.0.3"
   }
 }

package/src/chat-state.ts

@@ -14,19 +14,21 @@ 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 { LiveMessage, LiveToolCall, OpenAIMessage } 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 = Role;
-
-/** A transcript message: the v1 shape `@jxsuite/ai/messages` reads (specs/ai.md §2.3). */
-export type Message = LiveMessage;
-
-/** A tool call on a transcript message, carrying the outcome its chip renders. */
-export type ToolCallRecord = LiveToolCall;
+/**
+ * The published `@jxsuite/ai/chat-state` names for the transcript types, kept for existing
+ * importers.
+ */
+export type {
+  LiveMessage as Message,
+  LiveToolCall as ToolCallRecord,
+  Role as MessageRole,
+} from "./messages/types.ts";
 
 /**
  * The provider's own count for the last request, and where in the transcript it was taken.
@@ -57,10 +59,10 @@ export interface ChatUsage {
 }
 
 export interface ChatStore {
-  messages: Message[];
+  messages: LiveMessage[];
   status: ChatState;
   streamingContent: string;
-  pendingToolCalls: ToolCallRecord[];
+  pendingToolCalls: LiveToolCall[];
   error: string | null;
   model: string;
   tokenCount: number;
@@ -126,7 +128,7 @@ export function createChatState(opts: { model?: string } = {}) {
     usage: null,
   });
 
-  let _streamingMessage: Message | null = null;
+  let _streamingMessage: LiveMessage | null = null;
 
   /**
    * Add a user message and prepare for streaming response.
@@ -138,12 +140,12 @@ export function createChatState(opts: { model?: string } = {}) {
       return;
     }
 
-    const userMsg = {
+    const userMsg: LiveMessage = {
       id: uid(),
       role: "user",
       content: text,
       timestamp: Date.now(),
-    } as Message;
+    };
     store.messages.push(userMsg);
 
     beginAssistantTurn();
@@ -172,7 +174,7 @@ export function createChatState(opts: { model?: string } = {}) {
       role: "assistant",
       content: "",
       timestamp: Date.now(),
-    } as Message;
+    };
     store.messages.push(_streamingMessage);
     /*
      * Re-read through the reactive proxy so appendDelta / appendToolCallStart mutations notify
@@ -196,7 +198,7 @@ export function createChatState(opts: { model?: string } = {}) {
       toolCallId,
       content,
       timestamp: Date.now(),
-    } as Message);
+    });
   }
 
   /**
@@ -237,12 +239,12 @@ export function createChatState(opts: { model?: string } = {}) {
     if (store.status !== "streaming") {
       return;
     }
-    const tc = {
+    const tc: LiveToolCall = {
       id,
       name,
       arguments: "",
       result: null,
-    } as ToolCallRecord;
+    };
     store.pendingToolCalls.push(tc);
 
     if (_streamingMessage) {
@@ -423,13 +425,16 @@ export function createChatState(opts: { model?: string } = {}) {
     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 = {
+    const recorded: ChatUsage = {
       ...counts,
       contextTokens,
       lastMessageId: store.messages.at(-1)?.id ?? "",
       messageCount: store.messages.length,
-      ...(extra.systemTokens === undefined ? {} : { systemTokens: extra.systemTokens }),
     };
+    if (extra.systemTokens !== undefined) {
+      recorded.systemTokens = extra.systemTokens;
+    }
+    store.usage = recorded;
     store.tokenCount = contextTokens;
   }
 

package/src/gateway/chat.ts

@@ -11,6 +11,15 @@ import { problemResponse, refusal } from "./problem.ts";
 import { encodeSse, SSE_HEADERS } from "./sse.ts";
 import type { ChatGatewayOptions, GatewayRefusal, Upstream } from "./types.ts";
 
+/**
+ * The upstream a host forwards to when it configures none: OpenAI's own chat-completions API.
+ *
+ * The gateway never applies it itself (which upstream a request may reach is host policy, supplied
+ * through `resolveUpstream`). It lives here so every host that falls back to OpenAI, the dev server
+ * and the assistant's eval runner among them, names the same URL.
+ */
+export const DEFAULT_UPSTREAM_BASE_URL = "https://api.openai.com/v1";
+
 /** The refusal's detail for a body that is not JSON. */
 const INVALID_JSON = "Invalid JSON body";
 
@@ -160,6 +169,10 @@ export function createChatHandler<C extends { readonly signal: AbortSignal }>(
          JSON, as it was when the server read it with Bun's `req.json()`. The default decoder would
          strip it and accept the body; this extraction changes no byte a client receives. */
       const text = new TextDecoder("utf-8", { fatal: false, ignoreBOM: true }).decode(bytes);
+      /* SAFETY: every member of ChatRequestBody is optional and `unknown`, so the type claims only
+         that the parsed value can be destructured; each member is checked (messages, tools) or
+         forwarded as `unknown` (model, systemPrompt) below, and a JSON `null` throws at the
+         destructuring, as the route always has. */
       body = JSON.parse(text) as ChatRequestBody;
     } catch {
       return problemResponse(refusal("invalidRequest", INVALID_JSON));
@@ -192,13 +205,16 @@ export function createChatHandler<C extends { readonly signal: AbortSignal }>(
       context,
     );
 
+    // SAFETY: Array.isArray above proved `messages` is an array; its entries are forwarded unread.
     const upstreamBody: UpstreamBody = {
       model,
       messages: [{ role: "system", content: systemPrompt }, ...(messages as unknown[])],
       stream: true,
       stream_options: { include_usage: true },
     };
-    // The wire has always forwarded `tools` as sent, so a non-array with a length passes through.
+    /* The wire has always forwarded `tools` as sent, so a non-array with a length passes through.
+       SAFETY: only `length` is read, off a truthy value, and that read is total: a value with no
+       numeric `length` yields `undefined` (or its own member), which `> 0` compares as it always has. */
     if (tools && (tools as { length: number }).length > 0) {
       upstreamBody.tools = tools;
       upstreamBody.tool_choice = "auto";

package/src/gateway/index.ts

@@ -23,7 +23,7 @@ export {
   isAiSessionId,
   upstreamCacheHints,
 } from "../cache-hints.ts";
-export { createChatHandler } from "./chat.ts";
+export { createChatHandler, DEFAULT_UPSTREAM_BASE_URL } from "./chat.ts";
 export { modelsResponse } from "./models.ts";
 export { normalizeOpenAIStream } from "./normalize.ts";
 export { problemResponse } from "./problem.ts";

package/src/gateway/normalize.ts

@@ -11,41 +11,10 @@
  */
 
 import { problemDetails } from "@jxsuite/protocol/problems";
-import type { StreamEvent, StreamUsageEvent } from "../streaming-client.ts";
+import type { OpenAIStreamChunk, StreamEvent, StreamUsageEvent } from "../streaming-client.ts";
 import { problemTypeForStatus } from "./problem.ts";
 import { extractUpstreamErrorMessage } from "./upstream-error.ts";
 
-/** A tool-call fragment inside an OpenAI streaming `delta`. */
-interface ToolCallDelta {
-  index: number;
-  id?: string;
-  type?: string;
-  function?: { name?: string; arguments?: string };
-}
-
-/** A single OpenAI chat-completions streaming chunk (the JSON after `data: `). */
-interface OpenAIStreamChunk {
-  choices?: {
-    index?: number;
-    delta?: {
-      content?: string;
-      /** Thinking models' chain-of-thought: DeepSeek and Volcengine spell it this way... */
-      reasoning_content?: string;
-      /** ...and OpenRouter this way. Both carry the same thing. */
-      reasoning?: string;
-      tool_calls?: ToolCallDelta[];
-    };
-    finish_reason?: string | null;
-  }[];
-  /** The count `stream_options.include_usage` asks for, normally a final chunk with no choices. */
-  usage?: {
-    prompt_tokens?: number;
-    completion_tokens?: number;
-    prompt_tokens_details?: { cached_tokens?: number } | null;
-    completion_tokens_details?: { reasoning_tokens?: number } | null;
-  } | null;
-}
-
 /**
  * Normalize an upstream usage object into a `usage` frame, or null when it carries no count. The
  * detail figures are included only when the provider sent them: absent is "not said", not zero.
@@ -54,7 +23,7 @@ interface OpenAIStreamChunk {
  * @returns {StreamUsageEvent | null}
  */
 function usageFrame(usage: OpenAIStreamChunk["usage"]): StreamUsageEvent | null {
-  if (!usage || typeof usage.prompt_tokens !== "number") {
+  if (!usage || !isCount(usage.prompt_tokens)) {
     return null;
   }
   const frame: StreamUsageEvent = {
@@ -63,16 +32,37 @@ function usageFrame(usage: OpenAIStreamChunk["usage"]): StreamUsageEvent | null
     outputTokens: usage.completion_tokens ?? 0,
   };
   const cached = usage.prompt_tokens_details?.cached_tokens;
-  if (typeof cached === "number") {
+  if (isCount(cached)) {
     frame.cachedInputTokens = cached;
   }
   const reasoning = usage.completion_tokens_details?.reasoning_tokens;
-  if (typeof reasoning === "number") {
+  if (isCount(reasoning)) {
     frame.reasoningTokens = reasoning;
   }
   return frame;
 }
 
+/**
+ * True when a usage figure the provider sent is a number. The chunk is upstream JSON, so a figure
+ * its interface calls a number is checked before it is reported.
+ *
+ * @param {unknown} value - A `usage` member, as the provider sent it
+ * @returns {boolean}
+ */
+function isCount(value: unknown): value is number {
+  return typeof value === "number";
+}
+
+/**
+ * True when a chain-of-thought member the provider sent is a string.
+ *
+ * @param {unknown} value - `reasoning_content` or `reasoning`, as the provider sent it
+ * @returns {boolean}
+ */
+function isText(value: unknown): value is string {
+  return typeof value === "string";
+}
+
 /**
  * The stop reasons the stream reports; any other `finish_reason` keeps it reading.
  *
@@ -94,14 +84,31 @@ function stopReasonOf(reason: string | null | undefined): string | null {
  * failed, so nothing can change the status now. `message` stays for the readers that already show
  * it (server.md §4.3).
  *
- * @param {unknown} error - What `fetch` rejected with
+ * @param {unknown} cause - What `fetch` rejected with
+ * @returns {StreamEvent}
+ */
+export function fetchFailureFrame(cause: unknown): StreamEvent {
+  return failureFrame("Network error", cause);
+}
+
+/**
+ * The frame for an exchange that failed: `done: cancelled` for an abort, otherwise an `error` frame
+ * whose `message` is `prefix` and the failure's own message.
+ *
+ * @param {"Network error" | "Stream error"} prefix - Which half of the exchange failed
+ * @param {unknown} cause - What the request or the read rejected with
  * @returns {StreamEvent}
  */
-export function fetchFailureFrame(error: unknown): StreamEvent {
-  if ((error as Error).name === "AbortError") {
+function failureFrame(prefix: "Network error" | "Stream error", cause: unknown): StreamEvent {
+  /* SAFETY: `fetch` and a body reader reject with an Error (a TypeError, or the abort's
+     AbortError DOMException), and the reads below throw only TypeErrors. Only `name` and `message`
+     are read, so a custom non-null abort reason that is not an Error reads both as undefined, as
+     it always has. */
+  const failure = cause as Error;
+  if (failure.name === "AbortError") {
     return { type: "done", stopReason: "cancelled" };
   }
-  const message = `Network error: ${(error as Error).message}`;
+  const message = `${prefix}: ${failure.message}`;
   return { message, problem: problemDetails("upstreamFailure", message), type: "error" };
 }
 
@@ -191,13 +198,8 @@ export async function* normalizeOpenAIStream(response: Response): AsyncGenerator
      `finally` keeps that: the upstream must not outlive the reader it streams to. */
   let settled = false;
   try {
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done) {
-        break;
-      }
-
-      buffer += decoder.decode(value, { stream: true });
+    for (let chunk = await reader.read(); !chunk.done; chunk = await reader.read()) {
+      buffer += decoder.decode(chunk.value, { stream: true });
       const lines = buffer.split("\n");
       buffer = lines.pop() || "";
 
@@ -216,6 +218,10 @@ export async function* normalizeOpenAIStream(response: Response): AsyncGenerator
 
         let parsed: OpenAIStreamChunk;
         try {
+          /* SAFETY: the interface is the provider's wire shape, and this loop only reads it: each
+             member passes optional chaining, a truthiness test or a predicate before it shapes a
+             frame, and a chunk too malformed to read (JSON `null`, a non-iterable `tool_calls`)
+             throws into the catch below, which reports it as a stream error. */
           parsed = JSON.parse(dataStr) as OpenAIStreamChunk;
         } catch {
           continue;
@@ -241,7 +247,7 @@ export async function* normalizeOpenAIStream(response: Response): AsyncGenerator
            request carrying `tools`, so a proxy that swallows these frames makes the NEXT round a
            400 the client cannot repair. */
         const reasoning = delta?.reasoning_content ?? delta?.reasoning;
-        if (typeof reasoning === "string" && reasoning) {
+        if (isText(reasoning) && reasoning) {
           yield { type: "reasoning", content: reasoning };
         }
 
@@ -288,12 +294,7 @@ export async function* normalizeOpenAIStream(response: Response): AsyncGenerator
   } catch (error) {
     settled = true;
     void reader.cancel();
-    if ((error as Error).name === "AbortError") {
-      yield { type: "done", stopReason: "cancelled" };
-      return;
-    }
-    const message = `Stream error: ${(error as Error).message}`;
-    yield { message, problem: problemDetails("upstreamFailure", message), type: "error" };
+    yield failureFrame("Stream error", error);
   } finally {
     if (!settled) {
       void reader.cancel();

package/src/gateway/problem.ts

@@ -8,8 +8,18 @@
 import { PROBLEM_MEDIA_TYPE } from "@jxsuite/protocol/problem";
 import { problemDetails } from "@jxsuite/protocol/problems";
 import type { ProblemTypeName } from "@jxsuite/protocol/problems";
+import type { ProblemDetails } from "@jxsuite/protocol/problem";
 import type { GatewayRefusal } from "./types.ts";
 
+/**
+ * A problem body as an unmigrated client reads it: `error` is the line it shows. The gateway takes
+ * this view only to ask whether that line is already there, which is a writer's question, not a
+ * reader's, so the deprecation on `ProblemDetails.error` does not address it.
+ */
+interface LegacyProblemView {
+  readonly error?: string;
+}
+
 /**
  * A refusal of one declared problem type, answered with that type's own status.
  *
@@ -35,13 +45,15 @@ export function refusal(name: ProblemTypeName, detail: string): GatewayRefusal {
  */
 export function problemResponse(refused: GatewayRefusal): Response {
   const { code, problem, status } = refused;
-  const body = {
-    ...problem,
-    ...(problem.error === undefined && problem.detail !== undefined
-      ? { error: problem.detail }
-      : {}),
-    ...(code === undefined ? {} : { code }),
-  };
+  const body: ProblemDetails = { ...problem };
+  const legacy: LegacyProblemView = problem;
+  if (legacy.error === undefined && problem.detail !== undefined) {
+    // The alias is written untyped, as `problemDetails` writes it, so no reader is taught to use it.
+    Object.assign(body, { error: problem.detail });
+  }
+  if (code !== undefined) {
+    body.code = code;
+  }
   // Response.json would send `application/json`; RFC 9457 §3 is what says this body is a problem.
   return Response.json(body, { headers: { "Content-Type": PROBLEM_MEDIA_TYPE }, status });
 }
@@ -61,20 +73,20 @@ export function problemResponse(refused: GatewayRefusal): Response {
 export function problemTypeForStatus(status: number): ProblemTypeName {
   /* Any other status still becomes SOME type, and which side of 500 it falls on is what decides
      whether the caller is being told it made a mistake or that the upstream did. */
-  return STATUS_TYPES[status] ?? (status >= 500 ? "internalError" : "invalidRequest");
+  return STATUS_TYPES.get(status) ?? (status >= 500 ? "internalError" : "invalidRequest");
 }
 
 /** The statuses the table distinguishes, each onto a type answered with that same status. */
-const STATUS_TYPES: Readonly<Record<number, ProblemTypeName>> = {
-  400: "invalidRequest",
-  401: "unauthorized",
-  403: "forbidden",
-  404: "notFound",
-  405: "methodNotAllowed",
-  409: "conflict",
-  413: "payloadTooLarge",
-  501: "capabilityUnavailable",
-  502: "upstreamFailure",
-  503: "upstreamFailure",
-  504: "upstreamFailure",
-};
+const STATUS_TYPES: ReadonlyMap<number, ProblemTypeName> = new Map<number, ProblemTypeName>([
+  [400, "invalidRequest"],
+  [401, "unauthorized"],
+  [403, "forbidden"],
+  [404, "notFound"],
+  [405, "methodNotAllowed"],
+  [409, "conflict"],
+  [413, "payloadTooLarge"],
+  [501, "capabilityUnavailable"],
+  [502, "upstreamFailure"],
+  [503, "upstreamFailure"],
+  [504, "upstreamFailure"],
+]);

package/src/gateway/sse.ts

@@ -10,11 +10,11 @@ import type { StreamEvent } from "../streaming-client.ts";
  * The headers a chat stream is answered with. `no-cache` because a replayed stream is a different
  * turn, and `keep-alive` because the answer is long-lived by design.
  */
-export const SSE_HEADERS: Readonly<Record<string, string>> = {
+export const SSE_HEADERS = {
   "Content-Type": "text/event-stream",
   "Cache-Control": "no-cache",
   Connection: "keep-alive",
-};
+} as const satisfies Readonly<Record<string, string>>;
 
 /**
  * Frame `events` as a Server-Sent Events body: `data: <JSON>` and a blank line per frame, and

package/src/gateway/upstream-error.ts

@@ -26,29 +26,61 @@ export function extractUpstreamErrorMessage(rawBody: string, fallback: string):
   if (!rawBody) {
     return fallback;
   }
+  let parsed: unknown;
   try {
-    const { error, errors } = JSON.parse(rawBody) as {
-      error?: string | { message?: string };
-      errors?: { code?: number; message?: string }[];
-    };
-    if (typeof error === "string") {
-      return error;
-    }
-    if (error) {
-      const { message } = error;
-      if (message) {
-        return message;
+    parsed = JSON.parse(rawBody);
+  } catch {
+    /* Not JSON: use the raw body. */
+    return rawBody;
+  }
+  // JSON `null`, a primitive or an array carries neither member, so it is the raw body.
+  if (isMemberBag(parsed)) {
+    if ("error" in parsed) {
+      const { error } = parsed;
+      if (isText(error)) {
+        return error;
+      }
+      if (isMemberBag(error) && "message" in error && Boolean(error.message)) {
+        return String(error.message);
       }
     }
-    const [first] = errors ?? [];
-    if (first) {
-      const { message } = first;
-      if (message) {
-        return message;
+    if ("errors" in parsed && isEntryList(parsed.errors)) {
+      const [first] = parsed.errors;
+      if (isMemberBag(first) && "message" in first && Boolean(first.message)) {
+        return String(first.message);
       }
     }
-  } catch {
-    /* Not JSON: use the raw body. */
   }
   return rawBody;
 }
+
+/**
+ * True when a parsed body is a string, empty or not: a flat `error` string is the answer as sent.
+ *
+ * @param {unknown} value - A member of the parsed body
+ * @returns {boolean}
+ */
+function isText(value: unknown): value is string {
+  return typeof value === "string";
+}
+
+/**
+ * True when a parsed `errors` member is an array, whose first entry is Cloudflare's sentence.
+ *
+ * @param {unknown} value - The parsed body's `errors` member
+ * @returns {boolean}
+ */
+function isEntryList(value: unknown): value is readonly unknown[] {
+  return Array.isArray(value);
+}
+
+/**
+ * True when a parsed value is a JSON object (or array) whose members may be probed with `in`; false
+ * for `null` and every primitive.
+ *
+ * @param {unknown} value - The parsed body, or one of its members
+ * @returns {boolean}
+ */
+function isMemberBag(value: unknown): value is object {
+  return typeof value === "object" && value !== null;
+}

package/src/harness/index.ts

@@ -15,7 +15,7 @@
 
 export { LaneBusyError, createTurnLock } from "./lock.ts";
 export { fromStreamingClient, joinSystem } from "./model.ts";
-export { DEFAULT_TURN_POLICY } from "./policy.ts";
+export { CHARS_PER_TOKEN, DEFAULT_TURN_POLICY } from "./policy.ts";
 export { runTurn } from "./run.ts";
 
 export type {

package/src/harness/policy.ts

@@ -8,7 +8,7 @@
 import type { TurnPolicy } from "./types.ts";
 
 /** Average characters per token: the estimate every budget used before providers reported counts. */
-const CHARS_PER_TOKEN = 4;
+export const CHARS_PER_TOKEN = 4;
 
 /**
  * The defaults: five rounds of work, twenty-five rounds in all, and the texts the agent loop has