@graphorin/skills 0.5.0

package/dist/migration/index.js

@@ -0,0 +1,131 @@
+import { SkillManifestParseError } from "../errors/index.js";
+import { getSpecSnapshot } from "../spec/index.js";
+import { splitSkillMd } from "../frontmatter/index.js";
+import { parse, stringify } from "yaml";
+
+//#region src/migration/index.ts
+/**
+* `migrate-frontmatter` — idempotent rewrite helper that migrates
+* legacy `graphorin-*` frontmatter fields onto their upstream
+* equivalents per the `deprecate-graphorin-prefix` mappings recorded
+* in the bundled spec snapshot.
+*
+* The function is dry-run by default — callers must opt in to
+* persisting the rewritten bytes. The CLI binary in Phase 15 wraps
+* this surface; the library is exposed here so other tooling can
+* reuse it.
+*
+* @packageDocumentation
+*/
+/**
+* Migrate the bundled `deprecate-graphorin-prefix` mappings on a
+* single SKILL.md. The function is idempotent: re-running it on an
+* already-migrated SKILL.md returns `changed: false` and an empty
+* `rewrites` array.
+*
+* @stable
+*/
+function migrateFrontmatter(skillMd, options = {}) {
+	const skillId = options.skillId ?? "<inline>";
+	const apply = options.apply ?? false;
+	const split = splitSkillMd(skillMd);
+	let frontmatter;
+	try {
+		frontmatter = parse(split.frontmatter);
+	} catch (err) {
+		throw new SkillManifestParseError(`Skill '${skillId}' frontmatter is not valid YAML.`, { cause: err });
+	}
+	if (frontmatter === null || typeof frontmatter !== "object" || Array.isArray(frontmatter)) throw new SkillManifestParseError(`Skill '${skillId}' frontmatter must be a top-level object.`);
+	const fm = { ...frontmatter };
+	const snapshot = getSpecSnapshot();
+	const rewrites = [];
+	let mutated = false;
+	for (const [graphorinField, mapping] of Object.entries(snapshot.graphorinMapping)) {
+		if (!(graphorinField in fm)) continue;
+		if (mapping.policy !== "deprecate-graphorin-prefix") {
+			rewrites.push(Object.freeze({
+				fromField: graphorinField,
+				toField: graphorinField,
+				reason: mapping.policy === "co-exist" ? "co-exist-noop" : "graphorin-only-noop",
+				applied: false
+			}));
+			continue;
+		}
+		if (mapping.anthropicEquivalent === null) {
+			rewrites.push(Object.freeze({
+				fromField: graphorinField,
+				toField: graphorinField,
+				reason: "graphorin-only-noop",
+				applied: false
+			}));
+			continue;
+		}
+		if (mapping.anthropicEquivalent in fm) {
+			rewrites.push(Object.freeze({
+				fromField: graphorinField,
+				toField: mapping.anthropicEquivalent,
+				reason: "deprecate-graphorin-prefix",
+				applied: false
+			}));
+			continue;
+		}
+		if (apply) {
+			fm[mapping.anthropicEquivalent] = fm[graphorinField];
+			delete fm[graphorinField];
+			mutated = true;
+		}
+		rewrites.push(Object.freeze({
+			fromField: graphorinField,
+			toField: mapping.anthropicEquivalent,
+			reason: "deprecate-graphorin-prefix",
+			applied: apply
+		}));
+	}
+	if (!apply || !mutated) return Object.freeze({
+		skillId,
+		rewrites: Object.freeze(rewrites),
+		originalSkillMd: skillMd,
+		migratedSkillMd: skillMd,
+		changed: false
+	});
+	const migratedSkillMd = `---\n${stringify(sortKeysAnthropicFirst(fm), {
+		sortMapEntries: false,
+		lineWidth: 0
+	}).trimEnd()}\n---\n${split.body}`;
+	return Object.freeze({
+		skillId,
+		rewrites: Object.freeze(rewrites),
+		originalSkillMd: skillMd,
+		migratedSkillMd,
+		changed: true
+	});
+}
+/**
+* Stable key ordering: Anthropic-base fields first (in their snapshot
+* insertion order), then the `metadata` bucket, then the
+* `graphorin-*` fields, then anything else. The migrator emits in
+* this order so re-running the migrator on the same input yields
+* identical bytes (idempotence).
+*
+* @stable
+*/
+function sortKeysAnthropicFirst(frontmatter) {
+	const snapshot = getSpecSnapshot();
+	const baseKeys = Object.keys(snapshot.knownFields);
+	const out = {};
+	for (const key of baseKeys) if (key in frontmatter) out[key] = frontmatter[key];
+	if ("metadata" in frontmatter) out.metadata = frontmatter.metadata;
+	const remaining = Object.keys(frontmatter).filter((k) => !(k in out)).sort((a, b) => {
+		const aGraphorin = a.startsWith("graphorin-");
+		const bGraphorin = b.startsWith("graphorin-");
+		if (aGraphorin && !bGraphorin) return 1;
+		if (!aGraphorin && bGraphorin) return -1;
+		return a < b ? -1 : a > b ? 1 : 0;
+	});
+	for (const key of remaining) out[key] = frontmatter[key];
+	return out;
+}
+
+//#endregion
+export { migrateFrontmatter, sortKeysAnthropicFirst };
+//# sourceMappingURL=index.js.map

