agent-skillboard 0.2.14 → 0.2.16

package/src/route-renderer.mjs

@@ -0,0 +1,146 @@
+const FORMATTERS = {
+  brief: {
+    prefix: "- ",
+    candidatePrefix: "  - ",
+    guardReasonPrefix: "    - ",
+    text: safeText,
+    skill: code,
+    command: (value) => code(value, Number.POSITIVE_INFINITY),
+    list: formatCodeList,
+    guardReason: safeText,
+    noMatchNextStep: "ask a clarifying question before choosing a skill.",
+    includeFallbackWhenNoRecommendation: false
+  },
+  cli: {
+    prefix: "",
+    candidatePrefix: "- ",
+    guardReasonPrefix: "  - ",
+    text: String,
+    skill: String,
+    command: String,
+    list: formatRawCodeList,
+    guardReason: String,
+    noMatchNextStep: null,
+    includeFallbackWhenNoRecommendation: true
+  }
+};
+
+export function renderRouteSectionLines(route, options = {}) {
+  const formatter = FORMATTERS[options.format ?? "cli"] ?? FORMATTERS.cli;
+  const lines = [];
+  pushRouteMatchLines(lines, route, formatter, options);
+  if (route.recommended_skill === null) {
+    pushNoRecommendationLines(lines, route, formatter);
+    return lines;
+  }
+  pushRecommendationLines(lines, route, formatter, options);
+  return lines;
+}
+
+function pushRouteMatchLines(lines, route, formatter, options) {
+  lines.push(`${formatter.prefix}Intent: ${formatter.text(route.intent)}`);
+  if (options.includeWorkflow === true) {
+    lines.push(`${formatter.prefix}Workflow: ${formatter.text(route.workflow)}`);
+  }
+  lines.push(`${formatter.prefix}Match source: ${route.match_source}`);
+  lines.push(`${formatter.prefix}Matched capability: ${route.matched_capability ?? "none"}`);
+  lines.push(`${formatter.prefix}Matched skill: ${route.matched_skill === null || route.matched_skill === undefined ? "none" : formatter.skill(route.matched_skill)}`);
+  lines.push(`${formatter.prefix}Confidence: ${route.confidence}`);
+  lines.push(`${formatter.prefix}Why: ${formatter.text(route.recommendation_reason, 320)}`);
+  lines.push(`${formatter.prefix}Matched terms: ${formatter.list(route.matched_terms)}`);
+}
+
+function pushNoRecommendationLines(lines, route, formatter) {
+  lines.push(`${formatter.prefix}Recommended skill: none`);
+  if (formatter.includeFallbackWhenNoRecommendation) {
+    lines.push(`${formatter.prefix}Fallback skills: ${formatter.list(route.fallback_skills)}`);
+  }
+  if (formatter.noMatchNextStep !== null) {
+    lines.push(`${formatter.prefix}Next step: ${formatter.noMatchNextStep}`);
+  }
+}
+
+function pushRecommendationLines(lines, route, formatter, options) {
+  lines.push(`${formatter.prefix}Recommended skill: ${formatter.skill(route.recommended_skill)}`);
+  lines.push(`${formatter.prefix}Fallback skills: ${formatter.list(route.fallback_skills)}`);
+  if (route.overlap_resolution?.status === "resolved") {
+    lines.push(`${formatter.prefix}Overlap: ${safeText(route.overlap_resolution.summary, 320)}`);
+  }
+  if (route.policy_memory?.status === "applied") {
+    lines.push(`${formatter.prefix}Policy preference: ${safeText(route.policy_memory.summary, 320)}`);
+  }
+  pushCandidateLines(lines, route.route_candidates ?? [], formatter);
+  if (typeof options.nextStep === "string" && options.nextStep.length > 0) {
+    lines.push(`${formatter.prefix}Next step: ${safeText(options.nextStep, 360)}`);
+  }
+  if (route.guard_command !== null) {
+    lines.push(`${formatter.prefix}Guard: ${formatter.command(route.guard_command)}`);
+  }
+  pushDisclosureLines(lines, route, formatter);
+  pushPostUsePolicySuggestion(lines, route.post_use_policy_suggestion, formatter);
+}
+
+function pushCandidateLines(lines, candidates, formatter) {
+  if (candidates.length === 0) {
+    return;
+  }
+  lines.push(`${formatter.prefix}Route candidates:`);
+  for (const candidate of candidates) {
+    lines.push(`${formatter.candidatePrefix}${formatter.skill(candidate.skill)} (${routeCandidateStatus(candidate)})`);
+    if (!candidate.guard_allowed && candidate.guard_reasons.length > 0) {
+      lines.push(`${formatter.guardReasonPrefix}${formatter.guardReason(candidate.guard_reasons[0])}`);
+    }
+  }
+}
+
+function pushDisclosureLines(lines, route, formatter) {
+  if (route.usage_disclosure === null || route.usage_disclosure === undefined) {
+    return;
+  }
+  const skillLabel = formatter.skill(route.recommended_skill);
+  lines.push(`${formatter.prefix}Disclosure: ${routeDisclosureText(skillLabel)}`);
+  lines.push(`${formatter.prefix}Say before use: "${formatter.text(route.usage_disclosure.start_message)}"`);
+  lines.push(`${formatter.prefix}Say after completion: "${formatter.text(route.usage_disclosure.finish_message)}"`);
+}
+
+function pushPostUsePolicySuggestion(lines, suggestion, formatter) {
+  if (suggestion === null || suggestion === undefined) {
+    return;
+  }
+  lines.push(`${formatter.prefix}After completion: ${formatter.text(afterUsePromptText(suggestion.question))}`);
+  lines.push(`${formatter.prefix}Policy command after confirmation: ${formatter.command(suggestion.suggested_policy.command_hint)}`);
+}
+
+function routeCandidateStatus(candidate) {
+  return [
+    candidate.role,
+    candidate.selected ? "selected" : null,
+    candidate.guard_allowed ? "allowed" : "denied"
+  ].filter((value) => value !== null).join(", ");
+}
+
+function routeDisclosureText(skillLabel) {
+  return `run the guard automatically, state at the start that ${skillLabel} is being used, and state at completion that it was used. No extra user approval is needed when the guard allows it.`;
+}
+
+function afterUsePromptText(question) {
+  return question.replace(/^Should I /u, "ask whether to ").replace(/\?$/u, ".");
+}
+
+function safeText(value, maxLength = 180) {
+  const compact = String(value).replace(/\s+/g, " ").trim();
+  const withoutTicks = compact.replace(/`/g, "'");
+  return withoutTicks.length > maxLength ? `${withoutTicks.slice(0, maxLength - 3)}...` : withoutTicks;
+}
+
+function code(value, maxLength = 180) {
+  return `\`${safeText(value, maxLength)}\``;
+}
+
+function formatCodeList(values) {
+  return values.length === 0 ? "none" : values.map((value) => code(value)).join(", ");
+}
+
+function formatRawCodeList(values) {
+  return values.length === 0 ? "none" : values.map((value) => `\`${value}\``).join(", ");
+}

package/src/route-selection.mjs

@@ -0,0 +1,220 @@
+import { canUseSkill } from "./control/can-use-guard.mjs";
+import { canonicalRouteToken, phraseKey, tokensFor } from "./route-tokens.mjs";
+
+const HIGH_CONFIDENCE = 4;
+const MEDIUM_CONFIDENCE = 2;
+
+export function selectRoute(workspace, workflow, intent) {
+  const intentTokens = tokensFor(intent);
+  const skillCandidates = skillRouteCandidates(workspace, workflow, intent, intentTokens);
+  const explicitSkill = explicitAllowedSkillRouteCandidate(intent, skillCandidates);
+  const candidates = capabilityRouteCandidates(workspace, workflow)
+    .map((candidate) => scoreCandidate(workspace, candidate, intent, intentTokens))
+    .sort((left, right) => right.score - left.score || left.capability.localeCompare(right.capability));
+  const best = candidates.find((candidate) => candidate.score > 0);
+  const skillBest = skillCandidates.find((candidate) => candidate.score > 0 && candidate.allowed)
+    ?? skillCandidates.find((candidate) => candidate.score > 0);
+
+  return {
+    candidates,
+    skillCandidates,
+    explicitSkill,
+    best,
+    skillBest
+  };
+}
+
+function explicitAllowedSkillRouteCandidate(intent, skillCandidates) {
+  const intentKey = phraseKey(intent);
+  return skillCandidates.find((candidate) => candidate.allowed && exactSkillIdMention(intentKey, candidate.skill_id));
+}
+
+function exactSkillIdMention(intentKey, skillId) {
+  const skillKey = phraseKey(skillId);
+  return skillKey.length > 0 && intentKey.includes(skillKey);
+}
+
+function capabilityRouteCandidates(workspace, workflow) {
+  const workflowSkillIds = new Set(workflowBoundSkillIds(workspace, workflow));
+  return workspace.capabilities.flatMap((capability) => {
+    const requirement = workflow.requiredCapabilities.find((candidate) => candidate.name === capability.name);
+    const requiredSkillIds = uniqueStrings([
+      requirement?.preferred ?? "",
+      ...(requirement?.fallback ?? [])
+    ]);
+    const configuredSkillIds = uniqueStrings([
+      ...requiredSkillIds,
+      capability.canonical,
+      ...capability.alternatives
+    ]);
+    const boundSkillIds = configuredSkillIds.filter((skillId) => workflowSkillIds.has(skillId));
+    if (requirement === undefined && boundSkillIds.length === 0) {
+      return [];
+    }
+    const skillIds = requirement === undefined ? boundSkillIds : uniqueStrings([...requiredSkillIds, ...boundSkillIds]);
+    const skills = skillIds
+      .map((skillId) => workspace.skills.find((skill) => skill.id === skillId))
+      .filter((skill) => skill !== undefined);
+    return [{
+      capability: capability.name,
+      default_policy: capability.defaultPolicy,
+      skill_ids: skillIds,
+      skills,
+      required_by_workflow: requirement !== undefined
+    }];
+  });
+}
+
+function workflowBoundSkillIds(workspace, workflow) {
+  return uniqueStrings([
+    ...workflow.activeSkills,
+    ...workflow.requiredCapabilities.flatMap((capability) => [capability.preferred, ...capability.fallback]),
+    ...workspace.skills.filter((skill) => skill.invocation === "global-auto").map((skill) => skill.id)
+  ]);
+}
+
+function scoreCandidate(workspace, candidate, intent, intentTokens) {
+  const capabilityTokens = tokensFor(candidate.capability);
+  let score = phraseMatchScore(intent, candidate.capability);
+  const matched_tokens = [];
+  const matched_fields = [];
+  if (score > 0) {
+    matched_fields.push("capability name");
+  }
+  for (const token of capabilityTokens) {
+    if (intentTokens.has(token)) {
+      score += 2;
+      matched_tokens.push(token);
+      matched_fields.push("capability name");
+    }
+  }
+  const metadataMatch = scoreMetadataTerms(
+    candidate.skills.flatMap((skill) => skillMetadataTerms(workspace, skill.id, 1)),
+    intentTokens
+  );
+  score += metadataMatch.score;
+  matched_tokens.push(...metadataMatch.matchedTokens);
+  matched_fields.push(...metadataMatch.matchedFields);
+  return {
+    capability: candidate.capability,
+    confidence: confidenceFor(score),
+    score,
+    matched_tokens: uniqueStrings(matched_tokens).sort(),
+    matched_fields: uniqueStrings(matched_fields),
+    recommended_skill: candidate.skill_ids[0] ?? null,
+    fallback_skills: candidate.skill_ids.slice(1),
+    skill_ids: candidate.skill_ids,
+    required_by_workflow: candidate.required_by_workflow
+  };
+}
+
+function skillRouteCandidates(workspace, workflow, intent, intentTokens) {
+  return possibleWorkflowSkills(workspace, workflow)
+    .map((skill) => scoreSkillCandidate(workspace, skill, intent, intentTokens))
+    .sort((left, right) => right.score - left.score || left.skill_id.localeCompare(right.skill_id));
+}
+
+function scoreSkillCandidate(workspace, possibleSkill, intent, intentTokens) {
+  let score = phraseMatchScore(intent, possibleSkill.id);
+  const matched_fields = score > 0 ? ["skill id"] : [];
+  const metadataMatch = scoreMetadataTerms(skillMetadataTerms(workspace, possibleSkill.id, 2), intentTokens);
+  score += metadataMatch.score;
+  matched_fields.push(...metadataMatch.matchedFields);
+  const matched_tokens = metadataMatch.matchedTokens;
+  return {
+    skill_id: possibleSkill.id,
+    category: possibleSkill.category,
+    allowed: possibleSkill.allowed,
+    confidence: confidenceFor(score),
+    score,
+    matched_tokens: uniqueStrings(matched_tokens).sort(),
+    matched_fields: uniqueStrings(matched_fields)
+  };
+}
+
+function scoreMetadataTerms(terms, intentTokens) {
+  let score = 0;
+  const matchedTokens = [];
+  const matchedFields = [];
+  const seenTokens = new Set();
+  for (const term of terms) {
+    for (const token of tokensFor(term.value)) {
+      if (!intentTokens.has(token)) {
+        continue;
+      }
+      matchedFields.push(term.label);
+      const matchedToken = canonicalRouteToken(token);
+      if (seenTokens.has(matchedToken)) {
+        continue;
+      }
+      seenTokens.add(matchedToken);
+      score += term.weight;
+      matchedTokens.push(matchedToken);
+    }
+  }
+  return {
+    score,
+    matchedTokens,
+    matchedFields: uniqueStrings(matchedFields)
+  };
+}
+
+function skillMetadataTerms(workspace, skillId, weight) {
+  const skill = workspace.skills.find((candidate) => candidate.id === skillId);
+  const installed = installedSkillFor(workspace, skillId);
+  return [
+    { label: "skill id", value: skill?.id ?? skillId, weight },
+    { label: "skill path", value: skill?.path ?? installed?.path ?? "", weight },
+    { label: "category", value: skill?.category ?? "", weight },
+    { label: "SKILL.md name", value: installed?.name ?? "", weight },
+    { label: "SKILL.md description", value: installed?.description ?? "", weight }
+  ];
+}
+
+function installedSkillFor(workspace, skillId) {
+  const skill = workspace.skills.find((candidate) => candidate.id === skillId);
+  return workspace.installedSkills.find((installed) => installed.id === skillId || installed.path === skill?.path);
+}
+
+function phraseMatchScore(intent, capability) {
+  const normalizedIntent = phraseKey(intent);
+  const normalizedCapability = phraseKey(capability);
+  if (normalizedIntent.length === 0 || normalizedCapability.length === 0) {
+    return 0;
+  }
+  return normalizedIntent.includes(normalizedCapability) || normalizedCapability.includes(normalizedIntent) ? 4 : 0;
+}
+
+export function possibleWorkflowSkills(workspace, workflow) {
+  const ids = workflowBoundSkillIds(workspace, workflow);
+  return ids.map((skillId) => {
+    const skill = workspace.skills.find((candidate) => candidate.id === skillId);
+    const guard = canUseSkill(workspace, skillId, workflow.name);
+    return {
+      id: skillId,
+      status: skill?.status ?? null,
+      invocation: skill?.invocation ?? null,
+      category: skill?.category ?? null,
+      roles: guard.roles,
+      capability_roles: guard.capabilityRoles,
+      allowed: guard.allowed
+    };
+  });
+}
+
+export function confidenceFor(score) {
+  if (score >= HIGH_CONFIDENCE) {
+    return "high";
+  }
+  if (score >= MEDIUM_CONFIDENCE) {
+    return "medium";
+  }
+  if (score > 0) {
+    return "low";
+  }
+  return "none";
+}
+
+function uniqueStrings(values) {
+  return [...new Set(values.filter((value) => typeof value === "string" && value.length > 0))];
+}

package/src/route-tokens.mjs

@@ -0,0 +1,68 @@
+const ROUTE_STOP_WORDS = new Set([
+  "a",
+  "an",
+  "and",
+  "are",
+  "as",
+  "at",
+  "be",
+  "been",
+  "before",
+  "being",
+  "by",
+  "for",
+  "from",
+  "in",
+  "is",
+  "it",
+  "of",
+  "on",
+  "or",
+  "that",
+  "the",
+  "these",
+  "this",
+  "those",
+  "to",
+  "was",
+  "were",
+  "with",
+  "without",
+  "you",
+  "your"
+]);
+
+export function tokensFor(value) {
+  return new Set(String(value)
+    .toLowerCase()
+    .split(/[^a-z0-9]+/u)
+    .flatMap(tokenForms)
+    .filter(isRouteToken));
+}
+
+function tokenForms(token) {
+  const singular = singularRouteToken(token);
+  return singular === token ? [token] : [token, singular];
+}
+
+export function canonicalRouteToken(token) {
+  return singularRouteToken(token);
+}
+
+function singularRouteToken(token) {
+  if (token.length > 4 && token.endsWith("ies")) {
+    return `${token.slice(0, -3)}y`;
+  }
+  if (token.length > 3 && token.endsWith("s") && !/(?:ss|us|is)$/u.test(token)) {
+    return token.slice(0, -1);
+  }
+  return token;
+}
+
+function isRouteToken(token) {
+  return token.length > 1 && !ROUTE_STOP_WORDS.has(token);
+}
+
+export function phraseKey(value) {
+  return [...tokensFor(value)].join(" ");
+}