pi-provider-cursor-ask 0.1.0

package/src/stream/bridge-session.ts

@@ -0,0 +1,215 @@
+/**
+ * The active-bridge registry and the in-process HTTP/2 transport lifecycle that fills it.
+ *
+ * These two belong together: a transport parked mid-tool is only reachable through
+ * the registry, and every registry eviction path has to tear the transport down
+ * (cancel action + heartbeat timer) rather than just dropping the reference.
+ *
+ * Conversation/checkpoint state lives one layer up in ./session-state.ts, which
+ * imports this module — never the other way around.
+ */
+import { create, toBinary } from "@bufbuild/protobuf";
+
+import {
+  AgentClientMessageSchema,
+  ClientHeartbeatSchema,
+  CancelActionSchema,
+  ConversationActionSchema,
+} from "../proto/agent_pb.js";
+import {
+  createBridge,
+  frameConnectMessage,
+  type BridgeFactory,
+  type BridgeHandle,
+} from "../client/bridge.js";
+import { getCursorAgentUrl } from "./config.js";
+import { debugLog } from "./debug-log.js";
+import {
+  ACTIVE_BRIDGE_TTL_MS,
+  resolveH2ConnectTimeoutMs,
+  resolveH2IdleTimeoutMs,
+} from "./tuning.js";
+import type { ActiveBridge } from "./types.js";
+
+/** Test seam for the streaming HTTP/2 transport factory. */
+export function getBridgeFactory(): BridgeFactory {
+  return bridgeFactory;
+}
+
+export const activeBridges = new Map<string, ActiveBridge>();
+
+const defaultBridgeFactory: BridgeFactory = (options) => createBridge(options, debugLog);
+
+let bridgeFactory: BridgeFactory = defaultBridgeFactory;
+
+export function setBridgeFactoryForTests(factory?: BridgeFactory): void {
+  bridgeFactory = factory ?? defaultBridgeFactory;
+}
+
+export function clearActiveBridgeToolTimeout(active: ActiveBridge | undefined): void {
+  if (active?.toolTimeoutTimer) clearTimeout(active.toolTimeoutTimer);
+}
+
+export function removeActiveBridge(bridgeKey: string): void {
+  clearActiveBridgeToolTimeout(activeBridges.get(bridgeKey));
+  activeBridges.delete(bridgeKey);
+}
+
+export const idleBridges = new Map<
+  string,
+  { bridge: BridgeHandle; idleTimer: ReturnType<typeof setTimeout> }
+>();
+
+function canReuseBridge(bridge: BridgeHandle): boolean {
+  return bridge.alive && bridge.reusable;
+}
+
+export function destroyIdleBridge(bridgeKey: string): void {
+  const idle = idleBridges.get(bridgeKey);
+  if (!idle) return;
+  idleBridges.delete(bridgeKey);
+  clearTimeout(idle.idleTimer);
+  if (idle.bridge.alive) idle.bridge.end();
+}
+
+export function destroyAllIdleBridges(): void {
+  for (const key of [...idleBridges.keys()]) destroyIdleBridge(key);
+}
+
+/** Keep a live HTTP/2 session around so the next user turn can skip reconnect + TLS. */
+export function parkIdleBridge(bridgeKey: string, bridge: BridgeHandle): void {
+  // Drop the active-registry entry without closing the session — the leftover-turn
+  // path in native-core ends any transport still listed as active.
+  removeActiveBridge(bridgeKey);
+  destroyIdleBridge(bridgeKey);
+  if (!canReuseBridge(bridge)) {
+    if (bridge.alive) bridge.end();
+    return;
+  }
+  debugLog("bridge.park_idle", { bridgeKey });
+  const idleTimer = setTimeout(() => {
+    debugLog("bridge.idle_expired", { bridgeKey, ttlMs: ACTIVE_BRIDGE_TTL_MS });
+    destroyIdleBridge(bridgeKey);
+  }, ACTIVE_BRIDGE_TTL_MS);
+  idleTimer.unref?.();
+  idleBridges.set(bridgeKey, { bridge, idleTimer });
+}
+
+function takeIdleBridge(bridgeKey: string): BridgeHandle | undefined {
+  const idle = idleBridges.get(bridgeKey);
+  if (!idle) return undefined;
+  idleBridges.delete(bridgeKey);
+  clearTimeout(idle.idleTimer);
+  if (!canReuseBridge(idle.bridge)) {
+    if (idle.bridge.alive) idle.bridge.end();
+    return undefined;
+  }
+  return idle.bridge;
+}
+
+function armActiveBridgeTtl(
+  bridgeKey: string,
+  active: Omit<ActiveBridge, "toolTimeoutTimer">,
+): ReturnType<typeof setTimeout> {
+  const toolTimeoutTimer = setTimeout(() => {
+    debugLog("bridge.active_ttl_expired", { bridgeKey, ttlMs: ACTIVE_BRIDGE_TTL_MS });
+    cleanupBridge(active.bridge, active.heartbeatTimer, bridgeKey);
+  }, ACTIVE_BRIDGE_TTL_MS);
+  toolTimeoutTimer.unref?.();
+  return toolTimeoutTimer;
+}
+
+export function setActiveBridge(
+  bridgeKey: string,
+  active: Omit<ActiveBridge, "toolTimeoutTimer">,
+): void {
+  clearActiveBridgeToolTimeout(activeBridges.get(bridgeKey));
+  const toolTimeoutTimer = armActiveBridgeTtl(bridgeKey, active);
+  activeBridges.set(bridgeKey, { ...active, toolTimeoutTimer });
+}
+
+/** Slide the parked-bridge TTL forward while the bridge is still useful. */
+export function touchActiveBridge(bridgeKey: string): void {
+  const active = activeBridges.get(bridgeKey);
+  if (!active) return;
+  clearActiveBridgeToolTimeout(active);
+  active.toolTimeoutTimer = armActiveBridgeTtl(bridgeKey, active);
+}
+
+export function makeHeartbeatBytes(): Uint8Array {
+  const heartbeat = create(AgentClientMessageSchema, {
+    message: { case: "clientHeartbeat", value: create(ClientHeartbeatSchema, {}) },
+  });
+  return frameConnectMessage(toBinary(AgentClientMessageSchema, heartbeat));
+}
+
+// Cursor's MCP family carries Pi tool calls; native filesystem/shell/subagent tools stay hidden.
+const PI_MCP_TOOL_TYPES = [
+  "mcp_tool_call",
+  "get_mcp_tools_tool_call",
+  "list_mcp_resources_tool_call",
+  "read_mcp_resource_tool_call",
+  "mcp_auth_tool_call",
+] as const;
+
+export function startBridge(
+  accessToken: string,
+  requestBytes: Uint8Array,
+  options: { bridgeKey?: string; hasMcpTools: boolean },
+) {
+  const allowedTools = options.hasMcpTools ? PI_MCP_TOOL_TYPES : [];
+  const reused = options.bridgeKey ? takeIdleBridge(options.bridgeKey) : undefined;
+  let bridge;
+  if (reused) {
+    debugLog("bridge.reuse_idle", { bridgeKey: options?.bridgeKey });
+    reused.openStream!(accessToken, allowedTools);
+    reused.write(frameConnectMessage(requestBytes));
+    bridge = reused;
+  } else {
+    bridge = bridgeFactory({
+      accessToken,
+      rpcPath: "/agent.v1.AgentService/Run",
+      allowedTools,
+      url: getCursorAgentUrl(),
+      connectTimeoutMs: resolveH2ConnectTimeoutMs(process.env.PI_CURSOR_H2_CONNECT_TIMEOUT_MS),
+      idleTimeoutMs: resolveH2IdleTimeoutMs(process.env.PI_CURSOR_H2_IDLE_TIMEOUT_MS),
+    });
+    debugLog("bridge.start_run", { requestBytes });
+    bridge.write(frameConnectMessage(requestBytes));
+  }
+  // Keep heartbeats referenced so long tool pauses do not look idle to the transport.
+  // 15s interval: frequent enough to prevent mid-pause idle kills, low enough to
+  // avoid flooding a quiet stream with IPC chatter. Also slides the parked-bridge
+  // TTL so multi-round tool chains are not killed by the original park timestamp.
+  const heartbeatTimer = setInterval(() => {
+    bridge.write(makeHeartbeatBytes());
+    if (options?.bridgeKey) touchActiveBridge(options.bridgeKey);
+  }, 15_000);
+  return { bridge, heartbeatTimer };
+}
+
+export function sendCancelAction(bridge: BridgeHandle): void {
+  debugLog("bridge.cancel_action", {});
+  const action = create(ConversationActionSchema, {
+    action: { case: "cancelAction", value: create(CancelActionSchema, {}) },
+  });
+  const clientMessage = create(AgentClientMessageSchema, {
+    message: { case: "conversationAction", value: action },
+  });
+  bridge.write(frameConnectMessage(toBinary(AgentClientMessageSchema, clientMessage)));
+}
+
+export function cleanupBridge(
+  bridge: BridgeHandle,
+  heartbeatTimer: ReturnType<typeof setInterval>,
+  bridgeKey: string,
+): void {
+  debugLog("bridge.cleanup", { bridgeKey, alive: bridge.alive });
+  clearInterval(heartbeatTimer);
+  clearActiveBridgeToolTimeout(activeBridges.get(bridgeKey));
+  if (bridge.alive) {
+    sendCancelAction(bridge);
+    bridge.end();
+  }
+  activeBridges.delete(bridgeKey);
+}

