@sweny-ai/core 0.1.176 → 0.1.178

package/dist/skills/github.js

@@ -4,11 +4,6 @@
  * Replaces: source-control/github.ts + issue-tracking/github-issues.ts
  * ~800 lines → ~120 lines
  */
-let branchPusher;
-/** Register (or clear, with `undefined`) the sweny-side branch pusher. */
-export function setBranchPusher(fn) {
-    branchPusher = fn;
-}
 class GitHubApiError extends Error {
     status;
     body;
@@ -19,8 +14,28 @@ class GitHubApiError extends Error {
         this.body = body;
     }
 }
+/**
+ * The REST base: `ctx.githubApiUrl` (the operator's GITHUB_API_URL, for GHES)
+ * or https://api.github.com. Only a plain https URL: no credentials, query or
+ * fragment, since the token goes to it.
+ */
+export function githubApiBase(apiUrl) {
+    if (!apiUrl)
+        return "https://api.github.com";
+    let u;
+    try {
+        u = new URL(apiUrl);
+    }
+    catch {
+        throw new Error(`[GitHub] GITHUB_API_URL is not a URL`);
+    }
+    if (u.protocol !== "https:" || u.username || u.password || u.search || u.hash) {
+        throw new Error(`[GitHub] GITHUB_API_URL is not a plain https URL`);
+    }
+    return `${u.origin}${u.pathname.replace(/\/+$/, "")}`;
+}
 async function gh(path, ctx, init) {
-    const res = await fetch(`https://api.github.com${path}`, {
+    const res = await fetch(`${githubApiBase(ctx.githubApiUrl)}${path}`, {
         ...init,
         headers: {
             Authorization: `token ${ctx.config.GITHUB_TOKEN}`,
@@ -34,6 +49,49 @@ async function gh(path, ctx, init) {
         throw new GitHubApiError(res.status, await res.text());
     return res.json();
 }
+/**
+ * Whether sweny may push the PR's head branch, from the API (#498). The agent
+ * names head and base, so head could be an existing integration branch
+ * ("release") that is neither base nor default. A head that does not exist
+ * remotely is pushed with an empty lease (it must still not exist). One that
+ * exists is pushed only when it is unprotected and already has an open PR from
+ * this repo into `base`, leased on the sha the API returned. Any API failure
+ * means no push.
+ */
+export async function headPushLease(repo, head, base, ctx) {
+    const branch = head.replace(/^refs\/heads\//, "");
+    const target = base.replace(/^refs\/heads\//, "");
+    const seg = branch.split("/").map(encodeURIComponent).join("/");
+    let info;
+    try {
+        info = (await gh(`/repos/${repo}/branches/${seg}`, ctx));
+    }
+    catch (err) {
+        if (err instanceof GitHubApiError && err.status === 404)
+            return { remoteSha: "" };
+        return { skip: `cannot check head ${branch} on ${repo}: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    const sha = info?.commit?.sha;
+    if (typeof sha !== "string" || !/^[0-9a-f]{40}([0-9a-f]{24})?$/.test(sha)) {
+        return { skip: `cannot check head ${branch} on ${repo}: no branch sha in the API answer` };
+    }
+    if (info.protected !== false)
+        return { skip: `head ${branch} exists on ${repo} and is protected` };
+    const owner = repo.split("/")[0];
+    let open;
+    try {
+        open = await gh(`/repos/${repo}/pulls?head=${encodeURIComponent(`${owner}:${branch}`)}&base=${encodeURIComponent(target)}&state=open&per_page=1`, ctx);
+    }
+    catch (err) {
+        return {
+            skip: `cannot check open PRs for ${branch} on ${repo}: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    if (!Array.isArray(open) || open.length === 0) {
+        return { skip: `head ${branch} already exists on ${repo} with no open PR into ${target}` };
+    }
+    return { remoteSha: sha };
+}
 function isAlreadyExistsError(err) {
     if (!(err instanceof GitHubApiError) || err.status !== 422)
         return false;
@@ -187,15 +245,33 @@ export const github = {
                 // recommended `persist-credentials: false` checkout still ships the
                 // branch and the agent never holds a write token. Skipped unless the
                 // branch exists locally and origin is this repo; never forced.
-                if (branchPusher) {
-                    const push = await branchPusher({
-                        repo: input.repo,
-                        head: input.head,
-                        base: input.base ?? "main",
-                        token: ctx.config.GITHUB_TOKEN,
-                    });
-                    if (push.pushed)
-                        ctx.logger?.info?.(`  github_create_pr: pushed ${input.head} to origin`);
+                if (ctx.pushBranch) {
+                    // The default branch comes from the API, not the agent-written
+                    // checkout's origin/HEAD. Unknown means no push.
+                    let defaultBranch;
+                    try {
+                        const meta = (await gh(`/repos/${input.repo}`, ctx));
+                        if (typeof meta?.default_branch === "string")
+                            defaultBranch = meta.default_branch;
+                    }
+                    catch {
+                        // The pusher refuses without it; the PR request below reports the API error.
+                    }
+                    const lease = await headPushLease(input.repo, input.head, input.base ?? "main", ctx);
+                    const push = "skip" in lease
+                        ? { pushed: false, attempted: false, reason: lease.skip }
+                        : await ctx.pushBranch({
+                            repo: input.repo,
+                            head: input.head,
+                            base: input.base ?? "main",
+                            ...(defaultBranch ? { defaultBranch } : {}),
+                            remoteSha: lease.remoteSha,
+                            token: ctx.config.GITHUB_TOKEN,
+                        });
+                    if ("skip" in lease)
+                        ctx.logger?.warn?.(`  github_create_pr: not pushing: ${lease.skip}`);
+                    else if (push.pushed)
+                        ctx.logger?.info?.(`  github_create_pr: pushed ${input.head} to ${input.repo}`);
                     else if (push.attempted)
                         ctx.logger?.warn?.(`  github_create_pr: ${push.reason}; requesting the PR anyway`);
                     else

package/dist/startup-env.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The process environment as it was before sweny read any workspace file.
+ *
+ * The workspace is agent-writable, and its `.env` (cli/config-file.ts
+ * `loadDotenv`) may set any variable the real environment left unset. The
+ * privileged git push (skills/git-push.ts) must not take its PATH, proxy or CA
+ * settings, or the server it sends the token to, from a value the workspace
+ * introduced. This module is imported by config-file.ts, so the snapshot is
+ * taken when the module graph loads, before `loadDotenv()` runs.
+ *
+ * Node only.
+ */
+/** The environment captured at process startup, before any workspace file was read. */
+export declare function startupEnv(): Readonly<NodeJS.ProcessEnv>;
+/**
+ * The temp dir from the startup env. `os.tmpdir()` reads TMPDIR at call time,
+ * which a workspace `.env` can set; this never moves after startup.
+ */
+export declare function startupTmpdir(): string;
+/** Record that a workspace file (`.env`) set `key` in `process.env`. */
+export declare function markWorkspaceEnv(key: string): void;
+/** Test seam: forget that a workspace file set `key`. */
+export declare function unmarkWorkspaceEnv(key: string): void;
+/**
+ * The value of `key` the privileged path may use. From `process.env` itself
+ * (the CLI's run env) it is always the startup value. From a caller-built env
+ * it is the caller's value, unless a workspace file introduced the key (a copy
+ * of `process.env` taken after `loadDotenv`), which yields the startup value.
+ */
+export declare function trustedEnvValue(env: NodeJS.ProcessEnv, key: string): string | undefined;

package/dist/startup-env.js

@@ -0,0 +1,48 @@
+/**
+ * The process environment as it was before sweny read any workspace file.
+ *
+ * The workspace is agent-writable, and its `.env` (cli/config-file.ts
+ * `loadDotenv`) may set any variable the real environment left unset. The
+ * privileged git push (skills/git-push.ts) must not take its PATH, proxy or CA
+ * settings, or the server it sends the token to, from a value the workspace
+ * introduced. This module is imported by config-file.ts, so the snapshot is
+ * taken when the module graph loads, before `loadDotenv()` runs.
+ *
+ * Node only.
+ */
+import { tmpdir } from "node:os";
+const SNAPSHOT = Object.freeze({ ...process.env });
+/** os.tmpdir() as resolved from the startup env (TMPDIR, TEMP, TMP), before any workspace file was read. */
+const TMP = tmpdir();
+/** Variable names a workspace file wrote into `process.env` after startup. */
+const introduced = new Set();
+/** The environment captured at process startup, before any workspace file was read. */
+export function startupEnv() {
+    return SNAPSHOT;
+}
+/**
+ * The temp dir from the startup env. `os.tmpdir()` reads TMPDIR at call time,
+ * which a workspace `.env` can set; this never moves after startup.
+ */
+export function startupTmpdir() {
+    return TMP;
+}
+/** Record that a workspace file (`.env`) set `key` in `process.env`. */
+export function markWorkspaceEnv(key) {
+    introduced.add(key);
+}
+/** Test seam: forget that a workspace file set `key`. */
+export function unmarkWorkspaceEnv(key) {
+    introduced.delete(key);
+}
+/**
+ * The value of `key` the privileged path may use. From `process.env` itself
+ * (the CLI's run env) it is always the startup value. From a caller-built env
+ * it is the caller's value, unless a workspace file introduced the key (a copy
+ * of `process.env` taken after `loadDotenv`), which yields the startup value.
+ */
+export function trustedEnvValue(env, key) {
+    if (env === process.env || introduced.has(key))
+        return SNAPSHOT[key];
+    return env[key];
+}

package/dist/types.d.ts

@@ -12,7 +12,43 @@ export interface ToolContext {
     config: Record<string, string>;
     /** Structured logger */
     logger: Logger;
-}
+    /** The run's working directory (`ExecuteOptions.cwd`, else `process.cwd()`). */
+    cwd?: string;
+    /**
+     * A staged or dry run: no side effects. The executor refuses every
+     * non-`read` tool before its handler runs.
+     */
+    staged?: boolean;
+    /**
+     * Pushes a PR's head branch from the sweny process (#473), bound to this
+     * run's checkout. Set by the Node executor; absent in the browser build,
+     * where `github_create_pr` only calls the API.
+     */
+    pushBranch?: BranchPusher;
+    /**
+     * The operator's GITHUB_API_URL (GHES), read through the startup env
+     * snapshot by the Node executor. Absent means https://api.github.com.
+     */
+    githubApiUrl?: string;
+}
+/** The sweny-side head-branch push behind `github_create_pr` (#473). Never throws. */
+export type BranchPusher = (opts: {
+    repo: string;
+    head: string;
+    base: string;
+    /** The repo's default branch from the GitHub API; without it nothing is pushed. */
+    defaultBranch?: string;
+    /**
+     * The head branch's sha on the remote when it was checked through the API,
+     * or "" when it did not exist. The push leases on it. Without it nothing is pushed.
+     */
+    remoteSha?: string;
+    token?: string;
+}) => Promise<{
+    pushed: boolean;
+    attempted: boolean;
+    reason?: string;
+}>;
 /**
  * Side-effect class of a tool. `"read"` only reads. `"write"` can change
  * something outside the run: create, update, delete, post, send, invoke.
@@ -382,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
@@ -519,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;
 }
@@ -533,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;
@@ -562,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;
     /**
@@ -765,12 +834,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 {
@@ -780,8 +856,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",
     ];