bareloop 0.22.0 → 0.23.0

package/types/providers.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Look up a provider's table entry. Throws a NAMED error on an unrecognized
+ * provider — never a silent default (the `resolveRates`-style-substring-
+ * match lesson: a forward hazard even at zero observed rounds, MEMORY.md).
+ * `src/job.js`'s `PROVIDERS` menu is the one place a spec's `provider`
+ * field is validated; this is the runtime construction seam it feeds.
+ * @param {string} providerName
+ * @returns {ProviderTableEntry}
+ */
+export function resolveProvider(providerName: string): ProviderTableEntry;
+/**
+ * Construct ONE provider instance for `providerName`/`model`, applying
+ * `exposeErrorBody: true` (F153 — every constructed provider, unconditionally)
+ * and the model's own request-key gating (`paramsFor`). `baseUrl` (PRD item
+ * 28, ruling (d), 2026-09-09: admitted in v1) is forwarded only when given —
+ * every provider constructor here defaults it on its own when absent.
+ * @param {string} providerName
+ * @param {{apiKey?: string, model?: string, baseUrl?: string}} [options]
+ */
+export function makeProvider(providerName: string, { apiKey, model, baseUrl }?: {
+    apiKey?: string;
+    model?: string;
+    baseUrl?: string;
+}): any;
+/**
+ * Build the `{provider, providerFor, judgeProvider}` triple both runners
+ * need (`src/cli.js`'s `buildProviders`, `scripts/run-u.mjs`'s top-level
+ * wiring) — ONE seam instead of two copies of the same construction and
+ * tier-memoization logic. `model`/`tierModels` are already-RESOLVED inputs
+ * (the caller runs `resolveWorkerModel` itself, exactly as both runners did
+ * before this factory existed — that decision stays where each runner's own
+ * `--model` flag/spec precedence lives, not duplicated in here).
+ *
+ * The JUDGE stays pinned to `anthropic-api`/`judgeModel` regardless of
+ * `providerName` — arbiter territory (PRD item 28: "the judge stays PINNED
+ * … regardless of the job's worker provider"). A signed `judge:{provider,
+ * model}` field with its own calibration record is PRD item 28 part (2),
+ * NOT built here; until it lands, the judge always needs its own
+ * `judgeApiKey` (today, always `ANTHROPIC_API_KEY`), independent of which
+ * key the worker used.
+ * @param {object} args
+ * @param {string} args.providerName spec.provider (or the anthropic-api default)
+ * @param {string|undefined} args.apiKey the WORKER's key, read from the provider's own `envKey`
+ * @param {string} args.model the already-resolved worker model id
+ * @param {Readonly<Record<string, string>>} args.tierModels the already-resolved tier -> model map (spec override folded in by the caller)
+ * @param {string|undefined} [args.baseUrl] spec.baseUrl, if any
+ * @param {string|undefined} args.judgeApiKey the judge's own key (today: `ANTHROPIC_API_KEY`)
+ * @param {string} args.judgeModel `JUDGE_MODEL`
+ */
+export function buildRunnerProviders({ providerName, apiKey, model, tierModels, baseUrl, judgeApiKey, judgeModel, }: {
+    providerName: string;
+    apiKey: string | undefined;
+    model: string;
+    tierModels: Readonly<Record<string, string>>;
+    baseUrl?: string | undefined;
+    judgeApiKey: string | undefined;
+    judgeModel: string;
+}): {
+    provider: any;
+    providerFor: (tier: string) => any;
+    judgeProvider: any;
+};
+/**
+ * Today's anthropic-api tier table — EXACTLY the `DEFAULT_TIER_MODELS` both
+ * runners hardcoded before this factory existed. Any change to these two
+ * values is a change to shipped anthropic-api behaviour, not a refactor.
+ */
+export const ANTHROPIC_TIER_MODELS: Readonly<{
+    sonnet: "claude-sonnet-5";
+    haiku: "claude-haiku-4-5-20251001";
+}>;
+/**
+ * DeepSeek (F149/F150) is a SINGLE model, not a tiered family — hamr's
+ * ruling above: one secondary provider, not a menu. Both tiers map to the
+ * same model id ON PURPOSE: `resolveWorkerModel`/a runner's `providerFor
+ * (tier)` only ever LOOK UP a tier's model id (src/job.js:818-827,
+ * scripts/run-u.mjs's `providerFor`) — neither assumes the tiers name
+ * different models — so repeating the one id is the honest representation
+ * of a single-model provider, not a second model masquerading as `haiku`.
+ * If DeepSeek (or a future openai-api entrant) ever ships a genuinely
+ * cheaper tier model, this is where it would earn its own `haiku` id.
+ */
+export const OPENAI_TIER_MODELS: Readonly<{
+    sonnet: "deepseek-chat";
+    haiku: "deepseek-chat";
+}>;
+export type ProviderTableEntry = {
+    /**
+     * the bare-agent provider class
+     */
+    ctor: new (options: any) => any;
+    /**
+     * the environment variable this provider reads its key from
+     */
+    envKey: string;
+    /**
+     * tier name -> model id
+     */
+    tiers: Readonly<Record<string, string>>;
+    /**
+     * per-model request-key/param gating, applied on TOP of {exposeErrorBody:true, apiKey, model, baseUrl?}
+     */
+    paramsFor: (model: string | undefined) => Record<string, any>;
+};

