@graphorin/skills 0.5.0

package/dist/registry/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["lines: string[]","cues: string[]","matches: Skill[]","out: InlineSkillTool[]","request: Mutable<ActivationRequest>","out: ActivatedSkill[]","resources: ReadonlyArray<SkillResource>","stampedTools: ReadonlyArray<ResolvedTool>","out: RegisteredToolDeclaration[]"],"sources":["../../src/registry/index.ts"],"sourcesContent":["/**\n * `SkillRegistry` — registry over loaded skills.\n *\n * The registry is the surface the agent runtime (Phase 12) and the\n * standalone server (Phase 14) consume. It exposes:\n *\n * - `getMetadata()` — every skill's Tier-1 metadata, used by the\n *   ContextEngine to assemble the system prompt's skill metadata\n *   block (Phase 10d).\n * - `activate(triggers)` / `getActivationRequest(triggers)` —\n *   match a list of trigger strings (slash commands and / or model-\n *   emitted skill names) and return the corresponding\n *   {@link ActivatedSkill} records.\n * - `getSkill(name)` — direct lookup.\n * - `tools()` — flat list of declared tool entries; the runtime\n *   resolves the actual `Tool[]` through the `@graphorin/tools`\n *   registry.\n *\n * @packageDocumentation\n */\n\nimport type { ResolvedTool } from '@graphorin/core';\nimport { parseSlashCommand } from '../activation/index.js';\nimport { SkillNameCollisionError, SlashCommandParseError } from '../errors/index.js';\n\nexport type { StampedSkillTool } from './bridge.js';\nexport { stampSkillTool, stampSkillToolFromMetadata } from './bridge.js';\n\nimport type {\n  ActivatedSkill,\n  InlineSkillTool,\n  Skill,\n  SkillMetadata,\n  SkillResource,\n  SkillToolDeclaration,\n} from '../types/index.js';\n\n/**\n * Stamping seam injected by the agent runtime (Phase 12). It turns a skill's\n * pre-built `Tool` into a fully resolved `ResolvedTool` (trust class + sandbox\n * tier + source). The skills package keeps no hard dependency on\n * `@graphorin/tools`; when no stamper is configured, `activate()` surfaces no\n * tools (the runtime resolves them itself).\n */\nexport type SkillToolStamper = (tool: InlineSkillTool, metadata: SkillMetadata) => ResolvedTool;\n\n/** Options accepted by {@link createSkillRegistry}. */\nexport interface SkillRegistryOptions {\n  /**\n   * Default activation behaviour. When `'metadata-only'` (default),\n   * `activate(...)` returns the parsed activation request without\n   * invoking `Skill.body()`; callers (the agent runtime) then invoke\n   * the body resolver themselves so the runtime can attach a span.\n   * When `'eager'`, the registry resolves the body before returning,\n   * suitable for tests.\n   */\n  readonly activationStrategy?: 'metadata-only' | 'eager';\n  /**\n   * Optional stamping function (RP-11). When supplied, `activate()` runs each\n   * skill's pre-built `Tool[]` through it and surfaces the results on\n   * {@link ActivatedSkill.tools}. Without it, `activate()` surfaces no tools —\n   * the agent runtime resolves and stamps them itself.\n   */\n  readonly stampTool?: SkillToolStamper;\n}\n\n/** Public registry surface. */\nexport interface SkillRegistry {\n  register(skill: Skill): void;\n  /**\n   * Upsert a skill by name (RP-11). Unlike {@link SkillRegistry.register},\n   * `replace` overwrites an existing registration instead of throwing on a\n   * name collision — the upgrade path for hot-reloading a re-loaded skill.\n   */\n  replace(skill: Skill): void;\n  unregister(name: string): boolean;\n  getSkill(name: string): Skill | undefined;\n  has(name: string): boolean;\n  list(): ReadonlyArray<Skill>;\n  getMetadata(): ReadonlyArray<SkillMetadata>;\n  /**\n   * Skills surfaced into the system prompt for auto-activation.\n   * Skills with `disable-model-invocation: true` are excluded.\n   */\n  getAutoActivationMetadata(): ReadonlyArray<SkillMetadata>;\n  /**\n   * Render the auto-activation metadata as a string suitable for the\n   * system prompt. The format is bytes-stable and consumed verbatim\n   * by the ContextEngine layered template (Phase 10d). Skills with\n   * `disable-model-invocation: true` are excluded.\n   */\n  getMetadataBlock(): string;\n  /**\n   * Resolve a single trigger (model-emitted skill name OR the raw\n   * `/skill:<name>` slash-command body) into an {@link ActivationRequest}.\n   * Returns `null` when no skill matches and the trigger looked like a\n   * slash command — callers that want a strict mode should call\n   * {@link parseActivationTrigger} themselves.\n   */\n  resolveTrigger(trigger: string): ActivationRequest | null;\n  activate(\n    triggers: ReadonlyArray<string>,\n    signal?: AbortSignal,\n  ): Promise<ReadonlyArray<ActivatedSkill>>;\n  /**\n   * Best-effort match: returns every skill whose name OR description\n   * contains all of the supplied trigger tokens (case-insensitive).\n   * The agent runtime uses this when the model emits a trigger phrase\n   * that does not directly map to a skill name.\n   */\n  search(triggers: ReadonlyArray<string>): ReadonlyArray<Skill>;\n  /**\n   * Flat, deduplicated list of every pre-built tool shipped by the\n   * registered skills. The first registration wins on a `tool.name`\n   * collision; later collisions surface a one-time WARN through the\n   * console so operators can resolve the conflict (Phase 12 will\n   * route these through the audit emitter).\n   */\n  tools(): ReadonlyArray<InlineSkillTool>;\n  toolDeclarations(): ReadonlyArray<RegisteredToolDeclaration>;\n  size(): number;\n  clear(): void;\n}\n\n/** Activation request produced by {@link SkillRegistry.resolveTrigger}. */\nexport interface ActivationRequest {\n  readonly skill: Skill;\n  readonly activationKind: ActivatedSkill['activationKind'];\n  readonly args?: string;\n}\n\n/**\n * Tool-declaration record exposed by {@link SkillRegistry.toolDeclarations}.\n * Adds the owning skill's name and trust level so downstream\n * registrations into `@graphorin/tools` can stamp the source.\n *\n * @stable\n */\nexport interface RegisteredToolDeclaration extends SkillToolDeclaration {\n  readonly skillName: string;\n  readonly trustLevel: SkillMetadata['graphorinTrustLevel'];\n}\n\n/**\n * Build a fresh, empty registry. Multiple registries can co-exist\n * within a single process; the framework defaults to a single shared\n * instance per agent instance.\n *\n * @stable\n */\nexport function createSkillRegistry(options: SkillRegistryOptions = {}): SkillRegistry {\n  const skillsByName = new Map<string, Skill>();\n  const strategy = options.activationStrategy ?? 'metadata-only';\n\n  function register(skill: Skill): void {\n    if (skillsByName.has(skill.metadata.name)) {\n      throw new SkillNameCollisionError(skill.metadata.name);\n    }\n    skillsByName.set(skill.metadata.name, skill);\n  }\n\n  function replace(skill: Skill): void {\n    skillsByName.set(skill.metadata.name, skill);\n  }\n\n  function unregister(name: string): boolean {\n    return skillsByName.delete(name);\n  }\n\n  function getSkill(name: string): Skill | undefined {\n    return skillsByName.get(name);\n  }\n\n  function has(name: string): boolean {\n    return skillsByName.has(name);\n  }\n\n  function list(): ReadonlyArray<Skill> {\n    return Object.freeze([...skillsByName.values()]);\n  }\n\n  function getMetadata(): ReadonlyArray<SkillMetadata> {\n    return Object.freeze([...skillsByName.values()].map((skill) => skill.metadata));\n  }\n\n  function getAutoActivationMetadata(): ReadonlyArray<SkillMetadata> {\n    return Object.freeze(\n      [...skillsByName.values()]\n        .map((skill) => skill.metadata)\n        .filter((metadata) => !metadata.disableModelInvocation),\n    );\n  }\n\n  function getMetadataBlock(): string {\n    const lines: string[] = [];\n    const auto = getAutoActivationMetadata();\n    if (auto.length === 0) return '';\n    lines.push('# Available skills');\n    lines.push('');\n    for (const meta of auto) {\n      lines.push(`## ${meta.name}`);\n      lines.push('');\n      const description = meta.description.replace(/\\s+/gu, ' ').trim();\n      if (description.length > 0) lines.push(description);\n      const cues: string[] = [];\n      if (meta.allowedTools !== undefined && meta.allowedTools.length > 0) {\n        cues.push(`Allowed tools: ${[...meta.allowedTools].join(', ')}`);\n      }\n      if (meta.graphorinSensitivity !== undefined) {\n        cues.push(`Sensitivity: ${meta.graphorinSensitivity}`);\n      }\n      if (cues.length > 0) {\n        lines.push('');\n        for (const cue of cues) lines.push(`- ${cue}`);\n      }\n      lines.push('');\n    }\n    return lines.join('\\n').replace(/\\n+$/u, '\\n');\n  }\n\n  function search(triggers: ReadonlyArray<string>): ReadonlyArray<Skill> {\n    const tokens = [...triggers]\n      .flatMap((trigger) => trigger.toLowerCase().split(/\\s+/u))\n      .filter((tok) => tok.length > 0);\n    if (tokens.length === 0) return Object.freeze([]);\n    const matches: Skill[] = [];\n    const seen = new Set<string>();\n    for (const skill of skillsByName.values()) {\n      const haystack = `${skill.metadata.name}\\n${skill.metadata.description}`.toLowerCase();\n      const isMatch = tokens.every((tok) => haystack.includes(tok));\n      if (isMatch && !seen.has(skill.metadata.name)) {\n        seen.add(skill.metadata.name);\n        matches.push(skill);\n      }\n    }\n    return Object.freeze(matches);\n  }\n\n  function tools(): ReadonlyArray<InlineSkillTool> {\n    const seen = new Set<string>();\n    const out: InlineSkillTool[] = [];\n    const collisions = new Set<string>();\n    for (const skill of skillsByName.values()) {\n      for (const tool of skill.tools()) {\n        if (seen.has(tool.name)) {\n          if (!collisions.has(tool.name)) {\n            collisions.add(tool.name);\n            // eslint-disable-next-line no-console\n            console.warn(\n              `[graphorin/skills] Duplicate tool name '${tool.name}' across skills; first registration wins.`,\n            );\n          }\n          continue;\n        }\n        seen.add(tool.name);\n        out.push(tool);\n      }\n    }\n    return Object.freeze(out);\n  }\n\n  function resolveTrigger(trigger: string): ActivationRequest | null {\n    const parsed = parseActivationTrigger(trigger);\n    const skill = skillsByName.get(parsed.name);\n    if (skill === undefined) return null;\n    if (parsed.activationKind === 'auto' && skill.metadata.disableModelInvocation) {\n      // Auto-activation refused — the skill opted out.\n      return null;\n    }\n    const request: Mutable<ActivationRequest> = {\n      skill,\n      activationKind: parsed.activationKind,\n    };\n    if (parsed.args !== undefined && parsed.args.length > 0) request.args = parsed.args;\n    return Object.freeze(request);\n  }\n\n  async function activate(\n    triggers: ReadonlyArray<string>,\n    signal?: AbortSignal,\n  ): Promise<ReadonlyArray<ActivatedSkill>> {\n    const out: ActivatedSkill[] = [];\n    const seen = new Set<string>();\n    for (const trigger of triggers) {\n      const request = resolveTrigger(trigger);\n      if (request === null) continue;\n      if (seen.has(request.skill.metadata.name)) continue;\n      seen.add(request.skill.metadata.name);\n      const body = strategy === 'eager' ? await request.skill.body(signal) : '';\n      const resources: ReadonlyArray<SkillResource> =\n        strategy === 'eager' ? await request.skill.resources(signal) : Object.freeze([]);\n      // Pre-built tools (inline source) are surfaced via `Skill.tools()`.\n      // When the caller wired a `stampTool` function (the agent runtime does),\n      // each tool is stamped into a `ResolvedTool` and surfaced here; without\n      // it the registry exposes no tools (the runtime resolves them itself).\n      const stampedTools: ReadonlyArray<ResolvedTool> =\n        options.stampTool !== undefined\n          ? Object.freeze(\n              request.skill\n                .tools()\n                .map((tool) =>\n                  (options.stampTool as SkillToolStamper)(tool, request.skill.metadata),\n                ),\n            )\n          : Object.freeze([]);\n      out.push(\n        Object.freeze({\n          skill: request.skill,\n          body,\n          resources,\n          tools: stampedTools,\n          activationKind: request.activationKind,\n          activatedAt: Date.now(),\n        }),\n      );\n    }\n    return Object.freeze(out);\n  }\n\n  function toolDeclarations(): ReadonlyArray<RegisteredToolDeclaration> {\n    const out: RegisteredToolDeclaration[] = [];\n    for (const skill of skillsByName.values()) {\n      for (const decl of skill.toolDeclarations()) {\n        out.push(\n          Object.freeze({\n            ...decl,\n            skillName: skill.metadata.name,\n            trustLevel: skill.metadata.graphorinTrustLevel,\n          }),\n        );\n      }\n    }\n    return Object.freeze(out);\n  }\n\n  function size(): number {\n    return skillsByName.size;\n  }\n\n  function clear(): void {\n    skillsByName.clear();\n  }\n\n  return Object.freeze({\n    register,\n    replace,\n    unregister,\n    getSkill,\n    has,\n    list,\n    getMetadata,\n    getAutoActivationMetadata,\n    getMetadataBlock,\n    resolveTrigger,\n    activate,\n    search,\n    tools,\n    toolDeclarations,\n    size,\n    clear,\n  } satisfies SkillRegistry);\n}\n\n/**\n * Parsed activation trigger. The registry uses this to discriminate\n * slash-command activations (which override\n * `disable-model-invocation: true`) from model-emitted auto\n * activations (which honour it).\n *\n * @stable\n */\nexport interface ParsedActivationTrigger {\n  readonly name: string;\n  readonly activationKind: ActivatedSkill['activationKind'];\n  readonly args?: string;\n}\n\n/**\n * Parse a single activation trigger. Slash-command bodies\n * (`/skill:<name>`) are routed through the slash parser; bare names\n * are treated as auto-activation requests emitted by the model.\n *\n * Throws {@link SlashCommandParseError} when the body looks like a\n * slash command but does not match the grammar (so the caller can\n * surface the error to the user).\n *\n * @stable\n */\nexport function parseActivationTrigger(raw: string): ParsedActivationTrigger {\n  const trimmed = raw.trim();\n  if (trimmed.startsWith('/skill:') || /^\\s*\\/skill:/u.test(raw)) {\n    const parsed = parseSlashCommand(raw);\n    return Object.freeze({\n      name: parsed.name,\n      activationKind: 'slash-command' as const,\n      ...(parsed.args.length > 0 ? { args: parsed.args } : {}),\n    });\n  }\n  if (trimmed.length === 0) {\n    throw new SlashCommandParseError(raw, 'activation trigger must be non-empty.');\n  }\n  if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/u.test(trimmed)) {\n    throw new SlashCommandParseError(\n      raw,\n      'auto-activation trigger must match /^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$/.',\n    );\n  }\n  return Object.freeze({\n    name: trimmed,\n    activationKind: 'auto' as const,\n  });\n}\n\ntype Mutable<T> = { -readonly [K in keyof T]: T[K] };\n"],"mappings":"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"}

