@nimbus-dev/connectors 0.1.0

package/connectors/powerbi/nimbus.extension.json

@@ -0,0 +1,16 @@
+{
+  "id": "com.nimbus.powerbi",
+  "displayName": "Power BI",
+  "version": "0.1.0",
+  "description": "Power BI connector. Indexes Power BI reports as `powerbi:dashboard` items in the local index and exposes three read-only tools to the Nimbus agent (`powerbi_list`, `powerbi_get`, `powerbi_search`) plus two HITL-gated write tools: `powerbi_dataset_refresh` (trigger a dataset refresh; groupId optional, omit for My Workspace) and `powerbi_dataflow_refresh` (trigger a dataflow refresh). Uses Azure AD client-credentials flow (tenant_id/client_id/client_secret) to mint an access token, then calls the Power BI REST API. Hosts are fixed well-known endpoints (login.microsoftonline.com for AAD tokens, api.powerbi.com for the API); the static manifest network list declares both hosts directly — no per-tenant host derivation is needed.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": ["login.microsoftonline.com", "api.powerbi.com"],
+    "filesystem": { "read": [], "write": [] }
+  },
+  "hitlRequired": ["write"],
+  "syncInterval": 600,
+  "minNimbusVersion": "0.5.0"
+}

package/connectors/powerbi/src/search-filter.ts

@@ -0,0 +1,22 @@
+import {
+  asRecord,
+  makeQueryFilter,
+  type SearchMatchOptions,
+} from "../../../shared/search-filter.ts";
+
+export type PowerBiSearchMatchOptions = SearchMatchOptions;
+
+function stringAt(row: Record<string, unknown>, key: string): string {
+  const v = row[key];
+  return typeof v === "string" ? v : "";
+}
+
+function fieldsOf(item: unknown): readonly string[] | null {
+  const row = asRecord(item);
+  if (row === undefined) {
+    return null;
+  }
+  return [stringAt(row, "name"), stringAt(row, "description")];
+}
+
+export const filterPowerBiReports = makeQueryFilter(fieldsOf);

package/connectors/powerbi/src/server.ts