package/dist/migration/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["frontmatter: unknown","parseYaml","rewrites: MigrationRewrite[]","stringifyYaml","out: Record<string, unknown>"],"sources":["../../src/migration/index.ts"],"sourcesContent":["/**\n * `migrate-frontmatter` — idempotent rewrite helper that migrates\n * legacy `graphorin-*` frontmatter fields onto their upstream\n * equivalents per the `deprecate-graphorin-prefix` mappings recorded\n * in the bundled spec snapshot.\n *\n * The function is dry-run by default — callers must opt in to\n * persisting the rewritten bytes. The CLI binary in Phase 15 wraps\n * this surface; the library is exposed here so other tooling can\n * reuse it.\n *\n * @packageDocumentation\n */\n\nimport { parse as parseYaml, stringify as stringifyYaml } from 'yaml';\n\nimport { SkillManifestParseError } from '../errors/index.js';\nimport { splitSkillMd } from '../frontmatter/index.js';\nimport { getSpecSnapshot } from '../spec/index.js';\n\n/** A single rewrite the migrator applied (or would apply in a dry-run). */\nexport interface MigrationRewrite {\n  readonly fromField: string;\n  readonly toField: string;\n  readonly reason: 'deprecate-graphorin-prefix' | 'co-exist-noop' | 'graphorin-only-noop';\n  readonly applied: boolean;\n}\n\n/** Result of a single SKILL.md migration. */\nexport interface MigrationResult {\n  readonly skillId: string;\n  readonly rewrites: ReadonlyArray<MigrationRewrite>;\n  readonly originalSkillMd: string;\n  readonly migratedSkillMd: string;\n  readonly changed: boolean;\n}\n\n/** Options accepted by {@link migrateFrontmatter}. */\nexport interface MigrateFrontmatterOptions {\n  /** Identifier used in audit / error messages. Defaults to `'<inline>'`. */\n  readonly skillId?: string;\n  /**\n   * When `true`, rewrites are applied to the returned `migratedSkillMd`.\n   * When `false` (default), `migratedSkillMd === originalSkillMd` and\n   * the function operates as a dry-run report.\n   */\n  readonly apply?: boolean;\n}\n\n/**\n * Migrate the bundled `deprecate-graphorin-prefix` mappings on a\n * single SKILL.md. The function is idempotent: re-running it on an\n * already-migrated SKILL.md returns `changed: false` and an empty\n * `rewrites` array.\n *\n * @stable\n */\nexport function migrateFrontmatter(\n  skillMd: string,\n  options: MigrateFrontmatterOptions = {},\n): MigrationResult {\n  const skillId = options.skillId ?? '<inline>';\n  const apply = options.apply ?? false;\n  const split = splitSkillMd(skillMd);\n  let frontmatter: unknown;\n  try {\n    frontmatter = parseYaml(split.frontmatter);\n  } catch (err) {\n    throw new SkillManifestParseError(`Skill '${skillId}' frontmatter is not valid YAML.`, {\n      cause: err,\n    });\n  }\n  if (frontmatter === null || typeof frontmatter !== 'object' || Array.isArray(frontmatter)) {\n    throw new SkillManifestParseError(`Skill '${skillId}' frontmatter must be a top-level object.`);\n  }\n  const fm = { ...(frontmatter as Record<string, unknown>) };\n\n  const snapshot = getSpecSnapshot();\n  const rewrites: MigrationRewrite[] = [];\n  let mutated = false;\n\n  for (const [graphorinField, mapping] of Object.entries(snapshot.graphorinMapping)) {\n    if (!(graphorinField in fm)) continue;\n    if (mapping.policy !== 'deprecate-graphorin-prefix') {\n      rewrites.push(\n        Object.freeze({\n          fromField: graphorinField,\n          toField: graphorinField,\n          reason: mapping.policy === 'co-exist' ? 'co-exist-noop' : 'graphorin-only-noop',\n          applied: false,\n        }),\n      );\n      continue;\n    }\n    if (mapping.anthropicEquivalent === null) {\n      rewrites.push(\n        Object.freeze({\n          fromField: graphorinField,\n          toField: graphorinField,\n          reason: 'graphorin-only-noop',\n          applied: false,\n        }),\n      );\n      continue;\n    }\n    if (mapping.anthropicEquivalent in fm) {\n      // Both fields are already set — the validator will surface the\n      // diagnostic at load time. The migrator does not silently drop\n      // either side; the operator is expected to remove the redundant\n      // `graphorin-*` field manually after reviewing the diagnostic.\n      rewrites.push(\n        Object.freeze({\n          fromField: graphorinField,\n          toField: mapping.anthropicEquivalent,\n          reason: 'deprecate-graphorin-prefix',\n          applied: false,\n        }),\n      );\n      continue;\n    }\n    if (apply) {\n      fm[mapping.anthropicEquivalent] = fm[graphorinField];\n      delete fm[graphorinField];\n      mutated = true;\n    }\n    rewrites.push(\n      Object.freeze({\n        fromField: graphorinField,\n        toField: mapping.anthropicEquivalent,\n        reason: 'deprecate-graphorin-prefix',\n        applied: apply,\n      }),\n    );\n  }\n\n  if (!apply || !mutated) {\n    return Object.freeze({\n      skillId,\n      rewrites: Object.freeze(rewrites),\n      originalSkillMd: skillMd,\n      migratedSkillMd: skillMd,\n      changed: false,\n    });\n  }\n\n  const sortedFm = sortKeysAnthropicFirst(fm);\n  const migratedFrontmatter = stringifyYaml(sortedFm, {\n    sortMapEntries: false,\n    lineWidth: 0,\n  }).trimEnd();\n  const migratedSkillMd = `---\\n${migratedFrontmatter}\\n---\\n${split.body}`;\n\n  return Object.freeze({\n    skillId,\n    rewrites: Object.freeze(rewrites),\n    originalSkillMd: skillMd,\n    migratedSkillMd,\n    changed: true,\n  });\n}\n\n/**\n * Stable key ordering: Anthropic-base fields first (in their snapshot\n * insertion order), then the `metadata` bucket, then the\n * `graphorin-*` fields, then anything else. The migrator emits in\n * this order so re-running the migrator on the same input yields\n * identical bytes (idempotence).\n *\n * @stable\n */\nexport function sortKeysAnthropicFirst(\n  frontmatter: Record<string, unknown>,\n): Record<string, unknown> {\n  const snapshot = getSpecSnapshot();\n  const baseKeys = Object.keys(snapshot.knownFields);\n  const out: Record<string, unknown> = {};\n  for (const key of baseKeys) {\n    if (key in frontmatter) out[key] = frontmatter[key];\n  }\n  if ('metadata' in frontmatter) out.metadata = frontmatter.metadata;\n  const remaining = Object.keys(frontmatter)\n    .filter((k) => !(k in out))\n    .sort((a, b) => {\n      const aGraphorin = a.startsWith('graphorin-');\n      const bGraphorin = b.startsWith('graphorin-');\n      if (aGraphorin && !bGraphorin) return 1;\n      if (!aGraphorin && bGraphorin) return -1;\n      return a < b ? -1 : a > b ? 1 : 0;\n    });\n  for (const key of remaining) out[key] = frontmatter[key];\n  return out;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AAyDA,SAAgB,mBACd,SACA,UAAqC,EAAE,EACtB;CACjB,MAAM,UAAU,QAAQ,WAAW;CACnC,MAAM,QAAQ,QAAQ,SAAS;CAC/B,MAAM,QAAQ,aAAa,QAAQ;CACnC,IAAIA;AACJ,KAAI;AACF,gBAAcC,MAAU,MAAM,YAAY;UACnC,KAAK;AACZ,QAAM,IAAI,wBAAwB,UAAU,QAAQ,mCAAmC,EACrF,OAAO,KACR,CAAC;;AAEJ,KAAI,gBAAgB,QAAQ,OAAO,gBAAgB,YAAY,MAAM,QAAQ,YAAY,CACvF,OAAM,IAAI,wBAAwB,UAAU,QAAQ,2CAA2C;CAEjG,MAAM,KAAK,EAAE,GAAI,aAAyC;CAE1D,MAAM,WAAW,iBAAiB;CAClC,MAAMC,WAA+B,EAAE;CACvC,IAAI,UAAU;AAEd,MAAK,MAAM,CAAC,gBAAgB,YAAY,OAAO,QAAQ,SAAS,iBAAiB,EAAE;AACjF,MAAI,EAAE,kBAAkB,IAAK;AAC7B,MAAI,QAAQ,WAAW,8BAA8B;AACnD,YAAS,KACP,OAAO,OAAO;IACZ,WAAW;IACX,SAAS;IACT,QAAQ,QAAQ,WAAW,aAAa,kBAAkB;IAC1D,SAAS;IACV,CAAC,CACH;AACD;;AAEF,MAAI,QAAQ,wBAAwB,MAAM;AACxC,YAAS,KACP,OAAO,OAAO;IACZ,WAAW;IACX,SAAS;IACT,QAAQ;IACR,SAAS;IACV,CAAC,CACH;AACD;;AAEF,MAAI,QAAQ,uBAAuB,IAAI;AAKrC,YAAS,KACP,OAAO,OAAO;IACZ,WAAW;IACX,SAAS,QAAQ;IACjB,QAAQ;IACR,SAAS;IACV,CAAC,CACH;AACD;;AAEF,MAAI,OAAO;AACT,MAAG,QAAQ,uBAAuB,GAAG;AACrC,UAAO,GAAG;AACV,aAAU;;AAEZ,WAAS,KACP,OAAO,OAAO;GACZ,WAAW;GACX,SAAS,QAAQ;GACjB,QAAQ;GACR,SAAS;GACV,CAAC,CACH;;AAGH,KAAI,CAAC,SAAS,CAAC,QACb,QAAO,OAAO,OAAO;EACnB;EACA,UAAU,OAAO,OAAO,SAAS;EACjC,iBAAiB;EACjB,iBAAiB;EACjB,SAAS;EACV,CAAC;CAQJ,MAAM,kBAAkB,QAJIC,UADX,uBAAuB,GAAG,EACS;EAClD,gBAAgB;EAChB,WAAW;EACZ,CAAC,CAAC,SAAS,CACwC,SAAS,MAAM;AAEnE,QAAO,OAAO,OAAO;EACnB;EACA,UAAU,OAAO,OAAO,SAAS;EACjC,iBAAiB;EACjB;EACA,SAAS;EACV,CAAC;;;;;;;;;;;AAYJ,SAAgB,uBACd,aACyB;CACzB,MAAM,WAAW,iBAAiB;CAClC,MAAM,WAAW,OAAO,KAAK,SAAS,YAAY;CAClD,MAAMC,MAA+B,EAAE;AACvC,MAAK,MAAM,OAAO,SAChB,KAAI,OAAO,YAAa,KAAI,OAAO,YAAY;AAEjD,KAAI,cAAc,YAAa,KAAI,WAAW,YAAY;CAC1D,MAAM,YAAY,OAAO,KAAK,YAAY,CACvC,QAAQ,MAAM,EAAE,KAAK,KAAK,CAC1B,MAAM,GAAG,MAAM;EACd,MAAM,aAAa,EAAE,WAAW,aAAa;EAC7C,MAAM,aAAa,EAAE,WAAW,aAAa;AAC7C,MAAI,cAAc,CAAC,WAAY,QAAO;AACtC,MAAI,CAAC,cAAc,WAAY,QAAO;AACtC,SAAO,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI;GAChC;AACJ,MAAK,MAAM,OAAO,UAAW,KAAI,OAAO,YAAY;AACpD,QAAO"}

