taskboy 0.1.1__py3-none-any.whl

taskboy/adapters/jira.py

@@ -0,0 +1,263 @@
+"""jira cloud operations as permission-aware in-process mcp tools (JIR-001..010).
+
+a dedicated service-account api token (no delete permissions in jira's own scheme — JIR-006/007)
+never reaches the model. created issues always carry the `taskboy` + `agent-task-{id}` labels and
+a task footer (JIR-008); creation checks the artifacts table and a jql label search first (JIR-009).
+projects and issue types are validated against config (JIR-010).
+"""
+
+import json
+import logging
+
+from taskboy.adapters._util import _error, _text, wrap
+from taskboy.models import Task
+from taskboy.redact import redactor
+from taskboy.store import Store
+
+logger = logging.getLogger("taskboy.jira")
+
+
+class JiraAdapter:
+    def __init__(self, store: Store, task: Task, site: str, email: str, api_token: str, projects: list[str], issue_types: list[str], on_milestone=None, story_points_field: str = "", bot_name: str = "Agent"):
+        self.store = store
+        self.task = task
+        self.site = site.rstrip("/")
+        self.email = email
+        self.api_token = api_token
+        self.projects = projects
+        self.issue_types = issue_types
+        self.on_milestone = on_milestone
+        self.story_points_field = story_points_field
+        self.bot_name = bot_name
+
+    # -- tools -------------------------------------------------------------------
+
+    async def search_issues(self, args: dict) -> dict:
+        data = await self._request("GET", "/rest/api/3/search/jql", params={"jql": str(args.get("jql", "")), "maxResults": min(int(args.get("max_results", 10)), 20), "fields": "summary,status,issuetype,assignee"})
+        lines = []
+        for issue in data.get("issues") or []:
+            fields = issue.get("fields") or {}
+            lines.append(f"{issue.get('key')}: {str(fields.get('summary', ''))[:120]} [{(fields.get('status') or {}).get('name')}] ({(fields.get('issuetype') or {}).get('name')})")
+        return _text("\n".join(lines) or "no issues matched")
+
+    async def get_issue(self, args: dict) -> dict:
+        key = str(args.get("key", "")).strip().upper()
+        data = await self._request("GET", f"/rest/api/3/issue/{key}", params={"fields": "summary,status,issuetype,assignee,labels,description,priority"})
+        fields = data.get("fields") or {}
+        summary = {
+            "key": data.get("key"),
+            "summary": fields.get("summary"),
+            "status": (fields.get("status") or {}).get("name"),
+            "type": (fields.get("issuetype") or {}).get("name"),
+            "assignee": (fields.get("assignee") or {}).get("displayName"),
+            "labels": fields.get("labels"),
+            "priority": (fields.get("priority") or {}).get("name"),
+            "description": _adf_to_text(fields.get("description"))[:2000],
+        }
+        return _text(json.dumps(summary, ensure_ascii=False))
+
+    async def search_users(self, args: dict) -> dict:
+        users = await self._request("GET", "/rest/api/3/user/search", params={"query": str(args.get("query", "")), "maxResults": 10})
+        lines = [f"{user.get('accountId')}: {user.get('displayName')} ({user.get('emailAddress') or 'hidden'})" for user in users]
+        return _text("\n".join(lines) or "no users matched")
+
+    async def list_boards(self, args: dict) -> dict:
+        params: dict = {"maxResults": 20}
+        project = str(args.get("project") or "").strip().upper()
+        if project:
+            params["projectKeyOrId"] = project
+        data = await self._request("GET", "/rest/agile/1.0/board", params=params)
+        lines = [f"{board.get('id')}: {board.get('name')} ({board.get('type')})" for board in data.get("values") or []]
+        return _text("\n".join(lines) or "no boards matched")
+
+    async def list_sprints(self, args: dict) -> dict:
+        board_id = int(args.get("board_id") or 0)
+        data = await self._request("GET", f"/rest/agile/1.0/board/{board_id}/sprint", params={"state": "active,future", "maxResults": 20})
+        lines = [f"{sprint.get('id')}: {sprint.get('name')} [{sprint.get('state')}]" for sprint in data.get("values") or []]
+        return _text("\n".join(lines) or "no active or future sprints matched")
+
+    async def create_issue(self, args: dict) -> dict:
+        project = str(args.get("project", "")).strip().upper()
+        issue_type = str(args.get("issue_type", "")).strip()
+        summary = str(args.get("summary", "")).strip()
+        if self.projects and project not in self.projects:
+            return _error(f"project {project!r} is not on the approved list {self.projects}")
+        if self.issue_types and issue_type not in self.issue_types:
+            return _error(f"issue type {issue_type!r} is not permitted; use one of {self.issue_types}")
+        if not summary:
+            return _error("summary is required")
+
+        # idempotency layer 1: this task already created an issue with this summary (JIR-009, ORC-012)
+        for artifact in self.store.artifacts_for(self.task.task_id):
+            if artifact["kind"] == "jira_issue":
+                return _text(f"this task already created {artifact['external_id']} ({artifact['url']}) — comment on or update it instead of creating another")
+        # idempotency layer 2: jql on the task label catches the crash-after-create window
+        existing = await self._request("GET", "/rest/api/3/search/jql", params={"jql": f'labels = "agent-task-{self.task.task_id}"', "maxResults": 1, "fields": "summary"})
+        if existing.get("issues"):
+            issue = existing["issues"][0]
+            self._record_issue(issue["key"])
+            return _text(f"an issue already exists for this task: {issue['key']} — update it instead of creating another")
+
+        description = str(args.get("description", "")).rstrip()
+        footer = f"Created by {self.bot_name} (taskboy) for Slack task {self.task.task_id} in <#{self.task.slack_channel_id}>."
+        fields: dict = {
+            "project": {"key": project},
+            "issuetype": {"name": issue_type},
+            "summary": summary,
+            "description": _adf(f"{description}\n\n{footer}" if description else footer),
+            "labels": ["taskboy", f"agent-task-{self.task.task_id}"],  # JIR-008
+        }
+        assignee = str(args.get("assignee_account_id") or "").strip()
+        parent_key = str(args.get("parent_key") or "").strip()
+        story_points = float(args.get("story_points") or 0)
+        if assignee:
+            fields["assignee"] = {"accountId": assignee}
+        if parent_key:
+            fields["parent"] = {"key": parent_key.upper()}
+        points_note = ""
+        if story_points > 0:
+            if self.story_points_field:
+                fields[self.story_points_field] = story_points
+            else:
+                points_note = " — story points not set — configure jira.story_points_field"
+        payload = {"fields": fields}
+        created = await self._request("POST", "/rest/api/3/issue", payload)
+        key = str(created["key"])
+        self._record_issue(key)
+        if self.on_milestone:
+            await self.on_milestone(f"Created Jira issue {key}")
+        return _text(f"created {key}: {self.site}/browse/{key}{points_note}")
+
+    async def add_comment(self, args: dict) -> dict:
+        key = str(args.get("key", "")).strip().upper()
+        comment = await self._request("POST", f"/rest/api/3/issue/{key}/comment", {"body": _adf(str(args.get("body", "")))})
+        self.store.add_artifact(self.task.task_id, "jira_comment", f"{key}/comment/{comment.get('id')}", f"{self.site}/browse/{key}")
+        return _text(f"commented on {key}")
+
+    async def assign_issue(self, args: dict) -> dict:
+        key = str(args.get("key", "")).strip().upper()
+        account_id = str(args.get("account_id", "")).strip()
+        await self._request("PUT", f"/rest/api/3/issue/{key}/assignee", {"accountId": account_id})
+        self.store.add_event(self.task.task_id, "tool_call", {"jira_assignment": f"{key} -> {account_id}"}, tool_name="mcp__jira__assign_issue", is_write=True)
+        return _text(f"assigned {key} to account {account_id}")
+
+    async def move_to_sprint(self, args: dict) -> dict:
+        key = str(args.get("key", "")).strip().upper()
+        sprint_id = int(args.get("sprint_id") or 0)
+        await self._request("POST", f"/rest/agile/1.0/sprint/{sprint_id}/issue", {"issues": [key]})
+        self.store.add_event(self.task.task_id, "tool_call", {"jira_sprint": f"{key} -> {sprint_id}"}, tool_name="mcp__jira__move_to_sprint", is_write=True)
+        return _text(f"moved {key} to sprint {sprint_id}")
+
+    async def set_epic(self, args: dict) -> dict:
+        key = str(args.get("key", "")).strip().upper()
+        epic_key = str(args.get("epic_key", "")).strip().upper()
+        await self._request("PUT", f"/rest/api/3/issue/{key}", {"fields": {"parent": {"key": epic_key}}})
+        self.store.add_event(self.task.task_id, "tool_call", {"jira_epic": f"{key} -> {epic_key}"}, tool_name="mcp__jira__set_epic", is_write=True)
+        return _text(f"set {epic_key} as the epic for {key}")
+
+    async def set_story_points(self, args: dict) -> dict:
+        if not self.story_points_field:
+            return _error("story points field is not configured — set jira.story_points_field")
+        key = str(args.get("key", "")).strip().upper()
+        points = float(args.get("points") or 0)
+        await self._request("PUT", f"/rest/api/3/issue/{key}", {"fields": {self.story_points_field: points}})
+        self.store.add_event(self.task.task_id, "tool_call", {"jira_story_points": f"{key} -> {points}"}, tool_name="mcp__jira__set_story_points", is_write=True)
+        return _text(f"set {key} story points to {points:g}")
+
+    async def transition_issue(self, args: dict) -> dict:
+        key = str(args.get("key", "")).strip().upper()
+        wanted = str(args.get("transition", "")).strip().lower()
+        data = await self._request("GET", f"/rest/api/3/issue/{key}/transitions")
+        match = next((t for t in data.get("transitions") or [] if str(t.get("name", "")).lower() == wanted), None)
+        if match is None:
+            names = [t.get("name") for t in data.get("transitions") or []]
+            return _error(f"transition {wanted!r} is not available for {key}; available: {names}")
+        await self._request("POST", f"/rest/api/3/issue/{key}/transitions", {"transition": {"id": match["id"]}})
+        self.store.add_event(self.task.task_id, "tool_call", {"jira_transition": f"{key} -> {match.get('name')}"}, tool_name="mcp__jira__transition_issue", is_write=True)
+        return _text(f"transitioned {key} to {match.get('name')}")
+
+    async def link_pr(self, args: dict) -> dict:
+        """attach a github pull request to a jira issue as a remote link (JIR-005, GIT-013)."""
+        key = str(args.get("key", "")).strip().upper()
+        url = str(args.get("pr_url", "")).strip()
+        if not url.startswith("https://github.com/"):
+            return _error("pr_url must be a github pull request url")
+        await self._request("POST", f"/rest/api/3/issue/{key}/remotelink", {"object": {"url": url, "title": str(args.get("title", "")) or url}})
+        self.store.add_artifact(self.task.task_id, "jira_link", f"{key} -> {url}", url)
+        return _text(f"linked {url} to {key}")
+
+    # -- plumbing ------------------------------------------------------------------
+
+    def _record_issue(self, key: str) -> None:
+        self.store.add_artifact(self.task.task_id, "jira_issue", key, f"{self.site}/browse/{key}")
+
+    async def _request(self, method: str, path: str, payload: dict | None = None, params: dict | None = None) -> dict:
+        """the http seam — patched in unit tests. basic auth with the service-account token (TOL-007)."""
+        import aiohttp
+
+        auth = aiohttp.BasicAuth(self.email, self.api_token)
+        async with aiohttp.ClientSession(auth=auth) as session:
+            async with session.request(method, self.site + path, json=payload, params=params, headers={"Accept": "application/json"}) as response:
+                if response.status >= 300:
+                    body = redactor.redact(await response.text())[:300]
+                    raise RuntimeError(f"jira api {method} {path} failed: {response.status} — {body}")
+                return await response.json() if response.status != 204 else {}
+
+
+def _adf(text: str) -> dict:
+    """minimal atlassian document format: one paragraph per text block."""
+    paragraphs = [{"type": "paragraph", "content": [{"type": "text", "text": block}]} for block in text.split("\n\n") if block.strip()]
+    return {"type": "doc", "version": 1, "content": paragraphs or [{"type": "paragraph", "content": [{"type": "text", "text": " "}]}]}
+
+
+def _adf_to_text(node) -> str:
+    """flatten adf to plain text for bounded model context (TOL-006)."""
+    if node is None:
+        return ""
+    if isinstance(node, dict):
+        own = node.get("text", "")
+        children = "".join(_adf_to_text(child) for child in node.get("content") or [])
+        suffix = "\n" if node.get("type") in ("paragraph", "heading") else ""
+        return f"{own}{children}{suffix}"
+    return ""
+
+
+def build_jira_server(adapter: JiraAdapter):
+    from claude_agent_sdk import create_sdk_mcp_server, tool
+
+    tools = [
+        tool("search_issues", "Search Jira issues with JQL.", {"jql": str, "max_results": int})(wrap(adapter.search_issues, logger)),
+        tool("search_users", "Search Jira users and return account ids for assignment.", {"query": str})(wrap(adapter.search_users, logger)),
+        tool("get_issue", "Get one Jira issue (summary, status, description, labels).", {"key": str})(wrap(adapter.get_issue, logger)),
+        tool(
+            "list_boards",
+            "List Jira boards, optionally for one project.",
+            {"type": "object", "properties": {"project": {"type": "string"}}, "required": []},
+        )(wrap(adapter.list_boards, logger)),
+        tool("list_sprints", "List active and future sprints on a Jira board.", {"board_id": int})(wrap(adapter.list_sprints, logger)),
+        tool(
+            "create_issue",
+            "Create a Jira issue in an approved project. Search for duplicates first.",
+            {
+                "type": "object",
+                "properties": {
+                    "project": {"type": "string"},
+                    "issue_type": {"type": "string"},
+                    "summary": {"type": "string"},
+                    "description": {"type": "string"},
+                    "assignee_account_id": {"type": "string"},
+                    "parent_key": {"type": "string"},
+                    "story_points": {"type": "number"},
+                },
+                "required": ["project", "issue_type", "summary", "description"],
+            },
+        )(wrap(adapter.create_issue, logger)),
+        tool("add_comment", "Add a comment to a Jira issue.", {"key": str, "body": str})(wrap(adapter.add_comment, logger)),
+        tool("assign_issue", "Assign a Jira issue using an account id from search_users.", {"key": str, "account_id": str})(wrap(adapter.assign_issue, logger)),
+        tool("transition_issue", "Move a Jira issue through its workflow (e.g. 'In Progress', 'Done').", {"key": str, "transition": str})(wrap(adapter.transition_issue, logger)),
+        tool("move_to_sprint", "Move a Jira issue into a sprint.", {"key": str, "sprint_id": int})(wrap(adapter.move_to_sprint, logger)),
+        tool("set_epic", "Set the epic parent for a Jira story.", {"key": str, "epic_key": str})(wrap(adapter.set_epic, logger)),
+        tool("set_story_points", "Set the story point estimate on a Jira issue.", {"key": str, "points": float})(wrap(adapter.set_story_points, logger)),
+        tool("link_pr", "Attach a GitHub pull request link to a Jira issue.", {"key": str, "pr_url": str, "title": str})(wrap(adapter.link_pr, logger)),
+    ]
+    return create_sdk_mcp_server(name="jira", version="1.0.0", tools=tools)

