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

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