@openclaw/crabline 0.1.11 → 0.1.13

package/README.md

@@ -5,8 +5,10 @@
 Deterministic local messaging-channel mocks for OpenClaw QA.
 
 `crabline` is config-driven, CI-friendly, and deliberately has no `openclaw`
-dependency. It can run fixture-level local mocks, and it can also serve local
-provider APIs that OpenClaw live adapters can target during deterministic QA.
+dependency. A fixture-level **local mock provider** is a Crabline adapter used
+directly by fixture commands. A **local provider server** is a separate process
+that the Crabline channel driver starts so a real OpenClaw channel plugin can
+exercise its normal provider protocol during deterministic QA.
 
 ## What It Provides
 
@@ -15,16 +17,17 @@ provider APIs that OpenClaw live adapters can target during deterministic QA.
   `whatsapp`, and `zalo`
 - a `script` bridge for channels that are still exercised by external commands
 - per-provider local webhook endpoints for inbound events
-- local provider servers for live-adapter smoke tests for Mattermost, Matrix,
-  Signal, Slack, Telegram, WhatsApp, and Zalo
+- local provider servers for Crabline channel-driver tests for Discord,
+  Mattermost, Matrix, Signal, Slack, Telegram, WhatsApp, and Zalo
 - JSONL recorder files for deterministic wait/watch behavior
 - nonce-based `send`, `roundtrip`, `agent`, `probe`, `run`, `watch`, and
   `doctor` commands
 - text output by default and stable `--json` output for automation
 
-Crabline local servers are not live-provider coverage. They let OpenClaw run its
-normal channel adapter code against a local provider-shaped API. Release lanes
-still need the `live` driver and real provider credentials.
+Crabline local provider servers are not live-provider coverage and are not the
+fixture-level local mock provider feature. They let the real OpenClaw channel
+plugin run against a local provider-shaped API. Release lanes still need the
+`live` driver and real provider credentials.
 
 ## Install
 
@@ -41,6 +44,11 @@ pnpm dev fixtures --config fixtures/examples/crabline.example.yaml
 pnpm dev roundtrip telegram-dm --config fixtures/examples/crabline.example.yaml
 ```
 
+The source checkout does not link its own `crabline` bin into
+`node_modules/.bin`, so use `pnpm dev` there rather than
+`pnpm exec crabline`. An installed package exposes the `crabline` command used
+in the examples below.
+
 ## Quality Gate
 
 ```bash
@@ -98,6 +106,10 @@ Telegram `secretToken`, and Zalo `webhookSecret` enforce provider-native
 webhook authentication. Feishu `verificationToken` remains an additional or
 loopback-only callback check. Microsoft Teams also requires `appId` for
 non-loopback or explicitly public webhook endpoints.
+Authenticated external webhook ingress must advertise an HTTPS `publicUrl`;
+plain HTTP is limited to loopback-local testing.
+Feishu text callbacks require valid JSON-encoded `message.content`; malformed
+content is rejected.
 
 ## Built-In Mock Channels
 
@@ -134,15 +146,83 @@ them only from sources you trust and review changes before use.
 
 ## Local Provider Servers
 
-`serve` starts provider-shaped HTTP APIs for OpenClaw live adapters. This is the
-preferred Smoke CI path because OpenClaw still uses its normal channel adapter,
-but the provider endpoint is local and deterministic.
+`serve` starts local provider servers for real OpenClaw channel plugins. This is
+the preferred Crabline channel-driver path because the plugin still uses its
+normal provider protocol while the provider endpoint is local and
+deterministic. It does not use Crabline's fixture-level local mock provider.
+
+Commands in this section use the installed-package form. In a source checkout,
+replace `crabline` with `pnpm dev`.
+
+`serve` never accepts credential values in command-line arguments. Set
+`CRABLINE_ACCESS_TOKEN`, `CRABLINE_ADMIN_TOKEN`, `CRABLINE_BOT_TOKEN`, or
+`CRABLINE_SIGNING_SECRET`, or pass a bounded JSON object through a file
+descriptor. Package runners should use stdin:
+
+```bash
+pnpm dev --json serve slack --credentials-fd 0 < .crabline/serve-credentials.json
+```
+
+The installed CLI can also use an inherited descriptor when its launcher
+preserves descriptors above 2:
+
+```bash
+crabline --json serve slack --credentials-fd 3 3< .crabline/serve-credentials.json
+```
+
+The JSON fields are `accessToken`, `adminToken`, `botToken`, and
+`signingSecret`. File-descriptor values override environment fallbacks. Do not
+pass descriptors above 2 through package runners such as `pnpm`; use fd 0
+instead. Keep credential files owner-readable or pipe the JSON directly from a
+secret manager.
+
+Ready files contain generated provider and admin credentials. Crabline creates
+or replaces them with POSIX mode `0600`, but the parent directory still needs
+to be private. Exclude ready files from version control and CI artifact
+collection, and delete them after use. On non-POSIX or shared filesystems,
+verify the effective ACLs before publishing one.
 
 Library callers can pass `onEvent` to `startCrablineServer`, an individual
 provider server, or `startOpenClawCrablineAdapter`. Crabline awaits the callback
 after appending each API/admin event to `recorderPath`, so callers can react in
 process while retaining the JSONL artifact as durable evidence.
 
