@warlock.js/core 4.4.0 → 4.5.0

package/esm/ai/src/skills/skills.mjs

@@ -0,0 +1,109 @@
+import { buildCatalog, loadRecord, renderCatalogPrompt, semanticPreselect } from "./catalog.mjs";
+import { loadSkillTool } from "./load-skill-tool.mjs";
+import { saveSkillTool } from "./save-skill-tool.mjs";
+import { resolveSource } from "./sources/index.mjs";
+
+//#region ../@warlock.js/ai/src/skills/skills.ts
+const DEFAULT_MAX_LOADS_PER_RUN = 5;
+/**
+* Create a runtime skills library — the **mechanism** behind the
+* first-class `skills` agent option.
+*
+* The returned {@link SkillsContract} produces the agent-facing wiring:
+* - `catalog` / `catalogPrompt` — the always-injected cheap metadata block
+*   (one line per in-scope, non-candidate skill).
+* - `preload` — the bodies to inject up front per `inject` (`[]` when
+*   `inject` is omitted — the default catalog-only progressive disclosure).
+* - `tools(runId)` — the `loadSkill` tool always; plus `saveSkill` ONLY
+*   when a `review` gate is configured (otherwise self-authoring is inert).
+*
+* Sources are merged in order; a later source wins on a name collision.
+* `maxLoadsPerRun` (default 5) caps `loadSkill` calls per run; exhaustion
+* is an error RESULT the model self-corrects from, never a throw.
+*
+* @example
+* const lib = skills({
+*   name: "build-skills",
+*   sources: [{ type: "directory", path: "./agent-skills" }],
+*   inject: { select: "semantic", topK: 2, embedder },
+*   maxLoadsPerRun: 4,
+*   scope: { tags: ["frontend"] },
+* });
+*/
+function skills(config) {
+	if (!config.sources || config.sources.length === 0) throw new Error(`skills("${config.name}"): at least one source is required (directory / url / store)`);
+	const stores = config.sources.map(resolveSource);
+	const scope = config.scope;
+	const maxLoadsPerRun = config.maxLoadsPerRun ?? DEFAULT_MAX_LOADS_PER_RUN;
+	const reviewExposed = config.review !== void 0;
+	/** Fire an analytics event, swallowing any sink error (mirrors agent hooks). */
+	const emit = (event) => {
+		if (!config.analytics) return;
+		try {
+			Promise.resolve(config.analytics(event)).catch(() => void 0);
+		} catch {}
+	};
+	const catalog = async () => {
+		const entries = await buildCatalog(stores, scope);
+		for (const entry of entries) emit({
+			type: "catalogued",
+			skill: entry.name,
+			version: entry.version
+		});
+		return entries;
+	};
+	return {
+		name: config.name,
+		catalog,
+		async catalogPrompt() {
+			const entries = await catalog();
+			return renderCatalogPrompt(config.name, entries);
+		},
+		async preload(input) {
+			if (!config.inject) return [];
+			if (config.inject === "all") {
+				const entries = await buildCatalog(stores, scope);
+				const records = [];
+				for (const entry of entries) {
+					const record = await loadRecord(stores, entry.name, entry.version);
+					if (record) records.push(record);
+				}
+				return records;
+			}
+			return semanticPreselect(stores, input, config.inject.topK, {
+				embedder: config.inject.embedder,
+				threshold: config.inject.threshold,
+				scope
+			});
+		},
+		tools(runId) {
+			const entries = [loadSkillTool({
+				load: (name, version) => loadRecord(stores, name, version),
+				maxLoadsPerRun,
+				onLoaded: (record) => emit({
+					type: "loaded",
+					skill: record.name,
+					version: record.version,
+					runId
+				})
+			})];
+			if (reviewExposed && config.review) {
+				const reviewStore = config.review.store;
+				entries.push(saveSkillTool({
+					saveCandidate: (record) => reviewStore.saveCandidate(record),
+					onSaved: (record) => emit({
+						type: "saved",
+						skill: record.name,
+						version: record.version,
+						runId
+					})
+				}));
+			}
+			return entries;
+		}
+	};
+}
+
+//#endregion
+export { skills };
+//# sourceMappingURL=skills.mjs.map

