@jossuealcala/madre 0.2.0

package/src/extensions.mjs

@@ -0,0 +1,263 @@
+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 },
+    };
+  }));
+}
+
+// Runs one installer inside the project, streaming output lines. `runner`
+// lets tests substitute the real installer with a local script.
+export function runInstaller({ command, args, projectRoot, onLine, timeoutMs = 600000, heartbeatMs = 8000, env = process.env }) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, { cwd: projectRoot, env: { ...env, NO_COLOR: '1', CI: '1' }, stdio: ['ignore', 'pipe', 'pipe'] });
+    const started = Date.now();
+    let lastOutput = started;
+    // Installers go quiet for long stretches (npm install, git status); say so.
+    const heartbeat = setInterval(() => {
+      if (Date.now() - lastOutput >= heartbeatMs) {
+        onLine?.(`… still running · ${Math.round((Date.now() - started) / 1000)}s · installer is quiet (npm install or git status can take a while)`, 'heartbeat');
+        lastOutput = Date.now();
+      }
+    }, Math.min(heartbeatMs, 2000));
+    heartbeat.unref?.();
+    let buffer = '';
+    const feed = (chunk, stream) => {
+      buffer += chunk;
+      let index;
+      while ((index = buffer.indexOf('\n')) >= 0) {
+        const line = buffer.slice(0, index).replace(/\r$/, '');
+        buffer = buffer.slice(index + 1);
+        if (line.trim()) { lastOutput = Date.now(); onLine?.(line, stream); }
+      }
+    };
+    child.stdout.on('data', (chunk) => feed(String(chunk), 'stdout'));
+    child.stderr.on('data', (chunk) => feed(String(chunk), 'stderr'));
+    const timer = setTimeout(() => { child.kill('SIGKILL'); }, timeoutMs);
+    child.on('error', (error) => { clearTimeout(timer); clearInterval(heartbeat); resolve({ code: 1, error: error.code === 'ENOENT' ? `${error.message} (is the project folder present and ${command} on PATH?)` : error.message }); });
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      clearInterval(heartbeat);
+      if (buffer.trim()) onLine?.(buffer.trim(), 'stdout');
+      resolve({ code: code ?? 1 });
+    });
+  });
+}

package/src/files.mjs

