@caeliq/llms 1.0.56 → 1.0.58

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

@@ -0,0 +1,113 @@
+export type SseEmitter = {
+    enqueueChunk: (chunk: Record<string, unknown>) => void;
+    enqueueDone: () => void;
+};
+export declare function createSseHelpers(model: string, encoder: TextEncoder): {
+    setId(next: string): void;
+    content(text: string): {
+        choices: {
+            index: number;
+            delta: {
+                role: string;
+                content: string;
+            };
+            finish_reason: null;
+        }[];
+        id: string;
+        object: string;
+        created: number;
+        model: string;
+    };
+    thinking(text: string): {
+        choices: {
+            index: number;
+            delta: {
+                thinking: {
+                    content: string;
+                };
+            };
+            finish_reason: null;
+        }[];
+        id: string;
+        object: string;
+        created: number;
+        model: string;
+    };
+    /**
+     * Claude Code / Anthropic expecting extended-thinking streams require a
+     * signature_delta before the thinking block is closed. Cursor SDK has no
+     * provider signature, so emit a synthetic one (same pattern as reasoning /
+     * forcereasoning transformers). Without this, thinking_deltas are on the
+     * wire but the UI often never surfaces them.
+     */
+    thinkingSignature(signature?: string): {
+        choices: {
+            index: number;
+            delta: {
+                thinking: {
+                    signature: string;
+                };
+            };
+            finish_reason: null;
+        }[];
+        id: string;
+        object: string;
+        created: number;
+        model: string;
+    };
+    toolCall(tool: {
+        id: string;
+        name: string;
+        args: Record<string, unknown>;
+    }, index?: number): {
+        choices: {
+            index: number;
+            delta: {
+                role: string;
+                tool_calls: {
+                    index: number;
+                    id: string;
+                    type: string;
+                    function: {
+                        name: string;
+                        arguments: string;
+                    };
+                }[];
+            };
+            finish_reason: null;
+        }[];
+        id: string;
+        object: string;
+        created: number;
+        model: string;
+    };
+    finish(reason: "stop" | "tool_calls", usage?: {
+        prompt_tokens?: number;
+        completion_tokens?: number;
+        total_tokens?: number;
+        prompt_tokens_details?: {
+            cached_tokens?: number;
+        };
+    }): {
+        choices: {
+            index: number;
+            delta: {};
+            finish_reason: "stop" | "tool_calls";
+        }[];
+        usage: {
+            prompt_tokens: number;
+            completion_tokens: number;
+            total_tokens: number;
+            prompt_tokens_details: {
+                cached_tokens: number;
+            };
+        };
+        id: string;
+        object: string;
+        created: number;
+        model: string;
+    };
+    encode(chunk: Record<string, unknown>): Uint8Array<ArrayBufferLike>;
+    encodeDone(): Uint8Array<ArrayBufferLike>;
+};
+export declare function accumulateChatCompletion(model: string, chunks: Array<Record<string, unknown>>): Record<string, unknown>;

package/dist/cursor-sdk/hooks-template.d.ts

@@ -0,0 +1,2 @@
+import { type HostEnvironment } from "./host-env";
+export declare function ensureDenyHooksWorkspace(workspaceDir: string, hostEnv?: HostEnvironment): void;

package/dist/cursor-sdk/host-env.d.ts

