@kubuild/ai 0.3.0

package/dist/server/index.cjs

@@ -0,0 +1,1824 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/server/index.ts
+var server_exports = {};
+__export(server_exports, {
+  AnthropicAdapter: () => AnthropicAdapter,
+  CustomHttpAdapter: () => CustomHttpAdapter,
+  GeminiAdapter: () => GeminiAdapter,
+  KubuildAiEngine: () => KubuildAiEngine,
+  OpenAiAdapter: () => OpenAiAdapter,
+  createAiHandler: () => createAiHandler,
+  processAiRequest: () => processAiRequest
+});
+module.exports = __toCommonJS(server_exports);
+
+// src/server/engine.ts
+var import_schema2 = require("@kubuild/schema");
+
+// src/core/prompt-compiler.ts
+function compileComponentCatalog(registry) {
+  if (!registry) return [];
+  const definitions = registry.list();
+  return definitions.map((def) => {
+    const props = [];
+    if (def.propFields && Array.isArray(def.propFields)) {
+      for (const field of def.propFields) {
+        props.push({
+          name: field.name,
+          type: field.type || "string",
+          defaultValue: field.defaultValue,
+          options: field.options?.map((o) => o.value),
+          description: field.description
+        });
+      }
+    }
+    return {
+      type: def.type,
+      label: def.label || def.type,
+      category: def.category || "custom",
+      description: def.description,
+      acceptsChildren: def.acceptsChildren ?? false,
+      allowedChildren: def.allowedChildren,
+      disallowedParents: def.disallowedParents,
+      defaultProps: def.defaultProps,
+      props: props.length > 0 ? props : void 0
+    };
+  });
+}
+function buildSystemPrompt(options) {
+  const { catalog, mode, prefix, stylePreference } = options;
+  const catalogSummary = catalog.map((c) => {
+    let desc = `- **${c.type}** (${c.category}): ${c.label}`;
+    if (c.description) desc += ` - ${c.description}`;
+    desc += ` | acceptsChildren: ${c.acceptsChildren}`;
+    if (c.allowedChildren && c.allowedChildren.length > 0) {
+      desc += ` | allowedChildren: [${c.allowedChildren.join(", ")}]`;
+    }
+    if (c.props && c.props.length > 0) {
+      const propList = c.props.map((p) => {
+        let pStr = `${p.name} (${p.type})`;
+        if (p.options) pStr += `[${p.options.map(String).join("|")}]`;
+        return pStr;
+      }).join(", ");
+      desc += ` | props: { ${propList} }`;
+    }
+    return desc;
+  }).join("\n");
+  let modeInstructions = "";
+  if (mode === "full-page") {
+    modeInstructions = `
+You must generate a complete, valid KUBUILD PageDocument JSON with this exact structure:
+{
+  "schema": "stora.page",
+  "version": "1.0.0",
+  "metadata": {
+    "title": "<Page Title>",
+    "description": "<Page Description>",
+    "tags": ["<tag1>", "<tag2>"],
+    "category": "<category>"
+  },
+  "document": {
+    "id": "root-page",
+    "type": "page",
+    "styles": {
+      "base": {
+        "backgroundColor": "#ffffff",
+        "fontFamily": "Inter, system-ui, sans-serif",
+        "color": "#111827",
+        "minHeight": "100vh"
+      }
+    },
+    "children": [
+      // Sections here...
+    ]
+  }
+}
+`;
+  } else if (mode === "section") {
+    modeInstructions = `
+You must generate a single valid KUBUILD section Node JSON with this structure:
+{
+  "id": "section_<unique_suffix>",
+  "type": "section",
+  "styles": {
+    "base": {
+      "paddingTop": "64px",
+      "paddingBottom": "64px",
+      "paddingLeft": "24px",
+      "paddingRight": "24px"
+    }
+  },
+  "children": [
+    // Container and child nodes...
+  ]
+}
+`;
+  } else if (mode === "refactor") {
+    modeInstructions = `
+You must refactor the provided KUBUILD Node based on the user's instructions.
+Return ONLY the updated Node JSON while maintaining structural integrity.
+`;
+  }
+  const styleGuide = stylePreference ? `
+User Style Preference: "${stylePreference}". Follow this visual aesthetic closely.` : "\nStyle with modern, clean, high-conversion design patterns (accessible contrast, harmonious spacing, beautiful typography, subtle shadows/borders).";
+  return `${prefix ? prefix + "\n\n" : ""}You are an expert web designer and KUBUILD architecture generator.
+KUBUILD is a component-driven visual website builder. Your job is to output pure, valid JSON (and NOTHING ELSE) matching the KUBUILD schema and the registered component definitions.
+
+### RULES & CONSTRAINTS:
+1. Output MUST be valid JSON only. No markdown fences, no explanatory text, no HTML tags outside html-embed.
+2. Only use component types listed in the Component Catalog below. Do NOT invent new component types.
+3. Obey \`acceptsChildren\` and \`allowedChildren\`:
+   - Layout hierarchy: \`page\` -> \`section\` -> \`container\` or \`columns\` -> content components (\`heading\`, \`paragraph\`, \`button\`, \`image\`, \`form\`, etc.).
+   - Leaf components (e.g. \`button\`, \`input\`, \`heading\`, \`text\`, \`badge\`) must have \`acceptsChildren: false\` and empty or omitted \`children\`.
+4. Every node MUST have a unique string \`id\` (e.g. "hero-section", "hero-title", "cta-btn").
+5. Responsive & Interactive State Styling:
+   - Use the \`styles\` object with breakpoint keys: \`base\` (all viewports/desktop), and optionally \`tablet\` or \`mobile\`.
+   - In \`base\`, \`tablet\`, and \`mobile\`, values MUST be CSS primitives (strings or numbers, e.g. "backgroundColor": "#3b82f6"). NEVER put nested objects or ":hover" inside "base"!
+   - For hover, active, or interactive pseudo-classes, use \`styles.states\` with pseudo-class keys (e.g. \`":hover"\`), like:
+     "styles": {
+       "base": { "backgroundColor": "#3b82f6", "color": "#ffffff" },
+       "states": {
+         ":hover": { "backgroundColor": "#2563eb" }
+       }
+     }
+6. NEVER include dangerous scripts, \`javascript:\` URIs, or malicious payload attributes.
+${styleGuide}
+
+### OUTPUT SPECIFICATION:
+${modeInstructions}
+
+### REGISTERED COMPONENT CATALOG:
+${catalogSummary || "(Standard core components: page, section, container, columns, heading, paragraph, text, button, input, textarea, select, image, video, icon, badge, code-block)"}
+`;
+}
+function buildJsonSchemaForMode(mode) {
+  const nodeSchema = {
+    type: "object",
+    required: ["id", "type"],
+    properties: {
+      id: { type: "string" },
+      type: { type: "string" },
+      props: { type: "object" },
+      styles: {
+        type: "object",
+        properties: {
+          base: { type: "object" },
+          tablet: { type: "object" },
+          mobile: { type: "object" },
+          states: { type: "object" }
+        }
+      },
+      children: {
+        type: "array",
+        items: { $ref: "#" }
+      }
+    }
+  };
+  if (mode === "full-page") {
+    return {
+      type: "object",
+      required: ["schema", "version", "document"],
+      properties: {
+        schema: { type: "string", const: "stora.page" },
+        version: { type: "string", const: "1.0.0" },
+        metadata: {
+          type: "object",
+          properties: {
+            title: { type: "string" },
+            description: { type: "string" },
+            tags: { type: "array", items: { type: "string" } },
+            category: { type: "string" }
+          }
+        },
+        document: nodeSchema
+      }
+    };
+  }
+  return nodeSchema;
+}
+
+// src/core/normalizer.ts
+var import_schema = require("@kubuild/schema");
+var import_core = require("@kubuild/core");
+function extractJsonFromResponse(raw) {
+  let cleaned = raw.trim();
+  if (cleaned.startsWith("```")) {
+    const firstNewline = cleaned.indexOf("\n");
+    if (firstNewline !== -1) {
+      cleaned = cleaned.slice(firstNewline + 1);
+    }
+    if (cleaned.endsWith("```")) {
+      cleaned = cleaned.slice(0, cleaned.length - 3).trim();
+    }
+  }
+  const firstBrace = cleaned.indexOf("{");
+  const lastBrace = cleaned.lastIndexOf("}");
+  if (firstBrace !== -1 && lastBrace !== -1 && lastBrace > firstBrace) {
+    cleaned = cleaned.slice(firstBrace, lastBrace + 1);
+  }
+  try {
+    return JSON.parse(cleaned);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`Failed to parse AI response as JSON: ${msg}. Response was: ${raw.slice(0, 200)}...`);
+  }
+}
+function normalizeStyles(rawStyles) {
+  if (!rawStyles || typeof rawStyles !== "object" || Array.isArray(rawStyles)) {
+    return void 0;
+  }
+  const raw = rawStyles;
+  const result = {};
+  const states = {};
+  if (raw.states && typeof raw.states === "object" && !Array.isArray(raw.states)) {
+    for (const [stateKey, stateVal] of Object.entries(raw.states)) {
+      if (stateVal && typeof stateVal === "object" && !Array.isArray(stateVal)) {
+        states[stateKey] = { ...stateVal };
+      }
+    }
+  }
+  const knownBreakpoints = ["base", "desktop", "tablet", "mobile"];
+  const hasBreakpoint = Object.keys(raw).some((k) => knownBreakpoints.includes(k));
+  if (!hasBreakpoint) {
+    const baseStyles = {};
+    for (const [key, value] of Object.entries(raw)) {
+      if (key === "states") continue;
+      if (key.startsWith(":") || key === "hover" || key === "focus" || key === "active") {
+        const stateKey = key.startsWith(":") ? key : `:${key}`;
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+          states[stateKey] = { ...states[stateKey] || {}, ...value };
+        }
+      } else if (typeof value !== "object" || value === null) {
+        baseStyles[key] = value;
+      }
+    }
+    if (Object.keys(baseStyles).length > 0) {
+      result.base = baseStyles;
+    }
+  } else {
+    for (const bp of knownBreakpoints) {
+      const bpVal = raw[bp];
+      if (bpVal && typeof bpVal === "object" && !Array.isArray(bpVal)) {
+        const cleanBp = {};
+        for (const [key, value] of Object.entries(bpVal)) {
+          if (key.startsWith(":") || key === "hover" || key === "focus" || key === "active") {
+            const stateKey = key.startsWith(":") ? key : `:${key}`;
+            if (value && typeof value === "object" && !Array.isArray(value)) {
+              states[stateKey] = { ...states[stateKey] || {}, ...value };
+            }
+          } else if (typeof value !== "object" || value === null) {
+            cleanBp[key] = value;
+          }
+        }
+        if (Object.keys(cleanBp).length > 0) {
+          result[bp] = cleanBp;
+        }
+      }
+    }
+    for (const [key, value] of Object.entries(raw)) {
+      if (knownBreakpoints.includes(key) || key === "states") continue;
+      if (key.startsWith(":") || key === "hover" || key === "focus" || key === "active") {
+        const stateKey = key.startsWith(":") ? key : `:${key}`;
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+          states[stateKey] = { ...states[stateKey] || {}, ...value };
+        }
+      }
+    }
+  }
+  const cleanStates = {};
+  for (const [stateKey, stateDef] of Object.entries(states)) {
+    const cleanDef = {};
+    for (const [propKey, propVal] of Object.entries(stateDef)) {
+      if (typeof propVal !== "object" || propVal === null) {
+        cleanDef[propKey] = propVal;
+      }
+    }
+    if (Object.keys(cleanDef).length > 0) {
+      cleanStates[stateKey] = cleanDef;
+    }
+  }
+  if (Object.keys(cleanStates).length > 0) {
+    result.states = cleanStates;
+  }
+  return Object.keys(result).length > 0 ? result : void 0;
+}
+function normalizeNodeTree(node, usedIds = /* @__PURE__ */ new Set(), depth = 0) {
+  if (!node || typeof node !== "object") {
+    throw new Error(`Invalid node at depth ${depth}: must be an object`);
+  }
+  const raw = node;
+  const type = typeof raw.type === "string" && raw.type.trim() ? raw.type.trim() : "container";
+  let id = typeof raw.id === "string" && raw.id.trim() ? raw.id.trim() : "";
+  if (!id || usedIds.has(id)) {
+    let counter = 1;
+    let candidate = `${type}-${counter}`;
+    while (usedIds.has(candidate)) {
+      counter++;
+      candidate = `${type}-${counter}`;
+    }
+    id = candidate;
+  }
+  usedIds.add(id);
+  const props = raw.props && typeof raw.props === "object" && !Array.isArray(raw.props) ? { ...raw.props } : {};
+  if (type === "heading" && typeof props.level === "string") {
+    const parsedLevel = parseInt(props.level, 10);
+    if (!isNaN(parsedLevel) && parsedLevel >= 1 && parsedLevel <= 6) {
+      props.level = parsedLevel;
+    }
+  }
+  const styles = normalizeStyles(raw.styles);
+  let children = void 0;
+  if (Array.isArray(raw.children)) {
+    children = raw.children.filter((c) => c && typeof c === "object").map((c) => normalizeNodeTree(c, usedIds, depth + 1));
+  }
+  return {
+    id,
+    type,
+    props: Object.keys(props).length > 0 ? props : void 0,
+    styles,
+    children
+  };
+}
+function normalizeAndValidatePageDocument(rawJson, securityLimits) {
+  if (!rawJson || typeof rawJson !== "object") {
+    throw new Error("AI output must be a JSON object");
+  }
+  const obj = rawJson;
+  let docObject;
+  if (obj.type === "page" && !obj.document) {
+    docObject = {
+      schema: import_schema.SCHEMA_NAME,
+      version: import_schema.CURRENT_SCHEMA_VERSION,
+      metadata: {
+        title: typeof obj.props === "object" && obj.props !== null && obj.props.title || "AI Generated Page",
+        description: "Generated by KUBUILD AI"
+      },
+      document: obj
+    };
+  } else {
+    docObject = {
+      schema: import_schema.SCHEMA_NAME,
+      version: typeof obj.version === "string" ? obj.version : import_schema.CURRENT_SCHEMA_VERSION,
+      metadata: typeof obj.metadata === "object" && obj.metadata !== null ? obj.metadata : { title: "AI Generated Page", description: "Generated by KUBUILD AI" },
+      document: obj.document || obj
+    };
+  }
+  const usedIds = /* @__PURE__ */ new Set();
+  const normalizedRoot = normalizeNodeTree(docObject.document, usedIds);
+  if (normalizedRoot.type !== "page") {
+    normalizedRoot.type = "page";
+  }
+  const parsedMetadata = import_schema.DocumentMetadataSchema.parse({
+    title: "AI Generated Page",
+    description: "Generated by KUBUILD AI",
+    author: "KUBUILD AI",
+    tags: ["ai-generated"],
+    category: "general",
+    version: "1.0.0",
+    ...typeof docObject.metadata === "object" && docObject.metadata !== null ? docObject.metadata : {}
+  });
+  const finalDocument = {
+    schema: import_schema.SCHEMA_NAME,
+    version: import_schema.CURRENT_SCHEMA_VERSION,
+    metadata: parsedMetadata,
+    document: normalizedRoot
+  };
+  const parsed = import_schema.PageDocumentSchema.safeParse(finalDocument);
+  if (!parsed.success) {
+    const issues = parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
+    throw new Error(`Document schema validation failed: ${issues}`);
+  }
+  const validationResult = (0, import_core.validateDocument)(finalDocument, { securityLimits });
+  if (!validationResult.valid) {
+    const errorMsgs = validationResult.errors.map((e) => `${e.code}: ${e.message} (${e.path})`).join("; ");
+    throw new Error(`Document validation failed: ${errorMsgs}`);
+  }
+  return parsed.data;
+}
+function normalizeAndValidateSectionNode(rawJson, securityLimits) {
+  if (!rawJson || typeof rawJson !== "object") {
+    throw new Error("AI output must be a JSON object");
+  }
+  const usedIds = /* @__PURE__ */ new Set();
+  const normalized = normalizeNodeTree(rawJson, usedIds);
+  if (normalized.type !== "section") {
+    normalized.type = "section";
+  }
+  const parsed = import_schema.NodeSchema.safeParse(normalized);
+  if (!parsed.success) {
+    const issues = parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
+    throw new Error(`Section node schema validation failed: ${issues}`);
+  }
+  const secCheck = (0, import_core.validateDocumentSecurity)({ document: normalized }, securityLimits);
+  if (!secCheck.safe) {
+    const issues = secCheck.errors.map((e) => `${e.code}: ${e.message}`).join("; ");
+    throw new Error(`Section security check failed: ${issues}`);
+  }
+  return parsed.data;
+}
+function normalizeAndValidateRefactoredNode(rawJson, originalNode, securityLimits) {
+  if (!rawJson || typeof rawJson !== "object") {
+    throw new Error("AI output must be a JSON object");
+  }
+  const usedIds = /* @__PURE__ */ new Set();
+  const normalized = normalizeNodeTree(rawJson, usedIds);
+  normalized.id = originalNode.id;
+  normalized.type = originalNode.type;
+  const parsed = import_schema.NodeSchema.safeParse(normalized);
+  if (!parsed.success) {
+    const issues = parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
+    throw new Error(`Refactored node schema validation failed: ${issues}`);
+  }
+  const secCheck = (0, import_core.validateDocumentSecurity)({ document: normalized }, securityLimits);
+  if (!secCheck.safe) {
+    const issues = secCheck.errors.map((e) => `${e.code}: ${e.message}`).join("; ");
+    throw new Error(`Refactored node security check failed: ${issues}`);
+  }
+  return parsed.data;
+}
+
+// src/server/engine.ts
+var KubuildAiEngine = class {
+  options;
+  catalog;
+  constructor(options) {
+    if (!options.adapter) {
+      throw new Error("KubuildAiEngine requires an adapter instance");
+    }
+    this.options = options;
+    this.catalog = compileComponentCatalog(options.registry);
+  }
+  get adapterName() {
+    return this.options.adapter.name;
+  }
+  refreshCatalog() {
+    this.catalog = compileComponentCatalog(this.options.registry);
+  }
+  log(level, message, meta) {
+    if (this.options.logger) {
+      this.options.logger(level, message, meta);
+    } else if (this.options.debug) {
+      const ts = (/* @__PURE__ */ new Date()).toISOString();
+      console.log(`[KUBUILD-AI ${level.toUpperCase()}] [${ts}] ${message}`, meta !== void 0 ? meta : "");
+    }
+  }
+  async generatePage(request, context) {
+    let rawText = "";
+    try {
+      this.log("info", `Generating full page for prompt: "${request.prompt}"`);
+      const systemPrompt = buildSystemPrompt({
+        catalog: this.catalog,
+        mode: "full-page",
+        prefix: this.options.systemPromptPrefix,
+        stylePreference: request.stylePreference
+      });
+      let userPrompt = `User Request: ${request.prompt}`;
+      if (request.tone) userPrompt += `
+Tone: ${request.tone}`;
+      if (request.locale) userPrompt += `
+Language/Locale: ${request.locale}`;
+      const jsonSchema = buildJsonSchemaForMode("full-page");
+      const result = await this.options.adapter.generate({
+        systemPrompt,
+        userPrompt,
+        jsonSchema,
+        signal: context?.signal
+      });
+      this.log("debug", "Raw model response (generatePage)", result.text);
+      rawText = result.text;
+      const rawJson = extractJsonFromResponse(rawText);
+      const document = normalizeAndValidatePageDocument(
+        rawJson,
+        this.options.securityLimits
+      );
+      if (request.metadata) {
+        document.metadata = import_schema2.DocumentMetadataSchema.parse({
+          ...document.metadata,
+          ...request.metadata
+        });
+      }
+      this.log(
+        "info",
+        `Full page successfully generated: "${document.metadata?.title || "Untitled"}" (${document.document.children?.length || 0} sections)`
+      );
+      return {
+        success: true,
+        data: document,
+        usage: result.usage,
+        rawModelResponse: rawText
+      };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      this.log("error", `Generation failed: ${message}`);
+      return {
+        success: false,
+        error: {
+          code: "GENERATION_ERROR",
+          message
+        },
+        rawModelResponse: rawText || void 0
+      };
+    }
+  }
+  async generateSection(request, context) {
+    let rawText = "";
+    try {
+      const systemPrompt = buildSystemPrompt({
+        catalog: this.catalog,
+        mode: "section",
+        prefix: this.options.systemPromptPrefix,
+        stylePreference: request.stylePreference
+      });
+      let userPrompt = `Generate a single section node for: ${request.prompt}`;
+      if (request.targetSectionType) {
+        userPrompt += `
+Target Section Purpose: ${request.targetSectionType}`;
+      }
+      if (request.parentContext) {
+        userPrompt += `
+Surrounding Page Context: ${request.parentContext}`;
+      }
+      const jsonSchema = buildJsonSchemaForMode("section");
+      const result = await this.options.adapter.generate({
+        systemPrompt,
+        userPrompt,
+        jsonSchema,
+        signal: context?.signal
+      });
+      this.log("debug", "Raw model response (generateSection)", result.text);
+      rawText = result.text;
+      const rawJson = extractJsonFromResponse(rawText);
+      const sectionNode = normalizeAndValidateSectionNode(
+        rawJson,
+        this.options.securityLimits
+      );
+      return {
+        success: true,
+        data: sectionNode,
+        usage: result.usage,
+        rawModelResponse: rawText
+      };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return {
+        success: false,
+        error: {
+          code: "SECTION_GENERATION_ERROR",
+          message
+        },
+        rawModelResponse: rawText || void 0
+      };
+    }
+  }
+  async refactorNode(request, context) {
+    let rawText = "";
+    try {
+      const systemPrompt = buildSystemPrompt({
+        catalog: this.catalog,
+        mode: "refactor",
+        prefix: this.options.systemPromptPrefix,
+        stylePreference: request.stylePreference
+      });
+      const userPrompt = `Instruction: ${request.instruction}
+
+Current Node:
+${JSON.stringify(request.node, null, 2)}`;
+      const jsonSchema = buildJsonSchemaForMode("refactor");
+      const result = await this.options.adapter.generate({
+        systemPrompt,
+        userPrompt,
+        jsonSchema,
+        signal: context?.signal
+      });
+      rawText = result.text;
+      const rawJson = extractJsonFromResponse(rawText);
+      const updatedNode = normalizeAndValidateRefactoredNode(
+        rawJson,
+        request.node,
+        this.options.securityLimits
+      );
+      return {
+        success: true,
+        data: updatedNode,
+        usage: result.usage,
+        rawModelResponse: rawText
+      };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return {
+        success: false,
+        error: {
+          code: "REFACTOR_ERROR",
+          message
+        },
+        rawModelResponse: rawText || void 0
+      };
+    }
+  }
+  /**
+   * Progressive Section Streaming Generator.
+   * Emits structured SSE events: status -> metadata -> section (one by one) -> complete.
+   */
+  async *streamPage(request, context) {
+    try {
+      this.log("info", `[SSE] Starting streamPage for prompt: "${request.prompt}"`);
+      yield {
+        type: "status",
+        message: "Analyzing requirements and planning page sections..."
+      };
+      const planSystemPrompt = `
+You are a web architect for the KUBUILD page builder.
+Given the user's prompt, plan the website structure. Output pure JSON (no markdown fences, no explanatory text):
+{
+  "title": "<Page Title>",
+  "description": "<Page Description>",
+  "pageStyles": {
+    "base": {
+      "backgroundColor": "#ffffff",
+      "fontFamily": "Inter, system-ui, sans-serif",
+      "color": "#111827",
+      "minHeight": "100vh"
+    }
+  },
+  "sections": [
+    {
+      "type": "<hero|features|pricing|testimonials|cta|contact|footer>",
+      "title": "<Brief title>",
+      "prompt": "<Detailed prompt for generating this specific section with components, layout, and content>"
+    }
+  ]
+}
+Plan 3 cohesive, essential sections (e.g., hero, features, and cta) that fulfill the request.
+`;
+      let planUserPrompt = `User Request: ${request.prompt}`;
+      if (request.stylePreference) {
+        planUserPrompt += `
+Style Preference: ${request.stylePreference}`;
+      }
+      if (request.tone) planUserPrompt += `
+Tone: ${request.tone}`;
+      if (request.locale) planUserPrompt += `
+Locale: ${request.locale}`;
+      this.log("info", "[SSE] Generating website layout plan...");
+      const planResult = await this.options.adapter.generate({
+        systemPrompt: planSystemPrompt,
+        userPrompt: planUserPrompt,
+        signal: context?.signal
+      });
+      this.log("debug", "[SSE] Raw plan response from model", planResult.text);
+      let plan;
+      try {
+        plan = extractJsonFromResponse(planResult.text);
+        this.log("debug", "[SSE] Parsed plan successfully", plan);
+      } catch (parseErr) {
+        this.log("warn", "[SSE] Failed to parse plan JSON, using fallback plan", parseErr);
+        plan = {
+          title: "AI Generated Page",
+          description: "Generated by KUBUILD AI",
+          sections: [
+            { type: "hero", title: "Hero Banner", prompt: `Hero section for: ${request.prompt}` },
+            { type: "features", title: "Key Features", prompt: `Features grid for: ${request.prompt}` },
+            { type: "cta", title: "Call To Action", prompt: `Call to action section for: ${request.prompt}` }
+          ]
+        };
+      }
+      const sectionsToGenerate = Array.isArray(plan.sections) && plan.sections.length > 0 ? plan.sections : [
+        { type: "hero", title: "Hero Section", prompt: `Hero banner for: ${request.prompt}` },
+        { type: "features", title: "Features", prompt: `Features grid for: ${request.prompt}` },
+        { type: "cta", title: "Call To Action", prompt: `CTA section for: ${request.prompt}` }
+      ];
+      const metadata = import_schema2.DocumentMetadataSchema.parse({
+        title: plan.title || "AI Generated Page",
+        description: plan.description || "Generated by KUBUILD AI",
+        author: "KUBUILD AI",
+        tags: ["ai-generated", "progressive-stream"],
+        category: "landing",
+        version: "1.0.0",
+        ...request.metadata || {}
+      });
+      const rootPageNode = {
+        id: "root-page",
+        type: "page",
+        styles: plan.pageStyles || {
+          base: {
+            backgroundColor: "#ffffff",
+            fontFamily: "Inter, system-ui, sans-serif",
+            color: "#111827",
+            minHeight: "100vh"
+          }
+        },
+        children: []
+      };
+      this.log("info", `[SSE] Emitting metadata: "${metadata.title}"`);
+      yield {
+        type: "metadata",
+        metadata,
+        rootPageNode
+      };
+      this.log(
+        "info",
+        `[SSE] Plan ready with ${sectionsToGenerate.length} sections: ${sectionsToGenerate.map((s) => s.title).join(", ")}`
+      );
+      yield {
+        type: "status",
+        message: `Plan ready with ${sectionsToGenerate.length} sections: ${sectionsToGenerate.map((s) => s.title).join(", ")}`
+      };
+      const completedSections = [];
+      const total = sectionsToGenerate.length;
+      for (let i = 0; i < total; i++) {
+        if (context?.signal?.aborted) {
+          this.log("warn", "[SSE] Streaming aborted by client signal");
+          throw new Error("Streaming aborted by client");
+        }
+        const plannedSec = sectionsToGenerate[i];
+        this.log(
+          "info",
+          `[SSE] Generating section ${i + 1}/${total} [${plannedSec.type}]: "${plannedSec.title}"`
+        );
+        yield {
+          type: "status",
+          message: `Generating section ${i + 1}/${total} (${plannedSec.title})...`
+        };
+        const secRes = await this.generateSection(
+          {
+            prompt: plannedSec.prompt,
+            stylePreference: request.stylePreference,
+            targetSectionType: plannedSec.type,
+            parentContext: `Website: ${plan.title}. Previous sections: ${sectionsToGenerate.slice(0, i).map((s) => s.title).join(", ")}`
+          },
+          { signal: context?.signal }
+        );
+        if (secRes.success && secRes.data) {
+          this.log(
+            "info",
+            `[SSE] Section ${i + 1}/${total} generated successfully: [${secRes.data.id || secRes.data.type}]`
+          );
+          completedSections.push(secRes.data);
+          yield {
+            type: "section",
+            index: i,
+            total,
+            section: secRes.data
+          };
+        } else {
+          this.log("error", `[SSE] Section ${i + 1}/${total} failed`, secRes.error?.message);
+        }
+      }
+      if (completedSections.length === 0) {
+        this.log("error", "[SSE] All sections failed to generate.");
+        yield {
+          type: "error",
+          error: {
+            code: "STREAM_GENERATION_FAILED",
+            message: "All sections failed to generate. Please check server logs or retry."
+          }
+        };
+        return;
+      }
+      const finalDocument = {
+        schema: "stora.page",
+        version: "1.0.0",
+        metadata,
+        document: {
+          ...rootPageNode,
+          children: completedSections
+        }
+      };
+      this.log(
+        "info",
+        `[SSE] All ${completedSections.length} sections generated. Emitting complete event.`
+      );
+      yield {
+        type: "complete",
+        document: finalDocument
+      };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      this.log("error", `[SSE] Streaming failed: ${message}`);
+      yield {
+        type: "error",
+        error: {
+          code: "STREAM_ERROR",
+          message
+        }
+      };
+    }
+  }
+  /**
+   * Builds the system/user prompt pair shared by `chat()` and `chatStream()` — the exact
+   * same document/selection grounding is used regardless of whether the response is
+   * streamed token-by-token or returned as a single request/response (STORA-515).
+   */
+  buildChatPrompt(request) {
+    let systemPrompt = `You are the KUBUILD AI Assistant \u2014 an expert web designer, developer, and page architecture consultant.
+Your role is to assist users with creating, designing, refining, and understanding web pages built with the KUBUILD builder.
+Answer questions directly, concisely, and helpfully using friendly professional tone and markdown formatting.
+
+### Available KUBUILD Components:
+${this.catalog.map((c) => `- **${c.type}** (${c.category}): ${c.label}${c.description ? ` \u2014 ${c.description}` : ""}`).join("\n")}
+`;
+    if (this.options.systemPromptPrefix) {
+      systemPrompt = `${this.options.systemPromptPrefix}
+
+${systemPrompt}`;
+    }
+    if (request.systemPrompt) {
+      systemPrompt += `
+Additional Context:
+${request.systemPrompt}`;
+    }
+    if (request.currentDocument) {
+      const doc = request.currentDocument;
+      const sections = doc.document?.children || [];
+      const sectionSummary = sections.map((s, idx) => `Section ${idx + 1}: id="${s.id}", type="${s.type}", title="${s.props?.title || "untitled"}", childrenCount=${s.children?.length || 0}`).join("\n");
+      systemPrompt += `
+### Current Page in Builder Canvas:
+- Title: ${doc.metadata?.title || "Untitled Page"}
+- Description: ${doc.metadata?.description || "N/A"}
+- Total Sections: ${sections.length}
+- Sections Summary:
+${sectionSummary || "(Canvas is currently empty)"}
+`;
+    }
+    if (request.selectedNodeId) {
+      systemPrompt += `
+Currently Selected Component Node ID: "${request.selectedNodeId}"`;
+    }
+    const lastUserMsg = [...request.messages].reverse().find((m) => m.role === "user");
+    const userPrompt = lastUserMsg?.content || "Hello";
+    return { systemPrompt, userPrompt };
+  }
+  /**
+   * Conversational Assistant / Q&A.
+   * Can discuss web design, explain KUBUILD components, review current page,
+   * suggest improvements, or recommend copywriting.
+   *
+   * Single request/response — unchanged since before STORA-515. See `chatStream()` for
+   * the token-level streaming variant.
+   */
+  async chat(request, context) {
+    let rawText = "";
+    try {
+      if (!request.messages || !Array.isArray(request.messages) || request.messages.length === 0) {
+        return {
+          success: false,
+          error: {
+            code: "INVALID_CHAT_REQUEST",
+            message: '"messages" array is required and must not be empty'
+          }
+        };
+      }
+      this.log("info", `Processing chat turn with ${request.messages.length} messages`);
+      const { systemPrompt, userPrompt } = this.buildChatPrompt(request);
+      const result = await this.options.adapter.generate({
+        systemPrompt,
+        userPrompt,
+        messages: request.messages,
+        signal: context?.signal
+      });
+      rawText = result.text.trim();
+      const assistantMessage = {
+        role: "assistant",
+        content: rawText,
+        timestamp: Date.now()
+      };
+      return {
+        success: true,
+        data: {
+          message: assistantMessage
+        },
+        usage: result.usage,
+        rawModelResponse: rawText
+      };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      this.log("error", `Chat failed: ${message}`);
+      return {
+        success: false,
+        error: {
+          code: "CHAT_ERROR",
+          message
+        },
+        rawModelResponse: rawText || void 0
+      };
+    }
+  }
+  /**
+   * Token-level streaming variant of `chat()` (STORA-515). Emits `chat-chunk` events as
+   * partial text arrives, then a terminal `chat-complete` event with the fully assembled
+   * assistant message — the same `AsyncIterable<AiStreamEvent>` mechanism `streamPage`
+   * already uses, so it can be piped over SSE by `createAiHandler`/consumed by
+   * `KubuildAiClient` with no separate transport.
+   *
+   * When the configured adapter does not implement `generateStream` (e.g. the generic
+   * custom/HTTP adapter), this falls back to a single non-streaming `generate()` call and
+   * emits the entire response as one `chat-chunk`, so callers never see an error just
+   * because the underlying provider can't stream — only a less granular update cadence.
+   */
+  async *chatStream(request, context) {
+    try {
+      if (!request.messages || !Array.isArray(request.messages) || request.messages.length === 0) {
+        yield {
+          type: "error",
+          error: {
+            code: "INVALID_CHAT_REQUEST",
+            message: '"messages" array is required and must not be empty'
+          }
+        };
+        return;
+      }
+      this.log(
+        "info",
+        `[SSE] Starting chatStream with ${request.messages.length} messages (adapter: ${this.options.adapter.name})`
+      );
+      const { systemPrompt, userPrompt } = this.buildChatPrompt(request);
+      let accumulated = "";
+      let usage;
+      if (typeof this.options.adapter.generateStream === "function") {
+        const generator = this.options.adapter.generateStream({
+          systemPrompt,
+          userPrompt,
+          messages: request.messages,
+          signal: context?.signal
+        });
+        while (true) {
+          const { value, done } = await generator.next();
+          if (done) {
+            usage = value?.usage;
+            break;
+          }
+          accumulated += value;
+          yield { type: "chat-chunk", delta: value, content: accumulated };
+        }
+      } else {
+        this.log(
+          "debug",
+          `Adapter "${this.options.adapter.name}" has no generateStream; falling back to non-streaming chat`
+        );
+        const result = await this.options.adapter.generate({
+          systemPrompt,
+          userPrompt,
+          messages: request.messages,
+          signal: context?.signal
+        });
+        accumulated = result.text;
+        usage = result.usage;
+        yield { type: "chat-chunk", delta: accumulated, content: accumulated };
+      }
+      const assistantMessage = {
+        role: "assistant",
+        content: accumulated.trim(),
+        timestamp: Date.now()
+      };
+      this.log("info", "[SSE] Chat stream completed", usage);
+      yield { type: "chat-complete", message: assistantMessage };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      this.log("error", `[SSE] Chat streaming failed: ${message}`);
+      yield {
+        type: "error",
+        error: {
+          code: "CHAT_STREAM_ERROR",
+          message
+        }
+      };
+    }
+  }
+};
+
+// src/server/handler.ts
+async function processAiRequest(engine, body, signal) {
+  if (!body || typeof body !== "object") {
+    return {
+      status: 400,
+      response: {
+        success: false,
+        error: {
+          code: "BAD_REQUEST",
+          message: "Request body must be a valid JSON object"
+        }
+      }
+    };
+  }
+  const payload = body;
+  const mode = payload.mode || "full-page";
+  if (mode === "full-page") {
+    if (!payload.prompt || typeof payload.prompt !== "string") {
+      return {
+        status: 400,
+        response: {
+          success: false,
+          error: {
+            code: "INVALID_PROMPT",
+            message: '"prompt" is required for full-page generation'
+          }
+        }
+      };
+    }
+    const result = await engine.generatePage(
+      {
+        prompt: payload.prompt,
+        stylePreference: payload.stylePreference,
+        tone: payload.tone,
+        locale: payload.locale,
+        metadata: payload.metadata
+      },
+      { signal }
+    );
+    return {
+      status: result.success ? 200 : 500,
+      response: result
+    };
+  }
+  if (mode === "section") {
+    if (!payload.prompt || typeof payload.prompt !== "string") {
+      return {
+        status: 400,
+        response: {
+          success: false,
+          error: {
+            code: "INVALID_PROMPT",
+            message: '"prompt" is required for section generation'
+          }
+        }
+      };
+    }
+    const result = await engine.generateSection(
+      {
+        prompt: payload.prompt,
+        stylePreference: payload.stylePreference,
+        targetSectionType: payload.targetSectionType,
+        parentContext: payload.parentContext
+      },
+      { signal }
+    );
+    return {
+      status: result.success ? 200 : 500,
+      response: result
+    };
+  }
+  if (mode === "refactor") {
+    if (!payload.node || !payload.instruction) {
+      return {
+        status: 400,
+        response: {
+          success: false,
+          error: {
+            code: "INVALID_REFACTOR_PARAMS",
+            message: '"node" and "instruction" are required for refactoring'
+          }
+        }
+      };
+    }
+    const result = await engine.refactorNode(
+      {
+        node: payload.node,
+        instruction: payload.instruction,
+        stylePreference: payload.stylePreference
+      },
+      { signal }
+    );
+    return {
+      status: result.success ? 200 : 500,
+      response: result
+    };
+  }
+  if (mode === "chat") {
+    if (!payload.messages || !Array.isArray(payload.messages) || payload.messages.length === 0) {
+      return {
+        status: 400,
+        response: {
+          success: false,
+          error: {
+            code: "INVALID_CHAT_PARAMS",
+            message: '"messages" array is required and must not be empty for chat mode'
+          }
+        }
+      };
+    }
+    const result = await engine.chat(
+      {
+        messages: payload.messages,
+        currentDocument: payload.currentDocument,
+        selectedNodeId: payload.selectedNodeId
+      },
+      { signal }
+    );
+    return {
+      status: result.success ? 200 : 500,
+      response: result
+    };
+  }
+  return {
+    status: 400,
+    response: {
+      success: false,
+      error: {
+        code: "UNKNOWN_MODE",
+        message: `Unsupported mode: ${String(mode)}. Supported modes: 'full-page', 'section', 'refactor', 'chat'`
+      }
+    }
+  };
+}
+function createAiHandler(engine, options) {
+  return async (request) => {
+    try {
+      if (options?.beforeRequest) {
+        const hookResult = await options.beforeRequest(request);
+        if (hookResult instanceof Response) {
+          return hookResult;
+        }
+      }
+      if (request.method !== "POST") {
+        return new Response(
+          JSON.stringify({
+            success: false,
+            error: {
+              code: "METHOD_NOT_ALLOWED",
+              message: "Only POST requests are accepted"
+            }
+          }),
+          {
+            status: 405,
+            headers: {
+              "Content-Type": "application/json",
+              Allow: "POST"
+            }
+          }
+        );
+      }
+      const body = await request.json().catch(() => null);
+      if (body && typeof body === "object" && body.stream === true) {
+        const mode = body.mode || "full-page";
+        if (mode === "chat") {
+          if (!body.messages || !Array.isArray(body.messages) || body.messages.length === 0) {
+            return new Response(
+              JSON.stringify({
+                success: false,
+                error: {
+                  code: "INVALID_CHAT_PARAMS",
+                  message: '"messages" array is required and must not be empty for chat mode'
+                }
+              }),
+              {
+                status: 400,
+                headers: { "Content-Type": "application/json" }
+              }
+            );
+          }
+          const encoder2 = new TextEncoder();
+          const readable2 = new ReadableStream({
+            async start(controller) {
+              try {
+                for await (const event of engine.chatStream(
+                  {
+                    messages: body.messages,
+                    currentDocument: body.currentDocument,
+                    selectedNodeId: body.selectedNodeId
+                  },
+                  { signal: request.signal }
+                )) {
+                  controller.enqueue(
+                    encoder2.encode(`event: ${event.type}
+data: ${JSON.stringify(event)}
+
+`)
+                  );
+                }
+              } catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                controller.enqueue(
+                  encoder2.encode(
+                    `event: error
+data: ${JSON.stringify({ type: "error", error: { code: "CHAT_STREAM_ERROR", message } })}
+
+`
+                  )
+                );
+              } finally {
+                controller.close();
+              }
+            }
+          });
+          return new Response(readable2, {
+            status: 200,
+            headers: {
+              "Content-Type": "text/event-stream",
+              "Cache-Control": "no-cache, no-transform",
+              Connection: "keep-alive"
+            }
+          });
+        }
+        if (!body.prompt || typeof body.prompt !== "string") {
+          return new Response(
+            JSON.stringify({
+              success: false,
+              error: {
+                code: "INVALID_PROMPT",
+                message: '"prompt" is required for streaming generation'
+              }
+            }),
+            {
+              status: 400,
+              headers: { "Content-Type": "application/json" }
+            }
+          );
+        }
+        const encoder = new TextEncoder();
+        const readable = new ReadableStream({
+          async start(controller) {
+            try {
+              for await (const event of engine.streamPage(
+                {
+                  prompt: body.prompt,
+                  stylePreference: body.stylePreference,
+                  tone: body.tone,
+                  locale: body.locale,
+                  metadata: body.metadata
+                },
+                { signal: request.signal }
+              )) {
+                controller.enqueue(
+                  encoder.encode(`event: ${event.type}
+data: ${JSON.stringify(event)}
+
+`)
+                );
+              }
+            } catch (err) {
+              const message = err instanceof Error ? err.message : String(err);
+              controller.enqueue(
+                encoder.encode(
+                  `event: error
+data: ${JSON.stringify({ type: "error", error: { code: "STREAM_ERROR", message } })}
+
+`
+                )
+              );
+            } finally {
+              controller.close();
+            }
+          }
+        });
+        return new Response(readable, {
+          status: 200,
+          headers: {
+            "Content-Type": "text/event-stream",
+            "Cache-Control": "no-cache, no-transform",
+            Connection: "keep-alive"
+          }
+        });
+      }
+      const { status, response } = await processAiRequest(
+        engine,
+        body,
+        request.signal
+      );
+      return new Response(JSON.stringify(response), {
+        status,
+        headers: {
+          "Content-Type": "application/json"
+        }
+      });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return new Response(
+        JSON.stringify({
+          success: false,
+          error: {
+            code: "INTERNAL_SERVER_ERROR",
+            message
+          }
+        }),
+        {
+          status: 500,
+          headers: {
+            "Content-Type": "application/json"
+          }
+        }
+      );
+    }
+  };
+}
+
+// src/server/adapters/stream-utils.ts
+async function* readSseDataLines(body, signal) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    while (true) {
+      if (signal?.aborted) {
+        throw new Error("Streaming aborted by client");
+      }
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const frames = buffer.split("\n\n");
+      buffer = frames.pop() || "";
+      for (const frame of frames) {
+        for (const line of frame.split("\n")) {
+          const trimmed = line.trim();
+          if (trimmed.startsWith("data:")) {
+            yield trimmed.slice(5).trim();
+          }
+        }
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+// src/server/adapters/gemini.ts
+var GeminiAdapter = class {
+  name = "gemini";
+  apiKey;
+  model;
+  temperature;
+  baseUrl;
+  constructor(options) {
+    if (!options.apiKey) {
+      throw new Error("GeminiAdapter requires an apiKey");
+    }
+    this.apiKey = options.apiKey;
+    this.model = options.model || "gemini-2.5-flash";
+    this.temperature = options.temperature ?? 0.4;
+    this.baseUrl = options.baseUrl || "https://generativelanguage.googleapis.com/v1beta";
+  }
+  buildContents(params) {
+    const { userPrompt, messages: chatMessages } = params;
+    return chatMessages && chatMessages.length > 0 ? chatMessages.map((m) => ({
+      role: m.role === "assistant" ? "model" : "user",
+      parts: [{ text: m.content }]
+    })) : [
+      {
+        role: "user",
+        parts: [{ text: userPrompt }]
+      }
+    ];
+  }
+  async generate(params) {
+    const { systemPrompt, messages: chatMessages, signal } = params;
+    const url = `${this.baseUrl}/models/${encodeURIComponent(this.model)}:generateContent?key=${encodeURIComponent(this.apiKey)}`;
+    const contents = this.buildContents(params);
+    const generationConfig = {
+      temperature: this.temperature
+    };
+    if (params.jsonSchema || !chatMessages && (systemPrompt.includes("JSON") || systemPrompt.includes("json"))) {
+      generationConfig.responseMimeType = "application/json";
+    }
+    const body = {
+      system_instruction: {
+        parts: [{ text: systemPrompt }]
+      },
+      contents,
+      generationConfig
+    };
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(body),
+      signal
+    });
+    if (!res.ok) {
+      const errText = await res.text().catch(() => "");
+      throw new Error(
+        `Gemini API error [${res.status} ${res.statusText}]: ${errText || "Unknown error"}`
+      );
+    }
+    const data = await res.json();
+    const candidateText = data.candidates?.[0]?.content?.parts?.[0]?.text;
+    if (!candidateText) {
+      throw new Error("Gemini returned an empty or invalid candidate response");
+    }
+    return {
+      text: candidateText,
+      usage: data.usageMetadata ? {
+        promptTokens: data.usageMetadata.promptTokenCount,
+        completionTokens: data.usageMetadata.candidatesTokenCount
+      } : void 0
+    };
+  }
+  /**
+   * Token-level streaming via Gemini's `streamGenerateContent` SSE endpoint (STORA-515).
+   */
+  async *generateStream(params) {
+    const { systemPrompt, signal } = params;
+    const url = `${this.baseUrl}/models/${encodeURIComponent(this.model)}:streamGenerateContent?alt=sse&key=${encodeURIComponent(this.apiKey)}`;
+    const contents = this.buildContents(params);
+    const generationConfig = {
+      temperature: this.temperature
+    };
+    const body = {
+      system_instruction: {
+        parts: [{ text: systemPrompt }]
+      },
+      contents,
+      generationConfig
+    };
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(body),
+      signal
+    });
+    if (!res.ok) {
+      const errText = await res.text().catch(() => "");
+      throw new Error(
+        `Gemini API error [${res.status} ${res.statusText}]: ${errText || "Unknown error"}`
+      );
+    }
+    if (!res.body) {
+      throw new Error("Gemini streaming response has no readable body");
+    }
+    let text = "";
+    let usage;
+    for await (const raw of readSseDataLines(res.body, signal)) {
+      let parsed;
+      try {
+        parsed = JSON.parse(raw);
+      } catch {
+        continue;
+      }
+      const delta = parsed.candidates?.[0]?.content?.parts?.[0]?.text;
+      if (typeof delta === "string" && delta.length > 0) {
+        text += delta;
+        yield delta;
+      }
+      if (parsed.usageMetadata) {
+        usage = {
+          promptTokens: parsed.usageMetadata.promptTokenCount,
+          completionTokens: parsed.usageMetadata.candidatesTokenCount
+        };
+      }
+    }
+    return { text, usage };
+  }
+};
+
+// src/server/adapters/openai.ts
+var OpenAiAdapter = class {
+  name = "openai";
+  apiKey;
+  model;
+  temperature;
+  baseUrl;
+  customHeaders;
+  constructor(options) {
+    if (!options.apiKey) {
+      throw new Error("OpenAiAdapter requires an apiKey");
+    }
+    this.apiKey = options.apiKey;
+    this.model = options.model || "gpt-4o";
+    this.temperature = options.temperature ?? 0.4;
+    this.baseUrl = (options.baseUrl || "https://api.openai.com/v1").replace(/\/+$/, "");
+    this.customHeaders = options.headers;
+  }
+  buildMessages(params) {
+    const { systemPrompt, userPrompt, messages: chatMessages } = params;
+    return chatMessages && chatMessages.length > 0 ? [
+      { role: "system", content: systemPrompt },
+      ...chatMessages.map((m) => ({ role: m.role, content: m.content }))
+    ] : [
+      { role: "system", content: systemPrompt },
+      { role: "user", content: userPrompt }
+    ];
+  }
+  async generate(params) {
+    const { systemPrompt, signal } = params;
+    const url = `${this.baseUrl}/chat/completions`;
+    const messages = this.buildMessages(params);
+    const chatMessages = params.messages;
+    const body = {
+      model: this.model,
+      temperature: this.temperature,
+      messages
+    };
+    if (params.jsonSchema || !chatMessages && (systemPrompt.includes("JSON") || systemPrompt.includes("json"))) {
+      body.response_format = { type: "json_object" };
+    }
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.apiKey}`,
+        ...this.customHeaders
+      },
+      body: JSON.stringify(body),
+      signal
+    });
+    if (!res.ok) {
+      const errText = await res.text().catch(() => "");
+      throw new Error(
+        `OpenAI API error [${res.status} ${res.statusText}]: ${errText || "Unknown error"}`
+      );
+    }
+    const data = await res.json();
+    const content = data.choices?.[0]?.message?.content;
+    if (!content) {
+      throw new Error("OpenAI returned an empty message content");
+    }
+    return {
+      text: content,
+      usage: data.usage ? {
+        promptTokens: data.usage.prompt_tokens,
+        completionTokens: data.usage.completion_tokens
+      } : void 0
+    };
+  }
+  /**
+   * Token-level streaming via OpenAI's `stream: true` chat completions mode (STORA-515).
+   * Yields each `delta.content` fragment as it arrives and returns the fully assembled
+   * text + usage (when the final chunk includes it) once the stream ends.
+   */
+  async *generateStream(params) {
+    const { signal } = params;
+    const url = `${this.baseUrl}/chat/completions`;
+    const messages = this.buildMessages(params);
+    const body = {
+      model: this.model,
+      temperature: this.temperature,
+      messages,
+      stream: true
+    };
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.apiKey}`,
+        ...this.customHeaders
+      },
+      body: JSON.stringify(body),
+      signal
+    });
+    if (!res.ok) {
+      const errText = await res.text().catch(() => "");
+      throw new Error(
+        `OpenAI API error [${res.status} ${res.statusText}]: ${errText || "Unknown error"}`
+      );
+    }
+    if (!res.body) {
+      throw new Error("OpenAI streaming response has no readable body");
+    }
+    let text = "";
+    let usage;
+    for await (const raw of readSseDataLines(res.body, signal)) {
+      if (raw === "[DONE]") break;
+      let parsed;
+      try {
+        parsed = JSON.parse(raw);
+      } catch {
+        continue;
+      }
+      const delta = parsed.choices?.[0]?.delta?.content;
+      if (typeof delta === "string" && delta.length > 0) {
+        text += delta;
+        yield delta;
+      }
+      if (parsed.usage) {
+        usage = {
+          promptTokens: parsed.usage.prompt_tokens,
+          completionTokens: parsed.usage.completion_tokens
+        };
+      }
+    }
+    return { text, usage };
+  }
+};
+
+// src/server/adapters/anthropic.ts
+var AnthropicAdapter = class {
+  name = "anthropic";
+  apiKey;
+  model;
+  maxTokens;
+  temperature;
+  baseUrl;
+  anthropicVersion;
+  customHeaders;
+  constructor(options) {
+    if (!options.apiKey) {
+      throw new Error("AnthropicAdapter requires an apiKey");
+    }
+    this.apiKey = options.apiKey;
+    this.model = options.model || "claude-3-5-sonnet-20241022";
+    this.maxTokens = options.maxTokens ?? 4096;
+    this.temperature = options.temperature ?? 0.4;
+    this.baseUrl = (options.baseUrl || "https://api.anthropic.com/v1").replace(/\/+$/, "");
+    this.anthropicVersion = options.anthropicVersion || "2023-06-01";
+    this.customHeaders = options.headers;
+  }
+  buildMessages(params) {
+    const { userPrompt, messages: chatMessages } = params;
+    return chatMessages && chatMessages.length > 0 ? chatMessages.filter((m) => m.role === "user" || m.role === "assistant").map((m) => ({ role: m.role, content: m.content })) : [
+      {
+        role: "user",
+        content: userPrompt
+      }
+    ];
+  }
+  async generate(params) {
+    const { systemPrompt, signal } = params;
+    const url = `${this.baseUrl}/messages`;
+    const messages = this.buildMessages(params);
+    const body = {
+      model: this.model,
+      max_tokens: this.maxTokens,
+      temperature: this.temperature,
+      system: systemPrompt,
+      messages
+    };
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-api-key": this.apiKey,
+        "anthropic-version": this.anthropicVersion,
+        ...this.customHeaders
+      },
+      body: JSON.stringify(body),
+      signal
+    });
+    if (!res.ok) {
+      const errText = await res.text().catch(() => "");
+      throw new Error(
+        `Anthropic API error [${res.status} ${res.statusText}]: ${errText || "Unknown error"}`
+      );
+    }
+    const data = await res.json();
+    const textPart = data.content?.find((c) => c.type === "text")?.text;
+    if (!textPart) {
+      throw new Error("Anthropic returned an empty text content");
+    }
+    return {
+      text: textPart,
+      usage: data.usage ? {
+        promptTokens: data.usage.input_tokens,
+        completionTokens: data.usage.output_tokens
+      } : void 0
+    };
+  }
+  /**
+   * Token-level streaming via Anthropic's `stream: true` Messages API (STORA-515).
+   * Parses the `content_block_delta` (`text_delta`) events for incremental text and the
+   * `message_start`/`message_delta` events for usage accounting.
+   */
+  async *generateStream(params) {
+    const { systemPrompt, signal } = params;
+    const url = `${this.baseUrl}/messages`;
+    const messages = this.buildMessages(params);
+    const body = {
+      model: this.model,
+      max_tokens: this.maxTokens,
+      temperature: this.temperature,
+      system: systemPrompt,
+      messages,
+      stream: true
+    };
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-api-key": this.apiKey,
+        "anthropic-version": this.anthropicVersion,
+        ...this.customHeaders
+      },
+      body: JSON.stringify(body),
+      signal
+    });
+    if (!res.ok) {
+      const errText = await res.text().catch(() => "");
+      throw new Error(
+        `Anthropic API error [${res.status} ${res.statusText}]: ${errText || "Unknown error"}`
+      );
+    }
+    if (!res.body) {
+      throw new Error("Anthropic streaming response has no readable body");
+    }
+    let text = "";
+    let promptTokens;
+    let completionTokens;
+    for await (const raw of readSseDataLines(res.body, signal)) {
+      if (!raw) continue;
+      let evt;
+      try {
+        evt = JSON.parse(raw);
+      } catch {
+        continue;
+      }
+      if (evt.type === "content_block_delta" && evt.delta?.type === "text_delta") {
+        const delta = evt.delta.text;
+        if (typeof delta === "string" && delta.length > 0) {
+          text += delta;
+          yield delta;
+        }
+      } else if (evt.type === "message_start" && evt.message?.usage?.input_tokens !== void 0) {
+        promptTokens = evt.message.usage.input_tokens;
+      } else if (evt.type === "message_delta" && evt.usage?.output_tokens !== void 0) {
+        completionTokens = evt.usage.output_tokens;
+      }
+    }
+    return {
+      text,
+      usage: promptTokens !== void 0 || completionTokens !== void 0 ? { promptTokens, completionTokens } : void 0
+    };
+  }
+};
+
+// src/server/adapters/custom.ts
+var CustomHttpAdapter = class {
+  name;
+  url;
+  headers;
+  formatRequestBody;
+  parseResponse;
+  constructor(options) {
+    if (!options.url) {
+      throw new Error("CustomHttpAdapter requires a url");
+    }
+    this.url = options.url;
+    this.name = options.name || "custom-http";
+    this.headers = options.headers;
+    this.formatRequestBody = options.formatRequestBody || ((params) => ({
+      messages: params.messages && params.messages.length > 0 ? [
+        { role: "system", content: params.systemPrompt },
+        ...params.messages.map((m) => ({ role: m.role, content: m.content }))
+      ] : [
+        { role: "system", content: params.systemPrompt },
+        { role: "user", content: params.userPrompt }
+      ]
+    }));
+    this.parseResponse = options.parseResponse || ((json) => {
+      if (!json || typeof json !== "object") {
+        throw new Error("Response is not a valid JSON object");
+      }
+      const obj = json;
+      if (typeof obj.response === "string") return obj.response;
+      if (typeof obj.text === "string") return obj.text;
+      const choices = obj.choices;
+      if (Array.isArray(choices) && choices[0]?.message?.content) {
+        return choices[0].message.content;
+      }
+      const message = obj.message;
+      if (message && typeof message.content === "string") {
+        return message.content;
+      }
+      throw new Error("Unable to extract generated text from custom HTTP response");
+    });
+  }
+  async generate(params) {
+    const body = this.formatRequestBody(params);
+    const res = await fetch(this.url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...this.headers
+      },
+      body: JSON.stringify(body),
+      signal: params.signal
+    });
+    if (!res.ok) {
+      const errText = await res.text().catch(() => "");
+      throw new Error(
+        `Custom HTTP adapter error [${res.status} ${res.statusText}]: ${errText || "Unknown error"}`
+      );
+    }
+    const json = await res.json();
+    const text = this.parseResponse(json);
+    return { text };
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AnthropicAdapter,
+  CustomHttpAdapter,
+  GeminiAdapter,
+  KubuildAiEngine,
+  OpenAiAdapter,
+  createAiHandler,
+  processAiRequest
+});
+//# sourceMappingURL=index.cjs.map