@soyeht/soyeht 0.2.8 → 0.2.10

package/README.md

@@ -2,16 +2,24 @@
 
 Channel plugin for connecting the Soyeht Flutter mobile app to an OpenClaw gateway.
 
-## Install in OpenClaw
+## V1 Architecture
 
-After this package is published to npm, install it on the OpenClaw host with:
+The app and the OpenClaw instance communicate over **HTTP + SSE** on a shared network (typically Tailscale).
+
+- **Inbound** (app → plugin): `POST {gatewayUrl}/soyeht/messages/inbound`
+- **Outbound** (plugin → app): `GET {gatewayUrl}/soyeht/events/{accountId}?token=...` (SSE)
+- **Pairing**: QR code scanned by the app, then HTTP handshake
+
+No WebRTC. No public domain required. Tailscale resolves connectivity.
+
+## Install
 
 ```bash
-openclaw plugins install @soyeht/soyeht@0.1.2 --pin
+openclaw plugins install @soyeht/soyeht --pin
 openclaw plugins enable soyeht
 ```
 
-Then verify:
+Verify:
 
 ```bash
 openclaw plugins list
@@ -19,9 +27,42 @@ openclaw plugins info soyeht
 openclaw plugins doctor
 ```
 
-## Minimal configuration
+## Configuration
+
+Set `gatewayUrl` to the URL accessible from the app. With Tailscale, this is your instance's Tailscale IP or MagicDNS hostname:
+
+```bash
+# Using Tailscale IP
+openclaw config set channels.soyeht.gatewayUrl "http://100.x.y.z:18789"
+
+# Or using MagicDNS
+openclaw config set channels.soyeht.gatewayUrl "http://my-machine.tailnet.ts.net:18789"
+
+openclaw config set channels.soyeht.enabled true
+openclaw gateway restart
+```
+
+The plugin will auto-generate a pairing QR on startup if no peers are paired.
+
+### Manual pairing
+
+```bash
+openclaw gateway call soyeht.security.pairing.start '{"accountId": "default", "allowOverwrite": true}'
+```
+
+### Full config reference
 
-Add a Soyeht account under `channels.soyeht.accounts.default`:
+```yaml
+channels:
+  soyeht:
+    enabled: true
+    gatewayUrl: "http://100.x.y.z:18789"  # required — your Tailscale/LAN URL
+    # Optional (only for legacy backend mode, not needed in V1):
+    # backendBaseUrl: "https://your-backend.example"
+    # pluginAuthToken: "your-token"
+```
+
+Or with named accounts:
 
 ```yaml
 channels:
@@ -29,45 +70,47 @@ channels:
     accounts:
       default:
         enabled: true
-        backendBaseUrl: https://your-backend.example
-        pluginAuthToken: your-plugin-auth-token
-        security:
-          enabled: true
+        gatewayUrl: "http://100.x.y.z:18789"
 ```
 
-## Local validation
+## App endpoints
 
-```bash
-npm ci
-npm run validate
-```
+All called by the Flutter app against `{gatewayUrl}`:
 
-## Publish to npm
+| Method | Path | Purpose |
+|--------|------|---------|
+| `GET` | `/soyeht/pairing/info?t={token}` | Fetch plugin keys for pairing |
+| `POST` | `/soyeht/pairing/pair` | Register peer + start handshake |
+| `POST` | `/soyeht/pairing/finish` | Complete handshake, get streamToken |
+| `POST` | `/soyeht/messages/inbound` | Send encrypted message to agent |
+| `GET` | `/soyeht/events/{accountId}?token={streamToken}` | SSE stream for agent replies |
+| `GET` | `/soyeht/health` | Health check (503 if not ready) |
 
-1. Make sure the package name and scope are available on npm.
-2. Log in:
+## QR format
+
+The compact QR URL emitted by the plugin:
 
-```bash
-npm login
 ```
+soyeht://pair?g={gatewayUrl}&t={pairingToken}&fp={fingerprint}
+```
+
+The app parses the URL, then calls the HTTP pairing endpoints above.
 
-3. Bump the version:
+## Local development
 
 ```bash
-npm version patch
+npm ci
+npm run validate    # typecheck + tests
+npm run test:watch  # vitest in watch mode
 ```
 
-This also syncs `openclaw.plugin.json`.
-
-4. Publish publicly:
+## Publish
 
 ```bash
+npm version patch   # bumps package.json + openclaw.plugin.json
 npm publish
 ```
 
-The package is configured with `publishConfig.access=public`, so the first publish of the scoped package does not need an extra `--access public`.
-
 ## Protocol docs
 
-- [Protocol](docs/PROTOCOL.md)
-- [Flutter agent prompt](docs/FLUTTER_AGENT_PROMPT.md)
+- [Security Protocol](docs/PROTOCOL.md)

package/docs/PROTOCOL.md

@@ -67,13 +67,14 @@ Request params:
 }
 ```
 
