Harness

export type Harness = {
  run(task: HarnessTask, ctx: HarnessContext): Promise<HarnessResult>;
};

export type HarnessTask =
  | PlanTask
  | OrchestrateTask
  | ExecuteStepTask
  | FixStepTask;

export type PlanTask = {
  readonly kind: "plan";
  readonly workflowSnapshot: WorkflowDefinitionSnapshot;
  readonly input: unknown;
  readonly outerLoopContext?: OuterLoopContext;
};

export type OrchestrateTask = {
  readonly kind: "orchestrate";
  readonly available: readonly WorkflowDefinitionSnapshot[];
  readonly input: unknown;
};

export type ExecuteStepTask = {
  readonly kind: "execute_step";
  readonly step: LwirStep;
  readonly stepInput: unknown;
  readonly stepContext: { stepPath: string; visitIndex: number };
};

export type FixStepTask = {
  readonly kind: "fix_step";
  readonly step: LwirStep;
  readonly stepInput: unknown;
  readonly originalAttemptError: ErrorEnvelope;
  readonly priorFixAttempts: number;
};

export type HarnessResult =
  | { readonly kind: "plan"; readonly lwir: unknown }
  | { readonly kind: "orchestrate"; readonly output: unknown }
  | { readonly kind: "execute_step"; readonly output: unknown; readonly artifactRefs: readonly ArtifactRef[] }
  | { readonly kind: "fix_step"; readonly output: unknown; readonly fixedSource: string; readonly attempts: number }
  | { readonly kind: "delegate_to_default" };

export type HarnessContext = {
  readonly scope: HarnessScope;
  readonly model: ResolvedModel;
  readonly system?: string;
  readonly tools: ToolSet;
  readonly memoryMounts: readonly MemoryMount[];
  readonly scratchMounts: readonly ScratchMount[];
  readonly skills: readonly SkillDescriptor[];
  readonly mounts: readonly HarnessRuntimeMount[];
  readonly bashCapabilities?: WorkflowBashCapabilities;
  readonly durability: WorkflowHarnessDurabilitySink;
  readonly trace?: WorkflowHarnessTraceSink;
  readonly abortSignal: AbortSignal;
  readonly bash?: BashTool;
  readonly recorder?: HarnessEventRecorder;
};

export type HarnessScope = {
  readonly runId: RunId;
  readonly logDir: string;
  readonly role: HarnessRole;
  readonly parentRunId?: RunId;
};

export type HarnessRole =
  | "planner"
  | "orchestrator"
  | "worker.ai-generate"
  | "worker.code-run"
  | "worker.tool-call"
  | "fixer";

type BashTool = {
  execute(input: {
    cmd: string;
    cwd?: string;
    timeoutMs?: number;
  }): Promise<{
    stdout: string;
    stderr: string;
    exitCode: number;
  }>;
};

defineWorkflow({
  // ...
  bash: {
    network: {
      allow: ["https://api.example.com/"],
      methods: ["GET", "HEAD"],
      denyPrivateRanges: true,
    },
  },
});

export const workflowHarness: Harness = {
  async run(task, ctx) {
    switch (task.kind) {
      case "plan":
        return runPlanTask(task, ctx);

      case "orchestrate":
        return runOrchestrateTask(task, ctx);

      case "execute_step":
        return runExecuteStepTask(task, ctx);

      case "fix_step":
        return runFixStepTask(task, ctx);
    }
  },
};

async function executeStep(task: ExecuteStepTask, ctx: HarnessContext): Promise<HarnessResult> {
  switch (task.step.uses) {
    case "ai.generate":
      return runAgentLoopForAiStep(task, ctx);

    case "code.run":
      return executeCodeRunStep(task, ctx);

    case "tool.call":
      return executeToolCallStep(task, ctx);

    case "decision":
      return executeDecisionStep(task, ctx);

    case "parallel":
      throw new Error("parallel orchestration is the runtime's job, not the harness's");
  }
}

1. ctx.system                           dev-supplied intent
2. Role addendum                        SDK-shipped per role
3. Skill frontmatter list               name + description of each skill (bodies via bash)
4. Memory + scratch mount descriptions  paths, modes, and purpose
5. Available tools                      description + input schema from ctx.tools

[ctx.system]
You orchestrate candidate-evaluation workflows. Plan once per shared context; spawn parallel runs.

[Role addendum]
You are the Orchestrator for a Little Workflow run. Your tools:
- plan_workflow(workflowId, input) -> workflowVersionId
- run_workflow(workflowVersionId, input) -> output
- start_workflow(workflowId, input) -> output
- bash(cmd) -> {stdout, stderr, exitCode}

