awf 1.0.0__py3-none-any.whl

awf/__init__.py

@@ -0,0 +1,3 @@
+"""awf — Agentic Workflow Framework Python core."""
+
+__version__ = "0.4.0"

awf/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for ``python3 -m awf``."""
+import sys
+
+from .cli import main
+
+sys.exit(main())

awf/_atomic.py

@@ -0,0 +1,37 @@
+"""Atomic file write helpers for awf-core.
+
+Centralized so all modules use the same temp+rename pattern.
+"""
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+
+
+def atomic_write_text(path: Path, content: str, encoding: str = "utf-8") -> None:
+    """Write text file atomically via temp + rename.
+
+    Creates parent dir if missing. Uses tempfile in same dir to guarantee
+    same-filesystem rename (atomic on POSIX).
+
+    H5 fix: plan_progress.py was direct write_text — crash mid-write
+    corrupted plan.md (the only persistent progress artifact).
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp_path = tempfile.mkstemp(
+        prefix=f".{path.name}.",
+        suffix=".tmp",
+        dir=str(path.parent),
+    )
+    try:
+        with os.fdopen(fd, "w", encoding=encoding) as f:
+            f.write(content)
+        os.replace(tmp_path, path)
+    except Exception:
+        # Clean up temp file on failure
+        try:
+            os.unlink(tmp_path)
+        except OSError:
+            pass
+        raise

awf/_env.py

