@origintrail-official/dkg-adapter-openclaw 0.0.1-dev.1773506972.23bf9c0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2018 OriginTrail
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,341 @@
+# DKG V9 OpenClaw Adapter
+
+`@origintrail-official/dkg-adapter-openclaw` connects an existing OpenClaw agent to a DKG V9 node.
+
+The adapter is a thin HTTP client — it does **not** run its own DKG node. A single DKG daemon process (`dkg start`) owns the node, triple store, P2P networking, and Node UI. The adapter registers tools and integration modules that route through the daemon's HTTP API.
+
+This gives your OpenClaw agent:
+
+- **Verifiable memory** — DKG-backed memory recall/import plus file-watcher sync for `MEMORY.md` and `memory/*.md`
+- **Agent Hub chat** — a local chat surface in the DKG Node UI via the OpenClaw bridge
+- **DKG tools** — `dkg_status`, `dkg_query`, `dkg_publish`, `dkg_find_agents`, `dkg_send_message`, `dkg_read_messages`, `dkg_invoke_skill`, `dkg_list_paranets`
+- **OriginTrail Game** — 10 game tools for discovering, joining, and autonomously playing the cooperative multiplayer game on the DKG
+
+## Architecture
+
+```
+┌──────────────────────────────┐       HTTP        ┌──────────────────────────┐
+│  OpenClaw Gateway            │  ──────────────►  │  DKG Daemon (dkg start)  │
+│  ┌──────────────────────┐    │  localhost:9200    │  ┌────────────────────┐  │
+│  │ adapter-openclaw      │    │                   │  │  DKGAgent           │  │
+│  │  ┌─ DkgDaemonClient ─┤────┤───────────────►───│  │  Triple Store       │  │
+│  │  │  (thin HTTP)       │    │                   │  │  P2P / libp2p       │  │
+│  │  └───────────────────┘    │                   │  │  Node UI            │  │
+│  │  DkgChannelPlugin         │                   │  └────────────────────┘  │
+│  │  DkgGamePlugin            │                   └──────────────────────────┘
+│  │  DkgMemoryPlugin          │
+│  │  WriteCapture             │
+│  └──────────────────────┘    │
+└──────────────────────────────┘
+```
+
+One process. One node on the network.
+
+## Config Files
+
+| File | Owner | Purpose |
+| --- | --- | --- |
+| `~/.dkg/config.json` | Agent (during setup) | THE node config: name, relay, chain, auth |
+| `WORKSPACE_DIR/config.json` | Agent (during setup) | Adapter feature flags: `daemonUrl`, `memory`, `channel`, `game` |
+| `~/.openclaw/openclaw.json` | Agent (merge) | Plugin load path + entry |
+
+Auto-generated on first `dkg start`:
+- `~/.dkg/wallets.json` — 3 operational wallets (address + private key)
+- `~/.dkg/auth.token` — API bearer token
+- `~/.dkg/agent-key.bin` — Ed25519 identity key
+
+## Setup
+
+### 1. Clone and build this repo
+
+```bash
+git clone https://github.com/OriginTrail/dkg-v9.git
+cd dkg-v9
+pnpm install
+pnpm build
+```
+
+Use a stable checkout path because OpenClaw loads the adapter directly from this path.
+
+### 2. Write `~/.dkg/config.json`
+
+Read `network/testnet.json` from the cloned repo for relay, chain, and paranet defaults. Read the agent's name from `WORKSPACE_DIR/IDENTITY.md` (e.g. `~/.openclaw/workspace/IDENTITY.md` for the default workspace).
+
+Write `~/.dkg/config.json` directly (skip `dkg init` — it just prompts for the same values):
+
+```json
+{
+  "name": "<agent's OpenClaw name from IDENTITY.md>",
+  "apiPort": 9200,
+  "nodeRole": "edge",
+  "relay": "/ip4/167.71.33.105/tcp/9090/p2p/12D3KooWEpSGSVRZx3DqBijai85PLitzWjMzyFVMP4qeqSBUinxj",
+  "paranets": ["testing", "origin-trail-game"],
+  "chain": {
+    "type": "evm",
+    "rpcUrl": "https://sepolia.base.org",
+    "hubAddress": "0xC056e67Da4F51377Ad1B01f50F655fFdcCD809F6",
+    "chainId": "base:84532"
+  },
+  "auth": { "enabled": true },
+  "openclawAdapter": true
+}
+```
+
+### 3. Start the DKG daemon
+
+```bash
+pnpm dkg start
+```
+
+On first start, the daemon auto-generates:
+- `~/.dkg/wallets.json` — 3 operational wallets
+- `~/.dkg/auth.token` — API bearer token
+- `~/.dkg/agent-key.bin` — Ed25519 identity key
+
+**Present wallet addresses to the user.** Read `~/.dkg/wallets.json` and show the public addresses so the user can fund them with testnet ETH + TRAC for on-chain operations. Remind the user to back up `~/.dkg/wallets.json` securely — never paste private keys into chat, logs, or screenshots.
+
+**Fund the wallets.** Use the [V9 Testnet Faucet](../../docs/setup/TESTNET_FAUCET.md) to get both Base Sepolia ETH and TRAC in one call:
+
+```bash
+curl -X POST "https://euphoria.origin-trail.network/faucet/fund" \
+  -H "Content-Type: application/json" \
+  -H "Idempotency-Key: $(uuidgen || date +%s)" \
+  --data-raw '{
+    "mode": "v9_base_sepolia",
+    "wallets": ["0xWALLET1", "0xWALLET2", "0xWALLET3"]
+  }'
+```
+
+Replace the wallet addresses with the ones from `wallets.json`. Each wallet receives ETH (for gas) and TRAC (for on-chain operations). See the [full faucet reference](../../docs/setup/TESTNET_FAUCET.md) for rate limits, dry-run, and error handling.
+
+What the running daemon provides:
+- Local API at `http://127.0.0.1:9200`
+- Node UI at `http://127.0.0.1:9200/ui`
+- OpenClaw bridge endpoints under `/api/openclaw-channel/*`
+
+### 4. Enable the adapter in OpenClaw
+
+Read `~/.openclaw/openclaw.json` and discover `agents.defaults.workspace`.
+
+Merge three things into the existing `plugins` block:
+
+1. Add `"adapter-openclaw"` to `plugins.allow`
+2. Add the adapter path to `plugins.load.paths`
+3. Add the entry to `plugins.entries`
+
+```json
+{
+  "plugins": {
+    "allow": ["adapter-openclaw"],
+    "load": {
+      "paths": [
+        "~/dkg-v9/packages/adapter-openclaw"
+      ]
+    },
+    "entries": {
+      "adapter-openclaw": {
+        "enabled": true
+      }
+    }
+  }
+}
+```
+
+Rules:
+- The plugin entry key must be `adapter-openclaw` (matches `openclaw.plugin.json` `id`).
+- `adapter-openclaw` must appear in `plugins.allow` or the gateway will not load it.
+- Do not put DKG config in `plugins.entries` — that goes in the workspace `config.json`.
+- Merge into existing plugin config — do not replace the whole `plugins` block.
+
+### 5. Configure the adapter in the workspace
+
+Create or update `WORKSPACE_DIR/config.json` with a `"dkg-node"` block:
+
+```json
+{
+  "dkg-node": {
+    "daemonUrl": "http://127.0.0.1:9200",
+    "memory": { "enabled": true },
+    "channel": { "enabled": true },
+    "game": { "enabled": true }
+  }
+}
+```
+
+Notes:
+- `daemonUrl` defaults to `http://127.0.0.1:9200`, but set it explicitly for clarity.
+- `memory.enabled: true` enables `dkg_memory_search`, `dkg_memory_import`, first-run backlog import, and file watching for `WORKSPACE_DIR/MEMORY.md` and `WORKSPACE_DIR/memory/**/*.md`.
+- `channel.enabled: true` enables the DKG UI ↔ OpenClaw bridge used by Agent Hub.
+- `game.enabled: true` enables the 10 OriginTrail Game tools. Autopilot requires `channel.enabled: true` for agent consultation; without it, only manual `game_vote` is available.
+
+### 6. Copy the skill files into the workspace
+
+The package ships two skill files that teach the agent how to use DKG tools and game tools:
+
+```bash
+mkdir -p WORKSPACE_DIR/skills/dkg-node WORKSPACE_DIR/skills/origin-trail-game
+cp ~/dkg-v9/packages/adapter-openclaw/skills/dkg-node/SKILL.md WORKSPACE_DIR/skills/dkg-node/SKILL.md
+cp ~/dkg-v9/packages/adapter-openclaw/skills/origin-trail-game/SKILL.md WORKSPACE_DIR/skills/origin-trail-game/SKILL.md
+```
+
+- `dkg-node/SKILL.md` — teaches memory, publishing, querying, and agent discovery tools
+- `origin-trail-game/SKILL.md` — teaches game mechanics, actions, strategy, and autopilot usage
+
+### 7. Restart the OpenClaw gateway
+
+Restart the OpenClaw gateway so it reloads the plugin and workspace config.
+
+## Verification
+
+A setup is healthy when all of the following are true.
+
+### Daemon and tools
+
+Ask the OpenClaw agent to call `dkg_status`.
+
+Expected: the daemon's peer ID, connected peers, multiaddrs, and wallet addresses.
+
+### Node UI and Agent Hub bridge
+
+Open `http://127.0.0.1:9200/ui`.
+
+Then open Agent Hub and use the OpenClaw tab.
+
+Expected:
+- The tab reports the local bridge as healthy
+- Sending a message produces a reply from the OpenClaw agent
+- Chat appears in the DKG graph-backed history
+
+### Memory integration
+
+If `memory.enabled` is on:
+- Ask the agent to call `dkg_memory_import` with some text
+- Ask the agent to call `dkg_memory_search` to find it
+- Or edit `WORKSPACE_DIR/MEMORY.md` and wait for the file-watcher to pick it up
+
+Expected: imported memories become searchable in the daemon-backed `agent-memory` graph.
+
+## Tools
+
+### Always available (8 tools)
+
+| Tool | Purpose |
+| --- | --- |
+| `dkg_status` | Show DKG node status: peer ID, connected peers, multiaddrs, wallet addresses |
+| `dkg_list_paranets` | List paranets known to the node |
+| `dkg_publish` | Publish N-Quads triples to a paranet |
+| `dkg_query` | Run a local SPARQL query |
+| `dkg_find_agents` | Discover agents on the DKG network (filter by framework or skill type) |
+| `dkg_send_message` | Send an encrypted P2P message to another DKG agent |
+| `dkg_read_messages` | Read P2P messages from other DKG agents (filter by peer, limit, since) |
+| `dkg_invoke_skill` | Invoke a remote agent's skill over the DKG network |
+
+### When `game.enabled` is true (10 additional tools)
+
+| Tool | Purpose |
+| --- | --- |
+| `game_lobby` | List joinable and current swarms |
+| `game_join` | Join an existing swarm |
+| `game_create` | Create a new swarm (you become leader) |
+| `game_start` | Launch the expedition (leader only) |
+| `game_status` | Check game state, resources, party health, autopilot status |
+| `game_vote` | Cast a manual vote for the current turn |
+| `game_locations` | Get all 18 trail locations with details |
+| `game_leaderboard` | Scores from completed games |
+| `game_autopilot_start` | Start autonomous play (requires `channel.enabled`) |
+| `game_autopilot_stop` | Stop autonomous play |
+
+### When `memory.enabled` is true (2 additional tools)
+
+| Tool | Purpose |
+| --- | --- |
+| `dkg_memory_search` | Search the daemon-backed `agent-memory` graph |
+| `dkg_memory_import` | Import memory text into the daemon-backed graph |
+
+## Adapter Config Reference
+
+These keys live under `"dkg-node"` in `WORKSPACE_DIR/config.json`.
+
+| Key | Default | Purpose |
+| --- | --- | --- |
+| `daemonUrl` | `http://127.0.0.1:9200` | DKG daemon HTTP URL |
+| `memory.enabled` | `false` | Enable `dkg_memory_*` tools, file-watcher sync, and backlog import |
+| `memory.memoryDir` | `WORKSPACE_DIR/memory` | Override the watched memory directory |
+| `memory.watchDebounceMs` | `1500` | File watcher debounce interval (ms) |
+| `channel.enabled` | `false` | Enable the Agent Hub ↔ OpenClaw bridge |
+| `channel.port` | `9201` | Standalone bridge port (when gateway route registration unavailable) |
+| `game.enabled` | `false` | Enable the 10 OriginTrail Game tools |
+| `game.pollIntervalMs` | `2000` | Autopilot polling interval (ms) |
+| `game.decisionTimeoutMs` | `15000` | Agent consultation timeout per turn (ms) — falls back to safe default |
+
+## Agent Runbook
+
+If another agent is performing the setup, these are the exact steps:
+
+1. Read `~/.openclaw/openclaw.json` and discover `agents.defaults.workspace`.
+2. Clone this repo to a stable path such as `~/dkg-v9`, then `pnpm install && pnpm build`.
+3. Read `network/testnet.json` for relay, chain, and paranet defaults.
+4. Read the agent name from `WORKSPACE_DIR/IDENTITY.md`.
+5. Write `~/.dkg/config.json` programmatically using the agent name and network defaults. Include `"openclawAdapter": true`.
+6. Run `pnpm dkg start` — wallets, auth token, and identity key are auto-generated on first start.
+7. Read `~/.dkg/wallets.json` and show the public addresses so the user can fund them with testnet ETH + TRAC for on-chain operations. Remind the user to back up `~/.dkg/wallets.json` securely — never paste private keys into chat, logs, or screenshots. Fund the wallets by calling `POST https://euphoria.origin-trail.network/faucet/fund` with `{"mode": "v9_base_sepolia", "wallets": ["0xADDR1", "0xADDR2", "0xADDR3"]}`. Include an `Idempotency-Key` header. See [Testnet Faucet](../../docs/setup/TESTNET_FAUCET.md) for details.
+8. Merge into `~/.openclaw/openclaw.json`: add `"adapter-openclaw"` to `plugins.allow`, add the adapter path to `plugins.load.paths`, and add `adapter-openclaw` to `plugins.entries`.
+9. Write the `"dkg-node"` block into `WORKSPACE_DIR/config.json` with `daemonUrl`, `memory.enabled`, `channel.enabled`, and `game.enabled`.
+10. Copy `skills/dkg-node/SKILL.md` into `WORKSPACE_DIR/skills/dkg-node/SKILL.md` and `skills/origin-trail-game/SKILL.md` into `WORKSPACE_DIR/skills/origin-trail-game/SKILL.md`.
+11. Restart the OpenClaw gateway.
+12. Verify:
+    - `dkg_status` returns daemon info + wallet addresses
+    - `http://127.0.0.1:9200/ui` loads
+    - Agent Hub → OpenClaw bridge is healthy
+13. Report: `Setup complete, DKG V9 UI accessible at http://127.0.0.1:9200/ui`
+
+Replace the URL if the daemon binds to a different host or port.
+
+## Troubleshooting
+
+### `dkg_status` returns "daemon is not reachable"
+
+The daemon is not running or not reachable at the configured URL.
+
+Check:
+- `dkg start` was run and the process is still alive
+- `daemonUrl` in `WORKSPACE_DIR/config.json` matches the daemon's `apiPort`
+- No firewall blocking `127.0.0.1:9200`
+
+### Node UI works, but Agent Hub → OpenClaw is offline
+
+The daemon is up but the OpenClaw bridge is not reachable.
+
+Check:
+- `channel.enabled` is `true` in `WORKSPACE_DIR/config.json`
+- The OpenClaw gateway was restarted after config changes
+- The daemon is using the current token from `~/.dkg/auth.token`
+- If the gateway does not expose adapter HTTP routes, the standalone bridge port must be reachable on `127.0.0.1`
+
+### `dkg_memory_search` or `dkg_memory_import` is missing
+
+`memory.enabled` is off, or the plugin did not reload after config changes.
+
+### Memory tools exist but return nothing
+
+The daemon is reachable, but the `agent-memory` graph has no content yet.
+
+Try:
+- `dkg_memory_import` with some text
+- Editing `WORKSPACE_DIR/MEMORY.md`
+- Adding a Markdown file under `WORKSPACE_DIR/memory/`
+
+### Advanced daemon routing
+
+For non-default layouts, the daemon supports explicit OpenClaw bridge hints in `~/.dkg/config.json`:
+
+```json
+{
+  "openclawChannel": {
+    "bridgeUrl": "http://127.0.0.1:9201",
+    "gatewayUrl": "http://127.0.0.1:3000/api/dkg-channel"
+  }
+}
+```
+
+Use this only if the daemon cannot autodetect the local bridge/gateway path.

