car-runtime 0.4.1

package/LICENSE

@@ -0,0 +1,36 @@
+Common Agent Runtime — Binary License
+======================================
+
+Copyright © 2026 Parslee AI. All rights reserved.
+
+This package distributes pre-built binary artifacts of the Common Agent
+Runtime (the "Binaries"). Your use of the Binaries is subject to these terms.
+
+Subject to your agreement with these terms, Parslee AI grants you a
+worldwide, royalty-free, non-exclusive, non-transferable license to:
+
+  (a) download, install, and use the Binaries for any lawful purpose,
+      including commercial use;
+  (b) redistribute the Binaries in their original, unmodified form,
+      provided this license is included.
+
+You may NOT:
+
+  (c) modify, translate, adapt, or create derivative works of the Binaries;
+  (d) decompile, disassemble, reverse engineer, or otherwise attempt to
+      derive the source code of the Binaries, except to the extent that
+      applicable law expressly permits despite this limitation;
+  (e) remove, alter, or obscure any copyright, trademark, or other
+      proprietary notices on or in the Binaries;
+  (f) circumvent or disable any license-enforcement, anti-tamper, or
+      similar mechanism in the Binaries.
+
+If you need rights beyond those granted above — including modification,
+derivative works, source access, or a commercial redistribution agreement —
+contact Parslee AI.
+
+THE BINARIES ARE PROVIDED "AS IS" AND WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL
+PARSLEE AI BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING
+FROM THE USE OF, INABILITY TO USE, OR DISTRIBUTION OF THE BINARIES.

package/README.md

