@sweny-ai/core 0.1.177 → 0.1.179

package/dist/schema.js

@@ -7,7 +7,7 @@
  * parsing untrusted input (JSON/YAML import, Studio editor).
  */
 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 { AUTHOR_ASSOCIATIONS, CONTEXT_MODES, DECIDER_CONFIDENCE_FLOOR, DECIDER_MARGIN_FLOOR, DECIDER_MIN_CONFIDENCE, DECIDER_MIN_MARGIN, DECIDER_MODE_REMOVED, DECIDER_PROVIDER_MOVED, EVALUATOR_KINDS, EVAL_POLICIES, MCP_TRANSPORTS, NODE_ACCESS, NODE_ON_FAIL, REQUIRES_ON_FAIL, ROUTE_BY, 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 { resolveNodePermissions } from "./node-policy.js";
 import { workflowInputsZ, WORKFLOW_INPUT_TYPES } from "./inputs.js";
@@ -280,26 +280,22 @@ export const budgetZ = z
     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.
+ * Decision model thresholds (#357) for the nodes that set `route_by:
+ * decider`. Thresholds may be raised, and lowered no further than the floors.
+ * The provider (endpoint, model, key) comes only from operator config.
+ *
+ * Shapes from the shadow-mode release fail with an explanation instead of
+ * silently changing routing: `mode` ({@link DECIDER_MODE_REMOVED}) and
+ * `provider` ({@link DECIDER_PROVIDER_MOVED}).
  */
 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(),
+    mode: z.custom(() => false, { message: DECIDER_MODE_REMOVED }).optional(),
+    provider: z.custom(() => false, { message: DECIDER_PROVIDER_MOVED }).optional(),
+    min_confidence: z.number().min(DECIDER_CONFIDENCE_FLOOR).max(1).optional(),
+    min_margin: z.number().min(DECIDER_MARGIN_FLOOR).max(1).optional(),
 })
-    .strict()
-    .refine((d) => d.mode === "off" || d.provider !== undefined, {
-    message: "decider.provider is required when mode is shadow",
-});
+    .strict();
 /** One typed write intent a node may emit (#365). */
 export const safeOutputDeclarationZ = z
     .object({
@@ -342,6 +338,7 @@ export const nodeZ = z
     tools: nodeToolsZ.optional(),
     fail_soft: z.boolean().optional(),
     on_fail: z.enum(NODE_ON_FAIL).optional(),
+    route_by: z.enum(ROUTE_BY).optional(),
     permissions: nodePermissionsZ.optional(),
     outputs: z.array(safeOutputDeclarationZ).min(1).optional(),
     rules: nodeSourcesZ.optional(),
@@ -361,6 +358,7 @@ export const edgeZ = z
     // 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(),
+    description: z.string().min(1).optional(),
     max_iterations: z.number().int().min(1).max(EDGE_MAX_ITERATIONS_CEILING).optional(),
 })
     .strict();
@@ -478,6 +476,22 @@ export function validateWorkflow(workflow, knownSkills) {
         else
             m.set(k, [v]);
     };
+    // One edge per (from, to) pair (#357). A route picks a target node, so two
+    // edges to the same target would make their conditions ambiguous (which
+    // one's max_iterations counts, which one's condition the router saw). Write
+    // one edge whose condition covers both cases instead.
+    const seenPairs = new Set();
+    for (const edge of workflow.edges) {
+        const key = JSON.stringify([edge.from, edge.to]);
+        if (seenPairs.has(key)) {
+            errors.push({
+                code: "DUPLICATE_EDGE",
+                message: `More than one edge from "${edge.from}" to "${edge.to}"; merge them into one edge (combine the conditions with OR)`,
+                nodeId: edge.from,
+            });
+        }
+        seenPairs.add(key);
+    }
     // Edge targets must exist
     for (const edge of workflow.edges) {
         if (!nodeIds.has(edge.from)) {
@@ -1000,28 +1014,24 @@ export const workflowJsonSchema = {
         },
         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.",
+            description: "Decision model thresholds for the nodes that set route_by: decider. The provider (URL, model, key) comes only from operator config (.sweny.yml or SWENY_DECIDER_* env), never from the workflow; 'provider' and the removed 'mode' key are rejected.",
             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." },
-                    },
+                min_confidence: {
+                    type: "number",
+                    minimum: DECIDER_CONFIDENCE_FLOOR,
+                    maximum: 1,
+                    default: DECIDER_MIN_CONFIDENCE,
+                    description: "Accept the decider's answer only at or above this confidence.",
+                },
+                min_margin: {
+                    type: "number",
+                    minimum: DECIDER_MARGIN_FLOOR,
+                    maximum: 1,
+                    default: DECIDER_MIN_MARGIN,
+                    description: "Accept it only when the top label leads the runner-up by at least this much.",
                 },
             },
-            if: { properties: { mode: { const: "shadow" } } },
-            then: { required: ["provider"] },
         },
         SafeOutput: {
             type: "object",
@@ -1174,7 +1184,7 @@ export const workflowJsonSchema = {
         },
         decider: {
             $ref: "#/$defs/Decider",
-            description: "Decision model for route choices (shadow mode only). Default: off.",
+            description: "Thresholds for the decision model that decides the routes of route_by: decider nodes when confident. Default: 0.85 confidence, 0.2 margin.",
         },
         context_mode: {
             type: "string",
@@ -1335,6 +1345,11 @@ export const workflowJsonSchema = {
                         enum: [...NODE_ON_FAIL],
                         description: "What to do when this node finishes 'failed' (agent-level failure, or an eval failure that exhausted retries and was not softened by fail_soft). 'halt' (default) stops the workflow with the failure surfaced so a broken node never advances down a conditional edge; 'continue' preserves the legacy fall-through where routing proceeds from the failed node. Distinct from requires.on_fail (the pre-condition gate).",
                     },
+                    route_by: {
+                        type: "string",
+                        enum: [...ROUTE_BY],
+                        description: "Who picks this node's natural-language route. 'agent' (default): the agent's route evaluation. 'decider': the operator's decision model first, the agent when it is not confident. Expressions always win over both; put safety conditions in expressions.",
+                    },
                     permissions: {
                         $ref: "#/$defs/Permissions",
                         description: "What this node's agent may do. Absent: read when the node declares outputs, else the workflow's permissions, else write.",
@@ -1456,6 +1471,11 @@ export const workflowJsonSchema = {
                             },
                         ],
                     },
+                    description: {
+                        type: "string",
+                        minLength: 1,
+                        description: "The condition in natural language. For an { expr } edge, what the next rung reads when the expression cannot be evaluated because a field it needs is missing or invalid.",
+                    },
                     max_iterations: {
                         type: "integer",
                         minimum: 1,

package/dist/skills/github.js

@@ -181,6 +181,45 @@ export const github = {
                 return gh(`/search/issues?q=${encodeURIComponent(q)}&per_page=20`, ctx);
             },
         },
+        {
+            name: "github_list_issues",
+            access: "read",
+            description: "List a repository's most recently created issues (open and closed), newest first",
+            input_schema: {
+                type: "object",
+                properties: {
+                    repo: { type: "string", description: "owner/repo" },
+                    per_page: { type: "number", description: "How many per page (max 100, default 30)" },
+                    page: { type: "number", description: "Page number, from 1 (default 1)" },
+                },
+                required: ["repo"],
+            },
+            handler: async (input, ctx) => {
+                const n = Math.min(100, Math.max(1, Math.floor(input.per_page ?? 30)));
+                const page = Math.max(1, Math.floor(input.page ?? 1));
+                return gh(`/repos/${input.repo}/issues?state=all&sort=created&direction=desc&per_page=${n}&page=${page}`, ctx);
+            },
+        },
+        {
+            name: "github_list_issue_comments",
+            access: "read",
+            description: "List comments on an issue or pull request, optionally only those updated since a time",
+            input_schema: {
+                type: "object",
+                properties: {
+                    repo: { type: "string", description: "owner/repo" },
+                    issue_number: { type: "number", description: "Issue or PR number" },
+                    since: { type: "string", description: "ISO 8601 time: only comments updated at or after it" },
+                    page: { type: "number", description: "Page of 100 comments, oldest first, from 1 (default 1)" },
+                },
+                required: ["repo", "issue_number"],
+            },
+            handler: async (input, ctx) => {
+                const since = input.since ? `&since=${encodeURIComponent(input.since)}` : "";
+                const page = Math.max(1, Math.floor(input.page ?? 1));
+                return gh(`/repos/${input.repo}/issues/${Number(input.issue_number)}/comments?per_page=100&page=${page}${since}`, ctx);
+            },
+        },
         {
             name: "github_create_issue",
             access: "write",

package/dist/types.d.ts

@@ -418,6 +418,13 @@ export interface Node {
      * Distinct from `requires.on_fail`, which is the pre-condition gate.
      */
     on_fail?: NodeOnFail;
+    /**
+     * Who picks this node's natural-language route (#357). `agent` (default):
+     * the agent's route evaluation. `decider`: the operator's decision model is
+     * asked first and its confident answer is the route; otherwise the agent.
+     * Expressions always win over both. Safety conditions belong in expressions.
+     */
+    route_by?: RouteBy;
     /**
      * What this node's agent may do (#365). `read` runs the node read-only:
      * only `access: "read"` skill tools, no external skill MCP servers, no
@@ -555,6 +562,12 @@ export interface Edge {
      * evaluated by sweny with no model call.
      */
     when?: EdgeWhen;
+    /**
+     * The condition in natural language (#357). For an `{ expr }` edge it is
+     * what the next rung (decider or agent) reads when the expression cannot be
+     * evaluated because a field it needs is missing or invalid.
+     */
+    description?: string;
     /** Max times this edge can be followed (enables retry loops). Default: unlimited. */
     max_iterations?: number;
 }
@@ -569,6 +582,25 @@ export interface Edge {
  */
 export declare const WORKFLOW_TYPES: readonly ["pr_review", "e2e_test", "content_generation", "monitor", "data_sync", "generic"];
 export type WorkflowType = (typeof WORKFLOW_TYPES)[number];
+/**
+ * Decision model gates (#357). Shared by the Zod schema, the JSON schema and
+ * the executor; kept here so schema-only (browser) consumers need no Node code.
+ */
+/** Default: accept a decider answer only at or above this confidence. */
+export declare const DECIDER_MIN_CONFIDENCE = 0.85;
+/** Default: ... and only when the top label leads the runner-up by at least this much. */
+export declare const DECIDER_MIN_MARGIN = 0.2;
+/** A workflow may lower `min_confidence` to this and no further. */
+export declare const DECIDER_CONFIDENCE_FLOOR = 0.7;
+/** A workflow may lower `min_margin` to this and no further. */
+export declare const DECIDER_MARGIN_FLOOR = 0.1;
+/** `route_by` values: who picks a node's natural-language route. */
+export declare const ROUTE_BY: readonly ["agent", "decider"];
+export type RouteBy = (typeof ROUTE_BY)[number];
+/** Load error for a workflow that still declares the removed `decider.mode`. */
+export declare const DECIDER_MODE_REMOVED: string;
+/** Load error for a workflow that declares the provider itself. */
+export declare const DECIDER_PROVIDER_MOVED: string;
 /** A complete workflow definition. Pure data, fully serializable. */
 export interface Workflow {
     id: string;
@@ -598,8 +630,9 @@ export interface Workflow {
      */
     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.
+     * Decision model thresholds (#357) for the nodes that set `route_by:
+     * decider`. Never looser than the floors. The provider itself comes only
+     * from operator config, never from the workflow.
      */
     decider?: DeciderConfig;
     /**
@@ -694,6 +727,12 @@ export interface NodeResult {
      * Claude Code harness only; absent for harnesses that do not report it.
      */
     policy?: NodePolicyFacts;
+    /**
+     * The agent ran inside an enforced sandbox that keeps it out of the sweny
+     * state dir (run keys and journals). Set by the harness adapters; absent
+     * (treated as not contained) for anything that does not report it.
+     */
+    contained?: boolean;
     /** Safe outputs (#365): what the write stage did with each intent. Absent when the node declares none. */
     outputs?: SafeOutputReceipt[];
     /**
@@ -801,12 +840,19 @@ export interface TraceStep {
     /** 0-indexed retry attempt for this iteration. Absent when no retry fired. */
     retryAttempt?: number;
 }
+/**
+ * Which rung of the route ladder chose a conditional route (#357): a `when`
+ * expression, the decision model, or the agent's route evaluation.
+ */
+export type RouteRung = "expr" | "decider" | "agent";
 /** A routing decision between nodes */
 export interface TraceEdge {
     from: string;
     to: string;
     /** Why this edge was chosen (condition text or "only path") */
     reason: string;
+    /** Who chose it. Absent for an unconditional edge (nothing to decide). */
+    rung?: RouteRung;
 }
 /** Full execution trace — ordered steps + edges taken */
 export interface ExecutionTrace {
@@ -816,8 +862,14 @@ 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. */
+    /** One record per decision-model consultation (#357). Metadata only. Absent when no decider runs. */
     decisions?: DeciderRecord[];
+    /**
+     * Why the decider did not run for some or all of this run's `route_by:
+     * decider` nodes (#357): missing operator config, `--no-decider`, a rejected
+     * URL, an open breaker or a spent call cap. Absent when nothing turned it off.
+     */
+    deciderOff?: string;
 }
 /** Result of execute() — final node results + full execution trace */
 export interface ExecutionResult {

package/dist/types.js

@@ -117,6 +117,28 @@ export const WORKFLOW_TYPES = [
     "data_sync",
     "generic",
 ];
+/**
+ * Decision model gates (#357). Shared by the Zod schema, the JSON schema and
+ * the executor; kept here so schema-only (browser) consumers need no Node code.
+ */
+/** Default: accept a decider answer only at or above this confidence. */
+export const DECIDER_MIN_CONFIDENCE = 0.85;
+/** Default: ... and only when the top label leads the runner-up by at least this much. */
+export const DECIDER_MIN_MARGIN = 0.2;
+/** A workflow may lower `min_confidence` to this and no further. */
+export const DECIDER_CONFIDENCE_FLOOR = 0.7;
+/** A workflow may lower `min_margin` to this and no further. */
+export const DECIDER_MARGIN_FLOOR = 0.1;
+/** `route_by` values: who picks a node's natural-language route. */
+export const ROUTE_BY = ["agent", "decider"];
+/** Load error for a workflow that still declares the removed `decider.mode`. */
+export const DECIDER_MODE_REMOVED = "decider.mode was removed with shadow mode. A decider now decides the routes of nodes that set `route_by: decider`, " +
+    "using the provider from operator config (.sweny.yml `decider:` or SWENY_DECIDER_URL and SWENY_DECIDER_MODEL). " +
+    "Delete the mode line; to keep routing with the agent only, delete the whole decider block.";
+/** Load error for a workflow that declares the provider itself. */
+export const DECIDER_PROVIDER_MOVED = "decider.provider is not allowed in a workflow: the endpoint and key come only from operator config " +
+    "(.sweny.yml `decider: { url, model }`, or SWENY_DECIDER_URL and SWENY_DECIDER_MODEL; the key only from SWENY_DECIDER_API_KEY). " +
+    "Move it there. A workflow may only set min_confidence and min_margin here, and `route_by: decider` on nodes.";
 export const consoleLogger = {
     info: (msg, data) => console.log(`[info] ${msg}`, data ?? ""),
     warn: (msg, data) => console.warn(`[warn] ${msg}`, data ?? ""),

package/dist/when.d.ts

@@ -95,7 +95,14 @@ export interface ExpressionResult {
  * 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;
+export declare function evaluateExpression(ast: ExprNode, scope: ExpressionScope, opts?: {
+    /**
+     * `node.field` paths whose value broke its declared type or enum. Any
+     * reference to one (or below it), `exists` included, is a problem: the
+     * value is unknown, which is neither present nor absent.
+     */
+    invalid?: ReadonlySet<string>;
+}): ExpressionResult;
 /**
  * Check an expression against the workflow it routes. Returns one message per
  * problem, empty when the expression is valid:

package/dist/when.js

@@ -324,8 +324,14 @@ function lookup(scope, segments) {
  * Evaluate a parsed expression against node outputs. Never throws: a missing
  * field or a type mismatch yields `{ value: false, problem }`.
  */
-export function evaluateExpression(ast, scope) {
+export function evaluateExpression(ast, scope, opts = {}) {
+    const checkInvalid = (path) => {
+        if (opts.invalid && path.length >= 2 && opts.invalid.has(`${path[0]}.${path[1]}`)) {
+            throw new Abort(`field '${path[0]}.${path[1]}' does not match its declared type`);
+        }
+    };
     const read = (path) => {
+        checkInvalid(path);
         const v = lookup(scope, path);
         if (v === undefined)
             throw new Abort(`field '${path.join(".")}' is missing`);
@@ -345,6 +351,7 @@ export function evaluateExpression(ast, scope) {
             case "path":
                 return read(node.segments);
             case "exists": {
+                checkInvalid(node.path.segments);
                 const v = lookup(scope, node.path.segments);
                 return v !== undefined && v !== null;
             }

package/dist/workflow-builder.js

@@ -56,7 +56,9 @@ export function buildSystemPrompt(skills, existingWorkflow) {
         "- Use snake_case for node IDs (e.g. gather_errors, create_ticket)",
         "- Set `entry` to the first node in the flow",
         "- Only reference skill IDs from the list above in node `skills` arrays",
-        "- Use natural language for edge `when` conditions",
+        '- Prefer `when: { expr: "..." }` expressions for edge conditions: declare the deciding values as enum, number, integer or boolean properties in the source node\'s `output`, then compare them (e.g. `{ "expr": "triage.severity in [\'high\', \'critical\']" }`). Expressions route with no model call and always the same way',
+        "- Use a natural-language `when` only for a fuzzy condition no declared field can express",
+        "- Put safety conditions (anything that gates a write, a PR or an issue) in expressions, never in natural language",
         "- Every node must be reachable from the entry node",
         "- Return ONLY the workflow JSON object — no markdown fences, no explanation",
     ];