toolnexus 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Muthukumaran Navaneethakrishnan
+
+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,116 @@
+# toolnexus (JavaScript / TypeScript)
+
+Dynamic MCP servers + agent skills as a uniform tool list for any LLM. Built on
+`@modelcontextprotocol/sdk` (the same MCP SDK opencode uses). See the root
+[SPEC.md](../SPEC.md) for the language-independent contract.
+
+## Install
+
+```sh
+npm install toolnexus
+```
+
+## Use
+
+```ts
+import { createToolkit } from "toolnexus"
+
+const tk = await createToolkit({
+  mcpConfig: "./mcp.json",   // path or parsed object; key may be mcpServers/servers/mcp
+  skillsDir: "./skills",     // folder of <name>/SKILL.md (or an array of folders)
+  // extraTools: [...]        // your own custom tools, optional
+})
+
+// 1. give the model the tool schema in its native format
+const tools  = tk.toOpenAI()       // or tk.toAnthropic() / tk.toGemini()
+const system = tk.skillsPrompt()   // markdown catalog of skills for the system prompt
+
+// 2. when the model returns a tool call { name, arguments }:
+const res = await tk.execute(name, args)   // -> { output, isError, metadata }
+// feed res.output back as the tool result, loop.
+
+console.log(tk.mcpStatus())  // { server: "connected" | "failed" | "disabled" }
+await tk.close()
+```
+
+## Run the examples
+
+```sh
+npm install && npm run build
+
+# offline: connects to @modelcontextprotocol/server-everything via npx, lists tools, loads a skill
+node --experimental-strip-types examples/basic.ts
+
+# live: real OpenRouter tool-calling round trip (needs OPENROUTER_API_KEY)
+OPENROUTER_API_KEY=... node --experimental-strip-types examples/openrouter_test.ts
+```
+
+## API
+
+| Member | Description |
+|--------|-------------|
+| `createToolkit(opts)` | async factory → `Toolkit` |
+| `tk.tools()` | all uniform `Tool`s (mcp + skill + extras) |
+| `tk.get(name)` | one tool by name |
+| `tk.execute(name, args, ctx?)` | run a tool → `ToolResult` |
+| `tk.skillsPrompt()` | system-prompt skill catalog |
+| `tk.mcpStatus()` | per-server connection status |
+| `tk.toOpenAI()` / `toAnthropic()` / `toGemini()` | provider tool schemas |
+| `tk.register(...tools)` | add native/http/custom tools at runtime |
+| `tk.close()` | disconnect MCP servers |
+
+You can also use the sources directly: `loadMcp(config)`, `loadSkills(dir)`.
+
+## Native tools (a function → a tool)
+
+```ts
+import { defineTool } from "toolnexus"
+
+const add = defineTool({
+  name: "add", description: "Add two numbers",
+  inputSchema: { type: "object", properties: { a: { type: "number" }, b: { type: "number" } }, required: ["a", "b"] },
+  run: ({ a, b }) => `${(a as number) + (b as number)}`,   // string or ToolResult
+})
+tk.register(add)
+```
+
+## HTTP / REST tools (an endpoint → a tool)
+
+```ts
+import { httpTool } from "toolnexus"
+
+tk.register(httpTool({
+  name: "create_ticket", description: "Create a ticket", method: "POST",
+  url: "https://api.example.com/tickets",
+  headers: { Authorization: "Bearer ${API_TOKEN}" },   // ${ENV} expands from process.env, never logged
+  inputSchema: { type: "object", properties: { title: { type: "string" } }, required: ["title"] },
+}))
+```
+
+URL `{placeholders}` are filled from args; `query` args go to the querystring; the rest
+become the JSON body. Non-2xx → `{ isError: true, output: "HTTP <status>: <body>" }`.
+
+## Unified client (the host loop)
+
+```ts
+import { createClient } from "toolnexus"
+
+const agent = createClient({
+  baseUrl: "https://openrouter.ai/api/v1",  // any OpenAI- or Anthropic-style endpoint
+  style: "openai",                           // or "anthropic"
+  model: "openai/gpt-4o-mini",
+  // apiKey defaults to OPENROUTER_API_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY
+  systemPrompt: "You are a helpful agent.",
+})
+
+const { text, toolCalls } = await agent.run("do the thing", { toolkit: tk })
+```
+
+It injects `tk.skillsPrompt()` into the system message and runs the full
+call → execute tools → feed back → repeat loop (up to `maxTurns`, default 10).
+
+## Examples
+
+- `examples/basic.ts` — toolkit + adapters + skill load (offline).
+- `examples/agent.ts` — native + http tools driven by the unified client (live with `OPENROUTER_API_KEY`).
+- `examples/openrouter_test.ts` — minimal live tool-calling round trip.

