pi-extensible-workflows 1.0.1 → 3.0.0

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,6 +1,15 @@
 #!/usr/bin/env node
 import { type DoctorOptions } from "./doctor.js";
+import { type JsonSchema, type JsonValue } from "./index.js";
+import type { WorkflowCatalogFunction } from "./index.js";
 export interface CliOptions extends DoctorOptions {
     inspect?: (sessionId?: string) => Promise<void>;
+    transcript?: (sessionFile: string) => Promise<void>;
+    stderr?: (text: string) => void;
+    signal?: AbortSignal;
+    trustOverride?: boolean;
+    isTTY?: boolean;
 }
+export declare function formatWorkflowCliHelp(fn: WorkflowCatalogFunction, command?: string): string;
+export declare function parseWorkflowCliArgs(schema: JsonSchema, rawArgs: readonly string[]): Record<string, JsonValue>;
 export declare function runCli(args: readonly string[], options?: CliOptions, write?: (text: string) => void): Promise<number>;