pi-extensible-workflows 2.0.0 → 3.1.0

package/dist/src/budget.d.ts

@@ -0,0 +1,38 @@
+import { type BudgetDimension, type BudgetEvent, type WorkflowBudget, type WorkflowBudgetPatch, type WorkflowBudgetUsage, type AgentAccounting, type RunState } from "./types.js";
+export declare function validateBudget(value: unknown): WorkflowBudget | undefined;
+export declare function validateBudgetPatch(value: unknown): WorkflowBudgetPatch;
+export declare function budgetUsage(value?: Partial<WorkflowBudgetUsage>): WorkflowBudgetUsage;
+export declare class WorkflowBudgetRuntime {
+    #private;
+    readonly budget: WorkflowBudget | undefined;
+    readonly version: number;
+    constructor(budget: WorkflowBudget | undefined, version?: number, usage?: Partial<WorkflowBudgetUsage>, events?: readonly BudgetEvent[], options?: {
+        now?: () => number;
+        onChange?: () => void;
+        active?: boolean;
+    });
+    get usage(): WorkflowBudgetUsage;
+    get events(): readonly BudgetEvent[];
+    get hardExhausted(): boolean;
+    checkAgentLaunch(): void;
+    beforeAttempt(): void;
+    beforeTurn(): void;
+    afterTurn(accounting: AgentAccounting, final: boolean): void;
+    instruction(agentId?: string): string | undefined;
+    forAgent(agentId: string): {
+        beforeAttempt: () => void;
+        beforeTurn: () => void;
+        afterTurn: (accounting: AgentAccounting, final: boolean) => void;
+        instruction: () => string | undefined;
+    };
+    transition(state: RunState): void;
+    recordEvent(event: BudgetEvent): void;
+    snapshot(): {
+        usage: WorkflowBudgetUsage;
+        budgetEvents: readonly BudgetEvent[];
+    };
+}
+export declare function mergeBudget(budget: WorkflowBudget | undefined, patch: WorkflowBudgetPatch): WorkflowBudget | undefined;
+export declare function budgetRelaxed(previous: WorkflowBudget | undefined, next: WorkflowBudget | undefined): boolean;
+export declare function exhaustedBudgetDimensions(budget: WorkflowBudget | undefined, usage: WorkflowBudgetUsage): BudgetDimension[];
+export declare function resumeBudgetAllowed(budget: WorkflowBudget | undefined, usage: WorkflowBudgetUsage): boolean;

package/dist/src/budget.js

