harness-dispatch 0.4.0

package/dist/quota.js

@@ -0,0 +1,331 @@
+/**
+ * Quota management for harness-dispatch.
+ *
+ * Ported from `coding_agent.quota`. Two-layer approach:
+ *   1. Reactive — quota state is updated from every dispatch response
+ *      (rate-limit headers on 429s, or usage headers on success).
+ *   2. Proactive — each dispatcher can optionally implement `checkQuota()`
+ *      for a live snapshot. Results are cached with a TTL to avoid
+ *      hammering provider APIs.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { parseLimit, parseRemaining, } from "./dispatchers/shared/rate-limit-headers.js";
+export const DEFAULT_QUOTA_TTL_MS = 300_000; // 5 minutes
+export const PROACTIVE_CHECK_TIMEOUT_MS = 15_000;
+/**
+ * Default quota state location — same HARNESS_DISPATCH_STATE_DIR-override,
+ * else ~/.harness-dispatch/<subdir> pattern as jobs.ts/dispatch-log.ts. A
+ * bare "quota_state.json" (the old default) resolves relative to
+ * process.cwd(): running the router from different directories splits
+ * state across stray files, and — worse — the test suite writes real
+ * counts into whatever cwd the tests happen to run from (this repo's own
+ * root, in dev) since nothing points it elsewhere by default.
+ */
+function defaultStateFile() {
+    const dir = process.env.HARNESS_DISPATCH_STATE_DIR ?? path.join(homedir(), ".harness-dispatch");
+    return path.join(dir, "quota_state.json");
+}
+function monotonicSec() {
+    return performance.now() / 1000;
+}
+/** Mutable quota snapshot for one service, updated reactively. */
+export class QuotaState {
+    service;
+    remaining = null;
+    limit = null;
+    used = null;
+    resetAt = null;
+    source = "unknown";
+    updatedAtSec = 0; // performance.now() seconds
+    constructor(service) {
+        this.service = service;
+    }
+    get score() {
+        if (this.remaining !== null && this.limit && this.limit > 0) {
+            return Math.max(0, Math.min(1, this.remaining / this.limit));
+        }
+        if (this.used !== null && this.limit && this.limit > 0) {
+            return Math.max(0, Math.min(1, (this.limit - this.used) / this.limit));
+        }
+        return 1.0;
+    }
+    updateFromQuotaInfo(info) {
+        this.remaining = info.remaining ?? null;
+        this.limit = info.limit ?? null;
+        this.used = info.used ?? null;
+        this.resetAt = info.resetAt ?? null;
+        this.source = info.source;
+        this.updatedAtSec = monotonicSec();
+    }
+    toJSON() {
+        return {
+            used: this.used,
+            limit: this.limit,
+            remaining: this.remaining,
+            resetAt: this.resetAt,
+            score: this.score,
+            source: this.source,
+            updatedAgeSec: Math.round((monotonicSec() - this.updatedAtSec) * 10) / 10,
+        };
+    }
+}
+/**
+ * Manages quota state for all dispatchers.
+ */
+export class QuotaCache {
+    dispatchers;
+    ttlMs;
+    stateFile;
+    states = {};
+    /** performance.now() seconds of last proactive check per service. */
+    lastChecked = {};
+    localCounts;
+    localSuccessCounts;
+    localFailureCounts;
+    persistCounter = 0;
+    constructor(dispatchers, opts = {}) {
+        this.dispatchers = dispatchers;
+        this.ttlMs = opts.ttlMs ?? DEFAULT_QUOTA_TTL_MS;
+        this.stateFile = opts.stateFile ?? defaultStateFile();
+        for (const name of Object.keys(dispatchers)) {
+            this.states[name] = new QuotaState(name);
+        }
+        const loaded = this.loadLocalCounts();
+        this.localCounts = loaded.calls;
+        this.localSuccessCounts = loaded.success;
+        this.localFailureCounts = loaded.failure;
+    }
+    // ------------------------------------------------------------------
+    // Public API — called by Router
+    // ------------------------------------------------------------------
+    async getQuotaScore(service) {
+        await this.maybeRefresh(service);
+        const state = this.states[service];
+        return state ? state.score : 1.0;
+    }
+    recordResult(service, result) {
+        this.localCounts[service] = (this.localCounts[service] ?? 0) + 1;
+        if (result.success) {
+            this.localSuccessCounts[service] = (this.localSuccessCounts[service] ?? 0) + 1;
+        }
+        else {
+            this.localFailureCounts[service] = (this.localFailureCounts[service] ?? 0) + 1;
+        }
+        // CLI commands often exit immediately after a route. Use the synchronous
+        // atomic path so local-count persistence cannot leave a temp file behind.
+        this.saveLocalCountsSync();
+        if (!result.rateLimitHeaders && !result.rateLimited) {
+            return;
+        }
+        let state = this.states[service];
+        if (!state) {
+            state = new QuotaState(service);
+            this.states[service] = state;
+        }
+        if (result.rateLimitHeaders) {
+            const remaining = parseRemaining(result.rateLimitHeaders);
+            const limit = parseLimit(result.rateLimitHeaders);
+            if (remaining !== null || limit !== null) {
+                state.remaining = remaining;
+                state.limit = limit;
+                state.source = "headers";
+                state.updatedAtSec = monotonicSec();
+            }
+        }
+    }
+    async getQuotaInfo(service) {
+        await this.maybeRefresh(service);
+        const state = this.states[service];
+        if (!state) {
+            return null;
+        }
+        const info = {
+            service,
+            source: state.source,
+        };
+        if (state.used !== null)
+            info.used = state.used;
+        if (state.limit !== null)
+            info.limit = state.limit;
+        if (state.remaining !== null)
+            info.remaining = state.remaining;
+        if (state.resetAt !== null)
+            info.resetAt = state.resetAt;
+        return info;
+    }
+    async fullStatus() {
+        const out = {};
+        for (const service of Object.keys(this.dispatchers)) {
+            await this.maybeRefresh(service);
+            const state = this.states[service] ?? new QuotaState(service);
+            out[service] = {
+                ...state.toJSON(),
+                localCallCount: this.localCounts[service] ?? 0,
+                localSuccessCount: this.localSuccessCounts[service] ?? 0,
+                localFailureCount: this.localFailureCounts[service] ?? 0,
+            };
+        }
+        return out;
+    }
+    // ------------------------------------------------------------------
+    // Proactive refresh
+    // ------------------------------------------------------------------
+    async maybeRefresh(service) {
+        const last = this.lastChecked[service];
+        // Node's performance.now() starts near 0 at process start, unlike Python's
+        // time.monotonic() (which references OS boot). Treat "never checked" as a
+        // force-refresh rather than comparing against 0 — otherwise the first call
+        // in a freshly-started process may short-circuit before TTL elapses.
+        if (last !== undefined && monotonicSec() - last < this.ttlMs / 1000) {
+            return;
+        }
+        const dispatcher = this.dispatchers[service];
+        if (!dispatcher) {
+            return;
+        }
+        this.lastChecked[service] = monotonicSec();
+        try {
+            const info = await withTimeout(dispatcher.checkQuota(), PROACTIVE_CHECK_TIMEOUT_MS);
+            if (info.source !== "unknown") {
+                let state = this.states[service];
+                if (!state) {
+                    state = new QuotaState(service);
+                    this.states[service] = state;
+                }
+                state.updateFromQuotaInfo(info);
+            }
+        }
+        catch {
+            // Proactive check failed — rely on reactive state.
+        }
+    }
+    // ------------------------------------------------------------------
+    // Local count persistence
+    // ------------------------------------------------------------------
+    loadLocalCounts() {
+        if (!existsSync(this.stateFile)) {
+            return { calls: {}, success: {}, failure: {} };
+        }
+        try {
+            const raw = readFileSync(this.stateFile, "utf-8");
+            const data = JSON.parse(raw);
+            const calls = {};
+            const success = {};
+            const failure = {};
+            for (const [k, v] of Object.entries(data)) {
+                if (!v)
+                    continue;
+                if (typeof v.local_calls === "number")
+                    calls[k] = v.local_calls;
+                if (typeof v.local_success === "number")
+                    success[k] = v.local_success;
+                if (typeof v.local_failure === "number")
+                    failure[k] = v.local_failure;
+            }
+            return { calls, success, failure };
+        }
+        catch {
+            return { calls: {}, success: {}, failure: {} };
+        }
+    }
+    /**
+     * Build the on-disk payload, merging new counts over any existing state.
+     *
+     * Known limitation: this read-modify-write is not atomic across processes.
+     * Two `harness-dispatch` CLI invocations racing on the same stateFile can
+     * both read the same baseline and each write back only their own count,
+     * silently losing the other's increment. Left as-is deliberately —
+     * localCallCount/localSuccessCount/localFailureCount are purely
+     * informational (surfaced in `status`/`doctor`/`usage` output and the live
+     * dashboard; see status.ts, dashboard/live.ts), never consulted by
+     * QuotaState.score or any routing/billing decision — so an occasional
+     * undercount here doesn't affect what the router actually does, only what
+     * it reports. Not worth cross-process file locking for a display counter.
+     */
+    buildStatePayload() {
+        let existing = {};
+        try {
+            if (existsSync(this.stateFile)) {
+                const raw = readFileSync(this.stateFile, "utf-8");
+                const parsed = JSON.parse(raw);
+                if (parsed && typeof parsed === "object") {
+                    existing = parsed;
+                }
+            }
+        }
+        catch {
+            existing = {};
+        }
+        for (const [service, count] of Object.entries(this.localCounts)) {
+            const bucket = existing[service] ?? {};
+            bucket["local_calls"] = count;
+            existing[service] = bucket;
+        }
+        for (const [service, count] of Object.entries(this.localSuccessCounts)) {
+            const bucket = existing[service] ?? {};
+            bucket["local_success"] = count;
+            existing[service] = bucket;
+        }
+        for (const [service, count] of Object.entries(this.localFailureCounts)) {
+            const bucket = existing[service] ?? {};
+            bucket["local_failure"] = count;
+            existing[service] = bucket;
+        }
+        return JSON.stringify(existing, null, 2);
+    }
+    nextTempStateFile() {
+        this.persistCounter += 1;
+        return `${this.stateFile}.${process.pid}.${Date.now()}.${this.persistCounter}.tmp`;
+    }
+    writeStatePayloadAtomicSync(payload) {
+        const tmp = this.nextTempStateFile();
+        try {
+            mkdirSync(path.dirname(this.stateFile), { recursive: true });
+            writeFileSync(tmp, payload);
+            renameSync(tmp, this.stateFile);
+        }
+        catch (err) {
+            try {
+                unlinkSync(tmp);
+            }
+            catch {
+                // Ignore cleanup failures.
+            }
+            throw err;
+        }
+    }
+    /**
+     * Write local counts to disk via a temp-file-then-rename (atomic within
+     * this process — see buildStatePayload's doc comment for the known
+     * cross-process caveat). Synchronous so a CLI invocation that exits
+     * immediately after a route can't leave a temp file behind.
+     */
+    saveLocalCountsSync() {
+        try {
+            this.writeStatePayloadAtomicSync(this.buildStatePayload());
+        }
+        catch {
+            // Ignore.
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function withTimeout(promise, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new Error(`timeout after ${timeoutMs}ms`));
+        }, timeoutMs);
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (err) => {
+            clearTimeout(timer);
+            reject(err instanceof Error ? err : new Error(String(err)));
+        });
+    });
+}
+//# sourceMappingURL=quota.js.map

