task-while 0.0.1 → 0.0.3

package/src/harness/kernel.ts

@@ -0,0 +1,226 @@
+import {
+  createInitialState,
+  TaskStatus,
+  type Artifact,
+  type TaskState,
+} from './state'
+import {
+  WorkflowNodeType,
+  type DomainResult,
+  type Transition,
+  type TransitionRule,
+  type TypedArtifactMap,
+  type WorkflowContext,
+  type WorkflowNode,
+  type WorkflowProgram,
+} from './workflow-program'
+
+import type { HarnessStore } from './store'
+
+export enum KernelResultKind {
+  Error = 'error',
+  GateFail = 'gate.fail',
+  GatePass = 'gate.pass',
+}
+
+export function retryBudgetReached(state: TaskState, maxIterations: number) {
+  return Math.max(0, ...Object.values(state.phaseIterations)) >= maxIterations
+}
+
+export function errorRetry(maxIterations: number) {
+  return (retryPhase: string): TransitionRule =>
+    (input) =>
+      retryBudgetReached(input.state, maxIterations)
+        ? { nextPhase: null, status: TaskStatus.Blocked }
+        : { nextPhase: retryPhase, status: TaskStatus.Running }
+}
+
+export interface KernelResult {
+  status: TaskStatus
+}
+
+export async function runKernel(input: {
+  config: Record<string, unknown>
+  program: WorkflowProgram
+  protocol: string
+  store: HarnessStore
+  subjectId: string
+}): Promise<KernelResult> {
+  const { config, program, protocol, store, subjectId } = input
+
+  let state =
+    (await store.loadState(protocol, subjectId)) ??
+    createInitialState(subjectId)
+
+  if (
+    state.status === TaskStatus.Done ||
+    state.status === TaskStatus.Blocked ||
+    state.status === TaskStatus.Replan
+  ) {
+    return { status: state.status }
+  }
+
+  const artifactCache = new Map<string, Artifact>()
+  for (const [kind, artifactId] of Object.entries(state.artifacts)) {
+    const artifact = await store.loadArtifact(protocol, subjectId, artifactId)
+    if (artifact) {
+      artifactCache.set(kind, artifact)
+    }
+  }
+
+  const artifacts: TypedArtifactMap = {
+    get<T>(kind: string) {
+      return artifactCache.get(kind) as Artifact<T> | undefined
+    },
+    has(kind: string) {
+      return artifactCache.has(kind)
+    },
+    set(artifact: Artifact) {
+      artifactCache.set(artifact.kind, artifact)
+    },
+  }
+
+  if (state.status === TaskStatus.Suspended) {
+    state = { ...state, status: TaskStatus.Running }
+    await store.saveState(protocol, subjectId, state)
+  }
+
+  let current: null | string = state.currentPhase ?? program.entry
+
+  while (current) {
+    const node: undefined | WorkflowNode = program.nodes[current]
+    if (!node) {
+      throw new Error(`unknown node: ${current}`)
+    }
+
+    if (node.type === WorkflowNodeType.Gate) {
+      const ctx: WorkflowContext = { artifacts, config, state, subjectId }
+      const passed: boolean = await node.test(ctx)
+      const nextPhase: string = passed ? node.then : node.otherwise
+
+      await store.appendTransition(protocol, subjectId, {
+        nextPhase,
+        phase: current,
+        status: state.status,
+        timestamp: new Date().toISOString(),
+        resultKind: passed
+          ? KernelResultKind.GatePass
+          : KernelResultKind.GateFail,
+      })
+
+      current = nextPhase
+      continue
+    }
+
+    if (node.type === WorkflowNodeType.Branch) {
+      const ctx: WorkflowContext = { artifacts, config, state, subjectId }
+      const decision = await node.decide(ctx)
+      const nextPhase: string | undefined = node.paths[decision]
+      if (!nextPhase) {
+        throw new Error(`branch "${current}" has no path for "${decision}"`)
+      }
+
+      await store.appendTransition(protocol, subjectId, {
+        nextPhase,
+        phase: current,
+        resultKind: `branch.${decision}`,
+        status: state.status,
+        timestamp: new Date().toISOString(),
+      })
+
+      current = nextPhase
+      continue
+    }
+
+    const phaseCount = (state.phaseIterations[current] ?? 0) + 1
+    state = {
+      ...state,
+      currentPhase: current,
+      iteration: phaseCount,
+      phaseIterations: { ...state.phaseIterations, [current]: phaseCount },
+      status: TaskStatus.Running,
+    }
+    await store.saveState(protocol, subjectId, state)
+
+    let actionResult: { artifact?: Artifact; result: DomainResult }
+    try {
+      const ctx: WorkflowContext = { artifacts, config, state, subjectId }
+      actionResult = await node.run(ctx)
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error)
+      state = { ...state, failureReason: reason }
+
+      if (program.transitions[current]?.[KernelResultKind.Error]) {
+        actionResult = { result: { kind: KernelResultKind.Error } }
+      } else {
+        state = { ...state, status: TaskStatus.Blocked }
+        await store.saveState(protocol, subjectId, state)
+        await store.appendTransition(protocol, subjectId, {
+          nextPhase: null,
+          phase: current,
+          resultKind: KernelResultKind.Error,
+          status: TaskStatus.Blocked,
+          timestamp: new Date().toISOString(),
+        })
+        return { status: TaskStatus.Blocked }
+      }
+    }
+
+    if (actionResult.artifact) {
+      await store.saveArtifact(protocol, subjectId, actionResult.artifact)
+      artifacts.set(actionResult.artifact)
+      state = {
+        ...state,
+        artifacts: {
+          ...state.artifacts,
+          [actionResult.artifact.kind]: actionResult.artifact.id,
+        },
+      }
+    }
+
+    const transitionTable = program.transitions[current]
+    if (!transitionTable) {
+      throw new Error(`no transition table for "${current}"`)
+    }
+
+    const rule: TransitionRule | undefined =
+      transitionTable[actionResult.result.kind]
+    if (!rule) {
+      throw new Error(
+        `no transition rule for "${current}" -> "${actionResult.result.kind}"`,
+      )
+    }
+
+    const transition: Transition =
+      typeof rule === 'function'
+        ? rule({ result: actionResult.result, state })
+        : rule
+
+    state = {
+      ...state,
+      currentPhase: transition.nextPhase,
+      status: transition.status,
+      completedAt:
+        transition.status === TaskStatus.Done
+          ? new Date().toISOString()
+          : state.completedAt,
+    }
+    await store.saveState(protocol, subjectId, state)
+
+    await store.appendTransition(protocol, subjectId, {
+      nextPhase: transition.nextPhase,
+      phase: current,
+      resultKind: actionResult.result.kind,
+      status: transition.status,
+      timestamp: new Date().toISOString(),
+    })
+
+    if (state.status !== TaskStatus.Running) {
+      return { status: state.status }
+    }
+
+    current = transition.nextPhase
+  }
+
+  return { status: state.status }
+}

