toolnexus 0.6.0 → 0.8.0

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,11 +15,26 @@ 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
   /** Remote A2A agents — each advertised skill becomes a tool (source:"a2a"). */
   agents?: Agent[]
+  /**
+   * Host resolver for out-of-band input (§10). When set, connected MCP servers may elicit input
+   * from the human mid-`tools/call` and it is bridged onto this `waitFor` (form→kind:"input",
+   * URL→kind:"authorization"). Typically the same function passed to the client. Omit ⇒ MCP
+   * elicitation is not advertised.
+   */
+  waitFor?: (request: import("./types.js").Request) => Promise<import("./types.js").Answer>
 }
 
 export class Toolkit {
@@ -51,8 +66,29 @@ 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
+    const mcp = opts.mcpConfig !== undefined ? await loadMcp(opts.mcpConfig, { waitFor: opts.waitFor }) : 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

package/src/types.ts

@@ -43,6 +43,12 @@ export interface Answer {
   id: string
   ok: boolean
   data?: Record<string, unknown>
+  /**
+   * When `ok` is false, why (advisory — the loop rule branches only on `ok`). Distinguishes an
+   * explicit refusal from a dismissal/timeout; the MCP elicitation bridge maps `declined`→`decline`
+   * and everything else→`cancel`. (R1)
+   */
+  reason?: "declined" | "cancelled" | "expired"
 }
 
 let _pendingSeq = 0