agencode 0.1.0__py3-none-any.whl

agencli/agents/management_tools.py

@@ -0,0 +1,277 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from textwrap import shorten
+from typing import TYPE_CHECKING
+
+from langchain_core.tools import tool
+
+from agencli.agents.registry import AgentRegistry
+from agencli.core.config import AgenCLIConfig
+from agencli.skills.cli_backend import (
+    check_skills,
+    find_skills,
+    install_skill_cli,
+    list_installed_skills_cli,
+    render_command,
+    update_skills,
+)
+from agencli.skills.manager import install_skill as install_local_skill, list_installed_skills as list_local_skills
+
+if TYPE_CHECKING:
+    from agencli.agents.factory import AgentSpec
+
+
+def build_supervisor_management_tools(config: AgenCLIConfig) -> list:
+    registry = AgentRegistry(config.agents_dir)
+
+    @tool("list_saved_subagents")
+    def list_saved_subagents() -> str:
+        """List saved user-managed subagents and which ones are active under the supervisor."""
+        active = set(registry.load_active_names())
+        items = []
+        for name in registry.list_agents():
+            spec = registry.load(name)
+            items.append(
+                {
+                    "name": spec.name,
+                    "description": spec.description,
+                    "skills": list(spec.skills),
+                    "active": spec.name in active,
+                }
+            )
+        return json.dumps({"active_names": sorted(active), "subagents": items}, indent=2)
+
+    @tool("get_saved_subagent")
+    def get_saved_subagent(name: str) -> str:
+        """Load one saved subagent by name, including its prompt and attached skills."""
+        spec = registry.load(name.strip())
+        return json.dumps(_spec_payload(spec, active_names=registry.load_active_names()), indent=2)
+
+    @tool("save_subagent")
+    def save_subagent(
+        name: str,
+        system_prompt: str,
+        description: str = "",
+        skills: list[str] | None = None,
+        activate: bool = False,
+    ) -> str:
+        """Create or update a saved subagent with the given prompt and attached skill names."""
+        cleaned_name = name.strip()
+        cleaned_prompt = system_prompt.strip()
+        if not cleaned_name:
+            raise ValueError("Subagent name cannot be empty.")
+        if not cleaned_prompt:
+            raise ValueError("Subagent system prompt cannot be empty.")
+        from agencli.agents.factory import AgentSpec
+
+        existing = registry.load(cleaned_name) if cleaned_name in registry.list_agents() else None
+        spec = AgentSpec(
+            name=cleaned_name,
+            model=(existing.model if existing is not None else config.default_model),
+            system_prompt=cleaned_prompt,
+            description=description.strip() or (existing.description if existing is not None else _derive_description(cleaned_prompt)),
+            skills=sorted(dict.fromkeys(skills or (existing.skills if existing is not None else []))),
+            subagents=list(existing.subagents) if existing is not None else [],
+            mcp_servers=list(existing.mcp_servers) if existing is not None else [],
+            workspace_dir=(existing.workspace_dir if existing is not None else config.workspace_dir),
+        )
+        path = registry.save(spec)
+        active_names = set(registry.load_active_names())
+        if activate:
+            active_names.add(cleaned_name)
+            registry.save_active_names(sorted(active_names))
+        return json.dumps(
+            {
+                "saved": cleaned_name,
+                "path": str(path),
+                "active": cleaned_name in set(registry.load_active_names()),
+                "skills": spec.skills,
+            },
+            indent=2,
+        )
+
+    @tool("delete_subagent")
+    def delete_subagent(name: str) -> str:
+        """Delete a saved subagent and remove it from the supervisor active set."""
+        path = registry.delete(name.strip())
+        return json.dumps({"deleted": name.strip(), "path": str(path)}, indent=2)
+
+    @tool("set_active_subagents")
+    def set_active_subagents(names: list[str]) -> str:
+        """Replace the supervisor active subagent list with the provided saved subagent names."""
+        wanted = sorted({item.strip() for item in names if item and item.strip()})
+        existing = set(registry.list_agents())
+        missing = [name for name in wanted if name not in existing]
+        if missing:
+            raise ValueError(f"Unknown saved subagent(s): {', '.join(missing)}")
+        registry.save_active_names(wanted)
+        return json.dumps({"active_names": wanted}, indent=2)
+
+    @tool("list_attachable_skills")
+    def list_attachable_skills() -> str:
+        """List skills that can be attached to subagents, including local and Skills CLI installed skills."""
+        local = [
+            {
+                "name": skill.name,
+                "description": skill.description,
+                "source": str(skill.path),
+                "kind": "local",
+            }
+            for skill in list_local_skills(config.skills_dir)
+        ]
+        try:
+            _result, installed = list_installed_skills_cli(workspace_dir=config.workspace_dir)
+        except Exception as exc:
+            installed = []
+            local.append(
+                {
+                    "name": "warning",
+                    "description": f"Unable to query Skills CLI installed state: {exc}",
+                    "source": "skills-cli",
+                    "kind": "warning",
+                }
+            )
+        merged = {item["name"]: item for item in local}
+        for record in installed:
+            merged.setdefault(
+                record.name,
+                {
+                    "name": record.name,
+                    "description": record.details,
+                    "source": record.source or "skills-cli",
+                    "kind": f"installed:{record.scope or 'unknown'}",
+                },
+            )
+        return json.dumps({"skills": [merged[name] for name in sorted(merged)]}, indent=2)
+
+    @tool("search_marketplace_skills")
+    def search_marketplace_skills(query: str, limit: int = 8) -> str:
+        """Search the Skills marketplace with `npx skills find` and return the strongest matching skills."""
+        result, items = find_skills(query, workspace_dir=config.workspace_dir)
+        payload = {
+            "command": render_command(result.argv),
+            "ok": result.ok,
+            "results": [
+                {
+                    "name": item.name,
+                    "source": item.source,
+                    "skill_name": item.skill_name,
+                    "skills_page_url": item.skills_page_url,
+                    "github_repo_url": item.github_repo_url,
+                    "install_count": item.install_count_text,
+                    "description": item.description,
+                    "trust": list(item.quality.labels),
+                    "install_command": render_command(item.install_command) if item.install_command else None,
+                }
+                for item in items[: max(1, limit)]
+            ],
+        }
+        return json.dumps(payload, indent=2)
+
+    @tool("install_marketplace_skill")
+    def install_marketplace_skill(source: str, skill_name: str = "", global_install: bool = True, yes: bool = True) -> str:
+        """Install a skill through the Skills CLI and sync it into the local attachable skill library when possible."""
+        result = install_skill_cli(
+            source,
+            workspace_dir=config.workspace_dir,
+            skill_name=skill_name.strip() or None,
+            global_install=global_install,
+            yes=yes,
+        )
+        imported = None
+        if result.ok and skill_name.strip():
+            imported = _sync_installed_skill_into_local_library(config, skill_name.strip())
+        return json.dumps(
+            {
+                "command": render_command(result.argv),
+                "ok": result.ok,
+                "imported_local_skill": imported,
+                "stdout": result.stdout.strip(),
+                "stderr": result.stderr.strip(),
+                "error": result.error_summary,
+            },
+            indent=2,
+        )
+
+    @tool("check_skill_updates")
+    def check_skill_updates() -> str:
+        """Check for updates to installed marketplace skills."""
+        result, status = check_skills(workspace_dir=config.workspace_dir)
+        return json.dumps(
+            {
+                "command": render_command(result.argv),
+                "ok": result.ok,
+                "summary": status.summary,
+                "items": status.items,
+            },
+            indent=2,
+        )
+
+    @tool("update_marketplace_skills")
+    def update_marketplace_skills() -> str:
+        """Update installed marketplace skills to their latest versions."""
+        result, status = update_skills(workspace_dir=config.workspace_dir)
+        return json.dumps(
+            {
+                "command": render_command(result.argv),
+                "ok": result.ok,
+                "summary": status.summary,
+                "items": status.items,
+            },
+            indent=2,
+        )
+
+    return [
+        list_saved_subagents,
+        get_saved_subagent,
+        save_subagent,
+        delete_subagent,
+        set_active_subagents,
+        list_attachable_skills,
+        search_marketplace_skills,
+        install_marketplace_skill,
+        check_skill_updates,
+        update_marketplace_skills,
+    ]
+
+
+def _spec_payload(spec: "AgentSpec", *, active_names: list[str]) -> dict[str, object]:
+    return {
+        "name": spec.name,
+        "description": spec.description,
+        "system_prompt": spec.system_prompt,
+        "skills": list(spec.skills),
+        "active": spec.name in set(active_names),
+        "workspace_dir": spec.workspace_dir,
+    }
+
+
+def _derive_description(system_prompt: str) -> str:
+    return shorten(system_prompt.strip().replace("\n", " "), width=96, placeholder="...")
+
+
+def _sync_installed_skill_into_local_library(config: AgenCLIConfig, skill_name: str) -> str | None:
+    source_path = _discover_external_skill_path(config, skill_name)
+    if source_path is None:
+        return None
+    try:
+        installed = install_local_skill(source_path, config.skills_dir, overwrite=False)
+        return installed.name
+    except FileExistsError:
+        return skill_name
+
+
+def _discover_external_skill_path(config: AgenCLIConfig, skill_name: str) -> str | None:
+    candidates = [
+        Path(config.workspace_dir) / ".agents" / "skills" / skill_name,
+        Path(config.workspace_dir) / ".codex" / "skills" / skill_name,
+        Path.home() / ".agents" / "skills" / skill_name,
+        Path.home() / ".codex" / "skills" / skill_name,
+        Path.home() / ".config" / "agents" / "skills" / skill_name,
+    ]
+    for candidate in candidates:
+        if (candidate / "SKILL.md").exists():
+            return candidate.as_posix()
+    return None

