madarx 2.16.3 → 2.18.0

package/lib/auth.js

@@ -26,14 +26,26 @@ export { getAuthMode, getSupabaseAuthConfig, getSupabaseServiceKey } from './aut
 
 const IS_NEXT_PRODUCTION_BUILD = process.env.NEXT_PHASE === 'phase-production-build';
 
-// Deploy-time guard keys off the explicit env value only (the DB may not be
-// open at module load, and the env override is the production source of truth).
-if (
-  (process.env.MADARX_AUTH_MODE || 'local').toLowerCase() === 'local' &&
-  process.env.NODE_ENV === 'production' &&
-  !IS_NEXT_PRODUCTION_BUILD
-) {
-  console.error('[auth] WARNING: MADARX_AUTH_MODE is not set to supabase in NODE_ENV=production. Configure Supabase auth (Settings → Account) or set MADARX_AUTH_MODE=supabase before exposing this deployment.');
+// Deploy-time guard. Deferred to first session resolution (not module load) so
+// it can consult the EFFECTIVE auth mode via getAuthMode() — which resolves the
+// env override AND the UI-persisted DB config. Checking the env var alone at
+// module load false-alarms whenever Supabase was configured from Settings → the
+// DB isn't open yet at import time, so the env looked 'local' even though the
+// running mode is 'supabase'. One-shot.
+let _authModeWarned = false;
+function warnIfUnsafeAuthModeOnce() {
+  if (_authModeWarned) return;
+  _authModeWarned = true;
+  if (IS_NEXT_PRODUCTION_BUILD || process.env.NODE_ENV !== 'production') return;
+  let mode;
+  try {
+    mode = getAuthMode(); // env override → DB config → 'local'
+  } catch {
+    mode = (process.env.MADARX_AUTH_MODE || 'local').toLowerCase();
+  }
+  if (mode === 'local') {
+    console.error('[auth] WARNING: auth mode is local in NODE_ENV=production. Configure Supabase auth (Settings → Account) or set MADARX_AUTH_MODE=supabase before exposing this deployment.');
+  }
 }
 
 // ── Local dev synthetic user ──────────────────────────────────────────────────
@@ -329,6 +341,7 @@ function _upsertUserRow(sbUser) {
  * - supabase mode: reads Supabase session cookie; returns null if unauthenticated.
  */
 export async function getSession(req, { _client } = {}) {
+  warnIfUnsafeAuthModeOnce();
   if (getAuthMode() === 'local') {
     return getLocalDevUser();
   }

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/heartbeat-worker.js

@@ -132,7 +132,11 @@ async function executeTask(task) {
     });
   }
   return runAgentTick(payload.agent_id || task.agent_id, {
-    triggered_by: 'heartbeat-worker',
+    // Honor the enqueuer's provenance (e.g. a manual run from the dashboard sets
+    // triggered_by:'manual') so the recorded run + audit reflect why it ran,
+    // instead of flattening every queued tick to 'heartbeat-worker'.
+    triggered_by: payload.triggered_by || 'heartbeat-worker',
+    wake_reason: payload.reason || null,
     acting_on_behalf_of_user_id: actingUserId,
     heartbeat_task_id: task.id,
   });

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 };
 

package/lib/tools/adapters/browser-session.js

