@cutoffs/openclaw-plugin 0.3.0

package/index.js

@@ -0,0 +1,1720 @@
+import { createHash } from "node:crypto";
+import { readFileSync, statSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { Type } from "@sinclair/typebox";
+
+const PLUGIN_ID = "cutoffs-plugin";
+const LEGACY_PLUGIN_IDS = ["cutoffs", "openclaw-plugin"];
+const DEFAULT_BASE_URL = "https://cutoffs.dev";
+const USER_AGENT = "@cutoffs/openclaw-plugin/0.3.0";
+const DEFAULT_PAIRING_POLL_INTERVAL_MS = 3000;
+const DEFAULT_PAIRING_WAIT_TIMEOUT_MS = 5 * 60 * 1000;
+const MAX_FILE_UPLOAD_BYTES = 25 * 1024 * 1024;
+const APOLLO_S3KEY_PATTERN =
+  /^\d+\/[A-Z0-9_]+\/[A-Z0-9_]+\/(request|response)\/[A-Za-z0-9_-]+$/;
+
+function safeTrim(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : "";
+}
+
+function tokenizeArgs(value) {
+  const input = typeof value === "string" ? value.trim() : "";
+
+  if (!input) {
+    return [];
+  }
+
+  return Array.from(input.matchAll(/"([^"]*)"|'([^']*)'|(\S+)/g), (match) =>
+    match[1] ?? match[2] ?? match[3] ?? "",
+  );
+}
+
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function maskSecret(value) {
+  if (!isNonEmptyString(value)) {
+    return "(unset)";
+  }
+
+  const trimmed = value.trim();
+
+  if (trimmed.length <= 8) {
+    return `${trimmed.slice(0, 2)}***`;
+  }
+
+  return `${trimmed.slice(0, 4)}...${trimmed.slice(-4)}`;
+}
+
+function getPluginConfigEntry(entries, pluginId) {
+  const pluginEntry = entries?.[pluginId];
+
+  if (pluginEntry && typeof pluginEntry === "object") {
+    return pluginEntry.config ?? {};
+  }
+
+  return null;
+}
+
+function getDynamicPluginConfig(api) {
+  const liveConfig = api.runtime?.config?.loadConfig?.();
+  const entries = liveConfig?.plugins?.entries;
+
+  for (const pluginId of [api.id, ...LEGACY_PLUGIN_IDS]) {
+    const config = getPluginConfigEntry(entries, pluginId);
+
+    if (config) {
+      return config;
+    }
+  }
+
+  return api.pluginConfig ?? {};
+}
+
+function readApiKey(config) {
+  return isNonEmptyString(config.apiKey) ? config.apiKey.trim() : "";
+}
+
+function getPluginConfig(api) {
+  const rawConfig = getDynamicPluginConfig(api);
+  const apiKey = readApiKey(rawConfig);
+  const pendingPairing = isPlainObject(rawConfig.pendingPairing)
+    ? {
+        sessionToken: safeTrim(rawConfig.pendingPairing.sessionToken),
+        verifier: safeTrim(rawConfig.pendingPairing.verifier),
+        pairUrl: safeTrim(rawConfig.pendingPairing.pairUrl),
+        displayCode: safeTrim(rawConfig.pendingPairing.displayCode) || null,
+        deviceLabel: safeTrim(rawConfig.pendingPairing.deviceLabel),
+        expiresAt: safeTrim(rawConfig.pendingPairing.expiresAt),
+      }
+    : null;
+
+  const normalizedPendingPairing =
+    pendingPairing &&
+    pendingPairing.sessionToken &&
+    pendingPairing.verifier &&
+    pendingPairing.pairUrl &&
+    pendingPairing.expiresAt
+      ? pendingPairing
+      : null;
+
+  return {
+    apiKey,
+    pendingPairing: normalizedPendingPairing,
+  };
+}
+
+function requireApiKey(api) {
+  const { apiKey } = getPluginConfig(api);
+
+  if (!apiKey) {
+    throw new Error(
+      "Cutoffs is not configured yet. Start browser pairing with cutoffs_begin_pairing. If the plugin was just installed and this chat cannot see the tools yet, start a fresh chat and retry setup there.",
+    );
+  }
+
+  return { apiKey };
+}
+
+async function parseJsonSafely(response) {
+  try {
+    return await response.json();
+  } catch {
+    return null;
+  }
+}
+
+function stringifyPayload(payload) {
+  return JSON.stringify(payload, null, 2);
+}
+
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+class CutoffsPluginValidationError extends Error {
+  constructor(message, { code, invalidFields = [], hint } = {}) {
+    super(message);
+    this.name = "CutoffsPluginValidationError";
+    this.code = code;
+    this.invalidFields = invalidFields;
+    this.hint = hint;
+  }
+}
+
+function isFileUploadableShape(value) {
+  return (
+    isPlainObject(value) &&
+    isNonEmptyString(value.name) &&
+    isNonEmptyString(value.mimetype) &&
+    isNonEmptyString(value.s3key)
+  );
+}
+
+function collectFileUploadables(value, pathPrefix = "arguments") {
+  const matches = [];
+
+  function walk(current, currentPath) {
+    if (isFileUploadableShape(current)) {
+      matches.push({ path: currentPath, value: current });
+      return;
+    }
+
+    if (Array.isArray(current)) {
+      current.forEach((item, index) => walk(item, `${currentPath}[${index}]`));
+      return;
+    }
+
+    if (!isPlainObject(current)) {
+      return;
+    }
+
+    for (const [key, child] of Object.entries(current)) {
+      walk(child, `${currentPath}.${key}`);
+    }
+  }
+
+  walk(value, pathPrefix);
+  return matches;
+}
+
+function expandHomePath(filePath) {
+  if (filePath === "~") {
+    return os.homedir();
+  }
+
+  if (filePath.startsWith("~/")) {
+    return path.join(os.homedir(), filePath.slice(2));
+  }
+
+  return filePath;
+}
+
+function hasTraversalSegment(filePath) {
+  return filePath.split(/[\\/]+/).includes("..");
+}
+
+function permittedMediaRoots() {
+  return [
+    "/data/.openclaw/media",
+    path.join(os.homedir(), ".openclaw", "media"),
+    path.resolve(process.cwd(), ".openclaw", "media"),
+  ].map((root) => path.resolve(root));
+}
+
+// Subdirectories of `.openclaw/` the plugin is allowed to read files from.
+//
+// This is a SECURITY BOUNDARY. The file-upload relay reads whatever local path
+// the agent puts in `s3key` and ships the bytes off-machine to a public
+// destination (e.g. a social post), with no human confirming the file. Because
+// the path is chosen by a prompt-injectable LLM, an unrestricted allowlist would
+// turn `s3key` into an arbitrary-local-file-exfiltration primitive — an injected
+// instruction could publish `~/.ssh/id_rsa`, `~/.aws/credentials`, a `.env`, etc.
+//
+// We therefore only read from `.openclaw/` subtrees that hold media-shareable or
+// agent-owned content:
+//   media       — files the user attached in OpenClaw
+//   agents      — agent working dirs
+//   workspace-* — content the agent generated in its own workspace
+// Everything else (home dotfiles, ~/.ssh, ~/.aws, /etc, arbitrary absolute
+// paths) stays blocked, as does any `..` traversal (see hasTraversalSegment).
+const PERMITTED_OPENCLAW_SUBDIRS = ["media", "agents"];
+
+function isPermittedOpenclawSubdir(segment) {
+  return PERMITTED_OPENCLAW_SUBDIRS.includes(segment) || segment.startsWith("workspace");
+}
+
+function isInsidePath(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative.length > 0 && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+
+function resolvePermittedMediaPath(s3key) {
+  if (!isNonEmptyString(s3key) || hasTraversalSegment(s3key)) {
+    return null;
+  }
+
+  const normalized = path.resolve(expandHomePath(s3key));
+  const roots = permittedMediaRoots();
+  if (roots.some((root) => isInsidePath(root, normalized))) {
+    return normalized;
+  }
+
+  // Allow files under a trusted `.openclaw/<subdir>/...` subtree even when
+  // OpenClaw's root is in a location we don't enumerate above (e.g. a container
+  // path). Match the segment immediately after `.openclaw`, and require at least
+  // one path segment after it so we only ever resolve a file *inside* the subdir.
+  const segments = normalized.split(/[\\/]+/);
+  const openclawIndex = segments.lastIndexOf(".openclaw");
+  if (
+    openclawIndex !== -1 &&
+    openclawIndex + 2 < segments.length &&
+    isPermittedOpenclawSubdir(segments[openclawIndex + 1])
+  ) {
+    return normalized;
+  }
+
+  return null;
+}
+
+function readFileForUpload(fileUploadable, fieldPath) {
+  const filePath = resolvePermittedMediaPath(fileUploadable.s3key);
+  if (!filePath) {
+    throw new CutoffsPluginValidationError(
+      `The file for ${fieldPath} is outside the permitted OpenClaw attachment roots.`,
+      {
+        code: "invalid_file_path",
+        invalidFields: [`${fieldPath}.s3key`],
+        hint:
+          "Re-attach the file through OpenClaw so it is stored under an OpenClaw media directory before retrying.",
+      },
+    );
+  }
+
+  let stats;
+  try {
+    stats = statSync(filePath);
+  } catch (error) {
+    throw new CutoffsPluginValidationError(
+      `The file for ${fieldPath} could not be read: ${error instanceof Error ? error.message : "unknown read error"}.`,
+      {
+        code: "file_read_failed",
+        invalidFields: [`${fieldPath}.s3key`],
+        hint: "Re-attach the file through OpenClaw and retry the tool call.",
+      },
+    );
+  }
+
+  if (!stats.isFile()) {
+    throw new CutoffsPluginValidationError(
+      `The file for ${fieldPath} is not a regular file.`,
+      {
+        code: "file_read_failed",
+        invalidFields: [`${fieldPath}.s3key`],
+        hint: "Re-attach a regular file through OpenClaw and retry the tool call.",
+      },
+    );
+  }
+
+  if (stats.size > MAX_FILE_UPLOAD_BYTES) {
+    throw new CutoffsPluginValidationError(
+      `The file for ${fieldPath} is ${stats.size} bytes, exceeding the ${MAX_FILE_UPLOAD_BYTES}-byte cap (${MAX_FILE_UPLOAD_BYTES / (1024 * 1024)} MB).`,
+      {
+        code: "file_too_large",
+        invalidFields: [`${fieldPath}.s3key`],
+        hint: "Use a public URL field for this media when the tool supports one, or attach a smaller file.",
+      },
+    );
+  }
+
+  let bytes;
+  try {
+    bytes = readFileSync(filePath);
+  } catch (error) {
+    throw new CutoffsPluginValidationError(
+      `The file for ${fieldPath} could not be read: ${error instanceof Error ? error.message : "unknown read error"}.`,
+      {
+        code: "file_read_failed",
+        invalidFields: [`${fieldPath}.s3key`],
+        hint: "Re-attach the file through OpenClaw and retry the tool call.",
+      },
+    );
+  }
+
+  if (bytes.byteLength > MAX_FILE_UPLOAD_BYTES) {
+    throw new CutoffsPluginValidationError(
+      `The file for ${fieldPath} is ${bytes.byteLength} bytes, exceeding the ${MAX_FILE_UPLOAD_BYTES}-byte cap (${MAX_FILE_UPLOAD_BYTES / (1024 * 1024)} MB).`,
+      {
+        code: "file_too_large",
+        invalidFields: [`${fieldPath}.s3key`],
+        hint: "Use a public URL field for this media when the tool supports one, or attach a smaller file.",
+      },
+    );
+  }
+
+  return {
+    pointer: fileUploadable.s3key,
+    name: fileUploadable.name,
+    mimetype: fileUploadable.mimetype,
+    md5: createHash("md5").update(bytes).digest("hex"),
+    dataBase64: bytes.toString("base64"),
+  };
+}
+
+function buildFilesEnvelope(args) {
+  const files = [];
+  const seenPointers = new Set();
+
+  for (const match of collectFileUploadables(args)) {
+    if (APOLLO_S3KEY_PATTERN.test(match.value.s3key)) {
+      continue;
+    }
+
+    if (seenPointers.has(match.value.s3key)) {
+      continue;
+    }
+
+    files.push(readFileForUpload(match.value, match.path));
+    seenPointers.add(match.value.s3key);
+  }
+
+  return files;
+}
+
+function collectErrorFields(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  return value.filter(isNonEmptyString).map((item) => item.trim());
+}
+
+function resolveErrorSchema(payload) {
+  if (isPlainObject(payload?.inputSchema)) {
+    return payload.inputSchema;
+  }
+
+  if (isPlainObject(payload?.tool) && isPlainObject(payload.tool.inputSchema)) {
+    return payload.tool.inputSchema;
+  }
+
+  return null;
+}
+
+function formatStructuredCutoffsError(payload, status) {
+  if (payload && typeof payload.error === "string") {
+    const details =
+      Array.isArray(payload?.details) && payload.details.length > 0
+        ? `\n${payload.details.join("\n")}`
+        : "";
+    const upgradeHint =
+      typeof payload?.upgradeUrl === "string"
+        ? `\nUpgrade here: ${payload.upgradeUrl}`
+        : "";
+    return `${payload.error}${details}${upgradeHint}`;
+  }
+
+  const objectError = isPlainObject(payload?.error) ? payload.error : null;
+  const message = isNonEmptyString(objectError?.message)
+    ? objectError.message.trim()
+    : isNonEmptyString(payload?.message)
+      ? payload.message.trim()
+      : `Cutoffs request failed with status ${status}`;
+  const missingFields = collectErrorFields(payload?.missingFields);
+  const invalidFields = collectErrorFields(payload?.invalidFields);
+  const details = collectErrorFields(payload?.details);
+  const hint = isNonEmptyString(payload?.hint) ? payload.hint.trim() : "";
+  const schema = resolveErrorSchema(payload);
+  const lines = [message];
+
+  if (missingFields.length > 0) {
+    lines.push(`Missing fields: ${missingFields.join(", ")}`);
+  }
+
+  if (invalidFields.length > 0) {
+    lines.push(`Invalid fields: ${invalidFields.join(", ")}`);
+  }
+
+  if (details.length > 0) {
+    lines.push(...details);
+  }
+
+  if (hint) {
+    lines.push(`Hint: ${hint}`);
+  }
+
+  if (schema) {
+    lines.push("Input schema:");
+    lines.push(stringifyPayload(schema));
+  }
+
+  if (typeof payload?.upgradeUrl === "string") {
+    lines.push(`Upgrade here: ${payload.upgradeUrl}`);
+  }
+
+  return lines.join("\n");
+}
+
+async function callCutoffs(api, path, options = {}) {
+  const { apiKey } = requireApiKey(api);
+  const response = await fetch(`${DEFAULT_BASE_URL}${path}`, {
+    method: options.method ?? "GET",
+    headers: {
+      "X-Cutoffs-API-Key": apiKey,
+      "Content-Type": "application/json",
+      "User-Agent": USER_AGENT,
+      ...(options.headers ?? {}),
+    },
+    body: options.body ? JSON.stringify(options.body) : undefined,
+  });
+
+  const payload = await parseJsonSafely(response);
+
+  if (!response.ok) {
+    const error = new Error(formatStructuredCutoffsError(payload, response.status));
+    error.cutoffsPayload = payload;
+    error.cutoffsStatus = response.status;
+    throw error;
+  }
+
+  return payload;
+}
+
+async function callCutoffsPublic(path, options = {}) {
+  const response = await fetch(`${DEFAULT_BASE_URL}${path}`, {
+    method: options.method ?? "GET",
+    headers: {
+      "Content-Type": "application/json",
+      "User-Agent": USER_AGENT,
+      ...(options.headers ?? {}),
+    },
+    body: options.body ? JSON.stringify(options.body) : undefined,
+  });
+
+  const payload = await parseJsonSafely(response);
+
+  if (!response.ok) {
+    const message =
+      payload && typeof payload.error === "string"
+        ? payload.error
+        : `Cutoffs request failed with status ${response.status}`;
+    throw new Error(message);
+  }
+
+  return payload;
+}
+
+function textResult(text, details) {
+  return {
+    content: [
+      {
+        type: "text",
+        text,
+      },
+    ],
+    details,
+  };
+}
+
+function buildStartConnectionText(payload) {
+  if (payload?.alreadyConnected) {
+    const summary = {
+      integration: payload.integration,
+      connection: payload.connection ?? null,
+    };
+
+    return [
+      `${payload.integration} is already connected through Cutoffs. No new connection needed — use cutoffs_list_tools with integration "${payload.integration}" and cutoffs_call_tool to act on it.`,
+      "",
+      stringifyPayload(summary),
+    ].join("\n");
+  }
+
+  const summary = {
+    integration: payload.integration,
+    sessionToken: payload.sessionToken,
+    status: payload.status,
+    displayCode: payload.displayCode,
+    connectUrl: payload.connectUrl,
+    statusUrl: payload.statusUrl,
+    expiresAt: payload.expiresAt,
+    pollIntervalMs: payload.pollIntervalMs,
+  };
+
+  return [
+    "Cutoffs connection session started.",
+    "",
+    "Open the hosted setup URL, complete authentication, then poll the session token until the status changes.",
+    "",
+    stringifyPayload(summary),
+  ].join("\n");
+}
+
+function buildStatusText(payload) {
+  const summary = {
+    status: payload?.session?.status ?? null,
+    integration: payload?.session?.integration ?? null,
+    sessionToken: payload?.session?.token ?? null,
+    displayCode: payload?.session?.displayCode ?? null,
+    expiresAt: payload?.session?.expiresAt ?? null,
+    completedAt: payload?.session?.completedAt ?? null,
+    errorMessage: payload?.session?.errorMessage ?? null,
+    connection: payload?.connection ?? null,
+  };
+
+  return [
+    "Cutoffs connection session status:",
+    "",
+    stringifyPayload(summary),
+  ].join("\n");
+}
+
+function summarizeIntegrations(payload) {
+  const connections = Array.isArray(payload?.integrations) ? payload.integrations : [];
+  const grouped = new Map();
+
+  for (const connection of connections) {
+    const slug = typeof connection?.integration === "string" ? connection.integration : "unknown";
+    const existing = grouped.get(slug) ?? {
+      integration: slug,
+      connectionCount: 0,
+      defaultConnectionId: null,
+      connections: [],
+    };
+
+    existing.connectionCount += 1;
+
+    if (connection?.isDefault) {
+      existing.defaultConnectionId = connection.id ?? null;
+    }
+
+    existing.connections.push({
+      id: connection?.id ?? null,
+      connectionLabel: connection?.connectionLabel ?? null,
+      accountLabel: connection?.accountLabel ?? null,
+      isDefault: Boolean(connection?.isDefault),
+      expiresAt: connection?.expiresAt ?? null,
+    });
+
+    grouped.set(slug, existing);
+  }
+
+  return Array.from(grouped.values()).sort((left, right) =>
+    left.integration.localeCompare(right.integration),
+  );
+}
+
+function buildIntegrationListText(payload) {
+  const summary = summarizeIntegrations(payload);
+
+  if (summary.length === 0) {
+    return [
+      "No connected Cutoffs integrations found.",
+      "",
+      "Start a hosted connection first if the user wants to connect a new app.",
+    ].join("\n");
+  }
+
+  return [
+    "Connected Cutoffs integrations:",
+    "",
+    stringifyPayload(summary),
+  ].join("\n");
+}
+
+function buildToolListText(payload) {
+  const tools = Array.isArray(payload?.tools) ? payload.tools : [];
+  const integration = isNonEmptyString(payload?.integration) ? payload.integration : null;
+  const query = isNonEmptyString(payload?.query) ? payload.query : null;
+  const heading = query
+    ? integration
+      ? `Matching Cutoffs tools for ${integration} and "${query}":`
+      : `Matching Cutoffs tools for "${query}":`
+    : integration
+      ? `Available Cutoffs tools for ${integration}:`
+      : "Available Cutoffs tools:";
+  const emptyHeading = query
+    ? integration
+      ? `No matching Cutoffs tools found for ${integration} and "${query}".`
+      : `No matching Cutoffs tools found for "${query}".`
+    : integration
+      ? `No Cutoffs tools are currently available for ${integration}.`
+      : "No Cutoffs tools are currently available.";
+
+  return [
+    tools.length > 0 ? heading : emptyHeading,
+    "",
+    "Bias toward action: use the live inputSchema in these results, pick the best matching tool, and call it. Use cutoffs_describe_tool when you need more safety guidance or examples. If Cutoffs rejects the arguments, read the returned missingFields and inputSchema, then retry with corrections.",
+    "",
+    stringifyPayload(
+      tools.map((tool) => ({
+        integration: tool?.integration ?? null,
+        name: tool?.name ?? null,
+        description: tool?.description ?? tool?.summary ?? null,
+        inputSchema: tool?.inputSchema ?? null,
+        mode: tool?.mode ?? null,
+        accessLevel: tool?.accessLevel ?? null,
+        risk: tool?.risk ?? null,
+        guidanceAvailable: Boolean(tool?.guidanceAvailable),
+        requiresConfirmation: Boolean(tool?.requiresConfirmation),
+        previewAvailable: Boolean(tool?.previewAvailable),
+        defaultConnectionId: tool?.defaultConnectionId ?? null,
+        connectionCount: tool?.connectionCount ?? 0,
+      })),
+    ),
+  ].join("\n");
+}
+
+function buildToolDescriptionText(payload) {
+  const summary = payload?.tool ?? payload;
+
+  return [
+    "Cutoffs tool description:",
+    "",
+    stringifyPayload(summary),
+  ].join("\n");
+}
+
+function storedResultHint(payload) {
+  const candidate = payload?.result ?? payload?.data ?? payload;
+  const envelope =
+    candidate && typeof candidate === "object" && candidate.cutoffs_result === "stored"
+      ? candidate
+      : null;
+  if (!envelope) {
+    return null;
+  }
+
+  return [
+    "",
+    `This result is large and stored server-side (execution_id: ${envelope.execution_id}). Do not paste it or ask the user to.`,
+    `Read only what you need with cutoffs_get_result: { executionId: "${envelope.execution_id}", path, fields, offset, limit } (or count for just the shape).`,
+  ].join("\n");
+}
+
+function buildToolExecutionText(toolName, payload) {
+  const summary = {
+    tool: payload?.tool?.name ?? toolName,
+    integration: payload?.tool?.integration ?? null,
+    connectionId: payload?.connectionId ?? null,
+    requiresConfirmation: Boolean(payload?.requiresConfirmation),
+    policyReason: payload?.policyReason ?? null,
+    args: payload?.args ?? null,
+    result: payload?.result ?? payload,
+  };
+
+  const hint = storedResultHint(payload);
+
+  return [
+    `Cutoffs tool result: ${toolName}`,
+    "",
+    stringifyPayload(summary),
+    ...(hint ? [hint] : []),
+  ].join("\n");
+}
+
+function buildToolErrorText(toolName, error) {
+  const status = error?.cutoffsStatus ?? null;
+  const formatted =
+    typeof error?.message === "string" && error.message.trim()
+      ? error.message
+      : `Cutoffs request failed${status ? ` with status ${status}` : ""}.`;
+  return [`Cutoffs tool failed: ${toolName}`, "", formatted].join("\n");
+}
+
+function buildPluginValidationResult(toolName, error) {
+  const payload = {
+    ok: false,
+    error: {
+      type: "validation",
+      code: error.code ?? "invalid_file_upload",
+      message: error.message,
+      retryable: false,
+    },
+    details: [error.message],
+    missingFields: [],
+    invalidFields: error.invalidFields ?? [],
+    hint: error.hint,
+  };
+  const formattedError = new Error(formatStructuredCutoffsError(payload, 400));
+  formattedError.cutoffsPayload = payload;
+  formattedError.cutoffsStatus = 400;
+  return textResult(buildToolErrorText(toolName, formattedError), payload);
+}
+
+async function callToolWithErrorContent(toolName, api, path, options) {
+  try {
+    const payload = await callCutoffs(api, path, options);
+    return textResult(buildToolExecutionText(toolName, payload), payload);
+  } catch (error) {
+    if (error && typeof error === "object" && "cutoffsPayload" in error) {
+      return textResult(buildToolErrorText(toolName, error), error.cutoffsPayload);
+    }
+    throw error;
+  }
+}
+
+function buildPairingStartText(payload) {
+  const summary = buildPairingSummary(payload);
+
+  return [
+    "Cutoffs browser pairing started.",
+    "",
+    "Open the pairing URL in your browser, sign in to Cutoffs if needed, and approve this OpenClaw device. After approval, come back here and send `done` so OpenClaw can finish pairing safely.",
+    "",
+    stringifyPayload(summary),
+  ].join("\n");
+}
+
+function buildPairingSummary(payload) {
+  const session = payload?.session ?? null;
+
+  return {
+    status: session?.status ?? payload?.status ?? null,
+    sessionToken: session?.token ?? payload?.sessionToken ?? null,
+    deviceLabel: session?.deviceLabel ?? payload?.deviceLabel ?? null,
+    approvedUserHint: session?.approvedUserHint ?? null,
+    expiresAt: session?.expiresAt ?? payload?.expiresAt ?? null,
+    approvedAt: session?.approvedAt ?? null,
+    pairedAt: session?.pairedAt ?? null,
+    pairUrl: payload?.pairUrl ?? null,
+    pollIntervalMs: payload?.pollIntervalMs ?? null,
+    integrations: Array.isArray(payload?.integrations) ? payload.integrations : undefined,
+  };
+}
+
+function buildPairingPendingText(payload) {
+  return [
+    "Cutoffs pairing is still waiting for browser approval.",
+    "",
+    "Keep the pairing page open and approve this device. After approval, come back here and send `done` so OpenClaw can finish pairing.",
+    "",
+    stringifyPayload(buildPairingSummary(payload)),
+  ].join("\n");
+}
+
+function buildPairingProgressText(payload) {
+  return [
+    "Cutoffs browser approval received.",
+    "",
+    "Go back to OpenClaw and send `done` to finish the local setup.",
+    "",
+    stringifyPayload(buildPairingSummary(payload)),
+  ].join("\n");
+}
+
+function buildPairingCompletionText(payload) {
+  return [
+    "Cutoffs pairing completed.",
+    "",
+    "The local device credential is saved and ready to use.",
+    "",
+    stringifyPayload(buildPairingSummary(payload)),
+  ].join("\n");
+}
+
+function buildPairingStatusText(payload) {
+  return [
+    "Cutoffs pairing status:",
+    "",
+    stringifyPayload(buildPairingSummary(payload)),
+  ].join("\n");
+}
+
+function collectToolArguments(params, reservedKeys) {
+  if (isPlainObject(params.arguments)) {
+    return params.arguments;
+  }
+
+  const fallback = {};
+
+  for (const [key, value] of Object.entries(params ?? {})) {
+    if (reservedKeys.has(key)) {
+      continue;
+    }
+
+    fallback[key] = value;
+  }
+
+  return fallback;
+}
+
+async function persistPluginConfig(api, mutateConfig) {
+  const runtimeConfig = api.runtime?.config;
+
+  if (
+    typeof runtimeConfig?.loadConfig === "function" &&
+    typeof runtimeConfig?.writeConfigFile === "function"
+  ) {
+    const currentConfig = runtimeConfig.loadConfig();
+    const nextConfig = mutateConfig(structuredClone(currentConfig));
+
+    await runtimeConfig.writeConfigFile(nextConfig);
+
+    return nextConfig;
+  }
+
+  const fallbackRuntime = await import("openclaw/plugin-sdk/config-runtime");
+
+  if (typeof fallbackRuntime.updateConfig === "function") {
+    return fallbackRuntime.updateConfig((currentConfig) =>
+      mutateConfig(structuredClone(currentConfig)),
+    );
+  }
+
+  if (
+    typeof fallbackRuntime.loadConfig === "function" &&
+    typeof fallbackRuntime.writeConfigFile === "function"
+  ) {
+    const currentConfig = fallbackRuntime.loadConfig();
+    const nextConfig = mutateConfig(structuredClone(currentConfig));
+
+    await fallbackRuntime.writeConfigFile(nextConfig);
+
+    return nextConfig;
+  }
+
+  throw new Error("OpenClaw runtime config API is unavailable.");
+}
+
+function updatePluginEntryConfig(config, updater) {
+  const currentPlugins = config.plugins ?? {};
+  const currentEntries = currentPlugins.entries ?? {};
+  const legacyEntry = LEGACY_PLUGIN_IDS.map((pluginId) => currentEntries[pluginId]).find(
+    (entry) => entry && typeof entry === "object",
+  );
+  const currentEntry = currentEntries[PLUGIN_ID] ?? legacyEntry ?? {};
+  const currentPluginConfig = currentEntry.config ?? {};
+  const nextPluginConfig = updater({ ...currentPluginConfig });
+  const nextEntries = {
+    ...currentEntries,
+    [PLUGIN_ID]: {
+      ...currentEntry,
+      enabled: true,
+      config: nextPluginConfig,
+    },
+  };
+
+  for (const legacyPluginId of LEGACY_PLUGIN_IDS) {
+    if (legacyPluginId !== PLUGIN_ID) {
+      delete nextEntries[legacyPluginId];
+    }
+  }
+
+  return {
+    ...config,
+    plugins: {
+      ...currentPlugins,
+      entries: nextEntries,
+    },
+  };
+}
+
+async function saveApiKeyToConfig(api, apiKey, options = {}) {
+  const clearPendingPairing = options.clearPendingPairing !== false;
+
+  await persistPluginConfig(api, (config) =>
+    updatePluginEntryConfig(config, (pluginConfig) => {
+      const nextPluginConfig = {
+        ...pluginConfig,
+        apiKey,
+      };
+
+      delete nextPluginConfig.baseUrl;
+
+      if (clearPendingPairing) {
+        delete nextPluginConfig.pendingPairing;
+      }
+
+      return nextPluginConfig;
+    }),
+  );
+}
+
+async function clearPendingPairing(api) {
+  await persistPluginConfig(api, (config) =>
+    updatePluginEntryConfig(config, (pluginConfig) => {
+      const nextPluginConfig = { ...pluginConfig };
+      delete nextPluginConfig.pendingPairing;
+      return nextPluginConfig;
+    }),
+  );
+}
+
+async function savePendingPairing(api, pairing) {
+  await persistPluginConfig(api, (config) =>
+    updatePluginEntryConfig(config, (pluginConfig) => ({
+      ...pluginConfig,
+      pendingPairing: pairing,
+    })),
+  );
+}
+
+function isPendingPairingExpired(pendingPairing) {
+  if (!pendingPairing?.expiresAt) {
+    return true;
+  }
+
+  const expiresAt = Date.parse(pendingPairing.expiresAt);
+
+  return Number.isFinite(expiresAt) ? expiresAt <= Date.now() : true;
+}
+
+function normalizePairingPollIntervalMs(value) {
+  if (typeof value === "number" && Number.isFinite(value) && value >= 0) {
+    return Math.floor(value);
+  }
+
+  return DEFAULT_PAIRING_POLL_INTERVAL_MS;
+}
+
+function resolvePairingWaitTimeoutMs(pendingPairing) {
+  const expiresAt = Date.parse(pendingPairing?.expiresAt ?? "");
+
+  if (Number.isFinite(expiresAt)) {
+    return Math.max(0, Math.min(DEFAULT_PAIRING_WAIT_TIMEOUT_MS, expiresAt - Date.now()));
+  }
+
+  return DEFAULT_PAIRING_WAIT_TIMEOUT_MS;
+}
+
+function createAbortError() {
+  const error = new Error("Cutoffs pairing was interrupted before completion.");
+  error.name = "AbortError";
+  return error;
+}
+
+async function waitForPairingPollDelay(ms, signal) {
+  if (ms <= 0) {
+    return;
+  }
+
+  await new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      cleanup();
+      resolve();
+    }, ms);
+
+    const handleAbort = () => {
+      cleanup();
+      reject(createAbortError());
+    };
+
+    const cleanup = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", handleAbort);
+    };
+
+    if (signal?.aborted) {
+      handleAbort();
+      return;
+    }
+
+    signal?.addEventListener("abort", handleAbort, { once: true });
+  });
+}
+
+async function exchangeAndFinalizePairing(api, pendingPairing) {
+  const exchanged = await callCutoffsPublic(
+    `/api/openclaw/pair/sessions/${encodeURIComponent(pendingPairing.sessionToken)}/exchange`,
+    {
+      method: "POST",
+      body: { verifier: pendingPairing.verifier },
+    },
+  );
+  const apiKey = safeTrim(exchanged?.apiKey);
+
+  if (!apiKey) {
+    throw new Error("Cutoffs pairing did not return a local device credential.");
+  }
+
+  await saveApiKeyToConfig(api, apiKey, {
+    clearPendingPairing: false,
+  });
+
+  let finalizedSession = exchanged?.session ?? null;
+
+  try {
+    const finalized = await callCutoffsPublic(
+      `/api/openclaw/pair/sessions/${encodeURIComponent(pendingPairing.sessionToken)}/finalize`,
+      {
+        method: "POST",
+        body: { verifier: pendingPairing.verifier },
+      },
+    );
+    finalizedSession = finalized?.session ?? finalizedSession;
+    await clearPendingPairing(api);
+  } catch {
+    // Keep the pending pairing marker so the plugin can retry finalization later.
+  }
+
+  const integrationsPayload = await callCutoffs(api, "/api/integrations").catch(() => ({
+    integrations: [],
+  }));
+
+  return {
+    session: finalizedSession,
+    integrations: Array.isArray(integrationsPayload?.integrations)
+      ? integrationsPayload.integrations
+      : [],
+  };
+}
+
+async function getPairingStatus(api) {
+  const { pendingPairing, apiKey } = getPluginConfig(api);
+
+  if (!pendingPairing) {
+    if (apiKey) {
+      const integrationsPayload = await callCutoffs(api, "/api/integrations").catch(() => ({
+        integrations: [],
+      }));
+
+      return {
+        session: {
+          status: "paired",
+          token: null,
+          displayCode: null,
+          deviceLabel: null,
+          approvedUserHint: null,
+          expiresAt: null,
+          approvedAt: null,
+          pairedAt: null,
+        },
+        integrations: Array.isArray(integrationsPayload?.integrations)
+          ? integrationsPayload.integrations
+          : [],
+      };
+    }
+
+    throw new Error("No Cutoffs pairing session is in progress.");
+  }
+
+  if (isPendingPairingExpired(pendingPairing)) {
+    await clearPendingPairing(api);
+    throw new Error("The pending Cutoffs pairing session expired. Start a new pairing flow.");
+  }
+
+  const payload = await callCutoffsPublic(
+    `/api/openclaw/pair/sessions/${encodeURIComponent(pendingPairing.sessionToken)}`,
+  );
+  const status = safeTrim(payload?.session?.status);
+
+  if (status === "ready_for_device" || status === "awaiting_local_save") {
+    const completed = await exchangeAndFinalizePairing(api, pendingPairing);
+
+    return {
+      session: {
+        ...(completed.session ?? {}),
+      },
+      pairUrl: pendingPairing.pairUrl,
+      integrations: completed.integrations,
+    };
+  }
+
+  if (status === "expired" || status === "failed") {
+    await clearPendingPairing(api);
+  }
+
+  return {
+    ...payload,
+    pairUrl: pendingPairing.pairUrl,
+  };
+}
+
+async function waitForPairingCompletion(api, pendingPairing, options = {}) {
+  const pollIntervalMs = normalizePairingPollIntervalMs(options.pollIntervalMs);
+  const timeoutMs =
+    typeof options.timeoutMs === "number" && Number.isFinite(options.timeoutMs)
+      ? Math.max(0, Math.floor(options.timeoutMs))
+      : resolvePairingWaitTimeoutMs(pendingPairing);
+  const onUpdate = typeof options.onUpdate === "function" ? options.onUpdate : null;
+  const initialPayload = {
+    session: {
+      status: "awaiting_browser",
+      token: pendingPairing.sessionToken,
+      deviceLabel: pendingPairing.deviceLabel || "OpenClaw device",
+      approvedUserHint: null,
+      expiresAt: pendingPairing.expiresAt,
+      approvedAt: null,
+      pairedAt: null,
+    },
+    pairUrl: pendingPairing.pairUrl,
+    pollIntervalMs,
+  };
+
+  onUpdate?.(textResult(buildPairingStartText({ ...initialPayload, autoFinish: true }), initialPayload));
+
+  const deadline = Date.now() + timeoutMs;
+  let lastStatus = "awaiting_browser";
+  let lastPayload = initialPayload;
+
+  while (Date.now() <= deadline) {
+    if (options.signal?.aborted) {
+      throw createAbortError();
+    }
+
+    const payload = await getPairingStatus(api);
+    const status = safeTrim(payload?.session?.status) || "awaiting_browser";
+
+    lastPayload = payload;
+
+    if (onUpdate && status !== lastStatus) {
+      if (status === "ready_for_device" || status === "awaiting_local_save") {
+        onUpdate(textResult(buildPairingProgressText(payload), payload));
+      } else if (status === "paired") {
+        onUpdate(textResult(buildPairingCompletionText(payload), payload));
+      } else if (status === "expired" || status === "failed") {
+        onUpdate(textResult(buildPairingStatusText(payload), payload));
+      }
+    }
+
+    lastStatus = status;
+
+    if (status === "paired" || status === "expired" || status === "failed") {
+      return payload;
+    }
+
+    const remainingMs = deadline - Date.now();
+
+    if (remainingMs <= 0) {
+      break;
+    }
+
+    await waitForPairingPollDelay(Math.min(pollIntervalMs, remainingMs), options.signal);
+  }
+
+  return lastPayload;
+}
+
+function buildCommandHelp() {
+  return [
+    "Cutoffs commands:",
+    "",
+    "/cutoffs pair [deviceLabel]",
+    "/cutoffs pair-status",
+    "/cutoffs status",
+    "/cutoffs logout",
+  ].join("\n");
+}
+
+const cutoffsPlugin = {
+  id: PLUGIN_ID,
+  name: "Cutoffs",
+  description: "Generic Cutoffs bridge for hosted connections and dynamic integration tools inside OpenClaw",
+  register(api) {
+    api.registerCommand({
+      name: "cutoffs",
+      description: "Configure Cutoffs pairing and inspect plugin status.",
+      acceptsArgs: true,
+      handler: async (ctx) => {
+        const tokens = tokenizeArgs(ctx.args);
+        const action = (tokens[0] ?? "help").toLowerCase();
+
+        if (action === "help") {
+          return { text: buildCommandHelp() };
+        }
+
+        if (action === "status") {
+          const { apiKey, pendingPairing } = getPluginConfig(api);
+
+          return {
+            text: [
+              "Cutoffs status:",
+              `- credential: ${maskSecret(apiKey)}`,
+              `- configured: ${apiKey ? "yes" : "no"}`,
+              `- pairing: ${
+                pendingPairing
+                  ? isPendingPairingExpired(pendingPairing)
+                    ? "expired"
+                    : "pending"
+                  : apiKey
+                    ? "not needed"
+                    : "idle"
+              }`,
+              ...(pendingPairing && !isPendingPairingExpired(pendingPairing)
+                ? [
+                    `- pairUrl: ${pendingPairing.pairUrl}`,
+                    `- expiresAt: ${pendingPairing.expiresAt}`,
+                  ]
+                : []),
+            ].join("\n"),
+          };
+        }
+
+        if (action === "pair") {
+          const { apiKey, pendingPairing } = getPluginConfig(api);
+
+          if (apiKey) {
+            return {
+              text: "Cutoffs is already configured on this OpenClaw install. Use /cutoffs logout first if you want to pair a different account.",
+            };
+          }
+
+          if (pendingPairing && !isPendingPairingExpired(pendingPairing)) {
+            return {
+              text: buildPairingStartText({
+                sessionToken: pendingPairing.sessionToken,
+                deviceLabel: pendingPairing.deviceLabel || "OpenClaw device",
+                pairUrl: pendingPairing.pairUrl,
+                expiresAt: pendingPairing.expiresAt,
+                pollIntervalMs: DEFAULT_PAIRING_POLL_INTERVAL_MS,
+              }),
+            };
+          }
+
+          const deviceLabel = tokens.slice(1).join(" ").trim() || "OpenClaw device";
+          const payload = await callCutoffsPublic("/api/openclaw/pair/start", {
+            method: "POST",
+            body: { deviceLabel },
+          });
+
+          await savePendingPairing(api, {
+            sessionToken: payload.sessionToken,
+            verifier: payload.verifier,
+            pairUrl: payload.pairUrl,
+            displayCode: payload.displayCode,
+            deviceLabel: payload.deviceLabel || deviceLabel,
+            expiresAt: payload.expiresAt,
+          });
+
+          return { text: buildPairingStartText(payload) };
+        }
+
+        if (action === "pair-status") {
+          const payload = await getPairingStatus(api);
+          return { text: buildPairingStatusText(payload) };
+        }
+
+        if (action === "login") {
+          return {
+            text: "Manual credential entry is no longer supported. Use /cutoffs pair to start browser pairing.",
+          };
+        }
+
+        if (action === "logout") {
+          await persistPluginConfig(api, (config) =>
+            updatePluginEntryConfig(config, (pluginConfig) => {
+              const nextPluginConfig = { ...pluginConfig };
+
+              delete nextPluginConfig.apiKey;
+              delete nextPluginConfig.baseUrl;
+              delete nextPluginConfig.pendingPairing;
+
+              return nextPluginConfig;
+            }),
+          );
+
+          return { text: "Cutoffs credentials removed from local OpenClaw config." };
+        }
+
+        return { text: buildCommandHelp() };
+      },
+    });
+
+    api.registerTool({
+      name: "cutoffs_begin_pairing",
+      description: "Start or resume browser pairing for this OpenClaw install. Use this when Cutoffs is not configured yet so the user can approve the device in a browser without manual credential entry. After the user approves in the browser and comes back saying they are done, call cutoffs_get_pairing_status to finish the local setup.",
+      parameters: Type.Object({
+        deviceLabel: Type.Optional(Type.String({
+          description: "Optional friendly label for this OpenClaw device, for example Steve's MacBook.",
+          minLength: 1,
+        })),
+      }),
+      async execute(_id, params, _signal, _onUpdate) {
+        const { apiKey, pendingPairing } = getPluginConfig(api);
+
+        if (apiKey) {
+          return textResult(
+            "Cutoffs is already configured on this OpenClaw install. No pairing is needed unless the user wants to switch accounts.",
+            {
+              configured: true,
+            },
+          );
+        }
+
+        if (pendingPairing && isPendingPairingExpired(pendingPairing)) {
+          await clearPendingPairing(api);
+        }
+
+        const deviceLabel = isNonEmptyString(params.deviceLabel)
+          ? params.deviceLabel.trim()
+          : "OpenClaw device";
+
+        if (pendingPairing && !isPendingPairingExpired(pendingPairing)) {
+          const payload = {
+            status: "awaiting_browser",
+            sessionToken: pendingPairing.sessionToken,
+            deviceLabel: pendingPairing.deviceLabel || deviceLabel,
+            pairUrl: pendingPairing.pairUrl,
+            expiresAt: pendingPairing.expiresAt,
+            pollIntervalMs: DEFAULT_PAIRING_POLL_INTERVAL_MS,
+          };
+
+          return textResult(buildPairingStartText(payload), payload);
+        }
+
+        const payload = await callCutoffsPublic("/api/openclaw/pair/start", {
+          method: "POST",
+          body: {
+            deviceLabel,
+          },
+        });
+
+        await savePendingPairing(api, {
+          sessionToken: payload.sessionToken,
+          verifier: payload.verifier,
+          pairUrl: payload.pairUrl,
+          displayCode: payload.displayCode,
+          deviceLabel: payload.deviceLabel || deviceLabel,
+          expiresAt: payload.expiresAt,
+        });
+
+        const startPayload = {
+          ...payload,
+          pollIntervalMs: normalizePairingPollIntervalMs(payload?.pollIntervalMs),
+        };
+
+        return textResult(buildPairingStartText(startPayload), startPayload);
+      },
+    });
+
+    api.registerTool({
+      name: "cutoffs_get_pairing_status",
+      description: "Check whether browser pairing has been approved yet. Use this after the user comes back from the browser and says they are done. When approval is complete, this tool exchanges the session for a locally stored Cutoffs credential and finalizes pairing.",
+      parameters: Type.Object({}),
+      async execute() {
+        const payload = await getPairingStatus(api);
+        return textResult(buildPairingStatusText(payload), payload);
+      },
+    });
+
+    api.registerTool({
+      name: "cutoffs_start_connection",
+      description: "Internal: check whether a Cutoffs integration is already connected. Prefer `cutoffs_list_integrations` for this. Do NOT use this tool to start a new connection from chat — when an integration is not connected, tell the user to open https://cutoffs.dev/dashboard and connect it there. If the user already has an active connection, the response will be `alreadyConnected: true`.",
+      parameters: Type.Object({
+        integration: Type.String({
+          description: "Integration slug to connect, for example slack, github, or notion.",
+          minLength: 1,
+        }),
+        forceNew: Type.Optional(Type.Boolean({
+          description: "Set to true only if the user explicitly wants to add an additional connection alongside an existing one. Defaults to false, which reuses the existing active connection when present.",
+        })),
+      }),
+      async execute(_id, params) {
+        const integration = isNonEmptyString(params.integration) ? params.integration.trim() : "";
+
+        if (!integration) {
+          throw new Error("integration is required");
+        }
+
+        const payload = await callCutoffs(api, "/api/connect/start", {
+          method: "POST",
+          body: {
+            integration,
+            reuseIfConnected: params.forceNew !== true,
+          },
+        });
+
+        return textResult(buildStartConnectionText(payload), payload);
+      },
+    });
+
+    api.registerTool({
+      name: "cutoffs_get_connection_status",
+      description: "Internal: poll a hosted Cutoffs connection session by token. Rarely needed — connection setup is done in the dashboard at https://cutoffs.dev/dashboard, and `cutoffs_list_integrations` is the right way to confirm a new connection is live.",
+      parameters: Type.Object({
+        sessionToken: Type.String({
+          description: "Session token returned by cutoffs_start_connection.",
+          minLength: 1,
+        }),
+      }),
+      async execute(_id, params) {
+        const sessionToken = isNonEmptyString(params.sessionToken)
+          ? params.sessionToken.trim()
+          : "";
+
+        if (!sessionToken) {
+          throw new Error("sessionToken is required");
+        }
+
+        const payload = await callCutoffs(
+          api,
+          `/api/connect/sessions/${encodeURIComponent(sessionToken)}`,
+        );
+
+        return textResult(buildStatusText(payload), payload);
+      },
+    });
+
+    api.registerTool({
+      name: "cutoffs_list_integrations",
+      description: "List all external apps and services currently connected through Cutoffs.",
+      parameters: Type.Object({}),
+      async execute() {
+        const payload = await callCutoffs(api, "/api/integrations");
+        return textResult(buildIntegrationListText(payload), payload);
+      },
+    });
+
+    api.registerTool({
+      name: "cutoffs_list_tools",
+      description: "List the live Cutoffs tools for one connected integration so you can act instead of guessing. Results include each tool's current inputSchema. Pass the integration slug from cutoffs_list_integrations, then choose the best tool and call it.",
+      parameters: Type.Object({
+        integration: Type.String({
+          description: "Required integration slug to list only that app's tools, for example youtube, gmail, slack, notion, or github. Call cutoffs_list_integrations first if you do not know the slug.",
+          minLength: 1,
+        }),
+      }),
+      async execute(_id, params) {
+        const integration = isNonEmptyString(params?.integration)
+          ? params.integration.trim().toLowerCase()
+          : "";
+
+        if (!integration) {
+          throw new Error("integration is required. Call cutoffs_list_integrations first, then call cutoffs_list_tools with that integration slug.");
+        }
+
+        const path = `/api/tools?${new URLSearchParams({ integration }).toString()}`;
+        const payload = await callCutoffs(api, path);
+        return textResult(buildToolListText(payload), payload);
+      },
+    });
+
+    api.registerTool({
+      name: "cutoffs_search_tools",
+      description: "Search the user's connected Cutoffs tools by capability or keyword when you know the goal but not the exact tool name. Results include the live inputSchema for each match. Pick the best match and call it rather than asking the user to translate provider docs into arguments.",
+      parameters: Type.Object({
+        query: Type.String({
+          description: "Capability or keyword to search for, for example playlist, send email, channel statistics, create event, upload file, or list records.",
+          minLength: 1,
+        }),
+        integration: Type.Optional(Type.String({
+          description: "Optional connected integration slug to narrow results, for example youtube, gmail, slack, notion, or github.",
+          minLength: 1,
+        })),
+        limit: Type.Optional(Type.Integer({
+          description: "Maximum number of matches to return. Defaults to 10 and is capped by Cutoffs.",
+          minimum: 1,
+          maximum: 25,
+        })),
+      }),
+      async execute(_id, params) {
+        const query = isNonEmptyString(params?.query) ? params.query.trim() : "";
+
+        if (!query) {
+          throw new Error("query is required");
+        }
+
+        const searchParams = new URLSearchParams({ query });
+        const integration = isNonEmptyString(params?.integration)
+          ? params.integration.trim().toLowerCase()
+          : "";
+
+        if (integration) {
+          searchParams.set("integration", integration);
+        }
+
+        if (Number.isInteger(params?.limit)) {
+          searchParams.set("limit", String(params.limit));
+        }
+
+        const payload = await callCutoffs(api, `/api/tools/search?${searchParams.toString()}`);
+        return textResult(buildToolListText(payload), payload);
+      },
+    });
+
+    api.registerTool({
+      name: "cutoffs_describe_tool",
+      description: "Get the live recipe card for one Cutoffs tool: inputSchema, safety guidance, examples, prerequisites, and follow-up hints. Use this when a tool is unfamiliar or the call is write-like, then execute with your best guess.",
+      parameters: Type.Object({
+        tool: Type.String({
+          description: "Cutoffs tool name, for example notion_search or gmail_find_email.",
+          minLength: 1,
+        }),
+      }),
+      async execute(_id, params) {
+        const tool = isNonEmptyString(params.tool) ? params.tool.trim() : "";
+
+        if (!tool) {
+          throw new Error("tool is required");
+        }
+
+        const payload = await callCutoffs(api, `/api/tools/${encodeURIComponent(tool)}`);
+        return textResult(buildToolDescriptionText(payload), payload);
+      },
+    });
+
+    api.registerTool({
+      name: "cutoffs_preview_tool",
+      description: "Preview a Cutoffs tool call without side effects. Use this when a write tool feels risky or the arguments are still uncertain. Preview returns the same validation shape as a real call, so you can correct fields before executing.",
+      parameters: Type.Object({
+        tool: Type.String({
+          description: "Cutoffs tool name, for example notion_create_page or gmail_send_email.",
+          minLength: 1,
+        }),
+        arguments: Type.Optional(Type.Record(Type.String(), Type.Unknown(), {
+          description: "Arguments for the selected tool.",
+        })),
+        connectionId: Type.Optional(Type.Integer({
+          description: "Optional Cutoffs connection id when the user has multiple connections for one integration.",
+          minimum: 1,
+        })),
+      }),
+      async execute(_id, params) {
+        const tool = isNonEmptyString(params.tool) ? params.tool.trim() : "";
+        const args = collectToolArguments(
+          params,
+          new Set(["tool", "arguments", "connectionId"]),
+        );
+
+        if (!tool) {
+          throw new Error("tool is required");
+        }
+
+        let files;
+        try {
+          files = buildFilesEnvelope(args);
+        } catch (error) {
+          if (error instanceof CutoffsPluginValidationError) {
+            return buildPluginValidationResult(tool, error);
+          }
+          throw error;
+        }
+
+        return callToolWithErrorContent(
+          tool,
+          api,
+          `/api/tools/${encodeURIComponent(tool)}/preview`,
+          {
+            method: "POST",
+            body: {
+              arguments: args,
+              ...(Number.isInteger(params.connectionId)
+                ? { connectionId: params.connectionId }
+                : {}),
+              ...(files.length > 0 ? { files } : {}),
+            },
+          },
+        );
+      },
+    });
+
+    api.registerTool({
+      name: "cutoffs_call_tool",
+      description: "Run a Cutoffs tool aggressively using the live tool catalog and inputSchema as your source of truth. Do not ask the user which fields to use when the schema already tells you. If Cutoffs rejects the arguments, the error includes missingFields and the full inputSchema, so inspect that payload and retry with corrected fields.",
+      parameters: Type.Object({
+        tool: Type.String({
+          description: "Cutoffs tool name, for example notion_search or github_list_issues.",
+          minLength: 1,
+        }),
+        arguments: Type.Optional(Type.Record(Type.String(), Type.Unknown(), {
+          description: "Arguments for the selected tool.",
+        })),
+        connectionId: Type.Optional(Type.Integer({
+          description: "Optional Cutoffs connection id when the user has multiple connections for one integration.",
+          minimum: 1,
+        })),
+        confirmed: Type.Optional(Type.Boolean({
+          description: "Defaults to true. Pass false only when you want Cutoffs to refuse a write tool that needs explicit re-confirmation; use cutoffs_preview_tool for dry runs instead.",
+        })),
+      }),
+      async execute(_id, params) {
+        const tool = isNonEmptyString(params.tool) ? params.tool.trim() : "";
+        const args = collectToolArguments(
+          params,
+          new Set(["tool", "arguments", "connectionId", "confirmed"]),
+        );
+
+        if (!tool) {
+          throw new Error("tool is required");
+        }
+
+        const confirmed = params.confirmed !== false;
+
+        let files;
+        try {
+          files = buildFilesEnvelope(args);
+        } catch (error) {
+          if (error instanceof CutoffsPluginValidationError) {
+            return buildPluginValidationResult(tool, error);
+          }
+          throw error;
+        }
+
+        return callToolWithErrorContent(
+          tool,
+          api,
+          `/api/tools/${encodeURIComponent(tool)}/execute`,
+          {
+            method: "POST",
+            // Opt into result offloading: large results come back as a compact
+            // stored envelope (read with cutoffs_get_result) instead of flooding
+            // context. Servers that predate offloading ignore this header.
+            headers: { "x-cutoffs-capabilities": "offload" },
+            body: {
+              arguments: args,
+              ...(Number.isInteger(params.connectionId)
+                ? { connectionId: params.connectionId }
+                : {}),
+              confirmed,
+              ...(files.length > 0 ? { files } : {}),
+            },
+          },
+        );
+      },
+    });
+
+    api.registerTool({
+      name: "cutoffs_get_result",
+      description:
+        "Read a large stored Cutoffs result in slices instead of dumping the whole thing into context. When cutoffs_call_tool returns a result marked \"cutoffs_result\": \"stored\", call this with its execution_id and selectors to fetch only the part you need. Never ask the user to paste large data.",
+      parameters: Type.Object({
+        executionId: Type.String({
+          description: "The execution_id from a stored Cutoffs result envelope.",
+          minLength: 1,
+        }),
+        path: Type.Optional(Type.String({
+          description: "Dot path into the stored result, for example \"messages\" or \"data.items\". Omit for the whole result.",
+        })),
+        fields: Type.Optional(Type.Array(Type.String(), {
+          description: "Return only these keys from each item (when the value at path is an array) or from the object.",
+        })),
+        offset: Type.Optional(Type.Integer({
+          description: "Pagination offset when the value at path is an array.",
+          minimum: 0,
+        })),
+        limit: Type.Optional(Type.Integer({
+          description: "Pagination size when the value at path is an array. Defaults to 25, max 200.",
+          minimum: 1,
+          maximum: 200,
+        })),
+        count: Type.Optional(Type.Boolean({
+          description: "Return only the shape/size of the value at path, no data.",
+        })),
+      }),
+      async execute(_id, params) {
+        const executionId = isNonEmptyString(params.executionId) ? params.executionId.trim() : "";
+
+        if (!executionId) {
+          throw new Error("executionId is required. Pass the execution_id from a stored result envelope.");
+        }
+
+        const search = new URLSearchParams();
+        if (isNonEmptyString(params.path)) {
+          search.set("path", params.path.trim());
+        }
+        if (Array.isArray(params.fields)) {
+          const fields = params.fields.filter(isNonEmptyString).map((field) => field.trim());
+          if (fields.length > 0) {
+            search.set("fields", fields.join(","));
+          }
+        }
+        if (Number.isInteger(params.offset)) {
+          search.set("offset", String(params.offset));
+        }
+        if (Number.isInteger(params.limit)) {
+          search.set("limit", String(params.limit));
+        }
+        if (params.count === true) {
+          search.set("count", "true");
+        }
+
+        const query = search.toString();
+        const payload = await callCutoffs(
+          api,
+          `/api/executions/${encodeURIComponent(executionId)}${query ? `?${query}` : ""}`,
+          { headers: { "x-cutoffs-capabilities": "offload" } },
+        );
+
+        return textResult(
+          [`Cutoffs stored result: ${executionId}`, "", stringifyPayload(payload)].join("\n"),
+          payload,
+        );
+      },
+    });
+  },
+};
+
+export default cutoffsPlugin;