car-runtime 0.8.2 → 0.9.0

package/assets.json

@@ -0,0 +1,21 @@
+{
+  "_doc": "Canonical per-platform asset name registry for car-runtime npm. Read by install.js, scripts/release.sh, and .github/workflows/build.yml so the three never drift. Add a platform here first, then verify each consumer picks it up. x86_64-apple-darwin was dropped — Apple Silicon only on macOS.",
+  "platforms": {
+    "darwin-arm64": {
+      "node": "car-runtime.darwin-arm64.node",
+      "server": "car-server-darwin-arm64"
+    },
+    "linux-x64": {
+      "node": "car-runtime.linux-x64-gnu.node",
+      "server": "car-server-linux-x64-gnu"
+    },
+    "linux-arm64": {
+      "node": "car-runtime.linux-arm64-gnu.node",
+      "server": "car-server-linux-arm64-gnu"
+    },
+    "win32-x64": {
+      "node": "car-runtime.win32-x64-msvc.node",
+      "server": "car-server-win32-x64-msvc.exe"
+    }
+  }
+}

package/bin/car-server

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+// Cross-platform shim that execs the platform-specific car-server
+// binary downloaded by install.js. Pointed at by package.json's
+// `bin` field so `npx --package=car-runtime car-server` works.
+//
+// Why a JS shim, not a direct binary in `bin`: npm's bin entries
+// must be JS files (or have a hashbang) on POSIX, and the binary
+// suffix (`.exe`) varies on Windows. A 20-line dispatcher keeps
+// the package layout portable. Closes Parslee-ai/car-releases#36.
+
+const path = require('node:path');
+const fs = require('node:fs');
+const { spawnSync } = require('node:child_process');
+
+const pkgRoot = path.join(__dirname, '..');
+const ASSETS = JSON.parse(
+  fs.readFileSync(path.join(pkgRoot, 'assets.json'), 'utf8'),
+).platforms;
+
+const key = `${process.platform}-${process.arch}`;
+const entry = ASSETS[key];
+if (!entry) {
+  console.error(
+    `car-server is not available for ${key}. Supported: ${Object.keys(ASSETS).join(', ')}.`
+  );
+  process.exit(1);
+}
+
+const binary = path.join(pkgRoot, entry.server);
+
+if (!fs.existsSync(binary)) {
+  console.error(
+    `car-server binary not found at ${binary}.\n` +
+      `The car-runtime install script downloads it from the GitHub release; ` +
+      `re-run \`npm install car-runtime\`, or set CAR_RUNTIME_SKIP_DOWNLOAD=1 ` +
+      `and place the binary at that path manually.`
+  );
+  process.exit(1);
+}
+
+const result = spawnSync(binary, process.argv.slice(2), { stdio: 'inherit' });
+if (result.error) {
+  console.error(`car-server failed to spawn: ${result.error.message}`);
+  process.exit(1);
+}
+process.exit(result.status ?? 1);

package/index.d.ts

@@ -23,7 +23,11 @@
  * - `openSession`, `closeSession`, `registerPolicy(sessionId)` — use
  *   `session.open` / `session.close` JSON-RPC methods
  * - `stateSnapshot`, `stateKeys` — daemon-side endpoints pending
- * - `removeModel`, `registerModel` — daemon owns models_dir / models.json
+ * - `removeModel` — daemon owns models_dir / models.json
+ *
+ * (`registerModel` was re-exposed in #39 — it now proxies to the
+ *  daemon's `models.register` JSON-RPC. See its docstring for
+ *  the visibility caveat.)
  *
  * Daemon URL override: `CAR_DAEMON_URL=ws://...` (default
  * `ws://127.0.0.1:9100`).
