gatewaysdk 0.3.2__py3-none-any.whl

gatewaysdk/environment/schema/connectors/slack/handlers.py

@@ -0,0 +1,762 @@
+"""Slack collaboration operations over one canonical, validated schema store."""
+
+import base64
+import functools
+import hashlib
+import json
+from fractions import Fraction
+from pathlib import Path
+
+from gateway_env import store, tool
+
+
+@tool(name="list_channels")
+def list_channels(workspace_id):
+    if Path(__file__).with_name("slack-principal.json").is_file():
+        if workspace_id != _principal()[0]["workspace_id"]:
+            raise ValueError("channel_not_found")
+        return [
+            row
+            for row in store.list("slack_channels")
+            if row["workspace_id"] == workspace_id
+            and (not (row.get("is_private") or row.get("is_im") or row.get("is_mpim")) or _member(row["id"]))
+        ]
+    return [channel for channel in store.list("slack_channels") if channel["workspace_id"] == workspace_id]
+
+
+def _timestamp_key(message):
+    """Compare decimal strings exactly, including unequal fractional widths."""
+    timestamp = message["ts"]
+    seconds, separator, fraction = timestamp.partition(".")
+    if not separator or not seconds or not fraction or any(c not in "0123456789" for c in seconds + fraction):
+        raise ValueError("list_messages requires decimal Slack timestamp strings")
+    seconds = seconds.lstrip("0") or "0"
+    return len(seconds), seconds, fraction.rstrip("0"), timestamp
+
+
+@tool(name="list_messages")
+def list_messages(workspace_id, channel_id):
+    if Path(__file__).with_name("slack-principal.json").is_file():
+        if workspace_id != _principal()[0]["workspace_id"]:
+            raise ValueError("channel_not_found")
+        _channel(channel_id)
+    messages = [
+        message
+        for message in store.list("slack_messages")
+        if message["workspace_id"] == workspace_id and message["channel_id"] == channel_id
+    ]
+    return sorted(messages, key=_timestamp_key)
+
+
+@tool(name="post_message")
+def post_message(message):
+    if Path(__file__).with_name("slack-principal.json").is_file():
+        principal, _ = _principal()
+        if message["workspace_id"] != principal["workspace_id"] or message.get("user") != principal["user_id"]:
+            raise ValueError("no_permission")
+        _channel(message["channel_id"], write=True, membership=True)
+    if (
+        not message.get("user")
+        or not message.get("text")
+        or any(field in message for field in ("bot_id", "app_id", "subtype"))
+    ):
+        raise ValueError("post_message supports top-level human text messages only")
+    member = {
+        "workspace_id": message["workspace_id"],
+        "channel_id": message["channel_id"],
+        "user_id": message["user"],
+    }
+    if store.get("slack_memberships", member) is None:
+        raise ValueError("not_in_channel: the author is not a member of this channel")
+    author = store.get("slack_users", {"workspace_id": message["workspace_id"], "id": message["user"]})
+    if author.get("deleted") or author.get("is_bot") or author.get("is_app_user"):
+        raise ValueError("post_message supports top-level human text messages only")
+    return store.insert("slack_messages", message, source={"record": "tool.post_message"})
+
+
+# Slack-shaped executable subset. Every adapter delegates to these canonical
+# operations; principal identity is immutable bundle configuration, never input.
+class _SlackError(Exception):
+    pass
+
+
+def _api(fn):
+    @functools.wraps(fn)
+    def invoke(*args, **kwargs):
+        try:
+            return fn(*args, **kwargs)
+        except _SlackError as error:
+            return {"ok": False, "error": str(error)}
+
+    return invoke
+
+
+def _principal():
+    path = Path(__file__).with_name("slack-principal.json")
+    if not path.is_file():
+        raise _SlackError("not_authed")
+    principal = json.loads(path.read_text())
+    actor = store.get("slack_users", {"workspace_id": principal["workspace_id"], "id": principal["user_id"]})
+    if actor is None or actor.get("deleted") or actor.get("suspended"):
+        raise _SlackError("account_inactive")
+    return principal, actor
+
+
+def _rows(entity, **where):
+    principal, _ = _principal()
+    return [
+        row
+        for row in store.list(entity)
+        if row.get("workspace_id") == principal["workspace_id"] and all(row.get(k) == v for k, v in where.items())
+    ]
+
+
+class _ReadRows:
+    """Lazy lookup maps for one read response, never shared with mutations."""
+
+    def __init__(self):
+        self.workspace = _principal()[0]["workspace_id"]
+        self.entities = {}
+        self.indexes = {}
+
+    def __call__(self, entity, **where):
+        if entity not in self.entities:
+            self.entities[entity] = [row for row in store.list(entity) if row.get("workspace_id") == self.workspace]
+        values = self.entities[entity]
+        if not where:
+            return values
+        fields = tuple(sorted(where))
+        key = entity, fields
+        if key not in self.indexes:
+            groups = {}
+            for row in values:
+                groups.setdefault(tuple(row.get(field) for field in fields), []).append(row)
+            self.indexes[key] = groups
+        return self.indexes[key].get(tuple(where[field] for field in fields), [])
+
+
+def _key(**fields):
+    principal, _ = _principal()
+    return {"workspace_id": principal["workspace_id"], **fields}
+
+
+def _source(method):
+    principal, _ = _principal()
+    return {"record": "tool.slack." + method + ":" + principal["user_id"]}
+
+
+def _member(channel):
+    principal, _ = _principal()
+    return store.get("slack_memberships", _key(channel_id=channel, user_id=principal["user_id"])) is not None
+
+
+def _channel(channel, *, write=False, membership=False):
+    principal, actor = _principal()
+    row = store.get("slack_channels", _key(id=channel))
+    if row is None or ((row.get("is_private") or row.get("is_im") or row.get("is_mpim")) and not _member(channel)):
+        raise _SlackError("channel_not_found")
+    if (membership or actor.get("is_bot")) and not _member(channel):
+        raise _SlackError("not_in_channel")
+    if write and row.get("is_archived"):
+        raise _SlackError("is_archived")
+    state = store.get("slack_conversation_states", _key(channel_id=channel, user_id=principal["user_id"]))
+    if write and (row.get("is_frozen") or (state and state.get("is_read_only"))):
+        raise _SlackError("restricted_action")
+    return row
+
+
+def _public(row):
+    return {k: v for k, v in row.items() if k not in ("workspace_id", "channel_id")}
+
+
+def _conversation(row):
+    result = _public(row)
+    result["is_member"] = _member(row["id"])
+    principal, _ = _principal()
+    state = store.get("slack_conversation_states", _key(channel_id=row["id"], user_id=principal["user_id"]))
+    if state:
+        result.update(
+            {
+                k: v
+                for k, v in state.items()
+                if k not in ("workspace_id", "channel_id", "user_id", "counterpart_user_id")
+            }
+        )
+        if "counterpart_user_id" in state:
+            result["user"] = state["counterpart_user_id"]
+    result["is_member"] = _member(row["id"])
+    return result
+
+
+def _page(items, field, scope, cursor="", limit=100, *, render=None):
+    token = hashlib.sha256(json.dumps(scope, sort_keys=True).encode()).hexdigest()[:20]
+    offset = 0
+    if cursor:
+        try:
+            parsed = json.loads(base64.urlsafe_b64decode(cursor.encode()).decode())
+            if parsed["scope"] != token or type(parsed["offset"]) is not int or parsed["offset"] < 0:
+                raise ValueError()
+            offset = parsed["offset"]
+        except (ValueError, KeyError, TypeError, UnicodeError):
+            raise _SlackError("invalid_cursor") from None
+    end = offset + limit
+    next_cursor = (
+        base64.urlsafe_b64encode(json.dumps({"scope": token, "offset": end}, separators=(",", ":")).encode()).decode()
+        if end < len(items)
+        else ""
+    )
+    return {
+        "ok": True,
+        field: [render(item) for item in items[offset:end]] if render else items[offset:end],
+        "response_metadata": {"next_cursor": next_cursor},
+        "has_more": bool(next_cursor),
+    }
+
+
+def _number(ts, error="invalid_ts_latest"):
+    try:
+        if not isinstance(ts, str) or not ts or not all(c in "0123456789" for c in ts):
+            _timestamp_key({"ts": ts})
+        return Fraction(ts)
+    except (ValueError, TypeError, AttributeError, ZeroDivisionError):
+        raise _SlackError(error) from None
+
+
+def _message(channel, ts, *, write=False):
+    _channel(channel, write=write, membership=write)
+    _number(ts, "bad_timestamp")
+    row = store.get("slack_messages", _key(channel_id=channel, ts=ts))
+    if row is None:
+        raise _SlackError("message_not_found")
+    return row
+
+
+def _render_message(row, rows=None):
+    rows = rows or _rows
+    result = _public(row)
+    channel, ts = row["channel_id"], row["ts"]
+    thread = store.get("slack_message_threads", _key(channel_id=channel, reply_ts=ts))
+    children = rows("slack_message_threads", channel_id=channel, parent_ts=ts)
+    if thread or children:
+        result["thread_ts"] = thread["parent_ts"] if thread else ts
+    reactions = rows("slack_reaction_summaries", channel_id=channel, message_ts=ts)
+    if reactions:
+        result["reactions"] = [
+            {
+                "name": r["name"],
+                "count": r["count"],
+                "users": [
+                    u["user_id"]
+                    for u in rows("slack_reaction_users", channel_id=channel, message_ts=ts, name=r["name"])
+                ],
+            }
+            for r in reactions
+        ]
+    files = []
+    for association in rows("slack_message_files", channel_id=channel, message_ts=ts):
+        value = store.get("slack_files", _key(id=association["file_id"]))
+        files.append((association.get("position", 0), _public(value)))
+    for association in rows("slack_unavailable_message_files", channel_id=channel, message_ts=ts):
+        files.append((association.get("position", 0), {"id": association["file_id"], **association["reference"]}))
+    if files:
+        result["files"] = [value for _, value in sorted(files, key=lambda pair: (pair[0], pair[1]["id"]))]
+    return result
+
+
+def _next_ts():
+    # A deterministic logical clock, explicitly not vendor/server wall time.
+    seconds = (
+        max(
+            (int(_number(row["ts"]).numerator // _number(row["ts"]).denominator) for row in _rows("slack_messages")),
+            default=1700000000,
+        )
+        + 1
+    )
+    return str(seconds) + ".000001"
+
+
+def _user(row, rows=None):
+    rows = rows or _rows
+    result = _public(row)
+    if isinstance(result.get("profile"), dict):
+        profile = dict(result["profile"])
+        marker = profile.pop("fields_state", None)
+        fields = rows("slack_user_profile_fields", user_id=row["id"])
+        if marker == "null":
+            profile["fields"] = None
+        elif marker == "present" or fields:
+            profile["fields"] = {
+                f["field_id"]: {k: v for k, v in f.items() if k not in ("workspace_id", "user_id", "field_id")}
+                for f in fields
+            }
+        result["profile"] = profile
+    return result
+
+
+@tool(name="users.list")
+@_api
+def users_list(cursor="", limit=100):
+    rows = _ReadRows()
+    return _page(
+        rows("slack_users"),
+        "members",
+        ["users.list", _principal()[0]],
+        cursor,
+        limit,
+        render=lambda row: _user(row, rows),
+    )
+
+
+@tool(name="users.info")
+@_api
+def users_info(user):
+    value = store.get("slack_users", _key(id=user))
+    if value is None:
+        raise _SlackError("user_not_found")
+    return {"ok": True, "user": _user(value)}
+
+
+@tool(name="conversations.list")
+@_api
+def conversations_list(cursor="", limit=100, types="public_channel", exclude_archived=False):
+    allowed = types.split(",")
+    if any(kind not in ("public_channel", "private_channel", "im", "mpim") for kind in allowed):
+        raise _SlackError("invalid_types")
+    values = []
+    for row in _rows("slack_channels"):
+        kind = (
+            "im"
+            if row.get("is_im")
+            else "mpim" if row.get("is_mpim") else "private_channel" if row.get("is_private") else "public_channel"
+        )
+        if (
+            kind not in allowed
+            or (exclude_archived and row.get("is_archived"))
+            or (kind != "public_channel" and not _member(row["id"]))
+        ):
+            continue
+        values.append(row)
+    return _page(
+        values,
+        "channels",
+        ["conversations.list", _principal()[0], types, exclude_archived],
+        cursor,
+        limit,
+        render=_conversation,
+    )
+
+
+@tool(name="conversations.info")
+@_api
+def conversations_info(channel):
+    return {"ok": True, "channel": _conversation(_channel(channel))}
+
+
+@tool(name="conversations.members")
+@_api
+def conversations_members(channel, cursor="", limit=100):
+    _channel(channel)
+    return _page(
+        [row["user_id"] for row in _rows("slack_memberships", channel_id=channel)],
+        "members",
+        ["conversations.members", _principal()[0], channel],
+        cursor,
+        limit,
+    )
+
+
+def _history(channel, *, parent=None, cursor="", limit=100, oldest=None, latest=None, inclusive=False):
+    _channel(channel)
+    if parent is not None:
+        selected = _message(channel, parent)
+        association = store.get("slack_message_threads", _key(channel_id=channel, reply_ts=parent))
+        if association:
+            parent = association["parent_ts"]
+        if selected.get("subtype") in ("channel_join", "channel_leave"):
+            raise _SlackError("thread_not_found")
+    lower = _number(oldest, "invalid_ts_oldest") if oldest is not None else None
+    upper = _number(latest) if latest is not None else None
+    rows = _ReadRows()
+    threads = {row["reply_ts"]: row["parent_ts"] for row in rows("slack_message_threads", channel_id=channel)}
+    selected = []
+    for row in rows("slack_messages", channel_id=channel):
+        ts = row["ts"]
+        if parent is None and ts in threads and row.get("subtype") != "thread_broadcast":
+            continue
+        if parent is not None and ts != parent and threads.get(ts) != parent:
+            continue
+        numeric = _number(ts)
+        if lower is not None and (numeric < lower or (numeric == lower and not inclusive)):
+            continue
+        if upper is not None and (numeric > upper or (numeric == upper and not inclusive)):
+            continue
+        selected.append(row)
+    selected.sort(key=_timestamp_key, reverse=parent is None)
+    return _page(
+        selected,
+        "messages",
+        ["history", _principal()[0], channel, parent, oldest, latest, inclusive],
+        cursor,
+        limit,
+        render=lambda row: _render_message(row, rows),
+    )
+
+
+@tool(name="conversations.history")
+@_api
+def conversations_history(channel, cursor="", limit=100, oldest=None, latest=None, inclusive=False):
+    return _history(channel, cursor=cursor, limit=limit, oldest=oldest, latest=latest, inclusive=inclusive)
+
+
+@tool(name="conversations.replies")
+@_api
+def conversations_replies(channel, ts, cursor="", limit=100, oldest=None, latest=None, inclusive=False):
+    return _history(channel, parent=ts, cursor=cursor, limit=limit, oldest=oldest, latest=latest, inclusive=inclusive)
+
+
+@tool(name="conversations.join")
+@_api
+def conversations_join(channel):
+    row = _channel(channel, write=True)
+    if row.get("is_private") or row.get("is_im") or row.get("is_mpim"):
+        raise _SlackError("method_not_supported_for_channel_type")
+    principal, _ = _principal()
+    if not _member(channel):
+        store.insert(
+            "slack_memberships",
+            _key(channel_id=channel, user_id=principal["user_id"]),
+            source=_source("conversations.join"),
+        )
+        if "num_members" in row:
+            store.update(
+                "slack_channels",
+                _key(id=channel),
+                {"num_members": row["num_members"] + 1},
+                source=_source("conversations.join"),
+            )
+    return {"ok": True, "channel": _conversation(store.get("slack_channels", _key(id=channel)))}
+
+
+@tool(name="conversations.leave")
+@_api
+def conversations_leave(channel):
+    row = _channel(channel, write=True, membership=True)
+    if row.get("is_general") or row.get("is_im"):
+        raise _SlackError("cant_leave_general" if row.get("is_general") else "method_not_supported_for_channel_type")
+    principal, _ = _principal()
+    store.delete(
+        "slack_memberships",
+        _key(channel_id=channel, user_id=principal["user_id"]),
+        source=_source("conversations.leave"),
+    )
+    if "num_members" in row:
+        store.update(
+            "slack_channels",
+            _key(id=channel),
+            {"num_members": max(0, row["num_members"] - 1)},
+            source=_source("conversations.leave"),
+        )
+    return {"ok": True}
+
+
+@tool(name="chat.postMessage")
+@_api
+def chat_post_message(
+    channel, text=None, blocks=None, attachments=None, thread_ts=None, reply_broadcast=False, client_msg_id=None
+):
+    _channel(channel, write=True, membership=True)
+    if not text and not blocks and not attachments:
+        raise _SlackError("no_text")
+    if reply_broadcast and thread_ts is None:
+        raise _SlackError("invalid_arguments")
+    principal, _ = _principal()
+    parent = None
+    if thread_ts:
+        parent = _message(channel, thread_ts)
+        if store.get("slack_message_threads", _key(channel_id=channel, reply_ts=thread_ts)) or parent.get(
+            "subtype"
+        ) in ("channel_join", "channel_leave"):
+            raise _SlackError("thread_not_found")
+    if client_msg_id:
+        prior = [
+            m
+            for m in _rows("slack_messages", channel_id=channel, user=principal["user_id"])
+            if m.get("client_msg_id") == client_msg_id
+        ]
+        if prior:
+            return {"ok": True, "channel": channel, "ts": prior[0]["ts"], "message": _render_message(prior[0])}
+    value = _key(channel_id=channel, ts=_next_ts(), type="message", user=principal["user_id"])
+    for name, content in (
+        ("text", text),
+        ("blocks", blocks),
+        ("attachments", attachments),
+        ("client_msg_id", client_msg_id),
+    ):
+        if content is not None:
+            value[name] = content
+    if reply_broadcast:
+        value["subtype"] = "thread_broadcast"
+    store.insert("slack_messages", value, source=_source("chat.postMessage"))
+    if parent:
+        store.insert(
+            "slack_message_threads",
+            _key(channel_id=channel, reply_ts=value["ts"], parent_ts=thread_ts),
+            source=_source("chat.postMessage"),
+        )
+        store.update(
+            "slack_messages",
+            _key(channel_id=channel, ts=thread_ts),
+            {"reply_count": parent.get("reply_count", 0) + 1, "latest_reply": value["ts"]},
+            source=_source("chat.postMessage"),
+        )
+    return {"ok": True, "channel": channel, "ts": value["ts"], "message": _render_message(value)}
+
+
+@tool(name="chat.update")
+@_api
+def chat_update(channel, ts, text=None, blocks=None, attachments=None):
+    row = _message(channel, ts, write=True)
+    principal, _ = _principal()
+    if row.get("user") != principal["user_id"] or row.get("subtype") not in (None, "me_message", "thread_broadcast"):
+        raise _SlackError("cant_update_message")
+    patch = {
+        name: value
+        for name, value in (("text", text), ("blocks", blocks), ("attachments", attachments))
+        if value is not None
+    }
+    if not patch:
+        raise _SlackError("no_text")
+    if text is not None and blocks is None:
+        patch["blocks"] = []
+    patch["edited"] = {"user": principal["user_id"], "ts": _next_ts()}
+    updated = store.update("slack_messages", _key(channel_id=channel, ts=ts), patch, source=_source("chat.update"))
+    return {
+        "ok": True,
+        "channel": channel,
+        "ts": ts,
+        "text": updated.get("text", ""),
+        "message": _render_message(updated),
+    }
+
+
+@tool(name="chat.delete")
+@_api
+def chat_delete(channel, ts):
+    row = _message(channel, ts, write=True)
+    principal, _ = _principal()
+    if row.get("user") != principal["user_id"]:
+        raise _SlackError("cant_delete_message")
+    if (
+        _rows("slack_message_threads", channel_id=channel, parent_ts=ts)
+        or _rows("slack_scheduled_message_threads", channel_id=channel, parent_ts=ts)
+        or _rows("slack_ephemeral_message_threads", channel_id=channel, parent_ts=ts)
+    ):
+        raise _SlackError("unsupported_thread_root_delete")
+    association = store.get("slack_message_threads", _key(channel_id=channel, reply_ts=ts))
+    if association:
+        store.delete("slack_message_threads", _key(channel_id=channel, reply_ts=ts), source=_source("chat.delete"))
+        parent = _message(channel, association["parent_ts"])
+        store.update(
+            "slack_messages",
+            _key(channel_id=channel, ts=parent["ts"]),
+            {"reply_count": max(0, parent.get("reply_count", 0) - 1)},
+            source=_source("chat.delete"),
+        )
+    for entity, extra in (
+        ("slack_reaction_users", ("name", "user_id")),
+        ("slack_reaction_summaries", ("name",)),
+        ("slack_message_user_states", ("user_id",)),
+        ("slack_file_shares", ("file_id",)),
+        ("slack_message_files", ("file_id",)),
+        ("slack_unavailable_message_files", ("file_id",)),
+        ("slack_pins", ()),
+    ):
+        for dependent in _rows(entity, channel_id=channel, message_ts=ts):
+            store.delete(
+                entity,
+                _key(channel_id=channel, message_ts=ts, **{k: dependent[k] for k in extra}),
+                source=_source("chat.delete"),
+            )
+    store.delete("slack_messages", _key(channel_id=channel, ts=ts), source=_source("chat.delete"))
+    return {"ok": True, "channel": channel, "ts": ts}
+
+
+def _reaction(channel, timestamp, name, remove=False):
+    _message(channel, timestamp, write=True)
+    if not name or any(c.isspace() for c in name):
+        raise _SlackError("invalid_name")
+    principal, _ = _principal()
+    key = _key(channel_id=channel, message_ts=timestamp, name=name)
+    actor_key = {**key, "user_id": principal["user_id"]}
+    actor = store.get("slack_reaction_users", actor_key)
+    summary = store.get("slack_reaction_summaries", key)
+    method = "reactions.remove" if remove else "reactions.add"
+    if remove:
+        if actor is None:
+            raise _SlackError("no_reaction")
+        store.delete("slack_reaction_users", actor_key, source=_source(method))
+        count = max(0, summary["count"] - 1)
+        if count == 0 and not _rows("slack_reaction_users", channel_id=channel, message_ts=timestamp, name=name):
+            store.delete("slack_reaction_summaries", key, source=_source(method))
+        else:
+            store.update("slack_reaction_summaries", key, {"count": count}, source=_source(method))
+    else:
+        if actor:
+            raise _SlackError("already_reacted")
+        if summary:
+            store.update("slack_reaction_summaries", key, {"count": summary["count"] + 1}, source=_source(method))
+        else:
+            store.insert("slack_reaction_summaries", {**key, "count": 1}, source=_source(method))
+        store.insert("slack_reaction_users", actor_key, source=_source(method))
+    return {"ok": True}
+
+
+@tool(name="reactions.add")
+@_api
+def reactions_add(channel, timestamp, name):
+    return _reaction(channel, timestamp, name)
+
+
+@tool(name="reactions.remove")
+@_api
+def reactions_remove(channel, timestamp, name):
+    return _reaction(channel, timestamp, name, remove=True)
+
+
+@tool(name="reactions.get")
+@_api
+def reactions_get(channel, timestamp):
+    return {"ok": True, "type": "message", "channel": channel, "message": _render_message(_message(channel, timestamp))}
+
+
+def _file(file_id, *, row=None, rows=None, visible_channels=None):
+    rows = rows or _rows
+    row = store.get("slack_files", _key(id=file_id)) if row is None else row
+    principal, _ = _principal()
+    if row is None:
+        raise _SlackError("file_not_found")
+    visible = row.get("user") == principal["user_id"] or row.get("is_public")
+    channels = visible_channels if visible_channels is not None else {}
+    for share in rows("slack_message_files", file_id=file_id):
+        channel = share["channel_id"]
+        if channel not in channels:
+            try:
+                _channel(channel)
+                channels[channel] = True
+            except _SlackError:
+                channels[channel] = False
+        visible = visible or channels[channel]
+    if not visible:
+        raise _SlackError("file_not_found")
+    return row
+
+
+@tool(name="files.info")
+@_api
+def files_info(file):
+    return {"ok": True, "file": _public(_file(file))}
+
+
+@tool(name="files.list")
+@_api
+def files_list(channel=None, user=None, page=1, count=100):
+    if channel:
+        _channel(channel)
+    files = []
+    rows = _ReadRows()
+    visible_channels = {}
+    for row in rows("slack_files"):
+        if user and row.get("user") != user:
+            continue
+        if channel and not rows("slack_message_files", channel_id=channel, file_id=row["id"]):
+            continue
+        try:
+            files.append(_file(row["id"], row=row, rows=rows, visible_channels=visible_channels))
+        except _SlackError:
+            continue
+    return {
+        "ok": True,
+        "files": [_public(row) for row in files[(page - 1) * count : page * count]],
+        "paging": {"count": count, "total": len(files), "page": page, "pages": (len(files) + count - 1) // count},
+    }
+
+
+@tool(name="pins.list")
+@_api
+def pins_list(channel):
+    _channel(channel)
+    rows = _ReadRows()
+    return {
+        "ok": True,
+        "items": [
+            {
+                "type": "message",
+                "channel": channel,
+                "message": _render_message(_message(channel, r["message_ts"]), rows),
+                **{k: r[k] for k in ("created", "created_by") if k in r},
+            }
+            for r in rows("slack_pins", channel_id=channel)
+        ],
+    }
+
+
+@tool(name="pins.add")
+@_api
+def pins_add(channel, timestamp):
+    _message(channel, timestamp, write=True)
+    key = _key(channel_id=channel, message_ts=timestamp)
+    if store.get("slack_pins", key):
+        raise _SlackError("already_pinned")
+    store.insert("slack_pins", {**key, "created_by": _principal()[0]["user_id"]}, source=_source("pins.add"))
+    return {"ok": True}
+
+
+@tool(name="pins.remove")
+@_api
+def pins_remove(channel, timestamp):
+    _message(channel, timestamp, write=True)
+    key = _key(channel_id=channel, message_ts=timestamp)
+    if store.get("slack_pins", key) is None:
+        raise _SlackError("no_pin")
+    store.delete("slack_pins", key, source=_source("pins.remove"))
+    return {"ok": True}
+
+
+@tool(name="bookmarks.list")
+@_api
+def bookmarks_list(channel_id):
+    _channel(channel_id)
+    return {"ok": True, "bookmarks": [_public(r) for r in _rows("slack_bookmarks", channel_id=channel_id)]}
+
+
+@tool(name="usergroups.list")
+@_api
+def usergroups_list(include_users=False, include_disabled=False):
+    values = []
+    rows = _ReadRows()
+    for row in rows("slack_usergroups"):
+        if row.get("date_delete") and not include_disabled:
+            continue
+        value = _public(row)
+        value.pop("users_state", None)
+        if include_users:
+            value["users"] = [r["user_id"] for r in rows("slack_usergroup_memberships", usergroup_id=row["id"])]
+        values.append(value)
+    return {"ok": True, "usergroups": values}
+
+
+@tool(name="usergroups.users.list")
+@_api
+def usergroups_users_list(usergroup):
+    if store.get("slack_usergroups", _key(id=usergroup)) is None:
+        raise _SlackError("usergroup_not_found")
+    return {"ok": True, "users": [r["user_id"] for r in _rows("slack_usergroup_memberships", usergroup_id=usergroup)]}
+
+
+@tool(name="users.getPresence")
+@_api
+def users_get_presence(user):
+    row = store.get("slack_presence", _key(user_id=user))
+    if row is None:
+        raise _SlackError("presence_not_observed")
+    return {"ok": True, **{k: v for k, v in _public(row).items() if k != "user_id"}}