package/esm/ai/src/skills/skills.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/skills/skills.ts"],"sourcesContent":["import type { AgentToolEntry } from \"../tool/executable-as-tool\";\nimport {\n  buildCatalog,\n  loadRecord,\n  renderCatalogPrompt,\n  semanticPreselect,\n} from \"./catalog\";\nimport type {\n  SkillAnalyticsEvent,\n  SkillsConfig,\n} from \"./contracts/skills-config.type\";\nimport type {\n  SkillCatalogEntry,\n  SkillRecord,\n} from \"./contracts/skill-record.type\";\nimport type { SkillsContract } from \"./contracts/skills.contract\";\nimport type { SkillsStoreContract } from \"./contracts/skills-store.contract\";\nimport { loadSkillTool } from \"./load-skill-tool\";\nimport { saveSkillTool } from \"./save-skill-tool\";\nimport { resolveSource } from \"./sources\";\n\nconst DEFAULT_MAX_LOADS_PER_RUN = 5;\n\n/**\n * Create a runtime skills library — the **mechanism** behind the\n * first-class `skills` agent option.\n *\n * The returned {@link SkillsContract} produces the agent-facing wiring:\n * - `catalog` / `catalogPrompt` — the always-injected cheap metadata block\n *   (one line per in-scope, non-candidate skill).\n * - `preload` — the bodies to inject up front per `inject` (`[]` when\n *   `inject` is omitted — the default catalog-only progressive disclosure).\n * - `tools(runId)` — the `loadSkill` tool always; plus `saveSkill` ONLY\n *   when a `review` gate is configured (otherwise self-authoring is inert).\n *\n * Sources are merged in order; a later source wins on a name collision.\n * `maxLoadsPerRun` (default 5) caps `loadSkill` calls per run; exhaustion\n * is an error RESULT the model self-corrects from, never a throw.\n *\n * @example\n * const lib = skills({\n *   name: \"build-skills\",\n *   sources: [{ type: \"directory\", path: \"./agent-skills\" }],\n *   inject: { select: \"semantic\", topK: 2, embedder },\n *   maxLoadsPerRun: 4,\n *   scope: { tags: [\"frontend\"] },\n * });\n */\nexport function skills(config: SkillsConfig): SkillsContract {\n  if (!config.sources || config.sources.length === 0) {\n    throw new Error(\n      `skills(\"${config.name}\"): at least one source is required (directory / url / store)`,\n    );\n  }\n\n  const stores: SkillsStoreContract[] = config.sources.map(resolveSource);\n  const scope = config.scope;\n  const maxLoadsPerRun = config.maxLoadsPerRun ?? DEFAULT_MAX_LOADS_PER_RUN;\n  const reviewExposed = config.review !== undefined;\n\n  /** Fire an analytics event, swallowing any sink error (mirrors agent hooks). */\n  const emit = (event: SkillAnalyticsEvent): void => {\n    if (!config.analytics) {\n      return;\n    }\n\n    try {\n      void Promise.resolve(config.analytics(event)).catch(() => undefined);\n    } catch {\n      // Sink threw synchronously — swallowed; analytics never crash a run.\n    }\n  };\n\n  const catalog = async (): Promise<SkillCatalogEntry[]> => {\n    const entries = await buildCatalog(stores, scope);\n\n    for (const entry of entries) {\n      emit({ type: \"catalogued\", skill: entry.name, version: entry.version });\n    }\n\n    return entries;\n  };\n\n  return {\n    name: config.name,\n\n    catalog,\n\n    async catalogPrompt(): Promise<string> {\n      const entries = await catalog();\n\n      return renderCatalogPrompt(config.name, entries);\n    },\n\n    async preload(input: string): Promise<SkillRecord[]> {\n      if (!config.inject) {\n        return [];\n      }\n\n      if (config.inject === \"all\") {\n        const entries = await buildCatalog(stores, scope);\n        const records: SkillRecord[] = [];\n\n        for (const entry of entries) {\n          const record = await loadRecord(stores, entry.name, entry.version);\n\n          if (record) {\n            records.push(record);\n          }\n        }\n\n        return records;\n      }\n\n      // `{ select: \"semantic\", topK }`\n      return semanticPreselect(stores, input, config.inject.topK, {\n        embedder: config.inject.embedder,\n        threshold: config.inject.threshold,\n        scope,\n      });\n    },\n\n    tools(runId?: string): AgentToolEntry<any, any>[] {\n      const entries: AgentToolEntry<any, any>[] = [\n        loadSkillTool({\n          load: (name, version) => loadRecord(stores, name, version),\n          maxLoadsPerRun,\n          onLoaded: (record) =>\n            emit({ type: \"loaded\", skill: record.name, version: record.version, runId }),\n        }),\n      ];\n\n      // Phase 2 — `saveSkill` is exposed ONLY when a review gate is wired.\n      // Absent gate ⇒ self-authoring is inert: the tool is never registered\n      // and a candidate can never be written, let alone injected.\n      if (reviewExposed && config.review) {\n        const reviewStore = config.review.store;\n\n        entries.push(\n          saveSkillTool({\n            saveCandidate: (record) => reviewStore.saveCandidate(record),\n            onSaved: (record) =>\n              emit({ type: \"saved\", skill: record.name, version: record.version, runId }),\n          }),\n        );\n      }\n\n      return entries;\n    },\n  };\n}\n"],"mappings":";;;;;;AAqBA,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BlC,SAAgB,OAAO,QAAsC;CAC3D,IAAI,CAAC,OAAO,WAAW,OAAO,QAAQ,WAAW,GAC/C,MAAM,IAAI,MACR,WAAW,OAAO,KAAK,8DACzB;CAGF,MAAM,SAAgC,OAAO,QAAQ,IAAI,aAAa;CACtE,MAAM,QAAQ,OAAO;CACrB,MAAM,iBAAiB,OAAO,kBAAkB;CAChD,MAAM,gBAAgB,OAAO,WAAW;;CAGxC,MAAM,QAAQ,UAAqC;EACjD,IAAI,CAAC,OAAO,WACV;EAGF,IAAI;GACF,AAAK,QAAQ,QAAQ,OAAO,UAAU,KAAK,CAAC,CAAC,CAAC,YAAY,MAAS;EACrE,QAAQ,CAER;CACF;CAEA,MAAM,UAAU,YAA0C;EACxD,MAAM,UAAU,MAAM,aAAa,QAAQ,KAAK;EAEhD,KAAK,MAAM,SAAS,SAClB,KAAK;GAAE,MAAM;GAAc,OAAO,MAAM;GAAM,SAAS,MAAM;EAAQ,CAAC;EAGxE,OAAO;CACT;CAEA,OAAO;EACL,MAAM,OAAO;EAEb;EAEA,MAAM,gBAAiC;GACrC,MAAM,UAAU,MAAM,QAAQ;GAE9B,OAAO,oBAAoB,OAAO,MAAM,OAAO;EACjD;EAEA,MAAM,QAAQ,OAAuC;GACnD,IAAI,CAAC,OAAO,QACV,OAAO,CAAC;GAGV,IAAI,OAAO,WAAW,OAAO;IAC3B,MAAM,UAAU,MAAM,aAAa,QAAQ,KAAK;IAChD,MAAM,UAAyB,CAAC;IAEhC,KAAK,MAAM,SAAS,SAAS;KAC3B,MAAM,SAAS,MAAM,WAAW,QAAQ,MAAM,MAAM,MAAM,OAAO;KAEjE,IAAI,QACF,QAAQ,KAAK,MAAM;IAEvB;IAEA,OAAO;GACT;GAGA,OAAO,kBAAkB,QAAQ,OAAO,OAAO,OAAO,MAAM;IAC1D,UAAU,OAAO,OAAO;IACxB,WAAW,OAAO,OAAO;IACzB;GACF,CAAC;EACH;EAEA,MAAM,OAA4C;GAChD,MAAM,UAAsC,CAC1C,cAAc;IACZ,OAAO,MAAM,YAAY,WAAW,QAAQ,MAAM,OAAO;IACzD;IACA,WAAW,WACT,KAAK;KAAE,MAAM;KAAU,OAAO,OAAO;KAAM,SAAS,OAAO;KAAS;IAAM,CAAC;GAC/E,CAAC,CACH;GAKA,IAAI,iBAAiB,OAAO,QAAQ;IAClC,MAAM,cAAc,OAAO,OAAO;IAElC,QAAQ,KACN,cAAc;KACZ,gBAAgB,WAAW,YAAY,cAAc,MAAM;KAC3D,UAAU,WACR,KAAK;MAAE,MAAM;MAAS,OAAO,OAAO;MAAM,SAAS,OAAO;MAAS;KAAM,CAAC;IAC9E,CAAC,CACH;GACF;GAEA,OAAO;EACT;CACF;AACF"}

package/esm/ai/src/skills/sources/directory-source.mjs

