@nimbus-dev/connectors 0.3.0 → 0.5.0

package/connectors/apple/src/calendar-tools.ts

@@ -43,15 +43,59 @@ const listArgs = z.object({
   calendar: z.string().min(1).optional(),
 });
 
+/** A C0 control (CR, LF and TAB included), DEL, or a C1 control. */
+function isControlCode(code: number): boolean {
+  return code <= 0x1f || (code >= 0x7f && code <= 0x9f);
+}
+
+/**
+ * Whether `value` carries a control character anywhere. Event text reaches iCalendar content
+ * lines, where CR or LF ends a line and starts a new property; the SDK's escaping turns CRLF or LF
+ * into an escaped newline but leaves a bare CR. So the input is REFUSED here rather than relying
+ * on (or adding) an escape. Nothing is stripped.
+ */
+export function hasControlCharacter(value: string): boolean {
+  for (let i = 0; i < value.length; i++) {
+    if (isControlCode(value.charCodeAt(i))) return true;
+  }
+  return false;
+}
+
+/** Whether `value` carries any whitespace (Unicode `\s`) or control character. */
+export function hasWhitespaceOrControl(value: string): boolean {
+  return /\s/u.test(value) || hasControlCharacter(value);
+}
+
+export const ICLOUD_TEXT_REFUSAL = "must not contain a line break or other control character";
+export const ICLOUD_TIME_REFUSAL =
+  "must be a UTC time in the form YYYYMMDDTHHMMSSZ; all-day and floating times are not supported";
+export const ICLOUD_UID_REFUSAL =
+  "must be 1 to 200 characters, each a letter, a digit, '.', '_', '@' or '-'";
+export const ICLOUD_ATTENDEE_REFUSAL =
+  "each attendee must be one email address, with no whitespace or control character";
+
+/** `YYYYMMDDTHHMMSSZ`: a UTC date-time and nothing else (owner ruling OR-B4-6). */
+const UTC_DATE_TIME = /^\d{8}T\d{6}Z$/;
+const EVENT_UID = /^[A-Za-z0-9._@-]{1,200}$/;
+
+/** A free-text event field: refused, never cleaned, when it carries a control character. */
+function eventText(): z.ZodString {
+  return z.string().refine((s) => !hasControlCharacter(s), ICLOUD_TEXT_REFUSAL);
+}
+
 const createArgs = z.object({
-  calendar: z.string().min(1).optional(),
-  summary: z.string().min(1).max(1000),
-  start: z.string().min(1),
-  end: z.string().min(1),
-  description: z.string().max(10_000).optional(),
-  location: z.string().max(500).optional(),
-  attendees: z.array(z.email()).optional(),
-  uid: z.string().min(1).optional(),
+  calendar: eventText().min(1).optional(),
+  summary: eventText().min(1).max(1000),
+  start: z.string().regex(UTC_DATE_TIME, ICLOUD_TIME_REFUSAL),
+  end: z.string().regex(UTC_DATE_TIME, ICLOUD_TIME_REFUSAL),
+  description: eventText().max(10_000).optional(),
+  location: eventText().max(500).optional(),
+  // z.email() already refuses whitespace and controls today; the explicit check keeps that a
+  // stated property of THIS schema, not of zod's current email pattern.
+  attendees: z
+    .array(z.email().refine((s) => !hasWhitespaceOrControl(s), ICLOUD_ATTENDEE_REFUSAL))
+    .optional(),
+  uid: z.string().regex(EVENT_UID, ICLOUD_UID_REFUSAL).optional(),
 });
 
 const deleteArgs = z.object({
@@ -199,7 +243,7 @@ export function registerAppleCalendarTools(
       recoverable: true,
       scopeTargetOf: (p) => ({ kind: "calendar", value: p.calendar ?? "default" }),
     },
-    "Create a new event in iCloud Calendar via CalDAV PUT.",
+    "Create a new event in iCloud Calendar via CalDAV PUT. start and end are UTC, in the form YYYYMMDDTHHMMSSZ (all-day and floating times are refused). summary, description, location and calendar may not contain a line break or other control character; uid, when given, is 1-200 of A-Z a-z 0-9 . _ @ -.",
     createArgs,
     async (parsedData) => {
       const parsed = { success: true as const, data: parsedData };

package/connectors/confluence/src/tools.ts

@@ -11,6 +11,7 @@ import { parseCitationsJson } from "../../../shared/kb-markdown.ts";
 import {
   createRegisterSimpleTool,
   createZodToolRegistrar,
+  mcpJsonResult,
   mcpJsonResultFromTextIfOk,
 } from "../../../shared/mcp-tool-kit.ts";
 import { buildConfluenceKbPageBody } from "./kb-append.ts";
@@ -40,6 +41,67 @@ async function confFetch(
   return fetchAtlassianBasicAuthJsonText(url, email, token, init);
 }
 
+/** The parts of a page `confluence_page_append` reads and writes back. */
+interface PageSnapshot {
+  readonly type: string;
+  readonly title: string;
+  readonly version: number;
+  readonly html: string;
+}
+
+/** Parse `GET /content/{id}?expand=body.storage,version`; throws, quoting Confluence, on a failure. */
+function readPageSnapshot(res: { ok: boolean; status: number; text: string }): PageSnapshot {
+  if (!res.ok) {
+    throw new Error(`Confluence ${String(res.status)}: ${res.text.slice(0, 400)}`);
+  }
+  const page = JSON.parse(res.text) as {
+    type?: string;
+    title?: string;
+    version?: { number?: number };
+    body?: { storage?: { value?: string } };
+  };
+  if (page.version?.number === undefined) {
+    throw new Error("Confluence: page has no version");
+  }
+  return {
+    type: page.type ?? "page",
+    title: page.title ?? "",
+    version: page.version.number,
+    html: page.body?.storage?.value ?? "",
+  };
+}
+
+/** One entry of `confluence_page_get`'s `ancestors`: what a caller needs, not the whole page. */
+export interface PageAncestor {
+  readonly id: string | null;
+  readonly title: string | null;
+}
+
+/**
+ * Narrow the `ancestors` Confluence expands on a page to `{ id, title }` per entry, in Confluence's
+ * order (the space's top-level page first, the page's direct parent last). An ancestor is a whole
+ * content object (links, extensions, status); a caller deciding where a page sits needs only its
+ * id, and the title is free. An entry without a string id keeps its place with `id: null` rather
+ * than being dropped, so the chain is never shorter than Confluence said. A reply with no
+ * `ancestors` array is returned as it came: absent stays absent, never an invented `[]`.
+ */
+export function withAncestorSummaries(page: unknown): unknown {
+  if (page === null || typeof page !== "object" || Array.isArray(page)) return page;
+  const obj = page as Record<string, unknown>;
+  const ancestors = obj["ancestors"];
+  if (!Array.isArray(ancestors)) return page;
+  const summaries: PageAncestor[] = ancestors.map((a: unknown) => {
+    const entry = a !== null && typeof a === "object" ? (a as Record<string, unknown>) : {};
+    const id = entry["id"];
+    const title = entry["title"];
+    return {
+      id: typeof id === "string" ? id : null,
+      title: typeof title === "string" ? title : null,
+    };
+  });
+  return { ...obj, ancestors: summaries };
+}
+
 /** Tool names exposed by this connector — for contract/introspection tests. */
 export const CONFLUENCE_TOOL_NAMES = [
   "confluence_space_list",
@@ -52,6 +114,7 @@ export const CONFLUENCE_TOOL_NAMES = [
   "confluence_kb_append",
   "confluence_page_update",
   "confluence_comment_add",
+  "confluence_page_append",
 ] as const;
 
 export function registerConfluenceTools(
@@ -118,14 +181,23 @@ export function registerConfluenceTools(
 
   reg(
     "confluence_page_get",
-    "Get a Confluence page with body.storage (GET /content/{id}).",
+    "Get a Confluence page with body.storage (GET /content/{id}). ancestors lists the pages above it as { id, title }, the top-level page first and the direct parent last.",
     confluencePageIdSchema,
     async (parsed) => {
       const id = encodeURIComponent(parsed.pageId);
       const res = await confFetch(
-        `/content/${id}?expand=body.storage,version,history.lastUpdated,space`,
+        `/content/${id}?expand=body.storage,version,history.lastUpdated,space,ancestors`,
       );
-      return mcpJsonResultFromTextIfOk("Confluence", res);
+      if (!res.ok) {
+        throw new Error(`Confluence ${String(res.status)}: ${res.text.slice(0, 400)}`);
+      }
+      let page: unknown;
+      try {
+        page = JSON.parse(res.text) as unknown;
+      } catch {
+        throw new Error("Confluence: invalid JSON response");
+      }
+      return mcpJsonResult(withAncestorSummaries(page));
     },
   );
 
@@ -317,4 +389,63 @@ export function registerConfluenceTools(
       return mcpJsonResultFromTextIfOk("Confluence", res);
     },
   );
+
+  const confluencePageAppendSchema = z.object({
+    pageId: z.string().min(1),
+    storageHtml: z.string().min(1).max(65_000),
+  });
+
+  registerWriteTool(
+    "confluence_page_append",
+    {
+      mutates: "confluence.page.append",
+      // Confluence keeps every version of a page, so the previous body is one click away. No
+      // capturePreState on purpose: it would run once, before a retry, and describe a version that
+      // may not be the one this call changes.
+      recoverable: true,
+      scopeTargetOf: (p) => ({ kind: "page", value: p.pageId }),
+    },
+    "Append storage-format HTML to the END of a Confluence page, keeping everything already on it (GET then PUT /content/{id}); if the page changes while this runs it re-reads and retries once, then fails without writing.",
+    confluencePageAppendSchema,
+    async (parsed) => {
+      const id = encodeURIComponent(parsed.pageId);
+      // The fetch helper returns `{ ok, status, text }` without throwing, so the retry lives here.
+      // Each attempt re-reads the page, so it appends to the body as it is NOW.
+      for (let attempt = 1; attempt <= 2; attempt++) {
+        const page = readPageSnapshot(
+          await confFetch(`/content/${id}?expand=body.storage,version`),
+        );
+        const next = page.version + 1;
+        const put = await confFetch(`/content/${id}`, {
+          method: "PUT",
+          body: JSON.stringify({
+            type: page.type,
+            title: page.title,
+            version: { number: next, message: "nimbus" },
+            body: {
+              storage: { value: page.html + parsed.storageHtml, representation: "storage" },
+            },
+          }),
+        });
+        if (put.status === 409 && attempt === 1) {
+          continue;
+        }
+        if (put.status === 409) {
+          throw new Error("Confluence: page changed concurrently; nothing appended");
+        }
+        if (!put.ok) {
+          throw new Error(`Confluence ${String(put.status)}: ${put.text.slice(0, 400)}`);
+        }
+        let version = next;
+        try {
+          const written = JSON.parse(put.text) as { version?: { number?: number } };
+          version = written.version?.number ?? next;
+        } catch {
+          // A non-JSON success body: the version we sent is the one that was written.
+        }
+        return mcpJsonResult({ ok: true, pageId: parsed.pageId, version });
+      }
+      throw new Error("Confluence: page changed concurrently; nothing appended");
+    },
+  );
 }

package/connectors/discord/nimbus.extension.json

@@ -2,14 +2,14 @@
   "id": "com.nimbus.discord",
   "displayName": "Discord",
   "version": "0.1.0",
-  "description": "Discord opt-in connector (guilds, channels, messages). Disabled by default. Mutations require Gateway HITL.",
+  "description": "Discord opt-in connector (guilds, channels, messages; posts as the bot). Disabled by default. Mutations require Gateway HITL.",
   "author": "Nimbus",
   "entrypoint": "dist/server.js",
   "runtime": "bun",
   "permissions": {
     "network": ["discord.com", "gateway.discord.gg", "cdn.discordapp.com"]
   },
-  "hitlRequired": [],
+  "hitlRequired": ["write"],
   "syncInterval": 120,
   "minNimbusVersion": "0.2.0"
 }

package/connectors/discord/src/server.ts

@@ -1,8 +1,21 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CONSENT_SERVER_CAPABILITIES } from "../../../shared/consent-kit.ts";
 import { registerDiscordTools } from "./tools.ts";
 
-const server = new McpServer({ name: "nimbus-discord", version: "0.1.0" });
+const server = new McpServer(
+  { name: "nimbus-discord", version: "0.1.0" },
+  {
+    capabilities: CONSENT_SERVER_CAPABILITIES,
+    // Machine-readable security tiering, so a client can surface it rather than relying on a
+    // human having read the NOTICE file.
+    instructions:
+      "Nimbus Discord connector. Standalone: the message-post tool requires MCP elicitation " +
+      "consent and is limited by NIMBUS_MCP_DISCORD_WRITE_SCOPE (channel:<id>); it is not " +
+      "registered at all if this client does not support elicitation. No sandbox, no OS keychain " +
+      "and no egress ledger outside the Nimbus gateway. See NOTICE.",
+  },
+);
 
 registerDiscordTools(server);
 

package/connectors/discord/src/tools.ts

@@ -1,5 +1,11 @@
 import { z } from "zod";
-import { createRegisterSimpleTool, createZodToolRegistrar } from "../../../shared/mcp-tool-kit.ts";
+import { type ConsentServer, createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
+import {
+  createRegisterSimpleTool,
+  createZodToolRegistrar,
+  mcpJsonResult,
+  requireProcessEnv,
+} from "../../../shared/mcp-tool-kit.ts";
 import {
   makeRestToolRegistrar,
   type RestFetchResult,
@@ -25,10 +31,32 @@ async function discordFetch(
   return toRestFetchResult(res);
 }
 
-export function registerDiscordTools(server: { tool: (...args: never) => unknown }): void {
+/** Tool names exposed by this connector — for contract/introspection tests. */
+export const DISCORD_TOOL_NAMES = [
+  "discord_guild_list",
+  "discord_channel_list",
+  "discord_channel_messages",
+  "discord_thread_list",
+  "discord_message_post",
+] as const;
+
+export function registerDiscordTools(
+  server: ConsentServer & { tool: (...args: never) => unknown },
+): void {
   const registerSimpleTool = createRegisterSimpleTool(server);
   const reg = createZodToolRegistrar(registerSimpleTool);
 
+  /**
+   * Every MUTATING discord tool goes through here. Outside the gateway this adds the consent gate,
+   * the write-scope allow-list (`channel:<id>`), the mutation budget and the audit record; inside
+   * the gateway it is a pass-through, because executor.ts (I2) is the gate there.
+   */
+  const registerWriteTool = createWriteToolRegistrar(server, {
+    connector: "discord",
+    scopeEnv: "NIMBUS_MCP_DISCORD_WRITE_SCOPE",
+    scopeKinds: ["channel"],
+  });
+
   /** Standard Discord read tool: token → discordFetch(buildPath) → mcpJsonResultIfOk("Discord"). */
   const registerDiscordTool = makeRestToolRegistrar({
     registrar: reg,
@@ -79,4 +107,38 @@ export function registerDiscordTools(server: { tool: (...args: never) => unknown
     z.object({ guildId: z.string().min(1) }),
     (parsed) => `/guilds/${encodeURIComponent(parsed.guildId)}/threads/active`,
   );
+
+  registerWriteTool(
+    "discord_message_post",
+    {
+      mutates: "discord.message.post",
+      // A posted message is visible to the channel at once and cannot be unsent from here, but the
+      // post is the whole effect and its id is returned, so it is not an unrecoverable data loss.
+      recoverable: true,
+      scopeTargetOf: (p) => ({ kind: "channel", value: p.channelId }),
+    },
+    "Post a message to a Discord channel AS THE BOT (not as the user). Only user mentions are active: @everyone, @here and role mentions are sent as plain text.",
+    z.object({
+      channelId: z.string().regex(/^\d{17,20}$/, "channelId is a Discord snowflake (17-20 digits)"),
+      content: z.string().min(1).max(2000),
+    }),
+    async (parsed) => {
+      const token = requireProcessEnv("DISCORD_BOT_TOKEN");
+      const res = await discordFetch(token, `/channels/${parsed.channelId}/messages`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          content: parsed.content,
+          // Owner ruling: user mentions only. Without an explicit `parse` Discord resolves every
+          // mention in the text, so a model-written "@everyone" would ping the whole guild.
+          allowed_mentions: { parse: ["users"] },
+        }),
+      });
+      if (!res.ok) {
+        throw new Error(`Discord ${String(res.status)}: ${res.text.slice(0, 300)}`);
+      }
+      const created = res.json as { id?: unknown } | null;
+      return mcpJsonResult({ id: created?.id, channelId: parsed.channelId });
+    },
+  );
 }

package/connectors/github/src/tools.ts

@@ -28,6 +28,10 @@ export const GITHUB_TOOL_NAMES = [
   "github_issue_list",
   "github_issue_get",
   "github_issue_create",
+  "github_issue_comment_create",
+  "github_issue_labels_add",
+  "github_issue_assignees_add",
+  "github_issue_state_set",
   "github_ci_runs",
   "github_ci_run_get",
   "github_branch_delete",
@@ -214,6 +218,52 @@ export function registerGithubTools(
     (parsed) => jsonInit("POST", { title: parsed.title, body: parsed.body }),
   );
 
+  const githubIssueNumberSchema = repoSlugArgs.extend({
+    issueNumber: z.number().int().min(1),
+  });
+  const issuePath = (parsed: z.infer<typeof githubIssueNumberSchema>): string =>
+    `${ghRepoPath(parsed.owner, parsed.repo)}/issues/${String(parsed.issueNumber)}`;
+
+  registerGithubWriteTool(
+    "github_issue_comment_create",
+    { mutates: "github.issue.comment.create", recoverable: true },
+    "Add a comment to an issue or a pull request's conversation (pull requests are issues to GitHub); it posts as the authenticated user and changes nothing else.",
+    githubIssueNumberSchema.extend({ body: z.string().min(1).max(65_000) }),
+    (parsed) => `${issuePath(parsed)}/comments`,
+    (parsed) => jsonInit("POST", { body: parsed.body }),
+  );
+
+  registerGithubWriteTool(
+    "github_issue_labels_add",
+    { mutates: "github.issue.labels.add", recoverable: true },
+    "Add labels to an issue or pull request; a label that does not exist yet is created in the repository. It only adds, and cannot remove or replace any existing label.",
+    githubIssueNumberSchema.extend({
+      labels: z.array(z.string().min(1).max(50)).min(1).max(100),
+    }),
+    (parsed) => `${issuePath(parsed)}/labels`,
+    (parsed) => jsonInit("POST", { labels: parsed.labels }),
+  );
+
+  registerGithubWriteTool(
+    "github_issue_assignees_add",
+    { mutates: "github.issue.assignees.add", recoverable: true },
+    "Add assignees to an issue or pull request; it only adds, and cannot remove any existing assignee.",
+    githubIssueNumberSchema.extend({
+      assignees: z.array(z.string().min(1).max(39)).min(1).max(10),
+    }),
+    (parsed) => `${issuePath(parsed)}/assignees`,
+    (parsed) => jsonInit("POST", { assignees: parsed.assignees }),
+  );
+
+  registerGithubWriteTool(
+    "github_issue_state_set",
+    { mutates: "github.issue.state.set", recoverable: true },
+    "Open or close an issue (state open or closed); given a pull request number it closes or reopens that pull request. It changes only the state and can be reversed by setting it back.",
+    githubIssueNumberSchema.extend({ state: z.enum(["open", "closed"]) }),
+    issuePath,
+    (parsed) => jsonInit("PATCH", { state: parsed.state }),
+  );
+
   const githubCiRunsSchema = repoSlugArgs.extend({
     perPage: z.number().int().min(1).max(100).optional(),
     page: z.number().int().min(1).optional(),

package/connectors/github-actions/src/tools.ts

@@ -3,8 +3,8 @@ import type { ConsentServer } from "../../../shared/consent-kit.ts";
 import { createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
 import {
   GH_ACCEPT,
-  GH_API,
   GH_API_VERSION,
+  ghApiBase,
   ghFetch,
   ghQueryPath,
   ghRepoPath,
@@ -122,15 +122,27 @@ export function registerGithubActionsTools(
     }),
     async (parsed) => {
       const token = requireProcessEnv("GITHUB_PAT");
-      const url = `${GH_API}${ghRepoPath(parsed.owner, parsed.repo)}/actions/jobs/${String(parsed.jobId)}/logs`;
-      const res = await fetch(url, {
+      const url = `${ghApiBase()}${ghRepoPath(parsed.owner, parsed.repo)}/actions/jobs/${String(parsed.jobId)}/logs`;
+      // The log lives in third-party storage behind a redirect, so the redirect is followed BY HAND:
+      // the token goes to the API host only, never to wherever the Location points.
+      let res = await fetch(url, {
         headers: {
           Accept: GH_ACCEPT,
           Authorization: `Bearer ${token}`,
           "X-GitHub-Api-Version": GH_API_VERSION,
         },
-        redirect: "follow",
+        redirect: "manual",
       });
+      const location = res.status >= 300 && res.status < 400 ? res.headers.get("location") : null;
+      if (location !== null) {
+        const target = new URL(location, url);
+        // The Location is the server's to choose: only https (or http when the API base itself
+        // is http, e.g. an internal GHES) is followed, never file:, ftp: or the like.
+        if (target.protocol !== "https:" && target.protocol !== new URL(url).protocol) {
+          throw new Error(`GitHub Actions logs: refusing to follow a ${target.protocol} redirect`);
+        }
+        res = await fetch(target.href, { redirect: "follow" });
+      }
       const text = await res.text();
       if (!res.ok) {
         throw new Error(`GitHub Actions logs ${String(res.status)}: ${text.slice(0, 400)}`);

package/connectors/gitlab/src/tools.ts

@@ -76,6 +76,35 @@ const stateListUrl =
       setPaging(q, parsed);
     });
 
+/** `<origin>/api/graphql` for the configured REST base, with or without its `/api/v4` suffix. */
+function graphqlUrl(): string {
+  return `${apiBase().replace(/\/api\/v4$/, "")}/api/graphql`;
+}
+
+/** APPEND is the whole point: REPLACE would drop the assignees already on the issue. */
+const SET_ASSIGNEES_APPEND =
+  "mutation($projectPath: ID!, $iid: String!, $assigneeUsernames: [String!]!) {" +
+  " issueSetAssignees(input: { projectPath: $projectPath, iid: $iid," +
+  " assigneeUsernames: $assigneeUsernames, operationMode: APPEND }) { errors } }";
+
+/** The first GraphQL failure in a response (transport-level or the mutation's own), if any. */
+function graphqlFailure(json: unknown): string | undefined {
+  const body = json as {
+    errors?: readonly { message?: string }[];
+    data?: { issueSetAssignees?: { errors?: readonly string[] } | null } | null;
+  } | null;
+  if (body?.errors !== undefined && body.errors.length > 0) {
+    return body.errors.map((e) => e.message ?? "unknown error").join("; ");
+  }
+  const inner = body?.data?.issueSetAssignees;
+  if (inner === undefined || inner === null) {
+    return "no issueSetAssignees result";
+  }
+  return inner.errors !== undefined && inner.errors.length > 0
+    ? inner.errors.join("; ")
+    : undefined;
+}
+
 /** A CI job's whole plain-text trace; throws, quoting GitLab, on a non-ok status. */
 async function fetchJobTrace(parsed: {
   readonly projectPath: string;
@@ -100,6 +129,12 @@ export const GITLAB_TOOL_NAMES = [
   "gitlab_mr_merge",
   "gitlab_issue_list",
   "gitlab_issue_get",
+  "gitlab_issue_create",
+  "gitlab_issue_note_create",
+  "gitlab_mr_note_create",
+  "gitlab_issue_labels_add",
+  "gitlab_issue_assignees_add",
+  "gitlab_issue_state_set",
   "gitlab_pipeline_list",
   "gitlab_pipeline_get",
   "gitlab_pipeline_jobs_get",
@@ -270,6 +305,122 @@ export function registerGitlabTools(
       `/projects/${encodeURIComponent(parsed.projectPath)}/issues/${String(parsed.issueIid)}`,
   );
 
+  /** One label: GitLab joins a label list with commas, so a comma inside one would split it in two. */
+  const labelSchema = z
+    .string()
+    .min(1)
+    .max(255)
+    .refine((l) => !l.includes(","), "a label cannot contain a comma");
+  const assigneeIdSchema = z.number().int().min(1);
+  const noteBodySchema = z.string().min(1).max(65_000);
+  const issuePath = (p: { projectPath: string; issueIid: number }): string =>
+    `/projects/${encodeURIComponent(p.projectPath)}/issues/${String(p.issueIid)}`;
+  const jsonBody = (method: "POST" | "PUT", body: unknown): RequestInit => ({
+    method,
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+
+  registerGitlabWriteTool(
+    "gitlab_issue_create",
+    { mutates: "gitlab.issue.create", recoverable: true },
+    "Create a new issue in a project, optionally with labels and assignees.",
+    projectPathArg.extend({
+      title: z.string().min(1).max(255),
+      description: z.string().max(65_000).optional(),
+      labels: z.array(labelSchema).max(50).optional(),
+      assigneeIds: z.array(assigneeIdSchema).max(20).optional(),
+    }),
+    (parsed) => `/projects/${encodeURIComponent(parsed.projectPath)}/issues`,
+    (parsed) =>
+      jsonBody("POST", {
+        title: parsed.title,
+        description: parsed.description,
+        labels: parsed.labels?.join(","),
+        assignee_ids: parsed.assigneeIds,
+      }),
+  );
+
+  registerGitlabWriteTool(
+    "gitlab_issue_note_create",
+    { mutates: "gitlab.issue.note.create", recoverable: true },
+    "Add a comment (note) to an issue; it posts as the authenticated user and changes nothing else.",
+    gitlabIssueGetSchema.extend({ body: noteBodySchema }),
+    (parsed) => `${issuePath(parsed)}/notes`,
+    (parsed) => jsonBody("POST", { body: parsed.body }),
+  );
+
+  registerGitlabWriteTool(
+    "gitlab_mr_note_create",
+    { mutates: "gitlab.mr.note.create", recoverable: true },
+    "Add a comment (note) to a merge request; it posts as the authenticated user and changes nothing else.",
+    gitlabMrGetSchema.extend({ body: noteBodySchema }),
+    (parsed) =>
+      `/projects/${encodeURIComponent(parsed.projectPath)}/merge_requests/${String(parsed.mergeRequestIid)}/notes`,
+    (parsed) => jsonBody("POST", { body: parsed.body }),
+  );
+
+  registerGitlabWriteTool(
+    "gitlab_issue_labels_add",
+    { mutates: "gitlab.issue.labels.add", recoverable: true },
+    "Add labels to an issue; it only adds, and cannot remove or replace any existing label.",
+    gitlabIssueGetSchema.extend({ labels: z.array(labelSchema).min(1).max(50) }),
+    issuePath,
+    (parsed) => jsonBody("PUT", { add_labels: parsed.labels.join(",") }),
+  );
+
+  // REST "Update an issue" can only REPLACE assignees (`assignee_ids`), so the add goes through
+  // GraphQL's issueSetAssignees in APPEND mode: one atomic server-side add that removes nobody.
+  registerWriteTool(
+    "gitlab_issue_assignees_add",
+    {
+      mutates: "gitlab.issue.assignees.add",
+      recoverable: true,
+      scopeTargetOf: (p) => ({ kind: "repo", value: p.projectPath }),
+    },
+    "Add assignees (usernames) to an issue; it only adds, and cannot remove any existing assignee.",
+    gitlabIssueGetSchema.extend({
+      assigneeUsernames: z.array(z.string().min(1).max(255)).min(1).max(20),
+    }),
+    async (parsed) => {
+      const token = requireProcessEnv("GITLAB_PAT");
+      // GitLab documents `Authorization: Bearer` for /api/graphql (PRIVATE-TOKEN is the REST
+      // header), so this one request bypasses glFetch. Never the private_token query parameter:
+      // a token in a URL is logged.
+      const res = await toRestFetchResult(
+        await fetch(graphqlUrl(), {
+          method: "POST",
+          headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+          body: JSON.stringify({
+            query: SET_ASSIGNEES_APPEND,
+            variables: {
+              projectPath: parsed.projectPath,
+              iid: String(parsed.issueIid),
+              assigneeUsernames: parsed.assigneeUsernames,
+            },
+          }),
+        }),
+      );
+      if (!res.ok) {
+        throw new Error(`GitLab ${String(res.status)}: ${res.text.slice(0, 300)}`);
+      }
+      const failure = graphqlFailure(res.json);
+      if (failure !== undefined) {
+        throw new Error(`GitLab GraphQL: ${failure}`);
+      }
+      return jsonResult({ ok: true, assignees: parsed.assigneeUsernames });
+    },
+  );
+
+  registerGitlabWriteTool(
+    "gitlab_issue_state_set",
+    { mutates: "gitlab.issue.state.set", recoverable: true },
+    "Close or reopen an issue (stateEvent close or reopen); it changes only the state and can be reversed.",
+    gitlabIssueGetSchema.extend({ stateEvent: z.enum(["close", "reopen"]) }),
+    issuePath,
+    (parsed) => jsonBody("PUT", { state_event: parsed.stateEvent }),
+  );
+
   const gitlabPipelineListSchema = projectPathArg.extend({
     ref: z.string().max(500).optional(),
     status: z.string().max(64).optional(),

package/connectors/jira/src/tools.ts

@@ -56,6 +56,8 @@ export const JIRA_TOOL_NAMES = [
   "jira_issue_create",
   "jira_issue_update",
   "jira_comment_add",
+  "jira_issue_transitions_list",
+  "jira_issue_transition",
   "jira_board_list",
   "jira_sprint_list",
   "jira_epic_list",
@@ -242,6 +244,77 @@ export function registerJiraTools(
     },
   );
 
+  reg(
+    "jira_issue_transitions_list",
+    "List the workflow transitions available to a Jira issue right now, with their ids and required fields (GET /rest/api/3/issue/{key}/transitions); read this before jira_issue_transition.",
+    jiraIssueKeySchema,
+    async (parsed) => {
+      const { baseUrl, email, token } = requireJiraConfig();
+      const key = encodeURIComponent(parsed.issueKey);
+      const res = await jiraFetch(
+        baseUrl,
+        email,
+        token,
+        `/rest/api/3/issue/${key}/transitions?expand=transitions.fields`,
+      );
+      return mcpJsonResultFromTextIfOk("Jira", res, {
+        jsonParseErrorMessage: "Jira: invalid JSON from transitions list",
+      });
+    },
+  );
+
+  const jiraIssueTransitionSchema = jiraIssueKeySchema.extend({
+    transitionId: z
+      .string()
+      .regex(/^\d{1,20}$/, "transitionId is the numeric id from jira_issue_transitions_list"),
+  });
+
+  registerWriteTool(
+    "jira_issue_transition",
+    {
+      mutates: "jira.issue.transition",
+      // Workflows are often one-way (Done cannot always be left), so the status the issue is in
+      // BEFORE the move is captured: it is the one thing the audit record needs to reverse it.
+      recoverable: false,
+      capturePreState: async (parsed) => {
+        const { baseUrl, email, token } = requireJiraConfig();
+        const key = encodeURIComponent(parsed.issueKey);
+        const res = await jiraFetch(
+          baseUrl,
+          email,
+          token,
+          `/rest/api/3/issue/${key}?fields=status`,
+        );
+        if (!res.ok) {
+          throw new Error(`Jira ${String(res.status)}: ${res.text.slice(0, 200)}`);
+        }
+        const json = JSON.parse(res.text) as {
+          fields?: { status?: { name?: string; id?: string } };
+        };
+        return { status: json.fields?.status?.name ?? json.fields?.status?.id };
+      },
+      scopeTargetOf: (p) => ({ kind: "issue", value: p.issueKey }),
+    },
+    "Move a Jira issue through its workflow with a transition id from jira_issue_transitions_list (POST /rest/api/3/issue/{key}/transitions); workflows can be one-way, so this may not be reversible.",
+    jiraIssueTransitionSchema,
+    async (parsed) => {
+      const { baseUrl, email, token } = requireJiraConfig();
+      const key = encodeURIComponent(parsed.issueKey);
+      const res = await jiraFetch(baseUrl, email, token, `/rest/api/3/issue/${key}/transitions`, {
+        method: "POST",
+        body: JSON.stringify({ transition: { id: parsed.transitionId } }),
+      });
+      if (!res.ok) {
+        throw new Error(`Jira ${String(res.status)}: ${res.text.slice(0, 400)}`);
+      }
+      return jsonResult({
+        ok: true,
+        issueKey: parsed.issueKey,
+        transitionId: parsed.transitionId,
+      });
+    },
+  );
+
   const jiraBoardListSchema = z.object({
     startAt: z.number().int().min(0).optional(),
     maxResults: z.number().int().min(1).max(50).optional(),

package/connectors/obsidian/nimbus.extension.json

@@ -2,7 +2,7 @@
   "id": "com.nimbus.obsidian",
   "displayName": "Obsidian",
   "version": "0.1.0",
-  "description": "Local Obsidian vault connector (notes, backlinks). No network. Vault paths come from [[filesystem.roots]] and are merged into permissions.filesystem at spawn time by the Gateway. obsidian_append_to_daily_note requires HITL.",
+  "description": "Local Obsidian vault connector (notes, backlinks, daily notes). No network. Vault paths come from [[filesystem.roots]] and are merged into permissions.filesystem.read at spawn time by the Gateway, which may also add the vaults to permissions.filesystem.write at spawn (only while the owner has approved obsidian_append_to_daily_note for the model). obsidian_append_to_daily_note requires HITL; obsidian_daily_note_get is a read.",
   "author": "Nimbus",
   "entrypoint": "dist/server.js",
   "runtime": "bun",

package/connectors/obsidian/src/tools.ts

@@ -2,11 +2,13 @@ import { createHash } from "node:crypto";
 import {
   closeSync,
   fstatSync,
+  lstatSync,
   mkdirSync,
   openSync,
   readdirSync,
   readFileSync,
   readSync,
+  realpathSync,
   statSync,
   writeSync,
 } from "node:fs";
@@ -54,6 +56,93 @@ function assertWithinVault(vaultRoot: string, relPath: string): string {
   return candidate;
 }
 
+/** Whether anything, a dangling link included, sits at `p`. */
+function pathEntryExists(p: string): boolean {
+  try {
+    lstatSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Refuse `abs` (a path `assertWithinVault` already accepted) when the place it really names is
+ * outside the vault: a folder or note that is, or passes through, a symlink or junction out of the
+ * vault. `assertWithinVault` compares strings, so it cannot see a link.
+ *
+ * The note, and the folders above it, may not exist yet (the append creates them), so the check
+ * resolves the deepest part of the path that does exist; whatever is created below it is created
+ * inside it. A dangling link cannot be resolved and is refused. The check and the later open are
+ * two system calls, so a link swapped in between them is not seen here: the gateway's sandbox,
+ * which grants only the vaults, is the boundary (stated bound).
+ */
+export function assertRealpathWithinVault(vaultRoot: string, abs: string, relPath: string): void {
+  const realRoot = realpathSync(resolve(vaultRoot));
+  const prefix = realRoot.endsWith(sep) ? realRoot : realRoot + sep;
+  let probe = abs;
+  while (!pathEntryExists(probe)) {
+    const parent = dirname(probe);
+    if (parent === probe) break;
+    probe = parent;
+  }
+  let real: string;
+  try {
+    real = realpathSync(probe);
+  } catch {
+    throw new Error(`Path escapes vault: ${relPath}`);
+  }
+  if (real !== realRoot && !real.startsWith(prefix)) {
+    throw new Error(`Path escapes vault: ${relPath}`);
+  }
+}
+
+/** How much of the end of a daily note `obsidian_daily_note_get` returns. */
+export const DAILY_NOTE_TAIL_BYTES = 16 * 1024;
+
+/** The positioned-read signature of `readSync`, injectable so a test can count what is read. */
+export type PositionedRead = (
+  fd: number,
+  buffer: Buffer,
+  offset: number,
+  length: number,
+  position: number,
+) => number;
+
+/**
+ * The size of the file at `abs` and its last `maxBytes` bytes, decoded as UTF-8.
+ *
+ * Positioned reads of at most `maxBytes` in all, never the whole file. When the window starts
+ * inside the file, the UTF-8 continuation bytes it begins with (the rest of a character the window
+ * cut) are dropped, so the tail starts on a character boundary.
+ */
+export function readUtf8Tail(
+  abs: string,
+  maxBytes: number,
+  read: PositionedRead = readSync,
+): { size: number; tail: string } {
+  const fd = openSync(abs, "r");
+  try {
+    const size = fstatSync(fd).size;
+    const start = Math.max(0, size - maxBytes);
+    const length = size - start;
+    const buf = Buffer.alloc(length);
+    let got = 0;
+    while (got < length) {
+      const n = read(fd, buf, got, length - got, start + got);
+      if (n <= 0) break;
+      got += n;
+    }
+    let skip = 0;
+    if (start > 0) {
+      while (skip < 3 && skip < got && ((buf[skip] ?? 0) & 0xc0) === 0x80) skip++;
+    }
+    return { size, tail: buf.subarray(skip, got).toString("utf8") };
+  } finally {
+    closeSync(fd);
+  }
+}
+
 function loadVaultPaths(): readonly string[] {
   const raw = requireProcessEnv("OBSIDIAN_VAULT_PATHS_JSON");
   let parsed: unknown;
@@ -98,7 +187,10 @@ function walkForVaults(dir: string, out: VaultEntry[]): void {
     const sub = join(dir, e);
     let isDir = false;
     try {
-      const st = statSync(sub);
+      // lstat, not stat: stat follows a link, so its isSymbolicLink() was always false and
+      // discovery used to find a vault through a symlink or junction outside the configured root.
+      // Every link below a root is skipped, so a discovered vault is physically under its root.
+      const st = lstatSync(sub);
       isDir = st.isDirectory() && !st.isSymbolicLink();
     } catch {
       continue;
@@ -128,7 +220,9 @@ function walkNotes(currentDir: string, vaultRoot: string, out: string[]): void {
     let isFile = false;
     let isDir = false;
     try {
-      const st = statSync(full);
+      // lstat, not stat: stat follows a link, so its isSymbolicLink() is always false and the
+      // walk used to list notes through a symlink or junction, out of the vault included.
+      const st = lstatSync(full);
       if (st.isSymbolicLink()) continue;
       isFile = st.isFile();
       isDir = st.isDirectory();
@@ -151,6 +245,7 @@ function readNote(
   relPath: string,
 ): { title: string; body: string; raw: string } {
   const abs = assertWithinVault(vaultRoot, relPath);
+  assertRealpathWithinVault(vaultRoot, abs, relPath);
   const raw = readFileSync(abs, "utf8");
   const m = FRONTMATTER_RE.exec(raw);
   const body = m === null ? raw : raw.slice(m[0].length);
@@ -193,6 +288,7 @@ export const OBSIDIAN_TOOL_NAMES = [
   "obsidian_get",
   "obsidian_search",
   "obsidian_append_to_daily_note",
+  "obsidian_daily_note_get",
 ] as const;
 
 /** The date tokens an Obsidian daily-note filename format may contain. */
@@ -400,6 +496,28 @@ export function registerObsidianTools(
     }),
   );
 
+  /**
+   * The vault and the daily note a daily-note tool names: ONE resolution, shared by the append and
+   * the read, so the read shows exactly the note the append would write. String containment
+   * (`assertWithinVault`) and then realpath containment (`assertRealpathWithinVault`).
+   */
+  function resolveDailyNote(parsed: { vault_id: string; date_iso?: string | undefined }): {
+    v: VaultEntry;
+    rel: string;
+    abs: string;
+  } {
+    const v = findVaultByIdOrPathPrefix(VAULTS, parsed.vault_id);
+    if (v === undefined) {
+      throw new Error("Unknown vault_id");
+    }
+    const date =
+      parsed.date_iso === undefined ? new Date() : new Date(`${parsed.date_iso}T00:00:00Z`);
+    const rel = resolveDailyNoteRelativePath(v.root, date);
+    const abs = assertWithinVault(v.root, rel);
+    assertRealpathWithinVault(v.root, abs, rel);
+    return { v, rel, abs };
+  }
+
   const appendDailyNoteSchema = z.object({
     vault_id: z.string().min(1),
     content: z.string().min(1),
@@ -420,15 +538,10 @@ export function registerObsidianTools(
     "Append text to today's Obsidian daily note. Creates the file if it does not exist. Always appends — never overwrites. Adds a leading newline when the existing file does not end in one. Requires HITL `obsidian.note.append`.",
     appendDailyNoteSchema,
     syncToolHandler((parsed) => {
-      const v = findVaultByIdOrPathPrefix(VAULTS, parsed.vault_id);
-      if (v === undefined) {
-        throw new Error("Unknown vault_id");
-      }
-      const date =
-        parsed.date_iso === undefined ? new Date() : new Date(`${parsed.date_iso}T00:00:00Z`);
-      const rel = resolveDailyNoteRelativePath(v.root, date);
-      const abs = assertWithinVault(v.root, rel);
+      const { v, rel, abs } = resolveDailyNote(parsed);
       mkdirSync(dirname(abs), { recursive: true });
+      // Again, now the folders exist: what was created must still be inside the vault.
+      assertRealpathWithinVault(v.root, abs, rel);
 
       const fd = openSync(abs, "a+");
       let bytes = 0;
@@ -463,4 +576,39 @@ export function registerObsidianTools(
       });
     }),
   );
+
+  const dailyNoteGetSchema = z.object({
+    vault_id: z.string().min(1),
+    date_iso: z
+      .string()
+      .regex(/^\d{4}-\d{2}-\d{2}$/)
+      .optional(),
+  });
+
+  reg(
+    "obsidian_daily_note_get",
+    `Read the end of the Obsidian daily note that obsidian_append_to_daily_note would write for the same vault_id and date_iso (today in UTC when omitted). Returns { vault_id, vault_name, path, exists, size_bytes, tail }: tail is at most the last ${String(DAILY_NOTE_TAIL_BYTES)} bytes, starting on a character boundary; a missing note is exists: false, size_bytes: 0, tail "". Read-only.`,
+    dailyNoteGetSchema,
+    syncToolHandler((parsed) => {
+      const { v, rel, abs } = resolveDailyNote(parsed);
+      let exists = false;
+      let size = 0;
+      let tail = "";
+      if (pathEntryExists(abs)) {
+        if (!statSync(abs).isFile()) {
+          throw new Error(`Daily note is not a file: ${rel}`);
+        }
+        exists = true;
+        ({ size, tail } = readUtf8Tail(abs, DAILY_NOTE_TAIL_BYTES));
+      }
+      return jsonResult({
+        vault_id: v.id,
+        vault_name: v.name,
+        path: rel,
+        exists,
+        size_bytes: size,
+        tail,
+      });
+    }),
+  );
 }

package/connectors/outlook/src/tool-scope-policy.ts

@@ -3,6 +3,9 @@ const OUTLOOK_TOOL_MIN_SCOPES: Readonly<Record<string, readonly string[]>> = {
   outlook_mail_list: ["Mail.Read"],
   outlook_mail_read: ["Mail.Read"],
   outlook_mail_send: ["Mail.Send"],
+  // A draft is written into the mailbox, which Mail.Send alone does not allow. Mail.ReadWrite
+  // (owner ruling 2026-11-05) lets the tool create one; it cannot send it.
+  outlook_draft_create: ["Mail.ReadWrite"],
   outlook_calendar_list: ["Calendars.Read"],
   outlook_calendar_get: ["Calendars.Read"],
   outlook_calendar_create: ["Calendars.ReadWrite"],

package/connectors/outlook/src/tools.ts

@@ -37,12 +37,54 @@ function graphRequest(
   return makeRestFetcher({ apiBase: GRAPH, token })(pathOrUrl, init);
 }
 
+/** `a@x, ,b@y` as Graph recipients, empty entries dropped. */
+function graphRecipients(list: string): { emailAddress: { address: string } }[] {
+  return list
+    .split(",")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0)
+    .map((address) => ({ emailAddress: { address } }));
+}
+
+/** What `outlook_mail_send` and `outlook_draft_create` both build the message from. */
+interface MailFields {
+  readonly to: string;
+  readonly subject: string;
+  readonly body: string;
+  readonly contentType?: "text" | "html" | undefined;
+  readonly cc?: string | undefined;
+  readonly bcc?: string | undefined;
+}
+
+/**
+ * The Graph `message` resource: the body of `POST /me/messages` (a draft) and the `message` member
+ * of `POST /me/sendMail`. cc and bcc are left out when absent or empty.
+ */
+function graphMessage(data: MailFields): Record<string, unknown> {
+  const message: Record<string, unknown> = {
+    subject: data.subject,
+    body: {
+      contentType: (data.contentType ?? "text") === "html" ? "HTML" : "Text",
+      content: data.body,
+    },
+    toRecipients: graphRecipients(data.to),
+  };
+  if (data.cc !== undefined && data.cc !== "") {
+    message["ccRecipients"] = graphRecipients(data.cc);
+  }
+  if (data.bcc !== undefined && data.bcc !== "") {
+    message["bccRecipients"] = graphRecipients(data.bcc);
+  }
+  return message;
+}
+
 /** Tool names exposed by this connector — for contract/introspection tests. */
 export const OUTLOOK_TOOL_NAMES = [
   "outlook_mail_folders",
   "outlook_mail_list",
   "outlook_mail_read",
   "outlook_mail_send",
+  "outlook_draft_create",
   "outlook_calendar_list",
   "outlook_calendar_get",
   "outlook_calendar_create",
@@ -170,33 +212,10 @@ export function registerOutlookTools(
       outlookMailSendArgs,
       async (data) => {
         const token = requireProcessEnv("MICROSOFT_OAUTH_ACCESS_TOKEN");
-        const toList = data.to
-          .split(",")
-          .map((s) => s.trim())
-          .filter((s) => s.length > 0);
-        const message: Record<string, unknown> = {
-          subject: data.subject,
-          body: {
-            contentType: (data.contentType ?? "text") === "html" ? "HTML" : "Text",
-            content: data.body,
-          },
-          toRecipients: toList.map((addr) => ({
-            emailAddress: { address: addr },
-          })),
-        };
-        if (data.cc !== undefined && data.cc !== "") {
-          const ccList = data.cc
-            .split(",")
-            .map((s) => s.trim())
-            .filter((s) => s.length > 0);
-          message["ccRecipients"] = ccList.map((addr) => ({
-            emailAddress: { address: addr },
-          }));
-        }
         const r = await graphRequest(token, "/me/sendMail", {
           method: "POST",
           headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({ message, saveToSentItems: true }),
+          body: JSON.stringify({ message: graphMessage(data), saveToSentItems: true }),
         });
         if (!r.ok) {
           throw new Error(`Graph ${String(r.status)}: ${r.text.slice(0, 200)}`);
@@ -206,6 +225,37 @@ export function registerOutlookTools(
     );
   }
 
+  const outlookDraftCreateArgs = outlookMailSendArgs.extend({
+    bcc: headerLine({ max: 2000 }).optional(),
+  });
+
+  if (outlookToolShouldRegister("outlook_draft_create", grantedOutlookScopes)) {
+    registerWriteTool(
+      "outlook_draft_create",
+      {
+        mutates: "outlook.draft.create",
+        // The draft sits in Drafts until the owner deletes or sends it, and nothing is sent.
+        recoverable: true,
+        scopeTargetOf: (p) => ({ kind: "recipient", value: p.to }),
+      },
+      "Save an email as a DRAFT in the owner's Drafts folder via Microsoft Graph; it is not sent, and the owner reviews and sends it from Outlook.",
+      outlookDraftCreateArgs,
+      async (data) => {
+        const token = requireProcessEnv("MICROSOFT_OAUTH_ACCESS_TOKEN");
+        const r = await graphRequest(token, "/me/messages", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(graphMessage(data)),
+        });
+        if (!r.ok) {
+          throw new Error(`Graph ${String(r.status)}: ${r.text.slice(0, 200)}`);
+        }
+        const created = r.json as { id?: unknown; webLink?: unknown } | null;
+        return mcpJsonResult({ id: created?.id, webLink: created?.webLink });
+      },
+    );
+  }
+
   const outlookCalendarListArgs = z.object({
     startDateTime: z.string().min(1),
     endDateTime: z.string().min(1),

package/connectors/readwise/nimbus.extension.json

@@ -1,7 +1,7 @@
 {
   "id": "com.nimbus.readwise",
   "displayName": "Readwise",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Readwise connector (read-only). Surfaces the user's saved book/article highlights as `readwise:highlight` items in the local index — the highlighted excerpt text, the user's note, the parent book/article id, the location + location type, the color, tags, and the source article URL (for web highlights) — plus their parent books/articles as `readwise:book` items (title, author, category, source, highlight count, document note, tags, ASIN, source + Readwise book-review URLs), so a highlight's `book_id` resolves to a real indexed record. Useful for answering reading questions (\"what did I highlight about retries?\", \"which book was that note in?\") without leaving Nimbus. Token API-token auth (`Authorization: Token <token>` — Django-REST-Framework token auth, NOT Bearer). The SaaS host (readwise.io) is fixed. Readwise paginates both `/api/v2/highlights/` and `/api/v2/books/` by page number (DRF `{ count, next, previous, results }` envelope, page_size=1000). `highlighted_at` / `last_highlight_at` / `updated` are ISO-8601 (converted to epoch-ms on index). Book `external_id`s are namespaced `book/<id>` because Readwise numbers books and highlights in separate sequences. Documents / daily-review and the Reader v3 API remain deferred follow-ups.",
   "author": "Nimbus",
   "entrypoint": "dist/server.js",

package/package.json

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

package/shared/github-rest.ts

@@ -8,10 +8,19 @@
  * places, so a bump had to find all three.
  */
 
+import { optionalBaseUrl } from "./env-json-api.ts";
 import { makeRestFetcher, type RestFetchResult } from "./rest-tool-kit.ts";
 
 export const GH_API = "https://api.github.com";
 
+/**
+ * The API base in force: `GITHUB_API_BASE_URL` (a GitHub Enterprise Server `https://host/api/v3`),
+ * else {@link GH_API}. Read per call, so a test or an operator can change it without a restart.
+ */
+export function ghApiBase(): string {
+  return optionalBaseUrl("GITHUB_API_BASE_URL", GH_API);
+}
+
 /** The media type GitHub documents for its REST API. */
 export const GH_ACCEPT = "application/vnd.github+json";
 
@@ -24,9 +33,9 @@ export const GH_HEADERS: Record<string, string> = {
   "X-GitHub-Api-Version": GH_API_VERSION,
 };
 
-/** A Bearer-authenticated JSON request against {@link GH_API} (a relative path or a same-origin URL). */
+/** A Bearer-authenticated JSON request against {@link ghApiBase} (a relative path or a same-origin URL). */
 export function ghFetch(token: string, path: string, init?: RequestInit): Promise<RestFetchResult> {
-  return makeRestFetcher({ apiBase: GH_API, token, defaultHeaders: GH_HEADERS })(path, init);
+  return makeRestFetcher({ apiBase: ghApiBase(), token, defaultHeaders: GH_HEADERS })(path, init);
 }
 
 /** `/repos/<owner>/<repo>`, both segments URI-encoded. */
@@ -56,6 +65,8 @@ export function setGhPaging(params: URLSearchParams, paging: GhPaging): void {
  * parameters keep the order `setQuery` sets them in.
  */
 export function ghQueryPath(path: string, setQuery: (params: URLSearchParams) => void): string {
+  // Parsed against the FIXED public origin, never the configured base: the result is relative to
+  // the base ghFetch prepends, so a GHES `/api/v3` must not be in it.
   const u = new URL(`${GH_API}${path}`);
   setQuery(u.searchParams);
   return `${u.pathname}${u.search}`;