task-while 0.0.1

package/src/commands/batch.ts

@@ -0,0 +1,266 @@
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+
+import Ajv from 'ajv'
+import * as fsExtra from 'fs-extra'
+import { z } from 'zod'
+
+import { loadBatchConfig, type BatchConfig } from '../batch/config'
+import { discoverBatchFiles } from '../batch/discovery'
+import {
+  createBatchStructuredOutputProvider,
+  type BatchStructuredOutputProvider,
+} from '../batch/provider'
+import { parseWithSchema, uniqueStringArray } from '../schema/shared'
+import { writeJsonAtomic } from '../utils/fs'
+
+const batchStateSchema = z
+  .object({
+    failed: uniqueStringArray('failed'),
+    inProgress: uniqueStringArray('inProgress'),
+    pending: uniqueStringArray('pending'),
+  })
+  .strict()
+
+const batchResultsSchema = z.custom<Record<string, unknown>>(
+  (value) =>
+    typeof value === 'object' && value !== null && !Array.isArray(value),
+  {
+    message: 'results must be an object',
+  },
+)
+
+export interface BatchState {
+  failed: string[]
+  inProgress: string[]
+  pending: string[]
+}
+
+export interface RunBatchCommandInput {
+  configPath: string
+  cwd?: string
+  verbose?: boolean
+}
+
+export interface RunBatchCommandResult {
+  config: BatchConfig
+  failedFiles: string[]
+  processedFiles: string[]
+  results: Record<string, unknown>
+  state: BatchState
+}
+
+function createEmptyState(): BatchState {
+  return {
+    failed: [],
+    inProgress: [],
+    pending: [],
+  }
+}
+
+function unique(items: string[]) {
+  return [...new Set(items)]
+}
+
+async function readJsonFileIfExists(filePath: string) {
+  const exists = await fsExtra.pathExists(filePath)
+  if (!exists) {
+    return null
+  }
+  const raw = await readFile(filePath, 'utf8')
+  const value: unknown = JSON.parse(raw)
+  return value
+}
+
+async function loadBatchState(filePath: string) {
+  const value = await readJsonFileIfExists(filePath)
+  if (value === null) {
+    return createEmptyState()
+  }
+  return parseWithSchema(batchStateSchema, value)
+}
+
+async function loadBatchResults(filePath: string) {
+  const value = await readJsonFileIfExists(filePath)
+  if (value === null) {
+    return {}
+  }
+  return parseWithSchema(batchResultsSchema, value)
+}
+
+function mergeBatchState(input: {
+  discoveredFiles: string[]
+  results: Record<string, unknown>
+  state: BatchState
+}): BatchState {
+  const discovered = new Set(input.discoveredFiles)
+  const completed = new Set(Object.keys(input.results))
+  const failed = unique(input.state.failed).filter(
+    (filePath) => discovered.has(filePath) && !completed.has(filePath),
+  )
+  const failedSet = new Set(failed)
+  const pending = unique([
+    ...input.state.inProgress,
+    ...input.state.pending,
+  ]).filter(
+    (filePath) =>
+      discovered.has(filePath) &&
+      !completed.has(filePath) &&
+      !failedSet.has(filePath),
+  )
+  const pendingSet = new Set(pending)
+
+  for (const filePath of input.discoveredFiles) {
+    if (
+      completed.has(filePath) ||
+      failedSet.has(filePath) ||
+      pendingSet.has(filePath)
+    ) {
+      continue
+    }
+    pending.push(filePath)
+    pendingSet.add(filePath)
+  }
+
+  return {
+    failed,
+    inProgress: [],
+    pending,
+  }
+}
+
+function removeFile(items: string[], filePath: string) {
+  return items.filter((item) => item !== filePath)
+}
+
+function writeBatchFailure(filePath: string, error: unknown) {
+  process.stderr.write(
+    `[batch] failed ${filePath}: ${
+      error instanceof Error ? error.message : String(error)
+    }\n`,
+  )
+}
+
+async function recycleFailedFiles(
+  statePath: string,
+  state: BatchState,
+): Promise<BatchState> {
+  if (state.pending.length !== 0 || state.failed.length === 0) {
+    return state
+  }
+
+  const nextState: BatchState = {
+    failed: [],
+    inProgress: [],
+    pending: [...state.failed],
+  }
+  await writeJsonAtomic(statePath, nextState)
+  return nextState
+}
+
+function createProvider(config: BatchConfig): BatchStructuredOutputProvider {
+  if (config.provider === 'codex') {
+    return createBatchStructuredOutputProvider({
+      provider: 'codex',
+      ...(config.effort ? { effort: config.effort } : {}),
+      ...(config.model ? { model: config.model } : {}),
+      workspaceRoot: config.configDir,
+    })
+  }
+
+  return createBatchStructuredOutputProvider({
+    provider: 'claude',
+    ...(config.effort ? { effort: config.effort } : {}),
+    ...(config.model ? { model: config.model } : {}),
+    workspaceRoot: config.configDir,
+  })
+}
+
+export async function runBatchCommand(
+  input: RunBatchCommandInput,
+): Promise<RunBatchCommandResult> {
+  const cwd = input.cwd ?? process.cwd()
+  const config = await loadBatchConfig({
+    configPath: input.configPath,
+    cwd,
+  })
+
+  const statePath = path.join(config.configDir, 'state.json')
+  const resultsPath = path.join(config.configDir, 'results.json')
+  const excludedFiles = new Set([config.configPath, statePath, resultsPath])
+  const discoveredFiles = await discoverBatchFiles({
+    baseDir: config.configDir,
+    excludedFiles,
+    patterns: config.glob,
+  })
+  const results = await loadBatchResults(resultsPath)
+  let state: BatchState = mergeBatchState({
+    discoveredFiles,
+    results,
+    state: await loadBatchState(statePath),
+  })
+  await writeJsonAtomic(statePath, state)
+  await writeJsonAtomic(resultsPath, results)
+  const ajv = new Ajv({
+    allErrors: true,
+    strict: false,
+  })
+  const validateOutput = ajv.compile(config.schema)
+  const processedFiles: string[] = []
+  let provider: BatchStructuredOutputProvider | null = null
+
+  while (state.pending.length !== 0 || state.failed.length !== 0) {
+    if (state.pending.length === 0) {
+      state = await recycleFailedFiles(statePath, state)
+      continue
+    }
+    const filePath = state.pending[0]!
+    state = {
+      ...state,
+      inProgress: unique([...state.inProgress, filePath]),
+      pending: state.pending.slice(1),
+    }
+    await writeJsonAtomic(statePath, state)
+
+    try {
+      provider ??= createProvider(config)
+      const absoluteFilePath = path.join(config.configDir, filePath)
+      const content = await readFile(absoluteFilePath, 'utf8')
+      const output = await provider.runFile({
+        content,
+        filePath,
+        outputSchema: config.schema,
+        prompt: config.prompt,
+      })
+      if (!validateOutput(output)) {
+        throw new Error(ajv.errorsText(validateOutput.errors))
+      }
+      results[filePath] = output
+      await writeJsonAtomic(resultsPath, results)
+      state = {
+        ...state,
+        inProgress: removeFile(state.inProgress, filePath),
+      }
+      await writeJsonAtomic(statePath, state)
+      processedFiles.push(filePath)
+    } catch (error) {
+      if (input.verbose) {
+        writeBatchFailure(filePath, error)
+      }
+      state = {
+        failed: unique([...state.failed, filePath]),
+        inProgress: removeFile(state.inProgress, filePath),
+        pending: state.pending,
+      }
+      await writeJsonAtomic(statePath, state)
+    }
+  }
+
+  return {
+    config,
+    failedFiles: state.failed,
+    processedFiles,
+    results,
+    state,
+  }
+}

