@juno-ai/bind 9.0.0 → 11.0.0

package/skills/types.js

@@ -0,0 +1,55 @@
+/**
+ * The skill vocabulary — the *knowledge* sibling of `src/plugins/tool.ts`.
+ *
+ * A skill is a markdown-shaped procedure or reference module, disclosed to a
+ * model in three tiers: a one-line catalog entry it always sees (Tier 1), a
+ * body injected into the system prompt once loaded (Tier 2), and bundled
+ * resources it may read after loading (Tier 3). That progression is the whole
+ * point: a workspace's accumulated know-how does not fit in a context window,
+ * and a catalog line costs ~50 tokens where a body costs thousands.
+ *
+ * Two sources of skill exist and they differ in exactly one way — where the
+ * body comes from. A **code skill** is registered from the deployment's own
+ * source (see {@link SkillDef}) and its body is a build artifact; an
+ * **external skill** is data the host stores and can edit at runtime. The
+ * harness owns the first entirely and knows nothing about the second beyond
+ * the shape it resolves to, which is why {@link SkillSummary} is the only type
+ * both sides share.
+ */
+// ---------------------------------------------------------------------------
+// Bounds
+//
+// Every one of these bounds the *prompt*, not a database. They are defaults: a
+// host passes its own where the call takes one. What they must not be is
+// absent — an unbounded catalog and an unbounded active set are the two ways a
+// skill library silently degrades every run in the deployment rather than
+// failing one of them.
+// ---------------------------------------------------------------------------
+/**
+ * Rough token budget for the Tier-1 catalog. Past it the catalog demotes its
+ * overflow to names only rather than dropping entries: a name the model can
+ * still pass to `load_skill` beats a skill it cannot discover at all.
+ */
+export const SKILL_CATALOG_TOKEN_BUDGET = 2500;
+/**
+ * Max skills one session may hold loaded at once. The count half of the active
+ * bound — cheap to check before anything is resolved.
+ */
+export const SKILL_MAX_ACTIVE_PER_SESSION = 12;
+/**
+ * Combined token budget for all loaded bodies. The other half of the active
+ * bound, and the one that actually protects the context window: twelve small
+ * skills are fine and three large ones are not, so a count cap alone does not
+ * bound the prompt.
+ */
+export const SKILL_MAX_ACTIVE_BODY_TOKENS = 40_000;
+/**
+ * Characters per token, for every estimate in this module. Deliberately crude:
+ * these budgets choose between "render the line" and "render the name", and a
+ * real tokenizer would cost more than the decision is worth.
+ */
+export const SKILL_CHARS_PER_TOKEN = 4;
+/** The module's shared estimator. */
+export function estimateSkillTokens(text) {
+    return Math.ceil(text.length / SKILL_CHARS_PER_TOKEN);
+}

package/testing/index.d.ts

