@momentiq/dark-factory-cli 0.1.0-alpha.4

package/dist/adapters/cursor-sdk.d.ts

@@ -0,0 +1,153 @@
+import { type CriticConfig, type CriticResult, type CriticStatusMessage, type DoctorCheck, type ReviewPacket } from "@momentiq/dark-factory-schemas";
+import type { CriticAdapter, CriticReviewOptions } from "./critic.js";
+export { normalizeCriticEcho } from "./_shared.js";
+export declare const CURSOR_SDK_ADAPTER_ID = "cursor-sdk";
+export declare const CURSOR_API_KEY_ENV = "CURSOR_API_KEY";
+export declare const RETRY_BACKOFF_MS: readonly number[];
+export declare const PERMANENT_ERROR_CODES: ReadonlySet<string>;
+export type AttemptOutcome = {
+    kind: "success";
+    result: CriticResult;
+} | {
+    kind: "retryable_failure";
+    errorCode: string | null;
+    statusMessage: CriticStatusMessage | null;
+    message: string;
+    runId: string | null;
+    agentId: string | null;
+} | {
+    kind: "permanent_failure";
+    errorCode: string | null;
+    statusMessage: CriticStatusMessage | null;
+    result: CriticResult;
+};
+export type RetryableFailure = Extract<AttemptOutcome, {
+    kind: "retryable_failure";
+}>;
+/**
+ * Cycle 322.1 — Pure retry-loop runner.
+ *
+ * Drives a sequence of `attempt(idx)` calls under the
+ * {@link RETRY_BACKOFF_MS} schedule, dispatching on the returned
+ * {@link AttemptOutcome}:
+ *  - `success` / `permanent_failure` → return immediately, no more
+ *    attempts.
+ *  - `retryable_failure` → record the failure and (if budget
+ *    remains) sleep + try again.
+ *
+ * Honors `signal` between attempts and during backoff sleeps; on
+ * abort, builds a terminal result via `buildExhausted` with the
+ * last failure context (so callers can surface "what was the last
+ * upstream error" even when cancellation cut the loop short).
+ *
+ * Extracted as a free function so:
+ *  - 322.2 Gemini and 322.3 Grok adapters inherit the retry pattern
+ *    without copy-paste drift.
+ *  - The loop is unit-testable with scripted outcomes + a mock
+ *    `sleep` (see `tests/cursor-retry-loop.test.ts`) — no SDK mock
+ *    required.
+ */
+export declare function runRetryLoop(args: {
+    attempt: (idx: number) => Promise<AttemptOutcome>;
+    signal?: AbortSignal;
+    sleep?: (idx: number, signal: AbortSignal | undefined) => Promise<void>;
+    buildExhausted: (info: {
+        last: RetryableFailure | null;
+        totalAttempts: number;
+        aborted: boolean;
+    }) => CriticResult;
+}): Promise<CriticResult>;
+export declare class CursorSdkAdapter implements CriticAdapter {
+    private readonly options;
+    readonly id = "cursor-sdk";
+    readonly requiredEnvVars: readonly string[];
+    constructor(options?: {
+        apiKey?: string;
+    });
+    review(packet: ReviewPacket, critic: CriticConfig, options: CriticReviewOptions): Promise<CriticResult>;
+    private attemptReview;
+    doctor(critic: CriticConfig): Promise<DoctorCheck[]>;
+}
+export declare function buildModelSelection(critic: CriticConfig): {
+    id: string;
+    params?: Array<{
+        id: string;
+        value: string;
+    }>;
+};
+export declare function checkRunFinished(runStatus: string | undefined): string | null;
+export declare function extractRuntimeModel(agent: unknown): {
+    id: string;
+    params?: Array<{
+        id: string;
+        value: string;
+    }>;
+} | undefined;
+/**
+ * Pull structured status fields from an SDKStatusMessage stream event.
+ *
+ * The Cursor SDK streams `SDKStatusMessage` events before the terminal
+ * RunResult; when an upstream incident is in progress these carry the
+ * SDK's own human-readable explanation (e.g.,
+ * `{ status: "error", message: "Upstream model gpt-5.5 returned
+ * capacity_exceeded after retry policy exhausted" }`). The runtime
+ * shape is intentionally not pinned to a TypeScript type from the SDK
+ * because the SDK may evolve the field names; this extractor probes
+ * the documented Cursor surface AND falls back to a top-level
+ * `{ status, message }` shape so a slightly older or newer SDK still
+ * surfaces the signal.
+ *
+ * Returns `null` when the event is not a status message or lacks the
+ * structured payload (the common case — most stream events are
+ * `assistant` / `thinking` / `tool_call`).
+ */
+export declare function extractStatusMessage(event: unknown): CriticStatusMessage | null;
+/**
+ * Probe a terminal RunResult for the SDK's structured error code.
+ *
+ * The Cursor SDK has used at least four field names for this code
+ * across versions: `errorCode` (current), `error_code`, `code`, and
+ * `error.code` (nested under an `error` object). Probe in that order
+ * — first non-empty string wins. Returns `null` when none are
+ * present, which means the SDK did not surface a structured code at
+ * all (treat as "transient unless proven otherwise" so retry policy
+ * applies).
+ */
+export declare function extractRunErrorCode(result: unknown): string | null;
+/**
+ * Policy gate: decide whether a terminal Cursor SDK failure is
+ * retryable.
+ *
+ * Returns `false` (DO NOT retry) when:
+ *  - `runId` is null/undefined — the SDK never accepted the request;
+ *    this is an infrastructure failure (network, sandbox, adapter
+ *    init), not an API-layer failure that retry can paper over.
+ *  - `errorCode` is in {@link PERMANENT_ERROR_CODES} — retrying an
+ *    auth failure or quota-exceeded just wastes budget AND can mask
+ *    the real fault.
+ *
+ * Returns `true` (retry allowed) when the failure carries a `runId`
+ * AND `errorCode` is either missing OR not on the permanent-deny
+ * list. The 26/27 retryable-failure success rate documented at
+ * `RETRY_BACKOFF_MS` drives this policy without per-vendor heuristics.
+ */
+export declare function shouldRetryRunFailure(input: {
+    result: unknown;
+    errorCode: string | null;
+    runId: string | null;
+}): boolean;
+/**
+ * AbortSignal-aware sleep used between retry attempts.
+ *
+ * Resolves after `RETRY_BACKOFF_MS[idx]` ms, OR rejects immediately
+ * with an Error whose `name === "AbortError"` if the signal is (or
+ * becomes) aborted. The abort handler also clears the pending timer
+ * so a long backoff doesn't leak a Node timer after the caller
+ * cancelled.
+ *
+ * Throws synchronously (via the returned rejected promise) on
+ * out-of-range `idx` so an indexing bug in the caller fails loud
+ * instead of silently sleeping zero ms.
+ */
+export declare function sleepForRetry(idx: number, signal: AbortSignal | undefined): Promise<void>;
+//# sourceMappingURL=cursor-sdk.d.ts.map

package/dist/adapters/cursor-sdk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor-sdk.d.ts","sourceRoot":"","sources":["../../src/adapters/cursor-sdk.ts"],"names":[],"mappings":"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"}