agentic-devtools 0.2.332__py3-none-any.whl → 0.2.334__py3-none-any.whl

agentic_devtools/orchestration/nodes/initiate.py

@@ -0,0 +1,136 @@
+"""Initiate node: validate LLM config and detect issue provider.
+
+Entry point for the work-on-issue workflow. Validates that the LLM
+provider configuration exists and determines whether the issue is
+from Jira or GitHub based on the key format.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agentic_devtools.orchestration.nodes._helpers import detect_issue_provider, normalize_issue_key, utc_now
+from agentic_devtools.orchestration.state_schema import WorkOnIssueState
+
+
+def initiate_node(state: WorkOnIssueState) -> dict[str, Any]:
+    """Validate LLM config and detect issue provider.
+
+    Reads the issue key from state, detects the provider (Jira vs GitHub),
+    validates that an LLM provider is configured, and sets routing signals.
+
+    Fails fast with ``ProviderNotConfiguredError`` info in the error field
+    if no LLM provider configuration is found.
+    """
+    issue_key = state.get("issue_key", "")
+
+    # Fail fast when issue_key is missing, blank, or not a string — downstream
+    # nodes (retrieve, pull_request, completion) all require a valid key, and
+    # detect_issue_provider("") silently returns "github" which produces
+    # confusing failures later.
+    if not isinstance(issue_key, str) or not issue_key.strip():
+        _missing_error = "issue_key is required and must be a non-empty string"
+        return {
+            "step": "initiate",
+            "status": "failed",
+            "error": _missing_error,
+            "events": [
+                {
+                    "event": "initiate_failed",
+                    "timestamp": utc_now(),
+                    "signals": {"error": "missing_issue_key"},
+                }
+            ],
+        }
+
+    normalized_key = normalize_issue_key(issue_key)
+    if not normalized_key:
+        invalid_error = "issue_key must normalize to a non-empty issue identifier"
+        return {
+            "step": "initiate",
+            "status": "failed",
+            "error": invalid_error,
+            "events": [
+                {
+                    "event": "initiate_failed",
+                    "timestamp": utc_now(),
+                    "signals": {"error": "invalid_issue_key"},
+                }
+            ],
+        }
+
+    # Detect issue provider from key format
+    issue_provider = detect_issue_provider(issue_key)
+
+    # Validate LLM configuration exists
+    llm_config_error = _validate_llm_config()
+    if llm_config_error:
+        return {
+            "step": "initiate",
+            "status": "failed",
+            "error": llm_config_error,
+            "issue_provider": issue_provider,
+            "events": [
+                {
+                    "event": "initiate_failed",
+                    "timestamp": utc_now(),
+                    "signals": {"error": llm_config_error},
+                }
+            ],
+        }
+
+    # Translate any pre-flight error (e.g., wrong worktree/branch) into the
+    # ``needs_setup`` routing signal. ``issue_retrieved`` is intentionally NOT set
+    # here: it means "the issue was actually fetched" and is set solely by
+    # ``retrieve_node`` (and read by ``route_after_retrieve``). Setting it in this
+    # node would overload the signal with a second meaning ("pre-flight OK").
+    # ``route_after_initiate`` always proceeds to ``setup`` when there is no error.
+    pre_flight_error = state.get("error")
+    needs_setup = bool(pre_flight_error)
+
+    # Include the original pre-flight error detail in signals to aid diagnostics
+    # when reviewing workflow events / checkpoints. Only include when it is a
+    # non-empty string; truthy non-string values (e.g. dicts from corrupted state)
+    # are omitted to keep the signal payload consistent.
+    signals: dict[str, Any] = {
+        "needs_setup": needs_setup,
+        "issue_provider": issue_provider,
+    }
+    if isinstance(pre_flight_error, str) and pre_flight_error:
+        signals["pre_flight_error_detail"] = pre_flight_error
+
+    return {
+        "step": "initiate",
+        "status": "active",
+        "error": None,
+        "issue_provider": issue_provider,
+        "needs_setup": needs_setup,
+        "events": [
+            {
+                "event": "initiate_completed",
+                "timestamp": utc_now(),
+                "signals": signals,
+            }
+        ],
+    }
+
+
+def _validate_llm_config() -> str | None:
+    """Validate LLM provider configuration exists.
+
+    Returns:
+        Error message string if configuration is invalid, None if valid.
+    """
+    try:
+        from agentic_devtools.orchestration.llm.config import load_config
+
+        config = load_config()
+        if not config.providers:
+            return (
+                "ProviderNotConfiguredError: No LLM providers configured in "
+                ".agdt/config/llm-providers.yml. Configure at least one provider "
+                "before running the workflow."
+            )
+        return None
+    except Exception as exc:
+        return f"ProviderNotConfiguredError: Failed to load LLM config: {exc}"

agentic_devtools/orchestration/nodes/planning.py

@@ -0,0 +1,221 @@
+"""Planning node: generate implementation plan via LLM.
+
+Calls the configured LLM provider to analyze the issue and generate
+a structured implementation plan. Includes blocked detection for
+ambiguous or under-specified issues.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from agentic_devtools.orchestration.execution.context_factory import _run_async
+from agentic_devtools.orchestration.nodes._helpers import _to_nonneg_int, utc_now
+from agentic_devtools.orchestration.state_schema import WorkOnIssueState
+
+_MIN_SUMMARY_LENGTH = 5
+_MIN_DESCRIPTION_LENGTH = 20
+
+
+def planning_node(state: WorkOnIssueState) -> dict[str, Any]:
+    """Generate implementation plan using LLM.
+
+    Builds a system prompt with issue context, calls the LLM for
+    structured output, and evaluates whether the issue is clear enough
+    to proceed. If blocked, sets ``blocked_reason`` and routes to error.
+    Fails fast when ``issue_key`` is absent, blank, or not a string.
+    """
+    raw_issue_key = state.get("issue_key")
+    if not isinstance(raw_issue_key, str) or not raw_issue_key.strip():
+        return {
+            "step": "planning",
+            "error": "issue_key is missing or blank; cannot generate implementation plan.",
+            "events": [
+                {
+                    "event": "planning_failed",
+                    "timestamp": utc_now(),
+                    "signals": {"error": "issue_key is missing or blank"},
+                }
+            ],
+        }
+    issue_key: str = raw_issue_key
+    issue_data = state.get("issue_data", {})
+    issue_data_dict = issue_data if isinstance(issue_data, dict) else {}
+
+    # Build context for LLM; coerce to str so _check_blocked can safely call
+    # .strip() even when issue_data carries None or an ADF dict (Jira Cloud).
+    raw_summary = issue_data_dict.get("summary")
+    raw_description = issue_data_dict.get("description")
+    summary = raw_summary if isinstance(raw_summary, str) else ""
+    description = raw_description if isinstance(raw_description, str) else ""
+
+    # Check for obviously blocked issues (empty or trivial)
+    blocked_reason = _check_blocked(summary, description)
+    if blocked_reason:
+        return {
+            "step": "planning",
+            "status": "blocked",
+            "error": blocked_reason,
+            "blocked_reason": blocked_reason,
+            "plan_posted": False,
+            "events": [
+                {
+                    "event": "planning_blocked",
+                    "timestamp": utc_now(),
+                    "signals": {"blocked_reason": blocked_reason},
+                }
+            ],
+        }
+
+    # Call LLM for plan generation
+    try:
+        plan_result = _generate_plan(issue_key, issue_data_dict)
+    except Exception as exc:
+        return {
+            "step": "planning",
+            "error": f"Plan generation failed: {exc}",
+            "events": [
+                {
+                    "event": "planning_failed",
+                    "timestamp": utc_now(),
+                    "signals": {"error": str(exc)},
+                }
+            ],
+        }
+
+    # Check if LLM detected blocked state
+    if plan_result.get("is_blocked") is True:
+        raw_blocked = plan_result.get("blocked_reason", "")
+        blocked_reason = (
+            raw_blocked
+            if isinstance(raw_blocked, str) and raw_blocked.strip()
+            else "Issue is too ambiguous for autonomous implementation"
+        )
+        return {
+            "step": "planning",
+            "status": "blocked",
+            "error": blocked_reason,
+            "blocked_reason": blocked_reason,
+            "plan_posted": False,
+            "events": [
+                {
+                    "event": "planning_blocked",
+                    "timestamp": utc_now(),
+                    "signals": {"blocked_reason": blocked_reason},
+                }
+            ],
+        }
+
+    raw_plan = plan_result.get("plan", "")
+    plan_text = raw_plan if isinstance(raw_plan, str) else ""
+    raw_token_usage = plan_result.get("token_usage", {})
+    token_usage = raw_token_usage if isinstance(raw_token_usage, dict) else {}
+
+    return {
+        "step": "planning",
+        "status": "active",
+        "error": None,
+        "blocked_reason": None,
+        "plan": plan_text,
+        "plan_posted": True,
+        "token_usage_prompt": _to_nonneg_int(state.get("token_usage_prompt"))
+        + _to_nonneg_int(token_usage.get("prompt_tokens")),
+        "token_usage_completion": _to_nonneg_int(state.get("token_usage_completion"))
+        + _to_nonneg_int(token_usage.get("completion_tokens")),
+        "events": [
+            {
+                "event": "planning_completed",
+                "timestamp": utc_now(),
+                "signals": {"plan_posted": True},
+            }
+        ],
+    }
+
+
+def _check_blocked(summary: str, description: str) -> str | None:
+    """Check for obviously under-specified issues.
+
+    Returns a blocked reason string if the issue lacks sufficient detail,
+    or None if the issue appears actionable.
+    """
+    if not summary or len(summary.strip()) < _MIN_SUMMARY_LENGTH:
+        return "Issue summary is empty or too short (less than 5 characters). Cannot generate implementation plan."
+
+    if not description or len(description.strip()) < _MIN_DESCRIPTION_LENGTH:
+        return (
+            "Issue description is empty or too brief (less than 20 characters). "
+            "Insufficient context for autonomous implementation."
+        )
+
+    return None
+
+
+def _generate_plan(issue_key: str, issue_data: dict[str, Any]) -> dict[str, Any]:
+    """Generate implementation plan via LLM provider.
+
+    Returns dict with keys: plan, is_blocked, blocked_reason, token_usage.
+    """
+    from agentic_devtools.orchestration.llm.factory import ProviderFactory
+
+    factory = ProviderFactory()
+    provider = factory.get_provider("planning", "work_on_issue")
+
+    raw_summary = issue_data.get("summary")
+    raw_description = issue_data.get("description")
+    summary = raw_summary if isinstance(raw_summary, str) else ""
+    description = raw_description if isinstance(raw_description, str) else ""
+
+    system_prompt = (
+        "You are an implementation planning assistant. Given an issue description, "
+        "generate a structured implementation plan. If the issue is too vague or "
+        "contradictory to implement autonomously, respond with is_blocked=true.\n\n"
+        "Respond with a JSON object containing:\n"
+        '- "is_blocked": boolean (true if issue is too ambiguous)\n'
+        '- "blocked_reason": string (explanation if blocked, empty otherwise)\n'
+        '- "missing_information": list of strings (what info is needed if blocked)\n'
+        '- "plan": string (implementation plan if not blocked)\n'
+        '- "tasks": list of task descriptions\n'
+    )
+
+    user_prompt = f"Issue Key: {issue_key}\nSummary: {summary}\n\nDescription:\n{description}"
+
+    async def _call_llm():
+        from agentic_devtools.orchestration.llm.types import LLMMessage
+
+        messages = [
+            LLMMessage(role="system", content=system_prompt),
+            LLMMessage(role="user", content=user_prompt),
+        ]
+        response = await provider.complete(messages)
+        return response
+
+    response = _run_async(_call_llm())
+
+    # Parse response
+    token_usage = {}
+    if response.usage:
+        token_usage = {
+            "prompt_tokens": response.usage.input_tokens,
+            "completion_tokens": response.usage.output_tokens,
+        }
+
+    # Try to parse structured response
+    try:
+        parsed = json.loads(response.text)
+        if isinstance(parsed, dict):
+            return {
+                "plan": parsed.get("plan", response.text),
+                "is_blocked": parsed.get("is_blocked", False),
+                "blocked_reason": parsed.get("blocked_reason", ""),
+                "token_usage": token_usage,
+            }
+    except (json.JSONDecodeError, TypeError):
+        pass
+    # If response isn't valid JSON, or parsed to a non-dict type, treat it as the plan text
+    return {
+        "plan": response.text,
+        "is_blocked": False,
+        "blocked_reason": "",
+        "token_usage": token_usage,
+    }

