@graphorin/skills 0.6.1 → 0.7.0

package/src/migration/index.ts

@@ -0,0 +1,192 @@
+/**
+ * `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
+ */
+
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+
+import { SkillManifestParseError } from '../errors/index.js';
+import { splitSkillMd } from '../frontmatter/index.js';
+import { getSpecSnapshot } from '../spec/index.js';
+
+/** A single rewrite the migrator applied (or would apply in a dry-run). */
+export interface MigrationRewrite {
+  readonly fromField: string;
+  readonly toField: string;
+  readonly reason: 'deprecate-graphorin-prefix' | 'co-exist-noop' | 'graphorin-only-noop';
+  readonly applied: boolean;
+}
+
+/** Result of a single SKILL.md migration. */
+export interface MigrationResult {
+  readonly skillId: string;
+  readonly rewrites: ReadonlyArray<MigrationRewrite>;
+  readonly originalSkillMd: string;
+  readonly migratedSkillMd: string;
+  readonly changed: boolean;
+}
+
+/** Options accepted by {@link migrateFrontmatter}. */
+export interface MigrateFrontmatterOptions {
+  /** Identifier used in audit / error messages. Defaults to `'<inline>'`. */
+  readonly skillId?: string;
+  /**
+   * When `true`, rewrites are applied to the returned `migratedSkillMd`.
+   * When `false` (default), `migratedSkillMd === originalSkillMd` and
+   * the function operates as a dry-run report.
+   */
+  readonly apply?: boolean;
+}
+
+/**
+ * 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
+ */
+export function migrateFrontmatter(
+  skillMd: string,
+  options: MigrateFrontmatterOptions = {},
+): MigrationResult {
+  const skillId = options.skillId ?? '<inline>';
+  const apply = options.apply ?? false;
+  const split = splitSkillMd(skillMd);
+  let frontmatter: unknown;
+  try {
+    frontmatter = parseYaml(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 as Record<string, unknown>) };
+
+  const snapshot = getSpecSnapshot();
+  const rewrites: MigrationRewrite[] = [];
+  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) {
+      // Both fields are already set - the validator will surface the
+      // diagnostic at load time. The migrator does not silently drop
+      // either side; the operator is expected to remove the redundant
+      // `graphorin-*` field manually after reviewing the diagnostic.
+      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 sortedFm = sortKeysAnthropicFirst(fm);
+  const migratedFrontmatter = stringifyYaml(sortedFm, {
+    sortMapEntries: false,
+    lineWidth: 0,
+  }).trimEnd();
+  const migratedSkillMd = `---\n${migratedFrontmatter}\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
+ */
+export function sortKeysAnthropicFirst(
+  frontmatter: Record<string, unknown>,
+): Record<string, unknown> {
+  const snapshot = getSpecSnapshot();
+  const baseKeys = Object.keys(snapshot.knownFields);
+  const out: Record<string, unknown> = {};
+  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;
+}

package/src/registry/bridge.ts

@@ -0,0 +1,169 @@
+/**
+ * Helper functions that bridge skill-bundled `Tool` records into the
+ * `@graphorin/tools` registry.
+ *
+ * The skills loader does not import the runtime registry directly -
+ * downstream callers (the agent runtime in Phase 12, the test suite,
+ * and any user-supplied bootstrap script) materialise the actual
+ * `Tool[]` from the skill module surface and feed each one through
+ * {@link stampSkillTool} to get a {@link Tool} + a {@link ToolSource}
+ * pair the registry can register with the correct trust-class
+ * derivation, sandbox tier propagation, and inbound-sanitization
+ * defaults.
+ *
+ * @packageDocumentation
+ */
+
+import type { InboundSanitizationPolicy, SandboxPolicy, Tool, ToolSource } from '@graphorin/core';
+import { resolveSandbox, type SandboxTrustLevel } from '@graphorin/security/sandbox';
+
+import type { Skill, SkillMetadata } from '../types/index.js';
+
+/** Result of {@link stampSkillTool}. */
+export 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
+ */
+export function stampSkillTool<TInput = unknown, TOutput = unknown, TDeps = unknown>(
+  tool: Tool<TInput, TOutput, TDeps>,
+  skill: Pick<Skill, 'metadata'>,
+): StampedSkillTool<TInput, TOutput, TDeps> {
+  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
+ */
+export function stampSkillToolFromMetadata<TInput = unknown, TOutput = unknown, TDeps = unknown>(
+  tool: Tool<TInput, TOutput, TDeps>,
+  metadata: SkillMetadata,
+): StampedSkillTool<TInput, TOutput, TDeps> {
+  const trustLevel = mapTrustLevel(metadata.graphorinTrustLevel);
+  const sandboxResolverArgs: Parameters<typeof resolveSandbox>[0] = {
+    trustLevel,
+  };
+  if (tool.name !== undefined)
+    (sandboxResolverArgs as Mutable<typeof sandboxResolverArgs>).toolName = tool.name;
+  if (metadata.name !== undefined)
+    (sandboxResolverArgs as Mutable<typeof sandboxResolverArgs>).skillName = metadata.name;
+  const operatorOverride = sandboxOverrideFromTool(tool);
+  if (operatorOverride !== undefined)
+    (sandboxResolverArgs as Mutable<typeof sandboxResolverArgs>).override = operatorOverride;
+  const resolvedSandbox = resolveSandbox(sandboxResolverArgs);
+  const inboundSanitization = inboundSanitizationFor(tool, metadata.graphorinTrustLevel);
+  const stamped: Mutable<Tool<TInput, TOutput, TDeps>> = {
+    ...tool,
+    sandboxPolicy: mapSandboxKindToPolicy(resolvedSandbox.kind),
+    ...(inboundSanitization === undefined ? {} : { inboundSanitization }),
+  };
+  const source: ToolSource = Object.freeze({
+    kind: 'skill' as const,
+    skillName: metadata.name,
+    // 'unknown' inherits the strict sandbox policy of 'untrusted', so
+    // the agent runtime registers the source as untrusted too - that
+    // forces the inbound-sanitization default
+    // ('detect-and-strip-and-wrap') and the precedence ladder used by
+    // collision resolution to demote it relative to first-party
+    // / trusted-skill registrations.
+    trustLevel:
+      metadata.graphorinTrustLevel === 'untrusted' || metadata.graphorinTrustLevel === 'unknown'
+        ? 'untrusted'
+        : 'trusted',
+  });
+  return Object.freeze({
+    tool: Object.freeze(stamped) as Tool<TInput, TOutput, TDeps>,
+    source,
+    resolvedSandbox,
+    sandboxForced: resolvedSandbox.forced,
+    inboundSanitizationForced:
+      inboundSanitization !== undefined && tool.inboundSanitization === undefined,
+  });
+}
+
+function mapTrustLevel(level: SkillMetadata['graphorinTrustLevel']): SandboxTrustLevel {
+  switch (level) {
+    case 'untrusted':
+    case 'unknown':
+      // Phase 08 § Risks & mitigations: 'unknown' enforces sandbox
+      // without requiring signature, so the sandbox tier resolver
+      // applies the same strict policy as 'untrusted'.
+      return 'untrusted';
+    case 'trusted':
+    case 'trusted-with-scripts':
+      return 'trusted';
+    default: {
+      const exhaustive: never = level;
+      void exhaustive;
+      return 'user-defined';
+    }
+  }
+}
+
+function mapSandboxKindToPolicy(kind: ReturnType<typeof resolveSandbox>['kind']): SandboxPolicy {
+  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: Pick<Tool, 'inboundSanitization'>,
+  trustLevel: SkillMetadata['graphorinTrustLevel'],
+): InboundSanitizationPolicy | undefined {
+  if (tool.inboundSanitization !== undefined) return tool.inboundSanitization;
+  if (trustLevel === 'untrusted' || trustLevel === 'unknown') {
+    return 'detect-and-strip-and-wrap';
+  }
+  return undefined;
+}
+
+function sandboxOverrideFromTool(
+  tool: Pick<Tool, 'sandboxPolicy'>,
+): { readonly kind?: ReturnType<typeof resolveSandbox>['kind'] } | undefined {
+  switch (tool.sandboxPolicy) {
+    case undefined:
+      return undefined;
+    case 'none':
+      return { kind: 'none' };
+    case 'sandboxed':
+      return { kind: 'worker-threads' };
+    case 'isolated':
+      return { kind: 'isolated-vm' };
+    case 'docker':
+      return { kind: 'docker' };
+    default:
+      return undefined;
+  }
+}
+
+type Mutable<T> = { -readonly [K in keyof T]: T[K] };