@cubicecho/agent-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benjamin Van Treese
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,53 @@
+# @cubicecho/agent-core
+
+The endpoint-agnostic half of an OpenAI-compatible agent loop.
+
+Extracted from three servers that had each written it separately — `kanban_server`,
+`task_server` and `min-agent` — after the copies drifted far enough that a fix in one was a bug
+still live in another. See [`standards/extraction-backlog.md`](../standards/extraction-backlog.md).
+
+## What is here
+
+| Module | What it does |
+| --- | --- |
+| `schema-compat` | Makes an MCP tool schema something a strict or grammar-constrained server will accept. `sanitizeTools`, `relaxTools`, `isGrammarError`. |
+| `tool-loading` | On-demand tool discovery: a name-only catalogue plus a `load_tools` meta-tool, so a run pays for the schemas it asks for instead of all of them. |
+| `side-task` | One-shot calls that support a run without being one — small prompt, short answer, no tools, never worth failing the run over. |
+| `events` | The in-memory bus a watcher reads while a run happens. |
+| `client` | A pooled `OpenAI` client per endpoint, plus the context-window listing and its cache. |
+| `retry` | What to do when a request is lost, refused or too big: `isTransient`, `backoffMs`, `ContextOverflow`, `EndpointSilent`. |
+| `config` | The structural interfaces every function here asks for. |
+
+What is **not** here is the work: orchestration, prompts, and whatever the run is about. That
+is the caller's, and it is the part that actually differs between one server and the next.
+
+## The config seam
+
+Nothing here imports a config type from a consumer, and no function asks for a whole
+configuration. Each takes the narrowest shape it reads — `Endpoint`, `ModelParams`,
+`ToolPolicy`, `RetryPolicy` — and a caller satisfies it structurally:
+
+```ts
+import { getClient, type Endpoint } from "@cubicecho/agent-core";
+
+// A Drizzle settings row, a resolved agent, or a zod-inferred config: all three already are one.
+const client = getClient(settings satisfies Endpoint);
+```
+
+This matters because the three consumers do not agree on the fields. `task_server`'s settings
+row has no `contextLength`; `min-agent` spells it `contextLimit` and has no timeout or retry
+budget at all. A single god interface would have forced two of them to grow columns they have
+no use for.
+
+## Where the merged behaviour came from
+
+- `schema-compat` — `kanban_server`/`task_server`'s version, which strips **every** sibling of a
+  `$ref` rather than just `default`. `min-agent`'s did the latter, which leaves `nullable` beside
+  the surviving `$ref` on `anyOf: [{$ref}, {type: "null"}]` — the shape a schema-generated server
+  emits at every optional argument — and a strict validator rejects the tool.
+- `tool-loading` — theirs, plus `min-agent`'s `carryOver`/`MAX_CARRIED`, which bounds the tool
+  array across a multi-turn conversation. Both suites' assertions are kept.
+- `events` — `kanban_server`'s `usage` totals **and** `task_server`'s `step` grouping, including
+  its `fold` fix: two blocks in different steps are not one block.
+- `retry` — `kanban_server`'s, which is the only one of the three with the `ContextOverflow`
+  guard. `min-agent` had no retry layer at all.

package/dist/catalog.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The contract between whatever holds the tools and the loop that offers them to a model.
+ *
+ * This lives here rather than with the MCP pool because it is what `tool-loading.ts` reads, and
+ * nothing about it is MCP-specific: it is a list of names and one-line descriptions, grouped by
+ * where they came from. A caller with tools from somewhere else entirely satisfies it by
+ * building the array.
+ */
+/** One server's tools, without their JSON schemas — the cheap half of a tool definition. */
+export interface CatalogServer {
+    id: string;
+    label: string;
+    tools: {
+        name: string;
+        description: string;
+    }[];
+}

package/dist/catalog.js

@@ -0,0 +1,9 @@
+/**
+ * The contract between whatever holds the tools and the loop that offers them to a model.
+ *
+ * This lives here rather than with the MCP pool because it is what `tool-loading.ts` reads, and
+ * nothing about it is MCP-specific: it is a list of names and one-line descriptions, grouped by
+ * where they came from. A caller with tools from somewhere else entirely satisfies it by
+ * building the array.
+ */
+export {};

