@cubicecho/agent-core 0.1.0

package/dist/retry.js

@@ -0,0 +1,91 @@
+import OpenAI from "openai";
+import { estimateTokens } from "./side-task.js";
+/**
+ * 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 class EndpointSilent extends Error {
+    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 class ContextOverflow extends Error {
+    name = "ContextOverflow";
+}
+/** 1234 → "1.2k". The numbers in an overflow message are large and nobody reads the units digit. */
+export const compact = (tokens) => tokens >= 1000 ? `${(tokens / 1000).toFixed(1)}k` : String(tokens);
+/**
+ * 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 const requestTokens = (body) => estimateTokens(JSON.stringify(body.messages)) +
+    (body.tools?.length ? estimateTokens(JSON.stringify(body.tools)) : 0);
+/**
+ * Servers refuse an over-long request in their own words; these are the ones worth reading as
+ * that rather than as a broken request. Matched loosely — every one of them is some
+ * arrangement of "context" and "too long", and the arrangement is the part that varies.
+ */
+const OVERFLOW = [
+    /context (size|length|window)/i,
+    /exceeds? the (available|maximum)/i,
+    /too (long|large) for/i,
+    /reduce the length/i,
+];
+export const isOverflow = (detail) => OVERFLOW.some((pattern) => pattern.test(detail)) && /token|context/i.test(detail);
+/**
+ * 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 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 function isTransient(error) {
+    if (error instanceof EndpointSilent)
+        return true;
+    if (error instanceof OpenAI.APIConnectionError)
+        return true;
+    if (!(error instanceof OpenAI.APIError))
+        return false;
+    const { status } = error;
+    return status === 408 || status === 409 || status === 429 || (status ?? 0) >= 500;
+}
+/** Exponential, with jitter so several tasks failing at once do not return in lockstep. */
+export const backoffMs = (attempt) => Math.min(8000, 2 ** attempt * 500) * (0.5 + Math.random() / 2);
+export const sleep = (ms, signal) => new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+        signal?.removeEventListener("abort", onAbort);
+        resolve();
+    }, ms);
+    const onAbort = () => {
+        clearTimeout(timer);
+        reject(signal?.reason ?? new Error("aborted"));
+    };
+    if (signal?.aborted)
+        return onAbort();
+    signal?.addEventListener("abort", onAbort, { once: true });
+});

package/dist/schema-compat.d.ts

@@ -0,0 +1,17 @@
+import type OpenAI from "openai";
+export declare const sanitizeTools: (tools: OpenAI.ChatCompletionTool[]) => OpenAI.ChatCompletionTool[];
+/**
+ * The retry shape: llama.cpp's converter rejects regex escape classes (`\d`, `\w`, `\s`) in
+ * `pattern` and most `format` values, both of which only ever narrowed a string the tool
+ * re-validates anyway.
+ */
+export declare function relaxTools(tools: OpenAI.ChatCompletionTool[]): OpenAI.ChatCompletionTool[];
+/**
+ * Does this failure look like the server could not build a grammar from our tool schemas?
+ *
+ * Every server words this differently — llama-server says "error parsing grammar", Lemonade
+ * says "Failed to initialize samplers: failed to parse grammar", others surface the converter
+ * by name. Since a grammar is only ever involved in constrained decoding, treat any mention of
+ * one as ours; the retry is cheap and latches after a single request.
+ */
+export declare function isGrammarError(message: string): boolean;

package/dist/schema-compat.js

