@jossuealcala/madre 0.2.3 → 0.3.0

package/src/modules/git-pulse.mjs

@@ -0,0 +1,26 @@
+// Git Pulse: /git in the composer brings the repository's facts into the room.
+// Nothing to switch: it is on wherever the project is a git repository.
+
+import { defineModule } from './sdk.mjs';
+import { gitToplevel } from './helpers.mjs';
+
+export default defineModule({
+  id: 'git-pulse',
+  name: 'Git Pulse',
+  vendor: 'MADRE',
+  summary: 'Type /git in the composer to bring the repository\'s branch, uncommitted changes, recent commits or diff stats into the room as a shared fact card, read-only, without spending an agent turn.',
+  creates: ['nothing: read-only git commands run inside the project'],
+  requires: ['the project is a git repository'],
+  commands: ['/git status', '/git log [n]', '/git diff', '/git branches'],
+  card: 'fixed',
+  async status(ctx) {
+    const isRepo = await gitToplevel(ctx.projectRoot);
+    return {
+      status: { installed: Boolean(isRepo), detail: isRepo ? 'on · project is a git repository' : 'not a git repository' },
+      preflight: isRepo ? { ok: true, problems: [] } : { ok: false, problems: ['Run `git init` in the project to use /git.'] },
+      install: { display: '/git in the composer', platforms: [] },
+      fixed: true,
+    };
+  },
+  async toggle() { return { status: 405, body: { error: 'Git Pulse has no switch: it is on wherever the project is a git repository.' } }; },
+});

package/src/modules/helpers.mjs

@@ -0,0 +1,30 @@
+import { execFile } from 'node:child_process';
+import { access, readFile, realpath } from 'node:fs/promises';
+import { delimiter, join } from 'node:path';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+export async function readJson(path) {
+  try { return JSON.parse(await readFile(path, 'utf8')); } catch { return null; }
+}
+
+// Where does git think this project lives? AHP+ pins itself to the git root,
+// so a project inside a bigger repository (or a home directory that was
+// accidentally `git init`ed) would receive .ahp/ somewhere else entirely.
+export async function gitToplevel(projectRoot) {
+  try {
+    const { stdout } = await execFileAsync('git', ['-C', projectRoot, 'rev-parse', '--show-toplevel'], { timeout: 5000 });
+    return await realpath(stdout.trim()).catch(() => stdout.trim());
+  } catch {
+    return null;
+  }
+}
+
+export async function findOnPath(name, envPath = process.env.PATH ?? '') {
+  for (const directory of envPath.split(delimiter).filter(Boolean)) {
+    const candidate = join(directory, name);
+    if (await access(candidate).then(() => true, () => false)) return candidate;
+  }
+  return null;
+}

package/src/modules/image-studio.mjs

@@ -0,0 +1,39 @@
+// Image Studio: MADRE's own MCP image server on the Gemini image models, for
+// the CLIs that cannot draw natively. A switch and a model in config.json.
+
+import { defineModule } from './sdk.mjs';
+
+const MODELS = ['gemini-2.5-flash-image', 'gemini-3.1-flash-image', 'gemini-3-pro-image'];
+
+export default defineModule({
+  id: 'image-studio',
+  configKey: 'imageStudio',
+  name: 'Image Studio',
+  vendor: 'MADRE · Gemini API',
+  summary: 'Gives Gemini CLI, Claude Code and OpenCode an image-generation tool through a MADRE-owned MCP server on the Gemini API image models, using your own Gemini key and credits. Attached only inside a creation lease with the image scope on.',
+  creates: ['nothing in the project: images land in the lease directory like any artifact', 'an "image-studio" entry in ~/.pulse/config.json', 'an MCP server process per turn, started and stopped by the room'],
+  requires: ['a Gemini API key with credits (the key the Gemini CLI stores, or GEMINI_API_KEY)'],
+  models: MODELS,
+  settings: { enabled: false, model: MODELS[0] },
+  card: 'image-studio',
+  async status(ctx) {
+    const key = await ctx.services.imageKey();
+    const model = ctx.settings.model ?? MODELS[0];
+    return {
+      model,
+      status: { installed: Boolean(ctx.settings.enabled), detail: ctx.settings.enabled ? `on · ${model}${key ? '' : ' · no Gemini key found'}` : key ? 'key found' : 'no Gemini key found' },
+      preflight: key ? { ok: true, problems: [] } : { ok: false, problems: ['No Gemini API key: sign in with the Gemini CLI (/auth → API key) or set GEMINI_API_KEY. Image models bill against that key.'] },
+      install: { display: ctx.settings.enabled ? 'disable Image Studio' : 'enable Image Studio (config.json)', platforms: ['gemini', 'claude', 'opencode'] },
+    };
+  },
+  async toggle(ctx, payload) {
+    const enabled = !ctx.settings.enabled;
+    const key = await ctx.services.imageKey();
+    if (enabled && !key) return { status: 412, body: { error: 'No Gemini API key found. Sign in with the Gemini CLI (/auth → API key) or set GEMINI_API_KEY, then enable Image Studio.' } };
+    const model = typeof payload?.model === 'string' && payload.model ? payload.model : (ctx.settings.model ?? MODELS[0]);
+    await ctx.updateConfig({ modules: { ...(ctx.config.modules ?? {}), imageStudio: { enabled, model } } });
+    ctx.services.setImageModule({ enabled, model });
+    await ctx.record('extension.toggled', { id: 'image-studio', name: 'Image Studio', enabled, model });
+    return { status: 200, body: { enabled, model, capabilities: ctx.room.capabilities() } };
+  },
+});

