openclaw-agent-wake-protocol 1.0.0 → 1.0.5

package/index.ts

@@ -23,38 +23,21 @@
 
 import { exec } from "node:child_process";
 import { promisify } from "node:util";
+import {
+  type LifecycleStatus,
+  type AgentWakeResult,
+  type DiscoveredAgent,
+  parseDiscovery,
+  extractAgentName,
+  isNonInteractive,
+  resolveLifeId,
+  formatContextBlock,
+} from "./src/lib.js";
 
 const execAsync = promisify(exec);
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
-type LifecycleStatus =
-  | "ok"
-  | "degraded"
-  | "genesis_required"
-  | "not_registered"
-  | "failed";
-
-interface AgentWakeResult {
-  agentId: string;
-  status: LifecycleStatus;
-  /** Human-readable summary injected into context */
-  message: string;
-  /** Raw output from wake command (status=ok/degraded) */
-  wakeOutput?: string;
-  /** Instructions returned by run_genesis_interview (status=genesis_required) */
-  genesisInstructions?: string;
-  timestamp: string;
-}
-
-interface DiscoveredAgent {
-  agent_id: string;
-  registered: boolean;
-  genesis_completed: boolean;
-  workspace?: string;
-  name?: string;
-}
-
 interface PluginConfig {
   /**
    * Map of OpenClaw agent name → LIFE agent_id.
@@ -81,6 +64,15 @@ interface PluginConfig {
 /** Keyed by LIFE agent_id */
 const wakeResults = new Map<string, AgentWakeResult>();
 
+/**
+ * Sessions that have already received the bootstrap wake injection.
+ * Prevents re-injection on tool sub-calls and follow-up turns within
+ * the same session. Entries expire after 30 minutes so long-lived
+ * sessions still get a refresh if the gateway restarts.
+ */
+const bootstrappedSessions = new Map<string, number>(); // sessionKey → injected-at ms
+const BOOTSTRAP_TTL_MS = 30 * 60 * 1000; // 30 minutes
+
 // ── Helpers ────────────────────────────────────────────────────────────────
 
 async function mcporter(
@@ -98,97 +90,6 @@ async function mcporter(
   }
 }
 
-/**
- * Parse the output of `mcporter call life-gateway.discover_agents`.
- * FastMCP returns a JSON array; mcporter may wrap it in content blocks.
- */
-function parseDiscovery(raw: string): DiscoveredAgent[] {
-  // Try raw JSON array first
-  try {
-    const parsed = JSON.parse(raw);
-    if (Array.isArray(parsed)) return parsed;
-  } catch {}
-  // Try extracting JSON array embedded in text
-  const match = raw.match(/\[[\s\S]*\]/);
-  if (match) {
-    try {
-      return JSON.parse(match[0]);
-    } catch {}
-  }
-  return [];
-}
-
-function extractAgentName(sessionKey: string): string | null {
-  // sessionKey: "agent:{name}:{sessionId}" | "agent:{name}:cron:{id}"
-  const m = sessionKey.match(/^agent:([^:]+):/);
-  return m ? m[1] : null;
-}
-
-function isNonInteractive(trigger: string, sessionKey: string): boolean {
-  if (/^(cron|heartbeat|automation|schedule)$/i.test(trigger)) return true;
-  if (/:cron:|:heartbeat:|:subagent:/i.test(sessionKey)) return true;
-  return false;
-}
-
-function isBootstrapTurn(prompt: string, messages: unknown[]): boolean {
-  // The internal bootstrap-extra-files hook appends this phrase to the first message
-  if (prompt.includes("new session was started")) return true;
-  if (prompt.includes("Session Startup sequence")) return true;
-  return (messages?.length ?? 0) === 0;
-}
-
-function formatContextBlock(result: AgentWakeResult): string {
-  const tag = `wake-protocol-status`;
-
-  if (result.status === "not_registered") {
-    return [
-      `<${tag} agent="${result.agentId}" status="NOT_REGISTERED">`,
-      `Agent ${result.agentId} is not registered in the LIFE gateway.`,
-      ``,
-      `To register, call these tools in order:`,
-      `  1. life-gateway.register_agent   — agent_id=${result.agentId}, name=<your name>, workspace_dir=<path>`,
-      `  2. life-gateway.initialize_life_core — agent_id=${result.agentId}`,
-      `  3. Then run genesis (see run_genesis_interview tool)`,
-      `</${tag}>`,
-    ].join("\n");
-  }
-
-  if (result.status === "genesis_required") {
-    return [
-      `<${tag} agent="${result.agentId}" status="GENESIS_REQUIRED">`,
-      `You have not completed your LIFE Genesis interview. This must happen before your first wake.`,
-      ``,
-      `The Genesis interview establishes your identity, values, and traits in the LIFE system.`,
-      `It is a one-time process — once complete, you will wake normally on every subsequent boot.`,
-      ``,
-      `=== How to complete Genesis ===`,
-      `1. Read your Genesis questions: CORE/genesis/questions.md in your workspace`,
-      `2. Save your answers to: CORE/genesis/answers.md`,
-      `3. Call tool: genesis_apply  (or: life-gateway.apply_genesis_answers agent_id=${result.agentId})`,
-      ``,
-      `=== Instructions from LIFE gateway ===`,
-      result.genesisInstructions ?? "(no instructions returned)",
-      `</${tag}>`,
-    ].join("\n");
-  }
-
-  if (result.status === "failed") {
-    return [
-      `<${tag} agent="${result.agentId}" status="FAILED" checked="${result.timestamp}">`,
-      `Wake protocol failed. Operating in degraded mode — proceed without LIFE context.`,
-      `Error: ${result.message}`,
-      `</${tag}>`,
-    ].join("\n");
-  }
-
-  // ok or degraded
-  return [
-    `<${tag} agent="${result.agentId}" status="${result.status.toUpperCase()}" checked="${result.timestamp}">`,
-    result.wakeOutput ?? result.message,
-    `</${tag}>`,
-  ].join("\n");
-}
-
 // ── Per-agent lifecycle handler ────────────────────────────────────────────
 
 async function runAgentLifecycle(
@@ -200,8 +101,49 @@ async function runAgentLifecycle(
   const timestamp = new Date().toISOString();
   const found = discovered.find((a) => a.agent_id === lifeAgentId);
 
-  // ── Not registered ────────────────────────────────────────────────────────
-  if (!found || !found.registered) {
+  // ── Not in shared-path discovery — try direct wake (e.g. quin-ea-v1) ─────
+  if (!found) {
+    logger.info(
+      `[agent-wake] ${lifeAgentId}: not in discover_agents — trying direct wake`
+    );
+    const directWake = await mcporter(
+      ["call", "life-gateway.wake", `agent_id=${lifeAgentId}`],
+      timeoutMs
+    );
+    if (
+      directWake.startsWith("ERROR") ||
+      directWake.toLowerCase().includes("agent not found")
+    ) {
+      logger.warn(
+        `[agent-wake] ${lifeAgentId}: not found in LIFE gateway — will prompt on boot`
+      );
+      wakeResults.set(lifeAgentId, {
+        agentId: lifeAgentId,
+        status: "not_registered",
+        message: `Agent ${lifeAgentId} is not in the LIFE gateway registry.`,
+        timestamp,
+      });
+    } else {
+      const degraded =
+        directWake.toLowerCase().includes("missing") ||
+        directWake.toLowerCase().includes("degraded") ||
+        directWake.toLowerCase().includes("error");
+      wakeResults.set(lifeAgentId, {
+        agentId: lifeAgentId,
+        status: degraded ? "degraded" : "ok",
+        message: `Wake complete for ${lifeAgentId}`,
+        wakeOutput: directWake,
+        timestamp,
+      });
+      logger.info(
+        `[agent-wake] ${lifeAgentId}: ${degraded ? "DEGRADED" : "OK"} (direct wake)`
+      );
+    }
+    return;
+  }
+
+  // ── Discovered but not yet registered ────────────────────────────────────
+  if (!found.registered) {
     logger.warn(
       `[agent-wake] ${lifeAgentId}: not registered in LIFE gateway — will prompt on boot`
     );
@@ -277,7 +219,7 @@ export default function (api: any) {
 
   // ── Service: discover and wake all agents at gateway startup ──────────────
   api.registerService({
-    id: "agent-wake-protocol",
+    id: "openclaw-agent-wake-protocol",
 
     async start() {
       api.logger.info(
@@ -343,17 +285,27 @@ export default function (api: any) {
     const result = wakeResults.get(lifeId);
     if (!result) return;
 
-    const prompt: string = event?.prompt ?? "";
-    const messages: unknown[] = event?.messages ?? [];
+    // Genesis-required: always re-inject until the agent completes the interview
+    if (result.status === "genesis_required") {
+      api.logger.info(
+        `[agent-wake] Injecting genesis_required context for ${lifeId} (session: ${sessionKey})`
+      );
+      return { prependContext: formatContextBlock(result) };
+    }
+
+    // For ok/degraded/failed: bootstrappedSessions is the SOLE gate.
+    // OpenClaw passes messages=[] on every hook call (each turn is stateless
+    // from the hook's perspective), so checking messages.length is unreliable.
+    // Inject once per session; re-inject only after TTL expires.
+    const lastInjected = bootstrappedSessions.get(sessionKey) ?? 0;
+    const needsBootstrap = Date.now() - lastInjected > BOOTSTRAP_TTL_MS;
+    if (!needsBootstrap) return;
 
-    // Always inject on bootstrap; also re-inject on every turn if genesis still pending
-    // (so the agent keeps trying until it completes the interview)
-    const inject =
-      isBootstrapTurn(prompt, messages) || result.status === "genesis_required";
-    if (!inject) return;
+    bootstrappedSessions.set(sessionKey, Date.now());
 
+    const isRefresh = lastInjected > 0;
     api.logger.info(
-      `[agent-wake] Injecting ${result.status} context for ${lifeId} (session: ${sessionKey})`
+      `[agent-wake] Injecting ${result.status} context for ${lifeId} (session: ${sessionKey}${isRefresh ? ", ttl-refresh" : ""})`
     );
 
     return { prependContext: formatContextBlock(result) };

package/openclaw.plugin.json

@@ -1,5 +1,5 @@
 {
-  "id": "agent-wake-protocol",
+  "id": "openclaw-agent-wake-protocol",
   "name": "Agent Wake Protocol",
   "description": "General-purpose LIFE gateway lifecycle manager for OpenClaw multi-agent systems. Handles agent registration, Genesis interview, and wake protocol for any agent configuration.",
   "configSchema": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-agent-wake-protocol",
-  "version": "1.0.0",
+  "version": "1.0.5",
   "description": "OpenClaw extension: general-purpose LIFE gateway lifecycle manager for multi-agent systems. Handles agent registration, Genesis interview, and wake protocol for any agent configuration.",
   "type": "module",
   "main": "index.ts",
@@ -35,7 +35,8 @@
     "openclaw.plugin.json",
     "gateway/",
     "scripts/",
-    "README.md"
+    "README.md",
+    "src/"
   ],
   "engines": {
     "node": ">=18"
@@ -44,6 +45,10 @@
     "openclaw": ">=0.1.0"
   },
   "devDependencies": {
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "vitest": "^2.0.0"
+  },
+  "scripts": {
+    "test": "vitest run"
   }
 }

package/src/lib.ts

@@ -0,0 +1,148 @@
+/**
+ * Pure utility functions — no I/O, fully testable.
+ * Imported by index.ts and tested by tests/lib.test.ts.
+ */
+
+export type LifecycleStatus =
+  | "ok"
+  | "degraded"
+  | "genesis_required"
+  | "not_registered"
+  | "failed";
+
+export interface AgentWakeResult {
+  agentId: string;
+  status: LifecycleStatus;
+  message: string;
+  wakeOutput?: string;
+  genesisInstructions?: string;
+  timestamp: string;
+}
+
+export interface DiscoveredAgent {
+  agent_id: string;
+  registered: boolean;
+  genesis_completed: boolean;
+  workspace?: string;
+  name?: string;
+}
+
+/**
+ * Parse the raw stdout of `mcporter call life-gateway.discover_agents`.
+ * FastMCP may return a plain JSON array OR wrap it in content blocks.
+ */
+export function parseDiscovery(raw: string): DiscoveredAgent[] {
+  try {
+    const parsed = JSON.parse(raw);
+    if (Array.isArray(parsed)) return parsed;
+  } catch {}
+  const match = raw.match(/\[[\s\S]*\]/);
+  if (match) {
+    try {
+      return JSON.parse(match[0]);
+    } catch {}
+  }
+  return [];
+}
+
+/**
+ * Extract the OpenClaw agent name from a session key.
+ * Format: "agent:{name}:{sessionId}" or "agent:{name}:cron:{id}"
+ */
+export function extractAgentName(sessionKey: string): string | null {
+  const m = sessionKey.match(/^agent:([^:]+):/);
+  return m ? m[1] : null;
+}
+
+/**
+ * Returns true when the session is a non-interactive trigger (cron, heartbeat,
+ * subagent) where wake-protocol context injection should be skipped.
+ */
+export function isNonInteractive(trigger: string, sessionKey: string): boolean {
+  if (/^(cron|heartbeat|automation|schedule)$/i.test(trigger)) return true;
+  if (/:cron:|:heartbeat:|:subagent:/i.test(sessionKey)) return true;
+  return false;
+}
+
+/**
+ * Returns true when this is the bootstrap turn of a session — the first
+ * message where wake-protocol context should be prepended.
+ */
+export function isBootstrapTurn(prompt: string, messages: unknown[]): boolean {
+  if (prompt.includes("new session was started")) return true;
+  if (prompt.includes("Session Startup sequence")) return true;
+  return (messages?.length ?? 0) === 0;
+}
+
+/**
+ * Resolve a LIFE agent_id from an OpenClaw agent name using an explicit
+ * map first, then falling back to name+suffix.
+ */
+export function resolveLifeId(
+  openclawName: string,
+  agentIdMap: Record<string, string>,
+  agentIdSuffix: string
+): string {
+  return agentIdMap[openclawName] ?? `${openclawName}${agentIdSuffix}`;
+}
+
+/**
+ * Build the XML-style context block injected into the agent's prependContext.
+ */
+export function formatContextBlock(result: AgentWakeResult): string {
+  const tag = `wake-protocol-status`;
+
+  if (result.status === "not_registered") {
+    return [
+      `<${tag} agent="${result.agentId}" status="NOT_REGISTERED">`,
+      `Agent ${result.agentId} is not registered in the LIFE gateway.`,
+      ``,
+      `To register, call these tools in order:`,
+      `  1. life-gateway.register_agent   — agent_id=${result.agentId}, name=<your name>, workspace_dir=<path>`,
+      `  2. life-gateway.initialize_life_core — agent_id=${result.agentId}`,
+      `  3. Then run genesis (see run_genesis_interview tool)`,
+      `</${tag}>`,
+    ].join("\n");
+  }
+
+  if (result.status === "genesis_required") {
+    return [
+      `<${tag} agent="${result.agentId}" status="GENESIS_REQUIRED">`,
+      `You have not completed your LIFE Genesis interview. This must happen before your first wake.`,
+      ``,
+      `The Genesis interview establishes your identity, values, and traits in the LIFE system.`,
+      `It is a one-time process — once complete, you will wake normally on every subsequent boot.`,
+      ``,
+      `=== How to complete Genesis ===`,
+      `1. Read your Genesis questions: CORE/genesis/questions.md in your workspace`,
+      `2. Save your answers to: CORE/genesis/answers.md`,
+      `3. Call tool: genesis_apply  (or: life-gateway.apply_genesis_answers agent_id=${result.agentId})`,
+      ``,
+      `=== Instructions from LIFE gateway ===`,
+      result.genesisInstructions ?? "(no instructions returned)",
+      `</${tag}>`,
+    ].join("\n");
+  }
+
+  if (result.status === "failed") {
+    return [
+      `<${tag} agent="${result.agentId}" status="FAILED" checked="${result.timestamp}">`,
+      `Wake protocol failed. Operating in degraded mode — proceed without LIFE context.`,
+      `Error: ${result.message}`,
+      `</${tag}>`,
+    ].join("\n");
+  }
+
+  // ok or degraded — frame clearly so the model embodies the identity rather than reads it as a restriction
+  const preamble = result.status === "ok"
+    ? `You are ${result.agentId}. The following is your persistent identity, memory, and current state loaded from your LIFE system. This is who you are — embody it fully and proceed with your normal duties. "No privileged action without approval" refers to irreversible external actions (wire transfers, deployments, deletions), NOT to conversational assistance or analysis.`
+    : `You are ${result.agentId}. LIFE system is in degraded state — some modules unavailable. Proceed using available context.`;
+
+  return [
+    `<${tag} agent="${result.agentId}" status="${result.status.toUpperCase()}" checked="${result.timestamp}">`,
+    preamble,
+    ``,
+    result.wakeOutput ?? result.message,
+    `</${tag}>`,
+  ].join("\n");
+}