effect-cursor-sdk 0.2.0 → 0.3.0

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,6 +1,6 @@
 # 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)
+[![npm](https://img.shields.io/npm/v/effect-cursor-sdk)](https://www.npmjs.com/package/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).
 
@@ -18,18 +18,25 @@ Effect-native access to the new [Cursor SDK](https://cursor.com/docs/sdk/typescr
 - Observable: SDK calls are wrapped in spans and metrics with secret redaction utilities.
 - Testable: mock layers and fixtures let applications test Cursor workflows without network calls.
 
+## Documentation
+
+- [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
 
 | SDK capability                                                                   | Effect wrapper                                 |
 | -------------------------------------------------------------------------------- | ---------------------------------------------- |
 | `Agent.create`, `Agent.resume`, `Agent.prompt`                                   | `CursorAgentService`                           |
 | `agent.send`, `reload`, `close`, async dispose                                   | `CursorAgentService`                           |
-| `run.wait`, `stream`, `conversation`, `cancel`, status listeners, support checks | `CursorRunService`                             |
+| `run.wait`, `stream`, `conversation`, `cancel`, status listeners / streams, support checks | `CursorRunService`                             |
 | `agent.listArtifacts`, `downloadArtifact`                                        | `CursorArtifactService`                        |
 | `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 at agent entry) |
+| 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
@@ -310,11 +317,13 @@ const testProgram = Effect.gen(function* () {
 
 The main exports are:
 
-- `CursorAgentService` (prefer `createFromConfig`, `scopedFromConfig`, `promptFromConfig`, `resumeFromConfig` with `loadCursorConfig`)
+- **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))
 - `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`
@@ -326,6 +335,7 @@ Use generated TypeScript declarations for exact signatures.
 
 ```bash
 bun run typecheck
+bun run sdk-audit
 bun run lint
 bun run format:check
 bun run test
@@ -334,8 +344,14 @@ bun run build
 bun run lint:package
 ```
 
+After a `@cursor/sdk` bump, if `sdk-audit` fails, review [docs/SDK_COVERAGE.md](./docs/SDK_COVERAGE.md) and refresh the baseline only when drift is intentional: `bun run sdk-audit:refresh`.
+
 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:
@@ -361,4 +377,4 @@ bun run version
 bun run release
 ```
 
-`bun run release` runs `typecheck`, `lint`, `test`, `build`, and `publint` before publishing to NPM.
+`bun run release` runs `verify:publish` (including `sdk-audit`) before publishing to NPM.

package/dist/index.d.ts

@@ -1,7 +1,8 @@
-import { Config, Context, Effect, Layer, ManagedRuntime, Metric, Option, Redacted, Schema, Scope, Stream } from "effect";
+import { Config, Context, Effect, Layer, ManagedRuntime, Metric, Option, Redacted, Schedule, 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";
+import * as _$effect_Duration0 from "effect/Duration";
 
 //#region src/cursor-error.d.ts
 /**
@@ -275,6 +276,14 @@ declare const agentOptionsFromConfig: (config: CursorConfig, overrides?: AgentOp
  * It uses ConfigProvider to load the environment variables
  * with their default names (`CURSOR_API_KEY`, `CURSOR_MODEL`, `CURSOR_LOCAL_CWD`)
  * from {@link cursorConfig}.
+ * Omitting `CURSOR_API_KEY` only means no default API-key-based auth will be
+ * set; callers can still provide credentials via {@link agentOptionsFromConfig}
+ * overrides or the `*FromConfig` service helpers.
+ *
+ * If the API key is not set, it will log a warning message.
+ *
+ * **NOTE**: omitting the API key will cause an unauthenticated error
+ * in subsequent calls to the Cursor SDK API.
  *
  * @example
  * ```ts
@@ -419,41 +428,51 @@ declare class CursorSdkFactory extends CursorSdkFactory_base {
  * {@link CursorAgentServiceShape.scopedFromConfig}
  * so secrets stay in `Redacted` form until {@link agentOptionsFromConfig}
  * merges into SDK {@link AgentOptions}. Plain {@link AgentOptions} entry points
- * are deprecated; see the package README.
+ * are deprecated; see `DEPRECATIONS.md` and the README at the package root.
  */
 interface CursorAgentServiceShape {
   /**
-   * @deprecated Use {@link CursorAgentServiceShape.createFromConfig} with {@link loadCursorConfig} instead
-   * of passing raw {@link AgentOptions} (including a plain `apiKey` string).
+   * @deprecated Prefer {@link CursorAgentServiceShape.createFromConfig} with {@link loadCursorConfig}
+   * instead of raw {@link AgentOptions} (including a plain `apiKey` string). Next major: `createFromConfig`
+   * is planned to become `create` with the same parameters.
    */
   readonly create: (options: AgentOptions) => Effect.Effect<SDKAgent, CursorAuthenticationError | CursorRateLimitError | CursorIntegrationNotConnectedError | CursorConfigurationError | CursorNetworkError | CursorUnknownError>;
   /**
    * Create an agent from {@link CursorConfig} and optional SDK overrides.
    *
+   * @remarks
+   * Next major: planned rename to `create` with the same signature once plain-`AgentOptions` entry points are removed.
+   *
    * @see {@link loadCursorConfig}
    * @see {@link agentOptionsFromConfig}
    */
   readonly createFromConfig: (config: CursorConfig, overrides?: AgentOptions) => Effect.Effect<SDKAgent, CursorAuthenticationError | CursorRateLimitError | CursorIntegrationNotConnectedError | CursorConfigurationError | CursorNetworkError | CursorUnknownError>;
   /**
-   * @deprecated Use {@link CursorAgentServiceShape.resumeFromConfig} with {@link loadCursorConfig} instead
-   * of passing raw {@link AgentOptions}.
+   * @deprecated Prefer {@link CursorAgentServiceShape.resumeFromConfig} with {@link loadCursorConfig}
+   * instead of raw {@link AgentOptions}. Next major: `resumeFromConfig` is planned to become `resume` with the same parameters.
    */
   readonly resume: (agentId: string, options?: Partial<AgentOptions>) => Effect.Effect<SDKAgent, CursorAuthenticationError | CursorRateLimitError | CursorIntegrationNotConnectedError | CursorConfigurationError | CursorNetworkError | CursorUnknownError>;
   /**
    * Resume an agent from {@link CursorConfig} and optional SDK overrides.
    *
+   * @remarks
+   * Next major: planned rename to `resume` with the same signature once plain-`AgentOptions` entry points are removed.
+   *
    * @see {@link loadCursorConfig}
    * @see {@link agentOptionsFromConfig}
    */
   readonly resumeFromConfig: (agentId: string, config: CursorConfig, overrides?: AgentOptions) => Effect.Effect<SDKAgent, CursorAuthenticationError | CursorRateLimitError | CursorIntegrationNotConnectedError | CursorConfigurationError | CursorNetworkError | CursorUnknownError>;
   /**
-   * @deprecated Use {@link CursorAgentServiceShape.promptFromConfig} with {@link loadCursorConfig} instead
-   * of passing raw {@link AgentOptions}.
+   * @deprecated Prefer {@link CursorAgentServiceShape.promptFromConfig} with {@link loadCursorConfig}
+   * instead of raw {@link AgentOptions}. Next major: `promptFromConfig` is planned to become `prompt` with the same parameters.
    */
   readonly prompt: (message: string, options?: AgentOptions) => Effect.Effect<RunResult, CursorAuthenticationError | CursorRateLimitError | CursorIntegrationNotConnectedError | CursorConfigurationError | CursorNetworkError | CursorUnknownError>;
   /**
    * One-shot prompt from {@link CursorConfig} and optional SDK overrides.
    *
+   * @remarks
+   * Next major: planned rename to `prompt` with the same signature once plain-`AgentOptions` entry points are removed.
+   *
    * @see {@link loadCursorConfig}
    * @see {@link agentOptionsFromConfig}
    */
@@ -463,13 +482,16 @@ interface CursorAgentServiceShape {
   readonly close: (agent: SDKAgent) => Effect.Effect<void>;
   readonly dispose: (agent: SDKAgent) => Effect.Effect<void, CursorAuthenticationError | CursorRateLimitError | CursorIntegrationNotConnectedError | CursorConfigurationError | CursorNetworkError | CursorUnknownError>;
   /**
-   * @deprecated Use {@link CursorAgentServiceShape.scopedFromConfig} with {@link loadCursorConfig} instead
-   * of passing raw {@link AgentOptions}.
+   * @deprecated Prefer {@link CursorAgentServiceShape.scopedFromConfig} with {@link loadCursorConfig}
+   * instead of raw {@link AgentOptions}. Next major: `scopedFromConfig` is planned to become `scoped` with the same parameters.
    */
   readonly scoped: (options: AgentOptions) => Effect.Effect<SDKAgent, CursorAuthenticationError | CursorRateLimitError | CursorIntegrationNotConnectedError | CursorConfigurationError | CursorNetworkError | CursorUnknownError, Scope.Scope>;
   /**
    * Acquire an agent in a scope from {@link CursorConfig} and optional SDK overrides.
    *
+   * @remarks
+   * Next major: planned rename to `scoped` with the same signature once plain-`AgentOptions` entry points are removed.
+   *
    * @see {@link loadCursorConfig}
    * @see {@link agentOptionsFromConfig}
    */
@@ -506,6 +528,8 @@ declare const CursorAgentService_base: Context.ServiceClass<CursorAgentService,
  * 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
  */
@@ -587,6 +611,7 @@ declare class CursorInspectionService extends CursorInspectionService_base {
  * @see {@link makeMockSdkFactoryLayer}
  * @category testing
  */
+type CursorMockFactoryMethod = "create" | "resume" | "prompt" | "listAgents" | "listRuns" | "getRun" | "getAgent" | "archiveAgent" | "unarchiveAgent" | "deleteAgent" | "listMessages" | "me" | "listModels" | "listRepositories";
 interface CursorMockFixtures {
   readonly agentId?: string;
   readonly runId?: string;
@@ -599,6 +624,19 @@ interface CursorMockFixtures {
   readonly models?: ReadonlyArray<SDKModel>;
   readonly repositories?: ReadonlyArray<SDKRepository>;
   readonly user?: SDKUser;
+  /**
+   * Per-`send` merged fixtures. Each `MockCursorAgent.send` increments the index;
+   * when exhausted, further sends reuse the last entry merged with the base fixtures.
+   */
+  readonly sendSequence?: ReadonlyArray<Partial<CursorMockFixtures>>;
+  /**
+   * Reject a factory method with this error (Promise rejection).
+   */
+  readonly factoryErrors?: Partial<Record<CursorMockFactoryMethod, unknown>>;
+  /** Override {@link Run.supports} per operation. */
+  readonly runSupports?: Partial<Record<RunOperation, boolean>>;
+  /** Override unsupported reasons for operations marked false in {@link runSupports}. */
+  readonly runUnsupportedReason?: Partial<Record<RunOperation, string>>;
 }
 /**
  * Deterministic SDK `Run` implementation for tests.
@@ -622,17 +660,24 @@ declare class MockCursorRun implements Run {
   #private;
   readonly streamEvents: ReadonlyArray<SDKMessage>;
   readonly waitResult: RunResult;
+  readonly behavior?: {
+    readonly supports?: Partial<Record<RunOperation, boolean>>;
+    readonly unsupportedReason?: Partial<Record<RunOperation, string>>;
+  } | undefined;
   readonly id: string;
   readonly agentId: string;
   readonly createdAt: number;
-  constructor(streamEvents: ReadonlyArray<SDKMessage>, waitResult: RunResult);
+  constructor(streamEvents: ReadonlyArray<SDKMessage>, waitResult: RunResult, behavior?: {
+    readonly supports?: Partial<Record<RunOperation, boolean>>;
+    readonly unsupportedReason?: Partial<Record<RunOperation, string>>;
+  } | undefined);
   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;
+  supports(operation: RunOperation): boolean;
+  unsupportedReason(operation: RunOperation): string | undefined;
   stream(): AsyncGenerator<SDKMessage, void>;
   conversation(): Promise<[]>;
   wait(): Promise<RunResult>;
@@ -655,6 +700,7 @@ declare class MockCursorRun implements Run {
  * @category testing
  */
 declare class MockCursorAgent implements SDKAgent {
+  #private;
   readonly fixtures: CursorMockFixtures;
   readonly agentId: string;
   readonly runs: Run[];
@@ -686,6 +732,15 @@ declare const makeMockRun: (fixtures?: CursorMockFixtures) => MockCursorRun;
  * @category testing
  */
 declare const makeMockAgent: (fixtures?: CursorMockFixtures) => MockCursorAgent;
+/**
+ * Minimal assistant {@link SDKMessage} for streaming tests.
+ *
+ * @category testing
+ */
+declare const makeMockAssistantSdkMessage: (text: string, ids?: {
+  readonly agentId?: string;
+  readonly runId?: string;
+}) => SDKMessage;
 /**
  * Layer replacing the SDK factory with deterministic mock behavior.
  *
@@ -707,6 +762,146 @@ declare const makeMockAgent: (fixtures?: CursorMockFixtures) => MockCursorAgent;
  */
 declare const makeMockSdkFactoryLayer: (fixtures?: CursorMockFixtures) => Layer.Layer<CursorSdkFactory, never, never>;
 //#endregion
+//#region src/cursor-observability.d.ts
+/**
+ * Default exponential retry for Cursor catalog-style calls (list agents, models, repos).
+ *
+ * Matches the pattern used in the advanced ops dashboard example: 150ms base, 3 attempts.
+ *
+ * @example
+ * ```ts
+ * import { CursorInspectionService, cursorCatalogRetrySchedule, liveLayer } from "effect-cursor-sdk";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const inspection = yield* CursorInspectionService;
+ *   return yield* inspection.listModels().pipe(Effect.retry(cursorCatalogRetrySchedule));
+ * }).pipe(Effect.provide(liveLayer));
+ * ```
+ *
+ * @category observability
+ */
+declare const cursorCatalogRetrySchedule: Schedule.Schedule<[_$effect_Duration0.Duration, number], unknown, never, never>;
+/**
+ * Default timeout for parallel catalog loads.
+ *
+ * @example
+ * ```ts
+ * import { CursorInspectionService, cursorCatalogLoadTimeout, liveLayer } from "effect-cursor-sdk";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const inspection = yield* CursorInspectionService;
+ *   return yield* Effect.all(
+ *     { user: inspection.me(), models: inspection.listModels() },
+ *     { concurrency: "unbounded" },
+ *   ).pipe(Effect.timeout(cursorCatalogLoadTimeout));
+ * }).pipe(Effect.provide(liveLayer));
+ * ```
+ *
+ * @category observability
+ */
+declare const cursorCatalogLoadTimeout: "45 seconds";
+/**
+ * Append assistant-visible text from a streamed {@link SDKMessage} (same rules as {@link CursorRunService.collectText}).
+ *
+ * @example
+ * ```ts
+ * import { appendAssistantSdkMessageText } from "effect-cursor-sdk";
+ * import type { SDKMessage } from "effect-cursor-sdk";
+ *
+ * const events: SDKMessage[] = []; // from run.stream()
+ * const text = events.reduce(appendAssistantSdkMessageText, "");
+ * ```
+ *
+ * @category observability
+ */
+declare const appendAssistantSdkMessageText: (text: string, event: SDKMessage) => string;
+/**
+ * Wraps a run event stream and increments {@link cursorStreamEvents} per emitted event.
+ *
+ * @example
+ * ```ts
+ * import { CursorRunService, streamEventsTracked, liveLayer } from "effect-cursor-sdk";
+ * import { Effect, Stream } from "effect";
+ * import type { Run } from "effect-cursor-sdk";
+ *
+ * declare const run: Run;
+ *
+ * const program = Effect.gen(function* () {
+ *   const runs = yield* CursorRunService;
+ *   yield* streamEventsTracked(runs.streamEvents(run)).pipe(Stream.runDrain);
+ * }).pipe(Effect.provide(liveLayer));
+ * ```
+ *
+ * @category observability
+ */
+declare const streamEventsTracked: <E>(stream: Stream.Stream<E, CursorStreamError>) => Stream.Stream<E, CursorStreamError>;
+/**
+ * Like {@link CursorRunService.collectText}, but increments {@link cursorStreamEvents} per stream chunk.
+ *
+ * @param run - SDK run handle.
+ * @param streamEvents - Typically `runs.streamEvents` from {@link CursorRunService}.
+ *
+ * @example
+ * ```ts
+ * import { collectTextTracked, CursorRunService, liveLayer } from "effect-cursor-sdk";
+ * import { Effect } from "effect";
+ * import type { Run } from "effect-cursor-sdk";
+ *
+ * declare const run: Run;
+ *
+ * const text = Effect.gen(function* () {
+ *   const runs = yield* CursorRunService;
+ *   return yield* collectTextTracked(run, (r) => runs.streamEvents(r));
+ * }).pipe(Effect.provide(liveLayer));
+ * ```
+ *
+ * @category observability
+ */
+declare const collectTextTracked: (run: Run, streamEvents: (r: Run) => Stream.Stream<SDKMessage, CursorStreamError>) => Effect.Effect<string, CursorStreamError>;
+/**
+ * Build a redacted, log-safe summary of {@link AgentOptions} **without** an API key value.
+ *
+ * @remarks
+ * Nested structures are passed through {@link redact}. Never log raw `apiKey`.
+ *
+ * @example
+ * ```ts
+ * import { summarizeAgentOptionsForLog } from "effect-cursor-sdk";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const options = { model: { id: "composer-2" }, apiKey: "secret" };
+ *   yield* Effect.logInfo("cursor run", summarizeAgentOptionsForLog(options));
+ * });
+ * ```
+ *
+ * @category observability
+ */
+declare const summarizeAgentOptionsForLog: (options: AgentOptions) => Record<string, unknown>;
+/**
+ * Attach minimal run identifiers for structured logs or span attributes.
+ *
+ * @example
+ * ```ts
+ * import { summarizeRunForLog } from "effect-cursor-sdk";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const run = { id: "run_1", agentId: "agt_1", status: "finished" as const };
+ *   yield* Effect.logDebug("run done", summarizeRunForLog(run));
+ * });
+ * ```
+ *
+ * @category observability
+ */
+declare const summarizeRunForLog: (run: {
+  readonly id: string;
+  readonly agentId: string;
+  readonly status?: string;
+}) => Record<string, unknown>;
+//#endregion
 //#region src/cursor-run.d.ts
 interface CursorRunServiceShape {
   readonly supports: (run: Run, operation: RunOperation) => boolean;
@@ -717,6 +912,15 @@ interface CursorRunServiceShape {
   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>;
+  /**
+   * Status updates as a stream (backed by {@link Run.onDidChangeStatus}).
+   *
+   * @example
+   * ```ts
+   *
+   * ```
+   */
+  readonly streamStatusChanges: (run: Run) => Stream.Stream<RunStatus, never, never>;
 }
 declare const CursorRunService_base: Context.ServiceClass<CursorRunService, "effect-cursor-sdk/cursor-run/CursorRunService", CursorRunServiceShape>;
 /**
@@ -724,8 +928,13 @@ declare const CursorRunService_base: Context.ServiceClass<CursorRunService, "eff
  *
  * @example
  * ```ts
+ * const runService = yield* CursorRunService;
+ *
+ * // Create a run with the agent service
  * const run = yield* agents.send(agent, "Refactor auth")
- * const text = yield* runs.collectText(run)
+ *
+ * // Use the run service with the created run
+ * const conversation = yield* runService.conversation(run);
  * ```
  *
  * @see {@link CursorAgentService} for creating and sending runs.
@@ -755,7 +964,7 @@ declare class CursorRunService extends CursorRunService_base {
  *
  * @category layers
  */
-declare const liveLayer: Layer.Layer<CursorArtifactService | CursorAgentService | CursorSdkFactory | CursorRunService | CursorInspectionService, never, never>;
+declare const liveLayer: Layer.Layer<CursorAgentService | CursorSdkFactory | CursorArtifactService | CursorInspectionService | CursorRunService, never, never>;
 /**
  * Deterministic mock layer for tests and examples.
  *
@@ -773,7 +982,7 @@ declare const liveLayer: Layer.Layer<CursorArtifactService | CursorAgentService
  *
  * @category layers
  */
-declare const mockLayer: (fixtures?: CursorMockFixtures) => Layer.Layer<CursorArtifactService | CursorAgentService | CursorSdkFactory | CursorRunService | CursorInspectionService, never, never>;
+declare const mockLayer: (fixtures?: CursorMockFixtures) => Layer.Layer<CursorAgentService | CursorSdkFactory | CursorArtifactService | CursorInspectionService | CursorRunService, never, never>;
 /**
  * Ready-made live runtime.
  *
@@ -789,7 +998,7 @@ declare const mockLayer: (fixtures?: CursorMockFixtures) => Layer.Layer<CursorAr
  *
  * @category runtimes
  */
-declare const liveRuntime: ManagedRuntime.ManagedRuntime<CursorArtifactService | CursorAgentService | CursorSdkFactory | CursorRunService | CursorInspectionService, never>;
+declare const liveRuntime: ManagedRuntime.ManagedRuntime<CursorAgentService | CursorSdkFactory | CursorArtifactService | CursorInspectionService | CursorRunService, never>;
 /**
  * Ready-made mock runtime.
  *
@@ -806,7 +1015,7 @@ declare const liveRuntime: ManagedRuntime.ManagedRuntime<CursorArtifactService |
  *
  * @category runtimes
  */
-declare const makeMockRuntime: (fixtures?: CursorMockFixtures) => ManagedRuntime.ManagedRuntime<CursorArtifactService | CursorAgentService | CursorSdkFactory | CursorRunService | CursorInspectionService, never>;
+declare const makeMockRuntime: (fixtures?: CursorMockFixtures) => ManagedRuntime.ManagedRuntime<CursorAgentService | CursorSdkFactory | CursorArtifactService | CursorInspectionService | CursorRunService, never>;
 //#endregion
 //#region src/cursor-telemetry.d.ts
 /**
@@ -880,7 +1089,7 @@ declare const cursorStreamEvents: Metric.Counter<number>;
  */
 declare const redact: (value: unknown) => unknown;
 /**
- * Wraps an SDK-backed {@link Effect.Effect | Effect} with consistent
+ * Wraps an SDK-backed {@link 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`).
@@ -926,5 +1135,5 @@ declare const instrument: <A, E, R>(operation: CursorOperation, effect: Effect.E
  */
 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 };
+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, CursorMockFactoryMethod, 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, appendAssistantSdkMessageText, collectTextTracked, createAgentPlatform, createInMemoryRunEventNotifier, createLocalRunEventNotifier, createSdkMessageRunStreamEvent, cursorCatalogLoadTimeout, cursorCatalogRetrySchedule, cursorConfig, cursorOperationsFailed, cursorOperationsStarted, cursorStreamEvents, decodeLocalRunStreamEvent, decodeSdkMessageRunStreamEvent, getTurnType, instrument, isTerminalLocalRunStreamEvent, liveLayer, liveRuntime, loadCursorConfig, localRunStreamEventToSdkMessage, makeMockAgent, makeMockAssistantSdkMessage, makeMockRun, makeMockRuntime, makeMockSdkFactoryLayer, mapCursorError, mockLayer, packageName, redact, startLocalRunEventNotifierServer, streamEventsTracked, summarizeAgentOptionsForLog, summarizeRunForLog };
 //# sourceMappingURL=index.d.ts.map