@warlock.js/ai 4.3.0 → 4.5.0

package/esm/security/redact.mjs

@@ -0,0 +1,122 @@
+//#region ../@warlock.js/ai/src/security/redact.ts
+/**
+* Default set of sensitive key fragments (matched case-insensitively as
+* substrings of an object key). Covers the secrets that leak through
+* recorded requests, error causes, and trace payloads: auth headers, API
+* keys, cookies, tokens, passwords, and private keys.
+*/
+const DEFAULT_SENSITIVE_KEYS = [
+	"authorization",
+	"x-api-key",
+	"api-key",
+	"apikey",
+	"cookie",
+	"set-cookie",
+	"password",
+	"passwd",
+	"secret",
+	"token",
+	"access_token",
+	"refresh_token",
+	"client_secret",
+	"private_key",
+	"session"
+];
+/** HTTP header names always stripped from a serialized error/cause. */
+const SENSITIVE_HEADERS = [
+	"authorization",
+	"x-api-key",
+	"api-key",
+	"cookie",
+	"set-cookie",
+	"proxy-authorization"
+];
+const DEFAULT_PLACEHOLDER = "[redacted]";
+const DEFAULT_MAX_DEPTH = 8;
+function keyIsSensitive(key, fragments) {
+	const lower = key.toLowerCase();
+	return fragments.some((fragment) => lower.includes(fragment));
+}
+/**
+* Deep-copy `value` with any property whose KEY matches a sensitive
+* fragment replaced by the placeholder. Arrays are walked element-wise;
+* circular references and over-deep trees collapse to the placeholder.
+* Primitives pass through untouched (redaction is key-driven, not
+* value-driven — it never guesses at a bare string being a secret).
+*
+* Shared by VCR cassettes (S2), Panoptic content capture, and the error /
+* cause serializer (S4) so there is ONE redaction policy, not three.
+*/
+function redact(value, options = {}) {
+	const fragments = [...DEFAULT_SENSITIVE_KEYS, ...options.keys ?? []].map((k) => k.toLowerCase());
+	const placeholder = options.placeholder ?? DEFAULT_PLACEHOLDER;
+	const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+	const seen = /* @__PURE__ */ new WeakSet();
+	const walk = (input, depth) => {
+		if (input === null || typeof input !== "object") return input;
+		if (depth >= maxDepth || seen.has(input)) return placeholder;
+		seen.add(input);
+		if (Array.isArray(input)) return input.map((item) => walk(item, depth + 1));
+		const out = {};
+		for (const [key, val] of Object.entries(input)) out[key] = keyIsSensitive(key, fragments) ? placeholder : walk(val, depth + 1);
+		return out;
+	};
+	return walk(value, 0);
+}
+/**
+* Strip sensitive HTTP headers from a `Headers` instance or a plain
+* header record, returning a redacted plain object. Header names are
+* matched case-insensitively against {@link SENSITIVE_HEADERS}.
+*/
+function redactHeaders(headers, placeholder = DEFAULT_PLACEHOLDER) {
+	if (!headers) return {};
+	const entries = headers instanceof Headers ? [...headers.entries()] : Object.entries(headers);
+	const out = {};
+	for (const [key, val] of entries) out[key] = SENSITIVE_HEADERS.includes(key.toLowerCase()) ? placeholder : val;
+	return out;
+}
+/**
+* Patterns for secrets that hide in FREE TEXT (error messages, stack
+* traces, log lines) where the key-based {@link redact} can't reach them.
+* Each entry replaces the secret with `[redacted]` while keeping
+* surrounding context.
+*/
+const SECRET_PATTERNS = [
+	[/\bBearer\s+[A-Za-z0-9._~+/-]+=*/gi, "Bearer [redacted]"],
+	[/\b(authorization|x-api-key|api[_-]?key|cookie)("?\s*[:=]\s*"?)[^\s",}]+/gi, "$1$2[redacted]"],
+	[/\bsk-[A-Za-z0-9]{16,}\b/g, "[redacted]"],
+	[/\bxox[baprs]-[A-Za-z0-9-]{8,}\b/g, "[redacted]"],
+	[/\bgh[pousr]_[A-Za-z0-9]{20,}\b/g, "[redacted]"],
+	[/\bAKIA[0-9A-Z]{16}\b/g, "[redacted]"]
+];
+/**
+* Scrub secrets that appear in free-form text — error messages, stack
+* traces, exported log lines. Complements {@link redact} (which is key-
+* driven and can't see a token embedded in a string). Used by the trace /
+* error serializer (S4) before a message or stack is stored or exported.
+*/
+function scrubSecrets(text) {
+	let out = text;
+	for (const [pattern, replacement] of SECRET_PATTERNS) out = out.replace(pattern, replacement);
+	return out;
+}
+function redactError(error, options = {}) {
+	const { includeStack, ...redactOptions } = options;
+	if (error === null || typeof error !== "object") return {
+		name: "Error",
+		message: String(error)
+	};
+	const err = error;
+	const result = {
+		name: typeof err.name === "string" ? err.name : "Error",
+		message: typeof err.message === "string" ? err.message : String(error)
+	};
+	if (typeof err.code === "string") result.code = err.code;
+	if (err.cause !== void 0) result.cause = err.cause !== null && typeof err.cause === "object" ? redact(err.cause, redactOptions) : err.cause;
+	if (includeStack && typeof err.stack === "string") result.stack = err.stack;
+	return result;
+}
+
+//#endregion
+export { DEFAULT_SENSITIVE_KEYS, SENSITIVE_HEADERS, redact, redactError, redactHeaders, scrubSecrets };
+//# sourceMappingURL=redact.mjs.map

package/esm/security/redact.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/security/redact.ts"],"sourcesContent":["/**\n * Default set of sensitive key fragments (matched case-insensitively as\n * substrings of an object key). Covers the secrets that leak through\n * recorded requests, error causes, and trace payloads: auth headers, API\n * keys, cookies, tokens, passwords, and private keys.\n */\nexport const DEFAULT_SENSITIVE_KEYS: readonly string[] = [\n  \"authorization\",\n  \"x-api-key\",\n  \"api-key\",\n  \"apikey\",\n  \"cookie\",\n  \"set-cookie\",\n  \"password\",\n  \"passwd\",\n  \"secret\",\n  \"token\",\n  \"access_token\",\n  \"refresh_token\",\n  \"client_secret\",\n  \"private_key\",\n  \"session\",\n];\n\n/** HTTP header names always stripped from a serialized error/cause. */\nexport const SENSITIVE_HEADERS: readonly string[] = [\n  \"authorization\",\n  \"x-api-key\",\n  \"api-key\",\n  \"cookie\",\n  \"set-cookie\",\n  \"proxy-authorization\",\n];\n\nexport type RedactOptions = {\n  /** Extra key fragments to redact, merged with {@link DEFAULT_SENSITIVE_KEYS}. */\n  keys?: string[];\n  /** Replacement for a redacted value. Default `\"[redacted]\"`. */\n  placeholder?: string;\n  /** Maximum recursion depth before bailing out. Default `8`. */\n  maxDepth?: number;\n};\n\nconst DEFAULT_PLACEHOLDER = \"[redacted]\";\nconst DEFAULT_MAX_DEPTH = 8;\n\nfunction keyIsSensitive(key: string, fragments: string[]): boolean {\n  const lower = key.toLowerCase();\n  return fragments.some(fragment => lower.includes(fragment));\n}\n\n/**\n * Deep-copy `value` with any property whose KEY matches a sensitive\n * fragment replaced by the placeholder. Arrays are walked element-wise;\n * circular references and over-deep trees collapse to the placeholder.\n * Primitives pass through untouched (redaction is key-driven, not\n * value-driven — it never guesses at a bare string being a secret).\n *\n * Shared by VCR cassettes (S2), Panoptic content capture, and the error /\n * cause serializer (S4) so there is ONE redaction policy, not three.\n */\nexport function redact<T>(value: T, options: RedactOptions = {}): T {\n  const fragments = [...DEFAULT_SENSITIVE_KEYS, ...(options.keys ?? [])].map(k =>\n    k.toLowerCase(),\n  );\n  const placeholder = options.placeholder ?? DEFAULT_PLACEHOLDER;\n  const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;\n  const seen = new WeakSet<object>();\n\n  const walk = (input: unknown, depth: number): unknown => {\n    if (input === null || typeof input !== \"object\") {\n      return input;\n    }\n    if (depth >= maxDepth || seen.has(input)) {\n      return placeholder;\n    }\n    seen.add(input as object);\n\n    if (Array.isArray(input)) {\n      return input.map(item => walk(item, depth + 1));\n    }\n\n    const out: Record<string, unknown> = {};\n    for (const [key, val] of Object.entries(input as Record<string, unknown>)) {\n      out[key] = keyIsSensitive(key, fragments)\n        ? placeholder\n        : walk(val, depth + 1);\n    }\n    return out;\n  };\n\n  return walk(value, 0) as T;\n}\n\n/**\n * Strip sensitive HTTP headers from a `Headers` instance or a plain\n * header record, returning a redacted plain object. Header names are\n * matched case-insensitively against {@link SENSITIVE_HEADERS}.\n */\nexport function redactHeaders(\n  headers: Headers | Record<string, unknown> | undefined,\n  placeholder: string = DEFAULT_PLACEHOLDER,\n): Record<string, unknown> {\n  if (!headers) return {};\n\n  const entries: Array<[string, unknown]> =\n    headers instanceof Headers\n      ? [...headers.entries()]\n      : Object.entries(headers);\n\n  const out: Record<string, unknown> = {};\n  for (const [key, val] of entries) {\n    out[key] = SENSITIVE_HEADERS.includes(key.toLowerCase()) ? placeholder : val;\n  }\n  return out;\n}\n\n/**\n * Patterns for secrets that hide in FREE TEXT (error messages, stack\n * traces, log lines) where the key-based {@link redact} can't reach them.\n * Each entry replaces the secret with `[redacted]` while keeping\n * surrounding context.\n */\nconst SECRET_PATTERNS: ReadonlyArray<readonly [RegExp, string]> = [\n  [/\\bBearer\\s+[A-Za-z0-9._~+/-]+=*/gi, \"Bearer [redacted]\"],\n  [/\\b(authorization|x-api-key|api[_-]?key|cookie)(\"?\\s*[:=]\\s*\"?)[^\\s\",}]+/gi, \"$1$2[redacted]\"],\n  [/\\bsk-[A-Za-z0-9]{16,}\\b/g, \"[redacted]\"], // OpenAI-style keys\n  [/\\bxox[baprs]-[A-Za-z0-9-]{8,}\\b/g, \"[redacted]\"], // Slack tokens\n  [/\\bgh[pousr]_[A-Za-z0-9]{20,}\\b/g, \"[redacted]\"], // GitHub tokens\n  [/\\bAKIA[0-9A-Z]{16}\\b/g, \"[redacted]\"], // AWS access key ids\n];\n\n/**\n * Scrub secrets that appear in free-form text — error messages, stack\n * traces, exported log lines. Complements {@link redact} (which is key-\n * driven and can't see a token embedded in a string). Used by the trace /\n * error serializer (S4) before a message or stack is stored or exported.\n */\nexport function scrubSecrets(text: string): string {\n  let out = text;\n  for (const [pattern, replacement] of SECRET_PATTERNS) {\n    out = out.replace(pattern, replacement);\n  }\n  return out;\n}\n\n/**\n * Serialized, secret-free view of an error. `stack` is omitted by default\n * (it can embed local paths, endpoints, and tokens); pass\n * `includeStack: true` only for a trusted local sink. The retained\n * `cause` is deep-redacted via {@link redact}, so a raw provider SDK error\n * carrying `Authorization` / `x-api-key` on `cause.headers` is sanitized.\n */\nexport type RedactedError = {\n  name: string;\n  message: string;\n  code?: string;\n  cause?: unknown;\n  stack?: string;\n};\n\nexport function redactError(\n  error: unknown,\n  options: { includeStack?: boolean } & RedactOptions = {},\n): RedactedError {\n  const { includeStack, ...redactOptions } = options;\n\n  if (error === null || typeof error !== \"object\") {\n    return { name: \"Error\", message: String(error) };\n  }\n\n  const err = error as {\n    name?: unknown;\n    message?: unknown;\n    code?: unknown;\n    cause?: unknown;\n    stack?: unknown;\n  };\n\n  const result: RedactedError = {\n    name: typeof err.name === \"string\" ? err.name : \"Error\",\n    message: typeof err.message === \"string\" ? err.message : String(error),\n  };\n\n  if (typeof err.code === \"string\") {\n    result.code = err.code;\n  }\n  if (err.cause !== undefined) {\n    result.cause =\n      err.cause !== null && typeof err.cause === \"object\"\n        ? redact(err.cause, redactOptions)\n        : err.cause;\n  }\n  if (includeStack && typeof err.stack === \"string\") {\n    result.stack = err.stack;\n  }\n\n  return result;\n}\n"],"mappings":";;;;;;;AAMA,MAAa,yBAA4C;CACvD;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF;;AAGA,MAAa,oBAAuC;CAClD;CACA;CACA;CACA;CACA;CACA;AACF;AAWA,MAAM,sBAAsB;AAC5B,MAAM,oBAAoB;AAE1B,SAAS,eAAe,KAAa,WAA8B;CACjE,MAAM,QAAQ,IAAI,YAAY;CAC9B,OAAO,UAAU,MAAK,aAAY,MAAM,SAAS,QAAQ,CAAC;AAC5D;;;;;;;;;;;AAYA,SAAgB,OAAU,OAAU,UAAyB,CAAC,GAAM;CAClE,MAAM,YAAY,CAAC,GAAG,wBAAwB,GAAI,QAAQ,QAAQ,CAAC,CAAE,CAAC,CAAC,KAAI,MACzE,EAAE,YAAY,CAChB;CACA,MAAM,cAAc,QAAQ,eAAe;CAC3C,MAAM,WAAW,QAAQ,YAAY;CACrC,MAAM,uBAAO,IAAI,QAAgB;CAEjC,MAAM,QAAQ,OAAgB,UAA2B;EACvD,IAAI,UAAU,QAAQ,OAAO,UAAU,UACrC,OAAO;EAET,IAAI,SAAS,YAAY,KAAK,IAAI,KAAK,GACrC,OAAO;EAET,KAAK,IAAI,KAAe;EAExB,IAAI,MAAM,QAAQ,KAAK,GACrB,OAAO,MAAM,KAAI,SAAQ,KAAK,MAAM,QAAQ,CAAC,CAAC;EAGhD,MAAM,MAA+B,CAAC;EACtC,KAAK,MAAM,CAAC,KAAK,QAAQ,OAAO,QAAQ,KAAgC,GACtE,IAAI,OAAO,eAAe,KAAK,SAAS,IACpC,cACA,KAAK,KAAK,QAAQ,CAAC;EAEzB,OAAO;CACT;CAEA,OAAO,KAAK,OAAO,CAAC;AACtB;;;;;;AAOA,SAAgB,cACd,SACA,cAAsB,qBACG;CACzB,IAAI,CAAC,SAAS,OAAO,CAAC;CAEtB,MAAM,UACJ,mBAAmB,UACf,CAAC,GAAG,QAAQ,QAAQ,CAAC,IACrB,OAAO,QAAQ,OAAO;CAE5B,MAAM,MAA+B,CAAC;CACtC,KAAK,MAAM,CAAC,KAAK,QAAQ,SACvB,IAAI,OAAO,kBAAkB,SAAS,IAAI,YAAY,CAAC,IAAI,cAAc;CAE3E,OAAO;AACT;;;;;;;AAQA,MAAM,kBAA4D;CAChE,CAAC,qCAAqC,mBAAmB;CACzD,CAAC,6EAA6E,gBAAgB;CAC9F,CAAC,4BAA4B,YAAY;CACzC,CAAC,oCAAoC,YAAY;CACjD,CAAC,mCAAmC,YAAY;CAChD,CAAC,yBAAyB,YAAY;AACxC;;;;;;;AAQA,SAAgB,aAAa,MAAsB;CACjD,IAAI,MAAM;CACV,KAAK,MAAM,CAAC,SAAS,gBAAgB,iBACnC,MAAM,IAAI,QAAQ,SAAS,WAAW;CAExC,OAAO;AACT;AAiBA,SAAgB,YACd,OACA,UAAsD,CAAC,GACxC;CACf,MAAM,EAAE,cAAc,GAAG,kBAAkB;CAE3C,IAAI,UAAU,QAAQ,OAAO,UAAU,UACrC,OAAO;EAAE,MAAM;EAAS,SAAS,OAAO,KAAK;CAAE;CAGjD,MAAM,MAAM;CAQZ,MAAM,SAAwB;EAC5B,MAAM,OAAO,IAAI,SAAS,WAAW,IAAI,OAAO;EAChD,SAAS,OAAO,IAAI,YAAY,WAAW,IAAI,UAAU,OAAO,KAAK;CACvE;CAEA,IAAI,OAAO,IAAI,SAAS,UACtB,OAAO,OAAO,IAAI;CAEpB,IAAI,IAAI,UAAU,QAChB,OAAO,QACL,IAAI,UAAU,QAAQ,OAAO,IAAI,UAAU,WACvC,OAAO,IAAI,OAAO,aAAa,IAC/B,IAAI;CAEZ,IAAI,gBAAgB,OAAO,IAAI,UAAU,UACvC,OAAO,QAAQ,IAAI;CAGrB,OAAO;AACT"}

package/esm/serve/serve.d.mts

@@ -0,0 +1,50 @@
+import { StreamLike } from "./stream-to-sse.mjs";
+import { IncomingMessage, ServerResponse } from "node:http";
+
+//#region ../@warlock.js/ai/src/serve/serve.d.ts
+/**
+ * Anything `serve` can expose: a primitive whose `stream(input, options)`
+ * returns a {@link StreamLike}. Agents, supervisors, and orchestrators all
+ * satisfy it.
+ */
+type ServableExecutable<TInput = unknown> = {
+  stream(input: TInput, options?: Record<string, unknown>): StreamLike<{
+    type: string;
+  }, unknown>;
+};
+/** Options for {@link serve}. */
+type ServeOptions<TInput = unknown> = {
+  /**
+   * Bearer token required on every request. When set, a request must send
+   * `Authorization: Bearer <token>`, else `401` (S4-style auth, the same
+   * control the dashboard uses — fold this in for a production deploy).
+   */
+  authToken?: string;
+  /**
+   * Map the parsed JSON request body to the executable's input. Default:
+   * `body.input`. Override to accept a different request shape.
+   */
+  toInput?: (body: Record<string, unknown>) => TInput;
+  /**
+   * Map the parsed body to per-call stream options (e.g. an orchestrator
+   * `{ sessionId, history }` so a turn resumes the right session — A3
+   * wiring). Default: pass `sessionId` / `history` straight through.
+   */
+  toOptions?: (body: Record<string, unknown>) => Record<string, unknown>;
+};
+/**
+ * Turn an executable into a `node:http` request handler that streams its
+ * run to the client as Server-Sent Events (A3) — the production-serving
+ * primitive. POST a JSON body (`{ input, sessionId?, history? }`); the
+ * response is an `text/event-stream` of the primitive's events, the final
+ * `result`, then `[DONE]`. Absorbs the auth-token control; pair with a
+ * `sessionLock` + an orchestrator for durable multi-turn serving.
+ *
+ * @example
+ * import { createServer } from "node:http";
+ * createServer(ai.serve(myAgent, { authToken: process.env.TOKEN })).listen(8787);
+ */
+declare function serve<TInput = unknown>(executable: ServableExecutable<TInput>, options?: ServeOptions<TInput>): (req: IncomingMessage, res: ServerResponse) => void;
+//#endregion
+export { ServableExecutable, ServeOptions, serve };
+//# sourceMappingURL=serve.d.mts.map

package/esm/serve/serve.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/serve/serve.ts"],"mappings":";;;;;;AAQA;;;KAAY,kBAAA;EACV,MAAA,CAAO,KAAA,EAAO,MAAA,EAAQ,OAAA,GAAU,MAAA,oBAA0B,UAAA;IAAa,IAAA;EAAA;AAAA;;KAI7D,YAAA;EAJI;;;;;EAUd,SAAA;EAV2E;AAAA;AAI7E;;EAWE,OAAA,IAAW,IAAA,EAAM,MAAA,sBAA4B,MAAA;EAA5B;;;;;EAMjB,SAAA,IAAa,IAAA,EAAM,MAAA,sBAA4B,MAAA;AAAA;;;;;;;;;;;AAAM;AAqBvD;iBAAgB,KAAA,mBACd,UAAA,EAAY,kBAAA,CAAmB,MAAA,GAC/B,OAAA,GAAS,YAAA,CAAa,MAAA,KACpB,GAAA,EAAK,eAAA,EAAiB,GAAA,EAAK,cAAA"}

package/esm/serve/serve.mjs

@@ -0,0 +1,90 @@
+import { streamToSSE } from "./stream-to-sse.mjs";
+
+//#region ../@warlock.js/ai/src/serve/serve.ts
+const SECURITY_HEADERS = {
+	"x-content-type-options": "nosniff",
+	"x-frame-options": "DENY",
+	"referrer-policy": "no-referrer"
+};
+/**
+* Turn an executable into a `node:http` request handler that streams its
+* run to the client as Server-Sent Events (A3) — the production-serving
+* primitive. POST a JSON body (`{ input, sessionId?, history? }`); the
+* response is an `text/event-stream` of the primitive's events, the final
+* `result`, then `[DONE]`. Absorbs the auth-token control; pair with a
+* `sessionLock` + an orchestrator for durable multi-turn serving.
+*
+* @example
+* import { createServer } from "node:http";
+* createServer(ai.serve(myAgent, { authToken: process.env.TOKEN })).listen(8787);
+*/
+function serve(executable, options = {}) {
+	const toInput = options.toInput ?? ((body) => body.input);
+	const toOptions = options.toOptions ?? ((body) => {
+		const opts = {};
+		if (body.sessionId !== void 0) opts.sessionId = body.sessionId;
+		if (body.history !== void 0) opts.history = body.history;
+		return opts;
+	});
+	return function handle(req, res) {
+		(async () => {
+			if (req.method !== "POST") {
+				sendJson(res, 405, { error: "method_not_allowed" });
+				return;
+			}
+			if (options.authToken && req.headers.authorization !== `Bearer ${options.authToken}`) {
+				sendJson(res, 401, { error: "unauthorized" });
+				return;
+			}
+			let body;
+			try {
+				body = await readJsonBody(req);
+			} catch {
+				sendJson(res, 400, { error: "invalid_json" });
+				return;
+			}
+			res.writeHead(200, {
+				"content-type": "text/event-stream; charset=utf-8",
+				"cache-control": "no-cache",
+				connection: "keep-alive",
+				...SECURITY_HEADERS
+			});
+			try {
+				const stream = executable.stream(toInput(body), toOptions(body));
+				for await (const frame of streamToSSE(stream)) res.write(frame);
+			} catch (error) {
+				res.write(`event: error\ndata: ${JSON.stringify({ message: error instanceof Error ? error.message : String(error) })}\n\n`);
+			} finally {
+				res.end();
+			}
+		})();
+	};
+}
+/** Read and JSON-parse a request body. */
+function readJsonBody(req) {
+	return new Promise((resolve, reject) => {
+		let raw = "";
+		req.on("data", (chunk) => {
+			raw += chunk.toString();
+		});
+		req.on("end", () => {
+			try {
+				resolve(raw ? JSON.parse(raw) : {});
+			} catch (error) {
+				reject(error);
+			}
+		});
+		req.on("error", reject);
+	});
+}
+function sendJson(res, status, body) {
+	res.writeHead(status, {
+		"content-type": "application/json; charset=utf-8",
+		...SECURITY_HEADERS
+	});
+	res.end(JSON.stringify(body));
+}
+
+//#endregion
+export { serve };
+//# sourceMappingURL=serve.mjs.map

package/esm/serve/serve.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/serve/serve.ts"],"sourcesContent":["import type { IncomingMessage, ServerResponse } from \"node:http\";\nimport { streamToSSE, type StreamLike } from \"./stream-to-sse\";\n\n/**\n * Anything `serve` can expose: a primitive whose `stream(input, options)`\n * returns a {@link StreamLike}. Agents, supervisors, and orchestrators all\n * satisfy it.\n */\nexport type ServableExecutable<TInput = unknown> = {\n  stream(input: TInput, options?: Record<string, unknown>): StreamLike<{ type: string }, unknown>;\n};\n\n/** Options for {@link serve}. */\nexport type ServeOptions<TInput = unknown> = {\n  /**\n   * Bearer token required on every request. When set, a request must send\n   * `Authorization: Bearer <token>`, else `401` (S4-style auth, the same\n   * control the dashboard uses — fold this in for a production deploy).\n   */\n  authToken?: string;\n  /**\n   * Map the parsed JSON request body to the executable's input. Default:\n   * `body.input`. Override to accept a different request shape.\n   */\n  toInput?: (body: Record<string, unknown>) => TInput;\n  /**\n   * Map the parsed body to per-call stream options (e.g. an orchestrator\n   * `{ sessionId, history }` so a turn resumes the right session — A3\n   * wiring). Default: pass `sessionId` / `history` straight through.\n   */\n  toOptions?: (body: Record<string, unknown>) => Record<string, unknown>;\n};\n\nconst SECURITY_HEADERS: Record<string, string> = {\n  \"x-content-type-options\": \"nosniff\",\n  \"x-frame-options\": \"DENY\",\n  \"referrer-policy\": \"no-referrer\",\n};\n\n/**\n * Turn an executable into a `node:http` request handler that streams its\n * run to the client as Server-Sent Events (A3) — the production-serving\n * primitive. POST a JSON body (`{ input, sessionId?, history? }`); the\n * response is an `text/event-stream` of the primitive's events, the final\n * `result`, then `[DONE]`. Absorbs the auth-token control; pair with a\n * `sessionLock` + an orchestrator for durable multi-turn serving.\n *\n * @example\n * import { createServer } from \"node:http\";\n * createServer(ai.serve(myAgent, { authToken: process.env.TOKEN })).listen(8787);\n */\nexport function serve<TInput = unknown>(\n  executable: ServableExecutable<TInput>,\n  options: ServeOptions<TInput> = {},\n): (req: IncomingMessage, res: ServerResponse) => void {\n  const toInput = options.toInput ?? ((body) => body.input as TInput);\n  const toOptions =\n    options.toOptions ??\n    ((body) => {\n      const opts: Record<string, unknown> = {};\n      if (body.sessionId !== undefined) opts.sessionId = body.sessionId;\n      if (body.history !== undefined) opts.history = body.history;\n      return opts;\n    });\n\n  return function handle(req: IncomingMessage, res: ServerResponse): void {\n    void (async () => {\n      if (req.method !== \"POST\") {\n        sendJson(res, 405, { error: \"method_not_allowed\" });\n        return;\n      }\n\n      if (options.authToken && req.headers.authorization !== `Bearer ${options.authToken}`) {\n        sendJson(res, 401, { error: \"unauthorized\" });\n        return;\n      }\n\n      let body: Record<string, unknown>;\n      try {\n        body = await readJsonBody(req);\n      } catch {\n        sendJson(res, 400, { error: \"invalid_json\" });\n        return;\n      }\n\n      res.writeHead(200, {\n        \"content-type\": \"text/event-stream; charset=utf-8\",\n        \"cache-control\": \"no-cache\",\n        connection: \"keep-alive\",\n        ...SECURITY_HEADERS,\n      });\n\n      try {\n        const stream = executable.stream(toInput(body), toOptions(body));\n        for await (const frame of streamToSSE(stream)) {\n          res.write(frame);\n        }\n      } catch (error) {\n        res.write(\n          `event: error\\ndata: ${JSON.stringify({\n            message: error instanceof Error ? error.message : String(error),\n          })}\\n\\n`,\n        );\n      } finally {\n        res.end();\n      }\n    })();\n  };\n}\n\n/** Read and JSON-parse a request body. */\nfunction readJsonBody(req: IncomingMessage): Promise<Record<string, unknown>> {\n  return new Promise((resolve, reject) => {\n    let raw = \"\";\n    req.on(\"data\", (chunk: Buffer | string) => {\n      raw += chunk.toString();\n    });\n    req.on(\"end\", () => {\n      try {\n        resolve(raw ? (JSON.parse(raw) as Record<string, unknown>) : {});\n      } catch (error) {\n        reject(error);\n      }\n    });\n    req.on(\"error\", reject);\n  });\n}\n\nfunction sendJson(res: ServerResponse, status: number, body: unknown): void {\n  res.writeHead(status, { \"content-type\": \"application/json; charset=utf-8\", ...SECURITY_HEADERS });\n  res.end(JSON.stringify(body));\n}\n"],"mappings":";;;AAiCA,MAAM,mBAA2C;CAC/C,0BAA0B;CAC1B,mBAAmB;CACnB,mBAAmB;AACrB;;;;;;;;;;;;;AAcA,SAAgB,MACd,YACA,UAAgC,CAAC,GACoB;CACrD,MAAM,UAAU,QAAQ,aAAa,SAAS,KAAK;CACnD,MAAM,YACJ,QAAQ,eACN,SAAS;EACT,MAAM,OAAgC,CAAC;EACvC,IAAI,KAAK,cAAc,QAAW,KAAK,YAAY,KAAK;EACxD,IAAI,KAAK,YAAY,QAAW,KAAK,UAAU,KAAK;EACpD,OAAO;CACT;CAEF,OAAO,SAAS,OAAO,KAAsB,KAA2B;EACtE,CAAM,YAAY;GAChB,IAAI,IAAI,WAAW,QAAQ;IACzB,SAAS,KAAK,KAAK,EAAE,OAAO,qBAAqB,CAAC;IAClD;GACF;GAEA,IAAI,QAAQ,aAAa,IAAI,QAAQ,kBAAkB,UAAU,QAAQ,aAAa;IACpF,SAAS,KAAK,KAAK,EAAE,OAAO,eAAe,CAAC;IAC5C;GACF;GAEA,IAAI;GACJ,IAAI;IACF,OAAO,MAAM,aAAa,GAAG;GAC/B,QAAQ;IACN,SAAS,KAAK,KAAK,EAAE,OAAO,eAAe,CAAC;IAC5C;GACF;GAEA,IAAI,UAAU,KAAK;IACjB,gBAAgB;IAChB,iBAAiB;IACjB,YAAY;IACZ,GAAG;GACL,CAAC;GAED,IAAI;IACF,MAAM,SAAS,WAAW,OAAO,QAAQ,IAAI,GAAG,UAAU,IAAI,CAAC;IAC/D,WAAW,MAAM,SAAS,YAAY,MAAM,GAC1C,IAAI,MAAM,KAAK;GAEnB,SAAS,OAAO;IACd,IAAI,MACF,uBAAuB,KAAK,UAAU,EACpC,SAAS,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,EAChE,CAAC,EAAE,KACL;GACF,UAAU;IACR,IAAI,IAAI;GACV;EACF,EAAC,CAAE;CACL;AACF;;AAGA,SAAS,aAAa,KAAwD;CAC5E,OAAO,IAAI,SAAS,SAAS,WAAW;EACtC,IAAI,MAAM;EACV,IAAI,GAAG,SAAS,UAA2B;GACzC,OAAO,MAAM,SAAS;EACxB,CAAC;EACD,IAAI,GAAG,aAAa;GAClB,IAAI;IACF,QAAQ,MAAO,KAAK,MAAM,GAAG,IAAgC,CAAC,CAAC;GACjE,SAAS,OAAO;IACd,OAAO,KAAK;GACd;EACF,CAAC;EACD,IAAI,GAAG,SAAS,MAAM;CACxB,CAAC;AACH;AAEA,SAAS,SAAS,KAAqB,QAAgB,MAAqB;CAC1E,IAAI,UAAU,QAAQ;EAAE,gBAAgB;EAAmC,GAAG;CAAiB,CAAC;CAChG,IAAI,IAAI,KAAK,UAAU,IAAI,CAAC;AAC9B"}