package/dist/client.d.ts

@@ -0,0 +1,34 @@
+import OpenAI from "openai";
+import type { Endpoint } from "./config.ts";
+/**
+ * The SDK insists on a non-empty key even where the server will not look at it. This is what it
+ * gets. It also reads as "this endpoint has no key" at a call site, which an empty string does
+ * not — a caller must not let a local endpoint silently borrow the key meant for a paid one.
+ */
+export declare const NO_KEY = "agent-core";
+/** Zero or less means no limit, which the SDK spells as `undefined`. */
+export declare const timeoutMs: (config: Pick<Endpoint, "requestTimeoutSeconds">) => number | undefined;
+export declare function getClient(config: Endpoint): OpenAI;
+/** A model an endpoint offers, and what it says the model will read. Zero means it did not say. */
+export interface ModelInfo {
+    id: string;
+    contextLength: number;
+}
+/** Asks an endpoint what it serves, and remembers the answer. */
+export declare function listModels(config: Endpoint): Promise<ModelInfo[]>;
+/**
+ * How much a model will read, in tokens. Zero means nobody knows.
+ *
+ * `declared` is the operator's own number, and it wins outright: an endpoint can report the
+ * window a model was *built* with while serving it in a much smaller one — llama.cpp will
+ * happily load a 256k model at `-c 16384` and go on listing it as 256k — and a run refused on
+ * the honest-looking number is a run that fails at the endpoint instead.
+ *
+ * Otherwise the listing is asked, once per endpoint. A server that will not list models still
+ * has to be able to run a turn: a failure here is an unknown window, not a failed run.
+ */
+export declare function contextLimitFor(config: Endpoint & {
+    model: string;
+}, declared?: number): Promise<number>;
+/** Forgets every cached client and listing. For tests, and for a settings change under test. */
+export declare function resetClients(): void;

package/dist/client.js