@@ -0,0 +1,160 @@
+import { WorkflowError } from "./types.js";
+import { fail, object } from "./utils.js";
+function nonNegativeInteger(value) { return Number.isInteger(value) && value >= 0; }
+function nonNegativeFinite(value) { return typeof value === "number" && Number.isFinite(value) && value >= 0; }
+export function validateBudget(value) {
+    if (value === undefined)
+        return undefined;
+    if (!object(value))
+        fail("INVALID_METADATA", "budget must be an object");
+    const result = {};
+    for (const [dimension, raw] of Object.entries(value)) {
+        if (!["tokens", "costUsd", "durationMs", "agentLaunches"].includes(dimension))
+            fail("INVALID_METADATA", `Unknown budget dimension: ${dimension}`);
+        if (!object(raw))
+            fail("INVALID_METADATA", `${dimension} budget must be an object`);
+        if (Object.keys(raw).some((key) => key !== "soft" && key !== "hard"))
+            fail("INVALID_METADATA", `${dimension} budget has an unknown limit`);
+        const isCost = dimension === "costUsd";
+        for (const key of ["soft", "hard"])
+            if (raw[key] !== undefined && !(isCost ? nonNegativeFinite(raw[key]) : nonNegativeInteger(raw[key])))
+                fail("INVALID_METADATA", `${dimension}.${key} must be a non-negative ${isCost ? "finite number" : "integer"}`);
+        if (raw.soft !== undefined && raw.soft !== null && raw.hard !== undefined && raw.hard !== null && raw.soft >= raw.hard)
+            fail("INVALID_METADATA", `${dimension}.soft must be less than hard`);
+        const limits = {};
+        if (raw.soft !== undefined)
+            limits.soft = raw.soft;
+        if (raw.hard !== undefined)
+            limits.hard = raw.hard;
+        if (Object.keys(limits).length)
+            result[dimension] = limits;
+    }
+    return Object.freeze(result);
+}
+export function validateBudgetPatch(value) {
+    if (!object(value))
+        fail("INVALID_METADATA", "budget patch must be an object");
+    const result = {};
+    for (const [dimension, raw] of Object.entries(value)) {
+        if (!["tokens", "costUsd", "durationMs", "agentLaunches"].includes(dimension))
+            fail("INVALID_METADATA", `Unknown budget dimension: ${dimension}`);
+        if (raw === null) {
+            result[dimension] = null;
+            continue;
+        }
+        if (!object(raw) || Object.keys(raw).some((key) => key !== "soft" && key !== "hard"))
+            fail("INVALID_METADATA", `${dimension} budget patch must contain only soft and hard`);
+        const limits = {};
+        for (const key of ["soft", "hard"])
+            if (Object.prototype.hasOwnProperty.call(raw, key)) {
+                if (raw[key] === null)
+                    limits[key] = null;
+                else {
+                    const checked = validateBudget({ [dimension]: { [key]: raw[key] } })?.[dimension];
+                    if (checked?.[key] !== undefined)
+                        limits[key] = checked[key];
+                }
+            }
+        if (limits.soft !== null && limits.hard !== null && limits.soft !== undefined && limits.hard !== undefined && limits.soft >= limits.hard)
+            fail("INVALID_METADATA", `${dimension}.soft must be less than hard`);
+        result[dimension] = limits;
+    }
+    return result;
+}
+export function budgetUsage(value) { return { tokens: value?.tokens ?? 0, costUsd: value?.costUsd ?? 0, durationMs: value?.durationMs ?? 0, agentLaunches: value?.agentLaunches ?? 0 }; }
+export class WorkflowBudgetRuntime {
+    budget;
+    version;
+    #now;
+    #onChange;
+    #injected = new Set();
+    #seen = new Set();
+    #active;
+    #activeSince;
+    #usage;
+    #events;
+    #turnAccounting;
+    constructor(budget, version = 1, usage, events = [], options = {}) {
+        this.budget = budget;
+        this.version = version;
+        this.#now = options.now ?? (() => Date.now());
+        this.#onChange = options.onChange;
+        this.#active = options.active ?? true;
+        this.#activeSince = this.#active ? this.#now() : undefined;
+        this.#usage = budgetUsage(usage);
+        this.#events = [...events];
+        for (const event of events)
+            if (event.budgetVersion === version)
+                this.#seen.add(event.type);
+    }
+    get usage() { this.#syncDuration(); return { ...this.#usage }; }
+    get events() { return this.#events; }
+    get hardExhausted() { return this.#events.some((event) => event.type === "hard_exhausted" && event.budgetVersion === this.version); }
+    checkAgentLaunch() { this.#checkHard(["agentLaunches"]); }
+    beforeAttempt() { this.#checkHard(["agentLaunches"]); this.#usage.agentLaunches += 1; this.#evaluate(); }
+    beforeTurn() { this.#syncDuration(); this.#evaluate(); this.#checkHard(["tokens", "costUsd", "durationMs"]); }
+    afterTurn(accounting, final) { this.#syncDuration(); this.#applyTurn(accounting, final, this.#turnAccounting); this.#turnAccounting = { input: accounting.input, output: accounting.output, cost: accounting.cost }; }
+    #applyTurn(accounting, final, previous = { input: 0, output: 0, cost: 0 }) { this.#usage.tokens += Math.max(0, accounting.input - previous.input) + Math.max(0, accounting.output - previous.output); this.#usage.costUsd += Math.max(0, accounting.cost - previous.cost); this.#evaluate(); if (!final)
+        this.#checkHard(["tokens", "costUsd", "durationMs"]); }
+    instruction(agentId = "agent") { if (!this.#hasSoftCrossed() || this.#injected.has(agentId))
+        return undefined; this.#injected.add(agentId); return `The workflow budget soft limit has been reached. Finish the requested output now, preserving any required output schema. Current usage: ${JSON.stringify(this.usage)}. Do not start additional model work unless it is required to produce the final requested result.`; }
+    forAgent(agentId) { let attempt = 0; let previous; return { beforeAttempt: () => { attempt += 1; previous = undefined; this.beforeAttempt(); }, beforeTurn: () => { this.beforeTurn(); }, afterTurn: (accounting, final) => { this.#applyTurn(accounting, final, previous); previous = { input: accounting.input, output: accounting.output, cost: accounting.cost }; }, instruction: () => this.instruction(`${agentId}:${String(attempt + 1)}`) }; }
+    transition(state) { const active = state === "running"; if (active === this.#active)
+        return; if (active) {
+        this.#active = true;
+        this.#activeSince = this.#now();
+    }
+    else {
+        this.#syncDuration();
+        this.#evaluate();
+        this.#active = false;
+        this.#activeSince = undefined;
+    } this.#onChange?.(); }
+    #syncDuration() { if (this.#active && this.#activeSince !== undefined) {
+        const now = this.#now();
+        this.#usage.durationMs += Math.max(0, now - this.#activeSince);
+        this.#activeSince = now;
+    } }
+    #hasSoftCrossed() { return !!this.budget && Object.entries(this.budget).some(([dimension, limits]) => limits.soft !== undefined && this.#usage[dimension] >= limits.soft); }
+    #checkHard(dimensions) { const exhausted = dimensions.filter((dimension) => { const hard = this.budget?.[dimension]?.hard; return hard !== undefined && this.#usage[dimension] >= hard; }); if (!exhausted.length)
+        return; this.#record("hard_exhausted", exhausted); const detail = exhausted.map((dimension) => `${dimension} usage=${String(this.#usage[dimension])} hard=${String(this.budget?.[dimension]?.hard)}`).join(", "); throw new WorkflowError("BUDGET_EXHAUSTED", `Budget version ${String(this.version)} exhausted: ${detail}`); }
+    #evaluate() { const budget = this.budget; if (!budget)
+        return; const soft = Object.keys(budget).filter((dimension) => { const limits = budget[dimension]; return limits !== undefined && limits.soft !== undefined && this.#usage[dimension] >= limits.soft; }); if (soft.length)
+        this.#record("soft_crossed", soft); const overrun = Object.keys(budget).filter((dimension) => { const limits = budget[dimension]; return limits !== undefined && limits.hard !== undefined && this.#usage[dimension] > limits.hard; }); if (overrun.length)
+        this.#record("hard_overrun", overrun); }
+    #record(type, dimensions) { if (this.#seen.has(type))
+        return; this.#seen.add(type); this.#events.push({ type, budgetVersion: this.version, dimensions: [...dimensions], usage: this.usage, limits: structuredClone(this.budget ?? {}), at: this.#now() }); this.#onChange?.(); }
+    recordEvent(event) { this.#events.push(structuredClone(event)); }
+    snapshot() { return { usage: this.usage, budgetEvents: [...this.#events] }; }
+}
+export function mergeBudget(budget, patch) { const merged = structuredClone(budget ?? {}); for (const dimension of ["tokens", "costUsd", "durationMs", "agentLaunches"])
+    if (Object.prototype.hasOwnProperty.call(patch, dimension)) {
+        const value = patch[dimension];
+        if (value === null) {
+            Reflect.deleteProperty(merged, dimension);
+            continue;
+        }
+        const next = { ...(merged[dimension] ?? {}) };
+        for (const key of ["soft", "hard"])
+            if (value && Object.prototype.hasOwnProperty.call(value, key)) {
+                const limit = value[key];
+                if (limit === null)
+                    Reflect.deleteProperty(next, key);
+                else if (limit !== undefined)
+                    next[key] = limit;
+            }
+        if (Object.keys(next).length)
+            merged[dimension] = next;
+        else
+            Reflect.deleteProperty(merged, dimension);
+    } return validateBudget(merged); }
+export function budgetRelaxed(previous, next) { for (const dimension of ["tokens", "costUsd", "durationMs", "agentLaunches"]) {
+    const oldLimit = previous?.[dimension];
+    const newLimit = next?.[dimension];
+    for (const key of ["soft", "hard"])
+        if ((oldLimit?.[key] !== undefined && newLimit?.[key] === undefined) || (oldLimit?.[key] !== undefined && newLimit?.[key] !== undefined && newLimit[key] > oldLimit[key]))
+            return true;
+} return false; }
+export function exhaustedBudgetDimensions(budget, usage) { if (!budget)
+    return []; return Object.keys(budget).filter((dimension) => { const limits = budget[dimension]; return limits !== undefined && limits.hard !== undefined && usage[dimension] >= limits.hard; }); }
+export function resumeBudgetAllowed(budget, usage) { return exhaustedBudgetDimensions(budget, usage).length === 0; }

package/dist/src/cli.d.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { type DoctorOptions } from "./doctor.js";
+import { type DoctorCleanupOptions } from "./doctor-cleanup.js";
 import { type JsonSchema, type JsonValue } from "./index.js";
 import type { WorkflowCatalogFunction } from "./index.js";
 export interface CliOptions extends DoctorOptions {
@@ -12,4 +13,5 @@ export interface CliOptions extends DoctorOptions {
 }
 export declare function formatWorkflowCliHelp(fn: WorkflowCatalogFunction, command?: string): string;
 export declare function parseWorkflowCliArgs(schema: JsonSchema, rawArgs: readonly string[]): Record<string, JsonValue>;
+export declare function parseDoctorCleanupArgs(rawArgs: readonly string[]): Required<Pick<DoctorCleanupOptions, "olderThanDays" | "yes">>;
 export declare function runCli(args: readonly string[], options?: CliOptions, write?: (text: string) => void): Promise<number>;

package/dist/src/cli.js

@@ -7,7 +7,8 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { ProjectTrustStore, SessionManager, SettingsManager, createAgentSessionFromServices, createAgentSessionServices, getAgentDir, hasTrustRequiringProjectResources } from "@earendil-works/pi-coding-agent";
 import { Value } from "typebox/value";
 import { doctor, doctorExitCode, formatDoctorReport } from "./doctor.js";
-import workflowExtension, { formatWorkflowProgress, workflowCatalog } from "./index.js";
+import { doctorCleanup, doctorCleanupExitCode, formatDoctorCleanupReport } from "./doctor-cleanup.js";
+import workflowExtension, { formatWorkflowProgress, truncateWorkflowProgress, workflowCatalog, workflowSettingsPath } from "./index.js";
 import { runSessionInspector, transcriptFileLines } from "./session-inspector.js";
 function object(value) { return typeof value === "object" && value !== null && !Array.isArray(value); }
 function has(value, key) { return Object.prototype.hasOwnProperty.call(value, key); }
@@ -193,6 +194,34 @@ function launcherHelpLines() {
 }
 function workflowUsage() { return [`Usage: pi-extensible-workflows run <workflow-name> [workflow arguments] | export <workflow-name> [--name <command>] [--output <path>] [--force]`, "", "Launcher options:", ...launcherHelpLines()].join("\n") + "\n"; }
 function exportUsage() { return [`Usage: pi-extensible-workflows export <workflow-name> [--name <command>] [--output <path>] [--force]`, "", "Launcher options:", ...launcherHelpLines()].join("\n") + "\n"; }
+export function parseDoctorCleanupArgs(rawArgs) {
+    let olderThanDays = 90;
+    let yes = false;
+    let seenDays = false;
+    for (let index = 0; index < rawArgs.length; index += 1) {
+        const token = rawArgs[index];
+        if (token === "--yes") {
+            yes = true;
+            continue;
+        }
+        const inline = token.startsWith("--older-than-days=") ? token.slice("--older-than-days=".length) : undefined;
+        if (token === "--older-than-days" || inline !== undefined) {
+            if (seenDays)
+                throw new Error("--older-than-days may only be provided once");
+            const raw = inline ?? rawArgs[++index];
+            if (raw === undefined || !/^[1-9]\d*$/.test(raw))
+                throw new Error("older-than-days must be a positive integer");
+            const parsed = Number(raw);
+            if (!Number.isSafeInteger(parsed) || parsed < 1)
+                throw new Error("older-than-days must be a positive integer");
+            olderThanDays = parsed;
+            seenDays = true;
+            continue;
+        }
+        throw new Error(`Unknown cleanup option: ${token}`);
+    }
+    return { olderThanDays, yes };
+}
 function stripTrustOptions(rawArgs) {
     const args = [];
     let trustOverride;
@@ -278,7 +307,7 @@ async function createWorkflowRuntime(options, shutdownHandlers = []) {
     const workflowTool = tools.find((tool) => object(tool) && tool.name === "workflow");
     if (!workflowTool)
         throw new Error("The workflow runtime could not be initialized");
-    return { catalog: workflowCatalog(), services, workflowTool, shutdownHandlers };
+    return { catalog: workflowCatalog({ cwd, projectTrusted: settingsManager.isProjectTrusted(), globalSettingsPath: workflowSettingsPath(agentDir) }), services, workflowTool, shutdownHandlers };
 }
 function availableModelInfo(services, available = false) {
     const models = available ? services.modelRuntime.getAvailableSnapshot() : services.modelRuntime.getModels();
@@ -321,21 +350,27 @@ function writeLauncher(destination, workflowName, force) {
         rmSync(tempDir, { recursive: true, force: true });
     }
 }
+function terminalProgressStyles(enabled) {
+    const style = (code) => enabled ? (text) => `\x1b[${String(code)}m${text}\x1b[0m` : (text) => text;
+    return { accent: style(36), success: style(32), error: style(31), warning: style(33), muted: style(90), dim: style(2), bold: style(1) };
+}
 class CliProgress {
     stderr;
-    tty;
     #lastStable = "";
     #lines = 0;
     #frame = 0;
     #run;
     #timer;
+    #interactive;
+    #styles;
     constructor(stderr, tty) {
         this.stderr = stderr;
-        this.tty = tty;
+        this.#interactive = tty && process.env.NO_COLOR === undefined && process.env.TERM !== "dumb";
+        this.#styles = terminalProgressStyles(this.#interactive);
     }
     update(run) {
-        const stable = formatWorkflowProgress(run, "◇");
-        if (!this.tty) {
+        const stable = formatWorkflowProgress(run, "◇", this.#styles);
+        if (!this.#interactive) {
             if (stable !== this.#lastStable) {
                 this.#lastStable = stable;
                 this.stderr(`${stable}\n`);
@@ -352,7 +387,7 @@ class CliProgress {
             return;
         const spinner = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"][this.#frame++ % 10] ?? "◇";
         const width = process.stderr.columns || 80;
-        const text = formatWorkflowProgress(this.#run, spinner).split("\n").map((line) => line.length <= width ? line : `${line.slice(0, Math.max(0, width - 1))}…`).join("\n");
+        const text = truncateWorkflowProgress(formatWorkflowProgress(this.#run, spinner, this.#styles), width).join("\n");
         this.stderr(`${this.#lines ? `\x1b[${String(this.#lines)}A` : ""}${this.#lines ? "" : "\x1b[?25l"}\x1b[0J${text}\n`);
         this.#lines = text.split("\n").length;
     }
@@ -361,7 +396,7 @@ class CliProgress {
             clearInterval(this.#timer);
             this.#timer = undefined;
         }
-        if (this.tty && this.#lines) {
+        if (this.#interactive && this.#lines) {
             this.stderr(`\x1b[${String(this.#lines)}A\x1b[0J\x1b[?25h`);
             this.#lines = 0;
         }
@@ -506,6 +541,23 @@ export async function runCli(args, options = {}, write = (text) => { process.std
         write(formatDoctorReport(report));
         return doctorExitCode(report);
     }
+    if (args[0] === "doctor" && args[1] === "cleanup") {
+        if (args.slice(2).some((arg) => arg === "--help" || arg === "-h")) {
+            write("Usage: pi-extensible-workflows doctor cleanup [--older-than-days <days>] [--yes]\n");
+            return 0;
+        }
+        try {
+            const parsed = parseDoctorCleanupArgs(args.slice(2));
+            const cleanupOptions = { ...parsed, ...(options.cwd !== undefined ? { cwd: options.cwd } : {}) };
+            const report = await doctorCleanup(cleanupOptions);
+            write(formatDoctorCleanupReport(report));
+            return doctorCleanupExitCode(report);
+        }
+        catch (error) {
+            stderr(`Error: ${error instanceof Error ? error.message : String(error)}\n`);
+            return 1;
+        }
+    }
     if (args[0] === "inspect" && args.length <= 2) {
         try {
             await (options.inspect ?? runSessionInspector)(args[1]);

package/dist/src/doctor-cleanup.d.ts

@@ -0,0 +1,41 @@
+export interface DoctorCleanupOptions {
+    cwd?: string;
+    home?: string;
+    olderThanDays?: number;
+    yes?: boolean;
+    now?: number;
+}
+export interface CleanupRunResult {
+    sessionId: string;
+    runId: string;
+    action: "candidate" | "skipped" | "deleted" | "failed";
+    state: string;
+    stateMtimeMs: number;
+    path: string;
+    reason?: string;
+}
+export interface CleanupFailure {
+    sessionId: string;
+    runId?: string;
+    message: string;
+}
+export interface CleanupSessionReport {
+    sessionId: string;
+    path: string;
+    status: "preview" | "cleaned" | "skipped" | "failed";
+    reason?: string;
+}
+export interface DoctorCleanupReport {
+    cwd: string;
+    cutoffMs: number;
+    olderThanDays: number;
+    yes: boolean;
+    sessions: readonly CleanupSessionReport[];
+    candidates: readonly CleanupRunResult[];
+    skipped: readonly CleanupRunResult[];
+    deleted: readonly CleanupRunResult[];
+    failures: readonly CleanupFailure[];
+}
+export declare function doctorCleanup(options?: DoctorCleanupOptions): Promise<DoctorCleanupReport>;
+export declare function doctorCleanupExitCode(report: DoctorCleanupReport): 0 | 1;
+export declare function formatDoctorCleanupReport(report: DoctorCleanupReport): string;