toolnexus 0.3.0 → 0.4.0

package/README.md

@@ -7,9 +7,9 @@
 and you have a working agent — MCP servers, agent skills, your own functions, and HTTP endpoints
 unified as one tool set, driving any LLM.
 
-> **Right-sized.** Not a framework (no builders, advisors, runnables, config), not a toy that
-> falls over the moment you need streaming or a retry. Everything a real agent needs — the loop,
-> hooks, streaming, retries, memory — and nothing it doesn't.
+> **Right-sized.** Not a framework (no builders, advisors, runnables, config graphs), not a toy
+> that falls over the moment you need streaming or a retry. Everything a real agent needs — the
+> loop, hooks, streaming, retries, memory — and nothing it doesn't.
 
 The JS/TypeScript port of [toolnexus](https://github.com/muthuishere/toolnexus) — the same
 library, byte-identical, also in **Python, Go, Java, and C#**. Built on
@@ -21,30 +21,147 @@ library, byte-identical, also in **Python, Go, Java, and C#**. Built on
 npm install toolnexus
 ```
 
-## An agent in 3 steps
+## Quick start
+
+Built-in tools are on by default, so an empty toolkit can already act:
 
 ```ts
 import { createToolkit, createClient } from "toolnexus"
 
-// 1. tools from an mcp.json + a skills/ folder
-const tk = await createToolkit({ mcpConfig: "./mcp.json", skillsDir: "./skills" })
-
-// 2. point at any OpenAI- or Anthropic-style endpoint
+const tk = await createToolkit()                        // 10 built-in tools, on by default
 const agent = createClient({
-  baseUrl: "https://openrouter.ai/api/v1",
-  style: "openai",                  // or "anthropic"
+  baseUrl: "https://openrouter.ai/api/v1",              // any OpenAI- or Anthropic-style endpoint
+  style: "openai",                                      // or "anthropic"
   model: "openai/gpt-4o-mini",
 })
 
-// 3. run — skills are injected into the system prompt, tools are called for you, looped to an answer
-const { text } = await agent.run("Refund order 1234 for the customer.", { toolkit: tk })
+const { text } = await agent.run("What files are in this folder?", { toolkit: tk })
 console.log(text)
-await tk.close()
 ```
 
 `createClient` reads the key from `OPENROUTER_API_KEY` / `OPENAI_API_KEY` / `ANTHROPIC_API_KEY`
-by default. The loop runs call → execute tools → feed back → repeat (up to `maxTurns`, default 10),
-with hooks, streaming (`agent.stream(...)`), retries/backoff, and conversation memory available.
+(or pass `apiKey`). The loop runs call → execute tools → feed back → repeat (up to `maxTurns`,
+default 10), with hooks, streaming (`agent.stream(...)`), retries/backoff, timeout, and
+conversation memory available.
+
+## With MCP + skills
+
+Point the toolkit at an `mcp.json` and a `skills/` folder — every MCP server tool and every
+`SKILL.md` becomes part of the same tool set. Skills are injected into the system prompt; a
+single `skill` tool loads each on demand (progressive disclosure).
+
+```ts
+const tk = await createToolkit({
+  mcpConfig: "./mcp.json",     // path or a config object; local stdio + remote streamable-HTTP
+  skillsDir: "./skills",       // a folder of <name>/SKILL.md (string or string[])
+})
+
+const { text } = await agent.run("Refund order 1234 for the customer.", { toolkit: tk })
+console.log(text)
+await tk.close()               // disconnect MCP servers
+```
+
+## Conversations / memory
+
+`run()` is stateless — each call starts fresh. To keep a thread's history, use `ask()` with an
+`id`, or a `conversation()` object.
+
+**`ask(prompt, { toolkit, id? })`** — with an `id`, the client's `ConversationStore` remembers
+the thread: it *loads* that id's transcript, *runs*, *saves* the updated transcript, and returns
+the answer. The next `ask` with the same `id` continues it. Without an `id` it's a stateless
+one-shot (identical to `run`).
+
+```ts
+const agent = createClient({
+  baseUrl: "https://openrouter.ai/api/v1",
+  style: "openai",
+  model: "openai/gpt-4o-mini",
+  // store defaults to InMemoryConversationStore (process lifetime).
+})
+
+await agent.ask("My name is Muthu.", { toolkit: tk, id: "user-42" })
+const { text } = await agent.ask("What's my name?", { toolkit: tk, id: "user-42" })
+console.log(text)   // → "Your name is Muthu."
+```
+
+**Persist across processes.** A `ConversationStore` is two methods — implement it for a file, DB,
+or Redis and pass it as `store`:
+
+```ts
+import type { ConversationStore } from "toolnexus"
+
+interface ConversationStore {
+  get(id: string): Promise<any[] | undefined>   // stored transcript for id, or undefined
+  save(id: string, messages: any[]): Promise<void>
+}
+
+const agent = createClient({ baseUrl, style: "openai", model, store: myFileStore })
+```
+
+The default is `InMemoryConversationStore` (also exported). For a quick in-process thread without
+ids, `agent.conversation({ toolkit })` returns an object whose `.send(prompt)` retains history
+automatically (`.messages`, `.reset()`).
+
+The same `store` powers inbound A2A: `toolkit.serve` keys each peer's turns by the A2A
+`contextId` through `client.ask`, so a remote agent's conversation is remembered too (see below).
+
+**Streaming with memory.** The `id` also works while streaming. Pass `on_text` to `ask` to stream
+text deltas as they arrive — `ask` still returns the final `RunResult` — or iterate `stream()`
+directly. With an `id`, the thread is loaded before the stream and saved on the `done` event.
+
+```ts
+// block-style: stream deltas to stdout, still get the RunResult back — remembered under `id`
+const res = await agent.ask("Draft a reply.", {
+  toolkit: tk,
+  id: "user-42",
+  on_text: (delta) => process.stdout.write(delta),
+})
+
+// iterator: consume text + tool events; `id` makes it stateful (load before, save on `done`)
+for await (const ev of agent.stream("And summarise it.", { toolkit: tk, id: "user-42" })) {
+  if (ev.type === "text") process.stdout.write(ev.delta)
+  else if (ev.type === "done") console.log("\n", ev.result.usage)
+}
+```
+
+## Observability / metrics
+
+Zero-dependency, two outputs from one internal instrumentation — both opt-in, no cost when unused.
+
+**`onMetric` — a semantic event feed.** Pass it to `createClient` and it receives a readable
+`MetricEvent` at each significant point: `{ event: "llm", model, status, ms, promptTokens,
+completionTokens }` per model call, `{ event: "tool", tool, source, isError, ms }` per tool call,
+and a terminal `{ event: "run", model, turns, toolCalls, totalTokens, ms, error? }` per `run`/`ask`.
+Forward it anywhere (statsd, logs, OpenTelemetry) — the library holds no opinion.
+
+```ts
+const agent = createClient({
+  baseUrl, style: "openai", model,
+  onMetric: (ev) => console.log("[metric]", ev.event, JSON.stringify(ev)),
+})
+```
+
+**`client.metrics()` — built-in Prometheus text.** The same events feed a tiny in-memory registry
+that renders the Prometheus text exposition format (no third-party dep). Mount it at `GET /metrics`:
+
+```ts
+import { createServer } from "node:http"
+
+createServer((req, res) => {
+  if (req.url === "/metrics") {
+    res.setHeader("Content-Type", "text/plain; version=0.0.4")
+    res.end(agent.metrics())
+  } else {
+    res.statusCode = 404
+    res.end()
+  }
+}).listen(9090)
+```
+
+Series: `toolnexus_llm_requests_total{model,status}`, `toolnexus_llm_tokens_total{type}`,
+`toolnexus_tool_calls_total{tool,source,is_error}`, `toolnexus_run_errors_total{model}`, plus the
+`toolnexus_llm_request_duration_seconds` and `toolnexus_tool_duration_seconds` histograms. The
+rendered text is byte-identical across all five ports; OTLP push is a planned future companion.
 
 ## Add your own tools
 
@@ -52,64 +169,53 @@ with hooks, streaming (`agent.stream(...)`), retries/backoff, and conversation m
 import { defineTool, httpTool } from "toolnexus"
 
 tk.register(
-  // a plain function → a tool
+  // a plain function → a tool  (run returns a string or a full ToolResult)
   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)}`,
+    name: "add",
+    description: "Add two numbers",
+    inputSchema: {
+      type: "object",
+      properties: { a: { type: "number" }, b: { type: "number" } },
+      required: ["a", "b"],
+    },
+    run: (args) => `${(args.a as number) + (args.b as number)}`,
   }),
   // a REST endpoint → a tool
   httpTool({
-    name: "create_ticket", description: "Create a ticket", method: "POST",
+    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"] },
+    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>" }`.
-
-## Bring your own loop
-
-Don't want the host loop? Use the schema adapters and execute calls yourself:
-
-```ts
-const tools  = tk.toOpenAI()       // or tk.toAnthropic() / tk.toGemini()
-const system = tk.skillsPrompt()   // skills catalog for your system prompt (opens with a preamble telling the model to use the skill tool)
-// when the model returns a tool call { name, arguments }:
-const res = await tk.execute(name, args)   // -> { output, isError, metadata }
-```
-
-## The four sources
-
-| Source | How |
-|--------|-----|
-| **MCP servers** | an `mcp.json` (`mcpServers`/`servers`/`mcp`); local stdio + remote streamable-HTTP, `headers` for auth |
-| **Agent skills** | a folder of `<name>/SKILL.md`; a `skill` tool loads each on demand + a system-prompt catalog |
-| **Native tools** | `defineTool({...})` — a function becomes a tool |
-| **HTTP / REST** | `httpTool({...})` — an endpoint becomes a tool, `${ENV}` headers |
-
-All four appear as one uniform `Tool` in `tk.tools()`. Each is à la carte — use just `loadMcp(config)`
-or `loadSkills(dir)` if that's all you need.
+For `httpTool`: URL `{placeholders}` are filled from args; `query` arg names go to the
+querystring (all args on GET); the rest become the JSON body (`body: "json" | "form" | "raw"`).
+Non-2xx → `{ isError: true, output: "HTTP <status>: <body>" }`.
 
 ## Built-in tools
 
 A fifth source ships **10 built-in tools** — `bash`, `read`, `write`, `edit`, `grep`, `glob`,
-`webfetch`, `question`, `apply_patch`, `todowrite` (names + input schemas match
-opencode) — so an agent can act with zero wiring. They appear in the tool schema
+`webfetch`, `question`, `apply_patch`, `todowrite` (names + input schemas match opencode) — so an
+agent can act with zero wiring. They appear in the tool schema
 (`toOpenAI()`/`toAnthropic()`/`toGemini()`), like MCP tools — not the system prompt.
 
 **On by default.** One global toggle turns the whole source off, or a per-tool `tools` map
 disables individual builtins on the all-on baseline:
 
 ```ts
-const tk = await createToolkit({ mcpConfig: "./mcp.json", builtins: false })
+const tk = await createToolkit({ builtins: false })
 // also accepts { disabled: true } or { enabled: false }
 
 // per-tool: drop bash, keep the other nine (unknown names ignored; whole-source-off still wins)
-const tk2 = await createToolkit({ mcpConfig: "./mcp.json", builtins: { tools: { bash: false } } })
+const tk2 = await createToolkit({ builtins: { tools: { bash: false } } })
 ```
 
 `bash`/`write`/`edit`/`apply_patch` run commands and mutate the filesystem — the toggle is the
@@ -136,7 +242,7 @@ await tk.addAgent("https://writer.example.com/.well-known/agent-card.json")
 ```
 
 `agent({ card, headers?, timeout?, pollEvery? })` — `headers` support `${ENV}` expansion (never
-logged); `timeout` defaults to 300000ms, `pollEvery` to 1000ms. A config file can also carry an
+logged); `timeout` defaults to 300000ms, `pollEvery` to 1000ms. A config object can also carry an
 `agents` block (mirrors `mcpServers`). A failing agent is isolated — logged, contributes no tools,
 never fatal.
 
@@ -144,12 +250,8 @@ never fatal.
 built from your **SKILL.md skills** (never raw tools):
 
 ```ts
-import { createClient } from "toolnexus"
-
-const agent = createClient({ baseUrl: "https://openrouter.ai/api/v1", style: "openai", model: "openai/gpt-4o-mini" })
-
 const handle = await tk.serve("127.0.0.1:0", {
-  client: agent,
+  client: agent,                  // a createClient(...) instance fulfils each task
   a2a: {
     name: "research-agent",
     description: "Answers research questions.",
@@ -161,26 +263,62 @@ console.log(handle.url)   // GET /.well-known/agent-card.json ; POST / (SendMess
 await handle.stop()
 ```
 
-`serve(addr, { client, a2a?, onTask? })` fulfils each inbound `SendMessage` task via `client.run`.
-Task persistence is a pluggable `TaskStore` — in-memory default, `"file:<dir>"`, or your own.
+`serve(addr, { client, a2a?, onTask? })` fulfils each inbound `SendMessage` task via the client.
+Task persistence is a pluggable `TaskStore` — in-memory default, `"file:<dir>"`, or your own. And
+it **remembers**: a message's A2A `contextId` keys the conversation through `client.ask`, so a
+peer's turns in the same context carry history via the client's `ConversationStore`.
+
+## Bring your own loop
+
+Don't want the host loop? Use the schema adapters and execute calls yourself:
+
+```ts
+const tools  = tk.toOpenAI()       // or tk.toAnthropic() / tk.toGemini()
+const system = tk.skillsPrompt()   // skills catalog for your system prompt
+// when the model returns a tool call { name, arguments }:
+const res = await tk.execute(name, args)   // → { output, isError, metadata }
+```
+
+## The four sources
+
+| Source | How |
+|--------|-----|
+| **MCP servers** | an `mcp.json` (`mcpServers`/`servers`/`mcp`); local stdio + remote streamable-HTTP, `headers` for auth |
+| **Agent skills** | a folder of `<name>/SKILL.md`; a `skill` tool loads each on demand + a system-prompt catalog |
+| **Native tools** | `defineTool({...})` — a function becomes a tool |
+| **HTTP / REST** | `httpTool({...})` — an endpoint becomes a tool, `${ENV}` headers |
+
+All appear as one uniform `Tool` in `tk.tools()`. Built-ins are a fifth source; remote A2A agents
+a sixth.
 
 ## API
 
 | Member | Description |
 |--------|-------------|
-| `createToolkit(opts)` | async factory → `Toolkit` |
-| `createClient(opts)` | the unified host loop (`run` / `stream`) |
+| `createToolkit(opts)` | async factory → `Toolkit` (`mcpConfig`, `skillsDir`, `builtins`, `agents`, `extraTools`) |
+| `createClient(opts)` | the unified host loop (`baseUrl`, `style`, `model`, `store?`, `hooks?`, `maxTurns?`, `retries?`, `timeoutMs?`, `onMetric?`) |
+| `client.run(prompt, { toolkit, signal?, history? })` | stateless run → `RunResult` |
+| `client.ask(prompt, { toolkit, id?, on_text?, signal? })` | stateful with `id` (loads → runs → saves via `store`); one-shot without `id`; `on_text` streams text deltas |
+| `client.conversation({ toolkit })` | in-process multi-turn object — `.send(prompt)`, `.messages`, `.reset()` |
+| `client.stream(prompt, { toolkit, id? })` | async-iterate `StreamEvent`s (text deltas, tool calls/results, usage, done); `id` ⇒ stateful |
+| `client.metrics()` | Prometheus text exposition of cumulative metrics — mount at `GET /metrics` |
+| `ConversationStore` | `get(id)` / `save(id, messages)` — implement for file/db; default `InMemoryConversationStore` |
 | `tk.tools()` / `tk.get(name)` | the uniform tools |
+| `tk.register(...tools)` | add native/http/custom tools at runtime |
 | `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 |
+| `tk.serve(addr, { client, a2a?, onTask? })` | serve the toolkit as an A2A agent → `ServeHandle` |
+| `tk.addAgent(cardUrl \| Agent)` | fetch a remote agent's card and register its skills as tools |
 | `tk.close()` | disconnect MCP servers |
+| `defineTool` / `httpTool` / `agent` | build native / HTTP / A2A tools |
+| `InMemoryConversationStore` · `InMemoryTaskStore` / `FileTaskStore` | default stores (memory / A2A tasks) |
 
 ## More
 
-Full docs, the other four language ports, the shared behavior spec, and runnable examples:
-**https://github.com/muthuishere/toolnexus**
+Full docs, the other four language ports, and the shared cross-language behavior contract
+([`SPEC.md`](https://github.com/muthuishere/toolnexus/blob/main/SPEC.md)) — plus runnable
+`examples/`: **https://github.com/muthuishere/toolnexus**
 
 MIT licensed.

package/dist/client.d.ts

@@ -24,7 +24,37 @@ export interface ClientOptions {
     /** Conversation provider for `ask(prompt, { id })`. Default: in-memory (process lifetime).
      * Supply a file/db store to persist conversations across processes. */
     store?: ConversationStore;
+    /** Observability sink — receives semantic metric events ({event:"llm"|"tool"|"run"…}) as the
+     * loop runs (§8 Observability). Forward to statsd/logs/OTel/anything. No cost when unset. */
+    onMetric?: (ev: MetricEvent) => void;
 }
+/**
+ * Semantic observability events (§8). NOT counter/histogram primitives — readable records the
+ * host can forward anywhere. The same events also feed the built-in Prometheus registry
+ * (`client.metrics()`).
+ */
+export type MetricEvent = {
+    event: "llm";
+    model: string;
+    status: "ok" | "error";
+    ms: number;
+    promptTokens: number;
+    completionTokens: number;
+} | {
+    event: "tool";
+    tool: string;
+    source: string;
+    isError: boolean;
+    ms: number;
+} | {
+    event: "run";
+    model: string;
+    turns: number;
+    toolCalls: number;
+    totalTokens: number;
+    ms: number;
+    error?: string;
+};
 /**
  * Where `ask()` conversations are remembered — two methods. Ship the in-memory
  * default; implement this for a file/db/redis provider to persist across processes.
@@ -145,7 +175,17 @@ export declare class Client {
     private readonly opts;
     /** Conversation provider for `ask()` — from opts.store, else in-memory. */
     private readonly store;
+    /** Cumulative Prometheus registry fed by the same events `onMetric` sees. */
+    private readonly registry;
     constructor(opts: ClientOptions);
+    /** Prometheus text exposition of cumulative metrics (§8). Always valid, empty-but-valid before activity. */
+    metrics(): string;
+    /** Feed a semantic metric event to the built-in registry and the optional onMetric sink. */
+    private emit;
+    /** Emit the terminal `run` metric event and build the RunResult. */
+    private endRun;
+    /** Emit a `run` error metric event (once, on a thrown run). */
+    private emitRunError;
     run(prompt: string, ctx: {
         toolkit: Toolkit;
         signal?: AbortSignal;
@@ -160,6 +200,7 @@ export declare class Client {
     ask(prompt: string, ctx: {
         toolkit: Toolkit;
         id?: string;
+        on_text?: (delta: string) => void;
         signal?: AbortSignal;
     }): Promise<RunResult>;
     /** A stateful multi-turn conversation that retains history across sends. */
@@ -167,9 +208,14 @@ export declare class Client {
         toolkit: Toolkit;
         signal?: AbortSignal;
     }): Conversation;
-    /** Streaming variant: async-iterate live events (text deltas, tool calls/results, usage, done). */
+    /**
+     * Streaming variant: async-iterate live events (text deltas, tool calls/results, usage, done).
+     * With an `id`, it is stateful (like `ask`): the thread's transcript is loaded as history before
+     * streaming, and saved back to the ConversationStore on the terminal `done` event. No `id` ⇒ stateless.
+     */
     stream(prompt: string, ctx: {
         toolkit: Toolkit;
+        id?: string;
         signal?: AbortSignal;
     }): AsyncGenerator<StreamEvent, void, unknown>;
     private system;
@@ -179,6 +225,8 @@ export declare class Client {
     private llmFetch;
     /** Run one tool through beforeTool/afterTool hooks (mutate args, short-circuit, transform result). */
     private runTool;
+    /** One non-streaming LLM call, with an `llm` metric event (ok/error + per-call tokens + ms). */
+    private llmCallJson;
     private runOpenAI;
     private result;
     private runAnthropic;