@tangle-network/agent-runtime 0.337.2 → 0.339.0

package/dist/intelligence.js

@@ -1,20 +1,20 @@
-import { Da as defaultRedactor, Pn as resolveAgentEnvironmentProvider, Tr as toOtelAttributes, _r as buildRuntimeEventOtelSpans, br as flatOtelSpan, hr as buildLoopOtelSpans, ka as resolveRedactor, ui as authoredAgentIdentity, yr as createOtelExporter } from "./supervisor-Rz8AGpYb.js";
-import { F as canonicalCandidateDigest$1, z as immutableCandidateValue } from "./sandbox-profile-compat-QTkLe1Z6.js";
-import { a as createRuntimeUsageTotals, i as addRuntimeUsage, n as executeAgentImprovementActivation, o as isUsageAmount, r as verifyAgentImprovementActivationResult, t as createAgentImprovementActivationResult } from "./activation-BDP6Eivv.js";
-import { C as optimizationActivationReceiptFromMetadata, D as agentImprovementProfileSurfaceDigest, E as agentImprovementProfileDiffs, F as isAgentImprovementProfileSurface, I as isAgentProfileMeasuredSurface, N as assertProfileImprovementTargetsShareIdentity, O as agentImprovementProfileSurfaceInput, P as buildAgentImprovementActivationTargets, S as createOptimizationActivationReceipt, T as AGENT_PROFILE_MEASURED_SURFACES, V as assertProfileTrainingIsHeldOut, _ as profilePolicyWithBudget, a as executeAgentCandidateExperimentCell, b as profileTaskScenarioIdentity, d as verifyAgentImprovementActivation, f as verifyAgentImprovementProposal, g as profileImprovementMetadata, h as createProfileImprovementCostLedger, i as createAgentImprovementProposal, j as agentImprovementTargetProfileDiffs, l as reviewAgentImprovementProposal, m as verifyCandidateExecutionEvidence, n as createAgentImprovementActivation, o as proposeAgentImprovement, p as verifyAgentImprovementReview, r as createAgentImprovementMeasuredComparison, s as proposeAgentProfileImprovement, t as AgentCandidateExperimentCellExecutionError, u as runAgentCandidateExperiment, v as profilePreparationAccounting, w as AGENT_IMPROVEMENT_PROFILE_SURFACES, x as sealProfileImprovementBenchmark, y as profileStateDigest$1 } from "./improvement-cycle-D1I4hQvf.js";
-import { a as AGENT_CANDIDATE_EXECUTION_SUPPORT } from "./prepare-CER-ZkPp.js";
-import { d as omitUndefinedObjectFields, f as parseAgentCandidateProfileActivation, i as applyExactAgentProfileDiff, p as parseExactAgentProfile } from "./profile-gNUsHNIJ.js";
-import { n as exactProcessProviderAsCandidateExecutor, t as createProtectedAgentCandidateModelPort } from "./protected-model-port-BuRsviSL.js";
-import { agentImprovementSourceSchema, agentProfileImprovementArmSchema, applyAgentProfileDiff } from "@tangle-network/agent-interface";
-import { contentHash } from "@tangle-network/agent-eval";
+import { Ii as defaultRedactor, Kr as authoredAgentIdentity, Nt as resolveAgentEnvironmentProvider, Ri as resolveRedactor, an as buildRuntimeEventOtelSpans, cn as flatOtelSpan, pn as toOtelAttributes, rn as buildLoopOtelSpans, sn as createOtelExporter } from "./supervisor-DHrUJhEZ.js";
+import { B as omitTopLevelDigest, F as canonicalCandidateDigest$1, H as verifyCanonicalCandidateDocument, I as canonicalCandidateDocument, P as canonicalCandidateBytes$1, z as immutableCandidateValue } from "./sandbox-profile-compat-BzVBFqrz.js";
+import { a as assertProfileTrainingIsHeldOut, f as addRuntimeUsage, l as rethrowAfterCleanup, m as isUsageAmount, p as createRuntimeUsageTotals, t as improve } from "./improve-BOXTLWJ3.js";
+import { _ as agentImprovementTargetProfileDiffs, a as reviewAgentImprovementProposal, b as isAgentProfileMeasuredSurface, c as verifyAgentImprovementProposal, d as attachOptimizationActivationReceipt, f as createOptimizationActivationReceipt, g as agentImprovementProfileSurfaceInput, h as agentImprovementProfileSurfaceDigest, i as executeAgentImprovementActivation, l as verifyAgentImprovementReview, m as agentImprovementProfileDiffs, n as createAgentImprovementActivationResult, o as verifyAgentImprovementActivation, p as optimizationActivationReceiptFromMetadata, r as createAgentImprovementProposal, s as verifyAgentImprovementActivationResult, t as createAgentImprovementActivation, u as assertNoCallerOptimizationReceipt, v as assertProfileImprovementTargetsShareIdentity, y as isAgentImprovementProfileSurface } from "./activation-CVSFxis9.js";
+import { _ as parseAgentCandidateProfileActivation, a as applyExactAgentProfileDiff, d as createAgentCandidateProfileActivation, g as omitUndefinedObjectFields, m as materializeAgentCandidateProfilePlan, o as assertCandidateProfileBinding, v as parseExactAgentProfile } from "./profile-Dpei_Sq0.js";
+import { t as runAnalystLoop } from "./analyst-loop-DZw5QWT9.js";
+import { C as verifiedResourceTextByDigest, S as AGENT_CANDIDATE_EXECUTION_SUPPORT, n as executePreparedAgentCandidate, t as prepareAgentCandidateExecution, w as verifyAgentCandidateBundle, x as exactProcessProviderAsCandidateExecutor, y as createProtectedAgentCandidateModelPort } from "./prepare-bXkvPMJA.js";
+import { AGENT_IMPROVEMENT_SOURCE_METADATA_KEY, agentCandidateMaterializationReceiptSchema, agentCandidateRunReceiptSchema, agentImprovementSourceMetadata, agentImprovementSourceSchema, agentProfileImprovementArmSchema, applyAgentProfileDiff, candidateExecutionEvidenceSchema, numbersApproximatelyEqual } from "@tangle-network/agent-interface";
+import { CostLedger, contentHash } from "@tangle-network/agent-eval";
 import { ATTR, agentIdentityAttributes } from "@tangle-network/agent-trace-contract";
 import { assertProposalFindings } from "@tangle-network/agent-eval/analyst";
