cursor-sdk 0.1.3__py3-none-win_amd64.whl

cursor_sdk/__init__.py

@@ -0,0 +1,242 @@
+from ._async_agent import AsyncAgent
+from ._async_bridge import AsyncBridge
+from ._async_client import AsyncClient, AsyncCursorClient
+from ._async_connect import AsyncConnectTransport, DefaultAsyncHttpxClient
+from ._async_cursor import AsyncCursor
+from ._async_run import AsyncRun
+from ._bridge import Bridge, BridgeEndpoint
+from ._agent import Agent
+from ._client import Client, CursorClient, close_default_client
+from ._cursor import Cursor
+from ._run import Run
+from ._connect import DefaultHttpxClient
+from .errors import (
+    AuthenticationError,
+    APITimeoutError,
+    BadRequestError,
+    ConfigurationError,
+    CursorAgentError,
+    CursorSDKError,
+    IntegrationNotConnectedError,
+    InternalServerError,
+    NetworkError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    UnknownAgentError,
+    UnsupportedRunOperationError,
+)
+from .types import (
+    AgentConversationTurn,
+    AgentDefinition,
+    AgentDefinitionMcpServer,
+    AgentMessage,
+    AgentOptions,
+    AgentOptionsDict,
+    AsyncListResult,
+    CloudAgentOptionsDict,
+    CloudRepositoryDict,
+    AssistantConversationStep,
+    AssistantMessage,
+    CloudAgentOptions,
+    CloudEnvironment,
+    CloudRepository,
+    ConversationStep,
+    ConversationTurn,
+    HttpMcpServerConfig,
+    InteractionUpdate,
+    ListResult,
+    McpAuth,
+    LocalAgentOptions,
+    LocalAgentOptionsDict,
+    LocalSendOptions,
+    LocalSendOptionsDict,
+    ModelSelectionDict,
+    ModelParameterDefinition,
+    ModelParameterDefinitionValue,
+    ModelParameterValue,
+    ModelVariant,
+    ModelSelection,
+    PartialToolCallUpdate,
+    RunGitBranchInfo,
+    RunGitInfo,
+    RunResult,
+    RunSnapshot,
+    RunStreamEvent,
+    SDKAgentInfo,
+    SDKAssistantMessage,
+    SDKAssistantMessageContent,
+    SandboxOptions,
+    SDKImage,
+    SDKImageDimension,
+    SDKMessage,
+    SDKModel,
+    SDKRepository,
+    SDKRequestMessage,
+    SDKStatusMessage,
+    SDKSystemMessage,
+    SDKTaskMessage,
+    SDKThinkingMessage,
+    SDKToolUseMessage,
+    SDKUser,
+    SDKUserMessageContent,
+    SDKUserMessage,
+    SDKUserMessageEvent,
+    SdkArtifact,
+    SDKArtifact,
+    SendOptions,
+    SendOptionsDict,
+    UserMessageDict,
+    ShellCommand,
+    ShellConversationTurn,
+    ShellOutputDeltaUpdate,
+    ShellOutput,
+    SseMcpServerConfig,
+    StepCompletedUpdate,
+    StepStartedUpdate,
+    StdioMcpServerConfig,
+    SummaryCompletedUpdate,
+    SummaryStartedUpdate,
+    SummaryUpdate,
+    TextBlock,
+    ThinkingMessage,
+    ThinkingCompletedUpdate,
+    ThinkingConversationStep,
+    ThinkingDeltaUpdate,
+    TextDeltaUpdate,
+    TokenDeltaUpdate,
+    ToolCallCompletedUpdate,
+    ToolCallConversationStep,
+    ToolCallStartedUpdate,
+    ToolUseBlock,
+    TurnEndedUpdate,
+    UnknownInteractionUpdate,
+    UserMessageAppendedUpdate,
+    UserMessage,
+    parse_conversation_step,
+    parse_interaction_update,
+    sdk_message_from_json,
+)
+
+__all__ = [
+    "Agent",
+    "AgentConversationTurn",
+    "AgentDefinition",
+    "AgentDefinitionMcpServer",
+    "AgentMessage",
+    "AgentOptions",
+    "AgentOptionsDict",
+    "APITimeoutError",
+    "AssistantConversationStep",
+    "AssistantMessage",
+    "AsyncCursorClient",
+    "AsyncAgent",
+    "AsyncBridge",
+    "AsyncClient",
+    "AsyncConnectTransport",
+    "AsyncCursor",
+    "AsyncRun",
+    "AsyncListResult",
+    "AuthenticationError",
+    "BadRequestError",
+    "Bridge",
+    "BridgeEndpoint",
+    "Client",
+    "CursorClient",
+    "CloudAgentOptions",
+    "CloudAgentOptionsDict",
+    "CloudEnvironment",
+    "CloudRepository",
+    "CloudRepositoryDict",
+    "ConfigurationError",
+    "ConversationStep",
+    "ConversationTurn",
+    "Cursor",
+    "CursorAgentError",
+    "CursorSDKError",
+    "DefaultAsyncHttpxClient",
+    "InternalServerError",
+    "DefaultHttpxClient",
+    "HttpMcpServerConfig",
+    "IntegrationNotConnectedError",
+    "InteractionUpdate",
+    "ListResult",
+    "LocalAgentOptions",
+    "LocalAgentOptionsDict",
+    "LocalSendOptions",
+    "LocalSendOptionsDict",
+    "McpAuth",
+    "ModelParameterDefinition",
+    "ModelParameterDefinitionValue",
+    "ModelParameterValue",
+    "ModelSelection",
+    "ModelSelectionDict",
+    "ModelVariant",
+    "NetworkError",
+    "NotFoundError",
+    "PartialToolCallUpdate",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "Run",
+    "RunGitBranchInfo",
+    "RunGitInfo",
+    "RunResult",
+    "RunSnapshot",
+    "RunStreamEvent",
+    "SDKAgentInfo",
+    "SDKArtifact",
+    "SDKAssistantMessage",
+    "SDKAssistantMessageContent",
+    "SDKImage",
+    "SDKImageDimension",
+    "SDKMessage",
+    "SDKModel",
+    "SDKRepository",
+    "SDKRequestMessage",
+    "SDKStatusMessage",
+    "SDKSystemMessage",
+    "SDKTaskMessage",
+    "SDKThinkingMessage",
+    "SDKToolUseMessage",
+    "SDKUser",
+    "SDKUserMessage",
+    "SDKUserMessageContent",
+    "SDKUserMessageEvent",
+    "SandboxOptions",
+    "SdkArtifact",
+    "SendOptions",
+    "SendOptionsDict",
+    "ShellCommand",
+    "ShellConversationTurn",
+    "ShellOutput",
+    "ShellOutputDeltaUpdate",
+    "SseMcpServerConfig",
+    "StdioMcpServerConfig",
+    "StepCompletedUpdate",
+    "StepStartedUpdate",
+    "SummaryCompletedUpdate",
+    "SummaryStartedUpdate",
+    "SummaryUpdate",
+    "TextBlock",
+    "TextDeltaUpdate",
+    "ThinkingCompletedUpdate",
+    "ThinkingConversationStep",
+    "ThinkingDeltaUpdate",
+    "ThinkingMessage",
+    "TokenDeltaUpdate",
+    "ToolCallCompletedUpdate",
+    "ToolCallConversationStep",
+    "ToolCallStartedUpdate",
+    "ToolUseBlock",
+    "TurnEndedUpdate",
+    "UnknownAgentError",
+    "UnknownInteractionUpdate",
+    "UnsupportedRunOperationError",
+    "UserMessage",
+    "UserMessageAppendedUpdate",
+    "UserMessageDict",
+    "close_default_client",
+    "parse_conversation_step",
+    "parse_interaction_update",
+    "sdk_message_from_json",
+]