package/dist/quota.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quota.js","sourceRoot":"","sources":["../src/quota.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,UAAU,EACV,SAAS,EACT,YAAY,EACZ,UAAU,EACV,UAAU,EACV,aAAa,GACd,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,IAAI,MAAM,WAAW,CAAC;AAI7B,OAAO,EACL,UAAU,EACV,cAAc,GACf,MAAM,4CAA4C,CAAC;AAEpD,MAAM,CAAC,MAAM,oBAAoB,GAAG,OAAO,CAAC,CAAC,YAAY;AACzD,MAAM,CAAC,MAAM,0BAA0B,GAAG,MAAM,CAAC;AAEjD;;;;;;;;GAQG;AACH,SAAS,gBAAgB;IACvB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,0BAA0B,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,mBAAmB,CAAC,CAAC;IAChG,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,kBAAkB,CAAC,CAAC;AAC5C,CAAC;AAED,SAAS,YAAY;IACnB,OAAO,WAAW,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;AAClC,CAAC;AAeD,kEAAkE;AAClE,MAAM,OAAO,UAAU;IACrB,OAAO,CAAS;IAChB,SAAS,GAAkB,IAAI,CAAC;IAChC,KAAK,GAAkB,IAAI,CAAC;IAC5B,IAAI,GAAkB,IAAI,CAAC;IAC3B,OAAO,GAAkB,IAAI,CAAC;IAC9B,MAAM,GAAW,SAAS,CAAC;IAC3B,YAAY,GAAG,CAAC,CAAC,CAAC,4BAA4B;IAE9C,YAAY,OAAe;QACzB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,IAAI,KAAK;QACP,IAAI,IAAI,CAAC,SAAS,KAAK,IAAI,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC;YAC5D,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QAC/D,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC;YACvD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QACzE,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,mBAAmB,CAAC,IAAe;QACjC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC;QACxC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC;QAC9B,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC;QACpC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,YAAY,GAAG,YAAY,EAAE,CAAC;IACrC,CAAC;IAED,MAAM;QACJ,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,aAAa,EACX,IAAI,CAAC,KAAK,CAAC,CAAC,YAAY,EAAE,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE;SAC7D,CAAC;IACJ,CAAC;CACF;AAOD;;GAEG;AACH,MAAM,OAAO,UAAU;IACb,WAAW,CAA6B;IACxC,KAAK,CAAS;IACd,SAAS,CAAS;IAClB,MAAM,GAA+B,EAAE,CAAC;IAChD,qEAAqE;IAC7D,WAAW,GAA2B,EAAE,CAAC;IACzC,WAAW,CAAyB;IACpC,kBAAkB,CAAyB;IAC3C,kBAAkB,CAAyB;IAC3C,cAAc,GAAG,CAAC,CAAC;IAE3B,YACE,WAAuC,EACvC,OAA0B,EAAE;QAE5B,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,oBAAoB,CAAC;QAChD,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,gBAAgB,EAAE,CAAC;QAEtD,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;YAC5C,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC;QAC3C,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,CAAC,eAAe,EAAE,CAAC;QACtC,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,KAAK,CAAC;QAChC,IAAI,CAAC,kBAAkB,GAAG,MAAM,CAAC,OAAO,CAAC;QACzC,IAAI,CAAC,kBAAkB,GAAG,MAAM,CAAC,OAAO,CAAC;IAC3C,CAAC;IAED,qEAAqE;IACrE,gCAAgC;IAChC,qEAAqE;IAErE,KAAK,CAAC,aAAa,CAAC,OAAe;QACjC,MAAM,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;QACjC,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACnC,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC;IACnC,CAAC;IAED,YAAY,CAAC,OAAe,EAAE,MAAsB;QAClD,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;QACjE,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;QACjF,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;QACjF,CAAC;QAED,yEAAyE;QACzE,0EAA0E;QAC1E,IAAI,CAAC,mBAAmB,EAAE,CAAC;QAE3B,IAAI,CAAC,MAAM,CAAC,gBAAgB,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;YACpD,OAAO;QACT,CAAC;QAED,IAAI,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACjC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,KAAK,GAAG,IAAI,UAAU,CAAC,OAAO,CAAC,CAAC;YAChC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,KAAK,CAAC;QAC/B,CAAC;QAED,IAAI,MAAM,CAAC,gBAAgB,EAAE,CAAC;YAC5B,MAAM,SAAS,GAAG,cAAc,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;YAC1D,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;YAClD,IAAI,SAAS,KAAK,IAAI,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBACzC,KAAK,CAAC,SAAS,GAAG,SAAS,CAAC;gBAC5B,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC;gBACpB,KAAK,CAAC,MAAM,GAAG,SAAS,CAAC;gBACzB,KAAK,CAAC,YAAY,GAAG,YAAY,EAAE,CAAC;YACtC,CAAC;QACH,CAAC;IACH,CAAC;IAED,KAAK,CAAC,YAAY,CAAC,OAAe;QAChC,MAAM,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;QACjC,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACnC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,IAAI,GAAc;YACtB,OAAO;YACP,MAAM,EAAE,KAAK,CAAC,MAA6B;SAC5C,CAAC;QACF,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI;YAAE,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;QAChD,IAAI,KAAK,CAAC,KAAK,KAAK,IAAI;YAAE,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;QACnD,IAAI,KAAK,CAAC,SAAS,KAAK,IAAI;YAAE,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC;QAC/D,IAAI,KAAK,CAAC,OAAO,KAAK,IAAI;YAAE,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;QACzD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,CAAC,UAAU;QACd,MAAM,GAAG,GAAmC,EAAE,CAAC;QAC/C,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;YACpD,MAAM,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;YACjC,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,UAAU,CAAC,OAAO,CAAC,CAAC;YAC9D,GAAG,CAAC,OAAO,CAAC,GAAG;gBACb,GAAG,KAAK,CAAC,MAAM,EAAE;gBACjB,cAAc,EAAE,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC;gBAC9C,iBAAiB,EAAE,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,IAAI,CAAC;gBACxD,iBAAiB,EAAE,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,IAAI,CAAC;aACzD,CAAC;QACJ,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,qEAAqE;IACrE,oBAAoB;IACpB,qEAAqE;IAE7D,KAAK,CAAC,YAAY,CAAC,OAAe;QACxC,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;QACvC,2EAA2E;QAC3E,0EAA0E;QAC1E,2EAA2E;QAC3E,qEAAqE;QACrE,IAAI,IAAI,KAAK,SAAS,IAAI,YAAY,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC,KAAK,GAAG,IAAI,EAAE,CAAC;YACpE,OAAO;QACT,CAAC;QAED,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;QAC7C,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,OAAO;QACT,CAAC;QAED,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,GAAG,YAAY,EAAE,CAAC;QAC3C,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,WAAW,CAC5B,UAAU,CAAC,UAAU,EAAE,EACvB,0BAA0B,CAC3B,CAAC;YACF,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;gBAC9B,IAAI,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;gBACjC,IAAI,CAAC,KAAK,EAAE,CAAC;oBACX,KAAK,GAAG,IAAI,UAAU,CAAC,OAAO,CAAC,CAAC;oBAChC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,KAAK,CAAC;gBAC/B,CAAC;gBACD,KAAK,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC;YAClC,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,mDAAmD;QACrD,CAAC;IACH,CAAC;IAED,qEAAqE;IACrE,0BAA0B;IAC1B,qEAAqE;IAE7D,eAAe;QAKrB,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YAChC,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;QACjD,CAAC;QACD,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;YAClD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAG1B,CAAC;YACF,MAAM,KAAK,GAA2B,EAAE,CAAC;YACzC,MAAM,OAAO,GAA2B,EAAE,CAAC;YAC3C,MAAM,OAAO,GAA2B,EAAE,CAAC;YAC3C,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC1C,IAAI,CAAC,CAAC;oBAAE,SAAS;gBACjB,IAAI,OAAO,CAAC,CAAC,WAAW,KAAK,QAAQ;oBAAE,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,WAAW,CAAC;gBAChE,IAAI,OAAO,CAAC,CAAC,aAAa,KAAK,QAAQ;oBAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,aAAa,CAAC;gBACtE,IAAI,OAAO,CAAC,CAAC,aAAa,KAAK,QAAQ;oBAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,aAAa,CAAC;YACxE,CAAC;YACD,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;QACrC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;QACjD,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;;OAaG;IACK,iBAAiB;QACvB,IAAI,QAAQ,GAA4C,EAAE,CAAC;QAC3D,IAAI,CAAC;YACH,IAAI,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC/B,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;gBAClD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAGrB,CAAC;gBACT,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;oBACzC,QAAQ,GAAG,MAAM,CAAC;gBACpB,CAAC;YACH,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,QAAQ,GAAG,EAAE,CAAC;QAChB,CAAC;QACD,KAAK,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;YAChE,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;YACvC,MAAM,CAAC,aAAa,CAAC,GAAG,KAAK,CAAC;YAC9B,QAAQ,CAAC,OAAO,CAAC,GAAG,MAAM,CAAC;QAC7B,CAAC;QACD,KAAK,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,kBAAkB,CAAC,EAAE,CAAC;YACvE,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;YACvC,MAAM,CAAC,eAAe,CAAC,GAAG,KAAK,CAAC;YAChC,QAAQ,CAAC,OAAO,CAAC,GAAG,MAAM,CAAC;QAC7B,CAAC;QACD,KAAK,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,kBAAkB,CAAC,EAAE,CAAC;YACvE,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;YACvC,MAAM,CAAC,eAAe,CAAC,GAAG,KAAK,CAAC;YAChC,QAAQ,CAAC,OAAO,CAAC,GAAG,MAAM,CAAC;QAC7B,CAAC;QACD,OAAO,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAC3C,CAAC;IAEO,iBAAiB;QACvB,IAAI,CAAC,cAAc,IAAI,CAAC,CAAC;QACzB,OAAO,GAAG,IAAI,CAAC,SAAS,IAAI,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,cAAc,MAAM,CAAC;IACrF,CAAC;IAEO,2BAA2B,CAAC,OAAe;QACjD,MAAM,GAAG,GAAG,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACrC,IAAI,CAAC;YACH,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC7D,aAAa,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;YAC5B,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QAClC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC;gBACH,UAAU,CAAC,GAAG,CAAC,CAAC;YAClB,CAAC;YAAC,MAAM,CAAC;gBACP,2BAA2B;YAC7B,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,mBAAmB;QACjB,IAAI,CAAC;YACH,IAAI,CAAC,2BAA2B,CAAC,IAAI,CAAC,iBAAiB,EAAE,CAAC,CAAC;QAC7D,CAAC;QAAC,MAAM,CAAC;YACP,UAAU;QACZ,CAAC;IACH,CAAC;CACF;AAED,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E,SAAS,WAAW,CAAI,OAAmB,EAAE,SAAiB;IAC5D,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,MAAM,CAAC,IAAI,KAAK,CAAC,iBAAiB,SAAS,IAAI,CAAC,CAAC,CAAC;QACpD,CAAC,EAAE,SAAS,CAAC,CAAC;QACd,OAAO,CAAC,IAAI,CACV,CAAC,KAAK,EAAE,EAAE;YACR,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,OAAO,CAAC,KAAK,CAAC,CAAC;QACjB,CAAC,EACD,CAAC,GAAG,EAAE,EAAE;YACN,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,MAAM,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAC9D,CAAC,CACF,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/route-policy.d.ts

