chore: housekeeping from the runs of 2026-10-09
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:
2026-10-10 11:44:38 +01:00
parent 10d23a5f91
commit 71da0ed504
24 changed files with 1109 additions and 43 deletions

View File

@@ -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

View File

@@ -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):

View File

@@ -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]

View File

@@ -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)

View File

@@ -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,

View File

@@ -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)

View File

@@ -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