+Recorder files should normally have one filesystem name. If multiple processes
+cannot share the same OS account home, the home is read-only, or they write
+through hardlinks to the same recorder inode, set
+`CRABLINE_RECORDER_LOCK_DIR` to the same absolute writable directory for every
+writer. Pre-create that directory with the ownership, group, or ACLs required
+by those writers. Crabline refuses hardlinked server-recorder writes without
+this shared lock namespace. The configured path must be canonical and contain
+no symlink components. Scope each lock directory to one recorder filesystem;
+lock identities omit device numbers so containers that mount the same inode
+under different device IDs still coordinate. Otherwise, Unix writers coordinate
+through the OS account's `~/.cache/crabline/locks/server-recorder` namespace.
+
+Discord:
+
+```bash
+crabline --json serve discord --ready-file .crabline/discord-server.json
+```
+
+The manifest contains the bot/application identity, bot token, REST API root,
+Gateway metadata endpoint, Gateway WebSocket URL, authenticated admin ingress,
+and recorder path. The server implements the Discord REST v10 and Gateway
+subset used by the real OpenClaw Discord plugin: bot identity, `/gateway/bot`,
+JSON Gateway HELLO/IDENTIFY/READY/heartbeat/resume, DM and guild text channels,
+message sends and replies, typing, basic guild/member lookups, and application
+command registration. Admin ingress turns an injected user message into a
+normal `MESSAGE_CREATE` Gateway dispatch.
+
+This local provider server is separate from the fixture-level Discord local
+mock provider listed under Built-In Mock Channels. The fixture adapter models
+Discord interactions directly for Crabline commands; the server lets a real
+Discord client exercise provider-native REST and Gateway boundaries.
+
+The supported Gateway is v10 JSON with one shard. Transport compression,
+voice, interactions, attachments/multipart uploads, audit logs, and Discord's
+distributed permission and rate-limit systems are outside the current subset.
+
 Mattermost:
 
 ```bash
@@ -153,6 +233,7 @@ The JSON manifest contains:
 
 - `baseUrl`: OpenClaw `channels.mattermost.baseUrl` / `MATTERMOST_URL`
 - `botToken`: OpenClaw `channels.mattermost.botToken` / `MATTERMOST_BOT_TOKEN`
+- `webhookToken` / `MATTERMOST_TOKEN`: verifies native outgoing webhook posts
 - `endpoints.websocketUrl`: native Mattermost WebSocket endpoint
 - `adminToken`: send this as the `X-Crabline-Admin-Token` header when posting
   test user messages
@@ -163,7 +244,10 @@ The server implements a Mattermost API subset for text DM and channel
 roundtrips, including REST authentication/status codes, WebSocket
 authentication and `hello`, sequenced events, typing, and post
 create/edit/delete events. Admin ingress is only the test control plane;
-injected messages are delivered to clients as native `posted` events.
+injected messages require native 26-character lowercase channel/user IDs and
+are delivered to clients as channel-scoped native `posted` events. Optional
+`channelName` and `channelDisplayName` values populate the native event fields.
+`POST /api/v4/posts` requires a JSON media type.
 
 Matrix:
 
@@ -187,7 +271,9 @@ The server implements an unencrypted Matrix Client-Server API subset including
 `whoami`, filters, push rules, joined rooms and members, room state, `/sync`,
 room event sends, typing, and read receipts. Admin ingress is only the test
 control plane; injected messages are delivered to clients as native
-`m.room.message` events through `/sync`.
+`m.room.message` events through `/sync`. Optional `roomName` sets newly created
+room state, `direct: true` publishes `m.direct` account data, and `threadId`
+accepts the raw Matrix root event ID used in the native thread relation.
 
 Slack:
 
@@ -208,8 +294,8 @@ The JSON manifest contains:
 - `endpoints.eventsUrl`: local Slack Events API endpoint
 - `recorderPath`: JSONL file of local provider API/admin traffic
 
-The admin token is generated randomly unless `--admin-token <token>` is
-provided. Implemented Slack Web API endpoints include `auth.test`,
+The admin token is generated randomly unless `adminToken` is supplied through
+the credential ingress above. Implemented Slack Web API endpoints include `auth.test`,
 `chat.postMessage`, `conversations.open`, `conversations.info`,
 `conversations.history`, and `conversations.replies`.
 
@@ -251,16 +337,19 @@ The JSON manifest contains:
   messages; OpenClaw reads them through Telegram `getUpdates`
 - `recorderPath`: JSONL file of local provider API/admin traffic
 
-The admin token is generated randomly unless `--admin-token <token>` is
-provided. The inbound endpoint rejects requests without the matching admin
-header (or `Authorization: Bearer <token>`).
+The admin token is generated randomly unless `adminToken` is supplied through
+the credential ingress above. The inbound endpoint rejects requests without
+the matching admin header (or `Authorization: Bearer <token>`).
 
 Implemented Telegram Bot API endpoints include `getMe`, `sendMessage`,
 `sendPhoto`, `sendDocument`, `sendVideo`, `sendAudio`, `sendAnimation`, `editMessageText`,
 `deleteMessage`, `setMessageReaction`, `createForumTopic`, `editForumTopic`,
 `pinChatMessage`, `unpinChatMessage`, `getUpdates`, `deleteWebhook`,
 `setWebhook`, `setMyCommands`, `deleteMyCommands`, `sendChatAction`, and
-`answerCallbackQuery`.
+`answerCallbackQuery`. Webhook secrets use Telegram's 1-256 character
+letter/digit/underscore/hyphen alphabet. Text and caption fields enforce native
+string types and 4,096/1,024 UTF-16 limits, entity metadata is retained, and
+`@username` method targets resolve to numeric `Chat.id` values.
 
 WhatsApp:
 
@@ -286,7 +375,6 @@ The JSON manifest contains:
 - `endpoints.adminInboundUrl`: authenticated POST endpoint for test user
   messages using the WhatsApp Business webhook payload shape
 - `endpoints.messagesUrl`: provider-native Cloud API message and status endpoint
-- `endpoints.statusUrl`: alias for the same provider-native status endpoint
 - `recorderPath`: JSONL file of local provider API/admin traffic and Baileys
   WebSocket stanzas
 
@@ -301,7 +389,8 @@ Group outbound uses sender-key `skmsg` encryption and is outside this supported
 subset, so OpenClaw Crabline outbound targets are direct users only. Group
 inbound injection remains supported. The WebSocket endpoint rejects clients
 that do not present the access token embedded in the manifest URL. The admin
-token is generated randomly unless `--admin-token <token>` is provided.
+token is generated randomly unless `adminToken` is supplied through the
+credential ingress above.
 
 OpenClaw bridge callers should post injected user messages with the
 `providerUrl`, `providerHeaders`, and `providerBody` returned by
@@ -331,7 +420,9 @@ API methods accept GET query parameters or POST requests. Admin
 ingress injects a native Zalo update into the active polling or webhook
 transport. Webhook delivery posts the native `{ event_name, message }` update
 directly. OpenClaw-specific endpoint, config, and target mapping remain in the
-isolated bridge.
+isolated bridge. Programmatic `startZaloServer()` callers can tune the retained
+polling queue with `maxPendingInboundEvents` and `maxPendingInboundBytes`; the
+byte limit defaults to 64 MiB.
 
 The admin ingress accepts JSON like:
 
@@ -367,13 +458,34 @@ target:
 Examples:
 
 - Slack conversations: `C1234567890`, `G1234567890`, or `D1234567890`
+- Slack direct sends may also target user IDs such as `U1234567890` or
+  `W1234567890`
 - Slack threads: `1700000000.000100`
 - Telegram chats: `-1001234567890` or `@channelusername`
 - Telegram topics: `42`
-- WhatsApp Cloud API users: digits-only `wa_id` values such as `15551234567`
-- WhatsApp groups: `120363001234567890@g.us`
+- Telegram username targets require `@`, contain 5-32 letters, digits, or
+  underscores, and normalize to lowercase. Numeric chat IDs must be nonzero and
+  have an absolute value no greater than `2^52 - 1`.
+- Built-in WhatsApp Cloud API users: digits-only `wa_id` values such as
+  `15551234567`
+- Built-in WhatsApp Cloud API fixtures do not support `threadId` targets.
+- OpenClaw WhatsApp bridge users: `15551234567@s.whatsapp.net`
+  (legacy `15551234567@c.us` inputs are accepted and canonicalized)
+- OpenClaw WhatsApp bridge groups: `120363001234567890@g.us`
 - Discord channels and threads: Discord snowflake ids such as
   `123456789012345678`
+- iMessage recipients: E.164 phone numbers such as `+15551234567`, email
+  addresses such as `user@example.com`, or chat GUIDs such as
+  `iMessage;-;chat-guid` and `SMS;+;chat-guid`
+- Matrix rooms: scoped IDs such as `!abcdef:matrix.org` or Matrix v12
+  domainless room IDs; thread IDs are raw root event IDs such as
+  `$eventid:matrix.org`
+- Mattermost channels, users, and root posts: exactly 26 lowercase alphanumeric
+  characters, such as `abcdefghijklmnopqrstuvwx12`
+- Microsoft Teams: non-empty opaque Bot Connector `conversation.id` values such
+  as `a:opaque-conversation-id` or `19:conversation@thread.v2`
+- Zalo users, OAs, and chats: non-whitespace provider IDs such as `user-1` or
+  `group-1`
 
 ## Webhooks
 
@@ -403,6 +515,8 @@ Nested message payloads are also accepted:
 ```
 
 Malformed webhooks return `400`, and non-JSON requests return `415`.
