@sweny-ai/core 0.1.161 → 0.1.163

package/dist/executor.js

@@ -16,6 +16,7 @@ import { consoleLogger } from "./types.js";
 import { resolveSources } from "./source-resolver.js";
 import { evaluateAll, aggregateEval } from "./eval/index.js";
 import { evaluateRequires } from "./requires.js";
+import { evaluateExpression, isWhenExpression, parseExpression, whenLabel } from "./when.js";
 import { buildRetryPreamble } from "./retry.js";
 import { resolveExecutionModel } from "./model.js";
 import { buildToolAliases } from "./skills/index.js";
@@ -25,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";
 /**
@@ -87,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.
@@ -253,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;
         }
@@ -590,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, {
@@ -1118,15 +1125,17 @@ function resolveConfig(skills, overrides, env = process.env) {
  * Returns the next node ID, or null when execution should stop.
  */
 async function advanceFromNode(workflow, currentId, results, input, claude, observer, edgeCounts, logger, trace, abort) {
-    // Dry run path gate: stop at the first conditional routing decision.
+    // Dry run path gate: stop at the first natural-language routing decision.
     // Safety does not depend on this (#380): under dry-run every node already
-    // runs read-only (see execute()). The stop keeps the dry-run path a pure
-    // function of the graph (no LLM route evaluation, so the same workflow
-    // always visits the same nodes) and skips action branches whose output
-    // would only describe writes that cannot happen.
+    // runs read-only (see execute()). The stop keeps dry-run routing free of
+    // model route evaluation, so the path is reproducible from the node outputs
+    // alone. Expression edges (#461) are evaluated by sweny with no model call,
+    // so dry-run follows them: a preview can reach the nodes past a
+    // deterministic branch (still read-only, outputs staged) and stops only
+    // where a model would have to pick the branch.
     if (isDryRunInput(input)) {
         const outEdges = workflow.edges.filter((e) => e.from === currentId);
-        if (outEdges.some((e) => e.when)) {
+        if (outEdges.some((e) => e.when && !isWhenExpression(e.when))) {
             safeObserve(observer, { type: "route", from: currentId, to: "(end)", reason: "dry run" }, logger);
             return null;
         }
@@ -1134,7 +1143,7 @@ async function advanceFromNode(workflow, currentId, results, input, claude, obse
     const prevId = currentId;
     const nextId = await resolveNext(workflow, currentId, results, input, claude, observer, edgeCounts, logger, abort);
     if (nextId) {
-        const reason = workflow.edges.find((e) => e.from === prevId && e.to === nextId)?.when ?? "only path";
+        const reason = whenLabel(workflow.edges.find((e) => e.from === prevId && e.to === nextId)?.when) ?? "only path";
         trace.edges.push({ from: prevId, to: nextId, reason });
     }
     return nextId;
@@ -1144,7 +1153,8 @@ async function advanceFromNode(workflow, currentId, results, input, claude, obse
  *
  * - 0 out-edges → terminal (return null)
  * - 1 unconditional edge → follow it
- * - Multiple or conditional → Claude evaluates
+ * - Every conditional edge is an `{ expr }` expression → sweny evaluates them, no model call
+ * - Otherwise multiple or conditional → Claude evaluates
  *
  * Edges with max_iterations are filtered out once exhausted.
  */
@@ -1192,6 +1202,12 @@ async function resolveNext(workflow, current, results, input, claude, observer,
         safeObserve(observer, { type: "route", from: current, to: defaultEdge.to, reason: "only path" }, logger);
         return defaultEdge.to;
     }
+    // Deterministic routing (#461): every conditional out-edge is an expression,
+    // so sweny decides without a model call. validateWorkflow rejects a node
+    // that mixes expression and natural-language edges.
+    if (conditionalEdges.every((e) => isWhenExpression(e.when))) {
+        return resolveByExpressions(workflow, current, results, conditionalEdges, defaultEdge, observer, edgeCounts, logger);
+    }
     // Claude evaluates which condition matches. Include input so conditions
     // can reference workflow-level flags like dryRun, and expose evals so
     // routing edges can read `priorNode.evals.X.pass`.
@@ -1233,18 +1249,36 @@ async function resolveNext(workflow, current, results, input, claude, observer,
     }
     const choices = conditionalEdges.map((e) => ({
         id: e.to,
-        description: e.when,
+        description: whenLabel(e.when),
     }));
     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
@@ -1306,6 +1340,76 @@ async function resolveNext(workflow, current, results, input, claude, observer,
     }, logger);
     return resolved;
 }
+/**
+ * Pick the out-edge whose `{ expr }` condition is true, with no model call
+ * (#461). Exactly one true edge is taken. None true takes the unconditional
+ * default edge when there is one. Otherwise (no edge true and no default, or
+ * two or more true) it fails closed with a RouteEvaluationError, the same
+ * contract as a failed model route evaluation: sweny never guesses an edge.
+ *
+ * An expression reads only successful nodes' outputs. A missing field, or a
+ * node that did not run or did not succeed, makes that expression false and
+ * is logged as a warning, never a silent true.
+ */
+function resolveByExpressions(workflow, current, results, conditionalEdges, defaultEdge, observer, edgeCounts, logger) {
+    const scope = {};
+    for (const [id, r] of results.entries()) {
+        if (r.status === "success")
+            scope[id] = buildPriorNodeContext(r);
+    }
+    const matched = [];
+    for (const edge of conditionalEdges) {
+        const expr = whenLabel(edge.when);
+        let outcome;
+        try {
+            outcome = evaluateExpression(parseExpression(expr), scope);
+        }
+        catch (err) {
+            // validateWorkflow parses every expression before a run, so this only
+            // fires for a workflow that skipped validation. Fail closed.
+            const msg = err instanceof Error ? err.message : String(err);
+            safeObserve(observer, { type: "route", from: current, to: "(end)", reason: `invalid when expression` }, logger);
+            throw new RouteEvaluationError(current, `invalid when expression on edge '${current}' -> '${edge.to}': ${msg}`);
+        }
+        if (outcome.problem) {
+            logger?.warn(`  route expr: '${current}' -> '${edge.to}' is false: ${outcome.problem} (${expr})`, {
+                node: current,
+                to: edge.to,
+            });
+            safeObserve(observer, {
+                type: "node:warning",
+                node: current,
+                reason: `when expression on edge to '${edge.to}' evaluated false: ${outcome.problem}`,
+                fields: [],
+            }, logger);
+        }
+        if (outcome.value)
+            matched.push({ to: edge.to, expr });
+    }
+    const take = (to, reason) => {
+        if (edgeCounts) {
+            const key = `${current}→${to}`;
+            edgeCounts.set(key, (edgeCounts.get(key) ?? 0) + 1);
+        }
+        safeObserve(observer, { type: "route", from: current, to, reason }, logger);
+        return to;
+    };
+    if (matched.length === 1)
+        return take(matched[0].to, matched[0].expr);
+    if (matched.length === 0 && defaultEdge) {
+        logger?.info(`  route expr: no expression matched for '${current}'; taking default edge '${defaultEdge.to}'`, {
+            node: current,
+        });
+        return take(defaultEdge.to, "no expression matched; default edge");
+    }
+    const why = matched.length === 0
+        ? `no when expression on node '${current}' is true and there is no default (unconditional) edge`
+        : `${matched.length} when expressions on node '${current}' are true (to ${matched.map((m) => m.to).join(", ")}); ` +
+            `exactly one may match`;
+    logger?.error(`  route expr: ${why}; refusing to guess. Terminating the run.`, { node: current });
+    safeObserve(observer, { type: "route", from: current, to: "(end)", reason: why }, logger);
+    throw new RouteEvaluationError(current, `${why}; refusing to guess`);
+}
 /**
  * Validate a workflow definition before execution.
  */

package/dist/index.d.ts

@@ -21,12 +21,14 @@
  * })
  * ```
  */
-export type { Skill, SkillCategory, SkillDefinition, Tool, ToolContext, ConfigField, JSONSchema, Workflow, Node, Edge, NodeResult, ToolCall, ExecutionEvent, Observer, Claude, Logger, TraceStep, TraceEdge, ExecutionTrace, ExecutionResult, Source, ResolvedSource, SourceKind, SourceResolutionMap, WorkflowInputs, WorkflowInputField, WorkflowInputType, InputValidationError, InputValidationResult, Evaluator, EvaluatorRule, EvalResult, EvaluatorKind, NodeRequires, NodeRetry, NodeToolFilter, OutputMatch, NodeSources, EvalPolicy, RequiresOnFail, NodeOnFail, McpTransport, WorkflowType, SkillHarnessKey, NodeAccess, NodePermissions, NodePermissionsSpec, SafeOutputType, SafeOutputDeclaration, SafeOutputsPolicy, SafeOutputReceipt, SafeOutputPin, AuthorAssociation, } from "./types.js";
+export type { Skill, SkillCategory, SkillDefinition, Tool, ToolContext, ConfigField, JSONSchema, Workflow, Node, Edge, EdgeWhen, WhenExpression, NodeResult, ToolCall, ExecutionEvent, Observer, Claude, Logger, TraceStep, TraceEdge, ExecutionTrace, ExecutionResult, Source, ResolvedSource, SourceKind, SourceResolutionMap, WorkflowInputs, WorkflowInputField, WorkflowInputType, InputValidationError, InputValidationResult, Evaluator, EvaluatorRule, EvalResult, EvaluatorKind, NodeRequires, NodeRetry, NodeToolFilter, OutputMatch, NodeSources, EvalPolicy, RequiresOnFail, NodeOnFail, McpTransport, WorkflowType, SkillHarnessKey, NodeAccess, NodePermissions, NodePermissionsSpec, SafeOutputType, SafeOutputDeclaration, SafeOutputsPolicy, SafeOutputReceipt, SafeOutputPin, AuthorAssociation, } from "./types.js";
 export { WORKFLOW_INPUT_TYPES } from "./types.js";
 export { EVALUATOR_KINDS, EVAL_POLICIES, REQUIRES_ON_FAIL, NODE_ON_FAIL, MCP_TRANSPORTS, SKILL_CATEGORIES, SKILL_HARNESSES, SKILL_ID_PATTERN, SKILL_ID_MAX_LENGTH, isValidSkillId, NODE_ACCESS, TOOL_CLASSES, SAFE_OUTPUT_TYPES, SAFE_OUTPUT_APPLIERS, AUTHOR_ASSOCIATIONS, } from "./types.js";
 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";
@@ -43,6 +45,8 @@ export type { SkillValidationResult } from "./skills/index.js";
 export { loadCustomSkills, discoverSkills, configuredSkills } from "./skills/custom-loader.js";
 export { workflowZ, nodeZ, edgeZ, skillZ, mcpServerConfigZ, skillDefinitionZ, sourceZ, workflowInputsZ, parseWorkflow, validateWorkflow, workflowJsonSchema, skillJsonSchema, } from "./schema.js";
 export type { WorkflowError } from "./schema.js";
+export { isWhenExpression, whenLabel, parseExpression, evaluateExpression, checkExpression, ExpressionSyntaxError, } from "./when.js";
+export type { ExprNode, ExpressionScope, ExpressionResult } from "./when.js";
 export { loadAndValidateWorkflow, validateParsed } from "./loader.js";
 export type { LoaderResult, LoaderError, LoaderOptions } from "./loader.js";
 export { CURRENT_SPEC_VERSION, MIGRATIONS, migrateWorkflow } from "./migrations.js";

package/dist/index.js

@@ -27,6 +27,8 @@ export { EVALUATOR_KINDS, EVAL_POLICIES, REQUIRES_ON_FAIL, NODE_ON_FAIL, MCP_TRA
 export { consoleLogger } from "./types.js";
 // Executor
 export { execute, RouteEvaluationError } from "./executor.js";
+// Decision models, shadow mode (#357)
+export { systemOneProvider, DecideError, gateVerdict, DECIDER_MIN_CONFIDENCE, DECIDER_MIN_MARGIN } from "./decider.js";
 // Least-privilege nodes and safe outputs (#365)
 export { BudgetGuard, describeOverrun, minLimits, toLimits } from "./budget.js";
 export { resolveNodePermissions, buildNodePolicy } from "./node-policy.js";
@@ -43,6 +45,8 @@ export { github, linear, slack, sentry, datadog, notification, supabase, builtin
 export { loadCustomSkills, discoverSkills, configuredSkills } from "./skills/custom-loader.js";
 // Schema & validation
 export { workflowZ, nodeZ, edgeZ, skillZ, mcpServerConfigZ, skillDefinitionZ, sourceZ, workflowInputsZ, parseWorkflow, validateWorkflow, workflowJsonSchema, skillJsonSchema, } from "./schema.js";
+// Deterministic `when` expressions (#461). Pure, browser-safe.
+export { isWhenExpression, whenLabel, parseExpression, evaluateExpression, checkExpression, ExpressionSyntaxError, } from "./when.js";
 // Loader — canonical read → parse → structural-validate pipeline (the path
 // the CLI uses for `workflow run`, `workflow validate`, and `publish`).
 // Node-only: loader.ts imports `node:fs`, so this is NOT mirrored in browser.ts.

package/dist/mermaid.js

@@ -9,6 +9,7 @@
  * (current/success/failed/skipped) and optional execution trace
  * to highlight which edges were taken and show loop iterations.
  */
+import { whenLabel } from "./when.js";
 /**
  * Convert a Workflow to a Mermaid flowchart diagram string.
  *
@@ -102,8 +103,9 @@ export function toMermaid(workflow, options = {}) {
         const takenCount = edgeTakenCounts.get(key) ?? 0;
         // Build label parts
         const labelParts = [];
-        if (edge.when)
-            labelParts.push(edge.when);
+        const when = whenLabel(edge.when);
+        if (when)
+            labelParts.push(when);
         if (edge.max_iterations)
             labelParts.push(`max ${edge.max_iterations}x`);
         // Show how many times this edge was actually followed