mixdog 0.7.1

package/src/agent/orchestrator/internal-roles.mjs

@@ -0,0 +1,118 @@
+/**
+ * Internal hidden roles — plugin-managed, user-untouchable.
+ *
+ * Unlike user-workflow.json roles (which the user defines and edits freely),
+ * these roles are NEVER exposed to callers of the `bridge` MCP tool. They are
+ * invoked only by internal MCP handlers (explore / recall / search) and carry
+ * their own system prompt + tool-set policy.
+ *
+ * Lookup order (bridge-llm.resolvePresetName):
+ *   1. explicit preset arg
+ *   2. opts.preset
+ *   3. hidden-role registry (defaults/hidden-roles.json) ← plugin-internal
+ *   4. user-workflow.json[role]                          ← user-owned
+ *
+ * Role definitions live in defaults/hidden-roles.json. Editing that file is a
+ * plugin-code change; users cannot break the dispatch path by touching their
+ * workflow JSON.
+ *
+ * The preset names refer to entries seeded in mixdog-config.json (agent.presets)
+ * via DEFAULT_PRESETS (see config.mjs). If the user deletes the referenced preset
+ * from their config the hidden roles degrade gracefully — `resolvePresetName`
+ * returns a name, but session creation will fail with a clear "preset not
+ * found" error rather than silently mis-dispatching.
+ *
+ * Kind classification:
+ *   - 'retrieval'   : short-lived MCP-invoked hidden retrieval roles (explore).
+ *                     BP2 is cache-aligned with public `worker` (collect.mjs).
+ *   - 'maintenance' : background-trigger hidden roles (memory cycle, recap, scheduler,
+ *                     webhook). Receive only their own self section in BP2.
+ *
+ * Permission classification:
+ *   - 'read'       : read-only — write/edit/bash blocked at loop.mjs runtime
+ *                    guard with the same error string public read-only roles see.
+ *   - 'read-write' : full tool surface — used by hidden roles that legitimately
+ *                    mutate state (scheduler-task launches commands,
+ *                    webhook-handler persists payloads). bridge-llm honors this
+ *                    declaratively instead of forcing every hidden role to 'read'.
+ *
+ * Tool schema profile:
+ *   - 'unified'         : shared bridge tool schema for provider cache reuse.
+ *   - 'llm-only'        : no tools exposed; pure transform/classifier roles.
+ */
+
+import { fileURLToPath } from 'url'
+import { readFileSync } from 'fs'
+import { join, dirname } from 'path'
+
+// Load hidden-role definitions from defaults/hidden-roles.json at module
+// initialisation. CLAUDE_PLUGIN_ROOT points to the plugin root directory
+// (same pattern used by bridge-llm.mjs pluginRoot()). Falls back to a
+// path derived from import.meta.url (3 levels up from src/agent/orchestrator/)
+// so tests and standalone scripts work without the env var.
+function _loadHiddenRoles() {
+  const root = process.env.CLAUDE_PLUGIN_ROOT
+    || join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..')
+  try {
+    const raw = JSON.parse(readFileSync(join(root, 'defaults', 'hidden-roles.json'), 'utf8'))
+    const map = Object.create(null)
+    for (const entry of (raw.roles || [])) {
+      if (entry && entry.name) map[entry.name] = Object.freeze({ ...entry })
+    }
+    return Object.freeze(map)
+  } catch (err) {
+    // Fail loudly — a missing or malformed hidden-roles.json breaks dispatch.
+    throw new Error(`[internal-roles] failed to load defaults/hidden-roles.json: ${err.message}`)
+  }
+}
+
+const _HIDDEN_ROLES = _loadHiddenRoles()
+
+/**
+ * Return the hidden-role definition, or null if the name is not internal.
+ */
+export function getHiddenRole(name) {
+  if (!name) return null
+  return _HIDDEN_ROLES[name] || null
+}
+
+/**
+ * Resolve permission stamped on a bridge session. Hidden roles declared
+ * `permission: 'read'` are read-locked — caller opts cannot upgrade them.
+ */
+export function resolveBridgeSessionPermission(role, callerPermission) {
+  const hidden = getHiddenRole(role)
+  if (hidden && hidden.permission === 'read') return 'read'
+  if (callerPermission != null && callerPermission !== '') return callerPermission
+  if (hidden?.permission) return hidden.permission
+  return null
+}
+
+/**
+ * Boolean check — useful for branching inside bridge-llm / session-manager.
+ */
+export function isHiddenRole(name) {
+  if (!name) return false
+  return Object.prototype.hasOwnProperty.call(_HIDDEN_ROLES, name)
+}
+
+/**
+ * List all hidden role names. Used by diagnostics / setup UI guards to ensure
+ * a user-defined role doesn't collide with an internal one.
+ */
+export function listHiddenRoleNames() {
+  return Object.keys(_HIDDEN_ROLES)
+}
+
+/**
+ * List hidden role names matching a given kind ('retrieval' | 'maintenance').
+ * Consumed by collect.mjs to drive BP2 cache shard classification dynamically
+ * instead of hard-coding role-name sets.
+ */
+export function listHiddenRolesByKind(kind) {
+  const out = []
+  for (const [name, def] of Object.entries(_HIDDEN_ROLES)) {
+    if (def.kind === kind) out.push(name)
+  }
+  return out
+}

