howtofixcli 0.7.14 → 0.7.15

package/dist/workflow.js

@@ -1,349 +0,0 @@
-/**
- * The `workflow` tool: one script becomes a fleet of agents.
- *
- * The model writes a JavaScript workflow and this runs it, which is Claude
- * Code's `ultracode` mode reduced to what this harness's SDK can support. The
- * script's bindings live in `workflow-engine.ts`; this file owns the two things
- * that are about *this* harness:
- *
- * 1. **Which agent a call becomes.** The engine is backend-agnostic and asks for
- *    an agent; here that resolves to the subagent registry in `agents.ts`
- *    (`scout`/`task`/`reviewer`), opened directly rather than through the `task`
- *    tool — the tool's `drain()` runs *every* queued run, so concurrent
- *    `agent()` calls would each try to execute each other's runs. One run per
- *    call, one session per call, no shared queue.
- *
- * 2. **`meta` and the load-time rules.** The spec's file grammar: the first
- *    statement must be `export const meta = <pure literal>`, and the body must
- *    not import or export. `meta.phases[].title` values are matched against
- *    `phase()` calls for progress grouping.
- */
-import { readFileSync } from "node:fs";
-import { basename } from "node:path";
-import { StringEnum } from "@netrodev/hxf-ai";
-import { defineTool } from "@netrodev/hxf-coding-agent";
-import { Type } from "typebox";
-import { agents, modelRef, openAgentSession } from "./agents.js";
-import { createAgentWorktree } from "./git.js";
-import { createBindings, WorkflowError } from "./workflow-engine.js";
-import { formatElapsed, formatProgressLine } from "./workflow-progress.js";
-/** The status key the live progress line is published under. */
-export const WORKFLOW_STATUS_KEY = "workflow";
-let workflowControls = null;
-export function setWorkflowControls(next) {
-    workflowControls = next;
-}
-/** Cap on how long one run may take, so a runaway script cannot hang the tool. */
-const RUN_TIMEOUT_MS = 10 * 60 * 1000;
-/**
- * Read `meta` and enforce the load-time grammar.
- *
- * The spec allows only literal forms in `meta` (no identifiers, calls, member
- * access or spreads) and forbids `import`/`export` in the body. Rather than
- * writing a full AST check, the export is extracted textually and the literal is
- * evaluated by a `Function` with the binding names shadowed — so an identifier
- * in `meta` fails loudly instead of silently evaluating.
- */
-export function parseMeta(code) {
-    // Comments and blank lines may precede `meta`: both reference parsers skip
-    // them, and the contract's own checklist *requires* a header comment ("use
-    // case, when to use, args, patterns demonstrated, cost profile, output
-    // shape") above the literal. Requiring the export to be the byte-zero
-    // statement rejected every real workflow.
-    const stripped = code.replace(/^(?:\s+|\/\/[^\n]*\n|\/\*[\s\S]*?\*\/)*/, "");
-    const head = /^export\s+const\s+meta\s*=\s*/.exec(stripped);
-    if (!head) {
-        throw new WorkflowError("a workflow script must start with `export const meta = { name, description }`");
-    }
-    // Keep the body relative to the original source so line numbers in later
-    // errors still point at the file the author wrote.
-    const bodyStart = code.length - stripped.length;
-    // Find the end of the literal by brace matching rather than by looking for a
-    // semicolon: the reference scripts omit it (`export const meta = { ... }`),
-    // and requiring one rejected every real workflow.
-    const literalStart = head[0].length;
-    let depth = 0;
-    let inString = null;
-    let end = -1;
-    for (let index = literalStart; index < stripped.length; index++) {
-        const char = stripped[index];
-        if (inString) {
-            if (char === "\\")
-                index++;
-            else if (char === inString)
-                inString = null;
-            continue;
-        }
-        if (char === '"' || char === "'" || char === "`")
-            inString = char;
-        else if (char === "{" || char === "[")
-            depth++;
-        else if (char === "}" || char === "]") {
-            depth--;
-            if (depth === 0) {
-                end = index + 1;
-                break;
-            }
-        }
-    }
-    if (end === -1)
-        throw new WorkflowError("meta is not a closed literal object");
-    const literal = stripped.slice(literalStart, end);
-    // A trailing semicolon is optional.
-    const body = code.slice(bodyStart + end).replace(/^\s*;/, "");
-    if (/^\s*(import|export)\b/m.test(body)) {
-        throw new WorkflowError("a workflow body must not contain import or export declarations");
-    }
-    if (/\bimport\s*\(/.test(body)) {
-        throw new WorkflowError("a workflow body must not use dynamic import()");
-    }
-    let meta;
-    try {
-        meta = new Function(`"use strict"; return (${literal});`)();
-    }
-    catch (error) {
-        throw new WorkflowError(`meta must be a literal object: ${error instanceof Error ? error.message : String(error)}`);
-    }
-    if (typeof meta !== "object" || meta === null)
-        throw new WorkflowError("meta must be an object");
-    const record = meta;
-    if (typeof record.name !== "string" || !record.name.trim())
-        throw new WorkflowError("meta.name is required");
-    if (typeof record.description !== "string" || !record.description.trim()) {
-        throw new WorkflowError("meta.description is required");
-    }
-    const phases = Array.isArray(record.phases)
-        ? record.phases
-            .filter((entry) => typeof entry === "object" && entry !== null)
-            .map((entry) => ({
-            title: String(entry.title ?? ""),
-            ...(typeof entry.detail === "string" ? { detail: entry.detail } : {}),
-        }))
-            .filter((entry) => entry.title)
-        : undefined;
-    return {
-        meta: {
-            name: record.name,
-            description: record.description,
-            ...(typeof record.whenToUse === "string" ? { whenToUse: record.whenToUse } : {}),
-            ...(phases ? { phases } : {}),
-        },
-        body,
-    };
-}
-/**
- * Compile a body into an async function.
- *
- * `Function` is the only option here: the sandbox `codemode` uses is not
- * reachable with custom bindings (`CodemodeToolOptions` has no hook for them),
- * and a workflow script is model-authored code running in the user's own
- * session — the same trust level as the shell commands the agent already runs.
- * The body is a module body, so top-level `await` and `return` are legal, which
- * rules out a plain `Function`.
- */
-export function compileBody(body) {
-    const names = ["agent", "parallel", "pipeline", "phase", "log", "args", "budget"];
-    const source = `"use strict"; return (async () => {\n${body}\n})();`;
-    let factory;
-    try {
-        factory = new Function(...names, source);
-    }
-    catch (error) {
-        throw new WorkflowError(`workflow did not compile: ${error instanceof Error ? error.message : String(error)}`);
-    }
-    return factory;
-}
-/** Read the final text out of an agent session, whatever shape it returns. */
-function finalText(session) {
-    return session.getLastAssistantText()?.trim() ?? "";
-}
-/**
- * Run one agent call on a fresh subagent session.
- *
- * Output tokens, tool calls and the model come from the session's own stats,
- * which is what makes the script's `budget` real rather than advisory and what
- * fills the per-agent metric in the progress view.
- *
- * `isolation: "worktree"` gives the call its own checkout via `openAgentSession`,
- * which is the only correct way to run parallel agents that write to the same
- * files: siblings in one working tree race each other.
- */
-export function createInvoker(parentModel) {
-    return async ({ prompt, agentType, effort, model, isolation }) => {
-        const spec = agents.get(agentType) ?? agents.get("task");
-        if (!spec)
-            throw new WorkflowError(`no agent named ${agentType}`);
-        // `isolation: "worktree"` means a private checkout, not just a private cwd:
-        // parallel writers in one tree race each other's builds and `git add -A`.
-        const worktree = isolation === "worktree" ? await createAgentWorktree(process.cwd(), agentType) : null;
-        const session = await openAgentSession({
-            agent: spec.name,
-            effort: (effort ?? spec.effort),
-            // The script's `model` has to reach the session, not only the metric line:
-            // it used to be reported as the model that ran while the child actually
-            // ran the runtime default.
-            ...(model ? { model } : {}),
-            ...(parentModel ? { parentModel } : {}),
-            ...(worktree ? { worktree: worktree.path } : {}),
-        });
-        try {
-            await session.prompt(`${spec.prompt}\n\nTask:\n${prompt}`);
-            const stats = session.getSessionStats();
-            // The session first: it is the one that ran. The script's request is the
-            // fallback for a runtime that cannot name its own model.
-            const resolved = modelId(session) ?? model;
-            return {
-                text: finalText(session),
-                outputTokens: stats.tokens.output,
-                toolCalls: stats.toolCalls,
-                ...(resolved ? { model: resolved } : {}),
-            };
-        }
-        finally {
-            session.dispose();
-            await worktree?.remove();
-        }
-    };
-}
-/** The model a session actually ran on, when the SDK exposes it. */
-function modelId(session) {
-    return session.model?.id ?? session.model?.name;
-}
-export const workflowParams = Type.Object({
-    code: Type.Optional(Type.String({ description: "The workflow script source" })),
-    path: Type.Optional(Type.String({ description: "Path to a workflow script, instead of code" })),
-    agent: Type.Optional(StringEnum(["scout", "task", "reviewer"], { description: "Default agent profile for calls" })),
-    budget: Type.Optional(Type.Number({ description: "Output-token ceiling for the whole run" })),
-});
-export function createWorkflowTool(options) {
-    // The workbench registers its panel hooks once, the same way `setAsker` and
-    // `setMirror` hand other modules a live surface. The tool is built during
-    // session construction, before the TUI exists, so it cannot be passed in.
-    const hooks = () => options ?? workflowControls;
-    return defineTool({
-        name: "workflow",
-        label: "workflow",
-        description: "Run a JavaScript workflow that orchestrates many agents deterministically. Provide `code` (or `path`). The script starts with `export const meta = { name, description, phases }` and then uses the injected bindings: `agent(prompt, {label, phase, schema, effort, model, agentType, isolation})`, `parallel(thunks)`, `pipeline(items, ...stages)`, `phase(title)`, `log(msg)`, `args`, `budget`. `agent()` resolves null on failure and throws only when the budget or the call cap is exhausted, so null-check every result. `parallel()` takes thunks and never rejects; `pipeline()` has no barrier between items. Use it for fan-out, for builder-verifier loops that converge on a verdict, and for anything needing many agents whose order and count must be deterministic.",
-        promptSnippet: "workflow: orchestrate many agents from one JavaScript script",
-        parameters: workflowParams,
-        executionMode: "sequential",
-        async execute(_toolCallId, params, signal, onUpdate, ctx) {
-            const code = params.path ? readFileSync(params.path, "utf8") : (params.code ?? "");
-            if (!code.trim())
-                throw new WorkflowError("provide code or path");
-            const { meta, body } = parseMeta(code);
-            // The contract requires `meta.name` to match the script's filename, so a
-            // run launched by path is identifiable in the progress list and in any
-            // artifact directory named after it. A mismatch is a real error, not a
-            // warning: it is what makes the name trustworthy.
-            if (params.path) {
-                const file = basename(params.path).replace(/\.(js|mjs|cjs|ts)$/, "");
-                if (file !== meta.name) {
-                    throw new WorkflowError(`meta.name "${meta.name}" must match the script filename "${file}"`);
-                }
-            }
-            const factory = compileBody(body);
-            const startedAt = Date.now();
-            const steps = [];
-            let outputTokens = 0;
-            let callCount = 0;
-            const detailsOf = (ok, error) => ({
-                name: meta.name,
-                ...(meta.description ? { description: meta.description } : {}),
-                ok,
-                agents: callCount,
-                outputTokens,
-                startedAt,
-                phases: meta.phases ?? [],
-                steps,
-                ...(error ? { error } : {}),
-            });
-            // The live surface: the dock line shows the run in flight, the way the
-            // reference puts its progress line in the task panel under the input box.
-            const publish = (progress, ended) => {
-                ctx.ui.setStatus(WORKFLOW_STATUS_KEY, ended ? undefined : formatProgressLine(progress));
-                onUpdate?.({ content: [], details: detailsOf(false) });
-            };
-            const onProgress = (agents) => {
-                callCount = agents.length;
-                outputTokens = agents.reduce((sum, agent) => sum + agent.outputTokens, 0);
-                steps.splice(0, steps.length, ...agents.map((agent) => ({
-                    label: agent.label,
-                    phase: agent.phase,
-                    agent: agent.agentType,
-                    status: agent.status,
-                    outputTokens: agent.outputTokens,
-                    startedAt: agent.startedAt,
-                    ...(agent.toolCalls !== undefined ? { toolCalls: agent.toolCalls } : {}),
-                    ...(agent.model ? { model: agent.model } : {}),
-                    ...(agent.endedAt ? { endedAt: agent.endedAt } : {}),
-                    ...(agent.detail ? { detail: agent.detail } : {}),
-                    ...(agent.tasks ? { tasks: agent.tasks } : {}),
-                })));
-                publish({ name: meta.name, ...(meta.description ? { description: meta.description } : {}), phases: meta.phases ?? [], steps, startedAt }, false);
-            };
-            const invoke = createInvoker(modelRef(ctx?.model));
-            const bindings = createBindings({
-                invoke: params.agent ? wrapAgent(invoke, params.agent) : invoke,
-                budgetTotal: params.budget ?? null,
-                onProgress,
-                ...(signal ? { signal } : {}),
-                ...(hooks()?.isPaused ? { isPaused: hooks().isPaused } : {}),
-            });
-            const controller = new AbortController();
-            const timer = setTimeout(() => controller.abort(), RUN_TIMEOUT_MS);
-            if (signal)
-                signal.addEventListener("abort", () => controller.abort(), { once: true });
-            // Hand the panel a way to stop this run. `x` in the panel calls it; the
-            // abort then resolves in-flight calls as `null`, which is the engine's
-            // normal failure mode, so a stopped run still returns a partial result
-            // instead of throwing.
-            hooks()?.onStop?.(() => controller.abort());
-            try {
-                const result = await Promise.race([
-                    factory(bindings.agent, bindings.parallel, bindings.pipeline, bindings.phase, bindings.log, bindings.args, bindings.budget),
-                    new Promise((_resolve, reject) => controller.signal.addEventListener("abort", () => reject(new WorkflowError("workflow timed out or was aborted")))),
-                ]);
-                const endedAt = Date.now();
-                ctx.ui.setStatus(WORKFLOW_STATUS_KEY, undefined);
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: `${meta.name}: ${callCount} agent call(s), ${outputTokens} output tokens in ${formatElapsed(endedAt - startedAt)}\n\n${render(result)}`,
-                        },
-                    ],
-                    details: { ...detailsOf(true), endedAt },
-                };
-            }
-            catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                ctx.ui.setStatus(WORKFLOW_STATUS_KEY, undefined);
-                return {
-                    content: [{ type: "text", text: `${meta.name} failed after ${callCount} agent call(s): ${message}` }],
-                    details: { ...detailsOf(false, message), endedAt: Date.now() },
-                    isError: true,
-                };
-            }
-            finally {
-                clearTimeout(timer);
-                hooks()?.onStop?.(null);
-            }
-        },
-    });
-}
-/** Force every call to one agent profile, whatever the script asked for. */
-function wrapAgent(invoke, agentType) {
-    return (spec) => invoke({ ...spec, agentType });
-}
-/** The script's return value, as text for the model. */
-function render(value) {
-    if (typeof value === "string")
-        return value;
-    try {
-        return JSON.stringify(value, null, 2);
-    }
-    catch {
-        return String(value);
-    }
-}