@addai/node 0.4.0

package/dist/mcp-config.js

@@ -0,0 +1,133 @@
+"use strict";
+// Minimal MCP catalog + per-session filtering. Lifted from the desktop's
+// mcp-skills.ts and trimmed: the runtime only needs (a) "is this MCP name
+// installed in the relevant scope?" so we can decide whether to filter,
+// and (b) the ability to write a temp `.mcp.json` whitelisting just the
+// caller-requested servers.
+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.CLAUDE_HOME = void 0;
+exports.listMcps = listMcps;
+exports.writeSessionMcpConfig = writeSessionMcpConfig;
+exports.cleanupSessionMcpConfig = cleanupSessionMcpConfig;
+exports.cleanupAllSessionMcpConfigs = cleanupAllSessionMcpConfigs;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const paths_1 = require("./paths");
+Object.defineProperty(exports, "CLAUDE_HOME", { enumerable: true, get: function () { return paths_1.CLAUDE_HOME; } });
+const CLAUDE_CONFIG = path.join(os.homedir(), '.claude.json');
+function readJson(filePath) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+function extract(obj, scope) {
+    if (!obj)
+        return [];
+    const servers = (obj.mcpServers ?? {});
+    return Object.entries(servers)
+        .filter(([name]) => name !== 'codeflows-mcp-server')
+        .map(([name, s]) => ({ name, scope, command: s.command, args: s.args ?? [], env: s.env ?? {} }));
+}
+/** Best-effort MCP catalog. Used to decide what to whitelist when the
+ *  caller asks for a subset. */
+function listMcps(workingDirectory) {
+    const global = extract(readJson(CLAUDE_CONFIG), 'global');
+    const projectDotMcp = extract(readJson(path.join(workingDirectory, '.mcp.json')), 'project');
+    // Project-scope wins on name collision (matches desktop behavior).
+    const byName = new Map();
+    for (const s of global)
+        byName.set(s.name, s);
+    for (const s of projectDotMcp)
+        byName.set(s.name, s);
+    return Array.from(byName.values());
+}
+/**
+ * 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).
+ */
+function writeSessionMcpConfig(ptyId, workingDirectory, enabled) {
+    if (enabled === null)
+        return null;
+    const all = listMcps(workingDirectory);
+    const allow = new Set(enabled);
+    // Whitelist matches everything visible → no filter needed.
+    if (allow.size === all.length && all.every(s => allow.has(s.name)))
+        return null;
+    const out = {};
+    for (const s of all) {
+        if (!allow.has(s.name))
+            continue;
+        const entry = { command: s.command, args: s.args ?? [] };
+        if (s.env && Object.keys(s.env).length > 0)
+            entry.env = s.env;
+        out[s.name] = entry;
+    }
+    if (!fs.existsSync(paths_1.RUNTIME_SESSIONS_DIR)) {
+        fs.mkdirSync(paths_1.RUNTIME_SESSIONS_DIR, { recursive: true });
+    }
+    const target = path.join(paths_1.RUNTIME_SESSIONS_DIR, `${ptyId}.mcp.json`);
+    fs.writeFileSync(target, JSON.stringify({ mcpServers: out }, null, 2));
+    return target;
+}
+function cleanupSessionMcpConfig(filePath) {
+    if (!filePath)
+        return;
+    try {
+        fs.unlinkSync(filePath);
+    }
+    catch { /* already gone */ }
+}
+// Used at startup to remove stale per-session configs from a previous run.
+function cleanupAllSessionMcpConfigs() {
+    try {
+        if (!fs.existsSync(paths_1.RUNTIME_SESSIONS_DIR))
+            return;
+        for (const name of fs.readdirSync(paths_1.RUNTIME_SESSIONS_DIR)) {
+            if (name.endsWith('.mcp.json')) {
+                try {
+                    fs.unlinkSync(path.join(paths_1.RUNTIME_SESSIONS_DIR, name));
+                }
+                catch { }
+            }
+        }
+    }
+    catch { }
+}

package/dist/memory-capture.d.ts

@@ -0,0 +1,20 @@
+export interface CapturePayload {
+    entity_id: string;
+    request_id: string;
+    surface: string;
+    turn: {
+        user_text: string;
+        assistant_text: string;
+    };
+    transcript_ref: {
+        kind: string;
+        path?: string;
+        host?: string;
+    } | null;
+}
+export declare function buildCapturePayload(req: {
+    entityId: string;
+    requestId: string;
+    surface: string;
+}, userText: string, assistantText: string, transcriptRef: CapturePayload['transcript_ref']): CapturePayload;
+export declare function postCapture(baseUrl: string, serviceToken: string, payload: CapturePayload, timeoutMs?: number): Promise<void>;

