@sweny-ai/core 0.1.177 → 0.1.178

package/dist/decider.d.ts

@@ -1,32 +1,68 @@
 /**
- * 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).
  */
-/** Accept a decider answer only at or above this confidence. */
-export declare const DECIDER_MIN_CONFIDENCE = 0.85;
-/** ... and only when the top label leads the runner-up by at least this much. */
-export declare const DECIDER_MIN_MARGIN = 0.2;
-/** Per-call timeout when the provider does not set one. */
+import dns from "node:dns";
+/** Per-call timeout. */
 export declare const DECIDER_DEFAULT_TIMEOUT_MS = 2000;
-export type DeciderMode = "off" | "shadow";
-/** Workflow-level `decider` block. */
+/** Consecutive failed calls that open the breaker for the rest of the run. */
+export declare const DECIDER_BREAKER_FAILURES = 3;
+/** Decider calls one logical run (resumes included) may make. */
+export declare const DECIDER_DEFAULT_MAX_CALLS = 200;
+/** Probabilities must sum to 1 within this. */
+export declare const DECIDER_SUM_TOLERANCE = 0.01;
+/** Workflow-level `decider` block: thresholds only. */
 export interface DeciderConfig {
-    mode: DeciderMode;
-    provider?: {
-        /** Server root, e.g. `http://localhost:11434` or `https://api.typesafe.ai`. */
-        base_url: string;
-        model: string;
-        /** Name of the env var holding the bearer key. Never the key itself. */
-        api_key_env?: string;
-    };
+    /** Default 0.85, never below 0.7. */
+    min_confidence?: number;
+    /** Default 0.2, never below 0.1. */
+    min_margin?: number;
+}
+/**
+ * Operator config: where the decision model lives. Never read from a
+ * workflow file. The CLI builds it with one trust domain per credential: a
+ * URL from operator env (SWENY_DECIDER_URL) may be remote and gets the key
+ * (SWENY_DECIDER_API_KEY); a URL from repo content (`.sweny.yml`) is
+ * `loopbackOnly` and never gets a key. Library callers are the operator.
+ */
+export interface DeciderOperatorConfig {
+    /** Server root serving POST /v1/systemone. http or https only. */
+    url: string;
+    model: string;
+    /** Bearer key. Never sent when `loopbackOnly`. */
+    apiKey?: string;
+    /** Allow loopback and private addresses. Link-local and metadata addresses stay refused. */
+    allowPrivate?: boolean;
+    /** The URL came from repo content: it must resolve to loopback only, and no key is ever sent. */
+    loopbackOnly?: boolean;
+    /** DNS lookup to resolve the host with (test seam). Default: `dns.lookup`. */
+    lookup?: LookupFn;
+    /** Per-call timeout in ms. Default 2000. */
+    timeoutMs?: number;
+    /** Calls per logical run. Default 200. */
+    maxCalls?: number;
 }
 /** One Choice question: pick a key of `criteria`. */
 export interface ChoiceAsk {
@@ -34,16 +70,16 @@ export interface ChoiceAsk {
     instructions: string;
     criteria: Record<string, string>;
 }
-/** Only Choice exists today. Noul and Score arrive as further union members. */
 export type Ask = ChoiceAsk;
 export interface ChoiceVerdict {
     kind: "choice";
     label: string;
+    /** Exactly the criteria keys (null prototype). */
     probabilities: Record<string, number>;
     confidence: number;
 }
 export type Verdict = ChoiceVerdict;
-export type DecideErrorCode = "timeout" | "aborted" | "network" | "unauthorized" | "invalid_request" | "rate_limited" | "overloaded" | "http_error" | "malformed" | "unknown_label";
+export type DecideErrorCode = "timeout" | "aborted" | "network" | "unauthorized" | "invalid_request" | "rate_limited" | "overloaded" | "http_error" | "malformed" | "unknown_label" | "blocked_address";
 export declare class DecideError extends Error {
     readonly code: DecideErrorCode;
     constructor(code: DecideErrorCode, message: string);
@@ -61,84 +97,160 @@ export interface DecisionProvider {
     /** Throws {@link DecideError}; never returns a partial answer. */
     decide(req: DecideRequest): Promise<Record<string, Verdict>>;
 }
+/** Which addresses a decider connection may reach. */
+export interface AddressPolicy {
+    /** Loopback and private ranges allowed (operator env only). */
+    allowPrivate?: boolean;
+    /** Only loopback allowed (a URL that came from repo content). */
+    loopbackOnly?: boolean;
+}
+/** Why connecting to this resolved address is refused, or null. */
+export declare function addressProblem(address: string, policy: AddressPolicy): string | 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 declare function deciderUrlProblem(raw: string, policy?: AddressPolicy): string | null;
+/** Node's `lookup` shape for `net.connect` / `http.request`. */
+export type LookupFn = (hostname: string, options: dns.LookupOptions, callback: (err: NodeJS.ErrnoException | null, address: string | dns.LookupAddress[], family?: number) => void) => void;
+/**
+ * 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 declare function guardedLookup(policy: AddressPolicy, base?: LookupFn): LookupFn;
 export interface SystemOneOptions {
     baseUrl: string;
     model: string;
     apiKey?: string;
     /** Default timeout when `decide()` is not given one. Default 2000 ms. */
     timeoutMs?: number;
+    /** Addresses the connection may reach. Default: public only. */
+    policy?: AddressPolicy;
+    /** DNS lookup the guard resolves with (test seam). Default: `dns.lookup`. */
+    lookup?: LookupFn;
 }
 /**
  * `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 declare function systemOneProvider(opts: SystemOneOptions): DecisionProvider;
-export type FallThroughReason = DecideErrorCode | "low_confidence" | "low_margin" | "label_outside_edge_set";
+/**
+ * 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 declare function parseAnswers(body: unknown, asks: Record<string, Ask>): Record<string, Verdict>;
+export type FallThroughReason = DecideErrorCode | "low_confidence" | "low_margin" | "label_outside_edge_set" | "no_routable_state";
+export interface DeciderThresholds {
+    minConfidence: number;
+    minMargin: number;
+}
 export interface GateResult {
     accepted: boolean;
     reason?: FallThroughReason;
     /** Top probability minus the runner-up (0 when there is no runner-up). */
     margin: number;
 }
