@addai/node 0.4.0

package/README.md

@@ -0,0 +1,96 @@
+# entities-runtime
+
+A standalone Node.js daemon. Install it on any machine, pair with your
++Ai account, and your account can then run Claude Code / Codex sessions
+on that machine on its behalf — from Vault, from Entity Studio, or from
+anywhere else in +Ai.
+
+## Quick start
+
+```bash
+npx entities-runtime
+```
+
+The first run prints a 5-letter pairing code and a URL:
+
+```
+Pair this runtime with your +Ai account.
+
+  https://vault.add.ai/entity/connect/HDXYC
+
+Enter this code: HDXYC
+```
+
+Open the URL while signed into Vault, enter the code, and the runtime
+starts polling for work. Capabilities (claude, codex, git, node) are
+reported every 30 s.
+
+## Commands
+
+```
+entities-runtime                  run the daemon (foreground)
+entities-runtime status           pairing + capabilities + last-seen
+entities-runtime sessions         recent requests handled (--limit N)
+entities-runtime unpair --yes     disconnect from +Ai
+entities-runtime version          print version
+```
+
+`status` and `sessions` work without the daemon running — they hit
+Supabase directly using the daemon token in
+`~/.entities-runtime/state.json`.
+
+## Architecture
+
+See [`docs/architecture.md`](docs/architecture.md) for the full picture:
+Supabase tables, RPC inventory, request lifecycle, and the cancel-watcher
+flow.
+
+## DiskGuard — Codex scratch-dir disk protection
+
+Each Codex run gets a throwaway `CODEX_HOME` under the OS temp dir
+(`entities-codex-<rand>`). Codex writes its `state_*.sqlite`, logs, caches
+and shell snapshots there — typically 50–350 MB per run. codex-spawn now
+deletes that dir on exit, but a `SIGKILL`, a crash, or an orphan left by a
+previous runtime process can skip that path. On a dedicated host doing
+thousands of runs, those leftovers once grew to ~158 GiB and filled the
+disk (`ENOSPC`, repeated crashes).
+
+**DiskGuard** is the safety net. Like a CCTV DVR overwriting the oldest
+footage when the disk fills, it watches free space on the volume holding
+the temp dir and, when usage crosses a high-water mark, deletes the
+**oldest inactive** scratch dirs — oldest first — until usage drops back
+below a low-water mark, leaving a buffer for the OS. It runs at startup, on
+an interval, and opportunistically right before each new Codex run.
+
+Safety guarantees: it only touches directories directly under the temp root
+whose names match the configured prefix (realpath-validated); it never
+deletes a dir owned by a live session (in-process, or one whose
+`session.lock` PID is still alive) or one younger than the min-age guard;
+and it removes symlink *entries* without following them, so the durable
+`~/.codex` targets behind `sessions`/`auth.json` are never harmed.
+
+Note: DiskGuard can only reclaim space by deleting scratch dirs it owns. If
+a disk is full of *other* data it will evict what it can and log that it
+couldn't reach the target rather than touching anything it doesn't own.
+
+Configure via environment variables (defaults shown):
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `DISKGUARD_ENABLED` | `true` | Master switch for the sweeper. Cleanup-on-exit still runs when `false`. |
+| `DISKGUARD_HIGH_WATER_PCT` | `90` | Start evicting when volume usage reaches this %. |
+| `DISKGUARD_LOW_WATER_PCT` | `80` | Stop evicting once usage drops below this %. Clamped below high-water. |
+| `DISKGUARD_MIN_AGE_MINUTES` | `30` | Never evict a scratch dir younger than this. |
+| `DISKGUARD_CHECK_INTERVAL_SECONDS` | `60` | Periodic sweep cadence. |
+| `DISKGUARD_DRY_RUN` | `false` | Log what would be evicted without deleting anything. |
+| `DISKGUARD_PREFIXES` | `entities-codex-` | Comma-separated dir-name prefixes eligible for eviction. |
+| `DISKGUARD_TEMP_ROOT` | `os.tmpdir()` | Override the watched temp root (mainly for testing). |
+
+## Development
+
+```bash
+npm install
+npm run build
+node dist/cli.js
+npm test        # builds, then runs the node:test suite (see test/)
+```

package/dist/agent-auth.d.ts

