@yaklabs-ai/plugin-sdk 0.8.4

package/dist/disclosure.js

@@ -0,0 +1,873 @@
+// packages/plugin-sdk/dist/disclosure/disclosure-conformance.js
+import { readFile } from "node:fs/promises";
+
+// packages/herd-uri/dist/connection.js
+var CONNECTION_SELECTOR_RE = /^([a-zA-Z][a-zA-Z0-9+.-]*:\/\/)@([^/]+)(?:\/(.*))?$/;
+function parseUriConnectionSelector(input) {
+  const match = CONNECTION_SELECTOR_RE.exec(input.trim());
+  if (match?.[1] === void 0 || match[2] === void 0) {
+    return { rest: input };
+  }
+  return { selector: match[2], rest: `${match[1]}${match[3] ?? ""}` };
+}
+
+// packages/herd-uri/dist/template-route.js
+var PLACEHOLDER_RE = /<([^<>]+)>/g;
+var REST_SUFFIX = "...";
+var SCHEME_RE = /^([a-zA-Z][a-zA-Z0-9+.-]*):(?:\/\/)?(.*)$/s;
+function parseRoute(address) {
+  const trimmed = address.trim();
+  const match = SCHEME_RE.exec(trimmed);
+  const scheme = match?.[1]?.toLowerCase() ?? "";
+  const rest = match?.[2] ?? trimmed;
+  const [rawPath = "", rawQuery] = splitQuery(rest);
+  const path = rawPath.replace(/^\/+/, "").replace(/\/+$/, "");
+  const query = /* @__PURE__ */ new Map();
+  if (rawQuery !== void 0) {
+    for (const pair of rawQuery.split("&")) {
+      if (pair.length === 0)
+        continue;
+      const eq = pair.indexOf("=");
+      const key = eq === -1 ? pair : pair.slice(0, eq);
+      const value = eq === -1 ? "" : pair.slice(eq + 1);
+      if (key.length === 0)
+        continue;
+      if (!query.has(key) || isPlaceholder(value))
+        query.set(key, value);
+    }
+  }
+  return { scheme, path, query };
+}
+function splitQuery(rest) {
+  const hash = rest.indexOf("#");
+  const withoutFragment = hash === -1 ? rest : rest.slice(0, hash);
+  const q = withoutFragment.indexOf("?");
+  return q === -1 ? [withoutFragment, void 0] : [withoutFragment.slice(0, q), withoutFragment.slice(q + 1)];
+}
+function isPlaceholder(value) {
+  return /^<[^<>]+>$/.test(value);
+}
+function selectorPlaceholder(templateUri) {
+  const selector = parseUriConnectionSelector(templateUri).selector;
+  if (selector === void 0)
+    return void 0;
+  const match = /^<([^<>]+)>$/.exec(selector);
+  return match?.[1];
+}
+function isRestPlaceholder(name) {
+  return name.endsWith(REST_SUFFIX);
+}
+function placeholderParameterName(name) {
+  return isRestPlaceholder(name) ? name.slice(0, -REST_SUFFIX.length) : name;
+}
+function templateAddressProblem(templateUri) {
+  const parsed = parseRoute(stripUriSelector(templateUri));
+  for (const match of parsed.path.matchAll(PLACEHOLDER_RE)) {
+    const name = match[1] ?? "";
+    if (name.includes("/")) {
+      return `placeholder <${name}> contains a slash; use <${name.split("/")[0] ?? "path"}...> as the last segment for a rest-of-path placeholder`;
+    }
+    if (isRestPlaceholder(name) && match.index + match[0].length !== parsed.path.length) {
+      return `rest-of-path placeholder <${name}> must be the last path segment`;
+    }
+  }
+  return void 0;
+}
+function stripUriSelector(address) {
+  return parseUriConnectionSelector(address).rest;
+}
+function templatePlaceholders(templateUri) {
+  return deriveTemplateParameters({ uri: templateUri, description: "" }).map((parameter) => parameter.name);
+}
+function deriveTemplateParameters(template) {
+  const authored = new Map((template.parameters ?? []).map((parameter) => [parameter.name, parameter]));
+  const parsed = parseRoute(stripUriSelector(template.uri));
+  const derived = [];
+  const selector = selectorPlaceholder(template.uri);
+  if (selector !== void 0) {
+    derived.push(authored.get(selector) ?? {
+      name: selector,
+      in: "selector",
+      required: false,
+      schema: { type: "string" }
+    });
+  }
+  for (const match of parsed.path.matchAll(PLACEHOLDER_RE)) {
+    const name = placeholderParameterName(match[1] ?? "");
+    if (name.length === 0 || derived.some((p) => p.name === name))
+      continue;
+    derived.push(authored.get(name) ?? {
+      name,
+      in: "uri",
+      required: true,
+      schema: { type: "string" }
+    });
+  }
+  for (const [key, value] of parsed.query) {
+    if (derived.some((p) => p.name === key))
+      continue;
+    const schema = isPlaceholder(value) ? { type: "string" } : { type: "string", enum: value.split("|").filter((v) => v.length > 0) };
+    derived.push(authored.get(key) ?? {
+      name: key,
+      in: "query",
+      required: false,
+      schema
+    });
+  }
+  const derivedNames = new Set(derived.map((parameter) => parameter.name));
+  const extra = (template.parameters ?? []).filter((parameter) => !derivedNames.has(parameter.name));
+  return [...derived, ...extra];
+}
+
+// packages/herd-uri/dist/template-lint.js
+function lintUriTemplate(template) {
+  const findings = [];
+  const addressProblem = templateAddressProblem(template.uri);
+  if (addressProblem !== void 0) {
+    findings.push({
+      rule: "template-address-unmatchable",
+      uri: template.uri,
+      message: `${template.uri} can never be matched by help: ${addressProblem}.`
+    });
+  }
+  const operations = template.operations ?? [];
+  if (operations.filter((operation) => operation !== "help").length === 0) {
+    findings.push({
+      rule: "template-operations-missing",
+      uri: template.uri,
+      message: `${template.uri} lists no operations; a route must declare the verbs it supports.`
+    });
+  }
+  for (const operation of operations) {
+    if ((operation === "write" || operation === "edit") && template.accepts?.[operation] === void 0) {
+      findings.push({
+        rule: "template-accepts-missing",
+        uri: template.uri,
+        operation,
+        message: `${template.uri} lists ${operation} but declares no accepts.${operation} payload contract (use payload() from the handler's validator, or an explicit contract without a schema for an unstructured body).`
+      });
+    }
+    if (operation === "delete" && template.deleteEffect === void 0) {
+      findings.push({
+        rule: "template-delete-effect-missing",
+        uri: template.uri,
+        operation,
+        message: `${template.uri} lists delete but declares no deleteEffect (trash, permanent, or conditional).`
+      });
+    }
+    if (operation === "help")
+      continue;
+    const sentence = template.operationDocs?.[operation];
+    const soleVerb = operations.filter((candidate) => candidate !== "help").length === 1;
+    if (sentence === void 0 && !soleVerb) {
+      findings.push({
+        rule: "template-operation-docs-missing",
+        uri: template.uri,
+        operation,
+        message: `${template.uri} lists ${operation} alongside other verbs and has no operationDocs.${operation} sentence.`
+      });
+    }
+  }
+  const placeholders = new Set(templatePlaceholders(template.uri));
+  for (const parameter of template.parameters ?? []) {
+    if (placeholders.has(parameter.name))
+      continue;
+    findings.push({
+      rule: "template-parameter-unknown",
+      uri: template.uri,
+      parameter: parameter.name,
+      message: `${template.uri} authors parameter "${parameter.name}" but the address has no <${parameter.name}> placeholder.`
+    });
+  }
+  return findings;
+}
+
+// packages/herd-uri/dist/operations.js
+import { z } from "zod";
+var URI_OPERATIONS = [
+  "help",
+  "read",
+  "write",
+  "edit",
+  "list",
+  "search",
+  "delete"
+];
+var UriOperationSchema = z.enum(URI_OPERATIONS);
+
+// packages/herd-uri/dist/help-schema.js
+import { z as z2 } from "zod";
+var UriContractJsonSchema = z2.record(z2.string(), z2.unknown());
+var UriParameterSchema = z2.strictObject({
+  name: z2.string().min(1),
+  in: z2.enum(["uri", "query", "selector"]),
+  required: z2.boolean(),
+  description: z2.string().optional(),
+  schema: UriContractJsonSchema,
+  examples: z2.array(z2.unknown()).optional()
+});
+var UriPayloadContractSchema = z2.strictObject({
+  name: z2.string().min(1),
+  mediaType: z2.string().optional(),
+  description: z2.string().optional(),
+  schema: UriContractJsonSchema.optional(),
+  semanticConstraints: z2.array(z2.string().min(1)).min(1).optional(),
+  examples: z2.array(z2.unknown()).optional()
+});
+
+// packages/herd-uri/dist/text-edit.js
+import { z as z3 } from "zod";
+var findReplaceArm = z3.strictObject({
+  find: z3.string().min(1),
+  replace: z3.string(),
+  all: z3.boolean().optional()
+});
+var oldNewEntry = z3.strictObject({
+  oldText: z3.string().min(1),
+  newText: z3.string()
+});
+var uriTextEditPayloadArms = z3.union([
+  findReplaceArm,
+  z3.strictObject({ edits: z3.array(oldNewEntry).min(1) }),
+  oldNewEntry,
+  z3.array(oldNewEntry).min(1)
+]);
+
+// packages/herd-uri/dist/schema/to-json-schema.js
+import { z as z4 } from "zod";
+
+// packages/herd-agent/dist/core/tools/tool-parameters.js
+import { z as z5 } from "zod";
+var URI_PAYLOAD_MARKER = "x-kay-uri-payload";
+var uriPayloadSchema = z5.union([
+  z5.string(),
+  z5.record(z5.string(), z5.unknown()),
+  z5.array(z5.unknown()),
+  z5.number(),
+  z5.boolean(),
+  z5.null()
+]).meta({ [URI_PAYLOAD_MARKER]: true });
+
+// packages/herd-agent/dist/core/tools/uri/hint-tiers.js
+var FIELD_LIMIT_CHARS = 220;
+var FLOW_LABEL_LIMIT_CHARS = 80;
+var FLOW_WHEN_LIMIT_CHARS = 120;
+var HELP_URI_LIMIT_CHARS = 140;
+var LIST_LIMIT = 8;
+var LIST_ITEM_LIMIT_CHARS = 60;
+var URI_HINT_FIELD_LIMITS = {
+  /** Max chars for `agentHint.summary` (and, today, each flow's `example`). */
+  summary: FIELD_LIMIT_CHARS,
+  /** Max chars for a `commonFlows[].label`. */
+  flowLabel: FLOW_LABEL_LIMIT_CHARS,
+  /** Max chars for a `commonFlows[].when`. */
+  flowWhen: FLOW_WHEN_LIMIT_CHARS,
+  /** Max chars for a `commonFlows[].example`. */
+  flowExample: FIELD_LIMIT_CHARS,
+  /** Max chars for `agentHint.helpUri`. */
+  helpUri: HELP_URI_LIMIT_CHARS,
+  /** Max entries in `triggers.keywords` / `triggers.patterns`. */
+  triggerListItems: LIST_LIMIT,
+  /** Max chars for one `triggers.keywords` / `triggers.patterns` entry. */
+  triggerItem: LIST_ITEM_LIMIT_CHARS
+};
+
+// packages/plugin-sdk/dist/disclosure/disclosure-conformance.js
+var PLUGIN_DISCLOSURE_RULES = [
+  // (a) the agentHint a module must ship to be discoverable at all
+  "agent-hint-missing",
+  "agent-hint-summary-empty",
+  "agent-hint-flows-empty",
+  "agent-hint-triggers-missing",
+  // (b) help() well-formedness, per claimed scheme root
+  "scheme-claim-missing",
+  "help-missing",
+  "help-malformed",
+  "help-throws",
+  "help-uri-malformed",
+  "help-uri-throws",
+  // (c) the verb-documentation floor (#2863, #2935) — what a permission surface renders
+  "verb-coverage-missing",
+  "template-operation-docs-missing",
+  "verb-docs-missing",
+  // (c2) the route-contract floor (#6880, contract 2): a route's template is the whole
+  // contract for that route, so a mutating verb without its payload contract, a delete
+  // without its effect, or an authored parameter with no placeholder is a load-time defect.
+  // Rules are evaluated by `@herd/uri`'s `lintUriTemplate` so the daemon's built-in
+  // modules, a plugin's own suite, and this audit run the identical function.
+  "template-accepts-missing",
+  "template-address-unmatchable",
+  "template-delete-effect-missing",
+  "template-operations-missing",
+  "template-parameter-unknown",
+  // (c3) a template's address must be one the module can be asked about: its scheme
+  // is one the module claims (a scheme-less shorthand like `<conversation>/messages`
+  // never matches a `teams://` address). Module-aware, so it lives here and not in
+  // the pure per-template lint.
+  "template-scheme-mismatch",
+  // (d) the field clamps, measured against herd's own render limits
+  "clamp-summary",
+  "clamp-flow-label",
+  "clamp-flow-when",
+  "clamp-flow-example",
+  "clamp-trigger-count",
+  "clamp-trigger-item",
+  "clamp-help-uri",
+  // (e) module <-> bundled-skill cross-link integrity
+  "skill-link-dangling",
+  "skill-link-missing-scheme",
+  // (f) auditSkillCodegenPairs: a declared SKILL.md and its exported codegen pair must say the
+  // same thing. Rule ids below deliberately KEEP the historical `skill-twin-*` prefix even
+  // though the function and its prose were renamed (see PR that renamed `auditSkillCodegenPairs` to
+  // free "twin" for the Skills v2 product concept): `test/disclosure/conformance-contract.test.ts`
+  // pins CONTRACT_HISTORY's contract-1 entry byte-for-byte as the published SDK 0.3.0 floor, and
+  // changing a rule id string is exactly the kind of edit that test exists to catch — it would
+  // require appending a new CONTRACT_HISTORY entry, bumping `PLUGIN_DISCLOSURE_CONTRACT`, and
+  // cutting a new SDK release, none of which this rename earns. A rule id is a wire-visible
+  // string a third-party plugin's own suite may already assert on; renaming the function is free,
+  // renaming a published contract's rule ids is not.
+  "skill-twin-count-mismatch",
+  "skill-twin-missing-declaration",
+  "skill-twin-description-mismatch",
+  "skill-twin-file-unreadable",
+  "skill-twin-frontmatter-name-mismatch",
+  "skill-twin-frontmatter-description-mismatch",
+  "skill-twin-body-mismatch"
+];
+var PLUGIN_DISCLOSURE_CONTRACT = 2;
+var FAKE_RESOLVE_CONTEXT = { cwd: "/" };
+async function auditPluginDisclosure(input) {
+  const violations = [];
+  const hintBearing = input.modules.filter((module) => module.agentHint !== void 0);
+  violations.push(...auditHintPresence(input.modules));
+  for (const module of hintBearing) {
+    const hint = module.agentHint;
+    violations.push(...auditHintCompleteness(module, hint));
+    violations.push(...auditClampFit(module, hint));
+    const helpProbe = await auditHelp(module);
+    violations.push(...helpProbe.violations);
+    violations.push(...await auditHelpUri(module, hint));
+    violations.push(...auditVerbCoverage(module, helpProbe.helps));
+    violations.push(...auditRouteContracts(module, helpProbe.helps));
+    violations.push(...auditVerbDocs(module));
+    violations.push(...auditSkillsCrossLink(module, hint, input.declaredSkills));
+  }
+  violations.push(...auditUnlinkedSkills(hintBearing, input.declaredSkills, new Set(input.commandBoundSkillIds ?? [])));
+  return violations;
+}
+function auditHintPresence(modules) {
+  const violations = [];
+  for (const module of modules) {
+    if (module.agentHint !== void 0)
+      continue;
+    const roots = schemeRoots(module);
+    if (roots.length === 0)
+      continue;
+    violations.push({
+      moduleId: module.id,
+      rule: "agent-hint-missing",
+      detail: `Module '${module.id}' claims ${roots.join(", ")} but ships no agentHint, so no agent can ever learn it exists: the hint is the only thing the system prompt renders for a URI module, and the only thing the catalog projects. The module would dispatch correctly and stay invisible. Add an agentHint with a summary, at least one commonFlows entry, and at least one trigger.`
+    });
+  }
+  return violations;
+}
+function auditHintCompleteness(module, hint) {
+  const violations = [];
+  if (hint.summary.trim().length === 0) {
+    violations.push({
+      moduleId: module.id,
+      rule: "agent-hint-summary-empty",
+      detail: "agentHint.summary must be a non-empty string."
+    });
+  }
+  if (hint.commonFlows === void 0 || hint.commonFlows.length === 0) {
+    violations.push({
+      moduleId: module.id,
+      rule: "agent-hint-flows-empty",
+      detail: "agentHint.commonFlows must carry at least one worked flow."
+    });
+  }
+  const keywords = hint.triggers?.keywords ?? [];
+  const patterns = hint.triggers?.patterns ?? [];
+  if (keywords.length === 0 && patterns.length === 0) {
+    violations.push({
+      moduleId: module.id,
+      rule: "agent-hint-triggers-missing",
+      detail: "agentHint.triggers must declare at least one keyword or pattern."
+    });
+  }
+  return violations;
+}
+function isWellFormedHelp(value) {
+  if (typeof value !== "object" || value === null)
+    return false;
+  const help = value;
+  return typeof help.uri === "string" && help.uri.trim().length > 0 && typeof help.title === "string" && help.title.trim().length > 0 && typeof help.summary === "string" && help.summary.trim().length > 0;
+}
+function schemeRoots(module) {
+  return (module.claims ?? []).filter((claim) => claim.kind === "scheme").map((claim) => `${claim.scheme}://`);
+}
+async function auditHelp(module) {
+  if (module.help === void 0) {
+    return {
+      violations: [
+        {
+          moduleId: module.id,
+          rule: "help-missing",
+          detail: "Module has no help(); since #1125 the system prompt promises help() works for every space."
+        }
+      ],
+      helps: []
+    };
+  }
+  const roots = schemeRoots(module);
+  if (roots.length === 0) {
+    return {
+      violations: [
+        {
+          moduleId: module.id,
+          rule: "scheme-claim-missing",
+          detail: `Module has an agentHint but no { kind: "scheme" } claim, so its scheme root can't be located to call help() on.`
+        }
+      ],
+      helps: []
+    };
+  }
+  const violations = [];
+  const helps = [];
+  for (const root of roots) {
+    try {
+      const result = await module.help(root, FAKE_RESOLVE_CONTEXT);
+      if (isWellFormedHelp(result)) {
+        helps.push(result);
+      } else {
+        violations.push({
+          moduleId: module.id,
+          rule: "help-malformed",
+          detail: `help(${JSON.stringify(root)}) returned a value missing a non-empty uri/title/summary.`
+        });
+      }
+    } catch (error) {
+      violations.push({
+        moduleId: module.id,
+        rule: "help-throws",
+        detail: `help(${JSON.stringify(root)}) threw: ${errorMessage(error)}`
+      });
+    }
+  }
+  return { violations, helps };
+}
+function supportedVerbs(module) {
+  const verbs = [];
+  if (module.verbs.readable)
+    verbs.push("read");
+  if (module.verbs.listable && module.list !== void 0)
+    verbs.push("list");
+  if (module.verbs.listable && module.search !== void 0) {
+    verbs.push("search");
+  }
+  if (module.verbs.writable)
+    verbs.push("write");
+  if (module.verbs.editable)
+    verbs.push("edit");
+  if (module.verbs.deletable === true || module.delete !== void 0) {
+    verbs.push("delete");
+  }
+  return verbs;
+}
+function helpTemplates(helps) {
+  return helps.flatMap((help) => help.templates ?? []);
+}
+function auditVerbCoverage(module, helps) {
+  if (helps.length === 0)
+    return [];
+  const covered = new Set(helpTemplates(helps).flatMap((template) => template.operations ?? []));
+  const violations = [];
+  for (const verb of supportedVerbs(module)) {
+    if (covered.has(verb))
+      continue;
+    violations.push({
+      moduleId: module.id,
+      rule: "verb-coverage-missing",
+      detail: `Module '${module.id}' supports '${verb}' but no help() template lists it in 'operations', so there is no documented route for the verb. Add (or extend) a template naming the address shape '${verb}' acts on.`
+    });
+  }
+  return violations;
+}
+function auditRouteContracts(module, helps) {
+  const schemes = new Set((module.claims ?? []).flatMap((claim) => claim.kind === "scheme" ? [claim.scheme.toLowerCase()] : []));
+  const hasPatternClaim = (module.claims ?? []).some((claim) => claim.kind !== "scheme");
+  return helpTemplates(helps).flatMap((template) => {
+    const violations = lintUriTemplate(template).map((finding) => ({
+      moduleId: module.id,
+      rule: finding.rule,
+      detail: finding.message
+    }));
+    const scheme = /^([a-zA-Z][a-zA-Z0-9+.-]*):/.exec(template.uri.trim())?.[1];
+    if (schemes.size > 0 && !hasPatternClaim) {
+      if (scheme === void 0 || !schemes.has(scheme.toLowerCase())) {
+        violations.push({
+          moduleId: module.id,
+          rule: "template-scheme-mismatch",
+          detail: `Template '${template.uri}' ${scheme === void 0 ? "has no scheme" : `uses scheme '${scheme}'`}, but module '${module.id}' claims ${[...schemes].map((s) => `'${s}://'`).join(", ")}. help selects a route by scheme and path, so this template can never be asked about; write the full address (e.g. '${[...schemes][0]}://\u2026').`
+        });
+      }
+    }
+    return violations;
+  });
+}
+function auditVerbDocs(module) {
+  const violations = [];
+  for (const verb of supportedVerbs(module)) {
+    const doc = module.verbDocs?.[verb];
+    if (doc !== void 0 && doc.trim().length > 0)
+      continue;
+    violations.push({
+      moduleId: module.id,
+      rule: "verb-docs-missing",
+      detail: `Module '${module.id}' supports '${verb}' but verbDocs.${verb} is ${module.verbDocs === void 0 ? "absent (no verbDocs at all)" : "missing or empty"}. Document the verb's concrete provider effect in one plain sentence (and, for delete, how recoverable it is). Never wire mechanics or URI shapes.`
+    });
+  }
+  return violations;
+}
+async function auditHelpUri(module, hint) {
+  if (hint.helpUri === void 0 || module.help === void 0)
+    return [];
+  try {
+    const result = await module.help(hint.helpUri, FAKE_RESOLVE_CONTEXT);
+    if (!isWellFormedHelp(result)) {
+      return [
+        {
+          moduleId: module.id,
+          rule: "help-uri-malformed",
+          detail: `help(${JSON.stringify(hint.helpUri)}) (agentHint.helpUri) returned a value missing a non-empty uri/title/summary.`
+        }
+      ];
+    }
+  } catch (error) {
+    return [
+      {
+        moduleId: module.id,
+        rule: "help-uri-throws",
+        detail: `help(${JSON.stringify(hint.helpUri)}) (agentHint.helpUri) threw: ${errorMessage(error)}`
+      }
+    ];
+  }
+  return [];
+}
+function auditClampFit(module, hint) {
+  const violations = [];
+  const limits = URI_HINT_FIELD_LIMITS;
+  if (hint.summary.length > limits.summary) {
+    violations.push(clampViolation(module.id, "clamp-summary", "agentHint.summary", hint.summary.length, limits.summary));
+  }
+  for (const [index, flow] of (hint.commonFlows ?? []).entries()) {
+    if (flow.label.length > limits.flowLabel) {
+      violations.push(clampViolation(module.id, "clamp-flow-label", `agentHint.commonFlows[${index}].label`, flow.label.length, limits.flowLabel));
+    }
+    if (flow.when !== void 0 && flow.when.length > limits.flowWhen) {
+      violations.push(clampViolation(module.id, "clamp-flow-when", `agentHint.commonFlows[${index}].when`, flow.when.length, limits.flowWhen));
+    }
+    if (flow.example.length > limits.flowExample) {
+      violations.push(clampViolation(module.id, "clamp-flow-example", `agentHint.commonFlows[${index}].example`, flow.example.length, limits.flowExample));
+    }
+  }
+  for (const kind of ["keywords", "patterns"]) {
+    const values = hint.triggers?.[kind] ?? [];
+    if (values.length > limits.triggerListItems) {
+      violations.push({
+        moduleId: module.id,
+        rule: "clamp-trigger-count",
+        detail: `agentHint.triggers.${kind} has ${values.length} entries, over the ${limits.triggerListItems}-item limit.`
+      });
+    }
+    for (const [index, value] of values.entries()) {
+      if (value.length > limits.triggerItem) {
+        violations.push(clampViolation(module.id, "clamp-trigger-item", `agentHint.triggers.${kind}[${index}]`, value.length, limits.triggerItem));
+      }
+    }
+  }
+  if (hint.helpUri !== void 0 && hint.helpUri.length > limits.helpUri) {
+    violations.push(clampViolation(module.id, "clamp-help-uri", "agentHint.helpUri", hint.helpUri.length, limits.helpUri));
+  }
+  return violations;
+}
+function clampViolation(moduleId, rule, field, actual, max) {
+  return {
+    moduleId,
+    rule,
+    detail: `${field} is ${actual} chars, over the ${max}-char limit.`
+  };
+}
+function auditSkillsCrossLink(module, hint, declaredSkills) {
+  const violations = [];
+  const roots = schemeRoots(module);
+  for (const skillName of hint.skills ?? []) {
+    const skill = declaredSkills.find((s) => s.localId === skillName);
+    if (skill === void 0) {
+      violations.push({
+        moduleId: module.id,
+        rule: "skill-link-dangling",
+        detail: `agentHint.skills names '${skillName}', which is not a declared skill localId of this plugin.`
+      });
+      continue;
+    }
+    if (roots.length > 0 && !roots.some((root) => skill.description.includes(root))) {
+      violations.push({
+        moduleId: module.id,
+        rule: "skill-link-missing-scheme",
+        detail: `Skill '${skillName}' is linked from module '${module.id}' but its description names none of its scheme(s) (${roots.join(", ")}); the skill index shows only name/description before load, so the description is the only place this link can live.`
+      });
+    }
+  }
+  return violations;
+}
+function auditUnlinkedSkills(hintBearingModules, declaredSkills, commandBoundSkillIds) {
+  const linkedNames = /* @__PURE__ */ new Set();
+  for (const module of hintBearingModules) {
+    for (const name of module.agentHint?.skills ?? [])
+      linkedNames.add(name);
+  }
+  const pluginRoots = hintBearingModules.flatMap((module) => schemeRoots(module));
+  if (pluginRoots.length === 0)
+    return [];
+  const violations = [];
+  for (const skill of declaredSkills) {
+    if (linkedNames.has(skill.localId))
+      continue;
+    if (commandBoundSkillIds.has(skill.localId))
+      continue;
+    if (!pluginRoots.some((root) => skill.description.includes(root))) {
+      violations.push({
+        moduleId: skill.localId,
+        rule: "skill-link-missing-scheme",
+        detail: `Declared skill '${skill.localId}' is not linked from any module's agentHint.skills, but its description names none of the plugin's scheme(s) (${pluginRoots.join(", ")}); the skill index shows only name/description before load, so the description is the only place this link can live.`
+      });
+    }
+  }
+  return violations;
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+async function auditSkillCodegenPairs(input) {
+  const violations = [];
+  const { declaredSkills, exportedSkills, packageDir } = input;
+  if (declaredSkills.length !== exportedSkills.length) {
+    violations.push({
+      moduleId: "skills",
+      rule: "skill-twin-count-mismatch",
+      detail: `${declaredSkills.length} declared skill(s) but ${exportedSkills.length} exported PluginSkillDefinition(s).`
+    });
+  }
+  for (const skill of exportedSkills) {
+    const declaration = declaredSkills.find((d) => d.localId === skill.name);
+    if (declaration === void 0) {
+      violations.push({
+        moduleId: skill.name,
+        rule: "skill-twin-missing-declaration",
+        detail: `Exported skill '${skill.name}' has no manifest declaration with a matching localId.`
+      });
+      continue;
+    }
+    if (declaration.description !== skill.description) {
+      violations.push({
+        moduleId: skill.name,
+        rule: "skill-twin-description-mismatch",
+        detail: `Manifest description for '${skill.name}' does not match the exported PluginSkillDefinition's description.`
+      });
+    }
+    violations.push(
+      ...await auditSkillCodegenPairFile(skill, declaration, packageDir)
+    );
+  }
+  return violations;
+}
+async function auditSkillCodegenPairFile(skill, declaration, packageDir) {
+  let file;
+  try {
+    file = await readFile(new URL(declaration.path, packageDir), "utf8");
+  } catch (error) {
+    return [
+      {
+        moduleId: skill.name,
+        rule: "skill-twin-file-unreadable",
+        detail: `Could not read declared SKILL.md at '${declaration.path}': ${errorMessage(error)}`
+      }
+    ];
+  }
+  const codegenPairMatch = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/.exec(file);
+  const frontmatter = codegenPairMatch?.[1] === void 0 ? void 0 : `${codegenPairMatch[1]}
+`;
+  const body = codegenPairMatch?.[2];
+  const violations = [];
+  if (frontmatter === void 0 || !frontmatter.includes(`name: ${skill.name}
+`)) {
+    violations.push({
+      moduleId: skill.name,
+      rule: "skill-twin-frontmatter-name-mismatch",
+      detail: `SKILL.md frontmatter does not declare 'name: ${skill.name}'.`
+    });
+  }
+  if (frontmatter === void 0 || !frontmatter.includes(`description: ${skill.description}
+`)) {
+    violations.push({
+      moduleId: skill.name,
+      rule: "skill-twin-frontmatter-description-mismatch",
+      detail: "SKILL.md frontmatter description does not match the exported description."
+    });
+  }
+  if (body === void 0 || body.trim() !== skill.content.trim()) {
+    violations.push({
+      moduleId: skill.name,
+      rule: "skill-twin-body-mismatch",
+      detail: "SKILL.md body does not match the exported PluginSkillDefinition content."
+    });
+  }
+  return violations;
+}
+
+// packages/plugin-sdk/dist/disclosure/probe-kay-agent-capabilities.js
+var inertResult = () => new Promise(() => {
+});
+var INERT_FILESYSTEM = {
+  readText: inertResult,
+  writeText: inertResult,
+  mkdir: inertResult,
+  readDir: inertResult,
+  stat: inertResult,
+  rename: inertResult,
+  realpath: inertResult
+};
+var INERT_NETWORK = {
+  fetch: inertResult
+};
+var INERT_WEB_SESSION = {
+  request: inertResult,
+  download: inertResult
+};
+var INERT_PROCESS = {
+  run: inertResult
+};
+var INERT_WHITEBOARD = {
+  listTypes: async () => [],
+  forType: () => ({
+    payload: {
+      read: inertResult,
+      create: inertResult,
+      replace: inertResult
+    },
+    inventory: async () => ({ entries: [] }),
+    inspect: async () => void 0,
+    list: inertResult,
+    read: inertResult,
+    create: inertResult,
+    update: inertResult,
+    mutate: inertResult,
+    remove: inertResult
+  })
+};
+var INERT_WITH_JEV = async (_use, fallback) => fallback();
+function createKayAgentProbeCapabilityHandles() {
+  return {
+    filesystem: INERT_FILESYSTEM,
+    network: INERT_NETWORK,
+    webSession: INERT_WEB_SESSION,
+    process: INERT_PROCESS,
+    whiteboard: INERT_WHITEBOARD,
+    interceptToolCall: () => {
+    },
+    withJev: INERT_WITH_JEV,
+    // Fire-and-forget on the real api too, so dropping is the inert shape: nothing to hang on.
+    events: { publish: () => {
+    } }
+  };
+}
+
+// packages/plugin-sdk/dist/disclosure/probe-kay-agent-activate.js
+function collectUriModulesFromKayAgentActivate(activate) {
+  const modules = [];
+  const fakeApi = {
+    uri: {
+      registerModule: (module) => {
+        modules.push(module);
+      }
+    },
+    ...createKayAgentProbeCapabilityHandles(),
+    registerTool: () => {
+    },
+    registerSearchProvider: () => {
+    },
+    registerConverter: () => {
+    },
+    auth: {
+      advertiseService: () => {
+      },
+      declareOAuthPkceScheme: () => {
+      },
+      declareApiKeyScheme: () => {
+      },
+      declareExternalCliScheme: () => {
+      },
+      declareDelegatedScheme: () => {
+      },
+      registerDelegatedServiceSource: () => {
+      }
+    }
+  };
+  activate(fakeApi);
+  return modules;
+}
+
+// packages/plugin-sdk/dist/disclosure/probe-kay-agent-auth.js
+function collectAuthDeclarationsFromKayAgentActivate(activate) {
+  const services = [];
+  const oauthPkceSchemes = [];
+  const apiKeySchemes = [];
+  const delegatedSchemes = [];
+  const fakeApi = {
+    uri: {
+      registerModule: () => {
+      }
+    },
+    ...createKayAgentProbeCapabilityHandles(),
+    registerTool: () => {
+    },
+    registerSearchProvider: () => {
+    },
+    registerConverter: () => {
+    },
+    auth: {
+      advertiseService: (descriptor) => {
+        services.push(descriptor);
+      },
+      declareOAuthPkceScheme: (serviceId, scheme) => {
+        oauthPkceSchemes.push({ serviceId, scheme });
+      },
+      declareApiKeyScheme: (serviceId, scheme) => {
+        apiKeySchemes.push({ serviceId, scheme });
+      },
+      declareExternalCliScheme: () => {
+      },
+      declareDelegatedScheme: (serviceId, scheme) => {
+        delegatedSchemes.push({ serviceId, scheme });
+      },
+      registerDelegatedServiceSource: (source) => {
+        for (const { descriptor, scheme } of source()) {
+          services.push(descriptor);
+          delegatedSchemes.push({ serviceId: descriptor.id, scheme });
+        }
+      }
+    }
+  };
+  activate(fakeApi);
+  return { services, oauthPkceSchemes, apiKeySchemes, delegatedSchemes };
+}
+export {
+  PLUGIN_DISCLOSURE_CONTRACT,
+  PLUGIN_DISCLOSURE_RULES,
+  auditPluginDisclosure,
+  auditSkillCodegenPairs,
+  collectAuthDeclarationsFromKayAgentActivate,
+  collectUriModulesFromKayAgentActivate
+};