@newbase-clawchat/openclaw-clawchat 2026.4.29 → 2026.5.4

package/dist/src/login.runtime.js

@@ -0,0 +1,132 @@
+import { createInterface } from "node:readline/promises";
+import { createOpenclawClawlingApiClient } from "./api-client.js";
+import { ClawlingApiError } from "./api-types.js";
+import { CHANNEL_ID, mergeOpenclawClawchatToolAllow, resolveOpenclawClawlingAccount, } from "./config.js";
+/**
+ * Platform tag sent to `/v1/agents/connect`. Identifies the host of this
+ * agent runtime — openclaw's bundled clawchat channel.
+ */
+export const AGENTS_CONNECT_PLATFORM = "openclaw";
+/**
+ * Agent type tag sent to `/v1/agents/connect`. The clawchat channel is
+ * always a bot; humans don't log in through this flow.
+ */
+export const AGENTS_CONNECT_TYPE = "clawbot";
+/**
+ * Prompt the operator for an invite code.
+ *
+ * The prompt text is emitted via `runtime.log` so it flows through the
+ * same openclaw logging pipeline every other channel plugin uses (no
+ * clack frame, no raw-mode takeover, no TTY detection). Input is read
+ * from stdin with `node:readline` — Enter-to-submit is plain language in
+ * the prompt so any upstream LLM / orchestrator reading the log stream
+ * knows a newline is expected, and the behavior is identical under a
+ * TTY, piped stdin, or a test harness.
+ */
+async function promptInviteCodeFromStdin(runtime) {
+    runtime.log("Please enter your ClawChat invite code (press Enter to submit):");
+    let rl;
+    try {
+        rl = createInterface({ input: process.stdin, output: process.stdout });
+        const answer = await rl.question("> ");
+        return answer.trim();
+    }
+    finally {
+        rl?.close();
+    }
+}
+function buildLoginConfig(cfg, result) {
+    const channels = (cfg.channels ?? {});
+    const existing = (channels[CHANNEL_ID] ?? {});
+    const nextSection = {
+        ...existing,
+        enabled: true,
+        token: result.access_token,
+        userId: result.agent.user_id,
+    };
+    if (result.refresh_token) {
+        nextSection.refreshToken = result.refresh_token;
+    }
+    return mergeOpenclawClawchatToolAllow({
+        ...cfg,
+        channels: { ...channels, [CHANNEL_ID]: nextSection },
+    });
+}
+async function persistLoginConfig(params, result) {
+    if (params.mutateConfigFile) {
+        await params.mutateConfigFile({
+            afterWrite: { mode: "auto" },
+            mutate(draft) {
+                Object.assign(draft, buildLoginConfig(draft, result));
+            },
+        });
+        return;
+    }
+    if (params.persistConfig) {
+        await params.persistConfig(buildLoginConfig(params.cfg, result));
+        return;
+    }
+    throw new Error("openclaw-clawchat: mutateConfigFile is required to persist login credentials");
+}
+/**
+ * Run the invite-code credential exchange used by `clawchat_activate`,
+ * `openclaw channels add --channel openclaw-clawchat --token <invite-code>`,
+ * and `openclaw channels login --channel openclaw-clawchat`:
+ *   1. Read the existing channel section; require `baseUrl` to be set so we
+ *      know which server to hit.
+ *   2. Prompt the user for an invite code on stdin.
+ *   3. POST it to `${baseUrl}/v1/agents/connect`.
+ *   4. Write the returned `websocket_url` / `token` / `user_id` back into
+ *      the config so subsequent Gateway runs pick them up.
+ *
+ * Errors surface with clear messages (missing baseUrl, empty invite,
+ * server-side rejection) so the caller can relay them to the operator.
+ */
+export async function runOpenclawClawlingLogin(params) {
+    const { cfg, runtime } = params;
+    // `resolveOpenclawClawlingAccount` falls back to the built-in
+    // `DEFAULT_BASE_URL` / `DEFAULT_WEBSOCKET_URL` when the operator has not
+    // overridden them, so login works without a prior `openclaw channels setup --channel openclaw-clawchat`.
+    const account = resolveOpenclawClawlingAccount(cfg);
+    const inviteCode = (await (params.readInviteCode ?? (() => promptInviteCodeFromStdin(runtime)))()).trim();
+    if (!inviteCode) {
+        throw new Error("Login aborted: invite code is required.");
+    }
+    const apiClient = (params.apiClientFactory ?? createOpenclawClawlingApiClient)({
+        baseUrl: account.baseUrl,
+        // Pre-login we may not have a token yet. Send the current one (or empty)
+        // — the server should accept an unauthenticated invite-code exchange.
+        token: account.token || "",
+    });
+    runtime.log("Verifying invite code …");
+    let result;
+    try {
+        result = await apiClient.agentsConnect({
+            code: inviteCode,
+            platform: AGENTS_CONNECT_PLATFORM,
+            type: AGENTS_CONNECT_TYPE,
+        });
+    }
+    catch (err) {
+        if (err instanceof ClawlingApiError) {
+            throw new Error(`agents/connect failed (${err.kind}): ${err.message}`);
+        }
+        throw err;
+    }
+    if (!result?.access_token || !result?.agent?.user_id) {
+        throw new Error(`agents/connect response missing required fields (access_token / agent.user_id): ${JSON.stringify(result)}`);
+    }
+    const tokenPreview = redactToken(result.access_token);
+    runtime.log(`Updating config: channels.${CHANNEL_ID}.token=${tokenPreview} userId=${result.agent.user_id}${result.refresh_token ? " refreshToken=***" : ""} …`);
+    await persistLoginConfig(params, result);
+    runtime.log(`Config file updated.`);
+    runtime.log(`openclaw-clawchat login succeeded (user_id=${result.agent.user_id}, nickname=${result.agent.nickname || "-"}).`);
+}
+/** Shortens a token for display logs without revealing the full secret. */
+function redactToken(token) {
+    if (!token)
+        return "(empty)";
+    if (token.length <= 8)
+        return "***";
+    return `${token.slice(0, 4)}…${token.slice(-4)}`;
+}