@@ -0,0 +1,24 @@
+import type { Dispatcher } from "./dispatchers/base.js";
+import type { RouteBilling, RoutePolicy, RouteSkip, SafetyProfile, ServiceConfig } from "./types.js";
+export interface RoutePolicyResult {
+    blocked: boolean;
+    skipped?: RouteSkip;
+}
+export declare function evaluateRoutePolicy(route: string, svc: ServiceConfig, opts?: {
+    dispatcher?: Dispatcher;
+    circuitBroken?: boolean;
+    requestedSafetyProfile?: SafetyProfile;
+    routePolicy?: RoutePolicy;
+}): RoutePolicyResult;
+/**
+ * Scoring penalty applied to nudge route selection toward cheaper options
+ * when scores are otherwise close. Local routes (free, on this machine) pay
+ * nothing. Included-plan/free-quota-but-remote routes pay a small penalty
+ * (prefer local when close). Routes that can incur real per-use cost
+ * (metered API, unknown billing) must pay MORE than that, not less — they
+ * were previously falling through to the same 0 penalty as local routes,
+ * which meant the router could prefer spending real money over using a
+ * subscription you're already paying for or a free local model.
+ */
+export declare function nonLocalIncludedRoutePenalty(billing: RouteBilling): number;
+//# sourceMappingURL=route-policy.d.ts.map

