@jonathangu/openclawbrain 0.3.0

package/src/brain-harvest/self.ts

@@ -0,0 +1,147 @@
+import type { HarvestMessagePart, HarvestResult } from "../brain-runtime/evidence-detectors.js";
+
+const TOOL_FAILURE_PATTERNS = [
+  /\berror\b/i,
+  /\bfailed\b/i,
+  /\bexception\b/i,
+  /stack\s*trace/i,
+  /\bEINVAL\b/,
+  /\bENOENT\b/,
+  /\bEACCES\b/,
+  /exit\s+code\s+[1-9]/i,
+];
+
+const TOOL_SUCCESS_PATTERNS = [
+  /\bsuccess(ful|fully)?\b/i,
+  /\bpassed\b/i,
+  /\bdeployed\b/i,
+  /\bcreated\s+(commit|pr|branch)\b/i,
+  /\b\d+\s+pass(ed|ing)\b/i,
+  /\bfixed\b/i,
+  /\bresolved\b/i,
+];
+
+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 readPartMetadata(part: HarvestMessagePart): Record<string, unknown> {
+  const parsed = parseJson(part.metadata);
+  return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+    ? parsed as Record<string, unknown>
+    : {};
+}
+
+function isStructuredToolResultPart(part: HarvestMessagePart): boolean {
+  if (part.partType !== "tool") {
+    return false;
+  }
+  const metadata = readPartMetadata(part);
+  const rawType = typeof metadata.rawType === "string" ? metadata.rawType : "";
+  const originalRole = typeof metadata.originalRole === "string" ? metadata.originalRole : "";
+  return originalRole === "toolResult"
+    || rawType === "tool_result"
+    || rawType === "toolResult"
+    || rawType === "function_call_output";
+}
+
+function classifyStructuredToolOutput(output: unknown): { ok: boolean; reason: string } | null {
+  if (!output || typeof output !== "object" || Array.isArray(output)) {
+    return null;
+  }
+  const record = output as Record<string, unknown>;
+
+  if (record.isError === true || record.error !== undefined || record.errors !== undefined) {
+    return { ok: false, reason: "structured tool output indicates error" };
+  }
+  if (record.ok === false || record.success === false || record.passed === false || record.failed === true) {
+    return { ok: false, reason: "structured tool output indicates failure" };
+  }
+  if (typeof record.exitCode === "number" && record.exitCode > 0) {
+    return { ok: false, reason: `structured tool output exitCode=${record.exitCode}` };
+  }
+
+  if (record.ok === true || record.success === true || record.passed === true) {
+    return { ok: true, reason: "structured tool output indicates success" };
+  }
+  if (typeof record.exitCode === "number" && record.exitCode === 0) {
+    return { ok: true, reason: "structured tool output exitCode=0" };
+  }
+
+  return null;
+}
+
+export function detectStructuredSelfEvidence(messageParts?: HarvestMessagePart[]): HarvestResult | null {
+  if (!messageParts || messageParts.length === 0) {
+    return null;
+  }
+
+  for (const part of messageParts) {
+    if (!isStructuredToolResultPart(part)) {
+      continue;
+    }
+
+    const metadata = readPartMetadata(part);
+    if (metadata.isError === true) {
+      return {
+        value: -0.5,
+        source: "self",
+        reason: "structured tool result marked isError=true",
+        confidence: 0.9,
+        kind: "self_result",
+        extractor: "structured_tool_result",
+      };
+    }
+
+    const classified = classifyStructuredToolOutput(parseJson(part.toolOutput));
+    if (!classified) {
+      continue;
+    }
+
+    return {
+      value: classified.ok ? 0.5 : -0.5,
+      source: "self",
+      reason: classified.reason,
+      confidence: 0.9,
+      kind: "self_result",
+      extractor: "structured_tool_result",
+    };
+  }
+
+  return null;
+}
+
+export function detectSelfEvidence(content: string): HarvestResult | null {
+  for (const pattern of TOOL_FAILURE_PATTERNS) {
+    if (pattern.test(content)) {
+      return {
+        value: -0.5,
+        source: "self",
+        reason: `tool failure: ${pattern.source}`,
+        confidence: 0.7,
+        kind: "self_result",
+        extractor: "self_pattern",
+      };
+    }
+  }
+  for (const pattern of TOOL_SUCCESS_PATTERNS) {
+    if (pattern.test(content)) {
+      return {
+        value: 0.5,
+        source: "self",
+        reason: `tool success: ${pattern.source}`,
+        confidence: 0.7,
+        kind: "self_result",
+        extractor: "self_pattern",
+      };
+    }
+  }
+  return null;
+}

