@openclawbrain/cli 0.4.13 → 0.4.15

package/dist/src/install-converge.js

@@ -0,0 +1,217 @@
+const CHANGE_REASON_LABELS = {
+  install_identity: "plugin install identity changed",
+  install_layout: "authoritative install layout changed",
+  hook_path: "hook path changed",
+  hook_state: "hook install state changed",
+  loadability: "hook loadability changed",
+  activation_root: "pinned activation root changed",
+  loader_source: "loader source changed",
+  runtime_guard_source: "runtime-guard source changed",
+  plugins_config: "OpenClaw plugins config changed",
+};
+
+function sameValue(left, right) {
+  return left === right;
+}
+
+function installIdentityOf(fingerprint) {
+  if (fingerprint?.selectedInstall === null || fingerprint?.selectedInstall === undefined) {
+    return null;
+  }
+  return JSON.stringify({
+    extensionDir: fingerprint.selectedInstall.extensionDir ?? null,
+    manifestId: fingerprint.selectedInstall.manifestId ?? null,
+    installId: fingerprint.selectedInstall.installId ?? null,
+    packageName: fingerprint.selectedInstall.packageName ?? null,
+  });
+}
+
+export function planOpenClawBrainConvergePluginAction(fingerprint) {
+  const selectedInstall = fingerprint?.selectedInstall ?? null;
+  if (selectedInstall === null) {
+    return {
+      action: "install",
+      packageSpec: "@openclawbrain/openclaw",
+      pluginId: "openclawbrain",
+      reason: "no authoritative OpenClawBrain plugin install was discovered for this OpenClaw home",
+    };
+  }
+  if (selectedInstall.installLayout !== "native_package_plugin") {
+    return {
+      action: "install",
+      packageSpec: "@openclawbrain/openclaw",
+      pluginId: "openclawbrain",
+      reason: "the authoritative install is still a generated shadow extension, so converge must install the split-package plugin lane",
+    };
+  }
+  return {
+    action: "update",
+    packageSpec: "@openclawbrain/openclaw",
+    pluginId: "openclawbrain",
+    reason: "refresh the existing split-package plugin install so install/upgrade/repair stays on one converge path",
+  };
+}
+
+export function diffOpenClawBrainConvergeRuntimeFingerprint(before, after) {
+  const reasons = [];
+  if (!sameValue(installIdentityOf(before), installIdentityOf(after))) {
+    reasons.push("install_identity");
+  }
+  if (!sameValue(before?.installLayout ?? null, after?.installLayout ?? null)) {
+    reasons.push("install_layout");
+  }
+  if (!sameValue(before?.hookPath ?? null, after?.hookPath ?? null)) {
+    reasons.push("hook_path");
+  }
+  if (!sameValue(before?.hookState ?? null, after?.hookState ?? null)) {
+    reasons.push("hook_state");
+  }
+  if (!sameValue(before?.loadability ?? null, after?.loadability ?? null)) {
+    reasons.push("loadability");
+  }
+  if (!sameValue(before?.activationRoot ?? null, after?.activationRoot ?? null)) {
+    reasons.push("activation_root");
+  }
+  if (!sameValue(before?.loaderSource ?? null, after?.loaderSource ?? null)) {
+    reasons.push("loader_source");
+  }
+  if (!sameValue(before?.runtimeGuardSource ?? null, after?.runtimeGuardSource ?? null)) {
+    reasons.push("runtime_guard_source");
+  }
+  if (!sameValue(before?.pluginsConfig ?? null, after?.pluginsConfig ?? null)) {
+    reasons.push("plugins_config");
+  }
+  return {
+    changed: reasons.length > 0,
+    reasons,
+  };
+}
+
+export function describeOpenClawBrainConvergeChangeReasons(reasons) {
+  const normalized = reasons
+    .map((reason) => CHANGE_REASON_LABELS[reason] ?? reason)
+    .filter((reason, index, values) => values.indexOf(reason) === index);
+  return normalized.length === 0 ? "no runtime-affecting install changes detected" : normalized.join("; ");
+}
+
+export function buildOpenClawBrainConvergeRestartPlan(input) {
+  const changeReasons = input.changeReasons ?? [];
+  if (changeReasons.length === 0) {
+    return {
+      required: false,
+      automatic: false,
+      reason: "no_runtime_affecting_changes",
+      detail: "Skipped gateway restart because converge did not change plugin files, hook wiring, or the pinned activation root.",
+    };
+  }
+  if (input.profileName === null) {
+    return {
+      required: true,
+      automatic: false,
+      reason: "exact_profile_unresolved",
+      detail: "Restart is still required because converge changed runtime-affecting install state, but install could not infer an exact OpenClaw profile token for automatic restart.",
+    };
+  }
+  return {
+    required: true,
+    automatic: true,
+    reason: "runtime_affecting_changes_detected",
+    detail: `Restart is required because converge changed runtime-affecting install state for profile ${input.profileName}.`,
+  };
+}
+
+export function classifyOpenClawBrainConvergeVerification(input) {
+  const warnings = [];
+  const blockingReasons = [];
+  const installLayout = input.installLayout ?? null;
+  const installState = input.installState ?? "unknown";
+  const loadability = input.loadability ?? "unverified";
+  const displayedStatus = input.displayedStatus ?? "unknown";
+  const runtimeLoad = input.runtimeLoad ?? "unverified";
+  const loadProof = input.loadProof ?? "unverified";
+  const serveState = input.serveState ?? "unknown";
+  if (installLayout !== "native_package_plugin") {
+    blockingReasons.push("split-package native package plugin is not authoritative after converge");
+  }
+  if (installState !== "installed") {
+    blockingReasons.push(`hook install state is ${installState}`);
+  }
+  if (loadability !== "loadable") {
+    blockingReasons.push(`hook loadability is ${loadability}`);
+  }
+  if (displayedStatus === "fail") {
+    blockingReasons.push("status still reports fail");
+  }
+  const runtimeTruthAlreadyProven = displayedStatus === "ok"
+    && runtimeLoad === "proven"
+    && loadProof === "status_probe_ready";
+  if (input.restartRequired === true && input.restartPerformed !== true && !runtimeTruthAlreadyProven) {
+    blockingReasons.push("restart is still required before runtime load can be trusted");
+  }
+  if (blockingReasons.length > 0) {
+    return {
+      state: "failed",
+      manualActionRequired: true,
+      blockingReasons,
+      warnings,
+    };
+  }
+  if (input.restartRequired === true && input.restartPerformed !== true && runtimeTruthAlreadyProven) {
+    warnings.push("automatic restart was not performed because install could not infer an exact OpenClaw profile token, but current status already proves runtime load");
+  }
+  if (displayedStatus !== "ok") {
+    warnings.push(`status is ${displayedStatus}`);
+  }
+  if (runtimeLoad !== "proven") {
+    warnings.push(`runtime load is ${runtimeLoad}`);
+  }
+  if (loadProof !== "status_probe_ready") {
+    warnings.push(`loadProof is ${loadProof}`);
+  }
+  if (serveState !== "serving_active_pack") {
+    warnings.push(`serve state is ${serveState}`);
+  }
+  if (input.routeFnAvailable !== true) {
+    warnings.push("route_fn availability is not yet proven");
+  }
+  if (input.awaitingFirstExport === true) {
+    warnings.push("the attached profile has not emitted its first export yet");
+  }
+  return {
+    state: warnings.length > 0 ? "warning" : "healthy",
+    manualActionRequired: false,
+    blockingReasons,
+    warnings,
+  };
+}
+
+export function finalizeOpenClawBrainConvergeResult(input) {
+  const warnings = [...(input.warnings ?? []), ...(input.verification?.warnings ?? [])];
+  const uniqueWarnings = warnings.filter((warning, index, values) => values.indexOf(warning) === index);
+  if (input.stepFailure !== null && input.stepFailure !== undefined) {
+    return {
+      verdict: "failed",
+      why: input.stepFailure,
+      warnings: uniqueWarnings,
+    };
+  }
+  if (input.verification?.state === "failed") {
+    return {
+      verdict: input.verification.manualActionRequired ? "manual_action_required" : "failed",
+      why: input.verification.blockingReasons.join("; "),
+      warnings: uniqueWarnings,
+    };
+  }
+  if (input.verification?.state === "warning") {
+    return {
+      verdict: "converged_with_warnings",
+      why: input.verification.warnings.join("; "),
+      warnings: uniqueWarnings,
+    };
+  }
+  return {
+    verdict: "converged",
+    why: "plugin install, hook wiring, restart behavior, and status verification converged on the expected split-package state",
+    warnings: uniqueWarnings,
+  };
+}

