@jonathangu/openclawbrain 0.3.0

package/src/brain-runtime/tools.ts

@@ -0,0 +1,109 @@
+/**
+ * Agent tools: brain_teach, brain_status, brain_trace.
+ *
+ * Follows lossless-claw's tool pattern:
+ * - Typebox schemas for input validation
+ * - jsonResult() for output formatting
+ * - createX() factory functions
+ */
+
+import { Type } from "@sinclair/typebox";
+
+// Use LCM's existing tool helpers
+const jsonResult = (payload: unknown) => ({
+  content: [{ type: "text" as const, text: JSON.stringify(payload, null, 2) }],
+  details: payload,
+});
+
+// ─── Types ───
+
+interface BrainToolDeps {
+  teach: (
+    instruction: string,
+    kind?: string,
+    tags?: string[],
+  ) => Promise<{ nodeId: string; packVersion?: number | null }>;
+  status: () => Promise<Record<string, unknown>>;
+  getTrace: (traceId?: string) => Promise<Record<string, unknown> | null>;
+}
+
+// ─── brain_teach ───
+
+const BrainTeachSchema = Type.Object({
+  instruction: Type.String({
+    description: "What to remember or correct. Examples: 'use gh pr create, not hub', 'for deployment errors, always check CI logs first'",
+  }),
+  kind: Type.Optional(Type.String({
+    description: 'Node kind: "correction", "toolcard", or "workflow". Default: "correction".',
+    enum: ["correction", "toolcard", "workflow"],
+  })),
+  tags: Type.Optional(Type.Array(Type.String(), {
+    description: "Tags for filtering and retrieval",
+  })),
+});
+
+export function createBrainTeachTool(deps: BrainToolDeps) {
+  return {
+    name: "brain_teach",
+    label: "Brain Teach",
+    description: "Teach the brain a correction, pattern, or preference. Creates a high-trust human node that will be surfaced in future context.",
+    parameters: BrainTeachSchema,
+    async execute(_toolCallId: string, params: Record<string, unknown>) {
+      const instruction = params.instruction as string;
+      const kind = (params.kind as string) ?? "correction";
+      const tags = (params.tags as string[]) ?? [];
+
+      const result = await deps.teach(instruction, kind, tags);
+      return jsonResult({
+        success: true,
+        nodeId: result.nodeId,
+        packVersion: result.packVersion ?? null,
+        message: `Brain will remember: "${instruction.slice(0, 80)}${instruction.length > 80 ? "..." : ""}"`,
+      });
+    },
+  };
+}
+
+// ─── brain_status ───
+
+const BrainStatusSchema = Type.Object({});
+
+export function createBrainStatusTool(deps: BrainToolDeps) {
+  return {
+    name: "brain_status",
+    label: "Brain Status",
+    description: "Show brain health: node/edge counts, pack version, learning stats, recent traces.",
+    parameters: BrainStatusSchema,
+    async execute() {
+      const status = await deps.status();
+      return jsonResult(status);
+    },
+  };
+}
+
+// ─── brain_trace ───
+
+const BrainTraceSchema = Type.Object({
+  traceId: Type.Optional(Type.String({
+    description: "Specific trace ID (bt_...). Default: most recent trace.",
+  })),
+});
+
+export function createBrainTraceTool(deps: BrainToolDeps) {
+  return {
+    name: "brain_trace",
+    label: "Brain Trace",
+    description: "Show the detailed decision trace for the most recent (or specified) brain query. Shows seed ranking, traversal steps, candidate probabilities, fired nodes, and vetoed nodes.",
+    parameters: BrainTraceSchema,
+    async execute(_toolCallId: string, params: Record<string, unknown>) {
+      const traceId = params.traceId as string | undefined;
+      const trace = await deps.getTrace(traceId);
+
+      if (!trace) {
+        return jsonResult({ error: "No trace found", traceId });
+      }
+
+      return jsonResult(trace);
+    },
+  };
+}

package/src/brain-runtime/worker-state.ts

