@jossuealcala/madre 0.3.3 → 0.4.0

package/src/modules/image-studio.mjs

@@ -2,6 +2,7 @@
 // the CLIs that cannot draw natively. A switch and a model in config.json.
 
 import { defineModule } from './sdk.mjs';
+import { t } from '../i18n.mjs';
 
 const MODELS = ['gemini-2.5-flash-image', 'gemini-3.1-flash-image', 'gemini-3-pro-image'];
 
@@ -10,18 +11,22 @@ export default defineModule({
   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)'],
+  version: '1.0.0',
+  summary: 'Gives Gemini CLI, Claude Code and OpenCode an image tool, through a MADRE-owned MCP server on the Gemini image models and your own key and credits.',
+  creates: ['nothing in the project \u00b7 images land in the lease folder', 'an entry in ~/.pulse/config.json', 'an MCP server per turn, started and stopped by the room', 'attached only inside a creation lease with the image scope on'],
+  requires: ['a Gemini API key with credits (the one the Gemini CLI stores, or GEMINI_API_KEY)'],
   models: MODELS,
   settings: { enabled: false, model: MODELS[0] },
   card: 'image-studio',
+  controls: [{ key: 'model', label: 'MODEL', type: 'select', options: MODELS, note: 'The Gemini image model Image Studio draws with. It bills against your own key.' }],
+  // Changing the model while it is on has to reach the running room, not just the file.
+  async onSettings(ctx, settings) { if (settings.enabled) ctx.services.setImageModule({ enabled: true, model: settings.model }); },
   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' },
+      status: { installed: Boolean(ctx.settings.enabled), detail: ctx.settings.enabled ? `${t('on')} · ${model}${key ? '' : t(' · no Gemini key found')}` : key ? t('key found') : t('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'] },
     };

package/src/modules/index.mjs

@@ -1,21 +1,144 @@
-// The registry. Order is the order MODULES shows.
+// The registry. Order is the order MODULES shows. MADRE's own modules first; then the
+// human's, loaded from ~/.pulse/modules/*.mjs (every project) and <project>/.madre/modules/*.mjs
+// (this project). An external module is a file whose default export is a plain spec object
+// (defineModule is applied here), a module already built with defineModule, or a function
+// receiving { defineModule } and returning either. Agents cannot write those folders: .madre/
+// is a forbidden zone, and ~/.pulse lives outside every project.
+import { readdir, readFile, writeFile, mkdir, unlink, mkdtemp, rm, access } from 'node:fs/promises';
+import { translate } from '../i18n.mjs';
+import { join, basename, resolve, sep } from 'node:path';
+import { tmpdir } from 'node:os';
+import { pathToFileURL, fileURLToPath } from 'node:url';
 import ahp from './ahp.mjs';
 import imageStudio from './image-studio.mjs';
 import gitPulse from './git-pulse.mjs';
-import ashcode from './ashcode.mjs';
+import ash from './ash.mjs';
 import ripley from './ripley.mjs';
 import ollama from './ollama.mjs';
 import playwright from './playwright.mjs';
-import { matchRoute } from './sdk.mjs';
+import { defineModule, matchRoute } from './sdk.mjs';
 
