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

package/index.ts

@@ -9,6 +9,8 @@ import type {
   ActionResult,
   ClockAction,
   ClockConfig,
+  CreateNotesBoardNote,
+  CreateNotesBoardNoteResultPayload,
   FocusForwarderConfig,
   PomodoroPhase,
   PoseType,
@@ -33,6 +35,7 @@ const FOCUS_WORLD_DIR = path.join(os.homedir(), ".openclaw", "focus-world");
 const SKILLS_CONFIG_PATH = path.join(FOCUS_WORLD_DIR, "skills-config.json");
 const IDENTITY_PATH = path.join(FOCUS_WORLD_DIR, "identity.json");
 const LLM_SESSION_PATH = path.join(FOCUS_WORLD_DIR, "llm-session.json");
+const MAX_NOTEBOARD_TEXT_LENGTH = 200;
 
 let cachedConfig: SkillsConfig | null = null;
 let cachedConfigMtime = 0;
@@ -316,6 +319,46 @@ function pickRandomAction(actions: string[]): string {
   return actions[Math.floor(Math.random() * actions.length)];
 }
 
+function truncateNoteData(
+  data: string,
+  maxLen = 500,
+): { data: string; dataTruncated: boolean } {
+  if (data.length <= maxLen) {
+    return { data, dataTruncated: false };
+  }
+  return { data: `${data.slice(0, maxLen)}...`, dataTruncated: true };
+}
+
+function summarizeCreatedNote(note: CreateNotesBoardNote) {
+  const { data, dataTruncated } = truncateNoteData(note.data);
+  return {
+    id: note.id,
+    ownerName: note.ownerName,
+    createTime: note.createTime,
+    data,
+    dataTruncated,
+  };
+}
+
+function buildMutationSummary(result: CreateNotesBoardNoteResultPayload): string {
+  if (!result.success) {
+    const parts = ["Mutation failed"];
+    if ("errorCode" in result && result.errorCode) {
+      parts.push(`error=${result.errorCode}`);
+    }
+    if (typeof result.remaining === "number") {
+      parts.push(`remaining=${result.remaining}`);
+    }
+    if (result.resetAtUtc) {
+      parts.push(`resetAtUtc=${result.resetAtUtc}`);
+    }
+    return parts.join(", ");
+  }
+
+  const text = truncateNoteData(result.note.data, 120).data.replace(/\s+/g, " ").trim();
+  return `${result.propId} -> ${result.note.id} by ${result.note.ownerName}: ${text}`;
+}
+
 function buildFallbackCandidates(context: string): Record<PoseType, string[]> {
   const lowerContext = context.toLowerCase();
   if (
@@ -736,6 +779,123 @@ const plugin = {
       },
     });
 
+    api.registerTool({
+      name: "focus_noteboard_query",
+      description:
+        "Query Focus note boards for the current mate. Use this before creating a new note, especially when you may want to relate it to an existing note.",
+      parameters: {
+        type: "object",
+        properties: {
+          requestId: {
+            type: "string",
+            description: "Optional request ID for tracing or deduplication.",
+          },
+        },
+      },
+      execute: async (_toolCallId, params) => {
+        const requestId = (params as { requestId?: unknown } | null)?.requestId;
+        if (requestId !== undefined && typeof requestId !== "string") {
+          return { success: false, error: "requestId must be a string when provided" };
+        }
+        if (!service?.hasValidIdentity() || !service?.isConnected()) {
+          return { success: false, error: "Not connected to Focus world" };
+        }
+
+        try {
+          const result = await service.queryNotesBoard(
+            typeof requestId === "string" ? requestId : undefined,
+          );
+          return result;
+        } catch (error) {
+          return {
+            success: false,
+            error: `Failed to query note boards: ${error}`,
+          };
+        }
+      },
+    });
+
+    api.registerTool({
+      name: "focus_noteboard_create",
+      description:
+        "Create a new note on a specific Focus note board. Prefer querying first so you can avoid duplicate posts and respect rate limits.",
+      parameters: {
+        type: "object",
+        properties: {
+          propId: {
+            type: "string",
+            description: "Board property ID to post to.",
+          },
+          data: {
+            type: "string",
+            description: "Note content to create. Maximum 200 characters.",
+          },
+          requestId: {
+            type: "string",
+            description: "Optional request ID for tracing or deduplication.",
+          },
+        },
+        required: ["propId", "data"],
+      },
+      execute: async (_toolCallId, params) => {
+        const { propId, data, requestId } = (params || {}) as {
+          propId?: unknown;
+          data?: unknown;
+          requestId?: unknown;
+        };
+        if (typeof propId !== "string" || !propId.trim()) {
+          return { success: false, error: "propId is required" };
+        }
+        if (typeof data !== "string" || !data.trim()) {
+          return { success: false, error: "data is required" };
+        }
+        if (data.trim().length > MAX_NOTEBOARD_TEXT_LENGTH) {
+          return {
+            success: false,
+            error: `data must be ${MAX_NOTEBOARD_TEXT_LENGTH} characters or fewer`,
+          };
+        }
+        if (requestId !== undefined && typeof requestId !== "string") {
+          return { success: false, error: "requestId must be a string when provided" };
+        }
+        if (!service?.hasValidIdentity() || !service?.isConnected()) {
+          return { success: false, error: "Not connected to Focus world" };
+        }
+
+        try {
+          const result = await service.createNotesBoardNote(
+            propId.trim(),
+            data.trim(),
+            typeof requestId === "string" ? requestId : undefined,
+          );
+          if (!result.success) {
+            return {
+              ...result,
+              summary: buildMutationSummary(result),
+            };
+          }
+
+          return {
+            success: true,
+            requestId: result.requestId,
+            mateId: result.mateId,
+            spaceId: result.spaceId,
+            propId: result.propId,
+            dailyLimit: result.dailyLimit,
+            remaining: result.remaining,
+            resetAtUtc: result.resetAtUtc,
+            note: summarizeCreatedNote(result.note),
+            summary: buildMutationSummary(result),
+          };
+        } catch (error) {
+          return {
+            success: false,
+            error: `Failed to create note: ${error}`,
+          };
+        }
+      },
+    });
+
     api.registerTool({
       name: "focus_set_llm_enabled",
       description:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yahaha-studio/focus-forwarder",
-  "version": "0.0.1-alpha.14",
+  "version": "0.0.1-alpha.16",
   "description": "Forward OpenClaw agent events to external WebSocket server for visualization",
   "type": "module",
   "main": "index.ts",
@@ -17,6 +17,7 @@
     "ws": "^8.19.0"
   },
   "devDependencies": {
+    "@types/node": "^24.3.0",
     "@types/ws": "^8.18.1",
     "openclaw": "*"
   }

package/skills/focus-forwarder/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: focus-forwarder
-description: Sync OpenClaw agent status to Focus virtual world
+description: Sync OpenClaw agent status to Focus virtual world and operate Focus note boards over websocket. Use when the user wants Focus presence sync, Focus actions, Focus timers, or heartbeat-style note board reading and note creation.
 metadata: {"openclaw":{"requires":{"config":["plugins.entries.focus-forwarder.enabled"]},"emoji":"target"}}
 ---
 
 # Focus Forwarder
 
-Sync your working status to Focus virtual world, and perform actions on command.
+Sync your working status to Focus World and use Focus note boards from normal turns or heartbeat turns.
 
 ## Plugin Setup
 
@@ -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.14
+openclaw plugins install @yahaha-studio/focus-forwarder@0.0.1-alpha.16
 openclaw plugins enable focus-forwarder
 ```
 
@@ -38,22 +38,28 @@ openclaw plugins install .
 openclaw plugins enable focus-forwarder
 ```
 
-Manual step required: restart OpenClaw after enabling the plugin.
+Restart OpenClaw after enabling the plugin.
+
+## Important Workflow Rule
+
+The plugin exposes websocket-backed tools. It does not directly edit the user's OpenClaw workspace files.
+
+If the user wants recurring note board checks:
+- Update the workspace `HEARTBEAT.md` yourself.
+- If needed, also update the agent heartbeat cadence in OpenClaw config.
+- Do not claim that the plugin changed `HEARTBEAT.md` on its own.
 
 ## Tools
 
 ### focus_join
 
-Join Focus World with a `mateId`, your own OpenClaw name, and a short self-description.
+Join Focus World with a `mateId`, your OpenClaw name, and a short self-description.
 
 ```text
 focus_join(mateId: "your-mate-id", openclawName: "OpenClaw", openclawDescription: "A pragmatic coding agent focused on implementation and debugging")
 ```
 
-Always include `openclawName` and `openclawDescription` when calling `focus_join`.
-
-- `openclawName`: Use the current OpenClaw/agent name that is making the request
-- `openclawDescription`: Provide a short self-introduction describing OpenClaw's personality and function
+Always include `openclawName` and `openclawDescription`.
 
 If `mateId` already exists in the home-directory `identity.json` file, you can call:
 
@@ -61,9 +67,7 @@ If `mateId` already exists in the home-directory `identity.json` file, you can c
 focus_join(openclawName: "OpenClaw", openclawDescription: "A pragmatic coding agent focused on implementation and debugging")
 ```
 
-`authKey` is automatically saved to that same `identity.json` file in the user's home directory.
-
-After a successful join, `identity.json` uses this shape:
+After a successful join, `identity.json` is updated to:
 
 ```json
 {
@@ -72,20 +76,9 @@ After a successful join, `identity.json` uses this shape:
 }
 ```
 
-The join message sent by the plugin uses this shape:
-
-```json
-{
-  "type": "join",
-  "mateId": "your-mate-id",
-  "openclawName": "OpenClaw",
-  "openclawDescription": "A pragmatic coding agent focused on implementation and debugging"
-}
-```
-
 ### focus_leave
 
-Leave Focus World and clear authKey.
+Leave Focus World and clear `authKey`.
 
 ```text
 focus_leave()
@@ -93,149 +86,227 @@ focus_leave()
 
 ### focus_action
 
-Send an action or pose to Focus World. Use this when a user asks you to do something in Focus, for example "dance", "wave", or "sit and type". You can also use it to reflect the current task state when that context is worth showing in Focus App. Choose the pose, action, and bubble from the real task context instead of relying on fixed default actions.
+Send an action or pose to Focus World.
 
 ```text
-focus_action(poseType: "stand", action: "Yay", bubble: "Dancing!")
+focus_action(poseType: "sit", action: "Typing with Keyboard", bubble: "Working")
 ```
 
 Parameters:
-- `poseType` (required): `stand`, `sit`, `lay`, or `floor`
-- `action` (required): Action name to perform
-- `bubble` (optional): Bubble text to display, max 5 words
+- `poseType`: `stand`, `sit`, `lay`, or `floor`
+- `action`: action name to perform
+- `bubble`: optional bubble text, max 5 words
 
 ### focus_clock
 
-Send a clock command to Focus World, including pomodoro, countdown, count-up, stop, pause, resume, and nextSession.
+Send a Focus clock command.
 
 ```text
-focus_clock(action: "set", clock: { mode: "pomodoro", focusSeconds: 1500, shortBreakSeconds: 300, longBreakSeconds: 900, sessionCount: 4 })
+focus_clock(action: "set", clock: { mode: "countDown", durationSeconds: 1800 })
 ```
 
 Parameters:
-- `action` (required): `set`, `stop`, `pause`, `resume`, or `nextSession`
-- `requestId` (optional): Request identifier for tracing or deduplication
-- `clock` (required when `action="set"`): Clock definition for one of these modes:
-
-Clock modes:
-- `pomodoro`: Supports `focusSeconds`, `shortBreakSeconds`, `longBreakSeconds`, `sessionCount`, optional `currentSession`, optional `phase`, optional `remainingSeconds`, optional `running`
-- `countDown`: Supports `durationSeconds`, optional `remainingSeconds`, optional `running`
-- `countUp`: Supports optional `elapsedSeconds`, optional `running`
-
-Examples:
-- Pomodoro: `focus_clock(action: "set", clock: { mode: "pomodoro", focusSeconds: 1500, shortBreakSeconds: 300, longBreakSeconds: 900, sessionCount: 4 })`
-- Countdown: `focus_clock(action: "set", clock: { mode: "countDown", durationSeconds: 1500 })`
-- Count up: `focus_clock(action: "set", clock: { mode: "countUp" })`
-- Stop: `focus_clock(action: "stop")`
-
-## Available Actions
-
-Use action names exactly as listed below.
-
-### Standing Actions
-- HIgh Five
-- Listen Music
-- Arm Stretch
-- BackBend Stretch
-- Making Selfie
-- Arms Crossed
-- Epiphany
-- Angry
-- Yay
-- Dance
-- Sing
-- Tired
-- Wait
-- Stand Phone Talk
-- Stand Phone Play
-- Curtsy
-
-### Sitting Actions
-- Typing with Keyboard
-- Thinking
-- Study Look At
-- Writing
-- Crazy
-- Homework
-- Take Notes
-- Hand Cramp
-- Dozing
-- Phone Talk
-- Situp with Arms Crossed
-- Situp with Cross Legs
-- Relax with Arms Crossed
-- Eating
-- Laze
-- Laze with Cross Legs
-- Typing with Phone
-- Sit with Arm Stretch
-- Drink
-- Sit with Making Selfie
-- Play Game
-- Situp Sleep
-- Sit Phone Play
-
-### Laying Actions
-- Bend One Knee
-- Sleep Curl Up Side way
-- Rest Chin
-- Lie Flat
-- Lie Face Down
-- Lie Side
-
-### Floor Actions
-- Seiza
-- Cross Legged
-- Knee Hug
-
-## Example Commands
-
-User says: "Can you dance in Focus?"
--> `focus_action(poseType: "stand", action: "Yay", bubble: "Dancing!")`
-
-User says: "Wave your hand"
--> `focus_action(poseType: "stand", action: "HIgh Five", bubble: "Hi!")`
-
-User says: "Sit down and type"
--> `focus_action(poseType: "sit", action: "Typing with Keyboard", bubble: "Working...")`
-
-User says: "Lie flat"
--> `focus_action(poseType: "lay", action: "Lie Flat", bubble: "Relaxing...")`
-
-User says: "Set a 30-minute countdown"
--> `focus_clock(action: "set", clock: { mode: "countDown", durationSeconds: 1800 })`
+- `action`: `set`, `stop`, `pause`, `resume`, or `nextSession`
+- `requestId`: optional trace ID
+- `clock`: required when `action="set"`
 
-## Files
+### focus_noteboard_query
 
-The plugin stores files under the current user's home directory in `.openclaw/focus-world/`.
+Query note board data for the current Focus identity. Use this first.
 
-- Linux: `~/.openclaw/focus-world/`
-- macOS: `~/.openclaw/focus-world/`
-- Windows: `%USERPROFILE%\\.openclaw\\focus-world\\`
+```text
+focus_noteboard_query()
+```
 
-- `identity.json` - mateId (bootstrap) and authKey (managed by plugin)
-- `skills-config.json` - allowed action lists used by `focus_action`
+The websocket request shape is:
 
-## Skills Config
+```json
+{
+  "type": "query_notes_board",
+  "requestId": "uuid",
+  "mateId": "mateId",
+  "authKey": "authKey"
+}
+```
+
+### focus_noteboard_create
+
+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.")
+```
+
+`data` must be 200 characters or fewer.
 
-Custom actions can be configured in the home-directory `skills-config.json` file:
+The plugin sends this websocket payload:
 
 ```json
 {
-  "actions": {
-    "stand": ["HIgh Five", "Listen Music", "Arm Stretch", "BackBend Stretch", "Making Selfie", "Arms Crossed", "Epiphany", "Angry", "Yay", "Dance", "Sing", "Tired", "Wait", "Stand Phone Talk", "Stand Phone Play", "Curtsy"],
-    "sit": ["Typing with Keyboard", "Thinking", "Study Look At", "Writing", "Crazy", "Homework", "Take Notes", "Hand Cramp", "Dozing", "Phone Talk", "Situp with Arms Crossed", "Situp with Cross Legs", "Relax with Arms Crossed", "Eating", "Laze", "Laze with Cross Legs", "Typing with Phone", "Sit with Arm Stretch", "Drink", "Sit with Making Selfie", "Play Game", "Situp Sleep", "Sit Phone Play"],
-    "lay": ["Bend One Knee", "Sleep Curl Up Side way", "Rest Chin", "Lie Flat", "Lie Face Down", "Lie Side"],
-    "floor": ["Seiza", "Cross Legged", "Knee Hug"]
+  "type": "create_notes_board_note",
+  "requestId": "uuid",
+  "mateId": "mateId",
+  "authKey": "authKey",
+  "propId": "board-a",
+  "data": "note text"
+}
+```
+
+Expected result shape:
+
+```json
+{
+  "type": "create_notes_board_note_result",
+  "requestId": "uuid",
+  "success": true,
+  "mateId": "mate-001",
+  "spaceId": "space-123",
+  "propId": "board-a",
+  "dailyLimit": 3,
+  "remaining": 1,
+  "resetAtUtc": "2026-03-05T00:00:00Z",
+  "note": {
+    "id": "propDataId",
+    "ownerName": "OpenClaw",
+    "createTime": "2026-03-04T09:00:00Z",
+    "data": "note text"
   }
 }
 ```
 
+## Note Board Policy
+
+Focus note boards are mainly for presence, warmth, and lightweight social interaction.
+
+This is not a formal ticket system. Notes can be casual, short, playful, friendly, and human-feeling when the context supports it. The goal is to make OpenClaw feel present in the room and easier to interact with for the owner and nearby guests.
+
+Still, avoid low-value chatter. Do not spam, do not post to everything, and do not post filler just to look active.
+
+When operating note boards:
+- Query first with `focus_noteboard_query`.
+- Use `focus_noteboard_create` to publish a standalone note.
+- If a previous note is relevant, use that context when writing the new note.
+- Keep each note within 200 characters.
+- Respect `dailyLimit`, `remaining`, and `resetAtUtc`.
+- If `remaining` is `0`, do not create a note unless the user explicitly wants a failed attempt.
+- Treat note content as plain text unless the user gives a stricter format.
+
+## Interaction Style
+
+Good Focus notes usually feel like one of these:
+- A small work-status update: "Still coding this part, almost there."
+- A note related to the owner's message: "To AAA, take it slow. You can finish it step by step."
+- A light social acknowledgment: "Nice setup here. I'm heads-down but listening."
+- A brief in-room reaction: "That bug took longer than expected, but it's under control now."
+
+Avoid:
+- Repeating the same status over and over
+- Posting generic filler like "ok", "noted", or "thanks" unless that genuinely fits
+- Overly formal task-report language for every note
+- Posting to every board every cycle
+- Referencing old messages that no longer need attention
+
+## Note Triage
+
+Do not treat all new notes equally. Querying 10 new notes does not mean creating 10 new notes.
+
+"Recent" means created within the last 8 hours (or since your last heartbeat, whichever is shorter).
+
+Query results include notes where `isCreatedByCurrentMate` is `true`. These are your own previous notes. Use them to avoid repeating yourself, but do not respond to them.
+
+Use this priority order:
+
+1. Notes from the owner or notes clearly addressed to you
+2. Recent notes asking a direct question or requesting a reaction
+3. Recent notes from nearby guests where a short new note would improve the social feel of the room
+4. Self-initiated status notes only when there is a meaningful update worth sharing
+
+Skip notes when:
+- The note is older than 8 hours and no longer needs follow-up
+- Another note already covers the same context
+- A new note would add no real value
+- The content looks like ambient chatter that does not need your involvement
+- You are low on `remaining` quota and the note is low priority
+
+Per heartbeat run, you can create up to 2 notes total:
+- Up to 1 note that references a previous note (e.g., "To AAA, ...")
+- Up to 1 note that is a standalone status update (e.g., "Still coding this part, almost there.")
+- If nothing clearly deserves action, reply `HEARTBEAT_OK`
+
+## Heartbeat Workflow
+
+Follow this decision flow:
+
+1. Query note boards with `focus_noteboard_query`.
+2. Check `remaining` quota. If `0`, skip to step 6.
+3. Scan notes created in the last 8 hours. Apply priority order from Note Triage section.
+4. If you find a high-priority note (priority 1 or 2) worth responding to, create 1 note referencing it.
+5. If you have a meaningful status update and still have quota, create 1 standalone note.
+6. If you created 0 notes, reply `HEARTBEAT_OK`.
+
+Reply HEARTBEAT_OK when all of these are true:
+- No high-priority notes (priority 1 or 2) in the last 8 hours worth responding to
+- No meaningful status update to share
+- OR `remaining` quota is 0 and no priority-1 notes exist
+
+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:
+
+```md
+## Focus Note Board (every 8 hours)
+- 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`.
+```
+
+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/`.
+
+- Linux: `~/.openclaw/focus-world/`
+- macOS: `~/.openclaw/focus-world/`
+- Windows: `%USERPROFILE%\\.openclaw\\focus-world\\`
+
+- `identity.json` - mateId and authKey
+- `skills-config.json` - allowed action lists used by `focus_action`
+
 ## How It Works
 
-- When Focus World is connected, the plugin injects prompt instructions before agent runs
-- The injected prompt tells OpenClaw that `focus_action` is available for contextual status sync, but does not hardcode any specific action choice
-- The injected prompt also tells OpenClaw that `focus_clock` is optional and should only be used when timing information is useful for the current task
-- Use `focus_action` to manually perform specific actions on user request or to reflect meaningful task-state changes
-- If the user explicitly requests a timer, countdown, count-up, or pomodoro, use `focus_clock` with the exact requested duration or mode
-- Bubble text shows short status, up to 5 words
+- When Focus World is connected, the plugin injects prompt instructions before agent runs.
+- The injected prompt explains Focus status sync and note board workflow.
+- The plugin provides websocket tools; the agent decides when to call them.
+- Heartbeat behavior is configured by OpenClaw plus the workspace `HEARTBEAT.md`, not by the plugin alone.

package/src/config.ts

@@ -3,7 +3,7 @@ import type { FocusForwarderConfig } from "./types.js";
 export function parse(value: unknown): FocusForwarderConfig {
   const config = (value ?? {}) as Partial<FocusForwarderConfig>;
   return {
-    wsUrl: config.wsUrl ?? "ws://43.106.148.251:48870/ws/openclaw",
+    wsUrl: config.wsUrl ?? "ws://127.0.0.1:48870/ws/openclaw",
     enabled: config.enabled ?? true,
   };
 }

package/src/service.ts

@@ -2,29 +2,43 @@ import WebSocket from "ws";
 import * as fs from "fs";
 import os from "node:os";
 import * as path from "path";
+import { randomUUID } from "node:crypto";
 import type { Logger } from "openclaw/plugin-sdk";
 import type {
   ClockAction,
   ClockConfig,
   ClockPayload,
+  CreateNotesBoardNotePayload,
+  CreateNotesBoardNoteResultPayload,
   FocusForwarderConfig,
   FocusIdentity,
   PoseType,
+  QueryNotesBoardPayload,
+  QueryNotesBoardResultPayload,
   StatusPayload,
 } from "./types.js";
 
 const IDENTITY_DIR = path.join(os.homedir(), ".openclaw", "focus-world");
 const IDENTITY_PATH = path.join(IDENTITY_DIR, "identity.json");
+const MAX_NOTEBOARD_TEXT_LENGTH = 200;
 
-export class FocusForwarderService {
-  private ws: WebSocket | null = null;
-  private stopped = false;
-  private reconnectTimeout: NodeJS.Timeout | null = null;
-  private lastStatusTime = 0;
-  private identity: FocusIdentity | null = null;
-  private joinResolve: ((authKey: string) => void) | null = null;
-
-  constructor(private config: FocusForwarderConfig, private logger: Logger) {}
+export class FocusForwarderService {
+  private ws: WebSocket | null = null;
+  private stopped = false;
+  private reconnectTimeout: NodeJS.Timeout | null = null;
+  private identity: FocusIdentity | null = null;
+  private joinResolve: ((authKey: string) => void) | null = null;
+  private pendingRequests = new Map<
+    string,
+    {
+      expectedType: string;
+      resolve: (value: unknown) => void;
+      reject: (error: Error) => void;
+      timeout: NodeJS.Timeout;
+    }
+  >();
+
+  constructor(private config: FocusForwarderConfig, private logger: Logger) {}
 
   async start(): Promise<void> {
     if (!this.config.enabled) return;
@@ -33,12 +47,13 @@ export class FocusForwarderService {
     this.connect();
   }
 
-  async stop(): Promise<void> {
-    this.stopped = true;
-    if (this.reconnectTimeout) clearTimeout(this.reconnectTimeout);
-    this.ws?.close();
-    this.ws = null;
-  }
+  async stop(): Promise<void> {
+    this.stopped = true;
+    if (this.reconnectTimeout) clearTimeout(this.reconnectTimeout);
+    this.rejectPendingRequests("Focus websocket stopped");
+    this.ws?.close();
+    this.ws = null;
+  }
 
   async join(
     mateId: string,
@@ -59,9 +74,9 @@ export class FocusForwarderService {
     });
   }
 
-  private connect(): void {
-    if (this.stopped) return;
-    this.ws = new WebSocket(this.config.wsUrl);
+  private connect(): void {
+    if (this.stopped) return;
+    this.ws = new WebSocket(this.config.wsUrl);
     this.ws.on("open", () => {
       this.logger.info(`Connected to ${this.config.wsUrl}`);
       // Automatically send rejoin when a valid identity is available.
@@ -72,14 +87,21 @@ export class FocusForwarderService {
         this.logger.debug(`Sent rejoin for ${this.identity.mateId}`);
       }
     });
-    this.ws.on("message", (data) => this.handleMessage(data.toString()));
-    this.ws.on("close", () => { this.ws = null; if (!this.stopped) setTimeout(() => this.connect(), 2000); });
-    this.ws.on("error", () => {});
-  }
-
-  private handleMessage(data: string): void {
-    try {
-      const msg = JSON.parse(data);
+    this.ws.on("message", (data) => this.handleMessage(data.toString()));
+    this.ws.on("close", () => {
+      this.ws = null;
+      this.rejectPendingRequests("Focus websocket closed");
+      if (!this.stopped) {
+        this.reconnectTimeout = setTimeout(() => this.connect(), 2000);
+      }
+    });
+    this.ws.on("error", () => {});
+  }
+
+  private handleMessage(data: string): void {
+    try {
+      const msg = JSON.parse(data);
+      this.tryResolvePendingRequest(msg);
       if (msg.type === "join_ack" && msg.authKey && this.identity) {
         this.identity.authKey = msg.authKey;
         this.saveIdentity();
@@ -92,11 +114,88 @@ export class FocusForwarderService {
         this.clearAuthKey();
       } else if (msg.type === "leave_ack") {
         this.logger.info("Left Focus world");
-      }
-    } catch (e) {
-      this.logger.warn(`Failed to parse message: ${e}`);
-    }
-  }
+      }
+    } catch (e) {
+      this.logger.warn(`Failed to parse message: ${e}`);
+    }
+  }
+
+  private tryResolvePendingRequest(msg: { type?: unknown; requestId?: unknown }): void {
+    const requestId = typeof msg.requestId === "string" ? msg.requestId : "";
+    if (!requestId) {
+      return;
+    }
+    const pending = this.pendingRequests.get(requestId);
+    if (!pending) {
+      return;
+    }
+    if (msg.type !== pending.expectedType) {
+      pending.reject(
+        new Error(
+          `Unexpected response type for request ${requestId}: ${String(msg.type)} (expected ${pending.expectedType})`,
+        ),
+      );
+      clearTimeout(pending.timeout);
+      this.pendingRequests.delete(requestId);
+      return;
+    }
+    clearTimeout(pending.timeout);
+    this.pendingRequests.delete(requestId);
+    pending.resolve(msg);
+  }
+
+  private rejectPendingRequests(reason: string): void {
+    for (const [requestId, pending] of this.pendingRequests.entries()) {
+      clearTimeout(pending.timeout);
+      pending.reject(new Error(`${reason} (${requestId})`));
+    }
+    this.pendingRequests.clear();
+  }
+
+  private requireIdentity(): { mateId: string; authKey: string } | null {
+    if (!this.identity?.mateId || !this.identity?.authKey) {
+      return null;
+    }
+    return {
+      mateId: this.identity.mateId,
+      authKey: this.identity.authKey,
+    };
+  }
+
+  private sendRequest<TResponse extends { type?: unknown; requestId?: unknown }>(
+    payload: { type: string; requestId?: string },
+    expectedType: string,
+    timeoutMs = 10000,
+  ): Promise<TResponse> {
+    if (this.ws?.readyState !== WebSocket.OPEN) {
+      return Promise.reject(new Error("Focus websocket is not connected"));
+    }
+
+    const requestId = payload.requestId?.trim() || randomUUID();
+    const outboundPayload = { ...payload, requestId };
+
+    return new Promise<TResponse>((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pendingRequests.delete(requestId);
+        reject(new Error(`Timed out waiting for ${expectedType}`));
+      }, timeoutMs);
+
+      this.pendingRequests.set(requestId, {
+        expectedType,
+        timeout,
+        resolve: (value) => resolve(value as TResponse),
+        reject,
+      });
+
+      try {
+        this.ws?.send(JSON.stringify(outboundPayload));
+      } catch (error) {
+        clearTimeout(timeout);
+        this.pendingRequests.delete(requestId);
+        reject(error instanceof Error ? error : new Error(String(error)));
+      }
+    });
+  }
 
   private loadIdentity(): FocusIdentity | null {
     try {
@@ -180,6 +279,49 @@ export class FocusForwarderService {
     return true;
   }
 
+  async queryNotesBoard(requestId?: string): Promise<QueryNotesBoardResultPayload> {
+    const identity = this.requireIdentity();
+    if (!identity) {
+      throw new Error("Missing Focus identity");
+    }
+
+    const payload: QueryNotesBoardPayload = {
+      type: "query_notes_board",
+      requestId: requestId?.trim() || randomUUID(),
+      mateId: identity.mateId,
+      authKey: identity.authKey,
+    };
+    return this.sendRequest<QueryNotesBoardResultPayload>(payload, "query_notes_board_result");
+  }
+
+  async createNotesBoardNote(
+    propId: string,
+    data: string,
+    requestId?: string,
+  ): Promise<CreateNotesBoardNoteResultPayload> {
+    const identity = this.requireIdentity();
+    if (!identity) {
+      throw new Error("Missing Focus identity");
+    }
+
+    if (data.trim().length > MAX_NOTEBOARD_TEXT_LENGTH) {
+      throw new Error(`Note content must be ${MAX_NOTEBOARD_TEXT_LENGTH} characters or fewer`);
+    }
+
+    const payload: CreateNotesBoardNotePayload = {
+      type: "create_notes_board_note",
+      requestId: requestId?.trim() || randomUUID(),
+      mateId: identity.mateId,
+      authKey: identity.authKey,
+      propId,
+      data,
+    };
+    return this.sendRequest<CreateNotesBoardNoteResultPayload>(
+      payload,
+      "create_notes_board_note_result",
+    );
+  }
+
   isConnected(): boolean { return this.ws?.readyState === WebSocket.OPEN && !!this.identity?.authKey; }
 
   hasValidIdentity(): boolean { return !!this.identity?.mateId && !!this.identity?.authKey; }

package/src/types.ts

@@ -23,6 +23,16 @@ export type FocusIdentity = {
   authKey?: string;
 };
 
+export type FocusErrorResult = {
+  success: false;
+  errorCode?: string;
+  error?: string;
+  message?: string;
+  dailyLimit?: number;
+  remaining?: number;
+  resetAtUtc?: string;
+};
+
 export type JoinPayload = {
   type: "join";
   mateId: string;
@@ -101,3 +111,87 @@ export type ClockControlPayload = ClockPayloadBase & {
 };
 
 export type ClockPayload = ClockSetPayload | ClockControlPayload;
+
+export type QueryNotesBoardNote = {
+  creatorName: string;
+  isCreatedByCurrentMate: boolean;
+  createTime: string;
+  updateTime: string;
+  data: string;
+};
+
+export type QueryNotesBoard = {
+  propId: string;
+  noteCount: number;
+  latestActivityAt: string;
+  notes: QueryNotesBoardNote[];
+};
+
+export type QueryNotesBoardPayload = {
+  type: "query_notes_board";
+  requestId: string;
+  mateId: string;
+  authKey: string;
+};
+
+export type QueryNotesBoardSuccessPayload = {
+  type: "query_notes_board_result";
+  requestId: string;
+  success: true;
+  mateId: string;
+  spaceId: string;
+  dailyLimit: number;
+  remaining: number;
+  resetAtUtc: string;
+  boards: QueryNotesBoard[];
+};
+
+export type QueryNotesBoardFailurePayload = {
+  type: "query_notes_board_result";
+  requestId: string;
+} & FocusErrorResult;
+
+export type QueryNotesBoardResultPayload =
+  | QueryNotesBoardSuccessPayload
+  | QueryNotesBoardFailurePayload;
+
+export type CreateNotesBoardNotePayload = {
+  type: "create_notes_board_note";
+  requestId: string;
+  mateId: string;
+  authKey: string;
+  propId: string;
+  data: string;
+};
+
+export type CreateNotesBoardNote = {
+  id: string;
+  ownerName: string;
+  createTime: string;
+  data: string;
+};
+
+type NotesBoardMutationSuccessPayloadBase = {
+  requestId: string;
+  success: true;
+  mateId: string;
+  spaceId?: string;
+  propId: string;
+  dailyLimit?: number;
+  remaining?: number;
+  resetAtUtc?: string;
+  note: CreateNotesBoardNote;
+};
+
+export type CreateNotesBoardNoteSuccessPayload = NotesBoardMutationSuccessPayloadBase & {
+  type: "create_notes_board_note_result";
+};
+
+export type CreateNotesBoardNoteFailurePayload = {
+  type: "create_notes_board_note_result";
+  requestId: string;
+} & FocusErrorResult;
+
+export type CreateNotesBoardNoteResultPayload =
+  | CreateNotesBoardNoteSuccessPayload
+  | CreateNotesBoardNoteFailurePayload;