agent-skillboard 0.1.2 → 0.2.2

package/src/brief-renderer.mjs

@@ -1,6 +1,5 @@
+// SIZE_OK: src/brief-renderer.mjs is pre-existing renderer debt; this change only adds narrow AI/automation copy until a broader renderer split.
 const SKILL_SECTIONS = [
-  ["What your AI can use now", "automatic_allowed"],
-  ["Manual only", "manual_allowed"],
   ["Needs your decision", "needs_review"],
   ["Blocked for safety", "blocked"]
 ];
@@ -20,6 +19,7 @@ const CLEANUP_ACTION_KINDS = new Set([
 ]);
 const COMPACT_SKILL_LIMIT = 5;
 const TOP_CATEGORY_LIMIT = 5;
+const POLICY_DIAGNOSTIC_LIMIT = 3;
 const MAX_ACTIONS_PER_TEXT_SECTION = 5;
 const ACTION_KIND_RANK = new Map([
   ["setup-guidance", 0],
@@ -48,9 +48,16 @@ export function renderSkillBrief(brief, options = {}) {
   if (brief.error !== undefined) {
     lines.push(`Error: ${safeText(brief.error.message)}`, "");
   }
+  emitIntentRoute(lines, brief);
+  emitPolicyHealth(lines, brief);
   emitCategorySummary(lines, brief);
   emitNextAction(lines, brief, { verbose });
+  emitAvailableNowSection(lines, brief, { verbose });
   for (const [title, key] of SKILL_SECTIONS) {
+    if (key === "needs_review") {
+      emitDecisionSection(lines, brief, { verbose });
+      continue;
+    }
     emitSkillSection(lines, title, brief.skills[key], {
       brief,
       groupLabel: compactGroupLabel(key),
@@ -69,6 +76,109 @@ export function renderSkillBrief(brief, options = {}) {
   return `${lines.join("\n")}\n`;
 }
 
+function emitIntentRoute(lines, brief) {
+  const route = brief.assistant_guidance?.route;
+  if (route === undefined) {
+    return;
+  }
+  lines.push("## Suggested skill for this request", "");
+  lines.push(`- Intent: ${safeText(route.intent)}`);
+  lines.push(`- Match source: ${route.match_source}`);
+  lines.push(`- Matched capability: ${route.matched_capability ?? "none"}`);
+  lines.push(`- Matched skill: ${route.matched_skill === null ? "none" : code(route.matched_skill)}`);
+  lines.push(`- Confidence: ${route.confidence}`);
+  lines.push(`- Why: ${safeText(route.recommendation_reason, 320)}`);
+  lines.push(`- Matched terms: ${formatCodeList(route.matched_terms)}`);
+  if (route.recommended_skill === null) {
+    lines.push("- Recommended skill: none");
+    lines.push("- Next step: ask a clarifying question before choosing a skill.");
+  } else {
+    lines.push(`- Recommended skill: ${code(route.recommended_skill)}`);
+    lines.push(`- Fallback skills: ${formatCodeList(route.fallback_skills)}`);
+    if ((route.route_candidates ?? []).length > 0) {
+      lines.push("- Route candidates:");
+      for (const candidate of route.route_candidates) {
+        lines.push(`  - ${code(candidate.skill)} (${routeCandidateStatus(candidate)})`);
+        if (!candidate.guard_allowed && candidate.guard_reasons.length > 0) {
+          lines.push(`    - ${safeText(candidate.guard_reasons[0])}`);
+        }
+      }
+    }
+    lines.push(`- Guard: ${code(route.guard_command, Number.POSITIVE_INFINITY)}`);
+    if (route.usage_disclosure !== null && route.usage_disclosure !== undefined) {
+      lines.push(`- Disclosure: ${routeDisclosureText(code(route.recommended_skill))}`);
+      lines.push(`- Say before use: "${safeText(route.usage_disclosure.start_message)}"`);
+      lines.push(`- Say after completion: "${safeText(route.usage_disclosure.finish_message)}"`);
+    }
+    emitPostUsePolicySuggestion(lines, route.post_use_policy_suggestion);
+  }
+  lines.push("");
+}
+
+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 emitPostUsePolicySuggestion(lines, suggestion) {
+  if (suggestion === null || suggestion === undefined) {
+    return;
+  }
+  lines.push(`- After completion: ${safeText(afterUsePromptText(suggestion.question))}`);
+  lines.push(`- Policy command after confirmation: ${code(suggestion.suggested_policy.command_hint, Number.POSITIVE_INFINITY)}`);
+}
+
+function afterUsePromptText(question) {
+  return question.replace(/^Should I /u, "ask whether to ").replace(/\?$/u, ".");
+}
+
+function emitPolicyHealth(lines, brief) {
+  const policy = brief.health?.policy;
+  if (policy === undefined) {
+    return;
+  }
+  const errors = policy.errors ?? [];
+  const warnings = policy.warnings ?? [];
+  if (errors.length === 0 && warnings.length === 0) {
+    return;
+  }
+  lines.push("## Policy health", "");
+  emitPolicyDiagnostics(lines, "Policy errors", errors);
+  emitPolicyDiagnostics(lines, "Policy warnings", warnings);
+  lines.push(`- check with: ${code(policyCheckCommand(brief), Number.POSITIVE_INFINITY)}`);
+  lines.push("");
+}
+
+function emitPolicyDiagnostics(lines, label, diagnostics) {
+  if (diagnostics.length === 0) {
+    return;
+  }
+  lines.push(`- ${label}: ${diagnostics.length}`);
+  for (const diagnostic of diagnostics.slice(0, POLICY_DIAGNOSTIC_LIMIT)) {
+    lines.push(`  - ${safeText(diagnostic)}`);
+  }
+  const hidden = diagnostics.length - POLICY_DIAGNOSTIC_LIMIT;
+  if (hidden > 0) {
+    lines.push(`  - ${hidden} more hidden. Run ${code("skillboard check")}.`);
+  }
+}
+
+function policyCheckCommand(brief) {
+  const config = brief.health?.config_path;
+  const skills = brief.health?.skills_root;
+  if (config === undefined || skills === undefined) {
+    return "skillboard check";
+  }
+  return `skillboard check --config ${config} --skills ${skills}`;
+}
+
 function briefCounts(brief) {
   const automatic = brief.skills.automatic_allowed.length;
   const manual = brief.skills.manual_allowed.length;
@@ -76,32 +186,133 @@ function briefCounts(brief) {
     automatic,
     manual,
     usable: automatic + manual,
-    needsDecision: brief.skills.needs_review.length,
+    needsDecision: decisionCount(brief),
     blocked: brief.skills.blocked.length
   };
 }
 
+function decisionCount(brief) {
+  const skillDecisionCount = brief.skills.needs_review.length;
+  if (skillDecisionCount > 0) {
+    return skillDecisionCount;
+  }
+  return brief.review_queue?.length ?? 0;
+}
+
+function emitAvailableNowSection(lines, brief, options) {
+  lines.push("## What your AI can use now", "");
+  const entries = [
+    ...brief.skills.automatic_allowed.map((entry) => ({ entry, mode: "automatic" })),
+    ...brief.skills.manual_allowed.map((entry) => ({ entry, mode: "manual-only" }))
+  ];
+  if (entries.length === 0) {
+    lines.push("- none", "");
+    return;
+  }
+  lines.push("Automatic skills can be selected by the AI. On-request skills can be used when the user asks the AI; the AI runs the guard first.");
+  lines.push("When the guard allows use, disclose the selected skill at the start and completion instead of asking again.", "");
+  const visibleEntries = options.verbose ? entries : entries.slice(0, COMPACT_SKILL_LIMIT);
+  for (const item of visibleEntries) {
+    lines.push(formatSkillEntry(item.entry, [availableModeLabel(item.mode)]));
+  }
+  const hiddenEntries = entries.slice(visibleEntries.length);
+  if (hiddenEntries.length > 0) {
+    lines.push(`- ${hiddenEntries.length} more ${availableHiddenLabel(hiddenEntries)} hidden. Run ${code(verboseCommand(brief))} or ${code(listCommand(brief))}.`);
+  }
+  lines.push("");
+}
+
+function availableHiddenLabel(entries) {
+  const modes = new Set(entries.map((entry) => entry.mode));
+  if (modes.size !== 1) {
+    return "available skills";
+  }
+  return modes.has("manual-only") ? "on-request skills" : "automatic skills";
+}
+
+function availableModeLabel(mode) {
+  return mode === "manual-only" ? "on request" : mode;
+}
+
 function emitSkillSection(lines, title, entries, options) {
   lines.push(`## ${title}`, "");
   if (entries.length === 0) {
     lines.push("- none", "");
     return;
   }
+  emitSkillEntries(lines, entries, options);
+  lines.push("");
+}
+
+function emitSkillEntries(lines, entries, options) {
   const visibleEntries = options.verbose ? entries : entries.slice(0, COMPACT_SKILL_LIMIT);
   for (const entry of visibleEntries) {
-    const path = entry.path === undefined ? "" : ` (${safeText(entry.path)})`;
-    const reason = entry.reason === null || entry.reason === undefined
-      ? ""
-      : ` - ${safeText(entry.reason)}`;
-    lines.push(`- ${code(entry.id)}${path}${reason}`);
+    lines.push(formatSkillEntry(entry));
   }
   const hidden = entries.length - visibleEntries.length;
   if (hidden > 0) {
     lines.push(`- ${hidden} more ${options.groupLabel} hidden. Run ${code(verboseCommand(options.brief))} or ${code(listCommand(options.brief))}.`);
   }
+}
+
+function formatSkillEntry(entry, labels = []) {
+  const path = entry.path === undefined ? "" : ` (${safeText(entry.path)})`;
+  const reason = entry.reason === null || entry.reason === undefined ? null : safeText(entry.reason);
+  const details = [...labels, reason].filter((value) => value !== null && value !== "");
+  const suffix = details.length === 0 ? "" : ` - ${details.join("; ")}`;
+  return `- ${code(entry.id)}${path}${suffix}`;
+}
+
+function emitDecisionSection(lines, brief, options) {
+  lines.push("## Needs your decision", "");
+  const skillEntries = brief.skills.needs_review;
+  const reviewEntries = reviewEntriesForDecisionSection(brief, skillEntries);
+  if (skillEntries.length === 0 && reviewEntries.length === 0) {
+    lines.push("- none", "");
+    return;
+  }
+  if (skillEntries.length > 0) {
+    emitSkillEntries(lines, skillEntries, {
+      ...options,
+      brief,
+      groupLabel: "decision items"
+    });
+  }
+  if (reviewEntries.length > 0) {
+    emitReviewQueueEntries(lines, reviewEntries, {
+      ...options,
+      brief
+    });
+  }
   lines.push("");
 }
 
+function reviewEntriesForDecisionSection(brief, skillEntries) {
+  if (skillEntries.length === 0) {
+    return brief.review_queue ?? [];
+  }
+  return [];
+}
+
+function emitReviewQueueEntries(lines, entries, options) {
+  const visibleEntries = options.verbose ? entries : entries.slice(0, COMPACT_SKILL_LIMIT);
+  for (const entry of visibleEntries) {
+    const label = entry.label ?? entry.title ?? entry.id;
+    const action = firstActionId(entry);
+    const actionText = action === null ? "" : ` - action: ${code(action)}`;
+    lines.push(`- ${safeText(label)} - ${safeText(entry.reason)}${actionText}`);
+  }
+  const hidden = entries.length - visibleEntries.length;
+  if (hidden > 0) {
+    lines.push(`- ${hidden} more review decisions hidden. Run ${code(verboseCommand(options.brief))}.`);
+  }
+}
+
+function firstActionId(entry) {
+  const [action] = entry.action_ids ?? [];
+  return typeof action === "string" ? action : null;
+}
+
 function emitCategorySummary(lines, brief) {
   const categories = categoryCounts(brief);
   lines.push("## Top categories", "");
@@ -173,6 +384,7 @@ function workflowOption(brief) {
 function emitActions(lines, brief, options) {
   const actions = actionsForTextBrief(brief);
   lines.push("## Suggested next actions", "");
+  lines.push("AI/automation operations should use current action ids from this brief, then ask for user confirmation before applying one action.", "");
   if (actions.length === 0) {
     lines.push("- none", "");
     return;
@@ -209,6 +421,7 @@ function emitActions(lines, brief, options) {
 
 function emitNextAction(lines, brief, options) {
   lines.push("## Next safe action", "");
+  lines.push("AI/automation should present this as the next confirmable operation, not as an automatic mutation.", "");
   const action = nextSafeAction(brief);
   if (action === null) {
     lines.push("- none", "");
@@ -360,3 +573,7 @@ function safeText(value, maxLength = 180) {
 function code(value, maxLength = 180) {
   return `\`${safeText(value, maxLength)}\``;
 }
+
+function formatCodeList(values) {
+  return values.length === 0 ? "none" : values.map((value) => code(value)).join(", ");
+}