package/dist/registry/bridge.d.ts

@@ -0,0 +1,47 @@
+import { Skill, SkillMetadata } from "../types/index.js";
+import { resolveSandbox } from "@graphorin/security/sandbox";
+import { Tool, ToolSource } from "@graphorin/core";
+
+//#region src/registry/bridge.d.ts
+
+/** Result of {@link stampSkillTool}. */
+interface StampedSkillTool<TInput = unknown, TOutput = unknown, TDeps = unknown> {
+  readonly tool: Tool<TInput, TOutput, TDeps>;
+  readonly source: ToolSource;
+  /** Resolved sandbox policy after the tier resolver ran. */
+  readonly resolvedSandbox: ReturnType<typeof resolveSandbox>;
+  /** `true` when the resolver overrode the operator's choice. */
+  readonly sandboxForced: boolean;
+  /** `true` when the inbound sanitization policy was upgraded to the untrusted default. */
+  readonly inboundSanitizationForced: boolean;
+}
+/**
+ * Stamp a skill-bundled tool with the metadata the
+ * `@graphorin/tools` registry expects:
+ *
+ * 1. Derive a `ToolSource` of kind `'skill'` carrying the skill's
+ *    name and trust level.
+ * 2. Run `resolveSandbox(...)` so the resulting `Tool.sandboxPolicy`
+ *    matches the mandatory tier for untrusted skills (DEC-148).
+ * 3. Default the `inboundSanitization` policy to
+ *    `'detect-and-strip-and-wrap'` for untrusted skills when the tool
+ *    author left it unset; trusted skills inherit the operator's
+ *    choice.
+ *
+ * The function returns a freshly-frozen `Tool` with the resolved
+ * `sandboxPolicy` and `inboundSanitization` baked in so downstream
+ * registries cannot accidentally re-inherit a relaxed policy.
+ *
+ * @stable
+ */
+declare function stampSkillTool<TInput = unknown, TOutput = unknown, TDeps = unknown>(tool: Tool<TInput, TOutput, TDeps>, skill: Pick<Skill, 'metadata'>): StampedSkillTool<TInput, TOutput, TDeps>;
+/**
+ * Lower-level variant accepting a raw {@link SkillMetadata} so
+ * fixtures and tests do not have to materialise a full {@link Skill}.
+ *
+ * @stable
+ */
+declare function stampSkillToolFromMetadata<TInput = unknown, TOutput = unknown, TDeps = unknown>(tool: Tool<TInput, TOutput, TDeps>, metadata: SkillMetadata): StampedSkillTool<TInput, TOutput, TDeps>;
+//#endregion
+export { StampedSkillTool, stampSkillTool, stampSkillToolFromMetadata };
+//# sourceMappingURL=bridge.d.ts.map

