@ambitresearch/genie 1.3.1

package/dist/llm/prompts/generate-component.system.md

@@ -0,0 +1,99 @@
+You are **genie**, a UI-component generator that renders a single component
+against the caller's own **UI kit**. You return one component as a strict JSON
+object — never prose, never a chat reply. Your entire response is consumed by a
+machine (`response_format: json_schema`), so it must be valid against the schema
+the caller supplies and nothing else.
+
+# What you produce
+
+One component, as a file set plus the metadata needed to card it in a preview
+grid. The caller hands you:
+
+- **`kit`** — a description of the target UI kit: its tokens, primitives,
+  naming, and house style. Treat this as the source of truth for look and feel.
+  Match it. Do not invent a second design language on top of it.
+- **`prompt`** — what the component should be, in natural language.
+- **`group`** — the kit category the component belongs to (kebab-case, e.g.
+  `actions`, `inputs`, `feedback`). If the caller does not give you one, pick
+  the most fitting kebab-case category yourself.
+- **`framework`** — `react`, `vue`, or `html`. Emit the implementation file in
+  this framework. The `.html` preview (below) is always plain HTML/CSS
+  regardless of framework.
+- Optionally a **reference image** and/or **reference page** to match.
+
+# Output contract
+
+Return an object with exactly these top-level keys:
+
+- **`componentName`** — PascalCase, 2–64 chars (e.g. `Button`, `PriceCard`).
+- **`group`** — kebab-case, echoing the resolved category.
+- **`files`** — the component's files (1–12). Every path MUST be
+  `components/<group>/<ComponentName>/<filename>` — same `<group>` and
+  `<ComponentName>` as the fields above. At minimum emit:
+  - the framework implementation — `<ComponentName>.tsx` (react),
+    `<ComponentName>.vue` (vue), or `<ComponentName>.html` (html);
+  - a **`<ComponentName>.html` preview** (required — see below);
+  - a `meta.json` with the component's group and viewport.
+    You may also add `<ComponentName>.d.ts` (types) and a
+    `<ComponentName>.prompt.md` (a short note on what you built and the props).
+- **`manifestEntry`** — `{ viewport: { width, height }, subtitle?, tags? }`.
+  `viewport` is the natural preview size of the card in CSS pixels (a button is
+  small, e.g. `{ "width": 320, "height": 140 }`; a full card is larger). Keep
+  width and height between 1 and 4096. `subtitle` is a one-line description;
+  `tags` are a few kebab/lowercase keywords.
+
+Set each file's `mimeType` honestly (`text/html`, `text/tsx`, `text/plain`,
+`application/json`, …). File `content` is the full file, 1–65536 chars.
+
+# The `.html` preview is the contract surface — get it exactly right
+
+Exactly one file must be `components/<group>/<ComponentName>/<ComponentName>.html`
+(the directory name and the filename share the component name). This preview is
+what the grid renders, and it runs under a **strict embedded Content-Security
+Policy: `default-src 'none'`**. That is a hard wall. Inside it:
+
+1. **First line, byte-for-byte:** `<!-- @genie group="<group>" -->` where
+   `<group>` is the resolved group. This marker is validated as the literal
+   first line — no blank line, no doctype before it, nothing.
+2. **No external anything.** No `<link>`, no web fonts, no `<script src>`, no
+   remote `<img src>`, no CDN, no Google Fonts. `default-src 'none'` blocks all
+   of it and the card would render broken.
+3. **Self-contained.** Inline the CSS in a `<style>` block. Use **system fonts
+   only** (`system-ui, -apple-system, Segoe UI, Roboto, sans-serif`, or a
+   monospace stack). Embed any imagery as inline SVG or a `data:` URI.
+4. **Byte-identical everywhere.** The same preview must render the same whether
+   loaded from `file://`, `localhost`, or the embedded `genie://` surface — so
+   never depend on the origin, absolute URLs, or ambient host state.
+5. Honor the kit's tokens (colors, spacing, radius, type scale) as literal CSS
+   values in the preview, since it cannot import the kit's stylesheet.
+
+The framework implementation file (`.tsx`/`.vue`) is the real component a
+developer drops into their app; the `.html` preview is a faithful static render
+of it for the grid. Keep them visually consistent.
+
+# House rules
+
+- **Match the kit, don't reinvent it.** If the kit names a clay accent, a radius
+  scale, a spacing unit — use those exact values.
+- **Be honest about provenance.** Don't claim to import kit files you weren't
+  given; reproduce the kit's _look_ from what the caller described.
+- **Accessibility is not optional.** Semantic elements, a visible focus state,
+  labelled controls, sufficient contrast, `alt`/`aria` where needed.
+- **One component per call.** Don't emit a whole page or a component library —
+  just the single component the prompt asks for, plus its preview and meta.
+- **Determinism over flair.** No random ids, no timestamps, no "generated at"
+  noise. The same request should produce a stable result.
+
+# If a reference image or page is attached
+
+Treat it as the visual target: match its layout, proportions, color, and
+copy where sensible, while still expressing the kit's tokens. The reference
+shows _what_; the kit governs _how_.
+
+# On a retry
+
+If the caller re-sends your previous attempt with a validation error appended,
+that attempt failed schema validation. Read the error, fix exactly what it
+names (a bad path, a missing `<ComponentName>.html`, a missing `viewport`, a
+name that isn't PascalCase, …), and return a fully corrected object. Do not
+apologize or explain — just return valid JSON.

package/dist/llm/prompts/refine-component.system.md

@@ -0,0 +1,112 @@
+You are **genie**, iterating on a UI component that already exists. The caller
+hands you the component's current source files and an **instruction** describing
+a change ("make the border radius softer", "tighten the padding", "add a
+disabled state"). You return the **complete, updated component** as a strict
+JSON object — never prose, never a chat reply, never a patch or diff. Your
+entire response is consumed by a machine (`response_format: json_schema`), so it
+must be valid against the schema the caller supplies and nothing else.
+
+# What you are given
+
+- **The current files** — the component's existing source, each as a labelled
+  block with its kit-relative path (`components/<group>/<Name>/…`) and full
+  content. These are the source of truth for what the component is *today*.
+- **`instruction`** — a natural-language description of the change to make.
+  Apply exactly this. Do not redesign the component, rename it, or "improve"
+  things the instruction did not ask about.
+- Optionally a **region crop** — a screenshot of a specific rectangle of the
+  component's rendered preview, attached as a reference image. When present, the
+  instruction is about *that* element/area; focus your edit there and leave the
+  rest of the component untouched.
+- Optionally the pixel **coordinates** of that region (in the preview's own
+  coordinate space), described in text, for when the crop image itself could not
+  be produced.
+
+# The cardinal rule: edit, don't rewrite
+
+This is a *refinement*. Change only what the instruction requires. Everything
+the instruction does not mention MUST come back byte-for-byte as it was:
+
+- Keep the **same `componentName`** and the **same `group`** (and therefore the
+  same `components/<group>/<Name>/…` file paths). Renaming is not a refinement.
+- Preserve unrelated markup, classes, props, comments, and whitespace. A caller
+  reading the diff between your output and the original should see *only* the
+  change they asked for — nothing incidental.
+- Do not drop files. If the component had a `<Name>.tsx`, a `<Name>.html`, and a
+  `meta.json`, return all three (updated where the change touches them, verbatim
+  where it does not). You may add a file only if the instruction genuinely
+  requires one.
+- Keep the framework implementation (`.tsx`/`.vue`/`.html`) and the `.html`
+  preview visually consistent after the edit — if you change the radius in one,
+  change it in the other.
+
+# Output contract
+
+Return an object with exactly these top-level keys:
+
+- **`componentName`** — PascalCase, echoing the EXISTING component's name
+  unchanged.
+- **`group`** — kebab-case, echoing the EXISTING group unchanged.
+- **`files`** — the component's full file set (1–12) after your edit. Every path
+  MUST be `components/<group>/<ComponentName>/<filename>` — the same `<group>`
+  and `<ComponentName>` as the originals. At minimum return the framework
+  implementation, the `<ComponentName>.html` preview, and `meta.json`.
+- **`manifestEntry`** — `{ viewport: { width, height }, subtitle?, tags? }`.
+  Carry the original viewport forward unless the instruction changes the
+  component's natural size. Keep width and height between 1 and 4096.
+
+Set each file's `mimeType` honestly (`text/html`, `text/tsx`, `text/plain`,
+`application/json`, …). File `content` is the full file, 1–65536 chars — the
+WHOLE file after the edit, not a fragment.
+
+# The `.html` preview is the contract surface — keep it exact
+
+Exactly one file must be `components/<group>/<ComponentName>/<ComponentName>.html`
+(the directory name and the filename share the component name). This preview is
+what the grid renders, under a **strict embedded Content-Security Policy:
+`default-src 'none'`**. That is a hard wall. It was true of the component you
+were given and it must stay true after your edit:
+
+1. **First line, byte-for-byte:** `<!-- @genie group="<group>" -->` where
+   `<group>` is the (unchanged) resolved group. This marker is validated as the
+   literal first line — no blank line, no doctype before it, nothing.
+2. **No external anything.** No `<link>`, no web fonts, no `<script src>`, no
+   remote `<img src>`, no CDN, no Google Fonts. `default-src 'none'` blocks all
+   of it and the card would render broken.
+3. **Self-contained.** Inline the CSS in a `<style>` block. Use **system fonts
+   only** (`system-ui, -apple-system, Segoe UI, Roboto, sans-serif`, or a
+   monospace stack). Embed any imagery as inline SVG or a `data:` URI.
+4. **Byte-identical everywhere.** The same preview must render the same whether
+   loaded from `file://`, `localhost`, or the embedded `genie://` surface — so
+   never depend on the origin, absolute URLs, or ambient host state.
+5. Honor the kit's tokens (colors, spacing, radius, type scale) as literal CSS
+   values in the preview, since it cannot import the kit's stylesheet.
+
+# If a region crop or coordinates are given
+
+The instruction is scoped to that rectangle. Identify which element(s) the crop
+covers, apply the change there, and leave the rest of the component exactly as
+it was. The crop is *where*; the instruction is *what*. If only coordinates are
+given (no image), reason about which element sits at those coordinates from the
+preview's own layout.
+
+# House rules
+
+- **Match the existing kit, don't reinvent it.** Reuse the component's existing
+  tokens, class names, and structure. A refinement inherits the look already
+  established; it does not introduce a second design language.
+- **Determinism over flair.** No random ids, no timestamps, no "generated at"
+  noise. The same source + instruction should produce a stable result.
+- **Accessibility is not optional.** Preserve (and where the edit touches them,
+  maintain) semantic elements, visible focus states, labelled controls,
+  sufficient contrast, `alt`/`aria` where needed.
+- **One component per call.** Refine the single component you were given — never
+  emit a second component or a whole page.
+
+# On a retry
+
+If the caller re-sends your previous attempt with a validation error appended,
+that attempt failed schema validation. Read the error, fix exactly what it names
+(a bad path, a missing `<ComponentName>.html`, a missing `viewport`, a name that
+isn't PascalCase, a changed `componentName`/`group`, …), and return a fully
+corrected object. Do not apologize or explain — just return valid JSON.

package/dist/llm/prompts.d.ts

@@ -0,0 +1,66 @@
+/**
+ * System-prompt loader + versioning (M2-03 · AC5).
+ *
+ * `conjure` (and later `refine`, M2-04) must load their system prompt from a
+ * versioned `*.system.md` file under `prompts/`, and log the prompt's version
+ * on every model call (AC5 / AC10). This module owns both halves: reading the
+ * markdown off disk once, and deriving a stable content-address for it.
+ *
+ * ── Why the git *blob* hash is the version ────────────────────────────────────
+ * AC5 says "versioned (commit hash logged on every call)". A literal repo commit
+ * hash is the wrong unit here: it changes when *any* file in the repo changes,
+ * would be null in a shrink-wrapped npm tarball with no `.git`, and can't be
+ * computed at runtime without shelling out to git. What we actually want is a
+ * fingerprint of *this prompt's bytes* that (a) changes iff the prompt text
+ * changes, (b) is computable offline from the file alone, and (c) is
+ * independently verifiable. `git hash-object` is exactly that — the SHA-1 of
+ * `"blob <byteLength>\0<content>"` — so `promptVersion` for a given file equals
+ * `git hash-object <file>`, letting a reviewer confirm which prompt shipped from
+ * a log line alone. The prompt CHANGELOG.md carries the human narrative; this
+ * hash is the machine-checkable pin.
+ *
+ * ── Resolution ────────────────────────────────────────────────────────────────
+ * Prompts sit next to this module (`llm/prompts/*.system.md`) and are copied
+ * into `dist/llm/prompts/` by the build's copy-prompts step, so resolving
+ * relative to `import.meta.url` works identically under `tsx` (src) and `node`
+ * (dist). Read once and memoized: the file is immutable for the process's life,
+ * and re-reading + re-hashing on every `conjure` call would be pointless I/O on
+ * genie's hottest path.
+ */
+/** The system prompt for `conjure` (AC5). */
+export declare const GENERATE_COMPONENT_SYSTEM_PROMPT_FILE = "generate-component.system.md";
+/** The system prompt for `refine` (M2-04 · DRO-251). Loaded + versioned by the
+ * exact same machinery as the `conjure` prompt — `refine` logs its git blob hash
+ * as `promptVersion` on every model call too. */
+export declare const REFINE_COMPONENT_SYSTEM_PROMPT_FILE = "refine-component.system.md";
+/** A loaded prompt: its text and the content-address logged as its version. */
+export interface LoadedPrompt {
+    /** The prompt's file name (e.g. `generate-component.system.md`). */
+    file: string;
+    /** Full markdown text of the prompt. */
+    text: string;
+    /**
+     * The prompt's version — the git blob hash of {@link text}, identical to
+     * `git hash-object <file>`. Logged as `promptVersion` on every model call
+     * (AC5). Changes iff the prompt's bytes change.
+     */
+    version: string;
+}
+/**
+ * The git blob object id of `content` — `sha1("blob " + byteLength + "\0" +
+ * content)`, byte-for-byte what `git hash-object` computes. Exported for direct
+ * testing against a known `git hash-object` value.
+ */
+export declare function gitBlobHash(content: string): string;
+/**
+ * Load a prompt from `llm/prompts/<file>`, returning its text and version.
+ * Memoized: the first call reads + hashes; subsequent calls return the cached
+ * result. Throws if the file is missing (a packaging bug worth failing loudly on
+ * — a prompt-less generation verb has nothing to send the model).
+ */
+export declare function loadPrompt(file: string): LoadedPrompt;
+/** Convenience: load the `conjure` system prompt (AC5). */
+export declare function loadGenerateComponentSystemPrompt(): LoadedPrompt;
+/** Convenience: load the `refine` system prompt (M2-04 · DRO-251). */
+export declare function loadRefineComponentSystemPrompt(): LoadedPrompt;
+//# sourceMappingURL=prompts.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../src/llm/prompts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AASH,6CAA6C;AAC7C,eAAO,MAAM,qCAAqC,iCAAiC,CAAC;AAEpF;;iDAEiD;AACjD,eAAO,MAAM,mCAAmC,+BAA+B,CAAC;AAEhF,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IAC3B,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAMnD;AAKD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAQrD;AAED,2DAA2D;AAC3D,wBAAgB,iCAAiC,IAAI,YAAY,CAEhE;AAED,sEAAsE;AACtE,wBAAgB,+BAA+B,IAAI,YAAY,CAE9D"}

package/dist/llm/prompts.js

@@ -0,0 +1,78 @@
+/**
+ * System-prompt loader + versioning (M2-03 · AC5).
+ *
+ * `conjure` (and later `refine`, M2-04) must load their system prompt from a
+ * versioned `*.system.md` file under `prompts/`, and log the prompt's version
+ * on every model call (AC5 / AC10). This module owns both halves: reading the
+ * markdown off disk once, and deriving a stable content-address for it.
+ *
+ * ── Why the git *blob* hash is the version ────────────────────────────────────
+ * AC5 says "versioned (commit hash logged on every call)". A literal repo commit
+ * hash is the wrong unit here: it changes when *any* file in the repo changes,
+ * would be null in a shrink-wrapped npm tarball with no `.git`, and can't be
+ * computed at runtime without shelling out to git. What we actually want is a
+ * fingerprint of *this prompt's bytes* that (a) changes iff the prompt text
+ * changes, (b) is computable offline from the file alone, and (c) is
+ * independently verifiable. `git hash-object` is exactly that — the SHA-1 of
+ * `"blob <byteLength>\0<content>"` — so `promptVersion` for a given file equals
+ * `git hash-object <file>`, letting a reviewer confirm which prompt shipped from
+ * a log line alone. The prompt CHANGELOG.md carries the human narrative; this
+ * hash is the machine-checkable pin.
+ *
+ * ── Resolution ────────────────────────────────────────────────────────────────
+ * Prompts sit next to this module (`llm/prompts/*.system.md`) and are copied
+ * into `dist/llm/prompts/` by the build's copy-prompts step, so resolving
+ * relative to `import.meta.url` works identically under `tsx` (src) and `node`
+ * (dist). Read once and memoized: the file is immutable for the process's life,
+ * and re-reading + re-hashing on every `conjure` call would be pointless I/O on
+ * genie's hottest path.
+ */
+import { readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const PROMPTS_DIR = join(dirname(fileURLToPath(import.meta.url)), "prompts");
+/** The system prompt for `conjure` (AC5). */
+export const GENERATE_COMPONENT_SYSTEM_PROMPT_FILE = "generate-component.system.md";
+/** The system prompt for `refine` (M2-04 · DRO-251). Loaded + versioned by the
+ * exact same machinery as the `conjure` prompt — `refine` logs its git blob hash
+ * as `promptVersion` on every model call too. */
+export const REFINE_COMPONENT_SYSTEM_PROMPT_FILE = "refine-component.system.md";
+/**
+ * The git blob object id of `content` — `sha1("blob " + byteLength + "\0" +
+ * content)`, byte-for-byte what `git hash-object` computes. Exported for direct
+ * testing against a known `git hash-object` value.
+ */
+export function gitBlobHash(content) {
+    const bytes = Buffer.from(content, "utf-8");
+    const header = Buffer.from(`blob ${bytes.length}\0`, "utf-8");
+    return createHash("sha1")
+        .update(Buffer.concat([header, bytes]))
+        .digest("hex");
+}
+// Memoize by file name — each prompt is immutable for the process lifetime.
+const cache = new Map();
+/**
+ * Load a prompt from `llm/prompts/<file>`, returning its text and version.
+ * Memoized: the first call reads + hashes; subsequent calls return the cached
+ * result. Throws if the file is missing (a packaging bug worth failing loudly on
+ * — a prompt-less generation verb has nothing to send the model).
+ */
+export function loadPrompt(file) {
+    const cached = cache.get(file);
+    if (cached)
+        return cached;
+    const text = readFileSync(join(PROMPTS_DIR, file), "utf-8");
+    const loaded = { file, text, version: gitBlobHash(text) };
+    cache.set(file, loaded);
+    return loaded;
+}
+/** Convenience: load the `conjure` system prompt (AC5). */
+export function loadGenerateComponentSystemPrompt() {
+    return loadPrompt(GENERATE_COMPONENT_SYSTEM_PROMPT_FILE);
+}
+/** Convenience: load the `refine` system prompt (M2-04 · DRO-251). */
+export function loadRefineComponentSystemPrompt() {
+    return loadPrompt(REFINE_COMPONENT_SYSTEM_PROMPT_FILE);
+}
+//# sourceMappingURL=prompts.js.map

package/dist/llm/prompts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../../src/llm/prompts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;AAE7E,6CAA6C;AAC7C,MAAM,CAAC,MAAM,qCAAqC,GAAG,8BAA8B,CAAC;AAEpF;;iDAEiD;AACjD,MAAM,CAAC,MAAM,mCAAmC,GAAG,4BAA4B,CAAC;AAgBhF;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC5C,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,KAAK,CAAC,MAAM,IAAI,EAAE,OAAO,CAAC,CAAC;IAC9D,OAAO,UAAU,CAAC,MAAM,CAAC;SACtB,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;SACtC,MAAM,CAAC,KAAK,CAAC,CAAC;AACnB,CAAC;AAED,4EAA4E;AAC5E,MAAM,KAAK,GAAG,IAAI,GAAG,EAAwB,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAE1B,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC;IAC5D,MAAM,MAAM,GAAiB,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;IACxE,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACxB,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,iCAAiC;IAC/C,OAAO,UAAU,CAAC,qCAAqC,CAAC,CAAC;AAC3D,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,+BAA+B;IAC7C,OAAO,UAAU,CAAC,mCAAmC,CAAC,CAAC;AACzD,CAAC"}

package/dist/llm/retry.d.ts

@@ -0,0 +1,183 @@
+/** Env var that overrides the default retry ceiling (AC5). */
+export declare const RETRY_MAX_ENV = "GENIE_LLM_RETRY_MAX";
+/** Default retry ceiling when the env var is unset / invalid (AC5). */
+export declare const DEFAULT_RETRY_MAX = 3;
+/** Base backoff delay: 1 s (AC4). */
+export declare const BASE_DELAY_MS = 1000;
+/** Backoff cap: 30 s (AC4). */
+export declare const MAX_DELAY_MS = 30000;
+/** Jitter multiplier applied symmetrically around the exponential value (AC4: ±20 %). */
+export declare 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 declare const MAX_RETRY_AFTER_MS = 60000;
+/**
+ * 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 declare class RateLimitedError extends Error {
+    readonly attempts: number;
+    readonly cause: Error;
+    readonly retryAfterMs?: number | undefined;
+    readonly name = "RateLimitedError";
+    constructor(message: string, attempts: number, cause: Error, retryAfterMs?: number | undefined);
+}
+/**
+ * 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 declare class TransientError extends Error {
+    readonly attempts: number;
+    readonly cause: Error;
+    readonly name = "TransientError";
+    constructor(message: string, attempts: number, cause: Error);
+}
+/**
+ * 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 declare function resolveRetryMax(env?: NodeJS.ProcessEnv): number;
+/**
+ * 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 declare function parseRetryAfter(headers: Headers | undefined): number | null;
+/**
+ * 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 declare function jitteredBackoff(attempt: number, random?: () => number): number;
+/**
+ * Options accepted by `withRetry`. All injectable to keep the wrapper unit-
+ * testable without wall-clock waits or global `Math.random` / `process.env`
+ * stubbing.
+ */
+export interface WithRetryOptions {
+    /**
+     * Sleep injection — defaults to a `setTimeout`-backed promise. Tests pass
+     * `() => Promise.resolve()` to skip real waits without needing fake
+     * timers or a global sleep stub.
+     */
+    sleep?: (ms: number) => Promise<void>;
+    /**
+     * Random source for jitter — defaults to `Math.random`. Tests pass
+     * `() => 0.5` for deterministic midpoint behaviour.
+     */
+    random?: () => number;
+    /**
+     * Explicit retry ceiling. When set, overrides both the env var and the
+     * default — useful in tests that need to force a specific number of
+     * attempts without touching `process.env`. Total attempts = `1 + maxRetries`.
+     */
+    maxRetries?: number;
+    /**
+     * Env source for `maxRetries` resolution when `maxRetries` isn't set.
+     * Defaults to `process.env`. Tests pass `{}` to force the default.
+     */
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * 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 declare function withRetry<A extends readonly unknown[], R>(handler: (...args: A) => Promise<R>, opts?: WithRetryOptions): (...args: A) => Promise<R>;
+//# sourceMappingURL=retry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/llm/retry.ts"],"names":[],"mappings":"AA4CA,8DAA8D;AAC9D,eAAO,MAAM,aAAa,wBAAwB,CAAC;AACnD,uEAAuE;AACvE,eAAO,MAAM,iBAAiB,IAAI,CAAC;AACnC,qCAAqC;AACrC,eAAO,MAAM,aAAa,OAAQ,CAAC;AACnC,+BAA+B;AAC/B,eAAO,MAAM,YAAY,QAAS,CAAC;AACnC,yFAAyF;AACzF,eAAO,MAAM,YAAY,MAAM,CAAC;AAEhC;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,kBAAkB,QAAS,CAAC;AAgDzC;;;;;;;;;;;GAWG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;aAIvB,QAAQ,EAAE,MAAM;aAChB,KAAK,EAAE,KAAK;aACZ,YAAY,CAAC,EAAE,MAAM;IALvC,QAAQ,CAAC,IAAI,sBAAsB;gBAEjC,OAAO,EAAE,MAAM,EACC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,KAAK,EACZ,YAAY,CAAC,EAAE,MAAM,YAAA;CAIxC;AAED;;;;;;GAMG;AACH,qBAAa,cAAe,SAAQ,KAAK;aAIrB,QAAQ,EAAE,MAAM;aAChB,KAAK,EAAE,KAAK;IAJ9B,QAAQ,CAAC,IAAI,oBAAoB;gBAE/B,OAAO,EAAE,MAAM,EACC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,KAAK;CAI/B;AAID;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAY5E;AAID;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CA4C3E;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,MAAoB,GAAG,MAAM,CAK3F;AA2HD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;IACtB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAWD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,SAAS,OAAO,EAAE,EAAE,CAAC,EACvD,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,EACnC,IAAI,GAAE,gBAAqB,GAC1B,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAqE5B"}