effect-cursor-sdk 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,840 @@
+import { Config, Context, Effect, Layer, ManagedRuntime, Metric, Option, Redacted, Schema, Scope, Stream } from "effect";
+import { AgentDefinition, AgentMessage, AgentOperationOptions, AgentOptions, AuthenticationError, ConfigurationError, CursorAgentError, CursorAgentPlatform, CursorRequestOptions, GetAgentMessagesOptions, GetAgentOptions, GetRunOptions, IntegrationNotConnectedError, ListAgentsOptions, ListResult, ListRunsOptions, McpServerConfig, ModelListItem, ModelParameterDefinition, ModelParameterValue, ModelSelection, ModelVariant, NetworkError, RateLimitError, Run, RunOperation, RunResult, RunResultStatus, RunStatus, SDKAgent, SDKAgentInfo, SDKArtifact, SDKAssistantMessage, SDKImage, SDKImageDimension, SDKMessage, SDKModel, SDKRepository, SDKStatusMessage, SDKSystemMessage, SDKTaskMessage, SDKThinkingMessage, SDKToolUseMessage, SDKUser, SDKUserMessage, SDKUserMessageEvent, SendOptions, SettingSource, TextBlock, ToolUseBlock, UnknownAgentError, UnsupportedRunOperationError, createAgentPlatform, createInMemoryRunEventNotifier, createLocalRunEventNotifier, createSdkMessageRunStreamEvent, decodeLocalRunStreamEvent, decodeSdkMessageRunStreamEvent, getTurnType, isTerminalLocalRunStreamEvent, localRunStreamEventToSdkMessage, startLocalRunEventNotifierServer } from "@cursor/sdk";
+import * as _$effect_Types0 from "effect/Types";
+import * as _$effect_Cause0 from "effect/Cause";
+
+//#region src/cursor-error.d.ts
+/**
+ * The operation being executed when an SDK error crossed into Effect.
+ *
+ * @category errors
+ */
+type CursorOperation = "agent.create" | "agent.resume" | "agent.prompt" | "agent.send" | "agent.close" | "agent.reload" | "agent.dispose" | "agent.list" | "agent.get" | "agent.archive" | "agent.unarchive" | "agent.delete" | "messages.list" | "run.list" | "run.get" | "run.wait" | "run.stream" | "run.conversation" | "run.cancel" | "artifacts.list" | "artifacts.download" | "cursor.me" | "cursor.models.list" | "cursor.repositories.list";
+/**
+ * Safe metadata attached to wrapper errors.
+ *
+ * @category errors
+ */
+interface CursorErrorContext {
+  readonly operation: CursorOperation;
+  readonly agentId?: string;
+  readonly runId?: string;
+  readonly runtime?: "local" | "cloud";
+  readonly status?: string;
+}
+interface CursorErrorFields extends CursorErrorContext {
+  readonly message: string;
+  readonly cause: unknown;
+  readonly isRetryable: boolean;
+}
+declare const CursorAuthenticationError_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "CursorAuthenticationError";
+} & Readonly<A>;
+/**
+ * Authentication or permission failure reported by the Cursor SDK.
+ *
+ * @see {@link mapCursorError}
+ * @category errors
+ */
+declare class CursorAuthenticationError extends CursorAuthenticationError_base<CursorErrorFields> {}
+declare const CursorRateLimitError_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "CursorRateLimitError";
+} & Readonly<A>;
+/**
+ * Cursor rate limit or usage-limit failure.
+ *
+ * @see {@link mapCursorError}
+ * @category errors
+ */
+declare class CursorRateLimitError extends CursorRateLimitError_base<CursorErrorFields> {}
+declare const CursorConfigurationError_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "CursorConfigurationError";
+} & Readonly<A>;
+/**
+ * Invalid configuration, model, prompt, repository, or request options.
+ *
+ * @see {@link AgentOptions}
+ * @see {@link mapCursorError}
+ * @category errors
+ */
+declare class CursorConfigurationError extends CursorConfigurationError_base<CursorErrorFields> {}
+declare const CursorIntegrationNotConnectedError_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "CursorIntegrationNotConnectedError";
+} & Readonly<A>;
+/**
+ * SCM integration is not connected for a requested cloud repository.
+ *
+ * @see {@link mapCursorError}
+ * @category errors
+ */
+declare class CursorIntegrationNotConnectedError extends CursorIntegrationNotConnectedError_base<CursorErrorFields & {
+  readonly provider?: string;
+  readonly helpUrl?: string;
+}> {}
+declare const CursorNetworkError_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "CursorNetworkError";
+} & Readonly<A>;
+/**
+ * Network, service availability, timeout, or backend failure.
+ *
+ * @see {@link mapCursorError}
+ * @category errors
+ */
+declare class CursorNetworkError extends CursorNetworkError_base<CursorErrorFields> {}
+declare const CursorUnsupportedOperationError_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "CursorUnsupportedOperationError";
+} & Readonly<A>;
+/**
+ * A run operation is unavailable for the current runtime or run state.
+ *
+ * @see {@link RunOperation}
+ * @see {@link mapCursorError}
+ * @category errors
+ */
+declare class CursorUnsupportedOperationError extends CursorUnsupportedOperationError_base<CursorErrorFields & {
+  readonly sdkOperation?: RunOperation;
+}> {}
+declare const CursorRunFailedError_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "CursorRunFailedError";
+} & Readonly<A>;
+/**
+ * A run reached an error terminal state or failed to produce a usable result.
+ *
+ * @see {@link RunResult}
+ * @category errors
+ */
+declare class CursorRunFailedError extends CursorRunFailedError_base<CursorErrorFields> {}
+declare const CursorStreamError_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "CursorStreamError";
+} & Readonly<A>;
+/**
+ * Stream creation or iteration failed.
+ *
+ * @see {@link CursorRunService}
+ * @see {@link SDKMessage}
+ * @category errors
+ */
+declare class CursorStreamError extends CursorStreamError_base<CursorErrorFields> {}
+declare const CursorUnknownError_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "CursorUnknownError";
+} & Readonly<A>;
+/**
+ * Fallback for unknown SDK or JavaScript failures.
+ *
+ * @see {@link mapCursorError}
+ * @category errors
+ */
+declare class CursorUnknownError extends CursorUnknownError_base<CursorErrorFields> {}
+/**
+ * Convert any SDK failure into a tagged Effect error.
+ *
+ * @param cause - Unknown value thrown by `@cursor/sdk` or JavaScript runtime code.
+ * @param context - Safe operation metadata to attach to the tagged error.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { mapCursorError } from "effect-cursor-sdk"
+ *
+ * const effect = Effect.tryPromise({
+ *   try: () => run.wait(),
+ *   catch: (cause) => mapCursorError(cause, { operation: "run.wait", runId: run.id })
+ * })
+ * ```
+ *
+ * @see {@link CursorAuthenticationError}
+ * @see {@link CursorUnsupportedOperationError}
+ * @see {@link CursorStreamError}
+ *
+ * @category errors
+ */
+declare function mapCursorError(cause: unknown, context: CursorErrorContext & {
+  readonly operation: "run.stream";
+}): CursorStreamError;
+declare function mapCursorError(cause: unknown, context: CursorErrorContext & {
+  readonly operation: "run.cancel" | "run.conversation";
+}): CursorAuthenticationError | CursorRateLimitError | CursorIntegrationNotConnectedError | CursorConfigurationError | CursorNetworkError | CursorUnsupportedOperationError | CursorUnknownError;
+declare function mapCursorError(cause: unknown, context: CursorErrorContext): CursorAuthenticationError | CursorRateLimitError | CursorIntegrationNotConnectedError | CursorConfigurationError | CursorNetworkError | CursorUnknownError;
+//#endregion
+//#region src/cursor-sdk-factory.d.ts
+/**
+ * Thin boundary around the static `@cursor/sdk` APIs.
+ *
+ * Most application code should use {@link CursorAgentService},
+ * {@link CursorRunService}, {@link CursorArtifactService}, and
+ * {@link CursorInspectionService}. This factory exists so live code, tests, and
+ * user applications can replace SDK construction and static calls without
+ * monkey-patching imports.
+ *
+ * So in one line: you probably won't need this.
+ *
+ * @example
+ * ```ts
+ * import { CursorSdkFactory, CursorAgentService } from "effect-cursor-sdk"
+ * import { Layer } from "effect"
+ *
+ * const TestSdk = Layer.succeed(CursorSdkFactory)(
+ *   CursorSdkFactory.of({
+ *     create: () => mockAgent,
+ *     // implement the remaining factory methods for your test
+ *   })
+ * )
+ * ```
+ *
+ * @see {@link CursorAgentService} for creating, resuming, sending, and disposing agents.
+ * @see {@link CursorRunService} for wrapping `Run` handles.
+ * @see {@link CursorInspectionService} for static agent and account APIs.
+ * @see {@link CursorArtifactService} for artifact APIs on an SDK agent.
+ *
+ * @remarks
+ * **API boundary notice:** `create`, `resume`, and `prompt` take raw
+ * {@link AgentOptions} today; the same possible future change described on
+ * {@link CursorAgentServiceShape} may apply here. Prefer
+ * {@link loadCursorConfig} with {@link agentOptionsFromConfig} before calling
+ * these methods when wiring production code.
+ *
+ * @category services
+ */
+interface CursorSdkFactoryShape {
+  readonly create: (options: AgentOptions) => Promise<SDKAgent>;
+  readonly resume: (agentId: string, options?: Partial<AgentOptions>) => Promise<SDKAgent>;
+  readonly prompt: (message: string, options?: AgentOptions) => Promise<RunResult>;
+  readonly listAgents: (options?: ListAgentsOptions) => Promise<ListResult<SDKAgentInfo>>;
+  readonly listRuns: (agentId: string, options?: ListRunsOptions) => Promise<ListResult<Run>>;
+  readonly getRun: (runId: string, options?: GetRunOptions) => Promise<Run>;
+  readonly getAgent: (agentId: string, options?: GetAgentOptions) => Promise<SDKAgentInfo>;
+  readonly archiveAgent: (agentId: string, options?: AgentOperationOptions) => Promise<void>;
+  readonly unarchiveAgent: (agentId: string, options?: AgentOperationOptions) => Promise<void>;
+  readonly deleteAgent: (agentId: string, options?: AgentOperationOptions) => Promise<void>;
+  readonly listMessages: (agentId: string, options?: GetAgentMessagesOptions) => Promise<AgentMessage[]>;
+  readonly me: (options?: CursorRequestOptions) => Promise<SDKUser>;
+  readonly listModels: (options?: CursorRequestOptions) => Promise<SDKModel[]>;
+  readonly listRepositories: (options?: CursorRequestOptions) => Promise<SDKRepository[]>;
+}
+declare const CursorSdkFactory_base: Context.ServiceClass<CursorSdkFactory, "effect-cursor-sdk/cursor-sdk-factory/CursorSdkFactory", CursorSdkFactoryShape>;
+/**
+ * Context service that provides the live `@cursor/sdk` static API boundary.
+ *
+ * Use {@link CursorSdkFactory.Live} in production layers and override the
+ * service in tests with {@link makeMockSdkFactoryLayer} or a custom layer.
+ *
+ * @example
+ * ```ts
+ * const program = Effect.gen(function*() {
+ *   const sdk = yield* CursorSdkFactory
+ *   return sdk.create({ model: { id: "composer-2" }, local: { cwd: process.cwd() } })
+ * })
+ * ```
+ *
+ * @see {@link CursorSdkFactoryShape}
+ * @see {@link liveLayer}
+ * @category services
+ */
+declare class CursorSdkFactory extends CursorSdkFactory_base {
+  static readonly Live: Layer.Layer<CursorSdkFactory, never, never>;
+}
+//#endregion
+//#region src/cursor-agent.d.ts
+/**
+ * Agent lifecycle surface backed by the Cursor SDK.
+ *
+ * @remarks
+ * **API boundary notice:** `create`, `resume`, `prompt`, and `scoped` currently
+ * accept raw {@link AgentOptions} (including a plain `apiKey` string). A future
+ * major version may require options to flow through Effectful {@link CursorConfig}
+ * with {@link loadCursorConfig} and {@link agentOptionsFromConfig} instead of
+ * passing `AgentOptions` at this boundary. Prefer the config path for new code;
+ * see the package README.
+ */
+interface CursorAgentServiceShape {
+  readonly create: (options: AgentOptions) => Effect.Effect<SDKAgent, CursorAuthenticationError | CursorRateLimitError | CursorIntegrationNotConnectedError | CursorConfigurationError | CursorNetworkError | CursorUnknownError>;
+  readonly resume: (agentId: string, options?: Partial<AgentOptions>) => Effect.Effect<SDKAgent, CursorAuthenticationError | CursorRateLimitError | CursorIntegrationNotConnectedError | CursorConfigurationError | CursorNetworkError | CursorUnknownError>;
+  readonly prompt: (message: string, options?: AgentOptions) => Effect.Effect<RunResult, CursorAuthenticationError | CursorRateLimitError | CursorIntegrationNotConnectedError | CursorConfigurationError | CursorNetworkError | CursorUnknownError>;
+  readonly send: (agent: SDKAgent, message: string | SDKUserMessage, options?: SendOptions) => Effect.Effect<Run, CursorAuthenticationError | CursorRateLimitError | CursorIntegrationNotConnectedError | CursorConfigurationError | CursorNetworkError | CursorUnknownError>;
+  readonly reload: (agent: SDKAgent) => Effect.Effect<void, CursorAuthenticationError | CursorRateLimitError | CursorIntegrationNotConnectedError | CursorConfigurationError | CursorNetworkError | CursorUnknownError>;
+  readonly close: (agent: SDKAgent) => Effect.Effect<void>;
+  readonly dispose: (agent: SDKAgent) => Effect.Effect<void, CursorAuthenticationError | CursorRateLimitError | CursorIntegrationNotConnectedError | CursorConfigurationError | CursorNetworkError | CursorUnknownError>;
+  readonly scoped: (options: AgentOptions) => Effect.Effect<SDKAgent, CursorAuthenticationError | CursorRateLimitError | CursorIntegrationNotConnectedError | CursorConfigurationError | CursorNetworkError | CursorUnknownError, Scope.Scope>;
+}
+declare const CursorAgentService_base: Context.ServiceClass<CursorAgentService, "effect-cursor-sdk/cursor-agent/CursorAgentService", CursorAgentServiceShape>;
+/**
+ * Effect-native agent lifecycle and prompt service.
+ *
+ * The service wraps `Agent.create`, `Agent.resume`, `Agent.prompt`, and
+ * instance lifecycle methods while preserving SDK-owned option and result
+ * types.
+ *
+ * @example
+ * ```ts
+ * import { CursorAgentService, liveLayer } from "effect-cursor-sdk"
+ * import { Effect } from "effect"
+ *
+ * const program = Effect.gen(function*() {
+ *   const agents = yield* CursorAgentService
+ *   const agent = yield* agents.create({ model: { id: "composer-2" }, local: { cwd: process.cwd() } })
+ *   return yield* agents.send(agent, "Summarize this repository")
+ * }).pipe(Effect.provide(liveLayer))
+ * ```
+ *
+ * @see {@link CursorRunService} for operations on returned `Run` handles.
+ * @see {@link CursorSdkFactory} for replacing SDK construction in tests.
+ *
+ * @remarks
+ * Inherits the **API boundary notice** on {@link CursorAgentServiceShape} about
+ * a possible future switch from raw {@link AgentOptions} to
+ * {@link loadCursorConfig} / {@link agentOptionsFromConfig}.
+ *
+ * @category services
+ */
+declare class CursorAgentService extends CursorAgentService_base {
+  static readonly Live: Layer.Layer<CursorAgentService, never, CursorSdkFactory>;
+}
+//#endregion
+//#region src/cursor-artifacts.d.ts
+interface CursorArtifactServiceShape {
+  readonly listArtifacts: (agent: SDKAgent) => Effect.Effect<SDKArtifact[], CursorAuthenticationError | CursorRateLimitError | CursorIntegrationNotConnectedError | CursorConfigurationError | CursorNetworkError | CursorUnknownError>;
+  readonly downloadArtifact: (agent: SDKAgent, path: string) => Effect.Effect<Buffer, CursorAuthenticationError | CursorRateLimitError | CursorIntegrationNotConnectedError | CursorConfigurationError | CursorNetworkError | CursorUnknownError>;
+}
+declare const CursorArtifactService_base: Context.ServiceClass<CursorArtifactService, "effect-cursor-sdk/cursor-artifacts/CursorArtifactService", CursorArtifactServiceShape>;
+/**
+ * Effect-native wrappers for agent artifacts.
+ *
+ * @example
+ * ```ts
+ * const artifacts = yield* CursorArtifactService
+ * const items = yield* artifacts.listArtifacts(agent)
+ * const bytes = yield* artifacts.downloadArtifact(agent, items[0]!.path)
+ * ```
+ *
+ * @see {@link SDKArtifact}
+ *
+ * @category services
+ */
+declare class CursorArtifactService extends CursorArtifactService_base {
+  static readonly Live: Layer.Layer<CursorArtifactService, never, never>;
+}
+//#endregion
+//#region src/cursor-config.d.ts
+/**
+ * Branded secret material for the Cursor API key.
+ *
+ * Values are held inside {@link Redacted} on {@link CursorConfig}; this schema
+ * only brands the decoded plaintext type so it cannot be confused with other
+ * strings at the type level.
+ */
+declare const CursorApiKey: Schema.brand<Schema.Redacted<Schema.String>, "CursorApiKey">;
+type CursorApiKey = typeof CursorApiKey.Type;
+/**
+ * Branded model identifier from wrapper config.
+ *
+ * Populated from the `CURSOR_MODEL` environment variable when using
+ * {@link loadCursorConfig}.
+ */
+declare const CursorModelId: Schema.brand<Schema.String, "CursorModelId">;
+type CursorModelId = typeof CursorModelId.Type;
+/**
+ * Branded local working directory for agent runs.
+ *
+ * Populated from `CURSOR_LOCAL_CWD` when using {@link loadCursorConfig}.
+ */
+declare const CursorLocalCwd: Schema.brand<Schema.String, "CursorLocalCwd">;
+type CursorLocalCwd = typeof CursorLocalCwd.Type;
+declare const CursorConfig_base: Schema.Class<CursorConfig, Schema.Struct<{
+  readonly apiKey: Schema.optional<Schema.brand<Schema.Redacted<Schema.String>, "CursorApiKey">>;
+  readonly modelId: Schema.optional<Schema.brand<Schema.String, "CursorModelId">>;
+  readonly cwd: Schema.optional<Schema.brand<Schema.String, "CursorLocalCwd">>;
+}>, {}>;
+/**
+ * Minimal configuration owned by this wrapper.
+ *
+ * The SDK's `AgentOptions` type remains the source of truth for complete
+ * runtime options. This schema only models environment-derived defaults.
+ * Use {@link agentOptionsFromConfig} to merge those defaults into SDK-owned
+ * {@link AgentOptions}.
+ *
+ * @remarks
+ * **Forward path:** A future major version of this package may require all
+ * agent-related options to be supplied through this module (for example
+ * {@link loadCursorConfig} plus {@link agentOptionsFromConfig}) instead of raw
+ * {@link AgentOptions} on {@link CursorAgentService}.
+ * Prefer this path for new code.
+ *
+ * @example
+ * ```ts
+ * const config = new CursorConfig({
+ *   apiKey: Redacted.make(CursorApiKey.make(process.env.CURSOR_API_KEY!)),
+ *   modelId: CursorModelId.make("composer-2"),
+ *   cwd: CursorLocalCwd.make(process.cwd())
+ * })
+ * ```
+ *
+ * @see {@link cursorConfig}
+ * @see {@link loadCursorConfig}
+ *
+ * @category config
+ */
+declare class CursorConfig extends CursorConfig_base {}
+/**
+ * Effect Config descriptors for common Cursor environment variables.
+ *
+ * Reads `CURSOR_API_KEY`, `CURSOR_MODEL`, and `CURSOR_LOCAL_CWD` from the active
+ * Effect {@link ConfigProvider.ConfigProvider}. All fields are optional so
+ * callers can still pass complete SDK options explicitly.
+ *
+ * @example
+ * ```ts
+ * const config = yield* loadCursorConfig
+ * const options = agentOptionsFromConfig(config)
+ * ```
+ *
+ * @see {@link Config}
+ * @see {@link loadCursorConfig}
+ *
+ * @category config
+ */
+declare const cursorConfig: Config.Config<{
+  apiKey: Option.Option<Redacted.Redacted<string>>;
+  modelId: Option.Option<string>;
+  cwd: Option.Option<string>;
+}>;
+/**
+ * Build SDK `AgentOptions` from wrapper config and optional overrides.
+ *
+ * Explicit override values always win over environment-derived defaults.
+ *
+ * @param config - Wrapper-owned environment defaults.
+ * @param overrides - Complete or partial SDK-owned options to merge over the defaults.
+ *
+ * @example
+ * ```ts
+ * const options = agentOptionsFromConfig(config, {
+ *   cloud: {
+ *     repos: [{ url: "https://github.com/acme/app" }],
+ *     autoCreatePR: true
+ *   }
+ * })
+ * ```
+ *
+ * @see {@link CursorConfig}
+ * @see {@link AgentOptions}
+ *
+ * @remarks
+ * Same **forward path** notice as {@link CursorConfig}: this merge is the
+ * intended boundary for redacted keys and env defaults ahead of a possible
+ * requirement to use it for all agent entry points.
+ *
+ * @category config
+ */
+declare const agentOptionsFromConfig: (config: CursorConfig, overrides?: AgentOptions) => AgentOptions;
+/**
+ * Load environment-derived defaults as a schema-backed value.
+ *
+ * @example
+ * ```ts
+ * const config = yield* loadCursorConfig
+ * const options = agentOptionsFromConfig(config, { local: { cwd: process.cwd() } })
+ * ```
+ *
+ * @see {@link cursorConfig}
+ * @see {@link agentOptionsFromConfig}
+ *
+ * @remarks
+ * Same **forward path** notice as {@link CursorConfig}: this effect is the
+ * intended entry for redacted env defaults ahead of a possible requirement to
+ * use it (with {@link agentOptionsFromConfig}) for all agent entry points.
+ *
+ * @category config
+ */
+declare const loadCursorConfig: Effect.Effect<CursorConfig, Config.ConfigError, never>;
+//#endregion
+//#region src/cursor-inspection.d.ts
+interface CursorInspectionServiceShape {
+  readonly listAgents: (options?: ListAgentsOptions) => Effect.Effect<ListResult<SDKAgentInfo>, CursorAuthenticationError | CursorRateLimitError | CursorIntegrationNotConnectedError | CursorConfigurationError | CursorNetworkError | CursorUnknownError>;
+  readonly getAgent: (agentId: string, options?: GetAgentOptions) => Effect.Effect<SDKAgentInfo, CursorAuthenticationError | CursorRateLimitError | CursorIntegrationNotConnectedError | CursorConfigurationError | CursorNetworkError | CursorUnknownError>;
+  readonly archiveAgent: (agentId: string, options?: AgentOperationOptions) => Effect.Effect<void, CursorAuthenticationError | CursorRateLimitError | CursorIntegrationNotConnectedError | CursorConfigurationError | CursorNetworkError | CursorUnknownError>;
+  readonly unarchiveAgent: (agentId: string, options?: AgentOperationOptions) => Effect.Effect<void, CursorAuthenticationError | CursorRateLimitError | CursorIntegrationNotConnectedError | CursorConfigurationError | CursorNetworkError | CursorUnknownError>;
+  readonly deleteAgent: (agentId: string, options?: AgentOperationOptions) => Effect.Effect<void, CursorAuthenticationError | CursorRateLimitError | CursorIntegrationNotConnectedError | CursorConfigurationError | CursorNetworkError | CursorUnknownError>;
+  readonly listRuns: (agentId: string, options?: ListRunsOptions) => Effect.Effect<ListResult<Run>, CursorAuthenticationError | CursorRateLimitError | CursorIntegrationNotConnectedError | CursorConfigurationError | CursorNetworkError | CursorUnknownError>;
+  readonly getRun: (runId: string, options?: GetRunOptions) => Effect.Effect<Run, CursorAuthenticationError | CursorRateLimitError | CursorIntegrationNotConnectedError | CursorConfigurationError | CursorNetworkError | CursorUnknownError>;
+  readonly listMessages: (agentId: string, options?: GetAgentMessagesOptions) => Effect.Effect<AgentMessage[], CursorAuthenticationError | CursorRateLimitError | CursorIntegrationNotConnectedError | CursorConfigurationError | CursorNetworkError | CursorUnknownError>;
+  readonly me: (options?: CursorRequestOptions) => Effect.Effect<SDKUser, CursorAuthenticationError | CursorRateLimitError | CursorIntegrationNotConnectedError | CursorConfigurationError | CursorNetworkError | CursorUnknownError>;
+  readonly listModels: (options?: CursorRequestOptions) => Effect.Effect<SDKModel[], CursorAuthenticationError | CursorRateLimitError | CursorIntegrationNotConnectedError | CursorConfigurationError | CursorNetworkError | CursorUnknownError>;
+  readonly listRepositories: (options?: CursorRequestOptions) => Effect.Effect<SDKRepository[], CursorAuthenticationError | CursorRateLimitError | CursorIntegrationNotConnectedError | CursorConfigurationError | CursorNetworkError | CursorUnknownError>;
+}
+declare const CursorInspectionService_base: Context.ServiceClass<CursorInspectionService, "effect-cursor-sdk/cursor-inspection/CursorInspectionService", CursorInspectionServiceShape>;
+/**
+ * Effect-native wrappers for SDK inspection, lifecycle, and account catalog APIs.
+ *
+ * @example
+ * ```ts
+ * const inspection = yield* CursorInspectionService
+ * const agents = yield* inspection.listAgents({ runtime: "cloud", includeArchived: true })
+ * const models = yield* inspection.listModels()
+ * ```
+ *
+ * @see {@link CursorSdkFactory}
+ * @see {@link SDKAgentInfo}
+ *
+ * @category services
+ */
+declare class CursorInspectionService extends CursorInspectionService_base {
+  static readonly Live: Layer.Layer<CursorInspectionService, never, CursorSdkFactory>;
+}
+//#endregion
+//#region src/cursor-mock.d.ts
+/**
+ * Fixture data used by the deterministic mock SDK layer.
+ *
+ * @example
+ * ```ts
+ * const fixtures: CursorMockFixtures = {
+ *   stream: [assistantEvent],
+ *   result: { id: "run-1", status: "finished", result: "Done" }
+ * }
+ * ```
+ *
+ * @see {@link mockLayer}
+ * @see {@link makeMockSdkFactoryLayer}
+ * @category testing
+ */
+interface CursorMockFixtures {
+  readonly agentId?: string;
+  readonly runId?: string;
+  readonly stream?: ReadonlyArray<SDKMessage>;
+  readonly result?: RunResult;
+  readonly artifacts?: ReadonlyArray<SDKArtifact>;
+  readonly artifactData?: Buffer;
+  readonly agents?: ReadonlyArray<SDKAgentInfo>;
+  readonly messages?: ReadonlyArray<AgentMessage>;
+  readonly models?: ReadonlyArray<SDKModel>;
+  readonly repositories?: ReadonlyArray<SDKRepository>;
+  readonly user?: SDKUser;
+}
+/**
+ * Deterministic SDK `Run` implementation for tests.
+ *
+ * @param streamEvents - Events yielded by {@link MockCursorRun.stream}.
+ * @param waitResult - Result returned by {@link MockCursorRun.wait}.
+ *
+ * @example
+ * ```ts
+ * const run = new MockCursorRun([assistantEvent], {
+ *   id: "run-1",
+ *   status: "finished",
+ *   result: "Done"
+ * })
+ * ```
+ *
+ * @see {@link makeMockRun}
+ * @category testing
+ */
+declare class MockCursorRun implements Run {
+  #private;
+  readonly streamEvents: ReadonlyArray<SDKMessage>;
+  readonly waitResult: RunResult;
+  readonly id: string;
+  readonly agentId: string;
+  readonly createdAt: number;
+  constructor(streamEvents: ReadonlyArray<SDKMessage>, waitResult: RunResult);
+  get status(): RunStatus;
+  get result(): string | undefined;
+  get model(): RunResult["model"];
+  get durationMs(): number | undefined;
+  get git(): RunResult["git"];
+  supports(_operation: RunOperation): boolean;
+  unsupportedReason(_operation: RunOperation): string | undefined;
+  stream(): AsyncGenerator<SDKMessage, void>;
+  conversation(): Promise<[]>;
+  wait(): Promise<RunResult>;
+  cancel(): Promise<void>;
+  onDidChangeStatus(listener: (status: RunStatus) => void): () => void;
+}
+/**
+ * Deterministic SDK `Agent` implementation for tests.
+ *
+ * @param fixtures - Static data used by `send`, artifact methods, and metadata methods.
+ *
+ * @example
+ * ```ts
+ * const agent = new MockCursorAgent({ result: { id: "run-1", status: "finished" } })
+ * const run = await agent.send("hello")
+ * ```
+ *
+ * @see {@link makeMockAgent}
+ * @see {@link CursorMockFixtures}
+ * @category testing
+ */
+declare class MockCursorAgent implements SDKAgent {
+  readonly fixtures: CursorMockFixtures;
+  readonly agentId: string;
+  readonly runs: Run[];
+  closed: boolean;
+  constructor(fixtures?: CursorMockFixtures);
+  get model(): AgentOptions["model"] | undefined;
+  send(_message: string | SDKUserMessage, _options?: SendOptions): Promise<Run>;
+  close(): void;
+  reload(): Promise<void>;
+  [Symbol.asyncDispose](): Promise<void>;
+  listArtifacts(): Promise<SDKArtifact[]>;
+  downloadArtifact(_path: string): Promise<Buffer>;
+}
+/**
+ * Create a mock run from fixtures.
+ *
+ * @param fixtures - Optional mock run and stream data.
+ *
+ * @see {@link MockCursorRun}
+ * @category testing
+ */
+declare const makeMockRun: (fixtures?: CursorMockFixtures) => MockCursorRun;
+/**
+ * Create a mock agent from fixtures.
+ *
+ * @param fixtures - Optional mock agent, run, artifact, and metadata data.
+ *
+ * @see {@link MockCursorAgent}
+ * @category testing
+ */
+declare const makeMockAgent: (fixtures?: CursorMockFixtures) => MockCursorAgent;
+/**
+ * Layer replacing the SDK factory with deterministic mock behavior.
+ *
+ * This is the lowest-level mock entry point. Prefer {@link mockLayer} when you
+ * want all higher-level services wired together for tests.
+ *
+ * @param fixtures - Static SDK responses returned by the factory methods.
+ *
+ * @example
+ * ```ts
+ * const layer = makeMockSdkFactoryLayer({
+ *   agents: [{ agentId: "mock-agent", name: "Mock", summary: "Test", lastModified: 0 }]
+ * })
+ * ```
+ *
+ * @see {@link CursorSdkFactory}
+ * @see {@link mockLayer}
+ * @category testing
+ */
+declare const makeMockSdkFactoryLayer: (fixtures?: CursorMockFixtures) => Layer.Layer<CursorSdkFactory, never, never>;
+//#endregion
+//#region src/cursor-run.d.ts
+interface CursorRunServiceShape {
+  readonly supports: (run: Run, operation: RunOperation) => boolean;
+  readonly unsupportedReason: (run: Run, operation: RunOperation) => string | undefined;
+  readonly wait: (run: Run) => Effect.Effect<RunResult, CursorAuthenticationError | CursorRateLimitError | CursorIntegrationNotConnectedError | CursorConfigurationError | CursorNetworkError | CursorUnknownError>;
+  readonly cancel: (run: Run) => Effect.Effect<void, CursorAuthenticationError | CursorRateLimitError | CursorIntegrationNotConnectedError | CursorConfigurationError | CursorNetworkError | CursorUnsupportedOperationError | CursorUnknownError>;
+  readonly conversation: (run: Run) => ReturnType<Run["conversation"]> extends Promise<infer A> ? Effect.Effect<A, CursorAuthenticationError | CursorRateLimitError | CursorIntegrationNotConnectedError | CursorConfigurationError | CursorNetworkError | CursorUnsupportedOperationError | CursorUnknownError> : never;
+  readonly streamEvents: (run: Run) => Stream.Stream<SDKMessage, CursorStreamError>;
+  readonly collectText: (run: Run) => Effect.Effect<string, CursorStreamError>;
+  readonly onDidChangeStatus: (run: Run, listener: (status: RunStatus) => void) => Effect.Effect<() => void>;
+}
+declare const CursorRunService_base: Context.ServiceClass<CursorRunService, "effect-cursor-sdk/cursor-run/CursorRunService", CursorRunServiceShape>;
+/**
+ * Effect-native helpers for SDK run handles.
+ *
+ * @example
+ * ```ts
+ * const run = yield* agents.send(agent, "Refactor auth")
+ * const text = yield* runs.collectText(run)
+ * ```
+ *
+ * @see {@link CursorAgentService} for creating and sending runs.
+ * @see {@link SDKMessage} for the SDK-owned stream event shape.
+ *
+ * @category services
+ */
+declare class CursorRunService extends CursorRunService_base {
+  static readonly Live: Layer.Layer<CursorRunService, never, never>;
+}
+//#endregion
+//#region src/cursor-runtime.d.ts
+/**
+ * Live service layer for the SDK-backed Effect wrapper.
+ *
+ * Provides {@link CursorAgentService}, {@link CursorRunService},
+ * {@link CursorArtifactService}, and {@link CursorInspectionService} using
+ * {@link CursorSdkFactory.Live}.
+ *
+ * @example
+ * ```ts
+ * const result = yield* program.pipe(Effect.provide(liveLayer))
+ * ```
+ *
+ * @see {@link CursorSdkFactory}
+ * @see {@link liveRuntime}
+ *
+ * @category layers
+ */
+declare const liveLayer: Layer.Layer<CursorAgentService | CursorSdkFactory | CursorArtifactService | CursorRunService | CursorInspectionService, never, never>;
+/**
+ * Deterministic mock layer for tests and examples.
+ *
+ * @param fixtures - Static SDK responses returned by the mock factory.
+ *
+ * @example
+ * ```ts
+ * const layer = mockLayer({
+ *   result: { id: "run-1", status: "finished", result: "ok" }
+ * })
+ * ```
+ *
+ * @see {@link CursorMockFixtures}
+ * @see {@link makeMockSdkFactoryLayer}
+ *
+ * @category layers
+ */
+declare const mockLayer: (fixtures?: CursorMockFixtures) => Layer.Layer<CursorAgentService | CursorSdkFactory | CursorArtifactService | CursorRunService | CursorInspectionService, never, never>;
+/**
+ * Ready-made live runtime.
+ *
+ * Use this for small scripts that prefer `ManagedRuntime.runPromise` over
+ * manually providing {@link liveLayer}.
+ *
+ * @example
+ * ```ts
+ * const value = await liveRuntime.runPromise(program)
+ * ```
+ *
+ * @see {@link liveLayer}
+ *
+ * @category runtimes
+ */
+declare const liveRuntime: ManagedRuntime.ManagedRuntime<CursorAgentService | CursorSdkFactory | CursorArtifactService | CursorRunService | CursorInspectionService, never>;
+/**
+ * Ready-made mock runtime.
+ *
+ * @param fixtures - Static SDK responses returned by the mock services.
+ *
+ * @example
+ * ```ts
+ * const runtime = makeMockRuntime({ result: { id: "run-1", status: "finished" } })
+ * const value = await runtime.runPromise(program)
+ * ```
+ *
+ * @see {@link mockLayer}
+ * @see {@link CursorMockFixtures}
+ *
+ * @category runtimes
+ */
+declare const makeMockRuntime: (fixtures?: CursorMockFixtures) => ManagedRuntime.ManagedRuntime<CursorAgentService | CursorSdkFactory | CursorArtifactService | CursorRunService | CursorInspectionService, never>;
+//#endregion
+//#region src/cursor-telemetry.d.ts
+/**
+ * Increments once when an instrumented SDK effect **starts** execution.
+ *
+ * Bound to the metric key `cursor_operations_started`. Used by
+ * {@link instrument} on every wrapped call; pair with
+ * {@link cursorOperationsFailed} to compute failure rates per operation when
+ * both counters are exported to your metrics stack.
+ *
+ * @see {@link instrument}
+ * @see {@link cursorOperationsFailed}
+ *
+ * @category telemetry
+ */
+declare const cursorOperationsStarted: Metric.Counter<number>;
+/**
+ * Increments once when an instrumented SDK effect **fails** (any error channel
+ * value), after {@link cursorOperationsStarted} has already been recorded for
+ * that run.
+ *
+ * Bound to the metric key `cursor_operations_failed`. Failures are tracked in
+ * `Effect.tapError` so the effect still fails with the original error; this
+ * counter is observability-only.
+ *
+ * @see {@link instrument}
+ * @see {@link cursorOperationsStarted}
+ *
+ * @category telemetry
+ */
+declare const cursorOperationsFailed: Metric.Counter<number>;
+/**
+ * Counter reserved for **per-message** or **per-chunk** stream throughput.
+ *
+ * Bound to the metric key `cursor_stream_events`. The service wrappers do not
+ * attach this metric automatically to {@link CursorRunService.streamEvents};
+ * export it from your app if you want to `Metric.track` inside a
+ * `Stream.tapEffect` (or similar) when consuming SDK stream payloads.
+ *
+ * @see {@link CursorRunService}
+ *
+ * @category telemetry
+ */
+declare const cursorStreamEvents: Metric.Counter<number>;
+/**
+ * Deep-clones **plain** objects and arrays while replacing values under keys that
+ * often carry secrets, bearer material, or large opaque blobs (for example API
+ * keys, tokens, passwords, cookies, `Authorization`, or a generic `data` field).
+ *
+ * Matching is **substring-based on the lower-cased key name** (for example
+ * `apiKey`, `CURSOR_API_TOKEN`, `client_secret`, `setCookie` all match). Primitives
+ * and `null` pass through unchanged. Non-plain objects (for example `Date`, `Map`,
+ * class instances) are replaced by `"[opaque]"` so they are not serialized as empty
+ * objects. True circular references in the input are replaced by `"[circular]"`.
+ * Recursion deeper than 64 levels falls back to `"[opaque]"` for the overflow branch.
+ *
+ * This is a best-effort redactor for logs and attributes—not a cryptographic
+ * guarantee; do not rely on it for compliance redaction without review.
+ *
+ * @param value - Arbitrary JSON-like value to sanitize.
+ * @returns A structure of the same shape with sensitive-looking entries replaced
+ *   by the string `"[redacted]"`.
+ *
+ * @example
+ * ```ts
+ * redact({ apiKey: "secret", nested: { token: "x" }, safe: 1 })
+ * // => { apiKey: "[redacted]", nested: { token: "[redacted]" }, safe: 1 }
+ * ```
+ *
+ * @category telemetry
+ */
+declare const redact: (value: unknown) => unknown;
+/**
+ * Wraps an SDK-backed {@link Effect.Effect | Effect} with consistent
+ * observability: increments {@link cursorOperationsStarted} at execution start,
+ * increments {@link cursorOperationsFailed} on the error channel, and attaches
+ * a span named `cursor.<operation>` (for example `cursor.agent.list`).
+ *
+ * The span name is stable and includes the {@link CursorOperation} tag space
+ * so traces can be filtered consistently across agent, run, artifact, and
+ * inspection APIs.
+ *
+ * @param operation - Logical SDK operation; must match {@link CursorOperation}
+ *   for typed error mapping and trace taxonomy.
+ * @param effect - The effect produced by `Effect.tryPromise` (or similar)
+ *   around a single SDK call.
+ * @returns The same effect type `Effect<A, E, R>` with metrics and span
+ *   attached; success and failure values are unchanged.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { instrument } from "./cursor-telemetry"
+ *
+ * const eff = instrument(
+ *   "agent.get",
+ *   Effect.tryPromise({
+ *     try: () => sdk.getAgent(id),
+ *     catch: (e) => e,
+ *   }),
+ * )
+ * ```
+ *
+ * @see {@link cursorOperationsStarted}
+ * @see {@link cursorOperationsFailed}
+ * @see {@link CursorOperation}
+ *
+ * @category telemetry
+ */
+declare const instrument: <A, E, R>(operation: CursorOperation, effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+//#endregion
+//#region src/index.d.ts
+/**
+ * Public package name.
+ *
+ * @category metadata
+ */
+declare const packageName = "effect-cursor-sdk";
+//#endregion
+export { type AgentDefinition, type AgentMessage, type AgentOperationOptions, type AgentOptions, AuthenticationError, ConfigurationError, CursorAgentError, CursorAgentPlatform, CursorAgentService, CursorAgentServiceShape, CursorApiKey, CursorArtifactService, CursorArtifactServiceShape, CursorAuthenticationError, CursorConfig, CursorConfigurationError, CursorErrorContext, CursorInspectionService, CursorInspectionServiceShape, CursorIntegrationNotConnectedError, CursorLocalCwd, CursorMockFixtures, CursorModelId, CursorNetworkError, CursorOperation, CursorRateLimitError, type CursorRequestOptions, CursorRunFailedError, CursorRunService, CursorRunServiceShape, CursorSdkFactory, CursorSdkFactoryShape, CursorStreamError, CursorUnknownError, CursorUnsupportedOperationError, type GetAgentMessagesOptions, type GetAgentOptions, type GetRunOptions, IntegrationNotConnectedError, type ListAgentsOptions, type ListResult, type ListRunsOptions, type McpServerConfig, MockCursorAgent, MockCursorRun, type ModelListItem, type ModelParameterDefinition, type ModelParameterValue, type ModelSelection, type ModelVariant, NetworkError, RateLimitError, type Run, type RunOperation, type RunResult, type RunResultStatus, type RunStatus, type SDKAgent, type SDKAgentInfo, type SDKArtifact, type SDKAssistantMessage, type SDKImage, type SDKImageDimension, type SDKMessage, type SDKModel, type SDKRepository, type SDKStatusMessage, type SDKSystemMessage, type SDKTaskMessage, type SDKThinkingMessage, type SDKToolUseMessage, type SDKUser, type SDKUserMessage, type SDKUserMessageEvent, type SendOptions, type SettingSource, type TextBlock, type ToolUseBlock, UnknownAgentError, UnsupportedRunOperationError, agentOptionsFromConfig, createAgentPlatform, createInMemoryRunEventNotifier, createLocalRunEventNotifier, createSdkMessageRunStreamEvent, cursorConfig, cursorOperationsFailed, cursorOperationsStarted, cursorStreamEvents, decodeLocalRunStreamEvent, decodeSdkMessageRunStreamEvent, getTurnType, instrument, isTerminalLocalRunStreamEvent, liveLayer, liveRuntime, loadCursorConfig, localRunStreamEventToSdkMessage, makeMockAgent, makeMockRun, makeMockRuntime, makeMockSdkFactoryLayer, mapCursorError, mockLayer, packageName, redact, startLocalRunEventNotifierServer };
+//# sourceMappingURL=index.d.ts.map