-/** All gates must pass: label in the edge set, confidence, then top-two margin. */
-export declare function gateVerdict(v: ChoiceVerdict, edgeSet: ReadonlySet<string>): GateResult;
-/** One logged shadow decision. Metadata only: no state, no prompts, no prose. */
+/** The workflow's thresholds, else the defaults, never looser than the floors, never above 1. */
+export declare function resolveThresholds(config?: DeciderConfig): DeciderThresholds;
+/** All gates must pass: label in the edge set, confidence, then top-two margin (each with float slack). */
+export declare function gateVerdict(v: ChoiceVerdict, edgeSet: ReadonlySet<string>, thresholds?: DeciderThresholds): GateResult;
+/** One decider consultation. Metadata only: no state, no prompts, no prose. */
 export interface DeciderRecord {
     /** Node the route was decided at. */
     node: string;
+    /** `decided`: the label is the route. `fell_through`: the agent was asked. `skipped`: no call was made. */
+    outcome: "decided" | "fell_through" | "skipped";
+    reason?: FallThroughReason;
     /** Edge target the decider picked (a node id). Null when it gave no answer. */
-    decider_label: string | null;
-    /** Edge target the agent picked. Null when the agent's evaluation failed. */
-    agent_label: string | null;
+    label: string | null;
     confidence: number | null;
     margin: number | null;
-    /** `compared`: the decider passed every gate. `fell_through`: it did not, see `reason`. */
-    outcome: "compared" | "fell_through";
-    reason?: FallThroughReason | "agent_failed";
-    /** Decider label equals agent label. Null unless `outcome` is `compared`. */
-    agree: boolean | null;
     latency_ms: number;
     model: string;
     /** First 16 hex chars of sha256 over the state and criteria sent. */
     input_hash: string;
 }
