cowork-flow 0.0.48 → 0.0.49

package/template/skills/batch-execution/scripts/batch_recovery.py

@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Read-only Batch inspect and recovery projections."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from batch_state_machine import BATCH_STEPS, phase_for_step
+
+
+def failed_action(state: dict[str, Any]) -> dict[str, Any] | None:
+    """Return public facts for the action that paused Batch, if any."""
+
+    if state.get("phase") != "paused":
+        return None
+    action_results = dict(state.get("action_results") or {})
+    if not action_results:
+        return None
+    action_id, result = next(reversed(action_results.items()))
+    if not isinstance(result, dict):
+        return {"actionId": str(action_id)}
+    failed: dict[str, Any] = {"actionId": str(action_id)}
+    result_type = result.get("type")
+    if isinstance(result_type, str):
+        failed["type"] = result_type
+    outcome = result.get("outcome")
+    if isinstance(outcome, str):
+        failed["outcome"] = outcome
+    detail = result.get("detail")
+    if isinstance(detail, str) and detail.strip():
+        failed["detail"] = detail.strip()
+    return failed
+
+
+def current_phase(
+    state: dict[str, Any],
+    failed_action_facts: dict[str, Any] | None,
+) -> str | None:
+    """Project the current user-visible Batch phase without mutating state."""
+
+    next_action = state.get("next_action")
+    if isinstance(next_action, dict):
+        phase = next_action.get("phase")
+        return str(phase) if isinstance(phase, str) else None
+    if failed_action_facts is not None:
+        action_type = failed_action_facts.get("type")
+        if isinstance(action_type, str) and action_type in BATCH_STEPS:
+            return phase_for_step(action_type)
+    task_name = state.get("current_task")
+    if isinstance(task_name, str):
+        task_phases = dict(state.get("task_phases") or {})
+        phases = task_phases.get(task_name)
+        if isinstance(phases, list) and phases:
+            phase = phases[-1]
+            return str(phase) if isinstance(phase, str) else None
+    phase = state.get("phase")
+    return str(phase) if isinstance(phase, str) else None
+
+
+def recovery_facts(state: dict[str, Any]) -> dict[str, object]:
+    """Return read-only recovery hints for a paused Batch operation."""
+
+    if state.get("phase") != "paused":
+        return {}
+    operation_id = state.get("operation_id")
+    recovery: dict[str, object] = {}
+    if isinstance(operation_id, str) and operation_id.strip():
+        recovery["resumeCommand"] = f"batch-action resume {operation_id.strip()}"
+    task_name = state.get("current_task")
+    if isinstance(task_name, str) and task_name.strip():
+        recovery["retryTask"] = task_name.strip()
+    pause_reason = state.get("pause_reason")
+    if isinstance(pause_reason, str) and pause_reason.strip():
+        recovery["pausedReason"] = pause_reason.strip()
+    return recovery
+
+
+def inspect_projection(operation_id: str, state: dict[str, Any]) -> dict[str, Any]:
+    """Build the public inspect payload without state mutation or IO."""
+
+    failed = failed_action(state)
+    return {
+        "operationId": operation_id,
+        "state": state.get("phase"),
+        "rootTask": state.get("root_task"),
+        "currentPhase": current_phase(state, failed),
+        "currentTask": state.get("current_task"),
+        "completedTasks": list(state.get("completed_tasks") or []),
+        "pausedReason": state.get("pause_reason"),
+        "failedAction": failed,
+        "nextAction": state.get("next_action"),
+        "recovery": recovery_facts(state),
+    }

package/template/skills/batch-execution/scripts/batch_state_machine.py

