@frontmcp/adapters 1.1.2 → 1.2.0

package/esm/skills/index.mjs

@@ -0,0 +1,2117 @@
+// libs/adapters/src/skills/bundle/bundle.types.ts
+function bundleSkillToActions(skill, ops) {
+  return skill.operationIds.map((opId) => {
+    const op = ops[opId];
+    if (!op) {
+      throw new Error(`bundleSkillToActions: skill "${skill.id}" references unknown operationId "${opId}"`);
+    }
+    const action = {
+      actionId: op.operationId,
+      summary: op.summary ?? `${op.httpMethod} ${op.pathTemplate}`,
+      ...op.description !== void 0 && { description: op.description },
+      inputJsonSchema: op.inputSchema,
+      outputJsonSchema: op.outputSchema,
+      ...op.requiredAuthorities !== void 0 && { requiredAuthorities: op.requiredAuthorities }
+    };
+    return action;
+  });
+}
+
+// libs/adapters/src/skills/bundle/bundle.schema.ts
+import { z } from "@frontmcp/lazy-zod";
+var httpMethodSchema = z.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"]);
+var pathTemplateRegex = /^\/[^\s?#]*$/;
+var FORBIDDEN_PATH_FRAGMENTS = ["..", "\\", "`", "$(", "${"];
+var pathTemplateSchema = z.string().min(1).max(2048).refine((v) => pathTemplateRegex.test(v), {
+  message: "pathTemplate must start with `/` and contain no whitespace, `?`, or `#`"
+}).refine((v) => !FORBIDDEN_PATH_FRAGMENTS.some((bad) => v.includes(bad)), {
+  message: "pathTemplate contains a forbidden character or fragment (`..`, backtick, `$(`, etc.)"
+});
+var jsonSchemaShape = z.record(z.string(), z.unknown());
+var authoritiesPolicySchema = z.record(z.string(), z.unknown());
+var authBindingSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("none") }).strict(),
+  z.object({
+    kind: z.literal("bearer"),
+    vaultRef: z.string().min(1).max(256),
+    passthroughCallerToken: z.boolean().optional()
+  }).strict(),
+  z.object({
+    kind: z.literal("apiKey"),
+    in: z.enum(["header", "query"]),
+    name: z.string().min(1).max(128).regex(/^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/, "apiKey name must match RFC 7230 token grammar"),
+    vaultRef: z.string().min(1).max(256)
+  }).strict(),
+  z.object({
+    kind: z.literal("oauth2"),
+    flow: z.literal("client_credentials"),
+    vaultRef: z.string().min(1).max(256)
+  }).strict()
+]);
+var serviceDescriptorSchema = z.object({
+  id: z.string().min(1).max(128).regex(/^[a-zA-Z0-9_-]+$/, "service id must be alphanumeric / `-` / `_`"),
+  baseUrl: z.string().url().max(2048),
+  description: z.string().max(4096).optional()
+}).strict();
+var parameterMapperSchema = z.object({
+  inputKey: z.string().min(1).max(256),
+  type: z.enum(["path", "query", "header", "cookie", "body"]),
+  key: z.string().min(1).max(256),
+  required: z.boolean().optional(),
+  style: z.string().max(64).optional(),
+  explode: z.boolean().optional(),
+  serialization: z.record(z.string(), z.unknown()).optional(),
+  security: z.record(z.string(), z.unknown()).optional()
+}).passthrough();
+var operationDescriptorSchema = z.object({
+  operationId: z.string().min(1).max(256).regex(/^[a-zA-Z0-9_.\-:]+$/, "operationId must be alphanumeric / `-` / `_` / `.` / `:`"),
+  serviceId: z.string().min(1).max(128),
+  httpMethod: httpMethodSchema,
+  pathTemplate: pathTemplateSchema,
+  inputSchema: jsonSchemaShape,
+  outputSchema: jsonSchemaShape,
+  mapper: z.array(parameterMapperSchema).max(256),
+  authBindingRef: z.string().min(1).max(128),
+  requiredAuthorities: authoritiesPolicySchema.optional(),
+  maxResponseBytes: z.number().int().positive().max(64 * 1024 * 1024).optional(),
+  timeoutMs: z.number().int().positive().max(6e5).optional(),
+  summary: z.string().max(512).optional(),
+  description: z.string().max(8192).optional()
+}).strict();
+var bundledSkillSchema = z.object({
+  id: z.string().min(1).max(128).regex(/^[a-zA-Z0-9_.-]+$/),
+  name: z.string().min(1).max(256),
+  description: z.string().max(2048),
+  instructions: z.string().max(256 * 1024),
+  tags: z.array(z.string().max(64)).max(64).optional(),
+  operationIds: z.array(z.string().min(1).max(256)).min(0).max(2e3),
+  requiredAuthorities: authoritiesPolicySchema.optional(),
+  /**
+   * Other skill ids this skill depends on. Hosts that consume the bundle
+   * register skills in dependency order; cycles and missing deps are caught
+   * at apply time. Field name aligned with the agentskills Skill Package
+   * Manifest proposal (https://github.com/agentskills/agentskills/discussions/210)
+   * so bundles round-trip across runtimes without a schema bump.
+   */
+  requires: z.array(z.string().min(1).max(128)).max(64).optional()
+}).strict();
+var integritySchema = z.object({
+  alg: z.enum(["RS256", "EdDSA"]),
+  keyId: z.string().min(1).max(256),
+  signature: z.string().min(1).max(8192),
+  digest: z.string().min(1).max(256)
+}).strict();
+var resolvedBundleSchema = z.object({
+  schemaVersion: z.literal(1),
+  bundleId: z.string().min(1).max(256).regex(/^[a-zA-Z0-9_.\-:]+$/),
+  version: z.string().min(1).max(256),
+  generatedAt: z.string().min(1).refine((v) => !Number.isNaN(Date.parse(v)), { message: "generatedAt must be ISO 8601 parsable" }),
+  sourceDigest: z.string().min(1).max(256).regex(/^[a-fA-F0-9]+$/, "sourceDigest must be a hex sha256"),
+  services: z.array(serviceDescriptorSchema).min(1).max(64),
+  authBindings: z.record(z.string().min(1).max(128), authBindingSchema),
+  skills: z.array(bundledSkillSchema).max(1e3),
+  operations: z.record(z.string().min(1).max(256), operationDescriptorSchema),
+  integrity: integritySchema.optional()
+}).strict();
+function crossValidate(bundle) {
+  const errors = [];
+  const serviceIds = new Set(bundle.services.map((s) => s.id));
+  const authRefs = new Set(Object.keys(bundle.authBindings));
+  const opIds = new Set(Object.keys(bundle.operations));
+  for (const [opId, op] of Object.entries(bundle.operations)) {
+    if (op.operationId !== opId) {
+      errors.push(`operation key "${opId}" does not match operationId "${op.operationId}"`);
+    }
+    if (!serviceIds.has(op.serviceId)) {
+      errors.push(`operation "${opId}" references unknown service "${op.serviceId}"`);
+    }
+    if (!authRefs.has(op.authBindingRef)) {
+      errors.push(`operation "${opId}" references unknown authBinding "${op.authBindingRef}"`);
+    }
+  }
+  const seenSkillIds = /* @__PURE__ */ new Set();
+  for (const skill of bundle.skills) {
+    if (seenSkillIds.has(skill.id)) {
+      errors.push(`duplicate skill id "${skill.id}"`);
+    }
+    seenSkillIds.add(skill.id);
+    for (const opId of skill.operationIds) {
+      if (!opIds.has(opId)) {
+        errors.push(`skill "${skill.id}" references unknown operationId "${opId}"`);
+      }
+    }
+  }
+  return errors.length === 0 ? { ok: true } : { ok: false, errors };
+}
+
+// libs/adapters/src/skills/bundle/overlay-parser.ts
+import * as yaml from "js-yaml";
+var OVERLAY_BUNDLE_KEY = "x-frontmcp-bundle";
+var OverlayParseError = class extends Error {
+  constructor(message, errors) {
+    super(message);
+    this.errors = errors;
+    this.name = "OverlayParseError";
+  }
+};
+function parseRaw(input) {
+  switch (input.kind) {
+    case "yaml":
+      try {
+        return yaml.load(input.content);
+      } catch (e) {
+        throw new OverlayParseError(`Overlay YAML parse failed: ${e.message}`);
+      }
+    case "json":
+      try {
+        return JSON.parse(input.content);
+      } catch (e) {
+        throw new OverlayParseError(`Overlay JSON parse failed: ${e.message}`);
+      }
+    case "object":
+      return input.content;
+  }
+}
+function extractBundle(overlay) {
+  if (overlay === null || typeof overlay !== "object") {
+    throw new OverlayParseError("Overlay root must be an object");
+  }
+  const root = overlay;
+  if (OVERLAY_BUNDLE_KEY in root) {
+    return root[OVERLAY_BUNDLE_KEY];
+  }
+  const info = root["info"];
+  if (info && typeof info === "object" && OVERLAY_BUNDLE_KEY in info) {
+    return info[OVERLAY_BUNDLE_KEY];
+  }
+  if ("schemaVersion" in root && "bundleId" in root) {
+    return root;
+  }
+  throw new OverlayParseError(
+    "Overlay does not contain `info.x-frontmcp-bundle` or a bare bundle object with schemaVersion + bundleId"
+  );
+}
+function parseOverlay(input) {
+  const raw = parseRaw(input);
+  const bundleCandidate = extractBundle(raw);
+  const result = resolvedBundleSchema.safeParse(bundleCandidate);
+  if (!result.success) {
+    const errors = result.error.issues.map((i) => `${i.path.join(".") || "<root>"}: ${i.message}`);
+    throw new OverlayParseError(`Bundle schema validation failed (${errors.length} issue(s))`, errors);
+  }
+  const cross = crossValidate(result.data);
+  if (!cross.ok) {
+    throw new OverlayParseError(
+      `Bundle cross-reference validation failed (${cross.errors.length} issue(s))`,
+      cross.errors
+    );
+  }
+  return result.data;
+}
+
+// libs/adapters/src/skills/bundle/bundle-diff.ts
+var opEqual = (a, b) => a.operationId === b.operationId && a.serviceId === b.serviceId && a.httpMethod === b.httpMethod && a.pathTemplate === b.pathTemplate && a.authBindingRef === b.authBindingRef && JSON.stringify(a.mapper ?? null) === JSON.stringify(b.mapper ?? null) && JSON.stringify(a.inputSchema) === JSON.stringify(b.inputSchema) && JSON.stringify(a.outputSchema) === JSON.stringify(b.outputSchema) && JSON.stringify(a.requiredAuthorities ?? null) === JSON.stringify(b.requiredAuthorities ?? null) && a.maxResponseBytes === b.maxResponseBytes && a.timeoutMs === b.timeoutMs;
+var skillEqual = (a, b) => a.id === b.id && a.name === b.name && a.description === b.description && a.instructions === b.instructions && JSON.stringify(a.tags ?? []) === JSON.stringify(b.tags ?? []) && JSON.stringify(a.operationIds) === JSON.stringify(b.operationIds) && JSON.stringify(a.requiredAuthorities ?? null) === JSON.stringify(b.requiredAuthorities ?? null);
+function diffBundles(oldBundle, newBundle) {
+  const oldSkills = new Map((oldBundle?.skills ?? []).map((s) => [s.id, s]));
+  const newSkills = new Map(newBundle.skills.map((s) => [s.id, s]));
+  const addedSkillIds = [];
+  const removedSkillIds = [];
+  const changedSkillIds = [];
+  for (const [id, skill] of newSkills) {
+    const prev = oldSkills.get(id);
+    if (!prev) addedSkillIds.push(id);
+    else if (!skillEqual(prev, skill)) changedSkillIds.push(id);
+  }
+  for (const id of oldSkills.keys()) {
+    if (!newSkills.has(id)) removedSkillIds.push(id);
+  }
+  const oldOps = oldBundle?.operations ?? {};
+  const newOps = newBundle.operations;
+  const addedOperationIds = [];
+  const removedOperationIds = [];
+  const changedOperationIds = [];
+  for (const [id, op] of Object.entries(newOps)) {
+    const prev = oldOps[id];
+    if (!prev) addedOperationIds.push(id);
+    else if (!opEqual(prev, op)) changedOperationIds.push(id);
+  }
+  for (const id of Object.keys(oldOps)) {
+    if (!(id in newOps)) removedOperationIds.push(id);
+  }
+  const isNoOp = !!oldBundle && oldBundle.version === newBundle.version && addedSkillIds.length === 0 && removedSkillIds.length === 0 && changedSkillIds.length === 0 && addedOperationIds.length === 0 && removedOperationIds.length === 0 && changedOperationIds.length === 0;
+  return {
+    addedSkillIds,
+    removedSkillIds,
+    changedSkillIds,
+    addedOperationIds,
+    removedOperationIds,
+    changedOperationIds,
+    isNoOp
+  };
+}
+function formatDiffSummary(diff) {
+  if (diff.isNoOp) return "no-op";
+  return [
+    `+${diff.addedSkillIds.length}/-${diff.removedSkillIds.length}/~${diff.changedSkillIds.length} skills`,
+    `+${diff.addedOperationIds.length}/-${diff.removedOperationIds.length}/~${diff.changedOperationIds.length} ops`
+  ].join(", ");
+}
+
+// libs/adapters/src/skills/bundle/bundle.store.ts
+var KNOWN_BUNDLE_SOURCES = ["static", "npm", "saas-pull", "webhook", "filesystem", "unknown"];
+function normalizeBundleSource(value) {
+  if (typeof value !== "string") return "unknown";
+  return KNOWN_BUNDLE_SOURCES.includes(value) ? value : "unknown";
+}
+function classifySwapError(err) {
+  if (err instanceof BundlePinnedError) return "pinned";
+  if (err instanceof Error) {
+    const name = err.name;
+    const msg = err.message.toLowerCase();
+    if (name === "BundlePinnedError") return "pinned";
+    if (msg.includes("bundle is required") || msg.includes("malformed")) return "invalid_bundle";
+    if (msg.includes("listener")) return "listener_error";
+  }
+  return "unknown";
+}
+var BundleStore = class {
+  active;
+  listeners = /* @__PURE__ */ new Set();
+  history = [];
+  pinnedVersion;
+  historySize;
+  telemetry;
+  pullsCounter;
+  constructor(options = {}) {
+    const requested = options.historySize ?? 3;
+    if (!Number.isInteger(requested) || requested < 1) {
+      throw new Error("BundleStore: historySize must be a positive integer");
+    }
+    this.historySize = requested;
+    this.telemetry = options.telemetry;
+    this.pullsCounter = this.telemetry?.createCounter(
+      "frontmcp_skills_bundle_pulls_total",
+      "Number of bundle pulls (swaps) attempted, partitioned by status / source."
+    );
+  }
+  current() {
+    return this.active;
+  }
+  /**
+   * Swap to a new bundle. Returns the structural diff (no-op = same version
+   * with no field changes; the swap itself still fires listeners with isNoOp=true
+   * so observers can record the heartbeat).
+   *
+   * Throws when the store is pinned. The caller should check `isPinned()` first
+   * if it wants to skip silently rather than throw.
+   *
+   * @param next   - new bundle to activate
+   * @param source - optional source label (e.g. `npm`, `saas-pull`, `webhook`)
+   *                 used as a counter / span attribute. When omitted, `unknown`
+   *                 is reported.
+   */
+  swap(next, source) {
+    if (!next) {
+      throw new Error("BundleStore.swap: bundle is required");
+    }
+    const sourceLabel = normalizeBundleSource(source);
+    if (this.telemetry) {
+      const span = this.telemetry.startSpan("skill.bundle.swap", {
+        source: sourceLabel,
+        bundle_id: next.bundleId,
+        version: next.version,
+        skill_count: next.skills.length,
+        ...this.active?.version ? { from_version: this.active.version } : {}
+      });
+      try {
+        if (this.pinnedVersion !== void 0) {
+          throw new BundlePinnedError(this.pinnedVersion);
+        }
+        const diff = this.commit(next, "normal");
+        span.setAttributes({ status: "ok", is_no_op: diff.isNoOp });
+        span.end();
+        this.pullsCounter?.inc(1, { status: "ok", source: sourceLabel });
+        return diff;
+      } catch (err) {
+        const reason = classifySwapError(err);
+        if (span.endWithError) {
+          span.endWithError(err instanceof Error ? err : String(err));
+        } else {
+          span.recordError?.(err instanceof Error ? err : new Error(String(err)));
+          span.end();
+        }
+        this.pullsCounter?.inc(1, { status: "error", source: sourceLabel, reason });
+        throw err;
+      }
+    }
+    if (this.pinnedVersion !== void 0) {
+      throw new BundlePinnedError(this.pinnedVersion);
+    }
+    return this.commit(next, "normal");
+  }
+  /**
+   * Pin the active bundle to a specific historical version. Pinned stores
+   * reject `swap()` so source-driven updates accumulate elsewhere without
+   * activating. Returns the diff of the swap that activated the pinned
+   * version, or undefined if the pinned version was already active.
+   *
+   * Throws when `version` is unknown to the store's history.
+   */
+  pin(version) {
+    if (this.active && this.active.version === version) {
+      this.pinnedVersion = version;
+      return void 0;
+    }
+    const entry = this.history.find((h) => h.bundle.version === version);
+    if (!entry) {
+      throw new Error(`BundleStore.pin: version "${version}" not in history`);
+    }
+    const diff = this.commit(entry.bundle, "pin");
+    this.pinnedVersion = version;
+    return diff;
+  }
+  /**
+   * Re-activate the most recent bundle in history (the bundle that was
+   * active before the current one). Useful after a bad swap is detected.
+   * Returns the diff. Throws when no prior bundle is available.
+   *
+   * Rollback does NOT pin — sources can resume auto-swapping after rollback.
+   */
+  rollback() {
+    const prior = this.history[this.history.length - 1];
+    if (!prior) {
+      throw new Error("BundleStore.rollback: no prior bundle in history");
+    }
+    this.pinnedVersion = void 0;
+    return this.commit(prior.bundle, "rollback");
+  }
+  /** Lift the pin so `swap()` accepts new bundles again. */
+  unpin() {
+    this.pinnedVersion = void 0;
+  }
+  /** True when the store is currently pinned. */
+  isPinned() {
+    return this.pinnedVersion !== void 0;
+  }
+  /** Pinned version string, or undefined when unpinned. */
+  pinned() {
+    return this.pinnedVersion;
+  }
+  /**
+   * Snapshot of the history ring (oldest first; does not include the active
+   * bundle). Returned array is a shallow copy — safe to inspect.
+   */
+  historySnapshot() {
+    return this.history.map((h) => ({
+      version: h.bundle.version,
+      bundleId: h.bundle.bundleId,
+      validatedAt: h.validatedAt
+    }));
+  }
+  /** Subscribe to swap events. Returns an unsubscribe function. */
+  subscribe(fn) {
+    this.listeners.add(fn);
+    return () => {
+      this.listeners.delete(fn);
+    };
+  }
+  /** Reset to empty state. Used by tests. Does NOT fire listeners. */
+  reset() {
+    this.active = void 0;
+    this.history = [];
+    this.pinnedVersion = void 0;
+  }
+  /** Commit a new active bundle (shared by swap / pin / rollback). */
+  commit(next, reason) {
+    const previous = this.active;
+    const diff = diffBundles(previous, next);
+    if (previous) {
+      const lastInHistory = this.history[this.history.length - 1];
+      if (!lastInHistory || lastInHistory.bundle.version !== previous.version) {
+        this.history.push({ bundle: previous, validatedAt: Date.now() });
+        if (this.history.length > this.historySize) {
+          this.history.splice(0, this.history.length - this.historySize);
+        }
+      }
+    }
+    this.active = next;
+    for (const fn of this.listeners) {
+      try {
+        fn({ previous, current: next, diff, reason });
+      } catch {
+      }
+    }
+    return diff;
+  }
+};
+var BundlePinnedError = class extends Error {
+  constructor(pinnedVersion) {
+    super(`BundleStore is pinned to version "${pinnedVersion}"; new swaps are rejected until unpin().`);
+    this.pinnedVersion = pinnedVersion;
+    this.name = "BundlePinnedError";
+  }
+};
+
+// libs/adapters/src/skills/dependency/skill-dag.ts
+var SkillDependencyCycleError = class extends Error {
+  constructor(cycle) {
+    super(`skill dependency cycle: ${cycle.join(" -> ")}`);
+    this.cycle = cycle;
+    this.name = "SkillDependencyCycleError";
+  }
+};
+var SkillDependencyMissingError = class extends Error {
+  constructor(skillId, missingId) {
+    super(`skill "${skillId}" requires unknown skill "${missingId}"`);
+    this.skillId = skillId;
+    this.missingId = missingId;
+    this.name = "SkillDependencyMissingError";
+  }
+};
+var SkillDependencyInvariantError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SkillDependencyInvariantError";
+  }
+};
+function resolveSkillLoadOrder(skills) {
+  const byId = /* @__PURE__ */ new Map();
+  for (const skill of skills) {
+    if (byId.has(skill.id)) {
+      byId.set(skill.id, skill);
+      continue;
+    }
+    byId.set(skill.id, skill);
+  }
+  const inDegree = /* @__PURE__ */ new Map();
+  const requiredBy = /* @__PURE__ */ new Map();
+  for (const id of byId.keys()) {
+    inDegree.set(id, 0);
+    requiredBy.set(id, []);
+  }
+  for (const skill of byId.values()) {
+    const deps = skill.requires ?? [];
+    for (const depId of deps) {
+      if (!byId.has(depId)) {
+        throw new SkillDependencyMissingError(skill.id, depId);
+      }
+      inDegree.set(skill.id, (inDegree.get(skill.id) ?? 0) + 1);
+      const reverse = requiredBy.get(depId) ?? [];
+      reverse.push(skill.id);
+      requiredBy.set(depId, reverse);
+    }
+  }
+  const ready = [...byId.keys()].filter((id) => inDegree.get(id) === 0).sort();
+  const order = [];
+  while (ready.length > 0) {
+    const next = ready.shift();
+    if (next === void 0) {
+      throw new SkillDependencyInvariantError(
+        "resolveSkillLoadOrder: invariant broken \u2014 ready queue drained mid-iteration"
+      );
+    }
+    const nextSkill = byId.get(next);
+    if (!nextSkill) {
+      throw new SkillDependencyInvariantError(
+        `resolveSkillLoadOrder: invariant broken \u2014 id "${next}" missing from byId map`
+      );
+    }
+    order.push(nextSkill);
+    for (const dependent of requiredBy.get(next) ?? []) {
+      const remaining = (inDegree.get(dependent) ?? 0) - 1;
+      inDegree.set(dependent, remaining);
+      if (remaining === 0) {
+        let i = 0;
+        while (i < ready.length && ready[i] < dependent) i++;
+        ready.splice(i, 0, dependent);
+      }
+    }
+  }
+  if (order.length === byId.size) {
+    return order;
+  }
+  const remainingIds = [...byId.keys()].filter((id) => (inDegree.get(id) ?? 0) > 0);
+  const cycle = findCycle(remainingIds, byId);
+  throw new SkillDependencyCycleError(cycle);
+}
+function findCycle(remaining, byId) {
+  const adj = /* @__PURE__ */ new Map();
+  for (const id of remaining) {
+    adj.set(
+      id,
+      (byId.get(id)?.requires ?? []).filter((d) => remaining.includes(d))
+    );
+  }
+  const WHITE = 0;
+  const GRAY = 1;
+  const BLACK = 2;
+  const color = /* @__PURE__ */ new Map();
+  for (const id of remaining) color.set(id, WHITE);
+  const stack = [];
+  function dfs(node) {
+    color.set(node, GRAY);
+    stack.push(node);
+    for (const next of adj.get(node) ?? []) {
+      const c = color.get(next);
+      if (c === GRAY) {
+        const startIdx = stack.indexOf(next);
+        return [...stack.slice(startIdx), next];
+      }
+      if (c === WHITE) {
+        const found = dfs(next);
+        if (found) return found;
+      }
+    }
+    color.set(node, BLACK);
+    stack.pop();
+    return void 0;
+  }
+  for (const id of remaining) {
+    if (color.get(id) === WHITE) {
+      const cycle = dfs(id);
+      if (cycle) return cycle;
+    }
+  }
+  return remaining;
+}
+
+// libs/adapters/src/skills/source-options.ts
+import { z as z2 } from "@frontmcp/lazy-zod";
+var httpsUrl = z2.string().url().refine(
+  (v) => {
+    try {
+      return new URL(v).protocol === "https:";
+    } catch {
+      return false;
+    }
+  },
+  { message: "must use https://" }
+);
+var staticSourceSchema = z2.object({
+  type: z2.literal("static"),
+  /** Path to the bundle directory (containing spec.yaml + overlay.yaml) or a single overlay file. */
+  path: z2.string().min(1),
+  /** Watch the path for changes (fs.watch). Default false. */
+  watch: z2.boolean().default(false)
+});
+var npmSourceSchema = z2.object({
+  type: z2.literal("npm"),
+  /** npm package specifier, e.g. `@acme/frontmcp-billing-bundle`. */
+  packageName: z2.string().min(1),
+  /** Optional named export to read; default is the package's default export. */
+  exportName: z2.string().optional(),
+  /**
+   * Verify GitHub artifact attestation / npm provenance for the package before loading.
+   * Defaults to true. Set false (with warning) only for local development packages.
+   */
+  verifyProvenance: z2.boolean().default(true)
+});
+var saasSourceSchema = z2.object({
+  type: z2.literal("saas"),
+  /** SaaS pull endpoint, e.g. `https://cloud.frontmcp.dev/v1/bundles/<bundleId>`. */
+  endpoint: httpsUrl,
+  /** Pinned JWT issued by the SaaS for the customer's FrontMCP server. */
+  authToken: z2.string().min(1),
+  /**
+   * RFC 8707 resource indicator the JWT must encode. The plugin verifies
+   * `resource` AND `aud` claims match this on every push/pull.
+   */
+  expectedAudience: z2.string().min(1),
+  /** Polling interval in ms (boot pull is always immediate). Default 300000 (5 min). */
+  pollIntervalMs: z2.number().int().positive().default(3e5),
+  /**
+   * Mount a webhook handler at `POST /__skilled_openapi/push` so the SaaS can push
+   * updates synchronously. Default false in v1.2 (interval polling only).
+   */
+  enableWebhook: z2.boolean().default(false),
+  /** JWKS URL for verifying SaaS-issued tokens. */
+  jwksUrl: httpsUrl,
+  /** Expected issuer (`iss`) claim. */
+  expectedIssuer: z2.string().min(1)
+});
+var bundleSourceSchema = z2.discriminatedUnion("type", [staticSourceSchema, npmSourceSchema, saasSourceSchema]);
+var signatureKeySchema = z2.object({
+  /** Stable key id (matches `kid` claim in the bundle JWT). */
+  keyId: z2.string().min(1),
+  /** Algorithm for the signing key. */
+  alg: z2.enum(["RS256", "EdDSA"]),
+  /** PEM-encoded public key (RSA SPKI or Ed25519). */
+  publicKeyPem: z2.string().min(1)
+});
+
+// libs/adapters/src/skills/sources/npm.source.ts
+var NpmSource = class {
+  constructor(options, logger) {
+    this.options = options;
+    this.logger = logger;
+    this.id = `npm:${this.options.packageName}${this.options.exportName ? `#${this.options.exportName}` : ""}`;
+  }
+  id;
+  listeners = /* @__PURE__ */ new Set();
+  cached;
+  async start() {
+    const bundle = await this.loadBundleFromPackage();
+    this.cached = bundle;
+    this.notify(bundle);
+  }
+  onChange(listener) {
+    this.listeners.add(listener);
+    if (this.cached) {
+      try {
+        listener(this.cached);
+      } catch (e) {
+        this.logger.warn(`[npm-source] listener threw on replay: ${e.message}`);
+      }
+    }
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  async stop() {
+    this.listeners.clear();
+  }
+  async loadBundleFromPackage() {
+    if (this.options.verifyProvenance) {
+      this.logger.warn(
+        `[npm-source] verifyProvenance=true requested but provenance verification is not yet implemented in OSS (planned v1.2.x). Loading "${this.options.packageName}" without provenance check.`
+      );
+    }
+    const mod = await this.dynamicImport(this.options.packageName);
+    const exportName = this.options.exportName ?? "default";
+    const modRecord = mod;
+    const exported = modRecord[exportName] ?? (exportName === "default" ? mod : void 0);
+    if (exported === void 0 || exported === null) {
+      throw new Error(`npm source "${this.options.packageName}": export "${exportName}" not found on the package`);
+    }
+    return parseOverlay({ kind: "object", content: exported });
+  }
+  // Indirected so tests can stub.
+  dynamicImport(specifier) {
+    return import(specifier);
+  }
+  notify(bundle) {
+    for (const fn of this.listeners) {
+      try {
+        fn(bundle);
+      } catch (e) {
+        this.logger.warn(`[npm-source] listener threw: ${e.message}`);
+      }
+    }
+  }
+};
+
+// libs/adapters/src/skills/sources/saas-pull.source.ts
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+var DEFAULT_CACHE_DIR = ".frontmcp/skilled-openapi";
+var DEFAULT_PULL_TIMEOUT_MS = 3e4;
+var SaasPullSource = class {
+  constructor(options, cacheDir, logger) {
+    this.options = options;
+    this.cacheDir = cacheDir;
+    this.logger = logger;
+    this.id = `saas:${this.options.endpoint}`;
+  }
+  id;
+  listeners = /* @__PURE__ */ new Set();
+  pollHandle;
+  inFlight = false;
+  stopped = false;
+  async start() {
+    let bundle;
+    try {
+      bundle = await this.fetchOnce();
+      await this.persistCache(bundle);
+    } catch (e) {
+      this.logger.warn(
+        `[saas-source] initial pull failed (${e.message}); attempting cached bundle fallback`
+      );
+      bundle = await this.loadCache();
+      if (!bundle) {
+        throw new Error(
+          `[saas-source] initial pull failed and no cached bundle is available at ${this.cachePath()}: ${e.message}`
+        );
+      }
+      this.logger.warn(`[saas-source] using cached bundle "${bundle.bundleId}@${bundle.version}"`);
+    }
+    this.notify(bundle);
+    this.schedulePoll();
+  }
+  onChange(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  async stop() {
+    this.stopped = true;
+    if (this.pollHandle) {
+      clearTimeout(this.pollHandle);
+      this.pollHandle = void 0;
+    }
+    this.listeners.clear();
+  }
+  schedulePoll() {
+    if (this.stopped) return;
+    this.pollHandle = setTimeout(() => {
+      void this.pollOnce();
+    }, this.options.pollIntervalMs);
+    this.pollHandle.unref?.();
+  }
+  async pollOnce() {
+    if (this.stopped) return;
+    if (this.inFlight) {
+      this.schedulePoll();
+      return;
+    }
+    this.inFlight = true;
+    try {
+      const bundle = await this.fetchOnce();
+      await this.persistCache(bundle);
+      this.notify(bundle);
+    } catch (e) {
+      this.logger.warn(`[saas-source] poll failed: ${e.message}`);
+    } finally {
+      this.inFlight = false;
+      this.schedulePoll();
+    }
+  }
+  // Indirected so tests can stub the network call.
+  async httpGet(url, headers) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), DEFAULT_PULL_TIMEOUT_MS);
+    try {
+      const res = await fetch(url, { method: "GET", headers, signal: controller.signal });
+      const body = await res.text();
+      return { status: res.status, body };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  async fetchOnce() {
+    const { status, body } = await this.httpGet(this.options.endpoint, {
+      Authorization: `Bearer ${this.options.authToken}`,
+      Accept: "application/json, application/yaml",
+      "User-Agent": "frontmcp-skilled-openapi"
+    });
+    if (status < 200 || status >= 300) {
+      throw new Error(`pull responded ${status}`);
+    }
+    const trimmed = body.trimStart();
+    return parseOverlay(
+      trimmed.startsWith("{") || trimmed.startsWith("[") ? { kind: "json", content: body } : { kind: "yaml", content: body }
+    );
+  }
+  cachePath() {
+    const dir = this.cacheDir ?? DEFAULT_CACHE_DIR;
+    return path.resolve(dir, `${this.options.expectedAudience.replace(/[^a-zA-Z0-9_.-]/g, "_")}.json`);
+  }
+  async persistCache(bundle) {
+    try {
+      const filePath = this.cachePath();
+      await fs.mkdir(path.dirname(filePath), { recursive: true });
+      await fs.writeFile(filePath, JSON.stringify(bundle), "utf8");
+    } catch (e) {
+      this.logger.warn(`[saas-source] cache persist failed: ${e.message}`);
+    }
+  }
+  async loadCache() {
+    try {
+      const filePath = this.cachePath();
+      const raw = await fs.readFile(filePath, "utf8");
+      return parseOverlay({ kind: "json", content: raw });
+    } catch {
+      return void 0;
+    }
+  }
+  notify(bundle) {
+    for (const fn of this.listeners) {
+      try {
+        fn(bundle);
+      } catch (e) {
+        this.logger.warn(`[saas-source] listener threw: ${e.message}`);
+      }
+    }
+  }
+};
+
+// libs/adapters/src/skills/sources/static.source.ts
+import { watch as fsWatch } from "node:fs";
+import * as path2 from "node:path";
+import { readFile } from "@frontmcp/utils";
+var StaticSource = class {
+  constructor(options, logger) {
+    this.options = options;
+    this.logger = logger;
+    this.id = `static:${this.options.path}`;
+  }
+  id;
+  listeners = /* @__PURE__ */ new Set();
+  watcher;
+  debounceTimer;
+  stopped = false;
+  async start() {
+    const bundle = await this.fetchOnce();
+    this.notify(bundle);
+    if (this.options.watch) {
+      this.beginWatch();
+    }
+  }
+  onChange(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  async stop() {
+    this.stopped = true;
+    if (this.watcher) {
+      this.watcher.close();
+      this.watcher = void 0;
+    }
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+      this.debounceTimer = void 0;
+    }
+    this.listeners.clear();
+  }
+  async fetchOnce() {
+    const absPath = path2.resolve(this.options.path);
+    const raw = await readFile(absPath, "utf8");
+    const ext = path2.extname(absPath).toLowerCase();
+    let input;
+    if (ext === ".json") {
+      input = { kind: "json", content: raw };
+    } else if (ext === ".yaml" || ext === ".yml") {
+      input = { kind: "yaml", content: raw };
+    } else {
+      const trimmed = raw.trimStart();
+      input = trimmed.startsWith("{") || trimmed.startsWith("[") ? { kind: "json", content: raw } : { kind: "yaml", content: raw };
+    }
+    return parseOverlay(input);
+  }
+  notify(bundle) {
+    for (const fn of this.listeners) {
+      try {
+        fn(bundle);
+      } catch (e) {
+        this.logger.warn(`[static-source] listener threw: ${e.message}`);
+      }
+    }
+  }
+  beginWatch() {
+    const absPath = path2.resolve(this.options.path);
+    try {
+      this.watcher = fsWatch(absPath, { persistent: false }, () => this.scheduleRefresh());
+    } catch (e) {
+      this.logger.warn(`[static-source] fs.watch failed (${e.message}); polling at 2s instead`);
+      const tick = () => {
+        if (this.stopped) return;
+        this.scheduleRefresh();
+        setTimeout(tick, 2e3).unref?.();
+      };
+      setTimeout(tick, 2e3).unref?.();
+    }
+  }
+  scheduleRefresh() {
+    if (this.debounceTimer) clearTimeout(this.debounceTimer);
+    this.debounceTimer = setTimeout(async () => {
+      if (this.stopped) return;
+      try {
+        const bundle = await this.fetchOnce();
+        this.notify(bundle);
+      } catch (e) {
+        this.logger.warn(`[static-source] refresh failed: ${e.message}`);
+      }
+    }, 250);
+    this.debounceTimer.unref?.();
+  }
+};
+
+// libs/adapters/src/skills/sources/index.ts
+function createBundleSource(source, cacheDir, logger) {
+  switch (source.type) {
+    case "static":
+      return new StaticSource(source, logger);
+    case "npm":
+      return new NpmSource(source, logger);
+    case "saas":
+      return new SaasPullSource(source, cacheDir, logger);
+  }
+}
+
+// libs/adapters/src/skills/sources/filesystem-skills.source.ts
+import { watch as fsWatch2 } from "node:fs";
+import { sep as pathSep } from "node:path";
+import { basename, joinPath, pathResolve, readdir, readFile as readFile2, realpath, stat } from "@frontmcp/utils";
+var DEFAULT_OPTIONS = {
+  skillsDir: "./skills",
+  watch: true,
+  debounceMs: 200,
+  pollIntervalMs: 2e3
+};
+var FilesystemSkillsSource = class {
+  constructor(options, logger) {
+    this.logger = logger;
+    this.options = { ...DEFAULT_OPTIONS, ...options };
+    this.id = `filesystem-skills:${this.options.skillsDir}`;
+  }
+  id;
+  options;
+  listeners = /* @__PURE__ */ new Set();
+  known = /* @__PURE__ */ new Map();
+  // absPath → last emitted content
+  watcher;
+  pollTimer;
+  debounceTimers = /* @__PURE__ */ new Map();
+  stopped = false;
+  rootResolved = "";
+  onChange(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  async start() {
+    const absRoot = pathResolve(this.options.skillsDir);
+    try {
+      this.rootResolved = await realpath(absRoot);
+    } catch {
+      this.rootResolved = absRoot;
+    }
+    await this.initialScan();
+    if (this.options.watch) {
+      this.beginWatch();
+    }
+  }
+  async stop() {
+    this.stopped = true;
+    if (this.watcher) {
+      try {
+        this.watcher.close();
+      } catch {
+      }
+      this.watcher = void 0;
+    }
+    if (this.pollTimer) {
+      clearTimeout(this.pollTimer);
+      this.pollTimer = void 0;
+    }
+    for (const t of this.debounceTimers.values()) clearTimeout(t);
+    this.debounceTimers.clear();
+    this.listeners.clear();
+    this.known.clear();
+  }
+  async initialScan() {
+    const entries = await this.listSkillSubdirs();
+    for (const dir of entries) {
+      await this.refreshSkill(dir);
+    }
+  }
+  async listSkillSubdirs() {
+    let entries;
+    try {
+      entries = await readdir(this.rootResolved);
+    } catch (e) {
+      this.logger.warn(`[fs-skills] cannot read ${this.rootResolved}: ${e.message}`);
+      return [];
+    }
+    const out = [];
+    for (const name of entries) {
+      if (name.startsWith(".")) continue;
+      const abs = joinPath(this.rootResolved, name);
+      let resolved;
+      try {
+        resolved = await realpath(abs);
+      } catch {
+        continue;
+      }
+      if (!resolved.startsWith(this.rootResolved + pathSep) && resolved !== this.rootResolved) {
+        this.logger.warn(`[fs-skills] skipping ${name}: realpath escapes skillsDir`);
+        continue;
+      }
+      try {
+        const st = await stat(resolved);
+        if (st.isDirectory()) out.push(resolved);
+      } catch {
+      }
+    }
+    return out.sort();
+  }
+  /** Reload a single skill subdir and emit upsert (or delete if vanished). */
+  async refreshSkill(absDir) {
+    if (this.stopped) return;
+    let exists = false;
+    try {
+      const st = await stat(absDir);
+      exists = st.isDirectory();
+    } catch {
+      exists = false;
+    }
+    if (!exists) {
+      const prev2 = this.known.get(absDir);
+      if (prev2) {
+        this.known.delete(absDir);
+        this.emit({ op: "delete", skillId: prev2.id, absPath: absDir });
+      }
+      return;
+    }
+    let content;
+    try {
+      content = await loadFilesystemSkill(absDir);
+    } catch (e) {
+      this.logger.warn(`[fs-skills] failed to load ${absDir}: ${e.message}`);
+      return;
+    }
+    const prev = this.known.get(absDir);
+    if (prev && skillContentEqual(prev, content)) {
+      return;
+    }
+    this.known.set(absDir, content);
+    this.emit({ op: "upsert", skill: content, absPath: absDir });
+  }
+  emit(event) {
+    for (const fn of this.listeners) {
+      try {
+        fn(event);
+      } catch (e) {
+        this.logger.warn(`[fs-skills] listener threw: ${e.message}`);
+      }
+    }
+  }
+  beginWatch() {
+    try {
+      this.watcher = fsWatch2(this.rootResolved, { recursive: true, persistent: false }, (_eventType, filename) => {
+        if (this.stopped) return;
+        if (!filename) {
+          this.scheduleRescan();
+          return;
+        }
+        const first = filename.split(pathSep)[0];
+        if (!first || first.startsWith(".")) return;
+        const absDir = joinPath(this.rootResolved, first);
+        this.scheduleRefresh(absDir);
+      });
+      this.watcher.on("error", (e) => {
+        this.logger.warn(`[fs-skills] fs.watch error: ${e.message}; falling back to polling`);
+        this.watcher?.close();
+        this.watcher = void 0;
+        this.beginPolling();
+      });
+    } catch (e) {
+      this.logger.warn(
+        `[fs-skills] fs.watch failed (${e.message}); polling at ${this.options.pollIntervalMs}ms instead`
+      );
+      this.beginPolling();
+    }
+  }
+  beginPolling() {
+    const tick = async () => {
+      if (this.stopped) return;
+      try {
+        await this.pollOnce();
+      } catch (e) {
+        this.logger.warn(`[fs-skills] poll tick error: ${e.message}`);
+      }
+      if (this.stopped) return;
+      this.pollTimer = setTimeout(tick, this.options.pollIntervalMs);
+      this.pollTimer.unref?.();
+    };
+    this.pollTimer = setTimeout(tick, this.options.pollIntervalMs);
+    this.pollTimer.unref?.();
+  }
+  /** Compare current dir listing to known set; emit upserts/deletes. */
+  async pollOnce() {
+    const dirs = new Set(await this.listSkillSubdirs());
+    for (const known of [...this.known.keys()]) {
+      if (!dirs.has(known)) {
+        await this.refreshSkill(known);
+      }
+    }
+    for (const abs of dirs) {
+      await this.refreshSkill(abs);
+    }
+  }
+  /** Coarse rescan when filename is unknown (some Linux/macOS fs.watch events). */
+  scheduleRescan() {
+    const key = "<rescan>";
+    const existing = this.debounceTimers.get(key);
+    if (existing) clearTimeout(existing);
+    const t = setTimeout(() => {
+      this.debounceTimers.delete(key);
+      void this.pollOnce().catch((e) => {
+        this.logger.warn(`[fs-skills] rescan failed: ${e.message}`);
+      });
+    }, this.options.debounceMs);
+    t.unref?.();
+    this.debounceTimers.set(key, t);
+  }
+  scheduleRefresh(absDir) {
+    const existing = this.debounceTimers.get(absDir);
+    if (existing) clearTimeout(existing);
+    const t = setTimeout(() => {
+      this.debounceTimers.delete(absDir);
+      void this.refreshSkill(absDir).catch((e) => {
+        this.logger.warn(`[fs-skills] refresh failed for ${absDir}: ${e.message}`);
+      });
+    }, this.options.debounceMs);
+    t.unref?.();
+    this.debounceTimers.set(absDir, t);
+  }
+};
+async function loadFilesystemSkill(absDir) {
+  const skillMdPath = joinPath(absDir, "SKILL.md");
+  const raw = await readFile2(skillMdPath, "utf8");
+  const { frontmatter, body } = parseSkillFrontmatter(raw);
+  const dirName = basename(absDir);
+  const name = frontmatter["name"] ?? dirName;
+  const description = frontmatter["description"] ?? "";
+  if (!description) {
+    throw new Error(`SKILL.md missing 'description' frontmatter (in ${absDir})`);
+  }
+  const instructions = body.trim();
+  if (!instructions) {
+    throw new Error(`SKILL.md missing body content (in ${absDir})`);
+  }
+  const tools = parseToolList(frontmatter["tools"]);
+  const resources = {};
+  for (const sub of ["scripts", "references", "examples", "assets"]) {
+    const subAbs = joinPath(absDir, sub);
+    try {
+      const st = await stat(subAbs);
+      if (st.isDirectory()) resources[sub] = subAbs;
+    } catch {
+    }
+  }
+  const out = {
+    id: name,
+    name,
+    description,
+    instructions,
+    tools,
+    ...Object.keys(resources).length > 0 && { resources }
+  };
+  if (typeof frontmatter["license"] === "string") out.license = frontmatter["license"];
+  if (typeof frontmatter["compatibility"] === "string") out.compatibility = frontmatter["compatibility"];
+  return out;
+}
+function parseSkillFrontmatter(raw) {
+  if (!raw.startsWith("---")) {
+    return { frontmatter: {}, body: raw };
+  }
+  const closeIdx = raw.indexOf("\n---", 3);
+  if (closeIdx === -1) {
+    return { frontmatter: {}, body: raw };
+  }
+  const yamlBlock = raw.slice(3, closeIdx).trim();
+  let bodyStart = closeIdx + 4;
+  if (raw[bodyStart] === "\n") bodyStart += 1;
+  const body = raw.slice(bodyStart);
+  const fm = {};
+  let currentListKey;
+  for (const line of yamlBlock.split("\n")) {
+    if (!line.trim()) continue;
+    if (line.startsWith("- ") && currentListKey) {
+      const arr = fm[currentListKey] ?? [];
+      arr.push(stripQuotes(line.slice(2).trim()));
+      fm[currentListKey] = arr;
+      continue;
+    }
+    const colon = line.indexOf(":");
+    if (colon === -1) continue;
+    const key = line.slice(0, colon).trim();
+    const rest = line.slice(colon + 1).trim();
+    if (!rest) {
+      currentListKey = key;
+      fm[key] = [];
+      continue;
+    }
+    currentListKey = void 0;
+    fm[key] = stripQuotes(rest);
+  }
+  return { frontmatter: fm, body };
+}
+function stripQuotes(s) {
+  if (s.startsWith('"') && s.endsWith('"') || s.startsWith("'") && s.endsWith("'")) {
+    return s.slice(1, -1);
+  }
+  return s;
+}
+function parseToolList(raw) {
+  if (Array.isArray(raw)) {
+    return raw.map((t) => typeof t === "string" ? { name: t } : null).filter((t) => t !== null);
+  }
+  if (typeof raw === "string") {
+    return raw.split(",").map((t) => t.trim()).filter(Boolean).map((name) => ({ name }));
+  }
+  return [];
+}
+function skillContentEqual(a, b) {
+  return a.id === b.id && a.name === b.name && a.description === b.description && a.instructions === b.instructions && a.license === b.license && a.compatibility === b.compatibility && JSON.stringify(a.tools) === JSON.stringify(b.tools) && JSON.stringify(a.resources ?? {}) === JSON.stringify(b.resources ?? {});
+}
+
+// libs/adapters/src/skills/security/bundle-signature.ts
+import { base64urlDecode, pemToPublicJwk, rsaVerifySync, sha256Hex } from "@frontmcp/utils";
+function classifyReason(reason) {
+  if (reason.includes("missing integrity")) return "missing_integrity";
+  if (reason.includes("digest mismatch")) return "digest_mismatch";
+  if (reason.includes("unknown signing keyId")) return "unknown_key_id";
+  if (reason.includes("alg=")) return "alg_mismatch";
+  if (reason.includes("parse public key")) return "malformed_public_key";
+  if (reason.includes("not valid base64url")) return "malformed_signature";
+  if (reason.includes("signature verify threw")) return "verify_threw";
+  if (reason.includes("signature verification failed")) return "verify_failed";
+  return "other";
+}
+function canonicalize(value) {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((v) => canonicalize(v)).join(",")}]`;
+  }
+  const obj = value;
+  const keys = Object.keys(obj).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalize(obj[k])}`).join(",")}}`;
+}
+function bundleDigest(bundle) {
+  const { integrity: _drop, ...rest } = bundle;
+  void _drop;
+  return sha256Hex(canonicalize(rest));
+}
+function decodeSignatureBytes(signatureBase64Url) {
+  try {
+    return base64urlDecode(signatureBase64Url);
+  } catch {
+    return void 0;
+  }
+}
+function verifyBundleSignature(bundle, trustedKeys, telemetry) {
+  const failuresCounter = telemetry?.createCounter(
+    "frontmcp_skills_signature_failures_total",
+    "Number of bundle signature verification failures, partitioned by reason."
+  );
+  const verificationsCounter = telemetry?.createCounter(
+    "frontmcp_skills_signature_verifications_total",
+    "Number of bundle signature verification attempts, partitioned by status (ok|error)."
+  );
+  const fail = (reason) => {
+    failuresCounter?.inc(1, { reason: classifyReason(reason) });
+    verificationsCounter?.inc(1, { status: "error" });
+    return { ok: false, reason };
+  };
+  if (!bundle.integrity) {
+    return fail("bundle missing integrity envelope");
+  }
+  const { alg, keyId, signature, digest } = bundle.integrity;
+  const expectedDigest = bundleDigest(bundle);
+  if (digest.toLowerCase() !== expectedDigest.toLowerCase()) {
+    return fail(`digest mismatch (envelope=${digest.slice(0, 12)}.. computed=${expectedDigest.slice(0, 12)}..)`);
+  }
+  const trusted = trustedKeys.find((k) => k.keyId === keyId);
+  if (!trusted) {
+    return fail(`unknown signing keyId "${keyId}" \u2014 not in trustedKeys allowlist`);
+  }
+  if (trusted.alg !== alg) {
+    return fail(`key "${keyId}" alg=${trusted.alg} but envelope alg=${alg}`);
+  }
+  let publicJwk;
+  try {
+    publicJwk = pemToPublicJwk(trusted.publicKeyPem);
+  } catch (e) {
+    return fail(`failed to parse public key for "${keyId}": ${e.message}`);
+  }
+  const sigBytes = decodeSignatureBytes(signature);
+  if (!sigBytes) {
+    return fail("signature is not valid base64url");
+  }
+  const { integrity: _drop, ...rest } = bundle;
+  void _drop;
+  const canonicalBytes = new TextEncoder().encode(canonicalize(rest));
+  const verified = rsaVerifySync(alg, canonicalBytes, publicJwk, sigBytes);
+  if (!verified) {
+    return fail("signature verification failed");
+  }
+  verificationsCounter?.inc(1, { status: "ok" });
+  return { ok: true, keyId, alg };
+}
+
+// libs/adapters/src/skills/security/jwt-verifier.ts
+import { JwksService } from "@frontmcp/auth";
+var DEFAULT_REQUIRED_ROLES = ["frontmcp:cloud:push"];
+var BundlePushJwtVerifier = class {
+  constructor(options, logger, jwks) {
+    this.options = options;
+    this.logger = logger;
+    this.jwks = jwks ?? new JwksService({});
+    this.providerRef = {
+      id: "skilled-openapi-cloud-push",
+      issuerUrl: options.expectedIssuer,
+      jwksUri: options.jwksUri
+    };
+  }
+  providerRef;
+  jwks;
+  /**
+   * Verify a SaaS-issued bearer token. Returns ok=true only if signature,
+   * issuer, audience, RFC 8707 resource indicator, and role claims all check.
+   */
+  async verify(token) {
+    if (!token || typeof token !== "string") {
+      return { ok: false, reason: "token missing" };
+    }
+    let res;
+    try {
+      res = await this.jwks.verifyTransparentToken(token, [this.providerRef]);
+    } catch (e) {
+      this.logger.debug(`[skilled-openapi] jwt verify threw: ${e.message}`);
+      return { ok: false, reason: `verify failed: ${e.message}` };
+    }
+    if (!res.ok || !res.payload) {
+      return { ok: false, reason: res.error ?? "signature verify failed" };
+    }
+    const payload = res.payload;
+    const aud = payload["aud"];
+    const audValues = Array.isArray(aud) ? aud : aud !== void 0 ? [aud] : [];
+    if (!audValues.includes(this.options.expectedAudience)) {
+      return { ok: false, reason: `aud mismatch (expected "${this.options.expectedAudience}")` };
+    }
+    const resource = payload["resource"];
+    const resValues = Array.isArray(resource) ? resource : resource !== void 0 ? [resource] : [];
+    if (!resValues.includes(this.options.expectedResource)) {
+      return {
+        ok: false,
+        reason: `RFC 8707 resource indicator mismatch (expected "${this.options.expectedResource}")`
+      };
+    }
+    const requiredRoles = this.options.requiredRoles ?? DEFAULT_REQUIRED_ROLES;
+    if (requiredRoles.length > 0 && !this.matchesAny(payload["roles"], requiredRoles)) {
+      return { ok: false, reason: `missing required role (need one of ${requiredRoles.join(", ")})` };
+    }
+    if (this.options.requiredScopes && this.options.requiredScopes.length > 0) {
+      if (!this.matchesAny(payload["scope"] ?? payload["scp"], this.options.requiredScopes)) {
+        return {
+          ok: false,
+          reason: `missing required scope (need one of ${this.options.requiredScopes.join(", ")})`
+        };
+      }
+    }
+    return { ok: true, payload };
+  }
+  matchesAny(claim, required) {
+    const have = Array.isArray(claim) ? claim.filter((v) => typeof v === "string") : typeof claim === "string" ? claim.split(/\s+/).filter(Boolean) : [];
+    return required.some((r) => have.includes(r));
+  }
+};
+
+// libs/adapters/src/skills/security/webhook-replay-guard.ts
+import { sha256Hex as sha256Hex2 } from "@frontmcp/utils";
+function classifyReplayReason(reason) {
+  if (reason.includes("not finite")) return "invalid_timestamp";
+  if (reason.includes("too short")) return "invalid_nonce";
+  if (reason.includes("outside")) return "outside_window";
+  if (reason.includes("replay")) return "nonce_replay";
+  return "other";
+}
+var DEFAULT_WINDOW_MS = 5 * 60 * 1e3;
+var DEFAULT_CAPACITY = 5e3;
+var WebhookReplayGuard = class {
+  windowMs;
+  capacity;
+  seen = /* @__PURE__ */ new Map();
+  now = Date.now;
+  rejectsCounter;
+  checksCounter;
+  constructor(options = {}) {
+    const windowMs = options.windowMs ?? DEFAULT_WINDOW_MS;
+    const capacity = options.capacity ?? DEFAULT_CAPACITY;
+    if (!Number.isFinite(windowMs) || windowMs <= 0) {
+      throw new RangeError("WebhookReplayGuard: windowMs must be a finite number > 0");
+    }
+    if (!Number.isInteger(capacity) || capacity <= 0) {
+      throw new RangeError("WebhookReplayGuard: capacity must be a positive integer");
+    }
+    this.windowMs = windowMs;
+    this.capacity = capacity;
+    this.rejectsCounter = options.telemetry?.createCounter(
+      "frontmcp_skills_replay_rejects_total",
+      "Number of webhook replay-guard rejections, partitioned by reason."
+    );
+    this.checksCounter = options.telemetry?.createCounter(
+      "frontmcp_skills_replay_checks_total",
+      "Number of webhook replay-guard checks, partitioned by status (ok|error)."
+    );
+  }
+  /** For tests: override the time source. */
+  setNowProvider(fn) {
+    this.now = fn;
+  }
+  /**
+   * Check that a (timestamp, nonce) pair is fresh and unseen. Returns ok=false
+   * if the timestamp is outside the freshness window or the nonce has already
+   * been observed within that window.
+   */
+  check(args) {
+    const { timestampMs, nonce } = args;
+    const reject = (reason) => {
+      this.rejectsCounter?.inc(1, { reason: classifyReplayReason(reason) });
+      this.checksCounter?.inc(1, { status: "error" });
+      return { ok: false, reason };
+    };
+    if (!Number.isFinite(timestampMs)) {
+      return reject("timestamp not finite");
+    }
+    if (typeof nonce !== "string" || nonce.length < 8) {
+      return reject("nonce too short");
+    }
+    const now = this.now();
+    if (Math.abs(now - timestampMs) > this.windowMs) {
+      return reject(`timestamp outside ${this.windowMs}ms window`);
+    }
+    const key = sha256Hex2(nonce);
+    const expiresAt = this.seen.get(key);
+    if (expiresAt !== void 0 && expiresAt >= now) {
+      return reject("nonce replay detected within freshness window");
+    }
+    if (this.seen.size >= this.capacity) {
+      this.prune();
+    }
+    if (this.seen.size >= this.capacity) {
+      let victimKey;
+      let victimExpiry = Number.POSITIVE_INFINITY;
+      for (const [candidateKey, candidateExpiry] of this.seen) {
+        if (candidateExpiry < victimExpiry) {
+          victimKey = candidateKey;
+          victimExpiry = candidateExpiry;
+        }
+      }
+      if (victimKey !== void 0) this.seen.delete(victimKey);
+    }
+    this.seen.set(key, timestampMs + this.windowMs);
+    this.checksCounter?.inc(1, { status: "ok" });
+    return { ok: true };
+  }
+  /** Test/maintenance helper: drop expired entries proactively. */
+  prune() {
+    const now = this.now();
+    let removed = 0;
+    for (const [k, expiresAt] of this.seen) {
+      if (expiresAt < now) {
+        this.seen.delete(k);
+        removed++;
+      }
+    }
+    return removed;
+  }
+  /** Inspect: number of nonces currently tracked. */
+  get size() {
+    return this.seen.size;
+  }
+};
+
+// libs/adapters/src/skills/audit/audit-record.types.ts
+var SKILL_AUDIT_GENESIS_PREV_HASH = "0".repeat(64);
+var SKILL_AUDIT_KEYS = {
+  /** Atomic chain head counter — incremented per append. */
+  sequence: "audit:skills:sequence",
+  /** Per-record key. Use `SKILL_AUDIT_KEYS.record(seq)` to build. */
+  record: (sequence) => `audit:skills:records:${sequence}`
+};
+
+// libs/adapters/src/skills/audit/audit-chain.ts
+import { sha256Hex as sha256Hex3 } from "@frontmcp/utils";
+function canonicalizeRecordForSigning(record) {
+  const { signature: _drop, ...rest } = record;
+  void _drop;
+  return canonicalize(rest);
+}
+function nextPrevHash(prev) {
+  if (!prev) return SKILL_AUDIT_GENESIS_PREV_HASH;
+  return sha256Hex3(canonicalizeRecordForSigning(prev));
+}
+function linkRecord(prev, partial) {
+  return {
+    ...partial,
+    prevHash: nextPrevHash(prev)
+  };
+}
+function verifyChain(records, trustedKeys, verifier) {
+  if (records.length === 0) {
+    return { ok: true, verified: 0 };
+  }
+  let prev;
+  for (let i = 0; i < records.length; i++) {
+    const rec = records[i];
+    if (!rec) {
+      return { ok: false, breakAt: i, reason: "record at index is null/undefined" };
+    }
+    if (prev && rec.sequence !== prev.sequence + 1) {
+      return {
+        ok: false,
+        breakAt: rec.sequence,
+        reason: `sequence gap: expected ${prev.sequence + 1}, got ${rec.sequence}`
+      };
+    }
+    const expectedPrev = nextPrevHash(prev);
+    if (rec.prevHash !== expectedPrev) {
+      return {
+        ok: false,
+        breakAt: rec.sequence,
+        reason: `prevHash mismatch at sequence ${rec.sequence}: expected ${expectedPrev.slice(0, 12)}.. got ${rec.prevHash.slice(0, 12)}..`
+      };
+    }
+    const canonicalBytes = new TextEncoder().encode(canonicalizeRecordForSigning(rec));
+    const ok = verifier({
+      alg: rec.signatureAlg,
+      keyId: rec.signatureKeyId,
+      data: canonicalBytes,
+      signatureBase64Url: rec.signature,
+      trustedKeys: [...trustedKeys]
+    });
+    if (!ok) {
+      return {
+        ok: false,
+        breakAt: rec.sequence,
+        reason: `signature verification failed at sequence ${rec.sequence} (keyId="${rec.signatureKeyId}", alg=${rec.signatureAlg})`
+      };
+    }
+    prev = rec;
+  }
+  return { ok: true, verified: records.length };
+}
+
+// libs/adapters/src/skills/audit/audit-signer.ts
+import {
+  base64urlDecode as base64urlDecode2,
+  base64urlEncode,
+  hmacSha256,
+  pemToPublicJwk as pemToPublicJwk2,
+  rsaSignBase64Url,
+  rsaVerifySync as rsaVerifySync2,
+  timingSafeEqual
+} from "@frontmcp/utils";
+var Hs256AuditSigner = class {
+  key;
+  keyId;
+  /**
+   * @param secret - HMAC secret. Strings are UTF-8 encoded; pass a
+   *                 Uint8Array directly when you've derived the key (e.g.
+   *                 from HKDF) and want to avoid the extra encode step.
+   * @param keyId - Stable identifier (e.g. `'audit-dev-key'`) — surfaces in
+   *                 the signed record's `signatureKeyId` field.
+   */
+  constructor(secret, keyId) {
+    if (!keyId) {
+      throw new Error("Hs256AuditSigner: keyId must be a non-empty string");
+    }
+    if (typeof secret === "string") {
+      if (secret.length === 0) throw new Error("Hs256AuditSigner: secret must be non-empty");
+      this.key = new TextEncoder().encode(secret);
+    } else {
+      if (secret.length === 0) throw new Error("Hs256AuditSigner: secret must be non-empty");
+      this.key = new Uint8Array(secret);
+    }
+    this.keyId = keyId;
+  }
+  sign(record) {
+    const canonicalBytes = new TextEncoder().encode(
+      canonicalizeRecordForSigning({
+        ...record,
+        // Stub the signature fields to a deterministic shape so canonicalize
+        // sees the exact same byte layout the verifier will reconstruct.
+        signature: "",
+        signatureKeyId: this.keyId,
+        signatureAlg: "HS256"
+      })
+    );
+    const mac = hmacSha256(this.key, canonicalBytes);
+    return {
+      signature: base64urlEncode(mac),
+      keyId: this.keyId,
+      alg: "HS256"
+    };
+  }
+  getKeyId() {
+    return this.keyId;
+  }
+  getAlg() {
+    return "HS256";
+  }
+};
+var Rs256AuditSigner = class {
+  privateJwk;
+  keyId;
+  constructor(privateJwk, keyId) {
+    if (!keyId) {
+      throw new Error("Rs256AuditSigner: keyId must be a non-empty string");
+    }
+    if (!privateJwk || typeof privateJwk !== "object") {
+      throw new Error("Rs256AuditSigner: privateJwk must be a JWK object");
+    }
+    if (privateJwk.kty !== "RSA") {
+      throw new Error(`Rs256AuditSigner: privateJwk.kty must be "RSA", got "${String(privateJwk.kty)}"`);
+    }
+    if (!privateJwk.n || !privateJwk.e || !privateJwk.d) {
+      throw new Error("Rs256AuditSigner: privateJwk must include `n`, `e`, and `d` (RSA private key)");
+    }
+    this.privateJwk = { ...privateJwk };
+    this.keyId = keyId;
+  }
+  sign(record) {
+    const canonicalBytes = new TextEncoder().encode(
+      canonicalizeRecordForSigning({
+        ...record,
+        signature: "",
+        signatureKeyId: this.keyId,
+        signatureAlg: "RS256"
+      })
+    );
+    const signature = rsaSignBase64Url("RS256", canonicalBytes, this.privateJwk);
+    return {
+      signature,
+      keyId: this.keyId,
+      alg: "RS256"
+    };
+  }
+  getKeyId() {
+    return this.keyId;
+  }
+  getAlg() {
+    return "RS256";
+  }
+};
+var defaultAuditSignatureVerifier = ({
+  alg,
+  keyId,
+  data,
+  signatureBase64Url,
+  trustedKeys
+}) => {
+  const trusted = trustedKeys.find((k) => k.keyId === keyId && k.alg === alg);
+  if (!trusted) return false;
+  if (alg === "HS256") {
+    if (!trusted.secret) return false;
+    const expected = hmacSha256(trusted.secret, data);
+    let actual;
+    try {
+      actual = base64urlDecode2(signatureBase64Url);
+    } catch {
+      return false;
+    }
+    if (actual.length !== expected.length) return false;
+    return timingSafeEqual(actual, expected);
+  }
+  if (alg === "RS256") {
+    if (!trusted.publicKeyPem && !trusted.publicJwk) return false;
+    let publicJwk;
+    try {
+      publicJwk = trusted.publicJwk ?? pemToPublicJwk2(trusted.publicKeyPem);
+    } catch {
+      return false;
+    }
+    let sigBytes;
+    try {
+      sigBytes = base64urlDecode2(signatureBase64Url);
+    } catch {
+      return false;
+    }
+    return rsaVerifySync2("RS256", data, publicJwk, sigBytes);
+  }
+  const _exhaustive = alg;
+  void _exhaustive;
+  return false;
+};
+
+// libs/adapters/src/skills/audit/audit-store.ts
+var MemoryAuditStore = class {
+  records = [];
+  seq = 0;
+  async nextSequence() {
+    this.seq += 1;
+    return this.seq;
+  }
+  async appendAtSequence(record) {
+    if (this.records.some((r) => r.sequence === record.sequence)) {
+      throw new Error(`MemoryAuditStore: record at sequence ${record.sequence} already exists`);
+    }
+    this.records.push(record);
+  }
+  async tail() {
+    if (this.records.length === 0) return void 0;
+    return this.records[this.records.length - 1];
+  }
+  async read(opts) {
+    const from = opts?.from ?? 1;
+    const limit = opts?.limit;
+    const filtered = this.records.filter((r) => r.sequence >= from).sort((a, b) => a.sequence - b.sequence);
+    return limit !== void 0 ? filtered.slice(0, limit) : filtered;
+  }
+};
+var StorageAdapterAuditStore = class {
+  constructor(adapter, options = {}) {
+    this.adapter = adapter;
+    this.options = options;
+  }
+  get sequenceKey() {
+    return this.options.sequenceKey ?? SKILL_AUDIT_KEYS.sequence;
+  }
+  recordKey(sequence) {
+    const prefix = this.options.recordKeyPrefix;
+    return prefix ? `${prefix}${sequence}` : SKILL_AUDIT_KEYS.record(sequence);
+  }
+  async nextSequence() {
+    return this.adapter.incr(this.sequenceKey);
+  }
+  async appendAtSequence(record) {
+    const key = this.recordKey(record.sequence);
+    const existing = await this.adapter.get(key);
+    if (existing !== null) {
+      throw new Error(`StorageAdapterAuditStore: record at sequence ${record.sequence} already exists`);
+    }
+    const payload = JSON.stringify(record);
+    await this.adapter.set(key, payload, { ifNotExists: true });
+    const stored = await this.adapter.get(key);
+    if (stored !== payload) {
+      throw new Error(`StorageAdapterAuditStore: record at sequence ${record.sequence} was clobbered or not stored`);
+    }
+  }
+  async tail() {
+    const seqRaw = await this.adapter.get(this.sequenceKey);
+    if (!seqRaw) return void 0;
+    const seq = Number.parseInt(seqRaw, 10);
+    if (!Number.isFinite(seq) || seq <= 0) return void 0;
+    const maxLookback = this.options.tailLookback ?? 1024;
+    for (let s = seq; s > 0 && s > seq - maxLookback; s--) {
+      const raw = await this.adapter.get(this.recordKey(s));
+      if (!raw) continue;
+      try {
+        return JSON.parse(raw);
+      } catch {
+        throw new Error(`StorageAdapterAuditStore.tail: corrupt record at sequence ${s} cannot be parsed as JSON`);
+      }
+    }
+    return void 0;
+  }
+  async read(opts) {
+    const seqRaw = await this.adapter.get(this.sequenceKey);
+    if (!seqRaw) return [];
+    const head = Number.parseInt(seqRaw, 10);
+    if (!Number.isFinite(head) || head <= 0) return [];
+    const from = Math.max(1, opts?.from ?? 1);
+    const limit = opts?.limit;
+    const out = [];
+    for (let s = from; s <= head; s++) {
+      const raw = await this.adapter.get(this.recordKey(s));
+      if (!raw) continue;
+      try {
+        const parsed = JSON.parse(raw);
+        out.push(parsed);
+        if (limit !== void 0 && out.length >= limit) break;
+      } catch {
+      }
+    }
+    return out;
+  }
+};
+
+// libs/adapters/src/skills/audit/audit-writer.ts
+import { bytesToHex, hmacSha256 as hmacSha2562, randomUUID, sha256Hex as sha256Hex4 } from "@frontmcp/utils";
+var SKILL_AUDIT_ERROR_MESSAGE_MAX = 500;
+var SKILL_AUDIT_QUEUE_MAX = 1e3;
+var SkillAuditWriter = class {
+  constructor(store, signer, logger, metrics, options = {}) {
+    this.store = store;
+    this.signer = signer;
+    this.logger = logger;
+    this.metrics = metrics;
+    this.subjectMode = options.subjectMode ?? "hash";
+    this.subjectHashSecret = options.subjectHashSecret ?? this.deriveDefaultSubjectSecret();
+    this.maxQueueDepth = options.maxQueueDepth ?? SKILL_AUDIT_QUEUE_MAX;
+  }
+  /**
+   * Single-flight queue: every append() chains onto this promise so the
+   * read-tail-then-append-with-prevHash sequence stays atomic per process.
+   * This is the mate to the storage adapter's `incr` for cross-pod safety.
+   */
+  chainHeadLock = Promise.resolve();
+  /** Current in-flight queue depth (records awaiting the chain head lock). */
+  queueDepth = 0;
+  subjectMode;
+  subjectHashSecret;
+  maxQueueDepth;
+  /**
+   * Phase 2 in the tool: authority check just passed. We log the inputHash
+   * here so even invocations that fail at the network layer still leave a
+   * forensic breadcrumb tying the input to the policy decision.
+   */
+  writeAuthorityPass(ctx) {
+    return this.write({
+      phase: "authority-check-pass",
+      ctx
+    });
+  }
+  /**
+   * Phase 2 in the tool: authority check denied. Writing this record is
+   * security-relevant — without it, denied invocations would not appear in
+   * the audit log at all, and the most security-relevant events (someone
+   * trying to invoke an action they're not authorized for) would silently
+   * disappear. The tool MUST call this before returning the denial envelope.
+   */
+  writeAuthorityFail(ctx, extras) {
+    return this.write({
+      phase: "authority-check-fail",
+      ctx,
+      // Re-use the errorMessage field for the denial reason so the on-disk
+      // shape stays identical to other failure phases.
+      error: extras.reason
+    });
+  }
+  /** Phase 4 in the tool, success path. */
+  writeHttpCallSuccess(ctx, extras) {
+    return this.write({
+      phase: "http-call-success",
+      ctx,
+      status: extras.status,
+      output: extras.output
+    });
+  }
+  /** Phase 4 in the tool, failure path. */
+  writeHttpCallFailure(ctx, extras) {
+    return this.write({
+      phase: "http-call-failure",
+      ctx,
+      status: extras.status,
+      error: extras.error
+    });
+  }
+  /**
+   * Wait for all pending writes to complete. Useful for tests and graceful
+   * shutdown — the chain head lock resolves once every queued write has
+   * finished (success or swallowed-failure). Never throws.
+   */
+  async flush() {
+    while (this.queueDepth > 0) {
+      await this.chainHeadLock;
+    }
+  }
+  // ─── Internal ──────────────────────────────────────────────────────────
+  write(args) {
+    if (this.queueDepth >= this.maxQueueDepth) {
+      this.logger.warn(
+        `[skill-audit] queue overflow (${this.queueDepth}/${this.maxQueueDepth}); dropping ${args.phase} record. Audit backend likely unhealthy.`
+      );
+      this.metrics?.incrementDropped?.("queue-overflow");
+      return Promise.resolve();
+    }
+    this.queueDepth += 1;
+    const next = this.chainHeadLock.then(() => this.doWrite(args));
+    this.chainHeadLock = next.catch(() => void 0).finally(() => {
+      this.queueDepth -= 1;
+    });
+    return next.catch(() => void 0);
+  }
+  async doWrite(args) {
+    const { phase, ctx, status, output, error } = args;
+    let prev;
+    try {
+      prev = await this.store.tail();
+    } catch (e) {
+      this.logger.warn(`[skill-audit] failed to load chain tail: ${e.message}`);
+      this.metrics?.incrementWriteFailure("append");
+      return;
+    }
+    let inputHash;
+    try {
+      inputHash = sha256Hex4(canonicalize(ctx.input ?? null));
+    } catch (e) {
+      this.logger.warn(`[skill-audit] failed to canonicalize input: ${e.message}`);
+      this.metrics?.incrementWriteFailure("unexpected");
+      return;
+    }
+    let sequence;
+    try {
+      sequence = await this.store.nextSequence();
+    } catch (e) {
+      this.logger.warn(`[skill-audit] failed to allocate sequence: ${e.message}`);
+      this.metrics?.incrementWriteFailure("append");
+      return;
+    }
+    const partial = {
+      id: randomUUID(),
+      sequence,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      subject: this.applySubjectMode(ctx.subject || "anonymous"),
+      skillId: ctx.skillId,
+      actionId: ctx.actionId,
+      bundleId: ctx.bundleId,
+      bundleVersion: ctx.bundleVersion,
+      phase,
+      inputHash,
+      ...status !== void 0 ? { status } : {},
+      ...phase === "http-call-success" ? { outputHash: this.safeHash(output) } : {},
+      ...phase === "http-call-failure" || phase === "authority-check-fail" ? { errorMessage: this.formatError(error) } : {}
+    };
+    const linked = linkRecord(prev, partial);
+    let signed;
+    try {
+      const sig = this.signer.sign(linked);
+      signed = {
+        ...linked,
+        signature: sig.signature,
+        signatureKeyId: sig.keyId,
+        signatureAlg: sig.alg
+      };
+    } catch (e) {
+      this.logger.warn(`[skill-audit] failed to sign record at seq=${sequence}: ${e.message}`);
+      this.metrics?.incrementWriteFailure("sign");
+      await this.tryDecrementSequence(sequence);
+      return;
+    }
+    try {
+      await this.store.appendAtSequence(signed);
+      this.logger.debug?.(`[skill-audit] appended seq=${sequence} phase=${phase}`);
+    } catch (e) {
+      this.logger.warn(`[skill-audit] failed to append record at seq=${sequence}: ${e.message}`);
+      this.metrics?.incrementWriteFailure("append");
+      await this.tryDecrementSequence(sequence);
+    }
+  }
+  /**
+   * Best-effort sequence rollback. Storage adapters that support `decr` will
+   * close the gap; ones that don't are no-ops. We never throw out of this
+   * helper — a failed rollback is strictly worse than a permanent gap.
+   *
+   * Detection is duck-typed (we look at `.adapter.decr` and `.options.sequenceKey`)
+   * because the SkillAuditStore interface intentionally doesn't expose
+   * sequence-mutation methods — those are storage-specific implementation
+   * detail, and forcing every implementation to expose them would push the
+   * complexity onto every adapter even when the underlying store can't
+   * support transactional rollback.
+   */
+  async tryDecrementSequence(allocated) {
+    const storeAny = this.store;
+    if (!storeAny.adapter || typeof storeAny.adapter.decr !== "function") return;
+    const sequenceKey = storeAny.options?.sequenceKey ?? "audit:skills:sequence";
+    try {
+      await storeAny.adapter.decr(sequenceKey);
+      this.logger.debug?.(`[skill-audit] rolled back unused sequence ${allocated}`);
+    } catch {
+    }
+  }
+  /** Apply the configured subject-mode redaction. */
+  applySubjectMode(subject) {
+    if (this.subjectMode === "plain") return subject;
+    if (this.subjectMode === "omit") return "redacted";
+    const mac = hmacSha2562(this.subjectHashSecret, new TextEncoder().encode(subject));
+    const hex = bytesToHex(mac);
+    return `hashed:${hex.slice(0, 32)}`;
+  }
+  /**
+   * Default subject-hash secret derivation when the host doesn't supply one.
+   * Returns a deterministic 32-byte key seeded from the signer's keyId so
+   * two SkillAuditWriter instances configured against the same signer
+   * produce stable subject hashes — useful for joining records across
+   * writer reconfigurations within the same logical deployment. NOT a
+   * cryptographic key in its own right — the host SHOULD override via
+   * constructor options for production deployments.
+   */
+  deriveDefaultSubjectSecret() {
+    const key = new Uint8Array(32);
+    const seed = new TextEncoder().encode(`frontmcp:audit:subject:${this.signer.getKeyId()}`);
+    for (let i = 0; i < key.length; i++) {
+      key[i] = seed[i % seed.length] ?? 0;
+    }
+    return key;
+  }
+  /**
+   * Hash arbitrary output. Falls back to a sentinel if canonicalization
+   * fails (circular references, non-serializable values) — the verifier
+   * will treat it as a hash like any other.
+   */
+  safeHash(value) {
+    try {
+      return sha256Hex4(canonicalize(value ?? null));
+    } catch {
+      return sha256Hex4("audit:non-canonicalizable-output");
+    }
+  }
+  /** Truncate + sanitize an error to fit in the record. */
+  formatError(error) {
+    let raw;
+    if (error instanceof Error) {
+      raw = error.message;
+    } else if (typeof error === "string") {
+      raw = error;
+    } else if (error === void 0 || error === null) {
+      raw = "";
+    } else {
+      try {
+        raw = JSON.stringify(error);
+      } catch {
+        raw = String(error);
+      }
+    }
+    if (raw.length > SKILL_AUDIT_ERROR_MESSAGE_MAX) {
+      return raw.slice(0, SKILL_AUDIT_ERROR_MESSAGE_MAX) + "...";
+    }
+    return raw;
+  }
+};
+
+// libs/adapters/src/skills/audit/audit-config.ts
+var SkillAuditWriterToken = /* @__PURE__ */ Symbol.for(
+  "frontmcp:SKILL_AUDIT_WRITER"
+);
+
+// libs/adapters/src/skills/index.ts
+import { hasSkillAuditFactory, setSkillAuditFactory } from "@frontmcp/sdk";
+export {
+  BundlePinnedError,
+  BundlePushJwtVerifier,
+  BundleStore,
+  FilesystemSkillsSource,
+  Hs256AuditSigner,
+  MemoryAuditStore,
+  NpmSource,
+  OverlayParseError,
+  Rs256AuditSigner,
+  SKILL_AUDIT_ERROR_MESSAGE_MAX,
+  SKILL_AUDIT_GENESIS_PREV_HASH,
+  SKILL_AUDIT_KEYS,
+  SKILL_AUDIT_QUEUE_MAX,
+  SaasPullSource,
+  SkillAuditWriter,
+  SkillAuditWriterToken,
+  SkillDependencyCycleError,
+  SkillDependencyInvariantError,
+  SkillDependencyMissingError,
+  StaticSource,
+  StorageAdapterAuditStore,
+  WebhookReplayGuard,
+  bundleDigest,
+  bundleSkillToActions,
+  bundleSourceSchema,
+  canonicalize,
+  canonicalizeRecordForSigning,
+  createBundleSource,
+  crossValidate,
+  defaultAuditSignatureVerifier,
+  diffBundles,
+  formatDiffSummary,
+  hasSkillAuditFactory,
+  linkRecord,
+  loadFilesystemSkill,
+  nextPrevHash,
+  npmSourceSchema,
+  parseOverlay,
+  parseSkillFrontmatter,
+  resolveSkillLoadOrder,
+  resolvedBundleSchema,
+  saasSourceSchema,
+  setSkillAuditFactory,
+  signatureKeySchema,
+  staticSourceSchema,
+  verifyBundleSignature,
+  verifyChain
+};