toolnexus 0.20.0 → 0.22.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/tooltiers.ts

@@ -0,0 +1,221 @@
+/**
+ * Tool tiers (SPEC §8 "Prompt caching" → Tool tiers, change add-prompt-cache phase 2). With
+ * `ClientOptions.toolTiers` set, only CORE tools are sent with full schemas. LISTED tools appear
+ * as "name — one line" and DEFERRED tools by name only, both inside the description of a
+ * `tool_search` tool that returns full schemas on demand, as a tool result: the tools array
+ * never changes mid-session, so the cached prefix survives. A loaded tool is called by name, or
+ * through `call_tool {name, arguments}`, which the loop unwraps BEFORE hooks.
+ */
+import type { Tool, ToolResult } from "./types.js"
+
+/** `ClientOptions.toolTiers`. */
+export interface ToolTierOptions {
+  /** Always sent with their full schema. */
+  core?: string[]
+  /** Named only. Every other tool is listed (name + one line). A tool registered after the
+   * plan froze is deferred and found by search. */
+  deferred?: string[]
+  /** Caps the tokens sent up front (core schemas + tool_search + call_tool). Absent/0 ⇒ 5% of
+   * `contextWindow`; both absent ⇒ no budget. Over budget, the least-used core tools move to
+   * listed, then the least-used listed tools to deferred. */
+  budgetTokens?: number
+  contextWindow?: number
+  /** Host per-tool usage stat (higher = more used), read only when the plan is built. */
+  usageCount?: (name: string) => number
+  /** Token estimate of a JSON-encodable value; default ceil(bytes/4). */
+  countTokens?: (v: unknown) => number
+}
+
+export type ToolTier = "core" | "listed" | "deferred"
+
+/** The frozen tier assignment for one toolkit. */
+export interface ToolPlan {
+  tier: Map<string, ToolTier>
+  core: string[]
+  listed: string[]
+  deferred: string[]
+  search: Tool
+  call: Tool
+}
+
+const cmp = (a: string, b: string) => (a < b ? -1 : a > b ? 1 : 0)
+
+export function defaultCountTokens(v: unknown): number {
+  return Math.ceil(Buffer.byteLength(JSON.stringify(v) ?? "", "utf8") / 4)
+}
+
+export function toolDef(t: Tool): Record<string, unknown> {
+  return { name: t.name, description: t.description, inputSchema: t.inputSchema }
+}
+
+function firstLine(s: string): string {
+  const i = s.indexOf("\n")
+  if (i >= 0) s = s.slice(0, i)
+  // Go cuts at 120 BYTES; cut at 120 UTF-8 bytes too, without splitting a character.
+  if (Buffer.byteLength(s, "utf8") > 120) {
+    let out = ""
+    for (const ch of s) {
+      if (Buffer.byteLength(out + ch, "utf8") > 120) break
+      out += ch
+    }
+    s = out + "…"
+  }
+  return s
+}
+
+const notRun = async (): Promise<ToolResult> => ({ output: "engine-internal tool: run by the client loop", isError: true })
+
+function rebuild(p: ToolPlan, byName: Map<string, Tool>): void {
+  p.core = []
+  p.listed = []
+  p.deferred = []
+  for (const [n, t] of p.tier) (t === "core" ? p.core : t === "listed" ? p.listed : p.deferred).push(n)
+  p.core.sort(cmp)
+  p.listed.sort(cmp)
+  p.deferred.sort(cmp)
+  let d =
+    'Load the full schema of tools that are not shown in full, then call them by name (or with call_tool). Query by keywords, or "select:a,b" for exact names.'
+  if (p.listed.length) {
+    d += "\n\nAvailable tools:"
+    for (const n of p.listed) {
+      d += "\n- " + n
+      const line = firstLine(byName.get(n)?.description ?? "")
+      if (line) d += " — " + line
+    }
+  }
+  if (p.deferred.length) d += "\n\nMore tools (name only): " + p.deferred.join(", ")
+  p.search = {
+    name: "tool_search",
+    description: d,
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Keywords, or select:name1,name2" },
+        limit: { type: "number", description: "Maximum results for a keyword query (default 5)" },
+      },
+      required: ["query"],
+      additionalProperties: false,
+    },
+    source: "builtin",
+    hints: { readOnly: true, destructive: false, openWorld: false },
+    execute: notRun,
+  }
+  p.call = {
+    name: "call_tool",
+    description: "Call a tool loaded with tool_search, by name, with its arguments.",
+    inputSchema: {
+      type: "object",
+      properties: { name: { type: "string" }, arguments: { type: "object" } },
+      required: ["name"],
+      additionalProperties: false,
+    },
+    source: "builtin",
+    execute: notRun,
+  }
+}
+
+/** Build a tier plan over `tools` (exported for tests and host UIs). */
+export function buildToolPlan(o: ToolTierOptions, tools: Tool[]): ToolPlan {
+  const count = o.countTokens ?? defaultCountTokens
+  const usage = (n: string) => (o.usageCount ? o.usageCount(n) : 0)
+  const byName = new Map(tools.map((t) => [t.name, t] as const))
+  const tier = new Map<string, ToolTier>()
+  for (const t of tools) tier.set(t.name, "listed")
+  for (const n of o.deferred ?? []) if (tier.has(n)) tier.set(n, "deferred")
+  for (const n of o.core ?? []) if (tier.has(n)) tier.set(n, "core")
+  const p = { tier } as ToolPlan
+  rebuild(p, byName)
+
+  let budget = o.budgetTokens ?? 0
+  if (!budget && o.contextWindow && o.contextWindow > 0) budget = Math.floor(o.contextWindow / 20)
+  if (budget > 0) {
+    const cost = () => {
+      let n = count(toolDef(p.search)) + count(toolDef(p.call))
+      for (const name of p.core) n += count(toolDef(byName.get(name)!))
+      return n
+    }
+    // least used first; ties: bigger schema first, then name
+    const order = (names: string[]) =>
+      [...names].sort((a, b) => {
+        const ua = usage(a), ub = usage(b)
+        if (ua !== ub) return ua - ub
+        const sa = count(toolDef(byName.get(a)!)), sb = count(toolDef(byName.get(b)!))
+        if (sa !== sb) return sb - sa
+        return cmp(a, b)
+      })
+    for (const n of order(p.core)) {
+      if (cost() <= budget) break
+      tier.set(n, "listed")
+      rebuild(p, byName)
+    }
+    for (const n of order(p.listed)) {
+      if (cost() <= budget) break
+      tier.set(n, "deferred")
+      rebuild(p, byName)
+    }
+  }
+  return p
+}
+
+/** `call_tool {name, arguments}` → the real call; `undefined` when `name` is not call_tool. */
+export function unwrapCallTool(name: string, args: Record<string, unknown>): { name: string; args: Record<string, unknown> } | undefined {
+  if (name !== "call_tool") return undefined
+  const real = typeof args?.name === "string" ? args.name : ""
+  const inner = args?.arguments && typeof args.arguments === "object" && !Array.isArray(args.arguments) ? (args.arguments as Record<string, unknown>) : {}
+  return { name: real, args: inner }
+}
+
+/** Keys sorted at every level, so the loaded definitions print the same bytes as the Go port. */
+function sortKeys(v: unknown): unknown {
+  if (Array.isArray(v)) return v.map(sortKeys)
+  if (v && typeof v === "object") {
+    const out: Record<string, unknown> = {}
+    for (const k of Object.keys(v as object).sort(cmp)) out[k] = sortKeys((v as Record<string, unknown>)[k])
+    return out
+  }
+  return v
+}
+
+/** Go's json escapes `<`, `>`, `&`, U+2028 and U+2029 inside strings; they never occur outside one. */
+export function goHtmlEscape(json: string): string {
+  return json.replace(/[<>&\u2028\u2029]/g, (c) => "\\u" + c.charCodeAt(0).toString(16).padStart(4, "0"))
+}
+
+/** Run `tool_search` over every tool (any tier). */
+export function toolSearch(all: Tool[], get: (name: string) => Tool | undefined, args: Record<string, unknown>): ToolResult {
+  const q = (typeof args.query === "string" ? args.query : "").trim()
+  if (!q) return { output: "tool_search: query is required", isError: true }
+  let picked: Tool[] = []
+  if (q.startsWith("select:")) {
+    const missing: string[] = []
+    for (const raw of q.slice("select:".length).split(",")) {
+      const n = raw.trim()
+      if (!n) continue
+      const t = get(n)
+      if (t) picked.push(t)
+      else missing.push(n)
+    }
+    if (missing.length && !picked.length) return { output: "tool_search: no such tool: " + missing.join(", "), isError: true }
+  } else {
+    const limit = typeof args.limit === "number" && args.limit >= 1 ? Math.trunc(args.limit) : 5
+    const terms = q.toLowerCase().split(/\s+/).filter(Boolean)
+    const hits: Array<{ t: Tool; score: number }> = []
+    for (const t of all) {
+      const name = t.name.toLowerCase(), desc = t.description.toLowerCase()
+      let s = 0
+      for (const term of terms) {
+        if (name.includes(term)) s += 3
+        if (desc.includes(term)) s += 1
+      }
+      if (s > 0) hits.push({ t, score: s })
+    }
+    hits.sort((a, b) => b.score - a.score || cmp(a.t.name, b.t.name))
+    picked = hits.slice(0, limit).map((h) => h.t)
+  }
+  if (!picked.length) return { output: "No matching tools.", isError: false, metadata: { count: 0 } }
+  return {
+    output: "Loaded tools (call by name, or with call_tool):\n" + goHtmlEscape(JSON.stringify(sortKeys(picked.map(toolDef)), null, 2)),
+    isError: false,
+    metadata: { count: picked.length, tools: picked.map((t) => t.name) },
+  }
+}

