agent-devkit 0.1.5 → 0.2.0

package/runtime/cli/aikit/collaboration.py

@@ -0,0 +1,359 @@
+"""Structured multi-agent collaboration helpers."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cli.aikit.memory import redact_secrets
+
+
+COLLABORATION_SCHEMA_VERSION = "ai-devkit.collaboration/v1"
+TASK_ROLES = {"collector", "analyzer", "reviewer", "coordinator"}
+TEXT_PREVIEW_LIMIT = 600
+
+
+def normalize_collaborative_task(
+    task: dict[str, Any],
+    *,
+    role: str | None = None,
+    depends_on: list[str] | None = None,
+    sequence: int | None = None,
+) -> dict[str, Any]:
+    item = dict(task)
+    task_id = str(item.get("task_id") or item.get("id") or "").strip()
+    item["task_id"] = task_id
+    item["role"] = normalize_role(role or item.get("role"))
+    item["depends_on"] = normalize_depends_on(depends_on if depends_on is not None else item.get("depends_on"))
+    item["handoff"] = normalize_handoff(item.get("handoff"))
+    item["critical"] = item.get("primary") is True or item.get("critical") is True
+    item["parallel_safe"] = item.get("parallel_safe") is True
+    if sequence is not None:
+        item["sequence"] = sequence
+    return item
+
+
+def normalize_role(value: Any) -> str:
+    role = str(value or "").strip()
+    return role if role in TASK_ROLES else "analyzer"
+
+
+def normalize_depends_on(value: Any) -> list[str]:
+    if not isinstance(value, list):
+        return []
+    return [str(item).strip() for item in value if str(item).strip()]
+
+
+def normalize_handoff(value: Any) -> dict[str, Any]:
+    if isinstance(value, dict):
+        return {
+            "produces": normalize_string_list(value.get("produces")),
+            "consumes": normalize_string_list(value.get("consumes")),
+            "summary": str(value.get("summary") or "").strip(),
+        }
+    return {"produces": [], "consumes": [], "summary": ""}
+
+
+def normalize_string_list(value: Any) -> list[str]:
+    if not isinstance(value, list):
+        return []
+    return [str(item).strip() for item in value if str(item).strip()]
+
+
+def initial_shared_context(prompt: str, routing_decision: dict[str, Any] | None) -> dict[str, Any]:
+    routing = routing_decision if isinstance(routing_decision, dict) else {}
+    confidence_label = str(routing.get("confidence_label") or "").strip()
+    human_escalations = []
+    if routing.get("requires_confirmation"):
+        human_escalations.append(
+            human_escalation(
+                reason=str(routing.get("reason") or "Routing requires confirmation."),
+                source="task-orchestrator",
+                kind="routing-confirmation",
+                confidence=confidence_label or "low",
+            )
+        )
+    return {
+        "schema_version": COLLABORATION_SCHEMA_VERSION,
+        "facts": [
+            {
+                "source": "task-orchestrator",
+                "kind": "prompt",
+                "summary": preview_text(prompt),
+            }
+        ],
+        "inferences": [
+            {
+                "source": "task-orchestrator",
+                "kind": "routing",
+                "status": routing.get("status"),
+                "selected_agent_id": routing.get("selected_agent_id"),
+                "selected_capability_id": routing.get("selected_capability_id"),
+                "confidence": routing.get("confidence"),
+            }
+        ]
+        if routing
+        else [],
+        "artifacts": [],
+        "blockers": [],
+        "decisions": [],
+        "risks": [],
+        "questions": [],
+        "handoffs": [],
+        "conflicts": [],
+        "human_escalations": human_escalations,
+    }
+
+
+def build_collaboration_graph(
+    specialist_tasks: list[dict[str, Any]],
+    configuration_tasks: list[dict[str, Any]],
+    review_task: dict[str, Any] | None,
+) -> dict[str, Any]:
+    nodes = []
+    edges = []
+    all_tasks = [*specialist_tasks, *configuration_tasks]
+    if review_task:
+        all_tasks.append(review_task)
+    for task in all_tasks:
+        if not isinstance(task, dict):
+            continue
+        task_id = str(task.get("task_id") or task.get("id") or "")
+        if not task_id:
+            continue
+        nodes.append(
+            {
+                "task_id": task_id,
+                "agent_id": task.get("agent_id"),
+                "capability_id": task.get("capability_id"),
+                "role": normalize_role(task.get("role")),
+                "status": task.get("status"),
+                "parallel_safe": task.get("parallel_safe") is True,
+            }
+        )
+        for dependency in normalize_depends_on(task.get("depends_on")):
+            edges.append({"from": dependency, "to": task_id, "type": "depends_on"})
+    return {
+        "schema_version": COLLABORATION_SCHEMA_VERSION,
+        "nodes": nodes,
+        "edges": edges,
+        "parallel_groups": parallel_groups(nodes, edges),
+    }
+
+
+def parallel_groups(nodes: list[dict[str, Any]], edges: list[dict[str, Any]]) -> list[list[str]]:
+    blocked = {str(edge.get("to")) for edge in edges if edge.get("to")}
+    group = [
+        str(node["task_id"])
+        for node in nodes
+        if node.get("parallel_safe") is True and str(node.get("task_id") or "") not in blocked
+    ]
+    return [group] if len(group) > 1 else []
+
+
+def collaborative_task_sequence(plan: dict[str, Any]) -> list[dict[str, Any]]:
+    tasks = [task for task in plan.get("specialist_tasks") or [] if isinstance(task, dict)]
+    if not plan.get("collaboration_enabled"):
+        return [task for task in tasks if task.get("primary")]
+    return dependency_order(tasks)
+
+
+def dependency_order(tasks: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    by_id = {str(task.get("task_id") or task.get("id")): task for task in tasks if task.get("task_id") or task.get("id")}
+    ordered: list[dict[str, Any]] = []
+    remaining = dict(by_id)
+    while remaining:
+        progressed = False
+        for task_id, task in list(remaining.items()):
+            dependencies = normalize_depends_on(task.get("depends_on"))
+            if all(dependency not in remaining for dependency in dependencies):
+                ordered.append(task)
+                remaining.pop(task_id)
+                progressed = True
+        if not progressed:
+            ordered.extend(remaining.values())
+            break
+    return sorted(ordered, key=lambda task: int(task.get("sequence") or 0))
+
+
+def blocked_dependency(task: dict[str, Any], completed: set[str], failed: set[str]) -> str | None:
+    dependencies = normalize_depends_on(task.get("depends_on"))
+    failed_dependencies = [dependency for dependency in dependencies if dependency in failed]
+    if failed_dependencies:
+        return f"Task dependency failed: {', '.join(failed_dependencies)}."
+    missing = [dependency for dependency in dependencies if dependency not in completed]
+    if missing:
+        return f"Task dependency not completed: {', '.join(missing)}."
+    return None
+
+
+def merge_task_handoff(shared_context: dict[str, Any], task: dict[str, Any], result: dict[str, Any]) -> dict[str, Any]:
+    context = normalize_shared_context(shared_context)
+    handoff = summarize_handoff(task, result)
+    if handoff.get("fact"):
+        context["facts"].append(handoff["fact"])
+    if handoff.get("artifact"):
+        context["artifacts"].append(handoff["artifact"])
+    if handoff.get("blocker"):
+        context["blockers"].append(handoff["blocker"])
+    for risk in handoff.get("risks") or []:
+        context["risks"].append(risk)
+    for question in handoff.get("questions") or []:
+        context["questions"].append(question)
+    context["handoffs"].append(build_handoff(task, None, result, handoff=handoff))
+    if handoff.get("blocker"):
+        context["conflicts"].append(
+            conflict(
+                source=task.get("task_id") or task.get("id"),
+                kind="blocked-task",
+                summary=str(handoff["blocker"].get("reason") or "Task blocked."),
+                evidence=[task.get("agent_id"), task.get("capability_id")],
+                severity="high" if result.get("status") == "blocked" else "medium",
+            )
+        )
+        context["human_escalations"].append(
+            human_escalation(
+                reason=str(handoff["blocker"].get("reason") or "Task requires human decision."),
+                source=task.get("task_id") or task.get("id"),
+                kind="blocked-task",
+                confidence="low",
+            )
+        )
+    context["decisions"].append(
+        {
+            "source": task.get("task_id") or task.get("id"),
+            "agent_id": task.get("agent_id"),
+            "status": result.get("status"),
+            "ok": bool(result.get("ok")),
+        }
+    )
+    return context
+
+
+def normalize_shared_context(value: Any) -> dict[str, Any]:
+    if isinstance(value, dict):
+        context = dict(value)
+    else:
+        context = {}
+    context.setdefault("schema_version", COLLABORATION_SCHEMA_VERSION)
+    for key in (
+        "facts",
+        "inferences",
+        "artifacts",
+        "blockers",
+        "decisions",
+        "risks",
+        "questions",
+        "handoffs",
+        "conflicts",
+        "human_escalations",
+    ):
+        if not isinstance(context.get(key), list):
+            context[key] = []
+    return context
+
+
+def summarize_handoff(task: dict[str, Any], result: dict[str, Any]) -> dict[str, Any]:
+    source = task.get("task_id") or task.get("id")
+    summary = preview_text(result.get("message") or result.get("response") or result.get("stdout") or result.get("error") or result.get("reason") or "")
+    handoff: dict[str, Any] = {
+        "fact": {
+            "source": source,
+            "agent_id": task.get("agent_id"),
+            "capability_id": task.get("capability_id"),
+            "status": result.get("status"),
+            "summary": summary,
+        }
+    }
+    artifacts = result.get("artifacts")
+    if isinstance(artifacts, list) and artifacts:
+        handoff["artifact"] = {
+            "source": source,
+            "items": [safe_artifact(item) for item in artifacts[:10]],
+        }
+    if not result.get("ok"):
+        handoff["blocker"] = {
+            "source": source,
+            "reason": preview_text(result.get("reason") or result.get("error") or "Task did not complete successfully."),
+        }
+    risks = result.get("risks") if isinstance(result.get("risks"), list) else []
+    if risks:
+        handoff["risks"] = [{"source": source, "summary": preview_text(risk)} for risk in risks[:10]]
+    questions = result.get("questions") or result.get("next_questions")
+    if isinstance(questions, list) and questions:
+        handoff["questions"] = [{"source": source, "summary": preview_text(question)} for question in questions[:10]]
+    return handoff
+
+
+def build_handoff(
+    from_task: dict[str, Any],
+    to_task: dict[str, Any] | None,
+    result: dict[str, Any],
+    *,
+    handoff: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    summary = handoff or summarize_handoff(from_task, result)
+    return {
+        "from": str(from_task.get("agent_id") or ""),
+        "from_task_id": from_task.get("task_id") or from_task.get("id"),
+        "to": str((to_task or {}).get("agent_id") or "agent-devkit-core"),
+        "to_task_id": (to_task or {}).get("task_id") or (to_task or {}).get("id"),
+        "summary": ((summary.get("fact") or {}).get("summary") or ""),
+        "facts": [summary["fact"]] if summary.get("fact") else [],
+        "artifacts": [summary["artifact"]] if summary.get("artifact") else [],
+        "risks": list(summary.get("risks") or []),
+        "open_questions": list(summary.get("questions") or []),
+        "confidence": handoff_confidence(result),
+    }
+
+
+def conflict(
+    *,
+    source: Any,
+    kind: str,
+    summary: str,
+    evidence: list[Any] | None = None,
+    severity: str = "medium",
+) -> dict[str, Any]:
+    return {
+        "source": str(source or "unknown"),
+        "kind": kind,
+        "summary": preview_text(summary),
+        "evidence": [str(item) for item in evidence or [] if item],
+        "severity": severity if severity in {"low", "medium", "high"} else "medium",
+    }
+
+
+def human_escalation(*, reason: str, source: Any, kind: str, confidence: str = "low") -> dict[str, Any]:
+    return {
+        "source": str(source or "unknown"),
+        "kind": kind,
+        "reason": preview_text(reason),
+        "confidence": confidence if confidence in {"high", "medium", "low"} else "low",
+        "status": "waiting-for-user",
+    }
+
+
+def handoff_confidence(result: dict[str, Any]) -> str:
+    explicit = str(result.get("confidence") or "").strip().lower()
+    if explicit in {"high", "medium", "low"}:
+        return explicit
+    if result.get("ok"):
+        return "high"
+    if result.get("status") == "needs-input":
+        return "medium"
+    return "low"
+
+
+def safe_artifact(value: Any) -> Any:
+    if isinstance(value, dict):
+        return {str(key): preview_text(item) if isinstance(item, str) else item for key, item in value.items()}
+    if isinstance(value, str):
+        return preview_text(value)
+    return value
+
+
+def preview_text(value: Any, *, limit: int = TEXT_PREVIEW_LIMIT) -> str:
+    text = redact_secrets(str(value or "")).strip()
+    if len(text) <= limit:
+        return text
+    return text[: limit - 3].rstrip() + "..."

package/runtime/cli/aikit/configuration_orchestrator.py

@@ -44,7 +44,7 @@ def provider_setup_wizard(
         "reason": reason,
         "resume_prompt": prompt,
         "suggested_source_id": suggested_source_id if source_context else None,
-        "suggested_config": suggested_config(provider_id, suggested_project),
+        "suggested_config": suggested_config(provider, suggested_project),
         "next_question": next_question,
         "questions": questions,
         "credential_options": credential_options(provider),
@@ -107,19 +107,33 @@ def build_questions(
         if not name:
             continue
         suggested_value = suggested_value_for_field(provider, name, suggested_project)
-        questions.append(
-            {
-                "id": field_question_id(provider["id"], name),
-                "type": "text",
-                "text": question_text(provider, name, suggested_value=suggested_value),
-                "config_key": name,
-                "env": name,
-                "required": bool(field.get("required")),
-                "secret": bool(field.get("secret")),
-                "default": field.get("default"),
-                "suggested_value": suggested_value,
-            }
-        )
+        if field.get("secret") is True:
+            questions.append(
+                {
+                    "id": f"{field_question_id(provider['id'], name)}_env_ref",
+                    "type": "text",
+                    "text": f"Qual variavel de ambiente contem {name}?",
+                    "env_ref_key": name,
+                    "required": bool(field.get("required")),
+                    "secret": True,
+                    "stores_secret": False,
+                    "suggested_value": name,
+                }
+            )
+        else:
+            questions.append(
+                {
+                    "id": field_question_id(provider["id"], name),
+                    "type": "text",
+                    "text": question_text(provider, name, suggested_value=suggested_value),
+                    "config_key": name,
+                    "env": name,
+                    "required": bool(field.get("required")),
+                    "secret": False,
+                    "default": field.get("default"),
+                    "suggested_value": suggested_value,
+                }
+            )
     auth_methods = public_auth_methods(provider)
     if auth_methods:
         questions.append(
@@ -241,31 +255,43 @@ def credential_options(provider: dict[str, Any]) -> list[dict[str, Any]]:
     return unique
 
 
-def suggested_config(provider_id: str, suggested_project: str | None) -> dict[str, Any]:
+def suggested_config(provider: dict[str, Any], suggested_project: str | None) -> dict[str, Any]:
     config: dict[str, Any] = {}
-    if provider_id == "azure-devops" and suggested_project:
-        config["project"] = suggested_project
-        config["AZURE_DEVOPS_PROJECT"] = suggested_project
+    wizard = provider.get("wizard") if isinstance(provider.get("wizard"), dict) else {}
+    declared = wizard.get("suggested_config") if isinstance(wizard.get("suggested_config"), dict) else {}
+    for key, value in declared.items():
+        resolved = resolve_wizard_template(value, suggested_project=suggested_project)
+        if resolved is not None:
+            config[str(key)] = resolved
     return config
 
 
 def suggested_value_for_field(provider: dict[str, Any], name: str, suggested_project: str | None) -> str | None:
-    if provider.get("id") == "azure-devops" and name == "AZURE_DEVOPS_PROJECT" and suggested_project:
-        return suggested_project
-    return None
+    wizard = provider.get("wizard") if isinstance(provider.get("wizard"), dict) else {}
+    suggestions = wizard.get("field_suggestions") if isinstance(wizard.get("field_suggestions"), dict) else {}
+    return resolve_wizard_template(suggestions.get(name), suggested_project=suggested_project)
 
 
 def question_text(provider: dict[str, Any], name: str, *, suggested_value: str | None) -> str:
-    if provider.get("id") == "azure-devops" and name == "AZURE_DEVOPS_ORG":
-        return "Qual e a organizacao do Azure DevOps?"
-    if provider.get("id") == "azure-devops" and name == "AZURE_DEVOPS_PROJECT":
+    wizard = provider.get("wizard") if isinstance(provider.get("wizard"), dict) else {}
+    questions = wizard.get("questions") if isinstance(wizard.get("questions"), dict) else {}
+    if name in questions:
+        text = str(questions[name])
         if suggested_value:
-            return f'O projeto e "{suggested_value}"? Se nao, informe o nome correto.'
-        return "Qual e o nome do projeto no Azure DevOps?"
+            return f'{text} Valor sugerido: "{suggested_value}".'
+        return text
     label = name.replace("_", " ").lower()
     return f"Informe {label} para {provider.get('name') or provider.get('id')}."
 
 
+def resolve_wizard_template(value: Any, *, suggested_project: str | None) -> str | None:
+    if value == "prompt.project":
+        return suggested_project
+    if isinstance(value, str) and value:
+        return value
+    return None
+
+
 def field_question_id(provider_id: str, name: str) -> str:
     return f"{provider_slug(provider_id)}_{provider_slug(name)}"
 

package/runtime/cli/aikit/contribution.py

@@ -0,0 +1,105 @@
+"""Contribution preparation MVP for local Agent DevKit extensions."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+from cli.aikit.extensions import load_extensions
+
+
+CONTRIBUTION_SCHEMA_VERSION = "agent-devkit.contribution/v1"
+SECRET_PATTERN = re.compile(r"(token|secret|password|api[_-]?key|pat)\s*[:=]", re.IGNORECASE)
+PRIVATE_URL_PATTERN = re.compile(r"https?://(?:localhost|127\.0\.0\.1|10\.|192\.168\.|172\.(?:1[6-9]|2\d|3[0-1])\.)", re.IGNORECASE)
+LOCAL_PATH_PATTERN = re.compile(r"(/Users/|/home/|C:\\\\Users\\\\)")
+
+
+def contribution_list() -> dict[str, Any]:
+    extensions = load_extensions()["extensions"]
+    return {
+        "kind": "contributions",
+        "schema_version": CONTRIBUTION_SCHEMA_VERSION,
+        "status": "ok",
+        "items": [{"id": item.get("id"), "path": item.get("path"), "enabled": item.get("enabled") is True} for item in extensions],
+    }
+
+
+def contribution_checklist(extension_id: str) -> dict[str, Any]:
+    extension = find_extension(extension_id)
+    if not extension:
+        return {
+            "kind": "contribution-checklist",
+            "schema_version": CONTRIBUTION_SCHEMA_VERSION,
+            "status": "blocked",
+            "extension_id": extension_id,
+            "checks": [{"id": "extension-exists", "status": "failed"}],
+        }
+    checks = contribution_checks(Path(str(extension.get("path") or "")))
+    return {
+        "kind": "contribution-checklist",
+        "schema_version": CONTRIBUTION_SCHEMA_VERSION,
+        "status": "passed" if all(check["status"] == "passed" for check in checks) else "blocked",
+        "extension_id": extension_id,
+        "checks": checks,
+        "requires_human_confirmation_for_pr": True,
+    }
+
+
+def contribution_validate(extension_id: str) -> dict[str, Any]:
+    payload = contribution_checklist(extension_id)
+    payload["kind"] = "contribution-validation"
+    return payload
+
+
+def contribution_prepare(extension_id: str) -> dict[str, Any]:
+    checklist = contribution_checklist(extension_id)
+    return {
+        "kind": "contribution-prepare",
+        "schema_version": CONTRIBUTION_SCHEMA_VERSION,
+        "status": "planned" if checklist["status"] == "passed" else "blocked",
+        "extension_id": extension_id,
+        "checklist": checklist,
+        "creates_pr": False,
+    }
+
+
+def contribution_review(extension_id: str) -> dict[str, Any]:
+    checklist = contribution_checklist(extension_id)
+    return {
+        "kind": "contribution-review",
+        "schema_version": CONTRIBUTION_SCHEMA_VERSION,
+        "status": checklist["status"],
+        "extension_id": extension_id,
+        "findings": [check for check in checklist["checks"] if check["status"] != "passed"],
+    }
+
+
+def find_extension(extension_id: str) -> dict[str, Any] | None:
+    for item in load_extensions()["extensions"]:
+        if item.get("id") == extension_id:
+            return item
+    return None
+
+
+def contribution_checks(path: Path) -> list[dict[str, Any]]:
+    text = read_extension_text(path)
+    return [
+        {"id": "extension-exists", "status": "passed" if path.exists() else "failed"},
+        {"id": "no-secret-literals", "status": "failed" if SECRET_PATTERN.search(text) else "passed"},
+        {"id": "no-private-url", "status": "failed" if PRIVATE_URL_PATTERN.search(text) else "passed"},
+        {"id": "no-local-path", "status": "failed" if LOCAL_PATH_PATTERN.search(text) else "passed"},
+        {"id": "human-pr-confirmation", "status": "passed"},
+    ]
+
+
+def read_extension_text(path: Path) -> str:
+    if not path.exists():
+        return ""
+    if path.is_file():
+        return path.read_text(encoding="utf-8", errors="ignore")[:200_000]
+    chunks = []
+    for child in sorted(path.rglob("*")):
+        if child.is_file() and child.suffix in {".md", ".yaml", ".yml", ".json", ".py", ".sh", ".txt"}:
+            chunks.append(child.read_text(encoding="utf-8", errors="ignore")[:50_000])
+    return "\n".join(chunks)[:300_000]