@openclawbrain/openclaw 0.1.1 → 0.1.2

package/README.md

@@ -1,16 +1,66 @@
 # @openclawbrain/openclaw
 
-OpenClaw-facing runtime integration helpers for the TypeScript-first OpenClawBrain stack.
+OpenClaw integration helpers for promoted-pack compile consumption and normalized event emission.
 
-Use this package when OpenClaw needs a narrow, typed bridge over promoted packs without giving up runtime ownership:
+Use this package when OpenClaw needs a narrow, typed bridge over promoted packs:
 
+- bootstrap an initial attach pack from a normalized export and activate it
 - resolve the active promoted pack from activation pointers
-- consume `runtime_compile.v1` through a strict fail-open helper
+- consume `runtime_compile.v1` through an activation-aware serve-path helper
+- surface compact attach status over activation health, active pack freshness, and compile/handoff evidence
+- surface learned-route diagnostics alongside compiled context
 - emit normalized interaction and feedback events for learner handoff
 - optionally write learner-facing event-export bundles on disk
+- run a bounded async teacher loop that converts normalized exports into canonical supervision artifacts and future learner inputs
+- feed learner-side PG route refreshes only with explicit collected labels rather than heuristic learned-label propagation
+- keep the post-attach loop real with canonical supervision, bounded learner refresh, candidate promotion, and later compile freshness
+
+The post-attach loop stays off the hot path: it exports turns, builds candidate packs, and promotes them later rather than mutating the current active pack in place.
 
 ```ts
-import { compileRuntimeContext, runRuntimeTurn } from "@openclawbrain/openclaw";
+import {
+  bootstrapRuntimeAttach,
+  compileRuntimeContext,
+  describeAttachStatus,
+  rollbackRuntimeAttach,
+  runContinuousProductLoopTurn,
+  runRuntimeTurn
+} from "@openclawbrain/openclaw";
+
+const attach = bootstrapRuntimeAttach({
+  activationRoot: "/var/openclawbrain/activation",
+  packRoot: "/var/openclawbrain/packs/bootstrap",
+  packLabel: "customer-launch-attach",
+  workspace: {
+    workspaceId: "workspace-1",
+    snapshotId: "workspace-1@snapshot-1",
+    capturedAt: "2026-03-07T16:59:00.000Z",
+    rootDir: "/workspace/openclawbrain",
+    revision: "attach-rev-1"
+  },
+  interactionEvents: [],
+  feedbackEvents: []
+});
+
+console.log(attach.status.successSignals);
+
+const attachStatus = describeAttachStatus({
+  activationRoot: "/var/openclawbrain/activation"
+});
+
+console.log(attachStatus.inspection.active?.packId);
+console.log(attachStatus.compile?.handoffState);
+console.log(attachStatus.landingBoundaries.compileBoundary.activationSlot);
+console.log(attachStatus.landingBoundaries.failOpenSemantics.eventExportWriteFailurePreservesCompile);
+
+const rollbackPreview = rollbackRuntimeAttach({
+  activationRoot: "/var/openclawbrain/activation",
+  dryRun: true
+});
+
+console.log(rollbackPreview.allowed);
+console.log(rollbackPreview.before.activePackId);
+console.log(rollbackPreview.after?.activePackId);
 
 const compileResult = compileRuntimeContext({
   activationRoot: "/var/openclawbrain/activation",
@@ -18,6 +68,11 @@ const compileResult = compileRuntimeContext({
   runtimeHints: ["feedback scanner"]
 });
 
+if (compileResult.ok) {
+  console.log(compileResult.compileResponse.diagnostics.usedLearnedRouteFn);
+  console.log(compileResult.compileResponse.diagnostics.routerIdentity);
+}
+
 const turnResult = runRuntimeTurn(
   {
     sessionId: "session-123",
@@ -38,6 +93,66 @@ const turnResult = runRuntimeTurn(
     activationRoot: "/var/openclawbrain/activation"
   }
 );
+
+const productLoopTurn = runContinuousProductLoopTurn({
+  activationRoot: "/var/openclawbrain/activation",
+  loopRoot: "/var/openclawbrain/runtime-loop",
+  packLabel: "post-attach-loop",
+  workspace: {
+    workspaceId: "workspace-1",
+    snapshotId: "workspace-1@snapshot-2",
+    capturedAt: "2026-03-07T18:00:30.000Z",
+    rootDir: "/workspace/openclawbrain",
+    revision: "runtime-loop-rev-2"
+  },
+  turn: {
+    sessionId: "session-123",
+    channel: "whatsapp",
+    userMessage: "Compile the fresher learned route artifact after promotion.",
+    feedback: [{ content: "Prefer the fresher learned route artifact after promotion." }]
+  }
+});
+
+console.log(productLoopTurn.compileActiveVersion);
+console.log(productLoopTurn.learning.promoted);
+console.log(productLoopTurn.state.currentActivePack?.routerIdentity);
+```
+
+This package stays fail-open for non-learned-required compile misses, and event-export write failures do not erase successful compile output.
+
+## Boundary truth
+
+`describeAttachStatus()` now returns `landingBoundaries`, a compact runtime-facing statement of the actual OpenClaw handoff:
+
+- `compileBoundary`: OpenClaw compiles only from activation's `active` slot through `compileRuntimeContext()` / `runtime_compile.v1`
+- `eventExportBoundary`: `runRuntimeTurn()` emits normalized interaction/feedback exports for later learning handoff, and bundle-write failure does not erase successful compile output
+- `activePackBoundary`: `active` is the only serve-visible slot; `candidate` and `previous` stay inspectable until promotion or rollback changes pointers
+- `promotionBoundary`: learner refresh lands in `candidate`, activation promotion flips pointers, and only later compiles can see the fresher pack
+- `failOpenSemantics`: missing active packs fail open, but learned-required route-artifact drift hard-fails instead of silently serving static context
+- `runtimeResponsibilities`: OpenClaw remains responsible for runtime orchestration, prompt assembly, response delivery, and guarded serve-path decisions
+
+Operator-facing CLI:
+
+```bash
+pnpm exec openclawbrain-ops status --activation-root /var/openclawbrain/activation --event-export /var/openclawbrain/exports/latest --teacher-snapshot /var/openclawbrain/runtime/teacher-snapshot.json
+pnpm exec openclawbrain-ops doctor --activation-root /var/openclawbrain/activation --event-export /var/openclawbrain/exports/latest --teacher-snapshot /var/openclawbrain/runtime/teacher-snapshot.json
+pnpm exec openclawbrain-ops rollback --activation-root /var/openclawbrain/activation --dry-run
 ```
 
