effect-cursor-sdk 0.1.1 → 0.2.1

package/dist/index.js

@@ -109,6 +109,184 @@ function mapCursorError(cause, context) {
 	}));
 }
 //#endregion
+//#region src/cursor-config.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.
+*/
+const CursorApiKey = Schema.Redacted(Schema.String).pipe(Schema.brand("CursorApiKey"));
+/**
+* Branded model identifier from wrapper config.
+*
+* Populated from the `CURSOR_MODEL` environment variable when using
+* {@link loadCursorConfig}.
+*/
+const CursorModelId = Schema.String.pipe(Schema.brand("CursorModelId"));
+/**
+* Branded local working directory for agent runs.
+*
+* Populated from `CURSOR_LOCAL_CWD` when using {@link loadCursorConfig}.
+*/
+const CursorLocalCwd = Schema.String.pipe(Schema.brand("CursorLocalCwd"));
+/**
+* Minimal configuration owned by this wrapper.
+*
+* The SDK's `AgentOptions` type remains the source of truth for complete
+* runtime options. This schema models environment-derived defaults only.
+* Use {@link agentOptionsFromConfig} to merge those defaults into SDK-owned
+* {@link AgentOptions} at the SDK boundary.
+*
+* @remarks
+* **Preferred path:** Load defaults with {@link loadCursorConfig}, then call
+* `CursorAgentService` methods such as `createFromConfig` (and related helpers)
+* or merge manually with {@link agentOptionsFromConfig}. Passing plain
+* {@link AgentOptions} directly to deprecated `create` / `resume` / `prompt` /
+* `scoped` overloads may be removed in a future major version.
+*
+* @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
+*/
+var CursorConfig = class extends Schema.Class("CursorConfig")({
+	apiKey: Schema.optional(CursorApiKey),
+	modelId: Schema.optional(CursorModelId),
+	cwd: Schema.optional(CursorLocalCwd)
+}) {};
+/**
+* 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 merge with explicit overrides via {@link agentOptionsFromConfig}.
+*
+* @example
+* ```ts
+* const config = yield* loadCursorConfig
+* const options = agentOptionsFromConfig(config)
+* ```
+*
+* @see {@link Config}
+* @see {@link loadCursorConfig}
+*
+* @category config
+*/
+const cursorConfig = Config.all({
+	apiKey: Config.redacted("CURSOR_API_KEY").pipe(Config.option),
+	modelId: Config.string("CURSOR_MODEL").pipe(Config.option),
+	cwd: Config.string("CURSOR_LOCAL_CWD").pipe(Config.option)
+});
+/**
+* Build SDK `AgentOptions` from wrapper config and optional overrides.
+*
+* This is the adapter from typed, redacted {@link CursorConfig} to the SDK's
+* plain-string `apiKey` boundary. Prefer `CursorAgentService.createFromConfig`
+* (and related methods) over building {@link AgentOptions} by hand.
+*
+* @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
+* Explicit override values always win over environment-derived defaults.
+* For application code, prefer service methods that take {@link CursorConfig}
+* instead of calling this helper and then the deprecated `create` overload.
+*
+* @category config
+*/
+const agentOptionsFromConfig = (config, overrides = {}) => {
+	const model = overrides.model ?? (config.modelId ? { id: config.modelId } : void 0);
+	const hasNonEmptyLocalOverride = overrides.local !== void 0 && Object.keys(overrides.local).length > 0;
+	const local = config.cwd || hasNonEmptyLocalOverride ? {
+		cwd: config.cwd,
+		...overrides.local
+	} : void 0;
+	return {
+		...overrides,
+		apiKey: overrides.apiKey ?? (config.apiKey ? Redacted.value(config.apiKey) : void 0),
+		model,
+		local
+	};
+};
+/**
+* Load environment-derived defaults as a schema-backed value.
+* It uses ConfigProvider to load the environment variables
+* with their default names (`CURSOR_API_KEY`, `CURSOR_MODEL`, `CURSOR_LOCAL_CWD`)
+* from {@link cursorConfig}.
+*
+* @example
+* ```ts
+* const config = yield* loadCursorConfig
+* const options = agentOptionsFromConfig(config, { local: { cwd: process.cwd() } })
+* // Or use CursorAgentService.createFromConfig(config, { local: { cwd: process.cwd() } })
+* ```
+*
+* To change the way that the environment variables are loaded,
+* you can do it with Effect by providing a custom ConfigProvider.
+*
+* ```ts
+* // For example: load via custom environment object
+* const config = yield* loadCursorConfig.pipe(
+*  Effect.provideService(
+*    ConfigProvider.ConfigProvider,
+*    ConfigProvider.fromEnv({
+*      env: {
+*        CURSOR_API_KEY: "crsr_******",
+*        CURSOR_MODEL: "composer-2",
+*        CURSOR_LOCAL_CWD: "/workspace",
+*      },
+*    }),
+*  ),
+* )
+* ```
+*
+* @see {@link cursorConfig}
+* @see {@link agentOptionsFromConfig}
+*
+* @remarks
+* This effect is the preferred entry for redacted environment defaults.
+* Pair it with {@link agentOptionsFromConfig} or `CursorAgentService` helpers
+* such as `createFromConfig`.
+*
+* @category config
+*/
+const loadCursorConfig = Effect.gen(function* () {
+	const provider = yield* ConfigProvider.ConfigProvider;
+	const raw = yield* cursorConfig.parse(provider);
+	const apiKey = Option.getOrUndefined(raw.apiKey);
+	const modelId = Option.getOrUndefined(raw.modelId);
+	const cwd = Option.getOrUndefined(raw.cwd);
+	return new CursorConfig({
+		apiKey: apiKey ? CursorApiKey.make(apiKey) : void 0,
+		modelId: modelId !== void 0 ? CursorModelId.make(modelId) : void 0,
+		cwd: cwd !== void 0 ? CursorLocalCwd.make(cwd) : void 0
+	});
+});
+//#endregion
 //#region src/cursor-sdk-factory.ts
 /**
 * Context service that provides the live `@cursor/sdk` static API boundary.
@@ -118,9 +296,13 @@ function mapCursorError(cause, context) {
 *
 * @example
 * ```ts
+* import { CursorSdkFactory, agentOptionsFromConfig, loadCursorConfig } from "effect-cursor-sdk"
+* import { Effect } from "effect"
+*
 * const program = Effect.gen(function*() {
 *   const sdk = yield* CursorSdkFactory
-*   return sdk.create({ model: { id: "composer-2" }, local: { cwd: process.cwd() } })
+*   const config = yield* loadCursorConfig
+*   return sdk.create(agentOptionsFromConfig(config, { model: { id: "composer-2" } }))
 * })
 * ```
 *
@@ -363,12 +545,16 @@ const instrument = (operation, effect) => {
 *
 * @example
 * ```ts
-* import { CursorAgentService, liveLayer } from "effect-cursor-sdk"
+* import { CursorAgentService, liveLayer, loadCursorConfig } 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() } })
+*   const config = yield* loadCursorConfig
+*   const agent = yield* agents.createFromConfig(config, {
+*     model: { id: "composer-2" },
+*     local: { cwd: process.cwd() },
+*   })
 *   return yield* agents.send(agent, "Summarize this repository")
 * }).pipe(Effect.provide(liveLayer))
 * ```
@@ -377,9 +563,11 @@ const instrument = (operation, effect) => {
 * @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}.
+* Prefer {@link CursorAgentServiceShape.createFromConfig} and related methods
+* with {@link loadCursorConfig}; raw {@link AgentOptions} on
+* {@link CursorAgentServiceShape.create} and siblings are deprecated.
+* See `DEPRECATIONS.md` at the package root for migration and planned next-major renames
+* (`createFromConfig` → `create`, etc.).
 *
 * @category services
 */
