keystone-agui 0.1.1__tar.gz

keystone_agui-0.1.1/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: keystone-agui
+Version: 0.1.1
+Summary: AG-UI (Agent-User Interaction Protocol) shared surface: reading RunAgentInput (and what is deliberately refused from it) + encoding events for SSE. Consumed by every service that speaks AG-UI outward, so the request contract cannot drift between them.
+Requires-Python: >=3.12
+Requires-Dist: ag-ui-protocol<1,>=0.1.19
+Provides-Extra: dev
+Requires-Dist: jsonschema<5,>=4.18; extra == "dev"
+Requires-Dist: referencing<1,>=0.30; extra == "dev"
+Requires-Dist: pytest<9,>=8; extra == "dev"
+Requires-Dist: pytest-cov<7,>=6; extra == "dev"
+Requires-Dist: ruff==0.15.15; extra == "dev"

keystone_agui-0.1.1/__init__.py

@@ -0,0 +1,127 @@
+"""AG-UI (Agent-User Interaction Protocol) — the shared surface every Keystone door speaks.
+
+Two halves, and the split is the useful part:
+
+* :mod:`keystone.agui.inbound` — reading ``RunAgentInput``, and what is deliberately REFUSED
+  from it. Shared because the refusals are security-relevant and must not differ per service.
+* :mod:`keystone.agui.outbound` — encoding events onto the wire. Shared because the encoding
+  is the contract: camelCase aliases and SCREAMING_SNAKE ``type`` values come from the spec's
+  own models, and three hand-rolled copies is three chances to disagree with it.
+
+And one companion protocol: :mod:`keystone.agui.a2ui` holds A2UI's three message primitives, the
+component catalog every Keystone surface declares, and that catalog's icon enum — the parts that
+are the same for everyone.
+
+What is NOT here: the mapping from a service's internal vocabulary to AG-UI events, or to a UI.
+That is each service's own business — ``visual-builder`` knows which of its trace subtypes are
+middleware, ``master-agent`` knows what its graph steps mean and what a consult should look like,
+and neither should learn the other's. This module briefly held master-agent's delegation UI (its
+tool names, its wording, its icons) and that was the coupling this lib exists to remove, not to
+host: every importer would have inherited one service's vocabulary.
+"""
+
+from keystone.agui.a2ui import (
+    ACTIVITY_A2UI,
+    ACTIVITY_ADAPTIVE_CARD,
+    ACTIVITY_ADAPTIVE_CARD_KEY,
+    ACTIVITY_CARDS_KEY,
+    ACTIVITY_CARDS_V2,
+    ACTIVITY_COMPONENT_KEY,
+    ACTIVITY_COMPONENT_REGISTRY_KEY,
+    ACTIVITY_DRAWN_BY,
+    BUTTON_VARIANTS,
+    CATALOG_ICONS,
+    CATALOG_ID,
+    STEP_UI_KEY,
+    VERSION,
+    button_variant,
+    create_surface,
+    icon,
+    surface,
+    update_components,
+    update_data_model,
+)
+from keystone.agui.bindings import (
+    DISPLAY_COMPONENTS,
+    INPUT_COMPONENTS,
+    ChoiceBinding,
+    choice_values,
+    data_bindings,
+    display_only_paths,
+    template_of,
+    template_subtree_ids,
+)
+from keystone.agui.catalog_check import (
+    BASIC_CATALOG_ID,
+    KEYSTONE_CATALOG_ID,
+    component_names,
+    component_problems,
+    component_schemas,
+    surface_problems,
+)
+from keystone.agui.gate import GatedCall, gate_message, proposed_calls, resume_schema
+from keystone.agui.inbound import (
+    A2UI_ACTION_PROP,
+    APPROVALS_PROP,
+    ARTIFACT_URI_SCHEME,
+    ESCAPE_PROP,
+    KEYSTONE_PROPS,
+    TurnRequest,
+    read_turn,
+    resume_entries,
+    resume_entry,
+    user_message_content,
+)
+from keystone.agui.outbound import encode, json_str
+
+__all__ = [
+    "A2UI_ACTION_PROP",
+    "APPROVALS_PROP",
+    "ARTIFACT_URI_SCHEME",
+    "ACTIVITY_A2UI",
+    "ACTIVITY_ADAPTIVE_CARD",
+    "ACTIVITY_ADAPTIVE_CARD_KEY",
+    "ACTIVITY_DRAWN_BY",
+    "ACTIVITY_CARDS_V2",
+    "ACTIVITY_CARDS_KEY",
+    "ACTIVITY_COMPONENT_KEY",
+    "ACTIVITY_COMPONENT_REGISTRY_KEY",
+    "BASIC_CATALOG_ID",
+    "BUTTON_VARIANTS",
+    "CATALOG_ICONS",
+    "CATALOG_ID",
+    "DISPLAY_COMPONENTS",
+    "ESCAPE_PROP",
+    "INPUT_COMPONENTS",
+    "KEYSTONE_CATALOG_ID",
+    "KEYSTONE_PROPS",
+    "STEP_UI_KEY",
+    "VERSION",
+    "TurnRequest",
+    "button_variant",
+    "component_names",
+    "component_schemas",
+    "component_problems",
+    "create_surface",
+    "GatedCall",
+    "ChoiceBinding",
+    "choice_values",
+    "data_bindings",
+    "display_only_paths",
+    "encode",
+    "gate_message",
+    "json_str",
+    "proposed_calls",
+    "resume_schema",
+    "icon",
+    "read_turn",
+    "resume_entries",
+    "resume_entry",
+    "surface_problems",
+    "surface",
+    "user_message_content",
+    "template_of",
+    "template_subtree_ids",
+    "update_components",
+    "update_data_model",
+]

