latest refactoring
Some checks failed
validation / verify (push) Failing after 10s

This commit is contained in:
2026-10-06 20:22:37 +01:00
parent e94b2493e7
commit 7ee49ab352
414 changed files with 15768 additions and 3896 deletions

View File

@@ -1,27 +1 @@
"""Tools package."""
from .gcp_scanner import GCPEnvironmentScanner
from .mcp_developer_knowledge import (
DeveloperKnowledgeMCPClient,
developerknowledge_answer_query,
developerknowledge_get_documents,
developerknowledge_search_documents,
get_mcp_client,
)
from .validation_tools import (
validate_mermaid_diagram,
validate_repository_artifacts,
validate_terraform_syntax,
)
__all__ = [
"validate_mermaid_diagram",
"validate_repository_artifacts",
"validate_terraform_syntax",
"developerknowledge_search_documents",
"developerknowledge_get_documents",
"developerknowledge_answer_query",
"DeveloperKnowledgeMCPClient",
"get_mcp_client",
"GCPEnvironmentScanner",
]

318
app/tools/execution.py Normal file
View File

@@ -0,0 +1,318 @@
"""Execution tools: how agents act on an Execution.
Tools enforce the Ledger's rules at the moment an agent acts, and return refusals as
messages so a ReAct agent can recover. A tool ends the agent's turn by returning an
outcome.
"""
from __future__ import annotations
from collections.abc import Mapping, Sequence
from pathlib import PurePosixPath
from typing import Any
from app.adk.runtime import (
FILES_SCHEMA,
NeedsInput,
Submitted,
ToolResult,
ToolSpec,
TurnEnded,
files_from_argument,
)
from app.states.ledger import Ledger, LedgerRefusal, PhaseStatus
from app.workflows.deliverables import (
DEPENDENCY_GRAPH,
DeliverableKind,
PhaseId,
check_submission,
deliverables_in,
)
ORCHESTRATOR = "orchestrator"
CLOUD_READ = "cloud_read"
_NO_ARGS: Mapping[str, Any] = {"type": "object", "properties": {}}
def _schema(properties: Mapping[str, Any], required: Sequence[str]) -> dict[str, Any]:
return {
"type": "object",
"properties": dict(properties),
"required": list(required),
}
def _refused(reason: object) -> ToolResult:
return ToolResult(f"Refused: {reason}")
class OrchestratorToolbox:
"""The Orchestrator's tools, bound to a working copy of the Ledger for one turn."""
def __init__(
self,
ledger: Ledger,
deliverables: Mapping[str, Mapping[str, Any]],
pending_questions: Sequence[Mapping[str, Any]],
) -> None:
self.ledger = ledger
self._deliverables = deliverables
self._pending_questions = pending_questions
self.started: dict[DeliverableKind, int] = {}
self.questions: list[dict[str, str]] = []
self.approval: dict[str, Any] | None = None
self.escalation: str | None = None
def tools(self) -> list[ToolSpec]:
return [
ToolSpec(
"ready_work",
"List Deliverables ready to delegate and Phases ready for Approval.",
_NO_ARGS,
self.ready_work,
tier="execution",
),
ToolSpec(
"delegate",
"Start Specialists on ready Deliverables, in parallel. Ends your turn.",
_schema(
{"kinds": {"type": "array", "items": {"type": "string"}}},
["kinds"],
),
self.delegate,
tier="execution",
),
ToolSpec(
"ask_user",
"Ask the user your questions together with any waiting Specialist "
"questions. Ends your turn.",
_schema(
{"questions": {"type": "array", "items": {"type": "string"}}}, []
),
self.ask_user,
tier="execution",
),
ToolSpec(
"request_approval",
"Ask the user to approve a Phase whose Deliverables are all "
"submitted. Ends your turn unless the Execution is pre-approved.",
_schema(
{"phase": {"type": "string"}, "summary": {"type": "string"}},
["phase", "summary"],
),
self.request_approval,
tier="execution",
),
ToolSpec(
"reopen",
"Revise a submitted Deliverable; everything depending on it returns "
"to draft.",
_schema(
{"kind": {"type": "string"}, "reason": {"type": "string"}},
["kind", "reason"],
),
self.reopen,
tier="execution",
),
ToolSpec(
"read_deliverable",
"Read a submitted Deliverable's content.",
_schema({"kind": {"type": "string"}}, ["kind"]),
self.read_deliverable,
tier="execution",
),
ToolSpec(
"finish",
"Complete the Execution once packaging is approved. Ends your turn.",
_NO_ARGS,
self.finish,
tier="execution",
),
]
async def ready_work(self) -> ToolResult:
ready = ", ".join(self.ledger.ready_work()) or "none"
phases = ", ".join(self.ledger.phases_ready_for_approval()) or "none"
return ToolResult(
f"Ready to delegate: {ready}. Phases ready for approval: {phases}."
)
async def delegate(self, kinds: Sequence[str]) -> ToolResult:
try:
parsed = [DeliverableKind(kind) for kind in kinds]
if not parsed:
raise LedgerRefusal("name at least one Deliverable")
started = self.ledger.start(parsed, actor=ORCHESTRATOR)
except (ValueError, LedgerRefusal) as exc:
return _refused(exc)
self.started.update(started)
return ToolResult(f"Started: {', '.join(started)}.", TurnEnded("delegate"))
async def ask_user(self, questions: Sequence[str] = ()) -> ToolResult:
waiting = sorted(
self._pending_questions,
key=lambda item: list(DEPENDENCY_GRAPH).index(
DeliverableKind(item["kind"])
),
)
combined = [
{"from": item["kind"], "question": question}
for item in waiting
for question in item["questions"]
]
combined += [{"from": ORCHESTRATOR, "question": q} for q in questions if q]
if not combined:
return _refused("there is nothing to ask the user")
self.questions = combined
return ToolResult("Asked the user.", TurnEnded("ask_user"))
async def request_approval(self, phase: str, summary: str) -> ToolResult:
try:
phase_id = PhaseId(phase)
except ValueError as exc:
return _refused(exc)
if self.ledger.phase_status(phase_id) is not PhaseStatus.AWAITING_APPROVAL:
try:
self.ledger.request_approval(phase_id, actor=ORCHESTRATOR)
except LedgerRefusal as exc:
return _refused(exc)
if self.ledger.phase_status(phase_id) is PhaseStatus.APPROVED:
return ToolResult(
f"Phase {phase_id} approved (pre-approved Execution)."
)
self.approval = {
"phase": phase_id.value,
"summary": summary,
"deliverables": [kind.value for kind in deliverables_in(phase_id)],
}
return ToolResult(
f"Asked the user to approve {phase_id}.", TurnEnded("request_approval")
)
async def reopen(self, kind: str, reason: str) -> ToolResult:
try:
result = self.ledger.reopen(
DeliverableKind(kind), reason, actor=ORCHESTRATOR
)
except (ValueError, LedgerRefusal) as exc:
return _refused(exc)
if result.escalation:
if self.ledger.pre_approved:
self.escalation = result.escalation
return ToolResult(result.escalation, TurnEnded("escalate"))
return ToolResult(
f"{result.escalation} Use ask_user to put this to the user."
)
withdrawn = ", ".join(result.withdrawn_approvals) or "none"
return ToolResult(
f"Reopened {kind}. Returned to draft: {', '.join(result.reset)}. "
f"Approvals withdrawn: {withdrawn}."
)
async def read_deliverable(self, kind: str) -> ToolResult:
deliverable = self._deliverables.get(kind)
if deliverable is None:
return ToolResult(f"{kind} has not been submitted.")
return ToolResult(deliverable["content"])
async def finish(self) -> ToolResult:
if not self.ledger.can_finish():
return _refused("packaging has not been approved")
return ToolResult("Finishing the Execution.", TurnEnded("finish"))
def _safe_relative(name: str) -> bool:
path = PurePosixPath(name)
return bool(name) and not path.is_absolute() and ".." not in path.parts
def specialist_tools(
kind: DeliverableKind,
extra: Sequence[ToolSpec],
allow_cloud_read: bool | None,
) -> list[ToolSpec]:
"""A Specialist's tools: submit, ask, and its role's tools with the cloud-read gate."""
async def submit_deliverable(content: str, attachments: Any = None) -> ToolResult:
try:
attachments = files_from_argument(attachments)
except TypeError as exc:
return _refused(f"attachments: {exc}")
unsafe = [name for name in attachments if not _safe_relative(name)]
if unsafe:
return _refused(
"attachment names must be relative paths without '..': "
+ ", ".join(unsafe)
)
missing = check_submission(kind, content, attachments)
if missing:
return ToolResult(
"Not submitted. The Deliverable is missing: " + "; ".join(missing)
)
return ToolResult(f"Submitted {kind}.", Submitted(content, attachments))
async def needs_input(questions: Sequence[str]) -> ToolResult:
questions = tuple(q for q in questions if q)
if not questions:
return _refused("ask at least one question")
return ToolResult("Questions sent to the user.", NeedsInput(questions))
return [
ToolSpec(
"submit_deliverable",
f"Submit the {kind} Deliverable once it meets its contract. Ends your turn.",
_schema(
{
"content": {"type": "string"},
"attachments": FILES_SCHEMA,
},
["content"],
),
submit_deliverable,
tier="execution",
),
ToolSpec(
"needs_input",
"Ask the user questions you can't proceed without. Ends your turn.",
_schema(
{"questions": {"type": "array", "items": {"type": "string"}}},
["questions"],
),
needs_input,
tier="execution",
),
*(gate_cloud_read(tool, allow_cloud_read) for tool in extra),
]
def gate_cloud_read(tool: ToolSpec, allow_cloud_read: bool | None) -> ToolSpec:
"""Apply the Execution's cloud-read permission to a tool in that tier."""
if tool.tier != CLOUD_READ or allow_cloud_read is True:
return tool
if allow_cloud_read is False:
async def refuse(**_: Any) -> ToolResult:
return _refused(
"reading live cloud resources is not permitted for this Execution. "
"Work from what the user has told you and record the gap."
)
handler = refuse
else:
async def ask_permission(**_: Any) -> ToolResult:
return ToolResult(
"Permission to read live cloud resources is needed first.",
NeedsInput(
(
f"May I read live resources in your cloud environment? ({tool.name})",
),
permission=CLOUD_READ,
),
)
handler = ask_permission
return ToolSpec(tool.name, tool.description, tool.parameters, handler, tool.tier)