@@ -0,0 +1,106 @@
+import type { BrainConfig } from "../brain-core/types.js";
+import type { OpenClawBrainRuntimeConfig } from "../db/config.js";
+import type { BrainStore } from "../brain-store/store.js";
+
+export type WorkerLastExit = {
+  code: number | null;
+  signal: NodeJS.Signals | null;
+  at: number;
+};
+
+export type WorkerRuntimeState = {
+  workerMode: BrainConfig["workerMode"];
+  workerModeDevOnly: boolean;
+  workerModeWarning: string | null;
+  workerPid: number | null;
+  workerStatus: string | null;
+  workerLastHeartbeatAt: number | null;
+  workerLastReadyAt: number | null;
+  workerHealthy: boolean;
+  workerLastExit: WorkerLastExit | null;
+  workerRestartCount: number;
+  workerLastRestartAt: number | null;
+  workerStartedAt: number | null;
+  workerLastReloadRequestedAt: number | null;
+  workerLastReloadAckAt: number | null;
+  workerLastTickAt: number | null;
+  workerLastTickResultAt: number | null;
+  workerLastTickOk: boolean | null;
+  workerLastTickError: string | null;
+  workerLastFatalError: string | null;
+};
+
+function readInt(store: BrainStore, key: string): number | null {
+  const raw = store.getTrainingState(key)?.trim();
+  if (!raw) {
+    return null;
+  }
+  const value = Number.parseInt(raw, 10);
+  return Number.isFinite(value) && value > 0 ? value : null;
+}
+
+function readString(store: BrainStore, key: string): string | null {
+  const raw = store.getTrainingState(key)?.trim() ?? "";
+  return raw.length > 0 ? raw : null;
+}
+
+function readBoolean(store: BrainStore, key: string): boolean | null {
+  const raw = readString(store, key);
+  if (raw === "true") {
+    return true;
+  }
+  if (raw === "false") {
+    return false;
+  }
+  return null;
+}
+
+type WorkerStateConfig = Pick<BrainConfig, "workerMode" | "workerHeartbeatTimeoutMs">
+  | Pick<OpenClawBrainRuntimeConfig, "workerMode" | "workerHeartbeatTimeoutMs">;
+
+export function readWorkerRuntimeState(
+  store: BrainStore,
+  config: WorkerStateConfig,
+): WorkerRuntimeState {
+  const workerMode = config.workerMode ?? "child";
+  const workerHeartbeatTimeoutMs = config.workerHeartbeatTimeoutMs ?? 90_000;
+  const workerPid = readInt(store, "worker_pid");
+  const workerLastHeartbeatAt = readInt(store, "worker_last_heartbeat_at");
+  const workerLastReadyAt = readInt(store, "worker_last_ready_at");
+  const workerLastExitAt = readInt(store, "worker_last_exit_at");
+  const workerLastExitCodeRaw = store.getTrainingState("worker_last_exit_code")?.trim() ?? "";
+  const workerLastExitSignal = readString(store, "worker_last_exit_signal");
+  const workerLastExit = workerLastExitAt
+    ? {
+        code: workerLastExitCodeRaw.length > 0 ? Number.parseInt(workerLastExitCodeRaw, 10) : null,
+        signal: workerLastExitSignal as NodeJS.Signals | null,
+        at: workerLastExitAt,
+      }
+    : null;
+
+  return {
+    workerMode,
+    workerModeDevOnly: workerMode === "in_process",
+    workerModeWarning: workerMode === "in_process"
+      ? "in_process worker mode is dev-only; use child mode for production operator truth"
+      : null,
+    workerPid,
+    workerStatus: readString(store, "worker_status") ?? (workerMode === "child" ? "unknown" : "running"),
+    workerLastHeartbeatAt,
+    workerLastReadyAt,
+    workerHealthy: workerMode === "child"
+      ? Boolean(workerLastHeartbeatAt && (Date.now() - workerLastHeartbeatAt) < workerHeartbeatTimeoutMs)
+      : true,
+    workerLastExit,
+    workerRestartCount: readInt(store, "worker_restart_count") ?? 0,
+    workerLastRestartAt: readInt(store, "worker_last_restart_at"),
+    workerStartedAt: readInt(store, "worker_started_at"),
+    workerLastReloadRequestedAt: readInt(store, "worker_last_reload_requested_at"),
+    workerLastReloadAckAt: readInt(store, "worker_last_reload_ack_at"),
+    workerLastTickAt: readInt(store, "worker_last_tick_at"),
+    workerLastTickResultAt: readInt(store, "worker_last_tick_result_at"),
+    workerLastTickOk: readBoolean(store, "worker_last_tick_ok"),
+    workerLastTickError: readString(store, "worker_last_tick_error"),
+    workerLastFatalError: readString(store, "worker_last_fatal_error"),
+  };
+}