-Success payload:
+Success payload (QR V2 — when `gatewayUrl` is configured):
 
 ```json
 {
   "qrPayload": {
-    "version": 1,
+    "version": 2,
     "type": "soyeht_pairing_qr",
+    "gatewayUrl": "http://100.x.y.z:18789",
     "accountId": "default",
     "pairingToken": "<base64url-32-bytes>",
     "expiresAt": 1730000000000,
@@ -88,7 +89,13 @@ Success payload:
 }
 ```
 
-QR signature transcript:
+QR V2 signature transcript:
+
+```text
+pairing_qr_v2|{gatewayUrl}|{accountId}|{pairingToken}|{expiresAt}|{allowOverwrite?1:0}|{pluginIdentityKey}|{pluginDhKey}|{fingerprint}
+```
+
+QR V1 signature transcript (fallback — no `gatewayUrl`):
 
 ```text
 pairing_qr_v1|{accountId}|{pairingToken}|{expiresAt}|{allowOverwrite?1:0}|{pluginIdentityKey}|{pluginDhKey}|{fingerprint}
@@ -96,6 +103,20 @@ pairing_qr_v1|{accountId}|{pairingToken}|{expiresAt}|{allowOverwrite?1:0}|{plugi
 
 The signature is Ed25519 with the plugin identity private key.
 
+### Compact QR URL
+
+On service startup (auto-pairing) and via `pairing.start`, the plugin also emits a compact URL suitable for QR rendering:
+
+```
+soyeht://pair?g={gatewayUrl}&t={pairingToken}&fp={fingerprint}
+```
+
+The app parses this URL, then calls the HTTP pairing endpoints to fetch full key material and complete pairing:
+
+1. `GET {gatewayUrl}/soyeht/pairing/info?t={pairingToken}` — get plugin keys
+2. `POST {gatewayUrl}/soyeht/pairing/pair` — register peer + start handshake
+3. `POST {gatewayUrl}/soyeht/pairing/finish` — complete handshake, get streamToken
+
 ### `soyeht.security.pair`
 
 Purpose:
@@ -373,16 +394,59 @@ Webhook/envelope:
 - `direction_mismatch`
 - `version_mismatch`
 
-## Recommended Client Flow
-
-1. Plugin/host calls `soyeht.security.pairing.start`
-2. Plugin/host renders `qrText` as QR
-3. App scans QR and verifies it
-4. App generates long-term keys if needed
-5. App calls `soyeht.security.pair`
-6. App generates a fresh ephemeral X25519 key + nonce
-7. App calls `soyeht.security.handshake.init`
-8. App verifies `pluginSignature`
-9. App signs the same transcript and calls `soyeht.security.handshake.finish`
-10. App derives the same X3DH session locally and starts Envelope V2 messaging
+## V1 Transport: HTTP + SSE over Tailscale
+
+In V1, the app and plugin communicate over a shared network (Tailscale). All endpoints use the `gatewayUrl` from config (e.g., `http://100.x.y.z:18789`).
+
+### Inbound (app → plugin → agent)
+
+```
+POST {gatewayUrl}/soyeht/messages/inbound
+Content-Type: application/json
+
+{EnvelopeV2 JSON}
+```
+
+The plugin decrypts, responds `200`, then dispatches to the OpenClaw agent pipeline. The agent's reply is encrypted and pushed to the outbound SSE stream.
+
+### Outbound (plugin → app via SSE)
+
+```
+GET {gatewayUrl}/soyeht/events/{accountId}?token={streamToken}
+```
+
+Or with header:
+
+```
+GET {gatewayUrl}/soyeht/events/{accountId}
+Authorization: Bearer {streamToken}
+```
+
+The `streamToken` is returned by `POST /soyeht/pairing/finish` on successful handshake.
+
+SSE events are encrypted EnvelopeV2 payloads. The app decrypts using its ratchet session state.
+
+### Health check
+
+```
+GET {gatewayUrl}/soyeht/health
+```
+
+Returns `200` with state info when ready, `503` when not.
+
+## Recommended Client Flow (V1 — HTTP Pairing)
+
+1. Plugin auto-generates QR on startup (or via `soyeht.security.pairing.start`)
+2. App scans QR: `soyeht://pair?g={gatewayUrl}&t={pairingToken}&fp={fingerprint}`
+3. App calls `GET {gatewayUrl}/soyeht/pairing/info?t={pairingToken}`
+4. App verifies plugin keys and fingerprint
+5. App generates long-term keys if needed
+6. App calls `POST {gatewayUrl}/soyeht/pairing/pair` (registers peer + starts handshake)
+7. App verifies `pluginSignature` from response
+8. App signs the handshake transcript
+9. App calls `POST {gatewayUrl}/soyeht/pairing/finish`
+10. App receives `streamToken` and `sessionExpiresAt`
+11. App derives X3DH session and connects to SSE: `GET {gatewayUrl}/soyeht/events/{accountId}?token={streamToken}`
+12. App sends messages via `POST {gatewayUrl}/soyeht/messages/inbound`
+13. App receives agent replies via SSE stream
 

