@openclawbrain/openclaw 0.1.11 → 0.2.0

package/README.md

@@ -5,10 +5,11 @@ OpenClaw integration helpers for promoted-pack compile consumption and normalize
 This is the default front door for first-time OpenClawBrain users.
 
 - Start here when you want one package to import from instead of guessing across the `@openclawbrain/*` split.
-- Install it with `npm install @openclawbrain/openclaw`.
-- Use the `openclawbrain` CLI for status and rollback; `openclawbrain-ops` stays available as a compatibility alias.
-- `npm exec openclawbrain -- --help` now works from the installed package surface, but the exact quickstart commands remain the clearest first attach path.
-- Use local `.release/*.tgz` tarballs only for maintainer repo-tip / release-validation fallback, not as the default outside-user front door.
+- The stable front-door names are `@openclawbrain/openclaw` and `openclawbrain`.
+- If you are validating this repo-tip checkout, prepare the checkout with `pnpm install --frozen-lockfile`, run `pnpm release:status`, then `pnpm release:pack`, then install the local `.release/*.tgz` tarballs.
+- If you are intentionally consuming a later tagged and published wave, install it with `npm install @openclawbrain/openclaw`.
+- Use the `openclawbrain` CLI for status, rollback, and narrow scanner scans; `openclawbrain-ops` stays available as a compatibility alias.
+- `npm exec openclawbrain -- --help` works after either install path, but the exact quickstart commands remain the clearest first attach path.
 
 Use this package when OpenClaw needs the narrow supported operator bridge captured by `OPERATOR_API_CONTRACT_V1`:
 
@@ -142,16 +143,22 @@ Operator-facing CLI:
 ```bash
 pnpm exec openclawbrain status --activation-root /var/openclawbrain/activation --event-export /var/openclawbrain/exports/latest --teacher-snapshot /var/openclawbrain/runtime/teacher-snapshot.json
 pnpm exec openclawbrain rollback --activation-root /var/openclawbrain/activation --dry-run
+pnpm exec openclawbrain scan --session ./fixtures/recorded-session-replay/sanitized-support-escalation.trace.json --root /tmp/openclawbrain-scan-session
+pnpm exec openclawbrain scan --live /var/openclawbrain/exports/latest --workspace /var/openclawbrain/runtime/workspace.json --snapshot-out /var/openclawbrain/runtime/scan-live-snapshot.json
 ```
 
 - `openclawbrain-ops` remains available as the same CLI entrypoint if you already scripted against the older name
 - `bootstrapRuntimeAttach()` resolves the activation root, stamps the attach as a `current_profile` action, returns the canonical current-profile answer immediately, and includes copy-paste-ready next steps for the attached root that prefer the primary `openclawbrain` CLI while matching the current `npm`/`pnpm` invocation style when it is detectable; those hints now cover `status`, canonical `status --json`, and `rollback --dry-run`
+- `resolveActivationRoot()` keeps the existing explicit-path and global fallback chain, and same-gateway hosts with multiple `~/.openclaw-*` homes can now pin resolution to one installed OpenClaw profile home via `openclawHome` or `OPENCLAW_HOME`
 - `formatBootstrapRuntimeAttachReport()` prints the shipped attach handoff as a current-profile action instead of dropping callers straight into lower-level proof fields
