@caeliq/llms 1.0.66 → 1.0.68

package/dist/cursor-sdk/auth-exchange-cache.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @cursor/sdk POSTs /auth/exchange_user_api_key on every Agent.create and
+ * models.list. Subagent turns mint new session keys, so Agent.create runs
+ * again and the SDK does not cache the access token across those calls.
+ *
+ * Wrap global fetch: coalesce in-flight exchanges per crsr_ key, reuse the
+ * access token until a Cursor request with that token returns 401.
+ *
+ * Critical: never forward a caller's AbortSignal onto the shared exchange.
+ * Agent.create often cancels while another waiter still needs the token; if
+ * the first caller's signal aborts the shared fetch, every waiter rejects
+ * with AbortError and Node surfaces unhandledRejection / late-handled
+ * PromiseRejectionHandledWarning.
+ */
+/**
+ * Drop a cached exchanged token for a dashboard API key (crsr_... or Bearer).
+ * Call when Cursor reports auth failure via run status / AuthenticationError —
+ * those paths often never surface as an HTTP 401 on the wrapped fetch.
+ */
+export declare function invalidateCursorAuthExchange(crsrApiKey: string): void;
+/** Re-wrap if tests or other code replaced globalThis.fetch. */
+export declare function installCursorAuthExchangeCache(): void;
+export declare function __resetCursorAuthExchangeCacheForTests(): void;

package/dist/cursor-sdk/events-to-sse.d.ts

@@ -95,12 +95,12 @@ export declare function createSseHelpers(model: string, encoder: TextEncoder): {
             finish_reason: "stop" | "tool_calls";
         }[];
         usage: {
+            prompt_tokens_details?: {
+                cached_tokens: number;
+            } | undefined;
             prompt_tokens: number;
             completion_tokens: number;
             total_tokens: number;
-            prompt_tokens_details: {
-                cached_tokens: number;
-            };
         };
         id: string;
         object: string;

package/dist/cursor-sdk/lifecycle-planner.d.ts

@@ -36,6 +36,11 @@ export type CursorLifecycleInput<TParked extends CursorParkedToolRef = CursorPar
         hasSentPrompt: boolean;
         poisoned: boolean;
         alignment: CursorContextAlignment;
+        /**
+         * False when agent/model/workspace/tool configuration changed since the
+         * transcript commit. Undefined preserves the legacy behavior (match).
+         */
+        compatibilityMatch?: boolean;
         run: CursorRunSnapshot<TParked>;
     };
     turn: {
@@ -43,7 +48,9 @@ export type CursorLifecycleInput<TParked extends CursorParkedToolRef = CursorPar
         toolResults: readonly TResult[];
     };
 };
-export type CursorLifecycleRetirementReason = "poisoned-session" | "inconsistent-unused-session" | "unknown-context-alignment" | "divergent-context-alignment" | "active-different-turn" | "dead-parked-run" | "parked-turn-has-steering" | "parked-tool-results-mismatch" | "orphaned-tool-results";
+/** Hard remint only — soft alignment cases stay on the same agent. */
+export type CursorLifecycleRetirementReason = "poisoned-session";
+export type CursorLifecycleIncrementalReason = "strictly-aligned-idle-session" | "unknown-context-alignment" | "divergent-context-alignment" | "active-different-turn" | "dead-parked-run" | "parked-turn-has-steering" | "parked-tool-results-mismatch" | "orphaned-tool-results";
 export type CursorLifecycleRetirementPlan = {
     action: "retire-and-replay-full";
     reason: CursorLifecycleRetirementReason;
@@ -54,13 +61,23 @@ export type CursorLifecyclePlan<TParked extends CursorParkedToolRef = CursorPark
     matches: ExactParkedResultMatch<TParked, TResult>;
 } | {
     action: "send-full";
-    reason: "unused-session";
+    reason: "unused-session" | "inconsistent-unused-session";
 } | {
     action: "send-incremental";
-    reason: "strictly-aligned-idle-session";
+    reason: CursorLifecycleIncrementalReason;
 } | CursorLifecycleRetirementPlan;
 /**
- * Choose the only safe lifecycle action for a new, non-coalesced host turn.
+ * Soft incremental reasons where the runner must cancel/abandon any prior
+ * active or parked run before `agent.send` — without reminting the agent.
+ */
+export declare const CURSOR_SOFT_CANCEL_THEN_INCREMENTAL: Set<CursorLifecycleIncrementalReason>;
+/**
+ * Choose the lifecycle action for a new, non-coalesced host turn.
+ *
+ * Soft transcript-alignment mismatches stay on the same Cursor agent via
+ * `send-incremental` (caller cancels parked/active runs when needed). Hard
+ * remint (`retire-and-replay-full`) is reserved for poisoned sessions; send/
+ * stream failure recovery remints in the runner, not here.
  *
  * This function is intentionally pure. It neither resolves parked tools nor
  * changes session state; the caller executes the returned plan under its

package/dist/cursor-sdk/prompt.d.ts

@@ -3,6 +3,11 @@ import { type UnifiedTurnIntent } from "../types/turn-intent";
 import type { SDKUserMessage } from "@cursor/sdk";
 import { type HostEnvironment } from "./host-env";
 export declare function buildBridgeSystemGuidance(request: UnifiedChatRequest, workspaceDir: string, hostEnv?: HostEnvironment): string;
+/**
+ * Identity of the bridge preamble actually sent on an agent. Unchanged
+ * follow-ups skip re-sending it so Cursor history does not stack copies.
+ */
+export declare function bridgePromptGuidanceFingerprint(request: UnifiedChatRequest, workspaceDir: string, hostEnv: HostEnvironment): string;
 /**
  * Short restatement appended after the transcript. The guidance above is far
  * from the generation point once history is flattened in; this is the last
@@ -37,6 +42,11 @@ export declare function toSdkPrompt(request: UnifiedChatRequest, options: {
     hostEnv?: HostEnvironment;
     /** Protocol semantics recovered before Anthropic content was flattened. */
     turnIntent?: UnifiedTurnIntent;