package/esm/serve/sse.d.mts

@@ -0,0 +1,20 @@
+//#region ../@warlock.js/ai/src/serve/sse.d.ts
+/**
+ * Encode one Server-Sent-Events frame. Multi-line `data` is split into
+ * multiple `data:` lines per the SSE spec, so JSON with embedded newlines
+ * still parses on the client.
+ *
+ * @example
+ * encodeSSE({ event: "agent.trip.streaming", data: { delta: "Hi" } });
+ * // "event: agent.trip.streaming\ndata: {\"delta\":\"Hi\"}\n\n"
+ */
+declare function encodeSSE(frame: {
+  event?: string;
+  data: unknown;
+  id?: string;
+}): string;
+/** The terminal SSE frame a client watches for to stop reading. */
+declare const SSE_DONE = "data: [DONE]\n\n";
+//#endregion
+export { SSE_DONE, encodeSSE };
+//# sourceMappingURL=sse.d.mts.map

package/esm/serve/sse.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/serve/sse.ts"],"mappings":";;AASA;;;;;;;;iBAAgB,SAAA,CAAU,KAAA;EAAS,KAAA;EAAgB,IAAA;EAAe,EAAA;AAAA;;cAgBrD,QAAA"}

package/esm/serve/sse.mjs

@@ -0,0 +1,25 @@
+//#region ../@warlock.js/ai/src/serve/sse.ts
+/**
+* Encode one Server-Sent-Events frame. Multi-line `data` is split into
+* multiple `data:` lines per the SSE spec, so JSON with embedded newlines
+* still parses on the client.
+*
+* @example
+* encodeSSE({ event: "agent.trip.streaming", data: { delta: "Hi" } });
+* // "event: agent.trip.streaming\ndata: {\"delta\":\"Hi\"}\n\n"
+*/
+function encodeSSE(frame) {
+	let out = "";
+	if (frame.id) out += `id: ${frame.id}\n`;
+	if (frame.event) out += `event: ${frame.event}\n`;
+	const data = typeof frame.data === "string" ? frame.data : JSON.stringify(frame.data);
+	for (const line of data.split("\n")) out += `data: ${line}\n`;
+	out += "\n";
+	return out;
+}
+/** The terminal SSE frame a client watches for to stop reading. */
+const SSE_DONE = "data: [DONE]\n\n";
+
+//#endregion
+export { SSE_DONE, encodeSSE };
+//# sourceMappingURL=sse.mjs.map

package/esm/serve/sse.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/serve/sse.ts"],"sourcesContent":["/**\n * Encode one Server-Sent-Events frame. Multi-line `data` is split into\n * multiple `data:` lines per the SSE spec, so JSON with embedded newlines\n * still parses on the client.\n *\n * @example\n * encodeSSE({ event: \"agent.trip.streaming\", data: { delta: \"Hi\" } });\n * // \"event: agent.trip.streaming\\ndata: {\\\"delta\\\":\\\"Hi\\\"}\\n\\n\"\n */\nexport function encodeSSE(frame: { event?: string; data: unknown; id?: string }): string {\n  let out = \"\";\n  if (frame.id) out += `id: ${frame.id}\\n`;\n  if (frame.event) out += `event: ${frame.event}\\n`;\n\n  const data =\n    typeof frame.data === \"string\" ? frame.data : JSON.stringify(frame.data);\n  for (const line of data.split(\"\\n\")) {\n    out += `data: ${line}\\n`;\n  }\n\n  out += \"\\n\";\n  return out;\n}\n\n/** The terminal SSE frame a client watches for to stop reading. */\nexport const SSE_DONE = \"data: [DONE]\\n\\n\";\n"],"mappings":";;;;;;;;;;AASA,SAAgB,UAAU,OAA+D;CACvF,IAAI,MAAM;CACV,IAAI,MAAM,IAAI,OAAO,OAAO,MAAM,GAAG;CACrC,IAAI,MAAM,OAAO,OAAO,UAAU,MAAM,MAAM;CAE9C,MAAM,OACJ,OAAO,MAAM,SAAS,WAAW,MAAM,OAAO,KAAK,UAAU,MAAM,IAAI;CACzE,KAAK,MAAM,QAAQ,KAAK,MAAM,IAAI,GAChC,OAAO,SAAS,KAAK;CAGvB,OAAO;CACP,OAAO;AACT;;AAGA,MAAa,WAAW"}

