import type { AgentCheckpointStore, AgentRunStore, RunEventNotifier, RunEventStore } from "./run-store-public-types.js";
import type { LocalAgentStore } from "./store/local-agent-store.js";
/** Conversation mode for agent runs. */
export type AgentModeOption = "agent" | "plan";
export interface SDKImageDimension {
    width: number;
    height: number;
}
export type SDKImage = {
    url: string;
    dimension?: SDKImageDimension;
} | {
    data: string;
    mimeType: string;
    dimension?: SDKImageDimension;
};
export interface SDKUserMessage {
    text: string;
    images?: SDKImage[];
}
export type McpServerConfig = {
    type?: "stdio";
    command: string;
    args?: string[];
    env?: Record<string, string>;
    cwd?: string;
} | {
    type?: "http" | "sse";
    url: string;
    headers?: Record<string, string>;
    auth?: {
        CLIENT_ID: string;
        CLIENT_SECRET?: string;
        scopes?: string[];
    };
};
export type SettingSource = "project" | "user" | "team" | "mdm" | "plugins" | "all";
export type SDKJsonPrimitive = string | number | boolean | null;
export type SDKJsonValue = SDKJsonPrimitive | {
    [key: string]: SDKJsonValue;
} | SDKJsonValue[];
export type SDKCustomToolContent = {
    type: "text";
    text: string;
} | {
    type: "image";
    data: string;
    mimeType?: string;
};
export type SDKCustomToolResult = string | SDKJsonValue | {
    content: SDKCustomToolContent[];
    isError?: boolean;
    structuredContent?: Record<string, SDKJsonValue>;
};
export interface SDKCustomToolContext {
    toolCallId?: string;
}
export interface SDKCustomTool {
    description?: string;
    inputSchema?: Record<string, SDKJsonValue>;
    execute: (args: Record<string, SDKJsonValue>, context: SDKCustomToolContext) => SDKCustomToolResult | Promise<SDKCustomToolResult>;
}
export interface SandboxOptions {
    enabled: boolean;
}
export interface ModelParameterValue {
    id: string;
    value: string;
}
export interface ModelSelection {
    id: string;
    params?: ModelParameterValue[];
}
export interface ModelParameterDefinition {
    id: string;
    displayName?: string;
    values: Array<{
        value: string;
        displayName?: string;
    }>;
}
export interface ModelVariant {
    params: ModelParameterValue[];
    displayName: string;
    description?: string;
    isDefault?: boolean;
}
export interface ModelListItem {
    id: string;
    displayName: string;
    description?: string;
    aliases?: string[];
    parameters?: ModelParameterDefinition[];
    variants?: ModelVariant[];
}
export interface AgentDefinition {
    description: string;
    prompt: string;
    model?: ModelSelection | "inherit";
    mcpServers?: Array<string | Record<string, McpServerConfig>>;
}
/**
 * Options that only apply to local agents. Exported as a standalone type so
 * users can reference it directly (e.g. `Partial<LocalAgentOptions>`) instead
 * of having to unwrap the optional `local` field on `AgentOptions` with
 * `Partial<NonNullable<AgentOptions["local"]>>`.
 */
export interface LocalAgentOptions {
    /**
     * Primary working directory for this local agent (default shell cwd and
     * local agent-store scoping).
     */
    cwd?: string;
    /**
     * Additional / multi-root workspace folders. Merged with {@link cwd} (cwd
     * first, duplicates dropped) so project rules, skills, and request-context
     * workspace metadata load from every unique path. {@link cwd} remains the
     * primary working directory for the default shell and agent-store scoping.
     */
    dirs?: string[];
    /**
     * Enable Cursor's Auto-review for local tool calls. When this is true,
     * local runs select the classifier-backed Auto mode whenever the connected
     * backend has the Auto-review classifier feature enabled.
     */
    autoReview?: boolean;
    /**
     * Custom {@link LocalAgentStore} for this call. When omitted, uses
     * `Cursor.configure({ local: { store } })` if set; otherwise the default
     * SQLite backend when `sqlite3` is installed (`@cursor/sdk/sqlite`), or
     * {@link JsonlLocalAgentStore} when running without native SQLite.
     * Agent rows hold a slim checkpoint ref (`latestCheckpoint.rootBlobId`);
     * blob bytes live on `store.checkpoints`.
     */
    store?: LocalAgentStore;
    /**
     * Ambient Cursor settings layers to load from the local filesystem.
     * Local agents only. On cloud, `project` / `team` / `plugins` are
     * always on and `user` / `mdm` / `local` have no VM equivalent, so
     * this field is gated to the local shape.
     */
    settingSources?: SettingSource[];
    sandboxOptions?: SandboxOptions;
    /**
     * In-process callback tools for this agent, exposed as the
     * `custom-user-tools` MCP server (`GetMcpTools` / `CallMcpTool`). Applied on
     * every `send` unless overridden by {@link LocalSendOptions.customTools}.
     * Local agents only; not supported on cloud agents.
     *
     * Because these tools execute host-provided callbacks in the host process,
     * they never require interactive approval — they run even on sandboxed or
     * `autoReview` runs where MCP server tool calls would otherwise fail closed.
     */
    customTools?: Record<string, SDKCustomTool>;
    /**
     * Enable transport and stall auto-retry for local agent runs. Defaults to
     * true for headless embedders; set false to surface transport errors on the
     * first failure (legacy SDK behavior).
     */
    enableAgentRetries?: boolean;
}
/**
 * Per-send local overrides. Use with `Agent.send(..., { local })`. Agent-level
 * defaults live on {@link LocalAgentOptions} (`Agent.create({ local })`).
 */
export interface LocalSendOptions {
    /**
     * Expire the currently active persisted run, if any, before starting this
     * message as a new follow-up run. Recovery path for local agents left wedged
     * after a crashed CLI process.
     */
    force?: boolean;
    /**
     * Custom tools for this send only. When set, replaces
     * {@link LocalAgentOptions.customTools} for that run.
     */
    customTools?: Record<string, SDKCustomTool>;
}
/**
 * Options that only apply to cloud agents. Exported as a standalone type so
 * users can reference it directly (e.g. `Partial<CloudAgentOptions>`) instead
 * of having to unwrap the optional `cloud` field on `AgentOptions` with
 * `Partial<NonNullable<AgentOptions["cloud"]>>`.
 */
export interface CloudAgentOptions {
    env?: {
        type: "cloud";
        name?: string;
    } | {
        type: "pool";
        name?: string;
    } | {
        type: "machine";
        name?: string;
    };
    repos?: Array<{
        url: string;
        startingRef?: string;
        prUrl?: string;
    }>;
    workOnCurrentBranch?: boolean;
    autoCreatePR?: boolean;
    /**
     * When true, open PRs as the Cursor GitHub App instead of the API-key owner.
     * Defaults to true for service-account keys and false for user keys.
     */
    openAsCursorGithubApp?: boolean;
    skipReviewerRequest?: boolean;
    /**
     * Per-session env vars injected into the cloud agent's shell, e.g. for
     * caller-minted credentials. Encrypted at rest; deleted with the agent.
     */
    envVars?: Record<string, string>;
    /**
     * Caller-owned string tags persisted on the cloud agent for its lifetime.
     * Join to usage or billing exports client-side via `agent.id` / `cloud_agent_id`.
     *
     * Tags are persisted atomically with the cloud agent. Read them back through
     * `Cursor.agents.get(agentId)` / `Cursor.agents.list()` on
     * `SDKAgentInfo.metadata`.
     */
    metadata?: Record<string, string>;
}
export interface CursorAgentPlatformOptions {
    /**
     * Custom {@link LocalAgentStore}. Prefer `local.store` on `Agent.create` /
     * `Agent.resume` unless constructing a platform directly. When omitted, the
     * platform uses built-in SQLite under `stateRoot` — implement
     * {@link LocalAgentStore} only to replace that default path.
     */
    localStore?: LocalAgentStore;
    stateRoot?: string;
    workspaceRef?: string;
    /**
     * When set, custom-store reads filter to agents whose `cwd` matches. Populated
     * from an explicit caller `cwd`; omitted when the caller did not pass one.
     */
    scopedWorkspaceRef?: string;
    /**
     * Internal storage hooks retained for existing advanced callers.
     */
    store?: AgentRunStore;
    checkpointStore?: AgentCheckpointStore;
    eventStore?: RunEventStore;
    eventNotifier?: RunEventNotifier;
}
/**
 * Public tool names accepted by {@link AgentOptions.tools}.
 *
 * The listed literals are a curated set of the common local-agent built-in
 * tools, surfaced for editor autocomplete. They are not the full vocabulary:
 * the complete set is derived from the agent proto at runtime, so the
 * `(string & {})` member keeps the type open — any other public tool name,
 * capability group, or raw proto tool name (e.g. `"web_search_tool_call"`) is
 * still accepted. Unknown names are rejected at `Agent.create` /
 * `Agent.resume`, not by the type.
 */