package/dist/spec/index.d.ts

@@ -0,0 +1,92 @@
+//#region src/spec/index.d.ts
+/**
+ * Bundled snapshot loader for the `SKILL.md` packaging-format
+ * specification.
+ *
+ * The framework ships an offline copy of the upstream specification
+ * so the loader can decide which frontmatter fields are recognised,
+ * which `graphorin-*` extensions deprecate (or co-exist with) an
+ * upstream field, and whether a skill author's
+ * `graphorin-anthropic-spec` hint refers to a snapshot newer or older
+ * than the bundled one. The snapshot is checked-in to the repository
+ * and refreshed via the `pnpm run check-anthropic-spec` CI cron.
+ *
+ * The loader does not fetch the upstream specification; the only
+ * network call lives inside the CI helper script. The snapshot lookup
+ * is deterministic and side-effect free at runtime.
+ *
+ * @packageDocumentation
+ */
+/** Stability classification of a known upstream field. */
+type FieldStability = 'stable' | 'standardized' | 'experimental';
+/** Migration policy applied to a `graphorin-*` field that maps to an upstream field. */
+type GraphorinFieldPolicy = 'deprecate-graphorin-prefix' | 'co-exist' | 'graphorin-only';
+/** Single entry of the upstream-known fields map. */
+interface KnownFieldEntry {
+  readonly since: string;
+  readonly required: boolean;
+  readonly type: string;
+  readonly stability: FieldStability;
+}
+/** Single entry of the `graphorin-*` mapping map. */
+interface GraphorinMappingEntry {
+  readonly anthropicEquivalent: string | null;
+  readonly policy: GraphorinFieldPolicy;
+  readonly since?: string;
+  readonly rationale?: string;
+  readonly deprecateAt?: string;
+  readonly removeAt?: string;
+}
+/** Top-level shape of the bundled snapshot. */
+interface SpecSnapshot {
+  readonly snapshotDate: string;
+  readonly specSource: string;
+  readonly specCommit: string | null;
+  readonly rationale?: string;
+  readonly knownFields: Readonly<Record<string, KnownFieldEntry>>;
+  readonly graphorinMapping: Readonly<Record<string, GraphorinMappingEntry>>;
+}
+/**
+ * Override the bundled snapshot. Used by tests that exercise the
+ * "newer / older spec snapshot" branches of the validator.
+ *
+ * @experimental
+ */
+declare function _setSpecSnapshotForTesting(snapshot: SpecSnapshot | null): void;
+/**
+ * Return the currently active snapshot. Loads the bundled JSON file
+ * on first call, then caches the parsed object.
+ *
+ * @stable
+ */
+declare function getSpecSnapshot(): SpecSnapshot;
+/**
+ * Resolve a known-field entry by name. Returns `undefined` if the
+ * field is not part of the upstream specification.
+ *
+ * @stable
+ */
+declare function getKnownField(field: string): KnownFieldEntry | undefined;
+/**
+ * Resolve the mapping entry for a `graphorin-*` field. Returns
+ * `undefined` if the field is not known to the snapshot.
+ *
+ * @stable
+ */
+declare function getGraphorinMapping(field: string): GraphorinMappingEntry | undefined;
+/**
+ * Compare an author's `graphorin-anthropic-spec` value against the
+ * bundled snapshot date. Returns:
+ *
+ * - `'same'`        — the author targeted the same snapshot.
+ * - `'older'`       — the author targeted an older snapshot.
+ * - `'newer'`       — the author targeted a newer snapshot.
+ * - `'unparseable'` — the author's value could not be interpreted as
+ *   an ISO-8601 date.
+ *
+ * @stable
+ */
+declare function compareAuthorSpecHint(authorValue: string): 'same' | 'older' | 'newer' | 'unparseable';
+//#endregion
+export { FieldStability, GraphorinFieldPolicy, GraphorinMappingEntry, KnownFieldEntry, SpecSnapshot, _setSpecSnapshotForTesting, compareAuthorSpecHint, getGraphorinMapping, getKnownField, getSpecSnapshot };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/spec/index.ts"],"sourcesContent":[],"mappings":";;AAwBA;AAGA;AAGA;AAQA;AAUA;;;;;;;;AAkBA;AAUA;AAkCA;AAUA;AAgBA;;KAhHY,cAAA;;KAGA,oBAAA;;UAGK,eAAA;;;;sBAIK;;;UAIL,qBAAA;;mBAEE;;;;;;;UAQF,YAAA;;;;;wBAKO,SAAS,eAAe;6BACnB,SAAS,eAAe;;;;;;;;iBAYrC,0BAAA,WAAqC;;;;;;;iBAUrC,eAAA,CAAA,GAAmB;;;;;;;iBAkCnB,aAAA,iBAA8B;;;;;;;iBAU9B,mBAAA,iBAAoC;;;;;;;;;;;;;iBAgBpC,qBAAA"}