cursor_sdk/_agent.py

@@ -0,0 +1,432 @@
+"""Sync `Agent` class plus the `_AgentMessages` namespace.
+
+`Agent` is the per-conversation handle returned by `Client.create_agent`
+/ `Client.resume_agent`. It owns the agent_id, an optional caller-supplied
+api_key (used to authenticate cloud-agent RPCs through a remote bridge),
+and forwards calls to its `Client` via internal `_agent_unary` /
+`_agent_stream` helpers.
+
+The `Agent` <-> `Client` cycle is broken by:
+  - `_agent.py` imports `_default_client` (and `Client` only for typing)
+    from `_client.py`.
+  - `_client.py` does not import `_agent.py` at module top — it imports
+    `Agent` lazily inside `Client.create_agent` / `Client.resume_agent`,
+    the only two places it constructs an Agent.
+"""
+
+from __future__ import annotations
+
+import os
+import warnings
+from typing import TYPE_CHECKING, Any, Mapping
+
+from ._client import _default_client
+from ._helpers import (
+    _api_key_or_env,
+    _model_override_from_send_options,
+    _options_with_api_key,
+    _require_send_api_key_for_remote_cloud_agent,
+)
+from ._run import Run
+from .types import (
+    AgentMessage,
+    AgentOptions,
+    CloudAgentOptions,
+    ListResult,
+    LocalAgentOptions,
+    ModelSelection,
+    RunResult,
+    RunStreamEvent,
+    SDKAgentInfo,
+    SdkArtifact,
+    SendOptions,
+    UserMessage,
+    chunks_to_bytes,
+    send_options_idempotency_key,
+    send_options_to_json,
+)
+
+if TYPE_CHECKING:
+    from ._client import Client
+
+
+class _LifecycleMethod:
+    """Dispatch lifecycle calls by class or instance access."""
+
+    def __init__(self, rpc_method: str) -> None:
+        self._rpc_method = rpc_method
+
+    def __get__(self, instance: "Agent | None", owner: type) -> Any:
+        rpc = self._rpc_method
+        if instance is None:
+
+            def class_form(
+                agent_id: str,
+                options: Mapping[str, Any] | None = None,
+                *,
+                client: "Client | None" = None,
+            ) -> None:
+                (client or _default_client())._agent_unary(
+                    rpc,
+                    {"agentId": agent_id, "options": dict(options or {})},
+                )
+
+            return class_form
+
+        agent = instance
+
+        def instance_form(options: Mapping[str, Any] | None = None) -> None:
+            agent._lifecycle_unary(rpc, options)
+
+        return instance_form
+
+
+class Agent:
+    def __init__(
+        self,
+        *,
+        client: "Client",
+        agent_id: str,
+        model: Mapping[str, Any] | ModelSelection | None,
+        api_key: str | None = None,
+    ) -> None:
+        self.client = client
+        self.agent_id = agent_id
+        if model is None:
+            self.model: ModelSelection | None = None
+        elif isinstance(model, ModelSelection):
+            self.model = model
+        else:
+            self.model = ModelSelection.from_json(dict(model))
+        self._api_key = api_key or ""
+
+    @classmethod
+    def create(
+        cls,
+        options: AgentOptions | Mapping[str, Any] | None = None,
+        *,
+        client: "Client | None" = None,
+        model: str | ModelSelection | Mapping[str, Any] | None = None,
+        api_key: str | None = None,
+        name: str | None = None,
+        local: LocalAgentOptions | Mapping[str, Any] | None = None,
+        cloud: CloudAgentOptions | Mapping[str, Any] | None = None,
+        idempotency_key: str | None = None,
+    ) -> "Agent":
+        client = client or _default_client()
+        return client.create_agent(
+            options,
+            model=model,
+            api_key=api_key,
+            name=name,
+            local=local,
+            cloud=cloud,
+            idempotency_key=idempotency_key,
+        )
+
+    @classmethod
+    def resume(
+        cls,
+        agent_id: str,
+        options: AgentOptions | Mapping[str, Any] | None = None,
+        *,
+        client: "Client | None" = None,
+    ) -> "Agent":
+        return (client or _default_client()).resume_agent(agent_id, options)
+
+    @classmethod
+    def prompt(
+        cls,
+        message: str | Mapping[str, Any] | UserMessage,
+        options: AgentOptions | Mapping[str, Any] | None = None,
+        *,
+        client: "Client | None" = None,
+    ) -> RunResult:
+        agent = cls.create(options, client=client)
+        try:
+            return agent.send(message).wait()
+        finally:
+            agent.close()
+
+    @classmethod
+    def list(
+        cls,
+        options: Mapping[str, Any] | None = None,
+        *,
+        client: "Client | None" = None,
+    ) -> ListResult[SDKAgentInfo]:
+        return (client or _default_client()).list_agents(options)
+
+    @classmethod
+    def get(
+        cls,
+        agent_id: str,
+        *,
+        client: "Client | None" = None,
+        cwd: str | os.PathLike[str] | None = None,
+        api_key: str | None = None,
+    ) -> SDKAgentInfo:
+        target = client or _default_client()
+        return target.get_agent(
+            agent_id,
+            cwd=cwd,
+            api_key=_api_key_or_env(
+                api_key,
+                allow_env=target._allow_api_key_env_fallback,
+            ),
+        )
+
+    @classmethod
+    def list_runs(
+        cls,
+        agent_id: str,
+        options: Mapping[str, Any] | None = None,
+        *,
+        client: "Client | None" = None,
+    ) -> ListResult["Run"]:
+        return (client or _default_client()).list_runs(agent_id, options)
+
+    @classmethod
+    def get_run(
+        cls,
+        run_id: str,
+        options: Mapping[str, Any] | None = None,
+        *,
+        client: "Client | None" = None,
+    ) -> "Run":
+        return (client or _default_client()).get_run(run_id, options)
+
+    @classmethod
+    def cancel_run(
+        cls,
+        run_id: str,
+        *,
+        client: "Client | None" = None,
+        agent_id: str | None = None,
+    ) -> None:
+        (client or _default_client()).cancel_run(run_id, agent_id=agent_id)
+
+    @classmethod
+    def archive_agent(
+        cls,
+        agent_id: str,
+        options: Mapping[str, Any] | None = None,
+        *,
+        client: "Client | None" = None,
+    ) -> None:
+        warnings.warn(
+            "Agent.archive_agent is deprecated; use Agent.archive(agent_id) instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        cls.archive(agent_id, options, client=client)
+
+    @classmethod
+    def unarchive_agent(
+        cls,
+        agent_id: str,
+        options: Mapping[str, Any] | None = None,
+        *,
+        client: "Client | None" = None,
+    ) -> None:
+        warnings.warn(
+            "Agent.unarchive_agent is deprecated; use Agent.unarchive(agent_id) instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        cls.unarchive(agent_id, options, client=client)
+
+    @classmethod
+    def delete_agent(
+        cls,
+        agent_id: str,
+        options: Mapping[str, Any] | None = None,
+        *,
+        client: "Client | None" = None,
+    ) -> None:
+        warnings.warn(
+            "Agent.delete_agent is deprecated; use Agent.delete(agent_id) instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        cls.delete(agent_id, options, client=client)
+
+    def send(
+        self,
+        message: str | Mapping[str, Any] | UserMessage,
+        options: SendOptions | Mapping[str, Any] | None = None,
+        *,
+        idempotency_key: str | None = None,
+    ) -> "Run":
+        """Start a run and make explicit model overrides sticky on this agent."""
+        _require_send_api_key_for_remote_cloud_agent(
+            allow_env_fallback=self.client._allow_api_key_env_fallback,
+            agent_id=self.agent_id,
+            api_key=self._api_key,
+        )
+        idempotency_key = idempotency_key or send_options_idempotency_key(options)
+        # Inject the Agent's stored api_key into the outgoing request so the
+        # server can validate it; otherwise skip_remote_cloud_guard would let
+        # an attacker forge an api_key locally and bypass the guard.
+        request_options = _options_with_api_key(
+            self._api_key, send_options_to_json(options)
+        )
+        request = {
+            "agentId": self.agent_id,
+            "message": UserMessage.from_value(message).to_json(),
+            "options": request_options,
+            "idempotencyKey": idempotency_key or "",
+        }
+        run = Run(
+            client=self.client,
+            agent_id=self.agent_id,
+            event_stream=(
+                RunStreamEvent.from_json(event)
+                for event in self.client._agent_stream(
+                    "Send",
+                    request,
+                    skip_remote_cloud_guard=bool(self._api_key),
+                )
+            ),
+            send_options=options if isinstance(options, SendOptions) else None,
+        )
+        # Hand the parent Agent's api_key to the Run so subsequent cloud RPCs
+        # (cancel, wait, observe, conversation_json) include it in their
+        # request options. This is internal-only: there is no public API on
+        # Run to set _api_key, and any value placed here is forwarded to the
+        # bridge for server-side validation, so a forged value gets rejected
+        # by the server instead of silently spending env-fallback credentials.
+        run._api_key = self._api_key
+        model_override = _model_override_from_send_options(options)
+        if model_override is not None:
+            self.model = ModelSelection.from_json(model_override)
+        return run
+
+    def reload(self) -> None:
+        self.client._agent_unary("ReloadAgent", {"agentId": self.agent_id})
+
+    def close(self) -> None:
+        self.client._agent_unary("CloseAgent", {"agentId": self.agent_id})
+
+    def list_messages(
+        self, options: Mapping[str, Any] | None = None
+    ) -> list[AgentMessage]:
+        response = self.client._agent_unary(
+            "ListAgentMessages",
+            {
+                "agentId": self.agent_id,
+                "options": _options_with_api_key(self._api_key, options),
+            },
+            skip_remote_cloud_guard=bool(self._api_key),
+        )
+        return [AgentMessage.from_json(item) for item in response.get("messages", [])]
+
+    def list_artifacts(self) -> list[SdkArtifact]:
+        response = self.client._agent_unary(
+            "ListArtifacts",
+            {
+                "agentId": self.agent_id,
+                "options": _options_with_api_key(self._api_key),
+            },
+            skip_remote_cloud_guard=bool(self._api_key),
+        )
+        return [SdkArtifact.from_json(item) for item in response.get("artifacts", [])]
+
+    def download_artifact(self, path: str) -> bytes:
+        chunks = self.client._agent_stream(
+            "DownloadArtifact",
+            {
+                "agentId": self.agent_id,
+                "path": path,
+                "options": _options_with_api_key(self._api_key),
+            },
+            skip_remote_cloud_guard=bool(self._api_key),
+        )
+        return chunks_to_bytes(chunks)
+
+    def _lifecycle_unary(self, method: str, options: Mapping[str, Any] | None) -> None:
+        # Mirror Agent.send: when this Agent was created/resumed with an
+        # explicit api_key, propagate it into options so cloud-routed lifecycle
+        # calls through a remote bridge pass _is_cloud_agent_rpc's guard.
+        self.client._agent_unary(
+            method,
+            {
+                "agentId": self.agent_id,
+                "options": _options_with_api_key(self._api_key, options),
+            },
+            skip_remote_cloud_guard=bool(self._api_key),
+        )
+
+    def __enter__(self) -> "Agent":
+        return self
+
+    def __exit__(self, exc_type: object, exc: object, tb: object) -> None:
+        self.close()
+
+    archive = _LifecycleMethod("ArchiveAgent")
+    unarchive = _LifecycleMethod("UnarchiveAgent")
+    delete = _LifecycleMethod("DeleteAgent")
+
+
+class _AgentMessages:
+    def list(
+        self,
+        agent_id: str,
+        options: Mapping[str, Any] | None = None,
+        *,
+        client: "Client | None" = None,
+    ) -> list[AgentMessage]:
+        response = (client or _default_client())._agent_unary(
+            "ListAgentMessages", {"agentId": agent_id, "options": dict(options or {})}
+        )
+        return [AgentMessage.from_json(item) for item in response.get("messages", [])]
+
+
+class _AgentLifecycle:
+    """Deprecated. Use `Agent.archive(id)` / `Agent.unarchive(id)` / `Agent.delete(id)`."""
+
+    def archive(
+        self,
+        agent_id: str,
+        options: Mapping[str, Any] | None = None,
+        *,
+        client: "Client | None" = None,
+    ) -> None:
+        warnings.warn(
+            "Agent.lifecycle.archive is deprecated; use Agent.archive(agent_id) instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        Agent.archive(agent_id, options, client=client)
+
+    def unarchive(
+        self,
+        agent_id: str,
+        options: Mapping[str, Any] | None = None,
+        *,
+        client: "Client | None" = None,
+    ) -> None:
+        warnings.warn(
+            "Agent.lifecycle.unarchive is deprecated; use Agent.unarchive(agent_id) instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        Agent.unarchive(agent_id, options, client=client)
+
+    def delete(
+        self,
+        agent_id: str,
+        options: Mapping[str, Any] | None = None,
+        *,
+        client: "Client | None" = None,
+    ) -> None:
+        warnings.warn(
+            "Agent.lifecycle.delete is deprecated; use Agent.delete(agent_id) instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        Agent.delete(agent_id, options, client=client)
+
+
+Agent.messages = _AgentMessages()
+Agent.lifecycle = _AgentLifecycle()