package/src/agent/orchestrator/internal-tools.mjs

@@ -0,0 +1,88 @@
+/**
+ * Internal tool registry — in-process tools exposed to external LLMs via bridge.
+ *
+ * Populated by agent/index.mjs.handleToolCall when the server injects a
+ * context carrying { toolExecutor, internalTools }. The executor dispatches
+ * to the plugin's existing module router (worker IPC for memory/channels,
+ * in-process loadModule for search). No MCP loopback, no HTTP hop.
+ *
+ * Orchestrator modules (session/manager.mjs, session/loop.mjs) import from
+ * here instead of going through mcp/client.mjs for internal tools.
+ *
+ * Permission enforcement: bridge-worker tool calls (including internal tools)
+ * are gated by _checkWorkerPermission() in session/loop.mjs BEFORE reaching
+ * executeTool() → executeInternalTool(). No duplicate check is needed here;
+ * the loop is the single enforcement point for all dispatch paths.
+ */
+
+let _executor = null;
+let _tools = [];
+let _names = new Set();
+
+let _bootReady = false;
+let _bootResolver = null;
+const _bootPromise = new Promise((r) => { _bootResolver = r; });
+export function markBootReady() { if (_bootReady) return; _bootReady = true; _bootResolver(); }
+export async function awaitBootReady(timeoutMs = 2000) { if (_bootReady) return; await Promise.race([_bootPromise, new Promise((r) => setTimeout(r, timeoutMs))]); }
+
+// Per-tool executor overrides. Populated by addInternalTools() for extra
+// internal tools that bypass the main dispatch (tools.json + dispatchTool).
+const _overrides = new Map();
+
+export function setInternalToolsProvider({ executor, tools }) {
+    if (typeof executor !== 'function') throw new Error('internal-tools: executor must be a function');
+    _executor = executor;
+    const base = Array.isArray(tools) ? [...tools] : [];
+    // Re-registration (handleToolCall idempotent fallback) must preserve any
+    // override-backed tools previously registered via addInternalTools.
+    if (_overrides.size > 0) {
+        const baseNames = new Set(base.map(t => t?.name).filter(Boolean));
+        for (const [name] of _overrides) {
+            if (baseNames.has(name)) continue;
+            const existing = _tools.find(t => t?.name === name);
+            if (existing) base.push(existing);
+        }
+    }
+    _tools = base;
+    _names = new Set(_tools.map(t => t?.name).filter(Boolean));
+}
+
+/**
+ * Register additional tools that aren't declared in tools.json — each comes
+ * with its own executor.
+ *
+ * Re-registration is idempotent; later calls overwrite earlier entries with
+ * the same name.
+ */
+export function getInternalTools() {
+    return _tools;
+}
+
+export function isInternalTool(name) {
+    return _names.has(name);
+}
+
+export async function executeInternalTool(name, args, callerCtx = {}) {
+    if (!_names.has(name)) throw new Error(`internal-tools: "${name}" is not registered`);
+    const override = _overrides.get(name);
+    if (override) {
+        const result = await override(args ?? {}, callerCtx);
+        return _normalize(result);
+    }
+    if (!_executor) throw new Error(`internal-tools: executor not initialized (tool=${name})`);
+    const result = await _executor(name, args ?? {}, callerCtx);
+    return _normalize(result);
+}
+
+// Mirror executeMcpTool's shape normalization so the session loop sees a
+// plain string either way. Worker/module handlers return the MCP-shaped
+// `{ content: [{type:'text', text}] }` envelope directly.
+function _normalize(result) {
+    if (result && typeof result === 'object' && Array.isArray(result.content)) {
+        return result.content
+            .map((c) => (c?.type === 'text' ? c.text || '' : JSON.stringify(c)))
+            .join('\n');
+    }
+    if (typeof result === 'string') return result;
+    return JSON.stringify(result);
+}

