@ambitresearch/genie 1.3.1

package/dist/llm/client.js

@@ -0,0 +1,141 @@
+/**
+ * LLM client wrapper (M2-01) — genie's single point of contact with the
+ * operator's configured OpenAI-compatible chat-completions endpoint.
+ *
+ * genie calls a **configurable**
+ * OpenAI-compatible endpoint. LiteLLM is the reference gateway, but Ollama /
+ * OpenAI / vLLM / any compatible endpoint work the same way — no provider URL
+ * or API key is ever hardcoded here. Both come from env vars
+ * (`GENIE_LLM_BASE_URL` / `GENIE_LLM_API_KEY`), validated at construction so a
+ * misconfigured deployment fails fast (`MissingLLMConfigError`) rather than
+ * failing confusingly deep inside a generation call.
+ *
+ * All future generation verbs (`conjure` / `refine`, M2-03/M2-04) call through
+ * `createChatCompletion` rather than importing the `openai` SDK directly, so
+ * this module is the one place that knows about env vars, timeouts, and
+ * request logging for LLM calls.
+ *
+ * Out of scope (per the M2-01 issue): retry/backoff (M2-06) — `withRetry` in
+ * a later issue wraps `createChatCompletion` itself — and structured-output
+ * schema validation (M2-07).
+ */
+import OpenAI from "openai";
+// ─── Env var names ───────────────────────────────────────────────────────────
+/** Base URL of the operator's OpenAI-compatible endpoint. No default (AC3). */
+export const GENIE_LLM_BASE_URL_ENV = "GENIE_LLM_BASE_URL";
+/** API key/token for the configured endpoint. No default (AC3). */
+export const GENIE_LLM_API_KEY_ENV = "GENIE_LLM_API_KEY";
+/** Per-request timeout override, in milliseconds. */
+export const GENIE_LLM_REQUEST_TIMEOUT_MS_ENV = "GENIE_LLM_REQUEST_TIMEOUT_MS";
+/** Default request timeout: 120 000 ms (AC5). */
+export const DEFAULT_LLM_REQUEST_TIMEOUT_MS = 120_000;
+// ─── Errors ──────────────────────────────────────────────────────────────────
+/**
+ * Thrown when one or both required LLM env vars are unset (AC2). Callers
+ * should let this propagate at startup — there is no safe fallback endpoint
+ * to construct a client against (AC3).
+ */
+export class MissingLLMConfigError extends Error {
+    missing;
+    constructor(missing) {
+        super(`Missing required LLM configuration: ${missing.join(", ")}. ` +
+            `genie has no default LLM endpoint — set ${GENIE_LLM_BASE_URL_ENV} to an ` +
+            `operator-configured OpenAI-compatible endpoint and ${GENIE_LLM_API_KEY_ENV} ` +
+            `to its API key before starting genie.`);
+        this.missing = missing;
+        this.name = "MissingLLMConfigError";
+    }
+}
+// ─── Config resolution ───────────────────────────────────────────────────────
+/**
+ * Resolve `GENIE_LLM_REQUEST_TIMEOUT_MS`, falling back to the 120s default
+ * (AC5) when unset, blank, non-numeric, or non-positive. Mirrors the
+ * established fallback shape of `getPlanTTL` in `plans/index.ts`.
+ */
+export function resolveTimeoutMs(env = process.env) {
+    const raw = env[GENIE_LLM_REQUEST_TIMEOUT_MS_ENV];
+    if (raw) {
+        const parsed = parseInt(raw, 10);
+        if (!isNaN(parsed) && parsed > 0) {
+            return parsed;
+        }
+    }
+    return DEFAULT_LLM_REQUEST_TIMEOUT_MS;
+}
+/**
+ * Construct an `openai` SDK client from env vars (AC1). Throws
+ * `MissingLLMConfigError` synchronously if `GENIE_LLM_BASE_URL` or
+ * `GENIE_LLM_API_KEY` is unset or blank (AC2/AC3) — no default base URL is
+ * ever substituted.
+ *
+ * Exported as a factory (in addition to the `llmClient` singleton below) so
+ * tests can construct additional clients against a stub server, and so a
+ * future preflight/health-check path can validate config without relying on
+ * module-load side effects.
+ */
+export function createLLMClient(env = process.env) {
+    // Trim before checking: a whitespace-only value (e.g. a stray "  " from a
+    // misconfigured .env file) is truthy and would otherwise slip past the
+    // `!baseURL`/`!apiKey` checks below, then fail later with a confusing
+    // URL-parse or auth error instead of the clear MissingLLMConfigError this
+    // function exists to raise (AC2/AC3).
+    const baseURL = env[GENIE_LLM_BASE_URL_ENV]?.trim();
+    const apiKey = env[GENIE_LLM_API_KEY_ENV]?.trim();
+    const missing = [];
+    if (!baseURL)
+        missing.push(GENIE_LLM_BASE_URL_ENV);
+    if (!apiKey)
+        missing.push(GENIE_LLM_API_KEY_ENV);
+    if (missing.length > 0)
+        throw new MissingLLMConfigError(missing);
+    return new OpenAI({
+        baseURL,
+        apiKey,
+        timeout: resolveTimeoutMs(env),
+        // The `openai` SDK retries 429/5xx/408/409 internally by default
+        // (maxRetries: 2) — invisibly to this module. M2-06 owns retry/backoff
+        // for this wrapper (typed `RateLimitedError`/`TransientError`, honouring
+        // `Retry-After`, a `GENIE_LLM_RETRY_MAX`-configurable cap, one log line
+        // per attempt) and wraps `createChatCompletion` from the outside
+        // (`withRetry(createChatCompletion)`). Leaving the SDK's own retries
+        // enabled would silently double up on that policy — M2-06's "each
+        // attempt logged" and "max N retries total" guarantees would both be
+        // undermined by extra attempts happening a layer below where it can
+        // neither see nor count them. So this client makes exactly one attempt;
+        // all retry policy lives in one place (M2-06).
+        maxRetries: 0,
+    });
+}
+// ─── Singleton ───────────────────────────────────────────────────────────────
+/**
+ * The shared `openai` client every generation verb calls through (AC1).
+ * Constructed once at module load from env vars — a deployment missing
+ * `GENIE_LLM_BASE_URL`/`GENIE_LLM_API_KEY` fails the moment anything imports
+ * this module, rather than partway through a generation request.
+ */
+export const llmClient = createLLMClient();
+/**
+ * Thin wrapper around `llmClient.chat.completions.create` (AC4). Emits a
+ * structured `{ model, promptTokens, completionTokens, latencyMs }` log line
+ * to **stderr** on success — never stdout, which on the stdio transport *is*
+ * the JSON-RPC protocol stream (see `transport.ts` / `tools/plan.ts`'s audit
+ * log for the same convention).
+ *
+ * Does not retry and does not swallow errors: a rejected `create()` call
+ * propagates to the caller untouched so M2-06's `withRetry(createChatCompletion)`
+ * can wrap this function directly.
+ */
+export async function createChatCompletion(input) {
+    const startedAt = performance.now();
+    const completion = await llmClient.chat.completions.create(input);
+    const latencyMs = Math.round(performance.now() - startedAt);
+    process.stderr.write(JSON.stringify({
+        event: "llm.chat_completion",
+        model: completion.model,
+        promptTokens: completion.usage?.prompt_tokens ?? null,
+        completionTokens: completion.usage?.completion_tokens ?? null,
+        latencyMs,
+    }) + "\n");
+    return completion;
+}
+//# sourceMappingURL=client.js.map

