howtofixcli 0.7.24 → 0.7.26

package/dist/workflow-engine.js

@@ -0,0 +1,246 @@
+import { acquireAgentSlot } from "./agent-limiter.js";
+export const LIFETIME_CAP = 1000;
+export const FANOUT_CAP = 4096;
+/** How often a paused run re-checks for resume. */
+export const PAUSE_POLL_MS = 100;
+/** Ceiling on a pause, so a forgotten pause cannot hang the run forever. */
+export const PAUSE_MAX_MS = 5 * 60 * 1000;
+/**
+ * Hold until the run is resumed, or give up after {@link PAUSE_MAX_MS}.
+ *
+ * Resolves `true` to continue and `false` when the wait ran out — the caller
+ * then resolves that one call as `null`, which is the engine's normal way of
+ * saying "this agent produced nothing". A pause is therefore visible in the
+ * results instead of silently vanishing.
+ */
+export async function waitForResume(options, pollMs = PAUSE_POLL_MS, maxMs = PAUSE_MAX_MS) {
+    const deadline = Date.now() + maxMs;
+    while (options.isPaused?.()) {
+        if (options.signal?.aborted)
+            return false;
+        if (Date.now() >= deadline)
+            return false;
+        await new Promise((resolve) => setTimeout(resolve, pollMs));
+    }
+    return true;
+}
+/** Thrown for the three conditions that must not be swallowed by a script. */
+export class WorkflowError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "WorkflowError";
+    }
+}
+/** A FIFO semaphore, so `parallel()` fans out up to `limit` and queues the rest. */
+function createSemaphore(limit) {
+    let active = 0;
+    const waiting = [];
+    return async function acquire() {
+        if (active >= limit)
+            await new Promise((resolve) => waiting.push(resolve));
+        active++;
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            active--;
+            waiting.shift()?.();
+        };
+    };
+}
+/**
+ * Build the bindings for one run.
+ *
+ * Every agent call goes through {@link createBindings}'s `runAgent`, which owns
+ * the counters, the semaphore and the budget check — so no binding can bypass
+ * the caps.
+ */
+export function createBindings(options) {
+    const lifetimeCap = options.lifetimeCap ?? LIFETIME_CAP;
+    const fanoutCap = options.fanoutCap ?? FANOUT_CAP;
+    // The width is the shared limiter's, so a `task` call running at the same time
+    // is counted against the same budget. `concurrency` remains for a script that
+    // wants fewer in flight than the machine allows.
+    const local = options.concurrency ? createSemaphore(options.concurrency) : null;
+    const acquire = async () => {
+        const releaseShared = await acquireAgentSlot();
+        if (!local)
+            return releaseShared;
+        const releaseLocal = await local();
+        return () => {
+            releaseLocal();
+            releaseShared();
+        };
+    };
+    let calls = 0;
+    let spent = 0;
+    let currentPhase = "";
+    const emit = (event) => options.onEvent?.(event);
+    // Live snapshots, keyed by call so a repair turn updates the same entry rather
+    // than adding a second one for what the user sees as one agent.
+    const snapshots = new Map();
+    const publish = () => options.onProgress?.([...snapshots.values()]);
+    const runAgent = async (prompt, opts) => {
+        const spec = opts ?? {};
+        const label = typeof spec.label === "string" ? spec.label : `agent-${calls + 1}`;
+        const phase = typeof spec.phase === "string" ? spec.phase : currentPhase;
+        const agentType = typeof spec.agentType === "string" ? spec.agentType : "task";
+        const effort = typeof spec.effort === "string" ? spec.effort : undefined;
+        const model = typeof spec.model === "string" ? spec.model : undefined;
+        const isolation = typeof spec.isolation === "string" ? spec.isolation : undefined;
+        const schema = spec.schema;
+        // Budget and lifetime are checked before dispatch and throw, unlike an agent
+        // failure. This is the one difference a script is required to handle.
+        if (options.budgetTotal != null && spent >= options.budgetTotal) {
+            throw new WorkflowError(`budget exhausted: spent ${spent} of ${options.budgetTotal} output tokens`);
+        }
+        if (calls >= lifetimeCap) {
+            throw new WorkflowError(`lifetime cap reached: ${lifetimeCap} agent calls in one run`);
+        }
+        calls++;
+        const callIndex = calls;
+        // A pause holds the queue, it does not discard it: every call still runs,
+        // just later. The wait is bounded so a forgotten pause cannot hang a run.
+        if (options.isPaused?.()) {
+            const release = await waitForResume(options, PAUSE_POLL_MS, PAUSE_MAX_MS);
+            if (!release)
+                return null;
+        }
+        const release = await acquire();
+        try {
+            if (options.signal?.aborted)
+                return null;
+            emit({ kind: "agent_start", label, phase, ordinal: calls });
+            snapshots.set(callIndex, {
+                label,
+                phase,
+                agentType,
+                status: "running",
+                outputTokens: 0,
+                ...(model ? { model } : {}),
+                startedAt: Date.now(),
+            });
+            publish();
+            const settle = (status, outcome, detail) => {
+                const entry = snapshots.get(callIndex);
+                if (entry) {
+                    entry.status = status;
+                    entry.outputTokens = outcome.outputTokens;
+                    entry.endedAt = Date.now();
+                    if (outcome.toolCalls !== undefined)
+                        entry.toolCalls = outcome.toolCalls;
+                    if (outcome.model !== undefined)
+                        entry.model = outcome.model;
+                    if (detail)
+                        entry.detail = detail;
+                }
+                emit({ kind: "agent_end", label, ok: status === "ok", outputTokens: outcome.outputTokens });
+                publish();
+            };
+            // A schema call gets one repair turn: the model is shown the validation
+            // errors and asked again. Exhausting the retries resolves null, per spec.
+            const attempts = schema === undefined ? 1 : 2;
+            for (let attempt = 0; attempt < attempts; attempt++) {
+                const ask = attempt === 0 ? String(prompt) : undefined;
+                const outcome = await invokeSafely(ask ?? buildRepairPrompt(String(prompt), lastRejection), { label, phase, agentType, effort, model, isolation });
+                if (outcome === null) {
+                    settle("failed", { text: "", outputTokens: 0 });
+                    return null;
+                }
+                spent += outcome.outputTokens;
+                if (schema === undefined) {
+                    settle("ok", outcome, firstLine(outcome.text));
+                    return outcome.text;
+                }
+                const parsed = extractJsonLoose(outcome.text);
+                const issues = parsed === undefined ? [{ path: "", message: "reply was not JSON" }] : validateSchema(parsed, schema);
+                if (issues.length === 0) {
+                    settle("ok", outcome, firstLine(outcome.text));
+                    return parsed;
+                }
+                lastRejection = formatIssues(issues);
+                if (attempt === attempts - 1) {
+                    settle("failed", outcome, `schema: ${firstLine(lastRejection)}`);
+                    return null;
+                }
+            }
+            return null;
+        }
+        finally {
+            release();
+        }
+    };
+    let lastRejection = "";
+    const invokeSafely = async (prompt, spec) => {
+        try {
+            return await options.invoke({ prompt, ...spec });
+        }
+        catch {
+            // Engine-internal failures degrade to null, never a throw.
+            return null;
+        }
+    };
+    const parallel = async (thunks) => {
+        if (thunks.length > fanoutCap) {
+            throw new WorkflowError(`fan-out cap exceeded: ${thunks.length} items (max ${fanoutCap})`);
+        }
+        const results = await Promise.all(thunks.map(async (thunk) => {
+            try {
+                return await thunk();
+            }
+            catch {
+                return null;
+            }
+        }));
+        return results;
+    };
+    const pipeline = async (items, ...stages) => {
+        if (items.length > fanoutCap) {
+            throw new WorkflowError(`fan-out cap exceeded: ${items.length} items (max ${fanoutCap})`);
+        }
+        const results = await Promise.all(items.map(async (item, index) => {
+            let prev = item;
+            for (const stage of stages) {
+                try {
+                    prev = await stage(prev, item, index);
+                }
+                catch {
+                    return null; // only a throw drops the item
+                }
+            }
+            return prev;
+        }));
+        return results;
+    };
+    return {
+        agent: (prompt, opts) => runAgent(prompt, opts),
+        parallel,
+        pipeline,
+        phase: (title) => {
+            currentPhase = String(title);
+            emit({ kind: "phase", title: currentPhase });
+        },
+        log: (message) => emit({ kind: "log", message: String(message) }),
+        args: options.args,
+        budget: {
+            total: options.budgetTotal ?? null,
+            spent: () => spent,
+            remaining: () => (options.budgetTotal == null ? Infinity : Math.max(0, options.budgetTotal - spent)),
+        },
+    };
+}
+/** Told to the model when its reply did not validate. */
+function buildRepairPrompt(original, rejection) {
+    return `${original}\n\nYour previous reply did not satisfy the required schema:\n${rejection}\n\nReply with ONLY a corrected JSON value.`;
+}
+/** The first non-empty line, clipped — the one-line detail for a progress row. */
+function firstLine(text, max = 80) {
+    const line = text
+        .split("\n")
+        .map((entry) => entry.trim())
+        .find((entry) => entry.length > 0) ?? "";
+    return line.length > max ? `${line.slice(0, max)}…` : line;
+}
+/** Late-bound to keep `validateSchema`/`extractJson` out of the engine's import cycle. */
+import { extractJson as extractJsonLoose, formatIssues, validateSchema } from "./schema.js";