@thanh01.pmt/research-kit 1.2.4 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (74) hide show
  1. package/dist/academic/index.cjs +122 -0
  2. package/dist/academic/index.cjs.map +1 -1
  3. package/dist/academic/index.d.cts +27 -4
  4. package/dist/academic/index.d.ts +27 -4
  5. package/dist/academic/index.js +2 -1
  6. package/dist/agent/index.cjs +4277 -0
  7. package/dist/agent/index.cjs.map +1 -0
  8. package/dist/agent/index.d.cts +10 -0
  9. package/dist/agent/index.d.ts +10 -0
  10. package/dist/agent/index.js +10 -0
  11. package/dist/agent/index.js.map +1 -0
  12. package/dist/{catalogBuilder-B4eiLS_S.d.cts → catalogBuilder-BBCa9jqI.d.cts} +2 -2
  13. package/dist/{catalogBuilder-BNB_gaWP.d.ts → catalogBuilder-D-UiM37y.d.ts} +2 -2
  14. package/dist/chunk-2GBXVPOQ.js +3 -0
  15. package/dist/{chunk-J3VCGH7Z.js.map → chunk-2GBXVPOQ.js.map} +1 -1
  16. package/dist/chunk-2RMBLKP5.js +581 -0
  17. package/dist/chunk-2RMBLKP5.js.map +1 -0
  18. package/dist/{chunk-2XIEWCUE.js → chunk-32B5PVTQ.js} +2 -2
  19. package/dist/{chunk-2XIEWCUE.js.map → chunk-32B5PVTQ.js.map} +1 -1
  20. package/dist/{chunk-YICMTZS5.js → chunk-4O3FXMXO.js} +171 -3
  21. package/dist/chunk-4O3FXMXO.js.map +1 -0
  22. package/dist/chunk-LDCZ33AC.js +3 -0
  23. package/dist/chunk-LDCZ33AC.js.map +1 -0
  24. package/dist/{chunk-GK5KI5PB.js → chunk-MFRQ2VJZ.js} +63 -44
  25. package/dist/chunk-MFRQ2VJZ.js.map +1 -0
  26. package/dist/chunk-RAMDHDRJ.js +1931 -0
  27. package/dist/chunk-RAMDHDRJ.js.map +1 -0
  28. package/dist/{chunk-SAHBBO3U.js → chunk-RYLZYZRF.js} +4 -580
  29. package/dist/chunk-RYLZYZRF.js.map +1 -0
  30. package/dist/chunk-SHBDLP64.js +125 -0
  31. package/dist/chunk-SHBDLP64.js.map +1 -0
  32. package/dist/chunk-TYQEC24G.js +3 -0
  33. package/dist/chunk-TYQEC24G.js.map +1 -0
  34. package/dist/{chunk-KXJDQBSJ.js → chunk-UHKDJZNL.js} +11 -4
  35. package/dist/chunk-UHKDJZNL.js.map +1 -0
  36. package/dist/config/index.d.cts +1 -1
  37. package/dist/config/index.d.ts +1 -1
  38. package/dist/evidence/index.cjs +9 -2
  39. package/dist/evidence/index.cjs.map +1 -1
  40. package/dist/evidence/index.d.cts +2 -2
  41. package/dist/evidence/index.d.ts +2 -2
  42. package/dist/evidence/index.js +3 -2
  43. package/dist/harvester/index.cjs +168 -1
  44. package/dist/harvester/index.cjs.map +1 -1
  45. package/dist/harvester/index.d.cts +5 -161
  46. package/dist/harvester/index.d.ts +5 -161
  47. package/dist/harvester/index.js +4 -2
  48. package/dist/index-CGa7lf3L.d.ts +764 -0
  49. package/dist/{index-9rDiFuR4.d.cts → index-CxoD81QN.d.cts} +1 -1
  50. package/dist/{index-9rDiFuR4.d.ts → index-CxoD81QN.d.ts} +1 -1
  51. package/dist/index-DrjfrbGw.d.cts +764 -0
  52. package/dist/index.cjs +2411 -144
  53. package/dist/index.cjs.map +1 -1
  54. package/dist/index.d.cts +11 -174
  55. package/dist/index.d.ts +11 -174
  56. package/dist/index.js +34 -12
  57. package/dist/index.js.map +1 -1
  58. package/dist/{literatureReview-DOzgm9Q2.d.ts → literatureReview-Bn2iEGRO.d.ts} +1 -1
  59. package/dist/{literatureReview-BwidpYJo.d.cts → literatureReview-Bvlqk4DB.d.cts} +1 -1
  60. package/dist/pipeline/index.cjs +68 -43
  61. package/dist/pipeline/index.cjs.map +1 -1
  62. package/dist/pipeline/index.d.cts +5 -4
  63. package/dist/pipeline/index.d.ts +5 -4
  64. package/dist/pipeline/index.js +4 -3
  65. package/dist/socialPulseHarvester-CN4MwrpY.d.cts +204 -0
  66. package/dist/socialPulseHarvester-IbdT3zD1.d.ts +204 -0
  67. package/dist/{webScraper-CAQjE46m.d.cts → webScraper-BVvNW4yj.d.cts} +1 -1
  68. package/dist/{webScraper-CXIpvyA6.d.ts → webScraper-C9pB5Rgd.d.ts} +1 -1
  69. package/package.json +6 -1
  70. package/dist/chunk-GK5KI5PB.js.map +0 -1
  71. package/dist/chunk-J3VCGH7Z.js +0 -3
  72. package/dist/chunk-KXJDQBSJ.js.map +0 -1
  73. package/dist/chunk-SAHBBO3U.js.map +0 -1
  74. package/dist/chunk-YICMTZS5.js.map +0 -1
package/dist/index.cjs CHANGED
@@ -258,6 +258,126 @@ var AcademicSearchEngine = class {
258
258
  }
259
259
  };
260
260
 
