@kubuild/ai 0.3.1 → 0.5.0

package/dist/server/index.js

@@ -1,18 +1,27 @@
 import {
+  buildAgentSystemPrompt,
   buildJsonSchemaForMode,
+  buildSelectionContext,
   buildSystemPrompt,
   compileComponentCatalog,
   extractJsonFromResponse,
+  getNodeLabel,
   normalizeAndValidatePageDocument,
   normalizeAndValidateRefactoredNode,
-  normalizeAndValidateSectionNode
-} from "../chunk-UH24LHRY.js";
+  normalizeAndValidateSectionNode,
+  normalizeNodeTree,
+  pruneNodeForPrompt,
+  summarizeNodeTree
+} from "../chunk-YETTTWHI.js";
 import {
   AnthropicAdapter,
   CustomHttpAdapter,
   GeminiAdapter,
   OpenAiAdapter
-} from "../chunk-27AY2KBI.js";
+} from "../chunk-3DRAVYU3.js";
+import {
+  getMessageText
+} from "../chunk-ILLNRABB.js";
 
 // src/server/engine.ts
 import { DocumentMetadataSchema } from "@kubuild/schema";
@@ -55,6 +64,13 @@ var KubuildAiEngine = class {
 Tone: ${request.tone}`;
       if (request.locale) userPrompt += `
 Language/Locale: ${request.locale}`;
+      if (request.conversationHistory && request.conversationHistory.length > 0) {
+        const chatContext = request.conversationHistory.map((m) => `${m.role.toUpperCase()}: ${getMessageText(m)}`).join("\n");
+        userPrompt += `
+
+Prior Conversation Discussion Context:
+${chatContext}`;
+      }
       const jsonSchema = buildJsonSchemaForMode("full-page");
       const result = await this.options.adapter.generate({
         systemPrompt,
@@ -193,18 +209,18 @@ ${JSON.stringify(request.node, null, 2)}`;
       };
     }
   }