-This package stays fail-open by default: compile failures fall back to standard OpenClaw context injection, and event-export write failures do not erase successful compile output.
+- `status` prints a compressed one-screen summary of active/candidate pack truth, brain handoff state, serve-path fail-open status, route freshness, supervision flow, live-vs-backfill learning mode, the last async no-op reason, and rollback readiness
+- `doctor` prints explicit `PASS` / `WARN` / `FAIL` findings and exits `1` only when a hard serve-path failure exists
+- `rollback --dry-run` previews the exact `active <- previous` and `active -> candidate` move before you apply rollback for real
+- `--event-export` accepts either a runtime event-export bundle root or a normalized-export JSON payload
+- `--teacher-snapshot` accepts JSON from `teacherLoop.snapshot()` or `await teacherLoop.flush()` when you want the last duplicate/no-op reason plus learner bootstrapped/mode/next-lane backlog truth kept visible
+
+Programmatic rollback is available too:
+
+- `rollbackRuntimeAttach({ activationRoot, dryRun: true })` previews the move without changing activation pointers
+- `rollbackRuntimeAttach({ activationRoot })` applies the rollback and reports which pack was restored to `active`
+
+The learned-required serve path is stricter:
+
+- `compileRuntimeContext()` now forwards the active-slot diagnostics from `@openclawbrain/compiler.compileRuntimeFromActivation()`
+- learned-required active packs return `hardRequirementViolated=true` and `fallbackToStaticContext=false` when route artifacts drift or disappear
+- `runRuntimeTurn()` throws instead of silently serving through those learned-required failures
+- event-export write failures still do not erase successful compile output

package/dist/src/cli.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { type OperatorSurfaceInput } from "./index.js";
+interface ParsedOperatorCliArgs {
+    command: "status" | "doctor" | "rollback";
+    input: OperatorSurfaceInput;
+    json: boolean;
+    help: boolean;
+    dryRun: boolean;
+}
+export declare function parseOperatorCliArgs(argv: readonly string[]): ParsedOperatorCliArgs;
+export declare function runOperatorCli(argv?: readonly string[]): number;
+export {};

