task-while 0.0.3 → 0.0.5

package/README.md

@@ -40,7 +40,7 @@ pnpm exec task-while run
 
 ## Configuration
 
-`while.yaml` configures the `run` workflow only. When it is absent, the CLI runs `task.source: spec-kit`, `task.maxIterations: 5`, and `workflow.mode: direct` with `codex` for both roles. Each workflow role accepts provider-specific `model` and `effort`.
+`while.yaml` configures the `run` workflow only. When it is absent, the CLI runs `task.source: spec-kit`, `task.maxIterations: 5`, and `workflow.mode: direct` with `codex` for both roles. Each workflow role accepts provider-specific `model`, `effort`, and optional `timeout` in milliseconds.
 
 ```yaml
 task:
@@ -53,20 +53,23 @@ workflow:
     implementer:
       model: gpt-5-codex
       effort: high
+      timeout: 900000
     reviewer:
       model: gpt-5-codex
       effort: high
+      timeout: 900000
 ```
 
 Current status:
 
 - `workflow.roles.<role>.provider` accepts `codex` or `claude`; when omitted it defaults to `codex`, including roles that only set `model` and/or `effort`
+- `workflow.roles.<role>.timeout` is optional and sets a per-turn timeout in milliseconds for local agent runs; valid values are positive integers up to `2147483647`
 - `codex` `effort` accepts `minimal`, `low`, `medium`, `high`, or `xhigh`
 - `claude` `effort` accepts `low`, `medium`, `high`, or `max`
 - `workflow.mode: direct` requires `implementer` and `reviewer` to use identical `model` and `effort` when they share the same provider
 - `workflow.mode: direct` uses a local reviewer
 - `workflow.mode: pull-request` pushes a task branch, polls GitHub PR review from `chatgpt-codex-connector[bot]`, then squash-merges on approval
-- in `workflow.mode: pull-request`, reviewer `provider` still selects the remote reviewer, but any local reviewer `model` and `effort` values are ignored
+- in `workflow.mode: pull-request`, reviewer `provider` still selects the remote reviewer, but any local reviewer `model`, `effort`, and `timeout` values are ignored
 - `workflow.mode: pull-request` currently supports only `codex` as the remote reviewer provider
 - `task.maxIterations` uses the same configured limit for every task in the selected source session; run workflow retries share a single per-task budget across phases
 
@@ -127,12 +130,15 @@ cd /path/to/workspace
 pnpm exec task-while batch --config ./batch.yaml
 ```
 
+This repository also includes a repo-local skill at `skills/generate-batch-yaml/` for generating batch configs from natural-language requirements.
+
 Batch config example:
 
 ```yaml
 provider: claude
 model: claude-sonnet-4-6
 effort: max
+timeout: 300000
 glob:
   - 'src/**/*.{ts,tsx}'
 prompt: |
@@ -155,15 +161,16 @@ Batch behavior:
 - `glob` is optional and defaults to `**/*`
 - `glob` is resolved relative to the directory that contains `batch.yaml`
 - `provider`, `prompt`, and `schema` are required
-- `model` and `effort` are optional and are forwarded to the selected provider client
+- `model`, `effort`, and `timeout` are optional and are forwarded to the selected provider client
 - batch `provider` accepts `codex` or `claude`
 - batch `codex` `effort` accepts `minimal`, `low`, `medium`, `high`, or `xhigh`
 - batch `claude` `effort` accepts `low`, `medium`, `high`, or `max`
+- batch `timeout` is an optional per-file timeout in milliseconds; valid values are positive integers up to `2147483647`
 - each run scans files under the `batch.yaml` directory and filters them by `glob`
 - structured results are written beside the YAML file in `results.json`
 - internal harness state is written under `.while/harness/` beside the YAML file
 - result keys are relative to the directory that contains `batch.yaml`