export type ToolName = "shell" | "read" | "edit" | "grep" | "glob" | "ls" | "task" | "mcp" | "webSearch" | "delete" | "readLints" | "webFetch" | "semSearch" | "updateTodos" | "readTodos" | "askQuestion" | "await" | "generateImage" | "applyAgentDiff" | (string & {});
export interface AgentOptions {
    /**
     * Model selection (`{ id, params? }`). Required for local agents; optional
     * for cloud (the server resolves the caller's configured default when
     * omitted). Use `Cursor.models.list()` to discover valid selections.
     */
    model?: ModelSelection;
    apiKey?: string;
    /**
     * Restricts the built-in tools available to the model:
     *
     * - `undefined` (default) — the standard toolset for the selected model.
     * - `[]` — no built-in tools; the model can only respond with text.
     * - Non-empty — only the listed tools are offered to the model.
     *
     * Tool names use the SDK's public tool vocabulary — the same names carried
     * by `tool_call` stream events (`"shell"`, `"read"`, `"edit"`, `"grep"`,
     * `"glob"`, `"ls"`, `"task"`, `"mcp"`, ...). The vocabulary is derived from
     * the agent proto, so tools added to the platform are addressable without
     * an SDK update; raw proto tool names such as `"web_search_tool_call"` are
     * also accepted. Unknown names throw a `ConfigurationError` at
     * `Agent.create` / `Agent.resume` listing the valid names.
     *
     * Notes:
     * - `"shell"` and `"mcp"` are capability groups: `"shell"` also grants
     *   shell stdin writes, and `"mcp"` grants the whole MCP tool family
     *   (including {@link LocalAgentOptions.customTools}); omitting `"mcp"`
     *   disables MCP entirely.
     * - `"task"` gates subagents. Subagents launched through it keep their own
     *   curated toolsets; the restriction applies to the main agent loop.
     * - Not persisted on the agent: pass `tools` again on `Agent.resume` to
     *   keep the restriction for follow-up runs.
     *
     * Local agents only for now; combining `tools` with `cloud` throws a
     * `ConfigurationError`.
     *
     * See {@link ToolName} for the accepted names.
     */
    tools?: ToolName[];
    /**
     * Removes the listed built-in tools from the model's toolset. The
     * complement of {@link AgentOptions.tools}: instead of naming what stays,
     * name what goes, and everything else in the default toolset remains
     * available — including tools added to the platform after this SDK was
     * released.
     *
     * Accepts the same vocabulary as `tools` (public names, capability groups,
     * raw proto names); unknown names throw a `ConfigurationError` at
     * `Agent.create` / `Agent.resume`. Capability groups expand the same way:
     * `"shell"` also removes shell stdin writes, and `"mcp"` removes the whole
     * MCP tool family (including {@link LocalAgentOptions.customTools}).
     *
     * Notes:
     * - Combines with `tools` as deny-wins: a tool must be listed in `tools`
     *   (when set) and not listed in `disallowedTools` to be offered.
     * - Like `tools`, the exclusion applies to the main agent loop: subagents
     *   launched through `"task"` keep their own curated toolsets. Disallow
     *   `"task"` to prevent subagents entirely.
     * - Not persisted on the agent: pass `disallowedTools` again on
     *   `Agent.resume` to keep the exclusion for follow-up runs.
     *
     * Local agents only for now; combining `disallowedTools` with `cloud`
     * throws a `ConfigurationError`.
     */
    disallowedTools?: ToolName[];
    /**
     * Optional human-readable name for the agent, surfaced as the `title` in
     * `Agent.list()` / `Agent.get()`. Cloud agents auto-generate a name from
     * the first prompt when this is omitted; local agents fall back to a
     * generic default.
     */
    name?: string;
    local?: LocalAgentOptions;
    cloud?: CloudAgentOptions;
    mcpServers?: Record<string, McpServerConfig>;
    agents?: Record<string, AgentDefinition>;
    agentId?: string;
    idempotencyKey?: string;
    /** Initial conversation mode for this agent. */
    mode?: AgentModeOption;
}
//# sourceMappingURL=options.d.ts.map