@@ -0,0 +1,178 @@
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** Lookahead and lookbehind: `(?=`, `(?!`, `(?<=`, `(?<!`. */
+const LOOKAROUND = /\(\?<?[=!]/;
+const PRIMITIVES = new Set(["object", "string", "number", "integer", "boolean", "array", "null"]);
+const EMPTY_OBJECT = () => ({ type: "object", properties: {} });
+/** Keys whose value is a schema, or a list of them — several are spelled both ways. */
+const SCHEMA_KEYS = new Set([
+    "items",
+    "additionalProperties",
+    "not",
+    "if",
+    "then",
+    "else",
+    "contains",
+    "propertyNames",
+    "anyOf",
+    "oneOf",
+    "allOf",
+    "prefixItems",
+]);
+/** Keys whose value is a name -> schema map. */
+const SCHEMA_MAPS = new Set(["properties", "patternProperties", "$defs", "definitions"]);
+/**
+ * Coerces one schema position. Malformed MCP output sometimes puts a bare type name where a
+ * whole schema belongs, which the grammar converter reports as `Unrecognized schema: "object"`.
+ */
+function asSchema(node) {
+    if (typeof node === "string")
+        return PRIMITIVES.has(node) && node !== "object" ? { type: node } : EMPTY_OBJECT();
+    if (typeof node === "boolean")
+        return node;
+    if (!isObject(node))
+        return EMPTY_OBJECT();
+    return normalize(node);
+}
+/** Recursively rewrites the shapes llama.cpp's grammar converter cannot represent. */
+function normalize(node) {
+    const out = {};
+    for (const [key, value] of Object.entries(node)) {
+        // `type: ["string", "null"]` — the converter only accepts a single string type.
+        if (key === "type" && Array.isArray(value)) {
+            const names = value.filter((item) => typeof item === "string");
+            const concrete = names.filter((name) => name !== "null");
+            if (names.includes("null"))
+                out.nullable = true;
+            if (concrete.length === 1)
+                out.type = concrete[0];
+            else if (concrete.length > 1)
+                out.anyOf = concrete.map((name) => ({ type: name }));
+            else
+                out.type = "null";
+        }
+        else if (SCHEMA_KEYS.has(key)) {
+            out[key] = Array.isArray(value) ? value.map(asSchema) : asSchema(value);
+        }
+        else if (SCHEMA_MAPS.has(key) && isObject(value)) {
+            out[key] = Object.fromEntries(Object.entries(value).map(([name, sub]) => [name, asSchema(sub)]));
+        }
+        else {
+            out[key] = value;
+        }
+    }
+    collapseNullableUnion(out);
+    // A grammar is context-free; lookaround is not expressible in one at all, so no converter
+    // can accept it. Dropping it costs one advisory constraint on one string field.
+    if (typeof out.pattern === "string" && LOOKAROUND.test(out.pattern))
+        delete out.pattern;
+    // `{"type": "object"}` with no properties produces invalid GBNF.
+    if (out.type === "object" && !isObject(out.properties))
+        out.properties = {};
+    // Strict validators reject any sibling of `$ref`, and draft-07 ignores them, so a reference
+    // stands alone or not at all. This is not hypothetical tidying: collapsing `anyOf: [{$ref},
+    // {type: "null"}]` — the shape a schema-generated server emits at every optional argument —
+    // lands `nullable` right next to the `$ref` that survived. Whatever is dropped here was
+    // already unreadable to a conforming consumer; optionality still lives in the parent's
+    // `required`.
+    if ("$ref" in out)
+        return { $ref: out.$ref };
+    return out;
+}
+/**
+ * `{anyOf: [{type: "string"}, {type: "null"}]}` is how Pydantic-backed MCP servers spell an
+ * optional field. Optionality already lives in the parent's `required`, so keep the one real
+ * branch. A union with two real branches is meaningful and is left alone.
+ */
+function collapseNullableUnion(node) {
+    for (const key of ["anyOf", "oneOf"]) {
+        const variants = node[key];
+        if (!Array.isArray(variants))
+            continue;
+        const concrete = variants.filter((item) => !(isObject(item) && item.type === "null"));
+        if (concrete.length !== 1 || concrete.length === variants.length)
+            continue;
+        delete node[key];
+        Object.assign(node, { nullable: true, ...(isObject(concrete[0]) ? concrete[0] : {}) });
+    }
+}
+/** Combinators at the top level of a parameters schema; strict backends reject them outright. */
+const TOP_LEVEL_COMBINATORS = ["allOf", "anyOf", "oneOf", "enum", "not"];
+function sanitizeParameters(parameters) {
+    if (!isObject(parameters))
+        return EMPTY_OBJECT();
+    const out = normalize(parameters);
+    for (const key of TOP_LEVEL_COMBINATORS)
+        delete out[key];
+    if (out.type !== "object")
+        out.type = "object";
+    if (!isObject(out.properties))
+        out.properties = {};
+    return out;
+}
+const mapTools = (tools, fn) => tools.map((tool) => tool.type === "function"
+    ? { ...tool, function: { ...tool.function, parameters: fn(tool.function.parameters) } }
+    : tool);
+/**
+ * Cached against the tool object rather than recomputed.
+ *
+ * The agent loop rebuilds its tool array on every iteration of every step, and normalising a
+ * couple of dozen MCP schemas is the only walk in a run that is neither a request nor a query.
+ * The pool hands out the same definition objects for the life of a connection, so identity is
+ * exactly the right key: a reconnect makes new ones and they are normalised again.
+ */
+const sanitized = new WeakMap();
+export const sanitizeTools = (tools) => tools.map((tool) => {
+    const hit = sanitized.get(tool);
+    if (hit)
+        return hit;
+    const [clean] = mapTools([tool], sanitizeParameters);
+    sanitized.set(tool, clean);
+    return clean;
+});
+/**
+ * The retry shape: llama.cpp's converter rejects regex escape classes (`\d`, `\w`, `\s`) in
+ * `pattern` and most `format` values, both of which only ever narrowed a string the tool
+ * re-validates anyway.
+ */
+export function relaxTools(tools) {
+    const strip = (node) => {
+        if (Array.isArray(node))
+            return node.map(strip);
+        if (!isObject(node))
+            return node;
+        const out = {};
+        for (const [key, value] of Object.entries(node)) {
+            if (key === "pattern" || key === "format")
+                continue;
+            out[key] = strip(value);
+        }
+        return out;
+    };
+    return mapTools(tools, (parameters) => {
+        const stripped = strip(parameters);
+        return isObject(stripped) ? stripped : EMPTY_OBJECT();
+    });
+}
+/**
+ * Qwen chat templates raise this when the transcript has no user turn. Some servers wrap it
+ * in the same "unable to generate parser" wording as a real schema failure, and stripping
+ * keywords would not fix it.
+ */
+const NO_USER_QUERY = "no user query found";
+/**
+ * Does this failure look like the server could not build a grammar from our tool schemas?
+ *
+ * Every server words this differently — llama-server says "error parsing grammar", Lemonade
+ * says "Failed to initialize samplers: failed to parse grammar", others surface the converter
+ * by name. Since a grammar is only ever involved in constrained decoding, treat any mention of
+ * one as ours; the retry is cheap and latches after a single request.
+ */
+export function isGrammarError(message) {
+    const text = message.toLowerCase();
+    if (text.includes(NO_USER_QUERY))
+        return false;
+    return (text.includes("grammar") ||
+        text.includes("unrecognized schema") ||
+        text.includes("json schema conversion failed") ||
+        (text.includes("unable to generate parser") && text.includes("template")));
+}

package/dist/side-task.d.ts

@@ -0,0 +1,37 @@
+import type { Endpoint } from "./config.ts";
+export interface SideTaskOptions {
+    maxTokens?: number;
+    temperature?: number;
+    signal?: AbortSignal;
+}
+/** Runs a side task and returns the reply text, thinking stripped. Throws like any request. */
+export declare function ask(config: Endpoint, model: string, system: string, user: string, { maxTokens, temperature, signal }?: SideTaskOptions): Promise<string>;
+/**
+ * A side task is never worth failing the work it supports. Callers that can carry on without
+ * an answer use this and get `undefined` instead of an exception.
+ */
+export declare function tryAsk<T>(label: string, run: () => Promise<T>): Promise<T | undefined>;
+/**
+ * Models are asked for JSON and often answer with prose around it, or a fenced block. Pull out
+ * the first array or object rather than failing the task over a wrapper.
+ */
+export declare function parseJson<T>(text: string): T | undefined;
+/** Strips the quoting and list punctuation models decorate short answers with. */
+export declare const clean: (line: string) => string;
+/**
+ * A list-shaped reply, one item per line, cleaned of the bullets and quotes models decorate
+ * them with. Overlong items are dropped rather than truncated — a suggestion that has to be
+ * squinted at is worse than one fewer suggestion.
+ */
+export declare const listLines: (text: string, max: number, maxChars: number) => string[];
+/**
+ * Rough token count. 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 wherever it guards a window, 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 the guard existed.
+ */
+export declare const estimateTokens: (text: string) => number;

package/dist/side-task.js

@@ -0,0 +1,129 @@
+import OpenAI from "openai";
+import { getClient } from "./client.js";
+/**
+ * One-shot calls that support a run without being one: picking tools, naming a session,
+ * summarising a transcript, proposing follow-ups. They share a shape — small prompt, short
+ * answer, no tools, no streaming — and none is ever worth failing the run it supports.
+ */
+/**
+ * Reasoning models will happily spend a whole budget deliberating over a six-word answer and
+ * return empty content, so side tasks ask for thinking to be turned off. `reasoning_effort` is
+ * the OpenAI-compatible spelling and `chat_template_kwargs` the llama.cpp/vLLM one; servers
+ * disagree about which they take, so send both. One that rejects the unknown fields gets a
+ * single retry without them, and is not offered them again.
+ */
+const NO_THINKING = {
+    reasoning_effort: "none",
+    chat_template_kwargs: { enable_thinking: false },
+};
+/**
+ * The endpoints that turned out not to take the hints, by base URL.
+ *
+ * Keyed rather than global for the reason the client cache is keyed: a refusal is a fact about
+ * the server on the other end, not about this process. A llama.cpp box and a cloud API are both
+ * reachable from one consumer over its lifetime, and the first one's refusal must not stop the
+ * second from ever being asked.
+ */
+const noHints = new Set();
+/**
+ * Whether a failure is the server complaining about the request, rather than failing to answer.
+ *
+ * The retry below used to catch everything, so an aborted first call — or a connection that
+ * never landed — latched the hints off for the life of the process and every later side task
+ * paid for it by burning a whole budget on deliberation. Only a 4xx says the fields were the
+ * problem; a timeout, a refused connection or a 500 say nothing about them at all.
+ */
+function rejectedTheRequest(error) {
+    if (!(error instanceof OpenAI.APIError))
+        return false;
+    const status = error.status ?? 0;
+    return status >= 400 && status < 500;
+}
+/** Reasoning models that ignore the hints still fence their scratchpad; drop it. */
+const stripThinking = (text) => text.replace(/<think>[\s\S]*?<\/think>/gi, "");
+/** Runs a side task and returns the reply text, thinking stripped. Throws like any request. */
+export async function ask(config, model, system, user, { maxTokens = 512, temperature = 0.3, signal } = {}) {
+    const send = (hints) => getClient(config).chat.completions.create({
+        model,
+        max_tokens: maxTokens,
+        temperature,
+        messages: [
+            { role: "system", content: system },
+            { role: "user", content: user },
+        ],
+        ...(hints ? NO_THINKING : {}),
+    }, { signal });
+    const hints = !noHints.has(config.baseUrl);
+    let response;
+    try {
+        response = await send(hints);
+    }
+    catch (error) {
+        if (!hints || !rejectedTheRequest(error))
+            throw error;
+        console.warn("[side-task] server rejected the no-thinking hints; retrying without them");
+        noHints.add(config.baseUrl);
+        response = await send(false);
+    }
+    return stripThinking(response.choices[0]?.message?.content ?? "").trim();
+}
+/**
+ * A side task is never worth failing the work it supports. Callers that can carry on without
+ * an answer use this and get `undefined` instead of an exception.
+ */
+export async function tryAsk(label, run) {
+    try {
+        return await run();
+    }
+    catch (error) {
+        console.warn(`[side-task] ${label}:`, error.message);
+        return undefined;
+    }
+}
+/**
+ * Models are asked for JSON and often answer with prose around it, or a fenced block. Pull out
+ * the first array or object rather than failing the task over a wrapper.
+ */
+export function parseJson(text) {
+    const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
+    const body = (fenced?.[1] ?? text).trim();
+    const start = body.search(/[[{]/);
+    if (start < 0)
+        return undefined;
+    const end = Math.max(body.lastIndexOf("]"), body.lastIndexOf("}"));
+    if (end <= start)
+        return undefined;
+    try {
+        return JSON.parse(body.slice(start, end + 1));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Strips the quoting and list punctuation models decorate short answers with. */
+export const clean = (line) => line
+    .trim()
+    .replace(/^(?:[-*•]|\d+[.)])\s*/, "")
+    .replace(/^["'`]+|["'`.]+$/g, "")
+    .trim();
+/**
+ * A list-shaped reply, one item per line, cleaned of the bullets and quotes models decorate
+ * them with. Overlong items are dropped rather than truncated — a suggestion that has to be
+ * squinted at is worse than one fewer suggestion.
+ */
+export const listLines = (text, max, maxChars) => text
+    .split("\n")
+    .map(clean)
+    .filter((line) => line.length > 0 && line.length <= maxChars)
+    .slice(0, max);
+/**
+ * Rough token count. 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 wherever it guards a window, 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 the guard existed.
+ */
+export const estimateTokens = (text) => Math.ceil(text.length / 4);

package/dist/tool-loading.d.ts

@@ -0,0 +1,85 @@
+import type OpenAI from "openai";
+import type { CatalogServer } from "./catalog.ts";
+/**
+ * On-demand tool loading.
+ *
+ * A full tool definition is mostly JSON Schema, and it is sent on every request of every
+ * iteration whether or not the model wants it — a couple of connected servers can cost more
+ * tokens per request than the task's own prompt. So in on-demand mode the run starts with a
+ * bare *catalogue*: tool names only, appended to the system prompt, plus this one meta-tool.
+ * The model calls `load_tools` with what it needs, and the next round trip carries those real
+ * definitions.
+ *
+ * Names alone cost roughly a fortieth of what the schemas cost, so a run that needs no tools
+ * pays almost nothing, and a run that needs three pays for three.
+ */
+export declare const LOAD_TOOLS = "load_tools";
+/** One object for the life of the process — the agent loop asks for it on every iteration. */
+export declare const LOAD_TOOLS_DEFINITION: OpenAI.ChatCompletionTool;
+/** The catalogue as a plain grouped listing of names, loaded ones marked. */
+export declare function catalogList(catalog: CatalogServer[], loaded?: ReadonlySet<string>): string;
+/**
+ * The catalogue block appended to the system prompt. Names only — descriptions arrive on load.
+ *
+ * Loaded tools stay in the list, marked. Removing them reads as the tool having vanished the
+ * moment it was loaded, and the model loads again to get it back; hoisting them into a separate
+ * "already loaded" section splits a server's tools apart, and the model picks a sibling from
+ * the longer list instead.
+ */
+export declare function catalogPrompt(catalog: CatalogServer[], loaded?: ReadonlySet<string>): string;
+/**
+ * The most a single `load_tools` call may pull in.
+ *
+ * A wildcard like `gmail__*` matches 33 tools, and loading them all puts the model right back
+ * in the position on-demand loading exists to avoid — a tool array too large to choose from.
+ * Over-broad requests are refused with the matching names listed, so the next call can be
+ * precise.
+ */
+export declare const MAX_PER_LOAD = 12;
+/**
+ * The most a conversation carries between turns. Bounds the tool array no matter how long the
+ * conversation runs; least-recently-used names fall off the front.
+ *
+ * Only a multi-turn caller needs this — a run that starts from nothing each time has nothing to
+ * carry. See `carryOver`.
+ */
+export declare const MAX_CARRIED = 16;
+/** The tools to start the next turn with: recently used, newest last, capped. */
+export declare const carryOver: (previous: string[], used: Set<string>) => string[];
+/**
+ * Resolves requested names against the catalogue, expanding trailing `*` wildcards.
+ *
+ * Names are matched leniently. Catalogue entries are slug-qualified (`nas_fs__read_file`) and
+ * models routinely ask for the bare tool name, so an exact miss falls back to a suffix match
+ * on the `__` boundary — accepted only when it is unambiguous. Rejecting those outright just
+ * buys a wasted round trip while the model guesses the prefix, and pushes it toward
+ * shotgunning wildcards.
+ */
+export declare function expandNames(requested: string[], catalog: CatalogServer[]): {
+    matched: string[];
+    unknown: string[];
+    overBroad: {
+        name: string;
+        hits: string[];
+    }[];
+};
+/** What `load_tools` reports back: the descriptions, now that they are worth their tokens. */
+export declare function loadResult({ matched, unknown, overBroad }: ReturnType<typeof expandNames>, catalog: CatalogServer[]): string;
+export declare const inCatalog: (catalog: CatalogServer[], name: string) => boolean;
+/** `load_tools` arguments, defensively — a model may send a bare string or a nested object. */
+export declare function requestedNames(args: Record<string, unknown>): string[];
+/**
+ * Tool preselection.
+ *
+ * On-demand loading otherwise costs a round trip every run: the model reads the catalogue,
+ * calls `load_tools`, and only then can do the work. A small model reading the same catalogue
+ * usually names the right tools outright, so the task model finds them already loaded and
+ * starts working on its first step.
+ *
+ * A wrong guess is cheap — an unused definition is a few hundred tokens for one run — but a
+ * broad guess is not, so the same `MAX_PER_LOAD` cap applies here as to a `load_tools` call.
+ */
+export declare const PRESELECT_SYSTEM: string;
+export declare const preselectInput: (catalog: CatalogServer[], prompt: string) => string;
+/** Resolves a preselection against the catalogue: unknown names dropped, count capped. */
+export declare function preselection(names: unknown, catalog: CatalogServer[]): string[];