package/dist/spec/index.js

@@ -0,0 +1,105 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+//#region src/spec/index.ts
+/**
+* Bundled snapshot loader for the `SKILL.md` packaging-format
+* specification.
+*
+* The framework ships an offline copy of the upstream specification
+* so the loader can decide which frontmatter fields are recognised,
+* which `graphorin-*` extensions deprecate (or co-exist with) an
+* upstream field, and whether a skill author's
+* `graphorin-anthropic-spec` hint refers to a snapshot newer or older
+* than the bundled one. The snapshot is checked-in to the repository
+* and refreshed via the `pnpm run check-anthropic-spec` CI cron.
+*
+* The loader does not fetch the upstream specification; the only
+* network call lives inside the CI helper script. The snapshot lookup
+* is deterministic and side-effect free at runtime.
+*
+* @packageDocumentation
+*/
+let cached = null;
+let overrideSnapshot = null;
+/**
+* Override the bundled snapshot. Used by tests that exercise the
+* "newer / older spec snapshot" branches of the validator.
+*
+* @experimental
+*/
+function _setSpecSnapshotForTesting(snapshot) {
+	overrideSnapshot = snapshot;
+}
+/**
+* Return the currently active snapshot. Loads the bundled JSON file
+* on first call, then caches the parsed object.
+*
+* @stable
+*/
+function getSpecSnapshot() {
+	if (overrideSnapshot !== null) return overrideSnapshot;
+	if (cached !== null) return cached;
+	const __dirname = dirname(fileURLToPath(import.meta.url));
+	const candidates = [join(__dirname, "..", "..", "anthropic-spec-snapshot.json"), join(__dirname, "..", "..", "anthropic-spec-snapshot.json")];
+	let lastError;
+	for (const candidate of candidates) try {
+		const raw = readFileSync(candidate, "utf8");
+		const parsed = JSON.parse(raw);
+		cached = parsed;
+		return parsed;
+	} catch (err) {
+		lastError = err;
+	}
+	throw new Error(`Failed to load bundled spec snapshot. Tried: ${candidates.join(", ")}. Cause: ${lastError.message}`);
+}
+/**
+* Resolve a known-field entry by name. Returns `undefined` if the
+* field is not part of the upstream specification.
+*
+* @stable
+*/
+function getKnownField(field) {
+	return getSpecSnapshot().knownFields[field];
+}
+/**
+* Resolve the mapping entry for a `graphorin-*` field. Returns
+* `undefined` if the field is not known to the snapshot.
+*
+* @stable
+*/
+function getGraphorinMapping(field) {
+	return getSpecSnapshot().graphorinMapping[field];
+}
+/**
+* Compare an author's `graphorin-anthropic-spec` value against the
+* bundled snapshot date. Returns:
+*
+* - `'same'`        — the author targeted the same snapshot.
+* - `'older'`       — the author targeted an older snapshot.
+* - `'newer'`       — the author targeted a newer snapshot.
+* - `'unparseable'` — the author's value could not be interpreted as
+*   an ISO-8601 date.
+*
+* @stable
+*/
+function compareAuthorSpecHint(authorValue) {
+	const snapshot = getSpecSnapshot();
+	const author = parseDate(authorValue);
+	const local = parseDate(snapshot.snapshotDate);
+	if (author === null || local === null) return "unparseable";
+	if (author.getTime() === local.getTime()) return "same";
+	return author.getTime() > local.getTime() ? "newer" : "older";
+}
+function parseDate(value) {
+	const trimmed = value.trim();
+	if (!/^\d{4}-\d{2}-\d{2}/u.test(trimmed)) return null;
+	const date = new Date(trimmed);
+	if (Number.isNaN(date.getTime())) return null;
+	return date;
+}
+
+//#endregion
+export { _setSpecSnapshotForTesting, compareAuthorSpecHint, getGraphorinMapping, getKnownField, getSpecSnapshot };
+//# sourceMappingURL=index.js.map

