toolnexus 0.1.2 → 0.2.0

package/README.md

@@ -77,7 +77,7 @@ 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()   // markdown skills catalog for your system prompt
+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 }
 ```
@@ -94,6 +94,76 @@ const res = await tk.execute(name, args)   // -> { output, isError, metadata }
 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.
 
+## 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
+const tk = await createToolkit({ mcpConfig: "./mcp.json", 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 } } })
+```
+
+`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 { 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")
+```
+
+`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.
+
+**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", style: "openai", model: "openai/gpt-4o-mini" })
+
+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()
+```
+
+`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 |

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[];