@warlock.js/ai 4.3.0 → 4.5.0

package/esm/skills/save-skill-tool.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"save-skill-tool.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/skills/save-skill-tool.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport type { ToolContract } from \"../tool/tool\";\nimport { tool } from \"../tool/tool\";\nimport type { SkillRecord } from \"./contracts/skill-record.type\";\n\n/** Validated input of the `saveSkill` tool. */\nexport type SaveSkillInput = {\n  name: string;\n  description: string;\n  body: string;\n  tags?: string[];\n};\n\n/** Result the `saveSkill` tool feeds back to the model. */\nexport type SaveSkillResult =\n  | { saved: true; name: string; status: \"candidate\" }\n  | { error: string };\n\n/**\n * Hand-built Standard Schema for the `saveSkill` input — dependency-free,\n * mirroring `loadSkillSchema`. Requires `name` / `description` / `body`;\n * `tags` is an optional string array.\n */\nfunction saveSkillSchema(): StandardSchemaV1<SaveSkillInput> {\n  return {\n    \"~standard\": {\n      version: 1,\n      vendor: \"warlock-ai-skills\",\n      validate: (value: unknown) => {\n        const candidate = value as\n          | { name?: unknown; description?: unknown; body?: unknown; tags?: unknown }\n          | null;\n\n        if (\n          !candidate ||\n          typeof candidate.name !== \"string\" ||\n          typeof candidate.description !== \"string\" ||\n          typeof candidate.body !== \"string\"\n        ) {\n          return {\n            issues: [\n              {\n                message:\n                  \"saveSkill input must be { name: string; description: string; body: string; tags?: string[] }\",\n              },\n            ],\n          };\n        }\n\n        if (\n          candidate.tags !== undefined &&\n          (!Array.isArray(candidate.tags) ||\n            !candidate.tags.every((tag) => typeof tag === \"string\"))\n        ) {\n          return { issues: [{ message: \"saveSkill `tags` must be a string[] when provided\" }] };\n        }\n\n        return {\n          value: {\n            name: candidate.name,\n            description: candidate.description,\n            body: candidate.body,\n            ...(candidate.tags !== undefined ? { tags: candidate.tags as string[] } : {}),\n          },\n        };\n      },\n    },\n  };\n}\n\n/** Dependencies the `saveSkill` tool closes over. */\nexport type SaveSkillToolDeps = {\n  /** Write an INERT candidate; the returned record is `type: \"candidate\"`. */\n  saveCandidate: (record: Omit<SkillRecord, \"version\" | \"type\">) => Promise<SkillRecord>;\n  /** Fired on a successful save (`type: \"saved\"`); errors swallowed by the sink wrapper. */\n  onSaved?: (record: SkillRecord) => void;\n};\n\n/**\n * Build the **Phase 2** `saveSkill` tool — exposed ONLY when a `review`\n * gate is configured. It writes an INERT `type: \"candidate\"` record via\n * `saveCandidate`. A candidate is filtered out of the catalog and from\n * preload — it can NEVER be injected until the default-DENY review gate\n * promotes it. So `saveSkill` alone can never turn the model's own output\n * into an injected instruction; promotion is a separate, gated step.\n *\n * `execute` never throws — a store write failure surfaces as an error\n * result so the run continues.\n */\nexport function saveSkillTool(deps: SaveSkillToolDeps): ToolContract<SaveSkillInput, SaveSkillResult> {\n  return tool<SaveSkillInput, SaveSkillResult>({\n    name: \"saveSkill\",\n    description:\n      \"Propose a new reusable skill. The skill is saved as an INERT candidate and is NOT used until a reviewer approves it — it will not affect the current run.\",\n    input: saveSkillSchema(),\n    execute: async (input) => {\n      try {\n        const record = await deps.saveCandidate({\n          name: input.name,\n          description: input.description,\n          body: input.body,\n          ...(input.tags !== undefined ? { tags: input.tags } : {}),\n        });\n\n        deps.onSaved?.(record);\n\n        return { saved: true, name: record.name, status: \"candidate\" };\n      } catch (error) {\n        return { error: error instanceof Error ? error.message : String(error) };\n      }\n    },\n  });\n}\n"],"mappings":";;;;;;;;AAuBA,SAAS,kBAAoD;CAC3D,OAAO,EACL,aAAa;EACX,SAAS;EACT,QAAQ;EACR,WAAW,UAAmB;GAC5B,MAAM,YAAY;GAIlB,IACE,CAAC,aACD,OAAO,UAAU,SAAS,YAC1B,OAAO,UAAU,gBAAgB,YACjC,OAAO,UAAU,SAAS,UAE1B,OAAO,EACL,QAAQ,CACN,EACE,SACE,+FACJ,CACF,EACF;GAGF,IACE,UAAU,SAAS,WAClB,CAAC,MAAM,QAAQ,UAAU,IAAI,KAC5B,CAAC,UAAU,KAAK,OAAO,QAAQ,OAAO,QAAQ,QAAQ,IAExD,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS,oDAAoD,CAAC,EAAE;GAGtF,OAAO,EACL,OAAO;IACL,MAAM,UAAU;IAChB,aAAa,UAAU;IACvB,MAAM,UAAU;IAChB,GAAI,UAAU,SAAS,SAAY,EAAE,MAAM,UAAU,KAAiB,IAAI,CAAC;GAC7E,EACF;EACF;CACF,EACF;AACF;;;;;;;;;;;;AAqBA,SAAgB,cAAc,MAAwE;CACpG,OAAO,KAAsC;EAC3C,MAAM;EACN,aACE;EACF,OAAO,gBAAgB;EACvB,SAAS,OAAO,UAAU;GACxB,IAAI;IACF,MAAM,SAAS,MAAM,KAAK,cAAc;KACtC,MAAM,MAAM;KACZ,aAAa,MAAM;KACnB,MAAM,MAAM;KACZ,GAAI,MAAM,SAAS,SAAY,EAAE,MAAM,MAAM,KAAK,IAAI,CAAC;IACzD,CAAC;IAED,KAAK,UAAU,MAAM;IAErB,OAAO;KAAE,OAAO;KAAM,MAAM,OAAO;KAAM,QAAQ;IAAY;GAC/D,SAAS,OAAO;IACd,OAAO,EAAE,OAAO,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,EAAE;GACzE;EACF;CACF,CAAC;AACH"}

