@agentic-sdlc/dispatch 0.1.0

package/bin/dispatch.ts

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+import { resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { orchestrateStage } from "../src/orchestrator.js";
+import { readWorkflow } from "../src/workflow-reader.js";
+import { createSandboxProvider } from "../src/sandbox-provider.js";
+import type { RpcCommand } from "../src/sandbox-provider.js";
+
+interface CliArgs {
+  issue: number;
+  repo: string;
+  label?: string;
+  comment?: string;
+}
+
+function parseArgs(argv: string[]): CliArgs {
+  const args: Partial<CliArgs> = {};
+
+  for (let i = 0; i < argv.length; i++) {
+    const key = argv[i];
+    const value = argv[i + 1];
+    switch (key) {
+      case "--issue":
+        args.issue = Number(value);
+        i++;
+        break;
+      case "--repo":
+        args.repo = value;
+        i++;
+        break;
+      case "--label":
+        args.label = value;
+        i++;
+        break;
+      case "--comment":
+        args.comment = value;
+        i++;
+        break;
+      case "--help":
+        printUsage();
+        process.exit(0);
+    }
+  }
+
+  if (!args.issue) args.issue = parseInt(process.env.ISSUE_NUMBER ?? "", 10);
+  if (!args.repo) args.repo = process.env.REPO_NAME ?? process.env.GITHUB_REPOSITORY ?? "";
+  if (!args.label && !args.comment) args.label = process.env.LABEL_NAME ?? "";
+
+  if (!args.issue || isNaN(args.issue)) {
+    console.error("[dispatch] Missing required: --issue <number> or ISSUE_NUMBER env");
+    process.exit(1);
+  }
+  if (!args.repo) {
+    console.error("[dispatch] Missing required: --repo <owner/repo> or REPO_NAME env");
+    process.exit(1);
+  }
+  if (!args.label && !args.comment) {
+    console.error("[dispatch] Missing required: --label or --comment (or LABEL_NAME env)");
+    process.exit(1);
+  }
+
+  return args as CliArgs;
+}
+
+function printUsage(): void {
+  console.log(`Usage: harness-dispatch [options]
+
+Options:
+  --issue <number>    Issue number (or ISSUE_NUMBER env)
+  --repo <owner/repo> Repository (or REPO_NAME / GITHUB_REPOSITORY env)
+  --label <name>      Label that triggered the pipeline (or LABEL_NAME env)
+  --comment <text>    Forward a comment to the agent
+  --help              Show this help
+
+Environment variables:
+  DAYTONA_API_KEY         Sandbox provider auth
+  DAYTONA_API_URL         Sandbox API endpoint (default: https://app.daytona.io/api)
+  GH_TOKEN                GitHub token for API access
+  HARNESS_MODEL_API_KEY   Model provider API key
+  MODEL                   Model identifier
+  AWS_REGION              AWS region (default: us-east-1)
+  SNAPSHOT_NAME           Daytona snapshot name (default: pi-agent-v1)
+  HARNESS_SANDBOX_PROVIDER  Provider override: daytona | direct
+`);
+}
+
+interface DispatchConfig {
+  ghToken: string;
+  modelApiKey: string;
+  modelRegion: string;
+  model: string;
+  snapshotName: string;
+  daytonaApiKey?: string;
+  daytonaApiUrl?: string;
+}
+
+function loadConfig(): DispatchConfig {
+  const ghToken = process.env.GH_TOKEN ?? "";
+  if (!ghToken) {
+    console.error("[dispatch] Missing required: GH_TOKEN env");
+    process.exit(1);
+  }
+
+  return {
+    ghToken,
+    modelApiKey: process.env.HARNESS_MODEL_API_KEY ?? process.env.MODEL_API_KEY ?? "",
+    modelRegion: process.env.AWS_REGION ?? "us-east-1",
+    model: process.env.MODEL ?? "us.anthropic.claude-sonnet-4-20250514-v1:0",
+    snapshotName: process.env.SNAPSHOT_NAME ?? "pi-agent-v1",
+    daytonaApiKey: process.env.DAYTONA_API_KEY,
+    daytonaApiUrl: process.env.DAYTONA_API_URL,
+  };
+}
+
+async function main(): Promise<void> {
+  const args = parseArgs(process.argv.slice(2));
+  const config = loadConfig();
+
+  const workflowPath = resolve("WORKFLOW.md");
+  if (!existsSync(workflowPath)) {
+    console.error("[dispatch] WORKFLOW.md not found in current directory");
+    process.exit(1);
+  }
+
+  const workflowConfig = readWorkflow(workflowPath);
+  console.log(`[dispatch] Issue #${args.issue} | repo: ${args.repo} | ${args.label ? `label: ${args.label}` : `comment mode`}`);
+
+  const provider = createSandboxProvider({
+    apiKey: config.daytonaApiKey ?? "",
+    apiUrl: config.daytonaApiUrl ?? "",
+    ghToken: config.ghToken,
+    snapshotName: config.snapshotName,
+    modelApiKey: config.modelApiKey,
+    modelRegion: config.modelRegion,
+    model: config.model,
+  });
+
+  const sandbox = await provider.create({
+    issue: args.issue,
+    repo: args.repo,
+    profile: workflowConfig.sandbox.default_profile,
+  });
+  console.log(`[dispatch] Sandbox created: ${sandbox.id}`);
+
+  try {
+    await provider.rpc(sandbox.id, {
+      type: "prompt",
+      text: [
+        'git config user.email "bot@harness.dev"',
+        'git config user.name "Harness Bot"',
+      ].join(" && "),
+      issueNumber: args.issue,
+    });
+
+    if (args.label) {
+      await runLabelDispatch(args, config, provider, sandbox.id, workflowConfig);
+    } else if (args.comment) {
+      await runCommentDispatch(args, config, provider, sandbox.id);
+    }
+  } finally {
+    console.log(`[dispatch] Destroying sandbox ${sandbox.id}...`);
+    await provider.destroy(sandbox.id);
+    console.log("[dispatch] Done.");
+  }
+}
+
+async function runLabelDispatch(
+  args: CliArgs,
+  config: DispatchConfig,
+  provider: Awaited<ReturnType<typeof createSandboxProvider>>,
+  sandboxId: string,
+  workflowConfig: ReturnType<typeof readWorkflow>,
+): Promise<void> {
+  const piCommand = [
+    `ISSUE_NUMBER=${args.issue}`,
+    `AWS_BEARER_TOKEN_BEDROCK=$HARNESS_MODEL_API_KEY`,
+    `AWS_REGION=${config.modelRegion}`,
+    `GH_TOKEN=$GH_TOKEN`,
+    `pi -p "Process issue #${args.issue}. Current label: ${args.label}."`,
+    `-e node_modules/@agentic-sdlc/extension/src/index.ts`,
+    `--provider amazon-bedrock`,
+    `--model ${config.model}`,
+  ].join(" ");
+
+  console.log("[dispatch] Starting Pi agent...");
+  try {
+    const output = await provider.rpc(sandboxId, {
+      type: "prompt",
+      text: piCommand,
+      issueNumber: args.issue,
+    });
+    if (output) console.log(`[dispatch] Pi output: ${output.slice(0, 500)}`);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.log(`[dispatch] Pi exited: ${message.slice(0, 500)}`);
+  }
+
+  console.log("[dispatch] Running post-agent orchestration...");
+  const artifactsDir = resolve(`artifacts/issue-${args.issue}`);
+  const result = orchestrateStage({
+    issueNumber: args.issue,
+    repo: args.repo,
+    label: args.label!,
+    workflowConfig,
+    artifactsDir,
+  });
+
+  console.log(`[dispatch] Orchestration: stage=${result.stage} action=${result.action} nextLabel=${result.nextLabel ?? "none"}`);
+}
+
+async function runCommentDispatch(
+  args: CliArgs,
+  config: DispatchConfig,
+  provider: Awaited<ReturnType<typeof createSandboxProvider>>,
+  sandboxId: string,
+): Promise<void> {
+  const escapedComment = (args.comment ?? "").replace(/'/g, "'\\''");
+  const piCommand = [
+    `ISSUE_NUMBER=${args.issue}`,
+    `AWS_BEARER_TOKEN_BEDROCK=$HARNESS_MODEL_API_KEY`,
+    `AWS_REGION=${config.modelRegion}`,
+    `GH_TOKEN=$GH_TOKEN`,
+    `pi -p 'Human commented on issue #${args.issue}: ${escapedComment}'`,
+    `-e node_modules/@agentic-sdlc/extension/src/index.ts`,
+    `--provider amazon-bedrock`,
+    `--model ${config.model}`,
+  ].join(" ");
+
+  console.log("[dispatch] Forwarding comment to Pi agent...");
+  try {
+    await provider.rpc(sandboxId, {
+      type: "follow_up",
+      text: piCommand,
+      issueNumber: args.issue,
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.log(`[dispatch] Pi exited: ${message.slice(0, 500)}`);
+  }
+}
+
+main().catch((err) => {
+  console.error(`[dispatch] Fatal: ${err instanceof Error ? err.message : String(err)}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@agentic-sdlc/dispatch",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "CI-side dispatch and orchestration for the agentic SDLC harness",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hjgraca/agentic-sdlc-harness.git",
+    "directory": "packages/dispatch"
+  },
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "bin": {
+    "harness-dispatch": "./bin/dispatch.ts"
+  },
+  "files": ["src", "bin", "dist"],
+  "dependencies": {
+    "@daytona/sdk": "^0.175.0",
+    "yaml": "^2.8.0"
+  },
+  "devDependencies": {
+    "vitest": "^3.2.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.8.0"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "build": "tsc"
+  }
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export { orchestrateStage } from "./orchestrator.js";
+export { readWorkflow } from "./workflow-reader.js";
+export type { StageConfig, PipelineConfig, WorkflowConfig, OrchestrationContext, OrchestrationResult } from "./types.js";
+
+export { createSandboxProvider } from "./sandbox-provider.js";
+export type { SandboxProvider, SandboxProviderConfig, RpcCommand, SandboxStatus } from "./sandbox-provider.js";
+export { DaytonaSandboxProvider } from "./providers/daytona.js";
+export { DirectRunnerProvider } from "./providers/direct-runner.js";

package/src/orchestrator.ts

@@ -0,0 +1,273 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { OrchestrationContext, OrchestrationResult, StageConfig } from "./types.js";
+
+export function orchestrateStage(ctx: OrchestrationContext): OrchestrationResult {
+  const { issueNumber, repo, label, workflowConfig, artifactsDir } = ctx;
+  const { pipeline } = workflowConfig;
+
+  // 1. Find the stage from the label
+  const stageName = pipeline.labels[label];
+  if (!stageName) {
+    console.error(`[dispatch] No stage mapped for label "${label}"`);
+    return { stage: "unknown", action: "escalated", nextLabel: "escalated" };
+  }
+
+  const stageIndex = pipeline.stages.findIndex((s) => s.name === stageName);
+  if (stageIndex === -1) {
+    console.error(`[dispatch] Stage "${stageName}" not found in pipeline.stages`);
+    return { stage: stageName, action: "escalated", nextLabel: "escalated" };
+  }
+
+  const stage = pipeline.stages[stageIndex];
+
+  // 2. Check artifact exists (if stage produces one)
+  if (stage.produces) {
+    const artifactPath = join(artifactsDir, stage.produces);
+    if (!existsSync(artifactPath)) {
+      console.error(`[dispatch] Artifact not found: ${artifactPath}`);
+      applyLabel(repo, issueNumber, "escalated", label);
+      return { stage: stage.name, action: "no-artifact", nextLabel: "escalated" };
+    }
+  }
+
+  // 3. Handle by gate type
+  switch (stage.gate) {
+    case "none":
+      return handleGateNone(ctx, stage, stageIndex);
+    case "pr-review":
+      return handleGatePrReview(ctx, stage, stageIndex);
+    case "retry":
+      return handleGateRetry(ctx, stage, stageIndex);
+    default:
+      console.error(`[dispatch] Unknown gate type: ${stage.gate}`);
+      return { stage: stage.name, action: "escalated", nextLabel: "escalated" };
+  }
+}
+
+function handleGateNone(
+  ctx: OrchestrationContext,
+  stage: StageConfig,
+  stageIndex: number
+): OrchestrationResult {
+  const { issueNumber, repo, label, workflowConfig, artifactsDir } = ctx;
+
+  // Commit artifact to current branch and push
+  try {
+    execFileSync("git", ["add", artifactsDir]);
+    execFileSync("git", ["commit", "-m", `chore: add ${stage.produces} for issue #${issueNumber}`]);
+    execFileSync("git", ["push"]);
+  } catch (err) {
+    console.error(`[dispatch] Git commit/push failed for gate=none:`, err);
+  }
+
+  // Advance to next stage label
+  const nextLabel = findNextStageLabel(workflowConfig.pipeline, stageIndex);
+  if (nextLabel) {
+    applyLabel(repo, issueNumber, nextLabel, label);
+  }
+
+  return { stage: stage.name, action: "advanced", nextLabel };
+}
+
+function handleGatePrReview(
+  ctx: OrchestrationContext,
+  stage: StageConfig,
+  stageIndex: number
+): OrchestrationResult {
+  const { issueNumber, repo, label, workflowConfig, artifactsDir } = ctx;
+
+  const branchName = renderTemplate(stage.branch_pattern ?? `${stage.name}/issue-{{ issue.number }}`, issueNumber);
+
+  // Create or checkout branch
+  try {
+    execFileSync("git", ["checkout", "-b", branchName]);
+  } catch {
+    // Branch may already exist — try checking it out
+    try {
+      execFileSync("git", ["checkout", branchName]);
+    } catch (err) {
+      console.error(`[dispatch] Failed to checkout branch ${branchName}:`, err);
+    }
+  }
+
+  // Commit artifacts
+  try {
+    execFileSync("git", ["add", artifactsDir]);
+    execFileSync("git", ["commit", "-m", `feat: add ${stage.produces} for issue #${issueNumber}`]);
+  } catch (err) {
+    console.error(`[dispatch] Git commit failed for pr-review gate:`, err);
+  }
+
+  // Push branch
+  try {
+    execFileSync("git", ["push", "-u", "origin", branchName]);
+  } catch (err) {
+    console.error(`[dispatch] Git push failed:`, err);
+  }
+
+  // Open PR if one does not already exist
+  let prCreated = false;
+  try {
+    const existing = execFileSync("gh", [
+      "pr", "list",
+      "--repo", repo,
+      "--head", branchName,
+      "--json", "number",
+    ]).toString().trim();
+
+    const prs = JSON.parse(existing || "[]");
+    if (prs.length === 0) {
+      execFileSync("gh", [
+        "pr", "create",
+        "--repo", repo,
+        "--head", branchName,
+        "--title", `[#${issueNumber}] ${stage.name}: ${stage.produces}`,
+        "--body", `Automated PR for issue #${issueNumber} — stage: ${stage.name}`,
+      ]);
+      prCreated = true;
+    }
+  } catch (err) {
+    console.error(`[dispatch] PR creation failed:`, err);
+  }
+
+  // Find the "ready" label for this stage (convention: stage's own ready label)
+  const readyLabel = findReadyLabel(workflowConfig.pipeline, stage.name);
+  const nextLabel = readyLabel ?? findNextStageLabel(workflowConfig.pipeline, stageIndex);
+
+  if (nextLabel) {
+    applyLabel(repo, issueNumber, nextLabel, label);
+  }
+
+  return {
+    stage: stage.name,
+    action: prCreated ? "opened-pr" : "advanced",
+    nextLabel,
+  };
+}
+
+function handleGateRetry(
+  ctx: OrchestrationContext,
+  stage: StageConfig,
+  stageIndex: number
+): OrchestrationResult {
+  const { issueNumber, repo, label, workflowConfig, artifactsDir } = ctx;
+
+  // Read verdict from artifact frontmatter
+  const verdict = readVerdictFromArtifact(artifactsDir, stage.produces ?? "");
+  const maxRetries = stage.max_retries ?? 3;
+
+  if (verdict === "pass") {
+    // Advance to next stage
+    const nextLabel = findNextStageLabel(workflowConfig.pipeline, stageIndex);
+    if (nextLabel) {
+      applyLabel(repo, issueNumber, nextLabel, label);
+    }
+    return { stage: stage.name, action: "advanced", nextLabel };
+  }
+
+  // verdict is "fail" or unknown — check retry count
+  const attemptCount = getAttemptCount(artifactsDir, stage.name);
+
+  if (attemptCount >= maxRetries) {
+    applyLabel(repo, issueNumber, "escalated", label);
+    return { stage: stage.name, action: "escalated", nextLabel: "escalated" };
+  }
+
+  // Apply retry label (needs-fix)
+  const retryLabel = findRetryLabel(workflowConfig.pipeline, stage.name);
+  if (retryLabel) {
+    applyLabel(repo, issueNumber, retryLabel, label);
+  }
+
+  return { stage: stage.name, action: "retried", nextLabel: retryLabel };
+}
+
+// --- Helpers ---
+
+function renderTemplate(pattern: string, issueNumber: number): string {
+  return pattern.replace(/\{\{\s*issue\.number\s*\}\}/g, String(issueNumber));
+}
+
+function applyLabel(repo: string, issueNumber: number, addLabel: string, removeLabel: string): void {
+  try {
+    execFileSync("gh", [
+      "issue", "edit", String(issueNumber),
+      "--repo", repo,
+      "--add-label", addLabel,
+      "--remove-label", removeLabel,
+    ]);
+  } catch (err) {
+    console.error(`[dispatch] Label transition failed (add=${addLabel}, remove=${removeLabel}):`, err);
+  }
+}
+
+function findNextStageLabel(
+  pipeline: OrchestrationContext["workflowConfig"]["pipeline"],
+  currentStageIndex: number
+): string | undefined {
+  const nextStage = pipeline.stages[currentStageIndex + 1];
+  if (!nextStage) return undefined;
+
+  // Find the label that maps to the next stage's name
+  for (const [lbl, stageName] of Object.entries(pipeline.labels)) {
+    if (stageName === nextStage.name) {
+      return lbl;
+    }
+  }
+  return undefined;
+}
+
+function findReadyLabel(
+  pipeline: OrchestrationContext["workflowConfig"]["pipeline"],
+  stageName: string
+): string | undefined {
+  // Convention: look for a label like "{stage}-ready" that maps to this stage
+  for (const [lbl, mapped] of Object.entries(pipeline.labels)) {
+    if (mapped === stageName && lbl.endsWith("-ready")) {
+      return lbl;
+    }
+  }
+  return undefined;
+}
+
+function findRetryLabel(
+  pipeline: OrchestrationContext["workflowConfig"]["pipeline"],
+  stageName: string
+): string | undefined {
+  // Look for a label that triggers the preceding stage (for retry, we go back)
+  // Convention: "needs-fix" maps to the build stage for retries
+  for (const [lbl, mapped] of Object.entries(pipeline.labels)) {
+    if (lbl === "needs-fix" || lbl.includes("retry") || lbl.includes("fix")) {
+      return lbl;
+    }
+  }
+  return undefined;
+}
+
+function readVerdictFromArtifact(artifactsDir: string, artifactName: string): string {
+  try {
+    const content = readFileSync(join(artifactsDir, artifactName), "utf-8");
+    const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!frontmatterMatch) return "unknown";
+
+    const verdictMatch = frontmatterMatch[1].match(/^verdict:\s*(.+)$/m);
+    return verdictMatch ? verdictMatch[1].trim().toLowerCase() : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+function getAttemptCount(artifactsDir: string, stageName: string): number {
+  try {
+    const attemptFile = join(artifactsDir, `.${stageName}-attempts`);
+    if (existsSync(attemptFile)) {
+      const count = parseInt(readFileSync(attemptFile, "utf-8").trim(), 10);
+      return isNaN(count) ? 1 : count;
+    }
+    return 1;
+  } catch {
+    return 1;
+  }
+}

package/src/providers/daytona.ts

@@ -0,0 +1,157 @@
+import { Daytona, Sandbox } from "@daytona/sdk";
+import type { CreateSandboxFromSnapshotParams } from "@daytona/sdk";
+import type { SandboxProvider, SandboxProviderConfig, RpcCommand, SandboxStatus } from "../sandbox-provider.js";
+
+// ---------------------------------------------------------------------------
+// Daytona state mapping
+// ---------------------------------------------------------------------------
+
+export function mapDaytonaState(daytonaState: string): SandboxStatus["state"] {
+  switch (daytonaState) {
+    case "started":
+      return "running";
+    case "stopped":
+    case "archived":
+      return "paused";
+    default:
+      return "stopped";
+  }
+}
+
+// ---------------------------------------------------------------------------
+// DaytonaSandboxProvider
+// ---------------------------------------------------------------------------
+
+export interface DaytonaSandboxProviderOptions {
+  apiKey: string;
+  apiUrl: string;
+  ghToken: string;
+  snapshotName?: string;
+  modelApiKey?: string;
+  modelRegion?: string;
+  model?: string;
+}
+
+export class DaytonaSandboxProvider implements SandboxProvider {
+  private daytona: Daytona;
+  private ghToken: string;
+  private snapshotName: string | undefined;
+  private modelApiKey: string;
+  private modelRegion: string;
+  private model: string;
+  private sandboxCache: Map<string, Sandbox> = new Map();
+
+  constructor(options: DaytonaSandboxProviderOptions) {
+    if (!options.apiKey) {
+      throw new Error("DaytonaSandboxProvider: apiKey is required");
+    }
+    if (!options.apiUrl) {
+      options.apiUrl = "https://app.daytona.io/api";
+    }
+    if (!options.ghToken) {
+      throw new Error("DaytonaSandboxProvider: ghToken is required");
+    }
+
+    this.daytona = new Daytona({
+      apiKey: options.apiKey,
+      apiUrl: options.apiUrl,
+    });
+    this.ghToken = options.ghToken;
+    this.snapshotName = options.snapshotName;
+    this.modelApiKey = options.modelApiKey ?? "";
+    this.modelRegion = options.modelRegion ?? "us-east-1";
+    this.model = options.model ?? "bedrock:us.anthropic.claude-sonnet-4-20250514-v1:0";
+  }
+
+  async create(config: SandboxProviderConfig): Promise<{ id: string }> {
+    const createOptions: CreateSandboxFromSnapshotParams = {
+      language: "typescript",
+      labels: {
+        "github-issue": String(config.issue),
+        "github-repo": config.repo,
+        profile: config.profile,
+      },
+      autoStopInterval: 30,
+    };
+
+    if (this.snapshotName) {
+      createOptions.snapshot = this.snapshotName;
+    }
+
+    const sandbox = await this.daytona.create(createOptions);
+    const id = sandbox.id;
+
+    this.sandboxCache.set(id, sandbox);
+
+    // Use token-authenticated URL for private repos
+    const repoUrl = `https://x-access-token:${this.ghToken}@github.com/${config.repo}.git`;
+    await sandbox.git.clone(repoUrl, "/home/daytona/project");
+
+    // Configure gh CLI auth and strip token from git remote
+    await sandbox.process.executeCommand(
+      "gh auth setup-git",
+      "/home/daytona/project",
+      { GH_TOKEN: this.ghToken }
+    );
+    await sandbox.process.executeCommand(
+      `git remote set-url origin https://github.com/${config.repo}.git`,
+      "/home/daytona/project"
+    );
+
+    return { id };
+  }
+
+  async resume(id: string): Promise<void> {
+    const sandbox = await this.getSandbox(id);
+    await sandbox.start();
+  }
+
+  async pause(id: string): Promise<void> {
+    const sandbox = await this.getSandbox(id);
+    await sandbox.stop();
+  }
+
+  async destroy(id: string): Promise<void> {
+    const sandbox = await this.getSandbox(id);
+    await sandbox.delete();
+    this.sandboxCache.delete(id);
+  }
+
+  async rpc(id: string, command: RpcCommand): Promise<string> {
+    const sandbox = await this.getSandbox(id);
+
+    if (command.text) {
+      const result = await sandbox.process.executeCommand(
+        command.text,
+        "/home/daytona/project",
+        {
+          GH_TOKEN: this.ghToken,
+          MODEL_API_KEY: this.modelApiKey,
+          AWS_REGION: this.modelRegion,
+          MODEL: this.model,
+          ISSUE_NUMBER: String(command.issueNumber ?? ""),
+        }
+      );
+      if (result.exitCode !== 0) {
+        throw new Error(`RPC command failed (exit ${result.exitCode}): ${result.result}`);
+      }
+      return result.result ?? "";
+    }
+    return "";
+  }
+
+  async status(id: string): Promise<SandboxStatus> {
+    const sandbox = await this.getSandbox(id);
+    const daytonaState: string = sandbox.state ?? "unknown";
+    return { state: mapDaytonaState(daytonaState) };
+  }
+
+  private async getSandbox(id: string): Promise<Sandbox> {
+    const cached = this.sandboxCache.get(id);
+    if (cached) return cached;
+
+    const sandbox = await this.daytona.get(id);
+    this.sandboxCache.set(id, sandbox);
+    return sandbox;
+  }
+}

package/src/providers/direct-runner.ts

@@ -0,0 +1,91 @@
+import { mkdtempSync, rmSync, existsSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import type { SandboxProvider, SandboxProviderConfig, RpcCommand, SandboxStatus } from "../sandbox-provider.js";
+
+// ---------------------------------------------------------------------------
+// DirectRunnerProvider — lightweight local execution without remote sandboxes
+// ---------------------------------------------------------------------------
+
+export class DirectRunnerProvider implements SandboxProvider {
+  private sandboxes: Map<string, string> = new Map();
+
+  async create(config: SandboxProviderConfig): Promise<{ id: string }> {
+    const id = randomUUID();
+    const dir = mkdtempSync(join(tmpdir(), `harness-sandbox-${id.slice(0, 8)}-`));
+
+    // Clone the repo into the temp directory
+    const repoUrl = `https://github.com/${config.repo}.git`;
+    try {
+      execFileSync("git", ["clone", repoUrl, dir], {
+        stdio: "pipe",
+        env: { ...process.env },
+      });
+    } catch (err: unknown) {
+      // Clean up on clone failure
+      rmSync(dir, { recursive: true, force: true });
+      const message = err instanceof Error ? err.message : String(err);
+      throw new Error(`DirectRunnerProvider: failed to clone ${config.repo}: ${message}`);
+    }
+
+    this.sandboxes.set(id, dir);
+    return { id };
+  }
+
+  async resume(_id: string): Promise<void> {
+    // no-op for local execution
+  }
+
+  async pause(_id: string): Promise<void> {
+    // no-op for local execution
+  }
+
+  async destroy(id: string): Promise<void> {
+    const dir = this.sandboxes.get(id);
+    if (dir && existsSync(dir)) {
+      rmSync(dir, { recursive: true, force: true });
+    }
+    this.sandboxes.delete(id);
+  }
+
+  async rpc(id: string, command: RpcCommand): Promise<string> {
+    const dir = this.sandboxes.get(id);
+    if (!dir) {
+      throw new Error(`DirectRunnerProvider: sandbox ${id} not found`);
+    }
+
+    if (!command.text) {
+      return "";
+    }
+
+    try {
+      const result = execFileSync("bash", ["-c", command.text], {
+        cwd: dir,
+        stdio: "pipe",
+        env: {
+          ...process.env,
+          ISSUE_NUMBER: String(command.issueNumber ?? ""),
+        },
+        maxBuffer: 10 * 1024 * 1024, // 10MB
+      });
+      return result.toString();
+    } catch (err: unknown) {
+      const exitCode = (err as { status?: number }).status ?? 1;
+      const stderr = (err as { stderr?: Buffer }).stderr?.toString() ?? "";
+      throw new Error(
+        `DirectRunnerProvider: command failed (exit ${exitCode}): ${stderr || (err instanceof Error ? err.message : String(err))}`
+      );
+    }
+  }
+
+  async status(_id: string): Promise<SandboxStatus> {
+    return { state: "running" };
+  }
+
+  /** Visible for testing: get the working directory for a sandbox */
+  getWorkDir(id: string): string | undefined {
+    return this.sandboxes.get(id);
+  }
+}

package/src/sandbox-provider.ts

@@ -0,0 +1,58 @@
+// ---------------------------------------------------------------------------
+// Sandbox provider interface and factory
+// ---------------------------------------------------------------------------
+
+export interface SandboxProviderConfig {
+  issue: number;
+  repo: string;
+  profile: string;
+}
+
+export interface RpcCommand {
+  type: "prompt" | "follow_up" | "steer" | "abort" | "new_session";
+  text?: string;
+  issueNumber?: number;
+}
+
+export interface SandboxStatus {
+  state: "running" | "paused" | "stopped";
+}
+
+export interface SandboxProvider {
+  create(config: SandboxProviderConfig): Promise<{ id: string }>;
+  resume(id: string): Promise<void>;
+  pause(id: string): Promise<void>;
+  destroy(id: string): Promise<void>;
+  rpc(id: string, command: RpcCommand): Promise<string>;
+  status(id: string): Promise<SandboxStatus>;
+}
+
+// ---------------------------------------------------------------------------
+// Factory: auto-detect which provider to use
+// ---------------------------------------------------------------------------
+
+import { DirectRunnerProvider } from "./providers/direct-runner.js";
+import { DaytonaSandboxProvider } from "./providers/daytona.js";
+
+export function createSandboxProvider(options: Record<string, string> = {}): SandboxProvider {
+  const daytonaKey = options["DAYTONA_API_KEY"] ?? process.env["DAYTONA_API_KEY"];
+  const providerOverride = options["HARNESS_SANDBOX_PROVIDER"] ?? process.env["HARNESS_SANDBOX_PROVIDER"];
+
+  if (providerOverride === "direct") {
+    return new DirectRunnerProvider();
+  }
+
+  if (daytonaKey) {
+    return new DaytonaSandboxProvider({
+      apiKey: daytonaKey,
+      apiUrl: options["DAYTONA_API_URL"] ?? process.env["DAYTONA_API_URL"] ?? "https://app.daytona.io/api",
+      ghToken: options["GH_TOKEN"] ?? process.env["GH_TOKEN"] ?? "",
+      modelApiKey: options["MODEL_API_KEY"] ?? process.env["MODEL_API_KEY"],
+      modelRegion: options["MODEL_REGION"] ?? process.env["AWS_REGION"],
+      model: options["MODEL"] ?? process.env["MODEL"],
+    });
+  }
+
+  // Default: fall back to DirectRunnerProvider
+  return new DirectRunnerProvider();
+}

package/src/types.ts

@@ -0,0 +1,40 @@
+export interface StageConfig {
+  name: string;
+  role: string;
+  skill: string;
+  tools: string[];
+  gate: "none" | "pr-review" | "retry";
+  produces?: string;
+  branch_pattern?: string;
+  hooks?: Record<string, string>;
+  reads_only?: string[];
+  max_retries?: number;
+  trigger?: string;
+}
+
+export interface PipelineConfig {
+  stages: StageConfig[];
+  labels: Record<string, string>;
+}
+
+export interface WorkflowConfig {
+  pipeline: PipelineConfig;
+  sandbox: { default_profile: string; profiles: Record<string, string[]> };
+  agent: { max_concurrent_issues: number; cost_ceiling: number; stale_threshold_minutes: number };
+  validation: Record<string, string>;
+  prompts: Record<string, string>;
+}
+
+export interface OrchestrationContext {
+  issueNumber: number;
+  repo: string;
+  label: string;
+  workflowConfig: WorkflowConfig;
+  artifactsDir: string;
+}
+
+export interface OrchestrationResult {
+  stage: string;
+  action: "advanced" | "opened-pr" | "retried" | "escalated" | "no-artifact";
+  nextLabel?: string;
+}

package/src/workflow-reader.ts

@@ -0,0 +1,99 @@
+import { readFileSync } from "node:fs";
+import { parse } from "yaml";
+import type { WorkflowConfig } from "./types.js";
+
+export function readWorkflow(filePath: string): WorkflowConfig {
+  const content = readFileSync(filePath, "utf-8");
+  return parseWorkflow(content);
+}
+
+export function parseWorkflow(content: string): WorkflowConfig {
+  if (!content || content.trim().length === 0) {
+    throw new Error(
+      "WORKFLOW.md is empty. Expected YAML frontmatter between --- delimiters."
+    );
+  }
+
+  const frontmatter = extractFrontmatter(content);
+  const body = extractBody(content);
+  const config = parseYaml(frontmatter);
+  const prompts = extractPrompts(body);
+
+  return {
+    pipeline: config.pipeline as WorkflowConfig["pipeline"],
+    sandbox: config.sandbox as WorkflowConfig["sandbox"],
+    agent: config.agent as WorkflowConfig["agent"],
+    validation: (config.validation ?? {}) as WorkflowConfig["validation"],
+    prompts,
+  };
+}
+
+function extractFrontmatter(content: string): string {
+  const trimmed = content.trimStart();
+  if (!trimmed.startsWith("---")) {
+    throw new Error(
+      "WORKFLOW.md missing frontmatter. Expected file to start with --- delimiters."
+    );
+  }
+
+  const afterOpening = trimmed.slice(3);
+  const closingIndex = afterOpening.indexOf("\n---");
+  if (closingIndex === -1) {
+    throw new Error(
+      "WORKFLOW.md missing closing --- delimiter for frontmatter."
+    );
+  }
+
+  return afterOpening.slice(0, closingIndex);
+}
+
+function extractBody(content: string): string {
+  const trimmed = content.trimStart();
+  const afterOpening = trimmed.slice(3);
+  const closingIndex = afterOpening.indexOf("\n---");
+  if (closingIndex === -1) {
+    return "";
+  }
+
+  return afterOpening.slice(closingIndex + 4);
+}
+
+function parseYaml(frontmatter: string): Record<string, unknown> {
+  try {
+    const parsed = parse(frontmatter);
+    if (!parsed || typeof parsed !== "object") {
+      throw new Error(
+        "WORKFLOW.md frontmatter is not a valid YAML object."
+      );
+    }
+    return parsed as Record<string, unknown>;
+  } catch (err) {
+    if (err instanceof Error && err.message.startsWith("WORKFLOW.md")) {
+      throw err;
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`WORKFLOW.md contains malformed YAML: ${message}`);
+  }
+}
+
+function extractPrompts(body: string): Record<string, string> {
+  const prompts: Record<string, string> = {};
+
+  const sections = body.split(/^### /m);
+
+  for (const section of sections) {
+    if (!section.trim()) continue;
+
+    const newlineIndex = section.indexOf("\n");
+    if (newlineIndex === -1) continue;
+
+    const name = section.slice(0, newlineIndex).trim();
+    const template = section.slice(newlineIndex + 1).trimEnd();
+
+    if (name && template.trim()) {
+      prompts[name] = template.trimStart();
+    }
+  }
+
+  return prompts;
+}