package/src/commands/run.ts

@@ -0,0 +1,270 @@
+import {
+  createClaudeProvider,
+  type ClaudeAgentEvent,
+  type ClaudeAgentEventHandler,
+} from '../agents/claude'
+import {
+  createCodexProvider,
+  type CodexThreadEvent,
+  type CodexThreadEventHandler,
+} from '../agents/codex'
+import { providerOptionsEqual } from '../agents/provider-options'
+import { runWorkflow, type WorkflowRunResult } from '../core/orchestrator'
+import { buildTaskTopology } from '../core/task-topology'
+import { createOrchestratorRuntime } from '../runtime/fs-runtime'
+import { openTaskSource } from '../task-sources/registry'
+import {
+  loadWorkflowConfig,
+  type WorkflowConfig,
+  type WorkflowProvider,
+  type WorkflowRoleConfig,
+} from '../workflow/config'
+import {
+  createDirectWorkflowPreset,
+  createPullRequestWorkflowPreset,
+  type WorkflowRuntime,
+} from '../workflow/preset'
+import { createCodexRemoteReviewerProvider } from '../workflow/remote-reviewer'
+
+import type {
+  ImplementerProvider,
+  RemoteReviewerProvider,
+  ReviewerProvider,
+  WorkflowRoleProviders,
+} from '../agents/types'
+import type { WorkspaceContext } from '../types'
+
+export interface RunCommandOptions {
+  config?: WorkflowConfig
+  untilTaskId?: string
+  verbose?: boolean
+}
+
+export type WorkflowExecutionRunner = () => Promise<WorkflowRunResult>
+
+export interface WorkflowExecution {
+  config: WorkflowConfig
+  execute: WorkflowExecutionRunner
+  workflow: WorkflowRuntime
+}
+
+export interface ResolveWorkflowRuntimeInput {
+  config: WorkflowConfig
+  context: WorkspaceContext
+  options: RunCommandOptions
+}
+
+export type ProviderResolver = (
+  role: WorkflowRoleConfig,
+) => ImplementerProvider & ReviewerProvider
+
+export type RemoteReviewerResolver = (
+  providerName: WorkflowProvider,
+) => RemoteReviewerProvider
+
+function writeCodexEvent(event: CodexThreadEvent) {
+  const itemType =
+    event.type === 'item.completed' ||
+    event.type === 'item.started' ||
+    event.type === 'item.updated'
+      ? event.item.type
+      : null
+  process.stderr.write(
+    `[codex] ${event.type}${itemType ? ` ${itemType}` : ''}\n`,
+  )
+  if (
+    event.type === 'item.completed' &&
+    event.item.type === 'agent_message' &&
+    event.item.text?.trim()
+  ) {
+    process.stderr.write(`[codex] message ${event.item.text.trim()}\n`)
+  }
+  if (event.type === 'error') {
+    process.stderr.write(`[codex] error ${event.message}\n`)
+  }
+  if (event.type === 'turn.failed') {
+    process.stderr.write(`[codex] error ${event.error.message}\n`)
+  }
+}
+
+function createCodexEventHandler(
+  verbose: boolean | undefined,
+): CodexThreadEventHandler | undefined {
+  if (!verbose) {
+    return undefined
+  }
+  return writeCodexEvent
+}
+
+function writeClaudeEvent(event: ClaudeAgentEvent) {
+  const detail = event.type === 'text' ? ` ${event.delta}` : ''
+  process.stderr.write(`[claude] ${event.type}${detail}\n`)
+}
+
+function createClaudeEventHandler(
+  verbose: boolean | undefined,
+): ClaudeAgentEventHandler | undefined {
+  if (!verbose) {
+    return undefined
+  }
+  return writeClaudeEvent
+}
+
+function createProviderResolver(
+  context: WorkspaceContext,
+  verbose: boolean | undefined,
+): ProviderResolver {
+  const cache = new Map<
+    WorkflowProvider,
+    ImplementerProvider & ReviewerProvider
+  >()
+  return (role: WorkflowRoleConfig) => {
+    const cached = cache.get(role.provider)
+    if (cached) {
+      return cached
+    }
+    let provider: ImplementerProvider & ReviewerProvider
+    if (role.provider === 'claude') {
+      const onEvent = createClaudeEventHandler(verbose)
+      provider = createClaudeProvider({
+        ...(role.effort ? { effort: role.effort } : {}),
+        ...(role.model ? { model: role.model } : {}),
+        workspaceRoot: context.workspaceRoot,
+        ...(onEvent ? { onEvent } : {}),
+      })
+    } else {
+      const onEvent = createCodexEventHandler(verbose)
+      provider = createCodexProvider({
+        ...(role.effort ? { effort: role.effort } : {}),
+        ...(role.model ? { model: role.model } : {}),
+        workspaceRoot: context.workspaceRoot,
+        ...(onEvent ? { onEvent } : {}),
+      })
+    }
+    cache.set(role.provider, provider)
+    return provider
+  }
+}
+
+function createRemoteReviewerResolver(): RemoteReviewerResolver {
+  const cache = new Map<WorkflowProvider, RemoteReviewerProvider>()
+  return (providerName: WorkflowProvider) => {
+    const cached = cache.get(providerName)
+    if (cached) {
+      return cached
+    }
+    if (providerName === 'claude') {
+      throw new Error(
+        'claude remote reviewer is not implemented in pull-request mode',
+      )
+    }
+    const provider = createCodexRemoteReviewerProvider()
+    cache.set(providerName, provider)
+    return provider
+  }
+}
+
+function resolveWorkflowRuntime(
+  input: ResolveWorkflowRuntimeInput,
+): WorkflowRuntime {
+  const resolveProvider = createProviderResolver(
+    input.context,
+    input.options.verbose,
+  )
+  const implementerRole = input.config.workflow.roles.implementer
+  const reviewerRole = input.config.workflow.roles.reviewer
+
+  if (input.config.workflow.mode === 'pull-request') {
+    const resolveRemoteReviewer = createRemoteReviewerResolver()
+    const reviewer = resolveRemoteReviewer(reviewerRole.provider)
+    const implementer = resolveProvider(implementerRole)
+    const roles: WorkflowRoleProviders = {
+      implementer,
+      reviewer,
+    }
+
+    return {
+      roles,
+      preset: createPullRequestWorkflowPreset({
+        reviewer,
+      }),
+    }
+  }
+
+  if (
+    implementerRole.provider === reviewerRole.provider &&
+    !providerOptionsEqual(implementerRole, reviewerRole)
+  ) {
+    throw new Error(
+      `direct workflow roles implementer and reviewer must use matching model and effort when sharing provider ${implementerRole.provider}`,
+    )
+  }
+
+  const implementer = resolveProvider(implementerRole)
+  const reviewer = resolveProvider(reviewerRole)
+  const roles: WorkflowRoleProviders = {
+    implementer,
+    reviewer,
+  }
+
+  return {
+    roles,
+    preset: createDirectWorkflowPreset({
+      reviewer,
+    }),
+  }
+}
+
+export async function loadWorkflowExecution(
+  context: WorkspaceContext,
+  options: RunCommandOptions = {},
+): Promise<WorkflowExecution> {
+  const config =
+    options.config ?? (await loadWorkflowConfig(context.workspaceRoot))
+  const workflow = resolveWorkflowRuntime({
+    config,
+    context,
+    options,
+  })
+  const taskSource = await openTaskSource(config.task.source, {
+    featureDir: context.featureDir,
+    featureId: context.featureId,
+    workspaceRoot: context.workspaceRoot,
+  })
+  const runtime = createOrchestratorRuntime({
+    featureDir: context.featureDir,
+    taskSource,
+    workspaceRoot: context.workspaceRoot,
+  })
+  await runtime.git.requireCleanWorktree()
+  const graph = buildTaskTopology(
+    taskSource,
+    context.featureId,
+    config.task.maxIterations,
+  )
+  const untilTaskHandle = options.untilTaskId
+    ? taskSource.resolveTaskSelector(options.untilTaskId)
+    : undefined
+  const workflowInput = {
+    graph,
+    runtime,
+    workflow,
+    ...(untilTaskHandle ? { untilTaskHandle } : {}),
+  }
+
+  return {
+    config,
+    workflow,
+    async execute() {
+      return runWorkflow(workflowInput)
+    },
+  }
+}
+
+export async function runCommand(
+  context: WorkspaceContext,
+  options: RunCommandOptions = {},
+) {
+  const execution = await loadWorkflowExecution(context, options)
+  return execution.execute()
+}

