@jossuealcala/madre 0.3.1 → 0.3.3

package/src/room.mjs

@@ -21,11 +21,13 @@ import { parseDirectives } from './directives.mjs';
 import { isValidModelName } from './models.mjs';
 import { MODES, SCOPES, SCOPE_LABELS, capabilitySummary, normalizeMode, resolveScopes } from './capabilities.mjs';
 import { createLease, diffSnapshots, snapshot } from './lease.mjs';
+import { stat as statFile } from 'node:fs/promises';
+import { basename as baseName, join as joinPath } from 'node:path';
+import { contentTypeFor } from './files.mjs';
 import { imageStudioFor } from './image-studio.mjs';
 import { CAPABILITIES, imageModuleState } from './capabilities.mjs';
 import { resolveReferences } from './files.mjs';
 import { compressAshCode } from './ashcode.mjs';
-import { isGitRepo } from './checkpoint.mjs';
 
 // Adapters can fail with multi-line stderr or stack traces. The room keeps only
 // the first meaningful line, bounded, so the event log and the UI stay readable.
@@ -81,6 +83,7 @@ export class Room {
   #scopeConfig = {};
   #delegation;
   #privacy = null;
+  #toolsForTurn = null;
   #maxPlanSteps;
   #maxConcurrentTurns;
   #planMaxAgeMs;
@@ -98,6 +101,7 @@ export class Room {
     memoryServer = null,
     mother = null,
     privacy = null,
+    toolsForTurn = null,   // async ({ agent, mode, lease, scratchDir }) => MCP server specs from the modules
     historicalEvents = [],
     invokers = defaultInvokers,
     agentTimeouts = {},
@@ -117,6 +121,7 @@ export class Room {
     this.#memoryServer = memoryServer;
     this.#mother = mother;
     this.#privacy = privacy;
+    this.#toolsForTurn = toolsForTurn;
     this.#invokers = invokers;
     this.#agentTimeouts = agentTimeouts;
     this.#maxMessageChars = maxMessageChars;
@@ -193,8 +198,7 @@ export class Room {
     }
     const scopes = this.scopesFor(step.agent);
     const enabled = Object.fromEntries(SCOPES.map((scope) => [scope, scopes[scope].enabled && scopes[scope].wired]));
-    const lease = await createLease({ projectRoot: this.#projectRoot, leaseId: randomUUID() });
-    lease.messageId = parentMessageId;
+    const lease = await this.#projectLease({ leaseId: randomUUID(), messageId: parentMessageId });
     lease.scopes = decision.decision === 'plan' ? Object.fromEntries(SCOPES.map((scope) => [scope, true])) : enabled;
     await this.#emit('lease.granted', {
       escalated: decision.decision,
@@ -202,6 +206,7 @@ export class Room {
       messageId: parentMessageId,
       agent: step.agent,
       outDir: lease.relativeDir,
+      scratchDir: lease.scratchDir,
       scopes: SCOPES.filter((scope) => enabled[scope]),
       unavailable: SCOPES.filter((scope) => !scopes[scope].capable).map((scope) => SCOPE_LABELS[scope]),
       planId,
@@ -354,11 +359,12 @@ export class Room {
     const wanted = normalizeMode(mode, create === true ? 2 : 1);
     if (!parsed.target) return { ok: true, mode: wanted };
     const scopes = this.scopesFor(parsed.target);
-    if (wanted === 3) {
-      if (scopes.maxMode < 3) return { ok: false, status: 403, mode: wanted, maxMode: scopes.maxMode, error: `@${parsed.target} is capped at #${scopes.maxMode} ${MODES[scopes.maxMode].label}; raise its MAX MODE to #3 in CONNECTIONS first.` };
-      if (!(await isGitRepo(this.#projectRoot))) return { ok: false, status: 412, mode: wanted, maxMode: scopes.maxMode, error: 'CONTROL needs the project to be a git repository: the checkpoint that makes UNDO possible is a git commit. Run git init first.' };
-      if (this.#controlDesk.holder) return { ok: false, status: 409, mode: wanted, maxMode: scopes.maxMode, error: `@${this.#controlDesk.holder.agent} already holds CONTROL of this project; one holder at a time. STOPALL revokes it.` };
-      return { ok: true, mode: 3, maxMode: scopes.maxMode };
+    if (wanted >= 3) {
+      // #3 CONTROL and #4 AIRLOCK: the ceiling must allow it, and there is one holder at a time.
+      // A project without git still checkpoints, in MADRE's shadow repository.
+      if (scopes.maxMode < wanted) return { ok: false, status: 403, mode: wanted, maxMode: scopes.maxMode, error: `@${parsed.target} is capped at #${scopes.maxMode} ${MODES[scopes.maxMode].label}; raise its MAX MODE to #${wanted} in CONNECTIONS to arm ${MODES[wanted].label}.` };
+      if (this.#controlDesk.holder) return { ok: false, status: 409, mode: wanted, maxMode: scopes.maxMode, error: `@${this.#controlDesk.holder.agent} already holds ${MODES[this.#controlDesk.holder.mode ?? 3].label} of this project; one holder at a time. STOPALL revokes it.` };
+      return { ok: true, mode: wanted, maxMode: scopes.maxMode };
     }
     // #2 above the agent's ceiling still goes out: the room answers read-only
     // and says why (lease.refused), the way CREATE has always behaved.
@@ -517,7 +523,7 @@ export class Room {
     if (!gate.ok) throw new Error(gate.error);
     create = requestedMode === 2;
     const ghost = requestedMode === 0;
-    const control = requestedMode === 3;
+    const control = requestedMode >= 3;
     const files = (Array.isArray(attachments) ? attachments : []).map((id) => this.attachment(id)).filter(Boolean);
     if (!parsed.text && !files.length) throw new Error('Write a message first.');
     if (!parsed.target) throw new Error('Choose an agent or begin with @agent.');
@@ -536,7 +542,7 @@ export class Room {
     if (ghost) this.#ghost.add(messageId);
     await this.#emit('message.created', {
       messageId,
-      mode: ghost ? 0 : control ? 3 : (standing || create ? 2 : 1),
+      mode: ghost ? 0 : control ? requestedMode : (standing || create ? 2 : 1),
       role: 'user',
       sender: 'you',
       target: parsed.target,
@@ -574,10 +580,9 @@ export class Room {
           message: `@${parsed.target} will answer read-only: ${scopes.write.capable ? 'file creation is switched off for it (enable it in CONNECTIONS)' : 'its CLI cannot create files'}${unavailable.length ? `; it cannot ${unavailable.join(' or ')}` : ''}.${alternatives.length ? ` For creation ask ${alternatives.join(' or ')}.` : ''}`,
         });
       } else {
-        lease = await createLease({ projectRoot: this.#projectRoot, leaseId: randomUUID() });
-        lease.messageId = messageId;
+        lease = await this.#projectLease({ leaseId: randomUUID(), messageId });
         // CREATE authorizes the plan to use each delegate's enabled creation
-        // scopes; a standing write lease authorizes files only.
+        // scopes; a default-#2 lease authorizes files only.
         lease.scopeCeiling = { write: true, imageGen: !standing, web: true };
         lease.scopes = Object.fromEntries(SCOPES.map((scope) => [scope, enabled.includes(scope) && (!standing || scope === 'write')]));
         await this.#emit('lease.granted', {
@@ -586,6 +591,7 @@ export class Room {
           messageId,
           agent: parsed.target,
           outDir: lease.relativeDir,
+          scratchDir: lease.scratchDir,
           grantedBy: 'you',
           scopes: standing ? ['write'] : enabled,
           unavailable,
@@ -606,7 +612,26 @@ export class Room {
       allowDelegation = false;
       await this.#alert('plan-active', `A plan by @${[...this.#plans.values()][0].orchestrator} is still running. Your message will be answered, but no second plan will start. Type STOPALL to halt every agent.`, `plan-active:${messageId}`);
     }
-    await this.#track(this.#dispatch({ messageId, targetId: parsed.target, text: text2, requester: 'you', depth: 0, allowDelegation: allowDelegation && !ghost, model: chosenModel, attachments: files, references, lease, ashCode: ashActive, mode: ghost ? 0 : control ? 3 : (lease ? 2 : 1) }));
+    await this.#track(this.#dispatch({ messageId, targetId: parsed.target, text: text2, requester: 'you', depth: 0, allowDelegation: allowDelegation && !ghost, model: chosenModel, attachments: files, references, lease, ashCode: ashActive, mode: ghost ? 0 : control ? requestedMode : (lease ? 2 : 1) }));
+  }
+
+  // A #2 lease: the project itself is where new files go, and MADRE keeps a scratch folder
+  // under .pulse/out/ for what has no natural place. Each turn under it takes a checkpoint
+  // and puts back whatever existed before, so CREATE only ever adds.
+  async #projectLease({ leaseId, messageId }) {
+    const scratch = await createLease({ projectRoot: this.#projectRoot, leaseId });
+    return { leaseId, messageId, outDir: this.#projectRoot, relativeDir: '.', scratchDir: scratch.relativeDir, create: true };
+  }
+
+  // Artifacts from a #2 turn: the files the checkpoint saw appear, as the room shows them.
+  async #artifactsFrom(files) {
+    const out = [];
+    for (const file of files) {
+      if (file.status !== 'A') continue;
+      const info = await statFile(joinPath(this.#projectRoot, file.path)).catch(() => null);
+      out.push({ name: baseName(file.path), path: file.path, size: info?.size ?? 0, contentType: contentTypeFor(file.path), status: 'created' });
+    }
+    return out.sort((a, b) => a.path.localeCompare(b.path));
   }
 
   // Agents that can receive a delegated step from `self`.
@@ -714,7 +739,7 @@ export class Room {
     // The orchestrator's turn is over before its plan starts, so it is never
     // counted as in flight while the others work.
     if (outcome?.directives?.steps.length) {
-      await this.#runPlan({ orchestrator: agent.id, parentMessageId: outcome.responseMessageId, directives: outcome.directives, lease, ashCode });
+      await this.#runPlan({ orchestrator: agent.id, parentMessageId: outcome.responseMessageId, directives: outcome.directives, lease, ashCode, mode });
     }
     return outcome?.responseMessageId ?? null;
   }
@@ -745,13 +770,19 @@ export class Room {
     const turnScopes = { web: enabled.web, imageGen: enabled.imageGen };
     let lease = null;
     let controlRun = null;
-    if (mode === 3 && requester === 'you' && depth === 0) {
+    let createRun = null;
+    if (mode >= 3 && (requester === 'you' || planId) && depth <= 1 && agentScopes.maxMode >= mode && enabled.write) {
       // CONTROL: the project itself is the writable root, and a checkpoint
-      // taken now makes every change of this turn reversible.
-      const seat = await this.#controlDesk.begin({ agent, messageId, enabledScopes: enabled });
-      controlRun = seat.run;
-      lease = seat.lease;
-      await this.#emit('control.started', seat.announcement);
+      // taken now makes every change of this turn reversible. A plan step gets
+      // it when the orchestrator, itself in #3, named #3 for that step.
+      if (this.#controlDesk.holder) {
+        await this.#alert('control-busy', `@${this.#controlDesk.holder.agent} still holds CONTROL; @${agent.id} answers read-only this turn.`, `control-busy:${agent.id}`);
+      } else {
+        const seat = await this.#controlDesk.begin({ agent, messageId, enabledScopes: enabled, mode });
+        controlRun = seat.run;
+        lease = seat.lease;
+        await this.#emit('control.started', seat.announcement);
+      }
     } else if (sharedLease) {
       lease = enabled.write ? {
         ...sharedLease,
@@ -760,8 +791,7 @@ export class Room {
     } else if (agentScopes.write.always && enabled.write && requester !== 'you' && requester !== 'mother') {
       // Standing lease for a delegate: the human opted this agent into
       // creating files on every turn, so a plan step gets its own directory.
-      lease = await createLease({ projectRoot: this.#projectRoot, leaseId: randomUUID() });
-      lease.messageId = messageId;
+      lease = await this.#projectLease({ leaseId: randomUUID(), messageId });
       lease.scopeCeiling = { write: true, imageGen: false, web: true };
       lease.scopes = { ...enabled, imageGen: false };
       await this.#emit('lease.granted', {
@@ -770,11 +800,18 @@ export class Room {
         messageId,
         agent: agent.id,
         outDir: lease.relativeDir,
+        scratchDir: lease.scratchDir,
         scopes: ['write'],
         unavailable: SCOPES.filter((scope) => !agentScopes[scope].capable).map((scope) => SCOPE_LABELS[scope]),
         planId,
       });
     }
+    if (lease?.create && !controlRun) {
+      // CREATE: photograph the project now; after the turn only what appeared stays.
+      const seat = await this.#controlDesk.begin({ agent, messageId, enabledScopes: enabled, mode: 2 });
+      createRun = seat.run;
+      lease = { ...lease, checkpoint: seat.run.checkpoint };
+    }
     turnScopes.imageGen = Boolean(lease?.scopes?.imageGen);
     // The step asks for files but nobody granted a lease: say so now, with a
     // way out, instead of letting the agent's refusal be the only signal.
@@ -793,23 +830,27 @@ export class Room {
     const native = Boolean(CAPABILITIES[agent.id]?.imageGen);
     const studio = imageModuleState();
     const imageStudio = lease?.scopes?.imageGen && enabled.imageGen && !native && studio.enabled
-      ? imageStudioFor({ enabled: true, model: studio.model, outDir: lease.outDir })
+      ? imageStudioFor({ enabled: true, model: studio.model, outDir: lease.scratchDir ? joinPath(this.#projectRoot, lease.scratchDir) : lease.outDir })
       : null;
     // The turn's effective mode: #0 for ghosts, #3 in control, #2 only while it holds a lease.
-    const turnMode = mode === 0 ? 0 : controlRun ? 3 : lease ? 2 : 1;
+    const turnMode = mode === 0 ? 0 : controlRun ? controlRun.mode : lease ? 2 : 1;
     try {
       const invoke = this.#invokers[agent.adapter];
       if (!invoke) throw new Error(`${agent.label} does not have a supported MADRE adapter.`);
-      const before = lease && !lease.control ? await snapshot(lease.outDir) : null;
+      const before = lease && !lease.control && !lease.create ? await snapshot(lease.outDir) : null;
       const responseMessageId = randomUUID();
       const notesBefore = this.#memory ? this.#memory.maxMemoryId() : 0;
       const others = this.delegatesFor(agent.id);
       const mayDelegate = allowDelegation && this.#delegation && depth === 0;
+      // Tools the modules hand to this turn (a browser, say), attached to the CLI for this run only.
+      const mcpServers = this.#toolsForTurn && agent.adapter !== 'madre-local'
+        ? await this.#toolsForTurn({ agent: agent.id, mode: turnMode, lease, scratchDir: lease?.scratchDir ? joinPath(this.#projectRoot, lease.scratchDir) : null }).catch(() => [])
+        : [];
       const result = await invoke({
         executable: agent.path,
         projectRoot: this.#projectRoot,
         text,
-        prompt: this.#prompt({ agent, text, requester, depth, allowDelegation, context, recall, memories, attachments, references, lease, scopes: turnScopes, imageStudio, ashCode, mode: turnMode, escalation, 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 }),
+        prompt: this.#prompt({ agent, text, requester, depth, allowDelegation, context, recall, memories, attachments, references, lease, scopes: turnScopes, imageStudio, ashCode, mode: turnMode, escalation, mcpServers, 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 }),
         timeoutMs: this.timeoutFor(agent.id),
         signal,
         model,
@@ -818,6 +859,7 @@ export class Room {
         scopes: turnScopes,
         imageStudio,
         memoryServer: memoryServerForTurn(this.#memoryServer, { agent: agent.id, messageId: responseMessageId, mode: turnMode }),
+        mcpServers,
         // For @madre: who asks, who it may convene, and whether a plan would run at all.
         requester,
         crew: others,
@@ -828,7 +870,9 @@ export class Room {
       // the archivist or any other agent can see it. The reply says how many, not which.
       const guarded = this.#privacy?.redact(result.text ?? '') ?? { text: result.text, hits: 0 };
       if (guarded.hits) result.text = guarded.text;
-      const artifacts = lease && !lease.control ? diffSnapshots(before, await snapshot(lease.outDir), { relativeDir: lease.relativeDir }) : [];
+      // CREATE: what appeared stays and is shown; what existed before is put back and said.
+      const createChanges = createRun ? await this.#controlDesk.settle(createRun) : null;
+      const artifacts = createChanges ? await this.#artifactsFrom(createChanges.files) : lease && !lease.control ? diffSnapshots(before, await snapshot(lease.outDir), { relativeDir: lease.relativeDir }) : [];
       // CONTROL: what really changed in the project, forbidden zones reverted on the spot.
       const controlChanges = controlRun ? await this.#controlDesk.settle(controlRun) : null;
       const directives = mayDelegate
@@ -866,6 +910,9 @@ export class Room {
       if (artifacts.length) {
         await this.#emit('artifacts.created', { leaseId: lease.leaseId, messageId, responseMessageId, agent: agent.id, outDir: lease.relativeDir, files: artifacts });
       }
+      if (createChanges && (createChanges.existingReverted.length || createChanges.forbiddenReverted.length)) {
+        await this.#emit('create.reverted', { checkpointId: createChanges.checkpointId, agent: agent.id, messageId, responseMessageId, existing: createChanges.existingReverted, forbidden: createChanges.forbiddenReverted, message: createChanges.message });
+      }
       // What the agent saved through memory_note during this turn, for the bubble's hint.
       if (this.#memory && turnMode !== 0) {
         const noted = this.#memory.notesSince(notesBefore, { agent: agent.id });
@@ -884,24 +931,32 @@ export class Room {
     } finally {
       // Release CONTROL whichever way the turn ended; the checkpoint stays for UNDO.
       await this.#controlDesk.release(controlRun);
+      await this.#controlDesk.release(createRun);
     }
   }
 
-  async #runPlan({ orchestrator, parentMessageId, directives, lease = null, ashCode = false }) {
+  async #runPlan({ orchestrator, parentMessageId, directives, lease = null, ashCode = false, mode = 1 }) {
     const planId = randomUUID();
-    // The plan runs at the human's mode: #2 only while a lease exists, and a
-    // step's agent gets #2 only if its own scopes allow writing.
-    const stepMode = (agentId) => (lease && this.scopesFor(agentId).write.enabled ? 2 : 1);
+    // The plan's ceiling is the human's mode: #3 when the orchestrator held CONTROL, #2 while a
+    // lease exists, #1 otherwise. A step may ask for a mode ("@codex #2: …"); it gets the lowest
+    // of what it asked, the ceiling and its own MAX MODE. Without a number it inherits the plan.
+    const ceiling = mode >= 3 ? mode : lease ? 2 : 1;
+    const stepMode = (step) => {
+      const scopes = this.scopesFor(step.agent);
+      const asked = normalizeMode(step.mode, lease ? 2 : 1);
+      const granted = Math.min(asked, ceiling, scopes.maxMode);
+      return granted >= 2 && !scopes.write.enabled ? 1 : granted;
+    };
     const plan = { planId, orchestrator, steps: directives.steps, closing: directives.closing, step: 0, stopped: null, startedAt: Date.now() };
     this.#plans.set(planId, plan);
     await this.#emit('plan.created', {
       planId,
       orchestrator,
       parentMessageId,
-      steps: directives.steps.map((step) => ({ ...step, mode: stepMode(step.agent) })),
+      steps: directives.steps.map((step) => ({ ...step, mode: stepMode(step) })),
       closing: directives.closing,
       ignored: directives.ignored,
-      mode: lease ? 2 : 1,
+      mode: ceiling,
       leaseId: lease?.leaseId ?? null,
     });
     try {
@@ -917,7 +972,16 @@ export class Room {
         let stepLease = lease;
         let escalation = null;
         const stepScopes = this.scopesFor(step.agent);
-        if (!lease && !stepScopes.write.always && looksLikeCreation(step.text) && stepScopes.maxMode >= 2 && stepScopes.write.enabled) {
+        const wanted = stepMode(step);
+        // Under a #3 ceiling the orchestrator's word is enough: a #2 step gets its project lease,
+        // a #3 step gets CONTROL for its turn. Under #1 a creation step still asks the human.
+        if (ceiling >= 3 && !stepLease && wanted === 2) {
+          stepLease = await this.#projectLease({ leaseId: randomUUID(), messageId });
+          stepLease.scopeCeiling = { write: true, imageGen: true, web: true };
+          stepLease.scopes = Object.fromEntries(SCOPES.map((scope) => [scope, stepScopes[scope].enabled && stepScopes[scope].wired]));
+          await this.#emit('lease.granted', { delegated: true, leaseId: stepLease.leaseId, messageId, agent: step.agent, outDir: '.', scratchDir: stepLease.scratchDir, grantedBy: orchestrator, scopes: SCOPES.filter((scope) => stepLease.scopes[scope]), unavailable: [], planId });
+        }
+        if (ceiling < 3 && !lease && !stepScopes.write.always && (wanted >= 2 || looksLikeCreation(step.text)) && stepScopes.maxMode >= 2 && stepScopes.write.enabled) {
           const outcome = await this.#askForMode({ planId, plan, step, index, totalSteps: directives.steps.length + (directives.closing ? 1 : 0), orchestrator, parentMessageId, mode: 2 });
           if (outcome.scope === 'plan') lease = outcome.lease;
           if (outcome.scope) stepLease = outcome.lease; else escalation = outcome.reason;
@@ -933,12 +997,12 @@ export class Room {
           ashCode: ashCode ? { active: true, applied: abbreviated.applied, reason: abbreviated.reason, language: abbreviated.language, originalChars: abbreviated.originalChars, encodedChars: abbreviated.encodedChars } : undefined,
           status: 'delegated',
           planId,
-          mode: stepLease && stepScopes.write.enabled ? 2 : 1,
+          mode: wanted >= 3 ? wanted : stepLease && stepScopes.write.enabled ? 2 : 1,
           escalation: escalation ?? undefined,
           step: index + 1,
           totalSteps: directives.steps.length + (directives.closing ? 1 : 0),
         });
-        await this.#dispatch({ messageId, targetId: step.agent, text: stepText, requester: orchestrator, depth: 1, planId, allowDelegation: false, lease: stepLease, ashCode, mode: stepLease && stepScopes.write.enabled ? 2 : 1, escalation });
+        await this.#dispatch({ messageId, targetId: step.agent, text: stepText, requester: orchestrator, depth: 1, planId, allowDelegation: false, lease: wanted >= 3 ? null : stepLease, ashCode, mode: wanted >= 3 ? wanted : stepLease && stepScopes.write.enabled ? 2 : 1, escalation });
       }
       if (!plan.stopped && directives.closing) {
         plan.step = directives.steps.length + 1;

package/src/server.mjs

@@ -13,7 +13,7 @@ import { memoryServerFor } from './memory-tools.mjs';
 import { MotherChannel, CODE000_STRIKES } from './mother.mjs';
 import { ErrorSentinel } from './sentinel-errors.mjs';
 import { probeOllama, ollamaEmbedder, ollamaInvoker, pullModel } from './ollama.mjs';
-import { moduleById, describeModules, findModuleRoute } from './modules/index.mjs';
+import { moduleById, describeModules, findModuleRoute, toolsForTurn as modulesToolsForTurn } from './modules/index.mjs';
 import { madreAgent, madreInvoker, MADRE_AGENT_ID, MADRE_ADAPTER } from './adapters/madre.mjs';
 import { exportDataset, readiness as datasetReadiness } from './dataset.mjs';
 
@@ -43,7 +43,8 @@ import { extensionById, runInstaller } from './extensions.mjs';
 import { loginPlanFor, probeAll } from './auth-probe.mjs';
 import { loadConfig as readConfig, updateConfig } from './config.mjs';
 import { Privacy, normalizeTerms, privacySettings } from './privacy.mjs';
-import { checkForUpdate, detectInstall, updateCommand, releaseUrl } from './updates.mjs';
+import { checkForUpdate, detectInstall, updateCommand, releaseUrl, applyCommand } from './updates.mjs';
+import { spawn } from 'node:child_process';
 import { totalmem } from 'node:os';
 import { discoverModels } from './models.mjs';
 import { setImageModule } from './capabilities.mjs';
@@ -207,11 +208,15 @@ export async function createPulseServer({
   const mother = new MotherChannel(join(canonicalProjectRoot, '.pulse', 'mother.env'), { meta: memory ? { get: (key) => memory.metaGet(key), set: (key, value) => memory.metaSet(key, value) } : null });
   const motherOutcome = await mother.load().catch((error) => { console.error(`MADRE could not open MOTHER's channel: ${error.message}`); return null; });
   const startupMemory = await memoryConfig();
+  let listening = null;
+  const listeningPort = () => listening?.address?.()?.port ?? Number(process.env.PULSE_PORT ?? 4317);
   room = new Room({
     store,
     agents,
     projectRoot,
     privacy,
+    // Modules may hand tools to a turn; the room asks once per turn, the server knows the port.
+    toolsForTurn: async (turn) => modulesToolsForTurn(await moduleContext(), { ...turn, port: listeningPort(), roomDir }),
     softTokenBudget,
     contextMaxChars,
     recallShare: Number(process.env.PULSE_RECALL_SHARE ?? startupMemory.recallShare),
@@ -323,7 +328,9 @@ export async function createPulseServer({
         if (!agents.some((agent) => agent.id === agentId) || !scopes || typeof scopes !== 'object') continue;
         config.scopes[agentId] = { ...(current[agentId] ?? {}) };
         for (const scope of ['write', 'imageGen', 'web', 'alwaysCreate']) if (typeof scopes[scope] === 'boolean') config.scopes[agentId][scope] = scopes[scope];
-        if (Number.isInteger(Number(scopes.maxMode)) && Number(scopes.maxMode) >= 0 && Number(scopes.maxMode) <= 3) config.scopes[agentId].maxMode = Number(scopes.maxMode);
+        // MAX MODE and DEFAULT MODE are the two controls; setting them retires the older flags they replace.
+        if (Number.isInteger(Number(scopes.maxMode)) && Number(scopes.maxMode) >= 0 && Number(scopes.maxMode) <= 4) { config.scopes[agentId].maxMode = Number(scopes.maxMode); delete config.scopes[agentId].write; }
+        if (Number.isInteger(Number(scopes.defaultMode)) && Number(scopes.defaultMode) >= 1 && Number(scopes.defaultMode) <= 2) { config.scopes[agentId].defaultMode = Number(scopes.defaultMode); delete config.scopes[agentId].alwaysCreate; }
       }
       room.setScopes(config.scopes);
     }
@@ -784,6 +791,26 @@ export async function createPulseServer({
       if (request.method === 'GET' && url.pathname === '/api/version') {
         return sendJson(response, 200, await versionView({ force: url.searchParams.get('force') === '1' }));
       }
+      // One click: install the newer version and come back on the same port. The room records it,
+      // closes its listener so the port is free, hands the command to a detached shell and exits.
+      if (request.method === 'POST' && url.pathname === '/api/updates/apply') {
+        const info = await versionView();
+        if (!info.available) return sendJson(response, 409, { error: `Nothing to apply: ${info.current} is the latest MADRE knows of.` });
+        const command = applyCommand({ install, name: PACKAGE.name, version: info.latest, port: request.socket.localPort, projectRoot: canonicalProjectRoot });
+        if (!command) return sendJson(response, 412, { error: 'This copy runs from source: pull the repository and start it again.' });
+        if (room.activeTurns().length || room.activePlans().length) return sendJson(response, 409, { error: 'Agents are still working. STOPALL or wait, then update.' });
+        await room.record('room.updating', { from: info.current, to: info.latest, install, command });
+        sendJson(response, 202, { restarting: true, from: info.current, to: info.latest, command });
+        setTimeout(() => {
+          server.close(() => {
+            const child = spawn('/bin/sh', ['-c', command], { cwd: canonicalProjectRoot, detached: true, stdio: 'ignore', env: { ...process.env, PULSE_UPDATE_RESTART: '1' } });
+            child.unref();
+            setTimeout(() => process.exit(0), 200);
+          });
+          for (const client of clients.keys()) { try { client.end(); } catch { /* gone */ } }
+        }, 300);
+        return undefined;
+      }
       if (request.method === 'POST' && url.pathname === '/api/updates/settings') {
         const patch = await body(request).catch(() => ({}));
         if (typeof patch.check === 'boolean') { updatesConfig = { ...updatesConfig, check: patch.check }; await updateConfig(root, { updates: updatesConfig }); }
@@ -903,6 +930,7 @@ export async function createPulseServer({
       sendJson(response, 400, { error: error.message });
     }
   });
+  listening = server;
   // `server.close()` only resolves once every connection has ended, so the
   // long-lived SSE responses must be ended before the native close runs.
   const nativeClose = server.close.bind(server);

package/src/updates.mjs

@@ -38,6 +38,19 @@ export function updateCommand(install, name, version = 'latest') {
   }
 }
 
+// One shell line that installs the version and starts the same room on the same port.
+// The room's own process runs it detached after closing its listener, then exits.
+const shq = (value) => `'${String(value).replace(/'/g, `'\\''`)}'`;
+export function applyCommand({ install, name, version, port, projectRoot }) {
+  const start = `start --no-open --port ${Number(port) || 4317} --project ${shq(projectRoot)}`;
+  switch (install) {
+    case 'npx': return `exec npx -y ${name}@${version} ${start}`;
+    case 'project': return `npm install ${name}@${version} --no-fund --no-audit && exec npx --no ${name.split('/').pop()} ${start}`;
+    case 'global': return `npm install -g ${name}@${version} --no-fund --no-audit && exec ${name.split('/').pop()} ${start}`;
+    default: return null;   // source: the human pulls
+  }
+}
+
 export function releaseUrl(repository, version) {
   const url = String(repository?.url ?? repository ?? '').replace(/^git\+/, '').replace(/\.git$/, '');
   return url ? `${url}/releases/tag/v${version}` : null;