effect-cursor-sdk 0.2.0 → 0.3.0

package/dist/index.js

@@ -1,4 +1,4 @@
-import { Config, ConfigProvider, Context, Data, Effect, Layer, ManagedRuntime, Match, Metric, Option, Redacted, Schema, Stream } from "effect";
+import { Config, ConfigProvider, Context, Data, Effect, Layer, ManagedRuntime, Match, Metric, Option, Redacted, Schedule, Schema, Stream } from "effect";
 import { Agent, AuthenticationError, AuthenticationError as AuthenticationError$1, ConfigurationError, ConfigurationError as ConfigurationError$1, Cursor, CursorAgentError, CursorAgentError as CursorAgentError$1, CursorAgentPlatform, IntegrationNotConnectedError, IntegrationNotConnectedError as IntegrationNotConnectedError$1, NetworkError, NetworkError as NetworkError$1, RateLimitError, RateLimitError as RateLimitError$1, UnknownAgentError, UnknownAgentError as UnknownAgentError$1, UnsupportedRunOperationError, UnsupportedRunOperationError as UnsupportedRunOperationError$1, createAgentPlatform, createInMemoryRunEventNotifier, createLocalRunEventNotifier, createSdkMessageRunStreamEvent, decodeLocalRunStreamEvent, decodeSdkMessageRunStreamEvent, getTurnType, isTerminalLocalRunStreamEvent, localRunStreamEventToSdkMessage, startLocalRunEventNotifierServer } from "@cursor/sdk";
 //#region src/cursor-error.ts
 /**
@@ -237,6 +237,14 @@ const agentOptionsFromConfig = (config, overrides = {}) => {
 * 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
@@ -278,6 +286,7 @@ const loadCursorConfig = Effect.gen(function* () {
 	const provider = yield* ConfigProvider.ConfigProvider;
 	const raw = yield* cursorConfig.parse(provider);
 	const apiKey = Option.getOrUndefined(raw.apiKey);
+	if (apiKey === void 0 || apiKey === null) yield* Effect.logWarning("CURSOR_API_KEY is not set — this will cause an unauthenticated error in subsequent calls to the Cursor SDK API.");
 	const modelId = Option.getOrUndefined(raw.modelId);
 	const cwd = Option.getOrUndefined(raw.cwd);
 	return new CursorConfig({
@@ -493,7 +502,7 @@ const redact = (value) => {
 	return redactInner(value, /* @__PURE__ */ new Set(), 0);
 };
 /**
-* 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`).
@@ -566,6 +575,8 @@ const instrument = (operation, effect) => {
 * 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
 */
