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

package/dist/src/agent-execution.d.ts

@@ -0,0 +1,338 @@
+import { DefaultResourceLoader, ModelRuntime } from "@earendil-works/pi-coding-agent";
+import type { ExtensionContext, ModelRegistry, ToolDefinition } from "@earendil-works/pi-coding-agent";
+type HerdrModelContext = {
+    readonly model: ExtensionContext["model"];
+    readonly modelRegistry: ModelRegistry | undefined;
+};
+type AgentMessage = {
+    role: string;
+    content?: unknown;
+    stopReason?: string;
+    errorMessage?: string;
+    usage?: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        cost: {
+            total: number;
+        };
+    };
+};
+export interface PiSession {
+    readonly sessionId: string;
+    readonly sessionFile: string | undefined;
+    readonly messages: readonly AgentMessage[];
+    getSessionStats(): {
+        tokens: {
+            input: number;
+            output: number;
+            cacheRead: number;
+            cacheWrite: number;
+            total: number;
+        };
+        cost: number;
+    };
+    readonly systemPrompt?: string;
+    readonly model?: {
+        provider: string;
+        model?: string;
+        id?: string;
+    } | undefined;
+    readonly herdrModelContext?: HerdrModelContext;
+    readonly thinkingLevel?: string;
+    readonly agent?: {
+        state: {
+            tools: readonly {
+                name: string;
+            }[];
+        };
+        subscribe?(listener: (event: unknown) => void | Promise<void>): () => void;
+    };
+    readonly herdrResourcePaths?: {
+        extensions: readonly string[];
+        skills: readonly string[];
+    };
+    readonly herdrContextFiles?: readonly import("./types.js").ContextFile[];
+    preparePrompt(text: string): Promise<PiPromptInspection>;
+    getResourceInspection(): PiResourceInspection;
+    subscribe?(listener: (event: unknown) => void): () => void;
+    prompt(text: string): Promise<void>;
+    steer?(text: string): Promise<void>;
+    abort?(): Promise<void>;
+    dispose(): Promise<void>;
+}
+export interface PiPromptInspection {
+    readonly prompt: string;
+    readonly expandedPrompt: string;
+    readonly systemPrompt: string;
+    readonly messages: readonly unknown[];
+    readonly systemPromptOptions: unknown;
+    readonly inputHandled: boolean;
+    readonly diagnostics: readonly {
+        type: "error";
+        message: string;
+        source?: string;
+    }[];
+}
+export interface PiResourceInspection {
+    readonly extensions: readonly string[];
+    readonly skills: readonly string[];
+    readonly diagnostics: readonly {
+        type: "warning" | "error" | "collision";
+        message: string;
+        source?: string;
+    }[];
+    readonly systemPromptSource?: string;
+}
+import type { AgentAccounting, AgentActivity, AgentContinuity, AgentIdentity, AgentResourcePolicy, AgentResourceSelectors, AgentSetup, AgentSetupSummary, AgentTransport, AgentTransportContext, ContextFileScope, JsonSchema, JsonValue, LiveSessionHandoff, ModelSpec, PreparedAgentSession, RegisteredAgentSetupHook, SessionInput, WorkflowAgentSession, WorkflowAgentSessionReference, WorkflowAgentSessionState, WorkflowExtensionSettings, WorkflowExtensionSettingsValidatorContext, WorkflowRunContext } from "./types.js";
+import { type AgentDefinition, type AgentState } from "./types.js";
+import type { RunStore } from "./persistence.js";
+type AgentExecutionRunStore = Pick<RunStore, "recordSystemPrompt" | "validateWorktree" | "worktree" | "snapshotWorktree">;
+export type { AgentAccounting, AgentActivity, AgentInspectionMode, AgentSetup, AgentSetupContext, AgentSetupHook, AgentTransport, AgentTransportContext, PiRuntimeLaunchInfo, PreparedAgentSession, RegisteredAgentSetupHook, SessionInput, WorkflowAgentMessage, WorkflowAgentSession, WorkflowAgentSessionEvent, WorkflowAgentSessionReference, WorkflowAgentSessionState, WorkflowAgentSessionStats, WorkflowAgentTurnResult } from "./types.js";
+export interface AgentBudgetHooks {
+    beforeAttempt(): void;
+    beforeTurn(): void;
+    afterTurn(accounting: AgentAccounting, final: boolean): void;
+    instruction(): string | undefined;
+}
+export type { AgentDefinition } from "./types.js";
+export interface AgentProviderFailure {
+    label: string;
+    provider: string;
+    model: string;
+    error: string;
+}
+export type AgentProviderRecovery = "retry" | "abort" | {
+    model: string;
+};
+export interface AgentExecutionOptions {
+    label: string;
+    workflowName: string;
+    tuiIndex?: number;
+    tuiLabel?: string;
+    phase?: string;
+    parent?: string;
+    model?: string;
+    onProgress?: (progress: AgentProgress) => void | Promise<void>;
+    onAttempt?: (attempt: AgentAttempt) => void | Promise<void>;
+    providerErrorRecovery?: (failure: AgentProviderFailure) => Promise<AgentProviderRecovery>;
+    modelOverride?: ModelSpec;
+    tools?: readonly string[];
+    skills?: readonly string[];
+    extensions?: readonly string[];
+    effectiveTools?: readonly string[];
+    role?: string;
+    contextFiles?: readonly ContextFileScope[];
+    schema?: JsonSchema;
+    retries?: number;
+    timeoutMs?: number | null;
+    retryState?: string;
+    worktreeOwner?: string;
+    cwd?: string;
+    sessionPath?: string;
+    budget?: AgentBudgetHooks;
+    agentOptions?: Readonly<Record<string, JsonValue>>;
+    agentIdentity?: AgentIdentity;
+    inheritedExtensionSettings?: Readonly<WorkflowExtensionSettings>;
+    agentNodeId?: string;
+}
+export interface AgentExecutionRoot {
+    cwd: string;
+    model: ModelSpec;
+    tools: ReadonlySet<string>;
+    extensionSettings?: Readonly<WorkflowExtensionSettings> | undefined;
+    validateExtensionSettings?: (settings: Readonly<WorkflowExtensionSettings> | undefined, context: WorkflowExtensionSettingsValidatorContext) => void;
+    onAgentSettings?: (agentNodeId: string, settings: Readonly<WorkflowExtensionSettings>) => void;
+    resourceSelectors?: AgentResourceSelectors;
+    agentDefinitions?: Readonly<Record<string, AgentDefinition>>;
+    agentDir?: string;
+    additionalSkillPaths?: readonly string[];
+    availableModels?: ReadonlySet<string>;
+    knownModels?: ReadonlySet<string>;
+    modelAliases?: Readonly<Record<string, string>>;
+    blockedAliases?: ReadonlySet<string>;
+    blockedAliasTargets?: Readonly<Record<string, string>>;
+    settingsPath?: string;
+    extensionSettingsPath?: string;
+    runStore?: AgentExecutionRunStore;
+    providerPause?: () => Promise<void>;
+    agentSetupHooks?: readonly RegisteredAgentSetupHook[];
+    agentResourcePolicy?: () => AgentResourcePolicy | Promise<AgentResourcePolicy>;
+    runContext?: Readonly<WorkflowRunContext>;
+    onResourceWarning?: (message: string) => void;
+}
+export interface AgentToolCallProgress {
+    id: string;
+    name: string;
+    state: "running" | "completed" | "failed";
+}
+export interface AgentProgress {
+    accounting: AgentAccounting;
+    toolCalls: readonly AgentToolCallProgress[];
+    state?: WorkflowAgentSessionState;
+    activity?: AgentActivity;
+    lastEventAt?: number;
+    persist: boolean;
+}
+export interface AgentAttempt {
+    attempt: number;
+    transport: string;
+    session?: WorkflowAgentSessionReference;
+    liveSession?: WorkflowAgentSession;
+    prepared?: Readonly<PreparedAgentSession>;
+    handoff?: LiveSessionHandoff;
+    result?: JsonValue;
+    error?: {
+        code: string;
+        message: string;
+    };
+    accounting: AgentAccounting;
+    setup: AgentSetupSummary;
+}
+export interface AgentExecutionResult {
+    value: JsonValue;
+    attempts: readonly AgentAttempt[];
+    cwd: string;
+}
+export declare function createLocalPiSession(input: SessionInput): Promise<PiSession>;
+/**
+ * Hands the runtime the providers that extensions registered while loading.
+ *
+ * An extension that adds models (a proxy front-end, a gateway) registers them
+ * from its factory, and the loader parks those registrations on the extension
+ * runtime rather than applying them. Pi's own session assembly drains that
+ * queue; a workflow agent builds its runtime here by hand, so without this the
+ * models an extension provides stay unknown and every agent asking for one
+ * fails with UNKNOWN_MODEL.
+ */
+export declare function flushExtensionProviders(resourceLoader: DefaultResourceLoader, modelRuntime: ModelRuntime): string[];
+export declare function createLocalWorkflowAgentSession(prepared: Readonly<PreparedAgentSession>, context: Readonly<AgentTransportContext>): Promise<WorkflowAgentSession>;
+export declare const localAgentTransport: AgentTransport;
+export type PreparedAgentSetup = {
+    setup: AgentSetup;
+    summary: AgentSetupSummary;
+    failure?: {
+        error: unknown;
+        hook?: string;
+    };
+};
+export declare function prepareAgentSetupForInspection(root: AgentExecutionRoot, task: string, options: AgentExecutionOptions, transport: AgentTransport): Promise<PreparedAgentSetup>;
+export declare function getAgentAttempts(error: unknown): readonly AgentAttempt[] | undefined;
+export declare class WorkflowAgentExecutor {
+    private readonly root;
+    private readonly transport;
+    private readonly warnedRoleTools;
+    constructor(root: AgentExecutionRoot, transport?: AgentTransport);
+    setRunContext(runContext: Readonly<WorkflowRunContext>): void;
+    resolve(options: AgentExecutionOptions, inheritedTools?: readonly string[]): {
+        model: ModelSpec;
+        requestedModel?: string;
+        tools: readonly string[];
+        systemPrompt?: string;
+        systemPromptAppend: string;
+        contextFiles?: readonly ContextFileScope[];
+    };
+    execute(task: string, options: AgentExecutionOptions, signal?: AbortSignal, customTools?: readonly ToolDefinition[], setSteer?: (handler: (message: string) => void | Promise<void>) => void, beforeRetry?: () => void): Promise<AgentExecutionResult>;
+}
+export interface ScheduledAgentOptions {
+    label: string;
+    requestedLabel?: string;
+    parentBreadcrumb?: string;
+    cwd: string;
+    tools: readonly string[];
+    skills?: readonly string[];
+    extensions?: readonly string[];
+    worktreeOwner?: string;
+    model?: string;
+    role?: string;
+    contextFiles?: readonly ContextFileScope[];
+    schema?: JsonSchema;
+    retries?: number;
+    timeoutMs?: number | null;
+    sessionPath?: string;
+    continuity?: AgentContinuity;
+    agentOptions?: Readonly<Record<string, JsonValue>>;
+    agentIdentity?: AgentIdentity;
+    extensionSettings?: Readonly<WorkflowExtensionSettings>;
+}
+export type ScheduledAgentResult = {
+    id: string;
+    ok: true;
+    value: JsonValue;
+} | {
+    id: string;
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+};
+export interface ScheduledAgentInput {
+    id: string;
+    runId: string;
+    tuiIndex: number;
+    parentId?: string;
+    prompt: string;
+    options: Readonly<ScheduledAgentOptions>;
+    signal: AbortSignal;
+    setSteer: (handler: (message: string) => void | Promise<void>) => void;
+}
+export type ScheduledAgentRunner = (input: ScheduledAgentInput) => Promise<JsonValue>;
+type ScheduledNode = {
+    id: string;
+    runId: string;
+    parentId?: string;
+    prompt?: string;
+    options: Readonly<ScheduledAgentOptions>;
+    children: Set<string>;
+    collected: boolean;
+    resultQueue: Promise<void>;
+    collecting: boolean;
+    state: AgentState;
+    controller: AbortController;
+    promise: Promise<ScheduledAgentResult> | undefined;
+    resolve: ((result: ScheduledAgentResult) => void) | undefined;
+    completion: Promise<void>;
+    resolveCompletion: () => void;
+    task: () => Promise<void>;
+    restored: boolean;
+    steer?: (message: string) => void | Promise<void>;
+};
+export type OwnershipRecord = {
+    id: string;
+    parentId?: string;
+    prompt?: string;
+    label: string;
+    state: ScheduledNode["state"];
+    options: Readonly<ScheduledAgentOptions>;
+};
+type OwnershipWriter = (runId: string, ownership: readonly OwnershipRecord[]) => void | Promise<void>;
+export declare class FairAgentScheduler {
+    #private;
+    private readonly runner;
+    readonly sessionLimit: number;
+    private readonly writeOwnership?;
+    constructor(runner: ScheduledAgentRunner, sessionLimit?: number, writeOwnership?: OwnershipWriter | undefined);
+    addRun(runId: string, limit?: number, beforeLaunch?: () => void, extensionSettings?: Readonly<WorkflowExtensionSettings>): void;
+    updateRunLimit(runId: string, limit: number): void;
+    setRunExtensionSettings(runId: string, settings: Readonly<WorkflowExtensionSettings> | undefined): void;
+    setExtensionSettings(agentId: string, settings: Readonly<WorkflowExtensionSettings>): void;
+    spawn(runId: string, prompt: string, options: ScheduledAgentOptions, parentId?: string): {
+        id: string;
+        result: Promise<ScheduledAgentResult>;
+    };
+    result(parentId: string, childId: string): Promise<ScheduledAgentResult>;
+    steer(parentId: string, childId: string, message: string): Promise<void>;
+    cancel(id: string): void;
+    releaseResult(id: string): void;
+    cancelChildren(id: string): void;
+    retry(id: string): void;
+    attemptStarted(id: string): void;
+    cancelRun(runId: string): Promise<void>;
+    removeRun(runId: string): void;
+    toolsFor(parentId: string, resolveTools?: (role: string | undefined, tools: readonly string[] | undefined, model: string | undefined, inheritedTools: readonly string[], skills: readonly string[] | undefined, extensions: readonly string[] | undefined) => readonly string[]): ToolDefinition[];
+    snapshot(): readonly OwnershipRecord[];
+    restoreRun(runId: string, limit: number, ownership: readonly OwnershipRecord[], beforeLaunch?: () => void, extensionSettings?: Readonly<WorkflowExtensionSettings>): void;
+    flush(runId?: string): Promise<void>;
+}