@sweny-ai/core 0.1.177 → 0.1.178

package/dist/decider.js

@@ -1,22 +1,44 @@
 /**
- * Decision models (#357), shadow mode.
+ * Decision models (#357): a fast typed classifier that decides routes.
  *
  * A System One decision model (Ollama `/v1/systemone`, TypeSafe Jev) answers
- * one typed Choice question over a state in milliseconds. In shadow mode the
- * executor asks it the same route question the agent answers, in parallel,
- * and records whether they agree. The route is ALWAYS the agent's.
+ * one Choice question over a state in milliseconds. For a node that sets
+ * `route_by: decider` and whose conditional out-edges are natural language,
+ * the route ladder is:
  *
- * Privacy: the state goes only to the provider the workflow configured, never
- * to a default or fallback URL. What this module logs is metadata only
- * (labels are edge target node ids, plus numbers and a hash).
+ *   1. `when` expressions: sweny evaluates them, no model call (executor.ts).
+ *   2. The decider: its answer is the route only when the label is one of the
+ *      node's live out-edges, confidence is at least `min_confidence` and the
+ *      top label leads the runner-up by at least `min_margin`. Then the agent
+ *      is never asked.
+ *   3. The agent's route evaluation, exactly as without a decider.
+ *
+ * Any decider problem (timeout, HTTP error, malformed answer, unknown label,
+ * low confidence or margin, no routable state, open breaker, spent cap) falls
+ * through to rung 3.
+ *
+ * Trust boundary: the endpoint, model and key come only from operator config
+ * (`.sweny.yml` or SWENY_DECIDER_* env), never from the workflow, and the
+ * URL must not point at a private, link-local or metadata address unless the
+ * operator allows private addresses. The state sent is an explicit projection
+ * of declared typed fields (see executor.ts), redacted and fenced. What this
+ * module logs is metadata only (edge target ids, numbers and a hash).
  */
 import crypto from "node:crypto";
-/** Accept a decider answer only at or above this confidence. */
-export const DECIDER_MIN_CONFIDENCE = 0.85;
-/** ... and only when the top label leads the runner-up by at least this much. */
-export const DECIDER_MIN_MARGIN = 0.2;
-/** Per-call timeout when the provider does not set one. */
+import dns from "node:dns";
+import http from "node:http";
+import https from "node:https";
+import { DECIDER_CONFIDENCE_FLOOR, DECIDER_MARGIN_FLOOR, DECIDER_MIN_CONFIDENCE, DECIDER_MIN_MARGIN } from "./types.js";
+/** Per-call timeout. */
 export const DECIDER_DEFAULT_TIMEOUT_MS = 2000;
