madarx 2.17.0 → 2.18.0

package/lib/agent-engines.js

@@ -7,18 +7,42 @@ import { chatWithClaude } from './claude.js';
 const ANTHROPIC_MODEL = 'claude-sonnet-4-6';
 import { publishLiveEvent } from './live-events.js';
 import { WORKSPACE, DATA_DIR, ensureDirs } from './paths.js';
+import { getStreamVerbosity, verbosityStreamsThinking, thinkingBudgetTokens } from './engine-verbosity.js';
 
 const PROJECT_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
+// Extract a short, human-readable preview from a tool_result block's content.
+// Content can be a string or an array of {type:'text', text} / image parts.
+function previewToolResultContent(block) {
+  const c = block?.content;
+  let text = '';
+  if (typeof c === 'string') text = c;
+  else if (Array.isArray(c)) {
+    text = c.map(p => (typeof p === 'string' ? p : (p?.type === 'text' && typeof p.text === 'string' ? p.text : ''))).join('');
+  }
+  text = String(text || '');
+  return {
+    preview: text.slice(0, 200),
+    chars: text.length,
+    lines: text ? text.split('\n').length : 0,
+  };
+}
+
 // Parses Claude Code's `--output-format stream-json` stdout. Each line is a JSON
 // envelope. We care about:
 //   - assistant.message.content[].type === 'text'       → accumulate response text
+//   - assistant.message.content[].type === 'thinking'   → surface reasoning (onThinkingDelta)
 //   - assistant.message.content[].type === 'tool_use'   → emit agent_tool_start
 //   - user.message.content[].type      === 'tool_result' → emit agent_tool_result
