"""Intake: what a message that starts something is asking for (ADR-0007). Inside an Execution the router reads the user's replies. This is the same reading 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 change and how to name it, and starts nothing. Without a decision, and whenever the reading is not confident, the message is taken as a new request: that is what every message was before, and starting work nobody asked for is cheaper to put right than refusing work somebody did. """ from __future__ import annotations import logging from collections.abc import Mapping, Sequence from dataclasses import dataclass from pathlib import Path from typing import Any from app.engine.runtime import ( AgentRuntime, AgentTask, Decider, Question, RoleSpec, Submitted, ToolResult, ToolSpec, ) from app.engine.baseline import BaselineError, load_baseline from app.engine.customer_case import IN_PROGRESS, read_history from app.engine.execution_state import UNASSIGNED_CASE logger = logging.getLogger(__name__) NEW_REQUEST = "new_request" CHANGE_REQUEST = "change_request" QUESTION = "question" ABOUT = ( "I design cloud solution architectures. Tell me, at a high level, what you want " "built, and I will work through requirements, a target architecture, " "infrastructure code, validation and a packaged guide, asking for your approval " "at each Phase. Nothing was started for this message." ) def change_note(baseline: str) -> str: """What a caller is told when their message reads as a change to delivered work.""" return ( "This reads as a change to the architecture already delivered for this " f"Customer case, in Execution {baseline}. Nothing was started. To change " f'that architecture from where it stood, send this again with "baseline" ' f'set to "{baseline}". To design it as new work instead, send it again ' 'with "new_request" set to true.' ) 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 @dataclass(frozen=True) class IntakeReading: kind: str # new_request | change_request | question confidence: float = 0.0 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]]: """The case's earlier statements of intent whose Executions delivered something.""" if not customer_case or customer_case == UNASSIGNED_CASE: return [] return [ item for item in read_history(output_root, customer_case)["intents"] if isinstance(item, Mapping) and str(item.get("status", IN_PROGRESS)).startswith("completed") ] class Intake: def __init__( self, decider: Decider, 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 = "" ) -> IntakeReading: earlier = finished_intents(self._output_root, customer_case or "") text = message.strip() if not text: return IntakeReading(NEW_REQUEST, earlier=len(earlier)) answers = await self._decider.decide( _state(text, earlier), { "intake": Question( "choice", "What is the user's message? new_request: they describe " "something they want designed or built. change_request: they " "ask to change or extend an architecture already delivered to " "them. question: they ask about the service or about earlier " "work, and want an answer, not new work.", (NEW_REQUEST, CHANGE_REQUEST, QUESTION), ) }, scope=scope, ) answer = (answers or {}).get("intake") if answer is None: return IntakeReading(NEW_REQUEST, earlier=len(earlier)) kind, confidence = str(answer.value), float(answer.confidence) if kind != NEW_REQUEST and confidence < self._act: kind = NEW_REQUEST # not sure enough to do anything but start if kind == CHANGE_REQUEST and not earlier: 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 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: lines = [f"Architectures already delivered to this user: {len(earlier)}."] for item in list(earlier)[-_EARLIER_SHOWN:]: request = " ".join(str(item.get("workflow_request", "")).split())[:300] 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