managed-deepagents 0.9.3.dev4__py3-none-win_amd64.whl → 0.10.0.dev2__py3-none-win_amd64.whl

managed_deepagents/__init__.py

@@ -15,6 +15,19 @@ primitive is not part of the public surface.
 
 from __future__ import annotations
 
+from managed_deepagents._channels.github_types import (
+    GitHubAppOptions,
+    GitHubChannelRuntime,
+    GitHubEvent,
+    GitHubEventCallback,
+    GitHubEventResult,
+    GitHubHandlers,
+    GitHubLabeledIssuePayload,
+    GitHubPayload,
+    GitHubPullRequestPayload,
+    GitHubWorkflowPayload,
+    SupportedEventKey,
+)
 from managed_deepagents._channels.http import (
     HttpChannel,
     HttpChannelInboundMessage,
@@ -23,6 +36,11 @@ from managed_deepagents._channels.http import (
     HttpChannelRequest,
     HttpPostedMessage,
 )
+from managed_deepagents._channels.run_input import (
+    ChannelRunInput,
+    ChannelRunOptions,
+    ChannelRunResult,
+)
 from managed_deepagents._channels.types import (
     ChannelContentMessage,
     ChannelEvent,
@@ -102,11 +120,24 @@ __all__ = [
     "ChannelInfo",
     "ChannelMessage",
     "ChannelNativeMessage",
+    "ChannelRunInput",
+    "ChannelRunOptions",
+    "ChannelRunResult",
     "ConnectionNotFoundError",
     "CredentialAuthorizationRequiredError",
     "CredentialStoreError",
     "DeepAgentDefinition",
     "GeneratedSkill",
+    "GitHubAppOptions",
+    "GitHubChannelRuntime",
+    "GitHubEvent",
+    "GitHubEventCallback",
+    "GitHubEventResult",
+    "GitHubHandlers",
+    "GitHubLabeledIssuePayload",
+    "GitHubPayload",
+    "GitHubPullRequestPayload",
+    "GitHubWorkflowPayload",
     "HttpChannel",
     "HttpChannelInboundMessage",
     "HttpChannelParseResult",
@@ -144,6 +175,7 @@ __all__ = [
     "SkillSelection",
     "SlackPromptResponse",
     "SseMcpServerConfig",
+    "SupportedEventKey",
     "auth",
     "basic",
     "bearer",

managed_deepagents/_agent_auth.py

@@ -185,11 +185,28 @@ class AgentAuth:
         return principal_id
 
     def find_workspace_connection(self, slug: str) -> WorkspaceConnection | None:
-        """List workspace connections and return the row for ``slug``, if any."""
+        """Look up the workspace connection row for ``slug``, if any."""
         if not (self.context.workspace_id or "").strip():
             raise CredentialStoreError(
                 "connections are not configured: LANGSMITH_WORKSPACE_ID is not set"
             )
+        status, body = self._request(
+            "GET",
+            f"/v1/agent-auth/connections?{urllib.parse.urlencode({'slug': slug})}",
+        )
+        if status >= _HTTP_BAD_REQUEST:
+            raise CredentialStoreError("Agent Auth list connections failed", status, body)
+        items = _connection_items(body)
+        for item in items:
+            if item.get("slug") == slug:
+                return _workspace_connection_row(item)
+        # Older Agent Auth ignores ``slug`` and returns the first page of all rows.
+        if items:
+            return self._page_workspace_connection(slug)
+        return None
+
+    def _page_workspace_connection(self, slug: str) -> WorkspaceConnection | None:
+        """Page through all workspace connections for the row matching ``slug``."""
         cursor: str | None = None
         for _ in range(AGENT_AUTH_MAX_PROVIDER_PAGES):
             query: dict[str, str] = {
@@ -203,25 +220,9 @@ class AgentAuth:
             )
             if status >= _HTTP_BAD_REQUEST:
                 raise CredentialStoreError("Agent Auth list connections failed", status, body)
-            raw_items = body.get("items")
-            items = raw_items if isinstance(raw_items, list) else []
-            for item in items:
-                if not isinstance(item, Mapping) or item.get("slug") != slug:
-                    continue
-                connection_id = (
-                    item.get("id") or item.get("connection_id") or item.get("credential_id")
-                )
-                kind = _connection_credential_kind(item)
-                owner_policy = item.get("owner_policy")
-                if not isinstance(connection_id, str) or not connection_id:
-                    raise CredentialStoreError("Agent Auth connection row missing id or kind")
-                if not isinstance(kind, str) or not kind:
-                    raise CredentialStoreError("Agent Auth connection row missing id or kind")
-                return WorkspaceConnection(
-                    connection_id=connection_id,
-                    kind=kind,
-                    owner_policy=str(owner_policy) if isinstance(owner_policy, str) else "",
-                )
+            for item in _connection_items(body):
+                if item.get("slug") == slug:
+                    return _workspace_connection_row(item)
             next_cursor = body.get("next_cursor")
             if not isinstance(next_cursor, str) or not next_cursor or next_cursor == cursor:
                 return None
@@ -493,6 +494,27 @@ def _path_segment(value: str) -> str:
     return urllib.parse.quote(value, safe="")
 
 
+def _connection_items(body: Mapping[str, object]) -> list[Mapping[str, object]]:
+    """Object rows of a connection list response."""
+    raw_items = body.get("items")
+    if not isinstance(raw_items, list):
+        return []
+    return [item for item in raw_items if isinstance(item, Mapping)]
+
+
+def _workspace_connection_row(item: Mapping[str, object]) -> WorkspaceConnection:
+    connection_id = item.get("id") or item.get("connection_id") or item.get("credential_id")
+    kind = _connection_credential_kind(item)
+    owner_policy = item.get("owner_policy")
+    if not isinstance(connection_id, str) or not connection_id or not kind:
+        raise CredentialStoreError("Agent Auth connection row missing id or kind")
+    return WorkspaceConnection(
+        connection_id=connection_id,
+        kind=kind,
+        owner_policy=owner_policy if isinstance(owner_policy, str) else "",
+    )
+
+
 def _connection_credential_kind(item: Mapping[str, object]) -> str:
     credential = item.get("credential")
     if isinstance(credential, Mapping):

managed_deepagents/_channels/github.py

@@ -0,0 +1,534 @@
+from __future__ import annotations
+
+import asyncio
+import copy
+import hmac
+import inspect
+import json
+import os
+import re
+import time
+from collections.abc import Mapping
+from dataclasses import asdict
+from importlib import import_module
+from typing import TYPE_CHECKING, Any, TypedDict, cast
+from urllib.parse import quote, urlencode, urlsplit
+
+import httpx
+from langgraph_sdk.schema import MultitaskStrategy
+
+from managed_deepagents._channels.github_connections import (
+    GITHUB_TOKEN_SLUG,
+    github_app_connection_slug,
+)
+from managed_deepagents._channels.github_events import github_event
+from managed_deepagents._channels.github_schema import (
+    SUPPORTED_EVENT_KEYS,
+    github_identifier_adapter,
+    github_receipt_adapter,
+)
+from managed_deepagents._channels.github_types import (
+    GitHubAppOptions,
+    GitHubChannelRuntime,
+    GitHubEvent,
+    GitHubEventCallback,
+    GitHubHandlers,
+    GitHubRepository,
+    GitHubSender,
+    SupportedEventKey,
+    _ChannelName,
+)
+from managed_deepagents._channels.http import HttpChannel, channel_thread_id, http_channel
+from managed_deepagents._channels.runtime import is_json_value
+from managed_deepagents._log import logger
+
+if TYPE_CHECKING:
+    from managed_deepagents._channels.http.types import (
+        HttpChannelInboundMessage,
+        HttpChannelParseResult,
+        HttpChannelRequest,
+        HttpChannelRunInfo,
+        JsonValue,
+    )
+    from managed_deepagents._channels.run_input import ChannelRunResult
+
+_MAX_SAFE_INTEGER = 9007199254740991
+
+
+def github_channel(
+    *,
+    on_event: GitHubHandlers | None = None,
+    app: GitHubAppOptions | None = None,
+    multitask_strategy: MultitaskStrategy = "enqueue",
+) -> HttpChannel:
+    """Options for ``channels.github(...)``: App scope and event handlers that start runs.
+
+    Runs for the same issue or pull request share one thread.
+
+    Args:
+        on_event: Event handlers that start runs. Return a prompt (string,
+            message, or state), or ``None`` to skip. While a thread waits on an
+            interrupt, events start nothing and the issue or pull request is
+            told to continue it in LangSmith Studio.
+        app: App ``mda deploy`` creates; permissions and repository allowlist.
+        multitask_strategy: What an event that starts a run does while its
+            conversation already runs: ``enqueue`` (the default) waits for the
+            run and starts after it, ``interrupt`` cancels the run, keeping its
+            progress, and starts at once, ``rollback`` cancels it and discards
+            its progress, and ``reject`` starts nothing. Events on a
+            conversation that waits on an interrupt start nothing either way.
+
+    Example::
+
+        channels.github(
+            on_event={
+                "issues.opened": lambda e, _: f"Help with #{e.payload['issue']['number']}",
+            },
+        )
+    """
+    handlers = cast("Mapping[SupportedEventKey, GitHubEventCallback]", dict(on_event or {}))
+    if set(handlers) - SUPPORTED_EVENT_KEYS:
+        raise ValueError("unsupported GitHub event key")
+    repositories = _repositories(app)
+    provider_config: dict[str, JsonValue] = {"events": _subscribed_events(handlers)}
+    if app is not None:
+        provider_config["app"] = _app_config(app)
+
+    def name() -> str:
+        return channel.name or channel.kind
+
+    async def parse(ctx: HttpChannelRequest) -> HttpChannelParseResult:
+        return await _parse(ctx, handlers, name(), repositories)
+
+    async def run_input(
+        _message: HttpChannelInboundMessage, raw_event: JsonValue | None
+    ) -> ChannelRunResult | None:
+        return await _handler_input(handlers, raw_event, name(), paused=False)
+
+    async def on_paused(target: JsonValue, run: HttpChannelRunInfo) -> None:
+        # Only for an event its handler would act on, so the handler's filters,
+        # such as trusted senders or mentions, decide who gets a notice. The
+        # handler knows it is only asked, so it can skip side effects.
+        if await _handler_input(handlers, run.get("raw_event"), name(), paused=True) is None:
+            return
+        await _post_paused_notice(target, run)
+
+    channel = http_channel(
+        provider="github",
+        verify=_verify,
+        parse=parse,
+        input=run_input,
+        on_paused=on_paused,
+        provider_config=provider_config,
+        multitask_strategy=multitask_strategy,
+    )
+    return channel
+
+
+def _repositories(app: GitHubAppOptions | None) -> frozenset[str] | None:
+    """The repositories the channel is limited to, after checking the App options."""
+    # A misspelled option would silently widen what the agent's token reaches.
+    unknown = sorted(set(app or {}) - {"permissions", "repositories"})
+    if unknown:
+        raise ValueError(
+            f"unknown GitHub app option {', '.join(unknown)}; use permissions or repositories"
+        )
+    # GitHub names are case-insensitive; deploy validates the rest.
+    repositories = (
+        None
+        if app is None or "repositories" not in app
+        else frozenset(repository.strip().lower() for repository in app["repositories"])
+    )
+    if repositories is not None and not repositories:
+        raise ValueError(
+            "GitHub app.repositories must list at least one repository; "
+            "omit it to allow every repository"
+        )
+    return repositories
+
+
+def _subscribed_events(handlers: Mapping[SupportedEventKey, GitHubEventCallback]) -> list[str]:
+    """The events deploy subscribes the App to: the handled ones."""
+    return sorted(handlers)
+
+
+def _app_config(app: GitHubAppOptions) -> dict[str, JsonValue]:
+    """The App options deploy reads, without unset fields."""
+    config: dict[str, JsonValue] = {}
+    if "permissions" in app:
+        config["permissions"] = dict(app["permissions"])
+    if "repositories" in app:
+        config["repositories"] = list(app["repositories"])
+    return config
+
+
+# How long a value read from Agent Auth is reused before it is read again.
+_APP_VALUE_TTL_SECONDS = 300.0
+# How long a missing value is remembered, so unsigned traffic cannot hammer Agent Auth.
+_MISSING_APP_VALUE_TTL_SECONDS = 60.0
+
+
+class _AppValue:
+    __slots__ = ("expires_at", "value")
+
+    def __init__(self, value: asyncio.Future[str | None], expires_at: float) -> None:
+        self.value = value
+        self.expires_at = expires_at
+
+
+_app_values: dict[str, _AppValue] = {}
+
+
+async def _github_app_value(env_key: str, suffix: str) -> str | None:
+    """The App's webhook secret or bot ID.
+
+    The ``GH_*`` env override wins; otherwise the agent secret Agent Auth stored
+    when ``mda deploy`` created the App, at ``mda/github-app/{deployment}/{suffix}``.
+    Only a missing connection reads as ``None``; credential store failures propagate.
+    """
+    from managed_deepagents._connections import DEPLOYMENT_ID_ENV  # noqa: PLC0415
+
+    override = os.environ.get(env_key, "").strip()
+    if override:
+        return override
+    deployment_id = os.environ.get(DEPLOYMENT_ID_ENV, "").strip()
+    if not deployment_id:
+        return None
+    slug = github_app_connection_slug(deployment_id, suffix)
+    entry = _app_values.get(slug)
+    if entry is None or entry.expires_at <= time.monotonic():
+        # Concurrent deliveries share the in-flight read.
+        entry = _AppValue(
+            asyncio.ensure_future(_read_app_value(slug, suffix)),
+            time.monotonic() + _APP_VALUE_TTL_SECONDS,
+        )
+        _app_values[slug] = entry
+    try:
+        # Shielded so one cancelled delivery does not cancel the shared read.
+        value = await asyncio.shield(entry.value)
+    except Exception:
+        # Read again on the next delivery rather than caching a failure.
+        if _app_values.get(slug) is entry:
+            del _app_values[slug]
+        raise
+    if value is None:
+        entry.expires_at = min(entry.expires_at, time.monotonic() + _MISSING_APP_VALUE_TTL_SECONDS)
+    return value
+
+
+async def _read_app_value(slug: str, suffix: str) -> str | None:
+    from managed_deepagents._connections import (  # noqa: PLC0415
+        ConnectionNotFoundError,
+        connections,
+    )
+
+    try:
+        return await connections.resolve_deployment_secret(slug)
+    except ConnectionNotFoundError:
+        logger.error("GitHub App %s is not stored in Agent Auth", suffix)
+        return None
+
+
+def reset_github_app_values() -> None:
+    """Forget values read from Agent Auth; for tests."""
+    _app_values.clear()
+
+
+async def _verify(ctx: HttpChannelRequest) -> bool:
+    # GitHub pings a new App before Agent Auth has its webhook secret, and a
+    # ping starts nothing, so it needs no secret. Reading it here would also
+    # remember the secret as missing and reject the first real events.
+    if ctx.request.headers.get("x-github-event") == "ping":
+        return True
+    # Reject unsigned deliveries before reading the secret from Agent Auth.
+    signature = ctx.request.headers.get("x-hub-signature-256", "")
+    if re.fullmatch(r"sha256=[a-fA-F0-9]{64}", signature) is None:
+        return False
+    secret = await _github_app_value("GH_WEBHOOK_SECRET", "webhook-secret")
+    if not secret:
+        return False
+    expected = hmac.digest(secret.encode(), ctx.raw_body, "sha256")
+    return hmac.compare_digest(expected, bytes.fromhex(signature[7:]))
+
+
+async def _parse(
+    ctx: HttpChannelRequest,
+    handlers: Mapping[SupportedEventKey, GitHubEventCallback],
+    channel_name: str,
+    repositories: frozenset[str] | None,
+) -> HttpChannelParseResult:
+    json_response = import_module("starlette.responses").JSONResponse
+
+    envelope = github_receipt_adapter.validate_python(
+        {
+            "event": ctx.request.headers.get("x-github-event"),
+            "delivery_id": ctx.request.headers.get("x-github-delivery"),
+            "payload": await ctx.request.json(),
+        },
+        strict=True,
+    )
+    event = envelope["event"]
+    record = envelope["payload"]
+    _receipt(record, event, envelope["delivery_id"])
+    response = json_response({"status": "received"}, status_code=200 if event == "ping" else 202)
+
+    # Events nothing handles stop here, before run creation.
+    # Events without an action, such as `push`, are keyed by their name.
+    action = record.get("action")
+    key = cast("SupportedEventKey", event if action is None else f"{event}.{action}")
+    if handlers.get(key) is None:
+        return {"type": "ignore", "response": response}
+
+    parsed_event = github_event(key, record, envelope["delivery_id"])
+
+    # Events from repositories the channel is not limited to start nothing.
+    if repositories is not None and parsed_event.repository.full_name.lower() not in repositories:
+        return {"type": "ignore", "response": response}
+
+    # Ignore the App's own activity to avoid triggering ourselves.
+    configured_bot_id = await _github_app_value("GH_APP_BOT_ID", "bot-id") or ""
+    if not re.fullmatch(r"[1-9][0-9]*", configured_bot_id):
+        raise TypeError(
+            "GitHub App bot ID is unavailable; run `mda deploy` to store it or set GH_APP_BOT_ID"
+        )
+    bot_id = github_identifier_adapter.validate_python(int(configured_bot_id), strict=True)
+    if parsed_event.sender.id == bot_id:
+        return {"type": "ignore", "response": response}
+
+    # Preserve the original event even if a callback modifies its argument.
+    event_snapshot = asdict(parsed_event)
+    if not is_json_value(event_snapshot):
+        raise TypeError("invalid GitHub event")
+
+    # One thread per issue or pull request, so the agent keeps the
+    # conversation. Other events get their own thread, keyed by the delivery so
+    # a redelivery still finds the run it started.
+    delivery_id = envelope["delivery_id"]
+    number = _conversation_number(parsed_event)
+    thread_id = channel_thread_id(
+        channel_name,
+        f"delivery/{delivery_id}" if number is None else f"{parsed_event.repository.id}/{number}",
+    )
+    target: dict[str, JsonValue] | None = None
+    if number is not None:
+        target = {"repository": parsed_event.repository.full_name, "number": number}
+    # What the run starts with is decided once MDA knows the thread takes a new
+    # turn.
+    message: HttpChannelInboundMessage = {
+        "thread_id": thread_id,
+        "user_id": "mda:channel",
+        "target": target,
+        "delivery_key": delivery_id,
+    }
+    return {
+        "type": "message",
+        "message": message,
+        "raw_event": event_snapshot,
+        "response": response,
+    }
+
+
+async def _handler_input(
+    handlers: Mapping[SupportedEventKey, GitHubEventCallback],
+    raw_event: JsonValue | None,
+    channel_name: str,
+    *,
+    paused: bool,
+) -> ChannelRunResult | None:
+    """What the event's handler starts a run with; ``None`` when it skips or fails."""
+    event = _event(raw_event)
+    handler = None if event is None else handlers.get(event.key)
+    if event is None or handler is None:
+        return None
+    receipt = {
+        "event": logger.log_identifier(event.key),
+        "deliveryId": logger.log_identifier(event.delivery_id),
+    }
+    try:
+        result = handler(
+            event, GitHubChannelRuntime(channel=_ChannelName(name=channel_name), paused=paused)
+        )
+        content = await result if inspect.isawaitable(result) else result
+    except Exception as error:  # noqa: BLE001
+        logger.error(
+            "github callback failed %s (%s)",
+            json.dumps(receipt),
+            logger.safe_error_label(error),
+        )
+        return None
+    if content is not None:
+        logger.info("GitHub handler returned run input %s", json.dumps(receipt))
+    return cast("ChannelRunResult | None", content)
+
+
+def _event(raw_event: JsonValue | None) -> GitHubEvent | None:
+    """The parsed event a delivery carries, as callbacks may change it."""
+    if not isinstance(raw_event, Mapping):
+        return None
+    raw = cast("Mapping[str, object]", copy.deepcopy(dict(raw_event)))
+    try:
+        return GitHubEvent(
+            key=cast("SupportedEventKey", raw["key"]),
+            name=cast("str", raw["name"]),
+            action=cast("str", raw["action"]),
+            delivery_id=cast("str", raw["delivery_id"]),
+            installation_id=cast("int", raw["installation_id"]),
+            repository=GitHubRepository(**cast("dict[str, Any]", raw["repository"])),
+            sender=GitHubSender(**cast("dict[str, Any]", raw["sender"])),
+            payload=cast("Any", raw["payload"]),
+        )
+    except (KeyError, TypeError):
+        return None
+
+
+def _conversation_number(event: GitHubEvent) -> int | None:
+    """The issue or pull request an event is about, if any."""
+    payload = cast("Mapping[str, object]", event.payload)
+    for subject in ("issue", "pull_request"):
+        record = payload.get(subject)
+        number = record.get("number") if isinstance(record, Mapping) else None
+        if _is_issue_number(number):
+            return cast("int", number)
+    # A CI run belongs to a pull request only when it ran for exactly one.
+    for kind in ("workflow_run", "check_run", "check_suite"):
+        run = payload.get(kind)
+        pull_requests = run.get("pull_requests") if isinstance(run, Mapping) else None
+        if isinstance(pull_requests, list) and len(pull_requests) == 1:
+            only = pull_requests[0]
+            number = only.get("number") if isinstance(only, Mapping) else None
+            if _is_issue_number(number):
+                return cast("int", number)
+    return None
+
+
+def _is_issue_number(value: object) -> bool:
+    return type(value) is int and 0 < value <= _MAX_SAFE_INTEGER
+
+
+class _GitHubTarget(TypedDict):
+    """Where notices go: the issue or pull request of the conversation."""
+
+    repository: str
+    number: int
+
+
+_REPOSITORY_PATTERN = re.compile(r"[A-Za-z0-9-]+/[A-Za-z0-9._-]+")
+_UUID_PATTERN = re.compile(
+    r"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}", re.IGNORECASE
+)
+_GITHUB_API_TIMEOUT_SECONDS = 10.0
+
+
+async def _post_paused_notice(target: JsonValue, run: HttpChannelRunInfo) -> None:
+    """The thread waits on an interrupt, so tell the issue or pull request where to continue it.
+
+    Posts as the App with the agent's installation token; the notice is fixed text.
+    """
+    if not _is_github_target(target):
+        return
+    from managed_deepagents._connections import connections  # noqa: PLC0415
+
+    url = studio_url(run)
+    studio = f"[LangSmith Studio]({url})" if url else "LangSmith Studio"
+    github_target = cast("_GitHubTarget", target)
+    owner, name = github_target["repository"].split("/")
+    token = await connections.resolve_deployment_secret(GITHUB_TOKEN_SLUG)
+    async with httpx.AsyncClient(
+        timeout=_GITHUB_API_TIMEOUT_SECONDS, follow_redirects=False
+    ) as client:
+        response = await client.post(
+            f"https://api.github.com/repos/{quote(owner, safe='')}/{quote(name, safe='')}"
+            f"/issues/{github_target['number']}/comments",
+            headers={
+                "Accept": "application/vnd.github+json",
+                "Authorization": f"Bearer {token}",
+                "X-GitHub-Api-Version": "2022-11-28",
+            },
+            json={
+                "body": "I'm waiting for a decision on an earlier step in this conversation, "
+                f"so I haven't read this yet. Review the pending step in {studio}, "
+                "then comment again."
+            },
+        )
+    if not response.is_success:
+        raise RuntimeError(f"GitHub refused the paused notice (HTTP {response.status_code})")
+
+
+_DEPLOYMENT_NAME_PATTERN = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]{0,127}")
+
+
+def studio_url(run: HttpChannelRunInfo | None, env: Mapping[str, str] | None = None) -> str | None:
+    """The thread in the deployment's Studio.
+
+    The deployment's page when the deployment's name or the thread's assistant
+    is unknown. The LangSmith UI is the one ``mda deploy`` recorded for the
+    deployment's environment (``MDA_LANGSMITH_URL``); without it there is
+    nothing to link to.
+    """
+    from managed_deepagents._connections import DEPLOYMENT_ID_ENV  # noqa: PLC0415
+    from managed_deepagents.runtime import _managed_deployment_name  # noqa: PLC0415
+
+    values = os.environ if env is None else env
+    workspace = values.get("LANGSMITH_TENANT_ID", "").strip()
+    deployment = values.get(DEPLOYMENT_ID_ENV, "").strip()
+    if not (_UUID_PATTERN.fullmatch(workspace) and _UUID_PATTERN.fullmatch(deployment)):
+        return None
+    origin = _http_origin(values.get("MDA_LANGSMITH_URL", ""))
+    if origin is None:
+        return None
+    name = _managed_deployment_name(values) or ""
+    thread_id = (run or {}).get("thread_id", "")
+    assistant_id = (run or {}).get("assistant_id", "")
+    if not (
+        _DEPLOYMENT_NAME_PATTERN.fullmatch(name)
+        and _UUID_PATTERN.fullmatch(thread_id)
+        and _UUID_PATTERN.fullmatch(assistant_id)
+    ):
+        return f"{origin}/o/{workspace}/host/deployments/{deployment}"
+    query = urlencode(
+        {
+            "organizationId": workspace,
+            "render": "interact",
+            "hostProjectId": deployment,
+            "assistantId": assistant_id,
+            "mode": "chat",
+            "threadId": thread_id,
+        }
+    )
+    return f"{origin}/o/{workspace}/a/{quote(name, safe='')}/studio/thread?{query}"
+
+
+def _http_origin(value: str) -> str | None:
+    url = urlsplit(value.strip())
+    if url.scheme not in ("http", "https") or not url.hostname:
+        return None
+    return f"{url.scheme}://{url.netloc.rsplit('@', 1)[-1]}"
+
+
+def _is_github_target(value: object) -> bool:
+    if not isinstance(value, Mapping):
+        return False
+    repository = value.get("repository")
+    return (
+        isinstance(repository, str)
+        and _REPOSITORY_PATTERN.fullmatch(repository) is not None
+        and _is_issue_number(value.get("number"))
+    )
+
+
+def _receipt(record: Mapping[str, object], event: str, delivery_id: str) -> dict[str, str | int]:
+    receipt: dict[str, str | int] = {
+        "event": logger.log_identifier(event),
+        "deliveryId": logger.log_identifier(delivery_id),
+    }
+    action = record.get("action")
+    if isinstance(action, str):
+        receipt["action"] = logger.log_identifier(action)
+    for key, field in (("repository", "id"), ("issue", "number"), ("pull_request", "number")):
+        value = record.get(key)
+        if isinstance(value, dict):
+            receipt_id = value.get(field)
+            if type(receipt_id) is int and abs(receipt_id) <= _MAX_SAFE_INTEGER:
+                receipt[key] = receipt_id
+    logger.info("github receipt %s", json.dumps(receipt))
+    return receipt