package/dist/src/media-runtime.js

@@ -0,0 +1,85 @@
+export function inferMediaKindFromMime(mime) {
+    if (!mime)
+        return "file";
+    if (mime.startsWith("image/"))
+        return "image";
+    if (mime.startsWith("audio/"))
+        return "audio";
+    if (mime.startsWith("video/"))
+        return "video";
+    return "file";
+}
+const DEFAULT_MEDIA_MAX_BYTES = 20 * 1024 * 1024;
+/**
+ * Fetch each remote URL via the shared media runtime, persist to a local
+ * cache, and return the list of local paths.
+ *
+ * Failed items are logged at info level and dropped; the remaining items
+ * still resolve so a single bad URL doesn't blow up the whole inbound turn.
+ */
+export async function fetchInboundMedia(items, ctx) {
+    if (items.length === 0)
+        return [];
+    const maxBytes = ctx.maxBytes ?? DEFAULT_MEDIA_MAX_BYTES;
+    const paths = [];
+    for (const item of items) {
+        try {
+            const fetched = await ctx.runtime.channel.media.fetchRemoteMedia({
+                url: item.url,
+                maxBytes,
+            });
+            const saved = await ctx.runtime.channel.media.saveMediaBuffer(fetched.buffer, fetched.contentType ?? item.mime, "openclaw-clawchat-inbound", maxBytes, item.name ?? fetched.fileName);
+            paths.push(saved.path);
+        }
+        catch (err) {
+            ctx.log?.info?.(`openclaw-clawchat inbound media skipped: ${item.url} (${err instanceof Error ? err.message : String(err)})`);
+        }
+    }
+    return paths;
+}
+/**
+ * Upload each URL (remote or local path) to /media/upload via the api
+ * client and return a fragment ready to splice into `body.fragments`.
+ *
+ * Uses the host runtime's `runtime.media.loadWebMedia`, so local-root
+ * enforcement and media-loading policy stay aligned with the current
+ * OpenClaw runtime instead of a directly imported helper.
+ *
+ * Single-upload failures log at error and are dropped; the remaining
+ * fragments still come back so a partially-failing batch still sends the
+ * working media.
+ */
+export async function uploadOutboundMedia(urls, ctx) {
+    if (urls.length === 0)
+        return [];
+    const maxBytes = ctx.maxBytes ?? DEFAULT_MEDIA_MAX_BYTES;
+    const out = [];
+    for (const url of urls) {
+        try {
+            const loaded = await ctx.runtime.media.loadWebMedia(url, {
+                maxBytes,
+                ...(ctx.mediaLocalRoots && ctx.mediaLocalRoots.length > 0
+                    ? { localRoots: ctx.mediaLocalRoots }
+                    : {}),
+            });
+            const uploaded = await ctx.apiClient.uploadMedia({
+                buffer: loaded.buffer,
+                filename: loaded.fileName ?? "upload.bin",
+                mime: loaded.contentType,
+            });
+            const fragment = {
+                kind: inferMediaKindFromMime(uploaded.mime),
+                url: uploaded.url,
+                mime: uploaded.mime,
+                size: uploaded.size,
+            };
+            if (loaded.fileName)
+                fragment.name = loaded.fileName;
+            out.push(fragment);
+        }
+        catch (err) {
+            ctx.log?.error?.(`openclaw-clawchat outbound media upload failed: ${url} (${err instanceof Error ? err.message : String(err)})`);
+        }
+    }
+    return out;
+}

