Something went wrong. Try again.
A mental bridge between a hacker and their LLM(s) of choice.
Something went wrong. Try again.
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
vaultargument (an absolute path;--vaultis 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
<vault>/.noid/lockwritesgraph.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/planis 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_fileis allowed on any file, because refusing would push agents tomv, 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 insave-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
:socketonly 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 atnoid.lock/socket-path:<userData>/noid-<pid>.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]].