-  /**
-   * 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 = `
+  buildPlanPrompts(request) {
+    let sectionGuidance = "Plan between 4 to 6 cohesive, essential sections (e.g., hero, features, testimonials, pricing, cta, footer) that fulfill the request thoroughly.";
+    if (typeof request.sectionCount === "number") {
+      sectionGuidance = `Plan exactly ${request.sectionCount} cohesive sections that fulfill the request.`;
+    } else if (request.sectionCount?.min || request.sectionCount?.max) {
+      const min = request.sectionCount.min ?? 3;
+      const max = request.sectionCount.max ?? 8;
+      sectionGuidance = `Plan between ${min} and ${max} cohesive sections that fulfill the request.`;
+    } else {
+      sectionGuidance += " If the user request mentions a specific number or list of sections, respect the user request.";
+    }
+    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):
 {
@@ -226,44 +242,113 @@ Given the user's prompt, plan the website structure. Output pure JSON (no markdo
     }
   ]
 }
-Plan 3 cohesive, essential sections (e.g., hero, features, and cta) that fulfill the request.
+${sectionGuidance}
 `;
-      let planUserPrompt = `User Request: ${request.prompt}`;
-      if (request.stylePreference) {
-        planUserPrompt += `
+    let planUserPrompt = `User Request: ${request.prompt}`;
+    if (request.stylePreference) {
+      planUserPrompt += `
 Style Preference: ${request.stylePreference}`;
-      }
-      if (request.tone) planUserPrompt += `
+    }
+    if (request.tone) planUserPrompt += `
 Tone: ${request.tone}`;
-      if (request.locale) planUserPrompt += `
+    if (request.locale) planUserPrompt += `
 Locale: ${request.locale}`;
-      this.log("info", "[SSE] Generating website layout plan...");
+    if (request.conversationHistory && request.conversationHistory.length > 0) {
+      const chatContext = request.conversationHistory.map((m) => `${m.role.toUpperCase()}: ${getMessageText(m)}`).join("\n");
+      planUserPrompt += `
+
+Prior Conversation Discussion Context:
+${chatContext}`;
+    }
+    return { systemPrompt: planSystemPrompt, userPrompt: planUserPrompt };
+  }
+  async planPage(request, context) {
+    let rawText = "";
+    try {
+      const { systemPrompt, userPrompt } = this.buildPlanPrompts(request);
+      this.log("info", `Planning website layout for: "${request.prompt}"`);
       const planResult = await this.options.adapter.generate({
-        systemPrompt: planSystemPrompt,
-        userPrompt: planUserPrompt,
+        systemPrompt,
+        userPrompt,
         signal: context?.signal
       });
-      this.log("debug", "[SSE] Raw plan response from model", planResult.text);
+      rawText = planResult.text;
+      const plan = extractJsonFromResponse(rawText);
+      return {
+        success: true,
+        data: plan,
+        usage: planResult.usage,
+        rawModelResponse: rawText
+      };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      this.log("warn", "Failed to generate plan JSON, using fallback plan", message);
+      const fallbackPlan = {
+        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: "testimonials", title: "Testimonials", prompt: `Social proof and customer reviews for: ${request.prompt}` },
+          { type: "cta", title: "Call To Action", prompt: `Call to action section for: ${request.prompt}` },
+          { type: "footer", title: "Footer", prompt: `Footer navigation and copyright for: ${request.prompt}` }
+        ]
+      };
+      return {
+        success: true,
+        data: fallbackPlan,
+        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..."
+      };
       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}` }
-          ]
-        };
+      if (request.plan && Array.isArray(request.plan.sections) && request.plan.sections.length > 0) {
+        plan = request.plan;
+        this.log("info", `[SSE] Using approved pre-planned structure with ${plan.sections?.length ?? 0} sections`);
+      } else {
+        const { systemPrompt: planSystemPrompt, userPrompt: planUserPrompt } = this.buildPlanPrompts(request);
+        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);
+        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: "testimonials", title: "Testimonials", prompt: `Social proof for: ${request.prompt}` },
+              { type: "cta", title: "Call To Action", prompt: `Call to action section for: ${request.prompt}` },
+              { type: "footer", title: "Footer", prompt: `Footer 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}` }
+        { type: "testimonials", title: "Testimonials", prompt: `Social proof for: ${request.prompt}` },
+        { type: "cta", title: "Call To Action", prompt: `CTA section for: ${request.prompt}` },
+        { type: "footer", title: "Footer", prompt: `Footer section for: ${request.prompt}` }
       ];
       const metadata = DocumentMetadataSchema.parse({
         title: plan.title || "AI Generated Page",
@@ -423,7 +508,7 @@ ${sectionSummary || "(Canvas is currently empty)"}
 Currently Selected Component Node ID: "${request.selectedNodeId}"`;
     }
     const lastUserMsg = [...request.messages].reverse().find((m) => m.role === "user");
-    const userPrompt = lastUserMsg?.content || "Hello";
+    const userPrompt = lastUserMsg ? getMessageText(lastUserMsg) || "Hello" : "Hello";
     return { systemPrompt, userPrompt };
   }
   /**
@@ -564,8 +649,1067 @@ Currently Selected Component Node ID: "${request.selectedNodeId}"`;
   }
 };
 
+// src/server/tools/helpers.ts
+import { NodeSchema } from "@kubuild/schema";
+import {
+  collectNodeIdSet,
+  findNodeById,
+  validateDocumentSecurity
+} from "@kubuild/core";
+function fail(summary, message, extra) {
+  return {
+    ok: false,
+    summary,
+    content: { ok: false, error: message, ...extra ?? {} }
+  };
+}
+function succeed(summary, content, rest) {
+  return { ok: true, summary, content: { ok: true, ...content }, ...rest ?? {} };
+}
+function readString(input, key) {
+  const value = input[key];
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function readPlainObject(input, key) {
+  const value = input[key];
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  return value;
+}
+function readOptionalIndex(input, key) {
+  const value = input[key];
+  if (typeof value === "number" && Number.isInteger(value) && value >= 0) return value;
+  return void 0;
+}
+function similarity(a, b) {
+  if (a === b) return Infinity;
+  let shared = 0;
+  const max = Math.min(a.length, b.length);
+  while (shared < max && a[shared] === b[shared]) shared++;
+  return shared + (a.includes(b) || b.includes(a) ? 3 : 0);
+}
+function suggestNodeIds(document, badId, limit = 5) {
+  return Array.from(collectNodeIdSet(document.document)).map((id) => ({ id, score: similarity(id.toLowerCase(), badId.toLowerCase()) })).filter((entry) => entry.score > 0).sort((a, b) => b.score - a.score).slice(0, limit).map((entry) => entry.id);
+}
+function resolveNode(document, nodeId, toolName) {
+  const node = findNodeById(document.document, nodeId);
+  if (!node) {
+    return {
+      error: fail(
+        `${toolName}: node "${nodeId}" tidak ditemukan`,
+        `No node with id "${nodeId}" exists in this page. Node ids must come from the outline or from a tool result \u2014 never invented.`,
+        { suggestedNodeIds: suggestNodeIds(document, nodeId) }
+      )
+    };
+  }
+  return { node };
+}
+function findCatalogEntry(catalog, type) {
+  return catalog.find((entry) => entry.type === type);
+}
+function checkNesting(catalog, parent, childType) {
+  if (catalog.length === 0) return null;
+  const parentSpec = findCatalogEntry(catalog, parent.type);
+  if (parentSpec && !parentSpec.acceptsChildren) {
+    return `Component "${parent.type}" (#${parent.id}) cannot contain children. Insert into a container/section node instead.`;
+  }
+  if (parentSpec?.allowedChildren && parentSpec.allowedChildren.length > 0) {
+    if (!parentSpec.allowedChildren.includes(childType)) {
+      return `Component "${parent.type}" only accepts children of type [${parentSpec.allowedChildren.join(", ")}] \u2014 "${childType}" is not allowed.`;
+    }
+  }
+  const childSpec = findCatalogEntry(catalog, childType);
+  if (childSpec?.disallowedParents?.includes(parent.type)) {
+    return `Component "${childType}" cannot be placed inside "${parent.type}".`;
+  }
+  return null;
+}
+function checkComponentType(catalog, type) {
+  if (catalog.length === 0) return null;
+  if (findCatalogEntry(catalog, type)) return null;
+  const known = catalog.map((entry) => entry.type);
+  return `Unknown component type "${type}". Use list_component_types to see valid types. Known types: ${known.slice(0, 40).join(", ")}${known.length > 40 ? ", \u2026" : ""}`;
+}
+function checkDocumentSecurity(document, limits) {
+  const result = validateDocumentSecurity(document, limits);
+  if (result.safe) return null;
+  return result.errors.map((error) => `${error.code}: ${error.message}`).join("; ");
+}
+function normalizeIncomingNode(raw, document, options = {}) {
+  let normalized;
+  try {
+    normalized = normalizeNodeTree(raw);
+  } catch (err) {
+    return { error: err instanceof Error ? err.message : String(err) };
+  }
+  if (!options.preserveIds) {
+    const taken = collectNodeIdSet(document.document);
+    const reassign = (node) => {
+      if (!node.id || taken.has(node.id)) {
+        let counter = 1;
+        let candidate = `${node.type}-${counter}`;
+        while (taken.has(candidate)) {
+          counter++;
+          candidate = `${node.type}-${counter}`;
+        }
+        node.id = candidate;
+      }
+      taken.add(node.id);
+      for (const child of node.children ?? []) reassign(child);
+    };
+    reassign(normalized);
+  }
+  const parsed = NodeSchema.safeParse(normalized);
+  if (!parsed.success) {
+    return {
+      error: parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")
+    };
+  }
+  return { node: parsed.data };
+}
+function describeNode(node) {
+  const label = getNodeLabel(node, 32);
+  return label ? `${node.type} "${label}" (#${node.id})` : `${node.type} (#${node.id})`;
+}
+
+// src/server/tools/read-tools.ts
+var getPageOutline = {
+  kind: "read",
+  definition: {
+    name: "get_page_outline",
+    description: "Return the page structure as an indented outline of node ids, types, labels and child counts. Use this to re-orient after edits. Does not include props or styles \u2014 call read_node for those.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        maxDepth: {
+          type: "integer",
+          description: "How deep to expand the tree before collapsing. Default 3."
+        }
+      }
+    }
+  },
+  execute(input, context) {
+    const maxDepth = typeof input.maxDepth === "number" && input.maxDepth > 0 ? Math.floor(input.maxDepth) : 3;
+    return succeed("Membaca struktur halaman", {
+      outline: summarizeNodeTree(context.document.document, { maxDepth })
+    });
+  }
+};
+var readNode = {
+  kind: "read",
+  definition: {
+    name: "read_node",
+    description: "Return one node with its full props and styles, plus its parent, position and siblings. Always read a node before editing it, so you change only the fields that need changing.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        nodeId: { type: "string", description: "Id of the node to read (from the outline)." },
+        includeChildren: {
+          type: "boolean",
+          description: "Include the node subtree. Default false \u2014 keeps the result small."
+        }
+      },
+      required: ["nodeId"]
+    }
+  },
+  execute(input, context) {
+    const nodeId = readString(input, "nodeId");
+    if (!nodeId) return fail("read_node: nodeId kosong", 'Argument "nodeId" is required.');
+    const resolved = resolveNode(context.document, nodeId, "read_node");
+    if ("error" in resolved) return resolved.error;
+    const selection = buildSelectionContext(context.document.document, nodeId);
+    const includeChildren = input.includeChildren === true;
+    const node = includeChildren ? pruneNodeForPrompt(resolved.node, 3) : { ...resolved.node, children: void 0 };
+    return succeed(`Membaca node ${nodeId}`, {
+      node,
+      childCount: resolved.node.children?.length ?? 0,
+      parentId: selection?.parentId ?? null,
+      index: selection?.index ?? 0,
+      ancestors: selection?.ancestors.map((a) => ({ id: a.id, type: a.type })) ?? [],
+      siblings: selection?.siblings.map((sibling, i) => ({
+        index: i,
+        id: sibling.id,
+        type: sibling.type,
+        label: getNodeLabel(sibling)
+      })) ?? []
+    });
+  }
+};
+var findNodes = {
+  kind: "read",
+  definition: {
+    name: "find_nodes",
+    description: 'Search the page for nodes by component type and/or visible text. Use this instead of guessing ids when the user refers to something by what it says ("the Get Started button").',
+    inputSchema: {
+      type: "object",
+      properties: {
+        type: { type: "string", description: 'Component type to match exactly, e.g. "button".' },
+        textContains: {
+          type: "string",
+          description: "Case-insensitive substring to match against the node text/label props."
+        },
+        parentId: { type: "string", description: "Limit the search to this node subtree." },
+        limit: { type: "integer", description: "Max results. Default 20." }
+      }
+    }
+  },
+  execute(input, context) {
+    const type = readString(input, "type");
+    const textContains = readString(input, "textContains");
+    const parentId = readString(input, "parentId");
+    const limit = typeof input.limit === "number" && input.limit > 0 ? Math.floor(input.limit) : 20;
+    if (!type && !textContains) {
+      return fail(
+        "find_nodes: filter kosong",
+        'Provide at least one of "type" or "textContains" \u2014 an unfiltered search would just return the whole outline.'
+      );
+    }
+    let root = context.document.document;
+    if (parentId) {
+      const resolved = resolveNode(context.document, parentId, "find_nodes");
+      if ("error" in resolved) return resolved.error;
+      root = resolved.node;
+    }
+    const needle = textContains?.toLowerCase();
+    const matches = [];
+    const walk = (node) => {
+      if (matches.length >= limit) return;
+      const label = getNodeLabel(node);
+      const typeMatches = !type || node.type === type;
+      const textMatches = !needle || label.toLowerCase().includes(needle);
+      if (typeMatches && textMatches) {
+        matches.push({ id: node.id, type: node.type, label });
+      }
+      for (const child of node.children ?? []) walk(child);
+    };
+    walk(root);
+    return succeed(
+      `Mencari node (${matches.length} hasil)`,
+      matches.length > 0 ? { matches, count: matches.length } : {
+        matches: [],
+        count: 0,
+        hint: "Nothing matched. Try a broader filter, or call get_page_outline to see what exists."
+      }
+    );
+  }
+};
+var listComponentTypes = {
+  kind: "read",
+  definition: {
+    name: "list_component_types",
+    description: "List component types available in this editor, with their props and nesting rules. Call this before inserting a component type you have not used yet.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        category: { type: "string", description: 'Filter to one category, e.g. "layout".' }
+      }
+    }
+  },
+  execute(input, context) {
+    const category = readString(input, "category");
+    const entries = category ? context.catalog.filter((spec) => spec.category === category) : context.catalog;
+    return succeed(`Melihat katalog komponen (${entries.length})`, {
+      components: entries.map((spec) => ({
+        type: spec.type,
+        label: spec.label,
+        category: spec.category,
+        acceptsChildren: spec.acceptsChildren,
+        allowedChildren: spec.allowedChildren,
+        props: spec.props?.map((prop) => ({
+          name: prop.name,
+          type: prop.type,
+          options: prop.options
+        }))
+      }))
+    });
+  }
+};
+var READ_TOOLS = [getPageOutline, readNode, findNodes, listComponentTypes];
+
+// src/server/tools/write-tools.ts
+import {
+  duplicateNode,
+  findNodeById as findNodeById2,
+  insertNode,
+  moveNode,
+  removeNode,
+  replaceNode,
+  updateProps,
+  updateStyle
+} from "@kubuild/core";
+var BREAKPOINTS = ["base", "desktop", "tablet", "mobile"];
+function applyCommand(toolName, run) {
+  try {
+    return run();
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { error: fail(`${toolName} gagal`, message) };
+  }
+}
+function guardSecurity(toolName, document, context) {
+  const violation = checkDocumentSecurity(document, context.securityLimits);
+  if (!violation) return null;
+  return fail(
+    `${toolName} ditolak (security)`,
+    `The resulting document failed the security check and was rejected: ${violation}`
+  );
+}
+var updateNodeProps = {
+  kind: "write",
+  definition: {
+    name: "update_node_props",
+    description: "Change the props of one existing node (text, label, href, src, level, \u2026). This is the right tool for any content/copy change \u2014 it touches nothing else on the page.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        nodeId: { type: "string", description: "Id of the node to edit." },
+        props: {
+          type: "object",
+          description: "Props to write. Include only the props that should change."
+        },
+        merge: {
+          type: "boolean",
+          description: "true (default) merges with existing props. Only pass false to deliberately clear the other props."
+        }
+      },
+      required: ["nodeId", "props"]
+    }
+  },
+  execute(input, context) {
+    const nodeId = readString(input, "nodeId");
+    if (!nodeId) return fail("update_node_props: nodeId kosong", 'Argument "nodeId" is required.');
+    const props = readPlainObject(input, "props");
+    if (!props) {
+      return fail(
+        "update_node_props: props tidak valid",
+        'Argument "props" must be a JSON object of prop names to values.'
+      );
+    }
+    const resolved = resolveNode(context.document, nodeId, "update_node_props");
+    if ("error" in resolved) return resolved.error;
+    const merge = input.merge !== false;
+    const applied = applyCommand(
+      "update_node_props",
+      () => updateProps(context.document, { nodeId, props, merge })
+    );
+    if ("error" in applied) return applied.error;
+    const violation = guardSecurity("update_node_props", applied.document, context);
+    if (violation) return violation;
+    const op = { kind: "update-props", nodeId, props, merge };
+    const updated = findNodeById2(applied.document.document, nodeId);
+    return succeed(
+      `Ubah props ${describeNode(resolved.node)}`,
+      { nodeId, props: updated?.props ?? props, changedKeys: Object.keys(props) },
+      { op, document: applied.document }
+    );
+  }
+};
+var updateNodeStyles = {
+  kind: "write",
+  definition: {
+    name: "update_node_styles",
+    description: 'Change the styles of one existing node. Use `breakpoint` for normal styling and `state` for pseudo-classes like ":hover". This is the right tool for any color/spacing/size/typography change.',
+    inputSchema: {
+      type: "object",
+      properties: {
+        nodeId: { type: "string", description: "Id of the node to restyle." },
+        styles: {
+          type: "object",
+          description: 'CSS properties in camelCase with primitive values, e.g. { "backgroundColor": "#16a34a", "paddingTop": "24px" }. Never nest objects here.'
+        },
+        breakpoint: {
+          type: "string",
+          enum: ["base", "desktop", "tablet", "mobile"],
+          description: 'Breakpoint layer to write. Default "base".'
+        },
+        state: {
+          type: "string",
+          description: 'Pseudo-state layer such as ":hover", ":focus", ":active". Mutually exclusive with breakpoint.'
+        },
+        merge: {
+          type: "boolean",
+          description: "true (default) merges with existing styles in that layer."
+        }
+      },
+      required: ["nodeId", "styles"]
+    }
+  },
+  execute(input, context) {
+    const nodeId = readString(input, "nodeId");
+    if (!nodeId) return fail("update_node_styles: nodeId kosong", 'Argument "nodeId" is required.');
+    const styles = readPlainObject(input, "styles");
+    if (!styles) {
+      return fail(
+        "update_node_styles: styles tidak valid",
+        'Argument "styles" must be a JSON object of CSS properties with primitive values.'
+      );
+    }
+    const nested = Object.entries(styles).find(
+      ([, value]) => value !== null && typeof value === "object"
+    );
+    if (nested) {
+      return fail(
+        "update_node_styles: nilai bersarang",
+        `Style property "${nested[0]}" has an object value. Style values must be primitives \u2014 use the "state" argument for pseudo-classes instead of nesting them.`
+      );
+    }
+    const rawState = readString(input, "state");
+    const rawBreakpoint = readString(input, "breakpoint");
+    if (rawState && rawBreakpoint) {
+      return fail(
+        "update_node_styles: argumen bentrok",
+        'Pass either "breakpoint" or "state", not both \u2014 a pseudo-state layer is not per-breakpoint.'
+      );
+    }
+    if (rawBreakpoint && !BREAKPOINTS.includes(rawBreakpoint)) {
+      return fail(
+        "update_node_styles: breakpoint tidak dikenal",
+        `Unknown breakpoint "${rawBreakpoint}". Valid values: ${BREAKPOINTS.join(", ")}.`
+      );
+    }
+    const resolved = resolveNode(context.document, nodeId, "update_node_styles");
+    if ("error" in resolved) return resolved.error;
+    const state = rawState ? rawState.startsWith(":") ? rawState : `:${rawState}` : void 0;
+    const breakpoint = state ? void 0 : rawBreakpoint ?? "base";
+    const merge = input.merge !== false;
+    const applied = applyCommand(
+      "update_node_styles",
+      () => updateStyle(context.document, { nodeId, styles, breakpoint, state, merge })
+    );
+    if ("error" in applied) return applied.error;
+    const violation = guardSecurity("update_node_styles", applied.document, context);
+    if (violation) return violation;
+    const op = { kind: "update-styles", nodeId, styles, breakpoint, state, merge };
+    const layer = state ? `state ${state}` : `breakpoint ${breakpoint}`;
+    return succeed(
+      `Ubah style ${describeNode(resolved.node)} (${layer})`,
+      { nodeId, layer, appliedStyles: styles },
+      { op, document: applied.document }
+    );
+  }
+};
+var insertComponent = {
+  kind: "write",
+  definition: {
+    name: "insert_component",
+    description: "Insert one new component into an existing parent node. Use this for adding a single element (a button, a paragraph, an image). For a whole new page section, use insert_section instead.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        parentId: { type: "string", description: "Id of the node that will contain the new component." },
+        type: { type: "string", description: "Component type from the catalog." },
+        index: {
+          type: "integer",
+          description: "Position among the parent children. Omit to append at the end."
+        },
+        props: { type: "object", description: "Initial props for the new component." },
+        styles: {
+          type: "object",
+          description: 'Initial styles, e.g. { "base": { "marginTop": "16px" } }.'
+        },
+        children: {
+          type: "array",
+          description: "Optional nested child nodes, each { type, props?, styles?, children? }.",
+          items: { type: "object" }
+        }
+      },
+      required: ["parentId", "type"]
+    }
+  },
+  execute(input, context) {
+    const parentId = readString(input, "parentId");
+    const type = readString(input, "type");
+    if (!parentId || !type) {
+      return fail(
+        "insert_component: argumen kurang",
+        'Arguments "parentId" and "type" are both required.'
+      );
+    }
+    const typeError = checkComponentType(context.catalog, type);
+    if (typeError) return fail("insert_component: tipe tidak dikenal", typeError);
+    const resolvedParent = resolveNode(context.document, parentId, "insert_component");
+    if ("error" in resolvedParent) return resolvedParent.error;
+    const nestingError = checkNesting(context.catalog, resolvedParent.node, type);
+    if (nestingError) return fail("insert_component: nesting tidak valid", nestingError);
+    const normalized = normalizeIncomingNode(
+      {
+        type,
+        props: readPlainObject(input, "props") ?? void 0,
+        styles: readPlainObject(input, "styles") ?? void 0,
+        children: Array.isArray(input.children) ? input.children : void 0
+      },
+      context.document
+    );
+    if ("error" in normalized) {
+      return fail("insert_component: node tidak valid", normalized.error);
+    }
+    const index = readOptionalIndex(input, "index");
+    const applied = applyCommand(
+      "insert_component",
+      () => insertNode(context.document, { parentId, node: normalized.node, index })
+    );
+    if ("error" in applied) return applied.error;
+    const violation = guardSecurity("insert_component", applied.document, context);
+    if (violation) return violation;
+    const op = { kind: "insert-node", parentId, index, node: normalized.node };
+    return succeed(
+      `Tambah ${describeNode(normalized.node)} ke #${parentId}`,
+      { nodeId: normalized.node.id, parentId, index: index ?? null },
+      { op, document: applied.document }
+    );
+  }
+};
+var insertSection = {
+  kind: "write",
+  definition: {
+    name: "insert_section",
+    description: "Generate and insert a complete new page section (hero, features, pricing, FAQ, CTA, \u2026) from a description. Use this when the user asks to ADD a section \u2014 do not hand-build sections with insert_component.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        prompt: {
+          type: "string",
+          description: "Detailed description of the section: purpose, content, layout and tone. Write it in the language the page uses."
+        },
+        index: {
+          type: "integer",
+          description: "Position among the page sections. Omit to append at the end."
+        }
+      },
+      required: ["prompt"]
+    }
+  },
+  async execute(input, context) {
+    const prompt = readString(input, "prompt");
+    if (!prompt) return fail("insert_section: prompt kosong", 'Argument "prompt" is required.');
+    if (!context.generateSection) {
+      return fail(
+        "insert_section: tidak tersedia",
+        "Section generation is not available in this deployment. Build the section with insert_component instead."
+      );
+    }
+    const rootId = context.document.document.id;
+    const existingSections = (context.document.document.children ?? []).map((child) => `${child.type}: ${getNodeLabel(child) || child.id}`).join(", ");
+    let generated;
+    try {
+      generated = await context.generateSection({
+        prompt,
+        parentContext: `Page "${context.document.metadata?.title ?? "Untitled"}". Existing sections: ${existingSections || "(none)"}`
+      });
+    } catch (err) {
+      return fail(
+        "insert_section gagal",
+        `Section generation failed: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+    const normalized = normalizeIncomingNode(generated, context.document);
+    if ("error" in normalized) {
+      return fail("insert_section: section tidak valid", normalized.error);
+    }
+    const index = readOptionalIndex(input, "index");
+    const applied = applyCommand(
+      "insert_section",
+      () => insertNode(context.document, { parentId: rootId, node: normalized.node, index })
+    );
+    if ("error" in applied) return applied.error;
+    const violation = guardSecurity("insert_section", applied.document, context);
+    if (violation) return violation;
+    const op = { kind: "insert-node", parentId: rootId, index, node: normalized.node };
+    return succeed(
+      `Tambah section baru (#${normalized.node.id})`,
+      {
+        nodeId: normalized.node.id,
+        index: index ?? null,
+        childCount: normalized.node.children?.length ?? 0
+      },
+      { op, document: applied.document }
+    );
+  }
+};
+var moveNodeTool = {
+  kind: "write",
+  definition: {
+    name: "move_node",
+    description: "Move an existing node to a different parent and/or position.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        nodeId: { type: "string" },
+        targetParentId: { type: "string", description: "Id of the new parent node." },
+        index: { type: "integer", description: "Position within the new parent. Omit to append." }
+      },
+      required: ["nodeId", "targetParentId"]
+    }
+  },
+  execute(input, context) {
+    const nodeId = readString(input, "nodeId");
+    const targetParentId = readString(input, "targetParentId");
+    if (!nodeId || !targetParentId) {
+      return fail(
+        "move_node: argumen kurang",
+        'Arguments "nodeId" and "targetParentId" are both required.'
+      );
+    }
+    const resolved = resolveNode(context.document, nodeId, "move_node");
+    if ("error" in resolved) return resolved.error;
+    const resolvedParent = resolveNode(context.document, targetParentId, "move_node");
+    if ("error" in resolvedParent) return resolvedParent.error;
+    const nestingError = checkNesting(context.catalog, resolvedParent.node, resolved.node.type);
+    if (nestingError) return fail("move_node: nesting tidak valid", nestingError);
+    const index = readOptionalIndex(input, "index");
+    const applied = applyCommand(
+      "move_node",
+      () => moveNode(context.document, { nodeId, targetParentId, index })
+    );
+    if ("error" in applied) return applied.error;
+    const violation = guardSecurity("move_node", applied.document, context);
+    if (violation) return violation;
+    const op = { kind: "move-node", nodeId, targetParentId, index };
+    return succeed(
+      `Pindah ${describeNode(resolved.node)} ke #${targetParentId}`,
+      { nodeId, targetParentId, index: index ?? null },
+      { op, document: applied.document }
+    );
+  }
+};
+var duplicateNodeTool = {
+  kind: "write",
+  definition: {
+    name: "duplicate_node",
+    description: "Duplicate an existing node and its subtree, with fresh ids. Useful for repeating an existing card/feature rather than authoring a new one from scratch.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        nodeId: { type: "string" },
+        targetParentId: {
+          type: "string",
+          description: "Where to put the copy. Defaults to the original node parent."
+        },
+        index: { type: "integer", description: "Position of the copy. Defaults to right after the original." }
+      },
+      required: ["nodeId"]
+    }
+  },
+  execute(input, context) {
+    const nodeId = readString(input, "nodeId");
+    if (!nodeId) return fail("duplicate_node: nodeId kosong", 'Argument "nodeId" is required.');
+    const resolved = resolveNode(context.document, nodeId, "duplicate_node");
+    if ("error" in resolved) return resolved.error;
+    const targetParentId = readString(input, "targetParentId") ?? void 0;
+    if (targetParentId) {
+      const resolvedParent = resolveNode(context.document, targetParentId, "duplicate_node");
+      if ("error" in resolvedParent) return resolvedParent.error;
+    }
+    const index = readOptionalIndex(input, "index");
+    const applied = applyCommand(
+      "duplicate_node",
+      () => duplicateNode(context.document, { nodeId, targetParentId, index })
+    );
+    if ("error" in applied) return applied.error;
+    const violation = guardSecurity("duplicate_node", applied.document, context);
+    if (violation) return violation;
+    const op = { kind: "duplicate-node", nodeId, targetParentId, index };
+    return succeed(
+      `Duplikat ${describeNode(resolved.node)}`,
+      { nodeId, targetParentId: targetParentId ?? null, index: index ?? null },
+      { op, document: applied.document }
+    );
+  }
+};
+var deleteNode = {
+  kind: "write",
+  destructive: true,
+  definition: {
+    name: "delete_node",
+    description: "Permanently remove a node and everything inside it. Only call this when the user unambiguously asked to remove that specific thing. If the request is vague, ask instead.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        nodeId: { type: "string" },
+        reason: {
+          type: "string",
+          description: "Short justification quoting what the user asked for. Shown to the user before they apply."
+        }
+      },
+      required: ["nodeId", "reason"]
+    }
+  },
+  execute(input, context) {
+    const nodeId = readString(input, "nodeId");
+    if (!nodeId) return fail("delete_node: nodeId kosong", 'Argument "nodeId" is required.');
+    const reason = readString(input, "reason");
+    if (!reason) {
+      return fail(
+        "delete_node: alasan kosong",
+        'Argument "reason" is required for destructive actions \u2014 state what the user asked for.'
+      );
+    }
+    const resolved = resolveNode(context.document, nodeId, "delete_node");
+    if ("error" in resolved) return resolved.error;
+    const applied = applyCommand("delete_node", () => removeNode(context.document, { nodeId }));
+    if ("error" in applied) return applied.error;
+    const op = { kind: "delete-node", nodeId };
+    return succeed(
+      `Hapus ${describeNode(resolved.node)} \u2014 ${reason}`,
+      { nodeId, removedType: resolved.node.type },
+      { op, document: applied.document }
+    );
+  }
+};
+var replaceNodeTool = {
+  kind: "write",
+  destructive: true,
+  definition: {
+    name: "replace_node",
+    description: "Replace a node subtree wholesale. LAST RESORT \u2014 only when the children genuinely must be restructured. Never use it to change props or styles; use update_node_props / update_node_styles for that.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        nodeId: { type: "string", description: "Id of the node being replaced. The replacement keeps this id." },
+        node: {
+          type: "object",
+          description: "Replacement node { type, props?, styles?, children? }. Its id is forced to nodeId."
+        },
+        reason: {
+          type: "string",
+          description: "Why a structural replacement is required instead of a props/styles edit."
+        }
+      },
+      required: ["nodeId", "node", "reason"]
+    }
+  },
+  execute(input, context) {
+    const nodeId = readString(input, "nodeId");
+    const raw = readPlainObject(input, "node");
+    const reason = readString(input, "reason");
+    if (!nodeId || !raw || !reason) {
+      return fail(
+        "replace_node: argumen kurang",
+        'Arguments "nodeId", "node" and "reason" are all required.'
+      );
+    }
+    const resolved = resolveNode(context.document, nodeId, "replace_node");
+    if ("error" in resolved) return resolved.error;
+    const normalized = normalizeIncomingNode({ ...raw, id: void 0 }, context.document);
+    if ("error" in normalized) {
+      return fail("replace_node: node tidak valid", normalized.error);
+    }
+    const replacement = { ...normalized.node, id: nodeId, type: resolved.node.type };
+    const applied = applyCommand(
+      "replace_node",
+      () => replaceNode(context.document, { nodeId, node: replacement })
+    );
+    if ("error" in applied) return applied.error;
+    const violation = guardSecurity("replace_node", applied.document, context);
+    if (violation) return violation;
+    const op = { kind: "replace-node", nodeId, node: replacement };
+    return succeed(
+      `Ganti struktur ${describeNode(resolved.node)} \u2014 ${reason}`,
+      { nodeId, childCount: replacement.children?.length ?? 0 },
+      { op, document: applied.document }
+    );
+  }
+};
+var WRITE_TOOLS = [
+  updateNodeProps,
+  updateNodeStyles,
+  insertComponent,
+  insertSection,
+  moveNodeTool,
+  duplicateNodeTool,
+  deleteNode,
+  replaceNodeTool
+];
+
+// src/server/tools/index.ts
+function createDocumentTools(options = {}) {
+  const { allowWrites = true, exclude = [] } = options;
+  const tools = allowWrites ? [...READ_TOOLS, ...WRITE_TOOLS] : [...READ_TOOLS];
+  return tools.filter((tool) => !exclude.includes(tool.definition.name));
+}
+function toToolDefinitions(tools) {
+  return tools.map((tool) => tool.definition);
+}
+
+// src/server/agent.ts
+var DEFAULT_MAX_STEPS = 8;
+var MAX_TOOL_CALLS_PER_STEP = 8;
+function toolResultMessage(blocks) {
+  return { role: "user", content: blocks, timestamp: Date.now() };
+}
+var KubuildAiAgent = class {
+  options;
+  catalog;
+  tools;
+  constructor(options) {
+    if (!options.adapter) {
+      throw new Error("KubuildAiAgent requires an adapter instance");
+    }
+    if (!options.adapter.supportsTools) {
+      throw new Error(
+        `Adapter "${options.adapter.name}" does not support tool calling, which agent mode requires. Use an adapter with supportsTools === true (e.g. OpenAiAdapter).`
+      );
+    }
+    this.options = options;
+    this.catalog = compileComponentCatalog(options.registry);
+    this.tools = options.tools ?? createDocumentTools();
+  }
+  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) {
+      console.log(`[KUBUILD-AGENT ${level.toUpperCase()}] ${message}`, meta !== void 0 ? meta : "");
+    }
+  }
+  findTool(name) {
+    return this.tools.find((tool) => tool.definition.name === name);
+  }
+  /**
+   * Runs one tool call against the current snapshot.
+   *
+   * An unknown tool name is answered with a normal (failed) tool result rather than an
+   * exception, for the same reason bad arguments are: it gives the model a chance to pick a
+   * real tool on the next step instead of killing the run.
+   */
+  async executeToolCall(call, snapshot, signal) {
+    const tool = this.findTool(call.name);
+    if (!tool) {
+      const available = this.tools.map((t) => t.definition.name).join(", ");
+      return {
+        ok: false,
+        summary: `Tool "${call.name}" tidak dikenal`,
+        snapshot,
+        block: {
+          type: "tool_result",
+          toolUseId: call.id,
+          isError: true,
+          content: JSON.stringify({
+            ok: false,
+            error: `Unknown tool "${call.name}". Available tools: ${available}.`
+          })
+        }
+      };
+    }
+    let result;
+    try {
+      result = await tool.execute(call.input ?? {}, {
+        document: snapshot,
+        catalog: this.catalog,
+        securityLimits: this.options.securityLimits,
+        signal,
+        generateSection: this.options.engine ? async ({ prompt, parentContext }) => {
+          const response = await this.options.engine.generateSection(
+            { prompt, parentContext },
+            { signal }
+          );
+          if (!response.success || !response.data) {
+            throw new Error(response.error?.message ?? "Section generation failed");
+          }
+          return response.data;
+        } : void 0
+      });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      this.log("error", `Tool "${call.name}" threw`, message);
+      return {
+        ok: false,
+        summary: `Tool "${call.name}" error`,
+        snapshot,
+        block: {
+          type: "tool_result",
+          toolUseId: call.id,
+          isError: true,
+          content: JSON.stringify({ ok: false, error: message })
+        }
+      };
+    }
+    const op = result.ok && result.op ? {
+      id: call.id,
+      op: result.op,
+      summary: result.summary,
+      destructive: tool.destructive === true
+    } : void 0;
+    return {
+      ok: result.ok,
+      summary: result.summary,
+      snapshot: result.document ?? snapshot,
+      op,
+      block: {
+        type: "tool_result",
+        toolUseId: call.id,
+        isError: !result.ok,
+        content: JSON.stringify(result.content)
+      }
+    };
+  }
+  /**
+   * Executes one agent turn, streaming progress as `AiStreamEvent`s and ending with a
+   * terminal `agent-complete` (or `error`) event.
+   *
+   * The loop stops as soon as the model returns a turn with no tool calls — that final
+   * message is the summary shown to the user. It also stops at `maxSteps` (cost guard) or
+   * on abort, and reports which of those happened via `stoppedBy` so the UI can say
+   * "stopped after N steps" rather than pretending the work is finished.
+   */
+  async *run(request, context) {
+    const maxSteps = request.maxSteps ?? this.options.maxAgentSteps ?? DEFAULT_MAX_STEPS;
+    const signal = context?.signal;
+    if (!request.messages || request.messages.length === 0) {
+      yield {
+        type: "error",
+        error: { code: "INVALID_AGENT_REQUEST", message: '"messages" must not be empty' }
+      };
+      return;
+    }
+    if (!request.document?.document) {
+      yield {
+        type: "error",
+        error: { code: "INVALID_AGENT_REQUEST", message: '"document" is required for agent mode' }
+      };
+      return;
+    }
+    const systemPrompt = buildAgentSystemPrompt({
+      catalog: this.catalog,
+      document: request.document,
+      selectedNodeId: request.selectedNodeId,
+      prefix: this.options.systemPromptPrefix,
+      stylePreference: request.stylePreference,
+      additionalContext: request.systemPrompt
+    });
+    const toolDefinitions = toToolDefinitions(this.tools);
+    const messages = [...request.messages];
+    const ops = [];
+    let snapshot = request.document;
+    let promptTokens = 0;
+    let completionTokens = 0;
+    let summary = "";
+    let stoppedBy = "complete";
+    let step = 0;
+    this.log("info", `[AGENT] run started (maxSteps=${maxSteps}, tools=${toolDefinitions.length})`);
+    try {
+      while (step < maxSteps) {
+        if (signal?.aborted) {
+          stoppedBy = "aborted";
+          break;
+        }
+        step++;
+        yield { type: "agent-step", step, maxSteps };
+        const result = await this.options.adapter.generate({
+          systemPrompt,
+          userPrompt: getMessageText(request.messages[request.messages.length - 1]),
+          messages,
+          tools: toolDefinitions,
+          toolChoice: "auto",
+          signal
+        });
+        promptTokens += result.usage?.promptTokens ?? 0;
+        completionTokens += result.usage?.completionTokens ?? 0;
+        const toolCalls = result.toolCalls ?? [];
+        if (toolCalls.length === 0) {
+          summary = result.text.trim();
+          stoppedBy = "complete";
+          this.log("info", `[AGENT] finished after ${step} step(s) with ${ops.length} op(s)`);
+          break;
+        }
+        const assistantBlocks = [];
+        if (result.text.trim()) {
+          assistantBlocks.push({ type: "text", text: result.text });
+        }
+        assistantBlocks.push(...toolCalls);
+        messages.push({ role: "assistant", content: assistantBlocks, timestamp: Date.now() });
+        const capped = toolCalls.slice(0, MAX_TOOL_CALLS_PER_STEP);
+        const resultBlocks = [];
+        for (const call of capped) {
+          if (signal?.aborted) {
+            stoppedBy = "aborted";
+            break;
+          }
+          yield { type: "tool-call", id: call.id, name: call.name, input: call.input ?? {} };
+          const executed = await this.executeToolCall(call, snapshot, signal);
+          snapshot = executed.snapshot;
+          resultBlocks.push(executed.block);
+          if (executed.op) ops.push(executed.op);
+          yield {
+            type: "tool-result",
+            id: call.id,
+            name: call.name,
+            ok: executed.ok,
+            summary: executed.summary
+          };
+        }
+        for (const call of toolCalls.slice(capped.length)) {
+          resultBlocks.push({
+            type: "tool_result",
+            toolUseId: call.id,
+            isError: true,
+            content: JSON.stringify({
+              ok: false,
+              error: `Too many tool calls in one step (limit ${MAX_TOOL_CALLS_PER_STEP}). This call was not executed \u2014 request it again in the next step.`
+            })
+          });
+        }
+        messages.push(toolResultMessage(resultBlocks));
+        if (stoppedBy === "aborted") break;
+      }
+      if (stoppedBy === "complete" && step >= maxSteps && !summary) {
+        stoppedBy = "max-steps";
+        summary = `Berhenti setelah ${maxSteps} langkah. ${ops.length} perubahan sudah disiapkan \u2014 periksa hasilnya lalu minta lanjutan bila perlu.`;
+        this.log("warn", `[AGENT] hit maxSteps (${maxSteps}) with ${ops.length} op(s)`);
+      }
+      if (stoppedBy === "aborted" && !summary) {
+        summary = `Dihentikan. ${ops.length} perubahan sempat disiapkan.`;
+      }
+      yield {
+        type: "agent-complete",
+        result: {
+          ops,
+          summary,
+          stepsUsed: step,
+          stoppedBy,
+          usage: { promptTokens, completionTokens }
+        }
+      };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      this.log("error", `[AGENT] run failed: ${message}`);
+      yield {
+        type: "agent-complete",
+        result: {
+          ops,
+          summary: summary || `Terjadi error: ${message}`,
+          stepsUsed: step,
+          stoppedBy: "error",
+          usage: { promptTokens, completionTokens }
+        }
+      };
+      yield { type: "error", error: { code: "AGENT_ERROR", message } };
+    }
+  }
+  /** Non-streaming convenience wrapper — drains `run()` and returns its terminal result. */
+  async execute(request, context) {
+    let final = null;
+    let error = null;
+    for await (const event of this.run(request, context)) {
+      if (event.type === "agent-complete") final = event.result;
+      if (event.type === "error") error = event.error;
+    }
+    if (final) return final;
+    return {
+      ops: [],
+      summary: error?.message ?? "Agent produced no result",
+      stepsUsed: 0,
+      stoppedBy: "error"
+    };
+  }
+};
+
 // src/server/handler.ts