package/src/harness/state.ts

@@ -0,0 +1,47 @@
+export enum TaskStatus {
+  Blocked = 'blocked',
+  Done = 'done',
+  Queued = 'queued',
+  Replan = 'replan',
+  Running = 'running',
+  Suspended = 'suspended',
+}
+
+export interface TaskState {
+  artifacts: Record<string, string>
+  completedAt: null | string
+  currentPhase: null | string
+  failureReason: null | string
+  iteration: number
+  phaseIterations: Record<string, number>
+  status: TaskStatus
+}
+
+export interface TransitionRecord {
+  nextPhase: null | string
+  phase: string
+  resultKind: string
+  status: TaskStatus
+  timestamp: string
+}
+
+export interface Artifact<TPayload = unknown> {
+  id: string
+  kind: string
+  payload: TPayload
+  subjectId: string
+  timestamp: string
+}
+
+export function createInitialState(subjectId: string): TaskState {
+  void subjectId
+  return {
+    artifacts: {},
+    completedAt: null,
+    currentPhase: null,
+    failureReason: null,
+    iteration: 0,
+    phaseIterations: {},
+    status: TaskStatus.Queued,
+  }
+}

package/src/harness/store.ts

@@ -0,0 +1,26 @@
+import type { Artifact, TaskState, TransitionRecord } from './state'
+
+export interface HarnessStore {
+  appendTransition: (
+    protocol: string,
+    subjectId: string,
+    record: TransitionRecord,
+  ) => Promise<void>
+  listArtifacts: (protocol: string, subjectId: string) => Promise<Artifact[]>
+  loadArtifact: (
+    protocol: string,
+    subjectId: string,
+    artifactId: string,
+  ) => Promise<Artifact | null>
+  loadState: (protocol: string, subjectId: string) => Promise<null | TaskState>
+  saveArtifact: (
+    protocol: string,
+    subjectId: string,
+    artifact: Artifact,
+  ) => Promise<void>
+  saveState: (
+    protocol: string,
+    subjectId: string,
+    state: TaskState,
+  ) => Promise<void>
+}