package/dist/registry/bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.ts","names":[],"sources":["../../src/registry/bridge.ts"],"sourcesContent":[],"mappings":";;;;;;;AAsDc,UAhCG,gBAgCH,CAAA,SAAA,OAAA,EAAA,UAAA,OAAA,EAAA,QAAA,OAAA,CAAA,CAAA;EAAL,SAAA,IAAA,EA/BQ,IA+BR,CA/Ba,MA+Bb,EA/BqB,OA+BrB,EA/B8B,KA+B9B,CAAA;EACW,SAAA,MAAA,EA/BD,UA+BC;EAAQ;EAAS,SAAA,eAAA,EA7BT,UA6BS,CAAA,OA7BS,cA6BT,CAAA;EAAlC;EAAgB,SAAA,aAAA,EAAA,OAAA;EAUH;EACH,SAAA,yBAAA,EAAA,OAAA;;;;;;;;;;;;;;;;;;;;;iBAdG,2EACR,KAAK,QAAQ,SAAS,eACrB,KAAK,qBACX,iBAAiB,QAAQ,SAAS;;;;;;;iBAUrB,uFACR,KAAK,QAAQ,SAAS,kBAClB,gBACT,iBAAiB,QAAQ,SAAS"}

package/dist/registry/bridge.js

@@ -0,0 +1,91 @@
+import { resolveSandbox } from "@graphorin/security/sandbox";
+
+//#region src/registry/bridge.ts
+/**
+* Stamp a skill-bundled tool with the metadata the
+* `@graphorin/tools` registry expects:
+*
+* 1. Derive a `ToolSource` of kind `'skill'` carrying the skill's
+*    name and trust level.
+* 2. Run `resolveSandbox(...)` so the resulting `Tool.sandboxPolicy`
+*    matches the mandatory tier for untrusted skills (DEC-148).
+* 3. Default the `inboundSanitization` policy to
+*    `'detect-and-strip-and-wrap'` for untrusted skills when the tool
+*    author left it unset; trusted skills inherit the operator's
+*    choice.
+*
+* The function returns a freshly-frozen `Tool` with the resolved
+* `sandboxPolicy` and `inboundSanitization` baked in so downstream
+* registries cannot accidentally re-inherit a relaxed policy.
+*
+* @stable
+*/
+function stampSkillTool(tool, skill) {
+	return stampSkillToolFromMetadata(tool, skill.metadata);
+}
+/**
+* Lower-level variant accepting a raw {@link SkillMetadata} so
+* fixtures and tests do not have to materialise a full {@link Skill}.
+*
+* @stable
+*/
+function stampSkillToolFromMetadata(tool, metadata) {
+	const sandboxResolverArgs = { trustLevel: mapTrustLevel(metadata.graphorinTrustLevel) };
+	if (tool.name !== void 0) sandboxResolverArgs.toolName = tool.name;
+	if (metadata.name !== void 0) sandboxResolverArgs.skillName = metadata.name;
+	const operatorOverride = sandboxOverrideFromTool(tool);
+	if (operatorOverride !== void 0) sandboxResolverArgs.override = operatorOverride;
+	const resolvedSandbox = resolveSandbox(sandboxResolverArgs);
+	const inboundSanitization = inboundSanitizationFor(tool, metadata.graphorinTrustLevel);
+	const stamped = {
+		...tool,
+		sandboxPolicy: mapSandboxKindToPolicy(resolvedSandbox.kind),
+		...inboundSanitization === void 0 ? {} : { inboundSanitization }
+	};
+	const source = Object.freeze({
+		kind: "skill",
+		skillName: metadata.name,
+		trustLevel: metadata.graphorinTrustLevel === "untrusted" || metadata.graphorinTrustLevel === "unknown" ? "untrusted" : "trusted"
+	});
+	return Object.freeze({
+		tool: Object.freeze(stamped),
+		source,
+		resolvedSandbox,
+		sandboxForced: resolvedSandbox.forced,
+		inboundSanitizationForced: inboundSanitization !== void 0 && tool.inboundSanitization === void 0
+	});
+}
+function mapTrustLevel(level) {
+	switch (level) {
+		case "untrusted":
+		case "unknown": return "untrusted";
+		case "trusted":
+		case "trusted-with-scripts": return "trusted";
+		default: return "user-defined";
+	}
+}
+function mapSandboxKindToPolicy(kind) {
+	if (kind === "none") return "none";
+	if (kind === "worker-threads") return "sandboxed";
+	if (kind === "isolated-vm") return "isolated";
+	if (kind === "docker") return "docker";
+	return "sandboxed";
+}
+function inboundSanitizationFor(tool, trustLevel) {
+	if (tool.inboundSanitization !== void 0) return tool.inboundSanitization;
+	if (trustLevel === "untrusted" || trustLevel === "unknown") return "detect-and-strip-and-wrap";
+}
+function sandboxOverrideFromTool(tool) {
+	switch (tool.sandboxPolicy) {
+		case void 0: return;
+		case "none": return { kind: "none" };
+		case "sandboxed": return { kind: "worker-threads" };
+		case "isolated": return { kind: "isolated-vm" };
+		case "docker": return { kind: "docker" };
+		default: return;
+	}
+}
+
+//#endregion
+export { stampSkillTool, stampSkillToolFromMetadata };
+//# sourceMappingURL=bridge.js.map

