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

package/dist/src/runtime/agent-runner.d.ts

@@ -0,0 +1,143 @@
+export type RuntimeJsonValue = null | boolean | number | string | RuntimeJsonValue[] | {
+    [key: string]: RuntimeJsonValue;
+};
+export type RuntimeJsonSchema = {
+    [key: string]: RuntimeJsonValue;
+};
+export interface RuntimeModel {
+    readonly provider: string;
+    readonly model: string;
+    readonly thinking?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+}
+export interface RuntimeToolCall {
+    readonly id: string;
+    readonly input: RuntimeJsonValue;
+    readonly signal: AbortSignal;
+}
+export interface RuntimeToolResult {
+    readonly value: RuntimeJsonValue;
+    readonly isError?: boolean;
+}
+export interface RuntimeTool {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: RuntimeJsonSchema;
+    execute(call: RuntimeToolCall): Promise<RuntimeToolResult>;
+}
+export type RuntimeUsageAvailability = "complete" | "partial" | "unavailable";
+export interface RuntimeUsage {
+    readonly availability: RuntimeUsageAvailability;
+    readonly input?: number;
+    readonly output?: number;
+    readonly cacheRead?: number;
+    readonly cacheWrite?: number;
+    readonly costUsd?: number;
+}
+export type RuntimeAgentProviderRecovery = "retry" | "abort" | {
+    readonly model: string;
+};
+export interface RuntimeAgentProviderFailure {
+    readonly provider: string;
+    readonly model: string;
+    readonly error: string;
+}
+export declare class RuntimeAgentProviderError extends Error {
+    readonly failure: RuntimeAgentProviderFailure;
+    readonly recovery: RuntimeAgentProviderRecovery | undefined;
+    readonly handled: boolean;
+    constructor(failure: RuntimeAgentProviderFailure, recovery: RuntimeAgentProviderRecovery | undefined, handled: boolean);
+}
+export interface RuntimeAgentIdentity {
+    readonly id: string;
+    readonly structuralPath: readonly string[];
+    readonly parentId?: string;
+}
+export interface RuntimeRunIdentity {
+    readonly id: string;
+    readonly namespaceId: string;
+    readonly workflowName: string;
+}
+export interface RuntimeAgentState {
+    readonly model: RuntimeModel;
+    readonly thinking?: RuntimeModel["thinking"];
+    readonly tools: readonly string[];
+    readonly systemPrompt?: string;
+}
+export interface RuntimeToolCallProgress {
+    readonly id: string;
+    readonly name: string;
+    readonly state: "running" | "completed" | "failed";
+}
+export type RuntimeHandoffState = "local-running" | "takeover-pending" | "remote-running" | "returning-local" | "completed";
+export interface RuntimeAgentHandoff {
+    readonly state: RuntimeHandoffState;
+    readonly transferred: boolean;
+    observe(event: {
+        readonly type: string;
+    }): void;
+    request(launch: () => Promise<void>): Promise<void>;
+    waitForTakeover(): Promise<void>;
+    takeover(): void;
+    waitForResume(): Promise<void>;
+    release(reason?: string): void;
+}
+export interface RuntimeAgentRunControl {
+    readonly handoff?: RuntimeAgentHandoff;
+    steer(message: string): Promise<void>;
+}
+export interface RuntimeAgentProgress {
+    readonly usage: RuntimeUsage;
+    readonly toolCalls: readonly RuntimeToolCallProgress[];
+    readonly state?: RuntimeAgentState;
+    readonly activity?: {
+        readonly kind: "reasoning" | "tool" | "text";
+        readonly text: string;
+    };
+    readonly lastEventAt?: number;
+    readonly persist: boolean;
+}
+export interface RuntimeAgentTurnPolicy {
+    beforeTurn(): void;
+    afterTurn(usage: RuntimeUsage, final: boolean, requestInstruction?: boolean): string | undefined;
+}
+export interface RuntimeAgentRunRequest {
+    readonly task: string;
+    readonly cwd: string;
+    readonly model: RuntimeModel;
+    readonly enabledTools: readonly string[];
+    /** Tools owned by the runtime runner; host-specific adapters may map them at session creation. */
+    readonly customTools: readonly RuntimeTool[];
+    /** Explicit result schema; omitted agents use the default string workflow_result schema. */
+    readonly resultSchema?: RuntimeJsonSchema;
+    readonly run: RuntimeRunIdentity;
+    readonly agent: RuntimeAgentIdentity;
+    readonly signal: AbortSignal;
+    readonly timeoutMs?: number | null;
+    readonly onProgress?: (progress: RuntimeAgentProgress) => void | Promise<void>;
+    readonly handoff?: RuntimeAgentHandoff;
+    readonly onControl?: (control: RuntimeAgentRunControl) => void | Promise<void>;
+    readonly turnPolicy?: RuntimeAgentTurnPolicy;
+    readonly onProviderError?: (failure: RuntimeAgentProviderFailure) => Promise<RuntimeAgentProviderRecovery>;
+    readonly onProviderLimit?: () => Promise<void>;
+}
+export interface RuntimeAgentReference {
+    readonly transport: string;
+    readonly locator?: RuntimeJsonValue;
+}
+export interface RuntimeAgentRunResult {
+    /** The accepted workflow_result string for unstructured agents, or schema value when resultSchema was requested. */
+    readonly value: RuntimeJsonValue;
+    readonly usage: RuntimeUsage;
+    readonly reference?: RuntimeAgentReference;
+}
+export interface RuntimeAgentRunner {
+    readonly id: string;
+    readonly capabilities: {
+        readonly customTools: boolean;
+        readonly structuredResults: boolean;
+        readonly steering: boolean;
+        readonly handoff: boolean;
+        readonly usage: RuntimeUsageAvailability;
+    };
+    run(request: Readonly<RuntimeAgentRunRequest>): Promise<RuntimeAgentRunResult>;
+}