agencli/agents/prebuilt/__init__.py

@@ -0,0 +1 @@
+"""Prebuilt agent definitions."""

agencli/agents/prebuilt/catalog.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from agencli.agents.factory import AgentSpec
+from agencli.agents.supervisor import build_supervisor_agent
+
+
+PERFORMANCE_PROMPT_SUFFIX = (
+    " Optimize for fewer, larger operations. Inspect enough context up front, avoid repeating the same checks, "
+    "keep tool calls minimal, and prefer one strong command or grouped action when it can safely replace many "
+    "small steps."
+)
+
+
+def get_prebuilt_agents(default_model: str) -> dict[str, AgentSpec]:
+    agents = {
+        "filesystem-agent": AgentSpec(
+            name="filesystem-agent",
+            model=default_model,
+            description="Reads, writes, and navigates the workspace with deepagents' built-in filesystem tools.",
+            system_prompt=(
+                "You are a filesystem specialist. Read carefully before editing, "
+                "keep changes precise, and explain file operations clearly. When organizing files or folders, "
+                "prefer batched plans and grouped operations over one-item-at-a-time actions whenever the "
+                "available tools support it. Inspect first, decide the full target layout, then create needed "
+                "folders together and move related files in as few operations as possible to reduce tool chatter."
+                + PERFORMANCE_PROMPT_SUFFIX
+            ),
+        ),
+        "shell-agent": AgentSpec(
+            name="shell-agent",
+            model=default_model,
+            description="Runs shell commands with deepagents' built-in execute tool.",
+            system_prompt=(
+                "You are a shell automation specialist. Use commands carefully, "
+                "prefer safe inspections first, and summarize command results precisely. When shell automation "
+                "can safely batch a task, prefer one well-formed command over many tiny commands."
+                + PERFORMANCE_PROMPT_SUFFIX
+            ),
+        ),
+        "search-agent": AgentSpec(
+            name="search-agent",
+            model=default_model,
+            description="Searches the web through MCP-backed search tools.",
+            system_prompt=(
+                "You are a research specialist. Search broadly, synthesize findings, "
+                "and distinguish facts from inference. Avoid redundant searches and combine related questions into "
+                "the fewest high-value lookups that still produce a reliable answer."
+                + PERFORMANCE_PROMPT_SUFFIX
+            ),
+            mcp_servers=["search", "tavily-mcp"],
+        ),
+        "coding-agent": AgentSpec(
+            name="coding-agent",
+            model=default_model,
+            description="Combines deepagents' built-in filesystem and shell tools for implementation work.",
+            system_prompt=(
+                "You are an expert software engineer. Inspect files before editing, "
+                "make surgical changes, and verify your work. Prefer one cohesive patch and one targeted "
+                "verification pass over fragmented micro-steps. Use shell commands for bulk filesystem work when "
+                "they safely replace repetitive tool calls."
+                + PERFORMANCE_PROMPT_SUFFIX
+            ),
+        ),
+    }
+    agents["supervisor-agent"] = build_supervisor_agent(default_model)
+    return agents

