@agentprojectcontext/apx 1.33.1 → 1.35.0

package/src/core/agent/prompts/core/super-agent.md

@@ -0,0 +1,21 @@
+# Role
+You are the always-on agent for this APX install — the default voice when no project agent was named. Your real display name comes from the **User & identity** section below.
+
+APX is the system you operate (its daemon, config, projects, registered agents, sessions, message logs). APC is the project layout (`.apc/`, `AGENTS.md`) you read on disk when working inside a project. You are NOT APX or APC — you are the agent that knows them well and acts through them.
+
+You are not pinned to a single project. You move across every registered project freely, can delegate to a project's own agent (`call_agent`), dispatch work to an external runtime (`call_runtime` → claude-code, codex, opencode, …), or import a new agent from the vault (`list_vault_agents` → `import_agent`).
+
+# Hierarchy
+- **Self-run**: no agent named, or the user says "you/yourself/same/default" → act as yourself.
+- **Delegate**: the user names a registered project agent → `call_agent`.
+- **Dispatch**: the user names an external runtime → `call_runtime`.
+
+# Projects
+- The default workspace (`id=0`, name `default`) is APX home — it is the "global" scratchpad, not a user repo. Project-scoped work (routines, agent memory, code edits in a real repo) needs a REAL project; if the user asks for project-scoped work without naming one, ask which one.
+- Register a project with `add_project` only — never hand-write `AGENTS.md` or `.apc/project.json` via shell.
+- Identity changes (your name, the user's name, your personality) → `set_identity`, then confirm.
+
+# Don't
+- Don't tell the user to run an `apx …` command to get info you can fetch with a tool. You operate APX; run the tool yourself.
+- Don't paste base64 / data URIs in chat — send media via `send_telegram` params or paths.
+- Don't recite the registered-project list at the user; call a tool when they ask.

package/src/core/agent/prompts/discipline/action.md

@@ -0,0 +1,10 @@
+# Action discipline (mandatory)
+- NEVER acknowledge an action you will not execute in the same turn. If you say you will do something, the tool call must be in the same response.
+- Empty acknowledgments ("Ok", "On it", "Give me a moment", "I'll do that now") are not valid standalone replies when a tool call is expected. Either call the tool in this turn, or explain WHY you can't (missing permission, unclear params, tool unavailable).
+- If the user asks for multiple things, do them all in this turn using sequential tool calls.
+- If a tool errors, retry with different arguments before asking the user.
+
+# Chit-chat
+- A pure greeting / thanks / "ok" with no actionable request → reply with `finish` only, no other tool call. Tools exist so you can act when needed, not so you must use one.
+- A greeting that piggybacks a real request ("hola, listame las rutinas") is NOT chit-chat — handle the request normally.
+- When in doubt, ask ONE short clarifying question via `finish` — never invent a topic to "be useful".

package/src/core/agent/prompts/discipline/single-segment.md

@@ -0,0 +1,6 @@
+# One reply per turn (voice / desktop / deck-voice)
+Your reply will be spoken aloud, or shown briefly in a small surface. Produce ONE clean message per turn — no intro filler, no "ahora ejecuto X" before the tool, no restating after.
+
+- Call any tools you need silently, then write the ONE answer with the result.
+- Lead with the outcome. Keep it to 1–2 short sentences unless the user asks for detail.
+- Greet at most once per conversation; if you already greeted, skip it.

package/src/core/agent/prompts/discipline/two-segment.md

@@ -0,0 +1,11 @@
+# Two-segment turns (text channels with visible history)
+When you call a tool, the user sees two text segments — the intro before the tool runs, and the answer after it returns.
+
+1. **Intro** — a short natural filler in the user's language BEFORE the tool runs. 2–8 words. NEVER contains the answer. Examples: "Reviso eso", "Dale, lo anoto", "Un momento, busco".
+2. **Answer** — the substantive result AFTER the tool returns. Carries the data, the confirmation, or the next question.
+
+Rules:
+- The intro NEVER includes the substantive content. The tool hasn't run yet — you don't know the result.
+- The answer NEVER restates the intro. They're complementary: filler + result.
+- Greet at most ONCE per turn. If the intro greeted, the answer starts with the result.
+- A turn with NO tool calls produces ONE segment — go straight to the answer.

package/src/core/agent/prompts/modes/code-build.md

@@ -0,0 +1 @@
+MODE: build. Make the changes directly using your file and shell tools (read_file, write_file, edit_file, run_shell, …). Do not ask for confirmation and do not stop after one step — keep calling tools until the entire task is done, then briefly summarize what you changed and why. Prefer surgical edits over rewrites. When the user asks for a reusable script, snippet, or 'artifact' (something they want to keep and run later), put it under `artifacts/<name>` inside the project — it then shows up in the Artifacts tab. Don't drop reusable scripts at the project root. If a parameter you need is missing (API key, app id, target URL, …), call `ask_questions` ONCE with all your questions and stop — control returns to the user. Do not call ask_questions again in the same turn; you'll just get the same blank state back. Each question can be a string (free-text answer) OR an object {question, options:[{label, description}], multiSelect} for choices. Prefer 2–4 mutually-exclusive options when a question has a natural shortlist (yes/no, which-of-these, …); leave options empty for open-ended answers (API keys, names, free-form ideas). If the previous assistant turn already asked these same questions and the current user message is the compiled answers, DO NOT call ask_questions again — process the answers and proceed with the task.

package/src/core/agent/prompts/modes/code-plan.md

@@ -0,0 +1 @@
+MODE: plan. Investigate the codebase (read/list/search/grep) and propose an approach with the EXACT changes you would make (files + diffs/snippets). Do NOT write or edit files and do NOT run mutating shell commands — your editing tools are disabled in this mode. End with a concise, ordered plan.

package/src/core/agent/prompts/modes/index.js

@@ -0,0 +1,28 @@
+// Mode-specific system-prompt fragments for the Code module (plan / build).
+// Each mode lives in its own .md sibling and is loaded once at boot.
+//
+// Why .md files instead of inline strings: the prompts are content, not code.
+// Editing prompt copy shouldn't require touching code, and reviewing changes
+// to behavior should be a doc-shaped diff, not a JS-shaped one.
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { CODE_MODES } from "#core/constants/code-modes.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+function load(file) {
+  return fs.readFileSync(path.join(__dirname, file), "utf8").trim();
+}
+
+const CODE_PLAN_GUIDANCE  = load("code-plan.md");
+const CODE_BUILD_GUIDANCE = load("code-build.md");
+
+/**
+ * Return the system-prompt fragment that explains how this mode behaves to
+ * the agent. Falls back to BUILD when the mode is missing or unknown — build
+ * is the safer default for the Code module (no mid-edit "do nothing" stall).
+ */
+export function codeModeGuidance(mode) {
+  return mode === CODE_MODES.PLAN ? CODE_PLAN_GUIDANCE : CODE_BUILD_GUIDANCE;
+}

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

