@jossuealcala/madre 1.1.2 → 1.1.3

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 (101) hide show
  1. package/CHANGELOG.en.md +21 -1
  2. package/CHANGELOG.md +21 -1
  3. package/README.en.md +3 -3
  4. package/README.md +3 -3
  5. package/SECURITY.md +11 -6
  6. package/bin/madre.mjs +74 -11
  7. package/docs/REFERENCE.md +13 -7
  8. package/docs/SDK.md +8 -8
  9. package/docs/en/REFERENCE.md +10 -6
  10. package/docs/en/SDK.md +8 -8
  11. package/docs/en/training/README.md +1 -1
  12. package/docs/sdk/connector-module.mjs +1 -1
  13. package/docs/sdk/hello-module.mjs +1 -1
  14. package/docs/training/README.md +1 -1
  15. package/docs/training/train.sh +3 -0
  16. package/package.json +4 -2
  17. package/public/activity.js +9 -0
  18. package/public/app.js +988 -171
  19. package/public/attribution.js +9 -0
  20. package/public/brands.js +27 -13
  21. package/public/en.js +1 -2
  22. package/public/es.js +834 -257
  23. package/public/index.html +3 -0
  24. package/public/macroverso.js +24 -5
  25. package/public/manual-content.js +32 -2
  26. package/public/market-view.js +116 -9
  27. package/public/market.js +15 -0
  28. package/public/news-scenes.js +185 -0
  29. package/public/notices.js +66 -0
  30. package/public/power.js +1 -1
  31. package/public/resay.js +3 -0
  32. package/public/salas-mac.css +229 -26
  33. package/public/salas-mac.html +3 -0
  34. package/public/salas-mac.js +454 -37
  35. package/public/styles.css +393 -17
  36. package/public/tips.js +124 -0
  37. package/public/tour-chapters.js +75 -75
  38. package/public/tour.js +36 -8
  39. package/public/troubleshooting.js +215 -22
  40. package/public/welcome-scene.js +358 -0
  41. package/public/welcome.js +514 -273
  42. package/src/adapters/gemini-rest.mjs +236 -0
  43. package/src/adapters/gemini.mjs +9 -7
  44. package/src/adapters/grok.mjs +288 -0
  45. package/src/adapters/process.mjs +14 -3
  46. package/src/auth-probe.mjs +32 -0
  47. package/src/bridge/policy.mjs +1 -1
  48. package/src/capabilities.mjs +30 -0
  49. package/src/checkpoint.mjs +115 -1
  50. package/src/codex-route.mjs +113 -0
  51. package/src/credentials.mjs +46 -8
  52. package/src/dataset.mjs +18 -7
  53. package/src/event-store.mjs +10 -2
  54. package/src/ficha.mjs +142 -0
  55. package/src/files.mjs +36 -2
  56. package/src/lease.mjs +5 -0
  57. package/src/market-check.mjs +1 -1
  58. package/src/market-remote.mjs +135 -1
  59. package/src/mcp/image-server.mjs +1 -1
  60. package/src/mcp/memory-server.mjs +10 -0
  61. package/src/memory-tools.mjs +3 -0
  62. package/src/memory.mjs +29 -4
  63. package/src/models.mjs +21 -3
  64. package/src/modules/ahp.mjs +8 -3
  65. package/src/modules/bishop-exam.mjs +41 -12
  66. package/src/modules/bishop.mjs +2 -2
  67. package/src/modules/choices.mjs +12 -10
  68. package/src/modules/fetch-alone.mjs +7 -0
  69. package/src/modules/helpers.mjs +23 -5
  70. package/src/modules/image-studio.mjs +13 -27
  71. package/src/modules/index.mjs +54 -11
  72. package/src/modules/isolated.mjs +160 -0
  73. package/src/modules/ollama.mjs +35 -6
  74. package/src/modules/playwright.mjs +46 -17
  75. package/src/modules/run-alone.mjs +122 -0
  76. package/src/modules/runs.mjs +11 -8
  77. package/src/modules/sdk.mjs +4 -2
  78. package/src/notices-key.mjs +8 -0
  79. package/src/notices.mjs +185 -0
  80. package/src/ollama.mjs +57 -15
  81. package/src/outbound.mjs +45 -8
  82. package/src/room/archivist.mjs +30 -5
  83. package/src/room/busy.mjs +16 -0
  84. package/src/room/control.mjs +36 -6
  85. package/src/room/guard.mjs +32 -2
  86. package/src/room/prompt.mjs +32 -5
  87. package/src/room/vectors.mjs +7 -1
  88. package/src/room.mjs +94 -28
  89. package/src/router.mjs +1 -1
  90. package/src/runs.mjs +39 -0
  91. package/src/runtime-detection.mjs +46 -6
  92. package/src/salas.mjs +151 -15
  93. package/src/server.mjs +577 -80
  94. package/src/service.mjs +116 -0
  95. package/src/setup-trouble.mjs +20 -1
  96. package/src/skill-check.mjs +269 -0
  97. package/src/skills-import.mjs +128 -0
  98. package/src/skills.mjs +492 -0
  99. package/src/tour.mjs +14 -3
  100. package/src/whats-new.mjs +48 -0
  101. package/src/rumbo.mjs +0 -337
package/src/room.mjs CHANGED
@@ -1,12 +1,15 @@
1
1
  // SPDX-License-Identifier: BUSL-1.1
2
2
  // MADRE · © 2026 Jossue Alcalá · Business Source License 1.1: LICENSE
3
3
  import { invokeCodex, buildCodexArgs } from './adapters/codex.mjs';
4
+ import { codexRoute } from './codex-route.mjs';
4
5
  import { t } from './i18n.mjs';
5
6
  import { invokeClaude, buildClaudeArgs } from './adapters/claude.mjs';
6
7
  import { keptSubagents } from './adapters/subagents.mjs';
7
8
  import { invokeGemini, buildGeminiArgs } from './adapters/gemini.mjs';
