@addai/node 0.4.0

package/dist/kimi-binary.js

@@ -0,0 +1,68 @@
+"use strict";
+// Locate the `kimi` binary on the host. The Moonshot installer drops it
+// at ~/.kimi/bin/kimi by default, but it can also live on PATH or under
+// /usr/local/bin / /opt/homebrew/bin depending on how the user installed.
+// On Windows: kimi.exe under %USERPROFILE%\.kimi\bin, or an npm .cmd shim.
+//
+// Returns null if not present so callers can surface an install hint.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resetCache = resetCache;
+exports.findKimiBinary = findKimiBinary;
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const win_1 = require("./win");
+const POSIX_CANDIDATES = [
+    path.join(os.homedir(), '.kimi', 'bin', 'kimi'), // Moonshot installer default
+    '/usr/local/bin/kimi',
+    '/opt/homebrew/bin/kimi',
+];
+const WIN32_CANDIDATES = [
+    path.join(os.homedir(), '.kimi', 'bin', 'kimi.exe'),
+    path.join(os.homedir(), '.kimi', 'bin', 'kimi.cmd'),
+];
+/** Forget the cached lookup — call after an install so a fresh probe
+ *  can see a binary that was missing at daemon start. */
+function resetCache() { cached = undefined; }
+let cached;
+function findKimiBinary() {
+    if (cached !== undefined)
+        return cached;
+    cached = (0, win_1.findCliBinary)('kimi', {
+        posixCandidates: POSIX_CANDIDATES,
+        win32Candidates: WIN32_CANDIDATES,
+    });
+    return cached;
+}

package/dist/kimi-spawn.d.ts

@@ -0,0 +1,47 @@
+import type { RuntimeEvent, RuntimeEffortLevel } from './types';
+export interface KimiMcpServer {
+    slug: string;
+    command: string;
+    args?: string[] | null;
+    env?: Record<string, string> | null;
+}
+export interface KimiInput {
+    workingDirectory: string;
+    prompt: string;
+    model?: string;
+    /** Resume an existing session (mapped to `--session <id>`). */
+    resumeSessionId?: string;
+    /** Skip approval prompts. Maps to --yolo. */
+    bypassPermissions?: boolean;
+    /** When set, kimi runs against a sandboxed mcp config that contains
+     *  ONLY these MCP servers (host's ~/.kimi/mcp.json suppressed). */
+    mcpServers?: KimiMcpServer[];
+    /** Studio-entity system prompt — kimi doesn't have an explicit
+     *  --system-prompt flag, so we prepend it to the user prompt with a
+     *  separator the model can recognise. */
+    appendSystemPrompt?: string;
+    /** Per-run reasoning effort. The kimi CLI has no verified reasoning-effort
+     *  flag (unlike claude `--effort` / codex `reasoning.effort`), so by
+     *  default this is NOT forwarded — emitting an unsupported flag would make
+     *  every effort-tagged kimi run fail to spawn. The level IS exported as an
+     *  env var (KIMI_REASONING_EFFORT) so a kimi wrapper/config that opts in
+     *  can read it without us guessing at a CLI flag that might not exist. */
+    effortLevel?: RuntimeEffortLevel;
+}
+export interface KimiHandle {
+    pid: number | undefined;
+    sessionId: string | null;
+    kill(): void;
+    onEvent(cb: (e: RuntimeEvent) => void): void;
+    /** Fires on every raw stdout/stderr chunk. kimi emits no per-tool progress
+     *  events, so raw bytes are the only liveness signal during silent tool
+     *  work — the hang-watchdog consumes this to avoid killing a busy agent. */
+    onActivity(cb: () => void): void;
+    done: Promise<number>;
+}
+/** Parse one stream-json line into 0+ RuntimeEvents. Kimi's shapes are
+ *  similar in spirit to claude's: assistant text deltas, tool calls,
+ *  turn completion, and session metadata. Anything we don't recognise
+ *  is forwarded as `kimi:<type>` opaque events. */
+export declare function lineToEvents(line: Record<string, unknown>): RuntimeEvent[];
+export declare function spawnKimi(input: KimiInput): KimiHandle;