@@ -0,0 +1,111 @@
+import OpenAI from "openai";
+/**
+ * The SDK insists on a non-empty key even where the server will not look at it. This is what it
+ * gets. It also reads as "this endpoint has no key" at a call site, which an empty string does
+ * not — a caller must not let a local endpoint silently borrow the key meant for a paid one.
+ */
+export const NO_KEY = "agent-core";
+/** Zero or less means no limit, which the SDK spells as `undefined`. */
+export const timeoutMs = (config) => config.requestTimeoutSeconds > 0 ? config.requestTimeoutSeconds * 1000 : undefined;
+/**
+ * A client per endpoint, made once and kept.
+ *
+ * The SDK holds its own connection pool, and a run makes a request per tool iteration on top of
+ * whatever side tasks it asks for — building a fresh client for each of them throws that pool
+ * away every time. A map rather than the single slot it would otherwise be, because agents each
+ * name their own endpoint: two running side by side on different servers would evict each
+ * other's client on every request.
+ *
+ * `maxRetries: 0` turns the SDK's own retrying off. Streaming is what this is for, and a stream
+ * that has already emitted tokens must not be replayed from the top — the caller knows whether
+ * anything has been produced yet and the SDK does not. See `retry.ts`.
+ */
+const clients = new Map();
+export function getClient(config) {
+    const apiKey = config.apiKey || NO_KEY;
+    const timeout = timeoutMs(config);
+    // Stringified rather than joined on a separator: no character is impossible in a URL or a
+    // key, and two different endpoints must never resolve to the same cached client.
+    const key = JSON.stringify([config.baseUrl, apiKey, timeout]);
+    const existing = clients.get(key);
+    if (existing)
+        return existing;
+    const client = new OpenAI({ baseURL: config.baseUrl, apiKey, timeout, maxRetries: 0 });
+    clients.set(key, client);
+    return client;
+}
+/**
+ * The context window, spelled every way a server spells it.
+ *
+ * None of these is in the OpenAI listing schema, so every server that says anything says it as
+ * an extra key of its own: `context_length` is llama.cpp and LM Studio, `max_model_len` vLLM,
+ * `n_ctx` the raw llama bindings. Whichever turns up first is taken — a server reporting two
+ * of them is reporting the same number twice.
+ */
+const CONTEXT_KEYS = [
+    "context_length",
+    "max_context_window",
+    "max_model_len",
+    "context_window",
+    "n_ctx",
+];
+function contextLengthOf(model) {
+    const record = model;
+    for (const key of CONTEXT_KEYS) {
+        const value = record[key];
+        if (typeof value === "number" && value > 0)
+            return value;
+    }
+    return 0;
+}
+/**
+ * The last listing from each endpoint, so a run can size its window without a round trip.
+ *
+ * Keyed the same way the clients are, because two endpoints are two different sets of models
+ * and one of them having answered says nothing about the other. It is only ever a cache of
+ * something asked for anyway: nothing here refreshes it, and a listing that fails leaves
+ * whatever was there rather than emptying it.
+ */
+const listings = new Map();
+const endpointKey = (config) => JSON.stringify([config.baseUrl, config.apiKey || NO_KEY]);
+/** Asks an endpoint what it serves, and remembers the answer. */
+export async function listModels(config) {
+    const { data } = await getClient(config).models.list();
+    const models = data
+        .map((model) => ({ id: model.id, contextLength: contextLengthOf(model) }))
+        .sort((a, b) => a.id.localeCompare(b.id));
+    listings.set(endpointKey(config), models);
+    return models;
+}
+/**
+ * How much a model will read, in tokens. Zero means nobody knows.
+ *
+ * `declared` is the operator's own number, and it wins outright: an endpoint can report the
+ * window a model was *built* with while serving it in a much smaller one — llama.cpp will
+ * happily load a 256k model at `-c 16384` and go on listing it as 256k — and a run refused on
+ * the honest-looking number is a run that fails at the endpoint instead.
+ *
+ * Otherwise the listing is asked, once per endpoint. A server that will not list models still
+ * has to be able to run a turn: a failure here is an unknown window, not a failed run.
+ */
+export async function contextLimitFor(config, declared = 0) {
+    if (declared > 0)
+        return declared;
+    // A failure is not remembered: an endpoint that was down when the last run started is not an
+    // endpoint with no models, and the one listing this costs is nothing beside the run itself.
+    if (!listings.has(endpointKey(config))) {
+        try {
+            await listModels(config);
+        }
+        catch {
+            return 0;
+        }
+    }
+    const listed = listings.get(endpointKey(config)) ?? [];
+    return listed.find((model) => model.id === config.model)?.contextLength ?? 0;
+}
+/** Forgets every cached client and listing. For tests, and for a settings change under test. */
+export function resetClients() {
+    clients.clear();
+    listings.clear();
+}

package/dist/config.d.ts

@@ -0,0 +1,57 @@
+/**
+ * What this package needs to know about a caller's configuration.
+ *
+ * Deliberately not one interface. The three servers that consume this each hold their settings
+ * in a different shape — a resolved agent row, a settings row read straight from the database,
+ * a zod-inferred config object — and they do not all carry the same fields: `task_server`'s
+ * settings row has no `contextLength`, and `min-agent` spells it `contextLimit` and has no
+ * timeout or retry budget at all.
+ *
+ * So every function here asks for the narrowest thing it actually reads, and a caller satisfies
+ * it structurally. Nothing imports a config *type* from a consumer, and no consumer has to grow
+ * a field it has no use for in order to call `getClient`.
+ */
+/** Where to send a request and how long to wait. Everything that talks to a server needs this. */
+export interface Endpoint {
+    /** Any OpenAI-compatible base URL: OpenAI, Ollama, LM Studio, vLLM, OpenRouter, ... */
+    baseUrl: string;
+    /** Empty is normal — a local server ignores it. See `getClient` for what is sent instead. */
+    apiKey: string;
+    /** Zero or less means no limit. */
+    requestTimeoutSeconds: number;
+}
+/** What to ask the model for. */
+export interface ModelParams {
+    model: string;
+    maxTokens: number;
+    temperature: number;
+}
+/** How tools reach the model, and how long it may keep calling them. */
+export interface ToolPolicy {
+    /**
+     * "eager" sends every tool definition on every request. "ondemand" sends a name-only
+     * catalogue and lets the model pull in the schemas it needs. See `tool-loading.ts`.
+     */
+    toolDiscovery: "eager" | "ondemand";
+    /** The model that does the preselection pass. Empty means don't preselect. */
+    toolSelectModel: string;
+    /** Hard stop on runaway tool loops. */
+    maxToolIterations: number;
+}
+/** How many times a lost or refused request is worth sending again. See `retry.ts`. */
+export interface RetryPolicy {
+    maxRetries: number;
+}
+/**
+ * A whole agent configuration — every part, plus the two fields that belong to no group.
+ *
+ * Provided for callers that want one name for the lot. Nothing in this package asks for it:
+ * the functions take the parts, so a caller missing `contextLength` can still use all of them
+ * bar the window guard.
+ */
+export interface AgentConfig extends Endpoint, ModelParams, ToolPolicy, RetryPolicy {
+    /** The agent's own standing instruction, if it has one. */
+    systemPrompt: string;
+    /** What the operator says this model reads, in tokens. Zero means ask the endpoint. */
+    contextLength: number;
+}

