"""Maps A2A tasks onto Executions: a task is an Execution, its context is the Session. A new task starts an Execution; a message on an input-required task answers the Execution's prompt. Approvals and permissions count only as structured data parts, never as free text. Before a new task starts anything its message is read (app/nodes/intake.py): a question is answered and starts nothing. A message that reads as a change to delivered work also starts nothing: the caller is told which Execution it would change and how to name it as the Baseline, because a Change request never starts from earlier work on a guess (ADR-0006). """ from __future__ import annotations import logging from collections.abc import Mapping from typing import Any from a2a.helpers.proto_helpers import ( get_data_parts, new_data_part, new_task, new_text_part, ) from a2a.server.agent_execution import AgentExecutor, RequestContext from a2a.server.events import EventQueue from a2a.server.tasks import TaskUpdater from a2a.types import TaskState from google.protobuf import json_format from execution_engine.agent import ExecutionEngine, Interaction from execution_engine.nodes.intake import ( CHANGE_REQUEST, QUESTION, DeliveredAnswers, Intake, change_note, no_answer_note, ) from execution_engine.presentation import describe_prompt logger = logging.getLogger(__name__) STRUCTURED_REPLY_KEYS = ("approval", "permission") class EngineExecutor(AgentExecutor): def __init__( self, engine: ExecutionEngine, intake: Intake | None = None, answers: DeliveredAnswers | None = None, ) -> None: self._answers = answers self._engine = engine self._intake = intake async def execute(self, context: RequestContext, event_queue: EventQueue) -> None: task_id = context.task_id or "" updater = TaskUpdater(event_queue, task_id, context.context_id or "") new = context.current_task is None try: if new: history = [context.message] if context.message is not None else [] await event_queue.enqueue_event( new_task( task_id, context.context_id or "", TaskState.TASK_STATE_SUBMITTED, history=history, ) ) await updater.start_work() options = _options(context) # A platform step sends its fields as metadata and all of them # again as the text; the request field, when sent, is the request. request = str(options.get("request") or context.get_user_input()) # A pre-approved caller is a batch job: it sends work, not questions. if ( self._intake and not options.get("pre_approved") and not options.get("baseline") and not options.get("new_request") ): reading = await self._intake.read( request, options.get("customer_case"), scope=task_id, ) if reading.kind == QUESTION: text, about = self._engine.workflow.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( request, 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(text), new_data_part(data)] ) ) return if reading.kind == CHANGE_REQUEST and reading.latest: await updater.complete( updater.new_agent_message( [ new_text_part(change_note(reading.latest)), new_data_part( { "status": "answered", "intake": CHANGE_REQUEST, "baseline": reading.latest, } ), ] ) ) return interaction = await self._engine.start( request, session_id=context.context_id, customer_case=options.get("customer_case"), baseline=options.get("baseline"), overlay_skills=options.get("overlay_skills") or (), **{ name: options[name] for name in self._engine.workflow.options if name in options }, scope=options.get("scope"), sources=options.get("sources"), execution_id=task_id, pre_approved=options.get("pre_approved"), allow_cloud_read=options.get("allow_cloud_read"), ) else: await updater.start_work() interaction = await self._engine.resume(task_id, _reply(context)) except Exception as exc: logger.exception("Execution %s failed", task_id) await updater.failed( updater.new_agent_message( [ new_text_part( f"The Execution failed: {type(exc).__name__}: {exc}" ) ] ) ) return await self._publish(interaction, updater) async def cancel(self, context: RequestContext, event_queue: EventQueue) -> None: # The checkpoint stays; cancelling only ends the A2A task. updater = TaskUpdater( event_queue, context.task_id or "", context.context_id or "" ) await updater.cancel() async def _publish(self, interaction: Interaction, updater: TaskUpdater) -> None: workflow = self._engine.workflow if interaction.status == "awaiting_user" and interaction.prompt is not None: prompt = dict(interaction.prompt) await updater.requires_input( updater.new_agent_message( [ new_text_part( describe_prompt(prompt, workflow.describe_approval) ), new_data_part({"prompt": prompt}), ] ) ) return deliverables: Mapping[str, Mapping[str, Any]] = interaction.state.get( "deliverables", {} ) guide = deliverables.get(workflow.final) if guide: await updater.add_artifact( [new_text_part(guide["content"], media_type="text/markdown")], name=workflow.final_file, ) for kind, deliverable in deliverables.items(): for name, content in deliverable.get("attachments", {}).items(): await updater.add_artifact( [new_text_part(content)], name=name, metadata={"deliverable": kind} ) warnings = list(interaction.state.get("warnings", [])) summary = ( workflow.done if interaction.status == "completed" else "The Execution ended with warnings: " + "; ".join(warnings) ) await updater.complete( updater.new_agent_message( [ new_text_part(summary), new_data_part({"status": interaction.status, "warnings": warnings}), ] ) ) def _whole_numbers(value: Any) -> Any: """`value` with every number that is whole as an int. A message's metadata travels as a structure that holds every number as a double, so a caller's 9 arrives as 9.0. What it was sent as is what an option's check should see. """ if isinstance(value, float) and value.is_integer(): return int(value) if isinstance(value, Mapping): return {key: _whole_numbers(item) for key, item in value.items()} if isinstance(value, list): return [_whole_numbers(item) for item in value] return value def _options(context: RequestContext) -> dict[str, Any]: options: dict[str, Any] = {} if context.message is not None and context.message.HasField("metadata"): options.update( _whole_numbers(json_format.MessageToDict(context.message.metadata)) ) options.update(context.metadata) return options def _reply(context: RequestContext) -> dict[str, Any]: if context.message is not None: for data in get_data_parts(list(context.message.parts)): if isinstance(data, Mapping) and any( k in data for k in STRUCTURED_REPLY_KEYS ): return {k: data[k] for k in STRUCTURED_REPLY_KEYS if k in data} return {"reply": context.get_user_input()}