@@ -0,0 +1,201 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Pure in-memory Batch state transitions and action construction."""
+
+from __future__ import annotations
+
+from typing import Any
+
+BATCH_STEPS = (
+    "start_task",
+    "init_implement_context",
+    "await_implement_result",
+    "review_task",
+    "init_check_context",
+    "await_check_result",
+    "complete_task",
+    "archive_task",
+    "commit_task",
+)
+STEP_PHASES = {
+    "start_task": "start",
+    "await_implement_result": "implement",
+    "review_task": "review",
+    "await_check_result": "check",
+    "complete_task": "complete",
+    "archive_task": "archive",
+    "commit_task": "commit",
+}
+LIFECYCLE_STATUSES = {
+    "start_task": "in_progress",
+    "review_task": "review",
+    "complete_task": "completed",
+    "archive_task": "completed",
+}
+RUNTIME_ROLES = {
+    "init_implement_context": "implement",
+    "await_implement_result": "implement",
+    "init_check_context": "check",
+    "await_check_result": "check",
+}
+
+
+class BatchExecutionError(RuntimeError):
+    """Raised when Batch graph, state, or host input is invalid."""
+
+    def __init__(self, code: str, detail: str) -> None:
+        self.code = code
+        self.detail = detail
+        super().__init__(f"{code}: {detail}")
+
+
+def phase_for_step(step: str) -> str:
+    """Return the public Batch phase for a step name."""
+
+    if "implement" in step:
+        return "implement"
+    if "check" in step:
+        return "check"
+    return STEP_PHASES[step]
+
+
+def runtime_for(state: dict[str, Any], task_name: str, role: str) -> dict[str, Any]:
+    """Return a previously initialized runtime context reference."""
+
+    runtime_contexts = dict(state.get("runtime_contexts") or {})
+    task_contexts = dict(runtime_contexts.get(task_name) or {})
+    runtime = task_contexts.get(role)
+    if not isinstance(runtime, dict):
+        raise BatchExecutionError(
+            "BATCH-RUNTIME-MISSING-001",
+            f"runtime context was not initialized for {task_name}:{role}",
+        )
+    return runtime
+
+
+def build_action(state: dict[str, Any], task_name: str, step: str) -> dict[str, Any]:
+    """Build the next host-neutral Batch action without external side effects."""
+
+    sequence = int(state.get("next_action_sequence") or 0) + 1
+    state["next_action_sequence"] = sequence
+    action: dict[str, Any] = {
+        "action_id": f"{state['operation_id']}:{sequence}:{task_name}:{step}",
+        "type": step,
+        "phase": phase_for_step(step),
+        "task": task_name,
+        "task_dir": f".cowork-flow/tasks/{task_name}",
+    }
+    role = RUNTIME_ROLES.get(step)
+    if step.startswith("init_") and role:
+        action.update(
+            {
+                "role": role,
+                "agent_type": f"cowork-{role}",
+                "title": f"{role.capitalize()} Batch task {task_name}",
+            }
+        )
+    if step.startswith("await_") and role:
+        runtime = runtime_for(state, task_name, role)
+        action.update(
+            {
+                "role": role,
+                "runtime_context_id": runtime["runtime_context_id"],
+                "host_context_key": runtime["host_context_key"],
+            }
+        )
+    return action
+
+
+def advance_state(state: dict[str, Any]) -> bool:
+    """Advance Batch state in memory until it needs Host input or is complete."""
+
+    if state.get("phase") in {"completed", "paused"}:
+        return False
+    if isinstance(state.get("next_action"), dict):
+        return False
+
+    changed = False
+    completed_tasks = list(state.get("completed_tasks") or [])
+    task_steps = dict(state.get("task_steps") or {})
+    retry_count = dict(state.get("retry_count") or {})
+
+    for task_name in state["ordered_tasks"]:
+        if task_name in completed_tasks:
+            continue
+        if state.get("current_task") != task_name:
+            state["current_task"] = task_name
+            changed = True
+        completed_steps = list(task_steps.get(task_name) or [])
+        for step in BATCH_STEPS:
+            if step in completed_steps:
+                continue
+            action = build_action(state, task_name, step)
+            state["next_action"] = action
+            state["phase"] = "awaiting_host"
+            return True
+
+        completed_tasks.append(task_name)
+        state["completed_tasks"] = completed_tasks
+        retry_count[task_name] = 0
+        state["retry_count"] = retry_count
+        state["current_task"] = None
+        changed = True
+
+    state["phase"] = "completed"
+    state["current_task"] = None
+    state["next_action"] = None
+    state["pause_reason"] = None
+    return True or changed
+
+
+def mark_step_completed(
+    state: dict[str, Any],
+    action: dict[str, Any],
+    result: dict[str, Any],
+) -> None:
+    """Record a verified Host action result in the in-memory Batch state."""
+
+    task_name = str(action["task"])
+    step = str(action["type"])
+    task_steps = dict(state.get("task_steps") or {})
+    completed_steps = list(task_steps.get(task_name) or [])
+    if step not in completed_steps:
+        completed_steps.append(step)
+    task_steps[task_name] = completed_steps
+    state["task_steps"] = task_steps
+
+    phase = STEP_PHASES.get(step)
+    if phase:
+        task_phases = dict(state.get("task_phases") or {})
+        completed_phases = list(task_phases.get(task_name) or [])
+        if phase not in completed_phases:
+            completed_phases.append(phase)
+        task_phases[task_name] = completed_phases
+        state["task_phases"] = task_phases
+
+    if step == "commit_task":
+        commits = dict(state.get("commits") or {})
+        commits[task_name] = result["commit_id"].strip()
+        state["commits"] = commits
+
+
+def pause_state(
+    state: dict[str, Any],
+    action: dict[str, Any],
+    result: dict[str, Any],
+    detail: str,
+) -> dict[str, Any]:
+    """Move Batch state to paused after a fail-closed Host result."""
+
+    task_name = str(action["task"])
+    retry_count = dict(state.get("retry_count") or {})
+    retry_count[task_name] = int(retry_count.get(task_name, 0)) + 1
+    state["retry_count"] = retry_count
+    action_results = dict(state.get("action_results") or {})
+    action_results[result["action_id"]] = dict(result)
+    state["action_results"] = action_results
+    state["phase"] = "paused"
+    state["current_task"] = task_name
+    state["next_action"] = None
+    state["pause_reason"] = f"{task_name}:{action['type']}: {detail}"
+    return state

package/template/skills/batch-execution/scripts/batch_verification.py

@@ -0,0 +1,326 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Batch Host-result verification separated from state advancement."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Callable
+
+from batch_state_machine import (
+    LIFECYCLE_STATUSES,
+    RUNTIME_ROLES,
+    BatchExecutionError,
+    runtime_for,
+)
+
+CommitVerifier = Callable[[str], bool]
+
+
+def normalize_result(payload: dict[str, Any]) -> dict[str, Any]:
+    """Normalize a Host action result and fail closed on malformed input."""
+
+    if not isinstance(payload, dict):
+        raise BatchExecutionError(
+            "BATCH-RESULT-PAYLOAD-001",
+            "Host action result must be a JSON object",
+        )
+    result = dict(payload)
+    for key in ("action_id", "type", "outcome"):
+        value = result.get(key)
+        if not isinstance(value, str) or not value.strip():
+            raise BatchExecutionError(
+                "BATCH-RESULT-PAYLOAD-001",
+                f"Host action result is missing {key}",
+            )
+        result[key] = value.strip()
+    return result
+
+
+def required_text(payload: dict[str, Any], key: str, detail: str) -> str:
+    value = payload.get(key)
+    if not isinstance(value, str) or not value.strip():
+        raise BatchExecutionError("BATCH-RESULT-PAYLOAD-001", detail)
+    return value.strip()
+
+
+def optional_text(payload: dict[str, Any], key: str) -> str | None:
+    value = payload.get(key)
+    if isinstance(value, str) and value.strip():
+        return value.strip()
+    return None
+
+
+class BatchActionVerifier:
+    """Verify Host facts for one Batch action without advancing the state machine."""
+
+    def __init__(
+        self,
+        repo_root: Path,
+        runtime_contexts: Any,
+        commit_verifier: CommitVerifier,
+    ) -> None:
+        self.repo_root = Path(repo_root)
+        self.runtime_contexts = runtime_contexts
+        self.commit_verifier = commit_verifier
+
+    def verify_success(
+        self,
+        state: dict[str, Any],
+        action: dict[str, Any],
+        result: dict[str, Any],
+    ) -> None:
+        action_type = str(action["type"])
+        task_name = str(action["task"])
+        if action_type == "archive_task":
+            self.verify_archive_result(task_name, result)
+            return
+        if action_type in LIFECYCLE_STATUSES:
+            self.verify_task_status(task_name, LIFECYCLE_STATUSES[action_type], result)
+            return
+        if action_type.startswith("init_"):
+            self.verify_runtime_initialized(
+                state,
+                task_name,
+                RUNTIME_ROLES[action_type],
+                result,
+            )
+            return
+        if action_type.startswith("await_"):
+            self.verify_runtime_completed(
+                state,
+                task_name,
+                RUNTIME_ROLES[action_type],
+                action,
+                result,
+            )
+            return
+        if action_type == "commit_task":
+            commit_id = required_text(result, "commit_id", "commit result is missing commit_id")
+            if not self.commit_verifier(commit_id):
+                raise BatchExecutionError(
+                    "BATCH-COMMIT-VERIFY-001",
+                    f"commit_id could not be verified: {commit_id}",
+                )
+            return
+        raise BatchExecutionError(
+            "BATCH-ACTION-UNKNOWN-001",
+            f"unsupported Batch action: {action_type}",
+        )
+
+    def verify_task_status(
+        self,
+        task_name: str,
+        expected_status: str,
+        result: dict[str, Any],
+    ) -> None:
+        reported = optional_text(result, "task_status")
+        if reported and reported != expected_status:
+            raise BatchExecutionError(
+                "BATCH-TASK-STATUS-001",
+                f"Host reported task status {reported}; expected {expected_status}",
+            )
+        task_path = self.repo_root / ".cowork-flow" / "tasks" / task_name / "task.json"
+        try:
+            task_data = json.loads(task_path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as error:
+            raise BatchExecutionError(
+                "BATCH-TASK-LOAD-001",
+                f"cannot load task status for {task_name}: {error}",
+            ) from error
+        actual = task_data.get("status")
+        if actual != expected_status:
+            raise BatchExecutionError(
+                "BATCH-TASK-STATUS-001",
+                f"task status for {task_name} is {actual}; expected {expected_status}",
+            )
+
+    def verify_archive_result(self, task_name: str, result: dict[str, Any]) -> None:
+        destination = required_text(
+            result,
+            "archive_destination",
+            "archive result is missing archive_destination",
+        )
+        destination_path = Path(destination)
+        if destination_path.is_absolute():
+            raise BatchExecutionError(
+                "BATCH-ARCHIVE-VERIFY-001",
+                f"archive_destination must be relative: {destination}",
+            )
+        archive_root = (self.repo_root / ".cowork-flow" / "tasks" / "archive").resolve()
+        archive_path = (self.repo_root / destination_path).resolve()
+        try:
+            archive_path.relative_to(archive_root)
+        except ValueError as error:
+            raise BatchExecutionError(
+                "BATCH-ARCHIVE-VERIFY-001",
+                "archive_destination must be under "
+                f".cowork-flow/tasks/archive: {destination}",
+            ) from error
+        if archive_path.name != task_name:
+            raise BatchExecutionError(
+                "BATCH-ARCHIVE-VERIFY-001",
+                f"archive_destination task name is {archive_path.name}; expected {task_name}",
+            )
+        if not archive_path.is_dir():
+            raise BatchExecutionError(
+                "BATCH-ARCHIVE-VERIFY-001",
+                f"archive_destination does not exist: {destination}",
+            )
+        task_json = archive_path / "task.json"
+        try:
+            task_data = json.loads(task_json.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as error:
+            raise BatchExecutionError(
+                "BATCH-ARCHIVE-VERIFY-001",
+                f"archive_destination task.json cannot be loaded: {error}",
+            ) from error
+        logical_task_names = {task_name}
+        if len(task_name) > 6 and task_name[2] == "-" and task_name[5] == "-":
+            logical_task_names.add(task_name[6:])
+        if not any(task_data.get(field) in logical_task_names for field in ("name", "id")):
+            raise BatchExecutionError(
+                "BATCH-ARCHIVE-VERIFY-001",
+                "archive_destination task identity is "
+                f"name={task_data.get('name')} id={task_data.get('id')}; "
+                f"expected one of {sorted(logical_task_names)}",
+            )
+        if task_data.get("status") != "completed":
+            raise BatchExecutionError(
+                "BATCH-ARCHIVE-VERIFY-001",
+                f"archive_destination task status is {task_data.get('status')}; expected completed",
+            )
+
+    def verify_runtime_initialized(
+        self,
+        state: dict[str, Any],
+        task_name: str,
+        role: str,
+        result: dict[str, Any],
+    ) -> None:
+        runtime_context_id = required_text(
+            result,
+            "runtime_context_id",
+            "runtime initialization result is missing runtime_context_id",
+        )
+        host_context_key = required_text(
+            result,
+            "host_context_key",
+            "runtime initialization result is missing host_context_key",
+        )
+        context = self.runtime_contexts.load(runtime_context_id)
+        self.verify_runtime_identity(context, task_name, role, runtime_context_id)
+        status = context.get("status")
+        if status == "closed":
+            raise BatchExecutionError(
+                "BATCH-RUNTIME-CLOSED-001",
+                f"runtime context is already closed: {runtime_context_id}",
+            )
+        bound_key = context.get("bound_context_key")
+        if bound_key and bound_key != host_context_key:
+            raise BatchExecutionError(
+                "BATCH-RUNTIME-BIND-001",
+                f"runtime context {runtime_context_id} is bound to {bound_key}, not {host_context_key}",
+            )
+        runtime_contexts = dict(state.get("runtime_contexts") or {})
+        task_contexts = dict(runtime_contexts.get(task_name) or {})
+        task_contexts[role] = {
+            "runtime_context_id": runtime_context_id,
+            "host_context_key": host_context_key,
+        }
+        runtime_contexts[task_name] = task_contexts
+        state["runtime_contexts"] = runtime_contexts
+
+    def verify_runtime_completed(
+        self,
+        state: dict[str, Any],
+        task_name: str,
+        role: str,
+        action: dict[str, Any],
+        result: dict[str, Any],
+    ) -> None:
+        runtime = runtime_for(state, task_name, role)
+        runtime_context_id = required_text(
+            result,
+            "runtime_context_id",
+            "runtime result is missing runtime_context_id",
+        )
+        host_context_key = required_text(
+            result,
+            "host_context_key",
+            "runtime result is missing host_context_key",
+        )
+        if runtime_context_id != runtime["runtime_context_id"]:
+            raise BatchExecutionError(
+                "BATCH-RUNTIME-ID-001",
+                "runtime_context_id does not match initialized context: "
+                f"{runtime_context_id}; expected {runtime['runtime_context_id']}",
+            )
+        if host_context_key != runtime["host_context_key"]:
+            raise BatchExecutionError(
+                "BATCH-RUNTIME-BIND-001",
+                "host_context_key does not match initialized context: "
+                f"{host_context_key}; expected {runtime['host_context_key']}",
+            )
+        if action.get("runtime_context_id") != runtime_context_id:
+            raise BatchExecutionError(
+                "BATCH-RUNTIME-ID-001",
+                "runtime_context_id does not match pending action: "
+                f"{runtime_context_id}; expected {action.get('runtime_context_id')}",
+            )
+        context = self.runtime_contexts.load(runtime_context_id)
+        self.verify_runtime_identity(context, task_name, role, runtime_context_id)
+        status = context.get("status")
+        if status not in {"bound", "closed"}:
+            raise BatchExecutionError(
+                "BATCH-RUNTIME-BIND-001",
+                f"runtime context {runtime_context_id} is not bound",
+            )
+        if context.get("bound_context_key") != host_context_key:
+            raise BatchExecutionError(
+                "BATCH-RUNTIME-BIND-001",
+                f"runtime context {runtime_context_id} bound_context_key does not match result: "
+                f"{context.get('bound_context_key')}; expected {host_context_key}",
+            )
+        if status == "bound":
+            if not self.runtime_contexts.close(runtime_context_id):
+                raise BatchExecutionError(
+                    "BATCH-RUNTIME-CLOSE-001",
+                    f"runtime context could not be closed: {runtime_context_id}",
+                )
+            closed = self.runtime_contexts.load(runtime_context_id)
+            if closed.get("status") != "closed":
+                raise BatchExecutionError(
+                    "BATCH-RUNTIME-CLOSE-001",
+                    f"runtime context did not close: {runtime_context_id}",
+                )
+
+    @staticmethod
+    def verify_runtime_identity(
+        context: dict[str, Any],
+        task_name: str,
+        role: str,
+        runtime_context_id: str,
+    ) -> None:
+        if not context:
+            raise BatchExecutionError(
+                "BATCH-RUNTIME-MISSING-001",
+                f"runtime context does not exist: {runtime_context_id}",
+            )
+        if context.get("scope") != "subagent":
+            raise BatchExecutionError(
+                "BATCH-RUNTIME-SCOPE-001",
+                f"runtime context is not subagent-scoped: {runtime_context_id}",
+            )
+        if context.get("role") != role:
+            raise BatchExecutionError(
+                "BATCH-RUNTIME-ROLE-001",
+                f"runtime context role is not {role}: {runtime_context_id}",
+            )
+        expected_task_dir = f".cowork-flow/tasks/{task_name}"
+        if context.get("task_dir") != expected_task_dir:
+            raise BatchExecutionError(
+                "BATCH-RUNTIME-TASK-001",
+                f"runtime context task_dir is not {expected_task_dir}",
+            )

package/template/skills/cowork-flow/SKILL.md

@@ -41,5 +41,8 @@ Use the `task next` route payload and its `activatedSkill`/`recommendedSkill` fi
 Select at most one public Skill. If the payload has no Skill, follow the allowed
 operation directly or report the blocker; never guess a second workflow entry.
 
+Before editing for implement, read `implement.jsonl` and every listed `file` entry.
+If `test-first` is listed, read it and write the red test before production code.
+
 Public Skills carry workflow guidance. Runtime Gates carry hard enforcement.
 Do not recreate an internal protocol layer or another process authority.