@jossuealcala/madre 0.3.3 → 0.4.1

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 = {}) => {

package/src/modules/updates.mjs

@@ -0,0 +1,81 @@
+// Is there a newer version of what a module is? Two kinds of answer, because there are two kinds
+// of module.
+//
+// A module that ships with MADRE has its own version, written in its file and starting at 1.0.0.
+// It cannot update on its own: it arrives in a release, so its update is MADRE's update, and the
+// card says which release it travels in.
+//
+// A module that is a wrapper around something else — @playwright/mcp, Ollama, the AHP+ CLI — has
+// no version of its own worth showing. Its version is that thing's version, found on this
+// computer, and its update is that thing's next release. A module declares this once, in the SDK:
+//
+//   tracks: { name: '@playwright/mcp', npm: '@playwright/mcp' }
+//   tracks: { name: 'ollama', github: 'ollama/ollama' }
+//
+// Every check is cached a day in ~/.pulse/updates/, goes out only while the release channel is on,
+// and sends nothing but the name of the thing being asked about. A screen never waits on it:
+// MODULES reads the cache, and the button on a card is what forces a fresh look.
+
+import { join, dirname } from 'node:path';
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { checkForUpdate, compareVersions, UPDATE_TTL_MS } from '../updates.mjs';
+
+export const GITHUB_RELEASES = 'https://api.github.com/repos';
+
+async function readCache(file) {
+  try { return JSON.parse(await readFile(file, 'utf8')); } catch { return null; }
+}
+
+// The newest release of a repository, by its tag. Same shape and same cache as the registry read,
+// because a card does not care where a version comes from.
+export async function checkGithubRelease({ repo, current, cacheFile, fetchImpl = globalThis.fetch, now = Date.now(), ttlMs = UPDATE_TTL_MS, enabled = true, force = false, cacheOnly = false, timeoutMs = 4000 } = {}) {
+  const cached = cacheFile ? await readCache(cacheFile) : null;
+  const known = cached?.name === repo ? cached : null;
+  const fresh = known && Number.isFinite(known.checkedAt) && now - known.checkedAt < ttlMs;
+  let latest = known?.latest ?? null;
+  let checkedAt = known?.checkedAt ?? null;
+  let source = latest ? 'cache' : 'none';
+  let error = null;
+  if (enabled && !cacheOnly && (force || !fresh)) {
+    try {
+      const response = await fetchImpl(`${GITHUB_RELEASES}/${repo}/releases/latest`, { headers: { accept: 'application/vnd.github+json' }, signal: AbortSignal.timeout(timeoutMs) });
+      if (!response.ok) throw new Error(`github HTTP ${response.status}`);
+      const doc = await response.json();
+      const tag = String(doc?.tag_name ?? doc?.name ?? '').trim().replace(/^v/, '');
+      if (!tag) throw new Error('github answered without a release');
+      latest = tag;
+      checkedAt = now;
+      source = 'github';
+      if (cacheFile) {
+        await mkdir(dirname(cacheFile), { recursive: true }).catch(() => {});
+        await writeFile(cacheFile, JSON.stringify({ name: repo, latest, checkedAt })).catch(() => {});
+      }
+    } catch (cause) {
+      error = cause.message;
+      if (!latest) source = 'error';
+    }
+  }
+  if (!enabled) source = latest ? 'cache' : 'off';
+  return { enabled, current: current ?? null, latest, available: Boolean(latest && current && compareVersions(current, latest) < 0), checkedAt, source, error };
+}
+
+// What one card should say about being up to date. `item` is a described module.
+export async function moduleUpdate(item, { stateRoot, madre, fetchImpl = globalThis.fetch, enabled = true, force = false, cacheOnly = !force, now = Date.now() } = {}) {
+  const tracks = item?.tracks ?? null;
+  const common = { fetchImpl, enabled, force, cacheOnly, now };
+  if (!tracks) {
+    // It ships with MADRE, so what can be newer is MADRE.
+    const check = await checkForUpdate({ name: madre.name, current: madre.version, cacheFile: join(stateRoot, 'updates.json'), ...common });
+    return { via: 'madre', name: madre.name, current: item?.version ?? null, ships: madre.version, latest: check.latest, available: check.available, checkedAt: check.checkedAt, source: check.source, error: check.error };
+  }
+  const cacheFile = join(stateRoot, 'updates', `${item.id}.json`);
+  if (tracks.npm) {
+    const check = await checkForUpdate({ name: tracks.npm, current: item.version, cacheFile, ...common });
+    return { via: 'npm', name: tracks.npm, current: item.version ?? null, latest: check.latest, available: check.available, checkedAt: check.checkedAt, source: check.source, error: check.error };
+  }
+  if (tracks.github) {
+    const check = await checkGithubRelease({ repo: tracks.github, current: item.version, cacheFile, ...common });
+    return { via: 'github', name: tracks.name ?? tracks.github, latest: check.latest, current: item.version ?? null, available: check.available, checkedAt: check.checkedAt, source: check.source, error: check.error };
+  }
+  return { via: 'none', name: tracks.name ?? item.name, current: item.version ?? null, latest: null, available: false, checkedAt: null, source: 'none', error: null };
+}

package/src/ollama.mjs

@@ -34,16 +34,19 @@ export async function probeOllama({ host = ollamaHost(), fetchImpl = globalThis.
     const response = await fetchImpl(`${host}/api/tags`, { signal: AbortSignal.timeout(timeoutMs) });
     if (!response.ok) return { running: false, host, models: [], embedModel: null, chatModel: null, error: `HTTP ${response.status}` };
     const payload = await response.json();
+    // What Ollama itself is running. It answers or it does not; either way the probe goes on.
+    const version = await fetchImpl(`${host}/api/version`, { signal: AbortSignal.timeout(timeoutMs) })
+      .then((answer) => (answer.ok ? answer.json() : null)).then((body) => body?.version ?? null).catch(() => null);
     const models = (payload.models ?? []).map((model) => ({ name: model.name, size: model.size ?? 0, family: model.details?.family ?? '', details: model.details ?? {} }));
     const embeds = models.filter(isEmbedModel);
     const chats = models.filter((model) => !isEmbedModel(model));
     return {
-      running: true, host, models,
+      running: true, host, version, models,
       embedModel: pick(embeds, EMBED_MODELS, env.PULSE_OLLAMA_EMBED_MODEL),
       chatModel: pick(chats, CHAT_MODELS, env.PULSE_OLLAMA_MODEL),
     };
   } catch (error) {
-    return { running: false, host, models: [], embedModel: null, chatModel: null, error: error.message };
+    return { running: false, host, version: null, models: [], embedModel: null, chatModel: null, error: error.message };
   }
 }
 

package/src/outbound.mjs

@@ -0,0 +1,297 @@
+// What left this machine.
+//
+// MADRE runs on your computer and keeps everything it knows in a file you own, and that sentence
+// is worth exactly as much as the list that qualifies it. Something does leave: a version check,
+// an embedding, a crash report, the briefing itself. A person deciding whether to point this at a
+// private codebase needs that list to be complete, and needs it to come from the code rather than
+// from a promise in a README.
+//
+// So there are two halves here and they are different things.
+//
+// DESTINATIONS is the declaration: every address MADRE's own process may reach, what it says
+// there, what puts it on and where you turn it off. It is written by hand because it says what a
+// request MEANS, and no wrapper can know that.
+//
+// The log is the check on the declaration. Every fetch the room's process makes goes through one
+// wrapper — MADRE's own calls and any a module makes, because a module installed tomorrow runs
+// inside this process and cannot opt out of it — and lands in a line saying where it went and
+// when. An address nobody declared shows up as one nobody declared, which is the whole point.
+//
+// What is never recorded: bodies, headers, and the values of query parameters. The names stay.
+// The Gemini embedding endpoint takes the key in the URL, and a log of what left this machine
+// would be a poor place to leave it.
+
+import { appendFile, mkdir, open, stat, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+
+export const KEEP = 200;                 // lines held for the screen
+export const MAX_BYTES = 512 * 1024;     // the file is trimmed to the last KEEP lines past this
+const LOCAL = new Set(['127.0.0.1', 'localhost', '::1', '0.0.0.0', '[::1]']);
+
+// Where an unknown condition goes when somebody presses SEND. It lives here because this is the
+// file that has to name every address MADRE can reach; the room reads it from here.
+// The collector, under the product's own name. The address a human reads in the outbound log is
+// part of what they are being asked to trust, and a workers.dev subdomain with an account name in
+// it reads like somebody's scratch endpoint. The old address must keep answering: every room on
+// 0.4.0 and earlier carries it compiled in, and turning it off would stop their reports silently.
+export const DEFAULT_REPORT_URL = 'https://madre.run/v1/reports';
+export const LEGACY_REPORT_URL = 'https://madre-reports.jossue-alcala-o.workers.dev/v1/reports';
+
+// The declaration. `what` is the honest sentence: what a request carries, not what it is called.
+export const DESTINATIONS = [
+  {
+    id: 'crew', host: null, to: 'whoever runs the agent you send a turn to',
+    what: 'The briefing — the document above, your question, the memories it summoned and the transcript it carries.',
+    when: 'every turn you send to an agent that is not @madre',
+    where: 'you choose it every time you send a turn; @madre answers on this computer and sends nothing',
+    inside: false,
+  },
+  {
+    id: 'embeddings', host: 'generativelanguage.googleapis.com', match: (url) => /batchEmbedContents/.test(url.pathname), to: 'Google · Gemini embeddings',
+    what: 'The text of what is being embedded: the first 2000 characters of each memory, and the question a recall is made of.',
+    when: 'a memory is written or recalled, while embeddings are set to Gemini',
+    where: 'MU/TH/UR → MEMORY → EMBEDDINGS · OLLAMA keeps it on this computer, OFF drops back to words',
+    inside: true,
+  },
+  {
+    id: 'image', host: 'generativelanguage.googleapis.com', match: (url) => /generateContent/.test(url.pathname), to: 'Google · Gemini image model',
+    what: 'The prompt an agent wrote for an image.',
+    when: 'an agent calls the image tool during a lease',
+    where: 'MODULES → IMAGE STUDIO',
+    // It runs in a process of its own and writes its own line into this same log, so it is here.
+    inside: true,
+  },
+  {
+    id: 'npm', host: 'registry.npmjs.org', to: 'the npm registry',
+    what: 'The name of a package, to read the version of its latest release. Nothing about you or your project.',
+    when: 'at most once a day per package, while the release channel is on',
+    where: 'MU/TH/UR → RELEASE CHANNEL · or PULSE_UPDATE_CHECK=0',
+    inside: true,
+  },
+  {
+    id: 'github', host: 'api.github.com', to: 'GitHub',
+    what: 'The name of a repository, to read the tag of its latest release. Nothing about you or your project.',
+    when: 'at most once a day per repository, while the release channel is on',
+    where: 'MU/TH/UR → RELEASE CHANNEL · or PULSE_UPDATE_CHECK=0',
+    inside: true,
+  },
+  {
+    id: 'reports', host: new URL(DEFAULT_REPORT_URL).hostname, to: "the author's error collector",
+    what: 'An unknown condition: what broke, where in MADRE, and the version. Paths are cut back and your words are not in it.',
+    when: 'you press SEND — or on its own, only while auto-report is on',
+    where: 'MU/TH/UR → AUTO-REPORT UNKNOWN CONDITIONS · or PULSE_REPORT_URL',
+    inside: true,
+  },
+  {
+    id: 'anthropic', host: 'api.anthropic.com', to: 'Anthropic',
+    what: 'Your Claude Code token, to read how much of your plan is left. It is read from where Claude keeps it and never stored by MADRE.',
+    when: 'while a Claude session is being watched for its quota',
+    where: '⚙ CONNECTIONS → CLAUDE',
+    inside: true,
+  },
+  {
+    id: 'ollama', host: null, local: true, to: 'Ollama, on this computer',
+    what: 'Memories to embed, exchanges to distil, and whatever you ask @madre. It goes to a port on this machine and stops there.',
+    when: 'while Ollama is running',
+    where: 'MODULES → OLLAMA',
+    inside: true,
+  },
+];
+
+const byId = new Map(DESTINATIONS.map((one) => [one.id, one]));
+export const destination = (id) => byId.get(id) ?? null;
+
+// Which declaration a URL belongs to. An address nobody declared is said to be exactly that.
+export function classify(rawUrl, { reportHost = null } = {}) {
+  let url;
+  try { url = new URL(rawUrl); } catch { return { id: 'unknown', to: String(rawUrl).slice(0, 80), local: false }; }
+  const host = url.hostname.replace(/^\[|\]$/g, '');
+  if (LOCAL.has(host)) return { id: url.port === '11434' ? 'ollama' : 'room', to: `${host}:${url.port || '80'}`, local: true };
+  if (reportHost && host === reportHost) return { id: 'reports', to: byId.get('reports').to, local: false };
+  for (const one of DESTINATIONS) {
+    if (!one.host || one.host !== host) continue;
+    if (one.match && !one.match(url)) continue;
+    return { id: one.id, to: one.to, local: false };
+  }
+  return { id: 'unknown', to: host, local: false };
+}
+
+// One line of the log. No body, no headers, and no query VALUES — only which parameters were set.
+export function lineFor({ url, method = 'GET', status = null, ok = false, ms = 0, bytes = null, error = null, at, reportHost = null }) {
+  const kind = classify(url, { reportHost });
+  let path = '';
+  let params = [];
+  try {
+    const parsed = new URL(url);
+    path = parsed.pathname;
+    params = [...parsed.searchParams.keys()];
+  } catch { path = ''; }
+  return {
+    at: at ?? new Date().toISOString(),
+    id: kind.id,
+    to: kind.to,
+    local: Boolean(kind.local),
+    method: String(method || 'GET').toUpperCase(),
+    path,
+    ...(params.length ? { params } : {}),
+    ...(Number.isFinite(status) ? { status } : {}),
+    ok: Boolean(ok),
+    ms: Math.round(ms),
+    ...(Number.isFinite(bytes) ? { bytes } : {}),
+    ...(error ? { error } : {}),
+  };
+}
+
+async function tail(file, window = 96 * 1024) {
+  let handle;
+  try {
+    const size = (await stat(file)).size;
+    if (!size) return [];
+    handle = await open(file, 'r');
+    const length = Math.min(window, size);
+    const buffer = Buffer.alloc(length);
+    await handle.read(buffer, 0, length, size - length);
+    const lines = buffer.toString('utf8').split('\n').filter(Boolean);
+    const out = [];
+    for (const line of lines) {
+      try { out.push(JSON.parse(line)); } catch { /* a half line at the window's edge */ }
+    }
+    return out;
+  } catch {
+    return [];
+  } finally {
+    await handle?.close().catch(() => {});
+  }
+}
+
+export class OutboundLog {
+  #file;
+  #keep;
+  #recent = [];
+  #counts = new Map();
+  #writes = Promise.resolve();
+  #reportHost = null;
+  #restore = null;
+
+  constructor({ file = null, keep = KEEP } = {}) {
+    this.#file = file;
+    this.#keep = keep;
+  }
+
+  // The collector's address is a setting, so which host counts as the collector is read live.
+  watchReportUrl(url) {
+    try { this.#reportHost = url ? new URL(url).hostname : null; } catch { this.#reportHost = null; }
+    return this;
+  }
+
+  async load() {
+    if (!this.#file) return this;
+    const lines = await tail(this.#file);
+    this.#recent = lines.slice(-this.#keep);
+    for (const line of this.#recent) this.#count(line);
+    return this;
+  }
+
+  #count(line) {
+    const at = this.#counts.get(line.id) ?? { calls: 0, failed: 0, last: null };
+    at.calls += 1;
+    if (!line.ok) at.failed += 1;
+    at.last = line.at;
+    this.#counts.set(line.id, at);
+  }
+
+  record(input) {
+    const line = lineFor({ ...input, reportHost: this.#reportHost });
+    this.#recent.push(line);
+    if (this.#recent.length > this.#keep) this.#recent.splice(0, this.#recent.length - this.#keep);
+    this.#count(line);
+    if (this.#file) {
+      this.#writes = this.#writes
+        .then(async () => {
+          await mkdir(dirname(this.#file), { recursive: true }).catch(() => {});
+          await appendFile(this.#file, `${JSON.stringify(line)}\n`);
+          const size = await stat(this.#file).then((one) => one.size, () => 0);
+          // Only a writer that is holding a full screen of lines may rewrite the file: the
+          // image studio appends from its own process and knows nothing of what came before it.
+          if (size > MAX_BYTES && this.#recent.length >= this.#keep) await writeFile(this.#file, `${this.#recent.map((one) => JSON.stringify(one)).join('\n')}\n`);
+        })
+        .catch(() => null);
+    }
+    return line;
+  }
+
+  recent({ limit = 40 } = {}) { return this.#recent.slice(-limit).reverse(); }
+
+  counts() { return Object.fromEntries(this.#counts); }
+
+  // The wrapper. It never changes what the caller gets back and never reads the response body:
+  // a log that consumed what it watched would break the thing it is watching.
+  watch(fetchImpl = globalThis.fetch) {
+    if (fetchImpl?.watched) return fetchImpl;
+    const log = this;
+    const watched = async function outbound(resource, init = {}) {
+      const url = typeof resource === 'string' ? resource : (resource?.url ?? String(resource));
+      const method = init?.method ?? resource?.method ?? 'GET';
+      const bytes = typeof init?.body === 'string' ? Buffer.byteLength(init.body) : null;
+      const started = Date.now();
+      try {
+        const response = await fetchImpl(resource, init);
+        log.record({ url, method, bytes, status: response?.status ?? null, ok: Boolean(response?.ok), ms: Date.now() - started });
+        return response;
+      } catch (error) {
+        // The name and the code, never the message: a message carries the address it failed on
+        // and sometimes what was in it.
+        log.record({ url, method, bytes, ok: false, ms: Date.now() - started, error: error?.code ?? error?.name ?? 'failed' });
+        throw error;
+      }
+    };
+    watched.watched = true;
+    return watched;
+  }
+
+  // Everything in this process, including whatever a module calls. Returns the undo.
+  install(target = globalThis) {
+    if (this.#restore) return this.#restore;
+    const original = target.fetch;
+    // Binding makes a new function, which would hide a watch somebody else already installed;
+    // the mark travels with it so one process logs a request once.
+    const bound = original.bind(target);
+    bound.watched = original.watched;
+    target.fetch = this.watch(bound);
+    this.#restore = () => { target.fetch = original; this.#restore = null; };
+    return this.#restore;
+  }
+
+  async drain() { await this.#writes; }
+}
+
+// The declaration with today's answer filled in: is this one on, and what has it done.
+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 destinations = DESTINATIONS.map((one) => ({
+    id: one.id,
+    to: one.id === 'crew' && crew.length ? crew.join(' · ') : one.to,
+    what: one.what,
+    when: one.when,
+    where: one.where,
+    local: Boolean(one.local),
+    // Whether the call lands in the log at all. Everything MADRE starts does, the image studio
+    // from its own process included; the crew's own conversation with its provider does not.
+    inside: Boolean(one.inside),
+    on: state[one.id] ?? null,
+    calls: counts[one.id]?.calls ?? 0,
+    failed: counts[one.id]?.failed ?? 0,
+    last: counts[one.id]?.last ?? null,
+  }));
+  const undeclared = counts.unknown?.calls ?? 0;
+  return {
+    destinations,
+    recent: log?.recent({ limit: 40 }) ?? [],
+    undeclared,
+    says: undeclared
+      ? `${undeclared} request${undeclared === 1 ? '' : 's'} went to an address nothing here declares. A module can do that; nothing can do it unlogged.`
+      : 'Every request this process made went to an address declared above.',
+  };
+}