@kubuild/ai 0.3.1 → 0.5.0

package/dist/server/index.cjs

@@ -23,16 +23,162 @@ __export(server_exports, {
   AnthropicAdapter: () => AnthropicAdapter,
   CustomHttpAdapter: () => CustomHttpAdapter,
   GeminiAdapter: () => GeminiAdapter,
+  KubuildAiAgent: () => KubuildAiAgent,
   KubuildAiEngine: () => KubuildAiEngine,
   OpenAiAdapter: () => OpenAiAdapter,
+  READ_TOOLS: () => READ_TOOLS,
+  WRITE_TOOLS: () => WRITE_TOOLS,
+  checkComponentType: () => checkComponentType,
+  checkDocumentSecurity: () => checkDocumentSecurity,
+  checkNesting: () => checkNesting,
   createAiHandler: () => createAiHandler,
-  processAiRequest: () => processAiRequest
+  createDocumentTools: () => createDocumentTools,
+  normalizeIncomingNode: () => normalizeIncomingNode,
+  processAiRequest: () => processAiRequest,
+  suggestNodeIds: () => suggestNodeIds,
+  toToolDefinitions: () => toToolDefinitions
 });
 module.exports = __toCommonJS(server_exports);
 
 // src/server/engine.ts
 var import_schema2 = require("@kubuild/schema");
 