@@ -0,0 +1,9 @@
+export type AgentKind = 'claude' | 'claude-tui' | 'claude-bypass' | 'codex' | 'kimi' | 'gemini' | 'grok';
+export interface AuthCheckResult {
+    ok: boolean;
+    /** Short error code for the runtime_events row */
+    code?: 'auth_required';
+    /** Human-readable instruction the user can act on */
+    message?: string;
+}
+export declare function verifyAgentAuth(_agent: AgentKind): AuthCheckResult;

package/dist/agent-auth.js

@@ -0,0 +1,96 @@
+"use strict";
+// Pre-flight auth check for each agent CLI. Fast file-system / env probes
+// only — no subprocess spawn, no network calls — so the cost is sub-ms.
+//
+// Why: every spawn previously assumed the CLI was logged in. If it wasn't,
+// the child started, printed something cryptic to stderr (e.g. "Invalid
+// API key", "401 unauthorized", "please run /login"), and exited non-zero.
+// The user saw an event like `claude_stderr: 401 unauthorized` and had to
+// reverse-engineer what to do.
+//
+// **Fail-open contract**: this check NEVER blocks a spawn unless it has
+// strong evidence the agent is unauthed. The CLIs store credentials in
+// many places (file, env var, macOS keychain, OS-specific config dir),
+// and we can't enumerate them all from Node. So if we don't find a
+// credential AND don't see an explicit env var, we still LET the spawn
+// proceed — the CLI's own auth check is the source of truth. The only
+// time we return ok:false is the negative-knowledge case where we have
+// reason to believe the CLI is definitely unauthed; we currently never
+// hit that case in production. The function exists so future
+// improvements (per-agent `<cli> auth status` shell-outs) can plug in
+// here without re-wiring every spawn path.
+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.verifyAgentAuth = verifyAgentAuth;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const home = () => os.homedir();
+// Treat empty/whitespace files as unauthed (sometimes credential files
+// exist but contain `{}` or got truncated by an interrupted login).
+function fileLooksValid(p) {
+    try {
+        const st = fs.statSync(p);
+        if (!st.isFile())
+            return false;
+        return st.size > 16;
+    }
+    catch {
+        return false;
+    }
+}
+function anyFileLooksValid(paths) {
+    return paths.some(fileLooksValid);
+}
+function envSet(key) {
+    const v = process.env[key];
+    return typeof v === 'string' && v.length > 0;
+}
+function verifyAgentAuth(_agent) {
+    // Fail-open: we used to gate the spawn on the existence of a credential
+    // file (e.g. `~/.claude/.credentials.json`). Claude Code 2.x stores
+    // tokens in the macOS keychain on signed-in machines and the file
+    // doesn't exist — the check produced a false-negative `auth_required`
+    // on every working setup, hard-breaking the runtime.
+    //
+    // Letting the CLI's own auth flow surface the error is preferable: it
+    // emits a clear "please run /login" on stderr, which we forward to the
+    // user as a `<agent>_stderr` event. Not as pretty as a synthetic
+    // `auth_required` event, but it never produces a false-negative.
+    //
+    // The right way to do this in the future is `<cli> auth status` as a
+    // subprocess (which capabilities.ts already does for the heartbeat) —
+    // wire that in here when we're willing to add ~100ms to dispatch.
+    return { ok: true };
+}

package/dist/attachments.d.ts

@@ -0,0 +1,20 @@
+export declare const ATTACHMENTS_DIR = ".entity-attachments";
+export interface AttachmentCandidate {
+    url: string;
+    kind: 'image' | 'file' | 'video';
+}
+/** Pure: pull attachment URLs out of a prompt, markers first, deduped. */
+export declare function extractAttachmentUrls(prompt: string): AttachmentCandidate[];
+/** Pure: derive a safe local filename for a downloaded attachment. */
+export declare function localNameFor(url: string, index: number, contentType?: string): string;
+export type Downloader = (url: string) => Promise<{
+    bytes: Uint8Array;
+    contentType?: string;
+} | null>;
+/**
+ * Download every attachment referenced in the prompt into
+ * `<cwd>/.entity-attachments/` and return the prompt with a note appended
+ * listing the local paths. Returns the prompt unchanged when there is
+ * nothing to fetch or nothing could be fetched.
+ */
+export declare function prepareAttachments(prompt: string, cwd: string, download?: Downloader): Promise<string>;

package/dist/attachments.js

