effect-cursor-sdk 0.2.1 → 0.3.1

package/docs/RECIPES.md

@@ -0,0 +1,256 @@
+# Recipes
+
+Short patterns for common tasks. Each corresponds to an [`examples/`](../examples) app where a fuller program is useful.
+
+**Design note:** This package intentionally keeps the public API centered on the four Effect services (`CursorAgentService`, `CursorRunService`, `CursorArtifactService`, `CursorInspectionService`) plus config, observability, and mocks. Common compositions live here as copy-paste recipes so you always see which service owns each step.
+
+## Config-first agent (preferred)
+
+Use {@link loadCursorConfig} with {@link CursorAgentService.scopedFromConfig} or `createFromConfig`:
+
+```ts
+import { CursorAgentService, loadCursorConfig, liveLayer } from "effect-cursor-sdk";
+import { Effect } from "effect";
+
+const program = Effect.scoped(
+  Effect.gen(function* () {
+    const config = yield* loadCursorConfig;
+    const agents = yield* CursorAgentService;
+    const agent = yield* agents.scopedFromConfig(config, {
+      local: { cwd: process.cwd() },
+    });
+    return yield* agents.send(agent, "Summarize the repo");
+  }),
+).pipe(Effect.provide(liveLayer));
+```
+
+Equivalent merge style (also common in examples):
+
+```ts
+import { agentOptionsFromConfig } from "effect-cursor-sdk";
+
+const agent = yield* agents.scoped(agentOptionsFromConfig(config, { local: { cwd: process.cwd() } }));
+```
+
+## One-shot text from a prompt
+
+Use {@link CursorAgentService.promptFromConfig} and read `result` (default to empty string if absent):
+
+```ts
+import { CursorAgentService, liveLayer, loadCursorConfig } from "effect-cursor-sdk";
+import { Effect } from "effect";
+
+const program = Effect.gen(function* () {
+  const config = yield* loadCursorConfig;
+  const agents = yield* CursorAgentService;
+  const out = yield* agents.promptFromConfig("Hello", config, { model: { id: "composer-2" } });
+  return out.result ?? "";
+}).pipe(Effect.provide(liveLayer));
+```
+
+## Send and collect assistant text
+
+Call {@link CursorAgentService.send}, then {@link CursorRunService.collectText} on the returned run:
+
+```ts
+import { CursorAgentService, CursorRunService, loadCursorConfig, liveLayer } from "effect-cursor-sdk";
+import { Effect } from "effect";
+
+const program = Effect.scoped(
+  Effect.gen(function* () {
+    const config = yield* loadCursorConfig;
+    const agents = yield* CursorAgentService;
+    const runs = yield* CursorRunService;
+    const agent = yield* agents.scopedFromConfig(config, { local: { cwd: process.cwd() } });
+    const run = yield* agents.send(agent, "Explain Effect layers");
+    return yield* runs.collectText(run);
+  }),
+).pipe(Effect.provide(liveLayer));
+```
+
+## Streaming with metrics
+
+Use {@link streamEventsTracked} or {@link collectTextTracked} with {@link CursorRunService.streamEvents}:
+
+```ts
+import {
+  collectTextTracked,
+  CursorAgentService,
+  CursorRunService,
+  loadCursorConfig,
+  liveLayer,
+} from "effect-cursor-sdk";
+import { Effect } from "effect";
+
+const program = Effect.scoped(
+  Effect.gen(function* () {
+    const agents = yield* CursorAgentService;
+    const runs = yield* CursorRunService;
+    const config = yield* loadCursorConfig;
+    const agent = yield* agents.scopedFromConfig(config, { local: { cwd: process.cwd() } });
+    const run = yield* agents.send(agent, "Hi");
+    return yield* collectTextTracked(run, (r) => runs.streamEvents(r));
+  }),
+).pipe(Effect.provide(liveLayer));
+```
+
+## Status as a stream
+
+{@link CursorRunService.streamStatusChanges}:
+
+```ts
+runs.streamStatusChanges(run).pipe(Stream.take(3), Stream.runCollect);
+```
+
+## Resilient catalog fetch
+
+Reuse {@link cursorCatalogRetrySchedule} and {@link cursorCatalogLoadTimeout}:
+
+```ts
+import {
+  cursorCatalogLoadTimeout,
+  cursorCatalogRetrySchedule,
+  CursorInspectionService,
+  liveLayer,
+} from "effect-cursor-sdk";
+import { Effect } from "effect";
+
+const program = Effect.gen(function* () {
+  const inspection = yield* CursorInspectionService;
+  return yield* Effect.all(
+    {
+      agents: inspection.listAgents({ runtime: "cloud" }),
+      models: inspection.listModels(),
+    },
+    { concurrency: "unbounded" },
+  ).pipe(Effect.retry(cursorCatalogRetrySchedule), Effect.timeout(cursorCatalogLoadTimeout));
+}).pipe(Effect.provide(liveLayer));
+```
+
+## Paginated lists
+
+`listAgents` / `listRuns` return `nextCursor`. Loop until `nextCursor` is absent (with a `maxPages` guard):
+
+```ts
+import { CursorInspectionService, liveLayer } from "effect-cursor-sdk";
+import type { ListAgentsOptions, ListRunsOptions, Run, SDKAgentInfo } from "effect-cursor-sdk";
+import { Effect } from "effect";
+
+const listAgentsAllPages = (base?: ListAgentsOptions, maxPages = 100) =>
+  Effect.gen(function* () {
+    const inspection = yield* CursorInspectionService;
+    const out: SDKAgentInfo[] = [];
+    let cursor: string | undefined;
+    for (let page = 0; page < maxPages; page++) {
+      const res = yield* inspection.listAgents({ ...base, cursor } as ListAgentsOptions);
+      out.push(...res.items);
+      cursor = res.nextCursor;
+      if (cursor === undefined || res.items.length === 0) break;
+    }
+    return out;
+  });
+
+const listRunsAllPages = (agentId: string, base?: ListRunsOptions, maxPages = 100) =>
+  Effect.gen(function* () {
+    const inspection = yield* CursorInspectionService;
+    const out: Run[] = [];
+    let cursor: string | undefined;
+    for (let page = 0; page < maxPages; page++) {
+      const res = yield* inspection.listRuns(agentId, { ...base, cursor } as ListRunsOptions);
+      out.push(...res.items);
+      cursor = res.nextCursor;
+      if (cursor === undefined || res.items.length === 0) break;
+    }
+    return out;
+  });
+
+// …then e.g. listAgentsAllPages({ runtime: "cloud" }).pipe(Effect.provide(liveLayer));
+```
+
+## Lifecycle mutations (archive / unarchive / delete)
+
+Require operators to type an exact phrase before calling {@link CursorInspectionService.archiveAgent}, `unarchiveAgent`, or `deleteAgent`:
+
+```ts
+import { CursorInspectionService, liveLayer } from "effect-cursor-sdk";
+import { Data, Effect } from "effect";
+
+type LifecycleAction = "archive" | "unarchive" | "delete";
+
+class LifecycleConfirmationError extends Data.TaggedError("LifecycleConfirmationError")<{
+  readonly message: string;
+  readonly action: LifecycleAction;
+  readonly agentId: string;
+}> {}
+
+const lifecyclePhrase = (action: LifecycleAction, agentId: string) => `${action.toUpperCase()} ${agentId}`;
+
+const ensureLifecycleConfirmation = (
+  action: LifecycleAction,
+  agentId: string,
+  typed: string,
+): Effect.Effect<void, LifecycleConfirmationError> => {
+  const expected = lifecyclePhrase(action, agentId);
+  if (typed !== expected) {
+    return Effect.fail(
+      new LifecycleConfirmationError({
+        message: `Expected confirmation "${expected}".`,
+        action,
+        agentId,
+      }),
+    );
+  }
+  return Effect.void;
+};
+
+const archiveAgentConfirmed = (agentId: string, typed: string) =>
+  Effect.gen(function* () {
+    yield* ensureLifecycleConfirmation("archive", agentId, typed);
+    const inspection = yield* CursorInspectionService;
+    yield* inspection.archiveAgent(agentId);
+  });
+
+// archiveAgentConfirmed("agt_1", "ARCHIVE agt_1").pipe(Effect.provide(liveLayer));
+```
+
+Adjust for `unarchiveAgent` / `deleteAgent` the same way.
+
+## Artifacts
+
+After {@link CursorArtifactService.listArtifacts}, pick a path (exact, basename, or suffix match) and {@link CursorArtifactService.downloadArtifact}:
+
+```ts
+import { CursorArtifactService, liveLayer } from "effect-cursor-sdk";
+import type { SDKAgent, SDKArtifact } from "effect-cursor-sdk";
+import { Effect } from "effect";
+
+function resolveArtifactPath(requested: string, list: ReadonlyArray<SDKArtifact>): string | undefined {
+  if (list.some((a) => a.path === requested)) return requested;
+  const base = requested.replace(/^.*\//, "");
+  return list.find((a) => a.path === base || a.path.endsWith(`/${base}`))?.path;
+}
+
+const downloadArtifactResolved = (
+  agent: SDKAgent,
+  listing: ReadonlyArray<SDKArtifact>,
+  requested?: string,
+) =>
+  Effect.gen(function* () {
+    const artifacts = yield* CursorArtifactService;
+    const path = requested ? resolveArtifactPath(requested, listing) : listing[0]?.path;
+    if (path === undefined) return undefined;
+    const bytes = yield* artifacts.downloadArtifact(agent, path);
+    return { path, bytes } as const;
+  });
+
+// downloadArtifactResolved(agent, listing, "coverage.html").pipe(Effect.provide(liveLayer));
+```
+
+## Testing
+
+- {@link mockLayer} / {@link makeMockRuntime} for full stack tests.
+- {@link CursorMockFixtures.factoryErrors} to exercise error mapping and retries.
+- {@link CursorMockFixtures.sendSequence} for multi-turn runs.
+- {@link makeMockAssistantSdkMessage} for stream fixtures.
+
+See [SDK_COVERAGE.md](./SDK_COVERAGE.md) for wrapper vs re-export policy.