+// src/core/document-outline.ts
+var LABEL_PROPS = ["text", "label", "title", "heading", "content", "placeholder", "alt", "src"];
+var DEFAULT_LABEL_MAX = 60;
+function truncate(value, max = DEFAULT_LABEL_MAX) {
+  const oneLine = value.replace(/\s+/g, " ").trim();
+  return oneLine.length > max ? `${oneLine.slice(0, max - 1)}\u2026` : oneLine;
+}
+function getNodeLabel(node, max = DEFAULT_LABEL_MAX) {
+  const props = node.props ?? {};
+  for (const key of LABEL_PROPS) {
+    const value = props[key];
+    if (typeof value === "string" && value.trim()) {
+      return truncate(value, max);
+    }
+  }
+  return "";
+}
+function isOnPathTo(node, targetId) {
+  if (node.id === targetId) return true;
+  return (node.children ?? []).some((child) => isOnPathTo(child, targetId));
+}
+function summarizeNodeTree(root, options = {}) {
+  const { maxDepth = 3, focusNodeId, maxNodes = 200 } = options;
+  const lines = [];
+  let emitted = 0;
+  let truncated = false;
+  const walk = (node, depth) => {
+    if (emitted >= maxNodes) {
+      truncated = true;
+      return;
+    }
+    const indent = "  ".repeat(depth);
+    const label = getNodeLabel(node);
+    const children = node.children ?? [];
+    const parts = [`${indent}- #${node.id} (${node.type})`];
+    if (label) parts.push(`"${label}"`);
+    if (children.length > 0) parts.push(`[${children.length} children]`);
+    if (focusNodeId && node.id === focusNodeId) parts.push("\u2190 SELECTED");
+    lines.push(parts.join(" "));
+    emitted++;
+    if (children.length === 0) return;
+    const onFocusPath = Boolean(focusNodeId) && isOnPathTo(node, focusNodeId);
+    if (depth + 1 > maxDepth && !onFocusPath) {
+      lines.push(`${indent}  (+${countDescendants(node)} nested nodes \u2014 use read_node to expand)`);
+      return;
+    }
+    for (const child of children) {
+      walk(child, depth + 1);
+    }
+  };
+  walk(root, 0);
+  if (truncated) {
+    lines.push(`  (outline truncated at ${maxNodes} nodes \u2014 use find_nodes to locate specifics)`);
+  }
+  return lines.join("\n");
+}
+function countDescendants(node) {
+  return (node.children ?? []).reduce((total, child) => total + 1 + countDescendants(child), 0);
+}
+function summarizeDocument(document, options = {}) {
+  const header = [
+    `Title: ${document.metadata?.title || "Untitled Page"}`,
+    `Description: ${document.metadata?.description || "N/A"}`
+  ].join("\n");
+  return `${header}
+
+Page outline:
+${summarizeNodeTree(document.document, options)}`;
+}
+function buildSelectionContext(root, nodeId) {
+  const ancestors = [];
+  const walk = (node, parent, index) => {
+    if (node.id === nodeId) {
+      return {
+        node,
+        ancestors: [...ancestors],
+        siblings: parent ? parent.children ?? [] : [node],
+        index,
+        parentId: parent?.id ?? null
+      };
+    }
+    ancestors.push(node);
+    const children = node.children ?? [];
+    for (let i = 0; i < children.length; i++) {
+      const found = walk(children[i], node, i);
+      if (found) return found;
+    }
+    ancestors.pop();
+    return null;
+  };
+  return walk(root, null, 0);
+}
+function pruneNodeForPrompt(node, maxDepth = 2, depth = 0) {
+  const children = node.children ?? [];
+  if (children.length === 0) return node;
+  if (depth >= maxDepth) {
+    return {
+      ...node,
+      children: [
+        {
+          id: `${node.id}__collapsed`,
+          type: "__collapsed__",
+          props: {
+            note: `${countDescendants(node)} nested nodes omitted \u2014 call read_node on #${node.id} with includeChildren to expand`
+          }
+        }
+      ]
+    };
+  }
+  return {
+    ...node,
+    children: children.map((child) => pruneNodeForPrompt(child, maxDepth, depth + 1))
+  };
+}
+function formatSelectionContext(context) {
+  const path = context.ancestors.map((a) => `#${a.id}(${a.type})`).join(" > ");
+  const siblings = context.siblings.map((sibling, i) => {
+    const marker = sibling.id === context.node.id ? " \u2190 selected" : "";
+    const label = getNodeLabel(sibling);
+    return `  [${i}] #${sibling.id} (${sibling.type})${label ? ` "${label}"` : ""}${marker}`;
+  }).join("\n");
+  return [
+    "### Currently Selected Component",
+    `Node: #${context.node.id} (${context.node.type})`,
+    `Parent: ${context.parentId ? `#${context.parentId}` : "(root)"} \u2014 position ${context.index}`,
+    path ? `Path: ${path}` : "",
+    "Full node JSON:",
+    "```json",
+    JSON.stringify(pruneNodeForPrompt(context.node), null, 2),
+    "```",
+    "Siblings:",
+    siblings,
+    'When the user says "this", "ini", "komponen ini" or similar, they mean the selected node above.'
+  ].filter(Boolean).join("\n");
+}
+
 // src/core/prompt-compiler.ts
 function compileComponentCatalog(registry) {
   if (!registry) return [];
@@ -214,6 +360,100 @@ function buildJsonSchemaForMode(mode) {
   }
   return nodeSchema;
 }
