task-while 0.0.2 → 0.0.4

package/README.md

@@ -1,14 +1,14 @@
 # task-while
 
-`task-while` is a git-first task orchestrator built around a task source protocol. The published package name and CLI binary are both `task-while`.
+`task-while` is a git-first harness runtime built around a task source protocol. The published package name and CLI binary are both `task-while`.
 
 It reads workflow settings from `while.yaml`, opens the configured task source, executes one task at a time, reviews the result, integrates approved work, and creates one git commit per completed task. The built-in task sources are `spec-kit`, which consumes `spec.md`, `plan.md`, and `tasks.md` under `specs/<feature>/`, and `openspec`, which consumes an OpenSpec change under `openspec/changes/<change>/`.
 
-It also provides a standalone `batch` command for YAML-driven file processing that is independent from the feature/task orchestration workflow.
+It also provides a standalone `batch` command for YAML-driven file processing that is independent from the feature/task harness runtime workflow.
 
 ## Requirements
 
-- Node.js 18 or newer
+- Node.js 24 or newer
 - For `run`: a git repository with an initial commit
 - For `run`: a workspace with the directory layout required by the selected task source
 - For `run`: the files required by the selected task source
@@ -68,7 +68,7 @@ Current status:
 - `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
 - `workflow.mode: pull-request` currently supports only `codex` as the remote reviewer provider
-- `task.maxIterations` applies globally to every task in the selected source session
+- `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
 
 Example pull-request mode:
 
@@ -116,7 +116,7 @@ Useful flags:
 - `--feature <featureId>`: select the feature explicitly
 - For `task.source: openspec`, `--feature <featureId>` selects the OpenSpec change id
 - `--until-task <taskSelector>`: stop after the target task reaches `done`
-- `--verbose`: stream agent events to `stderr`
+- `--verbose`: stream direct provider details to `stderr`, including Claude init/task/tool/result summaries and Codex thinking, commands, MCP tools, file updates, todo changes, messages, and final usage
 
 ### `task-while batch`
 
@@ -127,6 +127,8 @@ 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
@@ -160,14 +162,13 @@ Batch behavior:
 - batch `codex` `effort` accepts `minimal`, `low`, `medium`, `high`, or `xhigh`
 - batch `claude` `effort` accepts `low`, `medium`, `high`, or `max`
 - each run scans files under the `batch.yaml` directory and filters them by `glob`
-- execution state is written beside the YAML file in `state.json`
 - 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 provider agent events to `stderr` during batch execution
+- `--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
-- when the current `pending` queue is exhausted and `failed` is non-empty, the command persists a recycle transition that moves `failed` back into `pending` for the next round
-- the command exits only when both `pending` and `failed` are empty
-- there is no retry limit for file-level failures; failed files continue to be retried round by round
+- 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
 - when `glob` matches no files, the command exits successfully without initializing a provider
 
 ## Task Lifecycle
@@ -261,52 +262,51 @@ task:
 
 ## What `task-while` Does Not Do
 
-`task-while` does not replace Spec Kit's project-level workflow. It does not run Spec Kit commands, checklists, hooks, or preset-installed skills.
+`task-while` does not replace Spec Kit's project-level workflow. It does not run Spec Kit commands, checklists, or hooks.
 
 Its contract with the selected task source is simple:
 
 - the task source parses source artifacts and provides prompts plus completion operations
-- `task-while` orchestrates implement, review, integrate, and persistence around that protocol
+- the harness runtime drives implement, review, integrate, and persistence around that protocol
 
 The standalone `batch` command is separate from this contract. It does not use task sources, task graphs, review/integrate stages, or git-first completion.
 
+## Architecture
+
+`task-while` uses a state-machine control plane:
+
+- **TaskState** per subject is the single source of truth, written atomically as JSON
+- **Transition log** (append-only JSONL) records phase transitions for debugging
+- **Artifacts** store large structured outputs (contracts, reviews, implementations) separately
+- A **pure kernel interpreter** executes typed workflow programs (action/gate/branch nodes + declarative transition tables)
+- A **session layer** drives multi-subject scheduling via pluggable schedulers
+- All external effects flow through unified **ports** (AgentPort, CodeHostPort, GitPort)
+
 ## Runtime Layout
 
 `run` keeps runtime state under:
 
 ```text