@@ -0,0 +1,38 @@
+import type { UnifiedChatRequest } from "../types/llm";
+/**
+ * Facts about the machine where host tools actually execute.
+ *
+ * CCR (and therefore the Cursor SDK agent) may run in a container with no
+ * access to the user's filesystem, while Claude Code executes every tool call
+ * on the user's real machine. Cursor builds its harness prompt server-side from
+ * the SDK's workspace root, so the model is told — at system level — that it
+ * lives in the scratch workspace. These facts are the counter-evidence: they are
+ * lifted verbatim from the host's own environment block.
+ */
+export type HostEnvironment = {
+    /** Absolute path of the host project root, when the host advertised one. */
+    projectRoot?: string;
+    /** Extra roots the host declared as in-scope. */
+    additionalRoots: string[];
+    platform?: string;
+    osVersion?: string;
+    /** Every `Key: value` pair discovered, in discovery order, verbatim. */
+    facts: Array<{
+        key: string;
+        value: string;
+    }>;
+    /** True when anything at all was discovered. */
+    known: boolean;
+    /** Stable id of the resolved environment; changes only when the facts change. */
+    fingerprint: string;
+};
+/** Nothing discovered — guidance falls back to conservative path wording. */
+export declare const EMPTY_HOST_ENVIRONMENT: HostEnvironment;
+export declare function extractHostEnvironment(request: UnifiedChatRequest): HostEnvironment;
+/** Bullet lines describing the host machine, for prompt/rules injection. */
+export declare function describeHostEnvironment(env: HostEnvironment): string[];
+/**
+ * Path rule for the model. Positive and concrete when the host root is known,
+ * conservative when it is not — never guess a root.
+ */
+export declare function hostPathRule(env: HostEnvironment): string;

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

