clawdbot 2026.1.4

package/dist/web/session.js

@@ -0,0 +1,346 @@
+import { randomUUID } from "node:crypto";
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { DisconnectReason, fetchLatestBaileysVersion, makeCacheableSignalKeyStore, makeWASocket, useMultiFileAuthState, } from "@whiskeysockets/baileys";
+import qrcode from "qrcode-terminal";
+import { resolveDefaultSessionStorePath } from "../config/sessions.js";
+import { danger, info, success } from "../globals.js";
+import { getChildLogger, toPinoLikeLogger } from "../logging.js";
+import { defaultRuntime } from "../runtime.js";
+import { CONFIG_DIR, ensureDir, jidToE164 } from "../utils.js";
+import { VERSION } from "../version.js";
+export function resolveWebAuthDir() {
+    return path.join(os.homedir(), ".clawdbot", "credentials");
+}
+function resolveWebCredsPath() {
+    return path.join(resolveWebAuthDir(), "creds.json");
+}
+function resolveWebCredsBackupPath() {
+    return path.join(resolveWebAuthDir(), "creds.json.bak");
+}
+export const WA_WEB_AUTH_DIR = path.join(CONFIG_DIR, "credentials");
+let credsSaveQueue = Promise.resolve();
+function enqueueSaveCreds(saveCreds, logger) {
+    credsSaveQueue = credsSaveQueue
+        .then(() => safeSaveCreds(saveCreds, logger))
+        .catch((err) => {
+        logger.warn({ error: String(err) }, "WhatsApp creds save queue error");
+    });
+}
+function readCredsJsonRaw(filePath) {
+    try {
+        if (!fsSync.existsSync(filePath))
+            return null;
+        const stats = fsSync.statSync(filePath);
+        if (!stats.isFile() || stats.size <= 1)
+            return null;
+        return fsSync.readFileSync(filePath, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+function maybeRestoreCredsFromBackup(logger) {
+    try {
+        const credsPath = resolveWebCredsPath();
+        const backupPath = resolveWebCredsBackupPath();
+        const raw = readCredsJsonRaw(credsPath);
+        if (raw) {
+            // Validate that creds.json is parseable.
+            JSON.parse(raw);
+            return;
+        }
+        const backupRaw = readCredsJsonRaw(backupPath);
+        if (!backupRaw)
+            return;
+        // Ensure backup is parseable before restoring.
+        JSON.parse(backupRaw);
+        fsSync.copyFileSync(backupPath, credsPath);
+        logger.warn({ credsPath }, "restored corrupted WhatsApp creds.json from backup");
+    }
+    catch {
+        // ignore
+    }
+}
+async function safeSaveCreds(saveCreds, logger) {
+    try {
+        // Best-effort backup so we can recover after abrupt restarts.
+        // Important: don't clobber a good backup with a corrupted/truncated creds.json.
+        const credsPath = resolveWebCredsPath();
+        const backupPath = resolveWebCredsBackupPath();
+        const raw = readCredsJsonRaw(credsPath);
+        if (raw) {
+            try {
+                JSON.parse(raw);
+                fsSync.copyFileSync(credsPath, backupPath);
+            }
+            catch {
+                // keep existing backup
+            }
+        }
+    }
+    catch {
+        // ignore backup failures
+    }
+    try {
+        await Promise.resolve(saveCreds());
+    }
+    catch (err) {
+        logger.warn({ error: String(err) }, "failed saving WhatsApp creds");
+    }
+}
+/**
+ * Create a Baileys socket backed by the multi-file auth store we keep on disk.
+ * Consumers can opt into QR printing for interactive login flows.
+ */
+export async function createWaSocket(printQr, verbose, opts = {}) {
+    const baseLogger = getChildLogger({ module: "baileys" }, {
+        level: verbose ? "info" : "silent",
+    });
+    const logger = toPinoLikeLogger(baseLogger, verbose ? "info" : "silent");
+    const authDir = resolveWebAuthDir();
+    await ensureDir(authDir);
+    const sessionLogger = getChildLogger({ module: "web-session" });
+    maybeRestoreCredsFromBackup(sessionLogger);
+    const { state, saveCreds } = await useMultiFileAuthState(authDir);
+    const { version } = await fetchLatestBaileysVersion();
+    const sock = makeWASocket({
+        auth: {
+            creds: state.creds,
+            keys: makeCacheableSignalKeyStore(state.keys, logger),
+        },
+        version,
+        logger,
+        printQRInTerminal: false,
+        browser: ["clawdbot", "cli", VERSION],
+        syncFullHistory: false,
+        markOnlineOnConnect: false,
+    });
+    sock.ev.on("creds.update", () => enqueueSaveCreds(saveCreds, sessionLogger));
+    sock.ev.on("connection.update", (update) => {
+        try {
+            const { connection, lastDisconnect, qr } = update;
+            if (qr) {
+                opts.onQr?.(qr);
+                if (printQr) {
+                    console.log("Scan this QR in WhatsApp (Linked Devices):");
+                    qrcode.generate(qr, { small: true });
+                }
+            }
+            if (connection === "close") {
+                const status = getStatusCode(lastDisconnect?.error);
+                if (status === DisconnectReason.loggedOut) {
+                    console.error(danger("WhatsApp session logged out. Run: clawdbot login"));
+                }
+            }
+            if (connection === "open" && verbose) {
+                console.log(success("WhatsApp Web connected."));
+            }
+        }
+        catch (err) {
+            sessionLogger.error({ error: String(err) }, "connection.update handler error");
+        }
+    });
+    // Handle WebSocket-level errors to prevent unhandled exceptions from crashing the process
+    if (sock.ws &&
+        typeof sock.ws.on === "function") {
+        sock.ws.on("error", (err) => {
+            sessionLogger.error({ error: String(err) }, "WebSocket error");
+        });
+    }
+    return sock;
+}
+export async function waitForWaConnection(sock) {
+    return new Promise((resolve, reject) => {
+        const evWithOff = sock.ev;
+        const handler = (...args) => {
+            const update = (args[0] ?? {});
+            if (update.connection === "open") {
+                evWithOff.off?.("connection.update", handler);
+                resolve();
+            }
+            if (update.connection === "close") {
+                evWithOff.off?.("connection.update", handler);
+                reject(update.lastDisconnect ?? new Error("Connection closed"));
+            }
+        };
+        sock.ev.on("connection.update", handler);
+    });
+}
+export function getStatusCode(err) {
+    return (err?.output?.statusCode ??
+        err?.status);
+}
+function safeStringify(value, limit = 800) {
+    try {
+        const seen = new WeakSet();
+        const raw = JSON.stringify(value, (_key, v) => {
+            if (typeof v === "bigint")
+                return v.toString();
+            if (typeof v === "function") {
+                const maybeName = v.name;
+                const name = typeof maybeName === "string" && maybeName.length > 0
+                    ? maybeName
+                    : "anonymous";
+                return `[Function ${name}]`;
+            }
+            if (typeof v === "object" && v) {
+                if (seen.has(v))
+                    return "[Circular]";
+                seen.add(v);
+            }
+            return v;
+        }, 2);
+        if (!raw)
+            return String(value);
+        return raw.length > limit ? `${raw.slice(0, limit)}…` : raw;
+    }
+    catch {
+        return String(value);
+    }
+}
+function extractBoomDetails(err) {
+    if (!err || typeof err !== "object")
+        return null;
+    const output = err?.output;
+    if (!output || typeof output !== "object")
+        return null;
+    const payload = output.payload;
+    const statusCode = typeof output.statusCode === "number"
+        ? output.statusCode
+        : typeof payload?.statusCode === "number"
+            ? payload.statusCode
+            : undefined;
+    const error = typeof payload?.error === "string" ? payload.error : undefined;
+    const message = typeof payload?.message === "string" ? payload.message : undefined;
+    if (!statusCode && !error && !message)
+        return null;
+    return { statusCode, error, message };
+}
+export function formatError(err) {
+    if (err instanceof Error)
+        return err.message;
+    if (typeof err === "string")
+        return err;
+    if (!err || typeof err !== "object")
+        return String(err);
+    // Baileys frequently wraps errors under `error` with a Boom-like shape.
+    const boom = extractBoomDetails(err) ??
+        extractBoomDetails(err?.error) ??
+        extractBoomDetails(err?.lastDisconnect?.error);
+    const status = boom?.statusCode ?? getStatusCode(err);
+    const code = err?.code;
+    const codeText = typeof code === "string" || typeof code === "number"
+        ? String(code)
+        : undefined;
+    const messageCandidates = [
+        boom?.message,
+        typeof err?.message === "string"
+            ? err.message
+            : undefined,
+        typeof err?.error?.message ===
+            "string"
+            ? err.error?.message
+            : undefined,
+    ].filter((v) => Boolean(v && v.trim().length > 0));
+    const message = messageCandidates[0];
+    const pieces = [];
+    if (typeof status === "number")
+        pieces.push(`status=${status}`);
+    if (boom?.error)
+        pieces.push(boom.error);
+    if (message)
+        pieces.push(message);
+    if (codeText)
+        pieces.push(`code=${codeText}`);
+    if (pieces.length > 0)
+        return pieces.join(" ");
+    return safeStringify(err);
+}
+export async function webAuthExists() {
+    const sessionLogger = getChildLogger({ module: "web-session" });
+    maybeRestoreCredsFromBackup(sessionLogger);
+    const authDir = resolveWebAuthDir();
+    const credsPath = resolveWebCredsPath();
+    try {
+        await fs.access(authDir);
+    }
+    catch {
+        return false;
+    }
+    try {
+        const stats = await fs.stat(credsPath);
+        if (!stats.isFile() || stats.size <= 1)
+            return false;
+        const raw = await fs.readFile(credsPath, "utf-8");
+        JSON.parse(raw);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function logoutWeb(runtime = defaultRuntime) {
+    const exists = await webAuthExists();
+    if (!exists) {
+        runtime.log(info("No WhatsApp Web session found; nothing to delete."));
+        return false;
+    }
+    await fs.rm(resolveWebAuthDir(), { recursive: true, force: true });
+    // Also drop session store to clear lingering per-sender state after logout.
+    await fs.rm(resolveDefaultSessionStorePath(), { force: true });
+    runtime.log(success("Cleared WhatsApp Web credentials."));
+    return true;
+}
+export function readWebSelfId() {
+    // Read the cached WhatsApp Web identity (jid + E.164) from disk if present.
+    try {
+        const credsPath = resolveWebCredsPath();
+        if (!fsSync.existsSync(credsPath)) {
+            return { e164: null, jid: null };
+        }
+        const raw = fsSync.readFileSync(credsPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        const jid = parsed?.me?.id ?? null;
+        const e164 = jid ? jidToE164(jid) : null;
+        return { e164, jid };
+    }
+    catch {
+        return { e164: null, jid: null };
+    }
+}
+/**
+ * Return the age (in milliseconds) of the cached WhatsApp web auth state, or null when missing.
+ * Helpful for heartbeats/observability to spot stale credentials.
+ */
+export function getWebAuthAgeMs() {
+    try {
+        const stats = fsSync.statSync(resolveWebCredsPath());
+        return Date.now() - stats.mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
+export function newConnectionId() {
+    return randomUUID();
+}
+export function logWebSelfId(runtime = defaultRuntime, includeProviderPrefix = false) {
+    // Human-friendly log of the currently linked personal web session.
+    const { e164, jid } = readWebSelfId();
+    const details = e164 || jid
+        ? `${e164 ?? "unknown"}${jid ? ` (jid ${jid})` : ""}`
+        : "unknown";
+    const prefix = includeProviderPrefix ? "Web Provider: " : "";
+    runtime.log(info(`${prefix}${details}`));
+}
+export async function pickProvider(pref) {
+    const choice = pref === "auto" ? "web" : pref;
+    const hasWeb = await webAuthExists();
+    if (!hasWeb) {
+        throw new Error("No WhatsApp Web session found. Run `clawdbot login --verbose` to link.");
+    }
+    return choice;
+}

package/docs/AGENTS.default.md

@@ -0,0 +1,116 @@
+---
+summary: "Default Clawdbot agent instructions and skills roster for the personal assistant setup"
+read_when:
+  - Starting a new Clawdbot agent session
+  - Enabling or auditing default skills
+---
+# AGENTS.md — Clawdbot Personal Assistant (default)
+
+## First run (recommended)
+
+Clawdbot uses a dedicated workspace directory for the agent. Default: `~/.clawdbot/workspace`.
+
+1) Create the workspace (if it doesn’t already exist):
+
+```bash
+mkdir -p ~/.clawdbot/workspace
+```
+
+2) Copy the default workspace templates into the workspace:
+
+```bash
+cp docs/templates/AGENTS.md ~/.clawdbot/workspace/AGENTS.md
+cp docs/templates/SOUL.md ~/.clawdbot/workspace/SOUL.md
+cp docs/templates/TOOLS.md ~/.clawdbot/workspace/TOOLS.md
+```
+
+3) Optional: if you want the personal assistant skill roster, replace AGENTS.md with this file:
+
+```bash
+cp docs/AGENTS.default.md ~/.clawdbot/workspace/AGENTS.md
+```
+
+4) Optional: choose a different workspace by setting `agent.workspace` (supports `~`):
+
+```json5
+{
+  agent: {
+    workspace: "~/clawd"
+  }
+}
+```
+
+## Safety defaults
+- Don’t dump directories or secrets into chat.
+- Don’t run destructive commands unless explicitly asked.
+- Don’t send partial/streaming replies to external messaging surfaces (only final replies).
+
+## Session start (required)
+- Read `SOUL.md`, `USER.md`, `memory.md`, and today+yesterday in `memory/`.
+- Do it before responding.
+
+## Soul (required)
+- `SOUL.md` defines identity, tone, and boundaries. Keep it current.
+- If you change `SOUL.md`, tell the user.
+- You are a fresh instance each session; continuity lives in these files.
+
+## Shared spaces (recommended)
+- You’re not the user’s voice; be careful in group chats or public channels.
+- Don’t share private data, contact info, or internal notes.
+
+## Memory system (recommended)
+- Daily log: `memory/YYYY-MM-DD.md` (create `memory/` if needed).
+- Long-term memory: `memory.md` for durable facts, preferences, and decisions.
+- On session start, read today + yesterday + `memory.md` if present.
+- Capture: decisions, preferences, constraints, open loops.
+- Avoid secrets unless explicitly requested.
+
+## Tools & skills
+- Tools live in skills; follow each skill’s `SKILL.md` when you need it.
+- Keep environment-specific notes in `TOOLS.md` (Notes for Skills).
+
+## Backup tip (recommended)
+If you treat this workspace as Clawd’s “memory”, make it a git repo (ideally private) so `AGENTS.md` and your memory files are backed up.
+
+```bash
+cd ~/.clawdbot/workspace
+git init
+git add AGENTS.md
+git commit -m "Add Clawd workspace"
+# Optional: add a private remote + push
+```
+
+## What Clawdbot Does
+- Runs WhatsApp gateway + Pi coding agent so the assistant can read/write chats, fetch context, and run skills via the host Mac.
+- macOS app manages permissions (screen recording, notifications, microphone) and exposes the `clawdbot` CLI via its bundled binary.
+- Direct chats collapse into the shared `main` session by default; groups stay isolated as `surface:group:<id>` (rooms: `surface:channel:<id>`); heartbeats keep background tasks alive.
+
+## Core Skills (enable in Settings → Skills)
+- **mcporter** — Tool server runtime/CLI for managing external skill backends.
+- **Peekaboo** — Fast macOS screenshots with optional AI vision analysis.
+- **camsnap** — Capture frames, clips, or motion alerts from RTSP/ONVIF security cams.
+- **oracle** — OpenAI-ready agent CLI with session replay and browser control.
+- **qmd** — Hybrid markdown search (BM25 + vectors + rerank) with a local server for agents.
+- **eightctl** — Control your sleep, from the terminal.
+- **imsg** — Send, read, stream iMessage & SMS.
+- **wacli** — WhatsApp CLI: sync, search, send.
+- **discord** — Discord actions: react, stickers, polls.
+- **gog** — Google Suite CLI: Gmail, Calendar, Drive, Contacts.
+- **spotify-player** — Terminal Spotify client to search/queue/control playback.
+- **sag** — ElevenLabs speech with mac-style say UX; streams to speakers by default.
+- **Sonos CLI** — Control Sonos speakers (discover/status/playback/volume/grouping) from scripts.
+- **blucli** — Play, group, and automate BluOS players from scripts.
+- **OpenHue CLI** — Philips Hue lighting control for scenes and automations.
+- **OpenAI Whisper** — Local speech-to-text for quick dictation and voicemail transcripts.
+- **Gemini CLI** — Google Gemini models from the terminal for fast Q&A.
+- **bird** — X/Twitter CLI to tweet, reply, read threads, and search without a browser.
+- **agent-tools** — Utility toolkit for automations and helper scripts.
+
+## Usage Notes
+- Prefer the `clawdbot` CLI for scripting; mac app handles permissions.
+- Run installs from the Skills tab; it hides the button if a binary is already present.
+- Keep heartbeats enabled so the assistant can schedule reminders, monitor inboxes, and trigger camera captures.
+- Canvas UI runs full-screen with native overlays. Avoid placing critical controls in the top-left/top-right/bottom edges; add explicit gutters in the layout and don’t rely on safe-area insets.
+- For browser-driven verification, use `clawdbot browser` (tabs/status/screenshot) with the clawd-managed Chrome profile.
+- For DOM inspection, use `clawdbot browser eval|query|dom|snapshot` (and `--json`/`--out` when you need machine output).
+- For interactions, use `clawdbot browser click|type|hover|drag|select|upload|press|wait|navigate|back|evaluate|run` (click/type require snapshot refs; use `evaluate` for CSS selectors).

package/docs/CNAME

@@ -0,0 +1 @@
+clawdbot.com

package/docs/RELEASING.md

@@ -0,0 +1,64 @@
+---
+summary: "Step-by-step release checklist for npm + macOS app"
+read_when:
+  - Cutting a new npm release
+  - Cutting a new macOS app release
+  - Verifying metadata before publishing
+---
+
+# Release Checklist (npm + macOS)
+
+Use `pnpm` (Node 22+) from the repo root. Keep the working tree clean before tagging/publishing.
+
+1) **Version & metadata**
+- [ ] Bump `package.json` version (e.g., `1.1.0`).
+- [ ] Update CLI/version strings: `src/cli/program.ts` and the Baileys user agent in `src/provider-web.ts`.
+- [ ] Confirm package metadata (name, description, repository, keywords, license) and `bin` map points to `dist/index.js` for `clawdbot`.
+- [ ] If dependencies changed, run `pnpm install` so `pnpm-lock.yaml` is current.
+
+2) **Build & artifacts**
+- [ ] If A2UI inputs changed, run `pnpm canvas:a2ui:bundle` and commit any updated `src/canvas-host/a2ui/a2ui.bundle.js`.
+- [ ] `pnpm run build` (regenerates `dist/`).
+- [ ] Optional: `npm pack --pack-destination /tmp` after the build; inspect the tarball contents and keep it handy for the GitHub release (do **not** commit it).
+
+3) **Changelog & docs**
+- [ ] Update `CHANGELOG.md` with user-facing highlights (create the file if missing); keep entries strictly descending by version.
+- [ ] Ensure README examples/flags match current CLI behavior (notably new commands or options).
+
+4) **Validation**
+- [ ] `pnpm lint`
+- [ ] `pnpm test` (or `pnpm test:coverage` if you need coverage output)
+- [ ] `pnpm run build` (last sanity check after tests)
+- [ ] `pnpm release:check` (verifies npm pack contents)
+- [ ] (Optional) Spot-check the web gateway if your changes affect send/receive paths.
+
+5) **macOS app (Sparkle)**
+- [ ] Build + sign the macOS app, then zip it for distribution.
+- [ ] Generate the Sparkle appcast (HTML notes via `scripts/make_appcast.sh`) and update `appcast.xml`.
+- [ ] Keep the app zip (and optional dSYM zip) ready to attach to the GitHub release.
+- [ ] Follow `docs/mac/release.md` for the exact commands and required env vars.
+  - `APP_BUILD` must be numeric + monotonic (no `-beta`) so Sparkle compares versions correctly.
+  - If notarizing, use the `clawdbot-notary` keychain profile created from App Store Connect API env vars (see `docs/mac/release.md`).
+
+6) **Publish (npm)**
+- [ ] Confirm git status is clean; commit and push as needed.
+- [ ] `npm login` (verify 2FA) if needed.
+- [ ] `npm publish --access public` (use `--tag beta` for pre-releases).
+- [ ] Verify the registry: `npm view clawdbot version` and `npx -y clawdbot@X.Y.Z --version` (or `--help`).
+
+### Troubleshooting (notes from 2.0.0-beta2 release)
+- **npm pack/publish hangs or produces huge tarball**: the macOS app bundle in `dist/Clawdbot.app` (and release zips) get swept into the package. Fix by whitelisting publish contents via `package.json` `files` (include dist subdirs, docs, skills; exclude app bundles). Confirm with `npm pack --dry-run` that `dist/Clawdbot.app` is not listed.
+- **npm auth web loop for dist-tags**: use legacy auth to get an OTP prompt:
+  - `NPM_CONFIG_AUTH_TYPE=legacy npm dist-tag add clawdbot@X.Y.Z latest`
+- **`npx` verification fails with `ECOMPROMISED: Lock compromised`**: retry with a fresh cache:
+  - `NPM_CONFIG_CACHE=/tmp/npm-cache-$(date +%s) npx -y clawdbot@X.Y.Z --version`
+- **Tag needs repointing after a late fix**: force-update and push the tag, then ensure the GitHub release assets still match:
+  - `git tag -f vX.Y.Z && git push -f origin vX.Y.Z`
+
+7) **GitHub release + appcast**
+- [ ] Tag and push: `git tag vX.Y.Z && git push origin vX.Y.Z` (or `git push --tags`).
+- [ ] Create/refresh the GitHub release for `vX.Y.Z` with **title `clawdbot X.Y.Z`** (not just the tag); body should inline the product-facing bullets from the changelog (no bare links) **and must not repeat the title inside the body**.
+- [ ] Attach artifacts: `npm pack` tarball (optional), `Clawdbot-X.Y.Z.zip`, and `Clawdbot-X.Y.Z.dSYM.zip` (if generated).
+- [ ] Commit the updated `appcast.xml` and push it (Sparkle feeds from main).
+- [ ] From a clean temp directory (no `package.json`), run `npx -y clawdbot@X.Y.Z send --help` to confirm install/CLI entrypoints work.
+- [ ] Announce/share release notes.