package/src/harness/workflow-builders.ts

@@ -0,0 +1,87 @@
+import {
+  WorkflowNodeType,
+  type ActionNode,
+  type ActionRunFn,
+  type BranchDecideFn,
+  type BranchNode,
+  type GateNode,
+  type GateTestFn,
+  type TransitionRule,
+  type WorkflowNode,
+  type WorkflowProgram,
+} from './workflow-program'
+
+export function action<TConfig = unknown>(
+  name: string,
+  overrides?: { run?: ActionRunFn<TConfig> },
+): ActionNode<TConfig> {
+  return {
+    name,
+    type: WorkflowNodeType.Action,
+    run:
+      overrides?.run ??
+      (async () => ({ result: { kind: `${name}.completed` } })),
+  }
+}
+
+export function gate<TConfig = unknown>(
+  name: string,
+  input: { otherwise: string; test: GateTestFn<TConfig>; then: string },
+): GateNode<TConfig> {
+  return {
+    name,
+    otherwise: input.otherwise,
+    test: input.test,
+    then: input.then,
+    type: WorkflowNodeType.Gate,
+  }
+}
+
+export function branch<TConfig = unknown>(
+  name: string,
+  input: { decide: BranchDecideFn<TConfig>; paths: Record<string, string> },
+): BranchNode<TConfig> {
+  return {
+    name,
+    decide: input.decide,
+    paths: input.paths,
+    type: WorkflowNodeType.Branch,
+  }
+}
+
+export function sequence<TConfig = unknown>(
+  nodes: WorkflowNode<TConfig>[],
+  transitions: Record<string, Record<string, TransitionRule>>,
+): WorkflowProgram<TConfig> {
+  const nodeMap: Record<string, WorkflowNode<TConfig>> = {}
+  for (const node of nodes) {
+    nodeMap[node.name] = node
+  }
+
+  const nodeNames = new Set(Object.keys(nodeMap))
+
+  for (const node of nodes) {
+    if (node.type === WorkflowNodeType.Action && !(node.name in transitions)) {
+      throw new Error(`missing transition table for action node "${node.name}"`)
+    }
+  }
+
+  for (const rules of Object.values(transitions)) {
+    for (const rule of Object.values(rules)) {
+      if (typeof rule === 'function') {
+        continue
+      }
+      if (rule.nextPhase !== null && !nodeNames.has(rule.nextPhase)) {
+        throw new Error(
+          `transition references unknown node "${rule.nextPhase}"`,
+        )
+      }
+    }
+  }
+
+  return {
+    entry: nodes[0]!.name,
+    nodes: nodeMap,
+    transitions,
+  }
+}

package/src/harness/workflow-program.ts

