@openclawbrain/cli 0.4.14 → 0.4.15

package/extension/index.ts

@@ -18,6 +18,7 @@ import {
 } from "@openclawbrain/openclaw";
 import {
   createBeforePromptBuildHandler,
+  type ExtensionDiagnostic,
   isActivationRootPlaceholder,
   validateExtensionRegistrationApi
 } from "./runtime-guard.js";
@@ -52,7 +53,7 @@ async function appendLocalDiagnosticLog(message: string): Promise<void> {
   }
 }
 
-async function reportDiagnostic(input: { key: string; message: string; once?: boolean }): Promise<void> {
+async function reportDiagnostic(input: ExtensionDiagnostic): Promise<void> {
   if (input.once) {
     if (warnedDiagnostics.has(input.key)) {
       return;
@@ -60,8 +61,30 @@ async function reportDiagnostic(input: { key: string; message: string; once?: bo
     warnedDiagnostics.add(input.key);
   }
 
-  console.warn(input.message);
-  await appendLocalDiagnosticLog(input.message);
+  const formatted = formatDiagnosticMessage(input);
+  console.warn(formatted);
+  await appendLocalDiagnosticLog(formatted);
+}
+
+function formatDiagnosticMessage(input: ExtensionDiagnostic): string {
+  if (
+    input.severity === undefined ||
+    input.actionability === undefined ||
+    input.summary === undefined ||
+    input.action === undefined
+  ) {
+    return input.message;
+  }
+
+  const detail = input.message.replace(/^\[openclawbrain\]\s*/, "");
+  return [
+    "[openclawbrain]",
+    `severity=${input.severity}`,
+    `actionability=${input.actionability}`,
+    `summary=${JSON.stringify(input.summary)}`,
+    `action=${JSON.stringify(input.action)}`,
+    `detail=${JSON.stringify(detail)}`
+  ].join(" ");
 }
 
 function announceStartupBreadcrumb(): void {
@@ -107,8 +130,12 @@ export default function register(api: unknown) {
       } catch (error) {
         const detail = error instanceof Error ? error.message : String(error);
         void reportDiagnostic({
-          key: `runtime-load-proof:${detail}`,
+          key: "runtime-load-proof-failed",
           once: true,
+          severity: "degraded",
+          actionability: "inspect_local_proof_write",
+          summary: "runtime-load proof write failed after hook registration",
+          action: "Inspect local filesystem permissions and the activation-root proof path if proof capture is expected.",
           message: `[openclawbrain] runtime load proof failed: ${detail}`
         });
       }
@@ -119,6 +146,10 @@ export default function register(api: unknown) {
     void reportDiagnostic({
       key: "registration-failed",
       once: true,
+      severity: "blocking",
+      actionability: "rerun_install",
+      summary: "extension registration threw before the runtime hook was fully attached",
+      action: "Rerun openclawbrain install --openclaw-home <path>; if it still fails, inspect the extension loader/runtime.",
       message: `[openclawbrain] extension registration failed: ${detail}`
     });
   }

package/extension/runtime-guard.ts

@@ -27,10 +27,23 @@ export type ExtensionCompileResult = ExtensionCompileSuccess | ExtensionCompileF
 
 export type ExtensionCompileRuntimeContext = (input: ExtensionCompileInput) => ExtensionCompileResult;
 
+export type ExtensionDiagnosticSeverity = "degraded" | "blocking";
+
+export type ExtensionDiagnosticActionability =
+  | "inspect_host_event_shape"
+  | "inspect_host_registration_api"
+  | "inspect_local_proof_write"
+  | "inspect_runtime_compile"
+  | "rerun_install";
+
 export interface ExtensionDiagnostic {
   key: string;
   message: string;
   once?: boolean;
+  severity?: ExtensionDiagnosticSeverity;
+  actionability?: ExtensionDiagnosticActionability;
+  summary?: string;
+  action?: string;
 }
 
 export interface ExtensionRegistrationApi {
@@ -53,13 +66,13 @@ export function validateExtensionRegistrationApi(api: unknown): { ok: true; api:
   if (!isRecord(api) || typeof api.on !== "function") {
     return {
       ok: false,
-      diagnostic: {
+      diagnostic: shapeDiagnostic({
         key: "registration-api-invalid",
         once: true,
         message:
           `[openclawbrain] extension inactive: host registration API is missing api.on(event, handler, options) ` +
           `(received=${describeValue(api)})`
-      }
+      })
     };
   }
 
@@ -145,12 +158,12 @@ export function createBeforePromptBuildHandler(input: {
 }): (event: unknown, ctx: unknown) => Promise<Record<string, unknown>> {
   return async (event: unknown, _ctx: unknown) => {
     if (isActivationRootPlaceholder(input.activationRoot)) {
-      await input.reportDiagnostic({
+      await input.reportDiagnostic(shapeDiagnostic({
         key: "activation-root-placeholder",
         once: true,
         message:
           "[openclawbrain] BRAIN NOT YET LOADED: ACTIVATION_ROOT is still a placeholder. Install @openclawbrain/cli, then run: openclawbrain install --openclaw-home <path>"
-      });
+      }));
       return {};
     }
 
@@ -190,12 +203,12 @@ export function createBeforePromptBuildHandler(input: {
 
       if (!result.ok) {
         const mode = result.hardRequirementViolated ? "hard-fail" : "fail-open";
-        await input.reportDiagnostic({
+        await input.reportDiagnostic(shapeDiagnostic({
           key: `compile-${mode}`,
           message:
             `[openclawbrain] ${mode}: ${result.error} ` +
             `(activationRoot=${input.activationRoot}, sessionId=${normalized.event.sessionId ?? "unknown"}, channel=${normalized.event.channel ?? "unknown"})`
-        });
+        }));
         return {};
       }
 
@@ -207,12 +220,12 @@ export function createBeforePromptBuildHandler(input: {
       }
     } catch (error) {
       const detail = error instanceof Error ? error.stack ?? error.message : String(error);
-      await input.reportDiagnostic({
+      await input.reportDiagnostic(shapeDiagnostic({
         key: "compile-threw",
         message:
           `[openclawbrain] compile threw: ${detail} ` +
           `(activationRoot=${input.activationRoot}, sessionId=${normalized.event.sessionId ?? "unknown"}, channel=${normalized.event.channel ?? "unknown"})`
-      });
+      }));
     }
 
     return {};
@@ -220,10 +233,10 @@ export function createBeforePromptBuildHandler(input: {
 }
 
 function failOpenDiagnostic(key: string, reason: string, detail: string): ExtensionDiagnostic {
-  return {
+  return shapeDiagnostic({
     key,
     message: `[openclawbrain] fail-open: ${reason} (${detail})`
-  };
+  });
 }
 
 function normalizeOptionalScalarField(
@@ -244,12 +257,12 @@ function normalizeOptionalScalarField(
     return String(value);
   }
 
-  warnings.push({
+  warnings.push(shapeDiagnostic({
     key: `runtime-${fieldName}-ignored`,
     message:
       `[openclawbrain] fail-open: ignored unsupported before_prompt_build ${fieldName} ` +
       `(${fieldName}=${describeValue(value)})`
-  });
+  }));
 
   return undefined;
 }
@@ -284,12 +297,12 @@ function normalizeOptionalNonNegativeIntegerField(
     }
   }
 
-  warnings.push({
+  warnings.push(shapeDiagnostic({
     key: `runtime-${fieldName}-ignored`,
     message:
       `[openclawbrain] fail-open: ignored unsupported before_prompt_build ${fieldName} ` +
       `(${fieldName}=${describeValue(value)})`
-  });
+  }));
 
   return undefined;
 }
@@ -402,6 +415,71 @@ function describeValue(value: unknown): string {
   return `${typeof value}(${String(value)})`;
 }
 
+function shapeDiagnostic(diagnostic: ExtensionDiagnostic): ExtensionDiagnostic {
+  if (
+    diagnostic.severity !== undefined &&
+    diagnostic.actionability !== undefined &&
+    diagnostic.summary !== undefined &&
+    diagnostic.action !== undefined
+  ) {
+    return diagnostic;
+  }
+
+  if (diagnostic.key === "activation-root-placeholder") {
+    return {
+      ...diagnostic,
+      severity: "blocking",
+      actionability: "rerun_install",
+      summary: "extension hook is installed but ACTIVATION_ROOT is still unpinned",
+      action: "Run openclawbrain install --openclaw-home <path> to pin the runtime hook."
+    };
+  }
+
+  if (diagnostic.key === "registration-api-invalid") {
+    return {
+      ...diagnostic,
+      severity: "blocking",
+      actionability: "inspect_host_registration_api",
+      summary: "extension host registration API is missing or incompatible",
+      action: "Repair or upgrade the host extension API so api.on(event, handler, options) is available."
+    };
+  }
+
+  if (diagnostic.key === "compile-hard-fail") {
+    return {
+      ...diagnostic,
+      severity: "blocking",
+      actionability: "inspect_runtime_compile",
+      summary: "brain context compile hit a hard requirement",
+      action: "Inspect the activation root and compile error; rerun install if the pinned hook may be stale."
+    };
+  }
+
+  if (diagnostic.key === "compile-fail-open" || diagnostic.key === "compile-threw") {
+    return {
+      ...diagnostic,
+      severity: "degraded",
+      actionability: "inspect_runtime_compile",
+      summary: diagnostic.key === "compile-threw"
+        ? "brain context compile threw during before_prompt_build"
+        : "brain context compile failed open during before_prompt_build",
+      action: "Inspect the activation root and compile error if brain context is unexpectedly empty."
+    };
+  }
+
+  if (diagnostic.key.startsWith("runtime-")) {
+    return {
+      ...diagnostic,
+      severity: "degraded",
+      actionability: "inspect_host_event_shape",
+      summary: "before_prompt_build payload was partial or malformed",
+      action: "Inspect the host before_prompt_build event shape; OpenClawBrain fail-opened safely."
+    };
+  }
+
+  return diagnostic;
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclawbrain/cli",
-  "version": "0.4.14",
+  "version": "0.4.15",
   "description": "OpenClawBrain operator CLI package with install/status helpers, daemon controls, and import/export tooling.",
   "type": "module",
   "main": "./dist/src/index.js",