car-runtime 0.23.0 → 0.24.1

package/index.d.ts

@@ -57,6 +57,33 @@ export class CarRuntime {
    */
   persistMemory(path: string): Promise<number>;
 
+  // --- Foreman ---
+
+  /**
+   * Decompose a coding `goal` into a footprint-annotated, scheduled subtask
+   * plan. `repo` defaults to the daemon's cwd. Returns a JSON
+   * `ForemanPlanReport` (`schema_version`, `valid`, `prefer_single_session`,
+   * `levels`, `subtasks[]` with declared `writes`/`reads`).
+   */
+  foremanPlan(goal: string, repo?: string, maxAttempts?: number): Promise<string>;
+
+  /**
+   * Plan a coding `goal`, then farm the subtasks to an external coding CLI
+   * (`adapter`, default `"claude-code"`) in isolated git worktrees, gating each
+   * worktree and the integrated union. `verifyCommand` is the per-worktree
+   * **regression** check; `unionVerifyCommand` is the integrated-union **goal**
+   * check (falls back to `verifyCommand` when omitted). **Spends real agent
+   * quota.** Returns JSON `{ plan, ran, run? }`.
+   */
+  foremanRun(
+    goal: string,
+    repo?: string,
+    adapter?: string,
+    verifyCommand?: Array<string>,
+    unionVerifyCommand?: Array<string>,
+    maxAttempts?: number
+  ): Promise<string>;
+
   // --- Tools & policies ---
 
   /** Register a tool by name. */
@@ -74,11 +101,13 @@ export class CarRuntime {
    * `run_id`.
    *
    * `paramsJson` is a serialized request object:
-   * `{ intent, agent_id?, agent_name?, outcome_description? }`. When
-   * `agent_id` is omitted the daemon resolves it from the session's
+   * `{ intent, agent_id?, agent_name?, outcome_description?, idempotency_key? }`.
+   * When `agent_id` is omitted the daemon resolves it from the session's
    * `agent_id` binding, then `CAR_AGENT_ID`, then a deterministic id
-   * synthesized from `agent_name`. Returns `{ run_id, agent_id }` as a
-   * JSON string.
+   * synthesized from `agent_name`. An `idempotency_key`, when supplied,
+   * becomes the `run_id` and makes the start dedup: if a run with that id
+   * already exists the existing run is returned instead of a duplicate.
+   * Returns `{ run_id, agent_id }` as a JSON string.
    */
   runsStart(paramsJson: string): Promise<string>;
 
@@ -131,8 +160,14 @@ export class CarRuntime {
   /**
    * Set replan configuration on this runtime.
    * `maxReplans` = 0 disables replanning (default).
+   * `replanOnRejected` (default false): when true, validator/policy/capability
+   * rejections (not just runtime failures) also trigger rollback + replan.
    */
-  setReplanConfig(maxReplans: number, delayMs?: number | null): Promise<void>;
+  setReplanConfig(
+    maxReplans: number,
+    delayMs?: number | null,
+    replanOnRejected?: boolean | null,
+  ): Promise<void>;
 
   // --- State ---
 
@@ -297,9 +332,17 @@ export class CarRuntime {
   /**
    * Generate with full tracking. Returns JSON with `text`, `tool_calls`,
    * `usage`, `model_used`, `latency_ms`, `time_to_first_token_ms`,
-   * `trace_id`. `time_to_first_token_ms` is wall-clock to the first
-   * sampled token (populated by local Candle/MLX paths; `null` for
-   * non-streaming remote calls).
+   * `trace_id`, `stop_reason`. `time_to_first_token_ms` is wall-clock to
+   * the first sampled token (populated by local Candle/MLX paths; `null`
+   * for non-streaming remote calls). `stop_reason` is the raw provider
+   * termination reason (OpenAI `finish_reason`, Anthropic `stop_reason`,
+   * Google `finishReason`); `null` for local backends or providers that
+   * don't report one. A value of `"length"`/`"max_tokens"`/`"MAX_TOKENS"`
+   * means the output was truncated at the token cap. On local Qwen3
+   * hybrid-thinking models it is also set to `"thinking_recovered"` when
+   * reasoning consumed the whole token budget and the runtime retried
+   * with reasoning suppressed to produce a direct answer, or
+   * `"thinking_truncated"` when even that retry was empty (car-releases#60).
    *
    * **Note:** intent is not exposed on the tracked path until the
    * positional argument list is converted to an options object —
@@ -390,6 +433,22 @@ export class CarRuntime {
    */
   detokenize(model: string, tokens: number[]): Promise<string>;
 
+  // --- Web search ---
+
+  /**
+   * Web search. The daemon resolves the backend: the signed-in Parslee
+   * account's hosted search when available, else a bring-your-own
+   * `TAVILY_API_KEY`. Returns JSON `{ query, source, results: [{title, url,
+   * snippet, score, published_date}] }`.
+   */
+  search(query: string, maxResults?: number | null): Promise<string>;
+
+  /**
+   * Fetch a URL and extract readable text (keyless; companion to `search`).
+   * Returns JSON `{ url, status, content_type, title?, text }`.
+   */
+  webFetch(url: string): Promise<string>;
+
   // --- Speech ---
 
   /** Prepare the managed speech runtime and return its root path. */
@@ -436,7 +495,10 @@ export class CarRuntime {
   /**
    * Unified registry (local + remote). Returns JSON array of
    * `{ id, name, provider, capabilities, param_count, size_mb,
-   *   context_length, available, is_local, public_benchmarks }`.
+   *   context_length, available, is_local, max_output_tokens,
+   *   public_benchmarks }`. `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.
@@ -469,6 +531,121 @@ export class CarRuntime {
    */
   recommend(useCase: string, tier: string, cloudOk: boolean): Promise<string>;
 
+  /**
+   * Coder — built-in coding agent (`coder.*` daemon namespace). Sessions
+   * live in the daemon and are visible in CarHost. Live `coder.event`
+   * streaming is WebSocket-only: call `coder.subscribe` on the daemon's
+   * WS directly (same contract as `infer.stream`).
+   *
+   * Start a session: provisions an isolated git worktree of `repo` and
+   * derives a verifiable outcome contract from `intent`. `engine` is
+   * `"auto" | "native" | "external[:agent_id]"` (default auto). Returns
+   * `{session_id, state, engine, worktree, contract}` JSON.
+   */
+  coderStart(
+    repo: string,
+    intent: string,
+    engine?: string | undefined | null,
+    maxIterations?: number | undefined | null,
+  ): Promise<string>;
+
+  /**
+   * Confirm the proposed outcome contract (optionally replacing it with
+   * the edited `contractJson`) and start the work loop.
+   */
+  coderConfirmContract(
+    sessionId: string,
+    contractJson?: string | undefined | null,
+  ): Promise<string>;
+
+  /** List coder sessions (live and persisted), newest first. */
+  coderList(): Promise<string>;
+
+  /** Full session detail, including contract and check results. */
+  coderGet(sessionId: string): Promise<string>;
+
+  /**
+   * Answer a `user_input_requested` event (reserved — neither engine
+   * requests mid-session input yet).
+   */
+  coderRespond(sessionId: string, text: string): Promise<string>;
+
+  /**
+   * Approve (publish the `car/coder/<id>` branch in the repo) or deny
+   * (abandon) a session awaiting merge approval.
+   */
+  coderApproveMerge(sessionId: string, approve: boolean): Promise<string>;
+
+  /** Cancel a session: stop the loop, abandon, remove the worktree. */
+  coderCancel(sessionId: string): Promise<string>;
+
+  /**
+   * Managed projects + in-daemon declarative agents (the non-developer path).
+   *
+   * Create (or load) a CAR-managed git-backed project under
+   * `~/.car/projects/`. `kind` is `"app"` (code) or `"agent"` (an in-daemon
+   * declarative agent). Returns the `CoderProject` JSON.
+   */
+  projectCreate(name: string, kind?: string | undefined | null): Promise<string>;
+  /** List managed projects, newest first. */
+  projectList(): Promise<string>;
+  /** One project's metadata by slug. */
+  projectGet(slug: string): Promise<string>;
+
+  /**
+   * Discover what the signed-in Parslee account can do — identity, m365
+   * product entitlements, and Studio reachability. Read-only. Returns JSON.
+   */
+  parsleeCapabilities(): Promise<string>;
+  /**
+   * Generate a Word document from a natural-language brief, saved to the
+   * user's connected drive. Gated on the `aie` entitlement. `documentType`
+   * defaults to `Report`. Returns JSON `{ file_id, web_url, ... }`.
+   */
+  parsleeM365GenerateDocument(contentBrief: string, outputFilePath: string, documentType?: string | undefined | null, title?: string | undefined | null, author?: string | undefined | null): Promise<string>;
+
+  /** List registered in-daemon declarative agents. */
+  declagentList(): Promise<string>;
+  /** One declarative agent's spec by id. */
+  declagentGet(id: string): Promise<string>;
+  /** Unregister a declarative agent. */
+  declagentRemove(id: string): Promise<string>;
+  /** Enable or disable a declarative agent. */
+  declagentSetEnabled(id: string, enabled: boolean): Promise<string>;
+  /**
+   * Run a declarative agent on an input, in-daemon (no external process).
+   * Returns `{ output, turns, tool_calls, error? }` JSON.
+   */
+  declagentInvoke(id: string, input: string): Promise<string>;
+  /**
+   * Route a need to the best-matching declarative agent by capability
+   * similarity. Returns `{ chosen, candidates, next_visited, invoked, result? }`
+   * JSON. With `invoke: true`, the top agent is run on `need` and its result is
+   * included. Network-entry case only; multi-hop Forward chaining (`from` /
+   * `visited`) is WS-only.
+   */
+  declagentRoute(need: string, invoke: boolean): Promise<string>;
+  /**
+   * Split a composite need into subtasks and route each to its best-matching
+   * agent. Returns `{ subtasks: [{ subtask, chosen, score, result? }], count,
+   * invoked }` JSON. `maxSubtasks` caps the split (clamped to [1, 10]; null =
+   * default 5). With `invoke: true`, each subtask's chosen agent runs.
+   */
+  declagentRouteSplit(need: string, invoke: boolean, maxSubtasks?: number | undefined | null): Promise<string>;
+  /**
+   * Read-only view of the learned routing topology: per-agent success stats
+   * and directed agent→agent edge weights. Returns `{ agents, edges }` JSON.
+   */
+  declagentRoutingStats(): Promise<string>;
+  /**
+   * AgentDNS-style discovery: resolve a natural-language need into ranked
+   * CAR-local services, each named under `agentdns://org/category/name`.
+   * Returns `{ services: [{ identifier, name, kind, protocol, score,
+   * similarity }], count }` JSON. `limit` caps results (clamped to [1, 50];
+   * null = default 5).
+   */
+  discoveryResolve(need: string, limit?: number | undefined | null): Promise<string>;
+
   /**
    * Build a concrete onboarding plan (machine summary, top pick, alternatives,
    * needs-more-memory, note) as JSON.
@@ -895,6 +1072,15 @@ export interface IntentHint {
    * `prefer_local` if both are set.
    */
   prefer_fast?: boolean;
+  /**
+   * Bias the score profile toward the most capable model — quality
+   * dominates, latency and cost near-floor (maps to
+   * `RoutingWorkload::Quality`). For quality-critical, infrequent work
+   * (building/verifying an agent, deriving a contract, structured
+   * extraction) where a weak model fails. Precedence: `prefer_fast` wins,
+   * then `prefer_quality`, then `prefer_local`.
+   */
+  prefer_quality?: boolean;
 }
 
 // --- Voice streaming (stored-callback pattern) ---
@@ -1006,6 +1192,27 @@ export function registerToolHandler(
  */
 export function unregisterToolHandler(): void;
 
+/**
+ * Register the callback fired when a tool callback is reaped
+ * (Parslee-ai/car#264). When a `tools.execute` callback exceeds its budget the
+ * daemon emits a `tools.cancel` notification; this callback receives the
+ * reaped call's `requestId` (the same `request_id` surfaced on the originating
+ * `tools.execute` call_json) so the host can abort the in-flight child it
+ * registered under that id (e.g. `AbortController.abort()` / `child.kill()`).
+ *
+ * Fire-and-forget — no return value. Process-wide setter; re-calling
+ * overwrites. Pair with `unregisterToolCancelHandler` to clear.
+ */
+export function registerToolCancelHandler(
+  handlerFn: (requestId: string) => void,
+): void;
+
+/**
+ * Clear the registered `tools.cancel` handler. Subsequent reaps are no longer
+ * routed to the host (the daemon has already abandoned the call regardless).
+ */
+export function unregisterToolCancelHandler(): void;
+
 export function transcribeStream(
   rt: CarRuntime,
   sessionId: string,
@@ -1717,11 +1924,32 @@ export function agentsStop(id: string, signal?: string | null): Promise<string>;
 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[]}`.
+ * Read a window of an agent's logs under
+ * `~/.car/logs/<id>.{stdout,stderr}.log`.
+ *
+ * - `n` caps lines per included stream (default 100; `0` ⇒ whole file,
+ *   still bounded by the tail byte ceiling below).
+ * - `stream` selects `"stdout"`, `"stderr"`, or `"combined"` (default).
+ *   Each stream is tailed independently, so a long stale stderr can no
+ *   longer bury live stdout (Parslee-ai/car#273).
+ * - `offset` pages back: skip this many lines from the end of each
+ *   stream before taking the window (`offset = n` ⇒ previous page).
+ *   Combined-view paging is not order-preserving — page within a single
+ *   stream to scroll back.
+ *
+ * Each stream is read via a bounded backward seek (at most an 8 MiB
+ * tail), not a whole-file slurp, since agent logs are append-only and
+ * never rotated. A log larger than the ceiling is truncated to its last
+ * 8 MiB and `more` is forced `true`.
+ *
+ * Returns JSON `{ lines: string[], stdout: string[], stderr: string[],
+ * stdoutTotal: number, stderrTotal: number, stdoutPath: string,
+ * stderrPath: string, more: boolean }`. `lines` keeps the legacy
+ * stdout-then-stderr combined view for back-compat. `stdoutTotal` /
+ * `stderrTotal` count lines in the scanned tail (exact within the
+ * ceiling).
  */
-export function agentsTailLog(id: string, n?: number | null): Promise<string>;
+export function agentsTailLog(id: string, n?: number | null, stream?: string | null, offset?: number | null): Promise<string>;
 
 // --- External-agent detection (car-external-agents) ---
 //

package/package.json

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