package/src/brain-runtime/assembler-extension.ts

@@ -0,0 +1,230 @@
+import type { AssembleContextResult } from "../assembler.js";
+import type { ContextEngine } from "openclaw/plugin-sdk";
+import type { TraversalResult } from "../brain-core/types.js";
+import type { BrainService } from "./service.js";
+
+type AgentMessage = Parameters<ContextEngine["ingest"]>[0]["message"];
+export type BrainAssemblyDecisionMode =
+  | "use_brain"
+  | "shadow"
+  | "skip_no_query"
+  | "skip_short_static_lookup"
+  | "skip_no_embedding"
+  | "skip_uninitialized"
+  | "skip_budget_too_small";
+
+export type BrainAssemblyDecision = {
+  mode: BrainAssemblyDecisionMode;
+  queryText: string;
+};
+
+export type BrainAssembledContextResult = AssembleContextResult & {
+  brainDecision?: {
+    mode: BrainAssemblyDecisionMode;
+    episodeId?: string | null;
+    traceId?: string | null;
+    footer?: string | null;
+  };
+};
+
+function decisionFooter(mode: BrainAssemblyDecisionMode): string {
+  switch (mode) {
+    case "use_brain":
+      return "[brain] used graph retrieval for this turn.";
+    case "shadow":
+      return "[brain shadow] recorded routing without injecting learned context.";
+    case "skip_no_query":
+      return "[brain] bypassed: no user query text.";
+    case "skip_short_static_lookup":
+      return "[brain] bypassed: short static lookup.";
+    case "skip_no_embedding":
+      return "[brain] bypassed: embeddings unavailable.";
+    case "skip_uninitialized":
+      return "[brain] bypassed: brain uninitialized or disabled.";
+    case "skip_budget_too_small":
+      return "[brain] bypassed: token budget too small.";
+  }
+}
+
+function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 4);
+}
+
+function extractText(content: unknown): string {
+  if (typeof content === "string") {
+    return content;
+  }
+  if (!Array.isArray(content)) {
+    return "";
+  }
+  return content
+    .filter((item): item is { type?: unknown; text?: unknown } => !!item && typeof item === "object")
+    .map((item) => (item.type === "text" && typeof item.text === "string" ? item.text : ""))
+    .join("\n")
+    .trim();
+}
+
+function buildBrainContextBlock(result: TraversalResult): string {
+  const corrections = result.fired.filter((node) => node.kind === "correction");
+  const playbooks = result.fired.filter((node) => node.kind === "workflow" || node.kind === "toolcard");
+  const evidence = result.fired.filter((node) => node.kind !== "correction" && node.kind !== "workflow" && node.kind !== "toolcard");
+
+  const sections = [
+    "OpenClawBrain retrieved context. Prefer correction cards over conflicting heuristics when directly relevant.",
+    "",
+    "## Correction Cards",
+    corrections.length > 0 ? corrections.map((node) => `- ${node.content}`).join("\n") : "- none",
+    "",
+    "## Route-Selected Evidence",
+    evidence.length > 0 ? evidence.map((node) => `- [${node.kind}] ${node.content}`).join("\n") : "- none",
+    "",
+    "## Toolcards And Playbooks",
+    playbooks.length > 0 ? playbooks.map((node) => `- [${node.kind}] ${node.content}`).join("\n") : "- none",
+    "",
+    "## Transcript Support",
+    "- Use the LCM transcript and summary context below for chronology and grounding.",
+    "",
+    `Trace: ${result.trace.footer}`,
+  ];
+  return sections.join("\n");
+}
+
+export class BrainAssemblerExtension {
+  constructor(private brain: BrainService) {}
+
+  decide(params: {
+    tokenBudget: number;
+    liveMessages: AgentMessage[];
+  }): BrainAssemblyDecision {
+    const latestUserMessage = [...params.liveMessages]
+      .reverse()
+      .find((message) => message.role === "user");
+    const queryText = latestUserMessage ? extractText(latestUserMessage.content) : "";
+
+    if (!this.brain.isEnabled() || !this.brain.isInitialized()) {
+      return { mode: "skip_uninitialized", queryText };
+    }
+    if (!this.brain.isEmbeddingConfigured()) {
+      return { mode: "skip_no_embedding", queryText };
+    }
+    if (params.tokenBudget < 512) {
+      return { mode: "skip_budget_too_small", queryText };
+    }
+    if (!queryText) {
+      return { mode: "skip_no_query", queryText };
+    }
+
+    const normalized = queryText.toLowerCase();
+    const looksStaticLookup =
+      queryText.length < 72
+      && (normalized.startsWith("read ")
+        || normalized.startsWith("show ")
+        || normalized.startsWith("open ")
+        || normalized.startsWith("cat ")
+        || normalized.startsWith("grep ")
+        || normalized.includes(".ts")
+        || normalized.includes(".md")
+        || normalized.includes(".json")
+        || normalized.includes("/"));
+    if (looksStaticLookup) {
+      return { mode: "skip_short_static_lookup", queryText };
+    }
+
+    return { mode: this.brain.isShadowMode() ? "shadow" : "use_brain", queryText };
+  }
+
+  async augmentAssembly(params: {
+    conversationId: number;
+    tokenBudget: number;
+    assembled: AssembleContextResult;
+    liveMessages: AgentMessage[];
+  }): Promise<BrainAssembledContextResult> {
+    const decision = this.decide({
+      tokenBudget: params.tokenBudget,
+      liveMessages: params.liveMessages,
+    });
+    if (decision.mode !== "use_brain" && decision.mode !== "shadow") {
+      this.brain.noteAssemblyDecision({
+        mode: decision.mode,
+        conversationId: params.conversationId,
+        footer: decisionFooter(decision.mode),
+      });
+      return {
+        ...params.assembled,
+        brainDecision: {
+          mode: decision.mode,
+          footer: decisionFooter(decision.mode),
+        },
+      };
+    }
+
+    const result = await this.brain.query({
+      conversationId: params.conversationId,
+      queryText: decision.queryText,
+      budgetChars: Math.max(256, Math.floor(params.tokenBudget * 4 * 0.3)),
+    });
+    if (!result) {
+      this.brain.noteAssemblyDecision({
+        mode: decision.mode,
+        conversationId: params.conversationId,
+        footer: decisionFooter(decision.mode),
+      });
+      return {
+        ...params.assembled,
+        brainDecision: {
+          mode: decision.mode,
+          footer: decisionFooter(decision.mode),
+        },
+      };
+    }
+
+    const brainMessage: AgentMessage = {
+      role: "user",
+      content: buildBrainContextBlock(result),
+    } as AgentMessage;
+    if (decision.mode === "shadow") {
+      this.brain.noteAssemblyDecision({
+        mode: "shadow",
+        conversationId: params.conversationId,
+        episodeId: result.episode.id,
+        traceId: result.trace.id,
+        footer: decisionFooter("shadow"),
+      });
+
+      return {
+        ...params.assembled,
+        brainDecision: {
+          mode: "shadow",
+          episodeId: result.episode.id,
+          traceId: result.trace.id,
+          footer: decisionFooter("shadow"),
+        },
+      };
+    }
+    this.brain.noteAssemblyDecision({
+      mode: "use_brain",
+      conversationId: params.conversationId,
+      episodeId: result.episode.id,
+      traceId: result.trace.id,
+      footer: result.trace.footer,
+    });
+
+    return {
+      ...params.assembled,
+      messages: [brainMessage, ...params.assembled.messages],
+      estimatedTokens: params.assembled.estimatedTokens + estimateTokens(extractText(brainMessage.content)),
+      systemPromptAddition: [
+        params.assembled.systemPromptAddition,
+        "OpenClawBrain sections are ranked by trust: correction cards, evidence, playbooks, then transcript support.",
+      ]
+        .filter(Boolean)
+        .join("\n\n"),
+      brainDecision: {
+        mode: "use_brain",
+        episodeId: result.episode.id,
+        traceId: result.trace.id,
+        footer: result.trace.footer,
+      },
+    };
+  }
+}

