@openclawbrain/cli 0.4.14 → 0.4.16

package/dist/src/teacher-decision-match.js

@@ -80,6 +80,14 @@ function readInteractionActivePackGraphChecksum(interaction) {
         ?? undefined;
 }
 
+function readInteractionExplicitTurnCompileEventId(interaction) {
+    return normalizeOptionalString(interaction?.turnCompileEventId)
+        ?? normalizeOptionalString(toRecord(interaction?.routeMetadata)?.turnCompileEventId)
+        ?? normalizeOptionalString(toRecord(interaction?.decisionProvenance)?.turnCompileEventId)
+        ?? normalizeOptionalString(toRecord(interaction?.metadata)?.turnCompileEventId)
+        ?? undefined;
+}
+
 function buildDecisionTimestamps(decision) {
     const timestamps = [];
     const turnCreatedAt = toTimestamp(decision.turnCreatedAt);
@@ -139,8 +147,10 @@ export function createServeTimeDecisionMatcher(decisions, options = {}) {
     const decisionsByRecordId = new Map();
     const decisionsBySelectionDigest = new Map();
     const ambiguousSelectionDigests = new Set();
-    const exactDecisions = new Map();
+    const decisionsByTurnCompileEventId = new Map();
+    const ambiguousTurnCompileEventIds = new Set();
     const fallbackDecisions = new Map();
+    const ambiguousFallbackDecisionKeys = new Set();
     const decisionsBySessionChannel = new Map();
     const globalFallbackDecisions = [];
 
@@ -164,15 +174,27 @@ export function createServeTimeDecisionMatcher(decisions, options = {}) {
             }
         }
         const turnCompileEventId = normalizeOptionalString(decision.turnCompileEventId);
-        if (turnCompileEventId !== undefined && !exactDecisions.has(turnCompileEventId)) {
-            exactDecisions.set(turnCompileEventId, decision);
+        if (turnCompileEventId !== undefined) {
+            if (decisionsByTurnCompileEventId.has(turnCompileEventId)) {
+                decisionsByTurnCompileEventId.delete(turnCompileEventId);
+                ambiguousTurnCompileEventIds.add(turnCompileEventId);
+            }
+            else if (!ambiguousTurnCompileEventIds.has(turnCompileEventId)) {
+                decisionsByTurnCompileEventId.set(turnCompileEventId, decision);
+            }
         }
         for (const candidateKey of [
             buildCandidateKey(decision.sessionId, decision.channel, decision.turnCreatedAt),
             buildCandidateKey(decision.sessionId, decision.channel, decision.recordedAt),
         ]) {
-            if (candidateKey !== null && !fallbackDecisions.has(candidateKey)) {
-                fallbackDecisions.set(candidateKey, decision);
+            if (candidateKey !== null) {
+                if (fallbackDecisions.has(candidateKey)) {
+                    fallbackDecisions.delete(candidateKey);
+                    ambiguousFallbackDecisionKeys.add(candidateKey);
+                }
+                else if (!ambiguousFallbackDecisionKeys.has(candidateKey)) {
+                    fallbackDecisions.set(candidateKey, decision);
+                }
             }
         }
         const sessionChannelKey = buildSessionChannelKey(decision.sessionId, decision.channel);
@@ -203,22 +225,37 @@ export function createServeTimeDecisionMatcher(decisions, options = {}) {
         if (decisionRecordId !== undefined) {
             return decisionsByRecordId.get(decisionRecordId) ?? null;
         }
-        const selectionDigestKey = buildSelectionDigestKey(
-            readInteractionSelectionDigest(interaction),
-            readInteractionActivePackGraphChecksum(interaction),
-        );
+        const interactionSelectionDigest = readInteractionSelectionDigest(interaction);
+        const interactionGraphChecksum = readInteractionActivePackGraphChecksum(interaction);
+        const selectionDigestKey = buildSelectionDigestKey(interactionSelectionDigest, interactionGraphChecksum);
         if (selectionDigestKey !== null) {
             if (ambiguousSelectionDigests.has(selectionDigestKey)) {
                 return null;
             }
             return decisionsBySelectionDigest.get(selectionDigestKey) ?? null;
         }
-        const exact = exactDecisions.get(interaction.eventId);
+        if (interactionSelectionDigest !== undefined || interactionGraphChecksum !== undefined) {
+            return null;
+        }
+        const explicitTurnCompileEventId = readInteractionExplicitTurnCompileEventId(interaction);
+        if (explicitTurnCompileEventId !== undefined) {
+            if (ambiguousTurnCompileEventIds.has(explicitTurnCompileEventId)) {
+                return null;
+            }
+            return decisionsByTurnCompileEventId.get(explicitTurnCompileEventId) ?? null;
+        }
+        const softTurnCompileEventId = normalizeOptionalString(interaction.eventId);
+        const exact = softTurnCompileEventId === undefined || ambiguousTurnCompileEventIds.has(softTurnCompileEventId)
+            ? undefined
+            : decisionsByTurnCompileEventId.get(softTurnCompileEventId);
         if (exact !== undefined) {
             return exact;
         }
         const exactFallbackKey = buildCandidateKey(interaction.sessionId, interaction.channel, interaction.createdAt);
         if (exactFallbackKey !== null) {
+            if (ambiguousFallbackDecisionKeys.has(exactFallbackKey)) {
+                return null;
+            }
             const fallback = fallbackDecisions.get(exactFallbackKey);
             if (fallback !== undefined) {
                 return fallback;

package/dist/src/teacher-labeler.d.ts

@@ -15,6 +15,17 @@ export interface TeacherLabelerResultV1 {
 export interface TeacherLabeler {
     label(input: TeacherLabelerRunInputV1): Promise<TeacherLabelerResultV1>;
 }
+export interface TeacherLabelerOpportunityInputV1 {
+    normalizedEventExport: NormalizedEventExportV1;
+    serveTimeDecisions?: readonly LearningSpineServeRouteDecisionLogEntryV1[];
+}
+export interface TeacherLabelerOpportunityV1 {
+    enabled: boolean;
+    candidateCount: number;
+    budgetedCandidateCount: number;
+    status: "disabled" | "ready" | "skipped";
+    detail: string;
+}
 export interface OllamaTeacherLabelerGenerateInputV1 {
     model: string;
     prompt: string;
@@ -47,4 +58,5 @@ export interface AsyncTeacherNoopLabelerConfigV1 {
 export type AsyncTeacherLabelerConfigV1 = AsyncTeacherNoopLabelerConfigV1 | AsyncTeacherOllamaLabelerConfigV1;
 export declare function createHttpOllamaTeacherLabelerClient(baseUrl?: string): OllamaTeacherLabelerClient;
 export declare function createOllamaTeacherLabeler(config: AsyncTeacherOllamaLabelerConfigV1): TeacherLabeler;
+export declare function summarizeTeacherLabelerOpportunity(input: TeacherLabelerOpportunityInputV1, config?: AsyncTeacherLabelerConfigV1 | null): TeacherLabelerOpportunityV1;
 export declare function createTeacherLabeler(config: AsyncTeacherLabelerConfigV1 | null | undefined): TeacherLabeler | null;

package/dist/src/teacher-labeler.js

@@ -246,6 +246,48 @@ function normalizeOllamaTeacherLabelerConfig(config) {
         client: config.client ?? createHttpOllamaTeacherLabelerClient(normalizeBaseUrl(config.baseUrl))
     };
 }
+export function summarizeTeacherLabelerOpportunity(input, config) {
+    const normalized = config === undefined || config === null || config.provider === "none"
+        ? {
+            enabled: false,
+            maxPromptChars: DEFAULT_OLLAMA_MAX_PROMPT_CHARS,
+            maxArtifactsPerExport: DEFAULT_OLLAMA_MAX_ARTIFACTS_PER_EXPORT,
+            maxInteractionsPerExport: DEFAULT_OLLAMA_MAX_INTERACTIONS,
+            maxUserMessageChars: DEFAULT_OLLAMA_MAX_USER_MESSAGE_CHARS,
+            maxContextIdsPerDecision: DEFAULT_OLLAMA_MAX_CONTEXT_IDS
+        }
+        : {
+            enabled: true,
+            ...normalizeOllamaTeacherLabelerConfig(config)
+        };
+    const candidates = collectCandidates(input, normalized);
+    if (candidates.length === 0) {
+        return {
+            enabled: normalized.enabled,
+            candidateCount: 0,
+            budgetedCandidateCount: 0,
+            status: normalized.enabled ? "skipped" : "disabled",
+            detail: "no_matching_interaction_text"
+        };
+    }
+    const budgetedCandidates = fitCandidatesToPromptBudget(candidates, normalized);
+    if (budgetedCandidates.length === 0) {
+        return {
+            enabled: normalized.enabled,
+            candidateCount: candidates.length,
+            budgetedCandidateCount: 0,
+            status: normalized.enabled ? "skipped" : "disabled",
+            detail: "prompt_budget_exhausted"
+        };
+    }
+    return {
+        enabled: normalized.enabled,
+        candidateCount: candidates.length,
+        budgetedCandidateCount: budgetedCandidates.length,
+        status: normalized.enabled ? "ready" : "disabled",
+        detail: `candidates=${budgetedCandidates.length}`
+    };
+}
 class HttpOllamaTeacherLabelerClient {
     baseUrl;
     constructor(baseUrl) {

package/dist/src/traced-learning-bridge.js

@@ -18,6 +18,22 @@ function normalizeOptionalString(value) {
 function normalizeSource(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
 }
+function summarizeBridgeSource(value) {
+    const source = normalizeSource(value);
+    if (source === null) {
+        return null;
+    }
+    const summarized = {
+        command: normalizeOptionalString(source.command),
+        bridge: normalizeOptionalString(source.bridge),
+        brainRoot: normalizeOptionalString(source.brainRoot),
+        stateDbPath: normalizeOptionalString(source.stateDbPath),
+        persistedKey: normalizeOptionalString(source.persistedKey),
+        candidatePackVersion: Number.isFinite(source.candidatePackVersion) ? Math.trunc(source.candidatePackVersion) : undefined,
+        candidateUpdateCount: normalizeCount(source.candidateUpdateCount)
+    };
+    return Object.fromEntries(Object.entries(summarized).filter(([, candidate]) => candidate !== null && candidate !== undefined));
+}
 function normalizeBridgePayload(payload) {
     if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
         throw new Error("expected traced-learning bridge payload object");
@@ -579,7 +595,7 @@ export function mergeTracedLearningBridgePayload(payload, persisted) {
                 supervisionCount: persistedBridge.supervisionCount,
                 routerUpdateCount: persistedBridge.routerUpdateCount,
                 teacherArtifactCount: persistedBridge.teacherArtifactCount,
-                source: persistedBridge.source
+                source: summarizeBridgeSource(persistedBridge.source)
             }
         }
     });

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.16",
   "description": "OpenClawBrain operator CLI package with install/status helpers, daemon controls, and import/export tooling.",
   "type": "module",
   "main": "./dist/src/index.js",