@bahulam/code 0.1.24 → 0.1.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bahulam/code",
-  "version": "0.1.24",
+  "version": "0.1.25",
   "description": "Bahulam Code — abundance, in your terminal. CLI-first, reliability-first, sub-agents, 65.6% SWE-bench Verified.",
   "type": "module",
   "bin": {

package/src/commands/install.mjs

@@ -32,6 +32,8 @@ import {
   resolveComposeDependencies,
 } from './plugin-manage.mjs';
 import { preflightPlugin, existingInstalledNames } from '../plugins/preflight.mjs';
+import { runMigrations, runSeed, runPostInstall, purgeData } from '../plugins/lifecycle.mjs';
+import { makePluginState } from '../plugins/state.mjs';
 
 const RESET = '\x1b[0m';
 const BOLD = '\x1b[1m';
@@ -68,6 +70,8 @@ function parseArgs(argv) {
       case '--slug': case '--name': parsed.slug = argv[++i]; break;
       case '--no-state': parsed.state = false; break;
       case '--no-workspace': parsed.workspace = false; break;
+      case '--no-seed': parsed.no_seed = true; break;
+      case '--reseed': parsed.reseed = true; break;
       default:
         if (!arg.startsWith('-')) positional.push(arg);
         break;
@@ -171,6 +175,8 @@ export async function handleInstallCommand(argv, { cwd = process.cwd() } = {}) {
     --slug <name>          Override the scaffolded pack slug (pi sources only)
     --no-state             Skip the persistent state layer (pi sources only)
     --no-workspace         Skip the reactive workspace panel (pi sources only)
+    --no-seed              Skip the lifecycle seed hook on install
+    --reseed               Re-run the seed hook even if it already ran
     --project              Install into ./.bahulam/plugins/ instead of ~/.bahulam/plugins/
     --ref <ref>            Git branch/tag/commit (git or registry sources)
     --json                 Machine-readable output
@@ -417,6 +423,11 @@ async function preflightAndReport({ dest, args, cwd, meta = null }) {
     }
   }
 
+  // Lifecycle — migrations → seed → post_install. Runs after preflight OK.
+  // --force also purges the state dir so a clean reinstall starts from zero;
+  // omit --force to preserve state across reinstalls (common upgrade case).
+  const lifecycleReport = await runLifecycleOnInstall(m, dest, args);
+
   if (args.json) {
     process.stdout.write(JSON.stringify({
       ok: true,
@@ -425,6 +436,7 @@ async function preflightAndReport({ dest, args, cwd, meta = null }) {
       directory: dest,
       scaffolded: Boolean(meta),
       ...(meta ? { pi_package: meta.packageName, namespace: meta.namespace, composed_tools: meta.exposeTools, agent: meta.agentSlug } : {}),
+      lifecycle: lifecycleReport,
     }, null, 2) + '\n');
     return;
   }
@@ -441,9 +453,63 @@ async function preflightAndReport({ dest, args, cwd, meta = null }) {
     process.stderr.write(`  ${DIM}scaffolded${RESET} from ${CYAN}pi:${meta.packageName}${RESET} (namespace ${CYAN}${meta.namespace}${RESET}, ${meta.exposeTools.length} composed tool${meta.exposeTools.length === 1 ? '' : 's'})\n`);
     process.stderr.write(`  ${DIM}Edit the pack under ${dest} to customize.${RESET}\n`);
   }
+  if (lifecycleReport.migrations?.ran || lifecycleReport.seed?.ran || lifecycleReport.post_install?.ran) {
+    const parts = [];
+    if (lifecycleReport.migrations?.ran) parts.push(`migrations: ${lifecycleReport.migrations.ran} applied`);
+    if (lifecycleReport.seed?.ran) parts.push('seed: ran');
+    if (lifecycleReport.post_install?.ran) parts.push('post_install: ran');
+    process.stderr.write(`  ${DIM}lifecycle${RESET} ${parts.join(', ')}\n`);
+  }
   process.stderr.write(`\n  ${DIM}Open with:${RESET} ${CYAN}bahulam plugin ${m.metadata.name}${RESET}\n\n`);
 }
 
+/**
+ * Run migrations → seed → post_install after a successful preflight.
+ * Callers pass `args.force` to also wipe the state dir first (true clean
+ * reinstall) and `args.no_seed` to skip seeding.
+ *
+ * Any lifecycle failure rolls back the plugin directory so the workspace
+ * is not left in a half-installed state — same policy as preflight
+ * rollback above.
+ */
+async function runLifecycleOnInstall(manifest, dest, args) {
+  const lifecycle = manifest.config?.lifecycle || null;
+  if (!lifecycle) return { skipped: true, reason: 'no config.lifecycle declared' };
+  const pluginName = manifest.metadata?.name;
+  if (!pluginName) return { skipped: true, reason: 'manifest missing name' };
+
+  // --force is a true clean reinstall: wipe both the plugin dir (already
+  // done by the installer's --force path) AND the state dir. Without
+  // --force we keep state across reinstalls so an upgrade doesn't
+  // silently discard user data.
+  if (args.force) {
+    const purged = purgeData(pluginName);
+    if (purged.purged) process.stderr.write(`  ${YELLOW}!${RESET} --force: purged state dir ${purged.dir}\n`);
+  }
+
+  const stateFactory = () => makePluginState(pluginName, { tables: manifest.config?.state?.tables || [] });
+  const report = { migrations: null, seed: null, post_install: null };
+  try {
+    report.migrations = await runMigrations({ pluginName, pluginDir: dest, manifest, stateFactory });
+    if (!args.no_seed) {
+      report.seed = await runSeed({
+        pluginName, pluginDir: dest, manifest,
+        args: { force: Boolean(args.reseed || args.force) },
+        stateFactory,
+      });
+    } else {
+      report.seed = { ran: false, reason: '--no-seed flag' };
+    }
+    report.post_install = await runPostInstall({ pluginName, pluginDir: dest, manifest, args, stateFactory });
+  } catch (err) {
+    // Roll back the plugin dir. State was intentionally not touched by us
+    // during the migration failure (snapshot-rollback took care of it).
+    fs.rmSync(dest, { recursive: true, force: true });
+    throw new Error(`lifecycle failed — rolled back ${dest}: ${err.message}`);
+  }
+  return report;
+}
+
 /**
  * Install-time host check: read the ingredient's requirements sidecar,
  * verify each detected binary is on PATH. Throws with an actionable
@@ -480,15 +546,31 @@ async function enforceHostRequirements({ piDir, packageName, args }) {
   }
 
   const host = checkRequirementsAgainstHost(reqs);
+  const optionalByName = new Map((reqs.system_binaries || []).map(b => [b.name, b.optional === true]));
   const missing = host.binaries.filter(b => !b.found);
-  if (missing.length === 0) return;
+  const missingRequired = missing.filter(b => !optionalByName.get(b.name));
+  const missingOptional = missing.filter(b => optionalByName.get(b.name));
+
+  const platformKey = process.platform === 'win32' ? 'win32'
+    : process.platform === 'darwin' ? 'darwin'
+    : 'linux';
+  const hintFor = (b) => b.install_hints?.[platformKey] || b.install_hints?.darwin || b.install_hints?.linux;
+
+  if (missingOptional.length) {
+    process.stderr.write(`${YELLOW}!${RESET} ${packageName} is missing ${missingOptional.length} optional binar${missingOptional.length === 1 ? 'y' : 'ies'} — some features will be disabled:\n`);
+    for (const b of missingOptional) {
+      const hint = hintFor(b);
+      process.stderr.write(`    ${DIM}·${RESET} ${BOLD}${b.name}${RESET}${hint ? ` — install: ${CYAN}${hint}${RESET}` : ''}\n`);
+    }
+  }
+
+  if (missingRequired.length === 0) return;
 
-  const platformKey = process.platform === 'darwin' ? 'darwin' : 'linux';
   const lines = [];
-  lines.push(`${packageName} needs ${missing.length} system binar${missing.length === 1 ? 'y' : 'ies'} not found on your PATH:`);
-  for (const b of missing) {
-    const hint = b.install_hints?.[platformKey];
-    lines.push(`  · ${b.name}${hint ? ` — install: ${CYAN}${hint}${RESET}` : ''}`);
+  lines.push(`${packageName} needs ${missingRequired.length} system binar${missingRequired.length === 1 ? 'y' : 'ies'} not found on your PATH:`);
+  for (const b of missingRequired) {
+    const hint = hintFor(b);
+    lines.push(`  · ${BOLD}${b.name}${RESET}${hint ? ` — install: ${CYAN}${hint}${RESET}` : ''}`);
   }
   if (args.force) {
     process.stderr.write(`${YELLOW}!${RESET} ${lines.join('\n')}\n`);

package/src/commands/plugin-manage.mjs

@@ -26,6 +26,8 @@ import { parsePluginManifestFile } from '../plugins/manifest.mjs';
 import { preflightPlugin, existingInstalledNames } from '../plugins/preflight.mjs';
 import { parsePiSource } from '../plugins/pi-compose.mjs';
 import { bahulamHome, pluginDirs, pluginInstallDir } from '../core/paths.mjs';
+import { runPreUninstall, runMigrations, runPostInstall, runSeed, purgeData, readLifecycleRecord } from '../plugins/lifecycle.mjs';
+import { makePluginState } from '../plugins/state.mjs';
 
 const RESET = '\x1b[0m';
 const BOLD = '\x1b[1m';
@@ -275,6 +277,15 @@ async function surfacePackRequirements(packDir, displayName = null) {
       process.stderr.write(`  ${icon} ${l.text}\n`);
     }
     if (reqs.system_binaries?.length) {
+      const platformKey = process.platform === 'win32' ? 'win32'
+        : process.platform === 'darwin' ? 'darwin'
+        : 'linux';
+      for (const b of reqs.system_binaries) {
+        const hint = b.install_hints?.[platformKey] || b.install_hints?.darwin || b.install_hints?.linux;
+        if (!hint) continue;
+        const tag = b.optional === true ? ` ${DIM}(optional)${RESET}` : '';
+        process.stderr.write(`    ${DIM}·${RESET} ${BOLD}${b.name}${RESET}${tag} — install: ${CYAN}${hint}${RESET}\n`);
+      }
       const name = displayName || path.basename(packDir);
       process.stderr.write(`  ${DIM}run${RESET}  ${CYAN}bahulam plugin doctor ${name}${RESET} ${DIM}to check your environment${RESET}\n`);
     }
@@ -540,16 +551,116 @@ async function cmdList(args, cwd) {
 
 // ── remove ──────────────────────────────────────────────────────────
 
-function cmdRemove(args, cwd) {
+async function cmdRemove(args, cwd) {
   if (!args.pluginName) throw new Error('remove requires a plugin name');
   const found = findByName(args.pluginName, cwd);
   if (!found) throw new Error(`plugin not found: ${args.pluginName}`);
+
+  // Load the manifest first — if the plugin has a pre_uninstall hook, we
+  // must run it BEFORE deleting the plugin dir (hook code lives there).
+  const scan = readManifest(found.directory);
+  const manifest = scan?.manifest || null;
+  const pluginName = manifest?.metadata?.name || found.name;
+  const stateFactory = manifest ? () => makePluginState(pluginName, { tables: manifest.config?.state?.tables || [] }) : null;
+
+  let preHookResult = { keepData: null, warnings: [] };
+  if (manifest?.config?.lifecycle?.pre_uninstall) {
+    try {
+      const r = await runPreUninstall({ pluginName, pluginDir: found.directory, manifest, args, stateFactory });
+      preHookResult = r.result || {};
+      if (Array.isArray(preHookResult.warnings)) {
+        for (const w of preHookResult.warnings) process.stderr.write(`  ${YELLOW}!${RESET} ${w}\n`);
+      }
+    } catch (err) {
+      // The hook explicitly failed — that is often intentional
+      // ("cannot remove: there is unsaved work"). Do not proceed.
+      throw new Error(`pre_uninstall hook failed: ${err.message}. Uninstall aborted; nothing was removed.`);
+    }
+  }
+
+  // Decide the data-cleanup behavior. Precedence:
+  //   1. Explicit CLI flag: --purge → wipe; --keep-data → keep.
+  //   2. pre_uninstall hook result.keepData (bool).
+  //   3. TTY → interactive prompt (default keep).
+  //   4. Non-TTY (piped/CI) → keep, and print the exact --purge command.
+  const dataDir = path.join(bahulamHome(), 'data', pluginName);
+  const hasDataDir = fs.existsSync(dataDir);
+  let purgeChoice = null; // true = purge, false = keep
+  const reasons = [];
+  if (args.purge) { purgeChoice = true; reasons.push('--purge'); }
+  else if (args.keep_data) { purgeChoice = false; reasons.push('--keep-data'); }
+  else if (preHookResult && typeof preHookResult.keepData === 'boolean') {
+    purgeChoice = !preHookResult.keepData;
+    reasons.push(`pre_uninstall.keepData=${preHookResult.keepData}`);
+  } else if (hasDataDir && process.stdin.isTTY && process.stdout.isTTY) {
+    purgeChoice = await promptYesNo(
+      `Also delete state at ${dataDir}? [y/N] `,
+      false,
+    );
+    reasons.push(`prompt=${purgeChoice ? 'y' : 'n'}`);
+  } else {
+    purgeChoice = false;
+    if (hasDataDir) reasons.push('non-TTY default: keep-data');
+  }
+
+  // Remove the plugin directory.
   rmrf(found.directory);
+
+  // Purge or keep the data dir.
+  let purged = { purged: false, dir: dataDir };
+  if (purgeChoice && hasDataDir) {
+    purged = purgeData(pluginName);
+  }
+
   if (args.json) {
-    process.stdout.write(JSON.stringify({ ok: true, removed: found.name, directory: found.directory }) + '\n');
+    process.stdout.write(JSON.stringify({
+      ok: true,
+      removed: found.name,
+      directory: found.directory,
+      data: {
+        kept: !purgeChoice,
+        purged: purged.purged,
+        directory: dataDir,
+        reason: reasons.join(' '),
+      },
+      pre_uninstall_ran: Boolean(manifest?.config?.lifecycle?.pre_uninstall),
+    }) + '\n');
     return;
   }
+
   process.stderr.write(`${GREEN}✓${RESET} Removed ${BOLD}${found.name}${RESET} (${found.directory})\n`);
+  if (purged.purged) {
+    process.stderr.write(`  ${DIM}data${RESET}      purged ${dataDir}\n`);
+  } else if (hasDataDir) {
+    process.stderr.write(
+      `  ${DIM}data${RESET}      kept ${dataDir}${reasons.length ? ` ${DIM}(${reasons.join(' ')})${RESET}` : ''}\n` +
+      `  ${DIM}To purge later:${RESET} ${CYAN}bahulam plugin remove ${found.name} --purge${RESET}` +
+      ` ${DIM}(plugin dir is gone; this variant only purges the data dir).${RESET}\n`,
+    );
+  }
+}
+
+/**
+ * Minimal yes/no prompt — no external deps. Reads a single line from
+ * stdin; empty answer takes the default.
+ */
+function promptYesNo(prompt, defaultAnswer) {
+  return new Promise((resolve) => {
+    try { process.stdout.write(prompt); } catch { /* ok */ }
+    let input = '';
+    const onData = (chunk) => {
+      input += chunk.toString();
+      const nl = input.indexOf('\n');
+      if (nl < 0) return;
+      process.stdin.removeListener('data', onData);
+      try { process.stdin.pause(); } catch { /* ok */ }
+      const answer = input.slice(0, nl).trim().toLowerCase();
+      if (!answer) return resolve(defaultAnswer);
+      resolve(answer === 'y' || answer === 'yes');
+    };
+    try { process.stdin.resume(); } catch { /* ok */ }
+    process.stdin.on('data', onData);
+  });
 }
 
 // ── enable / disable ────────────────────────────────────────────────
@@ -620,7 +731,15 @@ async function cmdUpdate(args, cwd) {
   const ref = args.ref || found.origin.ref;
   const subdir = found.origin.subdir;
   process.stderr.write(`${DIM}Updating ${found.name} from ${found.origin.url}${ref ? ` @ ${ref}` : ''}${subdir ? ` (subdir ${subdir})` : ''}...${RESET}\n`);
-  if (subdir) {
+
+  // --force wipes the plugin dir before the fetch so a stale local edit or
+  // corrupt install doesn't block the reset. Data dir is preserved.
+  if (args.force && !subdir) {
+    rmrf(found.directory);
+    fs.mkdirSync(found.directory, { recursive: true });
+    // Fresh clone into the empty dir.
+    await run('git', ['clone', '--depth', '1', ...(ref ? ['--branch', ref] : []), found.origin.url, found.directory]);
+  } else if (subdir) {
     // Monorepo: no .git in place, so re-fetch subdir contents into tmp
     // and rsync them over the install dir (preserves .bahulam-plugin.json).
     const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'bahulam-plugin-'));
@@ -640,7 +759,29 @@ async function cmdUpdate(args, cwd) {
   }
   writeStamp(found.directory, { origin: { ...found.origin, ref: ref || found.origin.ref } });
   const scan = readManifest(found.directory);
-  process.stderr.write(`${GREEN}✓${RESET} Updated ${BOLD}${found.name}${RESET}${scan?.manifest?.metadata?.version ? ` to v${scan.manifest.metadata.version}` : ''}\n`);
+  const manifest = scan?.manifest;
+  process.stderr.write(`${GREEN}✓${RESET} Updated ${BOLD}${found.name}${RESET}${manifest?.metadata?.version ? ` to v${manifest.metadata.version}` : ''}\n`);
+
+  // Lifecycle: run pending migrations, then post_install. Seed does NOT
+  // re-run on update (it's a one-shot). If the update failed at
+  // migration time, the state DB is auto-restored via snapshot.
+  if (manifest) {
+    const pluginName = manifest.metadata?.name || found.name;
+    const stateFactory = () => makePluginState(pluginName, { tables: manifest.config?.state?.tables || [] });
+    try {
+      const migReport = await runMigrations({ pluginName, pluginDir: found.directory, manifest, stateFactory });
+      if (migReport.ran) process.stderr.write(`  ${DIM}migrations${RESET} ${migReport.ran} applied\n`);
+      const postReport = await runPostInstall({ pluginName, pluginDir: found.directory, manifest, args, stateFactory });
+      if (postReport.ran) process.stderr.write(`  ${DIM}post_install${RESET} ran\n`);
+      // Stamp last_upgrade_at
+      const rec = readLifecycleRecord(pluginName);
+      rec.last_upgrade_at = new Date().toISOString();
+      rec.installed_version = manifest.metadata?.version || rec.installed_version;
+      fs.writeFileSync(path.join(bahulamHome(), 'data', pluginName, '_bahulam_lifecycle.json'), JSON.stringify(rec, null, 2), 'utf-8');
+    } catch (err) {
+      throw new Error(`update completed but lifecycle failed: ${err.message}`);
+    }
+  }
 }
 
 // ── dispatcher ──────────────────────────────────────────────────────
@@ -823,7 +964,7 @@ export async function handlePluginManagementCommand(args, { cwd = process.cwd(),
     switch (args.action) {
       case 'validate': case 'check': case 'lint': await cmdValidate(args, cwd); return;
       case 'list': case 'ls': await cmdList(args, cwd); return;
-      case 'remove': case 'rm': case 'uninstall': cmdRemove(args, cwd); return;
+      case 'remove': case 'rm': case 'uninstall': await cmdRemove(args, cwd); return;
       case 'enable': toggle(args, cwd, true); return;
       case 'disable': toggle(args, cwd, false); return;
       case 'info': cmdInfo(args, cwd); return;

package/src/config/cli-args.mjs

@@ -22,6 +22,7 @@
 export function parseArgs(args) {
     const result = {
         prompt: null,
+        runtimeMode: null,
         model: null,
         permissionMode: null,
         outputFormat: null,
@@ -45,6 +46,13 @@ export function parseArgs(args) {
         showHelp: false,
     };
 
+    const setRuntimeMode = (mode) => {
+        if (result.runtimeMode && result.runtimeMode !== mode) {
+            throw new Error(`Runtime modes are mutually exclusive: --${result.runtimeMode} and --${mode}`);
+        }
+        result.runtimeMode = mode;
+    };
+
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
 
@@ -128,10 +136,22 @@ export function parseArgs(args) {
                 break;
 
             case '--local':
-                // Force LocalAgent path (bypass backend). Meant for benchmarks
-                // that need to exercise the CLI's own LLM code — cache_control
-                // wiring, prompt-cache stats, etc.
+                // Force CLI-side orchestration. Model calls still use the
+                // shared Bahulam Gateway; this bypasses backend /api/execute.
                 result.local = true;
+                setRuntimeMode('local');
+                break;
+
+            case '--remote':
+                setRuntimeMode('remote');
+                break;
+
+            case '--bundled':
+                setRuntimeMode('bundled');
+                break;
+
+            case '--direct':
+                setRuntimeMode('direct');
                 break;
 
             case '--vision': {

package/src/config/model-catalog.mjs

@@ -94,3 +94,12 @@ export function readShippedCatalog() {
   _cache = null;
   return null;
 }
+
+export function findShippedModel(model) {
+  const wanted = String(model || '').trim();
+  if (!wanted) return null;
+  const catalog = readShippedCatalog() || [];
+  return catalog.find(row => row.id === wanted)
+    || catalog.find(row => row.id.endsWith(`/${wanted}`))
+    || null;
+}

package/src/config/model-defaults.mjs

@@ -40,3 +40,19 @@ export const SHIPPED_MODEL_DEFAULTS = readShippedModelDefaults();
 export const DEFAULT_REASONING_MODEL = SHIPPED_MODEL_DEFAULTS.reasoning;
 export const DEFAULT_FAST_MODEL = SHIPPED_MODEL_DEFAULTS.fast;
 export const DEFAULT_PLANNING_MODEL = SHIPPED_MODEL_DEFAULTS.planning;
+
+function envModel(names, fallback) {
+  for (const name of names) {
+    const value = typeof process !== 'undefined' ? process.env?.[name] : null;
+    if (typeof value === 'string' && value.trim()) return value.trim();
+  }
+  return fallback;
+}
+
+// Keep the named /model modes aligned with the backend chat mode matrix.
+export const CHAT_MODE_DEFAULTS = Object.freeze({
+  fast: envModel(['BAHULAM_CHAT_FAST_MODEL'], DEFAULT_FAST_MODEL),
+  thinking: envModel(['BAHULAM_CHAT_THINKING_MODEL'], DEFAULT_PLANNING_MODEL),
+  extra_thinking: envModel(['BAHULAM_CHAT_EXTRA_THINKING_MODEL'], 'minimax/minimax-m3'),
+  max_thinking: envModel(['BAHULAM_CHAT_MAX_THINKING_MODEL'], 'deepseek/deepseek-v4-pro'),
+});

package/src/core/approval.mjs

@@ -154,9 +154,10 @@ export class ApprovalManager {
 
     setReadline(rl) { this._rl = rl; }
 
-    setExecutionHooks({ onPause, onResume, onApprovalPromptEnd } = {}) {
+    setExecutionHooks({ onPause, onResume, onApprovalPromptStart, onApprovalPromptEnd } = {}) {
         this._execPause = onPause || null;
         this._execResume = onResume || null;
+        this._approvalPromptStart = onApprovalPromptStart || null;
         this._approvalPromptEnd = onApprovalPromptEnd || null;
     }
 
@@ -279,6 +280,12 @@ export class ApprovalManager {
 
         const isInteractive = process.stdin.isTTY;
 
+        // Shared lifecycle hook for every runtime. Hosts can leave a
+        // persistent approval marker before the transient dock is painted.
+        try {
+            this._approvalPromptStart?.({ tool: toolName, args, tier, why });
+        } catch { /* rendering must never block approval */ }
+
         // In rich TTY mode approval lives in the fixed input dock, replacing
         // "+ add instruction" until the user decides. Fallback/plain mode
         // still renders in the transcript.

package/src/core/attachments.mjs

@@ -465,6 +465,10 @@ function looksLikeAttachment(value) {
   return looksLikeImagePath(value) || looksLikeDocumentPath(value) || isClipboardAlias(value);
 }
 
+export function looksLikeAttachmentReference(value) {
+  return looksLikeAttachment(value);
+}
+
 /**
  * Parse @path references from `input` for BOTH images and documents.
  * Returns a cleaned instruction (with @refs removed) plus separate

package/src/core/backend-url.mjs

@@ -65,3 +65,19 @@ export function resolveBackendUrl() {
     // 3. Fallback to production
     return BACKEND_URLS.production;
 }
+
+/**
+ * Resolve the Gateway URL used by npm-owned orchestration.
+ *
+ * A local backend token must be validated by a Gateway configured against
+ * that same local backend; sending it to the production Gateway produces a
+ * misleading 401. Keep the explicit override for custom deployments.
+ */
+export function resolveGatewayUrl() {
+    if (process.env.BAHULAM_GATEWAY_URL) {
+        return process.env.BAHULAM_GATEWAY_URL.replace(/\/+$/, '');
+    }
+    const env = (process.env.TARANG_ENV || process.env.NODE_ENV || 'production').toLowerCase();
+    if (env === 'local' || env === 'docker') return 'http://127.0.0.1:8180/v1';
+    return 'https://gateway.bahulam.ai/v1';
+}