package/src/stream/client-transcript.ts

@@ -0,0 +1,51 @@
+/**
+ * Pi's view of the turn in flight, as opposed to the wire history sent upstream.
+ *
+ * `live` means the wire current turn is Pi's own turn. `recovered` means recovery
+ * replaced the wire turn with a synthetic one, so Pi's turn is `inFlightTurn`
+ * extended by whatever the synthetic turn produces. Matching recovery against the
+ * bridge suffix after any earlier recovery is unrecoverable — the wire turn is
+ * only a suffix of Pi's turn, so exact tool-id matching could never succeed again.
+ */
+import type { ClientTranscript, ParsedTurn } from "./types.js";
+
+export type { ClientTranscript } from "./types.js";
+
+export function liveTranscript(completedTurns: ParsedTurn[]): ClientTranscript {
+  return { kind: "live", completedTurns };
+}
+
+export function recoveredTranscript(
+  completedTurns: ParsedTurn[],
+  inFlightTurn: ParsedTurn,
+): ClientTranscript {
+  return { kind: "recovered", completedTurns, inFlightTurn };
+}
+
+/**
+ * The turn Pi will report as completed once this stream finishes.
+ * After recovery the wire current turn is synthetic; Pi's in-flight turn is the
+ * recorded one extended by whatever steps the synthetic turn produced.
+ */
+export function clientInFlightTurn(
+  transcript: ClientTranscript,
+  wireCurrentTurn: ParsedTurn,
+): ParsedTurn {
+  if (transcript.kind === "live") return wireCurrentTurn;
+  const userImages = transcript.inFlightTurn.userImages ?? wireCurrentTurn.userImages;
+  const recovered: ParsedTurn = {
+    userText: transcript.inFlightTurn.userText,
+    steps: [...transcript.inFlightTurn.steps, ...wireCurrentTurn.steps],
+  };
+  if (userImages?.length) recovered.userImages = userImages;
+  return recovered;
+}
+
+/** Mark that recovery replaced the wire current turn with a synthetic one. */
+export function withSyntheticCurrentTurn(
+  transcript: ClientTranscript,
+  preRecoveryCurrentTurn: ParsedTurn,
+): ClientTranscript {
+  if (transcript.kind === "recovered") return transcript;
+  return recoveredTranscript(transcript.completedTurns, preRecoveryCurrentTurn);
+}