package/src/agent/orchestrator/jobs.mjs

@@ -0,0 +1,116 @@
+import { join } from 'path';
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { randomUUID } from 'crypto';
+import { getPluginData } from './config.mjs';
+import { writeJsonAtomicSync } from '../../shared/atomic-file.mjs';
+function getJobsDir() {
+    const dir = join(getPluginData(), 'jobs');
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    return dir;
+}
+function stateFilePath() {
+    return join(getJobsDir(), 'state.json');
+}
+function jobFilePath(jobId) {
+    return join(getJobsDir(), `${jobId}.json`);
+}
+function _readStateFromDisk() {
+    const p = stateFilePath();
+    if (!existsSync(p))
+        return [];
+    try {
+        return JSON.parse(readFileSync(p, 'utf-8'));
+    }
+    catch {
+        return [];
+    }
+}
+
+// In-memory cache + 200ms debounce so a running→stage→done flurry writes once.
+let _stateCache = null;
+let _stateFlushTimer = null;
+function _flushState() {
+    _stateFlushTimer = null;
+    if (_stateCache === null) return;
+    const p = stateFilePath();
+    try {
+        writeJsonAtomicSync(p, _stateCache, { lock: true });
+    } catch { /* best-effort */ }
+}
+function writeState(state) {
+    _stateCache = state;
+    if (_stateFlushTimer) return; // coalesce: latest _stateCache written on flush
+    _stateFlushTimer = setTimeout(_flushState, 200);
+}
+
+export function drainJobs() {
+  if (_stateFlushTimer === null || _stateCache === null) return;
+  clearTimeout(_stateFlushTimer);
+  _flushState();
+}
+// SIGTERM/SIGINT drain runs through drain-registry.mjs; bare 'exit' hook
+// stays as an idempotent backup for cases where the registry already ran.
+process.on('exit', drainJobs);
+
+// Module-level mutex: serializes all state R/M/W in this process.
+let _stateLock = Promise.resolve();
+
+export function createJob(sessionId, prompt, context, { scopeKey, lane } = {}) {
+    const jobId = `job_${randomUUID()}`;
+    const now = new Date().toISOString();
+    const detail = {
+        jobId,
+        sessionId,
+        status: 'running',
+        scopeKey: scopeKey || null,
+        lane: lane || null,
+        request: { prompt, context },
+        startedAt: now,
+    };
+    // Write detail file first (unique path — no contention).
+    writeFileSync(jobFilePath(jobId), JSON.stringify(detail, null, 2));
+    // Mutate _stateCache synchronously so immediate same-process listJobs() sees the new job.
+    const newEntry = { jobId, sessionId, status: 'running', startedAt: now, lane: lane || null };
+    if (_stateCache !== null) {
+        _stateCache.push(newEntry);
+    } else {
+        _stateCache = [..._readStateFromDisk(), newEntry];
+    }
+    // Serialize disk persistence only (cache already updated above).
+    _stateLock = _stateLock.then(() => {
+        try {
+            writeState(_stateCache ?? []);
+        } catch { /* best-effort */ }
+    });
+    return jobId;
+}
+export function completeJob(jobId, result, failed = false) {
+    const now = new Date().toISOString();
+    const status = failed ? 'failed' : 'completed';
+    // Mutate _stateCache synchronously so immediate same-process reads see updated status.
+    if (_stateCache === null) _stateCache = _readStateFromDisk();
+    const syncEntry = _stateCache.find(j => j.jobId === jobId);
+    if (syncEntry) {
+        syncEntry.status = status;
+        syncEntry.finishedAt = now;
+    }
+    // Serialize disk persistence only (cache already updated above).
+    _stateLock = _stateLock.then(() => {
+        try {
+            writeState(_stateCache ?? []);
+        } catch { /* best-effort */ }
+    });
+    // Update detail file
+    const detailPath = jobFilePath(jobId);
+    if (existsSync(detailPath)) {
+        try {
+            const detail = JSON.parse(readFileSync(detailPath, 'utf-8'));
+            detail.status = status;
+            detail.result = result;
+            detail.finishedAt = now;
+            writeFileSync(detailPath, JSON.stringify(detail, null, 2));
+        }
+        catch { /* ignore corrupt file */ }
+    }
+}

