feat: OpenBrain ContextEngine plugin v0.0.1 (#3)

Co-authored-by: Jason Woltje <jason@diversecanvas.com>
Co-committed-by: Jason Woltje <jason@diversecanvas.com>

src/openclaw-types.ts

@@ -0,0 +1,128 @@
+export type AgentMessageRole = "user" | "assistant" | "tool" | "system" | string;
+
+export type AgentMessage = {
+  role: AgentMessageRole;
+  content: unknown;
+  timestamp?: number;
+  [key: string]: unknown;
+};
+
+export type AssembleResult = {
+  messages: AgentMessage[];
+  estimatedTokens: number;
+  systemPromptAddition?: string;
+};
+
+export type CompactResult = {
+  ok: boolean;
+  compacted: boolean;
+  reason?: string;
+  result?: {
+    summary?: string;
+    firstKeptEntryId?: string;
+    tokensBefore: number;
+    tokensAfter?: number;
+    details?: unknown;
+  };
+};
+
+export type IngestResult = {
+  ingested: boolean;
+};
+
+export type IngestBatchResult = {
+  ingestedCount: number;
+};
+
+export type BootstrapResult = {
+  bootstrapped: boolean;
+  importedMessages?: number;
+  reason?: string;
+};
+
+export type ContextEngineInfo = {
+  id: string;
+  name: string;
+  version?: string;
+  ownsCompaction?: boolean;
+};
+
+export type SubagentSpawnPreparation = {
+  rollback: () => void | Promise<void>;
+};
+
+export type SubagentEndReason = "deleted" | "completed" | "swept" | "released";
+
+export interface ContextEngine {
+  readonly info: ContextEngineInfo;
+
+  bootstrap?(params: { sessionId: string; sessionFile: string }): Promise<BootstrapResult>;
+
+  ingest(params: {
+    sessionId: string;
+    message: AgentMessage;
+    isHeartbeat?: boolean;
+  }): Promise<IngestResult>;
+
+  ingestBatch?(params: {
+    sessionId: string;
+    messages: AgentMessage[];
+    isHeartbeat?: boolean;
+  }): Promise<IngestBatchResult>;
+
+  afterTurn?(params: {
+    sessionId: string;
+    sessionFile: string;
+    messages: AgentMessage[];
+    prePromptMessageCount: number;
+    autoCompactionSummary?: string;
+    isHeartbeat?: boolean;
+    tokenBudget?: number;
+    legacyCompactionParams?: Record<string, unknown>;
+  }): Promise<void>;
+
+  assemble(params: {
+    sessionId: string;
+    messages: AgentMessage[];
+    tokenBudget?: number;
+  }): Promise<AssembleResult>;
+
+  compact(params: {
+    sessionId: string;
+    sessionFile: string;
+    tokenBudget?: number;
+    force?: boolean;
+    currentTokenCount?: number;
+    compactionTarget?: "budget" | "threshold";
+    customInstructions?: string;
+    legacyParams?: Record<string, unknown>;
+  }): Promise<CompactResult>;
+
+  prepareSubagentSpawn?(params: {
+    parentSessionKey: string;
+    childSessionKey: string;
+    ttlMs?: number;
+  }): Promise<SubagentSpawnPreparation | undefined>;
+
+  onSubagentEnded?(params: {
+    childSessionKey: string;
+    reason: SubagentEndReason;
+  }): Promise<void>;
+
+  dispose?(): Promise<void>;
+}
+
+export type ContextEngineFactory = () => ContextEngine | Promise<ContextEngine>;
+
+export type PluginLogger = {
+  debug?: (...args: unknown[]) => void;
+  info?: (...args: unknown[]) => void;
+  warn?: (...args: unknown[]) => void;
+  error?: (...args: unknown[]) => void;
+};
+
+export type OpenClawPluginApi = {
+  pluginConfig?: Record<string, unknown>;
+  logger?: PluginLogger;
+  registerContextEngine: (id: string, factory: ContextEngineFactory) => void;
+};