taskboy/adapters/sentry.py

@@ -0,0 +1,82 @@
+"""sentry diagnostics as read-only in-process mcp tools (SEN-001..006).
+
+strictly read-only in v1 (SEN-003): the adapter implements no write operations at all.
+event payloads are aggressively trimmed before entering model context (TOL-006, SEN-005).
+every access is attributable via the tool-call audit trail (SEN-006).
+"""
+
+import json
+import logging
+
+from taskboy.adapters._util import _error, _text, wrap
+from taskboy.models import Task
+from taskboy.redact import redactor
+from taskboy.store import Store
+
+logger = logging.getLogger("taskboy.sentry")
+
+SENTRY_API = "https://sentry.io/api/0"
+
+
+class SentryAdapter:
+    def __init__(self, store: Store, task: Task, organization: str, token: str, projects: list[str]):
+        self.store = store
+        self.task = task
+        self.organization = organization
+        self.token = token
+        self.projects = projects
+
+    async def list_issues(self, args: dict) -> dict:
+        project = str(args.get("project", "")).strip()
+        if self.projects and project not in self.projects:
+            return _error(f"project {project!r} is not on the approved list {self.projects}")
+        params = {"query": str(args.get("query", "is:unresolved")), "limit": str(min(int(args.get("limit", 10)), 20)), "sort": "freq"}
+        issues = await self._request(f"/projects/{self.organization}/{project}/issues/", params)
+        lines = [f"{i.get('shortId')} [{i.get('id')}]: {str(i.get('title', ''))[:120]} | {i.get('count')} events, {i.get('userCount')} users | last {i.get('lastSeen')}" for i in issues[:20]]
+        return _text("\n".join(lines) or "no issues matched")
+
+    async def get_issue(self, args: dict) -> dict:
+        issue = await self._request(f"/issues/{str(args.get('issue_id', '')).strip()}/", {})
+        summary = {key: issue.get(key) for key in ("shortId", "title", "culprit", "level", "status", "count", "userCount", "firstSeen", "lastSeen", "permalink")}
+        summary["project"] = (issue.get("project") or {}).get("slug")
+        return _text(json.dumps(summary, ensure_ascii=False))
+
+    async def get_latest_event(self, args: dict) -> dict:
+        """the stack trace, trimmed to what an investigation needs (SEN-002, SEN-005)."""
+        event = await self._request(f"/issues/{str(args.get('issue_id', '')).strip()}/events/latest/", {})
+        lines = [f"title: {event.get('title')}", f"message: {str(event.get('message', ''))[:300]}"]
+        for entry in event.get("entries") or []:
+            if entry.get("type") != "exception":
+                continue
+            for value in (entry.get("data") or {}).get("values") or []:
+                lines.append(f"exception: {value.get('type')}: {str(value.get('value', ''))[:200]}")
+                frames = ((value.get("stacktrace") or {}).get("frames") or [])[-12:]
+                for frame in frames:
+                    marker = " (in app)" if frame.get("inApp") else ""
+                    lines.append(f"  {frame.get('filename')}:{frame.get('lineNo')} in {frame.get('function')}{marker}")
+        tags = {tag.get("key"): tag.get("value") for tag in (event.get("tags") or [])[:12]}
+        lines.append(f"tags: {json.dumps(tags, ensure_ascii=False)}")
+        return _text("\n".join(lines))
+
+    async def _request(self, path: str, params: dict):
+        """the http seam — patched in unit tests."""
+        import aiohttp
+
+        headers = {"Authorization": f"Bearer {self.token}"}
+        async with aiohttp.ClientSession(headers=headers) as session:
+            async with session.get(SENTRY_API + path, params=params) as response:
+                if response.status >= 300:
+                    body = redactor.redact(await response.text())[:300]
+                    raise RuntimeError(f"sentry api GET {path} failed: {response.status} — {body}")
+                return await response.json()
+
+
+def build_sentry_server(adapter: SentryAdapter):
+    from claude_agent_sdk import create_sdk_mcp_server, tool
+
+    tools = [
+        tool("list_issues", "List Sentry issues in an approved project (query uses Sentry search syntax).", {"project": str, "query": str, "limit": int})(wrap(adapter.list_issues, logger)),
+        tool("get_issue", "Get one Sentry issue's summary by numeric id.", {"issue_id": str})(wrap(adapter.get_issue, logger)),
+        tool("get_latest_event", "Get the latest event for a Sentry issue: exception, stack trace, tags.", {"issue_id": str})(wrap(adapter.get_latest_event, logger)),
+    ]
+    return create_sdk_mcp_server(name="sentry", version="1.0.0", tools=tools)

