@aight-cool/aight-utils 0.1.14 → 0.1.17

package/index.ts

@@ -14,6 +14,7 @@ import { registerPushHook } from "./src/push-hook.js";
 import { registerHealth } from "./src/health.js";
 import { registerVersion } from "./src/version.js";
 import { registerGroupRpc } from "./src/groups.js";
+import { registerNotifPrefsRPC } from "./src/notif-prefs.js";
 
 const aightPlugin = {
   id: "aight-utils",
@@ -68,6 +69,7 @@ const aightPlugin = {
     registerHealth(api);
     registerVersion(api);
     registerGroupRpc(api);
+    registerNotifPrefsRPC(api);
 
     api.logger.info("[aight-utils] Plugin loaded");
   },

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.14",
+  "version": "0.1.17",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

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

package/src/bootstrap.ts

@@ -6,6 +6,16 @@ import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 
 const AIGHT_MD = `# Aight Integration
 
+## ⚠️ Shortcuts Protocol (CRITICAL — follow exactly)
+
+When you receive a message starting with "shortcut:", you MUST reply with ONLY a JSON object — no explanation, no markdown fences, no other text:
+{"short_name": "Example Name", "emoji": "🎯"}
+Rules:
+- short_name: 2-4 words, Title Case, describing what the shortcut does
+- emoji: a single relevant emoji
+- Do NOT answer the question in the shortcut text. Just label it.
+- Reply with NOTHING else — just the raw JSON object
+
 Aight is the iOS app the user is chatting through. It connects to the OpenClaw gateway running on their machine, giving them a native mobile interface for their AI agent.
 
 ## What You Can Do (via Aight)
@@ -189,6 +199,7 @@ When you receive a message prefixed with \`[Group Chat: "Name" — Members: ...]
 [Group Chat: "Name" — Members: emoji Name (@username), ...]
 [Recent messages]
 emoji SenderName: message text
+emoji SenderName: [your message at HH:MM]
 emoji SenderName: message text
 ...
 
@@ -196,15 +207,18 @@ emoji SenderName: message text
 The user's actual message
 \`\`\`
 
+**Your own messages are stubbed.** To save tokens, the app replaces the body of your own messages in the recent messages block with \`[your message at HH:MM]\`. You already have the full text in your session history, so no information is lost. Other agents' and the user's messages are shown in full.
+
 Rules:
 - To address another agent, **@mention them** in your reply text. The app routes automatically.
 - Do **NOT** use \`sessions_send\` — just @mention in your message.
 - Recent messages provide conversational context — the gateway session has full history.
 - \`[Your turn]\` marks the boundary between context and the new message you should respond to.
+- If you need to recall what you said at a specific time, check your own session history — it has the full text.
 
-## BUGS Group Chat — Task Protocol
+## Group Chat — Task Protocol
 
-When a task is posted in the BUGS group chat, follow these rules **without exception:**
+When a task is posted in any 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.
@@ -232,15 +246,7 @@ If an agent goes silent for 5+ minutes during an active task, any other agent (o
 
 ## Shortcuts (Aight App)
 
-When you receive a message starting with "shortcut:", extract a short name and emoji for it.
-Reply with ONLY a JSON object — no markdown, no explanation:
-\`\`\`
-{"short_name": "Example Name", "emoji": "🎯"}
-\`\`\`
-Rules:
-- short_name: 2-4 words, Title Case, describing what the shortcut does
-- emoji: a single relevant emoji
-- Reply with NOTHING else — just the JSON object
+See the Shortcuts Protocol at the top of this document.
 
 `;
 
@@ -250,7 +256,9 @@ export function registerBootstrap(api: OpenClawPluginApi) {
     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}`);
+      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)");

package/src/config.ts

@@ -16,7 +16,7 @@ export interface AightConfig {
   };
 }
 
-/** Keys that belong in the plugin config section (everything else routes to root gateway config) */
+/** Strict allowlist of keys this plugin owns — anything else is rejected */
 const PLUGIN_CONFIG_KEYS = new Set(["push", "today"]);
 
 /** Secret keys that must never be returned to clients via RPC */
@@ -53,25 +53,23 @@ export function registerConfig(api: OpenClawPluginApi) {
         return;
       }
       try {
+        // Reject any keys not in the plugin allowlist — never touch root gateway config
+        const incoming = params as Record<string, unknown>;
+        for (const key of Object.keys(incoming)) {
+          if (!PLUGIN_CONFIG_KEYS.has(key)) {
+            respond(false, { error: `Key "${key}" is not allowed in config.patch` });
+            return;
+          }
+        }
+
         // Load current config
         const currentConfig = await api.runtime.config.loadConfig();
         const pluginEntry = (currentConfig as any)?.plugins?.entries?.["aight-utils"] ?? {};
         const currentPluginConfig = pluginEntry.config ?? {};
 
-        // Separate plugin-level keys from gateway root-level keys
-        const pluginPatch: Record<string, unknown> = {};
-        const rootPatch: Record<string, unknown> = {};
-        for (const [key, value] of Object.entries(params as Record<string, unknown>)) {
-          if (PLUGIN_CONFIG_KEYS.has(key)) {
-            pluginPatch[key] = value;
-          } else {
-            rootPatch[key] = value;
-          }
-        }
-
-        // Deep merge plugin-level keys into plugin config
+        // Deep merge allowed plugin-level keys into plugin config
         const merged = { ...currentPluginConfig };
-        for (const [key, value] of Object.entries(pluginPatch)) {
+        for (const [key, value] of Object.entries(incoming)) {
           if (
             value &&
             typeof value === "object" &&
@@ -85,8 +83,9 @@ export function registerConfig(api: OpenClawPluginApi) {
           }
         }
 
-        // Build updated config: plugin config + root-level overrides
-        let updatedConfig: Record<string, unknown> = {
+        // Build updated config — only the plugin's own config section is modified;
+        // root gateway config is preserved as-is and never overwritten by client input.
+        const updatedConfig: Record<string, unknown> = {
           ...(currentConfig as Record<string, unknown>),
           plugins: {
             ...((currentConfig as any)?.plugins ?? {}),
@@ -100,21 +99,6 @@ export function registerConfig(api: OpenClawPluginApi) {
           },
         };
 
-        // Deep merge root-level keys into the gateway config
-        for (const [key, value] of Object.entries(rootPatch)) {
-          if (
-            value &&
-            typeof value === "object" &&
-            !Array.isArray(value) &&
-            updatedConfig[key] &&
-            typeof updatedConfig[key] === "object"
-          ) {
-            updatedConfig[key] = { ...(updatedConfig[key] as Record<string, unknown>), ...value };
-          } else {
-            updatedConfig[key] = value;
-          }
-        }
-
         await api.runtime.config.writeConfigFile(updatedConfig as any);
         respond(true, { ok: true, config: getClientSafeConfig(merged as AightConfig) });
       } catch (err) {

package/src/items.ts

@@ -150,13 +150,37 @@ export const AightItemToolParams = Type.Object({
 
 // ── Registration ──
 
+/** Strip heavy fields for list responses — detail is fetched via aight.items.get */
+function toLightItem(item: Item): Omit<Item, "description" | "metadata" | "url"> {
+  const { description: _d, metadata: _m, url: _u, ...light } = item;
+  return light;
+}
+
 export function registerItems(api: OpenClawPluginApi) {
   api.registerGatewayMethod(
     "aight.items.list",
     ({ params, respond }: GatewayRequestHandlerOptions) => {
       const filters: ListFilters =
         params && typeof params === "object" ? (params as ListFilters) : {};
-      respond(true, { items: listItems(filters) });
+      respond(true, { items: listItems(filters).map(toLightItem) });
+    },
+  );
+
+  api.registerGatewayMethod(
+    "aight.items.get",
+    ({ params, respond }: GatewayRequestHandlerOptions) => {
+      const id = typeof params?.id === "string" ? params.id : "";
+      if (!id) {
+        respond(false, { error: "id required" });
+        return;
+      }
+      const all = loadItems();
+      const item = all.find((i) => i.id === id);
+      if (!item || item.status === "deleted") {
+        respond(false, { error: "item not found" });
+        return;
+      }
+      respond(true, { item });
     },
   );
 

package/src/notif-prefs.ts

@@ -0,0 +1,115 @@
+/**
+ * Notification Preferences — gateway-side storage for push suppression.
+ *
+ * The app syncs notification preferences here via RPC. The push hook
+ * checks these prefs before sending to the relay — if a category is
+ * muted, the push never leaves the user's machine.
+ *
+ * RPC methods:
+ *   aight.notif.setPrefs  — update preferences
+ *   aight.notif.getPrefs  — read current preferences
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import type { OpenClawPluginApi, GatewayRequestHandlerOptions } from "openclaw/plugin-sdk";
+
+// ── Types ──
+
+export interface NotifPrefs {
+  globalMute: boolean;
+  muteUntil: string | null;
+  agentReplies: boolean;
+  groupChat: boolean;
+  cron: boolean;
+}
+
+const DEFAULTS: NotifPrefs = {
+  globalMute: false,
+  muteUntil: null,
+  agentReplies: true,
+  groupChat: true,
+  cron: false,
+};
+
+// ── Storage ──
+
+const PREFS_DIR = path.join(os.homedir(), ".openclaw", "aight");
+const PREFS_FILE = path.join(PREFS_DIR, "notif-prefs.json");
+
+export function loadNotifPrefs(): NotifPrefs {
+  try {
+    if (!fs.existsSync(PREFS_FILE)) return { ...DEFAULTS };
+    const raw = fs.readFileSync(PREFS_FILE, "utf-8");
+    const parsed = JSON.parse(raw);
+    return { ...DEFAULTS, ...parsed };
+  } catch {
+    return { ...DEFAULTS };
+  }
+}
+
+function saveNotifPrefs(prefs: NotifPrefs): void {
+  fs.mkdirSync(PREFS_DIR, { recursive: true, mode: 0o700 });
+  fs.writeFileSync(PREFS_FILE, JSON.stringify(prefs, null, 2), "utf-8");
+}
+
+// ── Classification (matches app-side logic) ──
+
+export function classifySessionKey(sessionKey: string): "agentReplies" | "groupChat" | "cron" {
+  if (sessionKey.includes(":cron:")) return "cron";
+  if (sessionKey.includes(":group-chat:")) return "groupChat";
+  return "agentReplies";
+}
+
+/**
+ * Check if a push for this sessionKey should be sent.
+ */
+export function shouldSendPush(sessionKey: string): boolean {
+  if (!sessionKey) return true; // fail open
+
+  const prefs = loadNotifPrefs();
+
+  // Global mute
+  if (prefs.globalMute) {
+    if (!prefs.muteUntil) return false; // indefinite
+    const expiry = new Date(prefs.muteUntil).getTime();
+    if (Date.now() < expiry) return false;
+    // Mute expired — clear it
+    prefs.globalMute = false;
+    prefs.muteUntil = null;
+    saveNotifPrefs(prefs);
+  }
+
+  // Category check
+  const category = classifySessionKey(sessionKey);
+  return prefs[category];
+}
+
+// ── RPC Registration ──
+
+export function registerNotifPrefsRPC(api: OpenClawPluginApi) {
+  api.registerGatewayMethod("aight.notif.getPrefs", ({ respond }: GatewayRequestHandlerOptions) => {
+    respond(true, loadNotifPrefs());
+  });
+
+  api.registerGatewayMethod(
+    "aight.notif.setPrefs",
+    ({ params, respond }: GatewayRequestHandlerOptions) => {
+      const update = (params ?? {}) as Partial<NotifPrefs>;
+      const current = loadNotifPrefs();
+
+      if (typeof update.globalMute === "boolean") current.globalMute = update.globalMute;
+      if (typeof update.agentReplies === "boolean") current.agentReplies = update.agentReplies;
+      if (typeof update.groupChat === "boolean") current.groupChat = update.groupChat;
+      if (typeof update.cron === "boolean") current.cron = update.cron;
+      if (update.muteUntil !== undefined) current.muteUntil = update.muteUntil;
+
+      saveNotifPrefs(current);
+      api.logger.info(`[aight-utils] Notification prefs updated: ${JSON.stringify(current)}`);
+      respond(true, current);
+    },
+  );
+
+  api.logger.info("[aight-utils] Notification prefs RPC registered");
+}

package/src/push-hook.ts

@@ -4,8 +4,9 @@
 
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import { getPluginConfig } from "./config.js";
-import { sendPush, loadTokens } from "./push.js";
+import { sendPush, loadTokens, unregisterToken } from "./push.js";
 import { loadGroupName } from "./groups.js";
+import { shouldSendPush } from "./notif-prefs.js";
 
 export function registerPushHook(api: OpenClawPluginApi) {
   try {
@@ -106,10 +107,18 @@ export function registerPushHook(api: OpenClawPluginApi) {
 
       const cleanBody = preview.trim().replace(/\n+/g, " ").trim();
 
+      // ── Notification preference gate ──
+      // Check if this category is muted — if so, don't send the push at all.
+      const sk_ = ctx.sessionKey ?? "";
+      if (!shouldSendPush(sk_)) {
+        api.logger.info(`[aight-utils] Push suppressed by notification prefs: ${sk_}`);
+        return;
+      }
+
       for (const device of tokens) {
         if (!device.sendKey) continue;
         try {
-          await sendPush(
+          const pushResult = await sendPush(
             device.deviceId,
             {
               title: pushTitle.trim(),
@@ -119,6 +128,23 @@ export function registerPushHook(api: OpenClawPluginApi) {
             },
             freshConfig,
           );
+          api.logger.info(
+            `[aight-utils] Push sent: session=${ctx.sessionKey} device=${device.deviceId} ok=${pushResult.ok}${pushResult.error ? ` error=${pushResult.error}` : ""}`,
+          );
+
+          // Auto-prune stale tokens — if the relay rejects the token, remove it
+          if (!pushResult.ok && pushResult.error) {
+            const err = pushResult.error.toLowerCase();
+            if (
+              err.includes("baddevicetoken") ||
+              err.includes("unregistered") ||
+              err.includes("devicetokennotfortopic") ||
+              err.includes("expired")
+            ) {
+              api.logger.info(`[aight-utils] Pruning stale device token: ${device.deviceId}`);
+              unregisterToken(device.deviceId);
+            }
+          }
         } catch (err) {
           api.logger.warn(
             `[aight-utils] Push failed: ${err instanceof Error ? err.message : String(err)}`,