cowork-flow 0.0.37 → 0.0.39

package/template/.cowork-flow/scripts/common/host/workflow_state_hook.py

@@ -0,0 +1,303 @@
+#!/usr/bin/env python3
+"""Shared workflow-state protocol used by host hook adapters."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+
+TAG_RE = re.compile(
+    r"\[workflow-state:([A-Za-z0-9_-]+)\]\s*\n(.*?)\n\s*"
+    r"\[/workflow-state:\1\]",
+    re.DOTALL,
+)
+DEFAULT_CONTRACT_REGISTRY = {
+    "contracts": [
+        {
+            "id": "RUNTIME_CONTEXT_DISPATCH_V2",
+            "path": ".cowork-flow/spec/contracts/subagent-dispatch.md",
+            "digest": [
+                "Formal subagent work is keyed by cowork_runtime_context_id.",
+                "Explicit shim bind records bound_context_key before formal output is accepted.",
+            ],
+            "readWhen": [
+                "before formal subagent dispatch",
+                "when checking subagent health",
+            ],
+        },
+    ]
+}
+
+
+def find_repo_root(start: Path) -> Path | None:
+    current = start.resolve()
+    while True:
+        if (current / ".cowork-flow").is_dir():
+            return current
+        if current == current.parent:
+            return None
+        current = current.parent
+
+
+def codex_dispatch_mode(root: Path) -> str:
+    _load_common(root)
+    try:
+        from common.core.config import get_codex_dispatch_mode
+    except Exception:
+        return "sub-agent"
+    try:
+        return get_codex_dispatch_mode(root)
+    except Exception:
+        return "sub-agent"
+
+
+def build_hook_context(
+    root: Path,
+    hook_input: dict[str, Any],
+    *,
+    host: str,
+    adapter: str,
+    preamble: tuple[str, ...],
+) -> str:
+    breadcrumbs = _load_breadcrumbs(root)
+    runtime_context, runtime_context_id = _resolve_runtime_context(
+        root,
+        hook_input,
+    )
+    extra_lines: list[str] | None = None
+    if runtime_context is not None:
+        task_dir = runtime_context.get("task_dir")
+        task_path = (
+            task_dir.strip()
+            if isinstance(task_dir, str) and task_dir.strip()
+            else None
+        )
+        status = "delegated_subtask"
+        source = (
+            f"runtime-context:{runtime_context.get('runtime_context_id')}"
+        )
+        extra_lines = _subagent_runtime_lines(runtime_context)
+    elif runtime_context_id:
+        task_path = None
+        status = "delegated_subtask"
+        source = f"runtime-context-invalid:{runtime_context_id}"
+        extra_lines = [
+            f"Runtime context: {runtime_context_id}",
+            "Scope: subagent",
+            (
+                "Runtime context is missing, closed, or invalid. "
+                "Do not run start/resume/task start/archive/commit/spawn."
+            ),
+        ]
+    else:
+        task_path, status, source = _get_active_task(root, hook_input)
+
+    body = (
+        breadcrumbs.get(status)
+        or "Refer to .cowork-flow/workflow.md for the current step."
+    )
+    if extra_lines:
+        body = "\n".join([body, *extra_lines])
+    if task_path is None:
+        header = f"Status: {status}\nSource: {source}"
+    else:
+        header = f"Task: {task_path}\nStatus: {status}\nSource: {source}"
+    return "\n\n".join(
+        [
+            *preamble,
+            _build_contract_digest(root, host, adapter),
+            f"<workflow-state>\n{header}\n{body}\n</workflow-state>",
+        ]
+    )
+
+
+def _load_breadcrumbs(root: Path) -> dict[str, str]:
+    path = (
+        root
+        / ".cowork-flow"
+        / "spec"
+        / "contracts"
+        / "workflow-state-templates.md"
+    )
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return {}
+    return {
+        match.group(1): match.group(2).strip()
+        for match in TAG_RE.finditer(text)
+    }
+
+
+def _load_contract_registry(
+    root: Path,
+) -> tuple[list[dict[str, Any]], str | None]:
+    path = (
+        root
+        / ".cowork-flow"
+        / "spec"
+        / "runtime"
+        / "contract-registry.json"
+    )
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except OSError:
+        data = DEFAULT_CONTRACT_REGISTRY
+        warning = f"contract registry unavailable at {path}; using fallback digest"
+    except json.JSONDecodeError:
+        data = DEFAULT_CONTRACT_REGISTRY
+        warning = f"contract registry invalid at {path}; using fallback digest"
+    else:
+        warning = None
+    contracts = data.get("contracts") if isinstance(data, dict) else None
+    if not isinstance(contracts, list):
+        contracts = DEFAULT_CONTRACT_REGISTRY["contracts"]
+        warning = warning or (
+            f"contract registry has no contracts array at {path}; "
+            "using fallback digest"
+        )
+    return [
+        contract for contract in contracts if isinstance(contract, dict)
+    ], warning
+
+
+def _build_contract_digest(
+    root: Path,
+    host: str,
+    adapter: str,
+) -> str:
+    contracts, warning = _load_contract_registry(root)
+    digest = hashlib.sha256()
+    digest.update(
+        json.dumps(
+            contracts,
+            ensure_ascii=False,
+            sort_keys=True,
+        ).encode("utf-8")
+    )
+    for contract in contracts:
+        path = contract.get("path")
+        if not isinstance(path, str) or not path.strip():
+            continue
+        try:
+            digest.update((root / path).read_bytes())
+        except OSError:
+            digest.update(f"missing:{path}".encode("utf-8"))
+    lines = [
+        f'<cowork-runtime host="{host}" adapter="{adapter}">',
+        f'<contract-digest fingerprint="{digest.hexdigest()[:16]}">',
+        (
+            "policy: repeat this short digest every hook; "
+            "read full spec files only before listed actions."
+        ),
+    ]
+    if warning:
+        lines.append(f"warning: {warning}")
+    for contract in contracts:
+        contract_id = contract.get("id")
+        path = contract.get("path")
+        if not isinstance(contract_id, str) or not contract_id.strip():
+            continue
+        path_text = (
+            path if isinstance(path, str) and path.strip() else "<missing-path>"
+        )
+        lines.append(f"- {contract_id}: {path_text}")
+        for item in _string_list(contract.get("digest"))[:2]:
+            lines.append(f"  digest: {item}")
+        read_when = _string_list(contract.get("readWhen"))
+        if read_when:
+            lines.append(f"  read_before: {'; '.join(read_when)}")
+    lines.extend(["</contract-digest>", "</cowork-runtime>"])
+    return "\n".join(lines)
+
+
+def _get_active_task(
+    root: Path,
+    hook_input: dict[str, Any],
+) -> tuple[str | None, str, str]:
+    _load_common(root)
+    try:
+        from common.task.active_task import get_active_task
+    except Exception:
+        return None, "no_task", "unavailable"
+    active = get_active_task(root, hook_input)
+    if not active.task_path:
+        return None, "no_task", active.source
+    task_json = root / active.task_path / "task.json"
+    try:
+        data = json.loads(task_json.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return active.task_path, "stale", active.source
+    status = data.get("status")
+    if not isinstance(status, str) or not status.strip():
+        status = "unknown"
+    return active.task_path, status.strip(), active.source
+
+
+def _resolve_runtime_context(
+    root: Path,
+    hook_input: dict[str, Any],
+) -> tuple[dict[str, Any] | None, str | None]:
+    _load_common(root)
+    try:
+        from common.task.active_task import (
+            bind_runtime_context,
+            read_runtime_context,
+            resolve_runtime_context_id,
+        )
+    except Exception:
+        return None, None
+    runtime_context_id = resolve_runtime_context_id(hook_input)
+    if not runtime_context_id:
+        return None, None
+    context = read_runtime_context(root, runtime_context_id)
+    if (
+        not context
+        or context.get("scope") != "subagent"
+        or context.get("status") == "closed"
+    ):
+        return None, runtime_context_id
+    bound = bind_runtime_context(
+        root,
+        runtime_context_id,
+        values=hook_input,
+    )
+    return bound or context, runtime_context_id
+
+
+def _subagent_runtime_lines(context: dict[str, Any]) -> list[str]:
+    assignment = (
+        context.get("assignment")
+        if isinstance(context.get("assignment"), dict)
+        else {}
+    )
+    lines = [
+        f"Runtime context: {context.get('runtime_context_id')}",
+        f"Agent: {context.get('agent_type') or 'unknown'}",
+        "Scope: subagent",
+        "Do not run start/resume/task start/archive/commit/spawn.",
+    ]
+    goal = assignment.get("goal")
+    if isinstance(goal, str) and goal.strip():
+        lines.append(f"Goal: {goal.strip()}")
+    return lines
+
+
+def _load_common(root: Path) -> None:
+    scripts_dir = root / ".cowork-flow" / "scripts"
+    if str(scripts_dir) not in sys.path:
+        sys.path.insert(0, str(scripts_dir))
+
+
+def _string_list(value: object) -> list[str]:
+    if not isinstance(value, list):
+        return []
+    return [
+        item for item in value
+        if isinstance(item, str) and item.strip()
+    ]

package/template/.cowork-flow/scripts/common/storage/__init__.py

@@ -0,0 +1 @@
+"""Revision-aware local state storage."""

package/template/.cowork-flow/scripts/common/storage/operation_log.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+"""Persistent operation log for recoverable multi-file writes."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from common.storage.state_store import StateStore, StateStoreError
+
+
+FINAL_PHASES = ("committed", "conflicted")
+
+
+class OperationLog:
+    """Persist and enumerate Unit of Work operation records."""
+
+    def __init__(
+        self,
+        repo_root: Path,
+        *,
+        state_store: StateStore | None = None,
+    ) -> None:
+        self.repo_root = Path(repo_root)
+        self.state_store = state_store or StateStore()
+        self.operations_dir = (
+            self.repo_root
+            / ".cowork-flow"
+            / ".runtime"
+            / "operations"
+        )
+
+    def path(self, operation_id: str) -> Path:
+        return self.operations_dir / f"{operation_id}.json"
+
+    def load(self, operation_id: str) -> dict:
+        return self.state_store.load(self.path(operation_id)).data
+
+    def create(self, operation_id: str, data: dict) -> dict:
+        path = self.path(operation_id)
+        if path.is_file():
+            return self.load(operation_id)
+        return self.state_store.replace(
+            path,
+            data,
+            expected_revision=0,
+            operation_id=f"{operation_id}:log:1",
+        ).data
+
+    def save(self, operation_id: str, data: dict) -> dict:
+        path = self.path(operation_id)
+        current = self.state_store.load(path)
+        return self.state_store.replace(
+            path,
+            data,
+            expected_revision=current.revision,
+            operation_id=(
+                f"{operation_id}:log:{current.revision + 1}"
+            ),
+        ).data
+
+    def pending(self) -> tuple[dict, ...]:
+        if not self.operations_dir.is_dir():
+            return ()
+        records: list[dict] = []
+        for path in sorted(self.operations_dir.glob("*.json")):
+            try:
+                record = self.state_store.load(path).data
+            except StateStoreError:
+                raise
+            if record.get("phase") not in FINAL_PHASES:
+                records.append(record)
+        return tuple(records)