-export const MODULES = [ahp, imageStudio, gitPulse, ashcode, ripley, ollama, playwright];
-// Every tool server the modules hand to one turn, flattened; a module that fails hands nothing.
-export async function toolsForTurn(ctx, turn) {
-  const lists = await Promise.all(MODULES.filter((module) => module.toolsForTurn).map((module) => module.toolsForTurn(ctx, turn)));
-  return lists.flat().filter((server) => server && server.name && server.command);
+export const MODULES = [ahp, imageStudio, gitPulse, ash, ripley, ollama, playwright];
+export const BUILTIN_IDS = new Set(MODULES.map((module) => module.id));
+export const loadFailures = [];   // { file, error } for MODULES to show
+export const moduleFolders = ({ stateRoot, projectRoot }) => ({ user: join(stateRoot, 'modules'), project: join(projectRoot, '.madre', 'modules') });
+// Where the SDK guide and the example live in this installation, for agents who build modules.
+export const sdkPaths = () => ({ guide: fileURLToPath(new URL('../../docs/SDK.md', import.meta.url)), example: fileURLToPath(new URL('../../docs/sdk/hello-module.mjs', import.meta.url)) });
+// A file an agent wrote that means "install me as a module": <id>.module.mjs.
+export const isModuleFile = (path) => /\.module\.mjs$/.test(String(path ?? ''));
+
+// The rules an outside module must keep so it cannot reach MADRE's core: its own id, and its
+// routes under /api/x/<id>/ only, never MADRE's own paths.
+function checkExternal(module, { replace = false } = {}) {
+  const taken = MODULES.find((known) => known.id === module.id);
+  // A module that ships with MADRE can never be shadowed. One of the human's own can be
+  // replaced, because that is what installing a newer copy of it is.
+  if (taken && (!replace || !taken.external)) throw new Error(`the id "${module.id}" is already taken`);
+  for (const route of module.routes ?? []) {
+    const path = typeof route.path === 'string' ? route.path : route.path?.source ?? '';
+    if (!path.startsWith(`/api/x/${module.id}/`) && !path.startsWith(`\\/api\\/x\\/${module.id}\\/`)) throw new Error(`route ${path} must live under /api/x/${module.id}/`);
+  }
+  return module;
+}
+
+// Loads one file as a module, throwing a readable error when it is not one.
+async function importModuleFile(file) {
+  const loaded = await import(`${pathToFileURL(file).href}?t=${Date.now()}`);
+  let spec = loaded.default ?? loaded.module ?? null;
+  if (typeof spec === 'function') spec = await spec({ defineModule });
+  if (!spec || typeof spec !== 'object') throw new Error('the default export must be a module spec object');
+  return typeof spec.describe === 'function' ? spec : defineModule(spec);
+}
+
+export async function loadExternalModules({ stateRoot, projectRoot }) {
+  for (let index = MODULES.length - 1; index >= 0; index -= 1) if (MODULES[index].external) MODULES.splice(index, 1);
+  loadFailures.length = 0;
+  const folders = moduleFolders({ stateRoot, projectRoot });
+  for (const [origin, dir] of Object.entries(folders)) {
+    let files = [];
+    try { files = (await readdir(dir)).filter((name) => /\.(mjs|js)$/.test(name) && !name.startsWith('.')).sort(); } catch { continue; }
+    for (const name of files) {
+      const file = join(dir, name);
+      try {
+        const module = checkExternal(await importModuleFile(file));
+        MODULES.push(Object.freeze({ ...module, external: true, origin, file }));
+      } catch (error) {
+        loadFailures.push({ file, origin, error: error.message });
+      }
+    }
+  }
+  return { loaded: MODULES.filter((module) => module.external), failures: [...loadFailures], folders };
+}
+
+// The one door every module comes through, whoever wrote it and wherever the text came from: it
+// is written to a scratch copy, imported there and checked against the house rules. A module runs
+// inside MADRE with the human's own permissions, so the check is the point. Checking installs
+// nothing and touches no registry — asking what a file is must never change what is loaded.
+export async function verifyModuleText({ text, name = null, replace = true }) {
+  const scratch = await mkdtemp(join(tmpdir(), 'madre-module-check-'));
+  try {
+    const probe = join(scratch, name && /\.m?js$/.test(name) ? basename(name) : 'candidate.mjs');
+    await writeFile(probe, text);
+    const module = checkExternal(await importModuleFile(probe), { replace });
+    return { id: module.id, name: module.name, vendor: module.vendor, version: module.version ?? null, summary: module.summary ?? '', updates: module.updates ?? null };
+  } finally { await rm(scratch, { recursive: true, force: true, maxRetries: 6, retryDelay: 60 }); }
+}
+
+export async function installModuleText({ text, name = null, scope = 'user', stateRoot, projectRoot, source = null, replace = true }) {
+  const module = await verifyModuleText({ text, name, replace });
+  const replaced = Boolean(MODULES.find((known) => known.id === module.id)?.external);
+  const folders = moduleFolders({ stateRoot, projectRoot });
+  const dir = folders[scope === 'project' ? 'project' : 'user'];
+  await mkdir(dir, { recursive: true });
+  const target = join(dir, `${module.id}.mjs`);
+  await writeFile(target, text);
+  // Where it came from, so the same place can be asked for a newer one later.
+  if (source) await writeFile(join(dir, `${module.id}.source.json`), JSON.stringify({ ...source, at: new Date().toISOString(), version: module.version ?? null }, null, 2)).catch(() => {});
+  await loadExternalModules({ stateRoot, projectRoot });
+  return { id: module.id, name: module.name, version: module.version ?? null, file: target, origin: scope === 'project' ? 'project' : 'user', replaced };
 }
+
+// The same thing from a file already on this computer. `source` must be inside the project or the
+// room folder; agents never reach the module folders themselves.
+export async function installModuleFile({ source, scope = 'user', stateRoot, projectRoot, roomDir = null }) {
+  const canonical = resolve(source);
+  const allowed = [resolve(projectRoot), ...(roomDir ? [resolve(roomDir)] : [])];
+  if (!allowed.some((root) => canonical === root || canonical.startsWith(root + sep))) throw new Error('A module can only be installed from a file inside the project or the room folder.');
+  const text = await readFile(canonical, 'utf8');
+  return installModuleText({ text, name: basename(canonical), scope, stateRoot, projectRoot, source: { kind: 'file', from: canonical } });
+}
+
+// Where a module was installed from, if MADRE was told. This is what "update this module" asks
+// again: the file the author keeps it in, or the address they publish it at.
+export async function moduleOrigin(module) {
+  if (!module?.external || !module.file) return null;
+  const declared = module.updates?.url ? { kind: 'url', from: module.updates.url } : null;
+  const remembered = await readFile(module.file.replace(/\.mjs$/, '.source.json'), 'utf8').then((raw) => JSON.parse(raw)).catch(() => null);
+  return declared ?? (remembered?.from ? { kind: remembered.kind ?? 'file', from: remembered.from, at: remembered.at ?? null } : null);
+}
+
+// Removing is for the human's modules only; MADRE's own stay.
+export async function removeExternalModule({ id, stateRoot, projectRoot }) {
+  const module = MODULES.find((known) => known.id === id);
+  if (!module) throw new Error(`No module "${id}".`);
+  if (!module.external) throw new Error(`${module.name} ships with MADRE and cannot be removed; switch it off instead.`);
+  await unlink(module.file).catch(() => {});
+  await loadExternalModules({ stateRoot, projectRoot });
+  return { id, name: module.name, file: module.file };
+}
+
 export const moduleById = (id) => MODULES.find((module) => module.id === id) ?? null;
-export function describeModules(ctx) { return Promise.all(MODULES.map((module) => module.describe(ctx))); }
+// What MODULES shows, with each card's update state attached from the cache when the room offers
+// the service. Never a network read: a screen that waits on a registry is a screen that hangs.
+export async function describeModules(ctx) {
+  const items = await Promise.all(MODULES.map((module) => module.describe(ctx)));
+  const look = ctx.services?.moduleUpdate;
+  // One place, at the boundary: what a module says about itself is written in English inside the
+  // module, and it is the card that speaks the room's language. Nothing in the module files
+  // changes, and neither does what a module hands to an agent.
+  if (!look) return translate(items);
+  return translate(await Promise.all(items.map(async (item) => ({ ...item, update: await look(item).catch(() => null) }))));
+}
 // One flat list of every route a module serves, with the module attached.
 export function findModuleRoute(method, pathname) {
   for (const module of MODULES) {
@@ -24,4 +147,13 @@ export function findModuleRoute(method, pathname) {
   }
   return null;
 }
+// Every slash command the modules declare, with its module attached.
+export function moduleCommands() {
+  return MODULES.flatMap((module) => (module.slash ?? []).map((command) => ({ ...command, module })));
+}
+// Every tool server the modules hand to one turn, flattened; a module that fails hands nothing.
+export async function toolsForTurn(ctx, turn) {
+  const lists = await Promise.all(MODULES.filter((module) => module.toolsForTurn).map((module) => module.toolsForTurn(ctx, turn)));
+  return lists.flat().filter((server) => server && server.name && server.command);
+}
 export { defineModule } from './sdk.mjs';

package/src/modules/ollama.mjs

@@ -2,33 +2,81 @@
 // Ollama runs. The server offers the wiring through ctx.services.ollama.
 
 import { defineModule } from './sdk.mjs';
+import { t } from '../i18n.mjs';
+import { findOnPath } from './helpers.mjs';
 import { RECOMMENDED } from '../ollama.mjs';
 
+// Ollama is not an npm package, so each system has its own way in. Where MADRE can run it, the
+// command is shown on the button before it runs; where it cannot, it hands over the download.
+export function ollamaInstallPlan({ platform = process.platform, brew = null } = {}) {
+  if (platform === 'darwin') {
+    return brew
+      ? { command: brew, args: ['install', 'ollama'], display: 'brew install ollama', note: 'Installs Ollama with Homebrew, the package manager already on this computer.' }
+      : { command: null, download: 'https://ollama.com/download', display: null, note: 'Homebrew is not on this computer. Download Ollama from ollama.com, open it once, and press RECHECK.' };
+  }
+  if (platform === 'linux') {
+    return { command: 'sh', args: ['-c', 'curl -fsSL https://ollama.com/install.sh | sh'], display: 'curl -fsSL https://ollama.com/install.sh | sh', note: "Ollama's own install script, downloaded from ollama.com and run on this computer." };
+  }
+  return { command: null, download: 'https://ollama.com/download', display: null, note: 'Download the Ollama installer from ollama.com, run it, and press RECHECK.' };
+}
+
+// A newer Ollama. Where MADRE can do it, the command is shown before it runs; where it cannot,
+// it hands over the download rather than pretending.
+export function ollamaUpdatePlan({ platform = process.platform, brew = null } = {}) {
+  if (platform === 'darwin') {
+    return brew
+      ? { command: brew, args: ['upgrade', 'ollama'], display: 'brew upgrade ollama', note: 'Upgrades Ollama with Homebrew. Your models stay where they are.' }
+      : { command: null, download: 'https://ollama.com/download', display: null, note: 'Ollama was not installed with Homebrew. Download the newer one from ollama.com, open it once, and press RECHECK. Your models stay where they are.' };
+  }
+  if (platform === 'linux') {
+    return { command: 'sh', args: ['-c', 'curl -fsSL https://ollama.com/install.sh | sh'], display: 'curl -fsSL https://ollama.com/install.sh | sh', note: "Ollama's own install script upgrades in place. Your models stay where they are." };
+  }
+  return { command: null, download: 'https://ollama.com/download', display: null, note: 'Download the newer Ollama from ollama.com and run it. Your models stay where they are.' };
+}
+
+// Waking it: the same command on every system, and the app on macOS does it too.
+export const ollamaStartPlan = () => ({ command: 'ollama', args: ['serve'], display: 'ollama serve' });
+
+// What the room needs to know about the local brain: its own state, whether it is even on this
+// computer, and the one step that moves it forward. The card and the routes share this.
+export async function ollamaView(probe, settings) {
+  const binary = await findOnPath('ollama');
+  return { ...probe, settings, binary, install: ollamaInstallPlan({ brew: await findOnPath('brew') }), start: ollamaStartPlan() };
+}
+
 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)'],
+  tracks: { name: 'ollama', github: 'ollama/ollama' },
+  summary: 'Recall by meaning and memory distillation on this machine, through Ollama: no provider tokens, nothing leaves.',
+  creates: ['nothing in the project', 'a block in ~/.pulse/config.json', 'models in Ollama\'s own store when you press PULL'],
+  requires: ['Ollama running (the app, or ollama serve)', 'an embedding model and a chat model \u00b7 MADRE can pull the recommended ones'],
   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 view = await ollamaView(probe, ctx.settings);
+    const binary = view.binary;
     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';
+    const roles = [settings.embeddings && probe.embedModel ? `${t('embeddings')} · ${probe.embedModel}` : null, settings.archivist && probe.chatModel ? `${t('archivist')} · ${probe.chatModel}` : null, settings.agent !== false && probe.chatModel ? t('@madre in the room') : null].filter(Boolean);
+    const detail = !probe.running ? (binary ? t('installed, not running · START it here') : t('not installed · INSTALL it here'))
+      : !settings.enabled ? t('off · {n} models available', { n: probe.models.length })
+        : roles.length ? `${t('on')} · ${roles.join(' · ')}` : t('on · no usable model yet · PULL one');
     return {
+      runs: [{ name: 'ollama', version: probe.version ?? null }],
       models: probe.models.map((model) => model.name),
       status: { installed: settings.enabled && probe.running && roles.length > 0, detail },
-      ollama: { ...probe, settings },
+      ollama: view,
       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 updatePlan(ctx) {
+    const { findOnPath } = await import('./helpers.mjs');
+    return ollamaUpdatePlan({ brew: await findOnPath('brew') });
+  },
   async toggle(ctx) {
     const enabled = !(ctx.settings.enabled ?? true);
     await ctx.updateConfig({ modules: { ...(ctx.config.modules ?? {}), ollama: { ...(ctx.config.modules?.ollama ?? {}), enabled } } });
@@ -37,14 +85,22 @@ export default defineModule({
     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: 'GET', path: '/api/ollama', handler: async (ctx) => ({ status: 200, body: { ollama: await ollamaView(await ctx.services.ollama.wire({ probe: false }), ctx.settings), recommended: RECOMMENDED } }) },
+    { method: 'POST', path: '/api/ollama/probe', handler: async (ctx) => ({ status: 200, body: { ollama: await ollamaView(await ctx.services.ollama.wire(), ctx.settings), 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/install', handler: async (ctx) => {
+      const started = await ctx.services.ollama.install();
+      return started.ok ? { status: 202, body: { installing: true, command: started.command } } : { status: started.download ? 412 : 409, body: { error: started.error, download: started.download ?? null } };
+    } },
+    { method: 'POST', path: '/api/ollama/start', handler: async (ctx) => {
+      const started = await ctx.services.ollama.start();
+      return started.ok ? { status: 200, body: { ollama: ctx.services.ollama.state() } } : { status: 412, body: { error: started.error } };
+    } },
     { 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.' } };

package/src/modules/playwright.mjs

@@ -3,25 +3,24 @@
 // scratch folder. Runs @playwright/mcp per turn, isolated, with allowed origins limited to the
 // room's own address: nothing else on the network is reachable through it.
 
-import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
 import { join } from 'node:path';
+import { t } from '../i18n.mjs';
 import { defineModule } from './sdk.mjs';
+import { packageVersion } from './helpers.mjs';
 
-const execFileAsync = promisify(execFile);
+export const PLAYWRIGHT_PACKAGE = '@playwright/mcp';
+export const PLAYWRIGHT_BROWSERS = ['chromium', 'firefox', 'webkit'];
 export const PLAYWRIGHT_SERVER_NAME = 'pulse-playwright';
 // The tools @playwright/mcp exposes that a room turn may use. Screenshots and files land in scratch.
 export const PLAYWRIGHT_TOOLS = ['browser_navigate', 'browser_navigate_back', 'browser_snapshot', 'browser_click', 'browser_type', 'browser_fill_form', 'browser_hover', 'browser_press_key', 'browser_select_option', 'browser_wait_for', 'browser_console_messages', 'browser_network_requests', 'browser_take_screenshot', 'browser_resize', 'browser_tabs', 'browser_close'];
 
 let probe = { at: 0, version: null };
-// Is @playwright/mcp installed where npx can find it without downloading? Cached a minute.
-export async function playwrightVersion({ env = process.env, now = Date.now() } = {}) {
-  if (now - probe.at < 60000) return probe.version;
-  let version = null;
-  try {
-    const { stdout } = await execFileAsync('npx', ['--no', '@playwright/mcp', '--version'], { env, timeout: 15000 });
-    version = stdout.trim().split('\n').pop().trim() || 'installed';
-  } catch { version = null; }
+// Is @playwright/mcp installed where npx can find it without downloading? Read from the package
+// itself, never asked of it: `npx --no <package> --version` answers with npm's own version and
+// exits cleanly when the package is not there, so it said 11.16.0 for a server never installed.
+export async function playwrightVersion({ env = process.env, projectRoot = process.cwd(), now = Date.now(), fresh = false } = {}) {
+  if (!fresh && now - probe.at < 60000) return probe.version;
+  const version = await packageVersion(PLAYWRIGHT_PACKAGE, { env, projectRoot });
   probe = { at: now, version };
   return version;
 }
@@ -41,22 +40,40 @@ export default defineModule({
   id: 'playwright',
   name: 'PLAYWRIGHT',
   vendor: 'MADRE · Playwright MCP',
-  summary: 'Hands every agent a headless browser that reaches only this MADRE: open the RIPLEY preview of a page, click through it, read the console, take screenshots into the turn\'s scratch folder. Runs @playwright/mcp isolated per turn; no other origin is reachable.',
-  creates: ['nothing in the project: screenshots land in .pulse/out/<turn>/', 'a playwright switch in ~/.pulse/config.json', 'a browser process per turn, started and stopped by the CLI'],
-  requires: ['@playwright/mcp installed (npm install -g @playwright/mcp) and a browser (npx playwright install chromium)', 'RIPLEY on, to have pages to open'],
+  tracks: { name: PLAYWRIGHT_PACKAGE, npm: PLAYWRIGHT_PACKAGE },
+  summary: 'Hands every agent a headless browser that reaches only this room: it opens the RIPLEY preview of a page, clicks through it, reads the console and takes screenshots.',
+  creates: ['nothing in the project \u00b7 screenshots land in .pulse/out/<turn>/', 'a switch in ~/.pulse/config.json', 'a browser per turn, started and stopped by the CLI', 'no origin but this room is reachable through it'],
+  requires: ['@playwright/mcp and a chromium browser on this machine', 'RIPLEY on, to have pages to open'],
   settings: { enabled: false, browser: 'chromium', headless: true },
   card: 'switch',
+  controls: [
+    { key: 'browser', label: 'BROWSER', type: 'select', options: PLAYWRIGHT_BROWSERS, note: 'Which browser engine the agents drive.' },
+    { key: 'headless', label: 'SHOW THE WINDOW', type: 'switch', invert: true, note: 'Off, the browser runs headless. On, it opens on this screen so you can watch.' },
+  ],
   async status(ctx) {
-    const version = await playwrightVersion({ env: ctx.env });
+    const version = await playwrightVersion({ env: ctx.env, projectRoot: ctx.projectRoot });
     return {
-      version: version ?? null,
-      status: { installed: Boolean(ctx.settings.enabled), detail: ctx.settings.enabled ? (version ? `on · @playwright/mcp ${version} · ${ctx.settings.browser}` : 'on · @playwright/mcp not found') : version ? `off · @playwright/mcp ${version} found` : 'off · @playwright/mcp not installed' },
+      runs: [{ name: PLAYWRIGHT_PACKAGE, version }],
+      settings: { browser: ctx.settings.browser ?? 'chromium', headless: ctx.settings.headless !== false },
+      status: { installed: Boolean(ctx.settings.enabled), detail: ctx.settings.enabled ? (version ? `${t('on')} · ${ctx.settings.browser}` : t('on · the browser server is not installed')) : version ? t('off') : t('off · the browser server is not installed') },
       preflight: version ? { ok: true, problems: [] } : { ok: false, problems: ['Install the browser server first: npm install -g @playwright/mcp && npx playwright install chromium'] },
       install: { display: ctx.settings.enabled ? 'disable PLAYWRIGHT' : 'enable PLAYWRIGHT (config.json)', platforms: ['codex', 'claude', 'gemini', 'opencode'] },
     };
   },
+  // Getting the browser server onto this computer, or a newer one. Installed globally, which is
+  // where `npx --no` looks for it at turn time without downloading anything.
+  async updatePlan(ctx, { latest = null } = {}) {
+    const target = latest ? `${PLAYWRIGHT_PACKAGE}@${latest}` : PLAYWRIGHT_PACKAGE;
+    return {
+      command: 'npm',
+      args: ['install', '-g', target],
+      display: `npm install -g ${target}`,
+      note: 'Installs the browser server for every project on this computer. A browser itself may still be missing; the card says so if it is.',
+      after: async () => { await playwrightVersion({ env: ctx.env, projectRoot: ctx.projectRoot, fresh: true }); },
+    };
+  },
   async toolsForTurn(ctx, turn) {
-    if (!(await playwrightVersion({ env: ctx.env }))) return [];
+    if (!(await playwrightVersion({ env: ctx.env, projectRoot: ctx.projectRoot }))) return [];
     if (turn.mode === 0) return [];   // a ghost turn leaves no screenshots and opens no browser
     const outputDir = turn.scratchDir ?? join(turn.roomDir ?? ctx.stateRoot, 'playwright');
     return [playwrightServerFor({ port: turn.port, outputDir, browser: ctx.settings.browser ?? 'chromium', headless: ctx.settings.headless !== false })];
@@ -68,6 +85,6 @@ export default defineModule({
     match: /@playwright\/mcp|playwright.*not (found|installed)|browser server/i,
     diagnosis: 'The PLAYWRIGHT module runs @playwright/mcp per turn. It is on, or you tried to open it, but npx cannot find the package without downloading, or no browser is installed.',
     remedy: 'Install it once, globally, then RECHECK in MODULES.',
-    fixes: { darwin: ['npm install -g @playwright/mcp', 'npx playwright install chromium'], linux: ['npm install -g @playwright/mcp', 'npx playwright install --with-deps chromium'], win32: ['npm install -g @playwright/mcp', 'npx playwright install chromium'] },
+    fixes: { darwin: ['npm install -g @playwright/mcp', 'npx playwright install chromium'], linux: ['npm install -g @playwright/mcp', 'npx playwright install --with-deps chromium'] },
   }],
 });

package/src/modules/ripley.mjs

@@ -2,17 +2,19 @@
 // A switch in config.json, read live by the preview route.
 
 import { defineModule } from './sdk.mjs';
+import { t } from '../i18n.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'],
+  version: '1.0.0',
+  summary: 'Renders HTML, SVG and Markdown from the project and from .pulse/out in the file viewer, inside a sealed frame.',
+  creates: ['nothing in the project', 'a switch in ~/.pulse/config.json', 'scripts run in the frame \u00b7 nothing leaves, nothing is stored, nothing reaches MADRE'],
   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' },
+      status: { installed: Boolean(ctx.settings.enabled), detail: ctx.settings.enabled ? t('on · PREVIEW in the file viewer') : t('off · files show as source') },
       install: { display: ctx.settings.enabled ? 'disable RIPLEY' : 'enable RIPLEY (config.json)', platforms: [] },
       fixed: false,
     };

package/src/modules/sdk.mjs

@@ -14,8 +14,43 @@
 // Kinds: 'builtin' switches MADRE's own behaviour (config.json only);
 // 'installer' writes into the project through a confirmed command.
 
+import { readFile, stat } from 'node:fs/promises';
+
 const camel = (id) => id.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
 
+let release = null;
+// MADRE's own release, read once from the package that is running.
+export async function madreRelease() {
+  if (release) return release;
+  const raw = await readFile(new URL('../../package.json', import.meta.url), 'utf8').catch(() => '');
+  try { release = JSON.parse(raw).version ?? '0.0.0'; } catch { release = '0.0.0'; }
+  return release;
+}
+
+// What version a card shows. A module that is a wrapper around something else — a browser server,
+// a local model runner, a CLI — has no version worth showing of its own: what matters is the
+// version of the thing it drives, found on this computer, and `null` means it is not there. Every
+// other module declares its own, starting at 1.0.0. A module someone else wrote and left
+// unversioned falls back to the day its file was written, which is the only truth on disk.
+export async function versionOf(module, { declared = null, tracked } = {}) {
+  if (tracked !== undefined) return { version: tracked, source: 'tracked' };
+  if (declared) return { version: declared, source: 'declared' };
+  if (module?.external) {
+    const when = await stat(module.file).then((info) => info.mtime).catch(() => null);
+    return when ? { version: when.toISOString().slice(0, 10), source: 'file' } : { version: null, source: 'none' };
+  }
+  return { version: '1.0.0', source: 'declared' };
+}
+
+// What a module drives that is not MADRE and not the module itself: an npm package, a server, a
+// binary on this computer. `version` is what was found here and now, `null` when it is not
+// installed at all; `target` is what the module would install if asked. The card shows each one
+// as its own tag, so a version on screen always belongs to something nameable.
+export function dependencies(runs) {
+  const list = Array.isArray(runs) ? runs : runs ? [runs] : [];
+  return list.filter((dep) => dep && dep.name).map((dep) => ({ name: String(dep.name), version: dep.version ?? null, target: dep.target ?? null }));
+}
+
 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.`);
@@ -23,9 +58,25 @@ export function defineModule(spec) {
   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,
+    id: spec.id, kind, name: spec.name, vendor: spec.vendor ?? 'MADRE', package: spec.package ?? null, version: spec.version ?? null,
+    // What this module's version follows, when it is not its own: { name, npm } or { name, github }.
+    // MADRE reads the version from there and looks for a newer one on its own, once a day.
+    tracks: spec.tracks ? { name: spec.tracks.name ?? spec.tracks.npm ?? spec.tracks.github ?? null, npm: spec.tracks.npm ?? null, github: spec.tracks.github ?? null } : null,
+    // Where a newer version of this module itself is published. A module you wrote says where it
+    // lives and MADRE can go and get it: the file is fetched, checked the same way an upload is,
+    // and only replaces the one installed if it passes and says it is newer.
+    updates: spec.updates?.url && /^https:\/\//.test(String(spec.updates.url)) ? { url: String(spec.updates.url) } : null,
+    summary: spec.summary ?? '', creates: spec.creates ?? [], requires: spec.requires ?? [], models: spec.models ?? [], commands: spec.commands ?? (spec.slash?.length ? spec.slash.map((command) => command.usage ?? `/${command.name}`) : undefined),
     card: spec.card ?? (kind === 'builtin' ? 'switch' : 'installer'),
+    // The settings floor of the card, declared instead of drawn: MADRE renders these and saves
+    // them into the module's own block of ~/.pulse/config.json.
+    controls: (spec.controls ?? []).map((control) => {
+      if (!control?.key) throw new Error(`Module ${spec.id}: a control needs a key.`);
+      const type = control.type ?? 'switch';
+      if (!['select', 'switch', 'text'].includes(type)) throw new Error(`Module ${spec.id}: control ${control.key} has no such type "${type}".`);
+      if (type === 'select' && !control.options?.length) throw new Error(`Module ${spec.id}: control ${control.key} is a select with no options.`);
+      return { key: control.key, label: control.label ?? control.key.toUpperCase(), type, options: control.options ?? [], note: control.note ?? '', invert: Boolean(control.invert) };
+    }),
   };
   const settingsFrom = (config) => ({ ...defaults, ...(config?.modules?.[configKey] ?? {}) });
   const module = {
@@ -36,12 +87,23 @@ export function defineModule(spec) {
     routes: (spec.routes ?? []).map((route) => ({ ...route, method: route.method.toUpperCase() })),
     onEvent: spec.onEvent ?? null,
     conditions: spec.conditions ?? [],
+    // Slash commands the human types in the composer; they run on the server with the module's
+    // ctx and settings and land in the room as a fact card everyone reads. Only while the module is on.
+    slash: (spec.slash ?? []).map((command) => {
+      if (!command?.name || !/^[a-z][a-z0-9-]*$/.test(command.name)) throw new Error(`Module ${spec.id}: a slash command needs a kebab-case name.`);
+      if (typeof command.execute !== 'function') throw new Error(`Module ${spec.id}: /${command.name} needs an execute(ctx, args) function.`);
+      return { name: command.name, usage: command.usage ?? `/${command.name}`, summary: command.summary ?? '', title: command.title ?? spec.name, available: command.available ?? null, execute: command.execute };
+    }),
     // Tools for a turn, only while the module is on. Failures never break a turn.
     toolsForTurn: spec.toolsForTurn ? async (ctx, turn) => {
       const settings = settingsFrom(ctx.config);
       if (kind === 'builtin' && !settings.enabled) return [];
       try { return (await spec.toolsForTurn({ ...ctx, settings }, turn)) ?? []; } catch (error) { console.error(`MADRE module ${spec.id}: toolsForTurn failed: ${error.message}`); return []; }
     } : null,
+    // How the outside thing this module drives gets a newer version onto this computer. MADRE
+    // shows the command before it runs and never runs one the human has not read. A module that
+    // cannot update what it drives returns the note that says where to get it instead.
+    updatePlan: spec.updatePlan ? async (ctx, what) => spec.updatePlan({ ...ctx, settings: settingsFrom(ctx.config) }, what) : null,
     // Legacy installer hooks, kept on the object so the confirm-and-run path can use them.
     detect: spec.detect ?? null,
     preflight: spec.preflight ?? null,
@@ -52,15 +114,44 @@ export function defineModule(spec) {
       const settings = settingsFrom(ctx.config);
       const own = spec.status ? await spec.status({ ...ctx, settings }) : {};
       const installed = own.installed ?? (kind === 'builtin' ? Boolean(settings.enabled) : false);
+      const runs = dependencies(own.runs);
+      const tracked = base.tracks ? (runs.find((dep) => dep.name === base.tracks.name)?.version ?? null) : undefined;
+      const stamp = await versionOf(this, { declared: spec.version ?? null, tracked });
       return {
         ...base,
+        ...(this.external ? { external: true, origin: this.origin, file: this.file } : {}),
         ...own,
+        version: stamp.version,
+        versionSource: stamp.source,
+        canUpdate: Boolean(spec.updatePlan),
+        controls: base.controls.map((control) => ({ ...control, value: settings[control.key] ?? null })),
+        ships: this.external ? null : await madreRelease(),
+        runs,
         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: [] }),
       };
     },
 
+    // One setting from the card's own floor. Only a key the module declared, only a value its
+    // type allows, and the module hears about it if it asked to.
+    setControl: base.controls.length ? async (ctx, { key, value } = {}) => {
+      const control = base.controls.find((known) => known.key === key);
+      if (!control) return { status: 400, body: { error: `${base.name} has no setting "${key}".` } };
+      let next = value;
+      if (control.type === 'switch') {
+        if (typeof value !== 'boolean') return { status: 400, body: { error: `${control.label} is on or off.` } };
+      } else if (control.type === 'select') {
+        if (!control.options.includes(value)) return { status: 400, body: { error: `${control.label} must be one of ${control.options.join(', ')}.` } };
+      } else {
+        next = String(value ?? '').slice(0, 500);
+      }
+      const settings = { ...settingsFrom(ctx.config), [key]: next };
+      await ctx.updateConfig({ modules: { ...(ctx.config.modules ?? {}), [configKey]: { ...(ctx.config.modules?.[configKey] ?? {}), [key]: next } } });
+      if (spec.onSettings) await spec.onSettings({ ...ctx, settings }, settings);
+      return { status: 200, body: { settings: Object.fromEntries(base.controls.map((known) => [known.key, settings[known.key] ?? null])) } };
+    } : null,
+
     // 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 = {}) => {