package/esm/serve/stream-to-sse.d.mts

@@ -0,0 +1,29 @@
+//#region ../@warlock.js/ai/src/serve/stream-to-sse.d.ts
+/**
+ * A streamable execution: an async iterable of typed events that also
+ * exposes the final `result` promise — exactly the shape every primitive's
+ * `stream()` returns ({@link StreamContract}).
+ */
+type StreamLike<TEvent extends {
+  type: string;
+}, TResult> = AsyncIterable<TEvent> & {
+  result?: Promise<TResult>;
+};
+/**
+ * Convert a primitive's event stream into an SSE byte stream (A3): each
+ * event becomes an SSE frame named by its `type`, then the final `result`
+ * (or an `error` frame if it rejects) is emitted, and finally the
+ * `[DONE]` sentinel. Pure and transport-agnostic — {@link serve} pipes it
+ * to an HTTP response, but it works against any sink.
+ *
+ * @example
+ * for await (const frame of streamToSSE(agent.stream("hi"))) {
+ *   res.write(frame);
+ * }
+ */
+declare function streamToSSE<TEvent extends {
+  type: string;
+}, TResult>(stream: StreamLike<TEvent, TResult>): AsyncIterable<string>;
+//#endregion
+export { StreamLike, streamToSSE };
+//# sourceMappingURL=stream-to-sse.d.mts.map