@@ -0,0 +1,177 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readdir, readFile, realpath, stat, writeFile } from 'node:fs/promises';
+import { extname, join, resolve, sep } from 'node:path';
+
+// Read-only file access for the room UI, and human attachments.
+//
+// Two roots are servable: the project (read-only, so agents' references to
+// files and images render inline) and the room's own attachments folder under
+// PULSE_HOME (where the human's uploads live, never inside the project).
+
+export const MAX_FILE_BYTES = 20 * 1024 * 1024;
+export const MAX_ATTACHMENT_BYTES = 15 * 1024 * 1024;
+
+const TYPES = {
+  '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp', '.svg': 'image/svg+xml', '.avif': 'image/avif',
+  '.pdf': 'application/pdf',
+  '.md': 'text/markdown', '.txt': 'text/plain', '.json': 'application/json', '.jsonl': 'application/x-ndjson', '.yaml': 'text/yaml', '.yml': 'text/yaml', '.toml': 'text/plain',
+  '.js': 'text/javascript', '.mjs': 'text/javascript', '.cjs': 'text/javascript', '.ts': 'text/plain', '.tsx': 'text/plain', '.jsx': 'text/plain',
+  '.py': 'text/plain', '.rb': 'text/plain', '.go': 'text/plain', '.rs': 'text/plain', '.java': 'text/plain', '.kt': 'text/plain', '.swift': 'text/plain', '.c': 'text/plain', '.h': 'text/plain', '.cpp': 'text/plain',
+  '.sh': 'text/plain', '.zsh': 'text/plain', '.css': 'text/css', '.html': 'text/plain', '.xml': 'text/plain', '.csv': 'text/csv', '.sql': 'text/plain', '.env': 'text/plain',
+  '.mp4': 'video/mp4', '.webm': 'video/webm', '.mp3': 'audio/mpeg', '.wav': 'audio/wav',
+};
+export const contentTypeFor = (name) => TYPES[extname(name).toLowerCase()] ?? 'application/octet-stream';
+export const isImage = (name) => contentTypeFor(name).startsWith('image/');
+export const isText = (name) => /^(text\/|application\/(json|x-ndjson))/.test(contentTypeFor(name));
+
+// Resolves `relative` inside `root`, refusing anything that escapes it (../,
+// absolute paths, symlinks pointing outside). Returns null when refused.
+export async function resolveInside(root, relative) {
+  if (typeof relative !== 'string' || !relative || relative.includes('\0')) return null;
+  const canonicalRoot = await realpath(root).catch(() => null);
+  if (!canonicalRoot) return null;
+  const candidate = resolve(canonicalRoot, relative);
+  if (candidate !== canonicalRoot && !candidate.startsWith(canonicalRoot + sep)) return null;
+  const canonical = await realpath(candidate).catch(() => null);
+  if (!canonical || (canonical !== canonicalRoot && !canonical.startsWith(canonicalRoot + sep))) return null;
+  return canonical;
+}
+
+// One level of the project tree, for the room's file panel. Directories
+// first, then files, both alphabetical; .git is never listed and node_modules
+// is shown but not walked. Read-only and fenced to the project root.
+const SKIP = new Set(['.git', '.DS_Store']);
+// Folders the search walk skips (the tree still opens them one level at a time).
+const SHALLOW = new Set(['node_modules', '.venv', 'venv', 'dist', 'build', '.next', '.git']);
+export async function listDirectory(root, relative = '.') {
+  const path = await resolveInside(root, relative || '.');
+  if (!path) return { status: 404, error: 'Not found.' };
+  let entries;
+  try { entries = await readdir(path, { withFileTypes: true }); } catch { return { status: 404, error: 'Not a directory.' }; }
+  const items = [];
+  for (const entry of entries) {
+    if (SKIP.has(entry.name)) continue;
+    const isDir = entry.isDirectory() || (entry.isSymbolicLink() && (await stat(join(path, entry.name)).catch(() => null))?.isDirectory());
+    const item = { name: entry.name, kind: isDir ? 'dir' : 'file' };
+    if (isDir && SHALLOW.has(entry.name)) item.shallow = true;
+    if (!isDir) {
+      const info = await stat(join(path, entry.name)).catch(() => null);
+      if (info) item.size = info.size;
+      item.contentType = contentTypeFor(entry.name);
+    }
+    items.push(item);
+  }
+  items.sort((a, b) => (a.kind === b.kind ? a.name.localeCompare(b.name, undefined, { sensitivity: 'base' }) : a.kind === 'dir' ? -1 : 1));
+  return { status: 200, entries: items.slice(0, 500), truncated: items.length > 500 };
+}
+
+// Fuzzy-ish file search for the "!" menu in the composer: every path under
+// the project (same fences as the tree, shallow folders skipped) scored by
+// substring and initials match. The walk is cached for a short while.
+const walkCache = new Map(); // root -> { at, files }
+export async function walkProject(root, { maxFiles = 20000, ttlMs = 15000 } = {}) {
+  const cached = walkCache.get(root);
+  if (cached && Date.now() - cached.at < ttlMs) return cached.files;
+  const files = [];
+  async function walk(dir, prefix, depth) {
+    if (files.length >= maxFiles || depth > 14) return;
+    let entries = [];
+    try { entries = await readdir(dir, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      if (SKIP.has(entry.name)) continue;
+      const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) { if (!SHALLOW.has(entry.name)) await walk(join(dir, entry.name), rel, depth + 1); continue; }
+      if (entry.isFile()) files.push(rel);
+      if (files.length >= maxFiles) return;
+    }
+  }
+  await walk(root, '', 0);
+  walkCache.set(root, { at: Date.now(), files });
+  return files;
+}
+
+export function scoreFile(path, query) {
+  const q = query.toLowerCase();
+  if (!q) return 1;
+  const lower = path.toLowerCase();
+  const name = lower.split('/').pop();
+  if (name === q) return 100;
+  if (name.startsWith(q)) return 80 - Math.min(name.length - q.length, 30);
+  if (name.includes(q)) return 60 - Math.min(name.indexOf(q), 30);
+  if (lower.includes(q)) return 40 - Math.min(lower.length / 10, 20);
+  // subsequence match ("rmjs" -> room.mjs)
+  let index = 0;
+  for (const char of q) { index = lower.indexOf(char, index); if (index < 0) return 0; index += 1; }
+  return 10 - Math.min(lower.length / 20, 9);
+}
+
+export async function searchFiles(root, query, { limit = 20 } = {}) {
+  const files = await walkProject(root);
+  return files
+    .map((path) => ({ path, score: scoreFile(path, String(query ?? '').trim()) }))
+    .filter((item) => item.score > 0)
+    .sort((a, b) => b.score - a.score || a.path.length - b.path.length || a.path.localeCompare(b.path))
+    .slice(0, limit)
+    .map((item) => ({ path: item.path, name: item.path.split('/').pop(), contentType: contentTypeFor(item.path) }));
+}
+
+// "!src/room.mjs:12-20" in a human message points an agent at a project file
+// (optionally a line range). Only files that exist inside the project count.
+export const REFERENCE = /(^|[\s(,;:])!((?:[\w.-]+\/)*[\w.-]+\.[A-Za-z0-9]{1,8})(?::(\d+)(?:-(\d+))?)?(?![\w/])/g;
+export async function resolveReferences(root, text, { maxLines = 120 } = {}) {
+  const found = [];
+  const seen = new Set();
+  for (const match of String(text ?? '').matchAll(REFERENCE)) {
+    const rel = match[2];
+    const key = `${rel}:${match[3] ?? ''}-${match[4] ?? ''}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const path = await resolveInside(root, rel);
+    if (!path) continue;
+    const info = await stat(path).catch(() => null);
+    if (!info || !info.isFile()) continue;
+    const reference = { path: rel, size: info.size, contentType: contentTypeFor(rel) };
+    if (match[3]) {
+      const from = Number(match[3]);
+      const to = match[4] ? Math.max(from, Number(match[4])) : from;
+      reference.lines = { from, to };
+      if (isText(rel) && info.size <= 2 * 1024 * 1024) {
+        const all = (await readFile(path, 'utf8')).split('\n');
+        reference.excerpt = all.slice(from - 1, Math.min(to, from - 1 + maxLines)).map((line, index) => `${String(from + index).padStart(4)} | ${line}`).join('\n');
+      }
+    }
+    found.push(reference);
+  }
+  return found;
+}
+
+export async function readServable(root, relative, { maxBytes = MAX_FILE_BYTES } = {}) {
+  const path = await resolveInside(root, relative);
+  if (!path) return { status: 404, error: 'Not found.' };
+  const info = await stat(path).catch(() => null);
+  if (!info || !info.isFile()) return { status: 404, error: 'Not found.' };
+  if (info.size > maxBytes) return { status: 413, error: `File is larger than ${Math.round(maxBytes / 1024 / 1024)} MB.` };
+  const body = await readFile(path);
+  return { status: 200, body, contentType: contentTypeFor(path), size: info.size, path };
+}
+
+const safeName = (name) => String(name ?? 'file').replace(/[^\w.\- ]+/g, '_').replace(/^\.+/, '').slice(0, 120) || 'file';
+
+export async function storeAttachment(attachmentsRoot, { name, bytes }) {
+  if (!Buffer.isBuffer(bytes) || bytes.length === 0) throw new Error('Attachment is empty.');
+  if (bytes.length > MAX_ATTACHMENT_BYTES) throw new Error(`Attachment is larger than ${Math.round(MAX_ATTACHMENT_BYTES / 1024 / 1024)} MB.`);
+  await mkdir(attachmentsRoot, { recursive: true });
+  const id = randomUUID();
+  const fileName = `${id.slice(0, 8)}-${safeName(name)}`;
+  const path = join(attachmentsRoot, fileName);
+  await writeFile(path, bytes, { mode: 0o600 });
+  return {
+    id,
+    name: safeName(name),
+    fileName,
+    path,
+    size: bytes.length,
+    contentType: contentTypeFor(fileName),
+    sha256: createHash('sha256').update(bytes).digest('hex'),
+  };
+}

package/src/image-studio.mjs

@@ -0,0 +1,25 @@
+import { fileURLToPath } from 'node:url';
+import { resolveGeminiKey } from './mcp/image-server.mjs';
+
+// How MADRE attaches its image MCP server to a CLI during a lease.
+export const IMAGE_SERVER_PATH = fileURLToPath(new URL('./mcp/image-server.mjs', import.meta.url));
+export const IMAGE_SERVER_NAME = 'pulse-image';
+export const IMAGE_TOOL = 'generate_image';
+
+export function imageStudioFor({ enabled, model, outDir, env = process.env }) {
+  if (!enabled || !outDir) return null;
+  return {
+    name: IMAGE_SERVER_NAME,
+    tool: IMAGE_TOOL,
+    command: process.execPath,
+    args: [IMAGE_SERVER_PATH],
+    env: {
+      PULSE_IMAGE_OUT_DIR: outDir,
+      PULSE_IMAGE_MODEL: model ?? 'gemini-2.5-flash-image',
+      ...(env.GEMINI_API_KEY ? { GEMINI_API_KEY: env.GEMINI_API_KEY } : {}),
+      ...(env.PULSE_IMAGE_FAKE ? { PULSE_IMAGE_FAKE: env.PULSE_IMAGE_FAKE } : {}),
+    },
+  };
+}
+
+export { resolveGeminiKey };

package/src/lease.mjs

@@ -0,0 +1,83 @@
+import { mkdir, readdir, stat } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+import { contentTypeFor } from './files.mjs';
+
+// A creation lease is the human saying, for one message (and the plan it may
+// start): "these agents may create files, here". MADRE makes a fresh
+// directory under <project>/.pulse/out/, points every adapter's write scope at
+// it, and afterwards reports exactly what appeared there as artifacts.
+//
+// Nothing else in the project becomes writable. The lease directory is
+// MADRE's own; add `.pulse/` to the project's ignore file if you do not want
+// artifacts committed.
+
+export const LEASE_ROOT = join('.pulse', 'out');
+
+const stamp = () => {
+  const now = new Date();
+  const pad = (value) => String(value).padStart(2, '0');
+  return `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+};
+
+export async function createLease({ projectRoot, leaseId }) {
+  const name = `${stamp()}-${leaseId.slice(0, 8)}`;
+  const relativeDir = join(LEASE_ROOT, name);
+  const outDir = join(projectRoot, relativeDir);
+  await mkdir(outDir, { recursive: true, mode: 0o755 });
+  return { leaseId, outDir, relativeDir };
+}
+
+// name → { size, mtimeMs } for every file under `dir`, recursively.
+export async function snapshot(dir) {
+  const files = new Map();
+  async function walk(current) {
+    let entries = [];
+    try { entries = await readdir(current, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      const path = join(current, entry.name);
+      if (entry.isDirectory()) { await walk(path); continue; }
+      if (!entry.isFile()) continue;
+      const info = await stat(path).catch(() => null);
+      if (info) files.set(relative(dir, path).split(sep).join('/'), { size: info.size, mtimeMs: info.mtimeMs });
+    }
+  }
+  await walk(dir);
+  return files;
+}
+
+// Files that are new or changed between two snapshots, as artifacts the room
+// can show: paths are relative to the project so /api/files can serve them.
+export function diffSnapshots(before, after, { relativeDir }) {
+  const artifacts = [];
+  for (const [name, info] of after) {
+    const previous = before.get(name);
+    if (previous && previous.size === info.size && previous.mtimeMs === info.mtimeMs) continue;
+    artifacts.push({
+      name: name.split('/').pop(),
+      path: `${relativeDir.split(sep).join('/')}/${name}`,
+      size: info.size,
+      contentType: contentTypeFor(name),
+      status: previous ? 'changed' : 'created',
+    });
+  }
+  return artifacts.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+export function leaseInstructions({ outDir, agentId, scopes = { write: true, imageGen: agentId === 'codex' }, capable = null, imageStudio = null, control = false }) {
+  const canImage = Boolean(scopes.imageGen);
+  const couldImage = capable ? Boolean(capable.imageGen?.capable) : canImage;
+  return [
+    control
+      ? `CONTROL (#3): the human put you in command of this project at ${outDir}. You may read, create and modify its files without asking, one change at a time, minimal and reversible. MADRE took a checkpoint before this turn; everything you change is listed to the human afterwards and can be undone in one click.`
+      : `CREATION LEASE: the human allows you to create files for this request, only inside ${outDir}.`,
+    control
+      ? 'Never touch .git, .pulse, .env files or credentials: writes there are denied and reverted. Do not run destructive commands. Do not delegate this power: other agents you involve work read-only.'
+      : 'Write every file you produce there (images, code, documents); paths elsewhere are denied.',
+    control ? 'End with a short list of the files you changed and why.' : 'Reading the project stays allowed. Do not modify project files.',
+    imageStudio ? `You can generate images with the MCP tool ${imageStudio.tool} (server ${imageStudio.name}): pass a detailed prompt and a file_name; it saves the PNG into the lease directory and returns the path.`
+      : canImage ? 'You can generate images; save them into the lease directory with a descriptive file name.'
+      : couldImage ? 'Image generation is switched off for this request; if asked for an image, say so and do not attempt it.'
+        : 'You cannot generate images from this CLI; if asked for one, say so plainly instead of attempting it.',
+    'List the files you created (or "none") before any plan block; nothing may follow a plan block.',
+  ].filter(Boolean).join('\n');
+}