stagent 0.1.0

package/src/lib/workflows/loop-executor.ts

@@ -0,0 +1,270 @@
+import { db } from "@/lib/db";
+import { workflows, agentLogs } from "@/lib/db/schema";
+import { eq } from "drizzle-orm";
+import { executeChildTask, updateWorkflowState } from "./engine";
+import type { WorkflowDefinition, LoopState, IterationState, LoopStopReason } from "./types";
+import { createInitialLoopState } from "./types";
+
+/**
+ * Execute the loop pattern — autonomous iteration with stop conditions.
+ * Each iteration creates a child task, passes previous output as context,
+ * and checks for completion signals, time budgets, and pause requests.
+ */
+export async function executeLoop(
+  workflowId: string,
+  definition: WorkflowDefinition
+): Promise<void> {
+  if (!definition.loopConfig) {
+    throw new Error("Loop pattern requires loopConfig");
+  }
+  if (!definition.steps.length) {
+    throw new Error("Loop pattern requires at least one step (the loop prompt)");
+  }
+
+  const {
+    maxIterations,
+    timeBudgetMs,
+    assignedAgent,
+    agentProfile,
+    completionSignals,
+  } = definition.loopConfig;
+  const loopPrompt = definition.steps[0].prompt;
+
+  // Restore existing state (resume) or create fresh
+  const loopState = await restoreOrCreateLoopState(workflowId);
+  loopState.status = "running";
+  await updateLoopState(workflowId, loopState, "active");
+
+  const startTime = new Date(loopState.startedAt).getTime();
+  let previousOutput = "";
+
+  // If resuming, grab the last completed iteration's result
+  if (loopState.iterations.length > 0) {
+    const lastCompleted = [...loopState.iterations]
+      .reverse()
+      .find((i) => i.status === "completed");
+    if (lastCompleted?.result) {
+      previousOutput = lastCompleted.result;
+    }
+  }
+
+  try {
+    while (loopState.currentIteration < maxIterations) {
+      // Check pause: re-fetch workflow status from DB
+      const [workflow] = await db
+        .select()
+        .from(workflows)
+        .where(eq(workflows.id, workflowId));
+
+      if (workflow?.status === "paused") {
+        loopState.status = "paused";
+        loopState.stopReason = "human_pause";
+        await updateLoopState(workflowId, loopState, "paused");
+        return;
+      }
+
+      if (workflow?.status === "completed" || workflow?.status === "draft") {
+        loopState.status = "completed";
+        loopState.stopReason = "human_cancel";
+        await updateLoopState(workflowId, loopState, workflow.status as "completed" | "draft");
+        return;
+      }
+
+      // Check time budget
+      if (timeBudgetMs) {
+        const elapsed = Date.now() - startTime;
+        if (elapsed >= timeBudgetMs) {
+          await finalizeLoop(workflowId, loopState, "time_budget");
+          return;
+        }
+      }
+
+      const iterationNum = loopState.currentIteration + 1;
+
+      // Build iteration prompt
+      const prompt = buildIterationPrompt(
+        loopPrompt,
+        previousOutput,
+        iterationNum,
+        maxIterations
+      );
+
+      // Create iteration state
+      const iterationState: IterationState = {
+        iteration: iterationNum,
+        taskId: "",
+        status: "running",
+        startedAt: new Date().toISOString(),
+      };
+      loopState.iterations.push(iterationState);
+      await updateLoopState(workflowId, loopState, "active");
+
+      await db.insert(agentLogs).values({
+        id: crypto.randomUUID(),
+        taskId: null,
+        agentType: "loop-executor",
+        event: "loop_iteration_started",
+        payload: JSON.stringify({
+          workflowId,
+          iteration: iterationNum,
+          maxIterations,
+        }),
+        timestamp: new Date(),
+      });
+
+      // Execute child task
+      const result = await executeChildTask(
+        workflowId,
+        `Loop Iteration ${iterationNum}`,
+        prompt,
+        assignedAgent ?? definition.steps[0].assignedAgent,
+        agentProfile ?? definition.steps[0].agentProfile
+      );
+
+      // Update iteration state
+      const iterStartTime = new Date(iterationState.startedAt!).getTime();
+      iterationState.taskId = result.taskId;
+      iterationState.completedAt = new Date().toISOString();
+      iterationState.durationMs = Date.now() - iterStartTime;
+
+      if (result.status === "completed") {
+        iterationState.status = "completed";
+        iterationState.result = result.result;
+        previousOutput = result.result ?? "";
+      } else {
+        iterationState.status = "failed";
+        iterationState.error = result.error;
+        await finalizeLoop(workflowId, loopState, "error");
+        return;
+      }
+
+      loopState.currentIteration = iterationNum;
+      await updateLoopState(workflowId, loopState, "active");
+
+      // Check completion signal
+      if (
+        result.result &&
+        detectCompletionSignal(result.result, completionSignals)
+      ) {
+        await finalizeLoop(workflowId, loopState, "agent_signaled");
+        return;
+      }
+    }
+
+    // Exhausted max iterations
+    await finalizeLoop(workflowId, loopState, "max_iterations");
+  } catch (error) {
+    loopState.status = "failed";
+    loopState.stopReason = "error";
+    loopState.completedAt = new Date().toISOString();
+    loopState.totalDurationMs =
+      Date.now() - new Date(loopState.startedAt).getTime();
+    await updateLoopState(workflowId, loopState, "active");
+    throw error;
+  }
+}
+
+/**
+ * Build the prompt for a single iteration, including previous output context.
+ */
+export function buildIterationPrompt(
+  template: string,
+  previousOutput: string,
+  iteration: number,
+  maxIterations: number
+): string {
+  const parts: string[] = [];
+
+  parts.push(`Iteration ${iteration} of ${maxIterations}.`);
+
+  if (previousOutput) {
+    parts.push(`\nPrevious iteration output:\n${previousOutput}`);
+  }
+
+  parts.push(`\n---\n\n${template}`);
+  parts.push(
+    `\nWhen you are fully satisfied with the result, include "LOOP_COMPLETE" in your response.`
+  );
+
+  return parts.join("");
+}
+
+/**
+ * Check if the output contains a completion signal.
+ * Case-insensitive substring match against the signal list.
+ */
+export function detectCompletionSignal(
+  output: string,
+  signals?: string[]
+): boolean {
+  const effectiveSignals = signals?.length ? signals : ["LOOP_COMPLETE"];
+  const lowerOutput = output.toLowerCase();
+  return effectiveSignals.some((signal) =>
+    lowerOutput.includes(signal.toLowerCase())
+  );
+}
+
+/**
+ * Store loop state in the workflow definition JSON alongside _state.
+ */
+export async function updateLoopState(
+  workflowId: string,
+  loopState: LoopState,
+  workflowStatus: "draft" | "active" | "paused" | "completed"
+): Promise<void> {
+  const [workflow] = await db
+    .select()
+    .from(workflows)
+    .where(eq(workflows.id, workflowId));
+
+  if (!workflow) return;
+
+  const parsed = JSON.parse(workflow.definition);
+  const combined = { ...parsed, _loopState: loopState };
+
+  await db
+    .update(workflows)
+    .set({
+      definition: JSON.stringify(combined),
+      status: workflowStatus,
+      updatedAt: new Date(),
+    })
+    .where(eq(workflows.id, workflowId));
+}
+
+/**
+ * Restore existing loop state from DB or create a fresh one.
+ */
+async function restoreOrCreateLoopState(
+  workflowId: string
+): Promise<LoopState> {
+  const [workflow] = await db
+    .select()
+    .from(workflows)
+    .where(eq(workflows.id, workflowId));
+
+  if (workflow) {
+    const parsed = JSON.parse(workflow.definition);
+    if (parsed._loopState) {
+      return parsed._loopState as LoopState;
+    }
+  }
+
+  return createInitialLoopState();
+}
+
+/**
+ * Finalize a loop with a stop reason and mark the workflow as completed.
+ */
+async function finalizeLoop(
+  workflowId: string,
+  loopState: LoopState,
+  stopReason: LoopStopReason
+): Promise<void> {
+  loopState.status = "completed";
+  loopState.stopReason = stopReason;
+  loopState.completedAt = new Date().toISOString();
+  loopState.totalDurationMs =
+    Date.now() - new Date(loopState.startedAt).getTime();
+  await updateLoopState(workflowId, loopState, "completed");
+}

