@ambitresearch/genie 1.3.1

package/dist/llm/retry.js

@@ -0,0 +1,475 @@
+/**
+ * Retry/backoff middleware (M2-06, DRO-253) — wraps an async LLM handler and
+ * retries transient failures with exponential-jittered backoff, honouring
+ * `Retry-After`, capped by `GENIE_LLM_RETRY_MAX`, surfacing a typed
+ * `RateLimitedError | TransientError` on exhaustion, and logging one line
+ * per retry to **stderr** (never stdout — on the stdio MCP transport, stdout
+ * IS the JSON-RPC protocol stream, and any stray line there corrupts every
+ * client's message framing; see `client.ts` / `plans/index.ts` /
+ * `middleware/plan-guard.ts` for the same convention).
+ *
+ * Composed as `withRetry(createChatCompletion)` at the call sites of every
+ * future generation verb (`conjure` / `refine`, M2-03 / M2-04). Kept as a
+ * generic HOF rather than baked into `client.ts` for two reasons:
+ *   1. `client.ts` deliberately makes exactly one attempt per call (see the
+ *      comment on `maxRetries: 0` there) so retry policy lives in exactly
+ *      one place — this file — where its "max N attempts" and "each attempt
+ *      logged" guarantees can't be silently double-counted by SDK-internal
+ *      retries happening a layer below.
+ *   2. A future non-chat handler (say, an embedding call) can be wrapped
+ *      the same way without knowing anything about the chat completions
+ *      surface.
+ *
+ * Retryability discriminates by the openai SDK's real error class hierarchy
+ * (`RateLimitError` / `InternalServerError` / `APIConnectionError` /
+ * `APIConnectionTimeoutError`) rather than by string-matching on `err.code`
+ * or `err.message`: global `fetch` wraps a socket-reset root cause as
+ * `TypeError('fetch failed')` and the SDK re-wraps that as an
+ * `APIConnectionError` — meaning the ECONNRESET code lives two levels deep
+ * at `err.cause.cause.code` and cannot be found by looking at the outermost
+ * error's own properties. The instanceof checks are the primary discriminator;
+ * the deep-cause code check is a belt-and-braces fallback for any transport
+ * that surfaces a raw node error without the SDK wrapping (e.g. a pre-request
+ * DNS failure, or a future alternate transport).
+ */
+import { APIConnectionError, APIConnectionTimeoutError, APIError, InternalServerError, RateLimitError, } from "openai";
+// ─── Constants ───────────────────────────────────────────────────────────
+/** Env var that overrides the default retry ceiling (AC5). */
+export const RETRY_MAX_ENV = "GENIE_LLM_RETRY_MAX";
+/** Default retry ceiling when the env var is unset / invalid (AC5). */
+export const DEFAULT_RETRY_MAX = 3;
+/** Base backoff delay: 1 s (AC4). */
+export const BASE_DELAY_MS = 1_000;
+/** Backoff cap: 30 s (AC4). */
+export const MAX_DELAY_MS = 30_000;
+/** Jitter multiplier applied symmetrically around the exponential value (AC4: ±20 %). */
+export const JITTER_RATIO = 0.2;
+/**
+ * Hard ceiling on an upstream-honoured `Retry-After` value once it's used as
+ * an actual `sleep()` duration (Copilot review on PR #126 / DRO-253).
+ * `MAX_DELAY_MS` only bounds OUR OWN computed exponential backoff — a value
+ * entirely within this module's control — but an honoured `Retry-After` is
+ * trusted verbatim by `parseRetryAfter`. A misconfigured or hostile upstream
+ * sending e.g. `Retry-After: 86400` (one day) would otherwise stall the
+ * in-flight call — and on the stdio MCP transport, the whole in-flight
+ * request — for that entire duration: `GENIE_LLM_REQUEST_TIMEOUT_MS` only
+ * bounds each individual HTTP request, not the sleep between retries.
+ *
+ * Set to 60 s — double `MAX_DELAY_MS` — so an explicit upstream signal is
+ * still granted more deference than our own guessed-at exponential
+ * schedule, while remaining bounded to a duration reasonable for a
+ * synchronous MCP tool call. (The reviewer described this figure as the
+ * `openai` SDK's own clamp; the SDK actually applies no such clamp — see
+ * `retryRequest`/`calculateDefaultRetryTimeoutMillis` in
+ * `openai/client.js`, which honours an unclamped `Retry-After` exactly as
+ * this module did before this fix. 60 s is picked on its own merits here,
+ * not inherited from upstream SDK behaviour.)
+ *
+ * Only the `sleep()` duration is clamped. `RateLimitedError.retryAfterMs`
+ * (surfaced to the caller on exhaustion, see `withRetry` below)
+ * deliberately keeps the TRUE, unclamped upstream value — that field's
+ * contract is "what did the upstream ask for" (e.g. so a UI layer can show
+ * "come back tomorrow"), not "how long did we actually wait".
+ */
+export const MAX_RETRY_AFTER_MS = 60_000;
+/**
+ * Node socket / DNS error codes that indicate a transient network failure
+ * worth retrying (AC2), when found on a RAW node error that bypasses the
+ * openai SDK's own error classes entirely (see the fallback branch at the
+ * bottom of `classifyError`). Kept intentionally narrow.
+ */
+const RETRYABLE_NETWORK_CODES = new Set(["ECONNRESET", "ETIMEDOUT"]);
+/**
+ * Node error codes that indicate a PERMANENT connection failure on an
+ * `APIConnectionError` — retrying won't help because the target
+ * fundamentally isn't reachable, as opposed to a transient peer reset or
+ * timeout (Copilot review on PR #126 / DRO-253). Used as a DENYLIST
+ * (exclude these, retry everything else) rather than an allowlist,
+ * deliberately:
+ *
+ * An earlier version of this fix tried the allowlist shape — only retry
+ * `APIConnectionError` when its cause code is in `RETRYABLE_NETWORK_CODES`
+ * — and it broke this file's OWN real-socket-destroy integration test
+ * (`recovers from a mid-flight socket destroy`, see `retry.test.ts`): a
+ * genuine peer-reset under Node's real `fetch`/undici stack surfaces as
+ * `SocketError` with code `UND_ERR_SOCKET`, one cause-level shallower than
+ * — and spelled entirely differently from — the `ECONNRESET` the mocked
+ * unit tests assume. An allowlist keyed on the wrong/incomplete code set
+ * would silently stop retrying the exact real-world failure this
+ * middleware exists to recover from. A denylist degrades safely instead:
+ * an unrecognised or future code still retries (matching this module's
+ * original, evidence-backed default), while the two well-understood
+ * permanent cases below stop burning the retry budget on a call that will
+ * never succeed:
+ *   - `ECONNREFUSED` — nothing is listening at the target address; a
+ *     retry a second later won't change that.
+ *   - `ENOTFOUND` — DNS has no record for the hostname at all (distinct
+ *     from `EAI_AGAIN`, "temporary failure in name resolution", which IS
+ *     transient by definition and deliberately stays off this list).
+ *
+ * TLS handshake rejection is NOT enumerated here: unlike the two codes
+ * above, there's no single stable, version-independent error code to key
+ * on across Node/undici/OpenSSL versions — guessing one wrong would give
+ * false confidence rather than real protection. It falls through to the
+ * safe "retry by default" behaviour like any other unrecognised code.
+ */
+const PERMANENT_CONNECTION_CODES = new Set(["ECONNREFUSED", "ENOTFOUND"]);
+// ─── Errors ──────────────────────────────────────────────────────────────
+/**
+ * Thrown when a 429 rate-limit response was retried the full budget and the
+ * upstream never gave a non-429 answer (AC6). Kept distinct from
+ * `TransientError` so callers that want to surface `ERR_RATE_LIMITED`
+ * separately from generic-transient-failure can branch on the type — matches
+ * the FR-046 PRD note about surfacing rate-limits distinctly.
+ *
+ * `retryAfterMs` carries the last `Retry-After` value (in milliseconds) the
+ * upstream sent, so a UI layer can show "come back in ~30 s" without having
+ * to unwrap the cause itself. Undefined if the final response carried no
+ * `Retry-After` header.
+ */
+export class RateLimitedError extends Error {
+    attempts;
+    cause;
+    retryAfterMs;
+    name = "RateLimitedError";
+    constructor(message, attempts, cause, retryAfterMs) {
+        super(message, { cause });
+        this.attempts = attempts;
+        this.cause = cause;
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+/**
+ * Thrown when a 5xx / network error was retried the full budget and the
+ * upstream never recovered (AC6). Callers that don't care about the
+ * distinction from `RateLimitedError` should catch `TransientError |
+ * RateLimitedError` as a union; both extend `Error` and both preserve the
+ * originating cause on `.cause`.
+ */
+export class TransientError extends Error {
+    attempts;
+    cause;
+    name = "TransientError";
+    constructor(message, attempts, cause) {
+        super(message, { cause });
+        this.attempts = attempts;
+        this.cause = cause;
+    }
+}
+// ─── Env resolution (AC5) ────────────────────────────────────────────────
+/**
+ * Resolve `GENIE_LLM_RETRY_MAX`, falling back to `DEFAULT_RETRY_MAX` when
+ * unset, blank, non-numeric, or negative. Mirrors the established fallback
+ * shape of `resolveTimeoutMs` in `client.ts` and `getPlanTTL` in
+ * `plans/index.ts`.
+ *
+ * A concrete `"0"` is a legitimate operator choice — one attempt, no retries
+ * — and must NOT be collapsed with "unset". An operator running against a
+ * test lab where they own the retry policy externally sets 0 and expects
+ * exactly 1 attempt, not 4.
+ *
+ * Requires the trimmed value to be ENTIRELY digits (Copilot review on PR
+ * #126 / DRO-253): `parseInt` alone silently accepts a leading-numeric
+ * prefix — `parseInt("5s", 10)` and `parseInt("3.5", 10)` both parse as
+ * valid (5 and 3 respectively) despite neither being a clean integer,
+ * contradicting this function's own "non-numeric → default" contract and
+ * silently misconfiguring an operator who fat-fingered the env var (e.g.
+ * copy-pasted a value with a trailing unit). The regex guard rejects
+ * anything that isn't purely `[0-9]+` before `parseInt` ever sees it.
+ */
+export function resolveRetryMax(env = process.env) {
+    const raw = env[RETRY_MAX_ENV];
+    if (raw !== undefined) {
+        const trimmed = raw.trim();
+        if (/^\d+$/.test(trimmed)) {
+            const parsed = parseInt(trimmed, 10);
+            if (!isNaN(parsed) && parsed >= 0) {
+                return parsed;
+            }
+        }
+    }
+    return DEFAULT_RETRY_MAX;
+}
+// ─── Retry-After parsing (AC3) ───────────────────────────────────────────
+/**
+ * Parse an HTTP `Retry-After` header (or the non-standard `retry-after-ms`)
+ * into milliseconds (AC3).
+ *
+ * Precedence:
+ *   1. `retry-after-ms` (millisecond precision, non-standard but common)
+ *   2. `retry-after` as fractional seconds (RFC 9110 delay-seconds form)
+ *   3. `retry-after` as HTTP-date (RFC 9110 date form) → delta from now,
+ *      clamped to 0 if the date is in the past.
+ *
+ * Returns `null` for absent, empty, or unparseable values — the caller then
+ * falls back to the jittered exponential schedule (AC4).
+ *
+ * The two-level parse (seconds first, HTTP-date fallback) matches the openai
+ * SDK's own `retryRequest` logic in `openai/client.js` so anyone already
+ * relying on either header form gets consistent behaviour whether they hit
+ * this wrapper or the SDK's own internal retry.
+ */
+export function parseRetryAfter(headers) {
+    if (!headers)
+        return null;
+    // 1. Millisecond-precision (non-standard, but the openai SDK recognises it).
+    const ms = headers.get("retry-after-ms");
+    if (ms) {
+        const parsed = parseFloat(ms);
+        if (!Number.isNaN(parsed) && parsed >= 0) {
+            return parsed;
+        }
+    }
+    // 2/3. Standard `retry-after`.
+    const raw = headers.get("retry-after");
+    if (!raw)
+        return null;
+    // Try delay-seconds form first — RFC 9110 §10.2.3 permits an integer
+    // (technically the ABNF is non-negative-integer, but many servers send
+    // fractional values and the openai SDK accepts them via parseFloat, so we
+    // match that lenient posture).
+    //
+    // Use a regex to distinguish "genuinely numeric" from "starts with a
+    // number then something else": `parseFloat("Wed 21 Oct")` returns
+    // `NaN`, but `parseFloat("21 Oct 2025")` returns `21`, which would
+    // silently interpret an HTTP-date as "21 seconds" if the two branches
+    // weren't strictly ordered. Round-trip stringification (`` `${n}` ===
+    // raw ``) is subtly wrong for values like `"7.0"` → `parseFloat` → `7`
+    // → `"7"`, which doesn't match; the regex sidesteps that whole class of
+    // bug by only recognising strings that ARE the numeric literal.
+    const trimmed = raw.trim();
+    if (/^\d+(\.\d+)?$/.test(trimmed)) {
+        const seconds = parseFloat(trimmed);
+        if (!Number.isNaN(seconds)) {
+            return Math.max(0, seconds * 1_000);
+        }
+    }
+    // Fall back to HTTP-date form.
+    const dateMs = Date.parse(raw);
+    if (!Number.isNaN(dateMs)) {
+        return Math.max(0, dateMs - Date.now());
+    }
+    return null;
+}
+// ─── Jittered exponential backoff (AC4) ──────────────────────────────────
+/**
+ * Compute the sleep duration for the given retry `attempt` (1-indexed —
+ * `attempt=1` is the delay before the first retry, i.e. after the initial
+ * attempt failed). Base 1 s, doubles per attempt, capped at 30 s, then a
+ * uniform ±20 % jitter applied on top (AC4).
+ *
+ * The cap is applied to the exponential value BEFORE the jitter multiplier,
+ * so at high attempt counts the delay is still bounded by
+ * `MAX_DELAY_MS * (1 + JITTER_RATIO)` on paper — but then clamped back to
+ * `MAX_DELAY_MS` a second time, so the effective ceiling is exactly 30 s
+ * (a strict interpretation of "cap 30 s" in the spec).
+ *
+ * `random` is injectable so tests can drive deterministic values without
+ * needing to stub `Math.random` globally.
+ */
+export function jitteredBackoff(attempt, random = Math.random) {
+    const exponential = BASE_DELAY_MS * Math.pow(2, attempt - 1);
+    const capped = Math.min(exponential, MAX_DELAY_MS);
+    const jitterMultiplier = 1 - JITTER_RATIO + random() * (JITTER_RATIO * 2);
+    return Math.min(Math.round(capped * jitterMultiplier), MAX_DELAY_MS);
+}
+// ─── Retryability discrimination (AC2) ───────────────────────────────────
+/**
+ * Walk `error.cause` down to `MAX_DEPTH` levels, looking for a node-style
+ * `.code` property (`ECONNRESET`, `ETIMEDOUT`, …). Global `fetch` wraps a
+ * socket-reset root cause as `TypeError('fetch failed', { cause: rootErr })`
+ * and the openai SDK re-wraps that as `APIConnectionError`, meaning the real
+ * code lives at `err.cause.cause.code` — two levels below where a naive
+ * `err.code` check would look. Depth-limited to prevent a pathological
+ * self-referential cause chain from looping.
+ */
+function findCauseCode(error) {
+    const MAX_DEPTH = 5;
+    let current = error;
+    for (let i = 0; i < MAX_DEPTH && current instanceof Error; i++) {
+        const code = current.code;
+        if (typeof code === "string")
+            return code;
+        current = current.cause;
+    }
+    return undefined;
+}
+function classifyError(error) {
+    if (error instanceof RateLimitError)
+        return "rateLimit";
+    if (error instanceof InternalServerError)
+        return "transient";
+    // Checked BEFORE the general APIConnectionError branch below because
+    // APIConnectionTimeoutError extends APIConnectionError — a client-side
+    // timeout has no wire-response context to inspect a cause code from, and
+    // maps directly to AC2's "ETIMEDOUT" bucket, so it's unconditionally
+    // retryable without needing the narrower cause-code check the plain
+    // APIConnectionError branch below applies.
+    if (error instanceof APIConnectionTimeoutError)
+        return "transient";
+    if (error instanceof APIConnectionError) {
+        // Deny-list, not allow-list (Copilot review on PR #126 / DRO-253 asked
+        // for *some* narrowing here — see `PERMANENT_CONNECTION_CODES`'s
+        // docstring for why an allowlist keyed on `RETRYABLE_NETWORK_CODES`
+        // broke this file's own real-socket-destroy integration test). Retry
+        // by default — matching this module's original, evidence-backed
+        // stance that the SDK only raises this class for wire-level failures
+        // where the request never reached a productive response — UNLESS the
+        // cause chain names one of the two well-understood permanent codes,
+        // in which case stop burning the retry budget on a call that will
+        // never succeed.
+        const networkCode = findCauseCode(error);
+        return networkCode && PERMANENT_CONNECTION_CODES.has(networkCode) ? "nonRetryable" : "transient";
+    }
+    // Non-openai APIError with a 5xx status (defensive — future SDK versions
+    // may add subclasses we haven't enumerated).
+    if (error instanceof APIError && typeof error.status === "number" && error.status >= 500) {
+        return "transient";
+    }
+    // Deep-cause network code check — catches raw node errors that bypass the
+    // openai SDK entirely (e.g. a pre-request rejection from a custom fetch).
+    const code = findCauseCode(error);
+    if (code && RETRYABLE_NETWORK_CODES.has(code))
+        return "transient";
+    return "nonRetryable";
+}
+/**
+ * Pull an HTTP status out of an openai APIError for logging. Non-openai
+ * errors and network-connection errors don't have one, so return null (AC7).
+ */
+function statusOf(error) {
+    if (error instanceof APIError) {
+        const status = error.status;
+        return typeof status === "number" ? status : null;
+    }
+    return null;
+}
+/**
+ * Pull `Retry-After` out of an openai APIError's response headers (AC3).
+ * Only present on errors carrying wire-response context (i.e. not on
+ * `APIConnectionError` / `APIConnectionTimeoutError`, which never received
+ * a response). Returns null when absent or unparseable.
+ */
+function retryAfterOf(error) {
+    if (error instanceof APIError && error.headers) {
+        return parseRetryAfter(error.headers);
+    }
+    return null;
+}
+// ─── Structured audit log (AC7) ──────────────────────────────────────────
+/**
+ * Emit one `llm.retry` audit line per retry attempt to stderr — never
+ * stdout. On the stdio MCP transport stdout IS the JSON-RPC protocol
+ * stream, and one stray line there corrupts every client's message framing
+ * (see the same-convention comment in `client.ts` on the sibling
+ * `llm.chat_completion` log).
+ *
+ * Includes `attempt` (1-indexed, matches AC7's contract), `status` (HTTP
+ * status if the error was an APIError; null for network failures), and
+ * `retryAfter` (milliseconds honoured, null if none). Deliberately does NOT
+ * include the request body, prompt, or completion text — the log is what an
+ * operator inspects afterwards, and leaking prompt content across every
+ * transient retry would be a real audit-log data leak.
+ */
+function logRetry(attempt, status, retryAfterMs) {
+    const line = JSON.stringify({
+        event: "llm.retry",
+        attempt,
+        status,
+        retryAfter: retryAfterMs,
+    });
+    process.stderr.write(line + "\n");
+}
+/**
+ * Default `setTimeout`-backed sleep. Extracted so both the default option
+ * value and any explicit `sleep` injection route through a single named
+ * function — makes stack traces in fake-timer tests self-explanatory.
+ */
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Wrap an async LLM handler with retry/backoff (AC1). Returns a function
+ * with the SAME argument list and return type as the input handler, so
+ * `withRetry(createChatCompletion)` is a drop-in replacement for
+ * `createChatCompletion` at every call site.
+ *
+ * Order of operations per attempt:
+ *   1. Call the handler.
+ *   2. On success → return the result immediately.
+ *   3. On failure → classify (AC2). Non-retryable errors propagate as-is
+ *      (the original error object, not a wrapped one — a caller that
+ *      already has instanceof/status handling for BadRequestError et al.
+ *      keeps working unchanged).
+ *   4. On retryable failure with remaining budget → emit an `llm.retry`
+ *      log line (AC7), sleep for `Retry-After` (AC3) or the jittered
+ *      backoff (AC4), then loop.
+ *   5. On retryable failure with exhausted budget → throw
+ *      `RateLimitedError` (if the tail-cause was a 429) or `TransientError`
+ *      (otherwise), preserving the original error on `.cause` (AC6).
+ *
+ * A handler that transitions from one retryable kind to another across
+ * attempts (say 429 → 503 → 500) throws whichever kind matches the LAST
+ * failing attempt, on the reasoning that "what the caller sees now" is the
+ * most useful discriminator for their fallback branch — a 429-turned-503
+ * indicates a genuinely degraded upstream, not a persistent rate-limit.
+ */
+export function withRetry(handler, opts = {}) {
+    const sleep = opts.sleep ?? defaultSleep;
+    const random = opts.random ?? Math.random;
+    const maxRetries = opts.maxRetries ?? resolveRetryMax(opts.env ?? process.env);
+    return async (...args) => {
+        let lastError;
+        // attempt 0 is the initial attempt; attempts 1..maxRetries are retries.
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                return await handler(...args);
+            }
+            catch (error) {
+                lastError = error;
+                const kind = classifyError(error);
+                if (kind === "nonRetryable") {
+                    throw error;
+                }
+                const remainingRetries = maxRetries - attempt;
+                if (remainingRetries <= 0) {
+                    // Budget exhausted — surface a typed error. Kind is derived from
+                    // the LAST failing attempt, on the reasoning that "what the
+                    // caller sees now" is the most useful discriminator (see the
+                    // JSDoc above).
+                    const err = error;
+                    const attemptsTotal = attempt + 1;
+                    if (kind === "rateLimit") {
+                        const retryAfterMs = retryAfterOf(error);
+                        throw new RateLimitedError(`LLM call exhausted ${attemptsTotal} attempts on rate-limit (429).`, attemptsTotal, err, retryAfterMs ?? undefined);
+                    }
+                    throw new TransientError(`LLM call exhausted ${attemptsTotal} attempts on transient failure.`, attemptsTotal, err);
+                }
+                // Retry — log, sleep, loop.
+                const status = statusOf(error);
+                const retryAfterMs = retryAfterOf(error);
+                // 1-indexed attempt number for the audit log (attempt=1 is the
+                // first retry, i.e. the second call overall). Logged verbatim
+                // (unclamped) — the log's `retryAfter` field records what the
+                // upstream actually asked for, same contract as
+                // `RateLimitedError.retryAfterMs` below.
+                logRetry(attempt + 1, status, retryAfterMs);
+                // Clamp only the value actually slept on (MAX_RETRY_AFTER_MS):
+                // `retryAfterMs` is trusted verbatim from the upstream response, so
+                // an unclamped sleep here would let a misconfigured or hostile
+                // upstream (e.g. `Retry-After: 86400`) stall this call — and, on
+                // the stdio MCP transport, the whole in-flight request — for that
+                // full duration. `jitteredBackoff` is already self-capping at
+                // MAX_DELAY_MS, so the clamp below is a no-op on that branch.
+                const delayMs = Math.min(retryAfterMs ?? jitteredBackoff(attempt + 1, random), MAX_RETRY_AFTER_MS);
+                await sleep(delayMs);
+            }
+        }
+        // Unreachable: the loop either returns on success or throws on the
+        // budget-exhaustion branch. TypeScript wants an explicit throw here
+        // because it can't prove the loop always terminates via one of those
+        // two branches — `throw` on the final `lastError` closes the type.
+        throw lastError;
+    };
+}
+//# sourceMappingURL=retry.js.map