@@ -0,0 +1,249 @@
+import { z } from "zod";
+import { type ConsentServer, createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
+import { searchToolInputSchema } from "../../../shared/mcp-search-tool.ts";
+import { fetchWithTimeout, mcpJsonResult as jsonResult } from "../../../shared/mcp-tool-kit.ts";
+import {
+  runReadOnlyMcpConnector,
+  type ZodToolRegistrar,
+} from "../../../shared/run-read-only-mcp-connector.ts";
+import { filterPowerBiReports } from "./search-filter.ts";
+
+function requireEnv(name: string): string {
+  const v = process.env[name]?.trim();
+  if (v === undefined || v === "") {
+    throw new Error(`${name} is not set`);
+  }
+  return v;
+}
+
+async function fetchAccessToken(
+  tenantId: string,
+  clientId: string,
+  clientSecret: string,
+): Promise<string> {
+  const url = `https://login.microsoftonline.com/${tenantId}/oauth2/v2.0/token`;
+  const body =
+    `grant_type=client_credentials` +
+    `&client_id=${encodeURIComponent(clientId)}` +
+    `&client_secret=${encodeURIComponent(clientSecret)}` +
+    `&scope=${encodeURIComponent("https://analysis.windows.net/powerbi/api/.default")}`;
+  const res = await fetchWithTimeout(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/x-www-form-urlencoded",
+      Accept: "application/json",
+    },
+    body,
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`Power BI token error ${String(res.status)}: ${text.slice(0, 400)}`);
+  }
+  const parsed = JSON.parse(text) as unknown;
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("Power BI token response: unexpected shape");
+  }
+  const token = (parsed as Record<string, unknown>)["access_token"];
+  if (typeof token !== "string" || token === "") {
+    throw new Error("Power BI token response: missing access_token");
+  }
+  return token;
+}
+
+const POWERBI_API_BASE = "https://api.powerbi.com";
+
+/** Mint an AAD access token from the connector's client-credentials env. */
+async function accessToken(): Promise<string> {
+  return fetchAccessToken(
+    requireEnv("POWERBI_TENANT_ID"),
+    requireEnv("POWERBI_CLIENT_ID"),
+    requireEnv("POWERBI_CLIENT_SECRET"),
+  );
+}
+
+function asRec(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+async function listReports(accessToken: string): Promise<unknown[]> {
+  const res = await fetchWithTimeout("https://api.powerbi.com/v1.0/myorg/reports", {
+    headers: { Authorization: `Bearer ${accessToken}`, Accept: "application/json" },
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`Power BI reports error ${String(res.status)}: ${text.slice(0, 400)}`);
+  }
+  const value = asRec(JSON.parse(text) as unknown)?.["value"];
+  return Array.isArray(value) ? value : [];
+}
+
+/** Fetch a dataset's table names for lineage (`GET /datasets/{id}/tables`); empty on any failure. */
+async function fetchDatasetTables(accessToken: string, datasetId: string): Promise<string[]> {
+  const res = await fetchWithTimeout(
+    `https://api.powerbi.com/v1.0/myorg/datasets/${encodeURIComponent(datasetId)}/tables`,
+    { headers: { Authorization: `Bearer ${accessToken}`, Accept: "application/json" } },
+  );
+  if (!res.ok) return [];
+  const value = asRec(JSON.parse(await res.text()) as unknown)?.["value"];
+  if (!Array.isArray(value)) return [];
+  const out: string[] = [];
+  for (const item of value) {
+    const name = asRec(item)?.["name"];
+    if (typeof name === "string" && name !== "") out.push(name);
+  }
+  return out;
+}
+
+/** Attach each report's dataset-table refs in-session, so the gateway never makes a second credentialed call. */
+async function expandReport(accessToken: string, report: unknown): Promise<unknown> {
+  const r = asRec(report);
+  if (r === undefined) return report;
+  const datasetId = r["datasetId"];
+  const datasetTables =
+    typeof datasetId === "string" && datasetId !== ""
+      ? await fetchDatasetTables(accessToken, datasetId)
+      : [];
+  return { ...r, datasetTables };
+}
+
+export function registerPowerBiTools(reg: ZodToolRegistrar, server: unknown): void {
+  // Despite the read-only helper's name, this connector exposes write tools. The consent
+  // kit needs the real server, which the helper now passes through as its second argument.
+  const registerWriteTool = createWriteToolRegistrar(server as ConsentServer, {
+    connector: "powerbi",
+    scopeEnv: "NIMBUS_MCP_POWERBI_WRITE_SCOPE",
+    scopeKinds: ["workspace"],
+  });
+
+  reg(
+    "powerbi_list",
+    "List Power BI reports (`GET /v1.0/myorg/reports`), each expanded with its dataset-table refs for lineage. The reports endpoint returns the full org list in one response and has no reliable server paging, so this is a single fetch returning ALL reports with `nextCursor: null` (`cursor`/`limit` are accepted for `_list` API symmetry but never truncate).",
+    z.object({
+      cursor: z.string().nullable().optional(),
+      limit: z.number().int().min(1).max(500).optional(),
+    }),
+    async (_p) => {
+      const tenantId = requireEnv("POWERBI_TENANT_ID");
+      const clientId = requireEnv("POWERBI_CLIENT_ID");
+      const clientSecret = requireEnv("POWERBI_CLIENT_SECRET");
+      const accessToken = await fetchAccessToken(tenantId, clientId, clientSecret);
+      // Return EVERY report: slicing to `limit` would silently drop reports (nextCursor is null, so
+      // the gateway drain stops) and lose them from the index for orgs with many reports.
+      const reports = await listReports(accessToken);
+      const items = await Promise.all(reports.map((r) => expandReport(accessToken, r)));
+      return jsonResult({ items, nextCursor: null });
+    },
+  );
+
+  reg(
+    "powerbi_get",
+    "Fetch one Power BI report by its id. Throws when the report is not found.",
+    z.object({
+      id: z.string().min(1),
+    }),
+    async (p) => {
+      const tenantId = requireEnv("POWERBI_TENANT_ID");
+      const clientId = requireEnv("POWERBI_CLIENT_ID");
+      const clientSecret = requireEnv("POWERBI_CLIENT_SECRET");
+      const accessToken = await fetchAccessToken(tenantId, clientId, clientSecret);
+      const reports = await listReports(accessToken);
+      const found = reports.find((r) => {
+        if (r === null || typeof r !== "object" || Array.isArray(r)) return false;
+        return (r as Record<string, unknown>)["id"] === p.id;
+      });
+      if (found === undefined) {
+        throw new Error(`Power BI report not found: ${p.id}`);
+      }
+      return jsonResult(found);
+    },
+  );
+
+  reg(
+    "powerbi_search",
+    "Substring search across Power BI reports. Matches the query (case-insensitive) against report name and description. Returns a `{ matches: [...] }` envelope.",
+    searchToolInputSchema(200),
+    async (p) => {
+      const tenantId = requireEnv("POWERBI_TENANT_ID");
+      const clientId = requireEnv("POWERBI_CLIENT_ID");
+      const clientSecret = requireEnv("POWERBI_CLIENT_SECRET");
+      const accessToken = await fetchAccessToken(tenantId, clientId, clientSecret);
+      const reports = await listReports(accessToken);
+      const matches = filterPowerBiReports(reports, { query: p.query, limit: p.limit });
+      return jsonResult({ matches });
+    },
+  );
+
+  registerWriteTool(
+    "powerbi_dataset_refresh",
+    {
+      mutates: "powerbi.dataset.refresh",
+      recoverable: true,
+      scopeTargetOf: (p) => ({ kind: "workspace", value: p.groupId ?? "my-workspace" }),
+    },
+    "Trigger a dataset refresh. groupId optional (omit for My Workspace). Async (202).",
+    // groupId is nullish: indexed dashboard metadata stores `null` for "My Workspace" reports, and
+    // Zod `.optional()` would reject a literal null — `.nullish()` accepts both null and undefined.
+    z.object({ groupId: z.string().min(1).nullish(), datasetId: z.string().min(1) }),
+    async (p) => {
+      const token = await accessToken();
+      // Narrow to a non-empty string in a local so encodeURIComponent sees `string` (not nullish).
+      const group =
+        p.groupId === undefined || p.groupId === null || p.groupId === "" ? undefined : p.groupId;
+      const datasetUrl =
+        group === undefined
+          ? `${POWERBI_API_BASE}/v1.0/myorg/datasets/${encodeURIComponent(p.datasetId)}/refreshes`
+          : `${POWERBI_API_BASE}/v1.0/myorg/groups/${encodeURIComponent(group)}/datasets/${encodeURIComponent(p.datasetId)}/refreshes`;
+      const res = await fetchWithTimeout(datasetUrl, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+        body: JSON.stringify({ notifyOption: "NoNotification" }),
+      });
+      if (!res.ok) {
+        throw new Error(
+          `Power BI dataset refresh ${String(res.status)}: ${(await res.text()).slice(0, 400)}`,
+        );
+      }
+      return jsonResult({
+        status: "queued",
+        ...(group === undefined ? {} : { groupId: group }),
+        datasetId: p.datasetId,
+      });
+    },
+  );
+
+  registerWriteTool(
+    "powerbi_dataflow_refresh",
+    {
+      mutates: "powerbi.dataflow.refresh",
+      recoverable: true,
+      scopeTargetOf: (p) => ({ kind: "workspace", value: p.groupId ?? "my-workspace" }),
+    },
+    "Trigger a dataflow refresh. Async (202).",
+    z.object({ groupId: z.string().min(1), dataflowId: z.string().min(1) }),
+    async (p) => {
+      const token = await accessToken();
+      const url = `${POWERBI_API_BASE}/v1.0/myorg/groups/${encodeURIComponent(p.groupId)}/dataflows/${encodeURIComponent(p.dataflowId)}/refreshes`;
+      const res = await fetchWithTimeout(url, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+        body: JSON.stringify({ notifyOption: "NoNotification" }),
+      });
+      if (!res.ok) {
+        throw new Error(
+          `Power BI dataflow refresh ${String(res.status)}: ${(await res.text()).slice(0, 400)}`,
+        );
+      }
+      return jsonResult({ status: "queued", groupId: p.groupId, dataflowId: p.dataflowId });
+    },
+  );
+}
+
+// Exported so the bundled-connector registry can start this server explicitly: `import.meta.main`
+// is false under an import, and the module must stay importable by tests without connecting stdio.
+export async function startConnector(): Promise<void> {
+  await runReadOnlyMcpConnector("nimbus-powerbi", registerPowerBiTools);
+}
+
+if (import.meta.main) await startConnector();