package/src/stream/config.ts

@@ -0,0 +1,5 @@
+/**
+ * Cursor agent URL and version configuration.
+ * Re-exports from src/config/index.js for stream-layer backward compatibility.
+ */
+export * from "../config/index.js";

package/src/stream/context-normalize.ts

@@ -0,0 +1,308 @@
+/**
+ * Normalize context-mode / session side-channel user messages into the system
+ * prompt so Cursor treats the real user turn as the task.
+ *
+ * Important: context-mode often appends injection text to the *same* user
+ * message as the real prompt ("hi\n\ncontext-mode active..."). Treating the
+ * whole message as side-channel swallows the real request. Mixed messages are
+ * split so only the infrastructure blocks move to the system prompt.
+ */
+
+export type OpenAIRole = "system" | "user" | "assistant" | "tool";
+
+export interface OpenAIContentPart {
+  type: string;
+  text?: string;
+  data?: string;
+  mimeType?: string;
+  image_url?: { url?: string };
+}
+
+export interface OpenAIMessage {
+  role: OpenAIRole;
+  content?: string | OpenAIContentPart[] | null;
+  tool_call_id?: string;
+  name?: string;
+  tool_calls?: unknown[];
+  /** Carried through untouched; see OpenAIMessage in ./types.ts. */
+  interrupted_notice?: string;
+  /** Replayed thinking from a prior assistant turn. */
+  thinking?: string;
+}
+
+const CONTEXT_MODE_SIDE_CHANNEL_PRIORITY =
+  "Provider infrastructure context only. The latest user message is the only task. " +
+  "Do not continue prior work, re-read files, or run compaction/session recovery " +
+  "unless the latest user message explicitly asks for that.";
+
+const RESUME_CONTEXT_PRIORITY =
+  "This block is the recovered conversation context from a resumed or compacted session. " +
+  "Treat it as active memory of prior work and continue from it. " +
+  "The latest user message is the current instruction, not a new unrelated task.";
+
+/** Markers that begin a side-channel block inside an otherwise normal user turn. */
+const SIDE_CHANNEL_BLOCK_START =
+  /(?:^|\n)[ \t]*(?:context-mode active\b|\[context\]|\[pi-lens automated\b|<session_state\b|<session_resume\b|<active_memory\b|<compaction\b|<session_mode\b|Hierarchy:\s*ctx_batch_execute)/i;
+
+export function textContent(content: OpenAIMessage["content"]): string {
+  if (content == null) return "";
+  if (typeof content === "string") return content;
+  return content
+    .filter((p) => p.type === "text" && p.text)
+    .map((p) => p.text as string)
+    .join("\n");
+}
+
+export function contentHasImageParts(content: OpenAIMessage["content"]): boolean {
+  if (!Array.isArray(content)) return false;
+  return content.some(
+    (part) =>
+      part.type === "image_url" ||
+      part.type === "image" ||
+      (typeof part.mimeType === "string" && part.mimeType.startsWith("image/")),
+  );
+}
+
+export function isContextModeSideChannelText(text: string): boolean {
+  const t = text.trim();
+  if (!t) return false;
+  return (
+    /^context-mode active\b/i.test(t) ||
+    /^\[context\]/i.test(t) ||
+    /(?:^|\n)[ \t]*\[pi-lens automated\b/i.test(t) ||
+    t.includes("<session_state") ||
+    t.includes("<session_resume") ||
+    t.includes("<active_memory>") ||
+    t.includes("<compaction") ||
+    t.includes("context_mode") ||
+    t.includes("Hierarchy: ctx_batch_execute") ||
+    /<\/?session_mode\b/i.test(t)
+  );
+}
+
+/**
+ * True when the entire message is infrastructure-only (no residual user task).
+ * Mixed messages that *contain* side-channel markers still return false here if
+ * there is leading/trailing user text after splitting.
+ */
+export function isPureContextModeSideChannelText(text: string): boolean {
+  if (!isContextModeSideChannelText(text)) return false;
+  const { userText, sideText } = splitUserTextAndSideChannel(text);
+  return !userText.trim() && !!sideText.trim();
+}
+
+/**
+ * True when a side-channel carries no useful session memory — only the standard
+ * context-mode hierarchy blurb and/or an empty/mode-only session_state.
+ * These add tokens without helping the model and should be dropped.
+ */
+export function isNoOpSideChannelText(text: string): boolean {
+  const t = text.trim();
+  if (!t) return true;
+  if (!isContextModeSideChannelText(t)) return false;
+
+  let rest = t;
+  // Strip standard hierarchy boilerplate lines.
+  rest = rest
+    .replace(/^context-mode active\b[^\n]*$/gim, "")
+    .replace(/^Read\/edit files[^\n]*$/gim, "")
+    .replace(/^Multi-command research[^\n]*$/gim, "")
+    .replace(/^Hierarchy:\s*ctx_batch_execute[^\n]*$/gim, "")
+    .replace(/\n{2,}/g, "\n")
+    .trim();
+
+  // Strip session_state blocks that only carry mode / empty shells.
+  rest = rest
+    .replace(/<session_state\b[^>]*>[\s\S]*?<\/session_state>/gi, (block) => {
+      if (sideChannelHasResumeMemory(block)) return block;
+      const inner = block
+        .replace(/<\/?session_state\b[^>]*>/gi, "")
+        .replace(/<session_mode\b[^>]*>[\s\S]*?<\/session_mode>/gi, "")
+        .replace(/<\/?(summary|turns|messages|memory)\b[^>]*>/gi, "")
+        .trim();
+      // Keep the block if it still has meaningful payload text.
+      return inner.length >= 40 ? block : "";
+    })
+    .replace(/\n{2,}/g, "\n")
+    .trim();
+
+  return rest.length < 24;
+}
+
+/**
+ * Split a user message that may concatenate real task text with context-mode /
+ * session_state injections.
+ */
+export function splitUserTextAndSideChannel(text: string): {
+  userText: string;
+  sideText: string;
+} {
+  const raw = text ?? "";
+  if (!raw.trim()) return { userText: "", sideText: "" };
+
+  if (!isContextModeSideChannelText(raw)) {
+    return { userText: raw, sideText: "" };
+  }
+
+  const match = SIDE_CHANNEL_BLOCK_START.exec(raw);
+  if (!match || match.index === undefined) {
+    // Marker mentioned mid-prose (e.g. "what is a <session_state> block?") — keep
+    // the whole string as the user task rather than swallowing it.
+    return { userText: raw, sideText: "" };
+  }
+
+  const start = match.index + (match[0].startsWith("\n") ? 1 : 0);
+  let userText = raw.slice(0, start).trim();
+  let sideText = raw.slice(start).trim();
+
+  // Side channel first, user task after the closing session_state block.
+  if (!userText && sideText) {
+    const closeIdx = sideText.toLowerCase().lastIndexOf("</session_state>");
+    if (closeIdx >= 0) {
+      const after = sideText.slice(closeIdx + "</session_state>".length).trim();
+      if (after && !isContextModeSideChannelText(after)) {
+        userText = after;
+        sideText = sideText.slice(0, closeIdx + "</session_state>".length).trim();
+      }
+    }
+  }
+
+  // If the "user" residue is still only infrastructure, drop it.
+  if (userText && isPureSideResidue(userText)) {
+    sideText = [sideText, userText].filter(Boolean).join("\n\n");
+    userText = "";
+  }
+
+  // No recoverable user task and the message looks like a full injection dump.
+  if (!userText && sideText) {
+    return { userText: "", sideText };
+  }
+
+  return { userText, sideText };
+}
+
+function isPureSideResidue(text: string): boolean {
+  const t = text.trim();
+  if (!t) return true;
+  if (isContextModeSideChannelText(t) && t.length > 80) return true;
+  // Single-line tool hierarchy leftovers.
+  if (/^Hierarchy:\s*ctx_/i.test(t)) return true;
+  if (/^Read\/edit files/i.test(t)) return true;
+  return false;
+}
+
+/**
+ * True when a side-channel carries a compaction summary or session-resume memory
+ * that the model must treat as prior work, not as disposable infrastructure.
+ */
+export function isResumeOrCompactionSideChannel(text: string): boolean {
+  if (/<session_resume\b/i.test(text)) return true;
+  const summary = text.match(/<summary\b[^>]*>([\s\S]*?)<\/summary>/i)?.[1]?.trim() ?? "";
+  if (summary.length >= 8) return true;
+  const memory =
+    text.match(/<active_memory\b[^>]*>([\s\S]*?)<\/active_memory>/i)?.[1]?.trim() ?? "";
+  return memory.length >= 8;
+}
+
+function sideChannelHasResumeMemory(text: string): boolean {
+  return isResumeOrCompactionSideChannel(text);
+}
+
+/** True when the system prompt holds folded session/compaction memory that a greeting must not drop. */
+export function systemPromptHasSessionMemory(systemPrompt: string): boolean {
+  const t = systemPrompt ?? "";
+  if (!t) return false;
+  return (
+    /<provider_context\b/i.test(t) ||
+    /<session_state\b/i.test(t) ||
+    /<session_resume\b/i.test(t) ||
+    /<active_memory\b/i.test(t)
+  );
+}
+
+export function frameContextModeSideChannel(text: string): string {
+  const priority = isResumeOrCompactionSideChannel(text)
+    ? RESUME_CONTEXT_PRIORITY
+    : CONTEXT_MODE_SIDE_CHANNEL_PRIORITY;
+  return (
+    `<provider_context source="context-mode">\n${text.trim()}\n</provider_context>\n\n` + priority
+  );
+}
+
+function rebuildUserContent(
+  original: OpenAIMessage["content"],
+  userText: string,
+): OpenAIMessage["content"] {
+  if (!Array.isArray(original)) return userText;
+
+  const imageParts = original.filter(
+    (part) =>
+      part.type === "image_url" ||
+      part.type === "image" ||
+      (typeof part.mimeType === "string" && part.mimeType.startsWith("image/")),
+  );
+  if (imageParts.length === 0) return userText;
+  return [{ type: "text", text: userText }, ...imageParts];
+}
+
+/**
+ * Fold pure side-channel user messages into the system prompt and keep the
+ * real user turns as the task. Mixed user messages are split in place.
+ */
+export function normalizeMessagesForCursor(messages: OpenAIMessage[]): OpenAIMessage[] {
+  const systemParts: string[] = [];
+  const sideParts: string[] = [];
+  const rest: OpenAIMessage[] = [];
+
+  for (const msg of messages) {
+    if (msg.role === "system") {
+      const text = textContent(msg.content);
+      if (text) systemParts.push(text);
+      continue;
+    }
+
+    if (msg.role === "user") {
+      const text = textContent(msg.content);
+      if (!text.trim()) {
+        rest.push(msg);
+        continue;
+      }
+
+      const { userText, sideText } = splitUserTextAndSideChannel(text);
+
+      if (sideText && !isNoOpSideChannelText(sideText)) sideParts.push(sideText);
+
+      if (!userText.trim()) {
+        // Pure side-channel (optionally keep images on a stub user turn).
+        if (contentHasImageParts(msg.content)) {
+          rest.push({
+            ...msg,
+            content: rebuildUserContent(msg.content, ""),
+          });
+        }
+        continue;
+      }
+
+      if (sideText) {
+        rest.push({
+          ...msg,
+          content: rebuildUserContent(msg.content, userText),
+        });
+        continue;
+      }
+    }
+
+    rest.push(msg);
+  }
+
+  if (sideParts.length === 0) {
+    if (systemParts.length === 0) return messages;
+    return [{ role: "system", content: systemParts.join("\n") }, ...rest];
+  }
+
+  const framed = frameContextModeSideChannel(sideParts.join("\n\n"));
+  // Put the real task framing *after* infrastructure context so models that
+  // overweight the end of the system prompt still see the priority rule last.
+  const system = systemParts.length > 0 ? `${systemParts.join("\n")}\n\n${framed}` : framed;
+  return [{ role: "system", content: system }, ...rest];
+}