package/dist/config.js

@@ -0,0 +1,14 @@
+/**
+ * What this package needs to know about a caller's configuration.
+ *
+ * Deliberately not one interface. The three servers that consume this each hold their settings
+ * in a different shape — a resolved agent row, a settings row read straight from the database,
+ * a zod-inferred config object — and they do not all carry the same fields: `task_server`'s
+ * settings row has no `contextLength`, and `min-agent` spells it `contextLimit` and has no
+ * timeout or retry budget at all.
+ *
+ * So every function here asks for the narrowest thing it actually reads, and a caller satisfies
+ * it structurally. Nothing imports a config *type* from a consumer, and no consumer has to grow
+ * a field it has no use for in order to call `getClient`.
+ */
+export {};

package/dist/errors.d.ts

@@ -0,0 +1,8 @@
+/**
+ * What went wrong, as a string.
+ *
+ * Almost everything caught here ends up in a run row, a tool result or a log line, and a
+ * `catch` binds `unknown` — so the same three-branch ternary was being written at every site
+ * that had to say what happened.
+ */
+export declare const errorMessage: (error: unknown) => string;

package/dist/errors.js

@@ -0,0 +1,8 @@
+/**
+ * What went wrong, as a string.
+ *
+ * Almost everything caught here ends up in a run row, a tool result or a log line, and a
+ * `catch` binds `unknown` — so the same three-branch ternary was being written at every site
+ * that had to say what happened.
+ */
+export const errorMessage = (error) => error instanceof Error ? error.message : String(error);

package/dist/events.d.ts

@@ -0,0 +1,87 @@
+/**
+ * What a run is doing, while it is doing it.
+ *
+ * A run row only exists as a before and an after: it is written when the agent starts and
+ * updated when it stops, and everything in between — the thinking, the tool the model reached
+ * for, the argument it got wrong — is gone by the time anyone can read it. This is that middle,
+ * kept in memory and handed to whoever is watching.
+ *
+ * In memory on purpose: it is debugging output, worth nothing once the run has finished and its
+ * outcome is in the database. Nothing here survives a restart, and nothing here is the record.
+ */
+export type RunEventKind = 
+/** A step of a caller's own flow began. `name` is the step, `text` its kind. */
+"step"
+/** A decision step chose an arm. `text` is the arm it took. */
+ | "decision"
+/** A new turn of the agent loop began, inside whichever step is running. */
+ | "turn"
+/** Reasoning tokens, as they arrive. */
+ | "thinking"
+/** Reply tokens, as they arrive. */
+ | "output"
+/** The model asked for a tool, with the arguments it chose. */
+ | "tool-call"
+/** A tool came back, with what it said. */
+ | "tool-result"
+/** Something the runner did that is not the model's doing — a preselection, a retry. */
+ | "notice"
+/** What the run has cost so far, as the endpoint reported it at the end of a turn. */
+ | "usage"
+/** The run ended. Always last, and always sent. */
+ | "done";
+/**
+ * What a run has spent, counted from the start of the run rather than for the turn that
+ * carried it: a client draws the latest one it has seen and needs no arithmetic of its own,
+ * and one lost to the backlog cap costs nothing because the next supersedes it.
+ */
+export interface RunUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+export interface RunEvent {
+    runId: string;
+    /** Per-run counter, from 1. Lets a client order and de-duplicate what it receives. */
+    seq: number;
+    at: Date;
+    kind: RunEventKind;
+    /** The delta, the arguments, the result, or the reason — whatever the kind carries. */
+    text: string;
+    /** Tool name on the tool kinds, otherwise empty. */
+    name: string;
+    /**
+     * The caller's own flow step this happened inside, so a watcher can group a run the way the
+     * work is written. Empty for events that belong to the run rather than to any one step, and
+     * empty throughout for a caller with no steps at all.
+     */
+    step: string;
+    /** Outcome on `tool-result` and `done`, otherwise null. */
+    ok: boolean | null;
+    /** Running totals on `usage`, otherwise null. */
+    usage: RunUsage | null;
+}
+/** What `emit` is given: the run and the sequence are the bus's to assign. */
+export type RunEventInput = Pick<RunEvent, "kind"> & Partial<Omit<RunEvent, "kind">>;
+/** Records one event and hands it to everyone watching that run. Never throws at the caller. */
+export declare function emit(runId: string, input: RunEventInput): RunEvent;
+/**
+ * Everything that has happened on a run, then everything that happens next, until it ends.
+ *
+ * The backlog comes first so a watcher that joins halfway through — or after the run finished,
+ * inside the retention window — reads the same story as one that was there from the start.
+ */
+export declare function watch(runId: string): AsyncGenerator<RunEvent>;
+/** The backlog alone, for a caller that wants a snapshot rather than a subscription. */
+export declare const history: (runId: string) => RunEvent[];
+/** Test seam: forget every run, so one test's events cannot be read by the next. */
+export declare const reset: () => void;
+/**
+ * Consecutive tokens of one kind are one thing being said, not hundreds of things.
+ *
+ * A client that reads a run in snapshots rather than token by token wants it that way: a
+ * reasoning model spends ten thousand deltas on a paragraph, and a paragraph is what it meant.
+ * Each block carries the `seq` of its last event, so asking for what came after one block
+ * picks up exactly where it left off.
+ */
+export declare function fold(events: RunEvent[]): RunEvent[];

