harness-dispatch 0.4.0

package/dist/circuit-breaker.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Per-service circuit breaker with dynamic cooldown from provider responses.
+ *
+ * Ported from the Python `coding_agent.router.CircuitBreaker` class.
+ * Uses `performance.now()` for monotonic seconds (equivalent to Python's
+ * `time.monotonic()`), independent of wall-clock adjustments.
+ */
+export declare const CIRCUIT_BREAKER_THRESHOLD = 5;
+export declare const CIRCUIT_BREAKER_DEFAULT_COOLDOWN_SEC = 300;
+export interface CircuitBreakerStatus {
+    tripped: boolean;
+    failures: number;
+    cooldownRemainingSec?: number;
+}
+export interface CircuitBreakerSnapshot {
+    failures: number;
+    /** Wall-clock epoch ms when the current cooldown ends; null when not tripped. */
+    blockedUntilMs: number | null;
+}
+export declare class CircuitBreaker {
+    private failures;
+    private trippedAt;
+    private cooldown;
+    get isTripped(): boolean;
+    recordFailure(retryAfterSec?: number): void;
+    recordSuccess(): void;
+    /** Immediately trip — use on 429 or explicit rate-limit response. */
+    trip(retryAfterSec?: number): void;
+    cooldownRemaining(): number;
+    status(): CircuitBreakerStatus;
+    /**
+     * Wall-clock snapshot for cross-process persistence. `trippedAt`/`cooldown`
+     * are deliberately monotonic (performance.now(), immune to clock
+     * adjustments mid-run) so they can't be written to disk as-is; this
+     * converts the live state to an absolute deadline a future process (after
+     * a restart) can compare against its own Date.now().
+     */
+    snapshot(): CircuitBreakerSnapshot;
+    /**
+     * Hydrate from a snapshot persisted by a previous process. A
+     * `blockedUntilMs` already in the past is treated as expired, matching
+     * this class's own auto-reset-on-expiry semantics.
+     */
+    restore(snapshot: CircuitBreakerSnapshot): void;
+    private reset;
+}
+//# sourceMappingURL=circuit-breaker.d.ts.map

package/dist/circuit-breaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.d.ts","sourceRoot":"","sources":["../src/circuit-breaker.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAC3C,eAAO,MAAM,oCAAoC,MAAM,CAAC;AAMxD,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,QAAQ,CAAgD;IAEhE,IAAI,SAAS,IAAI,OAAO,CASvB;IAED,aAAa,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI;IAW3C,aAAa,IAAI,IAAI;IAIrB,qEAAqE;IACrE,IAAI,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI;IAQlC,iBAAiB,IAAI,MAAM;IAO3B,MAAM,IAAI,oBAAoB;IAW9B;;;;;;OAMG;IACH,QAAQ,IAAI,sBAAsB;IAOlC;;;;OAIG;IACH,OAAO,CAAC,QAAQ,EAAE,sBAAsB,GAAG,IAAI;IAe/C,OAAO,CAAC,KAAK;CAKd"}

package/dist/circuit-breaker.js

@@ -0,0 +1,102 @@
+/**
+ * Per-service circuit breaker with dynamic cooldown from provider responses.
+ *
+ * Ported from the Python `coding_agent.router.CircuitBreaker` class.
+ * Uses `performance.now()` for monotonic seconds (equivalent to Python's
+ * `time.monotonic()`), independent of wall-clock adjustments.
+ */
+export const CIRCUIT_BREAKER_THRESHOLD = 5;
+export const CIRCUIT_BREAKER_DEFAULT_COOLDOWN_SEC = 300;
+function monotonicSec() {
+    return performance.now() / 1000;
+}
+export class CircuitBreaker {
+    failures = 0;
+    trippedAt = null;
+    cooldown = CIRCUIT_BREAKER_DEFAULT_COOLDOWN_SEC;
+    get isTripped() {
+        if (this.trippedAt === null) {
+            return false;
+        }
+        if (monotonicSec() - this.trippedAt >= this.cooldown) {
+            this.reset();
+            return false;
+        }
+        return true;
+    }
+    recordFailure(retryAfterSec) {
+        this.failures += 1;
+        if (this.failures >= CIRCUIT_BREAKER_THRESHOLD) {
+            this.trippedAt = monotonicSec();
+            this.cooldown =
+                retryAfterSec && retryAfterSec > 0
+                    ? retryAfterSec
+                    : CIRCUIT_BREAKER_DEFAULT_COOLDOWN_SEC;
+        }
+    }
+    recordSuccess() {
+        this.reset();
+    }
+    /** Immediately trip — use on 429 or explicit rate-limit response. */
+    trip(retryAfterSec) {
+        this.trippedAt = monotonicSec();
+        this.cooldown =
+            retryAfterSec && retryAfterSec > 0
+                ? retryAfterSec
+                : CIRCUIT_BREAKER_DEFAULT_COOLDOWN_SEC;
+    }
+    cooldownRemaining() {
+        if (!this.isTripped || this.trippedAt === null) {
+            return 0;
+        }
+        return Math.max(0, this.cooldown - (monotonicSec() - this.trippedAt));
+    }
+    status() {
+        if (!this.isTripped) {
+            return { tripped: false, failures: this.failures };
+        }
+        return {
+            tripped: true,
+            failures: this.failures,
+            cooldownRemainingSec: Math.round(this.cooldownRemaining() * 10) / 10,
+        };
+    }
+    /**
+     * Wall-clock snapshot for cross-process persistence. `trippedAt`/`cooldown`
+     * are deliberately monotonic (performance.now(), immune to clock
+     * adjustments mid-run) so they can't be written to disk as-is; this
+     * converts the live state to an absolute deadline a future process (after
+     * a restart) can compare against its own Date.now().
+     */
+    snapshot() {
+        if (!this.isTripped) {
+            return { failures: this.failures, blockedUntilMs: null };
+        }
+        return { failures: this.failures, blockedUntilMs: Date.now() + this.cooldownRemaining() * 1000 };
+    }
+    /**
+     * Hydrate from a snapshot persisted by a previous process. A
+     * `blockedUntilMs` already in the past is treated as expired, matching
+     * this class's own auto-reset-on-expiry semantics.
+     */
+    restore(snapshot) {
+        this.failures = snapshot.failures;
+        if (snapshot.blockedUntilMs === null) {
+            this.trippedAt = null;
+            return;
+        }
+        const remainingSec = (snapshot.blockedUntilMs - Date.now()) / 1000;
+        if (remainingSec <= 0) {
+            this.trippedAt = null;
+            return;
+        }
+        this.cooldown = remainingSec;
+        this.trippedAt = monotonicSec();
+    }
+    reset() {
+        this.failures = 0;
+        this.trippedAt = null;
+        this.cooldown = CIRCUIT_BREAKER_DEFAULT_COOLDOWN_SEC;
+    }
+}
+//# sourceMappingURL=circuit-breaker.js.map

