@clawpump/claw-agent 0.1.5 → 0.1.6

package/agent/gateway/relay/adapter.py

@@ -0,0 +1,222 @@
+"""RelayAdapter — one generic gateway adapter fronted by the connector. EXPERIMENTAL.
+
+A single ``BasePlatformAdapter`` subclass that, at handshake, receives a
+``CapabilityDescriptor`` from the connector telling it which platform it is
+fronting and which capabilities to advertise to the ``GatewayStreamConsumer``.
+It implements the four abstract methods (``connect`` / ``disconnect`` / ``send``
+/ ``get_chat_info``) plus the capability surface (``MAX_MESSAGE_LENGTH``,
+``message_len_fn``, ``supports_draft_streaming``) by delegating wire I/O to an
+injected transport and reading capabilities off the descriptor.
+
+There is NO per-platform gateway code: the connector is the only side that knows
+"this chat_id maps to a Discord channel, send it via the Discord websocket."
+The gateway sees an ordinary ``MessageEvent`` in and calls ``adapter.send`` out.
+
+EXPERIMENTAL: the transport protocol and descriptor schema may change without a
+deprecation cycle until >=2 Class-1 platforms validate them.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Callable, Dict, Optional
+
+from gateway.config import Platform, PlatformConfig
+from gateway.platforms.base import BasePlatformAdapter, SendResult
+from gateway.relay.descriptor import CapabilityDescriptor
+from gateway.relay.transport import RelayTransport
+
+logger = logging.getLogger(__name__)
+
+
+def _utf16_len(text: str) -> int:
+    """Count UTF-16 code units (Telegram's length unit)."""
+    return len(text.encode("utf-16-le")) // 2
+
+
+# Table-driven length-unit selection from the descriptor's ``len_unit``.
+_LEN_FNS: Dict[str, Callable[[str], int]] = {
+    "chars": len,
+    "utf16": _utf16_len,
+}
+
+
+class RelayAdapter(BasePlatformAdapter):
+    """Generic relay adapter advertising a connector-negotiated capability profile."""
+
+    def __init__(
+        self,
+        config: PlatformConfig,
+        descriptor: CapabilityDescriptor,
+        transport: Optional[RelayTransport] = None,
+    ) -> None:
+        # The relay adapter fronts many platforms but presents as a single
+        # logical platform to the runner; Platform.RELAY identifies it.
+        super().__init__(config, Platform.RELAY)
+        self.descriptor = descriptor
+        self._transport = transport
+        # Capability surface read by stream_consumer (getattr(..., 4096)).
+        self.MAX_MESSAGE_LENGTH = descriptor.max_message_length
+        # chat_id -> guild_id (Discord) / workspace scope, learned from inbound
+        # events. The connector's egress guard resolves the owning tenant from
+        # the OUTBOUND action's metadata.guild_id; the gateway's generic delivery
+        # path (run.py _thread_metadata_for_source) only carries thread_id, so we
+        # re-attach the scope here from what we saw inbound. Keyed by chat_id
+        # (channel) since that's what send() receives. See routedEgressGuard.ts.
+        self._scope_by_chat: Dict[str, str] = {}
+        self.supports_code_blocks = descriptor.markdown_dialect not in ("", "plain")
+
+    # ── capability surface (from descriptor) ─────────────────────────────
+    @property
+    def message_len_fn(self) -> Callable[[str], int]:
+        return _LEN_FNS.get(self.descriptor.len_unit, len)
+
+    def supports_draft_streaming(
+        self,
+        chat_type: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> bool:
+        return self.descriptor.supports_draft_streaming
+
+    # ── abstract methods (delegated to the transport) ────────────────────
+    async def connect(self) -> bool:
+        if self._transport is None:
+            raise RuntimeError("RelayAdapter has no transport configured")
+        self._transport.set_inbound_handler(self._on_inbound)
+        # Inbound interrupts (connector -> owning gateway) arrive as
+        # interrupt_inbound frames over the SAME outbound WS; bridge them to the
+        # adapter's interrupt path. WS-only: there is no inbound HTTP receiver.
+        set_interrupt = getattr(self._transport, "set_interrupt_inbound_handler", None)
+        if callable(set_interrupt):
+            set_interrupt(self.on_interrupt)
+        ok = await self._transport.connect()
+        if not ok:
+            return False
+        # Negotiate the real capability descriptor from the connector and adopt
+        # it — the placeholder passed at construction is replaced by what the
+        # connector advertises for the platform this gateway actually fronts.
+        try:
+            descriptor = await self._transport.handshake()
+        except Exception as exc:  # noqa: BLE001 - a failed handshake = a failed connect
+            logger.warning("relay handshake failed: %s", exc)
+            return False
+        self._apply_descriptor(descriptor)
+        # Inbound (messages + interrupts) is delivered over the outbound WS via
+        # the connector's relay bus — there is NO inbound HTTP endpoint (hosted
+        # gateways have no public IP). The transport's reader already dispatches
+        # `inbound` / `interrupt_inbound` frames to the handlers wired above.
+        return True
+
+    def _apply_descriptor(self, descriptor: CapabilityDescriptor) -> None:
+        """Adopt a (re)negotiated descriptor into the live capability surface."""
+        self.descriptor = descriptor
+        self.MAX_MESSAGE_LENGTH = descriptor.max_message_length
+        self.supports_code_blocks = descriptor.markdown_dialect not in ("", "plain")
+
+    async def _on_inbound(self, event) -> None:
+        """Bridge a connector-delivered MessageEvent into the normal adapter path."""
+        self._capture_scope(event)
+        await self.handle_message(event)
+
+    def _capture_scope(self, event) -> None:
+        """Remember chat_id -> guild scope from an inbound event so our outbound
+        (the agent's reply) can re-assert it for the connector's egress tenant
+        resolution. Never raises — scope tracking must not break inbound."""
+        try:
+            src = getattr(event, "source", None)
+            scope = getattr(src, "guild_id", None) if src else None
+            chat = getattr(src, "chat_id", None) if src else None
+            if scope and chat:
+                self._scope_by_chat[str(chat)] = str(scope)
+        except Exception:  # noqa: BLE001 - scope tracking must never break inbound
+            pass
+
+    def _with_scope(self, chat_id: str, metadata: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+        """Ensure the outbound metadata carries guild_id for the connector's
+        egress tenant resolution. The connector resolves the owning tenant from
+        metadata.guild_id (Discord); without it egress is declined as
+        'target not routed to an onboarded tenant'. No-op when we have no scope
+        for this chat (e.g. DMs) or it's already present."""
+        meta: Dict[str, Any] = dict(metadata or {})
+        if not meta.get("guild_id"):
+            scope = self._scope_by_chat.get(str(chat_id))
+            if scope:
+                meta["guild_id"] = scope
+        return meta
+
+    async def on_interrupt(self, session_key: str, chat_id: str) -> None:
+        """Bridge a connector-delivered /stop into the adapter's interrupt path.
+
+        The connector forwards a mid-turn interrupt down the socket owned by
+        the gateway instance running ``session_key``; this routes it to the
+        existing per-session interrupt mechanism (sets the
+        ``_active_sessions[session_key]`` Event and clears typing), cancelling
+        the right turn without touching sibling sessions.
+        """
+        await self.interrupt_session_activity(session_key, chat_id)
+
+    async def disconnect(self) -> None:
+        if self._transport is not None:
+            await self._transport.disconnect()
+
+    async def send(
+        self,
+        chat_id: str,
+        content: str,
+        reply_to: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> SendResult:
+        if self._transport is None:
+            return SendResult(success=False, error="no transport")
+        result = await self._transport.send_outbound(
+            {
+                "op": "send",
+                "chat_id": chat_id,
+                "content": content,
+                "reply_to": reply_to,
+                "metadata": self._with_scope(chat_id, metadata),
+            }
+        )
+        return SendResult(
+            success=bool(result.get("success")),
+            message_id=result.get("message_id"),
+            error=result.get("error"),
+        )
+
+    async def get_chat_info(self, chat_id: str) -> Dict[str, Any]:
+        # Proxied to the connector (it owns the platform connection / cache).
+        if self._transport is None:
+            return {"name": chat_id, "type": "dm"}
+        return await self._transport.get_chat_info(chat_id)
+
+    async def send_follow_up(
+        self,
+        session_key: str,
+        kind: str,
+        content: str,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> SendResult:
+        """Send via a shared-identity capability bound to a session (A2 outbound).
+
+        The gateway never holds the credential: it names the session it is
+        already in plus the capability ``kind``, and the connector resolves the
+        real value from its vault and egresses (enforcing the tenant match). Used
+        e.g. to post a Discord interaction follow-up as the shared bot without
+        the token ever reaching the gateway. See RelayTransport.send_follow_up.
+        """
+        if self._transport is None:
+            return SendResult(success=False, error="no transport")
+        result = await self._transport.send_follow_up(
+            {
+                "op": "follow_up",
+                "session_key": session_key,
+                "kind": kind,
+                "content": content,
+                "metadata": metadata or {},
+            }
+        )
+        return SendResult(
+            success=bool(result.get("success")),
+            message_id=result.get("message_id"),
+            error=result.get("error"),
+        )

package/agent/gateway/relay/auth.py

@@ -0,0 +1,168 @@
+"""Gateway-side relay authentication primitives. EXPERIMENTAL.
+
+The connector⇄gateway channel is authenticated because a gateway may be
+customer-managed and internet-exposed (see the connector repo
+``docs/connector-gateway-auth-design.md``). This module is the **gateway half**
+of two HMAC schemes whose wire bytes must match the connector's TypeScript
+exactly:
+
+1. **WS upgrade auth** (gateway → connector): the gateway presents
+   ``Authorization: Bearer <token>`` on the ``/relay`` WebSocket upgrade, where
+   ``token = make_upgrade_token(gateway_id, secret)``. Mirrors the connector's
+   ``relayAuthToken.ts`` ``makeToken`` (``src/core/relayAuthToken.ts``):
+   ``base64url(f"{payload}:{exp}:{sig}")`` with
+   ``sig = HMAC_SHA256(f"{payload}:{exp}", secret).hexdigest()`` and
+   ``payload == gateway_id``.
+
+2. **Inbound delivery signature** (connector → gateway): the connector signs
+   each inbound POST with the per-tenant *delivery key*, carried as
+   ``x-relay-timestamp`` + ``x-relay-signature`` headers; the gateway verifies
+   before accepting the event. Mirrors the connector's ``deliverySigning.ts``:
+   ``sig = HMAC_SHA256(f"{ts}.{body_json}", key).hexdigest()`` over the EXACT
+   request body bytes, with a replay-window skew check.
+
+Both schemes use a **multi-secret verify list** (primary first, then a secondary
+during a rotation window), exactly like ``api/src/handlers/stats_oauth.ts`` — so
+a secret rotation doesn't invalidate outstanding tokens.
+
+EXPERIMENTAL: may change without a deprecation cycle until ≥2 Class-1 platforms
+validate the relay contract.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import time
+from typing import Optional, Sequence
+
+# Header names the connector uses for inbound delivery signatures
+# (connector ``src/core/deliverySigning.ts`` — DELIVERY_TS_HEADER / SIG_HEADER).
+DELIVERY_TS_HEADER = "x-relay-timestamp"
+DELIVERY_SIG_HEADER = "x-relay-signature"
+
+# Default replay window for an inbound delivery signature (connector default).
+_DEFAULT_MAX_SKEW_SECONDS = 300
+# Default TTL for an upgrade token (connector ``makeUpgradeToken`` default).
+_DEFAULT_UPGRADE_TTL_SECONDS = 300
+
+
+def _hmac_hex(payload: str, secret: str) -> str:
+    """HMAC-SHA256 hex digest of ``payload`` under ``secret`` (UTF-8)."""
+    return hmac.new(secret.encode("utf-8"), payload.encode("utf-8"), hashlib.sha256).hexdigest()
+
+
+def sign(payload: str, secret: str) -> str:
+    """HMAC-SHA256 hex digest — the connector's ``sign`` (relayAuthToken.ts)."""
+    return _hmac_hex(payload, secret)
+
+
+def verify_signature(payload: str, sig_hex: str, secrets: Sequence[str]) -> bool:
+    """Constant-time check that ``sig_hex`` is a valid HMAC of ``payload`` under
+    ANY of ``secrets`` (rotation window). Length-mismatched candidates are
+    skipped without a timing leak. Mirrors ``verifySignature``.
+    """
+    try:
+        sig_buf = bytes.fromhex(sig_hex)
+    except (ValueError, TypeError):
+        return False
+    if len(sig_buf) == 0:
+        return False
+    for secret in secrets:
+        if not secret:
+            continue
+        expected = bytes.fromhex(_hmac_hex(payload, secret))
+        if len(expected) != len(sig_buf):
+            continue
+        if hmac.compare_digest(sig_buf, expected):
+            return True
+    return False
+
+
+def make_token(payload: str, secret: str, ttl_seconds: int = 0) -> str:
+    """Build a signed, optionally-expiring token — the connector's ``makeToken``.
+
+    ``base64url(f"{payload}:{exp}:{sig}")`` where ``exp`` is a unix-seconds
+    expiry (0 = never) and ``sig = HMAC_SHA256(f"{payload}:{exp}", secret)``.
+    base64url is unpadded to match Node's ``Buffer.toString("base64url")``.
+    """
+    exp = int(time.time()) + ttl_seconds if ttl_seconds > 0 else 0
+    signed = f"{payload}:{exp}"
+    sig = _hmac_hex(signed, secret)
+    raw = f"{signed}:{sig}".encode("utf-8")
+    return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")
+
+
+def make_upgrade_token(
+    gateway_id: str, secret: str, ttl_seconds: int = _DEFAULT_UPGRADE_TTL_SECONDS
+) -> str:
+    """The WS-upgrade bearer token a gateway sends: ``payload = gateway_id``.
+
+    The connector peeks ``gateway_id`` (the payload head) to index its secret
+    verify list, then verifies the signature against that gateway's stored
+    secret(s). Mirrors the connector's ``makeUpgradeToken``.
+    """
+    return make_token(gateway_id, secret, ttl_seconds)
+
+
+def verify_token(token: str, secrets: Sequence[str]) -> Optional[str]:
+    """Verify a token built by ``make_token``; return the payload or None.
+
+    Splits from the right so a payload may itself contain colons (mirrors the
+    connector's ``verifyToken``). Rejects an expired token and any signature
+    that doesn't match a secret in the verify list.
+    """
+    try:
+        # base64url decode with padding restored.
+        padded = token + "=" * (-len(token) % 4)
+        decoded = base64.urlsafe_b64decode(padded.encode("ascii")).decode("utf-8")
+    except (ValueError, TypeError):
+        return None
+    parts = decoded.split(":")
+    if len(parts) < 3:
+        return None
+    sig = parts[-1]
+    try:
+        exp = int(parts[-2])
+    except ValueError:
+        return None
+    payload = ":".join(parts[:-2])
+    if exp != 0 and int(time.time()) > exp:
+        return None
+    signed = f"{payload}:{exp}"
+    return payload if verify_signature(signed, sig, secrets) else None
+
+
+def _delivery_payload(ts: int, body_json: str) -> str:
+    """Signed material for an inbound delivery: ``f"{ts}.{body_json}"``."""
+    return f"{ts}.{body_json}"
+
+
+def verify_delivery_signature(
+    body_json: str,
+    timestamp: Optional[str],
+    signature: Optional[str],
+    verify_keys: Sequence[str],
+    max_skew_seconds: int = _DEFAULT_MAX_SKEW_SECONDS,
+    *,
+    now: Optional[int] = None,
+) -> bool:
+    """Verify a connector→gateway inbound delivery signature.
+
+    ``body_json`` MUST be the exact request body bytes decoded as UTF-8 — the
+    connector signs over the literal serialized body, so the gateway verifies
+    over the literal received body (no re-serialization). Checks the timestamp
+    is within ``max_skew_seconds`` of now and the HMAC matches any key in the
+    rotation verify list. Mirrors the connector's ``verifyDeliverySignature``.
+    """
+    if not timestamp or not signature:
+        return False
+    try:
+        ts = int(timestamp)
+    except (ValueError, TypeError):
+        return False
+    current = now if now is not None else int(time.time())
+    if abs(current - ts) > max_skew_seconds:
+        return False
+    return verify_signature(_delivery_payload(ts, body_json), signature, verify_keys)

package/agent/gateway/relay/descriptor.py

@@ -0,0 +1,118 @@
+"""CapabilityDescriptor — the relay handshake payload. EXPERIMENTAL.
+
+The connector hands a ``CapabilityDescriptor`` to the gateway's ``RelayAdapter``
+at handshake time; it tells the adapter which platform it is fronting and which
+capabilities to advertise to the ``GatewayStreamConsumer`` (char limit,
+draft-streaming, edit/threading support, markdown dialect, length unit). It is
+the linchpin of the generalization: one gateway adapter serves Discord,
+Telegram, Matrix, Signal, ... without per-platform branching.
+
+EXPERIMENTAL: this schema MAY CHANGE without a deprecation cycle until at least
+two real Class-1 platforms have validated it. Evolution during the experimental
+phase is additive-only, gated by ``contract_version`` (see
+docs/relay-connector-contract.md).
+
+Field origins (most are a wire-serializable projection of ``PlatformEntry`` plus
+the per-instance capability methods on ``BasePlatformAdapter``):
+
+- ``max_message_length`` -> ``PlatformEntry.max_message_length`` / adapter
+  ``MAX_MESSAGE_LENGTH`` attribute (read by stream_consumer).
+- ``len_unit``           -> selects which ``message_len_fn`` the adapter installs
+  ("chars" = builtin len; "utf16" = Telegram-style UTF-16 code-unit counting).
+- ``supports_draft_streaming`` -> adapter ``supports_draft_streaming()`` probe.
+- ``supports_edit``      -> whether edit-based streaming is possible (Discord/
+  Telegram yes; Signal/SMS no -> consumer degrades to one-message-per-segment).
+- ``supports_threads``   -> ``create_handoff_thread`` capability flag.
+- ``markdown_dialect``   -> presentation hint (e.g. "markdown_v2", "discord").
+- ``emoji`` / ``platform_hint`` / ``pii_safe`` -> ``PlatformEntry`` fields of the
+  same name.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass
+
+# Bump additively (never reinterpret an existing field) during the experimental
+# phase; a breaking change requires updating both repos in lockstep.
+CONTRACT_VERSION = 1
+
+
+@dataclass(frozen=True)
+class CapabilityDescriptor:
+    """Immutable capability descriptor negotiated at relay handshake.
+
+    Frozen so a descriptor cannot be mutated after handshake — the adapter
+    advertises a fixed capability profile for the life of the connection.
+    """
+
+    contract_version: int
+    platform: str
+    label: str
+    max_message_length: int
+    supports_draft_streaming: bool
+    supports_edit: bool
+    supports_threads: bool
+    markdown_dialect: str
+    len_unit: str  # "chars" | "utf16"
+    emoji: str = "\U0001f50c"  # 🔌 default (matches PlatformEntry default)
+    platform_hint: str = ""
+    pii_safe: bool = False
+
+    def to_json(self) -> str:
+        """Serialize to a compact, stable JSON string for the handshake frame."""
+        return json.dumps(asdict(self), sort_keys=True, ensure_ascii=False)
+
+    @classmethod
+    def from_json(cls, data: str) -> "CapabilityDescriptor":
+        """Deserialize from a handshake JSON string.
+
+        Unknown keys are ignored (forward-compat: a newer connector may send
+        fields this gateway does not know yet); missing optional keys fall back
+        to dataclass defaults.
+        """
+        raw = json.loads(data)
+        known = {f for f in cls.__dataclass_fields__}  # type: ignore[attr-defined]
+        filtered = {k: v for k, v in raw.items() if k in known}
+        return cls(**filtered)
+
+    @classmethod
+    def from_platform_entry(
+        cls,
+        entry,
+        *,
+        len_unit: str = "chars",
+        supports_draft_streaming: bool = False,
+        supports_edit: bool = True,
+        supports_threads: bool = False,
+        markdown_dialect: str = "plain",
+    ) -> "CapabilityDescriptor":
+        """Project a ``gateway.platform_registry.PlatformEntry`` into a descriptor.
+
+        Demonstrates the descriptor is a *subset/projection* of what
+        ``PlatformEntry`` already encodes, not a parallel concept: ``label``,
+        ``max_message_length``, ``emoji``, ``platform_hint``, ``pii_safe`` and
+        the platform name come straight off the entry. The runtime capability
+        bits that ``PlatformEntry`` does NOT encode (length unit, draft/edit/
+        thread/markdown behavior) are supplied by the caller — in production
+        the connector fills these from the live adapter's capability methods.
+
+        ``max_message_length`` of 0 on a ``PlatformEntry`` means "no limit";
+        we map that to the stream_consumer default of 4096 so the descriptor
+        always carries a concrete chunking bound.
+        """
+        max_len = getattr(entry, "max_message_length", 0) or 4096
+        return cls(
+            contract_version=CONTRACT_VERSION,
+            platform=entry.name,
+            label=entry.label,
+            max_message_length=max_len,
+            supports_draft_streaming=supports_draft_streaming,
+            supports_edit=supports_edit,
+            supports_threads=supports_threads,
+            markdown_dialect=markdown_dialect,
+            len_unit=len_unit,
+            emoji=getattr(entry, "emoji", "\U0001f50c"),
+            platform_hint=getattr(entry, "platform_hint", ""),
+            pii_safe=getattr(entry, "pii_safe", False),
+        )

package/agent/gateway/relay/transport.py

@@ -0,0 +1,101 @@
+"""Relay transport protocol — the gateway<->connector wire contract. EXPERIMENTAL.
+
+The ``RelayAdapter`` (gateway side) delegates all wire I/O to a ``RelayTransport``.
+The gateway dials OUT to the connector, so a production transport is a WebSocket
+client; in tests it is an in-memory stub (``tests/gateway/relay/stub_connector.py``).
+
+This module defines the protocol surface only — no concrete transport. The
+contract has four concerns:
+
+  1. Lifecycle: ``connect`` / ``disconnect``.
+  2. Handshake: ``handshake`` returns the ``CapabilityDescriptor`` the connector
+     advertises for the platform this adapter fronts.
+  3. Inbound: ``set_inbound_handler`` registers a callback the transport invokes
+     with each normalized ``MessageEvent`` the connector delivers.
+  4. Outbound: ``send_outbound`` carries send/edit/typing actions back to the
+     connector; ``get_chat_info`` proxies a chat-info lookup; ``send_interrupt``
+     routes a mid-turn /stop down the socket that owns the session_key.
+
+EXPERIMENTAL: may change without a deprecation cycle until >=2 Class-1 platforms
+validate it. See docs/relay-connector-contract.md.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Awaitable, Callable, Dict, Optional, Protocol, runtime_checkable
+
+from gateway.platforms.base import MessageEvent
+from gateway.relay.descriptor import CapabilityDescriptor
+
+# Callback the transport invokes for each inbound normalized event.
+InboundHandler = Callable[[MessageEvent], Awaitable[None]]
+
+
+@runtime_checkable
+class RelayTransport(Protocol):
+    """Full gateway<->connector transport contract."""
+
+    async def connect(self) -> bool:
+        """Open the connection to the connector; return True on success."""
+        ...
+
+    async def disconnect(self) -> None:
+        """Close the connection."""
+        ...
+
+    async def handshake(self) -> CapabilityDescriptor:
+        """Return the capability descriptor the connector advertises."""
+        ...
+
+    def set_inbound_handler(self, handler: InboundHandler) -> None:
+        """Register the callback invoked with each inbound MessageEvent."""
+        ...
+
+    async def send_outbound(self, action: Dict[str, Any]) -> Dict[str, Any]:
+        """Carry an outbound action (send/edit/typing) to the connector.
+
+        Returns a result dict; for ``op == "send"`` it carries
+        ``success`` and optionally ``message_id`` / ``error``.
+        """
+        ...
+
+    async def get_chat_info(self, chat_id: str) -> Dict[str, Any]:
+        """Proxy a chat-info lookup to the connector."""
+        ...
+
+    async def send_interrupt(self, session_key: str, reason: Optional[str] = None) -> None:
+        """Route a mid-turn /stop to the connector for ``session_key``.
+
+        The connector forwards it down the socket owned by the gateway
+        instance running that session (the /stop routing invariant). On the
+        gateway side this is the OUTBOUND direction; the actual task
+        cancellation happens when the connector echoes an interrupt inbound
+        (handled in Task 1.4).
+        """
+        ...
+
+    async def send_follow_up(self, action: Dict[str, Any]) -> Dict[str, Any]:
+        """Act on a shared-identity capability bound to a session (A2 outbound).
+
+        Some platforms hand the connector a credential that acts on the SHARED
+        bot identity (e.g. a Discord interaction follow-up token, valid ~15min).
+        Under A2 that credential NEVER reaches the gateway — the connector
+        stripped it at the edge and bound it in its capability vault keyed by
+        the session. To use it, the gateway issues a SEMANTIC action against the
+        session it is already in; it never names or holds a token.
+
+        The action dict carries:
+          ``op``          == ``"follow_up"``
+          ``session_key`` the session whose bound capability to wield
+          ``kind``        the capability kind (e.g. ``"discord.interaction_token"``)
+          ``content``     the message content to send via that capability
+          ``metadata?``   optional extras
+
+        The connector resolves the real capability (``resolveOutboundCapability``
+        on its side), enforces the tenant match (tenant B can never wield tenant
+        A's capability), and egresses. Returns ``{success, message_id?, error?}``;
+        ``success`` is False when the capability is absent/expired or the tenant
+        doesn't match — the gateway then has nothing to retry with (by design: a
+        leaked gateway holds zero capability material).
+        """
+        ...