@tloncorp/openclaw 0.4.3 → 0.6.0

package/README.md

@@ -4,17 +4,17 @@ Tlon/Urbit channel plugin for [OpenClaw](https://github.com/openclaw/openclaw).
 
 ## Features
 
-- **DMs**: Receive and respond to direct messages
-- **Group Channels**: Participate in group chats (mention-triggered or open mode)
-- **Thread Replies**: Support for threaded conversations
-- **Rich Content**: Images, links, and formatted text
-- **Ship Authorization**: Allowlist ships for DM access
-- **Channel Authorization**: Per-channel ship allowlists with open/restricted modes
-- **Approval System**: Approve/deny new DMs, channel mentions, and group invites via DM
-- **Settings Store**: Hot-reload config via Urbit settings-store (no restart needed)
-- **Auto-Discovery**: Automatically monitors all channels in joined groups
-- **Cite Resolution**: Parse and fetch quoted message content
-- **Optional Telemetry**: Explicit PostHog opt-in for hosted analytics
+-   **DMs**: Receive and respond to direct messages
+-   **Group Channels**: Participate in group chats (mention-triggered or open mode)
+-   **Thread Replies**: Support for threaded conversations
+-   **Rich Content**: Images, links, and formatted text
+-   **Ship Authorization**: Allowlist ships for DM access
+-   **Channel Authorization**: Per-channel ship allowlists with open/restricted modes
+-   **Approval System**: Approve/deny new DMs, channel mentions, and group invites via DM
+-   **Settings Store**: Hot-reload config via Urbit settings-store (no restart needed)
+-   **Auto-Discovery**: Automatically monitors all channels in joined groups
+-   **Cite Resolution**: Parse and fetch quoted message content
+-   **Optional Telemetry**: Explicit PostHog opt-in for hosted analytics
 
 ## Installation
 
@@ -22,82 +22,81 @@ This plugin is included with OpenClaw. Enable it in your config:
 
 ```yaml
 channels:
-  tlon:
-    enabled: true
-    ship: "~your-ship"
-    url: "https://your-ship.tlon.network"
-    code: "your-access-code"
+    tlon:
+        enabled: true
+        ship: '~your-ship'
+        url: 'https://your-ship.tlon.network'
+        code: 'your-access-code'
 ```
 
 ### Full Configuration Example
 
 ```yaml
 channels:
-  tlon:
-    enabled: true
-    ship: "~your-ship"
-    url: "https://your-ship.tlon.network"
-    code: "your-access-code"
-
-    # Owner receives approval requests and can manage the bot
-    ownerShip: "~your-main-ship"
-
-    # Ships allowed to DM the bot directly
-    dmAllowlist:
-      - "~trusted-friend"
-      - "~another-ship"
-
-    # Auto-accept settings
-    autoAcceptDmInvites: true # Accept DMs from ships in dmAllowlist
-    autoAcceptGroupInvites: false # Require approval for group invites
-
-    # Channel discovery
-    autoDiscoverChannels: true # Monitor all channels in joined groups
-    groupChannels: # Additional channels to monitor explicitly
-      - "chat/~host-ship/channel-name"
-
-    # Per-channel authorization
-    authorization:
-      channelRules:
-        "chat/~host/public-channel":
-          mode: "open" # Anyone can interact
-        "chat/~host/private-channel":
-          mode: "restricted"
-          allowedShips:
-            - "~specific-ship"
-
-    # Ships authorized by default for restricted channels
-    defaultAuthorizedShips:
-      - "~always-allowed"
-
-    # Show model info in responses
-    showModelSignature: false
-
-    # Optional PostHog telemetry. Disabled unless explicitly enabled.
-    telemetry:
-      enabled: true
-      apiKey: "phc_your_project_api_key"
-      host: "https://us.i.posthog.com"
+    tlon:
+        enabled: true
+        ship: '~your-ship'
+        url: 'https://your-ship.tlon.network'
+        code: 'your-access-code'
+
+        # Owner receives approval requests and can manage the bot
+        ownerShip: '~your-main-ship'
+
+        # Ships allowed to DM the bot directly
+        dmAllowlist:
+            - '~trusted-friend'
+            - '~another-ship'
+
+        # Auto-accept settings
+        autoAcceptDmInvites: true # Accept DMs from ships in dmAllowlist
+        autoAcceptGroupInvites: false # Require approval for group invites
+
+        # Channel discovery
+        autoDiscoverChannels: true # Monitor all channels in joined groups
+        groupChannels: # Additional channels to monitor explicitly
+            - 'chat/~host-ship/channel-name'
+
+        # Per-channel authorization
+        authorization:
+            channelRules:
+                'chat/~host/public-channel':
+                    mode: 'open' # Anyone can interact
+                'chat/~host/private-channel':
+                    mode: 'restricted'
+                    allowedShips:
+                        - '~specific-ship'
+
+        # Ships authorized by default for restricted channels
+        defaultAuthorizedShips:
+            - '~always-allowed'
+
+        # Show model info in responses
+        showModelSignature: false
+
+        # Optional PostHog telemetry. Disabled unless explicitly enabled.
+        telemetry:
+            enabled: true
+            apiKey: 'phc_your_project_api_key'
+            host: 'https://us.i.posthog.com'
 ```
 
 ## Telemetry
 
-Telemetry is disabled by default. The plugin only sends tlemetry events when `channels.tlon.telemetry.enabled`
-is set to `true` and an API key is configured.
+Telemetry is disabled by default. The plugin only sends telemetry events when `channels.tlon.telemetry.enabled` is set to `true` and an API key is configured.
 
-When enabled, the plugin captures a single `TlonBot Reply Handled` event each time it enters the OpenClaw reply
-flow. The event summarizes OpenClaw usage (tools used, character count, etc.), but does not log message content.
+Every event carries content-free version identity: `harness: "openclaw"`, `pluginVersion`, `pluginCommit`, `pluginFingerprint`, plus Hermes-compatible `adapterVersion` and `adapterFingerprint` fields for shared PostHog charts.
 
-The plugin does not enable telemetry automatically just because an API key is present. `enabled: true` is
-required so open-source installs do not phone home by default.
+When enabled, the plugin captures `TlonBot Gateway Connected` after subscriptions are active, `TlonBot Reply Handled` after each OpenClaw reply flow, `TlonBot Outbound Routed` for route-dependent sends, and heartbeat nudge events. `TlonBot Gateway Connected` also includes the resolved `tlon` CLI version as `tlonSkillVersion`. These summarize counts, routing, model/tool usage, and delivery status, but do not log message content.
+
+The plugin does not enable telemetry automatically just because an API key is present. `enabled: true` is required so open-source installs do not phone home by default.
 
 ## Approval System
 
 The approval system lets you control who can interact with your bot. When `ownerShip` is configured, you'll receive DM notifications for:
 
-- **DM requests** from ships not on your `dmAllowlist`
-- **Channel mentions** from ships not authorized for that channel
-- **Group invites** (if `autoAcceptGroupInvites` is false)
+-   **DM requests** from ships not on your `dmAllowlist`
+-   **Channel mentions** from ships not authorized for that channel
+-   **Group invites** (if `autoAcceptGroupInvites` is false)
 
 ### Usage
 
@@ -110,29 +109,41 @@ New DM request from ~sampel-palnet:
 Reply "approve", "deny", or "block" (ID: dm-1234567890-abc)
 ```
 
-- **approve**: Allow the interaction and add to allowlist. Original message is processed.
-- **deny**: Reject silently. Ship can try again later.
-- **block**: Permanently block using Tlon's native blocking.
+-   **approve**: Allow the interaction and add to allowlist. Original message is processed.
+-   **deny**: Reject silently. Ship can try again later.
+-   **block**: Permanently block using Tlon's native blocking.
 
 ### Admin Commands
 
 The owner can send these commands via DM:
 
-| Command         | Description                    |
-| --------------- | ------------------------------ |
-| `blocked`       | List all blocked ships         |
-| `pending`       | List pending approval requests |
-| `unblock ~ship` | Unblock a ship                 |
+| Command        | Description                                |
+| -------------- | ------------------------------------------ |
+| `tlon version` | Show OpenClaw Tlon plugin version identity |
+| `tlon-version` | Legacy alias for `tlon version`            |
+| `banned`       | List all blocked ships                     |
+| `pending`      | List pending approval requests             |
+| `unban ~ship`  | Unblock a ship                             |
+
+`/tlon version` and the legacy `/tlon-version` alias report the same field-per-line summary as Hermes:
+
+```
+Harness: OpenClaw
+Adapter Version: 0.4.3
+Tlon Skill: 0.3.2
+Fingerprint: fp1:8aa23ca2bc8d
+Source: no git checkout
+```
 
 ## Bundled Skill
 
 This plugin bundles [@tloncorp/tlon-skill](https://www.npmjs.com/package/@tloncorp/tlon-skill) which provides CLI commands for:
 
-- Contacts and profile management
-- Channel listing and history
-- Group administration
-- Message posting and reactions
-- Settings management
+-   Contacts and profile management
+-   Channel listing and history
+-   Group administration
+-   Message posting and reactions
+-   Settings management
 
 The skill is automatically available to your agent. For standalone usage, see the [tlon-skill repo](https://github.com/tloncorp/tlon-skill).
 
@@ -144,19 +155,19 @@ Full documentation: https://docs.openclaw.ai/channels/tlon
 
 ### Prerequisites
 
-- Docker
-- [GitHub CLI](https://cli.github.com/) (`gh`) authenticated with tloncorp access
-- A local Urbit ship (e.g., on `http://localhost:8080`)
-- Anthropic API key (or OpenRouter for alternative models)
+-   Docker
+-   [GitHub CLI](https://cli.github.com/) (`gh`) authenticated with tloncorp access
+-   A local Urbit ship (e.g., on `http://localhost:8080`)
+-   Anthropic API key (or OpenRouter for alternative models)
 
 ### Quick Start
 
 ```bash
-# 1. Clone this repo
-gh repo clone tloncorp/openclaw-tlon
-cd openclaw-tlon
+# 1. Clone the tlon-apps monorepo (this package lives at packages/openclaw)
+gh repo clone tloncorp/tlon-apps
+cd tlon-apps/packages/openclaw
 
-# 2. Run setup (clones tlonbot + tlon-apps, creates .env)
+# 2. Run setup (clones tlonbot next to the monorepo, creates .env)
 ./dev/setup.sh
 
 # 3. Edit .env with your credentials
@@ -176,48 +187,26 @@ docker compose --env-file .env -f dev/docker-compose.yml up --build
 ```
 parent/
 ├── tlonbot/            # Bot prompts + image-search extension (optional)
-├── tlon-apps/          # Source repo for dev-only local @tloncorp/api overrides
-│                       # (or another checkout such as "homestead")
-└── openclaw-tlon/      # This repo
+└── tlon-apps/          # This monorepo
+    └── packages/
+        ├── api/        # @tloncorp/api (workspace dependency)
+        ├── tlon-skill/ # @tloncorp/tlon-skill (workspace dependency)
+        └── openclaw/   # This package
 ```
 
-`@tloncorp/api` and `@tloncorp/tlon-skill` are installed via npm for normal installs. During Docker dev, the entrypoint will also link a local `@tloncorp/api` override from `${TLON_APPS_DIR:-../tlon-apps}/packages/api` when that checkout has been built.
-
-The dev override uses the real `tlon-apps/packages/api` package, similar to the old `api-beta` workflow. You still rebuild `tlon-apps` separately so its `dist/` stays current, and the container startup will link that local package instead of using the published npm copy.
-
-If your local checkout is named `homestead` instead of `tlon-apps`, set:
+`@tloncorp/api` and `@tloncorp/tlon-skill` are `workspace:^` dependencies, so on the host your editor and TypeScript resolve them straight from the sibling packages — no linking needed. After changing the API surface, rebuild it so `dist/` stays current:
 
 ```bash
-export TLON_APPS_DIR=/absolute/path/to/homestead
+pnpm --filter @tloncorp/api build
 ```
 
-`pnpm dev`, `pnpm dev:api:link`, and the Docker dev override will all use that path.
-
-If you want to modify `@tloncorp/api` locally while working in this repo, first link the local package into `openclaw-tlon` so your editor and local TypeScript resolve against `${TLON_APPS_DIR:-../tlon-apps}/packages/api`:
-
-```bash
-pnpm dev:api:link
-```
-
-That makes `openclaw-tlon` resolve `@tloncorp/api` to `${TLON_APPS_DIR:-../tlon-apps}/packages/api` on your machine. After changing the API surface, rebuild it there:
-
-```bash
-pnpm --dir "${TLON_APPS_DIR:-../tlon-apps}" --filter @tloncorp/api build
-```
-
-To switch back to the published npm package on your host:
-
-```bash
-pnpm dev:api:unlink
-```
+Inside the Docker dev container, the package is copied out of the workspace and its workspace deps are resolved to published npm versions; the entrypoint then links local overrides for `@tloncorp/api` (from the mounted monorepo's `packages/api`, when built) and `@tloncorp/tlon-skill` (built from source) on top.
 
 ### Making Changes
 
-1. Edit code in this repo or `${TLON_APPS_DIR:-../tlon-apps}/packages/api`
-2. If you changed the API package, rebuild it first:
-   `pnpm --dir "${TLON_APPS_DIR:-../tlon-apps}" --filter @tloncorp/api build`
+1. Edit code in this package or `packages/api`
+2. If you changed the API package, rebuild it first: `pnpm --filter @tloncorp/api build`
 3. Restart container: `docker compose --env-file .env -f dev/docker-compose.yml up --build`
-4. For faster iteration, run OpenClaw directly on host with npm link
 
 ## Testing
 
@@ -257,11 +246,11 @@ pnpm test:integration
 
 This will:
 
-- Start 3 fakezod ships (~zod as bot, ~ten as test user, ~mug as third party)
-- Build and start an OpenClaw container with the plugin
-- Wait for ships, gateway, and SSE subscriptions
-- Run all test cases in `test/cases/`
-- Tear everything down on exit
+-   Start 3 fakezod ships (~zod as bot, ~ten as test user, ~mug as third party)
+-   Build and start an OpenClaw container with the plugin
+-   Wait for ships, gateway, and SSE subscriptions
+-   Run all test cases in `test/cases/`
+-   Tear everything down on exit
 
 **Run a specific test:**
 
@@ -279,7 +268,7 @@ For iterative development — you manage the ships and gateway yourself, tests r
 ./dev/setup.sh
 ```
 
-This clones `tlonbot` and `tlon-apps` as sibling directories and creates `.env` from `.env.example` if it doesn't exist. `@tloncorp/api` still installs from npm by default, but the dev container will link a local override from `tlon-apps/packages/api` so you can test API changes without publishing first.
+This clones `tlonbot` next to the tlon-apps monorepo and creates `.env` from `.env.example` if it doesn't exist. Inside the dev container, the entrypoint links a local `@tloncorp/api` override from the monorepo's `packages/api` (when built) so you can test API changes without publishing first.
 
 **2. Edit `.env`:**
 
@@ -340,16 +329,16 @@ pnpm test:manual
 
 This will:
 
-- Start 3 fakezod ships and the OpenClaw gateway in Docker
-- Wait for everything to be ready
-- Print ship URLs, access codes, and gateway address
-- Tail gateway logs (Ctrl+C to stop and tear down)
+-   Start 3 fakezod ships and the OpenClaw gateway in Docker
+-   Wait for everything to be ready
+-   Print ship URLs, access codes, and gateway address
+-   Tail gateway logs (Ctrl+C to stop and tear down)
 
 Ships are accessible via browser:
 
-- **~zod** (bot): http://localhost:8080 — code: `lidlut-tabwed-pillex-ridrup`
-- **~ten** (user): http://localhost:8081 — code: `lapseg-nolmel-riswen-hopryc`
-- **~mug** (3rd party): http://localhost:8082 — code: `ravsut-bolryd-hapsum-pastul`
+-   **~zod** (bot): http://localhost:8080 — code: `lidlut-tabwed-pillex-ridrup`
+-   **~ten** (user): http://localhost:8081 — code: `lapseg-nolmel-riswen-hopryc`
+-   **~mug** (3rd party): http://localhost:8082 — code: `ravsut-bolryd-hapsum-pastul`
 
 To tear down without attaching to logs:
 
@@ -369,12 +358,12 @@ To test the `image_search` tool and Brave-powered `web_search`:
 
 1. Get a [Brave Search API key](https://brave.com/search/api/)
 2. Add to `.env`: `BRAVE_API_KEY=BSA...`
-3. Clone [tlonbot](https://github.com/tloncorp/tlonbot) as a sibling directory:
-   ```bash
-   cd .. && gh repo clone tloncorp/tlonbot
-   ```
+3. Clone [tlonbot](https://github.com/tloncorp/tlonbot) next to the tlon-apps monorepo root:
+    ```bash
+    gh repo clone tloncorp/tlonbot ../../../tlonbot
+    ```
 
-When `../tlonbot` exists, `docker-compose.local.yml` mounts it automatically, making the `image-search` plugin available. The entrypoint patches the config to load it if present.
+When that checkout exists (override the location with `TLONBOT_DIR`), `docker-compose.local.yml` mounts it automatically, making the `image-search` plugin available. The entrypoint patches the config to load it if present.
 
 Without these, `web_search` falls back to whatever provider is available, and `image_search` returns a "no API key" error — tests that don't depend on image search still pass.