package/dist/adapters.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Provider adapters — turn the uniform tool list into each LLM's tool schema.
+ * Execution is identical for every provider: read the tool name + args the model
+ * returned, call toolkit.execute(name, args), feed output back.
+ */
+import type { Tool } from "./types.js";
+export declare function toOpenAI(tools: Tool[]): {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: import("./types.js").JSONSchema;
+    };
+}[];
+export declare function toAnthropic(tools: Tool[]): {
+    name: string;
+    description: string;
+    input_schema: import("./types.js").JSONSchema;
+}[];
+export declare function toGemini(tools: Tool[]): {
+    functionDeclarations: {
+        name: string;
+        description: string;
+        parameters: import("./types.js").JSONSchema;
+    }[];
+}[];

package/dist/adapters.js

@@ -0,0 +1,24 @@
+export function toOpenAI(tools) {
+    return tools.map((t) => ({
+        type: "function",
+        function: { name: t.name, description: t.description, parameters: t.inputSchema },
+    }));
+}
+export function toAnthropic(tools) {
+    return tools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        input_schema: t.inputSchema,
+    }));
+}
+export function toGemini(tools) {
+    return [
+        {
+            functionDeclarations: tools.map((t) => ({
+                name: t.name,
+                description: t.description,
+                parameters: t.inputSchema,
+            })),
+        },
+    ];
+}

