@openagents-org/agent-launcher 0.2.149 → 0.2.151

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@openagents-org/agent-launcher",
-  "version": "0.2.149",
-  "description": "OpenAgents Launcher — install, configure, and run AI coding agents from your terminal",
+  "version": "0.2.151",
+  "description": "OpenAgents Launcher \u2014 install, configure, and run AI coding agents from your terminal",
   "main": "src/index.js",
   "bin": {
     "agn": "bin/agent-connector.js",

package/registry.json

@@ -835,5 +835,100 @@
       "login_command": "hermes setup",
       "not_ready_message": "Hermes not configured — run: hermes setup"
     }
+  },
+  {
+    "name": "mini-swe-agent",
+    "label": "mini-SWE-agent",
+    "description": "A minimal shell-based coding agent for fixing issues and modifying code in a workspace.",
+    "homepage": "https://mini-swe-agent.com",
+    "tags": [
+      "coding",
+      "cli",
+      "shell",
+      "autonomous"
+    ],
+    "builtin": true,
+    "support": {
+      "install": true,
+      "workspace": true,
+      "collaboration": true
+    },
+    "install": {
+      "binary": "mini",
+      "verify": "mini --help",
+      "verify_win": "mini --help",
+      "macos": "pip install mini-swe-agent",
+      "linux": "pip install mini-swe-agent",
+      "windows": "pip install mini-swe-agent"
+    },
+    "launch": {
+      "args": []
+    },
+    "env_config": [
+      {
+        "name": "MSWEA_MODEL_NAME",
+        "description": "Model to use (routed through LiteLLM), e.g. anthropic/claude-sonnet-4-5 or gpt-4o. Optional when a model is already configured via a config file or `mini-extra config setup`. Passed as --model.",
+        "required": false,
+        "placeholder": "anthropic/claude-sonnet-4-5"
+      },
+      {
+        "name": "MSWEA_MINI_CONFIG_PATH",
+        "description": "Path to a FULL mini config file (YAML). Optional. This REPLACES mini's built-in default config (agent prompt templates, step/environment settings) — it does not merge — so provide a complete file (a good starting point is the output of `mini-extra config setup`). Leave blank to use mini's default config.",
+        "required": false,
+        "placeholder": "/path/to/mini.yaml"
+      },
+      {
+        "name": "MSWEA_COST_LIMIT",
+        "description": "Optional per-run cost limit in USD, passed as --cost-limit. Leave blank for mini's default.",
+        "required": false,
+        "placeholder": "3.0"
+      },
+      {
+        "name": "ANTHROPIC_API_KEY",
+        "description": "Anthropic API key — used when the model is an Anthropic model. Leave blank if using another provider or a key already in your environment.",
+        "required": false,
+        "password": true
+      },
+      {
+        "name": "ANTHROPIC_BASE_URL",
+        "description": "Custom endpoint for native `anthropic/…` models (an enterprise gateway or Anthropic-protocol relay). Leave blank for hosted Anthropic. Note: most third-party relays are OpenAI-compatible — for those use an `openai/…` model + OPENAI_BASE_URL instead.",
+        "required": false,
+        "placeholder": "https://your-anthropic-gateway.example"
+      },
+      {
+        "name": "OPENAI_API_KEY",
+        "description": "OpenAI API key — used when the model is an OpenAI model. Leave blank if using another provider or a key already in your environment.",
+        "required": false,
+        "password": true
+      },
+      {
+        "name": "OPENAI_BASE_URL",
+        "description": "Custom endpoint for OpenAI-compatible models (a relay/proxy or self-hosted gateway) — applies only to `openai/…` models. Leave blank for hosted OpenAI, or for native providers like `deepseek/…` / `anthropic/…`.",
+        "required": false,
+        "placeholder": "https://your-relay.example/v1"
+      },
+      {
+        "name": "DEEPSEEK_API_KEY",
+        "description": "DeepSeek API key — used when the model is a `deepseek/…` model (e.g. deepseek/deepseek-chat or deepseek/deepseek-reasoner). Connects directly to api.deepseek.com; no base URL needed.",
+        "required": false,
+        "password": true
+      },
+      {
+        "name": "DEEPSEEK_API_BASE",
+        "description": "Custom endpoint for native `deepseek/…` models. Leave blank to use DeepSeek's default (api.deepseek.com).",
+        "required": false,
+        "placeholder": "https://api.deepseek.com"
+      }
+    ],
+    "check_ready": {
+      "env_vars": [
+        "MSWEA_MODEL_NAME",
+        "MSWEA_MINI_CONFIG_PATH",
+        "ANTHROPIC_API_KEY",
+        "OPENAI_API_KEY",
+        "DEEPSEEK_API_KEY"
+      ],
+      "not_ready_message": "mini-SWE-agent CLI detected. Configure a model through environment variables (MSWEA_MODEL_NAME + a provider key), a full config file (MSWEA_MINI_CONFIG_PATH), or the Model field before running a task."
+    }
   }
 ]

package/src/adapters/aider.js

