@runravel/ravel 0.1.0

package/src/orchestrator/orchestrator.ts

@@ -0,0 +1,270 @@
+import { promises as fs } from "node:fs";
+import path, { basename } from "node:path";
+import type { RegistryProcess, RegistrySnapshot } from "../control-plane/registry.js";
+import type { Budget } from "../schemas/common.js";
+import { BudgetMeter } from "../trust/budget.js";
+import type { AuditSink } from "../trust/audit.js";
+import { newId, systemClock, type Clock } from "../domain/ids.js";
+import {
+  addUsage,
+  emptyUsage,
+  type TaskContract,
+  type TaskResult,
+  type Usage,
+} from "../domain/types.js";
+import type { Lifecycle } from "../runtime/lifecycle.js";
+import type { Planner, PlanContext, RosterEntry } from "./planner.js";
+
+/** Hard ceiling on orchestration turns, independent of budget, to bound any loop. */
+const ABSOLUTE_MAX_TURNS = 12;
+
+/**
+ * Field-wise minimum of a requested per-task budget and what's left of the
+ * process budget — a task can ask for less but never more than remains.
+ */
+export function clampBudget(requested: Budget | undefined, remaining: Budget): Budget {
+  if (!requested) return remaining;
+  const out: Budget = { ...remaining };
+  for (const k of ["tokens", "usd", "seconds", "turns"] as const) {
+    const req = requested[k];
+    const rem = remaining[k];
+    if (req !== undefined) out[k] = rem !== undefined ? Math.min(req, rem) : req;
+  }
+  return out;
+}
+
+export type ProcessRunStatus = "completed" | "budget_exhausted" | "failed";
+
+export interface ProcessRunResult {
+  runId: string;
+  processName: string;
+  status: ProcessRunStatus;
+  summary: string;
+  /** Every task result produced, in dispatch order. */
+  results: TaskResult[];
+  usage: Usage;
+  turns: number;
+  /** The run's shared workspace dir, where deliverables/handoffs live (if any). */
+  workspaceDir?: string;
+}
+
+export interface OrchestratorDeps {
+  lifecycle: Lifecycle;
+  planner: Planner;
+  audit: AuditSink;
+  /** Parent dir for per-run workspaces. When set, runs get a shared workspace. */
+  workspaceRoot?: string;
+  clock?: Clock;
+}
+
+/**
+ * Runs a process to completion via the orchestrated task-contract model:
+ *
+ *   plan (owner decomposes) → dispatch contracts to workers → collect results
+ *   → re-plan with results → … until done / budget / turn cap.
+ *
+ * This is the deterministic control loop. There is no free-form agent chatter:
+ * every handoff is a structured TaskContract and every return is a TaskResult.
+ * The process budget bounds total spend and turns so a run always terminates.
+ */
+export class Orchestrator {
+  private readonly clock: Clock;
+  constructor(private readonly deps: OrchestratorDeps) {
+    this.clock = deps.clock ?? systemClock;
+  }
+
+  /** Resolve the workers an owner may dispatch to: its descendants in the tree. */
+  private rosterFor(ownerId: string, snapshot: RegistrySnapshot): RosterEntry[] {
+    const prefix = ownerId === "" ? "" : `${ownerId}/`;
+    const roster: RosterEntry[] = [];
+    for (const node of snapshot.nodes.values()) {
+      if (node.id === ownerId) continue;
+      const inSubtree = ownerId === "" ? node.id !== "" : node.id.startsWith(prefix);
+      if (inSubtree && this.deps.lifecycle.get(node.id)) {
+        roster.push({ nodeId: node.id, role: node.spec.role ?? node.spec.name, name: node.spec.name });
+      }
+    }
+    return roster;
+  }
+
+  private resolveAssignee(role: string, roster: RosterEntry[]): RosterEntry | undefined {
+    const needle = role.trim().toLowerCase();
+    return roster.find(
+      (r) => r.role.toLowerCase() === needle || r.name.toLowerCase() === needle || r.nodeId.toLowerCase() === needle,
+    );
+  }
+
+  async runProcess(
+    proc: RegistryProcess,
+    snapshot: RegistrySnapshot,
+    run: { inputs?: Record<string, unknown>; files?: string[]; runId?: string } = {},
+  ): Promise<ProcessRunResult> {
+    const runId = run.runId ?? newId("run");
+    const processName = proc.spec.name;
+    const budget: Budget = proc.spec.budget ?? { turns: ABSOLUTE_MAX_TURNS };
+    const meter = new BudgetMeter(budget, this.clock);
+    const results: TaskResult[] = [];
+    let usage: Usage = emptyUsage();
+
+    await this.deps.audit.append("process.started", {
+      nodeId: proc.ownerNodeId,
+      runId,
+      data: { process: processName, ...(run.inputs ? { inputs: run.inputs } : {}) },
+    });
+
+    const owner = this.deps.lifecycle.get(proc.ownerNodeId);
+    if (!owner) {
+      return this.finalize(runId, processName, "failed", `owner ${proc.ownerNodeId} has no runtime`, results, usage, 0);
+    }
+
+    // Provision the per-run shared workspace and stage input files into shared/
+    // once, so every dispatched agent reads inputs and hands off artifacts there.
+    let workspaceRoot: string | undefined;
+    let sharedDir: string | undefined;
+    if (this.deps.workspaceRoot) {
+      workspaceRoot = path.join(this.deps.workspaceRoot, runId);
+      sharedDir = path.join(workspaceRoot, "shared");
+      await fs.mkdir(sharedDir, { recursive: true });
+      for (const src of run.files ?? []) {
+        try {
+          await fs.copyFile(src, path.join(sharedDir, basename(src)));
+          await this.deps.audit.append("run.file_staged", { runId, data: { file: basename(src) } });
+        } catch (err) {
+          await this.deps.audit.append("run.file_stage_failed", {
+            runId,
+            data: { file: src, error: err instanceof Error ? err.message : String(err) },
+          });
+        }
+      }
+    }
+
+    const roster = this.rosterFor(proc.ownerNodeId, snapshot);
+    let status: ProcessRunStatus = "completed";
+    let summary = "";
+    let turns = 0;
+
+    while (turns < ABSOLUTE_MAX_TURNS) {
+      if (meter.exceeded()) {
+        status = "budget_exhausted";
+        summary = `Process budget exhausted (${meter.exceeded()}).`;
+        break;
+      }
+      meter.recordTurn();
+      turns += 1;
+
+      const ctx: PlanContext = {
+        process: proc.spec,
+        ownerNodeId: proc.ownerNodeId,
+        roster,
+        priorResults: results,
+        budgetRemaining: meter.remaining(),
+        runId,
+        ...(run.inputs ? { runInputs: run.inputs } : {}),
+        ...(run.files?.length ? { runFileNames: run.files.map((f) => basename(f)) } : {}),
+      };
+      const plan = await this.deps.planner.plan(ctx);
+      meter.recordUsage(plan.usage);
+      usage = addUsage(usage, plan.usage);
+
+      await this.deps.audit.append("process.turn", {
+        nodeId: proc.ownerNodeId,
+        runId,
+        data: {
+          turn: turns,
+          done: plan.done,
+          taskCount: plan.tasks.length,
+          assignees: plan.tasks.map((t) => t.assigneeRole),
+        },
+      });
+
+      if (plan.done) {
+        summary = plan.summary ?? "Process completed.";
+        status = "completed";
+        break;
+      }
+
+      if (plan.tasks.length === 0) {
+        // No tasks and not done — nothing to advance; stop rather than spin.
+        summary = plan.summary ?? "Owner produced no tasks and did not mark the process done.";
+        status = "failed";
+        break;
+      }
+
+      for (const task of plan.tasks) {
+        const assignee = this.resolveAssignee(task.assigneeRole, roster);
+        if (!assignee) {
+          const failed: TaskResult = {
+            contractId: newId("task"),
+            status: "failed",
+            summary: `No agent for role "${task.assigneeRole}"`,
+            artifacts: {},
+            followUps: [],
+            usage: emptyUsage(),
+          };
+          results.push(failed);
+          await this.deps.audit.append("task.unrouted", {
+            nodeId: proc.ownerNodeId,
+            runId,
+            data: { role: task.assigneeRole },
+          });
+          continue;
+        }
+
+        const worker = this.deps.lifecycle.get(assignee.nodeId)!;
+        const contract: TaskContract = {
+          id: newId("task"),
+          assigneeNodeId: assignee.nodeId,
+          issuerNodeId: proc.ownerNodeId,
+          goal: task.goal,
+          // Run-level inputs are available to every task; the planned task's own
+          // inputs take precedence on key collisions.
+          inputs: { ...(run.inputs ?? {}), ...(task.inputs ?? {}) },
+          definitionOfDone: task.definitionOfDone,
+          // A task's own budget (used for fan-out) is clamped to what's left; with
+          // no per-task budget it gets the whole remaining process budget.
+          budget: clampBudget(task.budget, meter.remaining()),
+          runId,
+          // All run agents share one workspace; inputs are already staged in shared/.
+          ...(workspaceRoot ? { workspaceRoot } : {}),
+        };
+        const result = await worker.runTask(contract);
+        results.push(result);
+        meter.recordUsage(result.usage);
+        usage = addUsage(usage, result.usage);
+      }
+    }
+
+    if (turns >= ABSOLUTE_MAX_TURNS && status === "completed" && summary === "") {
+      status = "budget_exhausted";
+      summary = `Reached the orchestration turn cap (${ABSOLUTE_MAX_TURNS}).`;
+    }
+
+    return this.finalize(runId, processName, status, summary, results, usage, turns, sharedDir);
+  }
+
+  private async finalize(
+    runId: string,
+    processName: string,
+    status: ProcessRunStatus,
+    summary: string,
+    results: TaskResult[],
+    usage: Usage,
+    turns: number,
+    workspaceDir?: string,
+  ): Promise<ProcessRunResult> {
+    await this.deps.audit.append("process.finished", {
+      runId,
+      data: { process: processName, status, turns, usage },
+    });
+    return {
+      runId,
+      processName,
+      status,
+      summary,
+      results,
+      usage,
+      turns,
+      ...(workspaceDir ? { workspaceDir } : {}),
+    };
+  }
+}

