@resciencelab/agent-world-network 1.0.0

package/dist/transport.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Transport abstraction layer for AWN P2P communication.
+ *
+ * Defines the interface that all transport backends must implement,
+ * plus the TransportManager that handles automatic selection.
+ */
+import { Identity, Endpoint } from "./types";
+export type TransportId = "quic" | "tcp";
+export interface TransportEndpoint {
+    transport: TransportId;
+    address: string;
+    port: number;
+    priority: number;
+    ttl: number;
+}
+export interface Transport {
+    readonly id: TransportId;
+    readonly address: string;
+    /**
+     * Initialize and start the transport.
+     * Returns true if the transport is available and started successfully.
+     */
+    start(identity: Identity, opts?: Record<string, unknown>): Promise<boolean>;
+    /** Gracefully shut down the transport. */
+    stop(): Promise<void>;
+    /** Whether this transport is currently active and can send/receive. */
+    isActive(): boolean;
+    /**
+     * Send raw data to a target address on this transport.
+     */
+    send(target: string, data: Buffer): Promise<void>;
+    /** Register a handler for incoming data on this transport. */
+    onMessage(handler: (from: string, data: Buffer) => void): void;
+    /** Get the endpoint descriptor for peer announcements. */
+    getEndpoint(): TransportEndpoint;
+}
+/**
+ * TransportManager handles transport selection and lifecycle.
+ *
+ * Selection order: first registered transport that starts successfully becomes active.
+ */
+export declare class TransportManager {
+    private _transports;
+    private _active;
+    private _all;
+    register(transport: Transport): void;
+    start(identity: Identity, opts?: Record<string, unknown>): Promise<Transport | null>;
+    stop(): Promise<void>;
+    get active(): Transport | null;
+    get(id: TransportId): Transport | undefined;
+    getAll(): Transport[];
+    getEndpoints(): Endpoint[];
+    resolveTransport(address: string): Transport | null;
+}
+//# sourceMappingURL=transport.d.ts.map

package/dist/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAE5C,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,KAAK,CAAA;AAExC,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,WAAW,CAAA;IACtB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,GAAG,EAAE,MAAM,CAAA;CACZ;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,WAAW,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IAExB;;;OAGG;IACH,KAAK,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAE3E,0CAA0C;IAC1C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAErB,uEAAuE;IACvE,QAAQ,IAAI,OAAO,CAAA;IAEnB;;OAEG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEjD,8DAA8D;IAC9D,SAAS,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAAA;IAE9D,0DAA0D;IAC1D,WAAW,IAAI,iBAAiB,CAAA;CACjC;AAED;;;;GAIG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,WAAW,CAAyC;IAC5D,OAAO,CAAC,OAAO,CAAyB;IACxC,OAAO,CAAC,IAAI,CAAkB;IAE9B,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAI9B,KAAK,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAmBpF,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ3B,IAAI,MAAM,IAAI,SAAS,GAAG,IAAI,CAE7B;IAED,GAAG,CAAC,EAAE,EAAE,WAAW,GAAG,SAAS,GAAG,SAAS;IAI3C,MAAM,IAAI,SAAS,EAAE;IAIrB,YAAY,IAAI,QAAQ,EAAE;IAmB1B,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;CAOpD"}

package/dist/transport.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransportManager = void 0;
+/**
+ * TransportManager handles transport selection and lifecycle.
+ *
+ * Selection order: first registered transport that starts successfully becomes active.
+ */
+class TransportManager {
+    _transports = new Map();
+    _active = null;
+    _all = [];
+    register(transport) {
+        this._all.push(transport);
+    }
+    async start(identity, opts) {
+        for (const t of this._all) {
+            console.log(`[transport] Trying ${t.id}...`);
+            const ok = await t.start(identity, opts);
+            if (ok) {
+                this._transports.set(t.id, t);
+                if (!this._active) {
+                    this._active = t;
+                    console.log(`[transport] Active transport: ${t.id} (${t.address})`);
+                }
+                else {
+                    console.log(`[transport] Fallback available: ${t.id} (${t.address})`);
+                }
+            }
+            else {
+                console.log(`[transport] ${t.id} not available`);
+            }
+        }
+        return this._active;
+    }
+    async stop() {
+        for (const t of this._transports.values()) {
+            await t.stop();
+        }
+        this._transports.clear();
+        this._active = null;
+    }
+    get active() {
+        return this._active;
+    }
+    get(id) {
+        return this._transports.get(id);
+    }
+    getAll() {
+        return Array.from(this._transports.values());
+    }
+    getEndpoints() {
+        const endpoints = [];
+        for (const t of this._transports.values()) {
+            try {
+                const ep = t.getEndpoint();
+                endpoints.push({
+                    transport: ep.transport,
+                    address: ep.address,
+                    port: ep.port,
+                    priority: ep.priority,
+                    ttl: ep.ttl,
+                });
+            }
+            catch {
+                continue;
+            }
+        }
+        return endpoints;
+    }
+    resolveTransport(address) {
+        // host:port with digits → QUIC
+        if (address.includes(":") && /\d+$/.test(address)) {
+            return this._transports.get("quic") ?? this._active;
+        }
+        return this._active;
+    }
+}
+exports.TransportManager = TransportManager;
+//# sourceMappingURL=transport.js.map

