agent-skillboard 0.2.15 → 0.2.17

package/src/agent-integration-files.mjs

@@ -0,0 +1,202 @@
+import { lstat, mkdir, readFile, rm, rmdir, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { AGENT_INTEGRATION_END, AGENT_INTEGRATION_START, agentIntegrationSkill } from "./agent-integration-content.mjs";
+import { applyOwnership, isInside } from "./agent-integration-home.mjs";
+
+export async function installAgentIntegration(targets, ownership = null) {
+  const created = [];
+  const updated = [];
+  const unchanged = [];
+  const preserved = [];
+  const content = agentIntegrationSkill();
+  for (const target of targets) {
+    if (!await isSafeManagedSkillTarget(target)) {
+      preserved.push(`${target.agent}:${target.skillPath}`);
+      continue;
+    }
+    const existing = await readFile(target.skillPath, "utf8").catch((error) => {
+      if (error?.code === "ENOENT") {
+        return null;
+      }
+      throw error;
+    });
+    if (existing === content) {
+      await applyOwnership(target.skillPath, ownership);
+      unchanged.push(`${target.agent}:${target.skillPath}`);
+      continue;
+    }
+    if (existing !== null && !existing.includes(AGENT_INTEGRATION_START)) {
+      preserved.push(`${target.agent}:${target.skillPath}`);
+      continue;
+    }
+    await mkdir(dirname(target.skillPath), { recursive: true });
+    await writeFile(target.skillPath, content, "utf8");
+    await applyOwnership(target.skillPath, ownership);
+    (existing === null ? created : updated).push(`${target.agent}:${target.skillPath}`);
+  }
+  return { created, updated, unchanged, preserved };
+}
+
+export async function uninstallAgentIntegration(targets, dryRun) {
+  const removed = [];
+  const updated = [];
+  const preserved = [];
+  const absent = [];
+  for (const target of targets) {
+    const result = await removeAgentIntegration(target, dryRun);
+    const value = `${target.agent}:${target.skillPath}`;
+    if (result === "removed") {
+      removed.push(value);
+    } else if (result === "updated") {
+      updated.push(value);
+    } else if (result === "preserved") {
+      preserved.push(value);
+    } else {
+      absent.push(value);
+    }
+  }
+  return { removed, updated, preserved, absent };
+}
+
+async function removeAgentIntegration(target, dryRun) {
+  if (!await isSafeManagedSkillTarget(target)) {
+    return "preserved";
+  }
+  const path = target.skillPath;
+  const stats = await pathStats(path);
+  if (stats === null) {
+    return "absent";
+  }
+  if (stats.isSymbolicLink() || !stats.isFile()) {
+    return "preserved";
+  }
+  const current = await readFile(path, "utf8");
+  const next = withoutAgentIntegrationBlock(current);
+  if (next === null) {
+    return "preserved";
+  }
+  if (shouldRemoveAgentIntegrationFile(next)) {
+    if (!dryRun) {
+      await rm(path);
+      await removeEmptyManagedSkillDir(dirname(path));
+    }
+    return "removed";
+  }
+  if (!dryRun) {
+    await writeFile(path, next, "utf8");
+  }
+  return "updated";
+}
+
+async function isSafeManagedSkillTarget(target) {
+  const root = resolve(target.root);
+  const skillPath = resolve(target.skillPath);
+  const skillDir = dirname(skillPath);
+  if (!isInside(skillDir, root) || !isInside(skillPath, root)) {
+    return false;
+  }
+  const boundary = managedBoundary(target, root);
+  if (await hasUnsafeManagedDirectoryComponent(boundary, skillDir)) {
+    return false;
+  }
+  const skillStats = await pathStats(skillPath);
+  return skillStats === null || !skillStats.isSymbolicLink();
+}
+
+function managedBoundary(target, root) {
+  const home = target.home === undefined ? null : resolve(target.home);
+  if (home === null) {
+    return root;
+  }
+  return isAtOrInside(root, home) ? home : root;
+}
+
+async function hasUnsafeManagedDirectoryComponent(root, skillDir) {
+  for (const component of managedDirectoryComponents(root, skillDir)) {
+    const stats = await pathStats(component);
+    if (stats !== null && (stats.isSymbolicLink() || !stats.isDirectory())) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function managedDirectoryComponents(root, skillDir) {
+  const fromRoot = [];
+  let current = skillDir;
+  while (isAtOrInside(current, root)) {
+    fromRoot.push(current);
+    const parent = dirname(current);
+    if (parent === current) {
+      break;
+    }
+    current = parent;
+  }
+
+  return uniquePaths(fromRoot.reverse());
+}
+
+function isAtOrInside(path, parent) {
+  return path === parent || isInside(path, parent);
+}
+
+function uniquePaths(paths) {
+  const seen = new Set();
+  const unique = [];
+  for (const path of paths) {
+    if (!seen.has(path)) {
+      seen.add(path);
+      unique.push(path);
+    }
+  }
+  return unique;
+}
+
+function withoutAgentIntegrationBlock(text) {
+  const start = text.indexOf(AGENT_INTEGRATION_START);
+  if (start === -1) {
+    return null;
+  }
+  const end = text.indexOf(AGENT_INTEGRATION_END, start);
+  if (end === -1) {
+    return null;
+  }
+  const afterBlock = end + AGENT_INTEGRATION_END.length;
+  let before = text.slice(0, start);
+  const after = text.slice(afterBlock).replace(/^\r?\n/u, "");
+  if (before.endsWith("\r\n\r\n")) {
+    before = before.slice(0, -2);
+  } else if (before.endsWith("\n\n")) {
+    before = before.slice(0, -1);
+  }
+  return `${before}${after}`;
+}
+
+function shouldRemoveAgentIntegrationFile(text) {
+  const trimmed = text.trim();
+  if (trimmed.length === 0) {
+    return true;
+  }
+  return /^---\s*\r?\nname:\s*skillboard\s*\r?\ndescription:[\s\S]*?\r?\n---\s*$/u.test(trimmed);
+}
+
+async function removeEmptyManagedSkillDir(path) {
+  try {
+    await rmdir(path);
+  } catch (error) {
+    if (error?.code !== "ENOENT" && error?.code !== "ENOTEMPTY" && error?.code !== "EEXIST") {
+      throw error;
+    }
+  }
+}
+
+async function pathStats(path) {
+  try {
+    return await lstat(path);
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+}

package/src/agent-integration-home.mjs

@@ -0,0 +1,185 @@
+import { execFile } from "node:child_process";
+import { access, chown, lstat, readFile } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+const GETENT_PATHS = ["/usr/bin/getent", "/bin/getent"];
+
+export async function resolveSetupHome(env, runtime) {
+  const explicit = nonEmpty(env.SKILLBOARD_SETUP_HOME);
+  if (explicit !== null) {
+    return explicit;
+  }
+  if (shouldUseSudoUserHome(env)) {
+      const sudoHome = nonEmpty(env.SUDO_HOME)
+      ?? await passwdHome(env.SUDO_USER, runtime.passwdPath ?? "/etc/passwd")
+      ?? await getentHome(env.SUDO_USER, runtime)
+      ?? await conventionalUserHome(env.SUDO_USER);
+    if (sudoHome !== null) {
+      return sudoHome;
+    }
+  }
+  return env.HOME ?? env.USERPROFILE;
+}
+
+export function setupOwnership(env, runtime, home) {
+  if (process.platform === "win32" || !shouldUseSudoUserHome(env)) {
+    return null;
+  }
+  const uid = parseNonNegativeInteger(env.SUDO_UID);
+  const gid = parseNonNegativeInteger(env.SUDO_GID);
+  if (uid === null || gid === null) {
+    return null;
+  }
+  const chownFunction = runtime.chown ?? chown;
+  if (runtime.chown === undefined && !canApplyProcessOwnership(uid, gid)) {
+    return null;
+  }
+  return {
+    uid,
+    gid,
+    home: resolve(home),
+    chown: chownFunction
+  };
+}
+
+export async function applyOwnership(path, ownership) {
+  if (ownership === null) {
+    return;
+  }
+  for (const ownedPath of await ownershipPaths(path, ownership.home)) {
+    await ownership.chown(ownedPath, ownership.uid, ownership.gid);
+  }
+}
+
+function canApplyProcessOwnership(uid, gid) {
+  if (typeof process.getuid !== "function") {
+    return false;
+  }
+  if (process.getuid() === 0) {
+    return true;
+  }
+  if (typeof process.getgid !== "function") {
+    return process.getuid() === uid;
+  }
+  return process.getuid() === uid && process.getgid() === gid;
+}
+
+function parseNonNegativeInteger(value) {
+  if (value === undefined || !/^\d+$/.test(value)) {
+    return null;
+  }
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) ? parsed : null;
+}
+
+function shouldUseSudoUserHome(env) {
+  const sudoUser = nonEmpty(env.SUDO_USER);
+  return process.platform !== "win32"
+    && sudoUser !== null
+    && sudoUser !== "root"
+    && (
+      env.SUDO_UID !== undefined
+      || env.SUDO_GID !== undefined
+      || env.USER === "root"
+      || env.LOGNAME === "root"
+      || env.HOME === "/root"
+    );
+}
+
+async function passwdHome(user, passwdPath) {
+  const text = await readFile(passwdPath, "utf8").catch(() => "");
+  for (const line of text.split("\n")) {
+    if (line.startsWith(`${user}:`)) {
+      return nonEmpty(line.split(":")[5]);
+    }
+  }
+  return null;
+}
+
+async function getentHome(user, runtime) {
+  const candidates = runtime.getentPath === undefined ? GETENT_PATHS : [runtime.getentPath];
+  for (const candidate of candidates) {
+    try {
+      const { stdout } = await execFileAsync(candidate, ["passwd", user], {
+        env: { PATH: "/usr/sbin:/usr/bin:/sbin:/bin" },
+        timeout: 1000
+      });
+      const home = nonEmpty(stdout.trim().split(":")[5]);
+      if (home !== null) {
+        return home;
+      }
+    } catch {
+      // Try the next trusted absolute path; fall back to conventional home paths below.
+    }
+  }
+  return null;
+}
+
+async function conventionalUserHome(user) {
+  const candidates = process.platform === "darwin"
+    ? [`/Users/${user}`]
+    : [`/home/${user}`];
+  for (const candidate of candidates) {
+    if (await exists(candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+async function exists(path) {
+  return access(path).then(() => true, () => false);
+}
+
+function nonEmpty(value) {
+  return value === undefined || value.trim() === "" ? null : value;
+}
+
+async function ownershipPaths(path, home) {
+  const resolvedHome = resolve(home);
+  const resolvedPath = resolve(path);
+  if (!isInside(resolvedPath, resolvedHome)) {
+    return [];
+  }
+  const homeStats = await pathStats(resolvedHome);
+  if (homeStats === null || homeStats.isSymbolicLink()) {
+    return [];
+  }
+  const directories = [];
+  let current = dirname(resolvedPath);
+  while (current !== resolvedHome && isInside(current, resolvedHome)) {
+    directories.push(current);
+    const parent = dirname(current);
+    if (parent === current) {
+      break;
+    }
+    current = parent;
+  }
+  const safePaths = [];
+  for (const candidate of [...directories.reverse(), resolvedPath]) {
+    const stats = await pathStats(candidate);
+    if (stats === null || stats.isSymbolicLink()) {
+      break;
+    }
+    safePaths.push(candidate);
+  }
+  return safePaths;
+}
+
+async function pathStats(path) {
+  try {
+    return await lstat(path);
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+}
+
+export function isInside(path, parent) {
+  const relativePath = relative(parent, path);
+  return relativePath !== "" && !relativePath.startsWith("..") && !isAbsolute(relativePath);
+}

package/src/agent-skill-roots.mjs

@@ -30,6 +30,7 @@ export async function setupAgentSkillTargets(agent, home = homedir(), env = proc
   const roots = await detectedAgentSkillRoots(agent, home, env, { includeFallback: options.includeFallback === true });
   return roots.map((root) => ({
     agent,
+    home: resolve(home),
     skillPath: join(root.skillRoot, "skillboard", "SKILL.md"),
     root: root.skillRoot,
     source: root.source

package/src/brief-renderer.mjs

@@ -1,4 +1,6 @@
 // SIZE_OK: src/brief-renderer.mjs is pre-existing renderer debt; this change only adds narrow AI/automation copy until a broader renderer split.
+import { renderRouteSectionLines } from "./route-renderer.mjs";
+
 const SKILL_SECTIONS = [
   ["Needs your decision", "needs_review"],
   ["Blocked for safety", "blocked"]
@@ -82,63 +84,13 @@ function emitIntentRoute(lines, brief) {
     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(...renderRouteSectionLines(route, {
+    format: "brief",
+    nextStep: brief.assistant_guidance?.recommended_next_step
+  }));
   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) {
@@ -271,6 +223,7 @@ function emitDecisionSection(lines, brief, options) {
     lines.push("- none", "");
     return;
   }
+  emitDeferredDecisionLead(lines, brief);
   if (skillEntries.length > 0) {
     emitSkillEntries(lines, skillEntries, {
       ...options,
@@ -287,6 +240,13 @@ function emitDecisionSection(lines, brief, options) {
   lines.push("");
 }
 
+function emitDeferredDecisionLead(lines, brief) {
+  if (!hasUsableRoutedSkill(brief)) {
+    return;
+  }
+  lines.push("A routed skill is already usable for this request; handle these decisions after the task unless a policy-changing action is needed now.", "");
+}
+
 function reviewEntriesForDecisionSection(brief, skillEntries) {
   if (skillEntries.length === 0) {
     return brief.review_queue ?? [];
@@ -384,7 +344,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.", "");
+  lines.push(suggestedActionsLead(brief), "");
   if (actions.length === 0) {
     lines.push("- none", "");
     return;
@@ -401,7 +361,7 @@ function emitActions(lines, brief, options) {
   if (!options.verbose) {
     const hiddenSecondary = other.length + cleanup.length;
     if (hiddenSecondary > 0) {
-      if (lines.at(-1) === "") {
+      if (lines[lines.length - 1] === "") {
         lines.pop();
       }
       lines.push(`- ${hiddenSecondary} safety and cleanup actions hidden. Run ${code(`skillboard brief --verbose${workflowOption(brief)}`)}.`);
@@ -419,9 +379,15 @@ function emitActions(lines, brief, options) {
   }
 }
 
+function suggestedActionsLead(brief) {
+  return hasUsableRoutedSkill(brief)
+    ? "After the routed task, use current action ids from this brief for policy changes; ask for one user confirmation before applying one action."
+    : "AI/automation operations should use current action ids from this brief, then ask for user confirmation before applying one action.";
+}
+
 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.", "");
+  lines.push(nextActionLead(brief), "");
   const action = nextSafeAction(brief);
   if (action === null) {
     lines.push("- none", "");
@@ -431,6 +397,19 @@ function emitNextAction(lines, brief, options) {
   lines.push("");
 }
 
+function nextActionLead(brief) {
+  return hasUsableRoutedSkill(brief)
+    ? "A routed skill is already usable for this request; handle this policy action after the task unless a policy-changing action is needed now."
+    : "AI/automation should present this as the next confirmable operation, not as an automatic mutation.";
+}
+
+function hasUsableRoutedSkill(brief) {
+  const route = brief.assistant_guidance?.route;
+  return route?.recommended_skill !== null
+    && route?.recommended_skill !== undefined
+    && route.guard_allowed === true;
+}
+
 function nextSafeAction(brief) {
   const actions = actionsForTextBrief(brief);
   if (actions.length === 0) {