-<source-entry>/<id>/.while/
+<source-entry>/<id>/.while/harness/
+  state/<protocol>/<subject-id>.json         — TaskState per subject (truth)
+  transitions/<protocol>/<subject-id>.jsonl  — TransitionRecord log (debug)
+  artifacts/<protocol>/<subject-id>/*.json   — Artifact per kind/iteration
 ```
 
-Important files:
-
-- `state.json`
-- `graph.json`
-- `report.json`
-- `events.jsonl`
-- `tasks/<taskHandle>/g<generation>/a<attempt>/implement.json`
-- `tasks/<taskHandle>/g<generation>/a<attempt>/review.json`
-- `tasks/<taskHandle>/g<generation>/a<attempt>/integrate.json`
-
-`.while` is runtime state, not the long-term source of truth. Pull-request review recovery reloads persisted `implement` artifacts by `taskHandle`, `generation`, and `attempt`.
+`.while` is runtime state, not the long-term source of truth. Resume reads the state file directly — no event replay needed.
 
 `batch` keeps runtime files beside the YAML config:
 
 ```text
 <config-dir>/
 ├── batch.yaml
-├── state.json
-└── results.json
+├── results.json
+└── .while/harness/
+    ├── state/batch/*.json
+    ├── transitions/batch/*.jsonl
+    └── artifacts/batch/...
 ```
 
-`state.json` contains:
-
-- `pending`
-- `inProgress`
-- `failed`
-
-`failed` is the current round's failure buffer. When `pending` becomes empty, those paths are persisted back into `pending` and retried in the next round. Historical state entries whose files no longer exist are dropped when a new run starts.
-
 `results.json` maps accepted structured output by file path relative to the `batch.yaml` directory. If the config lives under a subdirectory and uses patterns such as `../input/*.txt`, the keys keep that relative form.
 
 ## Publishing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "task-while",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "packageManager": "pnpm@10.32.1",
   "description": "Git-first task orchestrator for task-source workspaces",
   "author": "Zhang Yu",
@@ -48,7 +48,7 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.92",
-    "@openai/codex-sdk": "^0.116.0",
+    "@openai/codex-sdk": "^0.118.0",
     "ajv": "^8.18.0",
     "arg": "^5.0.2",
     "execa": "^8.0.1",

package/src/adapters/fs/harness-store.ts

@@ -0,0 +1,84 @@
+import { appendFile, mkdir, readdir, rename, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+
+import { pathExists, readJson } from 'fs-extra'
+
+import type { HarnessStore } from '../../harness/store'
+
+function encodeArtifactFileName(artifactId: string) {
+  return encodeURIComponent(artifactId)
+}
+
+export function createFsHarnessStore(root: string): HarnessStore {
+  const stateFile = (protocol: string, subjectId: string) =>
+    path.join(root, 'state', protocol, `${encodeURIComponent(subjectId)}.json`)
+
+  const artifactFile = (
+    protocol: string,
+    subjectId: string,
+    artifactId: string,
+  ) =>
+    path.join(
+      root,
+      'artifacts',
+      protocol,
+      encodeURIComponent(subjectId),
+      `${encodeArtifactFileName(artifactId)}.json`,
+    )
+
+  const artifactDir = (protocol: string, subjectId: string) =>
+    path.join(root, 'artifacts', protocol, encodeURIComponent(subjectId))
+
+  const transitionFile = (protocol: string, subjectId: string) =>
+    path.join(
+      root,
+      'transitions',
+      protocol,
+      `${encodeURIComponent(subjectId)}.jsonl`,
+    )
+
+  return {
+    async appendTransition(protocol, subjectId, record) {
+      const file = transitionFile(protocol, subjectId)
+      await mkdir(path.dirname(file), { recursive: true })
+      await appendFile(file, `${JSON.stringify(record)}\n`)
+    },
+    async listArtifacts(protocol, subjectId) {
+      const dir = artifactDir(protocol, subjectId)
+      if (!(await pathExists(dir))) {
+        return []
+      }
+      const directoryEntries = await readdir(dir)
+      const entries = directoryEntries.filter((e) => e.endsWith('.json'))
+      return Promise.all(
+        entries.map((entry) => readJson(path.join(dir, entry))),
+      )
+    },
+    async loadArtifact(protocol, subjectId, artifactId) {
+      const file = artifactFile(protocol, subjectId, artifactId)
+      if (!(await pathExists(file))) {
+        return null
+      }
+      return readJson(file)
+    },
+    async loadState(protocol, subjectId) {
+      const file = stateFile(protocol, subjectId)
+      if (!(await pathExists(file))) {
+        return null
+      }
+      return readJson(file)
+    },
+    async saveArtifact(protocol, subjectId, artifact) {
+      const file = artifactFile(protocol, subjectId, artifact.id)
+      await mkdir(path.dirname(file), { recursive: true })
+      await writeFile(file, JSON.stringify(artifact, null, 2))
+    },
+    async saveState(protocol, subjectId, state) {
+      const file = stateFile(protocol, subjectId)
+      const tmpFile = `${file}.tmp`
+      await mkdir(path.dirname(file), { recursive: true })
+      await writeFile(tmpFile, JSON.stringify(state, null, 2))
+      await rename(tmpFile, file)
+    },
+  }
+}

package/src/agents/claude.ts

@@ -22,11 +22,45 @@ export interface ClaudeTextEvent {
   type: 'text'
 }
 
-export interface ClaudeAssistantEvent {
-  type: 'assistant'
+export interface ClaudeInitEvent {
+  mcpServers: { name: string; status: string }[]
+  model: string
+  permissionMode: string
+  skills: string[]
+  tools: string[]
+  type: 'system.init'
+}
+
+export interface ClaudeTaskStartedEvent {
+  description: string
+  taskId: string
+  type: 'task.started'
+}
+
+export interface ClaudeTaskProgressEvent {
+  description: string
+  lastToolName?: string
+  summary?: string
+  taskId: string
+  type: 'task.progress'
+}
+
+export interface ClaudeToolProgressEvent {
+  elapsedTimeSeconds: number
+  toolName: string
+  toolUseId: string
+  type: 'tool.progress'
+}
+
+export interface ClaudeToolSummaryEvent {
+  summary: string
+  type: 'tool.summary'
 }
 
 export interface ClaudeResultEvent {
+  durationMs: number
+  numTurns: number
+  subtype: 'success'
   type: 'result'
 }
 
@@ -36,15 +70,21 @@ export interface ClaudeErrorEvent {
 }
 
 export type ClaudeAgentEvent =
-  | ClaudeAssistantEvent
   | ClaudeErrorEvent
+  | ClaudeInitEvent
   | ClaudeResultEvent
+  | ClaudeTaskProgressEvent
+  | ClaudeTaskStartedEvent
   | ClaudeTextEvent
+  | ClaudeToolProgressEvent
+  | ClaudeToolSummaryEvent
 
 export type ClaudeAgentEventHandler = (event: ClaudeAgentEvent) => void
 
 interface QueryResultMessage {
+  duration_ms?: number
   errors?: string[]
+  num_turns?: number
   structured_output?: unknown
   subtype: string
   type: 'result'
@@ -62,10 +102,53 @@ interface QueryAssistantMessage {
   type: 'assistant'
 }
 
+interface QuerySystemInitMessage {
+  mcp_servers: { name: string; status: string }[]
+  model: string
+  permissionMode: string
+  skills: string[]
+  subtype: 'init'
+  tools: string[]
+  type: 'system'
+}
+
+interface QueryTaskStartedMessage {
+  description: string
+  subtype: 'task_started'
+  task_id: string
+  type: 'system'
+}
+
+interface QueryTaskProgressMessage {
+  description: string
+  last_tool_name?: string
+  subtype: 'task_progress'
+  summary?: string
+  task_id: string
+  type: 'system'
+}
+
+interface QueryToolProgressMessage {
+  elapsed_time_seconds: number
+  tool_name: string
+  tool_use_id: string
+  type: 'tool_progress'
+}
+
+interface QueryToolUseSummaryMessage {
+  summary: string
+  type: 'tool_use_summary'
+}
+
 type QueryMessage =
   | QueryAssistantMessage
   | QueryResultMessage
   | QueryStreamEventMessage
+  | QuerySystemInitMessage
+  | QueryTaskProgressMessage
+  | QueryTaskStartedMessage
+  | QueryToolProgressMessage
+  | QueryToolUseSummaryMessage
 
 export interface ClaudeAgentClientOptions extends ClaudeProviderOptions {
   onEvent?: ClaudeAgentEventHandler
@@ -90,6 +173,65 @@ export class ClaudeAgentClient
     let structuredOutput: unknown = null
 
     for await (const message of messages) {
+      if (
+        message.type === 'system' &&
+        message.subtype === 'init' &&
+        this.options.onEvent
+      ) {
+        this.options.onEvent({
+          mcpServers: message.mcp_servers,
+          model: message.model,
+          permissionMode: message.permissionMode,
+          skills: message.skills,
+          tools: message.tools,
+          type: 'system.init',
+        })
+      }
+
+      if (
+        message.type === 'system' &&
+        message.subtype === 'task_started' &&
+        this.options.onEvent
+      ) {
+        this.options.onEvent({
+          description: message.description,
+          taskId: message.task_id,
+          type: 'task.started',
+        })
+      }
+
+      if (
+        message.type === 'system' &&
+        message.subtype === 'task_progress' &&
+        this.options.onEvent
+      ) {
+        this.options.onEvent({
+          description: message.description,
+          taskId: message.task_id,
+          type: 'task.progress',
+          ...(message.last_tool_name
+            ? { lastToolName: message.last_tool_name }
+            : {}),
+          ...(message.summary ? { summary: message.summary } : {}),
+        })
+      }
+
+      if (message.type === 'tool_progress' && this.options.onEvent) {
+        this.options.onEvent({
+          elapsedTimeSeconds: message.elapsed_time_seconds,
+          toolName: message.tool_name,
+          toolUseId: message.tool_use_id,
+          type: 'tool.progress',
+        })
+      }
+
+      if (message.type === 'tool_use_summary' && this.options.onEvent) {
+        this.options.onEvent({
+          summary: message.summary,
+          type: 'tool.summary',
+        })
+      }
+
       if (message.type === 'stream_event' && this.options.onEvent) {
         const event = message.event
         if (
@@ -101,10 +243,6 @@ export class ClaudeAgentClient
         }
       }
 
-      if (message.type === 'assistant' && this.options.onEvent) {
-        this.options.onEvent({ type: 'assistant' })
-      }
-
       if (message.type === 'result') {
         if (message.subtype !== 'success') {
           const detail = message.errors?.join('; ') ?? message.subtype
@@ -112,7 +250,12 @@ export class ClaudeAgentClient
         }
         structuredOutput = message.structured_output ?? null
         if (this.options.onEvent) {
-          this.options.onEvent({ type: 'result' })
+          this.options.onEvent({
+            durationMs: message.duration_ms ?? 0,
+            numTurns: message.num_turns ?? 0,
+            subtype: 'success',
+            type: 'result',
+          })
         }
       }
     }
@@ -138,12 +281,19 @@ export class ClaudeAgentClient
     const queryOptions = {
       allowDangerouslySkipPermissions: true,
       cwd: this.options.workspaceRoot,
-      includePartialMessages: !!this.options.onEvent,
       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

package/src/agents/codex.ts

@@ -58,11 +58,75 @@ export interface CodexTurnFailedError {
   message: string
 }
 
-export interface CodexItemPayload {
-  text?: string
-  type: string
+export interface CodexAgentMessageItem {
+  id: string
+  text: string
+  type: 'agent_message'
 }
 
+export interface CodexReasoningItem {
+  id: string
+  text: string
+  type: 'reasoning'
+}
+
+export interface CodexCommandExecutionItem {
+  aggregated_output: string
+  command: string
+  exit_code?: number
+  id: string
+  status: 'completed' | 'failed' | 'in_progress'
+  type: 'command_execution'
+}
+
+export interface CodexFileChangeItem {
+  changes: { kind: 'add' | 'delete' | 'update'; path: string }[]
+  id: string
+  status: 'completed' | 'failed'
+  type: 'file_change'
+}
+
+export interface CodexMcpToolCallItem {
+  arguments: unknown
+  error?: { message: string }
+  id: string
+  result?: {
+    structured_content: unknown
+  }
+  server: string
+  status: 'completed' | 'failed' | 'in_progress'
+  tool: string
+  type: 'mcp_tool_call'
+}
+
+export interface CodexWebSearchItem {
+  id: string
+  query: string
+  type: 'web_search'
+}
+
+export interface CodexTodoListItem {
+  id: string
+  items: { completed: boolean; text: string }[]
+  type: 'todo_list'
+}
+
+export interface CodexErrorItem {
+  id: string
+  message: string
+  type: 'error'
+}
+
+export type CodexItemPayload =
+  | CodexAgentMessageItem
+  | CodexCommandExecutionItem
+  | CodexErrorItem
+  | CodexFileChangeItem
+  | CodexMcpToolCallItem
+  | CodexReasoningItem
+  | CodexTodoListItem
+  | CodexWebSearchItem
+
 export type CodexThreadEvent =
   | CodexErrorEvent
   | CodexItemEvent
@@ -147,7 +211,7 @@ export class CodexAgentClient implements ImplementerProvider, ReviewerProvider {
         event.type === 'item.completed' &&
         event.item.type === 'agent_message'
       ) {
-        finalResponse = event.item.text?.trim() ?? ''
+        finalResponse = event.item.text.trim()
       }
     }