import { type PreviousOutput } from './engine/task-context'; import { type RouteDecision, type RoutingContext } from './engine/task-routing'; import { type FileReader } from './engine/task-input-file'; import { type ImageFileSystem, type MessageContentPart } from './engine/task-messages'; import { type HandlerContext, type HandlerResult } from './engine/task-handler'; import { type ResolveAgentOptions } from './engine/task-agent'; import { type MemoryFactory, type TaskMemoryStore } from './engine/task-memory'; import type { ResponseCache, TaskHooks } from './engine/types'; /** * Result of running a task. Mirrors Python `praisonaiagents.output.models.TaskOutput`. */ export interface TaskOutput { /** The task description the output answers. */ description: string; /** Raw text produced by the agent. */ raw: string; /** Name of the agent that produced the output. */ agent: string; /** Optional short summary of `raw`. */ summary?: string; /** Parsed JSON output when `outputJson` was requested. */ outputJson?: Record; /** Parsed structured output when `outputPydantic` was requested. */ outputPydantic?: unknown; /** Which form the output took. */ outputFormat?: 'RAW' | 'JSON' | 'Pydantic'; /** Message of a callback that failed (set by `Task.notifyComplete`). */ callbackError?: string; /** Non-fatal errors accumulated while finishing the task. */ nonFatalErrors?: string[]; } /** * Python parity: the metadata dict `Task._execute_callback_with_metadata` * hands to a callback that declares a second parameter. It is the only place * `loopState`, `inputFile`, `taskType` and `asyncExecution` reach user code. */ export interface TaskCallbackMetadata { taskId: number | string; taskName?: string; agentName?: string; taskType: string; taskStatus: string; taskDescription: string; expectedOutput: string; inputFile?: string; loopState: Record; retryCount: number; asyncExecution: boolean; } /** * A task completion callback; sync or async. A callback that declares a second * parameter also receives {@link TaskCallbackMetadata}, as in Python. */ export type TaskCallback = (output: TaskOutput, metadata?: TaskCallbackMetadata) => unknown | Promise; /** * A guardrail: either a validator returning `[ok, payload]` (sync or async) * or a natural-language description evaluated by an LLM (engine-level). */ export type TaskGuardrail = ((output: TaskOutput) => [boolean, unknown] | Promise<[boolean, unknown]>) | string; /** Flow control applied when a task fails. */ export type TaskOnError = 'stop' | 'continue' | 'retry'; /** Task lifecycle statuses (Python `TaskStatus`). Any other string is accepted too. */ export declare const TASK_STATUS: { readonly NOT_STARTED: "not started"; readonly IN_PROGRESS: "in progress"; readonly COMPLETED: "completed"; readonly FAILED: "failed"; readonly CANCELLED: "cancelled"; }; export interface TaskConfig { /** Python parity: name (Optional[str], default None). */ name?: string; /** Python parity: description (Optional[str], default None). Required unless `action` or `handler` is given. */ description?: string; /** Python parity: expected_output (Optional[str], default None → "Complete the task successfully"). */ expected_output?: string; /** Python parity: agent (Optional[Agent], default None). */ agent?: any; /** TS alias for Python `context` / `depends_on`: the tasks whose results feed this one. */ dependencies?: Task[]; /** Python parity: context (Optional[List[Union[str, List, Task]]], default None). Feeds `dependencies`. */ context?: (string | Task)[]; /** Python parity: depends_on (Optional[List[Union[str, List, Task]]], default None). Alias for `context`; takes precedence. */ dependsOn?: Task[]; /** Python parity: tools (Optional[List[Any]], default None). */ tools?: any[]; /** Python parity: async_execution (Optional[bool], default False). */ asyncExecution?: boolean; /** Python parity: config (Optional[Dict[str, Any]], default None). */ config?: Record; /** Python parity: output_file (Optional[str], default None). */ outputFile?: string; /** Python parity: output_json (Optional[Type[BaseModel]], default None). A schema for JSON output. */ outputJson?: unknown; /** Python parity: output_pydantic (Optional[Type[BaseModel]], default None). A schema for structured output. */ outputPydantic?: unknown; /** Python parity: callback (Optional[Callable[[TaskOutput], Any]], default None). Deprecated in Python; use `onTaskComplete`. */ callback?: TaskCallback; /** Python parity: on_task_complete (Optional[Callable[[TaskOutput], Any]], default None). */ onTaskComplete?: TaskCallback; /** Python parity: status (str, default "not started"). */ status?: string; /** Python parity: result (Optional[TaskOutput], default None). */ result?: TaskOutput | string | null; /** Python parity: create_directory (Optional[bool], default False). */ createDirectory?: boolean; /** Python parity: id (Optional[int], default None → uuid4). */ id?: number | string; /** Python parity: images (Optional[List[str]], default None). */ images?: string[]; /** Python parity: next_tasks (Optional[List[str]], default None). */ nextTasks?: string[]; /** Python parity: task_type (str, default "task"). */ taskType?: string; /** * Require a person to approve this task's OUTPUT before the next task * consumes it. Python parity: `Task(human_input=True)`. * * Distinct from the approval system, which gates a TOOL CALL, and from * guardrails, which validate automatically. Neither lets an orchestrator * say "a person must sign this off". */ humanInput?: boolean; /** What the reviewer is asked. Python parity: `human_review_prompt`. */ humanReviewPrompt?: string; /** Python parity: condition (Optional[Dict[str, List[str]]], default None). */ condition?: Record; /** Python parity: is_start (bool, default False). */ isStart?: boolean; /** Python parity: loop_state (Optional[Dict[str, Union[str, int]]], default None). */ loopState?: Record; /** Python parity: memory (Any, default None). */ memory?: unknown; /** Python parity: quality_check (bool, default True). */ qualityCheck?: boolean; /** Python parity: input_file (Optional[str], default None). */ inputFile?: string; /** Python parity: rerun (bool, default False). */ rerun?: boolean; /** Python parity: retain_full_context (bool, default False). */ retainFullContext?: boolean; /** Python parity: guardrail (Optional[Union[Callable[[TaskOutput], Tuple[bool, Any]], str]], default None). Deprecated in Python; use `guardrails`. */ guardrail?: TaskGuardrail; /** Python parity: guardrails (Optional[Union[Callable[[TaskOutput], Tuple[bool, Any]], str]], default None). */ guardrails?: TaskGuardrail; /** Python parity: max_retries (int, default 3). */ maxRetries?: number; /** Python parity: retry_count (int, default 0). */ retryCount?: number; /** Python parity: agent_config (Optional[Dict[str, Any]], default None). */ agentConfig?: Record; /** Python parity: variables (Optional[Dict[str, Any]], default None). */ variables?: Record; /** Python parity: skip_on_failure (bool, default False). */ skipOnFailure?: boolean; /** Python parity: retry_delay (float, default 0.0). Seconds. */ retryDelay?: number; /** Python parity: on_error (str, default "stop"). */ onError?: TaskOnError; /** Python parity: action (Optional[str], default None). Alias for `description`. */ action?: string; /** Python parity: handler (Optional[Callable], default None). Custom function run instead of an agent. */ handler?: (...args: unknown[]) => unknown; /** Python parity: should_run (Optional[Callable], default None). */ shouldRun?: () => boolean | Promise; /** Python parity: loop_over (Optional[str], default None). */ loopOver?: string; /** Python parity: loop_var (str, default "item"). */ loopVar?: string; /** Python parity: execution (Optional[Any], default None). */ execution?: unknown; /** Python parity: routing (Optional[Dict[str, List[str]]], default None). */ routing?: Record; /** Python parity: output_config (Optional[Any], default None). */ outputConfig?: unknown; /** Python parity: output (Optional[Any], default None). Unified output: file path, schema, or `{file, json, pydantic, variable}`. */ output?: unknown; /** Python parity: when (Optional[str], default None). */ when?: string; /** Python parity: then_task (Optional[str], default None). */ thenTask?: string; /** Python parity: else_task (Optional[str], default None). */ elseTask?: string; /** Python parity: autonomy (Optional[Any], default None). */ autonomy?: unknown; /** Python parity: knowledge (Optional[Any], default None). */ knowledge?: unknown; /** Python parity: web (Optional[Any], default None). */ web?: unknown; /** Python parity: reflection (Optional[Any], default None). */ reflection?: unknown; /** Python parity: planning (Optional[Any], default None). */ planning?: unknown; /** Python parity: hooks (Optional[Any], default None). */ hooks?: unknown; /** Python parity: caching (Optional[Any], default None). */ caching?: unknown; /** Python parity: output_variable (Optional[str], default None). */ outputVariable?: string; /** Python parity: fail_on_callback_error (bool, default False). */ failOnCallbackError?: boolean; /** Python parity: fail_on_memory_error (bool, default False). */ failOnMemoryError?: boolean; } export declare class Task { name?: string; description: string; expected_output: string; agent: any; dependencies: Task[]; /** Python parity: context — every context item (strings and tasks), `dependsOn` winning over `context`. */ context: (string | Task)[]; /** Python parity: result (Optional[TaskOutput], default None). */ result: TaskOutput | string | null; /** Python parity: tools (Optional[List[Any]], default None). */ tools: any[]; /** Python parity: async_execution (Optional[bool], default False). */ asyncExecution: boolean; /** Python parity: config (Optional[Dict[str, Any]], default None). */ config: Record; /** Python parity: output_file (Optional[str], default None). */ outputFile?: string; /** Python parity: output_json (Optional[Type[BaseModel]], default None). */ outputJson?: unknown; /** Python parity: output_pydantic (Optional[Type[BaseModel]], default None). */ outputPydantic?: unknown; /** Python parity: callback (Optional[Callable], default None). */ callback?: TaskCallback; /** Python parity: on_task_complete (Optional[Callable], default None). */ onTaskComplete?: TaskCallback; /** Python parity: status (str, default "not started"). */ status: string; /** Python parity: create_directory (Optional[bool], default False). */ createDirectory: boolean; /** Python parity: id (Optional[int], default None → uuid4). */ id: number | string; /** Python parity: images (Optional[List[str]], default None). */ images: string[]; /** Python parity: next_tasks (Optional[List[str]], default None). */ nextTasks: string[]; /** Python parity: task_type (str, default "task"). */ taskType: string; /** See {@link TaskConfig.humanInput}. */ humanInput: boolean; /** See {@link TaskConfig.humanReviewPrompt}. */ humanReviewPrompt?: string; /** Python parity: condition (Optional[Dict[str, List[str]]], default None). */ condition: Record; /** Python parity: is_start (bool, default False). */ isStart: boolean; /** Python parity: loop_state (Optional[Dict[str, Union[str, int]]], default None). */ loopState: Record; /** Python parity: memory (Any, default None). */ memory?: unknown; /** Python parity: quality_check (bool, default True). */ qualityCheck: boolean; /** Python parity: input_file (Optional[str], default None). */ inputFile?: string; /** Python parity: rerun (bool, default False). */ rerun: boolean; /** Python parity: retain_full_context (bool, default False). */ retainFullContext: boolean; /** Python parity: guardrail — the resolved guardrail (`guardrails` wins over `guardrail`). */ guardrail?: TaskGuardrail; /** Python parity: guardrails (canonical name); same value as `guardrail`. */ guardrails?: TaskGuardrail; /** Python parity: max_retries (int, default 3). */ maxRetries: number; /** Python parity: retry_count (int, default 0). */ retryCount: number; /** Python parity: agent_config (Optional[Dict[str, Any]], default None). */ agentConfig?: Record; /** Python parity: variables (Optional[Dict[str, Any]], default None). */ variables: Record; /** Python parity: skip_on_failure (bool, default False). */ skipOnFailure: boolean; /** Python parity: retry_delay (float, default 0.0). */ retryDelay: number; /** Python parity: on_error (str, default "stop"). */ onError: TaskOnError; /** Python parity: action (Optional[str], default None). Always mirrors `description` once resolved. */ action?: string; /** Python parity: handler (Optional[Callable], default None). */ handler?: (...args: unknown[]) => unknown; /** Python parity: should_run (Optional[Callable], default None). */ shouldRun?: () => boolean | Promise; /** Python parity: loop_over (Optional[str], default None). */ loopOver?: string; /** Python parity: loop_var (str, default "item"). */ loopVar: string; /** Python parity: execution (Optional[Any], default None). */ execution?: unknown; /** Python parity: routing (Optional[Dict[str, List[str]]], default None). Mirrors `condition` like Python. */ routing: Record; /** Python parity: output_config (Optional[Any], default None). */ outputConfig?: unknown; /** Python parity: output (Optional[Any], default None). The original unified output value. */ output?: unknown; /** Python parity: when (Optional[str], default None). */ when?: string; /** Python parity: then_task (Optional[str], default None). */ thenTask?: string; /** Python parity: else_task (Optional[str], default None). */ elseTask?: string; /** Python parity: autonomy (Optional[Any], default None). */ autonomy?: unknown; /** Python parity: knowledge (Optional[Any], default None). */ knowledge?: unknown; /** Python parity: web (Optional[Any], default None). */ web?: unknown; /** Python parity: reflection (Optional[Any], default None). */ reflection?: unknown; /** Python parity: planning (Optional[Any], default None). */ planning?: unknown; /** Python parity: hooks (Optional[Any], default None). */ hooks?: unknown; /** Python parity: caching (Optional[Any], default None). */ caching?: unknown; /** Python parity: output_variable (Optional[str], default None). */ outputVariable?: string; /** Python parity: fail_on_callback_error (bool, default False). */ failOnCallbackError: boolean; /** Python parity: fail_on_memory_error (bool, default False). */ failOnMemoryError: boolean; /** Python parity: non_fatal_errors — errors that did not stop the task (callback failures etc). */ nonFatalErrors: string[]; /** Python parity: validation_feedback — last guardrail failure, fed back on retry. */ validationFeedback?: unknown; /** Python parity: previous_tasks — names of the tasks whose `nextTasks` lead here. */ previousTasks: string[]; /** `hooks` resolved to the callbacks fired around this task, when it named any. */ resolvedHooks?: TaskHooks; /** `caching` resolved to a per-task response cache, when it is enabled. */ cache?: ResponseCache; constructor(config: TaskConfig); /** * Python parity: an `execution` config object can carry `asyncExec`, * `qualityCheck`, `maxRetries`, `rerun` and `onError`. Direct params win * when explicitly set; `onError` from the config always wins (as in Python). */ private resolveExecutionConfig; /** * Python parity: the unified `output` param consolidates output_file, * output_json, output_pydantic and output_variable. A string is a file * path; `{file, json, pydantic, variable}` sets the matching fields; any * other value is treated as a JSON output schema. */ private resolveUnifiedOutput; /** Whether moving from the current status to `next` is a legal lifecycle transition. */ canTransitionTo(next: string): boolean; /** * Python parity: `set_status`. Illegal transitions are logged but still * applied, for backward compatibility with raw string usage. */ setStatus(next: string): void; markStarted(): void; markCompleted(result?: TaskOutput | string): void; markFailed(): void; markCancelled(): void; get isTerminal(): boolean; /** True while `retryCount` is below `maxRetries`. */ canRetry(): boolean; /** Bump `retryCount` (the engine calls this before re-running). Returns the new count. */ recordRetry(): number; /** * Python parity: `retry_delay`. Seconds to wait before retry `attempt` * (0-based), doubling each time and capped at five minutes. A task with the * default `retryDelay` of 0 never waits. */ retryDelayFor(attempt: number): number; /** Sleep `retryDelayFor(attempt)` seconds. `timer` is injectable for tests. */ waitBeforeRetry(attempt: number, timer?: (fn: () => void, ms: number) => unknown): Promise; /** * Python parity: `skip_on_failure` / `on_error` * (`Agents._should_continue_on_dep_failure`). True when this task still runs, * in degraded mode, after an upstream dependency failed. */ continuesOnDependencyFailure(): boolean; /** * Python parity: `rerun`. Whether the runner should execute this task now — * false for a task that already completed unless `rerun` was requested. */ needsRun(): boolean; /** * Python parity: `retain_full_context` (`Process._build_task_context`). * Assemble the upstream context block for this task: every previous result * when `retainFullContext` is set, only the most recent one otherwise. * Consumes `validationFeedback`, so it is injected exactly once. */ buildContext(previous?: readonly PreviousOutput[]): string; /** True when this task uses the unified `when`/`thenTask`/`elseTask` routing. */ hasRouting(): boolean; /** Python parity: `evaluate_when`. A task without a `when` always passes. */ evaluateWhen(context?: RoutingContext): boolean; /** * Python parity: `get_next_task` plus the `condition`/`routing` and * `nextTasks` fallbacks the workflow engine applies. Returns the routing * decision: a named task, `exit`, or nothing. */ routeAfter(context?: RoutingContext): RouteDecision; /** The name of the task to run next, or `undefined` for exit / no route. */ nextTaskFor(context?: RoutingContext): string | undefined; /** * Python parity: `loop_over` / `loop_var` / `loop_state` * (`Workflows._run_step_loop`). One child task per item of the named * variable, with `loopVar` bound in the child's `variables` and the * position recorded on its `loopState`. `[]` when there is no loop. */ expandLoop(variables?: Record): Task[]; /** * Python parity: `input_file` (`Process._create_loop_subtasks`). One child * task per CSV row or text line, chained with `nextTasks`, the first flagged * `isStart` and the last inheriting this task's `nextTasks`. `[]` when the * task has no `inputFile`. */ expandFromInputFile(options?: { decisionMode?: boolean; readFile?: FileReader; }): Task[]; /** * Python parity: `handler` (`Workflows._run_step`). Run the task's own * function instead of an agent. `undefined` when there is no handler, so the * caller falls through to the agent path. */ runHandler(context: HandlerContext): Promise; /** * Python parity: `agent_config` (`Agents._create_agent_from_config`). The * agent that executes this task; a constructed one is assigned to `agent`. */ resolveAgent(options?: ResolveAgentOptions): unknown | undefined; /** * Python parity: `images` (`get_multimodal_message`). The message content for * `prompt`: plain text without images, a content list with one `image_url` * part per image with them. */ buildMessageContent(prompt: string, fileSystem?: ImageFileSystem): string | MessageContentPart[]; /** * Python parity: `_process_task_result`. Wrap `raw` in a TaskOutput, parsing * it when the task asked for `outputJson` or `outputPydantic`. */ buildOutput(raw: string, agentName?: string): TaskOutput; /** Python parity: `config` — the verbosity level a `config.verbose` requested. */ get verboseLevel(): number; /** * Python parity: `memory` plus `config.memory_config` (`initialize_memory`). * The task's store, created from `config.memory_config` on first use. */ initializeMemory(factory?: MemoryFactory): TaskMemoryStore | undefined; /** * Python parity: `store_in_memory`. Store `content` in the task's memory. * A failure lands on `nonFatalErrors` and is swallowed unless * `failOnMemoryError` is set. Returns whether anything was stored. */ storeInMemory(content: string, agentName?: string, factory?: MemoryFactory): Promise; /** Python parity: `memory` — recall related entries for the next prompt. */ memoryContext(query: string, maxItems?: number, factory?: MemoryFactory): Promise; /** Python parity: `knowledge` — the knowledge block for this task's prompt. */ knowledgeContext(query: string, limit?: number): Promise; /** * Python parity: `hooks` — fire this task's `onTaskStart` hook. A task * without hooks does nothing. */ notifyStart(index?: number): Promise; /** The workflow variable this task's output is stored under: `outputVariable`, else `name`. */ get outputVariableName(): string | undefined; /** `description` with `{{key}}` placeholders replaced from `variables` (then `extra`). */ renderDescription(extra?: Record): string; /** * Write `content` to `outputFile` (creating the parent directory when * `createDirectory` is set). Returns the resolved path, or undefined when * the task has no output file. */ writeOutput(content: string): string | undefined; /** Run `shouldRun` if present; a task without one always runs. */ shouldExecute(): Promise; /** * Run a callable guardrail against `output`. Returns `[ok, payload]`; * a failing result is remembered in `validationFeedback` for the retry * prompt. String guardrails (LLM-judged) and absent guardrails pass. */ runGuardrail(output: TaskOutput): Promise<[boolean, unknown]>; /** * Python parity: `execute_callback`. Awaits `callback` and `onTaskComplete` * (either may be sync or async). A throwing callback is recorded on * `nonFatalErrors` and `output.callbackError`; it is rethrown only when * `failOnCallbackError` is set. */ notifyComplete(output: TaskOutput): Promise; /** * Python parity: the metadata dict handed to a two-parameter callback * (`_execute_callback_with_metadata`). */ callbackMetadata(): TaskCallbackMetadata; toString(): string; } export interface TaskAgentConfig { name: string; role: string; goal: string; backstory: string; verbose?: boolean; llm?: string; markdown?: boolean; } export declare class Agent { private name; private role; private goal; private backstory; private verbose; private llm; private markdown; private result; constructor(config: TaskAgentConfig); execute(task: Task, dependencyResults?: any[]): Promise; } export interface TaskAgentTeamConfig { agents: Agent[]; tasks: Task[]; verbose?: boolean; process?: 'sequential' | 'parallel' | 'hierarchical'; manager_llm?: string; } /** * @deprecated Use TaskAgentTeamConfig instead */ export type TaskPraisonAIAgentsConfig = TaskAgentTeamConfig; export declare class TaskAgentTeam { private agents; private tasks; private verbose; private process; private manager_llm; constructor(config: TaskAgentTeamConfig); start(): Promise; private executeSequential; private executeHierarchical; } export type { TaskAgentConfig as AgentConfig };