toolnexus 0.1.1 → 0.2.0

package/src/serve.ts

@@ -0,0 +1,324 @@
+/**
+ * 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"
+import type { SkillInfo } from "./skill.js"
+import type { RunResult } from "./client.js"
+import type { A2AArtifact, A2ATask, A2ATaskState, AgentCard } from "./a2a.js"
+
+// ---------------------------------------------------------------------------
+// TaskStore adapter — pluggable persistence for served Tasks.
+// ---------------------------------------------------------------------------
+
+/** 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 class InMemoryTaskStore implements TaskStore {
+  private readonly tasks = new Map<string, A2ATask>()
+  async get(id: string): Promise<A2ATask | undefined> {
+    return this.tasks.get(id)
+  }
+  async save(task: A2ATask): Promise<void> {
+    this.tasks.set(task.id, task)
+  }
+}
+
+/** File-backed store — one JSON file per Task id, under `dir`. */
+export class FileTaskStore implements TaskStore {
+  constructor(private readonly dir: string) {
+    fs.mkdirSync(dir, { recursive: true })
+  }
+  private file(id: string): string {
+    return path.join(this.dir, `${sanitize(id)}.json`)
+  }
+  async get(id: string): Promise<A2ATask | undefined> {
+    try {
+      return JSON.parse(fs.readFileSync(this.file(id), "utf8")) as A2ATask
+    } catch {
+      return undefined
+    }
+  }
+  async save(task: A2ATask): Promise<void> {
+    fs.writeFileSync(this.file(task.id), JSON.stringify(task))
+  }
+}
+
+/** Map a `store` selector to a concrete TaskStore. `"file:<dir>"` → FileTaskStore. */
+export function resolveStore(store?: TaskStore | "memory" | string): TaskStore {
+  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
+}
+
+// ---------------------------------------------------------------------------
+// A2A serve config + handle.
+// ---------------------------------------------------------------------------
+
+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>
+}
+
+// ---------------------------------------------------------------------------
+// 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: A2AConfig, skills: SkillInfo[], url: string): AgentCard {
+  const wanted = cfg.skills
+  const selected = wanted ? skills.filter((s) => wanted.includes(s.name)) : skills
+  const card: AgentCard = {
+    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"
+
+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
+}
+
+/** Extract the concatenated text of a JSON-RPC `SendMessage` message's parts. */
+function messageText(params: any): string {
+  const parts = params?.message?.parts
+  if (!Array.isArray(parts)) return ""
+  return parts
+    .filter((p: any) => p && p.kind === "text" && typeof p.text === "string")
+    .map((p: any) => p.text)
+    .join("")
+}
+
+function readBody(req: http.IncomingMessage): Promise<string> {
+  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: StartServerOptions): Promise<ServeHandle> {
+  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: unknown, payload: object) => {
+      res.writeHead(200, { "content-type": "application/json" })
+      res.end(JSON.stringify({ jsonrpc: "2.0", id: id ?? null, ...payload }))
+    }
+    const rpcOk = (id: unknown, result: unknown) => rpcRes(id, { result })
+    const rpcErr = (id: unknown, code: number, message: string) => 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: any
+        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: A2ATask = { 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<void>((resolve) => server.listen(Number(portStr), host, resolve))
+
+  return {
+    url: baseUrl(host, server),
+    stop() {
+      return new Promise<void>((resolve) => server.close(() => resolve()))
+    },
+    close() {
+      return new Promise<void>((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: string,
+  text: string,
+  store: TaskStore,
+  runTask: (text: string) => Promise<RunResult>,
+  onTask?: OnTask,
+): Promise<void> {
+  let task: A2ATask
+  let result: RunResult | undefined
+  let state: A2ATaskState
+  try {
+    await store.save({ id, status: { state: "working" } })
+    result = await runTask(text)
+    const artifact: A2AArtifact = {
+      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: string): [string, string] {
+  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: string, server: http.Server): string {
+  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/src/skill.ts

@@ -4,7 +4,7 @@
  * 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 type { Tool, ToolResult } from "./types.js"
@@ -15,6 +15,14 @@ Use this tool to inject the skill's instructions and resources into current conv
 
 The 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 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."
+
 export interface SkillInfo {
   name: string
   description?: string
@@ -46,6 +54,9 @@ function parseFrontmatter(text: string): { data: Record<string, string>; content
 function walkSkillFiles(root: string): string[] {
   const out: string[] = []
   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<string>()
   while (stack.length) {
     const dir = stack.pop()!
     let entries
@@ -56,10 +67,30 @@ function walkSkillFiles(root: string): string[] {
     }
     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)
       }
     }
@@ -70,6 +101,7 @@ function walkSkillFiles(root: string): string[] {
 function sampleSiblingFiles(dir: string, limit = 10): string[] {
   const out: string[] = []
   const stack = [dir]
+  const seen = new Set<string>()
   while (stack.length && out.length < limit) {
     const cur = stack.pop()!
     let entries
@@ -81,10 +113,29 @@ function sampleSiblingFiles(dir: string, limit = 10): string[] {
     for (const entry of entries) {
       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)
       }
     }
@@ -187,6 +238,8 @@ export function loadSkills(dirs: string | string[]): SkillSource {
         .sort((a, b) => a.name.localeCompare(b.name))
       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/src/toolkit.ts

@@ -5,12 +5,20 @@
 import { type Tool, type ToolContext, type ToolResult, type McpStatus } from "./types.js"
 import { loadMcp, type McpSource } from "./mcp.js"
 import { loadSkills, type SkillSource } from "./skill.js"
+import { selectBuiltins, type BuiltinsConfig } from "./builtin.js"
+import { agentTools, parseAgentsConfig, type Agent } from "./a2a.js"
+import { startA2AServer, type A2AConfig, type OnTask, type ServeHandle } from "./serve.js"
 import { toAnthropic, toGemini, toOpenAI } from "./adapters.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 class Toolkit {
@@ -18,9 +26,18 @@ export class Toolkit {
   private constructor(
     private readonly mcp: McpSource | undefined,
     private readonly skill: SkillSource | undefined,
+    builtins: Tool[],
+    agents: Tool[],
     extraTools: Tool[],
+    /** A2A profile read from a top-level `a2a` config block (serve() falls back to this). */
+    private readonly a2aConfig: A2AConfig | undefined,
   ) {
-    const all = [...(mcp?.tools ?? []), ...(skill ? [skill.tool] : []), ...extraTools]
+    // 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`)
@@ -33,7 +50,44 @@ export class Toolkit {
   static async create(opts: ToolkitOptions): Promise<Toolkit> {
     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 as { builtins?: BuiltinsConfig }).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: Agent[] = [...(opts.agents ?? [])]
+    if (opts.mcpConfig && typeof opts.mcpConfig === "object" && "agents" in opts.mcpConfig) {
+      agentDescriptors.push(...parseAgentsConfig((opts.mcpConfig as { agents?: Parameters<typeof parseAgentsConfig>[0] }).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 [] as Tool[]
+        }),
+      ),
+    )
+    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: A2AConfig | undefined
+    if (opts.mcpConfig && typeof opts.mcpConfig === "object" && "a2a" in opts.mcpConfig) {
+      a2aConfig = (opts.mcpConfig as { a2a?: A2AConfig }).a2a
+    }
+
+    return new Toolkit(mcp, skill, builtins, agentToolsFlat, opts.extraTools ?? [], a2aConfig)
   }
 
   tools(): Tool[] {
@@ -56,6 +110,35 @@ 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: Agent | string, opts?: Omit<Agent, "card">): Promise<this> {
+    const ag: Agent = 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: string, opts: { client: Client; a2a?: A2AConfig; onTask?: OnTask }): Promise<ServeHandle> {
+    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: string, args: Record<string, unknown>, ctx?: ToolContext): Promise<ToolResult> {
     const tool = this.byName.get(name)
     if (!tool) {

package/src/types.ts

@@ -10,7 +10,7 @@ export type JSONSchema = {
   [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