package/dist/circuit-breaker.js.map

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

package/dist/config.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Configuration loading for harness-dispatch.
+ *
+ * Two entry points:
+ *   loadConfig(path?)   — if no path, auto-detects installed CLIs on PATH.
+ *                         If path points to a legacy YAML with a `services:`
+ *                         key, returns it verbatim. Otherwise merges minimal
+ *                         overrides onto auto-detected defaults.
+ *   watchConfig(path)   — poll the file's mtime once a second and reload on
+ *                         change. Returns {stop} to cancel the poller.
+ *
+ * All string values are scanned for ${ENV_VAR} references and replaced with
+ * the corresponding environment variable.
+ */
+import type { CliProtocolConfig, RouterConfig } from "./types.js";
+/** Named, selectable protocols — every harness in CLI_DEFAULTS that defines one, keyed by its harness name (see protocolFrom()'s string/`extends:` handling). */
+export declare const PROTOCOL_PRESETS: Record<string, CliProtocolConfig>;
+/** Injection seam for tests. Set via loadConfig({ whichFn }) if needed. */
+export type WhichFn = (cmd: string) => Promise<string | null>;
+export interface LoadConfigOptions {
+    /** Override `which` for tests — return null when a CLI is "not found". */
+    whichFn?: WhichFn;
+}
+/**
+ * Load a RouterConfig.
+ *
+ * If `path` is omitted (or the file doesn't exist), auto-detect CLIs on PATH
+ * and use built-in defaults. If the file has a top-level `services:` key,
+ * parse it in legacy mode. Otherwise auto-detect and merge `overrides`.
+ *
+ * Supports ${ENV_VAR} interpolation for any string value.
+ */
+export declare function loadConfig(path?: string, opts?: LoadConfigOptions): Promise<RouterConfig>;
+export interface ConfigWatcher {
+    stop(): void;
+}
+/**
+ * Poll the config file's mtime once per second. When it changes, reload and
+ * invoke `onChange`. The returned handle's stop() cancels the poller.
+ *
+ * Errors from reload are swallowed so a transient parse error doesn't kill
+ * the watcher — the next successful poll will pick up a repaired file.
+ */
+export declare function watchConfig(path: string, onChange: (c: RouterConfig) => void, opts?: {
+    intervalMs?: number;
+    whichFn?: WhichFn;
+}): ConfigWatcher;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAWH,OAAO,KAAK,EAOV,iBAAiB,EAGjB,YAAY,EAOb,MAAM,YAAY,CAAC;AA+EpB,iKAAiK;AACjK,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAI9D,CAAC;AA4DF,2EAA2E;AAC3E,MAAM,MAAM,OAAO,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;AA09B9D,MAAM,WAAW,iBAAiB;IAChC,0EAA0E;IAC1E,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,wBAAsB,UAAU,CAC9B,IAAI,CAAC,EAAE,MAAM,EACb,IAAI,GAAE,iBAAsB,GAC3B,OAAO,CAAC,YAAY,CAAC,CAwEvB;AAMD,MAAM,WAAW,aAAa;IAC5B,IAAI,IAAI,IAAI,CAAC;CACd;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,CAAC,CAAC,EAAE,YAAY,KAAK,IAAI,EACnC,IAAI,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GACpD,aAAa,CAkCf"}