fixed multile issues
Some checks failed
validation / verify (push) Failing after 8s

This commit is contained in:
2026-10-07 17:33:36 +01:00
parent 4c4d44ef87
commit 5bb22d984e
76 changed files with 5799 additions and 179 deletions

View File

@@ -7,8 +7,7 @@ outcome.
from __future__ import annotations
from collections.abc import Mapping, Sequence
from pathlib import PurePosixPath
from collections.abc import Mapping, MutableMapping, Sequence
from typing import Any
from app.adk.runtime import (
@@ -21,6 +20,14 @@ from app.adk.runtime import (
files_from_argument,
)
from app.states.ledger import Ledger, LedgerRefusal, PhaseStatus
from app.tools.workspace import (
file_tools,
graph_text,
graph_tools,
keep_graph,
safe_relative,
working_files,
)
from app.workflows.deliverables import (
DEPENDENCY_GRAPH,
DeliverableKind,
@@ -35,6 +42,7 @@ from app.workflows.target_architecture import (
TargetArchitecture,
parse_graph,
render_mermaid,
render_tables,
)
ORCHESTRATOR = "orchestrator"
@@ -244,29 +252,37 @@ class OrchestratorToolbox:
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,
upstream: Mapping[str, Mapping[str, Any]] | None = None,
working: MutableMapping[str, Any] | None = None,
library: Mapping[str, Mapping[str, Any]] | None = None,
) -> list[ToolSpec]:
"""A Specialist's tools: submit, ask, and its role's tools with the cloud-read gate.
"""A Specialist's tools: submit, ask, its working copy, and its role's tools with
the cloud-read gate.
`upstream` is the Deliverables this one builds on; with it, a submission's links
along the Requirements chain are checked.
along the Requirements chain are checked. `working` is the Deliverable's working
memory, where its working copy is kept. `library` is the earlier Deliverables
given to the Specialist as data files alone, to read whole when it needs one.
"""
working = {} if working is None else working
is_graph = kind is DeliverableKind.TARGET_ARCHITECTURE
own_files = DEPENDENCY_GRAPH[kind].working_copy is kind
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)]
# The working copy is the submission; a file passed here replaces its copy.
if own_files:
attachments = {**working_files(working), **attachments}
if is_graph and GRAPH_ATTACHMENT not in attachments and graph_text(working):
attachments[GRAPH_ATTACHMENT] = graph_text(working)
unsafe = [name for name in attachments if not safe_relative(name)]
if unsafe:
return _refused(
"attachment names must be relative paths without '..': "
@@ -277,13 +293,27 @@ def specialist_tools(
return ToolResult(
"Not submitted. The Deliverable is missing: " + "; ".join(missing)
)
if kind is DeliverableKind.TARGET_ARCHITECTURE:
# The diagram is a view of the graph, so the engine draws it.
attachments[DIAGRAM_ATTACHMENT] = render_mermaid(
parse_graph(attachments[GRAPH_ATTACHMENT])
)
if own_files:
working_files(working).update(attachments)
if is_graph:
# The tables and the diagram are views of the graph, so the engine
# writes them: they cannot disagree with it.
graph = parse_graph(attachments[GRAPH_ATTACHMENT])
keep_graph(working, attachments[GRAPH_ATTACHMENT])
content = content.rstrip() + "\n\n" + render_tables(graph)
attachments[DIAGRAM_ATTACHMENT] = render_mermaid(graph)
return ToolResult(f"Submitted {kind}.", Submitted(content, attachments))
async def read_deliverable(kind: str) -> ToolResult:
deliverable = (library or {}).get(kind)
if deliverable is None:
available = ", ".join(library or {}) or "none"
return _refused(f"{kind} is not one you can read here: {available}")
attached = ", ".join(deliverable.get("attachments", {})) or "none"
return ToolResult(
f"{deliverable.get('content', '')}\n\nAttachments: {attached}"
)
async def needs_input(
questions: Sequence[str], draft: str | None = None, attachments: Any = None
) -> ToolResult:
@@ -331,6 +361,23 @@ def specialist_tools(
needs_input,
tier="execution",
),
*(
[
ToolSpec(
"read_deliverable",
"Read the full text of an earlier Deliverable that `dependencies` "
"gives you as its data file alone: "
f"{', '.join(library)}. Use it only when the ids are not enough.",
_schema({"kind": {"type": "string"}}, ["kind"]),
read_deliverable,
tier="execution",
)
]
if library
else ()
),
*(graph_tools(working) if is_graph else ()),
*(file_tools(working) if own_files else ()),
*(gate_cloud_read(tool, allow_cloud_read) for tool in extra),
]

327
app/tools/jev.py Normal file
View File

@@ -0,0 +1,327 @@
"""The Jev decision client: typed answers to closed questions, within strict limits.
Jev is TypeSafe AI's decision model. This module is the only one that speaks to it,
through the vendor's Python SDK (`typesafe-sdk`), which owns the request shape, the
timeout and the retries. Everything else here is ours: the service's limits are not
published, so the client assumes they are strict and never lets Jev hold up an
Execution. Any refusal, failure or timeout returns None and the caller takes its
fallback.
"""
from __future__ import annotations
import asyncio
import hashlib
import json
import logging
import time
from collections import OrderedDict, deque
from collections.abc import Awaitable, Callable, Mapping
from dataclasses import dataclass, field
from typing import Any
from typesafe_sdk import (
AsyncTypeSafeClient,
Choice,
ChoiceAnswer,
Noul,
NoulAnswer,
RetryPolicy,
Score,
ScoreAnswer,
TypeSafeError,
TypeSafeRateLimitError,
)
from app.adk.runtime import Answer, Question
logger = logging.getLogger(__name__)
@dataclass(frozen=True)
class JevLimits:
"""Every limit the client keeps. Starting values, to tune from measurement."""
max_tokens: int = 48_000 # state plus questions; the service allows 64,000
max_question_tokens: int = 24_000 # state plus the longest question; allows 32,000
request_timeout: float = 5.0 # one HTTP attempt
total_timeout: float = 15.0 # a decision, retries included
retries: int = 2
backoff_base: float = 0.5
backoff_cap: float = 8.0
requests_per_second: float = 5.0
burst: int = 10
max_in_flight: int = 8
breaker_failures: int = 5
breaker_window: float = 30.0
breaker_cooldown: float = 60.0
cache_size: int = 1024
budget_calls: int = 500 # per scope, usually one Execution
budget_tokens: int = 1_000_000 # per scope; about $0.42 at the published price
@dataclass
class DecisionRecord:
"""One attempt to decide, kept for the evaluation report and for tuning."""
scope: str
questions: tuple[str, ...]
# answered | cached | too_large | over_budget | breaker_open | failed
outcome: str = "failed"
seconds: float = 0.0
rate_limited: bool = False
input_tokens: int = 0
confidence: Mapping[str, float] = field(default_factory=dict)
def estimate_tokens(text: str) -> int:
"""A deliberately high estimate: refusing locally is cheaper than a rejected call."""
return len(text) // 3 + 1
def encode_question(question: Question) -> Noul | Choice | Score:
if question.kind == "choice":
return Choice(
instructions=question.instructions,
criteria=dict.fromkeys(question.options),
)
if question.kind == "score":
return Score(
instructions=question.instructions, criteria=list(question.options)
)
return Noul(instructions=question.instructions)
def decode_answer(question: Question, raw: object) -> Answer | None:
"""The SDK's answer as ours, or None when it does not answer the question asked."""
if question.kind == "choice" and isinstance(raw, ChoiceAnswer):
# A choice outside the options asked for is not an answer.
if raw.choice not in question.options:
return None
return Answer(raw.choice, raw.confidence, dict(raw.probabilities))
if question.kind == "score" and isinstance(raw, ScoreAnswer):
probabilities = {str(level): p for level, p in raw.probabilities.items()}
return Answer(raw.score, raw.confidence, probabilities)
if question.kind == "noul" and isinstance(raw, NoulAnswer):
# Jev gives a probability for a yes-or-no question and no separate
# confidence, so confidence is how far the probability is from even.
return Answer(raw.noul, abs(2 * raw.noul - 1))
return None
class JevDecider:
def __init__(
self,
*,
api_key: str,
base_url: str | None = None,
model: str | None = None,
limits: JevLimits | None = None,
transport: Any = None,
clock: Callable[[], float] = time.monotonic,
sleep: Callable[[float], Awaitable[None]] = asyncio.sleep,
) -> None:
self.limits = limits or JevLimits()
self._clock = clock
self._sleep = sleep
self._client = AsyncTypeSafeClient(
api_key=api_key,
base_url=base_url,
model=model,
timeout=self.limits.request_timeout,
# The SDK retries 408, 429 and 5xx, and connection and timeout errors,
# with jittered backoff, and honours Retry-After.
retry=RetryPolicy(
max_retries=self.limits.retries,
backoff_initial=self.limits.backoff_base,
backoff_max=self.limits.backoff_cap,
timeout=self.limits.total_timeout,
),
transport=transport,
)
self._in_flight = asyncio.Semaphore(self.limits.max_in_flight)
# Token bucket: starts full, refills at `rate`, which drops when the service
# says we are going too fast.
self._rate = self.limits.requests_per_second
self._tokens = float(self.limits.burst)
self._refilled = clock()
self._bucket = asyncio.Lock()
self._failures: deque[float] = deque()
self._open_until = 0.0
self._probing = False
self._cache: OrderedDict[str, dict[str, Answer]] = OrderedDict()
self._calls: dict[str, int] = {}
self._tokens_used: dict[str, int] = {}
self._over_budget: set[str] = set()
self.records: list[DecisionRecord] = []
async def aclose(self) -> None:
await self._client.aclose()
async def decide(
self, state: str, questions: Mapping[str, Question], *, scope: str = ""
) -> Mapping[str, Answer] | None:
record = DecisionRecord(scope=scope, questions=tuple(questions))
self.records.append(record)
started = self._clock()
try:
return await self._decide(state, questions, scope, record)
finally:
record.seconds = self._clock() - started
async def _decide(
self,
state: str,
questions: Mapping[str, Question],
scope: str,
record: DecisionRecord,
) -> Mapping[str, Answer] | None:
if not questions:
record.outcome = "answered"
return {}
asked = {
name: {
"kind": question.kind,
"instructions": question.instructions,
"options": list(question.options),
}
for name, question in questions.items()
}
sizes = [estimate_tokens(json.dumps(item)) for item in asked.values()]
state_size = estimate_tokens(state)
if (
state_size + sum(sizes) > self.limits.max_tokens
or state_size + max(sizes) > self.limits.max_question_tokens
):
# Never truncate: the caller must split by Deliverable or section.
record.outcome = "too_large"
return None
key = hashlib.sha256(
json.dumps({"state": state, "questions": asked}, sort_keys=True).encode()
).hexdigest()
if key in self._cache:
self._cache.move_to_end(key)
record.outcome = "cached"
return dict(self._cache[key])
if (
self._calls.get(scope, 0) >= self.limits.budget_calls
or self._tokens_used.get(scope, 0) >= self.limits.budget_tokens
):
if scope not in self._over_budget:
self._over_budget.add(scope)
logger.warning("Jev budget reached for %s; using fallbacks", scope)
record.outcome = "over_budget"
return None
if not self._breaker_allows():
record.outcome = "breaker_open"
return None
self._calls[scope] = self._calls.get(scope, 0) + 1
await self._take_token()
try:
async with self._in_flight:
response = await self._client.system_one(
state=state,
questions={
name: encode_question(question)
for name, question in questions.items()
},
)
except TypeSafeRateLimitError:
# Still rate limited after the SDK's retries: halve our own rate.
record.rate_limited = True
self._rate = max(self._rate / 2, 0.25)
self._note_failure()
return None
except TypeSafeError as exc:
logger.info("Jev request failed: %s", type(exc).__name__)
self._note_failure()
return None
self._note_success()
used = response.usage.input_tokens or 0
record.input_tokens = used
self._tokens_used[scope] = self._tokens_used.get(scope, 0) + used
answers: dict[str, Answer] = {}
for name, question in questions.items():
answer = decode_answer(question, response.answers.get(name))
if answer is None:
# A reply that does not answer every question answers none.
return None
answers[name] = answer
record.outcome = "answered"
record.confidence = {name: a.confidence for name, a in answers.items()}
self._cache[key] = answers
while len(self._cache) > self.limits.cache_size:
self._cache.popitem(last=False)
return dict(answers)
async def _take_token(self) -> None:
async with self._bucket:
while True:
now = self._clock()
self._tokens = min(
float(self.limits.burst),
self._tokens + (now - self._refilled) * self._rate,
)
self._refilled = now
if self._tokens >= 1:
self._tokens -= 1
return
await self._sleep((1 - self._tokens) / self._rate)
def _breaker_allows(self) -> bool:
now = self._clock()
if now < self._open_until:
return False
if self._open_until and not self._probing:
# Cool-down over: let exactly one call through to test the service.
self._probing = True
return True
def _note_failure(self) -> None:
now = self._clock()
if self._probing:
self._probing = False
self._open_until = now + self.limits.breaker_cooldown
return
self._failures.append(now)
while self._failures and now - self._failures[0] > self.limits.breaker_window:
self._failures.popleft()
if len(self._failures) >= self.limits.breaker_failures:
self._failures.clear()
self._open_until = now + self.limits.breaker_cooldown
logger.warning(
"Jev circuit open for %.0fs after repeated failures",
self.limits.breaker_cooldown,
)
def _note_success(self) -> None:
self._failures.clear()
self._open_until = 0.0
self._probing = False
def summary(self) -> dict[str, Any]:
"""Totals for the evaluation report."""
outcomes: dict[str, int] = {}
for record in self.records:
outcomes[record.outcome] = outcomes.get(record.outcome, 0) + 1
answered = [r for r in self.records if r.outcome == "answered"]
return {
"decisions": len(self.records),
"outcomes": outcomes,
"fallbacks": sum(
count
for name, count in outcomes.items()
if name not in {"answered", "cached"}
),
"rate_limited": sum(1 for r in self.records if r.rate_limited),
"seconds": round(sum(r.seconds for r in answered), 3),
"input_tokens": sum(r.input_tokens for r in self.records),
}

View File

@@ -1,16 +1,23 @@
"""Local tools: a Mermaid syntax check and Terraform checks in a scratch directory.
Terraform runs only fmt, init -backend=false, validate and plan. No command that
changes cloud resources is ever constructed.
Terraform runs only fmt, init -backend=false, validate, plan and providers schema. No
command that changes cloud resources is ever constructed.
A Specialist with a working copy (app/tools/workspace.py) runs the checks on it and
passes no files; `terraform_fmt` formats the working copy in place. That is what
keeps a fix cheap: the model changes a line and validates, without sending every file
again on each call.
"""
from __future__ import annotations
import asyncio
import difflib
import json
import os
import re
import tempfile
from collections.abc import Awaitable, Callable, Iterable, Mapping
from collections.abc import Awaitable, Callable, Iterable, Mapping, MutableMapping
from dataclasses import dataclass, field
from pathlib import Path, PurePosixPath
from typing import Any
@@ -79,10 +86,19 @@ class TerraformRunner:
# Providers are downloaded here once and reused by every later check. Without it,
# each validate or plan downloads its providers again into a scratch directory.
plugin_cache_dir: str | None = None
# The providers the schema lookup answers for, as the provider bundle pins them:
# {local name: {"source": ..., "version": ...}}.
providers: Mapping[str, Mapping[str, str]] = field(default_factory=dict)
# Terraform's plugin cache is not safe for concurrent installs.
_init_lock: asyncio.Lock = field(default_factory=asyncio.Lock, repr=False)
_schema_lock: asyncio.Lock = field(default_factory=asyncio.Lock, repr=False)
# resource type -> (provider label, the resource's schema block)
_schemas: dict[str, tuple[str, dict[str, Any]]] | None = field(
default=None, repr=False
)
async def fmt(self, files: Mapping[str, str]) -> ToolResult:
async def formatted(self, files: Mapping[str, str]) -> dict[str, str] | ToolResult:
"""The files formatting changes, with their new content; or why it failed."""
refusal = _check_files(files)
if refusal:
return refusal
@@ -93,19 +109,24 @@ class TerraformRunner:
)
if code != 0:
return ToolResult(f"terraform fmt failed:\n{output}")
changed = [
name for name in files if (root / name).read_text() != files[name]
]
if not changed:
return ToolResult("terraform fmt: all files are already formatted.")
formatted = "\n\n".join(
f"--- {name}\n{(root / name).read_text()}" for name in changed
)
return ToolResult(
_clip(
f"terraform fmt reformatted {len(changed)} file(s):\n\n{formatted}"
)
)
return {
name: (root / name).read_text()
for name in files
if (root / name).read_text() != files[name]
}
async def fmt(self, files: Mapping[str, str]) -> ToolResult:
changed = await self.formatted(files)
if isinstance(changed, ToolResult):
return changed
if not changed:
return ToolResult("terraform fmt: all files are already formatted.")
formatted = "\n\n".join(
f"--- {name}\n{content}" for name, content in changed.items()
)
return ToolResult(
_clip(f"terraform fmt reformatted {len(changed)} file(s):\n\n{formatted}")
)
async def validate(self, files: Mapping[str, str]) -> ToolResult:
refusal = _check_files(files)
@@ -150,6 +171,87 @@ class TerraformRunner:
_clip(f"terraform plan {verdict} (nothing was applied):\n{output}")
)
async def schema(
self, resource_type: str, block: str = "", find: str = ""
) -> ToolResult:
"""What a resource type accepts, from the pinned provider's own schema."""
loaded = await self._load_schemas()
if isinstance(loaded, ToolResult):
return loaded
if resource_type not in loaded:
close = difflib.get_close_matches(resource_type, loaded, n=5, cutoff=0.6)
hint = f" Close matches: {', '.join(close)}." if close else ""
return ToolResult(
f"No resource type {resource_type} in {self._provider_labels()}.{hint}"
)
label, root = loaded[resource_type]
title = f"{resource_type} ({label})"
if find:
return ToolResult(_clip(_find_in_schema(title, root, find)))
node = root
for step in [part for part in block.split(".") if part]:
nested = node.get("block_types", {}).get(step)
if nested is None:
inside = ", ".join(sorted(node.get("block_types", {}))) or "none"
return ToolResult(
f"{title} has no block {block!r}: {step!r} is not a block there. "
f"Blocks at that level: {inside}."
)
node = nested["block"]
heading = f"{title}, block {block}" if block else title
return ToolResult(_clip(_render_schema(heading, node)))
def _provider_labels(self) -> str:
return (
", ".join(
f"{pin['source']} {pin['version']}" for pin in self.providers.values()
)
or "no pinned provider"
)
async def _load_schemas(self) -> dict[str, tuple[str, dict[str, Any]]] | ToolResult:
async with self._schema_lock:
if self._schemas is not None:
return self._schemas
if not self.providers:
return ToolResult(
"Schema lookup is unavailable: the Cloud provider bundle pins no "
"Terraform provider."
)
required = "\n".join(
f' {name} = {{ source = "{pin["source"]}", '
f'version = "{pin["version"]}" }}'
for name, pin in self.providers.items()
)
with tempfile.TemporaryDirectory(prefix="tf-schema-") as tmp:
root = Path(tmp)
(root / "versions.tf").write_text(
f"terraform {{\n required_providers {{\n{required}\n }}\n}}\n"
)
failure = await self._init(root)
if failure:
return failure
code, output = await self._run(
[self.binary, "providers", "schema", "-json"], root
)
if code != 0:
return ToolResult(
_clip(f"terraform providers schema failed:\n{output}")
)
try:
data = json.loads(output)
except ValueError:
return ToolResult("terraform providers schema returned no JSON.")
labels = {pin["source"]: pin["version"] for pin in self.providers.values()}
schemas: dict[str, tuple[str, dict[str, Any]]] = {}
for address, provider in (data.get("provider_schemas") or {}).items():
source = address.split("/", 1)[-1] # drop the registry host
label = f"{source} {labels.get(source, '')}".strip()
for name, resource in (provider.get("resource_schemas") or {}).items():
schemas[name] = (label, resource.get("block") or {})
self._schemas = schemas
return schemas
async def _init(self, root: Path) -> ToolResult | None:
command = [self.binary, "init", "-backend=false", "-input=false", "-no-color"]
if self.plugin_cache_dir:
@@ -236,6 +338,100 @@ def _clip(text: str) -> str:
return text if len(text) <= _MAX_OUTPUT else text[:_MAX_OUTPUT] + "\n[truncated]"
def _type(value: Any) -> str:
if isinstance(value, str):
return value
if isinstance(value, list) and len(value) == 2 and value[0] != "object":
return f"{value[0]} of {_type(value[1])}"
return "object"
def _use(attribute: Mapping[str, Any]) -> str:
if attribute.get("required"):
return "required"
return "optional" if attribute.get("optional") else "read-only"
def _arguments(node: Mapping[str, Any]) -> dict[str, Mapping[str, Any]]:
"""The arguments code may set: everything but the read-only ones."""
return {
name: attribute
for name, attribute in sorted((node.get("attributes") or {}).items())
if _use(attribute) != "read-only"
}
def _block_note(nested: Mapping[str, Any]) -> str:
notes = [str(nested.get("nesting_mode", "block"))]
if nested.get("min_items"):
notes.append(f"at least {nested['min_items']}")
if nested.get("max_items"):
notes.append(f"at most {nested['max_items']}")
return ", ".join(notes)
def _render_schema(heading: str, node: Mapping[str, Any]) -> str:
"""One level in full, and the blocks beneath it as an outline of names."""
lines = [heading, "", "Arguments:"]
arguments = _arguments(node)
for name, attribute in arguments.items():
described = " ".join(str(attribute.get("description") or "").split())[:160]
deprecated = " DEPRECATED" if attribute.get("deprecated") else ""
lines.append(
f" {name} ({_type(attribute.get('type'))}, {_use(attribute)})"
f"{deprecated}" + (f": {described}" if described else "")
)
if not arguments:
lines.append(" none")
def outline(parent: Mapping[str, Any], depth: int) -> None:
for name, nested in sorted((parent.get("block_types") or {}).items()):
inner = nested.get("block") or {}
names = ", ".join(
f"{argument}*" if attribute.get("required") else argument
for argument, attribute in _arguments(inner).items()
)
lines.append(
f"{' ' * depth}{name} {{ }} ({_block_note(nested)}): {names or '-'}"
)
outline(inner, depth + 1)
lines += ["", "Blocks (* marks a required argument):"]
before = len(lines)
outline(node, 1)
if len(lines) == before:
lines.append(" none")
lines += ["", "Pass `block`, such as a.b, for one block's arguments in full."]
return "\n".join(lines)
def _find_in_schema(title: str, root: Mapping[str, Any], wanted: str) -> str:
"""Every argument or block whose name contains `wanted`, with where it sits."""
needle = wanted.lower()
found: list[str] = []
def search(node: Mapping[str, Any], path: str) -> None:
for name, attribute in sorted((node.get("attributes") or {}).items()):
if needle in name.lower():
where = f"{path}.{name}" if path else name
found.append(
f" {where} ({_type(attribute.get('type'))}, {_use(attribute)})"
)
for name, nested in sorted((node.get("block_types") or {}).items()):
where = f"{path}.{name}" if path else name
if needle in name.lower():
found.append(f" {where} {{ }} ({_block_note(nested)})")
search(nested.get("block") or {}, where)
search(root, "")
if not found:
return (
f"{title} has no argument or block named like {wanted!r}. It cannot be "
"set on this resource type."
)
return f"{title}: {wanted!r} is found at\n" + "\n".join(found)
_FILES_SCHEMA: dict[str, Any] = {
**FILES_SCHEMA,
"description": "Terraform files in one directory, e.g. terraform/main.tf",
@@ -244,19 +440,53 @@ _FILES_SCHEMA: dict[str, Any] = {
def _with_files(
method: Callable[..., Awaitable[ToolResult]],
working_copy: MutableMapping[str, str] | None = None,
) -> Callable[..., Awaitable[ToolResult]]:
"""Adapt a runner method to take the FILES_SCHEMA argument."""
"""Adapt a runner method to take the FILES_SCHEMA argument.
async def handler(files: Any, **kwargs: Any) -> ToolResult:
With a working copy, the files are the Terraform files in it and the argument is
optional: files passed anyway are written to the working copy first.
"""
async def handler(files: Any = None, **kwargs: Any) -> ToolResult:
try:
converted = files_from_argument(files)
except TypeError as exc:
return ToolResult(f"Refused: files: {exc}")
return await method(converted, **kwargs)
if working_copy is None:
return await method(converted, **kwargs)
working_copy.update(converted)
return await method(_terraform_files(working_copy), **kwargs)
return handler
def _terraform_files(files: Mapping[str, str]) -> dict[str, str]:
return {
name: content
for name, content in files.items()
if name.endswith(_TERRAFORM_SUFFIXES)
}
def _fmt_in_place(
runner: TerraformRunner, working_copy: MutableMapping[str, str]
) -> Callable[..., Awaitable[ToolResult]]:
async def format_working_copy(files: Mapping[str, str]) -> ToolResult:
changed = await runner.formatted(files)
if isinstance(changed, ToolResult):
return changed
working_copy.update(changed)
if not changed:
return ToolResult("terraform fmt: all files are already formatted.")
return ToolResult(
f"terraform fmt reformatted {len(changed)} file(s) in your working "
f"copy: {', '.join(sorted(changed))}."
)
return _with_files(format_working_copy, working_copy)
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."),
@@ -268,10 +498,48 @@ LOCAL_TOOLS: dict[str, tuple[str, str]] = {
"cloud_read",
"Preview Terraform against the live cloud environment with a plan. Never applies.",
),
"terraform_schema": (
"general",
(
"Look up what a Terraform resource type accepts, from the provider's own "
"schema: its arguments and blocks, one block in full with `block`, or "
"whether an argument exists anywhere in it with `find`."
),
),
}
_ON_WORKING_COPY = " Runs on your working copy; pass no files."
def local_tools(
names: Iterable[str],
runner: TerraformRunner,
working_copy: MutableMapping[str, str] | None = None,
) -> list[ToolSpec]:
"""The named tools. With a `working_copy`, the Terraform checks run on it."""
files_required = [] if working_copy is not None else ["files"]
suffix = _ON_WORKING_COPY if working_copy is not None else ""
def checks(name: str, method: Callable[..., Awaitable[ToolResult]]) -> ToolSpec:
properties: dict[str, Any] = {"files": _FILES_SCHEMA}
if name == "terraform_plan":
properties["variables"] = {
"type": "object",
"additionalProperties": {"type": "string"},
}
tier, description = LOCAL_TOOLS[name]
return ToolSpec(
name,
description + suffix,
{
"type": "object",
"properties": properties,
"required": files_required,
},
method,
tier=tier,
)
def local_tools(names: Iterable[str], runner: TerraformRunner) -> list[ToolSpec]:
builders = {
"mermaid_check": lambda: ToolSpec(
"mermaid_check",
@@ -284,44 +552,41 @@ def local_tools(names: Iterable[str], runner: TerraformRunner) -> list[ToolSpec]
mermaid_check,
tier="general",
),
"terraform_fmt": lambda: ToolSpec(
"terraform_fmt": lambda: checks(
"terraform_fmt",
LOCAL_TOOLS["terraform_fmt"][1],
{
"type": "object",
"properties": {"files": _FILES_SCHEMA},
"required": ["files"],
},
_with_files(runner.fmt),
tier="general",
_fmt_in_place(runner, working_copy)
if working_copy is not None
else _with_files(runner.fmt),
),
"terraform_validate": lambda: ToolSpec(
"terraform_validate",
LOCAL_TOOLS["terraform_validate"][1],
{
"type": "object",
"properties": {"files": _FILES_SCHEMA},
"required": ["files"],
},
_with_files(runner.validate),
tier="general",
"terraform_validate": lambda: checks(
"terraform_validate", _with_files(runner.validate, working_copy)
),
"terraform_plan": lambda: ToolSpec(
"terraform_plan",
LOCAL_TOOLS["terraform_plan"][1],
"terraform_plan": lambda: checks(
"terraform_plan", _with_files(runner.plan, working_copy)
),
"terraform_schema": lambda: ToolSpec(
"terraform_schema",
LOCAL_TOOLS["terraform_schema"][1],
{
"type": "object",
"properties": {
"files": _FILES_SCHEMA,
"variables": {
"type": "object",
"additionalProperties": {"type": "string"},
"resource_type": {
"type": "string",
"description": "For example google_cloud_run_v2_service",
},
"block": {
"type": "string",
"description": "A nested block, such as template.containers",
},
"find": {
"type": "string",
"description": "An argument or block name to look for",
},
},
"required": ["files"],
"required": ["resource_type"],
},
_with_files(runner.plan),
tier="cloud_read",
runner.schema,
tier="general",
),
}
return [builders[name]() for name in names]

View File

@@ -2,19 +2,24 @@
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.
When the Deliverable has a working copy, the local tools are built on it.
Cloud-read gating is applied later, per Execution, by `specialist_tools`.
"""
from __future__ import annotations
from collections.abc import Mapping, MutableMapping, Sequence
from collections.abc import Callable, Mapping, MutableMapping, Sequence
from typing import Any
from app.adk.roles import PILLAR_ADVISOR
from app.adk.runtime import AgentRuntime, RoleSpec, RunLimiter, ToolFactory, ToolSpec
from app.tools.mcp import McpCatalog
from app.tools.pillars import pillar_consultation_tool
from app.workflows.deliverables import DeliverableKind
from app.tools.workspace import working_files
from app.workflows.deliverables import DEPENDENCY_GRAPH, DeliverableKind
# The local tools, built on a working copy of files when the Deliverable has one.
LocalToolBuilder = Callable[[MutableMapping[str, str] | None], Sequence[ToolSpec]]
def make_tool_factory(
@@ -22,11 +27,14 @@ def make_tool_factory(
roles: Mapping[str, RoleSpec],
pillar_skills: Mapping[str, str],
*,
local_tools: Sequence[ToolSpec] = (),
local_tools: Sequence[ToolSpec] | LocalToolBuilder = (),
catalog: McpCatalog | None = None,
limiter: RunLimiter | None = None,
) -> ToolFactory:
local_by_name = {tool.name: tool for tool in local_tools}
def build_local(
working_copy: MutableMapping[str, str] | None,
) -> Sequence[ToolSpec]:
return local_tools(working_copy) if callable(local_tools) else local_tools
def mcp_tools(role: RoleSpec) -> list[ToolSpec]:
return catalog.tools_for(role.mcp_servers) if catalog else []
@@ -42,6 +50,16 @@ def make_tool_factory(
def tools_for(
role: RoleSpec, deliverable: str | None, working: MutableMapping[str, Any]
) -> Sequence[ToolSpec]:
has_working_copy = any(
kind.value == deliverable and spec.working_copy is not None
for kind, spec in DEPENDENCY_GRAPH.items()
)
local_by_name = {
tool.name: tool
for tool in build_local(
working_files(working) if has_working_copy else None
)
}
tools = [local_by_name[name] for name in role.tools if name in local_by_name]
tools += mcp_tools(role)
if (

289
app/tools/workspace.py Normal file
View File

@@ -0,0 +1,289 @@
"""A Specialist's working copy: files and a graph built up over several tool calls.
A model that must return a whole Deliverable in one reply spends most of its output
repeating itself, and a long reply is what times out. With a working copy it writes a
file once, changes only the lines that need changing, and adds to a graph a few items
at a time. The working copy is kept with the Execution, so a Revision starts from the
last attempt instead of from nothing.
It lives in the Deliverable's working memory:
working["files"] {path: content}
working["graph"] the Target architecture, as target-architecture.json holds it
"""
from __future__ import annotations
import json
from collections.abc import Mapping, MutableMapping, Sequence
from pathlib import PurePosixPath
from typing import Any
from app.adk.runtime import ToolResult, ToolSpec
FILES = "files"
GRAPH = "graph"
_GRAPH_LISTS = ("elements", "relationships", "checks", "not_applicable")
_MAX_READ = 40_000
def safe_relative(name: str) -> bool:
path = PurePosixPath(name)
return bool(name) and not path.is_absolute() and ".." not in path.parts
def working_files(working: MutableMapping[str, Any]) -> MutableMapping[str, str]:
files = working.get(FILES)
if not isinstance(files, MutableMapping):
files = working[FILES] = {}
return files
def _schema(properties: Mapping[str, Any], required: Sequence[str]) -> dict[str, Any]:
return {
"type": "object",
"properties": dict(properties),
"required": list(required),
}
def _lines(content: str) -> int:
return content.count("\n") + (1 if content and not content.endswith("\n") else 0)
def file_tools(working: MutableMapping[str, Any]) -> list[ToolSpec]:
"""Tools that write, change and read the files of a working copy."""
files = working_files(working)
async def write_file(path: str, content: str) -> ToolResult:
if not safe_relative(path):
return ToolResult(
f"Refused: {path!r} must be a relative path without '..'."
)
files[path] = content
return ToolResult(f"Wrote {path} ({_lines(content)} lines).")
async def edit_file(path: str, old: str, new: str) -> ToolResult:
if path not in files:
return ToolResult(f"Refused: {path} is not in your working copy.")
found = files[path].count(old) if old else 0
if found != 1:
return ToolResult(
f"Refused: `old` must match exactly one place in {path}; it matches "
f"{found}. Include more of the surrounding lines."
)
files[path] = files[path].replace(old, new)
return ToolResult(f"Edited {path}.")
async def read_file(path: str = "") -> ToolResult:
if not path:
if not files:
return ToolResult("Your working copy is empty.")
return ToolResult(
"Your working copy:\n"
+ "\n".join(
f"- {name} ({_lines(files[name])} lines)" for name in sorted(files)
)
)
if path not in files:
return ToolResult(f"Refused: {path} is not in your working copy.")
content = files[path]
if len(content) > _MAX_READ:
content = content[:_MAX_READ] + "\n[truncated]"
return ToolResult(content)
async def delete_file(path: str) -> ToolResult:
if files.pop(path, None) is None:
return ToolResult(f"Refused: {path} is not in your working copy.")
return ToolResult(f"Deleted {path}.")
text = {"type": "string"}
return [
ToolSpec(
"write_file",
"Write one file of your working copy, replacing it if it exists. Your "
"working copy is attached for you when you submit.",
_schema({"path": text, "content": text}, ["path", "content"]),
write_file,
),
ToolSpec(
"edit_file",
"Change part of one file: replace the single place `old` matches with "
"`new`. Use this for a fix instead of writing the file again.",
_schema({"path": text, "old": text, "new": text}, ["path", "old", "new"]),
edit_file,
),
ToolSpec(
"read_file",
"Read one file of your working copy, or list its files when `path` is "
"left out.",
_schema({"path": text}, []),
read_file,
),
ToolSpec(
"delete_file",
"Remove one file from your working copy.",
_schema({"path": text}, ["path"]),
delete_file,
),
]
# --- the graph -----------------------------------------------------------------------
def working_graph(working: MutableMapping[str, Any]) -> dict[str, list[dict[str, Any]]]:
graph = working.get(GRAPH)
if not isinstance(graph, dict):
graph = working[GRAPH] = {}
for name in _GRAPH_LISTS:
if not isinstance(graph.get(name), list):
graph[name] = []
return graph
def graph_text(working: MutableMapping[str, Any]) -> str:
"""The working graph as target-architecture.json, or "" when nothing is in it."""
graph = working.get(GRAPH)
if not isinstance(graph, dict) or not any(graph.get(n) for n in _GRAPH_LISTS):
return ""
return json.dumps(
{name: graph.get(name, []) for name in _GRAPH_LISTS},
indent=2,
ensure_ascii=False,
)
def keep_graph(working: MutableMapping[str, Any], text: str) -> None:
"""Make a submitted graph the working graph, so a Revision amends it."""
try:
data = json.loads(text)
except ValueError:
return
if isinstance(data, dict):
working[GRAPH] = {
name: [item for item in data.get(name, []) if isinstance(item, dict)]
for name in _GRAPH_LISTS
}
def _key(name: str) -> str:
return "recommendation" if name == "not_applicable" else "id"
def graph_tools(working: MutableMapping[str, Any]) -> list[ToolSpec]:
"""Tools that build the Target architecture a few items at a time."""
async def graph_put(
elements: Sequence[Any] = (),
relationships: Sequence[Any] = (),
checks: Sequence[Any] = (),
not_applicable: Sequence[Any] = (),
) -> ToolResult:
graph = working_graph(working)
given = dict(
zip(
_GRAPH_LISTS,
(elements, relationships, checks, not_applicable),
strict=True,
)
)
bad = [
f"{name}[{index}]"
for name, items in given.items()
for index, item in enumerate(items or ())
if not isinstance(item, Mapping)
or not isinstance(item.get(_key(name)), str)
or not item[_key(name)].strip()
]
if bad:
return ToolResult(
"Refused: each item must be an object with an `id` (a "
f"`recommendation` under not_applicable): {', '.join(bad)}"
)
added = replaced = 0
for name, items in given.items():
key = _key(name)
for item in items or ():
for index, existing in enumerate(graph[name]):
if existing.get(key) == item[key]:
graph[name][index] = dict(item)
replaced += 1
break
else:
graph[name].append(dict(item))
added += 1
return ToolResult(f"Added {added}, replaced {replaced}. {_counts(graph)}")
async def graph_remove(ids: Sequence[str]) -> ToolResult:
graph = working_graph(working)
wanted = set(ids)
removed = 0
for name in _GRAPH_LISTS:
kept = [item for item in graph[name] if item.get(_key(name)) not in wanted]
removed += len(graph[name]) - len(kept)
graph[name] = kept
return ToolResult(f"Removed {removed}. {_counts(graph)}")
async def graph_read() -> ToolResult:
return ToolResult(graph_text(working) or "Your working graph is empty.")
def items(*fields: str, optional: tuple[str, ...] = ()) -> dict[str, Any]:
return {
"type": "array",
"items": _schema(
{name: {"type": "string"} for name in (*fields, *optional)}, fields
),
}
lists = {
"elements": items(
"id", "name", "product", "resource_type", optional=("component",)
),
"relationships": items("id", "from", "to", "kind"),
"checks": items("id", "applies_to", "statement", "source"),
"not_applicable": items("recommendation", "reason"),
}
return [
ToolSpec(
"graph_put",
"Add items to your working graph, or replace the ones with the same id. "
"Call it several times with a few items each. Your working graph is "
"attached as target-architecture.json when you submit.",
_schema(lists, []),
graph_put,
),
ToolSpec(
"graph_remove",
"Remove items from your working graph by id (a not-applicable entry by "
"its recommendation id).",
_schema({"ids": {"type": "array", "items": {"type": "string"}}}, ["ids"]),
graph_remove,
),
ToolSpec(
"graph_read",
"Read your working graph.",
{"type": "object", "properties": {}},
graph_read,
),
]
def _counts(graph: Mapping[str, Sequence[Any]]) -> str:
return (
f"The graph has {len(graph['elements'])} Elements, "
f"{len(graph['relationships'])} Relationships and "
f"{len(graph['checks'])} Checks."
)
def summary(working: Mapping[str, Any]) -> dict[str, Any] | None:
"""What a Specialist is told it already has, at the start of a run."""
told: dict[str, Any] = {}
files = working.get(FILES)
if isinstance(files, Mapping) and files:
told["files"] = sorted(files)
graph = working.get(GRAPH)
if isinstance(graph, Mapping) and any(graph.get(name) for name in _GRAPH_LISTS):
told["graph"] = {name: len(graph.get(name) or ()) for name in _GRAPH_LISTS}
return told or None