View File

@@ -1,346 +0,0 @@
"""Live Google Cloud Environment & Resource Scanner.
Discovers and audits existing resources in a target Google Cloud project (GCS buckets,
Compute Engine instances, Cloud SQL, Pub/Sub, Cloud Run) using Google Cloud REST APIs.
Authenticated via Application Default Credentials (ADC), Service Account keys, or gcloud CLI tokens.
"""
import json
import logging
import os
import subprocess
from typing import Any, Dict, List, Optional
import httpx
try:
import google.auth
import google.auth.transport.requests
HAS_GOOGLE_AUTH = True
except ImportError:
HAS_GOOGLE_AUTH = False
from app.config import get_settings
logger = logging.getLogger(__name__)
class GCPEnvironmentScanner:
"""Scans and audits live resources in a target Google Cloud project."""
def __init__(self, project_id: Optional[str] = None) -> None:
settings = get_settings()
self.project_id = project_id or settings.GCP_PROJECT_ID or os.getenv("GCP_PROJECT_ID")
self.timeout = httpx.Timeout(10.0)
if not self.project_id:
self._auto_detect_project()
def _auto_detect_project(self) -> None:
"""Attempt auto-detecting project ID via gcloud CLI."""
try:
cmd = ["gcloud", "config", "get-value", "project", "--quiet"]
proj = subprocess.check_output(cmd, text=True, stderr=subprocess.DEVNULL).strip()
if proj and proj != "(unset)":
self.project_id = proj
logger.info("Auto-detected GCP project_id: '%s'", proj)
except Exception:
pass
def _get_access_token(self) -> Optional[str]:
"""Obtain a valid OAuth2 bearer token from GCP_ACCESS_TOKEN env, service account key, google.auth, or gcloud CLI."""
# Method 0: Direct access token passed via environment
env_token = os.getenv("GCP_ACCESS_TOKEN")
if env_token and env_token.strip():
logger.info("Obtained GCP OAuth2 bearer token from GCP_ACCESS_TOKEN environment variable.")
return env_token.strip()
settings = get_settings()
key_path = settings.GOOGLE_APPLICATION_CREDENTIALS or os.getenv("GOOGLE_APPLICATION_CREDENTIALS")
# Method 1: Try Service Account Key file directly if specified
if key_path and os.path.isfile(key_path) and HAS_GOOGLE_AUTH:
try:
from google.oauth2 import service_account
scopes = ["https://www.googleapis.com/auth/cloud-platform"]
creds = service_account.Credentials.from_service_account_file(key_path, scopes=scopes)
auth_req = google.auth.transport.requests.Request()
creds.refresh(auth_req)
if creds.project_id and not self.project_id:
self.project_id = creds.project_id
if creds.token:
logger.info("Obtained GCP token via Service Account Key file: %s", key_path)
return creds.token
except Exception as exc:
logger.debug("Service account key auth failed for %s: %s", key_path, exc)
# Method 2: Try google.auth.default()
if HAS_GOOGLE_AUTH:
try:
creds, proj = google.auth.default(
scopes=["https://www.googleapis.com/auth/cloud-platform"]
)
auth_req = google.auth.transport.requests.Request()
creds.refresh(auth_req)
if not self.project_id and proj:
self.project_id = proj
if creds.token:
logger.info("Obtained GCP token via Application Default Credentials.")
return creds.token
except Exception as exc:
logger.debug("google.auth.default token acquisition failed: %s", exc)
# Method 3: Fallback to gcloud CLI token (with --quiet)
try:
cmd = ["gcloud", "auth", "print-access-token", "--quiet"]
token = subprocess.check_output(cmd, text=True, stderr=subprocess.DEVNULL).strip()
if token:
logger.info("Obtained GCP token via gcloud auth print-access-token --quiet.")
return token
except Exception as exc:
logger.debug("gcloud auth print-access-token fallback failed: %s", exc)
return None
def scan_environment(self) -> Dict[str, Any]:
"""Execute a full live environment scan against the target GCP project."""
token = self._get_access_token()
if not token or not self.project_id:
logger.warning(
"GCP Scanner unable to authenticate or project_id missing (project_id=%s, token_present=%s). "
"Using fallback baseline template.",
self.project_id,
bool(token),
)
return {"authenticated": False, "project_id": self.project_id, "resources": {}}
headers = {"Authorization": f"Bearer {token}"}
resources: Dict[str, Any] = {
"project_id": self.project_id,
"gcs_buckets": [],
"compute_instances": [],
"cloud_sql_instances": [],
"pubsub_topics": [],
"cloud_run_services": [],
"disabled_apis": [],
}
with httpx.Client(timeout=self.timeout) as client:
# 1. Scan GCS Buckets
try:
r = client.get(
f"https://storage.googleapis.com/storage/v1/b?project={self.project_id}",
headers=headers,
)
if r.status_code == 200:
items = r.json().get("items", [])
resources["gcs_buckets"] = [
{"name": item.get("name"), "location": item.get("location"), "storage_class": item.get("storageClass")}
for item in items
]
elif r.status_code == 403 and "SERVICE_DISABLED" in r.text:
resources["disabled_apis"].append("storage.googleapis.com")
except Exception as exc:
logger.debug("GCS scan error: %s", exc)
# 2. Scan Compute Engine Instances
try:
r = client.get(
f"https://compute.googleapis.com/compute/v1/projects/{self.project_id}/aggregated/instances",
headers=headers,
)
if r.status_code == 200:
items_dict = r.json().get("items", {})
instances = []
for zone, zone_data in items_dict.items():
for inst in zone_data.get("instances", []):
instances.append({
"name": inst.get("name"),
"zone": zone.replace("zones/", ""),
"status": inst.get("status"),
"machine_type": inst.get("machineType", "").split("/")[-1],
})
resources["compute_instances"] = instances
elif r.status_code == 403 and "SERVICE_DISABLED" in r.text:
resources["disabled_apis"].append("compute.googleapis.com")
except Exception as exc:
logger.debug("Compute Engine scan error: %s", exc)
# 3. Scan Cloud SQL Instances
try:
r = client.get(
f"https://sqladmin.googleapis.com/v1/projects/{self.project_id}/instances",
headers=headers,
)
if r.status_code == 200:
items = r.json().get("items", [])
resources["cloud_sql_instances"] = [
{
"name": item.get("name"),
"database_version": item.get("databaseVersion"),
"region": item.get("region"),
"state": item.get("state"),
}
for item in items
]
elif r.status_code == 403 and "SERVICE_DISABLED" in r.text:
resources["disabled_apis"].append("sqladmin.googleapis.com")
except Exception as exc:
logger.debug("Cloud SQL scan error: %s", exc)
# 4. Scan Pub/Sub Topics
try:
r = client.get(
f"https://pubsub.googleapis.com/v1/projects/{self.project_id}/topics",
headers=headers,
)
if r.status_code == 200:
topics = r.json().get("topics", [])
resources["pubsub_topics"] = [
{"name": t.get("name", "").split("/")[-1]} for t in topics
]
elif r.status_code == 403 and "SERVICE_DISABLED" in r.text:
resources["disabled_apis"].append("pubsub.googleapis.com")
except Exception as exc:
logger.debug("Pub/Sub scan error: %s", exc)
# 5. Scan Cloud Run Services
try:
r = client.get(
f"https://run.googleapis.com/v2/projects/{self.project_id}/locations/-/services",
headers=headers,
)
if r.status_code == 200:
services = r.json().get("services", [])
resources["cloud_run_services"] = [
{"name": s.get("name", "").split("/")[-1], "uri": s.get("uri")}
for s in services
]
elif r.status_code == 403 and "SERVICE_DISABLED" in r.text:
resources["disabled_apis"].append("run.googleapis.com")
except Exception as exc:
logger.debug("Cloud Run scan error: %s", exc)
return {"authenticated": True, "project_id": self.project_id, "resources": resources}
def format_scan_report(self, scan_result: Dict[str, Any]) -> Dict[str, str]:
"""Format live environment scan findings into markdown report and Mermaid diagram."""
if not scan_result.get("authenticated") or not scan_result.get("resources"):
# Fallback
doc = """# Pre-emptive Source Environment Discovery (As-Is Architecture)
## Existing Workload Audit
- **Workload Summary**: Event-Driven Regional Application (Legacy / Pre-existing Environment)
- **Current Hosting**: On-Premises Data Center / Legacy VM Infrastructure
- **Ingress Layer**: Self-managed NGINX Reverse Proxy listening on HTTP/HTTPS
- **Application Runtime**: Monolithic Application Instance (Single Point of Failure)
- **Database Layer**: Self-hosted PostgreSQL Instance (Unreplicated, Local Disk)
- **Queue / Messaging**: Local RabbitMQ Queue Instance
## Current Operational Pain Points & Bottlenecks
- Single-instance compute leading to downtime during maintenance windows.
- Manual scaling capabilities unable to handle unexpected traffic spikes.
- Unencrypted local storage and unmanaged backups creating data loss risks.
- Elevated operational overhead and hardware lifecycle costs.
## Source Component Topology
- `Client` -> `NGINX Proxy` -> `Monolith Application` -> `Local PostgreSQL / RabbitMQ`
"""
mmd = """flowchart TD
Client[External Client] -->|HTTP/HTTPS| NginxProxy[Legacy NGINX Proxy]
NginxProxy --> MonolithApp[Monolithic Application VM]
MonolithApp --> LocalDB[(Self-Hosted PostgreSQL)]
MonolithApp --> LocalQueue[Local RabbitMQ Queue]
"""
return {"doc": doc, "mermaid": mmd}
res = scan_result["resources"]
proj_id = res.get("project_id", "Unknown")
buckets = res.get("gcs_buckets", [])
instances = res.get("compute_instances", [])
sql_instances = res.get("cloud_sql_instances", [])
topics = res.get("pubsub_topics", [])
run_services = res.get("cloud_run_services", [])
disabled_apis = res.get("disabled_apis", [])
# Build Markdown Document
doc_lines = [
f"# Pre-emptive Live GCP Environment Discovery (Project: `{proj_id}`)",
"",
"## Live Resource Audit",
f"- **Target Google Cloud Project**: `{proj_id}`",
f"- **Discovered Storage Buckets**: {len(buckets)} GCS Bucket(s)" if buckets else "- **Discovered Storage Buckets**: None / Default Bucket",
f"- **Discovered Compute Instances**: {len(instances)} Compute VM(s)" if instances else "- **Discovered Compute Instances**: None active",
f"- **Discovered Database Instances**: {len(sql_instances)} Cloud SQL DB(s)" if sql_instances else "- **Discovered Database Instances**: None active",
f"- **Discovered Pub/Sub Topics**: {len(topics)} Topic(s)" if topics else "- **Discovered Pub/Sub Topics**: None active",
f"- **Discovered Cloud Run Services**: {len(run_services)} Service(s)" if run_services else "- **Discovered Cloud Run Services**: None active",
"",
"## Resource Inventory Breakdown",
]
if buckets:
doc_lines.append("### Cloud Storage Buckets")
for b in buckets:
doc_lines.append(f"- `b/{b['name']}` (Location: `{b['location']}`, Storage Class: `{b['storage_class']}`)")
doc_lines.append("")
if instances:
doc_lines.append("### Compute Engine Instances")
for inst in instances:
doc_lines.append(f"- VM `instance/{inst['name']}` (Zone: `{inst['zone']}`, Type: `{inst['machine_type']}`, Status: `{inst['status']}`)")
doc_lines.append("")
if sql_instances:
doc_lines.append("### Cloud SQL Databases")
for sql in sql_instances:
doc_lines.append(f"- DB `sql/{sql['name']}` (Engine: `{sql['database_version']}`, Region: `{sql['region']}`, State: `{sql['state']}`)")
doc_lines.append("")
if topics:
doc_lines.append("### Cloud Pub/Sub Topics")
for t in topics:
doc_lines.append(f"- Topic `pubsub/{t['name']}`")
doc_lines.append("")
if run_services:
doc_lines.append("### Cloud Run Services")
for s in run_services:
doc_lines.append(f"- Service `run/{s['name']}` (URI: `{s['uri']}`)")
doc_lines.append("")
if disabled_apis:
doc_lines.append("### API Status Diagnostics")
for api in disabled_apis:
doc_lines.append(f"- `SERVICE_DISABLED`: `{api}` is not enabled on project `{proj_id}`.")
doc_lines.append("")
doc_lines.extend([
"## Current Operational Bottlenecks & Migration Drivers",
"- As-is infrastructure requires serverless auto-scaling and managed high availability.",
"- Need for declarative IaC management via Terraform.",
"- Transition to least-privilege IAM service identities and automated CI validation.",
])
# Build Mermaid Diagram
mmd_lines = ["flowchart TD", f" subgraph GCPProject[\"Google Cloud Project: {proj_id}\"]"]
if buckets:
for i, b in enumerate(buckets[:3]):
mmd_lines.append(f" GCS{i}[(\"GCS: {b['name']}\")]")
if instances:
for i, inst in enumerate(instances[:3]):
mmd_lines.append(f" VM{i}[\"GCE: {inst['name']}\"]")
if sql_instances:
for i, sql in enumerate(sql_instances[:3]):
mmd_lines.append(f" SQL{i}[(\"Cloud SQL: {sql['name']}\")]")
if topics:
for i, t in enumerate(topics[:3]):
mmd_lines.append(f" PubSub{i}[\"PubSub: {t['name']}\"]")
if run_services:
for i, s in enumerate(run_services[:3]):
mmd_lines.append(f" Run{i}[\"Cloud Run: {s['name']}\"]")
if not (buckets or instances or sql_instances or topics or run_services):
mmd_lines.append(f" EmptyProject[\"Project {proj_id} (No Active Resources Detected)\"]")
mmd_lines.append(" end")
mmd_lines.append(" Client[External Traffic] --> GCPProject")
return {"doc": "\n".join(doc_lines), "mermaid": "\n".join(mmd_lines)}

