astra-cli-agent 0.1.0__py3-none-any.whl

astra/agents/kubernetes_agent.py

@@ -0,0 +1,150 @@
+"""Kubernetes Agent: translates an instruction into one kubectl tool call, executes it,
+reports back. Same one-LLM-call JSON tool-selection dispatch `DockerAgent`/`GitAgent`/
+`FileAgent` use, plus two behaviors specific to this domain:
+
+- **Ambient apply path**: `k8s_apply` takes a `path` arg (the manifest file); if the LLM
+  omits it and a `k8s.yaml`/`k8s.yml`/`manifest.yaml` file exists in the current project
+  directory, the agent defaults to it — same "ambient root, not LLM-chosen" trust level
+  `DockerAgent` gives `docker_build`'s `path` arg.
+- **The interactive confirm gate** (§8 of the architecture doc): a confirm-required tool call
+  (`k8s_delete`, `k8s_exec` — permanent deletion or arbitrary in-pod command execution) is
+  blocked on `self._confirm` before it runs, unless `state.assume_yes` is set. Declining
+  cancels the step without ever calling the tool — same gate every other worker agent applies.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from astra.agents.base import BaseAgent
+from astra.core.confirm import ConfirmFn, interactive_confirm
+from astra.core.events import Event, record
+from astra.core.state import AgentState, PlanStep
+from astra.llm.provider import LLMResponse
+from astra.llm.router import FallbackRouter
+from astra.tools.registry import ToolRegistry
+
+_AMBIENT_MANIFEST_NAMES = ("k8s.yaml", "k8s.yml", "manifest.yaml", "manifest.yml")
+
+
+def _strip_code_fence(text: str) -> str:
+    text = text.strip()
+    if text.startswith("```"):
+        lines = text.splitlines()
+        lines = lines[1:] if lines else lines
+        if lines and lines[-1].strip().startswith("```"):
+            lines = lines[:-1]
+        text = "\n".join(lines).strip()
+    return text
+
+
+class KubernetesAgent(BaseAgent):
+    name = "kubernetes"
+    description = (
+        "Manages Kubernetes resources in the current cluster context: list, describe, apply "
+        "manifests, scale, restart rollouts, expose, delete, and exec into pods."
+    )
+
+    def __init__(
+        self,
+        router: FallbackRouter,
+        tool_registry: ToolRegistry,
+        confirm: ConfirmFn = interactive_confirm,
+    ) -> None:
+        super().__init__(router)
+        self._tools = tool_registry
+        self._confirm = confirm
+        catalog_lines = "\n".join(f"- {t.name}: {t.description}" for t in tool_registry.by_tag(self.name))
+        self.system_prompt = (
+            "You are Astra's kubernetes agent. Given a developer instruction, choose exactly "
+            "one tool from the catalog and the arguments to call it with. Reply with ONLY a "
+            'single JSON object: {"tool": "<tool_name>", "args": {"<arg>": "<value>", ...}}. '
+            "Omit an arg entirely rather than inventing a value you weren't given — in "
+            'particular, omit "path" for k8s_apply and "namespace" for any tool if no '
+            "namespace was specified.\n\n"
+            f"Catalog:\n{catalog_lines}"
+        )
+
+    def run(self, state: AgentState) -> dict[str, Any]:
+        updated_plan = list(state.plan)
+        events = state.events
+        total_cost = state.total_cost_usd
+        root = Path.cwd().resolve()
+
+        for i, step in enumerate(updated_plan):
+            if step.agent != self.name or step.status != "pending":
+                continue
+            new_step, cost, events = self._execute_step(step, root, events, state.assume_yes)
+            updated_plan[i] = new_step
+            total_cost += cost
+
+        return {"plan": updated_plan, "events": events, "total_cost_usd": total_cost}
+
+    def _execute_step(
+        self, step: PlanStep, root: Path, events: list[Event], assume_yes: bool
+    ) -> tuple[PlanStep, float, list[Event]]:
+        selection_response = self.complete(step.instruction, temperature=0.0)
+        cost = selection_response.estimated_cost_usd
+
+        try:
+            tool_name, args = self._parse_selection(selection_response)
+        except ValueError as exc:
+            events = record(events, self.name, f"could not parse tool selection: {exc}")
+            return step.model_copy(update={"status": "failed", "result": str(exc)}), cost, events
+
+        tool = self._tools.get(tool_name)
+        if tool is None:
+            error = f"selected unknown kubernetes tool: {tool_name}"
+            events = record(events, self.name, error)
+            return step.model_copy(update={"status": "failed", "result": error}), cost, events
+
+        if tool_name == "k8s_apply" and not args.get("path"):
+            default_manifest = self._find_ambient_manifest(root)
+            if default_manifest is not None:
+                args["path"] = str(default_manifest)
+
+        is_risky = "confirm-required" in tool.tags
+        if is_risky and not assume_yes:
+            approved = self._confirm(f"Allow risky kubernetes operation ({tool_name}) with args={args}?")
+            if not approved:
+                message = f"cancelled by user (risky operation not confirmed): {tool_name}"
+                events = record(events, self.name, message)
+                return step.model_copy(update={"status": "failed", "result": message}), cost, events
+
+        try:
+            result = tool.func(**args)
+        except Exception as exc:  # LLM-supplied tool args are untrusted input; never crash the graph
+            error = f"kubernetes agent call to {tool_name} failed: {exc}"
+            events = record(events, self.name, error)
+            return step.model_copy(update={"status": "failed", "result": error}), cost, events
+
+        output = result.output or result.error or "(no output)"
+        if is_risky:
+            output = f"⚠️ risky operation ({tool_name}): {output}"
+            events = record(events, self.name, f"risky operation executed: {tool_name}")
+        events = record(events, self.name, f"executed step {step.step_id} via {tool_name}")
+
+        status = "done" if result.success else "failed"
+        return step.model_copy(update={"status": status, "result": output}), cost, events
+
+    def _find_ambient_manifest(self, root: Path) -> Path | None:
+        for name in _AMBIENT_MANIFEST_NAMES:
+            candidate = root / name
+            if candidate.is_file():
+                return candidate
+        return None
+
+    def _parse_selection(self, response: LLMResponse) -> tuple[str, dict[str, Any]]:
+        raw = _strip_code_fence(response.content)
+        try:
+            parsed = json.loads(raw)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"kubernetes agent produced non-JSON tool selection: {raw!r}") from exc
+
+        tool_name = parsed.get("tool")
+        args = parsed.get("args") or {}
+        if not isinstance(tool_name, str) or not isinstance(args, dict):
+            raise ValueError(f"kubernetes agent produced a malformed tool selection: {parsed!r}")
+        return tool_name, dict(args)

astra/agents/mcp_agent.py

@@ -0,0 +1,135 @@
+"""MCP Agent: translates an instruction into one call against a discovered MCP tool
+(or resource/prompt meta-tool) and executes it. Same one-LLM-call JSON tool-selection
+dispatch every other worker agent uses (`GitAgent`/`DockerAgent`/`KubernetesAgent`), plus
+the same interactive confirm gate for anything tagged `confirm-required` — which, for this
+domain, is most discovered tools by default (see `tools/mcp/discovery.py`'s risk-tagging
+rationale: an MCP server's own `readOnlyHint` annotation is trusted only when explicitly
+`True`, since third-party MCP servers are the least-trusted tool domain in this project).
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from astra.agents.base import BaseAgent
+from astra.core.confirm import ConfirmFn, interactive_confirm
+from astra.core.events import Event, record
+from astra.core.state import AgentState, PlanStep
+from astra.llm.provider import LLMResponse
+from astra.llm.router import FallbackRouter
+from astra.tools.registry import ToolRegistry
+
+
+def _strip_code_fence(text: str) -> str:
+    text = text.strip()
+    if text.startswith("```"):
+        lines = text.splitlines()
+        lines = lines[1:] if lines else lines
+        if lines and lines[-1].strip().startswith("```"):
+            lines = lines[:-1]
+        text = "\n".join(lines).strip()
+    return text
+
+
+class MCPAgent(BaseAgent):
+    name = "mcp"
+    description = (
+        "Calls tools, reads resources, and renders prompts exposed by configured MCP "
+        "(Model Context Protocol) servers — third-party plugins outside astra's built-in "
+        "tool domains."
+    )
+
+    def __init__(
+        self,
+        router: FallbackRouter,
+        tool_registry: ToolRegistry,
+        confirm: ConfirmFn = interactive_confirm,
+    ) -> None:
+        super().__init__(router)
+        self._tools = tool_registry
+        self._confirm = confirm
+        catalog_lines = "\n".join(f"- {t.name}: {t.description}" for t in tool_registry.by_tag(self.name))
+        self.system_prompt = (
+            "You are Astra's MCP agent. Given a developer instruction, choose exactly one "
+            "tool from the catalog and the arguments to call it with. Reply with ONLY a single "
+            'JSON object: {"tool": "<tool_name>", "args": {"<arg>": "<value>", ...}}. Omit an '
+            "arg entirely rather than inventing a value you weren't given. For a "
+            '"*_get_prompt" tool, "arguments" (if any) must be a JSON object encoded as a '
+            "string, e.g. \"{\\\"topic\\\": \\\"python\\\"}\".\n\n"
+            f"Catalog:\n{catalog_lines}"
+        )
+
+    def run(self, state: AgentState) -> dict[str, Any]:
+        updated_plan = list(state.plan)
+        events = state.events
+        total_cost = state.total_cost_usd
+
+        for i, step in enumerate(updated_plan):
+            if step.agent != self.name or step.status != "pending":
+                continue
+            new_step, cost, events = self._execute_step(step, events, state.assume_yes)
+            updated_plan[i] = new_step
+            total_cost += cost
+
+        return {"plan": updated_plan, "events": events, "total_cost_usd": total_cost}
+
+    def _execute_step(
+        self, step: PlanStep, events: list[Event], assume_yes: bool
+    ) -> tuple[PlanStep, float, list[Event]]:
+        if not self._tools.by_tag(self.name):
+            error = "no MCP tools available (no server configured, or discovery failed for all of them)"
+            events = record(events, self.name, error)
+            return step.model_copy(update={"status": "failed", "result": error}), 0.0, events
+
+        selection_response = self.complete(step.instruction, temperature=0.0)
+        cost = selection_response.estimated_cost_usd
+
+        try:
+            tool_name, args = self._parse_selection(selection_response)
+        except ValueError as exc:
+            events = record(events, self.name, f"could not parse tool selection: {exc}")
+            return step.model_copy(update={"status": "failed", "result": str(exc)}), cost, events
+
+        tool = self._tools.get(tool_name)
+        if tool is None:
+            error = f"selected unknown mcp tool: {tool_name}"
+            events = record(events, self.name, error)
+            return step.model_copy(update={"status": "failed", "result": error}), cost, events
+
+        is_risky = "confirm-required" in tool.tags
+        if is_risky and not assume_yes:
+            approved = self._confirm(f"Allow risky MCP operation ({tool_name}) with args={args}?")
+            if not approved:
+                message = f"cancelled by user (risky operation not confirmed): {tool_name}"
+                events = record(events, self.name, message)
+                return step.model_copy(update={"status": "failed", "result": message}), cost, events
+
+        try:
+            result = tool.func(**args)
+        except Exception as exc:  # LLM-supplied tool args are untrusted input; never crash the graph
+            error = f"mcp agent call to {tool_name} failed: {exc}"
+            events = record(events, self.name, error)
+            return step.model_copy(update={"status": "failed", "result": error}), cost, events
+
+        output = result.output or result.error or "(no output)"
+        if is_risky:
+            output = f"⚠️ risky operation ({tool_name}): {output}"
+            events = record(events, self.name, f"risky operation executed: {tool_name}")
+        events = record(events, self.name, f"executed step {step.step_id} via {tool_name}")
+
+        status = "done" if result.success else "failed"
+        return step.model_copy(update={"status": status, "result": output}), cost, events
+
+    def _parse_selection(self, response: LLMResponse) -> tuple[str, dict[str, Any]]:
+        raw = _strip_code_fence(response.content)
+        try:
+            parsed = json.loads(raw)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"mcp agent produced non-JSON tool selection: {raw!r}") from exc
+
+        tool_name = parsed.get("tool")
+        args = parsed.get("args") or {}
+        if not isinstance(tool_name, str) or not isinstance(args, dict):
+            raise ValueError(f"mcp agent produced a malformed tool selection: {parsed!r}")
+        return tool_name, dict(args)

