@sweny-ai/core 0.1.162 → 0.1.163

package/dist/cli/main.d.ts

@@ -12,6 +12,7 @@ export declare function workflowRunAction(file: string | undefined, options: Rec
     maxTokens?: string;
     maxCost?: string;
     yes?: boolean;
+    decider?: string;
 }): Promise<void>;
 export declare function workflowExportAction(name: string): void;
 export declare function workflowValidateAction(file: string, options: {

package/dist/cli/main.js

@@ -731,6 +731,10 @@ export function loadWorkflowFile(filePath, knownSkills) {
     return result.workflow;
 }
 export async function workflowRunAction(file, options) {
+    if (options.decider !== undefined && options.decider !== "off" && options.decider !== "shadow") {
+        console.error(chalk.red(`\n  --decider must be off or shadow, got "${options.decider}"\n`));
+        process.exit(1);
+    }
     // Reject junk --timeout/--max-steps up front (both paths) instead of
     // silently falling back to a default.
     let budget;
@@ -1005,6 +1009,7 @@ export async function workflowRunAction(file, options) {
             fileRoot: config.fileRoot || undefined,
             signal,
             max_steps: wfMaxSteps,
+            ...(options.decider ? { decider: options.decider } : {}),
             stageOutputs: options.stage === true,
             ...(spendBudget ? { budget: spendBudget } : {}),
             harnessPolicy: resolveHarnessPolicy(process.env, typeof options.harnessPolicy === "string" ? options.harnessPolicy : undefined, runLogger),
@@ -1024,7 +1029,7 @@ export async function workflowRunAction(file, options) {
         // PR billboard markdown (metadata only). Written before any early exit so
         // --json runs and failed runs still get a comment.
         if (options.commentFile) {
-            writeRunComment(options.commentFile, workflow, results, summarizeRun(results, wfDurationMs), {
+            writeRunComment(options.commentFile, workflow, results, summarizeRun(results, wfDurationMs, false, trace), {
                 trace,
                 durationsMs: Object.fromEntries(nodeTimer.durations),
             });
@@ -1051,7 +1056,7 @@ export async function workflowRunAction(file, options) {
         }
         // Run receipt (metadata only) + optional $GITHUB_STEP_SUMMARY.
         runLogger.flush();
-        const receipt = summarizeRun(results, wfDurationMs);
+        const receipt = summarizeRun(results, wfDurationMs, false, trace);
         writeStepSummary(workflow, results, receipt, trace);
         // The answer, above the receipt: the terminal node's result, or the failed node's error.
         // Also saved to .sweny/runs/<id>/output.md (local only; --no-history skips the file).

package/dist/cli/run-history.d.ts

@@ -55,6 +55,12 @@ export interface RunRecord {
     };
     /** Opinions the harness could not honor natively on some node, deduped. Absent when none. */
     degraded?: string[];
+    /** Shadow-mode decider agreement counts (#357). Absent when the decider was off. */
+    decider?: {
+        compared: number;
+        agreed: number;
+        fell_through: number;
+    };
 }
 /** sha256 (hex) of the workflow as canonical JSON: keys sorted, undefined dropped. */
 export declare function hashWorkflow(workflow: Workflow): string;

package/dist/cli/run-history.js

@@ -69,7 +69,7 @@ export function createNodeTimer(now = Date.now) {
 // ── Build the record ────────────────────────────────────────────
 const isNum = (v) => typeof v === "number" && Number.isFinite(v);
 export function buildRunRecord(i) {
-    const summary = summarizeRun(i.results, i.durationMs, i.crashed);
+    const summary = summarizeRun(i.results, i.durationMs, i.crashed, i.trace);
     const retries = new Map();
     for (const s of i.trace?.steps ?? []) {
         if (s.retryAttempt !== undefined)
@@ -113,6 +113,15 @@ export function buildRunRecord(i) {
         },
         ...(harness ? { harness: { id: harness.id, version: harness.version } } : {}),
         ...(degraded.length > 0 ? { degraded } : {}),
+        ...(summary.decider
+            ? {
+                decider: {
+                    compared: summary.decider.compared,
+                    agreed: summary.decider.agreed,
+                    fell_through: summary.decider.fellThrough,
+                },
+            }
+            : {}),
     };
 }
 // ── Write, prune, read ──────────────────────────────────────────

package/dist/cli/run-output.d.ts

@@ -39,6 +39,16 @@ export interface RunSummary {
         limit: number;
         spent: number;
     };
+    /**
+     * Shadow-mode decider agreement (#357), counts only. `compared` decisions
+     * passed every gate; `agreed` matched the agent; the rest fell through.
+     * Absent when the decider was off or never consulted.
+     */
+    decider?: {
+        compared: number;
+        agreed: number;
+        fellThrough: number;
+    };
 }
 export interface RunPolicy {
     /** Agent env narrowed to the allowlist. Absent when no node reported it. */
@@ -57,7 +67,7 @@ export interface RunPolicy {
 /** The short key of a `degraded` entry: the text before its first colon. */
 export declare function degradedKey(entry: string): string;
 /** Sum the per-node results into one run summary. */
-export declare function summarizeRun(results: Map<string, NodeResult>, durationMs: number, crashed?: boolean): RunSummary;
+export declare function summarizeRun(results: Map<string, NodeResult>, durationMs: number, crashed?: boolean, trace?: ExecutionTrace): RunSummary;
 /**
  * `policy: env scoped, sandbox on, 1 output staged`. Only what the run knew:
  * no segment for a fact no node reported. Undefined when there is nothing to say.

package/dist/cli/run-output.js

@@ -8,6 +8,7 @@
 import fs from "node:fs";
 import chalk from "chalk";
 import { consoleLogger } from "../types.js";
+import { summarizeDecisions } from "../decider.js";
 import { toMermaidBlock } from "../mermaid.js";
 /** The short key of a `degraded` entry: the text before its first colon. */
 export function degradedKey(entry) {
@@ -15,7 +16,7 @@ export function degradedKey(entry) {
     return (i === -1 ? entry : entry.slice(0, i)).trim();
 }
 /** Sum the per-node results into one run summary. */
-export function summarizeRun(results, durationMs, crashed = false) {
+export function summarizeRun(results, durationMs, crashed = false, trace) {
     let nodesOk = 0;
     let nodesSkipped = 0;
     let failed = crashed;
@@ -81,8 +82,13 @@ export function summarizeRun(results, durationMs, crashed = false) {
         ...(degraded.size > 0 ? { degraded: [...degraded] } : {}),
         ...(Object.keys(policy).length > 0 ? { policy } : {}),
         ...(budget ? { budget } : {}),
+        ...(trace?.decisions && trace.decisions.length > 0 ? { decider: decisionCounts(trace) } : {}),
     };
 }
+function decisionCounts(trace) {
+    const d = summarizeDecisions(trace.decisions ?? []);
+    return { compared: d.compared, agreed: d.agreed, fellThrough: d.fell_through };
+}
 /**
  * `policy: env scoped, sandbox on, 1 output staged`. Only what the run knew:
  * no segment for a fact no node reported. Undefined when there is nothing to say.
@@ -156,6 +162,13 @@ export function formatReceipt(s) {
         ...(s.degraded && s.degraded.length > 0 ? [`degraded: ${s.degraded.join(", ")}`] : []),
         ...(formatPolicySegment(s.policy) ? [formatPolicySegment(s.policy)] : []),
         ...(s.budget ? [formatBudgetOverrun(s.budget)] : []),
+        ...(s.decider
+            ? [
+                s.decider.compared > 0
+                    ? `decider agreed ${s.decider.agreed}/${s.decider.compared}`
+                    : `decider fell through ${s.decider.fellThrough}/${s.decider.fellThrough}`,
+            ]
+            : []),
     ];
     return parts.join(" · ");
 }
@@ -286,4 +299,8 @@ export const WORKFLOW_RUN_OPTIONS = [
         "--harness-policy <mode>",
         "strict: refuse a node whose policy the agent cannot enforce; warn: run it and report what was not enforced (default: strict under GitHub Actions, warn elsewhere; env SWENY_HARNESS_POLICY)",
     ],
+    [
+        "--decider <mode>",
+        "Decision model for route choices: off (default) or shadow. Shadow asks the workflow's decider.provider alongside the agent and reports agreement; the route is always the agent's. Needs decider.provider in the workflow (no default URL)",
+    ],
 ];

package/dist/decider.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Decision models (#357), shadow mode.
+ *
+ * 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.
+ *
+ * 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).
+ */
+/** 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. */
+export declare const DECIDER_DEFAULT_TIMEOUT_MS = 2000;
+export type DeciderMode = "off" | "shadow";
+/** Workflow-level `decider` block. */
+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;
+    };
+}
+/** One Choice question: pick a key of `criteria`. */
+export interface ChoiceAsk {
+    kind: "choice";
+    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;
+    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 declare class DecideError extends Error {
+    readonly code: DecideErrorCode;
+    constructor(code: DecideErrorCode, message: string);
+}
+export interface DecideRequest {
+    state: unknown;
+    asks: Record<string, Ask>;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+export interface DecisionProvider {
+    /** Short provider family label for logs, e.g. `systemone`. */
+    id: string;
+    model: string;
+    /** Throws {@link DecideError}; never returns a partial answer. */
+    decide(req: DecideRequest): Promise<Record<string, Verdict>>;
+}
+export interface SystemOneOptions {
+    baseUrl: string;
+    model: string;
+    apiKey?: string;
+    /** Default timeout when `decide()` is not given one. Default 2000 ms. */
+    timeoutMs?: number;
+}
+/**
+ * `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.
+ */
+export declare function systemOneProvider(opts: SystemOneOptions): DecisionProvider;
+export type FallThroughReason = DecideErrorCode | "low_confidence" | "low_margin" | "label_outside_edge_set";
+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. */
+export interface DeciderRecord {
+    /** Node the route was decided at. */
+    node: string;
+    /** 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;
+    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[];
+}
+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: {
+    question: string;
+    state: unknown;
+    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;
+};
+/**
+ * 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.
+ */
+export declare function createShadowDecider(config: DeciderConfig | undefined, modeOverride: DeciderMode | undefined, env: NodeJS.ProcessEnv, warn: (msg: string) => void): ShadowDecider | null;

package/dist/decider.js

@@ -0,0 +1,260 @@
+/**
+ * Decision models (#357), shadow mode.
+ *
+ * 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.
+ *
+ * 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).
+ */
+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. */
+export const DECIDER_DEFAULT_TIMEOUT_MS = 2000;
+export class DecideError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "DecideError";
+    }
+}
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const isProb = (v) => typeof v === "number" && Number.isFinite(v) && v >= 0 && v <= 1;
+/**
+ * `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.
+ */
+export function systemOneProvider(opts) {
+    const url = `${opts.baseUrl.replace(/\/+$/, "")}/v1/systemone`;
+    return {
+        id: "systemone",
+        model: opts.model,
+        async decide(req) {
+            const timeoutMs = req.timeoutMs ?? opts.timeoutMs ?? DECIDER_DEFAULT_TIMEOUT_MS;
+            const questions = {};
+            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);
+            }
+        },
+    };
+}
+function parseAnswers(body, asks) {
+    if (!isRecord(body) || !isRecord(body.answers))
+        throw new DecideError("malformed", "missing answers object");
+    const out = {};
+    for (const [name, ask] of Object.entries(asks)) {
+        const a = body.answers[name];
+        if (!isRecord(a))
+            throw new DecideError("malformed", `no answer for question '${name}'`);
+        if (a.type !== undefined && a.type !== ask.kind)
+            throw new DecideError("malformed", "answer type mismatch");
+        if (typeof a.choice !== "string")
+            throw new DecideError("malformed", "choice is not a string");
+        if (!isProb(a.confidence))
+            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)) {
+            if (!isProb(v))
+                throw new DecideError("malformed", "probability is not a number in 0..1");
+            probabilities[k] = 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");
+        }
+        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));
+    const margin = top - second;
+    if (!edgeSet.has(v.label))
+        return { accepted: false, reason: "label_outside_edge_set", margin };
+    if (!(v.confidence >= DECIDER_MIN_CONFIDENCE))
+        return { accepted: false, reason: "low_confidence", margin };
+    if (!(margin >= DECIDER_MIN_MARGIN))
+        return { accepted: false, reason: "low_margin", margin };
+    return { accepted: true, margin };
+}
+export function hashDecisionInput(state, criteria) {
+    let json;
+    try {
+        json = JSON.stringify({ state, criteria }) ?? "";
+    }
+    catch {
+        json = "unserializable";
+    }
+    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.
+ */
+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 () => {
+        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 v = out.route;
+            if (!v || v.kind !== "choice")
+                throw new DecideError("malformed", "no route answer");
+            const gate = gateVerdict(v, edgeSet);
+            return {
+                ...base,
+                decider_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 {
+                ...base,
+                decider_label: null,
+                confidence: null,
+                margin: null,
+                outcome: "fell_through",
+                reason: err instanceof DecideError ? err.code : "malformed",
+                latency_ms: Date.now() - started,
+            };
+        }
+    })();
+    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" };
+    }
+    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++;
+        }
+    }
+    return { compared, agreed, fell_through: records.length - compared };
+}
+/**
+ * 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.
+ */
+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;
+    }
+    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;
+        }
+    }
+    return { provider: systemOneProvider({ baseUrl: p.base_url, model: p.model, apiKey }), records: [] };
+}