-import { measuredComparisonFromAgentProfileImprovementExperiment, runAgentProfileImprovementExperiment, sealAgentProfileImprovementExperiment, verifyAgentProfileImprovementExperimentComparison } from "@tangle-network/agent-eval/contract";
+import { campaignSplitDigestFromIdentities } from "@tangle-network/agent-eval/campaign";
+import { measuredComparisonFromAgentProfileImprovementExperiment, measuredComparisonFromCandidateExperiment, runAgentProfileImprovementExperiment, runCandidateExperiment, sealAgentProfileImprovementExperiment, sealAgentProfileImprovementSuite, sealAgentProfileImprovementTask, sealCandidateExperiment, verifyAgentProfileImprovementExperimentComparison, verifyCandidateExperiment, verifyCandidateExperimentComparison } from "@tangle-network/agent-eval/contract";
 //#region src/intelligence/delivery.ts
 const defaultPlaneBaseUrl = "https://intelligence.tangle.tools";
 const defaultRefreshMs = 3e5;
 const defaultPlaneRequestTimeoutMs = 1e4;
-const maxPlaneErrorTextLength = 200;
 /** Resolve the ONE Intelligence base URL — the single knob both the send and
 *  receive paths derive from. Env fallback: `TANGLE_INTELLIGENCE_URL`. */
 function resolveIntelligenceBaseUrl(baseUrl) {
@@ -65,9 +65,6 @@ async function requestPlane(input) {
 function asRecord(value) {
 	return value && typeof value === "object" ? value : {};
 }
-function capPlaneErrorText(value) {
-	return value.slice(0, maxPlaneErrorTextLength);
-}
 function toDiffProvenance(value) {
 	const p = asRecord(value);
 	return {
@@ -146,76 +143,6 @@ async function pullCertified(opts) {
 		};
 	}
 }
-/**
-* Submit a completed Runtime proposal to Intelligence for product-side review.
-* This never runs an experiment, approves a proposal, or applies a candidate.
-* A 4xx response is a confirmed `rejected` request. Network failures, timeouts,
-* 5xx responses, and invalid success responses are `unconfirmed`, so callers
-* can retry the same digest because Intelligence stores proposals idempotently.
-*/
-async function submitAgentImprovementProposal(opts) {
-	let proposal;
-	try {
-		proposal = verifyAgentImprovementProposal(opts.proposal);
-	} catch (err) {
-		return {
-			succeeded: false,
-			submission: "not-sent",
-			error: `proposal validation failed: ${err instanceof Error ? err.message : String(err)}`
-		};
-	}
-	const request = await requestPlane({
-		...opts,
-		path: "/v1/improvements/proposals",
-		method: "POST",
-		headers: { "content-type": "application/json" },
-		body: JSON.stringify({ proposal })
-	});
-	if (!request.succeeded) return {
-		succeeded: false,
-		submission: request.attempted ? "unconfirmed" : "not-sent",
-		error: request.attempted ? `proposal submission request failed: ${request.error}` : request.error
-	};
-	const res = request.response;
-	if (!res.ok) {
-		const body = await res.text().catch(() => "");
-		let code;
-		let message = capPlaneErrorText(body);
-		try {
-			const parsed = asRecord(JSON.parse(body));
-			if (typeof parsed.error === "string") code = capPlaneErrorText(parsed.error);
-			if (typeof parsed.message === "string") message = capPlaneErrorText(parsed.message);
-		} catch {}
-		return {
-			succeeded: false,
-			submission: res.status >= 400 && res.status < 500 ? "rejected" : "unconfirmed",
-			error: `proposal submission ${res.status}: ${message}`,
-			status: res.status,
-			...code === void 0 ? {} : { code }
-		};
-	}
-	try {
-		const recorded = verifyAgentImprovementProposal(asRecord(await res.json()).proposal);
-		if (recorded.digest !== proposal.digest) return {
-			succeeded: false,
-			submission: "unconfirmed",
-			error: "proposal submission returned a different proposal digest",
-			status: res.status
-		};
-		return {
-			succeeded: true,
-			value: recorded,
-			status: res.status
-		};
-	} catch (err) {
-		return {
-			succeeded: false,
-			submission: "unconfirmed",
-			error: `proposal submission response parse failed: ${capPlaneErrorText(err instanceof Error ? err.message : String(err))}`,
-			status: res.status
-		};
-	}
-}
 /** Artifact-type buckets that fold into the system prompt, in fold order. A
 *  certified `context` capability whose content is free text (`instructions`)
 *  is delivered here so it actually reaches the agent — never bucketed into a
@@ -404,6 +331,70 @@ function normalizeReportedUsage(usage, intelligenceOff = false) {
 	};
 }
 //#endregion
+//#region src/intelligence/profile-improvement-experiment.ts
+function createProfileImprovementCostLedger(budgetUsd, context = "profile improvement") {
+	if (!Number.isFinite(budgetUsd) || budgetUsd < 0) throw new Error(`${context} budgetUsd must be a non-negative finite number`);
+	return new CostLedger({ costCeilingUsd: budgetUsd });
+}
+function profilePolicyWithBudget(policy, budgetUsd, context = "profile improvement") {
+	if (policy.budgetUsd !== void 0 && !numbersApproximatelyEqual(policy.budgetUsd, budgetUsd)) throw new Error(`${context} policy budgetUsd must equal the run budgetUsd`);
+	return {
+		...policy,
+		budgetUsd
+	};
+}
+function profilePreparationAccounting(costLedger, startedAt) {
+	const summary = costLedger.summary();
+	if (!summary.accountingComplete || summary.costProvenance.kind === "uncaptured") throw new Error("profile improvement preparation cost is incomplete");
+	return {
+		wallDurationMs: Math.max(0, performance.now() - startedAt),
+		cost: {
+			usd: summary.costProvenance.usd,
+			provenance: summary.costProvenance.kind
+		}
+	};
+}
+function profileStateDigest$1(stateDigest, identity, profile) {
+	return agentProfileImprovementArmSchema.parse({ stateDigest: stateDigest({
+		identity,
+		profile
+	}) }).stateDigest;
+}
+function sealProfileImprovementBenchmark(input) {
+	const tasks = input.tasks.map((task) => sealAgentProfileImprovementTask(task));
+	return sealAgentProfileImprovementSuite({
+		splitDigest: campaignSplitDigestFromIdentities(tasks.map(profileTaskScenarioIdentity), input.reps),
+		tasks,
+		reps: input.reps,
+		seeds: input.seeds
+	});
+}
+function profileTaskScenarioIdentity(task) {
+	return {
+		id: task.scenario.id,
+		kind: task.scenario.kind,
+		scenarioDigest: task.scenario.digest
+	};
+}
+function profileImprovementMetadata(metadata, source, optimizationReceipt) {
+	assertNoCallerOptimizationReceipt(metadata);
+	if (metadata && Object.hasOwn(metadata, AGENT_IMPROVEMENT_SOURCE_METADATA_KEY)) throw new Error(`candidate metadata reserves '${AGENT_IMPROVEMENT_SOURCE_METADATA_KEY}' for Runtime`);
+	const merged = {
+		...metadata ?? {},
+		...agentImprovementSourceMetadata(source)
+	};
+	return optimizationReceipt ? attachOptimizationActivationReceipt(merged, optimizationReceipt) : immutableCandidateValue(merged);
+}
+function completeImprovementSearchAccounting(analysis, improvement) {
+	if (!improvement.cost.accountingComplete) throw new Error(`agent improvement optimization cost is incomplete: ${improvement.cost.incompleteReasons.join(", ") || "unspecified"}`);
+	if (!Number.isFinite(improvement.cost.totalCostUsd) || improvement.cost.totalCostUsd < 0) throw new Error("agent improvement optimization cost must be finite and non-negative");
+	if (!Number.isFinite(improvement.durationMs) || improvement.durationMs < 0) throw new Error("agent improvement optimization duration must be finite and non-negative");
+	return {
+		searchCostUsd: analysis.costUsd + improvement.cost.totalCostUsd,
+		searchDurationMs: analysis.durationMs + improvement.durationMs
+	};
+}
+//#endregion
 //#region src/intelligence/authored-profile-improvement.ts
 /**
 * Put a complete authored/imported profile through the canonical profile
@@ -686,6 +677,433 @@ function isJsonSchema(v) {
 	return typeof v === "object" && v !== null && !Array.isArray(v);
 }
 //#endregion
+//#region src/intelligence/improvement-cycle.ts
+/** A failed baseline or candidate cell with its complete Runtime failure result. */
+var AgentCandidateExperimentCellExecutionError = class extends Error {
+	finalization;
+	constructor(finalization) {
+		super(`candidate experiment cell failed: ${finalization.reason}`);
+		this.name = "AgentCandidateExperimentCellExecutionError";
+		this.finalization = finalization;
+	}
+};
+function sealAgentImprovementExperiment(material, improvement) {
+	assertRuntimeOwnedExperimentFieldsAbsent(material);
+	const candidateLineage = {
+		source: "optimizer",
+		parentDigests: [material.baseline.digest],
+		runIds: [improvement.lineage.runId],
+		developmentSplitDigest: improvement.lineage.developmentSplitDigest
+	};
+	const experiment = sealCandidateExperiment({
+		...material,
+		candidateLineage
+	});
+	assertCandidateReleaseWorkIsFresh(experiment, improvement);
+	return experiment;
+}
+function assertRuntimeOwnedExperimentFieldsAbsent(material) {
+	if (material === null || typeof material !== "object" || Array.isArray(material)) throw new Error("agent improvement experiment material must be an object");
+	const supplied = ["candidateLineage", "digest"].filter((field) => Object.hasOwn(material, field));
+	if (supplied.length > 0) throw new Error(`agent improvement experiment material must not supply Runtime-owned fields: ${supplied.join(", ")}`);
+}
+/** Execute both arms of one immutable experiment and derive its paired result. */
+async function runAgentCandidateExperiment(options) {
+	const experiment = verifyCandidateExperiment(options.experiment);
+	const preparation = options.preparation ?? {
+		wallDurationMs: 0,
+		cost: {
+			usd: 0,
+			provenance: "observed"
+		}
+	};
+	const costLedger = options.costLedger ?? (experiment.policy.budgetUsd === void 0 ? void 0 : new CostLedger({ costCeilingUsd: experiment.policy.budgetUsd }));
+	const run = await runCandidateExperiment({
+		experiment,
+		...options.maxConcurrency === void 0 ? {} : { maxConcurrency: options.maxConcurrency },
+		...costLedger ? { costLedger } : {},
+		...options.signal ? { signal: options.signal } : {},
+		execute: async (input) => {
+			const placement = await options.placeCell(input);
+			return await executeAgentCandidateExperimentCell({
+				...input,
+				...placement
+			});
+		}
+	});
+	const evaluation = createAgentImprovementMeasuredComparison({
+		experiment,
+		measurements: run.measurements,
+		preparation,
+		measurement: run.measurement,
+		runId: options.runId,
+		...options.candidate ? { candidate: options.candidate } : {},
+		...options.generationsExplored === void 0 ? {} : { generationsExplored: options.generationsExplored },
+		...options.metadata ? { metadata: options.metadata } : {}
+	});
+	return {
+		experiment,
+		measurements: run.measurements,
+		evaluation
+	};
+}
+/** Execute one exact arm, task, repetition, seed, and attempt through Runtime. */
+async function executeAgentCandidateExperimentCell(options) {
+	const experiment = verifyCandidateExperiment(options.experiment);
+	const bundle = experiment[options.arm];
+	assertExactExperimentInput(options, experiment, bundle);
+	const attempt = options.attempt ?? 1;
+	if (attempt > options.task.attempt.maxAttempts) throw new Error("candidate experiment attempt exceeds the signed task policy");
+	const runCell = canonicalCandidateDocument({
+		kind: "agent-candidate-run-cell",
+		experimentDigest: experiment.digest,
+		arm: options.arm,
+		bundleDigest: bundle.digest,
+		suiteDigest: options.benchmarkCell.suiteDigest,
+		taskDigest: options.task.digest,
+		taskIndex: options.benchmarkCell.taskIndex,
+		repetition: options.benchmarkCell.repetition,
+		seed: options.seed,
+		attempt
+	}).value;
+	const verified = await verifyAgentCandidateBundle(bundle, options.ports);
+	const prepared = await prepareAgentCandidateExecution(verified, {
+		executionId: options.executionId,
+		runCell,
+		benchmarkSuite: experiment.benchmark.suite,
+		task: options.task,
+		executionRoots: options.executionRoots,
+		stagingRoots: options.stagingRoots
+	}, options.ports, options.preparation);
+	const finalization = await executePreparedAgentCandidate(prepared, options.execution);
+	if (!finalization.succeeded) throw new AgentCandidateExperimentCellExecutionError(finalization);
+	const evidence = canonicalCandidateDocument({
+		kind: "agent-candidate-execution-evidence",
+		materializationReceipt: prepared.materializationReceipt.value,
+		receipt: finalization.receipt.value
+	}).value;
+	return verifyCandidateExecutionEvidence(evidence, {
+		experiment,
+		arm: options.arm,
+		benchmarkCell: options.benchmarkCell,
+		seed: options.seed,
+		attempt,
+		resolvedResources: verifiedResourceTextByDigest(verified)
+	});
+}
+/** Delegate all statistics and promotion checks to agent-eval's receipt-based comparison. */
+function createAgentImprovementMeasuredComparison(options) {
+	return verifyCandidateExperimentComparison(measuredComparisonFromCandidateExperiment(options));
+}
+async function analyzeAgentImprovement(runId, options, costLedger, signal) {
+	assertMeasuredAnalysisOptions(options);
+	const analysis = await runAnalystLoop({
+		...options,
+		runId,
+		...costLedger ? {
+			costLedger,
+			costPhase: "profile-improvement-analysis"
+		} : {},
+		...signal ? { signal } : {}
+	});
+	if (costLedger) assertAnalysisCostRecorded(analysis, costLedger);
+	const judgeDerived = analysis.analystResult.findings.filter((finding) => finding.derived_from_judge === true);
+	if (judgeDerived.length > 0) throw new Error(`agent improvement analysis must not produce judge-derived findings: [${judgeDerived.map((finding) => finding.finding_id).join(", ")}]`);
+	return {
+		analysis,
+		findings: [...assertProposalFindings(analysis.analystResult.findings.map((finding) => ({
+			...finding,
+			proposal_origin: "production"
+		})), "agent improvement findings")]
+	};
+}
+function assertMeasuredAnalysisOptions(options) {
+	const rawOptions = options;
+	if (rawOptions.knowledgeProposalSource !== void 0 || rawOptions.improvementProposalSource !== void 0) throw new Error("measured agent improvement analysis must not run proposal sources");
+	if (rawOptions.onEvent !== void 0 || rawOptions.log !== void 0) throw new Error("measured agent improvement analysis must not run callbacks");
+	if (rawOptions.inputs.judgeInput !== void 0) throw new Error("measured agent improvement analysis must not receive judge input");
+}
+function completeAnalysisAccounting(analysis) {
+	const analysisCost = analysis.analystResult.total_cost_provenance;
+	if (!analysisCost || analysisCost.kind === "uncaptured") throw new Error("agent improvement analysis cost is uncaptured");
+	if (!Number.isFinite(analysis.analystResult.total_cost_usd) || analysis.analystResult.total_cost_usd < 0) throw new Error("agent improvement analysis cost must be finite and non-negative");
+	if (analysisCost.usd !== analysis.analystResult.total_cost_usd) throw new Error("agent improvement analysis cost does not match its provenance");
+	if (!Number.isFinite(analysis.durationMs) || analysis.durationMs < 0) throw new Error("agent improvement analysis duration must be finite and non-negative");
+	return {
+		costUsd: analysis.analystResult.total_cost_usd,
+		durationMs: analysis.durationMs
+	};
+}
+function assertAnalysisCostRecorded(analysis, costLedger) {
+	const reported = completeAnalysisAccounting(analysis);
+	const summary = costLedger.summary();
+	if (!summary.accountingComplete || summary.costProvenance.kind === "uncaptured") throw new Error("agent improvement analysis cost is incomplete in the shared account");
+	const analysisCost = analysis.analystResult.total_cost_provenance;
+	if (!analysisCost || analysisCost.kind === "uncaptured") throw new Error("agent improvement analysis cost is uncaptured");
+	if (!numbersApproximatelyEqual(summary.totalCostUsd, reported.costUsd) || summary.costProvenance.kind !== analysisCost.kind) throw new Error("agent improvement analysis cost does not match the shared account");
+}
+function assertReleaseSplitIsFresh(heldOutSplitDigest, improvement) {
+	const consumedSplits = [improvement.lineage.developmentSplitDigest];
+	if (improvement.mode === "method") {
+		const finalTestSplitDigest = improvement.lineage.finalTestSplitDigest;
+		if (!finalTestSplitDigest) throw new Error("method improvement does not retain its final-test split digest");
+		consumedSplits.push(finalTestSplitDigest);
+	}
+	if (consumedSplits.includes(heldOutSplitDigest)) throw new Error("release benchmark reuses an optimizer development or final-test split");
+}
+function assertReleaseScenariosAreFresh(improvement, heldOutScenarios) {
+	const optimizerScenarios = /* @__PURE__ */ new Map();
+	for (const [partition, scenarios] of [
+		["train", improvement.lineage.scenarioPartitions.train],
+		["selection", improvement.lineage.scenarioPartitions.selection],
+		["final-test", improvement.lineage.scenarioPartitions.finalTest]
+	]) for (const scenario of scenarios) optimizerScenarios.set(canonicalCandidateDigest$1(scenario), partition);
+	const reused = heldOutScenarios.filter((scenario) => optimizerScenarios.has(canonicalCandidateDigest$1(scenario))).map((scenario) => `${scenario.id} (${optimizerScenarios.get(canonicalCandidateDigest$1(scenario))})`);
+	if (reused.length > 0) throw new Error(`release benchmark reuses optimizer scenario(s): [${reused.join(", ")}]`);
+}
+function assertCandidateReleaseWorkIsFresh(experiment, improvement) {
+	for (const splitDigest of new Set(experiment.benchmark.tasks.map((task) => task.benchmark.splitDigest))) assertReleaseSplitIsFresh(splitDigest, improvement);
+	if (improvement.mode !== "method") return;
+	assertReleaseScenariosAreFresh(improvement, experiment.benchmark.tasks.map((task) => task.scenario));
+}
+function assertProfileReleaseWorkIsFresh(benchmark, improvement) {
+	assertReleaseSplitIsFresh(benchmark.suite.splitDigest, improvement);
+	assertReleaseScenariosAreFresh(improvement, benchmark.tasks.map(profileTaskScenarioIdentity));
+}
+/**
+* Analyze a product-owned profile, search one profile surface, then run the
+* exact baseline and candidate through the product executor before proposing.
+*/
+async function proposeAgentProfileImprovement(options) {
+	const source = agentImprovementSourceSchema.parse(options.source);
+	if (!isAgentProfileMeasuredSurface(options.improvement.surface ?? "prompt")) throw new Error("measured profile improvement supports profile surfaces or a complete agent profile; use the sealed-candidate path for this surface");
+	assertMeasuredAnalysisOptions(options.analysis);
+	const inputFindings = assertProposalFindings(options.improvement.findings ?? [], "profile improvement input findings");
+	const costLedger = createProfileImprovementCostLedger(options.budgetUsd);
+	const preparationStartedAt = performance.now();
+	const profile = parseExactAgentProfile(options.profile, "profile improvement source");
+	const baselineStateDigest = profileStateDigest$1(options.stateDigest, source.sourceIdentity, profile);
+	if (baselineStateDigest !== source.sourceDigest) throw new Error("profile improvement source digest does not match the measured profile state");
+	const policy = profilePolicyWithBudget(options.benchmark.policy, options.budgetUsd);
+	const benchmark = sealProfileImprovementBenchmark({
+		...options.benchmark,
+		policy
+	});
+	const heldOutDigests = new Set(benchmark.tasks.map((task) => task.scenario.digest));
+	assertProfileTrainingIsHeldOut(profile, heldOutDigests);
+	if (options.improvement.costCeiling !== void 0 && !numbersApproximatelyEqual(options.improvement.costCeiling, options.budgetUsd)) throw new Error("profile improvement costCeiling must equal the run budgetUsd");
+	const { analysis, findings } = await analyzeAgentImprovement(options.runId, options.analysis, costLedger, options.signal);
+	const proposalFindings = immutableCandidateValue([...inputFindings, ...findings]);
+	const improvement = await improve(profile, {
+		...options.improvement,
+		executionRef: options.executor.executionRef.digest,
+		agent: options.executor.optimize,
+		costLedger,
+		costCeiling: options.budgetUsd,
+		findings: proposalFindings
+	});
+	try {
+		if (improvement.decision !== "ship") throw new Error("agent profile improvement search did not produce a promotable candidate");
+		const candidateProfile = parseExactAgentProfile(improvement.candidate.profile, "profile improvement candidate");
+		const candidateStateDigest = profileStateDigest$1(options.stateDigest, source.sourceIdentity, candidateProfile);
+		if (candidateStateDigest === baselineStateDigest) throw new Error("profile improvement candidate state digest matches the baseline");
+		const change = agentImprovementProfileDiffs(profile, candidateProfile, {
+			id: `profile-improvement:${candidateStateDigest}`,
+			metadata: {
+				sourceIdentity: source.sourceIdentity,
+				sourceRevision: source.sourceRevision
+			}
+		});
+		const profileDiffIds = change.map((step) => {
+			if (!step.id) throw new Error("profile improvement change requires an exact diff id");
+			return step.id;
+		});
+		assertProfileTrainingIsHeldOut(candidateProfile, heldOutDigests);
+		assertProfileReleaseWorkIsFresh(benchmark, improvement);
+		const experiment = sealAgentProfileImprovementExperiment({
+			kind: "agent-profile-improvement-experiment",
+			digestAlgorithm: "rfc8785-sha256",
+			source,
+			executionRef: options.executor.executionRef,
+			baseline: { stateDigest: baselineStateDigest },
+			candidate: { stateDigest: candidateStateDigest },
+			change,
+			candidateLineage: {
+				source: "optimizer",
+				parentDigests: [source.sourceDigest],
+				runIds: [improvement.lineage.runId],
+				profileDiffIds,
+				developmentSplitDigest: improvement.lineage.developmentSplitDigest
+			},
+			benchmark,
+			policy
+		});
+		const profilesByStateDigest = /* @__PURE__ */ new Map([[baselineStateDigest, profile], [candidateStateDigest, candidateProfile]]);
+		const preparation = profilePreparationAccounting(costLedger, preparationStartedAt);
+		const run = await runAgentProfileImprovementExperiment({
+			experiment,
+			...options.maxConcurrency === void 0 ? {} : { maxConcurrency: options.maxConcurrency },
+			costLedger,
+			...options.signal ? { signal: options.signal } : {},
+			execute: async (input) => {
+				const measuredProfile = profilesByStateDigest.get(input.stateDigest);
+				if (!measuredProfile) throw new Error("profile improvement execution requested an unknown profile state");
+				return options.executor.measure({
+					...input,
+					profile: measuredProfile
+				});
+			}
+		});
+		const optimizationReceipt = createOptimizationActivationReceipt(improvement);
+		const evaluation = verifyAgentProfileImprovementExperimentComparison(measuredComparisonFromAgentProfileImprovementExperiment({
+			experiment,
+			measurements: run.measurements,
+			runId: options.runId,
+			...options.candidate ? { candidate: options.candidate } : {},
+			generationsExplored: improvement.generationsExplored ?? 0,
+			preparation,
+			measurement: run.measurement,
+			metadata: profileImprovementMetadata(options.metadata, source, optimizationReceipt)
+		}));
+		const proposal = createAgentImprovementProposal({
+			runId: options.runId,
+			findings: proposalFindings,
+			evaluation,
+			...options.now ? { now: options.now } : {}
+		});
+		return {
+			analysis,
+			improvement,
+			experiment,
+			measurements: run.measurements,
+			proposal
+		};
+	} catch (cause) {
+		return rethrowAfterCleanup(cause, () => improvement.dispose(), "proposeAgentProfileImprovement failed");
+	}
+}
+/** Analyze, search, then remeasure the resulting exact candidate before proposing it. */
+async function proposeAgentImprovement(options) {
+	assertNoCallerOptimizationReceipt(options.metadata);
+	assertMeasuredAnalysisOptions(options.analysis);
+	const inputFindings = assertProposalFindings(options.improvement.findings ?? [], "agent improvement input findings");
+	const { analysis, findings } = await analyzeAgentImprovement(options.runId, options.analysis);
+	const analysisAccounting = completeAnalysisAccounting(analysis);
+	const proposalFindings = immutableCandidateValue([...inputFindings, ...findings]);
+	const improvementInput = {
+		...options.improvement,
+		findings: proposalFindings
+	};
+	const improvement = improvementInput.surface === "code" ? await improve(improvementInput) : await improve(options.profile, improvementInput);
+	try {
+		if (improvement.decision !== "ship") throw new Error("agent improvement search did not produce a promotable candidate");
+		const searchAccounting = completeImprovementSearchAccounting(analysisAccounting, improvement);
+		const preparation = {
+			wallDurationMs: searchAccounting.searchDurationMs,
+			cost: {
+				usd: searchAccounting.searchCostUsd,
+				provenance: "estimated"
+			}
+		};
+		const optimizationReceipt = improvement.mode === "method" ? createOptimizationActivationReceipt(improvement) : void 0;
+		const experiment = sealAgentImprovementExperiment(await options.buildExperiment({
+			analysis,
+			improvement
+		}), improvement);
+		assertCandidateProfileBinding(options.profile, experiment.baseline.profile);
+		assertImprovementCandidateBinding(improvement, experiment);
+		const measured = await runAgentCandidateExperiment({
+			experiment,
+			runId: options.runId,
+			placeCell: options.placeCell,
+			...options.maxConcurrency === void 0 ? {} : { maxConcurrency: options.maxConcurrency },
+			...options.signal ? { signal: options.signal } : {},
+			...options.candidate ? { candidate: options.candidate } : {},
+			...optimizationReceipt ? { metadata: attachOptimizationActivationReceipt(options.metadata, optimizationReceipt) } : options.metadata ? { metadata: options.metadata } : {},
+			...improvement.generationsExplored === void 0 ? {} : { generationsExplored: improvement.generationsExplored },
+			preparation
+		});
+		const proposal = createAgentImprovementProposal({
+			runId: options.runId,
+			findings: proposalFindings,
+			evaluation: measured.evaluation,
+			...options.now ? { now: options.now } : {}
+		});
+		return {
+			analysis,
+			improvement,
+			experiment,
+			measurements: measured.measurements,
+			proposal
+		};
+	} catch (cause) {
+		return rethrowAfterCleanup(cause, () => improvement.dispose(), "proposeAgentImprovement failed");
+	}
+}
+function assertImprovementCandidateBinding(improvement, experiment) {
+	const candidate = improvement.candidate;
+	if (candidate.surface !== "code") {
+		try {
+			assertCandidateProfileBinding(candidate.profile, experiment.candidate.profile);
+		} catch (cause) {
+			throw new Error("candidate experiment does not contain the improvement winner", { cause });
+		}
+		return;
+	}
+	const surface = candidate.value;
+	const code = experiment.candidate.code;
+	if (typeof surface !== "object" || surface === null || surface.kind !== "code" || code.kind !== "git-patch" || code.baseCommit !== surface.baseCommit || code.baseTree !== surface.baseTree || code.candidateTree !== surface.candidateTree || code.patch.artifact.sha256 !== surface.patch.sha256 || code.patch.artifact.byteLength !== surface.patch.byteLength) throw new Error("candidate experiment does not contain the improvement winner");
+	if (canonicalCandidateDigest$1(experiment.baseline.profile) !== canonicalCandidateDigest$1(experiment.candidate.profile)) throw new Error("code improvement candidate changed the agent profile");
+}
+/** Recheck one Runtime receipt against its exact signed experiment cell. */
+function verifyCandidateExecutionEvidence(input, options) {
+	const experiment = verifyCandidateExperiment(options.experiment);
+	const bundle = experiment[options.arm];
+	const task = experiment.benchmark.tasks[options.benchmarkCell.taskIndex];
+	const index = options.benchmarkCell.taskIndex * experiment.benchmark.suite.reps + options.benchmarkCell.repetition;
+	if (!task || options.benchmarkCell.suiteDigest !== experiment.benchmark.suite.digest || options.seed !== experiment.benchmark.suite.seeds[index]) throw new Error("candidate execution evidence points outside its signed experiment");
+	const evidence = verifyCanonicalCandidateDocument(candidateExecutionEvidenceSchema.parse(input), "candidate execution evidence");
+	const materialization = verifyCanonicalCandidateDocument(agentCandidateMaterializationReceiptSchema.parse(evidence.materializationReceipt), "candidate materialization receipt");
+	const receipt = verifyCanonicalCandidateDocument(agentCandidateRunReceiptSchema.parse(evidence.receipt), "candidate run receipt");
+	const plan = materialization.executionPlan;
+	const cell = plan.material.runCell;
+	const attempt = options.attempt ?? 1;
+	if (cell.experimentDigest !== experiment.digest || cell.arm !== options.arm || cell.bundleDigest !== bundle.digest || cell.suiteDigest !== experiment.benchmark.suite.digest || cell.taskDigest !== task.digest || cell.taskIndex !== options.benchmarkCell.taskIndex || cell.repetition !== options.benchmarkCell.repetition || cell.seed !== options.seed || cell.attempt !== attempt || canonicalCandidateDigest$1(omitTopLevelDigest(cell)) !== cell.digest) throw new Error("candidate execution receipt substituted its signed experiment cell");
+	assertCapturedInput(materialization.benchmark.suite, experiment.benchmark.suite, "benchmark suite");
+	assertCapturedInput(materialization.benchmark.task, task, "benchmark task");
+	assertEvidenceMaterialDigest(plan, "candidate execution plan");
+	assertEvidenceMaterialDigest(materialization.profileActivation.profilePlan, "candidate profile plan");
+	const expectedProfilePlan = materializeAgentCandidateProfilePlan({
+		profile: bundle.profile,
+		harness: bundle.execution.harness,
+		launch: bundle.execution.launch,
+		workspace: bundle.execution.cwd.workspace,
+		workspaces: plan.material.workspaces,
+		resolvedResources: options.resolvedResources
+	});
+	const activation = parseAgentCandidateProfileActivation(materialization.profileActivation, materialization.profileActivation.profilePlan.digest);
+	const regeneratedActivation = createAgentCandidateProfileActivation(expectedProfilePlan, materialization.profileActivation.profilePlan);
+	if (activation.digest !== regeneratedActivation.digest) throw new Error("candidate profile activation does not match the experiment bundle");
+	if (materialization.bundleDigest !== bundle.digest || receipt.bundleDigest !== bundle.digest || receipt.runCellDigest !== cell.digest || receipt.materializationReceiptDigest !== materialization.digest || receipt.executionPlanDigest !== plan.digest) throw new Error("candidate execution evidence does not bind one exact Runtime run");
+	assertEvidenceMaterialDigest(receipt.modelSettlement, "candidate model settlement");
+	assertEvidenceMaterialDigest(receipt.taskOutcome, "candidate task outcome");
+	assertEvidenceMaterialDigest(receipt.benchmarkResult, "candidate benchmark result");
+	return immutableCandidateValue(evidence);
+}
+function assertExactExperimentInput(input, experiment, bundle) {
+	const task = experiment.benchmark.tasks[input.benchmarkCell.taskIndex];
+	const index = input.benchmarkCell.taskIndex * experiment.benchmark.suite.reps + input.benchmarkCell.repetition;
+	if (input.experiment.digest !== experiment.digest || input.bundle.digest !== bundle.digest || !task || input.task.digest !== task.digest || input.benchmarkCell.suiteDigest !== experiment.benchmark.suite.digest || input.seed !== experiment.benchmark.suite.seeds[index]) throw new Error("Runtime received a substituted candidate experiment cell");
+}
+function assertCapturedInput(captured, expected, label) {
+	const bytes = canonicalCandidateBytes$1(omitTopLevelDigest(expected));
+	if (captured.digest !== expected.digest || captured.material.sha256 !== expected.digest || captured.material.byteLength !== bytes.byteLength) throw new Error(`candidate materialization substituted its ${label}`);
+}
+function assertEvidenceMaterialDigest(evidence, label) {
+	const bytes = canonicalCandidateBytes$1(evidence.material);
+	if (canonicalCandidateDigest$1(evidence.material) !== evidence.digest || evidence.artifact.sha256 !== evidence.digest || evidence.artifact.byteLength !== bytes.byteLength) throw new Error(`${label} digest does not match its canonical material`);
+}
+//#endregion
 //#region src/intelligence/exact-process-candidate.ts
 /** Candidate surfaces implemented by the neutral exact-process executor. */
 const exactProcessCandidateExperimentExecutionSupport = Object.freeze({
@@ -1104,9 +1522,9 @@ function withIntelligence(agent, config) {
 * Tangle Intelligence SDK — trace capture plus reviewable improvement.
 *
 * The client keeps live-agent trace delivery best-effort. The separate
-* improvement-cycle exports analyze completed traces, run a signed baseline
-* versus candidate experiment, bind review to its result, and activate only
-* the exact measured candidate.
+* improvement-cycle exports analyze completed traces and run a signed baseline
+* versus candidate experiment. Activation exports bind review to its result
+* and activate only the exact measured candidate.
 *
 *   1. OBSERVE — wrap a generic agent and export one trace span per call to
 *      Tangle Intelligence, swallowing every export failure so a live agent
@@ -1398,6 +1816,6 @@ function withMissingAttributes(span, attributes) {
 	};
 }
 //#endregion
-export { AGENT_IMPROVEMENT_PROFILE_SURFACES, AGENT_PROFILE_MEASURED_SURFACES, AgentCandidateExperimentCellExecutionError, CapabilityNotAdmittedError, agentImprovementProfileDiffs, agentImprovementProfileSurfaceDigest, agentImprovementProfileSurfaceInput, agentImprovementTargetProfileDiffs, buildAgentImprovementActivationTargets, compileEffort, composeCertifiedPrompt, createAgentImprovementActivation, createAgentImprovementActivationResult, createAgentImprovementMeasuredComparison, createAgentImprovementProposal, createCertifiedPromptSource, createExactProcessCandidateExperimentExecutor, createIntelligenceClient, createOptimizationActivationReceipt, createProtectedExactProcessCandidateExperimentExecutor, defaultEffortTier, defaultRedactor, exactProcessCandidateExperimentExecutionSupport, executeAgentCandidateExperimentCell, executeAgentImprovementActivation, isAgentImprovementProfileSurface, isAgentProfileMeasuredSurface, isIntelligenceOff, manifestFromProfile, normalizeCertifiedProfile, optimizationActivationReceiptFromMetadata, parseAgentCandidateProfileActivation as parseCandidateProfileMaterialization, prepareAgentImprovementProfileActivation, proposeAgentImprovement, proposeAgentProfileImprovement, proposeAuthoredAgentProfileImprovement, pullCertified, resolveEffort, resolveIntelligenceBaseUrl, resolveRedactor, reviewAgentImprovementProposal, runAgentCandidateExperiment, submitAgentImprovementProposal, verifyAgentImprovementActivation, verifyAgentImprovementActivationResult, verifyAgentImprovementProposal, verifyAgentImprovementReview, verifyCandidateExecutionEvidence, withIntelligence };
+export { CapabilityNotAdmittedError, agentImprovementProfileDiffs, agentImprovementProfileSurfaceDigest, agentImprovementProfileSurfaceInput, agentImprovementTargetProfileDiffs, compileEffort, composeCertifiedPrompt, createAgentImprovementActivation, createAgentImprovementActivationResult, createAgentImprovementProposal, createCertifiedPromptSource, createExactProcessCandidateExperimentExecutor, createIntelligenceClient, createOptimizationActivationReceipt, createProtectedExactProcessCandidateExperimentExecutor, defaultRedactor, exactProcessCandidateExperimentExecutionSupport, executeAgentCandidateExperimentCell, executeAgentImprovementActivation, isAgentImprovementProfileSurface, isAgentProfileMeasuredSurface, isIntelligenceOff, manifestFromProfile, optimizationActivationReceiptFromMetadata, parseAgentCandidateProfileActivation as parseCandidateProfileMaterialization, prepareAgentImprovementProfileActivation, proposeAgentImprovement, proposeAgentProfileImprovement, proposeAuthoredAgentProfileImprovement, pullCertified, resolveEffort, reviewAgentImprovementProposal, runAgentCandidateExperiment, verifyAgentImprovementActivation, verifyAgentImprovementActivationResult, verifyAgentImprovementProposal, verifyAgentImprovementReview, verifyCandidateExecutionEvidence, withIntelligence };
 
 //# sourceMappingURL=intelligence.js.map