agencli/agents/registry.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from agencli.agents.factory import AgentSpec
+
+
+class AgentRegistry:
+    def __init__(self, agents_dir: str) -> None:
+        self.agents_path = Path(agents_dir)
+        self.agents_path.mkdir(parents=True, exist_ok=True)
+        self._state_path = self.agents_path / ".agencli-state.json"
+
+    def path_for(self, name: str) -> Path:
+        return self.agents_path / f"{name}.json"
+
+    def save(self, spec: AgentSpec) -> Path:
+        path = self.path_for(spec.name)
+        path.write_text(json.dumps(spec.serializable_dict(), indent=2), encoding="utf-8")
+        return path
+
+    def list_agents(self) -> list[str]:
+        return sorted(path.stem for path in self.agents_path.glob("*.json") if path.name != self._state_path.name)
+
+    def load(self, name: str) -> AgentSpec:
+        path = self.path_for(name)
+        raw = json.loads(path.read_text(encoding="utf-8"))
+        return AgentSpec.from_dict(raw)
+
+    def delete(self, name: str) -> Path:
+        path = self.path_for(name)
+        path.unlink()
+        active_names = [item for item in self.load_active_names() if item != name]
+        self.save_active_names(active_names)
+        return path
+
+    def load_active_names(self) -> list[str]:
+        if not self._state_path.exists():
+            return []
+        raw = json.loads(self._state_path.read_text(encoding="utf-8"))
+        names = raw.get("active_agents", [])
+        if not isinstance(names, list):
+            return []
+        return [str(name) for name in names if str(name).strip()]
+
+    def save_active_names(self, names: list[str]) -> Path:
+        normalized = sorted({name.strip() for name in names if name and name.strip()})
+        self._state_path.write_text(json.dumps({"active_agents": normalized}, indent=2), encoding="utf-8")
+        return self._state_path

