@addai/node 0.4.0

package/dist/install.js

@@ -0,0 +1,467 @@
+"use strict";
+// Install MCPs + skills + packages into a session's working directory
+// before the agent spawns.
+//
+// MCPs end up in a temp .mcp.json that Claude picks up via
+//   --mcp-config <path> --strict-mcp-config
+// (no global ~/.claude.json mutation — installs are session-scoped and
+//  vanish when the request finishes).
+//
+// Skills are written into <cwd>/.claude/skills/<slug>/SKILL.md (+ any
+// companion files). Claude's CLI scans that directory automatically.
+//
+// Packages are resolved server-side: runtime_resolve_install_set expands
+// each package into its constituent mcp_ids + skill_ids before returning.
+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.LEGACY_MCP_CONFIG_FILENAME = exports.MCP_CONFIG_FILENAME = void 0;
+exports.install = install;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const supabase_client_1 = require("./supabase-client");
+const store_1 = require("./store");
+const win_1 = require("./win");
+/** Hidden per-session MCP config written next to the agent's working dir. */
+exports.MCP_CONFIG_FILENAME = '.ainode.mcp.json';
+/** Pre-rename filename; removed when found so agents don't read a stale copy. */
+exports.LEGACY_MCP_CONFIG_FILENAME = '.entities-runtime.mcp.json';
+const NOOP_RESULT = {
+    mcpConfigPath: null,
+    skillSlugs: [],
+    mcps: [],
+    dispose: async () => { },
+};
+function token() {
+    return (0, store_1.readPairing)()?.daemonToken ?? null;
+}
+async function fetchResolved(set, requestId) {
+    const t = token();
+    if (!t)
+        return { mcps: [], skills: [] };
+    if (set.mcpIds.length === 0 && set.skillIds.length === 0 && set.packageIds.length === 0) {
+        return { mcps: [], skills: [] };
+    }
+    // p_request_id pins credential resolution to THIS request. Without it the
+    // server guesses "latest in-flight request on the runtime", which under
+    // concurrent runs (schedules + chat turns + distils) can hand one entity
+    // ANOTHER request's credentials — the 2026-07-21 wrong-GitHub-PAT incident.
+    const baseArgs = {
+        p_token: t,
+        p_mcp_ids: set.mcpIds,
+        p_skill_ids: set.skillIds,
+        p_package_ids: set.packageIds,
+    };
+    let out;
+    try {
+        out = await (0, supabase_client_1.rpc)('runtime_resolve_install_set', requestId ? { ...baseArgs, p_request_id: requestId } : baseArgs);
+    }
+    catch (err) {
+        // A DB that predates the p_request_id migration rejects the unknown
+        // parameter (PostgREST 404 "function not found"). Degrade to the legacy
+        // runtime-wide heuristic rather than failing the whole install.
+        if (requestId && err instanceof supabase_client_1.RpcError && err.status === 404) {
+            out = await (0, supabase_client_1.rpc)('runtime_resolve_install_set', baseArgs);
+        }
+        else {
+            throw err;
+        }
+    }
+    return {
+        mcps: Array.isArray(out?.mcps) ? out.mcps : [],
+        skills: Array.isArray(out?.skills) ? out.skills : [],
+    };
+}
+function writeMcpConfig(cwd, mcps) {
+    if (mcps.length === 0)
+        return null;
+    const servers = {};
+    for (const m of mcps) {
+        if (!m.slug || !m.command)
+            continue;
+        // Remote MCP servers: registry rows use command='http' (or 'sse') with
+        // args=[url]. An OAuth bearer token rides in the credential as
+        // OAUTH_ACCESS_TOKEN and becomes the Authorization header — this is how
+        // headless sessions use account-authenticated remote MCPs (e.g. the
+        // official Higgsfield server) without an interactive OAuth dance.
+        if (m.command === 'http' || m.command === 'sse') {
+            const url = Array.isArray(m.args) && typeof m.args[0] === 'string' ? m.args[0] : null;
+            if (!url)
+                continue;
+            const entry = { type: m.command, url };
+            const headers = {};
+            const token = m.env?.OAUTH_ACCESS_TOKEN;
+            if (token)
+                headers.Authorization = `Bearer ${token}`;
+            // Other env keys become literal headers (so remote MCPs with custom
+            // header auth work), but OAUTH_* keys are token bookkeeping (refresh
+            // token, expiry) — never send them as request headers.
+            for (const [k, v] of Object.entries(m.env || {})) {
+                if (!v || k.startsWith('OAUTH_'))
+                    continue;
+                headers[k.replace(/_/g, '-')] = v;
+            }
+            if (Object.keys(headers).length > 0)
+                entry.headers = headers;
+            servers[m.slug] = entry;
+            continue;
+        }
+        // On native Windows, registry commands like `npx` are npm .cmd shims
+        // that the agent CLI can't CreateProcess directly — the documented fix
+        // is a `cmd /c` wrapper. No-op on POSIX.
+        const wrapped = (0, win_1.wrapMcpCommandForPlatform)(m.command, Array.isArray(m.args) ? m.args : []);
+        const entry = {
+            command: wrapped.command,
+            args: wrapped.args,
+        };
+        if (m.env && Object.keys(m.env).length > 0) {
+            entry.env = m.env;
+        }
+        servers[m.slug] = entry;
+    }
+    if (Object.keys(servers).length === 0)
+        return null;
+    // Use a hidden sibling file so we can identify + clean up later.
+    // The daemon scopes these files per request id; the caller passes a
+    // unique cwd directory or we'd race ourselves on concurrent sessions
+    // in the same project.
+    const target = path.join(cwd, exports.MCP_CONFIG_FILENAME);
+    // A session dir reused from before the rename can still hold the old file;
+    // leaving it would let an agent read a stale server list.
+    try {
+        fs.rmSync(path.join(cwd, exports.LEGACY_MCP_CONFIG_FILENAME), { force: true });
+    }
+    catch { /* best effort */ }
+    fs.writeFileSync(target, JSON.stringify({ mcpServers: servers }, null, 2));
+    return target;
+}
+function writeSkills(cwd, skills, skillVarValues) {
+    if (skills.length === 0)
+        return { slugs: [], paths: [] };
+    const skillsRoot = path.join(cwd, '.claude', 'skills');
+    fs.mkdirSync(skillsRoot, { recursive: true });
+    const slugs = [];
+    const paths = [];
+    for (const s of skills) {
+        if (!s.slug)
+            continue;
+        const dir = path.join(skillsRoot, s.slug);
+        fs.mkdirSync(dir, { recursive: true });
+        // SKILL.md is the standard entrypoint Claude scans for.
+        const skillMd = path.join(dir, 'SKILL.md');
+        const body = buildSkillMarkdown(s, skillVarValues?.[s.id]);
+        fs.writeFileSync(skillMd, body);
+        paths.push(skillMd);
+        // Companion files (if any). f.path is server-supplied — resolve and
+        // verify containment so '../..'-style or absolute paths can never
+        // escape the skill dir (the old prefix-strip only removed ONE '../').
+        if (Array.isArray(s.files)) {
+            for (const f of s.files) {
+                if (!f.path)
+                    continue;
+                const safeRel = f.path.replace(/^\.\.?[\\/]+/g, '').replace(/[\\/]+/g, path.sep);
+                const dest = path.resolve(dir, safeRel);
+                if (!dest.startsWith(path.resolve(dir) + path.sep)) {
+                    console.error(`[install] skipping skill file with escaping path: ${f.path} (skill ${s.slug})`);
+                    continue;
+                }
+                fs.mkdirSync(path.dirname(dest), { recursive: true });
+                fs.writeFileSync(dest, f.content ?? '');
+                paths.push(dest);
+            }
+        }
+        slugs.push(s.slug);
+    }
+    return { slugs, paths };
+}
+function buildSkillMarkdown(s, values) {
+    // Substitute {{var.<name>}} tokens before wrapping in frontmatter so
+    // values can appear anywhere in the skill body.
+    const content = applySkillVars(s.content ?? '', s, values ?? {});
+    // Skills typically ship with YAML frontmatter that Claude reads
+    // (name + description). Synthesise it if the raw content lacks one.
+    const trimmed = content.trimStart();
+    if (trimmed.startsWith('---'))
+        return content;
+    return `---\nname: ${s.slug}\ndescription: ${(s.description ?? '').replace(/\n/g, ' ')}\n---\n\n${content}`;
+}
+/**
+ * Substitute {{var.<name>}} tokens in a skill's content with the effective
+ * value for that variable. The effective map is the skill's variable
+ * DEFAULTS overlaid by the provided per-node values. Unknown tokens (no
+ * matching var definition or value) resolve to an empty string and log a
+ * console.debug so a typo'd token is traceable.
+ */
+function applySkillVars(content, skill, values) {
+    // Build the effective map: defaults first, then overlay provided values.
+    const effective = {};
+    if (Array.isArray(skill.variables)) {
+        for (const v of skill.variables) {
+            if (v && typeof v.name === 'string') {
+                effective[v.name] = v.default != null ? String(v.default) : '';
+            }
+        }
+    }
+    for (const [k, val] of Object.entries(values || {})) {
+        effective[k] = val != null ? String(val) : '';
+    }
+    return content.replace(/\{\{\s*var\.([a-z0-9_]+)\s*\}\}/gi, (_m, name) => {
+        const key = name.toLowerCase();
+        if (Object.prototype.hasOwnProperty.call(effective, key))
+            return effective[key];
+        console.debug(`[install] skill var token {{var.${name}}} has no matching variable in skill ${skill.slug} (${skill.id})`);
+        return '';
+    });
+}
+/**
+ * Per-cwd install cache. Continuation turns in the same chat usually
+ * hit the same cwd with the same install set; re-resolving + rewriting
+ * .mcp.json each time wastes ~50-100ms. Cache keyed by (cwd, sorted ids
+ * hash, mcp_credentials).
+ *
+ * Bounded LRU — without this, long-lived daemons would accumulate one
+ * entry per distinct cwd ever seen, each holding the full ResolvedMcp /
+ * ResolvedSkill payloads (skill content can be tens of KB each). Map
+ * iteration order is insertion order, so the LRU dance is delete-and-set
+ * on access + delete-oldest when exceeding capacity.
+ */
+const INSTALL_CACHE_MAX = 64;
+const installCache = new Map();
+function touchInstallCache(cwd, entry) {
+    // Move-to-end: delete + set re-positions in iteration order.
+    installCache.delete(cwd);
+    installCache.set(cwd, entry);
+    while (installCache.size > INSTALL_CACHE_MAX) {
+        const oldest = installCache.keys().next().value;
+        if (oldest === undefined)
+            break;
+        installCache.delete(oldest);
+    }
+}
+function cacheKey(cwd, set, credentials, envOverrides, skillVarValues) {
+    const sorted = (arr) => [...(arr || [])].sort().join(',');
+    const credsHash = credentials ? JSON.stringify(credentials) : '';
+    const envHash = envOverrides ? JSON.stringify(envOverrides) : '';
+    // Hash only the values for skills actually in this install set so two
+    // installs with the same effective skill content share a cache entry,
+    // and a DIFFERENT set of values forces a fresh SKILL.md write instead of
+    // reusing a stale one.
+    let varsHash = '';
+    if (skillVarValues && set.skillIds.length > 0) {
+        const relevant = {};
+        for (const id of [...set.skillIds].sort()) {
+            if (skillVarValues[id])
+                relevant[id] = skillVarValues[id];
+        }
+        varsHash = JSON.stringify(relevant);
+    }
+    return `${cwd}|${sorted(set.mcpIds)}|${sorted(set.skillIds)}|${sorted(set.packageIds)}|${credsHash}|${envHash}|${varsHash}`;
+}
+/**
+ * Run install side-effects against `cwd` and return paths to clean up
+ * later. Safe to call with an empty set — returns a no-op result.
+ */
+async function install(cwd, set, credentials, 
+/** Per-session env overrides keyed by MCP slug. Merged into each resolved
+ *  MCP's env BEFORE writing .mcp.json, overriding credential-supplied
+ *  values for the same env var. Used by widgetstudio for dynamic
+ *  streaming auth tokens that can't live in a static vault credential. */
+envOverrides, 
+/** Per-skill variable values keyed by skill id → { varName: value }.
+ *  Overlaid onto each skill's variable defaults and substituted into the
+ *  skill content via {{var.<name>}} tokens before SKILL.md is written. */
+skillVarValues, 
+/** The entity_runtime_requests row being installed. Passed to the server
+ *  so credential resolution is scoped to THIS request instead of the
+ *  latest in-flight request on the runtime. */
+requestId) {
+    if (set.mcpIds.length === 0 && set.skillIds.length === 0 && set.packageIds.length === 0) {
+        return NOOP_RESULT;
+    }
+    // Cache lookup — if this cwd was just installed with the same set,
+    // reuse the files on disk. Make the dispose a no-op so back-to-back
+    // turns don't tear down + rebuild. envOverrides is part of the cache key
+    // because two sessions with different dynamic tokens must NOT share.
+    const key = cacheKey(cwd, set, credentials, envOverrides, skillVarValues);
+    const cached = installCache.get(cwd);
+    if (cached && cached.key === key) {
+        // Verify the files actually exist (defensive — could have been
+        // cleaned by a previous turn's late dispose).
+        if (!cached.result.mcpConfigPath || fs.existsSync(cached.result.mcpConfigPath)) {
+            // Two kinds of content resolve from LIVE server state that the cache
+            // key does NOT capture, so a plain cache hit can serve stale bytes
+            // until the daemon restarts:
+            //   1. MCP env values — the key hashes credential IDs, not their
+            //      values, so a rotated OAuth token (Higgsfield) or a vault-edited
+            //      PAT (GitHub) reads as a hit against a stale .mcp.json.
+            //   2. Skill bodies — the key hashes skill IDs + var values, not the
+            //      SKILL.md content, so editing a skill body never reaches a
+            //      running daemon.
+            // So on EVERY cache hit re-resolve (one RPC) and rewrite whichever of
+            // the two the install has: the .mcp.json and/or the SKILL.md files.
+            // fetchResolved returns both, so covering skills adds no extra RPC when
+            // MCPs are already being refreshed.
+            const hasMcps = (cached.result.mcps || []).length > 0;
+            const hasSkills = (cached.result.skillSlugs || []).length > 0;
+            if (hasMcps || hasSkills) {
+                try {
+                    const fresh = await fetchResolved(set, requestId);
+                    let freshMcpPath = cached.result.mcpConfigPath;
+                    let freshMcps = cached.result.mcps;
+                    if (hasMcps) {
+                        if (envOverrides) {
+                            for (const m of fresh.mcps) {
+                                const ov = envOverrides[m.slug];
+                                if (ov)
+                                    m.env = { ...(m.env || {}), ...ov };
+                            }
+                        }
+                        freshMcps = fresh.mcps;
+                        freshMcpPath = writeMcpConfig(cwd, fresh.mcps) ?? cached.result.mcpConfigPath;
+                    }
+                    let freshSkillSlugs = cached.result.skillSlugs;
+                    if (hasSkills) {
+                        // Skill files write to slug-deterministic paths, so re-writing
+                        // overwrites the same files the cached dispose already tracks.
+                        freshSkillSlugs = writeSkills(cwd, fresh.skills, skillVarValues).slugs;
+                    }
+                    const refreshed = {
+                        ...cached.result,
+                        mcpConfigPath: freshMcpPath,
+                        mcps: freshMcps,
+                        skillSlugs: freshSkillSlugs,
+                    };
+                    touchInstallCache(cwd, { result: refreshed, key });
+                    return { ...refreshed, dispose: async () => { } };
+                }
+                catch (err) {
+                    // Transient resolve failure — fall back to the cached config rather
+                    // than failing the whole install; next run tries again.
+                    console.error('[install] cache-hit refresh failed, using cached config:', err.message);
+                }
+            }
+            // Mark as recently used so LRU keeps it.
+            touchInstallCache(cwd, cached);
+            return { ...cached.result, dispose: async () => { } };
+        }
+    }
+    let resolved;
+    try {
+        resolved = await fetchResolved(set, requestId);
+    }
+    catch (err) {
+        console.error('[install] resolve failed:', err.message);
+        return NOOP_RESULT;
+    }
+    // Merge per-session env overrides into each MCP's env. Override semantics
+    // (overrides win on key conflict) — that's the whole point: a dynamic
+    // token must replace any stale value from the credential.
+    if (envOverrides) {
+        for (const m of resolved.mcps) {
+            const ov = envOverrides[m.slug];
+            if (!ov)
+                continue;
+            m.env = { ...(m.env || {}), ...ov };
+        }
+    }
+    const mcpConfigPath = writeMcpConfig(cwd, resolved.mcps);
+    const skills = writeSkills(cwd, resolved.skills, skillVarValues);
+    const result = {
+        mcpConfigPath,
+        skillSlugs: skills.slugs,
+        mcps: resolved.mcps,
+        dispose: async () => {
+            // We only clean up when a DIFFERENT install set has explicitly
+            // replaced us in the cache — i.e. `current.key !== key` AND
+            // current is defined. If `current` is undefined (cache was wiped
+            // by LRU eviction, daemon restart, etc.) we DO NOT delete: the
+            // session dir might still be in active use, and the daemon's
+            // startup sweep handles 7-day-old orphans separately.
+            //
+            // The previous code deleted on `current === undefined`, which
+            // bit us when a reclaim retry's dispose fired after the in-memory
+            // cache had been wiped (e.g., daemon restart between install +
+            // request completion). The .mcp.json got unlinked before the
+            // NEXT pickup of the same request could even read it.
+            const current = installCache.get(cwd);
+            if (!current)
+                return; // cache wiped — be defensive, don't delete
+            if (current.key === key)
+                return; // still us — keep file
+            // Cache now points at a different install set for this cwd → safe to clean.
+            if (mcpConfigPath) {
+                try {
+                    fs.unlinkSync(mcpConfigPath);
+                }
+                catch { /* already gone */ }
+            }
+            for (const p of skills.paths) {
+                try {
+                    fs.unlinkSync(p);
+                }
+                catch { }
+            }
+            try {
+                rmdirRecursiveIfEmpty(path.join(cwd, '.claude', 'skills'));
+            }
+            catch { }
+            try {
+                rmdirRecursiveIfEmpty(path.join(cwd, '.claude'));
+            }
+            catch { }
+        },
+    };
+    // Replace any previous cache entry for this cwd; the old dispose
+    // will run on its own request's `finally`.
+    touchInstallCache(cwd, { result, key });
+    return result;
+}
+function rmdirRecursiveIfEmpty(dir) {
+    if (!fs.existsSync(dir))
+        return;
+    // First try removing all empty subdirs depth-first.
+    for (const name of fs.readdirSync(dir)) {
+        const child = path.join(dir, name);
+        try {
+            const stat = fs.statSync(child);
+            if (stat.isDirectory())
+                rmdirRecursiveIfEmpty(child);
+        }
+        catch { }
+    }
+    try {
+        fs.rmdirSync(dir);
+    }
+    catch { /* not empty — leave it */ }
+}

