@marcoscale98/pi-extensible-workflows 5.14.1-fork.1

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,188 @@
+import { BUDGET_DIMENSIONS, WorkflowError } from "./types.js";
+import { fail, object } from "./utils.js";
+const BUDGET_LIMITS = ["soft", "hard"];
+function isBudgetDimension(value) { return BUDGET_DIMENSIONS.some((dimension) => dimension === value); }
+function isBudgetLimit(value) { return BUDGET_LIMITS.some((limit) => limit === value); }
+function dimensionEntries(value) {
+    const entries = [];
+    for (const [dimension, raw] of Object.entries(value)) {
+        if (!isBudgetDimension(dimension))
+            fail("INVALID_METADATA", `Unknown budget dimension: ${dimension}`);
+        entries.push([dimension, raw]);
+    }
+    return entries;
+}
+function limitEntries(value, message, ownOnly = false) {
+    if (Object.keys(value).some((key) => !isBudgetLimit(key)))
+        fail("INVALID_METADATA", message);
+    const entries = [];
+    for (const key of BUDGET_LIMITS) {
+        if (!ownOnly || Object.prototype.hasOwnProperty.call(value, key))
+            entries.push([key, value[key]]);
+    }
+    return entries;
+}
+function budgetEntries(value) {
+    const entries = [];
+    for (const [dimension, limits] of Object.entries(value)) {
+        if (!isBudgetDimension(dimension))
+            continue;
+        entries.push([dimension, limits]);
+    }
+    return entries;
+}
+function nonNegativeInteger(value) { return typeof value === "number" && Number.isInteger(value) && value >= 0; }
+function nonNegativeFinite(value) { return typeof value === "number" && Number.isFinite(value) && value >= 0; }
+function validatedLimit(value, dimension, key) {
+    const kind = dimension === "costUsd" ? "finite number" : "integer";
+    if (dimension === "costUsd") {
+        if (!nonNegativeFinite(value))
+            fail("INVALID_METADATA", `${dimension}.${key} must be a non-negative ${kind}`);
+        return value;
+    }
+    if (!nonNegativeInteger(value))
+        fail("INVALID_METADATA", `${dimension}.${key} must be a non-negative ${kind}`);
+    return value;
+}
+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 dimensionEntries(value)) {
+        if (!object(raw))
+            fail("INVALID_METADATA", `${dimension} budget must be an object`);
+        const limits = {};
+        for (const [key, rawLimit] of limitEntries(raw, `${dimension} budget has an unknown limit`)) {
+            if (rawLimit !== undefined)
+                limits[key] = validatedLimit(rawLimit, dimension, key);
+        }
+        if (limits.soft !== undefined && limits.hard !== undefined && limits.soft >= limits.hard)
+            fail("INVALID_METADATA", `${dimension}.soft must be less than 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 dimensionEntries(value)) {
+        if (raw === null) {
+            result[dimension] = null;
+            continue;
+        }
+        if (!object(raw))
+            fail("INVALID_METADATA", `${dimension} budget patch must contain only soft and hard`);
+        const limits = {};
+        for (const [key, rawLimit] of limitEntries(raw, `${dimension} budget patch must contain only soft and hard`, true)) {
+            if (rawLimit === null)
+                limits[key] = null;
+            else if (rawLimit !== undefined)
+                limits[key] = validatedLimit(rawLimit, dimension, 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 && budgetEntries(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 entries = budgetEntries(budget); const soft = entries.filter(([dimension, limits]) => limits.soft !== undefined && this.#usage[dimension] >= limits.soft).map(([dimension]) => dimension); if (soft.length)
+        this.#record("soft_crossed", soft); const overrun = entries.filter(([dimension, limits]) => limits.hard !== undefined && this.#usage[dimension] > limits.hard).map(([dimension]) => dimension); 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 BUDGET_DIMENSIONS)
+    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 BUDGET_LIMITS)
+            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 BUDGET_DIMENSIONS) {
+    const oldLimit = previous?.[dimension];
+    const newLimit = next?.[dimension];
+    for (const key of BUDGET_LIMITS)
+        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 budgetEntries(budget).filter(([dimension, limits]) => limits.hard !== undefined && usage[dimension] >= limits.hard).map(([dimension]) => dimension); }
+export function resumeBudgetAllowed(budget, usage) { return exhaustedBudgetDimensions(budget, usage).length === 0; }

package/dist/src/changelog.d.ts

@@ -0,0 +1,6 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+type ChangelogContext = Pick<ExtensionContext, "hasUI" | "mode"> & {
+    ui: Pick<ExtensionContext["ui"], "notify">;
+};
+export declare function showChangelogNotice(context: ChangelogContext, agentDir: string, packageDirectory?: string): Promise<void>;
+export {};

package/dist/src/changelog.js

@@ -0,0 +1,112 @@
+import { mkdir, readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { atomicJson, json } from "./io.js";
+import { object } from "./utils.js";
+import { isCorePackageName } from "./package-identity.js";
+const STATE_DIRECTORY = "pi-extensible-workflows";
+const STATE_FILE = "changelog-state.json";
+const MAX_NOTICE_CHARACTERS = 6_000;
+function packageMetadata(value, directory) {
+    if (!object(value) || !isCorePackageName(value.name) || typeof value.version !== "string" || !value.version.trim())
+        return undefined;
+    return { directory, version: value.version.trim() };
+}
+async function packageMetadataAt(directory) {
+    try {
+        const value = JSON.parse(await readFile(join(directory, "package.json"), "utf8"));
+        return packageMetadata(value, directory);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function installedPackageMetadata() {
+    const moduleDirectory = dirname(fileURLToPath(import.meta.url));
+    for (const directory of [join(moduleDirectory, ".."), join(moduleDirectory, "../..")]) {
+        const metadata = await packageMetadataAt(directory);
+        if (metadata)
+            return metadata;
+    }
+    return undefined;
+}
+function parseChangelog(markdown) {
+    const entries = [];
+    let current;
+    for (const line of markdown.split(/\r?\n/)) {
+        const heading = /^##\s+(?:\[([^\]\r\n]+)\]|([^\s\r\n]+))(?:\s+-.*)?\s*$/.exec(line);
+        if (heading) {
+            const version = heading[1]?.trim() ?? heading[2]?.trim();
+            current = undefined;
+            if (version && version.toLowerCase() !== "unreleased") {
+                current = { version, body: "" };
+                entries.push(current);
+            }
+            continue;
+        }
+        if (current)
+            current.body = current.body ? `${current.body}\n${line}` : line;
+    }
+    return entries;
+}
+async function readChangelog(directory) {
+    try {
+        return parseChangelog(await readFile(join(directory, "CHANGELOG.md"), "utf8"));
+    }
+    catch {
+        return [];
+    }
+}
+function releaseEntries(entries, currentVersion, previousVersion) {
+    const currentIndex = entries.findIndex((entry) => entry.version === currentVersion);
+    const current = entries[currentIndex];
+    if (current === undefined || current.body.trim() === "")
+        return [];
+    if (previousVersion === currentVersion)
+        return [];
+    const previousIndex = previousVersion === undefined ? -1 : entries.findIndex((entry) => entry.version === previousVersion);
+    const selected = previousIndex > currentIndex ? entries.slice(currentIndex, previousIndex) : [current];
+    return selected.filter((entry) => entry.body.trim() !== "");
+}
+function noticeText(version, entries) {
+    const notes = entries.map((entry) => `## ${entry.version}\n${entry.body.trim()}`).join("\n\n");
+    const bounded = notes.length > MAX_NOTICE_CHARACTERS ? `${notes.slice(0, MAX_NOTICE_CHARACTERS).trimEnd()}\n...` : notes;
+    return `pi-extensible-workflows updated to ${version}\n\n${bounded}`;
+}
+async function lastNotifiedVersion(path) {
+    try {
+        const value = await json(path);
+        return object(value) && typeof value.lastNotifiedVersion === "string" && value.lastNotifiedVersion.trim() ? value.lastNotifiedVersion : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function showChangelogNotice(context, agentDir, packageDirectory) {
+    if (!context.hasUI || (context.mode !== "tui" && context.mode !== "rpc"))
+        return;
+    const { ui } = context;
+    try {
+        const metadata = packageDirectory === undefined ? await installedPackageMetadata() : await packageMetadataAt(packageDirectory);
+        if (!metadata)
+            return;
+        const statePath = join(agentDir, STATE_DIRECTORY, STATE_FILE);
+        const previousVersion = await lastNotifiedVersion(statePath);
+        if (previousVersion === metadata.version)
+            return;
+        const entries = releaseEntries(await readChangelog(metadata.directory), metadata.version, previousVersion);
+        if (!entries.length)
+            return;
+        ui.notify(noticeText(metadata.version, entries), "info");
+        try {
+            await mkdir(dirname(statePath), { recursive: true, mode: 0o700 });
+            await atomicJson(statePath, { lastNotifiedVersion: metadata.version });
+        }
+        catch {
+            // The notice is advisory; a failed state write may repeat it on the next start.
+        }
+    }
+    catch {
+        // Changelog data is optional and must never prevent Pi startup.
+    }
+}

package/dist/src/decoders.d.ts

@@ -0,0 +1,96 @@
+import { type AgentDefinition, type BudgetApprovalRequest, type JsonValue, type LaunchSnapshot, type RunRecord, type WorkflowBudgetUsage, type WorkflowExtensionSettings } from "./types.js";
+import type { OwnershipRecord } from "./agent-execution.js";
+export interface EffectiveSystemPrompt {
+    sessionId: string;
+    attempt: number;
+    turn: number;
+    sha256: string;
+    prompt: string;
+}
+export type PersistedRun = RunRecord;
+export interface RunSummaryAgent {
+    id: string;
+    name: string;
+    label?: string;
+    state: string;
+    role?: string;
+    attempts: number;
+}
+export interface RunSummaryArtifacts {
+    runDirectory: string;
+    statePath: string;
+    journalPath: string;
+    snapshotPath: string;
+    workflowPath: string;
+    resultPath: string;
+    summaryPath: string;
+}
+export interface RunSummary {
+    schemaVersion: 1;
+    runId: string;
+    sessionId: string;
+    workflowName: string;
+    state: RunRecord["state"];
+    createdAt: string;
+    updatedAt: string;
+    terminalAt?: string;
+    usage: WorkflowBudgetUsage;
+    agents: readonly RunSummaryAgent[];
+    error?: RunRecord["error"];
+    failedAt?: string;
+    replayablePaths: readonly string[];
+    incompletePaths: readonly string[];
+    artifacts: RunSummaryArtifacts;
+}
+export interface CompletedOperation {
+    path: string;
+    value: JsonValue;
+}
+export interface AwaitingCheckpoint {
+    path: string;
+    name: string;
+    prompt: string;
+    context: JsonValue;
+}
+export type PendingWorkflowDecision = BudgetApprovalRequest;
+export type PersistedOwnershipNode = OwnershipRecord;
+export type Journal = {
+    completed: Record<string, CompletedOperation>;
+    awaiting?: Record<string, AwaitingCheckpoint>;
+    decisions?: Record<string, PendingWorkflowDecision>;
+};
+export declare function decodeAgentDefinition(value: unknown): AgentDefinition | undefined;
+export declare function decodeWorkflowExtensions(value: unknown): WorkflowExtensionSettings | undefined;
+export declare function decodePersistedRun(value: unknown, allowLegacyAgentSessions?: boolean): PersistedRun | undefined;
+export declare function isPersistedRun(value: unknown): value is PersistedRun;
+export declare function decodeLaunchSnapshot(value: unknown): LaunchSnapshot | undefined;
+export declare function decodeSessionOwner(value: unknown): SessionOwner | undefined;
+export declare function decodeOwnershipRecords(value: unknown): OwnershipRecord[] | undefined;
+export declare function decodeWorktreeReferences(value: unknown): WorktreeReference[] | undefined;
+export declare function decodeBorrowedWorktreeBindings(value: unknown): BorrowedWorktreeBinding[] | undefined;
+export declare function decodeJournal(value: unknown): Journal | undefined;
+export declare function decodeBooleanCheckpointResult(value: unknown): boolean | undefined;
+export declare function decodeSummaryProjection(value: unknown): Partial<RunSummary> | undefined;
+export declare function decodeSystemPromptArtifact(value: unknown): {
+    version: number;
+    format?: unknown;
+    storage?: unknown;
+    entries?: EffectiveSystemPrompt[];
+} | undefined;
+export interface WorktreeReference {
+    owner: string;
+    path: string;
+    branch: string;
+    cwd: string;
+    base: string;
+}
+export interface BorrowedWorktreeBinding {
+    name: string;
+    sourceRunId: string;
+    owner: string;
+}
+export type SessionOwner = {
+    pid: number;
+    token: string;
+    startedAt: number;
+};