@sweny-ai/core 0.1.161 → 0.1.163

package/dist/schema.js

@@ -10,6 +10,9 @@ import { z } from "zod";
 import { AUTHOR_ASSOCIATIONS, CONTEXT_MODES, EVALUATOR_KINDS, EVAL_POLICIES, MCP_TRANSPORTS, NODE_ACCESS, NODE_ON_FAIL, REQUIRES_ON_FAIL, SAFE_OUTPUT_APPLIERS, SAFE_OUTPUT_EXPIRES_PATTERN, SAFE_OUTPUT_MAX_CEILING, SAFE_OUTPUT_STATES, SAFE_OUTPUT_TYPES, SKILL_CATEGORIES, SKILL_ID_MAX_LENGTH, SKILL_ID_PATTERN, TOOL_ACCESS, TOOL_CLASSES, WORKFLOW_TYPES, } from "./types.js";
 import { sourceZ } from "./sources.js";
 import { workflowInputsZ, WORKFLOW_INPUT_TYPES } from "./inputs.js";
+import { checkExpression, isWhenExpression, WHEN_EXPR_MAX_LENGTH } from "./when.js";
+// Studio and other schema-only consumers label edges without importing the root entry.
+export { isWhenExpression, whenLabel } from "./when.js";
 export { sourceZ };
 export { workflowInputsZ };
 // ─── Zod Schemas ─────────────────────────────────────────────────
@@ -275,6 +278,27 @@ export const budgetZ = z
     .refine((b) => b.tokens !== undefined || b.cost_usd !== undefined, {
     message: "budget must declare at least one of tokens, cost_usd",
 });
+/**
+ * Decision model for route choices (#357). `shadow` needs a provider; the
+ * state only ever goes to that `base_url`, there is no fallback. The key is
+ * named by env var, never inlined.
+ */
+export const deciderZ = z
+    .object({
+    mode: z.enum(["off", "shadow"]),
+    provider: z
+        .object({
+        base_url: z.string().url(),
+        model: z.string().min(1),
+        api_key_env: z.string().min(1).optional(),
+    })
+        .strict()
+        .optional(),
+})
+    .strict()
+    .refine((d) => d.mode === "off" || d.provider !== undefined, {
+    message: "decider.provider is required when mode is shadow",
+});
 /** One typed write intent a node may emit (#365). */
 export const safeOutputDeclarationZ = z
     .object({
@@ -330,7 +354,9 @@ export const edgeZ = z
     .object({
     from: z.string().min(1),
     to: z.string().min(1),
-    when: z.string().optional(),
+    // Natural language (the harness picks the edge) or `{ expr }`, a
+    // deterministic expression sweny evaluates itself (#461). One or the other.
+    when: z.union([z.string(), z.object({ expr: z.string().min(1).max(WHEN_EXPR_MAX_LENGTH) }).strict()]).optional(),
     max_iterations: z.number().int().min(1).max(EDGE_MAX_ITERATIONS_CEILING).optional(),
 })
     .strict();
@@ -372,6 +398,7 @@ export const workflowZ = z.object({
     model: z.string().min(1).optional(),
     judge_budget: z.number().int().min(0).optional(),
     budget: budgetZ.optional(),
+    decider: deciderZ.optional(),
     context_mode: z.enum(CONTEXT_MODES).optional(),
     inputs: workflowInputsZ.optional(),
     permissions: nodePermissionsZ.optional(),
@@ -507,6 +534,68 @@ export function validateWorkflow(workflow, knownSkills) {
             });
         }
     }
+    // Deterministic `when` expressions (#461). Every path must name a declared
+    // output field of the edge's source node or one of its ancestors, so a typo
+    // is a load error rather than a branch that never fires. A node routes on
+    // expressions or on natural language, never both: a mixed node would hand
+    // the expression edges to the model and lose the determinism the author
+    // asked for.
+    const ancestorsCache = new Map();
+    const inAll = new Map();
+    for (const [from, tos] of outAll)
+        for (const to of tos)
+            push(inAll, to, from);
+    const ancestorsOf = (id) => {
+        let seen = ancestorsCache.get(id);
+        if (seen)
+            return seen;
+        seen = new Set([id]);
+        const queue = [id];
+        for (let i = 0; i < queue.length; i++) {
+            for (const from of inAll.get(queue[i]) ?? []) {
+                if (!seen.has(from)) {
+                    seen.add(from);
+                    queue.push(from);
+                }
+            }
+        }
+        ancestorsCache.set(id, seen);
+        return seen;
+    };
+    const outputs = Object.fromEntries(Object.entries(workflow.nodes).map(([id, n]) => [id, n.output]));
+    const conditionKinds = new Map();
+    for (const edge of workflow.edges) {
+        if (!nodeIds.has(edge.from) || !edge.when)
+            continue;
+        const kinds = conditionKinds.get(edge.from) ?? { expr: 0, nl: 0 };
+        conditionKinds.set(edge.from, kinds);
+        if (!isWhenExpression(edge.when)) {
+            kinds.nl++;
+            continue;
+        }
+        kinds.expr++;
+        const problems = checkExpression(edge.when.expr, {
+            from: edge.from,
+            ancestors: ancestorsOf(edge.from),
+            outputs,
+        });
+        for (const problem of problems) {
+            errors.push({
+                code: "INVALID_WHEN_EXPRESSION",
+                message: `Edge "${edge.from}" -> "${edge.to}": ${problem}`,
+                nodeId: edge.from,
+            });
+        }
+    }
+    for (const [from, kinds] of conditionKinds) {
+        if (kinds.expr > 0 && kinds.nl > 0) {
+            errors.push({
+                code: "MIXED_EDGE_CONDITIONS",
+                message: `Node "${from}" mixes expression and natural-language 'when' conditions on its out-edges; use one kind per node (an unconditional default edge is fine with either)`,
+                nodeId: from,
+            });
+        }
+    }
     // Reachability: BFS from entry. Skipped only when the entry is missing
     // (every node would be reported, which is noise). All other diagnostics
     // accumulate so one pass reports every structural problem.
@@ -894,6 +983,31 @@ export const workflowJsonSchema = {
                 cost_usd: { type: "number", exclusiveMinimum: 0, description: "Max reported cost in USD." },
             },
         },