package/docs/RELEASE_CHECKLIST.md

@@ -0,0 +1,46 @@
+# Release checklist
+
+Use this before publishing or tagging a release candidate.
+
+## Automated gates
+
+From the repository root:
+
+```bash
+bun install
+bun run typecheck
+bun run sdk-audit
+bun run lint
+bun run format:check
+bun run test
+bun run test:coverage
+bun run build
+bun run lint:package
+bun run examples:typecheck
+```
+
+`verify:publish` runs a subset: typecheck, `sdk-audit`, lint, test, build, publint.
+
+## SDK bump
+
+When updating `@cursor/sdk` in root `package.json`:
+
+1. `bun install`
+2. `bun run sdk-audit` — if it fails, inspect new exports (`docs/SDK_COVERAGE.md`, `src/cursor-types.ts`, `CursorSdkFactory`, mocks).
+3. Align example apps: each `examples/*/package.json` should use the same `@cursor/sdk` range as the library (see peer/dependency policy in `docs/SDK_COVERAGE.md`).
+4. Refresh `docs/SDK_COVERAGE.md` checklist table if wrappers changed.
+5. Optionally run `bun run sdk-audit:refresh` **only after** confirming drift is handled, then commit `scripts/sdk-export-baseline.json`.
+
+## Changesets and changelog
+
+- Add a [Changeset](https://github.com/changesets/changesets) for user-facing changes: `bun run changeset`
+- User-facing narrative also belongs in `CHANGELOG.md` when cutting a release (via Changesets or manual edit per repo practice).
+
+## Docs
+
+- Link new features from [README.md](../README.md).
+- Update [RECIPES.md](./RECIPES.md) when adding important usage patterns
+
+## Credentials note
+
+Live Cursor paths are not exercised in CI. After releasing, smoke-test with a disposable API key if you changed agent or networking code.

package/docs/SDK_COVERAGE.md

@@ -0,0 +1,72 @@
+# SDK coverage and compatibility
+
+This document is the (somewhat?) **source of truth** for how `effect-cursor-sdk` tracks [@cursor/sdk](https://cursor.com/docs/sdk/typescript). Update it whenever you add wrappers, re-exports, or bump the SDK.
+
+## Policy
+
+| Layer                      | What belongs here                                                                                                                                                                                                  |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Effect-native services** | Each important SDK call gets `Effect.tryPromise` (or `Stream`), `mapCursorError`, and `instrument` via `CursorAgentService`, `CursorRunService`, `CursorArtifactService`, or `CursorInspectionService`.            |
+| **Thin factory**           | `CursorSdkFactory` mirrors static `Agent.*` / `Cursor.*` entry points for tests and advanced DI.                                                                                                                   |
+| **Types and utilities**    | Curated re-exports in [`src/cursor-types.ts`](../src/cursor-types.ts). Anything else: import from `@cursor/sdk` directly (SDK stays the data-model source of truth).                                               |
+| **Cross-cutting helpers**   | Observability presets in [`src/cursor-observability.ts`](../src/cursor-observability.ts). Common multi-step flows belong in [RECIPES.md](./RECIPES.md) as documentation, not extra package exports. |
+
+## Wrapper checklist (maintain when `@cursor/sdk` changes)
+
+Mark each row when verified against the **pinned** SDK version in root [`package.json`](../package.json).
+
+### `Agent` static and instances
+
+| SDK surface                                       | Wrapper location                                                            | Status |
+| ------------------------------------------------- | --------------------------------------------------------------------------- | ------ |
+| `Agent.create`                                    | `CursorAgentService.create` / `createFromConfig`, `CursorSdkFactory.create` | OK     |
+| `Agent.resume`                                    | `CursorAgentService.resume` / `resumeFromConfig`, `CursorSdkFactory.resume` | OK     |
+| `Agent.prompt`                                    | `CursorAgentService.prompt` / `promptFromConfig`, `CursorSdkFactory.prompt` | OK     |
+| `Agent.list`                                      | `CursorInspectionService.listAgents`, `CursorSdkFactory.listAgents`         | OK     |
+| `Agent.get`                                       | `CursorInspectionService.getAgent`, `CursorSdkFactory.getAgent`             | OK     |
+| `Agent.archive` / `unarchive` / `delete`          | `CursorInspectionService.archiveAgent` / `unarchiveAgent` / `deleteAgent`   | OK     |
+| `Agent.listRuns`                                  | `CursorInspectionService.listRuns`, `CursorSdkFactory.listRuns`             | OK     |
+| `Agent.getRun`                                    | `CursorInspectionService.getRun`, `CursorSdkFactory.getRun`                 | OK     |
+| `Agent.messages.list`                             | `CursorInspectionService.listMessages`, `CursorSdkFactory.listMessages`     | OK     |
+| `SDKAgent.send`                                   | `CursorAgentService.send`                                                   | OK     |
+| `SDKAgent.reload`                                 | `CursorAgentService.reload`                                                 | OK     |
+| `SDKAgent.close`                                  | `CursorAgentService.close`                                                  | OK     |
+| async dispose                                     | `CursorAgentService.dispose`                                                | OK     |
+| `SDKAgent.listArtifacts`                          | `CursorArtifactService.listArtifacts`                                       | OK     |
+| `SDKAgent.downloadArtifact`                       | `CursorArtifactService.downloadArtifact`                                    | OK     |
+| `Run.wait` / `cancel` / `conversation` / `stream` | `CursorRunService`                                                          | OK     |
+| `Run.supports` / `unsupportedReason`              | `CursorRunService.supports` / `unsupportedReason`                           | OK     |
+| `Run.onDidChangeStatus`                           | `CursorRunService.onDidChangeStatus` (+ `streamStatusChanges` helper)       | OK     |
+
+### `Cursor` account APIs
+
+| SDK surface                | Wrapper location                                                                | Status |
+| -------------------------- | ------------------------------------------------------------------------------- | ------ |
+| `Cursor.me`                | `CursorInspectionService.me`, `CursorSdkFactory.me`                             | OK     |
+| `Cursor.models.list`       | `CursorInspectionService.listModels`, `CursorSdkFactory.listModels`             | OK     |
+| `Cursor.repositories.list` | `CursorInspectionService.listRepositories`, `CursorSdkFactory.listRepositories` | OK     |
+
+### Re-exported from `cursor-types`
+
+Helpers and errors such as `AuthenticationError`, local run stream decoders, `createAgentPlatform`, etc. See [`src/cursor-types.ts`](../src/cursor-types.ts). New SDK exports are **not** automatic: add them here deliberately to avoid semver surprises.
+
+## Optional audit script
+
+From the repo root (after `bun install` so `@cursor/sdk` is present):
+
+```bash
+bun run sdk-audit
+```
+
+The script compares known wrapper operations to exports reachable from `@cursor/sdk` and prints gaps. It is advisory: some SDK exports are types-only or platform binaries.
+
+## Release alignment
+
+When bumping `@cursor/sdk`:
+
+1. Run `bun run sdk-audit`.
+2. Update this checklist if new `Agent` / `Cursor` methods appear.
+3. Update `CursorSdkFactoryShape`, live implementation, and `makeMockSdkFactoryLayer` mocks in lockstep.
+4. Run `bun run verify:publish` and `bun run examples:typecheck`.
+
+See also [RELEASE_CHECKLIST.md](./RELEASE_CHECKLIST.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effect-cursor-sdk",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Effect-based wrapper around the Cursor SDK",
   "keywords": [
     "cursor",
@@ -21,7 +21,8 @@
     "dist",
     "README.md",
     "DEPRECATIONS.md",
-    "LICENSE"
+    "LICENSE",
+    "docs"
   ],
   "type": "module",
   "sideEffects": false,
@@ -52,15 +53,17 @@
     "examples:typecheck": "bun run --cwd examples/quickstart typecheck && bun run --cwd examples/cli typecheck && bun run --cwd examples/basic-agent-workflow typecheck && bun run --cwd examples/advanced-ops-dashboard typecheck",
     "examples:cli:mock": "bun run --cwd examples/cli dev -- --mock \"Summarize the mock response\"",
     "examples:advanced:mock": "bun run --cwd examples/advanced-ops-dashboard dev -- --mock --triage",
+    "sdk-audit": "bun scripts/sdk-surface-audit.ts",
+    "sdk-audit:refresh": "bun scripts/sdk-surface-audit.ts --write-baseline",
     "lint:package": "publint",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "test:watch": "vitest",
     "version": "changeset version",
-    "verify:publish": "bun run typecheck && bun run lint && bun run test && bun run build && bun run lint:package"
+    "verify:publish": "bun run typecheck && bun run sdk-audit && bun run lint && bun run test && bun run build && bun run lint:package"
   },
   "dependencies": {
-    "@cursor/sdk": "^1.0.10",
+    "@cursor/sdk": "^1.0.12",
     "effect-cursor-sdk": "."
   },
   "devDependencies": {