9
+ import { invokeGeminiRest } from './adapters/gemini-rest.mjs';
8
10
  import { invokeOpenCode, buildOpenCodeArgs } from './adapters/opencode.mjs';
9
11
  import { invokeCursor, buildCursorArgs } from './adapters/cursor.mjs';
12
+ import { invokeGrok, buildGrokArgs } from './adapters/grok.mjs';
10
13
  import { parseMessage } from './router.mjs';
11
14
  import { randomUUID } from 'node:crypto';
12
15
  import { basename } from 'node:path';
@@ -15,7 +18,7 @@ import { UsageSentinel } from './usage-sentinel.mjs';
15
18
  import { BLOCK_SOURCES, buildPrompt, promptParts, sparedChars, wantsModule } from './room/prompt.mjs';
16
19
  import { turnCost, observedRate } from './room/economy.mjs';
17
20
  import { contextFor } from './room/context.mjs';
18
- import { VERDICTS, travels } from './memory.mjs';
21
+ import { VERDICTS, travels, unsourced } from './memory.mjs';
19
22
  import { coldNotes, coldReading } from './cold.mjs';
20
23
  import { questionsFor } from './asking.mjs';
21
24
  import { coverageExam, consistencyExam, matchExam, exchanges, MATCH_SAMPLE, saysFor } from './exam.mjs';
@@ -27,7 +30,8 @@ import { GhostLedger } from './room/ghost.mjs';
27
30
  import { Escalation } from './room/escalation.mjs';
28
31
  import { Budget, budgetTokens } from './room/budget.mjs';
29
32
  import { VectorWorker } from './room/vectors.mjs';
30
- import { Archivist, distillDefaults } from './room/archivist.mjs';
33
+ import { Archivist, distillDefaults, LOCAL_DISTILL_MS } from './room/archivist.mjs';
34
+ import { machineBusy } from './room/busy.mjs';
31
35
  import { OLLAMA_ARCHIVIST } from './distiller.mjs';
32
36
  import { memoryServerForTurn } from './memory-tools.mjs';
33
37
  import { CODE000_STRIKES } from './mother.mjs';