@@ -0,0 +1,63 @@
+# car-runtime
+
+Node.js bindings for **Common Agent Runtime** — a deterministic execution
+layer for AI agents. Models propose; the runtime validates and executes.
+
+## Install
+
+```bash
+npm install car-runtime
+```
+
+The package's install script downloads the matching native binary for your
+platform from [car-releases](https://github.com/Parslee-ai/car-releases/releases).
+Supported platforms: macOS (14+) arm64/x64, Linux x64/arm64 glibc.
+
+## Quickstart
+
+```typescript
+import { CarRuntime, executeProposal } from 'car-runtime';
+
+const rt = new CarRuntime();
+
+// Register tools + policies.
+await rt.registerTool('shell');
+await rt.registerPolicy('no_rm', 'deny_tool_param', 'shell', 'command', 'rm -rf');
+
+// Verify before executing.
+const proposal = JSON.stringify({
+  actions: [{
+    id: 'a1',
+    type: 'tool_call',
+    tool: 'shell',
+    parameters: { command: 'ls' },
+    dependencies: [],
+  }],
+});
+
+const check = JSON.parse(await rt.verifyProposal(proposal));
+if (!check.valid) throw new Error(`invalid: ${JSON.stringify(check.issues)}`);
+
+// Execute with a JS tool callback.
+const result = await executeProposal(rt, proposal, async (callJson) => {
+  const { tool, params } = JSON.parse(callJson);
+  // Dispatch to your tool implementation.
+  return JSON.stringify({ stdout: 'ok' });
+});
+```
+
+Full API reference lives in [`index.d.ts`](./index.d.ts). High-level docs and
+examples: https://github.com/Parslee-ai/car-releases
+
+## Environment variables
+
+- `CAR_RUNTIME_SKIP_DOWNLOAD=1` — bypass the install-time download. Place the
+  binary in the package directory yourself.
+- `CAR_RUNTIME_DOWNLOAD_BASE=<url>` — override the download origin (e.g.
+  internal mirror). Binary filename is appended.
+
+## License
+
+Free for any use including commercial; free to redistribute unmodified.
+Modification, reverse engineering, and derivative works are not permitted.
+See [`LICENSE`](./LICENSE) for the full text. Copyright © 2026 Parslee AI.

package/index.d.ts

@@ -0,0 +1,387 @@
+/** Common Agent Runtime — native Node.js bindings.
+ *
+ * Most methods that return structured data return a JSON-encoded string; the
+ * caller is expected to `JSON.parse` the result. This keeps the FFI surface
+ * small and avoids coupling the native binding to any specific TS shape.
+ */
+
+/** Persistent runtime instance with state, memory, tools, and policies. */
+export class CarRuntime {
+  constructor();
+
+  // --- Memory persistence ---
+
+  /** Load memory graph from a JSON file. Returns the number of facts loaded. */
+  loadMemory(path: string): number;
+
+  /** Persist memory graph to a JSON file (backward-compatible flat format). */
+  persistMemory(path: string): void;
+
+  // --- Tools & policies ---
+
+  /** Register a tool by name. */
+  registerTool(name: string): Promise<void>;
+
+  /** Register CAR's built-in agent utility tools. */
+  registerAgentBasics(): Promise<void>;
+
+  /**
+   * Register a policy enforced in Rust on every action.
+   * `rule` is one of: "deny_tool", "deny_tool_param", "require_state".
+   */
+  registerPolicy(
+    name: string,
+    rule: string,
+    target?: string | null,
+    key?: string | null,
+    pattern?: string | null,
+    valueJson?: string | null,
+  ): Promise<void>;
+
+  /**
+   * Set replan configuration on this runtime.
+   * `maxReplans` = 0 disables replanning (default).
+   */
+  setReplanConfig(maxReplans: number, delayMs?: number | null): Promise<void>;
+
+  // --- State ---
+
+  /** Set a state key (value must be a JSON string). */
+  stateSet(key: string, valueJson: string): void;
+
+  /** Get a state key. Returns the value as a JSON string, or `"null"`. */
+  stateGet(key: string): string;
+
+  stateExists(key: string): boolean;
+
+  /** Snapshot of all state as a JSON string. */
+  stateSnapshot(): string;
+
+  stateKeys(): string[];
+
+  // --- Memory / Facts (graph-backed) ---
+
+  /** Add a fact. `kind` is typically "pattern" or "constraint". */
+  addFact(subject: string, body: string, kind: string, confidence?: number | null): number;
+
+  /** Query facts via graph spreading activation. Returns a JSON array. */
+  queryFacts(query: string, k?: number | null): string;
+
+  factCount(): number;
+
+  /**
+   * Build the full 4-layer context for a query.
+   * When `modelContextWindow` is provided, dynamically sizes the budget.
+   */
+  buildContext(query: string, modelContextWindow?: number | null): string;
+
+  /**
+   * Build context in Fast mode for latency-sensitive paths.
+   * Skips embedding flush, skill lookup, PPR-based scoring, known unknowns.
+   */
+  buildContextFast(query: string, modelContextWindow?: number | null): string;
+
+  /** Run memory consolidation ("dream") pass. Returns a JSON report. */
+  consolidate(): string;
+
+  // --- Skills ---
+
+  /** Save a learned skill with trigger context. Returns the node index. */
+  ingestSkill(
+    name: string,
+    code: string,
+    platform: string,
+    persona: string,
+    urlPattern: string,
+    taskKeywords: string[],
+    description: string,
+    supersedesSkill?: string | null,
+  ): number;
+
+  /** Find best matching skill for context. Returns JSON or `"null"`. */
+  findSkill(
+    persona: string,
+    url: string,
+    task: string,
+    maxResults?: number | null,
+  ): string;
+
+  /** Report skill execution outcome ("success" or "fail"). Returns updated stats JSON. */
+  reportOutcome(skillName: string, outcome: string): string;
+
+  /** Distill skills from execution trace events. Returns JSON array of DistilledSkill. */
+  distillSkills(eventsJson: string): Promise<string>;
+
+  /** Ingest distilled skills into the memory graph. Returns the count ingested. */
+  ingestDistilledSkills(skillsJson: string): number;
+
+  /** List skills (optionally filtered by domain). Returns JSON array. */
+  listSkills(domain?: string | null): string;
+
+  /** Domains with success rate below the given threshold (default 0.6). */
+  domainsNeedingEvolution(threshold?: number | null): string[];
+
+  /** Repair a degraded skill using local inference. Returns repaired code or null. */
+  repairSkill(skillName: string): Promise<string | null>;
+
+  /** Evolve skills for a domain based on failed events. Returns JSON array. */
+  evolveSkills(eventsJson: string, domain: string): Promise<string>;
+
+  // --- Inference ---
+
+  /** Generate text. Returns JSON: `{"text":"..."}`. */
+  infer(prompt: string, model?: string | null, maxTokens?: number | null): Promise<string>;
+
+  /**
+   * Generate with full tracking: text, tool_calls, usage, model_used, latency_ms.
+   * Returns JSON.
+   */
+  inferTracked(
+    prompt: string,
+    model?: string | null,
+    maxTokens?: number | null,
+    context?: string | null,
+    toolsJson?: string | null,
+    messagesJson?: string | null,
+  ): Promise<string>;
+
+  /** Generate text grounded with memory context from this runtime's memgine. */
+  inferWithContext(
+    prompt: string,
+    model?: string | null,
+    maxTokens?: number | null,
+  ): Promise<string>;
+
+  /** Embed texts. Returns JSON array of float arrays. */
+  embed(texts: string[], model?: string | null): Promise<string>;
+
+  /**
+   * Rerank documents against a query using a cross-encoder reranker.
+   * Returns JSON: `{ranked: [{index, score, document}, ...], model_used}`.
+   */
+  rerank(
+    query: string,
+    documents: string[],
+    model?: string | null,
+    topN?: number | null,
+    instruction?: string | null,
+  ): Promise<string>;
+
+  /** Classify text against labels. Returns JSON array of `{label, score}`. */
+  classify(text: string, labels: string[], model?: string | null): Promise<string>;
+
+  // --- Speech ---
+
+  /** Prepare the managed speech runtime and return its root path. */
+  prepareSpeechRuntime(): Promise<string>;
+
+  /** Transcribe a local audio file. Returns JSON `{text, model_used, language, ...}`. */
+  transcribe(
+    audioPath: string,
+    model?: string | null,
+    language?: string | null,
+    prompt?: string | null,
+    timestamps?: boolean | null,
+  ): Promise<string>;
+
+  /**
+   * Synthesize speech to an output file. Returns JSON `{audio_path, media_type, ...}`.
+   * `referenceAudioPath`, `referenceText`, `voiceInstruction` are Qwen3-TTS-specific
+   * controls (voice cloning / voice design); other backends ignore them.
+   */
+  synthesize(
+    text: string,
+    model?: string | null,
+    voice?: string | null,
+    language?: string | null,
+    speed?: number | null,
+    outputPath?: string | null,
+    format?: string | null,
+    referenceAudioPath?: string | null,
+    referenceText?: string | null,
+    voiceInstruction?: string | null,
+  ): Promise<string>;
+
+  // --- Models ---
+
+  /** Local + built-in models. Returns JSON array. */
+  listModels(): string;
+
+  /** Download a model. Returns its local path. */
+  pullModel(name: string): Promise<string>;
+
+  /** Remove a downloaded model. */
+  removeModel(name: string): void;
+
+  /** Unified registry (local + remote). Returns JSON array. */
+  listModelsUnified(): string;
+
+  /** Register a model schema (persists to `~/.car/models.json`). */
+  registerModel(schemaJson: string): void;
+
+  /** Route a prompt. Returns the routing decision as JSON. */
+  routeModel(prompt: string): Promise<string>;
+
+  /** Per-model performance profiles. Returns JSON. */
+  modelStats(): Promise<string>;
+
+  // --- Execution ---
+
+  /** Count of events in this runtime's execution log. */
+  eventCount(): Promise<number>;
+
+  /** Verify a proposal against this runtime's state + tools. Returns JSON. */
+  verifyProposal(proposalJson: string): Promise<string>;
+
+  // --- Browser automation ---
+
+  /**
+   * Run a JSON script of browser operations against a persistent Chromium
+   * session attached to this runtime instance. First call lazily launches
+   * Chromium (requires a local Chrome/Chromium binary); subsequent calls
+   * reuse the same session so element IDs from `observe` resolve across
+   * invocations.
+   *
+   * Script shape: `{operations: [{op:"navigate",url:"..."}, {op:"observe"}, ...]}`
+   * Supported ops: navigate, observe, click, type, scroll, keypress, wait.
+   * Returns JSON: `{steps:[{op,status,data,error,duration_ms}]}`. Execution
+   * short-circuits on first error.
+   */
+  browserRun(
+    scriptJson: string,
+    width?: number | null,
+    height?: number | null,
+  ): Promise<string>;
+}
+
+// ---------------------------------------------------------------------------
+// Standalone functions
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute a proposal through a CarRuntime with a JS tool callback.
+ * The callback receives `{"tool":"name","params":{...}}` as a JSON string
+ * and must return a JSON string.
+ */
+export function executeProposal(
+  rt: CarRuntime,
+  proposalJson: string,
+  toolFn: (callJson: string) => Promise<string>,
+): Promise<string>;
+
+/**
+ * Stream inference events in real time via a callback.
+ * Callback receives event JSON strings:
+ *   `{"type":"text","data":"..."}`
+ *   `{"type":"tool_start","name":"...","index":N}`
+ *   `{"type":"tool_delta","index":N,"data":"..."}`
+ *   `{"type":"done","text":"...","tool_calls":[...]}`
+ */
+export function inferStream(
+  rt: CarRuntime,
+  prompt: string,
+  model: string | null | undefined,
+  maxTokens: number | null | undefined,
+  context: string | null | undefined,
+  toolsJson: string | null | undefined,
+  onEvent: (eventJson: string) => void,
+): Promise<string>;
+
+// --- Verification (stateless) ---
+
+export function verify(
+  proposalJson: string,
+  initialStateJson?: string | null,
+  toolNames?: string[] | null,
+  maxActions?: number | null,
+): string;
+
+export function simulate(
+  proposalJson: string,
+  initialStateJson?: string | null,
+): string;
+
+export function optimize(proposalJson: string): string;
+
+export function equivalent(proposal1Json: string, proposal2Json: string): boolean;
+
+// --- Multi-agent coordination ---
+
+/**
+ * Register the agent runner callback for multi-agent and scheduler functions.
+ * Call once before using `runSwarm`, `runPipeline`, `runSupervisor`, etc.
+ *
+ * `agentFn(specJson, taskJson) => Promise<AgentOutput JSON>`
+ */
+export function registerAgentRunner(
+  agentFn: (specJson: string, taskJson: string) => Promise<string>,
+): Promise<void>;
+
+/** Run a Swarm pattern. `mode` is "parallel", "sequential", or "debate". */
+export function runSwarm(
+  mode: string,
+  agents: string,
+  task: string,
+  synthesizerSpec?: string | null,
+): Promise<string>;
+
+export function runPipeline(stages: string, task: string): Promise<string>;
+
+export function runSupervisor(
+  workers: string,
+  supervisor: string,
+  task: string,
+  maxRounds: number,
+): Promise<string>;
+
+export function runMapReduce(
+  mapper: string,
+  reducer: string,
+  task: string,
+  items: string,
+): Promise<string>;
+
+export function runVote(
+  agents: string,
+  task: string,
+  synthesizerSpec?: string | null,
+): Promise<string>;
+
+// --- Scheduler ---
+
+/** Create a task definition. Returns task JSON. */
+export function createTask(
+  name: string,
+  prompt: string,
+  trigger?: string | null,
+  schedule?: string | null,
+  systemPrompt?: string | null,
+): string;
+
+/** Run a task once using the registered agent runner. */
+export function runTask(taskJson: string): Promise<string>;
+
+/** Run a task loop using the registered agent runner. */
+export function runTaskLoop(
+  taskJson: string,
+  maxIterations?: number | null,
+): Promise<string>;
+
+/**
+ * Ensure a dream (memory consolidation) task exists in `~/.car/tasks/`.
+ * Returns true if a new task was created, false if one already existed.
+ */
+export function ensureDreamTask(): boolean;
+
+// --- Planner ---
+
+/**
+ * Score and rank candidate proposals. Returns JSON array of ScoredProposal.
+ * `candidatesJson` is a JSON array of ActionProposal objects.
+ * `tools` is an optional array of registered tool names.
+ */
+export function rankProposals(
+  candidatesJson: string,
+  tools?: string[] | null,
+  costWeight?: number | null,
+): string;

package/index.js

@@ -0,0 +1,37 @@
+// Platform-aware loader. The binary is downloaded at install time by
+// install.js — see that file for the download contract and opt-outs.
+
+const os = require('node:os');
+const path = require('node:path');
+
+const platformMap = {
+  'darwin-arm64': 'darwin-arm64',
+  'darwin-x64':   'darwin-x64',
+  'linux-x64':    'linux-x64-gnu',
+  'linux-arm64':  'linux-arm64-gnu',
+  'win32-x64':    'win32-x64-msvc',
+};
+
+const key = `${os.platform()}-${os.arch()}`;
+const target = platformMap[key];
+
+if (!target) {
+  throw new Error(
+    `Unsupported platform: ${key}. Supported: ${Object.keys(platformMap).join(', ')}.`,
+  );
+}
+
+const binaryPath = path.join(__dirname, `car-runtime.${target}.node`);
+
+let nativeModule;
+try {
+  nativeModule = require(binaryPath);
+} catch (e) {
+  throw new Error(
+    `Failed to load car-runtime native binary at ${binaryPath}. ` +
+      `Try reinstalling, or set CAR_RUNTIME_DOWNLOAD_BASE to a mirror and ` +
+      `run node install.js manually. Error: ${e.message}`,
+  );
+}
+
+module.exports = nativeModule;

package/install.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+// Downloads the native Node.js binary matching this package's version and
+// the host platform from the car-releases GitHub repo. Cached next to this
+// script so `require('./car-runtime.<platform>.node')` resolves without
+// another network round-trip.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const https = require('node:https');
+const { pipeline } = require('node:stream/promises');
+
+const PLATFORMS = {
+  'darwin-arm64': 'car-runtime.darwin-arm64.node',
+  'darwin-x64':   'car-runtime.darwin-x64.node',
+  'linux-x64':    'car-runtime.linux-x64-gnu.node',
+  'linux-arm64':  'car-runtime.linux-arm64-gnu.node',
+  'win32-x64':    'car-runtime.win32-x64-msvc.node',
+};
+
+function targetForHost() {
+  const key = `${process.platform}-${process.arch}`;
+  const name = PLATFORMS[key];
+  if (!name) {
+    throw new Error(
+      `Unsupported platform ${key}. Supported: ${Object.keys(PLATFORMS).join(', ')}.`,
+    );
+  }
+  return name;
+}
+
+function pkgVersion() {
+  const pkg = JSON.parse(
+    fs.readFileSync(path.join(__dirname, 'package.json'), 'utf8'),
+  );
+  return pkg.version;
+}
+
+function get(url) {
+  return new Promise((resolve, reject) => {
+    const req = https.get(
+      url,
+      { headers: { 'user-agent': `car-runtime-install/${pkgVersion()}` } },
+      (res) => {
+        if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+          // Follow redirect (GitHub release asset URLs redirect to S3).
+          res.resume();
+          return resolve(get(res.headers.location));
+        }
+        if (res.statusCode !== 200) {
+          res.resume();
+          return reject(new Error(`${url} → HTTP ${res.statusCode}`));
+        }
+        resolve(res);
+      },
+    );
+    req.on('error', reject);
+  });
+}
+
+async function main() {
+  const name = targetForHost();
+  const dest = path.join(__dirname, name);
+
+  // Opt-out for air-gapped installs — user is expected to drop the .node
+  // file into this directory themselves.
+  if (process.env.CAR_RUNTIME_SKIP_DOWNLOAD === '1') {
+    console.log('[car-runtime] CAR_RUNTIME_SKIP_DOWNLOAD=1 — skipping download.');
+    return;
+  }
+
+  // Skip if already present (e.g. preinstalled, reinstall without cache wipe).
+  if (fs.existsSync(dest)) {
+    return;
+  }
+
+  const version = pkgVersion();
+  const url = `https://github.com/Parslee-ai/car-releases/releases/download/v${version}/${name}`;
+
+  // Override for testing / mirrors.
+  const base = process.env.CAR_RUNTIME_DOWNLOAD_BASE;
+  const finalUrl = base ? `${base}/${name}` : url;
+
+  console.log(`[car-runtime] downloading ${finalUrl}`);
+  try {
+    const res = await get(finalUrl);
+    const tmp = `${dest}.part`;
+    await pipeline(res, fs.createWriteStream(tmp));
+    fs.renameSync(tmp, dest);
+    console.log(`[car-runtime] installed ${name}`);
+  } catch (err) {
+    console.error(
+      `[car-runtime] download failed: ${err.message}\n` +
+        `Place ${name} manually in ${__dirname} or set CAR_RUNTIME_SKIP_DOWNLOAD=1 ` +
+        `and ensure the binary is resolvable at require-time.`,
+    );
+    // Exit 0 so `npm install` doesn't fail the whole project — the require()
+    // in index.js will surface a clear error if the binary is missing.
+    process.exit(0);
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "car-runtime",
+  "version": "0.4.1",
+  "description": "Common Agent Runtime — a deterministic execution layer for AI agents",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "keywords": [
+    "ai",
+    "agent",
+    "runtime",
+    "llm",
+    "inference",
+    "napi"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Parslee-ai/car-releases.git"
+  },
+  "homepage": "https://github.com/Parslee-ai/car-releases",
+  "bugs": "https://github.com/Parslee-ai/car-releases/issues",
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "install.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "install": "node install.js || true"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "private": false
+}