View File

@@ -10,12 +10,12 @@ import asyncio
import os
import re
import tempfile
from collections.abc import Iterable, Mapping
from collections.abc import Awaitable, Callable, Iterable, Mapping
from dataclasses import dataclass
from pathlib import Path, PurePosixPath
from typing import Any
from app.agents.runtime import ToolResult, ToolSpec
from app.adk.runtime import FILES_SCHEMA, ToolResult, ToolSpec, files_from_argument
_MAX_OUTPUT = 8_000
_TERRAFORM_SUFFIXES = (".tf", ".tfvars", ".tf.json")
@@ -108,7 +108,7 @@ class TerraformRunner:
if refusal:
return refusal
with tempfile.TemporaryDirectory(prefix="tf-validate-") as tmp:
root = _write(Path(tmp), files)
root = _write(Path(tmp), files) / _module_dir(files)
failure = await self._init(root)
if failure:
return failure
@@ -127,7 +127,7 @@ class TerraformRunner:
if bad:
return ToolResult(f"Refused: invalid variable names {', '.join(bad)}")
with tempfile.TemporaryDirectory(prefix="tf-plan-") as tmp:
root = _write(Path(tmp), files)
root = _write(Path(tmp), files) / _module_dir(files)
failure = await self._init(root)
if failure:
return failure
@@ -198,9 +198,20 @@ def _check_files(files: Mapping[str, str]) -> ToolResult | None:
"Refused: file names must be relative .tf, .tf.json or .tfvars paths "
f"without '..': {', '.join(bad)}"
)
directories = {str(PurePosixPath(name).parent) for name in files}
if len(directories) > 1:
return ToolResult(
"Refused: put all files in one directory (one root module), for example "
f"terraform/main.tf and terraform/variables.tf; got {', '.join(sorted(directories))}"
)
return None
def _module_dir(files: Mapping[str, str]) -> str:
"""The one directory holding the files; Terraform runs there."""
return str(PurePosixPath(next(iter(files))).parent)
def _write(root: Path, files: Mapping[str, str]) -> Path:
for name, content in files.items():
target = root / name
@@ -214,11 +225,26 @@ def _clip(text: str) -> str:
_FILES_SCHEMA: dict[str, Any] = {
"type": "object",
"description": "Terraform files by relative path, e.g. {'main.tf': '...'}",
"additionalProperties": {"type": "string"},
**FILES_SCHEMA,
"description": "Terraform files in one directory, e.g. terraform/main.tf",
}
def _with_files(
method: Callable[..., Awaitable[ToolResult]],
) -> Callable[..., Awaitable[ToolResult]]:
"""Adapt a runner method to take the FILES_SCHEMA argument."""
async def handler(files: Any, **kwargs: Any) -> ToolResult:
try:
converted = files_from_argument(files)
except TypeError as exc:
return ToolResult(f"Refused: files: {exc}")
return await method(converted, **kwargs)
return handler
LOCAL_TOOLS: dict[str, tuple[str, str]] = {
"mermaid_check": ("general", "Check a Mermaid diagram's basic structure."),
"terraform_fmt": ("general", "Format Terraform files and return any that changed."),
@@ -254,7 +280,7 @@ def local_tools(names: Iterable[str], runner: TerraformRunner) -> list[ToolSpec]
"properties": {"files": _FILES_SCHEMA},
"required": ["files"],
},
runner.fmt,
_with_files(runner.fmt),
tier="general",
),
"terraform_validate": lambda: ToolSpec(
@@ -265,7 +291,7 @@ def local_tools(names: Iterable[str], runner: TerraformRunner) -> list[ToolSpec]
"properties": {"files": _FILES_SCHEMA},
"required": ["files"],
},
runner.validate,
_with_files(runner.validate),
tier="general",
),
"terraform_plan": lambda: ToolSpec(
@@ -282,7 +308,7 @@ def local_tools(names: Iterable[str], runner: TerraformRunner) -> list[ToolSpec]
},
"required": ["files"],
},
runner.plan,
_with_files(runner.plan),
tier="cloud_read",
),
}