@@ -869,9 +880,10 @@ var MockCursorRun = class {
 	createdAt = Date.now();
 	#status;
 	#listeners = /* @__PURE__ */ new Set();
-	constructor(streamEvents, waitResult) {
+	constructor(streamEvents, waitResult, behavior) {
 		this.streamEvents = streamEvents;
 		this.waitResult = waitResult;
+		this.behavior = behavior;
 		this.id = waitResult.id;
 		this.agentId = streamEvents[0]?.agent_id ?? "mock-agent";
 		this.#status = waitResult.status;
@@ -891,10 +903,14 @@ var MockCursorRun = class {
 	get git() {
 		return this.waitResult.git;
 	}
-	supports(_operation) {
-		return true;
+	supports(operation) {
+		const override = this.behavior?.supports?.[operation];
+		return override !== void 0 ? override : true;
+	}
+	unsupportedReason(operation) {
+		if (this.supports(operation)) return void 0;
+		return this.behavior?.unsupportedReason?.[operation] ?? "unsupported in mock";
 	}
-	unsupportedReason(_operation) {}
 	async *stream() {
 		yield* this.streamEvents;
 	}
@@ -934,6 +950,7 @@ var MockCursorAgent = class {
 	agentId;
 	runs = [];
 	closed = false;
+	#sendIndex = 0;
 	constructor(fixtures = {}) {
 		this.fixtures = fixtures;
 		this.agentId = fixtures.agentId ?? "mock-agent";
@@ -942,7 +959,14 @@ var MockCursorAgent = class {
 		return this.fixtures.result?.model;
 	}
 	async send(_message, _options) {
-		const run = makeMockRun(this.fixtures);
+		const seq = this.fixtures.sendSequence;
+		const piece = seq === void 0 ? void 0 : seq[Math.min(this.#sendIndex, Math.max(seq.length - 1, 0))];
+		const merged = piece !== void 0 ? {
+			...this.fixtures,
+			...piece
+		} : this.fixtures;
+		if (seq !== void 0) this.#sendIndex++;
+		const run = makeMockRun(merged);
 		this.runs.push(run);
 		return run;
 	}
@@ -974,6 +998,9 @@ const makeMockRun = (fixtures = {}) => {
 		id: runId,
 		status: "finished",
 		result: ""
+	}, {
+		supports: fixtures.runSupports,
+		unsupportedReason: fixtures.runUnsupportedReason
 	});
 };
 /**
@@ -988,6 +1015,29 @@ const makeMockAgent = (fixtures = {}) => {
 	return new MockCursorAgent(fixtures);
 };
 /**
+* Minimal assistant {@link SDKMessage} for streaming tests.
+*
+* @category testing
+*/
+const makeMockAssistantSdkMessage = (text, ids = {}) => {
+	return {
+		type: "assistant",
+		agent_id: ids.agentId ?? "mock-agent",
+		run_id: ids.runId ?? "mock-run",
+		message: {
+			role: "assistant",
+			content: [{
+				type: "text",
+				text
+			}]
+		}
+	};
+};
+const rejectFactory = (fixtures, method) => {
+	const err = fixtures.factoryErrors?.[method];
+	if (err !== void 0) return Promise.reject(err);
+};
+/**
 * Layer replacing the SDK factory with deterministic mock behavior.
 *
 * This is the lowest-level mock entry point. Prefer {@link mockLayer} when you
@@ -1009,12 +1059,14 @@ const makeMockAgent = (fixtures = {}) => {
 const makeMockSdkFactoryLayer = (fixtures = {}) => {
 	return Layer.succeed(CursorSdkFactory, CursorSdkFactory.of({
 		create: (_options) => {
-			return Promise.resolve(makeMockAgent(fixtures));
+			return rejectFactory(fixtures, "create") ?? Promise.resolve(makeMockAgent(fixtures));
 		},
 		resume: (_agentId, _options) => {
-			return Promise.resolve(makeMockAgent(fixtures));
+			return rejectFactory(fixtures, "resume") ?? Promise.resolve(makeMockAgent(fixtures));
 		},
 		prompt: async (_message, _options) => {
+			const early = rejectFactory(fixtures, "prompt");
+			if (early) return early;
 			return fixtures.result ?? {
 				id: fixtures.runId ?? "mock-run",
 				status: "finished",
@@ -1022,15 +1074,23 @@ const makeMockSdkFactoryLayer = (fixtures = {}) => {
 			};
 		},
 		listAgents: async (_options) => {
+			const early = rejectFactory(fixtures, "listAgents");
+			if (early) return early;
 			return { items: [...fixtures.agents ?? []] };
 		},
 		listRuns: async (_agentId, _options) => {
+			const early = rejectFactory(fixtures, "listRuns");
+			if (early) return early;
 			return { items: [makeMockRun(fixtures)] };
 		},
 		getRun: async (_runId, _options) => {
+			const early = rejectFactory(fixtures, "getRun");
+			if (early) return early;
 			return makeMockRun(fixtures);
 		},
 		getAgent: async (_agentId, _options) => {
+			const early = rejectFactory(fixtures, "getAgent");
+			if (early) return early;
 			return fixtures.agents?.[0] ?? {
 				agentId: fixtures.agentId ?? "mock-agent",
 				name: "Mock Agent",
@@ -1038,35 +1098,250 @@ const makeMockSdkFactoryLayer = (fixtures = {}) => {
 				lastModified: 0
 			};
 		},
-		archiveAgent: async (_agentId, _options) => {},
-		unarchiveAgent: async (_agentId, _options) => {},
-		deleteAgent: async (_agentId, _options) => {},
+		archiveAgent: async (_agentId, _options) => {
+			const early = rejectFactory(fixtures, "archiveAgent");
+			if (early) return early;
+		},
+		unarchiveAgent: async (_agentId, _options) => {
+			const early = rejectFactory(fixtures, "unarchiveAgent");
+			if (early) return early;
+		},
+		deleteAgent: async (_agentId, _options) => {
+			const early = rejectFactory(fixtures, "deleteAgent");
+			if (early) return early;
+		},
 		listMessages: async (_agentId, _options) => {
+			const early = rejectFactory(fixtures, "listMessages");
+			if (early) return early;
 			return [...fixtures.messages ?? []];
 		},
 		me: async (_options) => {
+			const early = rejectFactory(fixtures, "me");
+			if (early) return early;
 			return fixtures.user ?? {
 				apiKeyName: "mock",
 				createdAt: "1970-01-01T00:00:00.000Z"
 			};
 		},
 		listModels: async (_options) => {
+			const early = rejectFactory(fixtures, "listModels");
+			if (early) return early;
 			return [...fixtures.models ?? []];
 		},
 		listRepositories: async (_options) => {
+			const early = rejectFactory(fixtures, "listRepositories");
+			if (early) return early;
 			return [...fixtures.repositories ?? []];
 		}
 	}));
 };
 //#endregion
+//#region src/cursor-observability.ts
+/**
+* Reusable observability helpers: stream metrics, retry schedules, and safe summaries.
+*
+* @example
+* ```ts
+* import {
+*   cursorCatalogLoadTimeout,
+*   cursorCatalogRetrySchedule,
+*   CursorInspectionService,
+*   liveLayer,
+* } from "effect-cursor-sdk";
+* import { Effect } from "effect";
+*
+* const catalog = 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));
+* ```
+*
+* @module
+*/
+/**
+* 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
+*/
+const cursorCatalogRetrySchedule = Schedule.exponential("150 millis").pipe(Schedule.both(Schedule.recurs(3)));
+/**
+* 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
+*/
+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
+*/
+const appendAssistantSdkMessageText = (text, event) => {
+	if (event.type !== "assistant") return text;
+	return text + event.message.content.filter((block) => {
+		return block.type === "text";
+	}).map((block) => {
+		return block.text;
+	}).join("");
+};
+/**
+* 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
+*/
+const streamEventsTracked = (stream) => {
+	return stream.pipe(Stream.tap(() => Effect.void.pipe(Effect.trackSuccesses(cursorStreamEvents.pipe(Metric.withConstantInput(1))))));
+};
+/**
+* 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
+*/
+const collectTextTracked = (run, streamEvents) => {
+	return streamEventsTracked(streamEvents(run)).pipe(Stream.runFold(() => "", appendAssistantSdkMessageText));
+};
+/**
+* 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
+*/
+const summarizeAgentOptionsForLog = (options) => {
+	const mcpKeys = options.mcpServers ? Object.keys(options.mcpServers) : void 0;
+	return redact({
+		model: options.model,
+		name: options.name,
+		agentId: options.agentId,
+		local: options.local,
+		cloud: options.cloud ? {
+			reposCount: options.cloud.repos?.length,
+			autoCreatePR: options.cloud.autoCreatePR,
+			workOnCurrentBranch: options.cloud.workOnCurrentBranch,
+			envType: options.cloud.env?.type
+		} : void 0,
+		mcpServerNames: mcpKeys,
+		agentsCount: options.agents ? Object.keys(options.agents).length : void 0
+	});
+};
+/**
+* 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
+*/
+const summarizeRunForLog = (run) => {
+	return {
+		runId: run.id,
+		agentId: run.agentId,
+		status: run.status
+	};
+};
+//#endregion
 //#region src/cursor-run.ts
 /**
 * Effect-native helpers for SDK run handles.
 *
 * @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.
@@ -1130,6 +1405,31 @@ var CursorRunService = class CursorRunService extends Context.Service()("effect-
 		onDidChangeStatus: (run, listener) => {
 			return Effect.sync(() => run.onDidChangeStatus(listener));
 		},
+		streamStatusChanges: (run) => {
+			return Stream.fromAsyncIterable((async function* () {
+				const pending = [];
+				let notify;
+				const unsub = run.onDidChangeStatus((status) => {
+					pending.push(status);
+					const resume = notify;
+					notify = void 0;
+					resume?.();
+				});
+				try {
+					while (true) {
+						if (pending.length > 0) {
+							yield pending.shift();
+							continue;
+						}
+						await new Promise((resolve) => {
+							notify = resolve;
+						});
+					}
+				} finally {
+					unsub();
+				}
+			})(), () => void 0);
+		},
 		collectText: (run) => {
 			return Stream.fromAsyncIterable(run.stream(), (cause) => {
 				return mapCursorError(cause, {
@@ -1232,6 +1532,6 @@ const makeMockRuntime = (fixtures = {}) => {
 */
 const packageName = "effect-cursor-sdk";
 //#endregion
-export { AuthenticationError, ConfigurationError, CursorAgentError, CursorAgentPlatform, CursorAgentService, CursorApiKey, CursorArtifactService, CursorAuthenticationError, CursorConfig, CursorConfigurationError, CursorInspectionService, CursorIntegrationNotConnectedError, CursorLocalCwd, CursorModelId, CursorNetworkError, CursorRateLimitError, CursorRunFailedError, CursorRunService, CursorSdkFactory, CursorStreamError, CursorUnknownError, CursorUnsupportedOperationError, IntegrationNotConnectedError, MockCursorAgent, MockCursorRun, NetworkError, RateLimitError, 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 { AuthenticationError, ConfigurationError, CursorAgentError, CursorAgentPlatform, CursorAgentService, CursorApiKey, CursorArtifactService, CursorAuthenticationError, CursorConfig, CursorConfigurationError, CursorInspectionService, CursorIntegrationNotConnectedError, CursorLocalCwd, CursorModelId, CursorNetworkError, CursorRateLimitError, CursorRunFailedError, CursorRunService, CursorSdkFactory, CursorStreamError, CursorUnknownError, CursorUnsupportedOperationError, IntegrationNotConnectedError, MockCursorAgent, MockCursorRun, NetworkError, RateLimitError, 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.js.map