@jonathangu/openclawbrain 0.3.0 → 0.3.1

package/src/brain-harvest/self.ts

@@ -32,11 +32,14 @@ function parseJson(value: string | null | undefined): unknown {
   }
 }
 
+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> {
-  const parsed = parseJson(part.metadata);
-  return parsed && typeof parsed === "object" && !Array.isArray(parsed)
-    ? parsed as Record<string, unknown>
-    : {};
+  return asRecord(parseJson(part.metadata)) ?? {};
 }
 
 function isStructuredToolResultPart(part: HarvestMessagePart): boolean {
@@ -52,11 +55,133 @@ function isStructuredToolResultPart(part: HarvestMessagePart): boolean {
     || rawType === "function_call_output";
 }
 
+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 readNumber(record: Record<string, unknown> | null, keys: string[]): number | undefined {
+  if (!record) {
+    return undefined;
+  }
+  for (const key of keys) {
+    const value = record[key];
+    if (typeof value === "number" && Number.isFinite(value)) {
+      return value;
+    }
+  }
+  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, output: unknown): string | undefined {
+  const inputRecord = asRecord(input);
+  const outputRecord = asRecord(output);
+
+  return readString(inputRecord, ["command", "cmd", "shellCommand"])
+    ?? readCommand(inputRecord?.args)
+    ?? readString(outputRecord, ["command", "cmd", "shellCommand"])
+    ?? readCommand(outputRecord?.args)
+    ?? (typeof input === "string" && input.trim().length > 0 ? input.trim() : undefined);
+}
+
+function extractFilesTouched(input: unknown, output: unknown): string[] | undefined {
+  const inputRecord = asRecord(input);
+  const outputRecord = asRecord(output);
+  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, ["filePath", "path"]),
+    readString(inputRecord, ["filePath", "path"]),
+  ]) {
+    for (const item of readStringArray(value)) {
+      collected.add(item);
+    }
+  }
+
+  return collected.size > 0 ? Array.from(collected) : undefined;
+}
+
+function extractArtifactPath(output: unknown): string | undefined {
+  const record = asRecord(output);
+  return readString(record, ["artifactPath", "outputPath", "reportPath", "logPath"]);
+}
+
+function buildStructuredToolMetadata(part: HarvestMessagePart): Record<string, unknown> {
+  const metadata = readPartMetadata(part);
+  const rawType = typeof metadata.rawType === "string" ? metadata.rawType : null;
+  const parsedInput = parseJson(part.toolInput);
+  const parsedOutput = parseJson(part.toolOutput);
+  const result: Record<string, unknown> = {
+    toolCallId: part.toolCallId ?? null,
+    toolName: part.toolName ?? null,
+    partOrdinal: part.ordinal ?? null,
+    rawType,
+  };
+
+  const exitCode = readNumber(asRecord(parsedOutput), ["exitCode"]);
+  if (exitCode !== undefined) {
+    result.exitCode = exitCode;
+  }
+
+  const command = extractCommand(parsedInput, parsedOutput);
+  if (command) {
+    result.command = command;
+  }
+
+  const filesTouched = extractFilesTouched(parsedInput, parsedOutput);
+  if (filesTouched) {
+    result.filesTouched = filesTouched;
+  }
+
+  const artifactPath = extractArtifactPath(parsedOutput);
+  if (artifactPath) {
+    result.artifactPath = artifactPath;
+  }
+
+  return result;
+}
+
 function classifyStructuredToolOutput(output: unknown): { ok: boolean; reason: string } | null {
-  if (!output || typeof output !== "object" || Array.isArray(output)) {
+  const record = asRecord(output);
+  if (!record) {
     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" };
@@ -89,6 +214,7 @@ export function detectStructuredSelfEvidence(messageParts?: HarvestMessagePart[]
     }
 
     const metadata = readPartMetadata(part);
+    const evidenceMetadata = buildStructuredToolMetadata(part);
     if (metadata.isError === true) {
       return {
         value: -0.5,
@@ -97,6 +223,7 @@ export function detectStructuredSelfEvidence(messageParts?: HarvestMessagePart[]
         confidence: 0.9,
         kind: "self_result",
         extractor: "structured_tool_result",
+        metadata: evidenceMetadata,
       };
     }
 
@@ -112,6 +239,7 @@ export function detectStructuredSelfEvidence(messageParts?: HarvestMessagePart[]
       confidence: 0.9,
       kind: "self_result",
       extractor: "structured_tool_result",
+      metadata: evidenceMetadata,
     };
   }
 

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

@@ -5,6 +5,7 @@ import { detectSelfEvidence, detectStructuredSelfEvidence } from "../brain-harve
 
 export type HarvestMessagePart = {
   partType: string;
+  ordinal?: number;
   textContent?: string | null;
   toolCallId?: string | null;
   toolName?: string | null;
@@ -20,6 +21,7 @@ export interface HarvestResult {
   confidence?: number;
   kind: BrainEvidenceKind;
   extractor?: string;
+  metadata?: Record<string, unknown>;
 }
 
 export function detectEvidenceBatch(
@@ -37,7 +39,7 @@ export function detectEvidenceBatch(
     const self = structuredSelf ?? detectSelfEvidence(content);
     const results = [
       self,
-      detectScannerEvidence(content),
+      detectScannerEvidence(content, messageParts),
     ].filter((result): result is HarvestResult => result !== null);
 
     const deduped = new Map<string, HarvestResult>();

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

@@ -28,6 +28,7 @@ export class LabelHarvester {
    */
   async harvestFromMessage(params: {
     conversationId: number;
+    messageId?: number;
     episodeId?: string;
     role: string;
     content: string;
@@ -71,6 +72,7 @@ export class LabelHarvester {
         contentSnippet: params.content.slice(0, 240),
         metadata: {
           harvestedFromRole: params.role,
+          messageId: params.messageId ?? null,
           explicitEpisodeId,
           resolvedEpisodeId,
           matchedEpisodeId: matchingEpisode.id,
@@ -79,6 +81,7 @@ export class LabelHarvester {
           evidenceIndex: index,
           evidenceCount: results.length,
           messagePartCount: params.messageParts?.length ?? 0,
+          ...(result.metadata ?? {}),
         },
       });
 

package/src/brain-runtime/service.ts

@@ -599,11 +599,13 @@ export class BrainService {
 
   async harvestFromMessage(params: {
     conversationId: number;
+    messageId?: number;
     episodeId?: string;
     role: string;
     content: string;
     messageParts?: Array<{
       partType: string;
+      ordinal?: number;
       textContent?: string | null;
       toolCallId?: string | null;
       toolName?: string | null;

package/src/brain-store/embedding.ts

@@ -27,6 +27,12 @@ function trimTrailingSlashes(value: string): string {
   return value.replace(/\/+$/, "");
 }
 
+function resolveEmbeddingTimeoutMs(): number {
+  const raw = process.env.OPENCLAWBRAIN_EMBEDDING_TIMEOUT_MS?.trim();
+  const parsed = raw ? Number.parseInt(raw, 10) : 10000;
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 10000;
+}
+
 function resolveExplicitBaseUrl(config: OpenClawBrainRuntimeConfig): string | null {
   const explicit = config.embeddingBaseUrl.trim();
   return explicit ? trimTrailingSlashes(explicit) : null;
@@ -152,14 +158,29 @@ export function createEmbeddingClient(options: BrainEmbeddingOptions): BrainEmbe
       headers.authorization = `Bearer ${apiKey}`;
     }
 
-    const response = await fetch(`${baseUrl}/embeddings`, {
-      method: "POST",
-      headers,
-      body: JSON.stringify({
-        model: config.embeddingModel,
-        input: text,
-      }),
-    });
+    const timeoutMs = resolveEmbeddingTimeoutMs();
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+    let response;
+    try {
+      response = await fetch(`${baseUrl}/embeddings`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          model: config.embeddingModel,
+          input: text,
+        }),
+        signal: controller.signal,
+      });
+    } catch (error) {
+      if ((error as { name?: string }).name === "AbortError") {
+        throw new Error(`Embedding request timed out after ${timeoutMs}ms: ${baseUrl}/embeddings`);
+      }
+      throw error;
+    } finally {
+      clearTimeout(timer);
+    }
 
     if (!response.ok) {
       const body = await response.text();

package/src/brain-worker/worker.ts

@@ -9,12 +9,43 @@ import { computeReinforceUpdates, updateBaseline, applyWeightUpdates } from "../
 import { decayAllWeights } from "../brain-core/decay.js";
 import { computeHealth } from "../brain-core/health.js";
 
+function readExtractor(evidence: BrainEvidence): string | null {
+  const extractor = evidence.metadata?.extractor;
+  return typeof extractor === "string" && extractor.length > 0 ? extractor : null;
+}
+
+function evidenceSpecificityRank(evidence: BrainEvidence): number {
+  const extractor = readExtractor(evidence);
+  if (evidence.source === "scanner") {
+    switch (extractor) {
+      case "structured_guidance_parts":
+        return 3;
+      case "structured_tool_chain":
+        return 2;
+      case "scanner_marker":
+        return 1;
+      case "scanner_heuristic":
+      default:
+        return 0;
+    }
+  }
+
+  return 0;
+}
+
 function compareEvidencePriority(left: BrainEvidence, right: BrainEvidence): number {
   const trustDelta = trustRank(left.source) - trustRank(right.source);
   if (trustDelta !== 0) {
     return trustDelta;
   }
 
+  if (left.value !== right.value) {
+    const specificityDelta = evidenceSpecificityRank(left) - evidenceSpecificityRank(right);
+    if (specificityDelta !== 0) {
+      return specificityDelta;
+    }
+  }
+
   const confidenceDelta = left.confidence - right.confidence;
   if (confidenceDelta !== 0) {
     return confidenceDelta;
@@ -43,6 +74,15 @@ function losingEvidenceResolution(
     };
   }
 
+  const winnerSpecificity = evidenceSpecificityRank(winner);
+  const loserSpecificity = evidenceSpecificityRank(loser);
+  if (winnerSpecificity !== loserSpecificity) {
+    return {
+      resolution: "discarded_duplicate",
+      note: `same-trust evidence superseded by more-structured ${winner.source} evidence`,
+    };
+  }
+
   if (winner.confidence !== loser.confidence) {
     return {
       resolution: "discarded_duplicate",

package/src/engine.ts

@@ -1263,6 +1263,7 @@ export class LcmContextEngine implements ContextEngine {
     if (this.brainService) {
       await this.brainService.harvestFromMessage({
         conversationId,
+        messageId: msgRecord.messageId,
         episodeId: params.brainEpisodeId ?? this.pendingBrainEpisodeBySession.get(sessionId),
         role: stored.role,
         content: stored.content,