package/connectors/prefect/nimbus.extension.json

@@ -0,0 +1,16 @@
+{
+  "id": "com.nimbus.prefect",
+  "displayName": "Prefect",
+  "version": "0.1.0",
+  "description": "Prefect connector (read-only). Surfaces the user's data-orchestration deployments from a Prefect Cloud workspace or a self-hosted Prefect Server as prefect:deployment items in the local index — the deployment id, name, flow id, description, tags, paused flag, work pool, work queue, schedule, status, and created/updated timestamps. Useful for answering orchestration questions (\"which deployments are paused?\", \"what's the schedule for the nightly flow?\") without leaving Nimbus. Bearer-token auth (Prefect API key; required for Cloud, may be empty for self-hosted Server but still injected for uniform wiring). Prefect has no universal SaaS host: the per-tenant workspace API root is supplied via the prefect api_url vault key and added to the sandbox network list at spawn time by phase3AddPrefectMcp, so the static manifest network list is intentionally empty. The list endpoint is a POST filter: POST <api_url>/deployments/filter with a JSON body { limit, offset, sort } returns a bare JSON array of deployments; the connector walks a single forward offset pass per cycle, capped. v1 indexes deployments only — individual flow runs and task runs are a deferred follow-up. No write tools.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": [],
+    "filesystem": { "read": [], "write": [] }
+  },
+  "hitlRequired": [],
+  "syncInterval": 600,
+  "minNimbusVersion": "0.2.0"
+}

