@cubicecho/agent-core 0.1.0

package/dist/tool-loading.js

@@ -0,0 +1,185 @@
+/**
+ * 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 const LOAD_TOOLS = "load_tools";
+/** One object for the life of the process — the agent loop asks for it on every iteration. */
+export const LOAD_TOOLS_DEFINITION = {
+    type: "function",
+    function: {
+        name: LOAD_TOOLS,
+        description: "Load the full definitions of tools listed in the tool catalogue so you can call them. " +
+            "Pass the exact names you need, or a trailing wildcard like `server__group__*` for a " +
+            "whole group. The tools become callable on your next step — load them, then call them. " +
+            "Load only what the task actually needs.",
+        parameters: {
+            type: "object",
+            properties: {
+                names: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Tool names from the catalogue. Wildcards may end with `*`.",
+                },
+            },
+            required: ["names"],
+            additionalProperties: false,
+        },
+    },
+};
+/** The catalogue as a plain grouped listing of names, loaded ones marked. */
+export function catalogList(catalog, loaded) {
+    return catalog
+        .map((server) => {
+        const names = server.tools.map((tool) => `  ${tool.name}${loaded?.has(tool.name) ? " (loaded)" : ""}`);
+        return `${server.label}:\n${names.join("\n")}`;
+    })
+        .join("\n");
+}
+/**
+ * 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 function catalogPrompt(catalog, loaded) {
+    if (!catalog.length)
+        return "";
+    return [
+        "# Tool catalogue",
+        "",
+        "These tools exist but are not loaded. Call `load_tools` with the names you need, then call",
+        "them on the step after. Names are descriptive; load a tool to see its parameters. A name",
+        "marked `(loaded)` is already in your tool list — call it directly, do not load it again. Do",
+        "not load tools the task does not need, and do not mention this mechanism in your answer.",
+        "",
+        catalogList(catalog, loaded),
+    ].join("\n");
+}
+const flatten = (catalog) => catalog.flatMap((server) => server.tools);
+/**
+ * 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 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 const MAX_CARRIED = 16;
+/** The tools to start the next turn with: recently used, newest last, capped. */
+export const carryOver = (previous, used) => [...previous.filter((name) => !used.has(name)), ...used].slice(-MAX_CARRIED);
+/**
+ * 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 function expandNames(requested, catalog) {
+    const all = flatten(catalog);
+    const matched = new Set();
+    const unknown = [];
+    const overBroad = [];
+    const known = new Set(all.map((tool) => tool.name));
+    const resolve = (name) => {
+        if (name.endsWith("*")) {
+            const stem = name.slice(0, -1);
+            const direct = all.filter((tool) => tool.name.startsWith(stem));
+            if (direct.length)
+                return direct.map((tool) => tool.name);
+            return all.filter((tool) => tool.name.includes(`__${stem}`)).map((tool) => tool.name);
+        }
+        if (known.has(name))
+            return [name];
+        const suffix = all.filter((tool) => tool.name.endsWith(`__${name}`));
+        return suffix.length === 1 ? [suffix[0].name] : [];
+    };
+    for (const raw of requested) {
+        const name = raw.trim();
+        if (!name)
+            continue;
+        const hits = resolve(name);
+        if (!hits.length)
+            unknown.push(name);
+        else if (hits.length > MAX_PER_LOAD)
+            overBroad.push({ name, hits });
+        else
+            for (const hit of hits)
+                matched.add(hit);
+    }
+    return { matched: [...matched], unknown, overBroad };
+}
+/** What `load_tools` reports back: the descriptions, now that they are worth their tokens. */
+export function loadResult({ matched, unknown, overBroad }, catalog) {
+    const byName = new Map(flatten(catalog).map((tool) => [tool.name, tool.description]));
+    const lines = [];
+    if (matched.length) {
+        lines.push(`Loaded ${matched.length} tool(s); they are callable on your next step.`, "");
+        for (const name of matched)
+            lines.push(`${name}: ${byName.get(name) ?? ""}`.trim());
+    }
+    for (const { name, hits } of overBroad) {
+        if (lines.length)
+            lines.push("");
+        lines.push(`\`${name}\` matches ${hits.length} tools, more than the ${MAX_PER_LOAD} one call may load.`, "Name the ones you need from:", ...hits.map((hit) => `  ${hit}`));
+    }
+    if (unknown.length) {
+        if (lines.length)
+            lines.push("");
+        lines.push(`Not in the catalogue: ${unknown.join(", ")}. Check the names and try again.`);
+    }
+    return lines.join("\n") || "No tool names were given.";
+}
+export const inCatalog = (catalog, name) => catalog.some((server) => server.tools.some((tool) => tool.name === name));
+/** `load_tools` arguments, defensively — a model may send a bare string or a nested object. */
+export function requestedNames(args) {
+    const value = args.names ?? args.tools ?? args.name;
+    if (typeof value === "string")
+        return [value];
+    if (Array.isArray(value))
+        return value.filter((item) => typeof item === "string");
+    return [];
+}
+/**
+ * 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 const PRESELECT_SYSTEM = "You choose tools. Below is a catalogue of tool names, then a request. Reply with a JSON " +
+    "array of the names the request is likely to need — exact names from the catalogue, at most " +
+    `${MAX_PER_LOAD}, and as few as could do the job. Reply with \`[]\` if the request can be ` +
+    "answered without tools. Reply with the array alone — no prose, no explanation.";
+export const preselectInput = (catalog, prompt) => `# Tool catalogue\n\n${catalogList(catalog)}\n\n# Request\n\n${prompt.slice(0, 2000)}`;
+/** Resolves a preselection against the catalogue: unknown names dropped, count capped. */
+export function preselection(names, catalog) {
+    if (!Array.isArray(names))
+        return [];
+    const wanted = names.filter((name) => typeof name === "string");
+    return expandNames(wanted, catalog).matched.slice(0, MAX_PER_LOAD);
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@cubicecho/agent-core",
+  "version": "0.1.0",
+  "description": "The endpoint-agnostic half of an OpenAI-compatible agent loop: tool-schema compatibility, on-demand tool loading, one-shot side tasks, run events, and a pooled client.",
+  "keywords": [
+    "openai",
+    "agent",
+    "mcp",
+    "tool-calling",
+    "json-schema",
+    "llama.cpp",
+    "vllm",
+    "ollama",
+    "typescript"
+  ],
+  "license": "MIT",
+  "author": "Benjamin Van Treese <vantreeseba@gmail.com>",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cubicecho/agent-core.git"
+  },
+  "homepage": "https://github.com/cubicecho/agent-core#readme",
+  "bugs": {
+    "url": "https://github.com/cubicecho/agent-core/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepare": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "biome check .",
+    "format": "biome check --write ."
+  },
+  "peerDependencies": {
+    "openai": ">=6"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.11",
+    "@semantic-release/changelog": "^7.0.0",
+    "@semantic-release/git": "^11.0.1",
+    "@types/node": "^26.4.0",
+    "openai": "^7.8.0",
+    "semantic-release": "^25.0.9",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.11"
+  }
+}