package/src/core/engine-helpers.ts

@@ -0,0 +1,114 @@
+import type {
+  PendingTaskState,
+  ReviewFinding,
+  ReviewOutput,
+  ReviewVerdict,
+  TaskGraph,
+  TaskState,
+  TaskTopologyEntry,
+  WorkflowState,
+} from '../types'
+
+export function cloneState(state: WorkflowState): WorkflowState {
+  return structuredClone(state)
+}
+
+export function createBaseTaskState(): PendingTaskState {
+  return {
+    attempt: 0,
+    generation: 1,
+    invalidatedBy: null,
+    lastFindings: [],
+    status: 'pending',
+  }
+}
+
+export function getTask(
+  graph: TaskGraph,
+  taskHandle: string,
+): TaskTopologyEntry {
+  const task = graph.tasks.find((item) => item.handle === taskHandle)
+  if (!task) {
+    throw new Error(`Unknown task: ${taskHandle}`)
+  }
+  return task
+}
+
+export function getTaskState(
+  state: WorkflowState,
+  taskHandle: string,
+): TaskState {
+  const taskState = state.tasks[taskHandle]
+  if (!taskState) {
+    throw new Error(`Missing state for task ${taskHandle}`)
+  }
+  return taskState
+}
+
+export function canStartTask(
+  graph: TaskGraph,
+  state: WorkflowState,
+  taskHandle: string,
+) {
+  const task = getTask(graph, taskHandle)
+  return task.dependsOn.every(
+    (dependency) => state.tasks[dependency]?.status === 'done',
+  )
+}
+
+export function getMaxIterations(graph: TaskGraph) {
+  return graph.maxIterations
+}
+
+export function withReviewMetadata(
+  taskState: TaskState,
+  input: WithReviewMetadataInput,
+) {
+  const next = {
+    attempt: taskState.attempt,
+    generation: taskState.generation,
+    invalidatedBy: taskState.invalidatedBy,
+    lastFindings: taskState.lastFindings,
+    ...(taskState.lastReviewVerdict
+      ? { lastReviewVerdict: taskState.lastReviewVerdict }
+      : {}),
+  }
+  if (input.findings) {
+    next.lastFindings = input.findings
+  }
+  if (input.reviewVerdict) {
+    next.lastReviewVerdict = input.reviewVerdict
+  }
+  return next
+}
+
+export interface WithReviewMetadataInput {
+  findings?: ReviewFinding[]
+  reviewVerdict?: ReviewVerdict
+}
+
+export interface ZeroGateInput {
+  review: ReviewOutput
+}
+
+export function shouldPassZeroGate(input: ZeroGateInput) {
+  return (
+    input.review.verdict === 'pass' &&
+    input.review.findings.length === 0 &&
+    input.review.acceptanceChecks.every((check) => check.status === 'pass')
+  )
+}
+
+export function collectDescendants(
+  graph: TaskGraph,
+  taskHandle: string,
+  seen = new Set<string>(),
+) {
+  for (const task of graph.tasks) {
+    if (task.dependsOn.includes(taskHandle) && !seen.has(task.handle)) {
+      seen.add(task.handle)
+      collectDescendants(graph, task.handle, seen)
+    }
+  }
+  return seen
+}