package/src/orchestrator/planner.ts

@@ -0,0 +1,218 @@
+import { z } from "zod";
+import type { Budget } from "../schemas/common.js";
+import type { ProcessSpec } from "../schemas/process.js";
+import { emptyUsage, type TaskResult, type Usage } from "../domain/types.js";
+import type { AgentRuntime } from "../runtime/agent.js";
+
+/** A worker the owner may dispatch to (a descendant in the org tree). */
+export interface RosterEntry {
+  nodeId: string;
+  role: string;
+  name: string;
+}
+
+export interface PlanContext {
+  process: ProcessSpec;
+  ownerNodeId: string;
+  roster: RosterEntry[];
+  /** Results of tasks dispatched so far in this run (fed back for re-planning). */
+  priorResults: TaskResult[];
+  budgetRemaining: Budget;
+  runId: string;
+  /** Owner-supplied inputs for this run (e.g. prospect name, target languages). */
+  runInputs?: Record<string, unknown>;
+  /** Basenames of source files staged for this run, available to workers. */
+  runFileNames?: string[];
+}
+
+/** One task the owner wants to dispatch. */
+export interface PlannedTask {
+  assigneeRole: string;
+  goal: string;
+  definitionOfDone: string;
+  inputs?: Record<string, unknown>;
+  /**
+   * Optional per-task budget ceiling. Use it for fan-out (one task per item) so
+   * each task gets its own bounded slice rather than the whole remaining budget.
+   * Clamped to what's left of the process budget at dispatch.
+   */
+  budget?: Budget;
+}
+
+/**
+ * The owner's decision for this orchestration turn: either dispatch more tasks,
+ * or declare the process done with a final summary.
+ */
+export interface Plan {
+  done: boolean;
+  summary?: string;
+  tasks: PlannedTask[];
+  usage: Usage;
+}
+
+/**
+ * Decomposition is delegated to the owning manager agent — the orchestrator
+ * only runs the deterministic loop. Production uses `EnginePlanner` (the
+ * manager LLM emits a structured plan); tests inject a deterministic fake.
+ */
+export interface Planner {
+  plan(ctx: PlanContext): Promise<Plan>;
+}
+
+const PlanSchema = z.object({
+  done: z.boolean(),
+  summary: z.string().optional(),
+  tasks: z
+    .array(
+      z.object({
+        assigneeRole: z.string().min(1),
+        goal: z.string().min(1),
+        definitionOfDone: z.string().min(1),
+        inputs: z.record(z.unknown()).optional(),
+        budget: z
+          .object({
+            tokens: z.number().optional(),
+            usd: z.number().optional(),
+            seconds: z.number().optional(),
+            turns: z.number().optional(),
+          })
+          .optional(),
+      }),
+    )
+    .default([]),
+});
+
+/** Pull the first balanced top-level JSON object out of a model's text reply. */
+export function extractJsonObject(text: string): unknown {
+  const start = text.indexOf("{");
+  if (start === -1) return null;
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let i = start; i < text.length; i++) {
+    const ch = text[i]!;
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (ch === "\\") escaped = true;
+      else if (ch === '"') inString = false;
+      continue;
+    }
+    if (ch === '"') inString = true;
+    else if (ch === "{") depth++;
+    else if (ch === "}") {
+      depth--;
+      if (depth === 0) {
+        try {
+          return JSON.parse(text.slice(start, i + 1));
+        } catch {
+          return null;
+        }
+      }
+    }
+  }
+  return null;
+}
+
+function renderPlanPrompt(ctx: PlanContext): string {
+  const roster = ctx.roster.map((r) => `- role "${r.role}" (${r.name})`).join("\n") || "(no direct reports)";
+  const prior =
+    ctx.priorResults.length === 0
+      ? "(none yet — this is the first turn)"
+      : ctx.priorResults
+          .map((r, i) => `${i + 1}. [${r.status}] ${r.summary}`)
+          .join("\n");
+  const inputs =
+    ctx.runInputs && Object.keys(ctx.runInputs).length
+      ? Object.entries(ctx.runInputs)
+          .map(([k, v]) => `- ${k}: ${typeof v === "string" ? v : JSON.stringify(v)}`)
+          .join("\n")
+      : "(none)";
+  const files = ctx.runFileNames?.length
+    ? ctx.runFileNames.map((n) => `- ${n}`).join("\n")
+    : "(none)";
+  return [
+    `You are orchestrating the process "${ctx.process.name}".`,
+    ``,
+    `## Playbook`,
+    ctx.process.playbook,
+    ``,
+    `## Run inputs`,
+    inputs,
+    ``,
+    `## Source files (staged into each worker's working directory when dispatched)`,
+    files,
+    ``,
+    `## Definition of done`,
+    ctx.process.definitionOfDone,
+    ``,
+    `## Your team (you may dispatch tasks to these roles only)`,
+    roster,
+    ``,
+    `## Results so far`,
+    prior,
+    ``,
+    `Decide the next step. Respond with ONLY a JSON object of the form:`,
+    `{"done": boolean, "summary": string, "tasks": [{"assigneeRole": string, "goal": string, "definitionOfDone": string, "inputs": {}, "budget": {"usd": number, "turns": number}}]}`,
+    `Set "done": true with a "summary" when the definition of done is met or cannot be advanced.`,
+    `Otherwise set "done": false and list the task(s) to dispatch this turn.`,
+    `When you fan out over many items (e.g. one investigation per candidate),`,
+    `dispatch ONE task per item and give each a small per-task "budget" (e.g.`,
+    `{"usd": 0.5, "turns": 6}) so a long item can't drain the whole process budget.`,
+    `Omit "budget" for a single task that may use the remaining budget.`,
+    `A result marked [deferred] means the worker finished but a consequential action`,
+    `(e.g. sending or delivering) is queued for human approval — that work is DONE`,
+    `from your side. Do NOT re-dispatch a deferred task; treat its step as complete`,
+    `and mark the process "done" once the remaining steps are covered.`,
+  ].join("\n");
+}
+
+/**
+ * Planner backed by the owning agent's model. Asks the manager to emit a
+ * structured plan; if the reply can't be parsed as a plan, treats the reply as
+ * a final summary (fail safe — never loops on malformed output).
+ */
+export class EnginePlanner implements Planner {
+  constructor(private readonly resolveRuntime: (nodeId: string) => AgentRuntime | undefined) {}
+
+  async plan(ctx: PlanContext): Promise<Plan> {
+    const owner = this.resolveRuntime(ctx.ownerNodeId);
+    if (!owner) {
+      return { done: true, summary: `owner ${ctx.ownerNodeId} has no runtime`, tasks: [], usage: emptyUsage() };
+    }
+    let outcome = await owner.ask(renderPlanPrompt(ctx), {
+      budget: ctx.budgetRemaining,
+      runId: ctx.runId,
+    });
+    let parsed = PlanSchema.safeParse(extractJsonObject(outcome.text));
+    if (!parsed.success) {
+      // No parseable plan. The planner may have spent its turn budget on tool
+      // calls and never emitted the JSON. Retry once, demanding JSON and no tools
+      // — distinguishes "ran out of turns inspecting" from "genuinely done".
+      outcome = await owner.ask(
+        renderPlanPrompt(ctx) +
+          `\n\nIMPORTANT: Respond with ONLY the JSON plan object — no prose, and do NOT call any tools. ` +
+          `If there is nothing left to dispatch, return {"done": true, "summary": "..."}.`,
+        { budget: ctx.budgetRemaining, runId: ctx.runId },
+      );
+      parsed = PlanSchema.safeParse(extractJsonObject(outcome.text));
+    }
+    if (!parsed.success) {
+      // Still no plan — terminate, but make the reason VISIBLE rather than
+      // reporting a clean "completed" that silently did nothing.
+      return {
+        done: true,
+        summary: `Planner produced no structured plan (stopReason=${outcome.stopReason}${
+          outcome.budgetExceeded ? ", budget exhausted" : ""
+        }). No tasks dispatched. Raw reply: ${(outcome.text || "(empty)").slice(0, 200)}`,
+        tasks: [],
+        usage: outcome.usage,
+      };
+    }
+    return {
+      done: parsed.data.done,
+      ...(parsed.data.summary !== undefined ? { summary: parsed.data.summary } : {}),
+      tasks: parsed.data.tasks,
+      usage: outcome.usage,
+    };
+  }
+}