package/src/agent/orchestrator/mcp/client.mjs

@@ -0,0 +1,364 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { readFileSync, existsSync, readdirSync, mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { tmpdir, homedir } from 'os';
+import { randomUUID } from 'crypto';
+import { DEFAULT_MARKETPLACE } from '../../../shared/plugin-paths.mjs';
+import { smartReadTruncate } from '../tools/builtin/read-formatting.mjs';
+// --- Types ---
+/** Known auto-detect targets: port file path relative to tmpdir.
+ *  Note: `mixdog` used to self-loopback via active-instance.json's
+ *  httpPort, but that path went through channels' owner HTTP server which
+ *  only exposes a subset of tools. The plugin's own tools are now injected
+ *  in-process through agent's toolExecutor (see orchestrator/internal-tools),
+ *  so this registry is for genuinely external port-based MCP targets only. */
+const AUTO_DETECT_PORTS = {
+    'mixdog-memory': { dir: 'mixdog', file: 'active-instance.json', portField: 'memory_port', endpoint: '/mcp' },
+};
+const DEFAULT_MCP_CALL_TIMEOUT_MS = 0;
+// --- State ---
+const servers = new Map();
+// Memo for mcpToolHasField(name, field) — keyed by `${toolName}|${field}`.
+// The lookup (regex parse + servers Map get + tools.find + schema property
+// inspection) runs on every MCP tool invocation but its result only changes
+// when the servers/tools registry is (re)built. Cleared at every registry
+// mutation point (connectServer / disconnectAll) so a stale positive or
+// negative can never survive a tools-list change.
+const _mcpToolFieldMemo = new Map();
+function _invalidateMcpToolFieldMemo() {
+    _mcpToolFieldMemo.clear();
+}
+// --- Public API ---
+/**
+ * Connect to MCP servers defined in config.
+ * Supports stdio (child process) and http (Streamable HTTP) transports.
+ */
+export async function connectMcpServers(config) {
+    const failures = [];
+    for (const [name, cfg] of Object.entries(config)) {
+        try {
+            await connectServer(name, cfg);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[mcp-client] Failed to connect "${name}": ${msg}\n`);
+            failures.push({ name, msg });
+        }
+    }
+    if (failures.length > 0) {
+        const detail = failures.map(f => `${f.name}: ${f.msg}`).join('; ');
+        throw new Error(`[mcp-client] ${failures.length} MCP server(s) failed to connect — ${detail}`);
+    }
+}
+/**
+ * Get all tool definitions from connected MCP servers.
+ * Tool names are prefixed: `mcp__{serverName}__{toolName}`
+ */
+export function getMcpTools() {
+    const tools = [];
+    for (const server of servers.values()) {
+        tools.push(...server.tools);
+    }
+    return tools;
+}
+/**
+ * Execute an MCP tool call.
+ * Name format: `mcp__{serverName}__{toolName}`
+ */
+export async function executeMcpTool(name, args) {
+    // Parse: mcp__{server}__{tool}
+    const match = name.match(/^mcp__(.+?)__(.+)$/);
+    if (!match)
+        throw new Error(`Not an MCP tool name: ${name}`);
+    const [, serverName, toolName] = match;
+    const server = servers.get(serverName);
+    if (!server)
+        throw new Error(`MCP server "${serverName}" not connected`);
+    let result;
+    try {
+        result = await _callToolWithTimeout(server, toolName, args);
+    } catch (firstErr) {
+        const firstMsg = firstErr instanceof Error ? firstErr.message : String(firstErr);
+        if (isMcpToolCallTimeoutError(firstErr)) {
+            process.stderr.write(`[mcp-client] Tool call timed out; skipping reconnect retry for "${serverName}/${toolName}".\n`);
+            throw firstErr;
+        }
+        process.stderr.write(`[mcp-client] Tool call failed, attempting reconnect...\n`);
+        await new Promise(r => setTimeout(r, 500));
+        try {
+            await server.client.close();
+        } catch { /* ignore close error */ }
+        try {
+            await connectServer(serverName, server.cfg);
+        } catch (reconnectErr) {
+            const reconnectMsg = reconnectErr instanceof Error ? reconnectErr.message : String(reconnectErr);
+            throw new Error(`Tool call failed: ${firstMsg}; reconnect also failed: ${reconnectMsg}`);
+        }
+        const retryServer = servers.get(serverName);
+        if (!retryServer) {
+            throw new Error(`Tool call failed: ${firstMsg}; reconnect succeeded but server "${serverName}" entry is missing from registry`);
+        }
+        try {
+            result = await _callToolWithTimeout(retryServer, toolName, args);
+        } catch (retryErr) {
+            const retryMsg = retryErr instanceof Error ? retryErr.message : String(retryErr);
+            throw new Error(`Tool call failed: ${firstMsg}; retry after reconnect also failed: ${retryMsg}`);
+        }
+    }
+    const content = result.content;
+    let text;
+    if (Array.isArray(content)) {
+        text = content
+            .map((c) => (c.type === 'text' ? c.text || '' : JSON.stringify(c)))
+            .join('\n');
+    } else {
+        text = typeof content === 'string' ? content : JSON.stringify(content);
+    }
+    return capMcpOutput(text);
+}
+
+// MCP per-tool-call timeout. Disabled by default: external MCP tools can be
+// long-running, and replaying an arbitrary tool after a timeout can duplicate
+// side effects. Operators may opt in with MIXDOG_MCP_CALL_TIMEOUT_MS or a
+// per-server timeoutMs/callTimeoutMs config value. On expiry we close the
+// transport so the next dispatch reconnects fresh, but we do not retry the
+// timed-out call automatically.
+export function resolveMcpCallTimeoutMs(cfg = {}, env = process.env) {
+    const raw = cfg?.timeoutMs ?? cfg?.timeout_ms ?? cfg?.callTimeoutMs ?? cfg?.call_timeout_ms
+        ?? env?.MIXDOG_MCP_CALL_TIMEOUT_MS;
+    if (raw == null || raw === '' || raw === false) return DEFAULT_MCP_CALL_TIMEOUT_MS;
+    if (typeof raw === 'string' && /^(0|off|none|false)$/i.test(raw.trim())) return 0;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed <= 0) return DEFAULT_MCP_CALL_TIMEOUT_MS;
+    return Math.round(parsed);
+}
+
+export function isMcpToolCallTimeoutError(err) {
+    return err?.code === 'EMCPTOOLTIMEOUT';
+}
+
+async function _callToolWithTimeout(server, toolName, args) {
+    let timer;
+    const timeoutMs = resolveMcpCallTimeoutMs(server?.cfg);
+    if (!(timeoutMs > 0)) {
+        return server.client.callTool({ name: toolName, arguments: args });
+    }
+    const timeout = new Promise((_, rej) => {
+        timer = setTimeout(() => {
+            try { server.client.close().catch(() => {}); } catch { /* ignore */ }
+            const err = new Error(`MCP tool call timed out after ${timeoutMs}ms (server="${server.name}", tool="${toolName}")`);
+            err.code = 'EMCPTOOLTIMEOUT';
+            err.serverName = server.name;
+            err.toolName = toolName;
+            err.timeoutMs = timeoutMs;
+            rej(err);
+        }, timeoutMs);
+        if (timer.unref) timer.unref();
+    });
+    try {
+        return await Promise.race([
+            server.client.callTool({ name: toolName, arguments: args }),
+            timeout,
+        ]);
+    } finally {
+        if (timer) clearTimeout(timer);
+    }
+}
+
+function countTextLines(text) {
+    const s = String(text ?? '');
+    if (s.length === 0) return 0;
+    let lines = 1;
+    for (let i = 0; i < s.length; i += 1) {
+        if (s.charCodeAt(i) === 10) lines += 1;
+    }
+    return lines;
+}
+
+function capMcpOutput(content) {
+    const s = typeof content === 'string' ? content : String(content ?? '');
+    const bodyBytes = Buffer.byteLength(s, 'utf8');
+    const bodyLines = countTextLines(s);
+    const { text, truncated } = smartReadTruncate(s, bodyLines, bodyBytes);
+    if (!truncated) return text;
+    // Spill the full body to a tmp file so the caller can recover content
+    // elided by the head/tail cap (parity with the prior head-only spill).
+    let spillPath = null;
+    try {
+        const dir = join(tmpdir(), 'mixdog-mcp-output');
+        mkdirSync(dir, { recursive: true });
+        spillPath = join(dir, `mcp-${Date.now()}-${randomUUID().slice(0, 8)}.txt`);
+        writeFileSync(spillPath, s, 'utf-8');
+    } catch { /* spill best-effort */ }
+    const spillNote = spillPath
+        ? `\n\n... [full output spilled to ${spillPath}] ...`
+        : '';
+    return `${text}${spillNote}`;
+}
+/**
+ * Check if a tool name is an MCP tool.
+ */
+export function isMcpTool(name) {
+    return name.startsWith('mcp__');
+}
+/**
+ * Check whether the inputSchema for an MCP tool declares the given top-level
+ * property. Used to decide if the orchestrator should auto-inject context
+ * (e.g. cwd) into the args before dispatch — schemas that don't declare the
+ * field would reject the unknown argument.
+ */
+export function mcpToolHasField(name, field) {
+    const memoKey = `${name}|${field}`;
+    const memoized = _mcpToolFieldMemo.get(memoKey);
+    if (memoized !== undefined) return memoized;
+    const match = name.match(/^mcp__(.+?)__(.+)$/);
+    if (!match) { _mcpToolFieldMemo.set(memoKey, false); return false; }
+    const [, serverName] = match;
+    const server = servers.get(serverName);
+    if (!server) { _mcpToolFieldMemo.set(memoKey, false); return false; }
+    const tool = server.tools.find((t) => t.name === name);
+    if (!tool) { _mcpToolFieldMemo.set(memoKey, false); return false; }
+    const props = tool.inputSchema?.properties;
+    const result = Boolean(props && Object.prototype.hasOwnProperty.call(props, field));
+    _mcpToolFieldMemo.set(memoKey, result);
+    return result;
+}
+/**
+ * Disconnect all MCP servers.
+ */
+export const drainMcpClients = disconnectAll;
+export async function disconnectAll() {
+    for (const [name, server] of servers) {
+        try {
+            await server.client.close();
+        }
+        catch { /* ignore */ }
+        servers.delete(name);
+    }
+    _invalidateMcpToolFieldMemo();
+}
+/**
+ * Load MCP server configs from a JSON file.
+ * Supports both `{ mcpServers: { ... } }` and flat `{ name: { ... } }` format.
+ */
+
+function mcpConfigCommon(c) {
+    const timeout = c?.timeoutMs ?? c?.timeout_ms ?? c?.callTimeoutMs ?? c?.call_timeout_ms;
+    if (timeout == null) return {};
+    return { timeoutMs: resolveMcpCallTimeoutMs({ timeoutMs: timeout }, {}) };
+}
+// --- Internal ---
+function resolvePluginCacheScript(pluginName, script) {
+    const cacheBase = join(homedir(), '.claude', 'plugins', 'cache', DEFAULT_MARKETPLACE, pluginName);
+    if (existsSync(cacheBase)) {
+        const versions = readdirSync(cacheBase).filter(d => /^\d+\.\d+\.\d+/.test(d)).sort((a, b) => {
+            const pa = a.split('.').map(Number), pb = b.split('.').map(Number);
+            return (pa[0] - pb[0]) || (pa[1] - pb[1]) || (pa[2] - pb[2]);
+        });
+        for (let i = versions.length - 1; i >= 0; i--) {
+            const version = versions[i];
+            const dir = join(cacheBase, version);
+            const scriptPath = join(dir, script);
+            if (existsSync(scriptPath)) {
+                return { dir, scriptPath, source: `pluginCache:${pluginName}@${version}` };
+            }
+        }
+    }
+    const marketplaceDir = join(homedir(), '.claude', 'plugins', 'marketplaces', DEFAULT_MARKETPLACE, 'external_plugins', pluginName);
+    const marketplaceScript = join(marketplaceDir, script);
+    if (existsSync(marketplaceScript)) {
+        return { dir: marketplaceDir, scriptPath: marketplaceScript, source: `marketplace:${pluginName}` };
+    }
+    return null;
+}
+
+async function connectServer(name, cfg) {
+    const client = new Client({ name: `mixdog-agent/${name}`, version: '1.0.0' });
+    let transport;
+    // pluginCache: resolve latest cached plugin version as stdio transport
+    if (cfg.pluginCache) {
+        const script = cfg.script || 'scripts/run-mcp.mjs';
+        const resolved = resolvePluginCacheScript(cfg.pluginCache, script);
+        if (!resolved) throw new Error(`Script not found for pluginCache "${cfg.pluginCache}" (${script})`);
+        transport = new StdioClientTransport({
+            command: 'node',
+            args: [resolved.scriptPath],
+            cwd: resolved.dir,
+            env: {
+                ...process.env,
+                CLAUDE_PLUGIN_ROOT: resolved.dir,
+                CLAUDE_PLUGIN_DATA: join(homedir(), '.claude', 'plugins', 'data', `${cfg.pluginCache}-${DEFAULT_MARKETPLACE}`),
+            },
+        });
+        process.stderr.write(`[mcp-client] Connecting "${name}" via ${resolved.source}\n`);
+    }
+    // Auto-detect: read port from a running service's port file
+    else if (cfg.autoDetect) {
+        const spec = AUTO_DETECT_PORTS[cfg.autoDetect];
+        if (!spec)
+            throw new Error(`Unknown autoDetect target: "${cfg.autoDetect}"`);
+        const portFile = spec.dir === 'mixdog' && process.env.MIXDOG_RUNTIME_ROOT
+            ? join(process.env.MIXDOG_RUNTIME_ROOT, spec.file)
+            : join(tmpdir(), spec.dir, spec.file);
+        if (!existsSync(portFile)) {
+            throw new Error(`autoDetect server "${name}": port file missing (${portFile})`);
+        }
+        let port;
+        const raw = readFileSync(portFile, 'utf-8').trim();
+        if (spec.portField) {
+            try {
+                const json = JSON.parse(raw);
+                const v = json[spec.portField];
+                port = (typeof v === 'number' && Number.isFinite(v)) ? v : Number(v);
+                if (!Number.isFinite(port)) {
+                    throw new Error(`autoDetect server "${name}": portField "${spec.portField}" is not numeric in ${portFile}`);
+                }
+            } catch (jsonErr) {
+                if (jsonErr instanceof Error && jsonErr.message.startsWith('autoDetect server')) throw jsonErr;
+                throw new Error(`autoDetect server "${name}": invalid JSON in port file ${portFile}`);
+            }
+        }
+        else {
+            port = parseInt(raw, 10);
+        }
+        if (!Number.isFinite(port) || port < 1 || port > 65535) {
+            throw new Error(`autoDetect server "${name}": invalid port value in ${portFile}`);
+        }
+        const url = `http://127.0.0.1:${port}${spec.endpoint}`;
+        transport = new StreamableHTTPClientTransport(new URL(url));
+        process.stderr.write(`[mcp-client] Connecting "${name}" via autoDetect HTTP: ${url}\n`);
+    }
+    else if (cfg.transport === 'http' && cfg.url) {
+        transport = new StreamableHTTPClientTransport(new URL(cfg.url));
+        process.stderr.write(`[mcp-client] Connecting "${name}" via HTTP: ${cfg.url}\n`);
+    }
+    else if (cfg.command) {
+        transport = new StdioClientTransport({
+            command: cfg.command,
+            args: cfg.args,
+            cwd: cfg.cwd,
+            env: { ...process.env, ...cfg.env },
+        });
+    }
+    else {
+        throw new Error(`Invalid config for "${name}": need autoDetect, url (http), or command (stdio)`);
+    }
+    await client.connect(transport);
+    const toolsResult = await client.listTools();
+    if (!toolsResult || !Array.isArray(toolsResult.tools)) {
+        throw new Error(`[mcp-client] ListTools returned invalid shape for "${name}": missing or non-array tools field`);
+    }
+    const tools = toolsResult.tools.map((t) => ({
+        name: `mcp__${name}__${t.name}`,
+        description: t.description || '',
+        inputSchema: (t.inputSchema || { type: 'object', properties: {} }),
+        ...(t.annotations && typeof t.annotations === 'object' ? { annotations: t.annotations } : {}),
+    }));
+    const mode = cfg.pluginCache ? `pluginCache(${cfg.pluginCache})` : cfg.autoDetect ? `autoDetect(${cfg.autoDetect})` : cfg.transport || 'stdio';
+    const toolNames = tools.map(t => t.name);
+    servers.set(name, { name, client, transport, tools, cfg });
+    _invalidateMcpToolFieldMemo();
+    process.stderr.write(`[mcp] connected: ${tools.length} tools — ${toolNames.join(', ')}\n`);
+}