@juno-ai/bind 9.0.0 → 10.0.0

package/testing/index.js

@@ -0,0 +1,188 @@
+import { toolResultMessage } from "../plugins/tool-message.js";
+/**
+ * A sink that records what it was handed. `retractable` is the whole decision
+ * the text stream turns on, so it is the one required argument.
+ */
+export function recordingSink(retractable) {
+    const events = [];
+    return {
+        retractable,
+        events,
+        emit(event) {
+            events.push(event);
+        },
+    };
+}
+export function freshState(overrides = {}) {
+    return {
+        messages: [
+            { role: "system", content: "sys" },
+            { role: "user", content: "do the thing" },
+        ],
+        inputTokens: 0,
+        outputTokens: 0,
+        costCents: 0,
+        lastPromptTokens: 0,
+        lastOutputTokens: 0,
+        hasFreshTokenCount: false,
+        toolCalls: 0,
+        ...overrides,
+    };
+}
+/** An assistant message, with tool calls when given names. */
+export function assistant(content, toolCalls) {
+    return {
+        role: "assistant",
+        content,
+        refusal: null,
+        ...(toolCalls === undefined
+            ? {}
+            : {
+                tool_calls: toolCalls.map((tc) => ({
+                    id: tc.id,
+                    type: "function",
+                    function: { name: tc.name, arguments: tc.args ?? "{}" },
+                })),
+            }),
+    };
+}
+/**
+ * A successful tool result, encoded exactly as production encodes one.
+ *
+ * Routed through `toolResultMessage` rather than a bare `JSON.stringify` so a
+ * fixture-built transcript has the same shape a real run produces. A fixture
+ * that invents its own envelope reintroduces the "two formats in one
+ * transcript" problem that encoder exists to remove, and any test asserting on
+ * transcript shape would be pinning something production never emits.
+ * (`tool-message` is type-only internally, so this pulls no zod into
+ * `@juno-ai/bind/testing`.)
+ */
+export function toolOutcome(id, data = { ok: true }) {
+    return { toolMessage: toolResultMessage(id, { success: true, data }) };
+}
+/**
+ * Declare one tool call. `args` is serialized for you; pass a string to
+ * script malformed JSON on purpose (which is a case worth testing — models
+ * emit it).
+ */
+export function toolCall(name, args = {}, id = name) {
+    return {
+        id,
+        name,
+        args: typeof args === "string" ? args : JSON.stringify(args),
+    };
+}
+/** A turn where the model asks for tools, optionally alongside some text. */
+export function toolCallTurn(calls, opts = {}) {
+    return { ...opts, message: assistant(opts.content ?? null, calls) };
+}
+/**
+ * A turn with text and no tool calls — which is how the loop *ends*. A script
+ * that omits it runs to `maxIterations` (or exhausts the queue), so this is
+ * the difference between testing `stopReason: "done"` and testing
+ * `"iteration_limit"`.
+ */
+export function finalAnswer(content, opts = {}) {
+    return { ...opts, message: assistant(content) };
+}
+/**
+ * Turn a script into a `callModel` implementation.
+ *
+ * Exhausting the queue throws rather than looping forever or returning an
+ * empty turn: a script that ran out is a test that did not describe what it
+ * meant to, and the loop's own `maxIterations` cutoff would otherwise absorb
+ * the mistake and report a plausible-looking `iteration_limit`.
+ */
+export function scriptedModel(turns) {
+    const seenIds = new Set();
+    for (const turn of turns) {
+        for (const tc of turn.message.tool_calls ?? []) {
+            if (seenIds.has(tc.id)) {
+                throw new Error(`scriptedModel: duplicate tool-call id ${JSON.stringify(tc.id)}. ` +
+                    `Ids must be unique across the whole script — pass an explicit id ` +
+                    `to toolCall() when the same tool is called more than once.`);
+            }
+            seenIds.add(tc.id);
+        }
+    }
+    const queue = [...turns];
+    return async () => {
+        const next = queue.shift();
+        if (next === undefined) {
+            throw new Error(`scriptedModel: the script has ${turns.length} turn(s) and was already ` +
+                `exhausted on call ${turns.length + 1}. Add a turn, or end the script ` +
+                `with finalAnswer() so the loop stops.`);
+        }
+        return {
+            message: next.message,
+            inputTokens: next.inputTokens ?? 10,
+            outputTokens: next.outputTokens ?? 5,
+            costCents: next.costCents ?? 1,
+            // Present-only: an absent key and an explicit `null` both mean "not
+            // reported", and the loop treats them identically.
+            ...(next.cachedInputTokens === undefined
+                ? {}
+                : { cachedInputTokens: next.cachedInputTokens }),
+        };
+    };
+}
+/**
+ * A loop wired to a scripted model queue. `runToolCall` records dispatch and
+ * completion separately, so a test can tell "the loop asked for this call" from
+ * "this call's side effect happened" — the distinction every deadline and
+ * cancellation question turns on.
+ *
+ * Everything is overridable: pass `{ runToolCall }` to make a tool fail,
+ * `{ signal }` to abort mid-batch, `{ now }` to make timings deterministic.
+ */
+export function loopHarness(responses, overrides = {}) {
+    const state = overrides.state ?? freshState();
+    const ran = [];
+    const sideEffects = [];
+    const runTool = overrides.runToolCall ??
+        (async (tc) => {
+            sideEffects.push(tc.id);
+            return toolOutcome(tc.id);
+        });
+    const params = {
+        state,
+        maxIterations: 10,
+        callModel: scriptedModel(responses),
+        buildTools: () => [],
+        ...overrides,
+        // Wrapped AFTER the spread, so `ran` is recorded even when a caller
+        // overrides `runToolCall` — which is the documented way to reach the
+        // interesting states. Recording dispatch is the whole reason this harness
+        // exists, and making it the override's job to remember meant the first
+        // test to forget silently lost the distinction it was written to check.
+        runToolCall: async (tc) => {
+            ran.push(tc.id);
+            return await runTool(tc);
+        },
+    };
+    return { params, state, ran, sideEffects };
+}
+/**
+ * A clock that advances a fixed amount on every read. Makes the model-time and
+ * tool-time figures in `ToolLoopResult.stats` exactly predictable, which
+ * `Date.now` cannot be.
+ */
+export function steppingClock(stepMs = 1, startMs = 0) {
+    let current = startMs;
+    return () => {
+        const value = current;
+        current += stepMs;
+        return value;
+    };
+}
+/**
+ * Resolve after `ms` of real time. Kept tiny so suites stay fast.
+ *
+ * Deliberately not cancellable — it is for driving the loop's own micro-timers
+ * inside a test, not for long-lived waiting. Reach for your own scheduler if
+ * you need a wait that outlives the run, so a torn-down run cannot leave a
+ * timer resolving into nothing.
+ */
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/tools/control-chars.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The character set stripped from any untrusted text the harness interpolates
+ * into a message a model, a log, or a person will read.
+ *
+ * One definition, two call sites with different needs — a run interrupt's user
+ * id (removed outright, so it cannot forge lines in the `[Interrupt from user
+ * ...]` header) and a tool-argument path or name quoted back in a validation
+ * failure (replaced with a space, so adjacent tokens stay separated, and
+ * truncated). The *replacement* is the caller's choice; the *set* must not be,
+ * because it is the security decision. Two copies means a future addition —
+ * bidi overrides, say — lands in one and is forgotten in the other.
+ *
+ * Deliberately dependency-free: `@juno-ai/bind/loop` uses it, and that
+ * subpath's module graph is kept free of runtime `zod`.
+ */
+/**
+ * Remove control characters from `text`, optionally bounding its length.
+ *
+ * @param replacement what each stripped character becomes — `""` to delete it,
+ *   `" "` to keep surrounding words apart.
+ * @param maxLength truncate the result to at most this many characters.
+ */
+export declare function stripControlChars(text: string, replacement?: string, maxLength?: number): string;