package/dist/route-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-policy.d.ts","sourceRoot":"","sources":["../src/route-policy.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAExD,OAAO,KAAK,EACV,YAAY,EACZ,WAAW,EACX,SAAS,EACT,aAAa,EACb,aAAa,EACd,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,SAAS,CAAC;CACrB;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,aAAa,EAClB,IAAI,GAAE;IACJ,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,sBAAsB,CAAC,EAAE,aAAa,CAAC;IACvC,WAAW,CAAC,EAAE,WAAW,CAAC;CACtB,GACL,iBAAiB,CAqDnB;AAED;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAI1E"}

package/dist/route-policy.js

@@ -0,0 +1,92 @@
+import { billingIsBlocked, billingIsUnknown, buildRouteBilling } from "./billing.js";
+import { effectiveSafetyProfile, safetyProfileCompatible } from "./safety.js";
+export function evaluateRoutePolicy(route, svc, opts = {}) {
+    if (!svc.enabled) {
+        return skip(route, "disabled", "route is disabled");
+    }
+    if (!opts.dispatcher) {
+        return skip(route, "no_dispatcher", "no dispatcher is registered for this route");
+    }
+    if (!opts.dispatcher.isAvailable()) {
+        return skip(route, "unavailable", "required command or endpoint is unavailable");
+    }
+    if (opts.circuitBroken) {
+        return skip(route, "circuit_broken", "route circuit breaker is open");
+    }
+    const billing = buildRouteBilling(svc);
+    const routePolicy = evaluateOperationalRoutePolicy(route, billing, opts.routePolicy);
+    if (routePolicy.blocked)
+        return routePolicy;
+    if (billingIsUnknown(billing) &&
+        !isIncludedOrLocalRoute(billing) &&
+        !billing.allowPaidUsage) {
+        return skip(route, "unknown_billing", "billing source is unknown and paid usage is not allowed — this is a config-level " +
+            `block, not an availability problem; the operator must add \`allow_paid_usage: true\` ` +
+            `to '${route}' in config.yaml to enable it`);
+    }
+    if (billingIsBlocked(billing)) {
+        return skip(route, "paid_blocked", "route can incur paid usage and paid usage is not allowed — this is a config-level " +
+            `block, not an availability problem; the operator must add \`allow_paid_usage: true\` ` +
+            `to '${route}' in config.yaml (or run \`harness-dispatch configure --allow-paid\`) to enable it`);
+    }
+    if (!safetyProfileCompatible(svc, opts.requestedSafetyProfile)) {
+        return skip(route, "safety_incompatible", `effective safety ${effectiveSafetyProfile(svc, opts.requestedSafetyProfile)} exceeds requested safety`);
+    }
+    return { blocked: false };
+}
+/**
+ * Scoring penalty applied to nudge route selection toward cheaper options
+ * when scores are otherwise close. Local routes (free, on this machine) pay
+ * nothing. Included-plan/free-quota-but-remote routes pay a small penalty
+ * (prefer local when close). Routes that can incur real per-use cost
+ * (metered API, unknown billing) must pay MORE than that, not less — they
+ * were previously falling through to the same 0 penalty as local routes,
+ * which meant the router could prefer spending real money over using a
+ * subscription you're already paying for or a free local model.
+ */
+export function nonLocalIncludedRoutePenalty(billing) {
+    if (isLocalRoute(billing))
+        return 0;
+    if (isIncludedOrLocalRoute(billing))
+        return 0.2;
+    return 0.4;
+}
+function evaluateOperationalRoutePolicy(route, billing, routePolicy) {
+    if (routePolicy === "blocked") {
+        return skip(route, "route_policy", "excluded by the CALLER's own hints.routePolicy='blocked' on this request (dry-run) " +
+            "— not a config restriction or a router safety judgment about this route or its " +
+            "content; drop or change that hint to allow it");
+    }
+    if (routePolicy === "local_only" && !isLocalRoute(billing)) {
+        return skip(route, "route_policy", "excluded by the CALLER's own hints.routePolicy='local_only' on this request " +
+            "— not a config restriction or a router safety judgment about this route or its " +
+            "content; drop or change that hint to allow non-local routes");
+    }
+    if (routePolicy === "approval_required" && !isLocalRoute(billing)) {
+        return skip(route, "approval_required", "excluded by the CALLER's own hints.routePolicy='approval_required' on this request " +
+            "— not a config restriction or a router safety judgment about this route or its " +
+            "content; drop or change that hint to allow non-local routes");
+    }
+    return { blocked: false };
+}
+function isLocalRoute(billing) {
+    return (billing.kind === "local_compute" ||
+        billing.provider === "local" ||
+        billing.surface === "local_endpoint" ||
+        billing.authSource === "local_network");
+}
+function isIncludedOrLocalRoute(billing) {
+    return (isLocalRoute(billing) ||
+        billing.kind === "free_quota" ||
+        billing.kind === "included_plan_usage" ||
+        billing.kind === "included_plan_then_flexible_credits" ||
+        billing.kind === "included_credit_then_optional_overage" ||
+        billing.kind === "included_usage_then_on_demand");
+}
+function skip(route, code, message) {
+    return {
+        blocked: true,
+        skipped: { route, code, message },
+    };
+}
+//# sourceMappingURL=route-policy.js.map

