maestro-agent-sdk 0.1.37 → 0.1.39

package/dist/providers/fallback.js

@@ -1,223 +0,0 @@
-import { isAbortError } from "../core/is-abort-error.js";
-import { logger } from "../platform/logger.js";
-import { getNativeMaxOutputTokens } from "../registry.js";
-/**
- * Provider wrapper that falls back from a `primary` to a `fallback` provider
- * when the primary fails *before producing any output*.
- *
- * Motivating case: the Codex `/responses` backend (ChatGPT-OAuth) is the
- * primary for `gpt-5.*` models, but its OAuth refresh, HTTP round-trip, and
- * time-to-first-byte all happen INSIDE `stream()` before the first chunk is
- * yielded (see `codex.ts` — `fromEnv()` only constructs; auth resolves at
- * stream time). When any of those legs throws — OAuth dead, HTTP 401/429/5xx,
- * connect/TTFB timeout, network reset — this wrapper retries the turn against
- * DeepSeek instead of surfacing a hard `error` event.
- *
- * ## Why pre-first-chunk only
- *
- * Once the primary has yielded ANY chunk, the host has already displayed text
- * (or a tool_use has started) and the assistant turn's history is half-built.
- * Restarting against a different provider there would double-emit content and
- * desync the loop's message accumulation. So the switch is only safe before
- * the first chunk — after that, errors propagate unchanged. This covers the
- * overwhelming majority of "codex isn't working" failures, which are all
- * pre-stream by construction.
- *
- * ## Model id + maxTokens rewrite
- *
- * The agent loop passes the primary's resolved model id (e.g. `gpt-5.5`) in
- * `ProviderCompleteOptions.model`. DeepSeek would 400 on that slug, so the
- * fallback delegation rewrites `opts.model` to `fallbackModel` and clamps
- * `opts.maxTokens` to the fallback model's native output ceiling (a gpt-5.5
- * `maxTokens` could exceed a flash-tier fallback's cap). `thinkingBudget` is
- * harmlessly ignored by DeepSeek; `effort` is honored natively. Tools and
- * messages pass through untouched — each provider runs its own translation
- * from the shared `ProviderMessage` shape.
- *
- * ## Compaction props
- *
- * `compactionTriggerRatio` / `compactionTailProtect` / `guidedCompaction` are
- * read once by the loop *before* the turn, so they reflect the PRIMARY's
- * preference (Codex compacts early + guided). If the fallback fires, DeepSeek
- * runs against a slightly-more-aggressively-compacted history — harmless, and
- * not worth the complexity of swapping mid-turn.
- */
-export class FallbackProvider {
-    primary;
-    fallbackFactory;
-    fallbackModel;
-    fallbackInstance = null;
-    /**
-     * @param primary        The preferred provider (e.g. Codex).
-     * @param fallbackFactory Lazily constructs the fallback provider. Deferred so
-     *   a process that never trips the fallback never pays its construction cost
-     *   (and never requires its env to be present until actually needed).
-     * @param fallbackModel  Wire model id handed to the fallback provider, e.g.
-     *   `deepseek-v4-pro`. Replaces the primary's model id on delegation.
-     */
-    constructor(primary, fallbackFactory, fallbackModel) {
-        this.primary = primary;
-        this.fallbackFactory = fallbackFactory;
-        this.fallbackModel = fallbackModel;
-    }
-    // Surface the PRIMARY's compaction preferences to the loop (see class doc).
-    get compactionTriggerRatio() {
-        return this.primary.compactionTriggerRatio;
-    }
-    get compactionTailProtect() {
-        return this.primary.compactionTailProtect;
-    }
-    get guidedCompaction() {
-        return this.primary.guidedCompaction;
-    }
-    getFallback() {
-        if (!this.fallbackInstance) {
-            this.fallbackInstance = this.fallbackFactory();
-        }
-        return this.fallbackInstance;
-    }
-    /** Rewrite the request for the fallback provider: swap model id, clamp
-     *  maxTokens to the fallback's native output ceiling. */
-    rewriteOpts(opts) {
-        const cap = getNativeMaxOutputTokens(this.fallbackModel);
-        // Treat a missing OR non-positive maxTokens as "use the fallback's native
-        // cap". A literal `0` would otherwise survive the `??` (it's not nullish)
-        // and clamp to `Math.min(0, cap) === 0`, sending `max_tokens: 0` to the
-        // fallback — DeepSeek 400s on that, turning a recoverable codex failure
-        // into a hard error. The codex primary silently drops maxTokens, so a 0
-        // only becomes fatal after the fallback rewrite.
-        const want = opts.maxTokens && opts.maxTokens > 0 ? opts.maxTokens : cap;
-        return {
-            ...opts,
-            model: this.fallbackModel,
-            maxTokens: Math.min(want, cap),
-        };
-    }
-    shouldRethrow(e, opts) {
-        return isAbortError(e) || opts.abortSignal?.aborted === true;
-    }
-    async *stream(opts) {
-        // Single source for the primary stream so the pre-first-chunk guard below
-        // applies uniformly whether the primary streams natively or is adapted
-        // from `complete()`. Codex/DeepSeek both implement `stream()`; the
-        // complete()-adapter branch only guards a future stream-less primary.
-        const iter = this.primary.stream
-            ? this.primary.stream(opts)
-            : this.streamViaComplete(this.primary, opts);
-        let started = false;
-        try {
-            while (true) {
-                let result;
-                try {
-                    result = await iter.next();
-                }
-                catch (e) {
-                    // After the first chunk, or on a user abort, the error is terminal.
-                    if (started || this.shouldRethrow(e, opts))
-                        throw e;
-                    logger.warn({
-                        err: e,
-                        errName: e instanceof Error ? e.name : typeof e,
-                        errMessage: e instanceof Error ? e.message : String(e),
-                        primaryModel: opts.model,
-                        fallbackModel: this.fallbackModel,
-                    }, "FallbackProvider: primary failed before first chunk — falling back");
-                    const fb = this.getFallback();
-                    if (!fb.stream) {
-                        throw new Error("FallbackProvider: fallback provider has no stream()");
-                    }
-                    // Attach the primary failure as `cause` so a double-failure (DeepSeek
-                    // also down) doesn't hide why codex died — the surfaced error message
-                    // is DeepSeek's, but the codex error is recoverable from `.cause`.
-                    try {
-                        yield* fb.stream(this.rewriteOpts(opts));
-                    }
-                    catch (fallbackErr) {
-                        throw attachCause(fallbackErr, e);
-                    }
-                    return;
-                }
-                if (result.done)
-                    return;
-                started = true;
-                yield result.value;
-            }
-        }
-        finally {
-            // The primary is driven manually via `iter.next()` (not `yield*`), so a
-            // consumer `.return()` / `.throw()` — early `break`, downstream
-            // exception, host abort — does NOT auto-forward to it. Without this, the
-            // primary's cleanup `finally` (codex `parseSseFrames`: reader.releaseLock
-            // + abort-listener removal) never runs, leaking the ReadableStream reader
-            // lock and the abort listener. No-op when the primary already finished or
-            // errored. (The fallback path uses `yield*`, which forwards `.return()`
-            // on its own.)
-            await iter.return?.(undefined);
-        }
-    }
-    async complete(opts) {
-        try {
-            return await this.primary.complete(opts);
-        }
-        catch (e) {
-            if (this.shouldRethrow(e, opts))
-                throw e;
-            logger.warn({
-                err: e,
-                errName: e instanceof Error ? e.name : typeof e,
-                primaryModel: opts.model,
-                fallbackModel: this.fallbackModel,
-            }, "FallbackProvider: primary complete() failed — falling back");
-            try {
-                return await this.getFallback().complete(this.rewriteOpts(opts));
-            }
-            catch (fallbackErr) {
-                // Preserve the primary failure as `.cause` (see stream() for rationale).
-                throw attachCause(fallbackErr, e);
-            }
-        }
-    }
-    /** Adapt a `complete()`-only primary into the streaming shape. Defensive
-     *  helper for the stream-less-primary branch; unused for Codex/DeepSeek. */
-    async *streamViaComplete(provider, opts) {
-        const res = await provider.complete(opts);
-        for (const block of res.content) {
-            if (block.type === "text") {
-                yield { type: "text_delta", text: block.text };
-            }
-            else if (block.type === "thinking") {
-                yield { type: "thinking_complete", block };
-            }
-            else if (block.type === "tool_use") {
-                yield { type: "tool_use_start", id: block.id, name: block.name };
-                yield {
-                    type: "tool_use_input_delta",
-                    id: block.id,
-                    partial_json: JSON.stringify(block.input),
-                };
-                yield { type: "tool_use_complete", id: block.id, name: block.name };
-            }
-        }
-        yield { type: "message_complete", stopReason: res.stopReason, usage: res.usage };
-    }
-}
-/**
- * Attach `cause` to a thrown fallback error so a double-failure keeps a trail
- * back to the primary failure. The surfaced `.message` stays the fallback's
- * (that's what actually failed last), but `.cause` recovers why the primary
- * tripped the fallback in the first place. Only sets `cause` when the error is
- * an `Error` without one already, and swallows the rare read-only-`cause` case
- * — attaching debug context must never itself throw.
- */
-function attachCause(error, cause) {
-    if (error instanceof Error && error.cause === undefined) {
-        try {
-            error.cause = cause;
-        }
-        catch {
-            // `cause` is non-writable on some custom error subclasses — ignore.
-        }
-    }
-    return error;
-}
-//# sourceMappingURL=fallback.js.map

package/dist/providers/fallback.js.map

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