ts-agent-lib 0.1.0 → 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,416 @@
+import { z } from 'zod';
+
+declare const StepStatus: {
+    readonly PENDING: "pending";
+    readonly RUNNING: "running";
+    readonly COMPLETED: "completed";
+    readonly FAILED: "failed";
+    readonly BLOCKED: "blocked";
+    readonly CANCELLED: "cancelled";
+};
+type StepStatus = (typeof StepStatus)[keyof typeof StepStatus];
+declare const StepStatusSchema: z.ZodEnum<{
+    pending: "pending";
+    running: "running";
+    completed: "completed";
+    failed: "failed";
+    blocked: "blocked";
+    cancelled: "cancelled";
+}>;
+declare const ExecutionStatus: {
+    readonly PENDING: "pending";
+    readonly RUNNING: "running";
+    readonly COMPLETED: "completed";
+    readonly FAILED: "failed";
+    readonly CANCELLED: "cancelled";
+};
+type ExecutionStatus = (typeof ExecutionStatus)[keyof typeof ExecutionStatus];
+declare const ExecutionStatusSchema: z.ZodEnum<{
+    pending: "pending";
+    running: "running";
+    completed: "completed";
+    failed: "failed";
+    cancelled: "cancelled";
+}>;
+declare const StepSchema: z.ZodObject<{
+    id: z.ZodString;
+    action: z.ZodString;
+    deps: z.ZodPipe<z.ZodOptional<z.ZodArray<z.ZodString>>, z.ZodTransform<string[], string[] | undefined>>;
+    payload: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+type Step = z.infer<typeof StepSchema>;
+declare function utcNow(): Date;
+declare const ErrorInfoSchema: z.ZodObject<{
+    message: z.ZodString;
+    type: z.ZodOptional<z.ZodString>;
+    traceback: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type ErrorInfo = z.infer<typeof ErrorInfoSchema>;
+declare const StepResultSchema: z.ZodObject<{
+    stepId: z.ZodString;
+    status: z.ZodDefault<z.ZodEnum<{
+        pending: "pending";
+        running: "running";
+        completed: "completed";
+        failed: "failed";
+        blocked: "blocked";
+        cancelled: "cancelled";
+    }>>;
+    output: z.ZodOptional<z.ZodUnknown>;
+    error: z.ZodOptional<z.ZodObject<{
+        message: z.ZodString;
+        type: z.ZodOptional<z.ZodString>;
+        traceback: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    startedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+    finishedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+}, z.core.$strip>;
+type StepResult = z.infer<typeof StepResultSchema>;
+declare const ExecutionStateSchema: z.ZodObject<{
+    executionId: z.ZodString;
+    status: z.ZodDefault<z.ZodEnum<{
+        pending: "pending";
+        running: "running";
+        completed: "completed";
+        failed: "failed";
+        cancelled: "cancelled";
+    }>>;
+    steps: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodMap<z.ZodString, z.ZodObject<{
+        stepId: z.ZodString;
+        status: z.ZodDefault<z.ZodEnum<{
+            pending: "pending";
+            running: "running";
+            completed: "completed";
+            failed: "failed";
+            blocked: "blocked";
+            cancelled: "cancelled";
+        }>>;
+        output: z.ZodOptional<z.ZodUnknown>;
+        error: z.ZodOptional<z.ZodObject<{
+            message: z.ZodString;
+            type: z.ZodOptional<z.ZodString>;
+            traceback: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        startedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+        finishedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+    }, z.core.$strip>>>;
+    startedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+    finishedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+}, z.core.$strip>;
+type ExecutionState = z.infer<typeof ExecutionStateSchema>;
+declare const ExecutionEventSchema: z.ZodObject<{
+    executionId: z.ZodString;
+    ts: z.ZodCoercedDate<unknown>;
+    type: z.ZodString;
+}, z.core.$strip>;
+type ExecutionEvent = z.infer<typeof ExecutionEventSchema>;
+declare const ExecutionStartedSchema: z.ZodObject<{
+    executionId: z.ZodString;
+    ts: z.ZodCoercedDate<unknown>;
+    type: z.ZodLiteral<"execution_started">;
+    startedAt: z.ZodCoercedDate<unknown>;
+}, z.core.$strip>;
+type ExecutionStarted = z.infer<typeof ExecutionStartedSchema>;
+declare const ExecutionCompletedSchema: z.ZodObject<{
+    executionId: z.ZodString;
+    ts: z.ZodCoercedDate<unknown>;
+    type: z.ZodLiteral<"execution_completed">;
+    status: z.ZodEnum<{
+        pending: "pending";
+        running: "running";
+        completed: "completed";
+        failed: "failed";
+        cancelled: "cancelled";
+    }>;
+    finishedAt: z.ZodCoercedDate<unknown>;
+}, z.core.$strip>;
+type ExecutionCompleted = z.infer<typeof ExecutionCompletedSchema>;
+declare const ExecutionCancelledSchema: z.ZodObject<{
+    executionId: z.ZodString;
+    ts: z.ZodCoercedDate<unknown>;
+    type: z.ZodLiteral<"execution_cancelled">;
+    finishedAt: z.ZodCoercedDate<unknown>;
+}, z.core.$strip>;
+type ExecutionCancelled = z.infer<typeof ExecutionCancelledSchema>;
+declare const StepScheduledSchema: z.ZodObject<{
+    executionId: z.ZodString;
+    ts: z.ZodCoercedDate<unknown>;
+    type: z.ZodLiteral<"step_scheduled">;
+    stepId: z.ZodString;
+}, z.core.$strip>;
+type StepScheduled = z.infer<typeof StepScheduledSchema>;
+declare const StepStartedSchema: z.ZodObject<{
+    executionId: z.ZodString;
+    ts: z.ZodCoercedDate<unknown>;
+    type: z.ZodLiteral<"step_started">;
+    stepId: z.ZodString;
+}, z.core.$strip>;
+type StepStarted = z.infer<typeof StepStartedSchema>;
+declare const StepCompletedSchema: z.ZodObject<{
+    executionId: z.ZodString;
+    ts: z.ZodCoercedDate<unknown>;
+    type: z.ZodLiteral<"step_completed">;
+    stepId: z.ZodString;
+}, z.core.$strip>;
+type StepCompleted = z.infer<typeof StepCompletedSchema>;
+declare const StepFailedSchema: z.ZodObject<{
+    executionId: z.ZodString;
+    ts: z.ZodCoercedDate<unknown>;
+    type: z.ZodLiteral<"step_failed">;
+    stepId: z.ZodString;
+    error: z.ZodObject<{
+        message: z.ZodString;
+        type: z.ZodOptional<z.ZodString>;
+        traceback: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+type StepFailed = z.infer<typeof StepFailedSchema>;
+declare const StepBlockedSchema: z.ZodObject<{
+    executionId: z.ZodString;
+    ts: z.ZodCoercedDate<unknown>;
+    type: z.ZodLiteral<"step_blocked">;
+    stepId: z.ZodString;
+}, z.core.$strip>;
+type StepBlocked = z.infer<typeof StepBlockedSchema>;
+declare const StepCancelledSchema: z.ZodObject<{
+    executionId: z.ZodString;
+    ts: z.ZodCoercedDate<unknown>;
+    type: z.ZodLiteral<"step_cancelled">;
+    stepId: z.ZodString;
+}, z.core.$strip>;
+type StepCancelled = z.infer<typeof StepCancelledSchema>;
+declare const ExecutionEventTypeSchema: z.ZodUnion<readonly [z.ZodObject<{
+    executionId: z.ZodString;
+    ts: z.ZodCoercedDate<unknown>;
+    type: z.ZodLiteral<"execution_started">;
+    startedAt: z.ZodCoercedDate<unknown>;
+}, z.core.$strip>, z.ZodObject<{
+    executionId: z.ZodString;
+    ts: z.ZodCoercedDate<unknown>;
+    type: z.ZodLiteral<"execution_completed">;
+    status: z.ZodEnum<{
+        pending: "pending";
+        running: "running";
+        completed: "completed";
+        failed: "failed";
+        cancelled: "cancelled";
+    }>;
+    finishedAt: z.ZodCoercedDate<unknown>;
+}, z.core.$strip>, z.ZodObject<{
+    executionId: z.ZodString;
+    ts: z.ZodCoercedDate<unknown>;
+    type: z.ZodLiteral<"execution_cancelled">;
+    finishedAt: z.ZodCoercedDate<unknown>;
+}, z.core.$strip>, z.ZodObject<{
+    executionId: z.ZodString;
+    ts: z.ZodCoercedDate<unknown>;
+    type: z.ZodLiteral<"step_scheduled">;
+    stepId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    executionId: z.ZodString;
+    ts: z.ZodCoercedDate<unknown>;
+    type: z.ZodLiteral<"step_started">;
+    stepId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    executionId: z.ZodString;
+    ts: z.ZodCoercedDate<unknown>;
+    type: z.ZodLiteral<"step_completed">;
+    stepId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    executionId: z.ZodString;
+    ts: z.ZodCoercedDate<unknown>;
+    type: z.ZodLiteral<"step_failed">;
+    stepId: z.ZodString;
+    error: z.ZodObject<{
+        message: z.ZodString;
+        type: z.ZodOptional<z.ZodString>;
+        traceback: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    executionId: z.ZodString;
+    ts: z.ZodCoercedDate<unknown>;
+    type: z.ZodLiteral<"step_blocked">;
+    stepId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    executionId: z.ZodString;
+    ts: z.ZodCoercedDate<unknown>;
+    type: z.ZodLiteral<"step_cancelled">;
+    stepId: z.ZodString;
+}, z.core.$strip>]>;
+type ExecutionEventType = z.infer<typeof ExecutionEventTypeSchema>;
+type StepsInput = Map<string, Step> | Record<string, Step>;
+declare const PlanSchema: z.ZodObject<{
+    steps: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodMap<z.ZodString, z.ZodObject<{
+        id: z.ZodString;
+        action: z.ZodString;
+        deps: z.ZodPipe<z.ZodOptional<z.ZodArray<z.ZodString>>, z.ZodTransform<string[], string[] | undefined>>;
+        payload: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+type PlanInput = z.infer<typeof PlanSchema>;
+declare class Plan implements Iterable<Step> {
+    private readonly _steps;
+    constructor(steps: StepsInput);
+    [Symbol.iterator](): Iterator<Step>;
+    get steps(): ReadonlyMap<string, Step>;
+    getStep(stepId: string): Step;
+}
+
+type StepHandler = (step: Step, ctx: StepContext) => Promise<StepResult>;
+type EventHandler = (event: ExecutionEventType) => void | Promise<void>;
+interface ExecuteOptions {
+    onEvent?: EventHandler;
+    cancelSignal?: AbortSignal;
+    executionId?: string;
+}
+declare class StepContext {
+    private readonly _executionId;
+    private readonly _stepId;
+    private readonly _signal?;
+    private readonly _plan;
+    private readonly _getResult;
+    constructor(params: {
+        executionId: string;
+        stepId: string;
+        signal?: AbortSignal;
+        plan: Plan;
+        getResult: (stepId: string) => StepResult | undefined;
+    });
+    get executionId(): string;
+    get stepId(): string;
+    get signal(): AbortSignal | undefined;
+    isCancelled(): boolean;
+    getStep(stepId: string): Step;
+    getResult(stepId: string): Readonly<StepResult> | undefined;
+    requireResult(stepId: string): Readonly<StepResult>;
+    getDependencyResults(): Readonly<Record<string, StepResult>>;
+    getDependencyOutputs<T = unknown>(): Readonly<Record<string, T>>;
+}
+declare class DagExecutor {
+    private readonly maxParallelSteps;
+    private readonly failFast;
+    constructor(params?: {
+        maxParallelSteps?: number;
+        failFast?: boolean;
+    });
+    executeAsync(plan: Plan, handlers: Record<string, StepHandler>, options?: ExecuteOptions): Promise<ExecutionState>;
+    execute(plan: Plan, handlers: Record<string, StepHandler>, options?: ExecuteOptions): Promise<ExecutionState>;
+    streamExecute(plan: Plan, handlers: Record<string, StepHandler>, options?: ExecuteOptions): AsyncIterable<ExecutionEventType>;
+}
+
+declare class ExecutionError extends Error {
+    readonly executionId: string;
+    readonly status: ExecutionStatus;
+    readonly errors: ErrorInfo[];
+    constructor(params: {
+        executionId: string;
+        status: ExecutionStatus;
+        errors: ErrorInfo[];
+    });
+    static fromState(state: ExecutionState): ExecutionError;
+}
+declare function raiseIfFailed(state: ExecutionState): void;
+
+declare class PlanBuilder {
+    private readonly steps;
+    addStep(params: {
+        id: string;
+        action: string;
+        deps?: Iterable<string>;
+        payload?: unknown;
+    }): this;
+    addStepObj(step: Step): this;
+    build(): Plan;
+    private validateDependencies;
+    private validateAcyclic;
+}
+
+interface ExecutionObserver {
+    onEvent(event: ExecutionEventType): void | Promise<void>;
+}
+type ObserverErrorHandler = (observer: ExecutionObserver, event: ExecutionEventType, error: Error) => void | Promise<void>;
+declare const ObserverFailurePolicy: {
+    readonly LENIENT: "lenient";
+    readonly STRICT: "strict";
+};
+type ObserverFailurePolicy = (typeof ObserverFailurePolicy)[keyof typeof ObserverFailurePolicy];
+declare function composeObservers(observers: Iterable<ExecutionObserver>, options?: {
+    onError?: ObserverErrorHandler;
+    failurePolicy?: ObserverFailurePolicy;
+}): EventHandler;
+declare function composeObserversParallel(observers: Iterable<ExecutionObserver>, options?: {
+    onError?: ObserverErrorHandler;
+    failurePolicy?: ObserverFailurePolicy;
+}): EventHandler;
+declare const OverflowPolicy: {
+    readonly BLOCK: "block";
+    readonly DROP_NEW: "drop_new";
+    readonly DROP_OLDEST: "drop_oldest";
+};
+type OverflowPolicy = (typeof OverflowPolicy)[keyof typeof OverflowPolicy];
+declare abstract class BufferedObserver implements ExecutionObserver {
+    readonly maxQueueSize: number;
+    readonly overflowPolicy: OverflowPolicy;
+    readonly onError?: (event: ExecutionEventType, error: Error) => void | Promise<void>;
+    private readonly queue;
+    private task;
+    private started;
+    private abortController;
+    dropped: number;
+    failed: boolean;
+    lastError: Error | null;
+    constructor(params?: {
+        maxQueueSize?: number;
+        overflowPolicy?: OverflowPolicy;
+        onError?: (event: ExecutionEventType, error: Error) => void | Promise<void>;
+    });
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    onEvent(event: ExecutionEventType): Promise<void>;
+    private run;
+    protected abstract process(event: ExecutionEventType): void | Promise<void>;
+}
+
+type NumberLike = number;
+declare class Usage {
+    readonly provider?: string;
+    readonly model?: string;
+    readonly metrics: Record<string, NumberLike>;
+    constructor(params?: {
+        provider?: string;
+        model?: string;
+        metrics?: Record<string, NumberLike>;
+    });
+    add(other: Usage): Usage;
+}
+declare function aggregateUsage(state: ExecutionState, extract: (result: StepResult) => Usage | undefined): Usage;
+interface PricingRule {
+    metric: string;
+    perUnit: number;
+    scale?: number;
+}
+interface CostBreakdown {
+    byMetric: Record<string, number>;
+    total: number;
+}
+declare function estimateCost(usage: Usage, rules: PricingRule[]): CostBreakdown;
+
+declare class TaskOutput<T> {
+    readonly value: T;
+    readonly usage?: Usage;
+    readonly meta: Record<string, unknown>;
+    constructor(params: {
+        value: T;
+        usage?: Usage;
+        meta?: Record<string, unknown>;
+    });
+}
+declare function defaultUsageExtractor(res: StepResult): Usage | undefined;
+declare function runPlan(plan: Plan, handlers: Record<string, StepHandler>, options?: {
+    failOnError?: boolean;
+    usageExtractor?: ((res: StepResult) => Usage | undefined) | null;
+    pricingRules?: PricingRule[];
+    executor?: DagExecutor;
+}): Promise<[ExecutionState, Usage | undefined, CostBreakdown | undefined]>;
+
+export { BufferedObserver, type CostBreakdown, DagExecutor, type ErrorInfo, ErrorInfoSchema, type EventHandler, type ExecuteOptions, type ExecutionCancelled, ExecutionCancelledSchema, type ExecutionCompleted, ExecutionCompletedSchema, ExecutionError, type ExecutionEvent, ExecutionEventSchema, type ExecutionEventType, ExecutionEventTypeSchema, type ExecutionObserver, type ExecutionStarted, ExecutionStartedSchema, type ExecutionState, ExecutionStateSchema, ExecutionStatus, ExecutionStatusSchema, type ObserverErrorHandler, ObserverFailurePolicy, OverflowPolicy, Plan, PlanBuilder, type PlanInput, PlanSchema, type PricingRule, type Step, type StepBlocked, StepBlockedSchema, type StepCancelled, StepCancelledSchema, type StepCompleted, StepCompletedSchema, StepContext, type StepFailed, StepFailedSchema, type StepHandler, type StepResult, StepResultSchema, type StepScheduled, StepScheduledSchema, StepSchema, type StepStarted, StepStartedSchema, StepStatus, StepStatusSchema, type StepsInput, TaskOutput, Usage, aggregateUsage, composeObservers, composeObserversParallel, defaultUsageExtractor, estimateCost, raiseIfFailed, runPlan, utcNow };