package/tools/control-chars.js

@@ -0,0 +1,35 @@
+/**
+ * The character set stripped from any untrusted text the harness interpolates
+ * into a message a model, a log, or a person will read.
+ *
+ * One definition, two call sites with different needs — a run interrupt's user
+ * id (removed outright, so it cannot forge lines in the `[Interrupt from user
+ * ...]` header) and a tool-argument path or name quoted back in a validation
+ * failure (replaced with a space, so adjacent tokens stay separated, and
+ * truncated). The *replacement* is the caller's choice; the *set* must not be,
+ * because it is the security decision. Two copies means a future addition —
+ * bidi overrides, say — lands in one and is forgotten in the other.
+ *
+ * Deliberately dependency-free: `@juno-ai/bind/loop` uses it, and that
+ * subpath's module graph is kept free of runtime `zod`.
+ */
+/**
+ * C0 controls, DEL, C1 controls, and the Unicode line/paragraph separators.
+ *
+ * Module-private because it carries the `g` flag and is therefore stateful
+ * under `.test()` / `.exec()`. `String.replace` resets `lastIndex` itself, so
+ * routing every caller through {@link stripControlChars} keeps that hazard in
+ * one place.
+ */
+const CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g;
+/**
+ * Remove control characters from `text`, optionally bounding its length.
+ *
+ * @param replacement what each stripped character becomes — `""` to delete it,
+ *   `" "` to keep surrounding words apart.
+ * @param maxLength truncate the result to at most this many characters.
+ */
+export function stripControlChars(text, replacement = "", maxLength) {
+    const stripped = text.replace(CONTROL_CHARS, replacement);
+    return maxLength === undefined ? stripped : stripped.slice(0, maxLength);
+}