@kubuild/ai 0.6.0 → 0.7.0

package/dist/server/index.js

@@ -1,4 +1,5 @@
 import {
+  appendClientInstructions,
   buildAgentSystemPrompt,
   buildJsonSchemaForMode,
   buildSelectionContext,
@@ -6,13 +7,14 @@ import {
   compileComponentCatalog,
   extractJsonFromResponse,
   getNodeLabel,
+  joinInstructions,
   normalizeAndValidatePageDocument,
   normalizeAndValidateRefactoredNode,
   normalizeAndValidateSectionNode,
   normalizeNodeTree,
   pruneNodeForPrompt,
   summarizeNodeTree
-} from "../chunk-YETTTWHI.js";
+} from "../chunk-CCV6S4YN.js";
 import {
   AnthropicAdapter,
   CustomHttpAdapter,
@@ -24,7 +26,40 @@ import {
 } from "../chunk-ILLNRABB.js";
 
 // src/server/engine.ts
-import { DocumentMetadataSchema } from "@kubuild/schema";
+import { DocumentMetadataSchema, CURRENT_SCHEMA_VERSION } from "@kubuild/schema";
+function describeSectionCount(sectionCount) {
+  if (typeof sectionCount === "number" && Number.isFinite(sectionCount) && sectionCount > 0) {
+    return `exactly ${Math.floor(sectionCount)} cohesive sections`;
+  }
+  if (sectionCount && typeof sectionCount === "object" && (sectionCount.min || sectionCount.max)) {
+    const min = sectionCount.min ?? 3;
+    const max = sectionCount.max ?? 8;
+    return `between ${min} and ${max} cohesive sections`;
+  }
+  return null;
+}
+function hasPlannedSections(plan) {
+  return !!plan && Array.isArray(plan.sections) && plan.sections.length > 0;
+}
+function buildFallbackPlan(prompt) {
+  return {
+    title: "AI Generated Page",
+    description: "Generated by KUBUILD AI",
+    sections: [
+      { type: "hero", title: "Hero Banner", prompt: `Hero section for: ${prompt}` },
+      { type: "features", title: "Key Features", prompt: `Features grid for: ${prompt}` },
+      {
+        type: "testimonials",
+        title: "Testimonials",
+        prompt: `Social proof and customer reviews for: ${prompt}`
+      },
+      { type: "cta", title: "Call To Action", prompt: `Call to action section for: ${prompt}` },
+      { type: "footer", title: "Footer", prompt: `Footer navigation and copyright for: ${prompt}` }
+    ],
+    usedFallback: true
+  };
+}
+var PLAN_FALLBACK_MESSAGE = "The AI response could not be parsed as a page plan, so a generic default plan was used instead.";
 var KubuildAiEngine = class {
   options;
   catalog;
@@ -50,20 +85,31 @@ var KubuildAiEngine = class {
     }
   }
   async generatePage(request, context) {
+    if (hasPlannedSections(request.plan)) {
+      return this.generatePageFromPlan(request, context);
+    }
     let rawText = "";
     try {
       this.log("info", `Generating full page for prompt: "${request.prompt}"`);
-      const systemPrompt = buildSystemPrompt({
-        catalog: this.catalog,
-        mode: "full-page",
-        prefix: this.options.systemPromptPrefix,
-        stylePreference: request.stylePreference
-      });
+      const systemPrompt = appendClientInstructions(
+        buildSystemPrompt({
+          catalog: this.catalog,
+          mode: "full-page",
+          prefix: this.options.systemPromptPrefix,
+          stylePreference: request.stylePreference
+        }),
+        request.instructions
+      );
       let userPrompt = `User Request: ${request.prompt}`;
       if (request.tone) userPrompt += `
 Tone: ${request.tone}`;
       if (request.locale) userPrompt += `
 Language/Locale: ${request.locale}`;
+      const sectionCountPhrase = describeSectionCount(request.sectionCount);
+      if (sectionCountPhrase) {
+        userPrompt += `
+Section Count: the page root must contain ${sectionCountPhrase} as its direct children.`;
+      }
       if (request.conversationHistory && request.conversationHistory.length > 0) {
         const chatContext = request.conversationHistory.map((m) => `${m.role.toUpperCase()}: ${getMessageText(m)}`).join("\n");
         userPrompt += `
@@ -114,15 +160,42 @@ ${chatContext}`;
       };
     }
   }
+  /**
+   * Non-streaming counterpart of `streamPage` for a pre-approved plan: drains the same
+   * progressive pipeline and returns the assembled document, so both paths produce the
+   * same sections for the same plan.
+   */
+  async generatePageFromPlan(request, context) {
+    let document = null;
+    let error = null;
+    for await (const event of this.streamPage(request, context)) {
+      if (event.type === "complete") document = event.document;
+      if (event.type === "error") error = event.error;
+    }
+    if (document) {
+      return { success: true, data: document };
+    }
+    return {
+      success: false,
+      error: {
+        code: "GENERATION_ERROR",
+        message: error?.message ?? "Page generation from the approved plan produced no document.",
+        details: error ? { streamCode: error.code } : void 0
+      }
+    };
+  }
   async generateSection(request, context) {
     let rawText = "";
     try {
-      const systemPrompt = buildSystemPrompt({
-        catalog: this.catalog,
-        mode: "section",
-        prefix: this.options.systemPromptPrefix,
-        stylePreference: request.stylePreference
-      });
+      const systemPrompt = appendClientInstructions(
+        buildSystemPrompt({
+          catalog: this.catalog,
+          mode: "section",
+          prefix: this.options.systemPromptPrefix,
+          stylePreference: request.stylePreference
+        }),
+        request.instructions
+      );
       let userPrompt = `Generate a single section node for: ${request.prompt}`;
       if (request.targetSectionType) {
         userPrompt += `
@@ -167,12 +240,15 @@ Surrounding Page Context: ${request.parentContext}`;
   async refactorNode(request, context) {
     let rawText = "";
     try {
-      const systemPrompt = buildSystemPrompt({
-        catalog: this.catalog,
-        mode: "refactor",
-        prefix: this.options.systemPromptPrefix,
-        stylePreference: request.stylePreference
-      });
+      const systemPrompt = appendClientInstructions(
+        buildSystemPrompt({
+          catalog: this.catalog,
+          mode: "refactor",
+          prefix: this.options.systemPromptPrefix,
+          stylePreference: request.stylePreference
+        }),
+        request.instructions
+      );
       const userPrompt = `Instruction: ${request.instruction}
 
 Current Node:
@@ -210,16 +286,8 @@ ${JSON.stringify(request.node, null, 2)}`;
     }
   }
   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 sectionCountPhrase = describeSectionCount(request.sectionCount);
+    const sectionGuidance = sectionCountPhrase ? `Plan ${sectionCountPhrase} that fulfill the request.` : "Plan between 4 to 6 cohesive, essential sections (e.g., hero, features, testimonials, pricing, cta, footer) that fulfill the request thoroughly. 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):
@@ -260,46 +328,59 @@ Locale: ${request.locale}`;
 Prior Conversation Discussion Context:
 ${chatContext}`;
     }
-    return { systemPrompt: planSystemPrompt, userPrompt: planUserPrompt };
+    return {
+      systemPrompt: appendClientInstructions(planSystemPrompt, request.instructions),
+      userPrompt: planUserPrompt
+    };
   }
   async planPage(request, context) {
-    let rawText = "";
+    const { systemPrompt, userPrompt } = this.buildPlanPrompts(request);
+    this.log("info", `Planning website layout for: "${request.prompt}"`);
+    let planResult;
     try {
-      const { systemPrompt, userPrompt } = this.buildPlanPrompts(request);
-      this.log("info", `Planning website layout for: "${request.prompt}"`);
-      const planResult = await this.options.adapter.generate({
+      planResult = await this.options.adapter.generate({
         systemPrompt,
         userPrompt,
         signal: context?.signal
       });
-      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}` }
-        ]
+      this.log("error", `Planning failed: ${message}`);
+      return {
+        success: false,
+        error: { code: "PLAN_ERROR", message }
       };
+    }
+    const rawText = planResult.text;
+    let plan = null;
+    let parseError = "";
+    try {
+      const parsed = extractJsonFromResponse(rawText);
+      if (hasPlannedSections(parsed)) {
+        plan = parsed;
+      } else {
+        parseError = 'Plan JSON has no non-empty "sections" array';
+      }
+    } catch (err) {
+      parseError = err instanceof Error ? err.message : String(err);
+    }
+    if (plan) {
       return {
         success: true,
-        data: fallbackPlan,
-        rawModelResponse: rawText || void 0
+        data: plan,
+        usage: planResult.usage,
+        rawModelResponse: rawText
       };
     }
+    this.log("warn", "Failed to parse plan JSON, using fallback plan", parseError);
+    return {
+      success: true,
+      data: buildFallbackPlan(request.prompt),
+      usedFallback: true,
+      warnings: [{ code: "PLAN_FALLBACK", message: PLAN_FALLBACK_MESSAGE, details: parseError }],
+      usage: planResult.usage,
+      rawModelResponse: rawText || void 0
+    };
   }
   /**
    * Progressive Section Streaming Generator.
@@ -313,7 +394,7 @@ ${chatContext}`;
         message: "Analyzing requirements and planning page sections..."
       };
       let plan;
-      if (request.plan && Array.isArray(request.plan.sections) && request.plan.sections.length > 0) {
+      if (hasPlannedSections(request.plan)) {
         plan = request.plan;
         this.log("info", `[SSE] Using approved pre-planned structure with ${plan.sections?.length ?? 0} sections`);
       } else {
@@ -325,31 +406,21 @@ ${chatContext}`;
           signal: context?.signal
         });
         this.log("debug", "[SSE] Raw plan response from model", planResult.text);
+        let parsedPlan = null;
         try {
-          plan = extractJsonFromResponse(planResult.text);
-          this.log("debug", "[SSE] Parsed plan successfully", plan);
+          parsedPlan = extractJsonFromResponse(planResult.text);
+          this.log("debug", "[SSE] Parsed plan successfully", parsedPlan);
         } 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}` }
-            ]
-          };
+        }
+        if (hasPlannedSections(parsedPlan)) {
+          plan = parsedPlan;
+        } else {
+          plan = buildFallbackPlan(request.prompt);
+          yield { type: "status", message: PLAN_FALLBACK_MESSAGE };
         }
       }
-      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: "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 sectionsToGenerate = hasPlannedSections(plan) ? plan.sections : buildFallbackPlan(request.prompt).sections;
       const metadata = DocumentMetadataSchema.parse({
         title: plan.title || "AI Generated Page",
         description: plan.description || "Generated by KUBUILD AI",
@@ -406,6 +477,7 @@ ${chatContext}`;
           {
             prompt: plannedSec.prompt,
             stylePreference: request.stylePreference,
+            instructions: request.instructions,
             targetSectionType: plannedSec.type,
             parentContext: `Website: ${plan.title}. Previous sections: ${sectionsToGenerate.slice(0, i).map((s) => s.title).join(", ")}`
           },
@@ -440,7 +512,7 @@ ${chatContext}`;
       }
       const finalDocument = {
         schema: "stora.page",
-        version: "1.0.0",
+        version: CURRENT_SCHEMA_VERSION,
         metadata,
         document: {
           ...rootPageNode,
@@ -484,11 +556,6 @@ ${this.catalog.map((c) => `- **${c.type}** (${c.category}): ${c.label}${c.descri
       systemPrompt = `${this.options.systemPromptPrefix}
 
 ${systemPrompt}`;
-    }
-    if (request.systemPrompt) {
-      systemPrompt += `
-Additional Context:
-${request.systemPrompt}`;
     }
     if (request.currentDocument) {
       const doc = request.currentDocument;
@@ -507,6 +574,10 @@ ${sectionSummary || "(Canvas is currently empty)"}
       systemPrompt += `
 Currently Selected Component Node ID: "${request.selectedNodeId}"`;
     }
+    systemPrompt = appendClientInstructions(
+      systemPrompt,
+      joinInstructions(request.instructions, request.systemPrompt)
+    );
     const lastUserMsg = [...request.messages].reverse().find((m) => m.role === "user");
     const userPrompt = lastUserMsg ? getMessageText(lastUserMsg) || "Hello" : "Hello";
     return { systemPrompt, userPrompt };
@@ -695,7 +766,7 @@ function resolveNode(document, nodeId, toolName) {
   if (!node) {
     return {
       error: fail(
-        `${toolName}: node "${nodeId}" tidak ditemukan`,
+        `${toolName}: node "${nodeId}" not found`,
         `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) }
       )
@@ -789,7 +860,7 @@ var getPageOutline = {
   },
   execute(input, context) {
     const maxDepth = typeof input.maxDepth === "number" && input.maxDepth > 0 ? Math.floor(input.maxDepth) : 3;
-    return succeed("Membaca struktur halaman", {
+    return succeed("Read page outline", {
       outline: summarizeNodeTree(context.document.document, { maxDepth })
     });
   }
@@ -813,7 +884,7 @@ var readNode = {
   },
   execute(input, context) {
     const nodeId = readString(input, "nodeId");
-    if (!nodeId) return fail("read_node: nodeId kosong", 'Argument "nodeId" is required.');
+    if (!nodeId) return fail("read_node: nodeId missing", '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);
@@ -859,7 +930,7 @@ var findNodes = {
     const limit = typeof input.limit === "number" && input.limit > 0 ? Math.floor(input.limit) : 20;
     if (!type && !textContains) {
       return fail(
-        "find_nodes: filter kosong",
+        "find_nodes: empty filter",
         'Provide at least one of "type" or "textContains" \u2014 an unfiltered search would just return the whole outline.'
       );
     }
@@ -907,7 +978,7 @@ var listComponentTypes = {
   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})`, {
+    return succeed(`Viewed component catalog (${entries.length})`, {
       components: entries.map((spec) => ({
         type: spec.type,
         label: spec.label,
@@ -942,14 +1013,14 @@ function applyCommand(toolName, run) {
     return run();
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
-    return { error: fail(`${toolName} gagal`, message) };
+    return { error: fail(`${toolName} failed`, message) };
   }
 }
 function guardSecurity(toolName, document, context) {
   const violation = checkDocumentSecurity(document, context.securityLimits);
   if (!violation) return null;
   return fail(
-    `${toolName} ditolak (security)`,
+    `${toolName} rejected (security)`,
     `The resulting document failed the security check and was rejected: ${violation}`
   );
 }
@@ -976,11 +1047,11 @@ var updateNodeProps = {
   },
   execute(input, context) {
     const nodeId = readString(input, "nodeId");
-    if (!nodeId) return fail("update_node_props: nodeId kosong", 'Argument "nodeId" is required.');
+    if (!nodeId) return fail("update_node_props: nodeId missing", 'Argument "nodeId" is required.');
     const props = readPlainObject(input, "props");
     if (!props) {
       return fail(
-        "update_node_props: props tidak valid",
+        "update_node_props: invalid props",
         'Argument "props" must be a JSON object of prop names to values.'
       );
     }
@@ -997,7 +1068,7 @@ var updateNodeProps = {
     const op = { kind: "update-props", nodeId, props, merge };
     const updated = findNodeById2(applied.document.document, nodeId);
     return succeed(
-      `Ubah props ${describeNode(resolved.node)}`,
+      `Update props of ${describeNode(resolved.node)}`,
       { nodeId, props: updated?.props ?? props, changedKeys: Object.keys(props) },
       { op, document: applied.document }
     );
@@ -1035,11 +1106,11 @@ var updateNodeStyles = {
   },
   execute(input, context) {
     const nodeId = readString(input, "nodeId");
-    if (!nodeId) return fail("update_node_styles: nodeId kosong", 'Argument "nodeId" is required.');
+    if (!nodeId) return fail("update_node_styles: nodeId missing", 'Argument "nodeId" is required.');
     const styles = readPlainObject(input, "styles");
     if (!styles) {
       return fail(
-        "update_node_styles: styles tidak valid",
+        "update_node_styles: invalid styles",
         'Argument "styles" must be a JSON object of CSS properties with primitive values.'
       );
     }
@@ -1048,7 +1119,7 @@ var updateNodeStyles = {
     );
     if (nested) {
       return fail(
-        "update_node_styles: nilai bersarang",
+        "update_node_styles: nested value",
         `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.`
       );
     }
@@ -1056,13 +1127,13 @@ var updateNodeStyles = {
     const rawBreakpoint = readString(input, "breakpoint");
     if (rawState && rawBreakpoint) {
       return fail(
-        "update_node_styles: argumen bentrok",
+        "update_node_styles: conflicting arguments",
         '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",
+        "update_node_styles: unknown breakpoint",
         `Unknown breakpoint "${rawBreakpoint}". Valid values: ${BREAKPOINTS.join(", ")}.`
       );
     }
@@ -1081,7 +1152,7 @@ var updateNodeStyles = {
     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})`,
+      `Update styles of ${describeNode(resolved.node)} (${layer})`,
       { nodeId, layer, appliedStyles: styles },
       { op, document: applied.document }
     );
@@ -1120,16 +1191,16 @@ var insertComponent = {
     const type = readString(input, "type");
     if (!parentId || !type) {
       return fail(
-        "insert_component: argumen kurang",
+        "insert_component: missing arguments",
         'Arguments "parentId" and "type" are both required.'
       );
     }
     const typeError = checkComponentType(context.catalog, type);
-    if (typeError) return fail("insert_component: tipe tidak dikenal", typeError);
+    if (typeError) return fail("insert_component: unknown type", 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);
+    if (nestingError) return fail("insert_component: invalid nesting", nestingError);
     const normalized = normalizeIncomingNode(
       {
         type,
@@ -1140,7 +1211,7 @@ var insertComponent = {
       context.document
     );
     if ("error" in normalized) {
-      return fail("insert_component: node tidak valid", normalized.error);
+      return fail("insert_component: invalid node", normalized.error);
     }
     const index = readOptionalIndex(input, "index");
     const applied = applyCommand(
@@ -1152,7 +1223,7 @@ var insertComponent = {
     if (violation) return violation;
     const op = { kind: "insert-node", parentId, index, node: normalized.node };
     return succeed(
-      `Tambah ${describeNode(normalized.node)} ke #${parentId}`,
+      `Add ${describeNode(normalized.node)} to #${parentId}`,
       { nodeId: normalized.node.id, parentId, index: index ?? null },
       { op, document: applied.document }
     );
@@ -1180,10 +1251,10 @@ var insertSection = {
   },
   async execute(input, context) {
     const prompt = readString(input, "prompt");
-    if (!prompt) return fail("insert_section: prompt kosong", 'Argument "prompt" is required.');
+    if (!prompt) return fail("insert_section: prompt missing", 'Argument "prompt" is required.');
     if (!context.generateSection) {
       return fail(
-        "insert_section: tidak tersedia",
+        "insert_section: not available",
         "Section generation is not available in this deployment. Build the section with insert_component instead."
       );
     }
@@ -1197,13 +1268,13 @@ var insertSection = {
       });
     } catch (err) {
       return fail(
-        "insert_section gagal",
+        "insert_section failed",
         `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);
+      return fail("insert_section: invalid section", normalized.error);
     }
     const index = readOptionalIndex(input, "index");
     const applied = applyCommand(
@@ -1215,7 +1286,7 @@ var insertSection = {
     if (violation) return violation;
     const op = { kind: "insert-node", parentId: rootId, index, node: normalized.node };
     return succeed(
-      `Tambah section baru (#${normalized.node.id})`,
+      `Add new section (#${normalized.node.id})`,
       {
         nodeId: normalized.node.id,
         index: index ?? null,
@@ -1245,7 +1316,7 @@ var moveNodeTool = {
     const targetParentId = readString(input, "targetParentId");
     if (!nodeId || !targetParentId) {
       return fail(
-        "move_node: argumen kurang",
+        "move_node: missing arguments",
         'Arguments "nodeId" and "targetParentId" are both required.'
       );
     }
@@ -1254,7 +1325,7 @@ var moveNodeTool = {
     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);
+    if (nestingError) return fail("move_node: invalid nesting", nestingError);
     const index = readOptionalIndex(input, "index");
     const applied = applyCommand(
       "move_node",
@@ -1265,7 +1336,7 @@ var moveNodeTool = {
     if (violation) return violation;
     const op = { kind: "move-node", nodeId, targetParentId, index };
     return succeed(
-      `Pindah ${describeNode(resolved.node)} ke #${targetParentId}`,
+      `Move ${describeNode(resolved.node)} to #${targetParentId}`,
       { nodeId, targetParentId, index: index ?? null },
       { op, document: applied.document }
     );
@@ -1291,7 +1362,7 @@ var duplicateNodeTool = {
   },
   execute(input, context) {
     const nodeId = readString(input, "nodeId");
-    if (!nodeId) return fail("duplicate_node: nodeId kosong", 'Argument "nodeId" is required.');
+    if (!nodeId) return fail("duplicate_node: nodeId missing", '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;
@@ -1309,7 +1380,7 @@ var duplicateNodeTool = {
     if (violation) return violation;
     const op = { kind: "duplicate-node", nodeId, targetParentId, index };
     return succeed(
-      `Duplikat ${describeNode(resolved.node)}`,
+      `Duplicate ${describeNode(resolved.node)}`,
       { nodeId, targetParentId: targetParentId ?? null, index: index ?? null },
       { op, document: applied.document }
     );
@@ -1335,11 +1406,11 @@ var deleteNode = {
   },
   execute(input, context) {
     const nodeId = readString(input, "nodeId");
-    if (!nodeId) return fail("delete_node: nodeId kosong", 'Argument "nodeId" is required.');
+    if (!nodeId) return fail("delete_node: nodeId missing", 'Argument "nodeId" is required.');
     const reason = readString(input, "reason");
     if (!reason) {
       return fail(
-        "delete_node: alasan kosong",
+        "delete_node: reason missing",
         'Argument "reason" is required for destructive actions \u2014 state what the user asked for.'
       );
     }
@@ -1349,7 +1420,7 @@ var deleteNode = {
     if ("error" in applied) return applied.error;
     const op = { kind: "delete-node", nodeId };
     return succeed(
-      `Hapus ${describeNode(resolved.node)} \u2014 ${reason}`,
+      `Delete ${describeNode(resolved.node)} \u2014 ${reason}`,
       { nodeId, removedType: resolved.node.type },
       { op, document: applied.document }
     );
@@ -1383,7 +1454,7 @@ var replaceNodeTool = {
     const reason = readString(input, "reason");
     if (!nodeId || !raw || !reason) {
       return fail(
-        "replace_node: argumen kurang",
+        "replace_node: missing arguments",
         'Arguments "nodeId", "node" and "reason" are all required.'
       );
     }
@@ -1391,7 +1462,7 @@ var replaceNodeTool = {
     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);
+      return fail("replace_node: invalid node", normalized.error);
     }
     const replacement = { ...normalized.node, id: nodeId, type: resolved.node.type };
     const applied = applyCommand(
@@ -1403,7 +1474,7 @@ var replaceNodeTool = {
     if (violation) return violation;
     const op = { kind: "replace-node", nodeId, node: replacement };
     return succeed(
-      `Ganti struktur ${describeNode(resolved.node)} \u2014 ${reason}`,
+      `Replace structure of ${describeNode(resolved.node)} \u2014 ${reason}`,
       { nodeId, childCount: replacement.children?.length ?? 0 },
       { op, document: applied.document }
     );
@@ -1482,7 +1553,7 @@ var KubuildAiAgent = class {
       const available = this.tools.map((t) => t.definition.name).join(", ");
       return {
         ok: false,
-        summary: `Tool "${call.name}" tidak dikenal`,
+        summary: `Tool "${call.name}" is unknown`,
         snapshot,
         block: {
           type: "tool_result",
@@ -1579,7 +1650,7 @@ var KubuildAiAgent = class {
       selectedNodeId: request.selectedNodeId,
       prefix: this.options.systemPromptPrefix,
       stylePreference: request.stylePreference,
-      additionalContext: request.systemPrompt
+      additionalContext: joinInstructions(request.instructions, request.systemPrompt)
     });
     const toolDefinitions = toToolDefinitions(this.tools);
     const messages = [...request.messages];
@@ -1658,11 +1729,11 @@ var KubuildAiAgent = class {
       }
       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.`;
+        summary = `Stopped after ${maxSteps} steps. ${ops.length} change(s) prepared \u2014 review them and ask to continue if needed.`;
         this.log("warn", `[AGENT] hit maxSteps (${maxSteps}) with ${ops.length} op(s)`);
       }
       if (stoppedBy === "aborted" && !summary) {
-        summary = `Dihentikan. ${ops.length} perubahan sempat disiapkan.`;
+        summary = `Stopped. ${ops.length} change(s) were prepared before stopping.`;
       }
       yield {
         type: "agent-complete",
@@ -1681,7 +1752,7 @@ var KubuildAiAgent = class {
         type: "agent-complete",
         result: {
           ops,
-          summary: summary || `Terjadi error: ${message}`,
+          summary: summary || `An error occurred: ${message}`,
           stepsUsed: step,
           stoppedBy: "error",
           usage: { promptTokens, completionTokens }
@@ -1709,7 +1780,20 @@ var KubuildAiAgent = class {
 };
 
 // src/server/handler.ts
-async function processAiRequest(engine, body, signal, agent) {
+var DEFAULT_MAX_CLIENT_INSTRUCTIONS_LENGTH = 4e3;
+function resolveClientInstructions(payload, options) {
+  if (options?.allowClientInstructions === false) return void 0;
+  const text = joinInstructions(
+    typeof payload.instructions === "string" ? payload.instructions : void 0,
+    typeof payload.systemPrompt === "string" ? payload.systemPrompt : void 0
+  );
+  if (!text) return void 0;
+  const rawMax = options?.maxClientInstructionsLength;
+  const max = typeof rawMax === "number" && Number.isFinite(rawMax) && rawMax >= 0 ? Math.floor(rawMax) : DEFAULT_MAX_CLIENT_INSTRUCTIONS_LENGTH;
+  if (max === 0) return void 0;
+  return text.length > max ? text.slice(0, max) : text;
+}
+async function processAiRequest(engine, body, signal, agent, instructionsOptions) {
   if (!body || typeof body !== "object") {
     return {
       status: 400,
@@ -1724,6 +1808,7 @@ async function processAiRequest(engine, body, signal, agent) {
   }
   const payload = body;
   const mode = payload.mode || "full-page";
+  const instructions = resolveClientInstructions(payload, instructionsOptions);
   if (mode === "full-page") {
     if (!payload.prompt || typeof payload.prompt !== "string") {
       return {
@@ -1746,7 +1831,8 @@ async function processAiRequest(engine, body, signal, agent) {
         metadata: payload.metadata,
         conversationHistory: payload.conversationHistory ?? payload.messages,
         sectionCount: payload.sectionCount,
-        plan: payload.plan
+        plan: payload.plan,
+        instructions
       },
       { signal }
     );
@@ -1773,7 +1859,8 @@ async function processAiRequest(engine, body, signal, agent) {
         prompt: payload.prompt,
         stylePreference: payload.stylePreference,
         targetSectionType: payload.targetSectionType,
-        parentContext: payload.parentContext
+        parentContext: payload.parentContext,
+        instructions
       },
       { signal }
     );
@@ -1799,7 +1886,8 @@ async function processAiRequest(engine, body, signal, agent) {
       {
         node: payload.node,
         instruction: payload.instruction,
-        stylePreference: payload.stylePreference
+        stylePreference: payload.stylePreference,
+        instructions
       },
       { signal }
     );
@@ -1825,7 +1913,8 @@ async function processAiRequest(engine, body, signal, agent) {
       {
         messages: payload.messages,
         currentDocument: payload.currentDocument,
-        selectedNodeId: payload.selectedNodeId
+        selectedNodeId: payload.selectedNodeId,
+        instructions
       },
       { signal }
     );
@@ -1845,7 +1934,8 @@ async function processAiRequest(engine, body, signal, agent) {
         document: payload.document,
         selectedNodeId: payload.selectedNodeId,
         stylePreference: payload.stylePreference,
-        maxSteps: payload.maxSteps
+        maxSteps: payload.maxSteps,
+        instructions
       },
       { signal }
     );
@@ -1874,7 +1964,8 @@ async function processAiRequest(engine, body, signal, agent) {
         tone: payload.tone,
         locale: payload.locale,
         sectionCount: payload.sectionCount,
-        conversationHistory: payload.conversationHistory ?? payload.messages
+        conversationHistory: payload.conversationHistory ?? payload.messages,
+        instructions
       },
       { signal }
     );
@@ -1998,8 +2089,10 @@ 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";
+      const streamMode = body && typeof body === "object" ? body.mode || "full-page" : null;
+      if (body && typeof body === "object" && body.stream === true && (streamMode === "full-page" || streamMode === "chat" || streamMode === "agent")) {
+        const mode = streamMode;
+        const instructions = resolveClientInstructions(body, options);
         if (mode === "agent") {
           const validationError = validateAgentPayload(body, options?.agent);
           if (validationError) {
@@ -2015,7 +2108,8 @@ function createAiHandler(engine, options) {
                 document: body.document,
                 selectedNodeId: body.selectedNodeId,
                 stylePreference: body.stylePreference,
-                maxSteps: body.maxSteps
+                maxSteps: body.maxSteps,
+                instructions
               },
               { signal: request.signal }
             ),
@@ -2043,7 +2137,8 @@ function createAiHandler(engine, options) {
               {
                 messages: body.messages,
                 currentDocument: body.currentDocument,
-                selectedNodeId: body.selectedNodeId
+                selectedNodeId: body.selectedNodeId,
+                instructions
               },
               { signal: request.signal }
             ),
@@ -2075,7 +2170,8 @@ function createAiHandler(engine, options) {
               metadata: body.metadata,
               conversationHistory: body.conversationHistory ?? body.messages,
               sectionCount: body.sectionCount,
-              plan: body.plan
+              plan: body.plan,
+              instructions
             },
             { signal: request.signal }
           ),
@@ -2086,7 +2182,8 @@ function createAiHandler(engine, options) {
         engine,
         body,
         request.signal,
-        options?.agent
+        options?.agent,
+        options
       );
       return new Response(JSON.stringify(response), {
         status,
@@ -2117,6 +2214,7 @@ function createAiHandler(engine, options) {
 export {
   AnthropicAdapter,
   CustomHttpAdapter,
+  DEFAULT_MAX_CLIENT_INSTRUCTIONS_LENGTH,
   GeminiAdapter,
   KubuildAiAgent,
   KubuildAiEngine,
@@ -2130,6 +2228,7 @@ export {
   createDocumentTools,
   normalizeIncomingNode,
   processAiRequest,
+  resolveClientInstructions,
   suggestNodeIds,
   toToolDefinitions
 };