package/dist/memory-capture.js

@@ -0,0 +1,45 @@
+"use strict";
+// +Ai Memory (Task 5) — turn-capture payload builder and poster.
+//
+// Called from session-runner.ts's setStatus() 'completed' branch (same
+// hook point as notifySelfImproveIfEnabled) so the DB's
+// entity_studio_aggregate_assistant_text trigger has already aggregated
+// assistant_text for this request before we read it back. Best-effort:
+// postCapture must NEVER throw or slow down request processing — a failed
+// or slow capture must not affect the run in any way.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildCapturePayload = buildCapturePayload;
+exports.postCapture = postCapture;
+function buildCapturePayload(req, userText, assistantText, transcriptRef) {
+    return {
+        entity_id: req.entityId,
+        request_id: req.requestId,
+        surface: req.surface,
+        turn: { user_text: userText.slice(0, 8000), assistant_text: assistantText.slice(0, 12000) },
+        transcript_ref: transcriptRef,
+    };
+}
+async function postCapture(baseUrl, serviceToken, payload, timeoutMs = 5000) {
+    try {
+        const res = await fetch(`${baseUrl}/functions/v1/entity-memory-capture`, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                apikey: serviceToken,
+                authorization: `Bearer ${serviceToken}`,
+            },
+            body: JSON.stringify(payload),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!res.ok) {
+            // fire-and-forget: no retries (capture is lower-stakes than
+            // self-improve), but a non-2xx must never be silently discarded.
+            const text = await res.text().catch(() => '');
+            console.error('[memory-capture] http', res.status, text.slice(0, 200));
+        }
+    }
+    catch (err) {
+        // fire-and-forget: log, never throw (capture must not break runs)
+        console.error('[memory-capture] failed:', err?.message);
+    }
+}

package/dist/memory-pack.d.ts

@@ -0,0 +1,34 @@
+export declare const MEMORY_FALLBACK_MARKER = "\n\n[memory pack unavailable \u2014 memory fallback active]\n";
+export declare function replaceMemoryBlock(systemPrompt: string, packBlock: string): string;
+export declare function buildPackBody(args: {
+    entityId: string;
+    prompt: string;
+    budgetTokens?: number;
+    memberProfileId?: string | null;
+}): Record<string, unknown>;
+export declare function fetchMemoryPack(baseUrl: string, serviceToken: string, args: {
+    entityId: string;
+    prompt: string;
+    budgetTokens?: number;
+    memberProfileId?: string | null;
+}, timeoutMs?: number): Promise<{
+    block: string;
+    degraded: boolean;
+    flagged: boolean;
+}>;
+export declare function resolvePackEntityId(req: {
+    entity_studio_entity_id?: string | null;
+    entity_id?: string | null;
+}): string | null;
+export declare function applyMemoryPack(req: {
+    entity_studio_entity_id?: string | null;
+    entity_id?: string | null;
+    prompt?: string | null;
+    member_profile_id?: string | null;
+}, systemPrompt: string | null, baseUrl: string, serviceToken: string, deps: {
+    /** Overridable for tests; defaults to the real fetchMemoryPack above. */
+    fetchPack?: typeof fetchMemoryPack;
+    buildLegacyManifest: () => Promise<string | null>;
+    onFallback?: () => void;
+    onFlagged?: (flagged: boolean) => void;
+}): Promise<string | null>;

package/dist/memory-pack.js