package/dist/executor.d.ts

@@ -15,6 +15,7 @@
 import type { Workflow, Skill, Tool, Claude, Observer, Logger, ExecutionResult } from "./types.js";
 import type { HarnessPolicyMode } from "./harness/policy.js";
 import type { AgentHarness } from "./harness/types.js";
+import type { DeciderMode } from "./decider.js";
 import type { Budget } from "./budget.js";
 import { type ActorInfo } from "./safe-outputs.js";
 export interface ExecuteOptions {
@@ -97,6 +98,12 @@ export interface ExecuteOptions {
      * all (cost on Codex). Default: {@link resolveHarnessPolicy} from the run env.
      */
     harnessPolicy?: HarnessPolicyMode;
+    /**
+     * Override `workflow.decider.mode` (CLI `--decider`). `shadow` still needs
+     * `decider.provider` in the workflow; there is no default URL. Default: the
+     * workflow's own mode, else off (zero HTTP calls).
+     */
+    decider?: DeciderMode;
 }
 /**
  * Default workflow-level step budget. Counts total node executions across the

package/dist/executor.js

@@ -26,6 +26,7 @@ import { fenceUntrusted } from "./untrusted.js";
 import { asClaude } from "./harness/compat.js";
 import { budgetGate, isToolClass, policyGate, resolveHarnessPolicy } from "./harness/policy.js";
 import { BudgetGuard, describeOverrun, minLimits, toLimits } from "./budget.js";
+import { createShadowDecider, finishShadowDecision, startShadowDecision } from "./decider.js";
 import { buildNodePolicy, resolveNodePermissions } from "./node-policy.js";
 import { applySafeOutputs, createEmitOutputTool, createWriteStageState, resolveActor, safeOutputsInstruction, unresolvedOutputs, SAFE_OUTPUT_SCREEN_INSTRUCTION, } from "./safe-outputs.js";
 /**
@@ -88,6 +89,10 @@ export async function execute(workflow, input, options) {
     // `budget` and the caller's (`--max-tokens`, `--max-cost`).
     const budgetGuard = new BudgetGuard(minLimits(toLimits(workflow.budget), toLimits(options.budget)));
     const harnessPolicy = options.harnessPolicy ?? resolveHarnessPolicy(runEnv);
+    // Decision model (#357): shadow only. Null (the default) means no HTTP at all.
+    const shadow = createShadowDecider(workflow.decider, options.decider, runEnv, (m) => logger.warn(m));
+    if (shadow)
+        trace.decisions = shadow.records;
     // Build an eval-time alias table from the loaded skills. Each skill owns
     // its own mapping between skill-tool names and equivalent MCP names. Core
     // stays vendor-neutral; this call just unions what the skills declare.
@@ -254,7 +259,7 @@ export async function execute(workflow, input, options) {
             }
             // Apply normal routing rules (dry run gate + resolveNext).
             // TODO: dedupe with requires path — see advanceFromNode helper below
-            const next = await advanceFromNode(workflow, currentId, results, input, claude, observer, edgeCounts, logger, trace, { signal, timeoutMs });
+            const next = await advanceFromNode(workflow, currentId, results, input, claude, observer, edgeCounts, logger, trace, { signal, timeoutMs, shadow });
             currentId = next;
             continue;
         }
@@ -591,6 +596,7 @@ export async function execute(workflow, input, options) {
         currentId = await advanceFromNode(workflow, currentId, results, input, claude, observer, edgeCounts, logger, trace, {
             signal,
             timeoutMs,
+            shadow,
         });
     }
     safeObserve(observer, {
@@ -1248,13 +1254,31 @@ async function resolveNext(workflow, current, results, input, claude, observer,
     if (defaultEdge) {
         choices.push({ id: defaultEdge.to, description: "None of the above / default path" });
     }
+    const question = "Based on the results so far, which condition is true?";
+    // Shadow mode (#357): the decider gets the same question in parallel. Its
+    // promise never rejects and its answer is only logged, so the route below
+    // is the agent's in every case.
+    const pending = abort?.shadow
+        ? startShadowDecision(abort.shadow.provider, { question, state: context, choices, signal: abort.signal })
+        : undefined;
     const chosen = await claude.evaluate({
-        question: "Based on the results so far, which condition is true?",
+        question,
         context,
         choices,
         signal: abort?.signal,
         timeoutMs: abort?.timeoutMs,
     });
+    if (pending && abort?.shadow) {
+        try {
+            const rec = await finishShadowDecision(pending, current, chosen);
+            abort.shadow.records.push(rec);
+            const verdict = rec.outcome === "compared" ? (rec.agree ? "agreed" : "disagreed") : `fell through (${rec.reason})`;
+            logger?.info(`  decider (shadow): node '${current}' ${verdict}`, { ...rec });
+        }
+        catch {
+            // shadow logging must never affect a route
+        }
+    }
     // Fail closed. `evaluate` returns null when the routing decision could not
     // be made (SDK error, timeout, non-success subtype, or an unparseable
     // answer). We must NOT fall through to a conditional edge: on a node with a

package/dist/index.d.ts

@@ -27,6 +27,8 @@ export { EVALUATOR_KINDS, EVAL_POLICIES, REQUIRES_ON_FAIL, NODE_ON_FAIL, MCP_TRA
 export { consoleLogger } from "./types.js";
 export { execute, RouteEvaluationError } from "./executor.js";
 export type { ExecuteOptions } from "./executor.js";
+export { systemOneProvider, DecideError, gateVerdict, DECIDER_MIN_CONFIDENCE, DECIDER_MIN_MARGIN } from "./decider.js";
+export type { DecisionProvider, DeciderConfig, DeciderMode, DeciderRecord, SystemOneOptions } from "./decider.js";
 export { BudgetGuard, describeOverrun, minLimits, toLimits } from "./budget.js";
 export type { Budget, BudgetOverrun, BudgetUnit, SpendLimits } from "./budget.js";
 export { resolveNodePermissions, buildNodePolicy } from "./node-policy.js";