@@ -0,0 +1,108 @@
+import { parseFrontmatter, parseTags } from "./parse-frontmatter.mjs";
+
+//#region ../@warlock.js/ai/src/skills/sources/directory-source.ts
+/**
+* Lazily-loaded `node:fs/promises`. Core takes no new filesystem
+* dependency — a `store`-only or `url`-only consumer never touches the
+* filesystem because the module is imported on first read, not at module
+* load. Settled once and cached.
+*/
+let fsMod;
+let pathMod;
+async function loadFs() {
+	if (!fsMod) fsMod = await import("node:fs/promises");
+	if (!pathMod) pathMod = await import("node:path");
+	return {
+		fs: fsMod,
+		path: pathMod
+	};
+}
+/**
+* Read `path/<folder>/SKILL.md` into {@link SkillRecord}s, parsing the
+* same `key: value` front-matter as `scripts/generate-llms.mjs`. Each
+* direct sub-directory holding a `SKILL.md` becomes one skill named after
+* the folder; the `description` comes from front-matter, `tags` from a
+* comma-separated `tags:` line, and the body is everything after the
+* closing `---`. Files at the root (e.g. `README.md`) are ignored.
+*
+* Reads are a snapshot at first call and cached for the source's lifetime
+* (a single agent run reads the catalog and bodies from one consistent
+* view). A missing directory yields an empty library, not a throw.
+*/
+function directorySource(dirPath) {
+	let cache;
+	const records = () => {
+		if (!cache) cache = readDirectory(dirPath);
+		return cache;
+	};
+	return {
+		async list(scope) {
+			const all = await records();
+			const wanted = scope?.tags;
+			return [...all.values()].filter((record) => intersects(record.tags, wanted)).map(toCatalogEntry);
+		},
+		async load(name, version) {
+			const record = (await records()).get(name);
+			if (!record) return;
+			if (version !== void 0 && record.version !== version) return;
+			return record;
+		},
+		async saveCandidate() {
+			throw new Error("directory source is read-only — saveCandidate requires a writable store (set `review.store`)");
+		},
+		async promote() {
+			throw new Error("directory source is read-only — promote requires a writable store (set `review.store`)");
+		}
+	};
+}
+/** Walk the directory once, parsing every `<folder>/SKILL.md` into a record. */
+async function readDirectory(dirPath) {
+	const { fs, path } = await loadFs();
+	const records = /* @__PURE__ */ new Map();
+	let entries;
+	try {
+		entries = await fs.readdir(dirPath, { withFileTypes: true });
+	} catch {
+		return records;
+	}
+	for (const entry of entries) {
+		if (!entry.isDirectory()) continue;
+		const skillFile = path.join(dirPath, entry.name, "SKILL.md");
+		let text;
+		try {
+			text = await fs.readFile(skillFile, "utf8");
+		} catch {
+			continue;
+		}
+		const { meta, body } = parseFrontmatter(text);
+		records.set(entry.name, {
+			name: entry.name,
+			description: meta.description ?? "(no description)",
+			version: 1,
+			body: body.trim(),
+			tags: parseTags(meta.tags),
+			type: "authored"
+		});
+	}
+	return records;
+}
+/** Project a full record down to its catalog entry (body omitted). */
+function toCatalogEntry(record) {
+	return {
+		name: record.name,
+		description: record.description,
+		version: record.version,
+		tags: record.tags,
+		type: record.type
+	};
+}
+/** True when no filter is requested or the record shares a requested tag. */
+function intersects(recordTags, wanted) {
+	if (!wanted || wanted.length === 0) return true;
+	if (!recordTags || recordTags.length === 0) return false;
+	return recordTags.some((tag) => wanted.includes(tag));
+}
+
+//#endregion
+export { directorySource };
+//# sourceMappingURL=directory-source.mjs.map