@@ -44,7 +44,49 @@ export function readSelfMemoryForPrompt(limit = SELF_MEMORY_PROMPT_LIMIT) {
   const body = readSelfMemory().trim();
   if (!body) return "";
   if (body.length <= limit) return body;
-  return body.slice(0, limit).trimEnd() + "\n… (truncated — call read_self_memory for the full notebook)";
+
+  // The notebook grows chronologically (oldest day first), so a naive head
+  // slice injects the OLDEST notes and truncates the most recent — exactly
+  // backwards for "what's relevant now". Keep the file header + the NEWEST
+  // entries that fit `limit`, re-grouped under their date headings. The full
+  // file is always available via read_self_memory.
+  const firstLine = body.split("\n", 1)[0];
+  const header = firstLine.startsWith("# ") ? firstLine : notebookHeader();
+  const notice =
+    "_(most recent notes — older history truncated; call read_self_memory for the full notebook)_";
+
+  const entries = parseSelfMemoryEntries(body); // oldest → newest
+  if (!entries.length) {
+    // No structured bullets (free-form prose notebook) — fall back to the tail.
+    const tail = body.slice(-(limit - notice.length - 2)).replace(/^\S*\n/, "");
+    return `${notice}\n${tail.trim()}`;
+  }
+
+  let budget = limit - header.length - notice.length - 4;
+  const picked = [];
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const e = entries[i];
+    const tag =
+      (e.time ? `[${e.time}]` : "") +
+      (e.channel && e.channel !== "memory" ? `[${e.channel}]` : "");
+    const bullet = `- ${tag ? tag + " " : ""}${e.text}`.replace(/\s+/g, " ").trim();
+    const cost = bullet.length + 14; // headroom for an occasional date heading
+    if (budget - cost < 0 && picked.length) break;
+    picked.push({ date: e.date, bullet });
+    budget -= cost;
+  }
+  picked.reverse(); // back to chronological order (newest at the bottom)
+
+  const out = [header, notice];
+  let lastDate = "";
+  for (const p of picked) {
+    if (p.date && p.date !== lastDate) {
+      out.push("", `## ${p.date}`);
+      lastDate = p.date;
+    }
+    out.push(p.bullet);
+  }
+  return out.join("\n").trim();
 }
 
 // HH:MM (UTC) for the current time — used to tag notes per the cross-channel

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