package/openclaw.plugin.json

@@ -5,7 +5,7 @@
   ],
   "name": "Soyeht",
   "description": "Channel plugin for the Soyeht Flutter mobile app",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soyeht/soyeht",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "description": "OpenClaw channel plugin for the Soyeht Flutter mobile app",
   "type": "module",
   "main": "src/index.ts",

package/src/config.ts

@@ -71,14 +71,32 @@ function readAccountsSection(
   return section?.["accounts"] as Record<string, unknown> | undefined;
 }
 
+/**
+ * Read flat config from `channels.soyeht.*` (all keys except "accounts").
+ * Used as defaults when no explicit account entry exists.
+ */
+function readFlatConfig(cfg: OpenClawConfig): Record<string, unknown> {
+  const section = readConfigSection(cfg);
+  if (!section) return {};
+  const flat: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(section)) {
+    if (key !== "accounts") {
+      flat[key] = value;
+    }
+  }
+  return flat;
+}
+
 function readAccountConfig(
   cfg: OpenClawConfig,
   accountId: string,
 ): Record<string, unknown> {
+  const flat = readFlatConfig(cfg);
   const accounts = readAccountsSection(cfg);
-  if (!accounts) return {};
-  const entry = accounts[accountId];
-  return entry && typeof entry === "object" ? (entry as Record<string, unknown>) : {};
+  const entry = accounts?.[accountId];
+  const accountRaw = entry && typeof entry === "object" ? (entry as Record<string, unknown>) : {};
+  // Merge: flat config as defaults, account-specific overrides
+  return { ...flat, ...accountRaw };
 }
 
 // ---------------------------------------------------------------------------
