toolnexus 0.1.2 → 0.2.1

package/dist/serve.d.ts

@@ -0,0 +1,78 @@
+import type { SkillInfo } from "./skill.js";
+import type { RunResult } from "./client.js";
+import type { A2ATask, A2ATaskState, AgentCard } from "./a2a.js";
+/** Pluggable Task persistence. The-factory can plug NATS/JetStream the same way. */
+export interface TaskStore {
+    get(id: string): Promise<A2ATask | undefined>;
+    save(task: A2ATask): Promise<void>;
+}
+/** Default in-memory store — Tasks live only for the lifetime of the process. */
+export declare class InMemoryTaskStore implements TaskStore {
+    private readonly tasks;
+    get(id: string): Promise<A2ATask | undefined>;
+    save(task: A2ATask): Promise<void>;
+}
+/** File-backed store — one JSON file per Task id, under `dir`. */
+export declare class FileTaskStore implements TaskStore {
+    private readonly dir;
+    constructor(dir: string);
+    private file;
+    get(id: string): Promise<A2ATask | undefined>;
+    save(task: A2ATask): Promise<void>;
+}
+/** Map a `store` selector to a concrete TaskStore. `"file:<dir>"` → FileTaskStore. */
+export declare function resolveStore(store?: TaskStore | "memory" | string): TaskStore;
+export interface A2AProvider {
+    organization: string;
+    url: string;
+}
+/** Opt-in A2A profile for `toolkit.serve` — configures the Agent Card + store. */
+export interface A2AConfig {
+    name?: string;
+    description?: string;
+    version?: string;
+    provider?: A2AProvider;
+    /** Subset of the toolkit's skill ids/names to advertise; omit ⇒ all. */
+    skills?: string[];
+    /** `"memory"` (default) | `"file:<dir>"` | a custom TaskStore. */
+    store?: TaskStore | "memory" | string;
+}
+/** Surfaced on each Task's terminal state, carrying the RunResult telemetry. */
+export interface OnTaskEvent {
+    id: string;
+    skill?: string;
+    task: A2ATask;
+    result?: RunResult;
+    state: A2ATaskState;
+}
+export type OnTask = (ev: OnTaskEvent) => void | Promise<void>;
+/** Handle returned by `toolkit.serve` — the base URL plus a stop/close method. */
+export interface ServeHandle {
+    /** Base URL of the server, e.g. `http://127.0.0.1:PORT`. */
+    url: string;
+    stop(): Promise<void>;
+    /** Alias for `stop()`. */
+    close(): Promise<void>;
+}
+/**
+ * Build an Agent Card from the toolkit's skills. `skills` are the SkillSource's
+ * `SkillInfo`s (never raw tools); filtered to `cfg.skills` when given. `url` is
+ * the JSON-RPC endpoint peers POST to.
+ */
+export declare function buildAgentCard(cfg: A2AConfig, skills: SkillInfo[], url: string): AgentCard;
+export interface StartServerOptions {
+    /** `host:port` (port 0 ⇒ ephemeral). */
+    addr: string;
+    /** When present, mounts the A2A card + JSON-RPC routes; absent ⇒ no A2A routes. */
+    a2a?: A2AConfig;
+    /** The toolkit's skills, for the card. */
+    skills: SkillInfo[];
+    /** Runs one served Task through the client loop. */
+    runTask: (text: string) => Promise<RunResult>;
+    onTask?: OnTask;
+}
+/**
+ * Start the HTTP server. Delegated to by `Toolkit.serve`. When `a2a` is absent,
+ * the server answers 404 to everything (a minimal base for now).
+ */
+export declare function startA2AServer(opts: StartServerOptions): Promise<ServeHandle>;

package/dist/serve.js