+/** Consecutive failed calls that open the breaker for the rest of the run. */
+export const DECIDER_BREAKER_FAILURES = 3;
+/** Decider calls one logical run (resumes included) may make. */
+export const DECIDER_DEFAULT_MAX_CALLS = 200;
+/** Probabilities must sum to 1 within this. */
+export const DECIDER_SUM_TOLERANCE = 0.01;
+/** Float slack for the threshold comparisons (0.6 - 0.4 is 0.19999999999999996). */
+const EPS = 1e-9;
 export class DecideError extends Error {
     code;
     constructor(code, message) {
@@ -25,13 +47,175 @@ export class DecideError extends Error {
         this.name = "DecideError";
     }
 }
+// ─── URL policy ─────────────────────────────────────────────────
+function ipv4(host) {
+    const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+    if (!m)
+        return null;
+    const parts = m.slice(1).map(Number);
+    return parts.every((p) => p <= 255) ? parts : null;
+}
+function ipv6(host) {
+    if (!host.includes(":"))
+        return null;
+    let h = host;
+    // Trailing dotted IPv4 (::ffff:1.2.3.4).
+    const tail = /:(\d+\.\d+\.\d+\.\d+)$/.exec(h);
+    if (tail) {
+        const v4 = ipv4(tail[1]);
+        if (!v4)
+            return null;
+        h = h.slice(0, -tail[1].length) + ((v4[0] << 8) | v4[1]).toString(16) + ":" + ((v4[2] << 8) | v4[3]).toString(16);
+    }
+    const halves = h.split("::");
+    if (halves.length > 2)
+        return null;
+    const parse = (s) => s === "" ? [] : s.split(":").map((g) => (/^[0-9a-f]{1,4}$/i.test(g) ? parseInt(g, 16) : NaN));
+    const head = parse(halves[0]);
+    const rest = halves.length === 2 ? parse(halves[1]) : [];
+    if ([...head, ...rest].some((n) => Number.isNaN(n)))
+        return null;
+    const fill = halves.length === 2 ? 8 - head.length - rest.length : 0;
+    if (fill < 0 || (halves.length === 1 && head.length !== 8))
+        return null;
+    return [...head, ...Array(fill).fill(0), ...rest];
+}
+function classifyV4([a, b]) {
+    if (a === 169 && b === 254)
+        return "forbidden"; // link-local, cloud metadata (169.254.169.254)
+    if (a === 0)
+        return "forbidden";
+    if (a === 100 && b === 100)
+        return "forbidden"; // 100.100.100.200 metadata
+    if (a === 127)
+        return "loopback";
+    if (a === 10)
+        return "private";
+    if (a === 172 && b >= 16 && b <= 31)
+        return "private";
+    if (a === 192 && b === 168)
+        return "private";
+    if (a === 100 && b >= 64 && b <= 127)
+        return "private"; // CGNAT
+    if (a >= 224)
+        return "forbidden"; // multicast, reserved
+    return "public";
+}
+/** Class of an IP literal, or null when `host` is not one. */
+function classifyIp(host) {
+    const v4 = ipv4(host);
+    if (v4)
+        return classifyV4(v4);
+    const v6 = ipv6(host);
+    if (v6) {
+        if (v6.every((g) => g === 0))
+            return "forbidden"; // ::
+        if (v6.slice(0, 7).every((g) => g === 0) && v6[7] === 1)
+            return "loopback"; // ::1
+        if (v6.slice(0, 5).every((g) => g === 0) && v6[5] === 0xffff) {
+            return classifyV4([v6[6] >> 8, v6[6] & 0xff, v6[7] >> 8, v6[7] & 0xff]); // IPv4-mapped
+        }
+        if ((v6[0] & 0xffc0) === 0xfe80)
+            return "forbidden"; // link-local
+        if (v6[0] === 0xfd00 && v6[1] === 0x0ec2)
+            return "forbidden"; // AWS metadata fd00:ec2::254
+        if ((v6[0] & 0xfe00) === 0xfc00)
+            return "private"; // unique local
+        if ((v6[0] & 0xff00) === 0xff00)
+            return "forbidden"; // multicast
+        return "public";
+    }
+    return null;
+}
+const REPO_URL_NOT_LOOPBACK = "a decider url from repo content (.sweny.yml or a workspace .env) must be loopback; set SWENY_DECIDER_URL in the environment for a remote server";
+const bare = (hostname) => hostname
+    .replace(/^\[|\]$/g, "")
+    .toLowerCase()
+    .replace(/\.$/, "");
+/** Why connecting to this resolved address is refused, or null. */
+export function addressProblem(address, policy) {
+    const cls = classifyIp(bare(address)) ?? "forbidden"; // not an IP: never connect to it
+    if (cls === "forbidden")
+        return "decider address is link-local, metadata or reserved";
+    if (policy.loopbackOnly)
+        return cls === "loopback" ? null : REPO_URL_NOT_LOOPBACK;
+    if ((cls === "loopback" || cls === "private") && !policy.allowPrivate) {
+        return "decider address is loopback or private; set SWENY_DECIDER_ALLOW_PRIVATE=true in the environment to use it";
+    }
+    return null;
+}
+/**
+ * Static checks on the operator's decider URL, or null when it may be tried:
+ * http(s) only, no credentials in it, no metadata host name, and an IP
+ * literal must pass {@link addressProblem}. A host name is checked again on
+ * every connection, against the addresses it resolves to.
+ */
+export function deciderUrlProblem(raw, policy = {}) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return "decider url is not a valid URL";
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+        return "decider url must be http or https";
+    if (url.username || url.password)
+        return "decider url must not carry credentials (use SWENY_DECIDER_API_KEY)";
+    const host = bare(url.hostname);
+    if (host === "metadata" || host === "metadata.google.internal" || host === "instance-data") {
+        return "decider url points at a cloud metadata host";
+    }
+    if (classifyIp(host))
+        return addressProblem(host, policy);
+    return null;
+}
+/**
+ * A `lookup` for `http.request` that resolves every address, refuses the
+ * connection when any of them breaks the policy, and hands the socket the
+ * validated address itself. The socket connects to what was checked, so a
+ * second resolution cannot rebind the name to another address.
+ */
+export function guardedLookup(policy, base = dns.lookup) {
+    return (hostname, options, callback) => {
+        base(hostname, { ...(typeof options === "object" ? options : {}), all: true }, (err, addresses) => {
+            if (err)
+                return callback(err, "");
+            const list = (Array.isArray(addresses) ? addresses : [{ address: addresses, family: 4 }]);
+            if (list.length === 0)
+                return callback(Object.assign(new Error("no address"), { code: "ENOTFOUND" }), "");
+            for (const a of list) {
+                const why = addressProblem(a.address, policy);
+                if (why)
+                    return callback(Object.assign(new Error(why), { code: "EDECIDERBLOCKED" }), "");
+            }
+            if (typeof options === "object" && options.all)
+                return callback(null, list);
+            return callback(null, list[0].address, list[0].family);
+        });
+    };
+}
+/** Largest response body read. A decision is a few hundred bytes. */
+const MAX_RESPONSE_BYTES = 1_000_000;
+function statusCode(s) {
+    if (s === 401 || s === 403)
+        return "unauthorized";
+    if (s === 400 || s === 422)
+        return "invalid_request";
+    if (s === 429)
+        return "rate_limited";
+    if (s === 529 || s === 503)
+        return "overloaded";
+    return "http_error"; // includes 3xx: redirects are never followed
+}
 const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 const isProb = (v) => typeof v === "number" && Number.isFinite(v) && v >= 0 && v <= 1;
