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

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