package/esm/skills/skills.d.mts

@@ -0,0 +1,33 @@
+import { SkillsConfig } from "./contracts/skills-config.type.mjs";
+import { SkillsContract } from "./contracts/skills.contract.mjs";
+
+//#region ../@warlock.js/ai/src/skills/skills.d.ts
+/**
+ * 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"] },
+ * });
+ */
+declare function skills(config: SkillsConfig): SkillsContract;
+//#endregion
+export { skills };
+//# sourceMappingURL=skills.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"skills.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/skills/skills.ts"],"mappings":";;;;;;AAgDA;;;;;;;;AAA4D;;;;;;;;;;;;;;;iBAA5C,MAAA,CAAO,MAAA,EAAQ,YAAA,GAAe,cAAc"}

package/esm/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/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/skills/sources/directory-source.d.mts

@@ -0,0 +1,19 @@
+import { SkillsStoreContract } from "../contracts/skills-store.contract.mjs";
+
+//#region ../@warlock.js/ai/src/skills/sources/directory-source.d.ts
+/**
+ * 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.
+ */
+declare function directorySource(dirPath: string): SkillsStoreContract;
+//#endregion
+export { directorySource };
+//# sourceMappingURL=directory-source.d.mts.map

package/esm/skills/sources/directory-source.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directory-source.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/skills/sources/directory-source.ts"],"mappings":";;;;;AA2CA;;;;AAAqE;;;;;;iBAArD,eAAA,CAAgB,OAAA,WAAkB,mBAAmB"}

package/esm/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/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/skills/sources/index.d.mts

@@ -0,0 +1,18 @@
+import { SkillsStoreContract } from "../contracts/skills-store.contract.mjs";
+import { SkillSource } from "../contracts/skills-config.type.mjs";
+import { directorySource } from "./directory-source.mjs";
+import { urlSource } from "./url-source.mjs";
+import { storeSource } from "./store-source.mjs";
+import { ParsedFrontmatter, parseFrontmatter, parseTags } from "./parse-frontmatter.mjs";
+
+//#region ../@warlock.js/ai/src/skills/sources/index.d.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.
+ */
+declare function resolveSource(source: SkillSource): SkillsStoreContract;
+//#endregion
+export { resolveSource };
+//# sourceMappingURL=index.d.mts.map

