rivet-design 0.14.9 → 0.14.11

package/dist/agent-variants/workerRuntime.d.ts

@@ -0,0 +1,230 @@
+import { spawn } from 'child_process';
+import { type BinaryProbe, type RunnerVendor } from '../cli/runnerSelection';
+import type { WorkerEffortLevel } from '../hosts/workerDefaults';
+import type { WorkerFidelity } from './contracts';
+import type { WorkItemInitiator, WorkerSelection } from '../types/change-request-types';
+/**
+ * Executor-only worker tier, discriminated by vendor so a codex tier can never
+ * be handed to the claude adapter. This registry is deliberately separate from
+ * `FIDELITY_WORKER_TIERS` (src/hosts/workerDefaults.ts), which keeps supplying
+ * the HOST-worker hint defaults — the host path is unchanged by multi-vendor
+ * executor support.
+ */
+export type ExecutorWorkerTier = {
+    vendor: 'claude';
+    model: string;
+    effort: WorkerEffortLevel;
+} | {
+    vendor: 'codex';
+    /** Omitted by default: the user's own codex default model applies, so we
+     *  never pin a model id that their account/CLI version doesn't have. */
+    model?: string;
+    reasoningEffort: WorkerEffortLevel;
+} | {
+    vendor: 'cursor';
+    /** Cursor has no per-invocation quality knob and model switching is a
+     *  known capability cliff (see FIDELITY_WORKER_TIERS docs) — one model
+     *  for every fidelity, omitted by default so the user's Cursor default
+     *  applies. */
+    model?: string;
+};
+/**
+ * Fidelity → tier, per vendor. Claude mirrors the host registry (one model,
+ * effort varies — PR #965). Codex maps fidelity onto reasoning effort, its
+ * native analogue. Cursor cannot vary quality per invocation, so fidelity is
+ * intentionally a no-op there until a per-model benchmark says otherwise.
+ */
+export declare const EXECUTOR_FIDELITY_TIERS: Record<RunnerVendor, Record<WorkerFidelity, ExecutorWorkerTier>>;
+/** Cheapest valid tier per vendor — what the preflight probe runs with. Same
+ *  flags as a real worker (the probe must test the exact invocation), minimum
+ *  spend. */
+export declare const PREFLIGHT_TIERS: Record<RunnerVendor, ExecutorWorkerTier>;
+/** What an adapter can recover from a finished worker's stdout. */
+export type WorkerResultInfo = {
+    usage?: {
+        tokensIn?: number;
+        tokensOut?: number;
+        costUsd?: number;
+    };
+    /** Error/result text the CLI reported in-band (claude puts API failures in
+     *  the stdout JSON, codex in error items) — stderr alone is not enough. */
+    resultText?: string;
+    /** Structured HTTP status of an API failure, when the CLI reports one. */
+    apiErrorStatus?: number;
+};
+/**
+ * One adapter per vendor CLI: owns the arg grammar, how the briefing prompt is
+ * delivered, and how the result stream is parsed. The executor stays
+ * vendor-agnostic. Contracts verified live: 2026-07-22 against codex-cli
+ * 0.145.0 and claude; 2026-07-23 against cursor-agent 2026.07.23-e383d2b
+ * (print mode, argv prompt, trailing-JSON result with camelCase usage).
+ */
+export interface WorkerInvocationAdapter {
+    vendor: RunnerVendor;
+    binary: string;
+    /** 'stdin': briefing piped to the child; 'argv': appended as the prompt
+     *  argument (cursor-agent ignores stdin in print mode). */
+    promptDelivery: 'stdin' | 'argv';
+    buildArgs(tier: ExecutorWorkerTier): string[];
+    parseResult(stdoutTail: string): WorkerResultInfo;
+    /** Only claude reports structured model-availability failures
+     *  (api_error_status) that can safely drive the one-shot fallback-model
+     *  retry. */
+    supportsModelFallback: boolean;
+    spawnEnv(): NodeJS.ProcessEnv;
+}
+/** Claude's `--output-format json`: one trailing JSON result object. */
+export declare const parseClaudeWorkerResult: (stdout: string) => WorkerResultInfo;
+/** Codex's `exec --json`: JSONL events. Usage rides `turn.completed`; failures
+ *  surface as `item.completed` items of type `error` (and `turn.failed`). */
+export declare const parseCodexWorkerResult: (stdout: string) => WorkerResultInfo;
+export declare const makeClaudeAdapter: (binary?: string) => WorkerInvocationAdapter;
+export declare const makeCodexAdapter: (binary?: string) => WorkerInvocationAdapter;
+/** Cursor's `-p --output-format json`: one trailing JSON result object, like
+ *  claude's — but usage keys are camelCase (`inputTokens`) and `subtype`/
+ *  `result` are populated on success too ("success"/"ok"), so error text is
+ *  taken only when `is_error` is set. Shape live-verified 2026-07-23 against
+ *  cursor-agent 2026.07.23-e383d2b. */
+export declare const parseCursorWorkerResult: (stdout: string) => WorkerResultInfo;
+export declare const makeCursorAdapter: (binary?: string) => WorkerInvocationAdapter;
+export declare const adapterForVendor: (vendor: RunnerVendor, binaryOverride?: string) => WorkerInvocationAdapter;
+export type WorkerVendorSource = 'env'
+/** Explicit `--worker-provider` on THIS request — the user's live choice,
+ *  relayed by the host agent. Outranks config and initiator; only the
+ *  RIVET_EXECUTOR_* env escape hatches outrank it. */
+ | 'request' | 'user_config' | 'initiator' | 'probe'
+/** `workerVendorFallback` substituted this vendor after the explicit /
+ *  initiator-implied one failed preflight — surfaced so logs and summaries
+ *  never attribute the switched vendor to the original selection. */
+ | 'fallback';
+export type PreflightDiagnostic = {
+    vendor: RunnerVendor;
+    binary: string;
+    reason: string;
+};
+/**
+ * The lease-owner decision. `executor` carries the healthy runtime to spawn
+ * workers with; `host` means work items lease to the host agent (the
+ * pre-executor degraded mode) and carries per-vendor diagnostics explaining
+ * why. There is deliberately no cross-vendor silent substitution: an explicit
+ * or initiator-implied vendor that fails preflight lands on the host path —
+ * running another vendor's CLI (different subscription, data handling,
+ * bypassed-permissions posture) requires the `workerVendorFallback` opt-in.
+ */
+export type WorkerRuntimeDecision = {
+    mode: 'executor';
+    adapter: WorkerInvocationAdapter;
+    source: WorkerVendorSource;
+    /** Request-pinned worker model, present ONLY when the pin belongs to
+     *  the winning adapter: the requested provider matches, or — for a
+     *  model-only request — the winner is the PRIMARY candidate the pin
+     *  was resolved against. A cross-vendor fallback (or later probe-path
+     *  candidate) winner never inherits another CLI's model id. */
+    modelOverride?: string;
+} | {
+    mode: 'host';
+    diagnostics: PreflightDiagnostic[];
+};
+/** Coarse failure bucket — the ONLY failure detail that leaves the machine
+ *  (telemetry). Raw reasons carry stderr/paths/account fragments and stay in
+ *  local logs and run feedback. */
+export type ProbeFailureCategory = 'spawn_error' | 'timeout' | 'aborted' | 'login_required' | 'exit_nonzero' | 'worker_failure';
+export type PreflightSpawn = (args: {
+    command: string;
+    args: string[];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+}) => ReturnType<typeof spawn>;
+export type WorkerRuntimeResolverOptions = {
+    /** `workerVendor` from ~/.rivet/config.json, read lazily so config edits
+     *  don't require a server restart. */
+    configuredVendor?: () => string | undefined;
+    /** `workerVendorFallback` opt-in: allow trying OTHER vendors when the
+     *  explicit/initiator vendor fails preflight. Default false. */
+    crossVendorFallback?: () => boolean;
+    /** `workerModels.<vendor>` config override for executor worker tiers. */
+    configuredModelFor?: (vendor: RunnerVendor) => string | undefined;
+    /** Claude-only preflight rung mirroring the executor's per-item
+     *  fallback-model retry: when the PRIMARY model is what fails the probe
+     *  (no access / unknown model / model-scoped rate limit), probe once more
+     *  with the fallback model before declaring the runtime unhealthy —
+     *  otherwise an account lacking the default worker model degrades to the
+     *  host path before the per-item retry ever gets a chance. */
+    probeModelFallback?: {
+        fallbackModel: () => string | undefined;
+        isModelAvailabilityFailure: (args: {
+            message?: string;
+            apiErrorStatus?: number;
+            model?: string;
+        }) => boolean;
+    };
+    probeTimeoutMs?: number;
+    binaryProbe?: BinaryProbe;
+    spawnProbe?: PreflightSpawn;
+    env?: NodeJS.ProcessEnv;
+    telemetry?: {
+        track: (event: string, properties?: Record<string, unknown>) => void;
+    };
+};
+/**
+ * Resolves and preflights the executor's worker runtime, per request.
+ *
+ * Precedence: env override (`RIVET_EXECUTOR_VENDOR`, or legacy
+ * `RIVET_EXECUTOR_COMMAND` = claude-grammar custom binary) > user config
+ * `workerVendor` > the request initiator's agent > (human / no preference)
+ * probe installed vendors in registry order.
+ *
+ * Note this is deliberately PER-REQUEST, unlike apply-runner resolution
+ * (`resolveRunner`, fixed for the server's lifetime): one live session can
+ * serve requests initiated by different agents, and each request's workers
+ * should run on its initiator's runtime.
+ *
+ * Preflight lifecycle: one in-flight probe per runtime identity (vendor +
+ * binary + resolved model — concurrent resolves join it); a healthy result
+ * is cached until a runtime-shaped worker failure invalidates it
+ * (`markUnhealthy`) or a config edit changes the resolved model; an
+ * unhealthy result is re-probed on the next resolve — so a user who fixes
+ * their auth is not stuck on the host path, and each new run retries a
+ * broken vendor at most once.
+ */
+export declare class WorkerRuntimeResolver {
+    private readonly options;
+    private readonly health;
+    private readonly inFlight;
+    constructor(options?: WorkerRuntimeResolverOptions);
+    /** Invalidate a cached-healthy vendor after a runtime-shaped worker failure
+     *  (spawn error, unknown CLI option, auth rejection) so the next run
+     *  re-probes instead of leasing four more items to a dead runtime. */
+    markUnhealthy(vendor: RunnerVendor, reason: string): void;
+    resolve(args?: {
+        initiator?: WorkItemInitiator;
+        /** Explicit per-request runtime choice (`--worker-provider` /
+         *  `--worker-model`) relayed by the host agent. */
+        selection?: WorkerSelection;
+        signal?: AbortSignal;
+    }): Promise<WorkerRuntimeDecision>;
+    /** Candidate adapters in trial order, plus whether the choice was explicit
+     *  (strict = unhealthy means host path, not another vendor). */
+    private candidatesFor;
+    private withFallbackCandidates;
+    private adapterFor;
+    /** Tier the probe runs with — cheapest per vendor, with the same model
+     *  override precedence a real worker gets (`RIVET_EXECUTOR_MODEL` env >
+     *  request `--worker-model` > `workerModels.<vendor>` config) so the probe
+     *  exercises the exact model a real worker would run, not the CLI
+     *  default. */
+    private probeTierFor;
+    private preflight;
+    /** One probe — plus, for claude (the only vendor with a structured
+     *  fallback-model rung), a second probe on the fallback model when the
+     *  primary MODEL is what failed. A healthy fallback probe marks the
+     *  runtime healthy under the primary identity: real workers still start
+     *  on the primary tier and degrade per item via the executor's one-shot
+     *  fallback retry, exactly the pre-preflight behavior. */
+    private probeWithModelFallback;
+    private runProbe;
+}
+/** One-line human summary of a decision, for run feedback and server.log:
+ *  `codex` / `host path (claude: probe exited 1: …)`. */
+export declare const describeWorkerRuntimeDecision: (decision: WorkerRuntimeDecision) => string;
+//# sourceMappingURL=workerRuntime.d.ts.map

package/dist/agent-variants/workerRuntime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workerRuntime.d.ts","sourceRoot":"","sources":["../../src/agent-variants/workerRuntime.ts"],"names":[],"mappings":"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"}