+        Decider: {
+            type: "object",
+            required: ["mode"],
+            additionalProperties: false,
+            description: "Decision model for route choices. 'shadow' asks it alongside the agent and logs whether they agree; the route is always the agent's. The workflow state goes only to provider.base_url, with no fallback.",
+            properties: {
+                mode: { type: "string", enum: ["off", "shadow"] },
+                provider: {
+                    type: "object",
+                    required: ["base_url", "model"],
+                    additionalProperties: false,
+                    properties: {
+                        base_url: {
+                            type: "string",
+                            format: "uri",
+                            description: "Server root serving POST /v1/systemone (Ollama or TypeSafe Jev).",
+                        },
+                        model: { type: "string", minLength: 1 },
+                        api_key_env: { type: "string", minLength: 1, description: "Env var holding the bearer key." },
+                    },
+                },
+            },
+            if: { properties: { mode: { const: "shadow" } } },
+            then: { required: ["provider"] },
+        },
         SafeOutput: {
             type: "object",
             required: ["type"],
@@ -1043,6 +1157,10 @@ export const workflowJsonSchema = {
             $ref: "#/$defs/Budget",
             description: "Spend ceiling for the whole run and for every node. A node's own budget may only narrow it. The CLI's --max-tokens and --max-cost tighten it further.",
         },
+        decider: {
+            $ref: "#/$defs/Decider",
+            description: "Decision model for route choices (shadow mode only). Default: off.",
+        },
         context_mode: {
             type: "string",
             enum: [...CONTEXT_MODES],
@@ -1299,8 +1417,23 @@ export const workflowJsonSchema = {
                     from: { type: "string", minLength: 1 },
                     to: { type: "string", minLength: 1 },
                     when: {
-                        type: "string",
-                        description: "Natural language condition, evaluated at runtime by the workflow's harness.",
+                        description: "Condition for taking this edge. A string is natural language, evaluated at runtime by the workflow's harness. An object { expr } is a deterministic expression over prior nodes' declared output fields, evaluated by sweny with no model call.",
+                        oneOf: [
+                            { type: "string" },
+                            {
+                                type: "object",
+                                required: ["expr"],
+                                additionalProperties: false,
+                                properties: {
+                                    expr: {
+                                        type: "string",
+                                        minLength: 1,
+                                        maxLength: WHEN_EXPR_MAX_LENGTH,
+                                        description: "Boolean expression: == != < <= > >= in, && || !, exists, string/number/boolean/null literals, and node.field paths to declared output fields.",
+                                    },
+                                },
+                            },
+                        ],
                     },
                     max_iterations: {
                         type: "integer",

package/dist/studio.d.ts

@@ -38,7 +38,7 @@
  *    directly to node highlights. node:enter → glow blue,
  *    tool:call → show tool name, node:exit → green/red.
  */
-import type { Workflow, Node, ExecutionEvent, NodeResult, Skill } from "./types.js";
+import type { Workflow, Node, Edge, ExecutionEvent, NodeResult, Skill } from "./types.js";
 export interface FlowNode {
     id: string;
     type: "skillNode";
@@ -74,7 +74,7 @@ export interface FlowEdge {
     /** Array index of this edge in workflow.edges — used for stable lookups. */
     edgeIndex: number;
     data: {
-        when?: string;
+        when?: Edge["when"];
         max_iterations?: number;
         isConditional: boolean;
     };

package/dist/types.d.ts

@@ -4,6 +4,7 @@ export { WORKFLOW_INPUT_TYPES } from "./inputs.js";
 import type { Source as _Source, ResolvedSource as _ResolvedSource } from "./sources.js";
 import type { ToolClass } from "./harness/types.js";
 import type { Budget, BudgetOverrun } from "./budget.js";
+import type { DeciderConfig, DeciderRecord } from "./decider.js";
 export type JSONSchema = Record<string, unknown>;
 /** Context passed to tool handlers at execution time */
 export interface ToolContext {
@@ -489,12 +490,26 @@ export interface NodeToolFilter {
     /** Skill tool names removed from the node (applied after `allow`). */
     deny?: string[];
 }
+/**
+ * A deterministic edge condition (#461): a boolean expression over prior
+ * nodes' declared output fields, evaluated by sweny with no model call.
+ * Grammar and semantics: `when.ts`.
+ */
+export interface WhenExpression {
+    expr: string;
+}
+/** An edge condition: natural language (model-evaluated) or a `{ expr }` expression. */
+export type EdgeWhen = string | WhenExpression;
 /** An edge connecting two nodes */
 export interface Edge {
     from: string;
     to: string;
-    /** Natural language condition, evaluated at runtime by the workflow's harness. */
-    when?: string;
+    /**
+     * Condition for taking this edge. A string is natural language, evaluated at
+     * runtime by the workflow's harness. `{ expr }` is a deterministic expression
+     * evaluated by sweny with no model call.
+     */
+    when?: EdgeWhen;
     /** Max times this edge can be followed (enables retry loops). Default: unlimited. */
     max_iterations?: number;
 }
@@ -537,6 +552,11 @@ export interface Workflow {
      * `budget` may only narrow it. The CLI's `--max-tokens` / `--max-cost` tighten it.
      */
     budget?: Budget;
+    /**
+     * Decision model for route choices (#357). `shadow` asks it alongside the
+     * agent and logs agreement; the route is always the agent's. Default: off.
+     */
+    decider?: DeciderConfig;
     /**
      * What prior results a node's prompt receives (#337). `bounded` (default):
      * only nodes it can depend on (graph ancestors, nodes named by `requires`
@@ -751,6 +771,8 @@ export interface ExecutionTrace {
     edges: TraceEdge[];
     /** Resolved sources keyed by field path (e.g. "nodes.gather.instruction") */
     sources: Record<string, _ResolvedSource>;
+    /** Shadow-mode decider records, one per route decision (#357). Metadata only. Absent when the decider is off. */
+    decisions?: DeciderRecord[];
 }
 /** Result of execute() — final node results + full execution trace */
 export interface ExecutionResult {

package/dist/when.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Deterministic `when` expressions (#461).
+ *
+ * An edge's `when` is either natural language (a model picks the edge at
+ * runtime) or `{ expr: "..." }`, a small boolean expression over prior nodes'
+ * declared output fields that sweny evaluates itself, with no model call.
+ *
+ * Grammar (precedence low to high):
+ *
+ *   expr       := or
+ *   or         := and ( "||" and )*
+ *   and        := unary ( "&&" unary )*
+ *   unary      := "!" unary | comparison
+ *   comparison := operand ( ( "==" | "!=" | "<" | "<=" | ">" | ">=" | "in" ) operand )?
+ *   operand    := literal | list | path | "exists" path | "(" expr ")"
+ *   list       := "[" ( literal ( "," literal )* )? "]"
+ *   literal    := number | 'string' | "string" | true | false | null
+ *   path       := ident ( "." ident )+          (node id, then field, then nested fields)
+ *
+ * Semantics are strict and total. There is no coercion and no truthiness:
+ * `&&`, `||`, `!` and the expression itself need booleans; `<` and friends
+ * need two numbers or two strings; `in` needs a list on the right. A missing
+ * field (undefined, or a node that did not run or did not succeed) or a type
+ * mismatch makes the WHOLE expression false and is reported, so a negation
+ * can never turn a missing field into a silent true. `exists path` is the
+ * one explicit presence test: true when the value is present and not null,
+ * never a warning. `&&` and `||` short-circuit, so `exists a.x && a.x > 0`
+ * is safe.
+ *
+ * Pure module: no I/O, no eval, no Function, browser-safe. Strings in the
+ * routed data are compared as data only; nothing in them is ever parsed.
+ */
+import type { EdgeWhen, JSONSchema, WhenExpression } from "./types.js";
+/** Longest expression source accepted. Routing conditions are short. */
+export declare const WHEN_EXPR_MAX_LENGTH = 2000;
+/** True when an edge `when` is the structured `{ expr }` form. */
+export declare function isWhenExpression(when: unknown): when is WhenExpression;
+/** Human-readable label for a `when`: the NL text or the expression source. */
+export declare function whenLabel(when: EdgeWhen | undefined): string | undefined;
+export type Literal = string | number | boolean | null;
+export type ExprNode = {
+    kind: "literal";
+    value: Literal;
+} | {
+    kind: "list";
+    items: Literal[];
+} | {
+    kind: "path";
+    segments: string[];
+} | {
+    kind: "exists";
+    path: {
+        kind: "path";
+        segments: string[];
+    };
+} | {
+    kind: "not";
+    operand: ExprNode;
+} | {
+    kind: "and" | "or";
+    left: ExprNode;
+    right: ExprNode;
+} | {
+    kind: "cmp";
+    op: CmpOp;
+    left: ExprNode;
+    right: ExprNode;
+};
+export type CmpOp = "==" | "!=" | "<" | "<=" | ">" | ">=" | "in";
+export declare class ExpressionSyntaxError extends Error {
+    readonly position: number;
+    constructor(message: string, position: number);
+}
+/**
+ * Parse an expression source into an AST. Throws `ExpressionSyntaxError` on
+ * any syntax problem, including an empty source, an over-long source, or
+ * nesting deeper than the cap.
+ */
+export declare function parseExpression(src: string): ExprNode;
+/**
+ * Per-node data an expression may read, keyed by node id. A node that did not
+ * run or did not succeed is absent, so every path into it reads as missing.
+ */
+export type ExpressionScope = Record<string, Record<string, unknown> | undefined>;
+export interface ExpressionResult {
+    /** The edge is taken only when this is true. */
+    value: boolean;
+    /**
+     * Why the expression was forced false: a missing field or a type mismatch.
+     * Absent when it evaluated normally (to true or false).
+     */
+    problem?: string;
+}
+/**
+ * Evaluate a parsed expression against node outputs. Never throws: a missing
+ * field or a type mismatch yields `{ value: false, problem }`.
+ */
+export declare function evaluateExpression(ast: ExprNode, scope: ExpressionScope): ExpressionResult;
+/**
+ * Check an expression against the workflow it routes. Returns one message per
+ * problem, empty when the expression is valid:
+ *   - the source must parse;
+ *   - every path's node must be the edge's source or one of its ancestors;
+ *   - that node must declare `output.properties`, and the field (and any
+ *     nested field) must be declared there;
+ *   - a literal compared with a declared field must fit its declared type,
+ *     and a string literal compared with an enum field must be in the enum;
+ *   - a field used where a boolean is needed must be declared boolean.
+ */
+export declare function checkExpression(src: string, ctx: {
+    from: string;
+    ancestors: Set<string>;
+    outputs: Record<string, JSONSchema | undefined>;
+}): string[];