@agentprojectcontext/apx 1.68.0 → 1.70.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentprojectcontext/apx",
-  "version": "1.68.0",
+  "version": "1.70.0",
   "description": "APX — unified CLI + daemon for the Agent Project Context (APC) standard.",
   "publishConfig": {
     "access": "public"

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

@@ -0,0 +1,28 @@
+// Shared helper for the Obsidian agent tools (obsidian-*.js). Underscore file —
+// like _asana.js / _git.js — so it declares no tool `name:` of its own. Each
+// tool stays a thin adapter: resolve the project's effective Obsidian vault (its
+// own record wins over the default project's — see resolveIntegration), then
+// call the pure filesystem client in core/integrations/plugins/obsidian.js.
+import { resolveProject } from "../helpers.js";
+import { resolveIntegration } from "#core/integrations/index.js";
+import { resolveVaultPath } from "#core/integrations/plugins/obsidian.js";
+
+// Resolve the active Obsidian vault for a project, or throw a message the model
+// can act on (tell the user to connect a vault).
+export function resolveObsidian(projects, project) {
+  const p = resolveProject(projects, project);
+  const resolved = resolveIntegration({ projectStorage: p.storagePath, slug: "obsidian" });
+  if (!resolved) {
+    throw new Error(
+      "Obsidian is not connected for this project. Ask the user to connect a Vault in the web panel → Integrations → Plugins → Obsidian, or run `apx obsidian set <path>`.",
+    );
+  }
+  const config = resolved.record.config || {};
+  if (!config.vault_path) throw new Error("Obsidian integration has no vault path configured");
+  return { vaultPath: resolveVaultPath(config.vault_path), config, scope: resolved.scope };
+}
+
+// The optional `project` arg every Obsidian tool accepts (defaults to current).
+export const PROJECT_ARG = {
+  project: { type: "string", description: "APX project id/name (optional; defaults to current)" },
+};

package/src/core/agent/tools/handlers/obsidian-list-notes.js

@@ -0,0 +1,28 @@
+import * as obsidian from "#core/integrations/plugins/obsidian.js";
+import { resolveObsidian, PROJECT_ARG } from "./_obsidian.js";
+
+export default {
+  name: "obsidian_list_notes",
+  category: "integrations",
+  schema: {
+    type: "function",
+    function: {
+      name: "obsidian_list_notes",
+      description: "List note paths in the active Obsidian vault (vault-relative, sorted).",
+      parameters: {
+        type: "object",
+        properties: {
+          limit: { type: "number", description: "Max notes to return (default 500)" },
+          ...PROJECT_ARG,
+        },
+      },
+    },
+  },
+  makeHandler:
+    ({ projects }) =>
+    async ({ project, limit = 500 } = {}) => {
+      const { vaultPath } = resolveObsidian(projects, project);
+      const notes = obsidian.listNotes(vaultPath, { limit });
+      return { notes, count: notes.length };
+    },
+};

package/src/core/agent/tools/handlers/obsidian-read-note.js

@@ -0,0 +1,31 @@
+import * as obsidian from "#core/integrations/plugins/obsidian.js";
+import { resolveObsidian, PROJECT_ARG } from "./_obsidian.js";
+
+export default {
+  name: "obsidian_read_note",
+  category: "integrations",
+  schema: {
+    type: "function",
+    function: {
+      name: "obsidian_read_note",
+      description: "Read the full contents of a note in the active Obsidian vault.",
+      parameters: {
+        type: "object",
+        properties: {
+          note: {
+            type: "string",
+            description: "Vault-relative note path, e.g. 'Folder/Note.md' (the .md is optional)",
+          },
+          ...PROJECT_ARG,
+        },
+        required: ["note"],
+      },
+    },
+  },
+  makeHandler:
+    ({ projects }) =>
+    async ({ project, note } = {}) => {
+      const { vaultPath } = resolveObsidian(projects, project);
+      return { note, content: obsidian.readNote(vaultPath, note) };
+    },
+};

package/src/core/agent/tools/handlers/obsidian-search-notes.js

@@ -0,0 +1,30 @@
+import * as obsidian from "#core/integrations/plugins/obsidian.js";
+import { resolveObsidian, PROJECT_ARG } from "./_obsidian.js";
+
+export default {
+  name: "obsidian_search_notes",
+  category: "integrations",
+  schema: {
+    type: "function",
+    function: {
+      name: "obsidian_search_notes",
+      description:
+        "Search notes in the active Obsidian vault by text. Matches note bodies and filenames; returns a short snippet per hit.",
+      parameters: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "Text to search for" },
+          limit: { type: "number", description: "Max results (default 50)" },
+          ...PROJECT_ARG,
+        },
+        required: ["query"],
+      },
+    },
+  },
+  makeHandler:
+    ({ projects }) =>
+    async ({ project, query, limit = 50 } = {}) => {
+      const { vaultPath } = resolveObsidian(projects, project);
+      return { results: obsidian.searchNotes(vaultPath, query, { limit }) };
+    },
+};

