@agentprojectcontext/apx 1.69.0 → 1.71.0

package/src/core/integrations/plugins/obsidian.js

@@ -0,0 +1,339 @@
+// Obsidian integration plugin — the "credential" is a local Vault (a directory
+// of Markdown notes), not a remote API token. Unlike Asana/GitHub there is no
+// provider to call: the plugin's config is a filesystem `vault_path` plus a
+// couple of toggles. This same module doubles as a pure vault client that the
+// agent tools (obsidian-*.js) call to read/search/write notes directly on disk
+// — no external process, works offline, fully under APX's control.
+//
+// Two extra hooks beyond the standard lifecycle contract:
+//   - mcpServer(record): the generic MCP-reconcile hook the daemon uses to
+//     auto-register (opt-in) a community Obsidian MCP pointing at the vault.
+//   - actions.sync_memory(record, ctx): mirrors APX memory into the vault.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+// ─── path helpers ───────────────────────────────────────────────────────────
+
+// Expand a leading `~` to the user's home dir (Obsidian users type paths by hand).
+export function expandHome(p) {
+  const s = String(p || "");
+  if (s === "~") return os.homedir();
+  if (s.startsWith("~/") || s.startsWith("~\\")) return path.join(os.homedir(), s.slice(2));
+  return s;
+}
+
+// Turn a user-supplied vault path into a resolved absolute path.
+export function resolveVaultPath(raw) {
+  const expanded = expandHome(String(raw || "").trim());
+  if (!expanded) throw new Error("Vault path is empty");
+  return path.resolve(expanded);
+}
+
+// A directory is a "real" Obsidian vault when it holds a `.obsidian` config
+// folder. We don't require it — a plain folder of markdown works too — but we
+// report it so the UI can confirm the pick.
+export function isObsidianVault(vaultPath) {
+  try {
+    return fs.statSync(path.join(vaultPath, ".obsidian")).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+// Throw unless `vaultPath` points at an existing directory.
+export function assertVaultDir(vaultPath) {
+  let st;
+  try {
+    st = fs.statSync(vaultPath);
+  } catch {
+    throw new Error(`Vault path does not exist: ${vaultPath}`);
+  }
+  if (!st.isDirectory()) throw new Error(`Vault path is not a directory: ${vaultPath}`);
+  return true;
+}
+
+// Append `entry` to <root>/.gitignore unless already present. Idempotent.
+function ensureGitignore(root, entry) {
+  const gi = path.join(root, ".gitignore");
+  let text = "";
+  try {
+    text = fs.readFileSync(gi, "utf8");
+  } catch {
+    /* no .gitignore yet */
+  }
+  const bare = entry.replace(/\/$/, "");
+  const present = text.split("\n").some((l) => {
+    const t = l.trim();
+    return t === entry || t === bare;
+  });
+  if (present) return false;
+  const prefix = text && !text.endsWith("\n") ? `${text}\n` : text;
+  fs.writeFileSync(gi, `${prefix}${entry}\n`);
+  return true;
+}
+
+// Turn a project folder into an Obsidian vault so "the project IS the vault":
+// create a minimal `.obsidian/` config (makes the app recognize it) and
+// gitignore that config so per-machine vault settings never land in the repo.
+// Idempotent — safe to call on every activation. Returns { created, gitignored }.
+// NOTE: building block for auto-vault-on-activate — not yet wired into the
+// plugin lifecycle (that changes the configure contract + writes into repos;
+// pending an explicit product call on global-vs-per-project).
+export function ensureProjectVault(projectRoot) {
+  const root = path.resolve(projectRoot);
+  assertVaultDir(root);
+  const dot = path.join(root, ".obsidian");
+  let created = false;
+  if (!fs.existsSync(dot)) {
+    fs.mkdirSync(dot, { recursive: true });
+    fs.writeFileSync(path.join(dot, "app.json"), "{}\n");
+    created = true;
+  }
+  return { created, gitignored: ensureGitignore(root, ".obsidian/") };
+}
+
+// Normalize a user-supplied note reference to an absolute `.md` path inside the
+// vault, refusing anything that escapes the vault root (path-traversal guard).
+function noteAbs(vaultPath, note) {
+  let rel = String(note || "").trim();
+  if (!rel) throw new Error("Note path is required");
+  rel = rel.replace(/\\/g, "/").replace(/^\/+/, "");
+  if (!/\.md$/i.test(rel)) rel += ".md";
+  const root = path.resolve(vaultPath);
+  const abs = path.resolve(root, rel);
+  if (abs !== root && !abs.startsWith(root + path.sep)) {
+    throw new Error(`Note path escapes the vault: ${note}`);
+  }
+  return abs;
+}
+
+// ─── vault client (used by the agent tools) ─────────────────────────────────
+
+// Recursively list markdown notes as vault-relative POSIX paths. Skips dotfiles
+// and dot-dirs (`.obsidian`, `.trash`, …).
+export function listNotes(vaultPath, { limit = 1000 } = {}) {
+  assertVaultDir(vaultPath);
+  const root = path.resolve(vaultPath);
+  const out = [];
+  const walk = (dir) => {
+    if (out.length >= limit) return;
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (out.length >= limit) return;
+      if (e.name.startsWith(".")) continue;
+      const abs = path.join(dir, e.name);
+      if (e.isDirectory()) walk(abs);
+      else if (/\.md$/i.test(e.name)) out.push(path.relative(root, abs).split(path.sep).join("/"));
+    }
+  };
+  walk(root);
+  out.sort();
+  return out;
+}
+
+export function readNote(vaultPath, note) {
+  assertVaultDir(vaultPath);
+  const abs = noteAbs(vaultPath, note);
+  if (!fs.existsSync(abs)) throw new Error(`Note not found: ${note}`);
+  return fs.readFileSync(abs, "utf8");
+}
+
+// Create or update a note. `mode`: "overwrite" (default) | "append".
+export function writeNote(vaultPath, note, content, { mode = "overwrite" } = {}) {
+  assertVaultDir(vaultPath);
+  const abs = noteAbs(vaultPath, note);
+  const body = String(content ?? "");
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  if (mode === "append" && fs.existsSync(abs)) {
+    const prev = fs.readFileSync(abs, "utf8");
+    fs.writeFileSync(abs, prev + (prev.endsWith("\n") ? "" : "\n") + body);
+  } else {
+    fs.writeFileSync(abs, body);
+  }
+  const root = path.resolve(vaultPath);
+  return {
+    note: path.relative(root, abs).split(path.sep).join("/"),
+    bytes: Buffer.byteLength(body),
+    mode,
+  };
+}
+
+// Dependency-free substring search across note bodies + filenames. Returns a
+// short context snippet per hit.
+export function searchNotes(vaultPath, query, { limit = 50, caseSensitive = false } = {}) {
+  assertVaultDir(vaultPath);
+  const q = String(query || "").trim();
+  if (!q) throw new Error("Search query is required");
+  const needle = caseSensitive ? q : q.toLowerCase();
+  const notes = listNotes(vaultPath, { limit: 10000 });
+  const results = [];
+  for (const rel of notes) {
+    if (results.length >= limit) break;
+    let body;
+    try {
+      body = fs.readFileSync(path.join(vaultPath, rel), "utf8");
+    } catch {
+      continue;
+    }
+    const hay = caseSensitive ? body : body.toLowerCase();
+    const nameHit = (caseSensitive ? rel : rel.toLowerCase()).includes(needle);
+    const idx = hay.indexOf(needle);
+    if (idx === -1 && !nameHit) continue;
+    let snippet = "";
+    if (idx !== -1) {
+      const start = Math.max(0, idx - 40);
+      const end = Math.min(body.length, idx + needle.length + 40);
+      snippet =
+        (start > 0 ? "…" : "") +
+        body.slice(start, end).replace(/\s+/g, " ").trim() +
+        (end < body.length ? "…" : "");
+    }
+    results.push({ note: rel, snippet, title_match: nameHit });
+  }
+  return results;
+}
+
+// ─── plugin descriptor + lifecycle ──────────────────────────────────────────
+
+function asBool(v, fallback) {
+  if (v === undefined || v === null) return fallback;
+  return v === true || v === "true" || v === "on" || v === 1 || v === "1";
+}
+
+export const obsidianPlugin = {
+  slug: "obsidian",
+  name: "Obsidian",
+  type: "knowledge",
+  description:
+    "Conectá un Vault de Obsidian para que los agentes lean, busquen y escriban notas",
+  auth: "path",
+  tools: [
+    { slug: "obsidian_search_notes", desc: "Buscar notas en el Vault" },
+    { slug: "obsidian_read_note", desc: "Leer una nota" },
+    { slug: "obsidian_write_note", desc: "Crear o actualizar una nota" },
+    { slug: "obsidian_list_notes", desc: "Listar notas del Vault" },
+  ],
+  // Structure only — display text lives in web i18n (integrations.obsidian.*).
+  ui: {
+    accent: "purple",
+    configFields: [
+      { key: "vault_path", type: "path", placeholder: "/Users/tu-usuario/Obsidian/MiVault" },
+      { key: "auto_mcp", type: "toggle", default: false },
+      { key: "memory_sync", type: "toggle", default: false },
+    ],
+    connectedFields: ["vault_path", "vault_name", "note_count"],
+    // Buttons shown in the connected view (label from i18n).
+    actions: [{ action: "sync_memory" }],
+  },
+
+  configure(record, body = {}) {
+    const rawPath = String(body.vault_path ?? record?.config?.vault_path ?? "").trim();
+    if (!rawPath) throw new Error("Provide the path to your Obsidian vault");
+    const config = {
+      vault_path: rawPath,
+      auto_mcp: asBool(body.auto_mcp, record?.config?.auto_mcp ?? false),
+      memory_sync: asBool(body.memory_sync, record?.config?.memory_sync ?? false),
+    };
+    return {
+      patch: {
+        name: this.name,
+        type: this.type,
+        description: this.description,
+        status: "pending_validation",
+        config,
+      },
+    };
+  },
+
+  async validate(record) {
+    const config = record?.config || {};
+    let vaultPath;
+    try {
+      vaultPath = resolveVaultPath(config.vault_path);
+      assertVaultDir(vaultPath);
+    } catch (e) {
+      return {
+        patch: { status: "error", is_enabled: false, config: { last_error: String(e.message || e) } },
+        result: { ok: false, error: String(e.message || e) },
+      };
+    }
+    const isVault = isObsidianVault(vaultPath);
+    const noteCount = listNotes(vaultPath, { limit: 10000 }).length;
+    const vaultName = path.basename(vaultPath);
+    // Persist the resolved absolute path so downstream consumers (tools, MCP,
+    // sync) never re-expand `~`.
+    return {
+      patch: {
+        status: "active",
+        is_enabled: true,
+        config: {
+          vault_path: vaultPath,
+          vault_name: vaultName,
+          is_vault: isVault,
+          note_count: noteCount,
+          last_error: null,
+        },
+      },
+      result: { ok: true, vault_path: vaultPath, vault_name: vaultName, is_vault: isVault, note_count: noteCount },
+    };
+  },
+
+  status(record) {
+    const c = record?.config || {};
+    return {
+      slug: this.slug,
+      status: record?.status || "disconnected",
+      is_enabled: !!record?.is_enabled,
+      vault_path: c.vault_path || null,
+      vault_name: c.vault_name || null,
+      note_count: c.note_count ?? null,
+      is_vault: c.is_vault ?? null,
+      auto_mcp: !!c.auto_mcp,
+      memory_sync: !!c.memory_sync,
+    };
+  },
+
+  deactivate() {
+    return { patch: { status: "inactive", is_enabled: false } };
+  },
+
+  // Generic MCP-reconcile hook (see host/daemon/api/integrations.js). Returns
+  // the desired `{ name, def }` for a community Obsidian MCP when the vault is
+  // active AND the user opted into `auto_mcp`; otherwise `def: null` so the
+  // reconcile removes any stale server. Command/args overridable via config.
+  mcpServer(record) {
+    const c = record?.config || {};
+    const active = record?.status === "active" && !!record?.is_enabled && !!c.auto_mcp && !!c.vault_path;
+    if (!active) return { name: "obsidian", def: null };
+    const command = c.mcp_command || "npx";
+    const args =
+      Array.isArray(c.mcp_args) && c.mcp_args.length ? c.mcp_args : ["-y", "obsidian-mcp", c.vault_path];
+    return { name: "obsidian", def: { command, args, enabled: true } };
+  },
+
+  actions: {
+    // Quick connectivity probe (web refresh / smoke test): list a few notes.
+    async notes(record) {
+      const vaultPath = resolveVaultPath(record?.config?.vault_path);
+      const notes = listNotes(vaultPath, { limit: 25 });
+      return { notes, count: listNotes(vaultPath, { limit: 10000 }).length, sample: notes };
+    },
+    // Mirror APX memory into the vault. Needs project context (all projects +
+    // the current one), passed as the 2nd arg by the daemon action dispatch.
+    async sync_memory(record, ctx = {}) {
+      const vaultPath = resolveVaultPath(record?.config?.vault_path);
+      const folder = record?.config?.memory_folder || "APX";
+      const { syncMemoryToVault, collectMemorySources } = await import("../obsidian-memory.js");
+      const sources = collectMemorySources(ctx);
+      return syncMemoryToVault({ vaultPath, folder, sources });
+    },
+  },
+};
+
+export default obsidianPlugin;

package/src/core/mcp/runner.js

@@ -18,6 +18,20 @@ function nowIso() {
   return new Date().toISOString();
 }
 
+// Serializes cold-starts that share an npm/npx cache dir. Two MCP processes
+// with the same command+args but different env — e.g. the same
+// `npx @ahdev/dokploy-mcp@1.6.0` registered in two projects pointing at
+// different DOKPLOY_URLs — resolve to ONE shared npm cache dir
+// (~/.npm/_npx/<hash>). npm does not guard that dir against concurrent writes,
+// so overlapping cold-starts corrupt it (ENOTEMPTY / partial node_modules) and
+// the server dies on start, which respawns and corrupts it again. Chaining
+// start-ups by spec keeps the cache-touching phase from ever overlapping.
+const startGates = new Map(); // spec key -> promise resolved when current starter finishes
+
+function startKey(command, args) {
+  return JSON.stringify([command, args || []]);
+}
+
 class McpProcess {
   constructor({ name, command, args = [], env = {} }) {
     this.name = name;
@@ -127,30 +141,50 @@ class McpProcess {
   async _ensureInitialized() {
     if (this._initialized) return;
     if (!this._initPromise) {
-      this._initPromise = (async () => {
-        await this._send(
-          "initialize",
-          {
-            protocolVersion: "2024-11-05",
-            capabilities: {},
-            clientInfo: { name: "apx-daemon", version: "0.1.0" },
-          },
-          10_000
-        );
-        try {
-          this.proc.stdin.write(
-            JSON.stringify({
-              jsonrpc: "2.0",
-              method: "notifications/initialized",
-            }) + "\n"
-          );
-        } catch {}
-        this._initialized = true;
-      })();
+      this._initPromise = this._gatedInit();
     }
     return this._initPromise;
   }
 
+  // Acquire the per-spec start gate around the whole (spawn + npm cache work +
+  // JSON-RPC initialize) sequence so processes sharing an npx cache never
+  // cold-start concurrently. See startGates.
+  async _gatedInit() {
+    const key = startKey(this.command, this.args);
+    const prev = startGates.get(key) || Promise.resolve();
+    let release;
+    const gate = new Promise((r) => (release = r));
+    // The next starter of this spec waits on us — whether we succeed or fail.
+    startGates.set(key, prev.then(() => gate, () => gate));
+    try {
+      await prev.catch(() => {});
+      await this._doInitialize();
+    } finally {
+      release();
+    }
+  }
+
+  async _doInitialize() {
+    await this._send(
+      "initialize",
+      {
+        protocolVersion: "2024-11-05",
+        capabilities: {},
+        clientInfo: { name: "apx-daemon", version: "0.1.0" },
+      },
+      10_000
+    );
+    try {
+      this.proc.stdin.write(
+        JSON.stringify({
+          jsonrpc: "2.0",
+          method: "notifications/initialized",
+        }) + "\n"
+      );
+    } catch {}
+    this._initialized = true;
+  }
+
   async listTools() {
     await this._ensureInitialized();
     return collectToolPages((cursor) =>

package/src/core/memory/broker.js

@@ -87,10 +87,18 @@ export async function buildMemoryBlock(message, opts = {}) {
   const budgetMs = opts.budgetMs || DEFAULT_BUDGET_MS;
   const topK = opts.topK || DEFAULT_TOP_K;
   const store = opts.store || null;
+  // Scope isolation: the super-agent recalls only global rows ("global"), a
+  // project/agent turn recalls only its own — a single channel or an array of
+  // channels (["agent:…","project:…"]).
+  const scope = opts.scope || "global";
+  // The flat notebook slice is always included for the super-agent, but a
+  // project-agent turn already gets its own memory.md injected elsewhere, so it
+  // opts out (includeFlat:false) to keep this block RAG-only.
+  const includeFlat = opts.includeFlat !== false;
   const query = clean(message);
 
   // memory.md entries are read synchronously and always make the deadline.
-  const memEntries = lastMemoryEntries(memoryPath, 10);
+  const memEntries = includeFlat ? lastMemoryEntries(memoryPath, 10) : [];
 
   // RAG retrieval is the slow part — race it against the budget.
   let hits = [];
@@ -99,7 +107,7 @@ export async function buildMemoryBlock(message, opts = {}) {
       const { vector, embedder, dim } = await embedOne(query, opts.embed || {});
       const family = embedder.startsWith("ollama") ? "ollama" : "tf";
       const floor = MIN_SCORE[family] ?? 0;
-      const results = store.search(vector, { embedder, k: topK + 3 });
+      const results = store.search(vector, { embedder, k: topK + 3, scope });
       return results.filter((r) => r.score >= floor && (r.dim ?? dim) === dim);
     })();
     hits = await withTimeout(rag, budgetMs, []);
@@ -132,7 +140,7 @@ export async function buildMemoryBlock(message, opts = {}) {
   if (bullets.length === 0) return "";
 
   return [
-    "# Relevant memory (cross-channel)",
+    `# ${opts.heading || "Relevant memory (cross-channel)"}`,
     "Context recovered from your notebook and from the message log across channels.",
     "Treat these as known facts. If a fresh session opens and something here is still",
     "open, bring it up naturally in the user's language (e.g. \"yesterday we were on X — shall we continue?\") without being asked.",

package/src/core/memory/index.js

@@ -14,6 +14,7 @@
 import path from "node:path";
 import { APX_HOME } from "../config/index.js";
 import { ensureSelfMemoryFile } from "../agent/self-memory.js";
+import { agentRuntimeDir } from "../agent/memory.js";
 import fs from "node:fs";
 import { openMemoryStore } from "./store.js";
 import { indexNewMessages, CURSOR_PATH } from "./indexer.js";
@@ -30,14 +31,17 @@ let _store = null;
 let _ready = null;
 let _timer = null;
 let _cfg = {};
+let _projects = null;
 let _indexing = false;
 
 // Run one index pass unless one is already in flight (a full re-embed can take
 // longer than the timer interval — overlapping passes would race on clear()).
+// `_projects` (the daemon registry) lets the indexer reach each project's
+// .apc/memory.md; agent memory is walked straight off the filesystem.
 function indexOnce(note) {
   if (_indexing || !_store) return Promise.resolve();
   _indexing = true;
-  return indexNewMessages(_store, { embed: embedOptsFromConfig(_cfg), log: note })
+  return indexNewMessages(_store, { embed: embedOptsFromConfig(_cfg), projects: _projects, log: note })
     .catch(() => {})
     .finally(() => {
       _indexing = false;
@@ -58,7 +62,7 @@ function embedOptsFromConfig(config) {
 
 // Boot the subsystem (Pieza 1 file creation + Pieza 2 store/index). Safe to
 // call once from the daemon. Never throws.
-export async function initMemory({ config, log } = {}) {
+export async function initMemory({ config, log, projects } = {}) {
   const note = typeof log === "function" ? log : () => {};
   try {
     const created = ensureSelfMemoryFile();
@@ -71,6 +75,7 @@ export async function initMemory({ config, log } = {}) {
     return null;
   }
   _cfg = config || {};
+  _projects = projects || null;
   _ready = (async () => {
     try {
       _store = await openMemoryStore({ dbPath: DB_PATH, jsonPath: JSON_PATH, log: note });
@@ -151,6 +156,61 @@ export async function memoryBlockFor(message, { config, channel, budgetMs } = {}
       store,
       config,
       channel,
+      scope: "global", // super-agent recall — never pulls project/agent rows
+      budgetMs: budgetMs || config?.memory?.broker_budget_ms || 800,
+      topK: config?.memory?.rag_top_k || 5,
+      embed: embedOptsFromConfig(config),
+    });
+  } catch {
+    return "";
+  }
+}
+
+// Scoped recall for a specific project or agent turn. `scope` is the row channel
+// key: "project:<id>" or "agent:<projdir>:<slug>" (or an array of them).
+// `memoryPath` (optional) is that scope's own notebook, read as the flat slice.
+// Returns "" on any failure so the prompt builder can drop the block.
+export async function scopedMemoryBlockFor(message, { scope, memoryPath, config, budgetMs } = {}) {
+  try {
+    if (!scope || !memoryEnabled(config)) return "";
+    const store = await getMemoryStore();
+    return await buildMemoryBlock(message, {
+      store,
+      config,
+      scope,
+      memoryPath,
+      budgetMs: budgetMs || config?.memory?.broker_budget_ms || 800,
+      topK: config?.memory?.rag_top_k || 5,
+      embed: embedOptsFromConfig(config),
+    });
+  } catch {
+    return "";
+  }
+}
+
+// Consumer for a project-agent turn (Pieza 5). Retrieves the agent's OWN memory
+// plus its project's memory in one scoped query, isolated from every other
+// agent/project and from the super-agent's global recall. RAG-only (the agent's
+// flat memory.md is already injected by buildAgentSystem). Returns a `# Relevant
+// memory (this agent & project)` block, or "" on disabled/empty/error — so the
+// caller can just append it to `extraParts`.
+export async function agentScopedMemoryBlock(message, { project, agent, config, budgetMs } = {}) {
+  try {
+    if (!message || !agent?.slug || !memoryEnabled(config)) return "";
+    const store = await getMemoryStore();
+    if (!store) return "";
+    // The storage root is <APX_HOME>/projects/<apxId>; agent rows are indexed
+    // under channel "agent:<apxId>:<slug>" — derive apxId the same way the
+    // indexer's filesystem walk names it, straight from agentRuntimeDir.
+    const apxId = path.basename(path.dirname(path.dirname(agentRuntimeDir(project, agent.slug))));
+    const scope = [`agent:${apxId}:${agent.slug}`];
+    if (project?.id != null && String(project.id) !== "0") scope.push(`project:${project.id}`);
+    return await buildMemoryBlock(message, {
+      store,
+      config,
+      scope,
+      includeFlat: false,
+      heading: "Relevant memory (this agent & project)",
       budgetMs: budgetMs || config?.memory?.broker_budget_ms || 800,
       topK: config?.memory?.rag_top_k || 5,
       embed: embedOptsFromConfig(config),