package/dist/events.js

@@ -0,0 +1,133 @@
+/**
+ * What a run is doing, while it is doing it.
+ *
+ * A run row only exists as a before and an after: it is written when the agent starts and
+ * updated when it stops, and everything in between — the thinking, the tool the model reached
+ * for, the argument it got wrong — is gone by the time anyone can read it. This is that middle,
+ * kept in memory and handed to whoever is watching.
+ *
+ * In memory on purpose: it is debugging output, worth nothing once the run has finished and its
+ * outcome is in the database. Nothing here survives a restart, and nothing here is the record.
+ */
+/** How many events one run keeps for a watcher that joins late. A chatty run loses its oldest. */
+const MAX_EVENTS = 1000;
+/**
+ * How far past the cap the backlog is allowed to run before it is trimmed.
+ *
+ * Dropping the oldest event on every push means shifting a thousand-element array tens of
+ * thousands of times over a reasoning run — the one thing in here that would ever show up in a
+ * profile. Trimming in batches makes it a few dozen splices instead, at the cost of the backlog
+ * sometimes being a little longer than the cap, which nothing depends on.
+ */
+const TRIM_SLACK = 256;
+/** How long a finished run stays readable, for a watcher that arrives just after the end. */
+const RETAIN_MS = 60_000;
+const streams = new Map();
+const streamFor = (runId) => {
+    const existing = streams.get(runId);
+    if (existing)
+        return existing;
+    const stream = { events: [], listeners: new Set(), seq: 0 };
+    streams.set(runId, stream);
+    return stream;
+};
+/** Records one event and hands it to everyone watching that run. Never throws at the caller. */
+export function emit(runId, input) {
+    const stream = streamFor(runId);
+    const event = {
+        runId,
+        seq: ++stream.seq,
+        at: new Date(),
+        text: "",
+        name: "",
+        step: "",
+        ok: null,
+        usage: null,
+        ...input,
+    };
+    stream.events.push(event);
+    if (stream.events.length > MAX_EVENTS + TRIM_SLACK) {
+        stream.events.splice(0, stream.events.length - MAX_EVENTS);
+    }
+    for (const listener of stream.listeners)
+        listener(event);
+    if (event.kind === "done") {
+        // Kept for a moment so a watcher that arrives just after the end still sees how it went,
+        // then dropped: a finished run's record is the row, not this.
+        setTimeout(() => {
+            if (streams.get(runId) === stream && stream.listeners.size === 0)
+                streams.delete(runId);
+        }, RETAIN_MS).unref?.();
+    }
+    return event;
+}
+/**
+ * Everything that has happened on a run, then everything that happens next, until it ends.
+ *
+ * The backlog comes first so a watcher that joins halfway through — or after the run finished,
+ * inside the retention window — reads the same story as one that was there from the start.
+ */
+export async function* watch(runId) {
+    const stream = streamFor(runId);
+    const queue = [...stream.events];
+    let wake = null;
+    const listener = (event) => {
+        queue.push(event);
+        wake?.();
+    };
+    stream.listeners.add(listener);
+    try {
+        for (;;) {
+            while (queue.length > 0) {
+                const event = queue.shift();
+                yield event;
+                // `done` is the last event a run will ever have, so the subscription completes rather
+                // than leaving the client holding an open stream that will never say anything again.
+                if (event.kind === "done")
+                    return;
+            }
+            await new Promise((resolve) => {
+                wake = resolve;
+            });
+            wake = null;
+        }
+    }
+    finally {
+        stream.listeners.delete(listener);
+        // A watcher can name a run that has not started, or will never start. Nothing was recorded
+        // under it, so nothing is left behind either.
+        if (stream.listeners.size === 0 && stream.events.length === 0)
+            streams.delete(runId);
+    }
+}
+/** The backlog alone, for a caller that wants a snapshot rather than a subscription. */
+export const history = (runId) => [...(streams.get(runId)?.events ?? [])];
+/** Test seam: forget every run, so one test's events cannot be read by the next. */
+export const reset = () => streams.clear();
+/**
+ * Consecutive tokens of one kind are one thing being said, not hundreds of things.
+ *
+ * A client that reads a run in snapshots rather than token by token wants it that way: a
+ * reasoning model spends ten thousand deltas on a paragraph, and a paragraph is what it meant.
+ * Each block carries the `seq` of its last event, so asking for what came after one block
+ * picks up exactly where it left off.
+ */
+export function fold(events) {
+    const blocks = [];
+    for (const event of events) {
+        const last = blocks[blocks.length - 1];
+        const mergeable = event.kind === "thinking" || event.kind === "output";
+        if (last && mergeable && last.kind === event.kind && last.step === event.step) {
+            blocks[blocks.length - 1] = {
+                ...last,
+                seq: event.seq,
+                at: event.at,
+                text: last.text + event.text,
+            };
+        }
+        else {
+            blocks.push(event);
+        }
+    }
+    return blocks;
+}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The endpoint-agnostic half of an OpenAI-compatible agent loop.
+ *
+ * What is here is everything that does not know what the agent is *for*: making a tool schema
+ * a strict server will accept, getting tool definitions in front of a model without paying for
+ * all of them, one-shot calls that support a run, the event bus a watcher reads, a pooled
+ * client, and the rules about retrying. What is not here is the work — orchestration, prompts,
+ * and whatever the run is about — because that is the caller's, and it is the part that differs
+ * between one server and the next.
+ */
+export type { CatalogServer } from "./catalog.ts";
+export { contextLimitFor, getClient, listModels, type ModelInfo, NO_KEY, resetClients, timeoutMs, } from "./client.ts";
+export type { AgentConfig, Endpoint, ModelParams, RetryPolicy, ToolPolicy, } from "./config.ts";
+export { errorMessage } from "./errors.ts";
+export { emit, fold, history, type RunEvent, type RunEventInput, type RunEventKind, type RunUsage, reset, watch, } from "./events.ts";
+export { backoffMs, ContextOverflow, compact, EndpointSilent, isOverflow, isTransient, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, } from "./retry.ts";
+export { isGrammarError, relaxTools, sanitizeTools } from "./schema-compat.ts";
+export { ask, clean, estimateTokens, listLines, parseJson, type SideTaskOptions, tryAsk, } from "./side-task.ts";
+export { carryOver, catalogList, catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadResult, MAX_CARRIED, MAX_PER_LOAD, PRESELECT_SYSTEM, preselectInput, preselection, requestedNames, } from "./tool-loading.ts";

