@jaredboynton/rtinfer 0.1.0

package/bin/rtinferd.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+'use strict';
+
+const { spawnRaw } = require('../src/index');
+
+const result = spawnRaw(process.argv.slice(2));
+if (result.error) {
+  console.error('error: rtinferd native runtime failed to start');
+  process.exit(1);
+}
+process.exit(result.status == null ? 1 : result.status);

package/clients/rtinfer-client.mjs

@@ -0,0 +1,195 @@
+// Canonical rtinfer/1 HTTP client (JS).
+//
+// This is the SOURCE OF TRUTH for the JS client. Consumers vendor or symlink
+// this file; do not fork it. The matching Python client lives at
+// clients/python/rtinfer_client.py and MUST be edited in lockstep when the
+// wire contract changes.
+//
+// The daemon (rtinferd) serves the `rtinfer/1` loopback contract:
+//   POST /v1/infer            { contract, tier, system, user, schema?, schema_name?, model? }
+//   GET  /v1/infer/health     -> { contract, ready, provider, tiers }
+//
+// The daemon is the ONLY inference path: there is no live-realtime fallback.
+// When no daemon is reachable, calls reject with DaemonUnreachable so the
+// orchestrator fails loud (non-zero exit) rather than silently producing
+// zero output.
+//
+// Discovery order (deterministic; no repo imports another):
+//   1. $CSE_RTINFER_URL              explicit override / tests
+//   2. ~/.cse-rtinfer/endpoint.json  rtinferd advertises here on boot (authoritative)
+//   3. http://127.0.0.1:8787         legacy cse-toold cockpit default (transitional)
+//   else: unreachable -> fail loud.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const RTINFER_CONTRACT = "rtinfer/1";
+const CONTRACT_MAJOR = 1;
+const WELL_KNOWN = path.join(os.homedir(), ".cse-rtinfer", "endpoint.json");
+const LEGACY_COCKPIT_DEFAULT = "http://127.0.0.1:8787";
+const POOL_SIZE = Math.max(1, parseInt(process.env.EXPLORE_SEARCH_DAEMON_POOL || "4", 10));
+const SCORER_MODEL = (process.env.EXPLORE_SEARCH_SCORER_MODEL || "gpt-realtime-2").trim();
+const HEALTH_TIMEOUT_MS = Math.round(
+  (parseFloat(process.env.EXPLORE_SEARCH_DAEMON_CONNECT || "") || 0.5) * 1000,
+);
+const REQUEST_TIMEOUT_MS = Math.round(
+  (parseFloat(process.env.EXPLORE_SEARCH_DAEMON_REQUEST || "") || 20.0) * 1000,
+);
+// Synthesis (responses_text, gpt-5.x map-reduce) runs ~30s on a full pack and
+// far longer on a map-reduce, so it gets its own higher ceiling. The realtime
+// navigator/scorer tiers keep the tight 20s timeout above.
+const SYNTH_REQUEST_TIMEOUT_MS = Math.round(
+  (parseFloat(process.env.EXPLORE_SEARCH_DAEMON_SYNTH_REQUEST || "") || 90.0) * 1000,
+);
+
+let _resolved = false;
+let _base = null;
+
+export class DaemonUnreachable extends Error {
+  constructor(message = "no rtinfer daemon reachable") {
+    super(message);
+    this.name = "DaemonUnreachable";
+  }
+}
+
+export function daemonPoolSize() {
+  return POOL_SIZE;
+}
+
+export function scorerModel() {
+  return SCORER_MODEL;
+}
+
+// Accept any rtinfer/<major>.* matching CONTRACT_MAJOR so a minor bump does
+// not dark-fail; a true rtinfer/2 cleanly falls open.
+function contractMajorOk(contract) {
+  if (typeof contract !== "string") return false;
+  const m = /^rtinfer\/(\d+)/.exec(contract);
+  return !!m && parseInt(m[1], 10) === CONTRACT_MAJOR;
+}
+
+function envBool(name) {
+  return ["1", "true", "yes", "on"].includes((process.env[name] || "").trim().toLowerCase());
+}
+
+function healthUrl(base) {
+  return `${base.replace(/\/$/, "")}/v1/infer/health`;
+}
+
+function inferUrl(base) {
+  return `${base.replace(/\/$/, "")}/v1/infer`;
+}
+
+// A daemon is usable only if it answers health with our contract and reports
+// ready (codex auth reachable). `ready:false` means "present but warming" -> we
+// keep probing the next candidate, then the caller retries briefly.
+async function probe(base) {
+  try {
+    const r = await fetch(healthUrl(base), { signal: AbortSignal.timeout(HEALTH_TIMEOUT_MS) });
+    if (!r.ok) return false;
+    const d = await r.json();
+    return d && contractMajorOk(d.contract) && d.ready === true;
+  } catch {
+    return false;
+  }
+}
+
+function candidates() {
+  const out = [];
+  if (process.env.CSE_RTINFER_URL) out.push(process.env.CSE_RTINFER_URL);
+  // Strict mode: trust ONLY the explicit override, no well-known / cockpit
+  // fallback. Default off keeps the documented discovery order. Mirrors the
+  // Python client's CSE_RTINFER_STRICT_URL.
+  if (process.env.CSE_RTINFER_URL && envBool("CSE_RTINFER_STRICT_URL")) return out;
+  try {
+    const d = JSON.parse(fs.readFileSync(WELL_KNOWN, "utf8"));
+    if (d && contractMajorOk(d.contract) && d.base_url) out.push(d.base_url);
+  } catch {
+    /* no well-known file */
+  }
+  out.push(LEGACY_COCKPIT_DEFAULT);
+  return out;
+}
+
+// Resolve the daemon base URL once per process. Returns null when nothing is
+// reachable (the caller decides whether that is fatal).
+export async function discoverEndpoint({ refresh = false } = {}) {
+  if (_resolved && !refresh) return _base;
+  for (const base of candidates()) {
+    // eslint-disable-next-line no-await-in-loop
+    if (await probe(base)) {
+      _base = base;
+      _resolved = true;
+      return _base;
+    }
+  }
+  _base = null;
+  _resolved = true;
+  return null;
+}
+
+// True when a daemon is reachable. Async (was a sync gate-dir check before).
+export async function daemonEnabled() {
+  if (process.env.EXPLORE_SEARCH_DAEMON === "0") return false;
+  return (await discoverEndpoint()) != null;
+}
+
+// Warm-up = discovery probe; the server pool is already hot, so there is no
+// per-process socket to spawn. Returns the base URL or null.
+export async function warmDaemonPool() {
+  return discoverEndpoint();
+}
+
+// POST one rtinfer request. Throws DaemonUnreachable when no daemon is
+// reachable; returns null on a per-request error (so a single bad ask degrades
+// without aborting a batch). `tier` selects the model arm.
+export async function postInfer(tier, body) {
+  const base = await discoverEndpoint();
+  if (!base) throw new DaemonUnreachable();
+  const timeoutMs = tier === "responses_text" ? SYNTH_REQUEST_TIMEOUT_MS : REQUEST_TIMEOUT_MS;
+  let resp;
+  try {
+    resp = await fetch(inferUrl(base), {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ contract: RTINFER_CONTRACT, tier, ...body }),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch (e) {
+    // Transport failure after a successful health probe: the daemon went away
+    // mid-run. Treat as unreachable so the orchestrator fails loud.
+    throw new DaemonUnreachable(`rtinfer request failed: ${e.message}`);
+  }
+  let json = null;
+  try {
+    json = await resp.json();
+  } catch {
+    return null;
+  }
+  if (!resp.ok || !json || json.ok !== true) return null;
+  return tier === "responses_text" ? json.text : json.object;
+}
+
+// One structured realtime ask (navigator / scorer). Returns the parsed object
+// or null on a per-request error.
+export async function daemonAsk(namespace, req, { model = SCORER_MODEL } = {}) {
+  return postInfer("realtime_structured", {
+    system: req.system,
+    user: req.user,
+    schema: req.schema,
+    schema_name: req.schemaName || req.schema_name || "result",
+    model,
+    reasoning_effort: req.reasoningEffort,
+  });
+}
+
+// Batch of structured realtime asks. True parallelism comes from the server
+// pool's semaphore; the client just fans out concurrent fetches. Per-request
+// errors surface as null elements; total unreachability throws.
+export async function daemonAskBatch(namespace, requests, { model = SCORER_MODEL } = {}) {
+  // Probe once up front so an unreachable daemon throws before fan-out instead
+  // of N times in parallel.
+  const base = await discoverEndpoint();
+  if (!base) throw new DaemonUnreachable();
+  return Promise.all(requests.map((req) => daemonAsk(namespace, req, { model })));
+}

package/clients/rtinfer_client.py

@@ -0,0 +1,226 @@
+#!/usr/bin/env python3
+"""Canonical rtinfer/1 HTTP client (Python).
+
+SOURCE OF TRUTH for the Python client. Consumers vendor or symlink this file;
+do not fork it. The matching JS client lives at clients/js/rtinfer-client.mjs
+and MUST be edited in lockstep when the wire contract changes.
+
+The daemon (rtinferd) serves the `rtinfer/1` loopback contract:
+  POST /v1/infer            {contract, tier, system, user, schema?, schema_name?, model?}
+  GET  /v1/infer/health     -> {contract, ready, provider, tiers}
+
+This is a *preferred* path for borrowing the shared daemon, never a required
+one when used as a fallback layer: any unreachability, timeout, or non-OK
+envelope returns ``(None, None)`` so callers can fall through to their own
+inference path.
+
+Discovery order (matches clients/js/rtinfer-client.mjs):
+  1. $CSE_RTINFER_URL              explicit override / tests
+  2. ~/.cse-rtinfer/endpoint.json  rtinferd advertises here on boot (authoritative)
+  3. http://127.0.0.1:8787         legacy cse-toold cockpit default (transitional)
+
+The health gate accepts any rtinfer/1.x (major-1 match), so a minor bump does
+not dark-fail; a true rtinfer/2 cleanly falls open.
+
+Stdlib only: urllib + json.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+CONTRACT = "rtinfer/1"
+_CONTRACT_MAJOR = 1
+_LEGACY_COCKPIT_DEFAULT = "http://127.0.0.1:8787"
+_WELL_KNOWN = Path.home() / ".cse-rtinfer" / "endpoint.json"
+
+
+def _contract_major_ok(contract: Any) -> bool:
+    """True when ``contract`` is rtinfer/<major>.* matching _CONTRACT_MAJOR."""
+    if not isinstance(contract, str):
+        return False
+    m = re.match(r"^rtinfer/(\d+)", contract)
+    return bool(m) and int(m.group(1)) == _CONTRACT_MAJOR
+
+
+def _debug_log(msg: str) -> None:
+    if (os.environ.get("UNIFABLE_DEBUG") or os.environ.get("DEBUG") or "").strip():
+        try:
+            sys.stderr.write(f"[rtinfer] {msg}\n")
+        except OSError:
+            pass
+
+
+def _env_float(name: str, default: float) -> float:
+    try:
+        return float(os.environ.get(name) or default)
+    except (TypeError, ValueError):
+        return default
+
+
+HEALTH_TIMEOUT = _env_float("CSE_RTINFER_HEALTH_TIMEOUT", 0.5)
+REQUEST_TIMEOUT = _env_float("CSE_RTINFER_REQUEST_TIMEOUT", 95.0)
+# Re-discovery is cheap but not free; cache the resolved base for this process.
+_DISCOVERY_TTL = _env_float("CSE_RTINFER_DISCOVERY_TTL", 30.0)
+
+_resolved_at = 0.0
+_resolved_base: str | None = None
+
+
+def _env_bool(name: str) -> bool:
+    return (os.environ.get(name) or "").strip().lower() in ("1", "true", "yes", "on")
+
+
+def _candidates() -> list[str]:
+    out: list[str] = []
+    override = os.environ.get("CSE_RTINFER_URL")
+    if override:
+        out.append(override.strip())
+    # Strict mode: trust ONLY the explicit override, no well-known / cockpit
+    # fallback. Default off keeps the documented discovery order.
+    if override and _env_bool("CSE_RTINFER_STRICT_URL"):
+        return out
+    try:
+        data = json.loads(_WELL_KNOWN.read_text("utf-8"))
+        if isinstance(data, dict) and _contract_major_ok(data.get("contract")) and data.get("base_url"):
+            out.append(str(data["base_url"]).strip())
+    except (OSError, ValueError):
+        pass
+    out.append(_LEGACY_COCKPIT_DEFAULT)
+    return out
+
+
+def _health_ok(base: str) -> bool:
+    url = base.rstrip("/") + "/v1/infer/health"
+    try:
+        with urllib.request.urlopen(url, timeout=HEALTH_TIMEOUT) as resp:  # noqa: S310 (loopback only)
+            if resp.status != 200:
+                return False
+            data = json.loads(resp.read().decode("utf-8"))
+    except (urllib.error.URLError, OSError, ValueError, TimeoutError):
+        return False
+    if not isinstance(data, dict):
+        return False
+    if not _contract_major_ok(data.get("contract")):
+        if data.get("contract"):
+            _debug_log(f"contract mismatch at {base}: {data.get('contract')} (want rtinfer/{_CONTRACT_MAJOR}.x)")
+        return False
+    return data.get("ready") is True
+
+
+def discover(refresh: bool = False) -> str | None:
+    """Resolve a ready rtinfer base URL, or None. Cached for _DISCOVERY_TTL."""
+    global _resolved_at, _resolved_base
+    now = time.monotonic()
+    if not refresh and _resolved_base is not None and (now - _resolved_at) < _DISCOVERY_TTL:
+        return _resolved_base
+    for base in _candidates():
+        if _health_ok(base):
+            _resolved_base = base.rstrip("/")
+            _resolved_at = now
+            return _resolved_base
+    _resolved_base = None
+    _resolved_at = now
+    return None
+
+
+def ask_structured(
+    system: str,
+    user: str,
+    schema: dict[str, Any],
+    *,
+    schema_name: str = "result",
+    model: str | None = None,
+    timeout: float = REQUEST_TIMEOUT,
+) -> tuple[dict[str, Any] | None, dict[str, int] | None]:
+    """One structured ask over the shared daemon's realtime tier. Returns
+    ``(object, usage)`` on success, ``(None, None)`` to signal fallback.
+
+    ``usage`` is always None: the loopback endpoint does not surface token
+    counts, and the borrow path is off the correctness/measurement path."""
+    base = discover()
+    if base is None:
+        return None, None
+    body = {
+        "contract": CONTRACT,
+        "tier": "realtime_structured",
+        "system": system,
+        "user": user,
+        "schema": schema,
+        "schema_name": schema_name,
+    }
+    if model:
+        body["model"] = model
+    payload = json.dumps(body).encode("utf-8")
+    req = urllib.request.Request(
+        base + "/v1/infer",
+        data=payload,
+        headers={"content-type": "application/json"},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:  # noqa: S310 (loopback only)
+            data = json.loads(resp.read().decode("utf-8"))
+    except (urllib.error.URLError, OSError, ValueError, TimeoutError):
+        # Daemon went away mid-run: invalidate so the next call re-discovers.
+        _invalidate()
+        return None, None
+    if not isinstance(data, dict) or data.get("ok") is not True:
+        return None, None
+    obj = data.get("object")
+    if not isinstance(obj, dict):
+        return None, None
+    return obj, None
+
+
+def ask_text(
+    system: str,
+    user: str,
+    *,
+    model: str | None = None,
+    timeout: float = REQUEST_TIMEOUT,
+) -> str | None:
+    """One freeform-text ask over the shared daemon's responses_text tier.
+    Returns the assembled text on success, ``None`` to signal fallback."""
+    base = discover()
+    if base is None:
+        return None
+    body: dict[str, Any] = {
+        "contract": CONTRACT,
+        "tier": "responses_text",
+        "system": system,
+        "user": user,
+    }
+    if model:
+        body["model"] = model
+    payload = json.dumps(body).encode("utf-8")
+    req = urllib.request.Request(
+        base + "/v1/infer",
+        data=payload,
+        headers={"content-type": "application/json"},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:  # noqa: S310 (loopback only)
+            data = json.loads(resp.read().decode("utf-8"))
+    except (urllib.error.URLError, OSError, ValueError, TimeoutError):
+        _invalidate()
+        return None
+    if not isinstance(data, dict) or data.get("ok") is not True:
+        return None
+    text = data.get("text")
+    return text if isinstance(text, str) else None
+
+
+def _invalidate() -> None:
+    global _resolved_at, _resolved_base
+    _resolved_base = None
+    _resolved_at = 0.0

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@jaredboynton/rtinfer",
+  "version": "0.1.0",
+  "description": "Always-on loopback rtinfer/1 inference daemon (gpt-realtime + codex/responses over Codex OAuth). Shared by cse-tools and unifable.",
+  "license": "MIT",
+  "repository": "https://github.com/jaredboynton/rtinfer",
+  "engines": { "node": ">=18.0.0" },
+  "bin": {
+    "rtinferd": "bin/rtinferd.js"
+  },
+  "main": "clients/rtinfer-client.mjs",
+  "files": [
+    "bin/",
+    "src/",
+    "clients/"
+  ],
+  "scripts": {
+    "postinstall": "node src/postinstall.js"
+  },
+  "optionalDependencies": {
+    "@jaredboynton/rtinfer-darwin-arm64": "0.1.0",
+    "@jaredboynton/rtinfer-linux-arm64": "0.1.0"
+  }
+}

package/src/index.js

@@ -0,0 +1,52 @@
+'use strict';
+
+// Resolve the native rtinferd binary from the platform package (or a vendored
+// fallback) and exec it. Mirrors the cse-tools js-wrapper pattern.
+
+const path = require('path');
+const fs = require('fs');
+const child_process = require('child_process');
+
+function platformPackageName() {
+  return `@jaredboynton/rtinfer-${process.platform}-${process.arch}`;
+}
+
+function nativeBinaryName(platform) {
+  return platform === 'win32' ? 'rtinferd.exe' : 'rtinferd';
+}
+
+function resolveCoreBinary() {
+  const platformKey = `${process.platform}-${process.arch}`;
+  const supportedPlatforms = new Set(['darwin-arm64', 'linux-arm64']);
+  const binaryName = nativeBinaryName(process.platform);
+
+  if (supportedPlatforms.has(platformKey)) {
+    try {
+      const pkgJson = require.resolve(`${platformPackageName()}/package.json`);
+      const candidate = path.join(path.dirname(pkgJson), 'bin', binaryName);
+      if (fs.existsSync(candidate)) {
+        fs.accessSync(candidate, fs.constants.X_OK);
+        return candidate;
+      }
+    } catch (e) {
+      if (e && e.code === 'EACCES') throw new Error('native runtime is not executable');
+    }
+  }
+
+  const vendorCandidate = path.resolve(__dirname, '..', 'vendor', binaryName);
+  if (fs.existsSync(vendorCandidate)) {
+    fs.accessSync(vendorCandidate, fs.constants.X_OK);
+    return vendorCandidate;
+  }
+
+  throw new Error(`native runtime is unavailable for this platform: ${platformKey}`);
+}
+
+function spawnRaw(args, options) {
+  return child_process.spawnSync(resolveCoreBinary(), args || [], {
+    stdio: 'inherit',
+    ...(options || {}),
+  });
+}
+
+module.exports = { resolveCoreBinary, spawnRaw };

package/src/postinstall.js

@@ -0,0 +1,44 @@
+'use strict';
+
+// postinstall: install + load the always-on LaunchAgent so rtinferd is
+// running immediately after `npm i -g @jaredboynton/rtinfer`. Best-effort:
+// a failure here (no binary for this platform, CI sandbox, non-macOS) must
+// NOT fail the install. The daemon can always be started manually with
+// `rtinferd install` or `rtinferd serve`.
+
+const path = require('path');
+const fs = require('fs');
+const { spawnRaw } = require('./index');
+
+if (process.env.RTINFER_SKIP_POSTINSTALL === '1') {
+  process.exit(0);
+}
+
+// Pin the LaunchAgent to the STABLE npm global bin shim (this very wrapper),
+// not the versioned native binary, so in-daemon self-update is a no-op for the
+// plist: npm rewrites the shim in place and launchd respawns it unchanged.
+function npmGlobalShim() {
+  // npm exposes the install prefix to lifecycle scripts; the global bin shim
+  // lives at <prefix>/bin/rtinferd on POSIX.
+  const prefix = process.env.npm_config_prefix || process.env.PREFIX;
+  if (prefix) {
+    const shim = path.join(prefix, 'bin', 'rtinferd');
+    if (fs.existsSync(shim)) return shim;
+  }
+  return null;
+}
+
+try {
+  const shim = npmGlobalShim();
+  const env = shim ? { ...process.env, RTINFER_LAUNCH_BIN: shim } : process.env;
+  const result = spawnRaw(['install'], { env });
+  if (result.error || (result.status != null && result.status !== 0)) {
+    console.error('[rtinfer] postinstall: daemon not installed automatically; run `rtinferd install` to enable the always-on service.');
+  }
+} catch (e) {
+  console.error(`[rtinfer] postinstall skipped: ${e.message}`);
+  console.error('[rtinfer] run `rtinferd install` (macOS) or `rtinferd serve` to start the daemon.');
+}
+// Always exit 0 so npm install never fails on the daemon side-effect.
+process.exit(0);
+