car-runtime 0.7.0 → 0.8.1

package/README.md

@@ -3,6 +3,12 @@
 Node.js bindings for **Common Agent Runtime** — a deterministic execution
 layer for AI agents. Models propose; the runtime validates and executes.
 
+As of v0.8, this package is a **thin daemon client**: every method
+proxies to a singleton `car-server` daemon over WebSocket. The
+binary that runs the inference, holds the per-session memory graph,
+and dispatches tools is shipped alongside the .node module in this
+same package — start it once per host before using the bindings.
+
 ## Install
 
 ```bash
@@ -11,20 +17,38 @@ 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.
+Both the `.node` module **and** the `car-server` daemon binary are
+included. Supported platforms: macOS (14+) arm64/x64, Linux
+x64/arm64 glibc, Windows x64.
+
+## Start the daemon
+
+```bash
+# Foreground (Ctrl-C to stop). Default port 9100; auth on by default.
+npx --package=car-runtime car-server
+
+# Or background:
+npx --package=car-runtime car-server &
+```
+
+On macOS, the SwiftUI menubar host (`car-host`) launches the daemon
+automatically; install with `car-host install` (registers a launchd
+LaunchAgent so it comes up at login).
 
 ## Quickstart
 
 ```typescript
 import { CarRuntime, executeProposal } from 'car-runtime';
 
-const rt = new CarRuntime();
+const rt = new CarRuntime();   // lazy-connects to ws://127.0.0.1:9100/
 
-// Register tools + policies.
+// Register tools + policies. These calls proxy to the daemon's
+// per-session runtime and persist for the lifetime of this WS
+// connection.
 await rt.registerTool('shell');
 await rt.registerPolicy('no_rm', 'deny_tool_param', 'shell', 'command', 'rm -rf');
 