-- plain `status` is the human answer to “How's the brain?” for the current profile on that activation root; it now keeps principal backlog/downstream truth and active structural-graph evolution visible in the compact text summary, while `status --json` still emits the canonical `current_profile_brain_status.v1` answer from that same boundary
+- plain `status` is the human answer to “How's the brain?” for the current profile on that activation root; it now keeps the principal backlog frontier (`learnedThrough -> newestPending`), live-vs-backfill passive-learning progress, explicit backlog warning states, structural-decision origin, and active structural-graph evolution visible in the compact text summary, while `status --json` still emits the canonical `current_profile_brain_status.v1` answer from that same boundary
+- with `--teacher-snapshot`, that same human summary also keeps the learner `mode`, next lane, and exact scheduler `priority` bucket visible so operators can see live-first intake, principal-priority work, and passive backfill without pretending the canonical JSON object widened
 - `describeCurrentProfileBrainStatus()` freezes the current-profile `Host / Profile / Brain / Attachment` answer shape instead of widening to a second report payload
 - `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
+- `--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/scheduler-priority truth kept visible
+- `scan --session` is a checked-in proof-facing replay over a sanitized recorded-session trace; it reports the no-brain vs seed-pack vs learned-replay score spread and does not pretend to be the runtime hot path
+- `scan --live` is a one-shot live-export scan over a real event-export payload plus explicit workspace metadata; it truthfully reports teacher/learner state for that export and does not pretend a background daemon is running
 
 Programmatic rollback is available too:
 

package/dist/src/cli.d.ts

@@ -1,12 +1,96 @@
 #!/usr/bin/env node
+import { type DaemonCliArgs } from "./daemon.js";
 import { type CurrentProfileBrainStatusInput } from "./index.js";
-interface ParsedOperatorCliArgs {
+interface ParsedStatusRollbackCliArgs {
     command: "status" | "rollback";
     input: CurrentProfileBrainStatusInput;
     json: boolean;
     help: boolean;
     dryRun: boolean;
+    detailed: boolean;
 }
+interface ParsedAttachCliArgs {
+    command: "attach";
+    activationRoot: string;
+    packRoot: string;
+    packLabel: string;
+    workspaceId: string;
+    brainAttachmentPolicy: CurrentProfileBrainStatusInput["brainAttachmentPolicy"];
+    json: boolean;
+    help: boolean;
+}
+interface ParsedSetupCliArgs {
+    command: "setup";
+    openclawHome: string;
+    activationRoot: string;
+    shared: boolean;
+    workspaceId: string;
+    json: boolean;
+    help: boolean;
+}
+interface ParsedScanCliArgs {
+    command: "scan";
+    json: boolean;
+    help: boolean;
+    sessionPath: string | null;
+    livePath: string | null;
+    rootDir: string | null;
+    workspacePath: string | null;
+    packLabel: string | null;
+    observedAt: string | null;
+    snapshotOutPath: string | null;
+}
+interface ParsedContextCliArgs {
+    command: "context";
+    message: string;
+    activationRoot: string;
+    json: boolean;
+    help: boolean;
+}
+interface ParsedHistoryCliArgs {
+    command: "history";
+    activationRoot: string;
+    limit: number;
+    json: boolean;
+    help: boolean;
+}
+interface ParsedLearnCliArgs {
+    command: "learn";
+    activationRoot: string;
+    json: boolean;
+    help: boolean;
+}
+interface ParsedWatchCliArgs {
+    command: "watch";
+    activationRoot: string;
+    scanRoot: string | null;
+    interval: number;
+    json: boolean;
+    help: boolean;
+}
+interface ParsedExportCliArgs {
+    command: "export";
+    activationRoot: string;
+    outputPath: string;
+    json: boolean;
+    help: boolean;
+}
+interface ParsedImportCliArgs {
+    command: "import";
+    archivePath: string;
+    activationRoot: string;
+    force: boolean;
+    json: boolean;
+    help: boolean;
+}
+interface ParsedResetCliArgs {
+    command: "reset";
+    activationRoot: string;
+    yes: boolean;
+    json: boolean;
+    help: boolean;
+}
+type ParsedOperatorCliArgs = ParsedStatusRollbackCliArgs | ParsedAttachCliArgs | ParsedScanCliArgs | ParsedSetupCliArgs | ParsedContextCliArgs | ParsedHistoryCliArgs | ParsedLearnCliArgs | ParsedWatchCliArgs | DaemonCliArgs | ParsedExportCliArgs | ParsedImportCliArgs | ParsedResetCliArgs;
 export declare function parseOperatorCliArgs(argv: readonly string[]): ParsedOperatorCliArgs;
 export declare function runOperatorCli(argv?: readonly string[]): number;
 export {};