toolnexus 0.26.0 → 0.28.0

package/dist/skill.js

@@ -12,8 +12,16 @@
 import { readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
-import { parse as parseYaml } from "yaml";
+import { createRequire } from "node:module";
 import { compareCodePoints, compareDiscovery, sortEntriesByName } from "./order.js";
+// yaml is required on the first frontmatter parse, not at import, so a host with no skills never
+// loads it. `require` keeps the parse synchronous (listSkills/loadSkills are sync); yaml's Node
+// entry is CommonJS, so this is the same module instance an `import` would get.
+let yamlParse;
+function parseYaml(src) {
+    yamlParse ??= createRequire(import.meta.url)("yaml").parse;
+    return yamlParse(src);
+}
 export const SKILL_TOOL_DESCRIPTION = `Load a specialized skill when the task at hand matches one of the skills listed in the system prompt.
 
 Use this tool to inject the skill's instructions and resources into current conversation. The output may contain detailed workflow guidance as well as references to scripts, files, etc in the same directory as the skill.
@@ -25,6 +33,8 @@ The skill name must match one of the skills listed in your system prompt.`;
  */
 export const SKILLS_PROMPT_PREAMBLE = "Skills provide specialized instructions and workflows for specific tasks.\n" +
     "Use the skill tool to load a skill when a task matches its description.";
+/** Maximum skill `description` length, in Unicode code points, before a warning (SPEC.md §3). */
+export const SKILL_DESCRIPTION_MAX_CHARS = 1024;
 /**
  * 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.
@@ -304,6 +314,24 @@ function collectCandidates(opts) {
         cands.push(...candidatesFromDefs(opts.skills));
     return cands;
 }
+/**
+ * Warn — never modify — skills whose description exceeds SKILL_DESCRIPTION_MAX_CHARS code
+ * points (SPEC.md §3, #84). Each warning is also sent to the same channel as the
+ * duplicate-name warning. Order follows the given skills (discovery order).
+ */
+function describeWarnings(skills) {
+    const out = [];
+    for (const s of skills) {
+        if (s.description === undefined)
+            continue;
+        const chars = [...s.description].length;
+        if (chars > SKILL_DESCRIPTION_MAX_CHARS) {
+            console.warn(`[toolnexus] skill "${s.name}" (${s.location}) description is ${chars} chars, over ${SKILL_DESCRIPTION_MAX_CHARS} — kept unmodified`);
+            out.push({ location: s.location, reason: "oversized-description", chars });
+        }
+    }
+    return out;
+}
 /** Dedupe candidates by name (first-wins); later duplicates become skips. */
 function mergeCandidates(cands) {
     const skills = {};
@@ -355,7 +383,8 @@ function applySkillsFilter(skills, filter) {
 export function listSkills(input) {
     const opts = typeof input === "string" || Array.isArray(input) ? { dirs: input } : input;
     const merged = mergeCandidates(collectCandidates(opts));
-    return { skills: Object.values(merged.skills), skipped: merged.skipped };
+    const list = Object.values(merged.skills);
+    return { skills: list, skipped: merged.skipped, warnings: describeWarnings(list) };
 }
 /** Discover skills (dirs and/or data) and build the `skill` loader tool. */
 export function loadSkills(input) {
@@ -364,6 +393,7 @@ export function loadSkills(input) {
     const merged = mergeCandidates(collectCandidates(opts));
     const skills = applySkillsFilter(merged.skills, opts.filter);
     const skipped = merged.skipped;
+    const warnings = describeWarnings(Object.values(skills));
     const tool = {
         name: "skill",
         description: SKILL_TOOL_DESCRIPTION,
@@ -426,6 +456,7 @@ export function loadSkills(input) {
         skills,
         tool,
         skipped,
+        warnings,
         prompt() {
             const described = Object.values(skills)
                 .filter((s) => s.description !== undefined)

package/dist/transcript_search.d.ts

@@ -0,0 +1,27 @@
+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 declare const TRANSCRIPT_SEARCH_DESCRIPTION: string;
+/** 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 declare function messageText(msg: unknown): string;
+/**
+ * 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 declare function transcriptSearchTool(store: ConversationStore, opts?: TranscriptSearchOptions): Tool;

package/dist/transcript_search.js

@@ -0,0 +1,165 @@
+/**
+ * `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";
+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) {
+    return s.replace(WS, " ").replace(/^ | $/g, "");
+}
+/** ASCII-only case fold — never Unicode lowercasing (it changes lengths, differs per port). */
+function fold(s) {
+    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, b) {
+    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) {
+    if (Array.isArray(v))
+        return v.map(sortKeys);
+    if (v && typeof v === "object" && Object.getPrototypeOf(v) === Object.prototype) {
+        const o = v;
+        const out = {};
+        for (const k of Object.keys(o).sort(byCodePoint))
+            out[k] = sortKeys(o[k]);
+        return out;
+    }
+    return v;
+}
+function partsText(content) {
+    if (typeof content === "string")
+        return [content];
+    if (!Array.isArray(content))
+        return [];
+    const out = [];
+    for (const p of content) {
+        if (!p || typeof p !== "object")
+            continue;
+        const part = p;
+        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) {
+    if (!msg || typeof msg !== "object")
+        return "";
+    const m = msg;
+    const pieces = partsText(m.content);
+    if (Array.isArray(m.tool_calls)) {
+        for (const tc of m.tool_calls) {
+            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, at, qlen, size) {
+    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, opts = {}) {
+    if (!store || typeof store.list !== "function") {
+        throw new Error("transcriptSearchTool: the store must implement list()");
+    }
+    const listable = store;
+    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) => {
+            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 < 1) {
+                    return { output: "limit must be an integer >= 1", isError: true };
+                }
+                limit = Math.min(args.limit, maxResults);
+            }
+            const ids = typeof args.conversationId === "string" ? [args.conversationId] : (await listable.list()).map((e) => e.id);
+            const q = Array.from(fold(query));
+            const hits = [];
+            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?.role === "string" ? msg.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, needle) {
+    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;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolnexus",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "description": "Dynamic MCP servers + agent skills as uniform tools for any LLM (opencode-style).",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,7 +17,7 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "npm run build && node --experimental-strip-types --test test/unit.test.ts test/agents.test.ts test/agent-hooks.test.ts test/agent-inprocess.test.ts test/home.test.ts test/compaction.test.ts test/loop.test.ts test/in-process.test.ts test/translate.test.ts test/multimodal.test.ts test/classifier.test.ts test/classifier-backends.test.ts test/acp.test.ts test/acp-client.test.ts test/issues.test.ts test/host-boundary.test.ts test/judge.test.ts test/batteries.test.ts test/host-engine.test.ts test/host-turn-durability.test.ts test/host-engine-asks.test.ts test/tool-concurrency.test.ts test/media.test.ts test/examples.test.ts test/mcphandler.test.ts test/mcphandler-conformance.test.ts test/mcp2026.test.ts test/serve-mcp-conformance.test.ts",
+    "test": "npm run build && node --experimental-strip-types --test test/unit.test.ts test/agents.test.ts test/agent-hooks.test.ts test/agent-inprocess.test.ts test/home.test.ts test/memory-hierarchy.test.ts test/compaction.test.ts test/loop.test.ts test/in-process.test.ts test/translate.test.ts test/multimodal.test.ts test/classifier.test.ts test/classifier-backends.test.ts test/acp.test.ts test/acp-client.test.ts test/issues.test.ts test/host-boundary.test.ts test/judge.test.ts test/batteries.test.ts test/host-engine.test.ts test/host-turn-durability.test.ts test/host-engine-asks.test.ts test/tool-concurrency.test.ts test/media.test.ts test/examples.test.ts test/mcphandler.test.ts test/mcphandler-conformance.test.ts test/mcp2026.test.ts test/serve-mcp-conformance.test.ts test/mock-llm.test.ts test/nodefetch.test.ts test/retry-stream.test.ts test/stop-recovery.test.ts test/round-boundary.test.ts test/reactive-compaction.test.ts test/fallback-models.test.ts",
     "example": "node --experimental-strip-types examples/basic.ts",
     "example:judge": "node --experimental-strip-types examples/judge.ts",
     "example:multimodal": "node --experimental-strip-types examples/multimodal.ts",

package/src/acp.ts

@@ -86,15 +86,34 @@ export interface ACPOptions {
 /** One warm ACP connection: one child process, one session, alive across many
  *  turns. `.generate` has exactly the shape {@link InProcessOptions.generate}
  *  wants, so it plugs straight into {@link createInProcessClient}. */
+/** Per-call options for {@link ACPClient.generate} / {@link ACPClient.generateStream}. */
+export interface ACPGenerateOptions {
+  /** Cancels the turn: when it aborts mid-turn the `session/cancel` notification is sent,
+   *  the turn's reply is awaited (bounded by `requestTimeoutMs`, default 30s) so the next
+   *  turn never lands on a busy session, and the call rejects with an `AbortError`. The
+   *  process and session stay warm. */
+  signal?: AbortSignal
+}
+
 export interface ACPClient {
-  generate: (request: InProcessRequest) => Promise<InProcessResponse>
+  generate: (request: InProcessRequest, opts?: ACPGenerateOptions) => Promise<InProcessResponse>
   /** {@link generate}, streaming: `emit` fires as each `session/update` arrives —
    *  agent_message_chunk → `text`, agent_thought_chunk → `thought` (via "acp"),
    *  tool_call → `tool_call` and a completed/failed tool_call_update → `tool_result`
    *  (both via "acp": the agent's own tools, reported, never executed by the loop).
    *  Shaped for {@link InProcessOptions.generateStream}. The returned content is the
    *  message text only. */
-  generateStream: (request: InProcessRequest, emit: (event: StreamEvent) => void) => Promise<InProcessResponse>
+  generateStream: (
+    request: InProcessRequest,
+    emit: (event: StreamEvent) => void,
+    opts?: ACPGenerateOptions,
+  ) => Promise<InProcessResponse>
+  /** Sends `session/set_mode {sessionId, modeId}` on the running session (no restart). The
+   *  agent's error rejects this call only; the client stays usable. */
+  setMode: (mode: string) => Promise<void>
+  /** Changes the model on the running session exactly as the `model` option does:
+   *  `session/set_config_option {configId:"model"}`, then `session/set_model`; both failing rejects. */
+  setModel: (model: string) => Promise<void>
   /** Terminates the agent's process group. Idempotent — a second call is a no-op. */
   close: () => Promise<void>
   /** The agent's raw `initialize` result. */
@@ -353,20 +372,21 @@ export async function loadACP(opts: ACPOptions): Promise<ACPClient> {
   if (opts.mode) {
     await step("session/set_mode", () => call("session/set_mode", { sessionId, modeId: opts.mode }))
   }
-  if (opts.model) {
-    // Passed through unchanged. Stable ACP spelling first, then the older session/set_model.
-    const model = opts.model
-    await step(`set model ${JSON.stringify(model)}`, async () => {
+  // Passed through unchanged. Stable ACP spelling first, then the older session/set_model.
+  const sendModel = async (model: string): Promise<void> => {
+    try {
+      await call("session/set_config_option", { sessionId, configId: "model", value: model })
+    } catch (e1) {
       try {
-        await call("session/set_config_option", { sessionId, configId: "model", value: model })
-      } catch (e1) {
-        try {
-          await call("session/set_model", { sessionId, modelId: model })
-        } catch (e2) {
-          throw new Error(`${(e1 as Error).message}; ${(e2 as Error).message}`)
-        }
+        await call("session/set_model", { sessionId, modelId: model })
+      } catch (e2) {
+        throw new Error(`${(e1 as Error).message}; ${(e2 as Error).message}`)
       }
-    })
+    }
+  }
+  if (opts.model) {
+    const model = opts.model
+    await step(`set model ${JSON.stringify(model)}`, () => sendModel(model))
   }
 
   // Serialises turns: one ACP session is one conversation, so concurrent
@@ -375,7 +395,12 @@ export async function loadACP(opts: ACPOptions): Promise<ACPClient> {
   // queue itself never rejects (a failed turn does not poison later ones).
   let turnQueue: Promise<unknown> = Promise.resolve()
 
-  async function promptOnce(request: InProcessRequest, emit?: (event: StreamEvent) => void): Promise<InProcessResponse> {
+  async function promptOnce(
+    request: InProcessRequest,
+    emit?: (event: StreamEvent) => void,
+    signal?: AbortSignal,
+  ): Promise<InProcessResponse> {
+    if (signal?.aborted) throw acpAbortError()
     const text = renderPrompt(request)
     const id = `c-${++nextId}`
 
@@ -413,11 +438,18 @@ export async function loadACP(opts: ACPOptions): Promise<ACPClient> {
           break
         }
         case "tool_call_update": {
+          const callId: string = u.toolCallId ?? ""
+          // A non-empty title is remembered as the call's name for every later event (#188).
+          if (u.title) toolNames.set(callId, u.title)
+          const name: string = toolNames.get(callId) || ""
+          const raw = u.rawInput
+          if (raw && typeof raw === "object" && !Array.isArray(raw) && Object.keys(raw).length > 0) {
+            send({ type: "tool_call_args", id: callId, name, args: raw, via: "acp" })
+          }
           if (u.status !== "completed" && u.status !== "failed") break
-          const name: string = u.title || toolNames.get(u.toolCallId ?? "") || ""
           send({
             type: "tool_result",
-            id: u.toolCallId ?? "",
+            id: callId,
             name,
             output: acpToolContentText(u.content),
             isError: u.status === "failed",
@@ -440,21 +472,48 @@ export async function loadACP(opts: ACPOptions): Promise<ACPClient> {
       )
     })
 
+    let onAbort: (() => void) | undefined
+    const cancelled = new Promise<"cancelled">((resolve) => {
+      if (!signal) return
+      onAbort = () => resolve("cancelled")
+      signal.addEventListener("abort", onAbort, { once: true })
+    })
+
     try {
-      const msg = await Promise.race([replyPromise, timeout])
+      const msg = await Promise.race([replyPromise, timeout, cancelled])
+      if (msg === "cancelled") {
+        // ACP: session/cancel is a notification (no id); the agent then ends the turn with
+        // stopReason "cancelled". Wait (bounded) for that reply so the session is idle again.
+        write({ jsonrpc: "2.0", method: "session/cancel", params: { sessionId } })
+        const waitMs = opts.requestTimeoutMs && opts.requestTimeoutMs > 0 ? opts.requestTimeoutMs : 30000
+        let wait: NodeJS.Timeout | undefined
+        await Promise.race([
+          replyPromise,
+          new Promise((r) => {
+            wait = setTimeout(r, waitMs)
+          }),
+        ])
+        clearTimeout(wait)
+        throw acpAbortError()
+      }
       if (msg.error && msg.error.code === 0) throw new Error(msg.error.message)
       if (msg.error) throw new Error(`toolnexus: ACP error ${msg.error.code}: ${msg.error.message}`)
       return { content }
     } finally {
       clearTimeout(timer)
+      if (onAbort) signal!.removeEventListener("abort", onAbort)
       pending.delete(id)
       updateSink = null
     }
   }
 
-  const generateStream = (request: InProcessRequest, emit?: (event: StreamEvent) => void): Promise<InProcessResponse> => {
+  const generateStream = (
+    request: InProcessRequest,
+    emit?: (event: StreamEvent) => void,
+    callOpts?: ACPGenerateOptions,
+  ): Promise<InProcessResponse> => {
     if (closed) return Promise.reject(new Error("toolnexus: ACP client is closed"))
-    const turn = turnQueue.then(() => promptOnce(request, emit))
+    const turn = turnQueue.then(() => promptOnce(request, emit, callOpts?.signal))
     turnQueue = turn.then(
       () => undefined,
       () => undefined,
@@ -478,15 +537,35 @@ export async function loadACP(opts: ACPOptions): Promise<ACPClient> {
     if (t === "late") await Promise.race([childGone, new Promise((r) => setTimeout(r, 1000).unref())])
   }
 
-  const generate = (request: InProcessRequest): Promise<InProcessResponse> => generateStream(request)
+  const generate = (request: InProcessRequest, callOpts?: ACPGenerateOptions): Promise<InProcessResponse> =>
+    generateStream(request, undefined, callOpts)
 
-  const client: ACPClient = { generate, generateStream, close, initializeResult }
+  // SPEC §8C (#197): sent at once on the running session — no restart, not queued behind a turn.
+  const liveCall = async (label: string, fn: () => Promise<unknown>): Promise<void> => {
+    if (closed) throw new Error("toolnexus: ACP client is closed")
+    try {
+      await fn()
+    } catch (e) {
+      throw new Error(`toolnexus: acp: ${label}: ${e instanceof Error ? e.message : String(e)}`)
+    }
+  }
+  const setMode = (mode: string) =>
+    liveCall("session/set_mode", () => call("session/set_mode", { sessionId, modeId: mode }))
+  const setModel = (model: string) => liveCall(`set model ${JSON.stringify(model)}`, () => sendModel(model))
+
+  const client: ACPClient = { generate, generateStream, setMode, setModel, close, initializeResult }
   // Non-enumerable, undocumented — internal test hook only, so the public
   // ACPClient surface stays exactly {generate, generateStream, close}.
   Object.defineProperty(client, "_pid", { value: child.pid, enumerable: false })
   return client
 }
 
+function acpAbortError(): Error {
+  const e = new Error("toolnexus: ACP turn cancelled")
+  e.name = "AbortError"
+  return e
+}
+
 /** Signals the child's whole process group (POSIX), else the child itself. Never throws. */
 function killGroup(pid: number, signal: NodeJS.Signals): void {
   if (process.platform !== "win32") {