-- `--verbose` streams direct provider details to `stderr` during batch execution, including Claude init/task/tool/result summaries and Codex thinking, commands, MCP tools, file updates, todo changes, messages, and final usage
+- `--verbose` streams batch-level progress and direct provider details to `stderr` during batch execution, including the current file, completion counts, Claude init/task/tool/result summaries, and Codex thinking, commands, MCP tools, file updates, todo changes, messages, and final usage
 - rerunning the command resumes unfinished work and skips files that already have accepted results
 - failed files are suspended and retried after all pending files are processed
 - file-level retries are limited by `maxRetries` (default 3); exhausted files are marked blocked

package/package.json

@@ -1,7 +1,6 @@
 {
   "name": "task-while",
-  "version": "0.0.3",
-  "packageManager": "pnpm@10.32.1",
+  "version": "0.0.5",
   "description": "Git-first task orchestrator for task-source workspaces",
   "author": "Zhang Yu",
   "license": "MIT",
@@ -32,23 +31,9 @@
   "engines": {
     "node": ">=24"
   },
-  "scripts": {
-    "dev": "tsx src/index.ts",
-    "format": "prettier . --write",
-    "format:check": "prettier . --check",
-    "lint": "eslint .",
-    "lint:fix": "eslint . --fix",
-    "smoke:codex": "tsx fixtures/smoke/codex-provider.ts",
-    "smoke:e2e:codex": "tsx fixtures/smoke/codex-e2e.ts",
-    "smoke:github-pr-snapshot": "tsx fixtures/smoke/github-pr-snapshot.ts",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "coverage": "vitest run --coverage"
-  },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.92",
-    "@openai/codex-sdk": "^0.118.0",
+    "@anthropic-ai/claude-agent-sdk": "^0.2.104",
+    "@openai/codex-sdk": "^0.120.0",
     "ajv": "^8.18.0",
     "arg": "^5.0.2",
     "execa": "^8.0.1",
@@ -68,5 +53,19 @@
     "prettier": "^3.8.1",
     "typescript": "^5.9.3",
     "vitest": "4.1.0"
+  },
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "format": "prettier . --write",
+    "format:check": "prettier . --check",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "smoke:codex": "tsx fixtures/smoke/codex-provider.ts",
+    "smoke:e2e:codex": "tsx fixtures/smoke/codex-e2e.ts",
+    "smoke:github-pr-snapshot": "tsx fixtures/smoke/github-pr-snapshot.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage"
   }
-}
+}

package/src/agents/claude.ts

@@ -6,6 +6,7 @@ import {
   validateImplementOutput,
   validateReviewOutput,
 } from '../schema/index'
+import { withAbortTimeout } from './timeout'
 
 import type { Options as ClaudeQueryOptions } from '@anthropic-ai/claude-agent-sdk'
 