package/src/core/agent/tools/handlers/obsidian-write-note.js

@@ -0,0 +1,38 @@
+import * as obsidian from "#core/integrations/plugins/obsidian.js";
+import { resolveObsidian, PROJECT_ARG } from "./_obsidian.js";
+
+export default {
+  name: "obsidian_write_note",
+  category: "integrations",
+  schema: {
+    type: "function",
+    function: {
+      name: "obsidian_write_note",
+      description:
+        "Create or update a note in the active Obsidian vault. Use mode 'append' to add to an existing note, otherwise the note is overwritten.",
+      parameters: {
+        type: "object",
+        properties: {
+          note: {
+            type: "string",
+            description: "Vault-relative note path, e.g. 'Inbox/Idea.md' (the .md is optional; parent folders are created)",
+          },
+          content: { type: "string", description: "Markdown content to write" },
+          mode: {
+            type: "string",
+            enum: ["overwrite", "append"],
+            description: "Write mode (default 'overwrite')",
+          },
+          ...PROJECT_ARG,
+        },
+        required: ["note", "content"],
+      },
+    },
+  },
+  makeHandler:
+    ({ projects }) =>
+    async ({ project, note, content, mode = "overwrite" } = {}) => {
+      const { vaultPath } = resolveObsidian(projects, project);
+      return obsidian.writeNote(vaultPath, note, content, { mode });
+    },
+};

package/src/core/agent/tools/names.js

