@thanh01.pmt/curriculum-kit 1.0.1 → 1.0.3

package/dist/workflow/index.cjs

@@ -1,17 +1,20 @@
 'use strict';
 
+var fs = require('fs');
+var path4 = require('path');
 var ai = require('ai');
 var google = require('@ai-sdk/google');
 var openai = require('@ai-sdk/openai');
 var deepseek = require('@ai-sdk/deepseek');
-var fs = require('fs');
-var path = require('path');
 var zod = require('zod');
 var workflowPkg = require('workflow');
 var fs2 = require('fs/promises');
 var rest = require('@octokit/rest');
 var supabaseJs = require('@supabase/supabase-js');
+var url = require('url');
+require('crypto');
 
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
 function _interopNamespace(e) {
@@ -33,26 +36,133 @@ function _interopNamespace(e) {
 }
 
 var fs__default = /*#__PURE__*/_interopDefault(fs);
-var path__default = /*#__PURE__*/_interopDefault(path);
+var path4__default = /*#__PURE__*/_interopDefault(path4);
 var workflowPkg__namespace = /*#__PURE__*/_interopNamespace(workflowPkg);
 var fs2__default = /*#__PURE__*/_interopDefault(fs2);
 
-// src/ai/flows/generateLessonMasterFlow.ts
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+
+// src/errors/index.ts
+function createAiInferenceError(params) {
+  const {
+    errorCode,
+    message,
+    provider,
+    statusCode,
+    agent,
+    artifactType,
+    lessonId,
+    rawError,
+    suggestedAction = getSuggestedActionForCode(errorCode),
+    retryable = isCodeRetryable(errorCode)
+  } = params;
+  return new CurriculumError({
+    errorCode,
+    message,
+    provider,
+    statusCode,
+    agent,
+    artifactType,
+    lessonId,
+    suggestedAction,
+    retryable,
+    rawError: typeof rawError === "string" ? rawError : rawError?.message || JSON.stringify(rawError)
+  });
+}
+function getSuggestedActionForCode(code) {
+  switch (code) {
+    case "ERR_AI_NO_API_KEY":
+      return "V\xE0o Settings > API Keys \u0111\u1EC3 c\u1EA5u h\xECnh \xEDt nh\u1EA5t m\u1ED9t kh\xF3a API (Gemini, DeepSeek, OpenRouter, Alibaba ho\u1EB7c NVIDIA).";
+    case "ERR_AI_RATE_LIMIT":
+      return "API \u0111\xE3 v\u01B0\u1EE3t qu\xE1 gi\u1EDBi h\u1EA1n l\u01B0\u1EE3t g\u1ECDi (Rate Limit HTTP 429). H\xE3y ch\u1EDD 30-60 gi\xE2y r\u1ED3i b\u1EA5m Rerun ho\u1EB7c chuy\u1EC3n sang Provider d\u1EF1 ph\xF2ng.";
+    case "ERR_AI_AUTH_FAILED":
+      return "API Key kh\xF4ng h\u1EE3p l\u1EC7 ho\u1EB7c \u0111\xE3 h\u1EBFt h\u1EA1n (HTTP 401/403). Vui l\xF2ng ki\u1EC3m tra l\u1EA1i Key trong m\u1EE5c C\xE0i \u0111\u1EB7t.";
+    case "ERR_AI_NETWORK_TIMEOUT":
+      return "K\u1EBFt n\u1ED1i m\u1EA1ng t\u1EDBi m\xE1y ch\u1EE7 AI b\u1ECB qu\xE1 th\u1EDDi gian ch\u1EDD (Timeout). Vui l\xF2ng ki\u1EC3m tra \u0111\u01B0\u1EDDng truy\u1EC1n v\xE0 b\u1EA5m Rerun.";
+    case "ERR_AI_RESPONSE_MALFORMED":
+      return "M\xF4 h\xECnh AI tr\u1EA3 v\u1EC1 k\u1EBFt qu\u1EA3 r\u1ED7ng ho\u1EB7c kh\xF4ng \u0111\xFAng \u0111\u1ECBnh d\u1EA1ng markdown. B\u1EA5m Rerun \u0111\u1EC3 y\xEAu c\u1EA7u AI sinh l\u1EA1i.";
+    case "ERR_AI_ALL_PROVIDERS_FAILED":
+      return "To\xE0n b\u1ED9 c\xE1c nh\xE0 cung c\u1EA5p trong chu\u1ED7i Fallback \u0111\u1EC1u th\u1EA5t b\u1EA1i. Vui l\xF2ng ki\u1EC3m tra k\u1EBFt n\u1ED1i Internet v\xE0 h\u1EA1n m\u1EE9c Token.";
+    case "ERR_SOT_MISSING":
+      return "Thi\u1EBFu t\xE0i li\u1EC7u n\u1EC1n t\u1EA3ng SOT (CURRICULUM_FRAMEWORK.md ho\u1EB7c LEARNER_PROFILE.md). H\xE3y ch\u1EA1y workflow Kh\u1EDFi t\u1EA1o d\u1EF1 \xE1n tr\u01B0\u1EDBc.";
+    case "ERR_TASK_GATE_BLOCKED":
+      return "H\u1ECDc li\u1EC7u ph\xEDa sau b\u1ECB ch\u1EB7n do Gi\xE1o \xE1n (LESSON) ph\xEDa tr\u01B0\u1EDBc ch\u01B0a \u0111\u01B0\u1EE3c Ph\xEA duy\u1EC7t (Approval Gate). H\xE3y b\u1EA5m Ph\xEA duy\u1EC7t Gi\xE1o \xE1n \u0111\u1EC3 m\u1EDF kh\xF3a.";
+    case "ERR_METERED_LIMIT_EXCEEDED":
+      return "Ch\xEDnh s\xE1ch Metered Execution gi\u1EDBi h\u1EA1n t\u1ED1i \u0111a 2 b\xE0i h\u1ECDc m\u1ED7i \u0111\u1EE3t. Vui l\xF2ng ph\xEA duy\u1EC7t c\xE1c b\xE0i hi\u1EC7n t\u1EA1i tr\u01B0\u1EDBc khi t\u1EA1o th\xEAm.";
+    case "ERR_SCHEMA_CONTRACT_VIOLATION":
+      return "N\u1ED9i dung sinh ra thi\u1EBFu c\xE1c ph\u1EA7n b\u1EAFt bu\u1ED9c [REQUIRED]. H\xE3y k\xEDch ho\u1EA1t ki\u1EC3m th\u1EED ho\u1EB7c b\u1EA5m Rerun.";
+    case "ERR_STORAGE_IO_FAILED":
+      return "L\u1ED7i \u0111\u1ECDc/ghi t\u1EC7p tin tr\xEAn h\u1EC7 th\u1ED1ng l\u01B0u tr\u1EEF. Ki\u1EC3m tra quy\u1EC1n ghi th\u01B0 m\u1EE5c output/projects.";
+    default:
+      return "B\u1EA5m Rerun \u0111\u1EC3 th\u1EED l\u1EA1i ho\u1EB7c ki\u1EC3m tra nh\u1EADt k\xFD h\u1EC7 th\u1ED1ng.";
+  }
+}
+function isCodeRetryable(code) {
+  switch (code) {
+    case "ERR_AI_RATE_LIMIT":
+    case "ERR_AI_NETWORK_TIMEOUT":
+    case "ERR_AI_RESPONSE_MALFORMED":
+    case "ERR_STORAGE_IO_FAILED":
+      return true;
+    case "ERR_AI_NO_API_KEY":
+    case "ERR_AI_AUTH_FAILED":
+    case "ERR_SOT_MISSING":
+    case "ERR_TASK_GATE_BLOCKED":
+    case "ERR_METERED_LIMIT_EXCEEDED":
+    case "ERR_SCHEMA_CONTRACT_VIOLATION":
+      return false;
+    default:
+      return true;
+  }
+}
+var CurriculumError;
+var init_errors = __esm({
+  "src/errors/index.ts"() {
+    CurriculumError = class _CurriculumError extends Error {
+      detail;
+      constructor(detail) {
+        super(`[${detail.errorCode}] ${detail.message}`);
+        this.name = "CurriculumError";
+        this.detail = {
+          ...detail,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        };
+        Object.setPrototypeOf(this, _CurriculumError.prototype);
+      }
+      get errorCode() {
+        return this.detail.errorCode;
+      }
+      get retryable() {
+        return this.detail.retryable;
+      }
+      get suggestedAction() {
+        return this.detail.suggestedAction;
+      }
+      toJSON() {
+        return this.detail;
+      }
+    };
+  }
+});
 function resolveApiKey(keyName, explicitKey) {
+  if (explicitKey && explicitKey.trim()) return explicitKey.trim();
   if (typeof process !== "undefined" && process.env && process.env[keyName]) {
     return process.env[keyName];
   }
   try {
     const currentDir = process.cwd();
     const envPaths = [
-      path__default.default.resolve(currentDir, ".env.local"),
-      path__default.default.resolve(currentDir, ".env"),
-      path__default.default.resolve(currentDir, "apps/web/.env.local"),
-      path__default.default.resolve(currentDir, "packages/learnwell-platform/.env"),
-      path__default.default.resolve(currentDir, "..", ".env.local"),
-      path__default.default.resolve(currentDir, "..", ".env"),
-      path__default.default.resolve(currentDir, "../..", ".env.local"),
-      path__default.default.resolve(currentDir, "../..", ".env")
+      path4__default.default.resolve(currentDir, ".env.local"),
+      path4__default.default.resolve(currentDir, ".env"),
+      path4__default.default.resolve(currentDir, "apps/web/.env.local"),
+      path4__default.default.resolve(currentDir, "packages/learnwell-platform/.env"),
+      path4__default.default.resolve(currentDir, "..", ".env.local"),
+      path4__default.default.resolve(currentDir, "..", ".env"),
+      path4__default.default.resolve(currentDir, "../..", ".env.local"),
+      path4__default.default.resolve(currentDir, "../..", ".env")
     ];
     for (const envPath of envPaths) {
       if (fs__default.default.existsSync(envPath)) {
@@ -147,8 +257,571 @@ function getDesignatedFallbackConfig() {
   if (chain.length > 0) return chain[0];
   return { provider: "nvidia", model: "nvidia/nemotron-3-ultra-550b-a55b" };
 }
+function extractThoughtAndContent(rawText) {
+  let text = rawText || "";
+  let thought = "";
+  const thinkMatch = text.match(/<think>([\s\S]*?)<\/think>/i);
+  if (thinkMatch) {
+    thought = thinkMatch[1].trim();
+    text = text.replace(/<think>[\s\S]*?<\/think>/gi, "").trim();
+  } else if (text.includes("<think>")) {
+    const parts = text.split("<think>");
+    text = parts[0].trim();
+    thought = parts[1].trim();
+  }
+  if (!thought && (text.startsWith("Here's a thinking process:") || text.startsWith("Thinking Process:"))) {
+    const splitRegex = /\n(?=(?:#|##|###|🎯|🧭|📋|🚀|1\.\s+[A-Z\u00C0-\u1EF9]|---))/m;
+    const match = text.search(splitRegex);
+    if (match > 0) {
+      thought = text.slice(0, match).trim();
+      text = text.slice(match).trim();
+    }
+  }
+  let content = text.trim();
+  if (content.startsWith("```markdown")) {
+    content = content.replace(/^```markdown\s*\n/i, "").replace(/\n```\s*$/i, "");
+  } else if (content.startsWith("```md")) {
+    content = content.replace(/^```md\s*\n/i, "").replace(/\n```\s*$/i, "");
+  } else if (content.startsWith("```") && content.endsWith("```") && !content.includes("---")) {
+    content = content.replace(/^```\w*\s*\n/i, "").replace(/\n```\s*$/i, "");
+  }
+  return {
+    thought: thought.trim(),
+    content: content.trim()
+  };
+}
+function createIdleAbortController(idleMs) {
+  const controller = new AbortController();
+  let timer = null;
+  const arm = () => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(
+      () => controller.abort(new Error(`Idle timeout: no data for ${Math.round(idleMs / 1e3)}s`)),
+      idleMs
+    );
+    timer?.unref?.();
+  };
+  arm();
+  return {
+    signal: controller.signal,
+    /** Reset the idle window (call on every received chunk). */
+    kick: arm,
+    /** Clear the pending timer once the request lifecycle is over. */
+    dispose: () => {
+      if (timer) clearTimeout(timer);
+      timer = null;
+    }
+  };
+}
+async function processOpenAISSEStream(response, onChunk, idle, toolCallCollector) {
+  if (!response.body) return "";
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder("utf-8");
+  let fullRaw = "";
+  let buffer = "";
+  let insideThinkTag = false;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    idle?.kick();
+    buffer += decoder.decode(value, { stream: true });
+    const lines = buffer.split("\n");
+    buffer = lines.pop() || "";
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith(":")) continue;
+      if (trimmed === "data: [DONE]") continue;
+      if (trimmed.startsWith("data: ")) {
+        try {
+          const json = JSON.parse(trimmed.substring(6));
+          if (json.usage) {
+            const promptTokens = json.usage.prompt_tokens || json.usage.input_tokens || 0;
+            const completionTokens = json.usage.completion_tokens || json.usage.output_tokens || 0;
+            const totalTokens = json.usage.total_tokens || promptTokens + completionTokens;
+            const reasoningTokens = json.usage.completion_tokens_details?.reasoning_tokens || 0;
+            if (onChunk) {
+              onChunk(JSON.stringify({ promptTokens, completionTokens, totalTokens, reasoningTokens }), "usage");
+            }
+          }
+          const delta = json.choices?.[0]?.delta;
+          if (!delta) continue;
+          const reasoning = delta.reasoning_content || delta.thought || delta.reasoning || delta.thought_process || "";
+          if (reasoning) {
+            if (onChunk) onChunk(reasoning, "thought");
+          }
+          if (delta.tool_calls) {
+            const toolStr = JSON.stringify(delta.tool_calls);
+            if (onChunk) onChunk(toolStr, "tool_call");
+            if (toolCallCollector) ;
+          }
+          let content = delta.content || "";
+          if (content) {
+            fullRaw += content;
+            if (content.includes("<think>")) {
+              insideThinkTag = true;
+              const parts = content.split("<think>");
+              if (parts[0] && onChunk) onChunk(parts[0], "content");
+              content = parts[1] || "";
+            }
+            if (content.includes("</think>")) {
+              insideThinkTag = false;
+              const parts = content.split("</think>");
+              if (parts[0] && onChunk) onChunk(parts[0], "thought");
+              content = parts[1] || "";
+            }
+            if (insideThinkTag) {
+              if (onChunk && content) onChunk(content, "thought");
+            } else if (content) {
+              if (onChunk) onChunk(content, "content");
+            }
+          }
+        } catch {
+        }
+      }
+    }
+  }
+  idle?.dispose();
+  const extracted = extractThoughtAndContent(fullRaw);
+  return extracted.content || fullRaw;
+}
+async function processGeminiSSEStream(response, onChunk, idle) {
+  if (!response.body) return "";
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder("utf-8");
+  let fullText = "";
+  let buffer = "";
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    idle?.kick();
+    buffer += decoder.decode(value, { stream: true });
+    const lines = buffer.split("\n");
+    buffer = lines.pop() || "";
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith(":")) continue;
+      if (trimmed.startsWith("data: ")) {
+        try {
+          const json = JSON.parse(trimmed.substring(6));
+          if (json.usageMetadata) {
+            const promptTokens = json.usageMetadata.promptTokenCount || 0;
+            const completionTokens = json.usageMetadata.candidatesTokenCount || 0;
+            const totalTokens = json.usageMetadata.totalTokenCount || promptTokens + completionTokens;
+            if (onChunk) {
+              onChunk(JSON.stringify({ promptTokens, completionTokens, totalTokens }), "usage");
+            }
+          }
+          const parts = json.candidates?.[0]?.content?.parts || [];
+          for (const part of parts) {
+            if (part.thought) {
+              if (onChunk) onChunk(part.text || "", "thought");
+            } else if (part.text) {
+              fullText += part.text;
+              if (onChunk) onChunk(part.text, "content");
+            }
+          }
+        } catch {
+        }
+      }
+    }
+  }
+  idle?.dispose();
+  return fullText;
+}
+async function streamCurriculumAIInference(messages, projectContext, options = {}, onChunk) {
+  const openrouterKey = resolveApiKey("OPENROUTER_API_KEY", options.openrouterKey);
+  const deepseekKey = resolveApiKey("DEEPSEEK_API_KEY", options.deepseekKey);
+  const alibabaKey = resolveApiKey("ALIBABA_API_KEY", options.alibabaKey) || resolveApiKey("DASHSCOPE_API_KEY");
+  const geminiKey = resolveApiKey("GEMINI_API_KEY", options.geminiKey) || resolveApiKey("NEXT_PUBLIC_GEMINI_API_KEY");
+  const nvidiaKey = resolveApiKey("NVIDIA_API_KEY", options.nvidiaKey);
+  const temperature = options.temperature ?? 0.3;
+  const maxTokens = options.maxTokens ?? 32768;
+  const basePersona = options.systemPersona || "You are Curriculum OS Assistant \u2014 Senior AI Technical Curriculum Architect & Educational Content Specialist.";
+  const systemInstruction = `${basePersona}
+
+Project Context:
+${projectContext}
+
+Guidelines:
+1. You have full context of the project hierarchy, syllabus, lessons, and learning objectives. Answer precisely, deeply, and directly.
+2. Complete responses fully without truncation. When generating tables or roadmaps, include all sections/milestones.
+3. Keep technical terminology and official API symbols intact.
+4. Format output using clean Markdown, clear sections, bullet points, and code blocks where required.
+5. Do NOT use emojis in headings, tab titles, or UI navigation labels.`;
+  const formattedMessages = [
+    { role: "system", content: systemInstruction },
+    ...messages.map((m) => ({
+      role: m.role === "assistant" || m.role === "model" ? "assistant" : "user",
+      content: m.content
+    }))
+  ];
+  const providerErrors = {};
+  const requestedModel = options.model || "@preset/coding-free";
+  const isNvidiaPreferred = requestedModel.startsWith("nvidia/") || Boolean(nvidiaKey && !openrouterKey) && isProviderEnabled("nvidia");
+  if (nvidiaKey && isProviderEnabled("nvidia")) {
+    const candidateNemotronModels = [
+      requestedModel.startsWith("nvidia/") ? requestedModel : "nvidia/nemotron-3-ultra-550b-a55b",
+      "nvidia/nemotron-3-ultra-550b-a55b",
+      "nvidia/nemotron-3.5-lightning-30b-a3b",
+      "nvidia/nemotron-3-super-120b-a12b",
+      "nvidia/llama-3.1-nemotron-70b-instruct"
+    ].filter((m) => isModelAllowed(m));
+    const uniqueNvidiaModels = Array.from(new Set(candidateNemotronModels));
+    if (isNvidiaPreferred || uniqueNvidiaModels.length > 0) {
+      for (const model of uniqueNvidiaModels) {
+        try {
+          const idle = createIdleAbortController(18e4);
+          const res = await fetch("https://integrate.api.nvidia.com/v1/chat/completions", {
+            method: "POST",
+            headers: {
+              "Authorization": `Bearer ${nvidiaKey}`,
+              "Content-Type": "application/json"
+            },
+            body: JSON.stringify({
+              model,
+              messages: formattedMessages,
+              max_tokens: maxTokens,
+              temperature,
+              stream: true,
+              stream_options: { include_usage: true }
+            }),
+            signal: idle.signal
+          });
+          if (res.ok) {
+            const text = await processOpenAISSEStream(res, onChunk, idle);
+            if (text && text.trim()) return text;
+          } else {
+            const errText = await res.text().catch(() => "");
+            providerErrors[`nvidia_${model}`] = `HTTP ${res.status}: ${errText.slice(0, 120)}`;
+          }
+        } catch (e) {
+          providerErrors[`nvidia_${model}`] = e?.message || "Network error";
+          console.warn(`[NVIDIA Stream] Failover for ${model}:`, e?.message || e);
+        }
+      }
+    }
+  }
+  if (openrouterKey && isProviderEnabled("openrouter")) {
+    const openrouterModels = [
+      requestedModel,
+      "openrouter/free",
+      "nvidia/nemotron-3-super-120b-a12b:free",
+      "nvidia/nemotron-3-ultra-550b-a55b:free",
+      "nvidia/nemotron-3.5-lightning:free",
+      "minimax/minimax-m3:free",
+      "cohere/north-mini-code:free"
+    ].filter((m) => isModelAllowed(m));
+    const uniqueOrModels = Array.from(new Set(openrouterModels));
+    for (const model of uniqueOrModels) {
+      try {
+        const idle = createIdleAbortController(18e4);
+        const res = await fetch("https://openrouter.ai/api/v1/chat/completions", {
+          method: "POST",
+          headers: {
+            "Authorization": `Bearer ${openrouterKey}`,
+            "Content-Type": "application/json",
+            "HTTP-Referer": "https://orchable.composer",
+            "X-Title": "Curriculum OS Studio"
+          },
+          body: JSON.stringify({
+            model,
+            messages: formattedMessages,
+            max_tokens: maxTokens,
+            temperature,
+            stream: true,
+            stream_options: { include_usage: true }
+          }),
+          signal: idle.signal
+        });
+        if (res.ok) {
+          const text = await processOpenAISSEStream(res, onChunk, idle);
+          if (text && text.trim()) return text;
+        } else {
+          const errText = await res.text().catch(() => "");
+          providerErrors[`openrouter_${model}`] = `HTTP ${res.status}: ${errText.slice(0, 120)}`;
+          if (res.status === 429) {
+            console.warn(`[OpenRouter] Rate limited (429) for ${model}, trying fallback...`);
+          }
+        }
+      } catch (e) {
+        providerErrors[`openrouter_${model}`] = e?.message || "Network error";
+        console.warn(`[OpenRouter Stream] Failover for ${model}:`, e?.message || e);
+      }
+    }
+  }
+  if (deepseekKey && isProviderEnabled("deepseek")) {
+    const dsModel = options.model?.includes("deepseek-reasoner") ? "deepseek-reasoner" : "deepseek-chat";
+    if (isModelAllowed(dsModel)) {
+      try {
+        const idle = createIdleAbortController(18e4);
+        const res = await fetch("https://api.deepseek.com/chat/completions", {
+          method: "POST",
+          headers: {
+            "Authorization": `Bearer ${deepseekKey}`,
+            "Content-Type": "application/json"
+          },
+          body: JSON.stringify({
+            model: dsModel,
+            messages: formattedMessages,
+            max_tokens: maxTokens,
+            temperature,
+            stream: true,
+            stream_options: { include_usage: true }
+          }),
+          signal: idle.signal
+        });
+        if (res.ok) {
+          const text = await processOpenAISSEStream(res, onChunk, idle);
+          if (text && text.trim()) return text;
+        } else {
+          const errText = await res.text().catch(() => "");
+          providerErrors["deepseek"] = `HTTP ${res.status}: ${errText.slice(0, 120)}`;
+        }
+      } catch (e) {
+        providerErrors["deepseek"] = e?.message || "Network error";
+        console.warn(`[DeepSeek Stream] Failover:`, e?.message || e);
+      }
+    }
+  }
+  if (alibabaKey && isProviderEnabled("alibaba")) {
+    const qwenModels = (options.model?.startsWith("qwen") ? [options.model, "qwen3.7-plus", "qwen3.6-flash"] : ["qwen3.7-plus", "qwen3.6-flash"]).filter((m) => isModelAllowed(m));
+    const baseUrl = alibabaKey.startsWith("sk-sp-") ? "https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions" : "https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions";
+    for (const qwenModel of qwenModels) {
+      try {
+        const idle = createIdleAbortController(18e4);
+        const payload = {
+          model: qwenModel,
+          messages: formattedMessages,
+          max_tokens: maxTokens,
+          temperature,
+          stream: true,
+          stream_options: { include_usage: true }
+        };
+        const res = await fetch(baseUrl, {
+          method: "POST",
+          headers: {
+            "Authorization": `Bearer ${alibabaKey}`,
+            "Content-Type": "application/json"
+          },
+          body: JSON.stringify(payload),
+          signal: idle.signal
+        });
+        if (res.ok) {
+          const text = await processOpenAISSEStream(res, onChunk, idle);
+          if (text && text.trim()) return text;
+        } else {
+          const errText = await res.text().catch(() => "");
+          providerErrors[`alibaba_${qwenModel}`] = `HTTP ${res.status}: ${errText.slice(0, 120)}`;
+        }
+      } catch (e) {
+        providerErrors[`alibaba_${qwenModel}`] = e?.message || "Network error";
+        console.warn(`[Alibaba Stream] Failover for ${qwenModel}:`, e?.message || e);
+      }
+    }
+  }
+  if (geminiKey && (isProviderEnabled("gemini") || isProviderEnabled("google"))) {
+    const geminiModels = (options.model?.startsWith("gemini") ? [options.model, "gemini-1.5-flash", "gemini-2.0-flash"] : ["gemini-1.5-flash", "gemini-2.0-flash"]).filter((m) => isModelAllowed(m));
+    const geminiContents = [
+      { role: "user", parts: [{ text: systemInstruction }] },
+      { role: "model", parts: [{ text: "T\xF4i \u0111\xE3 hi\u1EC3u r\xF5 to\xE0n b\u1ED9 b\u1ED1i c\u1EA3nh d\u1EF1 \xE1n v\xE0 s\u1EB5n s\xE0ng h\u1ED7 tr\u1EE3 b\u1EA1n m\u1ED9t c\xE1ch chuy\xEAn s\xE2u, ch\xEDnh x\xE1c nh\u1EA5t." }] },
+      ...messages.map((m) => ({
+        role: m.role === "assistant" || m.role === "model" ? "model" : "user",
+        parts: [{ text: m.content }]
+      }))
+    ];
+    for (const gModel of geminiModels) {
+      try {
+        const idle = createIdleAbortController(18e4);
+        const res = await fetch(`https://generativelanguage.googleapis.com/v1beta/models/${gModel}:streamGenerateContent?alt=sse&key=${geminiKey}`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            contents: geminiContents,
+            generationConfig: {
+              temperature,
+              maxOutputTokens: maxTokens
+            }
+          }),
+          signal: idle.signal
+        });
+        if (res.ok) {
+          const text = await processGeminiSSEStream(res, onChunk, idle);
+          if (text && text.trim()) return text;
+        } else {
+          const errText = await res.text().catch(() => "");
+          providerErrors[`gemini_${gModel}`] = `HTTP ${res.status}: ${errText.slice(0, 120)}`;
+        }
+      } catch (e) {
+        providerErrors[`gemini_${gModel}`] = e?.message || "Network error";
+        console.warn(`[Gemini Stream] Failover for ${gModel}:`, e?.message || e);
+      }
+    }
+  }
+  const fallbackChain = getDesignatedFallbackChain();
+  if (fallbackChain.length > 0) {
+    console.log(
+      `[streamRunner] \u{1F6E1}\uFE0F Primary routes failed/exhausted. Invoking designated last-resort fallback chain:`,
+      fallbackChain.map((c) => `${c.provider}(${c.model})`).join(" -> ")
+    );
+    for (const target of fallbackChain) {
+      const { provider, model } = target;
+      if (provider === "nvidia" && nvidiaKey && isProviderEnabled("nvidia")) {
+        try {
+          const idle = createIdleAbortController(18e4);
+          const res = await fetch("https://integrate.api.nvidia.com/v1/chat/completions", {
+            method: "POST",
+            headers: {
+              "Authorization": `Bearer ${nvidiaKey}`,
+              "Content-Type": "application/json"
+            },
+            body: JSON.stringify({
+              model,
+              messages: formattedMessages,
+              max_tokens: maxTokens,
+              temperature,
+              stream: true,
+              stream_options: { include_usage: true }
+            }),
+            signal: idle.signal
+          });
+          if (res.ok) {
+            const text = await processOpenAISSEStream(res, onChunk, idle);
+            if (text && text.trim()) {
+              console.log(`[streamRunner] \u2705 Designated fallback NVIDIA (${model}) succeeded!`);
+              return text;
+            }
+          } else {
+            const errText = await res.text().catch(() => "");
+            providerErrors[`designated_fallback_nvidia_${model}`] = `HTTP ${res.status}: ${errText.slice(0, 120)}`;
+          }
+        } catch (e) {
+          providerErrors[`designated_fallback_nvidia_${model}`] = e?.message || "Network error";
+        }
+      } else if (provider === "openrouter" && openrouterKey && isProviderEnabled("openrouter")) {
+        try {
+          const idle = createIdleAbortController(18e4);
+          const res = await fetch("https://openrouter.ai/api/v1/chat/completions", {
+            method: "POST",
+            headers: {
+              "Authorization": `Bearer ${openrouterKey}`,
+              "Content-Type": "application/json",
+              "HTTP-Referer": "https://orchable.composer",
+              "X-Title": "Curriculum OS Studio"
+            },
+            body: JSON.stringify({
+              model,
+              messages: formattedMessages,
+              max_tokens: maxTokens,
+              temperature,
+              stream: true,
+              stream_options: { include_usage: true }
+            }),
+            signal: idle.signal
+          });
+          if (res.ok) {
+            const text = await processOpenAISSEStream(res, onChunk, idle);
+            if (text && text.trim()) {
+              console.log(`[streamRunner] \u2705 Designated fallback OpenRouter (${model}) succeeded!`);
+              return text;
+            }
+          } else {
+            const errText = await res.text().catch(() => "");
+            providerErrors[`designated_fallback_openrouter_${model}`] = `HTTP ${res.status}: ${errText.slice(0, 120)}`;
+          }
+        } catch (e) {
+          providerErrors[`designated_fallback_openrouter_${model}`] = e?.message || "Network error";
+        }
+      } else if ((provider === "alibaba" || provider === "dashscope") && alibabaKey && isProviderEnabled("alibaba")) {
+        const baseUrl = alibabaKey.startsWith("sk-sp-") ? "https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions" : "https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions";
+        try {
+          const idle = createIdleAbortController(18e4);
+          const res = await fetch(baseUrl, {
+            method: "POST",
+            headers: {
+              "Authorization": `Bearer ${alibabaKey}`,
+              "Content-Type": "application/json"
+            },
+            body: JSON.stringify({
+              model,
+              messages: formattedMessages,
+              max_tokens: maxTokens,
+              temperature,
+              stream: true,
+              stream_options: { include_usage: true }
+            }),
+            signal: idle.signal
+          });
+          if (res.ok) {
+            const text = await processOpenAISSEStream(res, onChunk, idle);
+            if (text && text.trim()) {
+              console.log(`[streamRunner] \u2705 Designated fallback Alibaba (${model}) succeeded!`);
+              return text;
+            }
+          } else {
+            const errText = await res.text().catch(() => "");
+            providerErrors[`designated_fallback_alibaba_${model}`] = `HTTP ${res.status}: ${errText.slice(0, 120)}`;
+          }
+        } catch (e) {
+          providerErrors[`designated_fallback_alibaba_${model}`] = e?.message || "Network error";
+        }
+      } else if ((provider === "google" || provider === "gemini") && geminiKey && (isProviderEnabled("gemini") || isProviderEnabled("google"))) {
+        try {
+          const idle = createIdleAbortController(18e4);
+          const res = await fetch(
+            `https://generativelanguage.googleapis.com/v1beta/models/${model}:streamGenerateContent?alt=sse&key=${geminiKey}`,
+            {
+              method: "POST",
+              headers: { "Content-Type": "application/json" },
+              body: JSON.stringify({
+                contents: [
+                  { role: "user", parts: [{ text: systemInstruction }] },
+                  { role: "model", parts: [{ text: "Understood. I will follow the project context and guidelines." }] },
+                  ...messages.map((m) => ({
+                    role: m.role === "assistant" || m.role === "model" ? "model" : "user",
+                    parts: [{ text: m.content }]
+                  }))
+                ],
+                generationConfig: {
+                  temperature,
+                  maxOutputTokens: maxTokens
+                }
+              }),
+              signal: idle.signal
+            }
+          );
+          if (res.ok) {
+            const text = await processGeminiSSEStream(res, onChunk, idle);
+            if (text && text.trim()) {
+              console.log(`[streamRunner] \u2705 Designated fallback Gemini (${model}) succeeded!`);
+              return text;
+            }
+          } else {
+            const errText = await res.text().catch(() => "");
+            providerErrors[`designated_fallback_gemini_${model}`] = `HTTP ${res.status}: ${errText.slice(0, 120)}`;
+          }
+        } catch (e) {
+          providerErrors[`designated_fallback_gemini_${model}`] = e?.message || "Network error";
+        }
+      }
+    }
+  }
+  const isRateLimited = Object.values(providerErrors).some((msg) => msg.includes("429"));
+  const isAuthFailed = Object.values(providerErrors).some((msg) => msg.includes("401") || msg.includes("403"));
+  const errorCode = isRateLimited ? "ERR_AI_RATE_LIMIT" : isAuthFailed ? "ERR_AI_AUTH_FAILED" : "ERR_AI_ALL_PROVIDERS_FAILED";
+  throw createAiInferenceError({
+    errorCode,
+    message: `Kh\xF4ng th\u1EC3 k\u1EBFt n\u1ED1i t\u1EDBi c\xE1c nh\xE0 cung c\u1EA5p AI trong chu\u1ED7i Fallback. Chi ti\u1EBFt: ${JSON.stringify(providerErrors)}`,
+    rawError: providerErrors
+  });
+}
+var init_streamRunner = __esm({
+  "src/ai/streamRunner.ts"() {
+    init_errors();
+  }
+});
 
 // src/ai/provider-factory.ts
