cartethyia 2.4.6 → 2.5.0

package/src/providers/integrations/cursor/cursor-identity.ts

@@ -0,0 +1,92 @@
+// Stable, non-secret installation identity for the Cursor integration.
+//
+// Cursor keys device identity off the ids embedded in `x-cursor-checksum` and
+// treats every new machineId as a separate device ("too many connections from
+// different devices"), so the fingerprint MUST be stable across restarts and
+// across processes on one host.
+//
+// The donor derived it from OS identifiers (IOPlatformUUID / MAC address) by
+// shelling out to `ioreg` / `reg query`. Cartethyia does not run provider code
+// that spawns a shell per dispatch: the identity is instead derived from
+// Cartethyia's own persisted installation id, which is stable for one
+// installation and is never derived from a credential. A credential-derived id
+// would rotate whenever an operator re-authenticated, which is exactly the
+// "too many devices" symptom the stability exists to avoid.
+import { createHash } from "node:crypto";
+import { getOrCreateInstallId } from "../shared/install-id";
+
+/** One process-lifetime cache: the id is stable, so it is read once. */
+let cached: { machineId: string; macMachineId: string } | undefined;
+let inFlight: Promise<{ machineId: string; macMachineId: string }> | undefined;
+
+function sha256Hex(value: string): string {
+  return createHash("sha256").update(value, "utf8").digest("hex");
+}
+
+/**
+ * Stable device fingerprints for the `x-cursor-checksum` header.
+ *
+ * `machineId` and `macMachineId` are two distinct hashes of one stable install
+ * id, mirroring the donor's two-id shape without reading a MAC address (which
+ * would make the fingerprint depend on hardware that a container may not have).
+ * Neither value is logged: they are device identity, not diagnostics.
+ */
+export async function resolveCursorDeviceIds(): Promise<{
+  machineId: string;
+  macMachineId: string;
+}> {
+  if (cached !== undefined) return cached;
+  inFlight ??= (async () => {
+    const installId = await getOrCreateInstallId("cursor");
+    return {
+      machineId: sha256Hex(`cursor-machine:${installId}`),
+      macMachineId: sha256Hex(`cursor-mac:${installId}`),
+    };
+  })();
+  try {
+    cached = await inFlight;
+    return cached;
+  } finally {
+    inFlight = undefined;
+  }
+}
+
+/**
+ * Cursor's obfuscated checksum header value.
+ *
+ * The wire format is a base64 of an obfuscated 6-byte time prefix followed by
+ * the device ids. Ported verbatim from the donor so the server's own de-obfuscation
+ * produces the ids it expects.
+ */
+export function createCursorChecksumHeader(machineId: string, macMachineId?: string): string {
+  const n = Math.floor(Date.now() / 1e6);
+  const ts = new Uint8Array([
+    (n >> 40) & 0xff,
+    (n >> 32) & 0xff,
+    (n >> 24) & 0xff,
+    (n >> 16) & 0xff,
+    (n >> 8) & 0xff,
+    n & 0xff,
+  ]);
+  const obfuscated = obfuscate(ts);
+  let binary = "";
+  for (const byte of obfuscated) binary += String.fromCharCode(byte);
+  const prefix = btoa(binary).replace(/=+$/, "");
+  return macMachineId ? `${prefix}${machineId}/${macMachineId}` : `${prefix}${machineId}`;
+}
+
+function obfuscate(bytes: Uint8Array): Uint8Array {
+  const out = new Uint8Array(bytes);
+  let a = 165;
+  for (let i = 0; i < out.length; i++) {
+    out[i] = ((out[i]! ^ a) + i) & 0xff;
+    a = out[i]!;
+  }
+  return out;
+}
+
+/** Test seam: clears the process-lifetime cache so an injected id is re-read. */
+export function resetCursorDeviceIdCache(): void {
+  cached = undefined;
+  inFlight = undefined;
+}

package/src/providers/integrations/cursor/cursor-request.ts