package/dist/src/cli.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { buildOperatorSurfaceReport, formatOperatorDoctorReport, formatOperatorRollbackReport, formatOperatorStatusReport, rollbackRuntimeAttach } from "./index.js";
+function operatorCliHelp() {
+    return [
+        "Usage:",
+        "  openclawbrain-ops <status|doctor|rollback> --activation-root <path> [options]",
+        "",
+        "Options:",
+        "  --activation-root <path>    Activation root to inspect.",
+        "  --event-export <path>       Event-export bundle root or normalized export JSON payload.",
+        "  --teacher-snapshot <path>   Async teacher snapshot JSON from teacherLoop.snapshot()/flush().",
+        "  --updated-at <iso>          Observation time to use for freshness checks.",
+        "  --dry-run                   Preview rollback pointer movement without writing activation state.",
+        "  --json                      Emit machine-readable JSON instead of text.",
+        "  --help                      Show this help.",
+        "",
+        "Common flow:",
+        "  1. status   quick attach / first-value / rollback summary",
+        "  2. doctor   explicit PASS / WARN / FAIL findings",
+        "  3. rollback --dry-run   preview active <- previous, active -> candidate",
+        "  4. rollback             apply the rollback when the preview says ready",
+        "",
+        "Exit codes:",
+        "  status: 0 on successful inspection, 1 on input/read failure.",
+        "  doctor: 0 when no FAIL findings are present, 1 otherwise.",
+        "  rollback: 0 when ready/applied, 1 when blocked or on input/read failure."
+    ].join("\n");
+}
+export function parseOperatorCliArgs(argv) {
+    let command = "status";
+    let activationRoot = null;
+    let eventExportPath = null;
+    let teacherSnapshotPath = null;
+    let updatedAt = null;
+    let json = false;
+    let help = false;
+    let dryRun = false;
+    const args = [...argv];
+    if (args[0] === "status" || args[0] === "doctor" || args[0] === "rollback") {
+        command = args.shift();
+    }
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--help" || arg === "-h") {
+            help = true;
+            continue;
+        }
+        if (arg === "--json") {
+            json = true;
+            continue;
+        }
+        if (arg === "--dry-run") {
+            dryRun = true;
+            continue;
+        }
+        const next = args[index + 1];
+        if (arg === "--activation-root") {
+            if (next === undefined) {
+                throw new Error("--activation-root requires a value");
+            }
+            activationRoot = next;
+            index += 1;
+            continue;
+        }
+        if (arg === "--event-export") {
+            if (next === undefined) {
+                throw new Error("--event-export requires a value");
+            }
+            eventExportPath = next;
+            index += 1;
+            continue;
+        }
+        if (arg === "--teacher-snapshot") {
+            if (next === undefined) {
+                throw new Error("--teacher-snapshot requires a value");
+            }
+            teacherSnapshotPath = next;
+            index += 1;
+            continue;
+        }
+        if (arg === "--updated-at") {
+            if (next === undefined) {
+                throw new Error("--updated-at requires a value");
+            }
+            updatedAt = next;
+            index += 1;
+            continue;
+        }
+        throw new Error(`unknown argument: ${arg}`);
+    }
+    return {
+        command,
+        input: {
+            activationRoot: activationRoot ?? "",
+            eventExportPath,
+            teacherSnapshotPath,
+            updatedAt
+        },
+        json,
+        help,
+        dryRun
+    };
+}
+export function runOperatorCli(argv = process.argv.slice(2)) {
+    const parsed = parseOperatorCliArgs(argv);
+    if (parsed.help) {
+        console.log(operatorCliHelp());
+        return 0;
+    }
+    const activationRoot = path.resolve(parsed.input.activationRoot);
+    if (parsed.command === "rollback") {
+        const result = rollbackRuntimeAttach({
+            activationRoot,
+            ...(parsed.input.updatedAt === null ? {} : { updatedAt: parsed.input.updatedAt }),
+            dryRun: parsed.dryRun
+        });
+        if (parsed.json) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            console.log(formatOperatorRollbackReport(result));
+        }
+        return result.allowed ? 0 : 1;
+    }
+    const report = buildOperatorSurfaceReport({
+        ...parsed.input,
+        activationRoot
+    });
+    if (parsed.json) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else if (parsed.command === "doctor") {
+        console.log(formatOperatorDoctorReport(report));
+    }
+    else {
+        console.log(formatOperatorStatusReport(report));
+    }
+    return parsed.command === "doctor" && report.status === "fail" ? 1 : 0;
+}
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    try {
+        process.exitCode = runOperatorCli();
+    }
+    catch (error) {
+        console.error("[openclawbrain-ops] failed");
+        console.error(error instanceof Error ? error.stack ?? error.message : String(error));
+        process.exitCode = 1;
+    }
+}
+//# sourceMappingURL=cli.js.map

package/dist/src/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"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"}