package/dist/src/message-mapper.js

@@ -0,0 +1,82 @@
+const MEDIA_KINDS = new Set(["image", "file", "audio", "video"]);
+function isMediaKind(kind) {
+    return MEDIA_KINDS.has(kind);
+}
+function renderMediaPlaceholder(fragment) {
+    const kind = String(fragment.kind ?? "");
+    const url = typeof fragment.url === "string" ? fragment.url : "";
+    if (!url)
+        return "";
+    const name = typeof fragment.name === "string" && fragment.name.trim()
+        ? fragment.name
+        : kind === "image"
+            ? "image"
+            : kind === "audio"
+                ? "audio"
+                : kind === "video"
+                    ? "video"
+                    : "file";
+    return kind === "image" ? `![${name}](${url})` : `[${name}](${url})`;
+}
+export function fragmentsToText(fragments, opts = {}) {
+    const fallback = opts.mentionFallbackIds ?? [];
+    let fallbackCursor = 0;
+    const parts = fragments.map((fragment) => {
+        const f = fragment;
+        if (f.kind === "text" && typeof f.text === "string") {
+            return f.text;
+        }
+        if (f.kind === "mention") {
+            const display = typeof f.display === "string" ? f.display : undefined;
+            if (display && display.trim())
+                return display;
+            const id = typeof f.user_id === "string" ? f.user_id : undefined;
+            if (id && id.trim())
+                return `@${id}`;
+            const fallbackId = fallback[fallbackCursor++];
+            if (fallbackId)
+                return `@${fallbackId}`;
+            return "";
+        }
+        if (typeof f.kind === "string" && isMediaKind(f.kind)) {
+            return renderMediaPlaceholder(f);
+        }
+        return "";
+    });
+    return parts.join("").trim();
+}
+export function textToFragments(text) {
+    if (!text || !text.trim())
+        return [];
+    return [{ kind: "text", text }];
+}
+/**
+ * Extract media fragments from a body (image/file/audio/video). Skips
+ * entries missing `url`. Preserves all optional metadata fields the
+ * SDK passes through (mime/size/width/height/duration/name).
+ */
+export function extractMediaFragments(fragments) {
+    const out = [];
+    for (const fragment of fragments) {
+        const f = fragment;
+        if (typeof f.kind !== "string" || !isMediaKind(f.kind))
+            continue;
+        if (typeof f.url !== "string" || !f.url)
+            continue;
+        const item = { kind: f.kind, url: f.url };
+        if (typeof f.name === "string")
+            item.name = f.name;
+        if (typeof f.mime === "string")
+            item.mime = f.mime;
+        if (typeof f.size === "number")
+            item.size = f.size;
+        if (typeof f.width === "number")
+            item.width = f.width;
+        if (typeof f.height === "number")
+            item.height = f.height;
+        if (typeof f.duration === "number")
+            item.duration = f.duration;
+        out.push(item);
+    }
+    return out;
+}

package/dist/src/outbound.js