package/dist/kimi-spawn.js

@@ -0,0 +1,319 @@
+"use strict";
+// kimi --print --output-format stream-json adapter.
+//
+// Mirrors claude-print.ts: spawns `kimi` non-interactively with a
+// JSONL output stream, parses each line into our normalised RuntimeEvent
+// shape, and resolves on exit. Kimi's stream-json shape is documented
+// upstream but we passthrough unknown event types as `kimi:<type>` for
+// safe forward-compat.
+//
+// Reference: https://moonshotai.github.io/kimi-cli/en/reference/kimi-command.html
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lineToEvents = lineToEvents;
+exports.spawnKimi = spawnKimi;
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const kimi_binary_1 = require("./kimi-binary");
+const win_1 = require("./win");
+const events_1 = require("./events");
+/** Write a sandbox $HOME with an empty .kimi dir so kimi's default
+ *  `~/.kimi/mcp.json` resolves to nothing. Caller is responsible for
+ *  cleanup (we drop it under os.tmpdir() so the OS reaps it). */
+function writeKimiSandboxHome(servers) {
+    const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'entities-kimi-'));
+    fs.mkdirSync(path.join(homeDir, '.kimi'), { mode: 0o700 });
+    const mcpConfig = { mcpServers: {} };
+    for (const s of servers) {
+        if (!s.slug || !s.command)
+            continue;
+        // `cmd /c` wrapper for npm-shim commands on native Windows (no-op on POSIX).
+        const wrapped = (0, win_1.wrapMcpCommandForPlatform)(s.command, Array.isArray(s.args) ? s.args : []);
+        mcpConfig.mcpServers[s.slug] = {
+            command: wrapped.command,
+            ...(wrapped.args.length > 0 ? { args: wrapped.args } : {}),
+            ...(s.env && Object.keys(s.env).length > 0 ? { env: s.env } : {}),
+        };
+    }
+    const mcpConfigPath = path.join(homeDir, '.kimi', 'mcp.json');
+    fs.writeFileSync(mcpConfigPath, JSON.stringify(mcpConfig, null, 2), { mode: 0o600 });
+    return { homeDir, mcpConfigPath };
+}
+/** Parse one stream-json line into 0+ RuntimeEvents. Kimi's shapes are
+ *  similar in spirit to claude's: assistant text deltas, tool calls,
+ *  turn completion, and session metadata. Anything we don't recognise
+ *  is forwarded as `kimi:<type>` opaque events. */
+function lineToEvents(line) {
+    const type = typeof line.type === 'string' ? line.type : '';
+    // Assistant text — kimi emits 'assistant_message' or 'assistant.delta'
+    // depending on version.
+    if (type === 'assistant_message' || type === 'assistant.delta' || type === 'message') {
+        const text = (typeof line.text === 'string' && line.text) ||
+            (typeof line.content === 'string' && line.content) ||
+            (line.delta?.text) ||
+            undefined;
+        if (text)
+            return [{ type: 'assistant_text', delta: text }];
+    }
+    // 'assistant' (claude-shaped block-array) fallback
+    if (type === 'assistant') {
+        const msg = line.message;
+        const content = msg?.content;
+        const out = [];
+        if (Array.isArray(content)) {
+            for (const b of content) {
+                if (b.type === 'text' && typeof b.text === 'string') {
+                    out.push({ type: 'assistant_text', delta: b.text });
+                }
+                else if (b.type === 'tool_use') {
+                    out.push({
+                        type: 'tool_use',
+                        id: String(b.id ?? ''),
+                        name: String(b.name ?? ''),
+                        input: b.input,
+                    });
+                }
+            }
+            return out;
+        }
+        // content is a plain STRING (kimi emits this for text-only turns) — the
+        // old code returned [] here, silently dropping the ENTIRE reply and all
+        // liveness for the turn. Synthesise the assistant_text so the answer
+        // (and heartbeat) survives.
+        if (typeof content === 'string' && content) {
+            return [{ type: 'assistant_text', delta: content }];
+        }
+        // Any other shape → fall through to the opaque passthrough below instead
+        // of being dropped, so we never silently swallow a populated message.
+        return [{ type: `kimi:${type}`, raw: line }];
+    }
+    // Tool result. Kimi's exact tool_result shape isn't verified upstream, so
+    // map the fields we can recognise (claude/gemini use id+content/output) and
+    // otherwise fall through to an opaque passthrough rather than dropping it.
+    if (type === 'tool_result') {
+        const id = String(line.tool_id ?? line.tool_use_id ?? line.id ?? '');
+        const content = line.output ?? line.content ?? line.result;
+        if (id || content !== undefined) {
+            const status = typeof line.status === 'string' ? line.status.toLowerCase() : '';
+            return [{
+                    type: 'tool_result',
+                    id,
+                    content,
+                    isError: line.is_error === true || line.error != null || (status !== '' && status !== 'success'),
+                }];
+        }
+        return [{ type: `kimi:${type}`, raw: line }];
+    }
+    // Turn complete / final message
+    if (type === 'turn_complete' || type === 'final_message' || type === 'result') {
+        return [{
+                type: 'turn_complete',
+                usage: line.usage ?? undefined,
+                stopReason: typeof line.stop_reason === 'string' ? line.stop_reason : undefined,
+            }];
+    }
+    // Errors
+    if (type === 'error' || type === 'turn_failed') {
+        const message = line.error?.message
+            ?? (typeof line.message === 'string' ? line.message : 'kimi error');
+        return [
+            { type: 'error', code: 'kimi_error', message },
+            { type: 'turn_complete', stopReason: 'failed' },
+        ];
+    }
+    // Anything else — opaque passthrough
+    return [{ type: `kimi:${type || 'unknown'}`, raw: line }];
+}
+function spawnKimi(input) {
+    const bin = (0, kimi_binary_1.findKimiBinary)();
+    if (!bin) {
+        // Surface a "kimi not installed" error via the event stream so the
+        // chat fails cleanly instead of hanging. bufferedEvents delivers even
+        // though the runner attaches its listener after an await.
+        const hint = win_1.IS_WINDOWS
+            ? 'kimi CLI is not installed on this runtime. See code.kimi.com for the Windows install.'
+            : 'kimi CLI is not installed on this runtime. Install: curl -L code.kimi.com/install.sh | bash';
+        const events = (0, events_1.bufferedEvents)([
+            { type: 'error', code: 'kimi_not_installed', message: hint },
+            { type: 'turn_complete', stopReason: 'failed' },
+        ]);
+        return {
+            pid: undefined,
+            sessionId: null,
+            kill: () => { },
+            onEvent: events.onEvent,
+            onActivity: () => { },
+            done: Promise.resolve(127),
+        };
+    }
+    // Sandbox the kimi config dir. HOME override means kimi's default
+    // We pass --mcp-config-file explicitly, so kimi reads OUR servers,
+    // not the host's ~/.kimi/mcp.json. The mcp config path can live in a
+    // throwaway temp dir; we no longer need to override HOME.
+    //
+    // The OLD approach (HOME=<tempdir>) was destructive: kimi shells out
+    // to git, pip, etc., and those tools read ~/.gitconfig, ~/.npmrc,
+    // ~/.netrc from HOME. Pointing HOME at an empty dir blew away every
+    // user-level tool config, causing silent tool-call failures
+    // (git push without creds, pip install without index URL).
+    const { homeDir: kimiSandboxDir, mcpConfigPath } = writeKimiSandboxHome(input.mcpServers ?? []);
+    const args = [
+        '--print',
+        '--output-format', 'stream-json',
+        '--work-dir', input.workingDirectory,
+        '--mcp-config-file', mcpConfigPath,
+    ];
+    if (input.resumeSessionId) {
+        args.push('--session', input.resumeSessionId);
+    }
+    if (input.model) {
+        args.push('--model', input.model);
+    }
+    if (input.bypassPermissions) {
+        args.push('--yolo');
+    }
+    // Kimi doesn't have --append-system-prompt; prepend with a separator
+    // the model can recognise as a system-like instruction block.
+    let promptText = input.prompt;
+    if (input.appendSystemPrompt && input.appendSystemPrompt.trim().length > 0) {
+        promptText = `[system]\n${input.appendSystemPrompt.trim()}\n[/system]\n\n${input.prompt}`;
+    }
+    args.push('--prompt', promptText);
+    // No HOME override: the real $HOME flows through so kimi's own auth +
+    // shelled-out tools (git/pip/node) can find their config files. The
+    // explicit --mcp-config-file already prevents host mcp.json leakage.
+    const childEnv = {
+        ...process.env,
+        TERM: 'dumb',
+        // Surface the requested reasoning effort without betting on a CLI flag
+        // that may not exist. A kimi config / wrapper can pick this up; if kimi
+        // ignores it, behaviour is unchanged (no spawn failure).
+        ...(input.effortLevel ? { KIMI_REASONING_EFFORT: input.effortLevel } : {}),
+    };
+    const listeners = [];
+    const emit = (e) => { for (const l of listeners)
+        try {
+            l(e);
+        }
+        catch { } };
+    const activityListeners = [];
+    const touchActivity = () => { for (const l of activityListeners)
+        try {
+            l();
+        }
+        catch { } };
+    let sessionId = null;
+    let buffer = '';
+    let proc;
+    try {
+        // npm .cmd shim → node script (win32); identity on POSIX. Both this
+        // resolution and spawn() itself can throw synchronously on Windows —
+        // fail the request cleanly instead of crashing the daemon.
+        const inv = (0, win_1.resolveCliInvocation)(bin, args);
+        proc = (0, child_process_1.spawn)(inv.file, inv.args, {
+            cwd: input.workingDirectory,
+            env: childEnv,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+    }
+    catch (err) {
+        const msg = err.message || String(err);
+        try {
+            fs.rmSync(kimiSandboxDir, { recursive: true, force: true });
+        }
+        catch { }
+        const events = (0, events_1.bufferedEvents)([
+            { type: 'error', code: 'kimi_spawn_failed', message: msg },
+            { type: 'turn_complete', stopReason: 'failed' },
+        ]);
+        return {
+            pid: undefined,
+            sessionId: null,
+            kill: () => { },
+            onEvent: events.onEvent,
+            onActivity: () => { },
+            done: Promise.resolve(-1),
+        };
+    }
+    proc.stdout?.on('data', (chunk) => {
+        touchActivity();
+        buffer += chunk.toString('utf8');
+        let nl;
+        while ((nl = buffer.indexOf('\n')) !== -1) {
+            const raw = buffer.slice(0, nl).trim();
+            buffer = buffer.slice(nl + 1);
+            if (!raw)
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                continue;
+            }
+            if (typeof parsed.session_id === 'string' && !sessionId)
+                sessionId = parsed.session_id;
+            for (const ev of lineToEvents(parsed))
+                emit(ev);
+        }
+    });
+    proc.stderr?.on('data', (chunk) => {
+        touchActivity();
+        const txt = chunk.toString('utf8').trim();
+        if (txt)
+            emit({ type: 'error', code: 'kimi_stderr', message: txt.slice(0, 4096) });
+    });
+    const done = new Promise((resolve, reject) => {
+        proc.once('error', reject);
+        proc.once('exit', (code) => {
+            // Best-effort cleanup of sandbox tmp dir
+            try {
+                fs.rmSync(kimiSandboxDir, { recursive: true, force: true });
+            }
+            catch { }
+            resolve(code ?? -1);
+        });
+    });
+    return {
+        pid: proc.pid,
+        get sessionId() { return sessionId; },
+        kill: () => { (0, win_1.killProcessTree)(proc); },
+        onEvent: (cb) => { listeners.push(cb); },
+        onActivity: (cb) => { activityListeners.push(cb); },
+        done,
+    };
+}

package/dist/lockfile.d.ts

@@ -0,0 +1,30 @@
+export interface LockfileBody {
+    pid: number;
+    port: number;
+    version: string;
+    startedAt: number;
+}
+/**
+ * Does this command line belong to one of our daemons?
+ *
+ * Kept deliberately broad across the +Ai Node rename: a box mid-roll may
+ * still be running a pre-rename daemon, and treating it as an unrelated
+ * process would let a second daemon start alongside it.
+ */
+export declare function isOwnDaemonCmdline(cmdline: string): boolean;
+/**
+ * Is the pid in the lockfile a live daemon of ours?
+ *
+ * Exported because the CLI's read-only "viewer" path needs the same answer
+ * acquireLockfile() needs: a lockfile left behind by a crashed daemon must
+ * not be mistaken for a running one.
+ */
+export declare function processAlive(pid: number): boolean;
+export declare function readLockfile(): LockfileBody | null;
+/**
+ * Throw if another runtime is already running. Returns the lockfile body
+ * we wrote on success. The caller is responsible for calling
+ * `releaseLockfile()` on clean shutdown.
+ */
+export declare function acquireLockfile(body: Omit<LockfileBody, 'pid'>): LockfileBody;
+export declare function releaseLockfile(): void;

package/dist/lockfile.js

@@ -0,0 +1,169 @@
+"use strict";
+// Tiny lockfile at `~/.ainode/runtime.json`. Written on start
+// (with pid + port + version), polled by the CodeFlows desktop to decide
+// whether the runtime is alive, and unlinked on a clean exit.
+//
+// We trust pid checks via `process.kill(pid, 0)` to detect stale lockfiles
+// from previous crashes — Node throws if the pid doesn't belong to a
+// running process we can signal.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isOwnDaemonCmdline = isOwnDaemonCmdline;
+exports.processAlive = processAlive;
+exports.readLockfile = readLockfile;
+exports.acquireLockfile = acquireLockfile;
+exports.releaseLockfile = releaseLockfile;
+const fs = __importStar(require("fs"));
+const paths_1 = require("./paths");
+function ensureHome() {
+    if (!fs.existsSync(paths_1.RUNTIME_HOME)) {
+        fs.mkdirSync(paths_1.RUNTIME_HOME, { recursive: true, mode: 0o700 });
+    }
+}
+/**
+ * Does this command line belong to one of our daemons?
+ *
+ * Kept deliberately broad across the +Ai Node rename: a box mid-roll may
+ * still be running a pre-rename daemon, and treating it as an unrelated
+ * process would let a second daemon start alongside it.
+ */
+function isOwnDaemonCmdline(cmdline) {
+    const s = cmdline.toLowerCase();
+    if (!s.trim())
+        return false;
+    // Every name this daemon has shipped under. '@addai/node' must be matched
+    // explicitly: its install path reads '.../@addai/node/dist/cli.js', which
+    // contains 'addai/node' but NOT 'ainode', so the bin-name check alone
+    // would call a live daemon stale and let a second one start beside it.
+    // Bare 'node' is deliberately never matched — it is every Node process.
+    return s.includes('@addai/node')
+        || s.includes('addai/node')
+        || s.includes('ainode')
+        || s.includes('entity-runtime')
+        || s.includes('entities-runtime');
+}
+/**
+ * Is the pid in the lockfile a live daemon of ours?
+ *
+ * Exported because the CLI's read-only "viewer" path needs the same answer
+ * acquireLockfile() needs: a lockfile left behind by a crashed daemon must
+ * not be mistaken for a running one.
+ */
+function processAlive(pid) {
+    let signalSucceeded;
+    try {
+        process.kill(pid, 0);
+        signalSucceeded = true;
+    }
+    catch (err) {
+        // ESRCH = no such process. EPERM = exists but not ours.
+        if (err.code !== 'EPERM')
+            return false;
+        signalSucceeded = false; // EPERM: process exists, but it might be a recycled PID owned by root etc.
+    }
+    // Defense against PID recycling: macOS recycles PIDs aggressively. After
+    // a `sudo pkill -9` + restart, the old daemon's PID can be reassigned to
+    // a system process owned by another user. `process.kill(pid, 0)` then
+    // returns EPERM (legitimately — that process IS alive, just not ours)
+    // and the naive check would refuse to start the new daemon forever.
+    // Verify the PID actually points at OUR daemon by checking its command
+    // line for the expected binary name. If the cmdline doesn't include
+    // 'entity-runtime' or 'entities-runtime', the lockfile is stale.
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { execFileSync } = require('child_process');
+        let out;
+        if (process.platform === 'win32') {
+            // No `ps` on Windows; the daemon runs as node.exe so tasklist's image
+            // name can't identify it — read the full command line via CIM.
+            out = execFileSync('powershell.exe', [
+                '-NoProfile', '-NonInteractive', '-Command',
+                `(Get-CimInstance Win32_Process -Filter "ProcessId=${Number(pid)}").CommandLine`,
+            ], { encoding: 'utf8', timeout: 5000, windowsHide: true }).toString().toLowerCase();
+        }
+        else {
+            out = execFileSync('ps', ['-p', String(pid), '-o', 'command='], {
+                encoding: 'utf8',
+                timeout: 2000,
+            }).toString().toLowerCase();
+        }
+        // Both probes exit 0 with empty output if pid is dead — handle that too.
+        if (!out.trim())
+            return false;
+        if (!isOwnDaemonCmdline(out)) {
+            return false; // pid was recycled to an unrelated process
+        }
+        return true;
+    }
+    catch {
+        // ps/powershell failed (timeout, weird platform). Fall back to the
+        // original signal result — better to refuse start than to clobber a
+        // real daemon.
+        return signalSucceeded;
+    }
+}
+function readLockfile() {
+    try {
+        const raw = fs.readFileSync(paths_1.RUNTIME_LOCK_FILE, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.pid !== 'number' || typeof parsed.port !== 'number')
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Throw if another runtime is already running. Returns the lockfile body
+ * we wrote on success. The caller is responsible for calling
+ * `releaseLockfile()` on clean shutdown.
+ */
+function acquireLockfile(body) {
+    ensureHome();
+    const existing = readLockfile();
+    if (existing && processAlive(existing.pid)) {
+        throw new Error(`ainode is already running (pid ${existing.pid}, port ${existing.port}).`);
+    }
+    const final = { pid: process.pid, ...body };
+    fs.writeFileSync(paths_1.RUNTIME_LOCK_FILE, JSON.stringify(final, null, 2), { mode: 0o600 });
+    return final;
+}
+function releaseLockfile() {
+    try {
+        fs.unlinkSync(paths_1.RUNTIME_LOCK_FILE);
+    }
+    catch { }
+}

package/dist/mcp-config.d.ts

@@ -0,0 +1,23 @@
+import { CLAUDE_HOME } from './paths';
+interface RawMcpServer {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    scope?: 'global' | 'project';
+}
+interface McpEntry extends RawMcpServer {
+    name: string;
+    scope: 'global' | 'project';
+}
+/** Best-effort MCP catalog. Used to decide what to whitelist when the
+ *  caller asks for a subset. */
+export declare function listMcps(workingDirectory: string): McpEntry[];
+/**
+ * Write a temp `.mcp.json` containing ONLY the caller-allowed servers,
+ * suitable for `claude --mcp-config <path> --strict-mcp-config`. Returns
+ * null when no filtering is needed (caller wants all visible MCPs).
+ */
+export declare function writeSessionMcpConfig(ptyId: string, workingDirectory: string, enabled: string[] | null): string | null;
+export declare function cleanupSessionMcpConfig(filePath: string | undefined): void;
+export declare function cleanupAllSessionMcpConfigs(): void;
+export { CLAUDE_HOME };