@yesod/core 0.0.2 → 0.1.0

package/dist/index.d.ts

@@ -1,36 +1,65 @@
 declare enum EventType {
     OrchestrationStarted = "orchestration.started",
+    OrchestrationCompleted = "orchestration.completed",
+    WorkflowStarted = "workflow.started",
+    WorkflowCompleted = "workflow.completed",
+    WorkflowFailed = "workflow.failed",
+    WorkflowStepStarted = "workflow.step.started",
+    WorkflowStepCompleted = "workflow.step.completed",
+    WorkflowStepFailed = "workflow.step.failed",
     TaskCreated = "task.created",
     TaskDependency = "task.dependency",
+    TaskCompleted = "task.completed",
     SessionSpawned = "session.spawned",
+    SessionMessage = "session.message",
     SessionEvent = "session.event",
     SessionSteered = "session.steered",
     SessionArtifact = "session.artifact",
     SessionCompleted = "session.completed",
-    TaskCompleted = "task.completed",
-    OrchestrationCompleted = "orchestration.completed",
+    SessionFailed = "session.failed",
+    SessionKilled = "session.killed",
+    CostIncurred = "cost.incurred",
     SubscriptionTriggered = "subscription.triggered"
 }
+interface CostRecord {
+    tokens: {
+        input: number;
+        output: number;
+        cacheRead?: number;
+        cacheWrite?: number;
+    };
+    usd: number;
+    runtime?: string;
+}
 interface YesodEvent {
     id: string;
     type: EventType;
-    timestamp: string;
+    source: string;
+    timestamp: number;
     sessionId?: string;
     orchestrationId?: string;
     taskId?: string;
+    workflowId?: string;
+    stepId?: string;
     payload: Record<string, unknown>;
+    metadata?: {
+        cost?: CostRecord;
+        duration?: number;
+    };
 }
 
 type EventHandler = (event: YesodEvent) => void | Promise<void>;
 interface EventFilter {
-    type?: EventType;
+    type?: EventType | EventType[];
     sessionId?: string;
     orchestrationId?: string;
+    workflowId?: string;
 }
 declare class EventBus {
     private handlers;
     private nextId;
     subscribe(filter: EventFilter, handler: EventHandler): string;
+    subscribeAll(handler: EventHandler): string;
     unsubscribe(id: string): void;
     emit(event: YesodEvent): Promise<void>;
     private matches;
@@ -46,6 +75,9 @@ interface Subscription {
     orchestratorSession: string;
     conditions: SubscriptionCondition[];
     mode: "any" | "all";
+    once?: boolean;
+    ttl?: number;
+    registeredAt?: number;
 }
 interface NotificationEvent {
     type: "subscription.triggered";
@@ -54,12 +86,16 @@ interface NotificationEvent {
 }
 declare class VantageEngine {
     private subscriptions;
+    private barrierState;
     register(subscription: Subscription): void;
     remove(subscriptionId: string): void;
-    /** Evaluate an incoming event against all subscriptions. Returns notifications for any triggered subscriptions. */
-    evaluate(_event: YesodEvent): NotificationEvent[];
+    evaluate(event: YesodEvent): NotificationEvent[];
     getSubscription(id: string): Subscription | undefined;
     listSubscriptions(): Subscription[];
+    activeCount(): number;
+    private matchAny;
+    private matchBarrier;
+    private matchCondition;
 }
 
 interface StorageQuery {
@@ -84,6 +120,120 @@ declare class InMemoryStorageAdapter implements StorageAdapter {
     delete(key: string): Promise<boolean>;
 }
 
+interface SessionHandle {
+    id: string;
+    adapter: string;
+    metadata: Record<string, unknown>;
+}
+type SessionStatus = "running" | "completed" | "failed" | "timeout" | "killed" | "unknown";
+interface RuntimeDecision {
+    reason: string;
+    considered: string[];
+    chosen: string;
+}
+interface TaskSpec {
+    instruction: string;
+    expectedResult: ResultSpec;
+    priorContext?: StepResult[];
+}
+interface ResultSpec {
+    format: "summary" | "structured" | "diff" | "review" | "test";
+    fields?: string[];
+    maxLength?: number;
+}
+interface StepResult {
+    stepId: string;
+    status: "completed" | "failed" | "timeout";
+    output: StructuredOutput;
+    meta: {
+        runtime: string;
+        decision: RuntimeDecision;
+        cost: CostRecord;
+        durationMs: number;
+        retries: number;
+    };
+}
+type StructuredOutput = SummaryOutput | DiffOutput | ReviewOutput | TestOutput | StructuredFieldsOutput | RawFallbackOutput;
+interface SummaryOutput {
+    format: "summary";
+    summary: string;
+}
+interface DiffOutput {
+    format: "diff";
+    summary: string;
+    filesChanged: Array<{
+        path: string;
+        linesAdded: number;
+        linesRemoved: number;
+    }>;
+}
+interface ReviewOutput {
+    format: "review";
+    summary: string;
+    findings: Array<{
+        severity: "critical" | "high" | "medium" | "low" | "info";
+        location: string;
+        issue: string;
+    }>;
+    filesReviewed: string[];
+}
+interface TestOutput {
+    format: "test";
+    summary: string;
+    passed: number;
+    failed: number;
+    skipped: number;
+    failures: Array<{
+        test: string;
+        error: string;
+    }>;
+}
+interface StructuredFieldsOutput {
+    format: "structured";
+    fields: Record<string, unknown>;
+}
+interface RawFallbackOutput {
+    format: "raw";
+    raw: string;
+    parseError?: string;
+}
+interface SpawnOptions {
+    task: TaskSpec;
+    runtime: string;
+    decision: RuntimeDecision;
+    mode?: "run" | "session";
+    cwd?: string;
+    timeout?: number;
+    labels?: Record<string, string>;
+    context?: {
+        workflowId: string;
+        stepId: string;
+        attempt: number;
+    };
+    adapterConfig?: Record<string, unknown>;
+}
+interface CodingSpawnOptions extends SpawnOptions {
+    repo?: string;
+    branch?: string;
+    files?: string[];
+}
+interface RetryPolicy {
+    maxAttempts: number;
+    backoffMs?: number;
+    backoffMultiplier?: number;
+    retryOn?: string[];
+}
+interface RuntimeAdapter {
+    readonly name: string;
+    readonly description?: string;
+    spawn(opts: SpawnOptions): Promise<SessionHandle>;
+    send(session: SessionHandle, message: string): Promise<void>;
+    kill(session: SessionHandle): Promise<void>;
+    status(session: SessionHandle): Promise<SessionStatus | null>;
+    onEvent(handler: (event: YesodEvent) => void): void;
+    dispose(): Promise<void>;
+}
+
 type SessionState = "pending" | "running" | "yielded" | "completed" | "failed" | "cancelled";
 interface SessionControl {
     maxTurns?: number;
@@ -99,8 +249,10 @@ interface CodingSession {
     parentSessionId?: string;
     state: SessionState;
     controls: SessionControl;
-    startedAt?: string;
-    completedAt?: string;
+    runtimeDecision?: RuntimeDecision;
+    stepResult?: StepResult;
+    startedAt?: number;
+    completedAt?: number;
     result?: Record<string, unknown>;
 }
 
@@ -108,19 +260,44 @@ type WorkflowState = "created" | "running" | "paused" | "completed" | "failed";
 interface WorkflowStep {
     id: string;
     name: string;
+    task: string;
+    expectedResult: ResultSpec;
+    runtime: string;
+    decision: RuntimeDecision;
+    dependsOn?: string[];
+    condition?: string;
+    retry?: RetryPolicy;
+    timeout?: number;
+    config?: Record<string, unknown>;
+    outputMapping?: Record<string, string>;
+}
+interface WorkflowInput {
+    name: string;
+    type: "string" | "number" | "boolean";
+    required?: boolean;
+    default?: unknown;
     description?: string;
-    dependsOn: string[];
-    taskId?: string;
-    state: WorkflowState;
+}
+interface WorkflowTrigger {
+    type: "event" | "schedule" | "manual";
+    config: Record<string, unknown>;
 }
 interface Workflow {
     id: string;
-    orchestrationId: string;
     name: string;
+    description?: string;
+    version?: string;
+    inputs?: WorkflowInput[];
     steps: WorkflowStep[];
+    triggers?: WorkflowTrigger[];
+    defaults?: {
+        runtime?: string;
+        timeout?: number;
+        retry?: RetryPolicy;
+    };
     state: WorkflowState;
-    createdAt: string;
-    completedAt?: string;
+    createdAt: number;
+    completedAt?: number;
 }
 
 interface ReadyStep {
@@ -128,19 +305,215 @@ interface ReadyStep {
     reason: string;
 }
 interface Scheduler {
-    /** Reports which steps have all dependencies satisfied and are ready to execute. The agent decides what to actually run. */
-    getReadySteps(workflowId: string): ReadyStep[];
+    getReadySteps(): ReadyStep[];
+}
+type StepState = "pending" | "running" | "completed" | "failed";
+declare class SimpleScheduler implements Scheduler {
+    private stepStates;
+    private stepMap;
+    constructor(steps: WorkflowStep[]);
+    getReadySteps(): ReadyStep[];
+    markRunning(stepId: string): void;
+    markCompleted(stepId: string): void;
+    markFailed(stepId: string): void;
+    getState(stepId: string): StepState | undefined;
+    isComplete(): boolean;
+    allSucceeded(): boolean;
+    /**
+     * Mark any pending step whose dependencies include a failed step as failed.
+     * Returns IDs of newly failed steps.
+     */
+    markUnreachable(): string[];
 }
 
-interface RuntimeRecommendation {
-    runtimeId: string;
-    name: string;
-    score: number;
-    reason: string;
+type EngineWorkflowState = "created" | "running" | "completed" | "failed";
+interface WorkflowExecution {
+    workflow: Workflow;
+    state: EngineWorkflowState;
+    scheduler: SimpleScheduler;
+    stepResults: Map<string, StepResult>;
+    activeSessions: Map<string, SessionHandle>;
+    startedAt: number;
+    completedAt?: number;
+}
+interface WorkflowStatus {
+    workflowId: string;
+    state: EngineWorkflowState;
+    steps: Array<{
+        stepId: string;
+        state: string;
+        result?: StepResult;
+    }>;
+    startedAt: number;
+    completedAt?: number;
 }
-interface Router {
-    /** Recommends available runtimes for a given task. The agent decides which to use. */
-    recommend(taskType: string): RuntimeRecommendation[];
+interface CostSummary {
+    totalUsd: number;
+    totalTokens: {
+        input: number;
+        output: number;
+    };
+    perStep: Array<{
+        stepId: string;
+        cost: CostRecord;
+        durationMs: number;
+    }>;
 }
+declare class OrchestrationEngine {
+    private adapter;
+    private bus;
+    private storage;
+    private executions;
+    constructor(adapter: RuntimeAdapter, bus: EventBus, storage: StorageAdapter);
+    createWorkflow(def: Workflow): Workflow;
+    startWorkflow(workflowId: string): Promise<void>;
+    cancelWorkflow(workflowId: string): Promise<void>;
+    getWorkflowStatus(workflowId: string): WorkflowStatus;
+    getCostSummary(workflowId?: string): CostSummary;
+    private advanceWorkflow;
+    private spawnStep;
+    private handleAdapterEvent;
+    private handleStepCompleted;
+    private handleStepFailed;
+}
+
+/**
+ * MCP tool JSON Schema definitions for Yesod agent-facing tools.
+ */
+declare const YESOD_TOOLS: {
+    readonly yesod_create_workflow: {
+        readonly name: "yesod_create_workflow";
+        readonly description: "Create and start a multi-step workflow. Define the steps, their dependencies, and expected output formats. Yesod will orchestrate execution, spawn child agents, and chain results automatically.";
+        readonly inputSchema: {
+            readonly type: "object";
+            readonly properties: {
+                readonly name: {
+                    readonly type: "string";
+                    readonly description: "Human-readable name for the workflow";
+                };
+                readonly steps: {
+                    readonly type: "array";
+                    readonly description: "Workflow steps to execute";
+                    readonly items: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly id: {
+                                readonly type: "string";
+                                readonly description: "Unique step identifier";
+                            };
+                            readonly name: {
+                                readonly type: "string";
+                                readonly description: "Human-readable step name";
+                            };
+                            readonly task: {
+                                readonly type: "string";
+                                readonly description: "Instruction for the agent performing this step";
+                            };
+                            readonly expectedResult: {
+                                readonly type: "object";
+                                readonly description: "Expected output format";
+                                readonly properties: {
+                                    readonly format: {
+                                        readonly type: "string";
+                                        readonly enum: readonly ["summary", "structured", "diff", "review", "test"];
+                                    };
+                                    readonly fields: {
+                                        readonly type: "array";
+                                        readonly items: {
+                                            readonly type: "string";
+                                        };
+                                        readonly description: "Fields to include (for structured format)";
+                                    };
+                                    readonly maxLength: {
+                                        readonly type: "number";
+                                        readonly description: "Max output length in characters";
+                                    };
+                                };
+                                readonly required: readonly ["format"];
+                            };
+                            readonly runtime: {
+                                readonly type: "string";
+                                readonly description: "Runtime to use (e.g. claude-code, codex)";
+                            };
+                            readonly decision: {
+                                readonly type: "object";
+                                readonly description: "Why this runtime was chosen";
+                                readonly properties: {
+                                    readonly reason: {
+                                        readonly type: "string";
+                                    };
+                                    readonly considered: {
+                                        readonly type: "array";
+                                        readonly items: {
+                                            readonly type: "string";
+                                        };
+                                    };
+                                    readonly chosen: {
+                                        readonly type: "string";
+                                    };
+                                };
+                                readonly required: readonly ["reason", "considered", "chosen"];
+                            };
+                            readonly dependsOn: {
+                                readonly type: "array";
+                                readonly items: {
+                                    readonly type: "string";
+                                };
+                                readonly description: "Step IDs this step depends on";
+                            };
+                            readonly timeout: {
+                                readonly type: "number";
+                                readonly description: "Timeout in milliseconds";
+                            };
+                        };
+                        readonly required: readonly ["id", "name", "task", "expectedResult", "runtime", "decision"];
+                    };
+                };
+            };
+            readonly required: readonly ["name", "steps"];
+        };
+    };
+    readonly yesod_workflow_status: {
+        readonly name: "yesod_workflow_status";
+        readonly description: "Check the current status of a running workflow, including per-step progress and results.";
+        readonly inputSchema: {
+            readonly type: "object";
+            readonly properties: {
+                readonly workflowId: {
+                    readonly type: "string";
+                    readonly description: "ID of the workflow to check";
+                };
+            };
+            readonly required: readonly ["workflowId"];
+        };
+    };
+    readonly yesod_cancel_workflow: {
+        readonly name: "yesod_cancel_workflow";
+        readonly description: "Cancel a running workflow. Kills all active sessions and marks the workflow as failed.";
+        readonly inputSchema: {
+            readonly type: "object";
+            readonly properties: {
+                readonly workflowId: {
+                    readonly type: "string";
+                    readonly description: "ID of the workflow to cancel";
+                };
+            };
+            readonly required: readonly ["workflowId"];
+        };
+    };
+    readonly yesod_cost_summary: {
+        readonly name: "yesod_cost_summary";
+        readonly description: "Get a cost breakdown showing token usage and USD cost, optionally filtered to a specific workflow.";
+        readonly inputSchema: {
+            readonly type: "object";
+            readonly properties: {
+                readonly workflowId: {
+                    readonly type: "string";
+                    readonly description: "Optional: filter to a specific workflow";
+                };
+            };
+        };
+    };
+};
 
-export { type CodingSession, EventBus, type EventFilter, type EventHandler, EventType, InMemoryStorageAdapter, type NotificationEvent, type ReadyStep, type Router, type RuntimeRecommendation, type Scheduler, type SessionControl, type SessionState, type StorageAdapter, type StorageQuery, type Subscription, type SubscriptionCondition, VantageEngine, type Workflow, type WorkflowState, type WorkflowStep, type YesodEvent };
+export { type CodingSession, type CodingSpawnOptions, type CostRecord, type CostSummary, type DiffOutput, type EngineWorkflowState, EventBus, type EventFilter, type EventHandler, EventType, InMemoryStorageAdapter, type NotificationEvent, OrchestrationEngine, type RawFallbackOutput, type ReadyStep, type ResultSpec, type RetryPolicy, type ReviewOutput, type RuntimeAdapter, type RuntimeDecision, type Scheduler, type SessionControl, type SessionHandle, type SessionState, type SessionStatus, SimpleScheduler, type SpawnOptions, type StepResult, type StepState, type StorageAdapter, type StorageQuery, type StructuredFieldsOutput, type StructuredOutput, type Subscription, type SubscriptionCondition, type SummaryOutput, type TaskSpec, type TestOutput, VantageEngine, type Workflow, type WorkflowExecution, type WorkflowInput, type WorkflowState, type WorkflowStatus, type WorkflowStep, type WorkflowTrigger, YESOD_TOOLS, type YesodEvent };