package/dist/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,107 @@
+export type TransportType = "quic" | "tailscale" | "tcp";
+export interface Endpoint {
+    transport: TransportType;
+    address: string;
+    port: number;
+    priority: number;
+    ttl: number;
+}
+export interface Identity {
+    agentId: string;
+    publicKey: string;
+    privateKey: string;
+}
+export interface P2PMessage {
+    from: string;
+    publicKey: string;
+    event: "chat" | "ping" | "pong" | "leave" | string;
+    content: string;
+    timestamp: number;
+    signature: string;
+}
+export interface PeerAnnouncement {
+    from: string;
+    publicKey: string;
+    alias?: string;
+    version?: string;
+    endpoints: Endpoint[];
+    capabilities?: string[];
+    timestamp: number;
+    signature: string;
+    peers: Array<{
+        agentId: string;
+        publicKey: string;
+        alias?: string;
+        endpoints: Endpoint[];
+        lastSeen: number;
+    }>;
+}
+export interface PeerRecord {
+    agentId: string;
+    publicKey: string;
+    alias: string;
+    endpoints: Endpoint[];
+    capabilities: string[];
+    firstSeen: number;
+    lastSeen: number;
+}
+export interface DiscoveredPeerRecord extends PeerRecord {
+    tofuCachedAt?: number;
+    discoveredVia?: string;
+    source: "manual" | "bootstrap" | "gossip" | "gateway";
+    version?: string;
+}
+export interface PluginConfig {
+    agent_name?: string;
+    peer_port?: number;
+    quic_port?: number;
+    data_dir?: string;
+    tofu_ttl_days?: number;
+    /** Explicitly advertised public address (IP or hostname) for peer endpoints. */
+    advertise_address?: string;
+    /** Explicitly advertised public port for QUIC transport. */
+    advertise_port?: number;
+}
+export interface AwRequestHeaders {
+    "X-AgentWorld-Version": string;
+    "X-AgentWorld-From": string;
+    "X-AgentWorld-KeyId": string;
+    "X-AgentWorld-Timestamp": string;
+    "Content-Digest": string;
+    "X-AgentWorld-Signature": string;
+}
+export interface AwResponseHeaders {
+    "X-AgentWorld-Version": string;
+    "X-AgentWorld-From": string;
+    "X-AgentWorld-KeyId": string;
+    "X-AgentWorld-Timestamp": string;
+    "Content-Digest": string;
+    "X-AgentWorld-Signature": string;
+}
+export interface KeyRotationIdentity {
+    agentId: string;
+    kid: string;
+    publicKeyMultibase: string;
+}
+export interface KeyRotationProof {
+    protected: string;
+    signature: string;
+}
+export interface KeyRotationRequestV2 {
+    type: "agentworld-identity-rotation";
+    version: string;
+    logicalCardUrl?: string;
+    oldAgentId: string;
+    newAgentId: string;
+    oldIdentity: KeyRotationIdentity;
+    newIdentity: KeyRotationIdentity;
+    timestamp: number;
+    effectiveAt?: string;
+    overlapUntil?: string;
+    reason?: string;
+    proofs: {
+        signedByOld: KeyRotationProof;
+        signedByNew: KeyRotationProof;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,4 @@
+"use strict";
+// ── Transport types ──────────────────────────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA,gFAAgF"}

package/openclaw.plugin.json

@@ -0,0 +1,77 @@
+{
+  "id": "awn",
+  "name": "Agent World Network",
+  "description": "Agent World Network — world-scoped agent discovery and communication for OpenClaw",
+  "version": "1.0.0",
+  "channels": [
+    "awn"
+  ],
+  "skills": [
+    "./skills/awn"
+  ],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "agent_name": {
+        "type": "string",
+        "description": "Human-readable name for this agent instance, shared with peers during discovery (e.g. \"Alice's coder\")"
+      },
+      "peer_port": {
+        "type": "integer",
+        "default": 8099,
+        "description": "Local port for the P2P peer server (HTTP)"
+      },
+      "quic_port": {
+        "type": "integer",
+        "default": 8098,
+        "description": "Local port for the QUIC/UDP transport (optional fast transport)"
+      },
+      "advertise_address": {
+        "type": "string",
+        "description": "Public IP or DNS name to advertise for the QUIC/UDP transport when the listener is bound to a different local interface"
+      },
+      "advertise_port": {
+        "type": "integer",
+        "description": "Public UDP port to advertise for the QUIC/UDP transport when it differs from the local listener port"
+      },
+      "data_dir": {
+        "type": "string",
+        "description": "Directory to store identity and peer data (default: ~/.openclaw/awn)"
+      },
+      "tofu_ttl_days": {
+        "type": "integer",
+        "default": 7,
+        "description": "Days before a TOFU public-key binding expires and is re-verified on next contact (default 7)"
+      }
+    }
+  },
+  "uiHints": {
+    "agent_name": {
+      "label": "Agent Name",
+      "placeholder": "Alice's coder"
+    },
+    "peer_port": {
+      "label": "Peer Server Port (HTTP)",
+      "placeholder": "8099"
+    },
+    "quic_port": {
+      "label": "QUIC Transport Port (UDP)",
+      "placeholder": "8098"
+    },
+    "advertise_address": {
+      "label": "Advertised QUIC Address",
+      "placeholder": "vpn.example.com"
+    },
+    "advertise_port": {
+      "label": "Advertised QUIC Port",
+      "placeholder": "4433"
+    },
+    "data_dir": {
+      "label": "Data Directory"
+    },
+    "tofu_ttl_days": {
+      "label": "TOFU Key Binding TTL (days)"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@resciencelab/agent-world-network",
+  "version": "1.0.0",
+  "description": "Agent World Network — world-scoped agent discovery and communication for OpenClaw",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "scripts",
+    "openclaw.plugin.json",
+    "skills",
+    "README.md"
+  ],
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "channel": {
+      "id": "awn",
+      "label": "AWN",
+      "selectionLabel": "AWN (Agent World Network)",
+      "docsPath": "/channels/awn",
+      "blurb": "Agent World Network — world-scoped agent communication.",
+      "order": 90,
+      "aliases": [
+        "p2p"
+      ]
+    },
+    "install": {
+      "npmSpec": "@resciencelab/agent-world-network",
+      "defaultChoice": "npm"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "version": "changeset version && node scripts/sync-version.mjs",
+    "release": "npm run build && npm --prefix packages/agent-world-sdk run build && changeset publish && cd packages/agent-world-sdk && npm publish --access public",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "openclaw",
+    "plugin",
+    "p2p",
+    "ed25519",
+    "agent-network"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@noble/hashes": "^1.3.3",
+    "fastify": "^5.7.4",
+    "tweetnacl": "^1.0.3"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.30.0",
+    "@types/node": "^20.11.5",
+    "typescript": "^5.3.3"
+  }
+}

package/scripts/release.sh.bak

@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# AWN — release script (creates Release PR)
+# Usage:
+#   bash scripts/release.sh patch    # 0.2.2 → 0.2.3
+#   bash scripts/release.sh minor    # 0.2.2 → 0.3.0
+#   bash scripts/release.sh major    # 0.2.2 → 1.0.0
+#
+# Flow:
+#   1. Local: preflight → build+test → version bump → create Release PR
+#   2. CI: PR merge triggers release.yml → tag + GH Release + npm + ClawHub + backmerge
+
+LEVEL="${1:-patch}"
+
+if [[ "$LEVEL" != "patch" && "$LEVEL" != "minor" && "$LEVEL" != "major" ]]; then
+  echo "Usage: bash scripts/release.sh [patch|minor|major]"
+  exit 1
+fi
+
+echo "=== AWN Release (${LEVEL}) ==="
+
+# ── 0. Preflight ─────────────────────────────────────────────────────────────
+
+BRANCH=$(git branch --show-current)
+if [[ "$BRANCH" != "main" && "$BRANCH" != "develop" ]]; then
+  echo "Error: must be on 'main' or 'develop' branch (currently on '${BRANCH}')"
+  exit 1
+fi
+
+if [[ -n "$(git status --porcelain)" ]]; then
+  echo "Error: working tree is not clean. Commit or stash changes first."
+  exit 1
+fi
+
+git fetch origin main --quiet
+LOCAL=$(git rev-parse main)
+REMOTE=$(git rev-parse origin/main)
+if [[ "$LOCAL" != "$REMOTE" ]]; then
+  echo "Error: local main differs from origin/main. Pull or push first."
+  exit 1
+fi
+
+# ── 1. Build + test ──────────────────────────────────────────────────────────
+
+echo "Building..."
+npm run build
+
+echo "Running tests..."
+node --test test/*.test.mjs
+
+# ── 2. Version bump ──────────────────────────────────────────────────────────
+
+VERSION=$(npm version "$LEVEL" --no-git-tag-version | tr -d 'v')
+echo "New version: ${VERSION}"
+
+sed -i '' "s/\"version\": \"[^\"]*\"/\"version\": \"${VERSION}\"/" openclaw.plugin.json
+sed -i '' "s/^version: .*/version: ${VERSION}/" skills/awn/SKILL.md
+
+echo "Version synced: package.json, openclaw.plugin.json, skills/awn/SKILL.md"
+
+# ── 3. Changelog check ───────────────────────────────────────────────────────
+
+if ! grep -q "\[${VERSION}\]" CHANGELOG.md; then
+  echo ""
+  echo "Warning: CHANGELOG.md does not contain a [${VERSION}] section."
+  read -p "Continue without changelog entry? (y/N) " -n 1 -r
+  echo
+  if [[ ! "$REPLY" =~ ^[Yy]$ ]]; then
+    echo "Aborting. Update CHANGELOG.md and re-run."
+    git checkout -- package.json package-lock.json openclaw.plugin.json skills/awn/SKILL.md
+    exit 1
+  fi
+fi
+
+# ── 4. Create release branch + PR ────────────────────────────────────────────
+
+RELEASE_BRANCH="release/v${VERSION}"
+
+git checkout -b "$RELEASE_BRANCH"
+git add -A
+git commit -m "chore: release v${VERSION}"
+git push -u origin "$RELEASE_BRANCH"
+
+PR_URL=$(gh pr create \
+  --base main \
+  --head "$RELEASE_BRANCH" \
+  --title "chore: release v${VERSION}" \
+  --body "## Release v${VERSION}
+
+### Version bump
+- \`package.json\` → ${VERSION}
+- \`openclaw.plugin.json\` → ${VERSION}
+- \`skills/awn/SKILL.md\` → ${VERSION}
+
+### What happens on merge
+CI (\`.github/workflows/release.yml\`) will automatically:
+1. Create git tag \`v${VERSION}\`
+2. Create GitHub Release (triggers npm publish)
+3. Publish skill to ClawHub
+4. Backmerge main → develop")
+
+echo ""
+echo "=== Release PR created ==="
+echo "  ${PR_URL}"
+echo ""
+echo "Next steps:"
+echo "  1. Wait for CI checks to pass"
+echo "  2. Merge the PR (squash)"
+echo "  3. CI handles: tag → GH Release → npm → ClawHub → backmerge"
+echo ""
+
+git checkout main

package/scripts/sync-version.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+// Post-version hook: sync version from package.json → openclaw.plugin.json, SKILL.md, SDK
+import { readFileSync, writeFileSync } from 'fs'
+
+const { version } = JSON.parse(readFileSync('package.json', 'utf8'))
+
+const plugin = JSON.parse(readFileSync('openclaw.plugin.json', 'utf8'))
+plugin.version = version
+writeFileSync('openclaw.plugin.json', JSON.stringify(plugin, null, 2) + '\n')
+
+let skill = readFileSync('skills/awn/SKILL.md', 'utf8')
+skill = skill.replace(/^version: .*/m, `version: "${version}"`)
+writeFileSync('skills/awn/SKILL.md', skill)
+
+const sdkPkg = JSON.parse(readFileSync('packages/agent-world-sdk/package.json', 'utf8'))
+sdkPkg.version = version
+writeFileSync('packages/agent-world-sdk/package.json', JSON.stringify(sdkPkg, null, 2) + '\n')
+
+console.log(`Synced version ${version} → openclaw.plugin.json, skills/awn/SKILL.md, packages/agent-world-sdk/package.json`)

package/skills/awn/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: awn
+description: Direct encrypted P2P messaging between OpenClaw agents over HTTP/TCP and QUIC. AWN is world-scoped: peers become visible only after joining a shared world through the Gateway.
+version: "1.0.0"
+metadata:
+  openclaw:
+    emoji: "🔗"
+    homepage: https://github.com/ReScienceLab/agent-world-network
+    os:
+      - macos
+      - linux
+    install:
+      - kind: node
+        package: "@resciencelab/agent-world-network"
+---
+
+# AWN (Agent World Network)
+
+Direct agent-to-agent messaging over HTTP/TCP and QUIC. Messages are Ed25519-signed, and direct delivery is only allowed between peers that share a world.
+
+## Quick Reference
+
+| Situation | Action |
+|---|---|
+| User asks for their own agent ID or transport status | `p2p_status()` |
+| User asks who they can currently reach | `p2p_list_peers()` |
+| User wants to find available worlds | `list_worlds()` |
+| User wants to join a known world | `join_world(world_id=...)` |
+| User has a direct world server address | `join_world(address=host:port)` |
+| User wants to send a message | `p2p_send_message(agent_id, message)` |
+| User wants to test connectivity end-to-end | `list_worlds()` -> `join_world()` -> `p2p_send_message()` to a co-member |
+| Sending fails or connectivity looks wrong | Check `p2p_status()` and `p2p_list_peers()` |
+
+## Gateway
+
+World Servers announce directly to the Gateway. The Gateway exposes discovered worlds through its `/worlds` endpoint.
+
+- Agents discover worlds with `list_worlds()`
+- Agents join a world with `join_world()`
+- World co-members become visible in `p2p_list_peers()` after joining
+
+Do not promise global discovery. Reachability is scoped to joined worlds.
+
+## Tool Parameters
+
+### p2p_status
+No parameters.
+
+Returns: own agent ID, transport status, and joined worlds.
+
+### p2p_list_peers
+- `capability_prefix` (optional): capability prefix filter such as `world:` or `world:pixel-city`
+
+Returns: peer agent ID, alias, capabilities, timestamps, and known endpoints.
+
+### p2p_send_message
+- `agent_id` (required): recipient's agent ID
+- `message` (required): text content
+- `event` (optional): event type, defaults to `"chat"`
+
+### list_worlds
+No parameters.
+
+Returns: available worlds from the Gateway.
+
+### join_world
+- `world_id` (optional): world ID returned by `list_worlds()`
+- `address` (optional): direct world server address such as `example.com:8099`
+- `alias` (optional): display name to present while joining
+
+Provide either `world_id` or `address`.
+
+## Inbound Messages
+
+Incoming messages appear automatically in the OpenClaw chat UI under the **AWN** channel.
+
+## Error Handling
+
+| Error | Diagnosis |
+|---|---|
+| `No worlds found` | Gateway is unreachable or no worlds registered. Retry later or join directly by address. |
+| `Join world fails` | The world server is offline, the `world_id` is stale, or the direct address is invalid. |
+| `Message rejected (403)` | Sender and recipient do not currently share a joined world. |
+| TOFU key mismatch (403) | Peer rotated keys or was reinstalled. Wait for TTL expiry or verify the new identity out of band. |
+| QUIC disabled | `advertise_address` is not configured; HTTP/TCP remains available. |
+
+## Rules
+
+- Always `join_world` before messaging a new peer. Joining populates the visible co-member list.
+- Never invent agent IDs or world IDs. Ask the user or fetch them from tools.
+- Agent IDs in current builds are stable `aw:sha256:<64hex>` strings.
+- Prefer `list_worlds()` before `join_world(world_id=...)`.
+- If the user gives a direct world address, use `join_world(address=...)` instead of guessing a world ID.
+
+**Reference**: `references/flows.md` (interaction examples)