@tangle-network/agent-runtime 0.194.0 → 0.195.1

package/dist/profiles.js

@@ -1,6 +1,8 @@
-import { i as researcherProfile, n as createResearcherValidator, r as multiHarnessResearcherFanout } from "./researcher-Cp4JRbFp.js";
+import { i as ConfigError } from "./errors-CDZ8XsVj.js";
+import { t as assertExecutableAgentProfile } from "./model-policy-Wf2MxXJ9.js";
 import { n as UI_LENSES, t as UI_FINDING_SEVERITIES } from "./substrate-B0TYNrXn.js";
 import { t as coderTaskToPrompt } from "./coder-yhVWbdWc.js";
+import { agentProfileSchema } from "@tangle-network/agent-interface";
 import { promises } from "node:fs";
 import path from "node:path";
 //#region src/profiles/ui-auditor/slugify.ts
@@ -317,6 +319,457 @@ async function writeAuditIndex(workspaceDir) {
 	return out;
 }
 //#endregion
+//#region src/profiles/researcher.ts
+/**
+* Opinionated preset for source-grounded research
+* tasks. The agent is told to:
+*   - bound its work to a single `knowledgeNamespace`
+*   - emit `items[]` carrying provenance + confidence
+*   - emit `citations[]` linking quotes back to source urls
+*   - emit `proposedWrites[]` — never call materialize itself
+*   - describe `gaps` it could not answer
+*
+* The profile is stateless and agent-agnostic. The caller supplies the exact execution profile;
+* this preset adds only the researcher prompt, tools, parser, and validator.
+*
+* Propose-don't-apply: the profile NEVER writes to the knowledge base.
+* It produces `proposedWrites: KnowledgeUpdate[]` in the output. The
+* caller (gtm-agent, journey-eval, user) decides whether to feed those
+* updates through `applyKnowledgeWriteBlocks` / a KbStore put.
+*
+* Namespace isolation: every `KnowledgeItem` + `KnowledgeUpdate` in the
+* output carries `namespace`. The validator hard-fails when any item
+* touches a namespace other than `task.knowledgeNamespace`.
+*
+* @experimental
+*/
+const DEFAULT_CITATION_DENSITY_MIN = .7;
+/** Build a source-grounded researcher profile with output parsing and validation. @experimental */
+function researcherProfile(options) {
+	const base = agentProfileSchema.parse(options.profile);
+	assertExecutableAgentProfile(base, "researcherProfile");
+	const name = options.name ?? base.name;
+	const systemPrompt = options.systemPrompt ?? RESEARCHER_SYSTEM_PROMPT;
+	const citationDensityMin = options.citationDensityMin ?? DEFAULT_CITATION_DENSITY_MIN;
+	const profile = {
+		...base,
+		name,
+		description: base.description ?? "Source-grounded research agent. Propose-don't-apply.",
+		prompt: {
+			...base.prompt,
+			systemPrompt
+		},
+		tools: {
+			web_search: true,
+			fs: true,
+			shell: true,
+			...base.tools
+		},
+		metadata: {
+			...base.metadata,
+			specialty: "researcher"
+		}
+	};
+	return {
+		profile,
+		taskToPrompt: formatResearcherPrompt,
+		output: { parse: parseResearcherEvents },
+		validator: options.task ? createResearcherValidator(options.task, { citationDensityMin }) : createResearcherValidator({
+			question: "",
+			knowledgeNamespace: ""
+		}, {
+			citationDensityMin,
+			namespaceCheck: false
+		}),
+		agentRunSpec: {
+			name,
+			profile,
+			taskToPrompt: formatResearcherPrompt
+		}
+	};
+}
+/**
+* Build a fanout topology over multiple harnesses. The kernel round-robins
+* `agentRuns` across the N parallel iterations and the `FanoutVote` driver
+* picks the highest-scoring valid output.
+*
+* @experimental
+*/
+function multiHarnessResearcherFanout(options) {
+	if (options.profiles.length === 0) throw new ConfigError("multiHarnessResearcherFanout: at least one exact profile is required");
+	const agentRuns = options.profiles.map((profile) => {
+		const { agentRunSpec } = researcherProfile({ profile });
+		return agentRunSpec;
+	});
+	const { output, validator } = researcherProfile({
+		profile: options.profiles[0],
+		citationDensityMin: options.citationDensityMin,
+		task: options.task
+	});
+	return {
+		agentRuns,
+		output,
+		validator,
+		driver: {
+			name: "researcher-fanout",
+			async plan(task, history) {
+				return history.length === 0 ? Array.from({ length: agentRuns.length }, () => task) : [];
+			},
+			decide() {
+				return "done";
+			},
+			describePlan() {
+				return { kind: "fanout" };
+			}
+		}
+	};
+}
+/**
+* Build a validator that closes over a specific `ResearchTask`'s constraints.
+*
+* Checks in order:
+*   1. Items must be non-empty.
+*   2. Every item carries `evidence.length >= 1`.
+*   3. Every item + proposedWrite is scoped to `task.knowledgeNamespace`
+*      (hard-fail on any namespace mismatch — defence in depth for the
+*      multi-tenant invariant).
+*   4. Citation density (citations with quote / items) >= floor.
+*
+* Aggregate score:
+*   0.4 · citation_density
+* + 0.2 · source_diversity (distinct sources / max(items, 1))
+* + 0.2 · recency_match (mean fraction within `recencyWindow`)
+* + 0.2 · (1 − gaps/maxGaps), maxGaps = max(items, 1)
+*
+* @experimental
+*/
+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 = .4 * scores.citation_density + .2 * scores.source_diversity + .2 * scores.recency_match + .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;
+}
+/** Built-in source-grounded research contract added to a caller-owned exact profile. */
+const 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 — 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)";
+	return `${window.since ? window.since.toISOString() : "-∞"} .. ${window.until ? window.until.toISOString() : "now"}`;
+}
+/**
+* Walk the event stream and return the last structured `research.result`
+* payload. Falls back to scanning text deltas for a fenced JSON block.
+*/
+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);
+}
+/** A coerced output that carries no items, citations, or proposed writes. */
+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;
+	}
+}
+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;
+	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 item = coerceItems([entry.item])?.[0];
+			if (!item) continue;
+			out.push({
+				kind: "insert",
+				namespace,
+				item
+			});
+		} else if (entry.kind === "supersede") {
+			const previousId = pickString(entry.previousId);
+			const item = coerceItems([entry.item])?.[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;
+}
+//#endregion
 //#region src/profiles/ui-auditor/lens-prompts.ts
 /** Cross-lens rules injected into every UI audit iteration: finding quality standards and scope limits. @experimental */
 const SHARED_AUDITOR_RULES = `