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

package/dist/adapters/grok-direct-sdk.d.ts

@@ -0,0 +1,148 @@
+import { type CriticConfig, type CriticResult, type DoctorCheck, type ReviewPacket } from "@momentiq/dark-factory-schemas";
+import type { CriticAdapter, CriticReviewOptions } from "./critic.js";
+export declare const GROK_DIRECT_SDK_ADAPTER_ID = "grok-direct-sdk";
+export declare const XAI_API_KEY_ENV = "XAI_API_KEY";
+export declare const XAI_BASE_URL = "https://api.x.ai/v1";
+export declare const GROK_PERMANENT_STATUS: ReadonlySet<number>;
+export declare const DEFAULT_REASONING_EFFORT: "high";
+export type GrokReasoningEffort = "low" | "medium" | "high" | "none";
+/**
+ * Test-shape compatible with the `openai` SDK's OpenAI client. The
+ * unit tests pass a mock conforming to this shape; production passes
+ * the real `new OpenAI({ apiKey, baseURL })` instance through the
+ * `createClient` factory on the adapter constructor.
+ *
+ * Documenting this shape here (rather than relying on the SDK's
+ * exported type) lets the test mocks stay narrow and resilient to
+ * SDK internal shape changes. The adapter uses ONLY the surface
+ * declared here — every SDK method the adapter calls is on this
+ * interface, so an SDK upgrade that re-shapes other surfaces won't
+ * silently break the adapter.
+ */
+export interface GrokClient {
+    responses: {
+        create: (params: GrokResponsesCreateParams, requestOptions?: {
+            signal?: AbortSignal;
+        }) => Promise<AsyncIterable<GrokStreamEvent>>;
+    };
+    models: {
+        list: () => AsyncIterable<{
+            id?: string;
+        }> | Promise<AsyncIterable<{
+            id?: string;
+        }>>;
+    };
+}
+export interface GrokResponsesCreateParams {
+    model: string;
+    reasoning?: {
+        effort?: GrokReasoningEffort;
+    };
+    input: Array<{
+        role: "system" | "user" | "assistant";
+        content: string;
+    }>;
+    text?: {
+        format?: {
+            type: "json_object";
+        };
+    };
+    store?: false;
+    stream: true;
+}
+/**
+ * The shape of a single xAI Responses API stream event. xAI mirrors
+ * the OpenAI Responses API stream contract, where each event carries
+ * a `type` discriminator (`response.output_text.delta`,
+ * `response.completed`, `response.failed`, `response.refusal.delta`,
+ * etc.). The adapter only reads:
+ *   - `type` (for dispatch)
+ *   - `delta` (on output_text.delta — the text accumulator)
+ *   - `response.usage.input_tokens` + `response.usage.output_tokens`
+ *     (on response.completed — the telemetry token-usage signal)
+ *   - `response.refusal_text` or similar (on response.refusal.*; the
+ *     safety-block permanent-failure path)
+ *
+ * Field shapes treated as `unknown` so the adapter is resilient to
+ * xAI extending the event envelope between when this was written and
+ * when it runs. The actual stream event shape is captured in
+ * `tools/agent-review/evals/spike-grok-responses-2026-05.md`.
+ */
+export interface GrokStreamEvent {
+    type?: string;
+    delta?: string;
+    response?: {
+        id?: string;
+        usage?: GrokUsage;
+        output?: Array<{
+            content?: Array<{
+                text?: string;
+                type?: string;
+            }>;
+        }>;
+        incomplete_details?: {
+            reason?: string;
+        };
+    };
+    refusal?: string;
+}
+export interface GrokUsage {
+    input_tokens?: number;
+    output_tokens?: number;
+    total_tokens?: number;
+    output_tokens_details?: {
+        reasoning_tokens?: number;
+    };
+}
+export interface GrokDirectSdkAdapterOptions {
+    apiKey?: string;
+    createClient?: (apiKey: string) => GrokClient;
+    sleep?: (idx: number, signal: AbortSignal | undefined) => Promise<void>;
+}
+/**
+ * Resolve the Grok reasoning-effort from the critic config's
+ * `model.params`. Falls back to {@link DEFAULT_REASONING_EFFORT}
+ * ("high") when unset. Validates against the documented
+ * Responses-API surface — invalid values fall back to the default
+ * rather than corrupting the request body.
+ *
+ * Coerces string inputs (the config schema's `value` is
+ * `string|number|boolean`; reasoning effort is always a string
+ * enum). Booleans and numbers are operator typos and use the
+ * default.
+ *
+ * Exported for direct unit testing (no SDK mock required).
+ */
+export declare function resolveReasoningEffort(critic: CriticConfig): GrokReasoningEffort;
+/**
+ * Probe a thrown error for an xAI Responses API HTTP status code.
+ * Returns `null` when the error didn't carry one (network error,
+ * non-API exception). Exported for direct unit testing.
+ *
+ * The `openai` SDK throws `APIError extends Error` with a `status:
+ * number` field on HTTP-level failures; a non-API failure (DNS,
+ * timeout in fetch, etc.) won't have this field set. Treating "no
+ * status" as retryable lets the loop catch real transient blips
+ * while not silently retrying logic errors.
+ */
+export declare function extractXaiApiErrorStatus(err: unknown): number | null;
+/**
+ * Policy gate: decide whether an xAI Responses API failure is
+ * retryable. Returns `false` for HTTP statuses in
+ * {@link GROK_PERMANENT_STATUS}, `true` otherwise (including
+ * no-status network errors).
+ *
+ * Exported for direct unit testing.
+ */
+export declare function isGrokPermanentFailure(status: number | null): boolean;
+export declare class GrokDirectSdkAdapter implements CriticAdapter {
+    private readonly options;
+    readonly id = "grok-direct-sdk";
+    readonly requiredEnvVars: readonly string[];
+    private readonly createClient;
+    constructor(options?: GrokDirectSdkAdapterOptions);
+    review(packet: ReviewPacket, critic: CriticConfig, options: CriticReviewOptions): Promise<CriticResult>;
+    private attemptReview;
+    doctor(critic: CriticConfig): Promise<DoctorCheck[]>;
+}
+//# sourceMappingURL=grok-direct-sdk.d.ts.map

package/dist/adapters/grok-direct-sdk.d.ts.map

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