@@ -0,0 +1,171 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MEMORY_FALLBACK_MARKER = void 0;
+exports.replaceMemoryBlock = replaceMemoryBlock;
+exports.buildPackBody = buildPackBody;
+exports.fetchMemoryPack = fetchMemoryPack;
+exports.resolvePackEntityId = resolvePackEntityId;
+exports.applyMemoryPack = applyMemoryPack;
+// +Ai Memory (Task 7) — semantic memory pack fetcher.
+//
+// Called from session-runner.ts's runRequest in place of the legacy flat
+// DocFlows manifest (buildMemoryManifest). Hits the entity-memory-pack edge
+// function (T6, deployed) which authenticates like entity-self-improve /
+// entity-memory-capture: gateway JWT (anon key as Bearer).
+//
+// Contract with the edge function:
+//   - block === ''      → entity has no memory_v2 pack (unflagged, or
+//                          genuinely nothing to say) → caller falls back to
+//                          the legacy buildMemoryManifest().
+//   - block non-empty   → use it INSTEAD of the legacy manifest.
+//   - any failure (network error, timeout, non-2xx, bad body) → fail LOUD:
+//     return the fallback marker with degraded=true so the caller can both
+//     (a) still inject a marker block into the system prompt so the model
+//     knows its memory is degraded, and (b) emit a `memory_fallback`
+//     runtime event so the failure is visible/observable, never silent.
+exports.MEMORY_FALLBACK_MARKER = '\n\n[memory pack unavailable — memory fallback active]\n';
+// +Ai Memory (post-final-review Finding 2) — dedupe the '## Memory' block.
+//
+// The DB dispatch trigger (entity_memory_recall_inject,
+// supabase/migrations/20260716110000_memory_v2_pack_trigger.sql, in the
+// addai-entity-studio repo) already appends its own budgeted keyword pack
+// to req.system_prompt at INSERT time for every memory_v2-flagged entity —
+// that block always starts with the literal sequence '\n\n## Memory\n' and
+// runs to the end of the string (the trigger appends it last). When this
+// daemon then fetches the richer edge-fn pack (fetchMemoryPack above) and
+// it comes back non-degraded and non-empty, appending it naively gives the
+// model two '## Memory' sections. This helper strips the trigger's
+// trailing block (found via the LAST occurrence of the marker, since the
+// trigger always appends last) before appending the edge-fn pack in its
+// place. Only call this when replacing with a real, non-degraded,
+// non-empty pack — degraded/empty paths must leave system_prompt untouched
+// by this function (empty packBlock is a no-op below).
+function replaceMemoryBlock(systemPrompt, packBlock) {
+    if (!packBlock)
+        return systemPrompt;
+    const base = systemPrompt ?? '';
+    const idx = base.lastIndexOf('\n\n## Memory\n');
+    const stripped = idx !== -1 ? base.slice(0, idx) : base;
+    return stripped && stripped.trim().length > 0 ? `${stripped}\n\n${packBlock}` : packBlock;
+}
+// +Ai Memory (Phase 3 Task 2 — member delivery).
+//
+// Builds the entity-memory-pack POST body. Extracted from fetchMemoryPack
+// so it's independently unit-testable: the null-member path must produce a
+// body with EXACTLY the same keys as pre-phase-3 (byte-identical contract),
+// which is easiest to assert directly on the plain object rather than by
+// scraping a captured HTTP request. `requester` is omitted entirely (not
+// sent as null) when there is no member, so a memberless dispatch's POST
+// body is indistinguishable from the pre-phase-3 shape.
+function buildPackBody(args) {
+    return {
+        entity_id: args.entityId,
+        prompt: args.prompt,
+        budget_tokens: args.budgetTokens,
+        ...(args.memberProfileId ? { requester: { profile_id: args.memberProfileId } } : {}),
+    };
+}
+async function fetchMemoryPack(baseUrl, serviceToken, args, 
+// edge fn steady-state ~600ms, cold start ~950ms; 3s bounds worst-case
+// spawn latency
+timeoutMs = 3000) {
+    try {
+        const r = await fetch(`${baseUrl}/functions/v1/entity-memory-pack`, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                apikey: serviceToken,
+                authorization: `Bearer ${serviceToken}`,
+            },
+            body: JSON.stringify(buildPackBody(args)),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!r.ok)
+            throw new Error(`pack ${r.status}`);
+        const j = (await r.json());
+        // Phase 4 T7: entity-memory-pack returns `skipped:"flag"` distinctly
+        // from a genuinely-empty pack (block === '' either way) — this is the
+        // one reliable, already-happening-every-turn signal for "is this
+        // entity memory_v2-flagged", reused (not re-asked) to gate the
+        // PreCompact hook write (see precompact-hook.ts / session-runner.ts).
+        return { block: j.block ?? '', degraded: false, flagged: j.skipped !== 'flag' };
+    }
+    catch (err) {
+        console.error('[memory-pack] failed:', err?.message);
+        // Unknown on failure — conservatively NOT flagged, so a pack-fetch
+        // outage never causes the PreCompact hook to be written when we
+        // couldn't actually confirm the entity is on the pack.
+        return { block: exports.MEMORY_FALLBACK_MARKER, degraded: true, flagged: false };
+    }
+}
+// +Ai Memory — runtime "entity_id alias" fix (final phase-3 review finding).
+//
+// runtime_pick_next_request (addai-entity-studio/supabase/migrations/
+// 20260718101000_memory_v3_pick_member.sql) `returns entity_runtime_requests`
+// — the BARE table rowtype, via `returning * into v_req; return v_req;`. No
+// jsonb_build_object, no column aliasing. PostgREST therefore serializes the
+// owning-entity column under its real name, `entity_studio_entity_id` — an
+// `entity_id` key never appears on a row from that RPC. The daemon's pack-
+// fetch gate previously read `req.entity_id` only, which meant the richer
+// edge-fn pack fetch below NEVER fired in production; memory only reached
+// entities via the DB dispatch trigger's already-injected '## Memory' block
+// (entity_memory_recall_inject). `entity_id` is kept as a secondary fallback
+// here — never populated by the current pick RPC, but cheap insurance
+// against any future/legacy shape (e.g. runtime_request_get_meta, which
+// DOES alias the column to `entity_id` via jsonb_build_object) that hands
+// this same row shape through a different code path.
+function resolvePackEntityId(req) {
+    return req.entity_studio_entity_id ?? req.entity_id ?? null;
+}
+// Extracted from session-runner.ts's runRequest so the gate → fetch →
+// three-way-switch → replaceMemoryBlock interaction is unit-testable without
+// exercising the rest of the daemon (spawn, install, cwd resolution, …).
+// Mirrors the inline logic byte-for-byte; behavior must not change when this
+// is swapped in at the call site — only WHICH entity id field is read
+// changes (see resolvePackEntityId above).
+//
+//   1. degraded         → fail LOUD: fold the fallback marker AND the legacy
+//                          manifest into system_prompt (never silently drop
+//                          what was already there), and let the caller know
+//                          via onFallback() so it can emit the runtime event.
+//   2. non-empty block  → the richer edge-fn pack REPLACES the DB dispatch
+//                          trigger's already-injected '## Memory' block
+//                          (replaceMemoryBlock, phase-1 B1 dedupe fix) —
+//                          never doubles the section.
+//   3. block === ''     → entity has no pack (unflagged / nothing to
+//                          recall) → legacy manifest, same as before.
+//   no entity id at all → pack fetch never fires; behaves exactly like case
+//                          3 (legacy manifest, or no-op if that's empty/null
+//                          too) — preserves pre-fix behavior for non-entity
+//                          runs byte-for-byte.
+async function applyMemoryPack(req, systemPrompt, baseUrl, serviceToken, deps) {
+    const entityId = resolvePackEntityId(req);
+    const fetchPack = deps.fetchPack ?? fetchMemoryPack;
+    const pack = entityId
+        ? await fetchPack(baseUrl, serviceToken, {
+            entityId,
+            prompt: req.prompt ?? '',
+            memberProfileId: req.member_profile_id ?? null,
+        })
+        : { block: '', degraded: false, flagged: false };
+    deps.onFlagged?.(pack.flagged);
+    if (pack.degraded) {
+        deps.onFallback?.();
+        const legacy = await deps.buildLegacyManifest();
+        const degradedManifest = legacy ? `${pack.block}\n\n${legacy}` : pack.block;
+        if (!degradedManifest)
+            return systemPrompt;
+        return systemPrompt && systemPrompt.trim().length > 0
+            ? `${systemPrompt}\n\n${degradedManifest}`
+            : degradedManifest;
+    }
+    if (pack.block !== '') {
+        return replaceMemoryBlock(systemPrompt ?? '', pack.block);
+    }
+    const legacyManifest = await deps.buildLegacyManifest();
+    if (!legacyManifest)
+        return systemPrompt;
+    return systemPrompt && systemPrompt.trim().length > 0
+        ? `${systemPrompt}\n\n${legacyManifest}`
+        : legacyManifest;
+}

