@nimbus-dev/connectors 0.6.0 → 0.8.0

package/connectors/gitlab/src/tools.ts

@@ -1,6 +1,17 @@
 import { z } from "zod";
+import {
+  assertCombinedSize,
+  assertCommitFiles,
+  COMMIT_MAX_COMBINED_BYTES,
+  COMMIT_MAX_FILES,
+  commitFilePathSchema,
+  commitFilesSchema,
+  fullShaSchema,
+  notOverwritable,
+} from "../../../shared/commit-files.ts";
 import {
   type ConsentServer,
+  createPrepareToolRegistrar,
   createWriteToolRegistrar,
   type WriteToolConfig,
 } from "../../../shared/consent-kit.ts";
@@ -21,6 +32,14 @@ import {
   type RestFetchResult,
   toRestFetchResult,
 } from "../../../shared/rest-tool-kit.ts";
+import {
+  assertRegularTargets,
+  branchHead,
+  type GitlabFileRead,
+  type GitlabGet,
+  readGitlabFilesAt,
+  refCommit,
+} from "./gitlab-files.ts";
 
 /**
  * A project reference that reaches a URL path: a numeric id, or `/`-separated segments of
@@ -163,6 +182,9 @@ export const GITLAB_TOOL_NAMES = [
   "gitlab_job_log_tail",
   "gitlab_pipeline_retry",
   "gitlab_pipeline_cancel",
+  "gitlab_files_get",
+  "gitlab_commit_prepare",
+  "gitlab_commit_create",
 ] as const;
 
 export function registerGitlabTools(
@@ -182,6 +204,16 @@ export function registerGitlabTools(
     scopeKinds: ["repo"],
   });
 
+  /**
+   * Prepare tools (shared/prepare-tool-ids.ts) read the state a write is bound to, for the gateway to
+   * call BEFORE the write's approval prompt; they are neither reads nor writes to the kit.
+   */
+  const registerPrepareTool = createPrepareToolRegistrar(server, {
+    connector: "gitlab",
+    scopeEnv: "NIMBUS_MCP_GITLAB_WRITE_SCOPE",
+    scopeKinds: ["repo"],
+  });
+
   /**
    * Standard GitLab tool, read or write: `token → glFetch(buildUrl[, buildInit]) →
    * mcpJsonResultIfOk("GitLab", res)`. `buildUrl` returns the relative path (or absolute URL) and
@@ -707,4 +739,198 @@ export function registerGitlabTools(
     "Cancel a pipeline.",
     "cancel",
   );
+
+  // -------------------------------------------------------------------------------------------
+  // Multi-file commit: gitlab_files_get (read), gitlab_commit_prepare (prepare), gitlab_commit_create
+  // -------------------------------------------------------------------------------------------
+
+  /** Bound GETs: the token is read at call time, before the first request. */
+  const gitlabGet = (): GitlabGet => {
+    const token = requireProcessEnv("GITLAB_PAT");
+    return (path) => glFetch(token, path);
+  };
+
+  const READ_LIMIT = COMMIT_MAX_COMBINED_BYTES;
+
+  /** What a read tool reports for one file; `content` only for text. */
+  function fileView(f: GitlabFileRead): Record<string, unknown> {
+    if (!f.exists) return { path: f.path, exists: false };
+    const base = {
+      path: f.path,
+      exists: true,
+      lastCommitId: f.lastCommitId,
+      executable: f.executable,
+      size: f.size,
+    };
+    return f.kind === "text" ? { ...base, content: f.content } : { ...base, withheld: f.kind };
+  }
+
+  reg(
+    "gitlab_files_get",
+    'Read up to 50 files at a branch, tag or commit: {ref, headSha, files:[{path, exists, lastCommitId, executable, size, content}]}. A binary or over-192-KiB file is reported with `withheld` instead of content, and the content of all the files together is capped at 192 KiB: the first file that does not fit, and every file after it, is reported with `withheld: "budget"` and no content.',
+    projectPathArg.extend({
+      ref: gitlabRefSchema,
+      paths: z.array(commitFilePathSchema).min(1).max(50),
+    }),
+    async (parsed) => {
+      const get = gitlabGet();
+      const project = encodeURIComponent(parsed.projectPath);
+      const sha = await refCommit(get, project, parsed.ref);
+      const files = await readGitlabFilesAt(
+        get,
+        project,
+        sha,
+        parsed.paths,
+        READ_LIMIT,
+        READ_LIMIT,
+      );
+      return jsonResult({ ref: parsed.ref, headSha: sha, files: files.map(fileView) });
+    },
+  );
+
+  const gitlabCommitInputSchema = projectPathArg.extend({
+    branch: gitlabRefSchema,
+    files: commitFilesSchema,
+  });
+
+  const repoScopeOf = (p: { projectPath: string }): { kind: string; value: string } => ({
+    kind: "repo",
+    value: p.projectPath,
+  });
+
+  registerPrepareTool(
+    "gitlab_commit_prepare",
+    { scopeTargetOf: repoScopeOf },
+    `Read the state a gitlab_commit_create is bound to: the branch head and, for each file, whether it exists, its last_commit_id, whether it is executable and its current content. Refuses (no truncation) a commit that touches more than ${String(COMMIT_MAX_FILES)} files or whose old and new content together exceed 192 KiB, and any existing file that is not a text file. Takes the commit's own projectPath, branch and files.`,
+    gitlabCommitInputSchema,
+    async (parsed) => {
+      assertCommitFiles(parsed.files);
+      const get = gitlabGet();
+      const project = encodeURIComponent(parsed.projectPath);
+      const head = await branchHead(get, project, parsed.branch);
+      const read = await readGitlabFilesAt(
+        get,
+        project,
+        head,
+        parsed.files.map((f) => f.path),
+        READ_LIMIT,
+      );
+      // The files API reports no mode, so a symlink looks like a text file: read the tree entries and
+      // refuse a symlink, a submodule or a directory before anything is written.
+      await assertRegularTargets(get, project, head, read);
+      let oldBytes = 0;
+      const files = read.map((f) => {
+        if (!f.exists) return { path: f.path, exists: false };
+        if (f.kind !== "text") throw notOverwritable(f.path);
+        oldBytes += f.size;
+        return {
+          path: f.path,
+          exists: true,
+          lastCommitId: f.lastCommitId,
+          executable: f.executable,
+          oldContent: f.content,
+        };
+      });
+      assertCombinedSize(oldBytes, parsed.files);
+      return jsonResult({ headSha: head, files });
+    },
+  );
+
+  registerWriteTool(
+    "gitlab_commit_create",
+    {
+      mutates: "gitlab.commit.create",
+      // A commit moves a branch; the inverse needs the head and each file's last commit, captured first.
+      recoverable: false,
+      capturePreState: async (parsed) => {
+        const get = gitlabGet();
+        const project = encodeURIComponent(parsed.projectPath);
+        const head = await branchHead(get, project, parsed.branch);
+        const read = await readGitlabFilesAt(
+          get,
+          project,
+          head,
+          parsed.files.map((f) => f.path),
+          READ_LIMIT,
+        );
+        return {
+          branch: parsed.branch,
+          headSha: head,
+          files: read.map((f) => ({
+            path: f.path,
+            lastCommitId: f.exists ? f.lastCommitId : null,
+          })),
+        };
+      },
+      scopeTargetOf: repoScopeOf,
+    },
+    "Commit one or more whole text files to a branch as ONE commit. The branch head is checked against expectedHeadSha (the head the owner approved) before the write, but GitLab has no head-conditional commit, so that check is NOT atomic with the write. What protects the files is last_commit_id: each update carries the file's last_commit_id read at the approved head, and GitLab refuses it if that file changed since. A commit to OTHER files that lands between the check and the write is not detected before the write; movedHead: true in the result reports it afterwards (the new commit's parent is not the approved head). Never forced.",
+    gitlabCommitInputSchema.extend({
+      message: z.string().min(1).max(5000),
+      expectedHeadSha: fullShaSchema,
+    }),
+    async (parsed) => {
+      assertCommitFiles(parsed.files);
+      const get = gitlabGet();
+      const token = requireProcessEnv("GITLAB_PAT");
+      const project = encodeURIComponent(parsed.projectPath);
+      const expected = parsed.expectedHeadSha.toLowerCase();
+      // 1. The head AGAIN: the approval was for this commit, not for whatever the branch became.
+      const head = await branchHead(get, project, parsed.branch);
+      if (head !== expected) {
+        throw new Error(`branch head is ${head}, not the approved ${expected}`);
+      }
+      // 2. Each existing file AT that head: its last_commit_id goes on the update action.
+      const read = await readGitlabFilesAt(
+        get,
+        project,
+        head,
+        parsed.files.map((f) => f.path),
+        READ_LIMIT,
+      );
+      // The files API reports no mode, so a symlink looks like a text file: read the tree entries and
+      // refuse a symlink, a submodule or a directory before anything is written.
+      await assertRegularTargets(get, project, head, read);
+      let oldBytes = 0;
+      const actions = parsed.files.map((f, i) => {
+        const existing = read[i];
+        if (existing === undefined || !existing.exists) {
+          return { action: "create", file_path: f.path, content: f.content, encoding: "text" };
+        }
+        if (existing.kind !== "text") throw notOverwritable(f.path);
+        oldBytes += existing.size;
+        return {
+          action: "update",
+          file_path: f.path,
+          content: f.content,
+          encoding: "text",
+          last_commit_id: existing.lastCommitId,
+        };
+      });
+      assertCombinedSize(oldBytes, parsed.files);
+      // 3. One commit, no force, no start_branch.
+      const res = await glFetch(
+        token,
+        `/projects/${project}/repository/commits`,
+        jsonBody("POST", { branch: parsed.branch, commit_message: parsed.message, actions }),
+      );
+      if (!res.ok) {
+        throw new Error(`GitLab ${String(res.status)}: ${res.text.slice(0, 300)}`);
+      }
+      const made = (res.json ?? {}) as { id?: unknown; parent_ids?: unknown; web_url?: unknown };
+      // The head can move between step 1 and this POST (the API has no head-conditional commit):
+      // say so when the new commit's parent is not the head that was approved.
+      const movedHead = !(
+        Array.isArray(made.parent_ids) && made.parent_ids.map(String).includes(expected)
+      );
+      return jsonResult({
+        ok: true,
+        commitId: made.id,
+        branch: parsed.branch,
+        parent: expected,
+        webUrl: made.web_url,
+        movedHead,
+      });
+    },
+  );
 }