package/dist/llm/retry.js.map

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

package/dist/llm/schema.d.ts

@@ -0,0 +1,129 @@
+/**
+ * `COMPONENT_SCHEMA` (M2-02) — the JSON Schema `conjure`/`refine` (M2-03/M2-04)
+ * demand from the model via `response_format: { type: "json_schema",
+ * json_schema: COMPONENT_SCHEMA }`, and that M2-07's Ajv validation pass
+ * (`validateComponent`) compiles against.
+ *
+ * Draft 7 only (AC2): no `anyOf`/`oneOf` discriminator pattern, and the only
+ * `$ref` in the whole schema is a single level deep (`manifestEntry.viewport`
+ * → `#/definitions/Viewport`, mirroring the RFC §9.20 shared-`$defs` shape).
+ * LiteLLM's structured-output passthrough to Anthropic (via tool-use) is the
+ * reason to keep nesting shallow — a deep `$ref` chain is exactly the shape
+ * that passthrough has been observed not to handle reliably.
+ *
+ * `as const satisfies JSONSchema7` (AC1) does two jobs at once: `satisfies`
+ * runs the object through `@types/json-schema`'s `JSONSchema7` shape so a
+ * typo'd keyword (e.g. `additionalProperty` instead of `additionalProperties`)
+ * is a compile error, while `as const` preserves the literal types `FromSchema`
+ * (AC7) needs to actually infer `ValidatedComponent` below rather than widening
+ * every string field to `string`.
+ */
+import type { FromSchema } from "json-schema-to-ts";
+export declare const COMPONENT_SCHEMA: {
+    readonly $schema: "http://json-schema.org/draft-07/schema#";
+    readonly $id: "https://genie.dev/schema/component.schema.json";
+    readonly title: "GenieComponent";
+    readonly description: string;
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: ["componentName", "group", "files", "manifestEntry"];
+    readonly definitions: {
+        readonly Viewport: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: ["width", "height"];
+            readonly properties: {
+                readonly width: {
+                    readonly type: "integer";
+                    readonly minimum: 1;
+                    readonly maximum: 4096;
+                };
+                readonly height: {
+                    readonly type: "integer";
+                    readonly minimum: 1;
+                    readonly maximum: 4096;
+                };
+            };
+        };
+    };
+    readonly properties: {
+        readonly componentName: {
+            readonly type: "string";
+            readonly description: "PascalCase component name, e.g. \"Button\".";
+            readonly pattern: "^[A-Z][A-Za-z0-9]{1,63}$";
+        };
+        readonly group: {
+            readonly type: "string";
+            readonly description: "Kebab-case UI-kit group/category, e.g. \"actions\".";
+            readonly pattern: "^[a-z0-9-]{1,32}$";
+        };
+        readonly files: {
+            readonly type: "array";
+            readonly description: string;
+            readonly minItems: 1;
+            readonly maxItems: 12;
+            readonly contains: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly path: {
+                        readonly type: "string";
+                        readonly pattern: "^components/[a-z0-9-]+/([A-Z][A-Za-z0-9]{1,63})/\\1\\.html$";
+                    };
+                };
+            };
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: ["path", "content", "mimeType"];
+                readonly properties: {
+                    readonly path: {
+                        readonly type: "string";
+                        readonly description: "Kit-relative path under components/<group>/<Name>/.";
+                        readonly pattern: "^components/[a-z0-9-]+/[A-Z][A-Za-z0-9]+/[A-Za-z0-9._-]+$";
+                    };
+                    readonly content: {
+                        readonly type: "string";
+                        readonly description: string;
+                        readonly minLength: 1;
+                        readonly maxLength: 65536;
+                    };
+                    readonly mimeType: {
+                        readonly type: "string";
+                        readonly description: "MIME type of `content`, e.g. \"text/html\".";
+                        readonly pattern: "^[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]*/[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]*$";
+                    };
+                };
+            };
+        };
+        readonly manifestEntry: {
+            readonly type: "object";
+            readonly description: string;
+            readonly additionalProperties: false;
+            readonly required: ["viewport"];
+            readonly properties: {
+                readonly viewport: {
+                    readonly $ref: "#/definitions/Viewport";
+                };
+                readonly subtitle: {
+                    readonly type: "string";
+                    readonly maxLength: 256;
+                };
+                readonly tags: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                    readonly maxItems: 16;
+                };
+            };
+        };
+    };
+};
+/**
+ * AC7 — TypeScript type inferred from {@link COMPONENT_SCHEMA} via
+ * `json-schema-to-ts`, so the schema (not a hand-maintained interface) is the
+ * single source of truth `conjure`/`refine`/`validateComponent` (M2-03/04/07)
+ * import against.
+ */
+export type ValidatedComponent = FromSchema<typeof COMPONENT_SCHEMA>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/llm/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/llm/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAwCpD,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6FG,CAAC;AAEjC;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC"}