--- name: agent-interface description: noid's MCP server for agents - one stdio server (mcp.js) per agent, serving any vault named per call; the vault lock decides who writes graph.edn; one pure core (noid.agent) runs in both direct and relay mode. metadata: type: project --- Approved by Arcadia 2026-09-26 (tasks: the agent interface, slices A and B). Vault per call approved by Arcadia 2026-09-27 (task 09). - Agents change files with their own tools. The MCP tools cover only what the file system can't express: the graph, authorship, activity, and `move_file` (a rename that keeps connections). - Every tool takes a `vault` argument (an absolute path; `--vault` is only an optional default), so one user-scope registration per agent serves every vault. Any existing folder may be a vault. The server realpaths it, and main compares realpaths too. A read-only call on a folder with no `.noid/` answers from a scan and creates nothing; the first write creates `.noid/`. Agents are told vault paths; there is no discovery tool yet. - Only the holder of `/.noid/lock` writes `graph.edn`. noid holds it while the vault is open. An MCP server holds it for one tool call at a time (a 30 s lease, plus a token checked before writing). - noid closed (or open on another folder): the server works in direct mode, reading graph.edn and scanning the folder under the lock. noid open: the server relays over a local socket, and the renderer applies the call as an action. - `noid.agent/plan` is the one pure implementation of every tool, shared by both modes. - Permissions follow "add, not override", between agents too: an agent may retype only an untyped connection or one it typed; disconnect only its own connections; write only its own note; claim only files with no author. The human may override anything from the UI. `move_file` is allowed on any file, because refusing would push agents to `mv`, which strands connections on a ghost. - Every graph.edn writer checks, right before writing, that its lock token is still in `.noid/lock`: the MCP server before each write or move, and the app in `save-graph!` (it re-acquires if the token is gone). Taking over a stale lock isn't atomic; the token checks are the real guarantee. Never add a graph.edn write path without one. - The app lock records `:socket` only while electron.agent is actually listening (`electron.agent/listening-path`, passed in by electron.ipc), because the mcp server treats an unanswering socket as a dead app and takes over the lock. A recorded-but-dead socket would let an agent write under a live app, which then overwrites that write on its next save. The socket lives at `noid.lock/socket-path`: `/noid-.sock`, falling back to tmpdir when the path is over 100 bytes (macOS caps socket paths at 104), or a named pipe on win32. It isn't kept in tmpdir, because tmp cleaners delete it. **Why:** Arcadia chose MCP over folder conventions, wanted agents to work while noid is closed, and wanted several agents per vault. Later (2026-09-27) she wanted the vault chosen at call time, so one registration works from any session. **How to apply:** new agent capabilities are new `noid.agent` tools with pure `plan` cases. Never write graph.edn without holding the lock. See [[connection-model]] and [[board-architecture]].