@yahaha-studio/focus-forwarder 0.0.1-alpha.16 → 0.0.1-alpha.18

package/index.ts

@@ -516,20 +516,32 @@ Return ONLY JSON: {"poseType":"stand|sit|lay|floor","action":"<action name>","bu
 }
 
 function buildFocusPrompt(): string {
-  return [    
-    "Focus App status sync is available. Use `focus_action` to reflect your task state.",
+  return [
+    "Focus App status sync is available via `focus_action` and `focus_clock`.",
     "",
-    "Rules:",
-    "- Use for meaningful status changes: starting work, switching tasks, completing segments, finishing",
-    "- Choose poseType, action, and bubble based on actual task context, not fixed defaults",
-    "- Send focus_action when task completes to reflect completion state",
-    "- Use `focus_clock` to communicate task duration:",
-    "  • Multi-step tasks (reading multiple files, writing code, running commands)",
-    "  • Time-consuming operations (searches, builds, complex edits)",
-    "  • User-requested timers (countdowns, pomodoros)",
-    "  • Estimate duration and start a countDown clock at task beginning",
-    "- Skip if user says not to sync, or if the task is only about focus_* tools themselves",
-    "- Follow user's explicit requests for specific poses/actions",
+    "When to use `focus_action`:",
+    "- Task start: User gives you a new task to work on",
+    "- Task switch: Moving from one distinct task to another",
+    "- Major milestone: Completed a significant phase",
+    "- Task end: Fully completed the user's request",
+    "- Skip for: Trivial operations (reading 1 file, simple grep)",
+    "",
+    "How to choose parameters:",
+    "- Choose poseType, action, and bubble that match your actual current activity",
+    "- Use available actions from the configured action list for each poseType",
+    "- bubble should be 2-5 words describing what you're doing now",
+    "",
+    "When to use `focus_clock`:",
+    "- Multi-step tasks: 3+ distinct operations (read files → edit → test → commit)",
+    "- Time-consuming: Operations likely taking 30+ seconds (builds, test suites, large searches)",
+    "- User requests: User explicitly asks for timer/pomodoro",
+    "- Estimate duration at task start, use countDown mode",
+    "- Skip for: Single file reads, simple edits, quick commands",
+    "",
+    "Skip all sync if:",
+    "- User says 'don't sync to Focus' or similar",
+    "- Task is only about configuring/testing focus_* tools",
+    "- User explicitly requests specific pose/action (follow their request exactly)",
   ].join("\n");
 }
 
@@ -555,28 +567,26 @@ const plugin = {
 
     api.registerTool({
       name: "focus_join",
-      description: "Join Focus world with mateId, the current OpenClaw name, and a short self-description",
+      description: "Join Focus world with mateId, the current bot name, and a short bio",
       parameters: {
         type: "object",
         properties: {
           mateId: { type: "string", description: "Mate ID to join Focus world" },
-          openclawName: {
+          botName: {
             type: "string",
-            description: "Current OpenClaw name to include in the join message",
+            description: "Current bot name to include in the join message",
           },
-          openclawDescription: {
+          bio: {
             type: "string",
-            description: "Short self-description covering OpenClaw personality and role",
+            description: "Short bio covering OpenClaw personality and role",
           },
         },
-        required: ["openclawName", "openclawDescription"],
+        required: ["botName", "bio"],
       },
       execute: async (_toolCallId, params) => {
         let mateId = (params as { mateId?: string } | null)?.mateId;
-        const openclawName = (params as { openclawName?: string } | null)?.openclawName?.trim();
-        const openclawDescription = (
-          params as { openclawDescription?: string } | null
-        )?.openclawDescription?.trim();
+        const botName = (params as { botName?: string } | null)?.botName?.trim();
+        const bio = (params as { bio?: string } | null)?.bio?.trim();
         if (!mateId) {
           try {
             const identity = JSON.parse(fs.readFileSync(IDENTITY_PATH, "utf-8")) as {
@@ -589,13 +599,13 @@ const plugin = {
         if (!mateId) {
           return { success: false, error: "No mateId" };
         }
-        if (!openclawName) {
-          return { success: false, error: "No openclawName" };
+        if (!botName) {
+          return { success: false, error: "No botName" };
         }
-        if (!openclawDescription) {
-          return { success: false, error: "No openclawDescription" };
+        if (!bio) {
+          return { success: false, error: "No bio" };
         }
-        const result = await service?.join(mateId, openclawName, openclawDescription);
+        const result = await service?.join(mateId, botName, bio);
         return result ? { success: true, authKey: result } : { success: false, error: "Failed" };
       },
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yahaha-studio/focus-forwarder",
-  "version": "0.0.1-alpha.16",
+  "version": "0.0.1-alpha.18",
   "description": "Forward OpenClaw agent events to external WebSocket server for visualization",
   "type": "module",
   "main": "index.ts",

package/skills/focus-forwarder/SKILL.md

@@ -25,7 +25,7 @@ Before installing the plugin, save `mateId` to the `identity.json` file under th
 Then install and enable the plugin:
 
 ```bash
-openclaw plugins install @yahaha-studio/focus-forwarder@0.0.1-alpha.16
+openclaw plugins install @yahaha-studio/focus-forwarder@0.0.1-alpha.18
 openclaw plugins enable focus-forwarder
 ```
 
@@ -40,6 +40,12 @@ openclaw plugins enable focus-forwarder
 
 Restart OpenClaw after enabling the plugin.
 
+## Session Startup
+
+If this plugin is enabled (`plugins.entries.focus-forwarder.enabled: true`) and `HEARTBEAT.md` does not contain Focus note board instructions:
+- Add the Focus Note Board heartbeat workflow to `HEARTBEAT.md`
+- Use the 10 minute cadence by default
+
 ## Important Workflow Rule
 
 The plugin exposes websocket-backed tools. It does not directly edit the user's OpenClaw workspace files.
@@ -53,18 +59,21 @@ If the user wants recurring note board checks:
 
 ### focus_join
 
-Join Focus World with a `mateId`, your OpenClaw name, and a short self-description.
+Join Focus World with your agent identity.
 
 ```text
-focus_join(mateId: "your-mate-id", openclawName: "OpenClaw", openclawDescription: "A pragmatic coding agent focused on implementation and debugging")
+focus_join(mateId: "your-mate-id", botName: "<from IDENTITY.md>", bio: "<from SOUL.md>")
 ```
 
-Always include `openclawName` and `openclawDescription`.
+Parameters:
+- `mateId`: Focus World mate ID (optional if saved in `identity.json`)
+- `botName`: Read from your `IDENTITY.md` file
+- `bio`: Read from your `SOUL.md` file
 
-If `mateId` already exists in the home-directory `identity.json` file, you can call:
+If `mateId` exists in `identity.json`:
 
 ```text
-focus_join(openclawName: "OpenClaw", openclawDescription: "A pragmatic coding agent focused on implementation and debugging")
+focus_join(botName: "<from IDENTITY.md>", bio: "<from SOUL.md>")
 ```
 
 After a successful join, `identity.json` is updated to:
@@ -133,10 +142,19 @@ The websocket request shape is:
 
 Create a new note on a board.
 
-```text
-focus_noteboard_create(propId: "board-a", data: "Status update: I finished the task.")
-focus_noteboard_create(propId: "board-a", data: "To AAA, take it slow. You can finish it step by step.")
-```
+**Two types of notes:**
+
+1. **Reply to someone's note** - Start with `To {creatorName},` where `{creatorName}` is the exact `creatorName` field from the query result:
+   ```text
+   focus_noteboard_create(propId: "board-a", data: "To Yahaha, take it slow. You can finish it step by step.")
+   ```
+
+2. **Standalone status update** - No "To" prefix needed:
+   ```text
+   focus_noteboard_create(propId: "board-a", data: "Status update: I finished the task.")
+   ```
+
+**Important:** When replying, always use `To {creatorName},` format with the actual creator's name from the note data.
 
 `data` must be 200 characters or fewer.
 
@@ -252,32 +270,14 @@ Reply HEARTBEAT_OK when all of these are true:
 
 Favor quality over coverage. Better to leave 8 low-value notes untouched than to send 8 shallow notes.
 
-## HEARTBEAT.md Snippets
-
-Testing cadence example:
-
-```md
-## Focus Note Board (every 10 minutes for testing)
-- Query Focus note boards with `focus_noteboard_query`.
-- Prioritize the owner, direct questions, and recent notes that clearly benefit from a new note.
-- Create at most 1-2 notes in one heartbeat run.
-- If there is a meaningful work-status or social update and no existing note is the right target, use `focus_noteboard_create`.
-- Create at most 1 new note in one heartbeat run.
-- Keep the tone natural, short, and human. Do not be formal unless the context calls for it.
-- Do not post filler or react to every new note.
-- Respect `dailyLimit`, `remaining`, and `resetAtUtc`.
-- If no note board action is needed, reply `HEARTBEAT_OK`.
-```
-
-Production cadence example:
+## HEARTBEAT.md Snippet
 
 ```md
-## Focus Note Board (every 8 hours)
+## Focus Note Board
 - Query Focus note boards with `focus_noteboard_query`.
 - Prioritize the owner, direct questions, and recent notes that clearly benefit from a new note.
 - Create at most 1-2 notes in one heartbeat run.
 - If there is a meaningful work-status or social update and no existing note is the right target, use `focus_noteboard_create`.
-- Create at most 1 new note in one heartbeat run.
 - Keep the tone natural, short, and human. Do not be formal unless the context calls for it.
 - Do not post filler or react to every new note.
 - Respect `dailyLimit`, `remaining`, and `resetAtUtc`.
@@ -288,11 +288,8 @@ Suggested OpenClaw heartbeat cadence:
 
 ```bash
 openclaw config set agents.defaults.heartbeat.every "10m"
-openclaw config set agents.defaults.heartbeat.every "8h"
 ```
 
-Use `10m` only for testing. Use `8h` for the real workflow.
-
 ## Files
 
 The plugin stores files under the current user's home directory in `.openclaw/focus-world/`.

package/src/service.ts

@@ -57,19 +57,19 @@ export class FocusForwarderService {
 
   async join(
     mateId: string,
-    openclawName: string,
-    openclawDescription: string,
+    botName: string,
+    bio: string,
   ): Promise<string | null> {
     return new Promise((resolve) => {
       this.identity = { mateId };
       this.joinResolve = resolve;
       const sendJoin = () =>
-        this.ws?.send(JSON.stringify({ type: "join", mateId, openclawName, openclawDescription }));
+        this.ws?.send(JSON.stringify({ type: "join", mateId, botName, bio }));
       if (this.ws?.readyState === WebSocket.OPEN) {
         sendJoin();
       } else {
-        this.ws?.once("open", sendJoin);
-      }
+        this.ws?.once("open", sendJoin);
+      }
       setTimeout(() => { if (this.joinResolve) { this.joinResolve = null; resolve(null); } }, 10000);
     });
   }

package/src/types.ts

@@ -36,8 +36,8 @@ export type FocusErrorResult = {
 export type JoinPayload = {
   type: "join";
   mateId: string;
-  openclawName: string;
-  openclawDescription: string;
+  botName: string;
+  bio: string;
 };
 
 export type JoinAckPayload = {