car-runtime 0.6.0 → 0.7.0

package/index.d.ts

@@ -49,9 +49,30 @@ export class CarRuntime {
   /** Register CAR's built-in agent utility tools. */
   registerAgentBasics(): Promise<void>;
 
+  /**
+   * Open a policy-scoping session and return its opaque id. Hosts
+   * that drive multiple concurrent agent contexts through one
+   * CarRuntime (IDE per-project rules, multi-tenant servers) call
+   * this once per context, then pass the id to subsequent
+   * `registerPolicy` and `executeProposal` calls so per-context rules
+   * stack on top of any global ones. Embedded only.
+   * See `docs/proposals/per-session-policy-scoping.md`.
+   */
+  openSession(): Promise<string>;
+
+  /**
+   * Close a session and drop every policy scoped to it. Returns true
+   * if a session by that id existed, false if it didn't (already
+   * closed, never opened).
+   */
+  closeSession(sessionId: string): Promise<boolean>;
+
   /**
    * Register a policy enforced in Rust on every action.
-   * `rule` is one of: "deny_tool", "deny_tool_param", "require_state".
+   * `rule` is one of: "deny_tool", "deny_tool_param", "require_state",
+   * "deny_tool_callback".
+   * `sessionId`, when set, scopes the policy to the named session
+   * (opened via `openSession`). Without it, the policy is global.
    */
   registerPolicy(
     name: string,
@@ -60,6 +81,7 @@ export class CarRuntime {
     key?: string | null,
     pattern?: string | null,
     valueJson?: string | null,
+    sessionId?: string | null,
   ): Promise<void>;
 
   /**
@@ -339,6 +361,15 @@ export class CarRuntime {
   /** Count of events in this runtime's execution log. */
   eventCount(): Promise<number>;
 
+  /** Execution log counts and approximate retained native bytes. Returns JSON. */
+  eventLogStats(): Promise<string>;
+
+  /** Keep only the newest events/spans in this runtime's execution log. Returns JSON. */
+  truncateEventLog(maxEvents?: number | null, maxSpans?: number | null): Promise<string>;
+
+  /** Clear this runtime's execution log. Returns JSON. */
+  clearEventLog(): Promise<string>;
+
   /** Verify a proposal against this runtime's state + tools. Returns JSON. */
   verifyProposal(proposalJson: string): Promise<string>;
 
@@ -460,7 +491,7 @@ export class CarRuntime {
   accountsOpen(accountId?: string | null): string;
 
   // -------------------------------------------------------------------------
-  // Calendar / Contacts / Mail integrations (delegated to OS providers)
+  // Calendar / Contacts / Mail / Messages integrations (delegated to OS providers)
   // -------------------------------------------------------------------------
 
   /** Returns JSON array of calendars discovered through the OS provider. */
@@ -501,6 +532,42 @@ export class CarRuntime {
    */
   mailSend(sendRequestJson: string): string;
 
+  /** Returns JSON array of Messages.app services/accounts. */
+  messagesServices(): string;
+
+  /** Returns JSON array of recent Messages.app chats. */
+  messagesChats(limit?: number | null): string;
+
+  /**
+   * Send a message through Messages.app. `sendRequestJson` is
+   * `{recipient, body, service_id?}`.
+   */
+  messagesSend(sendRequestJson: string): string;
+
+  /** Returns JSON array of Notes.app accounts. */
+  notesAccounts(): string;
+
+  /** Search Notes.app notes. */
+  notesFind(query: string, limit?: number | null): string;
+
+  /** Returns JSON array of Reminders.app lists. */
+  remindersLists(): string;
+
+  /** Returns JSON array of incomplete reminders. */
+  remindersItems(limit?: number | null): string;
+
+  /** Returns JSON array of Photos.app albums. */
+  photosAlbums(): string;
+
+  /** Returns JSON array of Safari bookmarks. */
+  bookmarksList(limit?: number | null): string;
+
+  /** Returns JSON standard account-backed file locations. */
+  filesLocations(): string;
+
+  /** Returns JSON OS keychain availability. */
+  keychainStatus(): string;
+
   // -------------------------------------------------------------------------
   // Wearable / activity (HealthKit + Fitbit/Garmin/Oura/etc.)
   // -------------------------------------------------------------------------
@@ -526,11 +593,18 @@ export class CarRuntime {
  * 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.
+ *
+ * `sessionId`, when provided, scopes per-action policy validation to
+ * the named session opened via `CarRuntime.openSession()`. Global
+ * 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`.
  */
 export function executeProposal(
   rt: CarRuntime,
   proposalJson: string,
   toolFn: (callJson: string) => Promise<string>,
+  sessionId?: string | null,
 ): Promise<string>;
 
 /**
@@ -622,6 +696,14 @@ export interface IntentHint {
    * quality-aware with a strong local_bonus so the hint wins ties.
    */
   prefer_local?: boolean;
+  /**
+   * Bias the score profile aggressively toward time-to-first-token.
+   * Maps to `RoutingWorkload::Fastest` — heavy latency weight, near-zero
+   * quality and cost weight. Designed for the fast track in voice-turn
+   * dispatch (sub-500ms first-audio target). Takes precedence over
+   * `prefer_local` if both are set.
+   */
+  prefer_fast?: boolean;
 }
 
 // --- Voice streaming (stored-callback pattern) ---
@@ -661,6 +743,23 @@ export interface TranscribeStreamOptions {
    * built lazily from `~/.car/voiceprints/`.
    */
   enrolled?: boolean;
+  /**
+   * Voice-context prompt overlay prepended to system prompts on the
+   * voice-invoked inference path. Omit (or pass `null`) to use the
+   * built-in default. An empty string disables the overlay (e.g. for
+   * callers who already supply their own voice-tuned system prompt).
+   */
+  voice_prompt_overlay?: string | null;
+  /**
+   * Streaming STT provider override. Currently only meaningful with
+   * `pcm_push` sources. `'elevenlabs'` opens an ElevenLabs Realtime
+   * websocket and forwards pushed PCM frames to it instead of running
+   * the in-process VAD + batch STT pipeline. Requires
+   * `ELEVENLABS_API_KEY` in env, config, or keychain. `'local'` is the
+   * explicit form of the default behavior. Unrecognised values fail at
+   * `transcribeStreamStart` time with a clear error.
+   */
+  provider?: 'elevenlabs' | 'local';
 }
 
 export type VoiceStreamEvent =
@@ -696,6 +795,66 @@ export function transcribeStreamPush(
 
 export function listVoiceSessions(rt: CarRuntime): string;
 
+// --- Voice turn dispatch (two-track sidecar pattern) ---
+
+export interface DispatchVoiceTurnRequest {
+  /** Finalized utterance text (typically from STT). */
+  utterance: string;
+  /** Optional voice session id this turn belongs to. */
+  session_id?: string | null;
+  /**
+   * Optional override for the voice-context overlay.
+   * `null`/omitted uses the default; an empty string disables.
+   */
+  config_overlay?: string | null;
+  /** Optional sidecar wait timeout in milliseconds. Default 30000. */
+  sidecar_timeout_ms?: number | null;
+}
+
+export interface DispatchVoiceTurnResponse {
+  turn_id: number;
+}
+
+export type VoiceTurnEvent =
+  | { type: 'voice.turn.fast_delta'; turn_id: number; text: string }
+  | { type: 'voice.turn.fast_done'; turn_id: number }
+  | {
+      type: 'voice.turn.bridge';
+      turn_id: number;
+      kind: 'email' | 'calendar' | 'search' | 'unknown';
+      phrase: string;
+    }
+  | { type: 'voice.turn.sidecar'; turn_id: number; text: string }
+  | { type: 'voice.turn.error'; turn_id: number; error: string }
+  | { type: 'voice.turn.cancelled'; turn_id: number };
+
+/**
+ * Dispatch a voice-turn utterance through the two-track sidecar pattern.
+ *
+ * Returns `{"turn_id": N}` (JSON-encoded) synchronously. Subsequent
+ * fast deltas, bridge phrases, sidecar results, errors, and
+ * cancellations flow through the JS callback registered via
+ * `registerVoiceEventHandler` as JSON-encoded `VoiceTurnEvent` objects.
+ * The host plays audio (or otherwise renders) from those events —
+ * CAR does NOT own the speaker on this path.
+ *
+ * Not available in Daemon mode (no in-process inference engine);
+ * connect to `ws://127.0.0.1:9100/` for the WebSocket flow there.
+ */
+export function dispatchVoiceTurn(rt: CarRuntime, requestJson: string): Promise<string>;
+
+/** Cancel the in-flight voice turn (if any). Idempotent. */
+export function cancelVoiceTurn(rt: CarRuntime): Promise<void>;
+
+/**
+ * Issue a 1-token probe with `prefer_fast: true` so the fast model is
+ * loaded into memory before the first user turn. Best-effort and
+ * idempotent — call at app startup.
+ *
+ * Not available in Daemon mode.
+ */
+export function prewarmVoiceTurn(rt: CarRuntime): Promise<void>;
+
 /**
  * Voice providers (STT + TTS) compiled into this build.
  *
@@ -928,6 +1087,44 @@ export function registerAgentRunner(
   agentFn: (specJson: string, taskJson: string) => Promise<string>,
 ): Promise<void>;
 
+/**
+ * Register the inference runner callback. Closes
+ * Parslee-ai/car-releases#24 — when a model schema declares
+ * `source: { type: "delegated", ... }`, CAR routes the request through
+ * this callback. The host owns the wire format (Anthropic, OpenAI,
+ * Vercel AI SDK, GitHub Models, etc.); CAR observes events and stays
+ * in the policy / replay path.
+ *
+ * The runner emits stream events for every chunk it receives from its
+ * provider via `inferenceRunnerEmitEvent(callId, eventJson)`, then
+ * resolves the promise with the final aggregated result JSON
+ * (`{text: string, tool_calls: ToolCall[]}`).
+ *
+ * Idempotent — re-calling overwrites the previous runner. Only one
+ * runner can be registered per process (matches `registerAgentRunner`).
+ *
+ * Event JSON shapes match `inferStream`'s event taxonomy:
+ *   `{type: "text", data: string}`
+ *   `{type: "tool_start", name: string, index: number, id?: string}`
+ *   `{type: "tool_delta", index: number, data: string}`
+ *   `{type: "usage", input_tokens: number, output_tokens: number}`
+ *   `{type: "done", text: string, tool_calls: ToolCall[]}`
+ */
+export function registerInferenceRunner(
+  runnerFn: (requestJson: string, callId: string) => Promise<string>,
+): void;
+
+/**
+ * Emit a stream event from inside the inference runner callback.
+ * `callId` is the second argument the runner received; `eventJson`
+ * is one of the shapes documented on `registerInferenceRunner`.
+ *
+ * Silently no-ops if `callId` is unknown (call already completed or
+ * the runner emitted after returning) — racing the normal completion
+ * path shouldn't error.
+ */
+export function inferenceRunnerEmitEvent(callId: string, eventJson: string): void;
+
 /** Run a Swarm pattern. `mode` is "parallel", "sequential", or "debate". */
 export function runSwarm(
   mode: string,

package/package.json

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