taskboy/adapters/slack_history.py

@@ -0,0 +1,204 @@
+"""task-channel-scoped Slack history as a read-only in-process mcp tool."""
+
+import json
+import logging
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+
+from taskboy.adapters._util import _error, _text, wrap
+from taskboy.models import Task
+from taskboy.mrkdwn import to_mrkdwn
+from taskboy.redact import redactor
+from taskboy.slack_users import cached_user_profile
+from taskboy.store import Store
+
+logger = logging.getLogger("taskboy.slack_history")
+
+HISTORY_MAX_LIMIT = 50
+HISTORY_DEFAULT_LIMIT = 20
+FILE_MAX_BYTES = 20 * 1024 * 1024
+INLINE_TEXT_MAX_BYTES = 50 * 1024
+INLINE_TEXT_MAX_CHARS = 3000
+TEXT_FILETYPES = {"csv", "html", "javascript", "json", "log", "markdown", "python", "shell", "text", "xml", "yaml"}
+
+
+class SlackHistoryAdapter:
+    def __init__(self, store: Store, task: Task, client, allowed_channels: list[str] | None = None, files_dir: str | Path | None = None):
+        self.store = store
+        self.task = task
+        self.client = client
+        self.allowed_channels = allowed_channels or []
+        self.files_dir = Path(files_dir) if files_dir is not None else None
+
+    async def channel_history(self, args: dict) -> dict:
+        oldest = str(args.get("oldest") or "") or None
+        latest = str(args.get("latest") or "") or None
+        cursor = str(args.get("cursor") or "") or None
+        limit = min(max(int(args.get("limit", HISTORY_DEFAULT_LIMIT)), 1), HISTORY_MAX_LIMIT)
+        self.store.add_event(self.task.task_id, "tool_call", {"oldest": oldest, "latest": latest, "limit": limit, "cursor": cursor}, tool_name="mcp__slack__channel_history", is_write=False)
+        data = await self._fetch(oldest, latest, limit, cursor)
+        lines = []
+        for message in reversed(data.get("messages") or []):
+            content = _message_content(message)
+            if not content:
+                continue
+            lines.append(f"[{_iso(message.get('ts'))}] <@{message.get('user', '')}>: {content}")
+        next_cursor = str((data.get("response_metadata") or {}).get("next_cursor") or "")
+        if next_cursor:
+            lines.append(f"more: pass cursor={next_cursor}")
+        return _text("\n".join(lines) or "no messages matched")
+
+    async def thread_replies(self, args: dict) -> dict:
+        channel = str(args.get("channel") or self.task.slack_channel_id)
+        if channel != self.task.slack_channel_id and channel not in self.allowed_channels:
+            return _error(f"channel {channel!r} is not allowed for this task")
+        thread_ts = str(args.get("thread_ts") or "")
+        if not thread_ts:
+            return _error("thread_ts is required")
+        limit = min(max(int(args.get("limit", HISTORY_DEFAULT_LIMIT)), 1), HISTORY_MAX_LIMIT)
+        self.store.add_event(self.task.task_id, "tool_call", {"channel": channel, "thread_ts": thread_ts, "limit": limit}, tool_name="mcp__slack__thread_replies", is_write=False)
+        data = await self.client.conversations_replies(channel=channel, ts=thread_ts, limit=limit)
+        lines = []
+        for message in data.get("messages") or []:
+            content = _message_content(message)
+            if content:
+                lines.append(f"[{_iso(message.get('ts'))}] <@{message.get('user', '')}>: {content}")
+        return _text("\n".join(lines) or "no messages matched")
+
+    async def get_file(self, args: dict) -> dict:
+        file_id = str(args.get("file_id") or "").strip()
+        if not file_id:
+            return _error("file_id is required")
+        self.store.add_event(self.task.task_id, "tool_call", {"file_id": file_id}, tool_name="mcp__slack__get_file", is_write=False)
+        if self.files_dir is None:
+            return _error("file downloads are not available for this task")
+        data = await self.client.files_info(file=file_id)
+        file = data.get("file") or {}
+        shared_channels = {str(channel) for channel in (file.get("channels") or []) + (file.get("groups") or []) + (file.get("ims") or [])}
+        readable_channels = {self.task.slack_channel_id, *self.allowed_channels}
+        if not shared_channels.intersection(readable_channels):
+            return _error(f"file {file_id} is not shared in a channel this task may read")
+        size = int(file.get("size") or 0)
+        if size > FILE_MAX_BYTES:
+            return _error(f"file {file_id} is larger than the 20 MB download limit")
+        url = str(file.get("url_private_download") or file.get("url_private") or "")
+        if not url:
+            return _error(f"file {file_id} has no download url")
+        content = await self._download_file(url)
+        if len(content) > FILE_MAX_BYTES:
+            return _error(f"file {file_id} is larger than the 20 MB download limit")
+        name = str(file.get("name") or file.get("title") or "file")
+        safe_name = re.sub(r"[/\\\\\x00]+", "_", name).strip() or "file"
+        self.files_dir.mkdir(parents=True, exist_ok=True)
+        destination = self.files_dir / f"{file_id}-{safe_name}"
+        destination.write_bytes(content)
+        relative_path = f"{self.files_dir.name}/{destination.name}"
+        mimetype = str(file.get("mimetype") or "application/octet-stream")
+        result = f"saved {relative_path} (name={name}, type={mimetype}, size={len(content)})"
+        filetype = str(file.get("filetype") or "").lower()
+        if len(content) <= INLINE_TEXT_MAX_BYTES and (mimetype.startswith("text/") or filetype in TEXT_FILETYPES):
+            result += f"\n\ncontent:\n{content.decode('utf-8', errors='replace')[:INLINE_TEXT_MAX_CHARS]}"
+        return _text(result)
+
+    async def user_info(self, args: dict) -> dict:
+        user_id = str(args.get("user") or "")
+        if not user_id:
+            return _error("user is required")
+        self.store.add_event(self.task.task_id, "tool_call", {"user": user_id}, tool_name="mcp__slack__user_info", is_write=False)
+        profile = self.store.get_slack_user(user_id)
+        try:
+            profile = await cached_user_profile(self.store, self.client, user_id)
+        except Exception as e:
+            self.store.add_error("slack", type(e).__name__, str(e), task_id=self.task.task_id, context={"operation": "users_info", "user_id": user_id})
+            if profile is None:
+                raise
+        return _text(json.dumps(profile, sort_keys=True))
+
+    async def send_dm(self, args: dict) -> dict:
+        user_id = str(args.get("user") or "").strip()
+        message = str(args.get("message") or "").strip()
+        if not user_id:
+            return _error("user is required")
+        if not message:
+            return _error("message is required")
+        self.store.add_event(self.task.task_id, "tool_call", {"user": user_id}, tool_name="mcp__slack__send_dm", is_write=True)
+        try:
+            opened = await self.client.conversations_open(users=user_id)
+            channel_id = str((opened.get("channel") or {}).get("id") or "")
+            if not channel_id:
+                raise RuntimeError("slack did not return a dm channel")
+            await self.client.chat_postMessage(channel=channel_id, text=redactor.redact(to_mrkdwn(message)))
+        except Exception as e:
+            self.store.add_error("slack", type(e).__name__, str(e), task_id=self.task.task_id, context={"operation": "send_dm", "user_id": user_id})
+            return _error(str(e))
+        return _text(f"sent a direct message to <@{user_id}>")
+
+    async def _fetch(self, oldest, latest, limit, cursor) -> dict:
+        kwargs = {"channel": self.task.slack_channel_id, "limit": limit}
+        if oldest:
+            kwargs["oldest"] = oldest
+        if latest:
+            kwargs["latest"] = latest
+        if cursor:
+            kwargs["cursor"] = cursor
+        return await self.client.conversations_history(**kwargs)
+
+    async def _download_file(self, url: str) -> bytes:
+        import aiohttp
+
+        headers = {"Authorization": f"Bearer {self.client.token}"}
+        async with aiohttp.ClientSession() as session:
+            async with session.get(url, headers=headers) as response:
+                if response.status >= 300:
+                    raise RuntimeError(redactor.redact(f"slack file download failed: {response.status}"))
+                return await response.read()
+
+
+def _iso(value) -> str:
+    try:
+        return datetime.fromtimestamp(float(value), timezone.utc).isoformat()
+    except (TypeError, ValueError, OSError):
+        return str(value or "")
+
+
+def _message_content(message: dict) -> str:
+    parts = []
+    text = str(message.get("text") or "").strip()
+    if text:
+        parts.append(text)
+    for file in message.get("files") or []:
+        parts.append(f"(file: {file.get('name')} id={file.get('id')} type={file.get('mimetype')})")
+    return " ".join(parts)
+
+
+def build_slack_server(adapter: SlackHistoryAdapter):
+    from claude_agent_sdk import create_sdk_mcp_server, tool
+
+    channel_history = tool(
+        "channel_history",
+        "Read only the Slack channel this task originated in. Thread replies appear only as parents; page older history with cursor or oldest.",
+        {"oldest": str, "latest": str, "limit": int, "cursor": str},
+    )(wrap(adapter.channel_history, logger))
+    thread_replies = tool(
+        "thread_replies",
+        "Read one Slack thread in the originating channel or another configured allowed channel.",
+        {
+            "type": "object",
+            "properties": {"channel": {"type": "string"}, "thread_ts": {"type": "string"}, "limit": {"type": "integer"}},
+            "required": ["thread_ts"],
+        },
+    )(wrap(adapter.thread_replies, logger))
+    user_info = tool("user_info", "Look up a Slack user's cached profile, refreshing it when stale.", {"user": str})(wrap(adapter.user_info, logger))
+    get_file = tool(
+        "get_file",
+        "Download a file attached to a Slack message in an allowed channel into the workspace (slack_files/) so it can be inspected. Pass the file id shown in channel_history/thread_replies output.",
+        {"file_id": str},
+    )(wrap(adapter.get_file, logger))
+    send_dm = tool(
+        "send_dm",
+        "Send a Slack direct message only when the task genuinely calls for contacting that user directly.",
+        {"user": str, "message": str},
+    )(wrap(adapter.send_dm, logger))
+    tools = [channel_history, thread_replies, user_info, get_file, send_dm]
+    return create_sdk_mcp_server(name="slack", version="1.0.0", tools=tools)