[Skill frontmatter list]
Available skills (read via `cat .agents/skills/<name>/SKILL.md`):
- batch-fan-out: Patterns for parallel tool calling when processing many items.

[Memory + scratch mount descriptions]
Memory mounts (read with bash):
- /mnt/memory/pipeline/ (rw) — persistent notes for this pipeline.
- /mnt/memory/org/ (ro) — organization-wide knowledge.

Scratch mounts (ephemeral, this run only):
- /mnt/scratch/own/ (rw) — your working area.

[Available tools]
fetchCandidates: Fetch candidates from ATS by job id. Input: {jobId: string}.

type SessionStartedEvent = {
  type: "harness.session.started";
  payload: {
    runId: RunId;
    role: HarnessRole;
    task: { kind: HarnessTask["kind"] };
    manifest: OrchestratorManifest | PlannerManifest | WorkerManifest | FixerManifest;
    manifestHash: string;
    parentRunId?: RunId;
  };
};

type SessionCompletedEvent = {
  type: "harness.session.completed";
  payload: {
    runId: RunId;
    output?: unknown;
    // Token-only rollup. The harness cannot see the model registry — it lives in
    // little-workflow, which depends on this package — so cost is derived downstream
    // instead, and `costUsd` on a recorded usage payload is rejected by the recorder.
    usage: {
      inputTokens: number;
      outputTokens: number;
      cachedInputTokens: number;
      reasoningTokens: number;
    };
  };
};

type SessionFailedEvent = {
  type: "harness.session.failed";
  payload: { runId: RunId; error: ErrorEnvelope };
};

type ModelCalledEvent = {
  type: "harness.model.called";
  payload: {
    turn: number;
    promptHash: string;
    request: {
      model: string;
      messages: Message[];
      tools: ToolReference[];
    };
  };
};

type ModelRespondedEvent = {
  type: "harness.model.responded";
  payload: {
    turn: number;
    callId: string;
    stepPath?: string;                             // stamped by the runtime bridge
    model: { provider: string; modelId: string };  // pricing key; must ride the payload
    response: {
      text?: string;
      toolCalls?: ToolCallRequest[];
      usage: {
        inputTokens: number;
        outputTokens: number;
        cachedInputTokens?: number;                // subset of inputTokens
        reasoningTokens?: number;                  // subset of outputTokens
      };
    };
  };
};

type ToolCallStartedEvent = {
  type: "harness.tool_call.started";
  payload: {
    turn?: number;
    callId: string;
    caller: "model" | "code";
    toolName: string;
    args: unknown;
  };
};

type ToolCallSucceededEvent = {
  type: "harness.tool_call.succeeded";
  payload: {
    callId: string;
    caller: "model" | "code";
    toolName: string;
    args: unknown;
    callIndex?: number;
    result: unknown;
    scope?: Record<string, unknown>;
    durationMs?: number;
  };
};

type ToolCallFailedEvent = {
  type: "harness.tool_call.failed";
  payload: {
    callId: string;
    caller: "model" | "code";
    toolName: string;
    args: unknown;
    callIndex?: number;
    error: ErrorEnvelope;
    scope?: Record<string, unknown>;
    durationMs?: number;
  };
};

type ExecuteStepStartedEvent = {
  type: "harness.execute_step.started";
  payload: {
    runId: RunId;
    stepId: string;
    uses: "ai.generate" | "code.run" | "tool.call" | "decision" | "parallel";
    stepPath: string;
    visitIndex: number;
  };
};

type ExecuteStepSucceededEvent = {
  type: "harness.execute_step.succeeded";
  payload: {
    runId: RunId;
    stepId: string;
    uses: "ai.generate" | "code.run" | "tool.call" | "decision" | "parallel";
    stepPath: string;
    visitIndex: number;
    output: unknown;
  };
};

import type { Harness } from "@little-stack/workflow/internals";

export const cloudflareHarness: Harness = {
  async run(task, ctx) {
    if (task.kind === "execute_step") {
      // Delegate direct-execute steps to the default.
      return { kind: "delegate_to_default" };
    }

    const response = await fetch("https://my-harness.workers.dev/run", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        task,
        scope: ctx.scope,
        modelSlotId: ctx.model.slotId,
        system: ctx.system,
        toolsManifest: Object.fromEntries(
          Object.entries(ctx.tools).map(([k, t]) => [k, { description: t.description, inputSchema: t.inputSchema }])
        ),
      }),
    });
    return await response.json();
  },
};

async run(task, ctx) {
  if (task.kind === "execute_step" && task.step.uses === "code.run") {
    return { kind: "delegate_to_default" };
  }
  // ...
}