package/dist/registry/bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.js","names":["sandboxResolverArgs: Parameters<typeof resolveSandbox>[0]","stamped: Mutable<Tool<TInput, TOutput, TDeps>>","source: ToolSource"],"sources":["../../src/registry/bridge.ts"],"sourcesContent":["/**\n * Helper functions that bridge skill-bundled `Tool` records into the\n * `@graphorin/tools` registry.\n *\n * The skills loader does not import the runtime registry directly —\n * downstream callers (the agent runtime in Phase 12, the test suite,\n * and any user-supplied bootstrap script) materialise the actual\n * `Tool[]` from the skill module surface and feed each one through\n * {@link stampSkillTool} to get a {@link Tool} + a {@link ToolSource}\n * pair the registry can register with the correct trust-class\n * derivation, sandbox tier propagation, and inbound-sanitization\n * defaults.\n *\n * @packageDocumentation\n */\n\nimport type { InboundSanitizationPolicy, SandboxPolicy, Tool, ToolSource } from '@graphorin/core';\nimport { resolveSandbox, type SandboxTrustLevel } from '@graphorin/security/sandbox';\n\nimport type { Skill, SkillMetadata } from '../types/index.js';\n\n/** Result of {@link stampSkillTool}. */\nexport interface StampedSkillTool<TInput = unknown, TOutput = unknown, TDeps = unknown> {\n  readonly tool: Tool<TInput, TOutput, TDeps>;\n  readonly source: ToolSource;\n  /** Resolved sandbox policy after the tier resolver ran. */\n  readonly resolvedSandbox: ReturnType<typeof resolveSandbox>;\n  /** `true` when the resolver overrode the operator's choice. */\n  readonly sandboxForced: boolean;\n  /** `true` when the inbound sanitization policy was upgraded to the untrusted default. */\n  readonly inboundSanitizationForced: boolean;\n}\n\n/**\n * Stamp a skill-bundled tool with the metadata the\n * `@graphorin/tools` registry expects:\n *\n * 1. Derive a `ToolSource` of kind `'skill'` carrying the skill's\n *    name and trust level.\n * 2. Run `resolveSandbox(...)` so the resulting `Tool.sandboxPolicy`\n *    matches the mandatory tier for untrusted skills (DEC-148).\n * 3. Default the `inboundSanitization` policy to\n *    `'detect-and-strip-and-wrap'` for untrusted skills when the tool\n *    author left it unset; trusted skills inherit the operator's\n *    choice.\n *\n * The function returns a freshly-frozen `Tool` with the resolved\n * `sandboxPolicy` and `inboundSanitization` baked in so downstream\n * registries cannot accidentally re-inherit a relaxed policy.\n *\n * @stable\n */\nexport function stampSkillTool<TInput = unknown, TOutput = unknown, TDeps = unknown>(\n  tool: Tool<TInput, TOutput, TDeps>,\n  skill: Pick<Skill, 'metadata'>,\n): StampedSkillTool<TInput, TOutput, TDeps> {\n  return stampSkillToolFromMetadata(tool, skill.metadata);\n}\n\n/**\n * Lower-level variant accepting a raw {@link SkillMetadata} so\n * fixtures and tests do not have to materialise a full {@link Skill}.\n *\n * @stable\n */\nexport function stampSkillToolFromMetadata<TInput = unknown, TOutput = unknown, TDeps = unknown>(\n  tool: Tool<TInput, TOutput, TDeps>,\n  metadata: SkillMetadata,\n): StampedSkillTool<TInput, TOutput, TDeps> {\n  const trustLevel = mapTrustLevel(metadata.graphorinTrustLevel);\n  const sandboxResolverArgs: Parameters<typeof resolveSandbox>[0] = {\n    trustLevel,\n  };\n  if (tool.name !== undefined)\n    (sandboxResolverArgs as Mutable<typeof sandboxResolverArgs>).toolName = tool.name;\n  if (metadata.name !== undefined)\n    (sandboxResolverArgs as Mutable<typeof sandboxResolverArgs>).skillName = metadata.name;\n  const operatorOverride = sandboxOverrideFromTool(tool);\n  if (operatorOverride !== undefined)\n    (sandboxResolverArgs as Mutable<typeof sandboxResolverArgs>).override = operatorOverride;\n  const resolvedSandbox = resolveSandbox(sandboxResolverArgs);\n  const inboundSanitization = inboundSanitizationFor(tool, metadata.graphorinTrustLevel);\n  const stamped: Mutable<Tool<TInput, TOutput, TDeps>> = {\n    ...tool,\n    sandboxPolicy: mapSandboxKindToPolicy(resolvedSandbox.kind),\n    ...(inboundSanitization === undefined ? {} : { inboundSanitization }),\n  };\n  const source: ToolSource = Object.freeze({\n    kind: 'skill' as const,\n    skillName: metadata.name,\n    // 'unknown' inherits the strict sandbox policy of 'untrusted', so\n    // the agent runtime registers the source as untrusted too — that\n    // forces the inbound-sanitization default\n    // ('detect-and-strip-and-wrap') and the precedence ladder used by\n    // collision resolution to demote it relative to first-party\n    // / trusted-skill registrations.\n    trustLevel:\n      metadata.graphorinTrustLevel === 'untrusted' || metadata.graphorinTrustLevel === 'unknown'\n        ? 'untrusted'\n        : 'trusted',\n  });\n  return Object.freeze({\n    tool: Object.freeze(stamped) as Tool<TInput, TOutput, TDeps>,\n    source,\n    resolvedSandbox,\n    sandboxForced: resolvedSandbox.forced,\n    inboundSanitizationForced:\n      inboundSanitization !== undefined && tool.inboundSanitization === undefined,\n  });\n}\n\nfunction mapTrustLevel(level: SkillMetadata['graphorinTrustLevel']): SandboxTrustLevel {\n  switch (level) {\n    case 'untrusted':\n    case 'unknown':\n      // Phase 08 § Risks & mitigations: 'unknown' enforces sandbox\n      // without requiring signature, so the sandbox tier resolver\n      // applies the same strict policy as 'untrusted'.\n      return 'untrusted';\n    case 'trusted':\n    case 'trusted-with-scripts':\n      return 'trusted';\n    default: {\n      const exhaustive: never = level;\n      void exhaustive;\n      return 'user-defined';\n    }\n  }\n}\n\nfunction mapSandboxKindToPolicy(kind: ReturnType<typeof resolveSandbox>['kind']): SandboxPolicy {\n  if (kind === 'none') return 'none';\n  if (kind === 'worker-threads') return 'sandboxed';\n  if (kind === 'isolated-vm') return 'isolated';\n  if (kind === 'docker') return 'docker';\n  return 'sandboxed';\n}\n\nfunction inboundSanitizationFor(\n  tool: Pick<Tool, 'inboundSanitization'>,\n  trustLevel: SkillMetadata['graphorinTrustLevel'],\n): InboundSanitizationPolicy | undefined {\n  if (tool.inboundSanitization !== undefined) return tool.inboundSanitization;\n  if (trustLevel === 'untrusted' || trustLevel === 'unknown') {\n    return 'detect-and-strip-and-wrap';\n  }\n  return undefined;\n}\n\nfunction sandboxOverrideFromTool(\n  tool: Pick<Tool, 'sandboxPolicy'>,\n): { readonly kind?: ReturnType<typeof resolveSandbox>['kind'] } | undefined {\n  switch (tool.sandboxPolicy) {\n    case undefined:\n      return undefined;\n    case 'none':\n      return { kind: 'none' };\n    case 'sandboxed':\n      return { kind: 'worker-threads' };\n    case 'isolated':\n      return { kind: 'isolated-vm' };\n    case 'docker':\n      return { kind: 'docker' };\n    default:\n      return undefined;\n  }\n}\n\ntype Mutable<T> = { -readonly [K in keyof T]: T[K] };\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAoDA,SAAgB,eACd,MACA,OAC0C;AAC1C,QAAO,2BAA2B,MAAM,MAAM,SAAS;;;;;;;;AASzD,SAAgB,2BACd,MACA,UAC0C;CAE1C,MAAMA,sBAA4D,EAChE,YAFiB,cAAc,SAAS,oBAAoB,EAG7D;AACD,KAAI,KAAK,SAAS,OAChB,CAAC,oBAA4D,WAAW,KAAK;AAC/E,KAAI,SAAS,SAAS,OACpB,CAAC,oBAA4D,YAAY,SAAS;CACpF,MAAM,mBAAmB,wBAAwB,KAAK;AACtD,KAAI,qBAAqB,OACvB,CAAC,oBAA4D,WAAW;CAC1E,MAAM,kBAAkB,eAAe,oBAAoB;CAC3D,MAAM,sBAAsB,uBAAuB,MAAM,SAAS,oBAAoB;CACtF,MAAMC,UAAiD;EACrD,GAAG;EACH,eAAe,uBAAuB,gBAAgB,KAAK;EAC3D,GAAI,wBAAwB,SAAY,EAAE,GAAG,EAAE,qBAAqB;EACrE;CACD,MAAMC,SAAqB,OAAO,OAAO;EACvC,MAAM;EACN,WAAW,SAAS;EAOpB,YACE,SAAS,wBAAwB,eAAe,SAAS,wBAAwB,YAC7E,cACA;EACP,CAAC;AACF,QAAO,OAAO,OAAO;EACnB,MAAM,OAAO,OAAO,QAAQ;EAC5B;EACA;EACA,eAAe,gBAAgB;EAC/B,2BACE,wBAAwB,UAAa,KAAK,wBAAwB;EACrE,CAAC;;AAGJ,SAAS,cAAc,OAAgE;AACrF,SAAQ,OAAR;EACE,KAAK;EACL,KAAK,UAIH,QAAO;EACT,KAAK;EACL,KAAK,uBACH,QAAO;EACT,QAGE,QAAO;;;AAKb,SAAS,uBAAuB,MAAgE;AAC9F,KAAI,SAAS,OAAQ,QAAO;AAC5B,KAAI,SAAS,iBAAkB,QAAO;AACtC,KAAI,SAAS,cAAe,QAAO;AACnC,KAAI,SAAS,SAAU,QAAO;AAC9B,QAAO;;AAGT,SAAS,uBACP,MACA,YACuC;AACvC,KAAI,KAAK,wBAAwB,OAAW,QAAO,KAAK;AACxD,KAAI,eAAe,eAAe,eAAe,UAC/C,QAAO;;AAKX,SAAS,wBACP,MAC2E;AAC3E,SAAQ,KAAK,eAAb;EACE,KAAK,OACH;EACF,KAAK,OACH,QAAO,EAAE,MAAM,QAAQ;EACzB,KAAK,YACH,QAAO,EAAE,MAAM,kBAAkB;EACnC,KAAK,WACH,QAAO,EAAE,MAAM,eAAe;EAChC,KAAK,SACH,QAAO,EAAE,MAAM,UAAU;EAC3B,QACE"}

package/dist/registry/index.d.ts

@@ -0,0 +1,140 @@
+import { ActivatedSkill, InlineSkillTool, Skill, SkillMetadata, SkillToolDeclaration } from "../types/index.js";
+import { StampedSkillTool, stampSkillTool, stampSkillToolFromMetadata } from "./bridge.js";
+import { ResolvedTool } from "@graphorin/core";
+
+//#region src/registry/index.d.ts
+
+/**
+ * Stamping seam injected by the agent runtime (Phase 12). It turns a skill's
+ * pre-built `Tool` into a fully resolved `ResolvedTool` (trust class + sandbox
+ * tier + source). The skills package keeps no hard dependency on
+ * `@graphorin/tools`; when no stamper is configured, `activate()` surfaces no
+ * tools (the runtime resolves them itself).
+ */
+type SkillToolStamper = (tool: InlineSkillTool, metadata: SkillMetadata) => ResolvedTool;
+/** Options accepted by {@link createSkillRegistry}. */
+interface SkillRegistryOptions {
+  /**
+   * Default activation behaviour. When `'metadata-only'` (default),
+   * `activate(...)` returns the parsed activation request without
+   * invoking `Skill.body()`; callers (the agent runtime) then invoke
+   * the body resolver themselves so the runtime can attach a span.
+   * When `'eager'`, the registry resolves the body before returning,
+   * suitable for tests.
+   */
+  readonly activationStrategy?: 'metadata-only' | 'eager';
+  /**
+   * Optional stamping function (RP-11). When supplied, `activate()` runs each
+   * skill's pre-built `Tool[]` through it and surfaces the results on
+   * {@link ActivatedSkill.tools}. Without it, `activate()` surfaces no tools —
+   * the agent runtime resolves and stamps them itself.
+   */
+  readonly stampTool?: SkillToolStamper;
+}
+/** Public registry surface. */
+interface SkillRegistry {
+  register(skill: Skill): void;
+  /**
+   * Upsert a skill by name (RP-11). Unlike {@link SkillRegistry.register},
+   * `replace` overwrites an existing registration instead of throwing on a
+   * name collision — the upgrade path for hot-reloading a re-loaded skill.
+   */
+  replace(skill: Skill): void;
+  unregister(name: string): boolean;
+  getSkill(name: string): Skill | undefined;
+  has(name: string): boolean;
+  list(): ReadonlyArray<Skill>;
+  getMetadata(): ReadonlyArray<SkillMetadata>;
+  /**
+   * Skills surfaced into the system prompt for auto-activation.
+   * Skills with `disable-model-invocation: true` are excluded.
+   */
+  getAutoActivationMetadata(): ReadonlyArray<SkillMetadata>;
+  /**
+   * Render the auto-activation metadata as a string suitable for the
+   * system prompt. The format is bytes-stable and consumed verbatim
+   * by the ContextEngine layered template (Phase 10d). Skills with
+   * `disable-model-invocation: true` are excluded.
+   */
+  getMetadataBlock(): string;
+  /**
+   * Resolve a single trigger (model-emitted skill name OR the raw
+   * `/skill:<name>` slash-command body) into an {@link ActivationRequest}.
+   * Returns `null` when no skill matches and the trigger looked like a
+   * slash command — callers that want a strict mode should call
+   * {@link parseActivationTrigger} themselves.
+   */
+  resolveTrigger(trigger: string): ActivationRequest | null;
+  activate(triggers: ReadonlyArray<string>, signal?: AbortSignal): Promise<ReadonlyArray<ActivatedSkill>>;
+  /**
+   * Best-effort match: returns every skill whose name OR description
+   * contains all of the supplied trigger tokens (case-insensitive).
+   * The agent runtime uses this when the model emits a trigger phrase
+   * that does not directly map to a skill name.
+   */
+  search(triggers: ReadonlyArray<string>): ReadonlyArray<Skill>;
+  /**
+   * Flat, deduplicated list of every pre-built tool shipped by the
+   * registered skills. The first registration wins on a `tool.name`
+   * collision; later collisions surface a one-time WARN through the
+   * console so operators can resolve the conflict (Phase 12 will
+   * route these through the audit emitter).
+   */
+  tools(): ReadonlyArray<InlineSkillTool>;
+  toolDeclarations(): ReadonlyArray<RegisteredToolDeclaration>;
+  size(): number;
+  clear(): void;
+}
+/** Activation request produced by {@link SkillRegistry.resolveTrigger}. */
+interface ActivationRequest {
+  readonly skill: Skill;
+  readonly activationKind: ActivatedSkill['activationKind'];
+  readonly args?: string;
+}
+/**
+ * Tool-declaration record exposed by {@link SkillRegistry.toolDeclarations}.
+ * Adds the owning skill's name and trust level so downstream
+ * registrations into `@graphorin/tools` can stamp the source.
+ *
+ * @stable
+ */
+interface RegisteredToolDeclaration extends SkillToolDeclaration {
+  readonly skillName: string;
+  readonly trustLevel: SkillMetadata['graphorinTrustLevel'];
+}
+/**
+ * Build a fresh, empty registry. Multiple registries can co-exist
+ * within a single process; the framework defaults to a single shared
+ * instance per agent instance.
+ *
+ * @stable
+ */
+declare function createSkillRegistry(options?: SkillRegistryOptions): SkillRegistry;
+/**
+ * Parsed activation trigger. The registry uses this to discriminate
+ * slash-command activations (which override
+ * `disable-model-invocation: true`) from model-emitted auto
+ * activations (which honour it).
+ *
+ * @stable
+ */
+interface ParsedActivationTrigger {
+  readonly name: string;
+  readonly activationKind: ActivatedSkill['activationKind'];
+  readonly args?: string;
+}
+/**
+ * Parse a single activation trigger. Slash-command bodies
+ * (`/skill:<name>`) are routed through the slash parser; bare names
+ * are treated as auto-activation requests emitted by the model.
+ *
+ * Throws {@link SlashCommandParseError} when the body looks like a
+ * slash command but does not match the grammar (so the caller can
+ * surface the error to the user).
+ *
+ * @stable
+ */
+declare function parseActivationTrigger(raw: string): ParsedActivationTrigger;
+//#endregion
+export { ActivationRequest, ParsedActivationTrigger, RegisteredToolDeclaration, SkillRegistry, SkillRegistryOptions, SkillToolStamper, type StampedSkillTool, createSkillRegistry, parseActivationTrigger, stampSkillTool, stampSkillToolFromMetadata };
+//# sourceMappingURL=index.d.ts.map

package/dist/registry/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/registry/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;AAsHW,KA1EC,gBAAA,GA0ED,CAAA,IAAA,EA1E2B,eA0E3B,EAAA,QAAA,EA1EsD,aA0EtD,EAAA,GA1EwE,YA0ExE;;AACW,UAxEL,oBAAA,CAwEK;EAAa;AAMnC;AAaA;AAYA;AA6NA;AAiBA;;;;;;;;;;uBArUuB;;;UAIN,aAAA;kBACC;;;;;;iBAMD;;0BAES;;UAEhB,cAAc;iBACP,cAAc;;;;;+BAKA,cAAc;;;;;;;;;;;;;;;mCAeV;qBAErB,gCACD,cACR,QAAQ,cAAc;;;;;;;mBAOR,wBAAwB,cAAc;;;;;;;;WAQ9C,cAAc;sBACH,cAAc;;;;;UAMnB,iBAAA;kBACC;2BACS;;;;;;;;;;UAWV,yBAAA,SAAkC;;uBAE5B;;;;;;;;;iBAUP,mBAAA,WAA6B,uBAA4B;;;;;;;;;UA6NxD,uBAAA;;2BAEU;;;;;;;;;;;;;;iBAeX,sBAAA,eAAqC"}

package/dist/registry/index.js

@@ -0,0 +1,193 @@
+import { SkillNameCollisionError, SlashCommandParseError } from "../errors/index.js";
+import { parseSlashCommand } from "../activation/index.js";
+import { stampSkillTool, stampSkillToolFromMetadata } from "./bridge.js";
+
+//#region src/registry/index.ts
+/**
+* Build a fresh, empty registry. Multiple registries can co-exist
+* within a single process; the framework defaults to a single shared
+* instance per agent instance.
+*
+* @stable
+*/
+function createSkillRegistry(options = {}) {
+	const skillsByName = /* @__PURE__ */ new Map();
+	const strategy = options.activationStrategy ?? "metadata-only";
+	function register(skill) {
+		if (skillsByName.has(skill.metadata.name)) throw new SkillNameCollisionError(skill.metadata.name);
+		skillsByName.set(skill.metadata.name, skill);
+	}
+	function replace(skill) {
+		skillsByName.set(skill.metadata.name, skill);
+	}
+	function unregister(name) {
+		return skillsByName.delete(name);
+	}
+	function getSkill(name) {
+		return skillsByName.get(name);
+	}
+	function has(name) {
+		return skillsByName.has(name);
+	}
+	function list() {
+		return Object.freeze([...skillsByName.values()]);
+	}
+	function getMetadata() {
+		return Object.freeze([...skillsByName.values()].map((skill) => skill.metadata));
+	}
+	function getAutoActivationMetadata() {
+		return Object.freeze([...skillsByName.values()].map((skill) => skill.metadata).filter((metadata) => !metadata.disableModelInvocation));
+	}
+	function getMetadataBlock() {
+		const lines = [];
+		const auto = getAutoActivationMetadata();
+		if (auto.length === 0) return "";
+		lines.push("# Available skills");
+		lines.push("");
+		for (const meta of auto) {
+			lines.push(`## ${meta.name}`);
+			lines.push("");
+			const description = meta.description.replace(/\s+/gu, " ").trim();
+			if (description.length > 0) lines.push(description);
+			const cues = [];
+			if (meta.allowedTools !== void 0 && meta.allowedTools.length > 0) cues.push(`Allowed tools: ${[...meta.allowedTools].join(", ")}`);
+			if (meta.graphorinSensitivity !== void 0) cues.push(`Sensitivity: ${meta.graphorinSensitivity}`);
+			if (cues.length > 0) {
+				lines.push("");
+				for (const cue of cues) lines.push(`- ${cue}`);
+			}
+			lines.push("");
+		}
+		return lines.join("\n").replace(/\n+$/u, "\n");
+	}
+	function search(triggers) {
+		const tokens = [...triggers].flatMap((trigger) => trigger.toLowerCase().split(/\s+/u)).filter((tok) => tok.length > 0);
+		if (tokens.length === 0) return Object.freeze([]);
+		const matches = [];
+		const seen = /* @__PURE__ */ new Set();
+		for (const skill of skillsByName.values()) {
+			const haystack = `${skill.metadata.name}\n${skill.metadata.description}`.toLowerCase();
+			if (tokens.every((tok) => haystack.includes(tok)) && !seen.has(skill.metadata.name)) {
+				seen.add(skill.metadata.name);
+				matches.push(skill);
+			}
+		}
+		return Object.freeze(matches);
+	}
+	function tools() {
+		const seen = /* @__PURE__ */ new Set();
+		const out = [];
+		const collisions = /* @__PURE__ */ new Set();
+		for (const skill of skillsByName.values()) for (const tool of skill.tools()) {
+			if (seen.has(tool.name)) {
+				if (!collisions.has(tool.name)) {
+					collisions.add(tool.name);
+					console.warn(`[graphorin/skills] Duplicate tool name '${tool.name}' across skills; first registration wins.`);
+				}
+				continue;
+			}
+			seen.add(tool.name);
+			out.push(tool);
+		}
+		return Object.freeze(out);
+	}
+	function resolveTrigger(trigger) {
+		const parsed = parseActivationTrigger(trigger);
+		const skill = skillsByName.get(parsed.name);
+		if (skill === void 0) return null;
+		if (parsed.activationKind === "auto" && skill.metadata.disableModelInvocation) return null;
+		const request = {
+			skill,
+			activationKind: parsed.activationKind
+		};
+		if (parsed.args !== void 0 && parsed.args.length > 0) request.args = parsed.args;
+		return Object.freeze(request);
+	}
+	async function activate(triggers, signal) {
+		const out = [];
+		const seen = /* @__PURE__ */ new Set();
+		for (const trigger of triggers) {
+			const request = resolveTrigger(trigger);
+			if (request === null) continue;
+			if (seen.has(request.skill.metadata.name)) continue;
+			seen.add(request.skill.metadata.name);
+			const body = strategy === "eager" ? await request.skill.body(signal) : "";
+			const resources = strategy === "eager" ? await request.skill.resources(signal) : Object.freeze([]);
+			const stampedTools = options.stampTool !== void 0 ? Object.freeze(request.skill.tools().map((tool) => options.stampTool(tool, request.skill.metadata))) : Object.freeze([]);
+			out.push(Object.freeze({
+				skill: request.skill,
+				body,
+				resources,
+				tools: stampedTools,
+				activationKind: request.activationKind,
+				activatedAt: Date.now()
+			}));
+		}
+		return Object.freeze(out);
+	}
+	function toolDeclarations() {
+		const out = [];
+		for (const skill of skillsByName.values()) for (const decl of skill.toolDeclarations()) out.push(Object.freeze({
+			...decl,
+			skillName: skill.metadata.name,
+			trustLevel: skill.metadata.graphorinTrustLevel
+		}));
+		return Object.freeze(out);
+	}
+	function size() {
+		return skillsByName.size;
+	}
+	function clear() {
+		skillsByName.clear();
+	}
+	return Object.freeze({
+		register,
+		replace,
+		unregister,
+		getSkill,
+		has,
+		list,
+		getMetadata,
+		getAutoActivationMetadata,
+		getMetadataBlock,
+		resolveTrigger,
+		activate,
+		search,
+		tools,
+		toolDeclarations,
+		size,
+		clear
+	});
+}
+/**
+* Parse a single activation trigger. Slash-command bodies
+* (`/skill:<name>`) are routed through the slash parser; bare names
+* are treated as auto-activation requests emitted by the model.
+*
+* Throws {@link SlashCommandParseError} when the body looks like a
+* slash command but does not match the grammar (so the caller can
+* surface the error to the user).
+*
+* @stable
+*/
+function parseActivationTrigger(raw) {
+	const trimmed = raw.trim();
+	if (trimmed.startsWith("/skill:") || /^\s*\/skill:/u.test(raw)) {
+		const parsed = parseSlashCommand(raw);
+		return Object.freeze({
+			name: parsed.name,
+			activationKind: "slash-command",
+			...parsed.args.length > 0 ? { args: parsed.args } : {}
+		});
+	}
+	if (trimmed.length === 0) throw new SlashCommandParseError(raw, "activation trigger must be non-empty.");
+	if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/u.test(trimmed)) throw new SlashCommandParseError(raw, "auto-activation trigger must match /^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$/.");
+	return Object.freeze({
+		name: trimmed,
+		activationKind: "auto"
+	});
+}
+
+//#endregion
+export { createSkillRegistry, parseActivationTrigger, stampSkillTool, stampSkillToolFromMetadata };
+//# sourceMappingURL=index.js.map