nebula-ai-core 0.1.0

package/src/brain/openai-brain.ts

@@ -0,0 +1,533 @@
+/**
+ * Provider-agnostic, OpenAI-compatible brain for Nebula.
+ *
+ * Replaces the legacy decentralized-compute brain. Talks to any endpoint that
+ * speaks the OpenAI `/chat/completions` shape via a simple `Authorization:
+ * Bearer` header, so the same adapter serves OpenAI (default GPT-4o-mini),
+ * Z.AI (GLM), Tencent Hunyuan, or any other compatible gateway by changing
+ * `baseUrl` / `model` / `apiKey` — no code change.
+ *
+ * The infer/compaction/tool-loop logic is intentionally identical to the
+ * harness's prior brain; only the transport (auth + endpoint) differs.
+ */
+import type { ToolSchema } from '../tools/types'
+import {
+  type CompactionOpts,
+  DEFAULT_COMPACTION_OPTS,
+  SUMMARY_SYSTEM_PROMPT,
+  compactHistory,
+  estimateTokens,
+  shouldCompact,
+} from './compaction'
+import { type FrozenPrefix, renderFrozenPrefix, renderUserContext } from './frozen-prefix'
+import type { HistoryPersist } from './history-persist'
+import { sanitizeDashes } from './sanitize'
+import type { Brain, BrainInferInput, BrainMessage, BrainTurn } from './types'
+
+/** Channel key used when none is specified — preserves single-history behavior. */
+export const DEFAULT_CHANNEL_KEY = 'default'
+
+/** Default cap on assistant output tokens per turn. */
+export const DEFAULT_MAX_OUTPUT_TOKENS = 4096
+
+/** Default OpenAI-compatible endpoint and model when not overridden. */
+export const DEFAULT_BASE_URL = 'https://api.openai.com/v1'
+export const DEFAULT_MODEL = 'gpt-4o-mini'
+
+export interface OpenAIBrainOpts {
+  /** OpenAI-compatible base URL, e.g. https://api.openai.com/v1 (default) or a Z.AI/Tencent gateway. */
+  baseUrl?: string
+  /** Bearer API key for the endpoint. */
+  apiKey: string
+  /** Model id, e.g. gpt-4o-mini (default), glm-4.6, hunyuan-*. */
+  model?: string
+  tools: ToolSchema[]
+  prefix: FrozenPrefix
+  /** Seed history for the legacy single-history (`'default'`) channel. */
+  history?: BrainMessage[]
+  /** Default 4096. */
+  maxOutputTokens?: number
+  /** Pre-flight auto-compaction config. Omit for defaults; pass `null` to disable. */
+  compaction?: CompactionOpts | null
+  /** Optional persistence handle for channel histories. */
+  persist?: HistoryPersist
+  onToolCall?: (call: { id: string; name: string; args: unknown }) => Promise<BrainMessage>
+}
+
+export class OpenAIBrain implements Brain {
+  private readonly baseUrl: string
+  private readonly apiKey: string
+  private readonly model: string
+  private ready = false
+  private readonly histories = new Map<string, BrainMessage[]>()
+  private readonly lastUsage = new Map<string, BrainTurn['usage']>()
+  private readonly renderedPrefix: string
+  private userContextText: string | null
+  private persistHydrated = false
+
+  constructor(private readonly opts: OpenAIBrainOpts) {
+    this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '')
+    this.apiKey = opts.apiKey
+    this.model = opts.model ?? DEFAULT_MODEL
+    if (opts.history && opts.history.length > 0) {
+      this.histories.set(DEFAULT_CHANNEL_KEY, [...opts.history])
+    }
+    this.renderedPrefix = renderFrozenPrefix(opts.prefix)
+    this.userContextText = renderUserContext(opts.prefix)
+  }
+
+  /** Refresh the per-turn user-context payload (MEMORY.md etc.) without rebuilding the prompt. */
+  refreshUserContext(prefix: FrozenPrefix): void {
+    this.userContextText = renderUserContext(prefix)
+  }
+
+  async init(): Promise<void> {
+    if (this.ready) return
+    this.ready = true
+    await this.hydrateFromPersist()
+  }
+
+  private async hydrateFromPersist(): Promise<void> {
+    if (this.persistHydrated || !this.opts.persist) return
+    this.persistHydrated = true
+    try {
+      const loaded = await this.opts.persist.loadAll()
+      for (const [key, history] of loaded) {
+        if (this.histories.has(key) && (this.histories.get(key)?.length ?? 0) > 0) continue
+        this.histories.set(key, [...history])
+      }
+    } catch {
+      // Persist load failures must never block brain startup.
+    }
+  }
+
+  getChannelHistory(channelKey: string = DEFAULT_CHANNEL_KEY): readonly BrainMessage[] {
+    return [...(this.histories.get(channelKey) ?? [])]
+  }
+
+  setChannelHistory(channelKey: string, history: BrainMessage[]): void {
+    this.histories.set(channelKey, [...history])
+  }
+
+  async clearChannel(channelKey: string = DEFAULT_CHANNEL_KEY): Promise<void> {
+    this.histories.set(channelKey, [])
+    this.lastUsage.delete(channelKey)
+    if (this.opts.persist) {
+      try {
+        await this.opts.persist.clearChannel(channelKey)
+      } catch {
+        // best-effort
+      }
+    }
+  }
+
+  listChannels(): string[] {
+    const out: string[] = []
+    for (const [k, v] of this.histories) {
+      if (v.length > 0) out.push(k)
+    }
+    return out
+  }
+
+  private getOrCreateHistory(channelKey: string): BrainMessage[] {
+    let h = this.histories.get(channelKey)
+    if (!h) {
+      h = []
+      this.histories.set(channelKey, h)
+    }
+    return h
+  }
+
+  async infer(input: BrainInferInput): Promise<BrainTurn> {
+    if (!this.ready) await this.init()
+    const signal = input.signal
+    if (signal?.aborted) {
+      throw new DOMException('aborted before infer started', 'AbortError')
+    }
+    const channelKey = input.channelKey ?? DEFAULT_CHANNEL_KEY
+    await this.maybeCompact(channelKey, input)
+
+    const history = this.getOrCreateHistory(channelKey)
+    const userText = normalizeUserContent(input)
+    const messages: BrainMessage[] = [{ role: 'system', content: this.renderedPrefix }, ...history]
+    if (this.userContextText) {
+      messages.push({ role: 'user', content: this.userContextText })
+    }
+    messages.push({ role: 'user', content: userText })
+
+    let turnResult: BrainTurn | null = null
+    let recoveredFromSafetyBlock = false
+    while (true) {
+      if (signal?.aborted) {
+        throw new DOMException('aborted between round-trips', 'AbortError')
+      }
+      const resp = await this.callCompletion(messages, signal)
+      turnResult = resp
+
+      if (!resp.toolCalls.length) {
+        const blockedName = detectBlockedToolError(resp.content ?? '')
+        if (blockedName && !recoveredFromSafetyBlock) {
+          recoveredFromSafetyBlock = true
+          const validNames = this.opts.tools
+            .map(t => (t as { name?: string }).name ?? '')
+            .filter(n => n.startsWith(`${blockedName}.`) || n.startsWith(`${blockedName}_`))
+            .slice(0, 12)
+          const hint =
+            validNames.length > 0
+              ? `Your last tool call used the bare name "${blockedName}", which is not a registered tool. Use the full name with subname (one of: ${validNames.join(', ')}). Retry now.`
+              : `Your last tool call used the bare name "${blockedName}", which is not a registered tool. Use the full namespaced name (e.g., something.action). Retry now.`
+          messages.push({ role: 'user', content: hint })
+          continue
+        }
+        messages.push({ role: 'assistant', content: resp.content ?? '' })
+        break
+      }
+
+      messages.push({
+        role: 'assistant',
+        content: resp.content ?? '',
+        toolCalls: resp.toolCalls,
+      })
+
+      for (const call of resp.toolCalls) {
+        if (signal?.aborted) {
+          throw new DOMException('aborted between tool calls', 'AbortError')
+        }
+        const isMalformed =
+          !call.name ||
+          (typeof call.args === 'string' &&
+            call.args !== '' &&
+            !looksLikeValidJsonString(call.args))
+        if (isMalformed) {
+          const toolLabel = call.name || MALFORMED_TOOL_LABEL
+          if (input.onToolEvent) {
+            try {
+              input.onToolEvent({
+                kind: 'start',
+                tool: toolLabel,
+                callId: call.id,
+                argsPreview: previewToolArgs(call.args),
+              })
+              input.onToolEvent({ kind: 'end', tool: toolLabel, callId: call.id, ok: false })
+            } catch {
+              /* swallow */
+            }
+          }
+          messages.push({
+            role: 'tool',
+            toolCallId: call.id,
+            content: JSON.stringify({
+              error:
+                'Tool call envelope was malformed (empty name or truncated arguments). Re-emit with a complete tool name and a parseable JSON args object.',
+            }),
+          })
+          continue
+        }
+        if (!this.opts.onToolCall) {
+          messages.push({
+            role: 'tool',
+            toolCallId: call.id,
+            content: JSON.stringify({ error: 'Tool handler not wired' }),
+          })
+          continue
+        }
+        if (input.onToolEvent) {
+          try {
+            input.onToolEvent({
+              kind: 'start',
+              tool: call.name,
+              callId: call.id,
+              argsPreview: previewToolArgs(call.args),
+            })
+          } catch {
+            /* observer errors must never block tool execution */
+          }
+        }
+        const toolMsg = await this.opts.onToolCall(call)
+        if (input.onToolEvent) {
+          try {
+            input.onToolEvent({
+              kind: 'end',
+              tool: call.name,
+              callId: call.id,
+              ok: inferToolOk(toolMsg.content ?? ''),
+            })
+          } catch {
+            /* swallow */
+          }
+        }
+        messages.push({ ...toolMsg, toolCallId: call.id })
+      }
+    }
+
+    const finalAssistant = findLastAssistantContent(messages)
+    const userMsg: BrainMessage = { role: 'user', content: userText }
+    const assistantMsg: BrainMessage = { role: 'assistant', content: finalAssistant }
+    history.push(userMsg)
+    history.push(assistantMsg)
+
+    if (turnResult?.usage) this.lastUsage.set(channelKey, turnResult.usage)
+
+    if (this.opts.persist) {
+      try {
+        await this.opts.persist.appendTurn(channelKey, userMsg, assistantMsg)
+      } catch {
+        // Persist failure is non-fatal for the live turn.
+      }
+    }
+
+    if (turnResult?.content) {
+      turnResult.content = sanitizeDashes(turnResult.content)
+    }
+    return turnResult ?? { content: null, toolCalls: [] }
+  }
+
+  private async maybeCompact(channelKey: string, input: BrainInferInput): Promise<void> {
+    if (this.opts.compaction === null) return
+    const cfg = this.opts.compaction ?? DEFAULT_COMPACTION_OPTS
+    const history = this.histories.get(channelKey)
+    if (!history || history.length === 0) return
+    const lastUsage = this.lastUsage.get(channelKey)
+    const trigger = shouldCompact(history, lastUsage?.promptTokens ?? null, cfg)
+    if (trigger == null) return
+    let compacted: BrainMessage[]
+    try {
+      compacted = await compactHistory(history, cfg, async older => this.summarizeOlder(older))
+    } catch {
+      return
+    }
+    if (compacted.length >= history.length) return
+    this.histories.set(channelKey, compacted)
+    this.lastUsage.delete(channelKey)
+    if (this.opts.persist) {
+      try {
+        await this.opts.persist.rewriteChannel(channelKey, compacted)
+      } catch {
+        // best-effort
+      }
+    }
+    if (input.onCompactionEvent) {
+      try {
+        input.onCompactionEvent({
+          channelKey,
+          from: history.length,
+          to: compacted.length,
+          promptTokens: trigger,
+        })
+      } catch {
+        /* observer errors swallowed */
+      }
+    }
+  }
+
+  private async summarizeOlder(older: readonly BrainMessage[]): Promise<string> {
+    const flat = older
+      .map(m => {
+        const tag = m.role.toUpperCase()
+        if (m.toolCalls && m.toolCalls.length > 0) {
+          const calls = m.toolCalls
+            .map(
+              tc =>
+                `${tc.name}(${typeof tc.args === 'string' ? tc.args : JSON.stringify(tc.args ?? {})})`,
+            )
+            .join(' | ')
+          return `${tag}: ${m.content || ''}\n[TOOL_CALLS] ${calls}`
+        }
+        return `${tag}: ${m.content || ''}`
+      })
+      .join('\n\n')
+    const body = {
+      model: this.model,
+      messages: [
+        { role: 'system', content: SUMMARY_SYSTEM_PROMPT },
+        { role: 'user', content: flat },
+      ],
+      max_tokens: 1024,
+    }
+    const resp = await fetch(`${this.baseUrl}/chat/completions`, {
+      method: 'POST',
+      headers: this.headers(),
+      body: JSON.stringify(body),
+    })
+    if (!resp.ok) {
+      throw new Error(`Compaction summarize HTTP ${resp.status}`)
+    }
+    const json = (await resp.json()) as {
+      choices: Array<{ message: { content?: string | null } }>
+    }
+    return (json.choices[0]?.message.content ?? '').trim()
+  }
+
+  private headers(): Record<string, string> {
+    return {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${this.apiKey}`,
+    }
+  }
+
+  private async callCompletion(messages: BrainMessage[], signal?: AbortSignal): Promise<BrainTurn> {
+    const body: Record<string, unknown> = {
+      model: this.model,
+      messages: messages.map(m => {
+        if (m.role === 'tool') {
+          return { role: 'tool', tool_call_id: m.toolCallId, content: m.content }
+        }
+        if (m.role === 'assistant' && m.toolCalls && m.toolCalls.length > 0) {
+          return {
+            role: 'assistant',
+            content: m.content || null,
+            tool_calls: m.toolCalls.map(tc => ({
+              id: tc.id,
+              type: 'function',
+              function: {
+                name: tc.name,
+                arguments: typeof tc.args === 'string' ? tc.args : JSON.stringify(tc.args),
+              },
+            })),
+          }
+        }
+        return { role: m.role, content: m.content }
+      }),
+      max_tokens: this.opts.maxOutputTokens ?? DEFAULT_MAX_OUTPUT_TOKENS,
+    }
+    if (this.opts.tools.length > 0) {
+      body.tools = this.opts.tools
+      body.tool_choice = 'auto'
+    }
+    const resp = await fetch(`${this.baseUrl}/chat/completions`, {
+      method: 'POST',
+      headers: this.headers(),
+      body: JSON.stringify(body),
+      signal,
+    })
+    if (!resp.ok) {
+      const text = await resp.text()
+      throw new Error(`Brain HTTP ${resp.status}: ${text}`)
+    }
+    const json = (await resp.json()) as {
+      choices: Array<{
+        finish_reason?: string
+        message: {
+          content?: string | null
+          tool_calls?: Array<{ id: string; function: { name: string; arguments: string } }>
+          reasoning_content?: string
+        }
+      }>
+      usage?: {
+        prompt_tokens?: number
+        completion_tokens?: number
+        total_tokens?: number
+        prompt_tokens_details?: { cached_tokens?: number }
+      }
+    }
+    const choice = json.choices[0]!
+    const msg = choice.message
+    const rawContent = msg.content
+    const reasoning = msg.reasoning_content
+    const fallbackFromReasoning =
+      !rawContent && reasoning && reasoning.length > 0 ? stripThinkBlocks(reasoning) : null
+    return {
+      content: rawContent ? rawContent : fallbackFromReasoning,
+      toolCalls: (msg.tool_calls ?? []).map(tc => ({
+        id: tc.id,
+        name: tc.function.name,
+        args: safeParseJson(tc.function.arguments),
+      })),
+      reasoningContent: msg.reasoning_content,
+      finishReason: choice.finish_reason,
+      usage: {
+        promptTokens: json.usage?.prompt_tokens,
+        completionTokens: json.usage?.completion_tokens,
+        totalTokens: json.usage?.total_tokens,
+        cachedTokens: json.usage?.prompt_tokens_details?.cached_tokens,
+      },
+    }
+  }
+}
+
+function normalizeUserContent(input: BrainInferInput): string {
+  const d = input.event.payload.data
+  if (typeof d === 'string') return d
+  return JSON.stringify(d)
+}
+
+function safeParseJson(raw: string): unknown {
+  try {
+    return JSON.parse(raw)
+  } catch {
+    return raw
+  }
+}
+
+export function looksLikeValidJsonString(raw: string): boolean {
+  if (!raw || raw.length === 0) return true
+  try {
+    JSON.parse(raw)
+    return true
+  } catch {
+    return false
+  }
+}
+
+const THINK_BLOCK_RE = /<think>[\s\S]*?<\/think>/g
+const MALFORMED_TOOL_LABEL = '<malformed>'
+
+export function stripThinkBlocks(text: string): string {
+  if (!text) return text
+  return text.replace(THINK_BLOCK_RE, '').trim()
+}
+
+export function detectBlockedToolError(content: string): string | null {
+  if (!content) return null
+  const m = content.match(/Unauthorized:\s+(\S+)\s+is a blocked tool/)
+  return m ? m[1]! : null
+}
+
+function findLastAssistantContent(messages: BrainMessage[]): string {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i]
+    if (m && m.role === 'assistant') return m.content
+  }
+  return ''
+}
+
+export function previewToolArgs(args: unknown): string {
+  if (args == null) return ''
+  if (typeof args === 'string') return truncatePreview(args)
+  if (Array.isArray(args)) return `[${args.length}]`
+  if (typeof args === 'object') {
+    const o = args as Record<string, unknown>
+    const keys = Object.keys(o)
+    if (keys.length === 0) return ''
+    for (const k of ['url', 'path', 'command', 'query', 'name', 'address']) {
+      const v = o[k]
+      if (typeof v === 'string' && v.length > 0) return truncatePreview(`${k}=${v}`)
+    }
+    return truncatePreview(keys.join(','))
+  }
+  try {
+    return truncatePreview(String(args))
+  } catch {
+    return ''
+  }
+}
+
+function truncatePreview(s: string): string {
+  const max = 60
+  if (s.length <= max) return s
+  return `${s.slice(0, max - 1)}…`
+}
+
+export function inferToolOk(content: string): boolean {
+  if (!content) return true
+  try {
+    const o = JSON.parse(content) as Record<string, unknown>
+    if (typeof o.ok === 'boolean') return o.ok
+    if (typeof o.error === 'string' && o.error.length > 0) return false
+    return true
+  } catch {
+    return !content.toLowerCase().includes('error')
+  }
+}
+
+export { estimateTokens }

package/src/brain/sanitize.ts

@@ -0,0 +1,23 @@
+/**
+ * Backstop sanitizer for brain output.
+ *
+ * The frozen-prefix system prompt forbids em-dashes (U+2014) and en-dashes
+ * (U+2013). Weak models (qwen3.6-plus, nebula's flagship) occasionally slip
+ * despite the rule. This sanitizer is the final filter on brain output,
+ * applied at the single brain return point in og-compute.ts so every
+ * surface (TUI, TG, A2A, market) sees clean text.
+ *
+ * Replacements were chosen to preserve readability with minimal punctuation
+ * disruption:
+ *   - U+2014 em-dash → comma + space ("X — Y" → "X, Y")
+ *   - U+2013 en-dash → ASCII hyphen ("3–5" → "3-5")
+ *
+ * Stand-alone hyphen-substitution avoids accidentally turning a number
+ * range into prose-only ("3 to 5" feels heavy-handed in code/numeric
+ * contexts), while comma substitution for em-dash keeps the prose rhythm
+ * the model intended.
+ */
+export function sanitizeDashes(text: string): string {
+  if (!text) return text
+  return text.replace(/—/g, ', ').replace(/–/g, '-')
+}

package/src/brain/stub.ts

@@ -0,0 +1,20 @@
+import type { Brain, BrainInferInput, BrainTurn } from './types'
+
+/**
+ * Echo brain for phase 1 — takes the event payload text and returns it
+ * verbatim. Lets us wire and test the runtime loop before the real Mantle
+ * Compute integration lands in phase 3.
+ */
+export class StubBrain implements Brain {
+  async infer(input: BrainInferInput): Promise<BrainTurn> {
+    const text =
+      typeof input.event.payload.data === 'string'
+        ? input.event.payload.data
+        : JSON.stringify(input.event.payload.data)
+    return {
+      content: `[stub-brain echo] ${text}`,
+      toolCalls: [],
+      finishReason: 'stop',
+    }
+  }
+}

package/src/brain/types.ts

@@ -0,0 +1,129 @@
+import type { NebulaEvent } from '../events/types'
+import type { ToolCall, ToolSchema } from '../tools/types'
+
+export interface BrainMessage {
+  role: 'system' | 'user' | 'assistant' | 'tool'
+  content: string
+  /** Required on `tool` role: the id of the assistant tool_call this responds to. */
+  toolCallId?: string
+  /**
+   * Required on `assistant` role messages that issued tool_calls. Without this
+   * the next round-trip's `tool` message has no preceding `tool_calls` to
+   * reference, and the OpenAI-compat endpoint rejects with HTTP 400
+   * "messages with role 'tool' must be a response to a preceeding message
+   * with 'tool_calls'".
+   */
+  toolCalls?: Array<{ id: string; name: string; args: unknown }>
+}
+
+/**
+ * Per-tool-call lifecycle event surfaced to the dispatcher for UI rendering.
+ * Distinct from the brain-construction `onToolCall` (which actually EXECUTES
+ * the tool); this is fire-and-forget for "show what the agent is doing right
+ * now" surfaces (TG progress message, future TUI bridge, etc.).
+ *
+ * Errors thrown by the observer are swallowed by the brain.
+ */
+export interface BrainToolEvent {
+  /** 'start' fires BEFORE tool execution; 'end' fires AFTER. */
+  kind: 'start' | 'end'
+  /** Fully-qualified tool name, e.g. `shell.run`. */
+  tool: string
+  /** Tool-call id; correlates start ↔ end pair within the same turn. */
+  callId: string
+  /** Short stringified args preview (≤ ~80 chars). Present on 'start'. */
+  argsPreview?: string
+  /** Tool execution success. Heuristic from result content. Present on 'end'. */
+  ok?: boolean
+}
+
+/**
+ * Compaction event surfaced when the brain auto-folds older history into a
+ * summary message. Subscribers (TUI primarily) use this to push a system row
+ * so the operator knows the summary fired. Errors thrown by the observer are
+ * swallowed by the brain.
+ */
+export interface BrainCompactionEvent {
+  /** Channel whose history was compacted. */
+  channelKey: string
+  /** Number of messages BEFORE compaction (full history length). */
+  from: number
+  /** Number of messages AFTER compaction (summary + kept recent). */
+  to: number
+  /** Token estimate of the pre-compaction history. */
+  promptTokens: number
+}
+
+export interface BrainInferInput {
+  /** The event that woke the brain. */
+  event: NebulaEvent
+  /** Optional multi-turn context beyond the event payload. */
+  history?: BrainMessage[]
+  /** Optional tool allowlist override (defaults to all registered tools). */
+  toolWhitelist?: string[]
+  /**
+   * Channel partition for this turn's history. Each surface keeps its own
+   * conversation context: TUI/stdin is `'tui:stdin'`, Telegram DM is
+   * `agent:<name>:telegram:dm:<chatId>`, A2A drains use `a2a:<peer>`,
+   * marketplace uses `'marketplace'`. Missing key falls back to `'default'`.
+   *
+   * Backward-compatible: omitting the key keeps the legacy single-history
+   * behavior under the `'default'` channel.
+   */
+  channelKey?: string
+  /**
+   * Cancel the in-flight turn. Aborts the upstream HTTP fetch (so Mantle
+   * Compute stops billing the round-trip immediately) and short-circuits
+   * the tool-call loop. The promise rejects with a DOMException whose
+   * `.name === 'AbortError'`. Caller should catch that and treat it as
+   * a clean operator-driven cancel, not an error.
+   */
+  signal?: AbortSignal
+  /**
+   * Per-turn observer of tool-call lifecycle. Fired by the brain before and
+   * after each tool execution. Use for UI streaming (TG progress message,
+   * TUI bridge) without bothering the brain-construction onToolCall (which
+   * is the actual tool executor). Errors swallowed by the brain.
+   */
+  onToolEvent?: (ev: BrainToolEvent) => void
+  /**
+   * Per-turn observer of compaction events. Fires when the pre-flight
+   * threshold check triggers a summarize-fold of older messages. TUI
+   * surfaces this as a system row; TG dispatchers leave it silent.
+   */
+  onCompactionEvent?: (ev: BrainCompactionEvent) => void
+}
+
+export interface BrainTurn {
+  content: string | null
+  toolCalls: ToolCall[]
+  reasoningContent?: string
+  finishReason?: string
+  usage?: {
+    promptTokens?: number
+    completionTokens?: number
+    totalTokens?: number
+    cachedTokens?: number
+  }
+}
+
+export interface Brain {
+  infer(input: BrainInferInput): Promise<BrainTurn>
+  /**
+   * v0.20.0: clear a channel's history. Optional so legacy non-OG brains
+   * (StubBrain etc) don't have to implement it.
+   */
+  clearChannel?(channelKey?: string): Promise<void> | void
+}
+
+export interface BrainProvider {
+  name: string
+  build(opts: BrainProviderOpts): Promise<Brain>
+}
+
+export interface BrainProviderOpts {
+  systemPrompt: string
+  tools: ToolSchema[]
+  maxTokens?: number
+  maxOutputTokens?: number
+}