@tangle-network/agent-runtime 0.104.0 → 0.106.0

package/dist/mcp/memory-bin.js

@@ -1,22 +1,43 @@
 #!/usr/bin/env node
-import {
-  createMemoryToolServer,
-  resolveMemoryFromEnv
-} from "../chunk-L5DST3QC.js";
-import "../chunk-YEJR7IXO.js";
-
-// src/mcp/memory-bin.ts
+import { a as createMemoryToolServer, c as resolveMemoryFromEnv } from "../memory-server-DL6cE2Ag.js";
+//#region src/mcp/memory-bin.ts
+/**
+* `agent-runtime-memory-mcp` — stdio memory MCP server entry point.
+*
+* Serves `memory_search` / `memory_get` over an agent's curated memory rows,
+* on the generic in-repo JSON-RPC core (`createStdioToolServer`). This is the
+* process `memoryMcpServer` (lifecycle/memory.ts) mounts into `profile.mcp`,
+* which the same-host client (`materializeLocalMcp`) spawns next to the
+* driven worker during a scored run.
+*
+* Environment variables (the `memoryMcpServer` contract):
+*   AGENT_MEMORY_FILE    optional — path to the durable row store (JSON array
+*                        or JSONL of MemoryItem).
+*   AGENT_MEMORY_ITEMS   optional — inline JSON array of MemoryItem rows;
+*                        wins over file rows on id collision.
+*   AGENT_MEMORY_LOG     optional — JSONL retrieval log, one row per
+*                        memory_search (the retrieval-holdout seam).
+*   AGENT_MEMORY_NAME    optional — server display name (default 'agent-memory').
+*
+* At least one of AGENT_MEMORY_FILE / AGENT_MEMORY_ITEMS must resolve rows:
+* an EMPTY memory refuses to boot (fail-closed, so a memory-carrying profile
+* whose store is missing fails the materialization, never a silent no-tool run).
+*
+* @experimental
+*/
 async function main() {
-  const { items, serverName, logPath } = resolveMemoryFromEnv(process.env);
-  const server = createMemoryToolServer({
-    items,
-    ...serverName ? { serverName } : {},
-    ...logPath ? { logPath } : {}
-  });
-  await server.serve();
+	const { items, serverName, logPath } = resolveMemoryFromEnv(process.env);
+	await createMemoryToolServer({
+		items,
+		...serverName ? { serverName } : {},
+		...logPath ? { logPath } : {}
+	}).serve();
 }
 main().catch((err) => {
-  console.error(`agent-runtime-memory-mcp: ${err instanceof Error ? err.message : String(err)}`);
-  process.exit(1);
+	console.error(`agent-runtime-memory-mcp: ${err instanceof Error ? err.message : String(err)}`);
+	process.exit(1);
 });
+//#endregion
+export {};
+
 //# sourceMappingURL=memory-bin.js.map