package/dist/DkgChannelPlugin.d.ts

@@ -0,0 +1,94 @@
+/**
+ * DkgChannelPlugin — Spike A: DKG UI ↔ OpenClaw channel bridge.
+ *
+ * Makes the DKG Node UI a first-class OpenClaw channel.  Messages sent
+ * through the Agent Hub chat go through this channel into the OpenClaw
+ * gateway's session system, meaning they share the same transcript and
+ * context as messages from Telegram, WhatsApp, or any other channel
+ * (when `dmScope: "main"`).
+ *
+ * Transport: The DKG daemon exposes `/api/openclaw-channel/send` for
+ * the frontend.  The daemon forwards the message to this plugin via
+ * a standalone HTTP server on a dedicated port (bridge mode).
+ *
+ * Message routing uses OpenClaw's plugin-sdk `dispatchInboundReplyWithBase`
+ * helper — the same pathway used by built-in channels (Telegram, Discord,
+ * etc.).  This ensures the message enters the agent's session system with
+ * full context continuity.
+ */
+import type { ChannelOutboundReply, DkgOpenClawConfig, OpenClawPluginApi } from './types.js';
+import type { DkgDaemonClient } from './dkg-client.js';
+export declare const CHANNEL_NAME = "dkg-ui";
+export declare class DkgChannelPlugin {
+    private readonly config;
+    private readonly client;
+    private api;
+    /** OpenClaw runtime — provides channel routing, session, and reply subsystems. */
+    private runtime;
+    /** Full OpenClawConfig — needed for agent dispatch. */
+    private cfg;
+    /** Plugin-sdk helpers — lazily loaded at first dispatch. */
+    private sdk;
+    /** True after the first loadSdk() attempt — prevents re-trying and re-logging every turn. */
+    private sdkLoaded;
+    private server;
+    private serverStart;
+    private readonly pendingRequests;
+    private readonly port;
+    private useGatewayRoute;
+    private inFlight;
+    private readonly maxInFlight;
+    constructor(config: NonNullable<DkgOpenClawConfig['channel']>, client: DkgDaemonClient);
+    register(api: OpenClawPluginApi): void;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private loadSdk;
+    private buildRegisteredChannelPlugin;
+    private resolveRegisteredAccount;
+    private buildStreamingReplyOptions;
+    /**
+     * Process an inbound message from the DKG UI.
+     * Routes through the OpenClaw session system and returns the agent reply.
+     */
+    processInbound(text: string, correlationId: string, identity: string): Promise<ChannelOutboundReply>;
+    /**
+     * Dispatch an inbound message using OpenClaw's plugin-sdk dispatch system.
+     * This is the same pathway used by Telegram, Discord, and other built-in channels.
+     */
+    private dispatchViaPluginSdk;
+    private dispatchWithSdk;
+    private dispatchWithRuntime;
+    /**
+     * Stream variant of processInbound. Yields events as the agent produces them.
+     * The caller is responsible for writing SSE frames and calling persistTurn after.
+     */
+    processInboundStream(text: string, correlationId: string, identity: string): AsyncGenerator<{
+        type: 'text_delta';
+        delta: string;
+    } | {
+        type: 'final';
+        text: string;
+        correlationId: string;
+    }>;
+    private handleOutboundReply;
+    private dispatchRuntimeReply;
+    private buildSdkCore;
+    private recordRuntimeInboundSession;
+    private handleUnexpectedHttpError;
+    private handleUnexpectedGatewayError;
+    /**
+     * Persist a chat turn to the DKG agent-memory graph.
+     * Fire-and-forget — errors are logged but don't affect the reply.
+     */
+    private persistTurn;
+    private handleHttpRequest;
+    private handleInboundHttp;
+    /** SSE streaming handler — yields events as the agent produces them. */
+    private handleInboundStreamHttp;
+    /** Handler for api.registerHttpRoute() — same logic, different req/res shape. */
+    private handleGatewayRoute;
+    private authorizeBridgeRequest;
+    get bridgePort(): number;
+    get isUsingGatewayRoute(): boolean;
+}
+//# sourceMappingURL=DkgChannelPlugin.d.ts.map

