@tangle-network/agent-knowledge 1.7.0 → 1.8.0

package/dist/profiles/index.js

@@ -1,365 +1,8 @@
-// src/profiles/researcher.ts
 import {
-  createFanoutVoteDriver
-} from "@tangle-network/agent-runtime/loops";
-var DEFAULT_HARNESS = "opencode/zai-coding-plan/glm-5.1";
-var DEFAULT_CITATION_DENSITY_MIN = 0.7;
-function researcherProfile(options = {}) {
-  const harness = options.harness ?? DEFAULT_HARNESS;
-  const name = options.name ?? `researcher-${harness}`;
-  const systemPrompt = options.systemPrompt ?? DEFAULT_RESEARCHER_SYSTEM_PROMPT;
-  const citationDensityMin = options.citationDensityMin ?? DEFAULT_CITATION_DENSITY_MIN;
-  const profile = {
-    name,
-    description: "Source-grounded research agent. Propose-don't-apply.",
-    prompt: { systemPrompt },
-    model: options.model ? { default: options.model } : void 0,
-    tools: { web_search: true, fs: true, shell: true },
-    metadata: { backendType: harness, role: "researcher" }
-  };
-  const output = { parse: parseResearcherEvents };
-  const validator = options.task ? createResearcherValidator(options.task, { citationDensityMin }) : createResearcherValidator(
-    { question: "", knowledgeNamespace: "" },
-    { citationDensityMin, namespaceCheck: false }
-  );
-  const agentRunSpec = {
-    name,
-    profile,
-    taskToPrompt: formatResearcherPrompt
-  };
-  return { profile, taskToPrompt: formatResearcherPrompt, output, validator, agentRunSpec };
-}
-function multiHarnessResearcherFanout(options = {}) {
-  const harnesses = options.harnesses && options.harnesses.length > 0 ? options.harnesses : ["opencode/zai-coding-plan/glm-5.1", "claude-code", "codex"];
-  const models = options.models ?? [];
-  const agentRuns = harnesses.map((harness, i) => {
-    const { agentRunSpec } = researcherProfile({ harness, model: models[i] });
-    return agentRunSpec;
-  });
-  const { output, validator } = researcherProfile({
-    citationDensityMin: options.citationDensityMin,
-    task: options.task
-  });
-  const driver = createFanoutVoteDriver({ n: harnesses.length });
-  return { agentRuns, output, validator, driver };
-}
-function createResearcherValidator(task, config = {}) {
-  const citationDensityMin = config.citationDensityMin ?? DEFAULT_CITATION_DENSITY_MIN;
-  const namespaceCheck = config.namespaceCheck ?? true;
-  return {
-    async validate(output) {
-      const notes = [];
-      const scores = {};
-      let pass = true;
-      if (!Array.isArray(output.items) || output.items.length === 0) {
-        pass = false;
-        notes.push("no items");
-        scores.items = 0;
-      } else {
-        scores.items = 1;
-      }
-      const missingEvidence = (output.items ?? []).filter(
-        (item) => !Array.isArray(item.evidence) || item.evidence.length === 0
-      );
-      if (missingEvidence.length > 0) {
-        pass = false;
-        notes.push(`${missingEvidence.length} item(s) without evidence`);
-        scores.provenance = 0;
-      } else {
-        scores.provenance = 1;
-      }
-      if (namespaceCheck) {
-        const foreignItems = (output.items ?? []).filter(
-          (item) => item.namespace !== task.knowledgeNamespace
-        );
-        const foreignWrites = (output.proposedWrites ?? []).filter(
-          (write) => write.namespace !== task.knowledgeNamespace
-        );
-        if (foreignItems.length > 0 || foreignWrites.length > 0) {
-          pass = false;
-          notes.push(
-            `namespace violation: ${foreignItems.length} item(s) + ${foreignWrites.length} write(s) outside ${task.knowledgeNamespace}`
-          );
-          scores.namespace = 0;
-        } else {
-          scores.namespace = 1;
-        }
-      }
-      const itemCount = Math.max(output.items?.length ?? 0, 1);
-      const citationsWithQuote = (output.citations ?? []).filter(
-        (citation) => typeof citation.quote === "string" && citation.quote.length > 0
-      ).length;
-      const citationDensity = Math.min(1, citationsWithQuote / itemCount);
-      if (citationDensity < citationDensityMin) {
-        pass = false;
-        notes.push(
-          `citation density ${citationDensity.toFixed(2)} below floor ${citationDensityMin.toFixed(2)}`
-        );
-      }
-      scores.citation_density = citationDensity;
-      const sourceSet = /* @__PURE__ */ new Set();
-      for (const item of output.items ?? []) {
-        for (const evidence of item.evidence ?? []) {
-          if (evidence.source) sourceSet.add(evidence.source);
-        }
-      }
-      scores.source_diversity = Math.min(1, sourceSet.size / itemCount);
-      scores.recency_match = recencyMatchScore(output.items ?? [], task.recencyWindow);
-      const maxGaps = itemCount;
-      const gapCount = output.gaps?.length ?? 0;
-      scores.gap_coverage = Math.max(0, 1 - gapCount / maxGaps);
-      const score = 0.4 * scores.citation_density + 0.2 * scores.source_diversity + 0.2 * scores.recency_match + 0.2 * scores.gap_coverage;
-      const verdict = {
-        valid: pass,
-        score: Number.isFinite(score) ? score : 0,
-        scores
-      };
-      if (notes.length > 0) verdict.notes = notes.join("; ");
-      return verdict;
-    }
-  };
-}
-function recencyMatchScore(items, window) {
-  if (!window || window.since === void 0 && window.until === void 0) return 1;
-  if (items.length === 0) return 0;
-  const sinceMs = window.since?.getTime() ?? Number.NEGATIVE_INFINITY;
-  const untilMs = window.until?.getTime() ?? Number.POSITIVE_INFINITY;
-  let hits = 0;
-  let total = 0;
-  for (const item of items) {
-    for (const evidence of item.evidence ?? []) {
-      if (typeof evidence.capturedAt !== "number") continue;
-      total += 1;
-      if (evidence.capturedAt >= sinceMs && evidence.capturedAt <= untilMs) hits += 1;
-    }
-  }
-  return total === 0 ? 0 : hits / total;
-}
-var DEFAULT_RESEARCHER_SYSTEM_PROMPT = [
-  "You are a research agent. Your job is to answer a research question with",
-  "source-grounded knowledge items that the caller will choose whether to",
-  "persist to a multi-tenant knowledge base.",
-  "",
-  "Hard rules:",
-  "  1. Every item you emit MUST carry the task's knowledgeNamespace exactly.",
-  "     Never write to a different namespace.",
-  "  2. Every item MUST carry at least one evidence entry with a source.",
-  "     A quote + url is strongly preferred; capturedAt is unix ms.",
-  "  3. You propose writes \u2014 you do NOT apply them. The caller decides.",
-  "  4. Self-report confidence honestly in [0, 1]. Do not inflate.",
-  "  5. List what you could not answer in `gaps`. Better to admit a gap",
-  "     than fabricate.",
-  "",
-  "When you finish, emit a single final structured message of the shape:",
-  "  ```json",
-  '  { "items": [{ "id": "...", "namespace": "...", "claim": "...",',
-  '                "evidence": [{ "source": "...", "quote": "...",',
-  '                               "url": "...", "capturedAt": 0 }],',
-  '                "confidence": 0.0,',
-  '                "authoredBy": { "kind": "agent", "id": "..." } }],',
-  '    "citations": [{ "url": "...", "quote": "...", "confidence": 0.0 }],',
-  '    "proposedWrites": [{ "kind": "insert", "namespace": "...",',
-  '                         "item": { /* same shape as items[] */ } }],',
-  '    "gaps": ["..."],',
-  '    "notes": "free-form commentary" }',
-  "  ```"
-].join("\n");
-function formatResearcherPrompt(task) {
-  const sources = task.sources?.length ? task.sources.join(", ") : "(no preference)";
-  const window = formatRecencyWindow(task.recencyWindow);
-  return [
-    `Question: ${task.question}`,
-    `Knowledge namespace (DO NOT cross): ${task.knowledgeNamespace}`,
-    `Scope: ${task.scope ?? "(unspecified)"}`,
-    `Preferred sources: ${sources}`,
-    `Recency window: ${window}`,
-    `Max items: ${task.maxItems ?? "(no cap)"}`,
-    `Per-item minimum confidence: ${task.minConfidence ?? "(no floor)"}`,
-    "",
-    "Produce knowledge items with provenance + citations + proposed writes.",
-    "List gaps for anything you could not answer. Emit the final JSON",
-    "result block exactly as instructed."
-  ].join("\n");
-}
-function formatRecencyWindow(window) {
-  if (!window) return "(none)";
-  const since = window.since ? window.since.toISOString() : "-\u221E";
-  const until = window.until ? window.until.toISOString() : "now";
-  return `${since} .. ${until}`;
-}
-function parseResearcherEvents(events) {
-  for (let i = events.length - 1; i >= 0; i -= 1) {
-    const event = events[i];
-    if (!event) continue;
-    const type = String(event.type ?? "");
-    const data = isRecord(event.data) ? event.data : {};
-    if (type === "result" || type === "final" || type === "research.result") {
-      const direct = coerceResearchOutput(data.result ?? data.output ?? data);
-      if (direct) return direct;
-    }
-  }
-  for (let i = events.length - 1; i >= 0; i -= 1) {
-    const event = events[i];
-    if (!event) continue;
-    const data = isRecord(event.data) ? event.data : {};
-    const text = pickString(data.text) ?? pickString(data.delta);
-    if (!text) continue;
-    const fenced = extractFencedJson(text);
-    if (!fenced) continue;
-    const coerced = coerceResearchOutput(fenced);
-    if (coerced) return coerced;
-  }
-  return { items: [], citations: [], proposedWrites: [] };
-}
-function isRecord(value) {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-function pickString(value) {
-  return typeof value === "string" && value.length > 0 ? value : void 0;
-}
-function extractFencedJson(text) {
-  const match = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
-  if (!match) return void 0;
-  const body = (match[1] ?? "").trim();
-  if (!body) return void 0;
-  try {
-    return JSON.parse(body);
-  } catch {
-    return void 0;
-  }
-}
-function coerceResearchOutput(value) {
-  if (!isRecord(value)) return void 0;
-  const items = coerceItems(value.items);
-  const citations = coerceCitations(value.citations);
-  const proposedWrites = coerceProposedWrites(value.proposedWrites);
-  if (items === void 0 && citations === void 0 && proposedWrites === void 0) {
-    return void 0;
-  }
-  const output = {
-    items: items ?? [],
-    citations: citations ?? [],
-    proposedWrites: proposedWrites ?? []
-  };
-  if (Array.isArray(value.gaps)) {
-    output.gaps = value.gaps.filter((entry) => typeof entry === "string");
-  }
-  const notes = pickString(value.notes);
-  if (notes) output.notes = notes;
-  const known = /* @__PURE__ */ new Set(["items", "citations", "proposedWrites", "gaps", "notes"]);
-  const extras = {};
-  let extrasCount = 0;
-  for (const [key, val] of Object.entries(value)) {
-    if (known.has(key)) continue;
-    extras[key] = val;
-    extrasCount += 1;
-  }
-  if (extrasCount > 0) output.raw = extras;
-  return output;
-}
-function coerceItems(value) {
-  if (!Array.isArray(value)) return void 0;
-  const out = [];
-  for (const entry of value) {
-    if (!isRecord(entry)) continue;
-    const id = pickString(entry.id);
-    const namespace = pickString(entry.namespace);
-    const claim = pickString(entry.claim);
-    const evidence = coerceEvidence(entry.evidence);
-    const confidence = toFiniteNumber(entry.confidence);
-    const authoredBy = coerceAuthoredBy(entry.authoredBy);
-    if (!id || !namespace || !claim || !authoredBy) continue;
-    const item = {
-      id,
-      namespace,
-      claim,
-      evidence,
-      confidence: clamp01(confidence),
-      authoredBy
-    };
-    if (Array.isArray(entry.supersedes)) {
-      item.supersedes = entry.supersedes.filter((s) => typeof s === "string");
-    }
-    const retractedAt = toFiniteNumber(entry.retractedAt);
-    if (retractedAt > 0) item.retractedAt = retractedAt;
-    out.push(item);
-  }
-  return out;
-}
-function coerceEvidence(value) {
-  if (!Array.isArray(value)) return [];
-  const out = [];
-  for (const entry of value) {
-    if (!isRecord(entry)) continue;
-    const source = pickString(entry.source);
-    if (!source) continue;
-    const item = {
-      source,
-      capturedAt: toFiniteNumber(entry.capturedAt)
-    };
-    const quote = pickString(entry.quote);
-    if (quote) item.quote = quote;
-    const url = pickString(entry.url);
-    if (url) item.url = url;
-    out.push(item);
-  }
-  return out;
-}
-function coerceAuthoredBy(value) {
-  if (!isRecord(value)) return void 0;
-  const kind = value.kind === "human" || value.kind === "agent" ? value.kind : void 0;
-  const id = pickString(value.id);
-  if (!kind || !id) return void 0;
-  return { kind, id };
-}
-function coerceCitations(value) {
-  if (!Array.isArray(value)) return void 0;
-  const out = [];
-  for (const entry of value) {
-    if (!isRecord(entry)) continue;
-    const url = pickString(entry.url);
-    const quote = pickString(entry.quote);
-    if (!url || !quote) continue;
-    out.push({ url, quote, confidence: clamp01(toFiniteNumber(entry.confidence)) });
-  }
-  return out;
-}
-function coerceProposedWrites(value) {
-  if (!Array.isArray(value)) return void 0;
-  const out = [];
-  for (const entry of value) {
-    if (!isRecord(entry)) continue;
-    const namespace = pickString(entry.namespace);
-    if (!namespace) continue;
-    if (entry.kind === "insert") {
-      const items = coerceItems([entry.item]);
-      const item = items?.[0];
-      if (!item) continue;
-      out.push({ kind: "insert", namespace, item });
-    } else if (entry.kind === "supersede") {
-      const previousId = pickString(entry.previousId);
-      const items = coerceItems([entry.item]);
-      const item = items?.[0];
-      if (!previousId || !item) continue;
-      out.push({ kind: "supersede", namespace, previousId, item });
-    } else if (entry.kind === "retract") {
-      const itemId = pickString(entry.itemId);
-      const reason = pickString(entry.reason);
-      if (!itemId || !reason) continue;
-      out.push({ kind: "retract", namespace, itemId, reason });
-    }
-  }
-  return out;
-}
-function toFiniteNumber(value) {
-  return typeof value === "number" && Number.isFinite(value) ? value : 0;
-}
-function clamp01(value) {
-  if (!Number.isFinite(value)) return 0;
-  if (value < 0) return 0;
-  if (value > 1) return 1;
-  return value;
-}
+  createResearcherValidator,
+  multiHarnessResearcherFanout,
+  researcherProfile
+} from "../chunk-MU5CEOGE.js";
 export {
   createResearcherValidator,
   multiHarnessResearcherFanout,

package/dist/profiles/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/profiles/researcher.ts"],"sourcesContent":["/**\n * @experimental\n *\n * `researcherProfile` — opinionated preset for source-grounded research\n * tasks. The agent is told to:\n *   - bound its work to a single `knowledgeNamespace`\n *   - emit `items[]` carrying provenance + confidence\n *   - emit `citations[]` linking quotes back to source urls\n *   - emit `proposedWrites[]` — never call materialize itself\n *   - describe `gaps` it could not answer\n *\n * The profile is stateless and agent-agnostic. `harness` selects the\n * sandbox-SDK backend. For heterogeneous fanout, use\n * `multiHarnessResearcherFanout`.\n *\n * Propose-don't-apply: the profile NEVER writes to the knowledge base.\n * It produces `proposedWrites: KnowledgeUpdate[]` in the output. The\n * caller (gtm-agent, journey-eval, user) decides whether to feed those\n * updates through `applyKnowledgeWriteBlocks` / a KbStore put.\n *\n * Namespace isolation: every `KnowledgeItem` + `KnowledgeUpdate` in the\n * output carries `namespace`. The validator hard-fails when any item\n * touches a namespace other than `task.knowledgeNamespace`.\n */\n\nimport {\n  type AgentProfile,\n  type AgentRunSpec,\n  createFanoutVoteDriver,\n  type DefaultVerdict,\n  type Driver,\n  type OutputAdapter,\n  type SandboxEvent,\n  type Validator,\n} from '@tangle-network/agent-runtime/loops'\n\n/** @experimental */\nexport type ResearchSource = 'web' | 'corpus' | 'twitter' | 'github' | 'docs'\n\n/** @experimental */\nexport interface ResearchTask {\n  /** The research question to answer. */\n  question: string\n  /** Bound: e.g. \"audience for cpg-founder ICP\". */\n  scope?: string\n  /** Multi-tenant scope (customer-id, workspace-id). Validator enforces. */\n  knowledgeNamespace: string\n  sources?: ResearchSource[]\n  recencyWindow?: { since?: Date; until?: Date }\n  maxItems?: number\n  /** Per-item minimum confidence in [0, 1]. Validator scores recall vs this. */\n  minConfidence?: number\n}\n\n/**\n * Knowledge item emitted by the researcher.\n *\n * Profile-local type. When agent-knowledge promotes `KnowledgeClaim` →\n * top-level `KnowledgeItem` substrate-wide, these fields collapse 1:1.\n *\n * @experimental\n */\nexport interface KnowledgeItem {\n  id: string\n  /** Multi-tenant scope. MUST equal `task.knowledgeNamespace`. */\n  namespace: string\n  /** The factual claim, in the researcher's words. */\n  claim: string\n  /** Provenance — at least one entry required. */\n  evidence: Array<{ source: string; quote?: string; url?: string; capturedAt: number }>\n  /** Researcher's self-reported confidence in [0, 1]. */\n  confidence: number\n  /** Prior item ids this supersedes (chain). */\n  supersedes?: string[]\n  /** Set if the agent is retracting an earlier item. Unix ms. */\n  retractedAt?: number\n  authoredBy: { kind: 'human' | 'agent'; id: string }\n}\n\n/**\n * A proposed write to the knowledge base. The profile does NOT apply\n * these — the caller decides.\n *\n * @experimental\n */\nexport type KnowledgeUpdate =\n  | { kind: 'insert'; namespace: string; item: KnowledgeItem }\n  | { kind: 'supersede'; namespace: string; previousId: string; item: KnowledgeItem }\n  | { kind: 'retract'; namespace: string; itemId: string; reason: string }\n\n/**\n * Researcher output. Required fields are typed; optional fields preserve\n * the agent's free-form intelligence (`notes`, `raw`). The validator\n * enforces the typed minimum.\n *\n * @experimental\n */\nexport interface ResearchOutput {\n  items: KnowledgeItem[]\n  citations: Array<{ url: string; quote: string; confidence: number }>\n  proposedWrites: KnowledgeUpdate[]\n  gaps?: string[]\n  notes?: string\n  /** Anything the agent emitted beyond the typed fields. */\n  raw?: unknown\n}\n\n/** @experimental */\nexport interface ResearcherProfileOptions {\n  /** Sandbox-SDK backend.type. Default `'opencode/zai-coding-plan/glm-5.1'`. */\n  harness?: string\n  /** Default model id passed in `AgentProfile.model.default`. */\n  model?: string\n  /** Custom system prompt replacement. Default = built-in researcher preset. */\n  systemPrompt?: string\n  /** Stable name for `AgentRunSpec.name`. Default = `researcher-${harness}`. */\n  name?: string\n  /**\n   * Default 0.7. Minimum (citations with quote) / items ratio for `valid=true`.\n   * Below this floor, citation_density scores < 1 and the item set is gated.\n   */\n  citationDensityMin?: number\n}\n\nconst DEFAULT_HARNESS = 'opencode/zai-coding-plan/glm-5.1'\nconst DEFAULT_CITATION_DENSITY_MIN = 0.7\n\n/** @experimental */\nexport function researcherProfile(\n  options: ResearcherProfileOptions & { task?: ResearchTask } = {},\n): {\n  profile: AgentProfile\n  taskToPrompt: (task: ResearchTask) => string\n  output: OutputAdapter<ResearchOutput>\n  validator: Validator<ResearchOutput>\n  agentRunSpec: AgentRunSpec<ResearchTask>\n} {\n  const harness = options.harness ?? DEFAULT_HARNESS\n  const name = options.name ?? `researcher-${harness}`\n  const systemPrompt = options.systemPrompt ?? DEFAULT_RESEARCHER_SYSTEM_PROMPT\n  const citationDensityMin = options.citationDensityMin ?? DEFAULT_CITATION_DENSITY_MIN\n  const profile: AgentProfile = {\n    name,\n    description: \"Source-grounded research agent. Propose-don't-apply.\",\n    prompt: { systemPrompt },\n    model: options.model ? { default: options.model } : undefined,\n    tools: { web_search: true, fs: true, shell: true },\n    metadata: { backendType: harness, role: 'researcher' },\n  }\n  const output: OutputAdapter<ResearchOutput> = { parse: parseResearcherEvents }\n  const validator: Validator<ResearchOutput> = options.task\n    ? createResearcherValidator(options.task, { citationDensityMin })\n    : createResearcherValidator(\n        { question: '', knowledgeNamespace: '' },\n        { citationDensityMin, namespaceCheck: false },\n      )\n  const agentRunSpec: AgentRunSpec<ResearchTask> = {\n    name,\n    profile,\n    taskToPrompt: formatResearcherPrompt,\n  }\n  return { profile, taskToPrompt: formatResearcherPrompt, output, validator, agentRunSpec }\n}\n\n/** @experimental */\nexport interface MultiHarnessResearcherFanoutOptions {\n  /** Backend.type identifiers, one per parallel agent. */\n  harnesses?: string[]\n  /** Optional per-harness model override. Indexed parallel to `harnesses`. */\n  models?: (string | undefined)[]\n  /** Default citation density floor for the shared validator. */\n  citationDensityMin?: number\n  /** Optional task — narrows the validator's namespace check. */\n  task?: ResearchTask\n}\n\n/**\n * Build a fanout topology over multiple harnesses. The kernel round-robins\n * `agentRuns` across the N parallel iterations and the `FanoutVote` driver\n * picks the highest-scoring valid output.\n *\n * @experimental\n */\nexport function multiHarnessResearcherFanout(options: MultiHarnessResearcherFanoutOptions = {}): {\n  agentRuns: AgentRunSpec<ResearchTask>[]\n  output: OutputAdapter<ResearchOutput>\n  validator: Validator<ResearchOutput>\n  driver: Driver<ResearchTask, ResearchOutput, 'pick-winner' | 'fail'>\n} {\n  const harnesses =\n    options.harnesses && options.harnesses.length > 0\n      ? options.harnesses\n      : ['opencode/zai-coding-plan/glm-5.1', 'claude-code', 'codex']\n  const models = options.models ?? []\n  const agentRuns = harnesses.map((harness, i) => {\n    const { agentRunSpec } = researcherProfile({ harness, model: models[i] })\n    return agentRunSpec\n  })\n  const { output, validator } = researcherProfile({\n    citationDensityMin: options.citationDensityMin,\n    task: options.task,\n  })\n  const driver = createFanoutVoteDriver<ResearchTask, ResearchOutput>({ n: harnesses.length })\n  return { agentRuns, output, validator, driver }\n}\n\n/**\n * Build a validator that closes over a specific `ResearchTask`'s constraints.\n *\n * Checks in order:\n *   1. Items must be non-empty.\n *   2. Every item carries `evidence.length >= 1`.\n *   3. Every item + proposedWrite is scoped to `task.knowledgeNamespace`\n *      (hard-fail on any namespace mismatch — defence in depth for the\n *      multi-tenant invariant).\n *   4. Citation density (citations with quote / items) >= floor.\n *\n * Aggregate score:\n *   0.4 · citation_density\n * + 0.2 · source_diversity (distinct sources / max(items, 1))\n * + 0.2 · recency_match (mean fraction within `recencyWindow`)\n * + 0.2 · (1 − gaps/maxGaps), maxGaps = max(items, 1)\n *\n * @experimental\n */\nexport function createResearcherValidator(\n  task: ResearchTask,\n  config: { citationDensityMin?: number; namespaceCheck?: boolean } = {},\n): Validator<ResearchOutput> {\n  const citationDensityMin = config.citationDensityMin ?? DEFAULT_CITATION_DENSITY_MIN\n  const namespaceCheck = config.namespaceCheck ?? true\n  return {\n    async validate(output) {\n      const notes: string[] = []\n      const scores: Record<string, number> = {}\n      let pass = true\n\n      if (!Array.isArray(output.items) || output.items.length === 0) {\n        pass = false\n        notes.push('no items')\n        scores.items = 0\n      } else {\n        scores.items = 1\n      }\n\n      const missingEvidence = (output.items ?? []).filter(\n        (item) => !Array.isArray(item.evidence) || item.evidence.length === 0,\n      )\n      if (missingEvidence.length > 0) {\n        pass = false\n        notes.push(`${missingEvidence.length} item(s) without evidence`)\n        scores.provenance = 0\n      } else {\n        scores.provenance = 1\n      }\n\n      if (namespaceCheck) {\n        const foreignItems = (output.items ?? []).filter(\n          (item) => item.namespace !== task.knowledgeNamespace,\n        )\n        const foreignWrites = (output.proposedWrites ?? []).filter(\n          (write) => write.namespace !== task.knowledgeNamespace,\n        )\n        if (foreignItems.length > 0 || foreignWrites.length > 0) {\n          pass = false\n          notes.push(\n            `namespace violation: ${foreignItems.length} item(s) + ${foreignWrites.length} write(s) ` +\n              `outside ${task.knowledgeNamespace}`,\n          )\n          scores.namespace = 0\n        } else {\n          scores.namespace = 1\n        }\n      }\n\n      const itemCount = Math.max(output.items?.length ?? 0, 1)\n      const citationsWithQuote = (output.citations ?? []).filter(\n        (citation) => typeof citation.quote === 'string' && citation.quote.length > 0,\n      ).length\n      const citationDensity = Math.min(1, citationsWithQuote / itemCount)\n      if (citationDensity < citationDensityMin) {\n        pass = false\n        notes.push(\n          `citation density ${citationDensity.toFixed(2)} below floor ${citationDensityMin.toFixed(2)}`,\n        )\n      }\n      scores.citation_density = citationDensity\n\n      const sourceSet = new Set<string>()\n      for (const item of output.items ?? []) {\n        for (const evidence of item.evidence ?? []) {\n          if (evidence.source) sourceSet.add(evidence.source)\n        }\n      }\n      scores.source_diversity = Math.min(1, sourceSet.size / itemCount)\n\n      scores.recency_match = recencyMatchScore(output.items ?? [], task.recencyWindow)\n\n      const maxGaps = itemCount\n      const gapCount = output.gaps?.length ?? 0\n      scores.gap_coverage = Math.max(0, 1 - gapCount / maxGaps)\n\n      const score =\n        0.4 * scores.citation_density +\n        0.2 * scores.source_diversity +\n        0.2 * scores.recency_match +\n        0.2 * scores.gap_coverage\n\n      const verdict: DefaultVerdict = {\n        valid: pass,\n        score: Number.isFinite(score) ? score : 0,\n        scores,\n      }\n      if (notes.length > 0) verdict.notes = notes.join('; ')\n      return verdict\n    },\n  }\n}\n\nfunction recencyMatchScore(items: KnowledgeItem[], window: ResearchTask['recencyWindow']): number {\n  if (!window || (window.since === undefined && window.until === undefined)) return 1\n  if (items.length === 0) return 0\n  const sinceMs = window.since?.getTime() ?? Number.NEGATIVE_INFINITY\n  const untilMs = window.until?.getTime() ?? Number.POSITIVE_INFINITY\n  let hits = 0\n  let total = 0\n  for (const item of items) {\n    for (const evidence of item.evidence ?? []) {\n      if (typeof evidence.capturedAt !== 'number') continue\n      total += 1\n      if (evidence.capturedAt >= sinceMs && evidence.capturedAt <= untilMs) hits += 1\n    }\n  }\n  return total === 0 ? 0 : hits / total\n}\n\nconst DEFAULT_RESEARCHER_SYSTEM_PROMPT = [\n  'You are a research agent. Your job is to answer a research question with',\n  'source-grounded knowledge items that the caller will choose whether to',\n  'persist to a multi-tenant knowledge base.',\n  '',\n  'Hard rules:',\n  \"  1. Every item you emit MUST carry the task's knowledgeNamespace exactly.\",\n  '     Never write to a different namespace.',\n  '  2. Every item MUST carry at least one evidence entry with a source.',\n  '     A quote + url is strongly preferred; capturedAt is unix ms.',\n  '  3. You propose writes — you do NOT apply them. The caller decides.',\n  '  4. Self-report confidence honestly in [0, 1]. Do not inflate.',\n  '  5. List what you could not answer in `gaps`. Better to admit a gap',\n  '     than fabricate.',\n  '',\n  'When you finish, emit a single final structured message of the shape:',\n  '  ```json',\n  '  { \"items\": [{ \"id\": \"...\", \"namespace\": \"...\", \"claim\": \"...\",',\n  '                \"evidence\": [{ \"source\": \"...\", \"quote\": \"...\",',\n  '                               \"url\": \"...\", \"capturedAt\": 0 }],',\n  '                \"confidence\": 0.0,',\n  '                \"authoredBy\": { \"kind\": \"agent\", \"id\": \"...\" } }],',\n  '    \"citations\": [{ \"url\": \"...\", \"quote\": \"...\", \"confidence\": 0.0 }],',\n  '    \"proposedWrites\": [{ \"kind\": \"insert\", \"namespace\": \"...\",',\n  '                         \"item\": { /* same shape as items[] */ } }],',\n  '    \"gaps\": [\"...\"],',\n  '    \"notes\": \"free-form commentary\" }',\n  '  ```',\n].join('\\n')\n\nfunction formatResearcherPrompt(task: ResearchTask): string {\n  const sources = task.sources?.length ? task.sources.join(', ') : '(no preference)'\n  const window = formatRecencyWindow(task.recencyWindow)\n  return [\n    `Question: ${task.question}`,\n    `Knowledge namespace (DO NOT cross): ${task.knowledgeNamespace}`,\n    `Scope: ${task.scope ?? '(unspecified)'}`,\n    `Preferred sources: ${sources}`,\n    `Recency window: ${window}`,\n    `Max items: ${task.maxItems ?? '(no cap)'}`,\n    `Per-item minimum confidence: ${task.minConfidence ?? '(no floor)'}`,\n    '',\n    'Produce knowledge items with provenance + citations + proposed writes.',\n    'List gaps for anything you could not answer. Emit the final JSON',\n    'result block exactly as instructed.',\n  ].join('\\n')\n}\n\nfunction formatRecencyWindow(window: ResearchTask['recencyWindow']): string {\n  if (!window) return '(none)'\n  const since = window.since ? window.since.toISOString() : '-∞'\n  const until = window.until ? window.until.toISOString() : 'now'\n  return `${since} .. ${until}`\n}\n\n/**\n * Walk the event stream and return the last structured `research.result`\n * payload. Falls back to scanning text deltas for a fenced JSON block.\n */\nfunction parseResearcherEvents(events: SandboxEvent[]): ResearchOutput {\n  for (let i = events.length - 1; i >= 0; i -= 1) {\n    const event = events[i]\n    if (!event) continue\n    const type = String(event.type ?? '')\n    const data = isRecord(event.data) ? event.data : {}\n    if (type === 'result' || type === 'final' || type === 'research.result') {\n      const direct = coerceResearchOutput(data.result ?? data.output ?? data)\n      if (direct) return direct\n    }\n  }\n  for (let i = events.length - 1; i >= 0; i -= 1) {\n    const event = events[i]\n    if (!event) continue\n    const data = isRecord(event.data) ? event.data : {}\n    const text = pickString(data.text) ?? pickString(data.delta)\n    if (!text) continue\n    const fenced = extractFencedJson(text)\n    if (!fenced) continue\n    const coerced = coerceResearchOutput(fenced)\n    if (coerced) return coerced\n  }\n  return { items: [], citations: [], proposedWrites: [] }\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return value !== null && typeof value === 'object' && !Array.isArray(value)\n}\n\nfunction pickString(value: unknown): string | undefined {\n  return typeof value === 'string' && value.length > 0 ? value : undefined\n}\n\nfunction extractFencedJson(text: string): unknown | undefined {\n  const match = text.match(/```(?:json)?\\s*([\\s\\S]*?)```/i)\n  if (!match) return undefined\n  const body = (match[1] ?? '').trim()\n  if (!body) return undefined\n  try {\n    return JSON.parse(body)\n  } catch {\n    return undefined\n  }\n}\n\nfunction coerceResearchOutput(value: unknown): ResearchOutput | undefined {\n  if (!isRecord(value)) return undefined\n  const items = coerceItems(value.items)\n  const citations = coerceCitations(value.citations)\n  const proposedWrites = coerceProposedWrites(value.proposedWrites)\n  // Reject completely empty payloads — those signal \"no result block\",\n  // not \"a valid empty result\".\n  if (items === undefined && citations === undefined && proposedWrites === undefined) {\n    return undefined\n  }\n  const output: ResearchOutput = {\n    items: items ?? [],\n    citations: citations ?? [],\n    proposedWrites: proposedWrites ?? [],\n  }\n  if (Array.isArray(value.gaps)) {\n    output.gaps = value.gaps.filter((entry): entry is string => typeof entry === 'string')\n  }\n  const notes = pickString(value.notes)\n  if (notes) output.notes = notes\n  // Preserve any extra fields the agent emitted that don't fit the typed\n  // surface — callers can inspect `raw` without forcing them through the\n  // typed coercion. We only include `raw` when the agent emitted fields\n  // beyond the known set.\n  const known = new Set(['items', 'citations', 'proposedWrites', 'gaps', 'notes'])\n  const extras: Record<string, unknown> = {}\n  let extrasCount = 0\n  for (const [key, val] of Object.entries(value)) {\n    if (known.has(key)) continue\n    extras[key] = val\n    extrasCount += 1\n  }\n  if (extrasCount > 0) output.raw = extras\n  return output\n}\n\nfunction coerceItems(value: unknown): KnowledgeItem[] | undefined {\n  if (!Array.isArray(value)) return undefined\n  const out: KnowledgeItem[] = []\n  for (const entry of value) {\n    if (!isRecord(entry)) continue\n    const id = pickString(entry.id)\n    const namespace = pickString(entry.namespace)\n    const claim = pickString(entry.claim)\n    const evidence = coerceEvidence(entry.evidence)\n    const confidence = toFiniteNumber(entry.confidence)\n    const authoredBy = coerceAuthoredBy(entry.authoredBy)\n    if (!id || !namespace || !claim || !authoredBy) continue\n    const item: KnowledgeItem = {\n      id,\n      namespace,\n      claim,\n      evidence,\n      confidence: clamp01(confidence),\n      authoredBy,\n    }\n    if (Array.isArray(entry.supersedes)) {\n      item.supersedes = entry.supersedes.filter((s): s is string => typeof s === 'string')\n    }\n    const retractedAt = toFiniteNumber(entry.retractedAt)\n    if (retractedAt > 0) item.retractedAt = retractedAt\n    out.push(item)\n  }\n  return out\n}\n\nfunction coerceEvidence(value: unknown): KnowledgeItem['evidence'] {\n  if (!Array.isArray(value)) return []\n  const out: KnowledgeItem['evidence'] = []\n  for (const entry of value) {\n    if (!isRecord(entry)) continue\n    const source = pickString(entry.source)\n    if (!source) continue\n    const item: KnowledgeItem['evidence'][number] = {\n      source,\n      capturedAt: toFiniteNumber(entry.capturedAt),\n    }\n    const quote = pickString(entry.quote)\n    if (quote) item.quote = quote\n    const url = pickString(entry.url)\n    if (url) item.url = url\n    out.push(item)\n  }\n  return out\n}\n\nfunction coerceAuthoredBy(value: unknown): KnowledgeItem['authoredBy'] | undefined {\n  if (!isRecord(value)) return undefined\n  const kind = value.kind === 'human' || value.kind === 'agent' ? value.kind : undefined\n  const id = pickString(value.id)\n  if (!kind || !id) return undefined\n  return { kind, id }\n}\n\nfunction coerceCitations(value: unknown): ResearchOutput['citations'] | undefined {\n  if (!Array.isArray(value)) return undefined\n  const out: ResearchOutput['citations'] = []\n  for (const entry of value) {\n    if (!isRecord(entry)) continue\n    const url = pickString(entry.url)\n    const quote = pickString(entry.quote)\n    if (!url || !quote) continue\n    out.push({ url, quote, confidence: clamp01(toFiniteNumber(entry.confidence)) })\n  }\n  return out\n}\n\nfunction coerceProposedWrites(value: unknown): KnowledgeUpdate[] | undefined {\n  if (!Array.isArray(value)) return undefined\n  const out: KnowledgeUpdate[] = []\n  for (const entry of value) {\n    if (!isRecord(entry)) continue\n    const namespace = pickString(entry.namespace)\n    if (!namespace) continue\n    if (entry.kind === 'insert') {\n      const items = coerceItems([entry.item])\n      const item = items?.[0]\n      if (!item) continue\n      out.push({ kind: 'insert', namespace, item })\n    } else if (entry.kind === 'supersede') {\n      const previousId = pickString(entry.previousId)\n      const items = coerceItems([entry.item])\n      const item = items?.[0]\n      if (!previousId || !item) continue\n      out.push({ kind: 'supersede', namespace, previousId, item })\n    } else if (entry.kind === 'retract') {\n      const itemId = pickString(entry.itemId)\n      const reason = pickString(entry.reason)\n      if (!itemId || !reason) continue\n      out.push({ kind: 'retract', namespace, itemId, reason })\n    }\n  }\n  return out\n}\n\nfunction toFiniteNumber(value: unknown): number {\n  return typeof value === 'number' && Number.isFinite(value) ? value : 0\n}\n\nfunction clamp01(value: number): number {\n  if (!Number.isFinite(value)) return 0\n  if (value < 0) return 0\n  if (value > 1) return 1\n  return value\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/docs/recursive-research-leaf.md

@@ -0,0 +1,86 @@
+# Skill: spawn a driver-loop as a leaf for a large sub-topic
+
+Supervisor-facing guidance. The `runResearchSupervisor` brain (see
+`src/research-supervisor.ts`) decomposes a goal into sub-topics and spawns one
+researcher per sub-topic over the live `Scope`. By default each spawn is a **bare
+worker**: a single researcher pass that adds sources and proposes pages.
+
+For a **large** sub-topic, a single worker pass under-covers it. The recursive
+move is to spawn, in place of that bare worker, a **driver-loop leaf** — a child
+that is itself a driver running its own worker (the two-agent loop), so the
+sub-topic gets verify + gap-fill + readiness-gate iteration, not one shot.
+
+`agent-runtime`'s `Scope.spawn(agent, task, opts)` makes this a first-class
+recursion: the spawned `Agent` can itself be a driver, not just a worker. The
+supervisor spawns a child `Agent` whose `act(task, childScope)` runs
+`runTwoAgentResearchLoop` (or its own `runResearchSupervisor`) scoped to the
+sub-topic, against the SAME knowledge base root, with a sub-topic-scoped slice of
+readiness specs. The conserved budget pool reserves `opts.budget` for the child
+atomically and refunds the unspent remainder on settle, so a driver-loop leaf
+spends from the same pool a bare worker would have — depth costs budget, not extra
+budget.
+
+## When it's worth it
+
+Spawn a driver-loop leaf (instead of a bare worker) for a sub-topic when ANY of
+these hold; otherwise spawn a bare worker.
+
+| Signal | Bare worker | Driver-loop leaf |
+| --- | --- | --- |
+| **Breadth** — distinct readiness specs the sub-topic must close | 1–2 | 3+ |
+| **Depth** — does a fact need a source THEN a derived claim citing it? | shallow (source ≈ answer) | layered (source → claim → cross-check) |
+| **Expected rounds** — passes to reach no-blocking-gaps for the sub-topic | ~1 | 2+ (a worker's first pass predictably leaves blocking gaps) |
+| **Verification risk** — is a wrong/duplicate source likely and costly here? | low | high (the leaf's driver rejects bad sources before they commit) |
+| **Budget headroom** — iterations/tokens left in the pool for this branch | tight | comfortable (a leaf needs ≥ ~3× a worker's per-pass spend) |
+
+Rule of thumb: **breadth ≥ 3 specs OR expected rounds ≥ 2 OR high verification
+risk ⇒ driver-loop leaf.** A sub-topic that is one fact from one source is a bare
+worker — wrapping it in a driver only burns budget on a loop that stops after
+round 1.
+
+## The shape
+
+```ts
+import type { Agent, Scope } from '@tangle-network/agent-runtime/loops'
+import { runTwoAgentResearchLoop, type TwoAgentResearchLoopResult } from '@tangle-network/agent-knowledge'
+
+// For a LARGE sub-topic, spawn a sub-driver leaf that runs the two-agent loop
+// scoped to that sub-topic. The child shares the KB root and the conserved
+// budget pool; it gets its own driver (verify + fill + gate) instead of a single
+// worker pass. The child is an `Agent` whose `act` IS the two-agent loop.
+const researchLeaf: Agent<typeof subTopic, TwoAgentResearchLoopResult> = {
+  name: `research-leaf:${subTopic.id}`,
+  async act(task, childScope: Scope<TwoAgentResearchLoopResult>) {
+    return runTwoAgentResearchLoop({
+      root, // the SAME knowledge base
+      goal: task.goal,
+      worker, // the sub-topic researcher
+      driver, // verifies the worker's sources, gap-fills, gates on readiness
+      driverResearches: true, // the leaf's driver also researches the missed gaps
+      readinessSpecs: task.specs, // the sub-topic's slice of the gate
+      signal: childScope.signal,
+    })
+  },
+}
+
+// Reserves `budget` from the conserved pool atomically; refunds on settle.
+const spawned = scope.spawn(researchLeaf, subTopic, {
+  label: `research-leaf:${subTopic.id}`,
+  budget: perSubTopicBudget, // a slice of the conserved pool
+})
+if (!spawned.ok) {
+  // fail-closed: 'budget-exhausted' | 'depth-exceeded' — spawn a bare worker or stop.
+}
+```
+
+A bare worker, by contrast, is `scope.spawn(workerFromBackend(backend)(...), …)`
+of the researcher profile — no inner driver, no per-sub-topic readiness gate, one
+pass.
+
+## Why this is a leaf, not a fork
+
+The driver-loop leaf is still ONE branch of the supervisor's tree. It reads and
+writes the same knowledge base, settles back through the same `Scope`, and
+spends from the same budget pool. The recursion is depth (a sub-driver inside a
+branch), not a second knowledge base — there is exactly one KB, and the
+supervisor's readiness gate over the whole KB is still what ends the run.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-knowledge",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Source-grounded, eval-gated knowledge growth primitives for agents.",
   "homepage": "https://github.com/tangle-network/agent-knowledge#readme",
   "repository": {
@@ -68,14 +68,14 @@
     "format": "biome format --write src tests"
   },
   "dependencies": {
-    "@tangle-network/agent-eval": ">=0.77.0 <0.80.0",
-    "@tangle-network/agent-runtime": "^0.44.0",
+    "@tangle-network/agent-eval": "^0.100.0",
+    "@tangle-network/agent-runtime": "^0.77.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.15",
     "@neo4j-labs/agent-memory": "0.4.0",
-    "@tangle-network/sandbox": "^0.4.0",
+    "@tangle-network/sandbox": "^0.8.0",
     "@types/node": "^25.6.0",
     "tsup": "^8.0.0",
     "typescript": "^5.7.0",