package/esm/skills/sources/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/skills/sources/index.ts"],"mappings":";;;;;;;;;AAkBA;;;;;iBAAgB,aAAA,CAAc,MAAA,EAAQ,WAAA,GAAc,mBAAmB"}

package/esm/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/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/skills/sources/parse-frontmatter.d.mts

@@ -0,0 +1,27 @@
+//#region ../@warlock.js/ai/src/skills/sources/parse-frontmatter.d.ts
+/** The parsed front-matter (cheap metadata) plus the stripped body. */
+type ParsedFrontmatter = {
+  /** Every `key: value` line from the front-matter block, values quote-stripped. */meta: Record<string, string>; /** Everything after the closing `---`, verbatim (the skill body). */
+  body: string;
+};
+/**
+ * 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`.
+ */
+declare function parseFrontmatter(text: string): ParsedFrontmatter;
+/**
+ * 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`.
+ */
+declare function parseTags(value: string | undefined): string[] | undefined;
+//#endregion
+export { ParsedFrontmatter, parseFrontmatter, parseTags };
+//# sourceMappingURL=parse-frontmatter.d.mts.map

package/esm/skills/sources/parse-frontmatter.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-frontmatter.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/skills/sources/parse-frontmatter.ts"],"mappings":";;KACY,iBAAA;EAAiB,kFAE3B,IAAA,EAAM,MAAM,kBAAA;EAEZ,IAAA;AAAA;;;AAAI;AAaN;;;;AAAiE;AAsCjE;;iBAtCgB,gBAAA,CAAiB,IAAA,WAAe,iBAAiB;;AAsCd;;;;;iBAAnC,SAAA,CAAU,KAAyB"}

package/esm/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/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/skills/sources/store-source.d.mts

@@ -0,0 +1,14 @@
+import { SkillsStoreContract } from "../contracts/skills-store.contract.mjs";
+
+//#region ../@warlock.js/ai/src/skills/sources/store-source.d.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.
+ */
+declare function storeSource(store: SkillsStoreContract): SkillsStoreContract;
+//#endregion
+export { storeSource };
+//# sourceMappingURL=store-source.d.mts.map

package/esm/skills/sources/store-source.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-source.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/skills/sources/store-source.ts"],"mappings":";;;;;AASA;;;;;iBAAgB,WAAA,CAAY,KAAA,EAAO,mBAAA,GAAsB,mBAAmB"}

package/esm/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/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/skills/sources/url-source.d.mts

@@ -0,0 +1,29 @@
+import { OutboundPolicy } from "../../security/outbound-policy.type.mjs";
+import { SkillsStoreContract } from "../contracts/skills-store.contract.mjs";
+
+//#region ../@warlock.js/ai/src/skills/sources/url-source.d.ts
+/** Options for {@link urlSource} (S3). */
+type UrlSourceOptions = {
+  headers?: Record<string, string>; /** Fetch hardening for the manifest request. */
+  policy?: OutboundPolicy; /** Cache the manifest for this many ms; omit to cache for the source's lifetime. */
+  cacheTtlMs?: number;
+};
+/**
+ * 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).
+ */
+declare function urlSource(url: string, options?: UrlSourceOptions): SkillsStoreContract;
+//#endregion
+export { urlSource };
+//# sourceMappingURL=url-source.d.mts.map

package/esm/skills/sources/url-source.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-source.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/skills/sources/url-source.ts"],"mappings":";;;;;KAgBY,gBAAA;EACV,OAAA,GAAU,MAAA,kBADgB;EAG1B,MAAA,GAAS,cAAc,EAAA;EAEvB,UAAA;AAAA;;;;;AAAU;AAkBZ;;;;;;;;;AAGsB;iBAHN,SAAA,CACd,GAAA,UACA,OAAA,GAAS,gBAAA,GACR,mBAAmB"}