@desplega.ai/agent-swarm 1.164.1 → 1.166.0

package/src/http/users.ts

@@ -18,6 +18,8 @@
  *   PATCH  /api/users/:id
  *   POST   /api/users/:id/mcp-tokens
  *   DELETE /api/users/:id/mcp-tokens/:tokenId
+ *   POST   /api/users/:id/connector-codes
+ *   POST   /api/connector/exchange                   (public: the code is the credential)
  *   POST   /api/users/:id/merge
  *   GET    /api/users/:id/events
  *   POST   /api/users/:id/identities
@@ -26,6 +28,11 @@
 
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { z } from "zod";
+import {
+  createConnectorCode,
+  DEFAULT_CONNECTOR_CODE_LABEL,
+  exchangeConnectorCode,
+} from "../be/connector-codes";
 import {
   createUser,
   deleteBudget,
@@ -51,6 +58,8 @@ import {
 } from "../be/users";
 import { UserCommsPrefsSchema, UserSchema } from "../types";
 import { getRequestAuth } from "../utils/request-auth-context";
+import { resolveAppUrl, resolveMcpBaseUrl } from "./config-values";
+import { clientIp, createIpRateLimiter } from "./ip-rate-limit";
 import { getOperatorActor } from "./operator-actor";
 import { route } from "./route-def";
 import { jsonError } from "./utils";
@@ -378,6 +387,87 @@ const revokeUserMcpTokenRoute = route({
   auth: { apiKey: true },
 });
 
+const createConnectorCodeRoute = route({
+  method: "post",
+  path: "/api/users/{id}/connector-codes",
+  pattern: ["api", "users", null, "connector-codes"],
+  summary: "Create a single-use connect code for the agent-swarm.dev ChatGPT connector",
+  description:
+    "Returns a 10-minute single-use code and the connector URL that carries it. The connector trades the code for an MCP token at POST /api/connector/exchange.",
+  tags: ["Users"],
+  params: z.object({ id: z.string() }),
+  body: z.object({
+    label: z.string().min(1).optional(),
+  }),
+  responses: {
+    201: {
+      description: "Connect code, its expiry and the connector URL",
+      schema: z.object({
+        code: z.string(),
+        expiresAt: z.string(),
+        connectUrl: z.string(),
+      }),
+    },
+    400: { description: "The public API origin or CONNECTOR_CONNECT_URL is not HTTPS" },
+    401: { description: "Unauthorized" },
+    404: { description: "User not found" },
+  },
+  auth: { apiKey: true },
+  rbac: { ungated: "same posture as POST /api/users/{id}/mcp-tokens (operator-only admission)" },
+});
+
+const exchangeConnectorCodeRoute = route({
+  method: "post",
+  path: "/api/connector/exchange",
+  pattern: ["api", "connector", "exchange"],
+  summary: "Exchange a connect code for a user MCP token",
+  description:
+    "Unauthenticated: the single-use code is the credential. Rate limited per IP. Unknown, expired and used codes all return 404 code_invalid.",
+  tags: ["Users"],
+  body: z.object({ code: z.string().min(1).max(256) }),
+  // Public route: cap the body before it is buffered and parsed.
+  maxBodyBytes: 1024,
+  responses: {
+    200: {
+      description: "Minted MCP token for the code's user",
+      schema: z.object({
+        token: z.string(),
+        userId: z.string(),
+        version: z.string(),
+      }),
+    },
+    404: { description: "Code unknown, malformed, expired or already used" },
+    413: { description: "Request body too large" },
+    429: { description: "Rate limited" },
+  },
+  auth: { apiKey: false },
+  rbac: {
+    ungated:
+      "the single-use code is the credential; the minted token carries the user's own grant and is admitted on use",
+  },
+});
+
+const connectorDiscoveryRoute = route({
+  method: "get",
+  path: "/api/connector/discovery",
+  pattern: ["api", "connector", "discovery"],
+  summary: "Public origins the agent-swarm.dev connector needs to find this swarm's dashboard",
+  description:
+    "Unauthenticated. Lets the connector turn an API origin into the dashboard URL that serves /connect. appUrl is omitted when APP_URL is not set or is not https.",
+  tags: ["Users"],
+  responses: {
+    200: {
+      description: "Public API origin, dashboard origin and connector connect URL",
+      schema: z.object({
+        apiUrl: z.string(),
+        appUrl: z.string().optional(),
+        connectUrl: z.string().nullable(),
+      }),
+    },
+  },
+  auth: { apiKey: false },
+});
+
 const mergeUsersRoute = route({
   method: "post",
   path: "/api/users/{id}/merge",
@@ -529,6 +619,54 @@ async function collectUnmappedForKind(kind: string, limit: number) {
   return Array.from(byId.values());
 }
 
+const DEFAULT_CONNECTOR_CONNECT_URL = "https://mcp.agent-swarm.dev/connections";
+
+/**
+ * The connector's connect page. Returns null unless it parses as an https://
+ * URL: the link carries a bearer-equivalent code, so it must never go out
+ * over plaintext or to a non-web scheme.
+ */
+function getConnectorConnectUrl(): URL | null {
+  const raw = process.env.CONNECTOR_CONNECT_URL?.trim() || DEFAULT_CONNECTOR_CONNECT_URL;
+  try {
+    const url = new URL(raw);
+    return url.protocol === "https:" ? url : null;
+  } catch {
+    return null;
+  }
+}
+
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+
+/**
+ * The connector only links https swarms in production. A loopback http
+ * origin also passes, for local stacks: there the connector's own SSRF guard
+ * (private swarms allowed only in its local env) makes the final call.
+ */
+function isConnectableSwarmOrigin(value: string): boolean {
+  try {
+    const url = new URL(value);
+    return (
+      url.protocol === "https:" || (url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname))
+    );
+  } catch {
+    return false;
+  }
+}
+
+/** `createConnectorCode` output: 32 random bytes in unpadded base64url. */
+const CONNECTOR_CODE_PATTERN = /^[A-Za-z0-9_-]{43}$/;
+
+/** 10 exchanges per minute per client IP. */
+const connectorExchangeRateLimiter = createIpRateLimiter({
+  capacity: 10,
+  refillPerMs: 10 / 60_000,
+});
+
+export function _resetConnectorExchangeRateLimitForTests(): void {
+  connectorExchangeRateLimiter.reset();
+}
+
 // ─── Handler ─────────────────────────────────────────────────────────────────
 
 export async function handleUsers(
@@ -694,6 +832,94 @@ export async function handleUsers(
     return true;
   }
 
+  // ─── POST /api/users/:id/connector-codes ──────────────────────────────────
+  if (createConnectorCodeRoute.match(req.method, pathSegments)) {
+    const parsed = await createConnectorCodeRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    const actor = getOperatorActor(req, res);
+    if (!actor) return true;
+    if (!(await getUserById(parsed.params.id))) {
+      jsonError(res, "User not found", 404);
+      return true;
+    }
+    // The connector refuses non-HTTPS swarm origins, so fail before minting a code.
+    // Same swarm_config-aware resolver as the dashboard's HTTPS gate.
+    const swarmOrigin = await resolveMcpBaseUrl();
+    if (!isConnectableSwarmOrigin(swarmOrigin)) {
+      jsonError(
+        res,
+        `The public API origin (${swarmOrigin}) is not HTTPS. Set PUBLIC_MCP_BASE_URL to an https:// origin.`,
+        400,
+      );
+      return true;
+    }
+    const connect = getConnectorConnectUrl();
+    if (!connect) {
+      jsonError(res, "CONNECTOR_CONNECT_URL must be an https:// URL.", 400);
+      return true;
+    }
+
+    try {
+      const { code, expiresAt } = await createConnectorCode(
+        parsed.params.id,
+        parsed.body.label ?? DEFAULT_CONNECTOR_CODE_LABEL,
+        actor,
+      );
+      connect.searchParams.set("swarm", swarmOrigin);
+      connect.searchParams.set("code", code);
+      const connectUrl = connect.toString();
+      createConnectorCodeRoute.respond(res, 201, { code, expiresAt, connectUrl });
+    } catch (err) {
+      jsonError(res, err instanceof Error ? err.message : "Failed to create connector code", 500);
+    }
+    return true;
+  }
+
+  // ─── GET /api/connector/discovery ─────────────────────────────────────────
+  if (connectorDiscoveryRoute.match(req.method, pathSegments)) {
+    const parsed = await connectorDiscoveryRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    // The connector only opens an https dashboard, so an http APP_URL is not reported.
+    const resolvedAppUrl = await resolveAppUrl();
+    const appUrl = resolvedAppUrl?.startsWith("https://") ? resolvedAppUrl : null;
+    connectorDiscoveryRoute.respond(res, 200, {
+      apiUrl: await resolveMcpBaseUrl(),
+      ...(appUrl ? { appUrl } : {}),
+      connectUrl: getConnectorConnectUrl()?.toString() ?? null,
+    });
+    return true;
+  }
+
+  // ─── POST /api/connector/exchange ─────────────────────────────────────────
+  if (exchangeConnectorCodeRoute.match(req.method, pathSegments)) {
+    if (!connectorExchangeRateLimiter.take(clientIp(req))) {
+      res.setHeader("Retry-After", "6");
+      jsonError(res, "rate_limited", 429);
+      return true;
+    }
+    const parsed = await exchangeConnectorCodeRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+
+    // Reject anything that is not a generated code shape before hashing it.
+    if (!CONNECTOR_CODE_PATTERN.test(parsed.body.code)) {
+      jsonError(res, "code_invalid", 404);
+      return true;
+    }
+
+    try {
+      const result = await exchangeConnectorCode(parsed.body.code);
+      if (!result) {
+        jsonError(res, "code_invalid", 404);
+        return true;
+      }
+      const version = (await Bun.file("package.json").json()).version;
+      exchangeConnectorCodeRoute.respond(res, 200, { ...result, version });
+    } catch (err) {
+      jsonError(res, err instanceof Error ? err.message : "Failed to exchange code", 500);
+    }
+    return true;
+  }
+
   // ─── DELETE /api/users/:id/mcp-tokens/:tokenId ────────────────────────────
   if (revokeUserMcpTokenRoute.match(req.method, pathSegments)) {
     const parsed = await revokeUserMcpTokenRoute.parse(req, res, pathSegments, queryParams);

package/src/http/workflows.ts

@@ -901,13 +901,14 @@ export async function handleWorkflows(
   if (getWorkflowRunRoute.match(req.method, pathSegments)) {
     const parsed = await getWorkflowRunRoute.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
-    const run = await getWorkflowRun(parsed.params.id);
+    // Display view: the scrubbed context and step outputs, never replay state.
+    const run = await getWorkflowRun(parsed.params.id, "display");
     if (!run) {
       res.writeHead(404);
       res.end();
       return true;
     }
-    const steps = await getWorkflowRunStepsByRunId(parsed.params.id);
+    const steps = await getWorkflowRunStepsByRunId(parsed.params.id, "display");
     getWorkflowRunRoute.respond(res, 200, { run, steps });
     return true;
   }

package/src/http.ts

@@ -1,3 +1,4 @@
+import "./utils/console-scrub-install.ts";
 import "./utils/internal-ai/register-bedrock.ts";
 
 import "./http/index";

package/src/integrations/kapso/client.ts

@@ -8,6 +8,8 @@
  * Both authenticate with the `X-API-Key` header.
  */
 
+import { scrubSecrets } from "../../utils/secret-scrubber";
+
 /** Result of an outbound text/reply send through the Meta proxy. */
 export interface KapsoSendResult {
   ok: boolean;
@@ -75,7 +77,7 @@ export async function sendKapsoText(params: {
     recipient_type: "individual",
     to: params.to,
     type: "text",
-    text: { preview_url: params.previewUrl ?? false, body: params.body },
+    text: { preview_url: params.previewUrl ?? false, body: scrubSecrets(params.body) },
   };
   if (params.contextMessageId) {
     payload.context = { message_id: params.contextMessageId };

package/src/jira/app.ts

@@ -1,5 +1,6 @@
 import { upsertOAuthApp } from "../be/db-queries/oauth";
 import { getPublicMcpBaseUrl } from "../utils/constants";
+import { isEnvFlagEnabled } from "../utils/env-flag";
 import { initJiraOutboundSync, teardownJiraOutboundSync } from "./outbound";
 // Side-effect import: registers all Jira event templates in the in-memory
 // registry at module load time (mirrors `src/linear/templates.ts`).
@@ -10,8 +11,7 @@ import { startJiraWebhookKeepalive, stopJiraWebhookKeepalive } from "./webhook-l
 let initialized = false;
 
 export function isJiraEnabled(): boolean {
-  const disabled = process.env.JIRA_DISABLE;
-  if (disabled === "true" || disabled === "1") return false;
+  if (isEnvFlagEnabled("JIRA_DISABLE", false)) return false;
   const enabled = process.env.JIRA_ENABLED;
   if (enabled === "false" || enabled === "0") return false;
   return !!process.env.JIRA_CLIENT_ID;

package/src/kv-view.ts

@@ -0,0 +1,324 @@
+/**
+ * Targeted reads of a stored KV value: a dot path into a JSON value plus an
+ * offset/limit window over the array items, object keys, or string characters
+ * found there. Shared by the kv-get MCP tool, the REST GET routes behind
+ * `ctx.swarm.kv_get`, and the ctx-control spill shape summary, so every path
+ * the summary prints is a path kv-get accepts.
+ *
+ * Pure functions only: no DB access, safe to import from any side.
+ */
+
+export type KvViewArgs = { path?: string; offset?: number; limit?: number };
+
+export type KvViewType = "object" | "array" | "string" | "number" | "boolean" | "null";
+
+export type KvView = {
+  /** Dot path that was resolved; "" is the whole value. */
+  path: string;
+  type: KvViewType;
+  /** Array items, object keys, or string characters at `path`. */
+  total?: number;
+  offset?: number;
+  returned?: number;
+  /** Offset of the next page, or null when this page reaches the end. */
+  nextOffset?: number | null;
+};
+
+export type KvViewResult =
+  | { ok: true; value: unknown; view: KvView }
+  | { ok: false; error: string };
+
+/** Longest `path` kv-get accepts. */
+export const KV_PATH_MAX_CHARS = 1024;
+
+/** JSON-encoded path bytes a spill shape summary may spend across its entries. */
+export const KV_SHAPE_PATH_BUDGET_BYTES = 2048;
+
+function pathBytes(path: string): number {
+  return Buffer.byteLength(JSON.stringify(path), "utf8");
+}
+
+export type KvShapeEntry = {
+  path: string;
+  type: KvViewType;
+  bytes: number;
+  /** Array items, object keys, or string characters. */
+  items?: number;
+};
+
+export function hasKvViewArgs(args: KvViewArgs): boolean {
+  return args.path !== undefined || args.offset !== undefined || args.limit !== undefined;
+}
+
+export function kvViewType(value: unknown): KvViewType {
+  if (value === null || value === undefined) return "null";
+  if (Array.isArray(value)) return "array";
+  switch (typeof value) {
+    case "object":
+      return "object";
+    case "string":
+      return "string";
+    case "number":
+    case "bigint":
+      return "number";
+    case "boolean":
+      return "boolean";
+    default:
+      return "null";
+  }
+}
+
+/**
+ * The JSON root of a stored value. `string` entries whose text parses to an
+ * object or array (MCP spill payloads are stored this way) are treated as
+ * JSON; any other string stays a plain string.
+ */
+export function kvViewRoot(value: unknown): { root: unknown; json: boolean } {
+  if (typeof value !== "string") return { root: value, json: true };
+  try {
+    const parsed: unknown = JSON.parse(value);
+    if (parsed !== null && typeof parsed === "object") return { root: parsed, json: true };
+  } catch {
+    // Not JSON: fall through to plain-string handling.
+  }
+  return { root: value, json: false };
+}
+
+function itemCount(value: unknown): number | undefined {
+  if (Array.isArray(value)) return value.length;
+  if (typeof value === "string") return value.length;
+  if (value !== null && typeof value === "object") return Object.keys(value).length;
+  return undefined;
+}
+
+/**
+ * Split a dot path into keys. `\.` is a literal dot and `\\` a literal
+ * backslash, so object keys containing dots stay addressable.
+ */
+export function splitKvPath(path: string): string[] {
+  const segments: string[] = [];
+  let current = "";
+  for (let i = 0; i < path.length; i++) {
+    const char = path[i] as string;
+    if (char === "\\" && i + 1 < path.length) {
+      current += path[++i];
+    } else if (char === ".") {
+      segments.push(current);
+      current = "";
+    } else {
+      current += char;
+    }
+  }
+  segments.push(current);
+  return segments;
+}
+
+/** Inverse of `splitKvPath`: escape each key and join with dots. */
+export function joinKvPath(segments: string[]): string {
+  return segments.map((key) => key.replace(/[\\.]/g, "\\$&")).join(".");
+}
+
+function resolvePath(
+  root: unknown,
+  path: string,
+): { ok: true; value: unknown } | { ok: false; error: string } {
+  if (path === "") return { ok: true, value: root };
+  const segments = splitKvPath(path);
+  if (segments.some((segment) => segment === "")) {
+    return {
+      ok: false,
+      error: `path "${path}" has an empty segment; use dot paths like "data.rows"`,
+    };
+  }
+  let current = root;
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i] as string;
+    const at = joinKvPath(segments.slice(0, i)) || "(root)";
+    if (Array.isArray(current)) {
+      const index = /^\d+$/.test(segment) ? Number(segment) : Number.NaN;
+      if (!(index < current.length)) {
+        return {
+          ok: false,
+          error: `path "${path}" not found: "${at}" is an array of ${current.length}; "${segment}" is not a valid index`,
+        };
+      }
+      current = current[index];
+    } else if (current !== null && typeof current === "object") {
+      if (!Object.hasOwn(current, segment)) {
+        return { ok: false, error: `path "${path}" not found: no key "${segment}" under "${at}"` };
+      }
+      current = (current as Record<string, unknown>)[segment];
+    } else {
+      return {
+        ok: false,
+        error: `path "${path}" not found: "${at}" is a ${kvViewType(current)}, it has no "${segment}"`,
+      };
+    }
+  }
+  return { ok: true, value: current };
+}
+
+/** The value at `path` ("" = whole value) inside a stored KV value. */
+export function resolveKvTarget(
+  value: unknown,
+  path: string,
+): { ok: true; value: unknown } | { ok: false; error: string } {
+  const { root, json } = kvViewRoot(value);
+  if (path !== "" && !json) {
+    return {
+      ok: false,
+      error: `path "${path}" needs a JSON value; this entry is a plain string (use offset/limit alone to page its characters)`,
+    };
+  }
+  return resolvePath(root, path);
+}
+
+/** Window `[offset, offset + limit)` over a target's items, keys, or characters. */
+export function sliceKvTarget(
+  target: unknown,
+  offset: number,
+  limit: number | undefined,
+): { value: unknown; total: number; returned: number; nextOffset: number | null } | undefined {
+  const total = itemCount(target);
+  if (total === undefined) return undefined;
+  const start = Math.min(offset, total);
+  const end = limit === undefined ? total : Math.min(total, start + limit);
+  let value: unknown;
+  let returned = end - start;
+  if (Array.isArray(target)) {
+    value = target.slice(start, end);
+  } else if (typeof target === "string") {
+    // Never end a page on a lone high surrogate: back off one char so the next
+    // page starts on the pair, or take the whole pair when it is the only char
+    // (otherwise `limit: 1` would return nothing and never advance).
+    const lastCode = target.charCodeAt(end - 1);
+    const splitsPair = end > start && end < total && lastCode >= 0xd800 && lastCode <= 0xdbff;
+    const safeEnd = splitsPair ? (end - 1 > start ? end - 1 : end + 1) : end;
+    value = target.slice(start, safeEnd);
+    returned = safeEnd - start;
+  } else {
+    value = Object.fromEntries(Object.entries(target as object).slice(start, end));
+  }
+  const reached = start + returned;
+  return { value, total, returned, nextOffset: reached < total ? reached : null };
+}
+
+/**
+ * Resolve `path`, then apply `offset`/`limit`. Out-of-range offsets return an
+ * empty page with the true `total`; missing paths and paths into a plain
+ * string are errors. No size cap here: callers that feed a model bound the
+ * page themselves (see the kv-get tool).
+ */
+export function resolveKvView(value: unknown, args: KvViewArgs): KvViewResult {
+  const path = args.path ?? "";
+  const resolved = resolveKvTarget(value, path);
+  if (!resolved.ok) return resolved;
+  const type = kvViewType(resolved.value);
+  const offset = args.offset ?? 0;
+  const sliced = sliceKvTarget(resolved.value, offset, args.limit);
+  if (!sliced) {
+    if (args.offset !== undefined || args.limit !== undefined) {
+      return {
+        ok: false,
+        error: `offset/limit page arrays, objects, and strings; "${path || "(root)"}" is a ${type}`,
+      };
+    }
+    return { ok: true, value: resolved.value, view: { path, type } };
+  }
+  return {
+    ok: true,
+    value: sliced.value,
+    view: {
+      path,
+      type,
+      total: sliced.total,
+      offset,
+      returned: sliced.returned,
+      nextOffset: sliced.nextOffset,
+    },
+  };
+}
+
+type ShapeNode = KvShapeEntry & { value: unknown; segments: string[]; ancestors: unknown[] };
+
+function shapeEntry(segments: string[], value: unknown, ancestors: unknown[]): ShapeNode {
+  const items = itemCount(value);
+  return {
+    path: joinKvPath(segments),
+    type: kvViewType(value),
+    bytes: Buffer.byteLength(JSON.stringify(value) ?? "", "utf8"),
+    ...(items !== undefined ? { items } : {}),
+    value,
+    segments,
+    ancestors,
+  };
+}
+
+function childEntries(node: Pick<ShapeNode, "value" | "segments" | "ancestors">): ShapeNode[] {
+  const { value, segments, ancestors } = node;
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return [];
+  return Object.entries(value).map(([key, child]) =>
+    shapeEntry([...segments, key], child, [...ancestors, value]),
+  );
+}
+
+/**
+ * The node itself when kv-get can address it within `budget` (JSON-encoded
+ * path bytes, what a path costs on the wire), else its nearest such ancestor.
+ * An empty key has no path syntax (`""` is the root and empty segments are
+ * rejected), so its parent stands in; the root always fits.
+ */
+function addressable(node: ShapeNode, budget: number): ShapeNode {
+  for (let depth = node.segments.length; depth > 0; depth--) {
+    const segments = node.segments.slice(0, depth);
+    if (segments.includes("")) continue;
+    const path = joinKvPath(segments);
+    if (path.length > KV_PATH_MAX_CHARS || pathBytes(path) > budget) continue;
+    if (depth === node.segments.length) return node;
+    return shapeEntry(segments, node.ancestors[depth], node.ancestors.slice(0, depth));
+  }
+  return shapeEntry([], node.ancestors[0] ?? node.value, []);
+}
+
+/**
+ * Bounded outline of a JSON value: its biggest branches by serialized bytes,
+ * expanding the dominant object one level at a time so the paths reach where
+ * the bulk lives (e.g. `outcome.data.data.result.rows`). Arrays are reported
+ * with their length and never expanded.
+ */
+export function summarizeKvShape(
+  root: unknown,
+  maxEntries = 8,
+  maxPathBytes = KV_SHAPE_PATH_BUDGET_BYTES,
+): KvShapeEntry[] {
+  const rootBytes = Buffer.byteLength(JSON.stringify(root) ?? "", "utf8");
+  let entries = childEntries({ value: root, segments: [], ancestors: [] });
+  for (let step = 0; step < 8; step++) {
+    const candidate = entries
+      .filter((entry) => entry.type === "object" && (entry.items ?? 0) > 0)
+      .sort((a, b) => b.bytes - a.bytes)[0];
+    if (!candidate || candidate.bytes * 4 < rootBytes) break;
+    entries = entries.filter((entry) => entry !== candidate).concat(childEntries(candidate));
+  }
+  // Skip crumbs (under 1% of the value) so the slots go to where the bulk is.
+  const sorted = entries.sort((a, b) => b.bytes - a.bytes);
+  const significant = sorted.filter((entry) => entry.bytes * 100 >= rootBytes);
+  // Paths stay exact so each one works as a kv-get `path`. The summary is
+  // bounded by total path bytes: a path that does not fit the remaining budget
+  // gives way to its nearest ancestor that does.
+  const shape: KvShapeEntry[] = [];
+  let budget = maxPathBytes;
+  for (const entry of significant.length > 0 ? significant : sorted) {
+    if (shape.length >= maxEntries) break;
+    const {
+      value: _value,
+      segments: _segments,
+      ancestors: _ancestors,
+      ...node
+    } = addressable(entry, budget);
+    if (shape.some((seen) => seen.path === node.path)) continue;
+    shape.push(node);
+    budget -= pathBytes(node.path);
+  }
+  return shape;
+}

package/src/linear/app.ts

@@ -1,6 +1,7 @@
 import { getOAuthApp, upsertOAuthApp } from "../be/db-queries/oauth";
 import { onAuthorizationRefreshed } from "../oauth/ensure-token";
 import { getPublicMcpBaseUrl } from "../utils/constants";
+import { isEnvFlagEnabled } from "../utils/env-flag";
 import { resetLinearClient } from "./client";
 import { initLinearOutboundSync, teardownLinearOutboundSync } from "./outbound";
 
@@ -8,8 +9,7 @@ let initialized = false;
 let unsubscribeRefresh: (() => void) | null = null;
 
 export function isLinearEnabled(): boolean {
-  const disabled = process.env.LINEAR_DISABLE;
-  if (disabled === "true" || disabled === "1") return false;
+  if (isEnvFlagEnabled("LINEAR_DISABLE", false)) return false;
   const enabled = process.env.LINEAR_ENABLED;
   if (enabled === "false" || enabled === "0") return false;
   return !!process.env.LINEAR_CLIENT_ID;

package/src/oauth/mcp-wrapper.ts

@@ -372,7 +372,7 @@ function formUrlEncodeComponent(value: string): string {
  * at each call site means a new sensitive field cannot forget one shape.
  */
 function redactSentCredentials(text: string, sent: Array<string | null | undefined>): string {
-  let out = scrubSecrets(text);
+  let out: string = scrubSecrets(text);
   for (const value of sent) {
     if (!value) continue;
     for (const shape of new Set([value, formUrlEncodeComponent(value)])) {