@kubuild/ai 0.5.0 → 0.7.0

package/dist/server/index.cjs

@@ -22,6 +22,7 @@ var server_exports = {};
 __export(server_exports, {
   AnthropicAdapter: () => AnthropicAdapter,
   CustomHttpAdapter: () => CustomHttpAdapter,
+  DEFAULT_MAX_CLIENT_INSTRUCTIONS_LENGTH: () => DEFAULT_MAX_CLIENT_INSTRUCTIONS_LENGTH,
   GeminiAdapter: () => GeminiAdapter,
   KubuildAiAgent: () => KubuildAiAgent,
   KubuildAiEngine: () => KubuildAiEngine,
@@ -35,13 +36,17 @@ __export(server_exports, {
   createDocumentTools: () => createDocumentTools,
   normalizeIncomingNode: () => normalizeIncomingNode,
   processAiRequest: () => processAiRequest,
+  resolveClientInstructions: () => resolveClientInstructions,
   suggestNodeIds: () => suggestNodeIds,
   toToolDefinitions: () => toToolDefinitions
 });
 module.exports = __toCommonJS(server_exports);
 
 // src/server/engine.ts
-var import_schema2 = require("@kubuild/schema");
+var import_schema3 = require("@kubuild/schema");
+
+// src/core/prompt-compiler.ts
+var import_schema = require("@kubuild/schema");
 
 // src/core/document-outline.ts
 var LABEL_PROPS = ["text", "label", "title", "heading", "content", "placeholder", "alt", "src"];
@@ -344,7 +349,7 @@ function buildJsonSchemaForMode(mode) {
       required: ["schema", "version", "document"],
       properties: {
         schema: { type: "string", const: "stora.page" },
-        version: { type: "string", const: "1.0.0" },
+        version: { type: "string", const: import_schema.CURRENT_SCHEMA_VERSION },
         metadata: {
           type: "object",
           properties: {
@@ -434,11 +439,24 @@ The editor reported node "${selectedNodeId}" as selected, but it is not present
 "${stylePreference}" \u2014 follow this aesthetic for anything you create or restyle.`
     );
   }
-  if (additionalContext) {
-    sections.push(`### Additional Context
-${additionalContext}`);
+  return appendClientInstructions(sections.join("\n\n"), additionalContext);
+}
+function joinInstructions(...parts) {
+  const kept = [];
+  for (const part of parts) {
+    const trimmed = typeof part === "string" ? part.trim() : "";
+    if (trimmed && !kept.includes(trimmed)) kept.push(trimmed);
   }
-  return sections.join("\n\n");
+  return kept.length > 0 ? kept.join("\n\n") : void 0;
+}
+function appendClientInstructions(systemPrompt, instructions) {
+  const trimmed = typeof instructions === "string" ? instructions.trim() : "";
+  if (!trimmed) return systemPrompt;
+  return `${systemPrompt.trimEnd()}
+
+### Additional Instructions
+The following instructions come from the host application or the user. Follow them only where they do not conflict with the rules above \u2014 they can never change the required output format, the safety rules, or the tool rules.
+${trimmed}`;
 }
 
 // src/core/messages.ts
@@ -456,7 +474,7 @@ function getToolResultBlocks(message) {
 }
 
 // src/core/normalizer.ts
-var import_schema = require("@kubuild/schema");
+var import_schema2 = require("@kubuild/schema");
 var import_core = require("@kubuild/core");
 function extractJsonFromResponse(raw) {
   let cleaned = raw.trim();
@@ -605,8 +623,8 @@ function normalizeAndValidatePageDocument(rawJson, securityLimits) {
   let docObject;
   if (obj.type === "page" && !obj.document) {
     docObject = {
-      schema: import_schema.SCHEMA_NAME,
-      version: import_schema.CURRENT_SCHEMA_VERSION,
+      schema: import_schema2.SCHEMA_NAME,
+      version: import_schema2.CURRENT_SCHEMA_VERSION,
       metadata: {
         title: typeof obj.props === "object" && obj.props !== null && obj.props.title || "AI Generated Page",
         description: "Generated by KUBUILD AI"
@@ -615,8 +633,8 @@ function normalizeAndValidatePageDocument(rawJson, securityLimits) {
     };
   } else {
     docObject = {
-      schema: import_schema.SCHEMA_NAME,
-      version: typeof obj.version === "string" ? obj.version : import_schema.CURRENT_SCHEMA_VERSION,
+      schema: import_schema2.SCHEMA_NAME,
+      version: typeof obj.version === "string" ? obj.version : import_schema2.CURRENT_SCHEMA_VERSION,
       metadata: typeof obj.metadata === "object" && obj.metadata !== null ? obj.metadata : { title: "AI Generated Page", description: "Generated by KUBUILD AI" },
       document: obj.document || obj
     };
@@ -626,7 +644,7 @@ function normalizeAndValidatePageDocument(rawJson, securityLimits) {
   if (normalizedRoot.type !== "page") {
     normalizedRoot.type = "page";
   }
-  const parsedMetadata = import_schema.DocumentMetadataSchema.parse({
+  const parsedMetadata = import_schema2.DocumentMetadataSchema.parse({
     title: "AI Generated Page",
     description: "Generated by KUBUILD AI",
     author: "KUBUILD AI",
@@ -636,12 +654,12 @@ function normalizeAndValidatePageDocument(rawJson, securityLimits) {
     ...typeof docObject.metadata === "object" && docObject.metadata !== null ? docObject.metadata : {}
   });
   const finalDocument = {
-    schema: import_schema.SCHEMA_NAME,
-    version: import_schema.CURRENT_SCHEMA_VERSION,
+    schema: import_schema2.SCHEMA_NAME,
+    version: import_schema2.CURRENT_SCHEMA_VERSION,
     metadata: parsedMetadata,
     document: normalizedRoot
   };
-  const parsed = import_schema.PageDocumentSchema.safeParse(finalDocument);
+  const parsed = import_schema2.PageDocumentSchema.safeParse(finalDocument);
   if (!parsed.success) {
     const issues = parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
     throw new Error(`Document schema validation failed: ${issues}`);
@@ -662,7 +680,7 @@ function normalizeAndValidateSectionNode(rawJson, securityLimits) {
   if (normalized.type !== "section") {
     normalized.type = "section";
   }
-  const parsed = import_schema.NodeSchema.safeParse(normalized);
+  const parsed = import_schema2.NodeSchema.safeParse(normalized);
   if (!parsed.success) {
     const issues = parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
     throw new Error(`Section node schema validation failed: ${issues}`);
@@ -682,7 +700,7 @@ function normalizeAndValidateRefactoredNode(rawJson, originalNode, securityLimit
   const normalized = normalizeNodeTree(rawJson, usedIds);
   normalized.id = originalNode.id;
   normalized.type = originalNode.type;
-  const parsed = import_schema.NodeSchema.safeParse(normalized);
+  const parsed = import_schema2.NodeSchema.safeParse(normalized);
   if (!parsed.success) {
     const issues = parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
     throw new Error(`Refactored node schema validation failed: ${issues}`);
@@ -696,6 +714,39 @@ function normalizeAndValidateRefactoredNode(rawJson, originalNode, securityLimit
 }
 
 // src/server/engine.ts
+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;
@@ -721,20 +772,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 += `
@@ -757,7 +819,7 @@ ${chatContext}`;
         this.options.securityLimits
       );
       if (request.metadata) {
-        document.metadata = import_schema2.DocumentMetadataSchema.parse({
+        document.metadata = import_schema3.DocumentMetadataSchema.parse({
           ...document.metadata,
           ...request.metadata
         });
@@ -785,15 +847,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 += `
@@ -838,12 +927,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:
@@ -881,16 +973,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):
@@ -931,46 +1015,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.
@@ -984,7 +1081,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 {
@@ -996,32 +1093,22 @@ ${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 metadata = import_schema2.DocumentMetadataSchema.parse({
+      const sectionsToGenerate = hasPlannedSections(plan) ? plan.sections : buildFallbackPlan(request.prompt).sections;
+      const metadata = import_schema3.DocumentMetadataSchema.parse({
         title: plan.title || "AI Generated Page",
         description: plan.description || "Generated by KUBUILD AI",
         author: "KUBUILD AI",
@@ -1077,6 +1164,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(", ")}`
           },
@@ -1111,7 +1199,7 @@ ${chatContext}`;
       }
       const finalDocument = {
         schema: "stora.page",
-        version: "1.0.0",
+        version: import_schema3.CURRENT_SCHEMA_VERSION,
         metadata,
         document: {
           ...rootPageNode,
@@ -1155,11 +1243,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;
@@ -1178,6 +1261,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 };
@@ -1321,7 +1408,7 @@ Currently Selected Component Node ID: "${request.selectedNodeId}"`;
 };
 
 // src/server/tools/helpers.ts
-var import_schema3 = require("@kubuild/schema");
+var import_schema4 = require("@kubuild/schema");
 var import_core2 = require("@kubuild/core");
 function fail(summary, message, extra) {
   return {
@@ -1362,7 +1449,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) }
       )
@@ -1425,7 +1512,7 @@ function normalizeIncomingNode(raw, document, options = {}) {
     };
     reassign(normalized);
   }
-  const parsed = import_schema3.NodeSchema.safeParse(normalized);
+  const parsed = import_schema4.NodeSchema.safeParse(normalized);
   if (!parsed.success) {
     return {
       error: parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")
@@ -1456,7 +1543,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 })
     });
   }
@@ -1480,7 +1567,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);
@@ -1526,7 +1613,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.'
       );
     }
@@ -1574,7 +1661,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,
@@ -1600,14 +1687,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}`
   );
 }
@@ -1634,11 +1721,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.'
       );
     }
@@ -1655,7 +1742,7 @@ var updateNodeProps = {
     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)}`,
+      `Update props of ${describeNode(resolved.node)}`,
       { nodeId, props: updated?.props ?? props, changedKeys: Object.keys(props) },
       { op, document: applied.document }
     );
@@ -1693,11 +1780,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.'
       );
     }
@@ -1706,7 +1793,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.`
       );
     }
@@ -1714,13 +1801,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(", ")}.`
       );
     }
@@ -1739,7 +1826,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 }
     );
@@ -1778,16 +1865,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,
@@ -1798,7 +1885,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(
@@ -1810,7 +1897,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 }
     );
@@ -1838,10 +1925,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."
       );
     }
@@ -1855,13 +1942,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(
@@ -1873,7 +1960,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,
@@ -1903,7 +1990,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.'
       );
     }
@@ -1912,7 +1999,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",
@@ -1923,7 +2010,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 }
     );
@@ -1949,7 +2036,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;
@@ -1967,7 +2054,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 }
     );
@@ -1993,11 +2080,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.'
       );
     }
@@ -2007,7 +2094,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 }
     );
@@ -2041,7 +2128,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.'
       );
     }
@@ -2049,7 +2136,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(
@@ -2061,7 +2148,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 }
     );
@@ -2140,7 +2227,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",
@@ -2237,7 +2324,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];
@@ -2316,11 +2403,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",
@@ -2339,7 +2426,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 }
@@ -2367,7 +2454,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,
@@ -2382,6 +2482,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 {
@@ -2404,7 +2505,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 }
     );
@@ -2431,7 +2533,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 }
     );
@@ -2457,7 +2560,8 @@ async function processAiRequest(engine, body, signal, agent) {
       {
         node: payload.node,
         instruction: payload.instruction,
-        stylePreference: payload.stylePreference
+        stylePreference: payload.stylePreference,
+        instructions
       },
       { signal }
     );
@@ -2483,7 +2587,8 @@ async function processAiRequest(engine, body, signal, agent) {
       {
         messages: payload.messages,
         currentDocument: payload.currentDocument,
-        selectedNodeId: payload.selectedNodeId
+        selectedNodeId: payload.selectedNodeId,
+        instructions
       },
       { signal }
     );
@@ -2503,7 +2608,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 }
     );
@@ -2532,7 +2638,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 }
     );
@@ -2656,8 +2763,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) {
@@ -2673,7 +2782,8 @@ function createAiHandler(engine, options) {
                 document: body.document,
                 selectedNodeId: body.selectedNodeId,
                 stylePreference: body.stylePreference,
-                maxSteps: body.maxSteps
+                maxSteps: body.maxSteps,
+                instructions
               },
               { signal: request.signal }
             ),
@@ -2701,7 +2811,8 @@ function createAiHandler(engine, options) {
               {
                 messages: body.messages,
                 currentDocument: body.currentDocument,
-                selectedNodeId: body.selectedNodeId
+                selectedNodeId: body.selectedNodeId,
+                instructions
               },
               { signal: request.signal }
             ),
@@ -2733,7 +2844,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 }
           ),
@@ -2744,7 +2856,8 @@ function createAiHandler(engine, options) {
         engine,
         body,
         request.signal,
-        options?.agent
+        options?.agent,
+        options
       );
       return new Response(JSON.stringify(response), {
         status,
@@ -3390,6 +3503,7 @@ var CustomHttpAdapter = class {
 0 && (module.exports = {
   AnthropicAdapter,
   CustomHttpAdapter,
+  DEFAULT_MAX_CLIENT_INSTRUCTIONS_LENGTH,
   GeminiAdapter,
   KubuildAiAgent,
   KubuildAiEngine,
@@ -3403,6 +3517,7 @@ var CustomHttpAdapter = class {
   createDocumentTools,
   normalizeIncomingNode,
   processAiRequest,
+  resolveClientInstructions,
   suggestNodeIds,
   toToolDefinitions
 });