@craftsamo/whatsapp-tools 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,616 @@
-# Temporary Holding Version
+# whatsapp-tools
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+WhatsApp tools for coding agents: chats, messages, contacts, history, received files, sends and actions on the user's own messages and chats.
+
+| Harness        | Delivery                                       | Pinned by                      |
+| -------------- | ---------------------------------------------- | ------------------------------ |
+| OpenCode V2    | native plugin (npm package, with skills)       | the version in the package     |
+| OpenCode V1    | native plugin (npm package, no skills)         | the version in the package     |
+| Claude Code    | plugin: MCP server and skills                  | the release tag, as the ref    |
+| Codex          | plugin: MCP server and skills                  | the release tag, as the ref    |
+| Grok Build     | plugin: MCP server and skills                  | the release tag, as `@ref`     |
+| Antigravity    | plugin: MCP server and skills                  | the release tag's tree URL     |
+| Hermes Agent   | native plugin (Python, calls the command line) | the release commit, as the SHA |
+| other MCP host | MCP server from npm                            | the version in the package     |
+
+The tools need [Node.js](https://nodejs.org/) 24 or later.
+[`docs/conventions.md`](docs/conventions.md) describes how the tools are named
+and how they behave.
+
+## Install
+
+Install from a release, never from the default branch: a release is a tag whose
+commit carries the built `dist/`, and the default branch does not. In the
+commands below, `<version>` is a release's version (`1.2.3`) and `<sha>` is the
+commit its tag names:
+
+```sh
+gh api repos/craft-agent/whatsapp-tools/commits/v<version> --jq .sha
+```
+
+### OpenCode
+
+OpenCode V2 takes the package and its options in `opencode.json`:
+
+```json
+{
+  "plugins": [{ "package": "@craftsamo/whatsapp-tools@<version>", "options": { "read_only": false } }],
+  "permissions": [{ "action": "whatsapp_*", "resource": "*", "effect": "ask" }]
+}
+```
+
+OpenCode V1 takes the package as a string, or as a pair with its options:
+
+```json
+{
+  "plugin": [["@craftsamo/whatsapp-tools@<version>", { "read_only": false }]],
+  "permission": { "whatsapp_*": "ask" }
+}
+```
+
+OpenCode allows any action no rule names, so the plugin's request is granted
+silently unless a rule says `ask`. Read tools never ask, so the `whatsapp_*` glob
+is safe.
+
+V1 registers no skills. Unpack the package and copy its `skills/*` folders into
+`~/.config/opencode/skills/`:
+
+```sh
+npm pack @craftsamo/whatsapp-tools@<version>
+tar -xzf craftsamo-whatsapp-tools-<version>.tgz
+mkdir -p ~/.config/opencode/skills
+cp -r package/skills/* ~/.config/opencode/skills/
+rm -rf package craftsamo-whatsapp-tools-<version>.tgz
+```
+
+### Claude Code
+
+```sh
+claude plugin marketplace add craft-agent/whatsapp-tools#v<version>
+claude plugin install whatsapp-tools@craft-agent
+```
+
+### Codex
+
+```sh
+codex plugin marketplace add craft-agent/whatsapp-tools --ref v<version>
+codex plugin add whatsapp-tools@craft-agent
+```
+
+Codex turns `-` into `_` in server names, so it shows the tools as
+`mcp__whatsapp_tools__whatsapp_*`. It starts the MCP server in the plugin's
+install directory and passes no roots, so the server takes each call's directory
+from what Codex sends with the call: its sandbox state, which the server asks
+for, else the one workspace it names.
+
+The plugin declares `default_tools_approval_mode = "writes"`: Codex asks before
+every tool not marked read-only. A user's
+`[plugins."<plugin>".mcp_servers.<server>]` setting can only tighten it. Setting
+`auto` there yields `prompt` (reads asked too), since Codex treats `auto` and
+`writes` as incomparable.
+
+### Grok Build
+
+```sh
+grok plugin install craft-agent/whatsapp-tools@v<version> --trust
+```
+
+Grok starts the MCP server in the session's working directory.
+
+### Antigravity
+
+Install from the tree of the release tag, never from the default branch, which
+has no built `dist/`; Antigravity clones the tag into
+`~/.gemini/config/plugins/whatsapp-tools`.
+
+```sh
+agy plugin install https://github.com/craft-agent/whatsapp-tools/tree/v<version>
+```
+
+### Hermes Agent
+
+The plugin needs Hermes Agent 0.22 or later. Hermes installs a commit, not a
+tag, and the plugin installs disabled:
+
+```sh
+hermes plugins install craft-agent/whatsapp-tools --ref <sha>
+hermes plugins enable whatsapp-tools
+```
+
+If a Hermes gateway is already running, restart it (`hermes gateway restart`) to
+load the plugin. While a gateway runs, `hermes chat` runs the plugin's tools in
+the gateway too, so they see the gateway's environment, not the shell's: the
+`PATH` that finds `wacli` and `node`, and any `WHATSAPP_TOOLS_*` variable, are
+the ones the gateway started with.
+
+The plugin runs the Node it found when Hermes started. If a version manager
+removes that version while Hermes runs, a call looks for Node again; when it
+finds none, restart Hermes from a shell where `node` runs.
+
+### Any other MCP host
+
+Add the server to the host's MCP configuration. Flags go in `args`:
+
+```json
+{
+  "mcpServers": {
+    "whatsapp-tools": {
+      "command": "npx",
+      "args": ["-y", "@craftsamo/whatsapp-tools@<version>", "--read-only"]
+    }
+  }
+}
+```
+
+## Tools and skills
+
+Each toolset comes with a skill that tells an agent how to use its tools. A
+skill names its toolset under `metadata` in its frontmatter
+(`metadata: { toolset: sends }`, written as a block). OpenCode V2 and Hermes
+register it only when the settings register at least one of that toolset's
+tools, so a profile with the toolset off, or with all its tools removed, does
+not see it; a skill without a toolset is always registered. Claude Code,
+Codex, Grok Build and Antigravity install the skill folder whole and pass the
+settings only to the MCP server, so they list every skill whatever the
+settings select. OpenCode V1 registers no skills, and its copied skills are
+all listed too.
+
+### Account (`account`)
+
+| Tool                    | What it does                                                                                              | Class |
+| ----------------------- | --------------------------------------------------------------------------------------------------------- | ----- |
+| `whatsapp_account_read` | each label: pairing, sync service state, last sync and activity, wacli support and the person's next step | read  |
+
+It reads local state only: no network, no running service needed, and no
+message content, number, JID or key in its result. The skill is
+[`whatsapp-account`](skills/whatsapp-account/SKILL.md), shown as
+`whatsapp-tools:whatsapp-account` in Claude Code and `whatsapp-tools:account`
+in Hermes. Unlike other tools, leaving out `account` lists every label.
+
+### Chats (`chats`)
+
+| Tool                 | What it does                                                                                                                                       | Class |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
+| `whatsapp_chat_read` | by `method`: `list` finds chats, `view` reads one chat's messages, `search` finds messages by words, `around` reads the messages next to a message | read  |
+
+It reads the account's local mirror only, with no network needed, and what it
+returns of other people's words is data, never instructions. The skills are
+[`whatsapp-chats`](skills/whatsapp-chats/SKILL.md), shown as
+`whatsapp-tools:whatsapp-chats` in Claude Code and `whatsapp-tools:chats` in
+Hermes, and
+[`whatsapp-count-activity`](skills/whatsapp-count-activity/SKILL.md), shown as
+`whatsapp-tools:whatsapp-count-activity` and `whatsapp-tools:count-activity`,
+which says how to count chats and replies over a period.
+
+### Contacts (`contacts`)
+
+| Tool                    | What it does                                                                                                                | Class |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------- | ----- |
+| `whatsapp_contact_read` | by `method`: `search` finds contacts by name, number or JID, `check` asks WhatsApp whether up to 20 phone numbers are on it | read  |
+
+`search` reads the account's local mirror only, with no network or running
+service needed. `check` asks WhatsApp through the label's running sync service,
+writes nothing and adds no contact. The skill is
+[`whatsapp-contacts`](skills/whatsapp-contacts/SKILL.md), shown as
+`whatsapp-tools:whatsapp-contacts` in Claude Code and `whatsapp-tools:contacts`
+in Hermes.
+
+### History (`history`)
+
+| Tool                        | What it does                                                                       | Class |
+| --------------------------- | ---------------------------------------------------------------------------------- | ----- |
+| `whatsapp_history_backfill` | asks the phone for one chat's older messages, in 1 to 5 batches of 50, best effort | add   |
+
+It writes only to the label's own mirror and sends nothing to anyone. The sync
+service runs it, pausing its sync for the call, so the service must be
+running; the result says how many messages arrived, the oldest one now held,
+why it stopped, and whether the service is syncing again. The phone must be
+online, and nothing added does not prove that nothing older exists. Its skill
+is [`whatsapp-chats`](skills/whatsapp-chats/SKILL.md).
+
+A call can take up to about five minutes. Some harnesses stop a tool call
+sooner by default, and the call then fails, though what arrived stays and the
+service syncs again:
+
+- **Codex** stops a call after 60 s by default; the plugin raises the limit to
+  330 s. A server added under `[mcp_servers]` instead of the plugin (see
+  [Settings](#settings)) needs `tool_timeout_sec = 330`.
+- **Antigravity** stops a call after 180 s. Give the server
+  `"timeoutSeconds": 330` in its MCP configuration.
+- **Hermes** gives the plugin's calls 150 s, and 330 s to
+  `whatsapp_history_backfill`, `whatsapp_file_save` and `whatsapp_file_send`;
+  nothing needs setting.
+
+### Files (`files`)
+
+| Tool                 | What it does                                                                                             | Class |
+| -------------------- | -------------------------------------------------------------------------------------------------------- | ----- |
+| `whatsapp_file_save` | saves one message's file into `download_dir`, inspecting archives and unpacking one when asked to        | add   |
+| `whatsapp_file_send` | sends 1 to 10 files, up to 100 MiB, to a person or a group, one message each, checked before any is sent | add   |
+
+Off by default: turn it on with the `files` toolset. A message's file goes into
+its own folder under `download_dir` (`~/Downloads/whatsapp-tools` by default),
+private and never executable, and nothing is overwritten. Programs,
+installers, disk images, macro documents and archives that cannot be read are
+refused; zip, tar and gzipped tar are inspected first and unpacked only when
+asked. On macOS each saved file carries the quarantine flag. A file WhatsApp's
+server no longer keeps is asked of the phone through the running sync service.
+The skill is
+[`whatsapp-files`](skills/whatsapp-files/SKILL.md), shown as
+`whatsapp-tools:whatsapp-files` in Claude Code and `whatsapp-tools:files` in
+Hermes.
+
+A call that falls back to the phone can take a few minutes; the tool time
+limits given above under History apply to it too.
+
+`whatsapp_file_send` sends only from the working directory and the
+directories the `send_dirs` setting names, judged by real path; a file
+anywhere else is refused, and so is the state directory. Keys and secrets
+(`.ssh`, `.env`, `*.pem`, …), the data folders of browsers, password managers
+and messengers, empty files, programs, installers and anything holding a
+private key block are never sent, wherever they are; an archive is sent only
+once every entry passes, and is never unpacked. Each file is copied into the
+label's outbox and checked there, so what is checked is what leaves, and a
+`sha256` the user approved makes a changed file `stale`. Each file is its own
+message, in the order given, with the text as the first file's caption (at most
+1,024 characters, refused on audio). Photos, videos and audio WhatsApp shows
+itself go as such, decided from the name and the first bytes, and everything
+else as a file; `as_document` sends all of them as files. A call that stops
+after some files went out fails and lists in `details` what went out, with
+the message ids, and what did not, so nothing is sent twice; a file that may
+have gone out is `uncertain`. A call takes at most 280 s, and the tool time
+limits given above under History apply to it too.
+
+### Sends (`sends`)
+
+| Tool                    | What it does                                                                                  | Class |
+| ----------------------- | --------------------------------------------------------------------------------------------- | ----- |
+| `whatsapp_message_send` | sends one text, up to 4,000 characters, to a person or a group, with an optional quoted reply | add   |
+
+On by default, and it goes through the label's running sync service, so the
+service must be running. It sends to people and groups only: a channel, a
+broadcast list and the status feed are refused. The chat is a JID from
+`whatsapp_chat_read`; for someone the mirror does not hold yet, it is the
+`chat` that `whatsapp_contact_read` `check` gives, and WhatsApp is asked right
+before sending whether the number has an account. The text goes out as given,
+surrounding blank space trimmed, never split, and with no link preview. A
+result means WhatsApp accepted the message, not that it was delivered or read.
+A failure known to happen before anything left says so; every other failure
+after the request was handed over is `uncertain`: the message may have gone
+out, and the chat is checked and the user asked before it is sent again. Like
+a message written on the phone, a send lowers the chat's unread count in the
+mirror and sends no read receipt. The skill is
+[`whatsapp-sends`](skills/whatsapp-sends/SKILL.md), shown as
+`whatsapp-tools:whatsapp-sends` in Claude Code and `whatsapp-tools:sends` in
+Hermes.
+
+### Actions (`actions`)
+
+| Tool                      | What it does                                                                   | Class          |
+| ------------------------- | ------------------------------------------------------------------------------ | -------------- |
+| `whatsapp_chat_archive`   | archives a chat, or unarchives it                                              | idempotent     |
+| `whatsapp_chat_mark`      | marks a chat read or unread, optionally sending read receipts                  | idempotent     |
+| `whatsapp_chat_mute`      | mutes a chat for 8 hours, a week or always, or unmutes it                      | idempotent     |
+| `whatsapp_chat_pin`       | pins a chat, or unpins it, up to the three WhatsApp allows                     | idempotent     |
+| `whatsapp_message_delete` | deletes a message the user sent for everyone, at most two days after it        | administrative |
+| `whatsapp_message_edit`   | replaces the text of a text message the user sent, at most 15 minutes after it | overwrite      |
+| `whatsapp_message_react`  | reacts to a message with one emoji, or removes the user's reaction             | overwrite      |
+
+Off by default: turn it on with the `actions` toolset. Each action goes
+through the label's running sync service and acts only on a chat and a message
+the mirror holds, named by JID and id from `whatsapp_chat_read`. Deleting for
+everyone pauses the sync service for the call, a few seconds, and the result
+says whether it syncs again. It keeps to the limits WhatsApp's own apps hold,
+and refuses past them before anything leaves. A result means WhatsApp
+accepted the action; a failure known to happen before anything left says so,
+and every other failure is `uncertain`: the chat is checked and the user asked
+before the action is tried again. A chat's archive, pin, mute and read state
+are states only the user's own devices show, and setting one again is safe,
+so their `uncertain` says so. Marking a chat read tells no one by default;
+only when the user asks for it does `receipts: true` send read receipts for up
+to 100 unread messages instead, which tells their senders and clears only the
+mirror's unread count, not necessarily the phone's mark. The skill is
+[`whatsapp-actions`](skills/whatsapp-actions/SKILL.md), shown as
+`whatsapp-tools:whatsapp-actions` in Claude Code and `whatsapp-tools:actions`
+in Hermes.
+
+## Adding a tool
+
+1. Write the spec in `src/core/<domain>/<verb>.ts` with `defineTool`: an ID
+   `<prefix>_<domain>_<verb>`, a title and description, the Zod argument and
+   output schemas, its toolset and write class, and `execute(args, context)`.
+   A write tool also gives `targets(args, context)`: what the call writes to,
+   as a permission rule should name it.
+2. Test it beside the spec (`<verb>.test.ts`), calling it through `invoke` as
+   the entry points do. A tool that runs a program is tested against a fake of
+   that program on `PATH`; no test reaches a real service.
+3. List it in `src/tools.ts`. A new toolset goes into `toolsets` in
+   `src/project.ts` (and `defaultToolsets` when it is on by default), a
+   setting of the package's own into `options` (and `OPTIONS` in `project.py`
+   with `config_schema` in `plugin.yaml`), and a variable the tool reads
+   besides the settings into `toolVariables`.
+4. Add or update the toolset's skill, `skills/<prefix>-<toolset>/SKILL.md`,
+   whose frontmatter names the toolset under `metadata`.
+5. Run `pnpm run build && pnpm run manifests` to list the tool in
+   `plugin.yaml` and its variables in Codex's manifest, then describe it under
+   "Tools and skills".
+
+[`docs/conventions.md`](docs/conventions.md) has the rules each step follows.
+
+A package declares each option as `text`, `boolean`, `number`, `list`, `path`
+or `paths`, or as an object with `type` and optional bounds. For example, in
+`src/project.ts`:
+
+```ts
+options: {
+  notes_dir: "path",
+  note_limit: { type: "number", integer: true, min: 1, max: 50 },
+}
+```
+
+`integer: true` requires a whole number; `min` and `max` bound a number or
+count a `list` or `paths` value's items. An object with only `type` means the
+same as the type alone. Hermes's `OPTIONS` mirrors the declarations on one
+line, with double quotes and Python's `True` for `integer`:
+
+```python
+OPTIONS: dict[str, str | dict[str, object]] = {"notes_dir": "path", "note_limit": {"type": "number", "integer": True, "min": 1, "max": 50}}
+```
+
+## Reads and writes
+
+Every read tool is named `<prefix>_<domain>_read`. Reads can run unasked;
+writes are confirmed by the harness.
+
+| Harness     | Reads without asking                                                                                             |
+| ----------- | ---------------------------------------------------------------------------------------------------------------- |
+| OpenCode    | always; the plugin asks only before a write                                                                      |
+| Claude Code | the rule `mcp__plugin_whatsapp-tools_whatsapp-tools__*_read` in `permissions.allow` of `~/.claude/settings.json` |
+| Codex       | always; Codex runs tools that declare `readOnlyHint` unasked, as the read tools do                               |
+| Grok Build  | `grok --allow 'MCPTool(whatsapp-tools__*_read)' --allow 'MCPTool(whatsapp_*_read)'` (both rules; see below)      |
+| Antigravity | the rule `mcp(whatsapp-tools_whatsapp-tools/<tool id>)` in `permissions.allow`, one for each read tool           |
+| Hermes      | always; the plugin asks only before a write                                                                      |
+
+Where a write is asked about, and where it is not:
+
+- **OpenCode** grants any action no rule names, so a write runs unasked unless
+  a rule asks for it: add the `whatsapp_*` rule shown under [OpenCode](#opencode).
+- **Codex** asks before every write because of the plugin's approval mode.
+  Under `codex exec` it refuses with "MCP tool call requires approval, but
+  approval policy is never".
+- **Grok Build** under `grok -p` refuses a write it cannot ask about, unless it
+  is allowed beforehand.
+- **Grok Build** calls the plugin's tools through its `use_tool` tool, and the
+  agent often names a tool without its server first. Grok checks the rules
+  against the name as given, so the server-qualified rule alone does not match
+  that first call. The second rule matches the short name; a write still
+  matches neither.
+- **Antigravity** asks before any MCP tool no rule allows, reads included, and
+  names the plugin's server `whatsapp-tools_whatsapp-tools` (plugin,
+  then server). `agy -p` refuses a tool it cannot ask about.
+- **Hermes** `hermes chat -q` refuses a write it cannot ask about; `hermes -z`
+  and `--yolo` skip approval, so writes then run unasked.
+
+## Settings
+
+Every entry point takes the same settings. A flag wins over its environment
+variable, and an option or setting wins over the variable too, except in
+Hermes, noted below.
+
+| Setting         | Flag              | Variable                       | Meaning                                                                           |
+| --------------- | ----------------- | ------------------------------ | --------------------------------------------------------------------------------- |
+| `toolsets`      | `--toolsets`      | `WHATSAPP_TOOLS_TOOLSETS`      | the toolsets that are on, or `all`; default those `src/project.ts` names          |
+| `read_only`     | `--read-only`     | `WHATSAPP_TOOLS_READ_ONLY`     | registers no tool that writes; wins over every other setting                      |
+| `tools`         | `--tools`         | `WHATSAPP_TOOLS_TOOLS`         | single tools to add by ID, whatever their toolset                                 |
+| `exclude_tools` | `--exclude-tools` | `WHATSAPP_TOOLS_EXCLUDE_TOOLS` | single tools to remove by ID; wins over `tools` and `toolsets`                    |
+| `confirm`       | `--confirm`       | `WHATSAPP_TOOLS_CONFIRM`       | MCP server only: `harness` (default) or `elicitation`, as the conventions say     |
+| `language`      | `--language`      | `WHATSAPP_TOOLS_LANGUAGE`      | native plugins only: the approval prompt's language, such as `ja`                 |
+| `emoji`         | —                 | —                              | Hermes only: the emoji shown beside each toolset, by toolset name (`""` for none) |
+| `state_dir`     | `--state-dir`     | `WHATSAPP_TOOLS_STATE_DIR`     | `path`: where every label's state lives; default `$XDG_STATE_HOME/whatsapp-tools` |
+| `download_dir`  | `--download-dir`  | `WHATSAPP_TOOLS_DOWNLOAD_DIR`  | `path`: where received files are saved; default `~/Downloads/whatsapp-tools`      |
+| `send_dirs`     | `--send-dirs`     | `WHATSAPP_TOOLS_SEND_DIRS`     | `paths`: the directories files may be sent from, besides the working directory    |
+
+Lists are comma-separated in a flag or a variable. `state_dir`, `download_dir`
+and `send_dirs` are this package's own settings, listed in `options` in
+`src/project.ts` and read the same way. A `path` is trimmed; `~` and `~/…`
+(also with the platform separator) stand for the home directory (`HOME` when
+it is absolute, else the account's). It must then be absolute and reaches the
+tool normalized, without a filesystem check. A blank path counts as unset,
+so the default applies. `paths` is a list of such paths, comma-separated in a
+flag or variable and an array of strings in a plugin option. Blank items are
+dropped, and a list with none left counts as unset. Repeated send directories
+are dropped. Bounds check only a given value, not an unset option. Refused
+values are `invalid_argument`, naming the flag, variable or option and what it
+must be.
+Hermes passes paths and lists to the command line, which checks the paths and
+bounds. Where each harness reads them:
+
+- **OpenCode** takes the plugin `options` shown above, with lists as arrays,
+  `read_only` as a boolean, `state_dir` and `download_dir` as paths and
+  `send_dirs` as an array of paths, and falls back to the variables. V2 runs plugins in
+  its background service, which keeps the environment it started with: a
+  variable set where `opencode run` starts has no effect until the service is
+  restarted in that environment (`opencode service restart`). V1 runs plugins
+  in its own process.
+- **Hermes** takes `plugins.entries.whatsapp-tools.settings` in
+  `config.yaml`:
+
+  ```yaml
+  plugins:
+    entries:
+      whatsapp-tools:
+        settings:
+          read_only: false
+          exclude_tools: []
+  ```
+
+  Without a `language` setting, the approval card follows Hermes's own
+  `display.language` (or `HERMES_LANGUAGE`), the language of its approval
+  buttons, and else stays in English. The plugin passes its own environment
+  to the command line it runs, so the variables work too. A setting that is
+  off or empty (`read_only: false`, `tools: []`, `exclude_tools: []`,
+  `send_dirs: []`) passes nothing, so a variable set in that environment
+  still applies: `WHATSAPP_TOOLS_READ_ONLY=true` keeps the plugin read-only
+  whatever the setting says. A running gateway keeps the environment it
+  started with, and `hermes chat` runs the tools there while it runs; restart
+  it (`hermes gateway restart`) after changing one.
+
+- **Claude Code, Grok Build and Antigravity** start the plugin's server without
+  flags and pass it the client's environment, so set the variables in the
+  environment the harness runs in.
+- **Codex** passes a plugin's MCP server only a few basic variables (such as
+  `PATH` and `HOME`) and those the plugin's manifest names, which are the
+  variables above: set them in the environment Codex runs in. A variable the
+  tools read besides the settings belongs in `toolVariables` in
+  `src/project.ts`; `pnpm run manifests` adds it to the manifest after the
+  settings' variables. To pass flags, or to give the server a variable the
+  package does not name, add the server under `[mcp_servers]` in Codex's
+  `config.toml` instead of using the plugin: flags go in `args`, `env_vars`
+  names the variables to forward from Codex's environment, and `env` sets
+  fixed values.
+
+  ```toml
+  [mcp_servers.whatsapp-tools]
+  command = "npx"
+  args = ["-y", "@craftsamo/whatsapp-tools@<version>", "--read-only"]
+  env_vars = ["WHATSAPP_TOOLS_TOOLSETS"]
+  tool_timeout_sec = 330
+  ```
+
+### Accounts and the sync service
+
+The tools use a WhatsApp account as a linked device of the user's phone, the
+way WhatsApp Web does, through [wacli](https://github.com/openclaw/wacli),
+which you install yourself (`brew install openclaw/tap/wacli`, or a release
+binary). They never drive WhatsApp Web or read another client's data.
+
+- **wacli 0.26 or later.** WhatsApp stops serving old clients until wacli
+  catches up with its protocol, so keep it updated; after an update, restart
+  the sync service so it runs the new release.
+- **Each linked device has a label**, 1 to 24 lowercase letters, digits and
+  `_` (`default` when pairing names none). A tool's `account` argument picks
+  the label; leave it out when only one device is paired. The account tool
+  instead lists every label when `account` is absent.
+- **Each label keeps its state in one directory**, `<state_dir>/<label>/`
+  (mode 700): wacli's store (the session keys, its mirror of your messages,
+  downloaded media), the sync service's socket, and the copies of files being
+  sent. `state_dir` defaults to `$XDG_STATE_HOME/whatsapp-tools`, or
+  `~/.local/state/whatsapp-tools`. wacli's own accounts in `~/.wacli` are not
+  used. Keep the directory out of backups you share: the keys read and send as
+  you.
+- **A sync service runs for each label**: it keeps the mirror current, and
+  every send and every other write goes through it, so the tools that write
+  need it running. Reads work with or without it. History starts when the
+  device is paired, with what the phone sends then; older messages can be
+  asked of the phone, best effort.
+- **WhatsApp unlinks a device unused for 30 days**, and every linked device
+  when the phone has been unused for 14; a phone takes four linked devices at
+  most. A running service keeps the device in use. An unlinked label is paired
+  again from the phone.
+- **wacli is not an official client.** WhatsApp has no API for personal
+  accounts, and it may limit or ban an account it finds using an unofficial
+  one.
+
+### Pairing a device and running the sync service
+
+Install [wacli 0.26 or later](https://github.com/openclaw/wacli) first: on
+macOS, `brew install openclaw/tap/wacli`; elsewhere, a release binary. macOS
+and Linux are supported; Windows is
+[#11](https://github.com/craft-agent/whatsapp-tools/issues/11).
+
+The commands come with the npm package, apart from any harness plugin: a
+plugin gives the tools, not a command on your `PATH`. Install the package
+globally, at the version of the plugin you use, so that the service it
+installs keeps a stable path:
+
+```sh
+npm install -g @craftsamo/whatsapp-tools@<version>
+```
+
+```sh
+# On the phone, WhatsApp > Linked devices > Link a device, then scan the QR.
+whatsapp-tools-cli pair --account work
+
+# Start syncing at logon, and restart after a failure.
+whatsapp-tools-cli service install --account work
+whatsapp-tools-cli service status
+```
+
+`--account` may be left out when only one label exists (`pair` names a new
+one `default`), except by `remove`, which always needs it; every command takes
+`--state-dir` like the tools. With
+several labels, add `--account work` to `service status` too.
+
+Every command below follows `whatsapp-tools-cli`:
+
+| Command                                                                             | What it does                                                                                                            |
+| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `pair [--account <label>] [--phone <number>] [--full-history [--history-days <n>]]` | pairs this machine from a QR code, or with `--phone` prints a code to enter on the phone, then waits for the first sync |
+| `sync [--account <label>]`                                                          | runs the sync service in the foreground, logging to standard error, until stopped                                       |
+| `service install \| uninstall \| status [--account <label>]`                        | registers/starts the service as a launchd agent (macOS) or systemd user unit (Linux), removes it, or reports its state  |
+| `remove --account <label> [--yes]`                                                  | uninstalls the service, logs the device out when possible and deletes the label's keys and history after confirmation   |
+
+- **The service records this package's paths and Node's**, so run
+  `service install` again after updating either. Where Node's path holds its
+  version, as under a version manager, `service install` records a `node` on
+  `PATH` at a path without it that starts the same Node, and warns when there
+  is none. That `node` then runs whichever Node the manager makes current.
+  `service status` and `whatsapp_account_read` say when the recorded program
+  is gone, once the service has been installed with this version. On macOS its
+  log is
+  `~/Library/Logs/io.github.craft-agent.whatsapp-tools/<label>.log`; on Linux,
+  `journalctl --user -u <unit>` as `service status` shows, and
+  `loginctl enable-linger` keeps it running while you are logged out.
+- **On macOS, Login Items lists the service as `whatsapp-tools-sync-<label>`**:
+  the agent starts through that launcher script, which `service install`
+  writes to
+  `~/Library/Application Support/io.github.craft-agent.whatsapp-tools/` and
+  `service uninstall` deletes. Switching the item off there stops syncing.
+- **A phone takes at most four linked devices**, and each label is one of
+  them. WhatsApp unlinks a device unused for 30 days, and every linked device
+  when the phone has been unused for 14 days; a running service keeps the
+  linked device in use, not the phone.
+- **`--full-history` asks the phone for its full history** while pairing,
+  instead of its recent months; `--history-days` limits how far back. It
+  takes effect only while pairing, and the phone keeps sending for a while
+  after `pair` ends, which reaches the mirror once the service runs. A
+  device already paired gets older messages with `whatsapp_history_backfill`,
+  one chat at a time, or by being removed and paired again.
+- **To pair a revoked label again**, run `pair` again: the dead session is
+  deleted and the mirror is kept. Use a new label for a different account.
+- **Removing a label logs the device out when possible.** If it cannot,
+  remove the linked device on the phone under WhatsApp > Linked devices too.
+- `whatsapp_account_read` tells an agent which step a label needs.
+
+## Layout
+
+- `src/project.ts` — the package's name, tool ID prefix, setting prefix,
+  toolsets, tool options and the other variables its tools read.
+- `src/core/` — the tool contract and the tools, free of any harness and of
+  the project's names.
+- `src/tools.ts` — the list of every tool, which each entry point registers.
+- `src/words.ts` — the translations of the tools' words, per language, which
+  the native plugins use in their approval prompts.
+- `src/mcp/` — the MCP server, built to `dist/mcp.js` and run by
+  `whatsapp-tools`.
+- `src/opencode/` — the OpenCode plugin, built to `dist/opencode.js`.
+- `src/cli/` — the command line the Hermes plugin calls, built to `dist/cli.js`
+  and run by `whatsapp-tools-cli`.
+- `src/hermes/`, `plugin.yaml` and `__init__.py` — the Hermes plugin.
+- `skills/` — one skill per toolset, `skills/<name>/SKILL.md`, which every
+  harness that takes skills loads from the package or plugin root; the native
+  plugins load only those of the toolsets that are on.
+- `.claude-plugin/`, `.codex-plugin/`, `.agents/plugins/`, `.mcp.json`,
+  `.antigravity-plugin/` and `mcp_config.json` — the plugin manifests of the
+  other harnesses. Codex reads `.codex-plugin/plugin.json`; a root
+  `plugin.json` would make it load the plugin as an Agent Plugin, whose tool
+  budget hides tools past a fixed size. The root `.mcp.json` is the
+  configuration Grok Build reads (with `${CLAUDE_PLUGIN_ROOT}`, the variable
+  both Grok Build and Claude Code expand); when working on this repository in
+  Claude Code, decline the project MCP server it offers from that file.
+
+How a release is made is in [`RELEASING.md`](RELEASING.md).
+
+## License
+
+[AGPL-3.0 with Commons Clause](LICENSE)

package/__init__.py

@@ -0,0 +1,36 @@
+"""Loads the plugin package from ``src/hermes/whatsapp_tools_hermes`` for Hermes, which imports this file.
+
+The package is loaded as ``<this module's name>._impl``, so Hermes, which evicts
+everything under a plugin's module name when it reloads it or loads it for another
+profile, evicts the package too, and each install path gets a package of its own.
+"""
+
+import importlib.util
+import sys
+from pathlib import Path
+
+_NAME = f"{__name__}._impl"
+_PACKAGE_DIR = Path(__file__).resolve().parent / "src" / "hermes" / "whatsapp_tools_hermes"
+
+
+def _evict() -> None:
+    """Drop the package and its submodules from ``sys.modules``."""
+    for name in list(sys.modules):
+        if name == _NAME or name.startswith(f"{_NAME}."):
+            sys.modules.pop(name, None)
+
+
+_spec = importlib.util.spec_from_file_location(
+    _NAME, _PACKAGE_DIR / "__init__.py", submodule_search_locations=[str(_PACKAGE_DIR)]
+)
+_module = importlib.util.module_from_spec(_spec)
+_evict()
+sys.modules[_NAME] = _module
+try:
+    _spec.loader.exec_module(_module)
+except BaseException:
+    _evict()
+    raise
+
+register = _module.register
+__all__ = ["register"]