@@ -61,6 +61,12 @@ export const TOOLS = Object.freeze({
   GITHUB_LIST_REPOS:   "github_list_repos",
   GITHUB_CREATE_ISSUE: "github_create_issue",
 
+  // Integrations — Obsidian plugin (see core/integrations/plugins/obsidian.js)
+  OBSIDIAN_SEARCH_NOTES: "obsidian_search_notes",
+  OBSIDIAN_READ_NOTE:    "obsidian_read_note",
+  OBSIDIAN_WRITE_NOTE:   "obsidian_write_note",
+  OBSIDIAN_LIST_NOTES:   "obsidian_list_notes",
+
   // Side-effects
   SEND_TELEGRAM:       "send_telegram",
   SET_IDENTITY:        "set_identity",
@@ -112,6 +118,10 @@ export const NATIVE_TOOL_NAMES = new Set([
   TOOLS.ASANA_UPDATE_TASK,
   TOOLS.GITHUB_LIST_REPOS,
   TOOLS.GITHUB_CREATE_ISSUE,
+  TOOLS.OBSIDIAN_SEARCH_NOTES,
+  TOOLS.OBSIDIAN_READ_NOTE,
+  TOOLS.OBSIDIAN_WRITE_NOTE,
+  TOOLS.OBSIDIAN_LIST_NOTES,
   TOOLS.SEND_TELEGRAM,
   TOOLS.SET_IDENTITY,
   TOOLS.SET_PERMISSION_MODE,

package/src/core/agent/tools/registry.js

@@ -40,6 +40,10 @@ import asanaCreateTask from "./handlers/asana-create-task.js";
 import asanaUpdateTask from "./handlers/asana-update-task.js";
 import githubListRepos from "./handlers/github-list-repos.js";
 import githubCreateIssue from "./handlers/github-create-issue.js";
+import obsidianSearchNotes from "./handlers/obsidian-search-notes.js";
+import obsidianReadNote from "./handlers/obsidian-read-note.js";
+import obsidianWriteNote from "./handlers/obsidian-write-note.js";
+import obsidianListNotes from "./handlers/obsidian-list-notes.js";
 import { createPermissionGuard } from "./helpers.js";
 import { buildBridgedTools, DEFAULT_CATEGORIES } from "./registry-bridge.js";
 import { TOOLS, CODE_CHANNEL_TOOLS } from "./names.js";
@@ -91,6 +95,10 @@ const NATIVE_TOOLS = [
   asanaUpdateTask,
   githubListRepos,
   githubCreateIssue,
+  obsidianSearchNotes,
+  obsidianReadNote,
+  obsidianWriteNote,
+  obsidianListNotes,
 ];
 
 // Registry-backed bridges. Categories can be overridden per-process via env

package/src/core/integrations/catalog.js

@@ -7,16 +7,19 @@
 // rest carry `coming_soon: true`. Adding a plugin = drop a module in ./plugins/
 // + register it in PLUGIN_SERVICES (open/closed) — no API/route changes.
 //
-// Scope of this catalog (per product decision): Asana, GitHub, WhatsApp only.
-// Telegram is intentionally absent — it's a channel, configured under its own
-// surface, not a service plugin. Transcription lives with the desktop STT stack.
+// Scope of this catalog (per product decision): Asana, GitHub, Obsidian,
+// WhatsApp. Telegram is intentionally absent — it's a channel, configured under
+// its own surface, not a service plugin. Transcription lives with the desktop
+// STT stack. Obsidian is path-based (a local Vault) rather than token-based.
 import { asanaPlugin } from "./plugins/asana.js";
 import { githubPlugin } from "./plugins/github.js";
+import { obsidianPlugin } from "./plugins/obsidian.js";
 
 // slug -> live plugin service (must implement the lifecycle contract).
 export const PLUGIN_SERVICES = Object.freeze({
   asana: asanaPlugin,
   github: githubPlugin,
+  obsidian: obsidianPlugin,
 });
 
 // Static descriptors for plugins that are declared but not yet connectable.

package/src/core/integrations/index.js

@@ -8,3 +8,5 @@ export {
 } from "./sources.js";
 export { IntegrationStore, resolveIntegration, redactRecord } from "./store.js";
 export { listCatalog, getPluginService, PLUGIN_SERVICES } from "./catalog.js";
+export { reconcilePluginMcp } from "./mcp-sync.js";
+export { collectMemorySources, syncMemoryToVault } from "./obsidian-memory.js";

package/src/core/integrations/mcp-sync.js

@@ -0,0 +1,71 @@
+// Generic plugin → MCP reconcile. A plugin may expose an optional
+// `mcpServer(record)` hook returning `{ name, def }` (def:null → should not
+// exist). The daemon calls reconcilePluginMcp after every lifecycle change so
+// an integration can keep an auto-registered MCP server in lockstep with its
+// state. Today only the Obsidian plugin uses it (opt-in `auto_mcp`).
+import {
+  readRuntimeMcps,
+  writeRuntimeMcps,
+  readGlobalMcps,
+  writeGlobalMcps,
+} from "#core/mcp/sources.js";
+
+// Map an integration scope to the MCP scope its auto-registered servers live in.
+// Auto-registered servers point at machine-local paths, so project→runtime
+// (per-project, never committed, chmod 0600) and global→global (machine-wide).
+// We deliberately avoid the committed `.apc/mcps.json` (shared) scope.
+function mcpScopeFor(integrationScope) {
+  return integrationScope === "global" ? "global" : "runtime";
+}
+
+function readMcpScope(scope, project) {
+  return scope === "global" ? readGlobalMcps() : readRuntimeMcps(project.storagePath);
+}
+
+function writeMcpScope(scope, project, json) {
+  return scope === "global" ? writeGlobalMcps(json) : writeRuntimeMcps(project.storagePath, json);
+}
+
+// Reconcile a plugin's desired MCP server against the store, then evict live
+// registries so agents pick up the change (mirrors host/daemon/api/mcps.js).
+// `desired` = { name, def } from svc.mcpServer(record); def:null removes it.
+export function reconcilePluginMcp({ desired, integrationScope, project, projects, registries }) {
+  if (!desired || !desired.name) return { changed: false, reason: "no-hook" };
+  const scope = mcpScopeFor(integrationScope);
+  if (scope === "runtime" && !project?.storagePath) {
+    return { changed: false, reason: "no-storage" };
+  }
+
+  const json = readMcpScope(scope, project) || {};
+  json.mcpServers = json.mcpServers || {};
+  const existing = json.mcpServers[desired.name];
+
+  let action = "none";
+  if (desired.def === null) {
+    if (existing) {
+      delete json.mcpServers[desired.name];
+      action = "removed";
+    }
+  } else {
+    const next = { ...(existing || {}), ...desired.def };
+    if (JSON.stringify(existing ?? null) !== JSON.stringify(next)) {
+      action = existing ? "updated" : "added";
+    }
+    json.mcpServers[desired.name] = next;
+  }
+
+  if (action === "none") return { changed: false, scope, name: desired.name };
+
+  writeMcpScope(scope, project, json);
+  try {
+    registries?.shutdown?.();
+  } catch {
+    /* best-effort — a rebuild below still refreshes the registry */
+  }
+  try {
+    projects?.rebuild?.(project?.id);
+  } catch {
+    /* best-effort */
+  }
+  return { changed: true, scope, name: desired.name, action };
+}

package/src/core/integrations/obsidian-memory.js

@@ -0,0 +1,108 @@
+// Memory ↔ Obsidian sync. Mirrors APX's memory.md files into a folder of the
+// active vault so notes are browsable/backup-able in Obsidian — cleanly and
+// WITHOUT duplicates: every source file maps to exactly ONE deterministic vault
+// note, overwritten in place on each sync (idempotent). We never delete vault
+// notes here, so removing a project won't nuke its backup.
+import fs from "node:fs";
+import path from "node:path";
+import { assertVaultDir } from "./plugins/obsidian.js";
+import { SELF_MEMORY_PATH } from "#core/agent/self-memory.js";
+import { apcMemoryFile } from "#core/apc/paths.js";
+
+const MANAGED_MARK = "<!-- APX-managed mirror — edits are overwritten on next sync -->";
+
+function readIfExists(p) {
+  try {
+    return fs.readFileSync(p, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+// Turn a project name into a safe single vault-folder segment.
+function safeSeg(name) {
+  const s = String(name || "project")
+    .trim()
+    .replace(/[/\\:*?"<>|]+/g, "-")
+    .replace(/\s+/g, " ")
+    .slice(0, 80);
+  return s || "project";
+}
+
+function projectLabel(entry) {
+  return (
+    entry?.config?.name ||
+    entry?.name ||
+    (entry?.path ? path.basename(entry.path) : null) ||
+    `project-${entry?.id ?? "?"}`
+  );
+}
+
+// Gather the APX memory files to mirror: the global notebook (~/.apx/memory.md)
+// plus every registered project's committed .apc/memory.md. Each source carries
+// a stable `rel` (its 1:1 destination inside the sync folder).
+export function collectMemorySources(ctx = {}) {
+  const sources = [];
+
+  const globalBody = readIfExists(SELF_MEMORY_PATH);
+  if (globalBody != null) {
+    sources.push({
+      id: "global",
+      label: "APX Global Memory",
+      rel: "APX Global Memory.md",
+      from: SELF_MEMORY_PATH,
+      body: globalBody,
+    });
+  }
+
+  const projects = ctx.projects;
+  const list = typeof projects?.list === "function" ? projects.list() : [];
+  for (const entry of list) {
+    const root = entry?.path;
+    if (!root) continue; // the default project (id 0) has no repo root
+    const memFile = apcMemoryFile(root);
+    const body = readIfExists(memFile);
+    if (body == null) continue;
+    const seg = safeSeg(projectLabel(entry));
+    sources.push({
+      id: `project:${entry.id}`,
+      label: `${projectLabel(entry)} — memory`,
+      rel: path.posix.join("projects", seg, "memory.md"),
+      from: memFile,
+      body,
+    });
+  }
+
+  return sources;
+}
+
+// Mirror the collected sources into <vault>/<folder>/. Idempotent: identical
+// input → byte-identical output; each source overwrites its own single note.
+export function syncMemoryToVault({ vaultPath, folder = "APX", sources = [] }) {
+  assertVaultDir(vaultPath);
+  const root = path.resolve(vaultPath);
+  const base = path.resolve(root, folder);
+  const written = [];
+  for (const src of sources) {
+    const abs = path.resolve(base, src.rel.split("/").join(path.sep));
+    // Guard: never escape the target folder.
+    if (abs !== base && !abs.startsWith(base + path.sep)) continue;
+    const content = `${MANAGED_MARK}\n<!-- source: ${src.from} -->\n\n${String(src.body).trimEnd()}\n`;
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    const prev = readIfExists(abs);
+    const changed = prev !== content;
+    if (changed) fs.writeFileSync(abs, content);
+    written.push({
+      id: src.id,
+      note: path.relative(root, abs).split(path.sep).join("/"),
+      changed,
+    });
+  }
+  return {
+    ok: true,
+    folder,
+    count: written.length,
+    changed: written.filter((w) => w.changed).length,
+    notes: written,
+  };
+}