toolnexus 0.7.0 → 0.9.0

package/src/mcp.ts

@@ -51,6 +51,10 @@ export interface LocalServer {
   enabled?: boolean
   disabled?: boolean
   timeout?: number
+  /** §2 Gap 7. Per-server tool allowlist keyed on ORIGINAL tool name; same semantics as the
+   * builtins/skills filter (nil/empty ⇒ all; ≥1 true ⇒ allowlist; only-false ⇒ drop-list; unknown
+   * ⇒ ignore+warn). Applied to the listed defs before sanitize/prefix. */
+  tools?: Record<string, boolean>
 }
 
 export interface RemoteServer {
@@ -60,6 +64,8 @@ export interface RemoteServer {
   enabled?: boolean
   disabled?: boolean
   timeout?: number
+  /** §2 Gap 7. Per-server tool allowlist (see LocalServer.tools). */
+  tools?: Record<string, boolean>
 }
 
 export type ServerConfig = LocalServer | RemoteServer
@@ -128,6 +134,40 @@ function joinTextContent(content: unknown): string {
     .join("\n")
 }
 
+/**
+ * §2 Gap 7. Apply a per-server tool allowlist to the listed defs. Same semantics as the builtins
+ * and skills filters: nil/empty ⇒ all; ≥1 true ⇒ allowlist (only true names); only-false ⇒ drop-list
+ * over all-on; unknown names ignored + warned once. Keyed on ORIGINAL tool name.
+ */
+function applyToolsFilter(server: string, defs: McpToolDef[], filter?: Record<string, boolean>): McpToolDef[] {
+  if (!filter) return defs
+  const keys = Object.keys(filter)
+  if (keys.length === 0) return defs
+  const hasTrue = keys.some((k) => filter[k] === true)
+  const present = new Set(defs.map((d) => d.name))
+  for (const k of keys) {
+    if (!present.has(k)) console.warn(`[toolnexus] server "${server}" tools filter name "${k}" matched no tool`)
+  }
+  return defs.filter((d) => (hasTrue ? filter[d.name] === true : filter[d.name] !== false))
+}
+
+/**
+ * §2 Gap 3. Race a promise against a per-server timeout and the caller's abort signal, so a hung
+ * connect/list is bounded (the SSE fallback included) and a parent cancellation aborts promptly.
+ */
+function raceTimeout<T>(p: Promise<T>, ms: number, signal?: AbortSignal): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = () => { cleanup(); reject((signal as any)?.reason ?? new Error("aborted")) }
+    const t = setTimeout(() => { cleanup(); reject(new Error("mcp connect/list timeout")) }, ms)
+    const cleanup = () => { clearTimeout(t); signal?.removeEventListener("abort", onAbort) }
+    if (signal) {
+      if (signal.aborted) return onAbort()
+      signal.addEventListener("abort", onAbort, { once: true })
+    }
+    p.then((v) => { cleanup(); resolve(v) }, (e) => { cleanup(); reject(e) })
+  })
+}
+
 async function paginateTools(client: Client, timeout: number): Promise<McpToolDef[]> {
   const result: McpToolDef[] = []
   const cursors = new Set<string>()
@@ -182,13 +222,59 @@ export interface McpSource {
   close(): Promise<void>
 }
 
-/** Connect to every enabled server, list + convert tools. Failures are isolated. */
-export async function loadMcp(input: string | object, opts?: { waitFor?: (request: Request) => Promise<Answer> }): Promise<McpSource> {
+/** Create a fresh (not-yet-connected) client, with the elicitation bridge attached if a waitFor
+ *  exists. Separated from connect so the caller ALWAYS holds a closeable reference — even if the
+ *  connect is later abandoned by a timeout/abort, `client.close()` still terminates any spawned
+ *  stdio child (no orphaned processes on cancellation). */
+function newMcpClient(waitFor?: (request: Request) => Promise<Answer>): Client {
+  const client = new Client({ name: "toolnexus", version: "0.1.0" }, { capabilities: waitFor ? { elicitation: {} } : {} })
+  if (waitFor) {
+    client.setRequestHandler(ElicitRequestSchema, async (request) =>
+      answerToElicitResult(await waitFor(elicitationToRequest(request.params))),
+    )
+  }
+  return client
+}
+
+/** Connect an existing client's transport (remote streamable-HTTP with SSE fallback, or local stdio). */
+async function connectTransport(client: Client, cfg: ServerConfig): Promise<void> {
+  if (isRemote(cfg)) {
+    const url = new URL(cfg.url)
+    const expanded = expandEnvHeaders(cfg.headers)
+    const requestInit = expanded ? { headers: expanded } : undefined
+    try {
+      await client.connect(new StreamableHTTPClientTransport(url, { requestInit }))
+    } catch {
+      await client.connect(new SSEClientTransport(url, { requestInit }))
+    }
+  } else {
+    const local = cfg as LocalServer
+    const [cmd, ...args] = local.command
+    await client.connect(
+      new StdioClientTransport({
+        command: cmd,
+        args,
+        cwd: local.cwd,
+        env: { ...(process.env as Record<string, string>), ...(local.environment ?? local.env ?? {}) },
+        stderr: "pipe",
+      }),
+    )
+  }
+}
+
+/** Connect to every enabled server, list + convert tools. Failures are isolated.
+ *  §2 Gap 3: an optional `signal` bounds each connect/list by the server timeout and aborts the
+ *  whole load promptly on parent cancellation. */
+export async function loadMcp(
+  input: string | object,
+  opts?: { waitFor?: (request: Request) => Promise<Answer>; signal?: AbortSignal },
+): Promise<McpSource> {
   const config = parseMcpConfig(input)
   const tools: Tool[] = []
   const status: Record<string, McpStatus> = {}
   const clients: Client[] = []
   const waitFor = opts?.waitFor
+  const signal = opts?.signal
 
   await Promise.all(
     Object.entries(config).map(async ([name, cfg]) => {
@@ -197,45 +283,22 @@ export async function loadMcp(input: string | object, opts?: { waitFor?: (reques
         return
       }
       const timeout = cfg.timeout ?? DEFAULT_TIMEOUT
-      // Advertise elicitation + register the bridge ONLY when a waitFor exists to satisfy it —
-      // a waitFor-less host degrades cleanly (the server won't elicit). (§10 elicitation bridge)
-      const client = new Client({ name: "toolnexus", version: "0.1.0" }, { capabilities: waitFor ? { elicitation: {} } : {} })
-      if (waitFor) {
-        client.setRequestHandler(ElicitRequestSchema, async (request) =>
-          answerToElicitResult(await waitFor(elicitationToRequest(request.params))),
-        )
-      }
+      // Create the client up front so a timed-out/aborted connect still has a closeable handle
+      // (its stdio child is killed by close() — never orphaned).
+      const client = newMcpClient(waitFor)
       try {
-        if (isRemote(cfg)) {
-          const url = new URL(cfg.url)
-          const expanded = expandEnvHeaders(cfg.headers)
-          const requestInit = expanded ? { headers: expanded } : undefined
-          try {
-            await client.connect(new StreamableHTTPClientTransport(url, { requestInit }))
-          } catch {
-            await client.connect(new SSEClientTransport(url, { requestInit }))
-          }
-        } else {
-          const local = cfg as LocalServer
-          const [cmd, ...args] = local.command
-          await client.connect(
-            new StdioClientTransport({
-              command: cmd,
-              args,
-              cwd: local.cwd,
-              env: { ...(process.env as Record<string, string>), ...(local.environment ?? local.env ?? {}) },
-              stderr: "pipe",
-            }),
-          )
-        }
-        const defs = await paginateTools(client, timeout)
-        for (const def of defs) tools.push(convertTool(name, def, client, timeout))
+        await raceTimeout(connectTransport(client, cfg), timeout, signal)
+        const defs = await raceTimeout(paginateTools(client, timeout), timeout, signal)
+        const kept = applyToolsFilter(name, defs, (cfg as { tools?: Record<string, boolean> }).tools)
+        for (const def of kept) tools.push(convertTool(name, def, client, timeout))
         clients.push(client)
         status[name] = "connected"
       } catch (e) {
         status[name] = "failed"
         await client.close().catch(() => {})
-        // one bad server never breaks the toolkit
+        // Parent cancellation/deadline aborts the whole load (§2 Gap 3, A1); a per-server timeout
+        // within budget isolates just this server.
+        if (signal?.aborted) throw e
         console.warn(`[toolnexus] MCP server "${name}" failed: ${e instanceof Error ? e.message : String(e)}`)
       }
     }),
@@ -249,3 +312,62 @@ export async function loadMcp(input: string | object, opts?: { waitFor?: (reques
     },
   }
 }
+
+/** §2 Gap 6. One listed tool definition (original, unprefixed name). */
+export interface ToolInfo {
+  name: string
+  description: string
+  inputSchema: JSONSchema
+}
+
+/** §2 Gap 6. Result of a list-only pass over an MCP config. */
+export interface McpInventory {
+  /** server → its full listed tool defs, UNFILTERED by ServerConfig.tools (authors the allowlist). */
+  tools: Record<string, ToolInfo[]>
+  status: Record<string, McpStatus>
+}
+
+/**
+ * §2 Gap 6. Connect to every enabled server, list tool definitions, and DISCONNECT before
+ * returning — no toolkit, no execute wiring, nothing left running. Failure isolation as in loadMcp.
+ */
+export async function listMcpTools(input: string | object, opts?: { signal?: AbortSignal }): Promise<McpInventory> {
+  const config = parseMcpConfig(input)
+  const toolsByServer: Record<string, ToolInfo[]> = {}
+  const status: Record<string, McpStatus> = {}
+  const signal = opts?.signal
+
+  await Promise.all(
+    Object.entries(config).map(async ([name, cfg]) => {
+      if (!isEnabled(cfg)) {
+        status[name] = "disabled"
+        return
+      }
+      const timeout = cfg.timeout ?? DEFAULT_TIMEOUT
+      // Client created up front so an aborted/timed-out connect is still closed (no orphaned child).
+      const client = newMcpClient()
+      try {
+        await raceTimeout(connectTransport(client, cfg), timeout, signal)
+        const defs = await raceTimeout(paginateTools(client, timeout), timeout, signal)
+        toolsByServer[name] = defs.map((d) => ({
+          name: d.name,
+          description: d.description ?? "",
+          inputSchema: {
+            ...(d.inputSchema as object),
+            type: "object",
+            properties: (d.inputSchema?.properties ?? {}) as Record<string, unknown>,
+          } as JSONSchema,
+        }))
+        status[name] = "connected"
+      } catch (e) {
+        status[name] = "failed"
+        if (signal?.aborted) { await client.close().catch(() => {}); throw e }
+        console.warn(`[toolnexus] MCP server "${name}" failed: ${e instanceof Error ? e.message : String(e)}`)
+      } finally {
+        await client.close().catch(() => {})
+      }
+    }),
+  )
+
+  return { tools: toolsByServer, status }
+}

package/src/serve.ts

@@ -62,7 +62,13 @@ export class FileTaskStore implements TaskStore {
     }
   }
   async save(task: A2ATask): Promise<void> {
-    fs.writeFileSync(this.file(task.id), JSON.stringify(task))
+    // Atomic write: a concurrent get() must never read a half-written file (that
+    // would surface as a spurious "Task not found" mid-poll). Write a temp file in
+    // the same dir, then rename over the target.
+    const target = this.file(task.id)
+    const tmp = `${target}.tmp`
+    fs.writeFileSync(tmp, JSON.stringify(task))
+    fs.renameSync(tmp, target)
   }
 }
 

package/src/skill.ts

@@ -3,6 +3,11 @@
  * discover **\/SKILL.md, parse frontmatter, and expose ONE `skill` tool that
  * loads a skill's instructions + sampled resources on demand (progressive
  * disclosure).
+ *
+ * Beyond on-disk discovery the source also accepts skills supplied as data
+ * (`SkillDef`) — SPEC.md §3. Directory-sourced skills keep the exact `file://`
+ * base + on-disk sibling sampling (byte-identical); data-sourced skills use a
+ * logical `skill://name/` base + a supplied resource list and never touch disk.
  */
 import { readFileSync, readdirSync, realpathSync, statSync } from "node:fs"
 import path from "node:path"
@@ -27,24 +32,72 @@ export const SKILLS_PROMPT_PREAMBLE =
 export interface SkillInfo {
   name: string
   description?: string
-  location: string // absolute path to SKILL.md
+  location: string // absolute path to SKILL.md (fs) or logical base (data)
   content: string // body after frontmatter
+  /** Internal origin discriminator; "fs" ⇒ on-disk (default), "logical" ⇒ data. */
+  origin?: "fs" | "logical"
+  /** Logical resource list (data-sourced skills only). */
+  resources?: string[]
+  /** Logical base, e.g. skill://name/ (data-sourced skills only). */
+  base?: string
+}
+
+/** A skill supplied directly as data, bypassing the filesystem (SPEC.md §3, S1). */
+export interface SkillDef {
+  name: string
+  description?: string
+  content: string
+  /** Optional logical resource names surfaced in the invoke-time <skill_files> block. */
+  resources?: string[]
+  /** Optional logical base; defaults to `skill://<name>/`. */
+  base?: string
+}
+
+/** Why a candidate SKILL.md did not become a skill (SPEC.md §3, S3). */
+export type SkillSkipReason = "missing-name" | "malformed-frontmatter" | "duplicate-name" | "unreadable"
+
+export interface SkillSkip {
+  location: string
+  reason: SkillSkipReason
+}
+
+/** Result of a list-only validate pass (SPEC.md §3, S3). */
+export interface SkillInventory {
+  skills: SkillInfo[]
+  skipped: SkillSkip[]
+}
+
+/** Options for loadSkills / listSkills (SPEC.md §3, S1/S2/S5). */
+export interface LoadSkillsOptions {
+  dirs?: string | string[]
+  skills?: SkillDef[]
+  /** Per-agent allowlist keyed on skill name; same semantics as the MCP tools filter. */
+  filter?: Record<string, boolean>
+  /** Sibling-file sample cap: 0 ⇒ default 10, n>0 ⇒ cap, -1 ⇒ omit <skill_files>. */
+  sampleLimit?: number
 }
 
 /**
  * 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.
+ *
+ * `malformed` is true only when fences are present but the YAML fails to parse —
+ * distinguishing a malformed header from a body with no frontmatter, so the
+ * inventory (S3) can report the right skip reason. loadSkills' behavior is
+ * unchanged: a malformed header yields no name and the skill is skipped.
  */
-function parseFrontmatter(text: string): { data: Record<string, string>; content: string } {
+function parseFrontmatter(text: string): { data: Record<string, string>; content: string; malformed: boolean } {
   const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(text)
-  if (!match) return { data: {}, content: text }
+  if (!match) return { data: {}, content: text, malformed: false }
   const data: Record<string, string> = {}
   let parsed: unknown
+  let malformed = false
   try {
     parsed = parseYaml(match[1])
   } catch {
     parsed = null
+    malformed = true
   }
   if (parsed && typeof parsed === "object") {
     for (const [key, value] of Object.entries(parsed as Record<string, unknown>)) {
@@ -55,7 +108,7 @@ function parseFrontmatter(text: string): { data: Record<string, string>; content
       }
     }
   }
-  return { data, content: match[2] }
+  return { data, content: match[2], malformed }
 }
 
 function walkSkillFiles(root: string): string[] {
@@ -150,50 +203,145 @@ function sampleSiblingFiles(dir: string, limit = 10): string[] {
   return out
 }
 
-export interface SkillSource {
-  skills: Record<string, SkillInfo>
-  tool: Tool
-  /** Markdown catalog for the system prompt (mirrors opencode Skill.fmt). */
-  prompt(): string
+/** One raw candidate before cross-source dedupe: a parsed skill OR a typed skip. */
+interface RawCandidate {
+  info?: SkillInfo
+  skip?: SkillSkip
 }
 
-/** Discover skills under one or more roots and build the `skill` loader tool. */
-export function loadSkills(dirs: string | string[]): SkillSource {
-  const roots = Array.isArray(dirs) ? dirs : [dirs]
-  const skills: Record<string, SkillInfo> = {}
-
-  for (const root of roots) {
-    let isDir = false
+/** Discover candidates under one on-disk root (order = discovery order). */
+function candidatesFromDir(root: string): RawCandidate[] {
+  const out: RawCandidate[] = []
+  let isDir = false
+  try {
+    isDir = statSync(root).isDirectory()
+  } catch {
+    isDir = false
+  }
+  if (!isDir) {
+    console.warn(`[toolnexus] skills dir not found: ${root}`)
+    return out
+  }
+  for (const file of walkSkillFiles(root)) {
+    let text: string
     try {
-      isDir = statSync(root).isDirectory()
+      text = readFileSync(file, "utf8")
     } catch {
-      isDir = false
+      out.push({ skip: { location: file, reason: "unreadable" } })
+      continue
     }
-    if (!isDir) {
-      console.warn(`[toolnexus] skills dir not found: ${root}`)
+    const { data, content, malformed } = parseFrontmatter(text)
+    if (malformed) {
+      out.push({ skip: { location: file, reason: "malformed-frontmatter" } })
       continue
     }
-    for (const file of walkSkillFiles(root)) {
-      let text: string
-      try {
-        text = readFileSync(file, "utf8")
-      } catch {
-        continue
-      }
-      const { data, content } = parseFrontmatter(text)
-      if (!data.name) continue
-      if (skills[data.name]) {
-        console.warn(`[toolnexus] duplicate skill name "${data.name}" (${file}) — keeping first`)
-        continue
-      }
-      skills[data.name] = {
-        name: data.name,
-        description: data.description,
-        location: file,
-        content,
-      }
+    if (!data.name) {
+      out.push({ skip: { location: file, reason: "missing-name" } })
+      continue
     }
+    out.push({ info: { name: data.name, description: data.description, location: file, content, origin: "fs" } })
   }
+  return out
+}
+
+/** Turn data-supplied skill defs into candidates (logical origin). */
+function candidatesFromDefs(defs: SkillDef[]): RawCandidate[] {
+  return defs.map((d): RawCandidate => {
+    if (!d.name) return { skip: { location: d.base ?? "skill://", reason: "missing-name" } }
+    const base = d.base && d.base.length > 0 ? d.base : `skill://${d.name}/`
+    return {
+      info: {
+        name: d.name,
+        description: d.description,
+        location: base,
+        content: d.content ?? "",
+        origin: "logical",
+        resources: d.resources ?? [],
+        base,
+      },
+    }
+  })
+}
+
+/** Collect ordered candidates from dirs then data defs. */
+function collectCandidates(opts: LoadSkillsOptions): RawCandidate[] {
+  const roots = opts.dirs === undefined ? [] : Array.isArray(opts.dirs) ? opts.dirs : [opts.dirs]
+  const cands: RawCandidate[] = []
+  for (const root of roots) cands.push(...candidatesFromDir(root))
+  if (opts.skills) cands.push(...candidatesFromDefs(opts.skills))
+  return cands
+}
+
+/** Dedupe candidates by name (first-wins); later duplicates become skips. */
+function mergeCandidates(cands: RawCandidate[]): { skills: Record<string, SkillInfo>; skipped: SkillSkip[] } {
+  const skills: Record<string, SkillInfo> = {}
+  const skipped: SkillSkip[] = []
+  for (const c of cands) {
+    if (c.skip) {
+      skipped.push(c.skip)
+      continue
+    }
+    const info = c.info!
+    if (skills[info.name]) {
+      console.warn(`[toolnexus] duplicate skill name "${info.name}" (${info.location}) — keeping first`)
+      skipped.push({ location: info.location, reason: "duplicate-name" })
+      continue
+    }
+    skills[info.name] = info
+  }
+  return { skills, skipped }
+}
+
+/**
+ * Apply the per-agent skill allowlist (S2), semantics identical to the MCP
+ * per-server tools filter and builtins: nil/empty ⇒ all; ≥1 true ⇒ allowlist
+ * (only true-mapped names); only-false ⇒ drop-list over all-on; unknown names
+ * are ignored and warned once.
+ */
+function applySkillsFilter(
+  skills: Record<string, SkillInfo>,
+  filter: Record<string, boolean> | undefined,
+): Record<string, SkillInfo> {
+  if (!filter) return skills
+  const keys = Object.keys(filter)
+  if (keys.length === 0) return skills
+  const hasTrue = keys.some((k) => filter[k] === true)
+  for (const k of keys) {
+    if (!(k in skills)) console.warn(`[toolnexus] skill filter name "${k}" matched no skill`)
+  }
+  const out: Record<string, SkillInfo> = {}
+  for (const [name, info] of Object.entries(skills)) {
+    if (hasTrue ? filter[name] === true : filter[name] !== false) out[name] = info
+  }
+  return out
+}
+
+export interface SkillSource {
+  skills: Record<string, SkillInfo>
+  tool: Tool
+  /** Markdown catalog for the system prompt (mirrors opencode Skill.fmt). */
+  prompt(): string
+}
+
+/**
+ * Discover + validate skills from the same sources loadSkills accepts, returning
+ * parsed skills plus typed skip reasons — no toolkit wired (SPEC.md §3, S3). The
+ * inventory is UNFILTERED (it exists to author/validate the allowlist).
+ */
+export function listSkills(input: string | string[] | LoadSkillsOptions): SkillInventory {
+  const opts: LoadSkillsOptions =
+    typeof input === "string" || Array.isArray(input) ? { dirs: input } : input
+  const merged = mergeCandidates(collectCandidates(opts))
+  return { skills: Object.values(merged.skills), skipped: merged.skipped }
+}
+
+/** Discover skills (dirs and/or data) and build the `skill` loader tool. */
+export function loadSkills(input: string | string[] | LoadSkillsOptions): SkillSource {
+  const opts: LoadSkillsOptions =
+    typeof input === "string" || Array.isArray(input) ? { dirs: input } : input
+  const sampleLimit = opts.sampleLimit ?? 0
+  const merged = mergeCandidates(collectCandidates(opts))
+  const skills = applySkillsFilter(merged.skills, opts.filter)
 
   const tool: Tool = {
     name: "skill",
@@ -214,10 +362,28 @@ export function loadSkills(dirs: string | string[]): SkillSource {
           isError: true,
         }
       }
-      const dir = path.dirname(info.location)
-      const base = pathToFileURL(dir).href
-      const files = sampleSiblingFiles(dir)
-      const output = [
+      // effLimit: 0 ⇒ default 10 (byte-identical to today), n>0 ⇒ cap, -1 ⇒ omit.
+      const effLimit = sampleLimit === 0 ? 10 : sampleLimit
+      let base: string
+      let files: string[]
+      let metaDir: string
+      // Emit the <skill_files> block: always for fs skills (byte-identical, even
+      // when empty), only when a data skill actually carries resources (an
+      // instruction-only data skill omits it). Never when sampling is disabled.
+      let emitFiles = effLimit !== -1
+      if (info.origin === "logical") {
+        base = info.base ?? `skill://${info.name}/`
+        const res = info.resources ?? []
+        if (res.length === 0) emitFiles = false
+        files = effLimit > 0 ? res.slice(0, effLimit) : res
+        metaDir = base
+      } else {
+        const dir = path.dirname(info.location)
+        base = pathToFileURL(dir).href
+        files = effLimit === -1 ? [] : sampleSiblingFiles(dir, effLimit)
+        metaDir = dir
+      }
+      const lines = [
         `<skill_content name="${info.name}">`,
         `# Skill: ${info.name}`,
         "",
@@ -225,14 +391,18 @@ export function loadSkills(dirs: string | string[]): SkillSource {
         "",
         `Base directory for this skill: ${base}`,
         "Relative paths in this skill (e.g., scripts/, reference/) are relative to this base directory.",
-        "Note: file list is sampled.",
-        "",
-        "<skill_files>",
-        files.map((f) => `<file>${f}</file>`).join("\n"),
-        "</skill_files>",
-        "</skill_content>",
-      ].join("\n")
-      return { output, isError: false, metadata: { name: info.name, dir } }
+      ]
+      if (emitFiles) {
+        lines.push(
+          "Note: file list is sampled.",
+          "",
+          "<skill_files>",
+          files.map((f) => `<file>${f}</file>`).join("\n"),
+          "</skill_files>",
+        )
+      }
+      lines.push("</skill_content>")
+      return { output: lines.join("\n"), isError: false, metadata: { name: info.name, dir: metaDir } }
     },
   }
 

package/src/toolkit.ts

@@ -4,7 +4,7 @@
  */
 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 { loadSkills, type SkillDef, 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"
@@ -15,6 +15,14 @@ import type { Client } from "./client.js"
 export interface ToolkitOptions {
   mcpConfig?: string | object
   skillsDir?: string | string[]
+  /** Skills supplied as data, bypassing the filesystem (§3, S1). */
+  skills?: SkillDef[]
+  /** Lazy provider of data-supplied skills, resolved once at toolkit build (§3, S1). */
+  skillProvider?: () => SkillDef[] | Promise<SkillDef[]>
+  /** Per-agent skill allowlist keyed on name; same semantics as the MCP tools filter (§3, S2). */
+  skillsFilter?: Record<string, boolean>
+  /** Sibling-file sample cap: 0 ⇒ default 10, n>0 ⇒ cap, -1 ⇒ omit <skill_files> (§3, S5). */
+  skillSampleLimit?: number
   extraTools?: Tool[]
   /** Built-in tools (§4A). On by default. false | { disabled:true } | { enabled:false } ⇒ off. */
   builtins?: BuiltinsConfig
@@ -27,6 +35,9 @@ export interface ToolkitOptions {
    * elicitation is not advertised.
    */
   waitFor?: (request: import("./types.js").Request) => Promise<import("./types.js").Answer>
+  /** §2 Gap 3. Bounds the MCP load: each connect/list is capped by the server timeout and the
+   * whole load aborts promptly if this signal fires. Omit ⇒ unbounded as before. */
+  signal?: AbortSignal
 }
 
 export class Toolkit {
@@ -58,8 +69,29 @@ export class Toolkit {
   }
 
   static async create(opts: ToolkitOptions): Promise<Toolkit> {
-    const mcp = opts.mcpConfig !== undefined ? await loadMcp(opts.mcpConfig, { waitFor: opts.waitFor }) : undefined
-    const skill = opts.skillsDir !== undefined ? loadSkills(opts.skillsDir) : undefined
+    const mcp = opts.mcpConfig !== undefined ? await loadMcp(opts.mcpConfig, { waitFor: opts.waitFor, signal: opts.signal }) : undefined
+    // Skills come from directories, in-memory data, and/or a lazy provider (§3,
+    // S1). The provider is resolved here (create() is async) and merged with the
+    // data list; a provider failure is isolated so other sources still load.
+    let skill: SkillSource | undefined
+    if (opts.skillsDir !== undefined || opts.skills !== undefined || opts.skillProvider !== undefined) {
+      let providerDefs: SkillDef[] = []
+      if (opts.skillProvider) {
+        try {
+          providerDefs = await opts.skillProvider()
+        } catch (e) {
+          console.warn(`[toolnexus] skill provider failed: ${e instanceof Error ? e.message : String(e)}`)
+          providerDefs = []
+        }
+      }
+      const dataDefs = [...(opts.skills ?? []), ...providerDefs]
+      skill = loadSkills({
+        dirs: opts.skillsDir,
+        skills: dataDefs.length > 0 ? dataDefs : undefined,
+        filter: opts.skillsFilter,
+        sampleLimit: opts.skillSampleLimit,
+      })
+    }
     // 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