keystone_agui-0.1.1/a2a_ext.py

@@ -0,0 +1,522 @@
+"""A2UI over A2A — the a2ui.org extension's wire shapes (v0.9.1), as pure dict helpers.
+
+One owner for both directions and both services: visual-builder EMITS these parts on its
+A2A door and READS the click coming back; master-agent reads the parts off the a2a-sdk's
+proto objects and emits the click. Two hand-rolled copies of `{"kind": "data", ...}` is
+two chances to disagree about where the mime marker sits.
+
+Detection is deliberately belt-and-braces: the spec marks the part with
+``metadata.mimeType``, but the a2a-sdk maps a JSON part onto a protobuf whose ``data``
+field is a bare ``Value`` — part-level metadata does not reliably survive the mapping.
+So a reader accepts EITHER the marker or the structure (every A2UI message carries one
+of a closed set of top-level keys), and an emitter stamps the marker on the artifact's
+metadata too, which does survive.
+
+**The message list travels wrapped in an object, under ``STEP_UI_KEY`` — a deliberate
+deviation from the a2ui.org spec's own literal example, which draws ``data`` as a bare
+list.** Found the hard way, building master-agent's A2A client (Task 5 of FDP-3028): a
+bare list crossing ``DataPart.data`` fails Pydantic validation inside the a2a-sdk BEFORE
+any of this repo's code runs. Confirmed against ``a2a-sdk`` 1.1.2 — the newest release
+ever published, so there is no newer version to pick up a fix —
+``a2a.compat.v0_3.types.DataPart.data`` is typed ``dict[str, Any]``, not ``list``.
+Feeding the spec-literal shape through a real client reproducibly raises
+``pydantic_core.ValidationError: Input should be a valid dictionary`` on both the
+streaming and the buffered path, which the caller cannot tell apart from a genuine
+outage. Three reasons this is the fix rather than a client-side workaround:
+
+1. A2A's ``DataPart.data`` is a structured object BY CONTRACT, and the transport
+   enforces it. When the extension spec and the transport contract disagree, the
+   transport wins — nothing crosses otherwise.
+2. This is the mechanism this stack already runs on: the shipped HITL resume part wraps
+   ITS list in a dict too (``{"hitl_decisions": [...]}``,
+   ``master-agent/clients/specialist_client.py``) and has worked in production against
+   real Visual Builder.
+3. ``STEP_UI_KEY`` ("a2ui") is not an invented name — it is this repo's EXISTING key for
+   exactly this payload (:mod:`keystone.agui.a2ui`, the same key VB's own runtime ``ui``
+   frame already uses for the same message list).
+
+A future reader must not "fix" :func:`a2ui_data_part` back to the spec's literal bare
+list — that is the shape that cannot cross the wire at all, not a stricter-than-needed
+choice made here. The READ side stays liberal on purpose: :func:`a2ui_messages_of_part`
+accepts both this wrapped shape and the spec-literal bare list, because a peer that
+reaches us over a transport that does not type-check ``DataPart.data`` (or an older
+build of this repo) may still send the bare form, and it must keep working.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .a2ui import STEP_UI_KEY, VERSION
+
+EXTENSION_URI = "https://a2ui.org/a2a-extension/a2ui/v0.9.1"
+MIME_TYPE = "application/a2ui+json"
+ACTIVATION_HEADER = "X-A2A-Extensions"
+
+#: The closed set of A2UI message kinds — one of these is present on every message the
+#: v0.9 protocol defines, which is what makes structural detection sound.
+_MESSAGE_KEYS = frozenset({"createSurface", "updateComponents", "updateDataModel", "deleteSurface", "action"})
+
+
+def a2ui_part_data(messages: list[dict[str, Any]]) -> dict[str, Any]:
+    """The dict payload of an A2UI DataPart — the wrapper R9 requires, in one place.
+
+    Both directions build a ``DataPart`` from this, not from a hand-rolled ``{"a2ui": ...}``
+    literal: :func:`a2ui_data_part` (VB's outbound surface) calls it below, and master-agent's
+    outbound click builds its protobuf ``Value`` from it directly — the same way the shipped
+    HITL resume part builds its ``Struct`` (``clients/specialist_client.py``). One accessor
+    writing the wrapper key is what R10/R11 mean by "the unwrap/wrap rule has exactly one
+    owner": a second place that writes ``{"a2ui": ...}`` by hand is a second copy to drift.
+    """
+    return {STEP_UI_KEY: messages}
+
+
+def a2ui_data_part(messages: list[dict[str, Any]]) -> dict[str, Any]:
+    """One A2A DataPart carrying a list of A2UI messages.
+
+    Wrapped under ``STEP_UI_KEY`` rather than sent as the spec's own bare list — see the
+    module docstring for why the transport, not the extension spec, wins this one.
+    """
+    return {"kind": "data", "data": a2ui_part_data(messages), "metadata": {"mimeType": MIME_TYPE}}
+
+
+#: The ui-component ref an A2UI surface was drawn from, on the ARTIFACT's metadata.
+#:
+#: **Not in the data part.** :func:`a2ui_part_data` has exactly one owner and BOTH directions build
+#: from it — master-agent's outbound CLICK included — and a click is drawn from no component, so a
+#: ref added there would ride one and mean nothing. Artifact metadata is also the copy that
+#: reliably survives the a2a-sdk's proto mapping (see the module docstring), which is precisely the
+#: property this key needs: its reader is master-agent, on the proto side.
+#:
+#: Same name as :data:`CARDS_COMPONENT_KEY` and the same meaning, deliberately — one word for "what
+#: was drawn" across both render formats — but a different PLACE, because the two parts differ in
+#: what they can carry (see :func:`cards_data_part`).
+A2UI_COMPONENT_KEY = "component"
+
+#: The ui-component REGISTRY KEY the same surface was drawn from (FDP-3036), beside the ref above.
+#:
+#: **Why both, when they are usually the same string.** The ref is the catalog name the drawing
+#: agent's tool enumerates — it is what :data:`OPEN_SURFACES_KEY` is keyed by, because that is the
+#: only name the peer's own tool can take as an argument. The key is what the UI Components
+#: registry resolves a PUBLISHED BUNDLE by, which is what a reader that wants to draw the surface
+#: again needs. ``ui_component_render_tool``'s ``entry.get("key") or ref`` is where the two part
+#: company: a component whose spec was not named after its key has a ref that resolves to nothing
+#: in the registry. Collapsing them into one field would make that case render an empty frame.
+#:
+#: Omitted when blank, the rule every other optional key here follows —
+#: :func:`component_key_of_artifact` answers ``""`` for a peer built before this existed, and
+#: deliberately does NOT fall back to the ref.
+A2UI_COMPONENT_REGISTRY_KEY = "componentKey"
+
+
+def a2ui_artifact_metadata(component: str = "", component_key: str = "") -> dict[str, Any]:
+    """The metadata of an artifact carrying an A2UI surface: the mime marker, and what was drawn.
+
+    ``component`` is OMITTED rather than sent blank — the same rule :func:`cards_data_part` applies
+    to its own copy: absent reads as "this runtime does not send it", while ``""`` would read as a
+    component whose ref is genuinely blank. A peer built before this key existed sends the marker
+    alone, and :func:`component_of_artifact` answers ``""`` for it.
+
+    ``component_key`` (FDP-3036) rides beside it under the same rule. See
+    :data:`A2UI_COMPONENT_REGISTRY_KEY` for why it is a second field and not the same one.
+    """
+    metadata: dict[str, Any] = {"mimeType": MIME_TYPE}
+    if component:
+        metadata[A2UI_COMPONENT_KEY] = component
+    if component_key:
+        metadata[A2UI_COMPONENT_REGISTRY_KEY] = component_key
+    return metadata
+
+
+def component_of_artifact(metadata: Any) -> str:
+    """The ui-component ref an A2UI artifact names, or ``""`` when it names none.
+
+    Total, and blank for every shape that is not a string under the key: the caller uses this to
+    decide whether a LATER turn can update the surface in place, and a non-string ref would name a
+    component no catalog can resolve. Falling back to "nothing is open" costs a redraw; guessing
+    costs an update aimed at a surface that does not exist.
+    """
+    if not isinstance(metadata, dict):
+        return ""
+    ref = metadata.get(A2UI_COMPONENT_KEY)
+    return ref if isinstance(ref, str) else ""
+
+
+def component_key_of_artifact(metadata: Any) -> str:
+    """The ui-component REGISTRY KEY an A2UI artifact names, or ``""`` when it names none.
+
+    Total and strictly typed, like its ref twin above — and with one rule of its own:
+    **it never falls back to the ref.** A ref that is not a key resolves to nothing in the UI
+    Components registry, so substituting one would turn "I do not know what was drawn" into a
+    lookup that misses and renders an empty frame — the exact failure this key was added to stop.
+    Blank means the drawing runtime predates FDP-3036, and a reader draws nothing for it.
+    """
+    if not isinstance(metadata, dict):
+        return ""
+    key = metadata.get(A2UI_COMPONENT_REGISTRY_KEY)
+    return key if isinstance(key, str) else ""
+
+
+#: Surfaces the CALLER already has on the employee's screen that the peer being called drew, as
+#: ``{component_ref: surface_id}``, on the outbound MESSAGE's metadata.
+#:
+#: **The problem it solves.** A consult runs on a fresh peer thread per tool call, so
+#: ``update_ui_component`` — which finds an open surface by scanning the current thread's own
+#: messages — sees nothing a previous consult drew and can only answer "call render_ui_component
+#: first". The employee then gets a second copy of the form for every field they fill in. Handing
+#: the open surfaces back is what lets the peer change the one already on screen.
+#:
+#: **Keyed by REF, not by surface id.** The peer's own tool takes a ``component`` argument that is a
+#: ``Literal`` over its catalog refs; a surface id is not something it can name. One entry per ref
+#: also settles the duplicate case by construction — a form drawn twice has one live surface, the
+#: newest, and the caller resolves that before sending.
+#:
+#: **Message metadata, not a data part.** Every reader on the inbound side treats a data part's
+#: PRESENCE as a branch selector (a resume, a click), so a hint riding one would change what the
+#: turn IS. Metadata is inert: a peer that does not know this key ignores it and behaves exactly as
+#: it did before, which is the compatibility this needs in both directions.
+OPEN_SURFACES_KEY = "open_surfaces"
+
+
+def open_surfaces_metadata(open_surfaces: dict[str, str] | None) -> dict[str, Any]:
+    """Message metadata naming the peer's surfaces already on screen — ``{}`` when there are none.
+
+    Empty means the key is ABSENT rather than present-and-empty: absent and empty mean the same
+    thing to a reader, and an empty object on every message would be noise on a wire whose other
+    optional keys are all omitted the same way (see :func:`cards_data_part`).
+    """
+    clean = {ref: sid for ref, sid in (open_surfaces or {}).items() if isinstance(ref, str) and ref and sid}
+    return {OPEN_SURFACES_KEY: clean} if clean else {}
+
+
+def open_surfaces_of_message(metadata: Any) -> dict[str, str]:
+    """``{component_ref: surface_id}`` off an inbound message's metadata — ``{}`` when it names none.
+
+    Total and strictly typed: every entry that is not a non-blank ``str`` → non-blank ``str`` is
+    dropped rather than passed on. This value decides which surface a later ``updateDataModel`` is
+    aimed at, and an operation aimed at a surface that does not exist is silently invisible — A2UI
+    has no fallback. Dropping an entry costs one redraw, which is exactly the behaviour that
+    existed before this key.
+    """
+    if not isinstance(metadata, dict):
+        return {}
+    raw = metadata.get(OPEN_SURFACES_KEY)
+    if not isinstance(raw, dict):
+        return {}
+    return {ref: sid for ref, sid in raw.items() if isinstance(ref, str) and ref and isinstance(sid, str) and sid}
+
+
+def looks_like_a2ui(data: Any) -> bool:
+    """Is this a non-empty list of A2UI messages? Structure only — no marker consulted."""
+    return (
+        isinstance(data, list)
+        and bool(data)
+        and all(isinstance(m, dict) and bool(_MESSAGE_KEYS & m.keys()) for m in data)
+    )
+
+
+def a2ui_messages_of_part(part: Any) -> list[dict[str, Any]] | None:
+    """The A2UI messages in one raw-JSON part, or ``None`` when it is not an a2ui part.
+
+    Accepts the dict-wrapped shape this module WRITES (``data: {STEP_UI_KEY: [...]}``) and,
+    liberally, the a2ui.org spec's own literal bare-list shape — marked or unmarked either
+    way. See the module docstring: only the write side changed, the read side stays liberal.
+    """
+    if not isinstance(part, dict) or part.get("kind") not in (None, "data"):
+        return None
+    data = part.get("data")
+    meta = part.get("metadata")
+    marked = isinstance(meta, dict) and meta.get("mimeType") == MIME_TYPE
+
+    messages = data.get(STEP_UI_KEY) if isinstance(data, dict) else data
+    if marked and isinstance(messages, list):
+        return [m for m in messages if isinstance(m, dict)]
+    if looks_like_a2ui(messages):
+        return list(messages)
+    return None
+
+
+#: The employee's own utterance for one *Send message* click, crossing A2A as its own marked part.
+#:
+#: **Why it is not an A2UI message.** ``_MESSAGE_KEYS`` above is the closed set the v0.9 protocol
+#: defines, and "the employee said this" is not one of them — folding it in would make a private
+#: addition to a standard vocabulary that every other reader of these parts would then have to
+#: know about. It is a fact about the TURN, not a change to a surface, so it travels beside the
+#: surface parts rather than inside them, with a marker of this stack's own.
+SPOKEN_MIME = "application/vnd.keystone.a2ui-spoken+json"
+
+#: The wrapper key, for the same transport reason ``STEP_UI_KEY`` is used above: ``DataPart.data``
+#: is typed ``dict[str, Any]`` by the a2a-sdk, so a bare string could not cross either.
+SPOKEN_KEY = "spoken"
+
+
+def spoken_data_part(text: str) -> dict[str, Any]:
+    """One A2A DataPart carrying what the employee said by pressing a control.
+
+    A click on a control whose author declared it *Send message* IS the employee saying that
+    sentence, and only the runtime that holds the component's handler table can tell which clicks
+    those are (``visual-builder``'s ``services.runtime.a2ui_action.spoken_text``). Downstream hops
+    cannot re-derive it, so it has to travel — this is the shape it travels in on the A2A hop, the
+    twin of the AG-UI door's ``TEXT_MESSAGE_START(role="user")``.
+    """
+    return {"kind": "data", "data": {SPOKEN_KEY: text}, "metadata": {"mimeType": SPOKEN_MIME}}
+
+
+def spoken_of_part(part: Any) -> str | None:
+    """What the employee said, from one raw-JSON part — ``None`` when the part is not one of these.
+
+    Strictly marker-gated, unlike :func:`a2ui_messages_of_part`: an A2UI message is recognisable by
+    its own structure, while this payload is one string under one key and structure alone would
+    claim any ``{"spoken": …}`` a peer happened to send. The marker is read from the part AND from
+    the artifact metadata copy the emitter stamps (the part-level one does not reliably survive the
+    a2a-sdk's proto mapping — see the module docstring), so a caller passes the artifact's metadata
+    in when it has decoded a proto part.
+    """
+    if not isinstance(part, dict) or part.get("kind") not in (None, "data"):
+        return None
+    meta = part.get("metadata")
+    if not (isinstance(meta, dict) and meta.get("mimeType") == SPOKEN_MIME):
+        return None
+    data = part.get("data")
+    text = data.get(SPOKEN_KEY) if isinstance(data, dict) else None
+    return text if isinstance(text, str) and text.strip() else None
+
+
+#: A finished Google Chat ``cardsV2`` payload, crossing A2A as its own marked part (FDP-3244 /
+#: FR-127a).
+#:
+#: **Its own mime, not** :data:`MIME_TYPE`. ``_MESSAGE_KEYS`` above is the closed set the A2UI v0.9
+#: protocol defines and ``cardsV2`` is not one of them: this is a rendering the CHANNEL draws, not a
+#: surface an A2UI renderer draws. Folding it into the A2UI part would make a private addition to a
+#: standard vocabulary that every other reader of these parts would then have to know about — the
+#: same reasoning that keeps :data:`SPOKEN_MIME` separate.
+#:
+#: The payload is the component author's, published through ui-component and validated by ITS gate
+#: (``services/ui-component/domain/publication.py``). Nothing on this wire reads inside ``cards``.
+CARDS_MIME = "application/vnd.keystone.cards-v2+json"
+
+CARDS_KEY = "cardsV2"
+CARDS_SURFACE_KEY = "surfaceId"
+CARDS_COMPONENT_KEY = "component"
+
+
+def cards_data_part(cards: list[dict[str, Any]], *, surface_id: str, component: str = "") -> dict[str, Any]:
+    """One A2A DataPart carrying a finished ``cardsV2`` payload.
+
+    ``surface_id`` rides IN the payload rather than being recovered from it, which is the one
+    structural difference from :func:`a2ui_data_part`: an A2UI message names its own ``surfaceId``
+    on every operation, and a Google card names nothing — it is a channel's render format, with no
+    place for our routing key. Without it a click has no drawer to go back to, so it is a required
+    argument here and a required field on read.
+
+    ``component`` names WHAT was drawn (it becomes the A2UI action's ``sourceComponentId``) and is
+    optional in a way ``surface_id`` is not. Omitted rather than sent empty: a reader treats absent
+    as "this runtime does not send it", while ``""`` would read as a component whose ref is blank.
+    """
+    data: dict[str, Any] = {CARDS_KEY: cards, CARDS_SURFACE_KEY: surface_id}
+    if component:
+        data[CARDS_COMPONENT_KEY] = component
+    return {"kind": "data", "data": data, "metadata": {"mimeType": CARDS_MIME}}
+
+
+def cards_of_part(part: Any) -> dict[str, Any] | None:
+    """The card payload in one raw-JSON part, or ``None`` when it is not one.
+
+    Returns ``{"cards", "surface_id", "component"}`` — flat keys rather than the wire's camelCase,
+    because the callers are Python and the wire shape has exactly one owner (this module).
+
+    Liberal about the MARKER and strict about the SHAPE, mirroring :func:`a2ui_messages_of_part`:
+    part-level metadata does not reliably survive the a2a-sdk's proto mapping, so an unmarked part
+    with the right structure is accepted — but a payload with no ``surfaceId``, or with an empty
+    card list, is refused outright. Both are unroutable or unrenderable, and minting a substitute id
+    would file a later click under an agent that never drew anything.
+    """
+    if not isinstance(part, dict) or part.get("kind") not in (None, "data"):
+        return None
+    data = part.get("data")
+    if not isinstance(data, dict):
+        return None
+    cards = data.get(CARDS_KEY)
+    if not isinstance(cards, list) or not cards or not all(isinstance(c, dict) for c in cards):
+        return None
+    surface_id = data.get(CARDS_SURFACE_KEY)
+    if not isinstance(surface_id, str) or not surface_id:
+        return None
+    component = data.get(CARDS_COMPONENT_KEY)
+    return {
+        "cards": list(cards),
+        "surface_id": surface_id,
+        "component": component if isinstance(component, str) else "",
+    }
+
+
+#: A finished Microsoft Teams Adaptive Card, crossing A2A as its own marked part (FDP-5466 — the
+#: sign-in card a consulted specialist draws on Teams). The Teams twin of :data:`CARDS_MIME`, with
+#: the same rules: its own mime, ``surfaceId`` in the payload, nothing on this wire reads the card.
+ADAPTIVE_CARD_MIME = "application/vnd.keystone.adaptive-card+json"
+
+ADAPTIVE_CARD_KEY = "adaptiveCard"
+
+
+def adaptive_card_data_part(card: dict[str, Any], *, surface_id: str) -> dict[str, Any]:
+    """One A2A DataPart carrying a finished Adaptive Card."""
+    return {
+        "kind": "data",
+        "data": {ADAPTIVE_CARD_KEY: card, CARDS_SURFACE_KEY: surface_id},
+        "metadata": {"mimeType": ADAPTIVE_CARD_MIME},
+    }
+
+
+def adaptive_card_of_part(part: Any) -> dict[str, Any] | None:
+    """``{"card", "surface_id"}`` from one raw-JSON part, or ``None`` when it is not one.
+
+    Same posture as :func:`cards_of_part`: liberal about the marker, strict about the shape. A
+    payload with no ``surfaceId`` or an empty card is refused.
+    """
+    if not isinstance(part, dict) or part.get("kind") not in (None, "data"):
+        return None
+    data = part.get("data")
+    if not isinstance(data, dict):
+        return None
+    card = data.get(ADAPTIVE_CARD_KEY)
+    if not isinstance(card, dict) or not card:
+        return None
+    surface_id = data.get(CARDS_SURFACE_KEY)
+    if not isinstance(surface_id, str) or not surface_id:
+        return None
+    return {"card": dict(card), "surface_id": surface_id}
+
+
+def action_messages(action: dict[str, Any]) -> list[dict[str, Any]]:
+    """The client→server message list for one user action (the flat click dict, wrapped)."""
+    return [{"version": VERSION, "action": dict(action)}]
+
+
+def action_of(messages: list[dict[str, Any]]) -> dict[str, Any] | None:
+    """The first action message's payload, or ``None``."""
+    for message in messages:
+        if isinstance(message, dict) and isinstance(message.get("action"), dict):
+            return message["action"]
+    return None
+
+
+def surface_id_of(messages: list[dict[str, Any]]) -> str:
+    """The ONE surface this message list addresses — '' when none or more than one.
+
+    Ambiguity is refused rather than guessed: the consumer keys a routing table on this,
+    and filing a two-surface batch under either id would misroute the other's clicks.
+    """
+    ids = {
+        str(body["surfaceId"])
+        for message in messages
+        if isinstance(message, dict)
+        for body in message.values()
+        if isinstance(body, dict) and body.get("surfaceId")
+    }
+    return ids.pop() if len(ids) == 1 else ""
+
+
+def restore_ints(value: Any) -> Any:
+    """Recursively turn whole-number floats back into ints.
+
+    protobuf ``Struct``'s only numeric type is a double, so every int crossing the
+    a2a-sdk arrives as a float (``gate_seq: 2 → 2.0``). A genuine ``2.0`` also becomes
+    ``2`` — accepted: A2UI payloads carry no semantically-float whole numbers.
+    """
+    if isinstance(value, float) and value.is_integer():
+        return int(value)
+    if isinstance(value, list):
+        return [restore_ints(v) for v in value]
+    if isinstance(value, dict):
+        return {k: restore_ints(v) for k, v in value.items()}
+    return value
+
+
+# ── FDP-6261 / FR-162 — the caller's turn and an agent's files, over A2A ──────────────────────────
+
+#: The caller's AG-UI turn, on the outbound MESSAGE's metadata: ``{"run_id", "conversation_id"}``.
+#:
+#: master-agent sends it when it consults or hands off, so a specialist that makes a file records the
+#: run and the conversation the EMPLOYEE is in (agent-conversations shows an agent's file only when
+#: its ``invocation_id`` is one of that conversation's runs). Message metadata for the reason
+#: :data:`OPEN_SURFACES_KEY` gives: inert to a peer that does not read it.
+TURN_KEY = "keystone"
+#: The bound file-artifact puts on both ids (``thread_id`` / ``invocation_id``, ``max_length=127``).
+_TURN_ID_MAX = 127
+
+#: A file an agent made, as a ``custom`` stream item and an AG-UI ``activityType``. Spelled out
+#: rather than imported: the producer is the agent SDK (``keystone.agent_sdk.clients.file_artifact``),
+#: which this library does not depend on. A contract with Front Desk: do not rename.
+FILE_ACTIVITY = "keystone.file"
+#: The artifact-level marker of a file artifact. Artifact metadata survives the a2a-sdk's proto
+#: mapping (see the module docstring); the data part's own ``type`` is the structural check.
+FILE_MIME_TYPE = "application/vnd.keystone.file+json"
+_FILE_KEYS = ("artifact_id", "name", "mime_type", "size")
+
+
+def turn_metadata(*, run_id: str = "", conversation_id: str = "") -> dict[str, Any]:
+    """Message metadata naming the caller's turn — ``{}`` when it names nothing."""
+    ids = {
+        key: value.strip()
+        for key, value in (("run_id", run_id), ("conversation_id", conversation_id))
+        if isinstance(value, str) and value.strip()
+    }
+    return {TURN_KEY: ids} if ids else {}
+
+
+def turn_of_message(metadata: Any) -> tuple[str, str]:
+    """``(run_id, conversation_id)`` off an inbound message's metadata; ``""`` for each it lacks.
+
+    An id that is not a non-blank string, or is longer than file-artifact accepts, is dropped: a
+    file without it is hidden, which fails closed, while a wrong one would bind it to a run it does
+    not belong to.
+    """
+    raw = metadata.get(TURN_KEY) if isinstance(metadata, dict) else None
+    if not isinstance(raw, dict):
+        return "", ""
+
+    def _id(key: str) -> str:
+        value = raw.get(key)
+        value = value.strip() if isinstance(value, str) else ""
+        return value if len(value) <= _TURN_ID_MAX else ""
+
+    return _id("run_id"), _id("conversation_id")
+
+
+def file_content(data: Any) -> dict[str, Any] | None:
+    """``{artifact_id, name, mime_type, size}`` of a file item, or ``None`` when it is not one.
+
+    Reads the SDK's ``custom`` item and the data part below alike (both carry ``type``). ``size``
+    is restored to an int: it crosses the a2a-sdk's protobuf ``Struct`` as a double.
+    """
+    if not isinstance(data, dict) or data.get("type") != FILE_ACTIVITY:
+        return None
+    artifact_id, name, mime_type, size = (data.get(key) for key in _FILE_KEYS)
+    if not (isinstance(artifact_id, str) and artifact_id and isinstance(name, str) and isinstance(mime_type, str)):
+        return None
+    if isinstance(size, float) and size.is_integer():
+        size = int(size)
+    if isinstance(size, bool) or not isinstance(size, int) or size < 0:
+        return None
+    return {"artifact_id": artifact_id, "name": name, "mime_type": mime_type, "size": size}
+
+
+def file_data_part(content: dict[str, Any]) -> dict[str, Any]:
+    """One A2A DataPart carrying a file an agent made (``content`` as :func:`file_content` returns)."""
+    return {"kind": "data", "data": {"type": FILE_ACTIVITY, **content}, "metadata": {"mimeType": FILE_MIME_TYPE}}
+
+
+def file_artifact(content: dict[str, Any]) -> dict[str, Any]:
+    """The A2A v0.3 artifact for one file: its own id, one data part, the marker on its metadata."""
+    return {
+        "artifactId": f"file-{content['artifact_id']}",
+        "parts": [file_data_part(content)],
+        "metadata": {"mimeType": FILE_MIME_TYPE},
+    }
+
+
+def file_of_part(part: Any) -> dict[str, Any] | None:
+    """The file in one A2A part (``{"kind": "data", "data": …}``), or ``None`` when it carries none."""
+    if not isinstance(part, dict):
+        return None
+    return file_content(part.get("data"))