@@ -0,0 +1,471 @@
+// Cartethyia-owned Cursor request builder.
+//
+// Translates a `CanonicalRequest` into Cursor's `AgentClientMessage` protobuf
+// messages. Everything here is wire construction — no transport, no session
+// state, no credentials — so it is testable against the schema without a socket.
+//
+// Two Cursor behaviours drive the shape:
+//
+// - **Nothing goes in `root_prompt_messages_json`.** A client-written entry
+//   stands in for the conversation's rendered root prompt, and Cursor then stops
+//   rendering RequestContext rules — including the host system-instructions rule
+//   the system prompt travels in. Prior history therefore rides in an escaped
+//   `<conversation_history>` prefix of the live user text instead.
+// - **Tools are advertised through `mcp_meta_tool_options`.** `AgentRunRequest.mcp_tools`
+//   stays empty on real turns; the model calls an advertised tool through the
+//   MCP exec channel, which is the only path this gateway executes.
+import type { CanonicalMessage, CanonicalRequest, ContentPart, ToolDefinition } from "../../../protocol/canonical-model";
+import { encodeMessage } from "./protocol/messages";
+import { encodeJsonAsValue } from "./protocol/struct";
+
+/**
+ * MCP namespace Cartethyia advertises client tools under.
+ *
+ * Cursor namespaces MCP tools by server, and an inbound `mcp_args` request
+ * carries both the server and the function name. Advertising under one fixed
+ * namespace is what makes "is this a tool the client declared?" decidable: a
+ * Cursor-native tool (shell, read, edit, …) arrives under a different server or
+ * with no server at all and is never executed by the gateway.
+ */
+export const CURSOR_MCP_NAMESPACE = "cartethyia";
+
+/** One tools advertisement Cursor receives in `RequestContext.mcp_meta_tool_options`. */
+export interface CursorToolDescriptor {
+  /** Cursor composite `name`: `<namespace>-<tool name>`. */
+  readonly name: string;
+  readonly description: string;
+  /** Server identifier every inbound call must echo to be executable. */
+  readonly providerIdentifier: string;
+  /** Bare function name the client declared. */
+  readonly toolName: string;
+  /** JSON Schema, encoded as a `google.protobuf.Value` on the wire. */
+  readonly inputSchema: unknown;
+}
+
+/** One image accepted from a canonical request, ready for `selected_images`. */
+export interface CursorImageInput {
+  readonly data: Uint8Array;
+  readonly mimeType: string;
+  readonly filename?: string;
+}
+
+/** Prior turn carried in the escaped history prefix of a rebased Run. */
+export interface CursorHistoryEntry {
+  readonly role: "user" | "assistant";
+  readonly content: string;
+}
+
+/** Closing tags that would let one history message end its own block early. */
+const SEED_HISTORY_TAGS = /<\/(conversation_history|user|assistant)>/gi;
+
+/**
+ * Prior turns of a Run without a checkpoint, as a transcript ahead of the live
+ * user text. `system` entries never appear: host system context travels as the
+ * system-instructions rule in RequestContext.
+ */
+export function seedHistoryUserText(
+  text: string,
+  history: readonly CursorHistoryEntry[] | undefined,
+): string {
+  const entries = (history ?? []).filter((entry) => entry.content.length > 0);
+  if (entries.length === 0) return text;
+  const transcript = entries
+    .map(
+      (entry) =>
+        `<${entry.role}>\n${entry.content.replace(SEED_HISTORY_TAGS, "<\\/$1>")}\n</${entry.role}>`,
+    )
+    .join("\n\n");
+  return `<conversation_history>\n${transcript}\n</conversation_history>\n\n${text}`;
+}
+
+/** Empty `ConversationStateStructure` for a Run with no checkpoint. */
+export function buildSeedConversationState(): Uint8Array {
+  return encodeMessage("ConversationStateStructure", {});
+}
+
+/**
+ * Advertises one request's declared function tools as Cursor MCP descriptors.
+ *
+ * A tool with no usable name is skipped rather than advertised under an
+ * invented one: an unnameable tool cannot be matched back to an inbound call,
+ * and advertising it would let the model call something the gateway cannot
+ * execute or the client cannot answer.
+ */
+export function toolDescriptorsFor(
+  tools: readonly ToolDefinition[] | undefined,
+): CursorToolDescriptor[] {
+  const descriptors: CursorToolDescriptor[] = [];
+  const seen = new Set<string>();
+  for (const tool of tools ?? []) {
+    const name = tool.name?.trim();
+    if (name === undefined || name.length === 0) continue;
+    if (seen.has(name)) continue;
+    seen.add(name);
+    descriptors.push({
+      name: `${CURSOR_MCP_NAMESPACE}-${name}`,
+      description: typeof tool.description === "string" ? tool.description : "",
+      providerIdentifier: CURSOR_MCP_NAMESPACE,
+      toolName: name,
+      inputSchema: tool.jsonSchema ?? { type: "object", properties: {} },
+    });
+  }
+  return descriptors;
+}
+
+/** `McpToolDefinition` protobuf messages for one descriptor set. */
+function mcpToolDefinitions(
+  descriptors: readonly CursorToolDescriptor[],
+): Record<string, unknown>[] {
+  return descriptors.map((descriptor) => ({
+    name: descriptor.name,
+    description: descriptor.description,
+    input_schema: encodeJsonAsValue(descriptor.inputSchema),
+    provider_identifier: descriptor.providerIdentifier,
+    tool_name: descriptor.toolName,
+  }));
+}
+
+/**
+ * Builds the RequestContext Cartethyia sends.
+ *
+ * The system prompt is a `global` rule: an untyped Cursor rule is attachable
+ * only on request, so its content would never reach the model on its own. Tools
+ * are advertised both in `tools` (#7) and in `mcp_meta_tool_options` (#34) —
+ * the meta-tool channel is the one Cursor's model actually draws its callable
+ * catalog from on a live turn.
+ */
+export function buildCursorRequestContext(input: {
+  readonly systemPrompt?: string;
+  readonly descriptors: readonly CursorToolDescriptor[];
+}): Record<string, unknown> {
+  const tools = mcpToolDefinitions(input.descriptors);
+  const rules =
+    input.systemPrompt !== undefined && input.systemPrompt.trim().length > 0
+      ? [
+          {
+            full_path: "cartethyia/system-instructions",
+            content: input.systemPrompt,
+            type: { global: {} },
+          },
+        ]
+      : [];
+  return {
+    ...(rules.length > 0 ? { rules } : {}),
+    ...(tools.length > 0 ? { tools } : {}),
+    // The host's own filesystem/web/search surface. A headless gateway has
+    // none; advertising none up front keeps Cursor from routing a tool call to
+    // a channel the gateway must then refuse.
+    mcp_file_system_options: { enabled: false },
+    web_search_enabled: false,
+    web_fetch_enabled: false,
+    ...(tools.length > 0
+      ? {
+          mcp_meta_tool_options: {
+            enabled: true,
+            mcp_descriptors: [
+              {
+                server_name: CURSOR_MCP_NAMESPACE,
+                server_identifier: CURSOR_MCP_NAMESPACE,
+                tools: tools.map((tool) => ({
+                  tool_name: tool["tool_name"],
+                  ...(typeof tool["description"] === "string"
+                    ? { description: tool["description"] }
+                    : {}),
+                  input_schema: tool["input_schema"],
+                })),
+              },
+            ],
+          },
+        }
+      : {}),
+    // Every context section the gateway does not populate is marked complete so
+    // Cursor does not wait for a follow-up the client will never send.
+    mcp_info_complete: true,
+    rules_info_complete: true,
+    env_info_complete: true,
+    repository_info_complete: true,
+    custom_subagents_info_complete: true,
+    agent_skills_info_complete: true,
+    mcp_file_system_info_complete: true,
+    git_status_info_complete: true,
+  };
+}
+
+/** Joins a request's system and instruction content into one prompt. */
+export function systemPromptFrom(request: CanonicalRequest): string | undefined {
+  const parts = [...(request.system ?? []), ...(request.instructions ?? [])];
+  const text = parts
+    .map((part) => (part.kind === "text" ? part.text : ""))
+    .filter((value) => value.length > 0)
+    .join("\n\n");
+  return text.length > 0 ? text : undefined;
+}
+
+/**
+ * Prior turns of a rebased Run, as escaped history entries.
+ *
+ * `system` turns never appear: host system context travels as the
+ * system-instructions rule, and `tool` turns become `user` entries because
+ * Cursor's seed transcript has no tool role.
+ */
+export function historyFromRequest(request: CanonicalRequest): CursorHistoryEntry[] {
+  const entries: CursorHistoryEntry[] = [];
+  for (const message of request.messages) {
+    const text = messageText(message);
+    if (text.trim().length === 0) continue;
+    if (message.role === "assistant") entries.push({ role: "assistant", content: text });
+    else if (message.role === "user" || message.role === "tool") {
+      entries.push({ role: "user", content: text });
+    }
+  }
+  return entries;
+}
+
+/** Builds `AgentClientMessage{run_request}` for one Cursor Run. */
+export function buildRunRequest(input: {
+  readonly text: string;
+  readonly modelId: string;
+  readonly conversationId: string;
+  /** Stable parent group; unlike the conversation id it survives a rebase. */
+  readonly conversationGroupId?: string;
+  readonly runId?: string;
+  readonly messageId?: string;
+  readonly history?: readonly CursorHistoryEntry[];
+  /** Cursor-declared parameter tuple (effort/context/fast) for this model. */
+  readonly parameterValues?: readonly { id: string; value: string }[];
+  readonly maxMode?: boolean;
+  readonly images?: readonly CursorImageInput[];
+  readonly descriptors?: readonly CursorToolDescriptor[];
+  readonly systemPrompt?: string;
+  /** Opaque checkpoint bytes; absent sends an empty seed state. */
+  readonly conversationState?: Uint8Array;
+  /** Resume a held Run instead of submitting another user turn. */
+  readonly action?: "user" | "resume";
+}): Uint8Array {
+  const messageId = input.messageId ?? crypto.randomUUID();
+  const seeded = !(input.conversationState && input.conversationState.length > 0);
+  const userMessage: Record<string, unknown> = {
+    text: seeded ? seedHistoryUserText(input.text, input.history) : input.text,
+    message_id: messageId,
+    // AGENT_MODE_AGENT: the default agent turn, as Cursor CLI sends it.
+    mode: 1,
+  };
+  if (input.images !== undefined && input.images.length > 0) {
+    userMessage["selected_context"] = {
+      selected_images: input.images.map((image) => ({
+        data: image.data,
+        uuid: crypto.randomUUID(),
+        ...(image.filename === undefined ? {} : { path: image.filename }),
+        mime_type: image.mimeType,
+      })),
+    };
+  }
+  const userMessageAction: Record<string, unknown> = { user_message: userMessage };
+  const requestContext = buildCursorRequestContext({
+    ...(input.systemPrompt === undefined ? {} : { systemPrompt: input.systemPrompt }),
+    descriptors: input.descriptors ?? [],
+  });
+  userMessageAction["request_context"] = requestContext;
+  const runRequest: Record<string, unknown> = {
+    conversation_id: input.conversationId,
+    conversation_group_id: input.conversationGroupId ?? input.conversationId,
+    run_id: input.runId ?? messageId,
+    action:
+      input.action === "resume"
+        ? { resume_action: { request_context: requestContext } }
+        : { user_message_action: userMessageAction },
+    requested_model: {
+      model_id: input.modelId,
+      max_mode: input.maxMode ?? false,
+      parameters: (input.parameterValues ?? []).map((parameter) => ({ ...parameter })),
+    },
+    conversation_state: seeded ? buildSeedConversationState() : input.conversationState,
+    mcp_tools: { mcp_tools: [] },
+    unknown_flag: 0,
+    field_12: 0,
+  };
+  return encodeMessage("AgentClientMessage", { run_request: runRequest });
+}
+
+/** `AgentClientMessage{client_heartbeat}`. */
+export function buildHeartbeat(): Uint8Array {
+  return encodeMessage("AgentClientMessage", { client_heartbeat: {} });
+}
+
+/**
+ * `ACM#5 exec_client_control_message.heartbeat{id}`: Cursor CLI sends one every
+ * few seconds for each exec it is still running. A zero id is left out, as
+ * proto3 does for a default scalar.
+ */
+export function buildExecHeartbeat(execId: number): Uint8Array {
+  return encodeMessage("AgentClientMessage", {
+    exec_client_control_message: { heartbeat: execId === 0 ? {} : { id: execId } },
+  });
+}
+
+/** `ACM#5 exec_client_control_message.stream_close{id}` after an exec result. */
+export function buildExecStreamClose(execId: number): Uint8Array {
+  return encodeMessage("AgentClientMessage", {
+    exec_client_control_message: { stream_close: { id: execId } },
+  });
+}
+
+/** Stops the live Run, as Cursor CLI does before closing the stream. */
+export function buildCancelAction(reason: string): Uint8Array {
+  return encodeMessage("AgentClientMessage", {
+    conversation_action: { cancel_action: { reason } },
+  });
+}
+
+/** `ACM#3 kv_client_message` reply to a server `set_blob`. */
+export function buildKvSetBlobResult(id: number): Uint8Array {
+  return encodeMessage("AgentClientMessage", {
+    kv_client_message: { id, set_blob_result: {} },
+  });
+}
+
+/** `ACM#3 kv_client_message` reply to a server `get_blob`. */
+export function buildKvGetBlobResult(id: number, blobData: Uint8Array): Uint8Array {
+  return encodeMessage("AgentClientMessage", {
+    kv_client_message: { id, get_blob_result: { blob_data: blobData } },
+  });
+}
+
+/** `ACM#2 exec_client_message{request_context_result}` reply to a context probe. */
+export function buildRequestContextResult(
+  execId: number,
+  requestContext: Record<string, unknown>,
+): Uint8Array {
+  return encodeMessage("AgentClientMessage", {
+    exec_client_message: {
+      id: execId,
+      request_context_result: { success: { request_context: requestContext } },
+    },
+  });
+}
+
+/**
+ * `ACM#2 exec_client_message{mcp_state_exec_result}` reply to Cursor's MCP
+ * availability probe.
+ *
+ * Cursor probes the servers behind an advertised tool before it emits a call,
+ * and a Run that never gets an answer stalls on heartbeats. Answering from the
+ * descriptors this Run advertised is what keeps the model's catalog intact.
+ */
+export function buildMcpStateResult(
+  execId: number,
+  descriptors: readonly CursorToolDescriptor[],
+): Uint8Array {
+  return encodeMessage("AgentClientMessage", {
+    exec_client_message: {
+      id: execId,
+      mcp_state_exec_result: {
+        success: {
+          servers: [
+            {
+              server_name: CURSOR_MCP_NAMESPACE,
+              server_identifier: CURSOR_MCP_NAMESPACE,
+              status: "connected",
+              tools: mcpToolDefinitions(descriptors),
+            },
+          ],
+        },
+      },
+    },
+  });
+}
+
+/** One `McpToolResultContentItem` for an image-bearing tool result. */
+function imageContentItem(data: Uint8Array, mimeType: string): Record<string, unknown> {
+  return { image: { data, mime_type: mimeType } };
+}
+
+/**
+ * `ACM#2 exec_client_message{mcp_result}` carrying one external tool result.
+ *
+ * `is_error` is set for a tool the client reported as failed: Cursor relays the
+ * distinction to the model, so a failure is not silently recast as a successful
+ * observation.
+ */
+export function buildMcpResult(input: {
+  readonly execId: number;
+  readonly text: string;
+  readonly isError: boolean;
+  readonly images?: readonly { data: Uint8Array; mimeType: string }[];
+}): Uint8Array {
+  const content: Record<string, unknown>[] = [];
+  if (input.text.length > 0) content.push({ text: { text: input.text } });
+  for (const image of input.images ?? []) {
+    content.push(imageContentItem(image.data, image.mimeType));
+  }
+  if (content.length === 0) content.push({ text: { text: "" } });
+  return encodeMessage("AgentClientMessage", {
+    exec_client_message: {
+      id: input.execId,
+      mcp_result: { success: { content, is_error: input.isError } },
+    },
+  });
+}
+
+/**
+ * `ACM#2 exec_client_message{mcp_result}` rejecting a tool the client never
+ * declared.
+ *
+ * A refusal is not an execution: Cursor asked for a host tool this gateway does
+ * not run, and answering `rejected` (rather than executing it or stalling) is
+ * what lets the model continue without the gateway ever touching a filesystem
+ * or a shell on the caller's behalf.
+ */
+export function buildMcpRejected(execId: number, reason: string): Uint8Array {
+  return encodeMessage("AgentClientMessage", {
+    exec_client_message: {
+      id: execId,
+      mcp_result: { rejected: { reason, is_readonly: true } },
+    },
+  });
+}
+
+/** Text of one canonical message, for the escaped history prefix. */
+export function messageText(message: CanonicalMessage): string {
+  const parts: string[] = [];
+  for (const part of message.content) {
+    if (part.kind === "text") parts.push(part.text);
+    else if (part.kind === "toolCall") parts.push(`[tool call ${part.name} ${stringifyArgs(part.arguments)}]`);
+    else if (part.kind === "toolResult") parts.push(`[tool result ${part.call_id} ${toolResultText(part)}]`);
+    else if (part.kind === "reasoning" && part.summary !== undefined) parts.push(part.summary);
+  }
+  return parts.join("\n");
+}
+
+function stringifyArgs(arguments_: unknown): string {
+  if (typeof arguments_ === "string") return arguments_;
+  try {
+    return JSON.stringify(arguments_ ?? {});
+  } catch {
+    return "{}";
+  }
+}
+
+function toolResultText(part: Extract<ContentPart, { kind: "toolResult" }>): string {
+  if (typeof part.content === "string") return part.content;
+  return part.content
+    .map((child) => (child.kind === "text" ? child.text : `[${child.kind}]`))
+    .join("\n");
+}
+
+/**
+ * The live user text of one canonical request: the last user turn.
+ *
+ * Everything before it is history, and Cursor's own `user_message.text` carries
+ * only the current prompt.
+ */
+export function liveUserText(request: CanonicalRequest): string {
+  for (let index = request.messages.length - 1; index >= 0; index -= 1) {
+    const message = request.messages[index];
+    if (message === undefined) continue;
+    if (message.role !== "user" && message.role !== "tool") continue;
+    const text = messageText(message);
+    if (text.trim().length > 0) return text;
+  }
+  return "";
+}