agentic_devtools/orchestration/nodes/pull_request.py

@@ -0,0 +1,256 @@
+"""Pull request node: create PR on the appropriate platform.
+
+Detects the platform (Azure DevOps vs GitHub) from the ``issue_provider``
+state field and creates a draft pull request with appropriate metadata.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from agentic_devtools.orchestration.nodes._helpers import (
+    detect_issue_provider,
+    normalize_issue_key,
+    run_command,
+    utc_now,
+)
+from agentic_devtools.orchestration.state_schema import WorkOnIssueState
+
+
+def pull_request_node(state: WorkOnIssueState) -> dict[str, Any]:
+    """Create pull request on the appropriate platform.
+
+    Uses ``issue_provider`` when it is ``"github"``/``"jira"``, otherwise derives
+    the platform from ``issue_key`` (GitHub numeric/#N vs Jira PROJECT-N).
+    Creates as draft by default.
+
+    Fails fast when ``issue_key`` is missing, blank, or not a string so a
+    corrupted/resumed checkpoint cannot raise ``AttributeError`` inside
+    ``detect_issue_provider()`` or ``normalize_issue_key()``, or silently
+    build a PR title with an empty scope.
+    """
+    issue_key = state.get("issue_key", "")
+    if not isinstance(issue_key, str) or not issue_key.strip():
+        return {
+            "step": "pull_request",
+            "error": "issue_key is required and must be a non-empty string",
+            "events": [
+                {
+                    "event": "pull_request_failed",
+                    "timestamp": utc_now(),
+                    "signals": {"error": "missing_issue_key"},
+                }
+            ],
+        }
+    raw_issue_provider = state.get("issue_provider")
+    issue_provider = (
+        raw_issue_provider
+        if isinstance(raw_issue_provider, str) and raw_issue_provider in {"jira", "github"}
+        else detect_issue_provider(issue_key)
+    )
+    normalized_key = normalize_issue_key(issue_key)
+    if not normalized_key:
+        return {
+            "step": "pull_request",
+            "error": "issue_key must normalize to a non-empty issue identifier",
+            "events": [
+                {
+                    "event": "pull_request_failed",
+                    "timestamp": utc_now(),
+                    "signals": {"error": "invalid_issue_key"},
+                }
+            ],
+        }
+    plan = state.get("plan", "")
+    issue_data = state.get("issue_data", {})
+
+    # Generate PR title and description
+    pr_title = _generate_pr_title(normalized_key, issue_data)
+    pr_description = _generate_pr_description(normalized_key, plan, issue_data)
+
+    # Get current branch — fail fast if git cannot determine it
+    branch_result = run_command(["git", "rev-parse", "--abbrev-ref", "HEAD"])
+    if branch_result.returncode != 0:
+        error_detail = branch_result.stderr.strip() or "Unable to determine current branch"
+        return {
+            "step": "pull_request",
+            "error": f"Cannot create PR: failed to determine current branch: {error_detail}",
+            "events": [
+                {
+                    "event": "pull_request_failed",
+                    "timestamp": utc_now(),
+                    "signals": {"error": "branch_detection_failed"},
+                }
+            ],
+        }
+    source_branch = branch_result.stdout.strip()
+    if not source_branch:
+        return {
+            "step": "pull_request",
+            "error": "Cannot create PR: failed to determine current branch: Unable to determine current branch",
+            "events": [
+                {
+                    "event": "pull_request_failed",
+                    "timestamp": utc_now(),
+                    "signals": {"error": "branch_detection_failed"},
+                }
+            ],
+        }
+
+    # Create PR based on platform
+    if issue_provider == "github":
+        result = _create_github_pr(pr_title, pr_description)
+    else:
+        result = _create_azure_devops_pr(pr_title, pr_description, source_branch)
+
+    if result.get("error"):
+        return {
+            "step": "pull_request",
+            "error": result["error"],
+            "pr_title": pr_title,
+            "events": [
+                {
+                    "event": "pull_request_failed",
+                    "timestamp": utc_now(),
+                    "signals": {"error": result["error"]},
+                }
+            ],
+        }
+
+    return {
+        "step": "pull_request",
+        "error": None,
+        "pr_created": True,
+        "pr_url": result.get("url", ""),
+        "pr_title": pr_title,
+        "events": [
+            {
+                "event": "pull_request_completed",
+                "timestamp": utc_now(),
+                "signals": {"pr_created": True, "pr_url": result.get("url", "")},
+            }
+        ],
+    }
+
+
+def _create_github_pr(title: str, description: str) -> dict[str, Any]:
+    """Create a GitHub PR via agdt-gh-create-pull-request."""
+    set_result = run_command(["agdt-set", "target_branch", "main"])
+    if set_result.returncode != 0:
+        return {"error": f"Failed to set 'target_branch' state before PR creation: {set_result.stderr.strip()}"}
+
+    set_result = run_command(["agdt-set", "draft", "true"])
+    if set_result.returncode != 0:
+        return {"error": f"Failed to set 'draft' state before PR creation: {set_result.stderr.strip()}"}
+
+    result = run_command(
+        [
+            "agdt-gh-create-pull-request",
+            "--title",
+            title,
+            "--body",
+            description,
+        ],
+        timeout=120,
+    )
+
+    if result.returncode != 0:
+        return {"error": f"GitHub PR creation failed: {result.stderr.strip()}"}
+
+    # Try to extract PR URL from output
+    url = ""
+    for line in result.stdout.splitlines():
+        match = re.search(r"https://github\.com/\S+/pull/\d+", line)
+        if match:
+            url = match.group(0)
+            break
+
+    return {"url": url}
+
+
+def _create_azure_devops_pr(title: str, description: str, source_branch: str) -> dict[str, Any]:
+    """Create an Azure DevOps PR via agdt-create-pull-request."""
+    # Set state values for the command; any failure is a hard prerequisite error
+    set_cmds = [
+        ["agdt-set", "source_branch", source_branch],
+        ["agdt-set", "target_branch", "main"],
+        ["agdt-set", "title", title],
+        ["agdt-set", "description", description],
+        ["agdt-set", "draft", "true"],
+    ]
+    for cmd in set_cmds:
+        set_result = run_command(cmd)
+        if set_result.returncode != 0:
+            key = cmd[1]
+            return {"error": f"Failed to set '{key}' state before PR creation: {set_result.stderr.strip()}"}
+
+    result = run_command(["agdt-create-pull-request"], timeout=120)
+    if result.returncode != 0:
+        return {"error": f"Azure DevOps PR creation failed: {result.stderr.strip()}"}
+
+    # Wait for background task
+    wait_result = run_command(["agdt-task-wait"], timeout=120)
+    if wait_result.returncode != 0:
+        return {"error": f"PR creation task wait failed: {wait_result.stderr.strip()}"}
+
+    # Extract PR URL from task log output (agdt-create-pull-request prints "PR URL: <url>")
+    url = ""
+    log_result = run_command(["agdt-task-log"])
+    if log_result.returncode == 0:
+        for line in log_result.stdout.splitlines():
+            stripped = line.strip()
+            if stripped.startswith("PR URL: "):
+                url = stripped[len("PR URL: ") :]
+                break
+
+    return {"url": url}
+
+
+def _generate_pr_title(issue_key: str, issue_data: Any) -> str:
+    """Generate PR title from issue data."""
+    summary = ""
+    if isinstance(issue_data, dict):
+        raw_summary = issue_data.get("summary", "")
+        if isinstance(raw_summary, str):
+            summary = raw_summary
+
+    if not summary:
+        summary = "autonomous implementation"
+
+    normalized = issue_key.lstrip("#")
+    if normalized.isdigit():
+        scope = f"#{normalized}"
+    else:
+        scope = normalized
+
+    title = f"feat({scope}): {summary}"
+    if len(title) > 72:
+        title = title[:69] + "..."
+    return title
+
+
+def _generate_pr_description(issue_key: str, plan: str, issue_data: Any) -> str:
+    """Generate PR description."""
+    summary = ""
+    if isinstance(issue_data, dict):
+        raw_summary = issue_data.get("summary", "")
+        if isinstance(raw_summary, str):
+            summary = raw_summary
+
+    if not isinstance(plan, str):
+        plan = ""
+
+    description_parts = [
+        f"## Summary\n\nAutonomous implementation for issue {issue_key}.",
+    ]
+
+    if summary:
+        description_parts.append(f"\n**Issue**: {summary}")
+
+    if plan:
+        plan_preview = plan[:500]
+        description_parts.append(f"\n## Implementation Plan\n\n{plan_preview}")
+
+    description_parts.append("\n---\n*Generated by LangChain work-on-issue workflow*")
+    return "\n".join(description_parts)