package/dist/src/learning-spine.d.ts

@@ -1,4 +1,4 @@
-import { type AlwaysOnLearningMaterializationJobV1 } from "./local-learner.js";
+import { type AlwaysOnLearningMaterializationJobV1 } from "@openclawbrain/learner";
 import { type BrainServeHotPathTimingV1, type NormalizedEventExportV1, type RouteMode, type RuntimeCompileResponseV1 } from "@openclawbrain/contracts";
 import { type LearningSpinePgRouteUpdateLogEntryV1, type LearningSpineServeRouteBreadcrumbsV1, type LearningSpineServeRouteDecisionLogEntryV1, type PackDescriptor } from "@openclawbrain/pack-format";
 type CompileFailureLike = {
@@ -22,6 +22,7 @@ interface RuntimeTurnLike {
     createdAt?: string | null;
     sequenceStart?: number | null;
     maxContextBlocks?: number;
+    maxContextChars?: number;
     budgetStrategy?: "fixed_v1" | "empirical_v1";
     mode?: RouteMode;
     runtimeHints?: readonly string[];

package/dist/src/learning-spine.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { rankContextBlocks } from "@openclawbrain/compiler";
-import { describeSparseFeedbackEventDispositions } from "./local-learner.js";
+import { describeSparseFeedbackEventDispositions } from "@openclawbrain/learner";
 import { CONTRACT_IDS } from "@openclawbrain/contracts";
 import { appendLearningSpineLogEntry, buildLearningSpineLogId, loadActivationPointers, loadPack, loadPackFromActivation, readLearningSpineLogEntries } from "@openclawbrain/pack-format";
 function noteValue(notes, prefix) {
@@ -10,6 +10,7 @@ function noteValue(notes, prefix) {
 function roundNumber(value) {
     return Math.round(value * 10_000) / 10_000;
 }
+const MAX_PERSISTED_ROUTE_DECISION_CANDIDATE_SET_IDS = 256;
 function softmax(values) {
     if (values.length === 0) {
         return [];
@@ -22,6 +23,48 @@ function softmax(values) {
     }
     return numerators.map((value) => roundNumber(value / denominator));
 }
+function isPlainObject(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function compactStructuralSignalValue(value, depth = 0) {
+    if (value === null || typeof value === "boolean") {
+        return value;
+    }
+    if (typeof value === "number") {
+        return Number.isFinite(value) ? roundNumber(value) : undefined;
+    }
+    if (typeof value === "string") {
+        return value.length <= 256 ? value : `${value.slice(0, 256)}...`;
+    }
+    if (depth >= 3) {
+        return undefined;
+    }
+    if (Array.isArray(value)) {
+        const compacted = value
+            .slice(0, 32)
+            .map((entry) => compactStructuralSignalValue(entry, depth + 1))
+            .filter((entry) => entry !== undefined);
+        return compacted;
+    }
+    if (!isPlainObject(value)) {
+        return undefined;
+    }
+    const compactedEntries = Object.entries(value)
+        .slice(0, 32)
+        .flatMap(([key, entry]) => {
+        const compacted = compactStructuralSignalValue(entry, depth + 1);
+        return compacted === undefined ? [] : [[key, compacted]];
+    });
+    return compactedEntries.length > 0 ? Object.fromEntries(compactedEntries) : undefined;
+}
+function compactStructuralSignals(value) {
+    const compacted = compactStructuralSignalValue(value);
+    return compacted !== undefined && isPlainObject(compacted) ? compacted : null;
+}
 function isStableKernelContextBlock(block) {
     if (block.id.includes(":event:") || block.id.includes(":teacher:")) {
         return false;
@@ -247,7 +290,7 @@ export function appendServeTimeRouteDecisionLog(input) {
         requestedBudget: {
             modeRequested: input.turn.mode ?? "heuristic",
             maxContextBlocks: effectiveMaxContextBlocks,
-            maxContextChars: null
+            maxContextChars: input.turn.maxContextChars ?? null
         },
         actualBudget: {
             modeEffective: input.compileResult.ok ? input.compileResult.compileResponse.diagnostics.modeEffective : null,
@@ -255,28 +298,15 @@ export function appendServeTimeRouteDecisionLog(input) {
             selectedCharCount: input.compileResult.ok ? input.compileResult.compileResponse.diagnostics.selectedCharCount : 0,
             selectedTokenCount: input.compileResult.ok ? input.compileResult.compileResponse.diagnostics.selectedTokenCount : 0
         },
-        candidateSetIds: ranked.map((entry) => entry.blockId),
+        candidateSetIds: ranked.slice(0, MAX_PERSISTED_ROUTE_DECISION_CANDIDATE_SET_IDS).map((entry) => entry.blockId),
         chosenContextIds: input.compileResult.ok ? input.compileResult.compileResponse.selectedContext.map((block) => block.id) : [],
         candidateScores: ranked.map((entry, index) => ({
             blockId: entry.blockId,
-            source: entry.source,
             selected: selectedIds.has(entry.blockId),
-            compactedFrom: entry.compactedFrom ?? [],
-            matchedTokens: [...entry.matchedTokens],
-            routingChannels: [...entry.routingChannels],
-            channelScores: {
-                graph: roundNumber(entry.channelScores.graph),
-                shortTerm: roundNumber(entry.channelScores.shortTerm),
-                vector: roundNumber(entry.channelScores.vector)
-            },
-            routeFnScore: roundNumber(entry.score),
             actionScore: roundNumber(entry.score),
-            actionProbability: probabilities[index] ?? 0,
-            actionLogProbability: probabilities[index] === undefined || probabilities[index] <= 0 ? null : roundNumber(Math.log(probabilities[index])),
-            traversalScore: roundNumber(entry.traversalScore ?? 0),
-            priority: entry.priority
+            actionProbability: probabilities[index] ?? 0
         })),
-        structuralSignals: input.compileResult.ok ? input.compileResult.compileResponse.diagnostics.structuralSignals : null,
+        structuralSignals: compactStructuralSignals(input.compileResult.ok ? input.compileResult.compileResponse.structuralSignals : null),
         fallbackReason: serveFallbackReason(input.compileResult),
         hotPathTiming: input.compileResult.timing,
         kernelContextCount: selectedKernelContextIds.length,
@@ -458,4 +488,4 @@ export function appendLearningUpdateLogs(input) {
         pgRouteUpdate
     };
 }
-//# sourceMappingURL=learning-spine.js.map
+//# sourceMappingURL=learning-spine.js.map

package/dist/src/local-learner.d.ts

@@ -81,6 +81,35 @@ export interface CandidatePackPayloads {
     vectors: PackVectorsPayloadV1;
     router: RouterArtifactV1 | null;
 }
+export interface TeacherObservationBindingStatsV1 {
+    totalObservationCount: number;
+    nonZeroObservationCount: number;
+    skippedZeroRewardCount: number;
+    accounting: {
+        exact: number;
+        heuristic: number;
+        unmatched: number;
+        ambiguous: number;
+    };
+    matched: {
+        exactDecisionId: number;
+        exactSelectionDigest: number;
+        turnCompileEventId: number;
+        legacyHeuristic: number;
+    };
+    unmatched: {
+        exactDecisionId: number;
+        exactSelectionDigest: number;
+        turnCompileEventId: number;
+        legacyHeuristic: number;
+    };
+    ambiguous: {
+        exactDecisionId: number;
+        exactSelectionDigest: number;
+        turnCompileEventId: number;
+        legacyHeuristic: number;
+    };
+}
 export interface CandidatePackBuildResult {
     manifest: ArtifactManifestV1;
     payloads: CandidatePackPayloads;
@@ -91,6 +120,7 @@ export interface CandidatePackBuildResult {
         decisionLogCount: number;
         fallbackReason: string | null;
         updatedBaseline: BaselineStateV1 | null;
+        observationBindingStats: TeacherObservationBindingStatsV1 | null;
     };
     summary: {
         packId: string;