package/src/brain-runtime/evidence-detectors.ts

@@ -0,0 +1,68 @@
+import type { BrainEvidenceKind, RewardSource } from "../brain-core/types.js";
+import { detectHumanEvidence } from "../brain-harvest/human.js";
+import { detectScannerEvidence } from "../brain-harvest/scanner.js";
+import { detectSelfEvidence, detectStructuredSelfEvidence } from "../brain-harvest/self.js";
+
+export type HarvestMessagePart = {
+  partType: string;
+  textContent?: string | null;
+  toolCallId?: string | null;
+  toolName?: string | null;
+  toolInput?: string | null;
+  toolOutput?: string | null;
+  metadata?: string | null;
+};
+
+export interface HarvestResult {
+  value: number;
+  source: RewardSource;
+  reason: string;
+  confidence?: number;
+  kind: BrainEvidenceKind;
+  extractor?: string;
+}
+
+export function detectEvidenceBatch(
+  role: string,
+  content: string,
+  messageParts?: HarvestMessagePart[],
+): HarvestResult[] {
+  if (role === "user") {
+    const human = detectHumanEvidence(content);
+    return human ? [human] : [];
+  }
+
+  if (role === "tool" || role === "assistant") {
+    const structuredSelf = detectStructuredSelfEvidence(messageParts);
+    const self = structuredSelf ?? detectSelfEvidence(content);
+    const results = [
+      self,
+      detectScannerEvidence(content),
+    ].filter((result): result is HarvestResult => result !== null);
+
+    const deduped = new Map<string, HarvestResult>();
+    for (const result of results) {
+      const key = [
+        result.source,
+        result.kind,
+        result.value,
+        result.reason,
+        result.extractor ?? "",
+      ].join("::");
+      if (!deduped.has(key)) {
+        deduped.set(key, result);
+      }
+    }
+    return Array.from(deduped.values());
+  }
+
+  return [];
+}
+
+export function detectEvidence(
+  role: string,
+  content: string,
+  messageParts?: HarvestMessagePart[],
+): HarvestResult | null {
+  return detectEvidenceBatch(role, content, messageParts)[0] ?? null;
+}

