@jossuealcala/madre 1.0.4 → 1.0.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (104) hide show
  1. package/CHANGELOG.en.md +106 -1
  2. package/CHANGELOG.md +106 -1
  3. package/NOTICE +30 -0
  4. package/README.en.md +59 -156
  5. package/README.md +60 -161
  6. package/TRADEMARKS.md +18 -0
  7. package/bin/madre.mjs +2 -2
  8. package/docs/REFERENCE.md +1 -1
  9. package/docs/SDK.md +25 -4
  10. package/docs/en/REFERENCE.md +1 -1
  11. package/docs/en/SDK.md +22 -2
  12. package/docs/madre-banner.png +0 -0
  13. package/package.json +1 -1
  14. package/public/app.js +1078 -239
  15. package/public/assets/manual/madre-manual-en.pdf +0 -0
  16. package/public/assets/manual/madre-manual-es.pdf +0 -0
  17. package/public/assets/manual/shots/en-agents.webp +0 -0
  18. package/public/assets/manual/shots/en-code.webp +0 -0
  19. package/public/assets/manual/shots/en-composer.webp +0 -0
  20. package/public/assets/manual/shots/en-connectors.webp +0 -0
  21. package/public/assets/manual/shots/en-continuity.webp +0 -0
  22. package/public/assets/manual/shots/en-coordinator.webp +0 -0
  23. package/public/assets/manual/shots/en-copilot.webp +0 -0
  24. package/public/assets/manual/shots/en-diagnostics.webp +0 -0
  25. package/public/assets/manual/shots/en-home.webp +0 -0
  26. package/public/assets/manual/shots/en-local.webp +0 -0
  27. package/public/assets/manual/shots/en-memory.webp +0 -0
  28. package/public/assets/manual/shots/en-modes.webp +0 -0
  29. package/public/assets/manual/shots/en-modules.webp +0 -0
  30. package/public/assets/manual/shots/en-notes.webp +0 -0
  31. package/public/assets/manual/shots/en-settings.webp +0 -0
  32. package/public/assets/manual/shots/en-windows.webp +0 -0
  33. package/public/assets/manual/shots/es-agents.webp +0 -0
  34. package/public/assets/manual/shots/es-code.webp +0 -0
  35. package/public/assets/manual/shots/es-composer.webp +0 -0
  36. package/public/assets/manual/shots/es-connectors.webp +0 -0
  37. package/public/assets/manual/shots/es-continuity.webp +0 -0
  38. package/public/assets/manual/shots/es-coordinator.webp +0 -0
  39. package/public/assets/manual/shots/es-copilot.webp +0 -0
  40. package/public/assets/manual/shots/es-diagnostics.webp +0 -0
  41. package/public/assets/manual/shots/es-home.webp +0 -0
  42. package/public/assets/manual/shots/es-local.webp +0 -0
  43. package/public/assets/manual/shots/es-memory.webp +0 -0
  44. package/public/assets/manual/shots/es-modes.webp +0 -0
  45. package/public/assets/manual/shots/es-modules.webp +0 -0
  46. package/public/assets/manual/shots/es-notes.webp +0 -0
  47. package/public/assets/manual/shots/es-settings.webp +0 -0
  48. package/public/assets/manual/shots/es-windows.webp +0 -0
  49. package/public/en.js +74 -0
  50. package/public/es.js +493 -136
  51. package/public/i18n.js +45 -7
  52. package/public/index.html +2 -3
  53. package/public/manual-content.js +657 -0
  54. package/public/manual-shots.js +43 -0
  55. package/public/manual.css +228 -0
  56. package/public/manual.html +15 -0
  57. package/public/manual.js +398 -0
  58. package/public/market-art.js +56 -0
  59. package/public/market-view.js +140 -22
  60. package/public/market.js +25 -14
  61. package/public/mcp-catalog.js +62 -0
  62. package/public/resay.js +1 -0
  63. package/public/salas-mac.css +178 -30
  64. package/public/salas-mac.html +5 -5
  65. package/public/salas-mac.js +432 -67
  66. package/public/styles.css +300 -42
  67. package/public/tour-chapters.js +98 -90
  68. package/public/tour.js +63 -21
  69. package/public/troubleshooting.js +145 -10
  70. package/src/adapters/cursor.mjs +56 -7
  71. package/src/adapters/gemini.mjs +12 -1
  72. package/src/adapters/madre.mjs +27 -6
  73. package/src/adapters/process.mjs +5 -2
  74. package/src/auth-probe.mjs +22 -3
  75. package/src/bridge/policy.mjs +1 -1
  76. package/src/bridge/server.mjs +1 -1
  77. package/src/capabilities.mjs +3 -3
  78. package/src/credentials.mjs +24 -2
  79. package/src/history.mjs +76 -0
  80. package/src/i18n.mjs +23 -1
  81. package/src/local-ai.mjs +10 -2
  82. package/src/looks.mjs +17 -5
  83. package/src/market-license.mjs +104 -0
  84. package/src/market-remote.mjs +17 -1
  85. package/src/mcp/notes-server.mjs +120 -0
  86. package/src/mcp/proxy.mjs +14 -3
  87. package/src/models.mjs +82 -9
  88. package/src/modules/index.mjs +3 -1
  89. package/src/modules/local-models.mjs +28 -0
  90. package/src/modules/notes.mjs +142 -0
  91. package/src/modules/ollama.mjs +39 -10
  92. package/src/modules/playwright.mjs +14 -3
  93. package/src/modules/reminders.mjs +345 -0
  94. package/src/modules/sdk.mjs +21 -5
  95. package/src/mother.mjs +11 -1
  96. package/src/ollama.mjs +2 -2
  97. package/src/opencode-health.mjs +63 -0
  98. package/src/outbound.mjs +25 -1
  99. package/src/reminder-time.mjs +127 -0
  100. package/src/room.mjs +19 -7
  101. package/src/runtime-detection.mjs +6 -2
  102. package/src/sentinel-errors.mjs +4 -3
  103. package/src/server.mjs +302 -70
  104. package/src/tour.mjs +24 -5
