@thanh01.pmt/curriculum-kit 1.0.0 → 1.0.2

package/dist/workflow/index.mjs

@@ -1,18 +1,127 @@
+import fs from 'fs';
+import path from 'path';
 import { generateObject } from 'ai';
 import { createGoogleGenerativeAI } from '@ai-sdk/google';
 import { createOpenAI } from '@ai-sdk/openai';
 import { createDeepSeek } from '@ai-sdk/deepseek';
-import fs from 'fs';
-import path from 'path';
 import { z } from 'zod';
 import * as workflowPkg from 'workflow';
 import { getStepMetadata, RetryableError, sleep } from 'workflow';
 import fs2 from 'fs/promises';
 import { Octokit } from '@octokit/rest';
 import { createClient } from '@supabase/supabase-js';
+import { fileURLToPath } from 'url';
+import 'crypto';
 
-// 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];
   }
@@ -121,8 +230,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",
@@ -5211,6 +5883,201 @@ async function generateRoadmapWorkflow(input) {
   };
 }
 
-export { DEFAULT_GATE_SETTINGS, approvalPayloadSchema, gateModeFor, generateActivityStep, generateCodeLabStep, generateDiagnosticQuizStep, generateExtensionStep, generateHandoutStep, generateMasterLessonStep, generateMilestoneWorkflow, generateRoadmapWorkflow, generateSelfLabStep, generateSlidesStep, generateTeacherGuideStep, generateWorksheetStep, judgeMasterLessonStep, judgeSatelliteStep, lessonApprovalHook, parseGateSettings, publishToGitStep, publishToSupabaseStep, repairMasterLessonStep, resolveGateSettings, saveMilestoneToWorkspaceStep, withRateLimitBackoff };
+// src/services/singleArtifactService.ts
+init_streamRunner();
+
+// src/services/lessonProductionService.ts
+init_streamRunner();
+init_errors();
+
+// src/services/lessonProductionService.ts
+var __filename$1 = typeof import.meta?.url === "string" ? fileURLToPath(import.meta.url) : "";
+var _resolvedDir = __filename$1 ? path.dirname(__filename$1) : typeof __dirname !== "undefined" ? __dirname : process.cwd();
+function loadCurriculumTemplate(templateName) {
+  const candidatePaths = [
+    path.resolve(process.cwd(), "_templates", templateName),
+    path.resolve(process.cwd(), "packages/curriculum-kit/docs/refs/templates", templateName),
+    path.resolve(process.cwd(), "docs/refs/templates", templateName),
+    path.resolve(_resolvedDir, "../docs/refs/templates", templateName),
+    path.resolve(_resolvedDir, "../../docs/refs/templates", templateName),
+    path.resolve(_resolvedDir, "../../../docs/refs/templates", templateName),
+    path.resolve(_resolvedDir, "../../../../the-ultimate-curriculum-agent-os/_templates", templateName)
+  ];
+  for (const p of candidatePaths) {
+    if (fs.existsSync(p)) {
+      try {
+        return fs.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) {
+  const id = lessonId || "ON_DEMAND";
+  switch (type) {
+    case "lesson":
+      return { filename: `LESSON_${id}.md`, persona: "@content", templateFile: "LESSON_5E_template.md" };
+    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" };
+  }
+}
+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)"],
+    contextSot = {},
+    options = {},
+    onChunk
+  } = req;
+  const meta = getArtifactMetadata(artifactType, lessonId);
+  const templateContent = loadCurriculumTemplate(meta.templateFile);
+  const displayTitle = lessonTitle || topic;
+  const hwStr = hardwarePlatform.join(", ");
+  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:
+1. AUTHORING LANGUAGE: 100% English (Plan C Canonical Specification).
+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()}" (Foundation: High support & concrete analogies; Balanced: Application & problem solving; Advanced: Systems architecture & concurrency invariants).
+5. TARGET AUDIENCE: ${targetAge} on ${hwStr}.
+6. OUTPUT INTEGRITY: Output clean Markdown starting directly with YAML frontmatter. Do not wrap entire response in triple backticks.`;
+  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}"
+
+${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 || `---
+id: "${lessonId || "ON_DEMAND"}"
+title: "${displayTitle}"
+type: "${artifactType.toUpperCase()}"
+---
+# ${displayTitle}`}
+
+### TASK INSTRUCTION:
+Generate the complete, thorough, production-grade "${artifactType.toUpperCase()}" artifact for "${displayTitle}". Ensure all [REQUIRED] sections are fully developed with realistic, detailed engineering content.`;
+  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
+    });
+  }
+}
+
+// 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);
+}
+
+export { DEFAULT_GATE_SETTINGS, approvalPayloadSchema, executeSingleArtifactStep, gateModeFor, generateActivityStep, generateCodeLabStep, generateDiagnosticQuizStep, generateExtensionStep, generateHandoutStep, generateMasterLessonStep, generateMilestoneWorkflow, generateRoadmapWorkflow, generateSelfLabStep, generateSingleArtifactWorkflow, generateSlidesStep, generateTeacherGuideStep, generateWorksheetStep, judgeMasterLessonStep, judgeSatelliteStep, lessonApprovalHook, parseGateSettings, publishToGitStep, publishToSupabaseStep, repairMasterLessonStep, resolveGateSettings, saveMilestoneToWorkspaceStep, withRateLimitBackoff };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map