@@ -41,14 +45,15 @@ import { stat as statFile, readdir, copyFile, mkdir as mkdirPath, readFile as re
41
45
  import { basename as baseName, join as joinPath } from 'node:path';
42
46
  import { declaredTypeFor, filesChangedSince } from './files.mjs';
43
47
  import { isModuleFile, sdkPaths } from './modules/index.mjs';
48
+ import { isSkillFile, skillGuide, skillIdOf } from './skills.mjs';
44
49
  import { validateAshReply } from './modules/ash-policy.mjs';
45
50
  import { PHONE_MAX_MODE } from './bridge/policy.mjs';
46
51
  import { parseChoice, withoutChoice } from './choices.mjs';
47
- import { parseRunRequest, withoutRunRequest, whyText, expandHome } from './runs.mjs';
52
+ import { parseRunRequest, withoutRunRequest, whyText, expandHome, attachCommandScripts } from './runs.mjs';
48
53
  import { runSettlement, returnedBlock } from './room/returns.mjs';
49
54
  import { copilotSafe, copilotBrief, COPILOT_MAX_ROUNDS } from './room/copilot.mjs';
50
55
  import { imageStudioFor } from './image-studio.mjs';
51
- import { CAPABILITIES, imageModuleState } from './capabilities.mjs';
56
+ import { CAPABILITIES, capabilityOf, imageModuleState } from './capabilities.mjs';
52
57
  import { resolveReferences } from './files.mjs';
53
58
 
54
59
  const VIA_KINDS = new Set(['iphone', 'ipad', 'android', 'android-tablet', 'other']);
@@ -62,12 +67,17 @@ export function failureMessage(error, maxLength = 500) {
62
67
  return line.length > maxLength ? `${line.slice(0, maxLength - 1)}…` : line;
63
68
  }
64
69
 
65
- const defaultInvokers = {
70
+ export const defaultInvokers = {
66
71
  'codex-readonly': invokeCodex,
67
72
  'claude-readonly': invokeClaude,
68
73
  'gemini-readonly': invokeGemini,
69
74
  'opencode-readonly': invokeOpenCode,
70
75
  'cursor-readonly': invokeCursor,
76
+ // Grok (adapters/grok.mjs): the message, the model, the effort and the turn's lease, nothing else.
77
+ 'grok-readonly': ({ executable, projectRoot, prompt, timeoutMs, signal, model, effort, lease, scopes, onProgress }) => invokeGrok({ executable, projectRoot, prompt, timeoutMs, signal, model, effort, lease, scopes, onProgress }),
78
+ // Gemini with a key and no CLI (runtime-detection.mjs): only what an API call can take. The
79
+ // project, attachments, a lease and tool servers are the CLI's; capabilities.mjs keeps it at #1.
80
+ 'gemini-rest': ({ prompt, model, signal, timeoutMs, onProgress, json }) => invokeGeminiRest({ prompt, model, signal, timeoutMs, onProgress, json }),
71
81
  };
72
82
 
73
83
  // What a turn costs against MADRE's local budget. Cache reads are close to
@@ -133,6 +143,7 @@ export class Room {
133
143
  #examProgress = null;
134
144
  #examStop = false;
135
145
  #archivist; // room/archivist: who distils, when, and the bench
146
+ #sessions = {}; // what the server last learned of each agent's session (sessions.updated)
136
147
  #vectors; // room/vectors: embeddings filled in the background
137
148
  #escalation; // room/escalation: plan steps waiting for the human
138
149
  #ghost = new GhostLedger();
@@ -165,6 +176,7 @@ export class Room {
165
176
  #delegation;
166
177
  #privacy = null;
167
178
  #toolsForTurn = null;
179
+ #skillsForTurn = null;
168
180
  #bishopForTurn = null;
169
181
  #linkedForTurn = null;
170
182
  // The turns running now, by the id of the answer they will write: which agent, at which mode.
@@ -193,6 +205,7 @@ export class Room {
193
205
  mother = null,
194
206
  privacy = null,
195
207
  toolsForTurn = null, // async ({ agent, mode, lease, scratchDir }) => MCP server specs from the modules
208
+ skillsForTurn = null, // async ({ agent, mode, text }) => the project's skills this turn carries (src/skills.mjs)
196
209
  bishopForTurn = null, // async ({ agent, mode, text, preview, turn }) => bounded BISHOP context in Salas
197
210
  linkedForTurn = null, // async ({ agent, mode, text, preview, turn }) => { text, dynamic } notes a link recalls (3e)
198
211
  copilot = null, // () => { until } while the human's copilot window is open (src/room/copilot.mjs)
@@ -226,6 +239,7 @@ export class Room {
226
239
  this.#mother = mother;
227
240
  this.#privacy = privacy;
228
241
  this.#toolsForTurn = toolsForTurn;
242
+ this.#skillsForTurn = skillsForTurn;
229
243
  this.#bishopForTurn = bishopForTurn;
230
244
  this.#linkedForTurn = linkedForTurn;
231
245
  this.#invokers = invokers;
@@ -242,7 +256,7 @@ export class Room {
242
256
  this.#budget.seed(historicalEvents, this.#sentinel);
243
257
  // What this room has been charged per character, from its own past turns.
244
258
  this.#rate = observedRate(historicalEvents);
245
- this.#vectors = new VectorWorker({ memory, stopped: () => this.#shuttingDown });
259
+ this.#vectors = new VectorWorker({ memory, stopped: () => this.#shuttingDown, busy: () => machineBusy() });
246
260
  this.#archivist = new Archivist({
247
261
  memory,
248
262
  settings: distillDefaults(distill),
@@ -252,12 +266,15 @@ export class Room {
252
266
  busyAgents: () => new Set([...this.#turns.values()].map((turn) => turn.agent).filter(Boolean)),
253
267
  turnsInFlight: () => this.#turns.size,
254
268
  timeoutFor: (id) => this.timeoutFor(id),
255
- localTimeoutMs: () => this.#agentTimeouts.ollama ?? 300000,
269
+ localTimeoutMs: () => this.#agentTimeouts.ollama ?? LOCAL_DISTILL_MS,
256
270
  projectName: () => basename(this.#projectRoot),
257
271
  projectRoot: () => this.#projectRoot,
258
272
  emit: (type, payload) => this.#emit(type, payload),
259
273
  recordUsage: (agent, usage) => this.#recordUsage(agent, usage),
260
274
  stopped: () => this.#shuttingDown,
275
+ // Who MADRE already knows cannot answer: no session, or not installed (L-9).
276
+ machineBusy: () => machineBusy(),
277
+ noSession: () => new Set(Object.entries(this.#sessions).filter(([, one]) => ['signed-out', 'not-installed'].includes(one?.state)).map(([id]) => id)),
261
278
  failureMessage,
262
279
  },
263
280
  });
@@ -357,6 +374,8 @@ export class Room {
357
374
  // agents have a session, once the probe that runs at start comes back (QA 1.1.0, NUE-11).
358
375
  announce(type, payload) {
359
376
  if (!['sessions.updated'].includes(type)) throw new Error(`Not a live announcement: ${type}`);
377
+ // The archivist reads it too: it does not hand a summary to an agent with no session (L-9).
378
+ if (type === 'sessions.updated' && payload?.sessions && typeof payload.sessions === 'object') this.#sessions = { ...payload.sessions };
360
379
  return this.#say(type, payload);
361
380
  }
362
381
 
@@ -577,13 +596,13 @@ export class Room {
577
596
  progress: this.#examProgress,
578
597
  last,
579
598
  can: {
580
- coverage: { ok: Boolean(this.#memory) && cases.length > 0, why: !this.#memory ? 'the room has no memory' : cases.length ? null : 'no exchange here is long enough to test with yet', method: embedder ? 'meaning' : 'words' },
581
- consistency: { ok: Boolean(this.#memory), why: this.#memory ? null : 'the room has no memory' },
599
+ coverage: { ok: Boolean(this.#memory) && cases.length > 0, why: !this.#memory ? t('the room has no memory') : cases.length ? null : t('no exchange here is long enough to test with yet'), method: embedder ? 'meaning' : 'words' },
600
+ consistency: { ok: Boolean(this.#memory), why: this.#memory ? null : t('the room has no memory') },
582
601
  match: {
583
602
  ok: Boolean(this.#memory) && localModel && Boolean(embedder) && cases.some((one) => !one.local),
584
- why: !localModel ? 'the local model is not running: open MODULES → OLLAMA'
585
- : !embedder ? 'this test needs embeddings, which are off'
586
- : cases.some((one) => !one.local) ? null : 'nothing here was answered by an agent other than the local one',
603
+ why: !localModel ? t('the local model is not running: open MODULES → OLLAMA')
604
+ : !embedder ? t('this test needs embeddings, which are off')
605
+ : cases.some((one) => !one.local) ? null : t('nothing here was answered by an agent other than the local one'),
587
606
  sample: Math.min(MATCH_SAMPLE, cases.filter((one) => !one.local).length),
588
607
  },
589
608
  },
@@ -843,6 +862,7 @@ export class Room {
843
862
  if (agentId === 'codex') return (await readCodexEfforts({ home: this.#codexHome }).catch(() => null))?.model ?? null;
844
863
  if (agentId === 'opencode') return process.env.PULSE_OPENCODE_MODEL || null;
845
864
  if (agentId === 'cursor') return process.env.PULSE_CURSOR_MODEL || null;
865
+ if (agentId === 'grok') return process.env.PULSE_GROK_MODEL || null;
846
866
  return null;
847
867
  }
848
868
 
@@ -1034,7 +1054,8 @@ export class Room {
1034
1054
  const said = settlement.done
1035
1055
  ? n === 1 ? t('The command you asked for ran. Go on with what you proposed.') : t('The {n} commands you asked for ran. Go on with what you proposed.', { n })
1036
1056
  : t('{n} of the {total} commands you asked for ran. Go on with what you proposed.', { n, total });
1037
- const text = `↩ @${agentId}${reply?.sequence ? ` #${reply.sequence}` : ''}: “${quoted.length > 120 ? `${quoted.slice(0, 119)}…` : quoted}”\n${said}`;
1057
+ // No message number: beside the modes #0–#4 it read as one (Q-14).
1058
+ const text = `↩ @${agentId}: “${quoted.length > 120 ? `${quoted.slice(0, 119)}…` : quoted}”\n${said}`;
1038
1059
  const returned = returnedBlock({ settlement, asking: asked?.text ?? null, said: reply?.payload?.text ?? null, replySequence: reply?.sequence ?? null });
1039
1060
  await this.#accept({
1040
1061
  text, target: agentId, mode,
@@ -1472,7 +1493,9 @@ export class Room {
1472
1493
  // Results waiting to go back stay with the human: STOP ALL means nothing starts by itself.
1473
1494
  for (const id of [...this.#returns.keys(), ...this.#returning.keys()]) this.#dropped.add(id);
1474
1495
  this.#returns.clear();
1475
- for (const turn of this.#turns.values()) turn.controller.abort(reason);
1496
+ // Marked as stopTurn marks its one turn: a turn the human braked is not a failure to diagnose,
1497
+ // and every turn STOP ALL cut reached the diagnostics as one (D-7, 2026-11-03).
1498
+ for (const turn of this.#turns.values()) { turn.stoppedByHuman = true; turn.controller.abort(reason); }
1476
1499
  this.#runDesk.stop('STOPALL');
1477
1500
  await this.#emit('room.stopped', { reason, plans, turns, agents: [...new Set([...this.#turns.values()].map((turn) => turn.agent))] });
1478
1501
  await Promise.allSettled([...this.#turns.values()].map((turn) => turn.promise));
@@ -1516,7 +1539,7 @@ export class Room {
1516
1539
  plan.stopped = reason;
1517
1540
  this.#escalation.settleAll(planId, 'stopped');
1518
1541
  for (const turn of this.#turns.values()) {
1519
- if (turn.planId === planId) turn.controller.abort(reason);
1542
+ if (turn.planId === planId) { turn.stoppedByHuman = true; turn.controller.abort(reason); }
1520
1543
  }
1521
1544
  return true;
1522
1545
  }
@@ -1539,15 +1562,22 @@ export class Room {
1539
1562
  await this.#emit('message.failed', { messageId, target: targetId, planId, error: `${agent.label} was detected, but its MADRE adapter is not enabled yet.` });
1540
1563
  return null;
1541
1564
  }
1542
- if (agent.route?.custom && !agent.route.allowed) {
1543
- const destination = agent.route.host ?? 'an unrecognised host';
1544
- const source = agent.route.source ?? 'a custom endpoint setting';
1565
+ // Codex can change its provider in config.toml while this room is open. Recheck before
1566
+ // reading any conversation or memory, then keep the roster's route current as well.
1567
+ const route = agent.id === 'codex' && agent.route ? await codexRoute() : agent.route;
1568
+ if (agent.id === 'codex' && agent.route) agent.route = route;
1569
+ if (route?.custom && !route.allowed) {
1570
+ const destination = route.host ?? 'an unrecognised host';
1571
+ const source = route.source ?? 'a custom endpoint setting';
1545
1572
  const official = agent.id === 'codex' ? 'OpenAI' : agent.id === 'claude' ? 'Anthropic' : 'the agent\'s official service';
1573
+ const advice = route.host
1574
+ ? `Remove that override to use the official service, or set PULSE_ALLOW_CUSTOM_AGENT_ENDPOINTS=${agent.id} only if you trust that endpoint.`
1575
+ : 'Remove that override to use the official service.';
1546
1576
  await this.#emit('message.failed', {
1547
1577
  messageId,
1548
1578
  target: targetId,
1549
1579
  planId,
1550
- 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.`,
1580
+ error: `MADRE blocked @${agent.id} before sending the briefing: ${source} points to ${destination}, not ${official}. ${advice}`,
1551
1581
  });
1552
1582
  return null;
1553
1583
  }
@@ -1639,6 +1669,7 @@ export class Room {
1639
1669
  ? await this.#toolsForTurn({ agent: agent.id, mode, lease: null, scratchDir: null }).catch(() => [])
1640
1670
  : [];
1641
1671
  const bishop = this.#bishopForTurn ? await this.#bishopForTurn({ agent: agent.id, mode, text, preview: true }).catch(() => null) : null;
1672
+ const skills = this.#skillsForTurn && agent.adapter !== 'madre-local' ? await this.#skillsForTurn({ agent: agent.id, mode, text, preview: true }).catch(() => []) : [];
1642
1673
  // Recall from links reads the other room when the turn runs; the preview only says it will.
1643
1674
  const linkedPreview = this.#linkedForTurn && agent.adapter !== 'madre-local' && mode !== 0 ? await this.#linkedForTurn({ agent: agent.id, mode, text, preview: true }).catch(() => null) : null;
1644
1675
  const scopes = this.scopesFor(agent.id);
@@ -1663,7 +1694,7 @@ export class Room {
1663
1694
  context: built.context, recall: built.recall, memories: built.memories,
1664
1695
  attachments: [], references: [], lease,
1665
1696
  scopes: { web: scopes.web.enabled && scopes.web.wired, imageGen: scopes.imageGen.enabled && scopes.imageGen.wired },
1666
- ash: ash === true && this.ashEnabled(), choices: this.#choicesEnabled && mode !== 0, runs: this.#runsEnabled && mode !== 0 && mode < 4, mode, escalation: null, mcpServers, bishop,
1697
+ ash: ash === true && this.ashEnabled(), choices: this.#choicesEnabled && mode !== 0, runs: this.#runsEnabled && mode !== 0 && mode < 4, mode, escalation: null, mcpServers, bishop, skills,
1667
1698
  });
1668
1699
  // Each block with what put it here and what would take it away, so "read, never written" can
1669
1700
  // be checked one block at a time instead of believed.
@@ -1701,6 +1732,13 @@ export class Room {
1701
1732
  mcpServers: [], env: [], isolation: [],
1702
1733
  };
1703
1734
  }
1735
+ if (agent.adapter === 'gemini-rest') {
1736
+ return {
1737
+ agent: agent.id, label: agent.label, local: false,
1738
+ says: t('No process is started for @gemini: the Gemini CLI is not installed, so MADRE sends the briefing to Google\'s Gemini API with your key and shows the answer. It cannot read the project, see attachments or write; install the Gemini CLI for that.'),
1739
+ mcpServers: [], env: [], isolation: [],
1740
+ };
1741
+ }
1704
1742
  const scopes = this.scopesFor(agent.id);
1705
1743
  const ceiling = Math.min(mode, scopes.maxMode ?? 0);
1706
1744
  const mcpServers = this.#toolsForTurn ? await this.#toolsForTurn({ agent: agent.id, mode: ceiling, lease: null, scratchDir: null }).catch(() => []) : [];
@@ -1711,7 +1749,8 @@ export class Room {
1711
1749
  : agent.id === 'gemini' ? buildGeminiArgs({ ...shared, policyPath: t('<written for this turn, deleted after it>'), attachmentsDir: null })
1712
1750
  : agent.id === 'opencode' ? buildOpenCodeArgs(shared)
1713
1751
  : agent.id === 'cursor' ? buildCursorArgs(shared)
1714
- : null;
1752
+ : agent.id === 'grok' ? buildGrokArgs({ ...shared, promptFile: t('<the briefing, in a file written for this turn and deleted after it>') })
1753
+ : null;
1715
1754
  if (!args) return { agent: agent.id, label: agent.label, local: false, says: t('MADRE has no adapter for @{agent}.', { agent: agent.id }), mcpServers: [], env: [], isolation: [] };
1716
1755
  const isolation = {
1717
1756
  codex: [t('--ephemeral: the run keeps no session of its own, so nothing said here reaches another project.')],
@@ -1719,10 +1758,12 @@ export class Room {
1719
1758
  gemini: [t('GEMINI_CLI_HOME points at a temporary home made for this turn and removed after it, so settings, hooks and extensions come from there and not from yours.'), t('GEMINI_CLI_NO_RELAUNCH keeps the launcher from spawning a second process MADRE could not stop.')],
1720
1759
  opencode: [t('The run is given the model you chose and nothing else of your session.')],
1721
1760
  cursor: [t('#0 and #1: --mode ask, Cursor\'s read-only mode, whatever its own settings say; no edits and no commands. #2 and #3: its agent mode with --force, writing allowed and every command denied. #4: commands allowed too. The places nobody writes stay denied at every mode, and MADRE locks and puts them back itself.'), t('CURSOR_CONFIG_DIR points at a configuration made for this turn and removed after it, with only what the mode you chose allows. The sign-in stays in the system keychain.')],
1761
+ grok: [t('#0 and #1: only the tools that read (--tools read_file,list_dir,grep) and --sandbox read-only. #2 and #3: its edit and write tools under --permission-mode dontAsk, writing allowed and the terminal denied, inside --sandbox workspace. #4: the terminal too, with --always-approve. At every mode the places nobody writes are denied one rule at a time.'), t('The folder is not trusted for the turn, and hooks, skills and servers from Claude and Cursor are not loaded. Grok keeps the conversation in its own history.')],
1722
1762
  }[agent.id] ?? [];
1723
1763
  const env = {
1724
1764
  gemini: [{ name: 'GEMINI_CLI_HOME', note: t('the temporary home for this turn') }, { name: 'GEMINI_CLI_NO_RELAUNCH', note: t('so the launcher stays killable') }],
1725
1765
  cursor: [{ name: 'CURSOR_CONFIG_DIR', note: t('the configuration for this turn, from the mode you chose') }, { name: 'NO_OPEN_BROWSER', note: t('a turn never opens a page') }],
1766
+ grok: [{ name: 'GROK_CLAUDE_*_ENABLED, GROK_CURSOR_*_ENABLED', note: t('false: nothing of Claude\'s or Cursor\'s is loaded') }, { name: 'GROK_MEMORY', note: t('0: Grok\'s own memory stays off; the project\'s is MADRE\'s') }, { name: 'GROK_DISABLE_AUTOUPDATER', note: t('1: a turn never updates the CLI') }],
1726
1767
  }[agent.id] ?? [];
1727
1768
  return {
1728
1769
  agent: agent.id, label: agent.label, local: false,
@@ -1762,6 +1803,7 @@ export class Room {
1762
1803
  controlHolder: this.#controlDesk.holder?.agent ?? null,
1763
1804
  privacyMarker: this.#privacy?.marker ?? '[ENTIDAD-ORG]',
1764
1805
  sdk: input.lease?.sdk ?? sdkPaths(),
1806
+ skillGuide: skillGuide(),
1765
1807
  madreModel: this.#agents.find((agent) => agent.id === 'madre' && agent.ready)?.version ?? null,
1766
1808
  });
1767
1809
  }
@@ -1771,7 +1813,12 @@ export class Room {
1771
1813
  // try that reports failures, with the room showing «writing…» until MADRE was closed.
1772
1814
  async #couldNotSeat({ messageId, agent, planId, error }) {
1773
1815
  const said = String(error?.message ?? error ?? '').split('\n').filter(Boolean).slice(0, 2).join(' ').slice(0, 300);
1774
- const text = t('MADRE could not take the restore point before @{agent} writes, so nothing was changed: {error}', { agent: agent.id, error: said });
1816
+ // No git on this computer at all (D-5, Linux copies of 1.1.2): said as what to install, not as
1817
+ // «spawn git ENOENT».
1818
+ const noGit = error?.code === 'ENOENT' && /\bgit\b/.test(`${error?.path ?? ''} ${error?.syscall ?? ''}`);
1819
+ const text = noGit
1820
+ ? t('This computer does not have git, which MADRE needs to take the restore point before @{agent} writes, so nothing was changed. Install git and send it again.', { agent: agent.id })
1821
+ : t('MADRE could not take the restore point before @{agent} writes, so nothing was changed: {error}', { agent: agent.id, error: said });
1775
1822
  await this.#emit('message.failed', { messageId, target: agent.id, planId, error: this.#privacy ? this.#privacy.redact(text).text : text });
1776
1823
  return null;
1777
1824
  }
@@ -1789,8 +1836,12 @@ export class Room {
1789
1836
  let controlRun = null;
1790
1837
  let createRun = null;
1791
1838
  let responseMessageId = null;
1792
- // The copilot's #3 reaches past an agent's max mode, never past what its CLI can write.
1793
- const asCopilot = copilot === true && mode === 3 && this.copilotOn() && Boolean(agentScopes.write?.capable);
1839
+ // The copilot's #3 reaches past an agent's max mode, never past what its CLI can write. The
1840
+ // window is read once, here: the turn may wait for the project before its prompt is written,
1841
+ // and a window that closed in that wait read as null there and failed the turn (D-16, a copy
1842
+ // in WSL, 2026-11-05). A turn that started under the window ends under it, as one running does.
1843
+ const copilotWindow = copilot === true && mode === 3 ? this.#copilotNow() : null;
1844
+ const asCopilot = Boolean(copilotWindow) && Boolean(agentScopes.write?.capable);
1794
1845
  if (mode >= 3 && (requester === 'you' || planId) && depth <= 1 && (agentScopes.maxMode >= mode || asCopilot) && (enabled.write || asCopilot)) {
1795
1846
  // CONTROL: the project itself is the writable root, and a checkpoint
1796
1847
  // taken now makes every change of this turn reversible. A plan step gets
@@ -1847,7 +1898,8 @@ export class Room {
1847
1898
  turnScopes.imageGen = Boolean(lease?.scopes?.imageGen);
1848
1899
  // The step asks for files but nobody granted a lease: say so now, with a
1849
1900
  // way out, instead of letting the agent's refusal be the only signal.
1850
- if (!lease && !sharedLease && !escalation && looksLikeCreation(text)) {
1901
+ // Only for an agent that could have created it: one that reads at every mode has no «Create» to turn on.
1902
+ if (!lease && !sharedLease && !escalation && capabilityOf(agent.id).write && looksLikeCreation(text)) {
1851
1903
  await this.#emit('lease.missing', {
1852
1904
  messageId,
1853
1905
  agent: agent.id,
@@ -1886,6 +1938,11 @@ export class Room {
1886
1938
  ? await this.#toolsForTurn({ agent: agent.id, mode: turnMode, text, turn: responseMessageId, lease, scratchDir: lease?.scratchDir ? joinPath(this.#projectRoot, lease.scratchDir) : null, servers: this.#runDesk.serving().filter((one) => !one.network).map((one) => one.port) }).catch(() => [])
1887
1939
  : [];
1888
1940
  const bishop = this.#bishopForTurn ? await this.#bishopForTurn({ agent: agent.id, mode: turnMode, text, turn: responseMessageId }).catch(() => null) : null;
1941
+ // Ways of working the human keeps for this project (H-2). Not for @madre: its briefing is its
1942
+ // own. A skill that fails to be read hands nothing and the turn goes on without it.
1943
+ const skills = this.#skillsForTurn && agent.adapter !== 'madre-local'
1944
+ ? await this.#skillsForTurn({ agent: agent.id, mode: turnMode, text, turn: responseMessageId }).catch(() => [])
1945
+ : [];
1889
1946
  // Notes a link with automatic recall brings to this turn (fase 3e): never in GHOST, never for
1890
1947
  // @madre (its briefing is its own), bounded by the module and counted as readings.
1891
1948
  const linked = this.#linkedForTurn && agent.adapter !== 'madre-local' && turnMode !== 0
@@ -1893,7 +1950,10 @@ export class Room {
1893
1950
  : null;
1894
1951
  // The prompt and the shape it was built from: one is sent, the other is kept until the CLI
1895
1952
  // says what it cost, so the bill can be attributed to the blocks that caused it.
1896
- const shaped = this.#promptFor({ agent, text, requester, depth, allowDelegation, context, recall, memories, attachments, references, lease, scopes: turnScopes, imageStudio, ash, choices: this.#choicesEnabled && turnMode !== 0, runs: this.#runsEnabled && turnMode !== 0 && turnMode < 4, mode: turnMode, escalation, mcpServers, bishop, linked, returned, copilot: asCopilot && controlRun ? copilotBrief(this.#copilotNow()) : null, sharedLeaseHint: sharedLease && !lease ? 'A creation lease is active for this plan, but file creation is not enabled for you: answer without creating files and say so if asked to create one.' : null });
1953
+ // Said in the room while the turn works: which way of working went in, and why. A skill the
1954
+ // person never sees is a skill they cannot switch off when it was the wrong one.
1955
+ if (skills.length) this.#say('turn.skills', { messageId, agent: agent.id, skills: skills.map(({ id, name, state, why }) => ({ id, name, state, why })) });
1956
+ const shaped = this.#promptFor({ agent, text, requester, depth, allowDelegation, context, recall, memories, attachments, references, lease, scopes: turnScopes, imageStudio, ash, skills, choices: this.#choicesEnabled && turnMode !== 0, runs: this.#runsEnabled && turnMode !== 0 && turnMode < 4, mode: turnMode, escalation, mcpServers, bishop, linked, returned, copilot: asCopilot && controlRun ? copilotBrief(copilotWindow) : null, sharedLeaseHint: sharedLease && !lease ? 'A creation lease is active for this plan, but file creation is not enabled for you: answer without creating files and say so if asked to create one.' : null });
1897
1957
  this.#promptShape.set(responseMessageId, { parts: shaped.parts, spared: shaped.spared, servers: [this.#memoryServer?.name, ...mcpServers.map((server) => server.name)].filter(Boolean) });
1898
1958
  // What this turn is about to read, said while it is still reading it. The size is exact;
1899
1959
  // only the conversion to tokens is an estimate, and it is made at this room's own rate.
@@ -2045,6 +2105,7 @@ export class Room {
2045
2105
  }
2046
2106
  if (asked) await this.#emit('choice.offered', { messageId, responseMessageId, agent: agent.id, question: asked.question, options: asked.options, recommended: asked.recommended ?? undefined, modes: asked.modes ?? undefined });
2047
2107
  if (requested) {
2108
+ await attachCommandScripts(requested.commands, { projectRoot: this.#projectRoot });
2048
2109
  await this.#emit('run.requested', { messageId, responseMessageId, agent: agent.id, reason: requested.reason, commands: requested.commands, mode: turnMode, copilot: asCopilot && controlRun ? true : undefined });
2049
2110
  if (asCopilot && controlRun) this.#copilotRuns.push(responseMessageId);
2050
2111
  }
@@ -2055,6 +2116,11 @@ export class Room {
2055
2116
  for (const file of artifacts.filter((item) => isModuleFile(item.path))) {
2056
2117
  await this.#emit('module.proposed', { agent: agent.id, messageId, responseMessageId, path: file.path, name: file.name });
2057
2118
  }
2119
+ // And a <id>.habilidad.md is one proposing a way of working (H-6). Same rule: it writes, the
2120
+ // person installs.
2121
+ for (const file of artifacts.filter((item) => isSkillFile(item.path))) {
2122
+ await this.#emit('skill.proposed', { agent: agent.id, messageId, responseMessageId, path: file.path, name: file.name, id: skillIdOf(file.path) });
2123
+ }
2058
2124
  }
2059
2125
  if (createChanges && (createChanges.existingReverted.length || createChanges.forbiddenReverted.length)) {
2060
2126
  await this.#emit('create.reverted', { checkpointId: createChanges.checkpointId, agent: agent.id, messageId, responseMessageId, existing: createChanges.existingReverted, forbidden: createChanges.forbiddenReverted, message: createChanges.message });
@@ -2063,7 +2129,7 @@ export class Room {
2063
2129
  if (this.#memory && turnMode !== 0) {
2064
2130
  const noted = this.#memory.notesSince(notesBefore, { agent: agent.id });
2065
2131
  if (noted.length) {
2066
- await this.#emit('memory.noted', { agent: agent.id, messageId, responseMessageId, notes: noted.map((note) => ({ id: note.id, kind: note.kind, text: note.text, fromSequence: note.fromSequence, throughSequence: note.throughSequence })), total: this.#memory.memoryCount() });
2132
+ await this.#emit('memory.noted', { agent: agent.id, messageId, responseMessageId, notes: noted.map((note) => ({ id: note.id, kind: note.kind, text: note.text, fromSequence: note.fromSequence, throughSequence: note.throughSequence, unsourced: unsourced(note) })), total: this.#memory.memoryCount() });
2067
2133
  this.#vectors.schedule();
2068
2134
  }
2069
2135
  }
@@ -2083,7 +2149,7 @@ export class Room {
2083
2149
  this.#liveTurns.delete(responseMessageId);
2084
2150
  // Which model the turn ran on, when the room knows it (the one asked for, or the agent's
2085
2151
  // default): what answered is what MADRE can offer again when another model fails.
2086
- const ranOn = await this.#pricedModel(agent.id, model).catch(() => null);
2152
+ const ranOn = result.model ?? await this.#pricedModel(agent.id, model).catch(() => null);
2087
2153
  await this.#emit('agent.completed', { messageId, agent: agent.id, handoffId, planId, ...(ranOn ? { ranOn } : {}) });
2088
2154
  return { responseMessageId, directives };
2089
2155
  } catch (error) {
package/src/router.mjs CHANGED
@@ -1,6 +1,6 @@
1
1
  // SPDX-License-Identifier: BUSL-1.1
2
2
  // MADRE · © 2026 Jossue Alcalá · Business Source License 1.1: LICENSE
3
- const supported = new Set(['codex', 'claude', 'gemini', 'opencode', 'cursor']);
3
+ const supported = new Set(['codex', 'claude', 'gemini', 'opencode', 'cursor', 'grok']);
4
4
 
5
5
  export function parseMessage(text, fallbackTarget = null) {
6
6
  const value = String(text ?? '').trim();
package/src/runs.mjs CHANGED
@@ -26,6 +26,7 @@
26
26
 
27
27
  import { homedir } from 'node:os';
28
28
  import { join } from 'node:path';
29
+ import { readFile } from 'node:fs/promises';
29
30
 
30
31
  export const MAX_COMMANDS = 5;
31
32
  const MAX_REASON = 300;
@@ -140,3 +141,41 @@ export function withoutRunRequest(text) {
140
141
  const last = [...source.matchAll(/```pulse-run\s*\n[\s\S]*?```/gi)].at(-1);
141
142
  return source.slice(0, last.index).trimEnd();
142
143
  }
144
+
145
+ // Resolves what script package.json defines for a package-manager command (RX-3).
146
+ // Returns the raw script string if defined, or null. Only where the manager really runs that script:
147
+ // npm runs one by its name alone only for test, start, stop and restart (`npm build` is «Unknown
148
+ // command»), and `bun test` and `bun build` are Bun's own test runner and bundler, not the scripts.
149
+ export function resolveScript(argv, packageJson) {
150
+ if (!Array.isArray(argv) || !packageJson || typeof packageJson !== 'object') return null;
151
+ const scripts = packageJson.scripts;
152
+ if (!scripts || typeof scripts !== 'object') return null;
153
+ const [pkg, sub, ...rest] = argv;
154
+ const name = String(pkg ?? '').toLowerCase();
155
+ if (!['npm', 'pnpm', 'yarn', 'bun'].includes(name)) return null;
156
+ const script = (key) => (key && typeof scripts[key] === 'string' ? scripts[key] : null);
157
+ if (sub === 'run' || sub === 'run-script') return script(rest[0]);
158
+ if (name === 'bun') return null;
159
+ if (sub === 'test' || (name !== 'yarn' && (sub === 't' || sub === 'tst'))) return script('test');
160
+ if (name === 'npm') return ['start', 'stop', 'restart'].includes(sub) ? script(sub) : null;
161
+ return script(sub);
162
+ }
163
+
164
+ // Attaches the real script from package.json to each command when available (RX-3).
165
+ export async function attachCommandScripts(commands, { projectRoot, readFile: read = readFile } = {}) {
166
+ if (!projectRoot || !Array.isArray(commands) || !commands.length) return commands;
167
+ let pkg = null;
168
+ try {
169
+ const raw = await read(join(projectRoot, 'package.json'), 'utf8');
170
+ pkg = JSON.parse(raw);
171
+ } catch {
172
+ return commands;
173
+ }
174
+ for (const command of commands) {
175
+ if (command?.argv && !command.script) {
176
+ const script = resolveScript(command.argv, pkg);
177
+ if (script) command.script = script;
178
+ }
179
+ }
180
+ return commands;
181
+ }
@@ -6,6 +6,7 @@ import { homedir, tmpdir, userInfo } from 'node:os';
6
6
  import { delimiter, join } from 'node:path';
7
7
  import { execFile } from 'node:child_process';
8
8
  import { promisify } from 'node:util';
9
+ import { keyFromGeminiEnvFile } from './mcp/image-server.mjs';
9
10
 
10
11
  const accountHome = () => { try { return userInfo().homedir || homedir(); } catch { return homedir(); } };
11
12
 
@@ -51,6 +52,17 @@ const definitions = [
51
52
  versionArgs: ['--version'],
52
53
  adapter: 'cursor-readonly',
53
54
  },
55
+ {
56
+ // Grok Build, xAI's own CLI (2026-11-06): npm puts it beside node, its own installer in
57
+ // ~/.grok/bin. Another program is called `grok` too (the community's grok-dev, which writes to
58
+ // ~/.grok as well), so only the one that says «grok <version> (<build>)» is spoken to.
59
+ id: 'grok',
60
+ label: 'Grok',
61
+ candidates: [...new Set(['grok', '/opt/homebrew/bin/grok', join(homedir(), '.grok', 'bin', 'grok'), join(accountHome(), '.grok', 'bin', 'grok')])],
62
+ versionArgs: ['--version'],
63
+ versionPattern: /^grok\s+\d+\.\d+\.\d+\s+\(/,
64
+ adapter: 'grok-readonly',
65
+ },
54
66
  ];
55
67
 
56
68
  const OFFICIAL_DESTINATIONS = {
@@ -176,19 +188,47 @@ async function readVersion(path, args) {
176
188
  export const toolsPrefix = (env = process.env) => join(env.PULSE_HOME ?? join(homedir(), '.pulse'), 'tools');
177
189
  export const toolsBin = (env = process.env) => (process.platform === 'win32' ? toolsPrefix(env) : join(toolsPrefix(env), 'bin'));
178
190
 
179
- export async function detectAgents({ env = process.env } = {}) {
191
+ // Gemini without its CLI (a575180, reviewed 2026-11-06): a Gemini API key the CLI's own places hold
192
+ // (GEMINI_API_KEY, or ~/.gemini/.env, where MADRE writes a pasted key) is enough to answer through
193
+ // Google's API. Only those: GOOGLE_API_KEY is any Google key (Maps, say), and the keychain is asked
194
+ // only when a turn needs the key, never on every look, where it could raise the system's prompt.
195
+ // PULSE_GEMINI_ADAPTER=rest takes the API even with the CLI there.
196
+ export async function geminiApiKeyPresent(env = process.env, fromFile = keyFromGeminiEnvFile) {
197
+ return Boolean(env.GEMINI_API_KEY) || Boolean(await fromFile(env).catch(() => null));
198
+ }
199
+
200
+ export async function detectAgents({ env = process.env, keyPresent = geminiApiKeyPresent, finder = findExecutable } = {}) {
180
201
  const searchPath = [env.PATH ?? '', toolsBin(env)].filter(Boolean).join(delimiter);
181
202
  return Promise.all(definitions.map(async (definition) => {
182
- const path = await findExecutable(definition.candidates, searchPath);
183
- const detected = Boolean(path);
203
+ let path = await finder(definition.candidates, searchPath, env);
204
+ let detected = Boolean(path);
205
+ let ready = detected && Boolean(definition.adapter);
206
+ let version = path ? await readVersion(path, definition.versionArgs) : null;
207
+ let adapter = definition.adapter ?? null;
208
+ let viaApi = false;
209
+ // A program with the right name that is not the right program is found, never spoken to.
210
+ const foreign = Boolean(path && definition.versionPattern && version && !definition.versionPattern.test(version));
211
+ if (foreign) ready = false;
212
+
213
+ if (definition.id === 'gemini' && (!detected || env.PULSE_GEMINI_ADAPTER === 'rest') && await keyPresent(env)) {
214
+ detected = true;
215
+ ready = true;
216
+ adapter = 'gemini-rest';
217
+ viaApi = true;
218
+ path = null;
219
+ version = 'Google AI Studio API';
220
+ }
221
+
184
222
  return {
185
223
  id: definition.id,
186
224
  label: definition.label,
187
225
  detected,
188
- ready: detected && Boolean(definition.adapter),
189
- adapter: definition.adapter ?? null,
226
+ ready,
227
+ adapter,
190
228
  path,
191
- version: path ? await readVersion(path, definition.versionArgs) : null,
229
+ version,
230
+ ...(viaApi ? { viaApi: true } : {}),
231
+ ...(foreign ? { foreign: true } : {}),
192
232
  route: agentRouteFromEnvironment(definition.id, env),
193
233
  };
194
234
  }));