package/src/models.mjs CHANGED
@@ -10,26 +10,32 @@ import { OPENCODE_PROVIDERS } from './credentials.mjs';
10
10
  // list) plus the aliases each vendor documents. Users can add their own in
11
11
  // ~/.pulse/config.json under "models".
12
12
 
13
+ export const CURSOR_FREE_NOTE = 'Your Cursor plan answers only with Auto: the other models need a paid plan.';
13
14
  export const KNOWN_MODELS = {
14
15
  codex: {
15
16
  defaults: ['gpt-5.6-sol', 'gpt-5.6-luna', 'gpt-5.6-terra', 'gpt-5.5'],
16
- note: 'Names from ~/.codex/models_cache.json; the CLI default comes from ~/.codex/config.toml.',
17
+ note: 'The models your plan offers in Codex. «default» is the one Codex uses on its own.',
17
18
  },
18
19
  claude: {
19
20
  defaults: ['fable', 'opus', 'sonnet', 'haiku'],
20
- note: 'Aliases resolve to the latest model of each family (e.g. fable → claude-fable-5-1). Full names also work.',
21
+ note: 'Each name is the newest model of its family that your Claude plan offers. You can also write a full model name.',
21
22
  },
23
+ // Read from Google with the Gemini key when there is one (2026-10-21); these when there is not.
24
+ // No 2.5: Google no longer gives it to new accounts, and a name that fails is worse than none.
22
25
  gemini: {
23
- defaults: ['auto', 'gemini-3-pro-preview', 'gemini-3-flash-preview', 'gemini-2.5-pro', 'gemini-2.5-flash'],
24
- note: '"auto" lets Gemini CLI route between pro and flash.',
26
+ defaults: ['auto', 'gemini-3-pro-preview', 'gemini-3-flash-preview'],
27
+ note: '«auto» lets Gemini choose between its fast model and its strongest one. The others are the ones your Gemini key opens.',
28
+ unread: 'These are the usual ones. Signed in with a Gemini API key, MADRE shows the ones your account opens.',
25
29
  },
26
30
  opencode: {
27
31
  defaults: [],
28
32
  note: 'provider/model, from `opencode models`. The room default is PULSE_OPENCODE_MODEL.',
29
33
  },
34
+ // Read from the account itself (`cursor-agent --list-models`, 2026-10-21); «auto» alone when it
35
+ // cannot be read. The four names that stood here were long gone from Cursor's list.
30
36
  cursor: {
31
- defaults: ['auto', 'sonnet-4', 'sonnet-4-thinking', 'gpt-5'],
32
- note: '"auto" lets Cursor choose. `cursor-agent --list-models` names the ones your account has; the room default is PULSE_CURSOR_MODEL.',
37
+ defaults: ['auto'],
38
+ note: '«auto» lets Cursor choose. The others are the ones your Cursor account lists; a free plan answers only with Auto.',
33
39
  },
34
40
  };
35
41
 
