@voicyclaw/voicyclaw 0.0.2

package/src/dispatch.ts

@@ -0,0 +1,175 @@
+import type {
+  OpenClawConfig,
+  PluginRuntime,
+  ReplyPayload,
+} from "openclaw/plugin-sdk";
+
+import type { ResolvedVoicyClawAccount } from "./config.js";
+import type { VoicyClawSttResultMessage } from "./protocol.js";
+
+type Logger = {
+  info: (message: string) => void;
+  warn: (message: string) => void;
+  error: (message: string) => void;
+};
+
+type VoicyClawReplyClient = {
+  sendPreview: (utteranceId: string, text: string, isFinal?: boolean) => void;
+  sendText: (utteranceId: string, text: string, isFinal?: boolean) => void;
+};
+
+type VoicyClawChannelRuntime = Pick<
+  PluginRuntime["channel"],
+  "reply" | "routing" | "session"
+>;
+
+export async function dispatchVoicyClawTranscript(params: {
+  account: ResolvedVoicyClawAccount;
+  cfg: OpenClawConfig;
+  channelRuntime: VoicyClawChannelRuntime;
+  client: VoicyClawReplyClient;
+  message: VoicyClawSttResultMessage;
+  log: Logger;
+  onOutbound?: () => void;
+}) {
+  const { account, cfg, channelRuntime, client, message, log, onOutbound } =
+    params;
+  const route = channelRuntime.routing.resolveAgentRoute({
+    cfg,
+    channel: "voicyclaw",
+    accountId: account.accountId,
+    peer: {
+      kind: "direct",
+      id: buildVoicyClawPeerId(account),
+    },
+  });
+  const storePath = channelRuntime.session.resolveStorePath(
+    cfg.session?.store,
+    {
+      agentId: route.agentId,
+    },
+  );
+  const previousTimestamp = channelRuntime.session.readSessionUpdatedAt({
+    storePath,
+    sessionKey: route.sessionKey,
+  });
+  const envelopeOptions =
+    channelRuntime.reply.resolveEnvelopeFormatOptions(cfg);
+  const receivedAt = Date.now();
+  const body = channelRuntime.reply.formatAgentEnvelope({
+    channel: "VoicyClaw",
+    from: buildConversationLabel(account),
+    timestamp: receivedAt,
+    previousTimestamp,
+    envelope: envelopeOptions,
+    body: message.text,
+  });
+  const ctxPayload = channelRuntime.reply.finalizeInboundContext({
+    Body: body,
+    BodyForAgent: message.text,
+    RawBody: message.text,
+    CommandBody: message.text,
+    From: buildVoicyClawTarget(account),
+    To: buildVoicyClawTarget(account),
+    SessionKey: route.sessionKey,
+    AccountId: route.accountId,
+    ChatType: "direct",
+    ConversationLabel: buildConversationLabel(account),
+    SenderName: "VoicyClaw User",
+    SenderId: buildVoicyClawPeerId(account),
+    Provider: "voicyclaw",
+    Surface: "voicyclaw",
+    MessageSid: message.utterance_id,
+    MessageSidFull: message.utterance_id,
+    Timestamp: receivedAt,
+    OriginatingChannel: "voicyclaw",
+    OriginatingTo: buildVoicyClawTarget(account),
+    CommandAuthorized: true,
+  });
+
+  await channelRuntime.session.recordInboundSession({
+    storePath,
+    sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
+    ctx: ctxPayload,
+    onRecordError: (error) => {
+      log.warn(
+        `[voicyclaw] failed recording inbound session for ${message.utterance_id}: ${String(
+          error,
+        )}`,
+      );
+    },
+  });
+
+  const result =
+    await channelRuntime.reply.dispatchReplyWithBufferedBlockDispatcher({
+      ctx: ctxPayload,
+      cfg,
+      dispatcherOptions: {
+        deliver: async (payload, info) => {
+          const text = replyPayloadToText(payload);
+          if (!text) {
+            return;
+          }
+
+          if (info.kind === "final") {
+            client.sendText(message.utterance_id, text, true);
+          } else {
+            client.sendPreview(message.utterance_id, text, false);
+          }
+          onOutbound?.();
+        },
+        onReplyStart: () => {
+          log.info(
+            `[voicyclaw] agent reply started for ${message.utterance_id} on ${route.sessionKey}`,
+          );
+        },
+        onError: (error, info) => {
+          log.warn(
+            `[voicyclaw] ${info.kind} reply failed for ${message.utterance_id}: ${String(
+              error,
+            )}`,
+          );
+        },
+      },
+    });
+
+  log.info(
+    `[voicyclaw] dispatched ${message.utterance_id} via ${route.agentId} (queuedFinal=${String(
+      result.queuedFinal,
+    )})`,
+  );
+
+  return {
+    route,
+    ctxPayload,
+    result,
+  };
+}
+
+function buildConversationLabel(account: ResolvedVoicyClawAccount) {
+  if (account.workspaceId) {
+    return `${account.workspaceId}/${account.channelId}`;
+  }
+
+  return account.channelId;
+}
+
+function buildVoicyClawPeerId(account: ResolvedVoicyClawAccount) {
+  return account.workspaceId
+    ? `${account.workspaceId}:${account.channelId}`
+    : account.channelId;
+}
+
+function buildVoicyClawTarget(account: ResolvedVoicyClawAccount) {
+  return `voicyclaw:${buildVoicyClawPeerId(account)}`;
+}
+
+export function replyPayloadToText(payload: ReplyPayload) {
+  const parts = [
+    payload.text?.trim(),
+    payload.mediaUrl?.trim(),
+    ...(payload.mediaUrls ?? []).map((entry) => entry.trim()),
+  ].filter(Boolean);
+
+  return parts.join("\n").trim();
+}