package/src/modules/index.mjs

@@ -0,0 +1,21 @@
+// The registry. Order is the order MODULES shows.
+import ahp from './ahp.mjs';
+import imageStudio from './image-studio.mjs';
+import gitPulse from './git-pulse.mjs';
+import ashcode from './ashcode.mjs';
+import ripley from './ripley.mjs';
+import ollama from './ollama.mjs';
+import { matchRoute } from './sdk.mjs';
+
+export const MODULES = [ahp, imageStudio, gitPulse, ashcode, ripley, ollama];
+export const moduleById = (id) => MODULES.find((module) => module.id === id) ?? null;
+export function describeModules(ctx) { return Promise.all(MODULES.map((module) => module.describe(ctx))); }
+// One flat list of every route a module serves, with the module attached.
+export function findModuleRoute(method, pathname) {
+  for (const module of MODULES) {
+    const hit = matchRoute(module.routes, method, pathname);
+    if (hit) return { module, ...hit };
+  }
+  return null;
+}
+export { defineModule } from './sdk.mjs';

package/src/modules/ollama.mjs

@@ -0,0 +1,56 @@
+// OLLAMA: local intelligence. Embeddings and distillation on this machine when
+// Ollama runs. The server offers the wiring through ctx.services.ollama.
+
+import { defineModule } from './sdk.mjs';
+import { RECOMMENDED } from '../ollama.mjs';
+
+export default defineModule({
+  id: 'ollama',
+  name: 'OLLAMA',
+  vendor: 'MADRE · LOCAL INTELLIGENCE',
+  summary: 'Recall by meaning and memory distillation on this machine through Ollama: no provider tokens, nothing leaves. Needs Ollama running with an embedding model and a chat model; MADRE can pull the recommended ones.',
+  creates: ['nothing in the project', 'an ollama block in ~/.pulse/config.json', 'models in Ollama\'s own store when you press PULL'],
+  requires: ['Ollama installed and running (ollama serve, or the Ollama app)'],
+  settings: { enabled: true, embeddings: true, archivist: true, agent: true },
+  card: 'ollama',
+  async status(ctx) {
+    const probe = ctx.services.ollama?.state() ?? { running: false, models: [], embedModel: null, chatModel: null };
+    const settings = ctx.settings;
+    const roles = [settings.embeddings && probe.embedModel ? `embeddings · ${probe.embedModel}` : null, settings.archivist && probe.chatModel ? `archivist · ${probe.chatModel}` : null, settings.agent !== false && probe.chatModel ? '@madre in the room' : null].filter(Boolean);
+    const detail = !probe.running ? 'not running · start Ollama and RECHECK'
+      : !settings.enabled ? `off · ${probe.models.length} model${probe.models.length === 1 ? '' : 's'} available`
+        : roles.length ? `on · ${roles.join(' · ')}` : 'on · no usable model yet · PULL one';
+    return {
+      models: probe.models.map((model) => model.name),
+      status: { installed: settings.enabled && probe.running && roles.length > 0, detail },
+      ollama: { ...probe, settings },
+      recommended: RECOMMENDED,
+      preflight: probe.running ? { ok: true, problems: [] } : { ok: false, problems: ['Ollama is not running: open the Ollama app or run `ollama serve`, then RECHECK.'] },
+      install: { display: settings.enabled ? 'disable Ollama' : 'enable Ollama (config.json)', platforms: [] },
+    };
+  },
+  async toggle(ctx) {
+    const enabled = !(ctx.settings.enabled ?? true);
+    await ctx.updateConfig({ modules: { ...(ctx.config.modules ?? {}), ollama: { ...(ctx.config.modules?.ollama ?? {}), enabled } } });
+    const status = await ctx.services.ollama.wire();
+    await ctx.record('extension.toggled', { id: 'ollama', name: 'OLLAMA', enabled });
+    return { status: 200, body: { enabled, ollama: status } };
+  },
+  routes: [
+    { method: 'GET', path: '/api/ollama', handler: async (ctx) => ({ status: 200, body: { ollama: await ctx.services.ollama.wire({ probe: false }), recommended: RECOMMENDED } }) },
+    { method: 'POST', path: '/api/ollama/probe', handler: async (ctx) => ({ status: 200, body: { ollama: await ctx.services.ollama.wire(), recommended: RECOMMENDED } }) },
+    { method: 'POST', path: '/api/ollama/settings', handler: async (ctx, { payload }) => {
+      const next = { ...(ctx.config.modules?.ollama ?? {}) };
+      for (const key of ['embeddings', 'archivist', 'agent', 'enabled']) if (typeof payload[key] === 'boolean') next[key] = payload[key];
+      await ctx.updateConfig({ modules: { ...(ctx.config.modules ?? {}), ollama: next } });
+      return { status: 200, body: { ollama: await ctx.services.ollama.wire({ probe: false }) } };
+    } },
+    { method: 'POST', path: '/api/ollama/pull', handler: async (ctx, { payload }) => {
+      const model = String(payload.model ?? '').trim();
+      if (!/^[a-z0-9][a-z0-9._:/-]{1,80}$/i.test(model)) return { status: 400, body: { error: 'Give a model name like nomic-embed-text or qwen2.5:3b.' } };
+      if (!ctx.services.ollama.state().running) return { status: 412, body: { error: 'Ollama is not running.' } };
+      const started = await ctx.services.ollama.pull(model);
+      return started.ok ? { status: 202, body: { pulling: model } } : { status: 409, body: { error: started.error } };
+    } },
+  ],
+});