@@ -0,0 +1,164 @@
+"use strict";
+// Chat attachments → local files the agent can actually see.
+//
+// The chatflows dispatch injects attachment references into the prompt as
+// markers — [Image: <url>], [File: <name> — <url>] — and older senders may
+// include bare image URLs. A URL alone gives the model no vision: something
+// has to fetch the bytes. Claude's Read tool renders images and PDFs
+// natively, so we download each referenced file into a scratch dir inside
+// the session cwd and append a note telling the agent where to look. The
+// original URLs stay in the prompt untouched — tools that want URLs
+// (image editing, Drive save) keep working.
+//
+// This replaces the 0.2.36 `--image <url>` flags, which the claude CLI does
+// not support (unknown option → instant exit 1 on every image message).
+//
+// Failure policy: best-effort everywhere. Any download error, oversize file
+// or timeout just skips that file — the prompt is still returned (with the
+// URL as-is) and the run proceeds. This must never block or fail a run.
+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.ATTACHMENTS_DIR = void 0;
+exports.extractAttachmentUrls = extractAttachmentUrls;
+exports.localNameFor = localNameFor;
+exports.prepareAttachments = prepareAttachments;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+exports.ATTACHMENTS_DIR = '.entity-attachments';
+const MAX_FILES = 8;
+const MAX_BYTES = 30 * 1024 * 1024; // per file
+const FETCH_TIMEOUT_MS = 20_000;
+const IMAGE_URL_RE = /https?:\/\/\S+\.(?:jpe?g|png|gif|webp|bmp|avif|svg)(?:\?[^\s\]]*)?(?=[\s\]]|$)/gi;
+// SQL marker: [Image: <url>] / [Video: <url>] / [File: <name> — <url>]
+const MARKER_RE = /\[(Image|File|Video): [^\]]*?(https?:\/\/[^\s\]]+)\]/gi;
+// Content types we never download: audio is pre-transcribed by chatflows,
+// video is too big to be useful to a text/vision agent.
+const SKIP_CONTENT_TYPES = /^(video|audio)\//i;
+const EXT_BY_CONTENT_TYPE = {
+    'image/jpeg': '.jpg',
+    'image/png': '.png',
+    'image/gif': '.gif',
+    'image/webp': '.webp',
+    'image/svg+xml': '.svg',
+    'application/pdf': '.pdf',
+    'text/plain': '.txt',
+    'text/csv': '.csv',
+    'application/json': '.json',
+};
+/** Pure: pull attachment URLs out of a prompt, markers first, deduped. */
+function extractAttachmentUrls(prompt) {
+    const seen = new Set();
+    const out = [];
+    for (const m of prompt.matchAll(MARKER_RE)) {
+        const url = m[2];
+        if (seen.has(url))
+            continue;
+        seen.add(url);
+        out.push({ url, kind: m[1].toLowerCase() });
+    }
+    for (const m of prompt.matchAll(IMAGE_URL_RE)) {
+        const url = m[0];
+        if (seen.has(url))
+            continue;
+        seen.add(url);
+        out.push({ url, kind: 'image' });
+    }
+    return out.filter(c => c.kind !== 'video').slice(0, MAX_FILES);
+}
+/** Pure: derive a safe local filename for a downloaded attachment. */
+function localNameFor(url, index, contentType) {
+    let base = 'attachment';
+    try {
+        base = decodeURIComponent(path.posix.basename(new URL(url).pathname)) || 'attachment';
+    }
+    catch { /* keep fallback */ }
+    base = base.replace(/[^\w.-]+/g, '_').slice(-60);
+    if (!/\.[A-Za-z0-9]{1,5}$/.test(base)) {
+        const ext = contentType ? EXT_BY_CONTENT_TYPE[contentType.split(';')[0].trim().toLowerCase()] : undefined;
+        if (ext)
+            base += ext;
+    }
+    return `${index + 1}-${base}`;
+}
+const defaultDownloader = async (url) => {
+    const res = await fetch(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS), redirect: 'follow' });
+    if (!res.ok)
+        return null;
+    const contentType = res.headers.get('content-type') ?? undefined;
+    if (contentType && SKIP_CONTENT_TYPES.test(contentType))
+        return null;
+    const len = Number(res.headers.get('content-length') ?? '0');
+    if (len > MAX_BYTES)
+        return null;
+    const bytes = new Uint8Array(await res.arrayBuffer());
+    if (bytes.byteLength > MAX_BYTES)
+        return null;
+    return { bytes, contentType };
+};
+/**
+ * Download every attachment referenced in the prompt into
+ * `<cwd>/.entity-attachments/` and return the prompt with a note appended
+ * listing the local paths. Returns the prompt unchanged when there is
+ * nothing to fetch or nothing could be fetched.
+ */
+async function prepareAttachments(prompt, cwd, download = defaultDownloader) {
+    const candidates = extractAttachmentUrls(prompt);
+    if (candidates.length === 0)
+        return prompt;
+    const dir = path.join(cwd, exports.ATTACHMENTS_DIR);
+    const saved = [];
+    for (let i = 0; i < candidates.length; i++) {
+        const { url } = candidates[i];
+        try {
+            const got = await download(url);
+            if (!got)
+                continue;
+            if (saved.length === 0) {
+                fs.mkdirSync(dir, { recursive: true });
+                // Self-ignoring dir so attachments never land in a project repo's
+                // git history when the cwd is a persistent git-backed project.
+                fs.writeFileSync(path.join(dir, '.gitignore'), '*\n');
+            }
+            const rel = `${exports.ATTACHMENTS_DIR}/${localNameFor(url, i, got.contentType)}`;
+            fs.writeFileSync(path.join(cwd, rel), got.bytes);
+            saved.push({ rel, url });
+        }
+        catch { /* skip this file; URL stays usable in the prompt */ }
+    }
+    if (saved.length === 0)
+        return prompt;
+    const lines = saved.map(s => `- ${s.rel}  (source: ${s.url})`);
+    return `${prompt}\n\n[Attached files downloaded locally — use the Read tool on these paths to view them:\n${lines.join('\n')}]`;
+}