@@ -0,0 +1,153 @@
+/**
+ * `@juno-ai/bind/testing` — fixtures for testing an agent against the harness
+ * without a provider, a network, or a credential.
+ *
+ * The loop's hardest behaviour to get right is also the hardest to test: what
+ * happens across several turns, with several tools, when one of them fails or
+ * the run is cut short. Reaching that state normally means mocking a streaming
+ * chat-completions client, which is a lot of scaffolding to write before the
+ * first assertion — so most consumers write it once, badly, and then only test
+ * the happy path.
+ *
+ * These are the fixtures this package's own cross-module suites use, published
+ * so a consumer does not rewrite them. They are ordinary values with no magic:
+ * a scripted model is a queue of prepared turns, and a harness is a
+ * {@link ToolLoopParams} you can override any field of.
+ *
+ * ```ts
+ * import { loopHarness, toolCall, toolCallTurn, finalAnswer } from "@juno-ai/bind/testing";
+ * import { runToolLoop } from "@juno-ai/bind/loop";
+ *
+ * const h = loopHarness([
+ *   toolCallTurn([toolCall("search", { q: "bind" })]),
+ *   finalAnswer("Found it."),
+ * ]);
+ * const { stopReason, stats } = await runToolLoop(h.params);
+ * expect(stopReason).toBe("done");
+ * expect(h.ran).toEqual(["search"]);
+ * ```
+ *
+ * This module ships in the published package rather than living beside the
+ * tests, so it is held to the same portability fences as `src/`: no Node
+ * builtins, no `process`, no framework, peer dependencies only.
+ */
+import type OpenAI from "openai";
+import type { ToolCallOutcome, ToolLoopParams, ToolLoopState } from "../loop/tool-loop.js";
+import type { TurnStreamEvent, TurnStreamSink } from "../completion/text-stream.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 declare function recordingSink(retractable: boolean): TurnStreamSink & {
+    readonly events: TurnStreamEvent[];
+};
+export declare function freshState(overrides?: Partial<ToolLoopState>): ToolLoopState;
+/** An assistant message, with tool calls when given names. */
+export declare function assistant(content: string | null, toolCalls?: ReadonlyArray<{
+    id: string;
+    name: string;
+    args?: string;
+}>): OpenAI.ChatCompletionMessage;
+/**
+ * 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 declare function toolOutcome(id: string, data?: unknown): ToolCallOutcome;
+/** One tool call in a scripted turn. */
+export interface ScriptedToolCall {
+    /** Defaults to the tool name — unique across the whole script, see
+     *  {@link scriptedModel}, which rejects a duplicate rather than letting it
+     *  produce a baffling transcript failure ten frames deep in the loop. */
+    readonly id: string;
+    readonly name: string;
+    readonly args: string;
+}
+/**
+ * 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 declare function toolCall(name: string, args?: unknown, id?: string): ScriptedToolCall;
+/** Per-turn accounting overrides. Defaults are small non-zero numbers so a
+ *  test asserting "usage was recorded" cannot pass on an all-zero fixture. */
+export interface TurnCost {
+    readonly inputTokens?: number;
+    readonly outputTokens?: number;
+    readonly costCents?: number;
+    /**
+     * Provider-reported cached input tokens. Omit it to script a transport that
+     * cannot report one — the run's total then skips this turn rather than
+     * counting a zero, which is the distinction `RunStats.cachedInputTokens`
+     * turns on. Pass `null` for the same effect explicitly.
+     */
+    readonly cachedInputTokens?: number | null;
+}
+/** One scripted model turn: the message to return, plus its usage. */
+export interface ModelResponse extends TurnCost {
+    readonly message: OpenAI.ChatCompletionMessage;
+}
+/** A turn where the model asks for tools, optionally alongside some text. */
+export declare function toolCallTurn(calls: readonly ScriptedToolCall[], opts?: TurnCost & {
+    readonly content?: string;
+}): ModelResponse;
+/**
+ * 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 declare function finalAnswer(content: string, opts?: TurnCost): ModelResponse;
+/**
+ * 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 declare function scriptedModel(turns: readonly ModelResponse[]): NonNullable<ToolLoopParams["callModel"]>;
+export interface LoopHarness {
+    params: ToolLoopParams;
+    state: ToolLoopState;
+    /** Ids the loop dispatched, in order. Recorded for you even if you override
+     *  `runToolCall`. */
+    ran: string[];
+    /** Ids whose tool actually reached its side effect. The default
+     *  `runToolCall` records one here on completion, so `ran` and `sideEffects`
+     *  match until an override makes them diverge — a tool that throws, hangs
+     *  past a deadline, or is torn down mid-flight. That divergence is the
+     *  question every cancellation test is really asking. */
+    sideEffects: string[];
+}
+/**
+ * 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 declare function loopHarness(responses: readonly ModelResponse[], overrides?: Partial<ToolLoopParams>): LoopHarness;
+/**
+ * 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 declare function steppingClock(stepMs?: number, startMs?: number): () => number;
+/**
+ * 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 declare function sleep(ms: number): Promise<void>;

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);
+}