/** * Runtime registry for PraisonAI agents. * * Port of `praisonaiagents/runtime/registry.py`: a module-level registry of * runtime factories with aliases, metadata, a lazily-registered `praisonai` * builtin, and fail-closed resolution of unknown ids. * * Behaviour mirrored from Python: * - `register` throws on a duplicate id (Python `ValueError`). * - `register` does NOT initialise the builtins first, so a caller may * register its own `"praisonai"` before any lookup; the later builtin * initialisation skips ids that already exist. * - `resolve` / `addAlias` on an unknown id throw * `Unknown runtime: . Available: ['a', 'b']` (same text as Python). * - `isAvailable` swallows only registry errors (Python catches `ValueError` * only); an exception thrown by the factory itself propagates. * - `resolve` accepts `configOverrides` and — exactly like Python — does not * forward it to the factory; it is kept for signature parity. * - Python defines `list_names` and `is_available` twice on the class; the * later definitions win and are the ones ported. * * Not ported: entry-point discovery (`_discover_entry_point_runtimes`, the * `praisonai.runtimes` importlib group). Node has no equivalent of Python * entry points; plugin runtimes register explicitly via * {@link registerRuntime}. */ import { AgentRuntimeProtocol, RuntimeCapabilityMatrix, RuntimeDelta, RuntimeResult, RunTurnOptions } from './protocols'; /** Constructor options for {@link RuntimeRegistryEntry}. */ export interface RuntimeRegistryEntryInit { runtimeId: string; /** Default: `runtimeId`. */ displayName?: string | null; /** Default `null`. */ description?: string | null; /** Default `false`. */ isBuiltin?: boolean; /** Default `{}`. */ metadata?: Record | null; } /** Entry in the runtime registry (Python `registry.py::RuntimeRegistryEntry`). */ export declare class RuntimeRegistryEntry { runtimeId: string; displayName: string; description: string | null; isBuiltin: boolean; metadata: Record; constructor(config: RuntimeRegistryEntryInit); } /** A factory producing a runtime instance (Python `Callable[[], AgentRuntimeProtocol]`). */ export type RuntimeFactory = () => AgentRuntimeProtocol; /** * Error raised for invalid registry operations — duplicate registration, * unknown runtime id, alias to an unknown runtime. Python raises * `ValueError` for all three. */ export declare class RuntimeRegistryError extends Error { constructor(message: string); } /** Protocol for runtime registries (Python `registry.py::RuntimeRegistryProtocol`). */ export interface RuntimeRegistryProtocol { register(runtimeId: string, factoryOrInstance: RuntimeFactory | AgentRuntimeProtocol, metadata?: Record): void; unregister(runtimeId: string): boolean; isRegistered(runtimeId: string): boolean; listRuntimes(): RuntimeRegistryEntry[]; getEntry(runtimeId: string): RuntimeRegistryEntry | null; resolve(runtimeId: string, configOverrides?: Record | null): AgentRuntimeProtocol; clear(): void; } /** * Concrete runtime registry implementation (Python `registry.py::RuntimeRegistry`). * * All instances share the module-level state, exactly as in Python. */ export declare class RuntimeRegistry implements RuntimeRegistryProtocol { /** * Register a runtime (Python `register`). A non-function value is treated * as an instance and wrapped in a factory that always returns it. * * @throws RuntimeRegistryError if `runtimeId` is already registered. */ register(runtimeId: string, factoryOrInstance: RuntimeFactory | AgentRuntimeProtocol, metadata?: Record): void; /** Unregister a runtime and any aliases pointing to it (Python `unregister`). */ unregister(runtimeId: string): boolean; /** True if `runtimeId` (or an alias of it) is registered (Python `is_registered`). */ isRegistered(runtimeId: string): boolean; /** All registered runtime ids (Python `list_names`, later definition). */ listNames(): string[]; /** * True if the runtime resolves (Python `is_available`, later definition: * tries `resolve` and swallows only `ValueError`). */ isAvailable(runtimeId: string): boolean; /** All registered runtimes as entries (Python `list_runtimes`). */ listRuntimes(): RuntimeRegistryEntry[]; /** Registry entry for a runtime (or alias), or `null` (Python `get_entry`). */ getEntry(runtimeId: string): RuntimeRegistryEntry | null; /** * Resolve a runtime by id or alias (Python `resolve`). Fail-closed: an * unknown id throws {@link RuntimeRegistryError}. * * `configOverrides` is accepted for parity with Python, which also does * not forward it to the factory. */ resolve(runtimeId: string, configOverrides?: Record | null): AgentRuntimeProtocol; /** Clear all runtimes, aliases and metadata; builtins re-register lazily (Python `clear`). */ clear(): void; /** * Add an alias for a registered runtime (Python `add_alias`). * * @throws RuntimeRegistryError if `canonicalRuntimeId` is not registered. */ addAlias(alias: string, canonicalRuntimeId: string): void; } /** Minimal surface of the agent the builtin runtime drives. */ export interface RuntimeAgentLike { chat(prompt: string): Promise; model?: unknown; llm?: unknown; id?: unknown; agentId?: unknown; } /** Options for {@link PraisonAIRuntime} (TypeScript-only; Python `__init__` takes none). */ export interface PraisonAIRuntimeOptions { /** * Builds the agent for a turn. Defaults to `new Agent(config)` from * `../agent/simple`, imported lazily to avoid a circular import. Injectable * for tests. */ agentFactory?: (config: Record) => Promise | RuntimeAgentLike; } /** * Built-in PraisonAI runtime (Python `runtime/builtin.py::PraisonAIRuntime`). * * Wraps the existing `Agent` so a runtime abstraction exists without * duplicating the chat loop. As in Python, `streamTurn` yields the full * response as a single delta (the agent has no async streaming iterator). * * Python's builtin only implements `supports`, `run_turn` and `stream_turn`; * the remaining protocol methods here are thin delegations so the class * satisfies {@link AgentRuntimeProtocol} structurally. */ export declare class PraisonAIRuntime implements AgentRuntimeProtocol { readonly runtimeId = "praisonai"; readonly runtimeName = "praisonai"; readonly runtimeVersion = "1.0"; private readonly agentFactory; constructor(options?: PraisonAIRuntimeOptions); /** Capability matrix; `runtime/capabilities.py` is not ported, so this is minimal. */ capabilities(): RuntimeCapabilityMatrix; /** The builtin runtime delegates to the LLM subsystem, so it is universal (Python `supports`). */ supports(modelRef?: string | null): boolean; private buildAgentConfig; /** Execute a single turn (Python `run_turn`). Errors become `RuntimeResult.error`. */ runTurn(prompt: string, options?: RunTurnOptions): Promise; /** Stream the response as a single delta (Python `stream_turn` workaround). */ streamTurn(prompt: string, kwargs?: Record): AsyncIterable; /** TypeScript addition: run a turn from an agent config dict. */ executeAgent(agentConfig: Record, prompt: string, kwargs?: Record): Promise>; /** TypeScript addition: stream a turn from an agent config dict. */ streamAgent(agentConfig: Record, prompt: string, kwargs?: Record): AsyncIterable; /** TypeScript addition: the builtin accepts any config. */ validateConfig(agentConfig: Record): Promise; /** TypeScript addition: the builtin is always healthy when importable. */ healthCheck(): Promise>; } /** The global runtime registry instance (TypeScript accessor for Python `_global_registry`). */ export declare function getRuntimeRegistry(): RuntimeRegistry; /** Register a runtime factory with the global registry (Python `register_runtime`). */ export declare function registerRuntime(runtimeId: string, factory: RuntimeFactory | AgentRuntimeProtocol, metadata?: Record): void; /** Unregister a runtime from the global registry (Python `unregister_runtime`). */ export declare function unregisterRuntime(runtimeId: string): boolean; /** All registered runtime ids (Python `list_runtimes`). */ export declare function listRuntimes(): string[]; /** Resolve a runtime by id using the global registry (Python `resolve_runtime`). */ export declare function resolveRuntime(runtimeId: string): AgentRuntimeProtocol; /** Add an alias for a runtime (Python `add_runtime_alias`). */ export declare function addRuntimeAlias(alias: string, canonicalRuntimeId: string): void; /** True if the runtime exists and can be created (Python `is_runtime_available`). */ export declare function isRuntimeAvailable(runtimeId: string): boolean;