@jonathangu/openclawbrain 0.3.0 → 0.3.1

package/index.ts

@@ -1270,6 +1270,194 @@ function createLcmDependencies(api: OpenClawPluginApi): LcmDependencies {
   };
 }
 
+type ContextEngineRegisteringApi = OpenClawPluginApi & {
+  registerContextEngine?: (id: string, factory: () => unknown) => void;
+};
+
+function normalizePromptText(value: unknown): string {
+  if (typeof value === "string") {
+    return value.trim();
+  }
+  if (Array.isArray(value)) {
+    return value
+      .map((entry) => normalizePromptText(entry))
+      .filter((entry) => entry.length > 0)
+      .join("\n")
+      .trim();
+  }
+  if (!value || typeof value !== "object") {
+    return "";
+  }
+
+  const record = value as Record<string, unknown>;
+  return [
+    normalizePromptText(record.text),
+    normalizePromptText(record.content),
+    normalizePromptText(record.value),
+    normalizePromptText(record.thinking),
+    normalizePromptText(record.summary),
+  ]
+    .filter((entry, index, arr) => entry.length > 0 && arr.indexOf(entry) === index)
+    .join("\n")
+    .trim();
+}
+
+function normalizePromptRole(message: unknown): string {
+  if (!message || typeof message !== "object") {
+    return "message";
+  }
+  const role = (message as { role?: unknown }).role;
+  return typeof role === "string" && role.trim().length > 0 ? role.trim() : "message";
+}
+
+function promptMessageSignature(message: unknown): string {
+  if (!message || typeof message !== "object") {
+    return JSON.stringify(message);
+  }
+  const record = message as Record<string, unknown>;
+  return JSON.stringify({
+    role: normalizePromptRole(record),
+    content: normalizePromptText(record.content),
+  });
+}
+
+function extractPrependedMessages(assembledMessages: unknown[], liveMessages: unknown[]): unknown[] {
+  if (assembledMessages.length === 0) {
+    return [];
+  }
+  if (liveMessages.length === 0) {
+    return assembledMessages;
+  }
+
+  const assembledSignatures = assembledMessages.map((message) => promptMessageSignature(message));
+  const liveSignatures = liveMessages.map((message) => promptMessageSignature(message));
+  const maxOverlap = Math.min(assembledSignatures.length, liveSignatures.length);
+
+  for (let overlap = maxOverlap; overlap > 0; overlap -= 1) {
+    const assembledTail = assembledSignatures.slice(-overlap);
+    const liveTail = liveSignatures.slice(-overlap);
+    if (assembledTail.join("\u0000") === liveTail.join("\u0000")) {
+      return assembledMessages.slice(0, assembledMessages.length - overlap);
+    }
+  }
+
+  return assembledMessages;
+}
+
+function formatPrependedContext(messages: unknown[], systemPromptAddition?: string): string | undefined {
+  const sections: string[] = [];
+  const promptAddition = typeof systemPromptAddition === "string" ? systemPromptAddition.trim() : "";
+  if (promptAddition) {
+    sections.push(promptAddition);
+  }
+
+  const renderedMessages = messages
+    .map((message) => {
+      const text = normalizePromptText((message as { content?: unknown } | null)?.content);
+      if (!text) {
+        return "";
+      }
+      return `### ${normalizePromptRole(message)}\n${text}`;
+    })
+    .filter((entry) => entry.length > 0);
+
+  if (renderedMessages.length > 0) {
+    sections.push([
+      "## OpenClawBrain recalled context",
+      "",
+      renderedMessages.join("\n\n"),
+    ].join("\n"));
+  }
+
+  if (sections.length === 0) {
+    return undefined;
+  }
+  return sections.join("\n\n");
+}
+
+function registerHookCompatibilityBridge(
+  api: OpenClawPluginApi,
+  lcm: LcmContextEngine,
+  deps: ReturnType<typeof createLcmDependencies>,
+): void {
+  const prePromptMessageCounts = new Map<string, number>();
+  const sessionIdsByKey = new Map<string, string>();
+
+  const rememberSession = (sessionId?: string | null, sessionKey?: string | null) => {
+    if (typeof sessionId === "string" && sessionId.trim().length > 0 && typeof sessionKey === "string" && sessionKey.trim().length > 0) {
+      sessionIdsByKey.set(sessionKey.trim(), sessionId.trim());
+    }
+  };
+
+  const resolveHookSessionId = async (ctx: { sessionId?: string; sessionKey?: string }): Promise<string | undefined> => {
+    if (typeof ctx.sessionId === "string" && ctx.sessionId.trim().length > 0) {
+      rememberSession(ctx.sessionId, ctx.sessionKey);
+      return ctx.sessionId.trim();
+    }
+    if (typeof ctx.sessionKey === "string" && ctx.sessionKey.trim().length > 0) {
+      const key = ctx.sessionKey.trim();
+      const remembered = sessionIdsByKey.get(key);
+      if (remembered) {
+        return remembered;
+      }
+      const resolved = await deps.resolveSessionIdFromSessionKey(key);
+      if (resolved) {
+        sessionIdsByKey.set(key, resolved);
+        return resolved;
+      }
+      return key;
+    }
+    return undefined;
+  };
+
+  api.on("before_prompt_build", async (event, ctx) => {
+    const sessionId = await resolveHookSessionId(ctx);
+    if (!sessionId) {
+      return undefined;
+    }
+    prePromptMessageCounts.set(sessionId, Array.isArray(event.messages) ? event.messages.length : 0);
+
+    const assembled = await lcm.assemble({
+      sessionId,
+      messages: Array.isArray(event.messages) ? event.messages as Parameters<LcmContextEngine["assemble"]>[0]["messages"] : [],
+    }) as AssembleResultWithSystemPrompt;
+    const prependedMessages = extractPrependedMessages(assembled.messages as unknown[], Array.isArray(event.messages) ? event.messages : []);
+    const prependContext = formatPrependedContext(prependedMessages, assembled.systemPromptAddition);
+    if (!prependContext) {
+      return undefined;
+    }
+    return { prependContext };
+  });
+
+  api.on("agent_end", async (event, ctx) => {
+    const sessionId = await resolveHookSessionId(ctx);
+    if (!sessionId) {
+      return;
+    }
+    const prePromptMessageCount = prePromptMessageCounts.get(sessionId) ?? 0;
+    prePromptMessageCounts.delete(sessionId);
+    await lcm.afterTurn({
+      sessionId,
+      sessionFile: "",
+      messages: Array.isArray(event.messages) ? event.messages as Parameters<LcmContextEngine["afterTurn"]>[0]["messages"] : [],
+      prePromptMessageCount,
+    });
+  });
+
+  api.on("session_end", async (_event, ctx) => {
+    prePromptMessageCounts.delete(ctx.sessionId);
+    for (const [sessionKey, sessionId] of sessionIdsByKey.entries()) {
+      if (sessionId === ctx.sessionId) {
+        sessionIdsByKey.delete(sessionKey);
+      }
+    }
+  });
+
+  api.logger.warn(
+    "[openclawbrain] registerContextEngine unavailable; using hook compatibility bridge for prompt assembly/after-turn ingest.",
+  );
+}
+
 const lcmPlugin = {
   id: "openclawbrain",
   name: "OpenClawBrain",
@@ -1290,7 +1478,12 @@ const lcmPlugin = {
     const deps = createLcmDependencies(api);
     const lcm = new LcmContextEngine(deps);
 
-    api.registerContextEngine("openclawbrain", () => lcm);
+    const contextApi = api as ContextEngineRegisteringApi;
+    if (typeof contextApi.registerContextEngine === "function") {
+      contextApi.registerContextEngine("openclawbrain", () => lcm);
+    } else {
+      registerHookCompatibilityBridge(api, lcm, deps);
+    }
     api.registerTool((ctx) =>
       createLcmGrepTool({
         deps,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jonathangu/openclawbrain",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "OpenClawBrain v2 for OpenClaw — lossless transcript memory with a clean learning-layer rebuild",
   "type": "module",
   "main": "index.ts",

package/src/brain-cli.ts

@@ -20,6 +20,17 @@ function printJson(payload: unknown): void {
   process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
 }
 
+function buildInitLog(): { info: (msg: string) => void; warn: (msg: string) => void } {
+  const verbose = /^(1|true|yes)$/i.test(process.env.OPENCLAWBRAIN_INIT_VERBOSE ?? "");
+  if (!verbose) {
+    return { info: () => {}, warn: () => {} };
+  }
+  return {
+    info: (msg: string) => process.stderr.write(`${msg}\n`),
+    warn: (msg: string) => process.stderr.write(`${msg}\n`),
+  };
+}
+
 function usage(): never {
   process.stderr.write(
     "Usage: openclawbrain <init|status|trace|replay|promote|rollback|disable|enable|doctor> [args]\n",
@@ -68,7 +79,7 @@ async function commandInit(workspaceArg?: string): Promise<void> {
     workspaceRoot,
     embedFn,
     semanticThreshold: brainConfig.semanticThreshold,
-    log: { info: () => {}, warn: () => {} },
+    log: buildInitLog(),
   });
 
   store.clearGraph();

package/src/brain-harvest/scanner.ts

@@ -1,4 +1,4 @@
-import type { HarvestResult } from "../brain-runtime/evidence-detectors.js";
+import type { HarvestMessagePart, HarvestResult } from "../brain-runtime/evidence-detectors.js";
 
 const EXPLICIT_SCANNER_PATTERNS = [
   /\bexpand for details about\b/i,
@@ -16,6 +16,20 @@ const BULLET_PATTERN = /^\s*[-*]\s+\S.+$/gm;
 const HEADING_PATTERN = /^\s{0,3}#{1,6}\s+\S.+$/m;
 const FILE_REF_PATTERN = /(?:^|[\s(])(?:\.?\/)?[\w./-]+\.(?:md|txt|ts|tsx|js|jsx|json|yaml|yml|sh|mjs)(?=$|[\s):,])/gim;
 const IMPERATIVE_STEP_PATTERN = /^\s*(?:[-*]\s+|\d+\.\s+)?(?:inspect|check|retry|run|use|open|read|edit|verify|restart|re-?run|apply|deploy|create|install|record|compare|promote|rollback)\b/gim;
+const STRUCTURED_TOOL_NAMES = new Set(["bash", "git", "gh", "pnpm", "npm", "node", "openclaw", "python", "python3", "curl", "ollama", "codex", "claude"]);
+const STRUCTURED_GUIDANCE_PART_TYPES = new Set(["file", "snapshot", "subtask", "patch", "compaction", "step_start", "step_finish", "retry"]);
+
+type ContentSignalSummary = {
+  docMarker: string | null;
+  numberedSteps: number;
+  bulletLines: number;
+  commandLines: number;
+  imperativeLines: number;
+  hasHeading: boolean;
+  fileRefs: number;
+  score: number;
+  signals: string[];
+};
 
 function countMatches(pattern: RegExp, content: string): number {
   const flags = pattern.flags.includes("g") ? pattern.flags : `${pattern.flags}g`;
@@ -23,25 +37,132 @@ function countMatches(pattern: RegExp, content: string): number {
   return Array.from(content.matchAll(matcher)).length;
 }
 
-export function detectScannerEvidence(content: string): HarvestResult | null {
-  for (const pattern of EXPLICIT_SCANNER_PATTERNS) {
-    if (pattern.test(content)) {
-      return {
-        value: 0.25,
-        source: "scanner",
-        reason: `scanner marker: ${pattern.source}`,
-        confidence: 0.7,
-        kind: "scanner_signal",
-        extractor: "scanner_marker",
-      };
+function parseJson(value: string | null | undefined): unknown {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    return null;
+  }
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : null;
+}
+
+function readPartMetadata(part: HarvestMessagePart): Record<string, unknown> {
+  return asRecord(parseJson(part.metadata)) ?? {};
+}
+
+function readString(record: Record<string, unknown> | null, keys: string[]): string | undefined {
+  if (!record) {
+    return undefined;
+  }
+  for (const key of keys) {
+    const value = record[key];
+    if (typeof value === "string" && value.trim().length > 0) {
+      return value.trim();
     }
   }
+  return undefined;
+}
 
+function readStringArray(value: unknown): string[] {
+  if (Array.isArray(value)) {
+    return value.filter((entry): entry is string => typeof entry === "string" && entry.trim().length > 0);
+  }
+  if (typeof value === "string" && value.trim().length > 0) {
+    return [value.trim()];
+  }
+  return [];
+}
+
+function readCommand(value: unknown): string | undefined {
+  if (typeof value === "string" && value.trim().length > 0) {
+    return value.trim();
+  }
+  if (Array.isArray(value)) {
+    const parts = value.filter((entry): entry is string => typeof entry === "string" && entry.trim().length > 0);
+    return parts.length > 0 ? parts.join(" ") : undefined;
+  }
+  return undefined;
+}
+
+function extractCommand(input: unknown): string | undefined {
+  const inputRecord = asRecord(input);
+  return readString(inputRecord, ["command", "cmd", "shellCommand"])
+    ?? readCommand(inputRecord?.args)
+    ?? (typeof input === "string" && input.trim().length > 0 ? input.trim() : undefined);
+}
+
+function collectStructuredFileHints(part: HarvestMessagePart, metadata: Record<string, unknown>): string[] {
+  const parsedInput = parseJson(part.toolInput);
+  const parsedOutput = parseJson(part.toolOutput);
+  const inputRecord = asRecord(parsedInput);
+  const outputRecord = asRecord(parsedOutput);
+  const rawRecord = asRecord(metadata.raw);
+  const collected = new Set<string>();
+
+  for (const value of [
+    outputRecord?.filesTouched,
+    outputRecord?.changedFiles,
+    outputRecord?.files,
+    outputRecord?.paths,
+    inputRecord?.filesTouched,
+    inputRecord?.files,
+    inputRecord?.paths,
+    readString(outputRecord, ["artifactPath", "outputPath", "reportPath", "logPath", "filePath", "path"]),
+    readString(inputRecord, ["artifactPath", "outputPath", "reportPath", "logPath", "filePath", "path"]),
+    readString(rawRecord, ["path", "filePath", "artifactPath"]),
+  ]) {
+    for (const item of readStringArray(value)) {
+      collected.add(item);
+    }
+  }
+
+  return Array.from(collected);
+}
+
+function collectStructuredPartDetails(part: HarvestMessagePart, metadata: Record<string, unknown>): {
+  paths: string[];
+  labels: string[];
+} {
+  const rawRecord = asRecord(metadata.raw);
+  const paths = new Set<string>();
+  const labels = new Set<string>();
+
+  for (const value of [
+    readString(rawRecord, ["path", "filePath", "artifactPath", "storageUri", "sourcePath", "targetPath", "outputPath"]),
+    readString(rawRecord, ["fileName", "title", "label", "name", "summaryId", "taskId", "stepId"]),
+    readString(rawRecord, ["summary", "description"]),
+    typeof part.textContent === "string" && part.textContent.trim().length > 0 ? part.textContent.trim() : undefined,
+  ]) {
+    for (const item of readStringArray(value)) {
+      if (/[/\\.]|^[A-Z0-9_-]+$/i.test(item)) {
+        paths.add(item);
+      }
+      labels.add(item);
+    }
+  }
+
+  return {
+    paths: Array.from(paths),
+    labels: Array.from(labels),
+  };
+}
+
+function collectContentSignals(content: string): ContentSignalSummary {
   const signals: string[] = [];
   let score = 0;
+  let docMarker: string | null = null;
 
   for (const pattern of DOC_MARKER_PATTERNS) {
     if (pattern.test(content)) {
+      docMarker = pattern.source;
       signals.push(`doc:${pattern.source}`);
       score += 1.0;
       break;
@@ -72,7 +193,8 @@ export function detectScannerEvidence(content: string): HarvestResult | null {
     score += 0.8;
   }
 
-  if (HEADING_PATTERN.test(content) && (numberedSteps >= 1 || bulletLines >= 2)) {
+  const hasHeading = HEADING_PATTERN.test(content);
+  if (hasHeading && (numberedSteps >= 1 || bulletLines >= 2)) {
     signals.push("heading");
     score += 0.4;
   }
@@ -83,16 +205,164 @@ export function detectScannerEvidence(content: string): HarvestResult | null {
     score += 0.3;
   }
 
-  if (score < 1.8) {
+  return {
+    docMarker,
+    numberedSteps,
+    bulletLines,
+    commandLines,
+    imperativeLines,
+    hasHeading,
+    fileRefs,
+    score,
+    signals,
+  };
+}
+
+function hasGuidanceShape(contentSignals: ContentSignalSummary): boolean {
+  return Boolean(contentSignals.docMarker)
+    || contentSignals.numberedSteps >= 2
+    || (contentSignals.hasHeading && contentSignals.bulletLines >= 2)
+    || contentSignals.imperativeLines >= 2;
+}
+
+function detectStructuredScannerEvidence(
+  contentSignals: ContentSignalSummary,
+  messageParts?: HarvestMessagePart[],
+): HarvestResult | null {
+  if (!messageParts || messageParts.length === 0 || !hasGuidanceShape(contentSignals)) {
+    return null;
+  }
+
+  const toolNames = new Set<string>();
+  const commands = new Set<string>();
+  const toolFileHints = new Set<string>();
+  const structuredPartTypes = new Set<string>();
+  const structuredPaths = new Set<string>();
+  const structuredLabels = new Set<string>();
+  const partOrdinals: number[] = [];
+  const rawTypes = new Set<string>();
+
+  for (const part of messageParts) {
+    const metadata = readPartMetadata(part);
+    const rawType = typeof metadata.rawType === "string" ? metadata.rawType : null;
+    if (rawType) {
+      rawTypes.add(rawType);
+    }
+
+    if (typeof part.ordinal === "number") {
+      partOrdinals.push(part.ordinal);
+    }
+
+    if (part.partType === "tool") {
+      const toolName = typeof part.toolName === "string" ? part.toolName.trim() : "";
+      if (toolName && STRUCTURED_TOOL_NAMES.has(toolName)) {
+        toolNames.add(toolName);
+      }
+
+      const command = extractCommand(parseJson(part.toolInput));
+      if (command) {
+        commands.add(command);
+      }
+
+      for (const hint of collectStructuredFileHints(part, metadata)) {
+        toolFileHints.add(hint);
+      }
+      continue;
+    }
+
+    if (STRUCTURED_GUIDANCE_PART_TYPES.has(part.partType)) {
+      structuredPartTypes.add(part.partType);
+      const details = collectStructuredPartDetails(part, metadata);
+      for (const path of details.paths) {
+        structuredPaths.add(path);
+      }
+      for (const label of details.labels) {
+        structuredLabels.add(label);
+      }
+    }
+  }
+
+  if (toolNames.size > 0 && (commands.size > 0 || toolFileHints.size > 0)) {
+    return {
+      value: 0.25,
+      source: "scanner",
+      reason: `scanner structured tool-chain: tools=${Array.from(toolNames).join(",")}`,
+      confidence: 0.85,
+      kind: "scanner_signal",
+      extractor: "structured_tool_chain",
+      metadata: {
+        toolNames: Array.from(toolNames),
+        commands: Array.from(commands),
+        fileHints: Array.from(toolFileHints),
+        partOrdinals,
+        rawTypes: Array.from(rawTypes),
+        guidanceSignals: contentSignals.signals,
+      },
+    };
+  }
+
+  if (structuredPartTypes.size === 0 || (structuredPaths.size === 0 && structuredLabels.size === 0)) {
+    return null;
+  }
+
+  return {
+    value: 0.25,
+    source: "scanner",
+    reason: `scanner structured guidance parts: ${Array.from(structuredPartTypes).join(",")}`,
+    confidence: 0.83,
+    kind: "scanner_signal",
+    extractor: "structured_guidance_parts",
+    metadata: {
+      structuredPartTypes: Array.from(structuredPartTypes),
+      pathHints: Array.from(structuredPaths),
+      labels: Array.from(structuredLabels),
+      partOrdinals,
+      rawTypes: Array.from(rawTypes),
+      guidanceSignals: contentSignals.signals,
+    },
+  };
+}
+
+export function detectScannerEvidence(content: string, messageParts?: HarvestMessagePart[]): HarvestResult | null {
+  for (const pattern of EXPLICIT_SCANNER_PATTERNS) {
+    if (pattern.test(content)) {
+      return {
+        value: 0.25,
+        source: "scanner",
+        reason: `scanner marker: ${pattern.source}`,
+        confidence: 0.7,
+        kind: "scanner_signal",
+        extractor: "scanner_marker",
+        metadata: { marker: pattern.source },
+      };
+    }
+  }
+
+  const contentSignals = collectContentSignals(content);
+  const structured = detectStructuredScannerEvidence(contentSignals, messageParts);
+  if (structured) {
+    return structured;
+  }
+
+  if (contentSignals.score < 1.8) {
     return null;
   }
 
   return {
     value: 0.25,
     source: "scanner",
-    reason: `scanner heuristic: ${signals.join(", ")}`,
-    confidence: Math.min(0.8, 0.5 + signals.length * 0.05),
+    reason: `scanner heuristic: ${contentSignals.signals.join(", ")}`,
+    confidence: Math.min(0.8, 0.5 + contentSignals.signals.length * 0.05),
     kind: "scanner_signal",
     extractor: "scanner_heuristic",
+    metadata: {
+      guidanceSignals: contentSignals.signals,
+      numberedSteps: contentSignals.numberedSteps,
+      bulletLines: contentSignals.bulletLines,
+      commandLines: contentSignals.commandLines,
+      imperativeLines: contentSignals.imperativeLines,
+      fileRefs: contentSignals.fileRefs,
+      hasHeading: contentSignals.hasHeading,
+    },
   };
 }