package/types/ratelimit.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Is `err` an HTTP 429 (rate-limited) response? True ONLY for an explicit
+ * status of 429 on the error itself. Nothing else qualifies — not message
+ * text (a message merely containing "429" is not this), not `retryable`,
+ * not any other status. Symmetric with `isTransportFailure`'s own status
+ * check (src/transport.js), just reading the opposite branch of it.
+ * @param {any} err
+ * @returns {boolean}
+ */
+export function isRateLimited(err: any): boolean;
+/**
+ * The vendor's RAW stated wait, in milliseconds, parsed straight from the
+ * error message — no default, no margin, no cap. `null` when nothing in the
+ * message matches a known shape. Exported separately from `rateLimitWaitMs`
+ * so a caller that wants to report the vendor's own number on the spine
+ * (`statedMs`) never has to re-derive it from the margin-adjusted figure.
+ *
+ * bare-agent does not expose the vendor's `retry-after` /
+ * `x-ratelimit-reset-*` response headers on the thrown error (BA-26) — the
+ * delay exists only in the vendor's English message text, so this parses
+ * that text. Verified real shape (OpenAI, run `8ev2sdkn`, 2026-09-08):
+ * "Please try again in 11.996s." This also supports "try again in 1.5
+ * seconds", "try again in 20ms", "retry after 30s", and "retry after 30
+ * seconds" — case-insensitive.
+ * @param {any} err
+ * @returns {number|null}
+ */
+export function statedWaitMs(err: any): number | null;
+/**
+ * How long to wait before retrying a 429, in milliseconds — or `null`
+ * meaning "do not retry at all" (either the parsed wait exceeds
+ * `RATE_LIMIT_MAX_WAIT_MS`, in which case waiting that long is the
+ * operator's decision, not ours).
+ *
+ * A parsed value gets `PARSED_DELAY_MARGIN_MS` added (the vendor's stated
+ * number is the earliest moment its window resets, not a safe one to fire
+ * on), capped so the margin itself can never push a parsed value over
+ * `RATE_LIMIT_MAX_WAIT_MS`. When nothing parses, `RATE_LIMIT_DEFAULT_WAIT_MS`
+ * is returned as-is, with no margin added (there is nothing to add margin
+ * to — it is already a conservative guess, not an earliest-moment reading).
+ * @param {any} err
+ * @returns {number|null}
+ */
+export function rateLimitWaitMs(err: any): number | null;
+/** The fixed retry budget: ONE extra attempt after a 429. Never read from a
+ * job spec or CLI flag — raising it is arbiter territory, mirroring
+ * transport.js's TRANSPORT_RETRIES exactly (tighten-only doctrine). */
+export const RATE_LIMIT_RETRIES: 1;
+/** bare-agent's `Retry.call` (if ever used) counts ATTEMPTS, not retries;
+ * this module's own hand-rolled ladder (src/planrun.js) does the same for
+ * symmetry with TRANSPORT_MAX_ATTEMPTS. */
+export const RATE_LIMIT_MAX_ATTEMPTS: number;
+/** The hard cap on how long we will ever wait for a vendor-stated 429 delay.
+ * A vendor asking for longer than this is not honoured — we do not retry at
+ * all in that case. Waiting that long is the operator's decision, not ours
+ * (arbiter territory: nothing here escalates the wait past what hamr set). */
+export const RATE_LIMIT_MAX_WAIT_MS: 60000;
+/** Used only when the vendor's message carries no parseable delay at all. */
+export const RATE_LIMIT_DEFAULT_WAIT_MS: 5000;

