effect-cursor-sdk 0.3.1 → 0.4.0

package/DEPRECATIONS.md

@@ -1,88 +1,5 @@
 # Deprecations
 
-This document lists deprecated `effect-cursor-sdk` APIs, what to use instead today, and how names are expected to change in the **next major** release. Deprecated APIs remain available until that major; follow [CHANGELOG.md](./CHANGELOG.md) and release notes when upgrading.
+There are currently **no deprecations** in this version of `effect-cursor-sdk`.
 
-## Status definitions
-
-| Status                 | Meaning                                                                                              |
-| ---------------------- | ---------------------------------------------------------------------------------------------------- |
-| **Deprecated**         | Still supported; avoid in new code. May show IDE warnings via TSDoc `@deprecated`.                   |
-| **Preferred now**      | Current recommended API; use with [`loadCursorConfig`](./README.md#quick-start) and related helpers. |
-| **Planned next major** | Intended replacement names after deprecated overloads and `*FromConfig` suffixes are removed.        |
-
-## Agent entry: plain `AgentOptions` vs config-first
-
-Passing raw [`AgentOptions`](https://cursor.com/docs/sdk/typescript) (including a plain `apiKey` string) directly to `CursorAgentService` agent entry points is **deprecated**. Prefer loading `CursorConfig` with `loadCursorConfig` (exported from this package) and using the `*FromConfig` methods so secrets stay [`Redacted`](https://effect.website/docs/schema/redacted/) until merged for the SDK boundary.
-
-### API mapping
-
-| Deprecated (`CursorAgentService`) | Preferred now                                   | Planned next major (same signatures as “Preferred now”) |
-| --------------------------------- | ----------------------------------------------- | ------------------------------------------------------- |
-| `create(options)`                 | `createFromConfig(config, overrides?)`          | `create(config, overrides?)`                            |
-| `resume(agentId, options?)`       | `resumeFromConfig(agentId, config, overrides?)` | `resume(agentId, config, overrides?)`                   |
-| `prompt(message, options?)`       | `promptFromConfig(message, config, overrides?)` | `prompt(message, config, overrides?)`                   |
-| `scoped(options)`                 | `scopedFromConfig(config, overrides?)`          | `scoped(config, overrides?)`                            |
-
-The `*FromConfig` suffixes exist today to keep deprecated plain-`AgentOptions` entry points without breaking callers. After removal of the legacy forms, the shorter names above are the intended stable surface.
-
-### Migrate `create`
-
-**Before (deprecated):**
-
-```ts
-const agent =
-  yield *
-  agents.create({
-    apiKey: process.env.CURSOR_API_KEY,
-    model: { id: "composer-2" },
-    local: { cwd: process.cwd() },
-  });
-```
-
-**After (preferred):**
-
-```ts
-const config = yield * loadCursorConfig;
-const agent =
-  yield *
-  agents.createFromConfig(config, {
-    model: { id: "composer-2" },
-    local: { cwd: process.cwd() },
-  });
-```
-
-If you need full control over merging into SDK options, call `agentOptionsFromConfig(config, overrides)` and pass the result only through internal or transitional code paths; application code should still prefer `createFromConfig`.
-
-### Migrate `prompt`
-
-**Before (deprecated):**
-
-```ts
-const result =
-  yield *
-  agents.prompt("Summarize the README", {
-    apiKey: process.env.CURSOR_API_KEY,
-    model: { id: "composer-2" },
-  });
-```
-
-**After (preferred):**
-
-```ts
-const config = yield * loadCursorConfig;
-const result =
-  yield *
-  agents.promptFromConfig("Summarize the README", config, {
-    model: { id: "composer-2" },
-  });
-```
-
-## Other deprecations
-
-`CursorSdkFactory` exposes raw SDK-style `create` / `resume` / `prompt` helpers for tests and advanced wiring; those are **deprecated for application code** in favor of `CursorAgentService` with the config-first flow above. See TSDoc on `CursorSdkFactory` in the published types.
-
-## Where else this is documented
-
-- [README.md](./README.md) — quick summary and link here.
-- Package root ships this file next to `README.md` on npm (see `package.json` `files`).
-- Per-symbol `@deprecated` tags on `CursorAgentService` and related exports in the TypeScript declarations.
+For historical breaking changes and release notes, see [CHANGELOG.md](./CHANGELOG.md).

package/README.md

@@ -6,8 +6,7 @@ Effect-native access to the new [Cursor SDK](https://cursor.com/docs/sdk/typescr
 
 `effect-cursor-sdk` wraps `@cursor/sdk` with Effect services, layers, scoped resource management, tagged errors, observability hooks, deterministic mocks, and ready-made runtimes. The upstream SDK remains the source of truth for Cursor-owned types; this package adds Effect ergonomics without creating a parallel model that can drift.
 
-> [!WARNING]
-> This project is in early development. While all functionality is available, there is still much room for improvement. Contributions are welcome!
+If you want to build with Cursor agents, and you are using Effect, this package is for you.
 
 ## Philosophy
 
@@ -23,7 +22,6 @@ Effect-native access to the new [Cursor SDK](https://cursor.com/docs/sdk/typescr
 - [SDK coverage & compatibility](./docs/SDK_COVERAGE.md) — wrapper checklist, audit script, release alignment
 - [Recipes](./docs/RECIPES.md) — short patterns (config-first agent, streaming, pagination, lifecycle, tests)
 - [Release checklist](./docs/RELEASE_CHECKLIST.md) — gates, SDK bumps, Changesets
-- [Next major migration (planned)](./docs/MIGRATION_NEXT_MAJOR.md) — config-first renames after deprecations are removed
 
 ## Feature Coverage
 
@@ -36,15 +34,43 @@ Effect-native access to the new [Cursor SDK](https://cursor.com/docs/sdk/typescr
 | `Agent.list`, `get`, `listRuns`, `getRun`, messages                              | `CursorInspectionService`                      |
 | `Agent.archive`, `unarchive`, `delete`                                           | `CursorInspectionService`                      |
 | `Cursor.me`, models, repositories                                                | `CursorInspectionService`                      |
-| MCP servers, sub-agents, local/cloud options, model options                      | Defaults via `CursorConfig` / `loadCursorConfig`; merged SDK `AgentOptions` ([deprecated](./DEPRECATIONS.md) at agent entry) |
+| MCP servers, sub-agents, local/cloud options, model options                      | Defaults via `CursorConfig` / `loadCursorConfig`; merged into SDK `AgentOptions` at the boundary |
 | Local run event helpers and platform helpers                                     | Re-exported from `@cursor/sdk`                 |
 
+## Use cases
+
+If you are new to the Cursor SDK, take a look at the [Cursor SDK Cookbook](https://github.com/cursor/cookbook). This cookbook provides some (cool!) examples of what you could do with the SDK.
+
+`effect-cursor-sdk` even [uses itself](#automated-changeset-agent) to spin up a Cursor agent to create changesets for pull requests against `main`! 🤯
+
 ## Install
 
 ```bash
 bun add effect-cursor-sdk effect @cursor/sdk
 ```
 
+`effect` is a **peer dependency** (Effect v4). `@cursor/sdk` is bundled with this package, but installing it in your app keeps SDK-owned types and versions explicit when you import from `@cursor/sdk` alongside the wrapper.
+
+### Requirements
+
+- **Runtime:** Bun or Node.js (examples and CI use Bun; Node works for library consumers).
+- **Effect:** `^4.0.0-beta` (see [Effect v4](https://effect.website/docs/introduction/overview) — still pre-release on the Effect side).
+- **Cursor SDK:** `@cursor/sdk` `^1.0.x` (pinned in this repo; see [SDK coverage](./docs/SDK_COVERAGE.md) when upgrading).
+
+### Configuration
+
+`loadCursorConfig` reads optional environment variables through Effect’s `ConfigProvider` (by default, `process.env`):
+
+| Variable | Purpose |
+| --- | --- |
+| `CURSOR_API_KEY` | API key for Cursor (stored as `Redacted` until merged into SDK options). |
+| `CURSOR_MODEL` | Default model id (for example `composer-2`). |
+| `CURSOR_LOCAL_CWD` | Default working directory for local agents. |
+
+All fields are optional at load time; missing `CURSOR_API_KEY` logs a warning and later SDK calls fail with authentication errors unless you pass overrides. Per-call overrides still win when using `create`, `scoped`, `prompt`, and `resume`.
+
+For offline tests and CI, use [`mockLayer`](#mocks-and-tests) or `makeMockRuntime` — no API key required.
+
 For development in this repo:
 
 ```bash
@@ -60,7 +86,7 @@ minimal first script to production-style Effect composition:
 
 | Example | What it demonstrates |
 | --- | --- |
-| [`quickstart`](./examples/quickstart) | First config-first local agent call with `loadCursorConfig`, `agentOptionsFromConfig`, and `collectText`. |
+| [`quickstart`](./examples/quickstart) | First config-first local agent call with `loadCursorConfig`, `scoped`, and `collectText`. |
 | [`cli`](./examples/cli) | A small terminal app with `liveRuntime`, offline `makeMockRuntime`, CLI overrides, and tagged error handling. |
 | [`basic-agent-workflow`](./examples/basic-agent-workflow) | Scoped agents, run status listeners, streaming, capability checks, and artifact listing/downloads. |
 | [`advanced-ops-dashboard`](./examples/advanced-ops-dashboard) | Inspection APIs, confirmation-gated lifecycle operations, parallel Effect composition, retries/timeouts, telemetry, redaction, and rich mocks. |
@@ -73,7 +99,7 @@ bun run examples:typecheck
 
 ## Quick Start
 
-Load environment defaults with `loadCursorConfig`, then create agents with `createFromConfig` (and `scopedFromConfig`, `promptFromConfig`, `resumeFromConfig` as needed). The API key stays in `Redacted` form until the merge step; `AgentOptions.apiKey` remains a plain string at the SDK boundary.
+Load environment defaults with `loadCursorConfig`, then create agents with `create` (and `scoped`, `prompt`, `resume` as needed). The API key stays in `Redacted` form until the merge step; `AgentOptions.apiKey` remains a plain string at the SDK boundary.
 
 ```ts
 import {
@@ -89,7 +115,7 @@ const program = Effect.gen(function* () {
   const runs = yield* CursorRunService;
 
   const config = yield* loadCursorConfig;
-  const agent = yield* agents.createFromConfig(config, {
+  const agent = yield* agents.create(config, {
     // Override the given config optionally with custom values
     model: { id: "composer-2" },
     local: { cwd: process.cwd() },
@@ -105,38 +131,11 @@ const program = Effect.gen(function* () {
 
 Effect’s default `ConfigProvider` reads `process.env`, so you usually do not need to install a custom provider for this.
 
-If you need full control over the merge into SDK options, you can still call `agentOptionsFromConfig` yourself and pass the result to deprecated `create`; prefer `createFromConfig` in application code.
-
-## Plain `AgentOptions` at the agent boundary (deprecated)
-
-Passing raw `AgentOptions` (for example `apiKey: process.env.CURSOR_API_KEY`) to `create`, `resume`, `prompt`, or `scoped` is **deprecated**. It still works for compatibility, but prefer the config flow above.
-
-```ts
-import { CursorAgentService, CursorRunService, liveLayer } from "effect-cursor-sdk";
-import { Effect } from "effect";
-
-const legacyProgram = Effect.gen(function* () {
-  const agents = yield* CursorAgentService;
-  const runs = yield* CursorRunService;
-
-  const agent = yield* agents.create({
-    apiKey: process.env.CURSOR_API_KEY,
-    model: { id: "composer-2" },
-    local: { cwd: process.cwd() },
-  });
-
-  const run = yield* agents.send(agent, "Explain this repository");
-  const text = yield* runs.collectText(run);
-  yield* agents.dispose(agent);
-  return text;
-}).pipe(Effect.provide(liveLayer));
-```
-
-Migrate by replacing `agents.create({ ... })` with `const config = yield* loadCursorConfig` and `agents.createFromConfig(config, { ... })` (or the other `*FromConfig` helpers).
+For advanced SDK-factory wiring in tests, you can still call `agentOptionsFromConfig` to merge config into plain `AgentOptions` before passing them to `CursorSdkFactory`.
 
 ## Scoped Agents
 
-Prefer `scopedFromConfig` when an agent should be disposed automatically:
+Prefer `scoped` when an agent should be disposed automatically:
 
 ```ts
 import { CursorAgentService, loadCursorConfig, liveLayer } from "effect-cursor-sdk";
@@ -146,7 +145,7 @@ const program = Effect.scoped(
   Effect.gen(function* () {
     const agents = yield* CursorAgentService;
     const config = yield* loadCursorConfig;
-    const agent = yield* agents.scopedFromConfig(config, {
+    const agent = yield* agents.scoped(config, {
       model: { id: "composer-2" },
       local: { cwd: process.cwd() },
     });
@@ -156,13 +155,24 @@ const program = Effect.scoped(
 ).pipe(Effect.provide(liveLayer));
 ```
 
+## Resume an existing agent
+
+Use `resume` with the agent id from a prior run or from `CursorInspectionService.listAgents`:
+
+```ts
+const config = yield* loadCursorConfig;
+const agent = yield* agents.resume("bc_abc123", config, {
+  local: { cwd: process.cwd() },
+});
+```
+
 ## Cloud Agents
 
 Cloud options are merged as SDK overrides on top of loaded config:
 
 ```ts
 const config = yield* loadCursorConfig;
-const agent = yield* agents.createFromConfig(config, {
+const agent = yield* agents.create(config, {
   model: { id: "composer-2" },
   cloud: {
     repos: [
@@ -198,6 +208,10 @@ yield* runs.streamEvents(run).pipe(
 );
 ```
 
+## Artifacts
+
+List and download run outputs with `CursorArtifactService` after `send` completes. See the [Artifacts recipe](./docs/RECIPES.md#artifacts) for path resolution and download patterns.
+
 ## Inspection And Metadata
 
 Use `CursorInspectionService` for agent/run listings, messages, lifecycle operations, account metadata, model discovery, and connected repositories.
@@ -214,7 +228,7 @@ const repos = yield* inspection.listRepositories();
 
 Because every Cursor call is an `Effect`, you compose it like the rest of your program: parallel requests, timeouts, retries, logging, and layers all work the same way.
 
-This agent garden snapshot loads your catalog in parallel, adds a resilient boundary around the batch, logs a safe summary (counts and IDs only — never log API keys), then asks Cursor for a one-shot triage opinion via `promptFromConfig`:
+This agent garden snapshot loads your catalog in parallel, adds a resilient boundary around the batch, logs a safe summary (counts and IDs only — never log API keys), then asks Cursor for a one-shot triage opinion via `prompt`:
 
 ```ts
 import {
@@ -250,7 +264,7 @@ const agentGardenSnapshot = Effect.gen(function* () {
     repos: catalog.repos.length,
   });
 
-  const triage = yield* agents.promptFromConfig(
+  const triage = yield* agents.prompt(
     [
       "You are helping on-call. Here is non-secret inventory:",
       `- Cloud agents (ids): ${catalog.cloud.items.map((a) => a.agentId).join(", ") || "(none)"}`,
@@ -272,10 +286,10 @@ Swap `liveLayer` for `mockLayer({ ... })` in tests and the same program shape ex
 
 ## Errors
 
-SDK failures are mapped into tagged errors such as `CursorAuthenticationError`, `CursorRateLimitError`, `CursorConfigurationError`, `CursorNetworkError`, and `CursorUnsupportedOperationError`. The original SDK error is preserved as `cause`, with safe operation context and retryability where available.
+SDK failures are mapped into tagged errors such as `CursorAuthenticationError`, `CursorRateLimitError`, `CursorConfigurationError`, `CursorAgentBusyError`, `CursorNetworkError`, and `CursorUnsupportedOperationError`. The original SDK error is preserved as `cause`, with safe operation context and retryability where available.
 
 ```ts
-program.pipe(
+const handled = program.pipe(
   Effect.catchTag("CursorRateLimitError", (error) =>
     Effect.logWarning(`Cursor rate limited request: ${error.message}`),
   ),
@@ -302,7 +316,7 @@ import { Effect } from "effect";
 const testProgram = Effect.gen(function* () {
   const agents = yield* CursorAgentService;
   const config = yield* loadCursorConfig;
-  const agent = yield* agents.createFromConfig(config, { model: { id: "composer-2" } });
+  const agent = yield* agents.create(config, { model: { id: "composer-2" } });
   return yield* agents.send(agent, "Hello");
 }).pipe(
   Effect.provide(
@@ -319,11 +333,11 @@ The main exports are:
 
 - **Recipes** — common compositions (prompt text, send + collect, pagination, lifecycle guards, artifacts) in [RECIPES.md](./docs/RECIPES.md)
 - **Observability helpers** (`streamEventsTracked`, `collectTextTracked`, catalog retry/timeout presets, log summaries)
-- `CursorAgentService` (prefer `createFromConfig`, `scopedFromConfig`, `promptFromConfig`, `resumeFromConfig` with `loadCursorConfig`; plain `AgentOptions` at the agent boundary is [deprecated](./DEPRECATIONS.md))
+- `CursorAgentService` (`create`, `scoped`, `prompt`, `resume` with `loadCursorConfig`)
 - `CursorRunService`
 - `CursorArtifactService`
 - `CursorInspectionService`
-- `CursorSdkFactory` ([deprecated for application code](./DEPRECATIONS.md#other-deprecations); low-level tests and overrides)
+- `CursorSdkFactory` (low-level SDK adapter for tests and advanced overrides)
 - `liveLayer`, `mockLayer`, `liveRuntime`, `makeMockRuntime`
 - `CursorConfig`, `cursorConfig`, `agentOptionsFromConfig`, `loadCursorConfig`
 - tagged Cursor error classes and `mapCursorError`
@@ -350,7 +364,7 @@ Coverage is measured with Vitest v8 coverage. The suite focuses on deterministic
 
 ## Deprecations
 
-Whenever you need a single place for what is deprecated, what to use instead, how to migrate, and what may change in the next major (when that is already decided), read **[DEPRECATIONS.md](./DEPRECATIONS.md)**. Pair it with **[CHANGELOG.md](./CHANGELOG.md)** for release-by-release notes; `@deprecated` tags on exported symbols mirror the same intent for day-to-day coding.
+See **[DEPRECATIONS.md](./DEPRECATIONS.md)** for the canonical list of deprecated APIs. Pair it with **[CHANGELOG.md](./CHANGELOG.md)** for release-by-release notes.
 
 ## Versioning and Publishing
 
@@ -368,7 +382,15 @@ User-facing changes should include a Changeset:
 bun run changeset
 ```
 
-On `main`, GitHub Actions uses Changesets to open a version PR when pending Changesets exist. After that PR is merged, the same workflow runs `bun run release` and publishes to NPM with the `NPM_TOKEN` repository secret.
+### Automated Changeset Agent
+
+This repository also includes a Cursor-powered changeset agent for pull requests against `main`. The workflow in `.github/workflows/changeset-agent.yml` runs `bun run changeset:agent`, starts a scoped local Cursor SDK agent with this package, asks it to inspect the PR diff, and commits a missing `.changeset/*.md` file back to the PR branch when release impact exists.
+
+The job runs only for same-repository, non-draft PRs because it needs both the `CURSOR_API_KEY` repository secret and write access to the PR branch. Forked PRs should add changesets manually or be handled from a trusted maintainer checkout.
+
+Other, optional environment variables are `CURSOR_MODEL` for the Cursor model id and `CHANGESET_BASE_REF` for the diff base. See [Changeset Agent](./docs/changeset-agent.md) for the full architecture, prompt contract, security model, and local usage.
+
+On `main`, GitHub Actions uses Changesets to open a version PR when pending Changesets exist. After that PR is merged, the same workflow runs `bun run release` and publishes to NPM.
 
 For local release preparation, apply pending Changesets and publish only after the package is approved for public release: