toolnexus 0.1.1 → 0.2.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

@@ -1,8 +1,19 @@
-# toolnexus (JavaScript / TypeScript)
+# toolnexus
 
-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.
+[![npm](https://img.shields.io/npm/v/toolnexus?logo=npm&label=npm)](https://www.npmjs.com/package/toolnexus)
+[![license](https://img.shields.io/badge/license-MIT-green)](https://github.com/muthuishere/toolnexus/blob/main/LICENSE)
+
+**Build an agent in a few lines.** Point at an `mcp.json` and a `skills/` folder, call `run()`,
+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.
+
+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
+`@modelcontextprotocol/sdk` (the MCP SDK opencode uses).
 
 ## Install
 
@@ -10,107 +21,166 @@ Dynamic MCP servers + agent skills as a uniform tool list for any LLM. Built on
 npm install toolnexus
 ```
 
-## Use
+## An agent in 3 steps
 
 ```ts
-import { createToolkit } from "toolnexus"
+import { createToolkit, createClient } 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. 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 agent = createClient({
+  baseUrl: "https://openrouter.ai/api/v1",
+  style: "openai",                  // or "anthropic"
+  model: "openai/gpt-4o-mini",
 })
 
-// 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
+// 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 })
+console.log(text)
+await tk.close()
+```
 
-// 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.
+`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.
 
-console.log(tk.mcpStatus())  // { server: "connected" | "failed" | "disabled" }
-await tk.close()
+## Add your own tools
+
+```ts
+import { defineTool, httpTool } from "toolnexus"
+
+tk.register(
+  // a plain function → a tool
+  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)}`,
+  }),
+  // a REST endpoint → a tool
+  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"] },
+  }),
+)
 ```
 
-## Run the examples
+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>" }`.
 
-```sh
-npm install && npm run build
+## Bring your own loop
 
-# offline: connects to @modelcontextprotocol/server-everything via npx, lists tools, loads a skill
-node --experimental-strip-types examples/basic.ts
+Don't want the host loop? Use the schema adapters and execute calls yourself:
 
-# live: real OpenRouter tool-calling round trip (needs OPENROUTER_API_KEY)
-OPENROUTER_API_KEY=... node --experimental-strip-types examples/openrouter_test.ts
+```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 }
 ```
 
-## API
+## The four sources
 
-| 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 |
+| 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 |
 
-You can also use the sources directly: `loadMcp(config)`, `loadSkills(dir)`.
+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.
 
-## Native tools (a function → a tool)
+## 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
+(`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
-import { defineTool } from "toolnexus"
+const tk = await createToolkit({ mcpConfig: "./mcp.json", builtins: false })
+// also accepts { disabled: true } or { enabled: false }
 
-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)
+// 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 } } })
 ```
 
-## HTTP / REST tools (an endpoint → a tool)
+`bash`/`write`/`edit`/`apply_patch` run commands and mutate the filesystem — the toggle is the
+off-switch for locked-down hosts.
+
+## A2A agents (agent-to-agent)
+
+Call **remote A2A agents** (each of their skills becomes a tool) and serve your own toolkit as an
+agent other A2A peers can call. A genuine, minimal subset of real A2A (JSON-RPC 2.0; Agent Card at
+`/.well-known/agent-card.json`; `SendMessage` → poll `GetTask`). No streaming / push / auth in v1.
+
+**Outbound — call a remote agent.** Each advertised skill becomes a tool named `<agent>_<skill>`
+(`source: "a2a"`):
 
 ```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"] },
