@yycholla/pi-dynamic-workflows 3.3.0

package/dist/workflow-commands.js

@@ -0,0 +1,260 @@
+/**
+ * `/workflows` slash command: list, inspect, and control background workflow runs.
+ * Shares the extension's single WorkflowManager so background runs are reachable.
+ */
+import { fmtFull, fmtTokenSegment, recomputeWorkflowSnapshot, renderWorkflowText, tokenFigures, } from "./display.js";
+import { effortDirective } from "./effort-command.js";
+import { registerSavedWorkflow } from "./saved-commands.js";
+import { buildForcedWorkflowPrompt, WORKFLOW_TOOL_NAME } from "./workflow-editor.js";
+import { openWorkflowNavigator } from "./workflow-ui.js";
+const STATUS_ICON = {
+    pending: "·",
+    running: "◆",
+    paused: "⏸",
+    completed: "✓",
+    failed: "✗",
+    aborted: "⊘",
+};
+const USAGE = "Usage: /workflows [list] | run <prompt> | status <id> | watch <id> | stop <id> | pause <id> | resume <id> | rm <id> | save <name> [runId]";
+const RUN_USAGE = "Usage: /workflows run <prompt> — force a dynamic workflow from the prompt";
+function summarizeRun(run) {
+    const icon = STATUS_ICON[run.status] ?? "?";
+    const done = run.agents.filter((a) => a.status === "done").length;
+    const total = run.agents.length;
+    const segment = fmtTokenSegment(tokenFigures(run.tokenUsage), fmtFull);
+    const tokens = segment ? ` · ${segment}` : "";
+    return `${icon} ${run.runId}  ${run.workflowName} [${run.status}] ${done}/${total} agents${tokens}`;
+}
+function oneLineProgress(snapshot) {
+    const total = snapshot.agents.length;
+    const done = snapshot.agents.filter((a) => a.status === "done").length;
+    const running = snapshot.agents.filter((a) => a.status === "running").length;
+    const errs = snapshot.agents.filter((a) => a.status === "error").length;
+    const phase = snapshot.currentPhase ? ` · ${snapshot.currentPhase}` : "";
+    return `◆ ${snapshot.name}: ${done}/${total} done${running ? `, ${running} running` : ""}${errs ? `, ${errs} err` : ""}${phase}`;
+}
+/**
+ * Subscribe to a running run's events and stream live progress to the status bar,
+ * printing the final snapshot when it finishes. Non-blocking: returns true if the
+ * run was active and is now being watched, false otherwise. Listeners clean up on
+ * completion so nothing leaks.
+ */
+function watchRun(manager, pi, ctx, id) {
+    const active = manager.getRun(id);
+    if (active?.status !== "running")
+        return false;
+    const key = `wf:${id}`;
+    const update = () => {
+        const run = manager.getRun(id);
+        if (run)
+            ctx.ui.setStatus(key, oneLineProgress(run.snapshot));
+    };
+    const onEvent = (e) => {
+        if (!e || e.runId === id)
+            update();
+    };
+    let settled = false;
+    const progressEvents = ["agentStart", "agentEnd", "phase", "log"];
+    const finalEvents = ["complete", "error", "stopped", "paused"];
+    const finish = (e) => {
+        if (e && e.runId !== id)
+            return;
+        if (settled)
+            return;
+        settled = true;
+        for (const ev of progressEvents)
+            manager.off(ev, onEvent);
+        for (const ev of finalEvents)
+            manager.off(ev, finish);
+        ctx.ui.setStatus(key, undefined);
+        const run = manager.getRun(id);
+        if (run) {
+            void pi.sendMessage({
+                customType: "workflows",
+                content: renderWorkflowText(recomputeWorkflowSnapshot(run.snapshot), true),
+                display: true,
+            });
+        }
+    };
+    for (const ev of progressEvents)
+        manager.on(ev, onEvent);
+    for (const ev of finalEvents)
+        manager.on(ev, finish);
+    update();
+    return true;
+}
+function renderPersistedStatus(run) {
+    const lines = [`${STATUS_ICON[run.status] ?? "?"} ${run.workflowName} (${run.runId}) — ${run.status}`];
+    if (run.currentPhase)
+        lines.push(`  phase: ${run.currentPhase}`);
+    for (const agent of run.agents) {
+        const icon = agent.status === "done" ? "✓" : agent.status === "error" ? "✗" : agent.status === "running" ? "◆" : "·";
+        lines.push(`  ${icon} ${agent.label}`);
+    }
+    const tokenSegment = fmtTokenSegment(tokenFigures(run.tokenUsage), fmtFull);
+    if (tokenSegment)
+        lines.push(`  tokens: ${tokenSegment}`);
+    if (run.durationMs)
+        lines.push(`  duration: ${(run.durationMs / 1000).toFixed(1)}s`);
+    return lines.join("\n");
+}
+/** Register the `/workflows` command against the shared manager. Idempotent. */
+export function registerWorkflowCommands(pi, manager, opts = {}) {
+    try {
+        const taken = (pi.getCommands?.() ?? []).some((c) => c.name === "workflows");
+        if (taken)
+            return;
+    }
+    catch {
+        // getCommands may be unavailable in some hosts; fall through and try to register.
+    }
+    pi.registerCommand("workflows", {
+        description: "Manage workflow runs — no args (opens navigator) | run <prompt> | status/stop/pause/resume <id> | rm <id> | save <name> [runId]",
+        async handler(args, ctx) {
+            const parts = args.trim().split(/\s+/).filter(Boolean);
+            const sub = (parts[0] ?? "list").toLowerCase();
+            const id = parts[1];
+            const print = (text) => pi.sendMessage({ customType: "workflows", content: text, display: true });
+            switch (sub) {
+                case "run": {
+                    const prompt = args
+                        .trim()
+                        .slice(parts[0]?.length ?? 0)
+                        .trim();
+                    if (!prompt) {
+                        ctx.ui.notify(RUN_USAGE, "warning");
+                        return;
+                    }
+                    // Best-effort: ensure the workflow tool is active (session_start usually has).
+                    // Add-only so this does not interfere with the keyword hook's save/restore state.
+                    try {
+                        const active = pi.getActiveTools?.() ?? [];
+                        if (!active.includes(WORKFLOW_TOOL_NAME))
+                            pi.setActiveTools?.([...active, WORKFLOW_TOOL_NAME]);
+                    }
+                    catch {
+                        // ignore — the forced directive is the real forcing primitive
+                    }
+                    const effort = opts.effort;
+                    const extra = effort && effort.level !== "off" ? effortDirective(effort.level) : undefined;
+                    // `/workflows run` is an explicit, maximal-intent command — use the
+                    // forcing directive (no "if it's a question just answer" escape),
+                    // distinct from the heuristic keyword/effort arming.
+                    const armed = buildForcedWorkflowPrompt(prompt, extra);
+                    ctx.ui.notify(`Running workflow: ${prompt.slice(0, 60)}${prompt.length > 60 ? "…" : ""}`, "info");
+                    try {
+                        await pi.sendMessage({ customType: "workflow-run", content: armed, display: true }, { triggerTurn: true, deliverAs: "followUp" });
+                    }
+                    catch {
+                        ctx.ui.notify("Could not start the workflow turn.", "error");
+                    }
+                    return;
+                }
+                case "ui":
+                case "list": {
+                    // Interactive navigator when a UI is available; plain text otherwise
+                    // (print/RPC mode) or when the user explicitly asks for `list`.
+                    if (sub !== "list" && ctx.hasUI) {
+                        await openWorkflowNavigator(pi, manager, ctx.ui, { storage: opts.storage, cwd: opts.cwd });
+                        return;
+                    }
+                    if (parts.length === 0 && ctx.hasUI) {
+                        await openWorkflowNavigator(pi, manager, ctx.ui, { storage: opts.storage, cwd: opts.cwd });
+                        return;
+                    }
+                    const runs = manager.listRuns();
+                    if (!runs.length) {
+                        await print("No workflow runs yet. Start one with a background workflow (background: true).");
+                        return;
+                    }
+                    await print(["Workflow runs:", ...runs.map(summarizeRun), "", USAGE].join("\n"));
+                    return;
+                }
+                case "watch":
+                case "status": {
+                    if (!id) {
+                        ctx.ui.notify(USAGE, "warning");
+                        return;
+                    }
+                    // A running run streams live progress to the status bar and prints the
+                    // final snapshot when it finishes — no need to re-run the command.
+                    if (watchRun(manager, pi, ctx, id)) {
+                        ctx.ui.notify(`Watching ${id} — live progress in the status bar; result prints when it finishes.`, "info");
+                        return;
+                    }
+                    const live = manager.getSnapshot(id);
+                    if (live) {
+                        await print(renderWorkflowText(recomputeWorkflowSnapshot(live), false));
+                        return;
+                    }
+                    const run = manager.listRuns().find((r) => r.runId === id);
+                    if (!run) {
+                        ctx.ui.notify(`No workflow run "${id}"`, "error");
+                        return;
+                    }
+                    await print(renderPersistedStatus(run));
+                    return;
+                }
+                case "stop": {
+                    if (!id)
+                        return ctx.ui.notify(USAGE, "warning");
+                    ctx.ui.notify(manager.stop(id) ? `Stopped ${id}` : `Cannot stop ${id} (not running)`, manager.getRun(id) ? "info" : "warning");
+                    return;
+                }
+                case "pause": {
+                    if (!id)
+                        return ctx.ui.notify(USAGE, "warning");
+                    ctx.ui.notify(manager.pause(id) ? `Paused ${id}` : `Cannot pause ${id} (not running)`, "info");
+                    return;
+                }
+                case "resume": {
+                    if (!id)
+                        return ctx.ui.notify(USAGE, "warning");
+                    const ok = await manager.resume(id);
+                    ctx.ui.notify(ok ? `Resumed ${id}` : `Resume not available for ${id} yet`, ok ? "info" : "warning");
+                    return;
+                }
+                case "rm": {
+                    if (!id)
+                        return ctx.ui.notify(USAGE, "warning");
+                    ctx.ui.notify(manager.deleteRun(id) ? `Removed ${id}` : `No run ${id}`, "info");
+                    return;
+                }
+                case "save": {
+                    const name = id;
+                    if (!name)
+                        return ctx.ui.notify("Usage: /workflows save <name> [runId]", "warning");
+                    if (!opts.storage)
+                        return ctx.ui.notify("Saving is not available (no storage configured)", "error");
+                    const storage = opts.storage;
+                    const runs = manager.listRuns();
+                    const runIdArg = parts[2];
+                    // Pick the named run, else the most recent run that still has its script.
+                    const run = runIdArg ? runs.find((r) => r.runId === runIdArg) : runs.find((r) => r.script);
+                    if (!run?.script) {
+                        ctx.ui.notify(runIdArg ? `No run ${runIdArg} with a script` : "No saved run to save", "error");
+                        return;
+                    }
+                    let saved;
+                    try {
+                        saved = storage.save({
+                            name,
+                            description: run.workflowName,
+                            script: run.script,
+                            location: "project",
+                        });
+                    }
+                    catch (error) {
+                        ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+                        return;
+                    }
+                    registerSavedWorkflow(pi, opts.cwd ?? process.cwd(), saved, undefined, () => storage.list().some((w) => w.name === saved.name));
+                    ctx.ui.notify(`Saved /${name} (from ${run.runId})`, "info");
+                    return;
+                }
+                default:
+                    ctx.ui.notify(`Unknown subcommand "${sub}". ${USAGE}`, "warning");
+            }
+        },
+    });
+}