package/dist/llm/client.js.map

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

package/dist/llm/component-response.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Shared component-generation response harness (M2-03/M2-04).
+ *
+ * `conjure` (M2-03 · DRO-250) and `refine` (M2-04 · DRO-251) are the same
+ * request/validate/retry machine wrapped around two different prompts:
+ *   - build the messages,
+ *   - demand structured output via `response_format: { type: "json_schema", … }`,
+ *   - parse + validate the reply against `COMPONENT_SCHEMA` (M2-02) with Ajv,
+ *   - retry EXACTLY ONCE with the validation error + prior output fed back.
+ *
+ * That machinery lived inline in `conjure.ts`; M2-04's AC6 is literally "same
+ * retry-once pattern as M2-03", so rather than clone a second (drift-prone) copy
+ * of the Ajv compile, the fence-stripper, the retry-feedback wording, and the
+ * two-attempt loop, both verbs import them from here. `refine` reusing this file
+ * is what makes "same pattern" a fact of the code, not a hope about two parallel
+ * implementations staying in step.
+ *
+ * What stays tool-side: each verb owns its own **`buildMessages`** (the prompt is
+ * the whole point of the difference between the two verbs) and its own per-call
+ * structured log + typed error (their AC10/AC8 field sets differ). This module
+ * owns everything between "here are the messages" and "here is a validated
+ * component or a reason it failed".
+ */
+import { type ErrorObject } from "ajv";
+import { type ValidatedComponent } from "./schema.js";
+import type { ChatCompletionInput, ChatCompletionResult } from "./client.js";
+/** Token/cost accounting summed across the (up to two) model calls. */
+export interface UsageInfo {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+/** A fresh zeroed usage accumulator. */
+export declare function emptyUsage(): UsageInfo;
+/** Add one completion's token counts into a running {@link UsageInfo}. */
+export declare function addUsage(into: UsageInfo, completion: ChatCompletionResult): void;
+/** The chat-completion seam. Production supplies a lazy wrapper over the M2-01
+ * `createChatCompletion`; tests inject a stub so no real endpoint or
+ * `GENIE_LLM_*` env is needed. Shared by both generation verbs. */
+export type ChatCompletionFn = (input: ChatCompletionInput) => Promise<ChatCompletionResult>;
+/** Structured warn/telemetry to stderr — never stdout (the stdio transport's
+ * stdout IS the JSON-RPC stream; same convention as client.ts / plan.ts). */
+export declare function logStderr(payload: Record<string, unknown>): void;
+/** Render Ajv errors as a compact, model-readable bullet list for the retry. */
+export declare function formatAjvErrors(errors: ErrorObject[] | null | undefined): string;
+/**
+ * Some endpoints wrap JSON in a ```json fence despite `response_format`. Strip a
+ * single leading/trailing fence defensively before parsing so a cosmetically
+ * fenced-but-valid reply doesn't cost a retry.
+ */
+export declare function stripJsonFence(raw: string): string;
+/** Outcome of parsing + schema-validating one model reply. */
+export type ParseResult = {
+    ok: true;
+    component: ValidatedComponent;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Parse + schema-validate one model reply. Returns the component or a reason. */
+export declare function parseAndValidate(raw: string | null | undefined): ParseResult;
+/**
+ * The `response_format` demanded on every generation call. Wraps
+ * COMPONENT_SCHEMA in the OpenAI structured-output envelope
+ * `{ name, description, schema }` — the real wire shape a compliant endpoint
+ * (and LiteLLM's passthrough) expects.
+ */
+export declare function buildComponentResponseFormat(): ChatCompletionInput["response_format"];
+/** Context appended to a user message on the ONE retry: the validation error and
+ * the model's prior (invalid) output, so it can self-correct (M2-03 AC8). */
+export interface RetryContext {
+    reason: string;
+    previous: string;
+}
+/**
+ * Append the shared retry-feedback block to a user instruction. Same wording for
+ * both verbs so the model sees a consistent "you failed validation, fix exactly
+ * this" contract regardless of which verb it is answering. Kept as a function
+ * (not a template inlined per tool) so the wording — which the M2-03 tests pin
+ * (`"failed schema validation"`, `"previous"`) — lives in exactly one place.
+ */
+export declare function appendRetryFeedback(userText: string, retry: RetryContext): string;
+/** Builds the messages for one attempt. `retry` is `undefined` on the first
+ * attempt and carries the validation feedback on the (single) retry. */
+export type BuildMessagesFn = (retry: RetryContext | undefined) => ChatCompletionInput["messages"];
+export type ValidateGeneratedComponent = (component: ValidatedComponent) => string | undefined;
+/** Result of {@link runComponentGeneration}: the parse outcome plus the accounting
+ * a caller needs for its per-call log (attempts + summed usage). */
+export interface GenerationRun {
+    outcome: ParseResult;
+    usage: UsageInfo;
+    /** 1 if the first reply validated, 2 if it took the retry. */
+    attempts: number;
+}
+/**
+ * Run the shared generation loop: one attempt, and — only if it fails schema
+ * validation — exactly one retry with the error + prior output fed back
+ * (M2-03 AC8 / M2-04 AC6). `buildMessages` is the sole per-verb input, so
+ * `conjure` and `refine` share this identical control flow while each keeps its
+ * own prompt. Usage is summed across both attempts; `attempts` reports whether
+ * the retry fired. The caller decides what to do with a still-invalid
+ * `outcome` (throw its own typed error) and logs its own per-call line.
+ */
+export declare function runComponentGeneration(params: {
+    chat: ChatCompletionFn;
+    model: string;
+    buildMessages: BuildMessagesFn;
+    /** Optional tool-specific validation applied after the shared JSON schema. */
+    validateGeneratedComponent?: ValidateGeneratedComponent;
+}): Promise<GenerationRun>;
+//# sourceMappingURL=component-response.d.ts.map

package/dist/llm/component-response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-response.d.ts","sourceRoot":"","sources":["../../src/llm/component-response.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AASH,OAAO,EAA8B,KAAK,WAAW,EAAE,MAAM,KAAK,CAAC;AAEnE,OAAO,EAAoB,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAIxE,OAAO,KAAK,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAE7E,uEAAuE;AACvE,MAAM,WAAW,SAAS;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,wCAAwC;AACxC,wBAAgB,UAAU,IAAI,SAAS,CAEtC;AAED,0EAA0E;AAC1E,wBAAgB,QAAQ,CAAC,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,oBAAoB,GAAG,IAAI,CAIhF;AAED;;mEAEmE;AACnE,MAAM,MAAM,gBAAgB,GAAG,CAAC,KAAK,EAAE,mBAAmB,KAAK,OAAO,CAAC,oBAAoB,CAAC,CAAC;AAE7F;6EAC6E;AAC7E,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAEhE;AAaD,gFAAgF;AAChF,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAKhF;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAKlD;AAED,8DAA8D;AAC9D,MAAM,MAAM,WAAW,GACnB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,SAAS,EAAE,kBAAkB,CAAA;CAAE,GAC3C;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAElC,kFAAkF;AAClF,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,WAAW,CAc5E;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,IAAI,mBAAmB,CAAC,iBAAiB,CAAC,CASrF;AAID;6EAC6E;AAC7E,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,MAAM,CASjF;AAID;wEACwE;AACxE,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,YAAY,GAAG,SAAS,KAAK,mBAAmB,CAAC,UAAU,CAAC,CAAC;AACnG,MAAM,MAAM,0BAA0B,GAAG,CAAC,SAAS,EAAE,kBAAkB,KAAK,MAAM,GAAG,SAAS,CAAC;AAE/F;oEACoE;AACpE,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,WAAW,CAAC;IACrB,KAAK,EAAE,SAAS,CAAC;IACjB,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,CAAC,MAAM,EAAE;IACnD,IAAI,EAAE,gBAAgB,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,eAAe,CAAC;IAC/B,8EAA8E;IAC9E,0BAA0B,CAAC,EAAE,0BAA0B,CAAC;CACzD,GAAG,OAAO,CAAC,aAAa,CAAC,CAmCzB"}

package/dist/llm/component-response.js

@@ -0,0 +1,167 @@
+/**
+ * Shared component-generation response harness (M2-03/M2-04).
+ *
+ * `conjure` (M2-03 · DRO-250) and `refine` (M2-04 · DRO-251) are the same
+ * request/validate/retry machine wrapped around two different prompts:
+ *   - build the messages,
+ *   - demand structured output via `response_format: { type: "json_schema", … }`,
+ *   - parse + validate the reply against `COMPONENT_SCHEMA` (M2-02) with Ajv,
+ *   - retry EXACTLY ONCE with the validation error + prior output fed back.
+ *
+ * That machinery lived inline in `conjure.ts`; M2-04's AC6 is literally "same
+ * retry-once pattern as M2-03", so rather than clone a second (drift-prone) copy
+ * of the Ajv compile, the fence-stripper, the retry-feedback wording, and the
+ * two-attempt loop, both verbs import them from here. `refine` reusing this file
+ * is what makes "same pattern" a fact of the code, not a hope about two parallel
+ * implementations staying in step.
+ *
+ * What stays tool-side: each verb owns its own **`buildMessages`** (the prompt is
+ * the whole point of the difference between the two verbs) and its own per-call
+ * structured log + typed error (their AC10/AC8 field sets differ). This module
+ * owns everything between "here are the messages" and "here is a validated
+ * component or a reason it failed".
+ */
+// Named `Ajv` import (not default): ajv@8 is CJS (`module.exports = Ajv` +
+// `module.exports.Ajv = Ajv`) with a `.d.ts` `export declare class Ajv`. Under
+// this repo's `verbatimModuleSyntax` + NodeNext, the *default* import resolves
+// to the module namespace object (TS2351 "not constructable"); the *named* `Ajv`
+// is both a constructable typed class and a cjs-module-lexer-detectable runtime
+// export, so it typechecks under `tsc` and runs under both vite (tests) and node
+// (compiled dist). (Carried verbatim from conjure.ts when this harness was
+// extracted — same reasoning, one copy.)
+import { Ajv } from "ajv";
+import { COMPONENT_SCHEMA } from "./schema.js";
+/** A fresh zeroed usage accumulator. */
+export function emptyUsage() {
+    return { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+}
+/** Add one completion's token counts into a running {@link UsageInfo}. */
+export function addUsage(into, completion) {
+    into.promptTokens += completion.usage?.prompt_tokens ?? 0;
+    into.completionTokens += completion.usage?.completion_tokens ?? 0;
+    into.totalTokens += completion.usage?.total_tokens ?? 0;
+}
+/** Structured warn/telemetry to stderr — never stdout (the stdio transport's
+ * stdout IS the JSON-RPC stream; same convention as client.ts / plan.ts). */
+export function logStderr(payload) {
+    process.stderr.write(JSON.stringify(payload) + "\n");
+}
+// ── Structured-output validation ──────────────────────────────────────────────
+//
+// Compile the validator once against COMPONENT_SCHEMA with the SAME Ajv
+// configuration the schema's own tests and M2-07's `validateComponent` use —
+// `{ strict: true, allErrors: true }`. `strict: true` surfaces schema-keyword
+// mistakes at compile time; `allErrors` lets a retry prompt name *every* problem
+// rather than only the first.
+const ajv = new Ajv({ strict: true, allErrors: true });
+const validateComponent = ajv.compile(COMPONENT_SCHEMA);
+/** Render Ajv errors as a compact, model-readable bullet list for the retry. */
+export function formatAjvErrors(errors) {
+    if (!errors || errors.length === 0)
+        return "(no detail)";
+    return errors
+        .map((e) => `- ${e.instancePath || "(root)"} ${e.message ?? "is invalid"}`)
+        .join("\n");
+}
+/**
+ * Some endpoints wrap JSON in a ```json fence despite `response_format`. Strip a
+ * single leading/trailing fence defensively before parsing so a cosmetically
+ * fenced-but-valid reply doesn't cost a retry.
+ */
+export function stripJsonFence(raw) {
+    const trimmed = raw.trim();
+    const fence = /^```(?:json)?\s*\n([\s\S]*?)\n```$/;
+    const m = fence.exec(trimmed);
+    return m ? m[1].trim() : trimmed;
+}
+/** Parse + schema-validate one model reply. Returns the component or a reason. */
+export function parseAndValidate(raw) {
+    if (!raw || raw.trim() === "") {
+        return { ok: false, reason: "The response was empty — return a JSON object." };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(stripJsonFence(raw));
+    }
+    catch (err) {
+        return { ok: false, reason: `The response was not valid JSON (${String(err)}).` };
+    }
+    if (validateComponent(parsed)) {
+        return { ok: true, component: parsed };
+    }
+    return { ok: false, reason: formatAjvErrors(validateComponent.errors) };
+}
+/**
+ * The `response_format` demanded on every generation call. Wraps
+ * COMPONENT_SCHEMA in the OpenAI structured-output envelope
+ * `{ name, description, schema }` — the real wire shape a compliant endpoint
+ * (and LiteLLM's passthrough) expects.
+ */
+export function buildComponentResponseFormat() {
+    return {
+        type: "json_schema",
+        json_schema: {
+            name: "GenieComponent",
+            description: COMPONENT_SCHEMA.description,
+            schema: COMPONENT_SCHEMA,
+        },
+    };
+}
+/**
+ * Append the shared retry-feedback block to a user instruction. Same wording for
+ * both verbs so the model sees a consistent "you failed validation, fix exactly
+ * this" contract regardless of which verb it is answering. Kept as a function
+ * (not a template inlined per tool) so the wording — which the M2-03 tests pin
+ * (`"failed schema validation"`, `"previous"`) — lives in exactly one place.
+ */
+export function appendRetryFeedback(userText, retry) {
+    return (userText +
+        "\n\n## Your previous attempt failed schema validation\n" +
+        "Fix exactly these problems and return corrected JSON — nothing else:\n" +
+        retry.reason +
+        "\n\n### Your previous (invalid) output\n" +
+        retry.previous);
+}
+/**
+ * Run the shared generation loop: one attempt, and — only if it fails schema
+ * validation — exactly one retry with the error + prior output fed back
+ * (M2-03 AC8 / M2-04 AC6). `buildMessages` is the sole per-verb input, so
+ * `conjure` and `refine` share this identical control flow while each keeps its
+ * own prompt. Usage is summed across both attempts; `attempts` reports whether
+ * the retry fired. The caller decides what to do with a still-invalid
+ * `outcome` (throw its own typed error) and logs its own per-call line.
+ */
+export async function runComponentGeneration(params) {
+    const { chat, model, buildMessages, validateGeneratedComponent } = params;
+    const usage = emptyUsage();
+    const responseFormat = buildComponentResponseFormat();
+    // Attempt 1.
+    const first = await chat({
+        model,
+        messages: buildMessages(undefined),
+        response_format: responseFormat,
+    });
+    addUsage(usage, first);
+    const firstRaw = first.choices[0]?.message?.content ?? null;
+    let outcome = applyGeneratedComponentValidation(parseAndValidate(firstRaw), validateGeneratedComponent);
+    let attempts = 1;
+    // Attempt 2 (retry once) — feed the validation error + prior output back.
+    if (!outcome.ok) {
+        const second = await chat({
+            model,
+            messages: buildMessages({ reason: outcome.reason, previous: firstRaw ?? "(empty)" }),
+            response_format: responseFormat,
+        });
+        addUsage(usage, second);
+        attempts = 2;
+        outcome = applyGeneratedComponentValidation(parseAndValidate(second.choices[0]?.message?.content ?? null), validateGeneratedComponent);
+    }
+    return { outcome, usage, attempts };
+}
+function applyGeneratedComponentValidation(outcome, validateGeneratedComponent) {
+    if (!outcome.ok || validateGeneratedComponent === undefined)
+        return outcome;
+    const reason = validateGeneratedComponent(outcome.component);
+    return reason === undefined ? outcome : { ok: false, reason };
+}
+//# sourceMappingURL=component-response.js.map

package/dist/llm/component-response.js.map

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

package/dist/llm/generated-files.d.ts

@@ -0,0 +1,10 @@
+import type { ValidatedComponent } from "./schema.js";
+export type GeneratedFileWithEncoding = ValidatedComponent["files"][number] & {
+    /** Encoding required when forwarding `content` to write_files as inline data. */
+    encoding: "utf-8" | "base64";
+};
+/** Normalize model-supplied MIME/encoding from the path used by the kit store. */
+export declare function normalizeGeneratedFiles(files: ValidatedComponent["files"]): GeneratedFileWithEncoding[];
+/** Reject binary generated files whose content cannot be safely decoded. */
+export declare function validateGeneratedBinaryContent(component: ValidatedComponent, ignoredPaths?: ReadonlySet<string>): string | undefined;
+//# sourceMappingURL=generated-files.d.ts.map

package/dist/llm/generated-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generated-files.d.ts","sourceRoot":"","sources":["../../src/llm/generated-files.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGtD,MAAM,MAAM,yBAAyB,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,GAAG;IAC5E,iFAAiF;IACjF,QAAQ,EAAE,OAAO,GAAG,QAAQ,CAAC;CAC9B,CAAC;AAEF,kFAAkF;AAClF,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,kBAAkB,CAAC,OAAO,CAAC,GACjC,yBAAyB,EAAE,CAS7B;AAED,4EAA4E;AAC5E,wBAAgB,8BAA8B,CAC5C,SAAS,EAAE,kBAAkB,EAC7B,YAAY,GAAE,WAAW,CAAC,MAAM,CAAa,GAC5C,MAAM,GAAG,SAAS,CAYpB"}

package/dist/llm/generated-files.js

@@ -0,0 +1,26 @@
+import { isTextMime, isValidBase64Content, resolveMime } from "../store/kit-files.js";
+/** Normalize model-supplied MIME/encoding from the path used by the kit store. */
+export function normalizeGeneratedFiles(files) {
+    return files.map((file) => {
+        const mimeType = resolveMime(file.path);
+        return {
+            ...file,
+            mimeType,
+            encoding: isTextMime(mimeType) ? "utf-8" : "base64",
+        };
+    });
+}
+/** Reject binary generated files whose content cannot be safely decoded. */
+export function validateGeneratedBinaryContent(component, ignoredPaths = new Set()) {
+    for (const [index, file] of component.files.entries()) {
+        if (ignoredPaths.has(file.path))
+            continue;
+        const mimeType = resolveMime(file.path);
+        if (!isTextMime(mimeType) && !isValidBase64Content(file.content)) {
+            return (`- /files/${index}/content must be valid base64 for binary file ` +
+                `"${file.path}" (${mimeType}).`);
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=generated-files.js.map

package/dist/llm/generated-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generated-files.js","sourceRoot":"","sources":["../../src/llm/generated-files.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAOtF,kFAAkF;AAClF,MAAM,UAAU,uBAAuB,CACrC,KAAkC;IAElC,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACxB,MAAM,QAAQ,GAAG,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACxC,OAAO;YACL,GAAG,IAAI;YACP,QAAQ;YACR,QAAQ,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ;SACpD,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,8BAA8B,CAC5C,SAA6B,EAC7B,eAAoC,IAAI,GAAG,EAAE;IAE7C,KAAK,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,SAAS,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;QACtD,IAAI,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,SAAS;QAC1C,MAAM,QAAQ,GAAG,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACxC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YACjE,OAAO,CACL,YAAY,KAAK,gDAAgD;gBACjE,IAAI,IAAI,CAAC,IAAI,MAAM,QAAQ,IAAI,CAChC,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/llm/prompts/CHANGELOG.md

@@ -0,0 +1,70 @@
+# Prompt changelog
+
+Version history for genie's LLM system prompts. The _effective_ version of a
+prompt at runtime is the git blob hash of its `.md` file (logged on every
+`conjure`/`refine` call as `promptVersion`), so this file is the human-readable
+narrative companion to that hash — it explains _why_ a prompt changed, not just
+_that_ it did.
+
+Per the M2-03 issue: "80% of the engineering effort here is in iterating on the
+system prompt. Track edits in `prompts/CHANGELOG.md`." Add a dated entry every
+time a `*.system.md` here changes.
+
+## generate-component.system.md
+
+### v1 — 2026-07-03 (M2-03 / DRO-250)
+
+Initial hand-authored system prompt for `conjure`.
+
+Hand-authored rather than adapted from Anthropic's `canvas-design` skill: that
+skill targets Anthropic's hosted Claude Design product and its `@dsCard` /
+`_ds_*` conventions, which are Anthropic-interop shapes genie deliberately keeps
+out of its native surface (CLAUDE.md hard rule 1). genie's native contract —
+`@genie` markers, `components/<group>/<Name>/` layout, the embedded-tier
+`default-src 'none'` CSP, and G-5 byte-identical previews — has no public
+equivalent to lift, so v1 encodes genie's own constraints directly.
+
+Covers:
+
+- The strict JSON-only output contract (mirrors `COMPONENT_SCHEMA`: top-level
+  `componentName` / `group` / `files` / `manifestEntry`, the
+  `components/<group>/<Name>/` path layout, and the required
+  `<Name>.html` preview).
+- The `@genie` first-line marker (`<!-- @genie group="<group>" -->`) — the
+  literal first line M3-01 validates post-hoc.
+- The embedded-tier CSP wall (`default-src 'none'`): no external assets, system
+  fonts only, self-contained inline CSS, byte-identical across
+  `file://`/`localhost`/`genie://` (RFC G-5).
+- Match-the-kit / honesty / accessibility / one-component-per-call house rules.
+- Reference-image and reference-page handling.
+- Retry behavior: on a re-send with an appended validation error, fix exactly
+  what the error names and return corrected JSON (supports AC8's retry-once).
+
+## refine-component.system.md
+
+### v1 — 2026-07-03 (M2-04 / DRO-251)
+
+Initial hand-authored system prompt for `refine` — the iterate-on-an-existing-
+component verb. Shares `conjure`'s output contract (the same `COMPONENT_SCHEMA`
+shape: top-level `componentName` / `group` / `files` / `manifestEntry`, the
+`components/<group>/<Name>/` layout, the `@genie` first-line marker, and the
+embedded-tier `default-src 'none'` CSP), because `refine` returns the same kind
+of artifact `conjure` does — a full, validated component — just derived from
+existing source plus an instruction rather than from a blank-slate prompt.
+
+Where it deliberately diverges from `generate-component.system.md`:
+
+- **Edit, don't rewrite.** The cardinal rule: change only what the `instruction`
+  requires and return everything else byte-for-byte. Keep the same
+  `componentName`/`group` (renaming is not a refinement), preserve unrelated
+  markup/props/whitespace, and don't drop files — so the unified diff the tool
+  computes (AC5) shows only the requested change, nothing incidental.
+- **Whole files, not a patch.** The model still returns the COMPONENT_SCHEMA
+  file set (full updated contents), never a diff — the tool derives the
+  informational diff itself (AC5: "files are the source of truth").
+- **Region scoping.** When a region crop (vision) or its coordinates are
+  attached, the instruction is scoped to that rectangle: edit there, leave the
+  rest untouched (AC4/AC7).
+- Retry behavior mirrors `conjure` (AC6 "same retry-once pattern as M2-03"):
+  on a re-send with an appended validation error, fix exactly what it names —
+  including a changed `componentName`/`group` — and return corrected JSON.