talon-agent 4.0.0 → 4.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "Dylan Neve",
   "license": "MIT",

package/src/core/engine/gateway-actions/cross-send.ts

@@ -2,22 +2,27 @@
  * Cross-frontend send — the server side of the `send_via` tool.
  *
  * A chat-free shared action: any session (an active Telegram chat, the
- * heartbeat, a dream run) delivers a plain text message through ANY
- * enabled messaging frontend by naming it explicitly. Explicit is the
- * point — the gateway's normal chat_id routing infers the owning
- * frontend from the numeric id's shape, and WhatsApp's hash-derived ids
- * also match the Telegram matcher, so a cross-frontend send routed that
- * way lands on the wrong platform once the originating turn's context
- * is cleared.
+ * heartbeat, a dream run) delivers a message through ANY enabled
+ * messaging frontend by naming it explicitly. Explicit is the point —
+ * the gateway's normal chat_id routing infers the owning frontend from
+ * the numeric id's shape, and WhatsApp's hash-derived ids also match the
+ * Telegram matcher, so a cross-frontend send routed that way lands on
+ * the wrong platform once the originating turn's context is cleared.
+ *
+ * Text is the common case; a media source (file_path / url / file_id)
+ * promotes the send to the matching per-kind action (send_photo,
+ * send_file, …), which every messaging frontend already implements and
+ * already resolves `body.target` for. Without this, reaching another
+ * platform meant text only — you could describe a photo to someone on
+ * WhatsApp but not send them one.
  *
  * Core never imports src/frontend (dependency-cruiser enforces it), so
  * dispatch goes through a broker: `Gateway.registerFrontendHandler`
  * mirrors each frontend's action handler here, and the action calls the
- * target's own `send_message` — the one send action every messaging
- * frontend implements. A numeric target doubles as the handler's chatId
- * key, so id-addressed frontends (telegram, discord, teams, native)
- * need no changes; non-numeric forms (WhatsApp phone numbers, wa_* ids)
- * ride in `body.target` for the frontend's adapter to resolve.
+ * target's own send action. A numeric target doubles as the handler's
+ * chatId key, so id-addressed frontends (telegram, discord, teams,
+ * native) need no changes; non-numeric forms (WhatsApp phone numbers,
+ * wa_* ids) ride in `body.target` for the frontend's adapter to resolve.
  */
 
 import type { FrontendActionHandler } from "../../types.js";
@@ -38,6 +43,77 @@ export function registerCrossSendTarget(
   else targets.set(name, handler);
 }
 