package/dist/src/runtime/agent-runner.js

@@ -0,0 +1,12 @@
+export class RuntimeAgentProviderError extends Error {
+    failure;
+    recovery;
+    handled;
+    constructor(failure, recovery, handled) {
+        super(failure.error);
+        this.failure = failure;
+        this.recovery = recovery;
+        this.handled = handled;
+        this.name = "RuntimeAgentProviderError";
+    }
+}

package/dist/src/runtime/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./agent-runner.js";
+export * from "./namespace.js";

package/dist/src/runtime/index.js

@@ -0,0 +1,2 @@
+export * from "./agent-runner.js";
+export * from "./namespace.js";

package/dist/src/runtime/namespace.d.ts

@@ -0,0 +1,14 @@
+export interface WorkflowNamespace {
+    readonly id: string;
+    readonly projectKey: string;
+    readonly cwd: string;
+    readonly storageRoot?: string;
+}
+export interface WorkflowLease {
+    readonly active: boolean;
+    release(): Promise<void>;
+}
+export interface WorkflowLeaseProvider {
+    acquire(namespace: Readonly<WorkflowNamespace>): Promise<WorkflowLease>;
+    isHeld(namespace: Readonly<WorkflowNamespace>): Promise<boolean>;
+}

package/dist/src/runtime/namespace.js

@@ -0,0 +1 @@
+export {};

package/dist/src/runtime/workflow-result.d.ts

@@ -0,0 +1,2 @@
+import type { RuntimeJsonSchema } from "./agent-runner.js";
+export declare const defaultWorkflowResultSchema: RuntimeJsonSchema;

package/dist/src/runtime/workflow-result.js

@@ -0,0 +1,6 @@
+export const defaultWorkflowResultSchema = {
+    type: "object",
+    properties: { result: { type: "string" } },
+    required: ["result"],
+    additionalProperties: false,
+};

package/dist/src/session-handoff.d.ts

@@ -0,0 +1,2 @@
+import type { LiveSessionHandoff } from "./types.js";
+export declare function createLiveSessionHandoff(): LiveSessionHandoff;

package/dist/src/session-handoff.js