package/dist/spec/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["cached: SpecSnapshot | null","overrideSnapshot: SpecSnapshot | null","lastError: unknown"],"sources":["../../src/spec/index.ts"],"sourcesContent":["/**\n * Bundled snapshot loader for the `SKILL.md` packaging-format\n * specification.\n *\n * The framework ships an offline copy of the upstream specification\n * so the loader can decide which frontmatter fields are recognised,\n * which `graphorin-*` extensions deprecate (or co-exist with) an\n * upstream field, and whether a skill author's\n * `graphorin-anthropic-spec` hint refers to a snapshot newer or older\n * than the bundled one. The snapshot is checked-in to the repository\n * and refreshed via the `pnpm run check-anthropic-spec` CI cron.\n *\n * The loader does not fetch the upstream specification; the only\n * network call lives inside the CI helper script. The snapshot lookup\n * is deterministic and side-effect free at runtime.\n *\n * @packageDocumentation\n */\n\nimport { readFileSync } from 'node:fs';\nimport { dirname, join } from 'node:path';\nimport { fileURLToPath } from 'node:url';\n\n/** Stability classification of a known upstream field. */\nexport type FieldStability = 'stable' | 'standardized' | 'experimental';\n\n/** Migration policy applied to a `graphorin-*` field that maps to an upstream field. */\nexport type GraphorinFieldPolicy = 'deprecate-graphorin-prefix' | 'co-exist' | 'graphorin-only';\n\n/** Single entry of the upstream-known fields map. */\nexport interface KnownFieldEntry {\n  readonly since: string;\n  readonly required: boolean;\n  readonly type: string;\n  readonly stability: FieldStability;\n}\n\n/** Single entry of the `graphorin-*` mapping map. */\nexport interface GraphorinMappingEntry {\n  readonly anthropicEquivalent: string | null;\n  readonly policy: GraphorinFieldPolicy;\n  readonly since?: string;\n  readonly rationale?: string;\n  readonly deprecateAt?: string;\n  readonly removeAt?: string;\n}\n\n/** Top-level shape of the bundled snapshot. */\nexport interface SpecSnapshot {\n  readonly snapshotDate: string;\n  readonly specSource: string;\n  readonly specCommit: string | null;\n  readonly rationale?: string;\n  readonly knownFields: Readonly<Record<string, KnownFieldEntry>>;\n  readonly graphorinMapping: Readonly<Record<string, GraphorinMappingEntry>>;\n}\n\nlet cached: SpecSnapshot | null = null;\nlet overrideSnapshot: SpecSnapshot | null = null;\n\n/**\n * Override the bundled snapshot. Used by tests that exercise the\n * \"newer / older spec snapshot\" branches of the validator.\n *\n * @experimental\n */\nexport function _setSpecSnapshotForTesting(snapshot: SpecSnapshot | null): void {\n  overrideSnapshot = snapshot;\n}\n\n/**\n * Return the currently active snapshot. Loads the bundled JSON file\n * on first call, then caches the parsed object.\n *\n * @stable\n */\nexport function getSpecSnapshot(): SpecSnapshot {\n  if (overrideSnapshot !== null) return overrideSnapshot;\n  if (cached !== null) return cached;\n  const __filename = fileURLToPath(import.meta.url);\n  const __dirname = dirname(__filename);\n  const candidates = [\n    // Source: packages/skills/src/spec/index.ts → ../../anthropic-spec-snapshot.json\n    join(__dirname, '..', '..', 'anthropic-spec-snapshot.json'),\n    // Built ESM: packages/skills/dist/spec/index.js → ../../anthropic-spec-snapshot.json\n    join(__dirname, '..', '..', 'anthropic-spec-snapshot.json'),\n  ];\n  let lastError: unknown;\n  for (const candidate of candidates) {\n    try {\n      const raw = readFileSync(candidate, 'utf8');\n      const parsed = JSON.parse(raw) as SpecSnapshot;\n      cached = parsed;\n      return parsed;\n    } catch (err) {\n      lastError = err;\n    }\n  }\n  throw new Error(\n    `Failed to load bundled spec snapshot. Tried: ${candidates.join(', ')}. ` +\n      `Cause: ${(lastError as Error).message}`,\n  );\n}\n\n/**\n * Resolve a known-field entry by name. Returns `undefined` if the\n * field is not part of the upstream specification.\n *\n * @stable\n */\nexport function getKnownField(field: string): KnownFieldEntry | undefined {\n  return getSpecSnapshot().knownFields[field];\n}\n\n/**\n * Resolve the mapping entry for a `graphorin-*` field. Returns\n * `undefined` if the field is not known to the snapshot.\n *\n * @stable\n */\nexport function getGraphorinMapping(field: string): GraphorinMappingEntry | undefined {\n  return getSpecSnapshot().graphorinMapping[field];\n}\n\n/**\n * Compare an author's `graphorin-anthropic-spec` value against the\n * bundled snapshot date. Returns:\n *\n * - `'same'`        — the author targeted the same snapshot.\n * - `'older'`       — the author targeted an older snapshot.\n * - `'newer'`       — the author targeted a newer snapshot.\n * - `'unparseable'` — the author's value could not be interpreted as\n *   an ISO-8601 date.\n *\n * @stable\n */\nexport function compareAuthorSpecHint(\n  authorValue: string,\n): 'same' | 'older' | 'newer' | 'unparseable' {\n  const snapshot = getSpecSnapshot();\n  const author = parseDate(authorValue);\n  const local = parseDate(snapshot.snapshotDate);\n  if (author === null || local === null) return 'unparseable';\n  if (author.getTime() === local.getTime()) return 'same';\n  return author.getTime() > local.getTime() ? 'newer' : 'older';\n}\n\nfunction parseDate(value: string): Date | null {\n  const trimmed = value.trim();\n  if (!/^\\d{4}-\\d{2}-\\d{2}/u.test(trimmed)) return null;\n  const date = new Date(trimmed);\n  if (Number.isNaN(date.getTime())) return null;\n  return date;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAyDA,IAAIA,SAA8B;AAClC,IAAIC,mBAAwC;;;;;;;AAQ5C,SAAgB,2BAA2B,UAAqC;AAC9E,oBAAmB;;;;;;;;AASrB,SAAgB,kBAAgC;AAC9C,KAAI,qBAAqB,KAAM,QAAO;AACtC,KAAI,WAAW,KAAM,QAAO;CAE5B,MAAM,YAAY,QADC,cAAc,OAAO,KAAK,IAAI,CACZ;CACrC,MAAM,aAAa,CAEjB,KAAK,WAAW,MAAM,MAAM,+BAA+B,EAE3D,KAAK,WAAW,MAAM,MAAM,+BAA+B,CAC5D;CACD,IAAIC;AACJ,MAAK,MAAM,aAAa,WACtB,KAAI;EACF,MAAM,MAAM,aAAa,WAAW,OAAO;EAC3C,MAAM,SAAS,KAAK,MAAM,IAAI;AAC9B,WAAS;AACT,SAAO;UACA,KAAK;AACZ,cAAY;;AAGhB,OAAM,IAAI,MACR,gDAAgD,WAAW,KAAK,KAAK,CAAC,WACzD,UAAoB,UAClC;;;;;;;;AASH,SAAgB,cAAc,OAA4C;AACxE,QAAO,iBAAiB,CAAC,YAAY;;;;;;;;AASvC,SAAgB,oBAAoB,OAAkD;AACpF,QAAO,iBAAiB,CAAC,iBAAiB;;;;;;;;;;;;;;AAe5C,SAAgB,sBACd,aAC4C;CAC5C,MAAM,WAAW,iBAAiB;CAClC,MAAM,SAAS,UAAU,YAAY;CACrC,MAAM,QAAQ,UAAU,SAAS,aAAa;AAC9C,KAAI,WAAW,QAAQ,UAAU,KAAM,QAAO;AAC9C,KAAI,OAAO,SAAS,KAAK,MAAM,SAAS,CAAE,QAAO;AACjD,QAAO,OAAO,SAAS,GAAG,MAAM,SAAS,GAAG,UAAU;;AAGxD,SAAS,UAAU,OAA4B;CAC7C,MAAM,UAAU,MAAM,MAAM;AAC5B,KAAI,CAAC,sBAAsB,KAAK,QAAQ,CAAE,QAAO;CACjD,MAAM,OAAO,IAAI,KAAK,QAAQ;AAC9B,KAAI,OAAO,MAAM,KAAK,SAAS,CAAC,CAAE,QAAO;AACzC,QAAO"}