+init_streamRunner();
 var DEFAULT_MODELS = {
   nvidia: "nvidia/nemotron-3-ultra-550b-a55b",
   openrouter: "@preset/coding-free",
@@ -3928,10 +4601,10 @@ ${answerKeySection}
 var LocalWorkspaceManager = class {
   baseDir;
   constructor(baseDir) {
-    this.baseDir = baseDir || path__default.default.resolve(process.cwd(), "output", "workspace-jobs");
+    this.baseDir = baseDir || path4__default.default.resolve(process.cwd(), "output", "workspace-jobs");
   }
   getJobDirectory(jobId) {
-    return path__default.default.join(this.baseDir, jobId);
+    return path4__default.default.join(this.baseDir, jobId);
   }
   async initJobWorkspace(jobId, initialInfo) {
     const jobDir = this.getJobDirectory(jobId);
@@ -3954,9 +4627,9 @@ var LocalWorkspaceManager = class {
   }
   async saveArtifact(jobId, milestoneSlug, filename, content, artifactType) {
     const jobDir = this.getJobDirectory(jobId);
-    const targetDir = path__default.default.join(jobDir, milestoneSlug);
+    const targetDir = path4__default.default.join(jobDir, milestoneSlug);
     await fs2__default.default.mkdir(targetDir, { recursive: true });
-    const filePath = path__default.default.join(targetDir, filename);
+    const filePath = path4__default.default.join(targetDir, filename);
     await fs2__default.default.writeFile(filePath, content, "utf-8");
     const stat = await fs2__default.default.stat(filePath);
     const manifest = await this.getManifest(jobId);
@@ -3964,7 +4637,7 @@ var LocalWorkspaceManager = class {
       manifest.artifacts.push({
         milestoneId: milestoneSlug,
         artifactType,
-        filePath: path__default.default.relative(jobDir, filePath),
+        filePath: path4__default.default.relative(jobDir, filePath),
         sizeBytes: stat.size,
         createdAt: (/* @__PURE__ */ new Date()).toISOString()
       });
@@ -3974,7 +4647,7 @@ var LocalWorkspaceManager = class {
     return filePath;
   }
   async getManifest(jobId) {
-    const manifestPath = path__default.default.join(this.getJobDirectory(jobId), "manifest.json");
+    const manifestPath = path4__default.default.join(this.getJobDirectory(jobId), "manifest.json");
     try {
       const data = await fs2__default.default.readFile(manifestPath, "utf-8");
       return JSON.parse(data);
@@ -3983,7 +4656,7 @@ var LocalWorkspaceManager = class {
     }
   }
   async saveManifest(jobId, manifest) {
-    const manifestPath = path__default.default.join(this.getJobDirectory(jobId), "manifest.json");
+    const manifestPath = path4__default.default.join(this.getJobDirectory(jobId), "manifest.json");
     manifest.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
     await fs2__default.default.writeFile(manifestPath, JSON.stringify(manifest, null, 2), "utf-8");
   }
@@ -4024,12 +4697,12 @@ async function publishToGitHub(options) {
     async function scanDir(currentDir) {
       const entries = await fs2__default.default.readdir(currentDir, { withFileTypes: true });
       for (const entry of entries) {
-        const fullPath = path__default.default.join(currentDir, entry.name);
+        const fullPath = path4__default.default.join(currentDir, entry.name);
         if (entry.isDirectory()) {
           await scanDir(fullPath);
         } else if (entry.isFile() && !entry.name.startsWith(".")) {
           const content = await fs2__default.default.readFile(fullPath, "utf-8");
-          const relPath = path__default.default.relative(options.localJobDir, fullPath);
+          const relPath = path4__default.default.relative(options.localJobDir, fullPath);
           filesToUpload.push({ path: relPath, content });
         }
       }
@@ -5237,8 +5910,480 @@ async function generateRoadmapWorkflow(input) {
   };
 }
 
+// src/services/singleArtifactService.ts
+init_streamRunner();
+
+// src/services/lessonProductionService.ts
+init_streamRunner();
+init_errors();
+
+// src/services/lessonProductionService.ts
+var __filename$1 = typeof (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)) === "string" ? url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href))) : "";
+var _resolvedDir = __filename$1 ? path4__default.default.dirname(__filename$1) : typeof __dirname !== "undefined" ? __dirname : process.cwd();
+function loadCurriculumTemplate(templateName) {
+  const candidatePaths = [
+    path4__default.default.resolve("/Users/tonypham/MEGA/WebApp/WIP/learnwell-platform/packages/curriculum-kit/docs/refs/templates", templateName),
+    path4__default.default.resolve(process.cwd(), "packages/curriculum-kit/docs/refs/templates", templateName),
+    path4__default.default.resolve(process.cwd(), "_templates", templateName),
+    path4__default.default.resolve(process.cwd(), "docs/refs/templates", templateName),
+    path4__default.default.resolve(_resolvedDir, "../docs/refs/templates", templateName),
+    path4__default.default.resolve(_resolvedDir, "../../docs/refs/templates", templateName),
+    path4__default.default.resolve(_resolvedDir, "../../../docs/refs/templates", templateName),
+    path4__default.default.resolve("/Users/tonypham/MEGA/WebApp/content-gen/the-ultimate-curriculum-agent-os/_templates", templateName),
+    path4__default.default.resolve(_resolvedDir, "../../../../the-ultimate-curriculum-agent-os/_templates", templateName)
+  ];
+  for (const p of candidatePaths) {
+    if (fs__default.default.existsSync(p)) {
+      try {
+        return fs__default.default.readFileSync(p, "utf-8");
+      } catch {
+      }
+    }
+  }
+  console.warn(`[curriculum-kit:loadCurriculumTemplate] \u26A0\uFE0F Template "${templateName}" not found across candidate paths. Falling back to inline structural scaffolding.`);
+  return "";
+}
+
+// src/services/singleArtifactService.ts
+init_errors();
+function getArtifactMetadata(type, lessonId, pedagogy) {
+  const id = lessonId || "ON_DEMAND";
+  switch (type) {
+    case "lesson": {
+      const p = (pedagogy || "").toLowerCase();
+      const templateFile = p === "edp" ? "LESSON_EDP_template.md" : p === "general" ? "LESSON_GENERAL_template.md" : "LESSON_5E_template.md";
+      return { filename: `LESSON_${id}.md`, persona: "@content", templateFile };
+    }
+    case "slide":
+      return { filename: `SLIDE_${id}.md`, persona: "@illustrator", templateFile: "SLIDE_template.md" };
+    case "act":
+      return { filename: `ACT_${id}.md`, persona: "@activity", templateFile: "ACT_template.md" };
+    case "quiz":
+      return { filename: `QUIZ_${id}.md`, persona: "@assessor", templateFile: "QUIZ_v4.6_template.md" };
+    case "guide":
+      return { filename: `GUIDE_${id}.md`, persona: "@content", templateFile: "GUIDE_template.md" };
+    case "handout":
+      return { filename: `HANDOUT_${id}.md`, persona: "@content", templateFile: "HANDOUT_template.md" };
+    case "worksheet":
+      return { filename: `WKS_${id}.md`, persona: "@content", templateFile: "WKS_template.md" };
+    case "rubric":
+      return { filename: `RUBRIC_${id}.md`, persona: "@assessor", templateFile: "RUBRIC_template.md" };
+    case "ext":
+      return { filename: `EXT_${id}.md`, persona: "@activity", templateFile: "EXT_template.md" };
+    case "glossary":
+      return { filename: `GLOSSARY_${id}.md`, persona: "@content", templateFile: "GLOSSARY_template.md" };
+    case "codelab":
+      return { filename: `CODE_${id}.md`, persona: "@activity", templateFile: "ACT_template.md" };
+    case "bom":
+      return { filename: `BOM_${id}.md`, persona: "@activity", templateFile: "PROJECT_BRIEF_template.md" };
+    case "exit_ticket":
+      return { filename: `EXIT_TICKET_${id}.md`, persona: "@assessor", templateFile: "EXIT_TICKET_template.md" };
+    case "tiered_practice":
+      return { filename: `TIERED_PRACTICE_${id}.md`, persona: "@activity", templateFile: "TIERED_PRACTICE_template.md" };
+    case "choice_board":
+      return { filename: `CHOICE_BOARD_${id}.md`, persona: "@activity", templateFile: "CHOICE_BOARD_template.md" };
+    case "science_lab":
+      return { filename: `SCIENCE_LAB_${id}.md`, persona: "@activity", templateFile: "SCIENCE_LAB_template.md" };
+    case "task_cards":
+      return { filename: `TASK_CARDS_${id}.md`, persona: "@activity", templateFile: "TASK_CARDS_template.md" };
+    case "station_rotation":
+      return { filename: `STATION_ROTATION_${id}.md`, persona: "@content", templateFile: "STATION_ROTATION_template.md" };
+    case "bell_ringer":
+      return { filename: `BELL_RINGER_${id}.md`, persona: "@content", templateFile: "BELL_RINGER_template.md" };
+    case "review_game":
+      return { filename: `REVIEW_GAME_${id}.md`, persona: "@assessor", templateFile: "REVIEW_GAME_template.md" };
+    case "graphic_organizer":
+      return { filename: `GRAPHIC_ORGANIZER_${id}.md`, persona: "@illustrator", templateFile: "GRAPHIC_ORGANIZER_template.md" };
+    default:
+      return { filename: `ARTIFACT_${id}.md`, persona: "@content", templateFile: "LESSON_5E_template.md" };
+  }
+}
+async function generateSingleArtifact(req) {
+  const {
+    artifactType,
+    topic,
+    lessonId,
+    lessonTitle,
+    pedagogy = "5e",
+    targetAge = "14-18 years old (High School / Early College)",
+    scaffoldingLevel = "balanced",
+    hardwarePlatform = ["MacBook Lab (macOS 14+ / Swift 6)"],
+    gradeLevel,
+    studentCount,
+    language = "Vietnamese",
+    extraContext,
+    config,
+    contextSot = {},
+    options = {},
+    onChunk
+  } = req;
+  const meta = getArtifactMetadata(artifactType, lessonId, pedagogy || config?.pedagogicalModel);
+  const displayTitle = lessonTitle || topic;
+  const loadedTemplate = loadCurriculumTemplate(meta.templateFile);
+  const templateContent = loadedTemplate || getDefaultFallbackTemplate(artifactType, displayTitle, lessonId || "ON_DEMAND");
+  const hwStr = hardwarePlatform.join(", ");
+  const selectedDevices = (config?.devices || (hardwarePlatform[0]?.toLowerCase().includes("paper") ? "paper-only" : "laptop")).toLowerCase();
+  const isBilingual = language.toLowerCase().includes("bilingual") || language.toLowerCase().includes("song");
+  const isVietnamese = !isBilingual && language.toLowerCase().includes("viet");
+  const langRule = isBilingual ? `1. AUTHORING LANGUAGE: Bilingual (Vietnamese - English). Headings and core conceptual definitions should be presented in Vietnamese with English technical terms in parentheses. Explanations and instructional text are in Vietnamese. Key code terms, comments, and challenge summaries are presented bilingually.` : isVietnamese ? `1. AUTHORING LANGUAGE: Vietnamese for all instructional text, explanations, questions, rubrics, and presenter notes. Programming code, syntax keywords, and standard API identifiers remain in standard English (with Vietnamese explanation comments/notes).` : `1. AUTHORING LANGUAGE: 100% English (Plan C Canonical Specification).`;
+  const isPaperOnly = selectedDevices === "paper-only" || hwStr.toLowerCase().includes("paper") || hwStr.toLowerCase().includes("print-ready");
+  const deviceRule = isPaperOnly ? `
+- \u{1F4C4} PAPER-ONLY / NO-DEVICE ENVIRONMENT: The learning space has NO computers or screens. All exercises, worksheets, task cards, exit tickets, and code analyses MUST be 100% printable. Provide write-in blank boxes, printed code snippets with line numbers, tracing tables, and physical manipulative instructions.` : selectedDevices === "tablet" || selectedDevices === "smartphone" ? `
+- \u{1F4F1} MOBILE/TABLET ENVIRONMENT: Activities should be optimized for touch interfaces and mobile/tablet sandboxes (e.g. Swift Playgrounds, Web IDEs, tap/touch interactions).` : `
+- \u{1F4BB} LAPTOP/DESKTOP ENVIRONMENT: Full keyboard, terminal, multi-file code editing, and browser developer tooling are available.`;
+  const classDynamicsRule = studentCount ? `
+- \u{1F465} CLASS SIZE LOGISTICS: Class has exactly ${studentCount} students. Structure group sizes, pair-programming pairs, station rotations, and material distribution to realistically accommodate ${studentCount} students without bottlenecks.` : "";
+  const scaffoldingRule = scaffoldingLevel === "foundation" ? `
+- \u{1FA9C} FOUNDATION SCAFFOLDING: High instructional support. Provide step-by-step numbered breakdowns, concrete real-world analogies, hints for every problem, scaffolded starter code/fill-in-the-blanks, and frequent check-for-understanding prompts.` : scaffoldingLevel === "advanced" ? `
+- \u{1F680} ADVANCED CHALLENGE: Minimal scaffolding. Focus on deeper system architecture, edge case handling, computational complexity, performance optimization, and open-ended extension challenges.` : `
+- \u2696\uFE0F BALANCED SCAFFOLDING: Balanced approach combining structured teacher guidance with independent inquiry and problem solving.`;
+  const extraContextRule = extraContext ? `
+- \u{1F3AF} CRITICAL USER INSTRUCTIONS (MANDATORY): "${extraContext}". You MUST directly reflect and satisfy every point of this user guidance in the generated artifact!` : "";
+  const artifactSpecializedPrompt = getArtifactSpecializedInvariants(artifactType, {
+    ...req,
+    studentCount});
+  const systemPrompt = `You are ${meta.persona}, an expert Curriculum & Pedagogical Specialist in the Curriculum OS Multi-Agent Team.
+Your task is to author a canonical, publication-grade learning artifact of type "${artifactType.toUpperCase()}".
+
+### CORE OPERATIONAL INVARIANTS:
+${langRule}
+2. NON-MOCK CODE INVARIANT: Any code snippet provided MUST be 100% syntactically valid, idiomatic, and executable without placeholders or fake functions.
+3. PEDAGOGICAL GROUNDING: Strictly align with the ${pedagogy.toUpperCase()} model, Bloom's Revised Taxonomy, and IEEE/ACM CS2023 guidelines.
+4. SCAFFOLDING LEVEL: "${scaffoldingLevel.toUpperCase()}".${scaffoldingRule}
+5. TARGET AUDIENCE: ${gradeLevel ? `Grade ${gradeLevel}, ` : ""}${targetAge} on ${hwStr}.${deviceRule}${classDynamicsRule}${extraContextRule}
+6. OUTPUT INTEGRITY: Output clean Markdown starting directly with YAML frontmatter. Do not wrap entire response in triple backticks.${artifactSpecializedPrompt}`;
+  const userPrompt = `### CONTEXT GROUND TRUTH:
+- Topic / Concept Domain: "${topic}"
+- Lesson ID: "${lessonId || "ON_DEMAND"}"
+- Artifact Title: "${displayTitle}"
+- Pedagogy: "${pedagogy.toUpperCase()}"
+- Scaffolding Level: "${scaffoldingLevel}"
+- Hardware Environment: "${hwStr}"
+${gradeLevel ? `- Target Grade Level: "${gradeLevel}"
+` : ""}${studentCount ? `- Class Size: "${studentCount} students"
+` : ""}- Target Language: "${language}"
+${selectedDevices ? `- Device Mode: "${selectedDevices}"
+` : ""}${extraContext ? `- User Specific Guidance & Requirements: "${extraContext}"
+` : ""}${config ? `- Full Task Config: ${JSON.stringify(config)}
+` : ""}
+${contextSot.framework ? `### SOT CURRICULUM FRAMEWORK:
+${contextSot.framework.slice(0, 1500)}
+` : ""}
+${contextSot.lessonPlan ? `### SOT CANONICAL LESSON PLAN:
+${contextSot.lessonPlan.slice(0, 1500)}
+` : ""}
+${contextSot.handout ? `### SOT STUDENT HANDOUT:
+${contextSot.handout.slice(0, 1e3)}
+` : ""}
+
+### MANDATORY CANONICAL TEMPLATE CONTRACT:
+Use the following reference template structure as the exact specification:
+
+${templateContent}
+
+### TASK INSTRUCTION:
+Generate the complete, thorough, publication-grade "${artifactType.toUpperCase()}" artifact for "${displayTitle}". Ensure all [REQUIRED] sections are fully developed with realistic, detailed pedagogical and technical content. Strictly follow the specialized invariants for "${artifactType.toUpperCase()}".`;
+  let accumulatedContent = "";
+  let accumulatedThought = "";
+  try {
+    const rawResult = await streamCurriculumAIInference(
+      [
+        { role: "system", content: systemPrompt },
+        { role: "user", content: userPrompt }
+      ],
+      userPrompt,
+      {
+        ...options,
+        systemPersona: systemPrompt
+      },
+      (chunk, type) => {
+        if (type === "thought") {
+          accumulatedThought += chunk;
+        } else if (type === "content") {
+          accumulatedContent += chunk;
+        }
+        if (onChunk) onChunk(chunk, type === "thought" ? "thought" : "content");
+      }
+    );
+    const { thought, content } = extractThoughtAndContent(rawResult);
+    return {
+      artifactType,
+      filename: meta.filename,
+      content: content || accumulatedContent,
+      persona: meta.persona,
+      thought: thought || accumulatedThought
+    };
+  } catch (error) {
+    throw createAiInferenceError({
+      errorCode: "ERR_AI_ALL_PROVIDERS_FAILED",
+      message: `Failed to generate single artifact ${artifactType}: ${error?.message || "Unknown error"}`,
+      rawError: error
+    });
+  }
+}
+function getArtifactSpecializedInvariants(type, req) {
+  const cfg = req.config || {};
+  const isPaperOnly = cfg.devices === "paper-only" || req.hardwarePlatform?.some((h) => h.toLowerCase().includes("paper"));
+  const studentCount = req.studentCount || "25";
+  switch (type) {
+    case "slide": {
+      const slideCount = cfg.slideCount || 10;
+      const presentationStyle = cfg.presentationStyle || "modern";
+      const presentationDuration = cfg.presentationDuration || 45;
+      const includeSpeakerNotes = cfg.includeSpeakerNotes !== false;
+      return `
+### \u{1F3AC} SLIDE PRESENTATION & MARP ARCHITECTURE INVARIANTS:
+1. **SLIDE COUNT & TIMING TARGET**:
+   - Generate EXACTLY ${slideCount} slides separated by \`---\` horizontal rules.
+   - Pacing: Target total duration is ${presentationDuration} minutes (~${Math.round(Number(presentationDuration) / Number(slideCount))} mins per slide).
+   - Visual Style: "${presentationStyle.toUpperCase()}". Maintain high visual clarity, contrasting accents, and executive polish.
+2. **STRICT CONCISENESS & 6x6 RULE (ABSOLUTELY NO TEXT WALLS)**:
+   - A slide is a VISUAL PROJECTION CANVAS, NOT a textbook or lesson plan!
+   - Maximum 4\u20136 bullet points per slide.
+   - Maximum 8\u201312 words per bullet point. Forbid dense multi-sentence paragraphs on the slide surface.
+3. **SPEAKER NOTES FOR ALL SPOKEN WORDS (<!-- Presenter Notes: ... -->)**:
+   ${includeSpeakerNotes ? "- MANDATORY: Every single slide MUST contain comprehensive presenter notes in `<!-- Presenter Notes: ... -->` at the bottom, giving the teacher the exact verbal talking points, analogies, and pacing tips." : "- Optional brief presenter notes."}
+4. **CLICK-TO-REVEAL SYSTEM**:
+   - Use \`<!-- clicks -->\` before bulleted lists (\`<ul>\` or \`<ol>\`) for incremental click-to-reveal.
+   - Use \`<!-- click -->\` before answers, code reveals, or key callouts.
+5. **2-COLUMN / SPLIT LAYOUT**:
+   - Use <div class="columns"><div>...</div><div>...</div></div> for side-by-side concept vs. code or problem vs. solution comparisons.
+6. **CONCISE CODE SNIPPETS**:
+   - Maximum 6\u201310 lines of clean code per snippet with inline comments. Never paste whole files.
+7. **MERMAID VISUALS**:
+   - Use Mermaid flowcharts or sequence diagrams for workflows and control loops.`;
+    }
+    case "tiered_practice": {
+      const techStack = cfg.techStack || (req.hardwarePlatform?.[0] || "Modern Programming Language");
+      const includeUnitTests = cfg.includeUnitTests !== false;
+      return `
+### \u{1FA9C} TIERED PRACTICE ARCHITECTURE INVARIANTS (3-TIER ADAPTIVE):
+- Target Technology Stack: "${techStack}"
+${includeUnitTests ? "- Automated Testing: Include explicit executable Unit Tests / Assertions for verifying Bronze, Silver, and Gold tiers." : ""}
+1. **3 EXPLICIT RIGOR TIERS**:
+   - **\u{1F949} Tier 1 (Bronze / C\u01A1 b\u1EA3n)**: 70% starter boilerplate / 30% fill-in. Direct recall, scaffolded fill-in-the-blanks, single-concept recognition with starter hints.
+   - **\u{1F948} Tier 2 (Silver / Ti\xEAu chu\u1EA9n)**: 30% starter boilerplate / 70% implementation. Independent multi-step problem solving, bug identification, synthesis of 2+ concepts.
+   - **\u{1F947} Tier 3 (Gold / Th\u1EED th\xE1ch)**: 0% code / open architecture. Edge case handling, algorithmic optimization, open-ended architectural design or extension.
+2. **COMPLETE WORKED SOLUTIONS & ANSWER KEYS**:
+   - Provide step-by-step worked solutions for every problem across all 3 tiers.
+3. **SELF-DIAGNOSTIC RUBRIC**:
+   - Include a clear student rubric with criteria for when a student is ready to level up from Bronze \u2794 Silver \u2794 Gold.`;
+    }
+    case "exit_ticket": {
+      const questionCount = cfg.questionCount || 3;
+      const diagnosticFocus = cfg.diagnosticFocus || "misconceptions";
+      return `
+### \u{1F39F}\uFE0F EXIT TICKET ARCHITECTURE INVARIANTS:
+1. **EXACTLY ${questionCount} TARGETED ITEMS (3\u20135 MINUTE DURATION)**:
+   - Item 1: Quick diagnostic checking mastery of the core objective.
+   - Item 2: Application with diagnostic trap focusing on: "${diagnosticFocus}".
+   - Item 3: Metacognitive self-check (Confidence rating 1\u20135 + "Explain what is still fuzzy").
+2. **TEACHER DIAGNOSTIC INTERVENTION GUIDE**:
+   - Provide a quick lookup table: "If student chooses/writes X \u2794 Misconception is Y \u2794 Quick remedy is Z".${isPaperOnly ? "\n3. **PRINTABLE CUT-OUT FORMAT**: Include student name/date line and cut-border dashed line." : ""}`;
+    }
+    case "quiz": {
+      const questionCount = cfg.questionCount || 5;
+      const questionTypes = Array.isArray(cfg.questionTypes) ? cfg.questionTypes.join(", ") : cfg.questionTypes || "multiple_choice";
+      const diagnosticFocus = cfg.diagnosticFocus || "balanced";
+      return `
+### \u{1F4DD} BLOOM-ALIGNED QUIZ ARCHITECTURE INVARIANTS:
+1. **EXACTLY ${questionCount} QUESTIONS (${questionTypes.toUpperCase()})**:
+   - Diagnostic emphasis: "${diagnosticFocus}".
+   - 40% Remember/Understand (Conceptual foundations).
+   - 40% Apply/Analyze (Bug finding, code tracing, scenario application).
+   - 20% Evaluate/Create (Algorithmic reasoning, trade-off evaluation).
+2. **HIGH-QUALITY DISTRACTORS WITH RATIONALE**:
+   - For every multiple choice item, explain WHY each incorrect option is a plausible misconception and WHY the key is correct.
+3. **COMPLETE ANSWER KEY & SCORING RUBRIC**:
+   - Explicit point distribution, partial credit guidelines, and sample ideal answers for open-ended questions.`;
+    }
+    case "task_cards": {
+      const cardCount = cfg.cardCount || 12;
+      const cardUsage = cfg.cardUsage || "stations";
+      return `
+### \u{1F4CB} TASK CARDS ARCHITECTURE INVARIANTS:
+1. **SET OF EXACTLY ${cardCount} NUMBERED CARDS (Optimized for ${cardUsage.toUpperCase()})**:
+   - Clearly mark each card: Card # (1 to ${cardCount}), Difficulty (Foundation / Standard / Challenge), and Target Skill.
+2. **STUDENT RECORDING SHEET (B\u1EA2NG GHI \u0110\xC1P \xC1N)**:
+   - Include a structured printable grid where students record answers for Cards 1\u2013${cardCount}.
+3. **TEACHER MASTER KEY**:
+   - Quick reference key with verified answers and explanations.${isPaperOnly ? "\n4. **PRINT-READY CARD BORDERS**: Layout with clean visual borders ready for physical printing and cutting." : ""}`;
+    }
+    case "graphic_organizer": {
+      const diagramType = cfg.diagramType || "concept_map";
+      const includeFillIn = cfg.includeFillInExercise !== false;
+      return `
+### \u{1F4CA} GRAPHIC ORGANIZER ARCHITECTURE INVARIANTS:
+1. **VISUAL MODEL TYPE: "${diagramType.toUpperCase()}"**:
+   - Structure a clear cognitive thinking tool: Concept Map, Flowchart, Venn Diagram, Hierarchy Tree, or Cause-Effect Matrix.
+2. **VALID MERMAID SYNTAX**:
+   - Embed complete, 100% syntactically correct Mermaid diagrams showing the knowledge structure.
+3. **ACTIVE STUDENT INTERACTION PROMPTS**:
+   ${includeFillIn ? "- Include interactive fill-in-the-blank nodes and connection articulation challenges." : "- Include synthesis and reflection prompts based on the visual model."}`;
+    }
+    case "choice_board": {
+      const gridSize = cfg.gridSize || "3x3";
+      const completionRule = cfg.completionRule || "row_column_diagonal";
+      return `
+### \u{1F3AF} CHOICE BOARD ARCHITECTURE INVARIANTS (UDL ${gridSize.toUpperCase()} MATRIX):
+1. **${gridSize.toUpperCase()} MENU (UDL MULTIPLE MEANS OF EXPRESSION)**:
+   - Option tasks spanning practical coding, architectural diagrams, analytical writing, and real-world scenarios.
+2. **COMPLETION CONTRACT: "${completionRule.toUpperCase()}"**:
+   - Explicit rule (e.g. Tic-Tac-Toe 3-in-a-row/column/diagonal, or Point Bounty system).
+3. **UNIFIED EVALUATION RUBRIC**:
+   - Consistent grading criteria applicable across all task choices on the board.`;
+    }
+    case "station_rotation": {
+      const stationCount = cfg.stationCount || 3;
+      const stationDuration = cfg.stationDuration || 15;
+      return `
+### \u{1F504} STATION ROTATION ARCHITECTURE INVARIANTS:
+1. **EXACTLY ${stationCount} STATIONS SCALED FOR ${studentCount} STUDENTS**:
+   - Group size: ~${Math.ceil(Number(studentCount) / Number(stationCount)) || 7} students per group.
+   - Distinct station roles: Teacher-Led Small Group, Independent Practical Lab, Collaborative / Unplugged Peer Challenge.
+2. **TIMING & TRANSITIONS (${stationDuration} MINS/STATION)**:
+   - ${stationDuration} minutes per station + 3-minute structured rotation protocol.
+3. **STATION DELIVERABLES & ACCOUNTABILITY**:
+   - Clear check-in deliverable required at each station to ensure on-task accountability.`;
+    }
+    case "act":
+    case "codelab":
+    case "science_lab": {
+      const techStack = cfg.techStack || (req.hardwarePlatform?.[0] || "Modern Programming Language");
+      const includeUnitTests = cfg.includeUnitTests !== false;
+      return `
+### \u{1F4BB} HANDS-ON LAB & CODE ACTIVITY ARCHITECTURE INVARIANTS:
+- Technology Stack: "${techStack}"
+${includeUnitTests ? "- Unit Testing: Provide automated assertions or test runner checks." : ""}
+1. **100% RUNNABLE CODE / RIGOROUS PROCEDURE**:
+   - Absolutely no fake APIs, mock functions, or non-executable pseudocode.
+2. **STRUCTURED LAB PHASES**:
+   - Objective & Environmental Prerequisites.
+   - Starter Skeleton Code with clear \`// TODO [Student Task]\` comments.
+   - Step-by-step Guided Challenges (Level 1 \u2794 Level 2 \u2794 Level 3).
+   - Automated Verification / Test Cases.
+   - Complete Reference Solution with design explanation.`;
+    }
+    case "bell_ringer":
+      return `
+### \u{1F514} BELL RINGER ARCHITECTURE INVARIANTS (3\u20135 MIN WARM-UP):
+1. **3 QUICK HOOK QUESTIONS**:
+   - 2 rapid-fire recall questions activating previous knowledge.
+   - 1 curiosity hook question bridging into today's core topic.
+2. **60-SECOND TEACHER REVIEW KEY**:
+   - Quick-glance answer key for instant whole-class review.`;
+    case "review_game":
+      return `
+### \u{1F3AE} REVIEW GAME ARCHITECTURE INVARIANTS:
+1. **GAMIFIED STRUCTURE**:
+   - Jeopardy-style board (3\u20134 Categories x 3 Point Values: 100 / 200 / 300) OR 3-Round Interactive Trivia.
+2. **CLEAR RULES & TEAM DYNAMICS**:
+   - Team scoring rules, buzz-in protocol, and tie-breaker challenge.
+3. **COMPLETE QUESTION & ANSWER DECK**:
+   - Verified answers and point values for the host/teacher.`;
+    case "guide": {
+      const lessonDuration = cfg.lessonDuration || 90;
+      return `
+### \u{1F4D6} TEACHER GUIDE ARCHITECTURE INVARIANTS (${lessonDuration} MINS LESSON):
+1. **MINUTE-BY-MINUTE PACING TIMELINE**:
+   - Pacing broken down for ${lessonDuration} minutes (Hook, Modeling, Guided Practice, Independent Practice, Debrief).
+2. **SOCRATIC QUESTIONS & PROMPTS**:
+   - Cold-call questions with anticipated student misconceptions and remediation scripts.
+3. **DIFFERENTIATION STRATEGIES**:
+   - Specific adaptations for students needing support vs. high-flyers needing extension.`;
+    }
+    case "worksheet":
+    case "handout":
+      return `
+### \u{1F4D1} WORKSHEET / HANDOUT ARCHITECTURE INVARIANTS:
+1. **I DO \u2794 WE DO \u2794 YOU DO SCAFFOLDING**:
+   - Part 1 (I Do): Fully worked and annotated example.
+   - Part 2 (We Do): Guided problem with fill-in hints and scaffolding scaffolds.
+   - Part 3 (You Do): Independent mastery challenge.
+2. **SELF-CHECK RUBRIC**:
+   - End-of-worksheet self-evaluation checklist.${isPaperOnly ? "\n3. **PRINTABLE WORKSPACES**: Include spacious, clean write-in boxes and workspace for calculations/code." : ""}`;
+    case "rubric": {
+      const rubricScale = cfg.rubricScale || "4_levels";
+      return `
+### \u{1F4CA} ANALYTIC RUBRIC ARCHITECTURE INVARIANTS (${rubricScale.toUpperCase()} SCALE):
+1. **RIGOROUS PROFICIENCY LEVELS**:
+   - 4 Proficiency Levels: Level 4 (Exemplary) | Level 3 (Proficient) | Level 2 (Developing) | Level 1 (Beginning).
+2. **CONCRETE OBSERVABLE CRITERIA**:
+   - Each cell MUST describe concrete, observable behavioral evidence, not vague words like "good" or "average".`;
+    }
+    case "glossary":
+      return `
+### \u{1F4DA} TECHNICAL GLOSSARY ARCHITECTURE INVARIANTS:
+1. **COMPREHENSIVE TERM PROFILES**:
+   - For every key term: Technical Definition, Real-world Analogy, Code Syntax Example, and Common Misconception.`;
+    case "bom":
+      return `
+### \u{1F4E6} BILL OF MATERIALS (BOM) ARCHITECTURE INVARIANTS:
+1. **CLASS-SCALED INVENTORY FOR ${studentCount} STUDENTS**:
+   - Exact quantities calculated for ${studentCount} students.
+   - Component specifications, estimated unit cost, and affordable alternatives.`;
+    case "lesson": {
+      const lessonDuration = cfg.lessonDuration || 90;
+      const pedagogicalModel = cfg.pedagogicalModel || req.pedagogy || "5e";
+      return `
+### \u{1F393} CANONICAL LESSON PLAN INVARIANTS (${pedagogicalModel.toUpperCase()} MODEL, ${lessonDuration} MINS):
+1. **A. LESSON DESIGN PLAN**:
+   - Learning Objectives (Bloom-aligned) & Observable Student Evidence.
+   - Activity Sequence mapping every phase with timing totaling ${lessonDuration} minutes.
+   - Resource Map & Assessment Map with explicit Artifact Contracts.
+2. **B. LESSON FLOW**:
+   - Detailed teacher moves, student actions, scripted key questions, and check-for-understanding points for every activity phase.`;
+    }
+    default:
+      return "";
+  }
+}
+function getDefaultFallbackTemplate(type, title, id) {
+  const upperType = type.toUpperCase();
+  return `---
+id: "${id}"
+title: "${title}"
+type: "${upperType}"
+version: "1.0.0"
+date: "${(/* @__PURE__ */ new Date()).toISOString().split("T")[0]}"
+---
+
+# ${title}
+
+## 1. Overview & Learning Objectives
+<!-- [REQUIRED] State 2-3 measurable, Bloom-aligned learning objectives -->
+
+## 2. Core Pedagogical Content
+<!-- [REQUIRED] Provide the core educational substance, questions, problems, and diagrams -->
+
+## 3. Practice & Differentiation
+<!-- [REQUIRED] Tiered support, worked examples, and challenges -->
+
+## 4. Assessment & Answer Key
+<!-- [REQUIRED] Complete solutions, rubrics, and diagnostic teacher feedback -->
+`;
+}
+
+// src/workflow/workflows/singleArtifactWorkflow.ts
+async function executeSingleArtifactStep(request) {
+  "use step";
+  const t0 = Date.now();
+  console.log(`  \u23F3 [Step: Single Artifact] Generating ${request.artifactType.toUpperCase()} for "${request.topic.slice(0, 35)}"...`);
+  const res = await withRateLimitBackoff({
+    stepName: `generate-single-artifact-${request.artifactType}-${(request.topic || "topic").slice(0, 20)}`,
+    fn: async () => generateSingleArtifact(request)
+  });
+  console.log(`  \u2705 [Step: Single Artifact] Done in ${((Date.now() - t0) / 1e3).toFixed(1)}s (File: "${res.filename}")`);
+  return res;
+}
+async function generateSingleArtifactWorkflow(request) {
+  "use workflow";
+  return executeSingleArtifactStep(request);
+}
+
 exports.DEFAULT_GATE_SETTINGS = DEFAULT_GATE_SETTINGS;
 exports.approvalPayloadSchema = approvalPayloadSchema;
+exports.executeSingleArtifactStep = executeSingleArtifactStep;
 exports.gateModeFor = gateModeFor;
 exports.generateActivityStep = generateActivityStep;
 exports.generateCodeLabStep = generateCodeLabStep;
@@ -5249,6 +6394,7 @@ exports.generateMasterLessonStep = generateMasterLessonStep;
 exports.generateMilestoneWorkflow = generateMilestoneWorkflow;
 exports.generateRoadmapWorkflow = generateRoadmapWorkflow;
 exports.generateSelfLabStep = generateSelfLabStep;
+exports.generateSingleArtifactWorkflow = generateSingleArtifactWorkflow;
 exports.generateSlidesStep = generateSlidesStep;
 exports.generateTeacherGuideStep = generateTeacherGuideStep;
 exports.generateWorksheetStep = generateWorksheetStep;