-}))
+import { createToolkit, agent } from "toolnexus"
+
+const tk = await createToolkit({
+  agents: [agent({ card: "https://researcher.example.com/.well-known/agent-card.json" })],
+})
+
+// or add one at runtime (an Agent descriptor or a bare card URL):
+await tk.addAgent("https://writer.example.com/.well-known/agent-card.json")
 ```
 
-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>" }`.
+`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
+`agents` block (mirrors `mcpServers`). A failing agent is isolated — logged, contributes no tools,
+never fatal.
 
-## Unified client (the host loop)
+**Inbound — serve your toolkit as an agent.** Opt in with the `a2a` profile; the Agent Card is
+built from your **SKILL.md skills** (never raw tools):
 
 ```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 agent = createClient({ baseUrl: "https://openrouter.ai/api/v1", style: "openai", model: "openai/gpt-4o-mini" })
 
-const { text, toolCalls } = await agent.run("do the thing", { toolkit: tk })
+const handle = await tk.serve("127.0.0.1:0", {
+  client: agent,
+  a2a: {
+    name: "research-agent",
+    description: "Answers research questions.",
+    // skills: ["hello-world"],   // subset of skills to advertise; omit ⇒ all
+    store: "memory",              // "memory" (default) | "file:<dir>" | a custom TaskStore
+  },
+})
+console.log(handle.url)   // GET /.well-known/agent-card.json ; POST / (SendMessage / GetTask)
+await handle.stop()
 ```
 
-It injects `tk.skillsPrompt()` into the system message and runs the full
-call → execute tools → feed back → repeat loop (up to `maxTurns`, default 10).
+`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.
+
+## API
+
+| Member | Description |
+|--------|-------------|
+| `createToolkit(opts)` | async factory → `Toolkit` |
+| `createClient(opts)` | the unified host loop (`run` / `stream`) |
+| `tk.tools()` / `tk.get(name)` | the uniform tools |
+| `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.close()` | disconnect MCP servers |
+
+## More
 
-## Examples
+Full docs, the other four language ports, the shared behavior spec, and runnable examples:
+**https://github.com/muthuishere/toolnexus**
 