+const own = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
 /**
  * `POST {baseUrl}/v1/systemone`. Ollama (local) and TypeSafe Jev (hosted)
  * share this wire shape; only base URL, key and model differ. Response
  * validation is strict: any deviation is a `malformed` or `unknown_label`
- * error, never a guess.
+ * error, never a guess. Error messages carry no URL and no key.
  */
 export function systemOneProvider(opts) {
     const url = `${opts.baseUrl.replace(/\/+$/, "")}/v1/systemone`;
@@ -44,73 +228,105 @@ export function systemOneProvider(opts) {
             for (const [name, ask] of Object.entries(req.asks)) {
                 questions[name] = { type: ask.kind, instructions: ask.instructions, criteria: ask.criteria };
             }
-            const ctl = new AbortController();
-            let timedOut = false;
-            const timer = setTimeout(() => {
-                timedOut = true;
-                ctl.abort();
-            }, timeoutMs);
-            const onAbort = () => ctl.abort();
-            if (req.signal?.aborted)
-                ctl.abort();
-            req.signal?.addEventListener("abort", onAbort, { once: true });
-            try {
-                let res;
-                try {
-                    res = await fetch(url, {
-                        method: "POST",
-                        headers: {
-                            "content-type": "application/json",
-                            ...(opts.apiKey ? { authorization: `Bearer ${opts.apiKey}` } : {}),
-                        },
-                        body: JSON.stringify({ model: opts.model, state: req.state, questions }),
-                        signal: ctl.signal,
-                    });
-                }
-                catch (err) {
-                    if (timedOut)
-                        throw new DecideError("timeout", `no answer within ${timeoutMs}ms`);
-                    if (ctl.signal.aborted)
-                        throw new DecideError("aborted", "request aborted");
-                    throw new DecideError("network", err instanceof Error ? err.name : "fetch failed");
-                }
-                if (!res.ok) {
-                    const s = res.status;
-                    const code = s === 401 || s === 403
-                        ? "unauthorized"
-                        : s === 400 || s === 422
-                            ? "invalid_request"
-                            : s === 429
-                                ? "rate_limited"
-                                : s === 529 || s === 503
-                                    ? "overloaded"
-                                    : "http_error";
-                    throw new DecideError(code, `HTTP ${s}`);
-                }
-                let body;
-                try {
-                    body = await res.json();
-                }
-                catch {
-                    if (timedOut)
-                        throw new DecideError("timeout", `no answer within ${timeoutMs}ms`);
-                    throw new DecideError("malformed", "response is not JSON");
-                }
-                return parseAnswers(body, req.asks);
-            }
-            finally {
-                clearTimeout(timer);
-                req.signal?.removeEventListener("abort", onAbort);
+            const target = new URL(url);
+            const policy = opts.policy ?? {};
+            // An IP literal never goes through `lookup`: check it here.
+            if (classifyIp(bare(target.hostname))) {
+                const why = addressProblem(target.hostname, policy);
+                if (why)
+                    throw new DecideError("blocked_address", why);
             }
+            const payload = JSON.stringify({ model: opts.model, state: req.state, questions });
+            const transport = target.protocol === "https:" ? https : http;
+            const body = await new Promise((resolve, reject) => {
+                let finished = false;
+                let timedOut = false;
+                let aborted = false;
+                let request;
+                const finish = (err, value) => {
+                    if (finished)
+                        return;
+                    finished = true;
+                    clearTimeout(timer);
+                    req.signal?.removeEventListener("abort", onAbort);
+                    if (err) {
+                        request?.destroy();
+                        reject(err);
+                    }
+                    else
+                        resolve(value);
+                };
+                const timer = setTimeout(() => {
+                    timedOut = true;
+                    finish(new DecideError("timeout", `no answer within ${timeoutMs}ms`));
+                }, timeoutMs);
+                const onAbort = () => {
+                    aborted = true;
+                    finish(new DecideError("aborted", "request aborted"));
+                };
+                if (req.signal?.aborted)
+                    return onAbort();
+                req.signal?.addEventListener("abort", onAbort, { once: true });
+                request = transport.request(target, {
+                    method: "POST",
+                    agent: false,
+                    lookup: guardedLookup(policy, opts.lookup),
+                    headers: {
+                        "content-type": "application/json",
+                        "content-length": Buffer.byteLength(payload),
+                        ...(opts.apiKey ? { authorization: `Bearer ${opts.apiKey}` } : {}),
+                    },
+                }, (res) => {
+                    const status = res.statusCode ?? 0;
+                    if (status < 200 || status >= 300) {
+                        res.resume();
+                        return finish(new DecideError(statusCode(status), `HTTP ${status}`));
+                    }
+                    const chunks = [];
+                    let size = 0;
+                    res.on("data", (c) => {
+                        size += c.length;
+                        if (size > MAX_RESPONSE_BYTES)
+                            return finish(new DecideError("malformed", "response too large"));
+                        chunks.push(c);
+                    });
+                    res.on("end", () => {
+                        try {
+                            finish(null, JSON.parse(Buffer.concat(chunks).toString("utf8")));
+                        }
+                        catch {
+                            finish(new DecideError("malformed", "response is not JSON"));
+                        }
+                    });
+                    res.on("error", () => finish(new DecideError("network", "response failed")));
+                });
+                request.on("error", (err) => {
+                    if (timedOut || aborted || finished)
+                        return;
+                    if (err.code === "EDECIDERBLOCKED")
+                        return finish(new DecideError("blocked_address", err.message));
+                    // Never the URL, the address or the key: only that it failed.
+                    finish(new DecideError("network", "request failed"));
+                });
+                request.end(payload);
+            });
+            return parseAnswers(body, req.asks);
         },
     };
 }