package/esm/ai/src/skills/sources/directory-source.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"directory-source.mjs","names":[],"sources":["../../../../../../../../../../@warlock.js/ai/src/skills/sources/directory-source.ts"],"sourcesContent":["import type {\n  SkillCatalogEntry,\n  SkillRecord,\n} from \"../contracts/skill-record.type\";\nimport type { SkillsStoreContract } from \"../contracts/skills-store.contract\";\nimport { parseFrontmatter, parseTags } from \"./parse-frontmatter\";\n\n/**\n * Lazily-loaded `node:fs/promises`. Core takes no new filesystem\n * dependency — a `store`-only or `url`-only consumer never touches the\n * filesystem because the module is imported on first read, not at module\n * load. Settled once and cached.\n */\nlet fsMod: typeof import(\"node:fs/promises\") | undefined;\nlet pathMod: typeof import(\"node:path\") | undefined;\n\nasync function loadFs(): Promise<{\n  fs: typeof import(\"node:fs/promises\");\n  path: typeof import(\"node:path\");\n}> {\n  if (!fsMod) {\n    fsMod = await import(\"node:fs/promises\");\n  }\n\n  if (!pathMod) {\n    pathMod = await import(\"node:path\");\n  }\n\n  return { fs: fsMod, path: pathMod };\n}\n\n/**\n * Read `path/<folder>/SKILL.md` into {@link SkillRecord}s, parsing the\n * same `key: value` front-matter as `scripts/generate-llms.mjs`. Each\n * direct sub-directory holding a `SKILL.md` becomes one skill named after\n * the folder; the `description` comes from front-matter, `tags` from a\n * comma-separated `tags:` line, and the body is everything after the\n * closing `---`. Files at the root (e.g. `README.md`) are ignored.\n *\n * Reads are a snapshot at first call and cached for the source's lifetime\n * (a single agent run reads the catalog and bodies from one consistent\n * view). A missing directory yields an empty library, not a throw.\n */\nexport function directorySource(dirPath: string): SkillsStoreContract {\n  let cache: Promise<Map<string, SkillRecord>> | undefined;\n\n  const records = (): Promise<Map<string, SkillRecord>> => {\n    if (!cache) {\n      cache = readDirectory(dirPath);\n    }\n\n    return cache;\n  };\n\n  return {\n    async list(scope?: { tags?: string[] }): Promise<SkillCatalogEntry[]> {\n      const all = await records();\n      const wanted = scope?.tags;\n\n      return [...all.values()]\n        .filter((record) => intersects(record.tags, wanted))\n        .map(toCatalogEntry);\n    },\n    async load(name: string, version?: number): Promise<SkillRecord | undefined> {\n      const all = await records();\n      const record = all.get(name);\n\n      if (!record) {\n        return undefined;\n      }\n\n      if (version !== undefined && record.version !== version) {\n        return undefined;\n      }\n\n      return record;\n    },\n    async saveCandidate(): Promise<SkillRecord> {\n      throw new Error(\n        \"directory source is read-only — saveCandidate requires a writable store (set `review.store`)\",\n      );\n    },\n    async promote(): Promise<SkillRecord> {\n      throw new Error(\n        \"directory source is read-only — promote requires a writable store (set `review.store`)\",\n      );\n    },\n  };\n}\n\n/** Walk the directory once, parsing every `<folder>/SKILL.md` into a record. */\nasync function readDirectory(dirPath: string): Promise<Map<string, SkillRecord>> {\n  const { fs, path } = await loadFs();\n  const records = new Map<string, SkillRecord>();\n\n  let entries: Array<{ name: string; isDirectory(): boolean }>;\n\n  try {\n    entries = await fs.readdir(dirPath, { withFileTypes: true });\n  } catch {\n    // Missing directory ⇒ empty library; the catalog simply omits it.\n    return records;\n  }\n\n  for (const entry of entries) {\n    if (!entry.isDirectory()) {\n      continue;\n    }\n\n    const skillFile = path.join(dirPath, entry.name, \"SKILL.md\");\n\n    let text: string;\n\n    try {\n      text = await fs.readFile(skillFile, \"utf8\");\n    } catch {\n      // A sub-directory without a SKILL.md is not a skill — skip it.\n      continue;\n    }\n\n    const { meta, body } = parseFrontmatter(text);\n\n    records.set(entry.name, {\n      name: entry.name,\n      description: meta.description ?? \"(no description)\",\n      version: 1,\n      body: body.trim(),\n      tags: parseTags(meta.tags),\n      type: \"authored\",\n    });\n  }\n\n  return records;\n}\n\n/** Project a full record down to its catalog entry (body omitted). */\nfunction toCatalogEntry(record: SkillRecord): SkillCatalogEntry {\n  return {\n    name: record.name,\n    description: record.description,\n    version: record.version,\n    tags: record.tags,\n    type: record.type,\n  };\n}\n\n/** True when no filter is requested or the record shares a requested tag. */\nfunction intersects(recordTags: string[] | undefined, wanted: string[] | undefined): boolean {\n  if (!wanted || wanted.length === 0) {\n    return true;\n  }\n\n  if (!recordTags || recordTags.length === 0) {\n    return false;\n  }\n\n  return recordTags.some((tag) => wanted.includes(tag));\n}\n"],"mappings":";;;;;;;;;AAaA,IAAI;AACJ,IAAI;AAEJ,eAAe,SAGZ;CACD,IAAI,CAAC,OACH,QAAQ,MAAM,OAAO;CAGvB,IAAI,CAAC,SACH,UAAU,MAAM,OAAO;CAGzB,OAAO;EAAE,IAAI;EAAO,MAAM;CAAQ;AACpC;;;;;;;;;;;;;AAcA,SAAgB,gBAAgB,SAAsC;CACpE,IAAI;CAEJ,MAAM,gBAAmD;EACvD,IAAI,CAAC,OACH,QAAQ,cAAc,OAAO;EAG/B,OAAO;CACT;CAEA,OAAO;EACL,MAAM,KAAK,OAA2D;GACpE,MAAM,MAAM,MAAM,QAAQ;GAC1B,MAAM,SAAS,OAAO;GAEtB,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,CAAC,CACrB,QAAQ,WAAW,WAAW,OAAO,MAAM,MAAM,CAAC,CAAC,CACnD,IAAI,cAAc;EACvB;EACA,MAAM,KAAK,MAAc,SAAoD;GAE3E,MAAM,UAAS,MADG,QAAQ,EACR,CAAC,IAAI,IAAI;GAE3B,IAAI,CAAC,QACH;GAGF,IAAI,YAAY,UAAa,OAAO,YAAY,SAC9C;GAGF,OAAO;EACT;EACA,MAAM,gBAAsC;GAC1C,MAAM,IAAI,MACR,8FACF;EACF;EACA,MAAM,UAAgC;GACpC,MAAM,IAAI,MACR,wFACF;EACF;CACF;AACF;;AAGA,eAAe,cAAc,SAAoD;CAC/E,MAAM,EAAE,IAAI,SAAS,MAAM,OAAO;CAClC,MAAM,0BAAU,IAAI,IAAyB;CAE7C,IAAI;CAEJ,IAAI;EACF,UAAU,MAAM,GAAG,QAAQ,SAAS,EAAE,eAAe,KAAK,CAAC;CAC7D,QAAQ;EAEN,OAAO;CACT;CAEA,KAAK,MAAM,SAAS,SAAS;EAC3B,IAAI,CAAC,MAAM,YAAY,GACrB;EAGF,MAAM,YAAY,KAAK,KAAK,SAAS,MAAM,MAAM,UAAU;EAE3D,IAAI;EAEJ,IAAI;GACF,OAAO,MAAM,GAAG,SAAS,WAAW,MAAM;EAC5C,QAAQ;GAEN;EACF;EAEA,MAAM,EAAE,MAAM,SAAS,iBAAiB,IAAI;EAE5C,QAAQ,IAAI,MAAM,MAAM;GACtB,MAAM,MAAM;GACZ,aAAa,KAAK,eAAe;GACjC,SAAS;GACT,MAAM,KAAK,KAAK;GAChB,MAAM,UAAU,KAAK,IAAI;GACzB,MAAM;EACR,CAAC;CACH;CAEA,OAAO;AACT;;AAGA,SAAS,eAAe,QAAwC;CAC9D,OAAO;EACL,MAAM,OAAO;EACb,aAAa,OAAO;EACpB,SAAS,OAAO;EAChB,MAAM,OAAO;EACb,MAAM,OAAO;CACf;AACF;;AAGA,SAAS,WAAW,YAAkC,QAAuC;CAC3F,IAAI,CAAC,UAAU,OAAO,WAAW,GAC/B,OAAO;CAGT,IAAI,CAAC,cAAc,WAAW,WAAW,GACvC,OAAO;CAGT,OAAO,WAAW,MAAM,QAAQ,OAAO,SAAS,GAAG,CAAC;AACtD"}

package/esm/ai/src/skills/sources/index.mjs

@@ -0,0 +1,27 @@
+import { parseFrontmatter, parseTags } from "./parse-frontmatter.mjs";
+import { directorySource } from "./directory-source.mjs";
+import { storeSource } from "./store-source.mjs";
+import { urlSource } from "./url-source.mjs";
+
+//#region ../@warlock.js/ai/src/skills/sources/index.ts
+/**
+* Resolve a declarative {@link SkillSource} into a concrete
+* {@link SkillsStoreContract} reader. Discriminated by `type` (never
+* `kind`): `directory` reads the filesystem, `url` fetches a manifest,
+* `store` passes a store through verbatim.
+*/
+function resolveSource(source) {
+	switch (source.type) {
+		case "directory": return directorySource(source.path);
+		case "url": return urlSource(source.url, {
+			headers: source.headers,
+			policy: source.policy,
+			cacheTtlMs: source.cacheTtlMs
+		});
+		case "store": return storeSource(source.store);
+	}
+}
+
+//#endregion
+export { resolveSource };
+//# sourceMappingURL=index.mjs.map

package/esm/ai/src/skills/sources/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../../../../../../../../../@warlock.js/ai/src/skills/sources/index.ts"],"sourcesContent":["import type { SkillSource } from \"../contracts/skills-config.type\";\nimport type { SkillsStoreContract } from \"../contracts/skills-store.contract\";\nimport { directorySource } from \"./directory-source\";\nimport { storeSource } from \"./store-source\";\nimport { urlSource } from \"./url-source\";\n\nexport { directorySource } from \"./directory-source\";\nexport { urlSource } from \"./url-source\";\nexport { storeSource } from \"./store-source\";\nexport { parseFrontmatter, parseTags } from \"./parse-frontmatter\";\nexport type { ParsedFrontmatter } from \"./parse-frontmatter\";\n\n/**\n * Resolve a declarative {@link SkillSource} into a concrete\n * {@link SkillsStoreContract} reader. Discriminated by `type` (never\n * `kind`): `directory` reads the filesystem, `url` fetches a manifest,\n * `store` passes a store through verbatim.\n */\nexport function resolveSource(source: SkillSource): SkillsStoreContract {\n  switch (source.type) {\n    case \"directory\":\n      return directorySource(source.path);\n    case \"url\":\n      return urlSource(source.url, {\n        headers: source.headers,\n        policy: source.policy,\n        cacheTtlMs: source.cacheTtlMs,\n      });\n    case \"store\":\n      return storeSource(source.store);\n  }\n}\n"],"mappings":";;;;;;;;;;;;AAkBA,SAAgB,cAAc,QAA0C;CACtE,QAAQ,OAAO,MAAf;EACE,KAAK,aACH,OAAO,gBAAgB,OAAO,IAAI;EACpC,KAAK,OACH,OAAO,UAAU,OAAO,KAAK;GAC3B,SAAS,OAAO;GAChB,QAAQ,OAAO;GACf,YAAY,OAAO;EACrB,CAAC;EACH,KAAK,SACH,OAAO,YAAY,OAAO,KAAK;CACnC;AACF"}