package/src/types.ts

@@ -32,6 +32,23 @@ export interface ToolContext {
   timeout?: number
   /** Present ONLY on a post-waitFor retry (§10): the resolution of a prior suspension. */
   answer?: Answer
+  /** The model's id for this tool call, set by the client loop (§4C). A message's calls run
+   * concurrently, so this is how a tool tells its sibling calls apart. Absent outside the loop. */
+  callId?: string
+}
+
+/**
+ * Advisory behavior hints (named after MCP tool annotations, §4C), for host permission gates
+ * built on `hooks.beforeTool`. Absent on a tool = unknown; treat it as mutating. Never sent to
+ * the model: no adapter or wire output carries them.
+ */
+export interface ToolHints {
+  /** The tool does not change its environment. */
+  readOnly: boolean
+  /** The tool may overwrite or delete things (meaningful when not readOnly). */
+  destructive: boolean
+  /** The tool reaches outside the host (network, external systems). */
+  openWorld: boolean
 }
 
 /**
@@ -110,6 +127,9 @@ export interface Tool {
   inputSchema: JSONSchema
   source: ToolSource
   execute(args: Record<string, unknown>, ctx?: ToolContext): Promise<ToolResult>
+  /** What the tool may do (§4C). Builtins always carry hints; MCP tools carry them when the
+   * server sends annotations. Advisory: a server can mislabel its tools. */
+  hints?: ToolHints
 }
 
 export type McpStatus = "connected" | "disabled" | "failed"