toolnexus 0.21.0 → 0.23.0

package/src/index.ts

@@ -14,6 +14,7 @@ export * from "./adapters.js"
 export * from "./translate.js"
 export * from "./toolkit.js"
 export * from "./client.js"
+export * from "./store.js"
 export * from "./classifier.js"
 export * as agents from "./agents/index.js"
 // Simple judgments (§8B, add-judge-adapters). `judge.noul/choice/score` are the NAMED builders
@@ -42,3 +43,7 @@ export {
   type GateOutcome,
   type Policy,
 } from "./judge.js"
+export * from "./promptcache.js"
+export * from "./tooltiers.js"
+export * from "./models.js"
+export * from "./builtin_extras.js"

package/src/mcp.ts

@@ -10,7 +10,7 @@ import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js"
 import type { Tool as McpToolDef, ElicitRequest, ElicitResult } from "@modelcontextprotocol/sdk/types.js"
 import { ElicitRequestSchema } from "@modelcontextprotocol/sdk/types.js"
-import { type JSONSchema, type Tool, type ToolContext, type ToolResult, type McpStatus, type Request, type Answer, sanitize } from "./types.js"
+import { type JSONSchema, type Tool, type ToolContext, type ToolHints, type ToolResult, type McpStatus, type Request, type Answer, sanitize } from "./types.js"
 import { type ContentPart, summarizePart } from "./content.js"
 
 // ---------------------------------------------------------------------------
@@ -88,12 +88,38 @@ function isEnabled(cfg: ServerConfig): boolean {
 export function parseMcpConfig(input: string | object): McpConfig {
   const raw: any = typeof input === "string" ? JSON.parse(readFileSync(input, "utf8")) : input
   const wrapped = raw.mcpServers ?? raw.servers ?? raw.mcp
-  if (wrapped !== undefined) return wrapped as McpConfig
+  if (wrapped !== undefined) return normalizeServers(wrapped)
   // Bare map of servers — but strip sibling top-level config keys (builtins/
   // agents/a2a/mcpServer) so they are not mistaken for MCP servers when no
   // wrapper key is present.
   const { builtins: _builtins, agents: _agents, a2a: _a2a, mcpServer: _mcpServer, ...servers } = raw
-  return servers as McpConfig
+  return normalizeServers(servers)
+}
+
+/**
+ * §2 `command` + `args`. A local server's `command` may be a non-empty string or a non-empty
+ * string array; an optional `args` string array is appended. The result is always the argv form
+ * (`command: string[]`, no `args`). Spawned with no shell. A remote server ignores `args`.
+ */
+function normalizeServers(servers: Record<string, any>): McpConfig {
+  const out: McpConfig = {}
+  for (const [name, cfg] of Object.entries(servers ?? {})) {
+    if (cfg === null || typeof cfg !== "object" || isRemote(cfg as ServerConfig)) {
+      out[name] = cfg
+      continue
+    }
+    const { args, command, ...rest } = cfg as any
+    const head: unknown[] | undefined =
+      typeof command === "string" ? [command] : Array.isArray(command) ? command : undefined
+    if (!head || head.length === 0 || head[0] === "" || head.some((c) => typeof c !== "string")) {
+      throw new Error(`mcp server "${name}": invalid command`)
+    }
+    if (args !== undefined && (!Array.isArray(args) || args.some((a: unknown) => typeof a !== "string"))) {
+      throw new Error(`mcp server "${name}": invalid args`)
+    }
+    out[name] = { ...rest, command: [...(head as string[]), ...((args as string[] | undefined) ?? [])] }
+  }
+  return out
 }
 
 /**
@@ -240,12 +266,16 @@ function convertTool(server: string, def: McpToolDef, client: Client, timeout: n
     description: def.description ?? "",
     inputSchema,
     source: "mcp",
+    ...(mcpHints((def as any).annotations) ? { hints: mcpHints((def as any).annotations) } : {}),
     async execute(args: Record<string, unknown>, ctx?: ToolContext): Promise<ToolResult> {
       try {
         const result: any = await client.callTool(
           { name: def.name, arguments: args ?? {} },
           undefined,
-          { resetTimeoutOnProgress: true, signal: ctx?.signal, timeout: ctx?.timeout ?? timeout },
+          // The SDK only attaches `_meta.progressToken` when `onprogress` is supplied; without it
+          // `resetTimeoutOnProgress` never fires (add-mcp-progress-timeout). Notifications for a
+          // token that matches no in-flight request are dropped by the SDK, so they never reset.
+          { onprogress: () => {}, resetTimeoutOnProgress: true, signal: ctx?.signal, timeout: ctx?.timeout ?? timeout },
         )
         // Parts are collected BEFORE any branch returns: the isError and structuredContent
         // short-circuits both read `content[]` on the way past, so neither reintroduces the
@@ -271,6 +301,129 @@ export interface McpSource {
   tools: Tool[]
   status: Record<string, McpStatus>
   close(): Promise<void>
+  /**
+   * `list_mcp_resources` and `read_mcp_resource` bound to this source's connected servers
+   * (SPEC §4C). Both read-only. Opt-in: register them on a toolkit. They stop working once the
+   * source is closed.
+   */
+  resourceTools(): Tool[]
+}
+
+/** One server's outcome, reported by `loadMcp`'s `onServer` the moment that server finishes. */
+export interface McpServerResult {
+  name: string
+  status: McpStatus
+  /** This server's converted tools (empty unless connected). Usable until the source closes. */
+  tools: Tool[]
+  /** Why the server failed (absent when connected or disabled). */
+  error?: Error
+}
+
+/**
+ * MCP tool annotations → ToolHints (SPEC §4C). No hint fields at all ⇒ undefined (unknown).
+ * Defaults follow the MCP spec: readOnlyHint false, destructiveHint and openWorldHint true.
+ */
+export function mcpHints(a: { readOnlyHint?: boolean; destructiveHint?: boolean; openWorldHint?: boolean } | undefined): ToolHints | undefined {
+  if (!a || (a.readOnlyHint === undefined && a.destructiveHint === undefined && a.openWorldHint === undefined)) return undefined
+  const h: ToolHints = { readOnly: a.readOnlyHint ?? false, destructive: a.destructiveHint ?? true, openWorld: a.openWorldHint ?? true }
+  if (h.readOnly) h.destructive = false
+  return h
+}
+
+interface ServerConn {
+  client: Client
+  timeout: number
+}
+
+function resourceTools(servers: Map<string, ServerConn>): Tool[] {
+  const ro: ToolHints = { readOnly: true, destructive: false, openWorld: false }
+  const names = () => [...servers.keys()].sort()
+  const conn = (server: string): ServerConn => {
+    const c = servers.get(server)
+    if (!c) throw new Error(`no connected MCP server "${server}" (connected: ${names().join(", ")})`)
+    return c
+  }
+  const list: Tool = {
+    name: "list_mcp_resources",
+    description: "List the resources MCP servers offer (uri, name, description, mimeType). Optionally for one server.",
+    inputSchema: {
+      type: "object",
+      properties: { server: { type: "string", description: "Only this server (default: all)" } },
+      additionalProperties: false,
+    },
+    source: "mcp",
+    hints: ro,
+    async execute(args, ctx) {
+      let targets = names()
+      const s = typeof args?.server === "string" ? args.server : ""
+      if (s) {
+        try {
+          conn(s)
+        } catch (e) {
+          return { output: `list_mcp_resources: ${(e as Error).message}`, isError: true }
+        }
+        targets = [s]
+      }
+      const lines: string[] = []
+      const items: unknown[] = []
+      for (const name of targets) {
+        const c = conn(name)
+        try {
+          const res: any = await c.client.listResources({}, { timeout: c.timeout, signal: ctx?.signal })
+          for (const r of res.resources ?? []) {
+            let line = `${name} ${r.uri}`
+            if (r.name) line += ` — ${r.name}`
+            if (r.mimeType) line += ` (${r.mimeType})`
+            if (r.description) line += `: ${r.description}`
+            lines.push(line)
+            items.push({ server: name, uri: r.uri, name: r.name ?? "", mimeType: r.mimeType ?? "", description: r.description ?? "" })
+          }
+        } catch (e) {
+          lines.push(`${name}: error: ${e instanceof Error ? e.message : String(e)}`)
+        }
+      }
+      if (!lines.length) return { output: "No resources.", isError: false, metadata: { count: 0 } }
+      return { output: lines.join("\n"), isError: false, metadata: { count: items.length, resources: items } }
+    },
+  }
+  const read: Tool = {
+    name: "read_mcp_resource",
+    description: "Read one MCP resource by server and uri. Text comes back as text; binary content is described, not inlined.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        server: { type: "string", description: "The MCP server name" },
+        uri: { type: "string", description: "The resource uri" },
+      },
+      required: ["server", "uri"],
+      additionalProperties: false,
+    },
+    source: "mcp",
+    hints: ro,
+    async execute(args, ctx) {
+      const server = typeof args?.server === "string" ? args.server : ""
+      const uri = typeof args?.uri === "string" ? args.uri : ""
+      let c: ServerConn
+      try {
+        c = conn(server)
+      } catch (e) {
+        return { output: `read_mcp_resource: ${(e as Error).message}`, isError: true }
+      }
+      if (!uri) return { output: "read_mcp_resource: uri is required", isError: true }
+      try {
+        const res: any = await c.client.readResource({ uri }, { timeout: c.timeout, signal: ctx?.signal })
+        const parts: string[] = []
+        for (const rc of res.contents ?? []) {
+          if (typeof rc.text === "string") parts.push(rc.text)
+          else if (typeof rc.blob === "string") parts.push(`[binary ${rc.mimeType ?? ""}, ${rc.blob.length} base64 chars]`)
+        }
+        return { output: parts.join("\n"), isError: false, metadata: { server, uri } }
+      } catch (e) {
+        return { output: `read_mcp_resource: ${e instanceof Error ? e.message : String(e)}`, isError: true }
+      }
+    },
+  }
+  return [list, read]
 }
 
 /** Create a fresh (not-yet-connected) client, with the elicitation bridge attached if a waitFor
@@ -318,19 +471,44 @@ async function connectTransport(client: Client, cfg: ServerConfig): Promise<void
  *  whole load promptly on parent cancellation. */
 export async function loadMcp(
   input: string | object,
-  opts?: { waitFor?: (request: Request) => Promise<Answer>; signal?: AbortSignal },
+  opts?: {
+    waitFor?: (request: Request) => Promise<Answer>
+    signal?: AbortSignal
+    /**
+     * Called once per server the moment it is connected, failed or found disabled (SPEC §4C),
+     * so a host can register a fast server's tools while a slow one is still connecting.
+     * Calls are serialized (an async callback is awaited before the next one runs); the load
+     * still resolves only after every server and every callback has finished.
+     */
+    onServer?: (result: McpServerResult) => void | Promise<void>
+  },
 ): Promise<McpSource> {
   const config = parseMcpConfig(input)
   const tools: Tool[] = []
   const status: Record<string, McpStatus> = {}
   const clients: Client[] = []
+  const servers = new Map<string, ServerConn>()
   const waitFor = opts?.waitFor
   const signal = opts?.signal
+  const onServer = opts?.onServer
+  let reports: Promise<void> = Promise.resolve()
+  let reportError: unknown
+  const report = (r: McpServerResult) => {
+    if (!onServer) return
+    reports = reports.then(async () => {
+      try {
+        await onServer(r)
+      } catch (e) {
+        reportError ??= e
+      }
+    })
+  }
 
-  await Promise.all(
+  const loading = Promise.all(
     Object.entries(config).map(async ([name, cfg]) => {
       if (!isEnabled(cfg)) {
         status[name] = "disabled"
+        report({ name, status: "disabled", tools: [] })
         return
       }
       const timeout = cfg.timeout ?? DEFAULT_TIMEOUT
@@ -341,19 +519,37 @@ export async function loadMcp(
         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))
+        const converted = kept.map((def) => convertTool(name, def, client, timeout))
+        tools.push(...converted)
         clients.push(client)
+        servers.set(name, { client, timeout })
         status[name] = "connected"
+        report({ name, status: "connected", tools: converted })
       } catch (e) {
         status[name] = "failed"
         await client.close().catch(() => {})
         // 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
+        report({ name, status: "failed", tools: [], error: e instanceof Error ? e : new Error(String(e)) })
         console.warn(`[toolnexus] MCP server "${name}" failed: ${e instanceof Error ? e.message : String(e)}`)
       }
     }),
   )
