xyne-plugin-spaces 0.1.0

package/bun.lock

@@ -0,0 +1,21 @@
+{
+  "lockfileVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "xyne-spaces",
+      "dependencies": {
+        "xyne-plugin": "^1.2.0",
+      },
+      "devDependencies": {
+        "typescript": "^5.9.3",
+      },
+    },
+  },
+  "packages": {
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "xyne-plugin": ["xyne-plugin@1.2.0", "", { "dependencies": { "zod": "^3.25.0" } }, "sha512-ecJJFMka/KvOlhF28CcRVfgmfHv6kE8JIn3cUlUCQ39b2j+9asM+/z5TOGkGHOXqSbtd5hl36zgtgvq8EA6h7A=="],
+
+    "zod": ["zod@3.25.76", "", {}, "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ=="],
+  }
+}

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "xyne-plugin-spaces",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "xyne-plugin": "^1.2.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

package/src/auth.ts

@@ -0,0 +1,105 @@
+/**
+ * Spaces auth — custom auth via localhost Electron server.
+ *
+ * Flow: POST /auth/request → Electron shows consent dialog → token returned.
+ * Token is stored in memory only — user re-approves each Xyne session.
+ */
+
+import type { ToolAuthConfig, ServiceCredentials } from "xyne-plugin"
+
+const BASE = "http://127.0.0.1:49231"
+
+// In-memory only — no disk persistence
+let _cached: ServiceCredentials | undefined
+
+export const spacesAuth: ToolAuthConfig = {
+  serviceID: "spaces",
+  label: "Spaces",
+  storage: {
+    async get() { return _cached },
+    async set(entry) { _cached = entry },
+    async remove() { _cached = undefined },
+  },
+  methods: [
+    {
+      type: "custom" as const,
+      label: "Connect to Spaces",
+      pendingMessage: "Approve the connection in the Spaces desktop app",
+      pendingHint: "Waiting for approval... · esc cancel",
+      async authorize() {
+        const response = await fetch(`${BASE}/auth/request`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            agentName: "Xyne",
+            agentType: "cli",
+            description: "Xyne CLI agent requesting access to search and memory",
+          }),
+        })
+
+        if (!response.ok) {
+          return { type: "failed" as const }
+        }
+
+        const data = (await response.json()) as {
+          status: string
+          accessToken?: string
+          expiresAt?: number
+        }
+
+        if (data.status !== "approved" || !data.accessToken) {
+          return { type: "failed" as const }
+        }
+
+        return {
+          type: "success" as const,
+          data: {
+            accessToken: data.accessToken,
+            expiresAt: data.expiresAt ?? Date.now() + 5 * 60 * 1000,
+          },
+        }
+      },
+    },
+  ],
+
+  async refresh(entry: ServiceCredentials) {
+    if (entry.type !== "custom") throw new Error("Expected custom credentials")
+    const expiresAt = entry.data["expiresAt"] as number | undefined
+    if (expiresAt && Date.now() < expiresAt) return entry
+    throw new Error("Token expired")
+  },
+}
+
+const log = (msg: string) => {
+  try { require("fs").appendFileSync("/tmp/tui-spaces-debug.log", `[${new Date().toISOString()}] ${msg}\n`) } catch {}
+}
+
+/** Make an authenticated request to the Spaces server. */
+export async function spacesFetch(
+  path: string,
+  accessToken: string,
+  init?: RequestInit,
+): Promise<unknown> {
+  const url = `${BASE}${path}`
+  const method = init?.method ?? "GET"
+  log(`${method} ${path}${init?.body ? ` body=${String(init.body).slice(0, 500)}` : ""}`)
+
+  const response = await fetch(url, {
+    ...init,
+    headers: {
+      Authorization: `Bearer ${accessToken}`,
+      "Content-Type": "application/json",
+      ...(init?.headers as Record<string, string> | undefined),
+    },
+  })
+
+  if (!response.ok) {
+    const text = await response.text()
+    log(`ERROR ${response.status}: ${text.slice(0, 500)}`)
+    throw new Error(`Spaces API ${response.status}: ${text}`)
+  }
+
+  const data = await response.json()
+  log(`OK ${response.status} (${JSON.stringify(data).length} bytes)`)
+  return data
+}

package/src/index.ts

