car-runtime 0.43.0 → 0.45.0

package/index.d.ts

@@ -34,6 +34,33 @@
  */
 
 /** Persistent runtime instance with state, memory, tools, and policies. */
+/**
+ * Optional settings for `coderStart`. Every field is independently omittable;
+ * each falls back to the daemon's `~/.car/coder.toml`.
+ *
+ * **Breaking (v0.44.0):** replaced five trailing positional optionals — three
+ * of them numbers — which callers could silently mis-order.
+ */
+export interface CoderStartOptions {
+  /** `"auto" | "native" | "external[:agent_id]" | "foreman[:agent_id]"`. */
+  engine?: string | undefined | null;
+  /** Contract-evaluation rounds before the native loop gives up. */
+  maxIterations?: number | undefined | null;
+  /** Per-session backbone pin, reaching whichever engine runs. */
+  model?: string | undefined | null;
+  /**
+   * External-engine hypothesis budget: fresh repair invocations after a red
+   * pass. Recurrence escalation needs >= 2 to reach the model at all.
+   */
+  repairInvokes?: number | undefined | null;
+  /**
+   * External-engine availability budget: re-invocations after the CLI process
+   * died mid-run. Separate from `repairInvokes` on purpose — one buys a
+   * hypothesis, the other buys a retry.
+   */
+  transientRetries?: number | undefined | null;
+}
+
 export class CarRuntime {
   constructor();
 
@@ -726,12 +753,25 @@ export class CarRuntime {
    * Unified registry (local + remote). Returns JSON array of
    * `{ id, name, provider, capabilities, param_count, size_mb,
    *   context_length, available, is_local, max_output_tokens,
-   *   public_benchmarks }`. `max_output_tokens` is the registry-declared
+   *   public_benchmarks, cost }`. `max_output_tokens` is the registry-declared
    *   per-model output ceiling (`null` when the entry omits it; callers
    *   then fall back to a fraction of `context_length`).
    * `public_benchmarks` is `[{ name, score, harness?, source_url?,
    * measured_at? }]` with score on a 0.0–1.0 scale; ships empty in
    * the built-in catalog and is populated via curated registry data.
+   * `cost` is the model's declared prices — `{ input_per_mtok,
+   * output_per_mtok, cache_read_input_per_mtok, cache_write_input_per_mtok,
+   * pricing_tiers, size_mb, ram_mb }` — in USD per 1M tokens, with
+   * `pricing_tiers` as `[{ min_prompt_tokens, ...prices }]` prompt-size
+   * overrides (highest threshold not above the prompt wins). Every price is
+   * nullable and `null` means **unpriced, not free**: a local model declares
+   * no prices, and a caller that reads that as `0` publishes a fabricated
+   * cost. The managed `parslee/…` alias rows carry the same prices as the
+   * upstream row they front, and this response carries no upstream
+   * identifier for them. That holds for this catalog view; `models.search`
+   * additionally exposes a `family` field which does name the upstream
+   * model family. Older daemons omit
+   * `cost` entirely; it deserializes to all-`null` rather than failing.
    */
   listModelsUnified(): string;
 
@@ -845,9 +885,7 @@ export class CarRuntime {
   coderStart(
     repo: string,
     intent: string,
-    engine?: string | undefined | null,
-    maxIterations?: number | undefined | null,
-    model?: string | undefined | null,
+    options?: CoderStartOptions | undefined | null,
   ): Promise<string>;
 
   /**
@@ -3266,9 +3304,27 @@ export function agentsTailLog(id: string, n?: number | null, stream?: string | n
  * installed AND ready to use" answer. Returns JSON
  * `[ExternalAgentSpec]` (empty array when nothing installed).
  *
+ * `ExternalAgentSpec.execution` (car#746) is the authoritative answer to
+ * "can this binary run at all":
+ *     { state: "runnable" }
+ *   | { state: "unusable", reason: string, checked_at: number }
+ * Written by detection, never revised by a health refresh. `health`
+ * answers a different question (is it authenticated) and is owned by
+ * refreshers that may rewrite it. Prefer `execution` over
+ * `health.status === "not_executable"`, which is still emitted for one
+ * compatibility window. An absent `execution` reads as "runnable".
+ *
  * `ExternalAgentSpec.health` shape (when populated):
  *   { id, status, details, reason?, checked_at }
- *   status: "ready" | "not_configured" | "expired" | "network_error" | "unknown"
+ *   status: "ready" | "not_configured" | "expired" | "network_error"
+ *         | "not_executable" | "unknown"
+ *
+ * `health` is also populated **without** `includeHealth` in one case:
+ * when detection finds the binary but proves it cannot be executed,
+ * the spec comes back with `status: "not_executable"` and a `reason`
+ * naming the path. Do not invoke a spec in that state — it will be
+ * killed at exec. Typical cause on macOS is Gatekeeper quarantine on
+ * a binary installed outside the App Store.
  *
  * The `auth_kind` field is **deprecated** (Phase 2 stage 1) — modern
  * builds keep credentials in OS keystores so the heuristic falls
@@ -3303,11 +3359,16 @@ export function agentsDetectExternal(
  *   {
  *     "id": "claude-code" | "codex" | "gemini",
  *     "status": "ready" | "not_configured" | "expired" |
- *               "network_error" | "unknown",
+ *               "network_error" | "not_executable" | "unknown",
  *     "details": <tool-specific JSON object>,
  *     "reason": <human-readable string when not Ready>,
  *     "checked_at": <unix-secs>
  *   }
+ *
+ * `not_executable` is set by *detection*, not by an auth-status
+ * command — a binary the OS won't run can't report its own auth
+ * state. It means the install is broken, not that the user is signed
+ * out, so don't prompt for a login flow.
  */
 export function agentsHealthExternal(
   id?: string | null,

package/package.json

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