View File

@@ -22,7 +22,7 @@ from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client
from mcp.shared._httpx_utils import create_mcp_http_client
from app.agents.runtime import ToolResult, ToolSpec
from app.adk.runtime import ToolResult, ToolSpec
from app.providers import McpServerSpec
logger = logging.getLogger(__name__)

View File

@@ -1,258 +0,0 @@
"""Google Developer Knowledge MCP (Model Context Protocol) Client & Tools.
Provides integration with the Google Developer Knowledge MCP server (https://developerknowledge.googleapis.com/mcp).
Implements official MCP tools:
- developerknowledge:search_documents
- developerknowledge:get_documents
- developerknowledge:answer_query
Supports live HTTP/JSON-RPC MCP requests with built-in offline GCP knowledge fallback
for offline testing and high availability.
"""
import logging
from typing import Any, Dict, List, Optional
import httpx
from langchain_core.tools import tool
from app.config import get_settings
logger = logging.getLogger(__name__)
# Fallback Offline GCP Developer Knowledge Base
OFFLINE_GCP_KNOWLEDGE_BASE: Dict[str, Dict[str, Any]] = {
"cloud_run": {
"title": "Google Cloud Run Architecture Guide",
"uri": "https://cloud.google.com/run/docs/overview/what-is-cloud-run",
"release_status": "GA (General Availability)",
"category": "compute",
"summary": "Stateless container execution platform with automatic scaling from zero to thousands of instances, built on Knative.",
"citations": ["https://cloud.google.com/run/docs/securing/service-identity"],
},
"pubsub": {
"title": "Google Cloud Pub/Sub Messaging Best Practices",
"uri": "https://cloud.google.com/pubsub/docs/overview",
"release_status": "GA (General Availability)",
"category": "messaging",
"summary": "Globally distributed, asynchronous message bus providing at-least-once delivery with dead-letter topics and exponential backoff.",
"citations": ["https://cloud.google.com/pubsub/docs/dead-letter-topics"],
},
"storage": {
"title": "Google Cloud Storage Object Lifecycle & Security",
"uri": "https://cloud.google.com/storage/docs/overview",
"release_status": "GA (General Availability)",
"category": "storage",
"summary": "Unified object storage with uniform bucket-level access, retention lifecycle rules, customer-managed encryption (CMEK), and audit logging.",
"citations": ["https://cloud.google.com/storage/docs/uniform-bucket-level-access"],
},
"firestore": {
"title": "Google Cloud Firestore Document Database",
"uri": "https://cloud.google.com/firestore/docs/overview",
"release_status": "GA (General Availability)",
"category": "database",
"summary": "Serverless, flexible NoSQL document database built for automatic scaling, rich queries, and ACID multi-document transactions.",
"citations": ["https://cloud.google.com/firestore/docs/best-practices"],
},
"iam": {
"title": "Google Cloud IAM Least-Privilege Identity Guide",
"uri": "https://cloud.google.com/iam/docs/overview",
"release_status": "GA (General Availability)",
"category": "security",
"summary": "Fine-grained access control and least-privilege service identity management for Google Cloud resources.",
"citations": ["https://cloud.google.com/iam/docs/using-iam-securely"],
},
}
class DeveloperKnowledgeMCPClient:
"""Client for Google Developer Knowledge MCP server."""
def __init__(self, mcp_url: Optional[str] = None) -> None:
settings = get_settings()
self.mcp_url = mcp_url or settings.DEVELOPER_KNOWLEDGE_MCP_URL
self.enabled = settings.DEVELOPER_KNOWLEDGE_MCP_ENABLED
self.timeout = httpx.Timeout(5.0)
def search_documents(self, query: str, category: str = "all") -> Dict[str, Any]:
"""Search Google Cloud reference architecture, decision-making, and best-practice documents."""
if self.enabled and self.mcp_url:
try:
payload = {
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "developerknowledge:search_documents",
"arguments": {"query": query, "category": category},
},
"id": 1,
}
with httpx.Client(timeout=self.timeout) as client:
resp = client.post(self.mcp_url, json=payload)
if resp.status_code == 200:
data = resp.json()
if "result" in data:
return {"source": "live_mcp", "data": data["result"]}
except Exception as exc:
logger.debug("Live MCP search_documents query failed (%s); using offline knowledge base.", exc)
# Offline fallback search
results = []
q_lower = query.lower()
for key, doc in OFFLINE_GCP_KNOWLEDGE_BASE.items():
if (
q_lower in doc["title"].lower()
or q_lower in doc["summary"].lower()
or q_lower in doc["category"].lower()
or category == "all"
or category == doc["category"]
):
results.append(doc)
return {
"source": "offline_fallback",
"query": query,
"category": category,
"total_matches": len(results),
"documents": results,
}
def get_documents(self, document_uri: str) -> Dict[str, Any]:
"""Fetch official Google Cloud document content and citations by URI."""
if self.enabled and self.mcp_url:
try:
payload = {
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "developerknowledge:get_documents",
"arguments": {"document_uri": document_uri},
},
"id": 2,
}
with httpx.Client(timeout=self.timeout) as client:
resp = client.post(self.mcp_url, json=payload)
if resp.status_code == 200:
data = resp.json()
if "result" in data:
return {"source": "live_mcp", "data": data["result"]}
except Exception as exc:
logger.debug("Live MCP get_documents query failed (%s); using offline knowledge base.", exc)
# Search matching offline doc
for doc in OFFLINE_GCP_KNOWLEDGE_BASE.values():
if document_uri in doc["uri"] or doc["uri"] in document_uri:
return {"source": "offline_fallback", "document": doc}
return {
"source": "offline_fallback",
"document_uri": document_uri,
"document": {
"title": f"Google Cloud Documentation ({document_uri})",
"uri": document_uri,
"release_status": "GA",
"summary": "Official Google Cloud architecture reference documentation.",
"citations": [document_uri],
},
}
def answer_query(self, query: str) -> Dict[str, Any]:
"""Answer architectural questions and check GCP product release statuses and best practices."""
if self.enabled and self.mcp_url:
try:
payload = {
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "developerknowledge:answer_query",
"arguments": {"query": query},
},
"id": 3,
}
with httpx.Client(timeout=self.timeout) as client:
resp = client.post(self.mcp_url, json=payload)
if resp.status_code == 200:
data = resp.json()
if "result" in data:
return {"source": "live_mcp", "answer": data["result"]}
except Exception as exc:
logger.debug("Live MCP answer_query failed (%s); using offline knowledge base.", exc)
# Offline grounding logic
q_lower = query.lower()
if "release status" in q_lower or "deprecated" in q_lower:
return {
"source": "offline_fallback",
"query": query,
"status_check": "All recommended products (Cloud Run, Pub/Sub, Cloud Storage, Firestore, Cloud IAM) are Active GA (General Availability). None are deprecated.",
"supported": True,
}
return {
"source": "offline_fallback",
"query": query,
"answer": (
"Google Cloud Architecture Best Practice: Design regional event-driven workloads "
"using Cloud Run for stateless container execution, Pub/Sub for asynchronous message buffering, "
"and Cloud Storage / Firestore for durable state retention under least-privilege IAM."
),
"citations": ["https://cloud.google.com/architecture/framework"],
}
# Singleton client instance
_mcp_client: Optional[DeveloperKnowledgeMCPClient] = None
def get_mcp_client() -> DeveloperKnowledgeMCPClient:
"""Get singleton DeveloperKnowledgeMCPClient."""
global _mcp_client
if _mcp_client is None:
_mcp_client = DeveloperKnowledgeMCPClient()
return _mcp_client
# ---------------------------------------------------------------------------
# LangChain @tool wrappers matching official Google spec
# ---------------------------------------------------------------------------
@tool
def developerknowledge_search_documents(query: str, category: str = "all") -> Dict[str, Any]:
"""Searches Google Cloud reference architecture, decision-making, and best-practice documents.
Args:
query: Search query string (e.g. 'Cloud Run PubSub event architecture').
category: Optional category filter ('compute', 'messaging', 'storage', 'security', or 'all').
Returns:
Dict containing matching Google Cloud documents and citations.
"""
client = get_mcp_client()
return client.search_documents(query=query, category=category)
@tool
def developerknowledge_get_documents(document_uri: str) -> Dict[str, Any]:
"""Retrieves official Google Cloud document content and citations by URI.
Args:
document_uri: Official Google Cloud documentation URL or document identifier.
Returns:
Dict containing document metadata, summary, and citations.
"""
client = get_mcp_client()
return client.get_documents(document_uri=document_uri)
@tool
def developerknowledge_answer_query(query: str) -> Dict[str, Any]:
"""Answers architectural questions and checks GCP product release statuses and best practices.
Args:
query: Architectural question or product status query string.
Returns:
Dict containing grounded answer, release status, and documentation citations.
"""
client = get_mcp_client()
return client.answer_query(query=query)