package/src/modules/ripley.mjs

@@ -0,0 +1,20 @@
+// RIPLEY: the file viewer renders HTML, SVG and Markdown inside a sealed frame.
+// A switch in config.json, read live by the preview route.
+
+import { defineModule } from './sdk.mjs';
+
+export default defineModule({
+  id: 'ripley',
+  name: 'RIPLEY',
+  vendor: 'MADRE · PREVIEW',
+  summary: 'Renders HTML, SVG and Markdown from the project and from .pulse/out in the file viewer, inside a sealed frame: scripts run but nothing leaves, nothing is stored, nothing reaches MADRE. Nothing leaves the room.',
+  creates: ['nothing in the project', 'a ripley switch in ~/.pulse/config.json'],
+  card: 'ripley',
+  async status(ctx) {
+    return {
+      status: { installed: Boolean(ctx.settings.enabled), detail: ctx.settings.enabled ? 'on · PREVIEW in the file viewer' : 'off · files show as source' },
+      install: { display: ctx.settings.enabled ? 'disable RIPLEY' : 'enable RIPLEY (config.json)', platforms: [] },
+      fixed: false,
+    };
+  },
+});

package/src/modules/sdk.mjs

@@ -0,0 +1,78 @@
+// MADRE's module SDK. A module is one file: what it is, the settings it keeps
+// in ~/.pulse/config.json, how it describes itself to MODULES, what its switch
+// does, the routes it serves and the events it listens to. The server builds a
+// context (ctx) per call and hands it in; the module never reaches for globals.
+//
+//   ctx = { projectRoot, stateRoot, config, settings, env, agents, room, readConfig(), updateConfig(patch),
+//           record(type, payload), services: { ... what the server offers } }
+//
+// Kinds: 'builtin' switches MADRE's own behaviour (config.json only);
+// 'installer' writes into the project through a confirmed command.
+
+const camel = (id) => id.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+
+export function defineModule(spec) {
+  if (!spec?.id || !/^[a-z][a-z0-9-]*$/.test(spec.id)) throw new Error(`Module id must be kebab-case: ${spec?.id}`);
+  if (!spec.name) throw new Error(`Module ${spec.id} needs a name.`);
+  const kind = spec.kind ?? 'builtin';
+  const configKey = spec.configKey ?? camel(spec.id);
+  const defaults = { ...(kind === 'builtin' ? { enabled: false } : {}), ...(spec.settings ?? {}) };
+  const base = {
+    id: spec.id, kind, name: spec.name, vendor: spec.vendor ?? 'MADRE', package: spec.package ?? null, version: spec.version ?? '0.1.0',
+    summary: spec.summary ?? '', creates: spec.creates ?? [], requires: spec.requires ?? [], models: spec.models ?? [], commands: spec.commands,
+    card: spec.card ?? (kind === 'builtin' ? 'switch' : 'installer'),
+  };
+  const settingsFrom = (config) => ({ ...defaults, ...(config?.modules?.[configKey] ?? {}) });
+  const module = {
+    ...base,
+    configKey,
+    defaults,
+    settingsFrom,
+    routes: (spec.routes ?? []).map((route) => ({ ...route, method: route.method.toUpperCase() })),
+    onEvent: spec.onEvent ?? null,
+    conditions: spec.conditions ?? [],
+    // Legacy installer hooks, kept on the object so the confirm-and-run path can use them.
+    detect: spec.detect ?? null,
+    preflight: spec.preflight ?? null,
+    installCommand: spec.installCommand ?? null,
+
+    // What MODULES shows: base fields plus status, preflight, install line and whatever the module adds.
+    async describe(ctx) {
+      const settings = settingsFrom(ctx.config);
+      const own = spec.status ? await spec.status({ ...ctx, settings }) : {};
+      const installed = own.installed ?? (kind === 'builtin' ? Boolean(settings.enabled) : false);
+      return {
+        ...base,
+        ...own,
+        status: own.status ?? { installed, detail: own.detail ?? (installed ? 'on' : 'off') },
+        preflight: own.preflight ?? { ok: true, problems: [] },
+        install: own.install ?? (kind === 'builtin' ? { display: installed ? `disable ${base.name}` : `enable ${base.name} (config.json)`, platforms: [] } : { display: '', platforms: [] }),
+      };
+    },
+
+    // The switch. Default for builtins: flip `enabled`, persist, tell the room.
+    // A module may guard it (`confirm`) or replace it (`toggle`).
+    toggle: kind === 'builtin' || spec.toggle ? async (ctx, payload = {}) => {
+      const settings = settingsFrom(ctx.config);
+      if (spec.toggle) return spec.toggle({ ...ctx, settings }, payload);
+      const enabled = !settings.enabled;
+      if (enabled && spec.confirm && payload.confirm !== true) return { status: 400, body: { error: spec.confirm } };
+      await ctx.updateConfig({ modules: { ...(ctx.config.modules ?? {}), [configKey]: { ...(ctx.config.modules?.[configKey] ?? {}), enabled } } });
+      const after = spec.onToggle ? await spec.onToggle({ ...ctx, settings: { ...settings, enabled } }, enabled) : null;
+      await ctx.record('extension.toggled', { id: spec.id, name: base.name, enabled, ...(spec.toggledEvent ?? {}) });
+      return { status: 200, body: { enabled, ...(after ?? {}), ...(spec.toggledBody?.(enabled) ?? {}) } };
+    } : null,
+  };
+  return Object.freeze(module);
+}
+
+// Matches a request against a module's routes; params come from a RegExp path.
+export function matchRoute(routes, method, pathname) {
+  for (const route of routes) {
+    if (route.method !== method) continue;
+    if (typeof route.path === 'string') { if (route.path === pathname) return { route, params: [] }; continue; }
+    const match = pathname.match(route.path);
+    if (match) return { route, params: match.slice(1) };
+  }
+  return null;
+}

