toolnexus 0.27.0 → 0.28.0

package/dist/index.d.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/dist/index.js

@@ -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/dist/mcp.js

@@ -6,6 +6,7 @@
 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 { AdoptedStdioTransport } from "./mcp2026/stdio.js";
 import { ElicitRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { sanitize } from "./types.js";
@@ -398,8 +399,19 @@ function resourceTools(servers) {
  *  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 {
+    inner;
+    getValidator(schema) {
+        return (this.inner ??= new AjvJsonSchemaValidator()).getValidator(schema);
+    }
+}
 function newMcpClient(waitFor) {
-    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/dist/nodefetch.d.ts

@@ -0,0 +1 @@
+export declare const nodeFetch: typeof fetch;

package/dist/nodefetch.js

@@ -0,0 +1,156 @@
+/**
+ * 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() {
+    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) {
+    const out = {};
+    if (!h)
+        return out;
+    if (h instanceof Headers || Array.isArray(h)) {
+        for (const [k, v] of h)
+            out[k] = v;
+        return out;
+    }
+    return { ...h };
+}
+// 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;
+function customDispatcher() {
+    const d = globalThis[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, init) {
+    const before = globalThis[DISPATCHER];
+    const p = globalThis.fetch(input, init);
+    if (before === undefined) {
+        const after = globalThis[DISPATCHER];
+        if (after !== undefined)
+            knownDefaultDispatcher = after;
+    }
+    return p;
+}
+const REDIRECTS = new Set([301, 302, 303, 307, 308]);
+export const nodeFetch = (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((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 = 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 = 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) => {
+                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));
+                return;
+            }
+            const chunks = [];
+            stream.on("data", (c) => 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/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.27.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

@@ -108,6 +108,12 @@ export interface ACPClient {
     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. */
@@ -366,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
@@ -431,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",
@@ -526,7 +540,20 @@ export async function loadACP(opts: ACPOptions): Promise<ACPClient> {
   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 })