package/dist/model-filter.d.ts

@@ -0,0 +1,4 @@
+export type ModelAgent = 'claude' | 'codex' | 'kimi' | 'gemini' | 'grok';
+/** Returns the model if it plausibly belongs to `agent`, else undefined
+ *  (= use the agent's default). Blank/null → undefined. */
+export declare function modelForAgent(agent: ModelAgent, model: string | null | undefined): string | undefined;

package/dist/model-filter.js

@@ -0,0 +1,34 @@
+"use strict";
+// Guard against stale cross-agent model ids.
+//
+// Chats store a `model` override. When the user switches a chat's AGENT
+// (claude → grok etc.), the stored model tags along and the daemon would
+// pass e.g. `grok --model claude-sonnet-4-5`, which exits 1 ("unknown
+// model id") and the whole turn fails with an opaque error.
+//
+// Every provider's model ids carry a recognisable family prefix, so we
+// drop any override that clearly belongs to a different agent and let the
+// CLI use its own default — a working reply on the agent's default model
+// beats a dead chat. Unknown/future ids that DO match the family pass
+// through untouched; the CLI remains the source of truth for validity.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.modelForAgent = modelForAgent;
+const FAMILY = {
+    claude: /^(claude|sonnet|opus|haiku|fable)/i,
+    codex: /^(gpt|o\d|codex)/i,
+    kimi: /^(kimi|moonshot)/i,
+    gemini: /^gemini/i,
+    grok: /^grok/i,
+};
+/** Returns the model if it plausibly belongs to `agent`, else undefined
+ *  (= use the agent's default). Blank/null → undefined. */
+function modelForAgent(agent, model) {
+    const m = (model ?? '').trim();
+    if (!m)
+        return undefined;
+    if (!FAMILY[agent].test(m)) {
+        console.log(`[model-filter] dropping model '${m}' — not a ${agent} model (stale from an agent switch); using ${agent}'s default`);
+        return undefined;
+    }
+    return m;
+}