@@ -0,0 +1,307 @@
+// Persistent vector index for the skill inspector.
+//
+// Why a store instead of re-embedding every turn:
+//   - The inspector scores the user prompt against every known skill on every
+//     turn. Even with the in-process cache in rag.js, a daemon restart pays the
+//     cold cost. A JSON-backed store survives restarts and makes `apx skills
+//     index` a real, observable operation (progress bar, totals).
+//   - It also unlocks "chunked" descriptions later: today we embed just the
+//     condensed description; tomorrow we can index the SKILL.md body itself.
+//
+// Format (~/.apx/skills/.index.json):
+//   {
+//     embedder: "tf" | "ollama:nomic-embed-text" | "openai:text-embedding-3-small" | ...,
+//     dim: 256 | 768 | ...,
+//     updated_at: "2026-06-13T...",
+//     items: {
+//       "<slug>": {
+//         slug, source, file, mtime_ms,
+//         desc_hash, desc, desc_vector: [..],
+//         // future: chunks: [{ text, vector }]
+//       }
+//     }
+//   }
+//
+// Invariants:
+//   - All vectors in the file share the same embedder tag and dim. Switching
+//     embedder invalidates the entire index — we rebuild from scratch.
+//   - A skill whose source file has a different mtime than what's recorded is
+//     re-embedded the next time `ensureIndex` runs. A skill that disappeared
+//     is dropped.
+//   - Reads NEVER throw into the daemon: a corrupted file is treated as empty.
+//
+// Concurrency: the daemon is single-process for now; we use a simple write-
+// then-rename to avoid half-written files, no advisory lock. If a future
+// multi-process arrangement is added, swap in proper file locking here.
+
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+import { embedOne } from "#core/memory/embeddings.js";
+import { listSkills } from "./loader.js";
+import { condenseSkillDescription } from "./catalog.js";
+
+const INDEX_PATH = path.join(os.homedir(), ".apx", "skills", ".index.json");
+
+// ---------------------------------------------------------------------------
+// Disk I/O
+// ---------------------------------------------------------------------------
+
+function emptyIndex() {
+  return { embedder: null, dim: null, updated_at: null, items: {} };
+}
+
+export function indexPath() {
+  return INDEX_PATH;
+}
+
+export function readIndex() {
+  try {
+    if (!fs.existsSync(INDEX_PATH)) return emptyIndex();
+    const raw = fs.readFileSync(INDEX_PATH, "utf8");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || !parsed.items) return emptyIndex();
+    return parsed;
+  } catch {
+    return emptyIndex();
+  }
+}
+
+function writeIndex(idx) {
+  fs.mkdirSync(path.dirname(INDEX_PATH), { recursive: true });
+  const tmp = INDEX_PATH + ".tmp";
+  fs.writeFileSync(tmp, JSON.stringify(idx, null, 2));
+  fs.renameSync(tmp, INDEX_PATH);
+}
+
+// ---------------------------------------------------------------------------
+// Hashing
+// ---------------------------------------------------------------------------
+
+function descHashOf(text) {
+  let h = 0;
+  const s = String(text || "");
+  for (let i = 0; i < s.length; i++) h = ((h << 5) - h + s.charCodeAt(i)) | 0;
+  return h;
+}
+
+function fileMtimeMs(file) {
+  try { return fs.statSync(file).mtimeMs; } catch { return 0; }
+}
+
+// ---------------------------------------------------------------------------
+// Build / refresh
+// ---------------------------------------------------------------------------
+
+/**
+ * Decide what work the next ensureIndex() call would do — without actually
+ * embedding anything. Used by `apx skills index` to render the progress bar
+ * and by the inspector startup probe to decide whether to bother rebuilding.
+ *
+ * Returns: { existing, missing, stale, gone, total } — `existing` are the
+ * slugs that already have an up-to-date vector, `missing` need a first embed,
+ * `stale` had their description rewritten, `gone` are slugs in the index but
+ * no longer on disk.
+ */
+export function planIndex({ projectPath, currentEmbedder } = {}) {
+  const skills = listSkills({ projectPath });
+  const idx = readIndex();
+  const embedderChanged = currentEmbedder && idx.embedder && idx.embedder !== currentEmbedder;
+
+  const existing = [];
+  const missing = [];
+  const stale = [];
+  const slugsSeen = new Set();
+
+  for (const s of skills) {
+    slugsSeen.add(s.slug);
+    const desc = condenseSkillDescription(s.description);
+    const hash = descHashOf(desc + "|" + s.file);
+    const mtime = fileMtimeMs(s.file);
+    const hit = idx.items?.[s.slug];
+
+    if (embedderChanged || !hit || !Array.isArray(hit.desc_vector)) {
+      missing.push(s.slug);
+    } else if (hit.desc_hash !== hash || hit.mtime_ms !== mtime) {
+      stale.push(s.slug);
+    } else {
+      existing.push(s.slug);
+    }
+  }
+
+  const gone = Object.keys(idx.items || {}).filter((slug) => !slugsSeen.has(slug));
+
+  return {
+    existing,
+    missing,
+    stale,
+    gone,
+    total: skills.length,
+    embedderChanged: !!embedderChanged,
+    embedder: idx.embedder,
+  };
+}
+
+/**
+ * Bring the on-disk index up to date with the current skill catalog. Skills
+ * with unchanged file+desc are skipped (cheap). Skills with new/changed
+ * content are re-embedded. Skills that disappeared are dropped. When the
+ * embedder differs from the file's tag, the whole index is rebuilt.
+ *
+ * @param opts.projectPath  also scan this project's .apc/skills
+ * @param opts.embedOpts    forwarded to embedOne (globalConfig, provider, ...)
+ * @param opts.onProgress   called as ({ done, total, slug, action })
+ * @param opts.force        rebuild every slug from scratch
+ * @returns { embedder, dim, items, changed: { added, refreshed, removed, kept } }
+ */
+export async function ensureIndex({ projectPath, embedOpts = {}, onProgress, force = false } = {}) {
+  const skills = listSkills({ projectPath });
+  const idxBefore = readIndex();
+
+  // Probe the embedder once. If TF fallback wins, every skill embeds offline —
+  // no per-skill provider timeout cost. Tag is "<provider>:<model>" or "tf".
+  const probe = await embedOne("probe", embedOpts);
+  const embedder = embedderTag(probe);
+  const dim = probe.vector.length;
+
+  const embedderChanged = !force && idxBefore.embedder && idxBefore.embedder !== embedder;
+  const items = embedderChanged || force ? {} : structuredClone(idxBefore.items || {});
+
+  const added = [];
+  const refreshed = [];
+  const kept = [];
+
+  const seen = new Set();
+  let done = 0;
+  for (const s of skills) {
+    seen.add(s.slug);
+    const desc = condenseSkillDescription(s.description);
+    const hash = descHashOf(desc + "|" + s.file);
+    const mtime = fileMtimeMs(s.file);
+
+    const prev = items[s.slug];
+    const upToDate = prev
+      && Array.isArray(prev.desc_vector)
+      && prev.desc_hash === hash
+      && prev.mtime_ms === mtime;
+
+    let action;
+    if (upToDate) {
+      kept.push(s.slug);
+      action = "kept";
+    } else {
+      const out = await embedOne(desc, embedOpts);
+      const vector = Array.isArray(out?.vector) ? out.vector : [];
+      items[s.slug] = {
+        slug: s.slug,
+        source: s.source,
+        file: s.file,
+        mtime_ms: mtime,
+        desc_hash: hash,
+        desc,
+        desc_vector: vector,
+      };
+      if (prev) {
+        refreshed.push(s.slug);
+        action = "refreshed";
+      } else {
+        added.push(s.slug);
+        action = "added";
+      }
+    }
+
+    done += 1;
+    try { onProgress?.({ done, total: skills.length, slug: s.slug, action }); }
+    catch { /* progress callback errors must not break indexing */ }
+  }
+
+  const removed = Object.keys(items).filter((slug) => !seen.has(slug));
+  for (const slug of removed) delete items[slug];
+
+  const next = {
+    embedder,
+    dim,
+    updated_at: new Date().toISOString(),
+    items,
+  };
+  writeIndex(next);
+
+  return {
+    embedder,
+    dim,
+    items,
+    changed: { added, refreshed, removed, kept },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Self-healing background refresh
+// ---------------------------------------------------------------------------
+
+// Single in-flight guard so concurrent turns don't stack reindexes. Module-
+// scoped: one daemon process = one refresh at a time.
+let refreshInFlight = null;
+
+/**
+ * If the on-disk index is out of date relative to the live catalog (a skill
+ * was added/edited/removed, or the embedder changed), kick a background
+ * rebuild — WITHOUT blocking the caller. The current turn keeps using whatever
+ * is already indexed; the next turn sees the fresh vectors.
+ *
+ * This is what makes "drop a SKILL.md and it just works" true: the inspector
+ * calls this every turn (fire-and-forget), and the daemon calls it on startup.
+ *
+ * Returns a small descriptor of what it decided to do (handy for logging/tests).
+ */
+export function backgroundRefreshIfStale({ projectPath, embedOpts = {}, currentEmbedder, onDone } = {}) {
+  if (refreshInFlight) return { started: false, reason: "in_flight" };
+
+  let plan;
+  try {
+    plan = planIndex({ projectPath, currentEmbedder });
+  } catch {
+    return { started: false, reason: "plan_failed" };
+  }
+
+  const work = plan.missing.length + plan.stale.length + plan.gone.length;
+  if (work === 0 && !plan.embedderChanged) {
+    return { started: false, reason: "fresh" };
+  }
+
+  refreshInFlight = ensureIndex({ projectPath, embedOpts, force: plan.embedderChanged })
+    .then((out) => {
+      try { onDone?.(out); } catch { /* best-effort */ }
+      return out;
+    })
+    .catch(() => null)
+    .finally(() => { refreshInFlight = null; });
+
+  return {
+    started: true,
+    missing: plan.missing.length,
+    stale: plan.stale.length,
+    gone: plan.gone.length,
+    embedderChanged: plan.embedderChanged,
+  };
+}
+
+/** Await any in-flight background refresh (used by tests / graceful shutdown). */
+export async function awaitRefresh() {
+  if (refreshInFlight) { try { await refreshInFlight; } catch { /* ignore */ } }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+export function embedderTag(probe) {
+  if (!probe) return "tf";
+  if (probe.embedder) return probe.embedder;
+  return "tf";
+}
+
+/** Delete the on-disk index. Used by `apx skills index --reset`. */
+export function clearIndex() {
+  try { fs.unlinkSync(INDEX_PATH); } catch { /* missing is fine */ }
+}

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

@@ -3,4 +3,18 @@ export { condenseSkillDescription, buildSkillsHintBlock } from "./catalog.js";
 export { tryResolveSkillCommand } from "./trigger.js";
 export { suggestSkillForPrompt, clearSkillVectorCache } from "./rag.js";
 export { listSkills, loadSkill, SKILL_LOCATIONS } from "./loader.js";
-
+export {
+  inspectPromptForSkills,
+  isInspectorEnabled,
+  INSPECTOR_DEFAULTS,
+  summarizeTrace,
+} from "./inspector.js";
+export {
+  ensureIndex,
+  planIndex,
+  readIndex,
+  clearIndex,
+  indexPath,
+  backgroundRefreshIfStale,
+  awaitRefresh,
+} from "./index-store.js";