@@ -0,0 +1,243 @@
+/**
+ * A2A (agent-to-agent) — INBOUND: serve a toolkit as a remote A2A agent.
+ *
+ * `toolkit.serve(addr, { client, a2a })` stands up a minimal HTTP server that,
+ * when the `a2a` profile is present, exposes:
+ *
+ *   GET  /.well-known/agent-card.json  → an Agent Card built from the toolkit's
+ *        **skills** (SKILL.md name+description), never raw tools.
+ *   POST /                             → JSON-RPC 2.0: `SendMessage` (submit a
+ *        Task, fulfil it asynchronously via `client.run`) + `GetTask` (poll).
+ *
+ * This is the inbound counterpart to a2a.ts (outbound) and speaks the same wire
+ * subset (verified against a2a-python). Task persistence is a pluggable
+ * `TaskStore` (in-memory default; file / custom selectable via `a2a.store`).
+ * See ../../SPEC.md and openspec/changes/add-a2a-agents.
+ */
+import http from "node:http";
+import fs from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { sanitize } from "./types.js";
+/** Default in-memory store — Tasks live only for the lifetime of the process. */
+export class InMemoryTaskStore {
+    tasks = new Map();
+    async get(id) {
+        return this.tasks.get(id);
+    }
+    async save(task) {
+        this.tasks.set(task.id, task);
+    }
+}
+/** File-backed store — one JSON file per Task id, under `dir`. */
+export class FileTaskStore {
+    dir;
+    constructor(dir) {
+        this.dir = dir;
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    file(id) {
+        return path.join(this.dir, `${sanitize(id)}.json`);
+    }
+    async get(id) {
+        try {
+            return JSON.parse(fs.readFileSync(this.file(id), "utf8"));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async save(task) {
+        fs.writeFileSync(this.file(task.id), JSON.stringify(task));
+    }
+}
+/** Map a `store` selector to a concrete TaskStore. `"file:<dir>"` → FileTaskStore. */
+export function resolveStore(store) {
+    if (store === undefined || store === "memory")
+        return new InMemoryTaskStore();
+    if (typeof store === "string") {
+        if (store.startsWith("file:"))
+            return new FileTaskStore(store.slice("file:".length));
+        throw new Error(`Unknown A2A store: "${store}" (expected "memory" or "file:<dir>")`);
+    }
+    return store;
+}
+// ---------------------------------------------------------------------------
+// Card builder.
+// ---------------------------------------------------------------------------
+const PROTOCOL_VERSION = "0.3.0";
+const DEFAULT_VERSION = "0.1.0";
+/**
+ * Build an Agent Card from the toolkit's skills. `skills` are the SkillSource's
+ * `SkillInfo`s (never raw tools); filtered to `cfg.skills` when given. `url` is
+ * the JSON-RPC endpoint peers POST to.
+ */
+export function buildAgentCard(cfg, skills, url) {
+    const wanted = cfg.skills;
+    const selected = wanted ? skills.filter((s) => wanted.includes(s.name)) : skills;
+    const card = {
+        name: cfg.name ?? "toolnexus-agent",
+        description: cfg.description ?? "",
+        version: cfg.version ?? DEFAULT_VERSION,
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: { streaming: false, pushNotifications: false },
+        defaultInputModes: ["text"],
+        defaultOutputModes: ["text"],
+        skills: selected.map((s) => ({ id: s.name, name: s.name, description: s.description ?? "" })),
+        url,
+    };
+    if (cfg.provider)
+        card.provider = cfg.provider;
+    return card;
+}
+// ---------------------------------------------------------------------------
+// Server.
+// ---------------------------------------------------------------------------
+const CARD_PATH = "/.well-known/agent-card.json";
+/** Extract the concatenated text of a JSON-RPC `SendMessage` message's parts. */
+function messageText(params) {
+    const parts = params?.message?.parts;
+    if (!Array.isArray(parts))
+        return "";
+    return parts
+        .filter((p) => p && p.kind === "text" && typeof p.text === "string")
+        .map((p) => p.text)
+        .join("");
+}
+function readBody(req) {
+    return new Promise((resolve) => {
+        let body = "";
+        req.on("data", (c) => (body += c));
+        req.on("end", () => resolve(body));
+    });
+}
+/**
+ * Start the HTTP server. Delegated to by `Toolkit.serve`. When `a2a` is absent,
+ * the server answers 404 to everything (a minimal base for now).
+ */
+export async function startA2AServer(opts) {
+    const { a2a, skills, runTask, onTask } = opts;
+    const [host, portStr] = splitAddr(opts.addr);
+    const store = a2a ? resolveStore(a2a.store) : undefined;
+    const server = http.createServer((req, res) => {
+        const rpcRes = (id, payload) => {
+            res.writeHead(200, { "content-type": "application/json" });
+            res.end(JSON.stringify({ jsonrpc: "2.0", id: id ?? null, ...payload }));
+        };
+        const rpcOk = (id, result) => rpcRes(id, { result });
+        const rpcErr = (id, code, message) => rpcRes(id, { error: { code, message } });
+        // No A2A profile ⇒ no routes.
+        if (!a2a || !store) {
+            res.writeHead(404);
+            res.end("not found");
+            return;
+        }
+        if (req.method === "GET" && req.url === CARD_PATH) {
+            const url = baseUrl(host, server) + "/";
+            res.writeHead(200, { "content-type": "application/json" });
+            res.end(JSON.stringify(buildAgentCard(a2a, skills, url)));
+            return;
+        }
+        if (req.method === "POST") {
+            readBody(req).then((body) => {
+                let rpc;
+                try {
+                    rpc = JSON.parse(body);
+                }
+                catch {
+                    return rpcErr(null, -32700, "Parse error");
+                }
+                if (rpc?.method === "SendMessage") {
+                    const text = messageText(rpc.params);
+                    const id = randomUUID();
+                    const submitted = { id, status: { state: "submitted" } };
+                    // Persist submitted, kick fulfilment async, return the id immediately.
+                    store.save(submitted).then(() => {
+                        void fulfil(id, text, store, runTask, onTask);
+                        rpcOk(rpc.id, submitted);
+                    });
+                    return;
+                }
+                if (rpc?.method === "GetTask") {
+                    const id = String(rpc.params?.id ?? "");
+                    store.get(id).then((task) => {
+                        if (!task)
+                            return rpcErr(rpc.id, -32001, `Task not found: ${id}`);
+                        rpcOk(rpc.id, task);
+                    });
+                    return;
+                }
+                return rpcErr(rpc?.id ?? null, -32601, `Method not found: ${rpc?.method}`);
+            });
+            return;
+        }
+        res.writeHead(404);
+        res.end("not found");
+    });
+    await new Promise((resolve) => server.listen(Number(portStr), host, resolve));
+    return {
+        url: baseUrl(host, server),
+        stop() {
+            return new Promise((resolve) => server.close(() => resolve()));
+        },
+        close() {
+            return new Promise((resolve) => server.close(() => resolve()));
+        },
+    };
+}
+/**
+ * Background fulfilment: submitted → working → (completed | failed). Never
+ * throws — a fulfilment error becomes a `failed` Task, keeping the server alive.
+ */
+async function fulfil(id, text, store, runTask, onTask) {
+    let task;
+    let result;
+    let state;
+    try {
+        await store.save({ id, status: { state: "working" } });
+        result = await runTask(text);
+        const artifact = {
+            artifactId: randomUUID(),
+            parts: [{ kind: "text", text: result.text }],
+        };
+        task = { id, status: { state: "completed" }, artifacts: [artifact] };
+        state = "completed";
+    }
+    catch (e) {
+        const detail = e instanceof Error ? e.message : String(e);
+        task = { id, status: { state: "failed", message: { role: "agent", parts: [{ kind: "text", text: detail }] } } };
+        state = "failed";
+    }
+    try {
+        await store.save(task);
+    }
+    catch {
+        // A store write failure must not crash the server.
+    }
+    if (onTask) {
+        try {
+            await onTask({ id, task, result, state });
+        }
+        catch {
+            // Host callback errors are isolated.
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Address helpers.
+// ---------------------------------------------------------------------------
+/** Split `host:port` on the last colon. Missing host ⇒ 127.0.0.1. */
+function splitAddr(addr) {
+    const idx = addr.lastIndexOf(":");
+    if (idx === -1)
+        return ["127.0.0.1", addr];
+    const host = addr.slice(0, idx) || "127.0.0.1";
+    return [host, addr.slice(idx + 1)];
+}
+/** Base URL for a listening server; 0.0.0.0 is reported as 127.0.0.1 for callers. */
+function baseUrl(host, server) {
+    const addr = server.address();
+    const port = typeof addr === "object" && addr ? addr.port : 0;
+    const h = host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host;
+    return `http://${h}:${port}`;
+}

package/dist/skill.d.ts

@@ -1,5 +1,10 @@
 import type { Tool } from "./types.js";
 export declare const SKILL_TOOL_DESCRIPTION = "Load a specialized skill when the task at hand matches one of the skills listed in the system prompt.\n\nUse this tool to inject the skill's instructions and resources into current conversation. The output may contain detailed workflow guidance as well as references to scripts, files, etc in the same directory as the skill.\n\nThe skill name must match one of the skills listed in your system prompt.";
+/**
+ * Instruction preamble prepended to skillsPrompt() when ≥1 described skill
+ * exists. Byte-identical across all four ports — do not reword. See SPEC.md §3.
+ */
+export declare const SKILLS_PROMPT_PREAMBLE: string;
 export interface SkillInfo {
     name: string;
     description?: string;

package/dist/skill.js

@@ -4,38 +4,55 @@
  * loads a skill's instructions + sampled resources on demand (progressive
  * disclosure).
  */
-import { readFileSync, readdirSync, statSync } from "node:fs";
+import { readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
+import { parse as parseYaml } from "yaml";
 export const SKILL_TOOL_DESCRIPTION = `Load a specialized skill when the task at hand matches one of the skills listed in the system prompt.
 
 Use this tool to inject the skill's instructions and resources into current conversation. The output may contain detailed workflow guidance as well as references to scripts, files, etc in the same directory as the skill.
 
 The skill name must match one of the skills listed in your system prompt.`;
-/** Minimal YAML frontmatter parser — only flat `key: value` pairs are needed. */
+/**
+ * Instruction preamble prepended to skillsPrompt() when ≥1 described skill
+ * exists. Byte-identical across all four ports — do not reword. See SPEC.md §3.
+ */
+export const SKILLS_PROMPT_PREAMBLE = "Skills provide specialized instructions and workflows for specific tasks.\n" +
+    "Use the skill tool to load a skill when a task matches its description.";
+/**
+ * Parse YAML frontmatter (between the leading `---` fences) with a real YAML
+ * parser, so folded (`>`)/literal (`|`) block scalars, quoting, and multi-line
+ * values all resolve correctly. Scalar values are coerced to strings.
+ */
 function parseFrontmatter(text) {
     const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(text);
     if (!match)
         return { data: {}, content: text };
     const data = {};
-    for (const line of match[1].split(/\r?\n/)) {
-        const idx = line.indexOf(":");
-        if (idx === -1)
-            continue;
-        const key = line.slice(0, idx).trim();
-        let value = line.slice(idx + 1).trim();
-        if ((value.startsWith('"') && value.endsWith('"')) ||
-            (value.startsWith("'") && value.endsWith("'"))) {
-            value = value.slice(1, -1);
+    let parsed;
+    try {
+        parsed = parseYaml(match[1]);
+    }
+    catch {
+        parsed = null;
+    }
+    if (parsed && typeof parsed === "object") {
+        for (const [key, value] of Object.entries(parsed)) {
+            // Trim so block-scalar trailing newlines (chomping differs subtly between
+            // YAML libs) don't leak — keeps the five ports byte-identical.
+            if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+                data[key] = String(value).trim();
+            }
         }
-        if (key)
-            data[key] = value;
     }
     return { data, content: match[2] };
 }
 function walkSkillFiles(root) {
     const out = [];
     const stack = [root];
+    // Follow symlinked directories (like opencode's `symlink: true` glob); guard
+    // against symlink cycles by tracking resolved real paths already visited.
+    const seen = new Set();
     while (stack.length) {
         const dir = stack.pop();
         let entries;
@@ -47,12 +64,35 @@ function walkSkillFiles(root) {
         }
         for (const entry of entries) {
             const full = path.join(dir, entry.name);
-            if (entry.isDirectory()) {
+            let isDir = entry.isDirectory();
+            let isFile = entry.isFile();
+            if (entry.isSymbolicLink()) {
+                // Resolve the link target to decide whether to descend / collect it.
+                try {
+                    const st = statSync(full);
+                    isDir = st.isDirectory();
+                    isFile = st.isFile();
+                }
+                catch {
+                    continue;
+                }
+            }
+            if (isDir) {
                 if (entry.name === "node_modules" || entry.name === ".git")
                     continue;
+                let real;
+                try {
+                    real = realpathSync(full);
+                }
+                catch {
+                    continue;
+                }
+                if (seen.has(real))
+                    continue;
+                seen.add(real);
                 stack.push(full);
             }
-            else if (entry.isFile() && entry.name === "SKILL.md") {
+            else if (isFile && entry.name === "SKILL.md") {
                 out.push(full);
             }
         }
@@ -62,6 +102,7 @@ function walkSkillFiles(root) {
 function sampleSiblingFiles(dir, limit = 10) {
     const out = [];
     const stack = [dir];
+    const seen = new Set();
     while (stack.length && out.length < limit) {
         const cur = stack.pop();
         let entries;
@@ -75,12 +116,34 @@ function sampleSiblingFiles(dir, limit = 10) {
             if (out.length >= limit)
                 break;
             const full = path.join(cur, entry.name);
-            if (entry.isDirectory()) {
+            let isDir = entry.isDirectory();
+            let isFile = entry.isFile();
+            if (entry.isSymbolicLink()) {
+                try {
+                    const st = statSync(full);
+                    isDir = st.isDirectory();
+                    isFile = st.isFile();
+                }
+                catch {
+                    continue;
+                }
+            }
+            if (isDir) {
                 if (entry.name === "node_modules" || entry.name === ".git")
                     continue;
+                let real;
+                try {
+                    real = realpathSync(full);
+                }
+                catch {
+                    continue;
+                }
+                if (seen.has(real))
+                    continue;
+                seen.add(real);
                 stack.push(full);
             }
-            else if (entry.isFile() && entry.name !== "SKILL.md") {
+            else if (isFile && entry.name !== "SKILL.md") {
                 out.push(full);
             }
         }
@@ -176,6 +239,8 @@ export function loadSkills(dirs) {
             if (described.length === 0)
                 return "No skills are currently available.";
             return [
+                SKILLS_PROMPT_PREAMBLE,
+                "",
                 "## Available Skills",
                 ...described.map((s) => `- **${s.name}**: ${s.description}`),
             ].join("\n");

package/dist/toolkit.d.ts

@@ -3,14 +3,24 @@
  * single uniform list, with provider adapters and a single execute() router.
  */
 import { type Tool, type ToolContext, type ToolResult, type McpStatus } from "./types.js";
+import { type BuiltinsConfig } from "./builtin.js";
+import { type Agent } from "./a2a.js";
+import { type A2AConfig, type OnTask, type ServeHandle } from "./serve.js";
+import type { Client } from "./client.js";
 export interface ToolkitOptions {
     mcpConfig?: string | object;
     skillsDir?: string | string[];
     extraTools?: Tool[];
+    /** Built-in tools (§4A). On by default. false | { disabled:true } | { enabled:false } ⇒ off. */
+    builtins?: BuiltinsConfig;
+    /** Remote A2A agents — each advertised skill becomes a tool (source:"a2a"). */
+    agents?: Agent[];
 }
 export declare class Toolkit {
     private readonly mcp;
     private readonly skill;
+    /** A2A profile read from a top-level `a2a` config block (serve() falls back to this). */
+    private readonly a2aConfig;
     private byName;
     private constructor();
     static create(opts: ToolkitOptions): Promise<Toolkit>;
@@ -18,6 +28,23 @@ export declare class Toolkit {
     get(name: string): Tool | undefined;
     /** Add a tool at runtime (native, http, or any custom Tool). First name wins. */
     register(...tools: Tool[]): this;
+    /**
+     * Fetch a remote A2A agent's card at runtime and register its skills as tools.
+     * Accepts an Agent descriptor or a bare card URL. First-name-wins dedupe.
+     */
+    addAgent(agentOrCardUrl: Agent | string, opts?: Omit<Agent, "card">): Promise<this>;
+    /**
+     * Serve this toolkit as an agent over HTTP. When the `a2a` profile is present
+     * (inline, or a top-level `a2a` config block the toolkit was built from), it
+     * mounts the A2A Agent Card (`/.well-known/agent-card.json`, built from skills)
+     * and a JSON-RPC endpoint (`SendMessage` + `GetTask`) fulfilled by `client.run`.
+     * When `a2a` is absent, no A2A routes are mounted. Returns a stoppable handle.
+     */
+    serve(addr: string, opts: {
+        client: Client;
+        a2a?: A2AConfig;
+        onTask?: OnTask;
+    }): Promise<ServeHandle>;
     execute(name: string, args: Record<string, unknown>, ctx?: ToolContext): Promise<ToolResult>;
     /** Markdown skill catalog for the system prompt. */
     skillsPrompt(): string;

package/dist/toolkit.js

@@ -1,14 +1,26 @@
 import { loadMcp } from "./mcp.js";
 import { loadSkills } from "./skill.js";
+import { selectBuiltins } from "./builtin.js";
+import { agentTools, parseAgentsConfig } from "./a2a.js";
+import { startA2AServer } from "./serve.js";
 import { toAnthropic, toGemini, toOpenAI } from "./adapters.js";
 export class Toolkit {
     mcp;
     skill;
+    a2aConfig;
     byName = new Map();
-    constructor(mcp, skill, extraTools) {
+    constructor(mcp, skill, builtins, agents, extraTools, 
+    /** A2A profile read from a top-level `a2a` config block (serve() falls back to this). */
+    a2aConfig) {
         this.mcp = mcp;
         this.skill = skill;
-        const all = [...(mcp?.tools ?? []), ...(skill ? [skill.tool] : []), ...extraTools];
+        this.a2aConfig = a2aConfig;
+        // Builtins are the lowest-precedence source: a host extraTools entry with
+        // the same name shadows a builtin (SPEC §4). Drop shadowed builtins up
+        // front, then apply the normal first-wins dedupe for MCP/skill/agents/extras.
+        const extraNames = new Set(extraTools.map((t) => t.name));
+        const activeBuiltins = builtins.filter((b) => !extraNames.has(b.name));
+        const all = [...(mcp?.tools ?? []), ...(skill ? [skill.tool] : []), ...activeBuiltins, ...agents, ...extraTools];
         for (const t of all) {
             if (this.byName.has(t.name)) {
                 console.warn(`[toolnexus] duplicate tool name "${t.name}" — keeping first`);
@@ -20,7 +32,35 @@ export class Toolkit {
     static async create(opts) {
         const mcp = opts.mcpConfig !== undefined ? await loadMcp(opts.mcpConfig) : undefined;
         const skill = opts.skillsDir !== undefined ? loadSkills(opts.skillsDir) : undefined;
-        return new Toolkit(mcp, skill, opts.extraTools ?? []);
+        // The toggle comes from the `builtins` option, or a top-level `builtins`
+        // key on a parsed config object — same precedence as MCP's isEnabled.
+        let builtinsCfg = opts.builtins;
+        if (builtinsCfg === undefined &&
+            opts.mcpConfig &&
+            typeof opts.mcpConfig === "object" &&
+            "builtins" in opts.mcpConfig) {
+            builtinsCfg = opts.mcpConfig.builtins;
+        }
+        const builtins = selectBuiltins(builtinsCfg);
+        // Remote A2A agents come from the `agents:[...]` option plus a top-level
+        // `agents` block on a parsed config object (mirrors mcpServers). Each is
+        // resolved to its skill tools; a failing agent never breaks the toolkit.
+        const agentDescriptors = [...(opts.agents ?? [])];
+        if (opts.mcpConfig && typeof opts.mcpConfig === "object" && "agents" in opts.mcpConfig) {
+            agentDescriptors.push(...parseAgentsConfig(opts.mcpConfig.agents));
+        }
+        const agentToolLists = await Promise.all(agentDescriptors.map((a) => agentTools(a).catch((e) => {
+            console.warn(`[toolnexus] A2A agent "${a.card}" failed: ${e instanceof Error ? e.message : String(e)}`);
+            return [];
+        })));
+        const agentToolsFlat = agentToolLists.flat();
+        // A2A inbound profile: a top-level `a2a` block on a parsed config object
+        // (mirrors builtins/agents). serve() prefers its inline `a2a` over this.
+        let a2aConfig;
+        if (opts.mcpConfig && typeof opts.mcpConfig === "object" && "a2a" in opts.mcpConfig) {
+            a2aConfig = opts.mcpConfig.a2a;
+        }
+        return new Toolkit(mcp, skill, builtins, agentToolsFlat, opts.extraTools ?? [], a2aConfig);
     }
     tools() {
         return [...this.byName.values()];
@@ -39,6 +79,33 @@ export class Toolkit {
         }
         return this;
     }
+    /**
+     * Fetch a remote A2A agent's card at runtime and register its skills as tools.
+     * Accepts an Agent descriptor or a bare card URL. First-name-wins dedupe.
+     */
+    async addAgent(agentOrCardUrl, opts) {
+        const ag = typeof agentOrCardUrl === "string" ? { card: agentOrCardUrl, ...opts } : agentOrCardUrl;
+        const tools = await agentTools(ag);
+        return this.register(...tools);
+    }
+    /**
+     * Serve this toolkit as an agent over HTTP. When the `a2a` profile is present
+     * (inline, or a top-level `a2a` config block the toolkit was built from), it
+     * mounts the A2A Agent Card (`/.well-known/agent-card.json`, built from skills)
+     * and a JSON-RPC endpoint (`SendMessage` + `GetTask`) fulfilled by `client.run`.
+     * When `a2a` is absent, no A2A routes are mounted. Returns a stoppable handle.
+     */
+    serve(addr, opts) {
+        const a2a = opts.a2a ?? this.a2aConfig;
+        const skills = this.skill ? Object.values(this.skill.skills) : [];
+        return startA2AServer({
+            addr,
+            a2a,
+            skills,
+            runTask: (text) => opts.client.run(text, { toolkit: this }),
+            onTask: opts.onTask,
+        });
+    }
     async execute(name, args, ctx) {
         const tool = this.byName.get(name);
         if (!tool) {

package/dist/types.d.ts

@@ -8,7 +8,7 @@ export type JSONSchema = {
     additionalProperties?: boolean;
     [k: string]: unknown;
 };
-export type ToolSource = "mcp" | "skill" | "native" | "http" | "custom";
+export type ToolSource = "mcp" | "skill" | "builtin" | "native" | "http" | "a2a" | "custom";
 export interface ToolResult {
     output: string;
     isError: boolean;