package/esm/serve/stream-to-sse.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-to-sse.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/serve/stream-to-sse.ts"],"mappings":";;AAOA;;;;KAAY,UAAA;EAA4B,IAAA;AAAA,cACtC,aAAA,CAAc,MAAA;EAAY,MAAA,GAAS,OAAA,CAAQ,OAAA;AAAA;;;;;;;;;;AAAO;AAcpD;;iBAAuB,WAAA;EAA6B,IAAA;AAAA,YAClD,MAAA,EAAQ,UAAA,CAAW,MAAA,EAAQ,OAAA,IAC1B,aAAA"}

package/esm/serve/stream-to-sse.mjs

@@ -0,0 +1,37 @@
+import { SSE_DONE, encodeSSE } from "./sse.mjs";
+
+//#region ../@warlock.js/ai/src/serve/stream-to-sse.ts
+/**
+* Convert a primitive's event stream into an SSE byte stream (A3): each
+* event becomes an SSE frame named by its `type`, then the final `result`
+* (or an `error` frame if it rejects) is emitted, and finally the
+* `[DONE]` sentinel. Pure and transport-agnostic — {@link serve} pipes it
+* to an HTTP response, but it works against any sink.
+*
+* @example
+* for await (const frame of streamToSSE(agent.stream("hi"))) {
+*   res.write(frame);
+* }
+*/
+async function* streamToSSE(stream) {
+	for await (const event of stream) yield encodeSSE({
+		event: event.type,
+		data: event
+	});
+	if (stream.result) try {
+		yield encodeSSE({
+			event: "result",
+			data: await stream.result
+		});
+	} catch (error) {
+		yield encodeSSE({
+			event: "error",
+			data: { message: error instanceof Error ? error.message : String(error) }
+		});
+	}
+	yield SSE_DONE;
+}
+
+//#endregion
+export { streamToSSE };
+//# sourceMappingURL=stream-to-sse.mjs.map