+function formatComponentCatalog(catalog) {
+  return 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");
+}
+var AGENT_INSTRUCTIONS = `You are the KUBUILD page-editing agent. You edit an existing page by calling tools \u2014 you never output page JSON directly.
+
+### HOW YOU WORK
+1. The page outline below is your map. It shows every node's id, type and label, but not its props or styles.
+2. To see a node's actual props/styles, call read_node. To locate nodes by type or text, call find_nodes. Never guess a node id \u2014 every id you pass must come from the outline or from a tool result.
+3. Make the change with the smallest tool that expresses it, then stop and summarize what you changed, in the user's language.
+
+### SURGICAL EDIT RULE (the most important rule)
+Change only what the user asked for.
+- Changing text/label/href/src -> update_node_props on that one node.
+- Changing color/spacing/size/alignment -> update_node_styles on that one node.
+- Adding something new -> insert_component (a single element) or insert_section (a whole new section).
+- replace_node is a last resort, only when a node's children genuinely must be restructured. Never use it to change a prop or a style.
+- Never rebuild a section, and never touch nodes the user did not ask about. If an instruction is ambiguous about scope, edit the narrowest node that satisfies it and say so in your summary.
+
+### DESTRUCTIVE ACTIONS
+delete_node and replace_node destroy user content. Only call them when the user asked unambiguously (e.g. "hapus section harga"). If the request is broad or vague ("bersihkan halaman ini", "hapus yang tidak perlu"), do not call them \u2014 ask the user which nodes to remove instead.
+
+### STYLING RULES
+- styles values are CSS primitives (strings/numbers). Use breakpoint ('base' | 'desktop' | 'tablet' | 'mobile') for normal styling and state (':hover', ':focus', ':active') for interactive states. Never nest a pseudo-class inside a breakpoint layer.
+- Only use component types that exist in the catalog below, and respect acceptsChildren/allowedChildren.
+- Never emit scripts, javascript: URIs, or event-handler attributes.
+
+### WHEN A TOOL FAILS
+A tool result with "ok": false means your input was wrong (unknown node id, invalid type, disallowed nesting). Read the error, fix your arguments, and retry \u2014 do not repeat the identical call, and do not give up silently.`;
+function buildAgentSystemPrompt(options) {
+  const { catalog, document, selectedNodeId, prefix, stylePreference, additionalContext } = options;
+  const selection = selectedNodeId ? buildSelectionContext(document.document, selectedNodeId) : null;
+  const sections = [];
+  if (prefix) sections.push(prefix);
+  sections.push(AGENT_INSTRUCTIONS);
+  sections.push(
+    `### REGISTERED COMPONENT CATALOG
+${formatComponentCatalog(catalog) || "(Standard core components: page, section, container, columns, heading, paragraph, text, button, input, textarea, select, image, video, icon, badge, code-block)"}`
+  );
+  sections.push(`### CURRENT PAGE
+${summarizeDocument(document, { focusNodeId: selectedNodeId })}`);
+  if (selection) {
+    sections.push(formatSelectionContext(selection));
+  } else if (selectedNodeId) {
+    sections.push(
+      `### Selection
+The editor reported node "${selectedNodeId}" as selected, but it is not present in the current page. Ignore it and ask the user what to target.`
+    );
+  } else {
+    sections.push(
+      '### Selection\nNo component is selected on the canvas. If the user says "this", ask which component they mean instead of guessing.'
+    );
+  }
+  if (stylePreference) {
+    sections.push(
+      `### Style Preference
+"${stylePreference}" \u2014 follow this aesthetic for anything you create or restyle.`
+    );
+  }
+  if (additionalContext) {
+    sections.push(`### Additional Context
+${additionalContext}`);
+  }
+  return sections.join("\n\n");
+}
+
+// src/core/messages.ts
+function getMessageText(message) {
+  if (typeof message.content === "string") return message.content;
+  return message.content.filter((block) => block.type === "text").map((block) => block.text).join("\n");
+}
+function getToolUseBlocks(message) {
+  if (typeof message.content === "string") return [];
+  return message.content.filter((b) => b.type === "tool_use");
+}
+function getToolResultBlocks(message) {
+  if (typeof message.content === "string") return [];
+  return message.content.filter((b) => b.type === "tool_result");
+}
 
 // src/core/normalizer.ts
 var import_schema = require("@kubuild/schema");
