@jossuealcala/madre 0.4.1 → 0.5.1

package/src/modules/sdk.mjs

@@ -51,6 +51,19 @@ export function dependencies(runs) {
   return list.filter((dep) => dep && dep.name).map((dep) => ({ name: String(dep.name), version: dep.version ?? null, target: dep.target ?? null }));
 }
 
+// Every field this contract answers to. Thirty-four of them and all but two optional, which is
+// generous until you misspell one: `sumary` used to install without a word and leave a card with
+// an empty summary. A key MADRE does not know is not fatal — a module written for a newer MADRE
+// may carry fields this one has not learned yet — so it is said out loud instead of refused.
+export const MODULE_FIELDS = new Set([
+  'id', 'kind', 'name', 'vendor', 'package', 'version', 'tracks', 'updates', 'summary', 'creates',
+  'requires', 'models', 'commands', 'card', 'configKey', 'settings', 'controls', 'routes',
+  'conditions', 'slash', 'status', 'preflight', 'detect', 'confirm', 'installCommand',
+  'updatePlan', 'toolsForTurn', 'toggle', 'onToggle', 'onSettings', 'onEvent', 'toggledEvent',
+  'toggledBody', 'describe',
+]);
+export const unknownFields = (spec) => Object.keys(spec ?? {}).filter((key) => !MODULE_FIELDS.has(key));
+
 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.`);
@@ -59,6 +72,8 @@ export function defineModule(spec) {
   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 ?? null,
+    // Keys this contract does not answer to. Carried so whoever installs the module is told.
+    unknown: unknownFields(spec),
     // 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,

package/src/outbound.mjs

@@ -269,7 +269,7 @@ export class OutboundLog {
 export function outboundView({ log = null, state = {}, agents = [] } = {}) {
   const counts = log?.counts() ?? {};
   const vendors = { codex: 'OpenAI', claude: 'Anthropic', gemini: 'Google', opencode: 'the provider OpenCode is signed in to' };
-  const crew = agents.filter((agent) => agent.detected && !agent.local).map((agent) => `@${agent.id} → ${vendors[agent.id] ?? 'its own provider'}`);
+  const crew = agents.filter((agent) => agent.detected && !agent.local).map((agent) => `@${agent.id} → ${agent.route?.destination ?? vendors[agent.id] ?? 'its own provider'}`);
   const destinations = DESTINATIONS.map((one) => ({
     id: one.id,
     to: one.id === 'crew' && crew.length ? crew.join(' · ') : one.to,

package/src/room/control.mjs

@@ -29,7 +29,7 @@ export class ControlDesk {
     this.#checkpoints.set(checkpoint.id, checkpoint);
     // Prevention first: .env files and MADRE's folders are read-only for the length of the turn.
     const guard = await guardForbidden(this.#projectRoot);
-    const run = { agent: agent.id, messageId, checkpoint, since: new Date().toISOString(), guard, mode };
+    const run = { agent: agent.id, messageId, checkpoint, since: new Date().toISOString(), guard, mode, scratchDir: null };
     if (mode >= 3) this.#holder = run;
     const lease = { leaseId: checkpoint.id, outDir: this.#projectRoot, relativeDir: '.', scopes: { ...enabledScopes, write: true }, control: mode >= 3, airlock: mode === 4, create: mode === 2, checkpoint };
     if (mode < 3) return { run, lease, announcement: null };
@@ -43,7 +43,14 @@ export class ControlDesk {
   async settle(run) {
     const diff = await diffCheckpoint(this.#projectRoot, run.checkpoint);
     const additive = run.mode === 2;
-    const toRevert = new Set(diff.forbidden);
+    // The draft folder MADRE itself hands the agent lives under `.pulse/out/`, and `.pulse/` is a
+    // forbidden zone — so the room named a place to write, the agent wrote there, and the room
+    // undid it. Nobody noticed here because this project ignores `.pulse/` and git never reported
+    // the files; in a project that does not, `/module` never reached its install card. A turn's
+    // own scratch folder is not a forbidden zone FOR THAT TURN. Every other `.pulse` path still is.
+    const ownScratch = run.scratchDir ? `${run.scratchDir.replace(/\/$/, '')}/` : null;
+    const mine = (path) => Boolean(ownScratch) && path.startsWith(ownScratch);
+    const toRevert = new Set(diff.forbidden.filter((path) => !mine(path)));
     if (additive) for (const file of diff.files) if (file.status !== 'A') toRevert.add(file.path);
     let reverted = [];
     if (toRevert.size) {
@@ -51,7 +58,7 @@ export class ControlDesk {
       reverted = [...restored.restored, ...restored.removed];
     }
     const kept = diff.files.filter((file) => !toRevert.has(file.path));
-    const changes = { checkpointId: run.checkpoint.id, agent: run.agent, messageId: run.messageId, mode: run.mode ?? 3, files: kept, stat: diff.stat, forbiddenReverted: diff.forbidden.length ? reverted.filter((path) => diff.forbidden.includes(path)) : [], existingReverted: additive ? reverted.filter((path) => !diff.forbidden.includes(path)) : [] };
+    const changes = { checkpointId: run.checkpoint.id, agent: run.agent, messageId: run.messageId, mode: run.mode ?? 3, files: kept, stat: diff.stat, forbiddenReverted: reverted.filter((path) => diff.forbidden.includes(path) && !mine(path)), existingReverted: additive ? reverted.filter((path) => !diff.forbidden.includes(path)) : [] };
     const count = changes.files.length;
     const notes = [
       changes.forbiddenReverted.length ? `${changes.forbiddenReverted.length} write(s) into forbidden zones were reverted.` : null,

package/src/room.mjs

@@ -945,6 +945,18 @@ export class Room {
       await this.#emit('message.failed', { messageId, target: targetId, planId, error: `${agent.label} was detected, but its MADRE adapter is not enabled yet.` });
       return null;
     }
+    if (agent.route?.custom && !agent.route.allowed) {
+      const destination = agent.route.host ?? 'an unrecognised host';
+      const source = agent.route.source ?? 'a custom endpoint setting';
+      const official = agent.id === 'codex' ? 'OpenAI' : agent.id === 'claude' ? 'Anthropic' : 'the agent\'s official service';
+      await this.#emit('message.failed', {
+        messageId,
+        target: targetId,
+        planId,
+        error: `MADRE blocked @${agent.id} before sending the briefing: ${source} points to ${destination}, not ${official}. Remove that override to use the official service, or set PULSE_ALLOW_CUSTOM_AGENT_ENDPOINTS=${agent.id} only if you trust that endpoint.`,
+      });
+      return null;
+    }
 
     const priorEvents = await this.#store.readAll();
     // @madre never reads its own canned replies back: a small model would echo them.
@@ -1185,6 +1197,9 @@ export class Room {
       // CREATE: photograph the project now; after the turn only what appeared stays.
       const seat = await this.#controlDesk.begin({ agent, messageId, enabledScopes: enabled, mode: 2 });
       createRun = seat.run;
+      // The folder this turn was told to draft in, so settling it does not undo what it was
+      // invited to write. Only this turn's own folder; every other `.pulse` path stays forbidden.
+      createRun.scratchDir = lease.scratchDir ?? null;
       lease = { ...lease, checkpoint: seat.run.checkpoint };
     }
     turnScopes.imageGen = Boolean(lease?.scopes?.imageGen);

package/src/runtime-detection.mjs

@@ -38,6 +38,55 @@ const definitions = [
   },
 ];
 
+const OFFICIAL_DESTINATIONS = {
+  codex: { label: 'OpenAI', hosts: ['api.openai.com'], variable: 'OPENAI_BASE_URL' },
+  claude: { label: 'Anthropic', hosts: ['api.anthropic.com'], variable: 'ANTHROPIC_BASE_URL' },
+};
+
+const enabled = (value) => /^(1|true|yes)$/i.test(String(value ?? '').trim());
+
+function customRoutesAllowed(agentId, env) {
+  const raw = String(env.PULSE_ALLOW_CUSTOM_AGENT_ENDPOINTS ?? '').trim().toLowerCase();
+  if (/^(1|true|all)$/.test(raw)) return true;
+  return raw.split(',').map((item) => item.trim()).includes(agentId);
+}
+
+function routeHost(value) {
+  try { return new URL(value).hostname.toLowerCase(); } catch { return null; }
+}
+
+// A CLI owns its network connection, but MADRE owns the document handed to that CLI. Name the
+// actual destination without ever returning a credential, path or query string. Unknown base URLs
+// are held at the door until the human explicitly trusts that agent's endpoint.
+export function agentRouteFromEnvironment(agentId, env = process.env) {
+  if (agentId === 'claude' && enabled(env.CLAUDE_CODE_USE_BEDROCK)) {
+    return { kind: 'provider', destination: 'Amazon Bedrock', source: 'CLAUDE_CODE_USE_BEDROCK', host: null, custom: false, allowed: true };
+  }
+  if (agentId === 'claude' && enabled(env.CLAUDE_CODE_USE_VERTEX)) {
+    return { kind: 'provider', destination: 'Google Vertex AI', source: 'CLAUDE_CODE_USE_VERTEX', host: null, custom: false, allowed: true };
+  }
+  if (agentId === 'claude' && enabled(env.CLAUDE_CODE_USE_FOUNDRY)) {
+    return { kind: 'provider', destination: 'Microsoft Foundry', source: 'CLAUDE_CODE_USE_FOUNDRY', host: null, custom: false, allowed: true };
+  }
+
+  const official = OFFICIAL_DESTINATIONS[agentId];
+  if (!official) return null;
+  const raw = String(env[official.variable] ?? '').trim();
+  if (!raw) return { kind: 'official', destination: official.label, source: null, host: null, custom: false, allowed: true };
+  const host = routeHost(raw);
+  const isOfficial = Boolean(host && official.hosts.some((candidate) => host === candidate || host.endsWith(`.${candidate}`)));
+  if (isOfficial) return { kind: 'official', destination: official.label, source: official.variable, host, custom: false, allowed: true };
+  const allowed = customRoutesAllowed(agentId, env);
+  return {
+    kind: 'custom',
+    destination: host ? `custom endpoint · ${host}` : 'custom endpoint',
+    source: official.variable,
+    host,
+    custom: true,
+    allowed,
+  };
+}
+
 async function executable(path) {
   try {
     await access(path, constants.X_OK);
@@ -99,6 +148,7 @@ export async function detectAgents({ env = process.env } = {}) {
       adapter: definition.adapter ?? null,
       path,
       version: path ? await readVersion(path, definition.versionArgs) : null,
+      route: agentRouteFromEnvironment(definition.id, env),
     };
   }));
 }

package/src/server.mjs

@@ -47,6 +47,9 @@ import { applyKey, keyPlanFor } from './credentials.mjs';
 import { loadConfig as readConfig, updateConfig } from './config.mjs';
 import { Privacy, normalizeTerms, privacySettings } from './privacy.mjs';
 import { checkForUpdate, detectInstall, updateCommand, releaseUrl, applyCommand } from './updates.mjs';
+
+// Where a person reads the module contract, in the language the room is speaking.
+const SDK_PAGE = { es: 'https://madre.run/sdk/', en: 'https://madre.run/en/sdk/' };
 import { moduleUpdate } from './modules/updates.mjs';
 import { adoptStrays, chatIndex, chatLedger, createChat, deleteChat, isChatId, listChats, openChat as openChatIndex, projectFloor, renameChat, touchChat, MAIN_CHAT } from './chats.mjs';
 import { spawn } from 'node:child_process';
@@ -193,7 +196,7 @@ export async function createPulseServer({
   const install = detectInstall({ projectRoot: canonicalProjectRoot });
   async function versionView({ force = false } = {}) {
     const check = await checkForUpdate({ name: PACKAGE.name, current: PACKAGE.version, cacheFile: join(root, 'updates.json'), fetchImpl: reportFetch, enabled: updatesEnabled(), force });
-    return { project: canonicalProjectRoot, ...check, name: PACKAGE.name, install, command: updateCommand(install, PACKAGE.name, check.latest ?? 'latest'), release: check.latest ? releaseUrl(PACKAGE.repository, check.latest) : null, envWins: process.env.PULSE_UPDATE_CHECK !== undefined };
+    return { project: canonicalProjectRoot, ...check, name: PACKAGE.name, install, command: updateCommand(install, PACKAGE.name, check.latest ?? 'latest'), release: check.latest ? releaseUrl(PACKAGE.repository, check.latest, roomLanguage()) : null, envWins: process.env.PULSE_UPDATE_CHECK !== undefined };
   }
   // Keeping the day's cache warm. MODULES is served from what is already on disk, so the looking
   // happens after the screen is answered, never in front of it: at most once an hour per room,
@@ -250,7 +253,7 @@ export async function createPulseServer({
     else if (!fifth.ready && index >= 0) { agents.splice(index, 1); changed = true; }
     if (room) {
       room.setInvoker(MADRE_ADAPTER, fifth.ready ? madreInvoker({ memory, ollama: () => ({ ...ollama, chatModel: ollama.madreModel ?? ollama.chatModel }), fetchImpl: reportFetch }) : null);
-      if (changed) await room.record('agents.updated', { agents: agents.map((agent) => ({ id: agent.id, label: agent.label, detected: agent.detected, ready: agent.ready, version: agent.version, local: Boolean(agent.local) })), removed: fifth.ready ? [] : [MADRE_AGENT_ID], reason: fifth.ready ? `@madre is in the room · ${fifth.version}` : '@madre left the room: Ollama has no chat model running' });
+      if (changed) await room.record('agents.updated', { agents: agents.map((agent) => ({ id: agent.id, label: agent.label, detected: agent.detected, ready: agent.ready, version: agent.version, local: Boolean(agent.local), route: agent.route ?? null })), removed: fifth.ready ? [] : [MADRE_AGENT_ID], reason: fifth.ready ? `@madre is in the room · ${fifth.version}` : '@madre left the room: Ollama has no chat model running' });
       // That a local model is running is not the same as it being of use on this project, and
       // the second thing is the one a person needs told. Said once per model, in the room, with
       // the one button that settles it — the crew line above fires only when the crew CHANGES,
@@ -465,7 +468,7 @@ export async function createPulseServer({
       const index = agents.findIndex((item) => item.id === next.id);
       if (index === -1) { agents.push(next); changed = true; continue; }
       const before = agents[index];
-      if (before.detected !== next.detected || before.ready !== next.ready || before.version !== next.version || before.path !== next.path) {
+      if (before.detected !== next.detected || before.ready !== next.ready || before.version !== next.version || before.path !== next.path || JSON.stringify(before.route ?? null) !== JSON.stringify(next.route ?? null)) {
         agents[index] = { ...before, ...next };
         changed = true;
       }
@@ -473,7 +476,7 @@ export async function createPulseServer({
     await refreshSessions();
     if (changed && announce) {
       await room.record('agents.updated', {
-        agents: agents.map((agent) => ({ id: agent.id, label: agent.label, detected: agent.detected, ready: agent.ready, version: agent.version, local: Boolean(agent.local) })),
+        agents: agents.map((agent) => ({ id: agent.id, label: agent.label, detected: agent.detected, ready: agent.ready, version: agent.version, local: Boolean(agent.local), route: agent.route ?? null })),
         removed: [],
         reason: 'the room looked again for the agents on this computer',
       });
@@ -846,7 +849,7 @@ export async function createPulseServer({
         response.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
         return response.end(html);
       }
-      if (request.method === 'GET' && ['/app.js', '/brands.js', '/troubleshooting.js', '/inquiry.js', '/i18n.js', '/es.js', '/resay.js'].includes(url.pathname)) {
+      if (request.method === 'GET' && ['/app.js', '/brands.js', '/troubleshooting.js', '/inquiry.js', '/i18n.js', '/es.js', '/resay.js', '/syntax.js'].includes(url.pathname)) {
         const js = await readFile(join(publicDirectory, url.pathname.slice(1)));
         response.writeHead(200, { 'content-type': 'text/javascript; charset=utf-8' });
         return response.end(js);
@@ -1474,7 +1477,7 @@ export async function createPulseServer({
       if (request.method === 'GET' && url.pathname === '/api/extensions') {
         const extensions = await describeModules(await moduleContext());
         void warmModuleUpdates(extensions);
-        return sendJson(response, 200, { installing, extensions, failures: loadFailures, folders: moduleFolders({ stateRoot: root, projectRoot: canonicalProjectRoot }), sdk: 'https://github.com/jossuealcacao-exe/madre/blob/main/docs/SDK.md' });
+        return sendJson(response, 200, { installing, extensions, failures: loadFailures, folders: moduleFolders({ stateRoot: root, projectRoot: canonicalProjectRoot }), sdk: SDK_PAGE[roomLanguage()] ?? SDK_PAGE.es });
       }
       // The human installs a module file an agent wrote (or they did): checked first, then copied into the chosen folder.
       if (request.method === 'POST' && url.pathname === '/api/extensions/install-file') {

package/src/updates.mjs

@@ -51,7 +51,15 @@ export function applyCommand({ install, name, version, port, projectRoot }) {
   }
 }
 
-export function releaseUrl(repository, version) {
+// Where a person reads what a version brought. The product's own house, in the language the room
+// is speaking — a release page on a code host is written for people who already work there, and
+// whoever pressed this button only wanted to know what changed. The repository stays the fallback
+// for a build with no house to point at.
+export const CHANGES_PAGE = { es: 'https://madre.run/cambios/', en: 'https://madre.run/en/changelog/' };
+
+export function releaseUrl(repository, version, language = 'es') {
+  const page = CHANGES_PAGE[language] ?? CHANGES_PAGE.es;
+  if (page) return version ? `${page}#v${version}` : page;
   const url = String(repository?.url ?? repository ?? '').replace(/^git\+/, '').replace(/\.git$/, '');
   return url ? `${url}/releases/tag/v${version}` : null;
 }