package/esm/serve/stream-to-sse.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-to-sse.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/serve/stream-to-sse.ts"],"sourcesContent":["import { encodeSSE, SSE_DONE } from \"./sse\";\n\n/**\n * A streamable execution: an async iterable of typed events that also\n * exposes the final `result` promise — exactly the shape every primitive's\n * `stream()` returns ({@link StreamContract}).\n */\nexport type StreamLike<TEvent extends { type: string }, TResult> =\n  AsyncIterable<TEvent> & { result?: Promise<TResult> };\n\n/**\n * Convert a primitive's event stream into an SSE byte stream (A3): each\n * event becomes an SSE frame named by its `type`, then the final `result`\n * (or an `error` frame if it rejects) is emitted, and finally the\n * `[DONE]` sentinel. Pure and transport-agnostic — {@link serve} pipes it\n * to an HTTP response, but it works against any sink.\n *\n * @example\n * for await (const frame of streamToSSE(agent.stream(\"hi\"))) {\n *   res.write(frame);\n * }\n */\nexport async function* streamToSSE<TEvent extends { type: string }, TResult>(\n  stream: StreamLike<TEvent, TResult>,\n): AsyncIterable<string> {\n  for await (const event of stream) {\n    yield encodeSSE({ event: event.type, data: event });\n  }\n\n  if (stream.result) {\n    try {\n      const result = await stream.result;\n      yield encodeSSE({ event: \"result\", data: result });\n    } catch (error) {\n      yield encodeSSE({\n        event: \"error\",\n        data: { message: error instanceof Error ? error.message : String(error) },\n      });\n    }\n  }\n\n  yield SSE_DONE;\n}\n"],"mappings":";;;;;;;;;;;;;;;AAsBA,gBAAuB,YACrB,QACuB;CACvB,WAAW,MAAM,SAAS,QACxB,MAAM,UAAU;EAAE,OAAO,MAAM;EAAM,MAAM;CAAM,CAAC;CAGpD,IAAI,OAAO,QACT,IAAI;EAEF,MAAM,UAAU;GAAE,OAAO;GAAU,MAAM,MADpB,OAAO;EACoB,CAAC;CACnD,SAAS,OAAO;EACd,MAAM,UAAU;GACd,OAAO;GACP,MAAM,EAAE,SAAS,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,EAAE;EAC1E,CAAC;CACH;CAGF,MAAM;AACR"}