@@ -495,6 +735,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,
@@ -633,18 +880,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):
 {
@@ -666,44 +913,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 = import_schema2.DocumentMetadataSchema.parse({
         title: plan.title || "AI Generated Page",
@@ -863,7 +1179,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 };
   }
   /**
@@ -1004,105 +1320,1154 @@ Currently Selected Component Node ID: "${request.selectedNodeId}"`;
   }
 };
 
-// src/server/handler.ts
-async function processAiRequest(engine, body, signal) {
-  if (!body || typeof body !== "object") {
+// src/server/tools/helpers.ts
+var import_schema3 = require("@kubuild/schema");
+var import_core2 = require("@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((0, import_core2.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 = (0, import_core2.findNodeById)(document.document, nodeId);
+  if (!node) {
     return {
-      status: 400,
-      response: {
-        success: false,
-        error: {
-          code: "BAD_REQUEST",
-          message: "Request body must be a valid JSON object"
+      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 = (0, import_core2.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 = (0, import_core2.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 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 }
-    );
+  const parsed = import_schema3.NodeSchema.safeParse(normalized);
+  if (!parsed.success) {
     return {
-      status: result.success ? 200 : 500,
-      response: result
+      error: parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")
     };
   }
-  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'
-          }
+  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."
         }
-      };
+      }
     }
-    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
-    };
+  },
+  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 })
+    });
   }
-  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'
-          }
+};
+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."
         }
-      };
-    }
-    const result = await engine.refactorNode(
-      {
-        node: payload.node,
-        instruction: payload.instruction,
-        stylePreference: payload.stylePreference
       },
-      { signal }
-    );
-    return {
-      status: result.success ? 200 : 500,
-      response: result
+      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."
+      }
+    );
   }
-  if (mode === "chat") {
-    if (!payload.messages || !Array.isArray(payload.messages) || payload.messages.length === 0) {
+};
+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
+var import_core3 = require("@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",
+      () => (0, import_core3.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 = (0, import_core3.findNodeById)(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",
+      () => (0, import_core3.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",
+      () => (0, import_core3.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",
+      () => (0, import_core3.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",
+      () => (0, import_core3.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",
+      () => (0, import_core3.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", () => (0, import_core3.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",
+      () => (0, import_core3.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, agent) {
+  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,
+        conversationHistory: payload.conversationHistory ?? payload.messages,
+        sectionCount: payload.sectionCount,
+        plan: payload.plan
+      },
+      { 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: {
@@ -1127,17 +2492,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 {
@@ -1168,6 +2658,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(
@@ -1184,48 +2696,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(
@@ -1242,55 +2723,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,
@@ -1368,7 +2822,7 @@ var GeminiAdapter = class {
     const { userPrompt, messages: chatMessages } = params;
     return chatMessages && chatMessages.length > 0 ? chatMessages.map((m) => ({
       role: m.role === "assistant" ? "model" : "user",
-      parts: [{ text: m.content }]
+      parts: [{ text: getMessageText(m) }]
     })) : [
       {
         role: "user",
@@ -1480,8 +2934,47 @@ var GeminiAdapter = class {
 };
 
 // src/server/adapters/openai.ts
+function mapStopReason(finishReason) {
+  switch (finishReason) {
+    case "stop":
+      return "stop";
+    case "tool_calls":
+    case "function_call":
+      return "tool_calls";
+    case "length":
+      return "length";
+    case "content_filter":
+      return "content_filter";
+    default:
+      return "unknown";
+  }
+}
+function parseToolCalls(raw) {
+  if (!Array.isArray(raw) || raw.length === 0) return [];
+  return raw.filter((call) => call?.function?.name).map((call, index) => {
+    let input = {};
+    const argsText = call.function?.arguments;
+    if (argsText && argsText.trim()) {
+      try {
+        const parsed = JSON.parse(argsText);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+          input = parsed;
+        }
+      } catch {
+        input = {};
+      }
+    }
+    return {
+      type: "tool_use",
+      id: call.id || `call_${index}`,
+      name: call.function.name,
+      input
+    };
+  });
+}
 var OpenAiAdapter = class {
   name = "openai";
+  supportsTools = true;
   apiKey;
   model;
   temperature;
@@ -1497,30 +2990,95 @@ var OpenAiAdapter = class {
     this.baseUrl = (options.baseUrl || "https://api.openai.com/v1").replace(/\/+$/, "");
     this.customHeaders = options.headers;
   }
+  /**
+   * Expands one `AiChatMessage` into the one-or-more OpenAI messages it corresponds to
+   * (STORA-530).
+   *
+   * The block model is Anthropic-shaped — tool results ride along inside a `user` message —
+   * while OpenAI wants each result as its own `role: 'tool'` message keyed by
+   * `tool_call_id`. That fan-out happens here so the rest of the stack stays
+   * provider-agnostic.
+   */
+  mapMessage(message) {
+    const toolUses = getToolUseBlocks(message);
+    const toolResults = getToolResultBlocks(message);
+    const text = getMessageText(message);
+    if (toolResults.length > 0) {
+      const results = toolResults.map((block) => ({
+        role: "tool",
+        content: block.content,
+        tool_call_id: block.toolUseId
+      }));
+      if (text.trim()) {
+        results.push({ role: "user", content: text });
+      }
+      return results;
+    }
+    if (toolUses.length > 0) {
+      return [
+        {
+          role: "assistant",
+          content: text.trim() ? text : null,
+          tool_calls: toolUses.map((block) => ({
+            id: block.id,
+            type: "function",
+            function: {
+              name: block.name,
+              arguments: JSON.stringify(block.input ?? {})
+            }
+          }))
+        }
+      ];
+    }
+    return [{ role: message.role, content: text }];
+  }
   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 }))
