@agentprojectcontext/apx 1.34.0 → 1.36.0

package/src/interfaces/cli/commands/skills.js

@@ -15,6 +15,20 @@ import {
   listEngineSkills,
   listLegacyPruneSlugs,
 } from "#core/apc/scaffold.js";
+import {
+  ensureIndex,
+  planIndex,
+  readIndex,
+  clearIndex,
+  indexPath,
+} from "#core/agent/skills/index-store.js";
+import { isInspectorEnabled } from "#core/agent/skills/inspector.js";
+import {
+  inspectPromptForSkills,
+  summarizeTrace,
+  INSPECTOR_DEFAULTS,
+} from "#core/agent/skills/inspector.js";
+import { readConfig, writeConfig } from "#core/config/index.js";
 
 // ---------------------------------------------------------------------------
 // Prompt helper
@@ -30,6 +44,31 @@ function ask(question) {
   });
 }
 
+// When the Skill Inspector is on, the catalog it scores against must stay in
+// sync with what's installed. Called after add/sync so a freshly available
+// skill is searchable immediately, without a separate `apx skills index`.
+// No-op (silent) when the inspector is disabled — nothing reads the index then.
+async function reindexInspectorIfEnabled() {
+  let config;
+  try {
+    config = readConfig();
+  } catch {
+    return;
+  }
+  if (!isInspectorEnabled(config)) return;
+  try {
+    const plan = planIndex({});
+    const work = plan.missing.length + plan.stale.length + plan.gone.length;
+    if (work === 0) return;
+    process.stdout.write(`\n  Skill Inspector on — reindexing ${work} changed skill(s)… `);
+    const out = await ensureIndex({ embedOpts: { globalConfig: config } });
+    const c = out.changed;
+    console.log(`done (${out.embedder}: +${c.added.length} ~${c.refreshed.length} -${c.removed.length}).`);
+  } catch (e) {
+    console.log(`\n  (skill index refresh failed: ${e.message})`);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // apx skills add [<target>...] [--global] [--project]
 // ---------------------------------------------------------------------------
@@ -65,6 +104,7 @@ export async function cmdSkillsAdd(args) {
     }
     console.log("\n  Loaded by: Claude Code, Cursor, Codex (OpenAI), Antigravity, and skills.sh-compatible tools.");
     console.log("  Activates automatically when working in a project with AGENTS.md or .apc/");
+    await reindexInspectorIfEnabled();
     return;
   }
 
@@ -93,6 +133,7 @@ export async function cmdSkillsAdd(args) {
     console.log("");
     for (const t of notes) console.log(`  note: ${t.note}`);
   }
+  await reindexInspectorIfEnabled();
 }
 
 // ---------------------------------------------------------------------------
@@ -154,6 +195,7 @@ export async function cmdSkillsSync(args) {
       }
     }
   }
+  await reindexInspectorIfEnabled();
 }
 
 // ---------------------------------------------------------------------------
@@ -261,3 +303,215 @@ export async function cmdSkillsStatus() {
   console.log("\n  Tip: run `apx skills add` for an interactive install.");
   console.log("  Claude Desktop has no project-file support (use apx-mcp instead).");
 }