package/dist/mcp/memory-bin.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/mcp/memory-bin.ts"],"sourcesContent":["#!/usr/bin/env node\n\n/**\n * `agent-runtime-memory-mcp` — stdio memory MCP server entry point.\n *\n * Serves `memory_search` / `memory_get` over an agent's curated memory rows,\n * on the generic in-repo JSON-RPC core (`createStdioToolServer`). This is the\n * process `memoryMcpServer` (lifecycle/memory.ts) mounts into `profile.mcp`,\n * which the same-host client (`materializeLocalMcp`) spawns next to the\n * driven worker during a scored run.\n *\n * Environment variables (the `memoryMcpServer` contract):\n *   AGENT_MEMORY_FILE    optional — path to the durable row store (JSON array\n *                        or JSONL of MemoryItem).\n *   AGENT_MEMORY_ITEMS   optional — inline JSON array of MemoryItem rows;\n *                        wins over file rows on id collision.\n *   AGENT_MEMORY_LOG     optional — JSONL retrieval log, one row per\n *                        memory_search (the retrieval-holdout seam).\n *   AGENT_MEMORY_NAME    optional — server display name (default 'agent-memory').\n *\n * At least one of AGENT_MEMORY_FILE / AGENT_MEMORY_ITEMS must resolve rows:\n * an EMPTY memory refuses to boot (fail-closed, so a memory-carrying profile\n * whose store is missing fails the materialization, never a silent no-tool run).\n *\n * @experimental\n */\n\nimport { createMemoryToolServer, resolveMemoryFromEnv } from './memory-server'\n\nasync function main(): Promise<void> {\n  const { items, serverName, logPath } = resolveMemoryFromEnv(process.env)\n  const server = createMemoryToolServer({\n    items,\n    ...(serverName ? { serverName } : {}),\n    ...(logPath ? { logPath } : {}),\n  })\n  await server.serve()\n}\n\nmain().catch((err: unknown) => {\n  console.error(`agent-runtime-memory-mcp: ${err instanceof Error ? err.message : String(err)}`)\n  process.exit(1)\n})\n"],"mappings":";;;;;;;;AA6BA,eAAe,OAAsB;AACnC,QAAM,EAAE,OAAO,YAAY,QAAQ,IAAI,qBAAqB,QAAQ,GAAG;AACvE,QAAM,SAAS,uBAAuB;AAAA,IACpC;AAAA,IACA,GAAI,aAAa,EAAE,WAAW,IAAI,CAAC;AAAA,IACnC,GAAI,UAAU,EAAE,QAAQ,IAAI,CAAC;AAAA,EAC/B,CAAC;AACD,QAAM,OAAO,MAAM;AACrB;AAEA,KAAK,EAAE,MAAM,CAAC,QAAiB;AAC7B,UAAQ,MAAM,6BAA6B,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG,CAAC,EAAE;AAC7F,UAAQ,KAAK,CAAC;AAChB,CAAC;","names":[]}
+{"version":3,"file":"memory-bin.js","names":[],"sources":["../../src/mcp/memory-bin.ts"],"sourcesContent":["#!/usr/bin/env node\n\n/**\n * `agent-runtime-memory-mcp` — stdio memory MCP server entry point.\n *\n * Serves `memory_search` / `memory_get` over an agent's curated memory rows,\n * on the generic in-repo JSON-RPC core (`createStdioToolServer`). This is the\n * process `memoryMcpServer` (lifecycle/memory.ts) mounts into `profile.mcp`,\n * which the same-host client (`materializeLocalMcp`) spawns next to the\n * driven worker during a scored run.\n *\n * Environment variables (the `memoryMcpServer` contract):\n *   AGENT_MEMORY_FILE    optional — path to the durable row store (JSON array\n *                        or JSONL of MemoryItem).\n *   AGENT_MEMORY_ITEMS   optional — inline JSON array of MemoryItem rows;\n *                        wins over file rows on id collision.\n *   AGENT_MEMORY_LOG     optional — JSONL retrieval log, one row per\n *                        memory_search (the retrieval-holdout seam).\n *   AGENT_MEMORY_NAME    optional — server display name (default 'agent-memory').\n *\n * At least one of AGENT_MEMORY_FILE / AGENT_MEMORY_ITEMS must resolve rows:\n * an EMPTY memory refuses to boot (fail-closed, so a memory-carrying profile\n * whose store is missing fails the materialization, never a silent no-tool run).\n *\n * @experimental\n */\n\nimport { createMemoryToolServer, resolveMemoryFromEnv } from './memory-server'\n\nasync function main(): Promise<void> {\n  const { items, serverName, logPath } = resolveMemoryFromEnv(process.env)\n  const server = createMemoryToolServer({\n    items,\n    ...(serverName ? { serverName } : {}),\n    ...(logPath ? { logPath } : {}),\n  })\n  await server.serve()\n}\n\nmain().catch((err: unknown) => {\n  console.error(`agent-runtime-memory-mcp: ${err instanceof Error ? err.message : String(err)}`)\n  process.exit(1)\n})\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,eAAe,OAAsB;CACnC,MAAM,EAAE,OAAO,YAAY,YAAY,qBAAqB,QAAQ,GAAG;CAMvE,MALe,uBAAuB;EACpC;EACA,GAAI,aAAa,EAAE,WAAW,IAAI,CAAC;EACnC,GAAI,UAAU,EAAE,QAAQ,IAAI,CAAC;CAC/B,CACW,CAAC,CAAC,MAAM;AACrB;AAEA,KAAK,CAAC,CAAC,OAAO,QAAiB;CAC7B,QAAQ,MAAM,6BAA6B,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG,GAAG;CAC7F,QAAQ,KAAK,CAAC;AAChB,CAAC"}

package/dist/memory-server-DL6cE2Ag.js

@@ -0,0 +1,234 @@
+import { u as ValidationError } from "./errors-DEAvWQPy.js";
+import { t as createStdioToolServer } from "./tool-server-RcWgLIsL.js";
+import { appendFileSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname } from "node:path";
+//#region src/mcp/memory-server.ts
+/**
+* Memory MCP server — the LIVE serving half of the `memory` profile surface
+* (Phase 5). A curated memory (lessons distilled from prior runs) is only
+* real if the DRIVEN agent can query it mid-task; this module serves a flat
+* store of `MemoryItem` rows as `memory_search` / `memory_get` tools over the
+* ONE in-repo stdio JSON-RPC core (`createStdioToolServer`), so the exact
+* wire protocol the same-host client (`connectStdioMcp` /
+* `materializeLocalMcp`, runtime/stdio-mcp-client.ts) speaks is guaranteed by
+* construction — serve and consume cannot drift.
+*
+* Retrieval is DETERMINISTIC lexical overlap (no vectors, no LLM): a lift
+* measured with this memory mounted is attributable to the lessons
+* themselves, never to retrieval-model noise. Every
+* `memory_search` can append one JSONL row to a retrieval log (`logPath`) —
+* the per-query record an off-policy retrieval estimator (agent-knowledge's
+* `RetrievalHoldout`) consumes. agent-knowledge is NOT a dependency of this
+* repo, so the log file is the flagged cross-package seam, not an import.
+*
+* Fail-loud discipline (mirrors `materializeLocalMcp`): an EMPTY memory is
+* never served — a profile without memory simply omits the artifact, and
+* silently serving zero rows would fake the with/without ablation.
+*
+* @experimental
+*/
+/** Env var naming the durable row store file the memory bin loads (the
+*  `memoryMcpServer` ↔ memory-bin contract). */
+const MEMORY_FILE_ENV = "AGENT_MEMORY_FILE";
+/** Env var carrying inline JSON `MemoryItem` rows (win over file rows on id). */
+const MEMORY_ITEMS_ENV = "AGENT_MEMORY_ITEMS";
+/** Env var naming the JSONL retrieval log (one row per `memory_search`). */
+const MEMORY_LOG_ENV = "AGENT_MEMORY_LOG";
+/** Env var overriding the served display name (default 'agent-memory'). */
+const MEMORY_NAME_ENV = "AGENT_MEMORY_NAME";
+/**
+* Build the memory MCP server: `memory_search` (lexical top-k over the rows)
+* and `memory_get` (one row by id) on the generic stdio JSON-RPC core.
+*/
+function createMemoryToolServer(opts) {
+	if (opts.items.length === 0) throw new ValidationError("createMemoryToolServer: refusing to serve an EMPTY memory — a profile without memory omits the artifact; serving zero rows would fake the with/without ablation");
+	const byId = /* @__PURE__ */ new Map();
+	for (const item of opts.items) {
+		if (byId.has(item.id)) throw new ValidationError(`createMemoryToolServer: duplicate memory item id '${item.id}'`);
+		byId.set(item.id, item);
+	}
+	const items = [...byId.values()];
+	const defaultK = opts.defaultK ?? 5;
+	const logPath = opts.logPath;
+	if (logPath) mkdirSync(dirname(logPath), { recursive: true });
+	const search = {
+		name: "memory_search",
+		description: "Search the agent memory of lessons learned from prior runs. Give what you are about to do or the problem you face; returns the top-k lessons ranked by relevance. Consult it BEFORE repeating work a prior run already learned from.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				query: {
+					type: "string",
+					description: "The task/problem at hand — matched against lesson text and tags."
+				},
+				k: {
+					type: "number",
+					description: `Max results (default ${defaultK}).`
+				},
+				tags: {
+					type: "array",
+					items: { type: "string" },
+					description: "Only return items carrying at least one of these tags."
+				}
+			},
+			required: ["query"]
+		},
+		handler: async (raw) => {
+			const args = raw ?? {};
+			if (typeof args.query !== "string" || args.query.trim().length === 0) throw new TypeError("memory_search: query must be a non-empty string");
+			const k = args.k === void 0 ? defaultK : Math.floor(Number(args.k));
+			if (!Number.isFinite(k) || k < 1) throw new TypeError("memory_search: k must be a positive integer");
+			let tagFilter;
+			if (args.tags !== void 0) {
+				if (!Array.isArray(args.tags) || args.tags.some((t) => typeof t !== "string")) throw new TypeError("memory_search: tags must be an array of strings");
+				tagFilter = args.tags;
+			}
+			const queryTokens = tokenize(args.query);
+			const results = (tagFilter ? items.filter((i) => (i.tags ?? []).some((t) => tagFilter.includes(t))) : items).map((item) => ({
+				item,
+				score: scoreItem(queryTokens, item)
+			})).filter((r) => r.score > 0).sort((a, b) => b.score - a.score).slice(0, k).map(({ item, score }) => ({
+				id: item.id,
+				text: item.text,
+				score: Number(score.toFixed(4)),
+				...item.tags ? { tags: item.tags } : {},
+				...item.source ? { source: item.source } : {}
+			}));
+			if (logPath) appendFileSync(logPath, `${JSON.stringify({
+				ts: (/* @__PURE__ */ new Date()).toISOString(),
+				query: args.query,
+				k,
+				returned: results.map((r) => ({
+					id: r.id,
+					score: r.score
+				}))
+			})}\n`);
+			return {
+				query: args.query,
+				results
+			};
+		}
+	};
+	return createStdioToolServer({
+		serverName: opts.serverName ?? "agent-memory",
+		serverVersion: opts.serverVersion ?? "0",
+		tools: [search, {
+			name: "memory_get",
+			description: "Fetch one memory item verbatim by its id (ids come from memory_search results).",
+			inputSchema: {
+				type: "object",
+				properties: { id: {
+					type: "string",
+					description: "The memory item id."
+				} },
+				required: ["id"]
+			},
+			handler: async (raw) => {
+				const args = raw ?? {};
+				if (typeof args.id !== "string" || args.id.trim().length === 0) throw new TypeError("memory_get: id must be a non-empty string");
+				const item = byId.get(args.id);
+				if (!item) throw new Error(`memory_get: no memory item with id '${args.id}'`);
+				return item;
+			}
+		}]
+	});
+}
+/** Coerce an untrusted JSON array into validated `MemoryItem` rows. */
+function parseMemoryItems(value, source) {
+	if (!Array.isArray(value)) throw new ValidationError(`${source}: expected a JSON array of memory items`);
+	return value.map((row, i) => coerceMemoryItem(row, `${source}[${i}]`));
+}
+/** Read a memory store file: a JSON array, or JSONL (one `MemoryItem` per line). */
+function readMemoryItemsFile(path) {
+	let raw;
+	try {
+		raw = readFileSync(path, "utf8");
+	} catch (err) {
+		throw new ValidationError(`readMemoryItemsFile: cannot read '${path}': ${err instanceof Error ? err.message : String(err)}`);
+	}
+	const trimmed = raw.trim();
+	if (trimmed.length === 0) return [];
+	if (trimmed.startsWith("[")) {
+		let parsed;
+		try {
+			parsed = JSON.parse(trimmed);
+		} catch (err) {
+			throw new ValidationError(`readMemoryItemsFile: '${path}' is not valid JSON: ${err.message}`);
+		}
+		return parseMemoryItems(parsed, path);
+	}
+	return trimmed.split("\n").map((line) => line.trim()).filter((line) => line.length > 0).map((line, i) => {
+		let parsed;
+		try {
+			parsed = JSON.parse(line);
+		} catch (err) {
+			throw new ValidationError(`readMemoryItemsFile: '${path}' line ${i + 1} is not valid JSON: ${err.message}`);
+		}
+		return coerceMemoryItem(parsed, `${path}:${i + 1}`);
+	});
+}
+/**
+* Resolve the bin's memory from `AGENT_MEMORY_FILE` (durable store) and/or
+* `AGENT_MEMORY_ITEMS` (inline JSON rows; wins on id collision). Zero rows is
+* a boot FAILURE, matching the fail-closed materialization discipline.
+*/
+function resolveMemoryFromEnv(env) {
+	const filePath = env[MEMORY_FILE_ENV];
+	const inlineRaw = env[MEMORY_ITEMS_ENV];
+	const fromFile = filePath ? readMemoryItemsFile(filePath) : [];
+	let inline = [];
+	if (inlineRaw) {
+		let parsed;
+		try {
+			parsed = JSON.parse(inlineRaw);
+		} catch (err) {
+			throw new ValidationError(`${MEMORY_ITEMS_ENV} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+		}
+		inline = parseMemoryItems(parsed, MEMORY_ITEMS_ENV);
+	}
+	const byId = /* @__PURE__ */ new Map();
+	for (const item of fromFile) byId.set(item.id, item);
+	for (const item of inline) byId.set(item.id, item);
+	if (byId.size === 0) throw new ValidationError(`memory bin: no memory items — set ${MEMORY_FILE_ENV} and/or ${MEMORY_ITEMS_ENV}; an EMPTY memory must never be served (a profile without memory omits the artifact)`);
+	const serverName = env[MEMORY_NAME_ENV];
+	const logPath = env[MEMORY_LOG_ENV];
+	return {
+		items: [...byId.values()],
+		...serverName ? { serverName } : {},
+		...logPath ? { logPath } : {}
+	};
+}
+function coerceMemoryItem(row, at) {
+	if (!row || typeof row !== "object" || Array.isArray(row)) throw new ValidationError(`${at}: memory item must be an object`);
+	const r = row;
+	if (typeof r.id !== "string" || r.id.trim().length === 0) throw new ValidationError(`${at}: 'id' must be a non-empty string`);
+	if (typeof r.text !== "string" || r.text.trim().length === 0) throw new ValidationError(`${at}: 'text' must be a non-empty string`);
+	let tags;
+	if (r.tags !== void 0) {
+		if (!Array.isArray(r.tags) || r.tags.some((t) => typeof t !== "string")) throw new ValidationError(`${at}: 'tags' must be an array of strings`);
+		tags = r.tags;
+	}
+	if (r.source !== void 0 && typeof r.source !== "string") throw new ValidationError(`${at}: 'source' must be a string`);
+	return {
+		id: r.id,
+		text: r.text,
+		...tags ? { tags } : {},
+		...typeof r.source === "string" ? { source: r.source } : {}
+	};
+}
+/** Unique lowercase alphanumeric tokens of length >= 2. */
+function tokenize(text) {
+	return [...new Set(text.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length >= 2))];
+}
+/** Fraction of query tokens present in the item's text + tags (0..1). */
+function scoreItem(queryTokens, item) {
+	if (queryTokens.length === 0) return 0;
+	const hay = new Set(tokenize(`${item.text} ${(item.tags ?? []).join(" ")}`));
+	let hit = 0;
+	for (const t of queryTokens) if (hay.has(t)) hit += 1;
+	return hit / queryTokens.length;
+}
+//#endregion
+export { createMemoryToolServer as a, resolveMemoryFromEnv as c, MEMORY_NAME_ENV as i, MEMORY_ITEMS_ENV as n, parseMemoryItems as o, MEMORY_LOG_ENV as r, readMemoryItemsFile as s, MEMORY_FILE_ENV as t };
+
+//# sourceMappingURL=memory-server-DL6cE2Ag.js.map

package/dist/memory-server-DL6cE2Ag.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-server-DL6cE2Ag.js","names":[],"sources":["../src/mcp/memory-server.ts"],"sourcesContent":["/**\n * Memory MCP server — the LIVE serving half of the `memory` profile surface\n * (Phase 5). A curated memory (lessons distilled from prior runs) is only\n * real if the DRIVEN agent can query it mid-task; this module serves a flat\n * store of `MemoryItem` rows as `memory_search` / `memory_get` tools over the\n * ONE in-repo stdio JSON-RPC core (`createStdioToolServer`), so the exact\n * wire protocol the same-host client (`connectStdioMcp` /\n * `materializeLocalMcp`, runtime/stdio-mcp-client.ts) speaks is guaranteed by\n * construction — serve and consume cannot drift.\n *\n * Retrieval is DETERMINISTIC lexical overlap (no vectors, no LLM): a lift\n * measured with this memory mounted is attributable to the lessons\n * themselves, never to retrieval-model noise. Every\n * `memory_search` can append one JSONL row to a retrieval log (`logPath`) —\n * the per-query record an off-policy retrieval estimator (agent-knowledge's\n * `RetrievalHoldout`) consumes. agent-knowledge is NOT a dependency of this\n * repo, so the log file is the flagged cross-package seam, not an import.\n *\n * Fail-loud discipline (mirrors `materializeLocalMcp`): an EMPTY memory is\n * never served — a profile without memory simply omits the artifact, and\n * silently serving zero rows would fake the with/without ablation.\n *\n * @experimental\n */\n\nimport { appendFileSync, mkdirSync, readFileSync } from 'node:fs'\nimport { dirname } from 'node:path'\nimport type { AgentProfileMcpServer } from '@tangle-network/agent-interface'\nimport { ValidationError } from '../errors'\nimport { createStdioToolServer, type McpToolDescriptor, type StdioToolServer } from './tool-server'\n\n/** One row of agent memory: a crisp lesson/fact with provenance. */\nexport interface MemoryItem {\n  /** Stable id (content-hash by convention; see `memoryArtifactFromLessons`). */\n  id: string\n  /** The lesson itself — one imperative or observation the agent should recall. */\n  text: string\n  /** Optional retrieval tags, matched by `memory_search` alongside the text. */\n  tags?: string[]\n  /** Provenance: the finding / trace / curation pass this row came from. */\n  source?: string\n}\n\n/**\n * The `memory` artifact payload — HOW a profile's memory is stored and served:\n *\n *   - `store: 'file'` — served by the in-repo memory bin\n *     (`agent-runtime-memory-mcp`, src/mcp/memory-bin.ts): rows load from\n *     `path` (a JSON array or JSONL file of `MemoryItem`) and/or the inline\n *     `items` seed (inline wins on id collision). At least one of\n *     `path`/`items` is required.\n *   - `store: 'mcp'`  — an EXTERNAL, already-runnable MCP server that exposes\n *     the memory tools itself; `server` is required and mounts verbatim.\n *\n * `logPath` makes the served memory append one JSONL row per `memory_search`\n * — the retrieval log a holdout estimator reads (see module doc).\n */\nexport interface AgentMemorySpec {\n  store: 'file' | 'mcp'\n  /** `store:'file'` — host path to the durable row store (JSON array or JSONL). */\n  path?: string\n  /** Inline seed rows, served alongside (and winning over) `path` rows. */\n  items?: MemoryItem[]\n  /** `store:'mcp'` — the external server that already serves memory tools. */\n  server?: AgentProfileMcpServer\n  /** JSONL retrieval log: one row per `memory_search` (ts, query, k, returned). */\n  logPath?: string\n}\n\n/** Env var naming the durable row store file the memory bin loads (the\n *  `memoryMcpServer` ↔ memory-bin contract). */\nexport const MEMORY_FILE_ENV = 'AGENT_MEMORY_FILE'\n/** Env var carrying inline JSON `MemoryItem` rows (win over file rows on id). */\nexport const MEMORY_ITEMS_ENV = 'AGENT_MEMORY_ITEMS'\n/** Env var naming the JSONL retrieval log (one row per `memory_search`). */\nexport const MEMORY_LOG_ENV = 'AGENT_MEMORY_LOG'\n/** Env var overriding the served display name (default 'agent-memory'). */\nexport const MEMORY_NAME_ENV = 'AGENT_MEMORY_NAME'\n\nexport interface CreateMemoryToolServerOptions {\n  /** The rows to serve. MUST be non-empty (an empty memory is never served). */\n  items: readonly MemoryItem[]\n  /** Server display name surfaced via `initialize`. Default 'agent-memory'. */\n  serverName?: string\n  /** Server version surfaced via `initialize`. Default '0'. */\n  serverVersion?: string\n  /** Default result count for `memory_search`. Default 5. */\n  defaultK?: number\n  /** Append one JSONL row per `memory_search` (the retrieval-holdout seam). */\n  logPath?: string\n}\n\n/**\n * Build the memory MCP server: `memory_search` (lexical top-k over the rows)\n * and `memory_get` (one row by id) on the generic stdio JSON-RPC core.\n */\nexport function createMemoryToolServer(opts: CreateMemoryToolServerOptions): StdioToolServer {\n  if (opts.items.length === 0) {\n    throw new ValidationError(\n      'createMemoryToolServer: refusing to serve an EMPTY memory — a profile without memory omits the artifact; serving zero rows would fake the with/without ablation',\n    )\n  }\n  const byId = new Map<string, MemoryItem>()\n  for (const item of opts.items) {\n    if (byId.has(item.id)) {\n      throw new ValidationError(`createMemoryToolServer: duplicate memory item id '${item.id}'`)\n    }\n    byId.set(item.id, item)\n  }\n  const items = [...byId.values()]\n  const defaultK = opts.defaultK ?? 5\n  const logPath = opts.logPath\n  if (logPath) mkdirSync(dirname(logPath), { recursive: true })\n\n  const search: McpToolDescriptor = {\n    name: 'memory_search',\n    description:\n      'Search the agent memory of lessons learned from prior runs. Give what you are about to do or the problem you face; returns the top-k lessons ranked by relevance. Consult it BEFORE repeating work a prior run already learned from.',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        query: {\n          type: 'string',\n          description: 'The task/problem at hand — matched against lesson text and tags.',\n        },\n        k: { type: 'number', description: `Max results (default ${defaultK}).` },\n        tags: {\n          type: 'array',\n          items: { type: 'string' },\n          description: 'Only return items carrying at least one of these tags.',\n        },\n      },\n      required: ['query'],\n    },\n    handler: async (raw) => {\n      const args = (raw ?? {}) as { query?: unknown; k?: unknown; tags?: unknown }\n      if (typeof args.query !== 'string' || args.query.trim().length === 0) {\n        throw new TypeError('memory_search: query must be a non-empty string')\n      }\n      const k = args.k === undefined ? defaultK : Math.floor(Number(args.k))\n      if (!Number.isFinite(k) || k < 1) {\n        throw new TypeError('memory_search: k must be a positive integer')\n      }\n      let tagFilter: string[] | undefined\n      if (args.tags !== undefined) {\n        if (!Array.isArray(args.tags) || args.tags.some((t) => typeof t !== 'string')) {\n          throw new TypeError('memory_search: tags must be an array of strings')\n        }\n        tagFilter = args.tags as string[]\n      }\n      const queryTokens = tokenize(args.query)\n      const pool = tagFilter\n        ? items.filter((i) => (i.tags ?? []).some((t) => tagFilter.includes(t)))\n        : items\n      const results = pool\n        .map((item) => ({ item, score: scoreItem(queryTokens, item) }))\n        .filter((r) => r.score > 0)\n        // Highest score first; stable on ties (curation order is the tiebreak).\n        .sort((a, b) => b.score - a.score)\n        .slice(0, k)\n        .map(({ item, score }) => ({\n          id: item.id,\n          text: item.text,\n          score: Number(score.toFixed(4)),\n          ...(item.tags ? { tags: item.tags } : {}),\n          ...(item.source ? { source: item.source } : {}),\n        }))\n      if (logPath) {\n        // The retrieval log: what was asked, what came back, at what rank —\n        // exactly the per-query record an off-policy estimator needs.\n        appendFileSync(\n          logPath,\n          `${JSON.stringify({\n            ts: new Date().toISOString(),\n            query: args.query,\n            k,\n            returned: results.map((r) => ({ id: r.id, score: r.score })),\n          })}\\n`,\n        )\n      }\n      return { query: args.query, results }\n    },\n  }\n\n  const get: McpToolDescriptor = {\n    name: 'memory_get',\n    description: 'Fetch one memory item verbatim by its id (ids come from memory_search results).',\n    inputSchema: {\n      type: 'object',\n      properties: { id: { type: 'string', description: 'The memory item id.' } },\n      required: ['id'],\n    },\n    handler: async (raw) => {\n      const args = (raw ?? {}) as { id?: unknown }\n      if (typeof args.id !== 'string' || args.id.trim().length === 0) {\n        throw new TypeError('memory_get: id must be a non-empty string')\n      }\n      const item = byId.get(args.id)\n      if (!item) throw new Error(`memory_get: no memory item with id '${args.id}'`)\n      return item\n    },\n  }\n\n  return createStdioToolServer({\n    serverName: opts.serverName ?? 'agent-memory',\n    serverVersion: opts.serverVersion ?? '0',\n    tools: [search, get],\n  })\n}\n\n/** Coerce an untrusted JSON array into validated `MemoryItem` rows. */\nexport function parseMemoryItems(value: unknown, source: string): MemoryItem[] {\n  if (!Array.isArray(value)) {\n    throw new ValidationError(`${source}: expected a JSON array of memory items`)\n  }\n  return value.map((row, i) => coerceMemoryItem(row, `${source}[${i}]`))\n}\n\n/** Read a memory store file: a JSON array, or JSONL (one `MemoryItem` per line). */\nexport function readMemoryItemsFile(path: string): MemoryItem[] {\n  let raw: string\n  try {\n    raw = readFileSync(path, 'utf8')\n  } catch (err) {\n    throw new ValidationError(\n      `readMemoryItemsFile: cannot read '${path}': ${err instanceof Error ? err.message : String(err)}`,\n    )\n  }\n  const trimmed = raw.trim()\n  if (trimmed.length === 0) return []\n  if (trimmed.startsWith('[')) {\n    let parsed: unknown\n    try {\n      parsed = JSON.parse(trimmed)\n    } catch (err) {\n      throw new ValidationError(\n        `readMemoryItemsFile: '${path}' is not valid JSON: ${(err as Error).message}`,\n      )\n    }\n    return parseMemoryItems(parsed, path)\n  }\n  return trimmed\n    .split('\\n')\n    .map((line) => line.trim())\n    .filter((line) => line.length > 0)\n    .map((line, i) => {\n      let parsed: unknown\n      try {\n        parsed = JSON.parse(line)\n      } catch (err) {\n        throw new ValidationError(\n          `readMemoryItemsFile: '${path}' line ${i + 1} is not valid JSON: ${(err as Error).message}`,\n        )\n      }\n      return coerceMemoryItem(parsed, `${path}:${i + 1}`)\n    })\n}\n\n/** What the memory bin resolved from its environment. */\nexport interface ResolvedMemoryEnv {\n  items: MemoryItem[]\n  serverName?: string\n  logPath?: string\n}\n\n/**\n * Resolve the bin's memory from `AGENT_MEMORY_FILE` (durable store) and/or\n * `AGENT_MEMORY_ITEMS` (inline JSON rows; wins on id collision). Zero rows is\n * a boot FAILURE, matching the fail-closed materialization discipline.\n */\nexport function resolveMemoryFromEnv(env: Record<string, string | undefined>): ResolvedMemoryEnv {\n  const filePath = env[MEMORY_FILE_ENV]\n  const inlineRaw = env[MEMORY_ITEMS_ENV]\n  const fromFile = filePath ? readMemoryItemsFile(filePath) : []\n  let inline: MemoryItem[] = []\n  if (inlineRaw) {\n    let parsed: unknown\n    try {\n      parsed = JSON.parse(inlineRaw)\n    } catch (err) {\n      throw new ValidationError(\n        `${MEMORY_ITEMS_ENV} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`,\n      )\n    }\n    inline = parseMemoryItems(parsed, MEMORY_ITEMS_ENV)\n  }\n  const byId = new Map<string, MemoryItem>()\n  for (const item of fromFile) byId.set(item.id, item)\n  for (const item of inline) byId.set(item.id, item)\n  if (byId.size === 0) {\n    throw new ValidationError(\n      `memory bin: no memory items — set ${MEMORY_FILE_ENV} and/or ${MEMORY_ITEMS_ENV}; an EMPTY memory must never be served (a profile without memory omits the artifact)`,\n    )\n  }\n  const serverName = env[MEMORY_NAME_ENV]\n  const logPath = env[MEMORY_LOG_ENV]\n  return {\n    items: [...byId.values()],\n    ...(serverName ? { serverName } : {}),\n    ...(logPath ? { logPath } : {}),\n  }\n}\n\nfunction coerceMemoryItem(row: unknown, at: string): MemoryItem {\n  if (!row || typeof row !== 'object' || Array.isArray(row)) {\n    throw new ValidationError(`${at}: memory item must be an object`)\n  }\n  const r = row as Record<string, unknown>\n  if (typeof r.id !== 'string' || r.id.trim().length === 0) {\n    throw new ValidationError(`${at}: 'id' must be a non-empty string`)\n  }\n  if (typeof r.text !== 'string' || r.text.trim().length === 0) {\n    throw new ValidationError(`${at}: 'text' must be a non-empty string`)\n  }\n  let tags: string[] | undefined\n  if (r.tags !== undefined) {\n    if (!Array.isArray(r.tags) || r.tags.some((t) => typeof t !== 'string')) {\n      throw new ValidationError(`${at}: 'tags' must be an array of strings`)\n    }\n    tags = r.tags as string[]\n  }\n  if (r.source !== undefined && typeof r.source !== 'string') {\n    throw new ValidationError(`${at}: 'source' must be a string`)\n  }\n  return {\n    id: r.id,\n    text: r.text,\n    ...(tags ? { tags } : {}),\n    ...(typeof r.source === 'string' ? { source: r.source } : {}),\n  }\n}\n\n/** Unique lowercase alphanumeric tokens of length >= 2. */\nfunction tokenize(text: string): string[] {\n  return [\n    ...new Set(\n      text\n        .toLowerCase()\n        .split(/[^a-z0-9]+/)\n        .filter((t) => t.length >= 2),\n    ),\n  ]\n}\n\n/** Fraction of query tokens present in the item's text + tags (0..1). */\nfunction scoreItem(queryTokens: readonly string[], item: MemoryItem): number {\n  if (queryTokens.length === 0) return 0\n  const hay = new Set(tokenize(`${item.text} ${(item.tags ?? []).join(' ')}`))\n  let hit = 0\n  for (const t of queryTokens) if (hay.has(t)) hit += 1\n  return hit / queryTokens.length\n}\n"],"mappings":"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"}

package/dist/model-resolution-Btd9iIKV.js

@@ -0,0 +1,98 @@
+//#region src/model-resolution.ts
+/** Default Tangle Router base URL used when no env override is set. */
+const DEFAULT_ROUTER_BASE_URL = "https://router.tangle.tools";
+/** Resolve the router base URL from env, normalised — no trailing `/v1` or `/`. */
+function resolveRouterBaseUrl(env = {}) {
+	return (env.TANGLE_ROUTER_URL ?? env.TANGLE_ROUTER_BASE_URL ?? "https://router.tangle.tools").replace(/\/v1\/?$/, "").replace(/\/$/, "");
+}
+/**
+* Fetch the model catalog from the router's `/v1/models`. Throws on a non-2xx
+* response — callers decide whether to fail open (empty catalog) or closed.
+*/
+async function getModels(routerBaseUrl = DEFAULT_ROUTER_BASE_URL) {
+	const res = await fetch(`${routerBaseUrl}/v1/models`, { headers: { Accept: "application/json" } });
+	if (!res.ok) throw new Error(`router /v1/models ${res.status}`);
+	const body = await res.json();
+	return Array.isArray(body.data) ? body.data : [];
+}
+/** Trim a candidate model id; `undefined` for non-strings and blanks. */
+function cleanModelId(value) {
+	if (typeof value !== "string") return void 0;
+	const trimmed = value.trim();
+	return trimmed.length > 0 ? trimmed : void 0;
+}
+/**
+* Resolve a chat model by precedence: the first candidate carrying a
+* non-blank model wins, else `fallback`. The caller owns the precedence
+* order, so each product keeps its own policy (request → workspace → env,
+* etc.) while the first-non-blank logic and the telemetry shape stay shared.
+*/
+function resolveChatModel(candidates, fallback) {
+	for (const candidate of candidates) {
+		const model = cleanModelId(candidate.model);
+		if (model) return {
+			source: candidate.source,
+			model
+		};
+	}
+	return fallback;
+}
+const WELL_FORMED_MODEL_ID = /^[A-Za-z0-9._/@:-]+$/;
+function isWellFormedModelId(modelId) {
+	return modelId.length <= 200 && WELL_FORMED_MODEL_ID.test(modelId);
+}
+/**
+* Every id a catalog entry can be addressed by — its bare id, plus a
+* `provider/id` form when the router exposes a separate provider slug.
+*/
+function catalogIdsForModel(model) {
+	const ids = /* @__PURE__ */ new Set();
+	const id = cleanModelId(model.id);
+	if (id) ids.add(id);
+	const provider = cleanModelId(model._provider) ?? cleanModelId(model.provider);
+	if (provider && id && !id.includes("/")) ids.add(`${provider}/${id}`);
+	return [...ids];
+}
+/**
+* Validate a caller-supplied chat-model id. Rejects non-strings, malformed
+* ids, and ids absent from both the caller's `allowlist` and the live router
+* catalog. Fails closed: when the catalog cannot be fetched, an unverifiable
+* id is rejected rather than admitted — a bad model never reaches the agent.
+*/
+async function validateChatModelId(modelId, options = {}) {
+	const { allowlist = [], routerBaseUrl = DEFAULT_ROUTER_BASE_URL, loadModels = getModels } = options;
+	const cleaned = cleanModelId(modelId);
+	if (!cleaned) return {
+		succeeded: false,
+		error: "Model id must be a non-empty string."
+	};
+	if (!isWellFormedModelId(cleaned)) return {
+		succeeded: false,
+		error: `Model id is malformed: ${cleaned}`
+	};
+	if (allowlist.some((id) => cleanModelId(id) === cleaned)) return {
+		succeeded: true,
+		value: cleaned
+	};
+	let catalog;
+	try {
+		catalog = await loadModels(routerBaseUrl);
+	} catch (err) {
+		return {
+			succeeded: false,
+			error: `Could not validate model catalog: ${err instanceof Error ? err.message : String(err)}`
+		};
+	}
+	if (!new Set(catalog.flatMap(catalogIdsForModel)).has(cleaned)) return {
+		succeeded: false,
+		error: `Model is not available: ${cleaned}`
+	};
+	return {
+		succeeded: true,
+		value: cleaned
+	};
+}
+//#endregion
+export { resolveRouterBaseUrl as a, resolveChatModel as i, cleanModelId as n, validateChatModelId as o, getModels as r, DEFAULT_ROUTER_BASE_URL as t };
+
+//# sourceMappingURL=model-resolution-Btd9iIKV.js.map

package/dist/model-resolution-Btd9iIKV.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-resolution-Btd9iIKV.js","names":[],"sources":["../src/model-resolution.ts"],"sourcesContent":["/**\n *\n * Chat-model resolution + catalog validation — the shared primitive every\n * product chat handler needs and was, until now, hand-rolling. Lifts the\n * router `/v1/models` fetch, the fail-closed id validation, and the\n * precedence resolver out of four near-identical per-repo copies.\n *\n * Policy-free by design: callers pass their own precedence order\n * (`resolveChatModel`) and their own known-good `allowlist`\n * (`validateChatModelId`), so each product keeps its resolution policy while\n * sharing the catalog fetch, the malformed-id guard, and the fail-closed\n * admission rule. No React, no `process.env` assumption — `env` is an\n * explicit narrow record so this runs unchanged in Node and in Workers.\n *\n * @stable\n */\n\n/**\n * A model entry as returned by the Tangle Router `/v1/models` endpoint.\n * Intentionally minimal — only the fields resolution + validation read.\n */\nexport interface ModelInfo {\n  id: string\n  name?: string\n  description?: string\n  /** Provider slug, when the router exposes it (`provider` or `_provider`). */\n  provider?: string\n  _provider?: string\n  architecture?: {\n    modality?: string\n    input_modalities?: string[]\n    output_modalities?: string[]\n  }\n}\n\n/** Env keys the router base URL is resolved from. */\nexport interface RouterEnv {\n  TANGLE_ROUTER_URL?: string\n  TANGLE_ROUTER_BASE_URL?: string\n}\n\n/** Default Tangle Router base URL used when no env override is set. */\nexport const DEFAULT_ROUTER_BASE_URL = 'https://router.tangle.tools'\n\n/** Resolve the router base URL from env, normalised — no trailing `/v1` or `/`. */\nexport function resolveRouterBaseUrl(env: RouterEnv = {}): string {\n  return (env.TANGLE_ROUTER_URL ?? env.TANGLE_ROUTER_BASE_URL ?? DEFAULT_ROUTER_BASE_URL)\n    .replace(/\\/v1\\/?$/, '')\n    .replace(/\\/$/, '')\n}\n\n/**\n * Fetch the model catalog from the router's `/v1/models`. Throws on a non-2xx\n * response — callers decide whether to fail open (empty catalog) or closed.\n */\nexport async function getModels(\n  routerBaseUrl: string = DEFAULT_ROUTER_BASE_URL,\n): Promise<ModelInfo[]> {\n  const res = await fetch(`${routerBaseUrl}/v1/models`, {\n    headers: { Accept: 'application/json' },\n  })\n  if (!res.ok) throw new Error(`router /v1/models ${res.status}`)\n  const body = (await res.json()) as { data?: ModelInfo[] }\n  return Array.isArray(body.data) ? body.data : []\n}\n\n/** Trim a candidate model id; `undefined` for non-strings and blanks. */\nexport function cleanModelId(value: unknown): string | undefined {\n  if (typeof value !== 'string') return undefined\n  const trimmed = value.trim()\n  return trimmed.length > 0 ? trimmed : undefined\n}\n\nexport interface ChatModelCandidate {\n  /** Stable label for telemetry — e.g. `request`, `workspace`, `env`. */\n  source: string\n  model: string | undefined\n}\n\nexport interface ResolvedChatModel {\n  source: string\n  model: string\n}\n\n/**\n * Resolve a chat model by precedence: the first candidate carrying a\n * non-blank model wins, else `fallback`. The caller owns the precedence\n * order, so each product keeps its own policy (request → workspace → env,\n * etc.) while the first-non-blank logic and the telemetry shape stay shared.\n */\nexport function resolveChatModel(\n  candidates: ChatModelCandidate[],\n  fallback: ResolvedChatModel,\n): ResolvedChatModel {\n  for (const candidate of candidates) {\n    const model = cleanModelId(candidate.model)\n    if (model) return { source: candidate.source, model }\n  }\n  return fallback\n}\n\nexport type ChatModelValidation =\n  | { succeeded: true; value: string }\n  | { succeeded: false; error: string }\n\nconst WELL_FORMED_MODEL_ID = /^[A-Za-z0-9._/@:-]+$/\n\nfunction isWellFormedModelId(modelId: string): boolean {\n  return modelId.length <= 200 && WELL_FORMED_MODEL_ID.test(modelId)\n}\n\n/**\n * Every id a catalog entry can be addressed by — its bare id, plus a\n * `provider/id` form when the router exposes a separate provider slug.\n */\nfunction catalogIdsForModel(model: ModelInfo): string[] {\n  const ids = new Set<string>()\n  const id = cleanModelId(model.id)\n  if (id) ids.add(id)\n  const provider = cleanModelId(model._provider) ?? cleanModelId(model.provider)\n  if (provider && id && !id.includes('/')) ids.add(`${provider}/${id}`)\n  return [...ids]\n}\n\n/**\n * Validate a caller-supplied chat-model id. Rejects non-strings, malformed\n * ids, and ids absent from both the caller's `allowlist` and the live router\n * catalog. Fails closed: when the catalog cannot be fetched, an unverifiable\n * id is rejected rather than admitted — a bad model never reaches the agent.\n */\nexport async function validateChatModelId(\n  modelId: unknown,\n  options: {\n    /**\n     * Known-good ids that skip the catalog round trip — e.g. the product's\n     * default model plus any env-configured ids.\n     */\n    allowlist?: string[]\n    routerBaseUrl?: string\n    /** Injectable catalog loader — overridden in tests. */\n    loadModels?: (routerBaseUrl: string) => Promise<ModelInfo[]>\n  } = {},\n): Promise<ChatModelValidation> {\n  const {\n    allowlist = [],\n    routerBaseUrl = DEFAULT_ROUTER_BASE_URL,\n    loadModels = getModels,\n  } = options\n\n  const cleaned = cleanModelId(modelId)\n  if (!cleaned) return { succeeded: false, error: 'Model id must be a non-empty string.' }\n  if (!isWellFormedModelId(cleaned)) {\n    return { succeeded: false, error: `Model id is malformed: ${cleaned}` }\n  }\n  if (allowlist.some((id) => cleanModelId(id) === cleaned)) {\n    return { succeeded: true, value: cleaned }\n  }\n\n  let catalog: ModelInfo[]\n  try {\n    catalog = await loadModels(routerBaseUrl)\n  } catch (err) {\n    const message = err instanceof Error ? err.message : String(err)\n    return { succeeded: false, error: `Could not validate model catalog: ${message}` }\n  }\n\n  const ids = new Set(catalog.flatMap(catalogIdsForModel))\n  if (!ids.has(cleaned)) return { succeeded: false, error: `Model is not available: ${cleaned}` }\n  return { succeeded: true, value: cleaned }\n}\n"],"mappings":";;AA0CA,MAAa,0BAA0B;;AAGvC,SAAgB,qBAAqB,MAAiB,CAAC,GAAW;CAChE,QAAQ,IAAI,qBAAqB,IAAI,0BAAA,8BAAA,CAClC,QAAQ,YAAY,EAAE,CAAC,CACvB,QAAQ,OAAO,EAAE;AACtB;;;;;AAMA,eAAsB,UACpB,gBAAwB,yBACF;CACtB,MAAM,MAAM,MAAM,MAAM,GAAG,cAAc,aAAa,EACpD,SAAS,EAAE,QAAQ,mBAAmB,EACxC,CAAC;CACD,IAAI,CAAC,IAAI,IAAI,MAAM,IAAI,MAAM,qBAAqB,IAAI,QAAQ;CAC9D,MAAM,OAAQ,MAAM,IAAI,KAAK;CAC7B,OAAO,MAAM,QAAQ,KAAK,IAAI,IAAI,KAAK,OAAO,CAAC;AACjD;;AAGA,SAAgB,aAAa,OAAoC;CAC/D,IAAI,OAAO,UAAU,UAAU,OAAO,KAAA;CACtC,MAAM,UAAU,MAAM,KAAK;CAC3B,OAAO,QAAQ,SAAS,IAAI,UAAU,KAAA;AACxC;;;;;;;AAmBA,SAAgB,iBACd,YACA,UACmB;CACnB,KAAK,MAAM,aAAa,YAAY;EAClC,MAAM,QAAQ,aAAa,UAAU,KAAK;EAC1C,IAAI,OAAO,OAAO;GAAE,QAAQ,UAAU;GAAQ;EAAM;CACtD;CACA,OAAO;AACT;AAMA,MAAM,uBAAuB;AAE7B,SAAS,oBAAoB,SAA0B;CACrD,OAAO,QAAQ,UAAU,OAAO,qBAAqB,KAAK,OAAO;AACnE;;;;;AAMA,SAAS,mBAAmB,OAA4B;CACtD,MAAM,sBAAM,IAAI,IAAY;CAC5B,MAAM,KAAK,aAAa,MAAM,EAAE;CAChC,IAAI,IAAI,IAAI,IAAI,EAAE;CAClB,MAAM,WAAW,aAAa,MAAM,SAAS,KAAK,aAAa,MAAM,QAAQ;CAC7E,IAAI,YAAY,MAAM,CAAC,GAAG,SAAS,GAAG,GAAG,IAAI,IAAI,GAAG,SAAS,GAAG,IAAI;CACpE,OAAO,CAAC,GAAG,GAAG;AAChB;;;;;;;AAQA,eAAsB,oBACpB,SACA,UASI,CAAC,GACyB;CAC9B,MAAM,EACJ,YAAY,CAAC,GACb,gBAAgB,yBAChB,aAAa,cACX;CAEJ,MAAM,UAAU,aAAa,OAAO;CACpC,IAAI,CAAC,SAAS,OAAO;EAAE,WAAW;EAAO,OAAO;CAAuC;CACvF,IAAI,CAAC,oBAAoB,OAAO,GAC9B,OAAO;EAAE,WAAW;EAAO,OAAO,0BAA0B;CAAU;CAExE,IAAI,UAAU,MAAM,OAAO,aAAa,EAAE,MAAM,OAAO,GACrD,OAAO;EAAE,WAAW;EAAM,OAAO;CAAQ;CAG3C,IAAI;CACJ,IAAI;EACF,UAAU,MAAM,WAAW,aAAa;CAC1C,SAAS,KAAK;EAEZ,OAAO;GAAE,WAAW;GAAO,OAAO,qCADlB,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;EACkB;CACnF;CAGA,IAAI,CAAC,IADW,IAAI,QAAQ,QAAQ,kBAAkB,CAC/C,CAAC,CAAC,IAAI,OAAO,GAAG,OAAO;EAAE,WAAW;EAAO,OAAO,2BAA2B;CAAU;CAC9F,OAAO;EAAE,WAAW;EAAM,OAAO;CAAQ;AAC3C"}

package/dist/openai-tools-B68JaOCx.d.ts

@@ -0,0 +1,24 @@
+import { h as OpenAIChatTool } from "./types-C9j4qg6l.js";
+//#region src/mcp/openai-tools.d.ts
+/**
+ *
+ * Returns the queue-bound delegation tools projected into OpenAI Chat
+ * Completions `tools[]` shape. The order is stable: `delegate_feedback`,
+ * `delegation_status`, `delegation_history`.
+ *
+ * @experimental
+ */
+declare function mcpToolsForRuntimeMcp(): OpenAIChatTool[];
+/**
+ *
+ * Subset filter — return only the projected tools whose `function.name`
+ * appears in `names`. Useful for curated mounts (e.g. only the queue-bound
+ * delegation tools, omitting `delegate_feedback`). Unknown names are
+ * silently ignored; pass an empty array to get an empty result.
+ *
+ * @experimental
+ */
+declare function mcpToolsForRuntimeMcpSubset(names: ReadonlyArray<string>): OpenAIChatTool[];
+//#endregion
+export { mcpToolsForRuntimeMcpSubset as n, mcpToolsForRuntimeMcp as t };
+//# sourceMappingURL=openai-tools-B68JaOCx.d.ts.map

package/dist/openai-tools-CKLy1C7M.js

@@ -0,0 +1,44 @@
+import { C as DELEGATE_FEEDBACK_INPUT_SCHEMA, S as DELEGATE_FEEDBACK_DESCRIPTION, c as DELEGATION_STATUS_INPUT_SCHEMA, f as DELEGATION_HISTORY_DESCRIPTION, l as DELEGATION_STATUS_TOOL_NAME, m as DELEGATION_HISTORY_TOOL_NAME, p as DELEGATION_HISTORY_INPUT_SCHEMA, s as DELEGATION_STATUS_DESCRIPTION, w as DELEGATE_FEEDBACK_TOOL_NAME } from "./supervise-BiRutHS9.js";
+//#region src/mcp/openai-tools.ts
+function buildTool(name, description, parameters) {
+	return {
+		type: "function",
+		function: {
+			name,
+			description,
+			parameters: { ...parameters }
+		}
+	};
+}
+/**
+*
+* Returns the queue-bound delegation tools projected into OpenAI Chat
+* Completions `tools[]` shape. The order is stable: `delegate_feedback`,
+* `delegation_status`, `delegation_history`.
+*
+* @experimental
+*/
+function mcpToolsForRuntimeMcp() {
+	return [
+		buildTool(DELEGATE_FEEDBACK_TOOL_NAME, DELEGATE_FEEDBACK_DESCRIPTION, DELEGATE_FEEDBACK_INPUT_SCHEMA),
+		buildTool(DELEGATION_STATUS_TOOL_NAME, DELEGATION_STATUS_DESCRIPTION, DELEGATION_STATUS_INPUT_SCHEMA),
+		buildTool(DELEGATION_HISTORY_TOOL_NAME, DELEGATION_HISTORY_DESCRIPTION, DELEGATION_HISTORY_INPUT_SCHEMA)
+	];
+}
+/**
+*
+* Subset filter — return only the projected tools whose `function.name`
+* appears in `names`. Useful for curated mounts (e.g. only the queue-bound
+* delegation tools, omitting `delegate_feedback`). Unknown names are
+* silently ignored; pass an empty array to get an empty result.
+*
+* @experimental
+*/
+function mcpToolsForRuntimeMcpSubset(names) {
+	const allowed = new Set(names);
+	return mcpToolsForRuntimeMcp().filter((tool) => allowed.has(tool.function.name));
+}
+//#endregion
+export { mcpToolsForRuntimeMcpSubset as n, mcpToolsForRuntimeMcp as t };
+
+//# sourceMappingURL=openai-tools-CKLy1C7M.js.map

package/dist/openai-tools-CKLy1C7M.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai-tools-CKLy1C7M.js","names":[],"sources":["../src/mcp/openai-tools.ts"],"sourcesContent":["/**\n *\n * OpenAI Chat Completions `tools[]` projection of the queue-bound agent-runtime\n * MCP delegation tools.\n *\n * Use when configuring `createOpenAICompatibleBackend({ tools: ... })` so the\n * model can call `delegate_feedback`, `delegation_status`, and\n * `delegation_history` through the OpenAI-compat transport (tcloud, OpenRouter,\n * OpenAI direct, cli-bridge). The runtime surfaces tool calls as `tool_call`\n * stream events — execution is the caller's responsibility (typically the\n * parent sandbox runtime's MCP mount).\n *\n * Sandbox-SDK callers do NOT need this helper: the sandbox runtime mounts\n * MCP servers natively and the in-sandbox harness discovers tools via the\n * runtime, not via an OpenAI tools array.\n *\n * Tool name + description + JSON-schema are pulled from the canonical\n * `DELEGATE_*` constants exported by `./tools/*` so the projection cannot\n * drift from the server's own validators.\n *\n * @experimental\n */\n\nimport type { OpenAIChatTool } from '../types'\nimport {\n  DELEGATE_FEEDBACK_DESCRIPTION,\n  DELEGATE_FEEDBACK_INPUT_SCHEMA,\n  DELEGATE_FEEDBACK_TOOL_NAME,\n} from './tools/delegate-feedback'\nimport {\n  DELEGATION_HISTORY_DESCRIPTION,\n  DELEGATION_HISTORY_INPUT_SCHEMA,\n  DELEGATION_HISTORY_TOOL_NAME,\n} from './tools/delegation-history'\nimport {\n  DELEGATION_STATUS_DESCRIPTION,\n  DELEGATION_STATUS_INPUT_SCHEMA,\n  DELEGATION_STATUS_TOOL_NAME,\n} from './tools/delegation-status'\n\nfunction buildTool(\n  name: string,\n  description: string,\n  parameters: Readonly<Record<string, unknown>>,\n): OpenAIChatTool {\n  // `parameters` arrives as a deeply-readonly `as const` literal. The\n  // OpenAI-compat backend JSON-serializes the body so a shallow copy\n  // into a plain object is sufficient — and shields callers that mutate\n  // the returned descriptor from corrupting the source constant.\n  return {\n    type: 'function',\n    function: { name, description, parameters: { ...parameters } },\n  }\n}\n\n/**\n *\n * Returns the queue-bound delegation tools projected into OpenAI Chat\n * Completions `tools[]` shape. The order is stable: `delegate_feedback`,\n * `delegation_status`, `delegation_history`.\n *\n * @experimental\n */\nexport function mcpToolsForRuntimeMcp(): OpenAIChatTool[] {\n  return [\n    buildTool(\n      DELEGATE_FEEDBACK_TOOL_NAME,\n      DELEGATE_FEEDBACK_DESCRIPTION,\n      DELEGATE_FEEDBACK_INPUT_SCHEMA as Readonly<Record<string, unknown>>,\n    ),\n    buildTool(\n      DELEGATION_STATUS_TOOL_NAME,\n      DELEGATION_STATUS_DESCRIPTION,\n      DELEGATION_STATUS_INPUT_SCHEMA as Readonly<Record<string, unknown>>,\n    ),\n    buildTool(\n      DELEGATION_HISTORY_TOOL_NAME,\n      DELEGATION_HISTORY_DESCRIPTION,\n      DELEGATION_HISTORY_INPUT_SCHEMA as Readonly<Record<string, unknown>>,\n    ),\n  ]\n}\n\n/**\n *\n * Subset filter — return only the projected tools whose `function.name`\n * appears in `names`. Useful for curated mounts (e.g. only the queue-bound\n * delegation tools, omitting `delegate_feedback`). Unknown names are\n * silently ignored; pass an empty array to get an empty result.\n *\n * @experimental\n */\nexport function mcpToolsForRuntimeMcpSubset(names: ReadonlyArray<string>): OpenAIChatTool[] {\n  const allowed = new Set(names)\n  return mcpToolsForRuntimeMcp().filter((tool) => allowed.has(tool.function.name))\n}\n"],"mappings":";;AAwCA,SAAS,UACP,MACA,aACA,YACgB;CAKhB,OAAO;EACL,MAAM;EACN,UAAU;GAAE;GAAM;GAAa,YAAY,EAAE,GAAG,WAAW;EAAE;CAC/D;AACF;;;;;;;;;AAUA,SAAgB,wBAA0C;CACxD,OAAO;EACL,UACE,6BACA,+BACA,8BACF;EACA,UACE,6BACA,+BACA,8BACF;EACA,UACE,8BACA,gCACA,+BACF;CACF;AACF;;;;;;;;;;AAWA,SAAgB,4BAA4B,OAAgD;CAC1F,MAAM,UAAU,IAAI,IAAI,KAAK;CAC7B,OAAO,sBAAsB,CAAC,CAAC,QAAQ,SAAS,QAAQ,IAAI,KAAK,SAAS,IAAI,CAAC;AACjF"}