package/connectors/kubernetes/src/tools.ts

@@ -2,21 +2,15 @@ import { z } from "zod";
 import { cliArg } from "../../../shared/cli-json-kit.ts";
 import type { ConsentServer } from "../../../shared/consent-kit.ts";
 import { createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
+import { isKubectlNotFound, projectDeployment } from "../../../shared/k8s-deployment-view.ts";
 import {
   createRegisterSimpleTool,
   createZodToolRegistrar,
   mcpJsonResult as jsonResult,
 } from "../../../shared/mcp-tool-kit.ts";
+import { withPrivateKubeconfig } from "../../../shared/private-kubeconfig.ts";
 import { runCliJsonThrowing, runCliOkThrowing } from "../../../shared/run-cli-json.ts";
 
-function requireKubeconfigPath(): string {
-  const p = process.env["KUBECONFIG"]?.trim();
-  if (p === undefined || p === "") {
-    throw new Error("KUBECONFIG env must be set to a kubeconfig file path");
-  }
-  return p;
-}
-
 function kubectlBase(): string[] {
   const args = ["kubectl"];
   const ctx = process.env["KUBE_CONTEXT"]?.trim();
@@ -26,13 +20,17 @@ function kubectlBase(): string[] {
   return args;
 }
 
-function kubeEnv(): Record<string, string | undefined> {
-  return { KUBECONFIG: requireKubeconfigPath() };
+/**
+ * Run `body` against a private copy of the kubeconfig `KUBECONFIG` names (shared/private-kubeconfig.ts):
+ * one tool call, one copy, so a call can neither change the owner's file nor race another call.
+ */
+function withKube<T>(body: (env: { readonly KUBECONFIG: string }) => Promise<T>): Promise<T> {
+  return withPrivateKubeconfig({ source: process.env["KUBECONFIG"] ?? "" }, body);
 }
 
-async function kubectlJson(rest: string[]): Promise<unknown> {
+function kubectlJson(rest: string[]): Promise<unknown> {
   const cmd = [...kubectlBase(), ...rest, "-o", "json"];
-  return runCliJsonThrowing(cmd, kubeEnv());
+  return withKube((env) => runCliJsonThrowing(cmd, env));
 }
 
 const optionalNamespaceSchema = z.object({ namespace: cliArg.optional() });
@@ -46,6 +44,7 @@ async function k8sListNamespacedResource(p: { namespace?: string | undefined },
 /** Tool names exposed by this connector — for contract/introspection tests. */
 export const KUBERNETES_TOOL_NAMES = [
   "k8s_pod_list",
+  "k8s_deployment_get",
   "k8s_deployment_list",
   "k8s_event_list",
   "k8s_rollout_restart",
@@ -76,6 +75,27 @@ export function registerKubernetesTools(
     (p) => k8sListNamespacedResource(p, "pods"),
   );
 
+  reg(
+    "k8s_deployment_get",
+    "Get one deployment's state: {name, namespace, replicas, readyReplicas, generation, observedGeneration, restartedAt, images}. The before-state of a restart or a scale.",
+    z.object({ namespace: cliArg.optional(), name: cliArg }),
+    async (p) => {
+      let data: unknown;
+      try {
+        // kubectlJson builds on kubectlBase(), so the configured KUBE_CONTEXT applies as it does
+        // to every other call here.
+        data = await kubectlJson(["get", "deployment", p.name, "-n", p.namespace ?? "default"]);
+      } catch (e) {
+        // Exit code of a missing object is not documented, so NotFound is read from the message.
+        if (e instanceof Error && isKubectlNotFound(e.message)) {
+          throw new Error("deployment not found", { cause: e });
+        }
+        throw e;
+      }
+      return jsonResult(projectDeployment(data));
+    },
+  );
+
   reg("k8s_deployment_list", "List deployments in a namespace.", optionalNamespaceSchema, (p) =>
     k8sListNamespacedResource(p, "deployments"),
   );
@@ -100,7 +120,7 @@ export function registerKubernetesTools(
     async (p) => {
       const ns = p.namespace ?? "default";
       const cmd = [...kubectlBase(), "rollout", "restart", p.resourceType, p.name, "-n", ns];
-      await runCliOkThrowing(cmd, kubeEnv());
+      await withKube((env) => runCliOkThrowing(cmd, env));
       return jsonResult({ ok: true });
     },
   );
@@ -124,7 +144,7 @@ export function registerKubernetesTools(
     async (p) => {
       const ns = p.namespace ?? "default";
       const cmd = [...kubectlBase(), "delete", "pod", p.podName, "-n", ns];
-      await runCliOkThrowing(cmd, kubeEnv());
+      await withKube((env) => runCliOkThrowing(cmd, env));
       return jsonResult({ ok: true });
     },
   );
@@ -153,7 +173,7 @@ export function registerKubernetesTools(
         ns,
         `--replicas=${String(p.replicas)}`,
       ];
-      await runCliOkThrowing(cmd, kubeEnv());
+      await withKube((env) => runCliOkThrowing(cmd, env));
       return jsonResult({ ok: true });
     },
   );

package/connectors/slack/src/tools.ts

@@ -102,9 +102,17 @@ export const SLACK_TOOL_NAMES = [
   "slack_message_post_dm",
   "slack_user_info",
   "slack_chat_post",
+  "slack_views_open",
   "slack_socket_open",
 ] as const;
 
+/** Largest serialised `blocks` array / `view` object Slack accepts from this connector (16 KiB). */
+export const SLACK_PAYLOAD_MAX_BYTES = 16 * 1024;
+
+function serialisedBytes(value: unknown): number {
+  return new TextEncoder().encode(JSON.stringify(value)).length;
+}
+
 export function registerSlackTools(
   server: ConsentServer & { tool: (...args: never) => unknown },
 ): void {
@@ -122,7 +130,7 @@ export function registerSlackTools(
     scopeEnv: "NIMBUS_MCP_SLACK_WRITE_SCOPE",
     // `user` scopes a direct message by the recipient's user id, which is all a DM has before
     // `conversations.open` creates its channel.
-    scopeKinds: ["channel", "user"],
+    scopeKinds: ["channel", "user", "view"],
   });
 
   const slackChannelListSchema = z.object({
@@ -341,7 +349,19 @@ export function registerSlackTools(
       ),
   );
 
-  const slackChatPostSchema = z.object({ channel: z.string().min(1), text: z.string().min(1) });
+  const slackChatPostSchema = z.object({
+    channel: z.string().min(1),
+    text: z.string().min(1),
+    // Block Kit blocks, sent to Slack verbatim beside `text` (which stays the notification fallback).
+    blocks: z
+      .array(z.looseObject({ type: z.string() }))
+      .min(1)
+      .max(50)
+      .refine((b) => serialisedBytes(b) <= SLACK_PAYLOAD_MAX_BYTES, {
+        message: `blocks must serialise to at most ${SLACK_PAYLOAD_MAX_BYTES} bytes`,
+      })
+      .optional(),
+  });
   registerWriteTool(
     "slack_chat_post",
     {
@@ -351,12 +371,43 @@ export function registerSlackTools(
     },
     "Post an operational bot message to a channel (ChatOps reply surface; bot token).",
     slackChatPostSchema,
-    async (parsed) =>
-      slackInvokeJsonWithToken(
+    async (parsed) => {
+      const body: Record<string, unknown> = { channel: parsed.channel, text: parsed.text };
+      if (parsed.blocks !== undefined) {
+        body["blocks"] = parsed.blocks;
+      }
+      return slackInvokeJsonWithToken(
         requireProcessEnv("SLACK_BOT_TOKEN"),
         "chat.postMessage",
-        { channel: parsed.channel, text: parsed.text },
+        body,
         "Slack chat.postMessage",
+      );
+    },
+  );
+
+  const slackViewsOpenSchema = z.object({
+    trigger_id: z.string().min(1),
+    view: z
+      .looseObject({ type: z.literal("modal") })
+      .refine((v) => serialisedBytes(v) <= SLACK_PAYLOAD_MAX_BYTES, {
+        message: `view must serialise to at most ${SLACK_PAYLOAD_MAX_BYTES} bytes`,
+      }),
+  });
+  registerWriteTool(
+    "slack_views_open",
+    {
+      mutates: "slack.views.open",
+      recoverable: true,
+      scopeTargetOf: () => ({ kind: "view", value: "modal" }),
+    },
+    "Open a confirmation modal for a user who clicked a ChatOps card button (ChatOps operational surface; bot token).",
+    slackViewsOpenSchema,
+    async (parsed) =>
+      slackInvokeJsonWithToken(
+        requireProcessEnv("SLACK_BOT_TOKEN"),
+        "views.open",
+        { trigger_id: parsed.trigger_id, view: parsed.view },
+        "Slack views.open",
       ),
   );
 

package/connectors/snowflake/src/server.ts

@@ -2,8 +2,9 @@ import { z } from "zod";
 import { type ConsentServer, createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
 import { cursorListInputSchema } from "../../../shared/cursor-list-tool.ts";
 import { requiredEnv } from "../../../shared/env-json-api.ts";
+import { guardedFetch } from "../../../shared/guarded-fetch.ts";
 import { searchToolInputSchema } from "../../../shared/mcp-search-tool.ts";
-import { fetchWithTimeout, mcpJsonResult as jsonResult } from "../../../shared/mcp-tool-kit.ts";
+import { mcpJsonResult as jsonResult } from "../../../shared/mcp-tool-kit.ts";
 import {
   runReadOnlyMcpConnector,
   type ZodToolRegistrar,
@@ -26,7 +27,9 @@ function authHeader(): Record<string, string> {
  */
 async function executeStatement(statement: string): Promise<unknown> {
   const url = `https://${requiredEnv("SNOWFLAKE_ACCOUNT")}.snowflakecomputing.com/api/v2/statements`;
-  const res = await fetchWithTimeout(url, {
+  // guardedFetch: the Bearer token must never follow a redirect to another origin, and a redirect
+  // on this POST (which may be a write) is refused rather than replayed.
+  const res = await guardedFetch("Snowflake", url, {
     method: "POST",
     headers: authHeader(),
     body: JSON.stringify({ statement, timeout: 60 }),
@@ -55,6 +58,23 @@ function sfLiteral(v: string): string {
   return `'${v.replaceAll("'", "''")}'`;
 }
 
+/** The parts of `db.schema.name`, each already vetted by {@link assertSfIdentifier}. */
+function splitObjectName(object: string): { db: string; schema: string; name: string } {
+  // The name is placed in string literals, where Snowflake reads a backslash as an escape.
+  if (object.includes("\\")) throw new Error("object must not contain a backslash");
+  const parts = assertSfIdentifier(object, "object").split(".");
+  const [db, schema, name] = parts;
+  if (parts.length !== 3 || db === undefined || schema === undefined || name === undefined) {
+    throw new Error("object must be a fully qualified name: database.schema.name");
+  }
+  return { db, schema, name };
+}
+
+/** An identifier part's name as Snowflake stores it: a quoted part verbatim, else upper-cased. */
+function storedName(part: string): string {
+  return part.startsWith('"') ? part.slice(1, -1) : part.toUpperCase();
+}
+
 const TABLES_SQL =
   "SELECT table_catalog AS database_name, table_schema AS schema_name, table_name, " +
   "row_count, last_altered FROM information_schema.tables WHERE table_schema <> 'INFORMATION_SCHEMA'";
@@ -108,6 +128,43 @@ function tableKey(row: Record<string, unknown>): string {
   return `${db}.${schema}.${table}`;
 }
 
+/**
+ * The metadata a comment or tag change is previewed against: the object's COMMENT and its tags,
+ * direct and inherited. Two statements, both live (never ACCOUNT_USAGE, whose TAG_REFERENCES lags
+ * up to 120 minutes):
+ * - `SHOW TABLES|VIEWS LIKE '<name>' IN SCHEMA db.schema` for the `comment` column. The LIKE pattern
+ *   supports the wildcards % and _ and the page documents no escape for them
+ *   (https://docs.snowflake.com/en/sql-reference/sql/show-tables), so none is relied on: the pattern
+ *   only NARROWS the rows, and the object is picked by exact name in code.
+ * - `INFORMATION_SCHEMA.TAG_REFERENCES('db.schema.name', 'TABLE')`; the domain TABLE covers views
+ *   (https://docs.snowflake.com/en/sql-reference/functions/tag_references).
+ * Metadata only: no row data is ever selected.
+ */
+async function objectMetadata(
+  objectType: "table" | "view",
+  object: string,
+): Promise<Record<string, unknown>> {
+  const { db, schema, name } = splitObjectName(object);
+  const verb = objectType === "view" ? "VIEWS" : "TABLES";
+  const shown = rowsFromStatementsResponse(
+    await executeStatement(
+      `SHOW ${verb} LIKE ${sfLiteral(name.startsWith('"') ? name.slice(1, -1) : name)} IN SCHEMA ${db}.${schema}`,
+    ),
+  );
+  const wanted = storedName(name);
+  const row = shown.find((r) => r["name"] === wanted);
+  if (row === undefined) throw new Error(`Snowflake ${objectType} not found: ${object}`);
+  const tagRows = rowsFromStatementsResponse(
+    await executeStatement(
+      `SELECT tag_name, tag_value FROM TABLE(${db}.INFORMATION_SCHEMA.TAG_REFERENCES(${sfLiteral(object)}, 'TABLE'))`,
+    ),
+  );
+  const tags = tagRows
+    .map((t) => ({ name: String(t["tag_name"] ?? ""), value: t["tag_value"] ?? null }))
+    .sort((a, b) => a.name.localeCompare(b.name) || String(a.value).localeCompare(String(b.value)));
+  return { object, objectType, comment: row["comment"] ?? "", tags };
+}
+
 /**
  * Register the three read-only Snowflake tools on `reg`. Exported (rather than inlined into the
  * `runReadOnlyMcpConnector` call) so the tool handlers can be exercised in unit tests without
@@ -166,6 +223,16 @@ export function registerSnowflakeTools(reg: ZodToolRegistrar, server: unknown):
     },
   );
 
+  reg(
+    "snowflake_object_metadata_get",
+    "Get a table's or view's COMMENT and tags (direct and inherited) by fully qualified name: {object, objectType, comment, tags:[{name, value}]}. The before-state of snowflake_comment_set and snowflake_tag_set; objectType defaults to table. Metadata only, never row data.",
+    z.object({
+      objectType: z.enum(["table", "view"]).optional(),
+      object: z.string().min(1),
+    }),
+    async (p) => jsonResult(await objectMetadata(p.objectType ?? "table", p.object)),
+  );
+
   registerWriteTool(
     "snowflake_tag_set",
     {

package/connectors/teams/src/bot-send.ts

@@ -55,10 +55,14 @@ function serviceUrlBase(): string {
   return base.endsWith("/") ? base : `${base}/`;
 }
 
-/** Send a plain-text message activity to a Teams conversation via the Bot Framework. */
+/**
+ * Send a message activity to a Teams conversation via the Bot Framework. `attachments` (an Adaptive
+ * Card) goes into the activity body only when given.
+ */
 export async function teamsBotSendActivity(
   conversationId: string,
   text: string,
+  attachments?: readonly unknown[],
 ): Promise<GraphLikeResult> {
   const appId = requireProcessEnv("TEAMS_BOT_APP_ID");
   const appPassword = requireProcessEnv("TEAMS_BOT_APP_PASSWORD");
@@ -67,6 +71,10 @@ export async function teamsBotSendActivity(
   return fetchBearerAuthorizedJson(url, token, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ type: "message", text }),
+    body: JSON.stringify(
+      attachments === undefined
+        ? { type: "message", text }
+        : { type: "message", text, attachments },
+    ),
   });
 }

package/connectors/teams/src/tools.ts

@@ -14,6 +14,9 @@ import {
 } from "../../../shared/mcp-tool-kit.ts";
 import { teamsBotSendActivity } from "./bot-send.ts";
 
+/** Largest serialised `attachments` array `teams_chat_post` accepts (28 KiB). */
+export const TEAMS_ATTACHMENTS_MAX_BYTES = 28 * 1024;
+
 const GRAPH = "https://graph.microsoft.com/v1.0";
 
 async function graphRequest(
@@ -265,6 +268,20 @@ export function registerTeamsTools(
   const teamsChatPostSchema = z.object({
     conversationId: z.string().min(1),
     text: z.string().min(1),
+    // Exactly one Adaptive Card, sent in the activity verbatim; at most 28 KiB serialised.
+    attachments: z
+      .array(
+        z.object({
+          contentType: z.literal("application/vnd.microsoft.card.adaptive"),
+          content: z.record(z.string(), z.unknown()),
+        }),
+      )
+      .length(1)
+      .refine(
+        (a) => new TextEncoder().encode(JSON.stringify(a)).length <= TEAMS_ATTACHMENTS_MAX_BYTES,
+        { message: `attachments must serialise to at most ${TEAMS_ATTACHMENTS_MAX_BYTES} bytes` },
+      )
+      .optional(),
   });
   registerWriteTool(
     "teams_chat_post",
@@ -276,7 +293,7 @@ export function registerTeamsTools(
     "Post an operational bot message to a Teams conversation (ChatOps reply surface; bot app creds).",
     teamsChatPostSchema,
     async (parsed) => {
-      const r = await teamsBotSendActivity(parsed.conversationId, parsed.text);
+      const r = await teamsBotSendActivity(parsed.conversationId, parsed.text, parsed.attachments);
       return graphListResult(r);
     },
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nimbus-dev/connectors",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "publishConfig": {
     "access": "public"
   },

package/shared/audit-chain.ts

@@ -23,7 +23,9 @@ import { setTimeout as sleep } from "node:timers/promises";
  * `out of scope` and `budget exhausted` are decided before any prompt. `budget exhausted after
  * approval` follows an `accepted` entry: writes in flight together spent the last of the budget
  * while this one's prompt was open, so a human approved a write that then did not run. A client
- * that cannot prompt is never offered a write tool at all, so it leaves no entry.
+ * that cannot prompt is never offered a write tool at all, so it leaves no entry. `prepared` is a
+ * prepare-class tool (consent-kit.ts) that ran in scope: it changes nothing and spends no budget,
+ * but the operator can see what was read on a write's behalf.
  */
 export type AuditOutcome =
   | "requested"
@@ -31,7 +33,8 @@ export type AuditOutcome =
   | "declined"
   | "refused"
   | "executed"
-  | "failed";
+  | "failed"
+  | "prepared";
 
 export type AuditEntry = {
   readonly ts: string;