package/dist/index.js

@@ -0,0 +1,17 @@
+/**
+ * The endpoint-agnostic half of an OpenAI-compatible agent loop.
+ *
+ * What is here is everything that does not know what the agent is *for*: making a tool schema
+ * a strict server will accept, getting tool definitions in front of a model without paying for
+ * all of them, one-shot calls that support a run, the event bus a watcher reads, a pooled
+ * client, and the rules about retrying. What is not here is the work — orchestration, prompts,
+ * and whatever the run is about — because that is the caller's, and it is the part that differs
+ * between one server and the next.
+ */
+export { contextLimitFor, getClient, listModels, NO_KEY, resetClients, timeoutMs, } from "./client.js";
+export { errorMessage } from "./errors.js";
+export { emit, fold, history, reset, watch, } from "./events.js";
+export { backoffMs, ContextOverflow, compact, EndpointSilent, isOverflow, isTransient, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, } from "./retry.js";
+export { isGrammarError, relaxTools, sanitizeTools } from "./schema-compat.js";
+export { ask, clean, estimateTokens, listLines, parseJson, tryAsk, } from "./side-task.js";
+export { carryOver, catalogList, catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadResult, MAX_CARRIED, MAX_PER_LOAD, PRESELECT_SYSTEM, preselectInput, preselection, requestedNames, } from "./tool-loading.js";