+    /**
+     * Bridge preamble + tail reminder. Default true. Set false on follow-ups
+     * whose tool catalog and host env already went out on this agent.
+     */
+    includeBridgeGuidance?: boolean;
 }): SDKUserMessage;
 export type TrailingCursorToolTurn = {
     toolResults: Array<{

package/dist/cursor-sdk/session.d.ts

@@ -4,6 +4,7 @@ import type { CursorTranscriptCommit } from "./turn-identity";
 import { type HostEnvironment } from "./host-env";
 import { type CursorSdkMode } from "./shared";
 export type ParkedTool = {
+    /** Original Cursor SDK tool-call id (never emitted to the client). */
     id: string;
     name: string;
     args: Record<string, unknown>;
@@ -30,8 +31,20 @@ export type CursorSdkSession = {
     streamNext?: Promise<IteratorResult<any>>;
     streamNextRunToken?: symbol;
     activeRunToken?: symbol;
+    /** Raw usage from the last completed SDK turn; never a parked CCR boundary. */
     lastSdkUsageRaw?: OpenAiUsage;
     parked: ParkedTool[];
+    /**
+     * Per-session bidirectional map between raw Cursor SDK tool-call ids
+     * (possibly newline-joined / overlong) and the host-safe aliases emitted
+     * to the client. Parked records keep originals; the wire carries aliases;
+     * incoming echoes are translated back before matching. Dies with the
+     * session; bounded below so long-lived agents cannot grow it forever.
+     */
+    toolIdAliases: {
+        byOriginal: Map<string, string>;
+        byAlias: Map<string, string>;
+    };
     /** Tool calls waiting to be emitted on the current SSE response. */
     pendingEmit: Array<{
         id: string;
@@ -63,6 +76,11 @@ export type CursorSdkSession = {
     compatibilityStamp?: string;
     /** Fingerprint of the host env baked into the workspace rules/deny hooks. */
     guidanceFingerprint?: string;
+    /**
+     * Bridge preamble last actually sent on this agent (host env + tool catalog).
+     * Unchanged follow-ups omit the preamble so history does not stack copies.
+     */
+    lastBridgePromptGuidanceFingerprint?: string;
     /**
      * Set when the local SDK handles are no longer trustworthy. The manager must
      * not hand this agent out for a future request.
@@ -98,6 +116,13 @@ export type CancelActiveRunResult = {
     failed: boolean;
     timedOut: boolean;
 };
+export declare function aliasHostToolId(session: CursorSdkSession, original: unknown): string | undefined;
+/**
+ * Translate a client-echoed tool-call id back to the parked SDK original.
+ * Unknown ids pass through unchanged so legacy / unmapped turns mismatch
+ * exactly as before instead of collapsing onto something unrelated.
+ */
+export declare function resolveHostToolId(session: CursorSdkSession, echoed: unknown): string;
 export declare function markSessionPoisoned(session: CursorSdkSession, reason: string): void;
 /**
  * Drop local run handles and await SDK `run.cancel()` when needed.
@@ -138,11 +163,29 @@ export declare function shouldEnableCursorSandbox(requested?: boolean): boolean;
  * path correction) is updated here regardless.
  */
 export declare function refreshWorkspaceGuidance(session: CursorSdkSession, hostEnv: HostEnvironment): boolean;
+/**
+ * Cursor SDK session directory key. Prefer explicit client conversation ids
+ * over hashing prompt text — never include system / harness version.
+ *
+ * Claude Code subagents share the parent session id. Mix first-user text so
+ * parallel Task agents each get their own Cursor Agent instead of collapsing
+ * onto one turn registry slot.
+ */
 export declare function buildSessionKey(input: {
     headerSession?: string;
+    /** Inbound-captured Claude/OpenCode session id (protocolContext / req). */
+    clientSessionId?: string;
     metadataUserId?: string;
     model?: string;
+    /** Anonymous clients only: first user text (not system). */
+    firstUserText?: string;
+    /** @deprecated Use firstUserText. Kept for call-site compatibility. */
     systemAndFirstUser?: string;
+    /**
+     * Claude Code Task / subagent turn. Parent session id alone is not unique
+     * across parallel subagents.
+     */
+    isSubagent?: boolean;
 }): string;
 /** True while a session has a live run, open stream, or unresolved host tools. */
 export declare function isSessionInFlight(session: CursorSdkSession): boolean;
@@ -187,6 +230,7 @@ export declare class SessionManager {
     dispose(key: string): Promise<void>;
     invalidate(sessionOrKey: CursorSdkSession | string, reason: string): Promise<void>;
     private disposeAgent;
+    private rehydratePersistedAgent;
     private createSessionRecord;
     private evictIfNeeded;
     private evictIdle;

package/dist/cursor-sdk/shared.d.ts

@@ -26,3 +26,10 @@ export declare function contentToText(content: UnifiedMessage["content"]): strin
 export declare function hashSessionFingerprint(parts: string[]): string;
 export declare function coerceThinkingText(value: unknown): string;
 export declare function extractEffort(request: any): string | undefined;
+/**
+ * Transient Cursor provider failures (throttling / overload) must not destroy
+ * the warm sticky agent: the retry reuses it instead of paying a cold start.
+ * Auth errors and client aborts are NOT transient — they keep the old
+ * retire-the-session behavior at the call site.
+ */
+export declare function isCursorTransientProviderError(err: unknown): boolean;

package/dist/cursor-sdk/turn-output.d.ts

@@ -71,6 +71,9 @@ export declare class CursorTurnRegistry {
         responseKind: "stream" | "json";
         signal?: AbortSignal;
     }): Promise<CursorTurnLease>;
+    peekActive(sessionKey: string): {
+        fingerprint: string;
+    } | undefined;
     clear(): void;
 }
 export declare const globalCursorTurnRegistry: CursorTurnRegistry;

package/dist/cursor-sdk/usage.d.ts

@@ -7,6 +7,13 @@ export type OpenAiUsage = {
         cached_tokens?: number;
     };
 };
+export type CursorUsageCounters = {
+    inputTokens: number;
+    outputTokens: number;
+    cacheRead: number;
+    cacheWrite: number;
+    reasoningTokens: number;
+};
 /**
  * Rough char→token estimate for mid-turn usage before Cursor emits a usage
  * event (and as the host-facing request usage even when it does).
@@ -18,11 +25,28 @@ export declare function estimateTokens(chars: number): number;
 export declare function estimateRequestPromptTokens(request: UnifiedChatRequest): number;
 /** Build OpenAI-style usage for a single CCR request (not Cursor session totals). */
 export declare function requestUsageFromEstimate(promptTokens: number, outputChars: number, cacheReadTokens?: number): OpenAiUsage;
+export declare function cursorUsageCountersFromSdk(raw: OpenAiUsage | undefined): CursorUsageCounters | undefined;
 /**
- * Cursor SDK usage is session-cumulative, while Claude Code needs per-request
- * usage. Use SDK usage only as a cache-read ratio and apply it to CCR's
- * current-request prompt estimate.
+ * Cursor SDK usage is per SDK turn, while Claude Code needs per-CCR-request
+ * usage. In bridge mode one SDK turn can span several parked host-tool request
+ * cycles. Use a terminal SDK witness only as a cache-read ratio for the CCR
+ * request that observes it; never attribute it to an earlier parked response.
+ *
+ * Kept for tests; prefer buildAccurateUsageFromSdk for turn-end reporting.
  */
 export declare function cacheReadFromSdkDelta(current: OpenAiUsage | undefined, previous: OpenAiUsage | undefined, promptTokens: number): number;
+/**
+ * Build per-request OpenAI usage from the SDK turn-end usage message,
+ * normalized to the per-request prompt estimate but preserving Cursor's cache
+ * proportions (same math as cursor-opencode-provider
+ * buildLanguageModelV3UsageFromCounters). Falls back to chars/4-based
+ * completion tokens when SDK output is absent.
+ *
+ * When the runtime reports no usage for the turn (the SDK emits the usage
+ * message only "when the runtime reported usage"), prompt_tokens_details is
+ * omitted entirely so the cache-outcome tap reports "unknown" instead of a
+ * bogus "unexpected-miss" from a zero that was never measured.
+ */
+export declare function buildAccurateUsageFromSdk(sdkRaw: OpenAiUsage | undefined, promptTokens: number, outputChars: number, priorRaw?: OpenAiUsage | undefined): OpenAiUsage;
 /** Map SDK TokenUsage / usage message into OpenAI shape (diagnostics only). */
 export declare function usageFromSdk(message: any): OpenAiUsage | undefined;