@tangle-network/agent-knowledge 1.7.0 → 1.8.0

package/README.md

@@ -29,7 +29,8 @@ Two ways in, depending on what you're doing:
 - **Author / inspect a KB by hand** → the [CLI](#cli) (`init` → `source-add` → `index` → `search` → `lint`). Fastest way to see the shape on disk.
 - **Drive it from an agent** → pick the primitive by intent:
   - *"Does the agent have enough context to run?"* → [`buildEvalKnowledgeBundle`](#agent-eval-integration) (block / ask / acquire before execution).
-  - *"Grow the KB as a researcher"* → [`runKnowledgeResearchLoop`](#research-loop) (deterministic mechanics; your agent owns judgment) or the sandbox [researcher profile](#researcher-profile) for `runLoop`.
+  - *"Grow the KB as a researcher"* → [`runKnowledgeResearchLoop`](#research-loop) (deterministic mechanics; your agent owns judgment), [`runTwoAgentResearchLoop`](#two-agent-research-loop) (researcher proposes, verifier checks + fills gaps, offline), or the sandbox [researcher profile](#researcher-profile) for `runLoop`.
+  - *"Spawn one researcher per sub-topic and stop when the KB is ready"* → [`runResearchSupervisor`](#research-supervisor) (a supervisor brain sizes the topology over a `Scope`; LIVE, needs creds).
   - *"Does this candidate KB actually improve task success?"* → run an [agent-eval improvement loop](#agent-eval-integration) over KB variants, then `knowledgeReleaseReport` for the promotion decision.
   - *"Keep live authorities fresh"* → [pluggable sources](#pluggable-knowledge-sources) + `detectChanges` → eval re-runs.
 
@@ -260,6 +261,81 @@ await runAgentControlLoop({
 })
 ```
 
+## Two-agent research loop
+
+`runTwoAgentResearchLoop()` is the offline sibling of `runKnowledgeResearchLoop`
+with a differentiated worker/driver split over ONE knowledge base: the `worker`
+does primary research (discovers sources, proposes pages for the open gaps); the
+`driver` verifies each candidate source before it commits, optionally gap-fills
+with its own pass (`driverResearches: true`), and gates on the readiness check.
+Both are yours (no creds) — the loop owns the deterministic mechanics (indexing,
+applying write blocks, scoring readiness) and stops once no blocking gap remains.
+
+```ts
+import {
+  defineReadinessSpec,
+  runTwoAgentResearchLoop,
+} from '@tangle-network/agent-knowledge'
+
+await runTwoAgentResearchLoop({
+  root: './kb',
+  goal: 'Build a grounded onboarding wiki for billing support',
+  readinessSpecs: [defineReadinessSpec({
+    id: 'refund-policy',
+    description: 'Refund policy grounding',
+    query: 'refund policy customer request',
+    requiredFor: ['support-agent'],
+  })],
+  // WORKER: primary research targeting `ctx.gaps`. Returns a ResearchContribution.
+  async worker({ gaps, index }) {
+    return {
+      sources: [/* AddSourceTextInput for the open gaps */],
+      proposalText: '/* ---FILE: knowledge/…--- write-protocol blocks */',
+    }
+  },
+  // DRIVER: verifies each candidate source before it commits, then gates.
+  driver: {
+    verifySource(source, { gaps }) {
+      return source.uri ? { accept: true } : { accept: false, reason: 'no uri' }
+    },
+  },
+})
+```
+
+## Research supervisor
+
+`runResearchSupervisor()` is the LIVE counterpart: a supervisor brain creates the
+topology dynamically — one researcher worker per sub-topic over a `Scope` — and
+stops when the knowledge base is ready. It is a thin wrapper over `supervise()`
+from `@tangle-network/agent-runtime/loops`; it builds nothing new. The worker
+shape is the [researcher profile](#researcher-profile), and the completion oracle
+is `knowledgeReadinessDeliverable` (re-reads the KB from disk and runs the
+readiness gate, so it stops on the real grounded state, not a worker's
+self-report). Needs creds: a supervisor router brain plus a worker backend.
+
+```ts
+import { defineReadinessSpec, runResearchSupervisor } from '@tangle-network/agent-knowledge'
+
+await runResearchSupervisor({
+  root: './kb',
+  goal: 'Build a grounded onboarding wiki for billing support',
+  readinessSpecs: [defineReadinessSpec({
+    id: 'refund-policy',
+    description: 'Refund policy grounding',
+    query: 'refund policy customer request',
+    requiredFor: ['support-agent'],
+  })],
+  budget: { maxIterations: 12, maxTokens: 200_000, maxUsd: 5 },
+  // WHERE researcher workers run — the real backend seam.
+  backend: {
+    backend: 'router', // or 'sandbox' / 'cli' / 'bridge'
+    routerBaseUrl: process.env.ROUTER_BASE_URL!,
+    routerKey: process.env.ROUTER_KEY!,
+    model: 'your-worker-model',
+  },
+})
+```
+
 ## Researcher profile
 
 `@tangle-network/agent-knowledge/profiles` ships a sandbox-SDK

package/dist/chunk-MU5CEOGE.js

@@ -0,0 +1,387 @@
+// src/profiles/researcher.ts
+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 = {
+    name: "researcher-fanout",
+    async plan(task, history) {
+      return history.length === 0 ? Array.from({ length: harnesses.length }, () => task) : [];
+    },
+    // 'done' is a terminal decision in the kernel; the loop finalizes after
+    // the single fanout round and selects the winner via `defaultSelectWinner`.
+    decide() {
+      return "done";
+    },
+    describePlan() {
+      return { kind: "fanout" };
+    }
+  };
+  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);
+      const finalText = pickString(data.finalText);
+      const fenced = finalText ? extractFencedJson(finalText) : void 0;
+      const fromFinalText = fenced ? coerceResearchOutput(fenced) : void 0;
+      if (direct && !isEmptyOutput(direct)) return direct;
+      if (fromFinalText) return fromFinalText;
+      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) ?? pickString(data.finalText);
+    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 isEmptyOutput(o) {
+  return o.items.length === 0 && o.citations.length === 0 && o.proposedWrites.length === 0;
+}
+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;
+}
+
+export {
+  researcherProfile,
+  multiHarnessResearcherFanout,
+  createResearcherValidator
+};
+//# sourceMappingURL=chunk-MU5CEOGE.js.map

package/dist/chunk-MU5CEOGE.js.map

@@ -0,0 +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 type {\n  AgentProfile,\n  AgentRunSpec,\n  DefaultVerdict,\n  Driver,\n  OutputAdapter,\n  SandboxEvent,\n  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, 'done'>\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  // Single fanout round across the N harnesses, then stop: the kernel\n  // round-robins `agentRuns` over the N branches and selects the winner\n  // (best valid score) across all iterations via `defaultSelectWinner`.\n  const driver: Driver<ResearchTask, ResearchOutput, 'done'> = {\n    name: 'researcher-fanout',\n    async plan(task, history) {\n      return history.length === 0 ? Array.from({ length: harnesses.length }, () => task) : []\n    },\n    // 'done' is a terminal decision in the kernel; the loop finalizes after\n    // the single fanout round and selects the winner via `defaultSelectWinner`.\n    decide() {\n      return 'done'\n    },\n    describePlan() {\n      return { kind: 'fanout' }\n    },\n  }\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      // opencode reports the agent's terminal answer in `finalText` (not result/output).\n      // Parse it too, and prefer it when `direct` is an all-empty shape — otherwise an\n      // event carrying both `{items:[],citations:[],proposedWrites:[]}` and a rich\n      // finalText would silently drop the real answer.\n      const finalText = pickString(data.finalText)\n      const fenced = finalText ? extractFencedJson(finalText) : undefined\n      const fromFinalText = fenced ? coerceResearchOutput(fenced) : undefined\n      if (direct && !isEmptyOutput(direct)) return direct\n      if (fromFinalText) return fromFinalText\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) ?? pickString(data.finalText)\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\n/** A coerced output that carries no items, citations, or proposed writes. */\nfunction isEmptyOutput(o: ResearchOutput): boolean {\n  return o.items.length === 0 && o.citations.length === 0 && o.proposedWrites.length === 0\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":[]}

package/dist/{chunk-HKYD765Q.js → chunk-WWY5FTKQ.js}

@@ -604,7 +604,7 @@ function lintKnowledgeIndex(index) {
   const inbound = /* @__PURE__ */ new Map();
   for (const page of index.pages) inbound.set(page.id, 0);
   for (const page of index.pages) {
-    if (page.outLinks.length === 0 && !isStructural(page.path)) {
+    if (page.outLinks.length === 0 && !isScaffoldPath(page.path)) {
       findings.push({
         type: "no-outlinks",
         severity: "info",
@@ -626,7 +626,7 @@ function lintKnowledgeIndex(index) {
   for (const edge of index.graph.edges)
     inbound.set(edge.target, (inbound.get(edge.target) ?? 0) + 1);
   for (const page of index.pages) {
-    if (!isStructural(page.path) && (inbound.get(page.id) ?? 0) === 0) {
+    if (!isScaffoldPath(page.path) && (inbound.get(page.id) ?? 0) === 0) {
       findings.push({
         type: "orphan",
         severity: "info",
@@ -705,9 +705,6 @@ function lintKnowledgeIndex(index) {
   }
   return findings;
 }
-function isStructural(path) {
-  return path.endsWith("/index.md") || path.endsWith("/log.md") || path === "knowledge/index.md" || path === "knowledge/log.md";
-}
 function extractSourceRefs(text) {
   const refs = [];
   const regex = /\[\^([A-Za-z0-9_-]+)(?:#([A-Za-z0-9_.:-]+))?\]/g;
@@ -718,6 +715,12 @@ function extractSourceRefs(text) {
   return refs;
 }
 
+// src/metadata.ts
+function stringMetadata(metadata, key) {
+  const value = metadata?.[key];
+  return typeof value === "string" ? value : void 0;
+}
+
 // src/inspect.ts
 function inspectKnowledgeIndex(index, options = {}) {
   const now = options.now ?? /* @__PURE__ */ new Date();
@@ -748,10 +751,6 @@ function inspectSourceFreshness(source, now) {
   const status = validUntil && Number.isFinite(Date.parse(validUntil)) ? Date.parse(validUntil) <= now.getTime() ? "expired" : "fresh" : "unknown";
   return { id: source.id, title: source.title, uri: source.uri, status, validUntil, lastVerifiedAt };
 }
-function stringMetadata(metadata, key) {
-  const value = metadata?.[key];
-  return typeof value === "string" ? value : void 0;
-}
 function explainKnowledgeTarget(index, target) {
   const page = index.pages.find(
     (candidate) => candidate.path === target || candidate.id === target || candidate.title.toLowerCase() === target.toLowerCase()
@@ -1004,7 +1003,7 @@ function validateKnowledgeIndex(index, options = {}) {
   }
   if (options.strict) {
     for (const page of index.pages) {
-      if (isStructuralPage(page.path)) continue;
+      if (isScaffoldPath(page.path)) continue;
       if (!page.frontmatter.id || !page.frontmatter.title) {
         findings.push({
           type: "missing-frontmatter",
@@ -1017,13 +1016,11 @@ function validateKnowledgeIndex(index, options = {}) {
   }
   return { ok: !findings.some((finding) => finding.severity === "error"), findings };
 }
-function isStructuralPage(path) {
-  return path === "knowledge/index.md" || path === "knowledge/log.md" || path.endsWith("/index.md") || path.endsWith("/log.md");
-}
 
 export {
   textSourceAdapter,
   mediaTypeFor,
+  stringMetadata,
   searchKnowledge,
   tokenizeQuery,
   reciprocalRankFusion,
@@ -1063,4 +1060,4 @@ export {
   KnowledgeBaseCandidateSchema,
   validateKnowledgeIndex
 };
-//# sourceMappingURL=chunk-HKYD765Q.js.map
+//# sourceMappingURL=chunk-WWY5FTKQ.js.map