package/dist/client.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Unified LLM client — the host loop. Give it a plain base URL + a style
+ * ("openai" | "anthropic"), and it runs the tool-calling agent loop against a
+ * Toolkit. See ../../SPEC.md §8.
+ */
+import type { Toolkit } from "./toolkit.js";
+import type { ToolResult } from "./types.js";
+export type ClientStyle = "openai" | "anthropic";
+export interface ClientOptions {
+    baseUrl: string;
+    style: ClientStyle;
+    model: string;
+    apiKey?: string;
+    headers?: Record<string, string>;
+    systemPrompt?: string;
+    maxTurns?: number;
+    hooks?: Hooks;
+    /** Retries on transient LLM errors (429/5xx/network). Default 2. */
+    retries?: number;
+    /** Base backoff in ms (exponential + jitter). Default 500. */
+    retryBaseMs?: number;
+    /** Whole-run deadline in ms; aborts the run (and its in-flight request) when exceeded. */
+    timeoutMs?: number;
+}
+/**
+ * Lifecycle hooks around the agent loop. Each may observe, and (where noted)
+ * mutate or short-circuit. All may be async.
+ */
+export interface Hooks {
+    /** Before each model call. Return { messages?, tools? } to replace them. */
+    beforeLLM?(ev: {
+        messages: any[];
+        tools: any[];
+        model: string;
+        turn: number;
+    }): void | {
+        messages?: any[];
+        tools?: any[];
+    } | Promise<void | {
+        messages?: any[];
+        tools?: any[];
+    }>;
+    /** After each model call (observe: logging, cost, tracing). */
+    afterLLM?(ev: {
+        response: any;
+        model: string;
+        turn: number;
+    }): void | Promise<void>;
+    /** Before a tool runs. Return { result } to SHORT-CIRCUIT (deny/cache), { args } to rewrite. */
+    beforeTool?(ev: {
+        name: string;
+        args: Record<string, unknown>;
+        id?: string;
+        turn: number;
+    }): void | {
+        args?: Record<string, unknown>;
+        result?: ToolResult;
+    } | Promise<void | {
+        args?: Record<string, unknown>;
+        result?: ToolResult;
+    }>;
+    /** After a tool runs. Return { result } to replace the result. */
+    afterTool?(ev: {
+        name: string;
+        args: Record<string, unknown>;
+        result: ToolResult;
+        id?: string;
+        turn: number;
+    }): void | {
+        result?: ToolResult;
+    } | Promise<void | {
+        result?: ToolResult;
+    }>;
+}
+/** A tool call the model made, plus its result + metadata. */
+export interface ToolCallRecord {
+    name: string;
+    args: Record<string, unknown>;
+    output: string;
+    isError: boolean;
+    metadata?: Record<string, unknown>;
+}
+/** Token usage, summed across every LLM round trip in the run. */
+export interface Usage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+export interface RunResult {
+    text: string;
+    messages: any[];
+    /** Every tool call made, with its output, error flag, and metadata. */
+    toolCalls: ToolCallRecord[];
+    /** Total number of tool calls (= toolCalls.length). */
+    toolCallCount: number;
+    /** Number of LLM round trips. */
+    turns: number;
+    /** Aggregated token usage across all turns. */
+    usage: Usage;
+    /** The model used. */
+    model: string;
+}
+/** Events yielded by client.stream(). */
+export type StreamEvent = {
+    type: "text";
+    delta: string;
+} | {
+    type: "tool_call";
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+} | {
+    type: "tool_result";
+    id: string;
+    name: string;
+    output: string;
+    isError: boolean;
+} | {
+    type: "usage";
+    usage: Usage;
+} | {
+    type: "done";
+    result: RunResult;
+};
+export declare class Client {
+    private readonly opts;
+    constructor(opts: ClientOptions);
+    run(prompt: string, ctx: {
+        toolkit: Toolkit;
+        signal?: AbortSignal;
+        history?: any[];
+    }): Promise<RunResult>;
+    /** A stateful multi-turn conversation that retains history across sends. */
+    conversation(ctx: {
+        toolkit: Toolkit;
+        signal?: AbortSignal;
+    }): Conversation;
+    /** Streaming variant: async-iterate live events (text deltas, tool calls/results, usage, done). */
+    stream(prompt: string, ctx: {
+        toolkit: Toolkit;
+        signal?: AbortSignal;
+    }): AsyncGenerator<StreamEvent, void, unknown>;
+    private system;
+    /** Build a run-scoped abort signal from the optional run-level timeout + an external signal. */
+    private makeSignal;
+    /** fetch with retry + exponential backoff on 429/5xx/network, honoring Retry-After; aborts via signal. */
+    private llmFetch;
+    /** Run one tool through beforeTool/afterTool hooks (mutate args, short-circuit, transform result). */
+    private runTool;
+    private runOpenAI;
+    private result;
+    private runAnthropic;
+    private streamOpenAI;
+    private streamAnthropic;
+}
+export declare function createClient(opts: ClientOptions): Client;
+/** Stateful multi-turn conversation: each send() continues the same transcript (memory). */
+export declare class Conversation {
+    private readonly client;
+    private readonly toolkit;
+    private readonly signal?;
+    /** Full running transcript (system + user + assistant + tool messages). */
+    messages: any[];
+    constructor(client: Client, toolkit: Toolkit, signal?: AbortSignal | undefined);
+    /** Send the next user turn; prior history is retained automatically. */
+    send(prompt: string): Promise<RunResult>;
+    /** Reset the conversation memory. */
+    reset(): void;
+}