package/connectors/prefect/src/search-filter.ts

@@ -0,0 +1,40 @@
+import {
+  asObjectish,
+  makeQueryFilter,
+  type SearchMatchOptions,
+  stringField,
+} from "../../../shared/search-filter.ts";
+
+export type PrefectSearchMatchOptions = SearchMatchOptions;
+
+/** Prefect deployment tags are a bare string array (not `{name}` objects). */
+function tagNames(row: Record<string, unknown>): string {
+  const tags = row["tags"];
+  if (!Array.isArray(tags)) {
+    return "";
+  }
+  const names: string[] = [];
+  for (const t of tags) {
+    if (typeof t === "string" && t !== "") {
+      names.push(t);
+    }
+  }
+  return names.join(" ");
+}
+
+function fieldsOf(item: unknown): readonly string[] | null {
+  const row = asObjectish(item);
+  if (row === undefined) {
+    return null;
+  }
+  return [
+    stringField(row, "name"),
+    stringField(row, "description"),
+    stringField(row, "work_pool_name"),
+    stringField(row, "work_queue_name"),
+    stringField(row, "status"),
+    tagNames(row),
+  ];
+}
+
+export const filterPrefectDeployments = makeQueryFilter(fieldsOf);

package/connectors/prefect/src/server.ts