-function parseAnswers(body, asks) {
+/**
+ * Strict: `probabilities` holds exactly the criteria keys, each finite in
+ * [0, 1], summing to 1 within {@link DECIDER_SUM_TOLERANCE}; the chosen label
+ * is a criteria key, compared exactly (no normalization), and the unique
+ * maximum. Anything else throws.
+ */
+export function parseAnswers(body, asks) {
     if (!isRecord(body) || !isRecord(body.answers))
         throw new DecideError("malformed", "missing answers object");
-    const out = {};
+    const answers = body.answers;
+    const out = Object.create(null);
     for (const [name, ask] of Object.entries(asks)) {
-        const a = body.answers[name];
+        const a = own(answers, name) ? answers[name] : undefined;
         if (!isRecord(a))
             throw new DecideError("malformed", `no answer for question '${name}'`);
         if (a.type !== undefined && a.type !== ask.kind)
@@ -121,34 +337,54 @@ function parseAnswers(body, asks) {
             throw new DecideError("malformed", "confidence is not a number in 0..1");
         if (!isRecord(a.probabilities))
             throw new DecideError("malformed", "probabilities is not an object");
-        const probabilities = {};
-        for (const [k, v] of Object.entries(a.probabilities)) {
+        const known = new Set(Object.keys(ask.criteria));
+        if (!known.has(a.choice))
+            throw new DecideError("unknown_label", "answer names a label outside the criteria");
+        const got = Object.keys(a.probabilities);
+        if (got.some((k) => !known.has(k)))
+            throw new DecideError("unknown_label", "probabilities name a label outside the criteria");
+        if (got.length !== known.size)
+            throw new DecideError("malformed", "probabilities do not cover every label");
+        const probabilities = Object.create(null);
+        let sum = 0;
+        for (const k of got) {
+            const v = a.probabilities[k];
             if (!isProb(v))
                 throw new DecideError("malformed", "probability is not a number in 0..1");
             probabilities[k] = v;
+            sum += v;
         }
-        const known = Object.keys(ask.criteria);
-        if (!known.includes(a.choice) ||
-            !(a.choice in probabilities) ||
-            Object.keys(probabilities).some((k) => !known.includes(k))) {
-            throw new DecideError("unknown_label", "answer names a label outside the criteria");
+        if (Math.abs(sum - 1) > DECIDER_SUM_TOLERANCE)
+            throw new DecideError("malformed", "probabilities do not sum to 1");
+        const top = probabilities[a.choice];
+        if (got.some((k) => k !== a.choice && probabilities[k] >= top)) {
+            throw new DecideError("malformed", "the chosen label is not the unique most probable one");
         }
         out[name] = { kind: "choice", label: a.choice, probabilities, confidence: a.confidence };
     }
     return out;
 }
-/** All gates must pass: label in the edge set, confidence, then top-two margin. */
-export function gateVerdict(v, edgeSet) {
-    const top = v.probabilities[v.label] ?? 0;
-    const second = Math.max(0, ...Object.entries(v.probabilities)
-        .filter(([k]) => k !== v.label)
-        .map(([, p]) => p));
+/** The workflow's thresholds, else the defaults, never looser than the floors, never above 1. */
+export function resolveThresholds(config) {
+    const pick = (v, dflt, floor) => typeof v === "number" && Number.isFinite(v) ? Math.min(1, Math.max(floor, v)) : dflt;
+    return {
+        minConfidence: pick(config?.min_confidence, DECIDER_MIN_CONFIDENCE, DECIDER_CONFIDENCE_FLOOR),
+        minMargin: pick(config?.min_margin, DECIDER_MIN_MARGIN, DECIDER_MARGIN_FLOOR),
+    };
+}
+/** All gates must pass: label in the edge set, confidence, then top-two margin (each with float slack). */
+export function gateVerdict(v, edgeSet, thresholds = resolveThresholds()) {
+    const top = own(v.probabilities, v.label) ? v.probabilities[v.label] : 0;
+    let second = 0;
+    for (const [k, p] of Object.entries(v.probabilities))
+        if (k !== v.label && p > second)
+            second = p;
     const margin = top - second;
     if (!edgeSet.has(v.label))
         return { accepted: false, reason: "label_outside_edge_set", margin };
-    if (!(v.confidence >= DECIDER_MIN_CONFIDENCE))
+    if (!(v.confidence >= thresholds.minConfidence - EPS))
         return { accepted: false, reason: "low_confidence", margin };
-    if (!(margin >= DECIDER_MIN_MARGIN))
+    if (!(margin >= thresholds.minMargin - EPS))
         return { accepted: false, reason: "low_margin", margin };
     return { accepted: true, margin };
 }
@@ -163,98 +399,182 @@ export function hashDecisionInput(state, criteria) {
     return crypto.createHash("sha256").update(json).digest("hex").slice(0, 16);
 }
 /**
- * Start the decider call. Returns at once; the promise never rejects, so the
- * agent's own evaluation is never delayed or failed by it.
+ * The decider for one logical run: thresholds, a circuit breaker and a call
+ * cap. `decide()` returns the edge target to take, or null to ask the agent.
+ * It never throws.
  */
-export function startShadowDecision(provider, req) {
-    const criteria = {};
-    for (const c of req.choices)
-        if (!(c.id in criteria))
-            criteria[c.id] = c.description;
-    const edgeSet = new Set(Object.keys(criteria));
-    const input_hash = hashDecisionInput(req.state, criteria);
-    const started = Date.now();
-    const base = { model: provider.model, input_hash };
-    const settled = (async () => {
+export class RunDecider {
+    provider;
+    opts;
+    records = [];
+    thresholds;
+    /** Set when the breaker opened or the cap was reached. */
+    offReason;
+    calls;
+    failures;
+    open;
+    capped = false;
+    maxCalls;
+    breakerFailures;
+    timeoutMs;
+    constructor(provider, opts = {}) {
+        this.provider = provider;
+        this.opts = opts;
+        this.thresholds = resolveThresholds(opts.config);
+        this.maxCalls = Math.max(0, Math.floor(opts.maxCalls ?? DECIDER_DEFAULT_MAX_CALLS));
+        this.breakerFailures = Math.max(1, Math.floor(opts.breakerFailures ?? DECIDER_BREAKER_FAILURES));
+        this.timeoutMs = opts.timeoutMs ?? DECIDER_DEFAULT_TIMEOUT_MS;
+        this.calls = opts.counters?.calls ?? 0;
+        this.failures = opts.counters?.failures ?? 0;
+        this.open = opts.counters?.open ?? false;
+        if (this.open)
+            this.offReason = `breaker open after ${this.breakerFailures} failed calls`;
+    }
+    get counters() {
+        return { calls: this.calls, failures: this.failures, open: this.open };
+    }
+    /** Record that a route skipped the decider without a call (no HTTP). */
+    skip(node, reason) {
+        const rec = {
+            node,
+            outcome: "skipped",
+            reason,
+            label: null,
+            confidence: null,
+            margin: null,
+            latency_ms: 0,
+            model: this.provider.model,
+            input_hash: "",
+        };
+        this.records.push(rec);
+        this.log(`  route decider: '${node}' skipped (${reason}); asking the agent`, rec);
+    }
+    async decide(q) {
+        if (this.open)
+            return null;
+        if (this.calls >= this.maxCalls) {
+            if (!this.capped) {
+                this.capped = true;
+                this.offReason = `call cap of ${this.maxCalls} reached`;
+                this.opts.warn?.(`  decider: reached the ${this.maxCalls}-call cap for this run; the agent routes the rest.`);
+            }
+            return null;
+        }
+        this.calls++;
+        const criteria = Object.create(null);
+        for (const c of q.choices)
+            if (!own(criteria, c.id))
+                criteria[c.id] = c.description;
+        const edgeSet = new Set(Object.keys(criteria));
+        const input_hash = hashDecisionInput(q.state, criteria);
+        const started = Date.now();
+        const base = { node: q.node, model: this.provider.model, input_hash };
+        let rec;
         try {
-            const out = await provider.decide({
-                state: req.state,
-                asks: { route: { kind: "choice", instructions: req.question, criteria } },
-                timeoutMs: DECIDER_DEFAULT_TIMEOUT_MS,
-                signal: req.signal,
+            const out = await this.provider.decide({
+                state: q.state,
+                asks: { route: { kind: "choice", instructions: q.question, criteria } },
+                timeoutMs: this.timeoutMs,
+                signal: q.signal,
             });
-            const v = out.route;
+            const v = own(out, "route") ? out.route : undefined;
             if (!v || v.kind !== "choice")
                 throw new DecideError("malformed", "no route answer");
-            const gate = gateVerdict(v, edgeSet);
-            return {
+            // A valid answer, even a low-confidence one, means the provider works.
+            this.failures = 0;
+            const gate = gateVerdict(v, edgeSet, this.thresholds);
+            rec = {
                 ...base,
-                decider_label: v.label,
+                outcome: gate.accepted ? "decided" : "fell_through",
+                ...(gate.reason ? { reason: gate.reason } : {}),
+                label: v.label,
                 confidence: v.confidence,
                 margin: gate.margin,
-                outcome: gate.accepted ? "compared" : "fell_through",
-                ...(gate.reason ? { reason: gate.reason } : {}),
                 latency_ms: Date.now() - started,
             };
         }
         catch (err) {
-            return {
+            const code = err instanceof DecideError ? err.code : "malformed";
+            // An aborted run is not the provider's fault.
+            if (code !== "aborted")
+                this.failures++;
+            rec = {
                 ...base,
-                decider_label: null,
+                outcome: "fell_through",
+                reason: code,
+                label: null,
                 confidence: null,
                 margin: null,
-                outcome: "fell_through",
-                reason: err instanceof DecideError ? err.code : "malformed",
                 latency_ms: Date.now() - started,
             };
+            if (this.failures >= this.breakerFailures && !this.open) {
+                this.open = true;
+                this.offReason = `breaker open after ${this.failures} failed calls`;
+                this.opts.warn?.(`  decider: ${this.failures} failed calls in a row (last: ${code}); not calling it again this run.`);
+            }
         }
-    })();
-    return { settled, edgeSet };
-}
-/** Join the decider's settled result with the agent's choice. */
-export async function finishShadowDecision(pending, node, agentLabel) {
-    const s = await pending.settled;
-    if (s.outcome === "fell_through")
-        return { node, agent_label: agentLabel, agree: null, ...s };
-    if (agentLabel === null) {
-        return { node, agent_label: null, agree: null, ...s, outcome: "fell_through", reason: "agent_failed" };
+        this.records.push(rec);
+        this.log(rec.outcome === "decided"
+            ? `  route decider: '${q.node}' -> '${rec.label}'`
+            : `  route decider: '${q.node}' fell through (${rec.reason}); asking the agent`, rec);
+        return rec.outcome === "decided" ? rec.label : null;
     }
-    return { node, agent_label: agentLabel, agree: s.decider_label === agentLabel, ...s };
-}
-/** `{ compared, agreed, fell_through }` over a run's records. */
-export function summarizeDecisions(records) {
-    let compared = 0;
-    let agreed = 0;
-    for (const r of records) {
-        if (r.outcome === "compared") {
-            compared++;
-            if (r.agree)
-                agreed++;
+    log(msg, rec) {
+        try {
+            this.opts.info?.(msg, { ...rec });
+        }
+        catch {
+            // logging never affects a route
         }
     }
-    return { compared, agreed, fell_through: records.length - compared };
+}
+/** True when some node opts into the decider. */
+export function wantsDecider(nodes) {
+    return Object.values(nodes).some((n) => n.route_by === "decider");
 }
 /**
- * Resolve the run's shadow decider, or null (mode off, nothing configured, or
- * a declared key env var is unset). No hosted fallback exists: null means no
- * HTTP at all.
+ * Resolve the run's decider. `decider` is null with `off` set to the reason
+ * when the workflow opted nodes in but the decider cannot run; both are empty
+ * when no node opted in. No hosted fallback exists: null means no HTTP.
  */
-export function createShadowDecider(config, modeOverride, env, warn) {
-    const mode = modeOverride ?? config?.mode ?? "off";
-    if (mode !== "shadow")
-        return null;
-    const p = config?.provider;
-    if (!p) {
-        warn("  decider: shadow mode needs decider.provider in the workflow; running without it.");
-        return null;
+export function createRunDecider(operator, workflow, opts = {}) {
+    if (!wantsDecider(workflow.nodes))
+        return { decider: null };
+    if (operator === false)
+        return { decider: null, off: "disabled for this run (--no-decider)" };
+    if (!operator || !operator.url || !operator.model) {
+        return {
+            decider: null,
+            off: "no operator config (set SWENY_DECIDER_URL and SWENY_DECIDER_MODEL, or decider: in .sweny.yml)",
+        };
     }
-    let apiKey;
-    if (p.api_key_env) {
-        apiKey = env[p.api_key_env];
-        if (!apiKey) {
-            warn(`  decider: env var ${p.api_key_env} is not set; running without the decider.`);
-            return null;
+    const policy = operator.loopbackOnly
+        ? { loopbackOnly: true }
+        : { allowPrivate: operator.allowPrivate === true };
+    const problem = deciderUrlProblem(operator.url, policy);
+    if (problem)
+        return { decider: null, off: problem };
+    if (operator.loopbackOnly) {
+        // A repo-content URL may only be a local name; anything else needs operator env.
+        const host = bare(new URL(operator.url).hostname);
+        if (!classifyIp(host) && host !== "localhost" && !host.endsWith(".localhost")) {
+            return { decider: null, off: REPO_URL_NOT_LOOPBACK };
         }
     }
-    return { provider: systemOneProvider({ baseUrl: p.base_url, model: p.model, apiKey }), records: [] };
+    const provider = systemOneProvider({
+        baseUrl: operator.url,
+        model: operator.model,
+        policy,
+        // Never a key for a URL that repo content chose.
+        ...(operator.apiKey && !operator.loopbackOnly ? { apiKey: operator.apiKey } : {}),
+        ...(operator.lookup ? { lookup: operator.lookup } : {}),
+    });
+    return {
+        decider: new RunDecider(provider, {
+            ...opts,
+            config: workflow.decider,
+            ...(operator.maxCalls !== undefined ? { maxCalls: operator.maxCalls } : {}),
+            ...(operator.timeoutMs !== undefined ? { timeoutMs: operator.timeoutMs } : {}),
+        }),
+    };
 }