taskboy/assets.py

@@ -0,0 +1,27 @@
+"""locations of the assets shipped inside the installed package (wheel or editable checkout).
+
+templates/ holds the seed material the wizard and operators copy out (config example,
+personalities, skill templates, slack manifest); deploy/ holds the host runtime files
+(systemd units, env example, git credential helper); ui_dist/ is the built dashboard.
+"""
+
+import shutil
+from importlib.resources import files
+from pathlib import Path
+
+PACKAGE_ROOT = Path(str(files("taskboy")))
+TEMPLATES_ROOT = PACKAGE_ROOT / "templates"
+DEPLOY_ROOT = PACKAGE_ROOT / "deploy"
+UI_DIST = PACKAGE_ROOT / "ui_dist"
+GIT_CRED_HELPER = DEPLOY_ROOT / "git-cred-helper.py"
+
+EXTRACTABLE = {"templates": TEMPLATES_ROOT, "deploy": DEPLOY_ROOT}
+
+
+def extract(name: str, destination: str) -> Path:
+    """copy a packaged asset tree (templates | deploy) into destination and return the new path."""
+    source = EXTRACTABLE[name]
+    target = Path(destination) / name
+    # pip byte-compiles installed .py files (the git credential helper); don't ship the cache
+    shutil.copytree(source, target, dirs_exist_ok=True, ignore=shutil.ignore_patterns("__pycache__", "*.pyc"))
+    return target