@sweny-ai/core 0.1.75 → 0.1.77

package/dist/executor.js

@@ -15,6 +15,8 @@
 import { consoleLogger } from "./types.js";
 import { resolveSources } from "./source-resolver.js";
 import { evaluateVerify } from "./verify.js";
+import { evaluateRequires } from "./requires.js";
+import { buildRetryPreamble } from "./retry.js";
 /**
  * Execute a workflow from entry to completion.
  *
@@ -96,6 +98,33 @@ export async function execute(workflow, input, options) {
             input,
             ...Object.fromEntries([...results.entries()].map(([k, v]) => [k, v.data])),
         };
+        // Pre-condition gate: evaluate `requires` against the cross-node context
+        // BEFORE invoking the LLM. Failure either marks the node failed (on_fail
+        // default) or skipped (on_fail: "skip") and skips execution entirely.
+        const requiresError = evaluateRequires(node.requires, context);
+        if (requiresError) {
+            const onFail = node.requires?.on_fail ?? "fail";
+            const result = onFail === "skip"
+                ? {
+                    status: "skipped",
+                    data: { skipped_reason: requiresError.replace(/^requires failed:/, "requires not met:") },
+                    toolCalls: [],
+                }
+                : {
+                    status: "failed",
+                    data: { error: requiresError },
+                    toolCalls: [],
+                };
+            results.set(currentId, result);
+            trace.steps.push({ node: currentId, status: result.status, iteration });
+            safeObserve(observer, { type: "node:exit", node: currentId, result }, logger);
+            logger.warn(`  requires ${onFail === "skip" ? "skipped" : "failed"}: ${requiresError}`, { node: currentId });
+            // 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);
+            currentId = next;
+            continue;
+        }
         // Wrap tool handlers to emit events + inject context
         const trackedTools = tools.map((t) => ({
             ...t,
@@ -111,56 +140,59 @@ export async function execute(workflow, input, options) {
         const effectiveRules = assembleCascaded("rules", currentId, workflow.nodes[currentId], inputRules.length, (workflow.rules ?? []).length, resolvedSources);
         const effectiveContext = assembleCascaded("context", currentId, workflow.nodes[currentId], inputContext.length, (workflow.context ?? []).length, resolvedSources);
         const instruction = buildNodeInstruction(resolvedInstruction, effectiveRules, effectiveContext, input, skillInstructions);
-        // Run Claude on this node
-        const result = await claude.run({
-            instruction,
-            context,
-            tools: trackedTools,
-            outputSchema: node.output,
-            maxTurns: node.max_turns,
-            onProgress: (message) => {
-                safeObserve(observer, { type: "node:progress", node: currentId, message }, logger);
-            },
-        });
-        // Machine-checked post-condition. Enforced AFTER the LLM finishes so that
-        // a model claiming success cannot bypass side-effect requirements (e.g.
-        // reporting "issue created" when no `linear_create_issue` call was made).
-        // Skipped entirely when the node already failed — the node's own error is
-        // the root cause and verify would just add noise.
-        if (result.status === "success") {
+        // Run Claude on this node, with optional verify-failure retry loop.
+        let attempt = 0;
+        let result;
+        let currentInstruction = instruction;
+        const retry = node.retry;
+        while (true) {
+            result = await claude.run({
+                instruction: currentInstruction,
+                context,
+                tools: trackedTools,
+                outputSchema: node.output,
+                maxTurns: node.max_turns,
+                onProgress: (message) => {
+                    safeObserve(observer, { type: "node:progress", node: currentId, message }, logger);
+                },
+            });
+            // Retry only triggers on verify failure — bail on tool/API errors.
+            if (result.status !== "success")
+                break;
             const verifyError = evaluateVerify(node.verify, result);
-            if (verifyError) {
-                result.status = "failed";
-                result.data = { ...result.data, error: verifyError };
+            if (!verifyError)
+                break;
+            // Apply verify failure to the result.
+            result.status = "failed";
+            result.data = { ...result.data, error: verifyError };
+            if (!retry || attempt >= retry.max) {
                 logger.warn(`  verify failed: ${verifyError}`, { node: currentId });
+                break;
             }
+            // Build retry preamble + record attempt in trace.
+            trace.steps.push({ node: currentId, status: "failed", iteration, retryAttempt: attempt });
+            logger.warn(`  verify failed (attempt ${attempt + 1}/${retry.max + 1}): ${verifyError}`, { node: currentId });
+            const preamble = await buildRetryPreamble({
+                retry,
+                verifyError,
+                toolCalls: result.toolCalls,
+                nodeInstruction: resolvedInstruction,
+                claude,
+                logger,
+                context,
+            });
+            currentInstruction = `${preamble}\n\n---\n\n${instruction}`;
+            safeObserve(observer, { type: "node:retry", node: currentId, attempt: attempt + 1, reason: verifyError, preamble }, logger);
+            attempt++;
         }
         results.set(currentId, result);
-        trace.steps.push({ node: currentId, status: result.status, iteration });
+        trace.steps.push(attempt > 0
+            ? { node: currentId, status: result.status, iteration, retryAttempt: attempt }
+            : { node: currentId, status: result.status, iteration });
         safeObserve(observer, { type: "node:exit", node: currentId, result }, logger);
         logger.info(`  ✓ ${result.status}`, { node: currentId, toolCalls: result.toolCalls.length });
-        // Dry run hard gate — stop at the first conditional routing decision.
-        // Unconditional edges are analysis flow (prepare→gather→investigate);
-        // conditional edges are action decisions (investigate→create_issue/skip).
-        // Enforced in the executor so it cannot be bypassed by LLM evaluation.
-        const isDryRun = input && typeof input === "object" && input.dryRun === true;
-        if (isDryRun) {
-            const outEdges = workflow.edges.filter((e) => e.from === currentId);
-            if (outEdges.some((e) => e.when)) {
-                safeObserve(observer, { type: "route", from: currentId, to: "(end)", reason: "dry run" }, logger);
-                currentId = null;
-                continue;
-            }
-        }
-        // Resolve next node via edge conditions
-        const prevId = currentId;
-        currentId = await resolveNext(workflow, currentId, results, input, claude, observer, edgeCounts, logger);
-        // Record the routing decision in the trace
-        if (currentId) {
-            const edgeKey = `${prevId}→${currentId}`;
-            const reason = workflow.edges.find((e) => e.from === prevId && e.to === currentId)?.when ?? "only path";
-            trace.edges.push({ from: prevId, to: currentId, reason });
-        }
+        // Dry run gate + routing — shared with requires path via advanceFromNode helper.
+        currentId = await advanceFromNode(workflow, currentId, results, input, claude, observer, edgeCounts, logger, trace);
     }
     safeObserve(observer, {
         type: "workflow:end",
@@ -341,6 +373,35 @@ function resolveConfig(skills, overrides) {
     }
     return config;
 }
+/**
+ * Apply the dry-run gate and then resolve the next node via edge conditions.
+ *
+ * Used in both the normal execution path and the requires-failure path so
+ * the dry-run guard + resolveNext + trace-edge recording logic lives in one place.
+ *
+ * Returns the next node ID, or null when execution should stop.
+ */
+async function advanceFromNode(workflow, currentId, results, input, claude, observer, edgeCounts, logger, trace) {
+    // Dry run hard gate — stop at the first conditional routing decision.
+    // Unconditional edges are analysis flow (prepare→gather→investigate);
+    // conditional edges are action decisions (investigate→create_issue/skip).
+    // Enforced in the executor so it cannot be bypassed by LLM evaluation.
+    const isDryRun = input && typeof input === "object" && input.dryRun === true;
+    if (isDryRun) {
+        const outEdges = workflow.edges.filter((e) => e.from === currentId);
+        if (outEdges.some((e) => e.when)) {
+            safeObserve(observer, { type: "route", from: currentId, to: "(end)", reason: "dry run" }, logger);
+            return null;
+        }
+    }
+    const prevId = currentId;
+    const nextId = await resolveNext(workflow, currentId, results, input, claude, observer, edgeCounts, logger);
+    if (nextId) {
+        const reason = workflow.edges.find((e) => e.from === prevId && e.to === nextId)?.when ?? "only path";
+        trace.edges.push({ from: prevId, to: nextId, reason });
+    }
+    return nextId;
+}
 /**
  * Resolve which edge to follow from the current node.
  *

package/dist/executor.test.js

@@ -353,6 +353,9 @@ describe("skill instruction injection", () => {
             async evaluate() {
                 return "";
             },
+            async ask() {
+                return "";
+            },
         };
         await execute(workflow, {}, {
             skills: createSkillMap([instructionSkill]),
@@ -405,6 +408,9 @@ describe("skill instruction injection", () => {
             async evaluate() {
                 return "";
             },
+            async ask() {
+                return "";
+            },
         };
         await execute(workflow, {}, {
             skills: createSkillMap([skillA, skillB]),
@@ -448,6 +454,9 @@ describe("skill instruction injection", () => {
             async evaluate() {
                 return "";
             },
+            async ask() {
+                return "";
+            },
         };
         // Should NOT throw "none are configured"
         const { results } = await execute(workflow, {}, {
@@ -487,6 +496,9 @@ describe("skill instruction injection", () => {
             async evaluate() {
                 return "";
             },
+            async ask() {
+                return "";
+            },
         };
         // No "my-rubric" in the skill map — executor must pull it from workflow.skills
         const { results } = await execute(workflow, {}, {
@@ -537,6 +549,9 @@ describe("skill instruction injection", () => {
             async evaluate() {
                 return "";
             },
+            async ask() {
+                return "";
+            },
         };
         await execute(workflow, {}, {
             skills: createSkillMap([callerSkill]),

package/dist/requires.d.ts

@@ -0,0 +1,7 @@
+import type { NodeRequires } from "./types.js";
+/**
+ * Evaluate a node's `requires` block against the cross-node context map.
+ * Returns null when all checks pass (or when `requires` is undefined),
+ * otherwise a single concatenated failure string.
+ */
+export declare function evaluateRequires(requires: NodeRequires | undefined, context: Record<string, unknown>): string | null;

