@yesod/core 0.0.1 → 0.1.0

package/README.md

@@ -0,0 +1,31 @@
+# @yesod/core
+
+Core engine for Yesod — orchestration toolkit that makes AI agents delegate better and lets humans see why.
+
+Provides the event bus, orchestration engine, scheduler, subscription engine (Vantage), TaskSpec/ResultSpec for structured delegation, RuntimeDecision tracking, and all shared interfaces.
+
+## Key Exports
+
+- **OrchestrationEngine** — executes workflows by coordinating the scheduler, runtime adapter, and event bus
+- **EventBus** — publish/subscribe for orchestration events with type and field filtering
+- **SimpleScheduler** — DAG-based step scheduling with dependency resolution
+- **VantageEngine** — compound condition evaluation with barrier mode and TTL
+- **TaskSpec / ResultSpec** — structured task delegation with typed result formats
+- **RuntimeDecision** — required metadata recording why the agent chose a runtime
+- **StepResult / StructuredOutput** — typed results (diff, review, test, summary) flowing back to orchestrators
+- **YESOD_TOOLS** — MCP tool JSON schemas for agent-facing tools
+- All type definitions and interfaces for adapters
+
+## Status
+
+Phase 0 complete. Core orchestration loop is implemented and tested (29 tests).
+
+## Links
+
+- [GitHub](https://github.com/eryv-ai/yesod)
+- [Architecture](https://github.com/eryv-ai/yesod/blob/main/docs/concept/03-architecture.md)
+- [Core Interfaces](https://github.com/eryv-ai/yesod/blob/main/docs/concept/05-interfaces.md)
+
+## License
+
+MIT

package/dist/index.cjs

@@ -23,22 +23,35 @@ __export(index_exports, {
   EventBus: () => EventBus,
   EventType: () => EventType,
   InMemoryStorageAdapter: () => InMemoryStorageAdapter,
-  VantageEngine: () => VantageEngine
+  OrchestrationEngine: () => OrchestrationEngine,
+  SimpleScheduler: () => SimpleScheduler,
+  VantageEngine: () => VantageEngine,
+  YESOD_TOOLS: () => YESOD_TOOLS
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/events.ts
 var EventType = /* @__PURE__ */ ((EventType2) => {
   EventType2["OrchestrationStarted"] = "orchestration.started";
+  EventType2["OrchestrationCompleted"] = "orchestration.completed";
+  EventType2["WorkflowStarted"] = "workflow.started";
+  EventType2["WorkflowCompleted"] = "workflow.completed";
+  EventType2["WorkflowFailed"] = "workflow.failed";
+  EventType2["WorkflowStepStarted"] = "workflow.step.started";
+  EventType2["WorkflowStepCompleted"] = "workflow.step.completed";
+  EventType2["WorkflowStepFailed"] = "workflow.step.failed";
   EventType2["TaskCreated"] = "task.created";
   EventType2["TaskDependency"] = "task.dependency";
+  EventType2["TaskCompleted"] = "task.completed";
   EventType2["SessionSpawned"] = "session.spawned";
+  EventType2["SessionMessage"] = "session.message";
   EventType2["SessionEvent"] = "session.event";
   EventType2["SessionSteered"] = "session.steered";
   EventType2["SessionArtifact"] = "session.artifact";
   EventType2["SessionCompleted"] = "session.completed";
-  EventType2["TaskCompleted"] = "task.completed";
-  EventType2["OrchestrationCompleted"] = "orchestration.completed";
+  EventType2["SessionFailed"] = "session.failed";
+  EventType2["SessionKilled"] = "session.killed";
+  EventType2["CostIncurred"] = "cost.incurred";
   EventType2["SubscriptionTriggered"] = "subscription.triggered";
   return EventType2;
 })(EventType || {});
@@ -52,6 +65,9 @@ var EventBus = class {
     this.handlers.set(id, { filter, handler });
     return id;
   }
+  subscribeAll(handler) {
+    return this.subscribe({}, handler);
+  }
   unsubscribe(id) {
     this.handlers.delete(id);
   }
@@ -68,9 +84,18 @@ var EventBus = class {
     await Promise.all(promises);
   }
   matches(event, filter) {
-    if (filter.type && event.type !== filter.type) return false;
+    if (filter.type) {
+      if (Array.isArray(filter.type)) {
+        if (!filter.type.includes(event.type)) return false;
+      } else {
+        if (event.type !== filter.type) return false;
+      }
+    }
     if (filter.sessionId && event.sessionId !== filter.sessionId) return false;
-    if (filter.orchestrationId && event.orchestrationId !== filter.orchestrationId) return false;
+    if (filter.orchestrationId && event.orchestrationId !== filter.orchestrationId)
+      return false;
+    if (filter.workflowId && event.workflowId !== filter.workflowId)
+      return false;
     return true;
   }
 };
@@ -78,15 +103,50 @@ var EventBus = class {
 // src/vantage.ts
 var VantageEngine = class {
   subscriptions = /* @__PURE__ */ new Map();
+  barrierState = /* @__PURE__ */ new Map();
   register(subscription) {
-    this.subscriptions.set(subscription.id, subscription);
+    const sub = { ...subscription, registeredAt: subscription.registeredAt ?? Date.now() };
+    this.subscriptions.set(sub.id, sub);
+    if (sub.mode === "all") {
+      this.barrierState.set(sub.id, /* @__PURE__ */ new Map());
+    }
   }
   remove(subscriptionId) {
     this.subscriptions.delete(subscriptionId);
+    this.barrierState.delete(subscriptionId);
   }
-  /** Evaluate an incoming event against all subscriptions. Returns notifications for any triggered subscriptions. */
-  evaluate(_event) {
-    return [];
+  evaluate(event) {
+    const notifications = [];
+    const toRemove = [];
+    for (const [id, sub] of this.subscriptions) {
+      if (sub.ttl && sub.registeredAt) {
+        if (Date.now() - sub.registeredAt > sub.ttl) {
+          toRemove.push(id);
+          continue;
+        }
+      }
+      if (sub.mode === "any") {
+        const matched = this.matchAny(event, sub);
+        if (matched) {
+          notifications.push({
+            type: "subscription.triggered",
+            subscriptionId: id,
+            matchedEvents: [event]
+          });
+          if (sub.once) toRemove.push(id);
+        }
+      } else {
+        const notification = this.matchBarrier(event, sub);
+        if (notification) {
+          notifications.push(notification);
+          if (sub.once) toRemove.push(id);
+        }
+      }
+    }
+    for (const id of toRemove) {
+      this.remove(id);
+    }
+    return notifications;
   }
   getSubscription(id) {
     return this.subscriptions.get(id);
@@ -94,6 +154,48 @@ var VantageEngine = class {
   listSubscriptions() {
     return Array.from(this.subscriptions.values());
   }
+  activeCount() {
+    return this.subscriptions.size;
+  }
+  matchAny(event, sub) {
+    return sub.conditions.some((cond) => this.matchCondition(event, cond));
+  }
+  matchBarrier(event, sub) {
+    let barrier = this.barrierState.get(sub.id);
+    if (!barrier) {
+      barrier = /* @__PURE__ */ new Map();
+      this.barrierState.set(sub.id, barrier);
+    }
+    for (let i = 0; i < sub.conditions.length; i++) {
+      if (barrier.has(i)) continue;
+      if (this.matchCondition(event, sub.conditions[i])) {
+        barrier.set(i, [event]);
+      }
+    }
+    if (barrier.size === sub.conditions.length) {
+      const allEvents = [];
+      for (const events of barrier.values()) {
+        allEvents.push(...events);
+      }
+      this.barrierState.delete(sub.id);
+      return {
+        type: "subscription.triggered",
+        subscriptionId: sub.id,
+        matchedEvents: allEvents
+      };
+    }
+    return null;
+  }
+  matchCondition(event, cond) {
+    if (event.type !== cond.eventType) return false;
+    if (cond.sessionId && event.sessionId !== cond.sessionId) return false;
+    if (cond.filter) {
+      for (const [key, value] of Object.entries(cond.filter)) {
+        if (event.payload[key] !== value) return false;
+      }
+    }
+    return true;
+  }
 };
 
 // src/storage.ts
@@ -112,11 +214,469 @@ var InMemoryStorageAdapter = class {
     return this.store.delete(key);
   }
 };
+
+// src/scheduler.ts
+var SimpleScheduler = class {
+  stepStates = /* @__PURE__ */ new Map();
+  stepMap = /* @__PURE__ */ new Map();
+  constructor(steps) {
+    for (const step of steps) {
+      this.stepMap.set(step.id, step);
+      this.stepStates.set(step.id, "pending");
+    }
+  }
+  getReadySteps() {
+    const ready = [];
+    for (const [id, state] of this.stepStates) {
+      if (state !== "pending") continue;
+      const step = this.stepMap.get(id);
+      const deps = step.dependsOn ?? [];
+      const allDepsCompleted = deps.every(
+        (depId) => this.stepStates.get(depId) === "completed"
+      );
+      if (allDepsCompleted) {
+        const reason = deps.length === 0 ? "No dependencies" : `Dependencies satisfied: ${deps.join(", ")}`;
+        ready.push({ step, reason });
+      }
+    }
+    return ready;
+  }
+  markRunning(stepId) {
+    this.stepStates.set(stepId, "running");
+  }
+  markCompleted(stepId) {
+    this.stepStates.set(stepId, "completed");
+  }
+  markFailed(stepId) {
+    this.stepStates.set(stepId, "failed");
+  }
+  getState(stepId) {
+    return this.stepStates.get(stepId);
+  }
+  isComplete() {
+    for (const state of this.stepStates.values()) {
+      if (state !== "completed" && state !== "failed") return false;
+    }
+    return true;
+  }
+  allSucceeded() {
+    for (const state of this.stepStates.values()) {
+      if (state !== "completed") return false;
+    }
+    return true;
+  }
+  /**
+   * Mark any pending step whose dependencies include a failed step as failed.
+   * Returns IDs of newly failed steps.
+   */
+  markUnreachable() {
+    const failed = [];
+    let changed = true;
+    while (changed) {
+      changed = false;
+      for (const [id, state] of this.stepStates) {
+        if (state !== "pending") continue;
+        const step = this.stepMap.get(id);
+        const deps = step.dependsOn ?? [];
+        const hasFailedDep = deps.some(
+          (depId) => this.stepStates.get(depId) === "failed"
+        );
+        if (hasFailedDep) {
+          this.stepStates.set(id, "failed");
+          failed.push(id);
+          changed = true;
+        }
+      }
+    }
+    return failed;
+  }
+};
+
+// src/engine.ts
+var idCounter = 0;
+function uid() {
+  return `evt-${Date.now()}-${++idCounter}`;
+}
+var OrchestrationEngine = class {
+  constructor(adapter, bus, storage) {
+    this.adapter = adapter;
+    this.bus = bus;
+    this.storage = storage;
+    this.adapter.onEvent((event) => this.handleAdapterEvent(event));
+  }
+  adapter;
+  bus;
+  storage;
+  executions = /* @__PURE__ */ new Map();
+  createWorkflow(def) {
+    const workflow = {
+      ...def,
+      id: def.id || uid(),
+      state: "created",
+      createdAt: Date.now()
+    };
+    const scheduler = new SimpleScheduler(workflow.steps);
+    this.executions.set(workflow.id, {
+      workflow,
+      state: "created",
+      scheduler,
+      stepResults: /* @__PURE__ */ new Map(),
+      activeSessions: /* @__PURE__ */ new Map(),
+      startedAt: 0
+    });
+    return workflow;
+  }
+  async startWorkflow(workflowId) {
+    const exec = this.executions.get(workflowId);
+    if (!exec) throw new Error(`Unknown workflow: ${workflowId}`);
+    if (exec.state !== "created") {
+      throw new Error(`Workflow ${workflowId} is already ${exec.state}`);
+    }
+    exec.state = "running";
+    exec.startedAt = Date.now();
+    await this.bus.emit({
+      id: uid(),
+      type: "workflow.started" /* WorkflowStarted */,
+      source: "engine",
+      timestamp: Date.now(),
+      workflowId,
+      payload: { name: exec.workflow.name }
+    });
+    await this.advanceWorkflow(workflowId);
+  }
+  async cancelWorkflow(workflowId) {
+    const exec = this.executions.get(workflowId);
+    if (!exec) throw new Error(`Unknown workflow: ${workflowId}`);
+    for (const [stepId, handle] of exec.activeSessions) {
+      try {
+        await this.adapter.kill(handle);
+      } catch {
+      }
+      exec.scheduler.markFailed(stepId);
+    }
+    exec.activeSessions.clear();
+    exec.state = "failed";
+    exec.completedAt = Date.now();
+    await this.bus.emit({
+      id: uid(),
+      type: "workflow.failed" /* WorkflowFailed */,
+      source: "engine",
+      timestamp: Date.now(),
+      workflowId,
+      payload: { reason: "cancelled" }
+    });
+  }
+  getWorkflowStatus(workflowId) {
+    const exec = this.executions.get(workflowId);
+    if (!exec) throw new Error(`Unknown workflow: ${workflowId}`);
+    return {
+      workflowId,
+      state: exec.state,
+      steps: exec.workflow.steps.map((step) => ({
+        stepId: step.id,
+        state: exec.scheduler.getState(step.id) ?? "pending",
+        result: exec.stepResults.get(step.id)
+      })),
+      startedAt: exec.startedAt,
+      completedAt: exec.completedAt
+    };
+  }
+  getCostSummary(workflowId) {
+    let results = [];
+    if (workflowId) {
+      const exec = this.executions.get(workflowId);
+      if (exec) {
+        results = Array.from(exec.stepResults.values());
+      }
+    } else {
+      for (const exec of this.executions.values()) {
+        results.push(...exec.stepResults.values());
+      }
+    }
+    let totalUsd = 0;
+    let totalInput = 0;
+    let totalOutput = 0;
+    const perStep = [];
+    for (const r of results) {
+      totalUsd += r.meta.cost.usd;
+      totalInput += r.meta.cost.tokens.input;
+      totalOutput += r.meta.cost.tokens.output;
+      perStep.push({
+        stepId: r.stepId,
+        cost: r.meta.cost,
+        durationMs: r.meta.durationMs
+      });
+    }
+    return {
+      totalUsd,
+      totalTokens: { input: totalInput, output: totalOutput },
+      perStep
+    };
+  }
+  // --- Internal ---
+  async advanceWorkflow(workflowId) {
+    const exec = this.executions.get(workflowId);
+    if (!exec || exec.state !== "running") return;
+    const readySteps = exec.scheduler.getReadySteps();
+    for (const { step } of readySteps) {
+      exec.scheduler.markRunning(step.id);
+      try {
+        await this.spawnStep(exec, step, workflowId);
+      } catch (err) {
+        exec.scheduler.markFailed(step.id);
+        await this.bus.emit({
+          id: uid(),
+          type: "workflow.step.failed" /* WorkflowStepFailed */,
+          source: "engine",
+          timestamp: Date.now(),
+          workflowId,
+          stepId: step.id,
+          payload: {
+            error: err instanceof Error ? err.message : String(err)
+          }
+        });
+      }
+    }
+    exec.scheduler.markUnreachable();
+    if (exec.scheduler.isComplete()) {
+      exec.state = exec.scheduler.allSucceeded() ? "completed" : "failed";
+      exec.completedAt = Date.now();
+      const eventType = exec.state === "completed" ? "workflow.completed" /* WorkflowCompleted */ : "workflow.failed" /* WorkflowFailed */;
+      await this.bus.emit({
+        id: uid(),
+        type: eventType,
+        source: "engine",
+        timestamp: Date.now(),
+        workflowId,
+        payload: {
+          duration: exec.completedAt - exec.startedAt
+        }
+      });
+    }
+  }
+  async spawnStep(exec, step, workflowId) {
+    const priorContext = [];
+    for (const depId of step.dependsOn ?? []) {
+      const depResult = exec.stepResults.get(depId);
+      if (depResult) priorContext.push(depResult);
+    }
+    const taskSpec = {
+      instruction: step.task,
+      expectedResult: step.expectedResult,
+      priorContext: priorContext.length > 0 ? priorContext : void 0
+    };
+    const spawnOpts = {
+      task: taskSpec,
+      runtime: step.runtime,
+      decision: step.decision,
+      timeout: step.timeout,
+      context: { workflowId, stepId: step.id, attempt: 1 }
+    };
+    await this.bus.emit({
+      id: uid(),
+      type: "workflow.step.started" /* WorkflowStepStarted */,
+      source: "engine",
+      timestamp: Date.now(),
+      workflowId,
+      stepId: step.id,
+      payload: { runtime: step.runtime }
+    });
+    const handle = await this.adapter.spawn(spawnOpts);
+    exec.activeSessions.set(step.id, handle);
+  }
+  async handleAdapterEvent(event) {
+    await this.bus.emit(event);
+    if (event.type === "session.completed" /* SessionCompleted */ && event.stepId) {
+      await this.handleStepCompleted(event);
+    } else if (event.type === "session.failed" /* SessionFailed */ && event.stepId) {
+      await this.handleStepFailed(event);
+    }
+  }
+  async handleStepCompleted(event) {
+    const workflowId = event.workflowId;
+    const stepId = event.stepId;
+    if (!workflowId || !stepId) return;
+    const exec = this.executions.get(workflowId);
+    if (!exec) return;
+    const stepResult = event.payload.stepResult;
+    if (stepResult) {
+      exec.stepResults.set(stepId, stepResult);
+    }
+    exec.activeSessions.delete(stepId);
+    exec.scheduler.markCompleted(stepId);
+    await this.bus.emit({
+      id: uid(),
+      type: "workflow.step.completed" /* WorkflowStepCompleted */,
+      source: "engine",
+      timestamp: Date.now(),
+      workflowId,
+      stepId,
+      payload: { result: stepResult }
+    });
+    await this.advanceWorkflow(workflowId);
+  }
+  async handleStepFailed(event) {
+    const workflowId = event.workflowId;
+    const stepId = event.stepId;
+    if (!workflowId || !stepId) return;
+    const exec = this.executions.get(workflowId);
+    if (!exec) return;
+    exec.activeSessions.delete(stepId);
+    exec.scheduler.markFailed(stepId);
+    await this.bus.emit({
+      id: uid(),
+      type: "workflow.step.failed" /* WorkflowStepFailed */,
+      source: "engine",
+      timestamp: Date.now(),
+      workflowId,
+      stepId,
+      payload: { error: event.payload.error }
+    });
+    await this.advanceWorkflow(workflowId);
+  }
+};
+
+// src/tools.ts
+var YESOD_TOOLS = {
+  yesod_create_workflow: {
+    name: "yesod_create_workflow",
+    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.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: {
+          type: "string",
+          description: "Human-readable name for the workflow"
+        },
+        steps: {
+          type: "array",
+          description: "Workflow steps to execute",
+          items: {
+            type: "object",
+            properties: {
+              id: {
+                type: "string",
+                description: "Unique step identifier"
+              },
+              name: {
+                type: "string",
+                description: "Human-readable step name"
+              },
+              task: {
+                type: "string",
+                description: "Instruction for the agent performing this step"
+              },
+              expectedResult: {
+                type: "object",
+                description: "Expected output format",
+                properties: {
+                  format: {
+                    type: "string",
+                    enum: ["summary", "structured", "diff", "review", "test"]
+                  },
+                  fields: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Fields to include (for structured format)"
+                  },
+                  maxLength: {
+                    type: "number",
+                    description: "Max output length in characters"
+                  }
+                },
+                required: ["format"]
+              },
+              runtime: {
+                type: "string",
+                description: "Runtime to use (e.g. claude-code, codex)"
+              },
+              decision: {
+                type: "object",
+                description: "Why this runtime was chosen",
+                properties: {
+                  reason: { type: "string" },
+                  considered: {
+                    type: "array",
+                    items: { type: "string" }
+                  },
+                  chosen: { type: "string" }
+                },
+                required: ["reason", "considered", "chosen"]
+              },
+              dependsOn: {
+                type: "array",
+                items: { type: "string" },
+                description: "Step IDs this step depends on"
+              },
+              timeout: {
+                type: "number",
+                description: "Timeout in milliseconds"
+              }
+            },
+            required: [
+              "id",
+              "name",
+              "task",
+              "expectedResult",
+              "runtime",
+              "decision"
+            ]
+          }
+        }
+      },
+      required: ["name", "steps"]
+    }
+  },
+  yesod_workflow_status: {
+    name: "yesod_workflow_status",
+    description: "Check the current status of a running workflow, including per-step progress and results.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        workflowId: {
+          type: "string",
+          description: "ID of the workflow to check"
+        }
+      },
+      required: ["workflowId"]
+    }
+  },
+  yesod_cancel_workflow: {
+    name: "yesod_cancel_workflow",
+    description: "Cancel a running workflow. Kills all active sessions and marks the workflow as failed.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        workflowId: {
+          type: "string",
+          description: "ID of the workflow to cancel"
+        }
+      },
+      required: ["workflowId"]
+    }
+  },
+  yesod_cost_summary: {
+    name: "yesod_cost_summary",
+    description: "Get a cost breakdown showing token usage and USD cost, optionally filtered to a specific workflow.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        workflowId: {
+          type: "string",
+          description: "Optional: filter to a specific workflow"
+        }
+      }
+    }
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   EventBus,
   EventType,
   InMemoryStorageAdapter,
-  VantageEngine
+  OrchestrationEngine,
+  SimpleScheduler,
+  VantageEngine,
+  YESOD_TOOLS
 });
 //# sourceMappingURL=index.cjs.map