111
app/tools/pillars.py Normal file
View File

@@ -0,0 +1,111 @@
"""The design advisor's fan-out to one advisor per architecture-framework pillar.
Pillar advice is working material for the design recommendations Deliverable, not a
Deliverable itself, so it never touches the Ledger.
"""
from __future__ import annotations
import asyncio
import dataclasses
from collections.abc import Mapping, Sequence
from app.adk.runtime import (
AgentRuntime,
AgentTask,
RoleSpec,
Submitted,
ToolResult,
ToolSpec,
)
CONSULT_TOOL = "consult_pillar_advisors"
def pillar_consultation_tool(
runtime: AgentRuntime,
advisor: RoleSpec,
pillar_skills: Mapping[str, str],
extra_tools: Sequence[ToolSpec] = (),
) -> ToolSpec:
"""A tool that runs one pillar advisor per pillar, in parallel, each with its Skill."""
async def consult(brief: str, pillars: Sequence[str] | None = None) -> ToolResult:
chosen = list(pillars) if pillars else list(pillar_skills)
unknown = [pillar for pillar in chosen if pillar not in pillar_skills]
if unknown:
return ToolResult(
f"Refused: unknown pillars {', '.join(unknown)}; "
f"choose from {', '.join(pillar_skills)}"
)
results = await asyncio.gather(
*(
_advise(
runtime, advisor, pillar, pillar_skills[pillar], brief, extra_tools
)
for pillar in chosen
)
)
return ToolResult("\n\n".join(results))
return ToolSpec(
CONSULT_TOOL,
"Get guidance from one advisor per architecture-framework pillar, in parallel. "
"Give a brief with the workload, its requirements and the selected products.",
{
"type": "object",
"properties": {
"brief": {"type": "string"},
"pillars": {
"type": "array",
"items": {"type": "string", "enum": list(pillar_skills)},
},
},
"required": ["brief"],
},
consult,
)
async def _advise(
runtime: AgentRuntime,
advisor: RoleSpec,
pillar: str,
skill: str,
brief: str,
extra_tools: Sequence[ToolSpec],
) -> str:
role = dataclasses.replace(advisor, skills=(skill,))
task = AgentTask(
role=advisor.name,
prompt=f"Advise on the {pillar} pillar for this workload.",
context={"pillar": pillar, "brief": brief},
)
try:
outcome = await runtime.run(role, task, [_submit_advice_tool(), *extra_tools])
except Exception as exc: # noqa: BLE001 - one failed advisor must not lose the others
return f"## {pillar}\n\nNo guidance: the advisor failed ({exc})."
if isinstance(outcome, Submitted):
return f"## {pillar}\n\n{outcome.content.strip()}"
return (
f"## {pillar}\n\nNo guidance: the advisor ended with {type(outcome).__name__}."
)
def _submit_advice_tool() -> ToolSpec:
async def submit_advice(content: str) -> ToolResult:
if not content.strip():
return ToolResult("Not submitted: the advice is empty.")
return ToolResult("Advice submitted.", Submitted(content))
return ToolSpec(
"submit_advice",
"Submit your pillar recommendations as markdown. Ends your turn.",
{
"type": "object",
"properties": {"content": {"type": "string"}},
"required": ["content"],
},
submit_advice,
tier="execution",
)