package/esm/skills/catalog.d.mts

@@ -0,0 +1,49 @@
+import { EmbedderContract } from "../contracts/embedder.contract.mjs";
+import { SkillCatalogEntry, SkillRecord } from "./contracts/skill-record.type.mjs";
+import { SkillsStoreContract } from "./contracts/skills-store.contract.mjs";
+
+//#region ../@warlock.js/ai/src/skills/catalog.d.ts
+/**
+ * Merge every source's `list()` into one de-duplicated catalog. Sources
+ * are merged in order; a LATER source wins on a name collision (explicit,
+ * documented precedence). Candidates are already filtered by each store's
+ * `list()`, so the merged catalog never carries an inert candidate.
+ */
+declare function buildCatalog(stores: SkillsStoreContract[], scope?: {
+  tags?: string[];
+}): Promise<SkillCatalogEntry[]>;
+/**
+ * Render the catalog as one line per skill — `name`, `version`,
+ * `description` — matching the projection `scripts/generate-llms.mjs`
+ * emits for `llms.txt` so the runtime catalog and the docs index read
+ * identically. Returns an empty string when no skills are in scope so the
+ * agent prepends nothing.
+ */
+declare function renderCatalogPrompt(name: string, entries: SkillCatalogEntry[]): string;
+/**
+ * Load the full record for `name` across the merged sources, honoring the
+ * later-source-wins precedence: the FIRST store (iterating in reverse) to
+ * return a hit owns the name. A pinned `version` narrows the lookup.
+ * Returns `undefined` when no source has the skill.
+ */
+declare function loadRecord(stores: SkillsStoreContract[], name: string, version?: number): Promise<SkillRecord | undefined>;
+/**
+ * Rank the in-scope catalog by cosine similarity to `input` and return the
+ * full `SkillRecord`s for the top `topK` clearing `threshold`.
+ *
+ * Embeds `input` and every catalog `description` via the resolved
+ * embedder (explicit `inject.embedder`, else the lazy provider), scores by
+ * cosine similarity, sorts descending, applies the optional floor, slices
+ * to `topK`, then loads those bodies. The embedder is the only optional
+ * dependency this whole feature carries.
+ */
+declare function semanticPreselect(stores: SkillsStoreContract[], input: string, topK: number, options?: {
+  embedder?: EmbedderContract;
+  threshold?: number;
+  scope?: {
+    tags?: string[];
+  };
+}): Promise<SkillRecord[]>;
+//#endregion
+export { buildCatalog, loadRecord, renderCatalogPrompt, semanticPreselect };
+//# sourceMappingURL=catalog.d.mts.map