package/src/brain-runtime/graph-io.ts

@@ -0,0 +1,72 @@
+import { computeHealth } from "../brain-core/health.js";
+import type { BrainConfig, BrainNode, SeedWeight } from "../brain-core/types.js";
+import type { BrainGraph } from "../brain-core/graph.js";
+import { PackManager } from "../brain-core/pack.js";
+import type { BrainStore } from "../brain-store/store.js";
+
+export function flattenEdges(graph: BrainGraph) {
+  return graph.getAllEdges();
+}
+
+export function flattenSeedWeights(graph: BrainGraph): SeedWeight[] {
+  const now = Date.now();
+  return graph.getAllSeedWeights().map((seedWeight) => ({
+    nodeId: seedWeight.nodeId,
+    weight: seedWeight.weight,
+    updatedAt: now,
+  }));
+}
+
+export function populateGraph(
+  graph: BrainGraph,
+  nodes: BrainNode[],
+  edges: ReturnType<typeof flattenEdges>,
+  seedWeights: SeedWeight[] = [],
+): void {
+  graph.clear();
+  for (const node of nodes) {
+    graph.addNode(node);
+  }
+  for (const edge of edges) {
+    graph.addEdge(edge);
+  }
+  for (const seedWeight of seedWeights) {
+    graph.setSeedWeight(seedWeight.nodeId, seedWeight.weight);
+  }
+}
+
+export function reloadGraphFromStore(store: BrainStore, graph: BrainGraph): void {
+  populateGraph(graph, store.getAllNodes(), store.loadAllEdges(), store.loadAllSeedWeights());
+}
+
+export function promoteGraphSnapshot(params: {
+  store: BrainStore;
+  graph: BrainGraph;
+  packManager: PackManager;
+  config: BrainConfig;
+  reason: string;
+  metadata: Record<string, unknown>;
+}): number | null {
+  if (params.graph.nodeCount() === 0) {
+    return null;
+  }
+
+  const health = computeHealth(
+    params.graph,
+    params.store.getRecentEpisodes(params.config.replayEpisodeCount),
+    params.store.getCurrentPackVersion() ?? 0,
+  );
+  const pack = params.packManager.buildCandidate(health);
+  params.store.writePackSnapshot({
+    version: pack.version,
+    nodes: params.graph.getAllNodes(),
+    edges: flattenEdges(params.graph),
+    seedWeights: flattenSeedWeights(params.graph),
+    metadata: {
+      reason: params.reason,
+      ...params.metadata,
+    },
+  });
+  params.packManager.promote(pack.version);
+  return pack.version;
+}

