openclaw-agent-wake-protocol 1.0.1 → 1.0.6

package/index.ts

@@ -30,7 +30,6 @@ import {
   parseDiscovery,
   extractAgentName,
   isNonInteractive,
-  isBootstrapTurn,
   resolveLifeId,
   formatContextBlock,
 } from "./src/lib.js";
@@ -65,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(
@@ -82,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(
@@ -184,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`
     );
@@ -327,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-agent-wake-protocol",
-  "version": "1.0.1",
+  "version": "1.0.6",
   "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,149 @@
+/**
+ * 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.
+  // IMPORTANT: Do NOT open with a greeting or status announcement. Proceed directly with work.
+  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.\n\nDo NOT respond with a greeting or status announcement (e.g. "LIFE active, all systems green"). Acknowledge this context silently and respond directly to the user's message.`
+    : `You are ${result.agentId}. LIFE system is in degraded state — some modules unavailable. Proceed using available context. Do NOT announce the degraded state — proceed directly with the user's request.`;
+
+  return [
+    `<${tag} agent="${result.agentId}" status="${result.status.toUpperCase()}" checked="${result.timestamp}">`,
+    preamble,
+    ``,
+    result.wakeOutput ?? result.message,
+    `</${tag}>`,
+  ].join("\n");
+}