package/esm/skills/catalog.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/skills/catalog.ts"],"mappings":";;;;;;;AA+FA;;;;iBAAsB,YAAA,CACpB,MAAA,EAAQ,mBAAA,IACR,KAAA;EAAU,IAAA;AAAA,IACT,OAAA,CAAQ,iBAAA;;;;;;;;iBAqBK,mBAAA,CAAoB,IAAA,UAAc,OAAA,EAAS,iBAAiB;AArBhD;AAqB5B;;;;;AArB4B,iBA6CN,UAAA,CACpB,MAAA,EAAQ,mBAAA,IACR,IAAA,UACA,OAAA,YACC,OAAA,CAAQ,WAAA;;;AA5BmE;AAwB9E;;;;;;;iBA0BsB,iBAAA,CACpB,MAAA,EAAQ,mBAAA,IACR,KAAA,UACA,IAAA,UACA,OAAA;EAAW,QAAA,GAAW,gBAAA;EAAkB,SAAA;EAAoB,KAAA;IAAU,IAAA;EAAA;AAAA,IACrE,OAAA,CAAQ,WAAA"}

package/esm/skills/catalog.mjs

@@ -0,0 +1,140 @@
+//#region ../@warlock.js/ai/src/skills/catalog.ts
+let isEmbedderPeerInstalled = null;
+let loadingPromise;
+const EMBEDDER_INSTALL_INSTRUCTIONS = `
+Semantic skill pre-injection ({ inject: { select: "semantic" } }) needs an
+embedder. Pass one explicitly (reuse the one you built for ai.memory()):
+
+  skills({ inject: { select: "semantic", topK: 2, embedder } })
+
+or install an embedder provider:
+
+  npm install @warlock.js/ai-openai
+
+Or with your preferred package manager:
+
+  pnpm add @warlock.js/ai-openai
+  yarn add @warlock.js/ai-openai
+
+Then build one with \`new OpenAIEmbedder(client, { name: "text-embedding-3-small" })\`
+and pass it via \`inject.embedder\`.
+`.trim();
+/**
+* Probe for an installed embedder provider once, concurrency-safe. A bare
+* `catch` flips the flag to `false`; the curated install string surfaces
+* at use time. The provider's embedder needs a constructed SDK client, so
+* we cannot auto-build one — the probe only decides whether the curated
+* message should mention installing the package vs. just passing one in.
+*/
+function probeEmbedderPeer() {
+	if (isEmbedderPeerInstalled !== null) return Promise.resolve();
+	if (loadingPromise) return loadingPromise;
+	loadingPromise = (async () => {
+		try {
+			await import("../ai-openai/src/index.mjs");
+			isEmbedderPeerInstalled = true;
+		} catch {
+			isEmbedderPeerInstalled = false;
+		}
+	})();
+	return loadingPromise;
+}
+/**
+* Resolve the embedder for semantic selection. The explicit
+* `inject.embedder` always wins. With none supplied, the lazy probe runs
+* and the curated install string is thrown at use time — a provider's
+* embedder requires a constructed client, so there is no safe auto-build.
+*/
+async function resolveEmbedder(explicit) {
+	if (explicit) return explicit;
+	probeEmbedderPeer();
+	throw new Error(EMBEDDER_INSTALL_INSTRUCTIONS);
+}
+/**
+* Merge every source's `list()` into one de-duplicated catalog. Sources
+* are merged in order; a LATER source wins on a name collision (explicit,
+* documented precedence). Candidates are already filtered by each store's
+* `list()`, so the merged catalog never carries an inert candidate.
+*/
+async function buildCatalog(stores, scope) {
+	const merged = /* @__PURE__ */ new Map();
+	for (const store of stores) {
+		const entries = await store.list(scope);
+		for (const entry of entries) merged.set(entry.name, entry);
+	}
+	return [...merged.values()];
+}
+/**
+* Render the catalog as one line per skill — `name`, `version`,
+* `description` — matching the projection `scripts/generate-llms.mjs`
+* emits for `llms.txt` so the runtime catalog and the docs index read
+* identically. Returns an empty string when no skills are in scope so the
+* agent prepends nothing.
+*/
+function renderCatalogPrompt(name, entries) {
+	if (entries.length === 0) return "";
+	const lines = entries.map((entry) => `- ${entry.name} (v${entry.version}): ${entry.description}`);
+	return [
+		`# Available skills — "${name}"`,
+		"",
+		"You can load any of the following skills on demand with the `loadSkill` tool to pull its full instructions into context:",
+		"",
+		...lines
+	].join("\n");
+}
+/**
+* Load the full record for `name` across the merged sources, honoring the
+* later-source-wins precedence: the FIRST store (iterating in reverse) to
+* return a hit owns the name. A pinned `version` narrows the lookup.
+* Returns `undefined` when no source has the skill.
+*/
+async function loadRecord(stores, name, version) {
+	for (let index = stores.length - 1; index >= 0; index--) {
+		const record = await stores[index].load(name, version);
+		if (record) return record;
+	}
+}
+/**
+* Rank the in-scope catalog by cosine similarity to `input` and return the
+* full `SkillRecord`s for the top `topK` clearing `threshold`.
+*
+* Embeds `input` and every catalog `description` via the resolved
+* embedder (explicit `inject.embedder`, else the lazy provider), scores by
+* cosine similarity, sorts descending, applies the optional floor, slices
+* to `topK`, then loads those bodies. The embedder is the only optional
+* dependency this whole feature carries.
+*/
+async function semanticPreselect(stores, input, topK, options = {}) {
+	const catalog = await buildCatalog(stores, options.scope);
+	if (catalog.length === 0 || topK <= 0) return [];
+	const { vectors } = await (await resolveEmbedder(options.embedder)).embedMany([input, ...catalog.map((entry) => entry.description)]);
+	const inputVector = vectors[0];
+	const threshold = options.threshold ?? 0;
+	const scored = catalog.map((entry, index) => ({
+		entry,
+		score: cosineSimilarity(inputVector, vectors[index + 1])
+	})).filter((candidate) => candidate.score >= threshold).sort((first, second) => second.score - first.score).slice(0, topK);
+	const records = [];
+	for (const candidate of scored) {
+		const record = await loadRecord(stores, candidate.entry.name, candidate.entry.version);
+		if (record) records.push(record);
+	}
+	return records;
+}
+/** Cosine similarity of two equal-length vectors; `0` when either is degenerate. */
+function cosineSimilarity(a, b) {
+	let dot = 0;
+	let normA = 0;
+	let normB = 0;
+	for (let index = 0; index < a.length; index++) {
+		dot += a[index] * b[index];
+		normA += a[index] * a[index];
+		normB += b[index] * b[index];
+	}
+	if (normA === 0 || normB === 0) return 0;
+	return dot / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+
+//#endregion
+export { buildCatalog, loadRecord, renderCatalogPrompt, semanticPreselect };
+//# sourceMappingURL=catalog.mjs.map