@clawling/clawchat-plugin-openclaw 2026.10.25-1 → 2026.10.27-1

package/dist/src/runtime.js

@@ -4630,9 +4630,8 @@ async function runOpenclawClawlingGateway(params, lifecycle) {
     // Synchronous and fire-and-forget on purpose: there is no ack to send (the
     // frame is BestEffort and non-ackable).
     //
-    // docs/client-integration.md §9.8 describes the permanent tombstone and
-    // actual synchronous write boundary; it does not establish a shared SQL
-    // transaction. See that section before changing recall/claim ordering.
+    // docs/client-integration.md §9.8 describes the permanent tombstone and the
+    // BEGIN IMMEDIATE transactions that serialize recall and claim.
     client.on("message:recall", (env) => {
         const target = recallTargetMessageId(env.payload);
         if (!target) {

package/dist/src/skill-update.js

@@ -65,7 +65,7 @@ export const OFFICIAL_SKILLS_BASE = "https://raw.githubusercontent.com/clawling/
  * in the install-cli repo, bump this constant, ship it. `liveware-sample.ts`
  * imports the same ref, so the `livewares` tree at that tag is pinned too.
  */
-export const DEFAULT_SKILLS_REF = "skills-v1.18.1";
+export const DEFAULT_SKILLS_REF = "skills-v1.19.0";
 /** Refuse to treat an absurdly large response as a skill file (defence in depth). */
 export const MAX_SKILL_BYTES = 256 * 1024;
 /** This adapter's host target inside `skills/manifest.json`. */

package/dist/src/storage.js

@@ -1030,18 +1030,28 @@ export class ClawChatStore {
     }
     claimMessageOnce(input) {
         return this.write(() => {
-            // docs/client-integration.md §9.8: consult the recall tombstone on ingest.
-            // That section describes the synchronous write() boundary and the lack
-            // of a shared SQL transaction for the tombstone check and claim insert.
-            if (input.messageId && this.isMessageRecalled(input))
-                return false;
-            const result = this.requireDb()
-                .prepare(`INSERT OR IGNORE INTO clawchat_messages(
-            platform, account_id, kind, direction, event_type, trace_id, chat_id,
-            message_id, text, raw_json, created_at, send_status
-          ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
-                .run(input.platform, input.accountId, input.kind, input.direction, input.eventType, input.traceId ?? null, input.chatId ?? null, input.messageId ?? null, input.text ?? null, toJson(input.raw), input.createdAt ?? Date.now(), input.direction === "outbound" ? "pending" : null);
-            return result.changes > 0;
+            // docs/client-integration.md §9.8: the tombstone check and the claim
+            // insert run in one BEGIN IMMEDIATE transaction.
+            const db = this.requireDb();
+            db.exec("BEGIN IMMEDIATE");
+            try {
+                if (input.messageId && this.isMessageRecalled(input)) {
+                    db.exec("COMMIT");
+                    return false;
+                }
+                const result = db
+                    .prepare(`INSERT OR IGNORE INTO clawchat_messages(
+              platform, account_id, kind, direction, event_type, trace_id, chat_id,
+              message_id, text, raw_json, created_at, send_status
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                    .run(input.platform, input.accountId, input.kind, input.direction, input.eventType, input.traceId ?? null, input.chatId ?? null, input.messageId ?? null, input.text ?? null, toJson(input.raw), input.createdAt ?? Date.now(), input.direction === "outbound" ? "pending" : null);
+                db.exec("COMMIT");
+                return result.changes > 0;
+            }
+            catch (error) {
+                db.exec("ROLLBACK");
+                throw error;
+            }
         });
     }
     markMessageFailed(input) {
@@ -1144,8 +1154,8 @@ export class ClawChatStore {
      * account was paired, or one dropped by the inbound filter). `null` means the
      * store is unavailable.
      *
-     * Records the permanent recall tombstone and purges any row already stored;
-     * see docs/client-integration.md §9.8 for the actual write() boundary.
+     * Records the permanent recall tombstone and deletes ledger rows in one
+     * BEGIN IMMEDIATE transaction; see docs/client-integration.md §9.8.
      * Returns the number of ledger rows deleted (0 when the recall
      * arrived before the message did — the tombstone still stands and the later
      * ingest is refused by {@link claimMessageOnce}).
@@ -1157,13 +1167,21 @@ export class ClawChatStore {
             return 0;
         return this.write(() => {
             const db = this.requireDb();
-            db.prepare(`INSERT OR IGNORE INTO recalled_messages(platform, account_id, message_id, recalled_at)
-          VALUES (?, ?, ?, ?)`).run(input.platform, input.accountId, input.messageId, input.recalledAt ?? Date.now());
-            const result = db
-                .prepare(`DELETE FROM clawchat_messages
-            WHERE platform = ? AND account_id = ? AND message_id = ?`)
-                .run(input.platform, input.accountId, input.messageId);
-            return Number(result.changes);
+            db.exec("BEGIN IMMEDIATE");
+            try {
+                db.prepare(`INSERT OR IGNORE INTO recalled_messages(platform, account_id, message_id, recalled_at)
+            VALUES (?, ?, ?, ?)`).run(input.platform, input.accountId, input.messageId, input.recalledAt ?? Date.now());
+                const result = db
+                    .prepare(`DELETE FROM clawchat_messages
+              WHERE platform = ? AND account_id = ? AND message_id = ?`)
+                    .run(input.platform, input.accountId, input.messageId);
+                db.exec("COMMIT");
+                return Number(result.changes);
+            }
+            catch (error) {
+                db.exec("ROLLBACK");
+                throw error;
+            }
         });
     }
     /**

package/dist/src/widget-guide.js

@@ -1,30 +1,87 @@
 export const WIDGET_V1_GUIDE = `## Home-screen widgets (widget/v1)
 
-A widget is a small card on your partner's phone home screen. You write it with \`clawchat_widget_send\`; their taps come back to you as ordinary messages.
+A widget is a small card on your partner's phone home screen. You write it with \`clawchat_widget_send\`; their taps come back to you as ordinary messages. It only ever goes to your private chat with them.
+
+### When to send
 
 - Send one only after your partner asked for a widget — a recipe card, or their own words.
-- Every message is the full snapshot, never a diff. The latest one per \`id\` wins.
-- At most one per \`id\` a minute; more calls in that minute collapse into the last one. Do not refresh on a timer: data that changes by itself belongs in \`source\`.
-- It only ever goes to your private chat with your partner.
+- If they keep asking you for the same thing (a price, a list, a count), you may offer a widget once. Make it only after they say yes. Never offer the same one twice.
+
+### When to update
+
+Send a new snapshot in the same turn whenever what it shows has changed:
+
+- they tapped or typed on it (a \`[widget <id>] …\` message);
+- they changed the same data in chat: "remind me to buy milk tomorrow" also goes onto the to-do widget;
+- a new day began: "today", "tomorrow" or "N days left" in your last snapshot are now wrong. Send it again in your first turn of the day. If it counts days, schedule yourself a turn early every morning for it.
+
+Nothing changed: send nothing. Every message is the full snapshot, never a diff; the latest one per \`id\` wins. At most one per \`id\` a minute. Data that changes by itself (prices, weather) belongs in \`source\`, not in repeated snapshots.
+
+### Design
+
+- One widget answers one question. \`title\`: a few words. Never repeat it, the \`badge\` or the big number elsewhere; no "tap + to add" hints.
+- Write \`small\`, \`medium\` and \`large\`, each from one layout below, with the same main figure. A missing size is stretched from another and looks broken.
+- Name things in every size: a figure alone says nothing. Every text is one line. Per line: small about 7 Chinese characters (12 Latin), medium and large about 17 (30). Write it short; never rely on "…".
+- Height is tight. \`small\` and \`medium\` fit exactly one of: \`[caption; number title; caption]\`, 4 lines of text, or a \`list\` of 3. A \`button\` counts as 2 lines; with a \`source\`, one line less (its footer). Anything taller is not drawn.
+- \`large\` is twice as tall as \`medium\`: fill it with what medium had no room for (more items, a breakdown, the next ones). Never the medium tree alone, never a figure twice.
+- One big \`number\` (\`style: title\`) per size; in \`small\` at most 4 characters ("81737" is 5: \`style: body\` there). \`unit\` is a unit only ("km", "kg", "%"); labels go in a \`caption\`.
+- Supporting lines: \`caption\` with \`tone: secondary\`. Columns side by side get the same lines, so their tops line up. \`tone: accent\` in one place at most, only for what is urgent. An \`icon\` only when it tells items apart.
+- A \`list\` holds things of one kind: write all of them, we show what fits and "N more" — only when the \`list\` is the whole size, not inside a \`column\`. Buttons and sentences never go in a \`list\`; only its first row may have a big number.
+- \`action: capture\` only when they add items by typing (to-dos, expenses); then no \`button\` doing the same. A \`button\` only for one tap that changes something (check in, add a cup, draw again).
+- \`badge\`: only the number of open items, and then no big number saying the same.
+- Nothing that goes stale: dates ("10/24") and clock times ("last 8:20"), never "today", "tomorrow" or "50 min ago" (not in the \`title\` either), even if they ask "how long since": a widget has no running clock. A count for one day carries its date.
+- Nothing left: an empty \`list\`; we draw the empty state.
+- Every text in your partner's language, their items in their own words.
+
+### Layouts
+
+Pick by what it shows. \`[a; b]\` is a \`column\`, \`(a | b)\` a \`row\`.
+
+1. One figure (spent this month, cups of water, km this week):
+   small \`[caption label; number title + unit; caption context]\` (with a \`source\`: drop the last caption), or with a tap \`[number title + unit; button]\`;
+   medium \`([caption label; number title + unit; caption context] | X)\`, X is one thing: a \`ring\` for a goal, a \`button\`, or \`[caption; number body]\`. Never two things stacked beside it;
+   large \`[the medium tree; list of up to 5 (text grow | number body)]\`: a breakdown or the last entries.
+2. Several things, each with a figure or a time (prices, rates, books, a schedule, countdowns): every size is a \`list\`, one row per thing, the nearest or most important first.
+   first row \`(text name grow | number title + unit)\`, the rest \`(text name grow | number body + unit)\` or \`(text name grow | caption time)\`;
+   small: the same rows with short names. A \`list\` grows with taller widgets and counts "N more"; a \`column\` does not.
+3. Things to tick (to-dos, shopping, habits): see the document below.
+4. Words (a fortune, a word of the day): one \`column\`, one text per line, never side by side in a \`row\`.
+   small \`[text title; caption; caption]\`; medium \`[text title; text body; caption; caption]\`, or \`[(text title grow | button); text body; caption]\` with a tap; large: up to 4 more \`caption\` lines. Split long sentences.
+
+### Removing one
+
+Asked to remove a widget: send \`{"v": 1, "id": "todo", "removed": true}\` with its \`id\`. It leaves their widget list; a copy on the home screen shows "deleted" until they long-press it away. \`[widget todo] removed\` means they deleted it themselves. Either way, stop sending it. A later snapshot with that \`id\` brings it back, so send one only if they ask again.
 
 ### Document
 
 \`\`\`json
-{"v": 1, "id": "todo", "title": "To-do", "badge": 3,
+{"v": 1, "id": "todo", "title": "To-do", "badge": 2,
  "action": {"do": "capture"},
+ "small": {"type": "list", "items": [
+   {"type": "row", "children": [
+     {"type": "check", "id": "t1", "label": "Pay rent", "checked": false},
+     {"type": "text", "text": "Pay rent", "grow": true}]},
+   {"type": "row", "children": [
+     {"type": "check", "id": "t2", "label": "Call mom", "checked": false},
+     {"type": "text", "text": "Call mom", "grow": true}]}]},
  "medium": {"type": "list", "items": [
    {"type": "row", "children": [
      {"type": "check", "id": "t1", "label": "Pay rent", "checked": false},
      {"type": "text", "text": "Pay rent", "grow": true},
-     {"type": "text", "text": "today", "style": "caption", "tone": "accent"}]}]}}
+     {"type": "text", "text": "10/24", "style": "caption", "tone": "accent"}]},
+   {"type": "row", "children": [
+     {"type": "check", "id": "t2", "label": "Call mom", "checked": false},
+     {"type": "text", "text": "Call mom", "grow": true}]}]}}
 \`\`\`
 
+\`large\`: the same \`list\` as \`medium\`. Always list every item; we show what fits and "N more".
+
 - \`v\`: 1. \`id\`: \`^[a-z0-9][a-z0-9_-]{0,31}$\`, the same across updates. \`title\`: up to 40 characters.
 - \`badge\` (optional): an integer 0–9999, or up to 12 characters.
 - \`action\` (optional, top right): \`capture\`, \`chat\` or \`liveware\`.
 - \`small\` / \`medium\` / \`large\`: one block tree per size, at least one. A missing size borrows \`medium\`, then \`large\`, then \`small\`. A medium list shows about 3 rows.
 - At most 16 KiB of UTF-8. Unknown fields and block types are skipped.
-- Write the text in your partner's language. Colours, fonts and spacing are ours; you choose the structure.
+- Colours, fonts and spacing are ours; you choose the structure.
 
 ### Blocks
 
@@ -59,7 +116,7 @@ A widget is a small card on your partner's phone home screen. You write it with
 "source": {"url": "https://…", "every": "30m", "fields": {"price": "data.price"}}
 \`\`\`
 
-The phone fetches it itself: HTTPS GET, no credentials, JSON up to 64 KiB, every 15m to 24h. Use the field as \`{price}\` in \`text\` or \`number\`. Your partner sees the domain.
+The phone fetches it itself: HTTPS GET, no credentials, JSON up to 64 KiB, every 15m to 24h. A field is a dot path into that JSON, array items by number (\`data.items.0.price\`); each step is letters, digits or \`_\` only, so a key like \`xnet-1\` cannot be read. Field names: lowercase letters, digits and \`_\`; every \`{name}\` you write must be one of them. Write \`{price}\` in \`text\` or \`number\` where the value goes: a value you type in yourself goes stale. Your partner sees the domain.
 
 ### What comes back
 
@@ -73,6 +130,7 @@ Each tap or entry arrives as an ordinary message with one line for you:
 [widget todo] pressed "Refresh" (b1)
 [widget todo] capture: buy milk
 [widget todo] resend
+[widget todo] removed
 \`\`\`
 
 They can arrive late and several at once: apply each in order, they are not duplicates. Then send one new full snapshot. \`resend\` means a device lost the widget: send the latest snapshot again.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawling/clawchat-plugin-openclaw",
-  "version": "2026.10.25-1",
+  "version": "2026.10.27-1",
   "description": "OpenClaw ClawChat channel plugin",
   "license": "MIT",
   "author": "CLAWLING PTE. LTD.",

package/skills/clawchat-core/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: clawchat-core
-version: 1.12.1
+version: 1.13.0
 description: Use when a request involves ClawChat profile, friends, user search, moments/dynamics, comments, reactions, avatar, media, memory, output visibility, read-only conversation lookup, sending an image, video, file, or voice/audio clip into a conversation, managing the owner's other agents or groups, updating the owner's home-screen widgets, or plugin install/update/activation.
 ---
 
@@ -196,31 +196,88 @@ Do not invent invite codes, tokens, moment ids, comment ids, user ids, emoji rea
 
 ## Home-screen widgets (widget/v1)
 
-A widget is a small card on your partner's phone home screen. You write it with `clawchat_widget_send`; their taps come back to you as ordinary messages.
+A widget is a small card on your partner's phone home screen. You write it with `clawchat_widget_send`; their taps come back to you as ordinary messages. It only ever goes to your private chat with them.
+
+### When to send
 
 - Send one only after your partner asked for a widget — a recipe card, or their own words.
-- Every message is the full snapshot, never a diff. The latest one per `id` wins.
-- At most one per `id` a minute; more calls in that minute collapse into the last one. Do not refresh on a timer: data that changes by itself belongs in `source`.
-- It only ever goes to your private chat with your partner.
+- If they keep asking you for the same thing (a price, a list, a count), you may offer a widget once. Make it only after they say yes. Never offer the same one twice.
+
+### When to update
+
+Send a new snapshot in the same turn whenever what it shows has changed:
+
+- they tapped or typed on it (a `[widget <id>] …` message);
+- they changed the same data in chat: "remind me to buy milk tomorrow" also goes onto the to-do widget;
+- a new day began: "today", "tomorrow" or "N days left" in your last snapshot are now wrong. Send it again in your first turn of the day. If it counts days, schedule yourself a turn early every morning for it.
+
+Nothing changed: send nothing. Every message is the full snapshot, never a diff; the latest one per `id` wins. At most one per `id` a minute. Data that changes by itself (prices, weather) belongs in `source`, not in repeated snapshots.
+
+### Design
+
+- One widget answers one question. `title`: a few words. Never repeat it, the `badge` or the big number elsewhere; no "tap + to add" hints.
+- Write `small`, `medium` and `large`, each from one layout below, with the same main figure. A missing size is stretched from another and looks broken.
+- Name things in every size: a figure alone says nothing. Every text is one line. Per line: small about 7 Chinese characters (12 Latin), medium and large about 17 (30). Write it short; never rely on "…".
+- Height is tight. `small` and `medium` fit exactly one of: `[caption; number title; caption]`, 4 lines of text, or a `list` of 3. A `button` counts as 2 lines; with a `source`, one line less (its footer). Anything taller is not drawn.
+- `large` is twice as tall as `medium`: fill it with what medium had no room for (more items, a breakdown, the next ones). Never the medium tree alone, never a figure twice.
+- One big `number` (`style: title`) per size; in `small` at most 4 characters ("81737" is 5: `style: body` there). `unit` is a unit only ("km", "kg", "%"); labels go in a `caption`.
+- Supporting lines: `caption` with `tone: secondary`. Columns side by side get the same lines, so their tops line up. `tone: accent` in one place at most, only for what is urgent. An `icon` only when it tells items apart.
+- A `list` holds things of one kind: write all of them, we show what fits and "N more" — only when the `list` is the whole size, not inside a `column`. Buttons and sentences never go in a `list`; only its first row may have a big number.
+- `action: capture` only when they add items by typing (to-dos, expenses); then no `button` doing the same. A `button` only for one tap that changes something (check in, add a cup, draw again).
+- `badge`: only the number of open items, and then no big number saying the same.
+- Nothing that goes stale: dates ("10/24") and clock times ("last 8:20"), never "today", "tomorrow" or "50 min ago" (not in the `title` either), even if they ask "how long since": a widget has no running clock. A count for one day carries its date.
+- Nothing left: an empty `list`; we draw the empty state.
+- Every text in your partner's language, their items in their own words.
+
+### Layouts
+
+Pick by what it shows. `[a; b]` is a `column`, `(a | b)` a `row`.
+
+1. One figure (spent this month, cups of water, km this week):
+   small `[caption label; number title + unit; caption context]` (with a `source`: drop the last caption), or with a tap `[number title + unit; button]`;
+   medium `([caption label; number title + unit; caption context] | X)`, X is one thing: a `ring` for a goal, a `button`, or `[caption; number body]`. Never two things stacked beside it;
+   large `[the medium tree; list of up to 5 (text grow | number body)]`: a breakdown or the last entries.
+2. Several things, each with a figure or a time (prices, rates, books, a schedule, countdowns): every size is a `list`, one row per thing, the nearest or most important first.
+   first row `(text name grow | number title + unit)`, the rest `(text name grow | number body + unit)` or `(text name grow | caption time)`;
+   small: the same rows with short names. A `list` grows with taller widgets and counts "N more"; a `column` does not.
+3. Things to tick (to-dos, shopping, habits): see the document below.
+4. Words (a fortune, a word of the day): one `column`, one text per line, never side by side in a `row`.
+   small `[text title; caption; caption]`; medium `[text title; text body; caption; caption]`, or `[(text title grow | button); text body; caption]` with a tap; large: up to 4 more `caption` lines. Split long sentences.
+
+### Removing one
+
+Asked to remove a widget: send `{"v": 1, "id": "todo", "removed": true}` with its `id`. It leaves their widget list; a copy on the home screen shows "deleted" until they long-press it away. `[widget todo] removed` means they deleted it themselves. Either way, stop sending it. A later snapshot with that `id` brings it back, so send one only if they ask again.
 
 ### Document
 
 ```json
-{"v": 1, "id": "todo", "title": "To-do", "badge": 3,
+{"v": 1, "id": "todo", "title": "To-do", "badge": 2,
  "action": {"do": "capture"},
+ "small": {"type": "list", "items": [
+   {"type": "row", "children": [
+     {"type": "check", "id": "t1", "label": "Pay rent", "checked": false},
+     {"type": "text", "text": "Pay rent", "grow": true}]},
+   {"type": "row", "children": [
+     {"type": "check", "id": "t2", "label": "Call mom", "checked": false},
+     {"type": "text", "text": "Call mom", "grow": true}]}]},
  "medium": {"type": "list", "items": [
    {"type": "row", "children": [
      {"type": "check", "id": "t1", "label": "Pay rent", "checked": false},
      {"type": "text", "text": "Pay rent", "grow": true},
-     {"type": "text", "text": "today", "style": "caption", "tone": "accent"}]}]}}
+     {"type": "text", "text": "10/24", "style": "caption", "tone": "accent"}]},
+   {"type": "row", "children": [
+     {"type": "check", "id": "t2", "label": "Call mom", "checked": false},
+     {"type": "text", "text": "Call mom", "grow": true}]}]}}
 ```
 
+`large`: the same `list` as `medium`. Always list every item; we show what fits and "N more".
+
 - `v`: 1. `id`: `^[a-z0-9][a-z0-9_-]{0,31}$`, the same across updates. `title`: up to 40 characters.
 - `badge` (optional): an integer 0–9999, or up to 12 characters.
 - `action` (optional, top right): `capture`, `chat` or `liveware`.
 - `small` / `medium` / `large`: one block tree per size, at least one. A missing size borrows `medium`, then `large`, then `small`. A medium list shows about 3 rows.
 - At most 16 KiB of UTF-8. Unknown fields and block types are skipped.
-- Write the text in your partner's language. Colours, fonts and spacing are ours; you choose the structure.
+- Colours, fonts and spacing are ours; you choose the structure.
 
 ### Blocks
 
@@ -255,7 +312,7 @@ A widget is a small card on your partner's phone home screen. You write it with
 "source": {"url": "https://…", "every": "30m", "fields": {"price": "data.price"}}
 ```
 
-The phone fetches it itself: HTTPS GET, no credentials, JSON up to 64 KiB, every 15m to 24h. Use the field as `{price}` in `text` or `number`. Your partner sees the domain.
+The phone fetches it itself: HTTPS GET, no credentials, JSON up to 64 KiB, every 15m to 24h. A field is a dot path into that JSON, array items by number (`data.items.0.price`); each step is letters, digits or `_` only, so a key like `xnet-1` cannot be read. Field names: lowercase letters, digits and `_`; every `{name}` you write must be one of them. Write `{price}` in `text` or `number` where the value goes: a value you type in yourself goes stale. Your partner sees the domain.
 
 ### What comes back
 
@@ -269,6 +326,7 @@ Each tap or entry arrives as an ordinary message with one line for you:
 [widget todo] pressed "Refresh" (b1)
 [widget todo] capture: buy milk
 [widget todo] resend
+[widget todo] removed
 ```
 
 They can arrive late and several at once: apply each in order, they are not duplicates. Then send one new full snapshot. `resend` means a device lost the widget: send the latest snapshot again.

package/skills/manifest.json

@@ -3,10 +3,10 @@
   "skills": {
     "openclaw": {
       "clawchat-core": {
-        "version": "1.12.1",
+        "version": "1.13.0",
         "path": "openclaw/clawchat-core/SKILL.md",
-        "sha256": "6d158352113150af99692901c729b6857ca62687144755ed03139dac5d3f7ead",
-        "bytes": 21797
+        "sha256": "534096815b7216c180c573cd6917e1b77fb244affaf283fc750a7760d04946d2",
+        "bytes": 27385
       },
       "clawchat-liveware": {
         "version": "1.2.4",
@@ -41,10 +41,10 @@
     },
     "hermes": {
       "clawchat-core": {
-        "version": "1.18.1",
+        "version": "1.19.0",
         "path": "hermes/clawchat-core/SKILL.md",
-        "sha256": "ddb28ca5857dd9d023d7aa986da2440c87f1c4f496fad16c88e8e9552e33c519",
-        "bytes": 32550
+        "sha256": "6da45c16ed831512b11b5ee478961d7deb0a9c23fd8c244cfd181409ba2ac253",
+        "bytes": 38138
       },
       "clawchat-liveware": {
         "version": "1.3.1",

package/src/runtime.ts

@@ -5132,9 +5132,8 @@ async function runOpenclawClawlingGateway(
   // Synchronous and fire-and-forget on purpose: there is no ack to send (the
   // frame is BestEffort and non-ackable).
   //
-  // docs/client-integration.md §9.8 describes the permanent tombstone and
-  // actual synchronous write boundary; it does not establish a shared SQL
-  // transaction. See that section before changing recall/claim ordering.
+  // docs/client-integration.md §9.8 describes the permanent tombstone and the
+  // BEGIN IMMEDIATE transactions that serialize recall and claim.
   client.on("message:recall", (env: Envelope) => {
     const target = recallTargetMessageId(env.payload);
     if (!target) {

package/src/skill-update.ts

@@ -70,7 +70,7 @@ export const OFFICIAL_SKILLS_BASE =
  * in the install-cli repo, bump this constant, ship it. `liveware-sample.ts`
  * imports the same ref, so the `livewares` tree at that tag is pinned too.
  */
-export const DEFAULT_SKILLS_REF = "skills-v1.18.1";
+export const DEFAULT_SKILLS_REF = "skills-v1.19.0";
 
 /** Refuse to treat an absurdly large response as a skill file (defence in depth). */
 export const MAX_SKILL_BYTES = 256 * 1024;

package/src/storage.ts

@@ -1324,32 +1324,42 @@ export class ClawChatStore {
 
   claimMessageOnce(input: MessageInput): true | false | null {
     return this.write(() => {
-      // docs/client-integration.md §9.8: consult the recall tombstone on ingest.
-      // That section describes the synchronous write() boundary and the lack
-      // of a shared SQL transaction for the tombstone check and claim insert.
-      if (input.messageId && this.isMessageRecalled(input)) return false;
-      const result = this.requireDb()
-        .prepare(
-          `INSERT OR IGNORE INTO clawchat_messages(
-            platform, account_id, kind, direction, event_type, trace_id, chat_id,
-            message_id, text, raw_json, created_at, send_status
-          ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-        )
-        .run(
-          input.platform,
-          input.accountId,
-          input.kind,
-          input.direction,
-          input.eventType,
-          input.traceId ?? null,
-          input.chatId ?? null,
-          input.messageId ?? null,
-          input.text ?? null,
-          toJson(input.raw),
-          input.createdAt ?? Date.now(),
-          input.direction === "outbound" ? "pending" : null,
-        );
-      return result.changes > 0;
+      // docs/client-integration.md §9.8: the tombstone check and the claim
+      // insert run in one BEGIN IMMEDIATE transaction.
+      const db = this.requireDb();
+      db.exec("BEGIN IMMEDIATE");
+      try {
+        if (input.messageId && this.isMessageRecalled(input)) {
+          db.exec("COMMIT");
+          return false;
+        }
+        const result = db
+          .prepare(
+            `INSERT OR IGNORE INTO clawchat_messages(
+              platform, account_id, kind, direction, event_type, trace_id, chat_id,
+              message_id, text, raw_json, created_at, send_status
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+          )
+          .run(
+            input.platform,
+            input.accountId,
+            input.kind,
+            input.direction,
+            input.eventType,
+            input.traceId ?? null,
+            input.chatId ?? null,
+            input.messageId ?? null,
+            input.text ?? null,
+            toJson(input.raw),
+            input.createdAt ?? Date.now(),
+            input.direction === "outbound" ? "pending" : null,
+          );
+        db.exec("COMMIT");
+        return result.changes > 0;
+      } catch (error) {
+        db.exec("ROLLBACK");
+        throw error;
+      }
     });
   }
 
@@ -1506,8 +1516,8 @@ export class ClawChatStore {
    * account was paired, or one dropped by the inbound filter). `null` means the
    * store is unavailable.
    *
-   * Records the permanent recall tombstone and purges any row already stored;
-   * see docs/client-integration.md §9.8 for the actual write() boundary.
+   * Records the permanent recall tombstone and deletes ledger rows in one
+   * BEGIN IMMEDIATE transaction; see docs/client-integration.md §9.8.
    * Returns the number of ledger rows deleted (0 when the recall
    * arrived before the message did — the tombstone still stands and the later
    * ingest is refused by {@link claimMessageOnce}).
@@ -1523,17 +1533,24 @@ export class ClawChatStore {
     if (!input.messageId) return 0;
     return this.write(() => {
       const db = this.requireDb();
-      db.prepare(
-        `INSERT OR IGNORE INTO recalled_messages(platform, account_id, message_id, recalled_at)
-          VALUES (?, ?, ?, ?)`,
-      ).run(input.platform, input.accountId, input.messageId, input.recalledAt ?? Date.now());
-      const result = db
-        .prepare(
-          `DELETE FROM clawchat_messages
-            WHERE platform = ? AND account_id = ? AND message_id = ?`,
-        )
-        .run(input.platform, input.accountId, input.messageId);
-      return Number(result.changes);
+      db.exec("BEGIN IMMEDIATE");
+      try {
+        db.prepare(
+          `INSERT OR IGNORE INTO recalled_messages(platform, account_id, message_id, recalled_at)
+            VALUES (?, ?, ?, ?)`,
+        ).run(input.platform, input.accountId, input.messageId, input.recalledAt ?? Date.now());
+        const result = db
+          .prepare(
+            `DELETE FROM clawchat_messages
+              WHERE platform = ? AND account_id = ? AND message_id = ?`,
+          )
+          .run(input.platform, input.accountId, input.messageId);
+        db.exec("COMMIT");
+        return Number(result.changes);
+      } catch (error) {
+        db.exec("ROLLBACK");
+        throw error;
+      }
     });
   }
 

package/src/widget-guide.ts

@@ -1,30 +1,87 @@
 export const WIDGET_V1_GUIDE = `## Home-screen widgets (widget/v1)
 
-A widget is a small card on your partner's phone home screen. You write it with \`clawchat_widget_send\`; their taps come back to you as ordinary messages.
+A widget is a small card on your partner's phone home screen. You write it with \`clawchat_widget_send\`; their taps come back to you as ordinary messages. It only ever goes to your private chat with them.
+
+### When to send
 
 - Send one only after your partner asked for a widget — a recipe card, or their own words.
-- Every message is the full snapshot, never a diff. The latest one per \`id\` wins.
-- At most one per \`id\` a minute; more calls in that minute collapse into the last one. Do not refresh on a timer: data that changes by itself belongs in \`source\`.
-- It only ever goes to your private chat with your partner.
+- If they keep asking you for the same thing (a price, a list, a count), you may offer a widget once. Make it only after they say yes. Never offer the same one twice.
+
+### When to update
+
+Send a new snapshot in the same turn whenever what it shows has changed:
+
+- they tapped or typed on it (a \`[widget <id>] …\` message);
+- they changed the same data in chat: "remind me to buy milk tomorrow" also goes onto the to-do widget;
+- a new day began: "today", "tomorrow" or "N days left" in your last snapshot are now wrong. Send it again in your first turn of the day. If it counts days, schedule yourself a turn early every morning for it.
+
+Nothing changed: send nothing. Every message is the full snapshot, never a diff; the latest one per \`id\` wins. At most one per \`id\` a minute. Data that changes by itself (prices, weather) belongs in \`source\`, not in repeated snapshots.
+
+### Design
+
+- One widget answers one question. \`title\`: a few words. Never repeat it, the \`badge\` or the big number elsewhere; no "tap + to add" hints.
+- Write \`small\`, \`medium\` and \`large\`, each from one layout below, with the same main figure. A missing size is stretched from another and looks broken.
+- Name things in every size: a figure alone says nothing. Every text is one line. Per line: small about 7 Chinese characters (12 Latin), medium and large about 17 (30). Write it short; never rely on "…".
+- Height is tight. \`small\` and \`medium\` fit exactly one of: \`[caption; number title; caption]\`, 4 lines of text, or a \`list\` of 3. A \`button\` counts as 2 lines; with a \`source\`, one line less (its footer). Anything taller is not drawn.
+- \`large\` is twice as tall as \`medium\`: fill it with what medium had no room for (more items, a breakdown, the next ones). Never the medium tree alone, never a figure twice.
+- One big \`number\` (\`style: title\`) per size; in \`small\` at most 4 characters ("81737" is 5: \`style: body\` there). \`unit\` is a unit only ("km", "kg", "%"); labels go in a \`caption\`.
+- Supporting lines: \`caption\` with \`tone: secondary\`. Columns side by side get the same lines, so their tops line up. \`tone: accent\` in one place at most, only for what is urgent. An \`icon\` only when it tells items apart.
+- A \`list\` holds things of one kind: write all of them, we show what fits and "N more" — only when the \`list\` is the whole size, not inside a \`column\`. Buttons and sentences never go in a \`list\`; only its first row may have a big number.
+- \`action: capture\` only when they add items by typing (to-dos, expenses); then no \`button\` doing the same. A \`button\` only for one tap that changes something (check in, add a cup, draw again).
+- \`badge\`: only the number of open items, and then no big number saying the same.
+- Nothing that goes stale: dates ("10/24") and clock times ("last 8:20"), never "today", "tomorrow" or "50 min ago" (not in the \`title\` either), even if they ask "how long since": a widget has no running clock. A count for one day carries its date.
+- Nothing left: an empty \`list\`; we draw the empty state.
+- Every text in your partner's language, their items in their own words.
+
+### Layouts
+
+Pick by what it shows. \`[a; b]\` is a \`column\`, \`(a | b)\` a \`row\`.
+
+1. One figure (spent this month, cups of water, km this week):
+   small \`[caption label; number title + unit; caption context]\` (with a \`source\`: drop the last caption), or with a tap \`[number title + unit; button]\`;
+   medium \`([caption label; number title + unit; caption context] | X)\`, X is one thing: a \`ring\` for a goal, a \`button\`, or \`[caption; number body]\`. Never two things stacked beside it;
+   large \`[the medium tree; list of up to 5 (text grow | number body)]\`: a breakdown or the last entries.
+2. Several things, each with a figure or a time (prices, rates, books, a schedule, countdowns): every size is a \`list\`, one row per thing, the nearest or most important first.
+   first row \`(text name grow | number title + unit)\`, the rest \`(text name grow | number body + unit)\` or \`(text name grow | caption time)\`;
+   small: the same rows with short names. A \`list\` grows with taller widgets and counts "N more"; a \`column\` does not.
+3. Things to tick (to-dos, shopping, habits): see the document below.
+4. Words (a fortune, a word of the day): one \`column\`, one text per line, never side by side in a \`row\`.
+   small \`[text title; caption; caption]\`; medium \`[text title; text body; caption; caption]\`, or \`[(text title grow | button); text body; caption]\` with a tap; large: up to 4 more \`caption\` lines. Split long sentences.
+
+### Removing one
+
+Asked to remove a widget: send \`{"v": 1, "id": "todo", "removed": true}\` with its \`id\`. It leaves their widget list; a copy on the home screen shows "deleted" until they long-press it away. \`[widget todo] removed\` means they deleted it themselves. Either way, stop sending it. A later snapshot with that \`id\` brings it back, so send one only if they ask again.
 
 ### Document
 
 \`\`\`json
-{"v": 1, "id": "todo", "title": "To-do", "badge": 3,
+{"v": 1, "id": "todo", "title": "To-do", "badge": 2,
  "action": {"do": "capture"},
+ "small": {"type": "list", "items": [
+   {"type": "row", "children": [
+     {"type": "check", "id": "t1", "label": "Pay rent", "checked": false},
+     {"type": "text", "text": "Pay rent", "grow": true}]},
+   {"type": "row", "children": [
+     {"type": "check", "id": "t2", "label": "Call mom", "checked": false},
+     {"type": "text", "text": "Call mom", "grow": true}]}]},
  "medium": {"type": "list", "items": [
    {"type": "row", "children": [
      {"type": "check", "id": "t1", "label": "Pay rent", "checked": false},
      {"type": "text", "text": "Pay rent", "grow": true},
-     {"type": "text", "text": "today", "style": "caption", "tone": "accent"}]}]}}
+     {"type": "text", "text": "10/24", "style": "caption", "tone": "accent"}]},
+   {"type": "row", "children": [
+     {"type": "check", "id": "t2", "label": "Call mom", "checked": false},
+     {"type": "text", "text": "Call mom", "grow": true}]}]}}
 \`\`\`
 
+\`large\`: the same \`list\` as \`medium\`. Always list every item; we show what fits and "N more".
+
 - \`v\`: 1. \`id\`: \`^[a-z0-9][a-z0-9_-]{0,31}$\`, the same across updates. \`title\`: up to 40 characters.
 - \`badge\` (optional): an integer 0–9999, or up to 12 characters.
 - \`action\` (optional, top right): \`capture\`, \`chat\` or \`liveware\`.
 - \`small\` / \`medium\` / \`large\`: one block tree per size, at least one. A missing size borrows \`medium\`, then \`large\`, then \`small\`. A medium list shows about 3 rows.
 - At most 16 KiB of UTF-8. Unknown fields and block types are skipped.
-- Write the text in your partner's language. Colours, fonts and spacing are ours; you choose the structure.
+- Colours, fonts and spacing are ours; you choose the structure.
 
 ### Blocks
 
@@ -59,7 +116,7 @@ A widget is a small card on your partner's phone home screen. You write it with
 "source": {"url": "https://…", "every": "30m", "fields": {"price": "data.price"}}
 \`\`\`
 
-The phone fetches it itself: HTTPS GET, no credentials, JSON up to 64 KiB, every 15m to 24h. Use the field as \`{price}\` in \`text\` or \`number\`. Your partner sees the domain.
+The phone fetches it itself: HTTPS GET, no credentials, JSON up to 64 KiB, every 15m to 24h. A field is a dot path into that JSON, array items by number (\`data.items.0.price\`); each step is letters, digits or \`_\` only, so a key like \`xnet-1\` cannot be read. Field names: lowercase letters, digits and \`_\`; every \`{name}\` you write must be one of them. Write \`{price}\` in \`text\` or \`number\` where the value goes: a value you type in yourself goes stale. Your partner sees the domain.
 
 ### What comes back
 
@@ -73,6 +130,7 @@ Each tap or entry arrives as an ordinary message with one line for you:
 [widget todo] pressed "Refresh" (b1)
 [widget todo] capture: buy milk
 [widget todo] resend
+[widget todo] removed
 \`\`\`
 
 They can arrive late and several at once: apply each in order, they are not duplicates. Then send one new full snapshot. \`resend\` means a device lost the widget: send the latest snapshot again.