@@ -454,15 +642,31 @@ var CursorAgentService = class CursorAgentService extends Context.Service()("eff
 				return Effect.ignore(dispose(agent));
 			});
 		};
+		const createFromConfig = (config, overrides = {}) => {
+			return create(agentOptionsFromConfig(config, overrides));
+		};
+		const resumeFromConfig = (agentId, config, overrides = {}) => {
+			return resume(agentId, agentOptionsFromConfig(config, overrides));
+		};
+		const promptFromConfig = (message, config, overrides = {}) => {
+			return prompt(message, agentOptionsFromConfig(config, overrides));
+		};
+		const scopedFromConfig = (config, overrides = {}) => {
+			return scoped(agentOptionsFromConfig(config, overrides));
+		};
 		return {
 			create,
+			createFromConfig,
 			resume,
+			resumeFromConfig,
 			prompt,
+			promptFromConfig,
 			send,
 			reload,
 			close,
 			dispose,
-			scoped
+			scoped,
+			scopedFromConfig
 		};
 	}));
 };
@@ -509,157 +713,6 @@ var CursorArtifactService = class CursorArtifactService extends Context.Service(
 	}));
 };
 //#endregion
-//#region src/cursor-config.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.
-*/
-const CursorApiKey = Schema.Redacted(Schema.String).pipe(Schema.brand("CursorApiKey"));
-/**
-* Branded model identifier from wrapper config.
-*
-* Populated from the `CURSOR_MODEL` environment variable when using
-* {@link loadCursorConfig}.
-*/
-const CursorModelId = Schema.String.pipe(Schema.brand("CursorModelId"));
-/**
-* Branded local working directory for agent runs.
-*
-* Populated from `CURSOR_LOCAL_CWD` when using {@link loadCursorConfig}.
-*/
-const CursorLocalCwd = Schema.String.pipe(Schema.brand("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
-*/
-var CursorConfig = class extends Schema.Class("CursorConfig")({
-	apiKey: Schema.optional(CursorApiKey),
-	modelId: Schema.optional(CursorModelId),
-	cwd: Schema.optional(CursorLocalCwd)
-}) {};
-/**
-* 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
-*/
-const cursorConfig = Config.all({
-	apiKey: Config.redacted("CURSOR_API_KEY").pipe(Config.option),
-	modelId: Config.string("CURSOR_MODEL").pipe(Config.option),
-	cwd: Config.string("CURSOR_LOCAL_CWD").pipe(Config.option)
-});
-/**
-* 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
-*/
-const agentOptionsFromConfig = (config, overrides = {}) => {
-	const model = overrides.model ?? (config.modelId ? { id: config.modelId } : void 0);
-	return {
-		...overrides,
-		apiKey: overrides.apiKey ?? (config.apiKey ? Redacted.value(config.apiKey) : void 0),
-		model,
-		local: overrides.local ?? config.cwd ? {
-			cwd: config.cwd,
-			...overrides.local
-		} : void 0
-	};
-};
-/**
-* 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
-*/
-const loadCursorConfig = Effect.gen(function* () {
-	const provider = yield* ConfigProvider.ConfigProvider;
-	const raw = yield* cursorConfig.parse(provider);
-	const apiKey = Option.getOrUndefined(raw.apiKey);
-	const modelId = Option.getOrUndefined(raw.modelId);
-	const cwd = Option.getOrUndefined(raw.cwd);
-	return new CursorConfig({
-		apiKey: apiKey ? CursorApiKey.make(apiKey) : void 0,
-		modelId: modelId !== void 0 ? CursorModelId.make(modelId) : void 0,
-		cwd: cwd !== void 0 ? CursorLocalCwd.make(cwd) : void 0
-	});
-});
-//#endregion
 //#region src/cursor-inspection.ts
 /**
 * Effect-native wrappers for SDK inspection, lifecycle, and account catalog APIs.