@@ -0,0 +1,181 @@
+import { createAttachedChannelResultAdapter, } from "openclaw/plugin-sdk/channel-send-result";
+import { chunkMarkdownText } from "openclaw/plugin-sdk/reply-runtime";
+import { createOpenclawClawlingApiClient } from "./api-client.js";
+import { CHANNEL_ID, resolveOpenclawClawlingAccount } from "./config.js";
+import { textToFragments } from "./message-mapper.js";
+import { uploadOutboundMedia } from "./media-runtime.js";
+import { getOpenclawClawlingClient, getOpenclawClawlingRuntime, waitForOpenclawClawlingClient, } from "./runtime.js";
+/**
+ * Parse an agent-initiated outbound recipient string into the new-protocol
+ * `chat_id` + `chat_type` pair.
+ *
+ * Accepted forms (case-insensitive prefix):
+ *   - `cc:{chat_id}`                  → direct
+ *   - `clawchat:{chat_id}`            → direct
+ *   - `openclaw-clawchat:{chat_id}`   → direct
+ *   - `cc:direct:{chat_id}`           → direct
+ *   - `cc:group:{chat_id}`            → group
+ *   - `clawchat:direct:{chat_id}`     → direct
+ *   - `clawchat:group:{chat_id}`      → group
+ *   - `openclaw-clawchat:direct:{chat_id}` → direct
+ *   - `openclaw-clawchat:group:{chat_id}`  → group
+ *   - bare `{chat_id}`                → direct (backward compat)
+ */
+export function parseOpenclawRecipient(to) {
+    const raw = (to ?? "").trim();
+    if (!raw)
+        throw new Error("openclaw-clawchat: outbound `to` is empty");
+    const firstColon = raw.indexOf(":");
+    if (firstColon < 0)
+        return { chatId: raw, chatType: "direct" };
+    const scheme = raw.slice(0, firstColon).toLowerCase();
+    const rest = raw.slice(firstColon + 1);
+    if (scheme !== "cc" && scheme !== "clawchat" && scheme !== CHANNEL_ID) {
+        return { chatId: raw, chatType: "direct" };
+    }
+    const secondColon = rest.indexOf(":");
+    if (secondColon >= 0) {
+        const typeToken = rest.slice(0, secondColon).toLowerCase();
+        const chatId = rest.slice(secondColon + 1).trim();
+        if ((typeToken === "direct" || typeToken === "group") && chatId) {
+            return { chatId, chatType: typeToken };
+        }
+    }
+    const chatId = rest.trim();
+    if (!chatId)
+        throw new Error(`openclaw-clawchat: missing chat_id in "${to}"`);
+    return { chatId, chatType: "direct" };
+}
+export async function sendOpenclawClawlingText(params) {
+    const text = (params.text ?? "").trim();
+    const richFragments = params.richFragments ?? [];
+    const mediaFragments = params.mediaFragments ?? [];
+    if (!text && richFragments.length === 0 && mediaFragments.length === 0) {
+        params.log?.info?.(`[${params.account.accountId}] openclaw-clawchat outbound suppressed: empty text and no media`);
+        return null;
+    }
+    const mentions = params.mentions ?? [];
+    const textFragments = text ? textToFragments(text) : [];
+    // Cast at the SDK boundary: each MediaItem object is structurally compatible
+    // with one of the SDK's narrow Fragment members (ImageFragment / FileFragment /
+    // AudioFragment / VideoFragment) based on its runtime `kind`. The wide local
+    // shape lets us build a single uniform array without a per-kind switch.
+    const fragments = [...textFragments, ...richFragments, ...mediaFragments];
+    const useReply = params.replyCtx && mediaFragments.length === 0;
+    if (params.replyCtx && mediaFragments.length > 0) {
+        params.log?.info?.(`[${params.account.accountId}] openclaw-clawchat replyCtx + media: downgraded to sendMessage`);
+    }
+    let ack;
+    let mode;
+    if (useReply && params.replyCtx) {
+        mode = "reply";
+        ack = await params.client.replyMessage({
+            chat_id: params.to.chatId,
+            mode: "normal",
+            replyTo: {
+                msgId: params.replyCtx.replyToMessageId,
+                senderId: params.replyCtx.replyPreviewChatId ?? params.replyCtx.replyPreviewSenderId,
+                nickName: params.replyCtx.replyPreviewNickName,
+                fragments: [{ kind: "text", text: params.replyCtx.replyPreviewText }],
+            },
+            body: { fragments },
+            context: { mentions },
+        });
+    }
+    else {
+        mode = "send";
+        ack = await params.client.sendMessage({
+            chat_id: params.to.chatId,
+            mode: "normal",
+            body: { fragments },
+            context: { mentions, reply: null },
+        });
+    }
+    params.log?.info?.(`[${params.account.accountId}] openclaw-clawchat outbound mode=${mode} msg=${ack.payload.message_id} text_len=${text.length} media=${mediaFragments.length} trace=${ack.trace_id}`);
+    return {
+        messageId: ack.payload.message_id,
+        acceptedAt: ack.payload.accepted_at,
+    };
+}
+/**
+ * Send one or more media fragments (image / file / audio / video) to the
+ * given target, with an optional text caption.
+ *
+ * Validates that mediaFragments is non-empty (returns null + info log
+ * otherwise) and delegates to {@link sendOpenclawClawlingText} for the
+ * actual envelope construction. Reuses the existing replyCtx-downgrade,
+ * ack backfill, and log shape.
+ */
+export async function sendOpenclawClawlingMedia(params) {
+    if (params.mediaFragments.length === 0) {
+        params.log?.info?.(`[${params.account.accountId}] openclaw-clawchat sendMedia called with empty mediaFragments; suppressed`);
+        return null;
+    }
+    return await sendOpenclawClawlingText({
+        client: params.client,
+        account: params.account,
+        to: params.to,
+        text: params.text ?? "",
+        mediaFragments: params.mediaFragments,
+        ...(params.replyCtx ? { replyCtx: params.replyCtx } : {}),
+        ...(params.mentions ? { mentions: params.mentions } : {}),
+        ...(params.log ? { log: params.log } : {}),
+    });
+}
+export const openclawClawlingOutbound = {
+    deliveryMode: "direct",
+    chunker: (text, limit) => chunkMarkdownText(text, limit),
+    chunkerMode: "markdown",
+    textChunkLimit: 4000,
+    ...createAttachedChannelResultAdapter({
+        channel: CHANNEL_ID,
+        sendText: async ({ cfg, to, text }) => {
+            const account = resolveOpenclawClawlingAccount(cfg);
+            const client = getOpenclawClawlingClient(account.accountId) ??
+                (await waitForOpenclawClawlingClient(account.accountId));
+            const result = await sendOpenclawClawlingText({
+                client,
+                account,
+                to: parseOpenclawRecipient(to),
+                text,
+            });
+            return {
+                to,
+                messageId: result?.messageId ?? `${account.userId}-${Date.now()}`,
+            };
+        },
+        sendMedia: async ({ cfg, to, text, mediaUrl, mediaLocalRoots }) => {
+            const account = resolveOpenclawClawlingAccount(cfg);
+            const client = getOpenclawClawlingClient(account.accountId) ??
+                (await waitForOpenclawClawlingClient(account.accountId));
+            if (!mediaUrl?.trim()) {
+                throw new Error("openclaw-clawchat sendMedia requires mediaUrl");
+            }
+            const runtime = getOpenclawClawlingRuntime();
+            const apiClient = createOpenclawClawlingApiClient({
+                baseUrl: account.baseUrl,
+                token: account.token,
+                userId: account.userId,
+            });
+            const mediaFragments = await uploadOutboundMedia([mediaUrl.trim()], {
+                apiClient,
+                runtime,
+                ...(mediaLocalRoots ? { mediaLocalRoots } : {}),
+            });
+            if (mediaFragments.length === 0) {
+                throw new Error(`openclaw-clawchat failed to upload media: ${mediaUrl}`);
+            }
+            const result = await sendOpenclawClawlingMedia({
+                client,
+                account,
+                to: parseOpenclawRecipient(to),
+                text,
+                mediaFragments,
+            });
+            return {
+                to,
+                messageId: result?.messageId ?? `${account.userId}-${Date.now()}`,
+            };
+        },
+    }),
+};