agencli/agents/runtime.py

@@ -0,0 +1,266 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+from typing import Any
+
+from agencli.core.session import ChatTurn
+
+
+DEFAULT_HISTORY_REPLAY_LIMIT = 50
+TRACE_PREVIEW_LIMIT = 240
+
+
+@dataclass(slots=True)
+class StreamEvent:
+    kind: str
+    label: str
+    text: str
+    phase: str = "update"
+    trace_id: str = ""
+
+
+def build_prompt_payload(
+    prompt: str | None = None,
+    *,
+    history: list[ChatTurn] | None = None,
+) -> dict[str, Any]:
+    messages = build_message_history(history or [])
+    if prompt:
+        normalized_prompt = prompt.strip()
+        if normalized_prompt:
+            messages.append(
+                {
+                    "role": "user",
+                    "content": normalized_prompt,
+                }
+            )
+    return {"messages": messages}
+
+
+def build_message_history(history: list[ChatTurn]) -> list[dict[str, str]]:
+    messages: list[dict[str, str]] = []
+    for turn in history:
+        role = _normalize_role(turn.role)
+        content = turn.content.strip()
+        if role is None or not content:
+            continue
+        messages.append({"role": role, "content": content})
+    return messages
+
+
+def parse_stream_chunk(chunk: Any) -> list[StreamEvent]:
+    if not isinstance(chunk, dict):
+        return []
+
+    events: list[StreamEvent] = []
+    for label, payload in chunk.items():
+        events.extend(_parse_payload_events(label, payload))
+    return events
+
+
+def extract_text_response(result: Any) -> str:
+    if result is None:
+        return ""
+
+    if isinstance(result, str):
+        return result
+
+    if isinstance(result, dict):
+        messages = result.get("messages")
+        if isinstance(messages, list):
+            for message in reversed(messages):
+                text = _extract_message_text(message)
+                if text:
+                    return text
+        for key in ("output", "result", "response"):
+            value = result.get(key)
+            if isinstance(value, str) and value.strip():
+                return value
+        return repr(result)
+
+    return _extract_message_text(result) or repr(result)
+
+
+def _summarize_payload(payload: Any) -> str:
+    if payload is None:
+        return ""
+    if isinstance(payload, dict):
+        filtered = {key: value for key, value in payload.items() if key not in {"messages", "skills_metadata"}}
+        if not filtered:
+            return ""
+        return _compact_text(filtered)
+    return _compact_text(payload)
+
+
+def _normalize_trace_label(label: str) -> str:
+    cleaned = label.replace("Middleware", "").replace("_", " ").strip()
+    parts = [part.strip() for part in cleaned.split(".") if part.strip()]
+    normalized = " / ".join(parts) if parts else cleaned
+    return normalized.lower()
+
+
+def _normalize_role(role: str | None) -> str | None:
+    if role is None:
+        return None
+    normalized = role.strip().lower()
+    if normalized in {"ai", "assistant"}:
+        return "assistant"
+    if normalized in {"human", "user"}:
+        return "user"
+    if normalized == "system":
+        return "system"
+    return None
+
+
+def _parse_payload_events(label: str, payload: Any) -> list[StreamEvent]:
+    if not isinstance(payload, dict):
+        summarized = _compact_text(payload)
+        if not summarized:
+            return []
+        return [StreamEvent(kind="state", label=_normalize_trace_label(label), text=summarized)]
+
+    events: list[StreamEvent] = []
+    messages = payload.get("messages", [])
+    if isinstance(messages, list):
+        for message in messages:
+            events.extend(_parse_message_event(label, message))
+
+    summary = _summarize_payload(payload)
+    if summary:
+        events.append(StreamEvent(kind="state", label=_normalize_trace_label(label), text=summary))
+    return events
+
+
+def _parse_message_event(label: str, message: Any) -> list[StreamEvent]:
+    role = _message_role(message)
+    events: list[StreamEvent] = []
+
+    if role == "assistant":
+        for tool_call in _extract_tool_calls(message):
+            tool_name = tool_call.get("name") or _normalize_trace_label(label)
+            tool_input = tool_call.get("args", tool_call.get("arguments"))
+            trace_id = str(tool_call.get("id", "")).strip()
+            if str(tool_name).strip() == "task" and isinstance(tool_input, dict):
+                subagent_type = str(tool_input.get("subagent_type", "")).strip()
+                description = _compact_text(tool_input.get("description")) or _compact_text(tool_input) or "invoked"
+                if subagent_type:
+                    events.append(
+                        StreamEvent(
+                            kind="subagent",
+                            label=subagent_type,
+                            text=description,
+                            phase="start",
+                            trace_id=trace_id,
+                        )
+                    )
+                    continue
+            events.append(
+                StreamEvent(
+                    kind="tool",
+                    label=str(tool_name),
+                    text=_compact_text(tool_input) or "invoked",
+                    phase="start",
+                    trace_id=trace_id,
+                )
+            )
+        text = _extract_message_text(message)
+        if text:
+            events.append(StreamEvent(kind="assistant", label="assistant", text=text, phase="message"))
+        return events
+
+    if role == "tool":
+        tool_name = _message_name(message) or _normalize_trace_label(label)
+        tool_text = _extract_message_text(message)
+        trace_id = _message_tool_call_id(message)
+        if tool_name == "task":
+            events.append(
+                StreamEvent(
+                    kind="subagent",
+                    label=tool_name,
+                    text=tool_text or "(ok)",
+                    phase="end",
+                    trace_id=trace_id,
+                )
+            )
+            return events
+        events.append(
+            StreamEvent(
+                kind="tool",
+                label=tool_name,
+                text=tool_text or "(ok)",
+                phase="end",
+                trace_id=trace_id,
+            )
+        )
+        return events
+
+    text = _extract_message_text(message)
+    if text:
+        events.append(StreamEvent(kind="state", label=_normalize_trace_label(label), text=text, phase="update"))
+    return events
+
+
+def _message_role(message: Any) -> str | None:
+    role = getattr(message, "type", None)
+    if role is None and isinstance(message, dict):
+        role = message.get("type") or message.get("role")
+    return _normalize_role(role) or ("tool" if str(role).strip().lower() == "tool" else None)
+
+
+def _message_name(message: Any) -> str:
+    name = getattr(message, "name", None)
+    if name is None and isinstance(message, dict):
+        name = message.get("name")
+    return str(name).strip() if name else ""
+
+
+def _message_tool_call_id(message: Any) -> str:
+    tool_call_id = getattr(message, "tool_call_id", None)
+    if tool_call_id is None and isinstance(message, dict):
+        tool_call_id = message.get("tool_call_id")
+    return str(tool_call_id).strip() if tool_call_id else ""
+
+
+def _extract_tool_calls(message: Any) -> list[dict[str, Any]]:
+    tool_calls = getattr(message, "tool_calls", None)
+    if tool_calls is None and isinstance(message, dict):
+        tool_calls = message.get("tool_calls")
+    if not isinstance(tool_calls, list):
+        return []
+    return [call for call in tool_calls if isinstance(call, dict)]
+
+
+def _extract_message_text(message: Any) -> str:
+    content = getattr(message, "content", None)
+    if content is None and isinstance(message, dict):
+        content = message.get("content")
+    if isinstance(content, str):
+        return content.strip()
+    if isinstance(content, list):
+        parts: list[str] = []
+        for item in content:
+            if isinstance(item, str):
+                parts.append(item)
+            elif isinstance(item, dict):
+                text = item.get("text")
+                if isinstance(text, str):
+                    parts.append(text)
+        return "\n".join(part for part in parts if part).strip()
+    return ""
+
+
+def _compact_text(value: Any, limit: int = TRACE_PREVIEW_LIMIT) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, str):
+        text = value.strip()
+    else:
+        try:
+            text = json.dumps(value, ensure_ascii=True, sort_keys=True)
+        except TypeError:
+            text = repr(value)
+    compacted = " ".join(text.split())
+    if len(compacted) <= limit:
+        return compacted
+    return f"{compacted[: limit - 3]}..."