-- `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.
+MIT licensed.

package/dist/a2a.d.ts

@@ -0,0 +1,86 @@
+import { type Tool } from "./types.js";
+export type A2ATaskState = "submitted" | "working" | "completed" | "failed" | "canceled" | string;
+export interface A2APart {
+    kind: string;
+    text?: string;
+    [k: string]: unknown;
+}
+export interface A2AMessage {
+    role: string;
+    messageId?: string;
+    parts?: A2APart[];
+    [k: string]: unknown;
+}
+export interface A2AArtifact {
+    parts?: A2APart[];
+    [k: string]: unknown;
+}
+export interface A2ATaskStatus {
+    state: A2ATaskState;
+    message?: A2AMessage;
+    [k: string]: unknown;
+}
+export interface A2ATask {
+    id: string;
+    status: A2ATaskStatus;
+    artifacts?: A2AArtifact[];
+    history?: A2AMessage[];
+    [k: string]: unknown;
+}
+export interface A2ASkill {
+    id?: string;
+    name?: string;
+    description?: string;
+    tags?: string[];
+    examples?: string[];
+    [k: string]: unknown;
+}
+export interface AgentCard {
+    name: string;
+    description?: string;
+    version?: string;
+    protocolVersion?: string;
+    capabilities?: {
+        streaming?: boolean;
+        pushNotifications?: boolean;
+        [k: string]: unknown;
+    };
+    defaultInputModes?: string[];
+    defaultOutputModes?: string[];
+    skills?: A2ASkill[];
+    /** The JSON-RPC endpoint the agent listens on. */
+    url?: string;
+    [k: string]: unknown;
+}
+export interface Agent {
+    /** URL of the Agent Card (`/.well-known/agent-card.json`). */
+    card: string;
+    /** `${ENV_VAR}` header values are expanded at call time and never logged. */
+    headers?: Record<string, string>;
+    /** Overall poll budget in ms (default 300000). */
+    timeout?: number;
+    /** Interval between `GetTask` polls in ms (default 1000). */
+    pollEvery?: number;
+}
+/** Build an Agent descriptor pointing at a remote Agent Card URL. */
+export declare function agent(opts: Agent): Agent;
+export interface AgentConfig {
+    card: string;
+    headers?: Record<string, string>;
+    timeout?: number;
+    pollEvery?: number;
+    enabled?: boolean;
+    disabled?: boolean;
+}
+export type AgentsConfig = Record<string, AgentConfig>;
+/**
+ * Parse an `agents` block (Record<name, AgentConfig>) into Agent descriptors,
+ * skipping disabled entries. The config key is just an identifier — a tool's
+ * name prefix comes from the fetched card's `name`, not the key.
+ */
+export declare function parseAgentsConfig(block: AgentsConfig | undefined): Agent[];
+/**
+ * Resolve an Agent to its tools: fetch the card, read `skills[]`, and produce
+ * one Tool per skill. The agent name prefix comes from the card's `name`.
+ */
+export declare function agentTools(ag: Agent): Promise<Tool[]>;

package/dist/a2a.js

@@ -0,0 +1,254 @@
+/**
+ * A2A (agent-to-agent) — OUTBOUND: call remote A2A agents.
+ *
+ * A remote agent publishes an Agent Card at `/.well-known/agent-card.json`
+ * describing its skills. Each advertised skill becomes a uniform `Tool`
+ * (source:"a2a") whose `execute` performs one JSON-RPC `SendMessage`
+ * (non-blocking) to get a Task id, then polls `GetTask` until the Task reaches
+ * a terminal state — mapping the Task's artifact/message text to a ToolResult.
+ *
+ * This is a genuine subset of real A2A (JSON-RPC 2.0 over one HTTP POST
+ * endpoint), so a toolnexus agent interoperates with real A2A peers. See
+ * ../../SPEC.md and openspec/changes/add-a2a-agents. Reuses the `${ENV}` header
+ * expansion from mcp.ts; secrets live in the environment and are never logged.
+ */
+import { randomUUID } from "node:crypto";
+import { sanitize } from "./types.js";
+import { expandEnvHeaders } from "./mcp.js";
+const DEFAULT_TIMEOUT = 300_000;
+const DEFAULT_POLL_EVERY = 1_000;
+/** Terminal A2A task states — polling stops once one of these is reached. */
+const TERMINAL = new Set(["completed", "failed", "canceled"]);
+/** Build an Agent descriptor pointing at a remote Agent Card URL. */
+export function agent(opts) {
+    return { card: opts.card, headers: opts.headers, timeout: opts.timeout, pollEvery: opts.pollEvery };
+}
+/** Normalize either an Agent descriptor or a bare card URL into an Agent. */
+function toAgent(agentOrCardUrl, opts) {
+    if (typeof agentOrCardUrl === "string")
+        return agent({ card: agentOrCardUrl, ...opts });
+    return agentOrCardUrl;
+}
+/** MCP `isEnabled` precedence: `disabled:true` wins, then `enabled:false`. */
+function isEnabled(cfg) {
+    if (cfg.disabled === true)
+        return false;
+    if (cfg.enabled === false)
+        return false;
+    return true;
+}
+/**
+ * Parse an `agents` block (Record<name, AgentConfig>) into Agent descriptors,
+ * skipping disabled entries. The config key is just an identifier — a tool's
+ * name prefix comes from the fetched card's `name`, not the key.
+ */
+export function parseAgentsConfig(block) {
+    if (!block)
+        return [];
+    const out = [];
+    for (const cfg of Object.values(block)) {
+        if (!cfg || typeof cfg.card !== "string")
+            continue;
+        if (!isEnabled(cfg))
+            continue;
+        out.push(agent({ card: cfg.card, headers: cfg.headers, timeout: cfg.timeout, pollEvery: cfg.pollEvery }));
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// JSON-RPC transport (single POST) + card fetch. Reuses httpTool's ${ENV}
+// header expansion, timeout handling, and non-2xx → error mapping.
+// ---------------------------------------------------------------------------
+/** POST one JSON-RPC 2.0 request and return `result` (throws on error/non-2xx). */
+async function jsonRpc(endpoint, method, params, headers, timeout, signal) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeout);
+    if (signal)
+        signal.addEventListener("abort", () => controller.abort(), { once: true });
+    try {
+        const res = await fetch(endpoint, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", ...headers },
+            body: JSON.stringify({ jsonrpc: "2.0", id: randomUUID(), method, params }),
+            signal: controller.signal,
+        });
+        const text = await res.text();
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}: ${text}`);
+        const payload = safeParse(text);
+        if (payload && payload.error) {
+            throw new Error(payload.error.message ?? `JSON-RPC error ${payload.error.code ?? ""}`.trim());
+        }
+        return payload?.result;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Fetch and parse the Agent Card at its URL (GET). */
+async function fetchCard(cardUrl, headers, timeout, signal) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeout);
+    if (signal)
+        signal.addEventListener("abort", () => controller.abort(), { once: true });
+    try {
+        const res = await fetch(cardUrl, { method: "GET", headers, signal: controller.signal });
+        const text = await res.text();
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}: ${text}`);
+        return JSON.parse(text);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function safeParse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Abortable sleep — resolves early (without error) if `signal` fires. */
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted)
+            return resolve();
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/** Concatenate a Task's text output: artifact text parts, else last agent message. */
+function extractOutput(task) {
+    const parts = [];
+    for (const artifact of task.artifacts ?? []) {
+        for (const part of artifact.parts ?? []) {
+            if (part.kind === "text" && typeof part.text === "string")
+                parts.push(part.text);
+        }
+    }
+    if (parts.length > 0)
+        return parts.join("\n");
+    // Fallback: the last agent message in history.
+    const history = task.history ?? [];
+    for (let i = history.length - 1; i >= 0; i--) {
+        const msg = history[i];
+        if (msg.role !== "agent")
+            continue;
+        const text = (msg.parts ?? [])
+            .filter((p) => p.kind === "text" && typeof p.text === "string")
+            .map((p) => p.text)
+            .join("\n");
+        if (text)
+            return text;
+    }
+    return "";
+}
+/** Text of a Task's status.message (used for failed/canceled error output). */
+function statusMessageText(task) {
+    const msg = task.status?.message;
+    if (!msg)
+        return "";
+    return (msg.parts ?? [])
+        .filter((p) => p.kind === "text" && typeof p.text === "string")
+        .map((p) => p.text)
+        .join("\n");
+}
+// ---------------------------------------------------------------------------
+// Skill → Tool.
+// ---------------------------------------------------------------------------
+const TASK_SCHEMA = {
+    type: "object",
+    properties: { task: { type: "string", description: "The task to send to the agent, in natural language." } },
+    required: ["task"],
+    additionalProperties: false,
+};
+/** Build one `source:"a2a"` Tool for a single advertised skill of an agent. */
+function skillTool(agentName, endpoint, skill, ag) {
+    const skillId = skill.id ?? skill.name ?? "";
+    const name = sanitize(agentName) + "_" + sanitize(skillId);
+    const timeout = ag.timeout ?? DEFAULT_TIMEOUT;
+    const pollEvery = ag.pollEvery ?? DEFAULT_POLL_EVERY;
+    return {
+        name,
+        description: skill.description ?? skill.name ?? skillId,
+        inputSchema: TASK_SCHEMA,
+        source: "a2a",
+        async execute(args, ctx) {
+            const start = Date.now();
+            const budget = ctx?.timeout ?? timeout;
+            const headers = expandEnvHeaders(ag.headers) ?? {};
+            const taskText = String(args?.task ?? "");
+            let polls = 0;
+            let taskId = "";
+            let state = "submitted";
+            const meta = () => ({ agent: agentName, taskId, state, polls, ms: Date.now() - start });
+            try {
+                // 1. SendMessage (non-blocking) → a submitted Task.
+                let task = (await jsonRpc(endpoint, "SendMessage", {
+                    message: { role: "user", messageId: randomUUID(), parts: [{ kind: "text", text: taskText }] },
+                    configuration: { blocking: false },
+                }, headers, budget, ctx?.signal));
+                taskId = task?.id ?? "";
+                state = task?.status?.state ?? "submitted";
+                // 2. Poll GetTask until terminal / timeout / cancel.
+                while (!TERMINAL.has(state)) {
+                    if (ctx?.signal?.aborted) {
+                        state = "canceled";
+                        return { output: `A2A task ${taskId} canceled`, isError: true, metadata: meta() };
+                    }
+                    if (Date.now() - start >= budget) {
+                        return {
+                            output: `A2A task ${taskId} timed out after ${budget}ms (state=${state})`,
+                            isError: true,
+                            metadata: meta(),
+                        };
+                    }
+                    await sleep(pollEvery, ctx?.signal);
+                    // Cancelled during the wait → stop before another GetTask.
+                    if (ctx?.signal?.aborted) {
+                        state = "canceled";
+                        return { output: `A2A task ${taskId} canceled`, isError: true, metadata: meta() };
+                    }
+                    task = (await jsonRpc(endpoint, "GetTask", { id: taskId }, headers, budget, ctx?.signal));
+                    polls++;
+                    state = task?.status?.state ?? state;
+                }
+                // 3. Map the terminal Task → ToolResult.
+                if (state === "completed") {
+                    return { output: extractOutput(task), isError: false, metadata: meta() };
+                }
+                const detail = statusMessageText(task);
+                return {
+                    output: `A2A task ${taskId} ${state}${detail ? `: ${detail}` : ""}`,
+                    isError: true,
+                    metadata: meta(),
+                };
+            }
+            catch (e) {
+                return { output: e instanceof Error ? e.message : String(e), isError: true, metadata: meta() };
+            }
+        },
+    };
+}
+/**
+ * Resolve an Agent to its tools: fetch the card, read `skills[]`, and produce
+ * one Tool per skill. The agent name prefix comes from the card's `name`.
+ */
+export async function agentTools(ag) {
+    const timeout = ag.timeout ?? DEFAULT_TIMEOUT;
+    const headers = expandEnvHeaders(ag.headers) ?? {};
+    const card = await fetchCard(ag.card, headers, timeout);
+    const agentName = card.name ?? "agent";
+    // The card's `url` is the JSON-RPC endpoint; fall back to the card origin.
+    const endpoint = card.url ?? new URL(ag.card).origin;
+    return (card.skills ?? []).map((skill) => skillTool(agentName, endpoint, skill, ag));
+}

package/dist/builtin.d.ts

@@ -0,0 +1,25 @@
+import type { Tool } from "./types.js";
+/** Config for the single global builtin toggle (mirrors MCP isEnabled precedence). */
+export type BuiltinsConfig = boolean | {
+    enabled?: boolean;
+    disabled?: boolean;
+    tools?: Record<string, boolean>;
+};
+/**
+ * Whether the builtin source is on. Default ON. Same precedence as MCP:
+ * `disabled:true` wins, else `enabled:false` disables, otherwise enabled.
+ */
+export declare function builtinsEnabled(cfg: BuiltinsConfig | undefined): boolean;
+/**
+ * Resolve the active builtin tools for a config. Whole-source-off wins and
+ * returns `[]`. Otherwise all ten are on; a `tools` name→bool map drops any
+ * tool mapped to `false` (all-on baseline; `true`/absent stay on; unknown names
+ * are ignored). SPEC §4A.
+ */
+export declare function selectBuiltins(cfg: BuiltinsConfig | undefined): Tool[];
+/**
+ * Build the ten built-in tools (each source:"builtin"). The order is fixed
+ * for parity: bash, read, write, edit, grep, glob, webfetch, question,
+ * apply_patch, todowrite.
+ */
+export declare function createBuiltinTools(): Tool[];