package/esm/ai/src/skills/sources/parse-frontmatter.mjs

@@ -0,0 +1,46 @@
+//#region ../@warlock.js/ai/src/skills/sources/parse-frontmatter.ts
+/**
+* Parse simple `key: value` YAML front-matter — the only form `SKILL.md`
+* uses (no nested objects, no block arrays). Ported verbatim from the
+* package's `scripts/generate-llms.mjs` `parseFrontmatter()` so the
+* runtime catalog and the docs `llms.txt` index agree byte-for-byte on
+* what a skill's `description` is.
+*
+* When the text has no `---`-delimited front-matter block, returns an
+* empty `meta` and the full text as `body`.
+*/
+function parseFrontmatter(text) {
+	const match = text.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+	if (!match) return {
+		meta: {},
+		body: text
+	};
+	const meta = {};
+	for (const line of match[1].split("\n")) {
+		const colon = line.indexOf(":");
+		if (colon === -1) continue;
+		const key = line.slice(0, colon).trim();
+		let value = line.slice(colon + 1).trim();
+		if (value.startsWith("'") && value.endsWith("'") || value.startsWith("\"") && value.endsWith("\"")) value = value.slice(1, -1).replace(/''/g, "'").replace(/\\"/g, "\"");
+		meta[key] = value;
+	}
+	return {
+		meta,
+		body: match[2]
+	};
+}
+/**
+* Split a front-matter `tags:` value into a string array. Accepts a
+* comma-separated inline list (`tags: frontend, react`) — the simple
+* inline form that fits the `key: value` parser. Returns `undefined` when
+* the value is absent or blank so a tagless skill stays `tags: undefined`.
+*/
+function parseTags(value) {
+	if (!value) return;
+	const tags = value.split(",").map((tag) => tag.trim()).filter((tag) => tag.length > 0);
+	return tags.length > 0 ? tags : void 0;
+}
+
+//#endregion
+export { parseFrontmatter, parseTags };
+//# sourceMappingURL=parse-frontmatter.mjs.map

package/esm/ai/src/skills/sources/parse-frontmatter.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-frontmatter.mjs","names":[],"sources":["../../../../../../../../../../@warlock.js/ai/src/skills/sources/parse-frontmatter.ts"],"sourcesContent":["/** The parsed front-matter (cheap metadata) plus the stripped body. */\nexport type ParsedFrontmatter = {\n  /** Every `key: value` line from the front-matter block, values quote-stripped. */\n  meta: Record<string, string>;\n  /** Everything after the closing `---`, verbatim (the skill body). */\n  body: string;\n};\n\n/**\n * Parse simple `key: value` YAML front-matter — the only form `SKILL.md`\n * uses (no nested objects, no block arrays). Ported verbatim from the\n * package's `scripts/generate-llms.mjs` `parseFrontmatter()` so the\n * runtime catalog and the docs `llms.txt` index agree byte-for-byte on\n * what a skill's `description` is.\n *\n * When the text has no `---`-delimited front-matter block, returns an\n * empty `meta` and the full text as `body`.\n */\nexport function parseFrontmatter(text: string): ParsedFrontmatter {\n  const match = text.match(/^---\\n([\\s\\S]*?)\\n---\\n([\\s\\S]*)$/);\n\n  if (!match) {\n    return { meta: {}, body: text };\n  }\n\n  const meta: Record<string, string> = {};\n\n  for (const line of match[1].split(\"\\n\")) {\n    const colon = line.indexOf(\":\");\n\n    if (colon === -1) {\n      continue;\n    }\n\n    const key = line.slice(0, colon).trim();\n    let value = line.slice(colon + 1).trim();\n\n    if (\n      (value.startsWith(\"'\") && value.endsWith(\"'\")) ||\n      (value.startsWith('\"') && value.endsWith('\"'))\n    ) {\n      value = value.slice(1, -1).replace(/''/g, \"'\").replace(/\\\\\"/g, '\"');\n    }\n\n    meta[key] = value;\n  }\n\n  return { meta, body: match[2] };\n}\n\n/**\n * Split a front-matter `tags:` value into a string array. Accepts a\n * comma-separated inline list (`tags: frontend, react`) — the simple\n * inline form that fits the `key: value` parser. Returns `undefined` when\n * the value is absent or blank so a tagless skill stays `tags: undefined`.\n */\nexport function parseTags(value: string | undefined): string[] | undefined {\n  if (!value) {\n    return undefined;\n  }\n\n  const tags = value\n    .split(\",\")\n    .map((tag) => tag.trim())\n    .filter((tag) => tag.length > 0);\n\n  return tags.length > 0 ? tags : undefined;\n}\n"],"mappings":";;;;;;;;;;;AAkBA,SAAgB,iBAAiB,MAAiC;CAChE,MAAM,QAAQ,KAAK,MAAM,mCAAmC;CAE5D,IAAI,CAAC,OACH,OAAO;EAAE,MAAM,CAAC;EAAG,MAAM;CAAK;CAGhC,MAAM,OAA+B,CAAC;CAEtC,KAAK,MAAM,QAAQ,MAAM,EAAE,CAAC,MAAM,IAAI,GAAG;EACvC,MAAM,QAAQ,KAAK,QAAQ,GAAG;EAE9B,IAAI,UAAU,IACZ;EAGF,MAAM,MAAM,KAAK,MAAM,GAAG,KAAK,CAAC,CAAC,KAAK;EACtC,IAAI,QAAQ,KAAK,MAAM,QAAQ,CAAC,CAAC,CAAC,KAAK;EAEvC,IACG,MAAM,WAAW,GAAG,KAAK,MAAM,SAAS,GAAG,KAC3C,MAAM,WAAW,IAAG,KAAK,MAAM,SAAS,IAAG,GAE5C,QAAQ,MAAM,MAAM,GAAG,EAAE,CAAC,CAAC,QAAQ,OAAO,GAAG,CAAC,CAAC,QAAQ,QAAQ,IAAG;EAGpE,KAAK,OAAO;CACd;CAEA,OAAO;EAAE;EAAM,MAAM,MAAM;CAAG;AAChC;;;;;;;AAQA,SAAgB,UAAU,OAAiD;CACzE,IAAI,CAAC,OACH;CAGF,MAAM,OAAO,MACV,MAAM,GAAG,CAAC,CACV,KAAK,QAAQ,IAAI,KAAK,CAAC,CAAC,CACxB,QAAQ,QAAQ,IAAI,SAAS,CAAC;CAEjC,OAAO,KAAK,SAAS,IAAI,OAAO;AAClC"}

package/esm/ai/src/skills/sources/store-source.mjs

@@ -0,0 +1,15 @@
+//#region ../@warlock.js/ai/src/skills/sources/store-source.ts
+/**
+* Adapt a `{ type: "store", store }` source — a pass-through to any
+* {@link SkillsStoreContract} (e.g. `MockSkillsStore`, or the Phase-2
+* `ProceduralSkillStore`). The store already implements every reader
+* method, so this is identity; it exists for symmetry with the directory
+* and url sources and to keep `resolveSource` a single dispatch table.
+*/
+function storeSource(store) {
+	return store;
+}
+
+//#endregion
+export { storeSource };
+//# sourceMappingURL=store-source.mjs.map

package/esm/ai/src/skills/sources/store-source.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-source.mjs","names":[],"sources":["../../../../../../../../../../@warlock.js/ai/src/skills/sources/store-source.ts"],"sourcesContent":["import type { SkillsStoreContract } from \"../contracts/skills-store.contract\";\n\n/**\n * Adapt a `{ type: \"store\", store }` source — a pass-through to any\n * {@link SkillsStoreContract} (e.g. `MockSkillsStore`, or the Phase-2\n * `ProceduralSkillStore`). The store already implements every reader\n * method, so this is identity; it exists for symmetry with the directory\n * and url sources and to keep `resolveSource` a single dispatch table.\n */\nexport function storeSource(store: SkillsStoreContract): SkillsStoreContract {\n  return store;\n}\n"],"mappings":";;;;;;;;AASA,SAAgB,YAAY,OAAiD;CAC3E,OAAO;AACT"}

