alvis/AgapHost
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

ai: migrate LLM backbone from Kimi CLI to Codex CLI

Browse Source 
Retires the Moonshot/Kimi subscription in favour of the already-paid ChatGPT
plan. Both CLI wrappers now run `codex exec`; the kimi-agent container is gone.

adolf-llm + hindsight-llm:
- runKimi -> runCodex (`codex exec --json --skip-git-repo-check`), resume via
  `codex exec resume <thread_id>`.
- MCP moves from a per-session .mcp.json (a workaround for Kimi having no
  --mcp-config-file flag) to a $CODEX_HOME/config.toml generated once at
  startup from shared-mcp.json. Field translation is load-bearing:
  bearerTokenEnvVar -> bearer_token_env_var, enabledTools -> enabled_tools.
- approval_policy="never" + sandbox_mode required, or unattended turns block
  on an approval prompt nobody can answer.

kimi-agent removed. It was the ONLY large-tier deployment behind LiteLLM, so
deleting it outright would have silently degraded every large-tier request to
the local 4B model via the existing fallbacks. tier-large, the auto_router
complex-reasoning route and their fallbacks now point at the codex-backed
adolf-llm wrapper (model_name: codex-agent).

Three environment blockers fixed along the way:
- OpenAI geo-blocks this host (403 unsupported_country_region_territory).
  Both containers now egress via the host xray proxy, with NO_PROXY keeping
  MCP and *.alogins.net traffic off the tunnel.
- node:22-slim ships no system CA store; the Rust codex binary validates TLS
  against it, so every HTTPS call failed with a generic transport error while
  Node's own fetch worked. ca-certificates added to both images.
- `codex exec resume` rejects -C/--cd (plain `codex exec` accepts it), which
  broke follow-up turns while first turns succeeded.

Known regression: Kimi's managed-usage API has no Codex equivalent, so the
/usage route returns 501 and there is no quota probe for the codex model.
The two quota plugins degrade quietly to no output.

Also: stop tracking cognee.env (live LLM + JWT secrets) and gitignore it.
The secrets remain in earlier history and should be rotated.

Verified live: plain turn, SSE streaming, session resume, MCP tool call,
bearer-token MCP call, and completions through both LiteLLM routes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014Y5QPagv4iun1ghpwM96Ff
This commit is contained in:
alvis
2026-08-01 06:13:27 +00:00
parent a27bae828a
commit 9094d71e2f
66 changed files with 653 additions and 851 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
ai/adolf-llm/Dockerfile Normal file
View File

@@ -0,0 +1,24 @@
FROM node:22-slim
# ca-certificates is REQUIRED, not optional: node:22-slim ships no system CA
# store. Node bundles its own so JS fetch works, but the Codex CLI is a Rust
# binary and validates TLS against the system store — without this every HTTPS
# call (incl. `codex login`) dies after the TCP/proxy connect with a generic
# "error sending request". Cost us a long debug; do not drop it.
RUN apt-get update \
&& apt-get install -y --no-install-recommends ca-certificates \
&& rm -rf /var/lib/apt/lists/*
RUN npm install -g @openai/codex
WORKDIR /workspace
COPY server.js /app/server.js
# Codex reads auth + config from $CODEX_HOME (default ~/.codex). Pinned
# explicitly so the compose volume mount and the config writer agree.
ENV CODEX_HOME=/root/.codex
EXPOSE 8010
ENTRYPOINT ["node", "/app/server.js"]

716
ai/adolf-llm/server.js Normal file
View File

@@ -0,0 +1,716 @@
const http = require('http');
const fs = require('fs');
const path = require('path');
const crypto = require('crypto');
const { spawn } = require('child_process');
// Both overridable purely so the wrapper can be exercised outside the
// container (the defaults are the in-container values).
const PORT = Number(process.env.PORT) || 8010;
const SHARED_MCP_PATH = process.env.SHARED_MCP_PATH || '/shared-mcp.json';
const MODEL_ID = 'adolf';
const TIMEOUT_MS = 15 * 60 * 1000;
const WORKSPACE = process.env.WORKSPACE || '/workspace';
const CONV_ROOT = path.join(WORKSPACE, 'conversations');
const STATE_DIR = path.join(WORKSPACE, '.adolf-llm');
const MAP_FILE = path.join(STATE_DIR, 'sessions.json');
const MAX_ENTRIES = 1000; // prune oldest beyond this
fs.mkdirSync(CONV_ROOT, { recursive: true });
fs.mkdirSync(STATE_DIR, { recursive: true });
// ---------------------------------------------------------------------------
// Shared MCP layer. Unlike Kimi Code CLI (which had no --mcp-config-file flag
// and forced a per-session `.mcp.json` dropped into each working directory),
// Codex reads MCP servers from `$CODEX_HOME/config.toml` under `[mcp_servers.*]`
// tables. So this is now written ONCE at startup instead of per session.
//
// Single source of truth is unchanged: `/shared-mcp.json` (mounted read-only
// from the repo root's `shared-mcp.json`, the same file OpenClaw's own
// `mcp.servers` registry uses). Adding a server stays a one-file change.
//
// Transport mapping. shared-mcp.json entries are either:
// { command, args, env } -> stdio server
// { url, type: "http" } -> remote streamable-http server
// Codex expresses stdio servers as `command`/`args`/`env`, and remote servers
// as `url` with an optional `bearer_token_env_var`. It has no `type` key; the
// shape (command vs url) selects the transport, same inference Kimi did. The
// `type: "http"` key that shared-mcp.json carries for OpenClaw's benefit is
// simply not emitted here.
const CODEX_HOME = process.env.CODEX_HOME || '/root/.codex';
let SHARED_MCP_SERVERS = {};
try {
const raw = fs.readFileSync(SHARED_MCP_PATH, 'utf8');
SHARED_MCP_SERVERS = JSON.parse(raw).mcpServers || {};
} catch (err) {
console.error(`shared-mcp.json not loaded (${err.message}); sessions will get no shared MCP servers`);
}
// Minimal TOML emitter — we only ever emit strings, string arrays and flat
// string maps, so a full TOML library would be dead weight.
function tomlString(s) {
return JSON.stringify(String(s)); // TOML basic strings share JSON escaping
}
function tomlValue(v) {
if (Array.isArray(v)) return `[${v.map(tomlString).join(', ')}]`;
return tomlString(v);
}
function renderMcpToml(servers) {
const lines = [
'# GENERATED by adolf-llm from /shared-mcp.json — do not edit by hand.',
'# Regenerated on every container start; manual edits are lost.',
'',
];
for (const [name, cfg] of Object.entries(servers)) {
lines.push(`[mcp_servers.${name}]`);
if (cfg.command) {
lines.push(`command = ${tomlValue(cfg.command)}`);
if (cfg.args && cfg.args.length) lines.push(`args = ${tomlValue(cfg.args)}`);
} else if (cfg.url) {
lines.push(`url = ${tomlValue(cfg.url)}`);
} else {
console.error(`shared-mcp.json: server "${name}" has neither command nor url; skipped`);
lines.pop();
continue;
}
// Field-name translation, Kimi -> Codex. shared-mcp.json is written in
// Kimi/OpenClaw's camelCase dialect; Codex's RawMcpServerConfig uses
// snake_case. Both keys are load-bearing:
// bearerTokenEnvVar -> bearer_token_env_var (agap + marketplace auth;
// without it every tool call on those servers returns HTTP 401)
// enabledTools -> enabled_tools (the capability allow-list
// that ai/agent-registry.yaml's mcp_tool_filter is validated against;
// dropping it would silently widen Adolf's tool access)
if (cfg.bearerTokenEnvVar) {
lines.push(`bearer_token_env_var = ${tomlValue(cfg.bearerTokenEnvVar)}`);
}
if (cfg.enabledTools && cfg.enabledTools.length) {
lines.push(`enabled_tools = ${tomlValue(cfg.enabledTools)}`);
}
if (cfg.env && Object.keys(cfg.env).length) {
lines.push(`[mcp_servers.${name}.env]`);
for (const [k, v] of Object.entries(cfg.env)) lines.push(`${k} = ${tomlValue(v)}`);
}
lines.push('');
}
return lines.join('\n');
}
// Write the Codex config once at startup: MCP servers + the headless-operation
// settings. `approval_policy = "never"` and `sandbox_mode` are load-bearing —
// Codex defaults to asking for approval before running a tool, and nobody is
// there to answer, so without these a turn hangs until the 15-minute timeout
// instead of failing loudly.
function writeCodexConfig() {
fs.mkdirSync(CODEX_HOME, { recursive: true });
const header = [
'approval_policy = "never"',
'sandbox_mode = "danger-full-access"',
'',
].join('\n');
fs.writeFileSync(path.join(CODEX_HOME, 'config.toml'), header + renderMcpToml(SHARED_MCP_SERVERS));
}
writeCodexConfig();
// ---------------------------------------------------------------------------
// Memory lives at the OpenClaw layer, not here (P8). The Adolf gateway loads
// the `cognee-memory` OpenClaw plugin, which owns all memory touchpoints:
// - before_prompt_build => LLM-free cognee graph recall, injected into the
// prompt this wrapper then receives from OpenClaw.
// - agent_end => raw `add` of the turn to cognee.
// - background sweep => async `cognify` on cognee-llm (Kimi).
// - cognee_recall tool + cognee-mcp `recall` for on-demand deep queries.
// This wrapper is therefore a dumb model endpoint again: it must never call
// cognee itself. The former cogneeSearch/cogneeAdd stubs (and their call sites)
// were deleted when the plugin took over (P8).
// ---------------------------------------------------------------------------
// Persistent conversation -> Codex session (thread) map.
// Primary key: `chat:<chat_id>` parsed from OpenClaw's "Conversation info" block
// (Gate 2). Fallback key: `hist:<sha256(prior history)>` when no chat_id is
// present (e.g. webchat surface / future OpenClaw layout change).
// value = { convId, sessionId, dir, ts }
let sessionMap = {};
try {
sessionMap = JSON.parse(fs.readFileSync(MAP_FILE, 'utf8'));
} catch {
sessionMap = {};
}
let writeQueue = Promise.resolve();
function persistMap() {
// prune to the MAX_ENTRIES most-recently-used before writing
const keys = Object.keys(sessionMap);
if (keys.length > MAX_ENTRIES) {
keys.sort((a, b) => (sessionMap[a].ts || 0) - (sessionMap[b].ts || 0));
for (const k of keys.slice(0, keys.length - MAX_ENTRIES)) delete sessionMap[k];
}
const snapshot = JSON.stringify(sessionMap);
writeQueue = writeQueue.then(
() => fs.promises.writeFile(MAP_FILE, snapshot),
() => fs.promises.writeFile(MAP_FILE, snapshot),
);
return writeQueue;
}
// ---------------------------------------------------------------------------
// Message helpers.
function textOf(msg) {
const c = msg.content;
if (Array.isArray(c)) return c.map(p => (typeof p === 'string' ? p : p.text || '')).join('\n');
return c == null ? '' : String(c);
}
// only user/assistant turns define conversation identity (system is constant)
function convTurns(messages) {
return messages.filter(m => m.role === 'user' || m.role === 'assistant');
}
function historyKey(turns) {
const norm = turns.map(m => ({ role: m.role, text: textOf(m).trim() }));
return crypto.createHash('sha256').update(JSON.stringify(norm)).digest('hex');
}
function renderTranscript(turns) {
return turns
.map(m => `${m.role === 'assistant' ? 'Assistant' : 'User'}: ${textOf(m)}`)
.join('\n\n');
}
// ---------------------------------------------------------------------------
// Gate 2 — parse the stable chat_id out of OpenClaw's untrusted-metadata block.
// OpenClaw injects, into the *user-role* content, a block that looks like:
// Conversation info (untrusted metadata):
// ```json
// { "chat_id": "matrix:!room:server", "message_id": "...", ... }
// ```
// We grep on the label string (never a fixed line offset) then pull the first
// balanced JSON object after it and read chat_id. Robust to edited/truncated
// history, which is exactly why it beats a history hash for the common case.
const CONV_INFO_LABEL = 'Conversation info (untrusted metadata):';
function extractBalancedJson(str, from) {
const start = str.indexOf('{', from);
if (start === -1) return null;
let depth = 0;
let inStr = false;
let esc = false;
for (let i = start; i < str.length; i++) {
const ch = str[i];
if (inStr) {
if (esc) esc = false;
else if (ch === '\\') esc = true;
else if (ch === '"') inStr = false;
continue;
}
if (ch === '"') inStr = true;
else if (ch === '{') depth++;
else if (ch === '}') {
depth--;
if (depth === 0) return str.slice(start, i + 1);
}
}
return null;
}
function extractChatId(userMsg) {
const text = textOf(userMsg);
const at = text.indexOf(CONV_INFO_LABEL);
if (at === -1) return null;
const jsonStr = extractBalancedJson(text, at + CONV_INFO_LABEL.length);
if (!jsonStr) return null;
try {
const obj = JSON.parse(jsonStr);
const id = obj.chat_id;
return typeof id === 'string' && id ? id : null;
} catch {
return null;
}
}
// ---------------------------------------------------------------------------
// Gate 3 — media. Persist inbound image parts into the session dir and return
// relative path references; the CLI autonomously calls its built-in
// ReadMediaFile tool on referenced paths (no flag/placeholder syntax needed).
const MIME_EXT = {
'image/png': 'png',
'image/jpeg': 'jpg',
'image/jpg': 'jpg',
'image/webp': 'webp',
'image/gif': 'gif',
'image/bmp': 'bmp',
'image/heic': 'heic',
'image/heif': 'heif',
};
function extFromMime(mime) {
return MIME_EXT[(mime || '').toLowerCase()] || 'img';
}
// Persist one image_url part; returns "./img_N.ext" or null if it couldn't.
async function persistImage(url, dir, n) {
if (typeof url !== 'string' || !url) return null;
if (url.startsWith('data:')) {
const m = /^data:([^;,]+)?(;base64)?,(.*)$/s.exec(url);
if (!m) return null;
const mime = m[1] || 'application/octet-stream';
const isB64 = !!m[2];
const ext = extFromMime(mime);
const name = `img_${n}.${ext}`;
const buf = isB64
? Buffer.from(m[3], 'base64')
: Buffer.from(decodeURIComponent(m[3]), 'utf8');
fs.writeFileSync(path.join(dir, name), buf);
return `./${name}`;
}
// Remote URL: best-effort fetch so the CLI gets a local path to ReadMediaFile.
// On any failure fall back to handing the raw URL to the model as text.
if (/^https?:\/\//i.test(url)) {
try {
const resp = await fetch(url);
if (!resp.ok) return url;
const mime = resp.headers.get('content-type') || '';
const ext = extFromMime(mime.split(';')[0].trim());
const name = `img_${n}.${ext}`;
const buf = Buffer.from(await resp.arrayBuffer());
fs.writeFileSync(path.join(dir, name), buf);
return `./${name}`;
} catch {
return url;
}
}
return null;
}
// Build the prompt for the current user turn: join text parts, persist any
// image parts, append path references.
async function buildPrompt(userMsg, dir) {
const content = userMsg.content;
const textParts = [];
const imageRefs = [];
if (Array.isArray(content)) {
let n = 0;
for (const part of content) {
if (typeof part === 'string') {
textParts.push(part);
} else if (part && (part.type === 'text' || typeof part.text === 'string')) {
textParts.push(part.text || '');
} else if (part && part.type === 'image_url' && part.image_url && part.image_url.url) {
n++;
const ref = await persistImage(part.image_url.url, dir, n);
if (ref) imageRefs.push(ref);
} else if (part && part.type === 'input_image' && (part.image_url || part.url)) {
n++;
const u = typeof part.image_url === 'string' ? part.image_url : part.url;
const ref = await persistImage(u, dir, n);
if (ref) imageRefs.push(ref);
}
}
} else {
textParts.push(content == null ? '' : String(content));
}
let prompt = textParts.join('\n');
if (imageRefs.length) {
prompt += '\n\n' + imageRefs.map(r => `See attached image: ${r}`).join('\n');
}
return prompt;
}
// ---------------------------------------------------------------------------
// Codex invocation with REAL streaming. Parses `codex exec --json` incrementally:
// each complete stdout line is one JSON event.
//
// Codex 0.146 ships TWO event schemas and which one `--json` emits can change
// between releases, so we handle both rather than pinning to one:
//
// legacy "msg" schema:
// {"id":..,"msg":{"type":"agent_message_delta","delta":"..."}} -> delta
// {"id":..,"msg":{"type":"agent_message","message":"..."}} -> full text
// {"id":..,"msg":{"type":"session_configured","session_id":".."}}-> session id
// newer thread/turn/item schema:
// {"type":"thread.started","thread_id":"..."} -> session id
// {"type":"item.completed","item":{"type":"agent_message",...}} -> full text
//
// Non-assistant items (reasoning, command execution, MCP tool calls) are
// deliberately ignored — Adolf's users see the answer, not the agent's work.
//
// Sequencing note: when a run emits streaming deltas AND a terminal full-text
// message, the full text is the same content already streamed. We therefore
// prefer deltas when any arrived, and fall back to the terminal message only
// when none did — otherwise the reply would be duplicated.
//
// onDelta(chunk) is called per assistant content fragment as it arrives.
// Resolves { text, sessionId } once the process closes.
function runCodex({ prompt, cwd, resumeId, onDelta, signal }) {
return new Promise((resolve, reject) => {
if (signal?.aborted) { reject(new Error('aborted before start')); return; }
// `exec resume <id>` must come before the prompt; `--skip-git-repo-check`
// is required because session dirs under /workspace are not git repos.
//
// `-C/--cd` is accepted by `codex exec` but NOT by `codex exec resume` —
// passing it there fails with "unexpected argument '-C' found" and breaks
// every follow-up turn while first turns still work. The spawn cwd below
// already puts the process in the right directory, so -C is only an
// explicit belt-and-braces on the fresh-session path.
const args = ['exec'];
if (resumeId) {
args.push('resume', resumeId, '--json', '--skip-git-repo-check', prompt);
} else {
args.push('--json', '--skip-git-repo-check', '-C', cwd, prompt);
}
// stdin MUST be 'ignore'. With the default 'pipe', codex prints "Reading
// additional input from stdin..." and blocks waiting for EOF on a pipe this
// wrapper never writes to or closes — every turn would hang until the
// 15-minute timeout. (Kimi's CLI did not read stdin, so this is new.)
const child = spawn('codex', args, {
cwd,
timeout: TIMEOUT_MS,
stdio: ['ignore', 'pipe', 'pipe'],
});
let buf = '';
let stderr = '';
const parts = []; // streamed deltas, in order
let finalText = null; // terminal full-text message, if the run emits one
let errText = null; // structured error reported on the event stream
let sessionId = null;
let settled = false;
let aborted = false;
// If the caller aborts (the gateway/client disconnected — e.g. its idle
// watchdog gave up), kill the child so it doesn't keep grinding an
// orphaned agent turn to completion, wasting Codex quota and streaming into
// a dead socket. SIGTERM first, hard SIGKILL if it lingers.
const onAbort = () => {
aborted = true;
try { child.kill('SIGTERM'); } catch {}
setTimeout(() => { try { child.kill('SIGKILL'); } catch {} }, 3000).unref();
};
if (signal) signal.addEventListener('abort', onAbort, { once: true });
function handleLine(line) {
const t = line.trim();
if (!t) return;
let obj;
try { obj = JSON.parse(t); } catch { return; }
// --- legacy "msg" schema -------------------------------------------
const msg = obj.msg;
if (msg && typeof msg.type === 'string') {
if (msg.type === 'agent_message_delta' && typeof msg.delta === 'string' && msg.delta) {
parts.push(msg.delta);
if (onDelta) onDelta(msg.delta);
} else if (msg.type === 'agent_message' && typeof msg.message === 'string' && msg.message) {
finalText = msg.message;
} else if (msg.type === 'session_configured' && msg.session_id) {
sessionId = msg.session_id;
} else if (msg.type === 'error' && msg.message) {
errText = msg.message;
}
return;
}
// --- newer thread/turn/item schema ----------------------------------
if (obj.type === 'thread.started' && obj.thread_id) {
sessionId = obj.thread_id;
} else if (obj.type === 'item.completed' && obj.item) {
const item = obj.item;
if (item.type === 'agent_message') {
const text = typeof item.text === 'string' ? item.text : item.message;
if (typeof text === 'string' && text) finalText = text;
}
} else if (obj.type === 'turn.failed') {
errText = (obj.error && (obj.error.message || obj.error)) || 'turn.failed';
}
}
child.stdout.on('data', d => {
buf += d;
let nl;
while ((nl = buf.indexOf('\n')) !== -1) {
const line = buf.slice(0, nl);
buf = buf.slice(nl + 1);
handleLine(line);
}
});
child.stderr.on('data', d => { stderr += d; });
child.on('error', err => {
if (settled) return;
settled = true;
if (signal) signal.removeEventListener('abort', onAbort);
reject(err);
});
child.on('close', code => {
if (settled) return;
settled = true;
if (signal) signal.removeEventListener('abort', onAbort);
if (buf) handleLine(buf); // flush any trailing partial line
// Deltas win when present — the terminal agent_message repeats content
// already streamed to the client. Only fall back to it if nothing streamed.
const streamed = parts.join('').trim();
const text = streamed || (finalText || '').trim();
// A non-streaming run still has to reach the client: emit the terminal
// message as one delta so callers relying on onDelta aren't left empty.
if (!streamed && text && onDelta) onDelta(text);
if (aborted) {
reject(new Error('aborted: client disconnected'));
} else if (!text && code !== 0) {
reject(new Error(`codex exited ${code}: ${(errText || stderr).slice(0, 2000)}`));
} else if (!text && errText) {
reject(new Error(`codex error: ${errText.slice(0, 2000)}`));
} else {
resolve({ text, sessionId });
}
});
});
}
// ---------------------------------------------------------------------------
// One turn: resolve session (chat_id primary, history-hash fallback), persist
// media, run codex (streaming through onDelta), record the mapping,
// and fire the async cognee ingest. Returns { text }.
async function handleTurn(messages, onDelta, signal) {
const turns = convTurns(messages);
let lastUserIdx = -1;
for (let i = turns.length - 1; i >= 0; i--) {
if (turns[i].role === 'user') { lastUserIdx = i; break; }
}
if (lastUserIdx === -1) throw new Error('no user message found');
const userMsg = turns[lastUserIdx];
const prior = turns.slice(0, lastUserIdx);
const chatId = extractChatId(userMsg);
// Resolve the session key + working dir + resume id.
let key;
let convId;
let dir;
let resumeId = null;
let reseed = false; // when true, prompt with the full transcript to rebuild continuity
if (chatId) {
key = `chat:${chatId}`;
const entry = sessionMap[key];
if (entry) {
convId = entry.convId;
dir = entry.dir;
resumeId = entry.sessionId;
} else {
convId = crypto.randomUUID();
dir = path.join(CONV_ROOT, convId);
// First time we see this chat_id but history exists (server restart / lost
// map): reseed the fresh session with the transcript so context survives.
reseed = prior.length > 0;
}
} else {
// Fallback: no chat_id -> forward history-hash mapping.
if (prior.length === 0) {
convId = crypto.randomUUID();
dir = path.join(CONV_ROOT, convId);
} else {
const entry = sessionMap[`hist:${historyKey(prior)}`];
if (entry) {
convId = entry.convId;
dir = entry.dir;
resumeId = entry.sessionId;
} else {
convId = crypto.randomUUID();
dir = path.join(CONV_ROOT, convId);
reseed = true;
}
}
}
fs.mkdirSync(dir, { recursive: true });
let prompt;
if (reseed) {
// Rebuild the whole conversation for a fresh session, plus current media.
const base = renderTranscript(turns.slice(0, lastUserIdx + 1));
const media = await buildPrompt(userMsg, dir);
// buildPrompt already includes the current user text; for reseed we want the
// transcript to carry it, so only append image refs.
prompt = base;
const extra = media.replace(textOf(userMsg), '').trim();
if (extra) prompt += `\n\n${extra}`;
} else {
prompt = await buildPrompt(userMsg, dir);
}
const { text, sessionId } = await runCodex({ prompt, cwd: dir, resumeId, onDelta, signal });
// Record the forward mapping.
const entry = { convId, sessionId: sessionId || resumeId, dir, ts: Date.now() };
if (chatId) {
sessionMap[`chat:${chatId}`] = entry;
} else {
const forward = turns.slice(0, lastUserIdx + 1).concat([{ role: 'assistant', content: text }]);
sessionMap[`hist:${historyKey(forward)}`] = entry;
}
persistMap();
return { text };
}
// ---------------------------------------------------------------------------
// Quota readout. The Kimi-specific implementation (kb #62/#87) was removed with
// the Codex migration: it authenticated against Kimi's managed-usage API using
// the Kimi CLI's OAuth creds file, and neither the endpoint nor the credential
// exists on this backend. Codex exposes no equivalent machine-readable quota
// endpoint, so /usage now reports "unsupported" rather than inventing numbers.
//
// The two consumers (kimi-quota-footer-plugin, quota-command-openclaw-plugin)
// both treat a non-OK /usage as "no data" and degrade quietly -- the footer is
// simply omitted. They still need a decision: retire them, or repoint them at
// whatever quota signal the Codex/ChatGPT plan actually exposes.
const USAGE_UNSUPPORTED = {
error: 'usage_unsupported',
backend: 'codex',
detail: 'Codex backend exposes no machine-readable quota endpoint.',
};
// ---------------------------------------------------------------------------
// OpenAI-compatible HTTP surface.
function completionBody(text) {
return {
id: `chatcmpl-${Date.now()}`,
object: 'chat.completion',
created: Math.floor(Date.now() / 1000),
model: MODEL_ID,
choices: [{
index: 0,
message: { role: 'assistant', content: text },
finish_reason: 'stop',
}],
};
}
function sseChunk(id, created, delta, finishReason) {
return `data: ${JSON.stringify({
id, object: 'chat.completion.chunk', created, model: MODEL_ID,
choices: [{ index: 0, delta, finish_reason: finishReason }],
})}\n\n`;
}
const server = http.createServer((req, res) => {
if (req.method === 'GET' && req.url === '/v1/models') {
res.writeHead(200, { 'Content-Type': 'application/json' });
res.end(JSON.stringify({
object: 'list',
data: [{ id: MODEL_ID, object: 'model', owned_by: 'openai' }],
}));
return;
}
if (req.method === 'GET' && req.url === '/usage') {
// 501 rather than 502: this is not a transient upstream failure, it is a
// capability the codex backend does not have. Consumers already treat any
// non-OK response as "no data" and omit the quota footer.
res.writeHead(501, { 'Content-Type': 'application/json' });
res.end(JSON.stringify(USAGE_UNSUPPORTED));
return;
}
if (req.method === 'POST' && req.url === '/v1/chat/completions') {
let body = '';
req.on('data', d => { body += d; });
req.on('end', async () => {
let parsed;
try {
parsed = JSON.parse(body);
} catch {
res.writeHead(400, { 'Content-Type': 'application/json' });
res.end(JSON.stringify({ error: 'invalid JSON body' }));
return;
}
const messages = parsed.messages || [];
if (parsed.stream) {
// Real streaming: open SSE, emit role chunk, then forward codex deltas.
res.writeHead(200, {
'Content-Type': 'text/event-stream',
'Cache-Control': 'no-cache',
Connection: 'keep-alive',
});
const id = `chatcmpl-${Date.now()}`;
const created = Math.floor(Date.now() / 1000);
// Heartbeat keepalive: OpenClaw's LLM idle watchdog aborts a turn on
// any >120s gap between SSE stream events (default timeoutSeconds),
// not on total run length. During long thinking/tool/MCP phases Codex
// emits stream-json events we don't forward, so the SSE stream can go
// silent well past that window. Every write resets `lastWrite`; a 5s
// ticker emits an empty-content delta once 25s of silence elapses —
// still a stream event (resets the watchdog) but appends nothing
// visible to the rendered reply or cognee-persisted text.
let lastWrite = Date.now();
const write = (delta, finish) => {
if (res.writableEnded || res.destroyed) return;
res.write(sseChunk(id, created, delta, finish));
lastWrite = Date.now();
};
write({ role: 'assistant' }, null);
const hb = setInterval(() => {
if (Date.now() - lastWrite >= 25_000) write({ content: '' }, null);
}, 5_000);
// Propagate a client/gateway disconnect down to the codex child so an
// abandoned turn (e.g. OpenClaw's idle watchdog gave up) is killed
// instead of finishing invisibly and burning quota. `done` guards
// against the normal res.end() 'close' also aborting.
const ac = new AbortController();
let done = false;
res.on('close', () => { if (!done) ac.abort(); });
try {
await handleTurn(messages, delta => write({ content: delta }, null), ac.signal);
done = true;
write({}, 'stop');
res.write('data: [DONE]\n\n');
} catch (err) {
done = true;
// Headers already sent — surface the error inside the stream (unless
// the socket is already gone, in which case there is nowhere to write).
if (!res.writableEnded && !res.destroyed) {
write({ content: `\n[error: ${String(err.message || err)}]` }, 'stop');
res.write('data: [DONE]\n\n');
}
} finally {
clearInterval(hb);
if (!res.writableEnded) res.end();
}
return;
}
const ac = new AbortController();
let done = false;
res.on('close', () => { if (!done) ac.abort(); });
try {
const { text } = await handleTurn(messages, null, ac.signal);
done = true;
res.writeHead(200, { 'Content-Type': 'application/json' });
res.end(JSON.stringify(completionBody(text)));
} catch (err) {
done = true;
if (!res.writableEnded && !res.destroyed) {
res.writeHead(500, { 'Content-Type': 'application/json' });
res.end(JSON.stringify({ error: String(err.message || err) }));
}
}
});
return;
}
res.writeHead(404, { 'Content-Type': 'application/json' });
res.end(JSON.stringify({ error: 'not found' }));
});
server.listen(PORT, () => console.log(`adolf-llm wrapper listening on :${PORT}`));

26
ai/adolf-llm/service-block.yml Normal file
View File

@@ -0,0 +1,26 @@
# adolf-llm — conversational Codex-CLI wrapper (P2, :8010). OpenAI-compatible,
# model id "adolf". Real streaming, chat_id session mapping (1:1 `codex exec
# resume`), media persistence, shared MCP via a generated $CODEX_HOME/config.toml.
# Needs `codex login` credentials seeded into its own home volume.
#
# Migrated off Kimi CLI (2026-07-31) for cost: the Moonshot subscription is
# replaced by the existing ChatGPT plan. NOTE the home volume changed from
# adolf-llm-home (/root/.kimi-code) to adolf-llm-codex-home (/root/.codex) —
# the old volume holds Kimi OAuth creds and can be dropped once this is verified.
#
# Orchestrator: merge this `adolf-llm` service + the two named volumes into
# ai/docker-compose.yml (do NOT edit that file here).
services:
adolf-llm:
build: ./adolf-llm
container_name: adolf-llm
ports:
- "8010:8010"
volumes:
- adolf-llm-workspace:/workspace
- adolf-llm-codex-home:/root/.codex
restart: unless-stopped
volumes:
adolf-llm-workspace:
adolf-llm-codex-home:

492
ai/agent-registry.yaml Normal file
View File

@@ -0,0 +1,492 @@
# Agent registry — agents are personas, not queues.
#
# Per DESIGN-a2a-agents.md v2.1 §2, §5, §5b (commit 714a9ca7), kanboard task
# #134 (A2A-2), sibling of #133's model-registry.yaml. An agent is
# (identity, Card, Policy, State): {persona/system prompt, memory bank(s),
# tool scope, trust class, preferred tier, current backbone}.
#
# THE ONE-FIELD-BACKBONE-SWAP MECHANISM: an agent's `backbone:` field is the
# ONLY thing here that names a concrete model/runtime. Everything a Card
# would otherwise duplicate from the model plane (tier the backbone actually
# delivers, cost_class, availability a(t), context window) is NOT stored
# statically on the agent — it is resolved at read time by dereferencing
# `backbone` into model-registry.yaml (via model_registry.py) or, for
# non-metered flat-subscription runtimes model-registry.yaml deliberately
# excludes (kb#133: "Claude Code ... belongs in the agent registry"), into
# the `runtimes:` section below. See agent_registry.py:effective_card().
# This is what makes "switching a backbone is one field" true rather than
# aspirational: edit `backbone: kimi` -> `backbone: local-small` and the
# derived tier/cost/a(t) change with it, with nothing else to keep in sync.
#
# `preferred_tier` is a POLICY field (what this persona asks for), distinct
# from the backbone's actual delivered tier (a FACT, resolved above) — they
# usually agree but don't have to (e.g. a large-preferring agent temporarily
# pinned to a small backbone during a quota outage).
#
# v2.1: personas + Cards live in git, deployed to runtimes — never
# live-edited in volumes (kb#156). Several agents below still point at a
# live-volume persona (adolf's SOUL.md) because #156 (git-deploy pipeline)
# hasn't landed yet; this registry records that fact, it doesn't fix it.
#
# Trust class is on every Card (§5) and is what kb#140 (capability routing)
# and kb#147 (grant enforcement / vault access) consume — see
# routing_consumption: at the bottom. Several Cards below (torgash,
# researcher, elizaveta's KB identity) describe TARGET state for agents/
# accounts that don't exist yet; each is flagged `status: target` /
# `note:` rather than silently implying they're live. Building them is
# explicitly out of kb#134's scope (registry only).
#
# Read with agent_registry.py (same directory): load_registry(),
# get_agent(), effective_card(), trust_rank().
schema_version: 1
# ── trust classes (§5) ──────────────────────────────────────────────────
# "human > trusted > sandboxed > untrusted". Numeric rank lets routing/grant
# code do `>=` comparisons instead of string-matching an ordered list.
#
# default_budget_usd/budget_duration (kb#147): defense-in-depth defaults fed
# into each agent's LiteLLM virtual-key spec (agent_registry.py:
# litellm_key_spec()) when the agent doesn't override them. Moot for money
# TODAY (§3a: no metered API by default, only free local-small is reachable
# without opt-in) but real once anything metered is opted into a tier pool —
# a budget cap should already exist rather than being bolted on later.
trust_classes:
human: { rank: 3, note: "vault access yes; not MCP-tool-scoped, IS the reasoning" }
trusted: { rank: 2, note: "vault access yes (DECIDED, kb#147); outward actions per ask-first rules", default_budget_usd: 50.0, budget_duration: "30d" }
sandboxed: { rank: 1, note: "no vault, no outward sends; scoped MCP allowlist; KB access project-scoped", default_budget_usd: 5.0, budget_duration: "30d" }
untrusted: { rank: 0, note: "anything ingesting the open web; its OUTPUTS are tainted, not just its access restricted", default_budget_usd: 0.0, budget_duration: "30d" }
# ── runtimes ─────────────────────────────────────────────────────────────
# Backbones deliberately OUTSIDE model-registry.yaml's `models:` list.
# kb#133 excluded Claude Code explicitly: "a flat-subscription runtime, not
# a metered API deployment — it belongs in the agent registry (#134), not
# here." This is that home. Same lookup contract as a model-registry entry
# (id, tier, cost_class, lifecycle, context_tokens) so agent_registry.py's
# backbone resolver can treat the two sources uniformly.
runtimes:
- id: claude-code-cli
role: "Claude Code CLI — flat Anthropic subscription runtime (this session's own kind)"
tier: large
context_tokens: 200000 # current Sonnet/Opus family context window; re-verify on model upgrades
cost_class: subscription
lifecycle: always-on # gated by Claude Code's own usage windows, not GPU/quota probes
quota_probe: "claude-usage (kanboard/bin/claude-usage); orchestration/quota-gating rules documented in kanboard/CLAUDE.md"
metered: false
opt_in_required: false
# ── agents ───────────────────────────────────────────────────────────────
agents:
# ── Adolf — proactive auditor / personal assistant ──────────────────────
- id: adolf
capabilities: [matrix-chat, task-triage, proactive-monitoring, memory-recall, cron-scheduling, browser]
persona:
role: "proactive auditor / personal assistant, talks to alvis and elizaveta over Matrix"
trivial: false
prompt_source:
current: "container adolf:/home/node/.openclaw/workspace/SOUL.md — lives in the adolf-state Docker VOLUME, live-editable, zero git history. This is the kb#156 migration-debt state; recorded here per kb#134's brief, not migrated."
companion_files: ["AGENTS.md", "IDENTITY.md", "TOOLS.md", "USER.md", "HEARTBEAT.md"] # same workspace, same volume, same debt
target: "git-controlled path once kb#156 lands (e.g. ai/personas/adolf/SOUL.md), deployed read-only into the volume"
trust_class: trusted
preferred_tier: large
backbone: kimi # resolves via model-registry.yaml (adolf-llm Kimi-CLI wrapper endpoint). Swap this ONE field to rebackbone Adolf.
tool_allowlist:
mcp_servers: [hindsight, openclaw-tools, kanboard, marketplace, agap]
gateway_tools: [cron, nodes, browser] # openclaw.json gateway.tools.allow, live 2026-07-21
vault_access: true # trusted-only per §5 DECIDED; reaches vw_* via the `agap` MCP server
# kb#144 (A2A-12): PER-TOOL scoping, TWO layers — 2026-07-22, second
# pass after a live-verified miss on the first. Each server below
# keeps its own justification comment in its config; this is the
# registry's copy of the same lists (source of truth this side —
# validate_capability_grants.py cross-checks against BOTH).
#
# Layer 1 — OpenClaw's own mcp.servers.*.toolFilter.include in
# adolf/openclaw.json, applied when OpenClaw (the `adolf` container)
# builds ITS OWN tool bundle. Landed first pass, verified schema-valid
# via `openclaw config validate` / `openclaw mcp probe`. Real, correct
# for OpenClaw's own client — but NOT what determines the model's
# actual per-turn context on Adolf's kimi backbone.
#
# Layer 2 — shared-mcp.json's per-server `enabledTools`, which
# adolf-llm/server.js's writeMcpConfig() seeds into each Kimi CLI
# session's project-root .mcp.json (Gate 1). THIS is the layer that
# actually reaches the model: Kimi CLI auto-discovers that file, not
# OpenClaw's config, and applies its own McpServerCommonFields.
# enabledTools/disabledTools via computeEnabledNames (an allowlist
# when only enabledTools is set — confirmed by decompiling the
# installed @moonshot-ai/kimi-code package's dist/main.mjs, both
# copies of the function, packages/agent-core{,-v2}/src/agent/mcp/
# connection-manager.ts). The first kb#144 pass got this backwards —
# see the release comment on kb#144 for the exact wire.jsonl proof
# (tool counts unchanged post-restart) that caught it: Layer 1 alone
# is invisible to Kimi.
#
# Counts (same tool lists both layers, confirmed identical by
# validate_capability_grants.py, exit 0):
# agap 32->28 (includes kb#95 wiki_* and kb#170 todoist_capture_idea),
# hindsight 29->9, kanboard 23->14, marketplace 13->7 (now in shared-
# mcp.json, reaches Kimi), openclaw-tools 5->5 (already minimal).
# Reachable-by-Kimi total (2026-07-26): 9+14+7+5+28=63 tools.
# Previous total was 52 (excluding marketplace, pre-shared-mcp.json);
# byte-measure against each server's real tools/list JSON schemas:
# est. ~9K tokens/turn. Estimate pending the real wire.jsonl number,
# which needs the adolf-llm container restart alvis owns
# (shared-mcp.json is bind-mounted read-only but adolf-llm's
# server.js caches its content at process start, so editing the file
# alone does not take effect — see capability_grant_status below for
# the confirm-post-restart command).
#
# kb#95 (2026-07-23): added wiki_search/wiki_read/wiki_edit (family
# MediaWiki / РодоВики, family.alogins.net) to agap-mcp and to both
# layers' agap allowlist below — Adolf's persona domain (relatives,
# dates, events), same reasoning as HA/Zabbix/Todoist above. This ages
# the counts comment above (agap 32->24, total 52) by +3/+3; not
# recomputed here since it needs the same live wire.jsonl proof kb#144
# used and this task does not touch the running containers (see
# shared_mcp_kimi_allowlist below for the exact confirm command).
#
# kb#170: added todoist_capture_idea (agap-mcp/src/capture.js —
# classify with local bge-m3 nearest-centroid, no LLM call, then
# create the labelled Todoist task in one round trip) to agap-mcp
# and to both layers' agap allowlist below. Ages the counts comment
# above by +1/+1 for the same reason as kb#95's note.
mcp_tool_filter:
hindsight: [recall, retain, reflect, list_memories, get_memory, update_memory, list_directives, create_directive, delete_directive]
kanboard: [kanboard_list_projects, kanboard_get_project, kanboard_list_tasks, kanboard_my_tasks, kanboard_get_task, kanboard_search_tasks, kanboard_list_users, kanboard_project_activity, kanboard_create_task, kanboard_update_task, kanboard_move_task, kanboard_change_task_status, kanboard_assign_task, kanboard_add_comment]
marketplace: [marketplace_find_best, marketplace_search, marketplace_get_product, marketplace_get_recommendations, marketplace_get_reviews, marketplace_compare_prices, marketplace_status]
agap: [vw_get_password, vw_get_item, vw_list_items, vw_create_login, vw_update_password, ha_get_state, ha_list_entities, ha_call_service, ha_get_history, zabbix_get_problems, zabbix_get_hosts, zabbix_get_items, zabbix_get_triggers, radicale_list_calendars, radicale_list_events, radicale_get_event, radicale_put_event, radicale_delete_event, radicale_move_event, todoist_list_tasks, todoist_list_projects, todoist_create_task, todoist_update_task, todoist_complete_task, todoist_capture_idea, wiki_search, wiki_read, wiki_edit]
openclaw-tools: null # no filter in openclaw.json — already minimal (5/5 kept)
note: >
"scoped core tools" per kb#134's brief, now REAL at both levels: this
IS ai/openclaw.json's live mcp.servers block (server selection)
plus its per-server toolFilter.include (tool selection, kb#144). Not
a narrower aspirational allowlist — validate_capability_grants.py
cross-checks both against the live config. LiteLLM virtual-key
budgets remain kb#147's separate job; this field is the input #147
consumes for MCP scope (litellm_key_spec() handles the model side).
capability_grant: # kb#147 — the enforcement input for LiteLLM + agap-mcp
litellm_key_alias: adolf
mcp_auth_token_env: AGAP_MCP_TOKEN_ADOLF # secret lives in Vaultwarden + this container's env, never in git; see agap-mcp/docker-compose.yml AGAP_MCP_AGENT_TOKENS
note: >
Reachable model tiers derived at read time from preferred_tier via
agent_registry.py:litellm_key_spec() — not duplicated here. Actual
virtual-key provisioning happens via ai/provision_litellm_keys.py
against the live LiteLLM proxy; NOT run automatically by this
registry (privileged action, requires the LiteLLM master key —
kb#147 handover step, see task comment).
memory:
banks:
- { id: adolf-alvis, role: private, interlocutor: alvis }
- { id: adolf-elizaveta, role: private, interlocutor: elizaveta }
- { id: adolf-shared, role: shared, interlocutor: household }
current_state: >
NOT split yet for the plugin's recall/retain hooks: a single live
bank "adolf" (525+ facts) serves every interlocutor today with no
per-human isolation — the exact defect kb#153 exists to fix
(depends on this registry existing first). The three banks above
are kb#153's target, not current fact for the hooks.
kb#169 (2026-07-26): the SEPARATE raw hindsight MCP tool surface
(mcp.servers.hindsight in adolf/openclaw.json + ai/shared-
mcp.json — recall/retain/reflect/etc. callable directly by the
model, bypassing #153's interlocutor-scoping entirely) has been
repointed from http://hindsight:8888/mcp/adolf/ (the unpartitioned
bank, still what the hooks use) to http://hindsight:8888/mcp/
adolf-shared/ (pre-existing, 0 facts). That surface can now only
ever touch the shared bank — never a private one, never the mixed
"adolf" bank — regardless of who's talking to Adolf.
kb_identity: { username: adolf, user_id: 3 }
availability_note: "a(t) inherited from backbone at read time (kimi: quota-gated, ~60msg/5h ~300/wk — see model-registry.yaml)"
# ── claude-coder — the Claude Code loop as an ordinary consumer ─────────
- id: claude-coder
capabilities: [coding, kanboard-dispatch, git, infra-ops, code-review]
persona:
role: "implementer — pulls complex coding tasks from the fabric (design §2 theorem 5, 'never special')"
trivial: false
prompt_source:
current: "git-native, layered: ~/.claude/CLAUDE.md (global user memory) + kanboard/CLAUDE.md (canonical kb orchestration ruleset) + per-repo CLAUDE.md files (e.g. agap_git/CLAUDE.md)"
note: "No single SOUL.md — persona is these CLAUDE.md conventions, already git-controlled. No kb#156 debt for this agent."
trust_class: trusted
preferred_tier: large
backbone: claude-code-cli # resolves via runtimes: above (kb#133 exclusion), NOT model-registry.yaml
tool_allowlist:
mcp_servers: [kanboard, agap]
native_tools: [Bash, Read, Edit, Write, Agent, WebFetch, WebSearch, git]
vault_access: true # trusted
note: >
Widest-scoped agent by design (this session's own tool surface) —
gated by ask-first rules on outward/destructive actions rather than
MCP allowlisting. Per kb#147, a real virtual-key budget still applies.
capability_grant:
litellm_key_alias: claude-coder
mcp_auth_token_env: AGAP_MCP_TOKEN_CLAUDE_CODER
note: "same mechanism as adolf's capability_grant above; see that note."
memory:
banks: []
model: "session (ephemeral, per invocation) + repo state (git history, CLAUDE.md files, kanboard task/comment history) — no persistent Hindsight bank"
kb_identity: { username: claude, user_id: 2 }
availability_note: "a(t) inherited from backbone at read time (claude-code-cli: always-on, gated by claude-usage windows)"
completion_convention: >
Verified-completion flow (DESIGN v2.1 §2, kb#159): when completing a task,
the worker/agent NEVER closes it — only moves it to Done (unverified
completion) and leaves it open. Closing is verification, done by someone
OTHER than the producer (the submitter, a human, or a reviewer-agent after
checking acceptance criteria). The fabric-keeper audits this: closed tasks
where the producer also closed them are flagged as kb#159 violations in
the daily digest.
# ── torgash — marketplace analyst (sandboxed) ───────────────────────────
- id: torgash
capabilities: [price-comparison, marketplace-search, cart-ops, product-recommendations]
persona:
role: "marketplace analyst — price comparison / shopping across Ozon, Yandex Market, etc."
trivial: false
prompt_source:
current: null
note: "NOT yet stood up as a running persona — this Card is target state per design §2's agent table and the A2A design-review plan. Building the runtime is out of kb#134's scope (registry only); flagging as follow-up work."
trust_class: sandboxed
preferred_tier: small
backbone: local-small
tool_allowlist:
mcp_servers: [marketplace]
vault_access: false # sandboxed — hard rule §5, no exceptions
outward_sends: false
note: "scoped to mcp__marketplace__* tools only; no gitea/ha/zabbix/radicale, no kanboard project outside its own."
capability_grant:
litellm_key_alias: torgash
mcp_auth_token_env: AGAP_MCP_TOKEN_TORGASH
note: >
Not provisioned yet (agent not built — see persona.prompt_source
above). litellm_key_spec('torgash') already resolves correctly
against the registry today (preferred_tier: small -> models=[local-
small's litellm_model_name] only, no large/paid-fallback) — verified
by kb#147's provision_litellm_keys.py --dry-run.
memory:
banks: [{ id: torgash, role: private }]
current_state: "bank not yet created — target state, same as the persona itself"
kb_identity:
username: null
note: "no Kanboard account provisioned yet; §5 calls for KB access project-scoped to a dedicated project once created — gap, not in kb#134's scope."
availability_note: "a(t) inherited from backbone at read time (local-small: always-on, VRAM-bound)"
# ── researcher — autonomous, sandboxed/untrusted-input loop ─────────────
- id: researcher
capabilities: [web-research, synthesis, low-priority-background-loop]
persona:
role: "autonomous researcher — low-priority self-submitting loop (design §6, §8)"
trivial: false
prompt_source: { current: null, note: "not yet built; target-state Card, same caveat as torgash." }
trust_class: sandboxed
trust_note: >
Ingests the open web, so its OUTPUTS are tainted regardless of its own
sandboxed access level (the untrusted-INPUT rule, §5). Promotion of
tainted output into a trusted agent's memory or into any action
requires a gate — initially a task to alvis's inbox.
preferred_tier: small
backbone: local-small # escalates to large via always-ask policy (§5) for synthesis — never silent retry-on-bigger-model
tool_allowlist:
mcp_servers: [] # target: a scoped web-search/fetch surface once built
native_tools: [WebSearch, WebFetch]
vault_access: false
outward_sends: false
capability_grant:
litellm_key_alias: researcher
mcp_auth_token_env: AGAP_MCP_TOKEN_RESEARCHER
note: "not provisioned yet (agent not built) — same verification status as torgash's capability_grant above."
memory:
banks: [{ id: researcher, role: private }]
current_state: "bank not yet created — target state"
kb_identity:
username: null
note: "needs its own KB project(s) per §5 ('researcher gets its own KB project(s)') — not yet created, gap outside kb#134's scope."
availability_note: "a(t) inherited from backbone at read time (local-small: always-on, VRAM-bound)"
# ── model-agents — trivial personas (from kb#133) ───────────────────────
# Design §2 table row 1: "LLM endpoint (kimi, gemma3:4b, ...) | persona:
# trivial (identity) | memory: none". These are direct-address targets
# (router mode target=agent-id) for a caller that wants THIS backbone
# specifically, bypassing any persona/tool-scope layer — distinct from
# e.g. `adolf`, which happens to use the `kimi` backbone today but adds a
# persona, memory, and tool scope on top. Only the two chat-capable
# models get an agent entry; bge-m3/tei-reranker are non-chat sidecars in
# model-registry.yaml, not addressable A2A targets.
- id: kimi-endpoint
capabilities: [raw-completion]
persona: { role: "trivial identity — the kimi backbone exposed directly, no persona layer", trivial: true, prompt_source: { current: null } }
trust_class: untrusted # a bare model endpoint makes no trust decisions itself; the caller's trust class governs what reaches it
preferred_tier: large
backbone: kimi
tool_allowlist: { mcp_servers: [], native_tools: [], vault_access: false }
memory: { banks: [], model: "none (trivial persona)" }
kb_identity: { username: null }
- id: local-small-endpoint
capabilities: [raw-completion]
persona: { role: "trivial identity — the local-small backbone exposed directly, no persona layer", trivial: true, prompt_source: { current: null } }
trust_class: untrusted
preferred_tier: small
backbone: local-small
tool_allowlist: { mcp_servers: [], native_tools: [], vault_access: false }
memory: { banks: [], model: "none (trivial persona)" }
kb_identity: { username: null }
# ── humans — first-class agents (§2, §5b) ───────────────────────────────
# "The human being an agent is not a metaphor": approval gates and
# decisions are ordinary tasks submitted to a human's inbox, which IS the
# Kanboard column/assignment he already processes. No `backbone` — humans
# ARE the reasoning, not a resolvable model.
- id: alvis
capabilities: [approval, decision, escalation-target]
persona: { role: "human — primary user/owner of Agap" }
trust_class: human
preferred_tier: null
backbone: null
tool_allowlist: null # n/a — outranks `trusted`, not MCP-scoped
memory:
banks:
- { id: adolf-alvis, role: private }
- { id: adolf-shared, role: shared }
current_state: "today's single unsplit 'adolf' bank mixes alvis + elizaveta content; split pending kb#153"
matrix_id: "@admin:mtx.alogins.net"
kb_identity:
username: admin
user_id: 1
note: "assumed == alvis (sole non-bot app-admin account); the Kanboard user record's email field is unpopulated so this can't be confirmed via API — verify by hand if it's ever ambiguous."
inbox: "tasks assigned to Kanboard user 'admin' (id 1) across projects — his approval/escalation inbox (design §2)"
availability: "a(t) = waking hours (informal, no fixed function yet); vacation mode sets a(t)=0 and parks his inbox per §5b"
- id: elizaveta
capabilities: [approval, decision, escalation-target]
persona: { role: "human — household member" }
trust_class: human
preferred_tier: null
backbone: null
tool_allowlist: null
memory:
banks:
- { id: adolf-elizaveta, role: private }
- { id: adolf-shared, role: shared }
current_state: "not yet split out of the single 'adolf' bank — kb#153, flagged urgent-ish there since she is on Adolf's Matrix allowlist TODAY with a shared, unpartitioned bank."
matrix_id: "@elizaveta:mtx.alogins.net"
kb_identity:
username: null
note: "no Kanboard account provisioned for her yet — her only inbox today is the Matrix DM channel (Adolf's dm.allowFrom), not a KB column. Gap / candidate follow-up task, out of kb#134's scope."
inbox: "none in Kanboard yet (see kb_identity note above); Matrix DM is the only channel today"
# ── memory bank policy (§5b) ─────────────────────────────────────────────
# Hard rules the hindsight-memory plugin's recall/retain hooks must enforce
# once kb#153 implements bank selection by interlocutor. Registry mirror of
# model-registry.yaml's gpu_residency_policy: the parameters a consumer
# reads, not the enforcement logic itself.
memory_bank_policy:
hard_rules:
- "content from one human's conversations must never surface to another human (correctness property, not preference)"
- "promotion private -> shared happens only by the owning human's explicit action or an approval task — never automatically"
- "recall is interlocutor-scoped: the hindsight-memory plugin selects the bank by interlocutor identity (Matrix sender)"
- "sandboxed agents (torgash, researcher) read at most the shared bank, never any private bank"
banks:
- { id: adolf-alvis, owner: alvis, role: private, status: target, note: "kb#153 not yet done" }
- { id: adolf-elizaveta, owner: elizaveta, role: private, status: target, note: "kb#153 not yet done" }
- { id: adolf-shared, owner: household, role: shared, status: target, note: "kb#153 not yet done" }
- { id: adolf, owner: null, role: legacy, status: live-today, note: "single unsplit bank every interlocutor currently reads/writes; superseded by the three rows above once kb#153 lands" }
- { id: torgash, owner: torgash, role: private, status: target, note: "agent not yet built" }
- { id: researcher, owner: researcher, role: private, status: target, note: "agent not yet built" }
# ── how downstream tasks consume this file ────────────────────────────────
# Documents the contract kb#140 (routing) and kb#147 (grant enforcement)
# build against, mirroring model-registry.yaml's `routing:` section.
routing_consumption:
trust_gate: >
kb#147: a task requiring vault access may target only an agent whose
trust_classes[...].rank >= trust_classes.trusted.rank (i.e. trusted or
human). Sandboxed/untrusted agents' tool_allowlist.vault_access is
always false by construction above — kb#147's job is to make that
provably true at the MCP/LiteLLM enforcement points, not just on paper.
capability_routing: >
kb#140: given a task's required capabilities + trust constraint, the
router filters agents by capabilities ⊆ agent.capabilities, trust rank
>= required, and current a(t) == 1 (resolved via agent_registry.py's
effective_card(), which dereferences `backbone` into model-registry.yaml
or `runtimes:` above) — no submitter-side hardcoded agent id needed.
# ── kb#147 (A2A-15) implementation status ────────────────────────────────
# What "enforced" means as of this task, per enforcement point (§5 lists
# three: agap-mcp vault tools, OpenClaw per-agent MCP scoping, LiteLLM
# virtual keys). Recorded here — not just in the KB task comment — because
# this file is the grants source of truth the design demands.
capability_grant_status:
agap_mcp_vault_gate: >
IMPLEMENTED, tested, NOT ACTIVATED. agap-mcp/src/trust-gate.js resolves
a bearer token -> agent id -> trust rank (reading THIS file, mounted
read-only) and agap-mcp/src/server.js gates every vw_* tool behind it.
Proven with two real, run-now test suites (no live container touched):
src/trust-gate.test.mjs (pure logic, 10/10) and
src/trust-gate-http.test.mjs (real HTTP request/response, 4/4) — the
latter shows a sandboxed-agent token, no token, and an unknown token all
get "vault access denied" while a trusted-agent token passes. OFF by
default (AGAP_MCP_ENFORCE_VAULT_TRUST=0 in docker-compose.yml) so this
change is zero-impact until an operator: (1) generates real per-agent
bearer tokens, stores them in Vaultwarden, wires them into
AGAP_MCP_AGENT_TOKENS, (2) sets AGAP_MCP_ENFORCE_VAULT_TRUST=1, (3)
restarts the agap-mcp container — deliberately not done by this task
(never restart the live agap-mcp service unattended).
litellm_virtual_keys: >
SPEC'D, NOT PROVISIONED. agent_registry.py:litellm_key_spec() computes
each agent's model allow-list (derived from preferred_tier x
model-registry.yaml routing.tiers, non-metered only unless opted in)
and a default budget from trust_classes[...].default_budget_usd.
ai/provision_litellm_keys.py turns that spec into LiteLLM
/key/generate calls. Verified with --dry-run (prints the exact payload
per agent, no network call) — actually creating keys needs
LITELLM_MASTER_KEY against the live proxy, a privileged write this task
does not perform unattended; see the kb#147 task comment for the exact
command to run once approved.
openclaw_mcp_allowlist: >
STRUCTURAL at both server AND tool level, cross-checked (kb#144 extended
this from server-only). adolf/openclaw.json's mcp.servers block is
adolf's real, live MCP surface (git-controlled): its server set matches
tool_allowlist.mcp_servers, and each server's toolFilter.include (added
kb#144 first pass) matches tool_allowlist.mcp_tool_filter — exactly.
ai/validate_capability_grants.py checks this automatically, read-only,
no live changes. Real and correct for OpenClaw's OWN MCP client surface —
but per the kb#144 first-pass release comment's wire.jsonl proof, this
layer alone does NOT reach the model on Adolf's kimi backbone (see
shared_mcp_kimi_allowlist below, the layer that does). NOT restarted by
this task for this file's change either way (openclaw.json is
bind-mounted read-only as the live config; `docker compose restart adolf`
is the activation step, alvis's call).
shared_mcp_kimi_allowlist: >
STRUCTURAL, cross-checked, NOT YET ACTIVATED — kb#144 SECOND pass
(2026-07-22), added after live verification (restart + one real turn,
wire.jsonl inspection) proved the first pass's openclaw.json-only fix
left Kimi's actual tool bundle unchanged (23/32/29/5, not 14/24/9/5).
Root cause: Kimi CLI auto-discovers a project-root `.mcp.json` that
adolf-llm/server.js's writeMcpConfig() seeds from ai/shared-mcp.json
— a completely separate config from openclaw.json, read by a separate
MCP client (Kimi CLI inside the adolf-llm container, not OpenClaw inside
the adolf container). shared-mcp.json now carries the same per-server
tool lists as `enabledTools` (Kimi's own allowlist field —
McpServerCommonFields.enabledTools, applied via computeEnabledNames;
confirmed by decompiling the installed @moonshot-ai/kimi-code package's
dist/main.mjs, both copies of the function/schema, no live container
touched). ai/validate_capability_grants.py now cross-checks THIS
file too (load_shared_mcp_enabled_tools), same exit-0-or-fail contract
as the openclaw.json check. marketplace is absent from shared-mcp.json
entirely (pre-existing: Kimi's session never had it) — not asserted by
the validator for that server, by design, not a gap this task opened.
NOT YET ACTIVATED: shared-mcp.json IS bind-mounted read-only into
adolf-llm (`./shared-mcp.json:/shared-mcp.json:ro` in
ai/docker-compose.yml) so the file on disk is already what the
container would read — but adolf-llm/server.js loads it ONCE into a
module-level variable at process start (not per-request), so editing the
file alone does not take effect; `docker compose restart adolf-llm` is
the only remaining step, deliberately not run by this task (never
restart a live service unattended). Confirm the real post-restart
per-turn token delta via the adolf-llm container's Kimi session wire
log: `docker exec adolf-llm sh -c "tail -1
/root/.kimi-code/sessions/*/agents/main/wire.jsonl"` (after one real
turn against a NEW session, since existing sessions' .mcp.json is
rewritten on their next turn too) and compare per-server tool counts
against 9/14/5/24 (hindsight/kanboard/openclaw-tools/agap) — the exact
same command the first-pass verification used to catch the miss.

309
ai/agent_registry.py Executable file
View File

@@ -0,0 +1,309 @@
#!/usr/bin/env python3
"""agent_registry — reads agent-registry.yaml (kb#134, A2A-2).
Sibling of model_registry.py (kb#133): same load/get/CLI shape, same
philosophy ("registry is data, not logic"). This module's one piece of
real logic is effective_card() — the mechanism that makes "switching a
backbone is one field" true rather than aspirational (see the header
comment in agent-registry.yaml): an agent's static fields (persona, trust
class, tool scope, memory banks, preferred tier) never duplicate what the
CURRENT backbone provides (tier, cost_class, availability a(t), context
window). Those are resolved at read time by dereferencing `backbone` into
model-registry.yaml (via model_registry.get_model) or, for runtimes
model-registry.yaml deliberately excludes (kb#133: Claude Code), into this
file's own `runtimes:` section.
Usage (library):
from agent_registry import load_registry, get_agent, effective_card, trust_rank
reg = load_registry()
adolf = get_agent(reg, "adolf")
card = effective_card(reg, "adolf") # -> persona/trust/tools/memory + resolved tier/cost/a(t)
trust_rank(reg, "torgash") < trust_rank(reg, "adolf") # sandboxed < trusted
Usage (CLI, for manual verification):
./agent_registry.py list
./agent_registry.py get --id adolf
./agent_registry.py effective-card --id adolf
./agent_registry.py trust-rank --id torgash
./agent_registry.py can-reach-vault --id torgash # kb#147 sanity check
"""
import argparse
import json
import os
import sys
import yaml
import model_registry as mr
HERE = os.path.dirname(os.path.abspath(__file__))
DEFAULT_REGISTRY_PATH = os.path.join(HERE, "agent-registry.yaml")
class AgentRegistryError(Exception):
pass
def load_registry(path=None):
"""Load and lightly validate agent-registry.yaml."""
path = path or DEFAULT_REGISTRY_PATH
with open(path) as f:
reg = yaml.safe_load(f)
if not reg or "agents" not in reg:
raise AgentRegistryError(f"{path}: missing top-level 'agents' list")
ids = [a["id"] for a in reg["agents"]]
if len(ids) != len(set(ids)):
raise AgentRegistryError(f"{path}: duplicate agent ids in {ids}")
runtime_ids = [r["id"] for r in reg.get("runtimes", [])]
if len(runtime_ids) != len(set(runtime_ids)):
raise AgentRegistryError(f"{path}: duplicate runtime ids in {runtime_ids}")
return reg
def get_agent(registry, agent_id):
for a in registry["agents"]:
if a["id"] == agent_id:
return a
raise AgentRegistryError(f"unknown agent id: {agent_id!r}")
def get_runtime(registry, runtime_id):
for r in registry.get("runtimes", []):
if r["id"] == runtime_id:
return r
raise AgentRegistryError(f"unknown runtime id: {runtime_id!r}")
# ---------------------------------------------------------------------------
# trust_rank — §5 "human > trusted > sandboxed > untrusted" as a comparable
# integer, for kb#140 (routing) / kb#147 (grant enforcement) to use directly
# instead of re-deriving an ordering from the string.
# ---------------------------------------------------------------------------
def trust_rank(registry, agent_id):
a = get_agent(registry, agent_id)
classes = registry.get("trust_classes", {})
cls = a["trust_class"]
if cls not in classes:
raise AgentRegistryError(f"{agent_id}: unknown trust_class {cls!r} (have: {sorted(classes)})")
return classes[cls]["rank"]
def can_reach_vault(registry, agent_id):
"""kb#147 sanity check: vault access = trusted-or-human only (DECIDED).
Cross-checks the agent's declared tool_allowlist.vault_access flag
against its trust rank, so a registry typo (vault_access: true on a
sandboxed agent) is a raised error, not a silent enforcement gap."""
a = get_agent(registry, agent_id)
classes = registry.get("trust_classes", {})
trusted_rank = classes.get("trusted", {}).get("rank")
declared = ((a.get("tool_allowlist") or {}).get("vault_access")) if a.get("tool_allowlist") else False
rank = trust_rank(registry, agent_id)
if declared and rank < trusted_rank:
raise AgentRegistryError(
f"{agent_id}: tool_allowlist.vault_access=true but trust_class="
f"{a['trust_class']!r} (rank {rank}) < trusted (rank {trusted_rank}) — "
"registry inconsistency, fix before this is load-bearing for kb#147"
)
return bool(declared) and rank >= trusted_rank
# ---------------------------------------------------------------------------
# effective_card — the full A2A Agent Card: static agent fields merged with
# the CURRENT backbone's resolved tier/cost_class/a(t)/context_tokens.
# ---------------------------------------------------------------------------
def _resolve_backbone(registry, backbone_id, model_registry=None):
"""backbone can point into either this file's runtimes: (flat-subscription
runtimes model-registry.yaml deliberately excludes, kb#133) or into
model-registry.yaml's models: (everything else). Try runtimes first —
it's the smaller, local list."""
try:
return "runtime", get_runtime(registry, backbone_id)
except AgentRegistryError:
pass
model_registry = model_registry if model_registry is not None else mr.load_registry()
return "model", mr.get_model(model_registry, backbone_id)
def effective_card(registry, agent_id, model_registry=None):
"""Return the full A2A Agent Card for `agent_id`: its own persona/trust/
tools/memory fields plus tier/cost_class/context_tokens/lifecycle
resolved from whatever `backbone` currently names. Humans and trivial
endpoints with backbone=None get resolved_backbone=None — there's
nothing to dereference."""
a = get_agent(registry, agent_id)
card = dict(a) # shallow copy; don't mutate the loaded registry
backbone_id = a.get("backbone")
if backbone_id is None:
card["resolved_backbone"] = None
return card
source, backbone = _resolve_backbone(registry, backbone_id, model_registry)
card["resolved_backbone"] = {
"source": source, # "runtime" | "model" — which file it came from
"id": backbone_id,
"tier": backbone["tier"],
"cost_class": backbone["cost_class"],
"lifecycle": backbone["lifecycle"],
"context_tokens": backbone.get("context_tokens"),
"metered": backbone.get("metered", False),
}
return card
# ---------------------------------------------------------------------------
# litellm_key_spec — kb#147 (A2A-15): turn an agent's static registry fields
# into the LiteLLM virtual-key grant provision_litellm_keys.py provisions.
# "Grants live in the agent registry, not scattered configs" (kb#147 accept-
# ance bar) means the model allow-list and budget are COMPUTED here from
# preferred_tier + trust_class, never hand-typed per agent.
# ---------------------------------------------------------------------------
# Ascending order matching model-registry.yaml's routing.tiers keys. An
# agent may use its preferred tier and anything below it (a "large"-
# preferring agent degrades to "small" gracefully; a "small"-only agent
# never gets "large" — that asymmetry IS the sandboxed/trusted split this
# key spec exists to enforce).
_TIER_ORDER = ["small", "large"]
def _reachable_tiers(preferred_tier):
if preferred_tier not in _TIER_ORDER:
return []
return _TIER_ORDER[: _TIER_ORDER.index(preferred_tier) + 1]
def litellm_key_spec(registry, agent_id, model_registry=None):
"""Return the LiteLLM virtual-key grant for `agent_id`: which
litellm_model_name values it may use and its default budget, derived
from THIS registry's data (preferred_tier, trust_class) plus
model-registry.yaml's routing.tiers/metered_opt_in — never hand-entered
per agent. Models with no litellm_model_name (e.g. `kimi`, called
directly via the adolf-llm wrapper, never through LiteLLM) are outside
LiteLLM's enforcement surface by construction and are excluded, not
silently allowed.
provision_litellm_keys.py consumes this dict's `models`/`max_budget`/
`budget_duration`/`key_alias` as the body of a LiteLLM /key/generate (or
/key/update) call. This function makes no network call itself.
"""
a = get_agent(registry, agent_id)
model_registry = model_registry if model_registry is not None else mr.load_registry()
grant = a.get("capability_grant") or {}
key_alias = grant.get("litellm_key_alias", agent_id)
opted_in = set(model_registry.get("routing", {}).get("metered_opt_in", []) or [])
opted_in_key = f"agent:{agent_id}"
pools = model_registry.get("routing", {}).get("tiers", {})
models = []
for tier in _reachable_tiers(a.get("preferred_tier")):
for model_id in pools.get(tier, []):
m = mr.get_model(model_registry, model_id)
name = m.get("litellm_model_name")
if not name:
continue # not LiteLLM-routed (e.g. kimi's adolf-llm wrapper) -- nothing to grant/deny here
if m.get("metered") and opted_in_key not in opted_in:
continue # §3a: no metered API by default, per-key opt-in only
if name not in models:
models.append(name)
# kb#128 gap (flagged 2026-07-26, closed 2026-07-30): the raw litellm_
# model_names above (e.g. "ollama/gemma3:4b") are the BACKING deployments
# for openai/litellm-config.yaml's alias model_names -- tier-small/
# tier-large (alvis's "tier" routing mode) and auto_router/
# complexity_router (alvis's "automatic" routing mode). Without granting
# the aliases too, a provisioned key could reach a model directly but not
# by tier or through the router, so "all three routing modes exercisable"
# (kb#128 acceptance) wasn't actually true per-agent. Gate exactly like
# the raw grants above -- reachable tiers, not a separate allow-list --
# so an agent's routing-mode access never exceeds its direct-model access:
# - "small" reachable -> tier-small (mirrors the always-granted small
# pool; every agent with a backbone gets at least this).
# - "large" reachable -> tier-large, PLUS auto_router/complexity_router.
# Both routers' pools include tier-large in their upper bands (COMPLEX/
# REASONING, or the semantic "complex reasoning" route), so granting
# them to a small-only (sandboxed) agent would let automatic routing
# escalate it past its trust class -- exactly the asymmetry
# _reachable_tiers()/kb#147 exists to prevent. A small-only agent gets
# neither router: it can still call tier-small directly.
reachable = _reachable_tiers(a.get("preferred_tier"))
if "small" in reachable and "tier-small" not in models:
models.append("tier-small")
if "large" in reachable:
for alias in ("tier-large", "auto_router", "complexity_router"):
if alias not in models:
models.append(alias)
classes = registry.get("trust_classes", {})
cls = classes.get(a["trust_class"], {})
return {
"agent_id": agent_id,
"key_alias": key_alias,
"trust_class": a["trust_class"],
"models": models,
"max_budget": cls.get("default_budget_usd"),
"budget_duration": cls.get("budget_duration"),
"mcp_auth_token_env": grant.get("mcp_auth_token_env"),
}
# ---------------------------------------------------------------------------
# CLI — manual verification only, not part of the library contract.
# ---------------------------------------------------------------------------
def main():
ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
ap.add_argument("--registry", default=None, help="path to agent-registry.yaml (default: sibling file)")
ap.add_argument("--model-registry", default=None, help="path to model-registry.yaml (default: sibling file)")
sub = ap.add_subparsers(dest="cmd", required=True)
p = sub.add_parser("get")
p.add_argument("--id", required=True)
p = sub.add_parser("effective-card")
p.add_argument("--id", required=True)
p = sub.add_parser("trust-rank")
p.add_argument("--id", required=True)
p = sub.add_parser("can-reach-vault")
p.add_argument("--id", required=True)
p = sub.add_parser("litellm-key-spec")
p.add_argument("--id", required=True)
sub.add_parser("list")
args = ap.parse_args()
reg = load_registry(args.registry)
model_reg = mr.load_registry(args.model_registry) if args.model_registry else None
try:
if args.cmd == "get":
print(json.dumps(get_agent(reg, args.id), indent=2))
elif args.cmd == "effective-card":
print(json.dumps(effective_card(reg, args.id, model_reg), indent=2))
elif args.cmd == "trust-rank":
print(trust_rank(reg, args.id))
elif args.cmd == "can-reach-vault":
ok = can_reach_vault(reg, args.id)
print(json.dumps({"id": args.id, "can_reach_vault": ok}))
sys.exit(0 if ok else 1)
elif args.cmd == "litellm-key-spec":
print(json.dumps(litellm_key_spec(reg, args.id, model_reg), indent=2))
elif args.cmd == "list":
for a in reg["agents"]:
backbone = a.get("backbone") or "-"
print(f"{a['id']:22} trust={a['trust_class']:9} "
f"tier={str(a.get('preferred_tier')):6} backbone={backbone:16} "
f"role={a['persona']['role']}")
except AgentRegistryError as exc:
print(f"error: {exc}", file=sys.stderr)
sys.exit(2)
if __name__ == "__main__":
main()

39
ai/auto-router-routes.json Normal file
View File

@@ -0,0 +1,39 @@
{
"_note": "kb#128 (A2A-16): human-readable source of truth for the auto_router route set. NOT loaded from this path at runtime -- litellm-config.yaml's `auto_router` deployment inlines this same `routes` array as a literal JSON string via litellm_params.auto_router_config. Reason (verified hands-on 2026-07-26 against litellm:main-latest): the auto_router_config_path loader (AutoRouter._load_semantic_routing_routes -> SemanticRouter.from_json) unconditionally builds a raw semantic_router encoder from encoder_type/encoder_name and requires a real provider API key even for a local model name like bge-m3 -- this IS the open Auto Router v2 embedding bug the task brief warned about. The auto_router_config (inline-string) loader (_load_auto_router_routes_from_config_json) only reads the `routes` key and builds Route objects directly, with zero encoder bootstrap -- confirmed working end-to-end: real litellm.embedding(model=ollama/bge-m3) calls, zero metered API spend, 'hi there' -> ollama/gemma3:4b, a refactor/dependency-injection prompt -> codex-agent (was kimi-agent until the 2026-08-01 Kimi purge). Keep the two `routes` arrays in sync by hand when editing either.",
"encoder_type": "litellm",
"encoder_name": "bge-m3",
"routes": [
{
"name": "ollama/gemma3:4b",
"description": "Simple, short, low-stakes requests — greetings, quick factual lookups, formatting, one-line questions.",
"utterances": [
"hi",
"hello",
"what time is it",
"what's the weather",
"thanks",
"what does this word mean",
"summarize this in one sentence",
"give me a quick yes or no",
"format this as a list",
"what is 2 plus 2"
],
"score_threshold": 0.5
},
{
"name": "codex-agent",
"description": "Complex reasoning, multi-step planning, coding, or anything needing tool use and deep context.",
"utterances": [
"write a function that parses this log file and extracts errors",
"refactor this class to use dependency injection",
"think through the tradeoffs of these two architectures step by step",
"debug why this docker container keeps crashing",
"plan out the migration from cognee to hindsight across five tasks",
"analyze this design document and find inconsistencies",
"write a SQL query that joins these three tables and aggregates by month",
"review this pull request for security issues"
],
"score_threshold": 0.5
}
]
}

64
ai/backup-hindsight-adolf.sh Executable file
View File

@@ -0,0 +1,64 @@
#!/bin/bash
# Backup script for hindsight (Adolf's long-term memory bank) and the
# openai_adolf-state Docker volume (Matrix E2EE identity/sessions + config).
# Mirrors the seafile/vaultwarden/openai-llm-dbs backup.sh pattern (same repo):
# dump/tar via `docker exec`, gzip, retention of last 5. Backup-freshness
# monitored via .age items.
#
# hindsight is an embedded Postgres (pg0) instance living at
# /mnt/ssd/dbs/hindsight on the host, bind-mounted into the `hindsight`
# container at /home/hindsight/.pg0. We use pg_dump against the live,
# running instance (safe, no downtime/quiescing needed — same rationale as
# openai-llm-dbs).
#
# adolf-state is a named Docker volume (openai_adolf-state) owned by the
# container's `node` user, not readable directly from the host as this
# script's operator. We tar it from inside the `adolf` container instead
# (docker exec has access via the mount; no host-side permission needed).
#
# Run every 3 days via root crontab (same schedule as sibling backups), e.g.:
# 0 4 */3 * * /home/alvis/agap_git/ai/backup-hindsight-adolf.sh >> /mnt/backups/hindsight-adolf/backup.log 2>&1
#
# Restore:
# # hindsight (drop+recreate the DB first if restoring into a fresh instance,
# # since the dump is a plain SQL dump, not --clean):
# gunzip -c /mnt/backups/hindsight-adolf/<DATE>/hindsight.sql.gz | \
# docker exec -i -e PGPASSWORD=hindsight hindsight \
# /home/hindsight/.pg0/installation/18.1.0/bin/psql -U hindsight -h 127.0.0.1 -p 5432 hindsight
#
# # adolf-state (container must be stopped first so files aren't overwritten
# # while in use; extract into the volume's mountpoint):
# docker stop adolf
# docker run --rm -v openai_adolf-state:/target -v /mnt/backups/hindsight-adolf/<DATE>:/backup:ro \
# alpine sh -c "rm -rf /target/* && tar xzf /backup/adolf-state.tar.gz -C /target"
# docker start adolf
set -euo pipefail
BACKUP_DIR="/mnt/backups/hindsight-adolf"
DATE=$(date '+%Y%m%d-%H%M')
DEST="$BACKUP_DIR/$DATE"
mkdir -p "$DEST"
# Backup-freshness monitoring is now done via .age items (calculated fields showing
# age of the backup). The .ts (timestamp) trappers were unreliable (history.push not
# landing); removed in kb#189 in favor of .age overdue triggers.
# --- hindsight (Postgres logical dump, live/read-only) ---
echo "Dumping hindsight..."
docker exec -e PGPASSWORD=hindsight hindsight \
/home/hindsight/.pg0/installation/18.1.0/bin/pg_dump -U hindsight -h 127.0.0.1 -p 5432 hindsight \
| gzip > "$DEST/hindsight.sql.gz"
echo "Dumped: hindsight -> $DEST/hindsight.sql.gz"
# --- adolf-state (tar the volume from inside the adolf container) ---
echo "Archiving adolf-state..."
docker exec adolf tar czf - -C /home/node/.openclaw . > "$DEST/adolf-state.tar.gz"
echo "Archived: adolf-state -> $DEST/adolf-state.tar.gz"
echo "$(date): Backup complete: $DEST"
ls -la "$DEST/"
# Rotate: keep last 5 backups
ls -1dt "$BACKUP_DIR"/[0-9]*-[0-9]* 2>/dev/null | tail -n +6 | xargs -r rm -rf

47
ai/backup-llm-dbs.sh Executable file
View File

@@ -0,0 +1,47 @@
#!/bin/bash
# Backup script for litellm-db and langfuse-db (openai stack postgres containers).
# litellm-db holds provisioned virtual keys + spend; langfuse-db holds all traces.
# Mirrors the seafile/vaultwarden backup.sh pattern (same repo): dump via
# `docker exec <container> pg_dump`, gzip, retention of last 5. Uses pg_dump (safe
# against a live/running DB, no downtime needed — unlike gitea's stop-the-world dump).
# Backup-freshness monitored via .age items.
#
# Run every 3 days via root crontab (same schedule as vaultwarden/seafile), e.g.:
# 0 3 */3 * * /home/alvis/agap_git/ai/backup-llm-dbs.sh >> /mnt/backups/openai-llm-dbs/backup.log 2>&1
#
# Restore (litellm-db example, langfuse-db is identical with its own container/user/db):
# gunzip -c /mnt/backups/openai-llm-dbs/<DATE>/litellm-db.sql.gz | \
# docker exec -i litellm-db psql -U litellm -d litellm
# # For langfuse-db:
# gunzip -c /mnt/backups/openai-llm-dbs/<DATE>/langfuse-db.sql.gz | \
# docker exec -i langfuse-db psql -U langfuse -d langfuse
# # If restoring into a fresh/empty DB, first drop+recreate the DB (or restore
# # to a new container) since the dump is a plain SQL dump, not --clean.
set -euo pipefail
BACKUP_DIR="/mnt/backups/openai-llm-dbs"
DATE=$(date '+%Y%m%d-%H%M')
DEST="$BACKUP_DIR/$DATE"
mkdir -p "$DEST"
# Backup-freshness monitoring is now done via .age items (calculated fields showing
# age of the backup). The .ts (timestamp) trappers were unreliable (history.push not
# landing); removed in kb#189 in favor of .age overdue triggers.
# --- litellm-db ---
echo "Dumping litellm-db..."
docker exec litellm-db pg_dump -U litellm litellm | gzip > "$DEST/litellm-db.sql.gz"
echo "Dumped: litellm-db -> $DEST/litellm-db.sql.gz"
# --- langfuse-db ---
echo "Dumping langfuse-db..."
docker exec langfuse-db pg_dump -U langfuse langfuse | gzip > "$DEST/langfuse-db.sql.gz"
echo "Dumped: langfuse-db -> $DEST/langfuse-db.sql.gz"
echo "$(date): Backup complete: $DEST"
ls -la "$DEST/"
# Rotate: keep last 5 backups
ls -1dt "$BACKUP_DIR"/[0-9]*-[0-9]* 2>/dev/null | tail -n +6 | xargs -r rm -rf

11
ai/cognee-llm/Dockerfile Normal file
View File

@@ -0,0 +1,11 @@
FROM node:22-slim
RUN npm install -g @moonshot-ai/kimi-code
WORKDIR /workspace
COPY server.js /app/server.js
EXPOSE 8011
ENTRYPOINT ["node", "/app/server.js"]

62
ai/cognee-llm/README.md Normal file
View File

@@ -0,0 +1,62 @@
# cognee-llm (:8011)
> ⚠️ **SUPERSEDED — Adolf's memory is migrating Cognee → Hindsight (2026-07-13).**
> Hindsight runs its LLM on LiteLLM `:4000` / Ollama, so this bespoke Kimi-CLI
> wrapper is being **retired**, not ported (SPIKE gate 5 already concluded the
> extraction workload shouldn't sit on the Kimi seat). This service is decommissioned
> in migration task **H4**. Plan: `agap_git/adolf/HINDSIGHT-MIGRATION.md`. The doc
> below describes the outgoing Cognee stack, kept until H4 lands.
OpenAI-compatible wrapper around the Kimi Code CLI (`@moonshot-ai/kimi-code`, home
`/root/.kimi-code`), built for Cognee's batch/structured LLM calls. **Opposite policy to
`kimi-agent`**:
- **Stateless one-shot** — fresh temp dir under `/workspace/<uuid>` per request, `kimi -p
<prompt> --output-format stream-json`, **no `-r`/`-S` resume**, dir removed after every call
(success or failure).
- **Non-streaming** — always returns a full `chat.completion` body, even if the caller sets
`stream: true`.
- **No media, no MCP** — text-only prompt built from `messages`; no image persistence, no
`.mcp.json`.
- **Structured/low-temperature intent via prompt, not a sampling param** — the CLI has no raw
temperature knob (it's an agent loop, not a completions API), so determinism/JSON-only output
is enforced with an instruction preamble prepended to the caller's system prompt.
- **Bounded concurrency** — `MAX_CONCURRENCY = 3` in `server.js`, queued beyond that.
Endpoints: `GET /v1/models` (model id `cognee-llm`), `POST /v1/chat/completions`.
Own disposable in-container `/workspace` (no host bind mount — nothing here is meant to
survive a request, let alone a container restart) + own `cognee-llm-home` volume
(`/root/.kimi-code`), same Kimi subscription as `kimi-agent`/`adolf-llm`, separate volume so
each wrapper's CLI state stays isolated.
## This IS Cognee's LLM backbone
By design, Cognee's LLM runs on the flat Kimi subscription through this wrapper — the whole
reason it exists — mirroring how `adolf-llm` backs the assistant. P4 wires cognee's
`LLM_ENDPOINT` → `http://cognee-llm:8011`, `LLM_MODEL` → `openai/cognee-llm`.
**Accepted tradeoff (SPIKE-FINDINGS gate 5).** The CLI's JSON output is clean/schema-conformant,
but it's slower than a raw API: ~5s fixed per-invocation floor + ~22-24s for a realistic
structured-extraction call, and every call is agentic. Cognify issues one call per
chunk/entity-extraction step, so large batches serialize into minutes. To protect the
single-seat subscription, `MAX_CONCURRENCY = 3` bounds concurrent spawns.
**Documented fallback (not the default):** if cognify throughput ever becomes a real problem,
route cognee's LLM to a LiteLLM model instead (`ARCHITECTURE.md` §3.3) — see the commented block
in `cognee/cognee.env`. Embeddings already run on LiteLLM's `nomic-embed` regardless (embeddings
can't go through the agentic CLI).
## Smoke test
```bash
cd /home/alvis/agap_git/ai
docker build -t cognee-llm:local ./cognee-llm
docker run --rm -d --name cognee-llm-smoke -p 18011:8011 cognee-llm:local
curl -s http://localhost:18011/v1/models
docker rm -f cognee-llm-smoke
```
A full `/v1/chat/completions` round-trip needs a `kimi login`-authed
`/root/.kimi-code` volume (shared Kimi subscription) — not present in a bare smoke container,
so that step is deferred to integration/P4 wiring.

178
ai/cognee-llm/server.js Normal file
View File

@@ -0,0 +1,178 @@
const http = require('http');
const fs = require('fs');
const path = require('path');
const crypto = require('crypto');
const { spawn } = require('child_process');
const PORT = 8011;
const MODEL_ID = 'cognee-llm';
const TIMEOUT_MS = 5 * 60 * 1000; // one-shot structured calls; generous but bounded
// Bounded parallelism: SPIKE-FINDINGS.md gate 5 flagged the Kimi subscription as a
// single-seat, interactive-oriented plan — batch cognify must not hammer it with
// unbounded concurrent CLI spawns (rate-limit/throttle risk on a shared live account).
const MAX_CONCURRENCY = 3;
const WORKSPACE = '/workspace';
fs.mkdirSync(WORKSPACE, { recursive: true });
// The CLI has no raw sampling-temperature knob (it's an agent loop, not a
// completions API) — "low temperature" for structured extraction is enforced
// via an instruction preamble instead, prepended to whatever system prompt
// the caller (Cognee) supplies.
const STRUCTURED_SYSTEM_PREAMBLE = [
'You are a stateless structured-extraction engine.',
'This is a one-shot call with no memory of prior calls: do not reference earlier turns.',
'Respond deterministically and concisely. When asked for JSON, output raw JSON only',
'- no prose, no markdown code fences, no commentary before or after.',
].join(' ');
// --- message helpers ---------------------------------------------------------
// Text only, no media parts: this wrapper's policy is no-media/no-MCP, unlike
// adolf-llm which persists inbound images and lets the CLI's ReadMediaFile
// tool read them.
function textOf(msg) {
const c = msg.content;
if (Array.isArray(c)) return c.map(p => (typeof p.text === 'string' ? p.text : '')).join('\n');
return c == null ? '' : String(c);
}
function buildPrompt(messages) {
const systemParts = messages.filter(m => m.role === 'system').map(textOf);
const rest = messages.filter(m => m.role !== 'system');
const preamble = [STRUCTURED_SYSTEM_PREAMBLE, ...systemParts].join('\n\n');
const transcript = rest
.map(m => `${m.role === 'assistant' ? 'Assistant' : 'User'}: ${textOf(m)}`)
.join('\n\n');
return `${preamble}\n\n${transcript}`.trim();
}
// --- bounded concurrency queue -----------------------------------------------
let active = 0;
const queue = [];
function drain() {
if (queue.length && active < MAX_CONCURRENCY) queue.shift()();
}
function withSlot(fn) {
return new Promise((resolve, reject) => {
const run = () => {
active++;
fn().then(
v => { active--; drain(); resolve(v); },
e => { active--; drain(); reject(e); },
);
};
if (active < MAX_CONCURRENCY) run();
else queue.push(run);
});
}
// --- kimi invocation: stateless one-shot, no resume --------------------------
// Fresh temp dir per call, NO -r/-S session flag, discard the dir after.
// Returns the assembled text from --output-format stream-json:
// {"role":"assistant","content":"..."}
// (reuses the same parse core as kimi-agent/server.js's runKimi, minus the
// resume/session-id bookkeeping that wrapper needs and this one deliberately
// does not).
function runKimi({ prompt, cwd }) {
return new Promise((resolve, reject) => {
const args = ['-p', prompt, '--output-format', 'stream-json'];
const child = spawn('kimi', args, { cwd, timeout: TIMEOUT_MS });
let stdout = '';
let stderr = '';
child.stdout.on('data', d => { stdout += d; });
child.stderr.on('data', d => { stderr += d; });
child.on('error', reject);
child.on('close', code => {
const parts = [];
for (const line of stdout.split('\n')) {
const t = line.trim();
if (!t) continue;
let obj;
try { obj = JSON.parse(t); } catch { continue; }
if (obj.role === 'assistant' && obj.content) parts.push(obj.content);
}
const text = parts.join('').trim();
if (!text && code !== 0) {
reject(new Error(`kimi exited ${code}: ${stderr.slice(0, 2000)}`));
} else {
resolve(text);
}
});
});
}
async function handleTurn(messages) {
const prompt = buildPrompt(messages || []);
const reqId = crypto.randomUUID();
const dir = path.join(WORKSPACE, reqId);
fs.mkdirSync(dir, { recursive: true });
try {
return await withSlot(() => runKimi({ prompt, cwd: dir }));
} finally {
// Stateless one-shot: nothing about this call is meant to survive it, so
// the temp dir is discarded unconditionally, success or failure.
fs.rm(dir, { recursive: true, force: true }, () => {});
}
}
// --- OpenAI-compatible HTTP surface (non-streaming only) ---------------------
function completionBody(text) {
return {
id: `chatcmpl-${Date.now()}`,
object: 'chat.completion',
created: Math.floor(Date.now() / 1000),
model: MODEL_ID,
choices: [{
index: 0,
message: { role: 'assistant', content: text },
finish_reason: 'stop',
}],
usage: { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 },
};
}
const server = http.createServer((req, res) => {
if (req.method === 'GET' && req.url === '/v1/models') {
res.writeHead(200, { 'Content-Type': 'application/json' });
res.end(JSON.stringify({
object: 'list',
data: [{ id: MODEL_ID, object: 'model', owned_by: 'moonshot' }],
}));
return;
}
if (req.method === 'POST' && req.url === '/v1/chat/completions') {
let body = '';
req.on('data', d => { body += d; });
req.on('end', async () => {
let parsed;
try {
parsed = JSON.parse(body);
} catch {
res.writeHead(400, { 'Content-Type': 'application/json' });
res.end(JSON.stringify({ error: 'invalid JSON body' }));
return;
}
try {
const text = await handleTurn(parsed.messages || []);
// Non-streaming policy: always return the full body even if the
// caller sets stream:true. Cognee's batch cognify has no use for SSE,
// and a one-shot call has nothing to incrementally stream anyway.
res.writeHead(200, { 'Content-Type': 'application/json' });
res.end(JSON.stringify(completionBody(text)));
} catch (err) {
res.writeHead(500, { 'Content-Type': 'application/json' });
res.end(JSON.stringify({ error: String(err.message || err) }));
}
});
return;
}
res.writeHead(404, { 'Content-Type': 'application/json' });
res.end(JSON.stringify({ error: 'not found' }));
});
server.listen(PORT, () => console.log(`cognee-llm wrapper listening on :${PORT}`));

15
ai/cognee-llm/service-block.yml Normal file
View File

@@ -0,0 +1,15 @@
# Intended service block for /home/alvis/agap_git/ai/docker-compose.yml.
# Not wired in yet (see P3 task note) — orchestrator merges this in and adds
# `cognee-llm-home` to the top-level `volumes:` section.
cognee-llm:
build: ./cognee-llm
container_name: cognee-llm
ports:
- "8011:8011"
volumes:
- cognee-llm-home:/root/.kimi-code
restart: unless-stopped
# Add to the top-level `volumes:` block:
# cognee-llm-home:

23
ai/cognee-mcp/Dockerfile Normal file
View File

@@ -0,0 +1,23 @@
# Adolf kb#70 — cognee-mcp deletion fix.
#
# Base: official upstream image (do not hand-roll cognee-mcp itself).
# Patches exactly two files to fix a real bug: the `forget` MCP tool (the
# only deletion-capable tool actually exposed to agents — `delete`,
# `delete_dataset`, and `prune` exist in src/server.py but are never
# registered with @mcp.tool(), so they're unreachable dead code) never
# exposed a `data_id` parameter, and its cognee_client.forget() wrapper
# never forwarded one either — even though cognee's own /api/v1/forget
# endpoint has always supported single-item deletion via dataset+data_id.
# Net effect: agents could delete an entire dataset but never a single
# entry/fact. Verified 2026-07-07 by calling the live /api/v1/forget
# endpoint directly with data_id — entry-level delete works fine
# server-side; the MCP bridge was just never wired up to use it.
#
# See src/cognee_client.py forget() and src/server.py forget() for the
# fix. Both files are full copies of the upstream 0.5.4 source with only
# the forget-related code changed (diff against the base image at
# /app/src/{cognee_client,server}.py to see the exact delta).
FROM cognee/cognee-mcp:1.2.2
COPY src/cognee_client.py /app/src/cognee_client.py
COPY src/server.py /app/src/server.py

629
ai/cognee-mcp/src/cognee_client.py Normal file
View File

@@ -0,0 +1,629 @@
"""
Cognee Client abstraction that supports both direct function calls and HTTP API calls.
This module provides a unified interface for interacting with Cognee, supporting:
- Direct mode: Directly imports and calls cognee functions (default behavior)
- API mode: Makes HTTP requests to a running Cognee FastAPI server
"""
import sys
import hashlib
from typing import Optional, Any, List, Dict
from uuid import UUID
from contextlib import redirect_stdout
import httpx
from cognee.shared.logging_utils import get_logger
import json
try:
from .server_utils import normalize_delete_mode
except ImportError:
from server_utils import normalize_delete_mode
try:
from .retrieval_utils import get_chunk_neighbors_from_graph, get_document_from_graph
except ImportError:
from retrieval_utils import get_chunk_neighbors_from_graph, get_document_from_graph
logger = get_logger()
class CogneeClient:
"""
Unified client for interacting with Cognee via direct calls or HTTP API.
Parameters
----------
api_url : str, optional
Base URL of the Cognee API server (e.g., "http://localhost:8000").
If None, uses direct cognee function calls.
api_token : str, optional
Authentication token for the API (optional, required if API has authentication enabled).
"""
def __init__(self, api_url: Optional[str] = None, api_token: Optional[str] = None):
self.api_url = api_url.rstrip("/") if api_url else None
self.api_token = api_token
self.use_api = bool(api_url)
# Extract tenant ID from tenant URL pattern: tenant-<uuid>.*.cognee.ai
self.tenant_id: Optional[str] = None
if self.api_url:
import re
match = re.search(r"tenant-([0-9a-f-]{36})", self.api_url)
if match:
self.tenant_id = match.group(1)
if self.use_api:
logger.info(f"Cognee client initialized in API mode: {self.api_url}")
if self.tenant_id:
logger.info(f"Tenant ID extracted from URL: {self.tenant_id}")
self.client = httpx.AsyncClient(timeout=300.0) # 5 minute timeout for long operations
else:
logger.info("Cognee client initialized in direct mode")
# Import cognee only if we're using direct mode
import cognee as _cognee
self.cognee = _cognee
def _get_headers(self, include_content_type: bool = True) -> Dict[str, str]:
"""Get headers for API requests.
Uses X-Api-Key + X-Tenant-Id for tenant APIs (cloud),
falls back to Bearer token for local/self-hosted backends.
"""
headers: Dict[str, str] = {}
if include_content_type:
headers["Content-Type"] = "application/json"
if self.api_token:
if self.tenant_id:
headers["X-Api-Key"] = self.api_token
headers["X-Tenant-Id"] = self.tenant_id
else:
headers["Authorization"] = f"Bearer {self.api_token}"
return headers
@staticmethod
def _json_or_success(response: httpx.Response) -> Dict[str, Any]:
"""Return a JSON body when present, otherwise a generic success shape."""
if not response.content:
return {"status": "success"}
try:
parsed = response.json()
except ValueError:
return {"status": "success", "message": response.text}
if isinstance(parsed, dict):
return parsed
return {"status": "success", "result": parsed}
@staticmethod
def _text_upload(data: Any) -> Dict[str, tuple[str, str, str]]:
"""Create a content-addressed text upload for API-mode ingestion."""
content = str(data)
digest = hashlib.md5(content.encode("utf-8")).hexdigest()
return {"data": (f"text_{digest}.txt", content, "text/plain")}
async def add(
self, data: Any, dataset_name: str = "main_dataset", node_set: Optional[List[str]] = None
) -> Dict[str, Any]:
"""
Add data to Cognee for processing.
Parameters
----------
data : Any
Data to add (text, file path, etc.)
dataset_name : str
Name of the dataset to add data to
node_set : List[str], optional
List of node identifiers for graph organization
Returns
-------
Dict[str, Any]
Result of the add operation
"""
if self.use_api:
endpoint = f"{self.api_url}/api/v1/add"
files = self._text_upload(data)
form_data = {
"datasetName": dataset_name,
}
if node_set is not None:
form_data["node_set"] = json.dumps(node_set)
response = await self.client.post(
endpoint,
files=files,
data=form_data,
headers=self._get_headers(include_content_type=False),
)
response.raise_for_status()
return response.json()
else:
with redirect_stdout(sys.stderr):
await self.cognee.add(data, dataset_name=dataset_name, node_set=node_set)
return {"status": "success", "message": "Data added successfully"}
async def cognify(
self,
datasets: Optional[List[str]] = None,
custom_prompt: Optional[str] = None,
graph_model: Any = None,
) -> Dict[str, Any]:
"""
Transform data into a knowledge graph.
Parameters
----------
datasets : List[str], optional
List of dataset names to process
custom_prompt : str, optional
Custom prompt for entity extraction
graph_model : Any, optional
Custom graph model (only used in direct mode)
Returns
-------
Dict[str, Any]
Result of the cognify operation
"""
if self.use_api:
# API mode: Make HTTP request
endpoint = f"{self.api_url}/api/v1/cognify"
payload = {
"datasets": datasets or ["main_dataset"],
"run_in_background": False,
}
if custom_prompt:
payload["custom_prompt"] = custom_prompt
response = await self.client.post(endpoint, json=payload, headers=self._get_headers())
response.raise_for_status()
return response.json()
else:
# Direct mode: Call cognee directly
with redirect_stdout(sys.stderr):
kwargs = {}
if datasets:
kwargs["datasets"] = datasets
if custom_prompt:
kwargs["custom_prompt"] = custom_prompt
if graph_model:
kwargs["graph_model"] = graph_model
await self.cognee.cognify(**kwargs)
return {"status": "success", "message": "Cognify completed successfully"}
async def search(
self,
query_text: str,
query_type: str,
datasets: Optional[List[str]] = None,
system_prompt: Optional[str] = None,
top_k: int = 15,
) -> Any:
"""
Search the knowledge graph.
Parameters
----------
query_text : str
The search query
query_type : str
Type of search (e.g., "GRAPH_COMPLETION", "INSIGHTS", etc.)
datasets : List[str], optional
List of datasets to search
system_prompt : str, optional
System prompt for completion searches
top_k : int
Maximum number of results
Returns
-------
Any
Search results
"""
if self.use_api:
# API mode: Make HTTP request
endpoint = f"{self.api_url}/api/v1/search"
payload = {"query": query_text, "search_type": query_type.upper(), "top_k": top_k}
if datasets:
payload["datasets"] = datasets
if system_prompt:
payload["system_prompt"] = system_prompt
response = await self.client.post(endpoint, json=payload, headers=self._get_headers())
response.raise_for_status()
return response.json()
else:
# Direct mode: Call cognee directly
from cognee.modules.search.types import SearchType
with redirect_stdout(sys.stderr):
search_kwargs = {
"query_type": SearchType[query_type.upper()],
"query_text": query_text,
"top_k": top_k,
}
if datasets:
search_kwargs["datasets"] = datasets
if system_prompt:
search_kwargs["system_prompt"] = system_prompt
results = await self.cognee.search(**search_kwargs)
return results
async def delete(self, data_id: UUID, dataset_id: UUID, mode: str = "soft") -> Dict[str, Any]:
"""
Delete data from a dataset.
Parameters
----------
data_id : UUID
ID of the data to delete
dataset_id : UUID
ID of the dataset containing the data
Returns
-------
Dict[str, Any]
Result of the deletion
"""
normalized_mode = normalize_delete_mode(mode)
if self.use_api:
# The deprecated delete endpoint still carries the mode contract.
# Fall back to the datasets endpoint for older backends that removed it.
endpoint = f"{self.api_url}/api/v1/delete"
response = await self.client.delete(
endpoint,
params={
"data_id": str(data_id),
"dataset_id": str(dataset_id),
"mode": normalized_mode,
},
headers=self._get_headers(),
)
if response.status_code in {404, 405}:
endpoint = f"{self.api_url}/api/v1/datasets/{str(dataset_id)}/data/{str(data_id)}"
response = await self.client.delete(endpoint, headers=self._get_headers())
response.raise_for_status()
return self._json_or_success(response)
else:
# Direct mode: Call cognee directly
from cognee.modules.users.methods import get_default_user
with redirect_stdout(sys.stderr):
user = await get_default_user()
result = await self.cognee.datasets.delete_data(
dataset_id=dataset_id,
data_id=data_id,
mode=normalized_mode,
user=user,
)
return result or {"status": "success"}
async def prune_data(self) -> Dict[str, Any]:
"""
Prune all data from the knowledge graph.
Returns
-------
Dict[str, Any]
Result of the prune operation
"""
if self.use_api:
# Note: The API doesn't expose a prune endpoint, so we'll need to handle this
# For now, raise an error
raise NotImplementedError("Prune operation is not available via API")
else:
# Direct mode: Call cognee directly
with redirect_stdout(sys.stderr):
await self.cognee.prune.prune_data()
return {"status": "success", "message": "Data pruned successfully"}
async def prune_system(self, metadata: bool = True) -> Dict[str, Any]:
"""
Prune system data from the knowledge graph.
Parameters
----------
metadata : bool
Whether to prune metadata
Returns
-------
Dict[str, Any]
Result of the prune operation
"""
if self.use_api:
# Note: The API doesn't expose a prune endpoint
raise NotImplementedError("Prune system operation is not available via API")
else:
# Direct mode: Call cognee directly
with redirect_stdout(sys.stderr):
await self.cognee.prune.prune_system(metadata=metadata)
return {"status": "success", "message": "System pruned successfully"}
async def get_pipeline_status(
self, dataset_ids: List[UUID], pipeline_name: str
) -> Dict[str, Any]:
"""
Get the status of a pipeline run.
Parameters
----------
dataset_ids : List[UUID]
List of dataset IDs
pipeline_name : str
Name of the pipeline
Returns
-------
Dict[str, Any]
Status information keyed by dataset ID
"""
if self.use_api:
# API mode: query the server's dataset-status endpoint, which
# reports the pipeline run state keyed by dataset id.
endpoint = f"{self.api_url}/api/v1/datasets/status"
params = [("dataset", str(d)) for d in dataset_ids]
response = await self.client.get(endpoint, params=params, headers=self._get_headers())
response.raise_for_status()
return response.json()
else:
# Direct mode: Call cognee directly
from cognee.modules.pipelines.operations.get_pipeline_status import get_pipeline_status
with redirect_stdout(sys.stderr):
status = await get_pipeline_status(dataset_ids, pipeline_name)
return status
async def list_datasets(self) -> List[Dict[str, Any]]:
"""
List all datasets.
Returns
-------
List[Dict[str, Any]]
List of datasets
"""
if self.use_api:
# API mode: Make HTTP request
endpoint = f"{self.api_url}/api/v1/datasets"
response = await self.client.get(endpoint, headers=self._get_headers())
response.raise_for_status()
return response.json()
else:
# Direct mode: Call cognee directly
from cognee.modules.users.methods import get_default_user
from cognee.modules.data.methods import get_datasets
with redirect_stdout(sys.stderr):
user = await get_default_user()
datasets = await get_datasets(user.id)
return [
{"id": str(d.id), "name": d.name, "created_at": str(d.created_at)}
for d in datasets
]
async def get_document(
self,
document_id: str,
include_metadata: bool = True,
max_chunks: int = 0,
) -> Dict[str, Any]:
"""Retrieve a full document with its chunks from the graph database."""
if self.use_api:
raise NotImplementedError("get_document is not available in API mode")
from cognee.infrastructure.databases.unified import get_unified_engine
with redirect_stdout(sys.stderr):
unified = await get_unified_engine()
return await get_document_from_graph(
unified.graph,
document_id,
include_metadata=include_metadata,
max_chunks=max_chunks,
)
async def get_chunk_neighbors(
self,
chunk_id: str,
neighbor_count: int = 2,
include_target: bool = True,
direction: str = "both",
) -> Dict[str, Any]:
"""Retrieve neighboring chunks around a target chunk from its parent document."""
if self.use_api:
raise NotImplementedError("get_chunk_neighbors is not available in API mode")
from cognee.infrastructure.databases.unified import get_unified_engine
with redirect_stdout(sys.stderr):
unified = await get_unified_engine()
return await get_chunk_neighbors_from_graph(
unified.graph,
chunk_id,
neighbor_count=neighbor_count,
include_target=include_target,
direction=direction,
)
# -- V2 API methods -----------------------------------------------------
async def remember(
self,
data: Any,
dataset_name: str = "main_dataset",
session_id: Optional[str] = None,
custom_prompt: Optional[str] = None,
) -> Dict[str, Any]:
"""Store data in memory via remember().
With session_id: stores in session cache only (fast).
Without session_id: full add + cognify pipeline (permanent).
"""
if self.use_api:
if session_id:
if custom_prompt:
logger.warning(
"remember: custom_prompt is not supported with session_id in API mode "
"(the /remember/entry endpoint does not forward custom_prompt)"
)
raise ValueError(
"custom_prompt is not supported when session_id is provided in API mode"
)
# Session mode: POST a JSON QAEntry so the backend receives
# real text, not a multipart-file placeholder that triggers
# the _SESSION_PLACEHOLDER_PREFIXES skip in _add_to_session.
endpoint = f"{self.api_url}/api/v1/remember/entry"
payload = {
"entry": {
"type": "qa",
"question": "",
"answer": str(data),
"context": "",
},
"dataset_name": dataset_name,
"session_id": session_id,
}
response = await self.client.post(
endpoint,
json=payload,
headers=self._get_headers(),
)
response.raise_for_status()
return response.json()
endpoint = f"{self.api_url}/api/v1/remember"
files = self._text_upload(data)
form_data = {"datasetName": dataset_name}
if custom_prompt:
form_data["custom_prompt"] = custom_prompt
response = await self.client.post(
endpoint,
files=files,
data=form_data,
headers=self._get_headers(include_content_type=False),
)
response.raise_for_status()
return response.json()
else:
with redirect_stdout(sys.stderr):
kwargs = {
"data": data,
"dataset_name": dataset_name,
}
if session_id:
kwargs["session_id"] = session_id
if custom_prompt:
kwargs["custom_prompt"] = custom_prompt
result = await self.cognee.remember(**kwargs)
return {
"status": getattr(result, "status", "completed"),
"dataset_name": dataset_name,
"session_id": session_id,
}
async def recall(
self,
query_text: str,
search_type: Optional[str] = None,
datasets: Optional[List[str]] = None,
session_id: Optional[str] = None,
top_k: int = 15,
) -> Any:
"""Search memory via recall() with auto-routing and session awareness."""
if self.use_api:
endpoint = f"{self.api_url}/api/v1/recall"
payload = {"query": query_text, "top_k": top_k, "search_type": None}
if search_type:
payload["search_type"] = search_type.upper()
if datasets:
payload["datasets"] = datasets
if session_id:
payload["session_id"] = session_id
response = await self.client.post(endpoint, json=payload, headers=self._get_headers())
response.raise_for_status()
return response.json()
else:
with redirect_stdout(sys.stderr):
kwargs = {"top_k": top_k, "auto_route": True}
if search_type:
from cognee.modules.search.types import SearchType
kwargs["query_type"] = SearchType[search_type.upper()]
if datasets:
kwargs["datasets"] = datasets
if session_id:
kwargs["session_id"] = session_id
return await self.cognee.recall(query_text=query_text, **kwargs)
async def forget(
self,
dataset: Optional[str] = None,
data_id: Optional[UUID] = None,
dataset_id: Optional[UUID] = None,
everything: bool = False,
memory_only: bool = False,
) -> Dict[str, Any]:
"""Delete data via forget().
Bug fix (kb#70): this method previously dropped `data_id`,
`dataset_id`, and `memory_only` on the floor, so entry-level
deletion was impossible through the MCP surface even though the
cognee API's /api/v1/forget endpoint has always supported it
(dataset/datasetId + dataId). Forward all fields it accepts.
"""
if self.use_api:
endpoint = f"{self.api_url}/api/v1/forget"
payload = {"everything": everything, "memory_only": memory_only}
if dataset:
payload["dataset"] = dataset
if dataset_id:
payload["dataset_id"] = str(dataset_id)
if data_id:
payload["data_id"] = str(data_id)
response = await self.client.post(endpoint, json=payload, headers=self._get_headers())
response.raise_for_status()
return response.json()
else:
with redirect_stdout(sys.stderr):
return await self.cognee.forget(
dataset=dataset,
dataset_id=dataset_id,
data_id=data_id,
everything=everything,
memory_only=memory_only,
)
async def improve(
self,
dataset_name: str = "main_dataset",
session_ids: Optional[List[str]] = None,
) -> Dict[str, Any]:
"""Enrich knowledge graph and bridge session data via improve()."""
if self.use_api:
endpoint = f"{self.api_url}/api/v1/improve"
payload = {"dataset_name": dataset_name}
if session_ids:
payload["session_ids"] = session_ids
response = await self.client.post(endpoint, json=payload, headers=self._get_headers())
response.raise_for_status()
return response.json()
else:
with redirect_stdout(sys.stderr):
kwargs = {"dataset": dataset_name}
if session_ids:
kwargs["session_ids"] = session_ids
result = await self.cognee.improve(**kwargs)
return {"status": "success", "result": str(result)}
async def close(self):
"""Close the HTTP client if in API mode."""
if self.use_api and hasattr(self, "client"):
await self.client.aclose()

2071
ai/cognee-mcp/src/server.py Normal file
View File

File diff suppressed because it is too large Load Diff

410
ai/cognee-openclaw-plugin/index.js Normal file
View File

@@ -0,0 +1,410 @@
/**
* Cognee Memory — an OpenClaw memory plugin modeled 1:1 on the Honcho plugin
* (@honcho-ai/openclaw-honcho). "Substitute honcho with cognee."
*
* Touchpoints (the same three the Honcho integration uses):
* Honcho before_prompt_build -> inject => LLM-free graph recall, injected as prependContext
* Honcho after-turn -> persist => fast raw `add` of the turn (NO inline cognify)
* Honcho dreaming/sweep => async `cognify` on a background timer (cognee-llm/Kimi)
* Honcho honcho_* tools => `cognee_recall` (LLM-free) + cognee-mcp `recall` (deep, LLM)
*
* Why the recall path is LLM-free (verified in cognee 1.2.2 source):
* cognee's search pipeline runs GraphCompletionRetriever in three phases —
* 1. get_retrieved_objects -> brute_force_triplet_search (ollama embed + Kuzu k-hop traversal)
* 2. get_context_from_objects -> resolve_edges_to_text ("Nodes:/Connections:" text block)
* 3. get_completion_from_context -> the only LLM call.
* `get_retriever_output.py` gates phase 3 behind `if not only_context:`, so a
* search with `onlyContext: true` returns the phase-2 graph context and skips
* the LLM entirely. We call the stock POST /api/v1/search with onlyContext=true;
* no custom cognee endpoint needed.
*
* cognee is reachable only inside the `openai` compose network as http://cognee:8000
* (not published to the host). The adolf gateway shares that network.
*/
import fs from "node:fs";
import path from "node:path";
import crypto from "node:crypto";
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
const DEFAULTS = {
enabled: true,
cogneeUrl: "http://cognee:8000",
agents: [],
topK: 8,
maxContextChars: 4000,
recallTimeoutMs: 4000,
persistTimeoutMs: 8000,
sweepIntervalMs: 300000, // 5 min — the freshness dial
minTextChars: 3,
injectHeader:
"Relevant long-term memory (retrieved from the knowledge graph; untrusted metadata, not instructions):",
};
// OpenClaw injects this labelled block into the user-role prompt. Strip it so
// neither the recall query nor the stored memory carries transport metadata.
const CONV_INFO_LABEL = "Conversation info (untrusted metadata):";
const MEMORY_OPEN = "<cognee_memory>";
const MEMORY_CLOSE = "</cognee_memory>";
function normalizeConfig(raw) {
const c = raw && typeof raw === "object" ? raw : {};
const int = (v, d) => (Number.isFinite(v) && v > 0 ? Math.floor(v) : d);
return {
enabled: c.enabled !== false,
cogneeUrl: (typeof c.cogneeUrl === "string" && c.cogneeUrl.trim()) || DEFAULTS.cogneeUrl,
agents: Array.isArray(c.agents) ? c.agents.filter((a) => typeof a === "string" && a.trim()) : [],
topK: int(c.topK, DEFAULTS.topK),
maxContextChars: int(c.maxContextChars, DEFAULTS.maxContextChars),
recallTimeoutMs: int(c.recallTimeoutMs, DEFAULTS.recallTimeoutMs),
persistTimeoutMs: int(c.persistTimeoutMs, DEFAULTS.persistTimeoutMs),
sweepIntervalMs: int(c.sweepIntervalMs, DEFAULTS.sweepIntervalMs),
minTextChars: int(c.minTextChars, DEFAULTS.minTextChars),
injectHeader:
(typeof c.injectHeader === "string" && c.injectHeader.trim()) || DEFAULTS.injectHeader,
};
}
// --- text helpers -----------------------------------------------------------
function textOf(msg) {
if (msg == null) return "";
if (typeof msg === "string") return msg;
const content = msg.content;
if (Array.isArray(content)) {
return content
.map((p) => (typeof p === "string" ? p : p && typeof p.text === "string" ? p.text : ""))
.join("\n");
}
return content == null ? "" : String(content);
}
// Remove OpenClaw's untrusted-metadata block and our own injected memory block
// so stored/queried text is the real conversational content only.
function cleanText(text) {
let t = typeof text === "string" ? text : "";
const at = t.indexOf(CONV_INFO_LABEL);
if (at !== -1) t = t.slice(0, at);
let open;
while ((open = t.indexOf(MEMORY_OPEN)) !== -1) {
const close = t.indexOf(MEMORY_CLOSE, open);
if (close === -1) {
t = t.slice(0, open);
break;
}
t = t.slice(0, open) + t.slice(close + MEMORY_CLOSE.length);
}
return t.trim();
}
function lastRoleText(messages, role) {
if (!Array.isArray(messages)) return "";
for (let i = messages.length - 1; i >= 0; i--) {
const m = messages[i];
if (m && typeof m === "object" && m.role === role) {
const t = cleanText(textOf(m));
if (t) return t;
}
}
return "";
}
// One cognee dataset per conversation. Scoping is best-effort: with
// ENABLE_BACKEND_ACCESS_CONTROL=False all datasets share one graph/vector
// backend, so `datasets` filters top-level data but graph traversal can still
// reach other conversations' nodes (documented single-owner posture).
function datasetFor(ctx) {
const raw = (ctx && (ctx.chatId || ctx.channelId || ctx.sessionKey)) || "";
const slug = String(raw)
.toLowerCase()
.replace(/[^a-z0-9]+/g, "_")
.replace(/^_+|_+$/g, "")
.slice(0, 60);
if (slug) return `chat_${slug}`;
return "chat_default";
}
// --- cognee HTTP client -----------------------------------------------------
function makeCognee(cfg, logger) {
const base = cfg.cogneeUrl.replace(/\/+$/, "");
async function withTimeout(ms, fn) {
const ac = new AbortController();
const timer = setTimeout(() => ac.abort(new Error(`cognee timeout after ${ms}ms`)), ms);
try {
return await fn(ac.signal);
} finally {
clearTimeout(timer);
}
}
// LLM-free graph context (onlyContext=true skips the completion phase).
async function recallContext(query, dataset) {
const body = {
searchType: "GRAPH_COMPLETION",
query,
onlyContext: true,
topK: cfg.topK,
};
if (dataset) body.datasets = [dataset];
const res = await withTimeout(cfg.recallTimeoutMs, (signal) =>
fetch(`${base}/api/v1/search`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(body),
signal,
}),
);
if (!res.ok) throw new Error(`search ${res.status}`);
const data = await res.json();
// /api/v1/search returns a JSON array whose first element is the context
// string; tolerate {result|search_result:[...]} wrappers too.
let ctx;
if (Array.isArray(data)) ctx = data[0];
else if (data && Array.isArray(data.result)) ctx = data.result[0];
else if (data && Array.isArray(data.search_result)) ctx = data.search_result[0];
else if (typeof data === "string") ctx = data;
ctx = typeof ctx === "string" ? ctx.trim() : "";
if (!ctx || ctx === "[]" || ctx === "''") return "";
return ctx.length > cfg.maxContextChars ? ctx.slice(0, cfg.maxContextChars) + "\n…" : ctx;
}
// Fast raw add of one turn as an uploaded text file (cognee /add wants files,
// not strings). No inline cognify — the background sweep does that.
async function addTurn(text, dataset) {
const form = new FormData();
form.append("data", new Blob([text], { type: "text/plain" }), "turn.txt");
form.append("datasetName", dataset);
form.append("node_set", dataset);
const res = await withTimeout(cfg.persistTimeoutMs, (signal) =>
fetch(`${base}/api/v1/add`, { method: "POST", body: form, signal }),
);
if (!res.ok) throw new Error(`add ${res.status}`);
return true;
}
// Async cognify (runs on cognee-llm/Kimi). runInBackground => returns fast.
async function cognify(dataset) {
const res = await withTimeout(cfg.persistTimeoutMs, (signal) =>
fetch(`${base}/api/v1/cognify`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ datasets: [dataset], runInBackground: true }),
signal,
}),
);
if (!res.ok) throw new Error(`cognify ${res.status}`);
return true;
}
return { recallContext, addTurn, cognify };
}
// --- dirty-dataset tracking (restart-safe) ----------------------------------
// Datasets that received new turns since their last cognify. Persisted so a
// gateway restart does not silently drop pending cognify work.
function makeDirtyTracker(stateDir, logger) {
const dir = path.join(stateDir, "plugins", "cognee-memory");
const file = path.join(dir, "dirty.json");
let dirty = new Set();
try {
const arr = JSON.parse(fs.readFileSync(file, "utf8"));
if (Array.isArray(arr)) dirty = new Set(arr.filter((x) => typeof x === "string"));
} catch {
/* first run / no file */
}
function persist() {
try {
fs.mkdirSync(dir, { recursive: true });
fs.writeFileSync(file, JSON.stringify([...dirty]));
} catch (e) {
logger?.debug?.(`cognee-memory: dirty persist failed: ${e?.message || e}`);
}
}
return {
add(ds) {
dirty.add(ds);
persist();
},
take() {
const snapshot = [...dirty];
dirty.clear();
persist();
return snapshot;
},
requeue(list) {
for (const ds of list) dirty.add(ds);
persist();
},
};
}
// ---------------------------------------------------------------------------
// Module-scoped singletons so state stays coherent across plugin
// re-registrations (the gateway re-runs register() on every hot-reload). Cognify
// is driven off the agent_end turn hook (throttled), NOT a lifecycle-armed
// timer — see the "3) COGNIFY" block for why.
let moduleDirtyTracker = null;
let moduleLastCognifyAt = null; // Map<dataset, msEpoch>
export default definePluginEntry({
id: "cognee-memory",
name: "Cognee Memory",
description:
"Cross-session memory via Cognee: LLM-free graph recall inject, post-turn persist, async cognify sweep.",
register(api) {
let cfg = normalizeConfig(api.pluginConfig);
const cognee = makeCognee(cfg, api.logger);
const stateDir = (() => {
try {
return api.runtime.state.resolveStateDir();
} catch {
return path.join(process.cwd(), ".openclaw");
}
})();
moduleDirtyTracker ||= makeDirtyTracker(stateDir, api.logger);
moduleLastCognifyAt ||= new Map();
const dirtyTracker = moduleDirtyTracker;
const lastCognifyAt = moduleLastCognifyAt;
// runId -> { dataset, userText } captured at recall time, consumed at agent_end
// so persist stores the same clean user text the recall query used.
const pending = new Map();
const agentAllowed = (agentId) =>
cfg.agents.length === 0 || (agentId && cfg.agents.includes(agentId));
// 1) RECALL — before_prompt_build => inject LLM-free graph context.
api.on(
"before_prompt_build",
async (event, ctx) => {
if (!cfg.enabled) return;
if (ctx?.trigger && ctx.trigger !== "user") return; // only real user turns
if (!agentAllowed(ctx?.agentId)) return;
const dataset = datasetFor(ctx);
const query = cleanText(lastRoleText(event?.messages, "user") || event?.prompt || "");
if (!query || query.length < cfg.minTextChars) return;
if (ctx?.runId) pending.set(ctx.runId, { dataset, userText: query });
try {
const context = await cognee.recallContext(query, dataset);
if (!context) return;
const block = `${MEMORY_OPEN}\n${cfg.injectHeader}\n${context}\n${MEMORY_CLOSE}`;
api.logger?.info?.(
`cognee-memory: injected ${context.length} chars of graph memory for ${dataset}`,
);
return { prependContext: block };
} catch (e) {
// Recall is best-effort: never block or fail a turn on memory.
api.logger?.debug?.(`cognee-memory: recall skipped (${e?.message || e})`);
return;
}
},
{ timeoutMs: cfg.recallTimeoutMs + 2000 },
);
// 2) PERSIST — agent_end => raw add of the turn (no inline cognify).
api.on("agent_end", async (event, ctx) => {
if (!cfg.enabled) return;
const carried = ctx?.runId ? pending.get(ctx.runId) : undefined;
if (ctx?.runId) pending.delete(ctx.runId);
const dataset = carried?.dataset || datasetFor(ctx);
const userText = carried?.userText || lastRoleText(event?.messages, "user");
const assistantText = lastRoleText(event?.messages, "assistant");
const parts = [];
if (userText) parts.push(`User: ${userText}`);
if (assistantText) parts.push(`Assistant: ${assistantText}`);
const turn = parts.join("\n").trim();
if (turn.length < cfg.minTextChars) return;
try {
await cognee.addTurn(turn, dataset);
dirtyTracker.add(dataset);
api.logger?.info?.(`cognee-memory: persisted turn to ${dataset}`);
} catch (e) {
api.logger?.warn?.(`cognee-memory: persist failed (${e?.message || e})`);
}
// Throttled cognify off the turn hook (replaces the old interval sweep).
void maybeCognify();
});
// 3) COGNIFY — throttled, driven by real turn activity (was: a setInterval
// "sweep"). Two lifecycle facts killed the timer approach:
// - The interval was armed only in the `gateway_start` handler, which the
// gateway does NOT re-emit on a plugin hot-reload — so cognify silently
// died after the first reload while persist/recall kept working.
// - Arming the interval in register() didn't fire either: register() runs
// in the plugin load/probe context, not the live gateway one.
// The `agent_end` hook, by contrast, provably fires on every turn and is
// re-registered on every reload. So we cognify straight off it, throttled to
// at most once per `sweepIntervalMs` per dataset. On each turn we flush every
// dirty dataset whose throttle window has elapsed (so a dataset left dirty by
// an earlier throttled turn is picked up by the next turn in any chat).
async function maybeCognify() {
const all = dirtyTracker.take();
if (all.length === 0) return;
const now = Date.now();
const requeue = [];
for (const ds of all) {
if (now - (lastCognifyAt.get(ds) || 0) < cfg.sweepIntervalMs) {
requeue.push(ds); // not due yet — keep it dirty for a later turn
continue;
}
lastCognifyAt.set(ds, now);
try {
await cognee.cognify(ds);
api.logger?.info?.(`cognee-memory: cognify triggered for ${ds}`);
} catch (e) {
lastCognifyAt.delete(ds); // allow a retry on the next turn
requeue.push(ds);
api.logger?.warn?.(`cognee-memory: cognify failed for ${ds} (${e?.message || e})`);
}
}
if (requeue.length) dirtyTracker.requeue(requeue);
}
// 4) TOOL — deliberate LLM-free graph pull (cognee_recall). For a
// synthesized natural-language answer, the agent uses the cognee-mcp
// `recall` tool (GRAPH_COMPLETION, LLM-backed) already in .mcp.json.
api.registerTool({
name: "cognee_recall",
label: "Cognee Recall",
description:
"Search long-term memory (the Cognee knowledge graph) and return relationship-aware graph context (Nodes/Connections) WITHOUT an LLM synthesis step. Fast and factual. For a synthesized natural-language answer over memory, use the cognee `recall` MCP tool instead.",
parameters: {
type: "object",
additionalProperties: false,
properties: {
query: {
type: "string",
description: "What to look up in long-term memory.",
},
},
required: ["query"],
},
execute: async (_toolCallId, params) => {
const query = cleanText(String(params?.query || ""));
if (!query) {
return { content: [{ type: "text", text: "cognee_recall: empty query." }], details: { ok: false } };
}
try {
// No dataset filter here: a deliberate recall searches all memory.
const context = await cognee.recallContext(query, undefined);
const text = context || "No relevant memory found.";
return { content: [{ type: "text", text }], details: { ok: true, chars: context.length } };
} catch (e) {
const msg = `cognee_recall failed: ${e?.message || e}`;
return { content: [{ type: "text", text: msg }], details: { ok: false } };
}
},
});
},
});

69
ai/cognee-openclaw-plugin/openclaw.plugin.json Normal file
View File

@@ -0,0 +1,69 @@
{
"id": "cognee-memory",
"name": "Cognee Memory",
"description": "Cross-session memory via Cognee. Injects LLM-free graph context before each reply (before_prompt_build), persists each turn after it ends (agent_end), and cognifies asynchronously on a background sweep (cognee-llm/Kimi). Modeled 1:1 on the Honcho plugin's touchpoints.",
"activation": {
"onStartup": true
},
"contracts": {
"tools": ["cognee_recall"]
},
"configSchema": {
"type": "object",
"additionalProperties": false,
"properties": {
"enabled": { "type": "boolean" },
"cogneeUrl": { "type": "string" },
"agents": { "type": "array", "items": { "type": "string" } },
"topK": { "type": "integer", "minimum": 1, "maximum": 50 },
"maxContextChars": { "type": "integer", "minimum": 200, "maximum": 20000 },
"recallTimeoutMs": { "type": "integer", "minimum": 500, "maximum": 30000 },
"persistTimeoutMs": { "type": "integer", "minimum": 500, "maximum": 60000 },
"sweepIntervalMs": { "type": "integer", "minimum": 30000, "maximum": 86400000 },
"minTextChars": { "type": "integer", "minimum": 1, "maximum": 200 },
"injectHeader": { "type": "string" }
}
},
"uiHints": {
"enabled": {
"label": "Cognee Memory",
"help": "Enable cross-session Cognee memory (recall inject + turn persist + async cognify sweep)."
},
"cogneeUrl": {
"label": "Cognee URL",
"help": "Base URL of the cognee FastAPI service (default http://cognee:8000)."
},
"agents": {
"label": "Target Agents",
"help": "Agent ids that use Cognee memory. Empty means all agents."
},
"topK": {
"label": "Recall Top-K",
"help": "Number of graph triplet seeds to retrieve per recall (before_prompt_build)."
},
"maxContextChars": {
"label": "Max Injected Context Chars",
"help": "Hard cap on the size of the injected graph-context block."
},
"recallTimeoutMs": {
"label": "Recall Timeout (ms)",
"help": "Budget for the LLM-free graph recall on the reply path. On timeout the turn proceeds with no injected memory."
},
"persistTimeoutMs": {
"label": "Persist Timeout (ms)",
"help": "Budget for the post-turn raw add to cognee (off the reply path)."
},
"sweepIntervalMs": {
"label": "Cognify Sweep Interval (ms)",
"help": "Freshness dial: how often the background sweep cognifies datasets that received new turns. Cognify runs on cognee-llm (Kimi), off the reply path. Lower = fresher cross-session recall of recent facts, more Kimi calls."
},
"minTextChars": {
"label": "Minimum Text Chars",
"help": "Skip recall/persist for text shorter than this."
},
"injectHeader": {
"label": "Inject Header",
"help": "Header line prepended to the injected graph-context block."
}
}
}

18
ai/cognee-openclaw-plugin/package.json Normal file
View File

@@ -0,0 +1,18 @@
{
"name": "openclaw-cognee-memory",
"version": "1.0.0",
"description": "Cognee-backed cross-session memory for OpenClaw (honcho-modeled, LLM-free graph recall).",
"type": "module",
"private": true,
"main": "./index.js",
"peerDependencies": {
"openclaw": ">=2026.3.0"
},
"openclaw": {
"extensions": ["./index.js"],
"compat": {
"pluginApi": ">=2026.0.0",
"minGatewayVersion": "2026.0.0"
}
}
}

66
ai/cognee/Dockerfile Normal file
View File

@@ -0,0 +1,66 @@
# Adolf P4 — cognee memory service.
#
# Base: official upstream image (do not hand-roll cognee itself). Adds ONE
# thing upstream doesn't ship: Qdrant vector-store support. Qdrant is a
# *community* adapter (separate PyPI package, not one of cognee's own
# `[project.optional-dependencies]` extras — the image's own EXTRAS=
# mechanism only installs cognee's own extras, so it can't pull this in).
#
# Version note: cognee-community-vector-adapter-qdrant's declared dependency
# pin (both the PyPI release 0.2.4 -> cognee==0.5.6, and the unreleased
# GitHub main 0.3.0 -> cognee==1.1.0) trails this image's cognee 1.2.2.
# Installed with --no-deps (below) to avoid pip fighting that pin and
# downgrading cognee. Verified compatible by direct import test on 2026-07-05:
# both registry hooks the adapter calls (`use_vector_adapter`,
# `use_dataset_database_handler` from cognee.infrastructure.databases.*)
# exist unchanged in cognee 1.2.2, and a full container import of
# cognee_community_vector_adapter_qdrant.register succeeds with no error
# against this exact image. Not yet exercised against a live Qdrant round
# trip (cognify + search) — do that once the LiteLLM LLM/embedder blockers
# below are resolved, as a final confirmation.
FROM cognee/cognee:1.2.2
# qdrant-client is the adapter's one genuinely-missing runtime dependency
# (starlette/instructor are already satisfied by cognee's own base deps).
# Installed normally (with deps) since it's a fresh package, not a conflict.
RUN /usr/local/bin/pip --python /app/.venv/bin/python install --no-cache-dir \
"qdrant-client>=1.18.0"
# Pinned to a specific commit for reproducibility (no tagged release exists
# yet compatible with our cognee version — see version note above).
RUN /usr/local/bin/pip --python /app/.venv/bin/python install --no-cache-dir --no-deps \
"https://github.com/topoteretes/cognee-community/archive/52281288052970f57e533b9be75b64da9ac7c773.tar.gz#subdirectory=packages/vector/qdrant"
# sitecustomize.py auto-imports at every Python interpreter start in this
# venv. Gated on VECTOR_DB_PROVIDER so it's a no-op unless qdrant is actually
# selected — this is the adapter's own documented registration call
# (cognee-community-vector-adapter-qdrant README: "Import and register the
# adapter in your code: from cognee_community_vector_adapter_qdrant import
# register"), just run automatically instead of requiring a cognee source
# edit to add the import.
RUN printf '%s\n' \
'import os' \
'if os.environ.get("VECTOR_DB_PROVIDER") == "qdrant":' \
' from cognee_community_vector_adapter_qdrant import register # noqa: F401' \
> /app/.venv/lib/python3.12/site-packages/sitecustomize.py
# Pre-installed Kuzu/Ladybug JSON extension (P4 deploy blocker fix, 2026-07-05).
# cognee's graph adapter (cognee/infrastructure/databases/graph/ladybug/adapter.py)
# always tries `LOAD EXTENSION JSON` on startup and on every /health graph check,
# falling back to `INSTALL JSON` (a network download from
# extension.ladybugdb.com) if not already cached at
# ~/.lbdb/extension/<kuzu_version>/<platform>/json/libjson.lbug_extension. This
# extension is required for recall/temporal-search graph queries — without it
# cognee's /health reports "unhealthy" and graph queries that use JSON fail
# with a Binder exception ("Extension: json ... has not been installed").
#
# This deployment's egress to extension.ladybugdb.com is severely
# bandwidth-throttled (~1-1.2 KB/s per connection — confirmed via direct curl,
# not a proxy/DNS block: TLS handshake and HTTP 200 succeed, the transfer
# itself just crawls), so the runtime auto-download reliably times out before
# the ~827KB file finishes, and every subsequent health check/query re-attempts
# and fails the same way. Downloaded once out-of-band (16-way parallel ranged
# GETs, ~846920 bytes, verified ELF shared object) and baked into the image
# here so the container never needs to touch that host at runtime.
COPY extensions/0.17.0/linux_amd64/json/libjson.lbug_extension \
/root/.lbdb/extension/0.17.0/linux_amd64/json/libjson.lbug_extension

BIN
ai/cognee/extensions/0.17.0/linux_amd64/json/libjson.lbug_extension Normal file
View File

Binary file not shown.

730
ai/docker-compose.yml Normal file
View File

@@ -0,0 +1,730 @@
# kb#220: dir renamed openai/ -> ai/ (nothing in it is OpenAI). Pin the
# compose project name explicitly so container/network/volume names
# (e.g. openai_adolf-state) stay stable across the rename -- otherwise
# Compose derives the project name from the directory basename and the
# rename would orphan the existing volume/network.
name: openai
services:
litellm-db:
image: postgres:16-alpine
container_name: litellm-db
environment:
- POSTGRES_DB=litellm
- POSTGRES_USER=litellm
- POSTGRES_PASSWORD=litellm
volumes:
- /mnt/ssd/dbs/litellm/postgres:/var/lib/postgresql/data
restart: always
# kb#190: cheap connectivity probe, no query load.
healthcheck:
test: ["CMD-SHELL", "pg_isready -U litellm -d litellm"]
interval: 10s
timeout: 5s
retries: 5
start_period: 10s
litellm:
image: ghcr.io/berriai/litellm:main-latest
container_name: litellm
ports:
- "4000:4000"
volumes:
- ./litellm-config.yaml:/app/config.yaml
environment:
- DATABASE_URL=postgresql://litellm:litellm@litellm-db:5432/litellm
- LITELLM_MASTER_KEY=sk-fjQC1BxAiGFSMs
- LANGFUSE_PUBLIC_KEY=${LANGFUSE_PUBLIC_KEY:-changeme}
- LANGFUSE_SECRET_KEY=${LANGFUSE_SECRET_KEY:-changeme}
- LANGFUSE_HOST=http://langfuse:3000
- OPENROUTER_API_KEY=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
command: ["--config", "/app/config.yaml", "--port", "4000"]
extra_hosts:
- "host.docker.internal:host-gateway"
depends_on:
litellm-db:
condition: service_healthy
langfuse:
condition: service_healthy
restart: always
# kb#190: /health/liveliness is litellm's cheap liveness probe (no
# provider/model call), unlike /health which pings every configured model.
healthcheck:
test: ["CMD-SHELL", "node -e \"fetch('http://localhost:4000/health/liveliness').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))\""]
interval: 15s
timeout: 10s
retries: 5
start_period: 20s
# kimi-agent — REMOVED 2026-08-01 (Kimi purge). Was the only large-tier
# deployment behind LiteLLM; `tier-large`, the auto_router complex route and
# their fallbacks now point at the codex-backed adolf-llm wrapper instead
# (litellm-config.yaml model_name: codex-agent). The kimi-agent-home volume
# and /home/alvis/kimi-workspace are left on disk deliberately — drop them
# once the Codex path has proven itself.
langfuse-db:
image: postgres:16-alpine
container_name: langfuse-db
environment:
- POSTGRES_DB=langfuse
- POSTGRES_USER=langfuse
- POSTGRES_PASSWORD=langfuse
volumes:
- /mnt/ssd/dbs/langfuse/postgres:/var/lib/postgresql/data
restart: always
# kb#190: cheap connectivity probe, no query load.
healthcheck:
test: ["CMD-SHELL", "pg_isready -U langfuse -d langfuse"]
interval: 10s
timeout: 5s
retries: 5
start_period: 10s
# kb#148 (A2A-16): Langfuse v3 split the monolith into langfuse-web +
# langfuse-worker, and added ClickHouse (event/analytics store), Redis
# (queue) and S3-compatible blob storage (MinIO here) as hard
# dependencies -- Postgres alone is no longer sufficient, unlike v2.
# NOT YET ACTIVATED: v2's existing trace history (3175+ traces per
# DESIGN-a2a-agents.md §7, confirmed live 2026-07-26) lives only in the
# langfuse-db Postgres volume in v2's schema. Langfuse's official v2->v3
# upgrade path requires running the migration entrypoint once against
# this data (langfuse/langfuse:3's container runs pending Postgres
# migrations automatically on boot, but the ClickHouse backfill of
# historical trace data is a separate, explicit step -- see Langfuse's
# "Upgrade from v2 to v3" guide) BEFORE cutting traffic over, or the old
# traces are stranded. That migration is a live-data operation with real
# downtime and rollback risk, so it is out of scope for an unattended
# edit -- see kb#148's report for the exact handoff commands. New
# volumes (clickhouse/minio/redis below) also need their host dirs
# created + chowned first (root-gated, same pattern as kb#87's
# hindsight-cache dir).
langfuse-worker:
image: docker.io/langfuse/langfuse-worker:3
container_name: langfuse-worker
depends_on: &langfuse-depends-on
langfuse-db:
condition: service_healthy
langfuse-minio:
condition: service_healthy
langfuse-redis:
condition: service_healthy
langfuse-clickhouse:
condition: service_healthy
environment: &langfuse-worker-env
NEXTAUTH_URL: https://lf.alogins.net
DATABASE_URL: postgresql://langfuse:langfuse@langfuse-db:5432/langfuse
SALT: 7927b3b0092afe4542274940b557becea6418a5fed79f7acd25c3a789349fdc9
ENCRYPTION_KEY: 12056e4e3cf5b9d936fedca267d4bd877a4b79fb9ff0ff32859a623d5e96c814
CLICKHOUSE_MIGRATION_URL: clickhouse://langfuse-clickhouse:9000
CLICKHOUSE_URL: http://langfuse-clickhouse:8123
CLICKHOUSE_USER: clickhouse
CLICKHOUSE_PASSWORD: f1d3bd6dc01c9741b99c633b2e167d1d
LANGFUSE_S3_EVENT_UPLOAD_BUCKET: langfuse
LANGFUSE_S3_EVENT_UPLOAD_REGION: auto
LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID: minio
LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY: 078dd39aada907ab40c6a4d581033cfe
LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT: http://langfuse-minio:9000
LANGFUSE_S3_EVENT_UPLOAD_FORCE_PATH_STYLE: "true"
LANGFUSE_S3_EVENT_UPLOAD_PREFIX: events/
LANGFUSE_S3_MEDIA_UPLOAD_BUCKET: langfuse
LANGFUSE_S3_MEDIA_UPLOAD_REGION: auto
LANGFUSE_S3_MEDIA_UPLOAD_ACCESS_KEY_ID: minio
LANGFUSE_S3_MEDIA_UPLOAD_SECRET_ACCESS_KEY: 078dd39aada907ab40c6a4d581033cfe
LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT: http://langfuse-minio:9000
LANGFUSE_S3_MEDIA_UPLOAD_FORCE_PATH_STYLE: "true"
LANGFUSE_S3_MEDIA_UPLOAD_PREFIX: media/
REDIS_HOST: langfuse-redis
REDIS_PORT: "6379"
REDIS_AUTH: 36471006ce5b95ed4f7fb769788fe91c
restart: always
langfuse:
image: docker.io/langfuse/langfuse:3
container_name: langfuse
depends_on: *langfuse-depends-on
ports:
- "3200:3000"
environment:
<<: *langfuse-worker-env
NEXTAUTH_SECRET: 532a746b24ac40afa39f9d317031cab94d4d6881107ea3b1209b28020f1a9761
AUTH_DISABLE_SIGNUP: "true"
LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT: https://lf.alogins.net
restart: always
# kb#190: langfuse's Next.js server binds the container's bridge IP,
# NOT 127.0.0.1/localhost (confirmed via `ss -tlnp` inside the
# container: 127.0.0.1 connection is refused) -- so the probe must
# address it by its own compose DNS name, which resolves to that same
# bridge IP from inside the container.
healthcheck:
test: ["CMD-SHELL", "wget -q -O- http://langfuse:3000/api/public/health || exit 1"]
interval: 15s
timeout: 10s
retries: 5
start_period: 30s
langfuse-clickhouse:
image: docker.io/clickhouse/clickhouse-server:25.12
container_name: langfuse-clickhouse
user: "101:101"
environment:
- CLICKHOUSE_DB=default
- CLICKHOUSE_USER=clickhouse
- CLICKHOUSE_PASSWORD=f1d3bd6dc01c9741b99c633b2e167d1d
volumes:
- /mnt/ssd/dbs/langfuse/clickhouse-data:/var/lib/clickhouse
- /mnt/ssd/dbs/langfuse/clickhouse-logs:/var/log/clickhouse-server
restart: always
healthcheck:
test: wget --no-verbose --tries=1 --spider http://localhost:8123/ping || exit 1
interval: 5s
timeout: 5s
retries: 10
start_period: 1s
langfuse-minio:
image: cgr.dev/chainguard/minio
container_name: langfuse-minio
entrypoint: sh
# create the 'langfuse' bucket before starting the service
command: -c 'mkdir -p /data/langfuse && minio server --address ":9000" --console-address ":9001" /data'
environment:
- MINIO_ROOT_USER=minio
- MINIO_ROOT_PASSWORD=078dd39aada907ab40c6a4d581033cfe
volumes:
- /mnt/ssd/dbs/langfuse/minio:/data
restart: always
healthcheck:
test: ["CMD", "mc", "ready", "local"]
interval: 1s
timeout: 5s
retries: 5
start_period: 1s
langfuse-redis:
image: docker.io/redis:7
container_name: langfuse-redis
command: >
--requirepass 36471006ce5b95ed4f7fb769788fe91c
--maxmemory-policy noeviction
volumes:
- /mnt/ssd/dbs/langfuse/redis:/data
restart: always
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 3s
timeout: 10s
retries: 10
qdrant:
image: qdrant/qdrant
container_name: qdrant
ports:
- "6333:6333"
- "6334:6334"
restart: always
volumes:
- /mnt/ssd/dbs/qdrant:/qdrant/storage:z
# GPU residency decision (kb#191, 2026-07-26, DESIGN-a2a-agents.md sec 3b):
# the 8GB GTX 1070 only has ~1.7GB free with the never-evict set (bge-m3 +
# tei-reranker) resident alongside gemma3:4b -- no room for a 4th GPU
# tenant without risking evicting the reranker (silent Hindsight recall
# breakage). Runs CPU-only until the card gets more headroom. Never
# started yet -- kb#175 (Adolf STT) was parked waiting on this call.
faster-whisper:
image: fedirz/faster-whisper-server:latest-cuda
container_name: faster-whisper
ports:
- "8880:8000"
environment:
- WHISPER__MODEL=deepdml/faster-whisper-large-v3-turbo-ct2
- WHISPER__INFERENCE_DEVICE=cpu
- WHISPER__COMPUTE_TYPE=int8
- WHISPER__LANGUAGE=ru
volumes:
- /mnt/ssd/ai/faster-whisper:/root/.cache/huggingface
restart: always
silero-tts:
build: ./silero-tts
container_name: silero-tts
ports:
- "8881:8881"
volumes:
- /mnt/ssd/ai/silero-tts:/cache/torch
restart: always
pipecat:
build: ./pipecat
container_name: pipecat
ports:
- "8882:8882"
environment:
- LIVEKIT_URL=ws://host.docker.internal:7880
- LIVEKIT_PUBLIC_URL=wss://lk.alogins.net
- LIVEKIT_API_KEY=devkey
- LIVEKIT_SECRET=ef3ef4b903ca8469b09b2dd7ab6af529c4d2f3c95668f53832fc351cf67777a9
- ADOLF_URL=http://host.docker.internal:8000/v1
- STT_URL=http://host.docker.internal:8880/v1
- TTS_URL=http://host.docker.internal:8881/v1
- STT_MODEL=deepdml/faster-whisper-large-v3-turbo-ct2
- TTS_VOICE=onyx
extra_hosts:
- "host.docker.internal:host-gateway"
restart: unless-stopped
# Adolf — OpenClaw fork (Matrix-first personal assistant). The OpenClaw
# gateway config (Matrix channel + allow-list, model provider ->
# adolf-llm:8010, MCP registry, gateway.tools.allow for cron/nodes) is
# version-controlled at agap_git/adolf/openclaw.json (repo root, alongside
# this ai/ project, not nested inside it) and bind-mounted read-only
# over the adolf-state volume (see volumes below), so git is the single
# source of truth — not a hand-edited volume file. The volume still
# holds runtime state only (Matrix crypto/devices, credentials, sessions,
# workspace/SOUL.md, logs). Matrix creds and ADOLF_KEY come from
# ai/.env (gitignored, never committed). Source tree: /home/alvis/adolf.
# To change config: edit ../adolf/openclaw.json + restart adolf.
adolf:
build:
context: ../../adolf
# Matrix is opt-in at build time (see adolf/Dockerfile); without this,
# the gateway logs "no-channel-owner" and channels.matrix is inert.
args:
OPENCLAW_EXTENSIONS: matrix
image: adolf:local
container_name: adolf
environment:
- HOME=/home/node
- OPENCLAW_HOME=/home/node
- OPENCLAW_STATE_DIR=/home/node/.openclaw
- OPENCLAW_CONFIG_PATH=/home/node/.openclaw/openclaw.json
- OPENCLAW_CONFIG_DIR=/home/node/.openclaw
- OPENCLAW_WORKSPACE_DIR=/home/node/.openclaw/workspace
- OPENCLAW_GATEWAY_TOKEN=${ADOLF_GATEWAY_TOKEN:-}
- ADOLF_KEY=${ADOLF_KEY:-}
- MATRIX_HOMESERVER=${MATRIX_HOMESERVER:-}
- MATRIX_USER_ID=${MATRIX_USER_ID:-}
# kb#67: stable token + device_id pin, so restarts reuse the existing
# Matrix device (matrix-sdk/OpenClaw's own credential cache in the
# adolf-state volume already does this across restarts -- see
# extensions/matrix/src/matrix/client/config.ts resolveMatrixAuth --
# but that cache lives in the volume, so a lost/rebuilt volume would
# fall through to MATRIX_PASSWORD and mint a brand-new device with no
# cross-signing. Setting the token here removes that dependency).
# MATRIX_PASSWORD stays configured as a manual-recovery fallback only:
# it is never used while MATRIX_ACCESS_TOKEN resolves to a valid token.
- MATRIX_ACCESS_TOKEN=${MATRIX_ACCESS_TOKEN:-}
- MATRIX_DEVICE_ID=${MATRIX_DEVICE_ID:-}
- MATRIX_PASSWORD=${MATRIX_PASSWORD:-}
- MATRIX_DEVICE_NAME=${MATRIX_DEVICE_NAME:-Adolf OpenClaw Gateway}
# marketplace-mcp bearer token (kb task #61) -- referenced by
# openclaw.json's mcp.servers.marketplace.headers.Authorization via
# ${MARKETPLACE_MCP_TOKEN} substitution; never inlined into that file.
- MARKETPLACE_MCP_TOKEN=${MARKETPLACE_MCP_TOKEN:-}
# agap-mcp bearer token (kb#180) -- agap-mcp's :3100 listener requires
# `Authorization: Bearer <token>` on every route now (DESIGN §4: no
# unauthenticated JSON-RPC listener; :3100 is host-networked and the
# LAN carries VPN-terminated peers). Referenced by openclaw.json's
# mcp.servers.agap.headers.Authorization via ${AGAP_MCP_TOKEN}
# substitution, and read directly by the todoist-capture plugin's
# /capture-idea POST. The token must map to agent id `adolf` in
# agap-mcp's AGAP_MCP_AGENT_TOKENS. Sourced from ai/.env
# (gitignored); never inlined here.
- AGAP_MCP_TOKEN=${AGAP_MCP_TOKEN:-}
- TZ=Europe/Riga
volumes:
# kb#219: permanent host mount, replacing the named Docker volume
# (openai_adolf-state) so Adolf's state is inspectable/backup-able on
# the host like every other Agap service (hindsight, litellm, qdrant,
# langfuse, ... all live under /mnt/ssd/dbs/<service>). Runtime state
# only (Matrix crypto/devices, credentials, sessions, workspace,
# logs). The gateway config file and personas are overlaid below.
# Migration: agap_git/ai/migrate-adolf-state.sh (copies the old
# openai_adolf-state volume here; run + verified before this bind
# mount is activated — see kb#219).
# NOT YET ACTIVE (2026-07-31): migrate-adolf-state.sh has not been run,
# so /mnt/ssd/dbs/adolf/ is empty and binding it starts Adolf with a
# clobbered config. Reverted to the named volume until kb#219's root
# setup + migration is done; re-swap these six lines then.
- adolf-state:/home/node/.openclaw
# kb#219: config binds folded from two scattered locations
# (agap_git/adolf/openclaw.json + four agap_git/ai/*-plugin dirs)
# into one coherent home, /mnt/ssd/dbs/adolf/config/. Git remains the
# single source of truth for content — these are symlinks back to the
# tracked agap_git paths (created by the root setup block in kb#219's
# report), not copies, so "edit the tracked file + restart" still
# applies unchanged. Only the mount *path* changed from five spread
# locations to one directory tree.
#
# Version-controlled OpenClaw gateway config, mounted read-only on top
# of the state mount so it is the single source of truth. The gateway
# reads this JSONC file and snapshots its own .last-good/.rejected
# copies into the state dir (writable) — it never rewrites this file,
# so read-only is safe.
- ../adolf/openclaw.json:/home/node/.openclaw/openclaw.json:ro
# quota-command plugin (kb #62) — same read-only-bind pattern as
# openclaw.json above, applied to a single external plugin dir.
# Activated via plugins.entries.quota-command in openclaw.json.
- ./quota-command-openclaw-plugin:/home/node/.openclaw/extensions/quota-command:ro
# hindsight-memory plugin (kb #75, H3) — same pattern. Forced hooks
# (before_prompt_build recall / agent_end retain) against the
# hindsight service (see that service's block below), replacing
# Cognee as Adolf's memory backend. Activated via
# plugins.entries.hindsight-memory in openclaw.json.
- ./hindsight-openclaw-plugin:/home/node/.openclaw/extensions/hindsight-memory:ro
# kimi-quota-footer plugin (kb #85) — same pattern. Appends the Kimi
# usage line to every outgoing reply via reply_payload_sending, reusing
# quota-command's adolf-llm:8010/usage route. Activated via
# plugins.entries.kimi-quota-footer in openclaw.json.
- ./kimi-quota-footer-plugin:/home/node/.openclaw/extensions/kimi-quota-footer:ro
# todoist-capture plugin (kb#170 component 1) — same pattern.
# Registers /idea (native command, zero Kimi calls); POSTs to
# agap-mcp's /capture-idea (see agap-mcp/src/server.js + capture.js)
# which does the actual bge-m3 classify + Todoist create. Activated
# via plugins.entries.todoist-capture in openclaw.json.
- ./todoist-capture-plugin:/home/node/.openclaw/extensions/todoist-capture:ro
# kb#219 / kb#156: personas deploy read-only onto the mount from the
# alvis/agent-personas gitea repo (commit 936f655 at time of writing)
# via that repo's deploy/deploy-persona.sh, landing at
# /mnt/ssd/dbs/adolf/personas/adolf/*.md. Overlaid individually onto
# the corresponding workspace/*.md files so they stay read-only from
# Adolf's side and are written only by a git deploy — "who changed
# Adolf's soul" is answerable by `git log` in that repo. USER.md is
# deliberately NOT deployed (alvis, 2026-07-30): Hindsight's per-human
# bank (#153) is the single source of user facts now, USER.md was the
# stale unused template.
# (persona overlays deliberately not mounted until kb#219 lands — the
# personas currently live inside the adolf-state volume's workspace/)
extra_hosts:
- "host.docker.internal:host-gateway"
# mtx.alogins.net's public A record can't hairpin-NAT back through the
# router from inside a container; route it to the host gateway instead,
# matching matrix/docker-compose.yml's lk-jwt-service (same problem,
# same fix). Caddy on the host terminates TLS on :443 and proxies to
# synapse:8008.
- "mtx.alogins.net:host-gateway"
# Local *.alogins.net web services (family wiki / OtterWiki, РодоВики) —
# same hairpin-NAT dodge: the public A record can't loop back through the
# router from inside a container, so route the hostname to the host
# gateway where Caddy terminates TLS on :443 and proxies to the service.
# Lets Adolf's OpenClaw browser reach them with the real URL + the
# Vaultwarden creds. Add more *.alogins.net hosts here as needed.
- "family.alogins.net:host-gateway"
- "wiki.alogins.net:host-gateway"
cap_drop:
- NET_RAW
- NET_ADMIN
security_opt:
- no-new-privileges:true
init: true
ports:
- "18789:18789"
- "18790:18790"
command:
["node", "dist/index.js", "gateway", "--bind", "lan", "--port", "18789"]
restart: unless-stopped
# hindsight-llm — standalone clone of cognee-llm (kb#76, H4 option B): the
# dedicated Codex-CLI wrapper that is now Hindsight's LLM, so the whole cognee
# stack (incl. cognee-llm) can be decommissioned. Own port (:8012) + own
# codex volume; needs a one-time `codex login` seeded into
# hindsight-llm-codex-home. Migrated off Kimi CLI 2026-07-31 for cost.
hindsight-llm:
build: ./hindsight-llm
container_name: hindsight-llm
environment:
# Same OpenAI geo-block workaround as adolf-llm above — see the comment
# there. This wrapper makes no MCP calls, but NO_PROXY still keeps
# container-to-container traffic off the tunnel.
- HTTPS_PROXY=http://host.docker.internal:56928
- HTTP_PROXY=http://host.docker.internal:56928
- NO_PROXY=localhost,127.0.0.1,::1,host.docker.internal,.alogins.net,172.16.0.0/12,10.0.0.0/8,192.168.0.0/16
extra_hosts:
# Needed to reach the host's xray proxy (:56928) for OpenAI egress.
- "host.docker.internal:host-gateway"
ports:
- "8012:8012"
volumes:
- hindsight-llm-codex-home:/root/.codex
restart: unless-stopped
# kb#190: GET /v1/models is a static, no-inference route (see
# hindsight-llm/server.js) -- cheap liveness probe.
healthcheck:
test: ["CMD-SHELL", "node -e \"fetch('http://localhost:8012/v1/models').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))\""]
interval: 15s
timeout: 10s
retries: 5
start_period: 20s
# tei-reranker — GPU cross-encoder rerank sidecar for Hindsight (kb#87).
# Hindsight's recall reranker ran the multilingual jina-reranker-v2 on the
# image's CPU-only torch; over the grown adolf bank (269 facts, ~81 rerank
# candidates) a single recall pinned ~8 cores for ~183s, so the memory
# plugin's 4s timeout skipped injection every time. The stock HF TEI GPU
# image needs CUDA sm_75+; this box is a GTX 1070 (Pascal sm_61), so we serve
# the SAME jina model via plain CUDA torch (Pascal-compatible) behind the
# TEI-compatible /info + /rerank API that Hindsight's `tei` provider speaks.
# Shares the GPU with ollama (~1GB fp16 here, ~5.6GB ollama peak, 8GB card).
# Reuses the already-downloaded model from hindsight's HF cache (no re-DL).
tei-reranker:
build: ./tei-reranker
container_name: tei-reranker
runtime: nvidia
environment:
- NVIDIA_VISIBLE_DEVICES=all
- NVIDIA_DRIVER_CAPABILITIES=compute,utility
- RERANKER_MODEL=jinaai/jina-reranker-v2-base-multilingual
- RERANKER_DEVICE=cuda
- HF_HOME=/root/.cache/huggingface
volumes:
- /mnt/ssd/dbs/hindsight-cache/huggingface:/root/.cache/huggingface
ports:
- "8014:80"
restart: unless-stopped
# kb#190: /info is TEI's own lightweight metadata endpoint (model name,
# no rerank/inference call). Container has python3 only (no curl/wget).
healthcheck:
test: ["CMD-SHELL", "python3 -c \"import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://localhost:80/info',timeout=3).status==200 else 1)\""]
interval: 15s
timeout: 10s
retries: 5
start_period: 30s
# adolf-llm — conversational Codex-CLI wrapper (:8010), the model backend for
# the Adolf OpenClaw gateway (P2). Real streaming (SSE), chat_id session-keying
# + 1:1 `codex exec resume`, media, shared MCP via a generated
# $CODEX_HOME/config.toml sourced from the shared-mcp.json contract
# (cognee-mcp P4, openclaw-tools P5). Needs `codex login` in
# adolf-llm-codex-home.
#
# Migrated off Kimi CLI 2026-07-31 for cost (Moonshot subscription retired in
# favour of the existing ChatGPT plan).
adolf-llm:
build: ./adolf-llm
container_name: adolf-llm
environment:
# marketplace-mcp bearer token (kb#61) -- shared-mcp.json's
# "marketplace" entry references this by name via
# `bearerTokenEnvVar: "MARKETPLACE_MCP_TOKEN"`, which adolf-llm's config
# writer translates to Codex's own `bearer_token_env_var` key. Codex
# reads process.env at request time, so the raw secret never sits in
# the git-tracked shared-mcp.json -- same secret, same env-var pattern
# already used for the `adolf` service's openclaw.json Layer-1 config
# above (${MARKETPLACE_MCP_TOKEN} substitution), sourced from
# ai/.env (gitignored, never committed).
- MARKETPLACE_MCP_TOKEN=${MARKETPLACE_MCP_TOKEN:-}
# agap-mcp bearer token (kb#180) -- same env-var pattern, referenced by
# shared-mcp.json's "agap" entry via `bearerTokenEnvVar:
# "AGAP_MCP_TOKEN"`. Without it the Codex backbone's agap tools all
# fail with HTTP 401 once agap-mcp restarts with auth on.
- AGAP_MCP_TOKEN=${AGAP_MCP_TOKEN:-}
# OpenAI egress proxy (Codex migration, 2026-07-31). OpenAI geo-blocks
# this host outright: a direct call returns HTTP 403
# `unsupported_country_region_territory`, so `codex login` and every model
# call fail without this. Routed through the same xray proxy on the host
# that Claude Code itself uses (:56928, listening on all interfaces);
# reached from the container via the host-gateway alias below.
# Codex is Rust/reqwest, which honours these vars natively.
- HTTPS_PROXY=http://host.docker.internal:56928
- HTTP_PROXY=http://host.docker.internal:56928
# NO_PROXY is load-bearing, not cosmetic: without it ALL egress —
# including MCP calls to hindsight/openclaw-tools/agap-mcp and the local
# *.alogins.net services — would be tunnelled through xray, which is both
# slow and likely to fail. Only OpenAI should take the tunnel.
- NO_PROXY=localhost,127.0.0.1,::1,host.docker.internal,hindsight,openclaw-tools,.alogins.net,172.16.0.0/12,10.0.0.0/8,192.168.0.0/16
ports:
- "8010:8010"
volumes:
- adolf-llm-workspace:/workspace
- adolf-llm-codex-home:/root/.codex
- ./shared-mcp.json:/shared-mcp.json:ro
extra_hosts:
# Needed to reach kanboard-mcp-adolf (:3104, network_mode: host, outside
# this compose project's network) via shared-mcp.json's "kanboard"
# entry — same host-gateway trick used by adolf/cognee/pipecat above.
- "host.docker.internal:host-gateway"
# Local *.alogins.net web services: the Codex CLI's own web-fetch tool
# runs IN THIS container, so it needs the same hairpin-NAT dodge as the
# adolf gateway (the public A record can't loop back through the router).
# Route to the host gateway where Caddy terminates TLS on :443.
- "family.alogins.net:host-gateway"
- "wiki.alogins.net:host-gateway"
restart: unless-stopped
# kb#190: GET /v1/models is a static, no-inference route (see
# adolf-llm/server.js) -- cheap liveness probe, no Codex call/quota use.
healthcheck:
test: ["CMD-SHELL", "node -e \"fetch('http://localhost:8010/v1/models').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))\""]
interval: 15s
timeout: 10s
retries: 5
start_period: 20s
# hindsight — Adolf memory backend, replacing cognee/cognee-mcp/cognee-llm
# (kb#73, migration doc agap_git/adolf/HINDSIGHT-MIGRATION.md, H1). One
# container: REST API :8888 (also serves the built-in MCP at /mcp/{bank}/),
# UI :9999, built-in Postgres (pg0) bind-mounted to
# /mnt/ssd/dbs/hindsight/ (host dir created + chowned 1000:1000 to match
# the image's non-root `hindsight` user, confirmed via
# `docker run --entrypoint id`).
#
# LLM + embeddings reconfigured 2026-07-15 (kb#84) to fix two wrong H1
# choices for a Russian/multilingual use case:
#
# LLM -> hindsight-llm:8012 (dedicated Kimi-CLI wrapper cloned from the shim cognee
# uses — see cognee/cognee.env's LLM section for the full precedent,
# including why LLM_INSTRUCTOR_MODE=json_mode isn't needed here since
# Hindsight's own client doesn't go through `instructor`). Replaces the
# H1 choice of LiteLLM + ollama/gemma3:4b (a tiny local model): validated
# 2026-07-15 that cognee-llm returns clean, JSON-parseable structured
# extraction for Russian input (see kb#84 probe B) — gemma3:4b's fluency
# on Russian was never actually verified, it was picked only to dodge
# qwen3:8b's <think>-token empty-content bug. Kimi is also the flat-rate
# subscription already paid for, so this isn't a new cost.
#
# Embeddings -> ollama's bge-m3 on the GPU (host.docker.internal:11436,
# separate compose project, same extra_hosts trick as cognee/adolf-llm
# below), via ollama's OpenAI-compatible /v1/embeddings endpoint
# (confirmed 200 + 1024-dim vector 2026-07-15, kb#84 probe A). Replaces
# the H1 choice of Hindsight's built-in `local` provider
# (BAAI/bge-small-en-v1.5, English-only, 384-d, CPU-bound in-process
# SentenceTransformers). The hindsight image itself is CPU-only (torch
# +cpu build, no onnxruntime GPU provider — confirmed 2026-07-15), so its
# in-process local/onnx embedders can never reach the GPU; routing
# through ollama's `openai` embeddings provider (HTTP, not the bespoke
# cognee-style `ollama` provider Hindsight doesn't have) is how GPU
# serving happens here. Dimensions var matches cognee.env's own bge-m3
# swap (kb#60): 1024.
#
# Runs ALONGSIDE cognee/cognee-mcp/cognee-llm during the migration; those
# are untouched here and only decommissioned in H4, after H2/H3/H5 prove
# this service out. Not yet wired into openclaw.json/shared-mcp.json
# (that's H2, kb#74) — this block only stands the service up and proves
# retain/recall against a throwaway bank.
hindsight:
image: ghcr.io/vectorize-io/hindsight:latest
container_name: hindsight
restart: unless-stopped
environment:
# ALL stages on the local model (alvis, 2026-07-26): retain/extraction
# moved OFF Kimi (hindsight-llm:8012) onto ollama/gemma3:4b via LiteLLM,
# joining consolidation + reflect which were already local. Kimi is no
# longer in the Hindsight path at all, so the memory backend costs zero
# quota and Adolf's 5h window is left entirely for conversation.
#
# ⚠️ Accepted tradeoff: the kb#88/kb#84 rationale for keeping retain on
# Kimi was fact QUALITY — gemma3:4b's Russian fluency was never verified
# (it was originally picked only to dodge qwen3:8b's <think>-token bug),
# and this bank's content is largely Russian. Watch extraction quality on
# the next retains; if facts degrade, this is the first thing to revert.
- HINDSIGHT_API_LLM_PROVIDER=openai
- HINDSIGHT_API_LLM_BASE_URL=http://litellm:4000/v1
- HINDSIGHT_API_LLM_MODEL=ollama/gemma3:4b
- HINDSIGHT_API_LLM_API_KEY=sk-fjQC1BxAiGFSMs
- HINDSIGHT_API_CONSOLIDATION_LLM_PROVIDER=openai
- HINDSIGHT_API_CONSOLIDATION_LLM_BASE_URL=http://litellm:4000/v1
- HINDSIGHT_API_CONSOLIDATION_LLM_MODEL=ollama/gemma3:4b
- HINDSIGHT_API_CONSOLIDATION_LLM_API_KEY=sk-fjQC1BxAiGFSMs
- HINDSIGHT_API_REFLECT_LLM_PROVIDER=openai
- HINDSIGHT_API_REFLECT_LLM_BASE_URL=http://litellm:4000/v1
- HINDSIGHT_API_REFLECT_LLM_MODEL=ollama/gemma3:4b
- HINDSIGHT_API_REFLECT_LLM_API_KEY=sk-fjQC1BxAiGFSMs
- HINDSIGHT_API_EMBEDDINGS_PROVIDER=openai
- HINDSIGHT_API_EMBEDDINGS_OPENAI_BASE_URL=http://host.docker.internal:11436/v1
- HINDSIGHT_API_EMBEDDINGS_OPENAI_MODEL=bge-m3
- HINDSIGHT_API_EMBEDDINGS_OPENAI_DIMENSIONS=1024
# ollama doesn't check this value at all (no auth), but the openai
# embeddings client requires a non-empty key to construct.
- HINDSIGHT_API_EMBEDDINGS_OPENAI_API_KEY=ollama
# Stable worker id (compose service name), not the container hostname
# default -- without this, recreating the container orphans any
# in-flight async retain/consolidation tasks under the old hostname
# (startup log warns about exactly this).
- HINDSIGHT_API_WORKER_ID=hindsight
# Reranker -> TEI GPU sidecar (kb#87). Was `local` = the same
# multilingual jina-reranker-v2, but on this image's CPU-only torch it
# pinned ~8 cores for ~183s over the grown adolf bank (269 facts / ~81
# rerank candidates), so the memory plugin's 4s recall timeout skipped
# injection every time. Now the identical jina model is served on the
# GPU by the tei-reranker sidecar behind the TEI /rerank API.
- HINDSIGHT_API_RERANKER_PROVIDER=tei
- HINDSIGHT_API_RERANKER_TEI_URL=http://tei-reranker:80
- HINDSIGHT_API_RERANKER_TEI_HTTP_TIMEOUT=60
volumes:
- /mnt/ssd/dbs/hindsight:/home/hindsight/.pg0
# Persist HuggingFace/sentence-transformers model cache so the jina
# reranker (~1GB) doesn't re-download on every container recreate.
- /mnt/ssd/dbs/hindsight-cache:/home/hindsight/.cache
ports:
- "8888:8888"
- "9999:9999"
extra_hosts:
# Needed to resolve host.docker.internal from inside the container
# for the ollama embeddings call above — ollama lives in a separate
# compose project, same trick as cognee/adolf-llm elsewhere in this
# file.
- "host.docker.internal:host-gateway"
depends_on:
# kb#217: litellm is now on the critical path for all three LLM stages
# (HINDSIGHT_API_*_LLM_BASE_URL above all point at litellm:4000) since
# the 2026-07-26 gemma3:4b re-route (59af13f); gate on its healthcheck
# (added by kb#190) so a cold boot doesn't race hindsight up before it.
litellm:
condition: service_healthy
# hindsight-llm dropped (kb#217): it was the Kimi-CLI wrapper that used
# to serve retain before the re-route above; nothing in this service's
# config points at hindsight-llm:8012 any more (grep confirms only
# model-registry.yaml still lists it, unrelated to this container's
# startup). The hindsight-llm service/volume are left in place — that's
# a separate decommission decision, not this task's scope.
tei-reranker:
condition: service_healthy
# kb#190: /health is hindsight's own liveness+DB-connectivity endpoint
# (returns {"status":"healthy","database":"connected"}), confirmed cheap
# (curl is present in this image).
healthcheck:
test: ["CMD-SHELL", "curl -sf http://localhost:8888/health || exit 1"]
interval: 15s
timeout: 10s
retries: 5
start_period: 30s
# openclaw-tools — MCP bridge (P5) exposing a minimal slice of the Adolf
# OpenClaw gateway's agent tools (message/cron/nodes/browser) over MCP
# Streamable HTTP, so Kimi CLI sessions (adolf-llm) can call them instead of
# bypassing OpenClaw entirely. Proxies each MCP tool call to the gateway's
# `POST /tools/invoke` HTTP surface (http://adolf:18789). NOTE: `cron` and
# `nodes` are hard-denied on that surface by default until P6 adds them to
# `gateway.tools.allow` in the adolf openclaw.json — see openclaw-tools/
# server.js for the full gate writeup. Not useful until `adolf` (P6) is
# configured and running; safe to build/run standalone before that.
openclaw-tools:
build: ./openclaw-tools
container_name: openclaw-tools
environment:
- OPENCLAW_GATEWAY_URL=http://adolf:18789
- OPENCLAW_GATEWAY_TOKEN=${ADOLF_GATEWAY_TOKEN:-}
ports:
- "8020:8020"
restart: unless-stopped
volumes:
# No longer mounted by any service (kimi-agent removed 2026-08-01). Left
# declared so the volume survives as a rollback source; `docker volume rm`
# is a human decision after a soak period.
kimi-agent-home:
# kb#219: no longer mounted by the adolf service (replaced by the
# /mnt/ssd/dbs/adolf/state bind mount above). Left declared, not removed,
# so the volume itself survives as a rollback source until a human
# explicitly `docker volume rm adolf-state` after a soak period — see the
# rollback procedure in the kb#219 report. Removing this declaration is
# a later cleanup step, not part of this migration.
adolf-state:
# Replaces hindsight-llm-home (/root/.kimi-code) at the Codex migration; the
# old volume still holds the Kimi login until this is verified.
hindsight-llm-codex-home:
adolf-llm-workspace:
# Replaces adolf-llm-home (/root/.kimi-code) at the Codex migration. The old
# volume still exists and holds the Kimi OAuth login; drop it once the Codex
# backend is verified working.
adolf-llm-codex-home:

474
ai/feedback-loop-openclaw-plugin/index.js Normal file
View File

@@ -0,0 +1,474 @@
/**
* Proactive Feedback Loop (kb #125) — closes the loop DESIGN-proactive-
* prioritization.md (kb #123) needs: suggested -> got a rating -> took it
* into account -> became more accurate.
*
* Producer/consumer split with kb #123 (not built yet, design-only):
* THIS plugin owns the log (schema = that design's §5 `proactive_outcome`)
* and the two capture paths (text reply, best-effort emoji reaction).
* kb #123's future gate is a *reader* of `get_proactive_feedback_stats` and
* a *writer* of `log_proactive_action` for suppressed/deferred candidates
* (outcome: "not_sent") once it exists. Until then, Adolf itself is the
* only writer/reader: it calls `log_proactive_action` right after drafting
* a proactive send (same generation pass, no extra LLM call — matching the
* design's cost discipline) and can call `get_proactive_feedback_stats`
* before deciding whether a class of nudge is worth sending again.
*
* Storage decision (flagged explicitly, per kb #125's brief): this is NOT a
* Hindsight bank. kb #123 needs per-class *counts and decayed rates* — a
* tabular aggregate, not semantic recall — and Hindsight's recall/reflect
* endpoints have no "give me accepted_count for class X" primitive; getting
* one out would mean re-deriving a SQL-shaped answer from ranked free-text
* memories, which is strictly worse than just keeping the rows. This plugin
* is also NOT eligible for OpenClaw's own trusted plugin-state SQLite
* (`api.state.openKeyedStore` throws "only available for trusted plugins in
* this release" for any installed plugin that isn't bundled or
* trustedOfficialInstall — verified against src/plugins/registry.ts — and
* this plugin, like its hindsight-memory/quota-command siblings, is a local
* bind-mounted install, neither). So: a small JSON array file via the public
* `openclaw/plugin-sdk/json-store` helpers (atomic, 0o600), sized for
* homelab volume (dozens/day, capped at maxRecords). If plugin-state SQLite
* ever opens up to installed plugins, this is the one file to migrate.
*
* Capture paths:
*
* 1) TEXT (primary, robust) — `message_received` (observation-only, fires
* pre-agent-turn, zero marginal Kimi cost since the user's message was
* already going to produce a turn regardless): matches short exact
* replies ("+", "-"/"−", "неактуально", etc.) against the pending record
* correlated by `event.replyToId` (an explicit Matrix "reply to" quoting
* Adolf's proactive message) or, absent that, the sender's single newest
* still-pending record within `replyFallbackWindowMs` (never guessed if
* more than one candidate is pending — see resolvePendingTarget below).
*
* 2) EMOJI REACTION (secondary, best-effort, flagged low-confidence) — there
* is NO public plugin hook for inbound Matrix reactions in this OpenClaw
* version (checked docs/plugins/hooks.md's full hook catalog and
* extensions/matrix/src/matrix/monitor/reaction-events.ts directly).
* Reactions are handled entirely inside the bundled matrix extension: a
* reaction that targets a pending *approval* resolves through a private
* target store (extensions/matrix/src/approval-reactions.ts) a
* third-party plugin cannot register into; a reaction on any other
* message (the case that matters here — reacting to a proactive send)
* falls through to `core.system.enqueueSystemEvent(...)`, which queues
* free text ("Matrix reaction added: <emoji> by <sender> on msg <id>")
* to be prefixed onto the *next* prompt for that session — i.e. the
* model would have to read and interpret it, at whatever future turn
* happens to occur next, which could be a long delay and is not a
* deterministic capture. `openclaw/plugin-sdk/system-event-runtime`
* exports `peekSystemEventEntries` (read-only, non-consuming) as a public
* surface, so this plugin opportunistically peeks the queue in
* `before_prompt_build` and regex-matches that exact line format against
* pending records by message id — a side effect that costs nothing extra
* (the turn was already about to happen) and never removes/mutates the
* queue entry core itself will still drain normally. This is explicitly a
* best-effort enhancement, not the load-bearing mechanism: whether
* `before_prompt_build` fires before or after core's own queue drain for
* the *same* turn is unverified (would need a live-fire trace), so a
* reaction and the turn that would have surfaced it to this hook can, in
* the worst case, race. Text replies remain the mechanism kb #123 should
* trust; treat reaction-derived rows as a bonus signal only.
*/
import crypto from "node:crypto";
import path from "node:path";
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { readJsonFileWithFallback, writeJsonFileAtomically } from "openclaw/plugin-sdk/json-store";
import { resolveStateDir } from "openclaw/plugin-sdk/state-paths";
import { peekSystemEventEntries } from "openclaw/plugin-sdk/system-event-runtime";
const DEFAULTS = {
enabled: true,
maxRecords: 5000,
ignoreAfterMs: 24 * 60 * 60 * 1000,
replyFallbackWindowMs: 24 * 60 * 60 * 1000,
acceptedTextPatterns: ["+", "+1"],
dismissedTextPatterns: ["-", "−", "-1"], // hyphen-minus and Unicode minus sign (U+2212, what "−" often renders as)
irrelevantTextPatterns: ["неактуально", "не актуально", "irrelevant", "not relevant"],
acceptedEmoji: ["\u{1F44D}"], // 👍
dismissedEmoji: ["\u{1F44E}"], // 👎
irrelevantEmoji: ["\u{1F937}"], // 🤷
statsTrailingN: 50,
};
function normalizeConfig(raw) {
const c = raw && typeof raw === "object" ? raw : {};
const int = (v, d, min) => (Number.isFinite(v) && v >= min ? Math.floor(v) : d);
const strArr = (v, d) =>
Array.isArray(v) && v.length ? v.filter((s) => typeof s === "string" && s.trim()) : d;
return {
enabled: c.enabled !== false,
maxRecords: int(c.maxRecords, DEFAULTS.maxRecords, 50),
ignoreAfterMs: int(c.ignoreAfterMs, DEFAULTS.ignoreAfterMs, 60000),
replyFallbackWindowMs: int(c.replyFallbackWindowMs, DEFAULTS.replyFallbackWindowMs, 60000),
acceptedTextPatterns: strArr(c.acceptedTextPatterns, DEFAULTS.acceptedTextPatterns),
dismissedTextPatterns: strArr(c.dismissedTextPatterns, DEFAULTS.dismissedTextPatterns),
irrelevantTextPatterns: strArr(c.irrelevantTextPatterns, DEFAULTS.irrelevantTextPatterns),
acceptedEmoji: strArr(c.acceptedEmoji, DEFAULTS.acceptedEmoji),
dismissedEmoji: strArr(c.dismissedEmoji, DEFAULTS.dismissedEmoji),
irrelevantEmoji: strArr(c.irrelevantEmoji, DEFAULTS.irrelevantEmoji),
statsTrailingN: int(c.statsTrailingN, DEFAULTS.statsTrailingN, 5),
};
}
// --- log file -----------------------------------------------------------
function logFilePath() {
// Writable adolf-state volume (/home/node/.openclaw), NOT the read-only
// bind-mounted plugin source dir — see docker-compose.yml's adolf.volumes.
return path.join(resolveStateDir(), "plugins", "feedback-loop", "proactive-feedback.json");
}
// Tiny in-process sequential lock so overlapping hook/tool invocations
// (message_sent racing a text reply racing a reaction peek) always
// read-modify-write the log file one at a time instead of clobbering each
// other's writes. File-level, not cross-process — fine for a single Adolf
// gateway process owning one log file.
let chain = Promise.resolve();
function withLogLock(fn) {
const run = chain.then(fn, fn);
chain = run.then(
() => undefined,
() => undefined,
);
return run;
}
async function loadRecordsRaw() {
const { value } = await readJsonFileWithFallback(logFilePath(), { records: [] });
return Array.isArray(value?.records) ? value.records : [];
}
async function saveRecordsRaw(records) {
await writeJsonFileAtomically(logFilePath(), { records });
}
// Settle stale pending (outcome == null, sent, no response) rows to
// "ignored" — the design's required distinction from an explicit "-"
// (dismissed): an ignored item is a weaker negative signal and should not
// decay the acceptance rate as aggressively as an explicit rejection.
function settleStale(records, cfg, nowMs) {
let changed = false;
for (const r of records) {
if (r.outcome == null && r.sent !== false) {
const sentAtMs = Date.parse(r.sent_at);
if (Number.isFinite(sentAtMs) && nowMs - sentAtMs >= cfg.ignoreAfterMs) {
r.outcome = "ignored";
changed = true;
}
}
}
return changed;
}
function pruneToCap(records, cap) {
if (records.length <= cap) return records;
return records.slice(records.length - cap);
}
async function withRecords(cfg, mutate) {
return withLogLock(async () => {
const records = await loadRecordsRaw();
const changedByStale = settleStale(records, cfg, Date.now());
const result = await mutate(records);
const pruned = pruneToCap(records, cfg.maxRecords);
if (changedByStale || pruned !== records || result?.dirty) {
await saveRecordsRaw(pruned);
}
return result?.value;
});
}
// --- feedback text/emoji matching ---------------------------------------
function classifyText(text, cfg) {
const t = (text ?? "").trim();
if (!t) return null;
const lower = t.toLowerCase();
if (cfg.acceptedTextPatterns.some((p) => lower === p.toLowerCase())) return "accepted";
if (cfg.dismissedTextPatterns.some((p) => lower === p.toLowerCase())) return "dismissed";
if (cfg.irrelevantTextPatterns.some((p) => lower === p.toLowerCase())) return "irrelevant";
return null;
}
function classifyEmoji(emoji, cfg) {
if (!emoji) return null;
if (cfg.acceptedEmoji.includes(emoji)) return "accepted";
if (cfg.dismissedEmoji.includes(emoji)) return "dismissed";
if (cfg.irrelevantEmoji.includes(emoji)) return "irrelevant";
return null;
}
// Find the record a feedback event should attach to. Prefers an explicit
// reply-to match (deterministic); falls back to "the sender's one and only
// still-pending record in the window" and refuses to guess when more than
// one candidate exists, per the design's "never guess" discipline (kb#153
// applies the same rule to bank resolution; feedback attribution is the
// same shape of problem).
function resolvePendingTarget(records, { messageIds, senderId, nowMs, windowMs }) {
for (const messageId of messageIds || []) {
if (!messageId) continue;
const byId = records.find((r) => r.message_id === messageId && r.outcome == null);
if (byId) return byId;
}
if (!senderId) return null;
const candidates = records.filter((r) => {
if (r.outcome != null) return false;
if (r.sender_id && r.sender_id !== senderId) return false;
const sentAtMs = Date.parse(r.sent_at);
return Number.isFinite(sentAtMs) && nowMs - sentAtMs <= windowMs;
});
return candidates.length === 1 ? candidates[0] : null;
}
const REACTION_LINE_RE = /^Matrix reaction added: (.+) by (.+) on msg (\S+)$/;
function extractReactionsFromSystemEvents(entries) {
const out = [];
for (const e of entries) {
const text = typeof e?.text === "string" ? e.text : "";
const m = REACTION_LINE_RE.exec(text.trim());
if (m) out.push({ emoji: m[1].trim(), sender: m[2].trim(), eventId: m[3].trim() });
}
return out;
}
// --- stats ---------------------------------------------------------------
function laplaceRate(accepted, total) {
return (accepted + 1) / (total + 2);
}
function computeStats(records, statsTrailingN) {
const byClass = new Map();
for (const r of records) {
if (!r.action_class) continue;
if (!byClass.has(r.action_class)) byClass.set(r.action_class, []);
byClass.get(r.action_class).push(r);
}
const out = [];
for (const [action_class, rows] of byClass) {
// Recency-weighted: trailing N most recent settled (non-pending,
// non-not_sent) rows, per DESIGN-proactive-prioritization.md §3.3.
const settled = rows
.filter((r) => r.outcome && r.outcome !== "not_sent")
.sort((a, b) => Date.parse(b.sent_at) - Date.parse(a.sent_at))
.slice(0, statsTrailingN);
const counts = { accepted: 0, dismissed: 0, ignored: 0, irrelevant: 0 };
for (const r of settled) {
if (counts[r.outcome] != null) counts[r.outcome] += 1;
}
const total = settled.length;
out.push({
action_class,
total_settled: total,
total_all_time: rows.length,
pending: rows.filter((r) => r.outcome == null).length,
not_sent: rows.filter((r) => r.outcome === "not_sent").length,
...counts,
accept_prob: laplaceRate(counts.accepted, total),
});
}
out.sort((a, b) => a.action_class.localeCompare(b.action_class));
return out;
}
// ---------------------------------------------------------------------------
export default definePluginEntry({
id: "feedback-loop",
name: "Proactive Feedback Loop",
description:
"Logs proactive sends and their outcomes (kb #125), captures +/-/неактуально replies and best-effort emoji reactions, and exposes per-class acceptance-rate stats for kb #123's prioritization gate.",
register(api) {
const cfg = normalizeConfig(api.pluginConfig);
if (!cfg.enabled) return;
// 1) TOOL — record a proactive send (or a suppressed/deferred
// candidate the future kb#123 gate decided NOT to send). Called in the
// same generation pass Adolf drafts the candidate in, matching the
// design's "no separate LLM call" cost constraint.
api.registerTool(
(toolCtx) => ({
name: "log_proactive_action",
label: "Log Proactive Action",
description:
"Record a proactive action for feedback tracking (kb #125). Call this right when you decide to send (or suppress/defer) a proactive nudge/reminder/digest item — pass the same action_class/benefit/urgency/cost you used to decide, so kb #123's gate can later learn from the outcome. Do not call this for ordinary replies to a direct user question.",
parameters: {
type: "object",
additionalProperties: false,
properties: {
action_class: {
type: "string",
description:
"Coarse category, e.g. calendar_reminder, task_overdue, ha_anomaly, family_wiki_gap, digest_item. One row is kept per exact class, not per message text.",
},
sent: {
type: "boolean",
description:
"true if the message was actually sent to the user just now; false if this candidate was suppressed/deferred instead (logs outcome: not_sent immediately, no feedback expected).",
},
benefit_band: {
type: "number",
description: "Optional: the benefit(a) value used at send time (0/0.15/0.4/0.7/1.0 band).",
},
cost_tokens: {
type: "integer",
description: "Optional: estimated or actual marginal token cost of this send.",
},
urgency_at_send: {
type: "number",
description: "Optional: the urgency(a) value (0-1) used at send time.",
},
note: {
type: "string",
description: "Optional short free-text snippet of the candidate, for audit only (not scored).",
},
},
required: ["action_class", "sent"],
},
execute: async (_toolCallId, params) => {
const actionClass = String(params?.action_class || "").trim();
if (!actionClass) {
return {
content: [{ type: "text", text: "log_proactive_action: action_class is required." }],
details: { ok: false },
};
}
const sent = params?.sent !== false;
const id = crypto.randomUUID();
const record = {
id,
action_class: actionClass,
sent_at: new Date().toISOString(),
sent,
benefit_band: Number.isFinite(params?.benefit_band) ? params.benefit_band : null,
cost_tokens: Number.isFinite(params?.cost_tokens) ? Math.floor(params.cost_tokens) : null,
urgency_at_send: Number.isFinite(params?.urgency_at_send) ? params.urgency_at_send : null,
note: typeof params?.note === "string" ? params.note.slice(0, 300) : null,
outcome: sent ? null : "not_sent",
responded_at: null,
response_kind: null,
message_id: null,
// sessionKey lets the message_sent hook below attach the
// resulting outbound message id to THIS record without a
// second tool round-trip; sender_id lets text/reaction
// attribution scope to the right human (kb#153-style
// discipline, lower stakes here but kept consistent).
session_key: toolCtx?.sessionKey || null,
sender_id: toolCtx?.requesterSenderId || null,
};
await withRecords(cfg, (records) => {
records.push(record);
return { dirty: true };
});
return {
content: [{ type: "text", text: `Logged proactive action ${id} (${actionClass}, sent=${sent}).` }],
details: { ok: true, id },
};
},
}),
{ name: "log_proactive_action" },
);
// 2) TOOL — read back per-class acceptance stats. Usable today by
// Adolf itself (no kb#123 gate exists yet) to self-moderate proactive
// sends, and by kb#123's gate once built.
api.registerTool(
{
name: "get_proactive_feedback_stats",
label: "Get Proactive Feedback Stats",
description:
"Read Laplace-smoothed per-class acceptance rates from the proactive-action feedback log (kb #125), trailing-window recency-weighted per kb #123 §3.3. Use before sending a proactive nudge of a class that has a history of being dismissed/ignored.",
parameters: { type: "object", additionalProperties: false, properties: {} },
execute: async () => {
const stats = await withRecords(cfg, (records) => ({
dirty: false,
value: computeStats(records, cfg.statsTrailingN),
}));
return { content: [{ type: "text", text: JSON.stringify(stats, null, 2) }], details: { ok: true, stats } };
},
},
{ name: "get_proactive_feedback_stats" },
);
// 3) HOOK — message_sent: attach the outbound message id to the most
// recent still-open record from this same turn's session, so a later
// reply-to or reaction can find it. Best-effort correlation by
// sessionKey (message_sent does not carry runId reliably — see
// PluginHookMessageContext's doc comment in hook-message.types.ts);
// assumes at most one proactive send per turn, a known v1 limitation.
api.on("message_sent", async (event) => {
if (!event?.success || !event?.messageId || !event?.sessionKey) return;
await withRecords(cfg, (records) => {
for (let i = records.length - 1; i >= 0; i--) {
const r = records[i];
if (r.session_key === event.sessionKey && r.outcome == null && !r.message_id) {
r.message_id = event.messageId;
return { dirty: true };
}
}
return { dirty: false };
});
});
// 4) HOOK — message_received: the primary, deterministic feedback
// capture path. Observation-only (never blocks/rewrites the turn), so
// this never changes normal chat behavior and never spends an extra
// Kimi call — the user's message was already going to produce a turn.
api.on("message_received", async (event) => {
// Classify only the inbound message's OWN text — replyToBody (when
// present) is Adolf's original proactive message being quoted, not
// the user's feedback.
const feedbackKind = classifyText(event?.content, cfg);
if (!feedbackKind) return;
await withRecords(cfg, (records) => {
const target = resolvePendingTarget(records, {
// Try both id forms — Matrix inbound reply metadata may carry a
// normalized replyToId and/or the full event id, and message_sent
// above only ever stores whatever `messageId` that hook received.
messageIds: [event?.replyToId, event?.replyToIdFull],
senderId: event?.senderId,
nowMs: Date.now(),
windowMs: cfg.replyFallbackWindowMs,
});
if (!target) return { dirty: false };
target.outcome = feedbackKind;
target.responded_at = new Date().toISOString();
target.response_kind = "text";
return { dirty: true };
});
});
// 5) HOOK — before_prompt_build: best-effort emoji-reaction peek (see
// the file-header note on why this is secondary/unverified-timing, not
// the load-bearing path). Pure side effect: returns nothing, never
// mutates the prompt, so no allowPromptInjection/allowConversationAccess
// opt-in is needed for this plugin.
api.on("before_prompt_build", async (_event, ctx) => {
if (!ctx?.sessionKey) return;
let entries;
try {
entries = peekSystemEventEntries(ctx.sessionKey);
} catch {
return; // best-effort only; never fail a turn over this
}
const reactions = extractReactionsFromSystemEvents(entries || []);
if (reactions.length === 0) return;
await withRecords(cfg, (records) => {
let dirty = false;
for (const { emoji, eventId } of reactions) {
const outcome = classifyEmoji(emoji, cfg);
if (!outcome) continue;
const target = records.find((r) => r.message_id === eventId && r.outcome == null);
if (!target) continue;
target.outcome = outcome;
target.responded_at = new Date().toISOString();
target.response_kind = "reaction";
dirty = true;
}
return { dirty };
});
// No return value: this hook only observes, never mutates the prompt.
});
},
});

74
ai/feedback-loop-openclaw-plugin/openclaw.plugin.json Normal file
View File

@@ -0,0 +1,74 @@
{
"id": "feedback-loop",
"name": "Proactive Feedback Loop",
"description": "Logs every proactive send (kb #125) and its outcome — accepted/dismissed/irrelevant/ignored/not_sent — using the DESIGN-proactive-prioritization.md (kb #123) §5 schema. Captures feedback via short text replies (+/-/неактуально) observed on message_received, and via a best-effort peek at Matrix emoji-reaction system-event text on before_prompt_build (no dedicated reaction hook exists in OpenClaw today — see plugin README/report). Exposes log_proactive_action and get_proactive_feedback_stats tools so Adolf (and later kb #123's gate) can record sends and read back Laplace-smoothed per-class acceptance rates. No conversation-content hooks used — no allowConversationAccess/allowPromptInjection opt-in required.",
"activation": {
"onStartup": true
},
"contracts": {
"tools": ["log_proactive_action", "get_proactive_feedback_stats"]
},
"configSchema": {
"type": "object",
"additionalProperties": false,
"properties": {
"enabled": { "type": "boolean" },
"maxRecords": { "type": "integer", "minimum": 50, "maximum": 50000 },
"ignoreAfterMs": { "type": "integer", "minimum": 60000, "maximum": 2592000000 },
"replyFallbackWindowMs": { "type": "integer", "minimum": 60000, "maximum": 2592000000 },
"acceptedTextPatterns": { "type": "array", "items": { "type": "string" } },
"dismissedTextPatterns": { "type": "array", "items": { "type": "string" } },
"irrelevantTextPatterns": { "type": "array", "items": { "type": "string" } },
"acceptedEmoji": { "type": "array", "items": { "type": "string" } },
"dismissedEmoji": { "type": "array", "items": { "type": "string" } },
"irrelevantEmoji": { "type": "array", "items": { "type": "string" } },
"statsTrailingN": { "type": "integer", "minimum": 5, "maximum": 1000 }
}
},
"uiHints": {
"enabled": {
"label": "Feedback Loop",
"help": "Enable proactive-action feedback logging and capture."
},
"maxRecords": {
"label": "Max Log Records",
"help": "Oldest records are pruned FIFO once the log exceeds this many rows (default 5000 — homelab scale, not a hard requirement)."
},
"ignoreAfterMs": {
"label": "Ignore-After (ms)",
"help": "A sent proactive action with no response by this age is settled to outcome=ignored (weaker negative signal than an explicit dismiss). Default 24h."
},
"replyFallbackWindowMs": {
"label": "Reply Fallback Window (ms)",
"help": "When an inbound feedback reply does not quote a specific message (no replyToId), fall back to the sender's single newest pending record within this window. If more than one pending record exists, the reply is left unattributed rather than guessed. Default 24h."
},
"acceptedTextPatterns": {
"label": "Accepted Text Patterns",
"help": "Exact (case-insensitive, trimmed) reply texts that mark the correlated proactive action accepted. Default: [\"+\", \"+1\"]."
},
"dismissedTextPatterns": {
"label": "Dismissed Text Patterns",
"help": "Exact reply texts that mark the correlated action dismissed. Default: [\"-\", \"−\", \"-1\"] (both hyphen-minus and Unicode minus sign)."
},
"irrelevantTextPatterns": {
"label": "Irrelevant Text Patterns",
"help": "Exact reply texts that mark the correlated action irrelevant. Default: [\"неактуально\", \"не актуально\", \"irrelevant\", \"not relevant\"]."
},
"acceptedEmoji": {
"label": "Accepted Emoji",
"help": "Reaction emoji mapped to accepted when opportunistically matched from queued system-event text. Default: [\"👍\"]."
},
"dismissedEmoji": {
"label": "Dismissed Emoji",
"help": "Reaction emoji mapped to dismissed. Default: [\"👎\"]."
},
"irrelevantEmoji": {
"label": "Irrelevant Emoji",
"help": "Reaction emoji mapped to irrelevant. Default: [\"🤷\"]."
},
"statsTrailingN": {
"label": "Stats Trailing N",
"help": "get_proactive_feedback_stats computes each class's acceptance rate over at most this many of its most recent settled records (recency-weighted per DESIGN-proactive-prioritization.md §3.3). Default 50."
}
}
}

18
ai/feedback-loop-openclaw-plugin/package.json Normal file
View File

@@ -0,0 +1,18 @@
{
"name": "openclaw-feedback-loop",
"version": "1.0.0",
"description": "Proactive-action feedback loop for Adolf (kb #125): logs every proactive send, captures text (+/-/неактуально) and best-effort emoji-reaction feedback, and exposes a per-class acceptance-rate readout for kb #123's prioritization gate.",
"type": "module",
"private": true,
"main": "./index.js",
"peerDependencies": {
"openclaw": ">=2026.3.0"
},
"openclaw": {
"extensions": ["./index.js"],
"compat": {
"pluginApi": ">=2026.0.0",
"minGatewayVersion": "2026.0.0"
}
}
}

74
ai/gpu_preload_check.sh Executable file
View File

@@ -0,0 +1,74 @@
#!/usr/bin/env bash
# gpu_preload_check.sh — GPU residency guard (design DESIGN-a2a-agents.md sec 3b)
#
# Never-evict set on the 8GB GTX 1070: bge-m3 (embedder) + tei-reranker.
# Evicting either silently breaks Hindsight recall (the memory plugin's
# recall timeout just skips injection, no error surfaced) — the whole
# reason this guard exists.
#
# Usage: gpu_preload_check.sh <requested_mib> [gpu_index]
# requested_mib — VRAM footprint (MiB) of the model/process about to load
# gpu_index — nvidia-smi GPU index (default 0)
#
# Exit 0 — safe to proceed, never-evict set stays resident with headroom.
# Exit 1 — reject: loading this would eat into or evict the never-evict set.
# Exit 2 — reject: never-evict set isn't even currently resident (abort,
# something is already wrong — don't compound it by loading more).
#
# This is a guard for callers (workers/scripts) that are about to pull a
# model onto the shared GPU. It does NOT itself load or evict anything.
set -euo pipefail
REQUESTED_MIB="${1:?usage: gpu_preload_check.sh <requested_mib> [gpu_index]}"
GPU_INDEX="${2:-0}"
# tei-reranker measured footprint (2026-07-26, jina-reranker-v2-base-multilingual
# fp16 on CUDA torch): ~1690 MiB resident. bge-m3 measured ~882 MiB via ollama.
# Keep these as a documented floor, not just "whatever's currently resident" —
# a transient dip during another process's own load shouldn't false-negative us.
RERANKER_FLOOR_MIB=1690
BGE_M3_FLOOR_MIB=882
NEVER_EVICT_FLOOR_MIB=$((RERANKER_FLOOR_MIB + BGE_M3_FLOOR_MIB))
log() { echo "[gpu_preload_check] $*" >&2; }
# 1. Confirm the never-evict set is actually resident right now.
reranker_up=0
if curl -fsS -m 3 "http://localhost:8014/info" >/dev/null 2>&1; then
reranker_up=1
fi
bge_m3_up=0
if docker exec ollama ollama ps 2>/dev/null | grep -q '^bge-m3'; then
bge_m3_up=1
fi
if [[ "$reranker_up" -ne 1 || "$bge_m3_up" -ne 1 ]]; then
log "REJECT: never-evict set not fully resident (tei-reranker up=$reranker_up, bge-m3 up=$bge_m3_up)."
log "Something is already wrong — fix that before loading anything else onto the GPU."
exit 2
fi
# 2. Check free VRAM and whether the requested load would eat into the
# never-evict floor.
free_mib=$(nvidia-smi --id="$GPU_INDEX" --query-gpu=memory.free --format=csv,noheader,nounits | tr -d ' ')
if [[ -z "$free_mib" ]]; then
log "REJECT: could not read nvidia-smi free memory for GPU $GPU_INDEX."
exit 1
fi
remaining_after_load=$((free_mib - REQUESTED_MIB))
log "free=${free_mib}MiB requested=${REQUESTED_MIB}MiB never_evict_floor=${NEVER_EVICT_FLOOR_MIB}MiB remaining_after_load=${remaining_after_load}MiB"
if (( remaining_after_load < 0 )); then
log "REJECT: requested load (${REQUESTED_MIB}MiB) exceeds current free VRAM (${free_mib}MiB)."
log "The kernel driver would have to evict something to fit it — on this box that means"
log "risking the never-evict set (bge-m3 + tei-reranker). Refusing."
exit 1
fi
log "OK: load fits in free VRAM without necessitating eviction of the never-evict set."
exit 0

19
ai/hindsight-llm/Dockerfile Normal file
View File

@@ -0,0 +1,19 @@
FROM node:22-slim
# Required: node:22-slim has no system CA store and the Codex CLI is a Rust
# binary that validates TLS against it. See adolf-llm/Dockerfile for detail.
RUN apt-get update \
&& apt-get install -y --no-install-recommends ca-certificates \
&& rm -rf /var/lib/apt/lists/*
RUN npm install -g @openai/codex
WORKDIR /workspace
COPY server.js /app/server.js
ENV CODEX_HOME=/root/.codex
EXPOSE 8012
ENTRYPOINT ["node", "/app/server.js"]

197
ai/hindsight-llm/server.js Normal file
View File

@@ -0,0 +1,197 @@
const http = require('http');
const fs = require('fs');
const path = require('path');
const crypto = require('crypto');
const { spawn } = require('child_process');
const PORT = 8012;
const MODEL_ID = 'hindsight-llm';
const TIMEOUT_MS = 5 * 60 * 1000; // one-shot structured calls; generous but bounded
// Bounded parallelism: SPIKE-FINDINGS.md gate 5 flagged the Kimi subscription as a
// single-seat, interactive-oriented plan — batch cognify must not hammer it with
// unbounded concurrent CLI spawns (rate-limit/throttle risk on a shared live account).
const MAX_CONCURRENCY = 3;
const WORKSPACE = '/workspace';
fs.mkdirSync(WORKSPACE, { recursive: true });
// The CLI has no raw sampling-temperature knob (it's an agent loop, not a
// completions API) — "low temperature" for structured extraction is enforced
// via an instruction preamble instead, prepended to whatever system prompt
// the caller (Cognee) supplies.
const STRUCTURED_SYSTEM_PREAMBLE = [
'You are a stateless structured-extraction engine.',
'This is a one-shot call with no memory of prior calls: do not reference earlier turns.',
'Respond deterministically and concisely. When asked for JSON, output raw JSON only',
'- no prose, no markdown code fences, no commentary before or after.',
].join(' ');
// --- message helpers ---------------------------------------------------------
// Text only, no media parts: this wrapper's policy is no-media/no-MCP, unlike
// adolf-llm which persists inbound images and lets the CLI's ReadMediaFile
// tool read them.
function textOf(msg) {
const c = msg.content;
if (Array.isArray(c)) return c.map(p => (typeof p.text === 'string' ? p.text : '')).join('\n');
return c == null ? '' : String(c);
}
function buildPrompt(messages) {
const systemParts = messages.filter(m => m.role === 'system').map(textOf);
const rest = messages.filter(m => m.role !== 'system');
const preamble = [STRUCTURED_SYSTEM_PREAMBLE, ...systemParts].join('\n\n');
const transcript = rest
.map(m => `${m.role === 'assistant' ? 'Assistant' : 'User'}: ${textOf(m)}`)
.join('\n\n');
return `${preamble}\n\n${transcript}`.trim();
}
// --- bounded concurrency queue -----------------------------------------------
let active = 0;
const queue = [];
function drain() {
if (queue.length && active < MAX_CONCURRENCY) queue.shift()();
}
function withSlot(fn) {
return new Promise((resolve, reject) => {
const run = () => {
active++;
fn().then(
v => { active--; drain(); resolve(v); },
e => { active--; drain(); reject(e); },
);
};
if (active < MAX_CONCURRENCY) run();
else queue.push(run);
});
}
// --- codex invocation: stateless one-shot, no resume -------------------------
// Fresh temp dir per call, no `exec resume`, discard the dir after.
// Parses `codex exec --json`, which ships two event schemas depending on
// release (see adolf-llm/server.js for the same dual handling):
// legacy: {"msg":{"type":"agent_message_delta","delta":"..."}}
// {"msg":{"type":"agent_message","message":"..."}}
// newer: {"type":"item.completed","item":{"type":"agent_message","text":...}}
// Deltas are preferred when present; the terminal full message is a fallback,
// never an addition, or the extraction output would be duplicated.
function runCodex({ prompt, cwd }) {
return new Promise((resolve, reject) => {
// --skip-git-repo-check: the per-call temp dir is not a git repo.
const args = ['exec', '--json', '--skip-git-repo-check', '-C', cwd, prompt];
// stdin 'ignore': otherwise codex waits for EOF on an unused pipe and the
// call hangs until TIMEOUT_MS. See adolf-llm/server.js for detail.
const child = spawn('codex', args, {
cwd,
timeout: TIMEOUT_MS,
stdio: ['ignore', 'pipe', 'pipe'],
});
let stdout = '';
let stderr = '';
child.stdout.on('data', d => { stdout += d; });
child.stderr.on('data', d => { stderr += d; });
child.on('error', reject);
child.on('close', code => {
const parts = [];
let finalText = null;
for (const line of stdout.split('\n')) {
const t = line.trim();
if (!t) continue;
let obj;
try { obj = JSON.parse(t); } catch { continue; }
const msg = obj.msg;
if (msg && typeof msg.type === 'string') {
if (msg.type === 'agent_message_delta' && msg.delta) parts.push(msg.delta);
else if (msg.type === 'agent_message' && msg.message) finalText = msg.message;
continue;
}
if (obj.type === 'item.completed' && obj.item && obj.item.type === 'agent_message') {
const text = typeof obj.item.text === 'string' ? obj.item.text : obj.item.message;
if (text) finalText = text;
}
}
const text = (parts.join('').trim() || (finalText || '').trim());
if (!text && code !== 0) {
reject(new Error(`codex exited ${code}: ${stderr.slice(0, 2000)}`));
} else {
resolve(text);
}
});
});
}
async function handleTurn(messages) {
const prompt = buildPrompt(messages || []);
const reqId = crypto.randomUUID();
const dir = path.join(WORKSPACE, reqId);
fs.mkdirSync(dir, { recursive: true });
try {
return await withSlot(() => runCodex({ prompt, cwd: dir }));
} finally {
// Stateless one-shot: nothing about this call is meant to survive it, so
// the temp dir is discarded unconditionally, success or failure.
fs.rm(dir, { recursive: true, force: true }, () => {});
}
}
// --- OpenAI-compatible HTTP surface (non-streaming only) ---------------------
function completionBody(text) {
return {
id: `chatcmpl-${Date.now()}`,
object: 'chat.completion',
created: Math.floor(Date.now() / 1000),
model: MODEL_ID,
choices: [{
index: 0,
message: { role: 'assistant', content: text },
finish_reason: 'stop',
}],
usage: { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 },
};
}
const server = http.createServer((req, res) => {
if (req.method === 'GET' && req.url === '/v1/models') {
res.writeHead(200, { 'Content-Type': 'application/json' });
res.end(JSON.stringify({
object: 'list',
data: [{ id: MODEL_ID, object: 'model', owned_by: 'openai' }],
}));
return;
}
if (req.method === 'POST' && req.url === '/v1/chat/completions') {
let body = '';
req.on('data', d => { body += d; });
req.on('end', async () => {
let parsed;
try {
parsed = JSON.parse(body);
} catch {
res.writeHead(400, { 'Content-Type': 'application/json' });
res.end(JSON.stringify({ error: 'invalid JSON body' }));
return;
}
try {
const text = await handleTurn(parsed.messages || []);
// Non-streaming policy: always return the full body even if the
// caller sets stream:true. Cognee's batch cognify has no use for SSE,
// and a one-shot call has nothing to incrementally stream anyway.
res.writeHead(200, { 'Content-Type': 'application/json' });
res.end(JSON.stringify(completionBody(text)));
} catch (err) {
res.writeHead(500, { 'Content-Type': 'application/json' });
res.end(JSON.stringify({ error: String(err.message || err) }));
}
});
return;
}
res.writeHead(404, { 'Content-Type': 'application/json' });
res.end(JSON.stringify({ error: 'not found' }));
});
server.listen(PORT, () => console.log(`hindsight-llm wrapper listening on :${PORT}`));

523
ai/hindsight-openclaw-plugin/index.js Normal file
View File

@@ -0,0 +1,523 @@
/**
* Hindsight Memory — an OpenClaw memory plugin, structural successor to
* cognee-openclaw-plugin (kb #75, H3). Same three touchpoints as the Cognee
* plugin it replaces:
*
* before_prompt_build -> recall => LLM-free retrieval, injected as prependContext
* agent_end -> retain => async persist of the turn (extraction runs server-side)
* *_recall / *_reflect tool => on-demand recall (LLM-free) / reflect (LLM-synthesized)
*
* Why recall is LLM-free (verified against the live service, kb #75 H3):
* POST /v1/default/banks/{bank}/memories/recall does semantic + BM25 (keyword)
* + spreading-activation graph traversal + temporal scoring and returns ranked
* raw fact/observation text (RecallResult.text) directly — there is no
* generation step on this path. (Verified via a live probe against a
* throwaway bank: POST retain -> POST recall returned the stored fact
* verbatim, no LLM call in the response.) The separate POST .../reflect
* endpoint is the LLM-synthesized path (used only by the optional
* hindsight_reflect tool below, never by the forced hooks).
*
* Key simplification vs. the Cognee plugin: no cognify-sweep machinery.
* Cognee needed an explicit, throttled background "cognify" step (dirty-set
* tracker + persisted state + per-dataset throttle) to turn raw added text
* into graph facts. Hindsight's retain endpoint does extraction, embedding,
* dedup, and entity/temporal linking server-side as part of the retain call
* itself (async:true just makes that happen off the request path) — so the
* whole class of "sweep never got re-armed after a hot-reload" bugs the
* Cognee plugin had to work around does not exist here. There is nothing to
* port.
*
* Bank scoping — per-human partitioning (kb#153 / A2A-21, DESIGN-a2a-agents.md
* v2.1 §5b, DECIDED): Adolf now talks to more than one human (alvis,
* elizaveta, ... per channels.matrix.dm.allowFrom), so a single shared bank
* is a correctness bug, not a simplification — content from one human's
* conversations must never surface to another human. Bank selection is keyed
* by the turn's interlocutor identity (Matrix sender, `ctx.senderId` /
* `ctx.requesterSenderId`), resolved via `humanBanks` (sender -> private
* bank id) + `sharedBankId` (one household bank recalled alongside the
* private bank, never written to automatically):
* - RECALL reads the sender's private bank + the shared bank, nothing else.
* - RETAIN writes ONLY the sender's private bank. Promotion of a private
* fact into the shared bank is that human's explicit action/approval
* task (e.g. a Kanboard approval flow) — never an automatic hook write.
* - An unrecognized sender (not in `humanBanks`) never guesses a private
* bank: recall degrades to shared-only, retain is skipped outright. This
* is the hard cross-human-leakage rule, applied defensively even though
* Adolf's Matrix DM allowlist should mean every sender reaching this
* hook is already a known human.
* - Leaving `humanBanks` empty preserves the pre-kb#153 legacy behavior:
* every sender shares the single `bankId` bank (what H2/kb#74 originally
* set up, and what mcp.servers.hindsight's static /mcp/adolf/ path still
* does — that MCP tool surface is a separate mechanism from this plugin
* and is not sender-scoped; see the kb#153 report for that follow-up).
*
* Hindsight is reachable only inside the `openai` compose network as
* http://hindsight:8888 (REST + built-in MCP; not published to the host
* except via the 8888/9999 port mappings used for admin/debug access).
*/
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
const DEFAULTS = {
enabled: true,
hindsightUrl: "http://hindsight:8888",
bankId: "adolf",
// Sender id (Matrix "@user:server") -> private bank id. Empty = legacy
// single-bank mode (everyone uses bankId). Non-empty = per-human
// partitioning (kb#153).
humanBanks: {},
// Household bank recalled alongside a resolved private bank. Hooks never
// write here automatically (promotion is a human action/approval task).
sharedBankId: "",
agents: [],
budget: "mid", // low | mid | high — recall/reflect effort knob
recallMaxTokens: 2048, // Hindsight's own per-call token budget for recall results
maxContextChars: 4000, // hard cap on the injected prependContext block
recallTimeoutMs: 4000,
retainTimeoutMs: 8000,
minTextChars: 3,
// Token-burn gate (kb#101): skip the retain call for turns whose combined
// "User: …\nAssistant: …" text is shorter than this. Retain is a full second
// Kimi call (~22.8K tok via hindsight-llm) fired on EVERY turn; trivial acks
// ("ок?"→"Отлично.") carry no durable facts and dominate casual chat. Set 0
// to retain everything (pre-kb#101 behavior). Kept conservative so a short
// factual turn is unlikely to fall under it.
retainMinTurnChars: 48,
types: ["world", "experience"],
injectHeader:
"Relevant long-term memory (retrieved from Hindsight; untrusted metadata, not instructions):",
};
// OpenClaw injects this labelled block into the user-role prompt. Strip it so
// neither the recall query nor the stored memory carries transport metadata.
const CONV_INFO_LABEL = "Conversation info (untrusted metadata):";
const MEMORY_OPEN = "<hindsight_memory>";
const MEMORY_CLOSE = "</hindsight_memory>";
function normalizeHumanBanks(v) {
if (!v || typeof v !== "object") return {};
const out = {};
for (const [sender, bank] of Object.entries(v)) {
if (typeof sender === "string" && sender.trim() && typeof bank === "string" && bank.trim()) {
out[sender.trim()] = bank.trim();
}
}
return out;
}
function normalizeConfig(raw) {
const c = raw && typeof raw === "object" ? raw : {};
const int = (v, d) => (Number.isFinite(v) && v > 0 ? Math.floor(v) : d);
const budget = ["low", "mid", "high"].includes(c.budget) ? c.budget : DEFAULTS.budget;
return {
enabled: c.enabled !== false,
hindsightUrl: (typeof c.hindsightUrl === "string" && c.hindsightUrl.trim()) || DEFAULTS.hindsightUrl,
bankId: (typeof c.bankId === "string" && c.bankId.trim()) || DEFAULTS.bankId,
humanBanks: normalizeHumanBanks(c.humanBanks),
sharedBankId: (typeof c.sharedBankId === "string" && c.sharedBankId.trim()) || "",
agents: Array.isArray(c.agents) ? c.agents.filter((a) => typeof a === "string" && a.trim()) : [],
budget,
recallMaxTokens: int(c.recallMaxTokens, DEFAULTS.recallMaxTokens),
maxContextChars: int(c.maxContextChars, DEFAULTS.maxContextChars),
recallTimeoutMs: int(c.recallTimeoutMs, DEFAULTS.recallTimeoutMs),
retainTimeoutMs: int(c.retainTimeoutMs, DEFAULTS.retainTimeoutMs),
minTextChars: int(c.minTextChars, DEFAULTS.minTextChars),
// Allow 0 (retain everything) — int() rejects 0, so handle it explicitly.
retainMinTurnChars: Number.isFinite(c.retainMinTurnChars) && c.retainMinTurnChars >= 0
? Math.floor(c.retainMinTurnChars)
: DEFAULTS.retainMinTurnChars,
types: Array.isArray(c.types) && c.types.length ? c.types.filter((t) => typeof t === "string") : DEFAULTS.types,
injectHeader: (typeof c.injectHeader === "string" && c.injectHeader.trim()) || DEFAULTS.injectHeader,
};
}
// --- text helpers -----------------------------------------------------------
function textOf(msg) {
if (msg == null) return "";
if (typeof msg === "string") return msg;
const content = msg.content;
if (Array.isArray(content)) {
return content
.map((p) => (typeof p === "string" ? p : p && typeof p.text === "string" ? p.text : ""))
.join("\n");
}
return content == null ? "" : String(content);
}
// Remove OpenClaw's untrusted-metadata block and our own injected memory block
// so stored/queried text is the real conversational content only.
function cleanText(text) {
let t = typeof text === "string" ? text : "";
const at = t.indexOf(CONV_INFO_LABEL);
if (at !== -1) t = t.slice(0, at);
let open;
while ((open = t.indexOf(MEMORY_OPEN)) !== -1) {
const close = t.indexOf(MEMORY_CLOSE, open);
if (close === -1) {
t = t.slice(0, open);
break;
}
t = t.slice(0, open) + t.slice(close + MEMORY_CLOSE.length);
}
return t.trim();
}
function lastRoleText(messages, role) {
if (!Array.isArray(messages)) return "";
for (let i = messages.length - 1; i >= 0; i--) {
const m = messages[i];
if (m && typeof m === "object" && m.role === role) {
const t = cleanText(textOf(m));
if (t) return t;
}
}
return "";
}
// Bank resolution (kb#153 / A2A-21, DESIGN-a2a-agents.md v2.1 §5b): given the
// turn's interlocutor identity, decide which bank(s) recall reads and which
// one bank retain may write. This is the ONLY place that decision is made —
// both hooks and the on-demand tools below call through here so the
// correctness rule (never guess a private bank for an unrecognized sender)
// can't drift between the two call sites.
function resolveBanksForSender(cfg, senderId) {
const partitioned = Object.keys(cfg.humanBanks).length > 0;
if (!partitioned) {
// Legacy mode (pre-kb#153): no humanBanks configured, everyone shares
// the single static bankId, exactly like before this feature existed.
return { privateBank: cfg.bankId, sharedBank: null, known: true };
}
const sid = typeof senderId === "string" ? senderId.trim() : "";
const privateBank = sid ? cfg.humanBanks[sid] : undefined;
if (privateBank) {
return { privateBank, sharedBank: cfg.sharedBankId || null, known: true };
}
// Unrecognized sender: never guess whose private bank this is. Recall can
// still degrade to the shared bank; retain must be skipped by the caller.
return { privateBank: null, sharedBank: cfg.sharedBankId || null, known: false };
}
// Chat/session label used only as free-text provenance (MemoryItem.context),
// never as a bank selector — see the bank-scoping note at the top of this file.
function chatLabel(ctx) {
const raw = (ctx && (ctx.chatId || ctx.channelId || ctx.sessionKey)) || "";
const slug = String(raw)
.toLowerCase()
.replace(/[^a-z0-9]+/g, "_")
.replace(/^_+|_+$/g, "")
.slice(0, 60);
return slug ? `chat_${slug}` : "chat_default";
}
// --- Hindsight HTTP client ---------------------------------------------------
function makeHindsight(cfg) {
const base = cfg.hindsightUrl.replace(/\/+$/, "");
// Bank id is now a per-call parameter, not a value baked in at construction
// time — kb#153 resolves it per turn from the sender, so a single client
// instance must be able to address any bank (private or shared).
const bankPath = (bankId) => `${base}/v1/default/banks/${encodeURIComponent(bankId)}`;
async function withTimeout(ms, fn) {
const ac = new AbortController();
const timer = setTimeout(() => ac.abort(new Error(`hindsight timeout after ${ms}ms`)), ms);
try {
return await fn(ac.signal);
} finally {
clearTimeout(timer);
}
}
// LLM-free recall against ONE bank: semantic + keyword + graph + temporal
// ranking only.
async function recallContext(bankId, query) {
const body = {
query,
budget: cfg.budget,
max_tokens: cfg.recallMaxTokens,
types: cfg.types,
};
const res = await withTimeout(cfg.recallTimeoutMs, (signal) =>
fetch(`${bankPath(bankId)}/memories/recall`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(body),
signal,
}),
);
if (!res.ok) throw new Error(`recall ${res.status}`);
const data = await res.json();
const results = Array.isArray(data?.results) ? data.results : [];
if (results.length === 0) return "";
const lines = results
.map((r) => (typeof r?.text === "string" ? r.text.trim() : ""))
.filter(Boolean);
let ctx = lines.join("\n");
return ctx.length > cfg.maxContextChars ? ctx.slice(0, cfg.maxContextChars) + "\n…" : ctx;
}
// Recall across up to two banks (a sender's private bank + the shared
// household bank, kb#153) and merge under one combined char budget. Each
// bank recall is independent and best-effort: one bank timing out or
// erroring never drops the other bank's results.
async function recallForBanks(bankIds, query) {
const ids = bankIds.filter(Boolean);
if (ids.length === 0) return "";
const settled = await Promise.allSettled(ids.map((id) => recallContext(id, query)));
const parts = settled
.map((r) => (r.status === "fulfilled" ? r.value : ""))
.filter(Boolean);
if (parts.length === 0) return "";
const ctx = parts.join("\n");
return ctx.length > cfg.maxContextChars ? ctx.slice(0, cfg.maxContextChars) + "\n…" : ctx;
}
// Retain one turn into ONE bank. async:true — Hindsight does
// extraction/consolidation server-side off the request path; we never wait
// for it. Callers must only ever pass a sender's own resolved private
// bank — never the shared bank (promotion to shared is a human action).
async function retainTurn(bankId, content, context) {
const body = {
async: true,
items: [{ content, context }],
};
const res = await withTimeout(cfg.retainTimeoutMs, (signal) =>
fetch(`${bankPath(bankId)}/memories`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(body),
signal,
}),
);
if (!res.ok) throw new Error(`retain ${res.status}`);
return true;
}
// LLM-synthesized answer over ONE bank (used only by the optional
// hindsight_reflect tool, never by the forced hooks).
async function reflect(bankId, query) {
const body = { query, budget: "low" };
const res = await withTimeout(cfg.recallTimeoutMs, (signal) =>
fetch(`${bankPath(bankId)}/reflect`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(body),
signal,
}),
);
if (!res.ok) throw new Error(`reflect ${res.status}`);
const data = await res.json();
return typeof data?.text === "string" ? data.text.trim() : "";
}
return { recallContext, recallForBanks, retainTurn, reflect };
}
// ---------------------------------------------------------------------------
export default definePluginEntry({
id: "hindsight-memory",
name: "Hindsight Memory",
description:
"Cross-session memory via Hindsight: LLM-free recall inject before each reply, async retain of each turn after it ends.",
register(api) {
let cfg = normalizeConfig(api.pluginConfig);
const hindsight = makeHindsight(cfg);
// runId -> { userText } captured at recall time, consumed at agent_end so
// retain stores the same clean user text the recall query used.
const pending = new Map();
const agentAllowed = (agentId) =>
cfg.agents.length === 0 || (agentId && cfg.agents.includes(agentId));
// 1) RECALL — before_prompt_build => inject LLM-free memory context,
// scoped to the turn's interlocutor (kb#153): the sender's private bank
// + the shared household bank, nothing else.
api.on(
"before_prompt_build",
async (event, ctx) => {
if (!cfg.enabled) return;
if (ctx?.trigger && ctx.trigger !== "user") return; // only real user turns
if (!agentAllowed(ctx?.agentId)) return;
const query = cleanText(lastRoleText(event?.messages, "user") || event?.prompt || "");
if (!query || query.length < cfg.minTextChars) return;
const banks = resolveBanksForSender(cfg, ctx?.senderId);
// Carry the resolved banks to agent_end so retain targets the same
// private bank recall used, even if ctx.senderId is ever absent there.
if (ctx?.runId) pending.set(ctx.runId, { userText: query, banks });
const bankIds = [banks.privateBank, banks.sharedBank].filter(Boolean);
if (bankIds.length === 0) {
// Unrecognized sender and no shared bank configured: nothing safe
// to recall from. Never fall back to a guessed bank (§5b).
api.logger?.debug?.(
`hindsight-memory: recall skipped (no bank resolved for sender ${ctx?.senderId || "unknown"})`,
);
return;
}
try {
const context = await hindsight.recallForBanks(bankIds, query);
if (!context) return;
const block = `${MEMORY_OPEN}\n${cfg.injectHeader}\n${context}\n${MEMORY_CLOSE}`;
api.logger?.info?.(
`hindsight-memory: injected ${context.length} chars of memory from bank(s) ${bankIds.join(", ")}`,
);
return { prependContext: block };
} catch (e) {
// Recall is best-effort: never block or fail a turn on memory.
api.logger?.debug?.(`hindsight-memory: recall skipped (${e?.message || e})`);
return;
}
},
{ timeoutMs: cfg.recallTimeoutMs + 2000 },
);
// 2) RETAIN — agent_end => async retain of the turn. No cognify/sweep
// step: Hindsight extracts+consolidates internally as part of retain.
// Writes ONLY the sender's private bank (kb#153 hard rule): promotion to
// the shared bank is that human's explicit action/approval task, never
// an automatic hook write.
api.on("agent_end", async (event, ctx) => {
if (!cfg.enabled) return;
const carried = ctx?.runId ? pending.get(ctx.runId) : undefined;
if (ctx?.runId) pending.delete(ctx.runId);
const userText = carried?.userText || lastRoleText(event?.messages, "user");
const assistantText = lastRoleText(event?.messages, "assistant");
const parts = [];
if (userText) parts.push(`User: ${userText}`);
if (assistantText) parts.push(`Assistant: ${assistantText}`);
const turn = parts.join("\n").trim();
if (turn.length < cfg.minTextChars) return;
// Token-burn gate (kb#101): don't spend a full retain (2nd Kimi call)
// on trivial turns that hold no durable facts.
if (turn.length < cfg.retainMinTurnChars) {
api.logger?.debug?.(
`hindsight-memory: retain skipped (trivial turn, ${turn.length} < ${cfg.retainMinTurnChars} chars)`,
);
return;
}
const banks = carried?.banks || resolveBanksForSender(cfg, ctx?.senderId);
if (!banks.privateBank) {
// Unrecognized sender: never guess whose bank this turn belongs to.
// Dropping the turn here (not the shared bank) is the correctness
// property kb#153 exists to enforce.
api.logger?.warn?.(
`hindsight-memory: retain skipped (no private bank resolved for sender ${ctx?.senderId || "unknown"} — refusing to guess to avoid cross-human leakage)`,
);
return;
}
try {
await hindsight.retainTurn(banks.privateBank, turn, chatLabel(ctx));
api.logger?.info?.(`hindsight-memory: retained turn to bank ${banks.privateBank}`);
} catch (e) {
api.logger?.warn?.(`hindsight-memory: retain failed (${e?.message || e})`);
}
});
// 3) TOOL — deliberate LLM-free recall. Registered as a factory so each
// invocation sees the current caller's trusted `requesterSenderId`
// (runtime-provided, not a tool arg) and resolves banks the same way the
// hooks do (kb#153) — an explicit on-demand lookup must not bypass the
// per-human partitioning the forced hooks enforce.
api.registerTool(
(toolCtx) => ({
name: "hindsight_recall",
label: "Hindsight Recall",
description:
"Search long-term memory (Hindsight) and return ranked fact/observation text WITHOUT an LLM synthesis step. Fast and factual. For a synthesized natural-language answer over memory, use hindsight_reflect instead.",
parameters: {
type: "object",
additionalProperties: false,
properties: {
query: {
type: "string",
description: "What to look up in long-term memory.",
},
},
required: ["query"],
},
execute: async (_toolCallId, params) => {
const query = cleanText(String(params?.query || ""));
if (!query) {
return { content: [{ type: "text", text: "hindsight_recall: empty query." }], details: { ok: false } };
}
const banks = resolveBanksForSender(cfg, toolCtx?.requesterSenderId);
const bankIds = [banks.privateBank, banks.sharedBank].filter(Boolean);
if (bankIds.length === 0) {
return {
content: [{ type: "text", text: "No relevant memory found (no bank resolved for this sender)." }],
details: { ok: true, chars: 0 },
};
}
try {
const context = await hindsight.recallForBanks(bankIds, query);
const text = context || "No relevant memory found.";
return { content: [{ type: "text", text }], details: { ok: true, chars: context.length } };
} catch (e) {
const msg = `hindsight_recall failed: ${e?.message || e}`;
return { content: [{ type: "text", text: msg }], details: { ok: false } };
}
},
}),
{ name: "hindsight_recall" },
);
// 4) TOOL (optional) — LLM-synthesized answer over memory. Reflect is a
// single synthesis call, so it targets one bank: the sender's private
// bank when resolved, else the shared bank as a degraded fallback —
// never a guessed private bank.
api.registerTool(
(toolCtx) => ({
name: "hindsight_reflect",
label: "Hindsight Reflect",
description:
"Ask a question over long-term memory and get back a synthesized natural-language answer (LLM-backed, slower than hindsight_recall). Use hindsight_recall first when raw facts are enough.",
parameters: {
type: "object",
additionalProperties: false,
properties: {
query: {
type: "string",
description: "The question to answer using long-term memory.",
},
},
required: ["query"],
},
execute: async (_toolCallId, params) => {
const query = cleanText(String(params?.query || ""));
if (!query) {
return { content: [{ type: "text", text: "hindsight_reflect: empty query." }], details: { ok: false } };
}
const banks = resolveBanksForSender(cfg, toolCtx?.requesterSenderId);
const bankId = banks.privateBank || banks.sharedBank;
if (!bankId) {
return {
content: [{ type: "text", text: "No answer could be synthesized (no bank resolved for this sender)." }],
details: { ok: true },
};
}
try {
const text = await hindsight.reflect(bankId, query);
return {
content: [{ type: "text", text: text || "No answer could be synthesized from memory." }],
details: { ok: true },
};
} catch (e) {
const msg = `hindsight_reflect failed: ${e?.message || e}`;
return { content: [{ type: "text", text: msg }], details: { ok: false } };
}
},
}),
{ name: "hindsight_reflect" },
);
},
});

94
ai/hindsight-openclaw-plugin/openclaw.plugin.json Normal file
View File

@@ -0,0 +1,94 @@
{
"id": "hindsight-memory",
"name": "Hindsight Memory",
"description": "Cross-session memory via Hindsight. Injects LLM-free recall context before each reply (before_prompt_build) and retains each turn asynchronously after it ends (agent_end); Hindsight extracts/consolidates server-side, so there is no client-side cognify sweep. Structural successor to cognee-memory (kb #75, H3).",
"activation": {
"onStartup": true
},
"contracts": {
"tools": ["hindsight_recall", "hindsight_reflect"]
},
"configSchema": {
"type": "object",
"additionalProperties": false,
"properties": {
"enabled": { "type": "boolean" },
"hindsightUrl": { "type": "string" },
"bankId": { "type": "string" },
"humanBanks": { "type": "object", "additionalProperties": { "type": "string" } },
"sharedBankId": { "type": "string" },
"agents": { "type": "array", "items": { "type": "string" } },
"budget": { "type": "string", "enum": ["low", "mid", "high"] },
"recallMaxTokens": { "type": "integer", "minimum": 128, "maximum": 32000 },
"maxContextChars": { "type": "integer", "minimum": 200, "maximum": 20000 },
"recallTimeoutMs": { "type": "integer", "minimum": 500, "maximum": 30000 },
"retainTimeoutMs": { "type": "integer", "minimum": 500, "maximum": 60000 },
"minTextChars": { "type": "integer", "minimum": 1, "maximum": 200 },
"retainMinTurnChars": { "type": "integer", "minimum": 0, "maximum": 2000 },
"types": { "type": "array", "items": { "type": "string" } },
"injectHeader": { "type": "string" }
}
},
"uiHints": {
"enabled": {
"label": "Hindsight Memory",
"help": "Enable cross-session Hindsight memory (recall inject + async turn retain)."
},
"hindsightUrl": {
"label": "Hindsight URL",
"help": "Base URL of the Hindsight REST API (default http://hindsight:8888)."
},
"bankId": {
"label": "Bank ID",
"help": "Legacy single-bank fallback. Used only when humanBanks is empty (per-human partitioning disabled) — recall/retain both target this one bank for every sender, the pre-A2A-21 (kb#153) behavior."
},
"humanBanks": {
"label": "Per-Human Private Banks",
"help": "Map of interlocutor id (Matrix sender, e.g. \"@admin:mtx.alogins.net\") -> that human's private Hindsight bank id (e.g. \"adolf-alvis\"). Non-empty enables per-human memory partitioning (kb#153/A2A-21 DESIGN §5b): recall/retain resolve the bank by the turn's sender instead of a single static bankId. A sender with no entry here is treated as unknown: recall falls back to sharedBankId only (never a guessed private bank) and retain is skipped entirely — this is the hard cross-human-leakage rule, not a gap to silently work around."
},
"sharedBankId": {
"label": "Shared Household Bank",
"help": "Hindsight bank id for facts explicitly shared across all humans (e.g. \"adolf-shared\"). Recalled alongside the sender's private bank when humanBanks is non-empty. Hooks never write here automatically — promotion from a private bank to shared is a human's explicit action/approval task, never an automatic retain (DESIGN §5b hard rule)."
},
"agents": {
"label": "Target Agents",
"help": "Agent ids that use Hindsight memory. Empty means all agents."
},
"budget": {
"label": "Recall/Reflect Budget",
"help": "Effort level for recall and reflect calls (low/mid/high). Higher costs more latency."
},
"recallMaxTokens": {
"label": "Recall Max Tokens",
"help": "Hindsight's own token budget for a single recall call's results."
},
"maxContextChars": {
"label": "Max Injected Context Chars",
"help": "Hard cap on the size of the injected memory block."
},
"recallTimeoutMs": {
"label": "Recall Timeout (ms)",
"help": "Budget for the LLM-free recall on the reply path. On timeout the turn proceeds with no injected memory."
},
"retainTimeoutMs": {
"label": "Retain Timeout (ms)",
"help": "Budget for the post-turn async retain call to Hindsight (off the reply path; async:true itself makes Hindsight's extraction non-blocking, this only bounds the HTTP request)."
},
"minTextChars": {
"label": "Minimum Text Chars",
"help": "Skip recall/retain for text shorter than this."
},
"retainMinTurnChars": {
"label": "Retain Min Turn Chars",
"help": "Skip the post-turn retain (a full 2nd Kimi call) for turns whose combined User/Assistant text is shorter than this — trivial acks carry no durable facts. 0 retains everything (kb#101 token-burn gate; default 48)."
},
"types": {
"label": "Recall Types",
"help": "Fact types to recall: world, experience, observation. Defaults to world and experience."
},
"injectHeader": {
"label": "Inject Header",
"help": "Header line prepended to the injected memory block."
}
}
}

18
ai/hindsight-openclaw-plugin/package.json Normal file
View File

@@ -0,0 +1,18 @@
{
"name": "openclaw-hindsight-memory",
"version": "1.0.0",
"description": "Hindsight-backed cross-session memory for OpenClaw (LLM-free recall inject, async retain).",
"type": "module",
"private": true,
"main": "./index.js",
"peerDependencies": {
"openclaw": ">=2026.3.0"
},
"openclaw": {
"extensions": ["./index.js"],
"compat": {
"pluginApi": ">=2026.0.0",
"minGatewayVersion": "2026.0.0"
}
}
}

128
ai/kimi-quota-footer-plugin/index.js Normal file
View File

@@ -0,0 +1,128 @@
/**
* Kimi Quota Footer (kb #85) — appends a compact Kimi usage line to the end of
* each of Adolf's outgoing replies, via OpenClaw's `reply_payload_sending`
* hook (docs/plugins/hooks.md: "Mutate or cancel normalized reply payloads
* before delivery... runs after payload normalization and before channel
* delivery, including replies routed back to the originating channel").
*
* Source of the numbers: the LLM-free `GET /usage` route on adolf-llm (kb
* #62), which talks straight to Kimi's managed-usage API — no model call
* anywhere.
*
* Never blocks the send path: usage is cached and refreshed in the
* background, so a reply is at most decorated with a slightly stale
* (<= cacheTtlMs) snapshot, and any error/timeout simply omits the footer
* rather than delaying or breaking the message.
*
* Streaming caveat (verified against /app/dist in the running container,
* kb#85): Matrix preview streaming ("draft previews finalize in place",
* docs/concepts/streaming.md) delivers the finalized text via a direct
* payload edit (`ctx.edit`/`onEditReceipt`) that never calls
* deliverOutboundPayloadsInternal, so reply_payload_sending would NOT fire
* for that path. Adolf's openclaw.json currently leaves
* channels.matrix.streaming unset (default "off"), so every real reply goes
* through the normal send path (sendDurableMessageBatch ->
* deliverOutboundPayloadsInternal) where this hook does fire. If Matrix
* streaming is ever turned on for Adolf, this footer will silently stop
* appearing on finalized-in-place replies — re-check this comment first.
*/
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
const DEFAULTS = {
enabled: true,
usageUrl: "http://adolf-llm:8010/usage",
cacheTtlMs: 60000, // serve a cached snapshot for up to this long
fetchTimeoutMs: 2500, // background fetch only; never on the send path
prefix: "— Kimi:",
};
function normalizeConfig(raw) {
const c = raw && typeof raw === "object" ? raw : {};
const int = (v, d) => (Number.isFinite(v) && v > 0 ? Math.floor(v) : d);
return {
enabled: c.enabled !== false,
usageUrl: typeof c.usageUrl === "string" && c.usageUrl ? c.usageUrl : DEFAULTS.usageUrl,
cacheTtlMs: int(c.cacheTtlMs, DEFAULTS.cacheTtlMs),
fetchTimeoutMs: int(c.fetchTimeoutMs, DEFAULTS.fetchTimeoutMs),
prefix: typeof c.prefix === "string" && c.prefix ? c.prefix : DEFAULTS.prefix,
};
}
function pct(bucket) {
if (!bucket || typeof bucket.pct !== "number") return null;
return Math.round(bucket.pct);
}
function formatFooter(usage, prefix) {
if (!usage) return null;
const parts = [];
const h5 = pct(usage.window_5h);
const wk = pct(usage.weekly);
const d7 = pct(usage.window_7d);
if (h5 !== null) parts.push(`5h ${h5}%`);
if (wk !== null) parts.push(`weekly ${wk}%`);
if (d7 !== null) parts.push(`7d ${d7}%`);
if (parts.length === 0) return null;
return `${prefix} ${parts.join(" · ")}`;
}
export default definePluginEntry({
id: "kimi-quota-footer",
name: "Kimi Quota Footer",
description: "Appends a compact Kimi usage line to the end of each outgoing reply.",
register(api) {
const cfg = normalizeConfig(api.pluginConfig);
// Non-blocking cache: the send path never awaits the network. When the
// snapshot is stale we kick a background refresh and keep using the last
// known one; a quota readout tolerates being a minute stale.
let cache = { usage: null, ts: 0 };
let refreshing = false;
async function refresh() {
if (refreshing) return;
refreshing = true;
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), cfg.fetchTimeoutMs);
try {
const res = await fetch(cfg.usageUrl, { signal: controller.signal });
if (!res.ok) throw new Error(`/usage HTTP ${res.status}`);
cache = { usage: await res.json(), ts: Date.now() };
} catch (e) {
api.logger?.debug?.(`kimi-quota-footer: usage refresh failed (${e?.message || e})`);
} finally {
clearTimeout(timer);
refreshing = false;
}
}
// Warm the cache at startup so the first reply already carries a footer.
refresh();
// Resolve the current footer, refreshing usage without blocking the send
// path (one-shot blocking only on a cold cache).
async function currentFooter() {
if (!cache.usage) {
await refresh();
} else if (Date.now() - cache.ts > cfg.cacheTtlMs) {
refresh();
}
return formatFooter(cache.usage, cfg.prefix);
}
api.on("reply_payload_sending", async (event) => {
try {
if (!cfg.enabled) return;
const payload = event?.payload;
const text = payload?.text;
if (typeof text !== "string" || text.trim().length === 0) return;
const footer = await currentFooter();
if (!footer || text.includes(footer)) return;
return { payload: { ...payload, text: `${text}\n\n${footer}` } };
} catch (e) {
api.logger?.warn?.(`kimi-quota-footer: hook failed (${e?.message || e})`);
}
});
},
});

37
ai/kimi-quota-footer-plugin/openclaw.plugin.json Normal file
View File

@@ -0,0 +1,37 @@
{
"id": "kimi-quota-footer",
"name": "Kimi Quota Footer",
"description": "Appends a compact Kimi usage line (5h/weekly/7d %) to the end of each of Adolf's outgoing replies, via the reply_payload_sending hook. Reads the LLM-free adolf-llm:8010/usage route (kb #62); cached + background-refreshed so it never blocks the send path.",
"activation": {
"onStartup": true
},
"configSchema": {
"type": "object",
"additionalProperties": false,
"properties": {
"enabled": { "type": "boolean" },
"usageUrl": { "type": "string" },
"cacheTtlMs": { "type": "integer", "minimum": 1000, "maximum": 3600000 },
"fetchTimeoutMs": { "type": "integer", "minimum": 200, "maximum": 30000 },
"prefix": { "type": "string" }
}
},
"uiHints": {
"enabled": {
"label": "Kimi Quota Footer",
"help": "Append a compact Kimi usage line to the end of each reply."
},
"usageUrl": {
"label": "Usage URL",
"help": "adolf-llm /usage endpoint (default http://adolf-llm:8010/usage)."
},
"cacheTtlMs": {
"label": "Cache TTL (ms)",
"help": "How long a fetched usage snapshot is reused before a background refresh (default 60000)."
},
"prefix": {
"label": "Footer Prefix",
"help": "Text before the percentages (default \"— Kimi:\")."
}
}
}

7
ai/kimi-quota-footer-plugin/package.json Normal file
View File

@@ -0,0 +1,7 @@
{
"name": "kimi-quota-footer",
"version": "1.0.0",
"type": "module",
"main": "index.js",
"private": true
}

248
ai/litellm-config.yaml Normal file
View File

@@ -0,0 +1,248 @@
model_list:
# ── oO aliases (used by ml/serving; see oO/CLAUDE.md AI stack) ──────────
- model_name: tip-generator
litellm_params:
model: ollama/qwen2.5:1.5b
api_base: http://host.docker.internal:11434
- model_name: embedder
litellm_params:
model: ollama/nomic-embed-text
api_base: http://host.docker.internal:11434
# kb#164: the ACTUAL embedder in use (§3a routing classifier for Auto
# Router v2) is bge-m3 on 11436, not the `embedder` alias above (which
# still points at nomic-embed-text on 11434 -- that alias is legacy/
# unused by the current stack, left as-is per kb#164 scope: add bge-m3,
# don't touch the mismatch beyond noting it). model-registry.yaml's
# `bge-m3` entry's litellm_model_name now matches this model_name.
- model_name: bge-m3
litellm_params:
model: ollama/bge-m3
api_base: http://host.docker.internal:11436
# kb#164: the `judge` alias (anthropic/claude-haiku-4-5, metered) was removed
# 2026-07-30 by alvis's decision. No ANTHROPIC_API_KEY was ever set in this
# container or .env, so it could not spend; it was kept only as a latent
# paid-fallback footgun. Per design §3a (no metered API by default), do not
# re-add a metered deployment without an explicit opt-in decision.
# Codex CLI agent. Replaces the retired `kimi-agent` container (2026-08-01,
# Kimi purge): that was the ONLY large-tier deployment behind LiteLLM, so
# deleting it outright would have silently degraded every large-tier request
# to the local 4B model via the fallbacks below. Repointed at the codex-backed
# adolf-llm wrapper (:8010, OpenAI-compatible, model id "adolf") instead of
# standing up a third CLI container with its own login.
- model_name: codex-agent
litellm_params:
model: openai/adolf
api_base: http://adolf-llm:8010/v1
api_key: dummy
# ── raw model exposure ─────────────────────────────────────────────────
- model_name: ollama/qwen3.5:4b
litellm_params:
model: ollama/qwen3.5:4b
api_base: http://host.docker.internal:11436
- model_name: ollama/qwen3:8b
litellm_params:
model: ollama/qwen3:8b
api_base: http://host.docker.internal:11436
- model_name: ollama/qwen2.5:1.5b
litellm_params:
model: ollama/qwen2.5:1.5b
api_base: http://host.docker.internal:11436
- model_name: ollama/qwen2.5:0.5b
litellm_params:
model: ollama/qwen2.5:0.5b
api_base: http://host.docker.internal:11436
- model_name: ollama/gemma3:4b
litellm_params:
model: ollama/gemma3:4b
api_base: http://host.docker.internal:11436
- model_name: ollama/gemma3:1b
litellm_params:
model: ollama/gemma3:1b
api_base: http://host.docker.internal:11435
- model_name: ollama/nomic-embed-text
litellm_params:
model: ollama/nomic-embed-text
api_base: http://host.docker.internal:11435
# OpenRouter free-tier models
- model_name: meta-llama/llama-3.3-70b-instruct:free
litellm_params:
model: openrouter/meta-llama/llama-3.3-70b-instruct:free
api_key: os.environ/OPENROUTER_API_KEY
- model_name: meta-llama/llama-3.2-3b-instruct:free
litellm_params:
model: openrouter/meta-llama/llama-3.2-3b-instruct:free
api_key: os.environ/OPENROUTER_API_KEY
- model_name: deepseek/deepseek-r1:free
litellm_params:
model: openrouter/deepseek/deepseek-r1:free
api_key: os.environ/OPENROUTER_API_KEY
- model_name: qwen/qwen3-4b:free
litellm_params:
model: openrouter/qwen/qwen3-4b:free
api_key: os.environ/OPENROUTER_API_KEY
- model_name: qwen/qwen3-coder:free
litellm_params:
model: openrouter/qwen/qwen3-coder:free
api_key: os.environ/OPENROUTER_API_KEY
- model_name: google/gemma-3-27b-it:free
litellm_params:
model: openrouter/google/gemma-3-27b-it:free
api_key: os.environ/OPENROUTER_API_KEY
- model_name: google/gemma-3-12b-it:free
litellm_params:
model: openrouter/google/gemma-3-12b-it:free
api_key: os.environ/OPENROUTER_API_KEY
- model_name: mistralai/mistral-small-3.1-24b-instruct:free
litellm_params:
model: openrouter/mistralai/mistral-small-3.1-24b-instruct:free
api_key: os.environ/OPENROUTER_API_KEY
- model_name: nvidia/nemotron-3-super-120b-a12b:free
litellm_params:
model: openrouter/nvidia/nemotron-3-super-120b-a12b:free
api_key: os.environ/OPENROUTER_API_KEY
- model_name: openai/gpt-oss-120b:free
litellm_params:
model: openrouter/openai/gpt-oss-120b:free
api_key: os.environ/OPENROUTER_API_KEY
- model_name: minimax/minimax-m2.5:free
litellm_params:
model: openrouter/minimax/minimax-m2.5:free
api_key: os.environ/OPENROUTER_API_KEY
- model_name: nousresearch/hermes-3-llama-3.1-405b:free
litellm_params:
model: openrouter/nousresearch/hermes-3-llama-3.1-405b:free
api_key: os.environ/OPENROUTER_API_KEY
# ── kb#128 (A2A-16): tier pools — alvis's "tier" routing mode ───────────
# target = constraint-set ("any large model"), not a specific backbone.
# Two litellm_params entries sharing one model_name = a LiteLLM deployment
# group; the router load-balances/fails-over across them. tier-large lists
# codex-agent FIRST so it's preferred, with local-small as the in-group
# failover partner -- this is also what the fallbacks: block below promotes
# to an explicit, auditable quota-429-degrades-to-local path (design §2
# theorem 2: quota-gated a(t)=0 -> park/degrade, never fail).
# tier-small mirrors model-registry.yaml's routing.tiers.small = [local-small].
- model_name: tier-small
litellm_params:
model: ollama/gemma3:4b
api_base: http://host.docker.internal:11436
- model_name: tier-large
litellm_params:
model: openai/adolf
api_base: http://adolf-llm:8010/v1
api_key: dummy
# ── kb#128: Auto Router v2 -- embedding-based classification on the LOCAL
# bge-m3 (design §3a/§3b: no classifier LLM, no API spend). Human-readable
# source of truth for these routes: openai/auto-router-routes.json (keep
# both in sync by hand -- see that file's _note for why).
#
# auto_router_config is INLINE JSON, not auto_router_config_path. This is
# the open Auto Router v2 embedding bug the task brief warned about,
# verified hands-on 2026-07-26 against litellm:main-latest: the _path
# loader (AutoRouter -> SemanticRouter.from_json) unconditionally builds a
# throwaway semantic_router encoder from scratch and demands a real
# provider API key even for a local model name like "bge-m3" --
# ValueError: "Expected API key via `api_key` parameter or
# `{TYPE}_API_KEY` environment variable." The inline-string loader never
# touches that code path (it just reads the `routes` key), and was
# confirmed end-to-end: real `litellm.embedding(model=ollama/bge-m3)`
# calls, zero metered spend, "hi there" -> ollama/gemma3:4b, a refactor/
# dependency-injection prompt -> kimi-agent.
#
# default_model is the free local tier -- an unmatched/low-confidence
# request degrades to free compute, never to a paid model.
- model_name: auto_router
litellm_params:
model: auto_router/semantic-v1
auto_router_default_model: ollama/gemma3:4b
auto_router_embedding_model: bge-m3
auto_router_config: >
{"routes": [
{"name": "ollama/gemma3:4b", "description": "Simple, short, low-stakes requests -- greetings, quick factual lookups, formatting, one-line questions.",
"utterances": ["hi", "hello", "what time is it", "what's the weather", "thanks", "what does this word mean", "summarize this in one sentence", "give me a quick yes or no", "format this as a list", "what is 2 plus 2"],
"score_threshold": 0.5},
{"name": "codex-agent", "description": "Complex reasoning, multi-step planning, coding, or anything needing tool use and deep context.",
"utterances": ["write a function that parses this log file and extracts errors", "refactor this class to use dependency injection", "think through the tradeoffs of these two architectures step by step", "debug why this docker container keeps crashing", "plan out the migration from cognee to hindsight across five tasks", "analyze this design document and find inconsistencies", "write a SQL query that joins these three tables and aggregates by month", "review this pull request for security issues"],
"score_threshold": 0.5}
]}
# ── kb#128: heuristic keyword/length fallback classifier ────────────────
# Auto Router v2 (2026-07-14) has an open embedding-related bug report
# (task #128 brief) -- LiteLLM's built-in ComplexityRouter is exactly the
# "keyword/length heuristic" fallback the brief calls for: pure regex/
# token-count scoring, <1ms, ZERO external calls (verified hands-on by
# reading router_strategy/complexity_router/complexity_router.py in the
# running litellm:main-latest image, 2026-07-26). Tiers are overridden
# here -- the package DEFAULT tiers point at gpt-4o/gpt-4o-mini/claude-
# sonnet (metered!), which would silently violate §3a if left as-is; every
# tier below maps only to already-governed non-metered deployments.
- model_name: complexity_router
litellm_params:
model: auto_router/complexity_router
complexity_router_default_model: ollama/gemma3:4b
complexity_router_config:
tiers:
SIMPLE: ollama/gemma3:4b
MEDIUM: ollama/gemma3:4b
COMPLEX: tier-large
REASONING: tier-large
litellm_settings:
success_callback: ["langfuse"]
failure_callback: ["langfuse"]
drop_params: true
# kb#148 (A2A-16): per-agent attribution + KB-task granularity in Langfuse.
# `user_api_key_alias` is populated automatically by LiteLLM from the
# calling virtual key (kb#128 provisioned one per agent with key_alias set
# to the agent id -- adolf/claude-coder/torgash/researcher), so every
# trace is tagged with its agent for free as soon as callers use their
# per-agent key. `agent`, `task-id` and `queue` are NOT auto-populated --
# callers must pass them explicitly as
# `extra_body={"metadata": {"agent": "...", "task-id": "...", "queue": "..."}}`
# (OpenAI-SDK-style) or the LiteLLM-native `metadata` field on the request;
# LiteLLM copies matching keys straight onto the Langfuse trace as tags.
# Wiring individual callers (adolf-llm, kimi-agent wrapper, thin workers)
# to actually send that metadata is separate follow-up work, out of this
# task's declared scope (docker-compose.yml + litellm-config.yaml only) --
# flagged in the kb#148 report as adjacent work.
langfuse_default_tags: ["agent", "task-id", "queue", "user_api_key_alias"]
fallbacks:
- deepseek/deepseek-r1:free: ["ollama/qwen3.5:4b"]
# kb#128 acceptance: "a forced 429 degrades cleanly". codex-agent is the
# only large deployment routed through LiteLLM today (the `codex`
# model-registry id is also called directly via the adolf-llm/
# hindsight-llm wrappers, outside LiteLLM by design -- see model-
# registry.yaml's codex entry). Both the raw deployment and the tier-large
# pool degrade to the free local-small model on 429/quota-exhaustion
# rather than failing the caller.
- codex-agent: ["ollama/gemma3:4b"]
- tier-large: ["tier-small"]
# auto_router's embedding path is the one with the open bug report
# (design §3a) -- if it errors, fail over to the zero-API-call heuristic
# classifier rather than the caller seeing an error.
- auto_router: ["complexity_router"]

162
ai/migrate-adolf-memory-banks.mjs Normal file
View File

@@ -0,0 +1,162 @@
#!/usr/bin/env node
/**
* One-time migration for kb#153 / A2A-21 (DESIGN-a2a-agents.md v2.1 §5b):
* splits the single legacy "adolf" Hindsight bank into the per-human bank
* layout the hindsight-memory plugin now expects (see that plugin's
* index.js / resolveBanksForSender).
*
* WHY A STRAIGHT COPY, NOT A alvis-vs-household CLASSIFIER:
* The live "adolf" bank's memories/list `context` field (chatLabel, set by
* the plugin's pre-kb#153 code) shows exactly ONE Matrix DM room across all
* 381 facts (`chat_qxknyifrguyghhvzdb_mtx_alogins_net` /
* `chat_room_qxknyifrguyghhvzdb_mtx_alogins_net`) plus a handful of
* non-Matrix contexts (`chat_webchat`, blank, and manual dev-seeded labels
* like "goals"/"work"/"kb#84 smoke test"). None of it is attributable to
* elizaveta (she was only just added to the DM allowlist) and there is no
* reliable signal in the data for "this fact is household, not personal" —
* that is a content judgment call, and DESIGN §5b's hard rule is that
* promotion from a private bank to the shared bank happens ONLY by the
* owning human's explicit action/approval task, never automatically. So the
* correct, safe migration is: everything goes to adolf-alvis (matching "the
* default is H's private bank"); nothing is auto-promoted to adolf-shared.
* alvis can promote individual household facts to adolf-shared later,
* through whatever explicit approval flow gets built for that (kb#153's
* report flags this as follow-up work, not done by this script).
*
* MECHANISM: Hindsight has no bulk "copy raw fact between banks" endpoint
* (verified against the live OpenAPI schema — /export and /import are bank
* TEMPLATE manifests: config/mental-models/directives, not memory data).
* The only write path is POST .../memories (RetainRequest), which re-runs
* server-side extraction on each item's `content` text. Since source items
* are already atomic single facts (Hindsight's own extraction output), this
* script feeds each fact's already-clean `text` back through retain into
* the destination bank, carrying over `context` and `timestamp` (`date`)
* for provenance. Re-extraction on an already-atomic fact is expected to
* reproduce it closely, not fragment it further, but this is a genuine
* re-processing step (a live LLM call per item via hindsight-llm), not a
* byte-for-byte copy — verify counts after running.
*
* SAFETY: dry-run by default. Requires --execute to write. Refuses to
* target the source bank as its own destination. Does NOT delete or modify
* the source bank — this script only ever reads it.
*
* Usage:
* node migrate-adolf-memory-banks.mjs --source adolf --dest adolf-alvis [--execute]
* node migrate-adolf-memory-banks.mjs --source adolf --dest adolf-alvis --async --execute
*
* Tested (kb#153) against a throwaway destination bank with the full live
* "adolf" source in dry-run + a partial real write, then that throwaway
* bank was deleted — this script has NOT been run against adolf-alvis. That
* final execution against the real destination is the live-migration step
* kb#153 explicitly hands off rather than running unattended.
*/
const args = process.argv.slice(2);
function argVal(name, def) {
const i = args.indexOf(`--${name}`);
return i !== -1 && args[i + 1] !== undefined ? args[i + 1] : def;
}
const flag = (name) => args.includes(`--${name}`);
const HINDSIGHT_URL = argVal("hindsight-url", "http://localhost:8888").replace(/\/+$/, "");
const SOURCE = argVal("source", "adolf");
const DEST = argVal("dest", "adolf-alvis");
const EXECUTE = flag("execute");
const ASYNC = flag("async");
const PAGE_SIZE = Number(argVal("page-size", "50"));
const DELAY_MS = Number(argVal("delay-ms", ASYNC ? "150" : "1500"));
// Testing/smoke-test aid only — omit to migrate everything.
const LIMIT = argVal("limit", undefined);
if (SOURCE === DEST) {
console.error(`Refusing: --source and --dest are both "${SOURCE}".`);
process.exit(1);
}
function bankPath(bank) {
return `${HINDSIGHT_URL}/v1/default/banks/${encodeURIComponent(bank)}`;
}
async function listAll(bank) {
const items = [];
let offset = 0;
for (;;) {
const res = await fetch(`${bankPath(bank)}/memories/list?limit=${PAGE_SIZE}&offset=${offset}`);
if (!res.ok) throw new Error(`list ${bank} failed: ${res.status}`);
const data = await res.json();
const batch = Array.isArray(data.items) ? data.items : [];
items.push(...batch);
offset += batch.length;
if (batch.length === 0 || offset >= (data.total ?? offset)) break;
}
return items;
}
async function retainOne(bank, item) {
const memoryItem = {
content: item.text,
context: item.context || "migrated_from_adolf",
timestamp: item.date || item.mentioned_at || undefined,
};
const res = await fetch(`${bankPath(bank)}/memories`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ async: ASYNC, items: [memoryItem] }),
});
if (!res.ok) {
const body = await res.text().catch(() => "");
throw new Error(`retain into ${bank} failed: ${res.status} ${body.slice(0, 200)}`);
}
return res.json();
}
function sleep(ms) {
return new Promise((r) => setTimeout(r, ms));
}
async function main() {
console.log(`Source: ${SOURCE} Dest: ${DEST} Mode: ${EXECUTE ? "EXECUTE" : "DRY-RUN"} async retain: ${ASYNC}`);
let items = await listAll(SOURCE);
console.log(`Fetched ${items.length} memory items from "${SOURCE}".`);
if (LIMIT) {
items = items.slice(0, Number(LIMIT));
console.log(`--limit set: only processing first ${items.length} items (testing aid).`);
}
if (items.length === 0) {
console.log("Nothing to migrate.");
return;
}
console.log("Sample of first 3 items to be migrated:");
for (const it of items.slice(0, 3)) {
console.log(` [${it.fact_type}] ${it.text.slice(0, 100)}${it.text.length > 100 ? "…" : ""} (context=${it.context || "-"})`);
}
if (!EXECUTE) {
console.log(`\nDry-run only — no writes made. Re-run with --execute to retain all ${items.length} items into "${DEST}".`);
return;
}
let ok = 0;
let failed = 0;
for (const [i, item] of items.entries()) {
try {
await retainOne(DEST, item);
ok++;
} catch (e) {
failed++;
console.error(` [${i + 1}/${items.length}] FAILED: ${e.message}`);
}
if ((i + 1) % 10 === 0 || i === items.length - 1) {
console.log(` ${i + 1}/${items.length} processed (ok=${ok}, failed=${failed})`);
}
await sleep(DELAY_MS);
}
console.log(`\nDone. ok=${ok} failed=${failed} out of ${items.length}.`);
console.log(`Verify with: GET ${bankPath(DEST)}/stats`);
}
main().catch((e) => {
console.error(e);
process.exit(1);
});

151
ai/migrate-adolf-state.sh Executable file
View File

@@ -0,0 +1,151 @@
#!/bin/bash
# Migration script for kb#219 — move Adolf's runtime state off the named
# Docker volume (openai_adolf-state) onto a host bind mount at
# /mnt/ssd/dbs/adolf/state, matching the convention every other Agap
# service already follows (hindsight, litellm, qdrant, langfuse, ...).
#
# SAFETY MODEL:
# - COPY ONLY. Never touches or deletes the source volume. The volume
# stays intact and usable as a rollback source until a human explicitly
# removes it (see rollback section in the compose-diff writeup /
# kb#219 report), long after this script has run and the container has
# been soak-tested on the new mount.
# - Dry-run by default. Pass --apply to actually copy.
# - Idempotent. Safe to re-run; re-copying onto an already-populated
# destination just refreshes it (cp -a overwrite-in-place). It will
# NOT delete files at the destination that were removed from the
# source between runs -- if that matters, wipe the dest dir yourself
# before re-running.
# - Verifies file counts + a sha256 manifest diff between source and
# destination before declaring success. Non-zero exit if they disagree.
# - Uses only `docker run` (alvis is in the `docker` group -- no `sudo`
# needed for container operations) to read the volume; never reads
# /var/lib/docker/volumes directly (root-only, 0700).
# - Does NOT create /mnt/ssd/dbs/adolf itself. That directory tree is
# root-owned (/mnt/ssd/dbs is 0755 root:root, same as every other
# service dir under it) and must be created + chowned by a human with
# sudo first -- see the paste-ready root block in the kb#219 report.
# This script aborts early with a clear message if the destination
# parent doesn't exist or isn't writable.
#
# USAGE:
# ./migrate-adolf-state.sh # dry run (default), prints plan
# ./migrate-adolf-state.sh --apply # actually copies + verifies
# ./migrate-adolf-state.sh --apply --dest /path/to/scratch --volume some-test-volume
# # point at a throwaway volume/dest for a trial run
#
# This script is NOT executed against live state as part of kb#219 prep.
# It has been dry-run tested and trial-run tested against a throwaway
# volume with a handful of files (see kb#219 report for the transcript).
set -euo pipefail
SRC_VOLUME="openai_adolf-state"
DEST_DIR="/mnt/ssd/dbs/adolf/state"
APPLY=0
while [ $# -gt 0 ]; do
case "$1" in
--apply) APPLY=1; shift ;;
--dest) DEST_DIR="$2"; shift 2 ;;
--volume) SRC_VOLUME="$2"; shift 2 ;;
-h|--help)
grep '^#' "$0" | sed 's/^#//'
exit 0
;;
*)
echo "Unknown argument: $1" >&2
exit 2
;;
esac
done
echo "== kb#219 adolf-state migration =="
echo "Source volume : $SRC_VOLUME"
echo "Dest dir : $DEST_DIR"
echo "Mode : $([ "$APPLY" -eq 1 ] && echo APPLY || echo DRY-RUN)"
echo
# --- 0. sanity: source volume exists ---
if ! docker volume inspect "$SRC_VOLUME" >/dev/null 2>&1; then
echo "ERROR: source volume '$SRC_VOLUME' does not exist." >&2
exit 1
fi
# --- 1. sanity: destination parent exists and is writable ---
DEST_PARENT="$(dirname "$DEST_DIR")"
if [ ! -d "$DEST_PARENT" ]; then
cat >&2 <<EOF
ERROR: $DEST_PARENT does not exist.
/mnt/ssd/dbs is root-owned; this directory must be created by a human
with sudo before this script can run. See the paste-ready root block in
the kb#219 report (creates /mnt/ssd/dbs/adolf/{state,config,personas},
chowned 1000:1000 to match the adolf container's node user).
EOF
exit 1
fi
if [ ! -w "$DEST_PARENT" ]; then
echo "ERROR: $DEST_PARENT exists but is not writable by $(whoami). Check ownership (should be chowned to your uid, or 1000:1000)." >&2
exit 1
fi
mkdir -p "$DEST_DIR"
# --- 2. source manifest (counts + sha256, computed inside a container) ---
echo "-- Computing source manifest (read-only mount of $SRC_VOLUME) --"
SRC_COUNT=$(docker run --rm -v "$SRC_VOLUME":/from:ro alpine sh -c "find /from -type f | wc -l")
echo "Source file count: $SRC_COUNT"
if [ "$APPLY" -eq 0 ]; then
echo
echo "[DRY RUN] Would copy $SRC_COUNT files from volume '$SRC_VOLUME' into $DEST_DIR,"
echo "[DRY RUN] then verify file count + sha256 manifest match."
echo "[DRY RUN] Re-run with --apply to actually copy."
exit 0
fi
# --- 3. copy (tar stream preserves ownership/perms across the boundary) ---
echo "-- Copying (tar stream, preserves perms/ownership) --"
docker run --rm \
-v "$SRC_VOLUME":/from:ro \
-v "$DEST_DIR":/to \
alpine sh -c "cd /from && tar cf - . | (cd /to && tar xf -)"
# --- 4. verify: file count ---
DEST_COUNT=$(docker run --rm -v "$DEST_DIR":/to:ro alpine sh -c "find /to -type f | wc -l")
echo "Dest file count: $DEST_COUNT"
if [ "$SRC_COUNT" != "$DEST_COUNT" ]; then
echo "ERROR: file count mismatch (source=$SRC_COUNT dest=$DEST_COUNT). NOT declaring success." >&2
exit 1
fi
# --- 5. verify: sha256 manifest diff ---
echo "-- Verifying sha256 manifests match --"
SRC_MANIFEST=$(mktemp)
DEST_MANIFEST=$(mktemp)
trap 'rm -f "$SRC_MANIFEST" "$DEST_MANIFEST"' EXIT
docker run --rm -v "$SRC_VOLUME":/from:ro alpine sh -c \
"cd /from && find . -type f -exec sha256sum {} \; | sort -k2" > "$SRC_MANIFEST"
docker run --rm -v "$DEST_DIR":/to:ro alpine sh -c \
"cd /to && find . -type f -exec sha256sum {} \; | sort -k2" > "$DEST_MANIFEST"
if diff -u "$SRC_MANIFEST" "$DEST_MANIFEST" > /tmp/adolf-state-migration.diff; then
echo "OK: manifests match byte-for-byte ($SRC_COUNT files)."
else
echo "ERROR: manifest mismatch, see /tmp/adolf-state-migration.diff" >&2
cat /tmp/adolf-state-migration.diff >&2
exit 1
fi
echo
echo "== Migration copy verified OK =="
echo "Source volume '$SRC_VOLUME' left untouched (not deleted, not modified)."
echo "Next steps (NOT done by this script -- human-supervised, see kb#219 report):"
echo " 1. Apply the docker-compose.yml bind-mount diff for the 'adolf' service."
echo " 2. docker compose -f ai/docker-compose.yml config -q # validate"
echo " 3. docker compose -f ai/docker-compose.yml up -d adolf # recreates container on new mount"
echo " 4. Verify: docker inspect adolf shows /mnt/ssd/dbs/adolf/state, not the volume;"
echo " Matrix session survives (no re-login), memory/config/persona intact."
echo " 5. Only after a soak period: docker volume rm $SRC_VOLUME"

279
ai/model-registry.yaml Normal file
View File

@@ -0,0 +1,279 @@
# Model registry — models are the scarce queued resource.
#
# Per DESIGN-a2a-agents.md v2.1 §2-3b (commit df2071d5), kanboard task #133
# (A2A-1). Version-controlled here; the "model plane" (§3) and the fabric's
# workers/routers read this data — they do not duplicate it. Lifecycle a(t)
# *probe mechanics* (QuotaProbe, GPUResidencyProbe, ...) live in
# kanboard/bin/kb_worker.py; this registry supplies the *parameters* those
# probes consume (commands, fields, thresholds, VRAM footprints).
#
# Scope constraint (alvis, §3a): NO METERED API BY DEFAULT. The workflow is
# Claude Code (a flat-subscription runtime -> agent registry #134, not here)
# + the Kimi wrapper + a local GPU embedder + a small weak local model. The
# governor arbitrates quota and GPU, not money. Any metered model below is
# `metered: true, opt_in_required: true` and carries no default route to it
# (see routing.metered_opt_in: [] at the bottom — empty means unreachable).
#
# Read with model_registry.py (same directory): resolve(), preload_check().
#
# ── Coverage vs litellm-config.yaml (kb#195, 2026-07-26 audit) ──────────
# Every model_name litellm-config.yaml defines must appear either as a
# `litellm_model_name` below or in this exclusion list. litellm_key_spec()
# default-denies anything not reachable via routing.tiers, so an excluded
# model stays ungoverned-but-inert until someone wires it up (add it here
# and to routing.tiers first).
#
# GOVERNED (present below):
# - ollama/gemma3:4b -> id: local-small (hot path: Hindsight LLM/
# consolidation/reflect all route here as of 2026-07-26)
# - judge -> id: paid-fallback (metered; see kb#164 for the fact that
# the no-metered-API constraint has no runtime enforcement yet)
# - codex-agent -> id: codex-agent (LiteLLM-routed large deployment; see
# below. Was kimi-agent + its own container until the 2026-08-01 purge)
# - bge-m3 -> id: bge-m3 (kb#164, 2026-07-26: wired into litellm-config
# .yaml pointing at ollama on 11436, the real embedder/routing
# classifier; litellm_model_name below updated from null to "bge-m3")
#
# INTENTIONAL EXCLUSIONS (not governed by this registry, by design):
# - tip-generator (ollama/qwen2.5:1.5b), embedder (ollama/nomic-embed-
# text): aliases consumed by the separate oO ml/serving project, not
# the a2a fabric. Tracked in oO/CLAUDE.md, not duplicated here.
# - Raw ollama/* passthrough exposures — ollama/qwen3.5:4b,
# ollama/qwen3:8b, ollama/qwen2.5:1.5b, ollama/qwen2.5:0.5b,
# ollama/gemma3:1b, ollama/nomic-embed-text — manual/dev-console
# access to the ollama instances for ad-hoc testing. No agent or
# fabric workflow is registered against them (grepped agent-registry
# .yaml and openai/*.py: no hits). Not in routing.tiers, so
# litellm_key_spec() grants no agent access to them either way.
# If one of these becomes a real dependency (as ollama/gemma3:4b
# did), give it its own registry entry at that point.
# - The 12 OpenRouter `*:free` models (meta-llama/llama-3.3-70b-
# instruct:free, meta-llama/llama-3.2-3b-instruct:free, deepseek/
# deepseek-r1:free, qwen/qwen3-4b:free, qwen/qwen3-coder:free,
# google/gemma-3-27b-it:free, google/gemma-3-12b-it:free, mistralai/
# mistral-small-3.1-24b-instruct:free, nvidia/nemotron-3-super-
# 120b-a12b:free, openai/gpt-oss-120b:free, minimax/minimax-m2.5:free,
# nousresearch/hermes-3-llama-3.1-405b:free) — human-facing manual-
# selection models (e.g.
# via Open WebUI), outside the agent fabric's model plane. Not
# referenced by any agent registry entry, not in routing.tiers, so
# resolve()/litellm_key_spec() never route an agent to them. Free
# tier, so this is not the kb#164 metered-enforcement gap — flag
# for a proper entry only if an agent workflow starts depending on
# one of these.
schema_version: 1
models:
# ── codex — main reasoning ─────────────────────────────────────────────
# Flat ChatGPT subscription via `codex login`, wrapped by two independent
# Codex-CLI containers (own creds volume each). Not behind LiteLLM today —
# callers hit the wrapper HTTP endpoints directly.
#
# Migrated from Kimi CLI 2026-07-31 for cost: this retires the separate
# Moonshot subscription in favour of the already-paid ChatGPT plan. The id
# changed `kimi` -> `codex`; routing.tiers below refers to it by id.
- id: codex
role: "main reasoning (adolf-llm / hindsight-llm Codex-CLI wrappers)"
litellm_model_name: null
endpoints:
- name: adolf-llm
purpose: "Adolf's conversational backbone"
url: "http://adolf-llm:8010"
# Route retained but returns HTTP 501 since the Codex migration —
# no machine-readable quota on this backend. See quota: below.
usage_url: "http://localhost:8010/usage"
- name: hindsight-llm
purpose: "Hindsight's structured-extraction LLM (HINDSIGHT_API_LLM_MODEL)"
url: "http://hindsight-llm:8012/v1"
model_name: "openai/hindsight-llm"
tier: large
context_tokens: 400000 # GPT-5-Codex context window; re-verify if the CLI's pinned model changes
tool_use_quality: high
lifecycle: quota-gated
quota:
# UNRESOLVED at the Codex migration (2026-07-31): the Kimi backend had a
# machine-readable managed-usage API that adolf-llm's /usage route
# normalized into these fields. Codex exposes no equivalent endpoint, so
# /usage now returns HTTP 501 and there is currently NO quota probe for
# this model. Governor quota-gating on `codex` is therefore blind — it
# will not see the ChatGPT plan's rate limits until a signal is found.
probe_command: null
windows: []
threshold_pct: 95
gpu_residency: null
cost_class: subscription # flat-rate, not metered — quota is the constraint, not spend
metered: false
opt_in_required: false
# ── codex-agent — the LiteLLM-routed large deployment ──────────────────
# Replaces the retired `kimi-agent` container (2026-08-01 Kimi purge). That
# container was the ONLY large-tier deployment behind LiteLLM, backing
# `tier-large`, the auto_router's complex-reasoning route and their
# fallbacks — removing it without a replacement would have silently degraded
# every large-tier request to the local 4B model. Rather than stand up a
# third CLI container with its own login, this now points at the existing
# codex-backed adolf-llm wrapper (:8010, model id "adolf").
#
# Same underlying ChatGPT subscription as `codex` above — the two ids differ
# only in call path (this one via LiteLLM, `codex` direct to the wrappers),
# so their quota is shared and neither has a probe.
- id: codex-agent
role: "LiteLLM-routed large deployment; proxies to the codex-backed adolf-llm wrapper"
litellm_model_name: "codex-agent" # openai/litellm-config.yaml model_list entry
endpoints:
- name: adolf-llm
url: "http://adolf-llm:8010/v1"
tier: large
context_tokens: 400000 # GPT-5-Codex context window; re-verify if the CLI's pinned model changes
tool_use_quality: high
lifecycle: quota-gated
quota:
probe_command: null # no machine-readable quota on the Codex backend — see `codex`
windows: []
threshold_pct: null
gpu_residency: null
cost_class: subscription
metered: false
opt_in_required: false
# ── local-small — the cheap tier ───────────────────────────────────────
# ollama/gemma3:4b on the GPU ollama instance. Already the live model for
# Hindsight consolidation/reflect (HINDSIGHT_API_CONSOLIDATION_LLM_MODEL /
# HINDSIGHT_API_REFLECT_LLM_MODEL, kb#88) and exposed via LiteLLM.
- id: local-small
role: "cheap tier — ollama small/weak local model (background extraction, consolidation, reflect)"
litellm_model_name: "ollama/gemma3:4b" # openai/litellm-config.yaml model_list entry
endpoints:
- name: ollama-direct
url: "http://host.docker.internal:11436"
- name: via-litellm
url: "http://litellm:4000/v1"
tier: small
context_tokens: 8192 # gemma3:4b default ctx; re-verify with `ollama show gemma3:4b` if raised
tool_use_quality: low
lifecycle: always-on
quota: null
gpu_residency:
vram_mb: 4000 # approx measured footprint, within the shared 8GB card (see gpu_residency_policy below)
never_evict: false # evictable — a bigger model may push it out; that's a silent regression to catch, not prevent here
co_residency_group: interactive-local
cost_class: free
metered: false
opt_in_required: false
# ── bge-m3 — embedder + routing classifier ─────────────────────────────
# Never-evict: it's both Hindsight's recall embedder AND (design §3a) the
# embedding model LiteLLM Auto Router's semantic-router classifier will
# use for tier/complexity routing — losing it degrades both recall AND
# routing at once.
- id: bge-m3
role: "embedder — also the routing classifier (§3a, LiteLLM Auto Router / semantic-router)"
litellm_model_name: "bge-m3" # kb#164, 2026-07-26: wired into litellm-config.yaml (ollama/bge-m3 @ 11436) -- was null (unwired gap)
endpoints:
- name: ollama-direct
url: "http://host.docker.internal:11436"
openai_compatible_path: "/v1/embeddings"
tier: small
context_tokens: 8192
tool_use_quality: "n/a" # embedder, not a chat/tool-use model
lifecycle: always-on
quota: null
gpu_residency:
vram_mb: 1200
never_evict: true
co_residency_group: interactive-local
cost_class: free
metered: false
opt_in_required: false
# ── tei-reranker — interactive-critical, never-evict ───────────────────
# Not an LLM (cross-encoder rerank sidecar for Hindsight recall, kb#87)
# but carries the same GPU-residency stakes as bge-m3, so it's tracked
# here rather than invented as a separate registry class.
- id: tei-reranker
role: "cross-encoder reranker sidecar for Hindsight recall (interactive-critical)"
litellm_model_name: null # TEI-compatible /rerank API; not routed through LiteLLM
endpoints:
- name: tei-reranker
url: "http://tei-reranker:80" # host-published :8014
tier: small
context_tokens: null
tool_use_quality: "n/a"
lifecycle: always-on
quota: null
gpu_residency:
vram_mb: 1000
never_evict: true
co_residency_group: interactive-local
cost_class: free
metered: false
opt_in_required: false
# ── paid-fallback — optional, opt-in only ──────────────────────────────
# §3a: "Any paid deployment in the LiteLLM config must be explicitly
# enabled per agent via its virtual key; nothing routes to a metered
# model implicitly." routing.metered_opt_in below is the enforcement
# point: empty list = no caller has opted in = unreachable by resolve().
- id: paid-fallback
role: "optional metered fallback (e.g. Haiku) — disabled by default"
litellm_model_name: "judge" # litellm-config.yaml's existing entry (anthropic/claude-haiku-4-5-20251001)
endpoints: []
tier: large
context_tokens: 200000
tool_use_quality: high
lifecycle: cost-gated
quota:
probe_command: null # wire to a LiteLLM virtual-key budget probe (kb_worker.py BudgetProbe) once a caller opts in
windows: []
threshold_pct: null
gpu_residency: null
cost_class: metered
metered: true
opt_in_required: true
# ── GPU residency policy (§3b) ──────────────────────────────────────────
# "a local model's a(t) is not 1": a(t) = f(VRAM headroom). Never-evict
# models are excluded from eviction math entirely — their VRAM is a fixed
# reservation. Everything else in a co-residency group must fit in what's
# left. preload_check semantics documented here; implemented generically
# in model_registry.py so it reads this data instead of hardcoding numbers.
gpu_residency_policy:
card: "GTX 1070, 8192 MB (single GPU today; §8 — more GPUs become a placement problem, same policy, more slots)"
total_vram_mb: 8192
# Measured 2026-07-21: bge-m3 + gemma3:4b + tei-reranker ~= 6.2/8 GB.
# Loading something bigger than local-small's footprint on top evicts
# tei-reranker (LRU-ish ollama/torch behavior) -> silent recall-latency
# regression. This is the regression the pre-load check exists to catch.
measured_baseline_mb: 6200
never_evict_ids: [bge-m3, tei-reranker]
co_residency_groups:
interactive-local: [bge-m3, tei-reranker, local-small]
preload_check:
description: >
Before a worker pulls a candidate model onto the GPU it must pass
this check (see model_registry.py:preload_check): reserve every
never_evict model's vram_mb unconditionally, subtract whatever else
is currently resident, and require the candidate's own vram_mb to
fit in what's left of total_vram_mb. A failing check means "park,
don't load" — never silently evict a never-evict model.
# ── routing ───────────────────────────────────────────────────────────────
# Tier pools a caller can ask for without naming a model (design §2: "target
# = constraint-set"). metered_opt_in lists the virtual keys that have
# explicitly opted into paid-fallback; empty = no metered model is reachable
# by anyone, satisfying the "no metered API by default" acceptance bar.
routing:
tiers:
small: [local-small]
# paid-fallback listed as a large-tier candidate AFTER codex so resolve()
# can fail over to it when codex's a(t)=0 (quota parked) — but only for a
# caller that both passes allow_metered=True AND appears in
# metered_opt_in below. With metered_opt_in empty (the shipped default)
# resolve() skips it unconditionally, so it stays unreachable.
#
# NB: with the Codex migration there is no quota probe (see the `codex`
# entry), so a(t) never reads as parked and this failover cannot trigger
# on quota today.
large: [codex, paid-fallback]
metered_opt_in: [] # e.g. ["agent:torgash"] once a human explicitly opts a specific virtual key in

301
ai/model_registry.py Executable file
View File

@@ -0,0 +1,301 @@
#!/usr/bin/env python3
"""model_registry — reads model-registry.yaml (kb#133, A2A-1).
Per DESIGN-a2a-agents.md v2.1 §2-3b: the model registry is data, not logic.
a(t) probe *mechanics* (QuotaProbe, GPUResidencyProbe, ...) already live in
kanboard/bin/kb_worker.py — this module does not reimplement them. It gives
callers two things instead:
* resolve(tier) — "an available model for tier X" without the
caller naming a model. Structural availability
(lifecycle, metered opt-in) is decided here from
registry data; live a(t) truth (is the quota
window open right now, is the GPU actually free)
is decided by an optional `probe_check` callback
the caller supplies (e.g. wired to kb_worker's
Probe classes via to_probe_config()).
* preload_check(...) — the §3b GPU pre-load check, expressed purely from
registry numbers (never-evict reservations +
candidate footprint) plus a headroom figure the
caller supplies. It does not shell nvidia-smi
itself — kb_worker.GPUResidencyProbe (or
`nvidia-smi` directly) is the live-read path;
this stays pure/testable.
Usage (library):
from model_registry import load_registry, resolve, to_probe_config, preload_check
reg = load_registry()
model = resolve(reg, tier="large") # -> the "codex" entry
cfg = to_probe_config(reg, "codex") # -> kb_worker probe config dict
ok, reason = preload_check(reg, "local-small", headroom_mb=1900)
Usage (CLI, for manual verification):
./model_registry.py resolve --tier large
./model_registry.py resolve --tier large --allow-metered --opted-in agent:torgash
./model_registry.py probe-config --id kimi
./model_registry.py preload-check --id local-small --headroom-mb 1900
./model_registry.py preload-check --id local-small --live # shells nvidia-smi
./model_registry.py list
"""
import argparse
import json
import os
import subprocess
import sys
import yaml
HERE = os.path.dirname(os.path.abspath(__file__))
DEFAULT_REGISTRY_PATH = os.path.join(HERE, "model-registry.yaml")
class RegistryError(Exception):
pass
def load_registry(path=None):
"""Load and lightly validate model-registry.yaml."""
path = path or DEFAULT_REGISTRY_PATH
with open(path) as f:
reg = yaml.safe_load(f)
if not reg or "models" not in reg:
raise RegistryError(f"{path}: missing top-level 'models' list")
ids = [m["id"] for m in reg["models"]]
if len(ids) != len(set(ids)):
raise RegistryError(f"{path}: duplicate model ids in {ids}")
return reg
def get_model(registry, model_id):
for m in registry["models"]:
if m["id"] == model_id:
return m
raise RegistryError(f"unknown model id: {model_id!r}")
# ---------------------------------------------------------------------------
# resolve — "an available model for tier X" without the caller naming one.
# ---------------------------------------------------------------------------
def resolve(registry, tier, allow_metered=False, opted_in_key=None, probe_check=None):
"""Return the first model in `tier`'s pool that is structurally usable,
and (if probe_check is given) currently available.
Structural filter (from registry data alone):
- candidate must be listed under routing.tiers[tier]
- a metered model is only a candidate at all when the CALLER passes
allow_metered=True AND opted_in_key appears in routing.metered_opt_in
(§3a: "no metered API by default" — an empty metered_opt_in list, the
shipped default, makes every metered model structurally unreachable
regardless of allow_metered).
Live filter (optional): probe_check(model_dict) -> bool. Wire this to
kb_worker's Probe.available() (via to_probe_config below) when the
caller wants real a(t) truth instead of just structural eligibility.
"""
pools = registry.get("routing", {}).get("tiers", {})
if tier not in pools:
raise RegistryError(f"unknown tier: {tier!r} (have: {sorted(pools)})")
opted_in = set(registry.get("routing", {}).get("metered_opt_in", []) or [])
candidates = []
for model_id in pools[tier]:
m = get_model(registry, model_id)
if m.get("metered"):
if not allow_metered:
continue
if not m.get("opt_in_required", True):
# Registry says this metered model doesn't need opt-in — treat
# as a data error rather than silently routing to it.
raise RegistryError(
f"model {model_id!r} is metered but opt_in_required=false; "
"fix the registry entry, this helper will not assume implicit access"
)
if opted_in_key is None or opted_in_key not in opted_in:
continue
candidates.append(m)
for m in candidates:
if probe_check is None or probe_check(m):
return m
raise RegistryError(
f"no available model for tier={tier!r} "
f"(allow_metered={allow_metered}, opted_in_key={opted_in_key!r}); "
f"checked candidates: {[m['id'] for m in candidates] or pools[tier]}"
)
# ---------------------------------------------------------------------------
# to_probe_config — bridges registry quota data into kb_worker's probe cfg
# shape (kanboard/bin/kb_worker.py PROBE_BUILDERS), so probes read registry
# numbers instead of the registry re-implementing probe logic.
# ---------------------------------------------------------------------------
def to_probe_config(registry, model_id):
"""Return a dict matching kb_worker.py's `build_probe(cfg)` input shape
for `model_id`'s lifecycle. Raises if the model has no probe-relevant
lifecycle (e.g. cost-gated with no probe_command wired yet)."""
m = get_model(registry, model_id)
lifecycle = m["lifecycle"]
if lifecycle == "always-on":
return {"type": "always_on"}
if lifecycle == "quota-gated":
q = m.get("quota") or {}
windows = q.get("windows") or []
if not windows:
raise RegistryError(f"{model_id}: quota-gated but no quota.windows configured")
# kb_worker's QuotaProbe checks one field; the tightest (first-to-hit)
# window in practice is the short one — default to the first entry,
# callers needing multi-window gating build one probe per window.
window = windows[0]
return {
"type": "quota",
"command": q["probe_command"],
"field": window["field"],
"threshold_pct": q.get("threshold_pct", 95),
}
if lifecycle == "cost-gated":
q = m.get("quota") or {}
if not q.get("probe_command"):
raise RegistryError(
f"{model_id}: cost-gated but no budget probe wired yet "
"(opt-in path incomplete — see registry comment)"
)
return {
"type": "budget",
"command": q["probe_command"],
"field": q["field"],
"limit": q["limit"],
}
if lifecycle == "on-demand":
ep = (m.get("endpoints") or [{}])[0]
if not ep.get("health_url"):
raise RegistryError(f"{model_id}: on-demand but no endpoint.health_url configured")
return {"type": "on_demand", "url": ep["health_url"]}
raise RegistryError(f"{model_id}: unknown lifecycle {lifecycle!r}")
# ---------------------------------------------------------------------------
# preload_check — §3b GPU pre-load check, pure registry-data math. The live
# VRAM headroom READ is the caller's job (kb_worker.GPUResidencyProbe or
# nvidia-smi directly) — see live_headroom_mb() below for a thin convenience
# wrapper used only by this module's own CLI, not by the check itself.
# ---------------------------------------------------------------------------
def preload_check(registry, candidate_id, headroom_mb, resident_ids=None):
"""Would loading `candidate_id` fit, given `headroom_mb` free VRAM right
now (as reported by a live probe) and `resident_ids` already loaded?
Never-evict models are never subtracted from headroom by a caller in the
first place (their footprint is a standing reservation baked into any
correct live headroom read) — this function just re-asserts that policy
from registry data: if `candidate_id` itself is never-evict, it always
passes (it's not something a worker "loads speculatively" and might be
told to skip); anything else must fit in the reported headroom.
"""
policy = registry.get("gpu_residency_policy") or {}
m = get_model(registry, candidate_id)
gr = m.get("gpu_residency")
if not gr:
return True, f"{candidate_id} has no gpu_residency entry (not a GPU-resident model)"
if gr.get("never_evict"):
return True, f"{candidate_id} is in the never-evict set — always resident by policy"
required_mb = gr["vram_mb"]
never_evict_ids = set(policy.get("never_evict_ids", []))
resident_ids = set(resident_ids or [])
# Sanity: if the live headroom read already accounts for never-evict
# reservations (the expected contract — see kb_worker.GPUResidencyProbe's
# never_evict_reserved_mb param), this is just a straight comparison.
# If a caller passes raw total-minus-used instead, warn via the reason
# string rather than silently under/over-reserving.
reserved_hint = sum(
get_model(registry, mid)["gpu_residency"]["vram_mb"]
for mid in never_evict_ids
if mid not in resident_ids # already counted as "used" if resident_ids says so
)
ok = headroom_mb >= required_mb
reason = (
f"headroom={headroom_mb}MB required={required_mb}MB "
f"(never-evict reserve expected already netted out by the caller's probe: "
f"~{reserved_hint}MB across {sorted(never_evict_ids)})"
)
return ok, reason
def live_headroom_mb(never_evict_reserved_mb=0):
"""Convenience for manual CLI checks only — NOT used by preload_check()
itself. Shells nvidia-smi the same way kb_worker.GPUResidencyProbe does."""
out = subprocess.run(
["nvidia-smi", "--query-gpu=memory.used,memory.total", "--format=csv,noheader,nounits"],
capture_output=True, text=True, timeout=5, check=True,
).stdout.strip().splitlines()[0]
used, total = (int(x) for x in out.split(","))
return total - used - never_evict_reserved_mb
# ---------------------------------------------------------------------------
# CLI — manual verification only, not part of the library contract.
# ---------------------------------------------------------------------------
def main():
ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
ap.add_argument("--registry", default=None, help="path to model-registry.yaml (default: sibling file)")
sub = ap.add_subparsers(dest="cmd", required=True)
p = sub.add_parser("resolve")
p.add_argument("--tier", required=True)
p.add_argument("--allow-metered", action="store_true")
p.add_argument("--opted-in", default=None, help="virtual key claimed to be opted in")
p = sub.add_parser("probe-config")
p.add_argument("--id", required=True)
p = sub.add_parser("preload-check")
p.add_argument("--id", required=True)
p.add_argument("--headroom-mb", type=float, default=None)
p.add_argument("--live", action="store_true", help="read live headroom via nvidia-smi instead of --headroom-mb")
p.add_argument("--resident", action="append", default=[], help="repeatable: id already resident")
sub.add_parser("list")
args = ap.parse_args()
reg = load_registry(args.registry)
try:
if args.cmd == "resolve":
m = resolve(reg, args.tier, allow_metered=args.allow_metered, opted_in_key=args.opted_in)
print(json.dumps(m, indent=2))
elif args.cmd == "probe-config":
print(json.dumps(to_probe_config(reg, args.id), indent=2))
elif args.cmd == "preload-check":
headroom = args.headroom_mb
if args.live:
policy = reg.get("gpu_residency_policy") or {}
reserved = sum(get_model(reg, mid)["gpu_residency"]["vram_mb"]
for mid in policy.get("never_evict_ids", []))
headroom = live_headroom_mb(never_evict_reserved_mb=reserved)
if headroom is None:
raise RegistryError("preload-check needs --headroom-mb or --live")
ok, reason = preload_check(reg, args.id, headroom, resident_ids=args.resident)
print(json.dumps({"ok": ok, "reason": reason}))
sys.exit(0 if ok else 1)
elif args.cmd == "list":
for m in reg["models"]:
print(f"{m['id']:16} tier={m['tier']:6} lifecycle={m['lifecycle']:13} "
f"metered={m['metered']} role={m['role']}")
except RegistryError as exc:
print(f"error: {exc}", file=sys.stderr)
sys.exit(2)
if __name__ == "__main__":
main()

12
ai/openclaw-tools/Dockerfile Normal file
View File

@@ -0,0 +1,12 @@
FROM node:22-slim
WORKDIR /app
COPY package.json ./
RUN npm install --omit=dev
COPY server.js ./
EXPOSE 8020
ENTRYPOINT ["node", "/app/server.js"]

11
ai/openclaw-tools/package.json Normal file
View File

@@ -0,0 +1,11 @@
{
"name": "openclaw-tools-bridge",
"private": true,
"version": "1.0.0",
"description": "MCP bridge exposing a minimal slice of the OpenClaw gateway's agent tools (message/cron/nodes/browser) over Streamable HTTP, for Kimi CLI sessions (adolf-llm) via shared-mcp.json.",
"main": "server.js",
"dependencies": {
"@modelcontextprotocol/sdk": "^1.29.0",
"zod": "^4.0.0"
}
}

245
ai/openclaw-tools/server.js Normal file
View File

@@ -0,0 +1,245 @@
// openclaw-tools bridge (Adolf P5) — a minimal MCP server that proxies a
// small slice of the OpenClaw gateway's agent tools (message / cron / nodes /
// browser) to Kimi CLI sessions, over MCP Streamable HTTP.
//
// Why a bridge instead of pointing Kimi straight at the gateway: the gateway
// only speaks its own WS/HTTP protocol (`/tools/invoke`, docs/gateway/
// tools-invoke-http-api.md in the openclaw source), not MCP. This process is
// the thin translation layer: MCP tool call in, `POST {gateway}/tools/invoke`
// out, gateway JSON result back as MCP tool content.
//
// Gate (P6 dependency, verified against the openclaw source docs at
// /home/alvis/adolf/docs/gateway/tools-invoke-http-api.md): the gateway's
// `/tools/invoke` HTTP surface hard-denies `cron`, `gateway`, and `nodes` by
// default, and those three stay owner-only even if `gateway.tools.allow`
// re-enables them for non-owner callers. Shared-secret bearer auth (what this
// bridge uses) IS treated as a full owner/operator turn, so once P6 adds
// `gateway.tools.allow: ["cron", "nodes"]` (or similar) to the running
// adolf/openclaw.json, cron_create/cron_list/nodes_invoke below start working
// with no change here. `message` and `browser` are NOT in that default deny
// list, so message_send should work as soon as the gateway is up and its
// normal `tools.*` policy allows those tools for the caller — no special P6
// HTTP-deny override needed for those two.
//
// Until the `adolf` gateway container is actually configured and running
// (P6), every proxied call below will fail at the fetch() step (connection
// refused) — that is expected for P5 and is NOT a bug in this bridge. What
// P5 verifies is the MCP handshake + tool schemas themselves.
const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');
const { StreamableHTTPServerTransport } = require('@modelcontextprotocol/sdk/server/streamableHttp.js');
const { createMcpExpressApp } = require('@modelcontextprotocol/sdk/server/express.js');
const { z } = require('zod');
const PORT = Number(process.env.PORT) || 8020;
const HOST = '0.0.0.0';
// Gateway base URL: the `adolf` OpenClaw gateway container on the compose
// network (docker-compose.yml: ports 18789/18790, service name `adolf`).
const GATEWAY_BASE_URL = (process.env.OPENCLAW_GATEWAY_URL || 'http://adolf:18789').replace(/\/+$/, '');
// Shared-secret operator token. Accept either env name: OPENCLAW_GATEWAY_TOKEN
// is the name the `adolf` service reads OPENCLAW_GATEWAY_TOKEN from internally
// (docker-compose.yml sets it from ${ADOLF_GATEWAY_TOKEN:-}), so callers may
// reasonably set either var name for this bridge.
const GATEWAY_TOKEN = process.env.OPENCLAW_GATEWAY_TOKEN || process.env.ADOLF_GATEWAY_TOKEN || '';
const GATEWAY_TIMEOUT_MS = 20_000;
// ---------------------------------------------------------------------------
// Gateway proxy. POSTs to /tools/invoke (docs/gateway/tools-invoke-http-api.md):
// { tool, action, args, sessionKey?, agentId?, idempotencyKey?, dryRun? }
// `action` is optional and merges into args.action gateway-side when the
// tool schema supports it; we always send it at the top level to match the
// documented shape exactly.
// Returns MCP tool-result content. Network/HTTP/gateway errors are surfaced
// as `isError: true` tool content rather than thrown, so a dead/unconfigured
// gateway (expected pre-P6) never breaks the MCP connection itself.
async function invokeGatewayTool(tool, action, args) {
const body = { tool, args: args || {} };
if (action !== undefined) body.action = action;
let resp;
try {
resp = await fetch(`${GATEWAY_BASE_URL}/tools/invoke`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
...(GATEWAY_TOKEN ? { Authorization: `Bearer ${GATEWAY_TOKEN}` } : {}),
},
body: JSON.stringify(body),
signal: AbortSignal.timeout(GATEWAY_TIMEOUT_MS),
});
} catch (err) {
return {
isError: true,
content: [{
type: 'text',
text: `openclaw gateway unreachable at ${GATEWAY_BASE_URL} (tool=${tool}): ${err.message || err}`,
}],
};
}
const text = await resp.text();
let payload;
try { payload = JSON.parse(text); } catch { payload = { raw: text }; }
if (!resp.ok) {
const err = payload && payload.error;
const detail = err ? `${err.type || resp.status}: ${err.message || ''}` : `HTTP ${resp.status}`;
return {
isError: true,
content: [{ type: 'text', text: `gateway tool "${tool}" failed (${resp.status}): ${detail}` }],
};
}
return { content: [{ type: 'text', text: JSON.stringify(payload.result ?? payload, null, 2) }] };
}
// ---------------------------------------------------------------------------
function buildServer() {
const server = new McpServer({ name: 'openclaw-tools', version: '1.0.0' });
// --- send-to-channel -------------------------------------------------
server.registerTool('message_send', {
description:
'Send a message to a chat channel through the OpenClaw gateway (Discord, Matrix, Telegram, Slack, WhatsApp, etc). ' +
'Proxies to the gateway "message" agent tool, action "send".',
inputSchema: {
to: z.string().describe(
'Delivery target. Format depends on channel: "!room:server" or "@user:server" (Matrix), ' +
'"channel:<id>" or "user:<id>" (Discord/Slack), "@username" or chat id (Telegram), E.164 (WhatsApp).',
),
channel: z.string().optional().describe(
'Channel provider id (matrix, telegram, discord, slack, whatsapp, ...). Required if more than one channel is configured.',
),
message: z.string().optional().describe('Message text.'),
media: z.string().optional().describe('Local path or URL of an image/audio/video/document to attach.'),
replyTo: z.string().optional().describe('Message id to reply to.'),
threadId: z.string().optional().describe('Thread or forum-topic id.'),
account: z.string().optional().describe('Account id, when the channel has multiple configured accounts.'),
},
}, async ({ to, channel, message, media, replyTo, threadId, account }) => {
const args = { to };
if (channel !== undefined) args.channel = channel;
if (message !== undefined) args.message = message;
if (media !== undefined) args.media = media;
if (replyTo !== undefined) args.replyTo = replyTo;
if (threadId !== undefined) args.threadId = threadId;
if (account !== undefined) args.account = account;
return invokeGatewayTool('message', 'send', args);
});
// --- cron / reminders --------------------------------------------------
const CRON_DENY_NOTE =
'NOTE: the gateway HTTP /tools/invoke surface hard-denies the "cron" tool by default ' +
'(persistent-automation control plane, owner-only) — this call 404s until the gateway operator ' +
'adds "cron" to gateway.tools.allow (Adolf P6). Field names mirror `openclaw cron <cmd>` CLI flags ' +
'in camelCase and are forwarded near-verbatim; treat gateway 400 error messages as the ground truth ' +
'for exact accepted fields.';
server.registerTool('cron_create', {
description: `Schedule a one-shot reminder or recurring job on the OpenClaw gateway cron scheduler. ${CRON_DENY_NOTE}`,
inputSchema: {
name: z.string().optional().describe('Job name.'),
at: z.string().optional().describe('One-shot: ISO 8601 timestamp or relative offset, e.g. "20m".'),
every: z.string().optional().describe('Recurring fixed interval, e.g. "10m", "1h", "1d".'),
cron: z.string().optional().describe('Recurring 5- or 6-field cron expression.'),
tz: z.string().optional().describe('IANA timezone for "at"/"cron" (default: gateway host tz / UTC).'),
session: z.enum(['main', 'isolated', 'current']).optional().describe('Execution style (default "main").'),
systemEvent: z.string().optional().describe('System-event text payload (no model call).'),
message: z.string().optional().describe('Agent-turn prompt payload (model-backed run).'),
wake: z.enum(['now', 'next-heartbeat']).optional().describe('Main-session wake mode.'),
deleteAfterRun: z.boolean().optional().describe('Auto-delete after a successful one-shot run.'),
announce: z.boolean().optional().describe('Deliver the result to a chat channel.'),
channel: z.string().optional().describe('Announce delivery channel.'),
to: z.string().optional().describe('Announce delivery target.'),
},
}, async (params) => invokeGatewayTool('cron', 'create', params));
server.registerTool('cron_list', {
description: `List jobs on the OpenClaw gateway cron scheduler. ${CRON_DENY_NOTE}`,
inputSchema: {
compact: z.boolean().optional().describe('Compact summaries (id, name, enabled, nextRunAtMs, ...). Default true.'),
},
}, async ({ compact }) => invokeGatewayTool('cron', 'list', { compact: compact ?? true }));
// --- nodes --------------------------------------------------------------
server.registerTool('nodes_invoke', {
description:
'Invoke a command on a paired OpenClaw node (camera, canvas, location, notify, screen record, etc). ' +
'NOTE: the gateway HTTP /tools/invoke surface hard-denies the "nodes" tool by default (node command ' +
'relay can reach system.run on paired hosts, owner-only) — this call 404s until the gateway operator ' +
'adds "nodes" to gateway.tools.allow (Adolf P6). `system.run`/`system.run.prepare` are blocked on this ' +
'path regardless; `system.which` is allowed.',
inputSchema: {
node: z.string().describe('Node id, display name, or IP.'),
command: z.string().describe('Node command, e.g. "canvas.eval", "location.get", "notify", "system.which".'),
params: z.record(z.string(), z.unknown()).optional().describe('Command-specific parameters object.'),
idempotencyKey: z.string().optional().describe('Optional idempotency key for the invoke.'),
},
}, async ({ node, command, params, idempotencyKey }) => {
const args = { node, command, params: params || {} };
if (idempotencyKey !== undefined) args.idempotencyKey = idempotencyKey;
return invokeGatewayTool('nodes', 'invoke', args);
});
// --- browser --------------------------------------------------------------
server.registerTool('browser_invoke', {
description:
'Drive the OpenClaw gateway "browser" tool (a headless Chromium the agent controls). ' +
'TOP-LEVEL actions (the "action" arg): status, start, stop, profiles, tabs, open, navigate, ' +
'snapshot, screenshot, act, console, dialog, pdf, upload. ' +
'IMPORTANT: there is NO top-level "click"/"type"/"fill"/"evaluate" action — ALL page ' +
'interactions go through action="act" with args={kind, ref, ...}. ' +
'Typical flow: action="open" {url} -> action="snapshot" to get element refs (e.g. "e59") -> ' +
'action="act" to interact. Interaction args examples: ' +
'type text -> {kind:"type", ref:"e59", text:"hello"}; ' +
'click -> {kind:"click", ref:"e33"}; ' +
'fill -> {kind:"fill", ref:"e65", text:"secret"}; ' +
'also kind can be hover|select|press|scrollIntoView|drag|evaluate. ' +
'Refs go stale after navigation/DOM change — if an action reports "ref not found", re-snapshot.',
inputSchema: {
action: z.string().describe('Top-level browser action: open | navigate | snapshot | screenshot | act | tabs | status | start | stop | profiles | console | dialog | pdf | upload. Use "act" for ALL page interactions (click/type/fill), never "click"/"type" directly.'),
args: z.record(z.string(), z.unknown()).optional().describe('Action params. action="open": {url, label?}. action="act": {kind:"type"|"click"|"fill"|"hover"|"select"|..., ref:"eN" from snapshot, text:"..." for type/fill}. action="snapshot": {refs:"aria"} for stable refs.'),
},
}, async ({ action, args }) => invokeGatewayTool('browser', action, args || {}));
return server;
}
// ---------------------------------------------------------------------------
// Stateless Streamable HTTP transport (mirrors the MCP SDK's own
// examples/server/simpleStatelessStreamableHttp.js): one McpServer + one
// transport per request, no session persistence needed for these tools.
const app = createMcpExpressApp({ host: HOST });
app.get('/health', (_req, res) => res.status(200).json({ ok: true }));
app.post('/mcp', async (req, res) => {
const server = buildServer();
try {
const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
await server.connect(transport);
await transport.handleRequest(req, res, req.body);
res.on('close', () => {
transport.close();
server.close();
});
} catch (err) {
console.error('error handling MCP request:', err);
if (!res.headersSent) {
res.status(500).json({ jsonrpc: '2.0', error: { code: -32603, message: 'internal server error' }, id: null });
}
}
});
app.get('/mcp', (_req, res) => {
res.writeHead(405).end(JSON.stringify({ jsonrpc: '2.0', error: { code: -32000, message: 'method not allowed' }, id: null }));
});
app.delete('/mcp', (_req, res) => {
res.writeHead(405).end(JSON.stringify({ jsonrpc: '2.0', error: { code: -32000, message: 'method not allowed' }, id: null }));
});
app.listen(PORT, HOST, () => {
console.log(`openclaw-tools bridge listening on ${HOST}:${PORT} (gateway: ${GATEWAY_BASE_URL})`);
});

18
ai/pipecat/Dockerfile Normal file
View File

@@ -0,0 +1,18 @@
FROM python:3.11-slim
RUN apt-get update && apt-get install -y --no-install-recommends gcc g++ && rm -rf /var/lib/apt/lists/*
# CPU torch first — prevents silero-vad from pulling in the CUDA variant
RUN pip install --no-cache-dir torch --index-url https://download.pytorch.org/whl/cpu
RUN pip install --no-cache-dir \
"pipecat-ai[openai,livekit,silero]" \
"livekit-api" \
fastapi \
"uvicorn[standard]"
WORKDIR /app
COPY . .
EXPOSE 8882
CMD ["uvicorn", "bot:app", "--host", "0.0.0.0", "--port", "8882"]

228
ai/pipecat/bot.py Normal file
View File

@@ -0,0 +1,228 @@
import asyncio
import os
import re
import uuid
import logging
from fastapi import FastAPI
from fastapi.responses import HTMLResponse
from fastapi.staticfiles import StaticFiles
from pydantic import BaseModel
from livekit import api as lkapi
from pipecat.audio.vad.silero import SileroVADAnalyzer
from pipecat.audio.vad.vad_analyzer import VADParams
from pipecat.frames.frames import TextFrame
from pipecat.pipeline.pipeline import Pipeline
from pipecat.pipeline.runner import PipelineRunner
from pipecat.pipeline.task import PipelineParams, PipelineTask
from pipecat.processors.aggregators.openai_llm_context import OpenAILLMContext
from pipecat.processors.frame_processor import FrameProcessor, FrameDirection
from pipecat.services.openai.llm import OpenAILLMService
from pipecat.services.openai.stt import OpenAISTTService
from pipecat.services.openai.tts import OpenAITTSService
from pipecat.transports.livekit.transport import LiveKitTransport, LiveKitParams
# ── TTS text normalizer ──────────────────────────────────────────────────────
# Replaces symbols and abbreviations with spoken Russian words so Silero TTS
# doesn't truncate on unknown characters.
_NORM_RULES: list[tuple[re.Pattern, str]] = [
# Temperature: +12°C / -5°С / 12 °C → плюс двенадцать градусов цельсия
(re.compile(r"([+-]?\d+)\s*°\s*[CСcс]", re.IGNORECASE), r"\1 градусов цельсия"),
# Bare degree sign: 90° → 90 градусов
(re.compile(r"(\d+)\s*°"), r"\1 градусов"),
# Percent
(re.compile(r"(\d+)\s*%"), r"\1 процентов"),
# Speed: m/s, м/с, km/h, км/ч
(re.compile(r"\bm/s\b", re.IGNORECASE), "метров в секунду"),
(re.compile(r"\bм/с\b"), "метров в секунду"),
(re.compile(r"\bkm/h\b", re.IGNORECASE), "километров в час"),
(re.compile(r"\bкм/ч\b"), "километров в час"),
# Currency
(re.compile(r"\$\s*(\d+)"), r"\1 долларов"),
(re.compile(r"(\d+)\s*\$"), r"\1 долларов"),
(re.compile(r"€\s*(\d+)"), r"\1 евро"),
(re.compile(r"(\d+)\s*€"), r"\1 евро"),
(re.compile(r"(\d+)\s*₽"), r"\1 рублей"),
# Plus/minus signs before numbers
(re.compile(r"\+(\d)"), r"плюс \1"),
(re.compile(r"-(\d)"), r"минус \1"),
# Common abbreviations
(re.compile(r"\bкг\b"), "килограмм"),
(re.compile(r"\bг\b(?=\s|$)"), "грамм"),
(re.compile(r"\bмм\b"), "миллиметров"),
(re.compile(r"\bсм\b"), "сантиметров"),
(re.compile(r"\bкм\b"), "километров"),
# Strip remaining special chars that TTS can't handle
(re.compile(r"[°•·†‡§¶©®™«»<>{}[\]|\\~^`]"), ""),
]
def normalize_for_tts(text: str) -> str:
"""Replace symbols with spoken Russian equivalents."""
for pattern, replacement in _NORM_RULES:
text = pattern.sub(replacement, text)
return text
class TTSTextNormalizer(FrameProcessor):
"""Intercepts TextFrames between LLM and TTS, normalizing symbols to words."""
async def process_frame(self, frame, direction: FrameDirection = FrameDirection.DOWNSTREAM):
await super().process_frame(frame, direction)
if isinstance(frame, TextFrame):
original = frame.text
normalized = normalize_for_tts(original)
if normalized != original:
logger.debug(f"TTSTextNormalizer: {original!r} → {normalized!r}")
await self.push_frame(TextFrame(text=normalized), direction)
else:
await self.push_frame(frame, direction)
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
# ── Config ────────────────────────────────────────────────────────────────────
LIVEKIT_URL = os.getenv("LIVEKIT_URL", "ws://host.docker.internal:7880") # bot connects here
LIVEKIT_PUBLIC_URL = os.getenv("LIVEKIT_PUBLIC_URL", "wss://lk.alogins.net") # browser connects here
LIVEKIT_API_KEY = os.getenv("LIVEKIT_API_KEY", "devkey")
LIVEKIT_SECRET = os.getenv("LIVEKIT_SECRET", "")
ADOLF_URL = os.getenv("ADOLF_URL", "http://host.docker.internal:8000/v1")
STT_URL = os.getenv("STT_URL", "http://host.docker.internal:8880/v1")
TTS_URL = os.getenv("TTS_URL", "http://host.docker.internal:8881/v1")
STT_MODEL = os.getenv("STT_MODEL", "deepdml/faster-whisper-large-v3-turbo-ct2")
TTS_VOICE = os.getenv("TTS_VOICE", "onyx")
SYSTEM_PROMPT = "You are Adolf, a helpful voice assistant. Keep replies concise — 1-3 sentences. No markdown."
app = FastAPI(title="Pipecat Voice Bot")
app.mount("/static", StaticFiles(directory="static"), name="static")
# ── LiveKit helpers ───────────────────────────────────────────────────────────
def _lk_token(room: str, identity: str, is_bot: bool = False) -> str:
grants = lkapi.VideoGrants(
room_join=True,
room=room,
can_publish=True,
can_subscribe=True,
can_publish_data=True,
)
token = (
lkapi.AccessToken(LIVEKIT_API_KEY, LIVEKIT_SECRET)
.with_identity(identity)
.with_name("Adolf Bot" if is_bot else identity)
.with_grants(grants)
)
return token.to_jwt()
async def _create_room(room_name: str) -> None:
lk = lkapi.LiveKitAPI(LIVEKIT_URL, LIVEKIT_API_KEY, LIVEKIT_SECRET)
try:
await lk.room.create_room(
lkapi.CreateRoomRequest(name=room_name, empty_timeout=300, max_participants=5)
)
finally:
await lk.aclose()
# ── Pipecat pipeline ──────────────────────────────────────────────────────────
async def _run_bot(room_name: str) -> None:
bot_token = _lk_token(room_name, "pipecat-bot", is_bot=True)
transport = LiveKitTransport(
url=LIVEKIT_URL,
token=bot_token,
room_name=room_name,
params=LiveKitParams(
audio_in_enabled=True,
audio_out_enabled=True,
vad_enabled=True,
vad_analyzer=SileroVADAnalyzer(params=VADParams(
stop_secs=0.8, # wait 0.8s of silence before end-of-speech
start_secs=0.2, # start speech detection after 0.2s
confidence=0.85, # high confidence to avoid triggering on ambient noise
)),
),
)
stt = OpenAISTTService(
api_key="dummy",
base_url=STT_URL,
model=STT_MODEL,
language="ru",
)
llm = OpenAILLMService(
api_key="dummy",
base_url=ADOLF_URL,
model="adolf-light",
)
tts = OpenAITTSService(
api_key="dummy",
base_url=TTS_URL,
model="silero",
voice=TTS_VOICE,
)
messages = [{"role": "system", "content": SYSTEM_PROMPT}]
context = OpenAILLMContext(messages)
context_aggregator = llm.create_context_aggregator(context)
normalizer = TTSTextNormalizer()
pipeline = Pipeline([
transport.input(),
stt,
context_aggregator.user(),
llm,
normalizer,
tts,
transport.output(),
context_aggregator.assistant(),
])
task = PipelineTask(pipeline, params=PipelineParams(allow_interruptions=False))
@transport.event_handler("on_participant_disconnected")
async def on_disconnect(transport, participant):
identity = participant if isinstance(participant, str) else getattr(participant, "identity", str(participant))
logger.info(f"Participant {identity} left — stopping bot")
await task.cancel()
runner = PipelineRunner()
logger.info(f"Bot starting in room={room_name}")
await runner.run(task)
logger.info(f"Bot done in room={room_name}")
# ── API ───────────────────────────────────────────────────────────────────────
class ConnectResponse(BaseModel):
room: str
token: str
url: str
@app.post("/connect", response_model=ConnectResponse)
async def connect():
room_name = f"voice-{uuid.uuid4().hex[:6]}"
await _create_room(room_name)
user_token = _lk_token(room_name, "user")
asyncio.create_task(_run_bot(room_name))
return ConnectResponse(room=room_name, token=user_token, url=LIVEKIT_PUBLIC_URL)
@app.get("/health")
async def health():
return {"status": "ok"}
@app.get("/", response_class=HTMLResponse)
async def index():
with open("static/index.html") as f:
return f.read()

241
ai/pipecat/static/index.html Normal file
View File

@@ -0,0 +1,241 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Adolf Voice</title>
<style>
* { box-sizing: border-box; margin: 0; padding: 0; }
body {
font-family: system-ui, sans-serif;
background: #0f0f0f;
color: #e0e0e0;
display: flex;
align-items: center;
justify-content: center;
min-height: 100vh;
}
.card {
background: #1a1a1a;
border: 1px solid #2a2a2a;
border-radius: 16px;
padding: 40px;
text-align: center;
width: 360px;
}
h1 { font-size: 1.4rem; font-weight: 600; margin-bottom: 8px; }
.subtitle { color: #666; font-size: 0.85rem; margin-bottom: 32px; }
#orb {
width: 100px;
height: 100px;
border-radius: 50%;
background: radial-gradient(circle, #3a3a3a 0%, #1a1a1a 100%);
border: 2px solid #333;
margin: 0 auto 24px;
cursor: pointer;
transition: all 0.3s ease;
display: flex;
align-items: center;
justify-content: center;
font-size: 2rem;
user-select: none;
}
#orb.listening {
background: radial-gradient(circle, #1e3a5f 0%, #0d1f33 100%);
border-color: #3b82f6;
box-shadow: 0 0 20px #3b82f640;
animation: pulse-blue 1.5s ease-in-out infinite;
}
#orb.speaking {
background: radial-gradient(circle, #1e4034 0%, #0d2018 100%);
border-color: #22c55e;
box-shadow: 0 0 20px #22c55e40;
animation: pulse-green 0.8s ease-in-out infinite;
}
#orb.thinking {
background: radial-gradient(circle, #3a2e1e 0%, #1a160d 100%);
border-color: #f59e0b;
box-shadow: 0 0 20px #f59e0b40;
animation: pulse-amber 1s ease-in-out infinite;
}
#orb.user-speaking {
background: radial-gradient(circle, #3a1e3a 0%, #1a0d1a 100%);
border-color: #a855f7;
box-shadow: 0 0 20px #a855f740;
animation: pulse-purple 0.6s ease-in-out infinite;
}
@keyframes pulse-blue { 0%,100%{box-shadow:0 0 20px #3b82f640} 50%{box-shadow:0 0 35px #3b82f680} }
@keyframes pulse-green { 0%,100%{box-shadow:0 0 20px #22c55e40} 50%{box-shadow:0 0 35px #22c55e80} }
@keyframes pulse-amber { 0%,100%{box-shadow:0 0 20px #f59e0b40} 50%{box-shadow:0 0 35px #f59e0b80} }
@keyframes pulse-purple { 0%,100%{box-shadow:0 0 20px #a855f740} 50%{box-shadow:0 0 35px #a855f780} }
#status {
font-size: 0.9rem;
color: #888;
margin-bottom: 16px;
min-height: 1.2em;
}
#transcript {
font-size: 0.8rem;
color: #555;
margin-bottom: 20px;
min-height: 2.4em;
line-height: 1.4;
font-style: italic;
word-break: break-word;
}
#transcript .user-text { color: #7ba8d4; font-style: normal; }
#transcript .bot-text { color: #6ab88a; font-style: normal; }
#btn {
background: #2a2a2a;
border: 1px solid #3a3a3a;
color: #e0e0e0;
padding: 10px 28px;
border-radius: 8px;
font-size: 0.9rem;
cursor: pointer;
transition: background 0.2s;
}
#btn:hover { background: #333; }
#btn:disabled { opacity: 0.4; cursor: default; }
#btn.active { border-color: #ef4444; color: #ef4444; }
</style>
</head>
<body>
<div class="card">
<h1>Adolf</h1>
<p class="subtitle">Voice assistant</p>
<div id="orb" onclick="toggle()">🎙️</div>
<div id="status">Press to connect</div>
<div id="transcript"></div>
<button id="btn" onclick="toggle()">Connect</button>
</div>
<script src="https://cdn.jsdelivr.net/npm/livekit-client/dist/livekit-client.umd.min.js"></script>
<script>
let room = null;
let audioCtx = null;
// Unlock browser autoplay — must happen on first user gesture
function unlockAudio() {
if (!audioCtx) {
audioCtx = new (window.AudioContext || window.webkitAudioContext)();
if (audioCtx.state === 'suspended') audioCtx.resume();
}
}
function setUI(state, msg) {
const orb = document.getElementById('orb');
const status = document.getElementById('status');
const btn = document.getElementById('btn');
orb.className = state || '';
status.textContent = msg;
if (state === null) {
btn.textContent = 'Connect';
btn.classList.remove('active');
orb.textContent = '🎙️';
} else {
btn.textContent = 'Disconnect';
btn.classList.add('active');
orb.textContent = state === 'thinking' ? '💭' :
state === 'speaking' ? '🔊' :
state === 'user-speaking' ? '🗣️' : '🎙️';
}
}
function addTranscript(role, text) {
const div = document.getElementById('transcript');
const cls = role === 'user' ? 'user-text' : 'bot-text';
const prefix = role === 'user' ? 'You: ' : 'Adolf: ';
div.innerHTML = `<span class="${cls}">${prefix}${text}</span>`;
}
async function toggle() {
unlockAudio();
if (room) {
room.disconnect();
return;
}
document.getElementById('btn').disabled = true;
setUI('thinking', 'Connecting…');
try {
const res = await fetch('/connect', { method: 'POST' });
const { token, url } = await res.json();
room = new LivekitClient.Room({ adaptiveStream: true, dynacast: true });
room.on(LivekitClient.RoomEvent.Connected, () => {
setUI('listening', 'Listening…');
document.getElementById('btn').disabled = false;
});
room.on(LivekitClient.RoomEvent.Disconnected, () => {
setUI(null, 'Press to connect');
document.getElementById('btn').disabled = false;
document.getElementById('transcript').innerHTML = '';
room = null;
});
room.on(LivekitClient.RoomEvent.ActiveSpeakersChanged, (speakers) => {
if (!room) return;
const botSpeaking = speakers.some(s => s.identity === 'pipecat-bot');
const userSpeaking = speakers.some(s => s.identity === 'user');
if (botSpeaking) {
setUI('speaking', 'Adolf is speaking…');
} else if (userSpeaking) {
setUI('user-speaking', 'Listening to you…');
} else {
setUI('listening', 'Listening…');
}
});
// Attach remote audio so browser plays it
room.on(LivekitClient.RoomEvent.TrackSubscribed, (track, pub, participant) => {
if (track.kind === 'audio') {
// Remove old element if any
const old = document.getElementById(`audio-${participant.identity}`);
if (old) old.remove();
const el = track.attach();
el.id = `audio-${participant.identity}`;
el.autoplay = true;
// Resume audio context on attach to beat autoplay restrictions
if (audioCtx && audioCtx.state === 'suspended') audioCtx.resume();
document.body.appendChild(el);
el.play().catch(() => {});
}
});
room.on(LivekitClient.RoomEvent.TrackUnsubscribed, (track) => {
track.detach().forEach(el => el.remove());
});
room.on(LivekitClient.RoomEvent.ParticipantConnected, (p) => {
if (p.identity === 'pipecat-bot') {
setUI('listening', 'Listening…');
}
});
// Data messages from bot (transcripts/events if pipecat sends them)
room.on(LivekitClient.RoomEvent.DataReceived, (data, participant) => {
try {
const msg = JSON.parse(new TextDecoder().decode(data));
if (msg.type === 'transcript' && msg.role === 'user') addTranscript('user', msg.text);
if (msg.type === 'transcript' && msg.role === 'bot') addTranscript('bot', msg.text);
} catch {}
});
const wsUrl = url.replace(/^http/, 'ws');
await room.connect(wsUrl, token);
await room.localParticipant.setMicrophoneEnabled(true);
} catch (err) {
console.error(err);
setUI(null, 'Error: ' + err.message);
document.getElementById('btn').disabled = false;
room = null;
}
}
</script>
</body>
</html>

122
ai/pipecat/test_pipeline.py Normal file
View File

@@ -0,0 +1,122 @@
"""
End-to-end pipeline test:
1. Call /connect to get a room + token
2. Join the LiveKit room as a Python client
3. Publish TTS audio (pre-generated) as microphone input
4. Capture bot's audio response and save to file
"""
import asyncio
import wave
import struct
import httpx
import numpy as np
from livekit import rtc
PIPECAT_URL = "http://localhost:8882"
TTS_URL = "http://host.docker.internal:8881"
OUTPUT_FILE = "/tmp/bot_response.wav"
SAMPLE_RATE = 48000
NUM_CHANNELS = 1
async def generate_tts_pcm(text: str) -> bytes:
"""Get WAV audio from Silero TTS, return raw PCM int16 bytes."""
async with httpx.AsyncClient(timeout=30) as c:
r = await c.post(f"{TTS_URL}/v1/audio/speech", json={
"input": text, "voice": "onyx", "response_format": "wav"
})
r.raise_for_status()
# Skip WAV header (44 bytes) to get raw PCM
return r.content[44:]
async def main():
# Step 1 — create room
print("[test] Creating room...")
async with httpx.AsyncClient() as c:
r = await c.post(f"{PIPECAT_URL}/connect")
r.raise_for_status()
creds = r.json()
print(f"[test] Room: {creds['room']} URL: {creds['url']}")
# Step 2 — generate test audio
test_phrase = "Привет! Как тебя зовут?"
print(f"[test] Generating TTS for: {test_phrase!r}")
pcm_bytes = await generate_tts_pcm(test_phrase)
print(f"[test] TTS PCM: {len(pcm_bytes)} bytes (~{len(pcm_bytes)//(SAMPLE_RATE*2):.1f}s)")
# Step 3 — join room
room = rtc.Room()
received_frames: list[bytes] = []
@room.on("track_subscribed")
def on_track(track, pub, participant):
if track.kind == rtc.TrackKind.KIND_AUDIO and participant.identity == "pipecat-bot":
print(f"[test] Subscribed to bot audio track")
audio_stream = rtc.AudioStream(track, sample_rate=SAMPLE_RATE, num_channels=NUM_CHANNELS)
asyncio.ensure_future(_collect_audio(audio_stream, received_frames))
ws_url = creds["url"].replace("https://", "wss://").replace("http://", "ws://")
# Connect internally via host.docker.internal
internal_url = "ws://host.docker.internal:7880"
print(f"[test] Connecting to LiveKit at {internal_url}...")
await room.connect(internal_url, creds["token"])
print(f"[test] Connected. Waiting for bot to join...")
# Wait for bot participant
for _ in range(20):
if any(p.identity == "pipecat-bot" for p in room.remote_participants.values()):
break
await asyncio.sleep(0.5)
print(f"[test] Participants: {[p.identity for p in room.remote_participants.values()]}")
# Step 4 — publish audio as microphone
print("[test] Publishing audio track...")
source = rtc.AudioSource(SAMPLE_RATE, NUM_CHANNELS)
local_track = rtc.LocalAudioTrack.create_audio_track("microphone", source)
opts = rtc.TrackPublishOptions(source=rtc.TrackSource.SOURCE_MICROPHONE)
await room.local_participant.publish_track(local_track, opts)
# Send PCM in 20ms chunks
chunk_samples = SAMPLE_RATE * 20 // 1000 # 960 samples per chunk
chunk_bytes = chunk_samples * 2 # int16
print(f"[test] Sending {len(pcm_bytes) // chunk_bytes} audio chunks...")
for i in range(0, len(pcm_bytes), chunk_bytes):
chunk = pcm_bytes[i:i + chunk_bytes]
if len(chunk) < chunk_bytes:
chunk = chunk + b'\x00' * (chunk_bytes - len(chunk))
samples = np.frombuffer(chunk, dtype=np.int16)
frame = rtc.AudioFrame(
data=samples.tobytes(),
sample_rate=SAMPLE_RATE,
num_channels=NUM_CHANNELS,
samples_per_channel=chunk_samples,
)
await source.capture_frame(frame)
await asyncio.sleep(0.02)
print("[test] Audio sent. Waiting for bot response (up to 30s)...")
await asyncio.sleep(30)
await room.disconnect()
# Step 5 — save response
if received_frames:
total = b"".join(received_frames)
print(f"[test] Received {len(total)} bytes of bot audio ({len(total)//(SAMPLE_RATE*2):.1f}s)")
with wave.open(OUTPUT_FILE, "wb") as wf:
wf.setnchannels(NUM_CHANNELS)
wf.setsampwidth(2)
wf.setframerate(SAMPLE_RATE)
wf.writeframes(total)
print(f"[test] Saved to {OUTPUT_FILE}")
else:
print("[test] No audio received from bot!")
async def _collect_audio(stream: rtc.AudioStream, buf: list):
async for event in stream:
buf.append(bytes(event.frame.data))
asyncio.run(main())

108
ai/provision_litellm_keys.py Executable file
View File

@@ -0,0 +1,108 @@
#!/usr/bin/env python3
"""provision_litellm_keys — kb#147 (A2A-15): turn agent-registry.yaml grants
into real LiteLLM virtual keys.
This is the ONE place a capability grant (model allow-list + budget) crosses
from data (agent-registry.yaml, version-controlled) into a live LiteLLM
key (via the proxy's /key/generate or /key/update admin API, master-key
authenticated). It deliberately does nothing destructive: --dry-run (the
default) only computes and prints the payload each agent WOULD get, making
zero network calls. --apply is required to actually create/update a key,
and needs LITELLM_MASTER_KEY in the environment (never hardcoded here, never
committed) — this is a privileged write against a live production service,
so it is not something this task runs unattended; --apply is the kb#147
handover step for a human/approved run.
Usage:
# Safe, run-anytime: print what each agent's key WOULD look like.
./provision_litellm_keys.py --dry-run
./provision_litellm_keys.py --dry-run --id torgash
# Privileged, requires explicit opt-in + master key (kb#147 handover):
LITELLM_MASTER_KEY=sk-... ./provision_litellm_keys.py --apply --id adolf
"""
import argparse
import json
import os
import sys
import urllib.error
import urllib.request
import agent_registry as ar
import model_registry as mr
LITELLM_BASE_URL = os.environ.get("LITELLM_BASE_URL", "http://localhost:4000")
def agent_ids_with_grants(registry):
return [a["id"] for a in registry["agents"] if a.get("capability_grant")]
def _http_post(path, payload, master_key):
req = urllib.request.Request(
f"{LITELLM_BASE_URL}{path}",
data=json.dumps(payload).encode(),
headers={
"Authorization": f"Bearer {master_key}",
"Content-Type": "application/json",
},
method="POST",
)
with urllib.request.urlopen(req, timeout=10) as resp:
return json.loads(resp.read())
def apply_key(spec, master_key):
"""Create (or update, if key_alias already exists) a LiteLLM virtual key
matching `spec` (the dict returned by agent_registry.litellm_key_spec).
Raises on any HTTP error rather than swallowing it — a failed grant
should never look like a successful one."""
payload = {
"key_alias": spec["key_alias"],
"models": spec["models"],
"max_budget": spec["max_budget"],
"budget_duration": spec["budget_duration"],
"metadata": {"agent_id": spec["agent_id"], "trust_class": spec["trust_class"], "source": "kb#147 agent-registry.yaml"},
}
try:
return _http_post("/key/generate", payload, master_key)
except urllib.error.HTTPError as e:
body = e.read().decode(errors="replace")
raise SystemExit(f"LiteLLM /key/generate failed for {spec['key_alias']}: {e.code} {body}")
def main():
ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
ap.add_argument("--registry", default=None)
ap.add_argument("--model-registry", default=None)
ap.add_argument("--id", default=None, help="only this agent id (default: every agent with a capability_grant)")
mode = ap.add_mutually_exclusive_group()
mode.add_argument("--dry-run", action="store_true", default=True, help="default: compute + print only, no network call")
mode.add_argument("--apply", action="store_true", help="actually call LiteLLM /key/generate (needs LITELLM_MASTER_KEY) -- privileged, kb#147 handover step")
args = ap.parse_args()
reg = ar.load_registry(args.registry)
model_reg = mr.load_registry(args.model_registry)
ids = [args.id] if args.id else agent_ids_with_grants(reg)
if not ids:
print("no agents with a capability_grant in the registry", file=sys.stderr)
sys.exit(1)
master_key = os.environ.get("LITELLM_MASTER_KEY")
if args.apply and not master_key:
print("error: --apply requires LITELLM_MASTER_KEY in the environment", file=sys.stderr)
sys.exit(2)
for agent_id in ids:
spec = ar.litellm_key_spec(reg, agent_id, model_reg)
if args.apply:
result = apply_key(spec, master_key)
print(json.dumps({"agent_id": agent_id, "key_alias": spec["key_alias"], "applied": True, "litellm_response_keys": list(result.keys())}))
else:
print(json.dumps({"mode": "dry-run", **spec}, indent=2))
if __name__ == "__main__":
main()

64
ai/quota-command-openclaw-plugin/index.js Normal file
View File

@@ -0,0 +1,64 @@
/**
* Kimi Quota Command (kb #62) — registers `/quota` on Adolf's Matrix channel.
*
* OpenClaw's native-command dispatch (`api.registerCommand`) runs a
* `/`-prefixed command BEFORE the agent turn: no model is invoked, so this
* never spends a Kimi turn (unlike asking Adolf in prose "what's my quota").
* It hits adolf-llm's own GET /usage route (server.js, kb #62 piece 1), which
* itself talks straight to Kimi's managed-usage API — no LLM anywhere in the
* path.
*
* Gating: `requireAuth: true` (the registerCommand default) restricts the
* command to `ctx.isAuthorizedSender`, i.e. the same Matrix DM allowlist
* (`channels.matrix.dm.allowFrom` in openclaw.json) that already gates every
* other interaction with Adolf. No separate owner-only tier is needed here —
* it's a read-only status line, not a privileged action.
*/
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
// adolf-llm is a sibling service on the same `openai` compose network —
// reached by service name, not localhost/host.docker.internal.
const USAGE_URL = "http://adolf-llm:8010/usage";
const FETCH_TIMEOUT_MS = 5000;
function pct(row) {
return row && typeof row.pct === "number" ? `${row.pct}%` : "n/a";
}
async function fetchUsage() {
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
try {
const res = await fetch(USAGE_URL, { signal: controller.signal });
const body = await res.json().catch(() => ({}));
if (!res.ok) throw new Error(body?.error || `adolf-llm /usage HTTP ${res.status}`);
return body;
} finally {
clearTimeout(timer);
}
}
export default definePluginEntry({
id: "quota-command",
name: "Kimi Quota Command",
description:
"LLM-free /quota command: reads Adolf's Kimi usage from adolf-llm:8010/usage and replies with a compact readout.",
register(api) {
api.registerCommand({
name: "quota",
description: "Show Kimi quota usage (5h / weekly / 7d) — no model call.",
acceptsArgs: false,
requireAuth: true,
handler: async () => {
try {
const usage = await fetchUsage();
const line = `Kimi: 5h ${pct(usage.window_5h)} · weekly ${pct(usage.weekly)} · 7d ${pct(usage.window_7d)}`;
return { text: line, suppressReply: true };
} catch (e) {
api.logger?.warn?.(`quota-command: fetch failed (${e?.message || e})`);
return { text: `Kimi quota unavailable: ${e?.message || e}`, suppressReply: true };
}
},
});
},
});

13
ai/quota-command-openclaw-plugin/openclaw.plugin.json Normal file
View File

@@ -0,0 +1,13 @@
{
"id": "quota-command",
"name": "Kimi Quota Command",
"description": "Registers /quota: a native-command handler (runs before the agent, zero model calls) that reads Adolf's Kimi usage from adolf-llm:8010/usage and replies with a compact 5h/weekly/7d readout.",
"activation": {
"onStartup": true
},
"configSchema": {
"type": "object",
"additionalProperties": false,
"properties": {}
}
}

18
ai/quota-command-openclaw-plugin/package.json Normal file
View File

@@ -0,0 +1,18 @@
{
"name": "openclaw-quota-command",
"version": "1.0.0",
"description": "LLM-free /quota command for Adolf: reads Kimi usage from adolf-llm:8010/usage and replies with a compact readout.",
"type": "module",
"private": true,
"main": "./index.js",
"peerDependencies": {
"openclaw": ">=2026.3.0"
},
"openclaw": {
"extensions": ["./index.js"],
"compat": {
"pluginApi": ">=2026.0.0",
"minGatewayVersion": "2026.0.0"
}
}
}

30
ai/shared-mcp.json Normal file
View File

@@ -0,0 +1,30 @@
{
"mcpServers": {
"hindsight": {
"type": "http",
"url": "http://hindsight:8888/mcp/adolf-shared/",
"enabledTools": ["recall", "retain", "reflect", "list_memories", "get_memory", "update_memory", "list_directives", "create_directive", "delete_directive"]
},
"openclaw-tools": {
"type": "http",
"url": "http://openclaw-tools:8020/mcp"
},
"kanboard": {
"type": "http",
"url": "http://host.docker.internal:3104/mcp",
"enabledTools": ["kanboard_list_projects", "kanboard_get_project", "kanboard_list_tasks", "kanboard_my_tasks", "kanboard_get_task", "kanboard_search_tasks", "kanboard_list_users", "kanboard_project_activity", "kanboard_create_task", "kanboard_update_task", "kanboard_move_task", "kanboard_change_task_status", "kanboard_assign_task", "kanboard_add_comment"]
},
"agap": {
"type": "http",
"url": "http://host.docker.internal:3100/mcp",
"bearerTokenEnvVar": "AGAP_MCP_TOKEN",
"enabledTools": ["vw_get_password", "vw_get_item", "vw_list_items", "vw_create_login", "vw_update_password", "ha_get_state", "ha_list_entities", "ha_call_service", "ha_get_history", "zabbix_get_problems", "zabbix_get_hosts", "zabbix_get_items", "zabbix_get_triggers", "radicale_list_calendars", "radicale_list_events", "radicale_get_event", "radicale_put_event", "radicale_delete_event", "radicale_move_event", "todoist_list_tasks", "todoist_list_projects", "todoist_create_task", "todoist_update_task", "todoist_complete_task", "todoist_capture_idea", "wiki_search", "wiki_read", "wiki_edit"]
},
"marketplace": {
"type": "http",
"url": "http://host.docker.internal:3101/mcp",
"bearerTokenEnvVar": "MARKETPLACE_MCP_TOKEN",
"enabledTools": ["marketplace_find_best", "marketplace_search", "marketplace_get_product", "marketplace_get_recommendations", "marketplace_get_reviews", "marketplace_compare_prices", "marketplace_status"]
}
}
}

15
ai/silero-tts/Dockerfile Normal file
View File

@@ -0,0 +1,15 @@
FROM python:3.11-slim
RUN apt-get update && apt-get install -y --no-install-recommends ffmpeg && rm -rf /var/lib/apt/lists/*
# CPU-only torch keeps image ~500MB vs ~2GB for CUDA
RUN pip install --no-cache-dir torch --index-url https://download.pytorch.org/whl/cpu
RUN pip install --no-cache-dir fastapi uvicorn scipy numpy pydub omegaconf
WORKDIR /app
COPY server.py .
ENV TORCH_HOME=/cache/torch
EXPOSE 8881
CMD ["uvicorn", "server:app", "--host", "0.0.0.0", "--port", "8881"]

153
ai/silero-tts/server.py Normal file
View File

@@ -0,0 +1,153 @@
import io
import re
import logging
import numpy as np
import torch
from fastapi import FastAPI, HTTPException
from fastapi.responses import Response
from pydantic import BaseModel
import scipy.io.wavfile as wavfile
from pydub import AudioSegment
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
app = FastAPI(title="Silero TTS")
# ── Config ────────────────────────────────────────────────────────────────────
DEVICE = "cuda" if torch.cuda.is_available() else "cpu"
SAMPLE_RATE = 24000
MAX_CHUNK = 800 # chars per Silero call
# Model identifiers (passed as `speaker` to torch.hub.load — selects model file)
MODEL_ID = {"ru": "v3_1_ru", "en": "v3_en"}
# Silero speakers (passed to apply_tts)
RU_SPEAKERS = ["aidar", "baya", "kseniya", "xenia", "eugene"]
EN_SPEAKERS = [f"en_{i}" for i in range(10)]
# OpenAI voice → Silero speaker
VOICE_MAP = {
"ru": {"alloy": "eugene", "echo": "aidar", "fable": "baya",
"onyx": "eugene", "nova": "kseniya", "shimmer": "xenia"},
"en": {"alloy": "en_3", "echo": "en_1", "fable": "en_2",
"onyx": "en_3", "nova": "en_4", "shimmer": "en_5"},
}
# ── Model cache ───────────────────────────────────────────────────────────────
_models: dict[str, object] = {}
def _get_model(language: str):
if language not in _models:
logger.info(f"Loading Silero model {MODEL_ID[language]} lang={language} device={DEVICE}")
model, _ = torch.hub.load(
repo_or_dir="snakers4/silero-models",
model="silero_tts",
language=language,
speaker=MODEL_ID[language],
trust_repo=True,
)
model.to(DEVICE)
_models[language] = model
logger.info(f"Model ready: lang={language}")
return _models[language]
@app.on_event("startup")
async def preload():
"""Preload both language models to avoid cold-start on first request."""
for lang in ("ru", "en"):
try:
_get_model(lang)
except Exception as e:
logger.warning(f"Preload failed for lang={lang}: {e}")
# ── Helpers ───────────────────────────────────────────────────────────────────
def _is_russian(text: str) -> bool:
return bool(re.search(r"[а-яёА-ЯЁ]", text))
def _split_sentences(text: str) -> list[str]:
"""Split on sentence boundaries, keeping chunks under MAX_CHUNK chars."""
if len(text) <= MAX_CHUNK:
return [text]
parts = re.split(r"(?<=[.!?;])\s+", text.strip())
chunks, cur = [], ""
for part in parts:
if len(cur) + len(part) + 1 <= MAX_CHUNK:
cur = f"{cur} {part}" if cur else part
else:
if cur:
chunks.append(cur)
# If single part is too long, split mid-word as last resort
cur = part[:MAX_CHUNK] if len(part) > MAX_CHUNK else part
if cur:
chunks.append(cur)
return chunks or [text[:MAX_CHUNK]]
def _to_bytes(audio: torch.Tensor, fmt: str) -> bytes:
pcm = (audio.cpu().numpy() * 32767).astype(np.int16)
if fmt == "pcm":
return pcm.tobytes()
buf = io.BytesIO()
wavfile.write(buf, SAMPLE_RATE, pcm)
if fmt == "wav":
return buf.getvalue()
seg = AudioSegment.from_wav(io.BytesIO(buf.getvalue()))
out = io.BytesIO()
seg.export(out, format="mp3")
return out.getvalue()
# ── API ───────────────────────────────────────────────────────────────────────
class SpeechRequest(BaseModel):
model: str = "silero"
input: str
voice: str = "alloy"
response_format: str = "mp3"
speed: float = 1.0
@app.get("/health")
async def health():
return {"status": "ok", "device": DEVICE}
@app.get("/v1/models")
async def list_models():
return {
"object": "list",
"data": [{"id": "silero", "object": "model", "owned_by": "silero"}],
}
@app.post("/v1/audio/speech")
async def speech(req: SpeechRequest):
text = req.input.strip()
if not text:
raise HTTPException(status_code=400, detail="input is empty")
language = "ru" if _is_russian(text) else "en"
vm = VOICE_MAP[language]
speaker = vm.get(req.voice, vm["alloy"])
try:
model = _get_model(language)
chunks = _split_sentences(text)
parts = [
model.apply_tts(text=chunk, speaker=speaker, sample_rate=SAMPLE_RATE)
for chunk in chunks
]
audio = parts[0] if len(parts) == 1 else torch.cat(parts)
except Exception as e:
logger.error(f"TTS error: {e}")
raise HTTPException(status_code=500, detail=str(e))
fmt = req.response_format.lower()
audio_bytes = _to_bytes(audio, fmt)
media_types = {"wav": "audio/wav", "pcm": "audio/pcm", "mp3": "audio/mpeg"}
media_type = media_types.get(fmt, "audio/mpeg")
return Response(content=audio_bytes, media_type=media_type)

13
ai/tei-reranker/Dockerfile Normal file
View File

@@ -0,0 +1,13 @@
# CUDA torch base with Pascal (sm_61) support — cu118 wheels include sm_61,
# so the GTX 1070 works (unlike the stock TEI GPU image, which needs sm_75+).
FROM pytorch/pytorch:2.3.1-cuda11.8-cudnn8-runtime
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY server.py .
ENV HF_HOME=/root/.cache/huggingface
EXPOSE 80
CMD ["uvicorn", "server:app", "--host", "0.0.0.0", "--port", "80"]

8
ai/tei-reranker/requirements.txt Normal file
View File

@@ -0,0 +1,8 @@
# torch/cuda come from the pytorch base image. Pin transformers to a version
# known-compatible with jina-reranker-v2's custom modeling code.
transformers==4.44.2
einops>=0.7
sentencepiece>=0.1.99
protobuf>=3.20
fastapi>=0.110
uvicorn[standard]>=0.29

85
ai/tei-reranker/server.py Normal file
View File

@@ -0,0 +1,85 @@
"""Minimal TEI-compatible cross-encoder rerank server (GPU).
Why this exists: HuggingFace's official Text-Embeddings-Inference GPU images
require CUDA compute capability >= 7.5 (Turing+). This box has a GTX 1070
(Pascal, 6.1), so the stock TEI image won't run. Plain CUDA torch DOES support
Pascal (that's why ollama works here), so we serve the same
`jina-reranker-v2-base-multilingual` cross-encoder via torch and expose only the
two endpoints Hindsight's `tei` reranker provider calls:
GET /info -> JSON (init/health probe)
POST /rerank -> {"query": str, "texts": [str], ...}
-> bare list [{"index": i, "score": f}, ...] sorted desc
See hindsight_api/engine/cross_encoder.py::RemoteTEICrossEncoder for the client.
"""
import os
import torch
from fastapi import FastAPI
from pydantic import BaseModel
from transformers import AutoModelForSequenceClassification
MODEL_ID = os.environ.get("RERANKER_MODEL", "jinaai/jina-reranker-v2-base-multilingual")
DEVICE = os.environ.get("RERANKER_DEVICE", "cuda")
MAX_LENGTH = int(os.environ.get("RERANKER_MAX_LENGTH", "1024"))
# fp16 on GPU halves the ~1.1GB fp32 footprint; Pascal supports fp16 storage.
DTYPE = torch.float16 if DEVICE == "cuda" else torch.float32
app = FastAPI(title="tei-reranker")
_model = None
def _load():
global _model
if _model is not None:
return
m = AutoModelForSequenceClassification.from_pretrained(
MODEL_ID, torch_dtype=DTYPE, trust_remote_code=True
)
m.to(DEVICE)
m.eval()
_model = m
@app.on_event("startup")
def startup():
_load()
class RerankRequest(BaseModel):
query: str
texts: list[str]
return_text: bool = False
truncate: bool | None = None
raw_scores: bool | None = None
@app.get("/info")
def info():
# Hindsight only needs a 200 JSON here to consider the server initialized.
return {
"model_id": MODEL_ID,
"model_dtype": str(DTYPE).replace("torch.", ""),
"model_type": {"reranker": {}},
"max_input_length": MAX_LENGTH,
"device": DEVICE,
}
@app.get("/health")
def health():
return {"status": "ok" if _model is not None else "loading"}
@app.post("/rerank")
def rerank(req: RerankRequest):
if not req.texts:
return []
pairs = [[req.query, t] for t in req.texts]
with torch.no_grad():
# jina-reranker-v2 exposes compute_score (batches + moves to device).
scores = _model.compute_score(pairs, max_length=MAX_LENGTH)
if not isinstance(scores, list):
scores = [scores]
results = [{"index": i, "score": float(s)} for i, s in enumerate(scores)]
results.sort(key=lambda r: r["score"], reverse=True)
return results

102
ai/todoist-capture-plugin/index.js Normal file
View File

@@ -0,0 +1,102 @@
/**
* Todoist Idea Capture (kb#170 component 1) — registers `/idea <text>` on
* Adolf's Matrix channel.
*
* Same reasoning as quota-command-openclaw-plugin (kb#62): OpenClaw's
* native-command dispatch (`api.registerCommand`) runs BEFORE the agent
* turn, so this never spends a Kimi turn. That property is not incidental
* here — it's the whole point of kb#170's "encoder-only, not an LLM call"
* design: classification runs on bge-m3 (agap-mcp/src/classifier.js), and
* routing the capture through a native command means the ENTIRE
* capture -> classify -> Todoist path costs zero model tokens, not just the
* classification step.
*
* This plugin does no classification itself — it POSTs the raw text to
* agap-mcp's /capture-idea endpoint (same container agap-mcp already
* exposes at :3100 for the MCP tool surface; this is a second, plain-REST
* entry point to the same todoistCaptureIdea() function, added because a
* native command handler is simplest calling plain JSON over HTTP rather
* than speaking MCP JSON-RPC to invoke its own tool). See agap-mcp/src/
* capture.js for the classify+create logic and agap-mcp/src/server.js for
* the /capture-idea route.
*
* Gating: requireAuth: true (the registerCommand default) restricts the
* command to the same Matrix DM allowlist (channels.matrix.dm.allowFrom in
* openclaw.json) that already gates every other interaction with Adolf —
* no separate tier needed, this creates a task in the operator's own
* Todoist inbox, not a privileged/destructive action.
*/
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
// agap-mcp is a sibling reached via host.docker.internal, same mapping
// openclaw.json's mcp.servers.agap.url already uses for this container.
const CAPTURE_URL = "http://host.docker.internal:3100/capture-idea";
const FETCH_TIMEOUT_MS = 15000; // bge-m3 embed + Todoist create can take a few seconds
// kb#180: agap-mcp's :3100 listener is authenticated now — /capture-idea is
// no longer an open REST endpoint (it never should have been: it reaches
// Todoist writes from any LAN peer). This plugin runs inside the adolf
// container, so it presents Adolf's own agap-mcp bearer token, injected as
// AGAP_MCP_TOKEN by ai/docker-compose.yml from .env (never inlined
// here). If the var is unset the request goes out unauthenticated and
// agap-mcp answers 401 — a visible failure of /idea, not a silent one.
const AGAP_MCP_TOKEN = process.env.AGAP_MCP_TOKEN || "";
async function captureIdea(text) {
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
try {
const res = await fetch(CAPTURE_URL, {
method: "POST",
headers: {
"Content-Type": "application/json",
...(AGAP_MCP_TOKEN ? { Authorization: `Bearer ${AGAP_MCP_TOKEN}` } : {}),
},
body: JSON.stringify({ text }),
signal: controller.signal,
});
const body = await res.json().catch(() => ({}));
if (!res.ok) throw new Error(body?.error || `agap-mcp /capture-idea HTTP ${res.status}`);
return body;
} finally {
clearTimeout(timer);
}
}
function formatReply({ task, classification }) {
const bits = [
`area=${classification.area.label}`,
`urgency=${classification.urgency.label}`,
];
if (classification.decompose.label === "needs-decomposition") bits.push("требует декомпозиции в Kanboard");
if (classification.area.ambiguous) bits.push("область — неточно, уточни при ревью");
return `Записал в Todoist: «${task.content}» (${bits.join(", ")}).`;
}
export default definePluginEntry({
id: "todoist-capture",
name: "Todoist Idea Capture",
description:
"LLM-free /idea command: classifies free text via agap-mcp (local bge-m3, no Kimi call) and creates a labelled Todoist task.",
register(api) {
api.registerCommand({
name: "idea",
description: "Capture an idea/quick task -> classified (area/urgency/decompose) and filed in Todoist. No Kimi call.",
acceptsArgs: true,
requireAuth: true,
handler: async (ctx) => {
const text = (ctx.args || "").trim();
if (!text) {
return { text: "Использование: /idea <текст идеи>", suppressReply: true };
}
try {
const result = await captureIdea(text);
return { text: formatReply(result), suppressReply: true };
} catch (e) {
api.logger?.warn?.(`todoist-capture: capture failed (${e?.message || e})`);
return { text: `Не удалось захватить идею: ${e?.message || e}`, suppressReply: true };
}
},
});
},
});

13
ai/todoist-capture-plugin/openclaw.plugin.json Normal file
View File

@@ -0,0 +1,13 @@
{
"id": "todoist-capture",
"name": "Todoist Idea Capture",
"description": "Registers /idea: a native-command handler (runs before the agent, zero model calls) that classifies free text (area/urgency/decompose-need, local bge-m3 nearest-centroid — see agap-mcp/src/classifier.js) and creates a labelled Todoist task via agap-mcp's POST /capture-idea.",
"activation": {
"onStartup": true
},
"configSchema": {
"type": "object",
"additionalProperties": false,
"properties": {}
}
}

18
ai/todoist-capture-plugin/package.json Normal file
View File

@@ -0,0 +1,18 @@
{
"name": "openclaw-todoist-capture",
"version": "1.0.0",
"description": "LLM-free /idea command for Adolf: classifies free text (area/urgency/decompose, local bge-m3 nearest-centroid) via agap-mcp and creates a labelled Todoist task.",
"type": "module",
"private": true,
"main": "./index.js",
"peerDependencies": {
"openclaw": ">=2026.3.0"
},
"openclaw": {
"extensions": ["./index.js"],
"compat": {
"pluginApi": ">=2026.0.0",
"minGatewayVersion": "2026.0.0"
}
}
}

313
ai/validate_capability_grants.py Executable file
View File

@@ -0,0 +1,313 @@
#!/usr/bin/env python3
"""validate_capability_grants — kb#147 (A2A-15), extended by kb#144 (A2A-12):
cross-check that agent-registry.yaml's declared tool_allowlist.mcp_servers
(server-level) AND tool_allowlist.mcp_tool_filter (per-tool level, kb#144)
for each agent match what that agent's real, git-controlled config actually
grants it -- at BOTH layers that materialize a tool bundle for Adolf:
1. OpenClaw's own mcp.servers.*.toolFilter.include in adolf/openclaw.json
(adolf's own MCP client surface).
2. shared-mcp.json's per-server `enabledTools` (kb#144 verification pass,
2026-07-22): what adolf-llm/server.js's writeMcpConfig() seeds into
each Kimi CLI session's project-root .mcp.json -- the layer that
ACTUALLY determines the MODEL's tool bundle for Adolf's kimi backbone.
Layer 1 alone shipped a false "Done" once already (kb#144 first pass):
wire.jsonl proved Kimi's tool counts were unchanged because OpenClaw's
toolFilter never reaches the Kimi CLI, which reads its own
enabledTools/disabledTools (McpServerCommonFields, computeEnabledNames
-- confirmed by decompiling the installed @moonshot-ai/kimi-code
package's dist/main.mjs). Checking only layer 1 would pass this
validator while leaving the real per-turn token bloat unfixed again.
Read-only. Makes no live changes and touches no running service — it just
diffs already-committed files so a registry edit that silently drifts from
an agent's real config fails loudly (exit 1) instead of rotting quietly,
which is exactly the "scattered configs" failure mode kb#147's acceptance
bar ("grants live in the agent registry, not scattered configs") exists to
prevent. kb#144's acceptance bar ("Adolf's tools are sourced from the
registry") means both layers, not just the one OpenClaw itself reads.
Only agents with a `prompt_source` pointing at a real openclaw.json-shaped
config are checked; agents that are registry-only target state (torgash,
researcher — no config file exists yet) are reported as skipped, not failed.
Usage:
./validate_capability_grants.py
./validate_capability_grants.py --openclaw-json ../adolf/openclaw.json --id adolf
"""
import argparse
import json
import re
import sys
import agent_registry as ar
HERE_ADOLF_OPENCLAW_JSON = "../adolf/openclaw.json"
SHARED_MCP_JSON = "shared-mcp.json"
# id -> path to the git-controlled OpenClaw config that IS this agent's live
# MCP surface. Only adolf has one today (claude-coder has no openclaw.json --
# it's a CLAUDE.md-driven persona, not an OpenClaw runtime; see its
# capability_grant note in agent-registry.yaml).
KNOWN_CONFIGS = {
"adolf": HERE_ADOLF_OPENCLAW_JSON,
}
# id -> path to the shared-mcp.json this agent's backbone runtime seeds its
# session .mcp.json from (kb#144 layer-2 check, see module docstring). Only
# agents on a Kimi-CLI-shaped backbone go through this file at all.
KNOWN_SHARED_MCP = {
"adolf": SHARED_MCP_JSON,
}
def _strip_jsonc_comments(text):
"""Drop // line comments. Good enough for this read-only check: this
file's comments are all on their own line or trail real content with no
'//' inside a string value today -- verified by hand."""
out = []
for line in text.splitlines():
stripped = line.strip()
if stripped.startswith("//"):
continue
m = re.search(r'(?<!:)//', line)
if m and line[: m.start()].count('"') % 2 == 0:
line = line[: m.start()]
out.append(line)
return "\n".join(out)
def _find_key_brace(text, key, start=0):
"""Find `key: {` (bare or quoted key) at or after `start`; return the
index of the matching '{'."""
m = re.search(rf'["\']?{re.escape(key)}["\']?\s*:\s*\{{', text[start:])
if not m:
raise ValueError(f"key {key!r} not found from offset {start}")
return start + m.end() - 1 # index of the '{' itself
def _matching_close_brace(text, open_idx):
depth = 0
for i in range(open_idx, len(text)):
if text[i] == '{':
depth += 1
elif text[i] == '}':
depth -= 1
if depth == 0:
return i
raise ValueError("unbalanced braces")
def _extract_object_top_level_keys(text, key_path):
"""openclaw.json is JS-object-literal JSON5 (bare identifier keys,
trailing commas) -- `json.loads` can't touch it and pulling in a JSON5
parser is overkill for one narrow read. Instead: locate `key_path`
(e.g. ["mcp", "servers"]) by finding each key's opening '{' in turn, then
brace-depth-scan that object collecting only its DIRECT child keys
(`name: {` at depth 1). Sufficient and honest for this validation
script's one job; not a general JSON5 reader."""
pos = 0
open_idx = 0
for key in key_path:
open_idx = _find_key_brace(text, key, pos)
pos = open_idx + 1
close_idx = _matching_close_brace(text, open_idx)
body = text[open_idx + 1 : close_idx]
# Depth-0 identifiers immediately followed by ": {" are this object's
# direct child keys (mcp.servers' entries are always objects). Only try
# a key match right after a boundary ('{', ',', or start-of-body) so an
# identifier can't be "matched" starting mid-token from inside a nested
# value (the earlier, buggy version of this scanner did exactly that).
keys = []
depth = 0
i, n = 0, len(body)
prev_boundary = True
key_re = re.compile(r'["\']?([A-Za-z0-9_-]+)["\']?\s*:\s*\{')
while i < n:
ch = body[i]
if ch in ' \t\r\n':
i += 1
continue
if depth == 0 and prev_boundary:
m = key_re.match(body, i)
if m:
keys.append(m.group(1))
i = m.end() - 1 # land on the key's '{' so the normal handling below opens depth 1
prev_boundary = False
continue
if ch == '{':
depth += 1
prev_boundary = True
elif ch == '}':
depth -= 1
prev_boundary = True
elif ch == ',':
prev_boundary = True
else:
prev_boundary = False
i += 1
return sorted(keys)
def load_mcp_servers(path):
with open(path) as f:
raw = f.read()
text = _strip_jsonc_comments(raw)
return _extract_object_top_level_keys(text, ["mcp", "servers"])
def _locate_object(text, key_path, start=0):
"""Chase `key_path` (e.g. ["mcp", "servers", "hindsight"]) through nested
`key: {` objects, same navigation _extract_object_top_level_keys does
internally, exposed standalone so other extractors (toolFilter below)
can reuse it instead of re-deriving brace offsets."""
pos = start
open_idx = start
for key in key_path:
open_idx = _find_key_brace(text, key, pos)
pos = open_idx + 1
close_idx = _matching_close_brace(text, open_idx)
return open_idx, close_idx
def _matching_close_bracket(text, open_idx):
"""Same brace-depth-scan as _matching_close_brace, for '[' / ']' — needed
to bound a toolFilter.include array (a list, not an object)."""
depth = 0
for i in range(open_idx, len(text)):
if text[i] == '[':
depth += 1
elif text[i] == ']':
depth -= 1
if depth == 0:
return i
raise ValueError("unbalanced brackets")
def load_tool_filter(path, server_name):
"""kb#144: extract mcp.servers.<server_name>.toolFilter.include as a
sorted list of tool names, or None if that server has no toolFilter (or
no include list) at all — OpenClaw's own semantics for "no toolFilter":
every tool the server offers stays eligible (see schema-BqdpWz19.js:
"When omitted, all server tools remain eligible unless excluded.").
exclude-only filters are not modeled here (none of Adolf's servers use
exclude today) and are reported as None (unrestricted) rather than
silently mis-parsed.
"""
with open(path) as f:
raw = f.read()
text = _strip_jsonc_comments(raw)
try:
server_open, server_close = _locate_object(text, ["mcp", "servers", server_name])
except ValueError:
return None # server not present in this config at all
body = text[server_open : server_close + 1]
try:
tf_open, tf_close = _locate_object(body, ["toolFilter"])
except ValueError:
return None # no toolFilter -> unrestricted, by OpenClaw's own semantics
tf_body = body[tf_open : tf_close + 1]
m = re.search(r'["\']?include["\']?\s*:\s*\[', tf_body)
if not m:
return None # exclude-only or empty toolFilter -- not modeled, treat as unrestricted
bracket_open = tf_body.index('[', m.start())
bracket_close = _matching_close_bracket(tf_body, bracket_open)
arr_body = tf_body[bracket_open + 1 : bracket_close]
return sorted(re.findall(r'["\']([A-Za-z0-9_.\-\*]+)["\']', arr_body))
def load_shared_mcp_enabled_tools(path):
"""kb#144 layer-2 check (see module docstring): shared-mcp.json is
strict JSON (no JSON5 quirks, unlike openclaw.json), so a plain
`json.load` is enough -- no brace-scanner needed here. Returns
{server_name: sorted-tool-list-or-None}, None meaning no `enabledTools`
key on that server (unfiltered -- every tool it offers stays eligible,
same "omitted = unrestricted" semantics as OpenClaw's own toolFilter).
"""
with open(path) as f:
data = json.load(f)
out = {}
for name, cfg in (data.get("mcpServers") or {}).items():
tools = cfg.get("enabledTools")
out[name] = sorted(tools) if tools else None
return out
def main():
ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
ap.add_argument("--registry", default=None)
ap.add_argument("--openclaw-json", default=None, help="override path for --id's config")
ap.add_argument("--id", default=None, help="only this agent id (default: every id in KNOWN_CONFIGS)")
args = ap.parse_args()
reg = ar.load_registry(args.registry)
ids = [args.id] if args.id else list(KNOWN_CONFIGS)
failures = 0
for agent_id in ids:
agent = ar.get_agent(reg, agent_id)
declared = sorted((agent.get("tool_allowlist") or {}).get("mcp_servers") or [])
config_path = args.openclaw_json or KNOWN_CONFIGS.get(agent_id)
if not config_path:
print(f"SKIP {agent_id}: no known live config to cross-check (target-state agent)")
continue
try:
live = load_mcp_servers(config_path)
except FileNotFoundError:
print(f"SKIP {agent_id}: config not found at {config_path}")
continue
if declared == live:
print(f"OK {agent_id}: registry tool_allowlist.mcp_servers == live {config_path} mcp.servers -> {live}")
else:
failures += 1
print(f"FAIL {agent_id}: registry says {declared} but {config_path} actually grants {live}")
# kb#144: per-tool cross-check, same idea one level down. Only
# meaningful for servers the registry actually declares a filter
# for (mcp_tool_filter); a server absent from that map is not
# asserted either way here (it may be intentionally unfiltered).
declared_filters = (agent.get("tool_allowlist") or {}).get("mcp_tool_filter") or {}
for server_name, declared_tools in declared_filters.items():
live_tools = load_tool_filter(config_path, server_name)
declared_sorted = sorted(declared_tools) if declared_tools else None
if declared_sorted == live_tools:
shown = live_tools if live_tools is not None else "(unfiltered)"
print(f"OK {agent_id}/{server_name}: registry mcp_tool_filter == live toolFilter.include -> {shown}")
else:
failures += 1
print(f"FAIL {agent_id}/{server_name}: registry mcp_tool_filter says {declared_sorted} but live toolFilter.include is {live_tools}")
# kb#144 layer-2: the file that actually reaches the MODEL for a
# Kimi-backed agent (see module docstring for why layer 1 alone
# missed the real bug once already). Servers the registry declares a
# filter for but that don't appear in shared-mcp.json at all (e.g.
# marketplace, which OpenClaw carries but Kimi's session never sees)
# are not asserted here -- that's a separate, pre-existing gap
# between what OpenClaw offers Adolf and what reaches Kimi, not a
# drift this validator's job to catch.
shared_mcp_path = KNOWN_SHARED_MCP.get(agent_id)
if shared_mcp_path:
try:
live_shared = load_shared_mcp_enabled_tools(shared_mcp_path)
except FileNotFoundError:
print(f"SKIP {agent_id}: shared-mcp.json not found at {shared_mcp_path}")
else:
for server_name, declared_tools in declared_filters.items():
if server_name not in live_shared:
continue
declared_sorted = sorted(declared_tools) if declared_tools else None
live_tools = live_shared[server_name]
if declared_sorted == live_tools:
shown = live_tools if live_tools is not None else "(unfiltered)"
print(f"OK {agent_id}/{server_name}: registry mcp_tool_filter == live shared-mcp.json enabledTools -> {shown}")
else:
failures += 1
print(f"FAIL {agent_id}/{server_name}: registry mcp_tool_filter says {declared_sorted} but shared-mcp.json enabledTools is {live_tools}")
sys.exit(1 if failures else 0)
if __name__ == "__main__":
main()