package/src/gateway.ts

@@ -0,0 +1,218 @@
+import type { ChannelGatewayAdapter, PluginRuntime } from "openclaw/plugin-sdk";
+import type { ResolvedVoicyClawAccount } from "./config.js";
+import { buildVoicyClawSocketUrl } from "./config.js";
+import { dispatchVoicyClawTranscript } from "./dispatch.js";
+import type { VoicyClawRuntime } from "./runtime.js";
+import { VoicyClawSocketClient } from "./socket-client.js";
+
+export function createVoicyClawGatewayAdapter(
+  runtime: VoicyClawRuntime,
+  channelRuntime: PluginRuntime["channel"],
+): ChannelGatewayAdapter<ResolvedVoicyClawAccount> {
+  return {
+    startAccount: async (ctx) => {
+      const account = ctx.account;
+      runtime.ensureAccount(account);
+
+      if (!account.enabled) {
+        runtime.markStopped(account);
+        ctx.setStatus({
+          accountId: account.accountId,
+          running: false,
+          connected: false,
+          lastStopAt: Date.now(),
+        });
+        await waitUntilAbortSignal(ctx.abortSignal);
+        return;
+      }
+
+      if (!account.configured) {
+        runtime.markStopped(account);
+        ctx.setStatus({
+          accountId: account.accountId,
+          running: false,
+          connected: false,
+          lastStopAt: Date.now(),
+          lastError: "missing VoicyClaw token",
+        });
+        await waitUntilAbortSignal(ctx.abortSignal);
+        return;
+      }
+
+      while (!ctx.abortSignal.aborted) {
+        const socketUrl = buildVoicyClawSocketUrl(account.url);
+        let client: VoicyClawSocketClient | null = null;
+
+        runtime.markStarting(account);
+        ctx.setStatus({
+          accountId: account.accountId,
+          running: true,
+          connected: false,
+          lastStartAt: Date.now(),
+          lastError: null,
+          baseUrl: account.url,
+          audience: account.channelId,
+        });
+
+        try {
+          client = new VoicyClawSocketClient({
+            account,
+            socketUrl,
+            logger: ctx.log ?? consoleLogger,
+            onTranscript: async (message) => {
+              runtime.markInbound(account.accountId);
+              ctx.setStatus({
+                accountId: account.accountId,
+                lastInboundAt: Date.now(),
+              });
+
+              if (!message.is_final) {
+                return;
+              }
+
+              if (account.devEchoReplies) {
+                client?.sendText(
+                  message.utterance_id,
+                  `VoicyClaw plugin echo: ${message.text || "(empty transcript)"}`,
+                  true,
+                );
+                runtime.markOutbound(account.accountId);
+                ctx.setStatus({
+                  accountId: account.accountId,
+                  lastOutboundAt: Date.now(),
+                });
+                return;
+              }
+
+              const activeClient = client;
+              if (!activeClient) {
+                return;
+              }
+
+              await dispatchVoicyClawTranscript({
+                account,
+                cfg: ctx.cfg,
+                channelRuntime,
+                client: activeClient,
+                message,
+                log: ctx.log ?? consoleLogger,
+                onOutbound: () => {
+                  runtime.markOutbound(account.accountId);
+                  ctx.setStatus({
+                    accountId: account.accountId,
+                    lastOutboundAt: Date.now(),
+                  });
+                },
+              });
+            },
+          });
+
+          const welcome = await client.connect();
+          runtime.markConnected(account, welcome.session_id);
+          ctx.setStatus({
+            accountId: account.accountId,
+            running: true,
+            connected: true,
+            lastConnectedAt: Date.now(),
+            lastError: null,
+            lastDisconnect: null,
+          });
+          ctx.log?.info?.(
+            `[voicyclaw] connected ${account.accountId} to ${socketUrl}`,
+          );
+
+          await client.waitUntilClosed();
+          if (ctx.abortSignal.aborted) {
+            break;
+          }
+
+          runtime.markDisconnected(account, "socket closed");
+          ctx.setStatus({
+            accountId: account.accountId,
+            running: true,
+            connected: false,
+            lastError: "socket closed",
+            lastDisconnect: {
+              at: Date.now(),
+              error: "socket closed",
+            },
+          });
+        } catch (error) {
+          const message =
+            error instanceof Error ? error.message : String(error);
+          runtime.markDisconnected(account, message);
+          ctx.setStatus({
+            accountId: account.accountId,
+            running: true,
+            connected: false,
+            lastError: message,
+            lastDisconnect: {
+              at: Date.now(),
+              error: message,
+            },
+          });
+          ctx.log?.warn?.(
+            `[voicyclaw] connector ${account.accountId} disconnected: ${message}`,
+          );
+        } finally {
+          await client?.close().catch(() => undefined);
+        }
+
+        if (ctx.abortSignal.aborted) {
+          break;
+        }
+
+        await sleep(account.reconnectBackoffMs, ctx.abortSignal);
+      }
+
+      runtime.markStopped(account);
+      ctx.setStatus({
+        accountId: account.accountId,
+        running: false,
+        connected: false,
+        lastStopAt: Date.now(),
+      });
+    },
+  };
+}
+
+const consoleLogger = {
+  info: (message: string) => console.log(message),
+  warn: (message: string) => console.warn(message),
+  error: (message: string) => console.error(message),
+};
+
+async function sleep(ms: number, signal: AbortSignal) {
+  if (signal.aborted) {
+    return;
+  }
+
+  await new Promise<void>((resolve) => {
+    const timeout = globalThis.setTimeout(() => {
+      cleanup();
+      resolve();
+    }, ms);
+
+    const cleanup = () => {
+      globalThis.clearTimeout(timeout);
+      signal.removeEventListener("abort", onAbort);
+    };
+
+    const onAbort = () => {
+      cleanup();
+      resolve();
+    };
+
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+async function waitUntilAbortSignal(signal: AbortSignal) {
+  if (signal.aborted) {
+    return;
+  }
+
+  await new Promise<void>((resolve) => {
+    signal.addEventListener("abort", () => resolve(), { once: true });
+  });
+}

package/src/protocol.ts

@@ -0,0 +1,205 @@
+export const VOICYCLAW_PROTOCOL_VERSION = "0.1" as const;
+
+export type VoicyClawProtocolVersion = typeof VOICYCLAW_PROTOCOL_VERSION;
+
+export type VoicyClawHelloMessage = {
+  type: "HELLO";
+  api_key: string;
+  bot_id: string;
+  channel_id: string;
+  protocol_version: VoicyClawProtocolVersion;
+};
+
+export type VoicyClawWelcomeMessage = {
+  type: "WELCOME";
+  session_id: string;
+  channel_id: string;
+  bot_id: string;
+};
+
+export type VoicyClawErrorMessage = {
+  type: "ERROR";
+  code:
+    | "AUTH_FAILED"
+    | "CHANNEL_NOT_FOUND"
+    | "BOT_ALREADY_CONNECTED"
+    | "PROTOCOL_VERSION_UNSUPPORTED";
+  message: string;
+};
+
+export type VoicyClawDisconnectMessage = {
+  type: "DISCONNECT";
+  session_id: string;
+  reason: string;
+};
+
+export type VoicyClawAudioStartMessage = {
+  type: "AUDIO_START";
+  session_id: string;
+  utterance_id: string;
+};
+
+export type VoicyClawAudioEndMessage = {
+  type: "AUDIO_END";
+  session_id: string;
+  utterance_id: string;
+};
+
+export type VoicyClawSttResultMessage = {
+  type: "STT_RESULT";
+  session_id: string;
+  utterance_id: string;
+  text: string;
+  is_final: boolean;
+};
+
+export type VoicyClawTtsTextMessage = {
+  type: "TTS_TEXT";
+  session_id: string;
+  utterance_id: string;
+  text: string;
+  is_final: boolean;
+};
+
+export type VoicyClawPreviewTextMessage = {
+  type: "BOT_PREVIEW";
+  session_id: string;
+  utterance_id: string;
+  text: string;
+  is_final: boolean;
+};
+
+export type VoicyClawServerMessage =
+  | VoicyClawWelcomeMessage
+  | VoicyClawErrorMessage
+  | VoicyClawDisconnectMessage
+  | VoicyClawAudioStartMessage
+  | VoicyClawAudioEndMessage
+  | VoicyClawSttResultMessage;
+
+export function createHelloMessage(params: {
+  token: string;
+  botId: string;
+  channelId: string;
+}): VoicyClawHelloMessage {
+  return {
+    type: "HELLO",
+    api_key: params.token,
+    bot_id: params.botId,
+    channel_id: params.channelId,
+    protocol_version: VOICYCLAW_PROTOCOL_VERSION,
+  };
+}
+
+export function createPreviewTextMessage(params: {
+  sessionId: string;
+  utteranceId: string;
+  text: string;
+  isFinal?: boolean;
+}): VoicyClawPreviewTextMessage {
+  return {
+    type: "BOT_PREVIEW",
+    session_id: params.sessionId,
+    utterance_id: params.utteranceId,
+    text: params.text,
+    is_final: params.isFinal ?? false,
+  };
+}
+
+export function createTtsTextMessage(params: {
+  sessionId: string;
+  utteranceId: string;
+  text: string;
+  isFinal?: boolean;
+}): VoicyClawTtsTextMessage {
+  return {
+    type: "TTS_TEXT",
+    session_id: params.sessionId,
+    utterance_id: params.utteranceId,
+    text: params.text,
+    is_final: params.isFinal ?? true,
+  };
+}
+
+export function parseVoicyClawServerMessage(
+  value: unknown,
+): VoicyClawServerMessage | null {
+  if (!isRecord(value) || typeof value.type !== "string") {
+    return null;
+  }
+
+  switch (value.type) {
+    case "WELCOME":
+      return isString(value.session_id) &&
+        isString(value.channel_id) &&
+        isString(value.bot_id)
+        ? {
+            type: "WELCOME",
+            session_id: value.session_id,
+            channel_id: value.channel_id,
+            bot_id: value.bot_id,
+          }
+        : null;
+
+    case "ERROR":
+      return isString(value.code) && isString(value.message)
+        ? {
+            type: "ERROR",
+            code: value.code as VoicyClawErrorMessage["code"],
+            message: value.message,
+          }
+        : null;
+
+    case "DISCONNECT":
+      return isString(value.session_id) && isString(value.reason)
+        ? {
+            type: "DISCONNECT",
+            session_id: value.session_id,
+            reason: value.reason,
+          }
+        : null;
+
+    case "AUDIO_START":
+      return isString(value.session_id) && isString(value.utterance_id)
+        ? {
+            type: "AUDIO_START",
+            session_id: value.session_id,
+            utterance_id: value.utterance_id,
+          }
+        : null;
+
+    case "AUDIO_END":
+      return isString(value.session_id) && isString(value.utterance_id)
+        ? {
+            type: "AUDIO_END",
+            session_id: value.session_id,
+            utterance_id: value.utterance_id,
+          }
+        : null;
+
+    case "STT_RESULT":
+      return isString(value.session_id) &&
+        isString(value.utterance_id) &&
+        isString(value.text) &&
+        typeof value.is_final === "boolean"
+        ? {
+            type: "STT_RESULT",
+            session_id: value.session_id,
+            utterance_id: value.utterance_id,
+            text: value.text,
+            is_final: value.is_final,
+          }
+        : null;
+
+    default:
+      return null;
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function isString(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}