@@ -278,34 +279,41 @@ export class ClaudeAgentClient
 
   public async invokeStructured<T>(input: ClaudeStructuredInput): Promise<T> {
     const { query } = await import('@anthropic-ai/claude-agent-sdk')
-    const queryOptions = {
-      allowDangerouslySkipPermissions: true,
-      cwd: this.options.workspaceRoot,
-      permissionMode: 'bypassPermissions',
-      outputFormat: {
-        schema: input.outputSchema,
-        type: 'json_schema',
-      },
-      ...(this.options.onEvent
-        ? {
-            agentProgressSummaries: true,
-            includePartialMessages: true,
-          }
-        : {
-            includePartialMessages: false,
-          }),
-      ...(this.options.model ? { model: this.options.model } : {}),
-      ...(this.options.effort ? { effort: this.options.effort } : {}),
-    } satisfies ClaudeQueryOptions
-
-    const messages = query({
-      options: queryOptions,
-      prompt: input.prompt,
-    })
+    return withAbortTimeout(
+      this.name,
+      this.options.timeout,
+      async (controller) => {
+        const queryOptions = {
+          allowDangerouslySkipPermissions: true,
+          cwd: this.options.workspaceRoot,
+          permissionMode: 'bypassPermissions',
+          outputFormat: {
+            schema: input.outputSchema,
+            type: 'json_schema',
+          },
+          ...(this.options.onEvent
+            ? {
+                agentProgressSummaries: true,
+                includePartialMessages: true,
+              }
+            : {
+                includePartialMessages: false,
+              }),
+          ...(this.options.model ? { model: this.options.model } : {}),
+          ...(this.options.effort ? { effort: this.options.effort } : {}),
+          ...(controller ? { abortController: controller } : {}),
+        } satisfies ClaudeQueryOptions
+
+        const messages = query({
+          options: queryOptions,
+          prompt: input.prompt,
+        })
 
-    return this.collectStructuredOutput(
-      messages as AsyncIterable<QueryMessage>,
-    ) as Promise<T>
+        return this.collectStructuredOutput(
+          messages as AsyncIterable<QueryMessage>,
+        ) as Promise<T>
+      },
+    )
   }
 
   public async review(input: ReviewAgentInput) {

package/src/agents/codex.ts

@@ -6,6 +6,7 @@ import {
   validateImplementOutput,
   validateReviewOutput,
 } from '../schema/index'
+import { withAbortTimeout } from './timeout'
 
 import type { CodexProviderOptions } from './provider-options'
 import type {
@@ -143,6 +144,7 @@ export interface CodexRunStreamedResult {
 
 export interface CodexThreadRunOptions {
   outputSchema: Record<string, unknown>
+  signal?: AbortSignal
 }
 
 export interface CodexThreadLike {
@@ -190,9 +192,11 @@ export class CodexAgentClient implements ImplementerProvider, ReviewerProvider {
   private async collectStreamedTurn<T>(
     thread: CodexThreadLike,
     input: CodexStructuredInput,
+    signal?: AbortSignal,
   ): Promise<T> {
     const streamedTurn = await thread.runStreamed!(input.prompt, {
       outputSchema: input.outputSchema,
+      ...(signal ? { signal } : {}),
     })
     let finalResponse = ''
 
@@ -259,23 +263,34 @@ export class CodexAgentClient implements ImplementerProvider, ReviewerProvider {
     const thread = client.startThread(startThreadOptions)
 
     if (this.options.onEvent && thread.runStreamed) {
-      return this.collectStreamedTurn<T>(thread, input)
-    }
-
-    const turn = await thread.run(input.prompt, {
-      outputSchema: input.outputSchema,
-    })
-    const response = turn.finalResponse.trim()
-    if (!response) {
-      throw new Error('Codex agent client returned empty finalResponse')
-    }
-    try {
-      return JSON.parse(response) as T
-    } catch (error) {
-      throw new Error('Codex agent client returned non-JSON finalResponse', {
-        cause: error,
-      })
+      return withAbortTimeout(this.name, this.options.timeout, (controller) =>
+        this.collectStreamedTurn<T>(thread, input, controller?.signal),
+      )
     }
+    return withAbortTimeout(
+      this.name,
+      this.options.timeout,
+      async (controller) => {
+        const turn = await thread.run(input.prompt, {
+          outputSchema: input.outputSchema,
+          ...(controller ? { signal: controller.signal } : {}),
+        })
+        const response = turn.finalResponse.trim()
+        if (!response) {
+          throw new Error('Codex agent client returned empty finalResponse')
+        }
+        try {
+          return JSON.parse(response) as T
+        } catch (error) {
+          throw new Error(
+            'Codex agent client returned non-JSON finalResponse',
+            {
+              cause: error,
+            },
+          )
+        }
+      },
+    )
   }
 
   public async review(input: ReviewAgentInput) {

package/src/agents/provider-options.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod'
 
 const modelSchema = z.string().trim().min(1)
+const timeoutSchema = z.number().int().positive().max(2_147_483_647)
 
 export const codexEffortSchema = z.enum([
   'minimal',
@@ -16,6 +17,7 @@ export const codexProviderOptionsSchema = z
   .object({
     effort: codexEffortSchema.optional(),
     model: modelSchema.optional(),
+    timeout: timeoutSchema.optional(),
   })
   .strict()
 
@@ -23,6 +25,7 @@ export const claudeProviderOptionsSchema = z
   .object({
     effort: claudeEffortSchema.optional(),
     model: modelSchema.optional(),
+    timeout: timeoutSchema.optional(),
   })
   .strict()
 
@@ -43,3 +46,17 @@ export function providerOptionsEqual(
     left.effort === right.effort
   )
 }
+
+export function providerOptionsCacheKey(options: {
+  effort?: string | undefined
+  model?: string | undefined
+  provider: 'claude' | 'codex'
+  timeout?: number | undefined
+}) {
+  return [
+    options.provider,
+    options.model ?? '',
+    options.effort ?? '',
+    String(options.timeout ?? ''),
+  ].join(':')
+}

package/src/agents/timeout.ts

@@ -0,0 +1,41 @@
+export class AgentTimeoutError extends Error {
+  public constructor(
+    public readonly provider: string,
+    public readonly timeout: number,
+    options?: ErrorOptions,
+  ) {
+    super(`${provider} agent timed out after ${timeout}ms`, options)
+  }
+}
+
+export async function withAbortTimeout<T>(
+  provider: string,
+  timeout: number | undefined,
+  run: (controller: AbortController | undefined) => Promise<T>,
+): Promise<T> {
+  if (!timeout) {
+    return run(undefined)
+  }
+
+  const controller = new AbortController()
+  const state = { timedOut: false }
+  const timer = setTimeout(() => {
+    state.timedOut = true
+    controller.abort()
+  }, timeout)
+
+  try {
+    const result = await run(controller)
+    if (state.timedOut) {
+      throw new AgentTimeoutError(provider, timeout)
+    }
+    return result
+  } catch (error) {
+    if (state.timedOut) {
+      throw new AgentTimeoutError(provider, timeout, { cause: error })
+    }
+    throw error
+  } finally {
+    clearTimeout(timer)
+  }
+}

package/src/batch/config.ts

@@ -97,6 +97,7 @@ export async function loadBatchConfig(
       provider: 'claude',
       ...(parsedConfig.model ? { model: parsedConfig.model } : {}),
       ...(parsedConfig.effort ? { effort: parsedConfig.effort } : {}),
+      ...(parsedConfig.timeout ? { timeout: parsedConfig.timeout } : {}),
     }
   }
 
@@ -105,5 +106,6 @@ export async function loadBatchConfig(
     provider: 'codex',
     ...(parsedConfig.model ? { model: parsedConfig.model } : {}),
     ...(parsedConfig.effort ? { effort: parsedConfig.effort } : {}),
+    ...(parsedConfig.timeout ? { timeout: parsedConfig.timeout } : {}),
   }
 }

package/src/batch/provider.ts

@@ -70,6 +70,7 @@ export function createBatchStructuredOutputProvider(
       new CodexAgentClient({
         ...(input.effort ? { effort: input.effort } : {}),
         ...(input.model ? { model: input.model } : {}),
+        ...(input.timeout ? { timeout: input.timeout } : {}),
         ...(onEvent ? { onEvent } : {}),
         workspaceRoot: input.workspaceRoot,
       }),
@@ -81,6 +82,7 @@ export function createBatchStructuredOutputProvider(
     new ClaudeAgentClient({
       ...(input.effort ? { effort: input.effort } : {}),
       ...(input.model ? { model: input.model } : {}),
+      ...(input.timeout ? { timeout: input.timeout } : {}),
       ...(onEvent ? { onEvent } : {}),
       workspaceRoot: input.workspaceRoot,
     }),

package/src/commands/batch.ts

@@ -42,6 +42,38 @@ export interface RunBatchCommandResult {
   resultsFilePath: string
 }
 
+function writeBatchVerboseLine(verbose: boolean | undefined, line: string) {
+  if (!verbose) {
+    return
+  }
+  process.stderr.write(`[batch] ${line}\n`)
+}
+
+function readSessionProgress(detail: unknown) {
+  if (typeof detail !== 'object' || detail === null) {
+    return null
+  }
+  const progress = (detail as { progress?: unknown }).progress
+  if (typeof progress !== 'object' || progress === null) {
+    return null
+  }
+
+  const blocked =
+    typeof (progress as { blocked?: unknown }).blocked === 'number'
+      ? (progress as { blocked: number }).blocked
+      : 0
+  const completed =
+    typeof (progress as { completed?: unknown }).completed === 'number'
+      ? (progress as { completed: number }).completed
+      : 0
+  const suspended =
+    typeof (progress as { suspended?: unknown }).suspended === 'number'
+      ? (progress as { suspended: number }).suspended
+      : 0
+
+  return { blocked, completed, suspended }
+}
+
 async function readJsonFileIfExists(filePath: string) {
   const exists = await fsExtra.pathExists(filePath)
   if (!exists) {
@@ -69,6 +101,7 @@ function createProvider(
       provider: 'codex',
       ...(config.effort ? { effort: config.effort } : {}),
       ...(config.model ? { model: config.model } : {}),
+      ...(config.timeout ? { timeout: config.timeout } : {}),
       ...(verbose === undefined ? {} : { verbose }),
       workspaceRoot: config.configDir,
     })
@@ -78,6 +111,7 @@ function createProvider(
     provider: 'claude',
     ...(config.effort ? { effort: config.effort } : {}),
     ...(config.model ? { model: config.model } : {}),
+    ...(config.timeout ? { timeout: config.timeout } : {}),
     ...(verbose === undefined ? {} : { verbose }),
     workspaceRoot: config.configDir,
   })
@@ -138,6 +172,10 @@ export async function runBatchCommand(
   })
 
   const processedFiles: string[] = []
+  const totalFiles = discoveredFiles.length
+  let blockedCount = 0
+  let completedCount = 0
+  let suspendedCount = 0
 
   for await (const event of runSession({
     config: {},
@@ -153,8 +191,70 @@ export async function runBatchCommand(
         }),
     },
   })) {
+    if (event.type === SessionEventType.SessionStarted) {
+      const progress = readSessionProgress(event.detail)
+      if (progress) {
+        blockedCount = progress.blocked
+        completedCount = progress.completed
+        suspendedCount = progress.suspended
+      }
+      writeBatchVerboseLine(
+        input.verbose,
+        `resume total=${totalFiles} completed=${completedCount} blocked=${blockedCount} suspended=${suspendedCount}`,
+      )
+      continue
+    }
+
+    if (event.type === SessionEventType.SubjectStarted) {
+      writeBatchVerboseLine(
+        input.verbose,
+        `start completed=${completedCount}/${totalFiles} file=${event.subjectId}`,
+      )
+      continue
+    }
+
+    if (event.type === SessionEventType.SubjectResumed) {
+      suspendedCount = Math.max(0, suspendedCount - 1)
+      writeBatchVerboseLine(
+        input.verbose,
+        `resume-file completed=${completedCount}/${totalFiles} file=${event.subjectId}`,
+      )
+      continue
+    }
+
     if (event.type === SessionEventType.SubjectDone) {
+      completedCount += 1
       processedFiles.push(event.subjectId)
+      writeBatchVerboseLine(
+        input.verbose,
+        `done completed=${completedCount}/${totalFiles} file=${event.subjectId}`,
+      )
+      continue
+    }
+
+    if (event.type === SessionEventType.SubjectBlocked) {
+      blockedCount += 1
+      writeBatchVerboseLine(
+        input.verbose,
+        `blocked completed=${completedCount}/${totalFiles} file=${event.subjectId}`,
+      )
+      continue
+    }
+
+    if (event.type === SessionEventType.SubjectSuspended) {
+      suspendedCount += 1
+      writeBatchVerboseLine(
+        input.verbose,
+        `suspended completed=${completedCount}/${totalFiles} file=${event.subjectId}`,
+      )
+      continue
+    }
+
+    if (event.type === SessionEventType.SessionDone) {
+      writeBatchVerboseLine(
+        input.verbose,
+        `session-done total=${totalFiles} completed=${completedCount} blocked=${blockedCount} suspended=${suspendedCount}`,
+      )
     }
   }
 

package/src/commands/run-providers.ts

@@ -4,6 +4,7 @@ import {
   createClaudeEventHandler,
   createCodexEventHandler,
 } from '../agents/event-log'
+import { providerOptionsCacheKey } from '../agents/provider-options'
 import { createCodexRemoteReviewerProvider } from '../workflow/remote-reviewer'
 
 import type {
@@ -26,12 +27,10 @@ export function createProviderResolver(
   context: WorkspaceContext,
   verbose: boolean | undefined,
 ): ProviderResolver {
-  const cache = new Map<
-    WorkflowProvider,
-    ImplementerProvider & ReviewerProvider
-  >()
+  const cache = new Map<string, ImplementerProvider & ReviewerProvider>()
   return (role: WorkflowRoleConfig) => {
-    const cached = cache.get(role.provider)
+    const cacheKey = providerOptionsCacheKey(role)
+    const cached = cache.get(cacheKey)
     if (cached) {
       return cached
     }
@@ -41,6 +40,7 @@ export function createProviderResolver(
       provider = createClaudeProvider({
         ...(role.effort ? { effort: role.effort } : {}),
         ...(role.model ? { model: role.model } : {}),
+        ...(role.timeout ? { timeout: role.timeout } : {}),
         workspaceRoot: context.workspaceRoot,
         ...(onEvent ? { onEvent } : {}),
       })
@@ -49,11 +49,12 @@ export function createProviderResolver(
       provider = createCodexProvider({
         ...(role.effort ? { effort: role.effort } : {}),
         ...(role.model ? { model: role.model } : {}),
+        ...(role.timeout ? { timeout: role.timeout } : {}),
         workspaceRoot: context.workspaceRoot,
         ...(onEvent ? { onEvent } : {}),
       })
     }
-    cache.set(role.provider, provider)
+    cache.set(cacheKey, provider)
     return provider
   }
 }

package/src/core/create-runtime-ports.ts

@@ -10,6 +10,7 @@ import {
   createClaudeEventHandler,
   createCodexEventHandler,
 } from '../agents/event-log'
+import { providerOptionsCacheKey } from '../agents/provider-options'
 import { GitRuntime } from '../runtime/git'
 import { GitHubRuntime } from '../runtime/github'
 import { createRuntimePaths } from '../runtime/path-layout'
@@ -54,7 +55,7 @@ export function createRuntimePorts(
   const agentCache = new Map<string, AgentPort>()
 
   function resolveAgent(role: AgentRoleConfig): AgentPort {
-    const key = `${role.provider}:${role.model ?? ''}:${role.effort ?? ''}`
+    const key = providerOptionsCacheKey(role)
     const cached = agentCache.get(key)
     if (cached) {
       return cached
@@ -72,6 +73,7 @@ export function createRuntimePorts(
             }
           : {}),
         ...(role.model ? { model: role.model } : {}),
+        ...(role.timeout ? { timeout: role.timeout } : {}),
         workspaceRoot: context.workspaceRoot,
         ...(onEvent ? { onEvent } : {}),
       })
@@ -86,6 +88,7 @@ export function createRuntimePorts(
             }
           : {}),
         ...(role.model ? { model: role.model } : {}),
+        ...(role.timeout ? { timeout: role.timeout } : {}),
         workspaceRoot: context.workspaceRoot,
         ...(onEvent ? { onEvent } : {}),
       })

package/src/core/runtime.ts

@@ -138,6 +138,7 @@ export interface AgentRoleConfig {
   effort?: string | undefined
   model?: string | undefined
   provider: 'claude' | 'codex'
+  timeout?: number | undefined
 }
 
 export interface OrchestratorRuntime {