package/dist/types/index.d.ts

@@ -0,0 +1,305 @@
+import { ResolvedSkillTrustPolicy, SkillSignatureVerificationResult, SkillSource as SupplyChainSkillSource, SkillTrustLevel } from "@graphorin/security/supply-chain";
+import { ResolvedTool, Tool } from "@graphorin/core";
+
+//#region src/types/index.d.ts
+
+/**
+ * Trust level recognised by the skills loader. Extends the
+ * supply-chain trust ladder with a third `'unknown'` value the
+ * loader uses for skills that have no explicit declaration. The
+ * sandbox tier resolver treats `'unknown'` like `'untrusted'`
+ * (mandatory `worker-threads + no-net + no-fs`); the supply-chain
+ * installer treats it as untrusted EXCEPT that the signature
+ * requirement is downgraded from mandatory to optional — signature
+ * is a trust upgrade, not a gate (Phase 08 § Risks & mitigations).
+ *
+ * @stable
+ */
+type SkillsTrustLevel = SkillTrustLevel | 'unknown';
+/**
+ * Conflict-resolution policy used by the frontmatter validator when an
+ * Anthropic-base field and the equivalent `graphorin-*` field are both
+ * declared.
+ *
+ * @stable
+ */
+type FrontmatterValidatorPolicy = 'warn' | 'error' | 'silent';
+/**
+ * Policy applied to frontmatter fields that are present but recognised
+ * neither by the bundled spec snapshot nor by the `graphorin-*`
+ * extension catalogue.
+ *
+ * @stable
+ */
+type UnknownFieldPolicy = 'preserve' | 'reject' | 'warn';
+/**
+ * Trust level applied to a loaded skill. Mirrors the supply-chain
+ * trust ladder + the loader's `'unknown'` extension so callers do
+ * not have to bridge two enums.
+ *
+ * @stable
+ */
+type SkillTrustLevelValue = SkillsTrustLevel;
+/**
+ * Source descriptor for a {@link loadSkills} request.
+ *
+ * - `'folder'`      — load from a directory on disk.
+ * - `'npm-package'` — install via the supply-chain installer + load.
+ * - `'git-repo'`    — shallow-clone via the supply-chain installer +
+ *   load.
+ * - `'inline'`      — the caller supplies a parsed skill structure;
+ *   useful for tests and embedded fixtures.
+ *
+ * @stable
+ */
+type SkillSource = {
+  readonly kind: 'folder';
+  readonly path: string;
+  /**
+   * Operator-supplied trust level. When present it overrides the
+   * skill's self-declared `graphorin-trust-level`. Without it, a
+   * folder's self-declared `trusted` / `trusted-with-scripts` is
+   * capped at `'unknown'` — a downloaded directory cannot promote
+   * itself; trust is granted by the integrator, never the artifact.
+   */
+  readonly trustLevel?: SkillTrustLevel;
+} | {
+  readonly kind: 'npm-package';
+  readonly packageName: string;
+  readonly version?: string;
+  readonly trustLevel?: SkillTrustLevel;
+} | {
+  readonly kind: 'git-repo';
+  readonly url: string;
+  readonly ref?: string;
+  readonly trustLevel?: SkillTrustLevel;
+} | {
+  readonly kind: 'inline';
+  readonly skill: InlineSkill;
+};
+/**
+ * Pre-built tool record accepted by the inline source. The loader
+ * does not parse the tool — it forwards the record to the agent
+ * runtime which feeds it through `stampSkillTool(...)` before
+ * registering with `@graphorin/tools`.
+ *
+ * @stable
+ */
+type InlineSkillTool = Tool;
+/**
+ * Pre-built skill payload accepted by `{ kind: 'inline' }`. Bypasses
+ * the file-system loader; useful for tests and bundled defaults.
+ *
+ * @stable
+ */
+interface InlineSkill {
+  readonly skillMd: string;
+  readonly basePath?: string;
+  readonly resources?: ReadonlyArray<{
+    readonly path: string;
+    readonly content: string;
+  }>;
+  /**
+   * Pre-built `Tool[]` payload. When supplied, the loader exposes
+   * these via {@link Skill.tools} so {@link SkillRegistry.tools}
+   * returns them deduplicated by `tool.name`.
+   *
+   * Folder / npm / git sources do not carry tool implementations —
+   * the agent runtime (Phase 12) materialises them from the skill's
+   * `tools/` directory. The inline source is the only path through
+   * which tests + bundled defaults can ship pre-built tools.
+   */
+  readonly tools?: ReadonlyArray<InlineSkillTool>;
+}
+/**
+ * Resolution outcome of a single field on a `SKILL.md` frontmatter.
+ *
+ * @stable
+ */
+interface FieldResolution<T = unknown> {
+  readonly value: T | undefined;
+  readonly source: 'anthropic-base' | 'metadata-graphorin' | 'graphorin-prefix' | 'fallback';
+  readonly conflicting: boolean;
+  readonly conflictingSources: ReadonlyArray<string>;
+}
+/**
+ * Diagnostic record produced by the frontmatter validator. Carries a
+ * structured `kind` so the loader can surface the diagnostic on a
+ * trace span / audit emitter without re-parsing the human message.
+ *
+ * @stable
+ */
+interface FrontmatterDiagnostic {
+  readonly kind: 'conflict' | 'experimental-field' | 'unknown-field' | 'spec-newer-than-loader' | 'spec-older-than-loader' | 'unsupported-frontmatter' | 'invalid-field-type' | 'missing-required-field' | 'untrusted-handoff-filter-required' | 'invalid-runtime-compat';
+  readonly field: string;
+  readonly severity: 'info' | 'warn' | 'error';
+  readonly message: string;
+  readonly hint?: string;
+}
+/**
+ * Validated skill metadata. Always available on the registry without
+ * loading the body — this is the always-present **Tier 1** payload
+ * that the system prompt advertises.
+ *
+ * @stable
+ */
+interface SkillMetadata {
+  readonly name: string;
+  readonly description: string;
+  readonly license?: string;
+  readonly compatibility?: string;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+  readonly allowedTools?: ReadonlyArray<string>;
+  readonly disableModelInvocation: boolean;
+  readonly graphorinTrustLevel: SkillsTrustLevel;
+  readonly graphorinRuntimeCompat?: string;
+  readonly graphorinSensitivity?: string;
+  readonly graphorinSensitivityDefaults?: Readonly<Record<string, string>>;
+  readonly graphorinSandbox?: Readonly<Record<string, unknown>>;
+  readonly graphorinHandoffInputFilter?: HandoffInputFilterDeclaration;
+  readonly graphorinSignaturePresent: boolean;
+  readonly graphorinAnthropicSpec?: string;
+  /** Author-declared graphorin runtime / extension version. */
+  readonly graphorinVersion?: string;
+  /** Raw frontmatter (read-only) for power users — every loader user can re-derive bespoke fields. */
+  readonly raw: Readonly<Record<string, unknown>>;
+}
+/**
+ * `graphorin-handoff-input-filter` declaration recognised by the
+ * loader. The runtime resolves the declaration into the actual filter
+ * implementation in Phase 12; the loader only validates the shape.
+ *
+ * @stable
+ */
+type HandoffInputFilterDeclaration = {
+  readonly kind: 'lastUser';
+} | {
+  readonly kind: 'lastN';
+  readonly n: number;
+} | {
+  readonly kind: 'summary';
+} | {
+  readonly kind: 'full';
+} | {
+  readonly kind: 'compose';
+  readonly steps: ReadonlyArray<HandoffInputFilterStep>;
+};
+/**
+ * Composable step recognised inside `graphorin-handoff-input-filter:
+ * { compose: [...] }`. The runtime resolves named steps into actual
+ * filter implementations in Phase 12.
+ *
+ * @stable
+ */
+type HandoffInputFilterStep = {
+  readonly kind: 'lastUser';
+} | {
+  readonly kind: 'lastN';
+  readonly n: number;
+} | {
+  readonly kind: 'summary';
+} | {
+  readonly kind: 'stripSensitiveOutputs';
+  readonly keepTier?: string;
+} | {
+  readonly kind: 'stripReasoning';
+};
+/**
+ * Tool declaration found inside `graphorin-tools:`. The loader only
+ * captures the declarations; the actual `Tool[]` is produced by the
+ * skill author's `tools/*.ts` modules and bridged into the
+ * `@graphorin/tools` registry by the agent runtime in Phase 12.
+ *
+ * @stable
+ */
+interface SkillToolDeclaration {
+  readonly name: string;
+  readonly module?: string;
+  readonly description?: string;
+  readonly tags?: ReadonlyArray<string>;
+}
+/**
+ * Lazy resource accessor returned by {@link Skill.resources}. The
+ * loader does not read the file off disk until `.read()` is invoked.
+ *
+ * @stable
+ */
+interface SkillResource {
+  readonly path: string;
+  readonly relativePath: string;
+  readonly mediaType?: string;
+  read(signal?: AbortSignal): Promise<Uint8Array>;
+  readText(signal?: AbortSignal): Promise<string>;
+}
+/**
+ * Loaded skill record returned by {@link SkillRegistry.getSkill} and
+ * {@link loadSkills}. Three-tier semantics:
+ *
+ * - {@link Skill.metadata} — always available (parsed at load time).
+ * - {@link Skill.body}     — lazy; resolved on first call. Cached for
+ *   subsequent calls.
+ * - {@link Skill.resources} — lazy listing; resource bytes are only
+ *   read when {@link SkillResource.read} is invoked.
+ * - {@link Skill.tools}    — derived from the `graphorin-tools`
+ *   declarations; the actual `Tool[]` is materialised by the agent
+ *   runtime through the `@graphorin/tools` registry.
+ *
+ * @stable
+ */
+interface Skill {
+  readonly metadata: SkillMetadata;
+  readonly source: SkillSource;
+  readonly basePath?: string;
+  readonly trustPolicy: ResolvedSkillTrustPolicy;
+  readonly signature?: SkillSignatureVerificationResult;
+  body(signal?: AbortSignal): Promise<string>;
+  resources(signal?: AbortSignal): Promise<ReadonlyArray<SkillResource>>;
+  /**
+   * Pre-built tools shipped with the skill. The inline source is the
+   * only path through which the loader carries actual `Tool[]`
+   * records; folder / npm / git sources return `[]` here and the
+   * agent runtime (Phase 12) materialises tools from the
+   * `graphorin-tools` declarations + the skill's `tools/` directory.
+   */
+  tools(): ReadonlyArray<InlineSkillTool>;
+  toolDeclarations(): ReadonlyArray<SkillToolDeclaration>;
+  diagnostics(): ReadonlyArray<FrontmatterDiagnostic>;
+}
+/**
+ * Activated skill — what the agent runtime sees after the model (or a
+ * slash command) elects a skill. Carries the loaded body + declared
+ * tools so the runtime can inject them into the conversation.
+ *
+ * @stable
+ */
+interface ActivatedSkill {
+  readonly skill: Skill;
+  readonly body: string;
+  readonly resources: ReadonlyArray<SkillResource>;
+  /**
+   * Tools made available to the model while the skill is active.
+   * The agent runtime (Phase 12) is the canonical producer — it
+   * resolves the skill's `tools/` directory or the inline-supplied
+   * `Tool[]` and feeds each entry through `stampSkillTool(...)` so
+   * the resulting `ResolvedTool` carries the right trust class +
+   * sandbox tier.
+   */
+  readonly tools: ReadonlyArray<ResolvedTool>;
+  readonly activationKind: 'auto' | 'slash-command' | 'explicit';
+  readonly activatedAt: number;
+}
+/**
+ * Result of {@link parseSlashCommand}. The loader parses
+ * `/skill:<name>` and `/skill:<name> <free-form-args>` into a
+ * structured payload the agent runtime consumes.
+ *
+ * @stable
+ */
+interface SlashCommandActivation {
+  readonly name: string;
+  readonly args: string;
+  readonly raw: string;
+}
+//#endregion
+export { ActivatedSkill, FieldResolution, FrontmatterDiagnostic, FrontmatterValidatorPolicy, HandoffInputFilterDeclaration, HandoffInputFilterStep, InlineSkill, InlineSkillTool, type ResolvedSkillTrustPolicy, Skill, SkillMetadata, SkillResource, type SkillSignatureVerificationResult, SkillSource, SkillToolDeclaration, type SkillTrustLevel, SkillTrustLevelValue, SkillsTrustLevel, SlashCommandActivation, type SupplyChainSkillSource, UnknownFieldPolicy };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/types/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;AA0GA;AAQA;;;;;AAsBA;AAcA;AAyBA;AAK+B,KAtJnB,gBAAA,GAAmB,eAsJA,GAAA,SAAA;;;;;;;;AAQU,KArJ7B,0BAAA,GAqJ6B,MAAA,GAAA,OAAA,GAAA,QAAA;;;;AAgBzC;AAiBA;AAkBA;AAaA;AAIgB,KAhNJ,kBAAA,GAgNI,UAAA,GAAA,QAAA,GAAA,MAAA;;;;;;AAmBhB;;AAEmB,KA5NP,oBAAA,GAAuB,gBA4NhB;;;;;;;;;;;;;AAeY,KA7NnB,WAAA,GA6NmB;EAAd,SAAA,IAAA,EAAA,QAAA;EAAa,SAAA,IAAA,EAAA,MAAA;EAUb;;;;;;;EAwBA,SAAA,UAAA,CAAA,EApPW,eAoPW;;;;;wBA9OX;;;;;wBAMA;;;kBAEmB;;;;;;;;;;KAUnC,eAAA,GAAkB;;;;;;;UAQb,WAAA;;;uBAGM;;;;;;;;;;;;;;mBAWJ,cAAc;;;;;;;UAQhB;kBACC;;;+BAGa;;;;;;;;;UAUd,qBAAA;;;;;;;;;;;;;;UAyBA,aAAA;;;;;sBAKK,SAAS;0BACL;;gCAEM;;;0CAGU,SAAS;8BACrB,SAAS;yCACE;;;;;;gBAMzB,SAAS;;;;;;;;;KAUb,6BAAA;;;;;;;;;;;kBAOU,cAAc;;;;;;;;;KAUxB,sBAAA;;;;;;;;;;;;;;;;;;;;;UAkBK,oBAAA;;;;kBAIC;;;;;;;;UASD,aAAA;;;;gBAID,cAAc,QAAQ;oBAClB,cAAc;;;;;;;;;;;;;;;;;UAkBjB,KAAA;qBACI;mBACF;;wBAEK;uBACD;gBACP,cAAc;qBACT,cAAc,QAAQ,cAAc;;;;;;;;WAQ9C,cAAc;sBACH,cAAc;iBACnB,cAAc;;;;;;;;;UAUd,cAAA;kBACC;;sBAEI,cAAc;;;;;;;;;kBASlB,cAAc;;;;;;;;;;;UAYf,sBAAA"}