@@ -0,0 +1,86 @@
+import type { Artifact, TaskState, TaskStatus } from './state'
+
+export enum WorkflowNodeType {
+  Action = 'action',
+  Branch = 'branch',
+  Gate = 'gate',
+}
+
+export interface TypedArtifactMap {
+  get: <T = unknown>(kind: string) => Artifact<T> | undefined
+  has: (kind: string) => boolean
+  set: (artifact: Artifact) => void
+}
+
+export interface WorkflowContext<TConfig = unknown> {
+  artifacts: TypedArtifactMap
+  config: TConfig
+  state: TaskState
+  subjectId: string
+}
+
+export interface DomainResult<
+  TKind extends string = string,
+  TPayload = unknown,
+> {
+  kind: TKind
+  payload?: TPayload
+}
+
+export interface ActionResult {
+  artifact?: Artifact
+  result: DomainResult
+}
+
+export type ActionRunFn<TConfig = unknown> = (
+  ctx: WorkflowContext<TConfig>,
+) => Promise<ActionResult>
+
+export type GateTestFn<TConfig = unknown> = (
+  ctx: WorkflowContext<TConfig>,
+) => Promise<boolean>
+
+export type BranchDecideFn<TConfig = unknown> = (
+  ctx: WorkflowContext<TConfig>,
+) => Promise<string>
+
+export interface ActionNode<TConfig = unknown> {
+  name: string
+  run: ActionRunFn<TConfig>
+  type: WorkflowNodeType.Action
+}
+
+export interface GateNode<TConfig = unknown> {
+  name: string
+  otherwise: string
+  test: GateTestFn<TConfig>
+  then: string
+  type: WorkflowNodeType.Gate
+}
+
+export interface BranchNode<TConfig = unknown> {
+  decide: BranchDecideFn<TConfig>
+  name: string
+  paths: Record<string, string>
+  type: WorkflowNodeType.Branch
+}
+
+export type WorkflowNode<TConfig = unknown> =
+  | ActionNode<TConfig>
+  | BranchNode<TConfig>
+  | GateNode<TConfig>
+
+export interface Transition {
+  nextPhase: null | string
+  status: TaskStatus
+}
+
+export type TransitionRule =
+  | ((input: { result: DomainResult; state: TaskState }) => Transition)
+  | Transition
+
+export interface WorkflowProgram<TConfig = unknown> {
+  entry: string
+  nodes: Record<string, WorkflowNode<TConfig>>
+  transitions: Record<string, Record<string, TransitionRule>>
+}

package/src/ports/agent.ts

@@ -0,0 +1,17 @@
+export interface AgentInvocation {
+  outputSchema: Record<string, unknown>
+  prompt: string
+  role: string
+}
+
+export interface AgentPort {
+  execute: (invocation: AgentInvocation) => Promise<unknown>
+  name: string
+}
+
+export function createRoleInvocation(
+  role: string,
+  input: Omit<AgentInvocation, 'role'>,
+): AgentInvocation {
+  return { ...input, role }
+}

package/src/ports/code-host.ts

@@ -0,0 +1,23 @@
+import type { PullRequestSnapshot } from '../core/runtime'
+
+export interface CodeHostPort {
+  createPullRequest: (input: {
+    baseBranch: string
+    body: string
+    headBranch: string
+    title: string
+  }) => Promise<{ number: number; url: string }>
+  findMergedPullRequestByHeadBranch: (input: {
+    headBranch: string
+  }) => Promise<null | { mergeCommitSha: string; number: number }>
+  findOpenPullRequestByHeadBranch: (input: {
+    headBranch: string
+  }) => Promise<null | { number: number }>
+  getPullRequestSnapshot: (input: {
+    pullRequestNumber: number
+  }) => Promise<PullRequestSnapshot>
+  squashMergePullRequest: (input: {
+    pullRequestNumber: number
+    subject: string
+  }) => Promise<{ commitSha: string }>
+}

package/src/programs/batch.ts