@@ -107,13 +107,14 @@ function classifyError(stderr, stdout) {
 // ---------------------------------------------------------------------------
 
 const VALID_PROVIDERS = [
-  'auto', 'openai', 'anthropic', 'openrouter', 'gemini', 'deepseek',
+  'auto', 'openai', 'anthropic', 'openrouter', 'requesty', 'gemini', 'deepseek',
   'openai-compatible',
 ];
 const PROVIDER_KEY_VAR = {
   openai: 'OPENAI_API_KEY',
   anthropic: 'ANTHROPIC_API_KEY',
   openrouter: 'OPENROUTER_API_KEY',
+  requesty: 'REQUESTY_API_KEY',
   gemini: 'GEMINI_API_KEY',
   deepseek: 'DEEPSEEK_API_KEY',
   'openai-compatible': 'OPENAI_API_KEY',
@@ -122,6 +123,7 @@ const PROVIDER_KEY_VAR = {
 function explicitPrefixProvider(model) {
   const m = String(model || '').trim().toLowerCase();
   if (m.startsWith('openrouter/')) return 'openrouter';
+  if (m.startsWith('requesty/')) return 'requesty';
   if (m.startsWith('anthropic/')) return 'anthropic';
   if (m.startsWith('openai/')) return 'openai';
   if (m.startsWith('gemini/') || m.startsWith('google/')) return 'gemini';
@@ -167,7 +169,7 @@ function resolveAiderProvider(provider, model, apiKey, baseUrl) {
     return {
       env: {}, model,
       error: `Unknown AIDER_PROVIDER '${provider}'. Valid values: auto, openai, `
-        + 'anthropic, openrouter, gemini, deepseek, openai-compatible.',
+        + 'anthropic, openrouter, requesty, gemini, deepseek, openai-compatible.',
     };
   }
   if (!provider) provider = 'auto';
@@ -191,7 +193,7 @@ function resolveAiderProvider(provider, model, apiKey, baseUrl) {
       return {
         env: {}, model,
         error: 'Could not determine the model provider for LLM_API_KEY. Set '
-          + 'AIDER_PROVIDER (openai, anthropic, openrouter, gemini, deepseek, or '
+          + 'AIDER_PROVIDER (openai, anthropic, openrouter, requesty, gemini, deepseek, or '
           + 'openai-compatible), use an AIDER_MODEL whose name identifies the '
           + 'provider, or set the native provider key directly.',
       };

package/src/adapters/base.js

@@ -370,12 +370,31 @@ class BaseAdapter {
     }
 
     try {
-      const result = installer.installSkill({
-        skill,
-        agentType: this.agentType,
-        workingDir: this.workingDir,
-        log: (m) => this._log(`skill.install: ${m}`),
-      });
+      // Custom (uploaded) skills carry source_type=workspace_file + a file_id.
+      // Download the package bytes here (async), then hand them to the sync
+      // installer. Catalog skills keep their existing fetch-by-source path.
+      const sourceType = skill && (skill.source_type || skill.sourceType);
+      let result;
+      if (sourceType === 'workspace_file') {
+        const fileId = skill.file_id || skill.fileId;
+        if (!fileId) throw new Error('workspace_file skill is missing file_id');
+        this._log(`skill.install: downloading uploaded package (file_id=${fileId})`);
+        const buffer = await this.client.readFile(this.workspaceId, this.token, fileId);
+        if (!buffer || buffer.length === 0) throw new Error('uploaded skill file is empty');
+        result = installer.installUploadedSkill({
+          skill, buffer,
+          agentType: this.agentType,
+          workingDir: this.workingDir,
+          log: (m) => this._log(`skill.install: ${m}`),
+        });
+      } else {
+        result = installer.installSkill({
+          skill,
+          agentType: this.agentType,
+          workingDir: this.workingDir,
+          log: (m) => this._log(`skill.install: ${m}`),
+        });
+      }
       try {
         await this.client.reportSkillStatus(this.workspaceId, this.agentName, this.token, {
           skillId, state: 'installed', path: result.path, partial: result.partial === true,
@@ -688,6 +707,15 @@ class BaseAdapter {
     }
 
     if (this._channelBusy.has(channel)) {
+      // A routine that's already running must not stack up. Routine fires are
+      // periodic, so a fire that arrives while the previous run is still going
+      // is simply dropped — the next scheduled tick re-fires once the agent is
+      // free. (The backend guard normally prevents this from even being sent;
+      // this is the last line of defense against a queue backlog.)
+      if (msg.senderName === 'system:routine') {
+        this._log(`Skipping routine fire in ${channel} — previous run still in progress`);
+        return;
+      }
       if (!this._channelQueues[channel]) this._channelQueues[channel] = [];
       const queueId = `q-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
       msg._queueId = queueId;

package/src/adapters/claude.js

@@ -971,6 +971,15 @@ class ClaudeAdapter extends BaseAdapter {
           try { await this.sendResponse(msgChannel, fullResponse); } catch {}
         } else if (existingPP.lastErrorText) {
           try { await this.sendError(msgChannel, this._formatClaudeError(existingPP.lastErrorText)); } catch {}
+        } else if (!existingPP.everPostedAnything) {
+          // Error with no text and no error message — don't leave the UI stuck
+          // on "thinking…". Reset the (possibly corrupt) session and tell the user.
+          if (this._channelSessions[msgChannel]) {
+            delete this._channelSessions[msgChannel];
+            try { this._saveSessions(); } catch {}
+            this._log(`Empty-error result — cleared session for ${msgChannel}`);
+          }
+          try { await this.sendError(msgChannel, 'The agent hit an error and could not respond. The session was reset — please send the message again.'); } catch {}
         }
         this._resetIdleTimer(msgChannel);
         if (!msg._todoNudge) {
@@ -1145,6 +1154,19 @@ class ClaudeAdapter extends BaseAdapter {
           // Claude finished with an error and no assistant text (e.g. 401 invalid
           // token). Surface it instead of silently dropping the turn.
           try { await this.sendError(msgChannel, this._formatClaudeError(pp.lastErrorText)); } catch {}
+        } else if (!pp.everPostedAnything) {
+          // Claude ended in error with NO assistant text AND an empty error
+          // message (e.g. a fast code=1 crash while resuming a corrupt session).
+          // Without this the turn is silently dropped and the UI hangs forever on
+          // "thinking…". Clear the (possibly bad) session so the next message
+          // starts fresh instead of re-resuming the same broken state, and tell
+          // the user rather than leaving a dead spinner.
+          if (this._channelSessions[msgChannel]) {
+            delete this._channelSessions[msgChannel];
+            try { this._saveSessions(); } catch {}
+            this._log(`Empty-error result — cleared session for ${msgChannel}`);
+          }
+          try { await this.sendError(msgChannel, 'The agent hit an error and could not respond. The session was reset — please send the message again.'); } catch {}
         }
 
         this._resetIdleTimer(msgChannel);

package/src/adapters/index.js

@@ -19,6 +19,7 @@ const GooseAdapter = require('./goose');
 const CopilotAdapter = require('./copilot');
 const ClineAdapter = require('./cline');
 const AmpAdapter = require('./amp');
+const MiniSweAgentAdapter = require('./mini');
 
 const ADAPTER_MAP = {
   openclaw: OpenClawAdapter,
@@ -35,11 +36,12 @@ const ADAPTER_MAP = {
   copilot: CopilotAdapter,
   cline: ClineAdapter,
   amp: AmpAdapter,
+  'mini-swe-agent': MiniSweAgentAdapter,
 };
 
 /**
  * Create an adapter instance for the given agent type.
- * @param {string} type - Agent type (openclaw, claude, codex, opencode, nanoclaw, cursor, hermes, gemini, kimi, aider, goose, copilot, cline, amp)
+ * @param {string} type - Agent type (openclaw, claude, codex, opencode, nanoclaw, cursor, hermes, gemini, kimi, aider, goose, copilot, cline, amp, mini-swe-agent)
  * @param {object} opts - Adapter constructor options
  * @returns {BaseAdapter}
  */
@@ -67,6 +69,7 @@ module.exports = {
   CopilotAdapter,
   ClineAdapter,
   AmpAdapter,
+  MiniSweAgentAdapter,
   createAdapter,
   ADAPTER_MAP,
 };

package/src/adapters/mini.js

@@ -0,0 +1,572 @@
+/**
+ * mini-SWE-agent adapter for OpenAgents workspace.
+ *
+ * Bridges the mini-swe-agent CLI (https://mini-swe-agent.com) to an OpenAgents
+ * workspace as a plain shell-based coding agent. Each workspace message spawns
+ * ONE non-interactive `mini` run in the task's workspace directory and exits:
+ *
+ *   mini [--model <model>] --yolo --exit-immediately \
+ *        [--cost-limit <n>] --output <trajectory> --task <prompt>
+ *
+ * Design notes (verified against the mini CLI docs):
+ *  - `mini` defaults to *confirm* mode (interactive) and, when the agent wants
+ *    to finish, PROMPTS for the next step instead of exiting. `--yolo` runs LM
+ *    commands without confirmation and `--exit-immediately` makes it exit on
+ *    finish — BOTH are required for a headless one-shot run, or the daemon would
+ *    hang waiting on stdin. stdin is also given /dev/null (stdio 'ignore') so a
+ *    stray prompt (e.g. the first-run setup wizard) can never wedge the process.
+ *  - mini is a Python process with no JSON event protocol: stdout is drained as
+ *    a best-effort progress log (ANSI-stripped, relayed as `thinking`, capped)
+ *    and the cleaned transcript tail is sent once as the final answer. The exit
+ *    code decides success (non-zero is never reported as success). PYTHONUNBUFFERED
+ *    is set so stdout streams instead of being fully buffered; NO_COLOR keeps
+ *    rich/ANSI escapes out of the relayed log.
+ *  - Each run gets its own --output trajectory file under ~/.openagents/sessions
+ *    (never in the project), removed afterwards, so concurrent channel runs never
+ *    clash on a shared trajectory.
+ *  - Stateless per task: mini keeps no memory across workspace messages (there is
+ *    no fabricated persistent session). The agent is auto-authorized to run shell
+ *    commands via --yolo — consistent with how Goose (GOOSE_MODE=auto) and Copilot
+ *    (--no-ask-user) already auto-execute; there is no shared per-command approval
+ *    gate to hook into.
+ *  - Config: mini's config is set via the MSWEA_MINI_CONFIG_PATH env var (which
+ *    mini reads as its default config file), forwarded through the agent env. We
+ *    intentionally do NOT pass --config: a single --config / MSWEA_MINI_CONFIG_PATH
+ *    REPLACES mini's built-in mini.yaml (agent prompt templates, step/env config)
+ *    rather than merging (verified in mini's run/mini.py), so the launcher field
+ *    is documented as a FULL config file, not a partial override.
+ *  - Multi-provider auth is left to mini/LiteLLM: the user supplies the model
+ *    (MSWEA_MODEL_NAME or the Model field) and provider keys (ANTHROPIC_API_KEY /
+ *    OPENAI_API_KEY / …) through the agent environment, which flows through
+ *    unchanged. Keys never reach the command line or the logs.
+ *
+ * Reuses all shared connectivity / dispatch / state machinery in BaseAdapter;
+ * only the mini-specific subprocess invocation and parsing live here. Node-only
+ * adapter (like Cline / Copilot) — there is no Python mirror.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execSync, spawn } = require('child_process');
+
+const BaseAdapter = require('./base');
+const { whichBinary, getEnhancedEnv, aiderBinDirs } = require('../paths');
+const {
+  REASON,
+  classifySpawnError,
+  redactDiagnostic,
+  shouldUseShellForBinary,
+} = require('./health-status');
+
+const IS_WINDOWS = process.platform === 'win32';
+// Terminate if mini produces no output for this long (a wedged turn). Resets on
+// any stdout activity, so a slow-but-progressing task is never killed.
+const IDLE_TIMEOUT_MS = 10 * 60 * 1000;
+// Cap how many stdout lines are relayed as `thinking` progress, so a task that
+// prints large command output (diffs, test logs) can't flood the channel. The
+// full transcript is still collected for the final answer.
+const MAX_STREAM_UPDATES = 60;
+// Cap the size of the final transcript we post back. mini's own closing summary
+// is at the END of stdout, so we keep the tail when truncating.
+const FINAL_RESPONSE_MAX = 12000;
+
+// eslint-disable-next-line no-control-regex
+const ANSI_RE = /\x1b\[[0-9;?]*[ -/]*[@-~]/g;
+const BLANKS_RE = /\n{3,}/g;
+
+// Error signatures → an actionable message. mini routes model calls through
+// LiteLLM, so the failure surface mirrors Aider's; a couple of mini-specific
+// cases (cost limit, no model configured) are added.
+const ERROR_SIGNATURES = [
+  [['authenticationerror', 'invalid api key', 'incorrect api key', 'no api key',
+    'missing these environment variables', 'api key not found', '401',
+    'unauthorized', 'permission denied to access model'],
+    'Authentication failed — configure a model API key (e.g. ANTHROPIC_API_KEY or '
+    + 'OPENAI_API_KEY) for the selected model in the agent environment.'],
+  [['notfounderror', 'model_not_found', 'does not exist', 'unknown model',
+    'could not find model', 'you do not have access to model'],
+    'Model not found or not accessible — check MSWEA_MODEL_NAME / the Model field '
+    + 'and that your key has access.'],
+  [['you must provide a model', 'no model', 'set up a model', 'model is required',
+    'run `mini-extra config setup`', 'run mini-extra config setup'],
+    'No model configured — set MSWEA_MODEL_NAME (or the Model field / a --config '
+    + 'file), or run `mini-extra config setup`.'],
+  [['cost limit', 'costlimit', 'exceeded the cost', 'limitreached', 'limit reached'],
+    'Stopped: the configured cost limit (MSWEA_COST_LIMIT) was reached before the '
+    + 'task finished.'],
+  [['rate limit', 'ratelimiterror', '429', 'quota', 'insufficient_quota'],
+    'Rate-limited or out of quota at the model provider — try again later.'],
+  [['connectionerror', 'timeout', 'could not connect', 'getaddrinfo',
+    'temporary failure in name resolution', 'network is unreachable',
+    'failed to establish a new connection'],
+    'Network error reaching the model provider — check connectivity and the base URL.'],
+];
+
+function miniInstallHint() {
+  return 'pip install mini-swe-agent';
+}
+
+function cleanOutput(text) {
+  return String(text || '').replace(ANSI_RE, '').replace(BLANKS_RE, '\n\n').trim();
+}
+
+function classifyError(stderr, stdout) {
+  const blob = `${stderr}\n${stdout}`.toLowerCase();
+  for (const [needles, message] of ERROR_SIGNATURES) {
+    if (needles.some((n) => blob.includes(n))) return message;
+  }
+  return null;
+}
+
+/**
+ * Wrap a workspace message as a self-contained coding task. mini works on the
+ * files directly via shell (it does NOT use the OpenAgents MCP tools), so the
+ * prompt is a plain instruction — no workspace/MCP context, and deliberately no
+ * SWE-bench / patch / benchmark wording.
+ */
+function buildTaskPrompt(userMessage) {
+  return [
+    'You are working in the current workspace directory.',
+    '',
+    'User request:',
+    userMessage,
+    '',
+    'Work directly on the files in the current workspace.',
+    'Inspect the codebase before editing.',
+    'Run relevant tests or checks where practical.',
+    'Do not merely describe a solution: make the changes in the workspace.',
+    'When finished, summarize:',
+    '- what you changed',
+    '- which checks/tests you ran',
+    '- any remaining limitations',
+  ].join('\n');
+}
+
+class MiniSweAgentAdapter extends BaseAdapter {
+  constructor(opts) {
+    super(opts);
+    this.disabledModules = opts.disabledModules || new Set();
+
+    // channel -> running child process (for stop / cleanup)
+    this._channelProcesses = {};
+    // channels the user explicitly stopped (suppress "no response" noise)
+    this._stoppingChannels = new Set();
+    this._trajCounter = 0;
+
+    // Per-run trajectory files live here, never in the project directory.
+    this._sessionsDir = path.join(
+      os.homedir(), '.openagents', 'sessions', 'mini-swe-agent',
+      `${this.workspaceId}_${this.agentName}`,
+    );
+
+    this._miniBin = this._findMiniBinary();
+    if (this._miniBin) {
+      this._log(`Using mini-SWE-agent CLI: ${this._miniBin}`);
+    } else {
+      this._log(`Warning: mini-SWE-agent CLI not found — install with: ${miniInstallHint()}`);
+    }
+  }
+
+  // ------------------------------------------------------------------
+  // Binary resolution
+  // ------------------------------------------------------------------
+
+  _findMiniBinary() {
+    // Shared cross-platform resolver runs `which`/`where` against an ENHANCED
+    // PATH (nvm/fnm/volta/homebrew + pip/pipx/uv user-install dirs) — covers the
+    // GUI/daemon "installed but not on PATH" case for a `pip install`.
+    const resolved = whichBinary('mini');
+    if (resolved) return this._resolveExePreference(resolved, IS_WINDOWS);
+
+    // Explicit fallback over the pip/pipx/uv user-install bin dirs plus the uv
+    // tool venv for mini-swe-agent.
+    const names = IS_WINDOWS ? ['mini.exe', 'mini.cmd', 'mini'] : ['mini'];
+    const dirs = [...aiderBinDirs()];
+    const home = os.homedir();
+    if (IS_WINDOWS) {
+      const appData = process.env.APPDATA || path.join(home, 'AppData', 'Roaming');
+      const uvTools = process.env.UV_TOOL_DIR || path.join(appData, 'uv', 'tools');
+      dirs.push(path.join(uvTools, 'mini-swe-agent', 'Scripts'));
+    } else {
+      const uvTools = process.env.UV_TOOL_DIR
+        || path.join(home, '.local', 'share', 'uv', 'tools');
+      dirs.push(path.join(uvTools, 'mini-swe-agent', 'bin'));
+    }
+    for (const dir of dirs) {
+      for (const name of names) {
+        const c = path.join(dir, name);
+        if (fs.existsSync(c)) return c;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * On Windows, prefer a directly-executable `mini.exe` over a `mini.cmd`/`.bat`
+   * shim that would otherwise have to be launched through a shell. pip/pipx/uv
+   * install a console-script `.exe` wrapper, so this normally resolves to the
+   * exe; if the resolver landed on a .cmd/.bat and a sibling .exe exists, use the
+   * .exe. No-op off Windows. (A .cmd shim still runs correctly via
+   * shouldUseShellForBinary — this just avoids the shell hop.)
+   */
+  _resolveExePreference(binPath, isWindows) {
+    if (!isWindows || !/\.(cmd|bat)$/i.test(String(binPath))) return binPath;
+    const exe = path.join(path.dirname(binPath), 'mini.exe');
+    return fs.existsSync(exe) ? exe : binPath;
+  }
+
+  /**
+   * Preflight gate (run by the daemon before join). mini needs a resolvable CLI
+   * to do anything useful; when none is found we surface 'runtime_missing' and
+   * skip the join. We deliberately do NOT block on a missing model here — mini
+   * can read a model from a global config we can't see, and a stray prompt is
+   * already made safe by the /dev/null stdin. A genuinely unconfigured model
+   * surfaces as a crisp error on the first run instead.
+   */
+  preflight() {
+    if (!this._miniBin) this._miniBin = this._findMiniBinary();
+    if (!this._miniBin) {
+      return {
+        ok: false,
+        reason: REASON.RUNTIME_MISSING,
+        message: `mini-SWE-agent CLI not found — install with: ${miniInstallHint()}`,
+      };
+    }
+    this._log(`mini-SWE-agent CLI resolved: ${this._miniBin}`);
+    return { ok: true };
+  }
+
+  // ------------------------------------------------------------------
+  // Config + command construction
+  // ------------------------------------------------------------------
+
+  _model() {
+    return String(
+      this.agentEnv.MSWEA_MODEL_NAME || this.agentEnv.MSWEA_MODEL
+      || this.agentEnv.LLM_MODEL || '',
+    ).trim();
+  }
+
+  _costLimit() {
+    const raw = String(this.agentEnv.MSWEA_COST_LIMIT || '').trim();
+    if (!raw) return null;
+    return /^\d+(\.\d+)?$/.test(raw) ? raw : null;
+  }
+
+  /**
+   * Build the mini argv. Order is stable: [--model], --yolo, --exit-immediately,
+   * [--cost-limit], [--output], --task <prompt>. The task is always the LAST
+   * argument and is passed as a single argv element (never string-concatenated),
+   * so quotes / spaces / newlines / shell metacharacters in the prompt are
+   * carried verbatim with no shell involvement. Config is NOT a flag here — it
+   * flows via the MSWEA_MINI_CONFIG_PATH env var (see the file header).
+   */
+  _buildMiniArgs({ model, costLimit, trajectoryPath, task }) {
+    const args = [];
+    if (model) args.push('--model', model);
+    args.push('--yolo', '--exit-immediately');
+    if (costLimit) args.push('--cost-limit', String(costLimit));
+    if (trajectoryPath) args.push('--output', trajectoryPath);
+    args.push('--task', task);
+    return args;
+  }
+
+  _buildSubprocessEnv() {
+    const base = getEnhancedEnv(this.agentEnv);
+    if (base.NO_COLOR === undefined) base.NO_COLOR = '1';
+    // mini is a Python process — force line-buffered stdout so progress streams
+    // instead of arriving all at once at exit.
+    base.PYTHONUNBUFFERED = '1';
+    // Skip mini's interactive first-run setup wizard. mini runs it whenever
+    // MSWEA_CONFIGURED is unset (see run/utilities/config.configure_if_first_time),
+    // which — under our /dev/null stdin — aborts with a useless "Aborted." even
+    // when the user HAS configured a model + key via the agent environment. In a
+    // daemon the wizard is never appropriate; the model/keys come from the env.
+    if (base.MSWEA_CONFIGURED === undefined) base.MSWEA_CONFIGURED = 'true';
+    return base;
+  }
+
+  // ------------------------------------------------------------------
+  // Control actions (stop)
+  // ------------------------------------------------------------------
+
+  async _onControlAction(action, payload) {
+    if (action === 'stop') {
+      for (const [channel, proc] of Object.entries(this._channelProcesses)) {
+        this._stoppingChannels.add(channel);
+        await this._stopProcess(proc);
+        delete this._channelProcesses[channel];
+        try { await this.sendStatus(channel, 'Execution stopped by user'); } catch {}
+      }
+      return;
+    }
+    await super._onControlAction(action, payload);
+  }
+
+  async _stopProcess(proc) {
+    if (!proc || proc.exitCode !== null) return;
+    try {
+      if (IS_WINDOWS) {
+        try { execSync(`taskkill /F /T /PID ${proc.pid}`, { timeout: 5000 }); } catch {}
+        return;
+      }
+      // POSIX: kill the whole process group (proc was detached) so the shell
+      // commands mini spawned under --yolo are reaped too — not left orphaned.
+      try { process.kill(-proc.pid, 'SIGTERM'); } catch { proc.kill('SIGTERM'); }
+      await new Promise((resolve) => {
+        const timeout = setTimeout(() => {
+          try { process.kill(-proc.pid, 'SIGKILL'); } catch { proc.kill('SIGKILL'); }
+          resolve();
+        }, 5000);
+        proc.on('exit', () => { clearTimeout(timeout); resolve(); });
+      });
+    } catch {}
+  }
+
+  /** True when an error is a child_process spawn failure (vs. a runtime error). */
+  _isSpawnError(e) {
+    if (!e) return false;
+    const code = e.code || e.errno;
+    return (
+      e.syscall === 'spawn'
+      || String(e.syscall || '').startsWith('spawn ')
+      || code === 'ENOENT'
+      || code === 'EACCES'
+      || code === 'EPERM'
+    );
+  }
+
+  // ------------------------------------------------------------------
+  // Message handler
+  // ------------------------------------------------------------------
+
+  async _handleMessage(msg) {
+    const content = (msg.content || '').trim();
+    if (!content) return;
+
+    const msgChannel = msg.sessionId || this.channelName;
+    const sender = msg.senderName || msg.senderType || 'user';
+    this._log(`Processing message from ${sender} in ${msgChannel}: ${content.length} chars`);
+
+    if (!this._miniBin) this._miniBin = this._findMiniBinary();
+    if (!this._miniBin) {
+      const message = `mini-SWE-agent CLI not found — install with: ${miniInstallHint()}`;
+      this._reportStatus(REASON.RUNTIME_MISSING, message);
+      await this.sendError(msgChannel, message);
+      return;
+    }
+
+    await this._autoTitleChannel(msgChannel, content);
+    this._stoppingChannels.delete(msgChannel);
+    await this.sendStatus(msgChannel, 'mini-SWE-agent is working...');
+
+    let result;
+    try {
+      result = await this._runMini(content, msgChannel);
+    } catch (e) {
+      // A failure to LAUNCH the process (ENOENT/EACCES) is a distinct, actionable
+      // failure — surface it as spawn_failed with the resolved path + code.
+      if (this._isSpawnError(e)) {
+        const { reason, message } = classifySpawnError(e, {
+          label: 'mini-SWE-agent',
+          bin: this._miniBin,
+        });
+        this._log(message);
+        this._reportStatus(reason, message);
+        await this.sendError(msgChannel, message);
+      } else {
+        this._log(`Error handling message: ${redactDiagnostic(e.message)}`);
+        await this.sendError(
+          msgChannel,
+          `Error processing message: ${redactDiagnostic(e.message)}`,
+        );
+      }
+      return;
+    }
+
+    if (this._stoppingChannels.has(msgChannel)) {
+      this._stoppingChannels.delete(msgChannel);
+      return;
+    }
+    const { text, error } = result;
+    if (error) {
+      await this.sendError(msgChannel, error);
+      return;
+    }
+    // A successful run proves the runtime is healthy — clear any prior error.
+    this._reportStatus(null);
+    if (text) {
+      await this.sendResponse(msgChannel, text);
+    } else {
+      await this.sendResponse(
+        msgChannel,
+        'mini-SWE-agent finished with no textual output (any file changes were applied '
+        + 'to the workspace directory).',
+      );
+    }
+  }
+
+  // ------------------------------------------------------------------
+  // Subprocess execution
+  // ------------------------------------------------------------------
+
+  async _runMini(content, msgChannel) {
+    fs.mkdirSync(this._sessionsDir, { recursive: true });
+    this._trajCounter += 1;
+    // Per-run trajectory file — isolates concurrent channel runs from a shared
+    // default trajectory. Removed after the run (we rely on stdout, not the
+    // trajectory, for the result).
+    const trajectoryPath = path.join(
+      this._sessionsDir, `traj-${process.pid}-${this._trajCounter}.json`,
+    );
+    const cmd = [
+      this._miniBin,
+      ...this._buildMiniArgs({
+        model: this._model(),
+        costLimit: this._costLimit(),
+        trajectoryPath,
+        task: buildTaskPrompt(content),
+      }),
+    ];
+    let result;
+    try {
+      result = await this._spawnMini(cmd, msgChannel);
+    } catch (e) {
+      // Keep the trajectory on a launch failure — it is most useful exactly when
+      // something went wrong.
+      this._log(`mini-SWE-agent trajectory kept for debugging: ${trajectoryPath}`);
+      throw e;
+    }
+    // Retain the trajectory on failure / timeout / cancel (when it matters for
+    // debugging); only clean it up on a clean success. Timeout and cancel both
+    // surface here as result.error and/or a stopping channel.
+    const kept = !!result.error || this._stoppingChannels.has(msgChannel);
+    if (kept) {
+      this._log(`mini-SWE-agent trajectory kept for debugging: ${trajectoryPath}`);
+    } else {
+      try { fs.rmSync(trajectoryPath, { force: true }); } catch {}
+    }
+    return result;
+  }
+
+  _spawnMini(cmd, msgChannel) {
+    return new Promise((resolve, reject) => {
+      const env = this._buildSubprocessEnv();
+
+      const proc = spawn(cmd[0], cmd.slice(1), {
+        // stdin is /dev/null: mini never has a terminal to prompt against, so a
+        // stray confirm / first-run wizard hits EOF and exits instead of hanging.
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env,
+        cwd: this.workingDir,
+        detached: !IS_WINDOWS,
+        windowsHide: true,
+        // Args are always an array (no shell string); the shared helper only
+        // opts into a shell for Windows .cmd/.bat shims so the daemon, adapter
+        // and launcher probe all agree on the rule.
+        shell: shouldUseShellForBinary(cmd[0]),
+      });
+      this._channelProcesses[msgChannel] = proc;
+      // Log the flags only — never the task text or any secret. The task is the
+      // last argv element; everything before it is safe to log.
+      this._log(`Running mini-SWE-agent: ${cmd.slice(0, cmd.indexOf('--task') + 1).map(String).join(' ')} <task>`);
+
+      // Guard the child's stdio streams against a benign post-SIGKILL 'error'
+      // (EPIPE/ECONNRESET) that would otherwise crash the process.
+      if (proc.stdout) proc.stdout.on('error', () => {});
+      if (proc.stderr) proc.stderr.on('error', () => {});
+
+      let stdoutBuf = '';
+      let stderrBuf = '';
+      let lineBuffer = '';
+      let streamCount = 0;
+      let pending = Promise.resolve();
+
+      let idleTimer = null;
+      const armIdle = () => {
+        if (idleTimer) clearTimeout(idleTimer);
+        idleTimer = setTimeout(() => {
+          this._log(`mini-SWE-agent produced no output for ${IDLE_TIMEOUT_MS / 1000}s — terminating`);
+          this._stopProcess(proc);
+        }, IDLE_TIMEOUT_MS);
+      };
+      armIdle();
+
+      if (proc.stderr) {
+        proc.stderr.on('data', (chunk) => { stderrBuf += chunk.toString('utf-8'); });
+      }
+
+      const handleLine = async (raw) => {
+        const stripped = raw.replace(ANSI_RE, '').trim();
+        if (!stripped) return;
+        if (streamCount < MAX_STREAM_UPDATES) {
+          streamCount += 1;
+          try { await this.sendThinking(msgChannel, stripped.slice(0, 500)); } catch {}
+        }
+      };
+
+      proc.stdout.on('data', (chunk) => {
+        armIdle();
+        const s = chunk.toString('utf-8');
+        stdoutBuf += s;
+        lineBuffer += s;
+        const lines = lineBuffer.split('\n');
+        lineBuffer = lines.pop();
+        for (const line of lines) {
+          pending = pending.then(() => handleLine(line)).catch(() => {});
+        }
+      });
+
+      proc.on('exit', async (code) => {
+        if (idleTimer) clearTimeout(idleTimer);
+        if (lineBuffer) {
+          pending = pending.then(() => handleLine(lineBuffer)).catch(() => {});
+        }
+        try { await pending; } catch {}
+        delete this._channelProcesses[msgChannel];
+
+        // User asked to stop — swallow output, emit no final answer here (the
+        // stop handler already sent the "stopped" status).
+        if (this._stoppingChannels.has(msgChannel)) {
+          resolve({ text: '', error: null });
+          return;
+        }
+
+        const stdoutText = cleanOutput(stdoutBuf);
+        const stderrText = cleanOutput(stderrBuf);
+        if (stderrText) this._log(`mini-SWE-agent stderr: ${stderrText.length} chars`);
+
+        if (code !== 0) {
+          let diagnostic = classifyError(stderrText, stdoutText);
+          if (!diagnostic) {
+            const tail = (stderrText || stdoutText).split('\n').filter(Boolean);
+            const detail = tail.length ? tail[tail.length - 1] : '';
+            diagnostic = `mini-SWE-agent exited with code ${code}.${detail ? ` ${redactDiagnostic(detail)}` : ''}`;
+          }
+          resolve({ text: '', error: diagnostic });
+          return;
+        }
+
+        // Exit 0: surface the cleaned transcript (tail-capped — mini's closing
+        // summary is at the end). Success ≠ "task definitely fixed", just that
+        // mini ran to completion.
+        let text = stdoutText;
+        if (text.length > FINAL_RESPONSE_MAX) {
+          text = `…(earlier output truncated)…\n\n${text.slice(-FINAL_RESPONSE_MAX)}`;
+        }
+        resolve({ text, error: null });
+      });
+
+      proc.on('error', (err) => {
+        if (idleTimer) clearTimeout(idleTimer);
+        delete this._channelProcesses[msgChannel];
+        reject(err);
+      });
+    });
+  }
+}
+
+module.exports = MiniSweAgentAdapter;

package/src/skill-installer.js

@@ -24,9 +24,16 @@
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+const zlib = require('zlib');
 const { execFileSync } = require('child_process');
 const { defaultAgentWorkdir } = require('./paths');
 
+// Uploaded-skill (.zip) extraction guards. Mirrors the server-side limits in
+// workspace/backend/app/custom_skills.py so both ends agree.
+const MAX_ZIP_ENTRIES = 2000;
+const MAX_ZIP_UNCOMPRESSED_BYTES = 50 * 1024 * 1024; // 50 MB expanded total
+const MAX_ZIP_COMPRESSION_RATIO = 200;               // expanded / stored
+
 /**
  * Resolve the skills directory for a given agent type, rooted at the agent's
  * working directory. Different runtimes look in different places:
@@ -257,6 +264,47 @@ function installSkill({ skill, agentType, workingDir, fetcher, log }) {
   return { path: destDir, skillId: norm.id, partial };
 }
 
+/**
+ * Install a user-uploaded custom skill (source_type=workspace_file) from an
+ * already-downloaded Buffer. Unlike catalog skills, the bytes are provided by
+ * the caller (the adapter downloads them via WorkspaceClient.readFile) — the
+ * installer never touches the network here.
+ *
+ *  - `.md`  → written verbatim as <destDir>/SKILL.md
+ *  - `.zip` → extracted with full path/symlink/zip-bomb validation; a single
+ *             top-level directory is stripped so SKILL.md ends up at the root.
+ *
+ * Reuses installSkill's dest-dir resolution, clean-on-reinstall, and final
+ * SKILL.md verification by passing a synchronous fetcher that writes the Buffer.
+ *
+ * @param {object} args
+ * @param {object} args.skill        metadata (id, package_type, filename, …)
+ * @param {Buffer} args.buffer       the uploaded file bytes
+ * @param {string} args.agentType
+ * @param {string} [args.workingDir]
+ * @param {function} [args.log]
+ * @returns {{path: string, skillId: string, partial: boolean}}
+ */
+function installUploadedSkill({ skill, buffer, agentType, workingDir, log }) {
+  const _log = log || (() => {});
+  if (!Buffer.isBuffer(buffer) || buffer.length === 0) {
+    const id = (skill && (skill.id || skill.skill_id)) || 'unknown';
+    throw new Error(`uploaded skill "${id}" has no file content`);
+  }
+  const packageType = _resolvePackageType(skill, buffer);
+  const fetcher = ({ destDir }) => {
+    if (packageType === 'zip') {
+      _installUploadedZip(buffer, destDir, _log);
+    } else {
+      fs.mkdirSync(destDir, { recursive: true });
+      fs.writeFileSync(path.join(destDir, 'SKILL.md'), buffer);
+      _log('wrote uploaded SKILL.md');
+    }
+    return { partial: false };
+  };
+  return installSkill({ skill, agentType, workingDir, fetcher, log: _log });
+}
+
 /**
  * Remove an installed skill directory. Idempotent.
  *
@@ -363,6 +411,175 @@ function _copyDir(src, dest) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Uploaded-skill (workspace_file) install internals
+// ---------------------------------------------------------------------------
+
+/** Decide md vs zip: declared package_type → zip magic sniff → filename hint. */
+function _resolvePackageType(skill, buffer) {
+  const declared = String((skill && (skill.package_type || skill.packageType)) || '').toLowerCase();
+  if (declared === 'zip' || declared === 'md') return declared;
+  if (Buffer.isBuffer(buffer) && buffer.length >= 2 && buffer[0] === 0x50 && buffer[1] === 0x4b) {
+    return 'zip'; // "PK"
+  }
+  const fn = String((skill && (skill.filename || skill.file_name)) || '').toLowerCase();
+  if (fn.endsWith('.zip')) return 'zip';
+  return 'md';
+}
+
+/** Only a real SKILL.md counts (uploaded zips must ship one, not just any *.md). */
+function _hasSkillMd(dir) {
+  for (const c of ['SKILL.md', 'skill.md', 'Skill.md']) {
+    if (fs.existsSync(path.join(dir, c))) return true;
+  }
+  return false;
+}
+
+// Path safety for a zip entry name. Mirrors _is_unsafe_zip_name in the backend:
+// reject absolute paths, Windows drive paths, and any ".." segment.
+function _isUnsafeZipName(name) {
+  if (!name) return true;
+  if (name.startsWith('/') || name.startsWith('\\')) return true;
+  if (/^[A-Za-z]:/.test(name)) return true;
+  return name.split(/[\\/]/).some((seg) => seg === '..');
+}
+
+function _isSymlinkMode(unixMode) {
+  return (unixMode & 0o170000) === 0o120000; // S_IFLNK
+}
+
+/**
+ * Parse a zip's central directory into entry descriptors. We trust the central
+ * directory (not local headers) for sizes/method, and reject zip64 (skills are
+ * small). Returns [{name, method, compSize, uncompSize, unixMode, localOffset}].
+ */
+function _readZipEntries(buf) {
+  const EOCD_SIG = 0x06054b50;
+  const maxBack = Math.min(buf.length, 22 + 0xffff);
+  let eocd = -1;
+  for (let i = buf.length - 22; i >= buf.length - maxBack && i >= 0; i--) {
+    if (buf.readUInt32LE(i) === EOCD_SIG) { eocd = i; break; }
+  }
+  if (eocd < 0) throw new Error('invalid zip: end-of-central-directory not found');
+
+  const totalEntries = buf.readUInt16LE(eocd + 10);
+  const cdOffset = buf.readUInt32LE(eocd + 16);
+  if (totalEntries === 0xffff || cdOffset === 0xffffffff) {
+    throw new Error('zip64 archives are not supported');
+  }
+
+  const entries = [];
+  let p = cdOffset;
+  for (let n = 0; n < totalEntries; n++) {
+    if (p + 46 > buf.length || buf.readUInt32LE(p) !== 0x02014b50) {
+      throw new Error('invalid zip: corrupt central directory');
+    }
+    const method = buf.readUInt16LE(p + 10);
+    const compSize = buf.readUInt32LE(p + 20);
+    const uncompSize = buf.readUInt32LE(p + 24);
+    const nameLen = buf.readUInt16LE(p + 28);
+    const extraLen = buf.readUInt16LE(p + 30);
+    const commentLen = buf.readUInt16LE(p + 32);
+    const externalAttr = buf.readUInt32LE(p + 38);
+    const localOffset = buf.readUInt32LE(p + 42);
+    if (compSize === 0xffffffff || uncompSize === 0xffffffff || localOffset === 0xffffffff) {
+      throw new Error('zip64 archives are not supported');
+    }
+    const name = buf.toString('utf8', p + 46, p + 46 + nameLen);
+    entries.push({
+      name, method, compSize, uncompSize, localOffset,
+      unixMode: (externalAttr >>> 16) & 0xffff,
+    });
+    p += 46 + nameLen + extraLen + commentLen;
+  }
+  return entries;
+}
+
+/** Read + decompress one entry's bytes (store or deflate only). */
+function _zipEntryData(buf, e) {
+  if (e.localOffset + 30 > buf.length || buf.readUInt32LE(e.localOffset) !== 0x04034b50) {
+    throw new Error(`invalid zip: bad local header for "${e.name}"`);
+  }
+  const nameLen = buf.readUInt16LE(e.localOffset + 26);
+  const extraLen = buf.readUInt16LE(e.localOffset + 28);
+  const start = e.localOffset + 30 + nameLen + extraLen;
+  const end = start + e.compSize;
+  if (end > buf.length) throw new Error(`invalid zip: truncated data for "${e.name}"`);
+  const raw = buf.subarray(start, end);
+  if (e.method === 0) return Buffer.from(raw);          // stored
+  if (e.method === 8) return zlib.inflateRawSync(raw);  // deflate
+  throw new Error(`unsupported zip compression method ${e.method} for "${e.name}"`);
+}
+
+/**
+ * Extract a validated zip Buffer into `outDir`. Enforces entry-count, total-
+ * size and compression-ratio caps, rejects unsafe paths / symlinks, and
+ * verifies every written path stays inside `outDir`.
+ */
+function _extractZipToDir(buffer, outDir, log) {
+  const entries = _readZipEntries(buffer);
+  if (entries.length > MAX_ZIP_ENTRIES) {
+    throw new Error(`zip has too many entries (> ${MAX_ZIP_ENTRIES})`);
+  }
+  let totalUncomp = 0;
+  let totalComp = 0;
+  for (const e of entries) { totalUncomp += e.uncompSize; totalComp += e.compSize; }
+  if (totalUncomp > MAX_ZIP_UNCOMPRESSED_BYTES) {
+    throw new Error('zip expands too large');
+  }
+  if (totalComp > 0 && totalUncomp / totalComp > MAX_ZIP_COMPRESSION_RATIO) {
+    throw new Error('zip compression ratio looks abusive (possible zip bomb)');
+  }
+
+  const root = path.resolve(outDir);
+  fs.mkdirSync(root, { recursive: true });
+  for (const e of entries) {
+    if (_isSymlinkMode(e.unixMode)) throw new Error(`zip contains a symlink entry: "${e.name}"`);
+    if (_isUnsafeZipName(e.name)) throw new Error(`zip contains an unsafe path: "${e.name}"`);
+    const isDir = e.name.endsWith('/');
+    const dest = path.resolve(root, e.name.replace(/\\/g, '/'));
+    if (dest !== root && !dest.startsWith(root + path.sep)) {
+      throw new Error(`zip entry escapes target dir: "${e.name}"`);
+    }
+    if (isDir) { fs.mkdirSync(dest, { recursive: true }); continue; }
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, _zipEntryData(buffer, e));
+  }
+  if (log) log(`extracted ${entries.length} zip entr${entries.length === 1 ? 'y' : 'ies'}`);
+}
+
+/**
+ * Install an uploaded `.zip` into `destDir`: extract to a temp dir, verify a
+ * SKILL.md is present (stripping a single wrapper directory if needed), then
+ * copy the validated tree in. On any failure the temp dir is cleaned up and
+ * nothing partial is written into destDir (installSkill emptied it first).
+ */
+function _installUploadedZip(buffer, destDir, log) {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'oa-skillzip-'));
+  try {
+    _extractZipToDir(buffer, tmp, log);
+
+    // Strip a single top-level wrapper dir (my-skill/SKILL.md → SKILL.md).
+    let srcRoot = tmp;
+    if (!_hasSkillMd(tmp)) {
+      const ents = fs.readdirSync(tmp, { withFileTypes: true });
+      const dirs = ents.filter((e) => e.isDirectory());
+      const files = ents.filter((e) => !e.isDirectory());
+      if (dirs.length === 1 && files.length === 0 && _hasSkillMd(path.join(tmp, dirs[0].name))) {
+        srcRoot = path.join(tmp, dirs[0].name);
+      }
+    }
+    if (!_hasSkillMd(srcRoot)) {
+      throw new Error('uploaded skill .zip has no SKILL.md');
+    }
+
+    fs.mkdirSync(destDir, { recursive: true });
+    _copyDir(srcRoot, destDir);
+  } finally {
+    try { fs.rmSync(tmp, { recursive: true, force: true }); } catch {}
+  }
+}
+
 // Blocking GET used only by defaultFetcher's HTTPS fallback (which runs off
 // the hot path inside a try/catch). Uses curl for redirect handling; returns
 // the body string or throws. git sparse-checkout is the primary strategy, so
@@ -379,6 +596,7 @@ function _httpGetSync(url) {
 module.exports = {
   skillsDirForAgentType,
   installSkill,
+  installUploadedSkill,
   uninstallSkill,
   listInstalledSkills,
   normalizeSkill,

package/src/update-check.js

@@ -115,6 +115,44 @@ function npmPrefixFromBin(npmBin, platform = process.platform) {
   return platform === 'win32' ? binDir : p.dirname(binDir);
 }
 
+/**
+ * Detect when the running launcher lives in an *isolated runtime* — the local
+ * npm project install.sh creates at `~/.openagents/nodejs`, where the package
+ * is at `<dir>/node_modules/@openagents-org/agent-launcher` and `<dir>` has its
+ * own `package.json`.
+ *
+ * This matters because a `-g` install (what a normal global/nvm install needs)
+ * lands in `<dir>/lib/node_modules`, but the isolated runtime's daemon loads
+ * from `<dir>/node_modules` — so `agn update` would report success while the
+ * running code never changed (the acen "update no-op" incident). For an
+ * isolated runtime we must do a *local* install into `<dir>` instead.
+ *
+ * Returns the project dir (`<dir>`) for an isolated runtime, else null (caller
+ * falls back to the global `-g` path). Global/nvm layouts are excluded: their
+ * package sits under `.../lib/node_modules` (basename 'lib') and the prefix
+ * root has no package.json.
+ */
+function isolatedRuntimeDir(opts = {}) {
+  const dir = opts.dir || __dirname; // <pkgRoot>/src
+  const exists = opts.exists || fs.existsSync;
+  // Path impl is injectable so tests can force POSIX/Windows semantics
+  // regardless of the host OS (mirrors npmPrefixFromBin's `platform`).
+  const p = opts.path || path;
+  try {
+    const pkgRoot = p.resolve(dir, '..');              // .../agent-launcher
+    const nodeModules = p.resolve(pkgRoot, '..', '..'); // .../node_modules
+    if (p.basename(nodeModules) !== 'node_modules') return null;
+    const projectDir = p.resolve(nodeModules, '..');    // dir containing node_modules
+    // Global npm layout is <prefix>/lib/node_modules — not an isolated project.
+    if (p.basename(projectDir) === 'lib') return null;
+    // A real local project has its own package.json; a global prefix does not.
+    if (!exists(p.join(projectDir, 'package.json'))) return null;
+    return projectDir;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Locate the npm executable next to the running node binary, falling back to
  * a PATH lookup. On Windows the runnable file is `npm.cmd`; the extensionless
@@ -150,15 +188,28 @@ function runUpdate(opts = {}) {
   const platform = opts.platform || process.platform;
   const spawn = opts.spawn || spawnSync;
   const npmBin = opts.npmBin || findNpmBin({ platform });
-  const prefix = opts.prefix !== undefined ? opts.prefix : npmPrefixFromBin(npmBin, platform);
-  // Use a GLOBAL install (-g). A LOCAL install (`npm install <pkg> --prefix
-  // <dir>`) treats <dir> as a project root and prunes every node_modules entry
-  // not reachable from its package.json. When the prefix is the portable node
-  // dir, that deletes node's own bundled npm/corepack (and other agent runtimes),
-  // breaking every subsequent `agn` command. A global install only adds/updates
-  // the named package into <prefix>/node_modules and never prunes its siblings.
-  const args = ['install', '-g', `${PKG_NAME}@latest`];
-  if (prefix) args.push('--prefix', prefix);
+  const isoDir = opts.isolatedDir !== undefined ? opts.isolatedDir : isolatedRuntimeDir();
+
+  let args;
+  if (isoDir) {
+    // Isolated runtime (install.sh's ~/.openagents/nodejs): a LOCAL npm project
+    // whose package lives in <dir>/node_modules — NOT <dir>/lib/node_modules.
+    // A `-g` install lands in lib/node_modules and silently no-ops the running
+    // launcher/daemon (which loads from node_modules). Install locally into the
+    // project dir instead. `--no-save` leaves package.json untouched (install.sh
+    // owns it), and because <dir>'s package.json already lists our deps npm has
+    // nothing extraneous to prune.
+    args = ['install', '--no-save', `${PKG_NAME}@latest`, '--prefix', isoDir];
+  } else {
+    // Global / nvm install. A LOCAL install (`npm install <pkg> --prefix <dir>`)
+    // here would treat <dir> as a project root and prune every node_modules
+    // entry not reachable from its package.json — deleting node's own bundled
+    // npm/corepack. A global install only adds/updates the named package into
+    // <prefix>/node_modules and never prunes its siblings.
+    const prefix = opts.prefix !== undefined ? opts.prefix : npmPrefixFromBin(npmBin, platform);
+    args = ['install', '-g', `${PKG_NAME}@latest`];
+    if (prefix) args.push('--prefix', prefix);
+  }
 
   // On Windows, npm.cmd is a batch file and must be invoked through cmd.exe.
   // Passing the args via cmd.exe with shell:false lets Node quote paths that
@@ -240,5 +291,6 @@ module.exports = {
   runUpdate,
   findNpmBin,
   npmPrefixFromBin,
+  isolatedRuntimeDir,
   currentVersion,
 };