jorel/dist/agents/task-execution.d.ts

A unified wrapper for working with LLMs from multiple providers, including streams, images, documents & automatic tool use.

import { LlmToolCall } from "../providers";
import { JorElAgentManager } from "../jorel/jorel.team";
import { TaskExecutionThread, TaskExecutionThreadDefinition } from "./task-execution-thread";
import { TaskExecutionThreadEvent } from "./task-execution-thread-event";
import { LLmToolContextSegment } from "../tools";
import { Nullable } from "../shared";
import { JorElTaskInput } from "../jorel";
/** Thrown when a task creation fails */
export declare class TaskCreationError extends Error {
    constructor(message: string);
}
/** Thrown when a task execution fails */
export declare class TaskExecutionError extends Error {
    readonly taskId: string;
    constructor(message: string, taskId: string);
}
export type TaskExecutionStatus = "pending" | "running" | "halted" | "completed";
export type TaskExecutionHaltingReason = "maxIterations" | "maxGenerations" | "maxDelegations" | "approvalRequired" | "invalidState" | "error" | "completed";
export declare const __mainTaskExecutionThreadId = "__main__";
export interface TaskExecutionEnvironment {
    context?: LLmToolContextSegment;
    secureContext?: LLmToolContextSegment;
    limits?: {
        maxIterations?: number;
        maxGenerations?: number;
        maxDelegations?: number;
    };
}
export interface TaskExecutionDefinition {
    id: string;
    status: TaskExecutionStatus;
    threads: {
        [threadId: string]: TaskExecutionThreadDefinition;
    };
    activeThreadId: string;
    stats: {
        generations: number;
        delegations: number;
    };
    modified: boolean;
    haltReason: Nullable<TaskExecutionHaltingReason>;
}
/**
 * Represents a task execution that manages multiple threads and their events.
 */
export declare class TaskExecution implements TaskExecutionDefinition {
    readonly id: string;
    threads: {
        [threadId: string]: TaskExecutionThread;
    };
    readonly stats: {
        generations: number;
        delegations: number;
    };
    /**
     * Create a new task execution
     * @param data - The task execution definition
     * @param jorEl - The agent manager instance
     */
    constructor(data: TaskExecutionDefinition, jorEl: JorElAgentManager);
    /**
     * Get the task execution definition
     */
    get status(): TaskExecutionStatus;
    /**
     * Set the task execution status
     */
    set status(status: TaskExecutionStatus);
    /**
     * Get the active thread ID
     */
    get activeThreadId(): string;
    /**
     * Set the active thread ID
     */
    set activeThreadId(threadId: string);
    /**
     * Whether this task execution (or any thread) has been modified
     */
    get modified(): boolean;
    /**
     * Set the modified state of this task execution
     */
    set modified(modified: boolean);
    /**
     * Get the reason for halting the task execution
     */
    get haltReason(): Nullable<TaskExecutionHaltingReason>;
    /**
     * Set the reason for halting the task execution
     */
    set haltReason(reason: Nullable<TaskExecutionHaltingReason>);
    /**
     * Events for this task execution along with aggregated usage statistics
     */
    get eventsWithStatistics(): {
        events: (TaskExecutionThreadEvent & {
            threadId: string;
            parentThreadId: Nullable<string>;
        })[];
        stats: {
            generations: number;
            delegations: number;
        };
        tokens: {
            [model: string]: {
                input: number;
                output: number;
            };
        };
    };
    /**
     * Get the result of the task execution
     */
    get result(): Nullable<string>;
    /**
     * Get the active thread for this task execution
     */
    get activeThread(): TaskExecutionThread;
    /**
     * Get the task execution definition
     */
    get definition(): TaskExecutionDefinition;
    /**
     * Get all events for this task execution
     */
    get events(): (TaskExecutionThreadEvent & {
        threadId: string;
        parentThreadId: Nullable<string>;
    })[];
    /**
     * Create a new instance of this execution - e.g. to avoid modifying the original
     */
    get copy(): TaskExecution;
    /**
     * Get the tool calls with pending approvals for this task execution
     */
    get toolCallsWithPendingApprovals(): (LlmToolCall & {
        messageId: string;
        threadId: string;
    })[];
    /**
     * Generate a new task execution from a task description
     * @param task
     * @param agentId
     * @param jorEl
     */
    static fromTask(task: JorElTaskInput, agentId: string, jorEl: JorElAgentManager): Promise<TaskExecution>;
    /**
     * Add a follow-up user message to the main thread
     * @param message
     */
    addFollowUpUserMessage(message: string): Promise<TaskExecution>;
    /**
     * Get events by thread
     * @param threadId
     */
    getEventsByThread(threadId?: string): (TaskExecutionThreadEvent & {
        threadId: string;
        parentThreadId: Nullable<string>;
    })[];
    /**
     * Halt the task execution
     * @param reason The reason for halting the task execution.
     * Can be one of
     * - `maxIterations`:    The task execution has reached the maximum number of iterations (steps). This is useful to prevent infinite loops.
     * - `maxGenerations`:   The task execution has reached the maximum number of generations (model calls). This can be used to control the cost of the task execution.
     * - `maxDelegations`:   The task execution has reached the maximum number of delegations. This can be used to prevent excessive delegation.
     * - `approvalRequired`: The task execution contains tool-calls which requires approval.
     * - `invalidState`:     The task execution is in an invalid state.
     * - `error` :           The task execution has encountered an error.
     */
    halt(reason: TaskExecutionHaltingReason): TaskExecution;
}