package/src/brain-runtime/worker-supervisor.ts

@@ -0,0 +1,169 @@
+import { fork, type ChildProcess } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import type { BrainConfig } from "../brain-core/types.js";
+import type { BrainStore } from "../brain-store/store.js";
+import type {
+  ChildToParentMessage,
+  ParentTeacherCompleteResultMessage,
+  ParentToChildMessage,
+  WorkerTeacherCompleteRequestMessage,
+} from "../brain-worker/protocol.js";
+
+export class WorkerSupervisor {
+  private child: ChildProcess | null = null;
+  private shouldRun = false;
+  private restartTimer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(
+    private params: {
+      config: BrainConfig;
+      store: BrainStore;
+      log: { info: (msg: string) => void; warn: (msg: string) => void; error: (msg: string) => void };
+      teacherModel: { provider: string; model: string } | null;
+      isEnabled: () => boolean;
+      onPackPromoted: () => void;
+      onTeacherComplete: (
+        message: WorkerTeacherCompleteRequestMessage,
+        teacherModel: { provider: string; model: string } | null,
+      ) => Promise<ParentTeacherCompleteResultMessage>;
+    },
+  ) {}
+
+  start(): void {
+    if (!this.params.isEnabled()) {
+      return;
+    }
+    this.shouldRun = true;
+    this.ensureChildWorker(false);
+  }
+
+  stop(): void {
+    this.shouldRun = false;
+    if (this.restartTimer) {
+      clearTimeout(this.restartTimer);
+      this.restartTimer = null;
+    }
+    if (this.child) {
+      this.params.store.setTrainingState("worker_status", "stopping");
+      this.send({ type: "shutdown" });
+      const child = this.child;
+      setTimeout(() => {
+        if (this.child === child) {
+          this.child.kill("SIGTERM");
+        }
+      }, 2_000);
+    }
+  }
+
+  requestGraphReload(): void {
+    this.params.store.setTrainingState("worker_last_reload_requested_at", Date.now());
+    this.send({ type: "reload-graph" });
+  }
+
+  private ensureChildWorker(isRestart: boolean): void {
+    if (this.child || !this.params.isEnabled()) {
+      return;
+    }
+
+    const status = isRestart ? "restarting" : "starting";
+    this.params.store.setTrainingState("worker_mode", "child");
+    this.params.store.setTrainingState("worker_status", status);
+    if (isRestart) {
+      const nextCount = (Number.parseInt(this.params.store.getTrainingState("worker_restart_count") ?? "0", 10) || 0) + 1;
+      const restartedAt = Date.now();
+      this.params.store.setTrainingState("worker_restart_count", nextCount);
+      this.params.store.setTrainingState("worker_last_restart_at", restartedAt);
+    }
+
+    const child = fork(
+      fileURLToPath(new URL("../brain-worker/child-runner.ts", import.meta.url)),
+      [],
+      {
+        execArgv: ["--import", "tsx/esm"],
+        stdio: ["ignore", "pipe", "pipe", "ipc"],
+        env: {
+          ...process.env,
+          OPENCLAWBRAIN_CHILD_CONFIG_JSON: JSON.stringify(this.params.config),
+          OPENCLAWBRAIN_CHILD_TEACHER_MODEL_JSON: this.params.teacherModel
+            ? JSON.stringify(this.params.teacherModel)
+            : "",
+        },
+      },
+    );
+
+    this.child = child;
+
+    child.stdout?.on("data", (chunk) => {
+      const text = String(chunk).trim();
+      if (text) {
+        this.params.log.info(text);
+      }
+    });
+    child.stderr?.on("data", (chunk) => {
+      const text = String(chunk).trim();
+      if (text) {
+        this.params.log.warn(text);
+      }
+    });
+    child.on("message", (message) => {
+      void this.handleMessage(message as ChildToParentMessage, child);
+    });
+    child.on("exit", (code, signal) => {
+      const exitedAt = Date.now();
+      this.params.store.setTrainingState("worker_pid", "");
+      this.params.store.setTrainingState("worker_last_exit_at", exitedAt);
+      this.params.store.setTrainingState("worker_last_exit_code", code === null ? "" : String(code));
+      this.params.store.setTrainingState("worker_last_exit_signal", signal ?? "");
+      if (this.child === child) {
+        this.child = null;
+      }
+      const nextStatus = this.shouldRun && this.params.isEnabled() ? "restarting" : "stopped";
+      this.params.store.setTrainingState("worker_status", nextStatus);
+      if (this.shouldRun && this.params.isEnabled()) {
+        this.restartTimer = setTimeout(() => {
+          this.restartTimer = null;
+          this.ensureChildWorker(true);
+        }, this.params.config.workerRestartDelayMs);
+      }
+    });
+  }
+
+  private send(message: ParentToChildMessage): void {
+    this.child?.send(message);
+  }
+
+  private async handleMessage(message: ChildToParentMessage, child: ChildProcess): Promise<void> {
+    switch (message.type) {
+      case "ready": {
+        this.params.store.setTrainingState("worker_last_ready_at", message.at);
+        this.params.store.setTrainingState("worker_last_fatal_error", "");
+        return;
+      }
+      case "heartbeat": {
+        return;
+      }
+      case "reload-graph-ack": {
+        return;
+      }
+      case "tick-result": {
+        return;
+      }
+      case "pack-promoted": {
+        this.params.onPackPromoted();
+        return;
+      }
+      case "teacher-complete": {
+        const result = await this.params.onTeacherComplete(message, this.params.teacherModel);
+        child.send?.(result);
+        return;
+      }
+      case "fatal-error": {
+        this.params.store.setTrainingState("worker_last_fatal_error", message.error);
+        this.params.log.error(`[brain] child worker fatal error: ${message.error}`);
+        return;
+      }
+      default:
+        return;
+    }
+  }
+}

