effect-cursor-sdk 0.1.1 → 0.2.1

package/DEPRECATIONS.md

@@ -0,0 +1,88 @@
+# 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.
+
+## 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.

package/README.md

@@ -1,5 +1,7 @@
 # effect-cursor-sdk
 
+![npm](https://img.shields.io/npm/v/effect-cursor-sdk) ![License MIT](https://img.shields.io/github/license/benjamin-kraatz/effect-cursor-sdk) ![CI](https://img.shields.io/github/actions/workflow/status/benjamin-kraatz/effect-cursor-sdk/ci.yml) ![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/benjamin-kraatz/effect-cursor-sdk?utm_source=oss&utm_medium=github&utm_campaign=benjamin-kraatz%2Feffect-cursor-sdk&labelColor=171717&color=FF570A&link=https%3A%2F%2Fcoderabbit.ai&label=CodeRabbit+Reviews)
+
 Effect-native access to the new [Cursor SDK](https://cursor.com/docs/sdk/typescript).
 
 `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.
@@ -27,7 +29,7 @@ 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                      | SDK-owned `AgentOptions` and re-exported types |
+| MCP servers, sub-agents, local/cloud options, model options                      | Defaults via `CursorConfig` / `loadCursorConfig`; merged SDK `AgentOptions` ([deprecated](./DEPRECATIONS.md) at agent entry) |
 | Local run event helpers and platform helpers                                     | Re-exported from `@cursor/sdk`                 |
 
 ## Install
@@ -44,18 +46,44 @@ bun run typecheck
 bun run test
 ```
 
+## Examples
+
+The [`examples`](./examples) directory contains a guided learning path from a
+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`. |
+| [`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. |
+
+Run all example typechecks from the repo root:
+
+```bash
+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.
+
 ```ts
-import { CursorAgentService, CursorRunService, liveLayer } from "effect-cursor-sdk";
-import { Effect, Stream } from "effect";
+import {
+  CursorAgentService,
+  CursorRunService,
+  loadCursorConfig,
+  liveLayer,
+} from "effect-cursor-sdk";
+import { Effect } from "effect";
 
 const program = Effect.gen(function* () {
   const agents = yield* CursorAgentService;
   const runs = yield* CursorRunService;
 
-  const agent = yield* agents.create({
-    apiKey: process.env.CURSOR_API_KEY,
+  const config = yield* loadCursorConfig;
+  const agent = yield* agents.createFromConfig(config, {
+    // Override the given config optionally with custom values
     model: { id: "composer-2" },
     local: { cwd: process.cwd() },
   });
@@ -68,56 +96,50 @@ const program = Effect.gen(function* () {
 }).pipe(Effect.provide(liveLayer));
 ```
 
-`AgentOptions.apiKey` is a plain string at the SDK boundary. To keep the key in `Redacted` form until that boundary, read `CURSOR_API_KEY` (and optional `CURSOR_MODEL`, `CURSOR_LOCAL_CWD`) with `loadCursorConfig`, then merge into `AgentOptions` with `agentOptionsFromConfig`.
-In a future version, we might drop the plain `AgentOptions` boundary and require all options to be passed through `CursorConfig` / `loadCursorConfig` / `agentOptionsFromConfig`.
-
 Effect’s default `ConfigProvider` reads `process.env`, so you usually do not need to install a custom provider for this.
 
-### Quick start with `loadCursorConfig`
+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,
-  agentOptionsFromConfig,
-  loadCursorConfig,
-  liveLayer,
-} from "effect-cursor-sdk";
+import { CursorAgentService, CursorRunService, liveLayer } from "effect-cursor-sdk";
 import { Effect } from "effect";
 
-const program = Effect.gen(function* () {
+const legacyProgram = Effect.gen(function* () {
   const agents = yield* CursorAgentService;
   const runs = yield* CursorRunService;
 
-  const config = yield* loadCursorConfig;
-  const agent = yield* agents.create(
-    // Flexible: use the config from the environment, and override with local options.
-    agentOptionsFromConfig(config, {
-      model: { id: "composer-2" },
-      local: { cwd: process.cwd() },
-    }),
-  );
+  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).
+
 ## Scoped Agents
 
-Prefer `scoped` when an agent should be disposed automatically:
+Prefer `scopedFromConfig` when an agent should be disposed automatically:
 
 ```ts
-import { CursorAgentService, liveLayer } from "effect-cursor-sdk";
+import { CursorAgentService, loadCursorConfig, liveLayer } from "effect-cursor-sdk";
 import { Effect } from "effect";
 
 const program = Effect.scoped(
   Effect.gen(function* () {
     const agents = yield* CursorAgentService;
-    const agent = yield* agents.scoped({
+    const config = yield* loadCursorConfig;
+    const agent = yield* agents.scopedFromConfig(config, {
       model: { id: "composer-2" },
       local: { cwd: process.cwd() },
     });
@@ -129,19 +151,19 @@ const program = Effect.scoped(
 
 ## Cloud Agents
 
-Cloud options are passed through as SDK `AgentOptions`:
+Cloud options are merged as SDK overrides on top of loaded config:
 
 ```ts
-const agent =
-  yield *
-  agents.create({
-    apiKey: process.env.CURSOR_API_KEY,
-    model: { id: "composer-2" },
-    cloud: {
-      repos: [{ url: "https://github.com/your-org/your-repo", startingRef: "main" }],
-      autoCreatePR: true,
-    },
-  });
+const config = yield* loadCursorConfig;
+const agent = yield* agents.createFromConfig(config, {
+  model: { id: "composer-2" },
+  cloud: {
+    repos: [
+      { url: "https://github.com/your-org/your-repo", startingRef: "main" },
+    ],
+    autoCreatePR: true,
+  },
+});
 ```
 
 ## Streaming
@@ -149,18 +171,24 @@ const agent =
 `CursorRunService.streamEvents` preserves SDK event shapes and returns an Effect `Stream`.
 
 ```ts
-const run = yield * agents.send(agent, "Refactor the auth module");
-
-yield *
-  runs
-    .streamEvents(run)
-    .pipe(
-      Stream.runForEach((event) =>
-        event.type === "assistant"
-          ? Effect.sync(() => console.log(event.message.content))
-          : Effect.void,
-      ),
-    );
+import { Effect, Stream } from "effect";
+
+const run = yield* agents.send(agent, "Refactor the auth module");
+
+yield* runs.streamEvents(run).pipe(
+  Stream.runForEach((event) => {
+    if (event.type !== "assistant") {
+      return Effect.void;
+    }
+
+    const text = event.message.content
+      .filter((block) => block.type === "text")
+      .map((block) => block.text)
+      .join("");
+
+    return Effect.sync(() => console.log(text));
+  }),
+);
 ```
 
 ## Inspection And Metadata
@@ -168,13 +196,73 @@ yield *
 Use `CursorInspectionService` for agent/run listings, messages, lifecycle operations, account metadata, model discovery, and connected repositories.
 
 ```ts
-const inspection = yield * CursorInspectionService;
+const inspection = yield* CursorInspectionService;
+
+const agents = yield* inspection.listAgents({ runtime: "cloud", includeArchived: true });
+const models = yield* inspection.listModels();
+const repos = yield* inspection.listRepositories();
+```
+
+## Integrate deeper with Effect
+
+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`:
+
+```ts
+import {
+  CursorAgentService,
+  CursorInspectionService,
+  loadCursorConfig,
+  liveLayer,
+} from "effect-cursor-sdk";
+import { Effect, Schedule } from "effect";
 
-const agents = yield * inspection.listAgents({ runtime: "cloud", includeArchived: true });
-const models = yield * inspection.listModels();
-const repos = yield * inspection.listRepositories();
+const agentGardenSnapshot = Effect.gen(function* () {
+  const inspection = yield* CursorInspectionService;
+  const agents = yield* CursorAgentService;
+  const config = yield* loadCursorConfig;
+
+  const catalog = yield* Effect.all(
+    {
+      cloud: inspection.listAgents({ runtime: "cloud", includeArchived: false }),
+      models: inspection.listModels(),
+      repos: inspection.listRepositories(),
+    },
+    { concurrency: "unbounded" },
+  ).pipe(
+    Effect.retry(
+      Schedule.exponential("150 millis").pipe(Schedule.both(Schedule.recurs(3))),
+    ),
+    Effect.timeout("45 seconds"),
+  );
+
+  yield* Effect.logInfo("Cursor catalog loaded", {
+    cloudAgents: catalog.cloud.items.length,
+    models: catalog.models.length,
+    repos: catalog.repos.length,
+  });
+
+  const triage = yield* agents.promptFromConfig(
+    [
+      "You are helping on-call. Here is non-secret inventory:",
+      `- Cloud agents (ids): ${catalog.cloud.items.map((a) => a.agentId).join(", ") || "(none)"}`,
+      `- Models (ids): ${catalog.models.map((m) => m.id).join(", ") || "(none)"}`,
+      `- Repos (urls): ${catalog.repos.map((r) => r.url).join(", ") || "(none)"}`,
+      "In two short sentences: what should we verify first before trusting automation here?",
+    ].join("\n"),
+    config,
+    {
+      model: { id: "composer-2" },
+    },
+  );
+
+  return triage.result;
+}).pipe(Effect.provide(liveLayer));
 ```
 
+Swap `liveLayer` for `mockLayer({ ... })` in tests and the same program shape exercises your orchestration without the network.
+
 ## 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.
@@ -201,12 +289,13 @@ Never log API keys, MCP credentials, authorization headers, or prompt image data
 Use `mockLayer` for deterministic tests:
 
 ```ts
-import { CursorAgentService, mockLayer } from "effect-cursor-sdk";
+import { CursorAgentService, loadCursorConfig, mockLayer } from "effect-cursor-sdk";
 import { Effect } from "effect";
 
 const testProgram = Effect.gen(function* () {
   const agents = yield* CursorAgentService;
-  const agent = yield* agents.create({ model: { id: "composer-2" } });
+  const config = yield* loadCursorConfig;
+  const agent = yield* agents.createFromConfig(config, { model: { id: "composer-2" } });
   return yield* agents.send(agent, "Hello");
 }).pipe(
   Effect.provide(
@@ -221,11 +310,11 @@ const testProgram = Effect.gen(function* () {
 
 The main exports are:
 
-- `CursorAgentService`
+- `CursorAgentService` (prefer `createFromConfig`, `scopedFromConfig`, `promptFromConfig`, `resumeFromConfig` with `loadCursorConfig`; plain `AgentOptions` at the agent boundary is [deprecated](./DEPRECATIONS.md))
 - `CursorRunService`
 - `CursorArtifactService`
 - `CursorInspectionService`
-- `CursorSdkFactory`
+- `CursorSdkFactory` ([deprecated for application code](./DEPRECATIONS.md#other-deprecations); low-level tests and overrides)
 - `liveLayer`, `mockLayer`, `liveRuntime`, `makeMockRuntime`
 - `CursorConfig`, `cursorConfig`, `agentOptionsFromConfig`, `loadCursorConfig`
 - tagged Cursor error classes and `mapCursorError`
@@ -247,6 +336,10 @@ bun run lint:package
 
 Coverage is measured with Vitest v8 coverage. The suite focuses on deterministic wrapper behavior; live SDK network paths should be validated separately with credentials and a disposable repository.
 
+## 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.
+
 ## Versioning and Publishing
 
 Use conventional commits for readable history and changelog context: