toolnexus 0.27.0 → 0.28.0

package/src/index.ts

@@ -8,6 +8,7 @@ export * from "./native.js"
 export * from "./http.js"
 export * from "./a2a.js"
 export * from "./acp.js"
+export * from "./transcript_search.js"
 export * from "./serve.js"
 export * from "./mcpserve.js"
 export * from "./mcphandler.js"

package/src/mcp.ts

@@ -6,6 +6,8 @@
 import { readFileSync } from "node:fs"
 import { Client } from "@modelcontextprotocol/sdk/client/index.js"
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"
+import { AjvJsonSchemaValidator } from "@modelcontextprotocol/sdk/validation/ajv"
+import type { jsonSchemaValidator } from "@modelcontextprotocol/sdk/validation"
 import { AdoptedStdioTransport } from "./mcp2026/stdio.js"
 import type { Tool as McpToolDef, ElicitRequest, ElicitResult } from "@modelcontextprotocol/sdk/types.js"
 import { ElicitRequestSchema } from "@modelcontextprotocol/sdk/types.js"
@@ -464,8 +466,23 @@ function resourceTools(servers: Map<string, ServerConn>): Tool[] {
  *  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). */
+/**
+ * The SDK's default validator, built on first use instead of per Client. Building an Ajv instance
+ * (meta-schemas + formats) costs ~2-3 ms on every connect, yet it is only consulted when a tool
+ * declares an `outputSchema`. Same validator, same results — just not paid for up front.
+ */
+class LazyAjvValidator implements jsonSchemaValidator {
+  private inner?: AjvJsonSchemaValidator
+  getValidator<T>(schema: Parameters<jsonSchemaValidator["getValidator"]>[0]) {
+    return (this.inner ??= new AjvJsonSchemaValidator()).getValidator<T>(schema)
+  }
+}
+
 function newMcpClient(waitFor?: (request: Request) => Promise<Answer>): Client {
-  const client = new Client({ name: "toolnexus", version: "0.1.0" }, { capabilities: waitFor ? { elicitation: {} } : {} })
+  const client = new Client(
+    { name: "toolnexus", version: "0.1.0" },
+    { capabilities: waitFor ? { elicitation: {} } : {}, jsonSchemaValidator: new LazyAjvValidator() },
+  )
   if (waitFor) {
     client.setRequestHandler(ElicitRequestSchema, async (request) =>
       answerToElicitResult(await waitFor(elicitationToRequest(request.params))),

package/src/nodefetch.ts

@@ -0,0 +1,143 @@
+/**
+ * Default LLM transport: a `fetch`-shaped function over `node:http`/`node:https` with a shared
+ * keep-alive agent.
+ *
+ * Why: Node's built-in `fetch` (undici + web streams) costs ~1.5 ms per local round-trip, against
+ * ~0.3 ms for `node:http` on the same keep-alive socket. With two LLM calls per tool-calling turn
+ * that was most of the client's per-request overhead (benchmarks/run_toolnexus_js.mjs).
+ *
+ * Behavior is kept identical to `fetch` for what the client uses (status, headers incl.
+ * Retry-After, json/text, a streamed `body` for SSE, abort via `signal` rejecting with its reason).
+ * Anything this path does not cover is handed to `globalThis.fetch` unchanged: a proxy env
+ * (`HTTP(S)_PROXY`, `NODE_USE_ENV_PROXY`), a replaced global `fetch`, a non-http(s) URL, a body
+ * that is not a string/bytes, and redirects.
+ */
+import http from "node:http"
+import https from "node:https"
+import { Readable } from "node:stream"
+import zlib from "node:zlib"
+
+const nativeFetch = globalThis.fetch
+const httpAgent = new http.Agent({ keepAlive: true })
+const httpsAgent = new https.Agent({ keepAlive: true })
+
+function proxyEnv(): boolean {
+  const e = process.env
+  return !!(e.HTTP_PROXY || e.HTTPS_PROXY || e.http_proxy || e.https_proxy || e.NODE_USE_ENV_PROXY)
+}
+
+function toHeaderRecord(h: RequestInit["headers"]): Record<string, string> {
+  const out: Record<string, string> = {}
+  if (!h) return out
+  if (h instanceof Headers || Array.isArray(h)) {
+    for (const [k, v] of h as Iterable<[string, string]>) out[k] = v
+    return out
+  }
+  return { ...(h as Record<string, string>) }
+}
+
+// undici's global dispatcher slot. Node fills it lazily with a default Agent on the first fetch;
+// anything else there (a ProxyAgent, a mock, a tuned Agent) means the host routed fetch on purpose.
+const DISPATCHER = Symbol.for("undici.globalDispatcher.1")
+let knownDefaultDispatcher: unknown
+
+function customDispatcher(): boolean {
+  const d = (globalThis as Record<symbol, unknown>)[DISPATCHER]
+  return d !== undefined && d !== knownDefaultDispatcher
+}
+
+/** Calls the platform fetch; if that call is what created Node's default dispatcher, remember it
+ * so later calls still take the fast path. */
+function platformFetch(input: Parameters<typeof fetch>[0], init?: RequestInit): Promise<Response> {
+  const before = (globalThis as Record<symbol, unknown>)[DISPATCHER]
+  const p = globalThis.fetch(input, init)
+  if (before === undefined) {
+    const after = (globalThis as Record<symbol, unknown>)[DISPATCHER]
+    if (after !== undefined) knownDefaultDispatcher = after
+  }
+  return p
+}
+
+const REDIRECTS = new Set([301, 302, 303, 307, 308])
+
+export const nodeFetch: typeof fetch = (input, init) => {
+  const fallback = () => platformFetch(input, init)
+  if (globalThis.fetch !== nativeFetch || proxyEnv() || customDispatcher()) return fallback()
+  if (init?.redirect && init.redirect !== "follow") return fallback()
+  const url = typeof input === "string" ? input : input instanceof URL ? input.href : undefined
+  const body = init?.body
+  if (url === undefined || (body != null && typeof body !== "string" && !(body instanceof Uint8Array))) return fallback()
+  const isHttps = url.startsWith("https:")
+  if (!isHttps && !url.startsWith("http:")) return fallback()
+  const signal = init?.signal ?? undefined
+  if (signal?.aborted) return Promise.reject(signal.reason)
+
+  return new Promise<Response>((resolve, reject) => {
+    const headers = toHeaderRecord(init?.headers)
+    if (body != null && !Object.keys(headers).some((k) => k.toLowerCase() === "content-length")) {
+      headers["content-length"] = String(typeof body === "string" ? Buffer.byteLength(body) : body.byteLength)
+    }
+    const mod = isHttps ? https : http
+    let settled = false
+    const onAbort = () => {
+      req.destroy(signal!.reason)
+      if (!settled) { settled = true; reject(signal!.reason) }
+    }
+    const req = mod.request(url, { method: init?.method ?? "GET", headers, agent: isHttps ? httpsAgent : httpAgent }, (res) => {
+      const status = res.statusCode ?? 0
+      if (REDIRECTS.has(status) && res.headers.location) {
+        // Follow it the way fetch does, from the redirect target: re-sending to the original URL
+        // would reach the server twice. 303, and 301/302 after a POST, become a bodiless GET;
+        // 307/308 repeat the method and body. Further hops are fetch's to follow.
+        res.resume()
+        signal?.removeEventListener("abort", onAbort)
+        settled = true
+        const target = new URL(res.headers.location, url).href
+        const method = (init?.method ?? "GET").toUpperCase()
+        const toGet = status === 303 ? method !== "HEAD" : (status === 301 || status === 302) && method === "POST"
+        let next: RequestInit | undefined = init
+        if (toGet) {
+          const h = toHeaderRecord(init?.headers)
+          for (const k of Object.keys(h)) {
+            if (/^content-(type|length|encoding|language|location)$/i.test(k)) delete h[k]
+          }
+          next = { ...init, method: "GET", body: undefined, headers: h }
+        }
+        platformFetch(target, next).then(resolve, reject)
+        return
+      }
+      const h = new Headers()
+      for (let i = 0; i < res.rawHeaders.length; i += 2) h.append(res.rawHeaders[i], res.rawHeaders[i + 1])
+      let stream: Readable = res
+      const enc = (res.headers["content-encoding"] ?? "").toLowerCase()
+      if (enc === "gzip" || enc === "x-gzip" || enc === "deflate") stream = res.pipe(zlib.createUnzip())
+      else if (enc === "br") stream = res.pipe(zlib.createBrotliDecompress())
+      const nullBody = status === 204 || status === 304 || init?.method === "HEAD"
+      const ctype = (res.headers["content-type"] ?? "").toLowerCase()
+      const done = (b: ConstructorParameters<typeof Response>[0]) => {
+        if (settled) return
+        settled = true
+        resolve(new Response(nullBody ? null : b, { status, statusText: res.statusMessage, headers: h }))
+      }
+      if (ctype.includes("text/event-stream")) {
+        // Streamed: the body is consumed incrementally (SSE). Abort still destroys the socket.
+        stream.once("end", () => signal?.removeEventListener("abort", onAbort))
+        done(Readable.toWeb(stream) as unknown as ReadableStream)
+        return
+      }
+      const chunks: Buffer[] = []
+      stream.on("data", (c: Buffer) => chunks.push(c))
+      stream.once("error", (e) => { if (!settled) { settled = true; reject(e) } })
+      stream.once("end", () => {
+        signal?.removeEventListener("abort", onAbort)
+        done(Buffer.concat(chunks))
+      })
+    })
+    req.once("error", (e) => {
+      signal?.removeEventListener("abort", onAbort)
+      if (!settled) { settled = true; reject(signal?.aborted ? signal.reason : new TypeError("fetch failed", { cause: e })) }
+    })
+    signal?.addEventListener("abort", onAbort, { once: true })
+    req.end(body ?? undefined)
+  })
+}

package/src/transcript_search.ts

@@ -0,0 +1,172 @@
+/**
+ * `transcriptSearchTool` — read-only search over a {@link ConversationStore} (SPEC.md §7E
+ * "Memory hierarchy" → transcript search). The ground-truth tier of agent memory: a dreaming
+ * persona checks its notes against what actually happened, not against its own notes.
+ */
+import { defineTool } from "./native.js"
+import type { Tool } from "./types.js"
+import type { ConversationEntry, ConversationStore } from "./client.js"
+
+/** Options for {@link transcriptSearchTool}. */
+export interface TranscriptSearchOptions {
+  /** Most hits returned per call (and the ceiling for the `limit` input). Default 20. */
+  maxResults?: number
+  /** Snippet length in characters (Unicode code points, not bytes). Default 200. */
+  snippetChars?: number
+  /** Tool name. Default `transcript_search`. */
+  name?: string
+}
+
+/** A store that can enumerate its conversations — what transcript search requires. */
+export type ListableConversationStore = ConversationStore & { list(): Promise<ConversationEntry[]> }
+
+export const TRANSCRIPT_SEARCH_DESCRIPTION =
+  "Search past conversation transcripts — the ground truth of what actually happened. " +
+  "Case-insensitive substring match over message text. Returns one line per matching " +
+  "message: <conversationId>#<index> <role>: <snippet>. Read-only."
+
+const WS = /[ \t\n\r\f\v]+/g
+
+/** Collapse every run of ASCII whitespace to one space and trim (§7E). */
+function normalize(s: string): string {
+  return s.replace(WS, " ").replace(/^ | $/g, "")
+}
+
+/** ASCII-only case fold — never Unicode lowercasing (it changes lengths, differs per port). */
+function fold(s: string): string {
+  return s.replace(/[A-Z]/g, (c) => String.fromCharCode(c.charCodeAt(0) + 32))
+}
+
+/** Code-point order (not UTF-16 code-unit order, which differs above U+FFFF). */
+function byCodePoint(a: string, b: string): number {
+  const x = Array.from(a)
+  const y = Array.from(b)
+  for (let i = 0; i < x.length && i < y.length; i++) {
+    const d = x[i].codePointAt(0)! - y[i].codePointAt(0)!
+    if (d !== 0) return d
+  }
+  return x.length - y.length
+}
+
+/** A copy with every object's keys sorted by code point, recursively (§7E); arrays keep order. */
+function sortKeys(v: unknown): unknown {
+  if (Array.isArray(v)) return v.map(sortKeys)
+  if (v && typeof v === "object" && Object.getPrototypeOf(v) === Object.prototype) {
+    const o = v as Record<string, unknown>
+    const out: Record<string, unknown> = {}
+    for (const k of Object.keys(o).sort(byCodePoint)) out[k] = sortKeys(o[k])
+    return out
+  }
+  return v
+}
+
+function partsText(content: unknown): string[] {
+  if (typeof content === "string") return [content]
+  if (!Array.isArray(content)) return []
+  const out: string[] = []
+  for (const p of content) {
+    if (!p || typeof p !== "object") continue
+    const part = p as Record<string, unknown>
+    if (part.type === "text" && typeof part.text === "string") out.push(part.text)
+    else if (part.type === "tool_use") out.push(JSON.stringify(sortKeys(part.input ?? {})))
+    else if (part.type === "tool_result") out.push(...partsText(part.content))
+  }
+  return out
+}
+
+/** The searchable text of one stored message (§7E): string content, text parts, tool_use
+ * input as compact JSON, tool_result content, then each OpenAI tool call's `arguments`
+ * string — pieces joined by "\n", then whitespace-normalized. Images are not text. */
+export function messageText(msg: unknown): string {
+  if (!msg || typeof msg !== "object") return ""
+  const m = msg as Record<string, unknown>
+  const pieces = partsText(m.content)
+  if (Array.isArray(m.tool_calls)) {
+    for (const tc of m.tool_calls as any[]) {
+      const a = tc?.function?.arguments
+      if (typeof a === "string") pieces.push(a)
+    }
+  }
+  return normalize(pieces.join("\n"))
+}
+
+/** Snippet of `snippetChars` code points centred on the match; `…` marks elision. */
+function snippet(cps: string[], at: number, qlen: number, size: number): string {
+  if (cps.length <= size) return cps.join("")
+  let start = at + Math.floor(qlen / 2) - Math.floor(size / 2)
+  start = Math.max(0, Math.min(start, cps.length - size))
+  const end = start + size
+  return (start > 0 ? "…" : "") + cps.slice(start, end).join("") + (end < cps.length ? "…" : "")
+}
+
+/**
+ * A read-only {@link Tool} over `store` (§7E). Construction throws unless the store has
+ * `list()`. Input `{query, conversationId?, limit?}`; output one line per hit,
+ * `<conversationId>#<index> <role>: <snippet>`, `no matches` when none, and a trailing
+ * `(+<k> more)` when hits exceed the limit. Never writes.
+ */
+export function transcriptSearchTool(store: ConversationStore, opts: TranscriptSearchOptions = {}): Tool {
+  if (!store || typeof (store as Partial<ListableConversationStore>).list !== "function") {
+    throw new Error("transcriptSearchTool: the store must implement list()")
+  }
+  const listable = store as ListableConversationStore
+  const maxResults = opts.maxResults ?? 20
+  const snippetChars = opts.snippetChars ?? 200
+  if (!Number.isInteger(maxResults) || maxResults < 1) throw new Error("transcriptSearchTool: maxResults must be an integer >= 1")
+  if (!Number.isInteger(snippetChars) || snippetChars < 1) throw new Error("transcriptSearchTool: snippetChars must be an integer >= 1")
+  return defineTool({
+    name: opts.name ?? "transcript_search",
+    description: TRANSCRIPT_SEARCH_DESCRIPTION,
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Text to find (case-insensitive substring)." },
+        conversationId: { type: "string", description: "Search only this conversation." },
+        limit: { type: "integer", description: `Most hits to return (default and max ${maxResults}).` },
+      },
+      required: ["query"],
+    },
+    run: async (args: Record<string, unknown>) => {
+      const query = typeof args.query === "string" ? normalize(args.query) : ""
+      if (query === "") return { output: "query is required", isError: true }
+      let limit = maxResults
+      if (args.limit !== undefined) {
+        if (!Number.isInteger(args.limit) || (args.limit as number) < 1) {
+          return { output: "limit must be an integer >= 1", isError: true }
+        }
+        limit = Math.min(args.limit as number, maxResults)
+      }
+      const ids =
+        typeof args.conversationId === "string" ? [args.conversationId] : (await listable.list()).map((e) => e.id)
+      const q = Array.from(fold(query))
+      const hits: string[] = []
+      let total = 0
+      for (const id of ids) {
+        const msgs = await listable.get(id)
+        if (!msgs) continue
+        msgs.forEach((msg, index) => {
+          const cps = Array.from(messageText(msg))
+          const hay = Array.from(fold(cps.join("")))
+          const at = indexOfCps(hay, q)
+          if (at < 0) return
+          total++
+          if (hits.length < limit) {
+            const role = typeof (msg as any)?.role === "string" ? (msg as any).role : "unknown"
+            hits.push(`${id}#${index} ${role}: ${snippet(cps, at, q.length, snippetChars)}`)
+          }
+        })
+      }
+      if (total === 0) return "no matches"
+      if (total > hits.length) hits.push(`(+${total - hits.length} more)`)
+      return hits.join("\n")
+    },
+  })
+}
+
+function indexOfCps(hay: string[], needle: string[]): number {
+  outer: for (let i = 0; i + needle.length <= hay.length; i++) {
+    for (let j = 0; j < needle.length; j++) if (hay[i + j] !== needle[j]) continue outer
+    return i
+  }
+  return -1
+}