+
+// ---------------------------------------------------------------------------
+// apx skills index [--reset] [--force]
+//
+// Build the persistent vector index that powers the skill Inspector. Runs the
+// configured embedding provider (defaults to local: ollama → tf fallback) over
+// every skill's condensed description and writes ~/.apx/skills/.index.json.
+// ---------------------------------------------------------------------------
+
+function renderBar(done, total, width = 24) {
+  if (!Number.isFinite(total) || total <= 0) return "";
+  const ratio = Math.max(0, Math.min(1, done / total));
+  const filled = Math.round(ratio * width);
+  return "[" + "█".repeat(filled) + " ".repeat(width - filled) + "]";
+}
+
+export async function cmdSkillsIndex(args = {}) {
+  const reset = !!args?.flags?.reset;
+  const force = !!args?.flags?.force;
+  if (reset) clearIndex();
+
+  const config = readConfig();
+  const root = findApfRoot();
+  const projectPath = root || undefined;
+
+  const plan = planIndex({ projectPath });
+  if (plan.total === 0) {
+    console.log("(no skills available — install some first with `apx skills sync` or drop a SKILL.md in ~/.apx/skills/<slug>/)");
+    return;
+  }
+
+  const headline = force
+    ? `Rebuilding index for ${plan.total} skills (force).`
+    : `Indexing ${plan.total} skills (${plan.existing.length} cached · ${plan.missing.length} new · ${plan.stale.length} stale · ${plan.gone.length} gone).`;
+  console.log(headline);
+
+  const t0 = Date.now();
+  let lastLine = "";
+  const out = await ensureIndex({
+    projectPath,
+    embedOpts: { globalConfig: config },
+    force,
+    onProgress: ({ done, total, slug, action }) => {
+      const bar = renderBar(done, total);
+      const tag = action.padEnd(9);
+      const line = `\r${bar} ${done}/${total}  ${tag}  ${slug}`.padEnd(lastLine.length, " ");
+      process.stdout.write(line);
+      lastLine = line;
+    },
+  });
+
+  const elapsedMs = Date.now() - t0;
+  process.stdout.write("\r" + " ".repeat(lastLine.length) + "\r");
+
+  const c = out.changed;
+  console.log(
+    `Done in ${(elapsedMs / 1000).toFixed(1)}s using ${out.embedder} (dim ${out.dim}).\n` +
+    `  added:     ${c.added.length}\n` +
+    `  refreshed: ${c.refreshed.length}\n` +
+    `  removed:   ${c.removed.length}\n` +
+    `  kept:      ${c.kept.length}\n` +
+    `  index:     ${indexPath()}`
+  );
+  if (c.added.length || c.refreshed.length) {
+    const sample = [...c.added, ...c.refreshed].slice(0, 6).join(", ");
+    if (sample) console.log(`  changes:   ${sample}${(c.added.length + c.refreshed.length) > 6 ? ", …" : ""}`);
+  }
+  if (out.embedder === "tf") {
+    console.log("  note:      using offline TF fallback (no embedding provider reachable). Configure one in config.memory.embeddings for better recall.");
+  }
+}
+
+// ---------------------------------------------------------------------------
+// apx skills inspect <prompt>
+//
+// Show what the Inspector would inject for a given user prompt. Doesn't touch
+// the model — pure middleware debug. Useful to tune thresholds and to see why
+// a skill did or didn't fire.
+// ---------------------------------------------------------------------------
+
+export async function cmdSkillsInspect(args) {
+  const promptParts = args?._ || [];
+  const prompt = promptParts.join(" ").trim();
+  if (!prompt) {
+    console.error("usage: apx skills inspect \"<prompt text>\"");
+    process.exitCode = 2;
+    return;
+  }
+
+  const config = readConfig();
+  const root = findApfRoot();
+  const projectPath = root || undefined;
+
+  // Force the inspector on for this command even if config has it off — the
+  // operator is explicitly asking "what WOULD the inspector do?".
+  const probedConfig = structuredClone(config);
+  probedConfig.skills = probedConfig.skills || {};
+  probedConfig.skills.inspector = {
+    ...INSPECTOR_DEFAULTS,
+    ...(probedConfig.skills.inspector || {}),
+    enabled: true,
+  };
+
+  const out = await inspectPromptForSkills({
+    prompt,
+    projectPath,
+    globalConfig: probedConfig,
+  });
+
+  console.log(`prompt:    ${prompt}`);
+  console.log(`embedder:  ${out.trace.embedder || "(none)"}`);
+  console.log(`decision:  ${summarizeTrace(out.trace)}`);
+  if (out.trace.scored?.length) {
+    console.log("scores:");
+    for (const s of out.trace.scored) console.log(`  ${s.sim.toFixed(3)}  ${s.slug}`);
+  }
+  if (out.contextNote) {
+    console.log("");
+    console.log("--- contextNote that would be injected ---");
+    console.log(out.contextNote);
+    console.log("--- end ---");
+  }
+}
+
+// ---------------------------------------------------------------------------
+// apx skills inspector [enable|disable|status|set <key> <value>]
+//
+// Manage config.skills.inspector. All keys live under that namespace; this
+// command is a thin shortcut so you don't have to remember the path.
+// ---------------------------------------------------------------------------
+
+const KNOWN_INSPECTOR_KEYS = Object.keys(INSPECTOR_DEFAULTS);
+
+function ensureInspectorBlock(cfg) {
+  cfg.skills = cfg.skills || {};
+  cfg.skills.inspector = { ...INSPECTOR_DEFAULTS, ...(cfg.skills.inspector || {}) };
+  return cfg;
+}
+
+function printInspectorStatus(cfg) {
+  const insp = cfg.skills?.inspector || {};
+  const merged = { ...INSPECTOR_DEFAULTS, ...insp };
+  console.log(`Skill Inspector: ${merged.enabled ? "ENABLED" : "disabled"}`);
+  for (const k of KNOWN_INSPECTOR_KEYS) {
+    if (k === "enabled") continue;
+    console.log(`  ${k.padEnd(16)} ${merged[k]}`);
+  }
+  const idx = readIndex();
+  const count = Object.keys(idx.items || {}).length;
+  console.log("");
+  console.log(`Index: ${count} skills (${idx.embedder || "—"}, dim ${idx.dim || "—"})`);
+  console.log(`File:  ${indexPath()}`);
+}
+
+export async function cmdSkillsInspector(args) {
+  const sub = (args?._ || [])[0];
+  const cfg = readConfig();
+
+  if (!sub || sub === "status") {
+    printInspectorStatus(cfg);
+    return;
+  }
+  if (sub === "enable" || sub === "on") {
+    ensureInspectorBlock(cfg).skills.inspector.enabled = true;
+    writeConfig(cfg);
+    console.log("Skill Inspector ENABLED. The catalog-wide hint block will be suppressed; per-turn RAG decides what skills go into context.");
+    console.log("Tip: run `apx skills index` once so the inspector has cached vectors to score against.");
+    return;
+  }
+  if (sub === "disable" || sub === "off") {
+    ensureInspectorBlock(cfg).skills.inspector.enabled = false;
+    writeConfig(cfg);
+    console.log("Skill Inspector disabled. Falling back to the legacy slug hint + passive RAG nudge.");
+    return;
+  }
+  if (sub === "set") {
+    const key = args._[1];
+    const value = args._[2];
+    if (!key || value === undefined) {
+      console.error("usage: apx skills inspector set <key> <value>");
+      console.error(`keys: ${KNOWN_INSPECTOR_KEYS.join(", ")}`);
+      process.exitCode = 2;
+      return;
+    }
+    if (!KNOWN_INSPECTOR_KEYS.includes(key)) {
+      console.error(`unknown key "${key}". Known: ${KNOWN_INSPECTOR_KEYS.join(", ")}`);
+      process.exitCode = 2;
+      return;
+    }
+    ensureInspectorBlock(cfg);
+    const def = INSPECTOR_DEFAULTS[key];
+    let coerced = value;
+    if (typeof def === "boolean") coerced = value === "true" || value === "1" || value === "on";
+    else if (typeof def === "number") {
+      const n = Number(value);
+      if (!Number.isFinite(n)) {
+        console.error(`value for "${key}" must be a number; got "${value}"`);
+        process.exitCode = 2;
+        return;
+      }
+      coerced = n;
+    }
+    cfg.skills.inspector[key] = coerced;
+    writeConfig(cfg);
+    console.log(`skills.inspector.${key} = ${coerced}`);
+    return;
+  }
+
+  console.error(`unknown inspector subcommand: ${sub}`);
+  console.error("usage: apx skills inspector [status|enable|disable|set <key> <value>]");
+  process.exitCode = 2;
+}