+  try {
+    await loading
+  } catch (e) {
+    // Parent cancellation: close every client, including ones whose tools onServer handed out.
+    await reports
+    await Promise.all(clients.map((c) => c.close().catch(() => {})))
+    throw e
+  }
+
+  await reports
+  if (reportError) {
+    await Promise.all(clients.map((c) => c.close().catch(() => {})))
+    throw reportError
+  }
 
   return {
     tools,
@@ -361,6 +557,7 @@ export async function loadMcp(
     async close() {
       await Promise.all(clients.map((c) => c.close().catch(() => {})))
     },
+    resourceTools: () => resourceTools(servers),
   }
 }
 

package/src/models.ts

@@ -0,0 +1,56 @@
+/**
+ * listModels (SPEC §4C): the models a provider offers, for model switching. One GET per page,
+ * no retries. Same key rules as the client (apiKey, apiKeyEnv, or the host's own env var).
+ */
+import { resolveKey, type ClientOptions } from "./client.js"
+
+/** One model a provider lists. */
+export interface ModelInfo {
+  id: string
+  /** The provider's display name, when it gives one. */
+  name?: string
+  /** Context window in tokens when the provider reports it (OpenRouter does). */
+  contextLength?: number
+}
+
+async function getJson(f: typeof fetch, url: string, headers: Record<string, string>, signal?: AbortSignal): Promise<any> {
+  const res = await f(url, { method: "GET", headers, signal })
+  const text = await res.text()
+  if (!res.ok) throw new Error(`list models: HTTP ${res.status}: ${text.slice(0, 300)}`)
+  return JSON.parse(text)
+}
+
+/**
+ * List the models at `opts.baseUrl` in `opts.style`: openai `GET {base}/models`; anthropic
+ * `GET {base}/v1/models`, following `has_more`/`last_id`. Sorted by id.
+ */
+export async function listModels(
+  opts: Pick<ClientOptions, "baseUrl" | "style" | "apiKey" | "apiKeyEnv" | "headers" | "fetch">,
+  ctx?: { signal?: AbortSignal },
+): Promise<ModelInfo[]> {
+  const key = resolveKey(opts)
+  const f = opts.fetch ?? fetch
+  const base = opts.baseUrl.replace(/\/+$/, "")
+  const out: ModelInfo[] = []
+  if (opts.style === "anthropic") {
+    const endpoint = base.endsWith("/v1") ? `${base}/models` : `${base}/v1/models`
+    let after = ""
+    for (let page = 0; page < 100; page++) {
+      const url = `${endpoint}?limit=1000${after ? `&after_id=${encodeURIComponent(after)}` : ""}`
+      const body = await getJson(f, url, { "x-api-key": key, "anthropic-version": "2023-06-01", ...opts.headers }, ctx?.signal)
+      for (const m of body?.data ?? []) out.push({ id: m.id, ...(m.display_name ? { name: m.display_name } : {}) })
+      if (!body?.has_more || !body?.last_id) break
+      after = body.last_id
+    }
+  } else {
+    const body = await getJson(f, `${base}/models`, { Authorization: `Bearer ${key}`, ...opts.headers }, ctx?.signal)
+    for (const m of body?.data ?? []) {
+      out.push({
+        id: m.id,
+        ...(m.name ? { name: m.name } : {}),
+        ...(typeof m.context_length === "number" && m.context_length > 0 ? { contextLength: m.context_length } : {}),
+      })
+    }
+  }
+  return out.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+}

