pi-provider-cursor-ask 0.1.0

package/src/stream/request-build.ts

@@ -0,0 +1,668 @@
+/**
+ * Builds the `AgentRunRequest` protobuf that starts (or resumes) a Cursor turn.
+ *
+ * Two shapes come out of here:
+ *   - a fresh request carrying the full conversation history as turn structures
+ *   - a resume request carrying an upstream checkpoint blob instead
+ *
+ * Large payloads (images, turn-step bytes) are content-addressed into a blob
+ * store and referenced by hash, which is what keeps a long session's request
+ * from re-uploading every attachment on every turn.
+ */
+import { create, fromBinary, fromJson, toBinary, toJson, type JsonValue } from "@bufbuild/protobuf";
+import { ValueSchema } from "@bufbuild/protobuf/wkt";
+import { createHash } from "node:crypto";
+import { pathToFileURL } from "node:url";
+
+import {
+  AgentClientMessageSchema,
+  AgentConversationTurnStructureSchema,
+  AgentRunRequestSchema,
+  AssistantMessageSchema,
+  ConversationActionSchema,
+  ConversationStateStructureSchema,
+  ConversationStepSchema,
+  ConversationTurnStructureSchema,
+  McpArgsSchema,
+  McpImageContentSchema,
+  McpSuccessSchema,
+  McpTextContentSchema,
+  McpToolCallSchema,
+  McpToolErrorSchema,
+  McpToolResultSchema,
+  McpToolResultContentItemSchema,
+  McpToolsSchema,
+  RequestedModelSchema,
+  RequestedModel_ModelParameterbytesSchema,
+  SelectedContextSchema,
+  SelectedImageSchema,
+  ThinkingMessageSchema,
+  ToolCallSchema,
+  UserMessageActionSchema,
+  UserMessageSchema,
+  type McpToolDefinition,
+  type UserMessage,
+} from "../proto/agent_pb.js";
+import { buildSelectedContextBlob, type CursorModelParameter } from "../client/cursor-wire.js";
+import { debugLog, requestDebugByBody } from "./debug-log.js";
+import {
+  buildRootPromptMessages,
+  encodeRootPromptMessage,
+  isPromptHistoryEnabled,
+  systemPromptRootMessage,
+} from "./root-prompt.js";
+export {
+  buildMcpToolDefinitions,
+  isSlimToolsEnabled,
+  slimOpenAIToolsForCursor,
+} from "./tool-schema.js";
+import type {
+  CursorRequestPayload,
+  OpenAIToolDef,
+  ParsedImageContent,
+  ParsedToolResult,
+  ParsedTurn,
+  ParsedTurnStep,
+} from "./types.js";
+
+export const MAX_MCP_TOOL_TEXT_BYTES = 512 * 1024;
+export const MAX_MCP_TOOL_RESULT_BYTES = 16 * 1024 * 1024;
+
+function truncateUtf8(text: string, maxBytes: number, originalBytes: number): string {
+  const suffix = `\n\n[pi-cursor truncated this tool result from ${originalBytes} bytes to protect the agent context. Use a narrower command, path, or line range.]`;
+  const suffixBytes = Buffer.byteLength(suffix, "utf8");
+  const bytes = Buffer.from(text, "utf8");
+  let end = Math.max(0, maxBytes - suffixBytes);
+  while (end > 0 && end < bytes.length && (bytes[end]! & 0xc0) === 0x80) end -= 1;
+  return bytes.subarray(0, end).toString("utf8") + suffix;
+}
+
+/**
+ * Bound a single tool response before it is journaled or encoded for Cursor.
+ * An accidental recursive dump should not poison every later turn in a session.
+ */
+export function normalizeToolResultForTransport(
+  result: Omit<ParsedToolResult, "isError"> & { isError?: boolean },
+): ParsedToolResult {
+  const originalTextBytes = Buffer.byteLength(result.content, "utf8");
+  let content =
+    originalTextBytes > MAX_MCP_TOOL_TEXT_BYTES
+      ? truncateUtf8(result.content, MAX_MCP_TOOL_TEXT_BYTES, originalTextBytes)
+      : result.content;
+
+  const images: ParsedImageContent[] = [];
+  let usedBytes = Buffer.byteLength(content, "utf8");
+  let droppedImages = 0;
+  let droppedImageBytes = 0;
+  for (const image of result.images ?? []) {
+    const imageBytes = image.data.byteLength + Buffer.byteLength(image.mimeType, "utf8");
+    if (usedBytes + imageBytes > MAX_MCP_TOOL_RESULT_BYTES) {
+      droppedImages += 1;
+      droppedImageBytes += image.data.byteLength;
+      continue;
+    }
+    images.push(image);
+    usedBytes += imageBytes;
+  }
+
+  if (droppedImages > 0) {
+    const notice = `\n\n[pi-cursor omitted ${droppedImages} oversized tool image(s), totaling ${droppedImageBytes} bytes, to protect the transport.]`;
+    const combined = content + notice;
+    const combinedBytes = Buffer.byteLength(combined, "utf8");
+    content =
+      combinedBytes > MAX_MCP_TOOL_TEXT_BYTES
+        ? truncateUtf8(combined, MAX_MCP_TOOL_TEXT_BYTES, combinedBytes)
+        : combined;
+  }
+
+  return {
+    content,
+    isError: result.isError === true,
+    ...(images.length > 0 && { images }),
+  };
+}
+
+/**
+ * Turns whose answer depends on nothing but politeness. Pi's agent prompt adds
+ * nothing to "thanks", so it can be dropped along with the tools.
+ */
+const PLEASANTRY_CONVERSATIONAL_TURNS = new Set([
+  "hi",
+  "hello",
+  "hey",
+  "hi there",
+  "hello there",
+  "hey there",
+  "yo",
+  "how are you",
+  "whats up",
+  "good morning",
+  "good afternoon",
+  "good evening",
+  "thanks",
+  "thank you",
+  "thanks a lot",
+  "thank you very much",
+  "thx",
+  "ty",
+  "ok",
+  "okay",
+  "got it",
+  "sounds good",
+  "cool",
+  "great",
+  "nice",
+  "ping",
+]);
+
+/**
+ * Identity and capability questions. Tool-free like a pleasantry, but the system
+ * prompt *is* the answer here — drop it and the model introduces itself as
+ * Cursor. Tools go; the prompt stays.
+ */
+const IDENTITY_CONVERSATIONAL_TURNS = new Set([
+  "what can you do",
+  "what can you do for me",
+  "what can you help me with",
+  "who are you",
+  "tell me about yourself",
+]);
+
+const TRIVIAL_CONVERSATIONAL_TURNS = new Set([
+  ...PLEASANTRY_CONVERSATIONAL_TURNS,
+  ...IDENTITY_CONVERSATIONAL_TURNS,
+]);
+
+function normalizeConversationalTurn(text: string): string {
+  return text
+    .trim()
+    .toLowerCase()
+    .replace(/[’']/g, "")
+    .replace(/[^a-z0-9\s]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/**
+ * Narrow allowlist for turns that cannot reasonably require a tool. Exact
+ * matching is intentional: "hi, inspect src" must retain the full tool set.
+ */
+export function isTrivialConversationalTurn(text: string): boolean {
+  const normalized = normalizeConversationalTurn(text);
+  return normalized.length <= 40 && TRIVIAL_CONVERSATIONAL_TURNS.has(normalized);
+}
+
+/**
+ * Subset of trivial turns the system prompt itself answers. These keep the full
+ * prompt even though they still drop tools.
+ */
+export function isIdentityConversationalTurn(text: string): boolean {
+  const normalized = normalizeConversationalTurn(text);
+  return normalized.length <= 40 && IDENTITY_CONVERSATIONAL_TURNS.has(normalized);
+}
+
+export function summarizeRequestSize(input: {
+  systemPrompt: string;
+  userText: string;
+  tools: OpenAIToolDef[];
+  mcpTools: McpToolDefinition[];
+  requestBytes: Uint8Array;
+  blobStore: Map<string, Uint8Array>;
+  turnCount?: number;
+}): {
+  systemChars: number;
+  userChars: number;
+  toolCount: number;
+  toolJsonChars: number;
+  mcpSchemaBytes: number;
+  requestBytes: number;
+  blobBytes: number;
+  wireBytes: number;
+  turnCount: number;
+  approxInputTokens: number;
+} {
+  let blobBytes = 0;
+  for (const bytes of input.blobStore.values()) blobBytes += bytes.byteLength;
+  let mcpSchemaBytes = 0;
+  for (const tool of input.mcpTools) {
+    mcpSchemaBytes += tool.inputSchema?.byteLength ?? 0;
+    mcpSchemaBytes += (tool.description?.length ?? 0) + (tool.name?.length ?? 0);
+  }
+  // `toolJsonChars` reports the raw Pi surface for comparison only. Do not add
+  // it (or mcpSchemaBytes) to the estimate: the encoded schemas already live in
+  // requestBytes, and the system/conversation content already lives in blobs.
+  const toolJsonChars = JSON.stringify(input.tools).length;
+  const systemChars = input.systemPrompt.length;
+  const userChars = input.userText.length;
+  const wireBytes = input.requestBytes.byteLength + blobBytes;
+  // Rough UTF-8/Latin heuristic used only for diagnostics, not billing.
+  const approxInputTokens = Math.round(wireBytes / 4);
+  return {
+    systemChars,
+    userChars,
+    toolCount: input.tools.length,
+    toolJsonChars,
+    mcpSchemaBytes,
+    requestBytes: input.requestBytes.byteLength,
+    blobBytes,
+    wireBytes,
+    turnCount: input.turnCount ?? 0,
+    approxInputTokens,
+  };
+}
+
+export function decodeMcpArgValue(value: Uint8Array): unknown {
+  try {
+    const parsed = fromBinary(ValueSchema, value);
+    return toJson(ValueSchema, parsed);
+  } catch {
+    // Not a protobuf Value; treat bytes as UTF-8 text for MCP tool args.
+    return new TextDecoder().decode(value);
+  }
+}
+
+export function decodeMcpArgsMap(args: Record<string, Uint8Array>): Record<string, unknown> {
+  const decoded: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(args)) decoded[key] = decodeMcpArgValue(value);
+  return decoded;
+}
+
+export function encodeMcpArgValue(value: unknown): Uint8Array {
+  try {
+    return toBinary(ValueSchema, fromJson(ValueSchema, value as JsonValue));
+  } catch {
+    return new TextEncoder().encode(String(value));
+  }
+}
+
+export function encodeMcpArgsMap(args: Record<string, unknown>): Record<string, Uint8Array> {
+  const encoded: Record<string, Uint8Array> = {};
+  for (const [key, value] of Object.entries(args)) encoded[key] = encodeMcpArgValue(value);
+  return encoded;
+}
+
+export function storeAsBlob(data: Uint8Array, blobStore: Map<string, Uint8Array>): Uint8Array {
+  const id = new Uint8Array(createHash("sha256").update(data).digest());
+  blobStore.set(Buffer.from(id).toString("hex"), data);
+  return id;
+}
+
+export function createSelectedImages(images: ParsedImageContent[]) {
+  // Matches Cursor CLI's ACP image path for inline image data:
+  // new SelectedImage({ dataOrBlobId: { case: "data", value }, uuid, mimeType })
+  return images.map((image) =>
+    create(SelectedImageSchema, {
+      uuid: crypto.randomUUID(),
+      mimeType: image.mimeType,
+      dataOrBlobId: { case: "data", value: image.data },
+    }),
+  );
+}
+
+export function createUserMessage(
+  text: string,
+  selectedContextBlob: Uint8Array,
+  images: ParsedImageContent[] = [],
+): UserMessage {
+  const messageId = crypto.randomUUID();
+  return create(UserMessageSchema, {
+    text,
+    messageId,
+    selectedContext: create(SelectedContextSchema, {
+      selectedImages: createSelectedImages(images),
+    }),
+    mode: 1,
+    selectedContextBlob,
+    correlationId: messageId,
+  });
+}
+
+export function buildMcpSuccessContent(result: ParsedToolResult) {
+  result = normalizeToolResultForTransport(result);
+  const content = [];
+  if (result.content.length > 0) {
+    content.push(
+      create(McpToolResultContentItemSchema, {
+        content: {
+          case: "text",
+          value: create(McpTextContentSchema, { text: result.content }),
+        },
+      }),
+    );
+  }
+  for (const image of result.images ?? []) {
+    content.push(
+      create(McpToolResultContentItemSchema, {
+        content: {
+          case: "image",
+          value: create(McpImageContentSchema, { data: image.data, mimeType: image.mimeType }),
+        },
+      }),
+    );
+  }
+  if (content.length === 0) {
+    content.push(
+      create(McpToolResultContentItemSchema, {
+        content: { case: "text", value: create(McpTextContentSchema, { text: "" }) },
+      }),
+    );
+  }
+  return content;
+}
+
+export function buildTurnStepBytes(step: ParsedTurnStep): Uint8Array {
+  if (step.kind === "assistantText") {
+    return toBinary(
+      ConversationStepSchema,
+      create(ConversationStepSchema, {
+        message: {
+          case: "assistantMessage",
+          value: create(AssistantMessageSchema, { text: step.text }),
+        },
+      }),
+    );
+  }
+
+  if (step.kind === "thinking") {
+    return toBinary(
+      ConversationStepSchema,
+      create(ConversationStepSchema, {
+        message: {
+          case: "thinkingMessage",
+          value: create(ThinkingMessageSchema, { text: step.text }),
+        },
+      }),
+    );
+  }
+
+  const toolName = step.toolName || "tool";
+  const mcpToolCall = create(McpToolCallSchema, {
+    args: create(McpArgsSchema, {
+      name: toolName,
+      args: encodeMcpArgsMap(step.arguments),
+      toolCallId: step.toolCallId,
+      providerIdentifier: "pi",
+      toolName,
+    }),
+    ...(step.result && {
+      result: create(McpToolResultSchema, {
+        result: step.result.isError
+          ? {
+              case: "error",
+              value: create(McpToolErrorSchema, { error: step.result.content }),
+            }
+          : {
+              case: "success",
+              value: create(McpSuccessSchema, {
+                content: buildMcpSuccessContent(step.result),
+                isError: false,
+              }),
+            },
+      }),
+    }),
+  });
+
+  return toBinary(
+    ConversationStepSchema,
+    create(ConversationStepSchema, {
+      message: {
+        case: "toolCall",
+        value: create(ToolCallSchema, {
+          tool: {
+            case: "mcpToolCall",
+            value: mcpToolCall,
+          },
+        }),
+      },
+    }),
+  );
+}
+
+export type BuildCursorRequestImageInput =
+  | ParsedImageContent
+  | {
+      data: string;
+      mimeType: string;
+    };
+
+export interface BuildCursorRequestTurnInput extends Omit<ParsedTurn, "userImages"> {
+  images?: BuildCursorRequestImageInput[];
+  userImages?: BuildCursorRequestImageInput[];
+}
+
+export interface BuildCursorRequestOptions {
+  checkpoint: Uint8Array | null;
+  conversationId: string;
+  cursorModelParameters?: CursorModelParameter[];
+  existingBlobStore?: Map<string, Uint8Array>;
+  mcpTools?: McpToolDefinition[];
+  modelId: string;
+  systemPrompt: string;
+  turns?: BuildCursorRequestTurnInput[];
+  userImages?: BuildCursorRequestImageInput[];
+  userText?: string;
+  maxMode?: boolean;
+  /** Re-publish the system prompt onto a checkpoint whose recorded prompt is stale. */
+  refreshSystemPrompt?: boolean;
+}
+
+export function normalizeImageInput(image: BuildCursorRequestImageInput): ParsedImageContent {
+  if (image.data instanceof Uint8Array) {
+    return {
+      data: image.data,
+      mimeType: image.mimeType,
+    };
+  }
+  return {
+    data: new Uint8Array(Buffer.from(image.data.replace(/\s/g, ""), "base64")),
+    mimeType: image.mimeType,
+  };
+}
+
+export function normalizeTurnInput(turn: BuildCursorRequestTurnInput): ParsedTurn {
+  const images = turn.userImages ?? turn.images;
+  return {
+    userText: turn.userText,
+    steps: turn.steps,
+    ...(images && images.length > 0 ? { userImages: images.map(normalizeImageInput) } : {}),
+  };
+}
+
+export function buildCursorRequest(
+  modelOrOptions: string | BuildCursorRequestOptions,
+  systemPrompt?: string,
+  userText?: string,
+  turns?: ParsedTurn[],
+  conversationId?: string,
+  checkpoint?: Uint8Array | null,
+  existingBlobStore?: Map<string, Uint8Array>,
+  maxMode = false,
+  cursorModelParameters: CursorModelParameter[] = [],
+  mcpTools: McpToolDefinition[] = [],
+  userImages: ParsedImageContent[] = [],
+  refreshSystemPrompt = false,
+): CursorRequestPayload {
+  if (typeof modelOrOptions !== "string") {
+    const normalizedTurns = (modelOrOptions.turns ?? []).map(normalizeTurnInput);
+    const currentTurn =
+      modelOrOptions.userText === undefined && normalizedTurns.length > 0
+        ? normalizedTurns[normalizedTurns.length - 1]
+        : undefined;
+    const completedTurns = currentTurn ? normalizedTurns.slice(0, -1) : normalizedTurns;
+    const currentImages = modelOrOptions.userImages
+      ? modelOrOptions.userImages.map(normalizeImageInput)
+      : (currentTurn?.userImages ?? []);
+
+    return buildCursorRequestFromParts(
+      modelOrOptions.modelId,
+      modelOrOptions.systemPrompt,
+      modelOrOptions.userText ?? currentTurn?.userText ?? "",
+      completedTurns,
+      modelOrOptions.conversationId,
+      modelOrOptions.checkpoint,
+      modelOrOptions.existingBlobStore,
+      modelOrOptions.maxMode ?? false,
+      modelOrOptions.cursorModelParameters ?? [],
+      modelOrOptions.mcpTools ?? [],
+      currentImages,
+      modelOrOptions.refreshSystemPrompt ?? false,
+    );
+  }
+
+  return buildCursorRequestFromParts(
+    modelOrOptions,
+    systemPrompt ?? "",
+    userText ?? "",
+    turns ?? [],
+    conversationId ?? crypto.randomUUID(),
+    checkpoint ?? null,
+    existingBlobStore,
+    maxMode,
+    cursorModelParameters,
+    mcpTools,
+    userImages,
+    refreshSystemPrompt,
+  );
+}
+
+export function buildCursorRequestFromParts(
+  modelId: string,
+  systemPrompt: string,
+  userText: string,
+  turns: ParsedTurn[],
+  conversationId: string,
+  checkpoint: Uint8Array | null,
+  existingBlobStore?: Map<string, Uint8Array>,
+  maxMode = false,
+  cursorModelParameters: CursorModelParameter[] = [],
+  mcpTools: McpToolDefinition[] = [],
+  userImages: ParsedImageContent[] = [],
+  refreshSystemPrompt = false,
+): CursorRequestPayload {
+  debugLog("cursor_request.build.start", {
+    modelId,
+    systemPrompt,
+    userText,
+    turns,
+    conversationId,
+    checkpoint,
+    existingBlobStore,
+    maxMode,
+    cursorModelParameters,
+    mcpToolCount: mcpTools.length,
+    userImageCount: userImages.length,
+  });
+  const blobStore = new Map<string, Uint8Array>(existingBlobStore ?? []);
+
+  const systemBytes = new TextEncoder().encode(
+    JSON.stringify({ role: "system", content: systemPrompt }),
+  );
+  const systemBlobId = storeAsBlob(systemBytes, blobStore);
+  const selectedCtxBlob = storeAsBlob(buildSelectedContextBlob([systemBlobId], "pi"), blobStore);
+
+  let conversationState;
+  if (checkpoint) {
+    conversationState = fromBinary(ConversationStateStructureSchema, checkpoint);
+    // A checkpoint froze the instructions recorded when the conversation began.
+    // Pi rewrites its system prompt as a session evolves — context-mode folds
+    // session memory into it — so a changed prompt is re-published here instead
+    // of being silently pinned to whatever turn one happened to say.
+    if (refreshSystemPrompt && isPromptHistoryEnabled() && systemPrompt.trim()) {
+      conversationState.rootPromptMessagesJson = [
+        ...conversationState.rootPromptMessagesJson,
+        storeAsBlob(encodeRootPromptMessage(systemPromptRootMessage(systemPrompt)), blobStore),
+      ];
+    }
+  } else {
+    const turnBlobIds: Uint8Array[] = [];
+    for (const turn of turns) {
+      const userMsg = createUserMessage(turn.userText, selectedCtxBlob, turn.userImages ?? []);
+      const userMsgBlobId = storeAsBlob(toBinary(UserMessageSchema, userMsg), blobStore);
+      const stepBlobIds = turn.steps.map((s) => storeAsBlob(buildTurnStepBytes(s), blobStore));
+
+      const agentTurn = create(AgentConversationTurnStructureSchema, {
+        userMessage: userMsgBlobId,
+        steps: stepBlobIds,
+        requestId: crypto.randomUUID(),
+      });
+      const turnStructure = create(ConversationTurnStructureSchema, {
+        turn: { case: "agentConversationTurn", value: agentTurn },
+      });
+      turnBlobIds.push(
+        storeAsBlob(toBinary(ConversationTurnStructureSchema, turnStructure), blobStore),
+      );
+    }
+
+    // `turns` is state, not prompt: Cursor's server never renders it back into
+    // model messages. The prompt it actually reads is this list, so the system
+    // prompt and every completed turn are replayed here — see ./root-prompt.ts.
+    const promptBlobIds = isPromptHistoryEnabled()
+      ? buildRootPromptMessages(systemPrompt, turns).map((message) =>
+          storeAsBlob(encodeRootPromptMessage(message), blobStore),
+        )
+      : [];
+
+    conversationState = create(ConversationStateStructureSchema, {
+      rootPromptMessagesJson: [systemBlobId, ...promptBlobIds],
+      turns: turnBlobIds,
+      todos: [],
+      pendingToolCalls: [],
+      previousWorkspaceUris: [pathToFileURL(process.cwd()).href],
+      mode: 1,
+      fileStates: {},
+      fileStatesV2: {},
+      summaryArchives: [],
+      turnTimings: [],
+      subagentStates: {},
+      selfSummaryCount: 0,
+      readPaths: [],
+      clientName: "pi",
+    });
+  }
+
+  const userMessage = createUserMessage(userText, selectedCtxBlob, userImages);
+  const action = create(ConversationActionSchema, {
+    action: { case: "userMessageAction", value: create(UserMessageActionSchema, { userMessage }) },
+  });
+  // Cursor's newer request path uses requestedModel instead of legacy modelDetails.
+  // Some Cursor models (for example GPT-5.5) use requestedModel.parameters
+  // for context/reasoning/fast instead of encoding everything in the model ID.
+  // Max Mode is routed from model metadata for parameterized variants.
+  debugLog("cursor_request.requested_model", {
+    modelId,
+    maxMode,
+    parameters: cursorModelParameters,
+  });
+  const parameters = cursorModelParameters.map((parameter) =>
+    create(RequestedModel_ModelParameterbytesSchema, parameter),
+  );
+  const requestedModel = create(RequestedModelSchema, { modelId, maxMode, parameters });
+  const runRequest = create(AgentRunRequestSchema, {
+    conversationState,
+    action,
+    requestedModel,
+    conversationId,
+    mcpTools: create(McpToolsSchema, { mcpTools }),
+  });
+  const clientMessage = create(AgentClientMessageSchema, {
+    message: { case: "runRequest", value: runRequest },
+  });
+
+  const requestBytes = toBinary(AgentClientMessageSchema, clientMessage);
+  const payload = {
+    contextCheckpoint: checkpoint ?? null,
+    requestBytes,
+    requestBody: requestBytes,
+    blobStore,
+    mcpTools,
+  };
+  requestDebugByBody.set(requestBytes, {
+    systemPrompt,
+    selectedImages: userImages.map((image) => ({
+      byteLength: image.data.byteLength,
+      mimeType: image.mimeType,
+    })),
+  });
+  debugLog("cursor_request.build.end", payload);
+  return payload;
+}