package/esm/ai/src/skills/sources/url-source.mjs

@@ -0,0 +1,117 @@
+import { fetchTextWithPolicy } from "../../security/outbound-policy.mjs";
+
+//#region ../@warlock.js/ai/src/skills/sources/url-source.ts
+/**
+* Read skills from a remote JSON manifest at `url`. The manifest is a flat
+* array of {@link SkillRecord}s (bodies inline).
+*
+* **Trust boundary (S3).** A remote skill source is a prompt supply chain —
+* its bodies flow straight into model context — so the manifest fetch runs
+* through the shared `OutboundPolicy` (scheme + host allowlist, post-DNS
+* private-IP deny, max bytes, timeout) and **every record is runtime-
+* validated** before it can be served. A malformed record fails loudly
+* rather than being cast blindly into a `SkillRecord`.
+*
+* The request is made lazily on the first `list()` / `load()`. The result
+* is cached for the source's lifetime, or for `cacheTtlMs` when set
+* (a stale cache refetches on next access).
+*/
+function urlSource(url, options = {}) {
+	const { headers, policy, cacheTtlMs } = options;
+	let cache;
+	let cachedAtMs;
+	const records = () => {
+		const expired = cacheTtlMs !== void 0 && cachedAtMs !== void 0 && Date.now() - cachedAtMs > cacheTtlMs;
+		if (!cache || expired) {
+			cachedAtMs = Date.now();
+			cache = fetchManifest(url, headers, policy);
+		}
+		return cache;
+	};
+	return {
+		async list(scope) {
+			const all = await records();
+			const wanted = scope?.tags;
+			return [...all.values()].filter((record) => record.type !== "candidate").filter((record) => intersects(record.tags, wanted)).map(toCatalogEntry);
+		},
+		async load(name, version) {
+			const record = (await records()).get(name);
+			if (!record || record.type === "candidate") return;
+			if (version !== void 0 && record.version !== version) return;
+			return record;
+		},
+		async saveCandidate() {
+			throw new Error("url source is read-only — saveCandidate requires a writable store (set `review.store`)");
+		},
+		async promote() {
+			throw new Error("url source is read-only — promote requires a writable store (set `review.store`)");
+		}
+	};
+}
+/** Fetch + validate + parse the manifest once into a name → record map. */
+async function fetchManifest(url, headers, policy) {
+	const result = await fetchTextWithPolicy(url, policy ?? {}, headers ? { headers } : void 0);
+	if (!result.ok) throw new Error(`url skill source failed: ${result.status} ${result.statusText} for ${url}`);
+	let parsed;
+	try {
+		parsed = JSON.parse(result.text);
+	} catch (cause) {
+		throw new Error(`url skill source returned invalid JSON from ${url}`, { cause });
+	}
+	if (!Array.isArray(parsed)) throw new Error(`url skill source at ${url} must return a JSON array of skill records`);
+	const records = /* @__PURE__ */ new Map();
+	parsed.forEach((raw, index) => {
+		const record = validateManifestRecord(raw, url, index);
+		records.set(record.name, record);
+	});
+	return records;
+}
+/**
+* Runtime-validate one manifest record before it is trusted as a
+* {@link SkillRecord}. Untyped remote JSON cast blindly into the context
+* is both an injection surface and a correctness bug; this rejects a
+* record missing the required `name` / `description` / `body` strings, and
+* fills `version` / `type` defaults for a thin record.
+*/
+function validateManifestRecord(raw, url, index) {
+	if (!raw || typeof raw !== "object") throw new Error(`url skill source at ${url}: record #${index} is not an object`);
+	const r = raw;
+	const requireString = (field) => {
+		const value = r[field];
+		if (typeof value !== "string" || value.length === 0) throw new Error(`url skill source at ${url}: record #${index} is missing a string "${field}"`);
+		return value;
+	};
+	const name = requireString("name");
+	const description = requireString("description");
+	const body = requireString("body");
+	const type = r.type === "authored" || r.type === "promoted" || r.type === "candidate" ? r.type : "authored";
+	return {
+		name,
+		description,
+		body,
+		version: typeof r.version === "number" ? r.version : 1,
+		type,
+		tags: Array.isArray(r.tags) ? r.tags.filter((t) => typeof t === "string") : void 0,
+		metadata: r.metadata && typeof r.metadata === "object" ? r.metadata : void 0
+	};
+}
+/** Project a full record down to its catalog entry (body omitted). */
+function toCatalogEntry(record) {
+	return {
+		name: record.name,
+		description: record.description,
+		version: record.version,
+		tags: record.tags,
+		type: record.type
+	};
+}
+/** True when no filter is requested or the record shares a requested tag. */
+function intersects(recordTags, wanted) {
+	if (!wanted || wanted.length === 0) return true;
+	if (!recordTags || recordTags.length === 0) return false;
+	return recordTags.some((tag) => wanted.includes(tag));
+}
+
+//#endregion
+export { urlSource };
+//# sourceMappingURL=url-source.mjs.map