package/src/promptcache.ts

@@ -0,0 +1,63 @@
+/**
+ * Prompt caching (SPEC §8 "Prompt caching", change add-prompt-cache). The engine keeps the
+ * request prefix stable and marks it for the provider's cache.
+ */
+
+/** `ClientOptions.promptCache`. */
+export interface PromptCacheOptions {
+  /** Groups requests that share a prefix (one per session). Sent as openai `prompt_cache_key`.
+   * Ignored by anthropic, which caches by prefix. */
+  key?: string
+  /** Ask for the provider's longer cache lifetime where one exists (anthropic `ttl: "1h"`). */
+  longTTL?: boolean
+}
+
+function withCacheControl(v: unknown, mark: Record<string, unknown>): unknown {
+  if (!v || typeof v !== "object" || Array.isArray(v)) return v
+  return { ...(v as Record<string, unknown>), cache_control: mark }
+}
+
+/**
+ * Mark the cacheable prefix in an assembled body, in place. The transcript's own objects are
+ * never mutated: every touched entry is copied.
+ *  - anthropic: `cache_control` on the last tool, the system prompt (a string becomes one text
+ *    block) and the last content block of the latest message (3 of the 4 allowed breakpoints).
+ *  - openai: `prompt_cache_key = key` when set; the prefix is cached automatically.
+ *  - gemini: nothing yet (explicit cachedContent is deferred).
+ */
+export function applyPromptCache(body: Record<string, any>, style: string, o: PromptCacheOptions): void {
+  if (style === "anthropic") {
+    const mark: Record<string, unknown> = { type: "ephemeral" }
+    if (o.longTTL) mark.ttl = "1h"
+    if (Array.isArray(body.tools) && body.tools.length > 0) {
+      const out = [...body.tools]
+      out[out.length - 1] = withCacheControl(out[out.length - 1], mark)
+      body.tools = out
+    }
+    if (typeof body.system === "string") {
+      if (body.system !== "") body.system = [{ type: "text", text: body.system, cache_control: mark }]
+    } else if (Array.isArray(body.system) && body.system.length > 0) {
+      const out = [...body.system]
+      out[out.length - 1] = withCacheControl(out[out.length - 1], mark)
+      body.system = out
+    }
+    if (Array.isArray(body.messages) && body.messages.length > 0) {
+      const out = [...body.messages]
+      const last = out[out.length - 1]
+      if (last && typeof last === "object" && !Array.isArray(last)) {
+        const m: Record<string, unknown> = { ...last }
+        if (typeof m.content === "string") {
+          m.content = [{ type: "text", text: m.content, cache_control: mark }]
+        } else if (Array.isArray(m.content) && m.content.length > 0) {
+          const blocks = [...m.content]
+          blocks[blocks.length - 1] = withCacheControl(blocks[blocks.length - 1], mark)
+          m.content = blocks
+        }
+        out[out.length - 1] = m
+      }
+      body.messages = out
+    }
+  } else if (style === "openai") {
+    if (o.key) body.prompt_cache_key = o.key
+  }
+}