package/dist/requires.js

@@ -0,0 +1,34 @@
+// ─── Requires: pre-condition gate ───────────────────────────────────
+//
+// Evaluates `node.requires` BEFORE the LLM runs. Same path grammar and
+// resolver as verify — the only differences are the data root (cross-node
+// context map instead of result.data) and the error prefix.
+import { checkOutputRequired, checkOutputMatches } from "./verify.js";
+/**
+ * Evaluate a node's `requires` block against the cross-node context map.
+ * Returns null when all checks pass (or when `requires` is undefined),
+ * otherwise a single concatenated failure string.
+ */
+export function evaluateRequires(requires, context) {
+    if (!requires)
+        return null;
+    const hasRequiredChecks = requires.output_required && requires.output_required.length > 0;
+    const hasMatchChecks = requires.output_matches && requires.output_matches.length > 0;
+    if (!hasRequiredChecks && !hasMatchChecks) {
+        return `requires failed:\n  - Requires block present but no checks declared`;
+    }
+    const failures = [];
+    if (hasRequiredChecks) {
+        const e = checkOutputRequired(requires.output_required, context);
+        if (e)
+            failures.push(e);
+    }
+    if (hasMatchChecks) {
+        const e = checkOutputMatches(requires.output_matches, context);
+        if (e)
+            failures.push(e);
+    }
+    if (failures.length === 0)
+        return null;
+    return `requires failed:\n  - ${failures.join("\n  - ")}`;
+}