@@ -0,0 +1,82 @@
+import { isTurnActivityStart, isTurnBoundaryEnd } from "./pi-runtime-adapter.js";
+export function createLiveSessionHandoff() {
+    let state = "local-running";
+    let turnActive = false;
+    let boundary;
+    let resolveBoundary;
+    let takeover;
+    let resolveTakeover;
+    let takenOver = false;
+    let resume;
+    let resolveResume;
+    let request;
+    const waitForBoundary = () => {
+        if (!turnActive)
+            return Promise.resolve();
+        boundary ??= new Promise((resolve) => { resolveBoundary = resolve; });
+        return boundary;
+    };
+    const finishBoundary = () => {
+        turnActive = false;
+        resolveBoundary?.();
+        boundary = undefined;
+        resolveBoundary = undefined;
+    };
+    const finishTakeover = () => {
+        takenOver = true;
+        state = "herdr-running";
+        resolveTakeover?.();
+        resolveTakeover = undefined;
+    };
+    const isReleased = () => state === "completed";
+    return {
+        get state() { return state; },
+        get transferred() { return takenOver; },
+        observe(event) {
+            if (isTurnActivityStart(event.type))
+                turnActive = true;
+            if (isTurnBoundaryEnd(event.type))
+                finishBoundary();
+        },
+        async request(launch) {
+            if (request)
+                return request;
+            if (isReleased())
+                return;
+            state = "handoff-pending";
+            takeover = new Promise((resolve) => { resolveTakeover = resolve; });
+            resume = new Promise((resolve) => { resolveResume = resolve; });
+            request = (async () => {
+                await waitForBoundary();
+                if (isReleased())
+                    return;
+                state = "herdr-running";
+                try {
+                    await launch();
+                }
+                finally {
+                    if (!takenOver) {
+                        state = "returning-local";
+                        resolveTakeover?.();
+                        resolveTakeover = undefined;
+                    }
+                    resolveResume?.();
+                    state = "completed";
+                }
+            })();
+            return request;
+        },
+        waitForTakeover() { return takeover ?? Promise.resolve(); },
+        takeover() { if (state === "herdr-running" && !takenOver)
+            finishTakeover(); },
+        waitForResume() { return resume ?? Promise.resolve(); },
+        release() {
+            state = "completed";
+            finishBoundary();
+            resolveTakeover?.();
+            resolveTakeover = undefined;
+            resolveResume?.();
+            resolveResume = undefined;
+        },
+    };
+}

package/dist/src/session-lease.d.ts

@@ -0,0 +1,12 @@
+export declare function processAlive(pid: number, startedAt?: number): Promise<boolean>;
+export declare function hasLiveSessionLease(cwd: string, sessionId: string, home?: string): Promise<boolean>;
+export declare class SessionLease {
+    #private;
+    readonly path: string;
+    readonly token: string;
+    constructor(path: string, token: string);
+    get active(): boolean;
+    release(): Promise<void>;
+}
+export declare function acquireSessionLease(cwd: string, sessionId: string, home?: string): Promise<SessionLease>;
+export declare function listRunIds(cwd: string, sessionId: string, home?: string, cleanTemps?: boolean): Promise<string[]>;

package/dist/src/session-lease.js

