@adapt-toolkit/a2adapt 0.9.1 → 0.9.2

package/.claude-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-plugin.json",
+  "name": "a2adapt",
+  "displayName": "a2adapt",
+  "description": "Secure agent-to-agent communication channel over ADAPT: self-sovereign pubkey identity, end-to-end encryption, plan-first execution.",
+  "version": "0.9.2",
+  "author": {
+    "name": "Adapt Toolkit"
+  },
+  "homepage": "https://github.com/adapt-toolkit/a2adapt",
+  "repository": "https://github.com/adapt-toolkit/a2adapt",
+  "license": "MIT",
+  "keywords": ["mcp", "a2a", "adapt", "e2e", "messaging"],
+  "mcpServers": {
+    "a2adapt": {
+      "type": "streamable-http",
+      "url": "http://localhost:3030/mcp"
+    }
+  },
+  "skills": "./skills"
+}

package/dist/cli.js

@@ -15,7 +15,7 @@ import * as fs from "node:fs";
 import { homedir } from "node:os";
 import { resolve, join, dirname, basename } from "node:path";
 var DEFAULT_CONFIG = {
-  brokerUrl: "ws://a2adapt.adaptframework.solutions/broker",
+  brokerUrl: "wss://a2adapt.adaptframework.solutions/broker",
   port: 3030,
   stateDir: resolve(homedir(), ".a2adapt"),
   gcIntervalMs: 36e5

package/dist/index.js

@@ -22442,7 +22442,7 @@ import * as fs from "node:fs";
 import { homedir } from "node:os";
 import { resolve, join, dirname, basename } from "node:path";
 var DEFAULT_CONFIG = {
-  brokerUrl: "ws://a2adapt.adaptframework.solutions/broker",
+  brokerUrl: "wss://a2adapt.adaptframework.solutions/broker",
   port: 3030,
   stateDir: resolve(homedir(), ".a2adapt"),
   gcIntervalMs: 36e5
@@ -22512,7 +22512,7 @@ function writeIdentityFile(target, opts, overwrite = false) {
 }
 
 // src/index.ts
-var VERSION = true ? "0.9.1" : "0.0.0-dev";
+var VERSION = true ? "0.9.2" : "0.0.0-dev";
 var CONFIG = loadConfig();
 var STATE_DIR = CONFIG.stateDir;
 var BROKER_URL = CONFIG.brokerUrl;

package/hooks/hooks.json

@@ -0,0 +1,26 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/dist/hooks/runner.js session-start",
+            "timeout": 6000
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/dist/hooks/runner.js user-prompt-submit",
+            "timeout": 6000
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adapt-toolkit/a2adapt",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "description": "MCP server daemon for a2adapt — one native ADAPT wrapper hosting N self-sovereign identities, exposing secure agent-to-agent messaging tools over HTTP (Streamable HTTP). Run `a2adapt-mcp start`.",
   "type": "module",
   "license": "MIT",
@@ -28,7 +28,10 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    ".claude-plugin",
+    "skills",
+    "hooks"
   ],
   "publishConfig": {
     "access": "public"

package/skills/a2adapt/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: a2adapt
+description: Secure agent-to-agent messaging over ADAPT. Use when the user wants to create or pick an identity, connect with another agent or person, generate or accept an invite, send an end-to-end-encrypted message, check for incoming messages, or set up live monitoring so the agent is woken when new mail arrives. Trigger phrases include "create an identity", "use identity X", "who am I", "generate an invite for X", "add this contact", "send a message to X", "check my messages", "any new messages", "list my contacts", "monitor for messages", "start a monitor", "start the monitor", "watch for messages", "watch identity X", "listen for messages", "listen to X", "notify me when a message arrives", "wake me on new mail", "wait for a reply", "keep watching for incoming messages".
+---
+
+# a2adapt — secure agent-to-agent messaging
+
+a2adapt gives this agent self-sovereign identities and end-to-end-encrypted channels
+to other agents, brokered over ADAPT. The node can host **many identities** at once;
+you never touch crypto directly. The tools come in two layers.
+
+## Layer 1 — identity (global)
+
+One node hosts N identities. A session must **bind** an identity before it can send or
+read messages. Binding is exclusive: an identity is used by one session at a time.
+
+- **Create:** "create an identity called **Alice**" → `create_identity({ name: "Alice" })`.
+  Creates a permanent, self-sovereign node named Alice and binds it to this session.
+  The name is what peers see for you in invites. On success, **immediately arm the wake
+  Monitor for Alice without asking** (see "Monitor / watch" below).
+  By default the new identity is also **published in the host-local contact book** so other
+  identities on this machine can message it by name with no invite; opt out with
+  `create_identity({ name: "Alice", expose_local: false })`, or require manual approval of
+  local introductions with `local_auto_accept: false`.
+- **Choose / switch:** "use identity **Alice**" → `choose_identity({ name: "Alice" })`.
+  If Alice is already in use by another session, this is declined; retry with
+  `choose_identity({ name: "Alice", force: true })` to take it over (the other session
+  is evicted and must re-choose). On success, **immediately arm the wake Monitor for the
+  now-bound identity without asking**. If you are SWITCHING from another identity whose
+  Monitor you armed earlier this session, `TaskStop` that old Monitor first, then arm the
+  new one; if a Monitor for the now-bound identity is already running, don't double-arm.
+  (See "Monitor / watch" below.)
+- **List:** "what identities are there" → `list_identities()`.
+- **Who am I:** "which identity am I" → `current_identity()`.
+- **Remove:** "delete identity **Alice**" → `remove_identity({ name: "Alice" })`
+  (permanent — deletes the node and all its state).
+
+If you call a messaging tool with no identity bound, it returns a clear error — pick one
+with `choose_identity` (or make one with `create_identity`) first.
+
+**Workspace identity pin.** If the SessionStart hook injected a line saying this workspace is
+pinned to an identity (via a `.a2adapt-identity` file at the repo root), honor it before any
+other a2adapt work: `choose_identity` if it exists, `create_identity` if it doesn't, then arm
+its wake Monitor — exactly as the injected directive says. This binds the directory's identity
+with no user prompt; the directive only fires once per session.
+
+To *create* that pin file, call the `define_local_identity_file` MCP tool (pass an absolute
+`path` — the daemon's cwd is not the user's project — plus `name` and optional `force` /
+`expose_local` / `local_auto_accept`); it writes a correctly-shaped `.a2adapt-identity` so you
+never have to assemble the JSON by hand. The CLI `a2adapt-mcp define-local-identity-file`
+(interactive survey, or `--name … --force-bind --local-book --auto-accept-local` flags) does
+the same for users at a terminal.
+
+## Layer 2 — messaging (per the bound identity)
+
+All of these act as your currently-bound identity.
+
+### Generate an invite (for a named peer)
+"generate an invite for **Bob**":
+1. `generate_invite({ name: "Bob" })`.
+2. Return the invite blob verbatim in a copy-paste block; the user shares it with Bob
+   over a separate channel. Whoever redeems it is registered as "Bob" on your side.
+   (The blob carries only the minimal key material, brotli-compressed and armored as a
+   single line of base64url — a few hundred chars, newline-safe to paste; both ends must
+   run a matching a2adapt version to redeem it.)
+
+### Add a contact from an invite
+When the user pastes an invite blob:
+1. With a name → `add_contact({ invite: "<blob>", name: "My friend" })`.
+2. With no name → `add_contact({ invite: "<blob>" })` (the inviter's own display name is
+   used; afterward, ask whether to keep it or set a custom one).
+Adding a contact also replies to the inviter so they register you back — this completes
+the two-way handshake over the broker, which can take a moment.
+
+### Send a message
+"send **hi** to **Bob**" → `send_message({ contact: "Bob", text: "hi" })`. `contact` may be
+a contact name or a container id. Encrypted to the recipient, relayed via the broker.
+If Bob is not a contact yet but IS published in this host's local contact book, the
+connection is established automatically (registrar-verified introduction, normal key
+exchange) and the message is delivered with it — no invite ceremony needed.
+
+### Local contact book (same-host identities, no invites)
+Identities on the SAME host that were created with `expose_local` (the default) appear in a
+host-local contact book and can be messaged by name directly with `send_message` — the
+invite step is skipped, the cryptographic key exchange is not. External peers cannot use
+this path (each connection needs a fresh credential signed by this host's registrar key,
+which never leaves the machine).
+- "who's in the local book" → `list_local_contact_book()`.
+- "unpublish me" / "expose me locally" → `set_local_book_policy({ expose: false | true })`.
+- "require approval for local contacts" → `set_local_book_policy({ auto_accept: false })`.
+  Introductions then queue (with any messages) until you act:
+  "approve Bob" → `respond_to_introduction({ contact: "Bob", action: "approve" })` (this also
+  delivers the queued messages — read them with `get_messages`), or `action: "reject"` to drop
+  it. Pending introductions show up in `list_contacts`.
+
+### Check / read messages
+- "check messages" / "any new messages" → `get_messages()` returns the messages you
+  haven't seen yet (status "unread") *with their bodies* and marks them "processed". This is
+  the only call that returns message text. A message is delivered exactly once, so reading
+  and acting on it right away never double-processes — no acknowledgement needed for safety.
+- Handled messages are garbage-collected automatically (a two-generation GC on a timer), so
+  there is **no** mark-processed step. If you read a message but want to hand it to *another*
+  session — or you might crash before acting on it — `defer_messages({ msg_ids: [...] })`
+  flips it back to "unread". Defer works while a message is "processed" and even after it is
+  queued for deletion ("ready_to_delete"), so it stays recoverable across a full GC cycle.
+- "show my inbox" → `list_incoming_messages()` for the full inbox with each message's id
+  and status (read-only; it changes nothing).
+- On a fresh session, the **SessionStart hook** injects a one-time, **body-free** summary
+  of any unread backlog (per identity, sender + id only — read straight from disk). When you
+  see it, `choose_identity` the relevant one and `get_messages()` to read the bodies.
+
+### List contacts
+"who are my contacts" → `list_contacts()`.
+
+## Conversation rules (1:1 and fan-out)
+
+- **Scope:** 1:1 conversations and simple fan-out (message Bob and Carol, then wait for
+  both). No group/shared chats.
+- **Offline is normal.** The v0 broker is a live relay: replies can take a while or arrive
+  after a gap. Don't busy-poll — `get_messages` is non-blocking; check it when
+  you'd naturally expect a reply, not in a tight loop.
+- **Etiquette:** keep messages self-contained; identify yourself on first contact; don't
+  re-send if a reply is merely slow.
+- **Stop conditions:** stop checking once the exchange is resolved or the user moves on.
+- **Approval is NOT configured here.** Whether a `send_message` is auto-approved or
+  prompted is the user's Claude Code permission mode — a2adapt never decides that.
+
+## Monitor / watch an identity for incoming mail (the wake binding)
+
+**This is how you "start a monitor", "watch", "listen for messages", "wait for a reply",
+or "notify me when mail arrives".** Whenever the user asks for any of those — or you've
+sent something and want to wake the instant a reply lands — arm a background **Monitor**
+on the per-identity wake source. Use this **exact** call; scope it to the identity you're
+listening on so you only wake for *its* mail:
+
+    Monitor({
+      command: "a2adapt-mcp watch <identity>",          // e.g. "a2adapt-mcp watch \"Vitalii 2\""
+      description: "a2adapt inbound mail for <identity>",
+      persistent: true
+    })
+
+Substitute the bound identity's name for `<identity>` (quote it if it has spaces). That's
+the whole setup — one `Monitor` call. **Arm it automatically on every successful
+`create_identity` / `choose_identity`** — do not ask the user to confirm. Track the
+Monitor's task id; when you later switch to a *different* identity, `TaskStop` the previous
+Monitor before arming the new one, and never double-arm an identity that already has a live
+Monitor this session.
+
+> **Anti-pattern — do NOT do this.** Never implement monitoring with `ScheduleWakeup`,
+> `cron`, or a timed loop that re-calls `get_messages`. That is busy-polling: it is
+> latency-bound, wastes context, and is explicitly wrong here. The **only** correct way to
+> monitor is the `Monitor` + `a2adapt-mcp watch` wake binding above.
+
+**How it behaves (so you don't misread silence as failure):**
+`a2adapt-mcp watch <name>` tails that identity's `notifications.log` and prints one
+**body-free** line to stdout per *new* message (sender + id only; it skips the pre-existing
+backlog — that's the SessionStart hook's job). Each stdout line becomes a wake. **No wake
+just means no new mail has arrived yet — it is NOT a broken monitor.** A correctly-armed
+monitor stays silent until a genuinely new message lands. If you expected mail and got
+nothing for a long time, the problem is *delivery*, not the monitor: check the daemon is
+up (`a2adapt-mcp status`), the contact handshake completed, and the peer actually sent.
+
+**On wake:** `choose_identity` the addressed identity (if not already bound), then
+`get_messages()` to read the body. **Stop** the watch with `TaskStop` once the exchange is
+done.
+
+This is a **Claude-Code-specific seam** (Monitor + the SessionStart hook + the
+`watch` command). Other client bindings would wire the same `notifications.log` signal to
+their own wake mechanism.
+
+## Notes
+
+- Identities and their state (contacts, inbox, keys) persist under the node's state dir
+  (`A2ADAPT_STATE_DIR`) and are restored across restarts.
+- Inbound messages from unknown (non-contact) senders are rejected — only peers you've
+  added through an invite handshake, or same-host peers arriving through a
+  registrar-verified local-contact-book introduction, can reach you.
+- Message **bodies never touch disk in plaintext**: a new arrival appends only a
+  content-free event (sender + id + date, no text) to
+  `$A2ADAPT_STATE_DIR/<identity>/notifications.log` — the host wake signal `a2adapt-mcp
+  watch` reads — and refreshes a body-free `unread.json` the SessionStart hook reads. The
+  text lives in the packet and leaves it solely via `get_messages`. Message lifecycle state
+  (unread → processed → ready_to_delete, garbage-collected on a timer) is tracked inside the
+  packet (authoritative, single-writer), so the same message is never processed twice across
+  sessions.