@@ -0,0 +1,371 @@
+import { type Plugin, tool, z } from "xyne-plugin"
+import { spacesAuth, spacesFetch } from "./auth"
+import { queryTickets, queryMessages, queryMessageDetail, queryChannels, queryUsers, queryUserActivity } from "./query"
+
+function getToken(ctx: { credentials?: { type: string; data?: Record<string, unknown> } }): string {
+  const creds = ctx.credentials
+  if (!creds || creds.type !== "custom") throw new Error("Expected Spaces credentials")
+  return creds.data!["accessToken"] as string
+}
+
+// ── Vespa Search ─────────────────────────────────────────────────────
+
+const spacesSearch = tool({
+  description:
+    "Search across all connected apps in Spaces — messages, tickets, files, channels, users. " +
+    "Supports filters like app, type, date range, priority, status, tags, and more.",
+  auth: spacesAuth,
+  args: {
+    query: z.string().describe("Search query text. Can be empty if filterOnly is true."),
+    apps: z.string().optional().describe("Comma-separated apps to search: chat, ticket, user, file (default: all)"),
+    type: z.string().optional().describe("Filter by type: messages, attachments, channels, tickets, files"),
+    from: z.string().optional().describe("Filter by sender user ID(s), comma-separated"),
+    in: z.string().optional().describe("Filter by channel ID(s), comma-separated"),
+    status: z.string().optional().describe("Filter by ticket status(es), comma-separated"),
+    priority: z.enum(["HIGH", "MEDIUM", "LOW", "CRITICAL"]).optional().describe("Filter by ticket priority"),
+    board: z.string().optional().describe("Filter by board name"),
+    tags: z.string().optional().describe("Filter by tags, comma-separated"),
+    stage: z.string().optional().describe("Filter by ticket stage"),
+    assignee: z.string().optional().describe("Filter by assigned user ID"),
+    before: z.string().optional().describe("Created before date (e.g. '15 Mar 26' or ISO format)"),
+    after: z.string().optional().describe("Created after date"),
+    range: z.string().optional().describe("Time range: today, yesterday, this week, last 7 days, last 30 days"),
+    filterOnly: z.boolean().optional().describe("Set true to search with filters only, no query text required"),
+    limit: z.number().min(1).max(50).default(10).describe("Max results per group (default 10)"),
+    offset: z.number().min(0).default(0).describe("Pagination offset (default 0)"),
+  },
+  async execute(args, ctx) {
+    const token = getToken(ctx)
+    const params = new URLSearchParams()
+    params.set("q", args.query)
+    params.set("limit", String(args.limit))
+    if (args.offset > 0) params.set("offset", String(args.offset))
+    if (args.apps) params.set("apps", args.apps)
+    if (args.type) params.set("type", args.type)
+    if (args.from) params.set("from", args.from)
+    if (args.in) params.set("in", args.in)
+    if (args.status) params.set("status", args.status)
+    if (args.priority) params.set("priority", args.priority)
+    if (args.board) params.set("board", args.board)
+    if (args.tags) params.set("tags", args.tags)
+    if (args.stage) params.set("stage", args.stage)
+    if (args.assignee) params.set("assignee", args.assignee)
+    if (args.before) params.set("before", args.before)
+    if (args.after) params.set("after", args.after)
+    if (args.range) params.set("range", args.range)
+    if (args.filterOnly) params.set("filterOnly", "true")
+
+    const data = (await spacesFetch(`/search?${params}`, token)) as {
+      success: boolean
+      data?: {
+        grouped: boolean
+        groups?: Array<{ groupValue: string; count: number; results: Array<SearchResult> }>
+        results?: SearchResult[]
+        totalCount?: number
+      }
+    }
+
+    if (!data.success || !data.data) return "Search failed."
+
+    if (data.data.grouped && data.data.groups) {
+      const groups = data.data.groups
+      if (groups.length === 0) return `No results found for "${args.query}".`
+      const parts: string[] = []
+      for (const group of groups) {
+        parts.push(`--- ${group.groupValue} (${group.count}) ---`)
+        for (const r of group.results) parts.push(formatSearchResult(r))
+        parts.push("")
+      }
+      return parts.join("\n")
+    }
+
+    const results = data.data.results ?? []
+    if (results.length === 0) return `No results found for "${args.query}".`
+    return `Found ${data.data.totalCount ?? results.length} result(s):\n\n${results.map(formatSearchResult).join("\n\n")}`
+  },
+})
+
+interface SearchResult {
+  id: string; type: string; title: string; subtitle?: string; context?: string
+  metadata?: Record<string, unknown>; searchContext?: Record<string, unknown>
+}
+
+function formatSearchResult(r: SearchResult): string {
+  const lines = [`[${r.type}] ${r.title}${r.subtitle ? ` — ${r.subtitle}` : ""}`]
+  if (r.context) lines.push(`  ${r.context.replace(/<\/?[^>]+>/g, "").slice(0, 300)}`)
+  const meta = r.metadata
+  if (meta) {
+    const p: string[] = []
+    if (meta["timestamp"]) p.push(`${meta["timestamp"]}`)
+    if (meta["channelName"]) p.push(`#${meta["channelName"]}`)
+    if (meta["status"]) p.push(`status: ${meta["status"]}`)
+    if (p.length > 0) lines.push(`  ${p.join(" · ")}`)
+  }
+  const sc = r.searchContext
+  if (sc) {
+    if (sc["senderName"]) lines.push(`  From: ${sc["senderName"]}`)
+    if (sc["xyneId"]) lines.push(`  ID: ${sc["xyneId"]}`)
+  }
+  return lines.join("\n")
+}
+
+// ── Memory Search ────────────────────────────────────────────────────
+
+const memorySearch = tool({
+  description: "Search Spaces memory — facts, SOPs, and knowledge base entries from past sessions.",
+  auth: spacesAuth,
+  args: {
+    query: z.string().optional().describe("Search query (leave empty to list recent)"),
+    scope: z.enum(["my", "all"]).default("my").describe("'my' for your items, 'all' for team-wide"),
+    limit: z.number().min(1).max(50).default(10).describe("Max results"),
+    offset: z.number().min(0).default(0).describe("Pagination offset"),
+    docType: z.enum(["fact", "sop"]).optional().describe("Filter by type"),
+    tags: z.array(z.string()).optional().describe("Filter by tags"),
+    reviewStatus: z.enum(["pending", "verified", "rejected"]).optional().describe("Filter by review status"),
+  },
+  async execute(args, ctx) {
+    const token = getToken(ctx)
+    const body: Record<string, unknown> = { scope: args.scope, limit: args.limit, offset: args.offset, includeSummary: true, includeQuery: true }
+    if (args.query) body["query"] = args.query
+    if (args.docType) body["docType"] = args.docType
+    if (args.tags) body["tags"] = args.tags
+    if (args.reviewStatus) body["reviewStatus"] = args.reviewStatus
+
+    const data = (await spacesFetch("/memory/search", token, { method: "POST", body: JSON.stringify(body) })) as {
+      success?: boolean; data?: { documents?: Array<{ docId: string; docType: string; userQuery?: string; chatSummary?: string[]; rawContent?: string; tags?: string[]; reviewStatus?: string; createdAt?: number }>; pagination?: { total: number } }
+    }
+
+    const docs = data.data?.documents ?? []
+    if (docs.length === 0) return args.query ? `No memory results for "${args.query}".` : "No memory entries found."
+    const parts = docs.map((d) => {
+      const lines = [`[${d.docType}] ${d.docId}`]
+      if (d.userQuery) lines.push(`  Query: ${d.userQuery}`)
+      if (d.chatSummary?.length) lines.push(`  Summary: ${d.chatSummary.join(" ")}`)
+      else if (d.rawContent) lines.push(`  ${d.rawContent.slice(0, 300)}${d.rawContent.length > 300 ? "..." : ""}`)
+      if (d.tags?.length) lines.push(`  Tags: ${d.tags.join(", ")}`)
+      if (d.reviewStatus) lines.push(`  Review: ${d.reviewStatus}`)
+      return lines.join("\n")
+    })
+    return `Found ${data.data?.pagination?.total ?? docs.length} result(s):\n\n${parts.join("\n\n")}`
+  },
+})
+
+// ── Tickets ──────────────────────────────────────────────────────────
+
+const spacesTickets = tool({
+  description:
+    "List and filter tickets in Spaces. Filter by status, priority, assignee, board, project, or stage. " +
+    "Returns ticket details including assignee, tags, stage, and conversation ID.",
+  auth: spacesAuth,
+  args: {
+    status: z.enum(["TODO", "STARTED", "PAUSED", "CANCELLED", "COMPLETED"]).optional().describe("Filter by status"),
+    priority: z.enum(["LOW", "MEDIUM", "HIGH", "CRITICAL"]).optional().describe("Filter by priority"),
+    assignedTo: z.string().optional().describe("Filter by assigned user's ID (use spaces-users to find user IDs)"),
+    createdBy: z.string().optional().describe("Filter by ticket creator's user ID"),
+    boardId: z.string().optional().describe("Filter by board ID (use spaces-search to find board IDs)"),
+    projectId: z.string().optional().describe("Filter by project ID (use spaces-search to find project IDs)"),
+    stageName: z.string().optional().describe("Filter by stage name"),
+    limit: z.number().min(1).max(50).default(20).describe("Max tickets (default 20)"),
+    offset: z.number().min(0).default(0).describe("Pagination offset"),
+  },
+  async execute(args, ctx) {
+    const token = getToken(ctx)
+    return queryTickets(token, args)
+  },
+})
+
+// ── Messages ─────────────────────────────────────────────────────────
+
+const spacesMessages = tool({
+  description:
+    "Read messages in a conversation thread. IMPORTANT: Use the conversationId field from spaces-tickets results (NOT the channel ID or ticket ID). " +
+    "Messages are returned in chronological order.",
+  auth: spacesAuth,
+  args: {
+    conversationId: z.string().describe("The conversationId field from spaces-tickets or spaces-activity results. This is NOT a channelId, ticketId, or messageId."),
+    limit: z.number().min(1).max(100).default(30).describe("Max messages (default 30)"),
+    offset: z.number().min(0).default(0).describe("Pagination offset"),
+  },
+  async execute(args, ctx) {
+    const token = getToken(ctx)
+    return queryMessages(token, args.conversationId, args.limit, args.offset)
+  },
+})
+
+// ── Message Detail ───────────────────────────────────────────────────
+
+const spacesMessageDetail = tool({
+  description:
+    "Get detailed information about a specific message including full content, sender details, " +
+    "reactions (with counts), and attachments. Use messageId from spaces-messages or spaces-activity results.",
+  auth: spacesAuth,
+  args: {
+    messageId: z.string().describe("The messageId field from spaces-messages or spaces-activity results. This is NOT a conversationId, channelId, or ticketId."),
+  },
+  async execute(args, ctx) {
+    const token = getToken(ctx)
+    return queryMessageDetail(token, args.messageId)
+  },
+})
+
+// ── Channels ─────────────────────────────────────────────────────────
+
+const spacesChannels = tool({
+  description:
+    "List channels in Spaces. Can filter by visibility (PUBLIC/PRIVATE) and scope type (DEFAULT/DM/TICKET/GROUP_DM). " +
+    "Returns channel name, participant count, project, and last activity.",
+  auth: spacesAuth,
+  args: {
+    visibility: z.enum(["PUBLIC", "PRIVATE"]).optional().describe("Filter by visibility"),
+    scopeType: z.enum(["DEFAULT", "DM", "TICKET", "DOCUMENT", "GROUP_DM"]).optional().describe("Filter by scope type"),
+    limit: z.number().min(1).max(50).default(20).describe("Max channels (default 20)"),
+  },
+  async execute(args, ctx) {
+    const token = getToken(ctx)
+    return queryChannels(token, args.limit, args.visibility, args.scopeType)
+  },
+})
+
+// ── Users ────────────────────────────────────────────────────────────
+
+const spacesUsers = tool({
+  description: "Look up users by name or email. Returns user ID, name, email, and type.",
+  auth: spacesAuth,
+  args: {
+    nameOrEmail: z.string().describe("Person's name to search by name, or email address (with @ or .) to search by email"),
+    limit: z.number().min(1).max(20).default(10).describe("Max results (default 10)"),
+  },
+  async execute(args, ctx) {
+    const token = getToken(ctx)
+    return queryUsers(token, args.nameOrEmail, args.limit)
+  },
+})
+
+// ── User Activity ────────────────────────────────────────────────────
+
+const spacesUserActivity = tool({
+  description:
+    "Get your activity feed — mentions, replies, assignments, and notifications. " +
+    "Returns messageId, conversationId, ticketId for each activity. " +
+    "Use conversationId with spaces-messages to read the full thread, or messageId with spaces-message-detail.",
+  auth: spacesAuth,
+  args: {
+    classification: z.string().optional().describe("Filter by classification (e.g. 'PENDING')"),
+    unreadOnly: z.boolean().optional().describe("Show only unread activity"),
+    limit: z.number().min(1).max(50).default(20).describe("Max entries (default 20)"),
+  },
+  async execute(args, ctx) {
+    const token = getToken(ctx)
+    return queryUserActivity(token, args.classification, args.unreadOnly === true ? false : undefined, args.limit)
+  },
+})
+
+// ── Web Fetch ────────────────────────────────────────────────────
+
+const spacesWebFetch = tool({
+  description:
+    "Fetch an external URL and return its content as markdown or text. " +
+    "Only use for URLs outside Xyne Spaces (e.g. GitHub PRs, docs, external links from messages). " +
+    "Do NOT use for Xyne Spaces internal URLs — use the other spaces tools instead.",
+  auth: spacesAuth,
+  args: {
+    url: z.string().describe("The URL to fetch"),
+    format: z.enum(["text", "markdown", "html"]).default("markdown").describe("Output format (default: markdown)"),
+  },
+  async execute(args) {
+    if (!args.url.startsWith("http://") && !args.url.startsWith("https://")) {
+      throw new Error("URL must start with http:// or https://")
+    }
+
+    const controller = new AbortController()
+    const timer = setTimeout(() => controller.abort(), 30_000)
+
+    try {
+      const response = await fetch(args.url, {
+        signal: controller.signal,
+        headers: {
+          "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36",
+          "Accept": "text/html;q=1.0, text/plain;q=0.8, */*;q=0.1",
+        },
+        redirect: "follow",
+      })
+      clearTimeout(timer)
+
+      if (!response.ok) throw new Error(`Fetch failed: ${response.status} ${response.statusText}`)
+
+      const contentType = response.headers.get("content-type") ?? ""
+      let text = await response.text()
+
+      if (contentType.includes("html") && args.format !== "html") {
+        // Strip scripts, styles, and tags
+        text = text
+          .replace(/<script[\s\S]*?<\/script>/gi, "")
+          .replace(/<style[\s\S]*?<\/style>/gi, "")
+          .replace(/<noscript[\s\S]*?<\/noscript>/gi, "")
+          .replace(/<[^>]+>/g, " ")
+          .replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">")
+          .replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&nbsp;/g, " ")
+          .replace(/\s+/g, " ")
+          .trim()
+      }
+
+      if (text.length > 15000) text = text.slice(0, 15000) + "\n\n... (truncated)"
+      return text
+    } finally {
+      clearTimeout(timer)
+    }
+  },
+})
+
+// ── Plugin ───────────────────────────────────────────────────────────
+
+const spacesTools = {
+  "spaces-search": spacesSearch,
+  "spaces-memory-search": memorySearch,
+  "spaces-tickets": spacesTickets,
+  "spaces-messages": spacesMessages,
+  "spaces-message-detail": spacesMessageDetail,
+  "spaces-channels": spacesChannels,
+  "spaces-users": spacesUsers,
+  "spaces-activity": spacesUserActivity,
+  "webfetch": spacesWebFetch,
+}
+
+const plugin: Plugin = async (_input) => ({
+  agent: {
+    spaces: {
+      description:
+        "Use this agent for any query about Xyne Spaces — tickets, messages, conversations, users, channels, or activity. " +
+        "Collects information and context from the Xyne Spaces app.",
+      mode: "all",
+      tools: spacesTools,
+      isolatedTools: true,
+      system: [
+        "You are a Spaces assistant with access to the user's Spaces workspace.",
+        "",
+        "## Capabilities",
+        "- **Search**: Full-text search across messages, tickets, files, channels, users",
+        "- **Memory**: Search facts, SOPs, and knowledge from past sessions",
+        "- **Tickets**: List/filter tickets by status, priority, assignee, board, stage",
+        "- **Messages**: Read conversation threads linked to tickets or channels",
+        "- **Message Detail**: Get full message with reactions and attachments",
+        "- **Channels**: Browse channels by visibility and scope",
+        "- **Users**: Look up users by name or email",
+        "- **Activity**: View user activity feed (mentions, replies, assignments)",
+        "",
+        "## Guidelines",
+        "- Use spaces-search for broad queries across all connected apps",
+        "- Use spaces-tickets for structured ticket queries with specific filters",
+        "- To read a ticket's discussion: first use spaces-tickets to get the conversationId, then use spaces-messages with that conversationId (NOT the channelId or ticket ID)",
+        "- Use spaces-users to resolve user names to IDs before filtering tickets",
+        "- Priority values: LOW, MEDIUM, HIGH, CRITICAL",
+        "- Status values: TODO, STARTED, PAUSED, CANCELLED, COMPLETED",
+        "- Date range shortcuts for search: today, yesterday, this week, last 7 days, last 30 days",
+        "- Be concise — summarize results, don't dump raw data",
+      ].join("\n"),
+      color: "#ef4444",
+    },
+  },
+})
+
+export default plugin