package/docs/_config.yml

@@ -0,0 +1,51 @@
+title: "CLAWDBOT Docs"
+description: "A TypeScript/Node gateway + macOS/iOS companions for WhatsApp (web) and Telegram (bot)."
+markdown: kramdown
+highlighter: rouge
+
+# Keep GitHub Pages' default page URLs (e.g. /gateway.html). Many docs links
+# are written as relative *.md links and are rewritten during the build.
+
+plugins:
+  - jekyll-relative-links
+
+relative_links:
+  enabled: true
+  collections: true
+
+defaults:
+  - scope:
+      path: ""
+    values:
+      layout: default
+
+nav:
+  - title: "Home"
+    url: "/"
+  - title: "Clawd Setup"
+    url: "/clawd.html"
+  - title: "Gateway"
+    url: "/gateway.html"
+  - title: "Remote"
+    url: "/remote.html"
+  - title: "Discovery"
+    url: "/discovery.html"
+  - title: "Configuration"
+    url: "/configuration.html"
+  - title: "WebChat"
+    url: "/webchat.html"
+  - title: "macOS App"
+    url: "/clawdbot-mac.html"
+  - title: "iOS Node"
+    url: "/ios/connect.html"
+  - title: "Telegram"
+    url: "/telegram.html"
+  - title: "Security"
+    url: "/security.html"
+  - title: "Troubleshooting"
+    url: "/troubleshooting.html"
+
+kramdown:
+  input: GFM
+  hard_wrap: false
+  syntax_highlighter: rouge