package/src/lib/workflows/parallel.ts

@@ -0,0 +1,55 @@
+import type { WorkflowDefinition, WorkflowStep } from "./types";
+
+export const MIN_PARALLEL_BRANCHES = 2;
+export const MAX_PARALLEL_BRANCHES = 5;
+export const PARALLEL_BRANCH_CONCURRENCY_LIMIT = 3;
+
+export interface ParallelWorkflowStructure {
+  branchSteps: WorkflowStep[];
+  synthesisStep: WorkflowStep;
+}
+
+export function getParallelWorkflowStructure(
+  definition: WorkflowDefinition
+): ParallelWorkflowStructure | null {
+  if (definition.pattern !== "parallel") {
+    return null;
+  }
+
+  const branchSteps = definition.steps.filter(
+    (step) => !step.dependsOn || step.dependsOn.length === 0
+  );
+  const synthesisSteps = definition.steps.filter(
+    (step) => step.dependsOn && step.dependsOn.length > 0
+  );
+
+  if (synthesisSteps.length !== 1) {
+    return null;
+  }
+
+  return {
+    branchSteps,
+    synthesisStep: synthesisSteps[0],
+  };
+}
+
+export function buildParallelSynthesisPrompt(input: {
+  branchOutputs: Array<{ stepName: string; result: string }>;
+  synthesisPrompt: string;
+}): string {
+  const sections = input.branchOutputs.map(
+    (branch, index) =>
+      `Branch ${index + 1} - ${branch.stepName}:\n${branch.result.trim()}`
+  );
+
+  return [
+    "You are synthesizing the completed results of parallel research branches.",
+    "",
+    "Parallel branch outputs:",
+    sections.join("\n\n---\n\n"),
+    "",
+    "---",
+    "",
+    input.synthesisPrompt,
+  ].join("\n");
+}