-// Everything else (system, init, hooks, partials, result) is ignored.
-function makeStreamJsonParser({ agentId, agentName, onText, onToolStart, onToolResult, onResult }) {
+//   - stream_event (only with --include-partial-messages) → incremental text /
+//     thinking deltas for smooth token-by-token streaming.
+// `partial` tells us deltas are active: when true the live preview is driven by
+// stream_event deltas, and the complete assistant envelope is used ONLY to
+// accumulate the authoritative final answer (avoids double-counting).
+export function makeStreamJsonParser({ agentId, agentName, partial = false, onText, onTextDelta, onThinkingDelta, onToolStart, onToolResult, onResult, onStatus }) {
   let buffer = '';
   const toolNameById = new Map();
+  const toolStartedAt = new Map();
   return function handleChunk(chunk) {
     buffer += chunk;
     let nl;
@@ -29,6 +53,28 @@ function makeStreamJsonParser({ agentId, agentName, onText, onToolStart, onToolR
       let evt;
       try { evt = JSON.parse(raw); } catch { continue; }
       if (!evt || typeof evt !== 'object') continue;
+
+      // Partial-message deltas (present only with --include-partial-messages).
+      // These wrap the raw Anthropic SSE event under evt.event. They drive the
+      // live preview; the authoritative answer still comes from the complete
+      // `assistant` envelopes below.
+      if (evt.type === 'stream_event' && evt.event && typeof evt.event === 'object') {
+        const se = evt.event;
+        if (se.type === 'content_block_delta' && se.delta) {
+          const d = se.delta;
+          if (d.type === 'text_delta' && typeof d.text === 'string') {
+            onTextDelta?.(d.text);
+          } else if (d.type === 'thinking_delta' && typeof d.thinking === 'string') {
+            onThinkingDelta?.(d.thinking);
+          }
+        } else if (se.type === 'content_block_start' && se.content_block?.type === 'thinking') {
+          onStatus?.('thinking');
+        } else if (se.type === 'message_start') {
+          onStatus?.('generating');
+        }
+        continue;
+      }
+
       // Terminal result event carries the run's final text at top level
       // (`evt.result`), not inside message.content. Capture it as a last-resort
       // answer for turns that emitted only tool_use blocks and no clean text
@@ -52,6 +98,16 @@ function makeStreamJsonParser({ agentId, agentName, onText, onToolStart, onToolR
         // can keep it for the live chat preview but exclude it from the
         // final return value.
         const hasToolUse = content.some(b => b?.type === 'tool_use');
+        // Thinking blocks in a complete envelope: only surface here when partial
+        // streaming is OFF (otherwise the stream_event deltas already did, and
+        // re-emitting would duplicate the reasoning).
+        if (!partial) {
+          for (const b of content) {
+            if (b?.type === 'thinking' && typeof b.thinking === 'string' && b.thinking) {
+              onThinkingDelta?.(b.thinking);
+            }
+          }
+        }
         const messageText = content
           .filter(b => b?.type === 'text' && typeof b.text === 'string')
           .map(b => b.text)
@@ -59,7 +115,10 @@ function makeStreamJsonParser({ agentId, agentName, onText, onToolStart, onToolR
         if (messageText) onText?.(messageText, { isFinal: !hasToolUse });
         for (const block of content) {
           if (block?.type === 'tool_use') {
-            if (block.id) toolNameById.set(block.id, block.name || 'tool');
+            if (block.id) {
+              toolNameById.set(block.id, block.name || 'tool');
+              toolStartedAt.set(block.id, Date.now());
+            }
             onToolStart?.({ id: block.id, name: block.name || 'tool', input: block.input });
             if (agentId) {
               publishLiveEvent({
@@ -76,7 +135,18 @@ function makeStreamJsonParser({ agentId, agentName, onText, onToolStart, onToolR
         for (const block of content) {
           if (block?.type === 'tool_result') {
             const toolName = toolNameById.get(block.tool_use_id) || 'tool';
-            onToolResult?.({ tool_use_id: block.tool_use_id, name: toolName, isError: Boolean(block.is_error) });
+            const startedAt = toolStartedAt.get(block.tool_use_id);
+            const durationMs = startedAt ? Date.now() - startedAt : null;
+            const { preview, chars, lines } = previewToolResultContent(block);
+            onToolResult?.({
+              tool_use_id: block.tool_use_id,
+              name: toolName,
+              isError: Boolean(block.is_error),
+              durationMs,
+              preview,
+              chars,
+              lines,
+            });
             if (agentId) {
               publishLiveEvent({
                 type: 'agent_tool_result',
@@ -85,9 +155,11 @@ function makeStreamJsonParser({ agentId, agentName, onText, onToolStart, onToolR
                 tool: toolName,
                 status: block.is_error ? 'error' : 'done',
                 isError: Boolean(block.is_error),
+                duration_ms: durationMs,
               });
             }
             toolNameById.delete(block.tool_use_id);
+            toolStartedAt.delete(block.tool_use_id);
           }
         }
       }
@@ -292,6 +364,30 @@ export async function commandExists(command) {
   });
 }
 
+// Whether the installed `claude` CLI understands --include-partial-messages
+// (needed for token-by-token streaming + thinking deltas). Older CLIs reject
+// unknown flags and fail the whole spawn, so we probe `claude --help` once and
+// cache the result, degrading gracefully to chunked streaming when absent.
+// Force with MADARX_CC_FORCE_PARTIAL=1, disable with =0.
+let _ccPartialSupport;
+async function claudeSupportsPartialMessages() {
+  if (process.env.MADARX_MOCK_CLAUDE_CODE_RESPONSE) return false;
+  if (process.env.MADARX_CC_FORCE_PARTIAL === '1') return true;
+  if (process.env.MADARX_CC_FORCE_PARTIAL === '0') return false;
+  if (_ccPartialSupport !== undefined) return _ccPartialSupport;
+  _ccPartialSupport = await new Promise(resolve => {
+    try {
+      const child = spawn(commandSpawnTarget('claude'), ['--help'], { shell: false });
+      let out = '';
+      child.stdout.on('data', c => { out += c.toString(); });
+      child.stderr.on('data', c => { out += c.toString(); });
+      child.on('error', () => resolve(false));
+      child.on('close', () => resolve(out.includes('include-partial-messages')));
+    } catch { resolve(false); }
+  });
+  return _ccPartialSupport;
+}
+
 async function listOllamaModels() {
   try {
     const response = await fetch(`${OLLAMA_BASE_URL}/api/tags`, { signal: AbortSignal.timeout(1500) });
@@ -384,32 +480,73 @@ function cliOutput(command, args, { cwd = process.cwd(), timeoutMs = 120000, clo
   });
 }
 
-export async function runOllamaAgent({ model, systemPrompt, userMessage, maxTokens = 2048 }) {
+export async function runOllamaAgent({ model, systemPrompt, userMessage, maxTokens = 2048, onChunk, onThinking } = {}) {
   if (process.env.MADARX_MOCK_OLLAMA_RESPONSE) return process.env.MADARX_MOCK_OLLAMA_RESPONSE;
+  // Stream only when a consumer wants live output. `think` surfaces reasoning on
+  // models that support it (deepseek-r1, qwen3, …) but errors on some Ollama
+  // versions/models, so it's opt-in via MADARX_OLLAMA_THINK=1.
+  const wantStream = Boolean(onChunk || onThinking);
+  const wantThink = wantStream && verbosityStreamsThinking() && process.env.MADARX_OLLAMA_THINK === '1';
+  const body = {
+    model: model || process.env.OLLAMA_MODEL,
+    stream: wantStream,
+    options: { num_predict: maxTokens },
+    messages: [
+      { role: 'system', content: systemPrompt },
+      { role: 'user', content: userMessage },
+    ],
+  };
+  if (wantThink) body.think = true;
   const response = await fetch(`${OLLAMA_BASE_URL}/api/chat`, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({
-      model: model || process.env.OLLAMA_MODEL,
-      stream: false,
-      options: { num_predict: maxTokens },
-      messages: [
-        { role: 'system', content: systemPrompt },
-        { role: 'user', content: userMessage },
-      ],
-    }),
+    body: JSON.stringify(body),
   });
   if (!response.ok) throw new Error(`Ollama chat failed: HTTP ${response.status}`);
-  const data = await response.json();
-  const content = data.message?.content || data.response || '';
+  if (!wantStream) {
+    const data = await response.json();
+    const content = data.message?.content || data.response || '';
+    if (!content.trim()) throw new Error('Ollama returned no text');
+    return content.trim();
+  }
+  // Streaming: Ollama emits newline-delimited JSON. Accumulate content + thinking
+  // and forward incremental pieces to the callbacks for a live chat preview.
+  let content = '';
+  let thinking = '';
+  const reader = response.body.getReader();
+  const dec = new TextDecoder();
+  let buf = '';
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    buf += dec.decode(value, { stream: true });
+    let nl;
+    while ((nl = buf.indexOf('\n')) >= 0) {
+      const line = buf.slice(0, nl).trim();
+      buf = buf.slice(nl + 1);
+      if (!line) continue;
+      let evt;
+      try { evt = JSON.parse(line); } catch { continue; }
+      const piece = evt.message?.content || evt.response || '';
+      const think = evt.message?.thinking || '';
+      if (piece) { content += piece; onChunk?.(piece, content); }
+      if (think) { thinking += think; onThinking?.(thinking, think); }
+    }
+  }
   if (!content.trim()) throw new Error('Ollama returned no text');
   return content.trim();
 }
 
-export async function runClaudeCodeAgent({ model, systemPrompt, userMessage, maxTurns, allowedTools = [], timeoutMs, onChunk, onAssistantText, onToolStart, onToolResult, cwd, addDirs = [], agentId, agentName } = {}) {
+export async function runClaudeCodeAgent({ model, systemPrompt, userMessage, maxTurns, allowedTools = [], timeoutMs, onChunk, onAssistantText, onThinking, onStatus, onToolStart, onToolResult, cwd, addDirs = [], agentId, agentName, verbosity } = {}) {
   if (process.env.MADARX_MOCK_CLAUDE_CODE_RESPONSE) return process.env.MADARX_MOCK_CLAUDE_CODE_RESPONSE;
   const prompt = `${systemPrompt}\n\n${userMessage}`;
   const effectiveMaxTurns = Number(maxTurns || process.env.CLAUDE_CODE_MAX_TURNS || 30);
+  const v = verbosity || getStreamVerbosity();
+  const wantsThinking = verbosityStreamsThinking(v);
+  // Token-by-token streaming + reasoning need --include-partial-messages, which
+  // only newer CLIs support. Probe once; fall back to chunked complete-message
+  // streaming when unavailable so nothing breaks on older installs.
+  const partial = wantsThinking && await claudeSupportsPartialMessages();
   const args = [
     '-p', prompt,
     '--max-turns', String(effectiveMaxTurns),
@@ -418,12 +555,21 @@ export async function runClaudeCodeAgent({ model, systemPrompt, userMessage, max
     '--permission-mode', 'bypassPermissions',
     '--setting-sources', 'project,local,user',
   ];
+  if (partial) args.push('--include-partial-messages');
   for (const dir of addDirs) {
     if (dir) args.push('--add-dir', dir);
   }
   if (allowedTools.length) args.push('--allowedTools', allowedTools.join(','));
   if (model && model !== 'claude-code') args.splice(2, 0, '--model', model);
 
+  // Best-effort nudge for the spawned CLI to actually produce extended thinking.
+  // Harmless when unsupported (the env var is simply ignored).
+  const subEnv = claudeSubprocessEnv();
+  if (wantsThinking) {
+    const budget = thinkingBudgetTokens(v);
+    if (budget > 0) subEnv.MAX_THINKING_TOKENS = String(Math.max(1024, budget));
+  }
+
   // Two buffers: `narrationParts` keeps every assistant text block (used only
   // for the live chat preview), `finalParts` keeps text from messages that had
   // NO tool_use — i.e. the actual answer, not the "let me search next…" prose.
@@ -433,17 +579,32 @@ export async function runClaudeCodeAgent({ model, systemPrompt, userMessage, max
   const finalParts = [];
   let lastNarration = '';
   let resultText = '';
+  // Live preview accumulators for partial mode. `liveDelta` is the running
+  // answer text (token deltas); `liveThinking` is the running reasoning. They
+  // never feed the returned answer — only the live chat surface.
+  let liveDelta = '';
+  let liveThinking = '';
   const parse = makeStreamJsonParser({
     agentId,
     agentName,
+    partial,
     onText: (t, opts = {}) => {
       narrationParts.push(t);
       if (opts.isFinal) finalParts.push(t);
       else lastNarration = t;
-      // Snapshot of running assistant prose so the route can stream a clean
-      // preview to the chat without exposing raw stream-json envelopes.
-      onAssistantText?.(narrationParts.join('').trim());
+      // When partial deltas are streaming the preview, the complete envelope is
+      // authoritative-only — don't also drive the preview from it (would double).
+      if (!partial) onAssistantText?.(narrationParts.join('').trim());
+    },
+    onTextDelta: (delta) => {
+      liveDelta += delta;
+      onAssistantText?.(liveDelta.trim());
+    },
+    onThinkingDelta: (delta) => {
+      liveThinking += delta;
+      onThinking?.(liveThinking.trim(), delta);
     },
+    onStatus: (phase) => { onStatus?.(phase); },
     onResult: (t) => { resultText = t; },
     onToolStart,
     onToolResult,
@@ -461,7 +622,7 @@ export async function runClaudeCodeAgent({ model, systemPrompt, userMessage, max
     // local CLI engine. Strip them so CC uses the logged-in subscription.
     // Honor an explicit opt-out for users who genuinely want API-key billing
     // for the spawned CLI (MADARX_CLI_USE_API_KEY=1).
-    env: claudeSubprocessEnv(),
+    env: subEnv,
     onChunk: (chunk) => {
       parse(chunk);
       onChunk?.(chunk);

package/lib/auth-config.js

@@ -74,26 +74,42 @@ export function verifyRecoveryToken(provided) {
 
 function envMode() {
   const raw = process.env.MADARX_AUTH_MODE;
-  if (raw && String(raw).trim()) return String(raw).trim().toLowerCase();
+  if (raw && String(raw).trim()) {
+    const m = String(raw).trim().toLowerCase();
+    if (VALID_MODES.has(m)) return m;
+  }
   return null;
 }
 
-/** True when MADARX_AUTH_MODE is explicitly set — the UI cannot override it. */
+/**
+ * True ONLY when the operator opts into a hard lock via MADARX_AUTH_MODE_LOCK=1
+ * (alongside a valid MADARX_AUTH_MODE). In that state the UI / recovery flow
+ * cannot change the mode — for multi-tenant deployments that must fail closed.
+ *
+ * A bare `MADARX_AUTH_MODE` is NOT a lock: it only seeds the initial default the
+ * UI can still override. This is deliberate — a stray `MADARX_AUTH_MODE=supabase`
+ * with no resolvable credentials must never strand the operator behind a login
+ * that can't initialise, because the config-table mode (written by the login
+ * screen and the recovery-token hatch) always wins over the env seed.
+ */
 export function isAuthModeEnvLocked() {
-  const m = envMode();
-  return Boolean(m && VALID_MODES.has(m));
+  const lock = String(process.env.MADARX_AUTH_MODE_LOCK || '').trim().toLowerCase();
+  return Boolean(envMode() && (lock === '1' || lock === 'true'));
 }
 
 export function getAuthMode() {
-  const override = envMode();
-  if (override && VALID_MODES.has(override)) return override;
+  // Hard lock (opt-in): env wins outright, UI cannot override.
+  if (isAuthModeEnvLocked()) return envMode();
+  // Normal precedence: the config table (UI/recovery-managed) wins, so the
+  // login screen and the recovery-token hatch can always change the mode.
   try {
     const stored = getConfig(AUTH_MODE_KEY, null);
     if (stored && VALID_MODES.has(stored)) return stored;
   } catch {
-    // DB not ready (very early boot) — fall through to the safe default.
+    // DB not ready (very early boot) — fall through to the env seed / default.
   }
-  return 'local';
+  // No stored mode yet → env acts as the initial default (seed), else local.
+  return envMode() || 'local';
 }
 
 export function getSupabaseAuthConfig() {

package/lib/claude.js

@@ -76,15 +76,32 @@ export async function chatWithClaude(messages, systemPrompt, tools = [], options
   return withRetry(() => client.messages.create(params), `chat(${params.model})`);
 }
 
-export async function streamChatWithClaude(messages, systemPrompt, tools = [], model = MODEL) {
+// Extended thinking is supported on Claude 3.7+ Sonnet and the Claude 4 family.
+// Enabling it on an older model (e.g. 3.5 Haiku/Sonnet) is a 400 — so we
+// allowlist and silently skip otherwise rather than break the turn.
+export function modelSupportsThinking(model) {
+  return /(sonnet-4|opus-4|haiku-4|3-7-sonnet)/i.test(String(model || ''));
+}
+
+export async function streamChatWithClaude(messages, systemPrompt, tools = [], model = MODEL, options = {}) {
   const client = getClient();
   const params = {
     model,
-    max_tokens: 8192,
+    max_tokens: options.max_tokens || 8192,
     system: systemPrompt,
     messages,
   };
   if (tools.length) params.tools = tools;
+  // Extended thinking: when a budget is requested AND the model supports it,
+  // enable interleaved reasoning so the route can stream `thinking` deltas.
+  // max_tokens must exceed the thinking budget — leave generous headroom for
+  // the actual answer (HTML artifacts can be large). temperature must be unset
+  // with thinking, so we never pass it here.
+  if (options.thinkingBudget > 0 && modelSupportsThinking(model)) {
+    const budget = Math.max(1024, Math.floor(options.thinkingBudget));
+    params.thinking = { type: 'enabled', budget_tokens: budget };
+    params.max_tokens = Math.max(params.max_tokens, budget + 8192);
+  }
   // Stream cannot be resumed mid-flight; outer retry only covers establishing
   // the stream (connection/429 before the first token), not a mid-stream drop.
   return withRetry(() => client.messages.stream(params), `stream(${model})`);

package/lib/cli/doctor.js

@@ -60,6 +60,30 @@ function checkMasterKey(layout) {
   };
 }
 
+// Catches the "team mode set but no credentials" lockout BEFORE boot. Soft +
+// env-only (doctor never opens the DB), so it can't see vault-stored keys — the
+// message is hedged accordingly. Precedence here mirrors getSupabaseAuthConfig:
+// process.env → env file, with NEXT_PUBLIC_* aliases honored.
+function checkAuthConfig(layout) {
+  const env = readEnvFile(layout.envFile);
+  const pick = (k) => process.env[k] || env[k] || '';
+  const mode = (pick('MADARX_AUTH_MODE') || '').trim().toLowerCase();
+  if (mode !== 'supabase') {
+    return { name: 'Auth config', ok: true, hard: false, detail: mode ? `mode=${mode}` : 'mode=local (default)' };
+  }
+  const url = pick('SUPABASE_URL') || pick('NEXT_PUBLIC_SUPABASE_URL');
+  const anon = pick('SUPABASE_ANON_KEY') || pick('NEXT_PUBLIC_SUPABASE_ANON_KEY');
+  if (url && anon) {
+    return { name: 'Auth config', ok: true, hard: false, detail: 'team mode + Supabase keys present' };
+  }
+  return {
+    name: 'Auth config',
+    ok: false,
+    hard: false,
+    detail: 'team mode set but no SUPABASE_URL/ANON_KEY in env — if they are not in the vault, login will fail. Configure on the login screen or run `madarx setup`.',
+  };
+}
+
 function checkStandalone() {
   const p = path.join(PKG_ROOT, '.next', 'standalone', 'server.js');
   const ok = fs.existsSync(p);
@@ -100,6 +124,7 @@ export async function runDoctor() {
     await checkSqlite(),
     checkHomeWritable(layout),
     checkMasterKey(layout),
+    checkAuthConfig(layout),
     checkStandalone(),
     checkWhatsAppDeps(),
     await checkPort(),

package/lib/connection-seeds.js

@@ -207,7 +207,7 @@ const CONNECTION_SEEDS = [
           type: 'password',
           placeholder: 'ghp_…',
           help_url: 'https://github.com/settings/tokens',
-          help_text: 'Use a fine-grained token. Grant only the scopes you need.',
+          help_text: 'To read repos beyond your own, the token must be granted access to them. Fine-grained PAT: under "Repository access" pick the orgs/repos (org owner may need to approve); classic PAT: enable the "repo" scope and, for SSO orgs, click "Authorize" / "Configure SSO" next to the token.',
           required: true,
         },
       ],

package/lib/engine-verbosity.js

@@ -0,0 +1,42 @@
+// Shared streaming-verbosity + extended-thinking config for sub-agent engines.
+//
+// One knob controls how much of an engine's work madarX surfaces live in the
+// chat. It applies engine-agnostically: the Claude Code CLI, the Anthropic
+// Messages API, and (best-effort) Ollama all read the same setting.
+//
+//   MADARX_CC_STREAM_VERBOSITY = 'quiet' | 'thinking' | 'full'   (default 'thinking')
+//     quiet    — legacy behavior: only complete assistant text + tool start/stop.
+//     thinking — stream token-by-token text, the model's reasoning, and rich
+//                tool detail (full input + output preview + duration).
+//     full     — everything in `thinking`, plus raw engine envelopes routed to
+//                the client's "engine log" disclosure for deep debugging.
+//
+// The name keeps the `CC_` prefix for backwards compatibility with the first
+// Claude-Code-only iteration; it now governs every engine.
+
+const VALID = new Set(['quiet', 'thinking', 'full']);
+
+export function getStreamVerbosity() {
+  const v = String(process.env.MADARX_CC_STREAM_VERBOSITY || 'thinking').trim().toLowerCase();
+  return VALID.has(v) ? v : 'thinking';
+}
+
+export function verbosityStreamsThinking(v = getStreamVerbosity()) {
+  return v === 'thinking' || v === 'full';
+}
+
+export function verbosityIsFull(v = getStreamVerbosity()) {
+  return v === 'full';
+}
+
+// Extended-thinking budget in tokens for engines where we control the request
+// (Anthropic Messages API directly; the spawned Claude Code CLI via the
+// MAX_THINKING_TOKENS env var, best-effort). 0 disables thinking. Anthropic
+// requires a floor of 1024 when enabled — callers clamp up to that. Default
+// 4000; override with MADARX_THINKING_BUDGET_TOKENS.
+export function thinkingBudgetTokens(v = getStreamVerbosity()) {
+  if (!verbosityStreamsThinking(v)) return 0;
+  const raw = Number(process.env.MADARX_THINKING_BUDGET_TOKENS);
+  if (Number.isFinite(raw) && raw >= 0) return Math.floor(raw);
+  return 4000;
+}

package/lib/env-file.js

@@ -20,6 +20,9 @@ export const ENV_DEFINITIONS = [
   // secrets vault, not here.
   { name: 'MADARX_WEB_PROVIDER', label: 'Web Provider Override', group: 'Web', description: 'Force a specific search provider: firecrawl, searxng, brave, or fetch.' },
 
+  // --- Browser tool config ---
+  { name: 'MADARX_BROWSER_HEADED', label: 'Visible Browser (headed)', group: 'Browser', description: 'Set to 1 to open a VISIBLE browser window you can watch the agent drive (click/type). Prefers your installed Chrome, falls back to bundled Chromium. Leave blank or 0 for headless. Applies on the next browser launch.' },
+
   // --- File tool config ---
   { name: 'MADARX_ALLOWED_ROOTS', label: 'Allowed File Roots', group: 'Local Tools', description: 'Colon-separated absolute paths the file adapter may read/write.' },
   { name: 'MADARX_FILE_READ_MAX_BYTES', label: 'Max File Read Bytes', group: 'Local Tools', description: 'Maximum bytes returned by a single file_read call (default: 1MB).' },

package/lib/pick-folder-authz.js

@@ -0,0 +1,15 @@
+import { requireRole } from './authz.js';
+
+// Authorization for the native folder picker (/api/fs/pick-folder).
+//
+// Plain folder selection is a benign local helper: it opens a native OS dialog
+// and returns the chosen path string, which only fills a form field — it grants
+// no access on its own (project creation and the disk layer enforce allowed
+// roots). So ANY authenticated user may use it; gating it on the org `admin`
+// role wrongly 403s a member/viewer with `insufficient_role`.
+//
+// Registering a Mines import root, by contrast, grants agents access to that
+// root, so that branch stays admin-gated.
+export function assertPickFolderRole(session, registerImportRoot) {
+  if (registerImportRoot) requireRole(session, 'admin', session?.org_id);
+}

package/lib/realtime-openai.js

@@ -28,6 +28,17 @@ export function realtimeConfigured() {
   return Boolean(getSecret('OPENAI_API_KEY') || process.env.OPENAI_API_KEY);
 }
 
+// Transport-only instruction block. In this mode the Realtime model is a
+// dumb microphone+transcriber: it must NOT reason, answer, or call tools.
+// All cognition runs through the main orchestrator stream (same brain as typed
+// chat); the Realtime model only converts speech → text. Output is suppressed
+// server-side via turn_detection.create_response:false, but we also instruct
+// the model explicitly as a belt-and-suspenders guard.
+const TRANSPORT_INSTRUCTIONS =
+  'You are a transcription microphone only. Do NOT respond, answer, comment, '
+  + 'or call any tool. Never speak. Your sole job is to let the system capture '
+  + 'the user\'s spoken words as text. Stay silent at all times.';
+
 export async function mintOpenAIRealtimeSession(opts = {}) {
   const apiKey = getSecret('OPENAI_API_KEY') || process.env.OPENAI_API_KEY;
   if (!apiKey) throw new Error('OPENAI_API_KEY missing for OpenAI Realtime');
@@ -35,12 +46,24 @@ export async function mintOpenAIRealtimeSession(opts = {}) {
   const model = String(opts.model || getSecret('OPENAI_REALTIME_MODEL') || process.env.OPENAI_REALTIME_MODEL || DEFAULT_REALTIME_MODEL);
   const voice = safeVoice(opts.voice || getSecret('OPENAI_REALTIME_VOICE') || process.env.OPENAI_REALTIME_VOICE);
 
+  // Transport mode: Realtime is STT-only. The orchestrator (Claude) is the
+  // brain; the TTS lane is the mouth. Force no tools + transcribe-only
+  // instructions and suppress the model's auto-response. This is the default
+  // for the unified voice=main-agent path; pass mode:'realtime' to fall back
+  // to the legacy in-browser-brain behaviour.
+  const transport = opts.mode === 'transport';
+
   // Build the durable Madarx instruction block from project + memory + state
   // unless the caller passed an override. Tools default to the curated voice
   // catalog; callers can pass a custom list (e.g. [] to disable tool calling).
   let instructions = String(opts.instructions || '').trim();
   let tools = Array.isArray(opts.tools) ? opts.tools : null;
-  if (!instructions || !tools) {
+  if (transport) {
+    // Transport mode never reasons or acts — ignore any caller-supplied tools
+    // and context, and pin the transcribe-only instruction block.
+    instructions = TRANSPORT_INSTRUCTIONS;
+    tools = [];
+  } else if (!instructions || !tools) {
     const ctx = buildVoiceContext({
       project_id: opts.project_id,
       agent_id: opts.agent_id,
@@ -66,6 +89,31 @@ export async function mintOpenAIRealtimeSession(opts = {}) {
     instructions,
     audio: { output: { voice } },
   };
+  if (transport) {
+    // Enable input transcription so we receive
+    // conversation.item.input_audio_transcription.completed events, and turn
+    // OFF automatic response generation so the Realtime model stays silent —
+    // the orchestrator produces the answer instead.
+    session.audio.input = {
+      transcription: { model: 'gpt-4o-mini-transcribe' },
+      turn_detection: { type: 'server_vad', create_response: false, interrupt_response: false },
+    };
+    session.output_modalities = ['text'];
+  }
+  // Reasoning effort is the biggest latency dial on gpt-realtime-2: lower =
+  // snappier first audio. session.reasoning.effort accepts minimal|low|medium|
+  // high; 'low' is OpenAI's recommended default for production voice agents.
+  // Guard on the model name so older realtime models (which reject the field)
+  // do not fail the mint.
+  if (/realtime-2/.test(model)) {
+    const effort = String(
+      opts.reasoning_effort
+      || getSecret('OPENAI_REALTIME_REASONING')
+      || process.env.OPENAI_REALTIME_REASONING
+      || 'low',
+    );
+    session.reasoning = { effort };
+  }
   if (Array.isArray(tools) && tools.length) session.tools = tools;
   const body = { session };