package/dist/node-health.d.ts

@@ -0,0 +1,18 @@
+export interface HealthSignals {
+    /** Percentage of the scratch volume used (0-100), or null if unreadable. */
+    diskUsedPct: number | null;
+}
+export interface HealthVerdict {
+    healthy: boolean;
+    blockers: Array<{
+        code: string;
+        message: string;
+    }>;
+}
+export interface HealthOpts {
+    /** Refuse pickup at/above this used-% on the scratch volume. */
+    diskCriticalPct?: number;
+}
+export declare function evaluateNodeHealth(signals: HealthSignals, opts?: HealthOpts): HealthVerdict;
+/** Read used-% of the volume holding `root` via statfs. null if unreadable. */
+export declare function readDiskUsedPct(root: string): number | null;

package/dist/node-health.js

@@ -0,0 +1,74 @@
+"use strict";
+// Pre-flight node health used to gate request pickup. The point is NOT to
+// diagnose everything — it's to stop a node that physically cannot finish a
+// run from ACCEPTING it. When the disk is full, every codex/claude spawn on
+// this node dies with ENOSPC ("No space left on device") — 57+ failures in
+// prod. If we refuse the pickup instead, the request stays `pending` and the
+// server-side failover hands it to a healthy backup, turning a guaranteed
+// failure into a clean failover.
+//
+// Fail-open is the rule: we only block on a signal we can actually read and
+// that is unambiguously fatal. Missing/unreadable info never blocks.
+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.evaluateNodeHealth = evaluateNodeHealth;
+exports.readDiskUsedPct = readDiskUsedPct;
+const fs = __importStar(require("fs"));
+const DEFAULT_DISK_CRITICAL_PCT = 97;
+function evaluateNodeHealth(signals, opts = {}) {
+    const blockers = [];
+    const critical = opts.diskCriticalPct ?? DEFAULT_DISK_CRITICAL_PCT;
+    if (signals.diskUsedPct != null && signals.diskUsedPct >= critical) {
+        blockers.push({
+            code: 'disk_critical',
+            message: `scratch disk ${signals.diskUsedPct.toFixed(0)}% full (>= ${critical}%) — refusing new runs so they fail over to a healthy node`,
+        });
+    }
+    return { healthy: blockers.length === 0, blockers };
+}
+/** Read used-% of the volume holding `root` via statfs. null if unreadable. */
+function readDiskUsedPct(root) {
+    try {
+        const st = fs.statfsSync(root);
+        const blocks = Number(st.blocks);
+        const bavail = Number(st.bavail);
+        if (!Number.isFinite(blocks) || blocks <= 0)
+            return null;
+        return (1 - bavail / blocks) * 100;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/pairing.d.ts

@@ -0,0 +1,20 @@
+interface FinalizeResult {
+    runtime_id: string;
+    daemon_token: string;
+}
+/**
+ * Request a fresh 5-letter pairing code.
+ * Returns the code; the caller is responsible for displaying it.
+ */
+export declare function requestPairCode(): Promise<string>;
+/**
+ * Block until the user has claimed the code at vault.add.ai or until the
+ * code expires. Returns the runtime_id + raw daemon_token on success.
+ * Saves the pairing to ~/.ainode/state.json.
+ */
+export declare function awaitPairing(code: string): Promise<FinalizeResult>;
+/**
+ * Print the human-facing instructions for a fresh pairing.
+ */
+export declare function printPairingInstructions(code: string): void;
+export {};