package/template/.cowork-flow/scripts/common/storage/state_store.py

@@ -0,0 +1,279 @@
+#!/usr/bin/env python3
+"""Revision-aware UTF-8 JSON state persistence."""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from contextlib import contextmanager
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterator
+
+
+STATE_METADATA_KEY = "_state"
+ATOMIC_REPLACE_ATTEMPTS = 5
+ATOMIC_REPLACE_RETRY_SECONDS = 0.01
+
+
+class StateStoreError(RuntimeError):
+    """Raised when versioned state cannot be read or persisted."""
+
+    def __init__(self, code: str, path: Path, detail: str) -> None:
+        self.code = code
+        self.path = path
+        self.detail = detail
+        super().__init__(f"{code}: {detail}: {path}")
+
+
+@dataclass(frozen=True)
+class StateSnapshot:
+    path: Path
+    data: dict
+    revision: int
+    operation_id: str | None
+    exists: bool
+
+
+class StateStore:
+    """Read and compare-and-swap JSON state documents."""
+
+    def __init__(
+        self,
+        *,
+        lock_timeout_seconds: float = 5.0,
+        lock_poll_seconds: float = 0.01,
+    ) -> None:
+        self.lock_timeout_seconds = lock_timeout_seconds
+        self.lock_poll_seconds = lock_poll_seconds
+
+    def load(
+        self,
+        path: str | Path,
+        *,
+        missing_ok: bool = False,
+    ) -> StateSnapshot:
+        return self._load_unlocked(Path(path), missing_ok=missing_ok)
+
+    def replace(
+        self,
+        path: str | Path,
+        data: dict,
+        *,
+        expected_revision: int | None,
+        operation_id: str,
+    ) -> StateSnapshot:
+        target = Path(path)
+        with self._lock(target):
+            current = self._load_unlocked(target, missing_ok=True)
+            if current.operation_id == operation_id:
+                if current.data == data:
+                    return current
+                raise StateStoreError(
+                    "STATE-IDEMPOTENCY-001",
+                    target,
+                    "operation id was already used with different state",
+                )
+            self._check_revision(target, current, expected_revision)
+
+            next_revision = current.revision + 1
+            persisted = dict(data)
+            persisted[STATE_METADATA_KEY] = {
+                "schema_version": 1,
+                "revision": next_revision,
+                "operation_id": operation_id,
+            }
+            self._atomic_write(target, persisted)
+            return StateSnapshot(
+                path=target,
+                data=dict(data),
+                revision=next_revision,
+                operation_id=operation_id,
+                exists=True,
+            )
+
+    def delete(
+        self,
+        path: str | Path,
+        *,
+        expected_revision: int | None,
+        operation_id: str,
+    ) -> bool:
+        del operation_id
+        target = Path(path)
+        with self._lock(target):
+            current = self._load_unlocked(target, missing_ok=True)
+            if not current.exists:
+                return False
+            self._check_revision(target, current, expected_revision)
+            try:
+                target.unlink()
+            except OSError as error:
+                raise StateStoreError(
+                    "STATE-SAVE-001",
+                    target,
+                    "state file could not be deleted",
+                ) from error
+            return True
+
+    def _load_unlocked(
+        self,
+        path: Path,
+        *,
+        missing_ok: bool,
+    ) -> StateSnapshot:
+        try:
+            raw_text = path.read_text(encoding="utf-8")
+        except FileNotFoundError as error:
+            if missing_ok:
+                return StateSnapshot(path, {}, 0, None, False)
+            raise StateStoreError(
+                "STATE-LOAD-001",
+                path,
+                "state file is missing",
+            ) from error
+        except UnicodeDecodeError as error:
+            raise StateStoreError(
+                "STATE-LOAD-003",
+                path,
+                "state file is not valid UTF-8",
+            ) from error
+        except OSError as error:
+            raise StateStoreError(
+                "STATE-LOAD-004",
+                path,
+                "state file could not be read",
+            ) from error
+
+        try:
+            raw = json.loads(raw_text)
+        except json.JSONDecodeError as error:
+            raise StateStoreError(
+                "STATE-LOAD-002",
+                path,
+                "state file is not valid JSON",
+            ) from error
+        if not isinstance(raw, dict):
+            raise StateStoreError(
+                "STATE-LOAD-002",
+                path,
+                "state file must contain a JSON object",
+            )
+
+        persisted = dict(raw)
+        metadata = persisted.pop(STATE_METADATA_KEY, {})
+        if not isinstance(metadata, dict):
+            raise StateStoreError(
+                "STATE-LOAD-005",
+                path,
+                "state metadata must be a JSON object",
+            )
+        revision = metadata.get("revision", 0)
+        if not isinstance(revision, int) or revision < 0:
+            raise StateStoreError(
+                "STATE-LOAD-005",
+                path,
+                "state revision must be a non-negative integer",
+            )
+        operation_id = metadata.get("operation_id")
+        if operation_id is not None and not isinstance(operation_id, str):
+            raise StateStoreError(
+                "STATE-LOAD-005",
+                path,
+                "state operation id must be a string",
+            )
+        return StateSnapshot(
+            path=path,
+            data=persisted,
+            revision=revision,
+            operation_id=operation_id,
+            exists=True,
+        )
+
+    @staticmethod
+    def _check_revision(
+        path: Path,
+        current: StateSnapshot,
+        expected_revision: int | None,
+    ) -> None:
+        if (
+            expected_revision is not None
+            and current.revision != expected_revision
+        ):
+            raise StateStoreError(
+                "STATE-CONFLICT-001",
+                path,
+                "expected revision "
+                f"{expected_revision}, found {current.revision}",
+            )
+
+    @staticmethod
+    def _atomic_write(path: Path, data: dict) -> None:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        temp_path = path.with_name(
+            f"{path.name}.{os.getpid()}.{time.time_ns()}.tmp"
+        )
+        json_text = json.dumps(
+            data,
+            indent=2,
+            ensure_ascii=False,
+        ) + "\n"
+        try:
+            temp_path.write_text(json_text, encoding="utf-8")
+            StateStore._replace_with_retry(temp_path, path)
+        except OSError as error:
+            try:
+                temp_path.unlink(missing_ok=True)
+            except OSError:
+                pass
+            raise StateStoreError(
+                "STATE-SAVE-001",
+                path,
+                "state file could not be written atomically",
+            ) from error
+
+    @staticmethod
+    def _replace_with_retry(source: Path, target: Path) -> None:
+        for attempt in range(ATOMIC_REPLACE_ATTEMPTS):
+            try:
+                os.replace(source, target)
+                return
+            except PermissionError:
+                if attempt == ATOMIC_REPLACE_ATTEMPTS - 1:
+                    raise
+                time.sleep(
+                    ATOMIC_REPLACE_RETRY_SECONDS * (2 ** attempt)
+                )
+
+    @contextmanager
+    def _lock(self, path: Path) -> Iterator[None]:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        lock_path = path.with_name(f"{path.name}.lock")
+        deadline = time.monotonic() + self.lock_timeout_seconds
+        lock_handle = None
+        while lock_handle is None:
+            try:
+                lock_handle = lock_path.open("x", encoding="utf-8")
+            except FileExistsError as error:
+                if time.monotonic() >= deadline:
+                    raise StateStoreError(
+                        "STATE-LOCK-001",
+                        path,
+                        "timed out waiting for state lock",
+                    ) from error
+                time.sleep(self.lock_poll_seconds)
+            except OSError as error:
+                raise StateStoreError(
+                    "STATE-LOCK-001",
+                    path,
+                    "state lock could not be created",
+                ) from error
+        try:
+            yield
+        finally:
+            lock_handle.close()
+            try:
+                lock_path.unlink(missing_ok=True)
+            except OSError:
+                pass