chore: housekeeping from the runs of 2026-10-09
Some checks failed
validation / verify (push) Failing after 12s
Some checks failed
validation / verify (push) Failing after 12s
- An Execution's files are written as each Deliverable is submitted, marked in_progress, so a killed process or one waiting for its user leaves them on disk. A write removes files an earlier write left that it no longer has. - A question about delivered work is answered from that Execution's solution guide by the reply writer; a question about the service is answered as before. Nothing is started for either. - Lessons: prove writes only for lessons the Skill holds; the Skill records the vendored Skill versions the lessons were read against, status names any that changed, and a test fails until they are reviewed. - Four more code patterns: Firestore, BigQuery, Eventarc and GKE. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -31,7 +31,15 @@ from google.protobuf import json_format
|
||||
|
||||
from app.agent import ExecutionEngine, Interaction
|
||||
from app.nodes.execution_nodes import GUIDE_FILENAME
|
||||
from app.nodes.intake import ABOUT, CHANGE_REQUEST, QUESTION, Intake, change_note
|
||||
from app.nodes.intake import (
|
||||
ABOUT,
|
||||
CHANGE_REQUEST,
|
||||
QUESTION,
|
||||
DeliveredAnswers,
|
||||
Intake,
|
||||
change_note,
|
||||
no_answer_note,
|
||||
)
|
||||
from app.presentation import describe_prompt
|
||||
from app.workflows.deliverables import DeliverableKind
|
||||
|
||||
@@ -41,7 +49,13 @@ STRUCTURED_REPLY_KEYS = ("approval", "permission")
|
||||
|
||||
|
||||
class SolutionArchitectExecutor(AgentExecutor):
|
||||
def __init__(self, engine: ExecutionEngine, intake: Intake | None = None) -> None:
|
||||
def __init__(
|
||||
self,
|
||||
engine: ExecutionEngine,
|
||||
intake: Intake | None = None,
|
||||
answers: DeliveredAnswers | None = None,
|
||||
) -> None:
|
||||
self._answers = answers
|
||||
self._engine = engine
|
||||
self._intake = intake
|
||||
|
||||
@@ -75,14 +89,21 @@ class SolutionArchitectExecutor(AgentExecutor):
|
||||
scope=task_id,
|
||||
)
|
||||
if reading.kind == QUESTION:
|
||||
text, about = ABOUT, None
|
||||
if reading.about_delivered and reading.latest and self._answers:
|
||||
# About what was delivered: answered from its files.
|
||||
about = reading.latest
|
||||
text = await self._answers.answer(
|
||||
context.get_user_input(),
|
||||
str(options.get("customer_case")),
|
||||
about,
|
||||
) or no_answer_note(about)
|
||||
data = {"status": "answered", "intake": QUESTION}
|
||||
if about:
|
||||
data["about"] = about
|
||||
await updater.complete(
|
||||
updater.new_agent_message(
|
||||
[
|
||||
new_text_part(ABOUT),
|
||||
new_data_part(
|
||||
{"status": "answered", "intake": QUESTION}
|
||||
),
|
||||
]
|
||||
[new_text_part(text), new_data_part(data)]
|
||||
)
|
||||
)
|
||||
return
|
||||
|
||||
@@ -36,7 +36,7 @@ from app.baseline import load_baseline
|
||||
from app.checkpointing import open_checkpointer
|
||||
from app.config import Settings
|
||||
from app.customer_case import record_intent
|
||||
from app.nodes.intake import Intake
|
||||
from app.nodes.intake import DeliveredAnswers, Intake
|
||||
from app.nodes.router import (
|
||||
REPLY_WRITER,
|
||||
OrchestratorPolicy,
|
||||
@@ -328,6 +328,8 @@ class Assembly:
|
||||
mcp_gaps: dict[str, str]
|
||||
decider: Decider = field(default_factory=NoDecider)
|
||||
intake: Intake | None = None # reads a message that starts something
|
||||
# Answers a question about delivered work from its files.
|
||||
answers: DeliveredAnswers | None = None
|
||||
|
||||
|
||||
def discover_overlays(settings: Settings, bundle: ProviderBundle) -> dict[str, Any]:
|
||||
@@ -529,6 +531,9 @@ async def open_assembly(
|
||||
output_root or settings.BASE_DIR,
|
||||
act=settings.JEV_ACT_THRESHOLD,
|
||||
),
|
||||
DeliveredAnswers(
|
||||
runtime, roles[REPLY_WRITER], output_root or settings.BASE_DIR
|
||||
),
|
||||
)
|
||||
finally:
|
||||
if isinstance(decider, JevDecider):
|
||||
|
||||
@@ -7,7 +7,7 @@ are ordinary evaluation reports; one is made with LESSONS_ENABLED=false.
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
from collections.abc import Mapping, Sequence
|
||||
from collections.abc import Collection, Mapping, Sequence
|
||||
from dataclasses import replace
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
@@ -106,6 +106,12 @@ def render(result: Mapping[str, Any], without: Path, with_lessons: Path) -> str:
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
def record(proposals: Sequence[Proposal], proof: str) -> list[Proposal]:
|
||||
"""Write the comparison into every published proposal."""
|
||||
return [write(replace(p, proof=proof)) for p in proposals if p.published]
|
||||
def record(
|
||||
proposals: Sequence[Proposal], proof: str, live: Collection[str]
|
||||
) -> list[Proposal]:
|
||||
"""Write the comparison into the proposal of every lesson in the Skill.
|
||||
|
||||
`live` is the ids the Skill holds now. A retired lesson was not part of what
|
||||
was compared, so its proposal is left as it was.
|
||||
"""
|
||||
return [write(replace(p, proof=proof)) for p in proposals if p.id in live]
|
||||
|
||||
@@ -8,7 +8,9 @@ the index in SKILL.md are written here, from approved proposals, and never by ha
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import re
|
||||
from collections.abc import Mapping
|
||||
from dataclasses import replace
|
||||
from datetime import UTC, date, datetime
|
||||
from pathlib import Path
|
||||
@@ -130,6 +132,45 @@ def publish(
|
||||
return write(replace(proposal, published=proposal.published or stamp))
|
||||
|
||||
|
||||
# The versions of the Skills the lessons were written beside, kept in the lessons
|
||||
# Skill. A lesson is a correction to how agents follow those Skills, so when one
|
||||
# of them changes each lesson is worth a second look: it may now be said upstream,
|
||||
# or contradict it.
|
||||
UPSTREAM_FILE = "upstream.json"
|
||||
|
||||
|
||||
def upstream_reviewed(skill_dir: Path) -> dict[str, str]:
|
||||
"""The upstream Skill versions the lessons were last reviewed against."""
|
||||
path = skill_dir / UPSTREAM_FILE
|
||||
if not path.is_file():
|
||||
return {}
|
||||
try:
|
||||
data = json.loads(path.read_text(encoding="utf-8"))
|
||||
except ValueError:
|
||||
return {}
|
||||
return {str(k): str(v) for k, v in data.items()} if isinstance(data, dict) else {}
|
||||
|
||||
|
||||
def mark_reviewed(skill_dir: Path, current: Mapping[str, str]) -> None:
|
||||
"""Record that the lessons stand against these upstream Skill versions."""
|
||||
(skill_dir / UPSTREAM_FILE).write_text(
|
||||
json.dumps(dict(sorted(current.items())), indent=2) + "\n", encoding="utf-8"
|
||||
)
|
||||
|
||||
|
||||
def upstream_changes(skill_dir: Path, current: Mapping[str, str]) -> list[str]:
|
||||
"""The upstream Skills that changed, appeared or went since the lessons were
|
||||
last reviewed. Empty when there are no lessons, or nothing was ever recorded."""
|
||||
reviewed = upstream_reviewed(skill_dir)
|
||||
if not reviewed or not published(skill_dir):
|
||||
return []
|
||||
return sorted(
|
||||
name
|
||||
for name in set(reviewed) | set(current)
|
||||
if reviewed.get(name) != current.get(name)
|
||||
)
|
||||
|
||||
|
||||
def retire(lesson_id: str, skill_dir: Path) -> bool:
|
||||
"""Remove a lesson from the Skill. Returns whether it was there."""
|
||||
deliverable = published(skill_dir).get(lesson_id)
|
||||
|
||||
@@ -89,7 +89,7 @@ def create_app(
|
||||
async with assembly_factory(settings) as assembly:
|
||||
handler = DefaultRequestHandlerV2(
|
||||
agent_executor=SolutionArchitectExecutor(
|
||||
assembly.engine, assembly.intake
|
||||
assembly.engine, assembly.intake, assembly.answers
|
||||
),
|
||||
task_store=InMemoryTaskStore(),
|
||||
agent_card=card,
|
||||
|
||||
@@ -15,7 +15,7 @@ import time
|
||||
from collections.abc import Awaitable, Callable, Mapping, MutableMapping, Sequence
|
||||
from dataclasses import dataclass
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
from typing import Any, cast
|
||||
|
||||
from langgraph.types import Command, Send, interrupt
|
||||
|
||||
@@ -37,7 +37,7 @@ from app.adk.runtime import (
|
||||
TurnEnded,
|
||||
)
|
||||
from app.baseline import WORKING_FILENAME
|
||||
from app.customer_case import close_intent
|
||||
from app.customer_case import IN_PROGRESS, close_intent
|
||||
from app.nodes.router import ModelOrchestrator, OrchestratorPolicy, TurnView
|
||||
from app.recorder import ExecutionRecorder
|
||||
from app.states.execution_state import (
|
||||
@@ -207,11 +207,13 @@ def make_execution_nodes(
|
||||
drafts = dict(state.get("drafts", {}))
|
||||
|
||||
outcomes = state.get("outcomes", [])
|
||||
arrived = False
|
||||
for record in outcomes[state.get("outcomes_applied", 0) :]:
|
||||
kind = DeliverableKind(record["kind"])
|
||||
try:
|
||||
if record["type"] == "submitted":
|
||||
ledger.submit(kind, record["attempt"], actor=record["role"])
|
||||
arrived = True
|
||||
deliverables[kind.value] = {
|
||||
"content": record["content"],
|
||||
"attachments": record["attachments"],
|
||||
@@ -252,6 +254,19 @@ def make_execution_nodes(
|
||||
]
|
||||
pending_questions.append({"kind": kind.value, "questions": questions})
|
||||
|
||||
if arrived:
|
||||
# What has been submitted is on disk as soon as it exists, marked as in
|
||||
# progress. A process that is killed leaves that much behind.
|
||||
try:
|
||||
_write_outputs(
|
||||
output_root,
|
||||
cast(ExecutionState, {**state, "deliverables": deliverables}),
|
||||
IN_PROGRESS,
|
||||
ledger,
|
||||
)
|
||||
except OSError:
|
||||
logger.exception("Writing the Execution's files so far failed")
|
||||
|
||||
turns = state.get("turns", 0) + 1
|
||||
update: dict[str, Any] = {
|
||||
"deliverables": deliverables,
|
||||
@@ -1214,6 +1229,26 @@ def _case(state: ExecutionState) -> str:
|
||||
return state.get("customer_case") or UNASSIGNED_CASE
|
||||
|
||||
|
||||
def _written_before(out_dir: Path) -> set[str]:
|
||||
"""The files an earlier write of this Execution's folder recorded."""
|
||||
try:
|
||||
manifest = json.loads((out_dir / MANIFEST_FILENAME).read_text("utf-8"))
|
||||
except (OSError, ValueError):
|
||||
return set()
|
||||
if not isinstance(manifest, dict):
|
||||
return set()
|
||||
names = {manifest.get("solution_guide"), manifest.get("changes")}
|
||||
for entry in (manifest.get("deliverables") or {}).values():
|
||||
if isinstance(entry, dict):
|
||||
names.add(entry.get("document"))
|
||||
names.update(entry.get("attachments") or [])
|
||||
return {
|
||||
name
|
||||
for name in names
|
||||
if isinstance(name, str) and name and ".." not in Path(name).parts
|
||||
}
|
||||
|
||||
|
||||
def _write_outputs(
|
||||
output_root: Path,
|
||||
state: ExecutionState,
|
||||
@@ -1267,6 +1302,11 @@ def _write_outputs(
|
||||
indent=2,
|
||||
ensure_ascii=False,
|
||||
)
|
||||
# The folder is written more than once as an Execution goes. A file an earlier
|
||||
# write left that this one does not have, such as a Terraform file removed in a
|
||||
# Revision, must not stay beside the files that replaced it.
|
||||
for stale in _written_before(out_dir) - set(files):
|
||||
(out_dir / stale).unlink(missing_ok=True)
|
||||
for name, content in files.items():
|
||||
path = out_dir / name
|
||||
path.parent.mkdir(parents=True, exist_ok=True)
|
||||
|
||||
@@ -6,6 +6,7 @@ one step earlier, for a message that arrives with no Execution in progress:
|
||||
new request design this workload start an Execution
|
||||
change request change what was delivered name the Baseline to change (ADR-0006)
|
||||
question what can you do, how long... answer; start nothing
|
||||
why did you choose X? answer from what was delivered
|
||||
|
||||
A change is never started from earlier work on a guess: the caller chooses the
|
||||
Baseline. So a message read as a change is answered with the Execution it would
|
||||
@@ -24,7 +25,17 @@ from dataclasses import dataclass
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
from app.adk.runtime import Decider, Question
|
||||
from app.adk.runtime import (
|
||||
AgentRuntime,
|
||||
AgentTask,
|
||||
Decider,
|
||||
Question,
|
||||
RoleSpec,
|
||||
Submitted,
|
||||
ToolResult,
|
||||
ToolSpec,
|
||||
)
|
||||
from app.baseline import BaselineError, load_baseline
|
||||
from app.customer_case import IN_PROGRESS, read_history
|
||||
from app.states.execution_state import UNASSIGNED_CASE
|
||||
|
||||
@@ -53,7 +64,18 @@ def change_note(baseline: str) -> str:
|
||||
)
|
||||
|
||||
|
||||
def no_answer_note(execution_id: str) -> str:
|
||||
"""What a caller is told when a question about delivered work went unanswered."""
|
||||
return (
|
||||
"I could not answer that from the documents delivered in Execution "
|
||||
f"{execution_id}. Its solution guide and Deliverables hold what was "
|
||||
"decided and why. Nothing was started for this message."
|
||||
)
|
||||
|
||||
|
||||
_MESSAGE_LIMIT = 8_000
|
||||
# How much of the delivered guide the answer is written from.
|
||||
_GUIDE_LIMIT = 80_000
|
||||
_EARLIER_SHOWN = 5
|
||||
|
||||
|
||||
@@ -64,6 +86,8 @@ class IntakeReading:
|
||||
judged: bool = False # False when no decision was available
|
||||
earlier: int = 0 # finished Executions of the same Customer case
|
||||
latest: str | None = None # the most recent of them: what a change would change
|
||||
# A question about what was delivered, as opposed to about the service.
|
||||
about_delivered: bool = False
|
||||
|
||||
|
||||
def finished_intents(output_root: Path, customer_case: str) -> list[Mapping[str, Any]]:
|
||||
@@ -85,11 +109,18 @@ class Intake:
|
||||
output_root: Path,
|
||||
*,
|
||||
act: float = 0.75,
|
||||
about_delivered_at: float = 0.6,
|
||||
) -> None:
|
||||
self._decider = decider
|
||||
self._output_root = output_root
|
||||
# How sure the reading must be before anything but a new Execution is done.
|
||||
self._act = act
|
||||
# How likely a question must be about delivered work to be answered from
|
||||
# it. Measured on 2026-10-10: six such questions scored 0.37 to 0.96, five
|
||||
# of them 0.73 or more; six about the service scored 0.07 to 0.16 and one
|
||||
# ambiguous one ("is my data stored anywhere?") 0.74. A wrong yes costs an
|
||||
# answer that says the documents do not cover it.
|
||||
self._about_delivered_at = about_delivered_at
|
||||
|
||||
async def read(
|
||||
self, message: str, customer_case: str | None = None, scope: str = ""
|
||||
@@ -123,9 +154,38 @@ class Intake:
|
||||
kind = NEW_REQUEST # there is nothing delivered to change
|
||||
logger.info("[%s] intake: %s (%.2f)", scope, kind, confidence)
|
||||
latest = str(earlier[-1].get("execution_id")) if earlier else None
|
||||
return IntakeReading(
|
||||
kind, confidence, judged=True, earlier=len(earlier), latest=latest
|
||||
about = (
|
||||
await self._about_delivered(text, earlier, scope)
|
||||
if kind == QUESTION and latest
|
||||
else False
|
||||
)
|
||||
return IntakeReading(
|
||||
kind,
|
||||
confidence,
|
||||
judged=True,
|
||||
earlier=len(earlier),
|
||||
latest=latest,
|
||||
about_delivered=about,
|
||||
)
|
||||
|
||||
async def _about_delivered(
|
||||
self, text: str, earlier: Sequence[Mapping[str, Any]], scope: str
|
||||
) -> bool:
|
||||
answers = await self._decider.decide(
|
||||
_state(text, earlier),
|
||||
{
|
||||
"about_delivered": Question(
|
||||
"noul",
|
||||
"Is the user asking about an architecture already delivered to "
|
||||
"them: what it contains, why something was chosen, or what "
|
||||
"validation found? Answer no when they ask what this service "
|
||||
"does or how it works in general.",
|
||||
)
|
||||
},
|
||||
scope=scope,
|
||||
)
|
||||
answer = (answers or {}).get("about_delivered")
|
||||
return answer is not None and float(answer.value) >= self._about_delivered_at
|
||||
|
||||
|
||||
def _state(message: str, earlier: Sequence[Mapping[str, Any]]) -> str:
|
||||
@@ -135,3 +195,65 @@ def _state(message: str, earlier: Sequence[Mapping[str, Any]]) -> str:
|
||||
lines.append(f"- {request}")
|
||||
lines.append(f"The user's message: {message[:_MESSAGE_LIMIT]}")
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
class DeliveredAnswers:
|
||||
"""Answers a question about delivered work from its documents, on the reply
|
||||
writer. It reads one Execution's files and starts nothing."""
|
||||
|
||||
def __init__(
|
||||
self, runtime: AgentRuntime, role: RoleSpec, output_root: Path
|
||||
) -> None:
|
||||
self._runtime = runtime
|
||||
self._role = role
|
||||
self._output_root = output_root
|
||||
|
||||
async def answer(
|
||||
self, question: str, customer_case: str, execution_id: str
|
||||
) -> str | None:
|
||||
"""The answer, or None when the documents could not be read or the writer
|
||||
gave none."""
|
||||
try:
|
||||
delivered = load_baseline(self._output_root, customer_case, execution_id)
|
||||
except BaselineError:
|
||||
return None
|
||||
guide = str(
|
||||
(delivered["deliverables"].get("solution_guide") or {}).get("content", "")
|
||||
)
|
||||
if not guide.strip():
|
||||
return None
|
||||
|
||||
async def write_reply(text: str) -> ToolResult:
|
||||
if not text.strip():
|
||||
return ToolResult("Not submitted: the reply is empty.")
|
||||
return ToolResult("Written.", Submitted(text))
|
||||
|
||||
tool = ToolSpec(
|
||||
"write_reply",
|
||||
"Give the text the user will read. Ends your turn.",
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {"text": {"type": "string"}},
|
||||
"required": ["text"],
|
||||
},
|
||||
write_reply,
|
||||
tier="execution",
|
||||
)
|
||||
task = AgentTask(
|
||||
role=self._role.name,
|
||||
prompt="Answer the user's question about the architecture delivered to them.",
|
||||
context={
|
||||
"question": question[:_MESSAGE_LIMIT],
|
||||
"delivered": {
|
||||
"execution_id": execution_id,
|
||||
"request": delivered.get("workflow_request", ""),
|
||||
"solution_guide": guide[:_GUIDE_LIMIT],
|
||||
},
|
||||
},
|
||||
)
|
||||
try:
|
||||
outcome = await self._runtime.run(self._role, task, [tool])
|
||||
except Exception: # a question must still get a reply
|
||||
logger.exception("Answering from delivered work failed")
|
||||
return None
|
||||
return outcome.content if isinstance(outcome, Submitted) else None
|
||||
|
||||
Reference in New Issue
Block a user