-// Verify before executing.
+// Verify before executing — pure static analysis on the daemon side.
 const proposal = JSON.stringify({
   actions: [{
     id: 'a1',
@@ -38,7 +62,11 @@ const proposal = JSON.stringify({
 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.
+// Execute with a JS tool callback. The callback runs in this Node
+// process; the daemon's WsToolExecutor calls back over the same WS
+// when an action needs to dispatch a tool. Proxied via
+// `register_handler("tools.execute", ...)` on the underlying
+// DaemonClient (phase 7.4).
 const result = await executeProposal(rt, proposal, async (callJson) => {
   const { tool, params } = JSON.parse(callJson);
   // Dispatch to your tool implementation.

package/index.d.ts

@@ -4,26 +4,26 @@
  * 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.
  *
- * ## Runtime modes (closes #139's cross-process admission gap)
+ * ## v0.8.0 — daemon-only
  *
- * `new CarRuntime()` runs in one of two modes, selected at construction:
+ * Every method talks to the singleton car-server daemon over WebSocket
+ * JSON-RPC. There is no embedded-engine fallback (the v0.7.x
+ * `CAR_FFI_MODE=embedded` knob is retired). Start `car-server` before
+ * using the bindings — on macOS the SwiftUI menubar app launches it for
+ * you; on Linux start it manually or via systemd.
  *
- * - **`daemon` (default)** — talks to the singleton car-server daemon over
- *   WebSocket JSON-RPC. Methods that touch shared resources (inference,
- *   embeddings, state, verification) proxy to the daemon — preserving the
- *   process-wide admission semaphore so two Node consumers don't double-load
- *   models or oversubscribe the GPU.
- * - **`embedded`** — explicit opt-in via `CAR_FFI_MODE=embedded`. Every
- *   method runs in-process. Useful for notebooks, offline dev, or single-
- *   process deployments where the caller knows they own the machine.
- *   Production embedders generally don't want this.
+ * The following methods are **not exposed in v0.8** and throw
+ * with a clear message — connect to the daemon's WebSocket directly
+ * for the equivalent flow (see `docs/websocket-protocol.md`):
  *
- * Some methods are **embedded-only by design** because their callback
- * surface (`ThreadsafeFunction` for tools, streaming events) doesn't
- * survive a network boundary cleanly. Those throw in `daemon` mode with a
- * clear message: `executeProposal`, `inferStream`. For streaming inference
- * under the singleton-daemon contract, talk to `ws://127.0.0.1:9100/`
- * directly.
+ * - `executeProposal` — use `proposal.submit` JSON-RPC + a `tools.execute`
+ *   handler on the WS connection
+ * - `inferStream`, `transcribeStream`, `dispatchVoiceTurn` — daemon
+ *   streams events over WS notifications
+ * - `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
  *
  * Daemon URL override: `CAR_DAEMON_URL=ws://...` (default
  * `ws://127.0.0.1:9100`).
@@ -35,11 +35,23 @@ export class CarRuntime {
 
   // --- Memory persistence ---
 
-  /** Load memory graph from a JSON file. Returns the number of facts loaded. */
-  loadMemory(path: string): number;
+  /**
+   * Load memory graph from a JSON file. Returns the number of facts loaded.
+   *
+   * Daemon-side read: `path` is sandboxed under `~/.car/memory/` (the
+   * 2026-05 audit boundary). Relative paths land under the base;
+   * absolute paths must already be under the base; `..` segments and
+   * symlinks pointing out of the sandbox are rejected.
+   */
+  loadMemory(path: string): Promise<number>;
 
-  /** Persist memory graph to a JSON file (backward-compatible flat format). */
-  persistMemory(path: string): void;
+  /**
+   * Persist memory graph to a JSON file (backward-compatible flat format).
+   * Returns the number of records written.
+   *
+   * Daemon-side write: same `~/.car/memory/` sandbox as `loadMemory`.
+   */
+  persistMemory(path: string): Promise<number>;
 
   // --- Tools & policies ---
 
@@ -952,13 +964,16 @@ export function stopMeeting(
   summarize?: boolean | null,
 ): Promise<string>;
 
-export function listMeetings(rt: CarRuntime, rootOverride?: string | null): string;
+export function listMeetings(
+  rt: CarRuntime,
+  rootOverride?: string | null,
+): Promise<string>;
 
 export function getMeeting(
   rt: CarRuntime,
   meetingId: string,
   rootOverride?: string | null,
-): string;
+): Promise<string>;
 
 // --- Agent registry (file-based, no daemon) ---
 
@@ -1242,6 +1257,17 @@ export function listShortcuts(argsJson: string): Promise<string>;
  */
 export function runShortcut(argsJson: string): Promise<string>;
 
+// --- Local notifications ---
+
+/**
+ * Deliver a user-visible local notification.
+ *
+ * `argsJson` shape: `{ title: string, body: string, subtitle?: string, sound?: string }`.
+ * Returns JSON `{delivered, platform, backend}`. iOS delivery is owned
+ * by the signed host app via UserNotifications.
+ */
+export function localNotification(argsJson: string): Promise<string>;
+
 // --- Vision OCR (car-vision) ---
 
 /**
@@ -1264,3 +1290,294 @@ export function runShortcut(argsJson: string): Promise<string>;
  * array rather than an error.
  */
 export function visionOcr(argsJson: string): Promise<string>;
+
+// --- In-process A2A dispatcher (car_a2a) ---
+
+/**
+ * Dispatch one A2A v1.0 method against the in-process singleton
+ * dispatcher. `method` is the spec method name (`"message/send"`,
+ * `"tasks/get"`, etc., or PascalCase aliases like `"SendMessage"`);
+ * `paramsJson` is the per-method `params` payload. Returns the
+ * JSON-stringified result.
+ *
+ * Streaming methods (`message/stream`, `tasks/resubscribe`) return
+ * a `MethodNotFound` error from the dispatcher's transport-neutral
+ * surface. HTTP+SSE is the supported transport for streaming and
+ * lives outside this FFI wrapper.
+ *
+ * Distinct from the daemon's WS A2A surface — both are valid; using
+ * both in one process gives you two task stores (task ids are
+ * unique per dispatcher).
+ */
+export function a2aDispatch(method: string, paramsJson: string): Promise<string>;
+
+// --- Lifecycle-managed agents (car_registry::supervisor) ---
+
+/**
+ * List every managed agent in `~/.car/agents.json` along with its
+ * runtime status. Returns JSON `[ManagedAgent]`.
+ *
+ * Wire shape matches the daemon's `agents.list` JSON-RPC method
+ * exactly so a host can swap between in-process and WS transports
+ * without reshaping payloads.
+ */
+export function agentsList(): Promise<string>;
+
+/**
+ * Re-validate every managed agent's `command` against the
+ * supervisor's `validate_command` rules — used to surface specs that
+ * broke after a system upgrade (Node moved versions, Homebrew pruned
+ * a symlink). Returns JSON `[{ id, command, ok, reason? }]`.
+ *
+ * Pairs with the `interpreter` sugar on `agentsUpsert`: hosts that
+ * resolve at upsert can re-resolve when health fires `ok: false`.
+ */
+export function agentsHealth(): Promise<string>;
+
+/**
+ * Add or replace an agent's spec. Persists `~/.car/agents.json`.
+ * The agent is NOT auto-started — call `agentsStart` (or
+ * `auto_start: true` will pick it up on the next boot via the
+ * supervisor's `start_all`).
+ *
+ * `specJson`:
+ * ```jsonc
+ * {
+ *   "id": "trader",                 // filename-safe
+ *   "name": "Trader",
+ *   "command": "/opt/homebrew/bin/node", // absolute path required
+ *   // OR: omit `command` and pass `interpreter: "node" | "python" | ...`
+ *   //     and the supervisor resolves the interpreter against $PATH
+ *   //     once at upsert and stores the absolute path in `command`.
+ *   "args": ["server.js"],
+ *   "cwd": "/path/to/project",       // optional
+ *   "env": { "K": "V" },             // merged on top of parent's env
+ *   "restart": "on_failure",         // never | on_failure | always
+ *   "max_restarts": 10,
+ *   "backoff_secs": 5,
+ *   "auto_start": true               // included by start_all on boot
+ * }
+ * ```
+ *
+ * Returns JSON `ManagedAgent`.
+ */
+export function agentsUpsert(specJson: string): Promise<string>;
+
+/**
+ * Remove an agent's spec. Stops the running child first if it's up.
+ * Idempotent — `{removed: false}` when nothing matched.
+ * Returns JSON `{removed: boolean}`.
+ */
+export function agentsRemove(id: string): Promise<string>;
+
+/**
+ * Spawn the agent's child if not already running. No-op when
+ * already `Running` or `Starting`. Resets `restart_count`.
+ * Returns JSON `ManagedAgent`.
+ */
+export function agentsStart(id: string): Promise<string>;
+
+/**
+ * Stop the agent and prevent the supervisor from respawning it.
+ * `signal` is `"term"` (SIGTERM with grace, default) or `"kill"`
+ * (SIGKILL immediately). Returns JSON `ManagedAgent`.
+ */
+export function agentsStop(id: string, signal?: string | null): Promise<string>;
+
+/**
+ * Stop then start. Equivalent to `agentsStop` followed by
+ * `agentsStart`. Returns JSON `ManagedAgent`.
+ */
+export function agentsRestart(id: string): Promise<string>;
+
+/**
+ * Read the last `n` lines from the agent's combined stdout +
+ * stderr log under `~/.car/logs/<id>.{stdout,stderr}.log`.
+ * Defaults to 100 lines. Returns JSON `{lines: string[]}`.
+ */
+export function agentsTailLog(id: string, n?: number | null): Promise<string>;
+
+// --- External-agent detection (car-external-agents) ---
+//
+// Phase 1 of docs/proposals/external-agent-detection.md — discover
+// installed agentic CLIs (Claude Code, Codex, Gemini) and report
+// version + auth-kind heuristic. Per-task invocation lands in Phase 2
+// alongside `agents.invoke_external`. Wire shape:
+//
+//   {
+//     "id": "claude-code" | "codex" | "gemini",
+//     "displayName": "Claude Code" | ...,
+//     "binaryPath": "/usr/local/bin/claude",
+//     "version": "1.0.51" | null,
+//     "authKind": "subscription" | "api_key" | "unknown" | "unauthenticated",
+//     "capabilities": { toolUse, mcp, hooks, sessions, streaming },
+//     "detectedAt": <unix-secs>
+//   }
+
+/**
+ * Cached snapshot of installed external agents. First call triggers
+ * a detection pass; subsequent calls return the cached list. Pass
+ * `includeHealth: true` to also populate each spec's `health` field
+ * via the tool's auth-status command — slower (one subprocess
+ * spawn per detected adapter) but gives a one-stop "what's
+ * installed AND ready to use" answer. Returns JSON
+ * `[ExternalAgentSpec]` (empty array when nothing installed).
+ *
+ * `ExternalAgentSpec.health` shape (when populated):
+ *   { id, status, details, reason?, checked_at }
+ *   status: "ready" | "not_configured" | "expired" | "network_error" | "unknown"
+ *
+ * The `auth_kind` field is **deprecated** (Phase 2 stage 1) — modern
+ * builds keep credentials in OS keystores so the heuristic falls
+ * through to "unknown" for the most common installs. Prefer `health`.
+ */
+export function agentsListExternal(
+  includeHealth?: boolean | null,
+): Promise<string>;
+
+/**
+ * Force re-detection of installed external agents. Updates the
+ * presence cache and returns the new snapshot. Pass
+ * `includeHealth: true` to also run ground-truth health checks
+ * (force-refreshing the per-tool 30s TTL cache). Returns JSON
+ * `[ExternalAgentSpec]`.
+ */
+export function agentsDetectExternal(
+  includeHealth?: boolean | null,
+): Promise<string>;
+
+/**
+ * Ground-truth health check via each tool's own auth-status command
+ * (`claude auth status`, `codex login status`). Replaces the Phase 1
+ * credential-file shape heuristic as the primary signal for "is this
+ * tool ready to invoke." Pass an `id` to check one adapter; omit it
+ * to check every detected adapter. `force: true` bypasses the 30s
+ * per-tool TTL cache.
+ *
+ * Wire shape: `[ExternalAgentHealth]` (when `id` omitted) or
+ * `ExternalAgentHealth` (when `id` supplied), where:
+ *
+ *   {
+ *     "id": "claude-code" | "codex" | "gemini",
+ *     "status": "ready" | "not_configured" | "expired" |
+ *               "network_error" | "unknown",
+ *     "details": <tool-specific JSON object>,
+ *     "reason": <human-readable string when not Ready>,
+ *     "checked_at": <unix-secs>
+ *   }
+ */
+export function agentsHealthExternal(
+  id?: string | null,
+  force?: boolean | null,
+): Promise<string>;
+
+/**
+ * Per-task invocation of an external CLI agent (Phase 2 stage 3).
+ * `id` selects the adapter (`"claude-code"` today; `codex` and
+ * `gemini` ship in follow-up PRs). `task` is the prompt. `optionsJson`
+ * is a JSON-encoded `InvokeOptions` — pass `"{}"` or `null` to accept
+ * defaults.
+ *
+ * `InvokeOptions` shape:
+ *
+ *   {
+ *     "cwd"?: string,                  // working directory
+ *     "allowed_tools"?: string[],      // tool allowlist; [] denies all
+ *     "max_turns"?: number,            // turn cap
+ *     "timeout_secs"?: number,         // hard deadline (default 300s)
+ *     "mcp_endpoint"?: string          // MCP server URL passed via
+ *                                      // --mcp-config; daemon callers
+ *                                      // auto-fill from car-server's
+ *                                      // bound /mcp URL. "" opts out.
+ *   }
+ *
+ * Returns JSON `InvokeResult`:
+ *
+ *   {
+ *     "answer": string,                // final agent response
+ *     "session_id"?: string,
+ *     "turns": number,
+ *     "tool_calls": number,            // tool_use blocks observed
+ *     "duration_ms": number,
+ *     "total_cost_usd"?: number,       // would-be API cost (subscription users don't pay)
+ *     "is_error": boolean,
+ *     "error"?: string
+ *   }
+ *
+ * Cost note: each invocation burns subscription quota. The runner
+ * doesn't gate cost; callers are responsible for rate limiting.
+ */
+export function agentsInvokeExternal(
+  id: string,
+  task: string,
+  optionsJson?: string | null,
+): Promise<string>;
+
+// --- A2UI surface store (car-a2ui) ---
+//
+// NOTE: NAPI-rs converts `a2ui_*` snake-case Rust names to `a2Ui*`
+// camelCase at the JS boundary because the digit→letter transition
+// after `a2` is treated as a word boundary by heck's casing rules.
+// Names below match the actual runtime exports.
+
+/**
+ * Process-singleton in-process A2UI v0.9 surface store. Wire shapes
+ * match the daemon's WebSocket `a2ui.*` methods exactly, so a host
+ * can move between transports without reshaping payloads.
+ *
+ * Embedded callers share one store across all calls in the process.
+ * Daemon-shared state (across processes) flows over the WebSocket
+ * surface — these functions do NOT proxy to the daemon.
+ *
+ * Returns JSON `A2uiCapabilities` (version, mimeType, catalogs,
+ * components, limits).
+ */
+export function a2UiCapabilities(): string;
+
+/**
+ * Apply a single A2UI envelope (`createSurface` | `updateComponents`
+ * | `updateDataModel` | `deleteSurface`). `envelopeJson` is the
+ * direct envelope shape (one message field set). Returns JSON
+ * `A2uiApplyResult` `{surfaceId, deleted, surface?}`.
+ */
+export function a2UiApply(envelopeJson: string): Promise<string>;
+
+/**
+ * Extract A2UI envelopes from a carrier payload (`{a2ui: {...}}`,
+ * A2A `DataPart`, artifact `parts`, etc.) and apply each in order.
+ * Owner is auto-extracted from A2A `taskId`/`contextId` shapes.
+ * Returns JSON `{applied: [A2uiApplyResult]}`.
+ */
+export function a2UiIngest(payloadJson: string): Promise<string>;
+
+/**
+ * List all live A2UI surfaces in the in-process store. Returns
+ * JSON `[A2uiSurface]`.
+ */
+export function a2UiSurfaces(): Promise<string>;
+
+/**
+ * Fetch a surface by id. Returns JSON `A2uiSurface` or `null` if
+ * the surface doesn't exist.
+ */
+export function a2UiGet(surfaceId: string): Promise<string>;
+
+/**
+ * Reap surfaces older than `limits.maxSurfaceAgeSecs`. Returns JSON
+ * `{removed: [surfaceId]}` — empty array when nothing was due.
+ */
+export function a2UiReap(): Promise<string>;
+
+/**
+ * Submit an A2UI user action (e.g. button click) back to the action
+ * handler. `actionJson` is the action payload. Returns JSON
+ * `{accepted: boolean, result?: any}`.
+ */
+export function a2UiAction(actionJson: string): Promise<string>;
+
+/**
+ * Validate a JSON payload against the store's size limits. Returns
+ * JSON `null` on success; rejects with a limit-exceeded error
+ * message otherwise.
+ */
+export function a2UiValidatePayload(valueJson: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "car-runtime",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "Common Agent Runtime — a deterministic execution layer for AI agents",
   "main": "index.js",
   "types": "index.d.ts",