@jossuealcala/madre 0.2.2 → 0.3.0

package/src/dataset.mjs

@@ -0,0 +1,85 @@
+// The dataset behind MADRE AI: every exchange the room kept (never GHOST),
+// redacted, as chat pairs a small model can learn from, plus the distilled
+// notes. Written next to the room's ledger in the format mlx-lm and most
+// fine-tuners read: one {"messages": [...]} per line, split train / valid.
+// Export is the first step of roadmap 2c; training runs outside MADRE, on the
+// human's machine, from docs/training/.
+
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { redact } from './sentinel-errors.mjs';
+
+const MIN_ANSWER_CHARS = 40;
+
+function system(project, agent) {
+  return `You are @${agent} in the MADRE room of the project "${project}". Answer the human directly and concisely; distinguish facts from inference; name files, agents and numbers exactly.`;
+}
+
+// Pairs a user message with the assistant reply that answered it (parentMessageId).
+export function pairsFromEvents(events, { project = 'project', home, user } = {}) {
+  const users = new Map();
+  const pairs = [];
+  for (const event of events) {
+    if (event.type !== 'message.created' || event.ghost || !Number.isInteger(event.sequence)) continue;
+    const p = event.payload ?? {};
+    if (typeof p.text !== 'string' || !p.text.trim()) continue;
+    if (p.role === 'user') { users.set(p.messageId, { text: p.text, mode: p.mode ?? 1, sequence: event.sequence }); continue; }
+    if (p.role !== 'assistant' || p.status === 'delegated') continue;
+    const ask = users.get(p.parentMessageId);
+    if (!ask) continue;
+    const answer = (p.originalText ?? p.text).trim();
+    if (answer.length < MIN_ANSWER_CHARS) continue;
+    pairs.push({
+      kind: 'turn',
+      agent: p.sender,
+      mode: p.mode ?? ask.mode,
+      sequence: event.sequence,
+      at: event.timestamp,
+      messages: [
+        { role: 'system', content: system(project, p.sender) },
+        { role: 'user', content: redact(ask.text, { home, user }) },
+        { role: 'assistant', content: redact(answer, { home, user }) },
+      ],
+    });
+  }
+  return pairs;
+}
+
+// Distilled notes become recall pairs: "what does the room remember about …" → the note.
+export function pairsFromNotes(notes, { project = 'project', home, user } = {}) {
+  return notes.map((note) => ({
+    kind: 'note',
+    agent: 'madre',
+    mode: 1,
+    sequence: note.throughSequence,
+    at: note.created,
+    messages: [
+      { role: 'system', content: `You are @madre, the memory of the MADRE room of the project "${project}". Answer only from what the room decided and recorded.` },
+      { role: 'user', content: `What does the room remember about this? Kind: ${note.kind}. Topic: ${redact(note.text, { home, user }).split(/[.;:]/)[0].slice(0, 80)}` },
+      { role: 'assistant', content: `${redact(note.text, { home, user })} [#${note.fromSequence}${note.throughSequence !== note.fromSequence ? `–#${note.throughSequence}` : ''}]` },
+    ],
+  }));
+}
+
+// Deterministic split: the sequence decides, so re-exports keep lines on the same side.
+export function split(pairs, { validEvery = 10 } = {}) {
+  const train = [];
+  const valid = [];
+  for (const pair of pairs) (pair.sequence % validEvery === 0 ? valid : train).push(pair);
+  if (!valid.length && train.length > 1) valid.push(train.pop());
+  return { train, valid };
+}
+
+export async function exportDataset({ events, notes = [], dir, project = 'project', home, user }) {
+  const pairs = [...pairsFromEvents(events, { project, home, user }), ...pairsFromNotes(notes, { project, home, user })].sort((a, b) => a.sequence - b.sequence);
+  const { train, valid } = split(pairs);
+  await mkdir(dir, { recursive: true });
+  const line = (pair) => JSON.stringify({ messages: pair.messages });
+  await writeFile(join(dir, 'train.jsonl'), train.map(line).join('\n') + (train.length ? '\n' : ''));
+  await writeFile(join(dir, 'valid.jsonl'), valid.map(line).join('\n') + (valid.length ? '\n' : ''));
+  const byAgent = {};
+  for (const pair of pairs) byAgent[pair.agent] = (byAgent[pair.agent] ?? 0) + 1;
+  const manifest = { project, exportedAt: new Date().toISOString(), pairs: pairs.length, turns: pairs.filter((p) => p.kind === 'turn').length, notes: pairs.filter((p) => p.kind === 'note').length, train: train.length, valid: valid.length, byAgent, files: ['train.jsonl', 'valid.jsonl'], format: 'chat · {"messages":[{role,content}]} · mlx-lm / llama-factory / axolotl' };
+  await writeFile(join(dir, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`);
+  return { dir, ...manifest };
+}

package/src/distiller.mjs

@@ -6,7 +6,9 @@
 import { MEMORY_KINDS } from './memory.mjs';
 
 // Cheapest first, by the models these CLIs run by default.
-export const DISTILLER_ORDER = ['gemini', 'opencode', 'codex', 'claude'];
+// Ollama, when the room has it, is the cheapest of all: local and free.
+export const DISTILLER_ORDER = ['ollama', 'gemini', 'opencode', 'codex', 'claude'];
+export const OLLAMA_ARCHIVIST = { id: 'ollama', label: 'Ollama', detected: true, ready: true, adapter: 'ollama', path: null, version: null, local: true };
 export const MAX_MEMORIES_PER_RUN = 5;
 export const MAX_MEMORY_CHARS = 240;
 
@@ -26,7 +28,7 @@ export function pickDistiller(agents, { preferred = null, busy = new Set(), invo
   return agents.find(usable) ?? null;
 }
 
-export function distillPrompt({ entries, projectName = 'the project', existing = [] }) {
+export function distillPrompt({ entries, projectName = 'the project', existing = [], json = false }) {
   const transcript = entries.map((entry) => {
     const who = entry.role === 'command' ? entry.sender : `@${entry.sender}`;
     const to = entry.target && entry.target !== 'room' ? ` → ${entry.target === 'you' ? 'human' : `@${entry.target}`}` : '';
@@ -41,9 +43,11 @@ export function distillPrompt({ entries, projectName = 'the project', existing =
     `- preference: how the human wants things done or said`,
     `- question: something left open that a later turn should not forget`,
     'Skip greetings, restatements, transient status, anything a reader of the code would see anyway, and anything the exchanges do not actually establish.',
-    `Output only JSON lines, one object per memory, at most ${MAX_MEMORIES_PER_RUN}, nothing else:`,
-    `{"kind":"decision|fact|preference|question","text":"one self-contained sentence in the language the room uses, at most ${MAX_MEMORY_CHARS} characters, naming files, agents and numbers exactly","sources":[sequence numbers it comes from]}`,
-    'If nothing durable was said, output exactly: NONE',
+    json
+      ? `Output one JSON object and nothing else: {"memories":[...]} with at most ${MAX_MEMORIES_PER_RUN} items, each {"kind":"decision|fact|preference|question","text":"one self-contained sentence in the language the room uses, at most ${MAX_MEMORY_CHARS} characters, naming files, agents and numbers exactly","sources":[sequence numbers it comes from]}. If nothing durable was said: {"memories":[]}`
+      : `Output only JSON lines, one object per memory, at most ${MAX_MEMORIES_PER_RUN}, nothing else:`,
+    json ? null : `{"kind":"decision|fact|preference|question","text":"one self-contained sentence in the language the room uses, at most ${MAX_MEMORY_CHARS} characters, naming files, agents and numbers exactly","sources":[sequence numbers it comes from]}`,
+    json ? null : 'If nothing durable was said, output exactly: NONE',
     known,
     '<exchanges>',
     transcript,
@@ -56,7 +60,13 @@ export function distillPrompt({ entries, projectName = 'the project', existing =
 export function parseDistillation(text, { fromSequence, throughSequence } = {}) {
   const memories = [];
   const seen = new Set();
-  for (const raw of String(text ?? '').split(/\r?\n/)) {
+  // A whole JSON object with a memories array (what local models return under format=json) is unrolled into lines.
+  let source = String(text ?? '');
+  const object = source.trim().match(/^\{[\s\S]*\}$/);
+  if (object) {
+    try { const parsed = JSON.parse(object[0]); if (Array.isArray(parsed?.memories)) source = parsed.memories.map((item) => JSON.stringify(item)).join('\n'); } catch { /* fall through: line by line */ }
+  }
+  for (const raw of source.split(/\r?\n/)) {
     const line = raw.trim().replace(/^```(?:json)?$|^```$/g, '').replace(/^[-*]\s+/, '');
     const start = line.indexOf('{');
     const end = line.lastIndexOf('}');

package/src/embeddings.mjs

@@ -68,11 +68,17 @@ async function geminiEmbed(texts, { key, model, dims, query, fetchImpl, timeoutM
 }
 
 // The embedder the memory uses: { model, dims, embed(texts, { query }) } or null when off.
-export function createEmbedder({ key = null, env = process.env, fetchImpl = globalThis.fetch, timeoutMs = Number(env.PULSE_EMBED_TIMEOUT_MS ?? 8000) } = {}) {
+// Which embedder: PULSE_EMBED_PROVIDER=ollama|gemini|auto. Auto prefers Ollama
+// when it is running with an embedding model (local, free, private), then Gemini
+// when there is a key, then none.
+export function createEmbedder({ key = null, env = process.env, fetchImpl = globalThis.fetch, timeoutMs = Number(env.PULSE_EMBED_TIMEOUT_MS ?? 8000), ollama = null, ollamaEmbedder: makeOllama = null } = {}) {
   if (env.PULSE_EMBED === '0') return null;
   if (env.PULSE_EMBED_FAKE === '1') {
     return { model: 'fake-64', dims: 64, embed: async (texts) => texts.map((text) => fakeEmbedding(text)) };
   }
+  const provider = env.PULSE_EMBED_PROVIDER ?? 'auto';
+  if (provider !== 'gemini' && ollama?.running && ollama.embedModel && makeOllama) return makeOllama({ host: ollama.host, model: ollama.embedModel, fetchImpl });
+  if (provider === 'ollama') return null;
   if (!key) return null;
   const model = env.PULSE_EMBED_MODEL ?? DEFAULT_EMBED_MODEL;
   const dims = Number(env.PULSE_EMBED_DIMS ?? DEFAULT_EMBED_DIMS);

package/src/extensions.mjs

@@ -1,227 +1,27 @@
-import { execFile, spawn } from 'node:child_process';
-import { access, readFile, realpath } from 'node:fs/promises';
-import { delimiter, join, resolve } from 'node:path';
-import { promisify } from 'node:util';
-
-const execFileAsync = promisify(execFile);
-
-// Optional room modules. Built-ins only change MADRE's local configuration;
-// the external AHP+ installer can write into the selected project, so it
-// requires explicit confirmation and records that action in the durable log.
-
-async function readJson(path) {
-  try {
-    return JSON.parse(await readFile(path, 'utf8'));
-  } catch {
-    return null;
-  }
-}
-
-// AHP+ platform names for the agents MADRE knows about. Gemini has no AHP+
-// adapter yet, so it is simply not requested.
-const AHP_PLATFORMS = { codex: 'codex', claude: 'claude', opencode: 'opencode' };
-
-// 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;
-}
-
-export const EXTENSIONS = [
-  {
-    id: 'ahp',
-    name: 'AHP+',
-    vendor: 'Agent Handoff Protocol Plus',
-    package: '@jossuealcala/ahp-plus',
-    version: '1.4.1',
-    summary: 'Verified project state, checkpoints and handoffs between AI sessions, stored in .ahp/ next to your code.',
-    creates: ['.ahp/ with manifest, sessions, handoffs and evidence', 'a project-local pin of @jossuealcala/ahp-plus', 'IDE adapter files for the detected agents'],
-    async detect(projectRoot) {
-      const manifest = await readJson(join(projectRoot, '.ahp', 'manifest.json'));
-      if (!manifest) return { installed: false };
-      const pinned = await readJson(join(projectRoot, 'node_modules', '@jossuealcala', 'ahp-plus', 'package.json'));
-      return {
-        installed: true,
-        version: pinned?.version ?? null,
-        protocolVersion: manifest.protocol_version ?? null,
-        projectId: manifest.project_id ?? null,
-        detail: [pinned?.version ? `cli ${pinned.version}` : null, manifest.protocol_version ? `protocol ${manifest.protocol_version}` : null].filter(Boolean).join(' · '),
-      };
-    },
-    // Refuses before anything is written when the outcome would be wrong.
-    async preflight(projectRoot, { toplevel = gitToplevel, npx = findOnPath } = {}) {
-      const root = await realpath(projectRoot).catch(() => resolve(projectRoot));
-      const problems = [];
-      if (!(await npx('npx'))) problems.push('npx is not on PATH for the MADRE server; start MADRE from a terminal where `npx --version` works.');
-      const top = await toplevel(root);
-      if (!top) {
-        problems.push('The project is not a git repository. AHP+ pins itself to the git root: run `git init` in the project first.');
-      } else if (top !== root) {
-        problems.push(`The project's git root is ${top}, not the project itself. AHP+ would install there. Run \`git init\` inside the project, or remove the stray repository at ${top}.`);
-      }
-      return { ok: problems.length === 0, problems, gitRoot: top };
-    },
-    installCommand({ agents = [] }) {
-      const platforms = agents
-        .filter((agent) => agent.detected && AHP_PLATFORMS[agent.id])
-        .map((agent) => AHP_PLATFORMS[agent.id]);
-      const args = ['--yes', `${this.package}@${this.version}`, 'setup', '.'];
-      if (platforms.length) args.push('--platforms', platforms.join(','));
-      return { command: 'npx', args, platforms, display: ['npx', ...args].join(' ') };
-    },
-  },
-];
-
-// Built-in module: no project write, no npm. "Installing" it enables MADRE's own
-// MCP image server for the CLIs that cannot generate images natively.
-export const IMAGE_STUDIO = {
-  id: 'image-studio',
-  kind: 'builtin',
-  name: 'Image Studio',
-  vendor: 'MADRE · Gemini API',
-  package: null,
-  version: '0.1.0',
-  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 CLI'],
-  requires: ['a Gemini API key with credits (the key the Gemini CLI stores, or GEMINI_API_KEY)'],
-  models: ['gemini-2.5-flash-image', 'gemini-3.1-flash-image', 'gemini-3-pro-image'],
-};
-EXTENSIONS.push(IMAGE_STUDIO);
-
-// Git Pulse: read-only repository facts in the room via /git. Nothing to
-// install; it is on wherever the project is a git repository.
-export const GIT_PULSE = {
-  id: 'git-pulse',
-  kind: 'builtin',
-  name: 'Git Pulse',
-  vendor: 'MADRE',
-  package: null,
-  version: '0.1.0',
-  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, without spending an agent turn.',
-  creates: ['nothing: read-only git commands run inside the project'],
-  requires: ['the project is a git repository'],
-  models: [],
-  commands: ['/git status', '/git log [n]', '/git diff', '/git branches'],
-};
-EXTENSIONS.push(GIT_PULSE);
-
-export const ASHCODE = {
-  id: 'ashcode',
-  kind: 'builtin',
-  name: 'AshCode',
-  vendor: 'MADRE · ORDER 937',
-  package: null,
-  version: '0.1.0-beta',
-  summary: 'Opt-in Spanish/English prompt and reply abbreviation. Keeps the original visible; may change meaning. Shorter characters do not guarantee fewer provider tokens.',
-  creates: ['nothing in the project', 'an ashCode switch in ~/.pulse/config.json', 'original and abbreviated text in the room event log when applied'],
-  requires: [],
-  models: [],
-};
-EXTENSIONS.push(ASHCODE);
-
-// RIPLEY: the file viewer renders HTML, SVG and Markdown instead of showing
-// their source, inside a sealed frame. A switch in config.json, nothing else.
-export const RIPLEY = {
-  id: 'ripley',
-  kind: 'builtin',
-  name: 'RIPLEY',
-  vendor: 'MADRE · PREVIEW',
-  package: null,
-  version: '0.1.0',
-  summary: 'Renders HTML, SVG and Markdown from the project and from .pulse/out in the file viewer, inside a sealed frame: no scripts, no network, no storage. Nothing leaves the room.',
-  creates: ['nothing in the project', 'a ripley switch in ~/.pulse/config.json'],
-  requires: [],
-  models: [],
-};
-EXTENSIONS.push(RIPLEY);
-
-export const extensionById = (id) => EXTENSIONS.find((extension) => extension.id === id) ?? null;
-
-export async function listExtensions({ projectRoot, agents = [], config = {}, imageKey = async () => null }) {
-  return Promise.all(EXTENSIONS.map(async (extension) => {
-    if (extension.id === 'git-pulse') {
-      const isRepo = await gitToplevel(projectRoot);
-      return {
-        id: extension.id, kind: 'builtin', name: extension.name, vendor: extension.vendor, package: null, version: extension.version,
-        summary: extension.summary, creates: extension.creates, requires: extension.requires, models: [], commands: extension.commands,
-        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,
-      };
-    }
-    if (extension.id === 'ashcode') {
-      const enabled = Boolean(config.modules?.ashCode?.enabled);
-      return {
-        id: extension.id, kind: 'builtin', name: extension.name, vendor: extension.vendor, package: null, version: extension.version,
-        summary: extension.summary, creates: extension.creates, requires: [], models: [],
-        status: { installed: enabled, detail: enabled ? 'on · beta · ORDER 937 available' : 'off · beta' },
-        preflight: { ok: true, problems: [] },
-        install: { display: enabled ? 'disable AshCode' : 'enable AshCode (config.json)', platforms: [] },
-        warning: 'Beta: abbreviation may alter meaning or introduce errors. Review the original. Character reduction is not verified token savings.',
-      };
-    }
-    if (extension.id === 'ripley') {
-      const enabled = Boolean(config.modules?.ripley?.enabled);
-      return {
-        id: extension.id, kind: 'builtin', name: extension.name, vendor: extension.vendor, package: null, version: extension.version,
-        summary: extension.summary, creates: extension.creates, requires: [], models: [],
-        status: { installed: enabled, detail: enabled ? 'on · PREVIEW in the file viewer' : 'off · files show as source' },
-        preflight: { ok: true, problems: [] },
-        install: { display: enabled ? 'disable RIPLEY' : 'enable RIPLEY (config.json)', platforms: [] },
-        fixed: false,
-      };
-    }
-    if (extension.kind === 'builtin') {
-      const enabled = Boolean(config.modules?.imageStudio?.enabled);
-      const key = await imageKey();
-      return {
-        id: extension.id,
-        kind: 'builtin',
-        name: extension.name,
-        vendor: extension.vendor,
-        package: null,
-        version: extension.version,
-        summary: extension.summary,
-        creates: extension.creates,
-        requires: extension.requires,
-        models: extension.models,
-        model: config.modules?.imageStudio?.model ?? extension.models[0],
-        status: { installed: enabled, detail: enabled ? `on · ${config.modules?.imageStudio?.model ?? extension.models[0]}${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\'s AI Studio credits.'] },
-        install: { display: enabled ? 'disable Image Studio' : 'enable Image Studio (config.json)', platforms: ['gemini', 'claude', 'opencode'] },
-      };
-    }
-    const status = await extension.detect(projectRoot);
-    const plan = extension.installCommand({ agents });
-    const preflight = extension.preflight ? await extension.preflight(projectRoot) : { ok: true, problems: [] };
-    return {
-      id: extension.id,
-      name: extension.name,
-      vendor: extension.vendor,
-      package: extension.package,
-      version: extension.version,
-      summary: extension.summary,
-      creates: extension.creates,
-      status,
-      preflight,
-      install: { display: plan.display, platforms: plan.platforms },
-    };
-  }));
+import { spawn } from 'node:child_process';
+import { MODULES, moduleById, describeModules } from './modules/index.mjs';
+export { gitToplevel, findOnPath } from './modules/helpers.mjs';
+
+// Compatibility over the module registry (src/modules/): the same names the
+// server and the tests have always used, now answered by one file per module.
+export const EXTENSIONS = MODULES;
+export const AHP = moduleById('ahp');
+export const IMAGE_STUDIO = moduleById('image-studio');
+export const GIT_PULSE = moduleById('git-pulse');
+export const ASHCODE = moduleById('ashcode');
+export const RIPLEY = moduleById('ripley');
+export const OLLAMA = moduleById('ollama');
+export const extensionById = moduleById;
+
+// Lists every module as MODULES shows it. `ollama` is the server's probe state;
+// `services` may add what a server offers (imageKey, ollama wiring).
+export async function listExtensions({ projectRoot, agents = [], config = {}, imageKey = async () => null, ollama = null, services = {}, env = process.env } = {}) {
+  const ctx = {
+    projectRoot, config, agents, env, room: null,
+    readConfig: async () => config, updateConfig: async () => {}, record: async () => {},
+    services: { imageKey, ollama: ollama ? { state: () => ollama, wire: async () => ollama, pull: async () => ({ ok: false, error: 'not available here' }) } : null, ...services },
+  };
+  return describeModules(ctx);
 }
 
 // Runs one installer inside the project, streaming output lines. `runner`

package/src/memory.mjs

@@ -390,7 +390,8 @@ export class RoomMemory {
   // weighted, like entries) and, when few match, the most recent decisions and
   // preferences, all from before `beforeSequence` so they add to the window
   // rather than repeat it, within a character budget.
-  recallMemories(text, { beforeSequence = Number.MAX_SAFE_INTEGER, limit = 6, maxChars = 1200, queryVector = null, semanticFloor = 0.45 } = {}) {
+  // `fallback` fills a thin match with the latest decisions and preferences; @madre turns it off to stay honest.
+  recallMemories(text, { beforeSequence = Number.MAX_SAFE_INTEGER, limit = 6, maxChars = 1200, queryVector = null, semanticFloor = 0.45, fallback = true } = {}) {
     if (!this.#db) return [];
     const total = this.memoryCount();
     if (!total) return [];
@@ -406,7 +407,7 @@ export class RoomMemory {
       for (const { id } of rows) scores.set(id, (scores.get(id) ?? 0) + weight);
     }
     const ids = RoomMemory.fuse(scores, semantic).map(([id]) => id);
-    if (ids.length < 2) {
+    if (fallback && ids.length < 2) {
       const recent = this.#db.prepare("SELECT id FROM memories WHERE through_sequence < ? AND kind IN ('decision', 'preference') ORDER BY id DESC LIMIT ?").all(beforeSequence, limit);
       for (const { id } of recent) if (!ids.includes(id)) ids.push(id);
     }

package/src/modules/ahp.mjs

@@ -0,0 +1,64 @@
+// AHP+: the one module that writes into the project, through a confirmed npx
+// command. Verified project state, checkpoints and handoffs in .ahp/.
+
+import { join, resolve } from 'node:path';
+import { realpath } from 'node:fs/promises';
+import { defineModule } from './sdk.mjs';
+import { readJson, gitToplevel, findOnPath } from './helpers.mjs';
+
+// AHP+ platform names for the agents MADRE knows about. Gemini has no AHP+
+// adapter yet, so it is simply not requested.
+const AHP_PLATFORMS = { codex: 'codex', claude: 'claude', opencode: 'opencode' };
+const PACKAGE = '@jossuealcala/ahp-plus';
+const VERSION = '1.4.1';
+
+async function detect(projectRoot) {
+  const manifest = await readJson(join(projectRoot, '.ahp', 'manifest.json'));
+  if (!manifest) return { installed: false };
+  const pinned = await readJson(join(projectRoot, 'node_modules', '@jossuealcala', 'ahp-plus', 'package.json'));
+  return {
+    installed: true,
+    version: pinned?.version ?? null,
+    protocolVersion: manifest.protocol_version ?? null,
+    projectId: manifest.project_id ?? null,
+    detail: [pinned?.version ? `cli ${pinned.version}` : null, manifest.protocol_version ? `protocol ${manifest.protocol_version}` : null].filter(Boolean).join(' · '),
+  };
+}
+
+// Refuses before anything is written when the outcome would be wrong.
+async function preflight(projectRoot, { toplevel = gitToplevel, npx = findOnPath } = {}) {
+  const root = await realpath(projectRoot).catch(() => resolve(projectRoot));
+  const problems = [];
+  if (!(await npx('npx'))) problems.push('npx is not on PATH for the MADRE server; start MADRE from a terminal where `npx --version` works.');
+  const top = await toplevel(root);
+  if (!top) {
+    problems.push('The project is not a git repository. AHP+ pins itself to the git root: run `git init` in the project first.');
+  } else if (top !== root) {
+    problems.push(`The project's git root is ${top}, not the project itself. AHP+ would install there. Run \`git init\` inside the project, or remove the stray repository at ${top}.`);
+  }
+  return { ok: problems.length === 0, problems, gitRoot: top };
+}
+
+function installCommand({ agents = [] }) {
+  const platforms = agents.filter((agent) => agent.detected && AHP_PLATFORMS[agent.id]).map((agent) => AHP_PLATFORMS[agent.id]);
+  const args = ['--yes', `${PACKAGE}@${VERSION}`, 'setup', '.'];
+  if (platforms.length) args.push('--platforms', platforms.join(','));
+  return { command: 'npx', args, platforms, display: ['npx', ...args].join(' ') };
+}
+
+export default defineModule({
+  id: 'ahp',
+  kind: 'installer',
+  name: 'AHP+',
+  vendor: 'Agent Handoff Protocol Plus',
+  package: PACKAGE,
+  version: VERSION,
+  summary: 'Verified project state, checkpoints and handoffs between AI sessions, stored in .ahp/ next to your code.',
+  creates: ['.ahp/ with manifest, sessions, handoffs and evidence', 'a project-local pin of @jossuealcala/ahp-plus', 'IDE adapter files for the detected agents'],
+  detect, preflight, installCommand,
+  async status(ctx) {
+    const status = await detect(ctx.projectRoot);
+    const plan = installCommand({ agents: ctx.agents });
+    return { status, preflight: await preflight(ctx.projectRoot), install: { display: plan.display, platforms: plan.platforms } };
+  },
+});

package/src/modules/ashcode.mjs

@@ -0,0 +1,28 @@
+// AshCode: opt-in abbreviation of prompts and replies. Beta, so the switch asks
+// for confirmation and the room says so every time it turns on.
+
+import { defineModule } from './sdk.mjs';
+
+const WARNING = 'Beta: abbreviation may alter meaning or introduce errors. Review the original. Character reduction is not verified token savings.';
+
+export default defineModule({
+  id: 'ashcode',
+  configKey: 'ashCode',
+  name: 'AshCode',
+  vendor: 'MADRE · ORDER 937',
+  version: '0.1.0-beta',
+  summary: 'Opt-in Spanish/English prompt and reply abbreviation. Keeps the original visible; may change meaning. Shorter characters do not guarantee fewer provider tokens.',
+  creates: ['nothing in the project', 'an ashCode switch in ~/.pulse/config.json', 'original and abbreviated text in the room event log when applied'],
+  card: 'ashcode',
+  confirm: 'AshCode is beta and can change meaning. Send { "confirm": true } to enable it.',
+  toggledEvent: { beta: true },
+  toggledBody: () => ({ beta: true, warning: 'AshCode beta may alter meaning; review the original. Character reduction is not verified token savings.' }),
+  async status(ctx) {
+    return {
+      status: { installed: Boolean(ctx.settings.enabled), detail: ctx.settings.enabled ? 'on · beta · ORDER 937 available' : 'off · beta' },
+      install: { display: ctx.settings.enabled ? 'disable AshCode' : 'enable AshCode (config.json)', platforms: [] },
+      warning: WARNING,
+    };
+  },
+  async onToggle(ctx, enabled) { ctx.room.setAshCode(enabled); return null; },
+});

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';