car-runtime 0.19.0 → 0.21.0

package/index.d.ts

@@ -65,6 +65,34 @@ export class CarRuntime {
   /** Register CAR's built-in agent utility tools. */
   registerAgentBasics(): Promise<void>;
 
+  /**
+   * Start an agent run on the daemon (agent run tracing). Brackets the
+   * beginning of a run: the daemon mints a durable `run_id`, resolves
+   * the owning `agent_id`, tags it as the session's current run before
+   * replying, and records that the run started. Await this before
+   * submitting any proposal so the per-turn recorder reads the right
+   * `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
+   * `agent_id` binding, then `CAR_AGENT_ID`, then a deterministic id
+   * synthesized from `agent_name`. Returns `{ run_id, agent_id }` as a
+   * JSON string.
+   */
+  runsStart(paramsJson: string): Promise<string>;
+
+  /**
+   * Complete an agent run on the daemon (agent run tracing). Records
+   * the terminal `AgentOutcome` for `run_id` and acks. Await this ack
+   * before letting the connection close so a healthy run is never
+   * mislabeled `Incomplete`.
+   *
+   * `paramsJson` is a serialized request object: `{ run_id, outcome }`.
+   * Returns `{ run_id, ok }` as a JSON string.
+   */
+  runsComplete(paramsJson: string): Promise<string>;
+
   /**
    * Open a policy-scoping session and return its opaque id. Hosts
    * that drive multiple concurrent agent contexts through one
@@ -217,6 +245,39 @@ export class CarRuntime {
   /** Evolve skills for a domain based on failed events. Returns JSON array. */
   evolveSkills(eventsJson: string, domain: string): Promise<string>;
 
+  /**
+   * Ingest distilled/evolved skills as validation-gated PROVISIONAL candidates
+   * on trial (vs `ingestDistilledSkills`, which trusts them active). Returns the
+   * count ingested. See docs/solutions/gated-skill-optimization.md.
+   */
+  ingestProvisionalSkills(skillsJson: string, tenant?: string | null): number;
+
+  /**
+   * Run the skill promotion gate: provisional candidates with enough trial
+   * outcomes are promoted (strictly-better Wilson lower bound) or rejected.
+   * Returns JSON `{ promoted: string[], rejected: string[] }`.
+   */
+  gateSkillCandidates(): Promise<string>;
+
+  /**
+   * Fetch a skill's full SkillMeta by key (lifecycle `status`, `incumbent`,
+   * `version`, `stats`). Returns JSON SkillMeta, or the string "null" if absent.
+   */
+  skillMeta(key: string): Promise<string>;
+
+  /**
+   * Export a VALIDATED skill as a portable markdown document (the SkillOpt
+   * best_skill.md analog). Only Active, healthy skills export. Returns the
+   * markdown, or null if the key is absent / not exportable.
+   */
+  exportSkill(key: string): Promise<string | null>;
+
+  /**
+   * Import a skill from a portable markdown document (digest-verified). Returns
+   * true on success; rejects malformed or tampered documents.
+   */
+  importSkill(markdown: string): Promise<boolean>;
+
   // --- Inference ---
 
   /**
@@ -277,6 +338,15 @@ export class CarRuntime {
    */
   inferTrackedWithRequest(requestJson: string): Promise<string>;
 
+  /**
+   * Build a runnable workflow from a natural-language goal via the daemon's
+   * builder. `requestJson` is `{ goal, existing?, max_attempts? }`; on the
+   * daemon the catalog (registered tools + models) is authoritative, so the
+   * tool cross-check fires. Returns
+   * `{ valid, workflow, issues, warnings, attempts }` as JSON.
+   */
+  buildWorkflow(requestJson: string): Promise<string>;
+
   /**
    * Generate text grounded with memory context from this runtime's
    * memgine. `intentJson` works the same as on {@link infer}.
@@ -391,6 +461,35 @@ export class CarRuntime {
    */
   registerModel(schemaJson: string): Promise<string>;
 
+  /**
+   * Recommend models for this machine + intent. `useCase`/`tier` are
+   * snake_case enum values (e.g. "coding", "most_capable"); `cloudOk` lets
+   * cloud models compete. Returns the `RecommendationSet` JSON
+   * (`{ picks, notEnoughMemory, note }`).
+   */
+  recommend(useCase: string, tier: string, cloudOk: boolean): Promise<string>;
+
+  /**
+   * Build a concrete onboarding plan (machine summary, top pick, alternatives,
+   * needs-more-memory, note) as JSON.
+   */
+  setupPlan(useCase: string, tier: string, cloudOk: boolean): Promise<string>;
+
+  /** Detect upgrades (curated + upstream, channel-gated). Returns JSON. */
+  detectUpgrades(): Promise<string>;
+
+  /** Current proactive-upgrade decision (poll form). Returns JSON. */
+  checkUpgradeNudge(inferenceActive: boolean): Promise<string>;
+
+  /** Dismiss an upgrade nudge by its `dismissKey` so it never re-fires. */
+  dismissUpgrade(dismissKey: string): Promise<string>;
+
+  /** Get update preferences as JSON. */
+  updatePrefsGet(): Promise<string>;
+
+  /** Set update preferences (JSON `UpdatePreferences` shape). Returns stored prefs JSON. */
+  updatePrefsSet(prefsJson: string): Promise<string>;
+
   /** Route a prompt. Returns the routing decision as JSON. */
   routeModel(prompt: string): Promise<string>;
 
@@ -568,6 +667,25 @@ export class CarRuntime {
     calendarIdsCsv?: string | null,
   ): string;
 
+  /**
+   * Create a calendar event. `inputJson` is JSON-encoded
+   * `{ calendar_id, title, start, end, all_day?, notes?, location?, url? }`
+   * with RFC3339 timestamps. Returns JSON-encoded EventMutationResult.
+   */
+  calendarCreateEvent(inputJson: string): string;
+
+  /**
+   * Update an existing event. `inputJson` is JSON-encoded
+   * `{ event_id, title?, start?, end?, all_day?, notes?, location?, url? }`.
+   * Absent fields leave existing values; empty string for
+   * notes/location/url clears that field. Returns JSON-encoded
+   * EventMutationResult.
+   */
+  calendarUpdateEvent(inputJson: string): string;
+
+  /** Delete an event by host-assigned id. Returns JSON-encoded EventMutationResult. */
+  calendarDeleteEvent(eventId: string): string;
+
   /** Returns JSON array of contact containers (sources). */
   contactsContainers(): string;
 
@@ -1064,6 +1182,15 @@ export function removeEnrollment(rt: CarRuntime, label: string): string;
  */
 export function runWorkflow(workflowJson: string): Promise<string>;
 
+/**
+ * Resume a workflow that paused at a human-in-the-loop approval gate.
+ * `pausedJson` is the `paused` checkpoint object from a prior `runWorkflow`
+ * (or `resumeWorkflow`) result; `inputJson` is a JSON object of the human's
+ * response fields. Returns the next workflow result JSON, which may itself be
+ * paused again at another gate.
+ */
+export function resumeWorkflow(pausedJson: string, inputJson: string): Promise<string>;
+
 /** Static analysis on a workflow definition. Returns verification report JSON. */
 export function verifyWorkflow(workflowJson: string): string;
 
@@ -1254,21 +1381,53 @@ export function registerAgentRunner(
 // See docs/websocket-protocol.md §"Inference runner" for the wire shape.
 // `car-server` is shipped as a binary in this npm package (`bin/car-server`).
 
-/** Run a Swarm pattern. `mode` is "parallel", "sequential", or "debate". */
+/**
+ * Coordination budget — a runtime-enforced spend ceiling for one multi-agent
+ * run. Passed to the `run*` functions as a JSON string (`JSON.stringify`).
+ * Every field is optional; an omitted field is unbounded.
+ *
+ * The runtime sums the token/cost spend reported by the agent runner and
+ * refuses to START further agents once a limit is crossed (overshoot is bounded
+ * by the in-flight work already launched). `maxAgents` is a hard cap on agents
+ * started. Note: these are snake_case JSON keys, matching the Rust `BudgetLimits`.
+ *
+ * ```ts
+ * const budget = JSON.stringify({ max_total_tokens: 200000, max_agents: 12 });
+ * await runSwarm("parallel", agents, task, null, budget);
+ * ```
+ */
+export interface BudgetLimits {
+  max_input_tokens?: number | null;
+  max_output_tokens?: number | null;
+  max_total_tokens?: number | null;
+  max_cost_usd?: number | null;
+  max_agents?: number | null;
+}
+
+/**
+ * Run a Swarm pattern. `mode` is "parallel", "sequential", or "debate".
+ * `budgetSpec` is an optional JSON-encoded {@link BudgetLimits}.
+ */
 export function runSwarm(
   mode: string,
   agents: string,
   task: string,
   synthesizerSpec?: string | null,
+  budgetSpec?: string | null,
 ): Promise<string>;
 
-export function runPipeline(stages: string, task: string): Promise<string>;
+export function runPipeline(
+  stages: string,
+  task: string,
+  budgetSpec?: string | null,
+): Promise<string>;
 
 export function runSupervisor(
   workers: string,
   supervisor: string,
   task: string,
   maxRounds: number,
+  budgetSpec?: string | null,
 ): Promise<string>;
 
 export function runMapReduce(
@@ -1276,12 +1435,41 @@ export function runMapReduce(
   reducer: string,
   task: string,
   items: string,
+  budgetSpec?: string | null,
 ): Promise<string>;
 
 export function runVote(
   agents: string,
   task: string,
   synthesizerSpec?: string | null,
+  budgetSpec?: string | null,
+): Promise<string>;
+
+/**
+ * Run a Tournament pattern: rank `competitors` (AgentSpec[] JSON) by
+ * single-elimination pairwise judging with a `judge` (AgentSpec JSON). Returns
+ * TournamentResult JSON ({ winner_name, winner_answer, ranking, matches, ... }).
+ * `budgetSpec` is an optional JSON-encoded {@link BudgetLimits}.
+ */
+export function runTournament(
+  competitors: string,
+  judge: string,
+  task: string,
+  budgetSpec?: string | null,
+): Promise<string>;
+
+/**
+ * Run an agent that can spawn isolated, tool-constrained sub-agents via the
+ * `spawn_subtask` tool. `mainAgent` is the main AgentSpec JSON; a spawned
+ * sub-agent may only use a subset of its tools (enforced by the tool schema's
+ * `enum` and re-checked at execution). `budgetSpec` is an optional JSON-encoded
+ * {@link BudgetLimits} that also caps the sub-agents this agent may spawn.
+ * Returns SpawnSubtaskResult JSON.
+ */
+export function runSubtask(
+  mainAgent: string,
+  task: string,
+  budgetSpec?: string | null,
 ): Promise<string>;
 
 // --- Scheduler ---

package/package.json

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