@@ -0,0 +1,94 @@
+import { z } from "zod";
+import { searchToolInputSchema } from "../../../shared/mcp-search-tool.ts";
+import { mcpJsonResult as jsonResult } from "../../../shared/mcp-tool-kit.ts";
+import { runReadOnlyMcpConnector } from "../../../shared/run-read-only-mcp-connector.ts";
+import { filterPrefectDeployments } from "./search-filter.ts";
+
+function trimTrailingSlash(s: string): string {
+  return s.endsWith("/") ? s.slice(0, -1) : s;
+}
+
+function apiBase(): string {
+  const v = process.env["PREFECT_API_URL"]?.trim();
+  if (v === undefined || v === "") {
+    throw new Error("PREFECT_API_URL is not set");
+  }
+  return trimTrailingSlash(v);
+}
+
+function authHeaders(): Record<string, string> {
+  const headers: Record<string, string> = { Accept: "application/json" };
+  // Prefect Cloud requires a Bearer API key; self-hosted Prefect Server may run
+  // keyless, so an empty key is tolerated (the header is simply omitted).
+  const apiKey = process.env["PREFECT_API_KEY"]?.trim();
+  if (apiKey !== undefined && apiKey !== "") {
+    headers["Authorization"] = `Bearer ${apiKey}`;
+  }
+  return headers;
+}
+
+async function prefectGet(path: string): Promise<unknown> {
+  const res = await fetch(`${apiBase()}${path}`, { headers: authHeaders() });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`Prefect ${String(res.status)}: ${text.slice(0, 400)}`);
+  }
+  return JSON.parse(text) as unknown;
+}
+
+async function prefectListDeployments(offset: number, limit: number): Promise<unknown> {
+  const res = await fetch(`${apiBase()}/deployments/filter`, {
+    method: "POST",
+    headers: { ...authHeaders(), "Content-Type": "application/json" },
+    body: JSON.stringify({ limit, offset, sort: "CREATED_DESC" }),
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`Prefect ${String(res.status)}: ${text.slice(0, 400)}`);
+  }
+  return JSON.parse(text) as unknown;
+}
+
+function deploymentsFrom(root: unknown): unknown[] {
+  return Array.isArray(root) ? root : [];
+}
+
+await runReadOnlyMcpConnector("nimbus-prefect", (reg) => {
+  reg(
+    "prefect_list",
+    "List Prefect deployments (POST <api_url>/deployments/filter with a JSON body { limit, offset, sort: CREATED_DESC }). Prefect's list endpoints are POST-with-body filters, not GET query-string endpoints; the response is a bare JSON array of deployment objects. The optional offset arg (default 0) selects the page start; limit is fixed at 100.",
+    z.object({
+      offset: z.number().int().min(0).optional(),
+    }),
+    async (p) => {
+      const offset = p.offset ?? 0;
+      const root = await prefectListDeployments(offset, 100);
+      return jsonResult({ items: deploymentsFrom(root) });
+    },
+  );
+
+  reg(
+    "prefect_get",
+    "Fetch one Prefect deployment by its id (GET <api_url>/deployments/{id}). The id is the deployment UUID string. Returns the deployment object directly (NOT wrapped in an array). Throws when no deployment with that id exists.",
+    z.object({
+      id: z.string().min(1),
+    }),
+    async (p) => {
+      return jsonResult(await prefectGet(`/deployments/${encodeURIComponent(p.id)}`));
+    },
+  );
+
+  reg(
+    "prefect_search",
+    "Substring search across the first page of Prefect deployments. Matches the query (case-insensitive) against the deployment name, description, work pool, work queue, status, and tags. Returns a matches envelope.",
+    searchToolInputSchema(100),
+    async (p) => {
+      const root = await prefectListDeployments(0, 100);
+      const matches = filterPrefectDeployments(deploymentsFrom(root), {
+        query: p.query,
+        limit: p.limit,
+      });
+      return jsonResult({ matches });
+    },
+  );
+});

package/connectors/protonmail/nimbus.extension.json

@@ -0,0 +1,16 @@
+{
+  "id": "com.nimbus.protonmail",
+  "displayName": "ProtonMail (Bridge)",
+  "version": "0.1.0",
+  "description": "ProtonMail email connector via ProtonMail Bridge (Tier-4 EMAIL class). ProtonMail is end-to-end encrypted, so the local ProtonMail Bridge app decrypts mail on the user's machine and exposes a standard IMAP/SMTP interface on the loopback interface (127.0.0.1:1143 IMAP / 127.0.0.1:1025 SMTP) with Bridge-generated credentials. This connector indexes the user's mailbox over that local IMAP listener as `protonmail:email` items — message HEADERS (subject, from, to/cc, date, message-id), a short capped plain-text body PREVIEW (~2 KB / 2000 chars), and attachment METADATA only (filename, size, mimetype). It NEVER downloads or parses attachment bytes and never fetches the full message body. Read tools (`protonmail_list`, `protonmail_get`, `protonmail_search`) plus one HITL-gated write tool (`protonmail_mail_send`) that sends mail over the Bridge SMTP relay. Bridge credentials arrive as scoped environment variables injected at spawn time (PROTONMAIL_HOST/PROTONMAIL_PORT/PROTONMAIL_USERNAME/PROTONMAIL_PASSWORD and PROTONMAIL_SMTP_*) — the connector never reads the vault. Because Bridge listens on the loopback interface with a self-signed certificate, the connection uses STARTTLS without certificate verification (it never leaves 127.0.0.1); the concrete 127.0.0.1:1143 + 127.0.0.1:1025 host:port entries are added to the sandbox network allow-list at spawn time by phase3AddProtonmailMcp.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": [],
+    "filesystem": { "read": [], "write": [] }
+  },
+  "hitlRequired": ["write"],
+  "syncInterval": 300,
+  "minNimbusVersion": "0.2.0"
+}