package/src/store.ts

@@ -0,0 +1,142 @@
+import { promises as fsp } from "node:fs"
+import path from "node:path"
+import { randomBytes } from "node:crypto"
+import { sortEntries, type ConversationEntry, type ConversationStore } from "./client.js"
+
+const ID_RE = /^[A-Za-z0-9._-]{1,128}$/
+const VERSION = 1
+
+function checkId(id: string): void {
+  if (typeof id !== "string" || !ID_RE.test(id) || id === "." || id === "..") {
+    throw new Error(`invalid conversation id: ${JSON.stringify(id)}`)
+  }
+}
+
+/**
+ * Durable {@link ConversationStore}: one file `<root>/<id>.json` per conversation holding
+ * `{"version":1,"messages":[...]}`. `save` writes a temp file (0600), fsyncs and renames it over
+ * the old one, so a reader sees the old or the new transcript, never a torn one (power-loss
+ * durability of the rename is best-effort). Same-id saves are serialized in-process; across
+ * processes the last rename wins.
+ */
+/**
+ * Durability mode (SPEC §8 "Durability mode"): `full` (default) flushes the file then fsyncs the
+ * directory best-effort; `fsync` flushes the file only; `none` skips every flush. Temp-then-rename
+ * holds in every mode. (On macOS Node's `fh.sync()` is libuv's fsync, which already issues
+ * `F_FULLFSYNC`; Node exposes no plainer flush, so `fsync` differs from `full` only by the dir fsync.)
+ */
+export type FileStoreSync = "full" | "fsync" | "none"
+
+export interface FileStoreOptions {
+  sync?: FileStoreSync
+}
+
+export class FileConversationStore implements ConversationStore {
+  readonly root: string
+  readonly sync: FileStoreSync
+  private readonly chains = new Map<string, Promise<void>>()
+
+  constructor(root: string, opts: FileStoreOptions = {}) {
+    if (typeof root !== "string" || root === "") throw new Error("FileConversationStore: root is required")
+    const mode = opts.sync ?? "full"
+    if (mode !== "full" && mode !== "fsync" && mode !== "none") {
+      throw new Error(`FileConversationStore: unknown sync mode ${JSON.stringify(opts.sync)}`)
+    }
+    this.root = root
+    this.sync = mode
+  }
+
+  private file(id: string): string {
+    return path.join(this.root, id + ".json")
+  }
+
+  async get(id: string): Promise<any[] | undefined> {
+    checkId(id)
+    let text: string
+    try {
+      text = await fsp.readFile(this.file(id), "utf8")
+    } catch (e: any) {
+      if (e?.code === "ENOENT") return undefined
+      throw e
+    }
+    let body: any
+    try {
+      body = JSON.parse(text)
+    } catch (e) {
+      throw new Error(`conversation "${id}": corrupt file: ${e instanceof Error ? e.message : String(e)}`)
+    }
+    if (body === null || typeof body !== "object" || body.version !== VERSION) {
+      throw new Error(`conversation "${id}": unsupported version ${JSON.stringify(body?.version)}`)
+    }
+    if (!Array.isArray(body.messages)) throw new Error(`conversation "${id}": corrupt file: messages is not an array`)
+    return body.messages
+  }
+
+  async save(id: string, messages: any[]): Promise<void> {
+    checkId(id)
+    const prev = this.chains.get(id) ?? Promise.resolve()
+    const next = prev.catch(() => {}).then(() => this.write(id, messages))
+    this.chains.set(id, next)
+    try {
+      await next
+    } finally {
+      if (this.chains.get(id) === next) this.chains.delete(id)
+    }
+  }
+
+  private async write(id: string, messages: any[]): Promise<void> {
+    await fsp.mkdir(this.root, { recursive: true, mode: 0o700 })
+    const tmp = path.join(this.root, `.${id}.${randomBytes(6).toString("hex")}.tmp`)
+    const data = JSON.stringify({ version: VERSION, messages })
+    let fh: Awaited<ReturnType<typeof fsp.open>> | undefined
+    try {
+      fh = await fsp.open(tmp, "w", 0o600)
+      await fh.writeFile(data, "utf8")
+      if (this.sync !== "none") await fh.sync()
+      await fh.close()
+      fh = undefined
+      await fsp.rename(tmp, this.file(id))
+    } catch (e) {
+      await fh?.close().catch(() => {})
+      await fsp.rm(tmp, { force: true }).catch(() => {})
+      throw e
+    }
+    // Best-effort parent-dir fsync so the rename itself survives power loss where supported.
+    if (this.sync !== "full") return
+    try {
+      const dir = await fsp.open(this.root, "r")
+      await dir.sync().catch(() => {})
+      await dir.close()
+    } catch {}
+  }
+
+  /** Every stored conversation, newest first (mtime; ties by id ascending). Bodies are not parsed. */
+  async list(): Promise<ConversationEntry[]> {
+    let names: string[]
+    try {
+      names = await fsp.readdir(this.root)
+    } catch (e: any) {
+      if (e?.code === "ENOENT") return []
+      throw e
+    }
+    const out: ConversationEntry[] = []
+    for (const name of names) {
+      if (!name.endsWith(".json")) continue
+      const id = name.slice(0, -5)
+      if (!ID_RE.test(id) || id === "." || id === "..") continue
+      try {
+        const st = await fsp.stat(path.join(this.root, name))
+        if (st.isFile()) out.push({ id, updatedAt: st.mtime })
+      } catch (e: any) {
+        if (e?.code !== "ENOENT") throw e
+      }
+    }
+    return sortEntries(out)
+  }
+
+  /** Remove a conversation; absent ids are not an error. */
+  async delete(id: string): Promise<void> {
+    checkId(id)
+    await fsp.rm(this.file(id), { force: true })
+  }
+}

package/src/toolkit.ts

@@ -79,7 +79,7 @@ export class Toolkit {
     }
   }
 
-  static async create(opts: ToolkitOptions): Promise<Toolkit> {
+  static async create(opts: ToolkitOptions = {}): Promise<Toolkit> {
     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
@@ -250,6 +250,6 @@ export class Toolkit {
   }
 }
 
-export function createToolkit(opts: ToolkitOptions): Promise<Toolkit> {
+export function createToolkit(opts: ToolkitOptions = {}): Promise<Toolkit> {
   return Toolkit.create(opts)
 }