-async function processAiRequest(engine, body, signal) {
+async function processAiRequest(engine, body, signal, agent) {
   if (!body || typeof body !== "object") {
     return {
       status: 400,
@@ -599,7 +1743,10 @@ async function processAiRequest(engine, body, signal) {
         stylePreference: payload.stylePreference,
         tone: payload.tone,
         locale: payload.locale,
-        metadata: payload.metadata
+        metadata: payload.metadata,
+        conversationHistory: payload.conversationHistory ?? payload.messages,
+        sectionCount: payload.sectionCount,
+        plan: payload.plan
       },
       { signal }
     );
@@ -687,17 +1834,142 @@ async function processAiRequest(engine, body, signal) {
       response: result
     };
   }
+  if (mode === "agent") {
+    const validationError = validateAgentPayload(payload, agent);
+    if (validationError) {
+      return { status: validationError.status, response: validationError.response };
+    }
+    const result = await agent.execute(
+      {
+        messages: payload.messages,
+        document: payload.document,
+        selectedNodeId: payload.selectedNodeId,
+        stylePreference: payload.stylePreference,
+        maxSteps: payload.maxSteps
+      },
+      { signal }
+    );
+    return {
+      status: result.stoppedBy === "error" ? 500 : 200,
+      response: { success: result.stoppedBy !== "error", data: result }
+    };
+  }
+  if (mode === "plan") {
+    if (!payload.prompt || typeof payload.prompt !== "string") {
+      return {
+        status: 400,
+        response: {
+          success: false,
+          error: {
+            code: "INVALID_PROMPT",
+            message: '"prompt" is required for planning mode'
+          }
+        }
+      };
+    }
+    const result = await engine.planPage(
+      {
+        prompt: payload.prompt,
+        stylePreference: payload.stylePreference,
+        tone: payload.tone,
+        locale: payload.locale,
+        sectionCount: payload.sectionCount,
+        conversationHistory: payload.conversationHistory ?? payload.messages
+      },
+      { 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'`
+        message: `Unsupported mode: ${String(mode)}. Supported modes: 'full-page', 'section', 'refactor', 'chat', 'agent', 'plan'`
       }
     }
   };
 }
+function validateAgentPayload(payload, agent) {
+  if (!agent) {
+    return {
+      status: 501,
+      response: {
+        success: false,
+        error: {
+          code: "AGENT_NOT_CONFIGURED",
+          message: "Agent mode is not enabled on this endpoint. Pass a KubuildAiAgent to createAiHandler to enable it."
+        }
+      }
+    };
+  }
+  if (!payload.messages || !Array.isArray(payload.messages) || payload.messages.length === 0) {
+    return {
+      status: 400,
+      response: {
+        success: false,
+        error: {
+          code: "INVALID_AGENT_PARAMS",
+          message: '"messages" array is required and must not be empty for agent mode'
+        }
+      }
+    };
+  }
+  if (!payload.document || !payload.document.document) {
+    return {
+      status: 400,
+      response: {
+        success: false,
+        error: {
+          code: "INVALID_AGENT_PARAMS",
+          message: '"document" (the current PageDocument) is required for agent mode'
+        }
+      }
+    };
+  }
+  return null;
+}
+function sseResponse(events, errorCode) {
+  const encoder = new TextEncoder();
+  const readable = new ReadableStream({
+    async start(controller) {
+      try {
+        for await (const event of events) {
+          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: errorCode, 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"
+    }
+  });
+}
 function createAiHandler(engine, options) {
   return async (request) => {
     try {
@@ -728,6 +2000,28 @@ function createAiHandler(engine, options) {
       const body = await request.json().catch(() => null);
       if (body && typeof body === "object" && body.stream === true) {
         const mode = body.mode || "full-page";
+        if (mode === "agent") {
+          const validationError = validateAgentPayload(body, options?.agent);
+          if (validationError) {
+            return new Response(JSON.stringify(validationError.response), {
+              status: validationError.status,
+              headers: { "Content-Type": "application/json" }
+            });
+          }
+          return sseResponse(
+            options.agent.run(
+              {
+                messages: body.messages,
+                document: body.document,
+                selectedNodeId: body.selectedNodeId,
+                stylePreference: body.stylePreference,
+                maxSteps: body.maxSteps
+              },
+              { signal: request.signal }
+            ),
+            "AGENT_STREAM_ERROR"
+          );
+        }
         if (mode === "chat") {
           if (!body.messages || !Array.isArray(body.messages) || body.messages.length === 0) {
             return new Response(
@@ -744,48 +2038,17 @@ function createAiHandler(engine, options) {
               }
             );
           }
-          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"
-            }
-          });
+          return sseResponse(
+            engine.chatStream(
+              {
+                messages: body.messages,
+                currentDocument: body.currentDocument,
+                selectedNodeId: body.selectedNodeId
+              },
+              { signal: request.signal }
+            ),
+            "CHAT_STREAM_ERROR"
+          );
         }
         if (!body.prompt || typeof body.prompt !== "string") {
           return new Response(
@@ -802,55 +2065,28 @@ data: ${JSON.stringify({ type: "error", error: { code: "CHAT_STREAM_ERROR", mess
             }
           );
         }
-        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"
-          }
-        });
+        return sseResponse(
+          engine.streamPage(
+            {
+              prompt: body.prompt,
+              stylePreference: body.stylePreference,
+              tone: body.tone,
+              locale: body.locale,
+              metadata: body.metadata,
+              conversationHistory: body.conversationHistory ?? body.messages,
+              sectionCount: body.sectionCount,
+              plan: body.plan
+            },
+            { signal: request.signal }
+          ),
+          "STREAM_ERROR"
+        );
       }
       const { status, response } = await processAiRequest(
         engine,
         body,
-        request.signal
+        request.signal,
+        options?.agent
       );
       return new Response(JSON.stringify(response), {
         status,
@@ -882,9 +2118,19 @@ export {
   AnthropicAdapter,
   CustomHttpAdapter,
   GeminiAdapter,
+  KubuildAiAgent,
   KubuildAiEngine,
   OpenAiAdapter,
+  READ_TOOLS,
+  WRITE_TOOLS,
+  checkComponentType,
+  checkDocumentSecurity,
+  checkNesting,
   createAiHandler,
-  processAiRequest
+  createDocumentTools,
+  normalizeIncomingNode,
+  processAiRequest,
+  suggestNodeIds,
+  toToolDefinitions
 };
 //# sourceMappingURL=index.js.map