Adam Moussa
48a81c0802
Security-review follow-up (LOGIC-01/02/05, all confirmed correctness). - New transport-neutral `decisions.normalize_decision(raw, *, allow_abandon)` is the single source of truth: approve-allowlist→approve; abandon-allowlist→abandon ONLY when allow_abandon; everything else (prose, empty, abandon-verbs when disallowed) → request_changes with the full reply as notes; idempotent on an already-formed decision dict. slack_adapter.map_plan_decision is now a thin wrapper (default allow_abandon=True, no caller churn). - LOGIC-01/02: graph._parse_decision now delegates to normalize_decision (was: any unrecognized verb → abandon → FAILED). The graph is now the universal safe backstop, so EVERY writer that bypassed the listener mapping — operator CLI answer_on_behalf (raw), Coordinator.submit_answer (raw), the recovery sweep — loops back on prose instead of silently FAILing the task. Explicit abandon still abandons (preserves the confirmed-button path). - LOGIC-05: the Slack FREE-TEXT reply path maps with allow_abandon=False, so a bare "cancel"/"stop"/"abandon" typed in-thread → request_changes (never terminal abandon); abandon stays reachable only via the confirm-guarded button. Tests: graph unrecognized→loops-back (not FAILED), operator raw-prose→request_ changes, free-text destructive verbs→request_changes vs button→abandon, normalizer idempotency. 1484 passed.
687 lines
28 KiB
Python
687 lines
28 KiB
Python
"""Slack Block Kit transport adapter (design §3.3.1, §7.1 P1).
|
|
|
|
The first concrete :class:`~agent_team.transport.base.Transport` implementation.
|
|
P1 ships the human gate over **one** transport (Slack first), so this adapter
|
|
must satisfy the §3.3.1 contracts the durable responder depends on:
|
|
|
|
* :meth:`SlackTransport.post_question` renders a :class:`QuestionSet` as a Slack
|
|
Block Kit message, embeds the ``question_id`` in the message ``callback_id``
|
|
(Slack's native callback metadata, the analogue of the GitHub ``<!-- shq:... -->``
|
|
marker), posts it via an **injected** poster callable, and returns the Slack
|
|
message ``ts`` as the ``channel_ref`` stored on the ledger row.
|
|
* :meth:`SlackTransport.parse_answer` normalizes an inbound Slack payload
|
|
(an interactive ``block_actions`` callback or a plain text/slash reply) to
|
|
``(question_id, answer, via)`` for the first-answer-wins compare-and-set.
|
|
|
|
This module is **transport I/O only** and carries no live wiring: the network
|
|
call is a dependency-injected ``poster`` callable, so the adapter is unit
|
|
testable and ships nothing provisioned. A production deployment supplies a
|
|
poster backed by the Composio Slack connector or ``slack_sdk`` (design §3 —
|
|
"the R720 routes Slack/Jira/Notion through" the Composio connector); the
|
|
foundation must not import or require either, so the default poster raises a
|
|
clear "not configured" error rather than reaching the network.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
from collections.abc import Callable, Mapping, Sequence
|
|
from typing import Any
|
|
|
|
from agent_team.decisions import (
|
|
ABANDON_VERBS as _ABANDON_VERBS,
|
|
)
|
|
from agent_team.decisions import (
|
|
APPROVE_VERBS as _APPROVE_VERBS,
|
|
)
|
|
from agent_team.decisions import (
|
|
normalize_decision,
|
|
)
|
|
from agent_team.transport.base import (
|
|
NormalizedAnswer,
|
|
QuestionSet,
|
|
Transport,
|
|
)
|
|
|
|
__all__ = [
|
|
"CALLBACK_ID_PREFIX",
|
|
"PLAN_DECISION_ABANDON_ACTION",
|
|
"PLAN_DECISION_ABANDON_VERBS",
|
|
"PLAN_DECISION_APPROVE_ACTION",
|
|
"PLAN_DECISION_APPROVE_VERBS",
|
|
"PLAN_DECISION_KIND",
|
|
"PLAN_DECISION_REQUEST_CHANGES_ACTION",
|
|
"VIA_SLACK",
|
|
"SlackPostError",
|
|
"SlackPoster",
|
|
"SlackTransport",
|
|
"build_callback_id",
|
|
"build_plan_decision_blocks",
|
|
"build_question_blocks",
|
|
"build_request_changes_modal",
|
|
"map_plan_decision",
|
|
"parse_callback_id",
|
|
]
|
|
|
|
# ``via`` channel-identity tag recorded in the ledger's ``answered_via`` column
|
|
# for the audit trail (§3.3.1).
|
|
VIA_SLACK = "slack"
|
|
|
|
# Namespacing prefix for the embedded ``callback_id`` so an inbound Slack
|
|
# interaction can be unambiguously mapped back to its ledger ``question_id``.
|
|
# Mirrors the GitHub ``<!-- shq:... -->`` marker convention (``shq`` = Sea Haven
|
|
# question) from the base module.
|
|
CALLBACK_ID_PREFIX = "shq"
|
|
|
|
# The ``pending_questions.kind`` discriminator for the plan-review decision gate.
|
|
# Mirrors ``agent_team.graph.PLAN_DECISION_KIND`` and the DB CHECK constraint;
|
|
# duplicated here (as a plain string constant) so the transport/listener layer
|
|
# can route kind-aware decisions WITHOUT importing the graph module.
|
|
PLAN_DECISION_KIND = "plan_decision"
|
|
|
|
# Plan-decision verb allowlists (B3). Re-exported from the transport-neutral
|
|
# :mod:`agent_team.decisions` home (the single source of truth) under their
|
|
# historical names so existing importers/tests are unchanged. A reply /
|
|
# button-value to a ``kind == 'plan_decision'`` question is normalized (lowercase
|
|
# + strip) and matched against these allowlists. Anything ELSE — arbitrary
|
|
# change-request prose — maps to ``request_changes`` carrying the FULL original
|
|
# reply as ``notes`` (the safe default; NEVER an accidental approve or abandon).
|
|
# See :func:`map_plan_decision` / :func:`agent_team.decisions.normalize_decision`.
|
|
PLAN_DECISION_APPROVE_VERBS: frozenset[str] = _APPROVE_VERBS
|
|
PLAN_DECISION_ABANDON_VERBS: frozenset[str] = _ABANDON_VERBS
|
|
|
|
# Block Kit action_id namespace for the three plan-gate buttons. Each carries
|
|
# the decision verb; ``request_changes`` opens a modal for free-form notes.
|
|
PLAN_DECISION_ACTION_PREFIX = "plan_decision"
|
|
PLAN_DECISION_APPROVE_ACTION = f"{PLAN_DECISION_ACTION_PREFIX}:approve"
|
|
PLAN_DECISION_REQUEST_CHANGES_ACTION = f"{PLAN_DECISION_ACTION_PREFIX}:request_changes"
|
|
PLAN_DECISION_ABANDON_ACTION = f"{PLAN_DECISION_ACTION_PREFIX}:abandon"
|
|
|
|
|
|
def map_plan_decision(raw_answer: Any, *, allow_abandon: bool = True) -> dict[str, str]:
|
|
"""Map a raw plan-gate reply to a structured ``{"decision", "notes"}`` dict.
|
|
|
|
Thin wrapper over the transport-neutral
|
|
:func:`agent_team.decisions.normalize_decision` (the single source of truth),
|
|
kept so existing importers/tests are unchanged. THE LOAD-BEARING B3 SAFETY
|
|
MAPPING normalizes a reply BEFORE it reaches the graph so arbitrary change
|
|
prose becomes ``request_changes`` (carrying the full original reply as
|
|
``notes``) rather than an accidental approve/abandon.
|
|
|
|
``allow_abandon`` (LOGIC-05) distinguishes a CONFIRMED destructive intent
|
|
from free text:
|
|
|
|
* ``allow_abandon=True`` (the default, used by the confirm-dialog-guarded
|
|
Block Kit Abandon BUTTON and explicit-id paths) — a bare abandon-verb in
|
|
:data:`PLAN_DECISION_ABANDON_VERBS` maps to ``abandon``.
|
|
* ``allow_abandon=False`` (FREE-TEXT thread replies) — those SAME verbs are
|
|
NOT honoured as a destructive abandon; they fall through to
|
|
``request_changes`` so a casually-typed "cancel" never terminally fails a
|
|
task with no confirmation. Only the confirmed button can abandon.
|
|
|
|
The answer is opaque DATA throughout — never executed or interpreted beyond
|
|
the verb match. Returns the dict the graph's decision parser consumes.
|
|
"""
|
|
return normalize_decision(raw_answer, allow_abandon=allow_abandon)
|
|
|
|
|
|
# Type of the network seam: given the rendered Slack message kwargs, perform the
|
|
# ``chat.postMessage`` and return the response payload. The only field this
|
|
# adapter requires from the response is the message ``ts`` (the ``channel_ref``).
|
|
SlackPoster = Callable[[dict[str, Any]], Mapping[str, Any]]
|
|
|
|
|
|
class SlackPostError(RuntimeError):
|
|
"""Raised when posting a Slack message fails or no poster is configured.
|
|
|
|
The §3.3.1 delivery rule writes the ledger row ``open`` *before* posting, so
|
|
a raised :class:`SlackPostError` leaves the row ``open`` with no
|
|
``channel_ref`` and the reconcile loop retries delivery idempotently. The
|
|
caller (responder/delivery loop) is expected to catch this and leave the row
|
|
for reconcile rather than treating the question as delivered.
|
|
"""
|
|
|
|
|
|
def _default_poster(_message: dict[str, Any]) -> Mapping[str, Any]:
|
|
"""Default poster: refuse to reach the network (pre-deployment scaffolding).
|
|
|
|
The foundation must not provision or wire live infrastructure, so a
|
|
:class:`SlackTransport` constructed without an explicit ``poster`` cannot
|
|
post. Production injects a poster backed by the Composio Slack connector or
|
|
``slack_sdk``.
|
|
"""
|
|
raise SlackPostError(
|
|
"SlackTransport has no poster configured; inject a Slack poster "
|
|
"callable (Composio connector / slack_sdk) before posting."
|
|
)
|
|
|
|
|
|
def build_callback_id(question_id: str) -> str:
|
|
"""Embed ``question_id`` in a namespaced Slack ``callback_id``.
|
|
|
|
Slack echoes the message-level ``callback_id`` back on every interaction
|
|
payload, so it is the natural carrier for the ledger ``question_id``
|
|
(§3.3.1: "Slack ``callback_id``").
|
|
"""
|
|
return f"{CALLBACK_ID_PREFIX}:{question_id}"
|
|
|
|
|
|
def parse_callback_id(callback_id: str) -> str:
|
|
"""Recover the ``question_id`` from a :func:`build_callback_id` value.
|
|
|
|
Accepts both the namespaced form (``shq:<question_id>``) and a bare
|
|
``question_id`` (defensive, in case a payload surfaces the id directly).
|
|
Raises :class:`ValueError` on an empty / malformed callback id so a
|
|
mis-mapped answer fails loudly instead of being silently mis-attributed.
|
|
"""
|
|
if not callback_id:
|
|
raise ValueError("empty callback_id")
|
|
prefix = f"{CALLBACK_ID_PREFIX}:"
|
|
if callback_id.startswith(prefix):
|
|
question_id = callback_id[len(prefix) :]
|
|
if not question_id:
|
|
raise ValueError(f"callback_id missing question_id: {callback_id!r}")
|
|
return question_id
|
|
return callback_id
|
|
|
|
|
|
def build_question_blocks(
|
|
question_set: QuestionSet, deadline: str
|
|
) -> list[dict[str, Any]]:
|
|
"""Render a :class:`QuestionSet` as Slack Block Kit blocks.
|
|
|
|
Surfaces optional ``context`` (``repo`` / ``summary``) as a context block,
|
|
lists the ordered questions, and footnotes the ``deadline`` so Adam sees the
|
|
answer window. Returns a plain JSON-serializable list (no Slack SDK types),
|
|
keeping the adapter dependency-free.
|
|
"""
|
|
blocks: list[dict[str, Any]] = [
|
|
{
|
|
"type": "header",
|
|
"text": {
|
|
"type": "plain_text",
|
|
"text": f"Agent-team needs input (turn {question_set.turn})",
|
|
},
|
|
}
|
|
]
|
|
|
|
context_elements: list[dict[str, Any]] = []
|
|
repo = question_set.context.get("repo")
|
|
if repo:
|
|
context_elements.append({"type": "mrkdwn", "text": f"*repo:* {repo}"})
|
|
summary = question_set.context.get("summary")
|
|
if summary:
|
|
context_elements.append({"type": "mrkdwn", "text": str(summary)})
|
|
if context_elements:
|
|
blocks.append({"type": "context", "elements": context_elements})
|
|
|
|
for index, question in enumerate(question_set.questions, start=1):
|
|
blocks.append(
|
|
{
|
|
"type": "section",
|
|
"text": {"type": "mrkdwn", "text": f"*{index}.* {question}"},
|
|
}
|
|
)
|
|
|
|
blocks.append(
|
|
{
|
|
"type": "context",
|
|
"elements": [
|
|
{"type": "mrkdwn", "text": f"_Reply in this thread by {deadline}._"}
|
|
],
|
|
}
|
|
)
|
|
return blocks
|
|
|
|
|
|
def build_plan_decision_blocks(
|
|
question_id: str, body_text: str
|
|
) -> list[dict[str, Any]]:
|
|
"""Render the plan-gate decision surface as Block Kit blocks (B3).
|
|
|
|
A section carrying the human-readable ``body_text`` (the plan summary +
|
|
review findings + decision instructions assembled by the coordinator) plus
|
|
an ``actions`` block with the three decision buttons:
|
|
|
|
* **Approve** (``action_id="plan_decision:approve"``, ``style="primary"``);
|
|
* **Request changes** (``action_id="plan_decision:request_changes"``) — its
|
|
dedicated handler opens a modal for free-form notes;
|
|
* **Abandon** (``action_id="plan_decision:abandon"``, ``style="danger"``,
|
|
guarded by a ``confirm`` dialog so it is never a single-click mistake).
|
|
|
|
Each button's ``value`` encodes ``"<verb>:<question_id>"`` so an inbound
|
|
``block_actions`` payload can recover BOTH the verb and the ledger
|
|
``question_id`` even if the message metadata is absent. The ``question_id``
|
|
is ALSO carried in the message ``metadata.event_payload`` by the caller
|
|
(mirroring the clarifier), so recovery is double-anchored. The section text
|
|
is the always-visible fallback for non-interactive clients (a free-text
|
|
thread reply remains an equal path to all three decisions).
|
|
|
|
Returns a plain JSON-serializable list (no Slack SDK types).
|
|
"""
|
|
section_text = body_text if body_text else "Plan needs your decision."
|
|
# Slack section text caps at ~3000 chars; keep a margin.
|
|
if len(section_text) > 2900:
|
|
section_text = section_text[:2900].rstrip() + "…"
|
|
return [
|
|
{"type": "section", "text": {"type": "mrkdwn", "text": section_text}},
|
|
{
|
|
"type": "actions",
|
|
"elements": [
|
|
{
|
|
"type": "button",
|
|
"action_id": PLAN_DECISION_APPROVE_ACTION,
|
|
"text": {"type": "plain_text", "text": "Approve"},
|
|
"style": "primary",
|
|
"value": f"approve:{question_id}",
|
|
},
|
|
{
|
|
"type": "button",
|
|
"action_id": PLAN_DECISION_REQUEST_CHANGES_ACTION,
|
|
"text": {"type": "plain_text", "text": "Request changes"},
|
|
"value": f"request_changes:{question_id}",
|
|
},
|
|
{
|
|
"type": "button",
|
|
"action_id": PLAN_DECISION_ABANDON_ACTION,
|
|
"text": {"type": "plain_text", "text": "Abandon"},
|
|
"style": "danger",
|
|
"value": f"abandon:{question_id}",
|
|
"confirm": {
|
|
"title": {"type": "plain_text", "text": "Abandon this task?"},
|
|
"text": {
|
|
"type": "mrkdwn",
|
|
"text": (
|
|
"This terminally FAILS the task. The plan is "
|
|
"discarded and the pipeline stops."
|
|
),
|
|
},
|
|
"confirm": {"type": "plain_text", "text": "Abandon"},
|
|
"deny": {"type": "plain_text", "text": "Keep"},
|
|
"style": "danger",
|
|
},
|
|
},
|
|
],
|
|
},
|
|
]
|
|
|
|
|
|
# Block / action ids for the request-changes modal input, so the inbound
|
|
# ``view_submission`` extraction can find the notes value deterministically.
|
|
REQUEST_CHANGES_MODAL_CALLBACK_ID = (
|
|
f"{PLAN_DECISION_ACTION_PREFIX}:request_changes_modal"
|
|
)
|
|
REQUEST_CHANGES_NOTES_BLOCK_ID = "plan_decision_notes_block"
|
|
REQUEST_CHANGES_NOTES_ACTION_ID = "plan_decision_notes_input"
|
|
|
|
|
|
def build_request_changes_modal(question_id: str) -> dict[str, Any]:
|
|
"""Build the "Request changes" notes modal (views.open view, B3).
|
|
|
|
One required multiline ``plain_text_input`` ("What should change?"). The
|
|
ledger ``question_id`` round-trips through ``private_metadata`` as
|
|
``"request_changes:<question_id>"`` so the eventual ``view_submission``
|
|
recovers it (mirroring the button-value encoding). On submit, the input text
|
|
becomes the ``request_changes`` notes via the kind-aware normalizer.
|
|
|
|
Returns a plain JSON-serializable view dict (no Slack SDK types) so the
|
|
caller passes it straight to ``client.views_open(trigger_id=..., view=...)``.
|
|
"""
|
|
return {
|
|
"type": "modal",
|
|
"callback_id": REQUEST_CHANGES_MODAL_CALLBACK_ID,
|
|
"private_metadata": f"request_changes:{question_id}",
|
|
"title": {"type": "plain_text", "text": "Request changes"},
|
|
"submit": {"type": "plain_text", "text": "Send"},
|
|
"close": {"type": "plain_text", "text": "Cancel"},
|
|
"blocks": [
|
|
{
|
|
"type": "input",
|
|
"block_id": REQUEST_CHANGES_NOTES_BLOCK_ID,
|
|
"label": {"type": "plain_text", "text": "What should change?"},
|
|
"element": {
|
|
"type": "plain_text_input",
|
|
"action_id": REQUEST_CHANGES_NOTES_ACTION_ID,
|
|
"multiline": True,
|
|
},
|
|
}
|
|
],
|
|
}
|
|
|
|
|
|
def _join_answer_actions(actions: Sequence[Mapping[str, Any]]) -> Any:
|
|
"""Reduce one-or-more interactive actions to a single answer value.
|
|
|
|
A button click yields one action; a multi-select yields several. A single
|
|
action collapses to its scalar value; multiple actions return the ordered
|
|
list of values so the responder records every selection.
|
|
"""
|
|
values = [_action_value(action) for action in actions]
|
|
if len(values) == 1:
|
|
return values[0]
|
|
return values
|
|
|
|
|
|
def _action_value(action: Mapping[str, Any]) -> Any:
|
|
"""Extract the answer value from one Slack ``block_actions`` action."""
|
|
if "value" in action and action["value"] is not None:
|
|
return action["value"]
|
|
selected = action.get("selected_option")
|
|
if isinstance(selected, Mapping):
|
|
return selected.get("value")
|
|
selected_options = action.get("selected_options")
|
|
if isinstance(selected_options, Sequence) and not isinstance(
|
|
selected_options, (str, bytes)
|
|
):
|
|
return [
|
|
opt.get("value") for opt in selected_options if isinstance(opt, Mapping)
|
|
]
|
|
selected_user = action.get("selected_user")
|
|
if selected_user is not None:
|
|
return selected_user
|
|
# Fall back to the action_id so a payload without an explicit value still
|
|
# maps to *some* deterministic answer rather than ``None``.
|
|
return action.get("action_id")
|
|
|
|
|
|
class SlackTransport(Transport):
|
|
"""Concrete Slack Block Kit :class:`Transport` (§3.3.1, P1 — Slack first).
|
|
|
|
``channel`` is the target Slack channel id. ``poster`` is the injected
|
|
network seam (defaults to a non-networking poster that raises, so the
|
|
foundation ships nothing live). ``thread_ts`` mode is implicit: when a
|
|
``QuestionSet`` is delivered the adapter posts a top-level message and uses
|
|
its ``ts`` as the ``channel_ref``; answers arrive as thread replies or
|
|
interactive callbacks carrying the embedded ``question_id``.
|
|
"""
|
|
|
|
def __init__(
|
|
self,
|
|
channel: str,
|
|
poster: SlackPoster | None = None,
|
|
) -> None:
|
|
self.channel = channel
|
|
self._poster: SlackPoster = poster if poster is not None else _default_poster
|
|
|
|
@property
|
|
def poster(self) -> SlackPoster:
|
|
"""The injected network seam (the ``chat.postMessage`` callable).
|
|
|
|
Exposed read-only so collaborators sharing this transport (e.g. the
|
|
inbound :class:`~agent_team.transport.slack_listener.SlackListener`) can
|
|
post auxiliary messages — the root "📥 Task received" ack and the 👍
|
|
reaction-bearing posts — through the SAME poster the question delivery
|
|
uses, instead of constructing a second client. The foundation default
|
|
still refuses the network (no poster configured).
|
|
"""
|
|
return self._poster
|
|
|
|
def post_question(
|
|
self,
|
|
*,
|
|
thread_id: str,
|
|
question_id: str,
|
|
turn: int,
|
|
question_set: QuestionSet,
|
|
deadline: str,
|
|
thread_ts: str | None = None,
|
|
) -> str:
|
|
"""Render + post the question-set; return the Slack ``ts`` channel_ref.
|
|
|
|
Embeds ``question_id`` in the message ``callback_id`` so an inbound
|
|
answer maps back (§3.3.1). On any poster failure raises
|
|
:class:`SlackPostError` so the ledger row stays ``open`` for reconcile.
|
|
|
|
``thread_ts`` (one-thread-per-task) — when set, the message is posted as
|
|
a THREADED REPLY under that root ``ts`` (the task's "📥 Task received"
|
|
ack post), so every clarifier question for a task lands in one Slack
|
|
thread. When ``None`` (the default, e.g. a task that did not originate
|
|
from ``/new-task``) the message is posted top-level exactly as before.
|
|
The returned value is still the POSTED message's own ``ts``; the caller
|
|
(:func:`agent_team.responder.notify_question`) is what records the
|
|
durable ``channel_ref`` (it uses the root ``thread_ts`` when threading so
|
|
an inbound reply's ``thread_ts`` maps back to this question).
|
|
"""
|
|
# Plan-review gate (B3): when the question_set is a plan decision, render
|
|
# the three decision buttons (Approve / Request changes / Abandon) over
|
|
# the presentation text instead of the generic question blocks. The
|
|
# presentation body is passed through the question_set ``context`` (under
|
|
# ``presentation``) by the coordinator; the buttons carry the recoverable
|
|
# question_id (and the message metadata double-anchors it). A free-text
|
|
# thread reply remains an equal path to all three decisions.
|
|
if question_set.context.get("kind") == PLAN_DECISION_KIND:
|
|
body_text = str(question_set.context.get("presentation") or "")
|
|
blocks = build_plan_decision_blocks(question_id, body_text)
|
|
fallback_text = body_text or (
|
|
f"Plan decision needed on task {thread_id} (turn {turn})."
|
|
)
|
|
else:
|
|
blocks = build_question_blocks(question_set, deadline)
|
|
fallback_text = (
|
|
f"Agent-team needs input on task {thread_id} "
|
|
f"(turn {turn}); reply by {deadline}."
|
|
)
|
|
message: dict[str, Any] = {
|
|
"channel": self.channel,
|
|
"callback_id": build_callback_id(question_id),
|
|
"text": fallback_text,
|
|
"blocks": blocks,
|
|
"metadata": {
|
|
"event_type": "agent_team_question",
|
|
"event_payload": {
|
|
"thread_id": thread_id,
|
|
"question_id": question_id,
|
|
"turn": turn,
|
|
},
|
|
},
|
|
}
|
|
# Thread under the task's root message when one exists (one thread per
|
|
# task). Only set the key when non-empty so the top-level-post behavior
|
|
# is byte-identical for non-/new-task origins.
|
|
if thread_ts:
|
|
message["thread_ts"] = thread_ts
|
|
|
|
try:
|
|
response = self._poster(message)
|
|
except SlackPostError:
|
|
raise
|
|
except Exception as exc: # noqa: BLE001 — normalize any poster failure
|
|
raise SlackPostError(f"Slack post failed: {exc}") from exc
|
|
|
|
channel_ref = _extract_ts(response)
|
|
if not channel_ref:
|
|
raise SlackPostError(
|
|
"Slack post response missing message 'ts'; cannot record "
|
|
f"channel_ref (response keys: {sorted(response.keys())})"
|
|
)
|
|
return channel_ref
|
|
|
|
def parse_answer(self, raw: Any) -> tuple[str, Any, str]:
|
|
"""Normalize an inbound Slack payload to ``(question_id, answer, via)``.
|
|
|
|
Handles the two inbound shapes for P1:
|
|
|
|
* an interactive ``block_actions`` payload — ``callback_id`` carries the
|
|
``question_id`` and ``actions[*]`` carry the answer value(s);
|
|
* a plain text / slash reply — ``callback_id`` (or ``question_id``)
|
|
carries the id and ``text`` / ``answer`` carries the value.
|
|
|
|
Raises :class:`ValueError` on a payload with no recoverable
|
|
``question_id`` so a malformed answer is rejected loudly rather than
|
|
mis-attributed.
|
|
"""
|
|
if not isinstance(raw, Mapping):
|
|
raise ValueError(f"Slack payload must be a mapping, got {type(raw)!r}")
|
|
|
|
question_id = _extract_question_id(raw)
|
|
answer = _extract_answer(raw)
|
|
normalized = NormalizedAnswer(
|
|
question_id=question_id, answer=answer, via=VIA_SLACK
|
|
)
|
|
return normalized.question_id, normalized.answer, normalized.via
|
|
|
|
|
|
def _extract_ts(response: Mapping[str, Any]) -> str | None:
|
|
"""Pull the message ``ts`` from a ``chat.postMessage`` response.
|
|
|
|
Slack returns the timestamp at the top level (``{"ts": ...}``) and also
|
|
nested under ``message`` (``{"message": {"ts": ...}}``); accept either.
|
|
"""
|
|
ts = response.get("ts")
|
|
if ts:
|
|
return str(ts)
|
|
message = response.get("message")
|
|
if isinstance(message, Mapping) and message.get("ts"):
|
|
return str(message["ts"])
|
|
return None
|
|
|
|
|
|
def _extract_question_id(raw: Mapping[str, Any]) -> str:
|
|
"""Recover the ledger ``question_id`` from any supported inbound payload."""
|
|
callback_id = raw.get("callback_id")
|
|
if callback_id:
|
|
return parse_callback_id(str(callback_id))
|
|
|
|
# Interactive payloads nest the callback metadata under ``view`` / ``message``.
|
|
view = raw.get("view")
|
|
if isinstance(view, Mapping):
|
|
# Modal (view_submission) round-trips the question_id through
|
|
# ``private_metadata`` (B3 request-changes modal). It carries
|
|
# ``"<verb>:<question_id>"`` (or a bare id); recover the id suffix. This
|
|
# is checked BEFORE the view ``callback_id`` because the B3 modal's
|
|
# callback_id is a modal identifier (``plan_decision:...``), NOT a
|
|
# ``shq:<question_id>`` carrier.
|
|
private_metadata = view.get("private_metadata")
|
|
if private_metadata:
|
|
return _question_id_from_value(str(private_metadata))
|
|
# A view whose callback_id IS an ``shq:`` carrier (a non-B3 modal that
|
|
# embedded the question id there directly) still resolves.
|
|
view_callback_id = view.get("callback_id")
|
|
if view_callback_id and str(view_callback_id).startswith(
|
|
f"{CALLBACK_ID_PREFIX}:"
|
|
):
|
|
return parse_callback_id(str(view_callback_id))
|
|
message = raw.get("message")
|
|
if isinstance(message, Mapping):
|
|
metadata = message.get("metadata")
|
|
if isinstance(metadata, Mapping):
|
|
payload = metadata.get("event_payload")
|
|
if isinstance(payload, Mapping) and payload.get("question_id"):
|
|
return str(payload["question_id"])
|
|
|
|
# Block-action button value: the B3 plan-gate buttons encode
|
|
# ``"<verb>:<question_id>"`` so the id is recoverable even with no
|
|
# callback_id / message metadata on the payload.
|
|
actions = raw.get("actions")
|
|
if (
|
|
isinstance(actions, Sequence)
|
|
and not isinstance(actions, (str, bytes))
|
|
and actions
|
|
):
|
|
for action in actions:
|
|
if not isinstance(action, Mapping):
|
|
continue
|
|
value = action.get("value")
|
|
if not value:
|
|
continue
|
|
qid = _question_id_from_plan_decision_value(str(value))
|
|
if qid:
|
|
return qid
|
|
|
|
question_id = raw.get("question_id")
|
|
if question_id:
|
|
return str(question_id)
|
|
|
|
raise ValueError("Slack payload carries no recoverable question_id")
|
|
|
|
|
|
_PLAN_DECISION_VALUE_VERBS = frozenset({"approve", "request_changes", "abandon"})
|
|
|
|
|
|
def _question_id_from_value(value: str) -> str:
|
|
"""Recover the question_id from a ``private_metadata`` string.
|
|
|
|
The B3 request-changes modal stores ``"<verb>:<question_id>"`` (or a bare
|
|
``question_id``) in ``private_metadata``. A leading known decision verb is a
|
|
prefix to strip; otherwise the whole value IS the id. Raises
|
|
:class:`ValueError` on an empty value.
|
|
"""
|
|
qid = _question_id_from_plan_decision_value(value)
|
|
if qid:
|
|
return qid
|
|
if not value:
|
|
raise ValueError("empty private_metadata; no recoverable question_id")
|
|
return value
|
|
|
|
|
|
def _question_id_from_plan_decision_value(value: str) -> str | None:
|
|
"""Return the ``question_id`` suffix of a ``"<verb>:<question_id>"`` value.
|
|
|
|
Only matches when the prefix is a known plan-decision verb so an ordinary
|
|
button value (e.g. a clarifier's free-text answer) is never mis-parsed.
|
|
Returns ``None`` if the value is not a ``"<verb>:<question_id>"`` encoding.
|
|
"""
|
|
verb, sep, rest = value.partition(":")
|
|
if sep and verb in _PLAN_DECISION_VALUE_VERBS and rest:
|
|
return rest
|
|
return None
|
|
|
|
|
|
def _modal_input_text(view: Mapping[str, Any]) -> Any:
|
|
"""Recover the submitted text from a ``view_submission`` view (B3 modal).
|
|
|
|
Walks ``view.state.values`` (``{block_id: {action_id: {value: ...}}}``) and
|
|
returns the first non-empty ``plain_text_input`` value. The B3 request-
|
|
changes modal has a single input, so the first value is the notes text.
|
|
Returns ``None`` if no input value is present.
|
|
"""
|
|
state = view.get("state")
|
|
if not isinstance(state, Mapping):
|
|
return None
|
|
values = state.get("values")
|
|
if not isinstance(values, Mapping):
|
|
return None
|
|
for block in values.values():
|
|
if not isinstance(block, Mapping):
|
|
continue
|
|
for action in block.values():
|
|
if isinstance(action, Mapping) and action.get("value") is not None:
|
|
return action["value"]
|
|
return None
|
|
|
|
|
|
def _extract_answer(raw: Mapping[str, Any]) -> Any:
|
|
"""Recover the answer value from any supported inbound payload."""
|
|
# view_submission (modal): the answer is the submitted input text (B3).
|
|
view = raw.get("view")
|
|
if isinstance(view, Mapping):
|
|
text = _modal_input_text(view)
|
|
if text is not None:
|
|
return text
|
|
|
|
actions = raw.get("actions")
|
|
if (
|
|
isinstance(actions, Sequence)
|
|
and not isinstance(actions, (str, bytes))
|
|
and actions
|
|
):
|
|
mappings = [action for action in actions if isinstance(action, Mapping)]
|
|
# A single plan-decision button encodes ``"<verb>:<question_id>"``; the
|
|
# question_id is recovered separately (callback_id / metadata / value),
|
|
# so the ANSWER is the bare verb. Stripping the suffix here lets the
|
|
# kind-aware normalizer match it against the approve/abandon allowlists.
|
|
if len(mappings) == 1:
|
|
value = mappings[0].get("value")
|
|
if value is not None:
|
|
verb, sep, rest = str(value).partition(":")
|
|
if sep and verb in _PLAN_DECISION_VALUE_VERBS and rest:
|
|
return verb
|
|
return _join_answer_actions(mappings)
|
|
|
|
if "answer" in raw:
|
|
return raw["answer"]
|
|
if "text" in raw:
|
|
return raw["text"]
|
|
if "value" in raw:
|
|
return raw["value"]
|
|
|
|
raise ValueError("Slack payload carries no recoverable answer")
|