48
app/tools/toolkit.py Normal file
View File

@@ -0,0 +1,48 @@
"""Which tools each role gets beyond the Execution tools.
A role gets the local tools its role file names, the tools of the remote MCP servers
the provider bundle assigns it, and, for the design advisor, the pillar consultation.
Cloud-read gating is applied later, per Execution, by `specialist_tools`.
"""
from __future__ import annotations
from collections.abc import Mapping, Sequence
from app.adk.roles import PILLAR_ADVISOR
from app.adk.runtime import AgentRuntime, RoleSpec, ToolFactory, ToolSpec
from app.tools.mcp import McpCatalog
from app.tools.pillars import pillar_consultation_tool
from app.workflows.deliverables import DeliverableKind
def make_tool_factory(
runtime: AgentRuntime,
roles: Mapping[str, RoleSpec],
pillar_skills: Mapping[str, str],
*,
local_tools: Sequence[ToolSpec] = (),
catalog: McpCatalog | None = None,
) -> ToolFactory:
local_by_name = {tool.name: tool for tool in local_tools}
def mcp_tools(role: RoleSpec) -> list[ToolSpec]:
return catalog.tools_for(role.mcp_servers) if catalog else []
consult = None
advisor = roles.get(PILLAR_ADVISOR)
if pillar_skills and advisor:
# Pillar advisors can't ask for permission, so they get general-tier tools only.
advisor_tools = [tool for tool in mcp_tools(advisor) if tool.tier == "general"]
consult = pillar_consultation_tool(
runtime, advisor, pillar_skills, extra_tools=advisor_tools
)
def tools_for(role: RoleSpec, deliverable: str | None) -> Sequence[ToolSpec]:
tools = [local_by_name[name] for name in role.tools if name in local_by_name]
tools += mcp_tools(role)
if consult and deliverable == DeliverableKind.DESIGN_RECOMMENDATIONS.value:
tools.append(consult)
return tools
return tools_for