@@ -0,0 +1,180 @@
+import { randomUUID } from "node:crypto";
+import { link, mkdir, open, readFile, readdir, rename, rm, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { WorkflowError } from "./types.js";
+import { isNodeError } from "./utils.js";
+import { decodeSessionOwner } from "./decoders.js";
+import { json } from "./io.js";
+import { runsDirectory } from "./paths.js";
+const SESSION_OWNER_FILE = "owner.json";
+const SESSION_OWNER_WRITE_GRACE_MS = 30_000;
+const RUN_CREATE_TEMP = /^\.([a-zA-Z0-9._-]+)\.(\d+)\.[0-9a-f-]+\.tmp$/;
+export async function processAlive(pid, startedAt) {
+    try {
+        process.kill(pid, 0);
+    }
+    catch (error) {
+        return !isNodeError(error, "ESRCH");
+    }
+    if (startedAt !== undefined && process.platform === "linux") {
+        try {
+            if ((await stat(`/proc/${String(pid)}`)).ctimeMs > startedAt)
+                return false;
+        }
+        catch (error) {
+            if (isNodeError(error, "ENOENT"))
+                return false;
+        }
+    }
+    return true;
+}
+export async function hasLiveSessionLease(cwd, sessionId, home = homedir()) {
+    const path = join(runsDirectory(cwd, sessionId, home), SESSION_OWNER_FILE);
+    let owner;
+    try {
+        owner = await json(path);
+    }
+    catch (error) {
+        if (isNodeError(error, "ENOENT"))
+            return false;
+        throw error;
+    }
+    const candidate = decodeSessionOwner(owner);
+    if (!candidate)
+        throw new WorkflowError("RUN_OWNED", `Pi session ${sessionId} has an invalid ownership lease`);
+    return processAlive(candidate.pid, candidate.startedAt);
+}
+function sameOwner(left, right) {
+    if (left === undefined || right === undefined)
+        return false;
+    return left.pid === right.pid && left.token === right.token;
+}
+async function restoreLease(path, stale) {
+    try {
+        await link(stale, path);
+    }
+    catch (error) {
+        if (!isNodeError(error, "EEXIST") && !isNodeError(error, "ENOENT"))
+            throw error;
+    }
+    await rm(stale, { force: true });
+}
+async function cleanupRunTemps(directory, entries) {
+    await Promise.all(entries.map(async (entry) => {
+        const match = entry.isDirectory() ? RUN_CREATE_TEMP.exec(entry.name) : undefined;
+        const pid = match?.[2] ? Number(match[2]) : undefined;
+        if (pid && !await processAlive(pid))
+            await rm(join(directory, entry.name), { recursive: true, force: true });
+    }));
+}
+export class SessionLease {
+    path;
+    token;
+    #released = false;
+    constructor(path, token) {
+        this.path = path;
+        this.token = token;
+    }
+    get active() { return !this.#released; }
+    async release() {
+        if (this.#released)
+            return;
+        this.#released = true;
+        try {
+            const owner = decodeSessionOwner(await json(this.path));
+            if (owner?.token === this.token)
+                await rm(this.path, { force: true });
+        }
+        catch (error) {
+            if (!isNodeError(error, "ENOENT"))
+                throw error;
+        }
+    }
+}
+export async function acquireSessionLease(cwd, sessionId, home = homedir()) {
+    const directory = runsDirectory(cwd, sessionId, home);
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const path = join(directory, SESSION_OWNER_FILE);
+    for (;;) {
+        const token = randomUUID();
+        const owner = { pid: process.pid, token, startedAt: process.platform === "linux" ? (await stat(`/proc/${String(process.pid)}`)).ctimeMs : Date.now() };
+        try {
+            const handle = await open(path, "wx", 0o600);
+            try {
+                await handle.writeFile(`${JSON.stringify(owner)}\n`, "utf8");
+            }
+            finally {
+                await handle.close();
+            }
+            return new SessionLease(path, token);
+        }
+        catch (error) {
+            if (!isNodeError(error, "EEXIST"))
+                throw error;
+            let existingOwner;
+            let existingText = "";
+            try {
+                existingText = await readFile(path, "utf8");
+                existingOwner = decodeSessionOwner(JSON.parse(existingText));
+                if (existingOwner && await processAlive(existingOwner.pid, existingOwner.startedAt))
+                    throw new WorkflowError("RUN_OWNED", `Pi session ${sessionId} is already owned by process ${String(existingOwner.pid)}`);
+            }
+            catch (readError) {
+                if (readError instanceof WorkflowError)
+                    throw readError;
+                if (isNodeError(readError, "ENOENT"))
+                    continue;
+                existingOwner = undefined;
+            }
+            if (existingOwner === undefined) {
+                const age = await stat(path).then((value) => Date.now() - value.mtimeMs).catch(() => 0);
+                if (age < SESSION_OWNER_WRITE_GRACE_MS)
+                    throw new WorkflowError("RUN_OWNED", `Pi session ${sessionId} has an active ownership lease`);
+            }
+            const stale = `${path}.${randomUUID()}.stale`;
+            try {
+                await rename(path, stale);
+                const movedText = await readFile(stale, "utf8");
+                let movedOwner;
+                try {
+                    movedOwner = decodeSessionOwner(JSON.parse(movedText));
+                }
+                catch {
+                    movedOwner = undefined;
+                }
+                if (movedOwner === undefined) {
+                    if (movedText === existingText)
+                        await rm(stale, { force: true });
+                    else
+                        await restoreLease(path, stale);
+                    continue;
+                }
+                if (!sameOwner(existingOwner, movedOwner)) {
+                    await restoreLease(path, stale);
+                    continue;
+                }
+                await rm(stale, { force: true });
+            }
+            catch (reclaimError) {
+                if (isNodeError(reclaimError, "ENOENT"))
+                    continue;
+                throw reclaimError;
+            }
+        }
+    }
+}
+export async function listRunIds(cwd, sessionId, home = homedir(), cleanTemps = true) {
+    const directory = runsDirectory(cwd, sessionId, home);
+    try {
+        const entries = await readdir(directory, { withFileTypes: true });
+        if (cleanTemps)
+            await cleanupRunTemps(directory, entries);
+        return entries.filter((entry) => entry.isDirectory() && !entry.name.startsWith(".")).map(({ name }) => name);
+    }
+    catch (error) {
+        if (isNodeError(error, "ENOENT"))
+            return [];
+        throw error;
+    }
+}

package/dist/src/store.d.ts

@@ -0,0 +1,95 @@
+import { type JsonValue, type LaunchSnapshot, type WorkflowRunEvent } from "./types.js";
+import { type AwaitingCheckpoint, type BorrowedWorktreeBinding, type CompletedOperation, type EffectiveSystemPrompt, type PendingWorkflowDecision, type PersistedOwnershipNode, type PersistedRun, type RunSummary, type WorktreeReference } from "./decoders.js";
+export declare class RunStore {
+    #private;
+    readonly cwd: string;
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly home: string;
+    readonly directory: string;
+    private journalLane;
+    private stateLane;
+    private summaryLane;
+    private worktreeLane;
+    private borrowedWorktreeLane;
+    private snapshotLane;
+    private launchSnapshotLane;
+    private systemPromptLane;
+    constructor(cwd: string, sessionId: string, runId: string, home?: string);
+    create(run: PersistedRun, snapshot: Readonly<LaunchSnapshot>): Promise<void>;
+    private refreshSummary;
+    private refreshSummaryBestEffort;
+    isComplete(): Promise<boolean>;
+    load(): Promise<{
+        run: PersistedRun;
+        snapshot: Readonly<LaunchSnapshot>;
+    }>;
+    loadStatus(): Promise<PersistedRun>;
+    loadSummary(): Promise<RunSummary>;
+    saveState(run: PersistedRun): Promise<void>;
+    updateState(update: (run: PersistedRun) => PersistedRun | Promise<PersistedRun>): Promise<PersistedRun>;
+    saveSnapshot(snapshot: Readonly<LaunchSnapshot>): Promise<void>;
+    appendEvent(event: WorkflowRunEvent): Promise<void>;
+    saveOwnership(nodes: readonly PersistedOwnershipNode[]): Promise<void>;
+    loadOwnership(): Promise<readonly PersistedOwnershipNode[]>;
+    systemPromptPath(): string;
+    private readSystemPromptArtifact;
+    private appendSystemPromptV2;
+    private migrateSystemPrompts;
+    private prepareSystemPromptStorage;
+    private readSystemPromptsV2;
+    recordSystemPrompt(entry: Omit<EffectiveSystemPrompt, "sha256">): Promise<void>;
+    systemPrompts(): Promise<readonly EffectiveSystemPrompt[]>;
+    private updateJournal;
+    complete(path: string, value: JsonValue): Promise<void>;
+    replay(path: string): Promise<CompletedOperation | undefined>;
+    replayableOperations(): Promise<readonly CompletedOperation[]>;
+    /** Every journaled agent operation of the retry lineage, mapped to its session file when one was recorded. */
+    agentSessionFiles(): Promise<ReadonlyMap<string, string | undefined>>;
+    private agentSessionFilesFrom;
+    /** Source lineage first, own journal last (it overrides); `path` narrows to one operation without cloning the rest. */
+    private replayableOperationsFrom;
+    awaitCheckpoint(checkpoint: AwaitingCheckpoint): Promise<boolean | undefined>;
+    awaitingCheckpoints(): Promise<readonly AwaitingCheckpoint[]>;
+    requestWorkflowDecision(request: PendingWorkflowDecision): Promise<void>;
+    pendingWorkflowDecisions(): Promise<readonly PendingWorkflowDecision[]>;
+    answerWorkflowDecision(proposalId: string, approved: boolean): Promise<PendingWorkflowDecision | undefined>;
+    answerCheckpoint(name: string, approved: boolean): Promise<AwaitingCheckpoint | undefined>;
+    private expectedWorktree;
+    private markerPath;
+    private namedWorktreeOwner;
+    private worktreeName;
+    private runWorktreePostCreateCommand;
+    private structuralWorktree;
+    private borrowedWorktreeRecords;
+    borrowedWorktrees(): Promise<readonly BorrowedWorktreeBinding[]>;
+    private borrowedWorktree;
+    private sourceRun;
+    validateParentRun(parentRunId: string): Promise<void>;
+    validateRetrySource(): Promise<void>;
+    private ownedWorktree;
+    private resolveBorrowedWorktree;
+    private findNamedWorktree;
+    resolveNamedWorktree(name: string, seen?: Set<string>): Promise<{
+        reference: WorktreeReference;
+        sourceRunId: string;
+        owner: string;
+    }>;
+    validateDeletionWorktrees(): Promise<void>;
+    validateBorrowedWorktrees(): Promise<void>;
+    validateNamedWorktrees(): Promise<void>;
+    ownsWorktree(owner: string): Promise<boolean>;
+    private cleanupMarker;
+    private cleanupOrphanWorktrees;
+    validateWorktree(owner: string, cwd?: string): Promise<WorktreeReference>;
+    worktree(owner: string): Promise<WorktreeReference>;
+    private resolveNamedWorktreeFromParent;
+    private bindBorrowedWorktree;
+    snapshotWorktree(owner: string): Promise<string>;
+    worktrees(): Promise<readonly WorktreeReference[]>;
+    validNamedWorktrees(): Promise<readonly string[]>;
+    changedWorktrees(): Promise<readonly WorktreeReference[]>;
+    saveResult(value: JsonValue): Promise<string>;
+    resultBytes(): Promise<number>;
+    delete(confirmed: boolean): Promise<void>;
+}