package/dist/jsonl-tail.d.ts

@@ -0,0 +1,20 @@
+export interface JsonlTailOptions {
+    timeoutMs?: number;
+    onTimeout?: () => void;
+    pollMs?: number;
+    /** When true and the file already exists, seek to the end before
+     *  tailing so prior contents are not replayed. Use this when attaching
+     *  to a resumed claude session — the JSONL persists across runs and
+     *  re-emitting old events causes the daemon to misinterpret them as
+     *  current-turn activity. Default false. */
+    seekToEnd?: boolean;
+}
+export interface JsonlTailHandle {
+    dispose(): void;
+}
+/**
+ * Tail a JSON-lines file. Calls `onLine` for each newline-terminated
+ * JSON object as it appears. Survives the file not existing yet (Claude
+ * creates the transcript only after the first turn round-trips).
+ */
+export declare function startJsonlTail(filePath: string, onLine: (line: Record<string, unknown>) => void, opts?: JsonlTailOptions): JsonlTailHandle;

package/dist/jsonl-tail.js

@@ -0,0 +1,192 @@
+"use strict";
+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.startJsonlTail = startJsonlTail;
+const fs = __importStar(require("fs"));
+/**
+ * Tail a JSON-lines file. Calls `onLine` for each newline-terminated
+ * JSON object as it appears. Survives the file not existing yet (Claude
+ * creates the transcript only after the first turn round-trips).
+ */
+function startJsonlTail(filePath, onLine, opts = {}) {
+    const pollMs = opts.pollMs ?? 50;
+    let offset = 0;
+    let buffer = '';
+    let disposed = false;
+    let watcher;
+    let initialPoll;
+    let timeoutTimer;
+    let fallbackPoll;
+    function feed(chunk) {
+        buffer += chunk;
+        let nl;
+        while ((nl = buffer.indexOf('\n')) !== -1) {
+            const raw = buffer.slice(0, nl).trim();
+            buffer = buffer.slice(nl + 1);
+            if (!raw)
+                continue;
+            try {
+                onLine(JSON.parse(raw));
+            }
+            catch {
+                /* tolerate malformed lines */
+            }
+        }
+    }
+    function readMore() {
+        if (disposed)
+            return;
+        let fd;
+        try {
+            const stat = fs.statSync(filePath);
+            // File-truncation guard: if the file is smaller than our offset
+            // (claude rewrote / rotated the JSONL) we'd otherwise stall
+            // forever — `stat.size <= offset` keeps short-circuiting reads.
+            // Reset the offset to read from the new top of the file.
+            if (stat.size < offset)
+                offset = 0;
+            if (stat.size <= offset)
+                return;
+            fd = fs.openSync(filePath, 'r');
+            const length = stat.size - offset;
+            const buf = Buffer.alloc(length);
+            fs.readSync(fd, buf, 0, length, offset);
+            offset = stat.size;
+            feed(buf.toString('utf8'));
+        }
+        catch {
+            /* deleted or transient */
+        }
+        finally {
+            if (fd !== undefined)
+                try {
+                    fs.closeSync(fd);
+                }
+                catch { }
+        }
+    }
+    function attachWatcher() {
+        if (disposed || watcher)
+            return;
+        try {
+            watcher = fs.watch(filePath, { persistent: false }, () => readMore());
+        }
+        catch {
+            /* fallback poll below covers a watcher that never attached */
+        }
+        // Safety net alongside (or instead of) the watcher: fs.watch coalesces,
+        // delays, or outright drops append events on some platforms — win32's
+        // ReadDirectoryChangesW especially, and network volumes everywhere. A
+        // cheap statSync every 500ms guarantees the tail always drains, and it
+        // also covers the case where fs.watch threw and was never retried.
+        if (!fallbackPoll) {
+            fallbackPoll = setInterval(() => readMore(), 500);
+            fallbackPoll.unref?.();
+        }
+    }
+    function pollForExistence() {
+        if (disposed)
+            return;
+        if (fs.existsSync(filePath)) {
+            if (timeoutTimer) {
+                clearTimeout(timeoutTimer);
+                timeoutTimer = undefined;
+            }
+            if (opts.seekToEnd) {
+                // Skip everything that's already in the file. The watcher will
+                // pick up new lines from this point on. Without this, resuming
+                // a claude session replays the entire prior transcript as if it
+                // were fresh activity — the daemon's session-runner can't tell
+                // a replayed `claude:last-prompt` from a real one and fires
+                // turn_complete the moment the spawn boots.
+                try {
+                    const stat = fs.statSync(filePath);
+                    offset = stat.size;
+                }
+                catch { /* fall back to offset=0 */ }
+            }
+            else {
+                readMore();
+            }
+            attachWatcher();
+            return;
+        }
+        initialPoll = setTimeout(pollForExistence, pollMs);
+    }
+    pollForExistence();
+    if (opts.timeoutMs && opts.onTimeout) {
+        timeoutTimer = setTimeout(() => {
+            if (disposed || watcher)
+                return;
+            // File hasn't appeared yet — surface the timeout as a UX warning
+            // but KEEP polling. claude TUI is sometimes slow to write the
+            // first line (large system prompt parse, slow MCP startup, agent
+            // taking >30s to produce a token); we don't want to permanently
+            // abandon the file. The spawn's onExit will dispose the tail
+            // when claude eventually exits.
+            opts.onTimeout?.();
+        }, opts.timeoutMs);
+    }
+    return {
+        dispose() {
+            // FINAL SYNCHRONOUS DRAIN before teardown. fs.watch coalesces and the
+            // 500ms fallback poll can both miss the very last append, so tearing
+            // down here without a final read loses the closing JSONL line — the
+            // final assistant_text / result — truncating the reply. readMore()
+            // is fully synchronous (statSync/openSync/readSync → feed → onLine)
+            // and short-circuits once disposed=true, so it MUST run BEFORE we set
+            // the flag. dispose() is called synchronously from the spawn's exit
+            // handler (session-runner onExit → tail.dispose()), so by the time
+            // the process has exited the file is fully flushed and this reads it
+            // to EOF in one pass.
+            try {
+                readMore();
+            }
+            catch { /* best-effort: never throw from teardown */ }
+            disposed = true;
+            if (initialPoll)
+                clearTimeout(initialPoll);
+            if (timeoutTimer)
+                clearTimeout(timeoutTimer);
+            if (fallbackPoll)
+                clearInterval(fallbackPoll);
+            if (watcher)
+                try {
+                    watcher.close();
+                }
+                catch { }
+        },
+    };
+}

package/dist/kimi-binary.d.ts

@@ -0,0 +1,4 @@
+/** Forget the cached lookup — call after an install so a fresh probe
+ *  can see a binary that was missing at daemon start. */
+export declare function resetCache(): void;
+export declare function findKimiBinary(): string | null;