@@ -1,10 +1,15 @@
 /**
  * browser-session.js — native Playwright browser-interaction adapter.
  *
- * Drives a real headless Chromium so the main agent can navigate, click, type,
- * read, and screenshot pages that need JavaScript (unlike browser_navigate,
- * which is fetch + regex only). One managed persistent context is shared across
- * calls and auto-closed after an idle window so we never leak browser processes.
+ * Drives a real Chromium so the main agent can navigate, click, type, read, and
+ * screenshot pages that need JavaScript (unlike browser_navigate, which is
+ * fetch + regex only). One managed persistent context is shared across calls and
+ * auto-closed after an idle window so we never leak browser processes.
+ *
+ * Headless by default. Set MADARX_BROWSER_HEADED=1 (or true/yes/on) to open a
+ * VISIBLE window the operator can watch — it prefers the installed Chrome
+ * (channel:'chrome'), falling back to bundled Chromium. The idle auto-close
+ * (90s) still applies, so a visible window left untouched closes on its own.
  *
  * Safety posture:
  *  - Dedicated profile under DATA_DIR/browser-profile — NOT the user's personal
@@ -45,6 +50,33 @@ function cap(text) {
   return redactToolOutput(String(text ?? '').slice(0, MAX_TEXT_CHARS));
 }
 
+// Headed mode lets the operator watch the agent drive a real, visible browser.
+// Off by default so headless servers and CI stay unattended. When on, prefer the
+// operator's installed Chrome (channel:'chrome') so it looks/behaves like a real
+// browser; we transparently fall back to bundled Chromium if that channel is
+// unavailable. The persistent profile (PROFILE_DIR) is still the dedicated
+// madarX profile, never the user's personal Chrome data.
+function isHeaded() {
+  const v = String(process.env.MADARX_BROWSER_HEADED || '').trim().toLowerCase();
+  return v === '1' || v === 'true' || v === 'yes' || v === 'on';
+}
+
+async function launchContext(chromium) {
+  const headed = isHeaded();
+  const base = {
+    headless: !headed,
+    args: ['--no-sandbox', '--disable-dev-shm-usage'],
+  };
+  if (headed) {
+    try {
+      return await chromium.launchPersistentContext(PROFILE_DIR, { ...base, channel: 'chrome' });
+    } catch {
+      // Installed Chrome not found — fall back to bundled Chromium, still headed.
+    }
+  }
+  return await chromium.launchPersistentContext(PROFILE_DIR, base);
+}
+
 function touchIdleTimer() {
   if (_idleTimer) clearTimeout(_idleTimer);
   _idleTimer = setTimeout(() => { closeBrowser().catch(() => {}); }, IDLE_CLOSE_MS);
@@ -75,10 +107,7 @@ async function ensurePage() {
   }
   fs.mkdirSync(PROFILE_DIR, { recursive: true });
   try {
-    _context = await chromium.launchPersistentContext(PROFILE_DIR, {
-      headless: true,
-      args: ['--no-sandbox', '--disable-dev-shm-usage'],
-    });
+    _context = await launchContext(chromium);
   } catch (err) {
     _context = null;
     throw new Error(

package/lib/tools/adapters/github.js

@@ -65,12 +65,30 @@ function parseOwnerRepo(repo_full_name) {
 // ── Error extraction ──────────────────────────────────────────────────────────
 
 async function extractGitHubError(res) {
+  let message = `GitHub API error: ${res.status}`;
   try {
     const data = await res.json();
-    return data?.message || `GitHub API error: ${res.status}`;
+    if (data?.message) message = data.message;
   } catch {
-    return `GitHub API error: ${res.status}`;
+    // non-JSON body — keep the status-based message
   }
+
+  // Actionable guidance for the two access failures users actually hit.
+  // SAML SSO: the org requires the token to be explicitly authorized. GitHub
+  // signals this via the x-github-sso response header.
+  const sso = res.headers?.get?.('x-github-sso');
+  if (res.status === 403 && sso) {
+    const urlMatch = /url=([^;,\s]+)/i.exec(sso);
+    const where = urlMatch ? ` Authorize it here: ${urlMatch[1]}` : '';
+    return `${message} — this org requires SAML SSO authorization for your token.${where}`;
+  }
+  if (res.status === 403) {
+    return `${message} — the token is valid but lacks permission for this resource (check the fine-grained PAT's repository access / scopes, and authorize SSO if the org uses it).`;
+  }
+  if (res.status === 404) {
+    return `${message} — not found, OR your token cannot see it. A fine-grained PAT only sees repos it was explicitly granted; a classic PAT needs the 'repo' scope. Grant access to this repo/org and retry.`;
+  }
+  return message;
 }
 
 // ── Response shapers ──────────────────────────────────────────────────────────
@@ -146,12 +164,36 @@ export async function ghRepoList(input = {}, options = {}) {
   const token = requireCredential('GITHUB_TOKEN', options);
   const agentId = options.agent_id ?? null;
 
-  const url = new URL(`${GH_API}/user/repos`);
-  if (input.visibility) url.searchParams.set('visibility', String(input.visibility));
-  if (input.type) url.searchParams.set('type', String(input.type));
+  // Two listing modes:
+  //  - `org` set → GET /orgs/{org}/repos (repos owned by that org the token can
+  //    see). This is how you reach org repos you were granted access to.
+  //  - otherwise → GET /user/repos across every affiliation the token has, so
+  //    collaborator + organization_member repos show up, not just owned ones.
+  const org = input.org ? String(input.org).trim() : '';
+  let url;
+  if (org) {
+    if (!/^[A-Za-z0-9_.-]+$/.test(org)) {
+      throw new Error(`org must be a valid GitHub org/owner name, got: ${org}`);
+    }
+    url = new URL(`${GH_API}/orgs/${org}/repos`);
+    if (input.type) url.searchParams.set('type', String(input.type)); // all|public|private|forks|sources|member
+  } else {
+    url = new URL(`${GH_API}/user/repos`);
+    // Default to the full affiliation set so org/collaborator repos are listed.
+    url.searchParams.set('affiliation', String(input.affiliation || 'owner,collaborator,organization_member'));
+    if (input.visibility) url.searchParams.set('visibility', String(input.visibility));
+    // `type` and `affiliation` are mutually exclusive on /user/repos — only send
+    // `type` when the caller did not narrow by affiliation themselves.
+    if (input.type && !input.affiliation) {
+      url.searchParams.delete('affiliation');
+      url.searchParams.set('type', String(input.type));
+    }
+  }
   if (input.sort) url.searchParams.set('sort', String(input.sort));
   const perPage = Math.min(Math.max(Number(input.per_page || 30), 1), 100);
   url.searchParams.set('per_page', String(perPage));
+  const page = Math.max(Number(input.page || 1), 1);
+  if (page > 1) url.searchParams.set('page', String(page));
 
   const res = await wrapFetch('gh_repo_list', agentId)(url, {
     headers: githubHeaders(token),

package/lib/tools/adapters/skill-bridge.js

@@ -0,0 +1,146 @@
+// Skill bridge — Phase 4 of voice/main-agent unification.
+//
+// Exposes a tightly-allowlisted set of first-party gstack CLI skills (the
+// visible-browser flows: /connect-chrome, /browse, /qa-only) as ONE in-app
+// tool. The main agent (and, by extension, voice — which now shares the full
+// catalog) can drive the same real browser the operator watches live.
+//
+// SECURITY — this crosses the Claude Code CLI trust boundary, so it is the most
+// sharply gated tool in the registry:
+//   • risk_level 'irreversible_external' → the main-agent path ALWAYS creates an
+//     approval request, even in trust-mode 'auto' (never bypassable).
+//   • registry.js force-gates it on the AGENT path too (added alongside
+//     browser_harness_run), so a sub-agent on auto can never self-run it.
+//   • enabled_default:false → the owner must explicitly install it first.
+//   • Hard env kill-switch MADARX_SKILL_BRIDGE_DISABLED=1.
+//   • Only skills on SKILL_BRIDGE_ALLOWLIST may be invoked — the LLM cannot
+//     name an arbitrary skill or shell command. The instruction is passed as
+//     data, never interpolated into a shell line.
+//   • The spawned CLI still runs under bypassPermissions bounded by the
+//     load-bearing deny list in .claude/settings.json (no rm/sudo/secret reads/
+//     network-from-shell/etc.).
+//
+// These are FIRST-PARTY skills (gstack, shipped with the repo), NOT
+// agent-authored code — so this does not violate the "never load/execute
+// LLM-authored code" invariant. The agent only chooses WHICH allowlisted skill
+// and WHAT instruction; it never supplies the skill body.
+
+import { runClaudeCodeAgent } from '../../agent-engines.js';
+import { DATA_DIR, WORKSPACE } from '../../paths.js';
+import { redactToolOutput } from '../safety.js';
+
+const DEFAULT_TIMEOUT_MS = 180000;
+const MAX_TIMEOUT_MS = 600000;
+const MAX_INSTRUCTION_CHARS = 4000;
+const MAX_SUMMARY_CHARS = 12000;
+const DEFAULT_MAX_TURNS = 25;
+
+// Allowlisted skills the bridge may invoke, keyed by the slug the agent passes.
+// Each entry: how to phrase the invocation + a one-line purpose. Keep this list
+// SHORT and visible-browser-focused; adding an entry widens the trust surface.
+const SKILL_BRIDGE_ALLOWLIST = {
+  'connect-chrome': {
+    purpose: 'Launch the visible GStack Chromium browser the operator can watch live.',
+    invoke: 'connect-chrome',
+  },
+  browse: {
+    purpose: 'Drive a browser to navigate, click, type, read pages, and capture screenshots.',
+    invoke: 'browse',
+  },
+  'qa-only': {
+    purpose: 'Run a QA pass against a running site and report findings (no fixes).',
+    invoke: 'qa-only',
+  },
+};
+
+export function listBridgeableSkills() {
+  return Object.entries(SKILL_BRIDGE_ALLOWLIST).map(([slug, meta]) => ({ slug, purpose: meta.purpose }));
+}
+
+function maxSummaryChars() {
+  const v = Number(process.env.MADARX_TOOL_OUTPUT_MAX_BYTES || MAX_SUMMARY_CHARS);
+  if (!Number.isFinite(v) || v <= 0) return MAX_SUMMARY_CHARS;
+  return Math.min(MAX_SUMMARY_CHARS, Math.floor(v));
+}
+
+function capSummary(text) {
+  return redactToolOutput(String(text || '').slice(0, maxSummaryChars()));
+}
+
+// Sync validation — runs BEFORE the approval/trust gates (PREFLIGHTS map). Throw
+// to reject outright; never reach the model with an off-allowlist skill.
+export function skillBridgeRunPreflight(input = {}) {
+  if (process.env.MADARX_SKILL_BRIDGE_DISABLED === '1') {
+    throw new Error('skill bridge is disabled (MADARX_SKILL_BRIDGE_DISABLED=1)');
+  }
+  const skill = String(input.skill || '').trim().toLowerCase();
+  if (!skill) throw new Error('skill is required');
+  const entry = SKILL_BRIDGE_ALLOWLIST[skill];
+  if (!entry) {
+    throw new Error(`skill "${skill}" is not bridgeable. Allowed: ${Object.keys(SKILL_BRIDGE_ALLOWLIST).join(', ')}`);
+  }
+  const instruction = String(input.instruction || '').trim();
+  if (!instruction) throw new Error('instruction is required');
+  if (instruction.length > MAX_INSTRUCTION_CHARS) {
+    throw new Error(`instruction is too long: ${instruction.length} chars; max ${MAX_INSTRUCTION_CHARS}`);
+  }
+  const timeoutMs = Math.max(
+    5000,
+    Math.min(MAX_TIMEOUT_MS, Number(input.timeout_ms || DEFAULT_TIMEOUT_MS) || DEFAULT_TIMEOUT_MS),
+  );
+  return { skill, entry, instruction, timeoutMs };
+}
+
+function buildSystemPrompt(skill, entry) {
+  return [
+    'You are a single-purpose runner spawned by the madarX main agent.',
+    `Your ONLY job: invoke the /${entry.invoke} skill and carry out the operator instruction with it.`,
+    `Purpose of this skill: ${entry.purpose}`,
+    'Rules:',
+    `- Use ONLY the /${entry.invoke} skill. Do not invoke other skills, write files outside workspace, or run unrelated commands.`,
+    '- Do not read secrets, .env files, or anything the deny list blocks.',
+    '- When done, reply with a concise plain-text summary of what happened and what you observed (URLs visited, key results). No markdown tables.',
+  ].join('\n');
+}
+
+export async function skillBridgeRun(input = {}, options = {}) {
+  const { skill, entry, instruction, timeoutMs } = skillBridgeRunPreflight(input);
+  const started = Date.now();
+
+  const systemPrompt = buildSystemPrompt(skill, entry);
+  const userMessage = `Use the /${entry.invoke} skill to do the following:\n\n${instruction}`;
+
+  try {
+    const text = await runClaudeCodeAgent({
+      systemPrompt,
+      userMessage,
+      maxTurns: DEFAULT_MAX_TURNS,
+      timeoutMs,
+      // Bounded toolset the gstack skills need (browser daemon runs via Bash).
+      // bypassPermissions + the .claude deny list remain the hard boundary.
+      allowedTools: ['Skill', 'Bash', 'Read', 'Write', 'Glob', 'Grep', 'WebFetch', 'WebSearch'],
+      addDirs: [WORKSPACE, DATA_DIR],
+      agentId: options.agent_id || 'main',
+      agentName: 'skill-bridge',
+    });
+
+    const summary = capSummary(text);
+    return {
+      ok: true,
+      tool: 'skill_bridge_run',
+      status: 'complete',
+      skill,
+      summary,
+      duration_ms: Date.now() - started,
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      tool: 'skill_bridge_run',
+      status: 'failed',
+      skill,
+      error: String(err?.message || err).slice(0, 1000),
+      duration_ms: Date.now() - started,
+    };
+  }
+}