package/dist/capabilities.d.ts

@@ -0,0 +1,64 @@
+interface AuthShape {
+    authed: boolean;
+    account?: string;
+    accountKind?: string;
+    plan?: string;
+}
+interface BinaryProbe extends AuthShape {
+    version?: string;
+    available: boolean;
+    /** Model-effort levels this harness accepts (from harness-registry). */
+    efforts?: string[];
+    /** True when the daemon can npm-install this harness remotely. */
+    installable?: boolean;
+    /** How this harness can be logged in: pty-url-code | api-key | on-device. */
+    login_strategy?: string;
+    /** All remote login methods (primary strategy first, then alternates). */
+    login_methods?: string[];
+}
+interface CapabilitiesShape {
+    /** Version of @addai/node running. Lets the studio / CodeFlows
+     *  UIs show "outdated daemon" hints and helps us debug field issues
+     *  ("which version was this row produced by?"). */
+    daemon_version?: string;
+    claude: BinaryProbe & {
+        models?: string[];
+    };
+    codex: BinaryProbe & {
+        models?: string[];
+    };
+    kimi: BinaryProbe & {
+        models?: string[];
+    };
+    gemini: BinaryProbe & {
+        models?: string[];
+    };
+    grok: BinaryProbe & {
+        models?: string[];
+    };
+    git: BinaryProbe;
+}
+/** Codex's credential store: $CODEX_HOME (or ~/.codex) + /auth.json. */
+export declare function codexHome(): string;
+/**
+ * Read auth state straight out of codex's credential file.
+ *
+ * `codex login status` cannot be trusted as the sole signal: on some
+ * installs it prints its "Logged in using ChatGPT" line only when stdio is
+ * a TTY and stays completely silent (exit 0, both streams empty) when the
+ * daemon runs it with pipes — so a logged-in node reported itself logged
+ * out forever, and remote logins "failed" verification after succeeding
+ * (live incident, Lennys-Mac-mini 2026-07-29). The file is written by the
+ * login flow itself, which makes it the fact rather than the commentary.
+ *
+ * Shape (values redacted):
+ *   { auth_mode: 'chatgpt', OPENAI_API_KEY: null,
+ *     tokens: { id_token, access_token, refresh_token, account_id },
+ *     last_refresh }
+ *
+ * Never throws: an unreadable or malformed store simply isn't proof of a
+ * login. Same approach probeKimi already takes for its OAuth store.
+ */
+export declare function codexAuthFromStore(home: string | null): AuthShape;
+export declare function probeCapabilities(): Promise<CapabilitiesShape>;
+export {};