package/dist/src/protocol.js

@@ -0,0 +1,38 @@
+/**
+ * Local narrow guards for inbound protocol envelopes.
+ *
+ * The SDK's `message` event hands us `Envelope<unknown>`. Before casting the
+ * payload to `DownlinkMessageSendPayload` we run these cheap structural checks
+ * so runtime errors surface as skipped messages, not crashes.
+ */
+export function isInboundMessagePayload(payload) {
+    if (!payload || typeof payload !== "object")
+        return false;
+    const p = payload;
+    if (typeof p.message_id !== "string" || !p.message_id)
+        return false;
+    if (typeof p.message !== "object" || p.message === null)
+        return false;
+    const m = p.message;
+    if (typeof m.body !== "object" || m.body === null)
+        return false;
+    const body = m.body;
+    if (!Array.isArray(body.fragments))
+        return false;
+    return true;
+}
+export function hasRenderableText(message) {
+    const fragments = message?.body?.fragments ?? [];
+    return fragments.some((f) => ((f.kind === "text" &&
+        typeof f.text === "string" &&
+        f.text.trim().length > 0) ||
+        (typeof f.kind === "string" &&
+            ["image", "file", "audio", "video"].includes(f.kind) &&
+            typeof f.url === "string" &&
+            f.url.trim().length > 0)));
+}
+export function isGroupSender(sender) {
+    if (!sender || typeof sender !== "object")
+        return false;
+    return sender.type === "group";
+}