package/dist/DkgChannelPlugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DkgChannelPlugin.d.ts","sourceRoot":"","sources":["../src/DkgChannelPlugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAOH,OAAO,KAAK,EACV,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,eAAO,MAAM,YAAY,WAAW,CAAC;AAerC,qBAAa,gBAAgB;IAmBzB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAnBzB,OAAO,CAAC,GAAG,CAAkC;IAC7C,kFAAkF;IAClF,OAAO,CAAC,OAAO,CAAa;IAC5B,uDAAuD;IACvD,OAAO,CAAC,GAAG,CAAa;IACxB,4DAA4D;IAC5D,OAAO,CAAC,GAAG,CAAa;IACxB,6FAA6F;IAC7F,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,WAAW,CAA8B;IACjD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqC;IACrE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAK;gBAGd,MAAM,EAAE,WAAW,CAAC,iBAAiB,CAAC,SAAS,CAAC,CAAC,EACjD,MAAM,EAAE,eAAe;IAS1C,QAAQ,CAAC,GAAG,EAAE,iBAAiB,GAAG,IAAI;IA2EhC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAmCtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAwB3B,OAAO,CAAC,OAAO;IAkDf,OAAO,CAAC,4BAA4B;IAoCpC,OAAO,CAAC,wBAAwB;IAQhC,OAAO,CAAC,0BAA0B;IAUlC;;;OAGG;IACG,cAAc,CAClB,IAAI,EAAE,MAAM,EACZ,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,oBAAoB,CAAC;IA8ChC;;;OAGG;YACW,oBAAoB;IAkFlC,OAAO,CAAC,eAAe;IAmDvB,OAAO,CAAC,mBAAmB;IAsD3B;;;OAGG;IACI,oBAAoB,CACzB,IAAI,EAAE,MAAM,EACZ,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,GACf,cAAc,CAAC;QAAE,IAAI,EAAE,YAAY,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;YAyInG,mBAAmB;IAgBjC,OAAO,CAAC,oBAAoB;IA2B5B,OAAO,CAAC,YAAY;YAwBN,2BAA2B;IA4BzC,OAAO,CAAC,yBAAyB;IAWjC,OAAO,CAAC,4BAA4B;IAUpC;;;OAGG;YACW,WAAW;YAwBX,iBAAiB;YA4BjB,iBAAiB;IAkD/B,wEAAwE;YAC1D,uBAAuB;IA+DrC,iFAAiF;YACnE,kBAAkB;IAoBhC,OAAO,CAAC,sBAAsB;IAuB9B,IAAI,UAAU,IAAI,MAAM,CAGvB;IAED,IAAI,mBAAmB,IAAI,OAAO,CAEjC;CACF"}