package/dist/retry.d.ts

@@ -0,0 +1,23 @@
+import type { Claude, NodeRetry, ToolCall, Logger } from "./types.js";
+export interface BuildRetryPreambleOptions {
+    retry: NodeRetry;
+    verifyError: string;
+    toolCalls: ToolCall[];
+    nodeInstruction: string;
+    claude: Claude;
+    logger: Logger;
+    context: Record<string, unknown>;
+}
+/**
+ * Build the retry preamble for a single retry attempt.
+ *
+ * Resolution order:
+ *   1. retry.instruction is a string         → static preamble + verify error
+ *   2. retry.instruction is { auto: true }   → claude.ask(default prompt)
+ *   3. retry.instruction is { reflect: "..." } → claude.ask(author prompt)
+ *   4. Otherwise (omitted)                   → default preamble
+ *
+ * Reflection failure (throw or empty response) silently falls back to the
+ * default static preamble and logs a warning.
+ */
+export declare function buildRetryPreamble(opts: BuildRetryPreambleOptions): Promise<string>;

package/dist/retry.js

@@ -0,0 +1,72 @@
+// ─── Retry: preamble construction for verify-failure self-healing ──
+//
+// Builds the preamble that gets prepended to the node instruction on retry.
+// In autonomous modes ({ auto: true } or { reflect: ... }), this calls
+// claude.ask to generate a diagnosis. If reflection fails or returns empty,
+// falls back to the default static preamble — reflection failure never
+// escalates to a workflow failure.
+import { isErrorOutput } from "./verify.js";
+const DEFAULT_REFLECTION_PROMPT = "Briefly diagnose the failure and state your strategy for the retry. Keep your response to 2-4 sentences.";
+const DEFAULT_PREAMBLE_HEADER = "## Previous attempt failed verification";
+/**
+ * Build the retry preamble for a single retry attempt.
+ *
+ * Resolution order:
+ *   1. retry.instruction is a string         → static preamble + verify error
+ *   2. retry.instruction is { auto: true }   → claude.ask(default prompt)
+ *   3. retry.instruction is { reflect: "..." } → claude.ask(author prompt)
+ *   4. Otherwise (omitted)                   → default preamble
+ *
+ * Reflection failure (throw or empty response) silently falls back to the
+ * default static preamble and logs a warning.
+ */
+export async function buildRetryPreamble(opts) {
+    const { retry, verifyError, toolCalls, nodeInstruction, claude, logger, context } = opts;
+    const inst = retry.instruction;
+    if (typeof inst === "string") {
+        return `## Retry guidance\n\n${inst}\n\n${DEFAULT_PREAMBLE_HEADER}\n\n${verifyError}`;
+    }
+    if (inst && typeof inst === "object") {
+        const reflectPrompt = "reflect" in inst && typeof inst.reflect === "string" ? inst.reflect : DEFAULT_REFLECTION_PROMPT;
+        const askInstruction = buildReflectionPrompt(reflectPrompt, nodeInstruction, verifyError, toolCalls);
+        try {
+            const diagnosis = await claude.ask({ instruction: askInstruction, context });
+            const trimmed = diagnosis.trim();
+            if (trimmed.length > 0) {
+                return `## Reflection on previous attempt\n\n${trimmed}\n\n${DEFAULT_PREAMBLE_HEADER}\n\n${verifyError}`;
+            }
+            logger.warn("Retry reflection returned empty response; falling back to default preamble.");
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            logger.warn(`Retry reflection threw: ${msg}; falling back to default preamble.`);
+        }
+    }
+    return defaultPreamble(verifyError);
+}
+function defaultPreamble(verifyError) {
+    return `${DEFAULT_PREAMBLE_HEADER}\n\n${verifyError}\n\nFix the issue and try again.`;
+}
+function buildReflectionPrompt(reflectPrompt, nodeInstruction, verifyError, toolCalls) {
+    const summary = summarizeToolCalls(toolCalls);
+    return [
+        `You attempted to: ${nodeInstruction}`,
+        "",
+        `Verification failed with: ${verifyError}`,
+        "",
+        `You called these tools during the failed attempt:`,
+        summary,
+        "",
+        reflectPrompt,
+    ].join("\n");
+}
+function summarizeToolCalls(toolCalls) {
+    if (toolCalls.length === 0)
+        return "(no tools were called)";
+    return toolCalls
+        .map((c) => {
+        const status = isErrorOutput(c.output) ? "error" : "ok";
+        return `  - ${c.tool} (${status})`;
+    })
+        .join("\n");
+}