@@ -359,8 +363,23 @@ export class CarRuntime {
    */
   listModelsUnified(): string;
 
-  /** Register a model schema (persists to `~/.car/models.json`). */
-  registerModel(schemaJson: string): void;
+  /**
+   * Register a `ModelSchema` via the daemon's `models.register`
+   * JSON-RPC method (Parslee-ai/car-releases#39). The schema is
+   * persisted to `~/.car/models.json` (replacing any existing
+   * entry with the same `id`).
+   *
+   * **Visibility limitation**: the model becomes visible to
+   * `infer` / `models.list` / `models.list_unified` on the **next
+   * daemon boot**. Live hot-update inside a running daemon is
+   * tracked as a separate follow-up that requires interior
+   * mutability on the `UnifiedRegistry`. Register before
+   * starting the daemon's inference path, or restart the daemon
+   * after a batch of registrations.
+   *
+   * Returns JSON `{id, registered, path, note}`.
+   */
+  registerModel(schemaJson: string): Promise<string>;
 
   /** Route a prompt. Returns the routing decision as JSON. */
   routeModel(prompt: string): Promise<string>;
@@ -385,6 +404,26 @@ export class CarRuntime {
   /** Verify a proposal against this runtime's state + tools. Returns JSON. */
   verifyProposal(proposalJson: string): Promise<string>;
 
+  /**
+   * Submit a proposal for daemon-side execution using the
+   * persistent `tools.execute` handler set by
+   * `registerToolHandler` (Parslee-ai/car-releases#38).
+   *
+   * Symmetric to `executeProposal` but without the per-call
+   * handler argument — the handler is process-wide. Fails up
+   * front if no handler is registered.
+   *
+   * `sessionId`, when provided, scopes per-action policy
+   * validation to a session opened via the daemon's
+   * `session.policy.open` JSON-RPC method.
+   *
+   * Returns the JSON-encoded execution result.
+   */
+  submitProposal(
+    proposalJson: string,
+    sessionId?: string | null,
+  ): Promise<string>;
+
   // --- Browser automation ---
 
   /**
@@ -611,12 +650,21 @@ export class CarRuntime {
  * policies still apply, plus the session's. Without a session id the
  * behavior matches the no-scope path bit-for-bit. See
  * `docs/proposals/per-session-policy-scoping.md`.
+ *
+ * `scopeJson`, when provided, is a serialized `RuntimeScope` —
+ * `{ callerId?: string, tenantId?: string, claims?: Record<string, any> }`
+ * — attaching per-execution caller / tenant identity. When `tenantId`
+ * is set, the runtime routes per-action state R/W through the
+ * tenant-scoped view so distinct tenants can't observe each other's
+ * keys (Parslee-ai/car#187 phase 3). Single-tenant in-process callers
+ * pass `null` / omit and see no behaviour change.
  */
 export function executeProposal(
   rt: CarRuntime,
   proposalJson: string,
   toolFn: (callJson: string) => Promise<string>,
   sessionId?: string | null,
+  scopeJson?: string | null,
 ): Promise<string>;
 
 /**
@@ -790,6 +838,36 @@ export function registerVoiceEventHandler(
   onEvent: (sessionId: string, eventJson: string) => void,
 ): void;
 
+/**
+ * Register the JS `tools.execute` handler for `submitProposal`
+ * (Parslee-ai/car-releases#38). When the daemon dispatches a
+ * proposal carrying host-owned tools, every tool routes through
+ * this handler.
+ *
+ * `handlerFn(callJson)` receives `{"tool":"name","params":{...}}`
+ * as a JSON string and MUST return a Promise resolving to the
+ * tool's JSON-encoded result. Throwing rejects the daemon-side
+ * action with a -32000 JSON-RPC error.
+ *
+ * Process-wide setter — re-calling overwrites the previous
+ * handler. Pair with `unregisterToolHandler` to clear. Symmetric
+ * to `registerInferenceRunner` / `registerAgentRunner`: only one
+ * handler can be active at a time.
+ *
+ * Required before `submitProposal`. `executeProposal` continues
+ * to accept a per-call handler and does not use this registration.
+ */
+export function registerToolHandler(
+  handlerFn: (callJson: string) => Promise<string>,
+): void;
+
+/**
+ * Clear the registered `tools.execute` handler. `submitProposal`
+ * calls after this will fail if the proposal carries any
+ * host-tool actions.
+ */
+export function unregisterToolHandler(): void;
+
 export function transcribeStream(
   rt: CarRuntime,
   sessionId: string,
@@ -1049,13 +1127,25 @@ export function reapStaleAgents(
  *   "agent_name": "...",             // optional
  *   "agent_description": "...",      // optional
  *   "organization": "...",           // optional
- *   "organization_url": "..."        // optional
+ *   "organization_url": "...",       // optional
+ *   "share_session_runtime": false   // optional, default false
  * }
  * ```
  *
+ * `share_session_runtime` — when `true`, the A2A dispatcher uses
+ * the calling `CarRuntime`'s session runtime instead of spawning a
+ * fresh one. Tools registered on the session via
+ * `registerToolSchema` then appear on the Agent Card's `skills`
+ * list, and A2A peer `message/send` calls for those tools route
+ * back to the handler installed via `registerToolHandler`. This is
+ * the canonical path for host-language agents to project themselves
+ * over A2A. Default `false` preserves the legacy fresh-Runtime
+ * behaviour (only `register_agent_basics` tools, dispatch in Rust).
+ *
  * Returns `'{"bound":"127.0.0.1:8731"}'` on success. Errors if a
- * server is already running, the bind fails, or `paramsJson` is
- * malformed.
+ * server is already running, the bind fails, `share_session_runtime`
+ * is set but no session runtime is available (e.g. invoked from a
+ * non-WS path), or `paramsJson` is malformed.
  */
 export function startA2aServer(paramsJson: string): Promise<string>;
 
@@ -1363,6 +1453,30 @@ export function agentsHealth(): Promise<string>;
  */
 export function agentsUpsert(specJson: string): Promise<string>;
 
+/**
+ * Install a contributed-agent `AgentManifest` (Parslee-ai/car#182
+ * phase 3). Runs install-time validation against the daemon's
+ * default host capability advertisement:
+ *
+ * - `runtime.car_min_version` must be satisfied by the runtime's
+ *   own semver.
+ * - Every `capabilities.required[namespace][feature]` must be
+ *   advertised by the host. Fail-closed on any miss.
+ * - `capabilities.optional` is reported back as `missingOptional`
+ *   when the host can't satisfy it — informational, not blocking.
+ *
+ * For `external_process` manifests with a `command`, the
+ * supervisor adopts the agent and returns it. For `pure_data`
+ * and `health_url`-only manifests, the manifest is written to
+ * `~/.car/agents/<id>/manifest.toml` but no `AgentSpec` is
+ * adopted (the supervisor only spawns command-shaped externals
+ * in this phase).
+ *
+ * Returns JSON
+ * `{report: {missingOptional: [{namespace, feature}]}, agent: ManagedAgent|null}`.
+ */
+export function agentsInstall(manifestJson: string): Promise<string>;
+
 /**
  * Remove an agent's spec. Stops the running child first if it's up.
  * Idempotent — `{removed: false}` when nothing matched.

package/index.js

@@ -4,9 +4,10 @@
 const os = require('node:os');
 const path = require('node:path');
 
+// darwin-x64 was dropped — Apple Silicon only on macOS. See the
+// "macOS x86_64 support dropped" CHANGELOG entry.
 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',

package/install.js

@@ -1,8 +1,19 @@
 #!/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
+// Downloads the native artifacts (Node.js `.node` module + the
+// `car-server` daemon 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')`
+// and `npx --package=car-runtime car-server` both resolve without
 // another network round-trip.
+//
+// Closes Parslee-ai/car-releases#36 followup: prior versions
+// shipped only the .node and broke `npx … car-server` despite the
+// README promising both.
+//
+// Asset names live in `assets.json` — single source of truth
+// across install.js, scripts/release.sh, and the CI build flow.
+// Per neo + Linus review feedback (this PR): consolidating the
+// list closes a 3-source drift hazard the prior commit left open.
 
 const fs = require('node:fs');
 const path = require('node:path');
@@ -10,23 +21,22 @@ const http = require('node:http');
 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',
-};
+// Platform → asset names read from the canonical assets.json registry.
+// darwin-x64 was removed there — Apple Silicon only on macOS. See the
+// "macOS x86_64 support dropped" CHANGELOG entry.
+const ASSETS = JSON.parse(
+  fs.readFileSync(path.join(__dirname, 'assets.json'), 'utf8'),
+).platforms;
 
 function targetForHost() {
   const key = `${process.platform}-${process.arch}`;
-  const name = PLATFORMS[key];
-  if (!name) {
+  const entry = ASSETS[key];
+  if (!entry) {
     throw new Error(
-      `Unsupported platform ${key}. Supported: ${Object.keys(PLATFORMS).join(', ')}.`,
+      `Unsupported platform ${key}. Supported: ${Object.keys(ASSETS).join(', ')}.`,
     );
   }
-  return name;
+  return { key, nodeName: entry.node, serverName: entry.server };
 }
 
 function pkgVersion() {
@@ -61,46 +71,87 @@ function get(url) {
   });
 }
 
+async function downloadAsset(assetName, destPath, { executable = false } = {}) {
+  if (fs.existsSync(destPath)) {
+    return { skipped: true };
+  }
+  const tmp = `${destPath}.part`;
+  // Clean stale .part files from a prior crashed install — without
+  // this, fs.createWriteStream's default flag is 'w' which truncates
+  // (fine for content) but a half-written file from a *previous*
+  // process exit between writeStream end + rename leaves an orphan
+  // .part on disk that nothing cleans up. Best-effort unlink.
+  if (fs.existsSync(tmp)) {
+    try {
+      fs.unlinkSync(tmp);
+    } catch (_) {
+      // Non-fatal — pipeline will overwrite with 'w' mode regardless.
+    }
+  }
+  const version = pkgVersion();
+  const base = process.env.CAR_RUNTIME_DOWNLOAD_BASE;
+  const url = base
+    ? `${base}/${assetName}`
+    : `https://github.com/Parslee-ai/car-releases/releases/download/v${version}/${assetName}`;
+  console.log(`[car-runtime] downloading ${url}`);
+  const res = await get(url);
+  await pipeline(res, fs.createWriteStream(tmp));
+  fs.renameSync(tmp, destPath);
+  if (executable && process.platform !== 'win32') {
+    // npm strips the execute bit from non-bin files. car-server is
+    // exec'd by bin/car-server through child_process.spawn, which
+    // needs the bit. chmod here so the bin shim doesn't have to
+    // re-stat + chmod on first run.
+    try {
+      fs.chmodSync(destPath, 0o755);
+    } catch (e) {
+      console.warn(
+        `[car-runtime] chmod +x on ${destPath} failed: ${e.message}. ` +
+          `\`npx --package=car-runtime car-server\` may fail with EACCES.`
+      );
+    }
+  }
+  console.log(`[car-runtime] installed ${assetName}`);
+  return { skipped: false };
+}
+
 async function main() {
-  const name = targetForHost();
-  const dest = path.join(__dirname, name);
+  const { nodeName, serverName } = targetForHost();
 
-  // Opt-out for air-gapped installs — user is expected to drop the .node
-  // file into this directory themselves.
+  // Opt-out for air-gapped installs — user is expected to drop both
+  // the .node file AND the car-server binary into this directory
+  // themselves before requiring the package.
   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}`;
+  const nodeDest = path.join(__dirname, nodeName);
+  const serverDest = path.join(__dirname, serverName);
 
-  // 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 non-zero so `npm install` fails loudly instead of silently producing
-    // a broken package. CAR_RUNTIME_SKIP_DOWNLOAD=1 remains the escape hatch
-    // for air-gapped installs; see the opt-out branch above.
-    process.exit(1);
+  // Both downloads are required. Failing one but not the other
+  // produces a half-working package (e.g. `require('car-runtime')`
+  // works but `npx --package=car-runtime car-server` fails at
+  // exec time) — strictly worse than `npm install` failing loudly
+  // here. The CI preflight gate ensures the release has both
+  // assets before publish, so under normal operation neither
+  // download fails for a missing asset; the only failure mode
+  // is network / mirror flakiness, which retries handle better
+  // than runtime ENOENT.
+  for (const { name, dest, executable, kind } of [
+    { name: nodeName, dest: nodeDest, executable: false, kind: '.node module' },
+    { name: serverName, dest: serverDest, executable: true, kind: 'car-server binary' },
+  ]) {
+    try {
+      await downloadAsset(name, dest, { executable });
+    } catch (err) {
+      console.error(
+        `[car-runtime] ${kind} download failed: ${err.message}\n` +
+          `Place ${name} manually in ${__dirname} or set CAR_RUNTIME_SKIP_DOWNLOAD=1 ` +
+          `and ensure both the .node module and car-server binary are present.`,
+      );
+      process.exit(1);
+    }
   }
 }
 

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "car-runtime",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "Common Agent Runtime — a deterministic execution layer for AI agents",
   "main": "index.js",
   "types": "index.d.ts",
+  "bin": {
+    "car-server": "bin/car-server"
+  },
   "keywords": [
     "ai",
     "agent",
@@ -34,6 +37,8 @@
     "index.js",
     "index.d.ts",
     "install.js",
+    "assets.json",
+    "bin/car-server",
     "README.md",
     "LICENSE"
   ],