@@ -0,0 +1,69 @@
+export type CursorContextAlignment = "strict" | "unknown" | "divergent";
+export type CursorParkedToolRef = {
+    id: string;
+};
+export type CursorToolResultRef = {
+    toolCallId: string;
+};
+export type ExactParkedResultMatch<TParked extends CursorParkedToolRef = CursorParkedToolRef, TResult extends CursorToolResultRef = CursorToolResultRef> = ReadonlyArray<{
+    parked: TParked;
+    result: TResult;
+}>;
+/**
+ * Pair every parked tool with exactly one result by id.
+ *
+ * Empty, missing, extra, blank, or duplicate ids are not exact matches. The
+ * returned pairs follow parked-tool order, and neither input array is mutated.
+ */
+export declare function matchParkedToolResultsExactly<TParked extends CursorParkedToolRef, TResult extends CursorToolResultRef>(parkedTools: readonly TParked[], toolResults: readonly TResult[]): ExactParkedResultMatch<TParked, TResult> | undefined;
+export type CursorRunSnapshot<TParked extends CursorParkedToolRef = CursorParkedToolRef> = {
+    kind: "idle";
+}
+/**
+ * Identical active turns must be coalesced before invoking this planner.
+ * This state therefore always represents a different, superseding turn.
+ */
+ | {
+    kind: "active-different-turn";
+} | {
+    kind: "parked";
+    /** False when the prior iterator/run can no longer be continued. */
+    live: boolean;
+    tools: readonly TParked[];
+};
+export type CursorLifecycleInput<TParked extends CursorParkedToolRef = CursorParkedToolRef, TResult extends CursorToolResultRef = CursorToolResultRef> = {
+    session: {
+        hasSentPrompt: boolean;
+        poisoned: boolean;
+        alignment: CursorContextAlignment;
+        run: CursorRunSnapshot<TParked>;
+    };
+    turn: {
+        hasMeaningfulSteering: boolean;
+        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";
+export type CursorLifecycleRetirementPlan = {
+    action: "retire-and-replay-full";
+    reason: CursorLifecycleRetirementReason;
+};
+export type CursorLifecyclePlan<TParked extends CursorParkedToolRef = CursorParkedToolRef, TResult extends CursorToolResultRef = CursorToolResultRef> = {
+    action: "resume-parked";
+    reason: "exact-parked-tool-results";
+    matches: ExactParkedResultMatch<TParked, TResult>;
+} | {
+    action: "send-full";
+    reason: "unused-session";
+} | {
+    action: "send-incremental";
+    reason: "strictly-aligned-idle-session";
+} | CursorLifecycleRetirementPlan;
+/**
+ * Choose the only safe lifecycle action for a new, non-coalesced host turn.
+ *
+ * This function is intentionally pure. It neither resolves parked tools nor
+ * changes session state; the caller executes the returned plan under its
+ * per-session coordinator.
+ */
+export declare function planCursorLifecycle<TParked extends CursorParkedToolRef, TResult extends CursorToolResultRef>(input: CursorLifecycleInput<TParked, TResult>): CursorLifecyclePlan<TParked, TResult>;

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

@@ -0,0 +1,59 @@
+import type { UnifiedChatRequest } from "../types/llm";
+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;
+/**
+ * Short restatement appended after the transcript. The guidance above is far
+ * from the generation point once history is flattened in; this is the last
+ * thing the model reads before answering.
+ */
+export declare function buildBridgeTailReminder(workspaceDir: string, hostEnv: HostEnvironment): string;
+/** Rules document for the sandbox workspace, injected by Cursor as project rules. */
+export declare function buildWorkspaceRulesDocument(workspaceDir: string, hostEnv: HostEnvironment): string;
+/** One-line rationale attached to Cursor built-in denials. */
+export declare function buildDenyGuidance(hostEnv: HostEnvironment): string;
+/**
+ * Detect a short terminal message that only announces work which never occurred.
+ * Keep this deliberately narrow: it is a recovery signal, not a general quality score.
+ */
+export declare function isProgressOnlyAssistantText(text: string): boolean;
+export declare function shouldContinueProgressOnlyTurn(input: {
+    mode: "bridge" | "plan" | "agent";
+    assistantText: string;
+    emittedHostTools: number;
+    continuationAttempts: number;
+}): boolean;
+export declare function progressOnlyContinuationPrompt(hostEnv?: HostEnvironment): SDKUserMessage;
+/**
+ * Flatten Unified chat history into a single SDK prompt for a fresh/continued send.
+ * Live parked tool results are resolved via customTools.execute — not only this text.
+ */
+export declare function toSdkPrompt(request: UnifiedChatRequest, options: {
+    mode: "bridge" | "plan" | "agent";
+    workspaceDir: string;
+    /** When true, only the latest user turn (+ guidance) is sent — session already has history. */
+    followUpOnly?: boolean;
+    hostEnv?: HostEnvironment;
+    /** Protocol semantics recovered before Anthropic content was flattened. */
+    turnIntent?: UnifiedTurnIntent;
+}): SDKUserMessage;
+export type TrailingCursorToolTurn = {
+    toolResults: Array<{
+        toolCallId: string;
+        content: string;
+        isError?: boolean;
+    }>;
+    /**
+     * Claude Code can reject a tool and append a replacement instruction in the
+     * same Anthropic user block. AnthropicTransformer splits that block into
+     * Unified `tool` then `user` messages. Only meaningful replacement content
+     * counts here; Claude Code's synthetic interruption marker alone does not.
+     */
+    hasTrailingUserInput: boolean;
+};
+export declare function analyzeTrailingCursorToolTurn(request: UnifiedChatRequest, turnIntent?: UnifiedTurnIntent): TrailingCursorToolTurn;
+export declare function extractTrailingToolResults(request: UnifiedChatRequest, turnIntent?: UnifiedTurnIntent): Array<{
+    toolCallId: string;
+    content: string;
+}>;

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

@@ -0,0 +1,40 @@
+import { type SDKMessage } from "@cursor/sdk";
+import type { UnifiedChatRequest } from "../types/llm";
+import type { UnifiedTurnIntent } from "../types/turn-intent";
+import { type CursorSdkSession } from "./session";
+import { type CursorSdkMode } from "./shared";
+export interface CursorSdkRunnerOptions {
+    cursorMode?: CursorSdkMode;
+    cursorCwd?: string;
+    /** Opt-in only; ignored/forced off in Docker. Default false. */
+    sandboxEnabled?: boolean;
+    abortSignal?: AbortSignal;
+    logger?: any;
+    /** Request-local protocol semantics; never serialized into the provider body. */
+    turnIntent?: UnifiedTurnIntent;
+    /** Stable source conversation identity recovered by the protocol adapter. */
+    sourceSessionIdentity?: string;
+}
+export declare function streamSessionEvents(session: CursorSdkSession, mode: CursorSdkMode, runToken: symbol, abortSignal?: AbortSignal): AsyncGenerator<{
+    kind: "sdk";
+    message: SDKMessage;
+    source: "stream" | "delta";
+} | {
+    kind: "host_tool";
+    tool: {
+        id: string;
+        name: string;
+        args: Record<string, unknown>;
+    };
+} | {
+    kind: "end";
+    aborted?: boolean;
+}>;
+/**
+ * Coordinate identical host retries before entering the session lifecycle.
+ *
+ * The shared turn owns the one response producer. Every caller receives an
+ * independent bounded replay stream, so no two HTTP responses can consume the
+ * same Cursor iterator.
+ */
+export declare function runCursor(request: UnifiedChatRequest, provider: any, context: any, options?: CursorSdkRunnerOptions): Promise<Response>;

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

@@ -0,0 +1,9 @@
+import type { SDKUserMessage } from "@cursor/sdk";
+import { type CursorSdkSession } from "./session";
+export declare const CURSOR_SEND_TIMEOUT_MESSAGE = "Cursor SDK agent.send timed out";
+export declare function isCursorAgentBusyError(err: unknown): boolean;
+export declare function isCursorSendPoisonError(err: unknown): boolean;
+export declare function sendCursorPrompt(session: CursorSdkSession, prompt: SDKUserMessage, sendOptions: Record<string, any>, options?: {
+    abortSignal?: AbortSignal;
+    logger?: any;
+}): Promise<import("@cursor/sdk").Run>;

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

@@ -0,0 +1,199 @@
+import { type ModelSelection, type Run, type SDKAgent, type SDKMessage } from "@cursor/sdk";
+import type { OpenAiUsage } from "./usage";
+import type { CursorTranscriptCommit } from "./turn-identity";
+import { type HostEnvironment } from "./host-env";
+import { type CursorSdkMode } from "./shared";
+export type ParkedTool = {
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+    runToken?: symbol;
+    resolve: (result: string) => void;
+    reject: (err: Error) => void;
+    promise: Promise<string>;
+};
+export type CursorSdkSession = {
+    key: string;
+    agent: SDKAgent;
+    agentId: string;
+    mode: CursorSdkMode;
+    workspaceDir: string;
+    /** Host machine facts for this session, refreshed each turn. */
+    hostEnv: HostEnvironment;
+    run?: Run;
+    streamIterator?: AsyncIterator<any>;
+    /**
+     * The one outstanding `iterator.next()` owned by this SDK run. It survives
+     * the HTTP tool-call boundary so a continuation never starts a second
+     * consumer on Cursor's single-consumer iterator.
+     */
+    streamNext?: Promise<IteratorResult<any>>;
+    streamNextRunToken?: symbol;
+    activeRunToken?: symbol;
+    lastSdkUsageRaw?: OpenAiUsage;
+    parked: ParkedTool[];
+    /** Tool calls waiting to be emitted on the current SSE response. */
+    pendingEmit: Array<{
+        id: string;
+        name: string;
+        args: Record<string, unknown>;
+        runToken?: symbol;
+    }>;
+    emitWaiters: Array<() => void>;
+    /** SDK raw delta callbacks waiting to be merged into the current SSE response. */
+    pendingSdkMessages: Array<{
+        message: SDKMessage;
+        runToken?: symbol;
+        source: "delta";
+    }>;
+    sdkMessageWaiters: Array<() => void>;
+    /**
+     * Serializes cancel/send so a follow-up compact/retry cannot call
+     * `agent.send` while a prior run is still marked active in the SDK store.
+     */
+    sendChain: Promise<void>;
+    /** True after at least one successful `agent.send` on this session. */
+    hasSentPrompt: boolean;
+    /**
+     * Exact host-visible transcript represented by this agent after the last
+     * completed response. Unknown means tail-only reuse is forbidden.
+     */
+    transcriptCommit?: CursorTranscriptCommit;
+    /** Agent/model/workspace/tool configuration paired with transcriptCommit. */
+    compatibilityStamp?: string;
+    /** Fingerprint of the host env baked into the workspace rules/deny hooks. */
+    guidanceFingerprint?: string;
+    /**
+     * Set when the local SDK handles are no longer trustworthy. The manager must
+     * not hand this agent out for a future request.
+     */
+    poisoned?: boolean;
+    poisonReason?: string;
+    lastActiveAt: number;
+    metrics: {
+        customToolCalls: number;
+        builtinToolCallsSeen: number;
+        /** Host tool calls whose arguments pointed at the scratch workspace. */
+        scratchPathViolations: number;
+        /** Violations answered with a corrective result instead of execution. */
+        scratchPathCorrections: number;
+    };
+    parkHostTool: (tool: {
+        id: string;
+        name: string;
+        args: Record<string, unknown>;
+    }) => Promise<string>;
+    notifyEmit: () => void;
+    waitForEmit: () => Promise<void>;
+    enqueueSdkMessage: (message: SDKMessage, runToken?: symbol) => void;
+    notifySdkMessage: () => void;
+    waitForSdkMessage: () => Promise<void>;
+};
+export type CancelActiveRunResult = {
+    skipped: boolean;
+    hadRun: boolean;
+    hadIterator: boolean;
+    runCancelFailed: boolean;
+    iteratorReturnFailed: boolean;
+    failed: boolean;
+    timedOut: boolean;
+};
+export declare function markSessionPoisoned(session: CursorSdkSession, reason: string): void;
+/**
+ * Drop local run handles and await SDK `run.cancel()` when needed.
+ *
+ * Cursor persists `activeRunId` in its local store and throws
+ * `Agent … already has active run` on the next `agent.send` until the prior
+ * run is terminal. Client disconnect / compact / retry often leave a live run.
+ */
+export declare function cancelActiveRun(session: CursorSdkSession, options?: {
+    rejectParked?: boolean;
+    reason?: string;
+    timeoutMs?: number;
+    onlyRunToken?: symbol;
+    poisonOnFailure?: boolean;
+}): Promise<CancelActiveRunResult>;
+export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, message: string): Promise<T>;
+/** Run `fn` exclusively against this session's cancel/send critical section. */
+export declare function withSessionSendLock<T>(session: CursorSdkSession, fn: () => Promise<T>): Promise<T>;
+/**
+ * Cursor local sandbox requires a supported host (typically desktop with the
+ * sandbox helper). Docker/Alpine/CI do not support it and throw:
+ * "Local SDK sandboxing was requested, but sandboxing is not supported…".
+ *
+ * Model D relies on deny-hooks + customTools park, not sandbox. Default OFF;
+ * opt in with transformer `sandboxEnabled: true` or `CCR_CURSOR_SANDBOX=1`
+ * only on supported hosts.
+ */
+export declare function shouldEnableCursorSandbox(requested?: boolean): boolean;
+/**
+ * Adopt this turn's host facts and re-stamp workspace rules when they changed.
+ * Cheap: files are only rewritten when their content actually differs.
+ *
+ * Cursor loads workspace rules when the agent's rules service is constructed,
+ * i.e. once per session — verified by appending a canary line to a live
+ * session's AGENTS.md, which the model did not see. So this rewrite serves the
+ * *next* agent created against this directory; the live turn picks up changed
+ * host facts through the prompt, and `session.hostEnv` (used by the scratch
+ * path correction) is updated here regardless.
+ */
+export declare function refreshWorkspaceGuidance(session: CursorSdkSession, hostEnv: HostEnvironment): boolean;
+export declare function buildSessionKey(input: {
+    headerSession?: string;
+    metadataUserId?: string;
+    model?: string;
+    systemAndFirstUser?: string;
+}): string;
+/** True while a session has a live run, open stream, or unresolved host tools. */
+export declare function isSessionInFlight(session: CursorSdkSession): boolean;
+export declare function touchSession(session: CursorSdkSession): void;
+export declare class SessionManager {
+    private logger?;
+    private sessions;
+    /** Per-key teardown barriers so reconnects cannot overtake SDK cancellation. */
+    private retirements;
+    /** Per-key creation barriers so retirement waiters cannot create sibling agents. */
+    private creations;
+    private cleanupTimer?;
+    /** Epoch 0 so the first eviction tick performs a sweep. */
+    private lastSweepAt;
+    constructor(logger?: any | undefined);
+    setLogger(logger: any): void;
+    get(key: string): CursorSdkSession | undefined;
+    retireSession(session: CursorSdkSession, reason: string, cleanup: () => Promise<boolean>): Promise<boolean>;
+    getOrCreate(options: {
+        key: string;
+        apiKey: string;
+        model: ModelSelection;
+        mode: CursorSdkMode;
+        cursorCwd?: string;
+        sandboxEnabled?: boolean;
+        hostEnv?: HostEnvironment;
+    }): Promise<CursorSdkSession>;
+    resume(options: {
+        key: string;
+        agentId: string;
+        apiKey: string;
+        model?: ModelSelection;
+        mode: CursorSdkMode;
+        workspaceDir: string;
+        sandboxEnabled?: boolean;
+        hostEnv?: HostEnvironment;
+    }): Promise<CursorSdkSession>;
+    resolveParkedTools(session: CursorSdkSession, results: Array<{
+        toolCallId: string;
+        content: string;
+    }>): number;
+    dispose(key: string): Promise<void>;
+    invalidate(sessionOrKey: CursorSdkSession | string, reason: string): void;
+    private createSessionRecord;
+    private evictIfNeeded;
+    private evictIdle;
+    /**
+     * Remove scratch workspaces left by earlier processes. `dispose` handles the
+     * live case; this collects what a crash, kill, or pre-cleanup build left on
+     * the volume. Rate limited and restricted to managed directories.
+     */
+    sweepOrphanWorkspaces(now?: number, root?: string): number;
+}
+export declare const globalSessionManager: SessionManager;

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

@@ -0,0 +1,28 @@
+import type { UnifiedMessage } from "../types/llm";
+export declare const CURSOR_SDK_TRANSFORMER_NAME = "cursor-sdk";
+export type CursorSdkMode = "bridge" | "plan" | "agent";
+export declare const DEFAULT_CURSOR_MODE: CursorSdkMode;
+export declare const CCR_HOME: string;
+export declare const CURSOR_SDK_WORKSPACES_ROOT: string;
+export declare const SESSION_IDLE_TTL_MS: number;
+export declare const SESSION_LRU_MAX = 32;
+/** Orphan scratch workspaces are swept after this long without modification. */
+export declare const ORPHAN_WORKSPACE_TTL_MS: number;
+/** How often the sweep may run, regardless of eviction tick frequency. */
+export declare const WORKSPACE_SWEEP_INTERVAL_MS: number;
+/**
+ * True only for a directory this module created for a session.
+ *
+ * Guards every removal: `cursorMode: "agent"` can point the session at a user
+ * supplied `cursorCwd`, which must never be swept.
+ */
+export declare function isManagedWorkspacePath(dir: string, root?: string): boolean;
+/** Cursor built-ins we try to deny so Claude Code remains the tool host. */
+export declare const CURSOR_BUILTIN_DENY_LIST: readonly ["Shell", "Read", "Write", "Delete", "Grep", "Glob", "Edit", "ApplyPatch", "Task", "SemanticSearch", "SemSearch", "ReadLints", "LS", "CreatePlan", "UpdateTodos", "Await", "WebFetch", "WebSearch", "GenerateImage"];
+export declare const CUSTOM_USER_TOOLS_SERVER = "custom-user-tools";
+export declare function ensureCcrHomePaths(): string[];
+/** Flatten Unified message content (string or content parts) into plain text. */
+export declare function contentToText(content: UnifiedMessage["content"]): string;
+export declare function hashSessionFingerprint(parts: string[]): string;
+export declare function coerceThinkingText(value: unknown): string;
+export declare function extractEffort(request: any): string | undefined;

package/dist/cursor-sdk/tool-paths.d.ts

@@ -0,0 +1,26 @@
+import { type HostEnvironment } from "./host-env";
+export type ScratchPathHit = {
+    /** Dotted path to the offending argument, e.g. `edits.0.file_path`. */
+    argPath: string;
+    /** The offending value, truncated. */
+    value: string;
+};
+/**
+ * Detect host tool arguments pointing at the sandbox workspace.
+ *
+ * This is the observable symptom of the model believing it is confined to its
+ * own cwd. Claude Code would execute the call on the host, where that path does
+ * not exist (or, worse, exists as an unrelated directory).
+ */
+export declare function findScratchPaths(args: unknown, workspaceDir: string): ScratchPathHit[];
+/**
+ * Guard against a pathological case: if the user's project genuinely lives
+ * under the scratch root, every path would look like a violation.
+ */
+export declare function scratchDetectionApplies(hostEnv: HostEnvironment): boolean;
+/**
+ * Tool result returned in place of executing the call. Deterministic correction
+ * where the prompt guidance is only preventive — the model gets the topology
+ * again at the exact moment it acted on the wrong belief.
+ */
+export declare function buildScratchPathCorrection(hits: ScratchPathHit[], toolName: string, workspaceDir: string, hostEnv: HostEnvironment): string;

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

@@ -0,0 +1,15 @@
+import type { SDKCustomTool } from "@cursor/sdk";
+import type { UnifiedChatRequest } from "../types/llm";
+import type { CursorSdkSession } from "./session";
+/**
+ * Per-request tally. Session metrics are cumulative and the SDK may invoke
+ * `execute` as soon as `agent.send` resolves — before the response stream is
+ * even constructed — so a start/end delta on the session counter silently
+ * misses the very first violation of a turn.
+ */
+export type TurnToolMetrics = {
+    scratchViolations: number;
+    scratchCorrections: number;
+};
+export declare function createTurnToolMetrics(): TurnToolMetrics;
+export declare function toCustomTools(request: UnifiedChatRequest, session: CursorSdkSession, logger?: any, turn?: TurnToolMetrics): Record<string, SDKCustomTool>;

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

@@ -0,0 +1,46 @@
+import type { UnifiedChatRequest, UnifiedMessage, UnifiedTool } from "../types/llm";
+import type { UnifiedTurnIntent } from "../types/turn-intent";
+import type { CursorSdkMode } from "./shared";
+/**
+ * Fingerprint a logical model turn independently of streaming, request tracing,
+ * cache hints, object insertion order, and JSON argument formatting.
+ */
+export declare function fingerprintCursorTurn(request: UnifiedChatRequest, runtime?: {
+    compatibilityStamp?: string;
+    turnIntent?: UnifiedTurnIntent;
+}): string;
+export type CursorCompatibilityInput = {
+    model: unknown;
+    mode: CursorSdkMode;
+    workspaceDir: string;
+    guidanceFingerprint?: string;
+    sandboxEnabled?: boolean;
+    /**
+     * A one-way credential/account fingerprint supplied by the caller. Never pass
+     * a raw API key.
+     */
+    credentialFingerprint?: string;
+    tools?: UnifiedTool[];
+};
+/**
+ * Fingerprint the properties that must remain compatible when an SDK agent is
+ * reused. The turn fingerprint separately covers prompt/tool semantics.
+ */
+export declare function createCursorCompatibilityStamp(input: CursorCompatibilityInput): string;
+export type CursorTranscriptCommit = Readonly<{
+    transcriptHash: string;
+    messageCount: number;
+}>;
+/**
+ * Commit the host-visible transcript after a successful assistant turn.
+ *
+ * The caller supplies the assistant message assembled from what was actually
+ * emitted to the host, rather than relying on Cursor's opaque checkpoint.
+ */
+export declare function createCursorTranscriptCommit(request: UnifiedChatRequest, assistantMessage?: UnifiedMessage): CursorTranscriptCommit;
+/**
+ * True only when the incoming transcript contains the exact committed prefix
+ * and at least one additional semantic message.
+ */
+export declare function getStrictCursorTranscriptSuffix(commit: CursorTranscriptCommit, request: UnifiedChatRequest): readonly UnifiedMessage[] | undefined;
+export declare function isStrictCursorTranscriptExtension(commit: CursorTranscriptCommit, request: UnifiedChatRequest): boolean;