@@ -0,0 +1,90 @@
+"""BD-22/25: subprocess environment setup for opencode run.
+
+Centralized so signal_watch + supervisor + agent_stage can use it without
+circular imports through orchestrator.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+
+def _pdeathsig_preexec() -> None:
+    """DF6-8: Set PR_SET_PDEATHSIG so child dies when parent (orchestrator) dies.
+
+    Linux-only. On other platforms, no-op (best effort).
+    Prevents orphan worker subprocesses from continuing after orchestrator crash.
+    """
+    if sys.platform != "linux":
+        return
+    try:
+        import ctypes
+        import signal as _signal
+
+        libc = ctypes.CDLL("libc.so.6", use_errno=True)
+        PR_SET_PDEATHSIG = 1
+        libc.prctl(PR_SET_PDEATHSIG, _signal.SIGTERM)
+    except Exception:
+        pass  # best effort — don't crash if libc/prctl unavailable
+
+
+def awf_subprocess_env() -> dict[str, str]:
+    """BD-22/KAUD-5: env for opencode subprocess spawned by awf.
+
+    Sets ``OPENCODE_CONFIG_CONTENT`` to override permission rules so
+    the subprocess can run ``edit``/``bash``/``write`` without prompting.
+
+    KAUD-5: MERGES with user's existing opencode.json instead of replacing.
+    Reads user's config, adds our permission overrides on top, preserves
+    user's other settings (theme, providers, agents, etc.).
+
+    BD-25: strip ``OPENCODE_SERVER_*`` env vars so the subprocess does NOT
+    attach to a running ``opencode serve`` instance.
+    """
+    env = os.environ.copy()
+
+    # KAUD-5: Start from user's existing config, then merge our overrides
+    user_config: dict = {}
+    try:
+        from .xdg import opencode_config_file
+        config_path = opencode_config_file()
+        if config_path.is_file():
+            user_config = json.loads(config_path.read_text(encoding="utf-8"))
+            if not isinstance(user_config, dict):
+                user_config = {}
+    except (OSError, json.JSONDecodeError):
+        pass  # If user config is unreadable, start from empty
+
+    # Merge: user config + our permission overrides (ours take priority)
+    merged = user_config.copy()
+    merged_permissions = merged.get("permission", {})
+    if not isinstance(merged_permissions, dict):
+        merged_permissions = {}
+    merged_permissions.update({
+        "edit": "allow",
+        "bash": "allow",
+        "write": "allow",
+        "webfetch": "allow",
+    })
+    merged["permission"] = merged_permissions
+
+    # P1 security: only serialize permission overrides to env — never API keys,
+    # providers, or other sensitive fields from opencode.json. Workers only
+    # need the permission overrides; everything else is loaded by opencode
+    # itself from the real config file.
+    config_json = json.dumps({"permission": merged_permissions})
+    env["OPENCODE_CONFIG_CONTENT"] = config_json
+
+    # BD-25: strip server env vars
+    strip_keys = (
+        "OPENCODE_SERVER",
+        "OPENCODE_SERVER_URL",
+        "OPENCODE_SERVER_TOKEN",
+        "OPENCODE_HOST",
+        "OPENCODE_HOST_TOKEN",
+    )
+    for key in list(env.keys()):
+        if key in strip_keys:
+            env.pop(key, None)
+    return env

awf/_log.py

@@ -0,0 +1,24 @@
+"""Lightweight file-based logger for awf.
+
+Centralized so any module can log without circular imports.
+"""
+from __future__ import annotations
+
+import datetime as _dt
+from pathlib import Path
+
+
+def log(logs_dir: Path, message: str) -> None:
+    """Append a timestamped message to ``logs_dir/orchestrator.log``."""
+    if not logs_dir.exists():
+        try:
+            logs_dir.mkdir(parents=True, exist_ok=True)
+        except OSError:
+            return
+    log_file = logs_dir / "orchestrator.log"
+    ts = _dt.datetime.now(_dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    try:
+        with open(log_file, "a", encoding="utf-8") as f:
+            f.write(f"[{ts}] {message}\n")
+    except OSError:
+        pass

awf/agent_stage.py

@@ -0,0 +1,275 @@
+"""Agent stage — spawn opencode run for each pipeline role.
+
+Extracted from orchestrator.py (A6 refactor).
+"""
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from . import paths
+from ._atomic import atomic_write_text
+from ._log import log as _log
+from .pipeline import Stage
+from .signals import clean_stage_signals, expected_signal_prefixes
+from .supervisor import (
+    build_prompt,
+    get_agent_name,
+    get_role_model,
+    resolve_role_file,
+)
+
+
+def run_agent_stage(
+    stage: Stage,
+    todo_id: str,
+    project_dir: Path,
+    config: dict,
+    logs_dir: Path,
+    prev_handoffs: list[Path] | None = None,
+    hard_timeout: int | None = None,
+) -> None:
+    """Spawn opencode run for an agent stage.
+
+    KAUD-4: ``hard_timeout`` overrides default 3600s timeout. Pass through
+    from CLI --timeout or config. None = use BD20_HARD_TIMEOUT default.
+
+    BD-15: ``prev_handoffs`` is a list of handoff .md files from previous
+    pipeline stages (in pipeline order). Each is passed to the agent as
+    ``--file`` so the agent sees what previous roles did.
+    """
+    role = stage.role
+    kind = stage.kind
+    agent_name = get_agent_name(config, role)
+
+    print()
+    print("=" * 41)
+    print(f"  AGENT STAGE: {role} ({kind})")
+    print(f"  Task: {todo_id}")
+    print("=" * 41)
+    print()
+
+    role_file = resolve_role_file(role, project_dir)
+    inbox = paths.inbox(project_dir)
+    todo_file = inbox / f"{todo_id}.md"
+
+    prompt = build_prompt(kind, todo_id, project_dir=project_dir)
+
+    print(f"Running agent: {agent_name}")
+    print(f"Role file: {role_file}")
+    print(f"Task: {todo_file}")
+    print()
+
+    # Clean stale signals this kind could produce
+    prefixes = expected_signal_prefixes(kind)
+    outbox = paths.outbox(project_dir)
+    clean_stage_signals(outbox, todo_id, *prefixes)
+
+    # DF5-5: clean stale PROGRESS from previous stage so collect_handoff
+    # doesn't pick up the previous worker's notes as this stage's output.
+    # PROGRESS is per-stage running notes, not cumulative. Previous stage's
+    # PROGRESS is already captured in its handoff .md file (BD-19).
+    stale_progress = outbox / f"PROGRESS-{todo_id}.md"
+    if stale_progress.exists():
+        stale_progress.unlink()
+        _log(logs_dir, f"DF5-5: cleaned stale PROGRESS-{todo_id}.md from previous stage")
+
+    _log(logs_dir, f"Agent stage started: {role} ({kind}) for {todo_id}")
+
+    cmd = [
+        "opencode", "run", "--auto",
+        "--print-logs",
+        "--agent", agent_name,
+        "--title", f"awf-{role}-{todo_id}",
+        "--file", str(role_file),
+        "--file", str(todo_file),
+    ]
+    role_model = get_role_model(config, role)
+    if role_model:
+        cmd += ["--model", role_model]
+
+    if prev_handoffs:
+        for hf in prev_handoffs:
+            if hf.is_file():
+                cmd += ["--file", str(hf)]
+                print(f"Handoff in:  {hf}")
+                _log(logs_dir, f"Forwarding handoff: {hf}")
+
+    cmd += ["--", prompt]
+
+    # BD-20: watch for expected signal files in outbox.
+    # P1: watch ALL expected prefixes, not just DONE/BLOCKED — otherwise
+    # REVIEW-APPROVED, TEST-PASSED etc. signals aren't detected until
+    # subprocess exits, causing unnecessary delays.
+    watch_paths: list[Path] = []
+    if todo_id:
+        for prefix in expected_signal_prefixes("execute"):
+            watch_paths.append(outbox / f"{prefix}-{todo_id}.ready")
+            watch_paths.append(outbox / f"{prefix}-{todo_id}.md.ready")
+
+    from ._env import awf_subprocess_env
+    from .signal_watch import run_subprocess_until_signal
+
+    result = run_subprocess_until_signal(
+        cmd, cwd=project_dir, watch_paths=watch_paths, logs_dir=logs_dir,
+        env=awf_subprocess_env(),
+        hard_timeout=hard_timeout,
+    )
+    _log(logs_dir, f"Agent stage finished: {role} ({kind}) for {todo_id} (exit={result.returncode})")
+    if result.returncode != 0:
+        raise RuntimeError(
+            f"Agent stage {role} ({kind}) subprocess exited with code {result.returncode}. "
+            f"Cmd: {' '.join(cmd)}"
+        )
+
+    collect_handoff(role, todo_id, project_dir, logs_dir)
+
+
+def collect_handoff(
+    role: str,
+    todo_id: str,
+    project_dir: Path,
+    logs_dir: Path,
+) -> Path:
+    """BD-15/19: gather PROGRESS/DONE + git diff summary into handoff .md.
+
+    BD-19: filename is ``<role>-<todo_id>.md`` so retry on the same role
+    doesn't overwrite the previous attempt's handoff.
+    """
+    handoff_dir = paths.agentic_dir(project_dir) / "handoff"
+    handoff_dir.mkdir(parents=True, exist_ok=True)
+    outbox = paths.outbox(project_dir)
+
+    progress = outbox / f"PROGRESS-{todo_id}.md"
+    # H2 fix: support legacy short form DONE-{short_id}.md
+    from .signals import find_signal_file
+    done_path = find_signal_file(outbox, "DONE", todo_id, ".md") or (outbox / f"DONE-{todo_id}.md")
+
+    parts: list[str] = [
+        f"# Handoff from `{role}` (TODO {todo_id})",
+        "",
+        "**Generated:** by awf orchestrator (BD-15)",
+        f"**Stage role:** {role}",
+        f"**TODO:** {todo_id}",
+        "",
+    ]
+
+    has_output = False
+    done_has_body = False
+    if done_path.is_file():
+        body = done_path.read_text(encoding="utf-8").strip()
+        if body:
+            parts += ["## DONE summary (from worker)", "", body, ""]
+            has_output = True
+            done_has_body = True
+
+    if progress.is_file():
+        body = progress.read_text(encoding="utf-8").strip()
+        if body:
+            parts += ["## PROGRESS notes (from worker)", "", body, ""]
+            has_output = True
+    elif not done_has_body:
+        # Only warn about missing PROGRESS if DONE summary is also absent.
+        # DONE carries the same info — warning when DONE exists is noise.
+        parts += [
+            "## ⚠️ Worker did not leave progress notes",
+            "",
+            f"Role `{role}` did not write PROGRESS-{todo_id}.md.",
+            "The work may still be valid — inspect git diff and DONE report.",
+            "",
+        ]
+
+    if not has_output:
+        parts += [
+            "## ⚠️ NO OUTPUT FROM PREVIOUS STAGE",
+            "",
+            f"Role `{role}` did not write PROGRESS-{todo_id}.md or DONE-{todo_id}.md.",
+            "Likely causes: worker crashed, hit turn-budget, or signalled",
+            "BLOCKED without leaving notes. Treat prior stage work as",
+            "unverified — inspect `git diff` against baseline before",
+            "proceeding. If this is unexpected, escalate via BLOCKED signal.",
+            "",
+        ]
+
+    # Git diff summary vs baseline
+    context_dir = paths.context_dir(project_dir)
+    sha_file = context_dir / f"BASELINE-{todo_id}.sha"
+    if sha_file.is_file():
+        base_sha = sha_file.read_text(encoding="utf-8").strip().split("\n")[0]
+        if base_sha:
+            try:
+                diff = subprocess.run(
+                    ["git", "diff", "--stat", base_sha],
+                    cwd=str(project_dir),
+                    capture_output=True,
+                    text=True,
+                    check=False,
+                    timeout=10,
+                )
+                if diff is not None and getattr(diff, "stdout", "").strip():
+                    parts += ["## Git diff summary (vs baseline)", "", "```", diff.stdout.strip(), "```", ""]
+            except (subprocess.TimeoutExpired, OSError) as e:
+                _log(logs_dir, f"handoff git-diff failed: {e}")
+
+    try:
+        last = subprocess.run(
+            ["git", "log", "-1", "--pretty=%h %s"],
+            cwd=str(project_dir),
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=5,
+        )
+        if last is not None and (getattr(last, "stdout", "") or "").strip():
+            parts += ["## Latest commit", "", f"`{last.stdout.strip()}`", ""]
+    except (subprocess.TimeoutExpired, OSError):
+        pass
+
+    parts += [
+        "## What the next role should know",
+        "",
+        "- Read this handoff first. The TODO file declares the goal; this file shows what's done.",
+        "- Pick up where this role left off. Do NOT redo work already done.",
+        "- Write your own handoff at `.agentic/handoff/<your-role>.md` when finished.",
+        "",
+    ]
+
+    out_file = handoff_dir / f"{role}-{todo_id}.md"
+    # QA-C: handoff write atomic (was direct write_text — inconsistent with
+    # rest of codebase which uses atomic_write_text for crash safety).
+    atomic_write_text(out_file, "\n".join(parts))
+    print(f"Handoff out: {out_file}")
+    _log(logs_dir, f"Handoff written: {out_file}")
+    return out_file
+
+
+def resolve_prev_handoffs(
+    pipeline_stages: list[Stage],
+    current_stage_idx: int,
+    project_dir: Path,
+    todo_id: str = "",
+) -> list[Path]:
+    """BD-15/19: return handoff paths for all AGENT stages before current_stage_idx."""
+    handoff_dir = paths.agentic_dir(project_dir) / "handoff"
+    result: list[Path] = []
+    for i in range(current_stage_idx):
+        st = pipeline_stages[i]
+        if st.role == "supervisor":
+            continue
+        if todo_id:
+            result.append(handoff_dir / f"{st.role}-{todo_id}.md")
+        else:
+            # P2: sort by name (numeric ID) instead of mtime — deterministic
+            # even when rapid retry creates files in the same second.
+            import re
+            def _sort_key(p: Path) -> tuple[int, str]:
+                m = re.search(r"(\d+)", p.name)
+                return (int(m.group(1)) if m else 0, p.name)
+            candidates = sorted(
+                handoff_dir.glob(f"{st.role}- *.md".replace(" ", "")),
+                key=_sort_key,
+                reverse=True,
+            )
+            if candidates:
+                result.append(candidates[0])
+    return result

awf/api/__init__.py

@@ -0,0 +1,128 @@
+"""Public API for agentic-workflow.
+
+All external callers (CLI, MCP plugin) MUST go through this module.
+Business logic lives in submodules — this file re-exports the public
+surface so callers can ``from awf import api; api.init_project(...)``.
+
+Layout:
+- ``_errors``      — AwfApiError
+- ``_results``     — Result dataclasses (InitResult, StatusResult,
+                     DispatchTodoResult, ApplyIncrementPlanResult, ...)
+- ``_stack``       — detect_stack, derive_project_name
+- ``_templates``   — _CONFIG_TEMPLATE, _ROLE_TEMPLATE, update_gitignore
+- ``_helpers``     — require_agentic, require_git_repo, read helpers
+- ``_background``  — start_in_background, check_pipeline_running, PipelineArgs
+- ``lifecycle``    — init_project, get_status, get_report, reset_runtime,
+                     list_orphans, remove_orphans
+- ``pipeline``     — start_pipeline, continue_pipeline, create_baseline,
+                     rollback, approve_commit
+- ``roles``        — add_role, analyze_roles
+- ``setup``        — apply_project_setup (project-setup form materialization)
+- ``dispatch``     — dispatch_todo (atomic TODO + baseline + signal)
+- ``context``      — load_supervisor_context (aggregate bootstrap payload),
+                     _extract_stage_info, _compute_expected_action
+- ``planning``     — apply_increment_plan (increment variant persistence)
+
+Error convention: every function returns a Result dataclass (success)
+or raises AwfApiError with a human-readable message. Callers wrap in
+try/except.
+"""
+from __future__ import annotations
+
+# Public types
+from ._errors import AwfApiError
+from ._results import (
+    AddRoleResult,
+    AnalyzeRolesResult,
+    ApplyIncrementPlanResult,
+    ApplyProjectSetupResult,
+    ApproveResult,
+    BaselineResult,
+    DispatchTodoResult,
+    InitResult,
+    ReportResult,
+    ResetResult,
+    RollbackResult,
+    StartResult,
+    StatusResult,
+    SupervisorContextResult,
+    WaitEventResult,
+)
+
+# Public functions — organized by submodule for clarity
+from ._stack import derive_project_name, detect_stack
+from .context import load_supervisor_context
+from .dispatch import dispatch_todo
+from .lifecycle import (
+    get_report,
+    get_status,
+    init_project,
+    list_orphans,
+    remove_orphans,
+    reset_runtime,
+)
+from .model_check import check_model_config
+from .pipeline import (
+    approve_commit,
+    continue_pipeline,
+    create_baseline,
+    kill_pipeline,
+    rollback,
+    start_pipeline,
+)
+from .planning import apply_increment_plan
+from .roles import add_role, analyze_roles
+from .setup import apply_project_setup
+from .wait_event import wait_for_event
+
+__all__ = [
+    # Exception
+    "AwfApiError",
+    # Result dataclasses
+    "InitResult",
+    "StatusResult",
+    "BaselineResult",
+    "RollbackResult",
+    "ApproveResult",
+    "ReportResult",
+    "ResetResult",
+    "AddRoleResult",
+    "StartResult",
+    "AnalyzeRolesResult",
+    "ApplyProjectSetupResult",
+    "DispatchTodoResult",
+    "SupervisorContextResult",
+    "ApplyIncrementPlanResult",
+    "WaitEventResult",
+    # Stack detection
+    "detect_stack",
+    "derive_project_name",
+    # Lifecycle
+    "init_project",
+    "get_status",
+    "get_report",
+    "reset_runtime",
+    "list_orphans",
+    "remove_orphans",
+    # Pipeline
+    "start_pipeline",
+    "continue_pipeline",
+    "kill_pipeline",
+    "create_baseline",
+    "rollback",
+    "approve_commit",
+    # Roles
+    "add_role",
+    "analyze_roles",
+    # Project-setup materialization
+    "apply_project_setup",
+    # TODO dispatch + supervisor context (dogfood-2 automation)
+    "dispatch_todo",
+    "load_supervisor_context",
+    # Increment planning (dogfood-7 — user picks decomposition variant)
+    "apply_increment_plan",
+    # Supervisor wake-up (DASH Phase 3 — no more polling)
+    "wait_for_event",
+    # Model configuration validation
+    "check_model_config",
+]