package/src/brain-store/embedding.ts

@@ -0,0 +1,179 @@
+import type { OpenClawBrainRuntimeConfig } from "../db/config.js";
+
+export type BrainEmbeddingFn = (text: string) => Promise<Float32Array>;
+
+export type BrainEmbeddingOptions = {
+  config: OpenClawBrainRuntimeConfig;
+  getApiKey?: (provider: string, model: string) => Promise<string | undefined>;
+  log?: {
+    debug?: (msg: string) => void;
+    warn?: (msg: string) => void;
+  };
+};
+
+export type EmbeddingAuthMode = "none" | "api_key";
+
+export type EmbeddingConfigSummary = {
+  baseUrl: string;
+  authMode: EmbeddingAuthMode | "unknown";
+  error: string | null;
+};
+
+function normalizeProvider(provider: string): string {
+  return provider.trim().toLowerCase();
+}
+
+function trimTrailingSlashes(value: string): string {
+  return value.replace(/\/+$/, "");
+}
+
+function resolveExplicitBaseUrl(config: OpenClawBrainRuntimeConfig): string | null {
+  const explicit = config.embeddingBaseUrl.trim();
+  return explicit ? trimTrailingSlashes(explicit) : null;
+}
+
+export function resolveEmbeddingBaseUrl(config: OpenClawBrainRuntimeConfig): string {
+  const explicit = resolveExplicitBaseUrl(config);
+  if (explicit) {
+    return explicit;
+  }
+
+  const provider = normalizeProvider(config.embeddingProvider);
+  if (provider === "openai" || provider === "openai-resp") {
+    return "https://api.openai.com/v1";
+  }
+  if (provider === "ollama") {
+    return "http://127.0.0.1:11434/v1";
+  }
+
+  throw new Error(`Unsupported embedding provider "${config.embeddingProvider}"`);
+}
+
+function isLoopbackHostname(hostname: string): boolean {
+  const normalized = hostname.trim().toLowerCase();
+  return normalized === "localhost"
+    || normalized === "127.0.0.1"
+    || normalized === "::1"
+    || normalized === "[::1]";
+}
+
+export function isLocalEmbeddingBaseUrl(baseUrl: string): boolean {
+  try {
+    const parsed = new URL(baseUrl);
+    return isLoopbackHostname(parsed.hostname);
+  } catch {
+    return false;
+  }
+}
+
+export function resolveEmbeddingAuthMode(config: OpenClawBrainRuntimeConfig): EmbeddingAuthMode {
+  const explicitApiKey = process.env.OPENCLAWBRAIN_EMBEDDING_API_KEY?.trim();
+  if (explicitApiKey) {
+    return "api_key";
+  }
+
+  const provider = normalizeProvider(config.embeddingProvider);
+  if (provider === "ollama") {
+    return "none";
+  }
+
+  const baseUrl = resolveEmbeddingBaseUrl(config);
+  if (isLocalEmbeddingBaseUrl(baseUrl)) {
+    return "none";
+  }
+
+  return "api_key";
+}
+
+export function describeEmbeddingConfig(config: OpenClawBrainRuntimeConfig): EmbeddingConfigSummary {
+  try {
+    return {
+      baseUrl: resolveEmbeddingBaseUrl(config),
+      authMode: resolveEmbeddingAuthMode(config),
+      error: null,
+    };
+  } catch (error) {
+    return {
+      baseUrl: config.embeddingBaseUrl.trim(),
+      authMode: "unknown",
+      error: (error as Error).message,
+    };
+  }
+}
+
+async function resolveApiKey(
+  config: OpenClawBrainRuntimeConfig,
+  getApiKey?: (provider: string, model: string) => Promise<string | undefined>,
+): Promise<string | undefined> {
+  const explicitEmbeddingKey = process.env.OPENCLAWBRAIN_EMBEDDING_API_KEY?.trim();
+  if (explicitEmbeddingKey) {
+    return explicitEmbeddingKey;
+  }
+
+  if (resolveEmbeddingAuthMode(config) === "none") {
+    return undefined;
+  }
+
+  if (getApiKey) {
+    const key = await getApiKey(config.embeddingProvider, config.embeddingModel);
+    if (key) {
+      return key;
+    }
+  }
+
+  if (normalizeProvider(config.embeddingProvider) === "openai" || normalizeProvider(config.embeddingProvider) === "openai-resp") {
+    const envKey = process.env.OPENAI_API_KEY?.trim();
+    if (envKey) {
+      return envKey;
+    }
+  }
+
+  throw new Error(`Missing API key for embedding provider "${config.embeddingProvider}"`);
+}
+
+export function hasEmbeddingConfiguration(config: OpenClawBrainRuntimeConfig): boolean {
+  return config.embeddingModel.trim().length > 0;
+}
+
+export function createEmbeddingClient(options: BrainEmbeddingOptions): BrainEmbeddingFn | null {
+  const { config, getApiKey, log } = options;
+  if (!hasEmbeddingConfiguration(config)) {
+    log?.warn?.("[brain] Embedding model is unset; learned retrieval is disabled until init/configuration is complete");
+    return null;
+  }
+
+  return async (text: string): Promise<Float32Array> => {
+    const apiKey = await resolveApiKey(config, getApiKey);
+    const baseUrl = resolveEmbeddingBaseUrl(config);
+    const headers: Record<string, string> = {
+      "content-type": "application/json",
+    };
+    if (apiKey) {
+      headers.authorization = `Bearer ${apiKey}`;
+    }
+
+    const response = await fetch(`${baseUrl}/embeddings`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        model: config.embeddingModel,
+        input: text,
+      }),
+    });
+
+    if (!response.ok) {
+      const body = await response.text();
+      throw new Error(`Embedding request failed (${response.status}): ${body.slice(0, 200)}`);
+    }
+
+    const payload = await response.json() as {
+      data?: Array<{ embedding?: number[] }>;
+    };
+    const embedding = payload.data?.[0]?.embedding;
+    if (!Array.isArray(embedding) || embedding.length === 0) {
+      throw new Error("Embedding response did not include a vector");
+    }
+
+    return new Float32Array(embedding.map((value) => Number(value)));
+  };
+}