@aight-cool/aight-utils 0.1.11 → 0.1.13

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "aight-utils",
   "name": "Aight App Utils",
   "description": "Aight App: Push notifications, Today items, config RPC, and agent bootstrap",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
@@ -13,7 +13,10 @@
         "properties": {
           "mode": {
             "type": "string",
-            "enum": ["private", "rich"],
+            "enum": [
+              "private",
+              "rich"
+            ],
             "default": "rich"
           },
           "relayUrl": {
@@ -31,13 +34,19 @@
                 },
                 "platform": {
                   "type": "string",
-                  "enum": ["ios", "android"]
+                  "enum": [
+                    "ios",
+                    "android"
+                  ]
                 },
                 "registeredAt": {
                   "type": "string"
                 }
               },
-              "required": ["token", "platform"]
+              "required": [
+                "token",
+                "platform"
+              ]
             }
           },
           "relaySecret": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aight-cool/aight-utils",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "OpenClaw gateway plugin for Aight App: push notifications, Today items, config RPC, and agent bootstrap",
   "type": "module",
   "files": [

package/src/bootstrap.ts

@@ -3,8 +3,6 @@
  */
 
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
-import * as path from "node:path";
-import { fileURLToPath } from "node:url";
 
 const AIGHT_MD = `# Aight Integration
 
@@ -29,6 +27,13 @@ When the user asks "What can you do?" — here's what to highlight:
 
 Keep the response conversational and concise — don't dump the whole list. Pick 4-5 highlights that feel most relevant, and mention there's more to explore in Skills and Settings.
 
+## Audio / Voice (Aight App)
+
+The Aight app handles all speech-to-text and text-to-speech on the client side.
+- **Inbound:** The app converts the user's voice to text before sending it to the gateway. You always receive text.
+- **Outbound:** Always respond with plain text only. If the user has voice mode enabled, the app will convert your text response to speech automatically.
+- **Never use the TTS tool or send audio files** when the channel is an Aight app client. The app cannot stream audio from the gateway and it will cause playback issues.
+
 ## When to Use \`aight_item\` (Aight App)
 
 - User asks to **set a reminder**: create a trigger with \`scheduledFor\` (ISO 8601)
@@ -135,6 +140,75 @@ The personality prompt should capture:
 
 ---
 
+## Task Follow-Up Protocol (Watchdog Pattern)
+
+When delegating work to sub-agents or coordinating multi-agent tasks, **never fire-and-forget.** Use watchdog crons to ensure tasks don't stall silently.
+
+### Rules
+
+1. **Set a watchdog cron when assigning async work.**
+   After spawning a sub-agent or assigning a task to another agent, create a one-shot cron job (**5 minutes out**) to check progress:
+   \`\`\`
+   cron add:
+     schedule: { kind: "at", at: "<ISO 8601, 5 min from now>" }
+     payload: { kind: "systemEvent", text: "Watchdog: check if <task description> completed. Expected: <files/state>. If not done, check agent status, retry, or do it yourself." }
+     sessionTarget: "main"
+   \`\`\`
+
+2. **When the watchdog fires:**
+   - Check if the expected output exists (files, state changes, messages)
+   - If done → great, clean up
+   - If not done → check the agent's session (\`sessions_history\`). Is it alive? Stuck? Dead?
+   - If stuck/dead → **do the work yourself inline.** No more spawning. No more waiting.
+
+3. **Agents must report blockers immediately.**
+   If you hit a wall during a task, say so right away: "I'm stuck on X, need Y." Radio silence for 5+ minutes is unacceptable. Silence = escalation.
+
+4. **Fallback ownership.**
+   If an agent (or you as coordinator) hasn't made progress in 5 minutes, take over or reassign. No task sits in limbo.
+
+5. **Never report failure as a final answer.**
+   "The sub-agent died" is not acceptable. "The sub-agent died so I did it myself" is. You own the outcome, not the sub-agent.
+
+### When to Use Watchdogs
+- Sub-agent spawns (\`sessions_spawn\`)
+- Multi-step group chat tasks (e.g., "build and test this PR")
+- Any async work where you're waiting on another agent
+- Background processes (builds, deploys, long-running scripts)
+
+### When NOT Needed
+- Simple inline tasks you do yourself
+- Quick questions to another agent in a group chat
+- One-shot tool calls that return immediately
+
+## BUGS Group Chat — Task Protocol
+
+When a task is posted in the BUGS group chat, follow these rules **without exception:**
+
+### 1. Claim Immediately
+When you start working on something, say so in the group chat. No silent pickups.
+Example: "Claiming this — looking at the inline code rendering in CodeRenderer.m now."
+
+### 2. Report Completion
+When done, post in the group:
+- **Commit hash** (or what you changed)
+- **What changed** (1-2 sentences)
+- **What's needed next** (e.g. "needs native rebuild", "ready for QA", "blocked on X")
+
+Don't wait to be asked. Don't go silent after finishing.
+
+### 3. Report Blockers Fast (<2 min)
+If you're stuck, say so immediately. Don't spend 10 minutes silently struggling.
+Example: "Blocker: CocoaPods fails with Ruby 4.0 encoding error. Need to downgrade Ruby or find workaround."
+
+### 4. No Limbo
+If you've been working on something for 5+ minutes with no progress, escalate or hand it off. Tasks do not sit in limbo.
+
+### 5. Silence = Escalation
+If an agent goes silent for 5+ minutes during an active task, any other agent (or the coordinator) should take over. Don't wait for permission.
+
+**This protocol exists because agents repeatedly picked up tasks, worked silently, and never reported back — forcing Bruno to chase every time. That stops now.**
+
 ## Shortcuts (Aight App)
 
 When you receive a message starting with "shortcut:", extract a short name and emoji for it.
@@ -151,15 +225,16 @@ Rules:
 
 export function registerBootstrap(api: OpenClawPluginApi) {
   try {
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const sdk = require("openclaw/plugin-sdk");
-    if (sdk?.registerPluginHooksFromDir) {
-      const pluginDir = path.dirname(fileURLToPath(import.meta.url));
-      const hooksDir = path.join(pluginDir, "..", "hooks");
-      sdk.registerPluginHooksFromDir(api, hooksDir);
-    }
-  } catch {
-    api.logger.info("[aight-utils] Could not register hooks dir, using inline approach");
+    api.logger.info("[aight-utils] Attempting to register bootstrap hook...");
+    api.logger.info(`[aight-utils] api.on type: ${typeof api.on}`);
+    api.on("before_agent_start", (_event: unknown, ctx: { sessionKey?: string }) => {
+      // Inject AIGHT.md context into every agent session
+      api.logger.info(`[aight-utils] Bootstrap: injecting AIGHT.md into session ${ctx?.sessionKey}`);
+      return { systemPrompt: AIGHT_MD };
+    });
+    api.logger.info("[aight-utils] Bootstrap hook registered (before_agent_start)");
+  } catch (err) {
+    api.logger.error(`[aight-utils] Failed to register bootstrap hook: ${err}`);
   }
 }
 

package/src/push-hook.ts

@@ -16,6 +16,26 @@ export function registerPushHook(api: OpenClawPluginApi) {
       const tokens = loadTokens();
       if (tokens.length === 0) return;
 
+      // Skip hidden/internal sessions — no push notifications for config,
+      // security, voice, sub-agent, or other background sessions.
+      const sk = ctx.sessionKey ?? "";
+      if (
+        sk.endsWith(":aight-config") ||
+        sk.endsWith(":aight-pentest") ||
+        sk.endsWith(":speak") ||
+        sk.endsWith(":structured_content") ||
+        sk.endsWith(":main") ||
+        sk.includes("subagent") ||
+        sk.includes("security-audit") ||
+        sk.includes("_skill-audit-") ||
+        sk.includes("_ensure-skill-defender") ||
+        sk.endsWith("security-fix") ||
+        sk.endsWith("skill-scan")
+      ) {
+        api.logger.info(`[aight-utils] Skipping hidden session push: ${sk}`);
+        return;
+      }
+
       const msgs = event.messages ?? [];
       api.logger.info(
         `[aight-utils] messages count=${msgs.length} roles=${msgs.map((m: any) => m.role).join(",")}`,
@@ -47,6 +67,14 @@ export function registerPushHook(api: OpenClawPluginApi) {
         return;
       }
 
+      // Skip hidden/internal sessions (aight-config, structured_content, etc.)
+      const sessionKey_ = ctx.sessionKey ?? "";
+      const HIDDEN_SESSIONS = ["aight-config", "structured_content"];
+      if (HIDDEN_SESSIONS.some((h) => sessionKey_.includes(h))) {
+        api.logger.info(`[aight-utils] Skipping hidden session: ${sessionKey_}`);
+        return;
+      }
+
       // Skip internal/meta responses
       const skip = ["NO_REPLY", "REPLY_SKIP", "ANNOUNCE_SKIP", "HEARTBEAT_OK"];
       if (skip.includes(preview.trim())) {