@@ -199,8 +217,16 @@ export function resolveSoyehtAccount(
 
 export function listSoyehtAccountIds(cfg: OpenClawConfig): string[] {
   const accounts = readAccountsSection(cfg);
-  return listConfiguredAccountIds({
+  const ids = listConfiguredAccountIds({
     accounts: accounts as Record<string, unknown> | undefined,
     normalizeAccountId,
   });
+  // If no explicit accounts but flat config exists, treat as "default" account
+  if (ids.length === 0) {
+    const flat = readFlatConfig(cfg);
+    if (Object.keys(flat).length > 0) {
+      return [DEFAULT_ACCOUNT_ID];
+    }
+  }
+  return ids;
 }

package/src/http.ts

@@ -126,9 +126,23 @@ export function processInboundEnvelope(
 // GET /soyeht/health
 // ---------------------------------------------------------------------------
 
-export function healthHandler(_api: OpenClawPluginApi) {
+export function healthHandler(_api: OpenClawPluginApi, v2deps?: SecurityV2Deps) {
   return async (_req: IncomingMessage, res: ServerResponse) => {
-    sendJson(res, 200, { ok: true, plugin: "soyeht", version: PLUGIN_VERSION });
+    const ready = v2deps?.ready ?? false;
+    const identityLoaded = Boolean(v2deps?.identity);
+    const activeSessions = v2deps?.sessions.size ?? 0;
+    const pairedPeers = v2deps?.peers.size ?? 0;
+    const queueStats = v2deps?.outboundQueue.stats() ?? { accounts: 0, totalMessages: 0 };
+
+    sendJson(res, ready ? 200 : 503, {
+      ok: ready,
+      plugin: "soyeht",
+      version: PLUGIN_VERSION,
+      identity: identityLoaded,
+      peers: pairedPeers,
+      sessions: activeSessions,
+      queue: queueStats,
+    });
   };
 }
 

package/src/index.ts

@@ -104,7 +104,7 @@ const soyehtPlugin: OpenClawPluginDefinition = {
     api.registerHttpRoute({
       path: "/soyeht/health",
       auth: "plugin",
-      handler: healthHandler(api),
+      handler: healthHandler(api, v2deps),
     });
     api.registerHttpRoute({
       path: "/soyeht/webhook/deliver",

package/src/outbound-queue.ts

@@ -41,6 +41,8 @@ export type OutboundQueue = {
   prune(): number;
   clear(): void;
 
+  stats(): { accounts: number; totalMessages: number };
+
   // Stream token management (for SSE auth)
   createStreamToken(accountId: string, expiresAt: number): string;
   validateStreamToken(token: string): StreamTokenInfo | null;
@@ -93,6 +95,19 @@ export function createOutboundQueue(opts: OutboundQueueOptions = {}): OutboundQu
     let waiting: ((value: IteratorResult<QueueEntry>) => void) | null = null;
     let closed = false;
 
+    // Drain backlog: snapshot current queue entries still within TTL.
+    // Done synchronously before registering live subscriber — no race in
+    // single-threaded Node.js, so no duplicates and no missed messages.
+    const now = Date.now();
+    const backlog = queues.get(accountId);
+    if (backlog) {
+      for (const entry of backlog) {
+        if (now - entry.enqueuedAt < ttlMs) {
+          pending.push(entry);
+        }
+      }
+    }
+
     const sub: Subscriber = {
       accountId,
       push(entry: QueueEntry) {
@@ -217,12 +232,21 @@ export function createOutboundQueue(opts: OutboundQueueOptions = {}): OutboundQu
     }
   }
 
+  function stats(): { accounts: number; totalMessages: number } {
+    let totalMessages = 0;
+    for (const q of queues.values()) {
+      totalMessages += q.length;
+    }
+    return { accounts: queues.size, totalMessages };
+  }
+
   return {
     enqueue,
     subscribe,
     hasSubscribers,
     prune,
     clear,
+    stats,
     createStreamToken,
     validateStreamToken,
     revokeStreamTokensForAccount,

package/src/types.ts

@@ -31,54 +31,57 @@ export type SoyehtAccountConfig = {
   };
 };
 
-export const SoyehtAccountConfigSchema: JsonSchema = {
-  type: "object",
-  additionalProperties: false,
-  properties: {
-    enabled: { type: "boolean" },
-    backendBaseUrl: { type: "string" },
-    pluginAuthToken: { type: "string" },
-    gatewayUrl: { type: "string" },
-    allowProactive: { type: "boolean" },
-    audio: {
-      type: "object",
-      additionalProperties: false,
-      properties: {
-        transcribeInbound: { type: "boolean" },
-        ttsOutbound: { type: "boolean" },
-      },
+// Shared properties object — reused at account level and channel top level
+const accountConfigProperties: Record<string, unknown> = {
+  enabled: { type: "boolean" },
+  backendBaseUrl: { type: "string" },
+  pluginAuthToken: { type: "string" },
+  gatewayUrl: { type: "string" },
+  allowProactive: { type: "boolean" },
+  audio: {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      transcribeInbound: { type: "boolean" },
+      ttsOutbound: { type: "boolean" },
     },
-    files: {
-      type: "object",
-      additionalProperties: false,
-      properties: {
-        acceptInbound: { type: "boolean" },
-        maxBytes: { type: "number" },
-      },
+  },
+  files: {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      acceptInbound: { type: "boolean" },
+      maxBytes: { type: "number" },
     },
-    security: {
-      type: "object",
-      additionalProperties: false,
-      properties: {
-        enabled: { type: "boolean" },
-        timestampToleranceMs: { type: "number" },
-        dhRatchetIntervalMessages: { type: "number" },
-        dhRatchetIntervalMs: { type: "number" },
-        sessionMaxAgeMs: { type: "number" },
-        rateLimit: {
-          type: "object",
-          additionalProperties: false,
-          properties: {
-            maxRequests: { type: "number" },
-            windowMs: { type: "number" },
-          },
+  },
+  security: {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      enabled: { type: "boolean" },
+      timestampToleranceMs: { type: "number" },
+      dhRatchetIntervalMessages: { type: "number" },
+      dhRatchetIntervalMs: { type: "number" },
+      sessionMaxAgeMs: { type: "number" },
+      rateLimit: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          maxRequests: { type: "number" },
+          windowMs: { type: "number" },
         },
       },
     },
   },
 };
 
-export type SoyehtChannelConfig = {
+export const SoyehtAccountConfigSchema: JsonSchema = {
+  type: "object",
+  additionalProperties: false,
+  properties: accountConfigProperties,
+};
+
+export type SoyehtChannelConfig = SoyehtAccountConfig & {
   accounts?: Record<string, SoyehtAccountConfig>;
 };
 
@@ -86,6 +89,9 @@ export const SoyehtChannelConfigSchema: JsonSchema = {
   type: "object",
   additionalProperties: false,
   properties: {
+    // Top-level account fields (flat config shorthand for single-account setups)
+    ...accountConfigProperties,
+    // Named accounts (multi-account support)
     accounts: {
       type: "object",
       additionalProperties: SoyehtAccountConfigSchema,

package/src/version.ts

@@ -1 +1 @@
-export const PLUGIN_VERSION = "0.2.8";
+export const PLUGIN_VERSION = "0.2.10";