package/esm/ai/src/skills/sources/url-source.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-source.mjs","names":[],"sources":["../../../../../../../../../../@warlock.js/ai/src/skills/sources/url-source.ts"],"sourcesContent":["import { fetchTextWithPolicy } from \"../../security/outbound-policy\";\nimport type { OutboundPolicy } from \"../../security/outbound-policy.type\";\nimport type {\n  SkillCatalogEntry,\n  SkillRecord,\n} from \"../contracts/skill-record.type\";\nimport type { SkillsStoreContract } from \"../contracts/skills-store.contract\";\n\n/**\n * The JSON manifest shape a `url` source fetches — a flat array of skill\n * records. Bodies travel inline; the catalog projection drops them so the\n * always-injected metadata block stays cheap.\n */\ntype SkillManifest = SkillRecord[];\n\n/** Options for {@link urlSource} (S3). */\nexport type UrlSourceOptions = {\n  headers?: Record<string, string>;\n  /** Fetch hardening for the manifest request. */\n  policy?: OutboundPolicy;\n  /** Cache the manifest for this many ms; omit to cache for the source's lifetime. */\n  cacheTtlMs?: number;\n};\n\n/**\n * Read skills from a remote JSON manifest at `url`. The manifest is a flat\n * array of {@link SkillRecord}s (bodies inline).\n *\n * **Trust boundary (S3).** A remote skill source is a prompt supply chain —\n * its bodies flow straight into model context — so the manifest fetch runs\n * through the shared `OutboundPolicy` (scheme + host allowlist, post-DNS\n * private-IP deny, max bytes, timeout) and **every record is runtime-\n * validated** before it can be served. A malformed record fails loudly\n * rather than being cast blindly into a `SkillRecord`.\n *\n * The request is made lazily on the first `list()` / `load()`. The result\n * is cached for the source's lifetime, or for `cacheTtlMs` when set\n * (a stale cache refetches on next access).\n */\nexport function urlSource(\n  url: string,\n  options: UrlSourceOptions = {},\n): SkillsStoreContract {\n  const { headers, policy, cacheTtlMs } = options;\n\n  let cache: Promise<Map<string, SkillRecord>> | undefined;\n  let cachedAtMs: number | undefined;\n\n  const records = (): Promise<Map<string, SkillRecord>> => {\n    const expired =\n      cacheTtlMs !== undefined &&\n      cachedAtMs !== undefined &&\n      Date.now() - cachedAtMs > cacheTtlMs;\n\n    if (!cache || expired) {\n      cachedAtMs = Date.now();\n      cache = fetchManifest(url, headers, policy);\n    }\n\n    return cache;\n  };\n\n  return {\n    async list(scope?: { tags?: string[] }): Promise<SkillCatalogEntry[]> {\n      const all = await records();\n      const wanted = scope?.tags;\n\n      return [...all.values()]\n        .filter(record => record.type !== \"candidate\")\n        .filter(record => intersects(record.tags, wanted))\n        .map(toCatalogEntry);\n    },\n    async load(name: string, version?: number): Promise<SkillRecord | undefined> {\n      const all = await records();\n      const record = all.get(name);\n\n      if (!record || record.type === \"candidate\") {\n        return undefined;\n      }\n\n      if (version !== undefined && record.version !== version) {\n        return undefined;\n      }\n\n      return record;\n    },\n    async saveCandidate(): Promise<SkillRecord> {\n      throw new Error(\n        \"url source is read-only — saveCandidate requires a writable store (set `review.store`)\",\n      );\n    },\n    async promote(): Promise<SkillRecord> {\n      throw new Error(\n        \"url source is read-only — promote requires a writable store (set `review.store`)\",\n      );\n    },\n  };\n}\n\n/** Fetch + validate + parse the manifest once into a name → record map. */\nasync function fetchManifest(\n  url: string,\n  headers: Record<string, string> | undefined,\n  policy: OutboundPolicy | undefined,\n): Promise<Map<string, SkillRecord>> {\n  const result = await fetchTextWithPolicy(\n    url,\n    policy ?? {},\n    headers ? { headers } : undefined,\n  );\n\n  if (!result.ok) {\n    throw new Error(\n      `url skill source failed: ${result.status} ${result.statusText} for ${url}`,\n    );\n  }\n\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(result.text);\n  } catch (cause) {\n    throw new Error(`url skill source returned invalid JSON from ${url}`, {\n      cause,\n    });\n  }\n\n  if (!Array.isArray(parsed)) {\n    throw new Error(\n      `url skill source at ${url} must return a JSON array of skill records`,\n    );\n  }\n\n  const records = new Map<string, SkillRecord>();\n\n  (parsed as SkillManifest).forEach((raw, index) => {\n    const record = validateManifestRecord(raw, url, index);\n    records.set(record.name, record);\n  });\n\n  return records;\n}\n\n/**\n * Runtime-validate one manifest record before it is trusted as a\n * {@link SkillRecord}. Untyped remote JSON cast blindly into the context\n * is both an injection surface and a correctness bug; this rejects a\n * record missing the required `name` / `description` / `body` strings, and\n * fills `version` / `type` defaults for a thin record.\n */\nfunction validateManifestRecord(\n  raw: unknown,\n  url: string,\n  index: number,\n): SkillRecord {\n  if (!raw || typeof raw !== \"object\") {\n    throw new Error(`url skill source at ${url}: record #${index} is not an object`);\n  }\n\n  const r = raw as Record<string, unknown>;\n  const requireString = (field: string): string => {\n    const value = r[field];\n    if (typeof value !== \"string\" || value.length === 0) {\n      throw new Error(\n        `url skill source at ${url}: record #${index} is missing a string \"${field}\"`,\n      );\n    }\n    return value;\n  };\n\n  const name = requireString(\"name\");\n  const description = requireString(\"description\");\n  const body = requireString(\"body\");\n\n  const type =\n    r.type === \"authored\" || r.type === \"promoted\" || r.type === \"candidate\"\n      ? r.type\n      : \"authored\";\n  const version = typeof r.version === \"number\" ? r.version : 1;\n  const tags = Array.isArray(r.tags)\n    ? r.tags.filter((t): t is string => typeof t === \"string\")\n    : undefined;\n  const metadata =\n    r.metadata && typeof r.metadata === \"object\"\n      ? (r.metadata as Record<string, unknown>)\n      : undefined;\n\n  return { name, description, body, version, type, tags, metadata };\n}\n\n/** Project a full record down to its catalog entry (body omitted). */\nfunction toCatalogEntry(record: SkillRecord): SkillCatalogEntry {\n  return {\n    name: record.name,\n    description: record.description,\n    version: record.version,\n    tags: record.tags,\n    type: record.type,\n  };\n}\n\n/** True when no filter is requested or the record shares a requested tag. */\nfunction intersects(recordTags: string[] | undefined, wanted: string[] | undefined): boolean {\n  if (!wanted || wanted.length === 0) {\n    return true;\n  }\n\n  if (!recordTags || recordTags.length === 0) {\n    return false;\n  }\n\n  return recordTags.some(tag => wanted.includes(tag));\n}\n"],"mappings":"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"}

package/esm/ai/src/snapshot/memory.mjs