package/src/query.ts

@@ -0,0 +1,338 @@
+/**
+ * Spaces query helpers — build Prisma ASTs and call /interact endpoint.
+ */
+
+import { spacesFetch } from "./auth"
+
+interface QueryAST {
+  model: string
+  operation: "findMany" | "count"
+  where?: Record<string, unknown>
+  orderBy?: Record<string, string> | Array<Record<string, string>>
+  take?: number
+  skip?: number
+  include?: Record<string, unknown>
+  select?: Record<string, unknown>
+}
+
+export async function query(token: string, ast: QueryAST): Promise<unknown> {
+  const result = (await spacesFetch("/interact", token, {
+    method: "POST",
+    body: JSON.stringify(ast),
+  })) as { data: unknown }
+  return result.data
+}
+
+// ── Tickets ──────────────────────────────────────────────────────────
+
+interface TicketFilters {
+  status?: string | undefined
+  priority?: string | undefined
+  assignedTo?: string | undefined
+  createdBy?: string | undefined
+  boardId?: string | undefined
+  projectId?: string | undefined
+  stageName?: string | undefined
+  limit?: number | undefined
+  offset?: number | undefined
+}
+
+interface TicketRow {
+  id: string
+  title: string
+  xyneId: string
+  statusV2: string
+  priority: string
+  stageName?: string
+  eta?: string
+  createdAt: string
+  updatedAt: string
+  conversationId?: string
+  assignedToUser?: { name: string } | null
+  createdByUser?: { name: string } | null
+  board?: { name: string } | null
+  project?: { name: string } | null
+  tags?: Array<{ name: string }>
+}
+
+export async function queryTickets(token: string, filters: TicketFilters): Promise<string> {
+  const where: Record<string, unknown> = {}
+  if (filters.status) where["statusV2"] = { equals: filters.status }
+  if (filters.priority) where["priority"] = { equals: filters.priority }
+  if (filters.assignedTo) where["assignedTo"] = { equals: filters.assignedTo }
+  if (filters.createdBy) where["createdBy"] = { equals: filters.createdBy }
+  if (filters.boardId) where["boardId"] = { equals: filters.boardId }
+  if (filters.projectId) where["projectId"] = { equals: filters.projectId }
+  if (filters.stageName) where["stageName"] = { equals: filters.stageName }
+
+  const rows = (await query(token, {
+    model: "ticket",
+    operation: "findMany",
+    where,
+    orderBy: [{ updatedAt: "desc" }],
+    take: filters.limit ?? 20,
+    skip: filters.offset ?? 0,
+    include: {
+      assignedToUser: { select: { name: true } },
+      createdByUser: { select: { name: true } },
+      board: { select: { name: true } },
+      project: { select: { name: true } },
+      tags: { select: { name: true } },
+    },
+  })) as TicketRow[]
+
+  if (rows.length === 0) return "No tickets found."
+
+  const lines = rows.map((t) => {
+    const parts = [`[${t.xyneId}] ${t.title}`]
+    parts.push(`  Status: ${t.statusV2} · Priority: ${t.priority}${t.stageName ? ` · Stage: ${t.stageName}` : ""}`)
+    if (t.assignedToUser) parts.push(`  Assigned: ${t.assignedToUser.name}`)
+    if (t.createdByUser) parts.push(`  Created by: ${t.createdByUser.name}`)
+    if (t.board) parts.push(`  Board: ${t.board.name}${t.project ? ` · Project: ${t.project.name}` : ""}`)
+    if (t.tags && t.tags.length > 0) parts.push(`  Tags: ${t.tags.map((tg) => tg.name).join(", ")}`)
+    if (t.eta) parts.push(`  ETA: ${new Date(t.eta).toLocaleDateString()}`)
+    if (t.conversationId) parts.push(`  ConversationID: ${t.conversationId}`)
+    parts.push(`  Updated: ${new Date(t.updatedAt).toLocaleString()}`)
+    return parts.join("\n")
+  })
+
+  return `${rows.length} ticket(s):\n\n${lines.join("\n\n")}`
+}
+
+// ── Messages ─────────────────────────────────────────────────────────
+
+interface MessageRow {
+  messageId: string
+  content: string
+  msgType: string
+  createdAt: string
+  hasAttachment: boolean
+  sender?: { name: string } | null
+}
+
+export async function queryMessages(token: string, conversationId: string, limit: number, offset: number): Promise<string> {
+  const rows = (await query(token, {
+    model: "message",
+    operation: "findMany",
+    where: {
+      conversationId: { equals: conversationId },
+      isDeleted: { equals: false },
+    },
+    orderBy: [{ createdAt: "asc" }],
+    take: limit,
+    skip: offset,
+    include: {
+      sender: { select: { name: true } },
+    },
+  })) as MessageRow[]
+
+  if (rows.length === 0) return `No messages found in conversation ${conversationId}.`
+
+  const lines = rows.map((m) => {
+    const sender = m.sender?.name ?? "unknown"
+    const time = new Date(m.createdAt).toLocaleString()
+    const attach = m.hasAttachment ? " 📎" : ""
+    return `[${time}] ${sender}${attach}: ${m.content}`
+  })
+
+  return `${rows.length} message(s):\n\n${lines.join("\n")}`
+}
+
+// ── Message Detail ───────────────────────────────────────────────────
+
+interface MessageDetailRow {
+  messageId: string
+  content: string
+  msgType: string
+  createdAt: string
+  edited: boolean
+  hasAttachment: boolean
+  sender?: { name: string; email: string } | null
+  reactions?: Array<{ emojiName: string; userId: string }>
+  reactionCounts?: Array<{ emojiName: string; count: number }>
+}
+
+interface AttachmentRow {
+  id: string
+  originalFilename: string
+  mimetype: string
+  size: number
+  url: string
+}
+
+export async function queryMessageDetail(token: string, messageId: string): Promise<string> {
+  const rows = (await query(token, {
+    model: "message",
+    operation: "findMany",
+    where: { messageId: { equals: messageId } },
+    take: 1,
+    include: {
+      sender: { select: { name: true, email: true } },
+      reactions: { select: { emojiName: true, userId: true } },
+      reactionCounts: { select: { emojiName: true, count: true } },
+    },
+  })) as MessageDetailRow[]
+
+  if (rows.length === 0) return `Message ${messageId} not found.`
+  const m = rows[0]!
+
+  const parts = [
+    `Message: ${m.messageId}`,
+    `From: ${m.sender?.name ?? "unknown"} (${m.sender?.email ?? ""})`,
+    `Type: ${m.msgType}${m.edited ? " (edited)" : ""}`,
+    `Date: ${new Date(m.createdAt).toLocaleString()}`,
+    `\n${m.content}`,
+  ]
+
+  // Reactions
+  if (m.reactionCounts && m.reactionCounts.length > 0) {
+    const rxns = m.reactionCounts.map((r) => `${r.emojiName} ×${r.count}`).join("  ")
+    parts.push(`\nReactions: ${rxns}`)
+  }
+
+  // Attachments
+  if (m.hasAttachment) {
+    const attachments = (await query(token, {
+      model: "messageAttachment",
+      operation: "findMany",
+      where: { entityId: { equals: messageId } },
+      take: 20,
+    })) as AttachmentRow[]
+
+    if (attachments.length > 0) {
+      parts.push(`\nAttachments (${attachments.length}):`)
+      for (const a of attachments) {
+        const size = a.size < 1024 ? `${a.size} B` : a.size < 1024 * 1024 ? `${(a.size / 1024).toFixed(1)} KB` : `${(a.size / (1024 * 1024)).toFixed(1)} MB`
+        parts.push(`  - ${a.originalFilename} (${a.mimetype}, ${size})`)
+      }
+    }
+  }
+
+  return parts.join("\n")
+}
+
+// ── Channels ─────────────────────────────────────────────────────────
+
+interface ChannelRow {
+  id: string
+  name: string
+  description?: string
+  type: string
+  scopeType: string
+  visibility: string
+  participantCount: number
+  lastActivityAt?: string
+  project?: { name: string } | null
+}
+
+export async function queryChannels(token: string, limit: number, visibility?: string, scopeType?: string): Promise<string> {
+  const where: Record<string, unknown> = {}
+  if (visibility) where["visibility"] = { equals: visibility }
+  if (scopeType) where["scopeType"] = { equals: scopeType }
+
+  const rows = (await query(token, {
+    model: "channel",
+    operation: "findMany",
+    where,
+    orderBy: [{ lastActivityAt: "desc" }],
+    take: limit,
+    include: {
+      project: { select: { name: true } },
+    },
+  })) as ChannelRow[]
+
+  if (rows.length === 0) return "No channels found."
+
+  const lines = rows.map((c) => {
+    const parts = [`#${c.name} (${c.scopeType}, ${c.visibility})`]
+    if (c.description) parts.push(`  ${c.description}`)
+    parts.push(`  Participants: ${c.participantCount}${c.project ? ` · Project: ${c.project.name}` : ""}`)
+    if (c.lastActivityAt) parts.push(`  Last active: ${new Date(c.lastActivityAt).toLocaleString()}`)
+    parts.push(`  ID: ${c.id}`)
+    return parts.join("\n")
+  })
+
+  return `${rows.length} channel(s):\n\n${lines.join("\n\n")}`
+}
+
+// ── Users ────────────────────────────────────────────────────────────
+
+interface UserRow {
+  id: string
+  name: string
+  email: string
+  status: string
+  userType: string
+  picture?: string
+}
+
+export async function queryUsers(token: string, nameOrEmail: string, limit: number): Promise<string> {
+  // OR not supported by query validator — search by name or email based on input
+  const isEmail = nameOrEmail.includes("@") || nameOrEmail.includes(".")
+  const where = isEmail
+    ? { email: { contains: nameOrEmail }, status: { equals: "ACTIVE" } }
+    : { name: { contains: nameOrEmail }, status: { equals: "ACTIVE" } }
+
+  const rows = (await query(token, {
+    model: "user",
+    operation: "findMany",
+    where,
+    take: limit,
+  })) as UserRow[]
+
+  if (rows.length === 0) return `No users found matching "${nameOrEmail}".`
+
+  const lines = rows.map((u) => `${u.name} (${u.email}) — ${u.userType}\n  ID: ${u.id}`)
+
+  return `${rows.length} user(s):\n\n${lines.join("\n\n")}`
+}
+
+// ── User Activity ────────────────────────────────────────────────────
+
+interface UserActivityRow {
+  id: string
+  actorAction: string
+  classification?: string
+  isRead: boolean
+  createdAt: string
+  channelId?: string
+  ticketId?: string
+  conversationId?: string
+  messageId?: string
+  actorId: string
+}
+
+export async function queryUserActivity(
+  token: string,
+  classification?: string,
+  isRead?: boolean,
+  limit?: number,
+): Promise<string> {
+  const where: Record<string, unknown> = {}
+  if (classification) where["classification"] = { equals: classification }
+  if (isRead !== undefined) where["isRead"] = { equals: isRead }
+
+  const rows = (await query(token, {
+    model: "activity",
+    operation: "findMany",
+    where,
+    orderBy: [{ createdAt: "desc" }],
+    take: limit ?? 20,
+  })) as UserActivityRow[]
+
+  if (rows.length === 0) return "No activity found."
+
+  const lines = rows.map((a) => {
+    const when = new Date(a.createdAt).toLocaleString()
+    const read = a.isRead ? "" : " (unread)"
+    const refs: string[] = []
+    if (a.messageId) refs.push(`messageId: ${a.messageId}`)
+    if (a.conversationId) refs.push(`conversationId: ${a.conversationId}`)
+    if (a.ticketId) refs.push(`ticketId: ${a.ticketId}`)
+    if (a.channelId) refs.push(`channelId: ${a.channelId}`)
+    const refStr = refs.length > 0 ? `\n    ${refs.join(" · ")}` : ""
+    return `[${when}] ${a.actorAction}${read}${a.classification ? ` · ${a.classification}` : ""}${refStr}`
+  })
+
+  return `${rows.length} activity entries:\n\n${lines.join("\n")}`
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "@tsconfig/bun/tsconfig.json",
+  "compilerOptions": {
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "exactOptionalPropertyTypes": true,
+    "noUncheckedIndexedAccess": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitOverride": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules"]
+}