@@ -154,7 +160,42 @@ export function isValidModelName(name) {
154
160
 
155
161
  const unique = (list) => [...new Set(list.filter(isValidModelName))];
156
162
 
157
- export async function discoverModels({ agents = [], config = {}, home = homedir(), listOpenCode = async () => [] } = {}) {
163
+ // Google's list for a Gemini key (`GET v1beta/models`): the models that converse, by their short
164
+ // names, «auto» first — the Gemini CLI's own routing. Embedding, image, voice, live and the
165
+ // computer-use models are for other work and are left out.
166
+ const GEMINI_NOT_CHAT = /embedding|image|imagen|nano-banana|tts|audio|transcribe|live|computer-use|customtools|robotics|aqa|veo|gemma/i;
167
+ // The order a person looks for: the «latest» names, then newest first, and in each version the
168
+ // strongest first (pro, then flash, then lite).
169
+ const geminiRank = (name) => {
170
+ const version = /latest/.test(name) ? 999 : Number(name.match(/gemini-(\d+(?:\.\d+)?)/)?.[1] ?? 0);
171
+ const tier = /lite/.test(name) ? 2 : /flash/.test(name) ? 1 : 0;
172
+ return [version, tier];
173
+ };
174
+ export function parseGeminiModels(json) {
175
+ let data = json;
176
+ if (typeof json === 'string') { try { data = JSON.parse(json); } catch { return []; } }
177
+ const names = [];
178
+ for (const one of Array.isArray(data?.models) ? data.models : []) {
179
+ const name = String(one?.name ?? '').replace(/^models\//, '');
180
+ if (!/^gemini-/.test(name) || GEMINI_NOT_CHAT.test(name) || !isValidModelName(name)) continue;
181
+ if (Array.isArray(one.supportedGenerationMethods) && !one.supportedGenerationMethods.includes('generateContent')) continue;
182
+ if (!names.includes(name)) names.push(name);
183
+ }
184
+ names.sort((a, b) => { const [va, ta] = geminiRank(a); const [vb, tb] = geminiRank(b); return vb - va || ta - tb || a.localeCompare(b); });
185
+ return names.length ? ['auto', ...names] : [];
186
+ }
187
+
188
+ // `cursor-agent --list-models` prints «id - Label» a line, after a heading: the ids, «auto» first.
189
+ export function parseCursorModels(text) {
190
+ const ids = [];
191
+ for (const line of String(text ?? '').split('\n')) {
192
+ const found = line.match(/^\s*([A-Za-z0-9][\w.:[\]-]*)\s+-\s+\S/);
193
+ if (found && isValidModelName(found[1]) && !ids.includes(found[1])) ids.push(found[1]);
194
+ }
195
+ return ids.includes('auto') ? ['auto', ...ids.filter((id) => id !== 'auto')] : ids;
196
+ }
197
+
198
+ export async function discoverModels({ agents = [], config = {}, home = homedir(), listOpenCode = async () => [], listCursor = async () => [], cursorOnlyAuto = () => false, listGemini = async () => [] } = {}) {
158
199
  const result = {};
159
200
  for (const agent of agents) {
160
201
  const known = KNOWN_MODELS[agent.id] ?? { defaults: [], note: '' };
@@ -197,6 +238,11 @@ export async function discoverModels({ agents = [], config = {}, home = homedir(
197
238
  }
198
239
  }
199
240
  }
241
+ if (agent.id === 'gemini' && agent.detected) discovered = await listGemini(agent).catch(() => []);
242
+ if (agent.id === 'cursor' && agent.detected) {
243
+ // A free plan refuses every named model (adapters/cursor.mjs): then Auto is all there is.
244
+ discovered = cursorOnlyAuto() ? ['auto'] : await listCursor(agent).catch(() => []);
245
+ }
200
246
  const custom = Array.isArray(config.models?.[agent.id]) ? config.models[agent.id] : [];
201
247
  // OpenCode speaks to many providers: what `opencode models` lists is already only the ones
202
248
  // signed in plus OpenCode's own. The person may hide a provider from the chooser (AJUSTES ›
@@ -207,15 +253,20 @@ export async function discoverModels({ agents = [], config = {}, home = homedir(
207
253
  discovered = discovered.filter((name) => !hidden.has(providerOf(name)));
208
254
  groups = groupOpenCode(unique([...custom, ...discovered]));
209
255
  }
256
+ if (agent.id === 'cursor' && discovered.length > 1) groups = groupCursor(unique([...custom, ...discovered]));
210
257
  result[agent.id] = {
211
258
  ...(groups ? { groups } : {}),
212
- models: unique([...custom, ...discovered, ...known.defaults]),
259
+ // What the account itself lists, when it can be read, is the whole choice: the names written
260
+ // here are only for a CLI that cannot say (2026-10-21). Added to it, they offered models the
261
+ // plan did not have, and a turn that failed on them.
262
+ models: unique([...custom, ...(discovered.length ? discovered : known.defaults)]),
213
263
  default: cliDefault,
214
- note: known.note,
264
+ note: agent.id === 'cursor' && cursorOnlyAuto() ? CURSOR_FREE_NOTE : !discovered.length && known.unread ? known.unread : known.note,
215
265
  efforts,
216
266
  effortDefault: isValidEffort(agent.id, effortDefault) ? effortDefault : null,
217
267
  ...(effortsByModel ? { effortsByModel, effortsShared } : {}),
218
268
  source: discovered.length ? 'discovered' : 'known',
269
+ ...(agent.id === 'cursor' && cursorOnlyAuto() ? { onlyAuto: true } : {}),
219
270
  };
220
271
  }
221
272
  return result;
@@ -256,6 +307,28 @@ export function providerLabel(id) {
256
307
  return id.split(/[-_.]/).map((part) => (part ? part[0].toUpperCase() + part.slice(1) : part)).join(' ');
257
308
  }
258
309
  // Groups in a steady order: the providers with a key first, by name; OpenCode's own models last.
310
+ // Cursor lists every model of every house, each in several speeds (265 on 2026-10-21): shown under
311
+ // the house it comes from, Cursor's own first, so the chooser can be read.
312
+ const CURSOR_HOUSES = [
313
+ ['cursor', 'Cursor', /^(auto|composer|cursor-small)/],
314
+ ['openai', 'OpenAI', /^(gpt|o\d|codex)/],
315
+ ['anthropic', 'Anthropic', /^claude/],
316
+ ['google', 'Google', /^gemini/],
317
+ ['xai', 'xAI', /^(cursor-)?grok/],
318
+ ['deepseek', 'DeepSeek', /^deepseek/],
319
+ ['moonshot', 'Moonshot', /^kimi/],
320
+ ];
321
+ export function groupCursor(names = []) {
322
+ const groups = new Map();
323
+ for (const name of names) {
324
+ const [id, label] = CURSOR_HOUSES.find(([, , test]) => test.test(name)) ?? ['other', 'Other'];
325
+ if (!groups.has(id)) groups.set(id, { id, label, own: id === 'cursor', models: [] });
326
+ groups.get(id).models.push(name);
327
+ }
328
+ const order = [...CURSOR_HOUSES.map(([id]) => id), 'other'];
329
+ return [...groups.values()].sort((a, b) => order.indexOf(a.id) - order.indexOf(b.id));
330
+ }
331
+
259
332
  export function groupOpenCode(names = []) {
260
333
  const byProvider = new Map();
261
334
  for (const name of names) {
@@ -18,6 +18,8 @@ import gitPulse from './git-pulse.mjs';
18
18
  import ash from './ash.mjs';
19
19
  import intents from './intents.mjs';
20
20
  import choices from './choices.mjs';
21
+ import notes from './notes.mjs';
22
+ import reminders from './reminders.mjs';
21
23
  import runs from './runs.mjs';
22
24
  import ripley from './ripley.mjs';
23
25
  import ollama from './ollama.mjs';
@@ -36,7 +38,7 @@ import { defineModule, matchRoute } from './sdk.mjs';
36
38
  // so a module of somebody's own cannot take one and collide with it the day it comes out.
37
39
  export const LAB_MODULES = [correo];
38
40
  const labsAsked = new Set(String(process.env.PULSE_LABS ?? '').split(',').map((id) => id.trim()).filter(Boolean));
39
- export const MODULES = [ahp, imageStudio, gitPulse, ash, intents, choices, runs, ripley, ollama, playwright, github, enlaces, bishop, mcpConnect, ...LAB_MODULES.filter((module) => labsAsked.has(module.id))];
41
+ export const MODULES = [ahp, imageStudio, gitPulse, ash, intents, choices, notes, reminders, runs, ripley, ollama, playwright, github, enlaces, bishop, mcpConnect, ...LAB_MODULES.filter((module) => labsAsked.has(module.id))];
40
42
  export const BUILTIN_IDS = new Set([...MODULES, ...LAB_MODULES].map((module) => module.id));
41
43
  export const loadFailures = []; // { file, error } for MODULES to show
42
44
  export const moduleFolders = ({ stateRoot, projectRoot }) => ({ user: join(stateRoot, 'modules'), project: join(projectRoot, '.madre', 'modules') });
@@ -34,6 +34,20 @@ export const MODEL_TIERS = [
34
34
  { id: '72b', params: 72, label: 'Qwen2.5 72B', ollama: 'qwen2.5:72b', base: 'mlx-community/Qwen2.5-72B-Instruct-4bit', quantized: true, runGb: 64, trainGb: 128 },
35
35
  ];
36
36
 
37
+ // Other families a person may choose instead (2026-10-20). Qwen2.5 stays the ladder MADRE
38
+ // recommends and trains on; these run in Ollama with the same minimums and are only offered where
39
+ // they load. Their notes are said to a person, so they stay in plain words.
40
+ export const OTHER_MODELS = [
41
+ { ollama: 'llama3.2:1b', label: 'Llama 3.2 1B', maker: 'Meta', params: 1, runGb: 4, note: 'The smallest. For a computer with little memory.' },
42
+ { ollama: 'llama3.2:3b', label: 'Llama 3.2 3B', maker: 'Meta', params: 3, runGb: 8, note: 'Quick. Strongest in English.' },
43
+ { ollama: 'gemma3:4b', label: 'Gemma 3 4B', maker: 'Google', params: 4, runGb: 8, note: 'Quick, and good in many languages.' },
44
+ { ollama: 'mistral:7b', label: 'Mistral 7B', maker: 'Mistral AI', params: 7, runGb: 12, note: 'Balanced, for everyday work.' },
45
+ { ollama: 'llama3.1:8b', label: 'Llama 3.1 8B', maker: 'Meta', params: 8, runGb: 12, note: 'Balanced. Strongest in English.' },
46
+ { ollama: 'gemma3:12b', label: 'Gemma 3 12B', maker: 'Google', params: 12, runGb: 16, note: 'Careful answers in many languages.' },
47
+ { ollama: 'phi4:14b', label: 'Phi-4 14B', maker: 'Microsoft', params: 14, runGb: 20, note: 'Reasons well for its size.' },
48
+ { ollama: 'gemma3:27b', label: 'Gemma 3 27B', maker: 'Google', params: 27, runGb: 32, note: 'The largest of its family. Needs a lot of memory.' },
49
+ ];
50
+
37
51
  // What the local AI does in MADRE, and the smallest model each one is worth turning on with. Below
38
52
  // it the feature works but answers poorly enough that it is better left off.
39
53
  export const LOCAL_FEATURES = [
@@ -116,6 +130,20 @@ export function hardwareFit(hardware) {
116
130
  return { hardware, usableGb: usable, accelerated, models, recommended: { run, train, largestRun }, features };
117
131
  }
118
132
 
133
+ // Every model a person may choose, each with whether it runs on this computer and which one MADRE
134
+ // recommends here: the Qwen2.5 ladder first, then the other families, smallest first.
135
+ export function modelCatalog(fit) {
136
+ const usable = fit?.usableGb ?? 0;
137
+ const accelerated = Boolean(fit?.accelerated);
138
+ const best = fit?.recommended?.run?.ollama ?? null;
139
+ const qwen = MODEL_TIERS.map((tier) => ({ ollama: tier.ollama, label: tier.label, maker: 'Alibaba', params: tier.params, runGb: tier.runGb, note: 'Good in many languages. The family MADRE recommends and trains.' }));
140
+ return [...qwen, ...OTHER_MODELS].map((model) => ({
141
+ ...model,
142
+ run: usable >= model.runGb ? (accelerated ? 'yes' : 'slow') : 'no',
143
+ recommended: model.ollama === best,
144
+ }));
145
+ }
146
+
119
147
  let measured = null;
120
148
  // Read once per process: the hardware does not change under a running room.
121
149
  export function hardwareOnce(options) {
@@ -0,0 +1,142 @@
1
+ // SPDX-License-Identifier: AGPL-3.0-only
2
+ // MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
3
+ // Notes (0.1, 2026-10-20): colored notes on a project, each one a window of the room.
4
+ //
5
+ // A note is what a person writes for themself: no agent reads it, nothing is sent anywhere, and it
6
+ // does not go into the project's folder. They are kept beside the project's conversations, in
7
+ // ~/.pulse/rooms/<id>/notes.json, one file per project, written whole (src/json-file.mjs). The page
8
+ // draws each open note as a window of its own — the same windows every module has, moved by their
9
+ // head and sized by their edges — and remembers where it was left.
10
+
11
+ import { readFile } from 'node:fs/promises';
12
+ import { join } from 'node:path';
13
+ import { randomUUID } from 'node:crypto';
14
+ import { defineModule } from './sdk.mjs';
15
+ import { oneAtATime, writeWhole } from '../json-file.mjs';
16
+ import { fileURLToPath } from 'node:url';
17
+ import { t } from '../i18n.mjs';
18
+
19
+ export const NOTES_SERVER = fileURLToPath(new URL('../mcp/notes-server.mjs', import.meta.url));
20
+ // A message that asks for a note (2026-10-20): «/notas …», «/notes …», «hazme una nota», «take a
21
+ // note». Only then is the tool handed to the turn: a tool in every turn costs its description in
22
+ // every prompt.
23
+ export const ASKS_FOR_NOTE = /(^|\s)\/(notas?|notes?)\b|\b(nota|notas|apunta|anota|note|notes|jot)\b/i;
24
+
25
+ export const NOTE_COLORS = ['yellow', 'green', 'blue', 'pink', 'purple', 'orange'];
26
+ export const NOTES_MAX = 200;
27
+ export const NOTE_TEXT_MAX = 20000;
28
+ const ID = /^[a-z0-9-]{6,64}$/i;
29
+ const notesFile = (roomDir) => join(roomDir, 'notes.json');
30
+ const number = (value, low, high) => (Number.isFinite(Number(value)) ? Math.round(Math.min(high, Math.max(low, Number(value)))) : null);
31
+
32
+ // Where a note was left on the page, as numbers that can be trusted, or nothing.
33
+ function boxOf(raw) {
34
+ if (!raw || typeof raw !== 'object') return null;
35
+ const box = { x: number(raw.x, -4000, 8000), y: number(raw.y, 0, 8000), w: number(raw.w, 160, 4000), h: number(raw.h, 120, 4000) };
36
+ return Object.values(box).every((value) => value !== null) ? box : null;
37
+ }
38
+ // One note read field by field: a file written by hand is read for what it says correctly.
39
+ function noteOf(raw) {
40
+ if (!raw || typeof raw !== 'object' || !ID.test(String(raw.id ?? ''))) return null;
41
+ const iso = (value) => (typeof value === 'string' && !Number.isNaN(Date.parse(value)) ? value : null);
42
+ return {
43
+ id: raw.id,
44
+ text: String(raw.text ?? '').slice(0, NOTE_TEXT_MAX),
45
+ color: NOTE_COLORS.includes(raw.color) ? raw.color : NOTE_COLORS[0],
46
+ open: raw.open !== false,
47
+ box: boxOf(raw.box),
48
+ at: iso(raw.at) ?? new Date(0).toISOString(),
49
+ };
50
+ }
51
+
52
+ export async function readNotes(roomDir) {
53
+ if (!roomDir) return [];
54
+ const raw = await readFile(notesFile(roomDir), 'utf8').then((text) => JSON.parse(text)).catch(() => null);
55
+ return (Array.isArray(raw?.notes) ? raw.notes : []).map(noteOf).filter(Boolean).slice(0, NOTES_MAX);
56
+ }
57
+ const writeNotes = (roomDir, notes) => writeWhole(notesFile(roomDir), `${JSON.stringify({ notes }, null, 2)}\n`);
58
+
59
+ // A new note, or a change to one: only what the change names moves.
60
+ export function saveNote(roomDir, change, now = new Date()) {
61
+ return oneAtATime(notesFile(roomDir), async () => {
62
+ const notes = await readNotes(roomDir);
63
+ const at = new Date(now).toISOString();
64
+ let note = change?.id ? notes.find((one) => one.id === change.id) : null;
65
+ if (change?.id && !note) return { error: 'unknown' };
66
+ if (!note) {
67
+ if (notes.length >= NOTES_MAX) return { error: 'full' };
68
+ note = { id: randomUUID(), text: '', color: NOTE_COLORS.includes(change?.color) ? change.color : NOTE_COLORS[0], open: true, box: null, at };
69
+ notes.push(note);
70
+ }
71
+ if (typeof change?.text === 'string') note.text = change.text.slice(0, NOTE_TEXT_MAX);
72
+ if (NOTE_COLORS.includes(change?.color)) note.color = change.color;
73
+ if (typeof change?.open === 'boolean') note.open = change.open;
74
+ if (change?.box !== undefined) note.box = boxOf(change.box);
75
+ note.at = at;
76
+ await writeNotes(roomDir, notes);
77
+ return { note };
78
+ });
79
+ }
80
+
81
+ export function deleteNote(roomDir, id) {
82
+ return oneAtATime(notesFile(roomDir), async () => {
83
+ const notes = await readNotes(roomDir);
84
+ const kept = notes.filter((one) => one.id !== id);
85
+ if (kept.length === notes.length) return { error: 'unknown' };
86
+ await writeNotes(roomDir, kept);
87
+ return { deleted: id };
88
+ });
89
+ }
90
+
91
+ const reply = (status, body) => ({ status, body });
92
+ const on = (ctx) => Boolean(notes.settingsFrom(ctx.config, ctx.roomId).enabled);
93
+ const door = (ctx) => (on(ctx) ? null : reply(412, { error: t('Notes is off in this project. Turn it on in Modules.') }));
94
+
95
+ const notes = defineModule({
96
+ id: 'notes',
97
+ name: 'Notes',
98
+ vendor: 'MADRE',
99
+ version: '0.1.0',
100
+ summary: 'Colored notes on the project, each in a window you move and size as you like. Only you read them: no agent sees them and nothing leaves your computer.',
101
+ creates: ['nothing in the project', 'a notes.json file beside the project’s conversations, in ~/.pulse'],
102
+ settings: { enabled: false },
103
+ async status(ctx) {
104
+ const list = await readNotes(ctx.roomDir);
105
+ const enabled = Boolean(ctx.settings.enabled);
106
+ return {
107
+ status: { installed: enabled, detail: enabled ? t('{n} notes in this project', { n: list.length }) : t('off') },
108
+ install: { display: enabled ? 'turn off Notes' : 'turn on Notes', platforms: [] },
109
+ notes: list.length,
110
+ };
111
+ },
112
+ // An agent makes a note when the person asks for one (src/mcp/notes-server.mjs): it can only add.
113
+ async toolsForTurn(ctx, turn) {
114
+ if (!ctx.roomDir || (turn?.text !== undefined && !ASKS_FOR_NOTE.test(turn.text))) return [];
115
+ return [{
116
+ name: 'madre-notes',
117
+ command: process.execPath,
118
+ args: [NOTES_SERVER],
119
+ env: { PULSE_NOTES_DIR: ctx.roomDir },
120
+ tools: ['create_note'],
121
+ brief: 'When the person asks for a note (they may write /notas or /notes), make it with the create_note tool of server madre-notes: short, clear, in their language. It opens on their screen as a colored note. You cannot read their other notes.',
122
+ }];
123
+ },
124
+ routes: [
125
+ { method: 'GET', path: '/api/notes', handler: async (ctx) => door(ctx) ?? reply(200, { notes: await readNotes(ctx.roomDir), colors: NOTE_COLORS }) },
126
+ { method: 'POST', path: '/api/notes', handler: async (ctx, { payload }) => {
127
+ const closed = door(ctx);
128
+ if (closed) return closed;
129
+ const saved = await saveNote(ctx.roomDir, payload ?? {});
130
+ if (saved.error === 'unknown') return reply(404, { error: t('That note is no longer here.') });
131
+ if (saved.error === 'full') return reply(409, { error: t('This project already has {n} notes. Delete one to make room.', { n: NOTES_MAX }) });
132
+ return reply(200, saved);
133
+ } },
134
+ { method: 'POST', path: '/api/notes/delete', handler: async (ctx, { payload }) => {
135
+ const closed = door(ctx);
136
+ if (closed) return closed;
137
+ const gone = await deleteNote(ctx.roomDir, String(payload?.id ?? ''));
138
+ return gone.error ? reply(404, { error: t('That note is no longer here.') }) : reply(200, gone);
139
+ } },
140
+ ],
141
+ });
142
+ export default notes;
@@ -3,44 +3,71 @@
3
3
  // OLLAMA: local intelligence. Embeddings and distillation on this machine when
4
4
  // Ollama runs. The server offers the wiring through ctx.services.ollama.
5
5
 
6
+ import { execFile } from 'node:child_process';
6
7
  import { defineModule } from './sdk.mjs';
7
8
  import { t } from '../i18n.mjs';
8
9
  import { findOnPath } from './helpers.mjs';
9
10
  import { RECOMMENDED } from '../ollama.mjs';
10
- import { hardwareOnce } from './local-models.mjs';
11
+ import { hardwareOnce, modelCatalog } from './local-models.mjs';
11
12
 
12
13
  // The chat model to pull is the one this computer runs well (local-models.mjs), not one size for
13
14
  // every machine; the embedding model is small enough for all of them. With the hardware, the page
14
15
  // says which sizes run here and which features of the local AI are worth turning on.
15
16
  export async function recommendedHere() {
16
17
  const fit = await hardwareOnce();
17
- return { ...RECOMMENDED, chat: fit.recommended.run?.ollama ?? RECOMMENDED.chat, hardware: fit };
18
+ return { ...RECOMMENDED, chat: fit.recommended.run?.ollama ?? RECOMMENDED.chat, hardware: fit, catalog: modelCatalog(fit) };
19
+ }
20
+
21
+ // On Linux the official script writes /usr/local and a systemd service, and when it is not root it
22
+ // asks sudo for both. MADRE runs it with no terminal, where sudo cannot ask for a password: it fails
23
+ // for a user who needs one and always for one who is not an administrator. So it runs here only as
24
+ // root or with sudo that needs no password; otherwise the command is handed over for a terminal.
25
+ // (Installing without root into ~/.local from Ollama's archive was weighed and left out: the archive
26
+ // changes format and size with each release, needs the GPU libraries beside it and a PATH the
27
+ // running MADRE does not see, and gives no service. One person keeps this; the script keeps itself.)
28
+ const LINUX_SCRIPT = 'curl -fsSL https://ollama.com/install.sh | sh';
29
+ const NEEDS_PASSWORD = "Ollama's install script needs the administrator password, and MADRE cannot ask for it. Run the command in a terminal, then press RECHECK.";
30
+
31
+ // `sudo -n true` answers at once: 0 when no password is needed, an error when one is (or when this
32
+ // user cannot use sudo at all). Asked once per run of MADRE; never with a terminal attached.
33
+ let sudoOnce = null;
34
+ export const sudoWithoutPassword = () => (sudoOnce ??= new Promise((resolve) => {
35
+ execFile('sudo', ['-n', 'true'], { timeout: 5000 }, (error) => resolve(!error));
36
+ }));
37
+
38
+ // Whether the Linux script can run from here. Elsewhere the question does not arise.
39
+ export async function adminHere({ platform = process.platform, uid = process.getuid?.() ?? null, sudo = sudoWithoutPassword } = {}) {
40
+ if (platform !== 'linux') return true;
41
+ if (uid === 0) return true;
42
+ return Boolean(await sudo());
18
43
  }
19
44
 
20
45
  // Ollama is not an npm package, so each system has its own way in. Where MADRE can run it, the
21
46
  // command is shown on the button before it runs; where it cannot, it hands over the download.
22
- export function ollamaInstallPlan({ platform = process.platform, brew = null } = {}) {
47
+ export function ollamaInstallPlan({ platform = process.platform, brew = null, admin = true } = {}) {
23
48
  if (platform === 'darwin') {
24
49
  return brew
25
50
  ? { command: brew, args: ['install', 'ollama'], display: 'brew install ollama', note: 'Installs Ollama with Homebrew, the package manager already on this computer.' }
26
51
  : { 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.' };
27
52
  }
28
53
  if (platform === 'linux') {
29
- 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." };
54
+ if (!admin) return { command: null, manual: true, display: LINUX_SCRIPT, note: t(NEEDS_PASSWORD) };
55
+ return { command: 'sh', args: ['-c', LINUX_SCRIPT], display: LINUX_SCRIPT, note: "Ollama's own install script, downloaded from ollama.com and run on this computer." };
30
56
  }
31
57
  return { command: null, download: 'https://ollama.com/download', display: null, note: 'Download the Ollama installer from ollama.com, run it, and press RECHECK.' };
32
58
  }
33
59
 
34
60
  // A newer Ollama. Where MADRE can do it, the command is shown before it runs; where it cannot,
35
61
  // it hands over the download rather than pretending.
36
- export function ollamaUpdatePlan({ platform = process.platform, brew = null } = {}) {
62
+ export function ollamaUpdatePlan({ platform = process.platform, brew = null, admin = true } = {}) {
37
63
  if (platform === 'darwin') {
38
64
  return brew
39
65
  ? { command: brew, args: ['upgrade', 'ollama'], display: 'brew upgrade ollama', note: 'Upgrades Ollama with Homebrew. Your models stay where they are.' }
40
66
  : { 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.' };
41
67
  }
42
68
  if (platform === 'linux') {
43
- 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." };
69
+ if (!admin) return { command: null, manual: true, display: LINUX_SCRIPT, note: `${t(NEEDS_PASSWORD)} ${t('Your models stay where they are.')}` };
70
+ return { command: 'sh', args: ['-c', LINUX_SCRIPT], display: LINUX_SCRIPT, note: "Ollama's own install script upgrades in place. Your models stay where they are." };
44
71
  }
45
72
  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.' };
46
73
  }
@@ -52,7 +79,9 @@ export const ollamaStartPlan = () => ({ command: 'ollama', args: ['serve'], disp
52
79
  // computer, and the one step that moves it forward. The card and the routes share this.
53
80
  export async function ollamaView(probe, settings) {
54
81
  const binary = await findOnPath('ollama');
55
- return { ...probe, settings, binary, install: ollamaInstallPlan({ brew: await findOnPath('brew') }), start: ollamaStartPlan() };
82
+ // The sudo question is only worth asking while there is something to install.
83
+ const admin = binary ? true : await adminHere();
84
+ return { ...probe, settings, binary, install: ollamaInstallPlan({ brew: await findOnPath('brew'), admin }), start: ollamaStartPlan() };
56
85
  }
57
86
 
58
87
  export default defineModule({
@@ -83,13 +112,13 @@ export default defineModule({
83
112
  status: { installed: settings.enabled && project.on && probe.running && roles.length > 0, detail },
84
113
  ollama: { ...view, project },
85
114
  recommended: await recommendedHere(),
86
- preflight: probe.running ? { ok: true, problems: [] } : { ok: false, problems: ['Ollama is not running: open the Ollama app or run `ollama serve`, then RECHECK.'] },
115
+ preflight: probe.running ? { ok: true, problems: [] } : { ok: false, problems: ['Ollama is not running: open the Ollama app or run `ollama serve`, then check again.'] },
87
116
  install: { display: settings.enabled ? 'disable Ollama' : 'enable Ollama (config.json)', platforms: [] },
88
117
  };
89
118
  },
90
119
  async updatePlan(ctx) {
91
120
  const { findOnPath } = await import('./helpers.mjs');
92
- const plan = ollamaUpdatePlan({ brew: await findOnPath('brew') });
121
+ const plan = ollamaUpdatePlan({ brew: await findOnPath('brew'), admin: await adminHere() });
93
122
  if (!plan.command) return plan;
94
123
  // Upgrading replaces the binary, not the server already running: until it restarts, the old
95
124
  // version keeps answering. Said before the button is pressed, done after the command.
@@ -122,7 +151,7 @@ export default defineModule({
122
151
  } },
123
152
  { method: 'POST', path: '/api/ollama/install', handler: async (ctx) => {
124
153
  const started = await ctx.services.ollama.install();
125
- return started.ok ? { status: 202, body: { installing: true, command: started.command } } : { status: started.download ? 412 : 409, body: { error: started.error, download: started.download ?? null } };
154
+ return started.ok ? { status: 202, body: { installing: true, command: started.command } } : { status: started.download || started.manual ? 412 : 409, body: { error: started.error, download: started.download ?? null, manual: started.manual ?? null } };
126
155
  } },
127
156
  { method: 'POST', path: '/api/ollama/start', handler: async (ctx) => {
128
157
  const started = await ctx.services.ollama.start();
@@ -219,7 +219,16 @@ export default defineModule({
219
219
  card: 'switch',
220
220
  controls: [
221
221
  { key: 'browser', label: 'BROWSER', type: 'select', options: PLAYWRIGHT_BROWSERS, note: 'Which browser engine the agents drive.' },
222
- { 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.' },
222
+ // Nothing opens the moment it is switched on: the window comes with the next agent that opens
223
+ // the page, and the person is told so, and how to try it (2026-10-20).
224
+ {
225
+ key: 'headless', label: 'SHOW THE WINDOW', type: 'switch', invert: true,
226
+ note: 'Off, the browser works without a window. On, the next time an agent opens your page, you see its window on this screen.',
227
+ said: {
228
+ on: 'Done. The next time an agent opens your page, its window opens on this screen. To try it, ask: «open the page and tell me what you see».',
229
+ off: 'Done. The browser works without a window again.',
230
+ },
231
+ },
223
232
  ],
224
233
  async status(ctx) {
225
234
  const version = await playwrightVersion({ env: ctx.env, projectRoot: ctx.projectRoot });
@@ -227,8 +236,10 @@ export default defineModule({
227
236
  return {
228
237
  runs: [{ name: PLAYWRIGHT_PACKAGE, version }],
229
238
  settings: { browser: ctx.settings.browser ?? 'chromium', headless: ctx.settings.headless !== false },
230
- status: { installed: Boolean(ctx.settings.enabled), detail: ctx.settings.enabled ? (!version ? t('on · the browser server is not installed') : health?.ok === false ? t('on · the browser does not start: {problem}. Turn it off and on again: MADRE downloads what is missing.', { problem: String(health.problem).replace(/[.\s]+$/, '').slice(0, 160) }) : `${t('on')} · ${ctx.settings.browser}`) : version ? t('off') : t('off · the browser server is not installed') },
231
- preflight: version ? { ok: true, problems: [] } : { ok: false, problems: [`Install the browser server first: npm install -g @playwright/mcp, then its browser: ${installBrowserLine(ctx.settings.browser)}`] },
239
+ status: { installed: Boolean(ctx.settings.enabled), detail: ctx.settings.enabled ? (!version ? t('on · the browser server is not installed') : health?.ok === false ? t('on · the browser does not start: {problem}. Turn it off and on again: MADRE downloads what is missing.', { problem: String(health.problem).replace(/[.\s]+$/, '').slice(0, 160) }) : `${t('on')} · ${ctx.settings.browser}`) : version ? t('off') : process.platform === 'win32' ? t('off · the browser server is not installed') : t('off · turn it on and MADRE installs its browser; it takes a few minutes') },
240
+ // Missing is not a reason to refuse the switch: turning it on installs what is missing
241
+ // (playwrightReady) everywhere but Windows (2026-10-20). Only there does the person install it.
242
+ preflight: version || process.platform !== 'win32' ? { ok: true, problems: [] } : { ok: false, problems: [t('Install the browser server first: {server}, then its browser: {browser}', { server: 'npm install -g @playwright/mcp', browser: installBrowserLine(ctx.settings.browser) })] },
232
243
  install: { display: ctx.settings.enabled ? 'disable PLAYWRIGHT' : 'enable PLAYWRIGHT (config.json)', platforms: ['codex', 'claude', 'gemini', 'opencode'] },
233
244
  };
234
245
  },