@@ -0,0 +1,139 @@
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+
+import { TaskStatus, type Artifact } from '../harness/state'
+import { action, sequence } from '../harness/workflow-builders'
+import { writeJsonAtomic } from '../utils/fs'
+
+import type { BatchStructuredOutputProvider } from '../batch/provider'
+import type { WorkflowProgram } from '../harness/workflow-program'
+
+export enum BatchPhase {
+  Persist = 'persist',
+  Prepare = 'prepare',
+  Process = 'process',
+}
+
+export enum BatchResult {
+  PersistCompleted = 'persist.completed',
+  PrepareCompleted = 'prepare.completed',
+  ProcessCompleted = 'process.completed',
+  ProcessRetryRequested = 'process.retry_requested',
+}
+
+export enum BatchArtifactKind {
+  PersistResult = 'persist_result',
+  PrepareResult = 'prepare_result',
+  ProcessResult = 'process_result',
+}
+
+export function createBatchProgram(deps: {
+  configDir: string
+  maxRetries: number
+  outputSchema: Record<string, unknown>
+  prompt: string
+  provider: BatchStructuredOutputProvider
+  results: Record<string, unknown>
+  resultsPath: string
+  validateOutput: (value: unknown) => void
+}): WorkflowProgram {
+  return sequence(
+    [
+      action(BatchPhase.Prepare, {
+        async run(ctx) {
+          const content = await readFile(
+            path.join(deps.configDir, ctx.subjectId),
+            'utf8',
+          )
+          const artifact: Artifact<{ content: string; filePath: string }> = {
+            id: `${encodeURIComponent(ctx.subjectId)}:${BatchArtifactKind.PrepareResult}`,
+            kind: BatchArtifactKind.PrepareResult,
+            payload: { content, filePath: ctx.subjectId },
+            subjectId: ctx.subjectId,
+            timestamp: new Date().toISOString(),
+          }
+          return {
+            artifact,
+            result: { kind: BatchResult.PrepareCompleted },
+          }
+        },
+      }),
+      action(BatchPhase.Process, {
+        async run(ctx) {
+          const prepareArtifact = ctx.artifacts.get<{
+            content: string
+            filePath: string
+          }>(BatchArtifactKind.PrepareResult)
+          try {
+            const output = await deps.provider.runFile({
+              content: prepareArtifact!.payload.content,
+              filePath: prepareArtifact!.payload.filePath,
+              outputSchema: deps.outputSchema,
+              prompt: deps.prompt,
+            })
+            deps.validateOutput(output)
+            const artifact: Artifact<{ output: unknown }> = {
+              id: `${encodeURIComponent(ctx.subjectId)}:${BatchArtifactKind.ProcessResult}`,
+              kind: BatchArtifactKind.ProcessResult,
+              payload: { output },
+              subjectId: ctx.subjectId,
+              timestamp: new Date().toISOString(),
+            }
+            return {
+              artifact,
+              result: { kind: BatchResult.ProcessCompleted },
+            }
+          } catch {
+            return {
+              result: { kind: BatchResult.ProcessRetryRequested },
+            }
+          }
+        },
+      }),
+      action(BatchPhase.Persist, {
+        async run(ctx) {
+          const processArtifact = ctx.artifacts.get<{ output: unknown }>(
+            BatchArtifactKind.ProcessResult,
+          )
+          deps.results[ctx.subjectId] = processArtifact!.payload.output
+          await writeJsonAtomic(deps.resultsPath, deps.results)
+          const artifact: Artifact<{ filePath: string; persisted: boolean }> = {
+            id: `${encodeURIComponent(ctx.subjectId)}:${BatchArtifactKind.PersistResult}`,
+            kind: BatchArtifactKind.PersistResult,
+            payload: { filePath: ctx.subjectId, persisted: true },
+            subjectId: ctx.subjectId,
+            timestamp: new Date().toISOString(),
+          }
+          return {
+            artifact,
+            result: { kind: BatchResult.PersistCompleted },
+          }
+        },
+      }),
+    ],
+    {
+      [BatchPhase.Persist]: {
+        [BatchResult.PersistCompleted]: {
+          nextPhase: null,
+          status: TaskStatus.Done,
+        },
+      },
+      [BatchPhase.Prepare]: {
+        [BatchResult.PrepareCompleted]: {
+          nextPhase: BatchPhase.Process,
+          status: TaskStatus.Running,
+        },
+      },
+      [BatchPhase.Process]: {
+        [BatchResult.ProcessCompleted]: {
+          nextPhase: BatchPhase.Persist,
+          status: TaskStatus.Running,
+        },
+        [BatchResult.ProcessRetryRequested]: (input) =>
+          input.state.iteration >= deps.maxRetries
+            ? { nextPhase: null, status: TaskStatus.Blocked }
+            : { nextPhase: BatchPhase.Process, status: TaskStatus.Suspended },
+      },
+    },
+  )
+}