astra/agents/memory_agent.py

@@ -0,0 +1,35 @@
+"""Memory Agent: the only agent that touches the SQLite store directly.
+
+Runs as the final graph node, persisting the completed request/response pair.
+Other agents that need history or preferences must go through this agent's
+`MemoryStore` rather than opening their own connection.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from astra.core.events import record
+from astra.core.state import AgentState
+from astra.llm.router import FallbackRouter
+from astra.memory.store import MemoryStore
+
+
+class MemoryAgent:
+    name = "memory"
+
+    def __init__(self, store: MemoryStore, llm_router: FallbackRouter) -> None:
+        self._store = store
+        self._router = llm_router
+
+    def run(self, state: AgentState) -> dict[str, Any]:
+        conversation = self._store.save_conversation(
+            request=state.request,
+            response=state.final_response or "",
+            cost_usd=state.total_cost_usd,
+        )
+        # Drains (not just reads) the router's call log — see `drain_call_log`'s docstring
+        # for why: this agent runs once per request, and draining keeps a future multi-request
+        # process (the Phase 16 REPL) from re-persisting a previous request's calls.
+        self._store.save_llm_calls(conversation.id, self._router.drain_call_log())
+        return {"events": record(state.events, self.name, "saved conversation to memory")}

astra/agents/planner_agent.py

@@ -0,0 +1,149 @@
+"""Planner Agent: in a single LLM call, both *routes* (picks which agent handles each step)
+and *plans* (rewrites the request into precise, ordered, imperative instructions).
+
+This merges what used to be two separate LLM calls — a `RouterAgent` that classified the
+request to exactly one agent, followed by a `PlannerAgent` that rewrote it into one
+instruction. Folding them into one call cuts a full LLM round-trip off every request, and
+lets the same call emit a *multi-step, multi-agent* plan (e.g. "commit my changes and then
+explain the diff" -> a git step followed by a coder step) instead of the previous
+always-exactly-one-step limitation.
+
+Output is a JSON object `{"steps": [{"agent": "<name>", "instruction": "<imperative>"}, ...]}`.
+Unknown agent names the LLM invents are coerced to the first catalog entry (so `execute_plan`
+never sees an unregistered agent — its `NoAgentAvailableError` is a defense-in-depth invariant,
+not a normal-path branch). Non-JSON / malformed output degrades gracefully to a single step
+routed to the fallback agent with the raw request as the instruction — the same "never crash
+the graph on unexpected LLM output" tolerance every other agent has.
+
+On a revision pass (`state.revision_feedback` set by the Reviewer), a single follow-up step is
+*appended* re-targeting the last step's agent with the reviewer's feedback folded in — prior
+steps stay in the plan for history, same as before the merge.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from astra.agents.base import BaseAgent
+from astra.core.events import record
+from astra.core.state import AgentState, PlanStep
+from astra.llm.router import FallbackRouter
+
+
+def _strip_code_fence(text: str) -> str:
+    text = text.strip()
+    if text.startswith("```"):
+        lines = text.splitlines()
+        lines = lines[1:] if lines else lines
+        if lines and lines[-1].strip().startswith("```"):
+            lines = lines[:-1]
+        text = "\n".join(lines).strip()
+    return text
+
+
+class PlannerAgent(BaseAgent):
+    name = "planner"
+
+    def __init__(self, router: FallbackRouter, agent_catalog: dict[str, str]) -> None:
+        super().__init__(router)
+        if not agent_catalog:
+            raise ValueError("agent_catalog must contain at least one agent")
+        self._catalog = agent_catalog
+        self._fallback_agent = next(iter(agent_catalog))
+        catalog_lines = "\n".join(f"- {name}: {desc}" for name, desc in agent_catalog.items())
+        self.system_prompt = (
+            "You are Astra's planning agent. You both choose which agent handles the work and "
+            "rewrite the developer's request into precise, imperative instructions. Reply with "
+            "ONLY a single JSON object of this exact shape:\n"
+            '{"steps": [{"agent": "<agent name from the catalog>", "instruction": '
+            '"<one precise imperative instruction>"}, ...]}\n'
+            "Use exactly one step for a simple request. Use multiple ordered steps only when the "
+            "request genuinely needs different agents or sequential actions (e.g. commit changes, "
+            "then explain the diff). Each 'agent' must be one of the catalog names below, "
+            "lowercase. Do not add commentary outside the JSON.\n\n"
+            f"Catalog:\n{catalog_lines}"
+        )
+
+    def run(self, state: AgentState) -> dict[str, Any]:
+        if state.revision_feedback:
+            return self._plan_revision(state)
+
+        user_content = state.request
+        if state.retrieved_context:
+            context_block = "\n\n".join(state.retrieved_context)
+            user_content = (
+                f"Relevant project context:\n{context_block}\n\nDeveloper request: {state.request}"
+            )
+        response = self.complete(user_content, temperature=0.1)
+        steps = self._parse_plan(response.content, state.request)
+        selected_agents: list[str] = []
+        for step in steps:
+            if step.agent not in selected_agents:
+                selected_agents.append(step.agent)
+        agents_desc = ",".join(selected_agents)
+        return {
+            "selected_agents": selected_agents,
+            "plan": steps,
+            "events": record(
+                state.events,
+                self.name,
+                f"planned {len(steps)} step(s) across agent(s): {agents_desc}",
+            ),
+            "total_cost_usd": state.total_cost_usd + response.estimated_cost_usd,
+        }
+
+    def _parse_plan(self, content: str, request: str) -> list[PlanStep]:
+        """Parses the JSON plan into PlanSteps, coercing unknown agent names and degrading to a
+        single fallback step on any malformed output."""
+        raw = _strip_code_fence(content)
+        try:
+            parsed = json.loads(raw)
+        except json.JSONDecodeError:
+            return [self._fallback_step(1, request)]
+
+        raw_steps = parsed.get("steps") if isinstance(parsed, dict) else None
+        if not isinstance(raw_steps, list) or not raw_steps:
+            return [self._fallback_step(1, request)]
+
+        steps: list[PlanStep] = []
+        for raw_step in raw_steps:
+            if not isinstance(raw_step, dict):
+                continue
+            agent = raw_step.get("agent")
+            instruction = raw_step.get("instruction")
+            if not isinstance(agent, str) or agent not in self._catalog:
+                agent = self._fallback_agent
+            if not isinstance(instruction, str) or not instruction.strip():
+                instruction = request
+            steps.append(
+                PlanStep(step_id=len(steps) + 1, agent=agent, instruction=instruction.strip())
+            )
+
+        return steps or [self._fallback_step(1, request)]
+
+    def _fallback_step(self, step_id: int, request: str) -> PlanStep:
+        return PlanStep(step_id=step_id, agent=self._fallback_agent, instruction=request)
+
+    def _plan_revision(self, state: AgentState) -> dict[str, Any]:
+        """Appends one more step re-targeting the last step's agent with reviewer feedback."""
+        agent_name = state.plan[-1].agent if state.plan else self._fallback_agent
+        previous_result = state.plan[-1].result if state.plan else "(no previous result)"
+        user_content = (
+            f"Developer request: {state.request}\n\n"
+            f"Previous attempt result:\n{previous_result}\n\n"
+            f"Reviewer feedback: {state.revision_feedback}\n\n"
+            "Rewrite a single, precise, imperative instruction that addresses the feedback. "
+            "Reply with only the instruction text, no JSON, no preamble."
+        )
+        response = self.complete(user_content, temperature=0.1)
+        instruction = response.content.strip() or state.request
+        next_step_id = state.plan[-1].step_id + 1 if state.plan else 1
+        step = PlanStep(step_id=next_step_id, agent=agent_name, instruction=instruction)
+        return {
+            "plan": [*state.plan, step],
+            "events": record(
+                state.events, self.name, f"planned revision step {next_step_id} for agent={agent_name}"
+            ),
+            "total_cost_usd": state.total_cost_usd + response.estimated_cost_usd,
+        }

astra/agents/research_agent.py

@@ -0,0 +1,121 @@
+"""Research Agent: translates an instruction into one web-search/fetch tool call, executes
+it, reports back. Same one-LLM-call JSON tool-selection dispatch every other worker agent
+uses, minus the interactive confirm gate — every tool in this domain is tagged "read-only"
+(an outbound HTTP GET against a public API, nothing to confirm or undo), so there's no
+confirm-required tier to check, unlike `GitAgent`/`FileAgent`/`DockerAgent`/
+`KubernetesAgent`.
+
+Every result line from a search tool carries its source URL, and `web_fetch_url` prefixes its
+output with `[source: <url>]` — that's the "citation" half of the architecture doc's
+"docs/SO/GitHub search with citation" requirement: the Reviewer's existing pass-risk-warnings-
+verbatim instruction (Phase 9) doesn't apply here since nothing here is risky, but source URLs
+in plain step output naturally survive into `final_response` the same way any other step
+result does.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from astra.agents.base import BaseAgent
+from astra.core.events import Event, record
+from astra.core.state import AgentState, PlanStep
+from astra.llm.provider import LLMResponse
+from astra.llm.router import FallbackRouter
+from astra.tools.registry import ToolRegistry
+
+
+def _strip_code_fence(text: str) -> str:
+    text = text.strip()
+    if text.startswith("```"):
+        lines = text.splitlines()
+        lines = lines[1:] if lines else lines
+        if lines and lines[-1].strip().startswith("```"):
+            lines = lines[:-1]
+        text = "\n".join(lines).strip()
+    return text
+
+
+class ResearchAgent(BaseAgent):
+    name = "research"
+    description = (
+        "Searches the web for developer information: general web/documentation search, GitHub "
+        "repositories, GitHub issues/pull requests, Stack Overflow questions, and fetches the "
+        "readable content of a specific documentation URL."
+    )
+
+    def __init__(self, router: FallbackRouter, tool_registry: ToolRegistry) -> None:
+        super().__init__(router)
+        self._tools = tool_registry
+        catalog_lines = "\n".join(f"- {t.name}: {t.description}" for t in tool_registry.by_tag(self.name))
+        self.system_prompt = (
+            "You are Astra's research agent. Given a developer instruction, choose exactly "
+            "one tool from the catalog and the arguments to call it with. Reply with ONLY a "
+            'single JSON object: {"tool": "<tool_name>", "args": {"<arg>": "<value>", ...}}. '
+            "Use web_search_general for broad web/documentation/how-to searches, "
+            "web_search_github_repos for finding libraries/projects, "
+            "web_search_github_issues for finding how others solved a specific problem, "
+            "web_search_stackoverflow for Q&A-style questions, and web_fetch_url only when "
+            "given (or you already know) a specific URL to read. Omit an arg entirely rather "
+            "than inventing a value you weren't given.\n\n"
+            f"Catalog:\n{catalog_lines}"
+        )
+
+    def run(self, state: AgentState) -> dict[str, Any]:
+        updated_plan = list(state.plan)
+        events = state.events
+        total_cost = state.total_cost_usd
+
+        for i, step in enumerate(updated_plan):
+            if step.agent != self.name or step.status != "pending":
+                continue
+            new_step, cost, events = self._execute_step(step, events)
+            updated_plan[i] = new_step
+            total_cost += cost
+
+        return {"plan": updated_plan, "events": events, "total_cost_usd": total_cost}
+
+    def _execute_step(
+        self, step: PlanStep, events: list[Event]
+    ) -> tuple[PlanStep, float, list[Event]]:
+        selection_response = self.complete(step.instruction, temperature=0.0)
+        cost = selection_response.estimated_cost_usd
+
+        try:
+            tool_name, args = self._parse_selection(selection_response)
+        except ValueError as exc:
+            events = record(events, self.name, f"could not parse tool selection: {exc}")
+            return step.model_copy(update={"status": "failed", "result": str(exc)}), cost, events
+
+        tool = self._tools.get(tool_name)
+        if tool is None:
+            error = f"selected unknown research tool: {tool_name}"
+            events = record(events, self.name, error)
+            return step.model_copy(update={"status": "failed", "result": error}), cost, events
+
+        try:
+            result = tool.func(**args)
+        except Exception as exc:  # LLM-supplied tool args are untrusted input; never crash the graph
+            error = f"research agent call to {tool_name} failed: {exc}"
+            events = record(events, self.name, error)
+            return step.model_copy(update={"status": "failed", "result": error}), cost, events
+
+        output = result.output or result.error or "(no output)"
+        events = record(events, self.name, f"executed step {step.step_id} via {tool_name}")
+
+        status = "done" if result.success else "failed"
+        return step.model_copy(update={"status": status, "result": output}), cost, events
+
+    def _parse_selection(self, response: LLMResponse) -> tuple[str, dict[str, Any]]:
+        raw = _strip_code_fence(response.content)
+        try:
+            parsed = json.loads(raw)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"research agent produced non-JSON tool selection: {raw!r}") from exc
+
+        tool_name = parsed.get("tool")
+        args = parsed.get("args") or {}
+        if not isinstance(tool_name, str) or not isinstance(args, dict):
+            raise ValueError(f"research agent produced a malformed tool selection: {parsed!r}")
+        return tool_name, dict(args)

astra/agents/retrieve_agent.py

@@ -0,0 +1,52 @@
+"""Retrieve Agent: injects ingested-project context into the request before planning.
+
+No-ops (no embedding cost, no extra latency) when the current working directory hasn't
+been ingested via `astra ingest` — most requests won't have a project registered, and
+this must stay free in that case.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from astra.core.events import record
+from astra.core.settings import MemorySettings
+from astra.core.state import AgentState
+from astra.memory.embeddings import EmbeddingModel
+from astra.memory.retriever import Retriever
+from astra.memory.store import MemoryStore
+from astra.memory.vector_store import VectorStore
+
+_TOP_K = 3
+
+
+class RetrieveAgent:
+    name = "retrieve"
+
+    def __init__(self, store: MemoryStore, memory_settings: MemorySettings) -> None:
+        self._store = store
+        self._memory_settings = memory_settings
+
+    def run(self, state: AgentState) -> dict[str, Any]:
+        project = self._store.get_project_by_path(str(Path.cwd()))
+        if project is None:
+            return {
+                "retrieved_context": [],
+                "events": record(state.events, self.name, "no ingested project for cwd"),
+            }
+
+        embeddings = EmbeddingModel(self._memory_settings.embedding_model)
+        vector_store = VectorStore(
+            self._memory_settings.index_path / project.slug, dimension=embeddings.dimension
+        )
+        results = Retriever(vector_store, embeddings).query(state.request, k=_TOP_K)
+        context = [f"{chunk.source}: {chunk.text.strip()}" for chunk, _distance in results]
+        return {
+            "retrieved_context": context,
+            "events": record(
+                state.events,
+                self.name,
+                f"retrieved {len(context)} chunk(s) from project {project.slug}",
+            ),
+        }