package/src/ollama.mjs

@@ -0,0 +1,118 @@
+// Ollama: the local intelligence MADRE leans on when it is there. Embeddings
+// for recall by meaning and a model to distil memories, both on this machine,
+// so remembering costs no tokens elsewhere and nothing leaves. Nothing here is
+// required: without Ollama every path falls back to what it did before.
+
+export const DEFAULT_OLLAMA_HOST = 'http://127.0.0.1:11434';
+// Embedding models we know how to talk to, best first.
+export const EMBED_MODELS = ['nomic-embed-text', 'mxbai-embed-large', 'snowflake-arctic-embed', 'all-minilm', 'bge-m3'];
+// Chat models that follow instructions well enough to distil, best first for a 16 GB machine.
+// General chat models first: @madre speaks for the room in the human's language, and coder
+// models drift into other voices. A coder is taken only when nothing else is there.
+export const CHAT_MODELS = ['qwen2.5:7b', 'llama3.1:8b', 'gemma3:4b', 'qwen2.5:3b', 'llama3.2:3b', 'qwen2.5:1.5b', 'llama3.2:1b', 'qwen2.5-coder:7b', 'qwen2.5-coder:1.5b'];
+// Ollama's default window is 4k tokens and it drops the OLDEST text when a prompt overflows:
+// the system prompt goes first. Every MADRE call asks for a wider window.
+export const DEFAULT_NUM_CTX = 8192;
+export const RECOMMENDED = { embed: 'nomic-embed-text', chat: 'qwen2.5:3b' };
+
+export function ollamaHost(env = process.env) {
+  return (env.PULSE_OLLAMA_HOST ?? env.OLLAMA_HOST ?? DEFAULT_OLLAMA_HOST).replace(/\/$/, '').replace(/^(?!https?:\/\/)/, 'http://');
+}
+
+const isEmbedModel = (model) => EMBED_MODELS.some((name) => model.name.startsWith(name)) || /embed|minilm|bge/i.test(model.name) || /bert|nomic/i.test(model.details?.family ?? '');
+function pick(models, preferred, env) {
+  const names = models.map((model) => model.name);
+  const bare = (name) => name.replace(/:latest$/, '');
+  if (env && names.some((name) => bare(name) === bare(env))) return names.find((name) => bare(name) === bare(env));
+  for (const want of preferred) { const hit = names.find((name) => bare(name) === want || bare(name).startsWith(`${want}`)); if (hit) return hit; }
+  return names[0] ?? null;
+}
+
+// Is Ollama there, and what can it do? Quick, never throws.
+export async function probeOllama({ host = ollamaHost(), fetchImpl = globalThis.fetch, timeoutMs = 1500, env = process.env } = {}) {
+  try {
+    const response = await fetchImpl(`${host}/api/tags`, { signal: AbortSignal.timeout(timeoutMs) });
+    if (!response.ok) return { running: false, host, models: [], embedModel: null, chatModel: null, error: `HTTP ${response.status}` };
+    const payload = await response.json();
+    const models = (payload.models ?? []).map((model) => ({ name: model.name, size: model.size ?? 0, family: model.details?.family ?? '', details: model.details ?? {} }));
+    const embeds = models.filter(isEmbedModel);
+    const chats = models.filter((model) => !isEmbedModel(model));
+    return {
+      running: true, host, models,
+      embedModel: pick(embeds, EMBED_MODELS, env.PULSE_OLLAMA_EMBED_MODEL),
+      chatModel: pick(chats, CHAT_MODELS, env.PULSE_OLLAMA_MODEL),
+    };
+  } catch (error) {
+    return { running: false, host, models: [], embedModel: null, chatModel: null, error: error.message };
+  }
+}
+
+// An embedder the memory understands: { model, dims, embed(texts, { query }) }.
+// nomic wants a task prefix; the others take the text as it is.
+export function ollamaEmbedder({ host = ollamaHost(), model, fetchImpl = globalThis.fetch, timeoutMs = 60000 } = {}) {
+  if (!model) return null;
+  const nomic = model.startsWith('nomic');
+  return {
+    model: `ollama:${model}`,
+    dims: null,
+    local: true,
+    async embed(texts, { query = false } = {}) {
+      const input = texts.map((text) => `${nomic ? (query ? 'search_query: ' : 'search_document: ') : ''}${String(text ?? '').slice(0, 2000) || ' '}`);
+      const response = await fetchImpl(`${host}/api/embed`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ model, input }), signal: AbortSignal.timeout(timeoutMs) });
+      if (!response.ok) throw new Error(`Ollama embeddings HTTP ${response.status}: ${(await response.text().catch(() => '')).slice(0, 200)}`);
+      const payload = await response.json();
+      const vectors = payload.embeddings ?? [];
+      if (vectors.length !== texts.length) throw new Error(`Ollama returned ${vectors.length} vectors for ${texts.length} texts.`);
+      return vectors.map((values) => Float32Array.from(values));
+    },
+  };
+}
+
+// One answer from a local model. `json: true` asks Ollama for a JSON object.
+export async function ollamaGenerate({ host = ollamaHost(), model, prompt, system = null, json = false, fetchImpl = globalThis.fetch, timeoutMs = 180000, temperature = 0.2, numCtx = DEFAULT_NUM_CTX } = {}) {
+  const started = Date.now();
+  const messages = [...(system ? [{ role: 'system', content: system }] : []), { role: 'user', content: prompt }];
+  const response = await fetchImpl(`${host}/api/chat`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ model, messages, stream: false, options: { temperature, num_ctx: numCtx }, ...(json ? { format: 'json' } : {}) }), signal: AbortSignal.timeout(timeoutMs) });
+  if (!response.ok) throw new Error(`Ollama HTTP ${response.status}: ${(await response.text().catch(() => '')).slice(0, 200)}`);
+  const payload = await response.json();
+  const inputTokens = payload.prompt_eval_count ?? 0;
+  const outputTokens = payload.eval_count ?? 0;
+  return {
+    text: String(payload.message?.content ?? '').trim(),
+    usage: { inputTokens, outputTokens, cachedInputTokens: 0, reasoningTokens: 0, totalTokens: inputTokens + outputTokens, costUsd: 0, source: 'ollama', local: true, model },
+    elapsedMs: Date.now() - started,
+  };
+}
+
+// The shape the room's invokers have: ({ prompt, timeoutMs }) → { text, usage }.
+export function ollamaInvoker({ host = ollamaHost(), model, fetchImpl = globalThis.fetch } = {}) {
+  if (!model) return null;
+  return async ({ prompt, timeoutMs = 180000, json = false }) => ollamaGenerate({ host, model, prompt, json, fetchImpl, timeoutMs });
+}
+
+// Pulls a model, reporting progress lines as Ollama streams them.
+export async function pullModel({ host = ollamaHost(), model, fetchImpl = globalThis.fetch, onLine = () => {}, timeoutMs = 30 * 60 * 1000 } = {}) {
+  const response = await fetchImpl(`${host}/api/pull`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ model, stream: true }), signal: AbortSignal.timeout(timeoutMs) });
+  if (!response.ok) throw new Error(`Ollama pull HTTP ${response.status}: ${(await response.text().catch(() => '')).slice(0, 200)}`);
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+  let lastStatus = '';
+  for (;;) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    buffer += decoder.decode(value, { stream: true });
+    let index;
+    while ((index = buffer.indexOf('\n')) >= 0) {
+      const line = buffer.slice(0, index).trim();
+      buffer = buffer.slice(index + 1);
+      if (!line) continue;
+      let event;
+      try { event = JSON.parse(line); } catch { continue; }
+      if (event.error) throw new Error(event.error);
+      const status = event.total ? `${event.status} · ${Math.round((event.completed ?? 0) / event.total * 100)}%` : event.status;
+      if (status && status !== lastStatus) { lastStatus = status; onLine(status); }
+    }
+  }
+  return { model };
+}