package/src/lib/workflows/swarm.ts

@@ -0,0 +1,97 @@
+import type { SwarmConfig, WorkflowDefinition, WorkflowStep } from "./types";
+
+export const MIN_SWARM_WORKERS = 2;
+export const MAX_SWARM_WORKERS = 5;
+export const DEFAULT_SWARM_CONCURRENCY_LIMIT = 2;
+
+export interface SwarmWorkflowStructure {
+  mayorStep: WorkflowStep;
+  workerSteps: WorkflowStep[];
+  refineryStep: WorkflowStep;
+  workerConcurrencyLimit: number;
+}
+
+export function getSwarmWorkflowStructure(
+  definition: WorkflowDefinition
+): SwarmWorkflowStructure | null {
+  if (definition.pattern !== "swarm" || definition.steps.length < 4) {
+    return null;
+  }
+
+  const mayorStep = definition.steps[0];
+  const refineryStep = definition.steps.at(-1);
+
+  if (!mayorStep || !refineryStep) {
+    return null;
+  }
+
+  const workerSteps = definition.steps.slice(1, -1);
+  if (workerSteps.length < MIN_SWARM_WORKERS) {
+    return null;
+  }
+
+  return {
+    mayorStep,
+    workerSteps,
+    refineryStep,
+    workerConcurrencyLimit: normalizeSwarmConcurrencyLimit(
+      definition.swarmConfig,
+      workerSteps.length
+    ),
+  };
+}
+
+export function normalizeSwarmConcurrencyLimit(
+  swarmConfig: SwarmConfig | undefined,
+  workerCount: number
+): number {
+  const rawLimit =
+    swarmConfig?.workerConcurrencyLimit ?? DEFAULT_SWARM_CONCURRENCY_LIMIT;
+
+  return Math.max(1, Math.min(rawLimit, Math.max(workerCount, 1)));
+}
+
+export function buildSwarmWorkerPrompt(input: {
+  mayorName: string;
+  mayorResult: string;
+  workerName: string;
+  workerPrompt: string;
+}): string {
+  return [
+    "You are one worker in a governed multi-agent swarm.",
+    "",
+    `${input.mayorName}:`,
+    input.mayorResult.trim(),
+    "",
+    `${input.workerName} assignment:`,
+    input.workerPrompt.trim(),
+    "",
+    "Complete only your assigned slice. Return concrete findings the refinery can merge.",
+  ].join("\n");
+}
+
+export function buildSwarmRefineryPrompt(input: {
+  mayorName: string;
+  mayorResult: string;
+  workerOutputs: Array<{ stepName: string; result: string }>;
+  refineryPrompt: string;
+}): string {
+  const workerSections = input.workerOutputs.map(
+    (worker, index) =>
+      `Worker ${index + 1} - ${worker.stepName}:\n${worker.result.trim()}`
+  );
+
+  return [
+    "You are the refinery for a governed multi-agent swarm.",
+    "",
+    `${input.mayorName}:`,
+    input.mayorResult.trim(),
+    "",
+    "Worker outputs:",
+    workerSections.join("\n\n---\n\n"),
+    "",
+    "---",
+    "",
+    input.refineryPrompt.trim(),
+  ].join("\n");
+}

