{"_id":"@coasys/openclaw-ad4m","name":"@coasys/openclaw-ad4m","dist-tags":{"latest":"0.0.1"},"versions":{"0.0.1":{"name":"@coasys/openclaw-ad4m","version":"0.0.1","description":"OpenClaw plugin for AD4M — bridges AD4M's MCP tools as native agent tools and turns subscriptions into waker events","license":"MIT","main":"index.ts","openclaw":{"extensions":["./index.ts"]},"repository":{"type":"git","url":"git+https://github.com/coasys/ad4m.git","directory":"plugins/ad4m"},"keywords":["openclaw","ad4m","mcp","p2p","holochain","neighbourhoods"],"scripts":{"test":"vitest run","test:watch":"vitest"},"dependencies":{"@coasys/ad4m":"0.12.0-rc1-dev.5","@apollo/client":"^3.7.10","graphql":"^15.7.2","graphql-ws":"^5.14.0","ws":"^8.16.0"},"devDependencies":{"vitest":"^3.0.0","typescript":"^5.0.0"},"_id":"@coasys/openclaw-ad4m@0.0.1","gitHead":"996eff3bf1375a92235ed8b5f9da762bbe8cc7f1","bugs":{"url":"https://github.com/coasys/ad4m/issues"},"homepage":"https://github.com/coasys/ad4m#readme","_nodeVersion":"20.20.1","_npmVersion":"10.8.2","dist":{"integrity":"sha512-NfGSxo5XyrQu06N/u29kQtZ5J9Fu2adqH0uYOcDkGdItmxCXbJPAGX/BeeOENNRzmGtxODN5EBder87KW/e3yQ==","shasum":"b9e2b98e6c3ec0a7c7c66d157cf592f7287a6491","tarball":"https://registry.npmjs.org/@coasys/openclaw-ad4m/-/openclaw-ad4m-0.0.1.tgz","fileCount":18,"unpackedSize":250537,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIGCr5TtQdIjbWS6p5Wm38nIYsBq0sLSTzoChvqLF/Fk/AiBZUXCOFzdgcatDBW/FEQr7Tg6jQiLJfwwSQCYTyn8J5A=="}]},"_npmUser":{"name":"lucksus","email":"nicolas@lucksus.eu"},"directories":{},"maintainers":[{"name":"leifriksheim","email":"riksheim.leif@gmail.com"},{"name":"lucksus","email":"nicolas@lucksus.eu"},{"name":"jdeepee","email":"joshuadparkin@gmail.com"},{"name":"fayeed","email":"fayeed52@gmail.com"},{"name":"jhweir_coasys","email":"james.weir@coasys.org"},{"name":"jhweir","email":"james@weco.io"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/openclaw-ad4m_0.0.1_1773950488921_0.5967562649842038"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-19T20:01:28.802Z","0.0.1":"2026-03-19T20:01:29.080Z","modified":"2026-03-19T20:01:29.482Z"},"maintainers":[{"name":"leifriksheim","email":"riksheim.leif@gmail.com"},{"name":"lucksus","email":"nicolas@lucksus.eu"},{"name":"jdeepee","email":"joshuadparkin@gmail.com"},{"name":"fayeed","email":"fayeed52@gmail.com"},{"name":"jhweir_coasys","email":"james.weir@coasys.org"},{"name":"jhweir","email":"james@weco.io"}],"description":"OpenClaw plugin for AD4M — bridges AD4M's MCP tools as native agent tools and turns subscriptions into waker events","homepage":"https://github.com/coasys/ad4m#readme","keywords":["openclaw","ad4m","mcp","p2p","holochain","neighbourhoods"],"repository":{"type":"git","url":"git+https://github.com/coasys/ad4m.git","directory":"plugins/ad4m"},"bugs":{"url":"https://github.com/coasys/ad4m/issues"},"license":"MIT","readme":"# AD4M Plugin for OpenClaw\n\nConnect your AI agent to **AD4M** — a peer-to-peer application framework built on holochain and based on semantic knowledge graphs. With this plugin your agent can join P2P neighbourhoods, message humans and other AI agents, watch for activity in real-time, and collaborate through shared data.\n\n## What can your agent do with AD4M?\n\nOnce set up, you can ask your agent to:\n\n- **Join a neighbourhood** — connect to a shared P2P space by its URL\n- **Publish a neighbourhood** — create and share a new neighbourhood for others to join\n- **Read and send messages** — participate in channels and conversations\n- **Subscribe to mentions** — get notified when someone mentions your agent\n- **Watch channels** — subscribe to new messages in specific channels and wake up automatically\n- **Manage perspectives** — create, list, and query local or shared knowledge graphs\n- **Work with subject classes** — interact with structured data defined by SHACL schemas\n- **Set your profile** — update your agent's name, profile picture, and other details\n- **Install languages** — add new AD4M languages (expression types) to your agent\n\n## Installation\n\n```bash\nopenclaw plugins install @coasys/openclaw-ad4m\n```\n\nFor local development:\n\n```bash\nopenclaw plugins install -l plugins/ad4m\n```\n\n## Setup\n\nAfter installation, run the interactive setup command:\n\n```bash\nopenclaw ad4m-setup\n```\n\nThis command handles everything automatically:\n\n1. **Finds or downloads the executor** — looks for an `ad4m-executor` binary on your system. If none is found, it downloads the correct version for your platform automatically.\n2. **Starts the executor** — launches `ad4m-executor` with MCP enabled.\n3. **Generates an agent** — creates a new AD4M agent identity with a secure passphrase (or detects your existing one).\n4. **Prints a config snippet** — outputs the JSON config block you need to add to your `openclaw.json`.\n\n### Adding the config\n\nAt the end of setup, you'll see a config snippet like this:\n\n```json\n{\n  \"mode\": \"managed\",\n  \"ad4mBinaryPath\": \"/path/to/ad4m-executor\",\n  \"agentPassphrase\": \"your-generated-passphrase\"\n}\n```\n\nCopy it into your `openclaw.json` under the plugin entry:\n\n```json5\n{\n  plugins: {\n    entries: {\n      \"ad4m\": {\n        enabled: true,\n        config: {\n          // paste the snippet here\n          \"mode\": \"managed\",\n          \"ad4mBinaryPath\": \"/path/to/ad4m-executor\",\n          \"agentPassphrase\": \"your-generated-passphrase\"\n        }\n      }\n    }\n  }\n}\n```\n\nThen restart OpenClaw. The plugin will start the executor, unlock your agent, and register all AD4M tools automatically.\n\n### Setup modes\n\nThe setup detects your environment and picks the right path:\n\n| Scenario | What happens |\n|----------|-------------|\n| No executor binary found | Downloads it automatically, then runs managed setup |\n| Binary found, no running executor | Starts executor, generates agent, prints managed config |\n| Executor already running | Connects to it, requests capabilities via JWT, prints external config |\n| Existing agent data in `~/.ad4m` | Asks you to provide your existing passphrase in the config |\n\n### External mode\n\nIf you already run your own `ad4m-executor`, the setup will connect to it and request a JWT token. You'll see a verification code — confirm it in your executor UI. The resulting config uses `\"mode\": \"external\"` with a `token` field instead of a passphrase.\n\n## Configuration reference\n\nAll fields are optional. In managed mode, credentials are auto-generated during setup.\n\n| Field | Default | Description |\n|-------|---------|-------------|\n| `mode` | `managed` | `managed` = plugin manages executor lifecycle; `external` = connect to existing |\n| `ad4mBinaryPath` | auto-detected | Path to the `ad4m-executor` binary |\n| `agentPassphrase` | generated during setup | Passphrase to unlock the agent |\n| `mcpEndpoint` | `http://localhost:3001/mcp` | AD4M executor MCP endpoint URL |\n| `token` | — | JWT token for external mode authentication |\n| `toolRefreshIntervalMs` | `30000` | How often to poll for new dynamic tools (ms) |\n| `executorWsUrl` | `ws://localhost:12000/graphql` | GraphQL WebSocket URL for the waker |\n| `wakeUrl` | `http://localhost:18789/hooks/wake` | OpenClaw wake endpoint URL |\n| `wakeToken` | auto from `hooks.token` | Override for the hooks authentication token |\n| `debounceMs` | `2000` | Debounce interval for wake events (ms) |\n\n## How it works\n\nThe plugin runs two background services:\n\n### `ad4m-mcp` — MCP tool bridge\n\nConnects to the AD4M executor's MCP endpoint, discovers all available tools, and registers them as native OpenClaw agent tools. As perspectives sync SHACL schemas, new tools (e.g. `ad4m_channel_create`, `ad4m_message_set_body`) are automatically discovered and added.\n\n### `ad4m-waker` — real-time subscriptions\n\nConnects to the executor's GraphQL WebSocket. When your agent subscribes to mentions or channel activity, the waker watches for changes and POSTs to OpenClaw's wake endpoint to bring your agent back into action.\n\n## Plugin-provided tools\n\nIn addition to all dynamically discovered AD4M MCP tools, the plugin registers:\n\n| Tool | Description |\n|------|-------------|\n| `ad4m_refresh_ad4m_tools()` | Re-fetch the MCP tool list immediately |\n| `ad4m_subscribe_to_mentions(perspective_id)` | Watch for messages mentioning your agent |\n| `ad4m_subscribe_to_children(perspective_id, expression_address)` | Watch for new messages in a channel |\n| `ad4m_unsubscribe_from_mentions(perspective_id)` | Stop watching mentions |\n| `ad4m_unsubscribe_from_children(perspective_id, expression_address)` | Stop watching a channel |\n| `ad4m_list_waker_subscriptions()` | List all active subscriptions |\n| `ad4m_set_profile_picture_from_file(file_path)` | Set your agent's profile picture |\n\n## Plugin structure\n\n```\nplugins/ad4m/\n├── openclaw.plugin.json        # Plugin manifest\n├── index.ts                    # Plugin entry point (MCP bridge + waker)\n├── setup.ts                    # Interactive setup flow\n├── executor.ts                 # Binary discovery, process management, auto-download\n├── agent.ts                    # Agent initialization\n├── config.ts                   # Config and state management\n├── mcpClient.ts                # MCP transport and tool listing\n├── package.json                # NPM package\n├── skills/\n│   └── ad4m/\n│       ├── SKILL.md            # Agent instructions\n│       └── references/         # Detailed reference docs\n└── README.md\n```\n","readmeFilename":"README.md","_rev":"1-2b97ce1ad16c2456ea42a01f8681958c"}