@tangle-network/agent-knowledge 1.7.0 → 1.8.0

package/dist/index.js

@@ -33,13 +33,14 @@ import {
   reciprocalRankFusion,
   searchKnowledge,
   sourceRegistryPath,
+  stringMetadata,
   textSourceAdapter,
   tokenizeQuery,
   validateKnowledgeIndex,
   writeJson,
   writeKnowledgeIndex,
   writeSourceRegistry
-} from "./chunk-HKYD765Q.js";
+} from "./chunk-WWY5FTKQ.js";
 import {
   AgentMemoryHitSchema,
   AgentMemoryKindSchema,
@@ -72,6 +73,9 @@ import {
   slugify,
   stableId
 } from "./chunk-YMKHCTS2.js";
+import {
+  researcherProfile
+} from "./chunk-MU5CEOGE.js";
 
 // src/changes.ts
 function detectChanges(prev, next, options = {}) {
@@ -421,10 +425,6 @@ function sourceFreshness(sources, now) {
     expiredSourceIds
   };
 }
-function stringMetadata(metadata, key) {
-  const value = metadata?.[key];
-  return typeof value === "string" ? value : void 0;
-}
 function isIsoDate(value) {
   return Boolean(value && Number.isFinite(Date.parse(value)));
 }
@@ -837,6 +837,11 @@ function knowledgeReleaseReport(input) {
     gateDecision: input.gateDecision ?? null,
     thresholds: {
       requireCorpus: false,
+      // The report gates on RunRecord-level outcomes, not on a separate scenario
+      // corpus (KnowledgeReleaseInput carries no dataset/scenarios). The scenario
+      // floor must therefore be 0 — otherwise the corpus axis fails closed on a
+      // dimension the report has no way to satisfy, masking the run-based gate.
+      minScenarioCount: 0,
       requireHoldout: input.hasHoldout ?? false,
       minHoldoutRuns: input.hasHoldout ? 1 : 0,
       minSearchRuns: 1,
@@ -859,6 +864,19 @@ import {
   blockingKnowledgeEval,
   objectiveEval
 } from "@tangle-network/agent-eval";
+
+// src/readiness-helpers.ts
+function readinessFor(options, index) {
+  if (!options.readinessSpecs?.length) return void 0;
+  return buildEvalKnowledgeBundle({
+    ...options.readiness ?? {},
+    taskId: options.readinessTaskId ?? options.goal,
+    index,
+    specs: options.readinessSpecs
+  });
+}
+
+// src/research-loop.ts
 function createKnowledgeControlLoopAdapter(options) {
   let initialized = false;
   const appliedSteps = [];
@@ -1005,15 +1023,256 @@ async function applyKnowledgeResearchDecision(options, decision, iteration = 1)
     metadata: decision.metadata
   };
 }
-function readinessFor(options, index) {
-  if (!options.readinessSpecs?.length) return void 0;
+
+// src/research-supervisor.ts
+import {
+  supervise
+} from "@tangle-network/agent-runtime/loops";
+var RESEARCH_SUPERVISOR_SYSTEM_PROMPT = [
+  "You are a research SUPERVISOR. You do not answer the research question yourself \u2014",
+  "you create and manage a team of researcher workers that grow ONE shared",
+  "knowledge base until it is ready.",
+  "",
+  "Each round:",
+  "  1. Read the goal and the gaps the readiness gate still reports.",
+  "  2. DECOMPOSE the open work into independent sub-topics. Spawn ONE researcher",
+  "     per sub-topic (spawn_agent) \u2014 split by sub-topic, never duplicate work.",
+  "     Spawn more researchers for a broad goal, fewer for a narrow one.",
+  "  3. Wait for the researchers to settle (await_event). Steer or re-spawn for",
+  "     the sub-topics that came back thin.",
+  "  4. STOP as soon as the deliverable check reports the knowledge base is ready.",
+  "",
+  "Conserve your budget: every spawn spends from one shared pool. Prefer a small",
+  "number of well-scoped researchers over a large fanout that re-covers the same",
+  "ground."
+].join("\n");
+function knowledgeReadinessDeliverable(options) {
+  return {
+    describe: `knowledge base at ${options.root} is ready for: ${options.goal}`,
+    async check() {
+      const index = await buildKnowledgeIndex(options.root);
+      const bundle = readinessFor(options, index);
+      return (bundle?.report.blockingMissingRequirements.length ?? 0) === 0;
+    }
+  };
+}
+async function runResearchSupervisor(options) {
+  await initKnowledgeBase(options.root);
+  const { profile: workerProfile } = researcherProfile({ harness: options.harness });
+  const baseInstructions = options.supervisorSystemPrompt ?? RESEARCH_SUPERVISOR_SYSTEM_PROMPT;
+  const workerContract = workerProfile.prompt?.systemPrompt;
+  const systemPrompt = workerContract ? `${baseInstructions}
+
+Each researcher worker you spawn follows this contract:
+${workerContract}` : baseInstructions;
+  const profile = {
+    name: "research-supervisor",
+    model: options.supervisorModel,
+    systemPrompt
+  };
+  return supervise(profile, options.goal, {
+    ...options.superviseOptions,
+    budget: options.budget,
+    backend: options.backend,
+    deliverable: knowledgeReadinessDeliverable(options)
+  });
+}
+
+// src/two-agent-research-loop.ts
+async function runTwoAgentResearchLoop(options) {
+  const maxRounds = Math.max(1, options.maxRounds ?? 3);
+  await initKnowledgeBase(options.root);
+  const steps = [];
+  let index = await buildKnowledgeIndex(options.root);
+  let readiness = readinessFor(options, index);
+  let ready = isReady(readiness?.report);
+  let steer;
+  for (let round2 = 1; round2 <= maxRounds && !ready; round2++) {
+    if (options.signal?.aborted) throw new Error("Two-agent research loop aborted");
+    const gaps = gapsFromReadiness(readiness);
+    const workerContribution = await options.worker({
+      root: options.root,
+      goal: options.goal,
+      round: round2,
+      index,
+      gaps,
+      steer,
+      readiness: requireReadiness(readiness, options),
+      signal: options.signal
+    });
+    const accepted = [];
+    const rejectedWorkerSources = [];
+    const existingUris = new Set(
+      index.sources.flatMap(
+        (source) => typeof source.metadata?.originalUri === "string" ? [source.metadata.originalUri] : []
+      )
+    );
+    for (const source of workerContribution.sources ?? []) {
+      if (isDuplicate(source, existingUris, accepted)) {
+        rejectedWorkerSources.push({ source, reason: "duplicate: already in the knowledge base" });
+        continue;
+      }
+      const verdict = await options.driver.verifySource(source, {
+        root: options.root,
+        goal: options.goal,
+        round: round2,
+        index,
+        gaps,
+        acceptedThisRound: accepted,
+        signal: options.signal
+      });
+      if (verdict.accept) accepted.push(source);
+      else rejectedWorkerSources.push({ source, reason: verdict.reason });
+    }
+    const acceptedWorkerSources = await registerSources(options, accepted);
+    const writtenPages = [];
+    writtenPages.push(
+      ...await applyPages(options.root, workerContribution, acceptedWorkerSources)
+    );
+    index = await buildKnowledgeIndex(options.root);
+    readiness = readinessFor(options, index);
+    let driverSources = [];
+    let driverNotes;
+    if (options.driverResearches && options.driver.research) {
+      const remainingGaps2 = gapsFromReadiness(readiness);
+      const driverContribution = await options.driver.research({
+        root: options.root,
+        goal: options.goal,
+        round: round2,
+        index,
+        remainingGaps: remainingGaps2,
+        readiness: requireReadiness(readiness, options),
+        signal: options.signal
+      });
+      driverNotes = driverContribution.notes;
+      driverSources = await registerSources(options, driverContribution.sources ?? []);
+      writtenPages.push(...await applyPages(options.root, driverContribution, driverSources));
+      index = await buildKnowledgeIndex(options.root);
+      readiness = readinessFor(options, index);
+    }
+    ready = isReady(readiness?.report);
+    const remainingGaps = gapsFromReadiness(readiness);
+    steer = ready ? void 0 : foldGaps(options.driver, remainingGaps);
+    const step = {
+      round: round2,
+      gaps,
+      acceptedWorkerSources,
+      rejectedWorkerSources,
+      driverSources,
+      writtenPages,
+      readiness,
+      ready,
+      event: createKnowledgeEvent({
+        type: "research.iteration",
+        actor: options.actor,
+        target: options.root,
+        metadata: {
+          goal: options.goal,
+          round: round2,
+          ready,
+          acceptedWorkerSourceCount: acceptedWorkerSources.length,
+          rejectedWorkerSourceCount: rejectedWorkerSources.length,
+          driverSourceCount: driverSources.length,
+          writtenPageCount: writtenPages.length,
+          remainingGapCount: remainingGaps.length
+        }
+      }),
+      notes: { worker: workerContribution.notes, driver: driverNotes }
+    };
+    steps.push(step);
+    await options.onRound?.(step);
+  }
+  return {
+    root: options.root,
+    goal: options.goal,
+    rounds: steps.length,
+    ready,
+    index,
+    readiness,
+    steps
+  };
+}
+function isReady(report) {
+  if (!report) return false;
+  return report.blockingMissingRequirements.length === 0;
+}
+function gapsFromReadiness(readiness) {
+  if (!readiness) return [];
+  const blocking = readiness.report.blockingMissingRequirements.map(
+    (requirement) => gapFor(requirement, readiness, true)
+  );
+  const nonBlocking = readiness.report.nonBlockingGaps.map(
+    (requirement) => gapFor(requirement, readiness, false)
+  );
+  return [...blocking, ...nonBlocking];
+}
+function gapFor(requirement, readiness, blocking) {
+  const spec = readiness.requirements.find((entry) => entry.id === requirement.id);
+  const query = typeof spec?.metadata?.query === "string" ? spec.metadata.query : requirement.description;
+  return { id: requirement.id, description: requirement.description, query, blocking };
+}
+function foldGaps(driver, gaps) {
+  if (gaps.length === 0) return void 0;
+  if (driver.foldGaps) return driver.foldGaps(gaps);
+  return [
+    "The knowledge base is still missing the following. Prioritise these next round:",
+    ...gaps.map(
+      (gap) => `- (${gap.blocking ? "blocking" : "soft"}) ${gap.description} [${gap.id}]`
+    )
+  ].join("\n");
+}
+function isDuplicate(source, existingUris, accepted) {
+  return existingUris.has(source.uri) || accepted.some((candidate) => candidate.uri === source.uri);
+}
+async function registerSources(options, sources) {
+  const records = [];
+  for (const source of sources) {
+    records.push(await addSourceText(options.root, source, options.sourceOptions));
+  }
+  return records;
+}
+async function applyPages(root, contribution, acceptedSources) {
+  if (acceptedSources.length === 0) return [];
+  const parts = [];
+  if (contribution.proposalText) parts.push(contribution.proposalText);
+  const built = contribution.buildPages?.(acceptedSources);
+  if (built) parts.push(built);
+  if (parts.length === 0) return [];
+  const applied = await applyKnowledgeWriteBlocks(root, parts.join("\n"));
+  return applied.written;
+}
+function requireReadiness(readiness, options) {
+  if (readiness) return readiness;
   return buildEvalKnowledgeBundle({
     ...options.readiness ?? {},
     taskId: options.readinessTaskId ?? options.goal,
-    index,
-    specs: options.readinessSpecs
+    index: emptyIndex(options.root),
+    specs: []
   });
 }
+function emptyIndex(root) {
+  return {
+    root,
+    generatedAt: (/* @__PURE__ */ new Date(0)).toISOString(),
+    sources: [],
+    pages: [],
+    graph: { nodes: [], edges: [] }
+  };
+}
+function sourceMatchesGaps(source, index, gaps) {
+  const haystack = `${source.title ?? ""}
+${source.text}`.toLowerCase();
+  const hits = [];
+  for (const gap of gaps) {
+    for (const token of gap.query.toLowerCase().split(/\s+/).filter(Boolean)) {
+      if (haystack.includes(token)) {
+        hits.push(...searchKnowledge(index, gap.query, 1));
+        break;
+      }
+    }
+  }
+  return hits;
+}
 export {
   AgentMemoryHitSchema,
   AgentMemoryKindSchema,
@@ -1033,6 +1292,7 @@ export {
   MemoryKbStore,
   POLITE_USER_AGENT,
   READINESS_SPEC_DEFAULTS,
+  RESEARCH_SUPERVISOR_SYSTEM_PROMPT,
   SCAFFOLD_PAGE_BASENAMES,
   SourceAnchorSchema,
   SourceRecordSchema,
@@ -1069,6 +1329,7 @@ export {
   inspectKnowledgeIndex,
   isSafeKnowledgePath,
   isScaffoldPath,
+  knowledgeReadinessDeliverable,
   knowledgeReleaseReport,
   layoutFor,
   lintKnowledgeIndex,
@@ -1087,9 +1348,12 @@ export {
   reciprocalRankFusion,
   renderMemoryContext,
   runKnowledgeResearchLoop,
+  runResearchSupervisor,
+  runTwoAgentResearchLoop,
   searchKnowledge,
   sha256,
   slugify,
+  sourceMatchesGaps,
   sourceRegistryPath,
   stableId,
   stripFrontmatter,