package/dist/workflow-comprehension.d.ts

@@ -0,0 +1,133 @@
+import type { ModelThinkingLevel } from "@earendil-works/pi-ai";
+import { ComprehensionSuite, ComprehensionTaskKind } from "./enums.js";
+import { type WorkflowRuntimeEvent } from "./workflow.js";
+/** Re-exported scenario groups and authoring operations used by the optional comprehension CLI. */
+export { ComprehensionSuite, ComprehensionTaskKind } from "./enums.js";
+/** Prompt and expected authoring branch for one optional model scenario. */
+export interface ComprehensionScenario {
+    id: string;
+    suite: ComprehensionSuite;
+    kind: ComprehensionTaskKind;
+    prompt: string;
+}
+/** Stable quick, core, and coverage scenarios available to provider and replay runs. */
+export declare const COMPREHENSION_SCENARIOS: readonly ComprehensionScenario[];
+/** Skill discovery and read calls observed while the parent model authored a workflow. */
+export interface SkillLoadingEvidence {
+    discovered: boolean;
+    loaded: boolean;
+    toolCalls: Array<{
+        tool: string;
+        path?: string;
+    }>;
+}
+/** Provider-reported usage attached to one generated workflow. */
+export interface ComprehensionTokenUsage {
+    input: number;
+    output: number;
+    total: number;
+    cost: number;
+    cacheRead: number;
+    cacheWrite: number;
+}
+/** Workflow source and generation evidence supplied to the deterministic replay seam. */
+export interface ModelGeneration {
+    workflow: string;
+    skillLoadingEvidence: SkillLoadingEvidence;
+    tokenUsage: ComprehensionTokenUsage;
+}
+/** Re-exported generation failure that retains loading and usage evidence. */
+export { ModelGenerationError } from "./errors.js";
+interface RuntimeCall {
+    index: number;
+    completedIndex: number | null;
+    label: string;
+    prompt: string;
+    phase: string | null;
+    structured: boolean;
+    scenarioRole: "generator" | "filter" | null;
+    status: "returned" | "null";
+    result: unknown;
+}
+type RuntimeEvent = WorkflowRuntimeEvent & {
+    index: number;
+};
+/** Exact requested and resolved model settings recorded for reproducible comparison. */
+export interface ComprehensionModelSelection {
+    requested: string;
+    resolved: string;
+    thinkingLevel: ModelThinkingLevel | null;
+}
+type ComprehensionFailureStage = "generation" | "parse" | "runtime" | "assertion";
+/** Versioned evidence from one generated workflow executed against its scenario contract. */
+export interface ComprehensionEvidence {
+    formatVersion: 2;
+    provider: string;
+    modelSelection: ComprehensionModelSelection;
+    extensionVersion: string;
+    contractVersions: {
+        format: string;
+        content: string;
+    };
+    skillVersion: string;
+    task: {
+        id: string;
+        suite: ComprehensionSuite;
+        kind: ComprehensionTaskKind;
+        prompt: string;
+    };
+    generatedWorkflow: string | null;
+    skillLoadingEvidence: SkillLoadingEvidence;
+    tokenUsage: ComprehensionTokenUsage | null;
+    runtime: {
+        calls: RuntimeCall[];
+        events: RuntimeEvent[];
+        topology: {
+            maxConcurrent: number;
+            phases: string[];
+        };
+        failures: Array<{
+            callIndex: number;
+            label: string;
+            message: string;
+            errorCode: string | null;
+            recoverable: boolean | null;
+        }>;
+        result: unknown;
+        assertions: Array<{
+            name: string;
+            passed: boolean;
+            details: string;
+        }>;
+    };
+    passed: boolean;
+    failure: {
+        stage: ComprehensionFailureStage;
+        message: string;
+        stack?: string;
+    } | null;
+}
+interface RunComprehensionScenarioBaseOptions {
+    scenario: ComprehensionScenario;
+    provider: string;
+    extensionVersion: string;
+    contractVersions: {
+        format: string;
+        content: string;
+    };
+    skillVersion: string;
+    generate: (scenario: ComprehensionScenario) => Promise<ModelGeneration>;
+}
+/** Dependencies and version facts needed to generate and execute one comprehension scenario. */
+export type RunComprehensionScenarioOptions = RunComprehensionScenarioBaseOptions & ({
+    modelSelection: ComprehensionModelSelection;
+    model?: never;
+} | {
+    /** @deprecated Use modelSelection. Retained for provider-free callers created before evidence format 2. */
+    model: string;
+    modelSelection?: never;
+});
+/** Select scenarios in stable declaration order for one suite. */
+export declare function selectComprehensionScenarios(suite: ComprehensionSuite | `${ComprehensionSuite}`): readonly ComprehensionScenario[];
+/** Generate, parse, execute, and behaviorally score one scenario without making scoring-stage provider calls. */
+export declare function runComprehensionScenario(options: RunComprehensionScenarioOptions): Promise<ComprehensionEvidence>;