package/connectors/protonmail/src/mail-core.ts

@@ -0,0 +1,96 @@
+/**
+ * ProtonMail (via ProtonMail Bridge) connector core — transport-agnostic logic
+ * for the read tools (`protonmail_list`, `protonmail_get`, `protonmail_search`)
+ * and the HITL-gated send tool (`protonmail_mail_send`). ProtonMail Bridge
+ * exposes a standard IMAP/SMTP interface on the loopback interface, so this is
+ * the same shape as the generic IMAP connector core.
+ *
+ * HARD SCOPE CONSTRAINT (security): this connector indexes HEADERS + a short
+ * capped plain-text body PREVIEW + attachment METADATA only. It NEVER downloads
+ * or parses attachment bytes and never fetches the full message body.
+ *
+ * The IMAP client and SMTP mailer are injected so tests never open real sockets.
+ */
+
+import type { MailAddress } from "../../../shared/imap-mail-core.ts";
+
+export {
+  capPreview,
+  clampLimit,
+  formatAddress,
+  PREVIEW_FETCH_BYTES,
+  PREVIEW_MAX_CHARS,
+} from "../../../shared/imap-mail-core.ts";
+export type { MailAddress };
+
+/** Message ENVELOPE — RFC 2822 header fields only. */
+export interface MailEnvelope {
+  readonly date?: Date | string | null;
+  readonly subject?: string | null;
+  readonly messageId?: string | null;
+  readonly from?: readonly MailAddress[];
+  readonly to?: readonly MailAddress[];
+  readonly cc?: readonly MailAddress[];
+}
+
+/** Attachment METADATA only — filename, size, mimetype. NEVER the bytes. */
+export interface MailAttachmentMeta {
+  readonly filename: string | null;
+  readonly sizeBytes: number | null;
+  readonly mimeType: string | null;
+}
+
+/**
+ * A single mailbox message reduced to header + attachment-metadata + a capped
+ * text preview. This is the ONLY shape the connector ever materializes.
+ */
+export interface MailMessageMeta {
+  readonly uid: number;
+  readonly mailbox: string;
+  readonly uidValidity: string | null;
+  readonly envelope: MailEnvelope;
+  readonly attachments: readonly MailAttachmentMeta[];
+  /** Plain-text body preview, already capped to {@link PREVIEW_MAX_CHARS}. */
+  readonly preview: string;
+}
+
+export interface MailListOptions {
+  readonly mailbox?: string;
+  readonly limit?: number;
+}
+
+export interface MailSearchOptions {
+  readonly query: string;
+  readonly mailbox?: string;
+  readonly limit?: number;
+}
+
+/**
+ * Minimal IMAP client surface the connector depends on. Implemented for real by
+ * the imapflow adapter in `server.ts` and by a fake in tests.
+ */
+export interface MailClient {
+  list(options: MailListOptions): Promise<MailMessageMeta[]>;
+  get(uid: number, mailbox?: string): Promise<MailMessageMeta | null>;
+  search(options: MailSearchOptions): Promise<MailMessageMeta[]>;
+}
+
+/** Outgoing message for the SMTP send tool. */
+export interface SendMailInput {
+  readonly to: string;
+  readonly subject: string;
+  readonly body: string;
+  readonly cc?: string;
+  readonly bcc?: string;
+}
+
+export interface SendMailResult {
+  readonly messageId: string | null;
+  readonly accepted: readonly string[];
+  readonly rejected: readonly string[];
+}
+
+/** Minimal SMTP mailer surface; implemented for real over nodemailer. */
+export interface SmtpMailer {
+  send(input: SendMailInput): Promise<SendMailResult>;
+}