package/dist/retry.d.ts

@@ -0,0 +1,57 @@
+import OpenAI from "openai";
+/**
+ * Everything about a request failing that is not about what the request said.
+ *
+ * A run makes a request per tool iteration against an endpoint that may be a laptop's llama.cpp
+ * or a hosted API, and the two fail in different ways for different reasons. This is the part
+ * of the loop with nothing to do with the model's answer: whether the request was lost, whether
+ * it was too big to have been sent at all, and how long to wait before sending it again.
+ */
+/** The endpoint stopped answering mid-request. Its own class so the retry can recognise it. */
+export declare class EndpointSilent extends Error {
+    readonly name = "EndpointSilent";
+}
+/**
+ * The request was bigger than the model will read. Its own class so nothing retries it: sending
+ * the same too-large request again is the same refusal, one round trip later.
+ */
+export declare class ContextOverflow extends Error {
+    readonly name = "ContextOverflow";
+}
+/** 1234 → "1.2k". The numbers in an overflow message are large and nobody reads the units digit. */
+export declare const compact: (tokens: number) => string;
+/**
+ * What this request will cost the window, in tokens, near enough.
+ *
+ * Characters over four, because there is no tokenizer here and there is not going to be one:
+ * a server that will not say how big its window is will not lend us its vocabulary either.
+ * The estimate runs low on tool schemas — JSON packs more tokens into a character than prose
+ * does — and that is the side to be wrong on, since the cost of guessing high is a run refused
+ * that would have worked, and the cost of guessing low is the endpoint's own refusal, which is
+ * where we were before this existed.
+ */
+export declare const requestTokens: (body: OpenAI.ChatCompletionCreateParamsStreaming) => number;
+export declare const isOverflow: (detail: string) => boolean;
+/**
+ * Below this, the window is nobody's business and is not asked for.
+ *
+ * Finding out what a model reads costs a listing against its endpoint, and a run whose whole
+ * request is a few thousand tokens fits anything anyone serves — spending a round trip to
+ * confirm that, on every run of every card, would be the cost of the guard falling on the
+ * runs that never needed it. A model in a window smaller than this exists, and a request that
+ * overruns one is left to the endpoint's own complaint, which reads properly now either way.
+ */
+export declare const SMALLEST_LIKELY_WINDOW = 8192;
+/**
+ * Whether a failed request is worth trying again.
+ *
+ * The question is whether the request was *refused or lost*, rather than answered with a
+ * complaint about its contents: a connection that never landed, a server too busy or too broken
+ * to answer, an endpoint that went quiet. A 400 for a malformed tool schema would fail exactly
+ * the same way on every attempt, and the two capability cases below are negotiated rather than
+ * retried blindly.
+ */
+export declare function isTransient(error: unknown): boolean;
+/** Exponential, with jitter so several tasks failing at once do not return in lockstep. */
+export declare const backoffMs: (attempt: number) => number;
+export declare const sleep: (ms: number, signal?: AbortSignal) => Promise<void>;