@@ -0,0 +1,81 @@
+//#region ../@warlock.js/ai/src/snapshot/memory.ts
+/**
+* In-memory {@link SnapshotStore} — supervisor run snapshots held in a
+* process-local `Map`, keyed by `runId`, never persisted to disk.
+*
+* Owns: the `runId` → {@link SupervisorSnapshot} mapping for
+* `iterate: true` mid-turn resume. Does NOT own: durability,
+* cross-process sharing, or TTL eviction — it is the zero-config
+* default for dev, tests, and single-process apps. Reach for
+* `ai.snapshot.pg()` / `ai.snapshot.redis()` (Phase 2) when a crashed
+* process must resume an in-flight turn.
+*
+* Front it with the {@link memory} factory — callers never `new` it.
+*/
+var MemorySnapshotStore = class {
+	constructor() {
+		this.snapshots = /* @__PURE__ */ new Map();
+	}
+	/**
+	* Return the snapshot for a `runId`, or `undefined` when no in-flight
+	* run is recorded.
+	*/
+	async load(runId) {
+		return this.snapshots.get(runId);
+	}
+	/**
+	* Persist a snapshot, keyed by its own `runId`. Overwrites any prior
+	* snapshot for the same run — a run has exactly one live snapshot.
+	*/
+	async save(snapshot) {
+		this.snapshots.set(snapshot.runId, snapshot);
+	}
+	/**
+	* Drop the snapshot for a `runId`.
+	*/
+	async delete(runId) {
+		this.snapshots.delete(runId);
+	}
+	/**
+	* List the known run ids, optionally filtered by a prefix.
+	*/
+	async list(prefix) {
+		const runIds = [];
+		for (const runId of this.snapshots.keys()) {
+			if (prefix !== void 0 && !runId.startsWith(prefix)) continue;
+			runIds.push(runId);
+		}
+		return runIds;
+	}
+	/**
+	* The memory store has no backing table — there is nothing to
+	* migrate. Returns an empty string so callers can treat `schema()`
+	* uniformly across drivers.
+	*/
+	schema() {
+		return "";
+	}
+};
+/**
+* Create an in-memory {@link SnapshotStore}. Zero-config — no client,
+* no connection. Suitable for dev, tests, and single-process apps that
+* don't need to resume an interrupted `iterate: true` turn across
+* restarts.
+*
+* @example
+* import { ai } from "@warlock.js/ai";
+*
+* const orchestrator = ai.orchestrator({
+*   name: "support",
+*   intents: { ... },
+*   iterate: true,
+*   snapshotStore: ai.snapshot.memory(),
+* });
+*/
+function memory() {
+	return new MemorySnapshotStore();
+}
+
+//#endregion
+export { memory };
+//# sourceMappingURL=memory.mjs.map

package/esm/ai/src/snapshot/memory.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/snapshot/memory.ts"],"sourcesContent":["import type { SnapshotStore } from \"../contracts/orchestrator/snapshot-store.contract\";\nimport type { SupervisorSnapshot } from \"../contracts/supervisor/supervisor-snapshot.type\";\n\n/**\n * In-memory {@link SnapshotStore} — supervisor run snapshots held in a\n * process-local `Map`, keyed by `runId`, never persisted to disk.\n *\n * Owns: the `runId` → {@link SupervisorSnapshot} mapping for\n * `iterate: true` mid-turn resume. Does NOT own: durability,\n * cross-process sharing, or TTL eviction — it is the zero-config\n * default for dev, tests, and single-process apps. Reach for\n * `ai.snapshot.pg()` / `ai.snapshot.redis()` (Phase 2) when a crashed\n * process must resume an in-flight turn.\n *\n * Front it with the {@link memory} factory — callers never `new` it.\n */\nclass MemorySnapshotStore<TSnapshot extends { runId: string }>\n  implements SnapshotStore<TSnapshot>\n{\n  /** Snapshots keyed by `runId`. */\n  private readonly snapshots = new Map<string, TSnapshot>();\n\n  /**\n   * Return the snapshot for a `runId`, or `undefined` when no in-flight\n   * run is recorded.\n   */\n  public async load(runId: string): Promise<TSnapshot | undefined> {\n    return this.snapshots.get(runId);\n  }\n\n  /**\n   * Persist a snapshot, keyed by its own `runId`. Overwrites any prior\n   * snapshot for the same run — a run has exactly one live snapshot.\n   */\n  public async save(snapshot: TSnapshot): Promise<void> {\n    this.snapshots.set(snapshot.runId, snapshot);\n  }\n\n  /**\n   * Drop the snapshot for a `runId`.\n   */\n  public async delete(runId: string): Promise<void> {\n    this.snapshots.delete(runId);\n  }\n\n  /**\n   * List the known run ids, optionally filtered by a prefix.\n   */\n  public async list(prefix?: string): Promise<string[]> {\n    const runIds: string[] = [];\n\n    for (const runId of this.snapshots.keys()) {\n      if (prefix !== undefined && !runId.startsWith(prefix)) {\n        continue;\n      }\n\n      runIds.push(runId);\n    }\n\n    return runIds;\n  }\n\n  /**\n   * The memory store has no backing table — there is nothing to\n   * migrate. Returns an empty string so callers can treat `schema()`\n   * uniformly across drivers.\n   */\n  public schema(): string {\n    return \"\";\n  }\n}\n\n/**\n * Create an in-memory {@link SnapshotStore}. Zero-config — no client,\n * no connection. Suitable for dev, tests, and single-process apps that\n * don't need to resume an interrupted `iterate: true` turn across\n * restarts.\n *\n * @example\n * import { ai } from \"@warlock.js/ai\";\n *\n * const orchestrator = ai.orchestrator({\n *   name: \"support\",\n *   intents: { ... },\n *   iterate: true,\n *   snapshotStore: ai.snapshot.memory(),\n * });\n */\nexport function memory<\n  TSnapshot extends { runId: string } = SupervisorSnapshot,\n>(): SnapshotStore<TSnapshot> {\n  return new MemorySnapshotStore<TSnapshot>();\n}\n"],"mappings":";;;;;;;;;;;;;;AAgBA,IAAM,sBAAN,MAEA;;mCAE+B,IAAI,IAAuB;;;;;;CAMxD,MAAa,KAAK,OAA+C;EAC/D,OAAO,KAAK,UAAU,IAAI,KAAK;CACjC;;;;;CAMA,MAAa,KAAK,UAAoC;EACpD,KAAK,UAAU,IAAI,SAAS,OAAO,QAAQ;CAC7C;;;;CAKA,MAAa,OAAO,OAA8B;EAChD,KAAK,UAAU,OAAO,KAAK;CAC7B;;;;CAKA,MAAa,KAAK,QAAoC;EACpD,MAAM,SAAmB,CAAC;EAE1B,KAAK,MAAM,SAAS,KAAK,UAAU,KAAK,GAAG;GACzC,IAAI,WAAW,UAAa,CAAC,MAAM,WAAW,MAAM,GAClD;GAGF,OAAO,KAAK,KAAK;EACnB;EAEA,OAAO;CACT;;;;;;CAOA,AAAO,SAAiB;EACtB,OAAO;CACT;AACF;;;;;;;;;;;;;;;;;AAkBA,SAAgB,SAEc;CAC5B,OAAO,IAAI,oBAA+B;AAC5C"}