+Configured webhook paths must be canonical URL pathnames without normalization,
+query, or fragment ambiguity.
 
 ## Evidence Flow
 

package/dist/src/bin/crabline.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 import { runCli } from "../cli/program.js";
-const exitCode = await runCli(process.argv);
+const exitCode = await runCli(process.argv, {
+    forceExit: (code) => process.exit(code),
+});
 if (exitCode !== 0) {
     process.exitCode = exitCode;
 }

package/dist/src/bin/crabline.js.map

@@ -1 +1 @@
-{"version":3,"file":"crabline.js","sourceRoot":"","sources":["../../../src/bin/crabline.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAE3C,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;AAC5C,IAAI,QAAQ,KAAK,CAAC,EAAE,CAAC;IACnB,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC;AAC9B,CAAC","sourcesContent":["#!/usr/bin/env node\n\nimport { runCli } from \"../cli/program.js\";\n\nconst exitCode = await runCli(process.argv);\nif (exitCode !== 0) {\n  process.exitCode = exitCode;\n}\n"]}
+{"version":3,"file":"crabline.js","sourceRoot":"","sources":["../../../src/bin/crabline.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAE3C,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE;IAC1C,SAAS,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;CACxC,CAAC,CAAC;AACH,IAAI,QAAQ,KAAK,CAAC,EAAE,CAAC;IACnB,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC;AAC9B,CAAC","sourcesContent":["#!/usr/bin/env node\n\nimport { runCli } from \"../cli/program.js\";\n\nconst exitCode = await runCli(process.argv, {\n  forceExit: (code) => process.exit(code),\n});\nif (exitCode !== 0) {\n  process.exitCode = exitCode;\n}\n"]}

package/dist/src/cli/program.d.ts

@@ -16,6 +16,10 @@ type ProgramDependencies = {
     removeReadyFile?: (filePath: string, expectedContents: string, expectedIdentity: ReadyFileIdentity) => Promise<void>;
     startServer?: (params: StartCrablineServerParams) => Promise<StartedCrablineServer>;
 };
+type RunCliOptions = {
+    dependencies?: ProgramDependencies;
+    forceExit?: (code: number) => never;
+};
 export declare function createProgram(setExitCode?: SetExitCode, dependencies?: ProgramDependencies): Command;
 type ShutdownSignal = "SIGINT" | "SIGTERM";
 type SignalTarget = {
@@ -25,5 +29,5 @@ type SignalTarget = {
 export declare function publishReadyFile(filePath: string, contents: string): Promise<ReadyFileIdentity>;
 export declare function removeReadyFile(filePath: string, expectedContents: string, expectedIdentity: ReadyFileIdentity): Promise<void>;
 export declare function waitForShutdown(close: () => Promise<void>, signalTarget?: SignalTarget): Promise<void>;
-export declare function runCli(argv: string[]): Promise<number>;
+export declare function runCli(argv: string[], options?: RunCliOptions): Promise<number>;
 export {};