package/src/interfaces/cli/index.js

@@ -100,7 +100,7 @@ import {
 import { cmdPluginsList, cmdPluginStatus } from "./commands/plugins.js";
 import { cmdDesktopStart, cmdDesktopStop, cmdDesktopStatus, cmdDesktopInstall, cmdDesktopUninstall } from "./commands/desktop.js";
 import { cmdVoiceSay, cmdVoiceListen, cmdVoiceProviders } from "./commands/voice.js";
-import { cmdSkillsAdd, cmdSkillsList, cmdSkillsStatus, cmdSkillsSync } from "./commands/skills.js";
+import { cmdSkillsAdd, cmdSkillsList, cmdSkillsStatus, cmdSkillsSync, cmdSkillsIndex, cmdSkillsInspect, cmdSkillsInspector } from "./commands/skills.js";
 import { cmdIdentity } from "./commands/identity.js";
 import { cmdCommandList, cmdCommandShow } from "./commands/command.js";
 import { cmdUpdate } from "./commands/update.js";
@@ -110,6 +110,7 @@ import { cmdModel } from "./commands/model.js";
 import { cmdPair, cmdPairWeb, cmdPairList, cmdPairRevoke } from "./commands/pair.js";
 import { checkForUpdate } from "#core/update-check.js";
 import { mascot } from "#core/mascot.js";
+import { apxHeader, apxBanner } from "./branding.js";
 import {
   cmdRoutineList,
   cmdRoutineGet,
@@ -1350,12 +1351,23 @@ const HELP_TOPICS = new Map(Object.entries({
   skills: topic({
     title: "apx skills",
     summary: "Install and inspect APX skill files for IDEs and agent tools.",
-    usage: ["apx skills [add] [targets] [--global]", "apx skills sync", "apx skills list", "apx skills status"],
+    usage: [
+      "apx skills [add] [targets] [--global]",
+      "apx skills sync",
+      "apx skills list",
+      "apx skills status",
+      "apx skills index [--reset] [--force]",
+      "apx skills inspect \"<prompt>\"",
+      "apx skills inspector [status|enable|disable|set <key> <value>]",
+    ],
     commands: [
       ["add [targets]", "Install APX skills into selected targets."],
       ["sync | refresh", "Re-install every bundled skill to every global skill dir (idempotent)."],
       ["list | ls", "List skills installed in this project's .apc/skills/."],
       ["status", "Show which bundled skills are present in each global dir."],
+      ["index", "Build/refresh the local RAG vector index used by the Skill Inspector."],
+      ["inspect", "Show which skills the Inspector would surface for a given prompt (debug)."],
+      ["inspector", "Toggle and tune the Skill Inspector (per-turn skill RAG middleware)."],
     ],
     examples: [
       "apx skills add claude-code cursor",
@@ -1403,6 +1415,40 @@ const HELP_TOPICS = new Map(Object.entries({
     usage: ["apx skills status"],
     examples: ["apx skills status"],
   }),
+  "skills index": topic({
+    title: "apx skills index",
+    summary:
+      "Build or refresh the local vector index that powers the Skill Inspector. Embeds each skill's condensed description with the configured embeddings provider (defaults to local: ollama → tf fallback). Idempotent: skills with unchanged file+description are kept. Use --force to re-embed everything; --reset to also delete the on-disk index first.",
+    usage: ["apx skills index [--reset] [--force]"],
+    options: [
+      ["--force", "Re-embed every skill, ignoring cached vectors."],
+      ["--reset", "Delete the index file before rebuilding."],
+    ],
+    examples: ["apx skills index", "apx skills index --force", "apx skills index --reset"],
+  }),
+  "skills inspect": topic({
+    title: "apx skills inspect",
+    summary:
+      "Dry-run the Skill Inspector against a prompt. Shows top similarity scores, which skill (if any) would be loaded inline, which would be hinted, and the actual contextNote that would be injected into the next turn's system prompt. The model is NOT called.",
+    usage: ["apx skills inspect \"<prompt text>\""],
+    examples: [
+      "apx skills inspect \"crear un video promocional\"",
+      "apx skills inspect \"profile the slow endpoint\"",
+    ],
+  }),
+  "skills inspector": topic({
+    title: "apx skills inspector",
+    summary:
+      "Toggle and tune the Skill Inspector (per-turn skill RAG). When ON: the static slug-dump in the system prompt is suppressed and a local RAG picks 0–N skills per turn — loading the body of high-confidence matches, hinting mid-confidence ones, injecting nothing below threshold. When OFF: legacy behaviour (full slug list + passive suggestion). Opt-in test feature.",
+    usage: ["apx skills inspector [status|enable|disable|set <key> <value>]"],
+    examples: [
+      "apx skills inspector enable",
+      "apx skills inspector disable",
+      "apx skills inspector status",
+      "apx skills inspector set load_threshold 0.5",
+      "apx skills inspector set max_loaded 2",
+    ],
+  }),
   plugins: topic({
     title: "apx plugins",
     summary: "Inspect loaded APX daemon plugins.",
@@ -2530,6 +2576,9 @@ async function dispatch(cmd, rest) {
         else if (sub === "list" || sub === "ls") await cmdSkillsList(a);
         else if (sub === "status") await cmdSkillsStatus();
         else if (sub === "sync" || sub === "refresh") await cmdSkillsSync(a);
+        else if (sub === "index") await cmdSkillsIndex(a);
+        else if (sub === "inspect") await cmdSkillsInspect(a);
+        else if (sub === "inspector") await cmdSkillsInspector(a);
         else die(`unknown skills subcommand: ${sub}`);
         break;
       }
@@ -2583,8 +2632,41 @@ async function dispatch(cmd, rest) {
 }
 
 const [topCmd, ...topRest] = argv;
+
+// ── CLI branding ────────────────────────────────────────────────────────────
+// Every command prints an "APX CLI · vX · <command>" mark to stderr (so stdout
+// pipes stay clean). Two exceptions:
+//   - SELF_BRANDED: commands that already render their own logo/mascot/status
+//     block — re-stamping them would double up.
+//   - BANNERED: branding-heavy moments that get the big ASCII wordmark instead
+//     of the compact line.
+// Suppress everything with APX_QUIET=1 / APX_NO_BANNER=1 (see branding.js).
+const SELF_BRANDED = new Set([
+  "status", "setup", "install", "daemon", "update", "upgrade", "help",
+]);
+const BANNERED = new Set(["init"]);
+
+function brandFor(cmd, rest) {
+  if (SELF_BRANDED.has(cmd)) return;
+  // Subtitle = the command path only (cmd + leading subcommand tokens), never
+  // free-form args. Stop at the first token that looks like an argument: a flag,
+  // something with spaces (a quoted prompt), or anything long. So
+  // `skills inspector status` shows fully, but `exec "long prompt…"` shows just
+  // `exec`.
+  const path = [cmd];
+  for (const tok of rest) {
+    if (!tok || tok.startsWith("-") || /\s/.test(tok) || tok.length > 24) break;
+    path.push(tok);
+    if (path.length >= 3) break;
+  }
+  const subtitle = path.join(" ");
+  if (BANNERED.has(cmd)) apxBanner(VERSION, subtitle);
+  else apxHeader(VERSION, subtitle);
+}
+
 (async () => {
   try {
+    brandFor(topCmd, topRest);
     await dispatch(topCmd, topRest);
     checkForUpdate(VERSION);
   } catch (err) {