package/src/brain-runtime/harvester-extension.ts

@@ -0,0 +1,98 @@
+/**
+ * Label harvesting from ingested messages.
+ *
+ * Structured evidence flow:
+ * - detect human/self/scanner evidence separately
+ * - persist raw evidence first
+ * - let the worker resolve evidence into labels with trust ordering
+ */
+
+import type { BrainStore } from "../brain-store/store.js";
+import {
+  detectEvidence,
+  detectEvidenceBatch,
+  type HarvestMessagePart,
+  type HarvestResult,
+} from "./evidence-detectors.js";
+
+export class LabelHarvester {
+  constructor(
+    private store: BrainStore,
+    private log: { info: (msg: string) => void; warn: (msg: string) => void },
+    private resolveEpisodeIdForConversation?: (conversationId: number) => string | null | undefined,
+  ) {}
+
+  /**
+   * Called from engine.ts after message ingestion.
+   * Detects evidence from message content and attaches it to the matching episode.
+   */
+  async harvestFromMessage(params: {
+    conversationId: number;
+    episodeId?: string;
+    role: string;
+    content: string;
+    messageParts?: HarvestMessagePart[];
+  }): Promise<void> {
+    const results = this.detectLabels(params.role, params.content, params.messageParts);
+    if (results.length === 0) return;
+
+    const explicitEpisodeId = params.episodeId ?? null;
+    const resolvedEpisodeId = explicitEpisodeId
+      ?? this.resolveEpisodeIdForConversation?.(params.conversationId)
+      ?? null;
+    const matchedResolvedEpisode = (() => {
+      if (!resolvedEpisodeId) {
+        return null;
+      }
+      const episode = this.store.getEpisode(resolvedEpisodeId);
+      return episode?.conversationId === params.conversationId ? episode : null;
+    })();
+    const matchingEpisode = matchedResolvedEpisode
+      ?? this.store.getRecentEpisodesForConversation(params.conversationId, 5)[0]
+      ?? null;
+
+    if (!matchingEpisode) return;
+
+    const attributionMode = matchedResolvedEpisode
+      ? explicitEpisodeId
+        ? "explicit"
+        : "resolver"
+      : "recent_conversation_fallback";
+
+    for (const [index, result] of results.entries()) {
+      this.store.insertEvidence({
+        episodeId: matchingEpisode.id,
+        conversationId: params.conversationId,
+        source: result.source,
+        kind: result.kind,
+        value: result.value,
+        confidence: result.confidence,
+        reason: result.reason,
+        contentSnippet: params.content.slice(0, 240),
+        metadata: {
+          harvestedFromRole: params.role,
+          explicitEpisodeId,
+          resolvedEpisodeId,
+          matchedEpisodeId: matchingEpisode.id,
+          attributionMode,
+          extractor: result.extractor ?? null,
+          evidenceIndex: index,
+          evidenceCount: results.length,
+          messagePartCount: params.messageParts?.length ?? 0,
+        },
+      });
+
+      this.log.info(
+        `[brain] Harvested ${result.source} evidence: ${result.value.toFixed(2)} for episode ${matchingEpisode.id} (${result.reason})`,
+      );
+    }
+  }
+
+  detectLabel(role: string, content: string, messageParts?: HarvestMessagePart[]): HarvestResult | null {
+    return detectEvidence(role, content, messageParts);
+  }
+
+  detectLabels(role: string, content: string, messageParts?: HarvestMessagePart[]): HarvestResult[] {
+    return detectEvidenceBatch(role, content, messageParts);
+  }
+}