package/dist/route-policy.js.map

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

package/dist/router.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Load-balancing router for harness-dispatch.
+ *
+ * Routing strategy
+ * ----------------
+ * Services are grouped by tier (lower number = higher quality). Selection
+ * prefers the best-scoring candidate in the lowest eligible tier:
+ *
+ *   Tier 1 (frontier)  ->  Tier 2 (strong)  ->  Tier 3 (fast/local)
+ *
+ * Services that are circuit-broken, policy-blocked, unavailable, or already
+ * tried this request are excluded from candidacy. On a failed dispatch
+ * (including rate limits) the router excludes that service and retries with
+ * the next-best candidate, up to `maxFallbacks` extra attempts per request
+ * (default 2, i.e. 3 attempts total — pass maxFallbacks: 0 to let the caller
+ * own retries). A request can therefore fail with untried routes remaining
+ * when the attempt cap is hit before candidates run out.
+ *
+ * Quality scoring
+ * ---------------
+ * Within a tier, services are ranked by a composite score:
+ *
+ *   final_score = quality_score * cli_capability * capability[task_type]
+ *                 * quota_score * weight
+ *
+ * Adjustments applied during selection (reflected in the reported
+ * finalScore for picked/fallback routes, but not for forced/explicit ones):
+ *  - Cost-based penalty under the "standard" route policy
+ *    (nonLocalIncludedRoutePenalty): 0 for local routes, -0.2 for non-local
+ *    included-plan/free-quota routes, -0.4 for routes that can incur real
+ *    per-use cost (metered API, unknown billing) — cheapest/lowest-risk
+ *    wins ties, in that order.
+ *  - +0.5 when hints.model matches the service name or one of its models.
+ *  - Under prefer_large_context, +0.3 for routes declaring >=2M
+ *    max_input_tokens and +0.15 for >=1M — declared context size, not
+ *    harness name.
+ *  - +0.3 when task_type="local" and the service is an openai_compatible
+ *    endpoint on localhost / 127.0.0.1.
+ *
+ * Tier auto-derivation
+ * --------------------
+ * If a service has `leaderboardModel` set in config, its tier is
+ * auto-derived from the Arena ELO score via LeaderboardCache.autoTier().
+ * Explicit `tier` in config is the fallback when ELO is unavailable.
+ *
+ * R3: adds `stream()` / `streamTo()` that emit `DispatcherEvent`s with an
+ * attached `RoutingDecision`. The buffered `route` / `routeTo` methods are
+ * reimplemented on top of the streaming primitives.
+ */
+import type { DispatchResult, DispatcherEvent, RouterConfig, RoutingDecision, RouteHints, RouteSkip, SafetyProfile, ServiceConfig, TaskType } from "./types.js";
+import { CircuitBreaker } from "./circuit-breaker.js";
+import { BreakerStore } from "./breaker-store.js";
+import { QuotaCache } from "./quota.js";
+import { LeaderboardCache } from "./leaderboard.js";
+import type { Dispatcher } from "./dispatchers/base.js";
+import { drainDispatcherStream } from "./dispatchers/base.js";
+/**
+ * Options for explicit-service dispatch (routeTo / streamTo).
+ *
+ * `model` is an instruction, not a routing hint: the caller already chose
+ * the service, so the value is passed to the harness as a model override
+ * verbatim (an invalid name fails loudly downstream instead of being
+ * silently dropped). `taskType` feeds capability scoring metadata and
+ * per-task model escalation (escalateOn/escalateModel).
+ */
+export interface ExplicitDispatchOpts {
+    safetyProfile?: SafetyProfile;
+    workspacePolicy?: ServiceConfig["workspacePolicy"];
+    routePolicy?: import("./types.js").RoutePolicy;
+    model?: string;
+    taskType?: TaskType;
+    timeoutMs?: number;
+    /**
+     * Fallback timeout when neither `timeoutMs` (explicit per-call override)
+     * nor the service's own `timeoutMs` config is set — below both in
+     * precedence, so it never silently overrides a real value. Used by `job`
+     * to give background dispatches a generous ceiling without a caller
+     * having to know to ask for one; `code` (which blocks the MCP call) does
+     * not set this and keeps the dispatcher's own short default.
+     */
+    defaultTimeoutMs?: number;
+}
+/**
+ * Router streaming events wrap the dispatcher event with the active routing
+ * decision. The decision is emitted on the first event of each dispatch
+ * attempt (so consumers can show "routing to claude_code" before the first
+ * token arrives) and is also attached to every subsequent event in case the
+ * consumer missed the first.
+ */
+export interface RouterStreamEvent {
+    event: DispatcherEvent;
+    decision: RoutingDecision | null;
+}
+export declare class Router {
+    #private;
+    private readonly config;
+    private readonly quota;
+    private readonly dispatchers;
+    private readonly leaderboard;
+    private readonly breakers;
+    private lastSkippedRoutes;
+    private readonly breakerStore;
+    constructor(config: RouterConfig, quota: QuotaCache, dispatchers: Record<string, Dispatcher>, leaderboard: LeaderboardCache, breakerStore?: BreakerStore);
+    private persistBreaker;
+    getBreaker(service: string): CircuitBreaker | undefined;
+    skippedRoutes(): RouteSkip[];
+    pickService(opts?: {
+        hints?: RouteHints;
+        prompt?: string;
+        files?: string[];
+        exclude?: Set<string>;
+    }): Promise<RoutingDecision | null>;
+    /**
+     * Stream events from the chosen dispatcher, with the same fallback logic
+     * as `route()`. When a dispatch fails (non-rate-limit), the router picks
+     * another service and yields that service's events — so the caller sees
+     * events from potentially multiple services during fallback.
+     *
+     * The last `completion` or `error` event always reflects the final
+     * outcome (success-with-fallback or all-attempts-failed).
+     */
+    stream(prompt: string, files: string[], workingDir: string, opts?: {
+        hints?: RouteHints;
+        maxFallbacks?: number;
+        defaultTimeoutMs?: number;
+    }): AsyncIterable<RouterStreamEvent>;
+    /**
+     * Stream from a specific service, bypassing tier selection. Same semantics
+     * as `routeTo()` but yields events in real time.
+     */
+    streamTo(service: string, prompt: string, files: string[], workingDir: string, opts?: ExplicitDispatchOpts): AsyncIterable<RouterStreamEvent>;
+    /**
+     * Route a task, with automatic fallback on transient failures.
+     *
+     * R3: reimplemented on top of `stream()`. The per-attempt result is
+     * captured from the `completion` event and drives the fallback loop.
+     *
+     * The old route() also had a quirk: when pickService returned null with
+     * no prior attempts, it yielded an error DispatchResult. On a later
+     * fallback round that returned null it returned the last attempt's
+     * result+decision. The streaming-based reimplementation below preserves
+     * the same externally observable behaviour for existing tests.
+     */
+    route(prompt: string, files: string[], workingDir: string, opts?: {
+        hints?: RouteHints;
+        maxFallbacks?: number;
+    }): Promise<{
+        result: DispatchResult;
+        decision: RoutingDecision | null;
+    }>;
+    /**
+     * Dispatch to a specific service, bypassing tier selection.
+     */
+    routeTo(service: string, prompt: string, files: string[], workingDir: string, opts?: ExplicitDispatchOpts): Promise<{
+        result: DispatchResult;
+        decision: RoutingDecision | null;
+    }>;
+    private handleResult;
+    circuitBreakerStatus(): Record<string, ReturnType<CircuitBreaker["status"]>>;
+}
+export { drainDispatcherStream };
+//# sourceMappingURL=router.d.ts.map

package/dist/router.d.ts.map

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