261
+ // src/academic/openAlexClient.ts
262
+ function cleanCrossrefAbstract(rawAbstract) {
263
+ if (!rawAbstract || typeof rawAbstract !== "string") return void 0;
264
+ const cleaned = rawAbstract.replace(/<\/?jats:[^>]+>/gi, " ").replace(/<\/?[^>]+>/g, " ").replace(/\s+/g, " ").trim();
265
+ return cleaned.length > 0 ? cleaned : void 0;
266
+ }
267
+ var OpenAlexClient = class {
268
+ mailto;
269
+ constructor(options = {}) {
270
+ this.mailto = options.mailto || "team@orchable.app";
271
+ }
272
+ async searchWorks(query, options = {}) {
273
+ const limit = options.limit ?? 5;
274
+ const papers = [];
275
+ const seenTitles = /* @__PURE__ */ new Set();
276
+ const pushUnique = (paper) => {
277
+ const norm = paper.title.toLowerCase().replace(/[^a-z0-9\u00C0-\u1EF9]+/g, "");
278
+ if (!norm || seenTitles.has(norm)) return;
279
+ seenTitles.add(norm);
280
+ papers.push(paper);
281
+ };
282
+ try {
283
+ const filters = [];
284
+ if (options.yearRange) {
285
+ const match = options.yearRange.match(/^(\d{4})-(\d{4})$/);
286
+ if (match) {
287
+ filters.push(`publication_year:${match[1]}-${match[2]}`);
288
+ } else if (/^\d{4}$/.test(options.yearRange)) {
289
+ filters.push(`publication_year:${options.yearRange}`);
290
+ }
291
+ }
292
+ if (options.openAccessOnly) {
293
+ filters.push("is_oa:true");
294
+ }
295
+ const params = new URLSearchParams({
296
+ search: query,
297
+ "per-page": String(limit)
298
+ });
299
+ if (filters.length > 0) {
300
+ params.set("filter", filters.join(","));
301
+ }
302
+ const res = await fetch(`https://api.openalex.org/works?${params.toString()}`, {
303
+ headers: {
304
+ "User-Agent": `OrchableResearchKit/1.3 (mailto:${this.mailto})`
305
+ },
306
+ signal: AbortSignal.timeout(7e3)
307
+ });
308
+ if (res.ok) {
309
+ const data = await res.json();
310
+ if (Array.isArray(data?.results)) {
311
+ for (const item of data.results) {
312
+ const abstractText = reconstructOpenAlexAbstract(item.abstract_inverted_index);
313
+ const concepts = Array.isArray(item.concepts) ? item.concepts.slice(0, 4).map((c) => c.display_name).filter(Boolean) : ["Computer Science"];
314
+ const cleanDoi = item.doi ? String(item.doi).replace(/^https?:\/\/doi\.org\//i, "") : void 0;
315
+ pushUnique({
316
+ id: item.id || `oa-${Math.random().toString(36).slice(2, 8)}`,
317
+ title: item.title || item.display_name || "Untitled",
318
+ abstract: abstractText,
319
+ authors: Array.isArray(item.authorships) ? item.authorships.map((a) => a.author?.display_name).filter(Boolean) : [],
320
+ year: item.publication_year,
321
+ citationCount: item.cited_by_count || 0,
322
+ venue: item.primary_location?.source?.display_name || void 0,
323
+ doi: cleanDoi,
324
+ url: item.doi || item.primary_location?.landing_page_url || item.id,
325
+ pdfUrl: item.open_access?.oa_url || item.primary_location?.pdf_url || void 0,
326
+ fieldsOfStudy: concepts.length > 0 ? concepts : ["Computer Science"]
327
+ });
328
+ }
329
+ }
330
+ }
331
+ } catch (e) {
332
+ console.warn("[OpenAlexClient] OpenAlex request failed:", e?.message || e);
333
+ }
334
+ if (papers.length < limit && options.includeCrossrefFallback !== false) {
335
+ try {
336
+ const remaining = limit - papers.length;
337
+ const params = new URLSearchParams({
338
+ query,
339
+ rows: String(remaining),
340
+ mailto: this.mailto
341
+ });
342
+ const res = await fetch(`https://api.crossref.org/works?${params.toString()}`, {
343
+ headers: {
344
+ "User-Agent": `OrchableResearchKit/1.3 (mailto:${this.mailto})`
345
+ },
346
+ signal: AbortSignal.timeout(7e3)
347
+ });
348
+ if (res.ok) {
349
+ const data = await res.json();
350
+ const items = data?.message?.items;
351
+ if (Array.isArray(items)) {
352
+ for (const item of items) {
353
+ const title = Array.isArray(item.title) ? item.title[0] : item.title;
354
+ if (!title) continue;
355
+ const year = item.published?.["date-parts"]?.[0]?.[0] || item["published-print"]?.["date-parts"]?.[0]?.[0] || item["published-online"]?.["date-parts"]?.[0]?.[0];
356
+ const authors = Array.isArray(item.author) ? item.author.map((a) => [a.given, a.family].filter(Boolean).join(" ").trim()).filter(Boolean) : [];
357
+ const doi = item.DOI ? String(item.DOI) : void 0;
358
+ pushUnique({
359
+ id: doi ? `crossref-${doi}` : `cr-${Math.random().toString(36).slice(2, 8)}`,
360
+ title: String(title),
361
+ abstract: cleanCrossrefAbstract(item.abstract),
362
+ authors,
363
+ year: typeof year === "number" ? year : void 0,
364
+ citationCount: Number(item["is-referenced-by-count"]) || 0,
365
+ venue: Array.isArray(item["container-title"]) ? item["container-title"][0] : void 0,
366
+ doi,
367
+ url: item.URL || (doi ? `https://doi.org/${doi}` : void 0),
368
+ fieldsOfStudy: Array.isArray(item.subject) && item.subject.length > 0 ? item.subject.slice(0, 3) : ["Academic"]
369
+ });
370
+ }
371
+ }
372
+ }
373
+ } catch (e) {
374
+ console.warn("[OpenAlexClient] Crossref fallback failed:", e?.message || e);
375
+ }
376
+ }
377
+ return papers.slice(0, limit);
378
+ }
379
+ };
380
+
261
381
  // src/academic/cs2023Taxonomy.ts
262
382
  var CSTA_K12_STRANDS = {
263
383
  CS: {
@@ -765,7 +885,7 @@ var MultiSourceSearchEngine = class {
765
885
  if (adapter && (!preferred || preferred === "custom")) {
766
886
  try {
767
887
  const customResults = await adapter.search(query, { limit, domainFilter: options.domainFilter });
768
- if (Array.isArray(customResults) && customResults.length > 0) {
888
+ if (Array.isArray(customResults)) {
769
889
  return customResults.map((r) => ({
770
890
  title: r.title,
771
891
  url: r.url,
@@ -2698,10 +2818,183 @@ var StemResourceResearcher = class {
2698
2818
  }
2699
2819
  };
2700
2820
 
2821
+ // src/harvester/socialPulseHarvester.ts
2822
+ var SocialPulseHarvester = class {
2823
+ constructor(searchEngine = new MultiSourceSearchEngine()) {
2824
+ this.searchEngine = searchEngine;
2825
+ }
2826
+ async harvest(topic, options = {}) {
2827
+ const recencyDays = Math.max(1, options.recencyDays ?? 30);
2828
+ const limitPerPlatform = options.limitPerPlatform ?? 4;
2829
+ const cutoffMs = Date.now() - recencyDays * 24 * 60 * 60 * 1e3;
2830
+ const cutoffUnixSec = Math.floor(cutoffMs / 1e3);
2831
+ const cutoffIsoDate = new Date(cutoffMs).toISOString().slice(0, 10);
2832
+ const items = [];
2833
+ const seenUrls = /* @__PURE__ */ new Set();
2834
+ const pushUnique = (item) => {
2835
+ const normUrl = item.url.trim().replace(/\/$/, "");
2836
+ if (!normUrl || seenUrls.has(normUrl)) return;
2837
+ seenUrls.add(normUrl);
2838
+ items.push(item);
2839
+ };
2840
+ const tasks = [];
2841
+ if (options.includeHackerNews !== false) {
2842
+ tasks.push(
2843
+ (async () => {
2844
+ try {
2845
+ const params = new URLSearchParams({
2846
+ query: topic,
2847
+ tags: "story",
2848
+ numericFilters: `created_at_i>${cutoffUnixSec}`,
2849
+ hitsPerPage: String(limitPerPlatform)
2850
+ });
2851
+ const res = await fetch(`https://hn.algolia.com/api/v1/search?${params.toString()}`, {
2852
+ headers: { "User-Agent": "OrchableResearchKit/1.3" },
2853
+ signal: AbortSignal.timeout(6500)
2854
+ });
2855
+ if (res.ok) {
2856
+ const data = await res.json();
2857
+ if (Array.isArray(data?.hits)) {
2858
+ for (const hit of data.hits) {
2859
+ const points = Number(hit.points) || 0;
2860
+ const comments = Number(hit.num_comments) || 0;
2861
+ const hnUrl = `https://news.ycombinator.com/item?id=${hit.objectID}`;
2862
+ const targetUrl = hit.url || hnUrl;
2863
+ const score = Math.min(10, Math.max(4, Math.round(4 + Math.log10(points + comments + 1) * 2)));
2864
+ pushUnique({
2865
+ id: `hn-${hit.objectID}`,
2866
+ platform: "hackernews",
2867
+ title: String(hit.title || "HackerNews Discussion"),
2868
+ url: targetUrl,
2869
+ snippet: `${hit.title} (${points} pts, ${comments} comments on HN: ${hnUrl})`,
2870
+ author: hit.author,
2871
+ createdAt: hit.created_at,
2872
+ engagementScore: score,
2873
+ rawMetrics: { points, comments }
2874
+ });
2875
+ }
2876
+ }
2877
+ }
2878
+ } catch (e) {
2879
+ console.warn("[SocialPulseHarvester] HackerNews query failed:", e?.message || e);
2880
+ }
2881
+ })()
2882
+ );
2883
+ }
2884
+ if (options.includeGitHub !== false) {
2885
+ tasks.push(
2886
+ (async () => {
2887
+ try {
2888
+ const q = `${topic} pushed:>=${cutoffIsoDate}`;
2889
+ const params = new URLSearchParams({
2890
+ q,
2891
+ sort: "stars",
2892
+ order: "desc",
2893
+ per_page: String(limitPerPlatform)
2894
+ });
2895
+ const res = await fetch(`https://api.github.com/search/repositories?${params.toString()}`, {
2896
+ headers: {
2897
+ Accept: "application/vnd.github+json",
2898
+ "User-Agent": "OrchableResearchKit/1.3"
2899
+ },
2900
+ signal: AbortSignal.timeout(6500)
2901
+ });
2902
+ if (res.ok) {
2903
+ const data = await res.json();
2904
+ if (Array.isArray(data?.items)) {
2905
+ for (const repo of data.items) {
2906
+ const stars = Number(repo.stargazers_count) || 0;
2907
+ const score = Math.min(10, Math.max(5, Math.round(4 + Math.log10(stars + 1) * 1.8)));
2908
+ pushUnique({
2909
+ id: `gh-${repo.id || repo.full_name}`,
2910
+ platform: "github",
2911
+ title: `${repo.full_name}: ${repo.description || "GitHub Repository"}`.slice(0, 180),
2912
+ url: repo.html_url,
2913
+ snippet: `${repo.description || ""} [Stars: ${stars}, Language: ${repo.language || "N/A"}, Updated: ${String(repo.pushed_at || "").slice(0, 10)}]`.trim(),
2914
+ author: repo.owner?.login,
2915
+ createdAt: repo.pushed_at || repo.created_at,
2916
+ engagementScore: score,
2917
+ rawMetrics: { stars }
2918
+ });
2919
+ }
2920
+ }
2921
+ }
2922
+ } catch (e) {
2923
+ console.warn("[SocialPulseHarvester] GitHub search failed:", e?.message || e);
2924
+ }
2925
+ })()
2926
+ );
2927
+ }
2928
+ if (options.includeRedditWeb !== false) {
2929
+ tasks.push(
2930
+ (async () => {
2931
+ try {
2932
+ const timeRange = recencyDays <= 7 ? "week" : recencyDays <= 35 ? "month" : "year";
2933
+ const hits = await this.searchEngine.search(`${topic} reddit OR community discussion pitfalls`, {
2934
+ limit: limitPerPlatform,
2935
+ timeRange
2936
+ });
2937
+ for (const [idx, h] of hits.entries()) {
2938
+ const isReddit = /reddit\.com/i.test(h.url);
2939
+ pushUnique({
2940
+ id: `pulse-${idx + 1}`,
2941
+ platform: isReddit ? "reddit" : "web",
2942
+ title: h.title,
2943
+ url: h.url,
2944
+ snippet: h.content.slice(0, 350),
2945
+ engagementScore: isReddit ? 7 : 6
2946
+ });
2947
+ }
2948
+ } catch (e) {
2949
+ console.warn("[SocialPulseHarvester] Recency web search failed:", e?.message || e);
2950
+ }
2951
+ })()
2952
+ );
2953
+ }
2954
+ await Promise.allSettled(tasks);
2955
+ items.sort((a, b) => b.engagementScore - a.engagementScore);
2956
+ const trendingReposAndTools = items.filter((i) => i.platform === "github").map((i) => `${i.title} (${i.url})`);
2957
+ const communityHighlights = items.slice(0, 6).map((i) => `[${i.platform.toUpperCase()}] ${i.title}: ${i.snippet}`);
2958
+ const mdLines = [
2959
+ `# \u{1F4E1} Social & Developer Pulse Report (Last ${recencyDays} Days): ${topic}`,
2960
+ `> **Harvested At:** \`${(/* @__PURE__ */ new Date()).toISOString()}\` | **Window:** \`Last ${recencyDays} days\` | **Total Signals:** \`${items.length}\``,
2961
+ `
2962
+ ## 1. Community Signals & Discussions`,
2963
+ ...items.length > 0 ? items.map(
2964
+ (item, idx) => `${idx + 1}. **[${item.platform.toUpperCase()}] [${item.title}](${item.url})** (Score: \`${item.engagementScore}/10\`)
2965
+ - ${item.snippet}`
2966
+ ) : ["- No recent social pulse items found within the specified window."]
2967
+ ];
2968
+ if (trendingReposAndTools.length > 0) {
2969
+ mdLines.push(
2970
+ `
2971
+ ## 2. Active Repositories & Tooling`,
2972
+ ...trendingReposAndTools.map((r) => `- ${r}`)
2973
+ );
2974
+ }
2975
+ return {
2976
+ topic,
2977
+ recencyDays,
2978
+ harvestedAt: (/* @__PURE__ */ new Date()).toISOString(),
2979
+ items,
2980
+ trendingReposAndTools,
2981
+ communityHighlights,
2982
+ markdownReport: mdLines.join("\n")
2983
+ };
2984
+ }
2985
+ };
2986
+
2701
2987
  // src/evidence/evidenceScorer.ts
2702
2988
  function tokenizeBilingualKeywords(text) {
2703
2989
  return text.normalize("NFC").toLowerCase().replace(/[.,;:!?()[\]{}"“”‘’/\\|`*_~#-]+/g, " ").split(/\s+/).filter((w) => w.length >= 2 && !/^(and|the|for|with|from|into|của|trong|được|những|các|cho|với|khi|và|hoặc|để|từ|đến|về)$/.test(w));
2704
2990
  }
2991
+ function keywordMatchesText(keyword, lowerText) {
2992
+ if (keyword.length <= 3) {
2993
+ const escaped = keyword.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
2994
+ return new RegExp(`(?:^|[^a-z0-9\\u00C0-\\u1EF9])${escaped}(?:$|[^a-z0-9\\u00C0-\\u1EF9])`, "i").test(lowerText);
2995
+ }
2996
+ return lowerText.includes(keyword);
2997
+ }
2705
2998
  function extractTopSentences(markdown, targetTopic, maxSentences = 3) {
2706
2999
  const keywords = tokenizeBilingualKeywords(targetTopic);
2707
3000
  const withoutCode = markdown.replace(/```[\s\S]*?```/g, " ");
@@ -2714,7 +3007,7 @@ function extractTopSentences(markdown, targetTopic, maxSentences = 3) {
2714
3007
  if (rawSentences.length === 0) return [];
2715
3008
  const scored = rawSentences.map((sentence, idx) => {
2716
3009
  const lower = sentence.normalize("NFC").toLowerCase();
2717
- const matchedCount = keywords.filter((k) => lower.includes(k)).length;
3010
+ const matchedCount = keywords.filter((k) => keywordMatchesText(k, lower)).length;
2718
3011
  const positionBonus = idx < 8 ? 1.5 : idx < 20 ? 0.5 : 0;
2719
3012
  const technicalBonus = /(`[^`]+`|\b(?:api|function|class|actor|async|sensor|pin|loop|state|biến|hàm|cảm biến|vòng lặp|mạch)\b)/i.test(
2720
3013
  sentence
@@ -2735,7 +3028,7 @@ var EvidenceScorer = class {
2735
3028
  let noiseScore = 2;
2736
3029
  const lowerContent = doc.markdownContent.normalize("NFC").toLowerCase();
2737
3030
  const targetKeywords = tokenizeBilingualKeywords(targetTopic);
2738
- const keywordMatches = targetKeywords.filter((k) => lowerContent.includes(k)).length;
3031
+ const keywordMatches = targetKeywords.filter((k) => keywordMatchesText(k, lowerContent)).length;
2739
3032
  const matchRatio = targetKeywords.length > 0 ? keywordMatches / targetKeywords.length : 1;
2740
3033
  if (matchRatio >= 0.75) depthScore += 3;
2741
3034
  else if (matchRatio >= 0.4) depthScore += 2;
@@ -3683,33 +3976,17 @@ var TechnicalGroundingEngine = class {
3683
3976
  preservedKeyExcerpts.push(...s.keyExcerpts);
3684
3977
  }
3685
3978
  }
3686
- const defaultExemplars = [
3687
- {
3688
- title: scrapedSnippets[0]?.title || `${topic} Hands-on Foundation Project`,
3689
- description: scrapedSnippets[0]?.excerpt ? scrapedSnippets[0].excerpt.slice(0, 220) : `Verified practical implementation integrating ${hardware || "core principles"} and ${software || "standard development tools"}.`,
3690
- targetAudience: `Students aged ${ageBand[0]}-${ageBand[1]}`,
3691
- sourceUrl: scrapedSnippets[0]?.url,
3692
- hardwareRequirements: hardware ? [hardware] : void 0,
3693
- softwareRequirements: software ? [software] : void 0
3694
- }
3695
- ];
3696
- const defaultBottlenecks = domain === "hardware" || Boolean(hardware) ? [
3697
- "Power supply decoupling and current surge when powering sensors or actuators.",
3698
- "Logic level shifting and hardware pin mapping conflicts."
3699
- ] : domain === "academic" ? [
3700
- "Cognitive load pacing and abstract concept grounding with physical analogies."
3701
- ] : [
3702
- "SDK/runtime version compatibility and local environment dependencies.",
3703
- "Syntax confusion between asynchronous event handling and blocking calls."
3704
- ];
3979
+ const defaultExemplars = [];
3980
+ const defaultBottlenecks = [];
3705
3981
  let factsheet = {
3706
3982
  topic,
3707
3983
  domain,
3984
+ evidenceBacked: false,
3708
3985
  compatibilityMatrix: {
3709
3986
  hardwarePlatform: hardware || void 0,
3710
3987
  softwareEnv: software || void 0,
3711
3988
  verifiedCompatible: true,
3712
- notes: hardware || software ? [`Targeting ${hardware || "General Platform"} with ${software || "Standard SDK"}.`] : [`Baseline technical verification for ${topic}.`]
3989
+ notes: []
3713
3990
  },
3714
3991
  ageFeasibility: {
3715
3992
  recommendedMinAge: ageBand[0],
@@ -3719,7 +3996,7 @@ var TechnicalGroundingEngine = class {
3719
3996
  },
3720
3997
  exemplarProjects: defaultExemplars,
3721
3998
  technicalBottlenecks: defaultBottlenecks,
3722
- groundingSources: scrapedSnippets.map((s) => ({ title: s.title, url: s.url })),
3999
+ groundingSources: scrapedSnippets.filter((s) => Boolean(s.url)).map((s) => ({ title: s.title, url: s.url })),
3723
4000
  markdownReport: "",
3724
4001
  codeSnippets: preservedCodeSnippets.slice(0, 4),
3725
4002
  pinoutTables: preservedTables.slice(0, 4),
@@ -3727,9 +4004,10 @@ var TechnicalGroundingEngine = class {
3727
4004
  };
3728
4005
  if (llm && scrapedSnippets.length > 0) {
3729
4006
  try {
4007
+ const roleByDomain = domain === "hardware" ? "Hardware & Embedded Systems Curriculum Specialist" : domain === "software" ? "Software & Technology Curriculum Specialist" : "Applied Subject Matter & Curriculum Specialist";
3730
4008
  const prompt = [
3731
- `You are a Lead STEM Curriculum Engineer. Analyze these research excerpts for topic: "${topic}".`,
3732
- `Hardware: ${hardware || "N/A"}, Software/Env: ${software || "N/A"}, Student Age Band: ${ageBand[0]}-${ageBand[1]} years old.`,
4009
+ `You are a ${roleByDomain}. Analyze these verified research excerpts for topic: "${topic}".`,
4010
+ `Domain: ${domain}, Hardware: ${hardware || "N/A"}, Software/Env: ${software || "N/A"}, Student Age Band: ${ageBand[0]}-${ageBand[1]} years old.`,
3733
4011
  `
3734
4012
  Harvested Sources:
3735
4013
  ${scrapedSnippets.map((s, i) => {
@@ -3746,7 +4024,7 @@ ${c.code}
3746
4024
  return parts.join("\n");
3747
4025
  }).join("\n\n")}`,
3748
4026
  `
3749
- Synthesize a strictly valid JSON object with:`,
4027
+ Synthesize a strictly valid JSON object based ONLY on the evidence above. If no evidence exists for a field, leave it as an empty array [] without inventing facts:`,
3750
4028
  `{`,
3751
4029
  ` "compatibilityVerdict": boolean,`,
3752
4030
  ` "compatibilityNotes": string[],`,
@@ -3781,10 +4059,28 @@ Synthesize a strictly valid JSON object with:`,
3781
4059
  }));
3782
4060
  }
3783
4061
  if (Array.isArray(parsed.technicalBottlenecks)) factsheet.technicalBottlenecks = parsed.technicalBottlenecks.map(String);
4062
+ if (factsheet.exemplarProjects.length > 0 || factsheet.technicalBottlenecks.length > 0) {
4063
+ factsheet.evidenceBacked = true;
4064
+ }
3784
4065
  }
3785
4066
  } catch (err) {
3786
4067
  console.warn("[TechnicalGroundingEngine] LLM synthesis error:", err?.message || err);
3787
4068
  }
4069
+ } else if (scrapedSnippets.length > 0 && scrapedSnippets[0]?.excerpt?.trim()) {
4070
+ const first = scrapedSnippets[0];
4071
+ if (first.title || first.excerpt) {
4072
+ factsheet.exemplarProjects = [
4073
+ {
4074
+ title: first.title || `${topic} Hands-on Foundation Project`,
4075
+ description: first.excerpt.slice(0, 220),
4076
+ targetAudience: `Students aged ${ageBand[0]}-${ageBand[1]}`,
4077
+ sourceUrl: first.url,
4078
+ hardwareRequirements: hardware ? [hardware] : void 0,
4079
+ softwareRequirements: software ? [software] : void 0
4080
+ }
4081
+ ];
4082
+ factsheet.evidenceBacked = true;
4083
+ }
3788
4084
  }
3789
4085
  factsheet.markdownReport = this.renderMarkdownReport(factsheet);
3790
4086
  return factsheet;
@@ -3798,23 +4094,41 @@ Synthesize a strictly valid JSON object with:`,
3798
4094
  `- **Hardware:** ${fs.compatibilityMatrix.hardwarePlatform || "N/A"}`,
3799
4095
  `- **Software / SDK:** ${fs.compatibilityMatrix.softwareEnv || "N/A"}`,
3800
4096
  `- **Verdict:** ${fs.compatibilityMatrix.verifiedCompatible ? "\u2705 Verified Compatible" : "\u26A0\uFE0F Compatibility Warning"}`,
3801
- ...fs.compatibilityMatrix.notes.map((n) => ` - ${n}`),
3802
- `
4097
+ ...fs.compatibilityMatrix.notes.map((n) => ` - ${n}`)
4098
+ ];
4099
+ if (fs.ageFeasibility.potentialBarriers.length > 0) {
4100
+ lines.push(
4101
+ `
3803
4102
  ## 2. Age Feasibility & Learner Barriers (Ages ${fs.ageFeasibility.recommendedMinAge}\u2013${fs.ageFeasibility.recommendedMaxAge})`,
3804
- ...fs.ageFeasibility.potentialBarriers.map((b) => `- \u26A0\uFE0F ${b}`),
3805
- `
4103
+ ...fs.ageFeasibility.potentialBarriers.map((b) => `- \u26A0\uFE0F ${b}`)
4104
+ );
4105
+ }
4106
+ if (fs.exemplarProjects.length > 0) {
4107
+ lines.push(
4108
+ `
3806
4109
  ## 3. Real-World Exemplar Projects`,
3807
- ...fs.exemplarProjects.map((ex, idx) => `### Exemplar ${idx + 1}: ${ex.title}
4110
+ ...fs.exemplarProjects.map(
4111
+ (ex, idx) => `### Exemplar ${idx + 1}: ${ex.title}
3808
4112
  - **Summary:** ${ex.description}
3809
4113
  - **Audience:** ${ex.targetAudience}${ex.sourceUrl ? `
3810
- - **Reference:** [Link](${ex.sourceUrl})` : ""}`),
3811
- `
4114
+ - **Reference:** [Link](${ex.sourceUrl})` : ""}`
4115
+ )
4116
+ );
4117
+ }
4118
+ if (fs.technicalBottlenecks.length > 0) {
4119
+ lines.push(
4120
+ `
3812
4121
  ## 4. Technical Bottlenecks & Pitfalls to Avoid`,
3813
- ...fs.technicalBottlenecks.map((bn) => `- \u{1F6D1} ${bn}`),
3814
- `
4122
+ ...fs.technicalBottlenecks.map((bn) => `- \u{1F6D1} ${bn}`)
4123
+ );
4124
+ }
4125
+ if (fs.groundingSources.length > 0) {
4126
+ lines.push(
4127
+ `
3815
4128
  ## 5. Grounding Citations`,
3816
- ...fs.groundingSources.map((s, idx) => `${idx + 1}. [${s.title}](${s.url})`)
3817
- ];
4129
+ ...fs.groundingSources.map((s, idx) => `${idx + 1}. [${s.title}](${s.url})`)
4130
+ );
4131
+ }
3818
4132
  if (fs.codeSnippets && fs.codeSnippets.length > 0) {
3819
4133
  lines.push(
3820
4134
  `
@@ -3825,125 +4139,2046 @@ ${c.code}
3825
4139
  );
3826
4140
  }
3827
4141
  if (fs.pinoutTables && fs.pinoutTables.length > 0) {
3828
- lines.push(
3829
- `
3830
- ## 7. Pinout & Specification Tables`,
3831
- ...fs.pinoutTables
3832
- );
4142
+ lines.push(`
4143
+ ## 7. Pinout & Specification Tables`, ...fs.pinoutTables);
3833
4144
  }
3834
4145
  return lines.join("\n");
3835
4146
  }
3836
4147
  };
3837
4148
 
3838
- // src/services/researchKitClient.ts
3839
- var KnowledgeDiscoveryService = class {
3840
- constructor(config) {
3841
- this.config = config;
3842
- this.searchEngine = new MultiSourceSearchEngine({
3843
- apiKeys: config.apiKeys,
3844
- allowEnvFallback: config.allowEnvFallback,
3845
- customAdapter: config.customSearchAdapter
3846
- });
3847
- this.webScraper = new WebScraper({
3848
- crawl4aiHost: config.crawl4aiHost,
3849
- jinaKey: config.apiKeys?.jina,
3850
- brightDataKey: config.apiKeys?.brightdata || config.apiKeys?.brightData,
3851
- allowEnvFallback: config.allowEnvFallback,
3852
- customAdapter: config.customCrawlerAdapter
3853
- });
3854
- this.youtubeService = new YouTubeIngestionService();
3855
- this.stemResearcher = new StemResourceResearcher();
3856
- }
3857
- searchEngine;
3858
- webScraper;
3859
- youtubeService;
3860
- stemResearcher;
3861
- async search(query, limit = 5) {
3862
- return this.searchEngine.search(query, {
3863
- limit,
3864
- apiKeys: this.config.apiKeys,
3865
- customAdapter: this.config.customSearchAdapter
3866
- });
3867
- }
3868
- async scrapeUrl(url) {
3869
- return this.webScraper.scrapeUrl(url, {
3870
- customAdapter: this.config.customCrawlerAdapter,
3871
- jinaKey: this.config.apiKeys?.jina
3872
- });
3873
- }
3874
- async ingestYouTube(urlOrVideoId, preferredLanguages = ["vi", "en"]) {
3875
- return this.youtubeService.fetchTranscript(urlOrVideoId, preferredLanguages);
4149
+ // src/agent/types.ts
4150
+ var RESEARCH_MODE_PRESETS = {
4151
+ search: {
4152
+ mode: "search",
4153
+ timeoutMs: 8e3,
4154
+ maxChannels: 1,
4155
+ channelConcurrency: 1,
4156
+ maxRounds: 1,
4157
+ maxQueriesPerRound: 1,
4158
+ maxScrapePerRound: 0,
4159
+ verifyClaims: false
4160
+ },
4161
+ research: {
4162
+ mode: "research",
4163
+ timeoutMs: 9e4,
4164
+ maxChannels: 2,
4165
+ channelConcurrency: 2,
4166
+ maxRounds: 1,
4167
+ maxQueriesPerRound: 3,
4168
+ maxScrapePerRound: 3,
4169
+ verifyClaims: false
4170
+ },
4171
+ "deep-research": {
4172
+ mode: "deep-research",
4173
+ timeoutMs: 3e5,
4174
+ maxChannels: 5,
4175
+ channelConcurrency: 2,
4176
+ maxRounds: 3,
4177
+ maxQueriesPerRound: 4,
4178
+ maxScrapePerRound: 4,
4179
+ verifyClaims: true
3876
4180
  }
3877
- async findStemResources(query, options) {
3878
- return this.stemResearcher.findResources(query, options);
4181
+ };
4182
+ var RESEARCH_PROFILE_PRESETS = {
4183
+ fast_grounded: {
4184
+ maxRounds: 1,
4185
+ maxQueriesPerRound: 3,
4186
+ maxScrapePerRound: 3,
4187
+ timeoutMs: 9e4,
4188
+ enableWeb: true,
4189
+ enableAcademic: false,
4190
+ enableSocialPulse: false,
4191
+ enableStemOer: false
4192
+ },
4193
+ deep_autonomous: {
4194
+ maxRounds: 3,
4195
+ maxQueriesPerRound: 4,
4196
+ maxScrapePerRound: 4,
4197
+ timeoutMs: 3e5,
4198
+ enableWeb: true,
4199
+ enableAcademic: true,
4200
+ enableSocialPulse: true,
4201
+ enableStemOer: true
4202
+ },
4203
+ technical: {
4204
+ maxRounds: 1,
4205
+ maxQueriesPerRound: 3,
4206
+ maxScrapePerRound: 3,
4207
+ timeoutMs: 9e4,
4208
+ enableWeb: true,
4209
+ enableAcademic: false,
4210
+ enableSocialPulse: true,
4211
+ enableStemOer: false
4212
+ },
4213
+ academic: {
4214
+ maxRounds: 1,
4215
+ maxQueriesPerRound: 3,
4216
+ maxScrapePerRound: 2,
4217
+ timeoutMs: 9e4,
4218
+ enableWeb: true,
4219
+ enableAcademic: true,
4220
+ enableSocialPulse: false,
4221
+ enableStemOer: false
4222
+ },
4223
+ social_pulse: {
4224
+ maxRounds: 1,
4225
+ maxQueriesPerRound: 3,
4226
+ maxScrapePerRound: 2,
4227
+ timeoutMs: 9e4,
4228
+ enableWeb: true,
4229
+ enableAcademic: false,
4230
+ enableSocialPulse: true,
4231
+ enableStemOer: false
4232
+ },
4233
+ curriculum_oer: {
4234
+ maxRounds: 1,
4235
+ maxQueriesPerRound: 3,
4236
+ maxScrapePerRound: 3,
4237
+ timeoutMs: 9e4,
4238
+ enableWeb: true,
4239
+ enableAcademic: false,
4240
+ enableSocialPulse: false,
4241
+ enableStemOer: true
4242
+ },
4243
+ general: {
4244
+ maxRounds: 1,
4245
+ maxQueriesPerRound: 3,
4246
+ maxScrapePerRound: 3,
4247
+ timeoutMs: 9e4,
4248
+ enableWeb: true,
4249
+ enableAcademic: false,
4250
+ enableSocialPulse: false,
4251
+ enableStemOer: false
3879
4252
  }
3880
4253
  };
3881
- var TerminologyGraphService = class {
3882
- constructor(config) {
3883
- this.config = config;
4254
+
4255
+ // src/agent/evidenceLedger.ts
4256
+ function normalizeUrlKey(rawUrl) {
4257
+ try {
4258
+ const u = new URL(rawUrl.trim());
4259
+ u.hash = "";
4260
+ for (const param of ["utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content", "ref"]) {
4261
+ u.searchParams.delete(param);
4262
+ }
4263
+ return u.toString().replace(/\/$/, "").toLowerCase();
4264
+ } catch {
4265
+ return rawUrl.trim().replace(/\/$/, "").toLowerCase();
3884
4266
  }
3885
- extractor = new PedagogicalTermExtractor();
3886
- extractConceptsDeterministic(topic, docs, domain) {
3887
- const resolvedDomain = domain ?? classifyTechnicalDomain(topic, void 0, this.config.defaultCourseContext).domain;
3888
- const normalizedDocs = typeof docs === "string" ? [
3889
- {
3890
- resourceId: "RES-01",
3891
- doc: {
3892
- url: "inline://corpus",
3893
- title: topic,
3894
- markdownContent: docs,
3895
- byteSize: Buffer.byteLength(docs, "utf-8"),
3896
- extractedCodeSnippets: [],
3897
- tablesCount: 0,
3898
- fetchProvider: "direct"
3899
- }
3900
- }
3901
- ] : docs;
3902
- return this.extractor.extractDeterministic(topic, resolvedDomain, normalizedDocs);
4267
+ }
4268
+ var EvidenceLedger = class {
4269
+ items = [];
4270
+ urlIndex = /* @__PURE__ */ new Map();
4271
+ idIndex = /* @__PURE__ */ new Map();
4272
+ allocateId() {
4273
+ const nextNum = this.items.length + 1;
4274
+ return `RES-${String(nextNum).padStart(2, "0")}`;
3903
4275
  }
3904
- async extractConcepts(topic, docs, options) {
3905
- const resolvedDomain = options?.domain ?? classifyTechnicalDomain(topic, void 0, options?.context ?? this.config.defaultCourseContext).domain;
3906
- const normalizedDocs = typeof docs === "string" ? [
3907
- {
3908
- resourceId: "RES-01",
3909
- doc: {
3910
- url: "inline://corpus",
3911
- title: topic,
3912
- markdownContent: docs,
3913
- byteSize: Buffer.byteLength(docs, "utf-8"),
3914
- extractedCodeSnippets: [],
3915
- keyExcerpts: [docs.slice(0, 600)],
3916
- tablesCount: 0,
3917
- fetchProvider: "direct"
3918
- }
3919
- }
3920
- ] : docs;
3921
- return this.extractor.extractWithOptionalLlm(topic, resolvedDomain, normalizedDocs, {
3922
- context: options?.context ?? this.config.defaultCourseContext,
3923
- llm: options?.llm ?? this.config.llm,
3924
- maxTerms: options?.maxTerms
3925
- });
4276
+ /**
4277
+ * Records or upgrades a ledger entry from a full `ScrapedDocument`.
4278
+ */
4279
+ addScrapedDocument(doc, relevanceScore, extraTakeaways = []) {
4280
+ const key = normalizeUrlKey(doc.url);
4281
+ const existing = this.urlIndex.get(key);
4282
+ const mergedExcerpts = Array.from(
4283
+ new Set([
4284
+ ...extraTakeaways,
4285
+ ...doc.keyExcerpts || [],
4286
+ doc.markdownContent.replace(/```[\s\S]*?```/g, " ").replace(/\s+/g, " ").trim().slice(0, 450)
4287
+ ].filter((e) => e && e.trim().length > 20))
4288
+ ).slice(0, 6);
4289
+ const sourceType = doc.fetchProvider === "youtube" ? "youtube" : "web";
4290
+ if (existing) {
4291
+ existing.title = doc.title || existing.title;
4292
+ existing.relevanceScore = Math.max(existing.relevanceScore, relevanceScore);
4293
+ existing.headings = doc.extractedHeadings?.slice(0, 8) || existing.headings;
4294
+ existing.keyExcerpts = mergedExcerpts.length > 0 ? mergedExcerpts : existing.keyExcerpts;
4295
+ existing.codeBlocks = (doc.extractedCodeBlocks || []).slice(0, 4);
4296
+ existing.tables = (doc.extractedTables || []).slice(0, 4);
4297
+ existing.rawByteSize = Math.max(existing.rawByteSize, doc.byteSize || 0);
4298
+ return this.toCompactReceipt(existing);
4299
+ }
4300
+ const item = {
4301
+ id: this.allocateId(),
4302
+ sourceType,
4303
+ title: doc.title || "Untitled Document",
4304
+ url: doc.url,
4305
+ relevanceScore: Math.max(1, Math.min(10, Math.round(relevanceScore))),
4306
+ headings: (doc.extractedHeadings || []).slice(0, 8),
4307
+ keyExcerpts: mergedExcerpts,
4308
+ codeBlocks: (doc.extractedCodeBlocks || []).slice(0, 4),
4309
+ tables: (doc.extractedTables || []).slice(0, 4),
4310
+ rawByteSize: doc.byteSize || Buffer.byteLength(doc.markdownContent || "", "utf-8"),
4311
+ accessedAt: (/* @__PURE__ */ new Date()).toISOString()
4312
+ };
4313
+ this.items.push(item);
4314
+ this.urlIndex.set(key, item);
4315
+ this.idIndex.set(item.id, item);
4316
+ return this.toCompactReceipt(item);
3926
4317
  }
3927
- formatConceptDagTsv(concepts) {
3928
- return this.extractor.formatConceptDagTsv(concepts);
4318
+ /**
4319
+ * Records a lightweight search hit when full scraping is skipped or pending.
4320
+ */
4321
+ addSearchHit(hit, relevanceScore = 6) {
4322
+ const key = normalizeUrlKey(hit.url);
4323
+ const existing = this.urlIndex.get(key);
4324
+ if (existing) {
4325
+ return this.toCompactReceipt(existing);
4326
+ }
4327
+ const snippet = (hit.content || "").replace(/\s+/g, " ").trim();
4328
+ const item = {
4329
+ id: this.allocateId(),
4330
+ sourceType: hit.engine === "academic" ? "academic" : "web",
4331
+ title: hit.title || "Search Result",
4332
+ url: hit.url,
4333
+ relevanceScore: Math.max(1, Math.min(10, Math.round(relevanceScore))),
4334
+ headings: [],
4335
+ keyExcerpts: snippet ? [snippet.slice(0, 450)] : [],
4336
+ codeBlocks: [],
4337
+ tables: [],
4338
+ rawByteSize: Buffer.byteLength(snippet, "utf-8"),
4339
+ accessedAt: (/* @__PURE__ */ new Date()).toISOString()
4340
+ };
4341
+ this.items.push(item);
4342
+ this.urlIndex.set(key, item);
4343
+ this.idIndex.set(item.id, item);
4344
+ return this.toCompactReceipt(item);
3929
4345
  }
3930
- };
3931
- var AcademicStandardsService = class {
3932
- constructor(config) {
3933
- this.config = config;
3934
- this.academicSearch = new AcademicSearchEngine({
3935
- apiKey: config.apiKeys?.semanticScholar,
3936
- allowEnvFallback: config.allowEnvFallback,
3937
- customAdapter: config.customAcademicSearchAdapter
3938
- });
4346
+ /**
4347
+ * Records a peer-reviewed or preprint paper from Semantic Scholar, OpenAlex, Crossref, or arXiv.
4348
+ */
4349
+ addAcademicPaper(paper) {
4350
+ const url = paper.url || paper.pdfUrl || (paper.doi ? `https://doi.org/${paper.doi}` : `https://openalex.org/${paper.id}`);
4351
+ const key = normalizeUrlKey(url);
4352
+ const existing = this.urlIndex.get(key);
4353
+ if (existing) {
4354
+ return this.toCompactReceipt(existing);
4355
+ }
4356
+ const abstractOrTldr = [paper.tldr, paper.abstract].filter(Boolean).join(" \u2014 ").trim();
4357
+ const citationBonus = paper.citationCount >= 50 ? 9 : paper.citationCount >= 10 ? 8 : 7;
4358
+ const item = {
4359
+ id: this.allocateId(),
4360
+ sourceType: "academic",
4361
+ title: paper.title,
4362
+ url,
4363
+ authorOrVenue: [paper.authors?.slice(0, 3).join(", "), paper.venue, paper.year].filter(Boolean).join(" \xB7 "),
4364
+ publishedDate: paper.year ? String(paper.year) : void 0,
4365
+ relevanceScore: citationBonus,
4366
+ headings: paper.fieldsOfStudy || [],
4367
+ keyExcerpts: abstractOrTldr ? [abstractOrTldr.slice(0, 600)] : [`Academic paper: ${paper.title}`],
4368
+ codeBlocks: [],
4369
+ tables: [],
4370
+ rawByteSize: Buffer.byteLength(abstractOrTldr || paper.title, "utf-8"),
4371
+ accessedAt: (/* @__PURE__ */ new Date()).toISOString()
4372
+ };
4373
+ this.items.push(item);
4374
+ this.urlIndex.set(key, item);
4375
+ this.idIndex.set(item.id, item);
4376
+ return this.toCompactReceipt(item);
3939
4377
  }
3940
- academicSearch;
3941
- litSynthesizer = new LiteratureReviewSynthesizer();
3942
- alignStandards(topic, context) {
3943
- return mapTopicToCS2023(topic, context ?? this.config.defaultCourseContext);
4378
+ /**
4379
+ * Records a 30-day social/developer pulse signal (HackerNews, GitHub, Reddit).
4380
+ */
4381
+ addSocialPulseItem(pulse) {
4382
+ const key = normalizeUrlKey(pulse.url);
4383
+ const existing = this.urlIndex.get(key);
4384
+ if (existing) {
4385
+ return this.toCompactReceipt(existing);
4386
+ }
4387
+ const item = {
4388
+ id: this.allocateId(),
4389
+ sourceType: "social_pulse",
4390
+ title: pulse.title,
4391
+ url: pulse.url,
4392
+ authorOrVenue: `${pulse.platform.toUpperCase()}${pulse.author ? ` (@${pulse.author})` : ""}`,
4393
+ publishedDate: pulse.createdAt,
4394
+ relevanceScore: Math.max(1, Math.min(10, pulse.engagementScore)),
4395
+ headings: [pulse.platform.toUpperCase()],
4396
+ keyExcerpts: [pulse.snippet.slice(0, 450)],
4397
+ codeBlocks: [],
4398
+ tables: [],
4399
+ rawByteSize: Buffer.byteLength(pulse.snippet, "utf-8"),
4400
+ accessedAt: (/* @__PURE__ */ new Date()).toISOString()
4401
+ };
4402
+ this.items.push(item);
4403
+ this.urlIndex.set(key, item);
4404
+ this.idIndex.set(item.id, item);
4405
+ return this.toCompactReceipt(item);
3944
4406
  }
3945
- async searchPapers(query, limit = 5) {
3946
- return this.academicSearch.searchPapers(query, {
4407
+ /**
4408
+ * Records a verified STEM OER simulation/resource (PhET, OpenStax, NASA, CS Unplugged).
4409
+ */
4410
+ addStemResource(resource) {
4411
+ const key = normalizeUrlKey(resource.url);
4412
+ const existing = this.urlIndex.get(key);
4413
+ if (existing) {
4414
+ return this.toCompactReceipt(existing);
4415
+ }
4416
+ const excerpt = `${resource.description} [Provider: ${resource.provider}${resource.license ? `, License: ${resource.license}` : ""}]`;
4417
+ const item = {
4418
+ id: this.allocateId(),
4419
+ sourceType: "stem_oer",
4420
+ title: resource.title,
4421
+ url: resource.url,
4422
+ authorOrVenue: resource.provider,
4423
+ relevanceScore: 8,
4424
+ headings: [resource.provider],
4425
+ keyExcerpts: [excerpt.slice(0, 450)],
4426
+ codeBlocks: [],
4427
+ tables: [],
4428
+ rawByteSize: Buffer.byteLength(excerpt, "utf-8"),
4429
+ accessedAt: (/* @__PURE__ */ new Date()).toISOString()
4430
+ };
4431
+ this.items.push(item);
4432
+ this.urlIndex.set(key, item);
4433
+ this.idIndex.set(item.id, item);
4434
+ return this.toCompactReceipt(item);
4435
+ }
4436
+ /**
4437
+ * Projects a full `LedgerItem` into a compact receipt (<= 150 tokens) for Stage A planning & gap analysis.
4438
+ */
4439
+ toCompactReceipt(item) {
4440
+ const rawExcerpt = item.keyExcerpts[0] || item.title;
4441
+ return {
4442
+ id: item.id,
4443
+ sourceType: item.sourceType,
4444
+ title: item.title.slice(0, 140),
4445
+ url: item.url,
4446
+ relevanceScore: item.relevanceScore,
4447
+ headings: item.headings.slice(0, 5),
4448
+ codeBlockCount: item.codeBlocks.length,
4449
+ tableCount: item.tables.length,
4450
+ briefExcerpt: rawExcerpt.slice(0, 300)
4451
+ };
4452
+ }
4453
+ getItems() {
4454
+ return [...this.items];
4455
+ }
4456
+ getApprovedItems(minScore = 6) {
4457
+ return this.items.filter((i) => i.relevanceScore >= minScore);
4458
+ }
4459
+ getReceipts() {
4460
+ return this.items.map((i) => this.toCompactReceipt(i));
4461
+ }
4462
+ getById(id) {
4463
+ return this.idIndex.get(id.toUpperCase());
4464
+ }
4465
+ getTotalCodeBlocks() {
4466
+ return this.items.reduce((sum, i) => sum + i.codeBlocks.length, 0);
4467
+ }
4468
+ getTotalTables() {
4469
+ return this.items.reduce((sum, i) => sum + i.tables.length, 0);
4470
+ }
4471
+ /**
4472
+ * Formats the top verified items with `[RES-xx]` tags, substantive excerpts, code blocks,
4473
+ * and tables for Stage B Contract Synthesis.
4474
+ */
4475
+ buildSynthesisCorpus(maxItems = 12) {
4476
+ const sorted = [...this.items].sort((a, b) => b.relevanceScore - a.relevanceScore).slice(0, maxItems);
4477
+ if (sorted.length === 0) {
4478
+ return "No verified sources recorded in EvidenceLedger.";
4479
+ }
4480
+ return sorted.map((item) => {
4481
+ const parts = [
4482
+ `[${item.id}] (${item.sourceType.toUpperCase()} \xB7 Score ${item.relevanceScore}/10) Title: ${item.title}`,
4483
+ `URL: ${item.url}`
4484
+ ];
4485
+ if (item.authorOrVenue) {
4486
+ parts.push(`Source/Author: ${item.authorOrVenue}`);
4487
+ }
4488
+ if (item.headings.length > 0) {
4489
+ parts.push(`Sections: ${item.headings.join(" | ")}`);
4490
+ }
4491
+ if (item.keyExcerpts.length > 0) {
4492
+ parts.push(`Verified Excerpts:
4493
+ ${item.keyExcerpts.map((e) => `- ${e}`).join("\n")}`);
4494
+ }
4495
+ if (item.codeBlocks.length > 0) {
4496
+ parts.push(
4497
+ `Extracted Code Blocks:
4498
+ ` + item.codeBlocks.slice(0, 2).map((cb) => `\`\`\`${cb.language || "text"}
4499
+ ${cb.code.slice(0, 600)}
4500
+ \`\`\``).join("\n")
4501
+ );
4502
+ }
4503
+ if (item.tables.length > 0) {
4504
+ parts.push(`Extracted Tables:
4505
+ ${item.tables.slice(0, 2).join("\n\n")}`);
4506
+ }
4507
+ return parts.join("\n");
4508
+ }).join("\n\n---\n\n");
4509
+ }
4510
+ /**
4511
+ * Returns concatenated plain text of all ledger items for deterministic/LLM `ClaimVerifier` checks.
4512
+ */
4513
+ buildFullRawCorpus() {
4514
+ return this.items.map(
4515
+ (i) => `${i.title}
4516
+ ${i.keyExcerpts.join("\n")}
4517
+ ${i.codeBlocks.map((c) => c.code).join("\n")}
4518
+ ${i.tables.join("\n")}`
4519
+ ).join("\n\n");
4520
+ }
4521
+ /**
4522
+ * Scans any synthesized report or JSON string for `[RES-xx]` citation markers
4523
+ * and verifies every marker against the ledger.
4524
+ */
4525
+ verifyCitationTags(synthesizedText) {
4526
+ const matches = [...synthesizedText.matchAll(/\[?(RES-\d{2,3})\]?/gi)];
4527
+ const validSet = /* @__PURE__ */ new Set();
4528
+ const invalidSet = /* @__PURE__ */ new Set();
4529
+ for (const m of matches) {
4530
+ const tag = m[1].toUpperCase();
4531
+ if (this.idIndex.has(tag)) {
4532
+ validSet.add(tag);
4533
+ } else {
4534
+ invalidSet.add(tag);
4535
+ }
4536
+ }
4537
+ return {
4538
+ validCitationIds: Array.from(validSet),
4539
+ invalidCitationIds: Array.from(invalidSet)
4540
+ };
4541
+ }
4542
+ /**
4543
+ * Maps ledger items into `ProvenanceRecord[]` for `ProvenanceTracker`.
4544
+ */
4545
+ toProvenanceRecords(defaultDomain = "general") {
4546
+ return this.items.map((item) => ({
4547
+ resourceId: item.id,
4548
+ sourceUrl: item.url,
4549
+ accessedAt: item.accessedAt,
4550
+ domain: item.sourceType || defaultDomain,
4551
+ relevanceScore: item.relevanceScore,
4552
+ byteSize: item.rawByteSize
4553
+ }));
4554
+ }
4555
+ };
4556
+
4557
+ // src/agent/decisionRouter.ts
4558
+ var QUESTION_FACETS = [
4559
+ "official_spec",
4560
+ "how_to_example",
4561
+ "pitfalls",
4562
+ "pedagogy_theory",
4563
+ "standards_policy",
4564
+ "emerging_trend",
4565
+ "learning_resources"
4566
+ ];
4567
+ var SOURCE_CHANNELS = [
4568
+ "web_docs",
4569
+ "academic",
4570
+ "social_pulse",
4571
+ "stem_oer",
4572
+ "video_media"
4573
+ ];
4574
+ var PRIOR_MATRIX = {
4575
+ official_spec: {
4576
+ web_docs: 0.95,
4577
+ academic: 0.2,
4578
+ social_pulse: 0.3,
4579
+ stem_oer: 0.15,
4580
+ video_media: 0.25
4581
+ },
4582
+ how_to_example: {
4583
+ web_docs: 0.9,
4584
+ academic: 0.15,
4585
+ social_pulse: 0.65,
4586
+ stem_oer: 0.35,
4587
+ video_media: 0.6
4588
+ },
4589
+ pitfalls: {
4590
+ web_docs: 0.65,
4591
+ academic: 0.25,
4592
+ social_pulse: 0.9,
4593
+ stem_oer: 0.1,
4594
+ video_media: 0.35
4595
+ },
4596
+ pedagogy_theory: {
4597
+ web_docs: 0.45,
4598
+ academic: 0.95,
4599
+ social_pulse: 0.2,
4600
+ stem_oer: 0.7,
4601
+ video_media: 0.3
4602
+ },
4603
+ standards_policy: {
4604
+ web_docs: 0.75,
4605
+ academic: 0.85,
4606
+ social_pulse: 0.15,
4607
+ stem_oer: 0.6,
4608
+ video_media: 0.15
4609
+ },
4610
+ emerging_trend: {
4611
+ web_docs: 0.6,
4612
+ academic: 0.45,
4613
+ social_pulse: 0.95,
4614
+ stem_oer: 0.1,
4615
+ video_media: 0.5
4616
+ },
4617
+ learning_resources: {
4618
+ web_docs: 0.65,
4619
+ academic: 0.3,
4620
+ social_pulse: 0.25,
4621
+ stem_oer: 0.95,
4622
+ video_media: 0.7
4623
+ }
4624
+ };
4625
+ function clampScore0to4(val, fallback = 1) {
4626
+ const n = Number(val);
4627
+ if (!Number.isFinite(n)) return fallback;
4628
+ return Math.max(0, Math.min(4, n));
4629
+ }
4630
+ function computeContractComplexityScore(contract) {
4631
+ let score = 0;
4632
+ const reqAttrs = contract.acceptanceCriteria?.requiredAttributes?.length || 0;
4633
+ const reqSecs = contract.requiredSections?.length || 0;
4634
+ const totalReqs = reqAttrs + reqSecs;
4635
+ if (totalReqs >= 4) score += 2;
4636
+ else if (totalReqs >= 2) score += 1;
4637
+ if (contract.acceptanceCriteria?.requireCodeExamples || contract.acceptanceCriteria?.requireTables) {
4638
+ score += 1;
4639
+ }
4640
+ if ((contract.acceptanceCriteria?.minSources ?? 2) >= 4 || Boolean(contract.outputSchema)) {
4641
+ score += 1;
4642
+ }
4643
+ return Math.min(4, score);
4644
+ }
4645
+ function inferFallbackFacetProbabilities(contract) {
4646
+ const dist = {
4647
+ official_spec: 0.25,
4648
+ how_to_example: 0.25,
4649
+ pitfalls: 0.15,
4650
+ pedagogy_theory: 0.1,
4651
+ standards_policy: 0.05,
4652
+ emerging_trend: 0.1,
4653
+ learning_resources: 0.1
4654
+ };
4655
+ if (contract.profile === "academic" || (contract.acceptanceCriteria?.minPeerReviewedSources ?? 0) >= 1) {
4656
+ return {
4657
+ official_spec: 0.05,
4658
+ how_to_example: 0.05,
4659
+ pitfalls: 0.05,
4660
+ pedagogy_theory: 0.5,
4661
+ standards_policy: 0.25,
4662
+ emerging_trend: 0.05,
4663
+ learning_resources: 0.05
4664
+ };
4665
+ }
4666
+ if (contract.profile === "social_pulse") {
4667
+ return {
4668
+ official_spec: 0.05,
4669
+ how_to_example: 0.15,
4670
+ pitfalls: 0.35,
4671
+ pedagogy_theory: 0.02,
4672
+ standards_policy: 0.03,
4673
+ emerging_trend: 0.35,
4674
+ learning_resources: 0.05
4675
+ };
4676
+ }
4677
+ if (contract.profile === "curriculum_oer") {
4678
+ return {
4679
+ official_spec: 0.05,
4680
+ how_to_example: 0.15,
4681
+ pitfalls: 0.05,
4682
+ pedagogy_theory: 0.2,
4683
+ standards_policy: 0.1,
4684
+ emerging_trend: 0.05,
4685
+ learning_resources: 0.4
4686
+ };
4687
+ }
4688
+ return dist;
4689
+ }
4690
+ function rankChannelsByExpectedPrior(facetProbabilities, contract) {
4691
+ const scores = {
4692
+ web_docs: 0,
4693
+ academic: 0,
4694
+ social_pulse: 0,
4695
+ stem_oer: 0,
4696
+ video_media: 0
4697
+ };
4698
+ for (const facet of QUESTION_FACETS) {
4699
+ const p = facetProbabilities[facet] ?? 0;
4700
+ const row = PRIOR_MATRIX[facet];
4701
+ for (const channel of SOURCE_CHANNELS) {
4702
+ scores[channel] += p * row[channel];
4703
+ }
4704
+ }
4705
+ if ((contract.acceptanceCriteria?.minPeerReviewedSources ?? 0) >= 1 || contract.profile === "academic") {
4706
+ scores.academic += 0.3;
4707
+ }
4708
+ if (contract.profile === "social_pulse" || contract.acceptanceCriteria?.recencyDays !== void 0 && contract.acceptanceCriteria.recencyDays <= 30) {
4709
+ scores.social_pulse += 0.2;
4710
+ }
4711
+ if (contract.acceptanceCriteria?.requireCodeExamples || contract.acceptanceCriteria?.requireTables || contract.context?.hardwarePlatform || contract.context?.softwareEnv) {
4712
+ scores.web_docs += 0.15;
4713
+ }
4714
+ if (contract.profile === "curriculum_oer") {
4715
+ scores.stem_oer += 0.3;
4716
+ }
4717
+ if (contract.preferredChannels && contract.preferredChannels.length > 0) {
4718
+ contract.preferredChannels.forEach((ch, idx) => {
4719
+ if (scores[ch] !== void 0) {
4720
+ scores[ch] += Math.max(0.25, 0.6 - idx * 0.1);
4721
+ }
4722
+ });
4723
+ }
4724
+ return SOURCE_CHANNELS.map((channel) => ({
4725
+ channel,
4726
+ score: Number(scores[channel].toFixed(4))
4727
+ })).sort((a, b) => b.score - a.score);
4728
+ }
4729
+ async function classifyModeAndPrior(contract, decision) {
4730
+ let requestedMode = contract.mode ?? "auto";
4731
+ if (!contract.mode && contract.profile) {
4732
+ if (contract.profile === "deep_autonomous") {
4733
+ requestedMode = "deep-research";
4734
+ } else if (contract.profile !== "auto") {
4735
+ requestedMode = "research";
4736
+ }
4737
+ }
4738
+ const contractScore = computeContractComplexityScore(contract);
4739
+ const hardEscalated = contract.acceptanceCriteria?.verifyClaims === true || (contract.acceptanceCriteria?.minPeerReviewedSources ?? 0) >= 2;
4740
+ let readingDepth = 1.5;
4741
+ let sourceDiversity = 1.5;
4742
+ let decomposition = 1 + Math.min(2, (contract.acceptanceCriteria?.requiredAttributes?.length || 0) * 0.5);
4743
+ let verificationStakes = hardEscalated ? 3.5 : 1.5;
4744
+ let decisionEvaluated = false;
4745
+ let facetProbabilities = inferFallbackFacetProbabilities(contract);
4746
+ if (decision) {
4747
+ try {
4748
+ const contextLines = [
4749
+ `Research Objective: ${contract.objective}`,
4750
+ contract.context?.hardwarePlatform ? `Hardware Platform: ${contract.context.hardwarePlatform}` : "",
4751
+ contract.context?.softwareEnv ? `Software Environment: ${contract.context.softwareEnv}` : "",
4752
+ contract.context?.ageBand ? `Target Learner Age Band: ${contract.context.ageBand[0]}-${contract.context.ageBand[1]}` : "",
4753
+ contract.acceptanceCriteria?.requiredAttributes?.length ? `Required Attributes: ${contract.acceptanceCriteria.requiredAttributes.join(", ")}` : "",
4754
+ contract.requiredSections?.length ? `Required Report Sections: ${contract.requiredSections.join(", ")}` : ""
4755
+ ].filter(Boolean).join("\n");
4756
+ const result = await decision({
4757
+ context: contextLines,
4758
+ questions: [
4759
+ {
4760
+ id: "reading_depth",
4761
+ type: "score",
4762
+ criteria: "Evaluate how much document reading depth is required to answer the research objective (0 = single snippet or quick fact lookup, 2 = full document or API tutorial reading, 4 = multi-document cross-comparison and deep synthesis)."
4763
+ },
4764
+ {
4765
+ id: "source_diversity",
4766
+ type: "score",
4767
+ criteria: "Evaluate how many distinct knowledge modalities (official web docs, peer-reviewed academic papers, developer community pulse, interactive STEM OER simulations) are required (0 = 1 source type suffices, 2 = 2 complementary channels needed, 4 = 3 or more heterogeneous channels required)."
4768
+ },
4769
+ {
4770
+ id: "decomposition",
4771
+ type: "score",
4772
+ criteria: "Evaluate how many distinct sub-questions, technical constraints, or comparative dimensions must be decomposed and resolved (0 = single atomic question, 2 = 2 to 3 related facets, 4 = 4 or more complex interdependent facets)."
4773
+ },
4774
+ {
4775
+ id: "verification_stakes",
4776
+ type: "score",
4777
+ criteria: "Evaluate the factual verification stakes and risk of conflicting claims or hallucination (0 = low-stakes lookup, 2 = standard technical or pedagogical grounding, 4 = high-stakes factual or academic audit requiring strict claim verification)."
4778
+ },
4779
+ {
4780
+ id: "question_facet",
4781
+ type: "choice",
4782
+ criteria: "Classify the primary information need of this research objective into the most fitting facet.",
4783
+ options: [...QUESTION_FACETS]
4784
+ }
4785
+ ]
4786
+ });
4787
+ const aDepth = result.answers["reading_depth"];
4788
+ const aDiv = result.answers["source_diversity"];
4789
+ const aDecomp = result.answers["decomposition"];
4790
+ const aStakes = result.answers["verification_stakes"];
4791
+ const aFacet = result.answers["question_facet"];
4792
+ if (aDepth?.type === "score") readingDepth = clampScore0to4(aDepth.score, readingDepth);
4793
+ if (aDiv?.type === "score") sourceDiversity = clampScore0to4(aDiv.score, sourceDiversity);
4794
+ if (aDecomp?.type === "score") decomposition = clampScore0to4(aDecomp.score, decomposition);
4795
+ if (aStakes?.type === "score") verificationStakes = clampScore0to4(aStakes.score, verificationStakes);
4796
+ if (aFacet?.type === "choice") {
4797
+ const rawProbs = aFacet.probabilities;
4798
+ if (rawProbs && Object.keys(rawProbs).length > 0) {
4799
+ let sum = 0;
4800
+ const nextProbs = {};
4801
+ for (const f of QUESTION_FACETS) {
4802
+ const v = Math.max(0, Number(rawProbs[f] ?? 0));
4803
+ nextProbs[f] = v;
4804
+ sum += v;
4805
+ }
4806
+ if (sum > 0) {
4807
+ for (const f of QUESTION_FACETS) {
4808
+ nextProbs[f] = Number((nextProbs[f] / sum).toFixed(4));
4809
+ }
4810
+ facetProbabilities = nextProbs;
4811
+ }
4812
+ } else if (QUESTION_FACETS.includes(aFacet.choice)) {
4813
+ const chosen = aFacet.choice;
4814
+ const nextProbs = {};
4815
+ for (const f of QUESTION_FACETS) {
4816
+ nextProbs[f] = f === chosen ? 0.7 : 0.05;
4817
+ }
4818
+ facetProbabilities = nextProbs;
4819
+ }
4820
+ }
4821
+ decisionEvaluated = true;
4822
+ } catch (e) {
4823
+ console.warn("[DecisionRouter] Decision model evaluation failed, using deterministic fallback:", e?.message || e);
4824
+ }
4825
+ }
4826
+ const totalScore = Math.max(
4827
+ 0,
4828
+ Math.min(20, Math.round(readingDepth + sourceDiversity + decomposition + verificationStakes + contractScore))
4829
+ );
4830
+ let resolvedMode;
4831
+ if (requestedMode !== "auto") {
4832
+ resolvedMode = requestedMode;
4833
+ } else if (hardEscalated || totalScore >= 13) {
4834
+ resolvedMode = "deep-research";
4835
+ } else if (totalScore <= 4) {
4836
+ resolvedMode = "search";
4837
+ } else {
4838
+ resolvedMode = "research";
4839
+ }
4840
+ const channelPriors = rankChannelsByExpectedPrior(facetProbabilities, contract);
4841
+ return {
4842
+ requestedMode,
4843
+ resolvedMode,
4844
+ decisionEvaluated,
4845
+ hardEscalated,
4846
+ rubricBreakdown: {
4847
+ readingDepth: Number(readingDepth.toFixed(2)),
4848
+ sourceDiversity: Number(sourceDiversity.toFixed(2)),
4849
+ decomposition: Number(decomposition.toFixed(2)),
4850
+ verificationStakes: Number(verificationStakes.toFixed(2)),
4851
+ contractScore,
4852
+ totalScore
4853
+ },
4854
+ facetProbabilities,
4855
+ channelPriors
4856
+ };
4857
+ }
4858
+ async function evaluateAttributeCoverageWithDecision(params) {
4859
+ const { objective, targetCheckList, receiptsText, decision } = params;
4860
+ if (targetCheckList.length === 0) {
4861
+ return { satisfied: [], missing: [] };
4862
+ }
4863
+ try {
4864
+ const questions = targetCheckList.map((attr, idx) => ({
4865
+ id: `attr_${idx}`,
4866
+ type: "noul",
4867
+ criteria: `Does the collected evidence contain concrete, substantive information addressing "${attr}" for the research objective "${objective}"?`
4868
+ }));
4869
+ const res = await decision({
4870
+ context: `Research Objective: "${objective}"
4871
+
4872
+ Collected Citation Receipts:
4873
+ ${receiptsText}`,
4874
+ questions
4875
+ });
4876
+ const satisfied = [];
4877
+ const missing = [];
4878
+ targetCheckList.forEach((attr, idx) => {
4879
+ const ans = res.answers[`attr_${idx}`];
4880
+ if (ans && ans.type === "noul" && ans.probability >= 0.55) {
4881
+ satisfied.push(attr);
4882
+ } else {
4883
+ missing.push(attr);
4884
+ }
4885
+ });
4886
+ return { satisfied, missing };
4887
+ } catch (e) {
4888
+ console.warn("[DecisionRouter] Attribute coverage noul check failed:", e?.message || e);
4889
+ return null;
4890
+ }
4891
+ }
4892
+
4893
+ // src/agent/channelScheduler.ts
4894
+ function classifyChannelStatus(itemsAdded, substantiveBytes, error) {
4895
+ if (error) return "error";
4896
+ if (itemsAdded <= 0) return "empty";
4897
+ if (itemsAdded >= 2 || substantiveBytes >= 450) return "ok";
4898
+ return "weak";
4899
+ }
4900
+ async function runConcurrentRefillScheduler(params) {
4901
+ const { channelQueue, maxChannels, signal, executeChannel } = params;
4902
+ const effectiveMax = Math.max(1, maxChannels);
4903
+ const concurrency = Math.max(1, Math.min(params.concurrency ?? 2, effectiveMax));
4904
+ const queue = [...channelQueue];
4905
+ const traces = [];
4906
+ const inFlightControllers = /* @__PURE__ */ new Set();
4907
+ let okChannels = 0;
4908
+ let stopped = false;
4909
+ const abortAllInFlight = () => {
4910
+ stopped = true;
4911
+ for (const ctrl of inFlightControllers) {
4912
+ try {
4913
+ ctrl.abort();
4914
+ } catch {
4915
+ }
4916
+ }
4917
+ inFlightControllers.clear();
4918
+ };
4919
+ if (signal) {
4920
+ if (signal.aborted) {
4921
+ return { traces: [], okChannels: 0 };
4922
+ }
4923
+ signal.addEventListener("abort", abortAllInFlight, { once: true });
4924
+ }
4925
+ return new Promise((resolve) => {
4926
+ let settled = false;
4927
+ const finishIfDone = () => {
4928
+ if (settled) return;
4929
+ if (stopped || okChannels >= effectiveMax || queue.length === 0 && inFlightControllers.size === 0) {
4930
+ settled = true;
4931
+ if (signal) {
4932
+ signal.removeEventListener("abort", onExternalAbort);
4933
+ }
4934
+ abortAllInFlight();
4935
+ resolve({ traces, okChannels });
4936
+ }
4937
+ };
4938
+ const onExternalAbort = () => {
4939
+ abortAllInFlight();
4940
+ finishIfDone();
4941
+ };
4942
+ const scheduleNext = () => {
4943
+ if (settled || stopped || signal?.aborted) {
4944
+ finishIfDone();
4945
+ return;
4946
+ }
4947
+ const remainingNeeded = effectiveMax - okChannels;
4948
+ const targetInFlight = Math.min(concurrency, remainingNeeded);
4949
+ while (!stopped && inFlightControllers.size < targetInFlight && queue.length > 0) {
4950
+ const next = queue.shift();
4951
+ if (!next) break;
4952
+ const channelController = new AbortController();
4953
+ inFlightControllers.add(channelController);
4954
+ const startMs = Date.now();
4955
+ executeChannel(next.channel, next.score, channelController.signal).then((trace) => {
4956
+ inFlightControllers.delete(channelController);
4957
+ if (settled || stopped) {
4958
+ finishIfDone();
4959
+ return;
4960
+ }
4961
+ traces.push(trace);
4962
+ if (trace.status === "ok") {
4963
+ okChannels += 1;
4964
+ if (okChannels >= effectiveMax) {
4965
+ abortAllInFlight();
4966
+ finishIfDone();
4967
+ return;
4968
+ }
4969
+ }
4970
+ scheduleNext();
4971
+ }).catch((err) => {
4972
+ inFlightControllers.delete(channelController);
4973
+ if (settled || stopped) {
4974
+ finishIfDone();
4975
+ return;
4976
+ }
4977
+ traces.push({
4978
+ channel: next.channel,
4979
+ status: "error",
4980
+ priorScore: next.score,
4981
+ itemsAdded: 0,
4982
+ durationMs: Date.now() - startMs,
4983
+ errorMessage: err?.message || String(err)
4984
+ });
4985
+ scheduleNext();
4986
+ });
4987
+ }
4988
+ finishIfDone();
4989
+ };
4990
+ scheduleNext();
4991
+ });
4992
+ }
4993
+ function describeZodSchemaKeys(schema) {
4994
+ if (!schema) return void 0;
4995
+ const def = schema?._def;
4996
+ if (def?.typeName === "ZodObject" && typeof def.shape === "function") {
4997
+ const shapeObj = def.shape();
4998
+ const keys = Object.keys(shapeObj);
4999
+ if (keys.length > 0) {
5000
+ return `JSON object with required top-level keys: ${keys.map((k) => `"${k}"`).join(", ")}`;
5001
+ }
5002
+ }
5003
+ return void 0;
5004
+ }
5005
+ function resolveResearchProfile(contract) {
5006
+ if (contract.profile && contract.profile !== "auto") {
5007
+ return contract.profile;
5008
+ }
5009
+ const text = `${contract.objective} ${contract.context?.positioning || ""}`.toLowerCase();
5010
+ if (/\b(hackernews|reddit|social|pulse|trend|last 30 days|community sentiment|github stars)\b/.test(text)) {
5011
+ return "social_pulse";
5012
+ }
5013
+ if (/\b(literature review|academic|peer-reviewed|openalex|arxiv|citation|paper|cs2023)\b/.test(text)) {
5014
+ return "academic";
5015
+ }
5016
+ if (/\b(phet|oer|openstax|simulation|worksheet|unplugged)\b/.test(text)) {
5017
+ return "curriculum_oer";
5018
+ }
5019
+ if (contract.context?.hardwarePlatform || contract.context?.softwareEnv || /\b(pinout|datasheet|gpio|i2c|pwm|api|sdk|compiler|microcontroller|arduino|esp32|roblox|swift|python)\b/.test(text)) {
5020
+ return "technical";
5021
+ }
5022
+ return "general";
5023
+ }
5024
+ function isSemanticRankedHit(hit) {
5025
+ return hit.engine === "exa" || hit.engine === "tavily" || hit.engine === "academic" || typeof hit.score === "number" && hit.score > 0;
5026
+ }
5027
+ function computeNativeHitScore(hit, defaultSemantic = 8, defaultLexical = 6) {
5028
+ if (typeof hit.score === "number" && hit.score > 0) {
5029
+ const scaled = hit.score <= 1 ? hit.score * 10 : hit.score;
5030
+ return Math.max(6, Math.min(10, Math.round(scaled)));
5031
+ }
5032
+ return isSemanticRankedHit(hit) ? defaultSemantic : defaultLexical;
5033
+ }
5034
+ var ResearchSubAgent = class {
5035
+ constructor(config = {}) {
5036
+ this.config = config;
5037
+ this.searchEngine = new MultiSourceSearchEngine({
5038
+ apiKeys: config.apiKeys,
5039
+ allowEnvFallback: config.allowEnvFallback,
5040
+ customAdapter: config.customSearchAdapter
5041
+ });
5042
+ this.webScraper = new WebScraper({
5043
+ crawl4aiHost: config.crawl4aiHost,
5044
+ jinaKey: config.apiKeys?.jina,
5045
+ brightDataKey: config.apiKeys?.brightdata || config.apiKeys?.brightData,
5046
+ allowEnvFallback: config.allowEnvFallback,
5047
+ customAdapter: config.customCrawlerAdapter
5048
+ });
5049
+ this.academicEngine = new AcademicSearchEngine({
5050
+ apiKey: config.apiKeys?.semanticScholar,
5051
+ allowEnvFallback: config.allowEnvFallback,
5052
+ customAdapter: config.customAcademicSearchAdapter
5053
+ });
5054
+ this.openAlexClient = new OpenAlexClient();
5055
+ this.socialPulseHarvester = new SocialPulseHarvester(this.searchEngine);
5056
+ this.stemResearcher = new StemResourceResearcher();
5057
+ this.youtubeService = new YouTubeIngestionService();
5058
+ this.healthAuditor = new HealthAuditor();
5059
+ this.evidenceScorer = new EvidenceScorer();
5060
+ this.claimVerifier = new ClaimVerifier();
5061
+ this.provenanceTracker = new ProvenanceTracker();
5062
+ }
5063
+ searchEngine;
5064
+ webScraper;
5065
+ academicEngine;
5066
+ openAlexClient;
5067
+ socialPulseHarvester;
5068
+ stemResearcher;
5069
+ youtubeService;
5070
+ healthAuditor;
5071
+ evidenceScorer;
5072
+ claimVerifier;
5073
+ provenanceTracker;
5074
+ /**
5075
+ * Executes a complete Plan-and-Execute research campaign governed by `contract`.
5076
+ */
5077
+ async run(contract, options) {
5078
+ const llm = options?.llm ?? this.config.llm;
5079
+ const decision = options?.decision ?? this.config.decision;
5080
+ const modeTrace = await classifyModeAndPrior(contract, decision);
5081
+ const resolvedMode = modeTrace.resolvedMode;
5082
+ const modePreset = RESEARCH_MODE_PRESETS[resolvedMode];
5083
+ const resolvedProfile = resolveResearchProfile(contract);
5084
+ const profilePreset = RESEARCH_PROFILE_PRESETS[resolvedProfile];
5085
+ const ctx = contract.context ?? this.config.defaultCourseContext;
5086
+ const domain = classifyTechnicalDomain(contract.objective, void 0, ctx).domain;
5087
+ const timeoutMs = Math.max(1e3, contract.budget?.timeoutMs ?? modePreset.timeoutMs);
5088
+ const maxChannels = Math.max(1, Math.min(5, contract.budget?.maxChannels ?? modePreset.maxChannels));
5089
+ const channelConcurrency = Math.max(
5090
+ 1,
5091
+ Math.min(3, contract.budget?.channelConcurrency ?? modePreset.channelConcurrency)
5092
+ );
5093
+ const maxRounds = resolvedMode === "search" ? 1 : Math.max(1, Math.min(5, contract.budget?.maxRounds ?? modePreset.maxRounds));
5094
+ const maxQueriesPerRound = Math.max(
5095
+ 1,
5096
+ Math.min(6, contract.budget?.maxQueriesPerRound ?? modePreset.maxQueriesPerRound)
5097
+ );
5098
+ const maxScrapePerRound = resolvedMode === "search" ? contract.budget?.maxScrapePerRound ?? 0 : Math.max(0, Math.min(6, contract.budget?.maxScrapePerRound ?? modePreset.maxScrapePerRound));
5099
+ const minSources = contract.acceptanceCriteria?.minSources ?? (resolvedMode === "search" ? 1 : 2);
5100
+ const minRelevanceScore = contract.acceptanceCriteria?.minRelevanceScore ?? 6;
5101
+ const recencyDays = contract.acceptanceCriteria?.recencyDays ?? 30;
5102
+ const shouldVerifyClaims = contract.acceptanceCriteria?.verifyClaims ?? modePreset.verifyClaims;
5103
+ const harvestBudgetMs = resolvedMode === "search" ? timeoutMs : Math.floor(timeoutMs * 0.75);
5104
+ const harvestAbortController = new AbortController();
5105
+ const harvestTimer = setTimeout(() => {
5106
+ harvestAbortController.abort();
5107
+ }, harvestBudgetMs);
5108
+ if (contract.signal) {
5109
+ if (contract.signal.aborted) {
5110
+ harvestAbortController.abort();
5111
+ } else {
5112
+ contract.signal.addEventListener("abort", () => harvestAbortController.abort(), { once: true });
5113
+ }
5114
+ }
5115
+ const ledger = new EvidenceLedger();
5116
+ const executedQueries = /* @__PURE__ */ new Set();
5117
+ const scrapedUrls = /* @__PURE__ */ new Set();
5118
+ const roundTraces = [];
5119
+ const allChannelTraces = [];
5120
+ let currentMissingGaps = [
5121
+ ...contract.acceptanceCriteria?.requiredAttributes || [],
5122
+ ...contract.requiredSections || []
5123
+ ];
5124
+ try {
5125
+ for (let round = 1; round <= maxRounds; round++) {
5126
+ if (harvestAbortController.signal.aborted) {
5127
+ break;
5128
+ }
5129
+ const beforeReceiptCount = ledger.getReceipts().length;
5130
+ const plannedQueries = await this.planQueriesForRound({
5131
+ round,
5132
+ contract,
5133
+ mode: resolvedMode,
5134
+ profile: resolvedProfile,
5135
+ missingGaps: currentMissingGaps,
5136
+ receipts: ledger.getReceipts(),
5137
+ executedQueries,
5138
+ maxQueries: maxQueriesPerRound,
5139
+ llm: resolvedMode === "search" ? void 0 : llm
5140
+ });
5141
+ for (const q of plannedQueries) {
5142
+ executedQueries.add(q.toLowerCase());
5143
+ }
5144
+ const roundChannelQueue = this.buildRoundChannelQueue(
5145
+ round,
5146
+ modeTrace.channelPriors,
5147
+ profilePreset,
5148
+ contract
5149
+ );
5150
+ const schedulerResult = await runConcurrentRefillScheduler({
5151
+ channelQueue: roundChannelQueue,
5152
+ maxChannels,
5153
+ concurrency: channelConcurrency,
5154
+ signal: harvestAbortController.signal,
5155
+ executeChannel: (channel, priorScore, channelSignal) => this.executeSingleChannel({
5156
+ channel,
5157
+ priorScore,
5158
+ queries: plannedQueries,
5159
+ contract,
5160
+ domain,
5161
+ recencyDays,
5162
+ maxScrapePerRound,
5163
+ scrapedUrls,
5164
+ ledger,
5165
+ signal: channelSignal
5166
+ })
5167
+ });
5168
+ allChannelTraces.push(...schedulerResult.traces);
5169
+ const afterReceiptCount = ledger.getReceipts().length;
5170
+ const newReceiptsAdded = afterReceiptCount - beforeReceiptCount;
5171
+ const evaluation = await this.evaluateRoundGaps({
5172
+ contract,
5173
+ mode: resolvedMode,
5174
+ ledger,
5175
+ minSources,
5176
+ minRelevanceScore,
5177
+ decision: resolvedMode === "search" ? void 0 : decision,
5178
+ llm: resolvedMode === "search" ? void 0 : llm
5179
+ });
5180
+ currentMissingGaps = evaluation.missingGaps;
5181
+ roundTraces.push({
5182
+ round,
5183
+ plannedQueries,
5184
+ newReceiptsAdded,
5185
+ satisfiedAttributes: evaluation.satisfiedAttributes,
5186
+ missingGaps: evaluation.missingGaps,
5187
+ channelTraces: schedulerResult.traces
5188
+ });
5189
+ if (evaluation.missingGaps.length === 0) {
5190
+ break;
5191
+ }
5192
+ }
5193
+ } finally {
5194
+ clearTimeout(harvestTimer);
5195
+ }
5196
+ const allItems = ledger.getItems();
5197
+ const approvedItems = ledger.getApprovedItems(minRelevanceScore);
5198
+ const provenanceSidecar = this.provenanceTracker.generateSidecar(
5199
+ contract.objective,
5200
+ ledger.toProvenanceRecords(domain)
5201
+ );
5202
+ if (allItems.length === 0) {
5203
+ const failMsg = `Research Sub-Agent failed to harvest any verified sources for objective: "${contract.objective}".`;
5204
+ return {
5205
+ status: "failed",
5206
+ objective: contract.objective,
5207
+ mode: resolvedMode,
5208
+ profile: resolvedProfile,
5209
+ roundsExecuted: roundTraces.length,
5210
+ data: null,
5211
+ markdownReport: `# \u274C Research Harvest Failed: ${contract.objective}
5212
+
5213
+ > ${failMsg}
5214
+
5215
+ ### Unresolved Gaps
5216
+ ${currentMissingGaps.length > 0 ? currentMissingGaps.map((g) => `- ${g}`).join("\n") : "- No reachable sources."}`,
5217
+ tier1Summary: failMsg,
5218
+ tier2TechnicalDigest: failMsg,
5219
+ ledgerItems: [],
5220
+ receipts: [],
5221
+ validCitationIds: [],
5222
+ invalidCitationIds: [],
5223
+ missingGaps: currentMissingGaps.length > 0 ? currentMissingGaps : ["minSources not met (0 harvested)"],
5224
+ roundTraces,
5225
+ modeClassificationTrace: modeTrace,
5226
+ channelTraces: allChannelTraces,
5227
+ provenanceMd: provenanceSidecar.provenanceMd
5228
+ };
5229
+ }
5230
+ if (resolvedMode === "search") {
5231
+ const receipts = ledger.getReceipts();
5232
+ const markdownReport = this.buildDeterministicMarkdownReport(
5233
+ contract.objective,
5234
+ resolvedProfile,
5235
+ allItems,
5236
+ contract.requiredSections
5237
+ );
5238
+ const tier1Summary = allItems.slice(0, 3).map((i) => `[${i.id}] ${i.title}: ${i.keyExcerpts[0] || ""}`).join(" ");
5239
+ const tier2TechnicalDigest = allItems.slice(0, 6).map((i) => `- **[${i.id}] ${i.title}** (${i.url}): ${i.keyExcerpts.slice(0, 2).join(" ")}`).join("\n");
5240
+ return {
5241
+ status: approvedItems.length >= minSources ? "success" : "partial",
5242
+ objective: contract.objective,
5243
+ mode: resolvedMode,
5244
+ profile: resolvedProfile,
5245
+ roundsExecuted: roundTraces.length,
5246
+ data: {
5247
+ objective: contract.objective,
5248
+ mode: resolvedMode,
5249
+ sources: receipts
5250
+ },
5251
+ markdownReport,
5252
+ tier1Summary,
5253
+ tier2TechnicalDigest,
5254
+ ledgerItems: allItems,
5255
+ receipts,
5256
+ validCitationIds: allItems.map((i) => i.id),
5257
+ invalidCitationIds: [],
5258
+ missingGaps: currentMissingGaps,
5259
+ roundTraces,
5260
+ modeClassificationTrace: modeTrace,
5261
+ channelTraces: allChannelTraces,
5262
+ provenanceMd: provenanceSidecar.provenanceMd
5263
+ };
5264
+ }
5265
+ return this.synthesizeAndVerify({
5266
+ contract,
5267
+ mode: resolvedMode,
5268
+ profile: resolvedProfile,
5269
+ domain,
5270
+ ledger,
5271
+ approvedCount: approvedItems.length,
5272
+ minSources,
5273
+ shouldVerifyClaims,
5274
+ missingGaps: currentMissingGaps,
5275
+ roundTraces,
5276
+ modeClassificationTrace: modeTrace,
5277
+ channelTraces: allChannelTraces,
5278
+ provenanceMd: provenanceSidecar.provenanceMd,
5279
+ llm,
5280
+ decision
5281
+ });
5282
+ }
5283
+ /**
5284
+ * Builds the Prior-sorted channel queue for a specific round.
5285
+ */
5286
+ buildRoundChannelQueue(round, channelPriors, profilePreset, contract) {
5287
+ if (contract.preferredChannels && contract.preferredChannels.length > 0) {
5288
+ const preferredSet = new Set(contract.preferredChannels);
5289
+ const preferred = channelPriors.filter((c) => preferredSet.has(c.channel));
5290
+ const others = channelPriors.filter((c) => !preferredSet.has(c.channel));
5291
+ if (this.config.allowEnvFallback === false) {
5292
+ return preferred;
5293
+ }
5294
+ return [...preferred, ...others];
5295
+ }
5296
+ if (contract.profile && contract.profile !== "auto") {
5297
+ const filtered = channelPriors.filter((c) => {
5298
+ if (c.channel === "web_docs") return profilePreset.enableWeb;
5299
+ if (c.channel === "academic") return profilePreset.enableAcademic;
5300
+ if (c.channel === "social_pulse") return profilePreset.enableSocialPulse;
5301
+ if (c.channel === "stem_oer") return profilePreset.enableStemOer;
5302
+ return false;
5303
+ });
5304
+ if (filtered.length > 0) {
5305
+ return filtered;
5306
+ }
5307
+ }
5308
+ if (this.config.allowEnvFallback === false) {
5309
+ const isolated = channelPriors.filter((c) => {
5310
+ if (c.channel === "web_docs") return Boolean(this.config.customSearchAdapter || this.config.apiKeys);
5311
+ if (c.channel === "academic") return Boolean(this.config.customAcademicSearchAdapter || this.config.apiKeys?.semanticScholar);
5312
+ return false;
5313
+ });
5314
+ if (isolated.length > 0) {
5315
+ return isolated;
5316
+ }
5317
+ }
5318
+ if (round > 1) {
5319
+ return [...channelPriors].sort((a, b) => {
5320
+ const boostA = a.channel === "web_docs" ? 0.3 : a.channel === "academic" ? 0.2 : 0;
5321
+ const boostB = b.channel === "web_docs" ? 0.3 : b.channel === "academic" ? 0.2 : 0;
5322
+ return b.score + boostB - (a.score + boostA);
5323
+ });
5324
+ }
5325
+ return [...channelPriors];
5326
+ }
5327
+ /**
5328
+ * Executes a single source channel and classifies its outcome (`'ok' | 'weak' | 'empty' | 'error'`)
5329
+ * using Non-Redundant Evidence Gating (ADR-0019).
5330
+ */
5331
+ async executeSingleChannel(params) {
5332
+ const {
5333
+ channel,
5334
+ priorScore,
5335
+ queries,
5336
+ contract,
5337
+ domain,
5338
+ recencyDays,
5339
+ maxScrapePerRound,
5340
+ scrapedUrls,
5341
+ ledger,
5342
+ signal
5343
+ } = params;
5344
+ const startMs = Date.now();
5345
+ const beforeItems = ledger.getItems().length;
5346
+ let substantiveBytes = 0;
5347
+ try {
5348
+ if (signal.aborted) {
5349
+ return {
5350
+ channel,
5351
+ status: "empty",
5352
+ priorScore,
5353
+ itemsAdded: 0,
5354
+ durationMs: 0
5355
+ };
5356
+ }
5357
+ if (channel === "web_docs") {
5358
+ const candidateHits = [];
5359
+ for (const q of queries) {
5360
+ if (signal.aborted) break;
5361
+ try {
5362
+ const hits = await this.searchEngine.search(q, { limit: 3 });
5363
+ for (const h of hits) {
5364
+ if (!isCommercialOrNoise({ url: h.url, title: h.title, snippet: h.content })) {
5365
+ if (!candidateHits.some((existing) => existing.url === h.url)) {
5366
+ candidateHits.push(h);
5367
+ }
5368
+ }
5369
+ }
5370
+ } catch {
5371
+ }
5372
+ }
5373
+ const urlsToScrape = maxScrapePerRound > 0 ? candidateHits.filter((h) => !scrapedUrls.has(h.url)).slice(0, maxScrapePerRound) : [];
5374
+ if (urlsToScrape.length > 0 && !signal.aborted) {
5375
+ await Promise.allSettled(
5376
+ urlsToScrape.map(async (hit) => {
5377
+ if (signal.aborted) return;
5378
+ scrapedUrls.add(hit.url);
5379
+ try {
5380
+ const doc = await this.webScraper.scrapeUrl(hit.url);
5381
+ const health = this.healthAuditor.auditDocument(doc);
5382
+ if (health.passed && doc.markdownContent.trim().length > 80) {
5383
+ if (isSemanticRankedHit(hit)) {
5384
+ const nativeScore = computeNativeHitScore(hit, 8, 7);
5385
+ const takeaways = extractTopSentences(doc.markdownContent, contract.objective, 3);
5386
+ const receipt = ledger.addScrapedDocument(doc, nativeScore, takeaways);
5387
+ const added = ledger.getById(receipt.id);
5388
+ substantiveBytes += added?.rawByteSize || doc.byteSize || 1e3;
5389
+ return;
5390
+ } else {
5391
+ const scored = this.evidenceScorer.scoreDocument(doc, domain, contract.objective);
5392
+ const receipt = ledger.addScrapedDocument(doc, scored.score, scored.keyTakeaways);
5393
+ const added = ledger.getById(receipt.id);
5394
+ substantiveBytes += added?.rawByteSize || doc.byteSize || 800;
5395
+ return;
5396
+ }
5397
+ }
5398
+ } catch {
5399
+ }
5400
+ if (hit.content && hit.content.trim().length > 30) {
5401
+ const hitScore = computeNativeHitScore(hit, 7, 6);
5402
+ ledger.addSearchHit(hit, hitScore);
5403
+ substantiveBytes += Buffer.byteLength(hit.content, "utf-8");
5404
+ }
5405
+ })
5406
+ );
5407
+ }
5408
+ const remainingHits = maxScrapePerRound > 0 ? candidateHits.slice(maxScrapePerRound, maxScrapePerRound + 3) : candidateHits.slice(0, 5);
5409
+ for (const hit of remainingHits) {
5410
+ if (hit.content && hit.content.trim().length > 35) {
5411
+ const hitScore = computeNativeHitScore(hit, 7, 6);
5412
+ ledger.addSearchHit(hit, hitScore);
5413
+ substantiveBytes += Math.max(
5414
+ maxScrapePerRound === 0 ? 500 : 100,
5415
+ Buffer.byteLength(hit.content, "utf-8")
5416
+ );
5417
+ }
5418
+ }
5419
+ } else if (channel === "academic") {
5420
+ const primaryQuery = queries[0] || contract.objective;
5421
+ const [s2Papers, oaPapers] = await Promise.all([
5422
+ this.academicEngine.searchPapers(primaryQuery, { limit: 3 }).catch(() => []),
5423
+ this.openAlexClient.searchWorks(primaryQuery, { limit: 3 }).catch(() => [])
5424
+ ]);
5425
+ for (const p of [...s2Papers, ...oaPapers].slice(0, 5)) {
5426
+ const receipt = ledger.addAcademicPaper(p);
5427
+ const item = ledger.getById(receipt.id);
5428
+ substantiveBytes += Math.max(850, item?.rawByteSize || 0);
5429
+ }
5430
+ } else if (channel === "social_pulse") {
5431
+ const pulseReport = await this.socialPulseHarvester.harvest(contract.objective, {
5432
+ recencyDays,
5433
+ limitPerPlatform: 3
5434
+ });
5435
+ for (const item of pulseReport.items.slice(0, 5)) {
5436
+ ledger.addSocialPulseItem(item);
5437
+ substantiveBytes += Math.max(450, Buffer.byteLength(item.snippet || "", "utf-8"));
5438
+ }
5439
+ } else if (channel === "stem_oer") {
5440
+ const oerCatalog = await this.stemResearcher.findResources(contract.objective, {
5441
+ limit: 4
5442
+ });
5443
+ for (const res of oerCatalog.resources.slice(0, 4)) {
5444
+ ledger.addStemResource({
5445
+ title: res.title,
5446
+ url: res.url,
5447
+ description: res.description,
5448
+ provider: res.provider,
5449
+ license: res.license?.type
5450
+ });
5451
+ substantiveBytes += Math.max(500, Buffer.byteLength(res.description || "", "utf-8"));
5452
+ }
5453
+ } else if (channel === "video_media") {
5454
+ const videoQuery = `${queries[0] || contract.objective} site:youtube.com tutorial lecture`;
5455
+ const hits = await this.searchEngine.search(videoQuery, { limit: 3 });
5456
+ for (const h of hits.slice(0, 3)) {
5457
+ if (signal.aborted) break;
5458
+ if (/youtube\.com\/watch|youtu\.be\//i.test(h.url)) {
5459
+ try {
5460
+ const transcript = await this.youtubeService.fetchTranscript(h.url, ["vi", "en"]);
5461
+ if (transcript && transcript.stitchedMarkdown && transcript.stitchedMarkdown.length > 60) {
5462
+ ledger.addScrapedDocument(
5463
+ {
5464
+ url: h.url,
5465
+ title: transcript.title || h.title || "YouTube Educational Video",
5466
+ markdownContent: transcript.stitchedMarkdown,
5467
+ byteSize: Buffer.byteLength(transcript.stitchedMarkdown, "utf-8"),
5468
+ extractedCodeSnippets: [],
5469
+ tablesCount: 0,
5470
+ fetchProvider: "youtube",
5471
+ keyExcerpts: [transcript.stitchedMarkdown.slice(0, 450)]
5472
+ },
5473
+ 8
5474
+ );
5475
+ substantiveBytes += Buffer.byteLength(transcript.stitchedMarkdown, "utf-8");
5476
+ continue;
5477
+ }
5478
+ } catch {
5479
+ }
5480
+ }
5481
+ if (h.content && h.content.trim().length > 30) {
5482
+ ledger.addSearchHit(h, 6);
5483
+ substantiveBytes += Buffer.byteLength(h.content, "utf-8");
5484
+ }
5485
+ }
5486
+ }
5487
+ const itemsAdded = Math.max(0, ledger.getItems().length - beforeItems);
5488
+ const status = classifyChannelStatus(itemsAdded, substantiveBytes);
5489
+ return {
5490
+ channel,
5491
+ status,
5492
+ priorScore,
5493
+ itemsAdded,
5494
+ durationMs: Date.now() - startMs
5495
+ };
5496
+ } catch (err) {
5497
+ const itemsAdded = Math.max(0, ledger.getItems().length - beforeItems);
5498
+ return {
5499
+ channel,
5500
+ status: itemsAdded > 0 ? classifyChannelStatus(itemsAdded, substantiveBytes) : "error",
5501
+ priorScore,
5502
+ itemsAdded,
5503
+ durationMs: Date.now() - startMs,
5504
+ errorMessage: err?.message || String(err)
5505
+ };
5506
+ }
5507
+ }
5508
+ /**
5509
+ * Plans targeted search queries for Round 1 (initial coverage) or Round > 1 (surgical gap filling).
5510
+ */
5511
+ async planQueriesForRound(params) {
5512
+ const { round, contract, mode, profile, missingGaps, receipts, executedQueries, maxQueries, llm } = params;
5513
+ const ctx = contract.context ?? this.config.defaultCourseContext;
5514
+ const toolAnchor = [ctx?.hardwarePlatform, ctx?.softwareEnv].filter(Boolean).join(" ").trim();
5515
+ const baseTopic = toolAnchor ? `${toolAnchor} ${contract.objective}` : contract.objective;
5516
+ if (mode === "search") {
5517
+ return [baseTopic.trim()].slice(0, maxQueries);
5518
+ }
5519
+ if (llm) {
5520
+ try {
5521
+ const promptLines = [
5522
+ `You are a Principal Research Planner for an autonomous Plan-and-Execute Research Sub-Agent.`,
5523
+ `Objective: "${contract.objective}"`,
5524
+ `Mode: ${mode} | Profile: ${profile} | Round: ${round}`,
5525
+ toolAnchor ? `Hardware/Software Context: ${toolAnchor}` : "",
5526
+ ctx?.ageBand ? `Target Learner Age Band: ${ctx.ageBand[0]}-${ctx.ageBand[1]}` : "",
5527
+ contract.requiredSections?.length ? `Required Sections: ${contract.requiredSections.join(", ")}` : "",
5528
+ contract.acceptanceCriteria?.requiredAttributes?.length ? `Required Attributes: ${contract.acceptanceCriteria.requiredAttributes.join(", ")}` : "",
5529
+ contract.acceptanceCriteria?.requireCodeExamples ? `Must find verified code examples.` : "",
5530
+ contract.acceptanceCriteria?.requireTables ? `Must find specification/pinout tables.` : ""
5531
+ ];
5532
+ if (round > 1 && receipts.length > 0) {
5533
+ promptLines.push(
5534
+ `
5535
+ Compact Receipts Collected So Far (${receipts.length} sources):`,
5536
+ ...receipts.slice(0, 8).map(
5537
+ (r) => `- [${r.id}] ${r.title} (score:${r.relevanceScore}, code:${r.codeBlockCount}, tables:${r.tableCount}): ${r.briefExcerpt.slice(0, 140)}`
5538
+ ),
5539
+ `
5540
+ Remaining Unresolved Gaps to Fill in Round ${round}:`,
5541
+ ...missingGaps.map((g) => `- ${g}`),
5542
+ `
5543
+ Previously Executed Queries (DO NOT REPEAT): ${Array.from(executedQueries).join(" | ")}`
5544
+ );
5545
+ }
5546
+ promptLines.push(
5547
+ `
5548
+ Generate ${maxQueries} high-precision search queries to fulfill ${round === 1 ? "the objective and required attributes" : "ONLY the remaining unresolved gaps"}.`,
5549
+ `Return ONLY a valid JSON array of query strings: ["query 1", "query 2"]`
5550
+ );
5551
+ const raw = await llm(promptLines.filter(Boolean).join("\n"), {
5552
+ system: "Return strictly a valid JSON array of search query strings.",
5553
+ temperature: 0.2,
5554
+ jsonMode: true
5555
+ });
5556
+ const match = raw.match(/\[[\s\S]*\]/);
5557
+ if (match) {
5558
+ const parsed = JSON.parse(match[0]);
5559
+ if (Array.isArray(parsed)) {
5560
+ const candidateQueries = parsed.map((q) => String(q).trim()).filter((q) => q.length > 3 && !executedQueries.has(q.toLowerCase())).slice(0, maxQueries);
5561
+ if (candidateQueries.length > 0) {
5562
+ return candidateQueries;
5563
+ }
5564
+ }
5565
+ }
5566
+ } catch (e) {
5567
+ console.warn(`[ResearchSubAgent] Round ${round} LLM query planning fallback:`, e?.message || e);
5568
+ }
5569
+ }
5570
+ const fallbackQueries = [];
5571
+ if (round === 1) {
5572
+ fallbackQueries.push(
5573
+ `${baseTopic} official documentation architecture specification`.trim(),
5574
+ `${baseTopic} practical examples tutorial implementation`.trim(),
5575
+ `${baseTopic} common pitfalls debugging troubleshooting bottlenecks`.trim()
5576
+ );
5577
+ if (contract.acceptanceCriteria?.requireTables) {
5578
+ fallbackQueries.push(`${baseTopic} pinout specification comparison table`.trim());
5579
+ }
5580
+ } else {
5581
+ for (const gap of missingGaps) {
5582
+ const candidate = `${baseTopic} ${gap}`.trim();
5583
+ if (!executedQueries.has(candidate.toLowerCase())) {
5584
+ fallbackQueries.push(candidate);
5585
+ }
5586
+ }
5587
+ if (fallbackQueries.length === 0) {
5588
+ fallbackQueries.push(`${baseTopic} advanced reference guide code examples`.trim());
5589
+ }
5590
+ }
5591
+ return fallbackQueries.filter((q) => !executedQueries.has(q.toLowerCase())).slice(0, maxQueries);
5592
+ }
5593
+ /**
5594
+ * Evaluates whether the current `EvidenceLedger` satisfies `acceptanceCriteria`,
5595
+ * `requiredAttributes`, and `requiredSections`.
5596
+ * Prioritizes Decision Model (`noul`) over Generative LLM when available (ADR-0019).
5597
+ */
5598
+ async evaluateRoundGaps(params) {
5599
+ const { contract, ledger, minSources, minRelevanceScore, decision, llm } = params;
5600
+ const missingGaps = [];
5601
+ const satisfiedAttributes = [];
5602
+ const approved = ledger.getApprovedItems(minRelevanceScore);
5603
+ if (approved.length < minSources) {
5604
+ missingGaps.push(`Need at least ${minSources} verified sources with score >= ${minRelevanceScore} (currently ${approved.length})`);
5605
+ } else {
5606
+ satisfiedAttributes.push(`minSources(${approved.length}/${minSources})`);
5607
+ }
5608
+ if (contract.acceptanceCriteria?.minPeerReviewedSources) {
5609
+ const academicCount = ledger.getItems().filter((i) => i.sourceType === "academic").length;
5610
+ if (academicCount < contract.acceptanceCriteria.minPeerReviewedSources) {
5611
+ missingGaps.push(
5612
+ `Need at least ${contract.acceptanceCriteria.minPeerReviewedSources} peer-reviewed academic sources (currently ${academicCount})`
5613
+ );
5614
+ } else {
5615
+ satisfiedAttributes.push(`peerReviewedSources(${academicCount}/${contract.acceptanceCriteria.minPeerReviewedSources})`);
5616
+ }
5617
+ }
5618
+ if (contract.acceptanceCriteria?.requireCodeExamples && ledger.getTotalCodeBlocks() === 0) {
5619
+ missingGaps.push("Missing verified code examples / syntax snippets");
5620
+ } else if (contract.acceptanceCriteria?.requireCodeExamples) {
5621
+ satisfiedAttributes.push(`codeExamples(${ledger.getTotalCodeBlocks()})`);
5622
+ }
5623
+ if (contract.acceptanceCriteria?.requireTables && ledger.getTotalTables() === 0) {
5624
+ missingGaps.push("Missing specification or pinout markdown tables");
5625
+ } else if (contract.acceptanceCriteria?.requireTables) {
5626
+ satisfiedAttributes.push(`tables(${ledger.getTotalTables()})`);
5627
+ }
5628
+ const targetCheckList = [
5629
+ ...contract.acceptanceCriteria?.requiredAttributes || [],
5630
+ ...contract.requiredSections || []
5631
+ ];
5632
+ if (targetCheckList.length > 0) {
5633
+ const receipts = ledger.getReceipts();
5634
+ if (receipts.length === 0) {
5635
+ missingGaps.push(...targetCheckList);
5636
+ } else {
5637
+ const receiptsText = receipts.map((r) => `- [${r.id}] ${r.title} (headings: ${r.headings.join(", ")}): ${r.briefExcerpt}`).join("\n");
5638
+ if (decision) {
5639
+ const decEval = await evaluateAttributeCoverageWithDecision({
5640
+ objective: contract.objective,
5641
+ targetCheckList,
5642
+ receiptsText,
5643
+ decision
5644
+ });
5645
+ if (decEval) {
5646
+ satisfiedAttributes.push(...decEval.satisfied);
5647
+ missingGaps.push(...decEval.missing);
5648
+ return { satisfiedAttributes, missingGaps };
5649
+ }
5650
+ }
5651
+ if (llm) {
5652
+ try {
5653
+ const prompt = [
5654
+ `Evaluate which of the required attributes/sections are covered by the collected Citation Receipts for "${contract.objective}".`,
5655
+ `Required Items: ${JSON.stringify(targetCheckList)}`,
5656
+ `Collected Citation Receipts:
5657
+ ${receiptsText}`,
5658
+ `Return ONLY a JSON object: {"satisfied": ["item1"], "missing": ["item2"]}`
5659
+ ].join("\n");
5660
+ const raw = await llm(prompt, {
5661
+ system: 'Output strictly valid JSON object with "satisfied" and "missing" string arrays.',
5662
+ temperature: 0.1,
5663
+ jsonMode: true
5664
+ });
5665
+ const match = raw.match(/\{[\s\S]*\}/);
5666
+ if (match) {
5667
+ const parsed = JSON.parse(match[0]);
5668
+ if (Array.isArray(parsed.satisfied)) {
5669
+ satisfiedAttributes.push(...parsed.satisfied.map(String));
5670
+ }
5671
+ if (Array.isArray(parsed.missing)) {
5672
+ missingGaps.push(...parsed.missing.map(String));
5673
+ }
5674
+ return { satisfiedAttributes, missingGaps };
5675
+ }
5676
+ } catch {
5677
+ }
5678
+ }
5679
+ const lowerCorpus = ledger.buildFullRawCorpus().toLowerCase();
5680
+ for (const reqItem of targetCheckList) {
5681
+ const tokens = reqItem.toLowerCase().replace(/[^a-z0-9\u00C0-\u1EF9]+/g, " ").split(/\s+/).filter((t) => t.length >= 3);
5682
+ const matched = tokens.filter((t) => lowerCorpus.includes(t)).length;
5683
+ if (tokens.length === 0 || matched / tokens.length >= 0.5) {
5684
+ satisfiedAttributes.push(reqItem);
5685
+ } else {
5686
+ missingGaps.push(reqItem);
5687
+ }
5688
+ }
5689
+ }
5690
+ }
5691
+ return { satisfiedAttributes, missingGaps };
5692
+ }
5693
+ /**
5694
+ * Verifies claims using Decision Model `choice` (`supported | refuted | not_enough_evidence`)
5695
+ * or Generative LLM NLI (`ClaimVerifier.verifyClaims`) when `shouldVerifyClaims` is enabled (e.g., `deep-research`).
5696
+ */
5697
+ async verifyClaimsWithDecisionOrLlm(claims, sourceCorpus, options) {
5698
+ if (claims.length === 0) {
5699
+ return this.claimVerifier.verifyClaimsDeterministic([], sourceCorpus);
5700
+ }
5701
+ if (options.decision) {
5702
+ try {
5703
+ const detBaseline = this.claimVerifier.verifyClaimsDeterministic(claims, sourceCorpus);
5704
+ const res = await options.decision({
5705
+ context: `Verified Evidence Corpus:
5706
+ ${sourceCorpus.slice(0, 6e3)}`,
5707
+ questions: claims.map((claim, idx) => ({
5708
+ id: `claim_${idx}`,
5709
+ type: "choice",
5710
+ criteria: `Evaluate whether the following claim is strictly supported, directly refuted, or has not_enough_evidence in the Verified Evidence Corpus: "${claim}"`,
5711
+ options: ["supported", "refuted", "not_enough_evidence"]
5712
+ }))
5713
+ });
5714
+ const verifiedClaims = claims.map((claim, idx) => {
5715
+ const ans = res.answers[`claim_${idx}`];
5716
+ const verdict = ans?.type === "choice" && ["supported", "refuted", "not_enough_evidence"].includes(ans.choice) ? ans.choice : detBaseline.claims[idx]?.isSupported ? "supported" : "not_enough_evidence";
5717
+ const prob = ans?.probabilities?.[verdict] ?? (verdict === "supported" ? 0.85 : 0.4);
5718
+ return {
5719
+ claimText: claim,
5720
+ verdict,
5721
+ isSupported: verdict === "supported",
5722
+ isLlmVerified: true,
5723
+ confidenceScore: Math.round(prob * 100),
5724
+ extractedQuote: detBaseline.claims[idx]?.extractedQuote,
5725
+ explanation: `Evaluated via Decision Model NLI choice (${verdict}).`
5726
+ };
5727
+ });
5728
+ const supportedCount = verifiedClaims.filter((c) => c.verdict === "supported").length;
5729
+ const refutedCount = verifiedClaims.filter((c) => c.verdict === "refuted").length;
5730
+ const supportPct = supportedCount / claims.length * 100;
5731
+ const hallucinationRisk = refutedCount > 0 ? "high" : supportPct >= 75 ? "low" : "medium";
5732
+ return {
5733
+ totalClaimsChecked: claims.length,
5734
+ supportedClaimsCount: supportedCount,
5735
+ refutedClaimsCount: refutedCount,
5736
+ unverifiedClaimsCount: claims.length - supportedCount,
5737
+ hallucinationRisk,
5738
+ isLlmVerified: true,
5739
+ claims: verifiedClaims,
5740
+ reportMd: detBaseline.reportMd
5741
+ };
5742
+ } catch {
5743
+ }
5744
+ }
5745
+ if (options.llm) {
5746
+ return this.claimVerifier.verifyClaims(claims, sourceCorpus, { llm: options.llm });
5747
+ }
5748
+ return this.claimVerifier.verifyClaimsDeterministic(claims, sourceCorpus);
5749
+ }
5750
+ /**
5751
+ * Stage B: Synthesizes `EvidenceLedger` excerpts into `outputSchema<T>` + `markdownReport`
5752
+ * and runs deterministic schema, citation, and claim verification gates.
5753
+ */
5754
+ async synthesizeAndVerify(params) {
5755
+ const {
5756
+ contract,
5757
+ mode,
5758
+ profile,
5759
+ ledger,
5760
+ approvedCount,
5761
+ minSources,
5762
+ shouldVerifyClaims,
5763
+ missingGaps,
5764
+ roundTraces,
5765
+ modeClassificationTrace,
5766
+ channelTraces,
5767
+ provenanceMd,
5768
+ llm,
5769
+ decision
5770
+ } = params;
5771
+ const synthesisCorpus = ledger.buildSynthesisCorpus(12);
5772
+ const items = ledger.getItems();
5773
+ const receipts = ledger.getReceipts();
5774
+ let synthesizedData = null;
5775
+ let markdownReport = "";
5776
+ let tier1Summary = "";
5777
+ let tier2TechnicalDigest = "";
5778
+ let keyClaims = [];
5779
+ let isLlmSynthesized = false;
5780
+ const schemaHint = contract.outputSchemaDescription || describeZodSchemaKeys(contract.outputSchema) || "JSON object capturing the key structured findings, technical constraints, exemplars, and citations";
5781
+ if (llm) {
5782
+ try {
5783
+ const requiredSectionsText = contract.requiredSections && contract.requiredSections.length > 0 ? contract.requiredSections.join(", ") : "Executive Summary, Key Technical & Empirical Findings, Practical Exemplars & Code/Specs, Common Pitfalls & Bottlenecks, Verified Sources";
5784
+ const prompt = [
5785
+ `You are a Principal Research Synthesizer. Synthesize the verified EvidenceLedger sources below to fulfill the Research Contract.`,
5786
+ `Objective: "${contract.objective}"`,
5787
+ `Mode: ${mode} | Profile: ${profile}`,
5788
+ contract.context?.ageBand ? `Learner Age Band: ${contract.context.ageBand[0]}-${contract.context.ageBand[1]}` : "",
5789
+ contract.context?.hardwarePlatform ? `Hardware Platform: ${contract.context.hardwarePlatform}` : "",
5790
+ contract.context?.softwareEnv ? `Software/Tools: ${contract.context.softwareEnv}` : "",
5791
+ `Required Markdown Sections: ${requiredSectionsText}`,
5792
+ `Required Structured "data" Payload Format: ${schemaHint}`,
5793
+ contract.acceptanceCriteria?.forbiddenTerms?.length ? `Forbidden Terms (MUST NOT APPEAR): ${contract.acceptanceCriteria.forbiddenTerms.join(", ")}` : "",
5794
+ `
5795
+ CRITICAL GROUNDING RULES:`,
5796
+ `1. Every claim, metric, pinout, or recommendation MUST cite its EvidenceLedger ID in brackets, e.g. [RES-01], [RES-02].`,
5797
+ `2. NEVER invent citation IDs outside [RES-01]..[RES-${String(items.length).padStart(2, "0")}].`,
5798
+ `3. If evidence for a specific attribute is missing from the ledger, state that explicitly rather than fabricating facts.`,
5799
+ `
5800
+ === VERIFIED EVIDENCE LEDGER ===
5801
+ ${synthesisCorpus}`,
5802
+ `
5803
+ Return ONLY a valid JSON object with the exact envelope:`,
5804
+ `{`,
5805
+ ` "data": { ...structured payload matching the Required Structured "data" Payload Format... },`,
5806
+ ` "markdownReport": "# Full Markdown Report with [RES-xx] citations and Required Markdown Sections...",`,
5807
+ ` "tier1Summary": "Concise <=200-word executive summary with [RES-xx] citations",`,
5808
+ ` "tier2TechnicalDigest": "Bulleted technical digest (<=600 words) preserving concrete APIs, specs, code/tables, and pitfalls with [RES-xx] tags",`,
5809
+ ` "keyClaims": ["Core factual claim 1 from report", "Core factual claim 2"]`,
5810
+ `}`
5811
+ ].filter(Boolean).join("\n");
5812
+ const raw = await llm(prompt, {
5813
+ system: "Output strictly valid JSON matching the requested synthesis envelope. Ground every claim in [RES-xx].",
5814
+ temperature: 0.2,
5815
+ jsonMode: true
5816
+ });
5817
+ const match = raw.match(/\{[\s\S]*\}/);
5818
+ if (match) {
5819
+ const parsed = JSON.parse(match[0]);
5820
+ markdownReport = typeof parsed.markdownReport === "string" ? parsed.markdownReport : "";
5821
+ tier1Summary = typeof parsed.tier1Summary === "string" ? parsed.tier1Summary : "";
5822
+ tier2TechnicalDigest = typeof parsed.tier2TechnicalDigest === "string" ? parsed.tier2TechnicalDigest : "";
5823
+ keyClaims = Array.isArray(parsed.keyClaims) ? parsed.keyClaims.map(String) : [];
5824
+ const candidateData = parsed.data !== void 0 ? parsed.data : parsed;
5825
+ if (contract.outputSchema) {
5826
+ const validation = contract.outputSchema.safeParse(candidateData);
5827
+ if (validation.success) {
5828
+ synthesizedData = validation.data;
5829
+ isLlmSynthesized = true;
5830
+ } else {
5831
+ const issuesText = validation.error.issues.map((iss) => `${iss.path.join(".") || "root"}: ${iss.message}`).join("; ");
5832
+ const repairPrompt = [
5833
+ `The synthesized "data" object failed Zod schema validation with issues: ${issuesText}`,
5834
+ `Schema requirement: ${schemaHint}`,
5835
+ `Original candidate data: ${JSON.stringify(candidateData)}`,
5836
+ `Repair and return ONLY the valid JSON object for "data" grounded strictly in the EvidenceLedger.`
5837
+ ].join("\n");
5838
+ const repairedRaw = await llm(repairPrompt, {
5839
+ system: "Return strictly valid JSON object matching the schema.",
5840
+ temperature: 0.1,
5841
+ jsonMode: true
5842
+ });
5843
+ const repMatch = repairedRaw.match(/\{[\s\S]*\}/);
5844
+ if (repMatch) {
5845
+ const repParsed = JSON.parse(repMatch[0]);
5846
+ const repCheck = contract.outputSchema.safeParse(repParsed);
5847
+ if (repCheck.success) {
5848
+ synthesizedData = repCheck.data;
5849
+ isLlmSynthesized = true;
5850
+ } else {
5851
+ missingGaps.push(`Output schema validation incomplete: ${issuesText}`);
5852
+ }
5853
+ }
5854
+ }
5855
+ } else {
5856
+ synthesizedData = candidateData;
5857
+ isLlmSynthesized = true;
5858
+ }
5859
+ }
5860
+ } catch (e) {
5861
+ console.warn("[ResearchSubAgent] Stage B LLM synthesis error, falling back to deterministic ledger compilation:", e?.message || e);
5862
+ }
5863
+ }
5864
+ if (!markdownReport) {
5865
+ markdownReport = this.buildDeterministicMarkdownReport(contract.objective, profile, items, contract.requiredSections);
5866
+ }
5867
+ if (!tier1Summary) {
5868
+ tier1Summary = items.slice(0, 3).map((i) => `[${i.id}] ${i.title}: ${i.keyExcerpts[0] || ""}`).join(" ");
5869
+ }
5870
+ if (!tier2TechnicalDigest) {
5871
+ tier2TechnicalDigest = items.slice(0, 6).map((i) => `- **[${i.id}] ${i.title}** (${i.url}): ${i.keyExcerpts.slice(0, 2).join(" ")}`).join("\n");
5872
+ }
5873
+ if (synthesizedData === null && !contract.outputSchema) {
5874
+ synthesizedData = {
5875
+ objective: contract.objective,
5876
+ mode,
5877
+ profile,
5878
+ sources: receipts,
5879
+ codeSnippets: items.flatMap((i) => i.codeBlocks).slice(0, 4),
5880
+ tables: items.flatMap((i) => i.tables).slice(0, 4)
5881
+ };
5882
+ }
5883
+ const combinedText = `${markdownReport}
5884
+ ${tier1Summary}
5885
+ ${tier2TechnicalDigest}
5886
+ ${JSON.stringify(synthesizedData || {})}`;
5887
+ const { validCitationIds, invalidCitationIds } = ledger.verifyCitationTags(combinedText);
5888
+ if (invalidCitationIds.length > 0) {
5889
+ for (const badId of invalidCitationIds) {
5890
+ const regex = new RegExp(`\\[?${badId}\\]?`, "gi");
5891
+ markdownReport = markdownReport.replace(regex, "[UNVERIFIED-CITATION-REMOVED]");
5892
+ tier1Summary = tier1Summary.replace(regex, "");
5893
+ tier2TechnicalDigest = tier2TechnicalDigest.replace(regex, "");
5894
+ }
5895
+ }
5896
+ if (contract.acceptanceCriteria?.forbiddenTerms?.length) {
5897
+ const lowerReport = markdownReport.toLowerCase();
5898
+ for (const forbidden of contract.acceptanceCriteria.forbiddenTerms) {
5899
+ if (lowerReport.includes(forbidden.toLowerCase())) {
5900
+ missingGaps.push(`Forbidden term detected in output: "${forbidden}"`);
5901
+ }
5902
+ }
5903
+ }
5904
+ const claimsToVerify = keyClaims.length > 0 ? keyClaims : items.slice(0, 4).map((i) => i.keyExcerpts[0]).filter((e) => Boolean(e && e.length > 25));
5905
+ const claimVerification = claimsToVerify.length > 0 ? shouldVerifyClaims ? await this.verifyClaimsWithDecisionOrLlm(claimsToVerify, ledger.buildFullRawCorpus(), {
5906
+ decision,
5907
+ llm
5908
+ }) : this.claimVerifier.verifyClaimsDeterministic(claimsToVerify, ledger.buildFullRawCorpus()) : void 0;
5909
+ let status = "success";
5910
+ if (!isLlmSynthesized && llm) {
5911
+ status = "degraded";
5912
+ } else if (missingGaps.length > 0 || approvedCount < minSources || contract.outputSchema && synthesizedData === null) {
5913
+ status = "partial";
5914
+ } else if (!llm) {
5915
+ status = contract.outputSchema && synthesizedData === null ? "degraded" : "success";
5916
+ }
5917
+ return {
5918
+ status,
5919
+ objective: contract.objective,
5920
+ mode,
5921
+ profile,
5922
+ roundsExecuted: roundTraces.length,
5923
+ data: synthesizedData,
5924
+ markdownReport,
5925
+ tier1Summary,
5926
+ tier2TechnicalDigest,
5927
+ ledgerItems: items,
5928
+ receipts,
5929
+ validCitationIds,
5930
+ invalidCitationIds,
5931
+ missingGaps,
5932
+ roundTraces,
5933
+ modeClassificationTrace,
5934
+ channelTraces,
5935
+ claimVerification,
5936
+ provenanceMd
5937
+ };
5938
+ }
5939
+ buildDeterministicMarkdownReport(objective, profile, items, requiredSections) {
5940
+ const sections = requiredSections && requiredSections.length > 0 ? requiredSections : [
5941
+ "Executive Summary",
5942
+ "Verified Technical & Domain Findings",
5943
+ "Code Exemplars & Specifications",
5944
+ "Verified Source Ledger"
5945
+ ];
5946
+ const lines = [
5947
+ `# Research Synthesis Report: ${objective}`,
5948
+ `> **Profile:** \`${profile}\` | **Verified Sources:** \`${items.length}\``,
5949
+ ""
5950
+ ];
5951
+ for (const sec of sections) {
5952
+ lines.push(`## ${sec}`);
5953
+ const lower = sec.toLowerCase();
5954
+ if (lower.includes("code") || lower.includes("spec") || lower.includes("table") || lower.includes("exemplar")) {
5955
+ const blocks = items.flatMap((i) => i.codeBlocks.map((cb) => ({ id: i.id, cb }))).slice(0, 3);
5956
+ const tables = items.flatMap((i) => i.tables.map((tb) => ({ id: i.id, tb }))).slice(0, 2);
5957
+ if (blocks.length === 0 && tables.length === 0) {
5958
+ lines.push(
5959
+ ...items.slice(0, 3).map((i) => `- **[${i.id}] ${i.title}**: ${i.keyExcerpts[0] || ""}`)
5960
+ );
5961
+ } else {
5962
+ for (const b of blocks) {
5963
+ lines.push(`From **[${b.id}]**:
5964
+ \`\`\`${b.cb.language || "text"}
5965
+ ${b.cb.code.slice(0, 500)}
5966
+ \`\`\``);
5967
+ }
5968
+ for (const t of tables) {
5969
+ lines.push(`From **[${t.id}]**:
5970
+
5971
+ ${t.tb}`);
5972
+ }
5973
+ }
5974
+ } else if (lower.includes("source") || lower.includes("reference") || lower.includes("ledger")) {
5975
+ for (const item of items) {
5976
+ lines.push(`- **[${item.id}]** [${item.title}](${item.url}) (${item.sourceType}, Score: ${item.relevanceScore}/10)`);
5977
+ }
5978
+ } else {
5979
+ for (const item of items.slice(0, 6)) {
5980
+ const excerpt = item.keyExcerpts[0] || item.title;
5981
+ lines.push(`- **[${item.id}] ${item.title}**: ${excerpt}`);
5982
+ }
5983
+ }
5984
+ lines.push("");
5985
+ }
5986
+ return lines.join("\n");
5987
+ }
5988
+ };
5989
+ var ResearchAgentToolInputSchema = zod.z.object({
5990
+ objective: zod.z.string().min(3).describe("Core research question or objective to investigate"),
5991
+ mode: zod.z.enum(["auto", "search", "research", "deep-research"]).optional().describe("Execution mode: auto, search (<=8s), research (<=90s, 2 channels), or deep-research (<=300s, 5 channels)"),
5992
+ preferredChannels: zod.z.array(zod.z.enum(["web_docs", "academic", "social_pulse", "stem_oer", "video_media"])).optional().describe("Optional preferred source channels to prioritize"),
5993
+ profile: zod.z.enum([
5994
+ "auto",
5995
+ "fast_grounded",
5996
+ "deep_autonomous",
5997
+ "technical",
5998
+ "academic",
5999
+ "social_pulse",
6000
+ "curriculum_oer",
6001
+ "general"
6002
+ ]).optional().describe("Legacy domain profile"),
6003
+ requiredAttributes: zod.z.array(zod.z.string()).optional().describe("Specific technical attributes, specs, or sub-questions that must be covered"),
6004
+ requiredSections: zod.z.array(zod.z.string()).optional().describe("Required Markdown sections in the synthesized report"),
6005
+ requireCodeExamples: zod.z.boolean().optional().describe("Whether verified code snippets are required"),
6006
+ requireTables: zod.z.boolean().optional().describe("Whether markdown specification/pinout tables are required"),
6007
+ verifyClaims: zod.z.boolean().optional().describe("Whether to run semantic NLI claim verification"),
6008
+ minSources: zod.z.number().int().min(1).max(10).optional().describe("Minimum number of verified sources (default: 2)"),
6009
+ maxChannels: zod.z.number().int().min(1).max(5).optional().describe("Maximum number of ok channels to harvest"),
6010
+ maxRounds: zod.z.number().int().min(1).max(4).optional().describe("Maximum Plan-Harvest-Evaluate rounds"),
6011
+ recencyDays: zod.z.number().int().min(1).max(365).optional().describe("Recency window in days for social pulse signals"),
6012
+ hardwarePlatform: zod.z.string().optional().describe("Optional hardware context (e.g., Arduino Uno, ESP32)"),
6013
+ softwareEnv: zod.z.string().optional().describe("Optional software/IDE context (e.g., mBlock 5, Roblox Studio, Swift 6)")
6014
+ });
6015
+ async function runResearchSubAgent(contract, config = {}) {
6016
+ const agent = new ResearchSubAgent(config);
6017
+ return agent.run(contract);
6018
+ }
6019
+ function createResearchAgentTool(config = {}) {
6020
+ const agent = new ResearchSubAgent(config);
6021
+ return {
6022
+ name: "run_research_subagent",
6023
+ description: "Delegate a research objective to the autonomous Plan-and-Execute Research Sub-Agent (supports mode: auto | search | research | deep-research).",
6024
+ parameters: ResearchAgentToolInputSchema,
6025
+ execute: async (input) => {
6026
+ const result = await agent.run({
6027
+ objective: input.objective,
6028
+ mode: input.mode ?? "auto",
6029
+ preferredChannels: input.preferredChannels,
6030
+ profile: input.profile ?? "auto",
6031
+ requiredSections: input.requiredSections,
6032
+ acceptanceCriteria: {
6033
+ minSources: input.minSources ?? 2,
6034
+ requireCodeExamples: input.requireCodeExamples,
6035
+ requireTables: input.requireTables,
6036
+ verifyClaims: input.verifyClaims,
6037
+ recencyDays: input.recencyDays ?? 30,
6038
+ requiredAttributes: input.requiredAttributes
6039
+ },
6040
+ budget: {
6041
+ maxRounds: input.maxRounds,
6042
+ maxChannels: input.maxChannels
6043
+ },
6044
+ context: input.hardwarePlatform || input.softwareEnv ? {
6045
+ ...config.defaultCourseContext,
6046
+ hardwarePlatform: input.hardwarePlatform ?? config.defaultCourseContext?.hardwarePlatform,
6047
+ softwareEnv: input.softwareEnv ?? config.defaultCourseContext?.softwareEnv
6048
+ } : config.defaultCourseContext
6049
+ });
6050
+ return {
6051
+ status: result.status,
6052
+ mode: result.mode,
6053
+ profile: result.profile,
6054
+ roundsExecuted: result.roundsExecuted,
6055
+ tier1Summary: result.tier1Summary,
6056
+ tier2TechnicalDigest: result.tier2TechnicalDigest,
6057
+ markdownReport: result.markdownReport,
6058
+ citations: result.receipts,
6059
+ validCitationIds: result.validCitationIds,
6060
+ missingGaps: result.missingGaps,
6061
+ modeClassificationTrace: result.modeClassificationTrace,
6062
+ channelTraces: result.channelTraces
6063
+ };
6064
+ }
6065
+ };
6066
+ }
6067
+
6068
+ // src/services/researchKitClient.ts
6069
+ var KnowledgeDiscoveryService = class {
6070
+ constructor(config) {
6071
+ this.config = config;
6072
+ this.searchEngine = new MultiSourceSearchEngine({
6073
+ apiKeys: config.apiKeys,
6074
+ allowEnvFallback: config.allowEnvFallback,
6075
+ customAdapter: config.customSearchAdapter
6076
+ });
6077
+ this.webScraper = new WebScraper({
6078
+ crawl4aiHost: config.crawl4aiHost,
6079
+ jinaKey: config.apiKeys?.jina,
6080
+ brightDataKey: config.apiKeys?.brightdata || config.apiKeys?.brightData,
6081
+ allowEnvFallback: config.allowEnvFallback,
6082
+ customAdapter: config.customCrawlerAdapter
6083
+ });
6084
+ this.youtubeService = new YouTubeIngestionService();
6085
+ this.stemResearcher = new StemResourceResearcher();
6086
+ this.socialPulseHarvester = new SocialPulseHarvester(this.searchEngine);
6087
+ }
6088
+ searchEngine;
6089
+ webScraper;
6090
+ youtubeService;
6091
+ stemResearcher;
6092
+ socialPulseHarvester;
6093
+ async search(query, limit = 5) {
6094
+ return this.searchEngine.search(query, {
6095
+ limit,
6096
+ apiKeys: this.config.apiKeys,
6097
+ customAdapter: this.config.customSearchAdapter
6098
+ });
6099
+ }
6100
+ async scrapeUrl(url) {
6101
+ return this.webScraper.scrapeUrl(url, {
6102
+ customAdapter: this.config.customCrawlerAdapter,
6103
+ jinaKey: this.config.apiKeys?.jina
6104
+ });
6105
+ }
6106
+ async ingestYouTube(urlOrVideoId, preferredLanguages = ["vi", "en"]) {
6107
+ return this.youtubeService.fetchTranscript(urlOrVideoId, preferredLanguages);
6108
+ }
6109
+ async findStemResources(query, options) {
6110
+ return this.stemResearcher.findResources(query, options);
6111
+ }
6112
+ async searchSocialPulse(topic, options) {
6113
+ return this.socialPulseHarvester.harvest(topic, options);
6114
+ }
6115
+ };
6116
+ var TerminologyGraphService = class {
6117
+ constructor(config) {
6118
+ this.config = config;
6119
+ }
6120
+ extractor = new PedagogicalTermExtractor();
6121
+ extractConceptsDeterministic(topic, docs, domain) {
6122
+ const resolvedDomain = domain ?? classifyTechnicalDomain(topic, void 0, this.config.defaultCourseContext).domain;
6123
+ const normalizedDocs = typeof docs === "string" ? [
6124
+ {
6125
+ resourceId: "RES-01",
6126
+ doc: {
6127
+ url: "inline://corpus",
6128
+ title: topic,
6129
+ markdownContent: docs,
6130
+ byteSize: Buffer.byteLength(docs, "utf-8"),
6131
+ extractedCodeSnippets: [],
6132
+ tablesCount: 0,
6133
+ fetchProvider: "direct"
6134
+ }
6135
+ }
6136
+ ] : docs;
6137
+ return this.extractor.extractDeterministic(topic, resolvedDomain, normalizedDocs);
6138
+ }
6139
+ async extractConcepts(topic, docs, options) {
6140
+ const resolvedDomain = options?.domain ?? classifyTechnicalDomain(topic, void 0, options?.context ?? this.config.defaultCourseContext).domain;
6141
+ const normalizedDocs = typeof docs === "string" ? [
6142
+ {
6143
+ resourceId: "RES-01",
6144
+ doc: {
6145
+ url: "inline://corpus",
6146
+ title: topic,
6147
+ markdownContent: docs,
6148
+ byteSize: Buffer.byteLength(docs, "utf-8"),
6149
+ extractedCodeSnippets: [],
6150
+ keyExcerpts: [docs.slice(0, 600)],
6151
+ tablesCount: 0,
6152
+ fetchProvider: "direct"
6153
+ }
6154
+ }
6155
+ ] : docs;
6156
+ return this.extractor.extractWithOptionalLlm(topic, resolvedDomain, normalizedDocs, {
6157
+ context: options?.context ?? this.config.defaultCourseContext,
6158
+ llm: options?.llm ?? this.config.llm,
6159
+ maxTerms: options?.maxTerms
6160
+ });
6161
+ }
6162
+ formatConceptDagTsv(concepts) {
6163
+ return this.extractor.formatConceptDagTsv(concepts);
6164
+ }
6165
+ };
6166
+ var AcademicStandardsService = class {
6167
+ constructor(config) {
6168
+ this.config = config;
6169
+ this.academicSearch = new AcademicSearchEngine({
6170
+ apiKey: config.apiKeys?.semanticScholar,
6171
+ allowEnvFallback: config.allowEnvFallback,
6172
+ customAdapter: config.customAcademicSearchAdapter
6173
+ });
6174
+ }
6175
+ academicSearch;
6176
+ litSynthesizer = new LiteratureReviewSynthesizer();
6177
+ alignStandards(topic, context) {
6178
+ return mapTopicToCS2023(topic, context ?? this.config.defaultCourseContext);
6179
+ }
6180
+ async searchPapers(query, limit = 5) {
6181
+ return this.academicSearch.searchPapers(query, {
3947
6182
  limit,
3948
6183
  apiKey: this.config.apiKeys?.semanticScholar,
3949
6184
  customAdapter: this.config.customAcademicSearchAdapter
@@ -4072,8 +6307,9 @@ var ResearchKitClient = class {
4072
6307
  this.verification = new EvidenceVerificationService(config);
4073
6308
  this.orchestrator = new PedagogicalSynthesisService(config);
4074
6309
  this.grounding = new TechnicalGroundingService(config);
6310
+ this.agent = new ResearchSubAgent(config);
4075
6311
  }
4076
- /** Service 1: Multi-Engine Web Search, Scraper & YouTube Transcript Ingestion */
6312
+ /** Service 1: Multi-Engine Web Search, Scraper, YouTube Transcript & 30-Day Social Pulse */
4077
6313
  discovery;
4078
6314
  /** Service 2: Bilingual Pedagogical Term Extraction & Prerequisite Concept Graph (DAG) */
4079
6315
  terminology;
@@ -4085,6 +6321,15 @@ var ResearchKitClient = class {
4085
6321
  orchestrator;
4086
6322
  /** Service 6: Technical Grounding, Hardware/Software Compatibility & Empirical Exemplars */
4087
6323
  grounding;
6324
+ /** Service 7: Autonomous Contract-Driven Plan-and-Execute Research Sub-Agent (v1.4.0) */
6325
+ agent;
6326
+ /**
6327
+ * Unified Tri-Mode entrypoint (`'auto' | 'search' | 'research' | 'deep-research'`).
6328
+ */
6329
+ async execute(mode, input) {
6330
+ const contract = typeof input === "string" ? { objective: input, mode } : { ...input, mode };
6331
+ return this.agent.run(contract);
6332
+ }
4088
6333
  };
4089
6334
 
4090
6335
  exports.AcademicPaperSchema = AcademicPaperSchema;
@@ -4100,6 +6345,7 @@ exports.ClaimVerifier = ClaimVerifier;
4100
6345
  exports.DEFAULT_RESEARCH_CONFIG = DEFAULT_RESEARCH_CONFIG;
4101
6346
  exports.ECOMMERCE_AND_COMMERCIAL_PATTERNS = ECOMMERCE_AND_COMMERCIAL_PATTERNS;
4102
6347
  exports.ECOMMERCE_DOMAINS = ECOMMERCE_DOMAINS;
6348
+ exports.EvidenceLedger = EvidenceLedger;
4103
6349
  exports.EvidenceScorer = EvidenceScorer;
4104
6350
  exports.EvidenceVerificationService = EvidenceVerificationService;
4105
6351
  exports.GitHubCurriculumClient = GitHubCurriculumClient;
@@ -4109,32 +6355,53 @@ exports.KnowledgeDiscoveryService = KnowledgeDiscoveryService;
4109
6355
  exports.LiteratureReviewSynthesizer = LiteratureReviewSynthesizer;
4110
6356
  exports.MultiSourceSearchEngine = MultiSourceSearchEngine;
4111
6357
  exports.NasaMediaClient = NasaMediaClient;
6358
+ exports.OpenAlexClient = OpenAlexClient;
4112
6359
  exports.OpenverseClient = OpenverseClient;
6360
+ exports.PRIOR_MATRIX = PRIOR_MATRIX;
4113
6361
  exports.PedagogicalSynthesisService = PedagogicalSynthesisService;
4114
6362
  exports.PedagogicalTermExtractor = PedagogicalTermExtractor;
4115
6363
  exports.ProvenanceTracker = ProvenanceTracker;
6364
+ exports.QUESTION_FACETS = QUESTION_FACETS;
6365
+ exports.RESEARCH_MODE_PRESETS = RESEARCH_MODE_PRESETS;
6366
+ exports.RESEARCH_PROFILE_PRESETS = RESEARCH_PROFILE_PRESETS;
4116
6367
  exports.ReferencePackBuilder = ReferencePackBuilder;
6368
+ exports.ResearchAgentToolInputSchema = ResearchAgentToolInputSchema;
4117
6369
  exports.ResearchConfigSchema = ResearchConfigSchema;
4118
6370
  exports.ResearchKitClient = ResearchKitClient;
6371
+ exports.ResearchSubAgent = ResearchSubAgent;
6372
+ exports.SOURCE_CHANNELS = SOURCE_CHANNELS;
6373
+ exports.SocialPulseHarvester = SocialPulseHarvester;
4119
6374
  exports.StemResourceResearcher = StemResourceResearcher;
4120
6375
  exports.TechnicalGroundingEngine = TechnicalGroundingEngine;
4121
6376
  exports.TechnicalGroundingService = TechnicalGroundingService;
4122
6377
  exports.TerminologyGraphService = TerminologyGraphService;
4123
6378
  exports.WebScraper = WebScraper;
4124
6379
  exports.YouTubeIngestionService = YouTubeIngestionService;
6380
+ exports.classifyChannelStatus = classifyChannelStatus;
6381
+ exports.classifyModeAndPrior = classifyModeAndPrior;
4125
6382
  exports.classifyTechnicalDomain = classifyTechnicalDomain;
6383
+ exports.cleanCrossrefAbstract = cleanCrossrefAbstract;
6384
+ exports.computeContractComplexityScore = computeContractComplexityScore;
6385
+ exports.createResearchAgentTool = createResearchAgentTool;
6386
+ exports.evaluateAttributeCoverageWithDecision = evaluateAttributeCoverageWithDecision;
4126
6387
  exports.evaluateTechnicalDensity = evaluateTechnicalDensity;
4127
6388
  exports.extractSubstantiveExcerpts = extractSubstantiveExcerpts;
4128
6389
  exports.extractTopSentences = extractTopSentences;
4129
6390
  exports.extractYouTubeVideoId = extractYouTubeVideoId;
4130
6391
  exports.formatTimestamp = formatTimestamp;
6392
+ exports.inferFallbackFacetProbabilities = inferFallbackFacetProbabilities;
4131
6393
  exports.inferPrimaryCodeLanguage = inferPrimaryCodeLanguage;
4132
6394
  exports.isCommercialOrNoise = isCommercialOrNoise;
6395
+ exports.isSemanticRankedHit = isSemanticRankedHit;
4133
6396
  exports.isYouTubeUrl = isYouTubeUrl;
4134
6397
  exports.kahnTopologicalSort = kahnTopologicalSort;
4135
6398
  exports.mapTopicToCS2023 = mapTopicToCS2023;
4136
6399
  exports.normalizeUrlForDedup = normalizeUrlForDedup;
6400
+ exports.rankChannelsByExpectedPrior = rankChannelsByExpectedPrior;
4137
6401
  exports.reconstructOpenAlexAbstract = reconstructOpenAlexAbstract;
6402
+ exports.resolveResearchProfile = resolveResearchProfile;
6403
+ exports.runConcurrentRefillScheduler = runConcurrentRefillScheduler;
6404
+ exports.runResearchSubAgent = runResearchSubAgent;
4138
6405
  exports.stitchCaptionSegments = stitchCaptionSegments;
4139
6406
  exports.transitiveReduction = transitiveReduction;
4140
6407
  //# sourceMappingURL=index.cjs.map