package/types/run.d.ts

@@ -167,6 +167,14 @@
  *   'close-red' | 'close-unsupported' | 'recipe-stale' | 'branch-red' | 'pricing-red' | 'provider-red' |
  *   'interpreter-red' | 'cap-halt' | 'wall-halt' | 'step-stalled' |
  *   'hitl-pause' | 'hitl-decision-red' | `step-red:<id>`
+ *   NOTE: `job-end` can ALSO land with outcome 'runner-drained' (F140/PRD item
+ *   28(c)) — the `beforeExit` backstop's own terminal, emitted from OUTSIDE this
+ *   function's normal control flow when the process drains with no `job-end` at
+ *   all (a provider promise that never settled). It never appears as this
+ *   function's own RETURN value (nothing is left to receive it), only as the
+ *   spine's terminal record. Non-zero exit, `spendComplete:false` always, and
+ *   deliberately NOT in the resumable/checkpoint set (`src/reuse.js`) — an
+ *   unknown in-flight state is not a known-safe resume point.
  */
 export function runJob(rawSpec: object | string, { approvals, workdir, provider, nativeProvider, providerFor, judgeProvider, emit, capRuns, strikeLimit, shellCapUsd, closeTimeoutMs, closeDir, layerRoot, readShim, scout, bridge, priorSpentUsd, priorSpendComplete, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, reviewDoor, doorRerun, resumable }: {
     approvals: unknown;

package/types/transport.d.ts

@@ -2,11 +2,17 @@
  * Is `err` a transport-class failure — the request never produced an HTTP
  * response? True for: a TLS fault mid-record ("bad record mac" and kin), a
  * reset/broken/timed-out socket (ECONNRESET, EPIPE, ETIMEDOUT, ECONNREFUSED,
- * ENETUNREACH — by code on the error itself or on `err.cause`), and
- * `fetch failed` wrapping a network `cause`. False for anything carrying an
- * HTTP status (`err.status`/`err.statusCode`, 4xx/5xx/429) or an explicit
+ * ENETUNREACH — by code on the error itself or on `err.cause`), `fetch
+ * failed` wrapping a network `cause`, and — as of bare-agent 0.42.0 (BA-25)
+ * — a `ProviderError` whose `err.context.bound === 'transport'`: the
+ * response stream ended (`'aborted'`/`'error'`/premature `'close'`) after
+ * headers but before the body completed, which bare-agent itself rejects as
+ * retryable with no HTTP status. False for anything carrying an HTTP status
+ * (`err.status`/`err.statusCode`, 4xx/5xx/429) or an explicit
  * `err.retryable === false` — those are provider RESPONSES, not transport
- * casualties, and bare-agent's own policy governs them unchanged.
+ * casualties, and bare-agent's own policy governs them unchanged; both
+ * guards run BEFORE the `context.bound` check, so a status or an explicit
+ * `retryable:false` wins even if `bound` says 'transport'.
  * @param {any} err
  * @returns {boolean}
  */