+/**
+ * Media kinds send_via can carry. Each maps to `send_<kind>`, the action
+ * name every frontend's media handler already registers.
+ */
+const MEDIA_KINDS = [
+  "photo",
+  "video",
+  "animation",
+  "voice",
+  "audio",
+  "sticker",
+  "video_note",
+  "file",
+] as const;
+
+const MEDIA_KIND_SET: ReadonlySet<string> = new Set(MEDIA_KINDS);
+
+/**
+ * Extension → kind, so the common cases need no media_type. Anything
+ * unrecognised travels as a document, which is the one kind that
+ * accepts arbitrary bytes on every platform.
+ */
+const KIND_BY_EXT: Record<string, string> = {
+  ".jpg": "photo",
+  ".jpeg": "photo",
+  ".png": "photo",
+  ".webp": "photo",
+  ".heic": "photo",
+  ".gif": "animation",
+  ".mp4": "video",
+  ".mov": "video",
+  ".mkv": "video",
+  ".webm": "video",
+  ".mp3": "audio",
+  ".m4a": "audio",
+  ".flac": "audio",
+  ".wav": "audio",
+  ".ogg": "voice",
+  ".opus": "voice",
+};
+
+/** Lowercased extension of a path or URL, "" when there isn't one. */
+function extensionOf(source: string): string {
+  let path = source;
+  try {
+    // Strip query/fragment so "a.png?v=2" still reads as .png.
+    path = new URL(source).pathname;
+  } catch {
+    // Not a URL — a filesystem path, used as-is.
+  }
+  const dot = path.lastIndexOf(".");
+  const slash = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
+  return dot > slash ? path.slice(dot).toLowerCase() : "";
+}
+
+/**
+ * Look up a registered frontend handler by name. Exported for the other
+ * cross-frontend actions (account management), which need the same
+ * broker and the same "is it enabled?" answer.
+ */
+export function crossSendTarget(
+  name: string,
+): FrontendActionHandler | undefined {
+  return targets.get(name);
+}
+
+/** Enabled frontend names, for a "not enabled (enabled: …)" error. */
+export function crossSendTargetNames(): string[] {
+  return [...targets.keys()].sort();
+}
+
 export const crossSendHandlers: SharedActionHandlers = {
   send_via: async (body) => {
     const frontend = String(body.frontend ?? "")
@@ -45,35 +121,71 @@ export const crossSendHandlers: SharedActionHandlers = {
       .toLowerCase();
     const target = String(body.target ?? "").trim();
     const text = String(body.text ?? "");
+    const filePath = body.file_path ? String(body.file_path) : "";
+    const url = body.url ? String(body.url) : "";
+    const fileId = body.file_id ? String(body.file_id) : "";
+    const hasMedia = Boolean(filePath || url || fileId);
     if (!frontend) {
       return { ok: false, error: "send_via: frontend is required" };
     }
     if (!target) {
       return { ok: false, error: "send_via: target is required" };
     }
-    if (!text.trim()) {
-      return { ok: false, error: "send_via: text is required" };
+    if (!hasMedia && !text.trim()) {
+      return {
+        ok: false,
+        error:
+          "send_via: text is required (or a media source: file_path, url, " +
+          "or file_id)",
+      };
     }
-    const handler = targets.get(frontend);
+    const handler = crossSendTarget(frontend);
     if (!handler) {
-      const enabled = [...targets.keys()].sort().join(", ") || "none";
+      const enabled = crossSendTargetNames().join(", ") || "none";
       return {
         ok: false,
         error: `send_via: the ${frontend} frontend is not enabled (enabled: ${enabled})`,
       };
     }
+
+    // Text-only keeps the exact shape it always had; a media source
+    // promotes the send to the per-kind action, with text as the caption.
+    let payload: Record<string, unknown>;
+    let action: string;
+    if (hasMedia) {
+      const explicit = String(body.media_type ?? "")
+        .trim()
+        .toLowerCase();
+      const kind =
+        explicit || KIND_BY_EXT[extensionOf(filePath || url)] || "file";
+      if (!MEDIA_KIND_SET.has(kind)) {
+        return {
+          ok: false,
+          error:
+            `send_via: unknown media_type "${kind}" — use one of ` +
+            `${MEDIA_KINDS.join(", ")}`,
+        };
+      }
+      action = `send_${kind}`;
+      payload = { action, target };
+      if (filePath) payload.file_path = filePath;
+      if (url) payload.url = url;
+      if (fileId) payload.file_id = fileId;
+      if (text.trim()) payload.caption = text;
+    } else {
+      action = "send_message";
+      payload = { action, text, target };
+    }
+
     // A numeric target is the handler's chatId key; other forms travel in
     // body.target for the frontend's adapter to resolve. 0 is the same
     // "no chat" sentinel the chat-free dispatch itself uses.
     const numericTarget = /^-?\d+$/.test(target) ? Number(target) : 0;
-    const result = await handler(
-      { action: "send_message", text, target },
-      numericTarget,
-    );
+    const result = await handler(payload, numericTarget);
     if (!result) {
       return {
         ok: false,
-        error: `send_via: the ${frontend} frontend does not implement send_message`,
+        error: `send_via: the ${frontend} frontend does not implement ${action}`,
       };
     }
     return result;

package/src/core/engine/gateway-actions/index.ts

@@ -37,6 +37,10 @@ import {
   chatFreeActions as meshChatFreeActions,
 } from "./mesh.js";
 import { crossSendHandlers, crossSendChatFreeActions } from "./cross-send.js";
+import {
+  whatsappAccountHandlers,
+  whatsappAccountChatFreeActions,
+} from "./whatsapp-account.js";
 import { nativeHandlers } from "./native.js";
 
 // Null-prototype so a request `action` of "toString" / "constructor" / etc.
@@ -54,6 +58,7 @@ const handlers: SharedActionHandlers = Object.assign(Object.create(null), {
   ...modelHandlers,
   ...meshHandlers,
   ...crossSendHandlers,
+  ...whatsappAccountHandlers,
   ...nativeHandlers,
 });
 
@@ -64,6 +69,7 @@ const handlers: SharedActionHandlers = Object.assign(Object.create(null), {
 const chatFreeActions: ReadonlySet<string> = new Set([
   ...meshChatFreeActions,
   ...crossSendChatFreeActions,
+  ...whatsappAccountChatFreeActions,
 ]);
 
 export async function handleSharedAction(

package/src/core/engine/gateway-actions/whatsapp-account.ts

@@ -0,0 +1,54 @@
+/**
+ * WhatsApp account management — the server side of the
+ * `whatsapp_account` tool.
+ *
+ * A chat-free shared action, for the same reason `send_via` is one: the
+ * account surface belongs to the WhatsApp *connection*, not to any
+ * conversation, and the session driving it usually lives somewhere else
+ * (Dylan's Telegram DM, or a heartbeat run with no ambient chat at
+ * all). Routing it through the normal chat_id path would demand a
+ * WhatsApp chat that need not exist.
+ *
+ * Dispatch reuses the cross-send broker — core never imports
+ * src/frontend, so the WhatsApp handler arrives by registration — and
+ * deliberately sends no `target`, because the frontend's dispatcher
+ * treats `body.target` as a chat-routing key and these ops address the
+ * logged-in identity instead.
+ */
+
+import type { SharedActionHandlers } from "./types.js";
+import { crossSendTarget, crossSendTargetNames } from "./cross-send.js";
+
+export const whatsappAccountHandlers: SharedActionHandlers = {
+  whatsapp_account: async (body) => {
+    const op = String(body.op ?? "").trim();
+    if (!op) {
+      return { ok: false, error: "whatsapp_account: op is required" };
+    }
+    const handler = crossSendTarget("whatsapp");
+    if (!handler) {
+      const enabled = crossSendTargetNames().join(", ") || "none";
+      return {
+        ok: false,
+        error: `whatsapp_account: the whatsapp frontend is not enabled (enabled: ${enabled})`,
+      };
+    }
+    // 0 is the chat-free dispatch's own "no chat" sentinel; the frontend
+    // lists whatsapp_account as chatless, so it never resolves one.
+    const result = await handler({ ...body, action: "whatsapp_account" }, 0);
+    if (!result) {
+      return {
+        ok: false,
+        error:
+          "whatsapp_account: the whatsapp frontend does not implement " +
+          "whatsapp_account (is it running an older build?)",
+      };
+    }
+    return result;
+  },
+};
+
+/** Chat-free by design — see the module note. */
+export const whatsappAccountChatFreeActions: ReadonlySet<string> = new Set([
+  "whatsapp_account",
+]);

package/src/core/tools/cross-send.ts

@@ -14,14 +14,17 @@ import type { ToolDefinition } from "./types.js";
 export const crossSendTools: ToolDefinition[] = [
   {
     name: "send_via",
-    description: `Send a plain text message through ANY enabled messaging frontend — including one this chat does not live on. Use it to reach someone on another platform (e.g. from Telegram or a heartbeat run, message a WhatsApp number). For the current chat, keep using the normal delivery tools (end_turn / send / send_message).
+    description: `Send a message — text, or a photo/video/file/voice note — through ANY enabled messaging frontend, including one this chat does not live on. Use it to reach someone on another platform (e.g. from Telegram or a heartbeat run, message a WhatsApp number). For the current chat, keep using the normal delivery tools (end_turn / send / send_message).
 
 Target forms:
 - whatsapp: a phone number with country code ("+353871234567" or "353871234567"), a wa_dm_<number>/wa_group_<id> chat id, or a raw JID; a bare numeric chat id works only for chats already seen since startup
 - telegram / discord / teams / native: the numeric chat id, as a string (Telegram supergroups/channels are negative, DMs positive)
 
+Media: give file_path (a workspace file) or url (a public URL, fetched by the platform); text becomes the caption. The kind is inferred from the extension — pass media_type to override (e.g. send a .webp as a sticker rather than a photo). file_id is Telegram-only; other platforms have no equivalent and will say so.
+
 Examples:
   send_via(frontend="whatsapp", target="+353871234567", text="On my way")
+  send_via(frontend="whatsapp", target="+353871234567", file_path="media/plot.png", text="here's the chart")
   send_via(frontend="telegram", target="-1001426819337", text="Build is green")
 
 Fails with a clear error when the named frontend is not enabled or not connected.`,
@@ -36,8 +39,40 @@ Fails with a clear error when the named frontend is not enabled or not connected
         ),
       text: z
         .string()
+        .optional()
+        .describe(
+          "Message text, or the caption when media is attached. Markdown supported where the platform supports it. Required unless a media source is given.",
+        ),
+      file_path: z
+        .string()
+        .optional()
+        .describe("Workspace file to send as media."),
+      url: z
+        .string()
+        .optional()
+        .describe(
+          "Public URL of media to send — fetched by the target platform.",
+        ),
+      file_id: z
+        .string()
+        .optional()
+        .describe(
+          "Platform file_id for media already seen in chat (Telegram only).",
+        ),
+      media_type: z
+        .enum([
+          "photo",
+          "video",
+          "animation",
+          "voice",
+          "audio",
+          "sticker",
+          "video_note",
+          "file",
+        ])
+        .optional()
         .describe(
-          "Message text. Markdown supported where the platform supports it.",
+          "Override the media kind. Default: inferred from the file extension, falling back to a document.",
         ),
     },
     execute: (params, bridge) => bridge("send_via", params),

package/src/core/tools/index.ts

@@ -23,6 +23,7 @@ import { adminTools } from "./admin.js";
 import { modelTools } from "./models.js";
 import { meshTools } from "./mesh.js";
 import { crossSendTools } from "./cross-send.js";
+import { whatsappTools } from "./whatsapp.js";
 import { moderationTools } from "./moderation.js";
 import { nativeTools } from "./native.js";
 
@@ -44,6 +45,7 @@ export const ALL_TOOLS: readonly ToolDefinition[] = [
   ...modelTools,
   ...meshTools,
   ...crossSendTools,
+  ...whatsappTools,
   ...moderationTools,
 ];
 

package/src/core/tools/whatsapp.ts

@@ -0,0 +1,109 @@
+import { z } from "zod";
+import type { ToolDefinition } from "./types.js";
+
+/**
+ * WhatsApp account management. Deliberately NOT frontend-restricted
+ * (the same reasoning as crossSendTools): the account being managed and
+ * the session managing it are usually on different frontends — a
+ * Telegram DM setting the WhatsApp profile photo, or a heartbeat run
+ * with no ambient chat. The gateway serves it as a chat-free action
+ * (see engine/gateway-actions/whatsapp-account.ts), so it needs no
+ * resolved WhatsApp conversation to work.
+ */
+export const whatsappTools: ToolDefinition[] = [
+  {
+    name: "whatsapp_account",
+    description: `Read and change the bot's own WhatsApp account — profile, privacy, blocklist, presence. Works from any frontend (it addresses the WhatsApp connection, not a chat), and fails with a clear error when the WhatsApp frontend is not enabled.
+
+Profile:
+  whatsapp_account(op="get_profile") — number, display name, about text, profile photo URL
+  whatsapp_account(op="set_name", name="Claudius")
+  whatsapp_account(op="set_about", text="Running on Talon") — empty text clears it
+  whatsapp_account(op="set_photo", file_path="media/avatar.jpg") — or url=...; square images work best
+  whatsapp_account(op="remove_photo")
+
+Other people:
+  whatsapp_account(op="get_user_profile", contact="+353871234567") — their about + photo, as your account can see them
+
+Privacy (op="get_privacy" lists the current values):
+  whatsapp_account(op="set_privacy", setting="last_seen", value="contacts")
+  settings: last_seen, online, profile_photo, about, groups_add (all | contacts | contact_blacklist | none¹),
+            read_receipts (all | none), calls (all | known), messages (all | contacts),
+            online also accepts match_last_seen
+  ¹ groups_add has no "none"; online takes only all/match_last_seen.
+  whatsapp_account(op="set_disappearing", duration="7d") — default timer for NEW chats: off, 24h, 7d, 90d, or seconds
+
+Blocking and presence:
+  whatsapp_account(op="get_blocklist")
+  whatsapp_account(op="block", contact="+353871234567") / op="unblock"
+  whatsapp_account(op="set_presence", presence="available") — or "unavailable" to appear offline
+
+Changes here are real and immediately visible to that account's contacts.`,
+    schema: {
+      op: z
+        .enum([
+          "get_profile",
+          "get_user_profile",
+          "set_name",
+          "set_about",
+          "set_photo",
+          "remove_photo",
+          "get_privacy",
+          "set_privacy",
+          "set_disappearing",
+          "get_blocklist",
+          "block",
+          "unblock",
+          "set_presence",
+        ])
+        .describe("The account operation to perform."),
+      name: z.string().optional().describe("New display name (set_name)."),
+      text: z
+        .string()
+        .optional()
+        .describe("New about/status text (set_about); empty clears it."),
+      file_path: z
+        .string()
+        .optional()
+        .describe("Workspace image for set_photo."),
+      url: z.string().optional().describe("Public image URL for set_photo."),
+      contact: z
+        .string()
+        .optional()
+        .describe(
+          "Who to act on for get_user_profile / block / unblock: a phone number with country code, or a JID. Not an internal id — deliberately not named user_id.",
+        ),
+      setting: z
+        .enum([
+          "last_seen",
+          "online",
+          "profile_photo",
+          "about",
+          "read_receipts",
+          "groups_add",
+          "calls",
+          "messages",
+        ])
+        .optional()
+        .describe("Which privacy knob to change (set_privacy)."),
+      value: z
+        .string()
+        .optional()
+        .describe(
+          "New privacy value (set_privacy) — the accepted set depends on the setting.",
+        ),
+      duration: z
+        .string()
+        .optional()
+        .describe(
+          "Default disappearing timer for new chats (set_disappearing): off, 24h, 7d, 90d, or seconds.",
+        ),
+      presence: z
+        .enum(["available", "unavailable"])
+        .optional()
+        .describe("Presence to broadcast (set_presence)."),
+    },
+    execute: (params, bridge) => bridge("whatsapp_account", params),
+    tag: "admin",
+  },
+];

package/src/frontend/whatsapp/actions/account.ts

@@ -0,0 +1,282 @@
+/**
+ * Account actions — the bot's own WhatsApp identity and settings.
+ *
+ * Everything here addresses the logged-in account rather than a chat:
+ * display name, about text, profile photo, privacy knobs, the
+ * blocklist, and presence. That makes these the only WhatsApp actions
+ * with no chat to resolve, so the dispatcher treats them as chatless —
+ * which is also what lets them be driven from another frontend (a
+ * Telegram session managing the WhatsApp account) with no ambient
+ * WhatsApp chat in play.
+ *
+ * One `whatsapp_account` action with an `op` switch, mirroring
+ * `moderate`: the surface is wide but every op is small, and a single
+ * tool keeps the model from having to learn a dozen names.
+ */
+
+import { jidNormalizedUser, type WASocket } from "baileys";
+import type { ActionResult } from "../../../core/types.js";
+import {
+  readStatusText,
+  resolveMediaUpload,
+  toUserJid,
+  tryAction,
+} from "./shared.js";
+import type { WhatsAppActionContext, WhatsAppActionHandlers } from "./types.js";
+
+/** The account's own JID, device suffix stripped. */
+function ownJid(sock: WASocket): string {
+  const raw = sock.user?.id;
+  if (!raw) throw new Error("not logged in — no account JID yet");
+  return jidNormalizedUser(raw);
+}
+
+/**
+ * The privacy knobs WhatsApp exposes, each with its accepted values and
+ * the setter it maps to. Table-driven so `set_privacy` stays one lookup
+ * and an unknown setting can name every valid one back.
+ */
+const PRIVACY: Record<
+  string,
+  {
+    values: readonly string[];
+    apply: (sock: WASocket, v: string) => Promise<void>;
+  }
+> = {
+  last_seen: {
+    values: ["all", "contacts", "contact_blacklist", "none"],
+    apply: (s, v) => s.updateLastSeenPrivacy(v as "all"),
+  },
+  online: {
+    values: ["all", "match_last_seen"],
+    apply: (s, v) => s.updateOnlinePrivacy(v as "all"),
+  },
+  profile_photo: {
+    values: ["all", "contacts", "contact_blacklist", "none"],
+    apply: (s, v) => s.updateProfilePicturePrivacy(v as "all"),
+  },
+  about: {
+    values: ["all", "contacts", "contact_blacklist", "none"],
+    apply: (s, v) => s.updateStatusPrivacy(v as "all"),
+  },
+  read_receipts: {
+    values: ["all", "none"],
+    apply: (s, v) => s.updateReadReceiptsPrivacy(v as "all"),
+  },
+  groups_add: {
+    values: ["all", "contacts", "contact_blacklist"],
+    apply: (s, v) => s.updateGroupsAddPrivacy(v as "all"),
+  },
+  calls: {
+    values: ["all", "known"],
+    apply: (s, v) => s.updateCallPrivacy(v as "all"),
+  },
+  messages: {
+    values: ["all", "contacts"],
+    apply: (s, v) => s.updateMessagesPrivacy(v as "all"),
+  },
+};
+
+/** Named durations for the default disappearing-message timer. */
+const DISAPPEARING: Record<string, number> = {
+  off: 0,
+  "24h": 86400,
+  "7d": 604800,
+  "90d": 7776000,
+};
+
+type Op = (
+  body: Record<string, unknown>,
+  ctx: WhatsAppActionContext,
+) => Promise<ActionResult>;
+
+/** Whole own-profile read: who this account is, as WhatsApp sees it. */
+const getProfile: Op = async (_body, ctx) => {
+  const jid = ownJid(ctx.sock);
+  const lines = [
+    `jid: ${jid}`,
+    `number: +${jid.split("@")[0]}`,
+    `name: ${ctx.sock.user?.name ?? "(unset)"}`,
+  ];
+  // Both reads are best-effort: a fresh account has neither, and the
+  // account's own privacy settings never hide them from itself.
+  const status = await ctx.sock.fetchStatus(jid).catch(() => undefined);
+  lines.push(`about: ${readStatusText(status) ?? "(unset)"}`);
+  const photo = await ctx.sock
+    .profilePictureUrl(jid, "image")
+    .catch(() => undefined);
+  lines.push(`photo: ${photo ?? "(none)"}`);
+  return { ok: true, text: lines.join("\n") };
+};
+
+/** Another account's public card — what strangers see of them. */
+const getUserProfile: Op = async (body, ctx) => {
+  const jid = toUserJid(body.contact ?? body.user_id);
+  if (!jid) {
+    return { ok: false, error: "get_user_profile: contact is required" };
+  }
+  const status = await ctx.sock.fetchStatus(jid).catch(() => undefined);
+  const photo = await ctx.sock
+    .profilePictureUrl(jid, "image")
+    .catch(() => undefined);
+  return {
+    ok: true,
+    text: [
+      `jid: ${jid}`,
+      `about: ${readStatusText(status) ?? "(hidden or unset)"}`,
+      `photo: ${photo ?? "(hidden or none)"}`,
+    ].join("\n"),
+  };
+};
+
+const setName: Op = async (body, ctx) => {
+  const name = String(body.name ?? "").trim();
+  if (!name) return { ok: false, error: "set_name: name is required" };
+  await ctx.sock.updateProfileName(name);
+  return { ok: true, text: `Display name set to "${name}".` };
+};
+
+const setAbout: Op = async (body, ctx) => {
+  // An empty string is a legitimate value here — it clears the about.
+  const text = String(body.text ?? body.about ?? "");
+  await ctx.sock.updateProfileStatus(text);
+  return {
+    ok: true,
+    text: text ? `About set to "${text}".` : "About cleared.",
+  };
+};
+
+const setPhoto: Op = async (body, ctx) => {
+  const resolved = resolveMediaUpload(body, "set_photo");
+  if ("error" in resolved) return { ok: false, error: resolved.error };
+  await ctx.sock.updateProfilePicture(ownJid(ctx.sock), resolved.media);
+  return { ok: true, text: "Profile photo updated." };
+};
+
+const removePhoto: Op = async (_body, ctx) => {
+  await ctx.sock.removeProfilePicture(ownJid(ctx.sock));
+  return { ok: true, text: "Profile photo removed." };
+};
+
+const getPrivacy: Op = async (_body, ctx) => {
+  const settings = await ctx.sock.fetchPrivacySettings(true);
+  const rows = Object.entries(settings).map(([k, v]) => `${k}: ${v}`);
+  return {
+    ok: true,
+    text: rows.length ? rows.join("\n") : "No privacy settings reported.",
+  };
+};
+
+const setPrivacy: Op = async (body, ctx) => {
+  const setting = String(body.setting ?? "")
+    .trim()
+    .toLowerCase();
+  const knob = Object.hasOwn(PRIVACY, setting) ? PRIVACY[setting] : undefined;
+  if (!knob) {
+    return {
+      ok: false,
+      error: `set_privacy: unknown setting "${setting}" — use one of ${Object.keys(PRIVACY).join(", ")}`,
+    };
+  }
+  const value = String(body.value ?? "")
+    .trim()
+    .toLowerCase();
+  if (!knob.values.includes(value)) {
+    return {
+      ok: false,
+      error: `set_privacy: ${setting} accepts ${knob.values.join(", ")} (got "${value}")`,
+    };
+  }
+  await knob.apply(ctx.sock, value);
+  return { ok: true, text: `Privacy ${setting} set to ${value}.` };
+};
+
+const setDisappearing: Op = async (body, ctx) => {
+  const raw = String(body.duration ?? "")
+    .trim()
+    .toLowerCase();
+  const seconds = Object.hasOwn(DISAPPEARING, raw)
+    ? DISAPPEARING[raw]
+    : Number(raw);
+  if (!Number.isFinite(seconds) || seconds < 0) {
+    return {
+      ok: false,
+      error: `set_disappearing: duration must be seconds, or one of ${Object.keys(DISAPPEARING).join(", ")}`,
+    };
+  }
+  await ctx.sock.updateDefaultDisappearingMode(seconds);
+  return {
+    ok: true,
+    text: seconds
+      ? `New chats now disappear after ${seconds}s.`
+      : "Disappearing messages off for new chats.",
+  };
+};
+
+const getBlocklist: Op = async (_body, ctx) => {
+  const blocked = (await ctx.sock.fetchBlocklist()).filter(Boolean);
+  return {
+    ok: true,
+    text: blocked.length ? blocked.join("\n") : "Blocklist is empty.",
+  };
+};
+
+/** block / unblock share everything but the verb. */
+function blockOp(action: "block" | "unblock"): Op {
+  return async (body, ctx) => {
+    const jid = toUserJid(body.contact ?? body.user_id);
+    if (!jid) return { ok: false, error: `${action}: contact is required` };
+    await ctx.sock.updateBlockStatus(jid, action);
+    return { ok: true, text: `${jid} ${action}ed.` };
+  };
+}
+
+const setPresence: Op = async (body, ctx) => {
+  const state = String(body.presence ?? body.state ?? "")
+    .trim()
+    .toLowerCase();
+  if (state !== "available" && state !== "unavailable") {
+    return {
+      ok: false,
+      error: 'set_presence: presence must be "available" or "unavailable"',
+    };
+  }
+  await ctx.sock.sendPresenceUpdate(state);
+  return { ok: true, text: `Presence set to ${state}.` };
+};
+
+const OPS: Record<string, Op> = {
+  get_profile: getProfile,
+  get_user_profile: getUserProfile,
+  set_name: setName,
+  set_about: setAbout,
+  set_photo: setPhoto,
+  remove_photo: removePhoto,
+  get_privacy: getPrivacy,
+  set_privacy: setPrivacy,
+  set_disappearing: setDisappearing,
+  get_blocklist: getBlocklist,
+  block: blockOp("block"),
+  unblock: blockOp("unblock"),
+  set_presence: setPresence,
+};
+
+/** Every op name, for the "unknown op" error to list back. */
+const ACCOUNT_OPS: readonly string[] = Object.keys(OPS);
+
+export const accountHandlers: WhatsAppActionHandlers = {
+  whatsapp_account: (body, _chatId, ctx) =>
+    tryAction("whatsapp_account", async () => {
+      const op = String(body.op ?? "")
+        .trim()
+        .toLowerCase();
+      const run = Object.hasOwn(OPS, op) ? OPS[op] : undefined;
+      if (!run) {
+        return {
+          ok: false,
+          error: `whatsapp_account: unknown op "${op}" — use one of ${ACCOUNT_OPS.join(", ")}`,
+        };
+      }
+      return run(body, ctx);
+    }),
+};

package/src/frontend/whatsapp/actions/chat-info.ts

@@ -7,7 +7,7 @@
  * retrieval (get_message_by_id, download_media) lives in history.ts.
  */
 
-import { toUserJid, tryAction } from "./shared.js";
+import { readStatusText, toUserJid, tryAction } from "./shared.js";
 import type { WhatsAppActionHandlers } from "./types.js";
 
 /** Render one participant the way the other frontends render members. */
@@ -117,14 +117,7 @@ export const chatInfoHandlers: WhatsAppActionHandlers = {
       const status: unknown = await ctx.sock
         .fetchStatus(jid)
         .catch(() => undefined);
-      // fetchStatus has returned both a bare object and a one-element
-      // array across Baileys versions; accept either shape.
-      const entry = (Array.isArray(status) ? status[0] : status) as
-        { status?: string | { status?: string } } | undefined;
-      const statusText =
-        typeof entry?.status === "string"
-          ? entry.status
-          : entry?.status?.status;
+      const statusText = readStatusText(status);
       if (statusText) lines.push(`about: ${statusText}`);
       const picture = await ctx.sock
         .profilePictureUrl(jid, "image")

package/src/frontend/whatsapp/actions/index.ts

@@ -9,6 +9,7 @@
  * WhatsApp-specific implementation.
  *
  * Split by responsibility (mirrors the telegram/discord actions/ layout):
+ *   - account    — the bot's own profile, privacy, blocklist, presence
  *   - shared     — tryAction, media/quote resolution, send helpers
  *   - messaging  — text, replies, reactions, edits, deletes, pins, presence
  *   - media      — images, video, audio, documents, polls, locations, …
@@ -25,6 +26,7 @@ import {
   resolveWhatsAppTarget,
   type WhatsAppChatInfo,
 } from "../registry.js";
+import { accountHandlers } from "./account.js";
 import { chatInfoHandlers } from "./chat-info.js";
 import { historyHandlers } from "./history.js";
 import { mediaHandlers } from "./media.js";
@@ -35,6 +37,7 @@ import type { WhatsAppActionContext, WhatsAppActionHandlers } from "./types.js";
 // Null-prototype so a request `action` of "toString" / "constructor" can't
 // resolve an inherited Object.prototype method via `handlers[action]`.
 const handlers: WhatsAppActionHandlers = Object.assign(Object.create(null), {
+  ...accountHandlers,
   ...messagingHandlers,
   ...mediaHandlers,
   ...chatInfoHandlers,
@@ -42,8 +45,16 @@ const handlers: WhatsAppActionHandlers = Object.assign(Object.create(null), {
   ...moderationHandlers,
 });
 
-/** Actions that operate on the store alone and need no resolved chat. */
-const CHATLESS_ACTIONS = new Set(["cancel_scheduled", "list_scheduled"]);
+/**
+ * Actions that need no resolved chat: the store-only scheduling pair,
+ * and the account surface, which addresses the logged-in identity
+ * rather than any conversation.
+ */
+const CHATLESS_ACTIONS = new Set([
+  "cancel_scheduled",
+  "list_scheduled",
+  "whatsapp_account",
+]);
 
 export function createWhatsAppActionHandler(
   getSock: () => WASocket | null,

package/src/frontend/whatsapp/actions/shared.ts

@@ -304,3 +304,17 @@ export function toUserJid(value: unknown): string | null {
   const digits = raw.replace(/[^0-9]/g, "");
   return digits ? `${digits}@s.whatsapp.net` : null;
 }
+
+/**
+ * Pull the about text out of a `fetchStatus` result. Baileys has
+ * returned both a bare object and a one-element array across versions,
+ * and the payload itself nests `status` either as a string or as
+ * `{ status }` — accept all four shapes rather than guess one.
+ */
+export function readStatusText(result: unknown): string | undefined {
+  const entry = (Array.isArray(result) ? result[0] : result) as
+    { status?: string | { status?: string } } | undefined;
+  return typeof entry?.status === "string"
+    ? entry.status
+    : entry?.status?.status;
+}