View File

@@ -1,124 +0,0 @@
"""LangChain decorated tools for artifact and schema validation."""
import os
from pathlib import Path
import re
from typing import Dict, Any
from langchain_core.tools import tool
@tool
def validate_mermaid_diagram(diagram_content: str) -> Dict[str, Any]:
"""Validates the syntax and graph structure of a Mermaid diagram.
Args:
diagram_content: Raw text content of the Mermaid diagram file.
Returns:
Dict with status, valid boolean, and error details if any.
"""
if not diagram_content or not diagram_content.strip():
return {"valid": False, "error": "Mermaid diagram is empty."}
if not re.search(r"\b(flowchart|graph)\b", diagram_content):
return {
"valid": False,
"error": "Mermaid diagram must start with 'flowchart' or 'graph'.",
}
# Basic bracket matching check
open_brackets = diagram_content.count("[") + diagram_content.count("(") + diagram_content.count("{")
close_brackets = diagram_content.count("]") + diagram_content.count(")") + diagram_content.count("}")
if open_brackets != close_brackets:
return {
"valid": False,
"error": "Mismatched brackets in Mermaid diagram syntax.",
}
return {"valid": True, "message": "Mermaid diagram syntax is valid."}
@tool
def validate_terraform_syntax(terraform_content: str) -> Dict[str, Any]:
"""Validates Terraform HCL basic structure and required Google Cloud blocks.
Args:
terraform_content: Raw HCL text content of main.tf.
Returns:
Dict with valid boolean and diagnostic information.
"""
if not terraform_content or not terraform_content.strip():
return {"valid": False, "error": "Terraform configuration is empty."}
if "resource" not in terraform_content and "module" not in terraform_content:
return {
"valid": False,
"error": "Terraform configuration must contain at least one resource or module block.",
}
return {"valid": True, "message": "Terraform HCL structural check passed."}
@tool
def validate_repository_artifacts(target_dir: str) -> Dict[str, Any]:
"""Executes full offline validation against solution architecture artifacts in a directory.
Args:
target_dir: Directory path containing the solution architecture repository.
Returns:
Dict containing validation pass status and missing items list.
"""
root = Path(target_dir)
def find_artifact(filename):
search_dirs = [
root / "deliverables" / "as-is",
root / "deliverables" / "target",
root / "deliverables" / "validation",
root / "deliverables" / "guides",
root / "deliverables",
root / "docs",
root,
]
for d in search_dirs:
candidate = d / filename
if candidate.is_file():
return candidate
return None
required_names = ["requirements.md", "architecture.md", "architecture.mmd", "solution-architecture-guide.md"]
missing = []
for fname in required_names:
if not find_artifact(fname):
missing.append(fname)
if not (root / "terraform/main.tf").is_file():
missing.append("terraform/main.tf")
if not (root / "terraform/variables.tf").is_file():
missing.append("terraform/variables.tf")
guide_path = find_artifact("solution-architecture-guide.md")
if guide_path:
guide_text = guide_path.read_text(encoding="utf-8")
required_sections = ["Functional requirements", "Selected products", "Validation results", "Terraform", "Mermaid"]
for section in required_sections:
if section not in guide_text:
missing.append(f"Guide section missing: {section}")
else:
missing.append("solution-architecture-guide.md missing")
mmd_path = find_artifact("architecture.mmd")
if mmd_path:
mmd_text = mmd_path.read_text(encoding="utf-8")
if not re.search(r"flowchart|graph", mmd_text):
missing.append("Invalid Mermaid graph directive in architecture.mmd")
passed = len(missing) == 0
return {
"valid": passed,
"missing_items": missing,
"message": "All required architecture artifacts valid." if passed else f"Validation failed for: {', '.join(missing)}",
}