-    ] : [
+    if (chatMessages && chatMessages.length > 0) {
+      return [
+        { role: "system", content: systemPrompt },
+        ...chatMessages.flatMap((m) => this.mapMessage(m))
+      ];
+    }
+    return [
       { 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;
+  /**
+   * Shared request body builder for `generate`/`generateStream` — notably the
+   * `response_format` decision, which must never fire in tool mode: OpenAI rejects
+   * `json_object` combined with `tools`, and a tool-calling turn's text output is a
+   * natural-language summary, not JSON.
+   */
+  buildBody(params) {
+    const { systemPrompt, jsonSchema, messages: chatMessages, tools, toolChoice } = params;
     const body = {
       model: this.model,
-      temperature: this.temperature,
-      messages
+      temperature: params.temperature ?? this.temperature,
+      messages: this.buildMessages(params)
     };
-    if (params.jsonSchema || !chatMessages && (systemPrompt.includes("JSON") || systemPrompt.includes("json"))) {
+    if (tools && tools.length > 0) {
+      body.tools = tools.map((tool) => ({
+        type: "function",
+        function: {
+          name: tool.name,
+          description: tool.description,
+          parameters: tool.inputSchema
+        }
+      }));
+      if (toolChoice) {
+        body.tool_choice = typeof toolChoice === "string" ? toolChoice : { type: "function", function: { name: toolChoice.name } };
+      }
+      return body;
+    }
+    if (jsonSchema || !chatMessages && (systemPrompt.includes("JSON") || systemPrompt.includes("json"))) {
       body.response_format = { type: "json_object" };
     }
-    const res = await fetch(url, {
+    return body;
+  }
+  async post(body, signal) {
+    const res = await fetch(`${this.baseUrl}/chat/completions`, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
@@ -1536,13 +3094,21 @@ var OpenAiAdapter = class {
         `OpenAI API error [${res.status} ${res.statusText}]: ${errText || "Unknown error"}`
       );
     }
+    return res;
+  }
+  async generate(params) {
+    const res = await this.post(this.buildBody(params), params.signal);
     const data = await res.json();
-    const content = data.choices?.[0]?.message?.content;
-    if (!content) {
+    const choice = data.choices?.[0];
+    const content = choice?.message?.content;
+    const toolCalls = parseToolCalls(choice?.message?.tool_calls);
+    if (!content && toolCalls.length === 0) {
       throw new Error("OpenAI returned an empty message content");
     }
     return {
-      text: content,
+      text: content || "",
+      toolCalls: toolCalls.length > 0 ? toolCalls : void 0,
+      stopReason: mapStopReason(choice?.finish_reason),
       usage: data.usage ? {
         promptTokens: data.usage.prompt_tokens,
         completionTokens: data.usage.completion_tokens
@@ -1553,38 +3119,23 @@ var OpenAiAdapter = class {
    * 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.
+   *
+   * Tool calls arrive fragmented too (STORA-530): `delta.tool_calls[].function.arguments`
+   * is delivered as a character stream across many chunks, keyed by array `index`. They're
+   * accumulated per index and parsed only once the stream ends — parsing a partial
+   * arguments string would always fail. Tool call deltas are never `yield`ed as text,
+   * since they aren't part of the assistant's visible message.
    */
   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"}`
-      );
-    }
+    const res = await this.post({ ...this.buildBody(params), stream: true }, signal);
     if (!res.body) {
       throw new Error("OpenAI streaming response has no readable body");
     }
     let text = "";
     let usage;
+    let finishReason;
+    const toolCallAccumulator = /* @__PURE__ */ new Map();
     for await (const raw of readSseDataLines(res.body, signal)) {
       if (raw === "[DONE]") break;
       let parsed;
@@ -1593,11 +3144,23 @@ var OpenAiAdapter = class {
       } catch {
         continue;
       }
-      const delta = parsed.choices?.[0]?.delta?.content;
+      const choice = parsed.choices?.[0];
+      const delta = choice?.delta?.content;
       if (typeof delta === "string" && delta.length > 0) {
         text += delta;
         yield delta;
       }
+      for (const call of choice?.delta?.tool_calls ?? []) {
+        const index = typeof call.index === "number" ? call.index : 0;
+        const entry = toolCallAccumulator.get(index) ?? { id: "", name: "", arguments: "" };
+        if (call.id) entry.id = call.id;
+        if (call.function?.name) entry.name = call.function.name;
+        if (call.function?.arguments) entry.arguments += call.function.arguments;
+        toolCallAccumulator.set(index, entry);
+      }
+      if (choice?.finish_reason) {
+        finishReason = choice.finish_reason;
+      }
       if (parsed.usage) {
         usage = {
           promptTokens: parsed.usage.prompt_tokens,
@@ -1605,7 +3168,19 @@ var OpenAiAdapter = class {
         };
       }
     }
-    return { text, usage };
+    const toolCalls = parseToolCalls(
+      Array.from(toolCallAccumulator.entries()).sort(([a], [b]) => a - b).map(([, entry]) => ({
+        id: entry.id,
+        type: "function",
+        function: { name: entry.name, arguments: entry.arguments }
+      }))
+    );
+    return {
+      text,
+      toolCalls: toolCalls.length > 0 ? toolCalls : void 0,
+      stopReason: mapStopReason(finishReason),
+      usage
+    };
   }
 };
 
@@ -1633,7 +3208,7 @@ var AnthropicAdapter = class {
   }
   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 })) : [
+    return chatMessages && chatMessages.length > 0 ? chatMessages.filter((m) => m.role === "user" || m.role === "assistant").map((m) => ({ role: m.role, content: getMessageText(m) })) : [
       {
         role: "user",
         content: userPrompt
@@ -1765,7 +3340,7 @@ var CustomHttpAdapter = class {
     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 }))
+        ...params.messages.map((m) => ({ role: m.role, content: getMessageText(m) }))
       ] : [
         { role: "system", content: params.systemPrompt },
         { role: "user", content: params.userPrompt }
@@ -1816,9 +3391,19 @@ var CustomHttpAdapter = class {
   AnthropicAdapter,
   CustomHttpAdapter,
   GeminiAdapter,
+  KubuildAiAgent,
   KubuildAiEngine,
   OpenAiAdapter,
+  READ_TOOLS,
+  WRITE_TOOLS,
+  checkComponentType,
+  checkDocumentSecurity,
+  checkNesting,
   createAiHandler,
-  processAiRequest
+  createDocumentTools,
+  normalizeIncomingNode,
+  processAiRequest,
+  suggestNodeIds,
+  toToolDefinitions
 });
 //# sourceMappingURL=index.cjs.map