package/src/lib/workflows/types.ts

@@ -0,0 +1,112 @@
+export type WorkflowPattern =
+  | "sequence"
+  | "planner-executor"
+  | "checkpoint"
+  | "loop"
+  | "parallel"
+  | "swarm";
+
+export interface WorkflowStep {
+  id: string;
+  name: string;
+  prompt: string;
+  requiresApproval?: boolean;
+  dependsOn?: string[];
+  assignedAgent?: string;
+  agentProfile?: string;
+}
+
+export interface LoopConfig {
+  maxIterations: number;
+  timeBudgetMs?: number;
+  assignedAgent?: string;
+  agentProfile?: string;
+  completionSignals?: string[];
+}
+
+export interface SwarmConfig {
+  workerConcurrencyLimit?: number;
+}
+
+export interface WorkflowDefinition {
+  pattern: WorkflowPattern;
+  steps: WorkflowStep[];
+  loopConfig?: LoopConfig;
+  swarmConfig?: SwarmConfig;
+}
+
+export type LoopStopReason =
+  | "max_iterations"
+  | "time_budget"
+  | "agent_signaled"
+  | "human_cancel"
+  | "human_pause"
+  | "error";
+
+export interface IterationState {
+  iteration: number;
+  taskId: string;
+  status: "pending" | "running" | "completed" | "failed";
+  result?: string;
+  error?: string;
+  startedAt?: string;
+  completedAt?: string;
+  durationMs?: number;
+}
+
+export interface LoopState {
+  currentIteration: number;
+  iterations: IterationState[];
+  status: "running" | "completed" | "paused" | "failed";
+  stopReason?: LoopStopReason;
+  startedAt: string;
+  completedAt?: string;
+  totalDurationMs?: number;
+}
+
+export function createInitialLoopState(): LoopState {
+  return {
+    currentIteration: 0,
+    iterations: [],
+    status: "running",
+    startedAt: new Date().toISOString(),
+  };
+}
+
+export type WorkflowStepStatus =
+  | "pending"
+  | "running"
+  | "completed"
+  | "failed"
+  | "waiting_approval"
+  | "waiting_dependencies";
+
+export interface StepState {
+  stepId: string;
+  status: WorkflowStepStatus;
+  taskId?: string;
+  result?: string;
+  error?: string;
+  startedAt?: string;
+  completedAt?: string;
+}
+
+export interface WorkflowState {
+  currentStepIndex: number;
+  stepStates: StepState[];
+  status: "running" | "completed" | "failed" | "paused";
+  startedAt: string;
+  completedAt?: string;
+}
+
+export function createInitialState(definition: WorkflowDefinition): WorkflowState {
+  return {
+    currentStepIndex: 0,
+    stepStates: definition.steps.map((step) => ({
+      stepId: step.id,
+      status: "pending",
+    })),
+    status: "running",
+    startedAt: new Date().toISOString(),
+  };
+}

package/tsconfig.json

@@ -0,0 +1,41 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": [
+      "dom",
+      "dom.iterable",
+      "esnext"
+    ],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "paths": {
+      "@/*": [
+        "./src/*"
+      ]
+    },
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ]
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}