@agentprojectcontext/apx 1.33.1 → 1.35.0

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

@@ -0,0 +1,317 @@
+// Skill Inspector — middleware that mutates the chat each turn so the agent
+// only ever sees the skills it actually needs.
+//
+// Design goals (test feature, opt-in via config.skills.inspector.enabled):
+//   1. NO static slug dump. The "Available skills" hint block listing every
+//      slug in the catalog is suppressed when the inspector is on — the agent
+//      reaches skills via this middleware and the existing load_skill tool.
+//   2. Per-turn re-evaluation. The decision is recomputed from the current
+//      user prompt; a skill that matched last turn but not this one simply
+//      disappears from the next system prompt — natural decay.
+//   3. Two tiers based on confidence:
+//        - LOAD  (sim ≥ load_threshold): the body is inlined as contextNote.
+//          The agent has it right there — no extra tool call.
+//        - HINT  (sim ≥ hint_threshold): only the slug + one-line description
+//          is named, and the agent is told to call load_skill if it actually
+//          needs the syntax.
+//      Below hint_threshold → nothing.
+//   4. Local-first. Uses the same embeddings chain as cross-channel memory
+//      (ollama → gemini → openai → tf). With no provider, the offline TF
+//      fallback runs — works on any machine, zero API key, zero GPU.
+//   5. Never block the request. Any embedding failure → empty contextNote.
+//
+// Returns a structured trace so the daemon can emit `skill_inspector` events
+// to the stream (handy for the web debug panel and CLI inspect).
+
+import { embedOne, cosineSim } from "#core/memory/embeddings.js";
+import { listSkills, loadSkill } from "./loader.js";
+import { readIndex, backgroundRefreshIfStale } from "./index-store.js";
+
+// Defaults — exported so the CLI/web can render them.
+export const INSPECTOR_DEFAULTS = Object.freeze({
+  enabled: false,             // OPT-IN — this is a test feature.
+  load_threshold: 0.55,       // sim ≥ this → inline body
+  hint_threshold: 0.40,       // sim ≥ this → just hint
+  margin: 0.04,               // top must beat runner-up by this for confident pick
+  max_loaded: 1,              // how many bodies to inline at once
+  max_hints: 2,               // how many additional hints to add
+  prompt_floor: 8,            // skip super-short prompts ("ok", "hola")
+  body_char_cap: 6000,        // hard cap on inlined skill bodies (token guard)
+});
+
+function effectiveConfig(globalConfig) {
+  const raw = globalConfig?.skills?.inspector || {};
+  return { ...INSPECTOR_DEFAULTS, ...raw };
+}
+
+/** Quick public probe so the daemon/api can decide whether to suppress the
+ *  static hint block in the system prompt. */
+export function isInspectorEnabled(globalConfig) {
+  return effectiveConfig(globalConfig).enabled === true;
+}
+
+// ---------------------------------------------------------------------------
+// Scoring
+// ---------------------------------------------------------------------------
+
+function scoreAgainstIndex(promptVec, indexItems) {
+  const out = [];
+  for (const slug of Object.keys(indexItems)) {
+    const it = indexItems[slug];
+    if (!Array.isArray(it.desc_vector)) continue;
+    out.push({
+      slug,
+      source: it.source,
+      desc: it.desc || "",
+      file: it.file,
+      sim: cosineSim(promptVec, it.desc_vector),
+    });
+  }
+  out.sort((a, b) => b.sim - a.sim);
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Context block rendering
+// ---------------------------------------------------------------------------
+
+function renderInjectedBlock({ loaded, hinted, embedder }) {
+  if (loaded.length === 0 && hinted.length === 0) return "";
+
+  const lines = [
+    "# Skill Inspector",
+    `Local RAG (${embedder}) matched the user's prompt against your skill catalog.`,
+    "The catalog itself is NOT in your system prompt — only what's below is.",
+    "If none of these is right, call `list_skills` to browse and `load_skill` to fetch one.",
+    "",
+  ];
+
+  if (loaded.length) {
+    lines.push("## Loaded for this turn");
+    for (const s of loaded) {
+      lines.push("");
+      lines.push(`### \`${s.slug}\`  (sim ${s.sim.toFixed(2)}, source: ${s.source})`);
+      lines.push(s.body);
+    }
+    lines.push("");
+  }
+
+  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}`);
+    }
+    lines.push("");
+    lines.push("Call `load_skill({slug:\"…\"})` for any of these BEFORE answering if you need its exact syntax.");
+  }
+
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Main entrypoint
+// ---------------------------------------------------------------------------
+
+/**
+ * Decide what skill context (if any) to inject for this turn.
+ *
+ * @param {object} args
+ * @param {string} args.prompt          the user's current message
+ * @param {string=} args.projectPath    project root (project skills shadow global)
+ * @param {object=} args.globalConfig   passed through to embedOne()
+ * @param {object=} args.embedOpts      optional embedOne overrides
+ *
+ * @returns {{
+ *   contextNote: string,
+ *   trace: {
+ *     enabled: boolean,
+ *     reason?: string,
+ *     embedder?: string,
+ *     scored?: Array<{slug, sim}>,
+ *     loaded?: string[],
+ *     hinted?: string[],
+ *   }
+ * }}
+ */
+export async function inspectPromptForSkills({ prompt, projectPath, globalConfig, embedOpts } = {}) {
+  const cfg = effectiveConfig(globalConfig);
+  if (!cfg.enabled) {
+    return { contextNote: "", trace: { enabled: false, reason: "disabled" } };
+  }
+
+  const text = String(prompt || "").trim();
+  if (text.length < cfg.prompt_floor) {
+    return { contextNote: "", trace: { enabled: true, reason: "prompt_too_short" } };
+  }
+
+  // Self-heal: if a skill was added/edited/removed since the last index, kick a
+  // background rebuild. Non-blocking — this turn uses whatever is already on
+  // disk; the next turn picks up the fresh vectors. This is what lets a user
+  // drop a SKILL.md and have it "just work" without running `apx skills index`.
+  try {
+    backgroundRefreshIfStale({ projectPath, embedOpts: { ...(embedOpts || {}), globalConfig } });
+  } catch { /* best-effort */ }
+
+  // Pull the persistent index. If it's empty (no `apx skills index` ever ran),
+  // we don't fall back to recomputing every skill's vector here — that's the
+  // job of the index command and the daemon startup probe. Instead, we emit a
+  // trace reason so the operator sees "you forgot to index".
+  const idx = readIndex();
+  const items = idx.items || {};
+  const indexedCount = Object.keys(items).length;
+
+  // If the on-disk index has nothing yet, try a JIT pass over the live catalog
+  // using the in-process cache. Slower than a primed index but means a fresh
+  // install still works — the inspector is supposed to "just work" the moment
+  // it's flipped on.
+  if (indexedCount === 0) {
+    return await inspectFromLive({ text, projectPath, cfg, globalConfig, embedOpts });
+  }
+
+  const probe = await embedOne(text, { ...(embedOpts || {}), globalConfig });
+  if (!probe || !Array.isArray(probe.vector) || probe.vector.length === 0) {
+    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`.
+  if (idx.embedder && idx.embedder !== probe.embedder) {
+    return {
+      contextNote: "",
+      trace: {
+        enabled: true,
+        reason: "embedder_mismatch",
+        embedder: probe.embedder,
+        index_embedder: idx.embedder,
+      },
+    };
+  }
+
+  const scored = scoreAgainstIndex(probe.vector, items);
+  return await pickAndRender({ scored, projectPath, probe, cfg });
+}
+
+// ---------------------------------------------------------------------------
+// JIT fallback when the persistent index is empty
+// ---------------------------------------------------------------------------
+
+async function inspectFromLive({ text, projectPath, cfg, globalConfig, embedOpts }) {
+  const skills = listSkills({ projectPath });
+  if (!skills.length) {
+    return { contextNote: "", trace: { enabled: true, reason: "no_skills" } };
+  }
+
+  const probe = await embedOne(text, { ...(embedOpts || {}), globalConfig });
+  if (!probe || !Array.isArray(probe.vector) || probe.vector.length === 0) {
+    return { contextNote: "", trace: { enabled: true, reason: "embed_failed" } };
+  }
+
+  const scored = [];
+  for (const s of skills) {
+    const desc = (s.description || "").slice(0, 600);
+    if (!desc.trim()) continue;
+    const out = await embedOne(desc, { ...(embedOpts || {}), globalConfig });
+    if (!out || !Array.isArray(out.vector)) continue;
+    scored.push({
+      slug: s.slug,
+      source: s.source,
+      desc,
+      file: s.file,
+      sim: cosineSim(probe.vector, out.vector),
+    });
+  }
+  scored.sort((a, b) => b.sim - a.sim);
+  const result = await pickAndRender({ scored, projectPath, probe, cfg });
+  return {
+    contextNote: result.contextNote,
+    trace: { ...result.trace, jit: true },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Common pick + render
+// ---------------------------------------------------------------------------
+
+async function pickAndRender({ scored, projectPath, probe, cfg }) {
+  if (scored.length === 0) {
+    return { contextNote: "", trace: { enabled: true, reason: "no_candidates", embedder: probe.embedder } };
+  }
+  const top = scored[0];
+  const runner = scored[1] || { sim: 0 };
+
+  if (top.sim < cfg.hint_threshold) {
+    return {
+      contextNote: "",
+      trace: {
+        enabled: true,
+        reason: "below_threshold",
+        embedder: probe.embedder,
+        scored: scored.slice(0, 5).map((s) => ({ slug: s.slug, sim: Number(s.sim.toFixed(3)) })),
+      },
+    };
+  }
+
+  const loaded = [];
+  const hinted = [];
+
+  // High-confidence top picks → inline body. Bounded by max_loaded and require
+  // a margin over the runner-up so a flat tie of weak matches doesn't bloat
+  // the prompt.
+  if (top.sim >= cfg.load_threshold && top.sim - runner.sim >= cfg.margin) {
+    for (let i = 0; i < scored.length && loaded.length < cfg.max_loaded; i++) {
+      const cand = scored[i];
+      if (cand.sim < cfg.load_threshold) break;
+      const body = readBodyCapped(cand.slug, projectPath, cfg.body_char_cap);
+      if (!body) continue;
+      loaded.push({ ...cand, body });
+    }
+  }
+
+  // Mid-confidence remainder → hint.
+  for (const cand of scored) {
+    if (loaded.some((l) => l.slug === cand.slug)) continue;
+    if (hinted.length >= cfg.max_hints) break;
+    if (cand.sim < cfg.hint_threshold) break;
+    hinted.push(cand);
+  }
+
+  const contextNote = renderInjectedBlock({ loaded, hinted, embedder: probe.embedder });
+  return {
+    contextNote,
+    trace: {
+      enabled: true,
+      embedder: probe.embedder,
+      scored: scored.slice(0, 5).map((s) => ({ slug: s.slug, sim: Number(s.sim.toFixed(3)) })),
+      loaded: loaded.map((l) => l.slug),
+      hinted: hinted.map((h) => h.slug),
+    },
+  };
+}
+
+function readBodyCapped(slug, projectPath, cap) {
+  try {
+    const { body } = loadSkill(slug, { projectPath });
+    if (!body) return "";
+    if (body.length <= cap) return body;
+    return body.slice(0, cap) + "\n\n…(skill body truncated — call load_skill for the full text)";
+  } catch {
+    return "";
+  }
+}
+
+// Small helper used by the CLI inspect command to print why something fell out.
+export function summarizeTrace(trace) {
+  if (!trace) return "(no trace)";
+  if (!trace.enabled) return `inspector disabled (${trace.reason || "off"})`;
+  if (trace.reason && !trace.loaded && !trace.hinted) {
+    return `no skill injected: ${trace.reason}`;
+  }
+  const parts = [];
+  if (trace.loaded?.length) parts.push(`loaded: ${trace.loaded.join(", ")}`);
+  if (trace.hinted?.length) parts.push(`hinted: ${trace.hinted.join(", ")}`);
+  if (!parts.length) parts.push("nothing injected");
+  return parts.join(" · ");
+}
+
+// Re-exported for callers that want to introspect.
+export { readIndex };

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

@@ -10,15 +10,19 @@
 //   1. <projectPath>/.apc/skills/<slug>.md           ← project-scoped (flat)
 //   1b.<projectPath>/.apc/skills/<slug>/SKILL.md     ← project-scoped (dir)
 //   2. ~/.apx/skills/<slug>/SKILL.md                 ← user-installed global
-//   3. <packageRoot>/skills/<slug>/SKILL.md          ← bundled core skills
-//                                                     (apx, apc-context)
-//   4. <packageRoot>/src/core/runtime-skills/<slug>.md
-//                                                     (claude-code, codex-cli,
-//                                                      opencode-cli, openrouter)
+//   3. <packageRoot>/src/core/runtime-skills/<slug>/SKILL.md
+//                                                     ← runtime-internal set
+//                                                       (rich apx-*, apc-context,
+//                                                       claude-code, codex-cli,
+//                                                       opencode-cli, openrouter)
 //
-// A slug found in a higher-priority location SHADOWS lower ones. A user can
-// override the bundled apc-context by dropping `~/.apx/skills/apc-context/SKILL.md`,
-// but the bundled copy stays in the package as a safety net.
+// A slug found in a higher-priority location SHADOWS lower ones. The user can
+// override any runtime skill by dropping `~/.apx/skills/<slug>/SKILL.md`; the
+// in-repo copy stays as a safety net.
+//
+// NOTE: <packageRoot>/skills/<slug>/SKILL.md is intentionally NOT in this chain.
+// That dir holds the engine-side slim set replicated to external CLIs/IDEs
+// (~/.claude/skills/, ~/.codex/skills/, ...) — it's not for the super-agent.
 //
 // Note: the bundled `apc-context` skill is REFRESHED from the canonical apc
 // repo on every npm install / update (see src/interfaces/cli/postinstall.js). APC is a
@@ -28,6 +32,7 @@ import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
 import { fileURLToPath } from "node:url";
+import { apcSkillsDir } from "#core/apc/paths.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname  = path.dirname(__filename);
@@ -35,8 +40,10 @@ const __dirname  = path.dirname(__filename);
 // → repo root. Used to find the bundled skills/ folder at the repo root.
 const PACKAGE_ROOT = path.resolve(__dirname, "..", "..", "..", "..");
 
-const RUNTIME_SKILLS_DIR = path.join(PACKAGE_ROOT, "src", "core", "runtime-skills");
-const BUNDLED_SKILLS_DIR = path.join(PACKAGE_ROOT, "skills");
+// Runtime-internal skills — full apx-* catalog + CLI docs. Lives outside
+// <packageRoot>/skills/ so external tools that copy "skills/" from the repo
+// don't accidentally pull the rich set or the runtime CLI docs.
+const BUILTIN_SKILLS_DIR = path.join(PACKAGE_ROOT, "src", "core", "runtime-skills");
 const GLOBAL_DIR         = path.join(os.homedir(), ".apx", "skills");
 
 // ---------------------------------------------------------------------------
@@ -119,7 +126,7 @@ export function listSkills({ projectPath } = {}) {
 
   // priority 1: project-scoped
   if (projectPath) {
-    const apcSkills = path.join(projectPath, ".apc", "skills");
+    const apcSkills = apcSkillsDir(projectPath);
     found.push(...scanDirStyle(apcSkills, "project"));
     found.push(...scanFlatStyle(apcSkills, "project"));
   }
@@ -127,11 +134,9 @@ export function listSkills({ projectPath } = {}) {
   // priority 2: user-installed global
   found.push(...scanDirStyle(GLOBAL_DIR, "global"));
 
-  // priority 3: bundled core skills (apx, apc-context)
-  found.push(...scanDirStyle(BUNDLED_SKILLS_DIR, "builtin"));
-
-  // priority 4: runtime docs (claude-code, codex-cli, opencode-cli, openrouter)
-  found.push(...scanFlatStyle(RUNTIME_SKILLS_DIR, "builtin"));
+  // priority 3: runtime-internal builtin set
+  // (rich apx-*, apc-context, plus claude-code, codex-cli, opencode-cli, openrouter)
+  found.push(...scanDirStyle(BUILTIN_SKILLS_DIR, "builtin"));
 
   // dedupe by slug (first-wins = higher priority shadows lower)
   const seen = new Set();
@@ -189,7 +194,6 @@ export function loadSkill(slug, { projectPath } = {}) {
 
 // Useful for diagnostics
 export const SKILL_LOCATIONS = {
-  runtime_skills: RUNTIME_SKILLS_DIR,
-  bundled: BUNDLED_SKILLS_DIR,
+  builtin: BUILTIN_SKILLS_DIR,
   global: GLOBAL_DIR,
 };

package/src/core/agent/stream/turn-accumulator.js

@@ -0,0 +1,73 @@
+// Accumulate super-agent stream events into the rich ChatPart shape so a
+// persisted assistant turn matches exactly what the UI rendered live.
+// Mirrors the front-end reducer in hooks/useChat.ts (applyStreamEvent) — keep
+// the two in sync if you add a new event type.
+//
+// Pure: no I/O, no globals. Caller drives it event-by-event and finally calls
+// build() to snapshot the resulting parts/notes/model/usage.
+export function makeTurnAccumulator() {
+  const parts = [];
+  const notes = [];
+  let model = null;
+  let usage = null;
+  const findTool = (id) => parts.find((p) => p.kind === "tool" && p.id === id);
+  return {
+    apply(ev) {
+      switch (ev?.type) {
+        case "model_start":
+          if (ev.model) model = ev.model;
+          break;
+        case "model_routed":
+          if (ev.model) model = ev.model;
+          if (ev.from_fallback) notes.push(`routing fell back → ${ev.model}`);
+          break;
+        case "engine_failed":
+          notes.push(`engine ${ev.model || "?"} failed → ${ev.retry_with || "retry"}`);
+          break;
+        case "model_retry":
+          notes.push(`retry (${ev.reason || "?"})`);
+          break;
+        case "tools_suppressed":
+          notes.push(`tools suppressed: ${(ev.tools || []).join(", ")}`);
+          break;
+        case "assistant_text":
+          if (ev.text) parts.push({ kind: "text", text: ev.text });
+          break;
+        case "tool_start":
+          if (ev.trace)
+            parts.push({
+              kind: "tool",
+              id: ev.trace.id,
+              tool: ev.trace.tool,
+              args: ev.trace.args,
+              status: "running",
+            });
+          break;
+        case "tool_deduped": {
+          const t = ev.trace && findTool(ev.trace.id);
+          if (t) t.status = "deduped";
+          break;
+        }
+        case "tool_result": {
+          const t = ev.trace && findTool(ev.trace.id);
+          if (t) {
+            t.result = ev.trace.result;
+            const errored =
+              ev.trace.result && typeof ev.trace.result === "object" && ev.trace.result.error;
+            t.status = errored ? "error" : t.status === "deduped" ? "deduped" : "done";
+          }
+          break;
+        }
+        case "final":
+          usage = ev.result?.usage ?? usage;
+          if (!model) model = ev.result?.name || null;
+          break;
+        default:
+          break;
+      }
+    },
+    build() {
+      return { parts, notes, model, usage };
+    },
+  };
+}

package/src/core/agent/suggestions.js

@@ -0,0 +1,37 @@
+// Parse the trailing ```suggestions JSON``` block out of an agent reply.
+// Surfaces like the deck/desktop render the JSON as chips; the visible reply
+// should be stripped of the fenced block so the user (and TTS) never sees it.
+//
+// Pure: just regex + JSON.parse. Malformed JSON drops suggestions silently
+// rather than failing the turn — better UX to show the reply without chips
+// than an error.
+const SUGGESTIONS_BLOCK_RE = /\n*```\s*suggestions\s*\n([\s\S]*?)\n?```\s*$/i;
+
+const MAX_SUGGESTIONS = 4;
+const MAX_LABEL_LEN = 48;
+const MAX_COMMAND_LEN = 96;
+
+export function extractSuggestions(text) {
+  if (typeof text !== "string" || !text) {
+    return { cleanText: text || "", suggestions: [] };
+  }
+  const m = SUGGESTIONS_BLOCK_RE.exec(text);
+  if (!m) return { cleanText: text, suggestions: [] };
+  const cleanText = text.slice(0, m.index).trim();
+  let suggestions = [];
+  try {
+    const parsed = JSON.parse(m[1]);
+    if (Array.isArray(parsed)) {
+      suggestions = parsed
+        .filter((s) => s && typeof s === "object" && typeof s.label === "string")
+        .slice(0, MAX_SUGGESTIONS)
+        .map((s) => ({
+          label: String(s.label).slice(0, MAX_LABEL_LEN),
+          ...(typeof s.command === "string" ? { command: s.command.slice(0, MAX_COMMAND_LEN) } : {}),
+        }));
+    }
+  } catch {
+    // Malformed JSON — drop silently.
+  }
+  return { cleanText, suggestions };
+}

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

@@ -10,6 +10,7 @@ import {
 } from "#core/agent/index.js";
 import { resolveAgentName } from "#core/identity/index.js";
 import { memoryBlockFor } from "#core/memory/index.js";
+import { CHANNELS } from "#core/constants/channels.js";
 
 export {
   buildIdentityBlock,
@@ -58,6 +59,10 @@ export async function runSuperAgent({
   // Null disables human-in-the-loop (tools that need confirmation fail
   // immediately instead of waiting for user input).
   requestConfirmation = null,
+  // When true, suppress the static "Available skills" slug-dump hint block
+  // because a per-turn skill inspector already injected the right context.
+  // Set by the daemon's super-agent endpoint when config.skills.inspector is on.
+  skipSkillsHint = false,
 }) {
   if (!isSuperAgentEnabled(globalConfig)) {
     throw new Error("super-agent not enabled (set super_agent.enabled and .model in ~/.apx/config.json)");
@@ -74,7 +79,7 @@ export async function runSuperAgent({
     memoryBlock = await memoryBlockFor(prompt, { config: globalConfig, channel });
     // "Hilos activos en otros canales" — pure-recency cross-channel awareness.
     // Skipped for autonomous routines (no human to reference other threads).
-    if (channel !== "routine") {
+    if (channel !== CHANNELS.ROUTINE) {
       try {
         activeThreadsBlock = buildActiveThreadsBlock(channel, { config: globalConfig });
       } catch {
@@ -106,6 +111,7 @@ export async function runSuperAgent({
     // Compact "tools you can activate" block (names only, no schemas). Empty on
     // full channels and tool-free callers, where it's omitted from the prompt.
     lazyToolsBlock: buildLazyToolsBlock(toolSession),
+    skipSkillsHint,
   });
 
   const toolSchemas = noTools ? [] : toolSession.initialSchemas;

package/src/core/agent/tools/handlers/_git.js

@@ -0,0 +1,50 @@
+// Shared git spawn helper. Resolves the working directory from the same
+// project/cwd contract every other shell-aware tool uses (resolveProject),
+// then runs `git <args...>` with no shell so paths with spaces are safe.
+import { spawn } from "node:child_process";
+import { resolveProject } from "../helpers.js";
+
+const DEFAULT_TIMEOUT_MS = 15_000;
+const MAX_OUTPUT_CHARS = 60_000; // ~15K tokens — generous for diffs, cuts runaways
+
+export function runGit(args, { cwd, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  return new Promise((resolve) => {
+    const child = spawn("git", args, { cwd, env: process.env });
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGTERM");
+    }, timeoutMs);
+    child.stdout.on("data", (d) => { stdout += d.toString(); });
+    child.stderr.on("data", (d) => { stderr += d.toString(); });
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      resolve({ ok: false, error: err.message });
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      const truncated = stdout.length > MAX_OUTPUT_CHARS;
+      if (truncated) stdout = stdout.slice(0, MAX_OUTPUT_CHARS) + "\n…(output truncated)";
+      resolve({
+        ok: code === 0,
+        code,
+        stdout,
+        stderr: stderr.trim() || null,
+        timedOut,
+        truncated,
+      });
+    });
+  });
+}
+
+/** Resolve the working directory for a git tool from the standard tool args. */
+export function resolveGitCwd(ctx, { project, cwd }) {
+  // 1) If `cwd` was passed, use it directly (advanced override).
+  if (cwd) return cwd;
+  // 2) Otherwise resolve `project` (id, name, or path) → project root.
+  const proj = resolveProject(ctx.projects, project);
+  if (!proj) throw new Error("git: no project resolved (pass project or cwd)");
+  return proj.path;
+}

package/src/core/agent/tools/handlers/add-project.js

@@ -2,12 +2,15 @@ import fs from "node:fs";
 import path from "node:path";
 import { readConfig, addProject as addProjectInConfig } from "#core/config/index.js";
 import { initApf } from "#core/apc/scaffold.js";
+import { agentsMdFile, apcProjectFile } from "#core/apc/paths.js";
 import { projectMeta } from "../helpers.js";
 
+// Stricter than core/apc/paths.js::isApcProject — `add_project` also requires
+// AGENTS.md at the root, matching the gate that config.addProject() enforces.
 function isApcProject(absPath) {
   return (
-    fs.existsSync(path.join(absPath, "AGENTS.md")) &&
-    fs.existsSync(path.join(absPath, ".apc", "project.json"))
+    fs.existsSync(agentsMdFile(absPath)) &&
+    fs.existsSync(apcProjectFile(absPath))
   );
 }
 

package/src/core/agent/tools/handlers/call-runtime.js

@@ -2,13 +2,14 @@ import fs from "node:fs";
 import path from "node:path";
 import { loggerFor } from "#core/logging.js";
 import { readAgents } from "#core/apc/parser.js";
+import { apcProjectFile } from "#core/apc/paths.js";
 import {
   closeRuntimeSession,
   createRuntimeSession,
   extractRuntimeResult as extractApfResult,
 } from "#core/stores/runtime-sessions.js";
 import { buildRuntimeBridgeHint as buildApfHint } from "#core/agent/runtime-bridge.js";
-import { detectAll } from "#host/daemon/env-detect.js";
+import { detectAll } from "#core/runtimes/detect.js";
 import {
   findEngineSessionById,
   readEngineSessionContext,
@@ -88,7 +89,7 @@ function resolveProjectForAgent(projects, project, slug) {
 
 function projectName(project) {
   try {
-    const meta = JSON.parse(fs.readFileSync(path.join(project.path, ".apc", "project.json"), "utf8"));
+    const meta = JSON.parse(fs.readFileSync(apcProjectFile(project.path), "utf8"));
     if (meta.name) return meta.name;
   } catch {}
   return path.basename(project.path);