@soyeht/soyeht 0.1.2 → 0.2.0

package/openclaw.plugin.json

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

package/package.json

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

package/src/channel.ts

@@ -10,8 +10,38 @@ import {
   buildOutboundEnvelope,
   postToBackend,
 } from "./outbound.js";
+import { encryptEnvelopeV2 } from "./envelope-v2.js";
 import type { SecurityV2Deps } from "./service.js";
 
+// ---------------------------------------------------------------------------
+// Transport mode detection
+// ---------------------------------------------------------------------------
+
+type TransportMode = "direct" | "backend";
+
+function resolveTransportMode(
+  account: ResolvedSoyehtAccount,
+  v2deps?: SecurityV2Deps,
+): TransportMode {
+  const hasSession = v2deps?.sessions.has(account.accountId) ?? false;
+  const hasBackend = Boolean(account.backendBaseUrl && account.pluginAuthToken);
+  const hasSseSubscribers = v2deps?.outboundQueue.hasSubscribers(account.accountId) ?? false;
+
+  // Direct mode: active session + SSE client connected (or queue available)
+  if (hasSession && (hasSseSubscribers || !hasBackend)) {
+    return "direct";
+  }
+  // Backend mode: backend configured
+  if (hasBackend) {
+    return "backend";
+  }
+  // Default: direct (even without SSE subscriber — messages queue for later pickup)
+  if (hasSession) {
+    return "direct";
+  }
+  return "backend";
+}
+
 export function createSoyehtChannel(v2deps?: SecurityV2Deps): ChannelPlugin<ResolvedSoyehtAccount> {
   return {
     id: "soyeht",
@@ -44,15 +74,26 @@ export function createSoyehtChannel(v2deps?: SecurityV2Deps): ChannelPlugin<Reso
       resolveAccount: (cfg, accountId) => resolveSoyehtAccount(cfg, accountId),
       defaultAccountId: () => "default",
       isEnabled: (account) => account.enabled,
-      isConfigured: (account) => Boolean(account.backendBaseUrl && account.pluginAuthToken),
-      describeAccount: (account) => ({
-        accountId: account.accountId,
-        enabled: account.enabled,
-        configured: Boolean(account.backendBaseUrl && account.pluginAuthToken),
-        backendConfigured: Boolean(account.backendBaseUrl),
-        securityEnabled: account.security.enabled,
-        allowProactive: account.allowProactive,
-      }),
+      isConfigured: (account) => {
+        // Direct mode: active V2 session is sufficient
+        const hasSession = v2deps?.sessions.has(account.accountId) ?? false;
+        if (hasSession) return true;
+        // Backend mode: backendBaseUrl + pluginAuthToken
+        return Boolean(account.backendBaseUrl && account.pluginAuthToken);
+      },
+      describeAccount: (account) => {
+        const mode = resolveTransportMode(account, v2deps);
+        return {
+          accountId: account.accountId,
+          enabled: account.enabled,
+          configured: Boolean(account.backendBaseUrl && account.pluginAuthToken) ||
+            (v2deps?.sessions.has(account.accountId) ?? false),
+          backendConfigured: Boolean(account.backendBaseUrl),
+          securityEnabled: account.security.enabled,
+          allowProactive: account.allowProactive,
+          transportMode: mode,
+        };
+      },
     },
 
     outbound: {
@@ -60,14 +101,6 @@ export function createSoyehtChannel(v2deps?: SecurityV2Deps): ChannelPlugin<Reso
 
       async sendText(ctx) {
         const account = resolveSoyehtAccount(ctx.cfg, ctx.accountId);
-        if (!account.backendBaseUrl) {
-          return {
-            channel: "soyeht",
-            messageId: randomUUID(),
-            meta: { error: true, reason: "no_backend_url" },
-          };
-        }
-
         const ratchetSession = v2deps?.sessions.get(account.accountId);
 
         if (account.security.enabled && !ratchetSession) {
@@ -86,11 +119,25 @@ export function createSoyehtChannel(v2deps?: SecurityV2Deps): ChannelPlugin<Reso
           };
         }
 
+        const mode = resolveTransportMode(account, v2deps);
         const envelope = buildOutboundEnvelope(account.accountId, ctx.to, {
           contentType: "text",
           text: ctx.text,
         });
 
+        if (mode === "direct" && ratchetSession && v2deps) {
+          return enqueueOutbound(account, envelope, ratchetSession, v2deps);
+        }
+
+        // Backend mode (or no session for direct)
+        if (!account.backendBaseUrl) {
+          return {
+            channel: "soyeht",
+            messageId: randomUUID(),
+            meta: { error: true, reason: "no_backend_url" },
+          };
+        }
+
         return postToBackend(account.backendBaseUrl, account.pluginAuthToken, envelope, {
           ratchetSession,
           dhRatchetCfg: {
@@ -106,11 +153,11 @@ export function createSoyehtChannel(v2deps?: SecurityV2Deps): ChannelPlugin<Reso
 
       async sendMedia(ctx) {
         const account = resolveSoyehtAccount(ctx.cfg, ctx.accountId);
-        if (!account.backendBaseUrl || !ctx.mediaUrl) {
+        if (!ctx.mediaUrl) {
           return {
             channel: "soyeht",
             messageId: randomUUID(),
-            meta: { error: true, reason: !ctx.mediaUrl ? "no_media_url" : "no_backend_url" },
+            meta: { error: true, reason: "no_media_url" },
           };
         }
 
@@ -132,6 +179,7 @@ export function createSoyehtChannel(v2deps?: SecurityV2Deps): ChannelPlugin<Reso
           };
         }
 
+        const mode = resolveTransportMode(account, v2deps);
         const envelope = buildOutboundEnvelope(account.accountId, ctx.to, {
           contentType: "audio",
           renderStyle: "voice_note",
@@ -140,6 +188,19 @@ export function createSoyehtChannel(v2deps?: SecurityV2Deps): ChannelPlugin<Reso
           url: ctx.mediaUrl,
         });
 
+        if (mode === "direct" && ratchetSession && v2deps) {
+          return enqueueOutbound(account, envelope, ratchetSession, v2deps);
+        }
+
+        // Backend mode
+        if (!account.backendBaseUrl) {
+          return {
+            channel: "soyeht",
+            messageId: randomUUID(),
+            meta: { error: true, reason: "no_backend_url" },
+          };
+        }
+
         return postToBackend(account.backendBaseUrl, account.pluginAuthToken, envelope, {
           ratchetSession,
           dhRatchetCfg: {
@@ -155,3 +216,44 @@ export function createSoyehtChannel(v2deps?: SecurityV2Deps): ChannelPlugin<Reso
     },
   };
 }
+
+// ---------------------------------------------------------------------------
+// Encrypt + enqueue for direct mode (outbound via SSE)
+// ---------------------------------------------------------------------------
+
+import type { OutboundEnvelope } from "./types.js";
+import type { RatchetState } from "./ratchet.js";
+
+function enqueueOutbound(
+  account: ResolvedSoyehtAccount,
+  envelope: OutboundEnvelope,
+  ratchetSession: RatchetState,
+  v2deps: SecurityV2Deps,
+): { channel: string; messageId: string; meta?: Record<string, unknown> } {
+  if (ratchetSession.expiresAt < Date.now()) {
+    return {
+      channel: "soyeht",
+      messageId: envelope.deliveryId,
+      meta: { error: true, reason: "session_expired" },
+    };
+  }
+
+  const { envelope: v2env, updatedSession } = encryptEnvelopeV2({
+    session: ratchetSession,
+    accountId: envelope.accountId,
+    plaintext: JSON.stringify(envelope),
+    dhRatchetCfg: {
+      intervalMessages: account.security.dhRatchetIntervalMessages,
+      intervalMs: account.security.dhRatchetIntervalMs,
+    },
+  });
+  v2deps.sessions.set(account.accountId, updatedSession);
+
+  const entry = v2deps.outboundQueue.enqueue(account.accountId, v2env);
+
+  return {
+    channel: "soyeht",
+    messageId: envelope.deliveryId,
+    meta: { transportMode: "direct", queueEntryId: entry.id },
+  };
+}

package/src/config.ts

@@ -23,6 +23,7 @@ export type ResolvedSoyehtAccount = {
   enabled: boolean;
   backendBaseUrl: string;
   pluginAuthToken: string;
+  gatewayUrl: string;
   allowProactive: boolean;
   audio: {
     transcribeInbound: boolean;
@@ -133,6 +134,8 @@ export function resolveSoyehtAccount(
         : "",
     pluginAuthToken:
       typeof raw["pluginAuthToken"] === "string" ? raw["pluginAuthToken"] : "",
+    gatewayUrl:
+      typeof raw["gatewayUrl"] === "string" ? raw["gatewayUrl"] : "",
     allowProactive:
       typeof raw["allowProactive"] === "boolean" ? raw["allowProactive"] : false,
     audio: {

package/src/http.ts

@@ -43,6 +43,67 @@ async function readRawBodyBuffer(req: IncomingMessage): Promise<Buffer> {
 
 export { readRawBodyBuffer };
 
+// ---------------------------------------------------------------------------
+// Shared: process an inbound EnvelopeV2 (validate + decrypt + update session)
+// ---------------------------------------------------------------------------
+
+export type ProcessInboundResult =
+  | { ok: true; plaintext: string; accountId: string; envelope: EnvelopeV2 }
+  | { ok: false; status: number; error: string };
+
+export function processInboundEnvelope(
+  api: OpenClawPluginApi,
+  v2deps: SecurityV2Deps,
+  envelope: EnvelopeV2,
+  hintedAccountId?: string,
+): ProcessInboundResult {
+  const envelopeAccountId = normalizeAccountId(envelope.accountId);
+  if (hintedAccountId && hintedAccountId !== envelopeAccountId) {
+    return { ok: false, status: 401, error: "account_mismatch" };
+  }
+
+  const accountId = hintedAccountId ?? envelopeAccountId;
+  const session = v2deps.sessions.get(accountId);
+  if (!session) {
+    return { ok: false, status: 401, error: "session_required" };
+  }
+
+  if (session.expiresAt < Date.now()) {
+    return { ok: false, status: 401, error: "session_expired" };
+  }
+
+  if (session.accountId !== envelopeAccountId) {
+    return { ok: false, status: 401, error: "account_mismatch" };
+  }
+
+  const validation = validateEnvelopeV2(envelope, session);
+  if (!validation.valid) {
+    api.logger.warn("[soyeht] Envelope validation failed", { error: validation.error, accountId });
+    return { ok: false, status: 401, error: validation.error };
+  }
+
+  // Deep-clone session before decryption so in-place Buffer mutations
+  // cannot corrupt the stored session on failure.
+  const sessionClone = cloneRatchetSession(session);
+
+  let plaintext: string;
+  let updatedSession;
+  try {
+    const result = decryptEnvelopeV2({ session: sessionClone, envelope });
+    plaintext = result.plaintext;
+    updatedSession = result.updatedSession;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : "decryption_failed";
+    api.logger.warn("[soyeht] Envelope decryption failed", { error: msg, accountId });
+    return { ok: false, status: 401, error: msg };
+  }
+
+  // Update session
+  v2deps.sessions.set(accountId, updatedSession);
+
+  return { ok: true, plaintext, accountId, envelope };
+}
+
 // ---------------------------------------------------------------------------
 // GET /soyeht/health
 // ---------------------------------------------------------------------------
@@ -54,7 +115,7 @@ export function healthHandler(_api: OpenClawPluginApi) {
 }
 
 // ---------------------------------------------------------------------------
-// POST /soyeht/webhook/deliver
+// POST /soyeht/webhook/deliver (legacy backend mode)
 // ---------------------------------------------------------------------------
 
 export function webhookHandler(
@@ -89,7 +150,6 @@ export function webhookHandler(
     try {
       const rawBody = await readRawBodyBuffer(req);
 
-      // Parse the envelope
       let envelope: EnvelopeV2;
       try {
         envelope = JSON.parse(rawBody.toString("utf8")) as EnvelopeV2;
@@ -98,60 +158,76 @@ export function webhookHandler(
         return;
       }
 
-      const envelopeAccountId = normalizeAccountId(envelope.accountId);
-      if (hintedAccountId && hintedAccountId !== envelopeAccountId) {
-        sendJson(res, 401, { ok: false, error: "account_mismatch" });
+      const result = processInboundEnvelope(api, v2deps, envelope, hintedAccountId);
+      if (!result.ok) {
+        sendJson(res, result.status, { ok: false, error: result.error });
         return;
       }
 
-      const accountId = hintedAccountId ?? envelopeAccountId;
-      const session = v2deps.sessions.get(accountId);
-      if (!session) {
-        sendJson(res, 401, { ok: false, error: "session_required" });
-        return;
-      }
+      api.logger.info("[soyeht] Webhook delivery received", { accountId: result.accountId });
+      sendJson(res, 200, { ok: true, received: true });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "unknown_error";
+      sendJson(res, 400, { ok: false, error: message });
+    }
+  };
+}
 
-      if (session.expiresAt < Date.now()) {
-        sendJson(res, 401, { ok: false, error: "session_expired" });
-        return;
-      }
+// ---------------------------------------------------------------------------
+// POST /soyeht/messages/inbound (direct mode — app → plugin → agent)
+// ---------------------------------------------------------------------------
+
+export function inboundHandler(
+  api: OpenClawPluginApi,
+  v2deps: SecurityV2Deps,
+) {
+  return async (req: IncomingMessage, res: ServerResponse) => {
+    if (req.method !== "POST") {
+      sendJson(res, 405, { ok: false, error: "method_not_allowed" });
+      return;
+    }
+
+    if (!v2deps.ready) {
+      sendJson(res, 503, { ok: false, error: "service_unavailable" });
+      return;
+    }
 
-      if (session.accountId !== envelopeAccountId) {
-        sendJson(res, 401, { ok: false, error: "account_mismatch" });
+    try {
+      const rawBody = await readRawBodyBuffer(req);
+
+      let envelope: EnvelopeV2;
+      try {
+        envelope = JSON.parse(rawBody.toString("utf8")) as EnvelopeV2;
+      } catch {
+        sendJson(res, 400, { ok: false, error: "invalid_json" });
         return;
       }
 
-      // Validate envelope (trust only the parsed body — no header overrides)
-      const validation = validateEnvelopeV2(envelope, session);
-      if (!validation.valid) {
-        api.logger.warn("[soyeht] Webhook validation failed", { error: validation.error, accountId });
-        sendJson(res, 401, { ok: false, error: validation.error });
+      const envelopeAccountId = normalizeAccountId(envelope.accountId);
+
+      // Rate limit per-account
+      const { allowed, retryAfterMs } = v2deps.rateLimiter.check(`inbound:${envelopeAccountId}`);
+      if (!allowed) {
+        res.setHeader("Retry-After", String(Math.ceil((retryAfterMs ?? 60_000) / 1000)));
+        sendJson(res, 429, { ok: false, error: "rate_limited" });
         return;
       }
 
-      // Deep-clone session before decryption so in-place Buffer mutations
-      // (rootKey.fill(0), chainKey.fill(0)) cannot corrupt the stored session on failure.
-      const sessionClone = cloneRatchetSession(session);
-
-      // Decrypt
-      let plaintext: string;
-      let updatedSession;
-      try {
-        const result = decryptEnvelopeV2({ session: sessionClone, envelope });
-        plaintext = result.plaintext;
-        updatedSession = result.updatedSession;
-      } catch (err) {
-        const msg = err instanceof Error ? err.message : "decryption_failed";
-        api.logger.warn("[soyeht] Webhook decryption failed", { error: msg, accountId });
-        sendJson(res, 401, { ok: false, error: msg });
+      const result = processInboundEnvelope(api, v2deps, envelope);
+      if (!result.ok) {
+        sendJson(res, result.status, { ok: false, error: result.error });
         return;
       }
 
-      // Update session
-      v2deps.sessions.set(accountId, updatedSession);
+      // TODO: Push decrypted message to OpenClaw agent pipeline.
+      // The exact API depends on the OpenClaw runtime (e.g. api.channel.pushInbound()).
+      // For now the message is decrypted and the session is updated;
+      // wiring to the agent conversation will be done when the runtime API is known.
+      api.logger.info("[soyeht] Inbound message received (direct mode)", {
+        accountId: result.accountId,
+      });
 
-      api.logger.info("[soyeht] Webhook delivery received", { accountId });
-      sendJson(res, 200, { ok: true, received: true });
+      sendJson(res, 200, { ok: true, received: true, accountId: result.accountId });
     } catch (err) {
       const message = err instanceof Error ? err.message : "unknown_error";
       sendJson(res, 400, { ok: false, error: message });
@@ -159,6 +235,112 @@ export function webhookHandler(
   };
 }
 
+// ---------------------------------------------------------------------------
+// GET /soyeht/events/:accountId (SSE — plugin → app outbound stream)
+// ---------------------------------------------------------------------------
+
+const SSE_KEEPALIVE_MS = 30_000;
+
+export function sseHandler(
+  api: OpenClawPluginApi,
+  v2deps: SecurityV2Deps,
+) {
+  return async (req: IncomingMessage, res: ServerResponse) => {
+    if (req.method !== "GET") {
+      sendJson(res, 405, { ok: false, error: "method_not_allowed" });
+      return;
+    }
+
+    if (!v2deps.ready) {
+      sendJson(res, 503, { ok: false, error: "service_unavailable" });
+      return;
+    }
+
+    // Extract accountId from URL: /soyeht/events/<accountId>
+    const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+    const pathParts = url.pathname.split("/").filter(Boolean);
+    // Expected: ["soyeht", "events", "<accountId>"]
+    const accountId = pathParts.length >= 3 ? normalizeAccountId(pathParts[2]) : undefined;
+    if (!accountId) {
+      sendJson(res, 400, { ok: false, error: "missing_account_id" });
+      return;
+    }
+
+    // Auth: validate stream token from Authorization header or query param
+    const authHeader = req.headers.authorization ?? "";
+    const bearerMatch = authHeader.match(/^Bearer\s+(.+)$/i);
+    const token = bearerMatch?.[1] ?? url.searchParams.get("token") ?? "";
+
+    if (!token) {
+      sendJson(res, 401, { ok: false, error: "stream_token_required" });
+      return;
+    }
+
+    const tokenInfo = v2deps.outboundQueue.validateStreamToken(token);
+    if (!tokenInfo) {
+      sendJson(res, 401, { ok: false, error: "invalid_stream_token" });
+      return;
+    }
+
+    if (tokenInfo.accountId !== accountId) {
+      sendJson(res, 403, { ok: false, error: "token_account_mismatch" });
+      return;
+    }
+
+    // Verify active session exists
+    const session = v2deps.sessions.get(accountId);
+    if (!session || session.expiresAt < Date.now()) {
+      sendJson(res, 401, { ok: false, error: "session_required" });
+      return;
+    }
+
+    // SSE headers
+    res.writeHead(200, {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache",
+      Connection: "keep-alive",
+      "X-Accel-Buffering": "no",
+    });
+    res.write(`retry: 3000\n\n`);
+
+    api.logger.info("[soyeht] SSE client connected", { accountId });
+
+    // Subscribe to outbound queue
+    const subscription = v2deps.outboundQueue.subscribe(accountId);
+
+    // Keepalive ping
+    const keepalive = setInterval(() => {
+      if (!res.destroyed) {
+        res.write(`: ping\n\n`);
+      }
+    }, SSE_KEEPALIVE_MS);
+    if (typeof keepalive === "object" && "unref" in keepalive) {
+      keepalive.unref();
+    }
+
+    // Client disconnect
+    const onClose = () => {
+      clearInterval(keepalive);
+      subscription.unsubscribe();
+      api.logger.info("[soyeht] SSE client disconnected", { accountId });
+    };
+
+    req.on("close", onClose);
+    res.on("close", onClose);
+
+    // Stream messages
+    try {
+      for await (const entry of subscription) {
+        if (res.destroyed) break;
+        const data = JSON.stringify(entry.data);
+        res.write(`id: ${entry.id}\ndata: ${data}\n\n`);
+      }
+    } catch {
+      // subscription closed or error — clean up handled by onClose
+    }
+  };
+}
+
 // ---------------------------------------------------------------------------
 // POST /soyeht/livekit/token — stub
 // ---------------------------------------------------------------------------

package/src/index.ts

@@ -13,6 +13,8 @@ import {
   healthHandler,
   webhookHandler,
   livekitTokenHandler,
+  inboundHandler,
+  sseHandler,
 } from "./http.js";
 import {
   createSoyehtService,
@@ -71,7 +73,7 @@ const soyehtPlugin: OpenClawPluginDefinition = {
 
   configSchema: emptyPluginConfigSchema,
 
-  async register(api) {
+  register(api) {
     // V2 deps — identity/sessions loaded in service.start()
     const v2deps = createSecurityV2Deps();
 
@@ -110,6 +112,19 @@ const soyehtPlugin: OpenClawPluginDefinition = {
       handler: livekitTokenHandler(api),
     });
 
+    // Direct mode routes (app ↔ plugin)
+    api.registerHttpRoute({
+      path: "/soyeht/messages/inbound",
+      auth: "plugin",
+      handler: inboundHandler(api, v2deps),
+    });
+    api.registerHttpRoute({
+      path: "/soyeht/events",
+      auth: "plugin",
+      match: "prefix",
+      handler: sseHandler(api, v2deps),
+    });
+
     // Background service (manages state lifecycle)
     api.registerService(createSoyehtService(api, v2deps));
 

package/src/outbound-queue.ts

@@ -0,0 +1,230 @@
+import { randomBytes } from "node:crypto";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type QueueEntry = {
+  id: string;
+  accountId: string;
+  data: unknown; // EnvelopeV2 JSON
+  enqueuedAt: number;
+};
+
+type Subscriber = {
+  accountId: string;
+  push: (entry: QueueEntry) => void;
+  closed: boolean;
+};
+
+export type StreamTokenInfo = {
+  accountId: string;
+  expiresAt: number;
+};
+
+// ---------------------------------------------------------------------------
+// OutboundQueue — in-memory, bounded, per-accountId
+// ---------------------------------------------------------------------------
+
+const DEFAULT_MAX_PER_ACCOUNT = 1000;
+const DEFAULT_TTL_MS = 3_600_000; // 1 hour
+
+export type OutboundQueueOptions = {
+  maxPerAccount?: number;
+  ttlMs?: number;
+};
+
+export type OutboundQueue = {
+  enqueue(accountId: string, data: unknown): QueueEntry;
+  subscribe(accountId: string): AsyncIterable<QueueEntry> & { unsubscribe: () => void };
+  hasSubscribers(accountId: string): boolean;
+  prune(): number;
+  clear(): void;
+
+  // Stream token management (for SSE auth)
+  createStreamToken(accountId: string, expiresAt: number): string;
+  validateStreamToken(token: string): StreamTokenInfo | null;
+  revokeStreamTokensForAccount(accountId: string): void;
+};
+
+export function createOutboundQueue(opts: OutboundQueueOptions = {}): OutboundQueue {
+  const maxPerAccount = opts.maxPerAccount ?? DEFAULT_MAX_PER_ACCOUNT;
+  const ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+
+  const queues = new Map<string, QueueEntry[]>();
+  const subscribers = new Map<string, Set<Subscriber>>();
+  const streamTokens = new Map<string, StreamTokenInfo>();
+
+  function enqueue(accountId: string, data: unknown): QueueEntry {
+    const entry: QueueEntry = {
+      id: randomBytes(16).toString("hex"),
+      accountId,
+      data,
+      enqueuedAt: Date.now(),
+    };
+
+    let q = queues.get(accountId);
+    if (!q) {
+      q = [];
+      queues.set(accountId, q);
+    }
+    q.push(entry);
+
+    // FIFO overflow
+    while (q.length > maxPerAccount) {
+      q.shift();
+    }
+
+    // Push to live subscribers
+    const subs = subscribers.get(accountId);
+    if (subs) {
+      for (const sub of subs) {
+        if (!sub.closed) {
+          sub.push(entry);
+        }
+      }
+    }
+
+    return entry;
+  }
+
+  function subscribe(accountId: string): AsyncIterable<QueueEntry> & { unsubscribe: () => void } {
+    const pending: QueueEntry[] = [];
+    let waiting: ((value: IteratorResult<QueueEntry>) => void) | null = null;
+    let closed = false;
+
+    const sub: Subscriber = {
+      accountId,
+      push(entry: QueueEntry) {
+        if (closed) return;
+        if (waiting) {
+          const resolve = waiting;
+          waiting = null;
+          resolve({ value: entry, done: false });
+        } else {
+          pending.push(entry);
+        }
+      },
+      closed: false,
+    };
+
+    let subs = subscribers.get(accountId);
+    if (!subs) {
+      subs = new Set();
+      subscribers.set(accountId, subs);
+    }
+    subs.add(sub);
+
+    function unsubscribe() {
+      closed = true;
+      sub.closed = true;
+      const s = subscribers.get(accountId);
+      if (s) {
+        s.delete(sub);
+        if (s.size === 0) subscribers.delete(accountId);
+      }
+      if (waiting) {
+        waiting({ value: undefined as unknown as QueueEntry, done: true });
+        waiting = null;
+      }
+    }
+
+    return {
+      unsubscribe,
+      [Symbol.asyncIterator]() {
+        return {
+          next(): Promise<IteratorResult<QueueEntry>> {
+            if (closed) {
+              return Promise.resolve({ value: undefined as unknown as QueueEntry, done: true });
+            }
+            if (pending.length > 0) {
+              return Promise.resolve({ value: pending.shift()!, done: false });
+            }
+            return new Promise<IteratorResult<QueueEntry>>((resolve) => {
+              waiting = resolve;
+            });
+          },
+          return(): Promise<IteratorResult<QueueEntry>> {
+            unsubscribe();
+            return Promise.resolve({ value: undefined as unknown as QueueEntry, done: true });
+          },
+        };
+      },
+    };
+  }
+
+  function hasSubscribers(accountId: string): boolean {
+    const subs = subscribers.get(accountId);
+    return Boolean(subs && subs.size > 0);
+  }
+
+  function prune(): number {
+    const now = Date.now();
+    let pruned = 0;
+    for (const [accountId, q] of queues) {
+      const before = q.length;
+      const filtered = q.filter((e) => now - e.enqueuedAt < ttlMs);
+      pruned += before - filtered.length;
+      if (filtered.length === 0) {
+        queues.delete(accountId);
+      } else if (filtered.length !== before) {
+        queues.set(accountId, filtered);
+      }
+    }
+
+    // Prune expired stream tokens
+    for (const [token, info] of streamTokens) {
+      if (info.expiresAt < now) {
+        streamTokens.delete(token);
+      }
+    }
+
+    return pruned;
+  }
+
+  function clear(): void {
+    queues.clear();
+    for (const subs of subscribers.values()) {
+      for (const sub of subs) {
+        sub.closed = true;
+      }
+    }
+    subscribers.clear();
+    streamTokens.clear();
+  }
+
+  function createStreamToken(accountId: string, expiresAt: number): string {
+    const token = randomBytes(32).toString("hex");
+    streamTokens.set(token, { accountId, expiresAt });
+    return token;
+  }
+
+  function validateStreamToken(token: string): StreamTokenInfo | null {
+    const info = streamTokens.get(token);
+    if (!info) return null;
+    if (info.expiresAt < Date.now()) {
+      streamTokens.delete(token);
+      return null;
+    }
+    return info;
+  }
+
+  function revokeStreamTokensForAccount(accountId: string): void {
+    for (const [token, info] of streamTokens) {
+      if (info.accountId === accountId) {
+        streamTokens.delete(token);
+      }
+    }
+  }
+
+  return {
+    enqueue,
+    subscribe,
+    hasSubscribers,
+    prune,
+    clear,
+    createStreamToken,
+    validateStreamToken,
+    revokeStreamTokensForAccount,
+  };
+}

package/src/pairing.ts

@@ -10,7 +10,7 @@ import {
   importEd25519PublicKey,
   importX25519PublicKey,
 } from "./crypto.js";
-import { normalizeAccountId } from "./config.js";
+import { normalizeAccountId, resolveSoyehtAccount } from "./config.js";
 import { deleteSession, savePeer, type PeerIdentity } from "./identity.js";
 import { zeroBuffer } from "./ratchet.js";
 import type { SecurityV2Deps } from "./service.js";
@@ -26,6 +26,7 @@ function clampPairingTtlMs(value: unknown): number {
   return Math.min(Math.max(Math.trunc(value), MIN_PAIRING_TTL_MS), MAX_PAIRING_TTL_MS);
 }
 
+// V1 transcript (backward compat — no gatewayUrl)
 export function buildPairingQrTranscript(params: {
   accountId: string;
   pairingToken: string;
@@ -50,6 +51,33 @@ export function buildPairingQrTranscript(params: {
   );
 }
 
+// V2 transcript — includes gatewayUrl
+export function buildPairingQrTranscriptV2(params: {
+  gatewayUrl: string;
+  accountId: string;
+  pairingToken: string;
+  expiresAt: number;
+  allowOverwrite: boolean;
+  pluginIdentityKey: string;
+  pluginDhKey: string;
+  fingerprint: string;
+}): Buffer {
+  const {
+    gatewayUrl,
+    accountId,
+    pairingToken,
+    expiresAt,
+    allowOverwrite,
+    pluginIdentityKey,
+    pluginDhKey,
+    fingerprint,
+  } = params;
+  return Buffer.from(
+    `pairing_qr_v2|${gatewayUrl}|${accountId}|${pairingToken}|${expiresAt}|${allowOverwrite ? 1 : 0}|${pluginIdentityKey}|${pluginDhKey}|${fingerprint}`,
+    "utf8",
+  );
+}
+
 export function buildPairingProofTranscript(params: {
   accountId: string;
   pairingToken: string;
@@ -64,11 +92,11 @@ export function buildPairingProofTranscript(params: {
   );
 }
 
-function signPairingQrPayload(
+function signTranscript(
   privateKey: Parameters<typeof ed25519Sign>[0],
-  payload: Parameters<typeof buildPairingQrTranscript>[0],
+  transcript: Buffer,
 ): string {
-  return base64UrlEncode(ed25519Sign(privateKey, buildPairingQrTranscript(payload)));
+  return base64UrlEncode(ed25519Sign(privateKey, transcript));
 }
 
 function clearAccountSessionState(v2deps: SecurityV2Deps, accountId: string): void {
@@ -87,6 +115,27 @@ function clearAccountSessionState(v2deps: SecurityV2Deps, accountId: string): vo
   }
 }
 
+// ---------------------------------------------------------------------------
+// Resolve the gateway URL for QR V2
+// ---------------------------------------------------------------------------
+
+function resolveGatewayUrl(api: OpenClawPluginApi, configGatewayUrl: string): string {
+  // 1) Explicit config
+  if (configGatewayUrl) return configGatewayUrl;
+
+  // 2) Attempt auto-detection from runtime (if available)
+  const runtime = api.runtime as Record<string, unknown>;
+  if (typeof runtime["gatewayUrl"] === "string" && runtime["gatewayUrl"]) {
+    return runtime["gatewayUrl"];
+  }
+  if (typeof runtime["baseUrl"] === "string" && runtime["baseUrl"]) {
+    return runtime["baseUrl"];
+  }
+
+  // 3) Empty — the app will need to be configured manually
+  return "";
+}
+
 // ---------------------------------------------------------------------------
 // soyeht.security.identity — expose plugin public keys
 // ---------------------------------------------------------------------------
@@ -124,7 +173,7 @@ export function handleSecurityIdentity(
 // ---------------------------------------------------------------------------
 
 export function handleSecurityPairingStart(
-  _api: OpenClawPluginApi,
+  api: OpenClawPluginApi,
   v2deps: SecurityV2Deps,
 ): GatewayRequestHandler {
   return async ({ params, respond }) => {
@@ -163,9 +212,13 @@ export function handleSecurityPairingStart(
     const pairingToken = base64UrlEncode(randomBytes(32));
     const expiresAt = Date.now() + ttlMs;
     const fingerprint = computeFingerprint(v2deps.identity);
-    const payload = {
-      version: 1 as const,
-      type: "soyeht_pairing_qr" as const,
+
+    // Resolve gatewayUrl for QR V2
+    const cfg = await api.runtime.config.loadConfig();
+    const account = resolveSoyehtAccount(cfg, accountId);
+    const gatewayUrl = resolveGatewayUrl(api, account.gatewayUrl);
+
+    const basePayload = {
       accountId,
       pairingToken,
       expiresAt,
@@ -174,8 +227,31 @@ export function handleSecurityPairingStart(
       pluginDhKey: v2deps.identity.dhKey.publicKeyB64,
       fingerprint,
     };
-    const signature = signPairingQrPayload(v2deps.identity.signKey.privateKey, payload);
-    const qrPayload = { ...payload, signature };
+
+    let qrPayload: Record<string, unknown>;
+
+    if (gatewayUrl) {
+      // QR V2 — includes gatewayUrl
+      const transcript = buildPairingQrTranscriptV2({ gatewayUrl, ...basePayload });
+      const signature = signTranscript(v2deps.identity.signKey.privateKey, transcript);
+      qrPayload = {
+        version: 2,
+        type: "soyeht_pairing_qr",
+        gatewayUrl,
+        ...basePayload,
+        signature,
+      };
+    } else {
+      // QR V1 fallback — no gatewayUrl available
+      const transcript = buildPairingQrTranscript(basePayload);
+      const signature = signTranscript(v2deps.identity.signKey.privateKey, transcript);
+      qrPayload = {
+        version: 1,
+        type: "soyeht_pairing_qr",
+        ...basePayload,
+        signature,
+      };
+    }
 
     v2deps.pairingSessions.set(pairingToken, {
       token: pairingToken,

package/src/rpc.ts

@@ -9,11 +9,11 @@ import {
   normalizeAccountId,
 } from "./config.js";
 import {
-  deliverTextMessage,
   postToBackend,
   buildOutboundEnvelope,
   type PostToBackendOptions,
 } from "./outbound.js";
+import { encryptEnvelopeV2 } from "./envelope-v2.js";
 import type { TextMessagePayload } from "./types.js";
 import {
   base64UrlDecode,
@@ -115,14 +115,6 @@ export function handleNotify(
       return;
     }
 
-    if (!account.backendBaseUrl || !account.pluginAuthToken) {
-      respond(false, undefined, {
-        code: "NOT_CONFIGURED",
-        message: "Account is not fully configured",
-      });
-      return;
-    }
-
     const to = params["to"] as string;
     const text = params["text"] as string;
     if (!to || !text) {
@@ -133,54 +125,67 @@ export function handleNotify(
       return;
     }
 
-    if (account.security.enabled && v2deps) {
+    // Direct mode: encrypt and enqueue if V2 session exists
+    if (v2deps) {
       const ratchetSession = v2deps.sessions.get(account.accountId);
-      if (!ratchetSession) {
-        respond(false, undefined, {
-          code: "SESSION_REQUIRED",
-          message: "V2 session required for secure delivery",
+      if (ratchetSession) {
+        if (ratchetSession.expiresAt < Date.now()) {
+          respond(false, undefined, {
+            code: "SESSION_EXPIRED",
+            message: "V2 session has expired, re-handshake required",
+          });
+          return;
+        }
+
+        const message: TextMessagePayload = { contentType: "text", text };
+        const envelope = buildOutboundEnvelope(account.accountId, to, message);
+        const { envelope: v2env, updatedSession } = encryptEnvelopeV2({
+          session: ratchetSession,
+          accountId: account.accountId,
+          plaintext: JSON.stringify(envelope),
+          dhRatchetCfg: {
+            intervalMessages: account.security.dhRatchetIntervalMessages,
+            intervalMs: account.security.dhRatchetIntervalMs,
+          },
+        });
+        v2deps.sessions.set(account.accountId, updatedSession);
+        const entry = v2deps.outboundQueue.enqueue(account.accountId, v2env);
+        respond(true, {
+          deliveryId: envelope.deliveryId,
+          meta: { transportMode: "direct", queueEntryId: entry.id },
         });
         return;
       }
 
-      if (ratchetSession.expiresAt < Date.now()) {
+      if (account.security.enabled) {
         respond(false, undefined, {
-          code: "SESSION_EXPIRED",
-          message: "V2 session has expired, re-handshake required",
+          code: "SESSION_REQUIRED",
+          message: "V2 session required for secure delivery",
         });
         return;
       }
+    }
 
-      const message: TextMessagePayload = { contentType: "text", text };
-      const envelope = buildOutboundEnvelope(account.accountId, to, message);
-      const opts: PostToBackendOptions = {
-        ratchetSession,
-        dhRatchetCfg: {
-          intervalMessages: account.security.dhRatchetIntervalMessages,
-          intervalMs: account.security.dhRatchetIntervalMs,
-        },
-        onSessionUpdated: (updated) => v2deps.sessions.set(account.accountId, updated),
-        securityEnabled: true,
-      };
-      const result = await postToBackend(
-        account.backendBaseUrl,
-        account.pluginAuthToken,
-        envelope,
-        opts,
-      );
-      respond(true, { deliveryId: result.messageId, meta: result.meta });
+    // Backend mode fallback
+    if (!account.backendBaseUrl || !account.pluginAuthToken) {
+      respond(false, undefined, {
+        code: "NOT_CONFIGURED",
+        message: "Account is not fully configured (no session and no backend)",
+      });
       return;
     }
 
-    const result = await deliverTextMessage({
-      backendBaseUrl: account.backendBaseUrl,
-      pluginAuthToken: account.pluginAuthToken,
-      accountId: account.accountId,
-      sessionId: to,
-      to,
-      text,
-    });
-
+    const message: TextMessagePayload = { contentType: "text", text };
+    const envelope = buildOutboundEnvelope(account.accountId, to, message);
+    const opts: PostToBackendOptions = {
+      securityEnabled: false,
+    };
+    const result = await postToBackend(
+      account.backendBaseUrl,
+      account.pluginAuthToken,
+      envelope,
+      opts,
+    );
     respond(true, { deliveryId: result.messageId, meta: result.meta });
   };
 }
@@ -456,6 +461,10 @@ export function handleSecurityHandshakeFinish(
       });
     }
 
+    // Revoke old stream tokens and issue a fresh one for SSE auth
+    v2deps.outboundQueue.revokeStreamTokensForAccount(accountId);
+    const streamToken = v2deps.outboundQueue.createStreamToken(accountId, pending.sessionExpiresAt);
+
     api.logger.info("[soyeht] V2 handshake completed", { accountId });
 
     respond(true, {
@@ -463,6 +472,7 @@ export function handleSecurityHandshakeFinish(
       phase: "finish",
       complete: true,
       expiresAt: pending.sessionExpiresAt,
+      streamToken,
     });
   };
 }

package/src/service.ts

@@ -12,6 +12,7 @@ import { zeroBuffer } from "./ratchet.js";
 import { computeFingerprint, type X25519KeyPair } from "./crypto.js";
 import type { IdentityBundle, PeerIdentity } from "./identity.js";
 import type { RatchetState } from "./ratchet.js";
+import { createOutboundQueue, type OutboundQueue } from "./outbound-queue.js";
 
 const HEARTBEAT_INTERVAL_MS = 60_000; // 60s
 
@@ -27,6 +28,7 @@ export type SecurityV2Deps = {
   pendingHandshakes: Map<string, PendingHandshake>;
   nonceCache: NonceCache;
   rateLimiter: RateLimiter;
+  outboundQueue: OutboundQueue;
   ready: boolean;
   stateDir?: string;
 };
@@ -58,6 +60,7 @@ export function createSecurityV2Deps(): SecurityV2Deps {
     pendingHandshakes: new Map(),
     nonceCache: createNonceCache(),
     rateLimiter: createRateLimiter(),
+    outboundQueue: createOutboundQueue(),
     ready: false,
   };
 }
@@ -115,6 +118,7 @@ export function createSoyehtService(
           const now = Date.now();
           v2deps.nonceCache.prune();
           v2deps.rateLimiter.prune();
+          v2deps.outboundQueue.prune();
           for (const [token, session] of v2deps.pairingSessions) {
             if (session.expiresAt <= now) {
               v2deps.pairingSessions.delete(token);
@@ -168,6 +172,7 @@ export function createSoyehtService(
         v2deps.peers.clear();
         v2deps.pairingSessions.clear();
         v2deps.pendingHandshakes.clear();
+        v2deps.outboundQueue.clear();
         v2deps.ready = false;
       }
 

package/src/types.ts

@@ -8,6 +8,7 @@ export type SoyehtAccountConfig = {
   enabled?: boolean;
   backendBaseUrl?: string;
   pluginAuthToken?: string;
+  gatewayUrl?: string;
   allowProactive?: boolean;
   audio?: {
     transcribeInbound?: boolean;
@@ -37,6 +38,7 @@ export const SoyehtAccountConfigSchema: JsonSchema = {
     enabled: { type: "boolean" },
     backendBaseUrl: { type: "string" },
     pluginAuthToken: { type: "string" },
+    gatewayUrl: { type: "string" },
     allowProactive: { type: "boolean" },
     audio: {
       type: "object",
@@ -367,6 +369,51 @@ export const PairingQrPayloadSchema: JsonSchema = {
   },
 };
 
+export type PairingQrPayloadV2 = {
+  version: 2;
+  type: "soyeht_pairing_qr";
+  gatewayUrl: string;
+  accountId: string;
+  pairingToken: string;
+  expiresAt: number;
+  allowOverwrite: boolean;
+  pluginIdentityKey: string;
+  pluginDhKey: string;
+  fingerprint: string;
+  signature: string;
+};
+
+export const PairingQrPayloadV2Schema: JsonSchema = {
+  type: "object",
+  additionalProperties: false,
+  required: [
+    "version",
+    "type",
+    "gatewayUrl",
+    "accountId",
+    "pairingToken",
+    "expiresAt",
+    "allowOverwrite",
+    "pluginIdentityKey",
+    "pluginDhKey",
+    "fingerprint",
+    "signature",
+  ],
+  properties: {
+    version: { const: 2 },
+    type: { const: "soyeht_pairing_qr" },
+    gatewayUrl: { type: "string", minLength: 1 },
+    accountId: { type: "string" },
+    pairingToken: { type: "string" },
+    expiresAt: { type: "number" },
+    allowOverwrite: { type: "boolean" },
+    pluginIdentityKey: { type: "string" },
+    pluginDhKey: { type: "string" },
+    fingerprint: { type: "string" },
+    signature: { type: "string" },
+  },
+};
+
 export type HandshakeFinishV2 = {
   version: 2;
   accountId: string;
@@ -397,6 +444,11 @@ export const SOYEHT_CAPABILITIES = {
   voiceContractVersion: 1,
   pipeline: "stt->llm->tts" as const,
   supportedContentTypes: ["text", "audio", "file"] as const,
+  transport: {
+    direct: true,
+    backend: true,
+    defaultMode: "direct" as const,
+  },
   security: {
     version: 2,
     pairingMode: "qr_token" as const,

package/src/version.ts

@@ -1 +1 @@
-export const PLUGIN_VERSION = "0.1.2";
+export const PLUGIN_VERSION = "0.2.0";