@agentprojectcontext/apx 1.81.0 → 1.89.1

package/src/core/agent/run-turn.js

@@ -0,0 +1,253 @@
+// One turn of a project agent — THE shared turn engine, used by the 1:1 chat
+// route (host/daemon/api/exec.js), the group cascade (agent/group), and anyone
+// else who needs an agent to answer with its real tools.
+//
+// WHY THIS EXISTS (moved here from exec.js so it can be reused without a route
+// importing from another route). This used to be `callEngine` and nothing else:
+// system prompt in, text out, no tools anywhere — which is why an agent asked to
+// browse answered with a fenced {"tool":"browser_navigate",…} instead of
+// browsing. It had nothing to call, so narrating the call was the only move left
+// to it. Now the same loop the routine runner uses runs here too, gated by the
+// same `resolveAgentAllowedTools` — the agent's declared `tools:` field when it
+// has one, the broad default when it does not.
+//
+// `tools: false` keeps the old shape for a caller that wants one model call and
+// no side effects.
+import { callEngine } from "#core/engines/index.js";
+import { resolveAgentAllowedTools } from "#core/agent/agent-tools.js";
+import { runAgent } from "#core/agent/index.js";
+import { createToolSession, makeToolHandlers } from "#core/agent/tools/registry.js";
+import { loadAgentSkills, collectAgentSkillMedia } from "#core/agent/skills/agent-skills.js";
+import { scopeProjects } from "#core/apc/projects-helpers.js";
+import { channelToolIters, MAX_TOOL_ITERS } from "#core/agent/constants.js";
+import { judgeConfig, judgeCompletion, applyJudgeLoop, continuableTurn } from "#core/agent/judge.js";
+
+// A chat reply is prose, not a Telegram one-liner: run-agent's 512-token default
+// truncates an agent mid-answer on the surface where the whole answer is the
+// point. Same headroom the routine runner gives itself.
+export const AGENT_TURN_MAX_TOKENS = 4096;
+
+/**
+ * @returns {{text, trace, usage, model, allowedTools, media, endedAwaitingUser, judge?}}
+ *   `media` is what the agent attached to THIS reply (attach_media). The caller
+ *   delivers it and records it on the turn; an empty array means it sent none.
+ *   `endedAwaitingUser` is true when the turn closed by asking the user
+ *   something, so nobody answers on their behalf. `judge` is the verdict trail,
+ *   present only when the completion judge actually scored the turn.
+ */
+export async function runAgentTurn({
+  p,
+  agent,
+  modelId,
+  system,
+  prompt,
+  previousMessages = [],
+  // Images that arrived with this turn: [{ kind, mime, data, path }]. Only the
+  // tool-driven path forwards them — the toolless callEngine branch is text.
+  attachments = [],
+  channel,
+  channelMeta,
+  temperature,
+  maxTokens,
+  tools = true,
+  // Left unset, the channel decides (channelToolIters). A project agent in the
+  // web chat is on the same watched surface Roby is, and was stopping every 9
+  // actions to ask whether to continue — the budget belongs to the surface, not
+  // to which agent happens to be answering.
+  maxIters,
+  projects,
+  plugins,
+  registries,
+  config,
+  onEvent = null,
+  onToken = null,
+  requestConfirmation = null,
+  // Cancellation. Without it a turn could only be stopped by not looking at it:
+  // the caller's stream closing does not end the run (that is what lets another
+  // tab catch up), so "stop" and "interrupt" both come down to signalling this.
+  signal = null,
+  // The completion judge, injectable so a test can supply verdicts without an
+  // engine. Production always uses the real one.
+  judgeCompletionFn = judgeCompletion,
+}) {
+  const cap = Number.isFinite(Number(maxTokens)) ? Number(maxTokens) : AGENT_TURN_MAX_TOKENS;
+
+  if (tools === false) {
+    const result = await callEngine({
+      modelId,
+      system,
+      messages: [...previousMessages, { role: "user", content: prompt }],
+      config: p.config || config,
+      temperature,
+      maxTokens,
+      signal,
+    });
+    return {
+      text: result.text || "",
+      trace: [],
+      usage: result.usage,
+      // What ANSWERED, which is not always what was resolved: routing can fall
+      // back mid-turn, and the caller should be told which model replied.
+      model: result.model || modelId,
+      allowedTools: [],
+      media: [],
+      // One model call, no tools, no loop: there is nothing here that could
+      // have stopped halfway, and nothing that could have asked.
+      endedAwaitingUser: false,
+    };
+  }
+
+  const cfg = structuredClone(p.config || config || {});
+  // Deliberately NOT forcing permission_mode. A routine pins it to "total"
+  // because a scheduled run has nobody to approve a dangerous tool; a chat has
+  // a person on the other end, so the configured policy stands and a blocked
+  // tool comes back to the model as an observation it can re-plan around.
+  const allowedTools = resolveAgentAllowedTools(agent);
+  // The allowlist decides WHAT it may call; the channel decides how much of it
+  // is loaded up front — a full channel gets the lot, a lightweight one starts
+  // on the base set and expands through discover_tools.
+  const toolSession = createToolSession(channel, { allowedTools });
+
+  // Images this agent's skills declare: the pool attach_media / view_media
+  // validate an id against, and the sink a queued attachment lands in.
+  //
+  // These used to be supplied ONLY by the routine runner, so attach_media was
+  // dead on every surface with a person on the other end: the same skills whose
+  // image manifest build-agent-system.js had just rendered into the prompt were
+  // not attachable, and the tool answered "no attachable images — this agent's
+  // skills declare none" to a model that could see them listed. A skill's
+  // picture is at its most useful mid-conversation, which was the one place it
+  // could not be sent.
+  const attachableMedia = collectAgentSkillMedia(loadAgentSkills(p, agent));
+  const mediaSink = [];
+
+  // An explicit budget from the caller always wins; otherwise the surface's own
+  // default applies. See channelToolIters.
+  //
+  // Resolved to a NUMBER, falling through to runAgent's own default rather than
+  // leaving it unset, because this is the turn's total and the judge loop below
+  // subtracts from it. "Whatever runAgent picks" is not a total you can share
+  // between rounds. Same resolution runSuperAgent does.
+  const turnMaxIters = (Number.isFinite(Number(maxIters)) && Number(maxIters) > 0
+    ? Number(maxIters)
+    : channelToolIters(cfg, channel)) || MAX_TOOL_ITERS;
+
+  const hasImage = (attachments || []).some((a) => a?.data && /^image\//.test(a.mime || ""));
+  // `iters` is what THIS pass may spend: the whole budget for the first run,
+  // whatever is left for a judge round.
+  const runOnce = (turnPrompt, history, iters = turnMaxIters) =>
+    runAgent({
+      globalConfig: cfg,
+      system,
+      prompt: turnPrompt,
+      previousMessages: history,
+      attachments,
+      overrideModel: modelId,
+      toolSchemas: toolSession.initialSchemas,
+      makeToolHandlers,
+      toolHandlerCtx: {
+        // Same scoping as a routine run: this agent belongs to `p`, so that is
+        // what an unqualified path means to it. See scopeProjects.
+        projects: scopeProjects(projects, p.id),
+        plugins,
+        registries,
+        globalConfig: cfg,
+        channel,
+        channelMeta: {
+          ...(channelMeta || {}),
+          ...(hasImage ? { has_image: true } : {}),
+          agentSlug: agent.slug,
+          projectPath: p.path,
+        },
+        toolSession,
+        attachableMedia,
+        mediaSink,
+        requestConfirmation,
+      },
+      agentName: agent.slug,
+      maxTokens: cap,
+      signal,
+      maxIters: iters,
+      onEvent,
+      onToken,
+    });
+
+  let result = await runOnce(prompt, previousMessages);
+
+  // Goal-completion judge — the same loop runSuperAgent runs, on the same
+  // switch (`super_agent.judge.continue_unfinished`, on by default).
+  //
+  // A conversational turn ends when the model stops calling tools, which is
+  // also what it does when it merely ANNOUNCES its next step ("ahora genero el
+  // SRT") and writes no call: nothing is finished, nothing was asked, and the
+  // task sits there until a person types "seguí". The super-agent has been
+  // continued automatically since b071e70; every project agent was still
+  // waiting to be poked, so Magui stalled in the web chat where Roby did not.
+  //
+  // EVERY CHANNEL a project agent answers on, not only the watched ones. The
+  // failure is the model's, not the surface's — the announce-instead-of-act
+  // turn reads identically on `api` and on `web` — and the two exclusions in
+  // continuableTurn already spend the call where it pays: a turn that ran no
+  // tools is chat (so "hola" never costs a judge call), and a turn that closed
+  // by ASKING is waiting rather than unfinished, which is the regression
+  // documented on continuableTurn — continuing it answers over the user's head
+  // and re-asks the identical question.
+  //
+  // Those two make a channel gate redundant, because they already cut per
+  // surface for the right reason. A bounded channel (api, and everything else
+  // channelToolIters leaves alone) reserves its last iteration for the wrap-up,
+  // so a turn that used its whole budget ends by asking and is excluded —
+  // leaving only the turn that quit early, which is exactly the bug. The
+  // run-to-completion surfaces (web, web_sidebar) have no wrap-up to fall back
+  // on, so the judge is the only thing that notices — and there a human is
+  // watching the tool calls render, one click from stopping the turn.
+  //
+  // Cost is one extra model call per JUDGED turn, and after those exclusions
+  // the judged population is "ran real tools, then went quiet without asking
+  // anything" — where a wasted scoring call is far cheaper than work that
+  // stopped halfway and nobody noticed. The group cascade reaches this too: a
+  // speaker that ran tools and went quiet is the same bug in a busier room.
+  //
+  // Not gated on `judge.enabled` — that switch guards the OTHER door, a
+  // completion-contract turn's own "done" claim, which project agents never
+  // take (no finish tool, no forced tool choice). An aborted turn is the user
+  // saying stop, the one instruction a judge must not overrule.
+  const jCfg = judgeConfig(cfg);
+  if (jCfg.continue_unfinished && !signal?.aborted && continuableTurn(result)) {
+    // Rolling refinement history: each round sees the original goal, its own
+    // prior reply, and the judge's follow-up as ordinary conversation turns.
+    const history = [...previousMessages, { role: "user", content: prompt }];
+    result = await applyJudgeLoop({
+      initialResult: result,
+      cfg: jCfg,
+      onEvent,
+      // The turn's whole budget, shared with the run above rather than reissued
+      // per round. See the "one turn, one budget" note in constants.js.
+      maxIters: turnMaxIters,
+      // The model that ran the turn is the judge's last-resort scorer: a
+      // project agent can be the only agent an install has, and `judge.model` /
+      // `super_agent.model` may both be unset.
+      judgeFn: (r) => judgeCompletionFn({ goal: prompt, result: r, globalConfig: cfg, fallbackModel: modelId }),
+      runFollowup: async (followup, prior, { maxIters: roundIters } = {}) => {
+        history.push({ role: "assistant", content: prior.text || "" });
+        const next = await runOnce(followup, [...history], roundIters);
+        history.push({ role: "user", content: followup });
+        return next;
+      },
+    });
+  }
+
+  return {
+    text: result.text || "",
+    trace: Array.isArray(result.trace) ? result.trace : [],
+    usage: result.usage,
+    model: result.model || modelId,
+    allowedTools,
+    // Accumulated across judge rounds by construction: the same sink is handed
+    // to every round, so an image attached before the turn was continued still
+    // reaches the caller.
+    media: mediaSink,
+    endedAwaitingUser: !!result.endedAwaitingUser,
+    ...(result.judge ? { judge: result.judge } : {}),
+  };
+}

package/src/core/agent/self-memory.js

@@ -19,8 +19,7 @@ import { SELF_MEMORY_PATH } from "../config/paths.js";
 
 export { SELF_MEMORY_PATH };
 import { resolveAgentName } from "../identity/index.js";
-
-
+import { appendDatedBullet } from "#core/memory/dated-log.js";
 
 function notebookHeader() {
   let name = "";
@@ -91,59 +90,23 @@ export function readSelfMemoryForPrompt(limit = SELF_MEMORY_PROMPT_LIMIT) {
   return out.join("\n").trim();
 }
 
-// HH:MM (UTC) for the current time — used to tag notes per the cross-channel
-// format "[HH:MM][canal] nota".
-function nowHm() {
-  return new Date().toISOString().slice(11, 16);
-}
-
 /**
- * Append a dated note to the notebook. Each note is a markdown bullet under a
- * `## YYYY-MM-DD` heading so the file stays chronologically skimmable. Creates
- * the file (and ~/.apx) on first write.
- *
- * opts.channel — when given, the bullet is tagged "[HH:MM][channel] note" so
- *   the cross-channel broker (and the RAG indexer) can attribute the note to a
- *   surface and time. Without it the legacy "- note" form is kept.
+ * Append a dated note to the notebook. Creates the file (and ~/.apx) on first
+ * write. The bullet format — one `## YYYY-MM-DD` heading per day, an
+ * "[HH:MM][channel]" tag so the cross-channel broker and the RAG indexer can
+ * attribute a note to a surface and a time — lives in core/memory/dated-log.js,
+ * shared with project memory and routine memory.
  */
 export function appendSelfMemory(note, opts = {}) {
   const text = String(note || "").trim();
   if (!text) throw new Error("nothing to remember (empty note)");
   fs.mkdirSync(path.dirname(SELF_MEMORY_PATH), { recursive: true });
 
-  const today = new Date().toISOString().slice(0, 10);
-  const existing = readSelfMemory();
-  const heading = `## ${today}`;
-  const oneLine = text.replace(/\n+/g, " ").trim();
-  const channel = String(opts.channel || "").trim().toLowerCase();
-  const tag = channel ? `[${opts.time || nowHm()}][${channel}] ` : "";
-  const bullet = `- ${tag}${oneLine}`;
-
-  let next;
-  if (!existing.trim()) {
-    next = `${notebookHeader()}\n\n${heading}\n${bullet}\n`;
-  } else if (existing.includes(heading)) {
-    // Append the bullet under today's existing heading.
-    const lines = existing.split("\n");
-    const idx = lines.lastIndexOf(heading);
-    // Find the end of today's block (next heading or EOF).
-    let insertAt = lines.length;
-    for (let i = idx + 1; i < lines.length; i++) {
-      if (lines[i].startsWith("## ")) {
-        insertAt = i;
-        break;
-      }
-    }
-    // Trim trailing blank lines inside the block before inserting.
-    while (insertAt > idx + 1 && lines[insertAt - 1].trim() === "") insertAt--;
-    lines.splice(insertAt, 0, bullet);
-    next = lines.join("\n");
-    if (!next.endsWith("\n")) next += "\n";
-  } else {
-    const sep = existing.endsWith("\n") ? "" : "\n";
-    next = `${existing}${sep}\n${heading}\n${bullet}\n`;
-  }
-
+  const next = appendDatedBullet(readSelfMemory(), text, {
+    channel: opts.channel,
+    time: opts.time,
+    header: notebookHeader(),
+  });
   fs.writeFileSync(SELF_MEMORY_PATH, next);
   return { path: SELF_MEMORY_PATH, note: text };
 }
@@ -164,12 +127,15 @@ export function ensureSelfMemoryFile() {
 // Parse the notebook into structured entries, oldest first. Tolerant of both
 // the legacy "- note" bullets and the tagged "[HH:MM][channel] note" /
 // "[YYYY-MM-DD HH:MM][channel] note" forms. Each entry:
-//   { date, time, channel, ts, text }
+//   { date, time, channel, ts, text, line }
+// `line` is the 0-based line number in the source text, so a caller editing
+// the file (prune) can remove exactly this bullet and nothing around it.
 export function parseSelfMemoryEntries(text) {
   const out = [];
   let date = "";
-  for (const raw of String(text || "").split("\n")) {
-    const line = raw.trim();
+  const rawLines = String(text || "").split("\n");
+  for (let li = 0; li < rawLines.length; li++) {
+    const line = rawLines[li].trim();
     const h = line.match(/^##\s+(\d{4}-\d{2}-\d{2})/);
     if (h) {
       date = h[1];
@@ -203,7 +169,7 @@ export function parseSelfMemoryEntries(text) {
     if (!rest) continue;
     const hm = time ? time.padStart(5, "0") : "00:00";
     const ts = date ? `${date}T${hm}:00Z` : "";
-    out.push({ date, time, channel: channel || "memory", ts, text: rest });
+    out.push({ date, time, channel: channel || "memory", ts, text: rest, line: li });
   }
   return out;
 }

package/src/core/agent/skills/agent-skills.js

@@ -0,0 +1,118 @@
+// A project agent's DECLARED skills (its `skills:` frontmatter), resolved and
+// rendered for the system prompt — with progressive disclosure.
+//
+// Until now every declared skill was injected whole into the prompt on EVERY
+// run. Cheap for a small skill, wasteful for a big one: a 7 KB syllabus spent
+// ~1.8 K tokens on every heartbeat even though a session teaches one section.
+//
+// The rule here:
+//   • small skill (body ≤ EAGER_MAX_CHARS) → inject the full body. One round
+//     trip saved is worth more than the tokens; there is nothing to page.
+//   • large skill                          → inject a CARD: description, the
+//     section outline, and the image manifest. The agent pulls the one section
+//     it needs with read_skill, and attaches/looks at an image with
+//     attach_media / view_media. Baseline tokens drop to the outline.
+//
+// This module is the single source both the prompt builder and the routine
+// runner read from, so "what skills are in context" and "what images can the
+// agent attach" never drift from what the prompt actually said.
+import { loadSkill } from "./loader.js";
+import { agentSkills } from "./declared.js";
+import { skillOutline } from "./sections.js";
+import { readSkillMedia, renderMediaManifest } from "./media.js";
+
+// A skill whose body is at or under this many characters is injected whole.
+// ~1800 chars ≈ 450 tokens — below that the card + a read_skill round trip
+// would cost more than it saves.
+export const EAGER_MAX_CHARS = 1800;
+
+/**
+ * Load an agent's declared skills with everything the prompt and the runner
+ * need. Skills that fail to resolve are skipped (a stale `skills:` entry must
+ * not crash a run).
+ *
+ * @returns {Array<{
+ *   slug:string, mode:'eager'|'lazy', body:string, description:string,
+ *   outline:string[], media:Array, file:string
+ * }>}
+ */
+export function loadAgentSkills(project, agent) {
+  const out = [];
+  for (const slug of agentSkills(agent)) {
+    let skill;
+    try {
+      skill = loadSkill(slug, { projectPath: project?.path });
+    } catch {
+      continue; // stale entry — silently skip, never throw mid-run
+    }
+    const body = String(skill.body || "").trim();
+    const media = readSkillMedia(skill);
+    // A skill with images is a large skill by nature (you page through it), so
+    // it goes lazy even if the text is short — that is exactly when the media
+    // manifest + read_skill pay off.
+    const mode = body.length <= EAGER_MAX_CHARS && media.length === 0 ? "eager" : "lazy";
+    out.push({
+      slug,
+      mode,
+      body,
+      description: skill.description || "",
+      outline: skillOutline(body),
+      media,
+      file: skill.file || "",
+    });
+  }
+  return out;
+}
+
+/**
+ * The system-prompt block for a set of loaded skills. Eager skills print full;
+ * lazy skills print a card (description + outline + image manifest) plus the
+ * one-line instruction for how to pull more.
+ */
+export function renderAgentSkillsBlock(loaded) {
+  const parts = [];
+  for (const s of loaded) {
+    if (s.mode === "eager") {
+      parts.push(`## Skill: ${s.slug}\n${s.body}`);
+      continue;
+    }
+    const lines = [`## Skill: ${s.slug} (loaded on demand)`];
+    if (s.description) lines.push(s.description);
+    if (s.outline.length) {
+      lines.push(
+        "Sections (call `read_skill` with the skill slug and a section title/number to read one):",
+        ...s.outline.map((t) => `- ${t}`),
+      );
+    }
+    const manifest = renderMediaManifest(s.media);
+    if (manifest) lines.push(manifest);
+    parts.push(lines.join("\n"));
+  }
+  return parts.join("\n\n");
+}
+
+/**
+ * Every image across an agent's loaded skills, flattened and tagged with its
+ * skill, for the runner to validate attach_media / view_media against and to
+ * hand to delivery. Only images whose file actually exists are returned.
+ */
+export function collectAgentSkillMedia(loaded) {
+  const out = [];
+  for (const s of loaded) {
+    for (const m of s.media) {
+      if (!m.exists) continue;
+      out.push({ skill: s.slug, id: m.id, path: m.path, caption: m.caption, mime: m.mime, file: m.file });
+    }
+  }
+  return out;
+}
+
+/** Compact "skills in context" summary for the turn record (visibility). */
+export function skillsInContextSummary(loaded) {
+  return loaded.map((s) => ({
+    slug: s.slug,
+    mode: s.mode,
+    sections: s.outline.length,
+    images: s.media.filter((m) => m.exists).length,
+  }));
+}

package/src/core/agent/skills/catalog.js

@@ -7,7 +7,7 @@
 //      condensed description) is reached via the `list_skills` tool.
 //   2. The `list_skills` tool itself renders descriptions using
 //      condenseSkillDescription() — keeps the trigger-list tails out of the
-//      tool result, same way the legacy catalog did.
+//      tool result.
 //
 // Skill descriptions are authored for Claude Code's skill matcher, so many end
 // with verbose "Trigger on: …" / "Activate when …" / "Activa cuando…" lists.

package/src/core/agent/skills/declared.js

@@ -0,0 +1,13 @@
+// Reading list-valued frontmatter fields off an agent card. Lives in its own
+// module so both the prompt builder (build-agent-system.js) and the skill
+// loader (agent-skills.js) can share it without an import cycle.
+
+export function listField(value) {
+  if (Array.isArray(value)) return value.map(String).map((s) => s.trim()).filter(Boolean);
+  return String(value || "").split(",").map((s) => s.trim()).filter(Boolean);
+}
+
+/** The skill slugs an agent declares in its `skills:` frontmatter. */
+export function agentSkills(agent) {
+  return listField(agent?.fields?.Skills);
+}

package/src/core/agent/skills/index-store.js

@@ -165,6 +165,13 @@ export async function ensureIndex({ projectPath, embedOpts = {}, onProgress, for
   const embedder = embedderTag(probe);
   const dim = probe.vector.length;
 
+  // Pin every per-skill embed to the engine the probe actually landed on, so a
+  // chain that fell past a rate-limited provider to a working one doesn't
+  // re-probe (and re-fail) the dead provider once per skill.
+  const embedPinned = embedder === "tf"
+    ? { ...embedOpts, forceTf: true }
+    : { ...embedOpts, provider: embedder.split(":")[0] };
+
   const embedderChanged = !force && idxBefore.embedder && idxBefore.embedder !== embedder;
   const items = embedderChanged || force ? {} : structuredClone(idxBefore.items || {});
 
@@ -191,7 +198,7 @@ export async function ensureIndex({ projectPath, embedOpts = {}, onProgress, for
       kept.push(s.slug);
       action = "kept";
     } else {
-      const out = await embedOne(desc, embedOpts);
+      const out = await embedOne(desc, embedPinned);
       const vector = Array.isArray(out?.vector) ? out.vector : [];
       items[s.slug] = {
         slug: s.slug,

package/src/core/agent/skills/inspector.js

@@ -100,7 +100,10 @@ function renderInjectedBlock({ loaded, hinted, embedder }) {
   if (hinted.length) {
     lines.push("## Possibly relevant — load on demand");
     for (const s of hinted) {
-      lines.push(`- \`${s.slug}\` — sim ${s.sim.toFixed(2)}. ${s.desc}`);
+      // A description read from a block scalar carries real newlines; this is
+      // one markdown list item, so collapse it back to a single line.
+      const desc = String(s.desc || "").replace(/\s+/g, " ").trim();
+      lines.push(`- \`${s.slug}\` — sim ${s.sim.toFixed(2)}. ${desc}`);
     }
     lines.push("");
     lines.push("Call `load_skill({slug:\"…\"})` for any of these BEFORE answering if you need its exact syntax.");
@@ -174,9 +177,23 @@ export async function inspectPromptForSkills({ prompt, projectPath, globalConfig
     return { contextNote: "", trace: { enabled: true, reason: "embed_failed" } };
   }
 
-  // Embedder mismatch — old index was built with a different provider. Don't
-  // mix cosine spaces; the operator needs to re-run `apx skills index`.
+  // Embedder mismatch — the index was built with a different provider (e.g. the
+  // local Ollama server was up when it was indexed and is now down, so we fell
+  // back to `tf`). Cosine only means anything within one embedder space, so we
+  // can't score this turn. But the line-156 refresh can't detect this on its own
+  // (it runs before we know the request-time embedder), so kick a rebuild HERE
+  // with the embedder we just probed: planIndex sees embedderChanged and rebuilds
+  // the index to the current space, and the NEXT turn scores normally. Without
+  // this the mismatch stuck silently until a daemon reboot or `apx skills index`
+  // — which is exactly how skill suggestions "just stopped appearing".
   if (idx.embedder && idx.embedder !== probe.embedder) {
+    try {
+      backgroundRefreshIfStale({
+        projectPath,
+        embedOpts: { ...(embedOpts || {}), globalConfig },
+        currentEmbedder: probe.embedder,
+      });
+    } catch { /* best-effort */ }
     return {
       contextNote: "",
       trace: {

package/src/core/agent/skills/loader.js

@@ -34,6 +34,7 @@ import { SKILLS_DIR } from "#core/config/paths.js";
 import { fileURLToPath } from "node:url";
 import { apcSkillsDir } from "#core/apc/paths.js";
 import { parseFrontmatter } from "#core/apc/frontmatter.js";
+import { skillOrigin } from "./origin.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname  = path.dirname(__filename);
@@ -56,7 +57,15 @@ const GLOBAL_DIR         = SKILLS_DIR;
 // Directory scanners
 // ---------------------------------------------------------------------------
 
-/** Returns [{slug, source, file}] from a directory using <slug>/SKILL.md layout. */
+/** Returns [{slug, source, file}] from a directory using <slug>/SKILL.md layout.
+ *
+ *  Symlinked entries count. `readdirSync({withFileTypes:true})` reports a
+ *  symlink-to-directory as isSymbolicLink() and NOT isDirectory(), so testing
+ *  isDirectory() alone silently skipped any skill linked in from somewhere
+ *  else — the natural way to keep a skill managed by an external tool
+ *  (`npx skills add` installs to ~/.agents/skills/) without copying it. The
+ *  existsSync() below follows the link, so a broken link or a link to a file
+ *  still drops out. */
 function scanDirStyle(baseDir, source) {
   if (!baseDir || !fs.existsSync(baseDir)) return [];
   const out = [];
@@ -64,7 +73,7 @@ function scanDirStyle(baseDir, source) {
   try { entries = fs.readdirSync(baseDir, { withFileTypes: true }); }
   catch { return []; }
   for (const e of entries) {
-    if (!e.isDirectory()) continue;
+    if (!e.isDirectory() && !e.isSymbolicLink()) continue;
     const file = path.join(baseDir, e.name, "SKILL.md");
     if (fs.existsSync(file)) out.push({ slug: e.name, source, file });
   }
@@ -79,8 +88,10 @@ function scanFlatStyle(baseDir, source) {
   try { entries = fs.readdirSync(baseDir, { withFileTypes: true }); }
   catch { return []; }
   for (const e of entries) {
-    if (!e.isFile() || !e.name.endsWith(".md")) continue;
+    if (!e.isFile() && !e.isSymbolicLink()) continue;   // see scanDirStyle
+    if (!e.name.endsWith(".md")) continue;
     if (e.name === "README.md") continue;
+    if (e.isSymbolicLink() && !fs.statSync(path.join(baseDir, e.name), { throwIfNoEntry: false })?.isFile()) continue;
     out.push({
       slug: e.name.replace(/\.md$/, ""),
       source,
@@ -138,6 +149,7 @@ export function listSkills({ projectPath } = {}) {
       source: entry.source,
       description,
       file: entry.file,
+      ...skillOrigin(entry.file, { source: entry.source }),
     });
   }
   return result;
@@ -170,6 +182,9 @@ export function loadSkill(slug, { projectPath } = {}) {
     description: entry.description || fm.description || "",
     frontmatter: fm,
     body: body.trim(),
+    origin: entry.origin,
+    origin_path: entry.origin_path,
+    file_path: entry.file_path,
   };
 }