package/src/room/archivist.mjs

@@ -0,0 +1,141 @@
+// The archivist: every so often the cheapest allowed agent reads what nobody
+// has distilled and keeps the few notes worth remembering. Scheduling by count
+// or by quiet, one batch per run, a bench for whoever fails, a report to the
+// room either way. The room hands in what it knows through `deps`.
+
+import { pickDistiller, distillPrompt, parseDistillation, OLLAMA_ARCHIVIST } from '../distiller.mjs';
+
+export const BENCH_MS = 30 * 60 * 1000;
+
+export function distillDefaults(distill = {}, env = process.env) {
+  return {
+    enabled: distill.enabled ?? env.PULSE_DISTILL !== '0',
+    every: Math.max(1, Number(distill.every ?? env.PULSE_DISTILL_EVERY ?? 10)),
+    idleMs: Math.max(1000, Number(distill.idleMs ?? env.PULSE_DISTILL_IDLE_MS ?? 10 * 60 * 1000)),
+    maxChars: Math.max(500, Number(distill.maxChars ?? env.PULSE_DISTILL_MAX_CHARS ?? 6000)),
+    agent: distill.agent ?? env.PULSE_DISTILL_AGENT ?? null,
+    model: distill.model ?? env.PULSE_DISTILL_MODEL ?? null,
+    allowed: Array.isArray(distill.allowed) && distill.allowed.length ? [...distill.allowed] : null,   // who may distil; null = anyone
+  };
+}
+
+export class Archivist {
+  #memory;
+  #settings;
+  #deps;
+  #timer = null;
+  #running = null;
+  #failures = new Map();   // fromSequence -> failed attempts on that batch
+  #bench = new Map();      // agent -> until (ms)
+
+  // deps: agents(), invokers(), busyAgents(), turnsInFlight(), timeoutFor(id), localTimeoutMs(), projectName(), emit(type, payload), recordUsage(agent, usage), stopped(), failureMessage(error)
+  constructor({ memory, settings, deps }) {
+    this.#memory = memory;
+    this.#settings = settings;
+    this.#deps = deps;
+  }
+  get inflight() { return this.#running; }
+  settings() { return { ...this.#settings, allowed: this.#settings.allowed ? [...this.#settings.allowed] : null }; }
+
+  configure(patch = {}) {
+    const s = this.#settings;
+    if (typeof patch.enabled === 'boolean') s.enabled = patch.enabled;
+    if (Number(patch.every) >= 1) s.every = Math.trunc(Number(patch.every));
+    if (Number(patch.idleMs) >= 1000) s.idleMs = Math.trunc(Number(patch.idleMs));
+    if (Number(patch.maxChars) >= 500) s.maxChars = Math.trunc(Number(patch.maxChars));
+    if ('agent' in patch) s.agent = patch.agent ? String(patch.agent) : null;
+    if ('allowed' in patch) s.allowed = Array.isArray(patch.allowed) && patch.allowed.length ? [...patch.allowed] : null;
+    this.#bench.clear();
+    return this.settings();
+  }
+
+  // After a turn: run now if enough piled up and the room is quiet, else wait for quiet.
+  schedule() {
+    if (this.#deps.stopped() || !this.#memory || !this.#settings.enabled) return;
+    clearTimeout(this.#timer);
+    this.#timer = null;
+    let pending = 0;
+    try { pending = this.#memory.undistilledCount(); } catch { return; }
+    if (pending < 2) return;
+    const wait = pending >= this.#settings.every ? (this.#deps.turnsInFlight() ? 3000 : 0) : this.#settings.idleMs;
+    this.#timer = setTimeout(() => {
+      this.#timer = null;
+      if (this.#deps.turnsInFlight()) { this.schedule(); return; }
+      void this.runNow();
+    }, wait);
+    this.#timer.unref?.();
+  }
+
+  #candidates() {
+    const invokers = this.#deps.invokers();
+    // @madre answers questions; the archive is written by the Ollama archivist itself.
+    const agents = this.#deps.agents().filter((agent) => agent.adapter !== 'madre-local');
+    const everyone = invokers.ollama ? [OLLAMA_ARCHIVIST, ...agents] : agents;
+    return this.#settings.allowed ? everyone.filter((agent) => this.#settings.allowed.includes(agent.id)) : everyone;
+  }
+
+  // One batch: the cheapest usable agent reads it, well-formed notes are kept,
+  // the batch is marked, tokens are counted. A batch that fails three times is
+  // skipped so a poisoned range cannot stall the archive; whoever failed sits out.
+  async runNow() {
+    if (!this.#memory) return null;
+    if (this.#running) return this.#running;
+    this.#running = (async () => {
+      const batch = this.#memory.undistilled({ maxChars: this.#settings.maxChars });
+      if (!batch.entries.length) return null;
+      const invokers = this.#deps.invokers();
+      const busy = this.#deps.busyAgents();
+      const now = Date.now();
+      for (const [id, until] of this.#bench) if (until <= now) this.#bench.delete(id);
+      const benched = new Set(this.#bench.keys());
+      const candidates = this.#candidates();
+      let agent = pickDistiller(candidates, { preferred: this.#settings.agent, busy, invokers, benched });
+      if (!agent && benched.size) { this.#bench.clear(); agent = pickDistiller(candidates, { preferred: this.#settings.agent, busy, invokers }); }
+      if (!agent) return null;
+      const started = Date.now();
+      try {
+        const local = agent.adapter === 'ollama';
+        const prompt = distillPrompt({ entries: batch.entries, projectName: this.#deps.projectName(), existing: this.#memory.memories({ limit: 12 }), json: local });
+        const result = await invokers[agent.adapter]({ executable: agent.path, projectRoot: this.#deps.projectRoot(), prompt, timeoutMs: local ? this.#deps.localTimeoutMs() : this.#deps.timeoutFor(agent.id), model: local ? null : this.#settings.model, json: local, attachments: [], lease: null, scopes: { web: false, imageGen: false }, imageStudio: null });
+        const memories = parseDistillation(result?.text, { fromSequence: batch.fromSequence, throughSequence: batch.throughSequence });
+        const added = this.#memory.addMemories(memories, { agent: agent.id, fromSequence: batch.fromSequence, throughSequence: batch.throughSequence });
+        this.#memory.markDistilled(batch.sequences);
+        this.#failures.delete(batch.fromSequence);
+        // Local tokens cost nothing and count against no provider budget; they are reported, not charged.
+        if (!local) await this.#deps.recordUsage(agent.id, result?.usage ?? null);
+        const kinds = {};
+        for (const memory of memories) kinds[memory.kind] = (kinds[memory.kind] ?? 0) + 1;
+        const report = { agent: agent.id, local, model: local ? result?.usage?.model ?? null : this.#settings.model, tokens: result?.usage?.totalTokens ?? null, added, parsed: memories.length, considered: batch.entries.length, fromSequence: batch.fromSequence, throughSequence: batch.throughSequence, remaining: batch.remaining, kinds, elapsedMs: Date.now() - started, total: this.#memory.memoryCount() };
+        await this.#deps.emit('memory.distilled', report);
+        return report;
+      } catch (error) {
+        const attempts = (this.#failures.get(batch.fromSequence) ?? 0) + 1;
+        this.#failures.set(batch.fromSequence, attempts);
+        const skipped = attempts >= 3;
+        if (skipped) { this.#memory.markDistilled(batch.sequences); this.#failures.delete(batch.fromSequence); }
+        this.#bench.set(agent.id, Date.now() + BENCH_MS);
+        const next = pickDistiller(candidates, { preferred: this.#settings.agent, busy: new Set(), invokers, benched: new Set(this.#bench.keys()) });
+        const report = { agent: agent.id, error: this.#deps.failureMessage(error), attempts, skipped, next: next?.id ?? null, fromSequence: batch.fromSequence, throughSequence: batch.throughSequence, considered: batch.entries.length, remaining: batch.remaining };
+        await this.#deps.emit('memory.distilled', report);
+        return report;
+      }
+    })().finally(() => { this.#running = null; });
+    return this.#running;
+  }
+
+  // Tests: run a distillation that is due by count without waiting for its
+  // timer, leave an idle wait alone, and let a run in flight finish.
+  async settle() {
+    if (this.#timer && !this.#deps.turnsInFlight() && this.#memory && this.#memory.undistilledCount() >= this.#settings.every) {
+      clearTimeout(this.#timer);
+      this.#timer = null;
+      await this.runNow();
+    }
+    await this.#running;
+  }
+
+  stop() {
+    clearTimeout(this.#timer);
+    this.#timer = null;
+  }
+}

package/src/room/attachments.mjs

@@ -0,0 +1,15 @@
+// Human uploads, stored under the room (never in the project). Registered
+// here so a message can reference them by id; the ledger lets a restarted
+// room rebuild the registry.
+
+import { dirname } from 'node:path';
+
+export class Attachments {
+  #records = new Map();
+  register(record) {
+    this.#records.set(record.id, { ...record, dir: dirname(record.path) });
+    return this.#records.get(record.id);
+  }
+  restore(records) { for (const record of records) this.#records.set(record.id, record); }
+  get(id) { return this.#records.get(id) ?? null; }
+}

package/src/room/budget.mjs

@@ -0,0 +1,83 @@
+// The local token budget: a rolling window per agent (five hours, like the
+// providers' short windows), raw totals for the record, and the seeding of the
+// usage sentinel from the ledger on start.
+
+// What a turn costs against MADRE's local budget. Cache reads are close to
+// free at every provider, so they weigh a tenth; Codex counts cached tokens
+// inside its input, so they are taken out before weighing.
+export function budgetTokens(usage = {}) {
+  if (usage.local) return 0;
+  const n = (value) => (Number.isFinite(Number(value)) ? Number(value) : 0);
+  const cached = n(usage.cachedInputTokens);
+  const input = usage.source === 'codex-json' ? Math.max(0, n(usage.inputTokens) - cached) : n(usage.inputTokens);
+  const fresh = input + n(usage.cacheCreationInputTokens) + n(usage.outputTokens) + n(usage.reasoningTokens);
+  if (!fresh && !cached) return n(usage.totalTokens);
+  return Math.round(fresh + cached * 0.1);
+}
+
+export class Budget {
+  #window = new Map();      // agent -> [{ at, spent }]
+  #raw = new Map();         // agent -> raw total tokens ever
+  #windowMs;
+  softBudget;
+
+  constructor({ softBudget = 500000, windowMs = Number(process.env.PULSE_BUDGET_WINDOW_MS ?? 5 * 3600 * 1000) } = {}) {
+    this.softBudget = softBudget;
+    this.#windowMs = windowMs;
+  }
+  get windowMs() { return this.#windowMs; }
+
+  // Replays usage from the ledger and tells the sentinel where each ring stood.
+  seed(events, sentinel) {
+    for (const event of events) {
+      if (event.type === 'usage.recorded') {
+        this.#raw.set(event.payload.agent, event.payload.roomTotalTokens);
+        const at = new Date(event.timestamp ?? 0).getTime() || 0;
+        const spent = event.payload.budgetTokens ?? budgetTokens(event.payload.usage ?? {});
+        const list = this.#window.get(event.payload.agent) ?? [];
+        list.push({ at, spent });
+        this.#window.set(event.payload.agent, list);
+      }
+      if (sentinel && (event.type === 'quota.updated' || event.type === 'limit.warning')) {
+        // An old report whose window has since reset must not seed a full ring.
+        const passed = event.payload.resetAt && new Date(event.payload.resetAt).getTime() <= Date.now();
+        sentinel.seed(passed ? { ...event.payload, usedPercent: 0 } : event.payload);
+      }
+    }
+    if (sentinel && Number.isFinite(this.softBudget) && this.softBudget > 0) {
+      for (const agent of this.#window.keys()) {
+        sentinel.seed({ agent, usedPercent: (this.windowTotal(agent) / this.softBudget) * 100, source: 'room-soft-budget' });
+      }
+    }
+  }
+
+  // Budget tokens spent by an agent inside the rolling window, dropping what fell out.
+  windowTotal(agent, now = Date.now()) {
+    const list = (this.#window.get(agent) ?? []).filter((entry) => now - entry.at < this.#windowMs);
+    this.#window.set(agent, list);
+    return list.reduce((sum, entry) => sum + entry.spent, 0);
+  }
+
+  // The local window as the UI should see it now: totals recomputed so a ring
+  // empties when the window rolls over, even without a new turn.
+  view(agents) {
+    const now = Date.now();
+    return Object.fromEntries(agents.map((agent) => {
+      const total = this.windowTotal(agent.id, now);
+      const oldest = (this.#window.get(agent.id) ?? [])[0]?.at ?? null;
+      return [agent.id, { tokens: total, rawTokens: this.#raw.get(agent.id) ?? 0, windowMs: this.#windowMs, rollsOverAt: oldest ? new Date(oldest + this.#windowMs).toISOString() : null }];
+    }));
+  }
+
+  // Charges a turn and returns what the ledger should record and what the ring shows.
+  record(agent, usage) {
+    const spent = budgetTokens(usage);
+    const list = this.#window.get(agent) ?? [];
+    list.push({ at: Date.now(), spent });
+    this.#window.set(agent, list);
+    const total = this.windowTotal(agent);
+    const rawTotal = (this.#raw.get(agent) ?? 0) + (usage.totalTokens ?? 0);
+    this.#raw.set(agent, rawTotal);
+    return { spent, total, rawTotal, windowMs: this.#windowMs, usedPercent: this.softBudget > 0 ? (total / this.softBudget) * 100 : null, projectedPercent: this.softBudget > 0 ? ((total + spent) / this.softBudget) * 100 : null };
+  }
+}