-/** What the executor holds for one run in shadow mode. */
-export interface ShadowDecider {
-    provider: DecisionProvider;
-    records: DeciderRecord[];
+/** The breaker and cap counters, journaled so they span resumes. */
+export interface DeciderCounters {
+    calls: number;
+    failures: number;
+    open: boolean;
 }
 export declare function hashDecisionInput(state: unknown, criteria: Record<string, string>): string;
-export interface PendingShadow {
-    /** Never rejects. */
-    settled: Promise<Omit<DeciderRecord, "agent_label" | "agree" | "node">>;
-    edgeSet: ReadonlySet<string>;
-}
-/**
- * Start the decider call. Returns at once; the promise never rejects, so the
- * agent's own evaluation is never delayed or failed by it.
- */
-export declare function startShadowDecision(provider: DecisionProvider, req: {
+export interface RouteQuestion {
+    node: string;
     question: string;
+    /** The fenced, redacted routing projection. */
     state: unknown;
+    /** Every live out-edge target of the node, with its condition. */
     choices: {
         id: string;
         description: string;
     }[];
     signal?: AbortSignal;
-}): PendingShadow;
-/** Join the decider's settled result with the agent's choice. */
-export declare function finishShadowDecision(pending: PendingShadow, node: string, agentLabel: string | null): Promise<DeciderRecord>;
-/** `{ compared, agreed, fell_through }` over a run's records. */
-export declare function summarizeDecisions(records: readonly DeciderRecord[]): {
-    compared: number;
-    agreed: number;
-    fell_through: number;
-};
+}
+export interface RunDeciderOptions {
+    /** Raw workflow thresholds; clamped to the floors here. */
+    config?: DeciderConfig;
+    maxCalls?: number;
+    breakerFailures?: number;
+    timeoutMs?: number;
+    /** Counters carried over from an earlier attempt of the same run (resume). */
+    counters?: DeciderCounters;
+    /** Operator-facing messages (breaker opened, cap reached). Metadata only. */
+    warn?: (msg: string) => void;
+    /** Per-call log line. Metadata only. */
+    info?: (msg: string, data?: Record<string, unknown>) => void;
+}
 /**
- * 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.
+ * 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 declare function createShadowDecider(config: DeciderConfig | undefined, modeOverride: DeciderMode | undefined, env: NodeJS.ProcessEnv, warn: (msg: string) => void): ShadowDecider | null;
+export declare class RunDecider {
+    readonly provider: DecisionProvider;
+    private readonly opts;
+    readonly records: DeciderRecord[];
+    readonly thresholds: DeciderThresholds;
+    /** Set when the breaker opened or the cap was reached. */
+    offReason?: string;
+    private calls;
+    private failures;
+    private open;
+    private capped;
+    private readonly maxCalls;
+    private readonly breakerFailures;
+    private readonly timeoutMs;
+    constructor(provider: DecisionProvider, opts?: RunDeciderOptions);
+    get counters(): DeciderCounters;
+    /** Record that a route skipped the decider without a call (no HTTP). */
+    skip(node: string, reason: FallThroughReason): void;
+    decide(q: RouteQuestion): Promise<string | null>;
+    private log;
+}
+/** True when some node opts into the decider. */
+export declare function wantsDecider(nodes: Record<string, {
+    route_by?: string;
+}>): boolean;
+/**
+ * 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 declare function createRunDecider(operator: DeciderOperatorConfig | false | undefined, workflow: {
+    decider?: DeciderConfig;
+    nodes: Record<string, {
+        route_by?: string;
+    }>;
+}, opts?: Omit<RunDeciderOptions, "config" | "maxCalls" | "timeoutMs">): {
+    decider: RunDecider | null;
+    off?: string;
+};